Add CP1 Discovery agents in both patterns
All checks were successful
check agents / check (push) Successful in 10s

ALZ-F01 Discovery as a sub-agent orchestrator (sub-agents/) and as eight
individual declarative agents (individual-agents/), with their KAB workflow
exports. Shared check, render and import scripts, the alz-discovery-sample
MCP server, the crucible-kab-dev deploy profile, deployment docs, platform
issue reports and the source material. Agent steps time out at 20 minutes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-10-29 18:25:57 +00:00
commit 416c66ced4
331 changed files with 33561 additions and 0 deletions

View File

@@ -0,0 +1,22 @@
# 0001. One orchestrator agent per workflow, with the story agents as sub-agents
| | |
|---|---|
| Status | Accepted |
| Date | 2026-10-29 |
| Decided by | Product owner (CP1) |
| Requirements changed | ALZ-F01 (3214441) execution model; ALZ-DSC-01…08 (3214451–3214458): "each agent is a separately deployed agent that calls MCP tools itself; there is no orchestrator" |
## Context
The v1.1 stories describe eight agents that each run alone and hand work to each other through `alz-run` MCP tools. On the platform, a sub-agent sees only the request written for it, and nothing outside a single request is remembered. The stories need shared context, sessions and memory across the eight agents, and nothing in the platform provides them.
## Decision
One agent per workflow, `cp1-alz-discovery-orchestrator-agent` for Discovery, built from the platform's `subagent-pattern`. The eight story agents become its sub-agents, one per story (`dsc_01_planner` … `dsc_08_critic`). The orchestrator holds the run's data (see ADR 0002) and the other six Features will follow the same shape.
## Consequences
- **One deployment** to build, release and evaluate. A change to one sub-agent's prompt redeploys all of Discovery.
- **One identity on the MCP gateway,** so per-agent MCP allowlists become a single per-tool allowlist (ADR 0003).
- **The stories still map one to one** onto sub-agents, so the board structure doesn't change.

View File

@@ -0,0 +1,22 @@
# 0002. Hand-offs go through a run workspace; the alz-run tools are removed
| | |
|---|---|
| Status | Accepted |
| Date | 2026-10-29 |
| Decided by | Product owner (CP1), decision D1 |
| Requirements changed | Every DSC story's Tool Definitions: `alz-run.get_outputs`, `submit_output`, `submit_verdict`, `checkpoint`. DSC-03 `alz-inventory.write_inventory`, DSC-05 `alz-classification.tag_pii`, DSC-06 `alz-dependency.graph` |
## Context
The `alz-run` tools were invented for the "no orchestrator" design and don't exist on the platform. The MCP write tools stored outputs in platform stores that don't exist either.
## Decision
The orchestrator keeps a run workspace (`app/workspace.py`) of write-once records with a hash-chained manifest. Every MCP result and every sub-agent reply is a record. `delegate` replaces `get_outputs`/`submit_output`, the phase reply replaces `submit_verdict`, and the runtime's loop limits replace `checkpoint`. The write tools are dropped, because their output is a record.
## Consequences
- **Server-side checks become code checks:** the schema check moves to the agent's contract, and the out-of-scope id check moves to `check_plan`, the collect phase's check and the critic.
- **Halting:** a halt is the runtime's guard rails plus charter rule 7, with no checkpoint record.
- **Records can't be changed once written,** and editing one outside the agent fails the next phase.

View File

@@ -0,0 +1,22 @@
# 0003. The orchestrator makes every MCP call
| | |
|---|---|
| Status | Accepted |
| Date | 2026-10-29 |
| Decided by | Forced by the platform runtime (0.35.7); confirmed by the product owner |
| Requirements changed | Every DSC story: "the agent calls its allowlisted MCP tools itself"; the per-agent MCP allowlist rows |
## Context
The runtime builds a sub-agent with its prompt, model and functions only, with no MCP tools and no skills (`spec.py`, `_plain_tools`).
## Decision
The orchestrator declares every read-only MCP tool under `mcp:` and makes the calls the phase skills list. It stores each result unchanged with its `evidence_ref`, and the sub-agents read those records with `workspace_get`.
## Consequences
- **Least privilege is weaker:** one MCP key covers all the tools, where the stories had one per agent.
- **The orchestrator writes raw results,** so it could alter one before storing it. The critic cross-checks findings against the MCP call log (`alz-evidence.get_call_log`), which the orchestrator can't edit.
- **More model calls for the orchestrator:** `AGENT_MAX_ITERATIONS` is raised to 60.

View File

@@ -0,0 +1,22 @@
# 0004. Discovery runs as four phases, one request each
| | |
|---|---|
| Status | Proposed |
| Date | 2026-10-29 |
| Decided by | Built as a default; awaiting product owner confirmation |
| Requirements changed | ALZ-F01 flow (planner → executors → critic as one continuous run) |
## Context
A request is bounded to 25 minutes and a model-call budget, and nothing carries over to the next request. A whole estate doesn't fit in one request. The KAB workflow format passes only workflow inputs and earlier steps' outputs to a step, with no constant per step.
## Decision
Four workflow steps call the same agent: plan, collect, analyse and critique. Each phase reads what earlier phases stored. Step 1 sends no `phase`, and every later step sends the previous step's `next_phase`. With no phase, the agent uses the run's last recorded outcome: a new run is planned, and a failed or halted phase stops the chain. The critique step asks the Engagement Lead to approve.
## Consequences
- **Each phase gets its own budget and its own artifacts**, so provenance is per phase.
- **No scan-batch loop:** the workflow format has none, so collect runs every batch unless a request names one.
- **A failed phase must be rerun by name,** which is deliberate.

View File

@@ -0,0 +1,23 @@
# 0005. Sub-agents are called from code; the critic's verdict is enforced in code
| | |
|---|---|
| Status | Proposed |
| Date | 2026-10-29 |
| Decided by | Built as a default; awaiting product owner confirmation |
| Requirements changed | DSC-08 (3214458): "the platform sets the phase status from the critic's `submit_verdict`"; the residual weakness "critic advisory, not independent" |
## Context
A sub-agent the model calls as a tool can be skipped, and when it fails the runtime tells the model to "continue without it". With one orchestrator, the critic sees only what the orchestrator sends it.
## Decision
- **All sub-agents are `as_tool: false`.** The model calls `delegate`, and `delegate`'s code asks the sub-agent through `ask_sub_agent`. It stores the reply unchanged, with the sub-agent as producer, and records a failure instead of hiding it.
- **The critic's inputs are forced:** it always receives every record in the run.
- **`post_process` recomputes the verdict:** it measures coverage against a fresh read of the scope, and a critic `pass` the code doesn't agree with becomes `fail`. A critique that isn't a pass is never `completed`.
- **The critic runs on its own model** (ADR 0009).
## Consequences
The critic can't be left out or fed a filtered view. Its judgement still depends on its prompt and model, and it is advisory everywhere except coverage.

View File

@@ -0,0 +1,20 @@
# 0006. The scan executor returns one findings record per batch
| | |
|---|---|
| Status | Proposed |
| Date | 2026-10-29 |
| Decided by | Built as a default; awaiting product owner confirmation |
| Requirements changed | DSC-02 (3214452): "one scope entry per call, and one finding submitted per call" |
## Context
One sub-agent call per scope entry would spend the request's time and model budget on hand-offs.
## Decision
The orchestrator still calls `scan_target` once per scope entry, and stores a batch's results in one record. `dsc_02_scan_executor` returns `{"findings": [...]}` with one finding per entry in that record, and the eight-key finding schema is unchanged.
## Consequences
The collect phase's check requires a finding for every planned target in the batch. A missing one makes the phase `completed_with_gaps`.

View File

@@ -0,0 +1,14 @@
# 0007. Agent and sub-agent names
| | |
|---|---|
| Status | Proposed |
| Date | 2026-10-29 |
| Decided by | Built as a default; awaiting product owner confirmation |
| Requirements changed | Agent IDs ALZ-DSC-01…08 as deployable names |
## Decision
- **The agent** is `cp1-alz-discovery-orchestrator-agent`, following the `cp4-*-agent` convention of cp4-agents.
- **Sub-agents** are named `dsc_0N_<role>`, because the runtime requires a Python identifier. That also sets each sub-agent's model variable: `<NAME>_LLM_MODEL`.
- **Story IDs:** prompts and outputs still use the story IDs (ALZ-DSC-0N).

View File

@@ -0,0 +1,20 @@
# 0008. The agent carries app/; the cp1-agents check allows it
| | |
|---|---|
| Status | Accepted |
| Date | 2026-10-29 |
| Decided by | Product owner (CP1) |
| Requirements changed | cp4-agents' folder rule "no app/" (declarative agents only), adopted as the cp1-agents baseline |
## Context
The workspace, `delegate`, the discovery rules and the enforcing hooks are code (ADRs 0002, 0005). The cp4-agents check refuses any `app/`.
## Decision
`scripts/check_agents.py` allows `app/` only when `agent.yaml` declares functions, hooks or sub_agents. The Dockerfile must then copy `app/` and `prompts/`, and each sub-agent's prompt must exist. An agent that declares none of these is still refused an `app/`.
## Consequences
Kyndryl's modernization-agents CI may hold `app/` to the stricter rule. Confirm before raising a pull request there.

View File

@@ -0,0 +1,20 @@
# 0009. Models
| | |
|---|---|
| Status | Proposed |
| Date | 2026-10-29 |
| Decided by | Built as a default; awaiting product owner and platform confirmation |
| Requirements changed | Earlier draft settings `claude-sonnet-4-5` / `gpt-5.4`; DSC-08's note "state if the critic shares a model with any executor" |
## Context
The Azure AI resource behind the gateway deploys `gpt-4o`, `gpt-5.6-sol`, `claude-sonnet-5-5`, `claude-haiku-5-5` and `text-embedding-3-small`. It has no `gpt-5.4` or `claude-sonnet-4-5`. The CP4 agents run on `gpt-5.6-sol`.
## Decision
The agent and seven sub-agents use `gpt-5.6-sol` (temperature 1, max tokens 32000), as the CP4 agents do. The critic uses `claude-sonnet-5-5` (`DSC_08_CRITIC_LLM_MODEL`), a different model family from the agents it judges. Eval cases wait 330 seconds, because `gpt-5.6-sol` is a reasoning model.
## Consequences
Confirm both names on the cluster's LiteLLM gateway before the first run. If `claude-sonnet-5-5` isn't served, the critic's calls fail and the critique phase reports `failed`. Point `DSC_08_CRITIC_LLM_MODEL` at another model the gateway serves. Removing the variable instead would put the critic on the same model as the agents it judges.

View File

@@ -0,0 +1,20 @@
# 0010. Run data and evidence live in execution storage until platform artifacts ship
| | |
|---|---|
| Status | Proposed |
| Date | 2026-10-29 |
| Decided by | Built as a default; awaiting platform team confirmation |
| Requirements changed | Platform rails PR-11 (MCP call log on the evidence chain) and the stories' `alz-evidence` hash-linked evidence chain |
## Context
The platform's artifact subsystem (projects, typed artifacts, contributions, lineage) is designed but not built (PROJECT_WORKFLOW_ARTIFACT_IMPLEMENTATION_PLAN, Release B). Today the executor registers each step's output as an `execution_output` artifact on the shared volume.
## Decision
The workspace writes under `$EXECUTION_STORAGE_ROOT/alz-discovery/<engagement>/<run>/` on `execution-storage-pvc`. Its manifest is hash-chained, and every record names its producer and inputs. When Release B ships, the records map to artifact types and contributions.
## Consequences
The platform team must confirm agent functions may write to the volume, and agree a retention period for client data. The phase outputs still register as platform artifacts through the executor.

View File

@@ -0,0 +1,20 @@
# 0011. Deploy with kustomize from filled-in placeholders; keys stay in Secrets
| | |
|---|---|
| Status | Accepted |
| Date | 2026-10-29 |
| Decided by | Product owner (CP1) |
| Requirements changed | None in the stories; the deploy path differs from cp4-agents, which leaves deployment to Kyndryl's agent CI |
## Decision
- **Placeholders stay:** each `kubernetes/` folder keeps Kyndryl CI's placeholders, as cp4-agents does.
- **`scripts/render_k8s.py`** fills them for a deploy profile (`deploy/crucible-kab-dev.yaml`) into `build/`, ready for `kubectl diff -k` and `kubectl apply -k`.
- **`secretnames.yaml` is left out of the build,** so a deploy can't wipe a Secret created by hand.
- **`namespace.yaml` is left out too.** `agents` and `mcp-servers` are shared with other agents, so the build must neither relabel them nor let `kubectl delete -k` remove them.
- **The MCP server's inline registration-key placeholder is removed,** so that key is read from its Secret.
## Consequences
Keys are created with `kubectl create secret` and never appear in a file in the repository. The cluster has no `agent-platform-connections` ConfigMap, so the profile names the LiteLLM and MCP gateways in the agent's ConfigMap.

View File

@@ -0,0 +1,33 @@
# 0012. Uploads and project artifacts enter only through the orchestrator
| | |
|---|---|
| Status | Accepted |
| Date | 2026-10-29 |
| Decided by | Product owner (CP1) |
| Requirements changed | ALZ-F01 sources: the stories take estate data only from MCP sources (CMDB, scans); client files and earlier outputs were not an input |
## Context
KAB puts files in front of a workflow with two activity steps:
- **Parse Assessment Files** (`parse_assessment_files`): the run form shows an upload field `file`, and the step hands on `parsed_content`.
- **Artifacts** (`select_artifacts`): project artifacts are fixed by id, and the step hands on `artifacts`, records with a `file_path` on the executions volume and inline `content` when small.
Agents can't call the artifact API, because their outbound connections are restricted. Every step's reply is registered as an `execution_output` artifact at the end of a run in a project.
## Decision
- **Only the plan step takes files.** It receives `source_documents` (from `u1.parsed_content`) and `artifacts` (from `a1.artifacts`).
- **`pre_process` imports them in code before any model call** (`app/artifacts.py`):
- `plan/source-documents` and `plan/artifact-NN` hold the content;
- `plan/artifact-NN-provenance` holds the id, type, path and sha256;
- files are read only from inside the executions volume, up to 2 MB each.
- **The model's request then carries only `imported_records`,** the refs.
- **Sub-agents get the content records through `delegate`,** never artifact ids, paths or provenance. The critic's forced inputs exclude provenance and phase-outcome records.
- **`scripts/build_workflow.py` adds the front steps,** and `scripts/kab_import_workflow.py` validates and imports the workflow through `POST /api/workflows/import`.
## Consequences
- **Files are evidence, never scope.** The planner may not add a target from them.
- **An artifact that can't be read is reported** in the plan phase's `issues`, and recorded as `plan/artifact-NN-unreadable`.
- **Outputs stay `execution_output` artifacts.** Typed outputs would need a platform change.

View File

@@ -0,0 +1,30 @@
# Architecture decision records
Each record documents a change to the original requirements for ALZ-F01 Discovery: the ADO Feature
[3214441](https://dev.azure.com/Kyndryl/Global%20Modernization%20Engineering%20Hub%20-%20Agent%20Board/_workitems/edit/3214441)
and its stories 3214451–3214458, as written in the v1.1 story files
(`drafts/cp1/agentic-landing-zone/stories/F01-discovery/` in the engineering hub workspace).
**Status values:**
- **Accepted:** decided by the product owner.
- **Proposed:** built as a default and awaiting confirmation.
- **Superseded:** replaced; the record names the ADR that replaces it.
The ADO items and story files have not been updated to match any of these records yet.
| ADR | Decision | Status |
|---|---|---|
| [0001](0001-orchestrator-with-sub-agents.md) | One orchestrator agent per workflow; the eight story agents are its sub-agents | Accepted |
| [0002](0002-workspace-replaces-alz-run.md) | Hand-offs go through a run workspace; the `alz-run` tools and the MCP write tools are removed | Accepted |
| [0003](0003-orchestrator-makes-mcp-calls.md) | The orchestrator makes every MCP call; sub-agents call none | Accepted |
| [0004](0004-four-phases-one-request-each.md) | Discovery runs as four phases, one request each; the phase can be inferred | Proposed |
| [0005](0005-sub-agents-from-code-and-enforced-verdict.md) | Sub-agents are called from code, and the critic's verdict is enforced in code | Proposed |
| [0006](0006-findings-per-scan-batch.md) | The scan executor returns one findings record per batch | Proposed |
| [0007](0007-names.md) | Agent and sub-agent names | Proposed |
| [0008](0008-app-folder-in-cp1-agents.md) | The agent carries `app/`; the cp1-agents check allows it | Accepted |
| [0009](0009-models.md) | `gpt-5.6-sol` for the agent, `claude-sonnet-5-5` for the critic | Proposed |
| [0010](0010-evidence-in-execution-storage.md) | Run data and evidence live in execution storage until platform artifacts ship | Proposed |
| [0011](0011-kustomize-deploy-secrets-outside-manifests.md) | Deploy with kustomize from filled-in placeholders; keys stay in Secrets | Accepted |
| [0012](0012-artifacts-through-the-orchestrator.md) | Uploads and project artifacts enter only through the orchestrator, as workspace records | Accepted |
New records copy [template.md](template.md) and take the next number.

View File

@@ -0,0 +1,20 @@
# NNNN. Title
| | |
|---|---|
| Status | Proposed |
| Date | YYYY-MM-DD |
| Decided by | |
| Requirements changed | Story / ADO item and the section that no longer holds |
## Context
What is true, and why the original requirement cannot stand as written.
## Decision
What we do instead.
## Consequences
What gets better, what gets worse, and what has to happen next.