Architect

Architect

Architect Skill — drives design decisions through Socratic questioning and produces a complete technical documentation system.

The architect's deliverables are the documentation system itself. Writing overview.md is the act of system decomposition; writing domain-model.md is the act of establishing ubiquitous language. Documentation is not a by-product of design — documentation IS the design.

Core Principles

1. Documentation before code: Each step's documentation output serves as input for the next step — no skipping, no reordering
2. Socratic questioning drives design: Do not propose solutions directly — first identify architectural concerns from User Stories, then converge design decisions through questioning
3. User Stories are purely user-perspective: User Stories should contain only user experience and acceptance criteria — never mix in technical details
4. Single file ≤ 400 lines: If exceeded, use overview.md as the entry point and split downward with layered navigation
5. Terminology unification: domain-model.md implements DDD Ubiquitous Language — the single source of truth (SSOT) for business term <-> technical term mapping
6. Superpowers outputs must be consolidated: Plans generated during a session must be written into docs/ before coding begins
7. Design-first approach: Documentation may describe the target state (design ahead of code is normal); however, implemented features must have corresponding documentation

Overall Workflow (must be executed in order)

1. User Story          → Define user experience flows and acceptance criteria (no technical details)
2. Architecture Design → User Story pattern recognition → Socratic questioning → brainstorming divergence
                         → Converge using methodology references → Output overview.md + domain-model.md + ADR
3. Dev/Test Env Design → Build feedback loops for AI Agent TDD
4. Module Detail Design→ Module-level pattern recognition → questioning → output ≤400 line module docs
5. Layered Test Plan   → Generate L2-L4 plans based on User Stories + tech design + env design
   (L2-L4)
6. Parallel TDD Dev    → Implement in parallel using agent teams + superpowers

Documentation Directory Structure

All documentation must reside under docs/ in the project root. In the tree below, docs/ is the root, and all subdirectories (product/, architecture/, etc.) are children of docs/. Absolute paths look like <project-root>/docs/product/prd.md. Do not create standalone product/ or architecture/ directories at the project root.

docs/                                # <-- The single root directory for all documentation
├── TODO.md                          # Documentation review tracking checklist (SSOT)
├── product/                         # docs/product/ — Product layer: user perspective
│   ├── prd.md                       # docs/product/prd.md
│   └── user-stories/
│       ├── README.md                # docs/product/user-stories/README.md
│       └── {service-or-module}.md   # docs/product/user-stories/{service}.md
├── architecture/                    # docs/architecture/ — Architecture layer: system design decisions
│   ├── overview.md                  # docs/architecture/overview.md (≤400 lines)
│   ├── domain-model.md              # docs/architecture/domain-model.md — Ubiquitous Language SSOT
│   ├── tech-stack.md                # docs/architecture/tech-stack.md
│   └── {service}/                   # docs/architecture/{service}/
│       ├── overview.md              # docs/architecture/{service}/overview.md (≤400 lines)
│       └── {topic}.md               # docs/architecture/{service}/{topic}.md (≤400 lines)
├── testing/                         # docs/testing/ — Testing layer: strategy and test cases
│   ├── strategy.md                  # docs/testing/strategy.md
│   └── services/{service}/          # docs/testing/services/{service}/
└── deployment/                      # docs/deployment/ — Deployment layer: environment operations manual
    ├── local-dev.md
    ├── ci.md
    └── cd.md

Rules

Step 1 — User Stories (docs/product/user-stories/{service}.md)

What to write: User experience flows, Epic breakdown, verifiable acceptance criteria (AC). May include NFRs (non-functional requirements).

Strictly forbidden: Technical implementation details (no class names, API paths, database fields, or protocol details). User Stories are the user's perspective, not a technical specification.

Document structure:

• Split files by service or module (e.g., gateway.md, sandbox.md) — one file per service domain
• Organize each file by Epic — an Epic is a business-meaningful feature cluster
• ID format: US-{module-abbreviation}-{number} (e.g., US-FI-01)
• Each User Story: Background (Why) + User Story (Who/What/Goal) + AC (Given/When/Then format)
• NFRs in a separate section with quantifiable metrics (e.g., "p95 response < 2s") — no implementation approach
• Progress markers: ✅ Implemented / ⚙️ In Progress / Not Started
• After adding new User Story, update the index table in user-stories/README.md

Companion Skill: story-craftsman (guided interviews to uncover context + standard template generation)

Step 2 — Architecture Design (docs/architecture/)

Step 2 is the architect's core work. Do not jump straight to drawing architecture diagrams after reading the User Stories — first identify the architectural concerns implied in the User Stories, converge design decisions through questioning, then commit them to documentation.

2a. User Story Pattern Recognition

After reading Step 1's User Stories, identify the implicit architectural concerns. Common User Story patterns and their architectural signals:

Not all User Stories will trigger every signal. A simple CRUD feature does not need to be questioned about distributed consistency. Only question what is relevant to the current User Story.

2b. Socratic Questioning

For each identified architectural concern, converge design decisions through questioning rather than giving direct answers. The goal is to have the user (or yourself) explicitly answer the following:

Boundary definition (corresponding to DDD Bounded Context):

• Do these two pieces of logic change at different frequencies?
• Do their failures need to be isolated? (A going down should not affect B)
• Do they have clear data ownership? (Who is the source of truth?)

Integration patterns:

• Does the caller need the result immediately? → Sync vs async
• If the downstream is down, should the upstream fail or continue? → Coupling level
• Does this operation need to be idempotent? (What happens on repeat calls?)

Observability (must question for every feature):

• After this feature launches, how do we know it's successful? → Define core metrics (conversion rate, retention, p95 latency, etc.)
• Are new tracking events needed? → User behavior events (impression/click/conversion funnel)
• Is A/B experiment validation needed? → When the approach is uncertain, use experiment data instead of guessing
• What are the SLA targets? → Quantified targets for availability, response time, error rate
• How do we detect problems? → Alert rules, dashboards, log keywords

Design constraints:

• What is the most critical non-functional requirement? (Latency? Throughput? Consistency? Availability?)
• Which are hard constraints (non-negotiable) and which are soft constraints (trade-offable)?
• What technologies is the team most experienced with? (Tech selection should consider team capability)

2c. Architecture Quality Principles

Designs must be checked against the following principles. These are also the criteria used by code-review to evaluate design quality.

Structural principles:

• High cohesion, low coupling: Clear module boundaries, each module does one thing, changes do not propagate
• Dependency direction: Stable modules do not depend on unstable modules, dependencies flow in one direction
• Vertical slicing: Organized by business domain rather than technical stack layers
• Core module separation: Core business logic is independent of frameworks and infrastructure, reusable across environments
• Ports & Adapters: Business logic is strictly isolated from external dependencies; all I/O is defined through Port interfaces, no direct dependency on concrete implementations

Robustness principles:

• Failure isolation: External dependencies going down have degradation/circuit-breaker/timeout strategies
• Idempotency: Write operations are safe for repeated calls
• Data consistency: Transaction boundaries for cross-table/cross-service operations are correct
• Input validation: User input is validated at system boundaries
• Built-in stubs: Every external dependency has a corresponding Stub/Mock; test environments do not require external services to be online

Evolvability principles:

• Extension points: Interfaces are pre-designed for known future changes
• Interface minimization: APIs expose only necessary information without leaking internal implementation
• Naming is design: Variable, function, and interface names must accurately convey intent; naming is not just about readability — it determines whether an AI Agent can correctly understand semantics
• Every rule has a Why: Documentation, comments, and commit messages explain "why," not just "what"; ADR, AC, and config items all need rationale

2d. Solution Divergence and Convergence

After gathering sufficient information through questioning:

1. Invoke superpowers:brainstorming to diverge and explore possible approaches
2. Reference methodology decision cards in references/ to evaluate approaches (see this skill's references/ directory)
3. Converge: Select an approach, record it as an ADR

ADR reasoning chain (must be included — conclusions alone are insufficient):

• Context: What problem is being faced + what constraints exist
• Options: What approaches were considered (at least 2)
• Trade-off: Pros and cons of each approach (not just the pros)
• Decision: What was chosen (or Pending — see below)
• Consequences: What costs were accepted

Pending ADR: When questions remain unanswered or information is insufficient for a decision, a Pending ADR must be created (Decision marked as Pending) rather than skipping it. A Pending ADR records the known Context and Options, and explicitly states "which questions must be answered before a decision can be made." This ensures uncertain decision points are explicitly tracked and not forgotten during subsequent design.

2e. Documentation Output

Output files:

• overview.md — Architecture overview (design goals table → Mermaid architecture diagram → component responsibilities table → sub-document navigation table)
• domain-model.md — Ubiquitous Language SSOT (business term <-> technical term mapping, essentially implementing DDD Ubiquitous Language)
• ADR records in overview.md or separate files

Documentation standards:

• Single file ≤ 400 lines — when exceeded, split into sub-documents; overview.md retains only the overview and sub-document navigation table
• Record review time using |Document Status at the beginning of the file
• All terminology must align with domain-model.md — consult it before writing; do not invent new concepts
• Use relative paths for cross-document references; add a three-column navigation table at the top of subsystem documents (submodule | document | description)
• Use <br/> for line breaks in Mermaid diagram nodes — \n is prohibited

Companion Skills: doc-writing (HWPR to mark human design decisions, AWOR for expanded detail), superpowers:brainstorming (solution divergence)

Step 3 — Dev/Test Environment Design (docs/deployment/local-dev.md)

What to write: L1/L2/L3 layered environment architecture, multi-worktree port isolation strategy, shared channel switching mechanism, hot-reload configuration. The goal is to build a fast-feedback TDD loop for AI Agents.

Documentation standards:

• local-dev.md has two sections: User Guide (commands and results, for developers) + Implementation Details (design rationale, for maintainers)
• Use make targets as the entry point for operations; bare commands are prohibited in documentation

Companion Skills:

• multi-worktree-dev (L1/L2/L3 layered design, port hash offset, shared channel exclusive switching, health probing)
• mock-engine (Mock infrastructure: start/stop mock services, load test data, create test scenarios)

Step 4 — Module Detail Design (docs/architecture/{service}/*.md)

What to write: Internal design of a single service/module — interface contracts, data flows, state machines, key algorithms.

Like Step 2, Step 4 also requires first identifying module-level design concerns, then converging through questioning.

4a. Module-Level Pattern Recognition

4b. Output After Questioning

After converging through questioning, produce a module design document that must include:

• Interface contract: Not just API path + request/response, but also error classification and idempotency description
• State machine (if applicable): State diagram + guard conditions + concurrency handling strategy
• Dependency direction: Who this module depends on, who depends on it, and whether the direction is correct (stable modules should not depend on unstable modules)
• Data flow: Source → transform → sink, including error/retry paths
• Observability design: Core metric definitions (SLA), new tracking events needed (event tracking), A/B experiment plan (if applicable), alert rules, dashboards

Documentation standards:

• Each file strictly ≤ 400 lines — this is a hard limit, not a suggestion
• When exceeding 400 lines, split: keep the overview in {service}/overview.md, move details to {service}/{topic}.md
• Layered nesting: system overview → service overview → module details; each layer is responsible only for its own granularity
• Each detail document references its parent service overview at the top, forming a navigable document tree

Companion Skill: doc-writing (HWPR/AWOR framework)

Step 5 — Layered Test Plan (docs/testing/)

What to write: A layered testing strategy generated from Step 1 (User Story acceptance criteria) + Step 2 (technical design) + Step 3 (environment design).

Document structure:

docs/testing/
├── strategy.md                 # Overview (≤400 lines): layer table, layering logic, mock architecture, traceability matrix, CI/CD
└── scenarios/                  # AC-level scenario matrices (strategy.md should not contain individual test cases)
    ├── ep1-<epic>.md           # By Epic (product/QA perspective)
    ├── tech-<module>.md        # By technical module (developer perspective)
    └── tech-nfr.md             # NFR degradation/fault tolerance

strategy.md must include:

1. 10-column test layer overview table (layer / case count / test goal / real dependencies / mock dependencies / real infra / mock infra / execution timing / duration / code location)
2. Layering logic table (what problem each layer solves + why the layer above is insufficient)
3. Mock infrastructure SSOT (directory structure + mock/real switching strategy per layer)
4. Requirements traceability matrix (User Story → test case IDs per layer)
5. Quality gate table (gate / checkpoint / criteria)

Scenario file AC-level traceability table: Fixed 8-column format AC Scenario | Smoke | L1 | L2-1 | L2-2 | L3-1 | L3-2 | L4, each cell filled with specific test case IDs.

Key principles:

• L3/L4 are black-box tests — test clients interact directly with the user interface; intercepting or mocking internal components at intermediate layers is prohibited
• Test scenario data is switched via make mock-scenario for controlled, repeatable execution

Quality standards (also the criteria used by code-review for evaluating tests; see testing-strategy skill for detailed layered strategy):

• Code without E2E tests must not merge to trunk — treated as a defect, not a "to-do"
• Each implemented User Story AC must have L3 E2E test coverage (AC describes user behavior and must be verified end-to-end; L3 uses real dependencies, not stubs)
• Each implemented API handler must have at least L2 integration tests (verifying interface contracts and data correctness)
• State changes, deletions, corrections, and other core flows must have boundary scenario coverage
• Test scenarios must cover all ACs in the User Stories (verified via traceability matrix: AC → L2 case ID + L3 scenario ID)
• Built-in stubs are a shift-left strategy: Every external dependency has a corresponding stub; L1/L2 do not require external services to be online. However, L3 E2E must use real dependencies to verify the complete chain

Companion Skills:

• testing-strategy (generate complete layered strategy by project type, includes references/engagement-example.md real-world example)
• mock-engine (mock infrastructure management: L1/L2 stub/mock service startup, test scenario data loading)
• multi-worktree-dev (test parallel safety design — multiple worktrees do not contend for shared channels)

Step 6 — CI/CD Deployment Documentation (docs/deployment/ci.md + cd.md)

What to write: CI pipeline quality gates, CD deployment strategy, K8s resource configuration, Ingress routing, secrets management.

Companion Skills:

Cross-Document Maintenance Rules

Superpowers Output Consolidation Rules

superpowers:writing-plans, superpowers:brainstorming, and other skills generate design documents or plans during a session. These documents must be consolidated into the docs/ system — they cannot exist only in session context or temporary files:

Consolidation timing: After superpowers plan is confirmed and before coding starts — consolidate documents first, then begin coding.

Documentation Review (docs/TODO.md)

TODO.md tracks all items pending review using three states: [ ] To Do / [/] In Progress / [x] Done

Review focus areas:

• Whether any file exceeds 400 lines (split if so)
• Whether terminology is consistent with domain-model.md (business term <-> technical term mapping)
• Whether User Stories contain technical details
• Whether cross-document reference paths are correct
• Whether User Story status is synchronized with code implementation
• Whether Product / Architecture interpretations of Phase breakdown are aligned
• Whether ADR includes a complete reasoning chain (Context → Options → Trade-off → Decision → Consequences)

Skill Toolchain Quick Reference

Methodology References (references/)

The questioning and solution evaluation in Steps 2/4 can reference the following methodology decision cards. Each card answers only three questions: when to use it, core concepts quick reference, and when NOT to use it.

The AI agent already has sufficient knowledge of these methodologies — the value of the decision cards is helping determine "should I use this for the current scenario."

Example Comparisons

Bad — Jumping to architecture diagram immediately after reading User Stories

Read User Stories → Directly write overview.md and draw Mermaid diagrams
→ No questioning, service boundaries drawn by intuition, ADR has no reasoning chain

Good — Pattern recognition → questioning → brainstorming → convergence

Read User Story → Identify "multi-tenant + distributed update" signals
→ Question: What level of data isolation between tenants? What's the catch-up strategy for offline nodes?
→ Brainstorm 3 approaches
→ Reference DDD + multi-tenant decision cards to evaluate
→ Select approach, write ADR (with complete reasoning chain)
→ Output overview.md + domain-model.md

Bad — User Story contains technical details

## US-GW-01 Message Routing
After a user sends a message, the Gateway calls the `resolve_intent()` method through
IntentResolveMiddleware, queries the PostgreSQL workspace table to get the agent_id,
then distributes it to the corresponding Sandbox Pod via Redis Pub/Sub.

Problem: AC should describe the results the user sees, not class names, databases, or middleware.

Good — User Story from purely user perspective

## US-GW-01 Message Routing
**Background**: Users need to maintain independent Agent context across different group chats.

**User Story**: As a team member, I want each group chat to have its own Agent context
so that the Agent remembers each group's context independently without cross-contamination.

**AC**:
- Given the user has had conversations in both Group A and Group B
- When the user asks a question in Group A
- Then the Agent responds based only on Group A's history, without mixing in Group B's content

Bad — Single file exceeds 400 lines with no splitting

docs/architecture/gateway.md  (800 lines, containing all subsystem details)

Good — Overview with navigation + layered sub-documents

docs/architecture/gateway/
├── overview.md          (≤400 lines, architecture diagram + sub-document navigation table)
├── intent-resolve.md    (≤400 lines)
├── thread-lane.md       (≤400 lines)
└── feishu-card.md       (≤400 lines)

Bad — Superpowers output stays in the session

After brainstorming is complete, directly say "ok, let's start coding"
→ Plan exists only in session context, lost in next session, cannot serve as test baseline

Good — Consolidate plan into docs/ before coding

Brainstorming complete → Write into docs/architecture/overview.md → commit → start coding