# Context: cp1-alz-discovery-orchestrator-agent For coding agents working in this folder. Human documentation is in `docs/`; don't duplicate it here. ## What this agent is The ALZ-F01 Discovery workflow as one KAB agent (runtime `agent-runtime-adk` 0.35.7) with eight sub-agents, one per ADO story. Built from the platform's `subagent-pattern` (the declarative shape plus `sub_agents:`). Every change to the story requirements is recorded in `docs/adr/` (0001–0011). ## Story → implementation map | ADO | Story | Sub-agent | Phase | Prompt | Rules it calls (`app/rules.py`) | Stored as | |---|---|---|---|---|---|---| | 3214451 | ALZ-DSC-01 Discovery Planner | `dsc_01_planner` | plan | `prompts/dsc_01_planner.md` | — (`check_plan` runs on its output) | `plan/task-graph` | | 3214452 | ALZ-DSC-02 Estate Scan Executor | `dsc_02_scan_executor` | collect | `prompts/dsc_02_scan_executor.md` | — | `collect/findings-` | | 3214453 | ALZ-DSC-03 Asset Inventory Normalisation | `dsc_03_inventory` | analyse | `prompts/dsc_03_inventory.md` | `match_score`, `record_confidence` | `analyse/inventory` | | 3214454 | ALZ-DSC-04 CMDB & ITSM Reconciliation | `dsc_04_cmdb_reconciliation` | analyse | `prompts/dsc_04_cmdb_reconciliation.md` | `ghost_action` | `analyse/drift-report` | | 3214455 | ALZ-DSC-05 Data Classification | `dsc_05_data_classification` | analyse | `prompts/dsc_05_data_classification.md` | `roll_up_store` | `analyse/data-classification` | | 3214456 | ALZ-DSC-06 Dependency Mapping | `dsc_06_dependency_mapping` | analyse | `prompts/dsc_06_dependency_mapping.md` | `score_edge`, `node_metrics` | `analyse/dependency-graph` | | 3214457 | ALZ-DSC-07 Network Discovery & Assessment | `dsc_07_network` | analyse | `prompts/dsc_07_network.md` | `find_overlaps`, `bottleneck_severity` | `analyse/network` | | 3214458 | ALZ-DSC-08 Discovery Critic | `dsc_08_critic` | critique | `prompts/dsc_08_critic.md` | `coverage_check` | `critique/critic-verdict` | The source of each prompt is the story's v1.1 Comprehensive Prompt (engineering hub workspace: `drafts/cp1/agentic-landing-zone/stories/F01-discovery/ALZ-DSC-0N-Comprehensive-Prompt.md`), with the `alz-run` tools and the agent's own MCP calls removed (ADRs 0002, 0003). ## Files | File | Responsibility | |---|---| | `agent.yaml` | Identity, skills, contract, `functions:`, `mcp:` (9 logical servers, read-only tools), `sub_agents:` (all `as_tool: false`), hooks | | `prompt.md` | Orchestrator instructions and the L0 charter | | `skills/discovery-/SKILL.md` | The steps of each phase: which MCP calls, which records, which `delegate` calls | | `app/artifacts.py` | Plan-phase import of `source_documents` / `artifacts` into `plan/source-documents`, `plan/artifact-NN` (content) and `plan/artifact-NN-provenance` (id, type, path, sha256 -- never sent to a sub-agent) | | `app/workspace.py` | Run store: write-once records, hash-chained `manifest.jsonl`, `bind_run`/`current_run` (a contextvar set in `pre_process`) | | `app/tools.py` | `workspace_put/get/list`; `delegate` (phase allow-list `PHASE_SUB_AGENTS`, forced critic inputs, stores replies, records failures as `failed-*`) | | `app/rules.py` | Deterministic rules; `_plan_issues` is shared by `check_plan` and `post_process` | | `app/business_logic.py` | `before_model` names the run and phase; `pre_process` infers the phase from `outcome-*` records, checks the chain and prerequisites, and may answer with `Reply`; `post_process` rebuilds the reply, enforces the verdict and writes the phase's `outcome-*` | | `schemas/` | Contract; `phase` is optional | | `kubernetes/` | Kyndryl CI placeholders, the same as cp4-agents; filled only in `../../../build/` by `../../../scripts/render_k8s.py` | ## Invariants: don't break these 1. **Records are write-once.** Never add an overwrite path to `workspace.put`. 2. **The run comes from the request** (via `bind_run`), never from a model's tool arguments. 3. **`post_process` decides** `status`, `artifacts`, `verdict`, `next_phase` and `manifest_head` from the workspace. Don't trust the model's values for these. 4. **The critic's inputs are every record in the run.** A critique without a parseable critic record is `failed`; a critique with any reason is not `completed`. 5. **Sub-agents get no MCP tools** (the runtime refuses them). Data reaches them through records and `workspace_get`. 6. **No keys in any file.** `scripts/check_agents.py` scans for them. 7. **Artifacts enter only through the orchestrator** (ADR 0012): sub-agents get content records, never artifact ids, paths or `-provenance` records. 8. **Every requirement change gets an ADR** in `docs/adr/`, and a matching step in `.agents/PLAN.md`. ## Runtime facts relied on (agent-runtime-adk 0.35.7) - **Sub-agent keys:** `name`, `description`, `prompt`, `functions`, `as_tool`. No `mcp`, no skills. - **`ask_sub_agent(name, request)`** runs outside the request's model-call budget and raises `SubAgentFailed`. Hooks run on sub-agent model calls, with `call.agent` set to the sub-agent's name. - **`pre_process` may return `Reply(text)`** to answer without a model call. `post_process` runs before the output contract check. - **A content rule** (data is never instructions) is appended to every prompt by the runtime. ## Verify a change ```sh python3 ../../../scripts/check_agents.py --runtime-image cruciblecoredevacr.azurecr.io/kab/agent-runtime-adk:0.35.7 . python3 ../scripts/dry_run.py . "$(mktemp -d)" python3 ../scripts/build_workflow.py && git diff --exit-code ../workflows/ # after any schemas/ change ```