/architecture

name: architecture
description: "Architecture design and documentation. Produces 3-architecture.md with component diagrams, data flow, integration points, and architecture decisions. Reads existing tech-spec as input. Use when: designing system architecture, documenting component interactions, creating architecture docs, producing 3-architecture.md. Not for: tech spec writing (use tech-spec), code implementation (use feature-dev), architecture consulting only (use codex-architect)."
allowed-tools: Read, Grep, Glob, Bash(git:*), Bash(node:*), Bash(bash:*), Write, Agent, Skill, AskUserQuestion

Architecture Design Skill

Trigger

• Keywords: architecture, architecture design, architecture doc, component diagram, 3-architecture, system design, document architecture

When NOT to Use

• Tech spec writing (use `/tech-spec`)
• Code implementation (use `/feature-dev`)
• Architecture consulting only (use `/codex-architect`)
• Implementation roadmap (use `/deep-analyze`)

Usage

/architecture                          # Auto-detect feature, create/update
/architecture <feature-keyword>        # Specify feature
/architecture --skip-debate            # Skip Phase 3 adversarial debate

Workflow

sequenceDiagram
    participant U as User
    participant C as Claude
    participant E as Explore Agent
    participant X as Codex
    participant D as Architecture Designer
    participant B as /codex-brainstorm

    C->>C: Phase 0: Context Resolution
    par Phase 1: Research
        C->>E: Track A: Code pattern analysis (background)
        C->>C: Track B: Read tech-spec (inline)
    end
    E-->>C: Component list + dependencies
    C->>X: Track C: Architecture advice
    X-->>C: Independent recommendations
    C->>D: Phase 2: Architecture Design
    D-->>C: Component + flow + decisions
    C->>B: Phase 3: Verification (debate)
    B-->>C: Equilibrium conclusion
    C->>C: Phase 4: Write 3-architecture.md
    C->>U: Auto-trigger /codex-review-doc

Phase 0: Context Resolution

Detect the target feature using the 5-level cascade.

See `@skills/create-request/references/feature-context-resolution.md` for the full algorithm.

# The wrapper, not the CLI directly: it owns the failure payload, so the full shape with
# `scan_error: true` arrives however the CLI fails — nonzero exit, signal, partial write, or a
# payload that is not the agreed shape. (Not when `node` itself is unavailable: nothing running
# under node survives that.) `|| echo '{}'` would produce a payload the gate cannot see as failure.
node scripts/resolve-feature.js

> **`scan_error` gate.** Gate on **`scan_error !== false`**, not on `scan_error === true`. When it > is not exactly `false` the four source sets are **unknown, not empty** — the corpus could not be > enumerated (unreadable directory, broken taxonomy, no repository), *or* the resolver never ran > and a shell fallback supplied a payload with no such field at all. `{}` is the shape that made > the stricter test useless: it has no `scan_error`, so `=== true` is false and the gate passes a > payload that contains nothing. Do not proceed as though the feature has no authority documents — > report and take the ⚠️ Need Human exit. A `key` may still be present, so a non-null `key` is not > evidence the sets are complete.

| State | Mode | |-------|------| | `3-architecture.md` exists | Update (incremental) | | `3-architecture.md` absent + a tech spec resolves | Create (tech-spec-informed) | | `3-architecture.md` absent + no tech spec resolves | Create (code-only research) | | Feature not resolved | Gate: Need Human |

"A tech spec resolves" means `design_records` holds an entry of `type: tech-spec` — the same resolution Track B uses.

**`design_records` is an array, and more than one entry can be a tech spec**, so "the entry" needs a rule rather than an assumption. `docs/features/auto-loop-evolution/` is the live case: a split spec contributes `2-tech-spec/2-tech-spec.md` **and** its sub-document `2-tech-spec/1-phase-d-hook-hardening.md`, both `type: tech-spec` design records. Select in this order, and stop at the first that answers:

**Filter first, then choose — every later rule reads the filtered list, never the whole set.** Candidates are the `design_records` entries whose `type` is `tech-spec`; a requirements or architecture record is not a candidate at any step, and a rule phrased over "entries" rather than over candidates will select one. `docs/features/codex-review-spec/` and `docs/features/harness-engineering-rebrand/` are the live proof: neither has a tech-spec design record, each has exactly one canonical requirements record, and a canonicality test applied to the unfiltered set picks it.

| # | Candidates (`design_records` where `type: tech-spec`) | Result | |---|---------------------------------------------------|--------| | 1 | none | **No tech spec resolves** — the ordinary code-only row of the table above. Not an exit: a feature that has not been specced is a normal state, and Track C is given `(none — do not read a spec)` | | 2 | exactly one | that one | | 3 | two or more, exactly one with `is_canonical: true` | that one — a split spec's main file keeps the canonical filename, which is what makes it the main file | | 4 | two or more, and none or several canonical | **Gate: Need Human**, naming the candidates |

Rows 1 and 4 are different answers and must not be collapsed: "there is no spec" is a fact the skill acts on, "there are two and I cannot tell which" is an ambiguity it must not resolve by picking. **The set decides, and the set also names the file.** `canonical_docs` is role-blind: it selects the tech spec from `doc_inventory` whatever role that document resolves to, so a spec that has declared itself `History record` or `Work record` is still non-null there while being absent from `design_records`. Reading the alias as evidence of design authority is exactly the confusion the source sets replace — and it