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