# Architect System

> Designs technical blueprints — tech stack selection, database schema, API design, file structure, and deployment plan for a defined product or feature. Produces `architecture/system-architecture.md`. Not for unclear requirements (use discover) or task decomposition (use breakdown-tasks). For user journey mapping, see map-user-flow. For code quality after building, see review-work.

- **Type:** Skill
- **Install:** `agentstack add skill-hungv47-meta-skills-architect-system`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [hungv47](https://agentstack.voostack.com/s/hungv47)
- **Installs:** 0
- **Category:** [Databases](https://agentstack.voostack.com/c/databases)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [hungv47](https://github.com/hungv47)
- **Source:** https://github.com/hungv47/meta-skills/tree/main/forsvn-dev/skills/product/architect-system
- **Website:** https://skills.forsvn.com/

## Install

```sh
agentstack add skill-hungv47-meta-skills-architect-system
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# System Architecture Designer — Orchestrator

Transforms product specifications into a technical blueprint covering stack, schema, APIs, and deployment. Capability metadata (route triggers, prerequisites, load map, artifact contract) lives in [`routing.yaml`](routing.yaml). Methodology and history: [`references/playbook.md`](references/playbook.md).

**Core question:** Will this still work at 10x scale with 10x team?

## When To Use

- Defined product or feature needing a technical blueprint (stack, schema, API, infra, deployment).
- Major scale shift (10x growth) or migration to new core infrastructure.
- Greenfield, brownfield (extending existing system), or migration (replacing existing).
- Architecture re-run after significant spec change.

## When NOT To Use

- Requirements fuzzy → `/discover`.
- Code-level cleanup → `/clean-code`.
- Task decomposition from existing architecture → `/breakdown-tasks`.
- UI/flow mapping → `/map-user-flow`.
- Existing code has the same operational mechanics duplicated across 2+ callers → `/extract-service`.

## Before Starting

| Artifact | Source | Required? |
|---|---|---|
| `research/product-context.md` | research-icp | Recommended — product dims, voice, constraints |
| `docs/forsvn/artifacts/meta/specs/*.md` | spec/PRD | Recommended — feature scope |
| `docs/forsvn/artifacts/product/flow/*.md` | map-user-flow | Recommended — user types + flows |
| `docs/forsvn/experience/technical.md` | (any skill) | Optional — stack history + constraints |
| `.forsvn/index/manifest.json` | system | Optional — prior runs + downstream task state |

Apply [`references/_shared/before-starting-check.md`](references/_shared/before-starting-check.md). `--fast` forces single-agent regardless of scope; All 8 Critical Gates fire in every mode.

## Pre-Dispatch

Run [`references/_shared/pre-dispatch-protocol.md`](references/_shared/pre-dispatch-protocol.md). Needed dimensions: spec/PRD reference, scale targets (users / RPS / data), constraints (budget / team skills / latency / compliance), deployment context (greenfield / brownfield / migration). Full read-order + interview prompts: [`references/procedures/pre-dispatch.md`](references/procedures/pre-dispatch.md).

## Critical Gates — all 8 fire in every mode

Before delivering, the critic-agent verifies ALL of these pass:

- [ ] Every tech choice has a rationale (not just "it's popular").
- [ ] API endpoints exist for every user-facing feature.
- [ ] Database schema covers all entities mentioned in product spec.
- [ ] Deployment section includes complete env var list.
- [ ] File structure matches chosen framework conventions.
- [ ] Auth model covers all user roles and permission levels.
- [ ] At least one architectural trade-off is documented with alternatives considered.
- [ ] Every external dependency is classified (in-process / local-substitutable / remote-owned / true-external) per [`references/dependency-classification.md`](references/dependency-classification.md).

Failure → critic identifies which agent must fix it; orchestrator re-dispatches with specific feedback. Revision-loop handling + 2-round limit: [`references/anti-patterns.md`](references/anti-patterns.md) § "Revision loop".

## Artifact Contract

- **Path:** `architecture/system-architecture.md` (active); prior runs renamed `system-architecture.v[N].md`.
- **Lifecycle:** `canonical` — top-level folder; edited in place by humans + future runs; team's authoritative architecture record.
- **Frontmatter:** `skill`, `version`, `date`, `status`, `stack` (=product), `review_surface` (=html — the forsvn-preview review module renders the themed preview while `decision_state: pending`), `decision_state`, `review_tool`, `reviewed_at`, `reviewer`, `lifecycle`, `produced_by`, `provenance`. v2 schema in [`references/_shared/artifact-contract-template.md`](references/_shared/artifact-contract-template.md).
- **Required sections:** 12 sections (§1 Overview → §12 Security Review) + §12a STRIDE + §12b OWASP + §12d false-positive log. §12c LLM/AI Security conditional. Not Included + Open Questions when applicable.
- **Consumed by:** `breakdown-tasks`, `review-work`, `clean-code`, `forsvn`, operator.

Full template + section content + version-increment rule: [`references/report-template.md`](references/report-template.md).

## Chain Position

Previous: `/discover` or `/map-user-flow` (optional, both sharpen output) | Next: `/breakdown-tasks` (decomposes into tasks). Cross-stack: reads `docs/forsvn/artifacts/meta/sketches/prioritize-*.md`.

Re-run triggers: product spec changes significantly, scale requirements change (10x growth), migrating core infrastructure, adding major new integrations.

## Dispatch

Multi-agent default (7 agents: stack-selection · infrastructure · schema · api · integration · scaling · critic). Single-agent fallback when mode-resolver downgrades to `fast`. Full execution layers, dispatch protocol, routing logic, and fallback steps: [`references/procedures/dispatch-mechanics.md`](references/procedures/dispatch-mechanics.md). Per-agent role + file paths: [`references/agent-manifest.md`](references/agent-manifest.md).
Session execution profile (single-vs-multi): inherit per `references/_shared/execution-policy.md`.

## Anti-Patterns

Read [`references/anti-patterns.md`](references/anti-patterns.md) at every doubt — premature microservices, schema without queries, auth-as-afterthought, missing error states, "we'll add monitoring later," over-engineering for scale. Revision-loop handling + when-to-defer-instead-of-architecting also live there.

## Durable Rules (protected)

## Completion Status

- **DONE** — full architecture written (stack, schema, API, infra, scaling), critic PASS, open questions listed.
- **DONE_WITH_CONCERNS** — written with scaling assumptions or stack tradeoffs flagged in Open Questions.
- **BLOCKED** — requirements contradict (budget vs scale, latency vs cost); needs user trade-off decision.
- **NEEDS_CONTEXT** — spec, prioritized initiatives, or user-flows missing; recommend `/discover`, `/prioritize`, or `/map-user-flow` first.

## Next Step

After delivery: the operator reviews + sets the decision via the forsvn-preview review module (`/forsvn:review`), `decision_state`. Approved → dispatch `/breakdown-tasks` to decompose into tasks. Suggested edits → re-run with feedback. Denied → loop back to `/discover` or `/map-user-flow`.

## References

- [`references/procedures/{pre-dispatch, dispatch-mechanics}.md`](references/procedures/)
- [`references/playbook.md`](references/playbook.md), [`references/agent-manifest.md`](references/agent-manifest.md), [`references/anti-patterns.md`](references/anti-patterns.md), [`references/report-template.md`](references/report-template.md)
- [`references/_shared/{pre-dispatch-protocol, before-starting-check, mode-resolver}.md`](references/_shared/)
- [`references/pre-dispatch-prompts.md`](references/pre-dispatch-prompts.md), [`dependency-classification.md`](references/dependency-classification.md)
- Pattern catalogs (agent-consumed): [`tech-stack-patterns.md`](references/tech-stack-patterns.md), [`tech-stack-matrix.md`](references/tech-stack-matrix.md), [`file-structure-patterns.md`](references/file-structure-patterns.md), [`database-patterns.md`](references/database-patterns.md), [`api-patterns.md`](references/api-patterns.md), [`auth-patterns.md`](references/auth-patterns.md), [`deployment-patterns.md`](references/deployment-patterns.md), [`failure-modes.md`](references/failure-modes.md), [`interaction-edge-cases.md`](references/interaction-edge-cases.md), [`security-patterns.md`](references/security-patterns.md)
- Walkthrough: [`references/examples/saas-invoicing-walkthrough.md`](references/examples/saas-invoicing-walkthrough.md)

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [hungv47](https://github.com/hungv47)
- **Source:** [hungv47/meta-skills](https://github.com/hungv47/meta-skills)
- **License:** MIT
- **Homepage:** https://skills.forsvn.com/

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-hungv47-meta-skills-architect-system
- Seller: https://agentstack.voostack.com/s/hungv47
- 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%.