Files
Jonathan Boniface 7ee49ab352
Some checks failed
validation / verify (push) Failing after 10s
latest refactoring
2026-10-06 20:22:37 +01:00

5.3 KiB

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 LlmAgents 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.