Docs

# Prototype — Full-Stack Feature Orchestrator

> Orchestrate end-to-end feature development from requirements through deployment, with checkpoint gates and session persistence.

`/orc:prototype` is the only orc skill that combines planning **and** execution in a single command. Where `/orc:spec` generates plans and `/orc:swarm` executes them, prototype does both — walking through 9 sequential steps across 3 phases, with mandatory user approval gates before implementation starts and before deployment begins. This page covers:

- [How it works](#how-it-works) — the 9-step workflow at a glance
- [Run a prototype](#run-a-prototype) — invocation, flags, and what to expect
- [Phases in detail](#phases-in-detail) — what each step produces
- [Checkpoint gates](#checkpoint-gates) — where execution pauses for approval
- [State management](#state-management) — session persistence and resumption
- [Agents used](#agents-used) — which agents run at each step
- [Vibe-code integration](#vibe-code-integration) — design-system-aware frontend
- [How prototype compares to other skills](#how-prototype-compares-to-other-skills) — spec, swarm, review

**Tip:** Looking for planning without execution? See [Planning Pipeline Deep Dive](./002-planning-pipeline-deep-dive.md). For parallel code review, see [Code Analysis](./004-code-analysis.md).

![Prototype workflow diagram](./diagrams/skill-prototype.png)

***

## How it works

Prototype follows a strict sequential workflow — no skipping, no reordering. Each step writes an output file to `.prototype/` before the next step can begin.

```
Phase 1: Architecture & Design
  Step 1  Requirements gathering (interactive Q&A)
  Step 2  Database & data model design
  Step 3  Backend & frontend architecture
  ─────── CHECKPOINT 1: approve design before code ───────

Phase 2: Implementation
  Step 4  Database implementation
  Step 5  Backend implementation
  Step 6  Frontend implementation (delegates to /orc:vibe-code)
  Step 7  Testing + Security + Performance (3 agents in parallel)
  ─────── CHECKPOINT 2: approve quality before deployment ───────

Phase 3: Delivery
  Step 8  Deployment & infrastructure
  Step 9  Documentation & handoff
```

***

## Run a prototype

```
/orc:prototype "add multi-tenant auth" --stack react/fastapi/postgres --api-style rest
```

| Flag | Default | Options |
| :--- | :------ | :------ |
| `--stack` | auto-detect | Any `frontend/backend/db` triple |
| `--api-style` | `rest` | `rest`, `graphql` |

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

**What happens next:**

1. Pre-flight checks for an existing session (resume or archive)
2. `.prototype/` directory and `state.json` initialized
3. Step 1 begins — you'll be asked 6 requirements questions, one at a time

***

## Phases in detail

### Phase 1: Architecture & Design (Steps 1-3)

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

1. Problem statement and user pain point
2. Acceptance criteria
3. Scope boundaries (what's explicitly out)
4. Technical constraints
5. Stack confirmation
6. Dependencies on other features/services

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

**Step 2 — Database design.** A `general-purpose` agent designs the schema: entity relationships, column types, indexing strategy, migration plan, query patterns, and data access layer.

Writes `.prototype/02-database-design.md`.

**Step 3 — Architecture.** Another `general-purpose` agent designs the full-stack architecture: API endpoints, service layer, auth, component hierarchy, state management, routing, error handling, and security considerations.

Writes `.prototype/03-architecture.md`.

### Phase 2: Implementation (Steps 4-7)

**Step 4 — Database implementation.** Migrations, models, repositories, constraints, indexes. Reads the design from Step 2 and writes actual code.

**Step 5 — Backend implementation.** API routes, services, validation, auth middleware, logging. Reads architecture from Step 3 and DB implementation from Step 4.

**Step 6 — Frontend implementation.** If a design system exists in the repo, delegates to `/orc:vibe-code` for design-system-aware UI building with browser verification. Otherwise falls back to a `general-purpose` agent. See [Vibe-code integration](#vibe-code-integration).

**Step 7 — Parallel verification.** Three agents launch simultaneously:

| Agent | Focus |
| :---- | :---- |
| `general-purpose` | Write unit, integration, and component tests |
| `orc:security-reviewer` | OWASP Top 10, auth flaws, injection, XSS/CSRF |
| `orc:performance-engineer` | N+1 queries, missing indexes, bundle size, caching |

Results consolidate into `.prototype/07-testing.md`. Critical/high findings are fixed before proceeding.

### Phase 3: Delivery (Steps 8-9)

**Step 8 — Deployment.** The `orc:deployment-engineer` agent creates CI/CD config, migration steps, feature flags, health checks, monitoring alerts, and a rollback runbook.

**Step 9 — Documentation.** A `general-purpose` agent writes API docs, schema migration notes, an ADR for key design choices, and a handoff summary.

***

## Checkpoint gates

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

### Checkpoint 1 — After architecture, before code

```
Architecture and database design are complete. Please review:
- .prototype/02-database-design.md
- .prototype/03-architecture.md

1. Approve — proceed to implementation
2. Request changes — tell me what to adjust
3. Pause — save progress and stop here
```

**Why it exists:** Catching a bad schema or API design after 3 steps of planning is cheap. Catching it after Steps 4-6 have written hundreds of lines of code is expensive.

### Checkpoint 2 — After testing, before deployment

```
Testing and validation complete. Please review .prototype/07-testing.md

1. Approve — proceed to deployment & documentation
2. Request changes — tell me what to fix
3. Pause — save progress and stop here
```

**Why it exists:** Security or performance findings should be resolved before deployment config is generated. This gate ensures no critical issues slip through.

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

***

## State management

### Session files

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

| File | Purpose |
| :--- | :------ |
| `state.json` | Progress tracker — current step, completed steps, stack config |
| `01-requirements.md` | Step 1 output |
| `02-database-design.md` | Step 2 output |
| `03-architecture.md` | Step 3 output |
| `04-database-impl.md` | Step 4 output |
| `05-backend-impl.md` | Step 5 output |
| `06-frontend-impl.md` | Step 6 output |
| `07-testing.md` | Step 7 output (consolidated from 3 agents) |
| `08-deployment.md` | Step 8 output |
| `09-documentation.md` | Step 9 output |

### state.json structure

```json
{
  "feature": "add multi-tenant auth",
  "status": "in_progress",
  "stack": "react/fastapi/postgres",
  "api_style": "rest",
  "current_step": 4,
  "current_phase": 2,
  "completed_steps": [1, 2, 3],
  "files_created": ["01-requirements.md", "02-database-design.md", "03-architecture.md"],
  "started_at": "2026-03-15T10:00:00Z",
  "last_updated": "2026-03-15T10:45:00Z"
}
```

### Resuming a session

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

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

### Why file-driven state matters

Agents read prior step outputs from `.prototype/*.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 | What it does |
| :--- | :---- | :--- | :----------- |
| 1 | (orchestrator) | Interactive | AskUserQuestion loop, writes requirements |
| 2 | `general-purpose` | Foreground task | Database schema design |
| 3 | `general-purpose` | Foreground task | Full-stack architecture |
| 4 | `general-purpose` | Foreground task | Database code (migrations, models) |
| 5 | `general-purpose` | Foreground task | Backend code (API, services) |
| 6 | `/orc:vibe-code` or `general-purpose` | Skill or task | Frontend code |
| 7a | `general-purpose` | Background task | Test suite creation |
| 7b | `orc:security-reviewer` | Background task | Security audit |
| 7c | `orc:performance-engineer` | Background task | Performance review |
| 8 | `orc:deployment-engineer` | Foreground task | CI/CD, infra, runbook |
| 9 | `general-purpose` | Foreground task | API docs, ADR, handoff |

Steps 7a-7c are the only parallel step — all three launch with `run_in_background: true` in a single message, matching the pattern used by `/orc:review`.

***

## Vibe-code integration

Step 6 checks for a design system before building frontend:

```
Glob("skills/design-system/systems/*/spec.md")
```

**If a design system exists:** The orchestrator reads `.prototype/03-architecture.md` and `.prototype/05-backend-impl.md` into context (so vibe-code knows the API shape), then invokes:

```
Skill("orc:vibe-code", args="<detected-system> <component-description>")
```

Vibe-code loads the design system spec, builds components using design tokens, and spawns browser verification agents. After vibe-code completes, the prototype orchestrator writes `.prototype/06-frontend-impl.md` summarizing what was built.

**If no design system exists:** Falls back to a `general-purpose` agent with frontend implementation instructions.

***

## How prototype compares to other skills

|  | Prototype | Spec | Swarm | Review |
| :--- | :--- | :--- | :--- | :--- |
| **Purpose** | Plan + execute a feature | Plan only | Execute a plan | Audit changes |
| **Input** | Feature description | Feature description | PLAN.md | Git diff |
| **Output** | Working code + docs | ROADMAP.md + PLANs | Committed code | Issue list |
| **State location** | `.prototype/` | `.claude/plans/` | TEAM-PLAN.md | Plan file |
| **Checkpoint gates** | 2 (mid-execution) | 0 (clarification rounds) | 1 (plan approval) | 1 (synthesis) |
| **Session resume** | Yes (state.json) | No | No | No |
| **Max parallelism** | 3 agents (Step 7) | 4 agents (research) | N executors (waves) | 5 agents |
| **Executes code** | Yes | No | Yes | No |

**When to use which:**

- **Prototype** — You have a feature idea and want working code end-to-end, with quality gates
- **Spec + Swarm** — Complex multi-phase projects that need planning before execution
- **Review** — Code already exists, you want a quality audit before merging

***

## Troubleshooting

| Issue | Cause | Solution |
| :---- | :---- | :------- |
| Skill not found | Plugin not loaded | Run `/orc:install` to verify plugin registration |
| Agent fails at Step 7 | Missing agent definition | Verify `agents/performance-engineer.md` and `agents/deployment-engineer.md` exist |
| Checkpoint stuck | Waiting for input | Select option 1/2/3 via the prompt — prototype won't proceed without explicit choice |
| Resume offers wrong step | Stale state.json | Delete `.prototype/state.json` and restart, or select "Start fresh" |
| Vibe-code not triggered | No design system | Create one with `/orc:design-system new <name>`, or accept the general-purpose fallback |

## See also

- [Skill Reference](./001-orc-skill-reference.md) — Full command listing
- [Planning Pipeline](./002-planning-pipeline-deep-dive.md) — How `/orc:spec` works
- [Implementation](./003-implementation.md) — How `/orc:swarm` executes plans
- [Code Analysis](./004-code-analysis.md) — How `/orc:review` audits code

---

> Based on [wshobson/agents full-stack-feature](https://github.com/wshobson/agents) (MIT License). Adapted for the orc plugin with orc agent remapping, vibe-code integration, and session persistence.