Docs

# Arch — Rust Project Orchestrator

> Orchestrate Rust projects from requirements through tested implementation with parallel review teammates for quality, security, and fuzzing.

`/orc:arch` combines architecture design with full implementation for pure Rust projects. It adapts the [Prototype](./007-prototype-skill.md) pattern — sequential steps with checkpoint gates — but adds Rust-specific tooling: `rust-architect` patterns drive design, `rust-expert` knowledge guides implementation, and a 4-agent parallel review wave runs `/rust-skills`, security audit, `/cargo-fuzz`, and clippy. This page covers:

- [How it works](#how-it-works) — the 7-step workflow at a glance
- [Run an arch session](#run-an-arch-session) — invocation, flags, and what to expect
- [Phases in detail](#phases-in-detail) — what each step produces
- [The review wave](#the-review-wave) — how Step 5 uses a scoped team for parallel skill invocation
- [Asset wiring](#asset-wiring) — how 6 external skills and agents are connected
- [Checkpoint gates](#checkpoint-gates) — where execution pauses for approval
- [State management](#state-management) — session persistence and resumption
- [How arch compares to prototype](#how-arch-compares-to-prototype) — what's different and why
- [Troubleshooting](#troubleshooting)

**Tip:** Looking for generic full-stack prototyping? See [Prototype Skill](./007-prototype-skill.md). For planning without execution, see [Planning Pipeline](./002-planning-pipeline-deep-dive.md).

![Arch workflow diagram](./diagrams/skill-arch.png)

***

## How it works

Arch follows 7 sequential steps across 3 phases. Each step writes an output file to `.arch/` before the next begins.

```
Phase 1: Design
  Step 1  Requirements gathering (interactive Q&A, 8 questions)
  Step 2  Architecture design (data model + module structure)
  ─────── CHECKPOINT 1: approve architecture before code ───────

Phase 2: Implementation
  Step 3  Core implementation (code + cargo build)
  Step 4  Test suite (unit + integration + cargo test)
  Step 5  Parallel review wave (4 teammates in a team)
  ─────── CHECKPOINT 2: approve reviews before fixes ───────

Phase 3: Fixes & Delivery
  Step 6  Fix critical findings
  Step 7  Documentation & handoff
```

Steps 1-4 and 6-7 use standalone Tasks — one agent per step, no team overhead. Step 5 is the only step that creates a team, spawning 4 reviewers in parallel with access to specialized skills.

***

## Run an arch session

```
/orc:arch "CLI tool that parses PCAP files and extracts DNS queries" --crate bin --async tokio
```

| Flag | Default | Options |
| :--- | :------ | :------ |
| `--crate` | auto-detect from `Cargo.toml` | `bin`, `lib`, `workspace` |
| `--async` | auto-detect from deps | `tokio`, `async-std`, `none` |

The feature description (everything before the flags) becomes `$ARGUMENTS` — referenced in every agent prompt throughout the workflow.

**What happens next:**

1. Pre-flight checks for an existing session (resume or archive)
2. `.arch/` directory and `state.json` initialized
3. Crate type and async runtime detected from `Cargo.toml`
4. Step 1 begins — you'll be asked 8 requirements questions, one at a time

***

## Phases in detail

### Phase 1: Design (Steps 1-2)

**Step 1 — Requirements gathering.** Interactive Q&A via `AskUserQuestion`, one question at a time:

1. Problem statement
2. Acceptance criteria
3. Scope boundaries
4. Crate type (bin/lib/workspace)
5. Key crates (tokio, axum, serde, etc.)
6. Async runtime
7. Error strategy (thiserror/anyhow/custom)
8. Constraints (no_std, MSRV, platforms, performance)

Writes `.arch/01-requirements.md`.

**Step 2 — Architecture design.** A standalone `general-purpose` agent designs both the data model and module architecture in a single document. The agent reads `~/.claude/skills/rust-architect/SKILL.md` from disk as reference material for type design principles, ownership strategies, and NEVER_DO patterns.

Deliverables cover two areas:

| Data Model | Module Architecture |
| :--------- | :------------------ |
| Core structs and enums with derives | Crate structure (lib/bin split) |
| Trait design and relationships | Module tree with visibility boundaries |
| Error types with thiserror | Public API surface |
| Newtype wrappers for domain types | Key function signatures |
| Serde strategy | Data flow and error propagation |
| Ownership strategy (own vs borrow, Cow, Arc) | Async design, config, logging |

Writes `.arch/02-architecture.md`.

### Phase 2: Implementation (Steps 3-5)

**Step 3 — Core implementation.** A standalone `general-purpose` agent implements the project. The prompt embeds `rust-expert` focus areas (ownership, error handling, pattern matching, traits, concurrency, memory efficiency) and a quality checklist. The agent also reads `~/.claude/skills/rust-skills/SKILL.md` from disk — 179 coding rules across 14 categories.

Writes code files + `.arch/03-implementation.md`.

**Step 4 — Test suite.** A standalone `general-purpose` agent writes unit tests (`#[cfg(test)]` modules), integration tests (`tests/` directory), and runs `cargo test`. Conditionally reads `~/.claude/skills/property-based-testing/SKILL.md` if proptest is relevant.

Writes test files + `.arch/04-tests.md`.

**Step 5 — Parallel review wave.** The only team-based step. See [The review wave](#the-review-wave) for the full breakdown.

Writes `.arch/05-review.md` (consolidated from 4 sub-reviews).

### Phase 3: Fixes & Delivery (Steps 6-7)

**Step 6 — Fix critical issues.** If the review wave found Critical or High findings, a standalone `general-purpose` agent fixes them, then re-runs `cargo test` and `cargo clippy`. If no critical findings, writes a brief "No critical issues to fix" note.

Writes `.arch/06-fixes.md`.

**Step 7 — Documentation.** A standalone `general-purpose` agent writes project documentation: README.md with quickstart and architecture overview, rustdoc verification, and NEVER_DO rules derived from `rust-architect` patterns.

Writes `.arch/07-documentation.md`.

***

## The review wave

Step 5 is where arch diverges most from the prototype pattern. Instead of independent background tasks, it creates a scoped team with 4 named teammates that can invoke specialized skills.

### Why a team is required

Standalone Tasks (agents without `team_name`) **cannot call the Skill tool**. Only teammates spawned with a `team_name` have access to invoke skills. Since the review wave needs `/rust-skills`, `/cargo-fuzz`, and `/zeroize-audit`, a team is mandatory.

### How it executes

```
TeamCreate("arch-review")
  ↓
TaskCreate x4 (upfront, before spawning)
  ↓
Single message spawns 4 teammates (all run_in_background: true):
  ├── w1-rust-review  →  Skill("rust-skills") — 179 rules
  ├── w1-security     →  Skill("zeroize-audit") if crypto
  ├── w1-fuzz         →  Skill("cargo-fuzz") — fuzz targets
  └── w1-clippy       →  cargo clippy + fmt + build
  ↓
Wait for all 4 (TaskList verification)
  ↓
Consolidate → .arch/05-review.md
  ↓
TeamDelete("arch-review")
```

### Teammate details

| Teammate | Model | Skill invoked | Output file | Focus |
| :------- | :---- | :------------ | :---------- | :---- |
| **w1-rust-review** | sonnet | `/rust-skills` | `05a-rust-review.md` | 179 Rust rules: ownership, error handling, API design, async |
| **w1-security** | sonnet | `/zeroize-audit` (conditional) | `05b-security-review.md` | Unsafe blocks, unwrap, integer overflow, path traversal, secrets |
| **w1-fuzz** | sonnet | `/cargo-fuzz` | `05c-fuzzing.md` | Fuzz targets for parser/input functions |
| **w1-clippy** | sonnet | (none — cargo commands) | `05d-lint.md` | clippy warnings, fmt check, build verification |

Each teammate follows the TaskUpdate protocol: claim task → do work → complete task → SendMessage to team lead with summary.

### Team lifecycle

The team exists **only during Step 5**. It is created after checkpoint 1 approval and deleted before checkpoint 2. No checkpoint spans the team's lifecycle — this prevents orphaned teams if the session is paused.

***

## Asset wiring

Arch references 6 external skills and agents. They connect in two distinct patterns:

### Read from disk (reference material)

Agents read skill files as context — like reading documentation before starting work. No Skill tool invocation.

| Asset | Location | Lines | Used in | What it provides |
| :---- | :------- | ----: | :------ | :--------------- |
| **rust-architect** | `~/.claude/skills/rust-architect/SKILL.md` | 3,332 | Steps 2, 7 | Type design principles, NEVER_DO patterns, ownership strategies, README templates |
| **rust-expert** | `~/.claude/agents/rust-expert.md` | 57 | Step 3 | Focus areas and quality checklist (embedded directly in prompt) |
| **rust-skills** | `~/.claude/skills/rust-skills/SKILL.md` | 335 | Step 3 | 179 coding rules across 14 categories |
| **property-based-testing** | `~/.claude/skills/property-based-testing/SKILL.md` | 123 | Step 4 | Proptest patterns (conditional — only if relevant) |

### Skill tool invocation (active execution)

Teammates invoke skills via the `Skill` tool — the skill runs its full workflow inside the teammate's context.

| Asset | Location | Lines | Used in | What it provides |
| :---- | :------- | ----: | :------ | :--------------- |
| **rust-skills** | `~/.claude/skills/rust-skills/SKILL.md` | 335 | Step 5 (w1-rust-review) | Formal code review against 179 rules |
| **cargo-fuzz** | `~/.claude/skills/cargo-fuzz/SKILL.md` | 454 | Step 5 (w1-fuzz) | Fuzz target setup with libFuzzer backend |
| **zeroize-audit** | `~/.claude/skills/zeroize-audit/SKILL.md` | 371 | Step 5 (w1-security) | Crypto zeroization analysis (conditional) |

**Warning:** `rust-skills` appears in both patterns — read from disk in Step 3 (implementation reference) and invoked via Skill tool in Step 5 (formal review). The read-from-disk pattern works for standalone tasks; the Skill invocation pattern requires a teammate.

***

## Checkpoint gates

Arch has two mandatory approval points. Execution halts until you explicitly choose to continue.

### Checkpoint 1 — After architecture, before code

```
Architecture design complete. Please review:
- .arch/02-architecture.md

1. Approve — proceed to implementation
2. Request changes — revise and re-checkpoint
3. Pause — save progress and stop
```

**Why it exists:** Catching a bad data model or module structure after Step 2 is cheap. Catching it after Steps 3-5 have written implementation code and run reviews is expensive.

### Checkpoint 2 — After reviews, before fixes

```
Review wave complete:
- Rust idiom review: X findings (N critical, M high)
- Security review: X findings (N critical, M high)
- Fuzzing: X targets created
- Clippy/fmt: PASS/FAIL

1. Approve — proceed to fix critical issues and finalize
2. Request changes — specific direction
3. Pause — save and stop
```

**Why it exists:** The review wave surfaces findings across 4 dimensions. You decide which findings warrant fixes and which are acceptable — before the fix agent starts changing code.

**Warning:** Selecting "Pause" at either checkpoint saves progress to `state.json`. Resume later with `/orc:arch` — the skill detects the in-progress session.

***

## State management

### Session files

All state lives in `.arch/` at the project root:

| File | Purpose |
| :--- | :------ |
| `state.json` | Progress tracker — current step, completed steps, crate config |
| `01-requirements.md` | Step 1 output |
| `02-architecture.md` | Step 2 output (data model + module architecture) |
| `03-implementation.md` | Step 3 output (implementation summary) |
| `04-tests.md` | Step 4 output (test summary + cargo test results) |
| `05-review.md` | Step 5 output (consolidated from 4 sub-reviews) |
| `05a-rust-review.md` | Sub-review: rust-skills findings |
| `05b-security-review.md` | Sub-review: security findings |
| `05c-fuzzing.md` | Sub-review: fuzz target setup |
| `05d-lint.md` | Sub-review: clippy + fmt results |
| `06-fixes.md` | Step 6 output (fix summary + test results) |
| `07-documentation.md` | Step 7 output (docs written summary) |

### state.json structure

```json
{
  "feature": "CLI tool that parses PCAP files",
  "status": "in_progress",
  "crate_type": "bin",
  "async_runtime": "tokio",
  "current_step": 3,
  "current_phase": 2,
  "completed_steps": [1, 2],
  "files_created": ["01-requirements.md", "02-architecture.md"]
}
```

### Resuming a session

If `.arch/state.json` exists when you invoke `/orc:arch`:

- **In progress:** You're offered Resume (skip to `current_step`, read prior outputs from disk) or Start Fresh (archives to `.arch-archived-{date}/`)
- **Complete:** You're offered Archive and Start Fresh

### Why file-driven state matters

Agents read prior step outputs from `.arch/*.md` files, not from the conversation context window. This means:

- Sessions survive context exhaustion and `/orc:half-clone`
- Each agent gets exactly the context it needs (no bloated prompts)
- The audit trail is human-readable on disk

***

## Agents used

| Step | Agent | Mode | Model | What it does |
| :--- | :---- | :--- | :---- | :----------- |
| 1 | (orchestrator) | Interactive | inherit | AskUserQuestion loop, writes requirements |
| 2 | `general-purpose` | Standalone task | opus | Architecture + data model design |
| 3 | `general-purpose` | Standalone task | opus | Core implementation |
| 4 | `general-purpose` | Standalone task | opus | Test suite + cargo test |
| 5a | `general-purpose` | Teammate (arch-review) | sonnet | Rust idiom review via `/rust-skills` |
| 5b | `general-purpose` | Teammate (arch-review) | sonnet | Security review + `/zeroize-audit` |
| 5c | `general-purpose` | Teammate (arch-review) | sonnet | Fuzzing setup via `/cargo-fuzz` |
| 5d | `general-purpose` | Teammate (arch-review) | sonnet | clippy + fmt + build |
| 6 | `general-purpose` | Standalone task | opus | Fix critical findings |
| 7 | `general-purpose` | Standalone task | sonnet | Documentation + NEVER_DO rules |

Design and implementation steps (2-4, 6) use **opus** for deeper reasoning. Review and documentation steps (5a-d, 7) use **sonnet** for speed — they execute focused, well-scoped tasks.

***

## How arch compares to prototype

|  | Arch | Prototype |
| :--- | :--- | :--- |
| **Purpose** | Plan + build a Rust project | Plan + build any full-stack feature |
| **Steps** | 7 | 9 |
| **Frontend** | None (pure Rust) | Yes (with `/orc:vibe-code` integration) |
| **Deployment** | None | Yes (CI/CD, infrastructure, runbooks) |
| **Performance review** | None (rely on Rust compiler) | Yes (`orc:performance-engineer`) |
| **Fuzzing** | Yes (`/cargo-fuzz` in review wave) | No |
| **Security review** | Rust-specific (unsafe, unwrap, `/zeroize-audit`) | Generic (OWASP, SQL injection, XSS) |
| **Lint gate** | Yes (cargo clippy + fmt + build) | No |
| **Team usage** | Step 5 only (`arch-review`) | None (standalone tasks only) |
| **Skill invocations** | 6 assets, 2 wiring patterns | 1 conditional (vibe-code) |
| **Output dir** | `.arch/` (7 files + 4 sub-reviews) | `.prototype/` (9 flat files) |
| **Checkpoints** | After arch, after reviews | After arch, after testing |
| **Requirements Q&A** | 8 questions (Rust-specific) | 6 questions (generic) |

**When to use which:**

- **Arch** — You're building a Rust project (CLI, library, service) and want architecture-through-tested-code with Rust-specific quality gates
- **Prototype** — You're building a multi-stack feature (web, Rust, Solidity) and want the full lifecycle including frontend and deployment
- **Spec + Swarm** — Complex multi-phase projects that need planning separate from execution

***

## Troubleshooting

| Issue | Cause | Solution |
| :---- | :---- | :------- |
| Skill not found | Plugin not loaded | Run `/orc:install` to verify plugin registration |
| Teammate can't invoke skill | Missing team_name in Task | Verify Step 5 uses `team_name="arch-review"` |
| Review wave hangs | One teammate stuck | Check `TaskList` for in_progress tasks; resume or retry |
| Checkpoint stuck | Waiting for input | Select option 1/2/3 — arch won't proceed without choice |
| Resume offers wrong step | Stale state.json | Delete `.arch/state.json` and restart |
| rust-architect too large | 3,332 lines in context | Agent reads selectively — not all content loaded at once |
| No Cargo.toml found | Wrong directory | Run from project root where `Cargo.toml` lives |

## See also

- [Prototype Skill](./007-prototype-skill.md) — Generic full-stack feature orchestrator
- [Skill Reference](./001-orc-skill-reference.md) — Full command listing
- [Implementation Skills](./003-implementation.md) — How `/orc:swarm` executes plans
- [Planning Pipeline](./002-planning-pipeline-deep-dive.md) — How `/orc:spec` works