Files
gcp_solution_architecture_a…/docs/agents/issue-tracker.md
Jonathan Boniface 4fefe0ab33
Some checks failed
validation / verify (push) Failing after 10s
docs: design the portable solution architect agent
Record the direction and build plan for replacing the upstream
google-cloud-solution-architecture skill with a portable agent.

- ADR-0002: Agent Skills are the portable unit of behaviour, loaded by
  the framework's native skill runtime; discovery and grounding use
  each Cloud provider's hosted remote MCP servers.
- ADR-0003: LangGraph holds Execution state, checkpoints and
  interrupts; a ReAct Orchestrator and Specialists run as ADK
  LlmAgents with SkillToolset. Supersedes ADR-0001.
- CONTEXT.md: domain glossary (Execution, Phase, Approval, Revision,
  Orchestrator, Specialist, Deliverable, Dependency, Cloud provider).
- .scratch/solution-architect-agent/spec.md: build spec with the
  dependency graph, Revision rules, tool tiers, MCP allowlists, A2A
  interaction, tests and nine build increments.
- .scratch/phase-pipeline/spec.md: superseded; kept as decision log.
- CLAUDE.md and docs/agents/: agent skill configuration (local
  markdown issue tracker, triage labels, domain docs).
- README.md: direction note; flags current ADK classes as stubs.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-09-15 18:09:26 +01:00

1.8 KiB

Issue tracker: Local Markdown

Issues and specs for this repo live as markdown files in .scratch/.

Conventions

  • One feature per directory: .scratch/<feature-slug>/
  • The spec is .scratch/<feature-slug>/spec.md
  • Implementation issues are one file per ticket at .scratch/<feature-slug>/issues/<NN>-<slug>.md, numbered from 01, never a single combined tickets file
  • Triage state is recorded as a Status: line near the top of each issue file (see triage-labels.md for the role strings)
  • Comments and conversation history append to the bottom of the file under a ## Comments heading

When a skill says "publish to the issue tracker"

Create a new file under .scratch/<feature-slug>/ (creating the directory if needed).

When a skill says "fetch the relevant ticket"

Read the file at the referenced path. The user will normally pass the path or the issue number directly.

Wayfinding operations

Used by /wayfinder. The map is a file with one child file per ticket.

  • Map: .scratch/<effort>/map.md (the Notes / Decisions-so-far / Fog body).
  • Child ticket: .scratch/<effort>/issues/NN-<slug>.md, numbered from 01, with the question in the body. A Type: line records the ticket type (research/prototype/grilling/task); a Status: line records claimed/resolved.
  • Blocking: a Blocked by: NN, NN line near the top. A ticket is unblocked when every file it lists is resolved.
  • Frontier: scan .scratch/<effort>/issues/ for files that are open, unblocked, and unclaimed; first by number wins.
  • Claim: set Status: claimed and save before any work.
  • Resolve: append the answer under an ## Answer heading, set Status: resolved, then append a context pointer (gist + link) to the map's Decisions-so-far in map.md.