Vaibtan Architect
Design from caller behavior inward. Ground the current system, compare materially different shapes, choose one coherent contract, then implement only when the user's request includes implementation.
If the requested deliverable is a technical specification, read technical-spec.md and follow its design-only boundary. Its sections own the rationale; do not also run the phases below or produce a separate rationale artifact.
1. Ground
Trace the affected behavior from entrypoint to side effects and response. Read callers, types, tests, configuration, and runtime boundaries. Use $how for execution structure and $why when historical rationale or external evidence could constrain a redesign.
State the current ownership, invariants, and failure model. Preserve any unresolved facts that could change the design as open questions, and establish them from source or a small experiment when possible. Do not invent an unresolved fact when the design is fully grounded.
2. Sketch alternatives
Produce at least two structurally distinct candidates for a novel or consequential boundary. Alternatives must differ in ownership, public contract, data shape, or call flow rather than naming.
Use $arena when independent candidate generation adds confidence. Otherwise compare the alternatives directly. If delegation is used, read $CODEX_HOME/pstack-models.toml and default architect runners to the deep and general profiles.
Each viable candidate should show:
- caller usage;
- important types and signatures;
- module ownership and dependencies;
- entrypoint-to-side-effect flow;
- expected failures and boundary translation;
- test seams and operational impact.
Screen candidates with design red flags. Prefer a cohesive module that hides complexity behind a low-burden interface.
3. Choose and record
Select one design against explicit criteria. Use the rationale template for a substantial decision. Record rejected alternatives and the evidence that decided the choice.
Proceed without a checkpoint unless the user requested design-only work, a review before implementation, or a product decision remains open. In those cases, return the concrete design and stop at that boundary.
4. Implement against the contract
When implementation is authorized, make the smallest coherent change that realizes the chosen shape. Treat repeated deviations as evidence that the architecture is wrong. Re-ground and redesign instead of accumulating escape hatches, optional fields, pass-through layers, or casts.
Review every delegated diff. Verify caller-visible behavior and the relevant static contracts. Report any planned contract that changed during implementation and why.