5.3 KiB
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 commit81a31a6, withVENDOR.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. Onlyapp/providers.pynames 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
ExecutionEngineinterface. - 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_turnandawait_userchange 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 importsgoogle.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_scriptis 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.
/generateresponse 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 ineval/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, rootterraform/,deliverables/{as-is,target,validation,guides}/) are still checked in.