# Sa Architecture Design

> SA design-mode procedure for producing docs/architecture.md, ADRs, and docs/instrumentation-contract.md from a signed-off SRS. Use when Solution Architect is dispatched in `design` mode after SRS sign-off to create or revise greenfield architecture, choose dependencies through the approval gate, define C4 C1-C3, API/data/async/cross-cutting sections, and establish format-boundary and gate-field c…

- **Type:** Skill
- **Install:** `agentstack add skill-evolplus-talos-sa-architecture-design`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [evolplus](https://agentstack.voostack.com/s/evolplus)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [evolplus](https://github.com/evolplus)
- **Source:** https://github.com/evolplus/talos/tree/main/skills/sa-architecture-design

## Install

```sh
agentstack add skill-evolplus-talos-sa-architecture-design
```

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

## About

# SA Architecture Design

## Use

Use this skill when SA is dispatched in `design` mode. Do not use for brownfield extraction or external-integration adequacy; those have separate skills.

## Inputs

- `docs/SRS.md` at `Status: Signed-off`
- `docs/user-stories/`, `docs/frs/`, `docs/external-integrations/`
- Existing `docs/architecture.md` and `docs/decisions/` when revising
- SRS headers `Designated Dependency Approver`, `Frontend-Framework`, `Backend-Track`, `Backend-Framework`
- `solution-defaults`, `third-party-dependency-evaluation`, `adr-author`, `c4-author`, `data-lifecycle-contracts`, `format-boundary-contracts`

## Outputs

1. `docs/architecture.md` using `agents/_templates/_artifacts/architecture-template.md`.
2. ADRs under `docs/decisions/` for every non-trivial choice.
3. `docs/instrumentation-contract.md` for any SRS with a UI surface.
4. `docs/open-issues.md` entries for architectural gaps that cannot be resolved from the SRS.
5. Worktree `plan-update.json` with `track: "sa"`.

## Procedure

1. Verify SRS is signed off. Halt if not.
2. Read the SRS, every linked US/FR, external integration files, and prior ADRs.
3. Build C4 levels:
   - C1 Context: system boundary, actors, external systems.
   - C2 Containers: runnable/deployable units, datastores, queues, clients.
   - C3 Components: required for non-trivial containers; each component row carries `Linked FRs`.
   - Do not author C4 Code; Dev roles own code-level artifacts.
4. Fill architecture sections:
   - §3.5 Data Models when persistent state exists.
   - §3.6 API Inventory for REST/gRPC/GraphQL/WebSocket/events/queues, linking contract files.
   - §3.7 Dependency & Call Graph for cross-container calls, internal packages, and production dependencies.
   - §3.8 Async Workflows for event/queue flows.
   - Cross-cutting concerns, failure modes, NFR posture, open risks, and observability.
5. Apply data-contract skills:
   - Use `format-boundary-contracts` for fields crossing incompatible formats.
   - Use `data-lifecycle-contracts` for gate fields read by one component and written by another.
6. For UI-bearing SRSs, author `docs/instrumentation-contract.md` declaring stable test IDs/accessibility identifiers for FE Dev and QA.
7. For every non-trivial architectural choice, author an ADR.
8. For new third-party dependencies:
   - Check `solution-defaults` first.
   - Reuse prior ADR approvals when valid.
   - Otherwise evaluate 2-4 options with `third-party-dependency-evaluation`, halt with `NEEDS_CONTEXT`, and wait for the Designated Dependency Approver.
   - Do not include the dependency in accepted architecture until approval is recorded.
9. Run a self-containment check on produced artifacts.
10. Commit changes, then emit `plan-update.json`.

## Quality Bar

The architecture must let TL break down tasks and Devs implement without reverse-engineering intent. Every SRS requirement must have an architectural home, or a documented open issue.

## Hard Rules

- Never propose architecture before SRS sign-off.
- Never write source code, tests, API contracts, or plan files.
- Never weaken SRS Security & Compliance.
- Never approve dependencies yourself.
- Never skip `docs/instrumentation-contract.md` for UI-bearing SRSs.
- Never omit architecture §6 when format-boundary or gate-field conditions are present.
- Commit before signaling done.

## Source & license

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

- **Author:** [evolplus](https://github.com/evolplus)
- **Source:** [evolplus/talos](https://github.com/evolplus/talos)
- **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:** yes
- **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-evolplus-talos-sa-architecture-design
- Seller: https://agentstack.voostack.com/s/evolplus
- 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%.