/architect

name: architect
description: 'Use when non-trivial code needs a design, codebase design or architecture needs improving, or one module needs targeted interface narrowing, seams, or testability. Not for diagrams, deploy, 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; or design one named module's interface, seams, and testability (targeted-module). | | Authority | Reversible local: writes only named local design artifacts and, when the request permits, the selected design in the working tree; rollback is deleting or reverting those writes. 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 plan 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. In targeted-module mode: the chosen module presents a small coherent interface, hides implementation complexity, concentrates change locally, and is testable through explicit seams. |

Refusal

Not for visual architecture diagrams or HTML artifacts; use visual-diagram, which renders a self-contained visual; 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 shipping skills. Not for people-process or organizational architecture.

Inputs

• `mode`: `greenfield` (design before implementation), `brownfield` (survey, deepen, or seams/testability/guardrails on existing code), or `targeted-module` (one named module's interface, seams, and testability). Infer from the request; confirm when ambiguous.
• Targeted-module: one named target module (a function, class, package, crate, or tier-spanning slice) with readable source and enough of its callers and tests to judge what they must know; optional: intended adapters, candidate seam locations, and the target language, inferred from the source when not stated.

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 plan.
• 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.

Fix these terms; do not substitute near-synonyms: no "unit", "component", or "service" for module; no "API" or "signature" for interface, which name only the type-level surface; no "boundary" for seam, which is overloaded with DDD's bounded context. Say "adapter" when the seam is the topic and "implementation" otherwise; a small adapter can hold a large implementation, and a large adapter a small one.

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 plan, 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 plan**, modules, types, control flow, failure paths, from the selected sketch. Done when: the implementation plan 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 scor