Architect

---
name: architect
description: 'Use when non-trivial code needs designing before implementation, or an existing codebase needs its architecture improved: surveying for shallow modules, locating a seam, deepening a structure, hardening with guardrails, or making code testable. Also handles surveying for shallow modules, locating seams, deepening structures, hardening with guardrails, and making code testable. Not for architecture diagrams, deploy, remote, credential, or irreversible changes.'
---

# Architect

## Contract

| Field | Bound contract |
|---|---|
| Trigger | Design non-trivial code before implementation (greenfield), or improve an existing codebase's architecture (brownfield): survey for shallow modules, locate a seam, deepen a structure, harden with guardrails, or make code testable. |
| Authority | Write named local design artifacts and, when the request permits, implement the selected design in the working tree. All writes reversible by deleting or reverting them. No VCS, credential, paid, published, deployed, or remote mutation. |
| Side effect | A local design package; in implement mode, the accepted refactor, its tests, inline `CONTEXT.md` entries for established domain terms, and an optional local ADR the user accepts. |
| Done | An explicit design choice with tradeoffs and a coherent implementation shape are recorded. In brownfield implement mode: one chosen deepening candidate is grilled to resolution, its shallow path is replaced rather than layered, tests exercise the resulting interface, obsolete shallow tests and code are removed, and established domain terms and accepted decisions are recorded locally. |

## Refusal

Not for visual architecture diagrams or HTML artifacts — use architecture-diagram, which renders a self-contained visual from a frozen specification; architect designs code structure (modules, interfaces, seams, depth) and produces a design package, not a rendered diagram. Not for deploy, remote, credential, publish, or irreversible changes — use deploy or shipping skills. Not for people-process or organizational architecture.

## Vocabulary

Use these terms consistently in every recommendation and design sketch:

- Module: any unit with an interface and implementation, at any scale.
- Interface: every fact a caller must know — types, invariants, ordering, errors, configuration, performance shape.
- Implementation: what the interface hides.
- Depth: behavior hidden per unit of interface learned; a deep module provides high leverage through a small interface. Shallow modules expose a broad surface with little hidden.
- Seam: a point where behavior can be substituted or tested in isolation without editing that behavior in place.
- Adapter: a concrete implementation used at a seam.
- Leverage: capability gained per unit of interface learned.
- Locality: concentrating a change, bug, or required knowledge at one maintenance site.

## Procedure

### Greenfield mode — design before implementation

1. **Bound scope.** Confirm the code unit to design and its trust boundary (inputs, callers, failure paths). Done when: the unit is named and its boundary stated. If the request is trivial or already fully specified, stop and report no design needed.
2. **Sketch the usage surface first.** Write the public call shape — signatures, call sites, data shapes — before any implementation detail. Done when: the usage surface is recorded as a local artifact.
3. **Produce at least two competing design sketches** that each satisfy the usage surface and differ in structure or tradeoff. Done when: each sketch is coherent enough to evaluate.
4. **Evaluate every sketch against red flags:** hidden complexity, leaky abstraction, unbounded scope, premature generality, missing error or edge handling. Done when: each sketch has a red-flag record.
5. **Apply the redesign threshold.** If every sketch trips a blocking red flag or no sketch is coherent, redesign from the usage surface. Stop redesigning once at least one sketch is coherent and trips no blocking red flag. Done when: at least one coherent, unblocked sketch exists.
6. **Select the sketch with the best tradeoff record.** State the explicit design choice and the rejected alternatives with their tradeoffs. Done when: the choice and rejections are recorded.
7. **Derive the coherent implementation shape** — modules, types, control flow, failure paths — from the selected sketch. Done when: the implementation shape is recorded.
8. **Implement only if the human request and authority permit;** otherwise stop at the design package. Done when: either implementation is complete or the design package is delivered.

### Brownfield mode — improve existing architecture

#### Survey (read-only)

1. **Validate scope.** If a scope subset is supplied, confirm each path exists. Reject any path that does not. Done when: scope is confirmed or rejected with the missing path named.
2. **Enumerate module surfaces and assess depth.** See `references/survey-ranking.md` for the depth indicators and two-axis scoring. Done when: every public module is scored.
3. **Identify shallow modules and rank deepening candidates** by refactoring effort (call sites affected) and architectural gain (internal depth gained). Higher gain, lower effort ranks higher. Done when: a ranked candidate list exists.
4. **Select the top candidate** with a one-paragraph rationale. If no shallow modules are found, report zero candidates. Done when: one candidate is chosen or zero-candidate is reported.
5. **Return the report.** Do not modify source code. Done when: the ranked list, chosen candidate, internal seam notes, and any load-bearing rejection note are delivered.

#### Deepen (implement)

1. **Dispatch a read-only explorer** over the selected candidate's scope. Read applicable `CONTEXT.md` and local ADRs when present. Done when: the candidate's files, coupling, and dependencies are understood.
2. **Classify friction with the deletion test:** if deleting a module removes complexity, it is pass-through; if complexity spreads into callers, it earns its place. Treat the public interface as the test surface. Introduce a seam only for two real implementations (production + test); do not create a port for a hypothetical second adapter. Done when: each candidate has a deletion-test result.
3. **Present a numbered candidate list.** For each: name the files, the concrete problem and deletion-test result, a plain-language solution without an interface proposal, and expected locality, leverage, and testability changes. Ask the user to select one before writing. Done when: the user selects one candidate.
4. **Grill the selected candidate adversarially.** Resolve one dependent design decision at a time and recommend one answer. Bound the changed-file set before mutation. If a new domain term becomes established, update or lazily create `CONTEXT.md` immediately. If the user rejects a design for a reason future maintainers need, offer a local ADR and write it only after acceptance. Done when: every design decision is resolved.
5. **If the user requests interface alternatives, dispatch the design-twice parallel passes** described in `references/interface-design.md`. Done when: the designs are compared and differences resolved.
6. **Choose the dependency treatment by observed class** — see `references/deepening.md` for the four categories and their testing strategies. Done when: the dependency treatment is named.
7. **Implement only the accepted design.** Validate external and serialized inputs at the new interface. Migrate every scoped caller, delete the replaced shallow path, and delete shallow-module tests after equivalent interface tests exist. Do not layer the new design over the old. Done when: the shallow path is replaced, not layered.
8. **Exercise the changed behavior through the same interface callers use.** Confirm the accepted invariants, error modes, and relevant dependency implementation. Review the final changed-file set against the bound scope. Done when: interface-level checks pass and the changed-file set matches the bound scope.

#### Locate seam, testability, guardrails (read-only or implement)

1. **Locate the seam:** identify points where a caller can substitute an alternate implementation or inject a test double. If no seam exists, propose the smallest interface introduction that creates one without widening the public surface. Done when: each seam is named or the smallest creating-interface is proposed.
2. **Make code testable:** identify the concrete dependencies that block isolated testing, then propose seams (interface extraction or dependency injection) that make those dependencies substitutable. Prefer a seam that does not change production behavior. Done when: each blocking dependency has a proposed seam.
3. **Harden with guardrails:** recommend tooling that enforces the decisions — type-level constraints that make invalid states unrepresentable, lint or analysis rules that fail on violation, boundary checks, or tests that fail when an invariant breaks. Name the invariant each guardrail protects. Done when: each guardrail is tied to its invariant.
4. **Stop at recommendations unless the request and authority permit implementation.** Mark any recommendation not grounded in read code as inference. Done when: recommendations are delivered or implementation is complete.

## Failure and recovery

- Trivial or fully specified request (greenfield): stop, report no design needed, mutate nothing.
- No coherent sketch after the redesign threshold (greenfield): report blocked with the red-flag record; do not implement.
- Target code unreadable or absent (brownfield): report what is missing and stop. Do not infer structure from names alone.
- Ambiguous design question (brownfield): ask which sub-branch applies before proceeding. Do not guess and do not run all sub-branches.
- No defensible candidate (brownfield deepen): return `no-candidate` with the inspected scope and observed friction; make no changes.
- No selection or unresolved decision (brownfield deepen): return `blocked` with the candidate list or exact unresolved decision; preserve completed read-only analysis; make no implementation change.
- ADR conflict without a load-bearing reopening reason: preserve the ADR and return `blocked-by-decision`; do not re-litigate or bypass it.
- Conflicting constraints: surface the conflict and the tradeoff explicitly. Do not silently pick one side.
- Missing required implementation fact or unavailable behavioral check: return `blocked` with the missing fact or check and the files already changed. Do not claim the done predicate.
- Failed implementation or verification: restore every modified named file to its captured pre-change contents, remove only newly created artifacts from this run, and return `failed-rolled-back` with the failing observation. If exact restoration cannot be proved, stop with `recovery-required`, listing each affected file and its pre-change source.
- Partial result: analysis, candidate lists, and resolved decisions may be reported, but partially migrated code is never a successful output and must be rolled back. Ungrounded recommendations are marked as inference.
- Scope drift: stop, report the widening, mutate nothing outside the named artifacts.
- Rollback: delete or revert the named local design artifacts. No VCS, credential, or remote mutation is permitted.

## Output

A design package containing: the usage surface (greenfield) or the surveyed scope and ranked candidates (brownfield); the competing sketches or candidate list; the red-flag evaluation or deletion-test results; the selected design with tradeoffs and rejected alternatives; the coherent implementation shape; and, in implement mode, the interface-level checks and observed results, any `CONTEXT.md` or accepted ADR update, and the replacement and deletion performed. Terminal classification: `done`, `no-design-needed`, `no-candidate`, `blocked`, `blocked-by-decision`, `failed-rolled-back`, or `recovery-required`.