liza-mas/architecture-planning

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:

| Too low (code-planner territory) | Right level | Too high (spec territory) | |----------------------------------|-------------|---------------------------| | "Function X takes param Y: int" | "Component A exposes a query interface that B calls" | "The system should be reliable" | | "Use a map[string]Task" | "Tasks are indexed by ID for O(1) lookup" | "Store tasks" | | "Error wraps with fmt.Errorf" | "Errors propagate up with context; no silent swallowing" | "Handle errors" |

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

| Pattern | What goes wrong | |---------|----------------| | Architecture Astronautics | Over-abstraction for hypothetical flexibility. If an interface has one implementation and no planned second, it's a cost not an investment. | | Scope Inflation | Components or interfaces not required by the spec. The plan should be minimal — just enough structure. | | Interface Speculation | Defining detailed contracts before understanding data flow. Trace data first; interfaces emerge from what needs to cross boundaries. | | Monolithic Scope | One giant scope spanning unrelated domain boundaries. Decompose when a scope covers multiple domains. | | Task-Level Decomposition | Splitting within a domain by implementation steps (e.g., "scaffolding" then "logic", or "core" then "wiring"). Build config and stubs that serve one feature are not a separate domain. Implementation sequencing is code-planner territory; the architect decomposes by domain. | | False Independence | Scopes sharing state or files without depends_on. Shared-file audit catches file overlap; also audit for shared-state overlap. | | Invisible Decisions | Structural choices without rationale. Every boundary should answer "why here?" | | Cathedral Planning | Pursuing perfect upfront design. Define boundaries and interfaces; implementation detail crystallizes during code-planning. | | Pattern Imposition | Forcing design patterns onto the problem. Name the problem first; pattern is the solution, not the starting point. | | Boundary Amnesia | Components without interface contracts. Every boundary needs a contract. |

Integration

| Skill | Relationship | |-------|-------------| | software-architecture-review | Complementary. This skill defines; that skill evaluates. | | detailed-spec-writing | Upstream. Goal spec is the primary input. | | systemic-thinking | Used by Architecture Reviewer to evaluate the plan. |

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.

| Pairing Prompt | Liza Behavior | |----------------|---------------| | "Parent deliverables conflict — resolve?" | Surface in Open Questions; document both options | | "Scope too broad — split?" | Decompose further; document split rationale | | "Existing pattern X — follow or deviate?" | State rationale; reviewer evaluates | | "Cross-cutting concern Y unaddressed" | Must be addressed before submission |