# Architect > Architecture Decision Records, System spec, Milestone plan - Skill: `xoai/architect` (Agent Skill) - Install (CLI): `npx skillmds@latest add xoai/architect` - Raw SKILL.md: https://api.skillmd.com/api/skills/xoai/architect/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: xoai (https://skillmd.com/u/xoai) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/xoai/architect --- - PERSONA: Read sage/core/agents/architect.persona.md for your mindset. # Architect Workflow System design for new projects or major redesigns. Elicit, then design, then plan. Never skip steps. ## Auto-Pickup Scan `.sage/work/` for architect initiatives. This scan is MANDATORY — check the DISK. **Manifest-first path:** If `.sage/work/*/manifest.md` exists with `workflow: architect`, run `python3 "${CLAUDE_PLUGIN_ROOT}/tools/manifest.py" resume` (no python3 → read the manifest by hand). Resume at the phase the brief indicates, with the manifest body as judgment *context, not orders* — the live user outranks recorded decisions, recorded decisions outrank manifest prose, and evidence outranks all of it. Multi-session architect cycles benefit most from the manifest — it preserves the reasoning behind architecture decisions across sessions. **Fallback path:** If no manifest.md but artifacts exist, use file-scan: - No artifacts → Step 2 (elicitation) - Brief exists, no spec/ADRs → Step 3 (design) - Spec/ADRs exist, no plan → Step 4 (milestone plan) - Plan exists → Step 5 (phased build) Create manifest.md from inferred state before proceeding (backfill). You MUST follow this routing. Do not override it. Scan `.sage/docs/` for existing research, ADRs, or decisions. Read `.sage/decisions.md` for context. Read `handoff` field in the most recent artifact if present. ### Manifest Lifecycle (architect workflow) **Create** manifest.md when brief.md is saved (after elicitation), `gate_state: pre-spec`. **Update** at every checkpoint: elicitation gate, design checkpoint, plan checkpoint, each milestone completion — advance `gate_state` with each. **Session end ([N]):** Manifest update is MANDATORY — architect cycles span sessions, so handoff guidance is critical. **Completion:** Set `status: complete` and `gate_state: complete` after final milestone — the completion guard requires `gate_state` to have reached `gates-passed` first. **gate_state at each checkpoint (machine field — the spec-gate hook reads it):** - Manifest created (brief saved) → `pre-spec` - Design / ADRs approved `[A]` (spec.md `status: completed`) → `spec-approved` - Plan approved `[A]` → `plan-approved` - Implementing a milestone via build-loop → `building` - A milestone's quality gates pass → `gates-passed` - Final milestone complete → `complete` Until `gate_state` reaches `spec-approved`, edits to source files are blocked — this is Rule 3 (design before implementation) made mechanical. **Anti-lazy-manifest:** Same contract as build workflow — summary must contain judgment, not spec titles. ## Step 2: Deep Elicitation This is the most important step. Understand the full picture before designing anything. For comprehensive elicitation process, read `sage/core/capabilities/elicitation/deep-elicit/SKILL.md`. **Three rounds — each produces a VISIBLE ARTIFACT:** **Round 1 — Vision:** What are you building and why? Who is it for? What does success look like? → Produce: vision summary (saved inline in brief or presented) **Round 2 — Constraints:** Technical constraints, timeline, team size, existing systems to integrate with, non-negotiables. → Produce: constraints list (saved inline in brief or presented) **Round 3 — Gaps:** What's still unclear? What assumptions are we making? → Produce: gaps analysis (saved inline in brief or presented) Save combined elicitation to `.sage/work/YYYYMMDD-slug/brief.md`. **Do NOT proceed to design until all three rounds are complete.** Do NOT compress three rounds into one response. Do NOT skip rounds because "the user already explained everything." Each round asks different questions — answers to Round 1 don't satisfy Round 2 or 3. If Sage has relevant UNDERSTAND skills (research, analysis), recommend them here: Sage recommends understanding the context before designing: [1] Start with research — understand user needs first [2] Continue with elicitation round [N] [3] Something else 🔒 **ELICITATION GATE:** **File check:** Does `.sage/work/*/brief.md` exist with content from all three rounds (vision, constraints, gaps)? If no → complete the missing rounds. Do NOT proceed to design. Do NOT rationalize skipping: - "The user described the system clearly" → NOT three-round elicitation - "I understand the requirements" → your understanding is not a brief file - "We can figure out details during design" → gaps analysis exists to catch exactly this. Do it now, not during design. Sage: Elicitation complete. Brief saved. [A] Approve — continue to architecture design [R] Revise — I want to add or change something [N] New session — type /architect to continue with design Pick A/R/N, or tell me what to change. ## Step 3: Architecture Design **File check:** `.sage/work/*/brief.md` MUST exist before designing. If it doesn't exist, go back to Step 2. No exceptions. Define: system components, data model, API boundaries, technology choices, deployment architecture, security model. Document key trade-offs and the reasoning behind each decision. Save architecture decisions to `.sage/docs/decision-*.md`. Save the full design to `.sage/work/YYYYMMDD-slug/spec.md` with frontmatter. 🔒 **DESIGN CHECKPOINT:** **Self-check (observable conditions):** - [ ] brief.md exists in .sage/work/ (elicitation was completed) - [ ] spec.md exists in .sage/work/ (design was written) - [ ] At least one decision-*.md exists in .sage/docs/ (ADRs written) - [ ] Trade-offs are named for each major decision If ANY fails → go back and create the missing artifact. Sage: Architecture design saved. ADRs in .sage/docs/decision-*.md Decision: [key architecture decisions]. (append to .sage/decisions.md) [A] Approve — continue to planning in this session [R] Revise — here's what needs changing [Q] Question — I want to understand [specific decision] better [N] New session — type /architect to continue with milestone plan Pick A/R/Q/N, or tell me what to change. On approval: update spec frontmatter to `status: completed`. Write `handoff` field in frontmatter: ```yaml handoff: | Key decisions: [architecture choices and trade-offs] Open questions: [what needs resolution during build] Risks: [cross-cutting concerns, performance, migration] Next agent should: [specific guidance for milestone planning] ``` Append architecture decisions to decisions.md (Rule 7). ## Step 4: Milestone Plan **File check:** `.sage/work/*/spec.md` MUST exist with `status: completed` before creating a milestone plan. If it doesn't → go back to Step 3. Break the build into milestones (not tasks — milestones). Each milestone should be deployable and testable independently. Within each milestone, create a task plan. Save to `.sage/work/YYYYMMDD-slug/plan.md` with frontmatter. 🔒 **PLAN CHECKPOINT:** Sage: Milestone plan saved to .sage/work/YYYYMMDD-slug/plan.md [A] Approve — start building milestone 1 in this session [R] Revise — adjust the breakdown [N] New session — type /build to start milestone 1 Pick A/R/N, or tell me what to change. On approval: append plan approach to decisions.md (Rule 7). **Next steps (Zone 3):** Next steps: /build — spec → plan → implement → verify (start milestone 1) /review — independent evaluation of the architecture /reflect — review design decisions before building Type a command, or describe what you want to do next. ## Step 5: Phased Build Execute milestone by milestone. **Each milestone MUST follow the build workflow gates independently:** For each milestone: 1. Create milestone-specific spec if the milestone adds new details beyond the architecture spec 2. Create milestone task plan 3. Implement via build-loop with quality gates per task 4. Verify milestone independently (tests pass, feature works) 5. Present milestone checkpoint Do NOT batch-implement multiple milestones without checkpoints. Do NOT skip per-milestone verification because "I'll test everything at the end." **At each milestone completion checkpoint:** Sage: Milestone [N] complete — [summary] Decision: [what was learned during implementation]. (append to decisions.md) [C] Continue to milestone [N+1] [R] Revise — adjust before continuing [P] Pause — type /build to continue next session **Re-validate after each milestone:** Check architecture assumptions against what implementation revealed. If the architecture needs adjustment, note it in decisions.md and update ADRs before proceeding. ## Quality Criteria **Communication style:** Systems thinking. Name trade-offs explicitly, discuss failure modes, and explain decisions in terms of constraints and alternatives considered. Good architecture output: - Trade-offs are named explicitly — no trade-offs = not deep enough - Failure modes addressed for every integration point - System boundaries are clear — what's in scope, what's external - Each milestone is independently deployable and valuable ## Rules - Elicitation before design. brief.md MUST EXIST before spec.md is created. "I understand the requirements" is NOT a brief file. - Three elicitation rounds. Do NOT compress or skip rounds. - Decisions documented with rationale. ADRs in .sage/docs/. - Checkpoints mandatory. Present [A]/[R] and wait. - Milestones build independently. Each follows build workflow gates. - Re-validate after each milestone. Architecture assumptions may be wrong — implementation reveals truth. ## Failure Modes - **Agent skips elicitation:** "I already understand the system." The elicitation gate blocks this — brief.md must exist. - **Agent compresses rounds:** One response covering all three rounds misses the back-and-forth that catches gaps. Rounds must be sequential with user input between them. - **Agent batch-implements milestones:** "I'll build all three milestones in one pass." Each milestone needs its own checkpoint. - **Architecture assumptions survive implementation:** The re-validate step after each milestone catches stale assumptions.