# Architect > Use when designing a new feature or system, making architecture decisions, writing technical design docs, or structuring project documentation. Triggers on "design", "architecture", "technical design", "ADR", "system decomposition", "how should I structure this", "设计方案", "架构设计", "技术方案", "文档体系", "写 User Story", "写文档". Also use when reviewing existing architecture docs or asking "where should I put… - **Type:** Skill - **Install:** `agentstack add skill-addxai-enterprise-harness-engineering-architect` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [addxai](https://agentstack.voostack.com/s/addxai) - **Installs:** 0 - **Category:** [Cloud & Infrastructure](https://agentstack.voostack.com/c/cloud-infrastructure) - **Latest version:** 0.1.0 - **License:** Apache-2.0 - **Upstream author:** [addxai](https://github.com/addxai) - **Source:** https://github.com/addxai/enterprise-harness-engineering/tree/main/skills/architect ## Install ```sh agentstack add skill-addxai-enterprise-harness-engineering-architect ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # 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 `/docs/product/prd.md`. Do not create standalone `product/` or `architecture/` directories at the project root. ``` docs/ # 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 `` 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 | Module Characteristic | Questioning Direction | |---------|-------------| | Exposes external APIs | Error classification (which are retryable / which are not), idempotency, versioning strategy | | Entities with lifecycles | State definitions, transition guard conditions, concurrent transitions, invalid transition handling | | Depends on external services | Timeout strategy, circuit-breaker thresholds, degradation plan, anti-corruption layer design | | High-concurrency reads/writes | Lock granularity, optimistic vs pessimistic, cache consistency | | Complex business rules | Will rules change? Configuration-driven vs hard-coded? How to handle rule conflicts? | | User-behavior-related features | What tracking events are needed? How is the funnel defined? Is A/B experimentation needed? | #### 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-.md # By Epic (product/QA perspective) ├── tech-.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**: | Task | Skill | |------|-------| | Write/review `.gitlab-ci.yml` | `gitlab-ci` | | Full deployment workflow for new apps (CI + K8s + Ingress + Vault + Crossplane) | `cicd-developer` | | ArgoCD GitOps sync/rollback/troubleshooting | `argocd` | | Set up CICD component stack for new clusters | `argocd-deploy` | | View/troubleshoot K8s cluster resources | `k8s-ops` | | Image registry Robot Account | `harbor` | | Vault secrets management | `vault-kv-manager` | | Runner selection and troubleshooting | `gitlab-instance-runners` | | Embedded repo CI Pipeline | `embed-ci-setup` | | Jenkins pipeline management | `jenkins` | --- ## Cross-Document Maintenance Rules | Operation | Must Also Update | |------|------------------| | Add/delete/rename document | `docs/TODO.md` | | Add User Story | `user-stories/README.md` index table | | Change architecture component responsibilities | `architecture/overview.md` mapping table | | Add domain terminology | `architecture/domain-model.md` | | Document + code changed together | Put in the same MR (use `gitlab-mr` skill) | ### 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: | Superpowers Output | Consolidation Target | |----------------|---------| | Feature plan / brainstorm conclusions | Corresponding Epic in `docs/product/user-stories/{service}.md` | | Overall technical plan / writing-plans output | `docs/architecture/overview.md` or corresponding service overview | | Module implementation plan | `docs/architecture/{service}/{topic}.md` | | Test plan | `docs/testing/strategy.md` or `services/{service}/` | | Dev environment design | `docs/deployment/local-dev.md` | **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 | Step | Task | Skill to Use | |------|------|-----------| | Step 1 | Write User Stories | `story-craftsman` | | Step 2 | Architecture design: solution divergence | `superpowers:brainstorming` | | Step 2 | Architecture design: write documentation | `doc-writing` | | Step 3 | Design dev/test environment layering | `multi-worktree-dev` | | Step 4 | Module detail design | `doc-writing` | | Step 5 | Generate layered test plan | `testing-strategy` + `multi-worktree-dev` | | Step 6 | CI Pipeline configuration | `gitlab-ci` / `embed-ci-setup` / `jenkins` | | Step 6 | CD full deployment workflow | `cicd-developer` | | Step 6 | K8s / images / secrets | `k8s-ops` + `vault-kv-manager` | | Throughout | Event tracking definition and management | event tracking platform | | Throughout | A/B experiments / Feature Flags | A/B experiment platform | | Throughout | SLA metric configuration | `sla-metric` | | Throughout | Monitoring dashboards / alerts | `grafana` + `prometheus` | | Throughout | Error monitoring | `sentry` + `sentry-onboarding` | | Throughout | Submit documentation + code together as MR | `gitlab-mr` | | Throughout | R&D process orchestration | `dev-workflow` | | Throughout | Create or update the Skill itself | `superpowers:writing-skills` | --- ## 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."** | Decision Card | Applicable Signals | |-------|---------| | `references/ddd.md` | Confused business terminology, unclear service boundaries, multi-team collaboration | | `references/event-driven.md` | Async processing, cross-service coordination, state change notifications | | `references/hexagonal.md` | Multiple external integrations, need for testability, preventing framework lock-in | | `references/state-machine.md` | Entities with lifecycles, complex state transition rules | | `references/integration-patterns.md` | Third-party API integration, unreliable external systems | | `references/multi-tenant.md` | OEM / white-label / multi-tenant scenarios | --- ## 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 contai … ## Source & license This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [addxai](https://github.com/addxai) - **Source:** [addxai/enterprise-harness-engineering](https://github.com/addxai/enterprise-harness-engineering) - **License:** Apache-2.0 Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-addxai-enterprise-harness-engineering-architect - Seller: https://agentstack.voostack.com/s/addxai - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.