architecture-planning

name: architecture-planning description: Define component boundaries, interfaces, and structural decisions for a change

Objective

Consolidate approved upstream deliverables into a cohesive architectural plan that downstream code-planners can implement independently.

Output: a git-tracked architecture document (specs/arch-plan/<goal-slug>/<timestamp>-<task-id>.md) plus structured output[] entries, one per code-planning scope. Each output entry becomes a code-planning child task — the code-planner reads the architecture document and its scope entry, the goal spec, and referenced material. Write accordingly: the arch doc should be self-contained for structural decisions, leaving behavioral detail to the spec.

The architect bridges what (spec) and how (code plan). Spec says what to build; the architect says where each piece goes and how pieces connect. Code-planners turn each scope into implementation steps.

Trigger

• Orchestrator creates an architecture task (Liza mode)
• User asks to plan architecture for a feature or change (Pairing mode)
• Implementation planning requires structural decisions before code-planning

Inputs

Your task provides:

• A goal spec (spec_ref) — what must be built
• Parent task context — upstream deliverables being consolidated (many-to-one fan-in)
• An output mechanism — set-task-output for each code-planning scope

Scope discipline:

• Upfront: Read goal spec + parent task deliverables + explore relevant codebase areas
• On demand: Broader exploration only when structural questions require it
• Declare what you read and why in References

Output Format

Architecture Plan format at the task-specified path.

Protocol

1. Consolidate

Read and synthesize all inputs before making any structural decisions.

1. Read the goal spec — the authoritative source for what must be built
2. Read all parent task deliverables (descriptions, outputs, referenced specs/plans)
3. Synthesize scope: what is the full extent of what must be built?
4. Identify:
   • Overlaps — parent deliverables that touch the same area
   • Gaps — scope in the goal spec not covered by any parent deliverable
   • Conflicts — parent deliverables that make incompatible assumptions

If conflicts are unresolvable from the spec, surface as Open Questions.

2. Survey

Map the existing architecture before proposing changes.

1. Explore the codebase: existing components, patterns, boundaries
2. Identify extension points, constraints, and conventions to follow
3. Note existing components affected by this change

Do not over-explore. Enough understanding for sound structural decisions, not a full architecture review. For deeper analysis of a specific area, use software-architecture-review in Code Review Supplement mode.

3. Design

Define structural decisions. Each decision must have a rationale.

1. Component boundaries — new or modified components, what each is responsible for
2. Interface contracts — how components communicate; what data crosses boundaries, in what form
3. Data flow — trace the primary data paths end-to-end
4. Cross-cutting concerns — error handling, observability, configuration, security
5. Structural decisions — explicit choices with rationale

Decision altitude:

If a decision reads like code, it's too low. If it reads like a requirement, it's too high.

4. Decompose

Map the architecture to code-planning scopes. Each scope becomes one code-planner task. Scopes correspond to domains or sub-domains — not to implementation steps. Sequencing work within a scope is code-planner territory.

1. Identify scopes — natural boundaries from the design
2. Scope independence — each code-planner should work without waiting for another
3. Scope completeness — each scope is implementable and testable on its own
4. Ordering constraints — depends_on only when scope B cannot be implemented without A's output
5. Shared-file audit — overlapping file access needs depends_on or explicit interface contracts

Decomposition heuristics:

• A scope requiring >5-8 files to understand is probably too broad
• A scope producing <2-3 meaningful changes is too narrow — merge it with a sibling
• If you can't write a falsifiable done_when, the scope isn't well-bounded
• Prefer scopes aligned with existing package/module boundaries
• If two scopes share one domain and differ only in implementation order, they're one scope
• A domain must have independent user-visible purpose from the spec's perspective. Build config, packaging, module stubs, and boilerplate that exist solely to support a feature are part of that feature's scope — not a separate domain. "Scaffolding then implementation" is an implementation-step split disguised as a domain split.

5. Self-Review

Before submitting:

• Every component boundary has a clear responsibility statement
• Every interface contract specifies what crosses the boundary
• Data flow traces cover primary paths — no orphaned components
• Structural decisions have explicit rationale
• Decomposition covers the full goal spec scope
• Scopes map to domains, not implementation steps within a domain
• Each scope has a falsifiable done_when
• depends_on captures true ordering constraints only
• Shared-file conflicts identified and resolved
• Architecture document is self-contained for code-planners
• No decisions prescribe implementation detail below interface level
• Cross-cutting concerns addressed for all components
• Re-read goal spec — nothing from spec left unassigned

Fix issues before submitting.

Constraints

• Do not write code — architecture plan only
• Do not prescribe implementation detail below the interface level
• Do not modify existing specs unless task explicitly scopes an update
• Do not invent requirements beyond the goal spec
• Surface contradictions between parent deliverables as Open Questions
• Respect existing architectural patterns unless there is a concrete reason to deviate (document it)

Anti-Patterns

Integration

Mode-Specific Behavior

Pairing: Present the architecture plan for human review before writing.

Liza: Autonomous within task scope. Plan submitted for review; Architecture Reviewer validates.