# Arch > Orchestrated Rust project architect — requirements to tested implementation with parallel teammates for design, coding, review, and fuzzing - **Type:** Skill - **Install:** `agentstack add skill-qgolem-orc-arch` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [qGolem](https://agentstack.voostack.com/s/qgolem) - **Installs:** 0 - **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [qGolem](https://github.com/qGolem) - **Source:** https://github.com/qGolem/orc/tree/main/skills/arch ## Install ```sh agentstack add skill-qgolem-orc-arch ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # Arch — Rust Project Orchestrator Multi-phase Rust project architect. Gathers requirements interactively, designs architecture using rust-architect patterns, implements with rust-expert knowledge, then spawns a parallel review wave with rust-skills + cargo-fuzz. No frontend — pure Rust. **Skill dependencies:** This skill expects rust-architect, rust-skills, cargo-fuzz, property-based-testing, and zeroize-audit installed at `.claude/skills/`, and rust-expert at `.claude/agents/`. Install via `/orc:install`. If installed globally at `~/.claude/` instead, adjust paths accordingly. ## CRITICAL RULES 1. **Execute steps in order.** Do NOT skip, reorder, or merge steps. 2. **Write output files.** Each step produces its file in `.arch/` before the next begins. 3. **Stop at checkpoints.** PHASE CHECKPOINTs require explicit user approval via AskUserQuestion. 4. **Halt on failure.** If any step fails, STOP and present the error. 5. **Never enter plan mode.** This skill IS the plan — execute it. 6. **No frontend.** Skip any UI/browser/component work. Pure Rust. 7. **Team only for Step 5.** TeamCreate/TeamDelete scoped to the review wave only. ## Pre-flight ### Check for existing session If `.arch/state.json` exists with `status: "in_progress"`: ``` Found an in-progress arch session: Feature: [name] Current step: [step] ``` Ask via AskUserQuestion: - **Resume** — continue from saved step - **Start fresh** — archive to `.arch-archived-{date}/`, create new `.arch/` ### Initialize ```bash mkdir -p .arch ``` Write `.arch/state.json`: ```json { "feature": "$ARGUMENTS", "status": "in_progress", "crate_type": "auto-detect", "async_runtime": "auto-detect", "current_step": 1, "current_phase": 1, "completed_steps": [], "files_created": [] } ``` Detect from project: - `Cargo.toml` → crate type (bin/lib/workspace from `[package]` or `[workspace]`) - `tokio` in deps → async runtime - Parse `--crate` and `--async` flags from `$ARGUMENTS` as overrides --- ## Phase 1: Design (Steps 1-2) — Interactive ### Step 1: Requirements Gathering Ask ONE question at a time via AskUserQuestion: 1. **Problem**: "What does this project/feature do? What problem does it solve?" 2. **Acceptance criteria**: "What are the key acceptance criteria? When is it 'done'?" 3. **Scope boundaries**: "What is explicitly OUT of scope?" 4. **Crate type**: "Binary, library, or workspace? Single crate or multi-crate?" 5. **Key crates**: "Core dependencies? (e.g., tokio, axum, serde, clap, sqlx, tonic)" 6. **Async**: "Async runtime needed? (tokio/async-std/none)" 7. **Error strategy**: "Error handling approach? (thiserror for lib errors, anyhow for bins, custom)" 8. **Constraints**: "Any constraints? (no_std, MSRV, target platforms, performance targets)" Write `.arch/01-requirements.md`. Update state: step → 2. ### Step 2: Architecture Design Read `.arch/01-requirements.md`. Spawn architecture agent (standalone Task — no team): ``` Task( subagent_type="general-purpose", model="opus", prompt="You are a Rust architect designing a complete project architecture. ## Requirements [Insert full contents of .arch/01-requirements.md] ## Reference Material Read .claude/skills/rust-architect/SKILL.md from disk. Use it as reference for: - Type design principles (newtype wrappers, #[non_exhaustive], #[must_use]) - Ownership strategies (when to own vs borrow, Cow, Arc for shared state) - NEVER_DO patterns (things to avoid in Rust architecture) - Error handling patterns (thiserror vs anyhow, error chains) Do NOT execute it as a skill — read it as reference material only. ## Deliverables Write a single comprehensive architecture document covering: ### Data Model 1. Core structs and enums — with derive macros, field types, visibility 2. Trait design — key traits, methods, relationships 3. Error types — custom error enum with thiserror, From impls 4. Newtype wrappers — for domain types (IDs, validated strings, bounded numbers) 5. Serde strategy — derives, custom serializers, rename conventions 6. Ownership strategy — which types own data vs borrow, Cow usage, Arc for shared state ### Module Architecture 1. Crate structure — lib/bin split, workspace layout if multi-crate 2. Module tree — mod hierarchy, pub/pub(crate) boundaries 3. Public API surface — what's exported, what's internal 4. Key function signatures — with full type signatures 5. Data flow — how data moves through the system (ownership transfers, borrows) 6. Error propagation — ? operator chains, where errors are created vs handled 7. Async design — if async: task spawning, channels, shared state (Arc>) 8. Configuration — config crate, env vars, CLI args (clap) 9. Logging — tracing crate setup, span hierarchy If CLI: command structure (clap subcommands, args, flags) If server: endpoint routing, middleware stack, request lifecycle If library: public trait surface, feature flags, optional deps Write your complete design to .arch/02-architecture.md" ) ``` Wait for completion. Update state: step → checkpoint-1. --- ## PHASE CHECKPOINT 1 — User Approval Required Display summary of `.arch/02-architecture.md`. Ask via AskUserQuestion: - **Approve** — proceed to implementation - **Request changes** — revise and re-checkpoint - **Pause** — save progress and stop Do NOT proceed until approved. --- ## Phase 2: Implementation (Steps 3-5) ### Step 3: Core Implementation Read `.arch/01-requirements.md` and `.arch/02-architecture.md`. Spawn implementation agent (standalone Task — no team): ``` Task( subagent_type="general-purpose", model="opus", prompt="You are a Rust implementation expert. Implement the project based on the approved architecture. ## Requirements [Insert .arch/01-requirements.md] ## Architecture [Insert .arch/02-architecture.md] ## Reference Material Read .claude/skills/rust-skills/SKILL.md from disk — it contains 179 Rust coding rules. Apply these rules during implementation. ## Rust Expert Focus Areas Prioritize these during implementation: - Ownership and borrowing — zero-copy where possible, explicit lifetime annotations - Error handling — Result/Option chains with ?, no unwrap() in library code - Pattern matching — exhaustive matches, no wildcard catch-alls on enums - Traits and generics — for polymorphism and code reuse - Concurrency — Send/Sync safety, async/await patterns - Memory efficiency — avoid unnecessary allocations, use iterators over collect ## Quality Checklist Before completing, verify: - [ ] Compiles without warnings - [ ] No unwrap()/expect() in non-test code - [ ] No `as any` or type suppression - [ ] #[must_use] on fallible functions - [ ] All unsafe blocks documented with // SAFETY: - [ ] Functions ≤100 lines, complexity ≤8, ≤5 params - [ ] Input validation at system boundaries ## Instructions 1. Implement core data structures (structs, enums) with derives 2. Implement trait definitions and their impls 3. Implement error types with thiserror 4. Implement core business logic modules 5. Implement public API surface (CLI commands or HTTP handlers or lib exports) 6. Wire up configuration, logging (tracing), and error propagation 7. Add input validation at system boundaries 8. Follow the architecture exactly — do not add unrequested features Write all code files. Write summary to .arch/03-implementation.md (files created/modified, key decisions). Report: files created count + summary" ) ``` Wait for completion. Update state: step → 4. ### Step 4: Test Suite Read `.arch/02-architecture.md` and `.arch/03-implementation.md`. Spawn test writer agent (standalone Task — no team): ``` Task( subagent_type="general-purpose", model="opus", prompt="You are a Rust test engineer. Write comprehensive tests for the implementation. ## Architecture [Insert .arch/02-architecture.md] ## Implementation [Insert .arch/03-implementation.md] ## Instructions 1. Write unit tests in #[cfg(test)] modules for all new functions 2. Write integration tests in tests/ directory for public API 3. Test error paths: ensure errors propagate correctly with ? 4. Test edge cases: empty inputs, max values, boundary conditions 5. Test async code: use #[tokio::test] for async functions 6. Use assert_eq!, assert!, assert_ne! — no unwrap() in assertions 7. Consider proptest for data structure invariants if applicable (read .claude/skills/property-based-testing/SKILL.md if relevant) 8. Follow existing test patterns in the project Target: every public function has at least one test. Error paths tested. Write all test files. Run: cargo test 2>&1 (report full output). Write summary to .arch/04-tests.md (test files, coverage areas, pass/fail). Report: test count + pass/fail status" ) ``` Wait for completion. Update state: step → 5. ### Step 5: Parallel Review Wave Read `.arch/03-implementation.md` and `.arch/04-tests.md`. Create scoped team and all tasks upfront: ``` TeamCreate(team_name="arch-review", description="Parallel review wave for arch skill") TaskCreate(subject="rust-review", description="Rust idiom + quality review via rust-skills") TaskCreate(subject="security-review", description="Security review: unsafe, unwrap, input validation") TaskCreate(subject="cargo-fuzz-setup", description="Fuzzing setup with cargo-fuzz") TaskCreate(subject="clippy-check", description="Run cargo clippy + cargo fmt check") ``` Spawn all 4 teammates in a **single message** (all `run_in_background: true`): ``` Task( name="w1-rust-review", subagent_type="general-purpose", team_name="arch-review", model="sonnet", run_in_background=true, prompt="You are review teammate w1-rust-review on team \"arch-review\". Review the implementation against Rust best practices. ## Implementation [Insert .arch/03-implementation.md] 1. TaskUpdate: claim task \"rust-review\" (owner=\"w1-rust-review\", status=\"in_progress\") 2. Use the Skill tool to invoke skill \"rust-skills\" — apply the 179 rules to the codebase 3. Write findings to .arch/05a-rust-review.md (rule violations, severity, file:line, fix) 4. TaskUpdate: complete (status=\"completed\") 5. SendMessage to team lead: findings count by severity" ) Task( name="w1-security", subagent_type="general-purpose", team_name="arch-review", model="sonnet", run_in_background=true, prompt="You are review teammate w1-security on team \"arch-review\". Security review of the Rust implementation. ## Implementation [Insert .arch/03-implementation.md] Focus on: - unsafe blocks without // SAFETY: comments - unwrap()/expect() in non-test code - Unchecked integer arithmetic (use checked_add, saturating_mul, etc.) - Unchecked as casts (use TryFrom instead) - Missing input validation at system boundaries - Path traversal in file operations - Command injection in process spawning - Missing timeouts on network/IO operations - Secrets in logs or error messages If the codebase handles cryptographic keys, passwords, or sensitive data: use the Skill tool to invoke skill \"zeroize-audit\" for zeroization analysis. 1. TaskUpdate: claim task \"security-review\" (owner=\"w1-security\", status=\"in_progress\") 2. Write findings to .arch/05b-security-review.md 3. TaskUpdate: complete (status=\"completed\") 4. SendMessage to team lead: findings count by severity" ) Task( name="w1-fuzz", subagent_type="general-purpose", team_name="arch-review", model="sonnet", run_in_background=true, prompt="You are fuzzing teammate w1-fuzz on team \"arch-review\". Set up cargo-fuzz for the implementation. ## Implementation [Insert .arch/03-implementation.md] 1. TaskUpdate: claim task \"cargo-fuzz-setup\" (owner=\"w1-fuzz\", status=\"in_progress\") 2. Use the Skill tool to invoke skill \"cargo-fuzz\" 3. Create fuzz targets for functions that accept user input or parse data 4. Write setup summary to .arch/05c-fuzzing.md (targets created, how to run) 5. TaskUpdate: complete (status=\"completed\") 6. SendMessage to team lead: fuzz targets created count" ) Task( name="w1-clippy", subagent_type="general-purpose", team_name="arch-review", model="sonnet", run_in_background=true, prompt="You are lint teammate w1-clippy on team \"arch-review\". Run static analysis on the implementation. 1. TaskUpdate: claim task \"clippy-check\" (owner=\"w1-clippy\", status=\"in_progress\") 2. Run: cargo clippy --workspace --all-features -- -D warnings 2>&1 3. Run: cargo fmt --all -- --check 2>&1 4. Run: cargo build 2>&1 (verify it compiles) 5. If clippy or fmt issues found, fix them 6. Write results to .arch/05d-lint.md (clippy warnings, fmt issues, build status) 7. TaskUpdate: complete (status=\"completed\") 8. SendMessage to team lead: pass/fail + issue counts" ) ``` Wait for all 4. Verify via `TaskList`. Consolidate into `.arch/05-review.md`: ```markdown # Review Wave Results ## Rust Idiom Review [Summary from .arch/05a-rust-review.md] ## Security Review [Summary from .arch/05b-security-review.md] ## Fuzzing Setup [Summary from .arch/05c-fuzzing.md] ## Lint Results [Summary from .arch/05d-lint.md] ## Critical/High Findings [Aggregated list for Step 6] ``` Shutdown review team: ``` TeamDelete(team_name="arch-review") ``` Update state: step → checkpoint-2. --- ## PHASE CHECKPOINT 2 — User Approval Required Present via AskUserQuestion: ``` 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 ``` Do NOT proceed until approved. --- ## Phase 3: Fixes & Delivery (Steps 6-7) ### Step 6: Fix Critical Issues If any Critical or High findings from the review wave: ``` Task( subagent_type="general-purpose", model="opus", prompt="Fix all Critical and High findings from the review wave. ## Findings to fix [Insert critical/high items from .arch/05-review.md] ## Rules - Fix only the identified issues — no scope creep - Run cargo test after fixes to ensure nothing broke - Run cargo clippy to verify lint issues resolved Fix each finding. Run cargo test && cargo clippy 2>&1. Write fix summary to .arch/06-fixes.md (what was fixed, test results)." ) ``` If no critical/high findings, skip. Write `.arch/06-fixes.md` noting "No critical issues to fix." Update state: step → 7. ### Step 7: Documentation ``` Task( subagent_type="general-purpose", model="sonnet", prompt="Write project documentation. ## All context [Insert .arch/01-requirements.md] [Insert .arch/02-architecture.md] [Insert .arch/03-implementation.md] [Insert .arch/04-tests.md] ## Reference Read .claude/skills/rust-architect/SKILL.md from disk for README structure and NEVER_DO rules to include in project documentation. ## Instructions 1. Write/update README.md with: purpose, quickstart, usage examples, architecture overview 2. Verify all public items have rustdoc (/// comments) 3. Generate NEVER_DO rules section based on rust-architect patterns 4. Write .arch/07-documentation.md summarizing what was documented Do NOT write CLAUDE.md or memory files." ) ``` Wait for completion. Update state: step → complete. --- ## Completion Update `.arch/state.json`: `status → "complete"`. Present: ``` Arch complete: $FEATURE .arch/ ├── 01-requirements.md ├── 02-architecture.md ├── 03-implementation.md ├── 04-tests.md ├── 05-review.md (consolidated) │ ├── 05a-rust-review.md │ ├── 05b-security-review.md │ ├── 05c-fuzzing.md │ └── 05d-lint.md ├── 06-fixes.md ├── 07-documentation.md └── state.json Next steps: 1. cargo test — verify all tests pass 2. cargo clippy — verify no warnings 3. Review .arch/05c-fuzzing.md for fuzz target instructions 4. Run /rust-skills for ongoing code quality checks ``` ## Asset Wiring | Asset | Location | How Used | |-------|----------|----------| | rust-architect | `.claude/skills/rust-architect/` | Step 2 + 7: agent reads from disk as architecture reference | | rust-expert | … ## Source & license This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [qGolem](https://github.com/qGolem) - **Source:** [qGolem/orc](https://github.com/qGolem/orc) - **License:** MIT 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-qgolem-orc-arch - Seller: https://agentstack.voostack.com/s/qgolem - 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%.