Files
gcp_solution_architecture_a…/.agents/plans/iter-03-kab-layout/DETAIL.md
Jonathan Boniface 7ee49ab352
Some checks failed
validation / verify (push) Failing after 10s
latest refactoring
2026-10-06 20:22:37 +01:00

5.1 KiB

Plan Detail

Step 1: Container starts the Execution engine

  • Capability: The image runs the reviewed and evaluated engine.
  • Rationale: The Dockerfile started python -m app.agent, the iteration 1 pipeline, while every evaluation ran the new engine.
  • Where: Dockerfile, README.md.
  • Acceptance criteria: The container's main process is the A2A server. /health and /.well-known/agent-card.json answer on the container port. Existing -p 8080:8080 run commands still work.

Step 2: Legacy pipeline moved to app/legacy/

  • Capability: The KAB folder names are free for the new engine, with the old pipeline still importable and tested.
  • Rationale: The owner chose to keep the old code rather than delete it (2026-10-06). The old and new code cannot share app/nodes/, app/states/, app/workflows/.
  • Where: app/legacy/, the five legacy tests in tests/, eval/eval_harness.py, SKILLS_DIR in app/config.py.
  • Acceptance criteria: Every legacy test passes against app.legacy.*. Nothing outside app/legacy/, those tests and the legacy eval files imports app.legacy.

Step 3: Engine moved into the KAB folders

  • Capability: The engine's modules sit where the KAB workflow standard expects them.
  • Rationale: Platform consistency: decomposers, reviewers and other agents on the platform look for state in app/states/, nodes in app/nodes/, graphs in app/workflows/, the manager in app/agent.py.
  • Where: The path table in ../README.md.
  • Acceptance criteria: Behaviour is unchanged: the full suite passes with only import paths edited in tests. google.adk is still imported only by app/adk/adk_runtime.py. Package __init__.py files import nothing, so app.states can import app.workflows.deliverables without a cycle.

Step 4: Graph file split into nodes and wiring

  • Capability: Node logic in app/nodes/, graph assembly in app/workflows/.
  • Rationale: The KAB layout separates stage nodes from graph construction; the engine had both in one 560-line file.
  • Where: app/nodes/execution_nodes.py (make_execution_nodes returns an ExecutionNodes of the five node callables), app/workflows/execution_graph.py (build_execution_graph), ToolFactory in app/adk/runtime.py.
  • Acceptance criteria: build_execution_graph keeps its signature. The nodes still route with Command and Send, so the wiring declares only the fixed edges.

Step 5: Refresh paths in the spec and ADR text

  • Capability: Design documents that name modules where they are.
  • Rationale: .scratch/solution-architect-agent/spec.md (module layout, acceptance list, comments) and the ADRs still use pre-move paths. An agent following them will look in app/legacy/ or in folders that no longer exist.
  • Where: .scratch/solution-architect-agent/spec.md sections "Module layout" and "Acceptance"; docs/adr/0002-*.md consequence about app/skills/; docs/adr/0003-*.md.
  • Acceptance criteria: The spec's module layout matches the tree. Each acceptance command in the spec runs against current paths. Dated ## Comments entries stay as written, since they are history; one note at the top of the comments points to ../README.md for translation.

Step 6: Finish iteration 2's cleanup list

  • Capability: The parts of iteration 2 step 9 that still apply once the legacy code is kept.
  • Rationale: The spec's cleanup list mixed deletions (now dropped) with changes the new engine still needs.
  • Where and what:
    • workflow.yaml: rewrite its phases to the four upstream Phases and their Deliverables.
    • app/config.py, .env.example: move settings only app/legacy/ reads (HOST, PORT, GCP_PROJECT_ID, GCP_REGION, ADK_*, DEVELOPER_KNOWLEDGE_MCP_*, SKILLS_DIR, EVAL_DATASET_PATH, the OpenAI and Azure keys) under a clearly marked legacy block. Keep POSTGRES_* and DATABASE_URL: the Postgres checkpointer builds its URL from them.
    • mypy.ini, ruff.toml: exclude app/legacy/ and the legacy eval files, so ruff check . and mypy . report on live code only (198 and 38 findings today, almost all legacy).
    • Dockerfile: stop copying what only the legacy pipeline reads, once step 7 is decided.
  • Acceptance criteria: ruff check . and mypy . are clean or list only known, recorded exceptions. workflow.yaml names the four Phases in app/workflows/deliverables.py. The suite passes.

Step 7: Decide the future of app/legacy/

  • Capability: One code path, or a deliberate, documented second one.
  • Rationale: Two pipelines cost every reader a detour, and the legacy one holds what ADR-0002 rules out: hand-written cloud clients, non-conformant Skills, a pretend ADK layer.
  • Options for the owner: delete app/legacy/ with its tests and the legacy eval files; or keep it frozen and excluded from lint, types and the image.
  • Guardrail: Deleting files with uncommitted changes was blocked once by the permission system. Commit first, then delete in a commit of its own.
  • Acceptance criteria: The decision is recorded here. If deleted: grep -rn "app\.legacy" app eval tests is empty and the suite passes.