# Plan Detail The spec is the full design. Each entry here gives the step's purpose, the rule it must keep, and its acceptance criteria. Paths are current (post iteration 3). ## Step 1: Environment and baseline - **Capability:** A reproducible environment and a recorded test baseline to compare every later step against. - **Rationale:** Later steps claim "the suite stays green"; that needs a starting count. - **Where:** `.venv/`, `requirements.txt`, `requirements-dev.txt`. - **Acceptance criteria:** The existing suite runs and its result is recorded in the spec's comments. ## Step 2: Vendored Skills and provider bundle - **Capability:** Upstream Skills available unmodified, and a Cloud provider expressed as configuration. - **Rationale:** ADR-0002. Upstream changes must arrive as a diff, and a second Cloud provider must be addable without touching the core. - **Where:** `skills/vendor/google/` (pinned to upstream commit `81a31a6`, with `VENDOR.md`, `LICENSE`, `SHA256SUMS`), `scripts/sync-vendored-skills.sh`, `providers/gcp.yaml`, `app/providers.py`, `app/skills/agent_skills.py`. - **Acceptance criteria:** Vendored files match their checksums. Every Skill under `skills/` passes the Agent Skills frontmatter rules. Only `app/providers.py` names a provider. ## Step 3: Deliverables and Ledger - **Capability:** The dependency graph of Deliverables as data, and a pure Ledger that enforces acceptance, Approval and Revision rules. - **Rationale:** ADR-0003. Dependencies are guaranteed by code; ordering is the model's choice. - **Where:** `app/workflows/deliverables.py` (the only place Phases, Deliverables and Dependencies are declared), `app/states/ledger.py`. - **Acceptance criteria:** A Dependency inside a Phase is met on submission; across Phases only on Approval. Reopening a Deliverable returns it and its dependents to draft and withdraws affected Approvals. Revisions are capped. ## Step 4: Execution graph - **Capability:** A checkpointed LangGraph Execution that pauses for the user, behind one `ExecutionEngine` interface. - **Rationale:** ADR-0003. Resumable, recordable progress at every step, with framework types kept out of state. - **Where:** `app/adk/runtime.py` (interface), `app/adk/fake_runtime.py`, `app/states/execution_state.py`, `app/tools/execution.py`, `app/nodes/execution_nodes.py`, `app/workflows/execution_graph.py`, `app/agent.py`, `app/recorder.py`, `app/checkpointing.py`. - **Acceptance criteria:** Only `orchestrator_turn` and `await_user` change the Ledger. No Approval is ever granted from free text. Cloud-read tools are unreachable without permission. All of it is tested with the fake runtime and no model. ## Step 5: ADK runtime and role files - **Capability:** Real ADK `LlmAgent`s running role files with scoped Skills, behind the runtime interface. - **Rationale:** ADR-0003. Each agent runs its own ReAct loop; Skills load on demand through `SkillToolset`. - **Where:** `app/adk/adk_runtime.py` (the only module that imports `google.adk`), `app/adk/roles.py`, `agents/*.md`, `agents/partials/specialist-protocol.md`, `app/tools/pillars.py`. - **Acceptance criteria:** Role files carry no Skill, MCP server or model names; the bundle supplies them. `run_skill_script` is never offered. Each pillar advisor loads only its own pillar Skill. ## Step 6: Tools and remote MCP servers - **Capability:** Local check tools and the Cloud provider's hosted MCP servers, exposed through reviewed read-only allowlists. - **Rationale:** ADR-0002. No hand-written cloud API clients; reading a user's cloud needs their permission. - **Where:** `app/tools/local.py`, `app/tools/mcp.py`, `app/tools/toolkit.py`, `providers/gcp.yaml` (`mcp_servers`, `role_mcp_servers`), `skills/cloud-discovery/`, `skills/iac-validation/`, `docs/operations/mcp-access.md`, `providers/reviews/gcp-mcp-tools.json`. - **Acceptance criteria:** Only allowlisted tools are exposed. No tool can apply, deploy or run a script. An unavailable server becomes a recorded discovery gap, not a failure. ## Step 7: Interfaces - **Capability:** Interactive Executions over A2A, and a pre-approved one-shot `/generate`. - **Rationale:** Spec decision D28. - **Where:** `app/main.py`, `app/a2a_server.py`, `app/card.py`, `app/presentation.py`. - **Acceptance criteria:** Approvals travel as structured data. The agent card is derived from the dependency graph. `/generate` response keys are unchanged from iteration 1. ## Step 8: Evaluation - **Capability:** A real-model evaluation of the whole engine with scripted user answers. - **Rationale:** The gate for cleanup: proceed only when every case scores at least 0.8. - **Where:** `eval/solution_eval.py`, `eval/scoring.py`, `eval/datasets/solution_cases.json`, `tests/eval/`. - **Acceptance criteria:** Each benchmark case completes and reaches `PASS_THRESHOLD` (0.8) on the 8 checks in `eval/scoring.py`. ## Step 9: Cleanup - **Capability:** One code path: the legacy pipeline removed and the new engine the only engine. - **Status:** Done in iteration 3, by a different route. On 2026-10-06 the engine first moved into the KAB folder layout, and the legacy pipeline was then deleted (`iter-03-kab-layout/steps/step-7.md`). - **Not done from the spec's list:** the sample artefacts the pipeline once wrote (`docs/*.md`, root `terraform/`, `deliverables/{as-is,target,validation,guides}/`) are still checked in.