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 its assigned architecture scope and declared direct references. Write a locally sufficient structural delta; leave behavioral authority at its source rather than copying it into the architecture document.

Follow the shared Reference-First Authoring contract. This skill owns scope-local structure, interfaces, data flow, failure handling, and structural rationale. It references inherited behavior and shared architecture. Map components, interfaces, and proof obligations to the requirements they serve, separating the minimum mechanism Must scope needs from optional extensions; check consequential platform assumptions and place each proof at its stage per Priority, Commitments and Proof Stage. A master groups a shared uncertainty and names its specialist owner instead of investigating it in every child.

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 (§BRAND_NAME_TITLE§ 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 assigned goal/parent anchors and their declared direct references; explore relevant codebase areas
• On demand: Broader exploration only when structural questions require it
• Declare selected source anchors in the strict Source References section and map every assigned obligation to a direct-reference ID

Every new architecture plan must contain exactly one strict ## Source References section using the shared contract's JSON-quoted grammar, a 40-lowercase-hex source revision, non-empty direct references, and non-empty obligation coverage. Use exact eligible ATX heading text in fragments, not slugs.

Output Format

Architecture Plan format at the task-specified path.

Protocol

1. Consolidate

Read and synthesize the assigned anchor spans and direct references before making structural decisions.

1. Read the assigned goal-spec anchors — the authoritative source for what must be built
2. Read parent task envelopes and their assigned artifact anchors; follow only declared direct references needed for an unresolved dependency
3. Synthesize the assigned obligations and structural scope
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
4. Read the project's decision record where it keeps one — prior decisions bind unless deliberately revisited

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

Provider freeze: Obtain early epic Provider Ask Inventory; reconcile assigned epics/source obligations and merged consumers. Answer or concretely defer each interface ID, consumer epic/ref, operations, fields and statuses. Unavailable asks block affected freeze; unresolved needs are Design prerequisites, not gap notes. Child scope/preserve rules allow tests, acceptance manifests and repairs; verify existing-source premises before binding. Inventory strings create no executable dependency edges. Scope #### CONTRACT owns interface prose; keep allocations/acceptance/executable metadata outside. Edit only its preexisting unique subsection; freeze complete output manifest, allocation and approved resolved proofs.

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, naming the earliest one that suffices (see False Dependence)
5. Shared-file audit — overlapping edits to a file or definition need depends_on unless stated to commute (each keeps the other's behavior; no common key, slot, name or position; neither needs the other's initialization or state). An interface contract removes a consumer's wait, not a writer edge.

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 scopes are locally sufficient from their direct references and task envelopes
• No decisions prescribe implementation detail below interface level
• Cross-cutting concerns addressed for all components
• Every assigned obligation maps to a direct reference whose anchor span contains it
• Structural decisions do not silently redefine inherited behavior
• Provider asks, freeze duty, human-owned prerequisites met

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
• Inherited NFRs are bounds: refine inside them, never tighten them. Challenge a target that looks overkill for the business context (e.g. HA for a non-critical tool) as an Open Question with its build and proof cost. A recorded human decision that states that cost is inherited without reconfirmation.
• Surface contradictions between parent deliverables as Open Questions
• Respect existing architectural patterns unless there is a concrete reason to deviate (document it)
• Where the project keeps a decision record, write to it any structural decision durable enough to constrain later work — a deviation from an existing pattern, or an ADR candidate named upstream. Where it keeps none, name the candidate in the plan. Rationale is already required at step 3; this decides where the decision lives, not whether to justify it.

Anti-Patterns

Integration

Mode-Specific Behavior

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

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