Prototype

---
description: "Full-stack feature prototyping — requirements to deployment with checkpoint gates"
argument-hint: "<feature description> [--stack react/fastapi/postgres | rust/axum | solidity/foundry] [--api-style rest|graphql]"
allowed-tools:
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep
  - Task
  - Skill
  - AskUserQuestion
model: inherit
context: inherit
hooks: {}
user-invocable: true
---

> Based on [wshobson/agents full-stack-feature](https://github.com/wshobson/agents) (MIT License)

# Prototype — Feature Orchestrator

## CRITICAL BEHAVIORAL RULES

You MUST follow these rules exactly. Violating any of them is a failure.

1. **Execute steps in order.** Do NOT skip ahead, reorder, or merge steps.
2. **Write output files.** Each step MUST produce its output file in `.prototype/` before the next step begins. Read from prior step files -- do NOT rely on context window memory.
3. **Stop at checkpoints.** When you reach a `PHASE CHECKPOINT`, you MUST stop and wait for explicit user approval before continuing. Use the AskUserQuestion tool with clear options.
4. **Halt on failure.** If any step fails (agent error, test failure, missing dependency), STOP immediately. Present the error and ask the user how to proceed. Do NOT silently continue.
5. **Use only local agents.** All `subagent_type` references use agents bundled with this plugin or `general-purpose`. No cross-plugin dependencies.
6. **Never enter plan mode autonomously.** Do NOT use EnterPlanMode. This command IS the plan -- execute it.

## Pre-flight Checks

Before starting, perform these checks:

### 1. Check for existing session

Check if `.prototype/state.json` exists:

- If it exists and `status` is `"in_progress"`: Read it, display the current step, and ask the user:

  ```
  Found an in-progress prototype session:
  Feature: [name from state]
  Current step: [step from state]

  1. Resume from where we left off
  2. Start fresh (archives existing session)
  ```

  **Resuming**: Read `current_step` from `state.json`. Skip directly to that step — all prior step output files already exist in `.prototype/` and should be read from disk, not regenerated.

  **Archiving**: Move the entire `.prototype/` directory to `.prototype-archived-{ISO_DATE}/`, then create a fresh `.prototype/`.

- If it exists and `status` is `"complete"`: Ask whether to archive and start fresh.

### 2. Initialize state

Create `.prototype/` directory and `state.json`:

```json
{
  "feature": "$ARGUMENTS",
  "status": "in_progress",
  "stack": "auto-detect",
  "api_style": "rest",
  "complexity": "medium",
  "current_step": 1,
  "current_phase": 1,
  "completed_steps": [],
  "files_created": [],
  "started_at": "ISO_TIMESTAMP",
  "last_updated": "ISO_TIMESTAMP"
}
```

Parse `$ARGUMENTS` for `--stack`, `--api-style`, and `--complexity` flags. Use defaults if not specified.

### 3. Parse feature description

Extract the feature description from `$ARGUMENTS` (everything before the flags). This is referenced as `$FEATURE` in prompts below.

### 4. Detect stack category

Determine the stack category from the `--stack` flag or project marker files:

| Marker file | Stack category | Example `--stack` values |
|-------------|---------------|--------------------------|
| `package.json` / `tsconfig.json` | **web** | `react/fastapi/postgres`, `next/express/prisma` |
| `Cargo.toml` | **rust** | `rust/axum`, `rust/cli`, `rust/lib` |
| `foundry.toml` / `hardhat.config.*` | **solidity** | `solidity/foundry`, `solidity/hardhat` |

Store the category in `state.json` as `"stack_category": "web|rust|solidity"`. Agent prompts below reference `$STACK_CATEGORY` to adjust guidance.

---

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

### Step 1: Requirements Gathering

Gather requirements through interactive Q&A. Ask ONE question at a time using the AskUserQuestion tool. Do NOT ask all questions at once.

**Questions to ask (in order):**

1. **Problem Statement**: "What problem does this feature solve? Who is the user and what's their pain point?"
2. **Acceptance Criteria**: "What are the key acceptance criteria? When is this feature 'done'?"
3. **Scope Boundaries**: "What is explicitly OUT of scope for this feature?"
4. **Technical Constraints**: "Any technical constraints? (e.g., existing API conventions, specific DB, latency requirements, auth system)"
5. **Stack Confirmation**: Adapt to detected stack category:
   - **web**: "Confirm the tech stack -- detected [stack] from project. Frontend framework? Backend framework? Database? Any changes?"
   - **rust**: "Confirm the tech stack -- detected Rust from Cargo.toml. Binary or library? Async runtime (tokio/async-std)? Key crates? Any changes?"
   - **solidity**: "Confirm the tech stack -- detected Solidity from foundry.toml. Foundry or Hardhat? Target chain? Key dependencies (OpenZeppelin, Solmate)? Any changes?"
6. **Dependencies**: "Does this feature depend on or affect other features/services?"

After gathering answers, write the requirements document:

**Output file:** `.prototype/01-requirements.md`

```markdown
# Requirements: $FEATURE

## Problem Statement

[From Q1]

## Acceptance Criteria

[From Q2 -- formatted as checkboxes]

## Scope

### In Scope

[Derived from answers]

### Out of Scope

[From Q3]

## Technical Constraints

[From Q4]

## Technology Stack

[From Q5 -- adapt to stack category:
  web: frontend, backend, database, infrastructure
  rust: crate type, async runtime, key crates, target platforms
  solidity: toolchain, target chain, dependencies, deployment strategy]

## Dependencies

[From Q6]

## Configuration

- Stack: [detected or specified]
- API Style: [rest|graphql]
- Complexity: [simple|medium|complex]
```

Update `state.json`: set `current_step` to 2, add `"01-requirements.md"` to `files_created`, add step 1 to `completed_steps`.

### Step 2: Data Model & Storage Design

Read `.prototype/01-requirements.md` to load requirements context.

**Stack-specific scope:**
- **web**: Database schema, tables, relationships, migrations, query patterns
- **rust**: Data structures, serialization (serde), storage strategy (file/DB/in-memory), trait design
- **solidity**: Contract storage layout, struct definitions, mappings, events, storage gas optimization

Use the Task tool to launch a data architecture agent:

```
Task:
  subagent_type: "general-purpose"
  description: "Design database schema and data models for $FEATURE"
  prompt: |
    You are a data architect. Design the data model and storage layer for this feature.

    ## Requirements
    [Insert full contents of .prototype/01-requirements.md]

    ## Deliverables (adapt to stack category: $STACK_CATEGORY)

    ### For web stacks:
    1. Entity relationship design: Tables/collections, relationships, cardinality
    2. Schema definitions: Column types, constraints, defaults, nullable fields
    3. Indexing strategy: Which columns to index, index types, composite indexes
    4. Migration strategy: How to safely add/modify schema in production
    5. Query patterns: Expected read/write patterns and how the schema supports them
    6. Data access patterns: Repository/DAO interface design

    ### For Rust stacks:
    1. Core data structures: Structs, enums, type aliases
    2. Trait design: Key traits, their methods, and relationships
    3. Serialization: serde derives, custom serializers if needed
    4. Storage strategy: File I/O, database (diesel/sqlx), or in-memory
    5. Error types: Custom error enums with thiserror/anyhow

    ### For Solidity stacks:
    1. Contract storage: State variables, mappings, arrays
    2. Struct definitions: On-chain data structures
    3. Events: What state changes to emit for off-chain indexing
    4. Access control: Roles, modifiers, ownership model
    5. Storage optimization: Packing, immutable/constant where possible

    Write your complete data model design as a single markdown document.
```

Save the agent's output to `.prototype/02-database-design.md`.

Update `state.json`: set `current_step` to 3, add step 2 to `completed_steps`.

### Step 3: Backend & Frontend Architecture

Read `.prototype/01-requirements.md` and `.prototype/02-database-design.md`.

Use the Task tool to launch an architecture agent:

```
Task:
  subagent_type: "general-purpose"
  description: "Design full-stack architecture for $FEATURE"
  prompt: |
    You are a software architect. Design the architecture for this feature.

    ## Requirements
    [Insert contents of .prototype/01-requirements.md]

    ## Data Model
    [Insert contents of .prototype/02-database-design.md]

    ## Deliverables (adapt to stack category: $STACK_CATEGORY)

    ### For web stacks:
    **Backend**: API endpoints, request/response schemas, service layer, auth, integration points
    **Frontend**: Component hierarchy, state management, routing, API integration, data fetching
    **Cross-cutting**: Error flow (backend → API → frontend), security (XSS/CSRF), risk assessment

    ### For Rust stacks:
    **Module architecture**: Crate structure (lib/bin split), module tree, public API surface
    **Core logic**: Key functions, data flow, error propagation strategy (? operator, custom errors)
    **CLI/API surface**: Command structure (clap) or API endpoints (axum/actix), input validation
    **Cross-cutting**: Error handling (thiserror/anyhow), logging (tracing), configuration (config crate)

    ### For Solidity stacks:
    **Contract architecture**: Contract hierarchy, inheritance, interfaces, libraries
    **Function design**: External/public functions, access control modifiers, state transitions
    **Integration**: Cross-contract calls, proxy patterns, upgrade strategy if applicable
    **Security**: Checks-effects-interactions pattern, reentrancy guards, access control, gas optimization
    **IMPORTANT**: Smart contracts are immutable once deployed — security must be designed in, not patched later

    Write your complete architecture design as a single markdown document.
```

Save the agent's output to `.prototype/03-architecture.md`.

Update `state.json`: set `current_step` to "checkpoint-1", add step 3 to `completed_steps`.

---

## PHASE CHECKPOINT 1 -- User Approval Required

You MUST stop here and present the architecture for review.

Display a summary of the database design and architecture from `.prototype/02-database-design.md` and `.prototype/03-architecture.md` (key components, API endpoints, data model overview, component structure) and ask:

```
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
```

Do NOT proceed to Phase 2 until the user selects option 1. If they select option 2, revise and re-checkpoint. If option 3, update `state.json` and stop.

---

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

### Step 4: Data Layer Implementation

Read `.prototype/01-requirements.md` and `.prototype/02-database-design.md`.

Use the Task tool:

```
Task:
  subagent_type: "general-purpose"
  description: "Implement data layer for $FEATURE"
  prompt: |
    You are a data layer engineer. Implement the data/storage layer for this feature.

    ## Requirements
    [Insert contents of .prototype/01-requirements.md]

    ## Data Model Design
    [Insert contents of .prototype/02-database-design.md]

    ## Instructions (adapt to stack category: $STACK_CATEGORY)

    ### For web stacks:
    1. Create migration scripts for schema changes
    2. Implement models/entities matching the schema design
    3. Implement repository/data access layer with the designed query patterns
    4. Add database-level validation constraints
    5. Follow the project's existing ORM and migration patterns

    ### For Rust stacks:
    1. Implement core data structures (structs, enums) with appropriate derives
    2. Implement trait definitions and their implementations
    3. Add serde serialization/deserialization as designed
    4. Implement storage layer (file I/O, database client, or in-memory)
    5. Implement error types with thiserror or anyhow

    ### For Solidity stacks:
    1. Implement contract storage variables and struct definitions
    2. Implement events for state change logging
    3. Add access control modifiers (onlyOwner, role-based)
    4. Implement storage optimization (variable packing, immutable/constant)
    5. Follow checks-effects-interactions pattern for all state mutations

    Write all code files. Report what files were created/modified.
```

Save a summary to `.prototype/04-database-impl.md`.

Update `state.json`: set `current_step` to 5, add step 4 to `completed_steps`.

### Step 5: Backend Implementation

Read `.prototype/01-requirements.md`, `.prototype/03-architecture.md`, and `.prototype/04-database-impl.md`.

Use the Task tool:

```
Task:
  subagent_type: "general-purpose"
  description: "Implement backend services for $FEATURE"
  prompt: |
    You are a developer. Implement the core logic for this feature based on the approved architecture.

    ## Requirements
    [Insert contents of .prototype/01-requirements.md]

    ## Architecture
    [Insert contents of .prototype/03-architecture.md]

    ## Data Layer Implementation
    [Insert contents of .prototype/04-database-impl.md]

    ## Instructions (adapt to stack category: $STACK_CATEGORY)

    ### For web stacks:
    1. Implement API endpoints/resolvers as designed in the architecture
    2. Implement business logic in the service layer
    3. Wire up the data access layer from the database implementation
    4. Add input validation, error handling, and proper HTTP status codes
    5. Implement authentication/authorization middleware as designed
    6. Add structured logging and observability hooks

    ### For Rust stacks:
    1. Implement public API surface (CLI commands or HTTP handlers)
    2. Implement core business logic modules
    3. Wire up data layer (storage, serialization)
    4. Add input validation and error propagation with ? operator
    5. Add structured logging with tracing crate
    6. Implement configuration loading (env vars, config files)

    ### For Solidity stacks:
    1. Implement external/public functions as designed
    2. Implement internal helper functions and libraries
    3. Wire up cross-contract interactions (interfaces, calls)
    4. Add input validation (require statements, custom errors)
    5. Implement access control and modifier chains
    6. Add NatSpec documentation for all public functions

    Follow the project's existing code patterns and conventions.
    Write all code files. Report what files were created/modified.
```

Save a summary to `.prototype/05-backend-impl.md`.

Update `state.json`: set `current_step` to 6, add step 5 to `completed_steps`.

### Step 6: Frontend Implementation

Read `.prototype/01-requirements.md`, `.prototype/03-architecture.md`, and `.prototype/05-backend-impl.md`.

**If a design system is available** (check `Glob("skills/design-system/systems/*/spec.md")`):

Delegate frontend work to `/orc:vibe-code` which provides design system awareness + browser-automated visual verification.

Before invoking, read `.prototype/03-architecture.md` and `.prototype/05-backend-impl.md` into context so vibe-code has the API shape. Then invoke:

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

After vibe-code completes, the orchestrator (you) MUST write `.prototype/06-frontend-impl.md` summarizing what was built — vibe-code does not know about `.prototype/` state files.

**Otherwise**, use the Task tool with a general-purpose agent:

```
Task:
  subagent_type: "general-purpose"
  description: "Implement frontend for $FEATURE"
  prompt: |
    You are a frontend developer. Implement the frontend components for this feature.

    ## Requirements
    [Insert contents of .prototype/01-requirements.md]

    ## Architecture
    [Insert contents of .prototype/03-architecture.md]

    ## Backend Implementation
    [Insert contents of .prototype/05-backend-impl.md]

    ## Instructions
    1. Build UI components following the component hierarchy from the architecture
    2. Implement state management and data flow as designed
    3. Integrate with the backend API endpoints using the designed data fetching strategy
    4. Implement form handling, validation, and error states
    5. Add loading states and optimistic updates where appropriate
    6. Ensure responsive design and accessibility basics (semantic HTML, ARIA labels, keyboard nav)
    7. Follow the project's existing frontend patterns and component conventions

    Write all code files. Report what files were created/modified.
```

Save a summary to `.prototype/06-frontend-impl.md`.

**Note:** If the feature has no frontend component (pure backend/API, Rust CLI/library, or Solidity smart contract), skip this step -- write a brief note in `06-frontend-impl.md` explaining why it was skipped, and continue.

Update `state.json`: set `current_step` to 7, add step 6 to `completed_steps`.

### Step 7: Testing & Validation

Read `.prototype/04-database-impl.md`, `.prototype/05-backend-impl.md`, and `.prototype/06-frontend-impl.md`.

Launch three agents in parallel using multiple Task tool calls in a single response (all with `run_in_background: true`). Wait for all three to complete before consolidating.

**7a. Test Suite Creation:**

```
Task:
  subagent_type: "general-purpose"
  run_in_background: true
  description: "Create test suite for $FEATURE"
  prompt: |
    Create a comprehensive test suite for this full-stack feature.

    ## What was implemented
    ### Database
    [Insert contents of .prototype/04-database-impl.md]

    ### Backend
    [Insert contents of .prototype/05-backend-impl.md]

    ### Frontend
    [Insert contents of .prototype/06-frontend-impl.md]

    ## Instructions (adapt to stack category: $STACK_CATEGORY)

    ### For web stacks:
    1. Write unit tests for all new backend functions/methods
    2. Write integration tests for API endpoints
    3. Write database tests for migrations and query patterns
    4. Write frontend component tests if applicable
    5. Follow existing test patterns and frameworks in the project

    ### For Rust stacks:
    1. Write unit tests (inline #[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 ? operator
    4. Use cargo test conventions; no unwrap() in test assertions — use assert_eq!, assert!
    5. Follow existing test patterns in the project

    ### For Solidity stacks:
    1. Write test contracts inheriting forge-std/Test.sol
    2. Test all external/public functions (happy path + revert cases)
    3. Add fuzz tests (testFuzz_ prefix) for functions accepting user input
    4. Test access control: verify unauthorized callers are rejected
    5. Use vm.expectRevert(), vm.prank(), bound() cheatcodes appropriately
    6. Follow forge test conventions (setUp, test_ prefix, *.t.sol files)

    ### All stacks:
    Cover: happy path, edge cases, error handling, boundary conditions.
    Target 80%+ code coverage for new code.

    Write all test files. Report what test files were created and what they cover.
```

**7b. Security Review:**

```
Task:
  subagent_type: "orc:security-reviewer"
  run_in_background: true
  description: "Security review of $FEATURE"
  prompt: |
    Perform a security review of this full-stack feature implementation.

    ## Architecture
    [Insert contents of .prototype/03-architecture.md]

    ## Database Implementation
    [Insert contents of .prototype/04-database-impl.md]

    ## Backend Implementation
    [Insert contents of .prototype/05-backend-impl.md]

    ## Frontend Implementation
    [Insert contents of .prototype/06-frontend-impl.md]

    Review for security issues appropriate to the stack category ($STACK_CATEGORY):
    - **web**: OWASP Top 10, SQL injection, XSS/CSRF, auth flaws, data protection
    - **rust**: unsafe blocks without SAFETY comments, bare unwrap() in non-test code, unchecked as casts, missing input validation
    - **solidity**: Reentrancy, missing access control, tx.origin auth, unchecked return values, unbounded loops, storage vs memory errors, contract size limits

    Provide findings with severity, location, and specific fix recommendations.
```

**7c. Performance Review:**

```
Task:
  subagent_type: "orc:performance-engineer"
  run_in_background: true
  description: "Performance review of $FEATURE"
  prompt: |
    Review the performance of this full-stack feature implementation.

    ## Architecture
    [Insert contents of .prototype/03-architecture.md]

    ## Database Implementation
    [Insert contents of .prototype/04-database-impl.md]

    ## Backend Implementation
    [Insert contents of .prototype/05-backend-impl.md]

    ## Frontend Implementation
    [Insert contents of .prototype/06-frontend-impl.md]

    Review for performance issues appropriate to the stack category ($STACK_CATEGORY):
    - **web**: N+1 queries, missing indexes, large payloads, bundle size, unnecessary re-renders
    - **rust**: Unnecessary allocations/clones, missing iterators (collect vs for-loop), blocking in async, large stack frames
    - **solidity**: Gas optimization (storage reads/writes, calldata vs memory, event indexing), contract size (24KB EIP-170 limit), unbounded loops

    Provide findings with impact estimates and specific optimization recommendations.
```

After all three complete, consolidate results into `.prototype/07-testing.md`:

```markdown
# Testing & Validation: $FEATURE

## Test Suite

[Summary from 7a -- files created, coverage areas]

## Security Findings

[Summary from 7b -- findings by severity]

## Performance Findings

[Summary from 7c -- findings by impact]

## Action Items

[List any critical/high findings that need to be addressed before delivery]
```

If there are Critical or High severity findings from security or performance review, address them now before proceeding. Apply fixes and re-validate.

Update `state.json`: set `current_step` to "checkpoint-2", add step 7 to `completed_steps`.

---

## PHASE CHECKPOINT 2 -- User Approval Required

Display a summary of testing and validation results from `.prototype/07-testing.md` and ask:

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

Test coverage: [summary]
Security findings: [X critical, Y high, Z medium]
Performance findings: [X critical, Y high, Z medium]

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

Do NOT proceed to Phase 3 until the user approves.

---

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

### Step 8: Deployment & Infrastructure

Read `.prototype/03-architecture.md` and `.prototype/07-testing.md`.

Use the Task tool:

```
Task:
  subagent_type: "orc:deployment-engineer"
  description: "Create deployment config for $FEATURE"
  prompt: |
    Create the deployment and infrastructure configuration for this full-stack feature.

    ## Architecture
    [Insert contents of .prototype/03-architecture.md]

    ## Testing Results
    [Insert contents of .prototype/07-testing.md]

    ## Instructions (adapt to stack category: $STACK_CATEGORY)

    ### For web stacks:
    1. Create or update CI/CD pipeline configuration
    2. Add database migration steps to the deployment pipeline
    3. Add feature flag configuration if needed
    4. Define health checks and readiness probes
    5. Create monitoring alerts (error rate, latency, throughput)
    6. Write deployment runbook with rollback steps

    ### For Rust stacks:
    1. Create or update CI/CD pipeline (cargo build --release --locked)
    2. Add cross-compilation targets if needed
    3. Configure binary distribution (cargo-dist, Docker, or package manager)
    4. Add cargo clippy and cargo test to CI gates
    5. Write deployment/release runbook

    ### For Solidity stacks:
    1. Create deployment scripts (forge script in script/*.s.sol)
    2. Configure per-chain deployment (RPC URLs, chain IDs, verification)
    3. Add forge build --sizes check to CI (EIP-170 contract size limit)
    4. Add forge test and forge snapshot to CI gates
    5. Write deployment runbook with verification steps (--verify --etherscan-api-key)
    6. IMPORTANT: Include rollback strategy — smart contracts are immutable; document upgrade path or emergency pause

    Follow existing deployment patterns in the project.
    Write all configuration files. Report what was created/modified.
```

Save output to `.prototype/08-deployment.md`.

Update `state.json`: set `current_step` to 9, add step 8 to `completed_steps`.

### Step 9: Documentation & Handoff

Read all previous `.prototype/*.md` files.

Use the Task tool:

```
Task:
  subagent_type: "general-purpose"
  description: "Write documentation for $FEATURE"
  prompt: |
    You are a technical writer. Create documentation for this full-stack feature.

    ## Feature Context
    [Insert contents of .prototype/01-requirements.md]

    ## Architecture
    [Insert contents of .prototype/03-architecture.md]

    ## Implementation Summary
    ### Database: [Insert contents of .prototype/04-database-impl.md]
    ### Backend: [Insert contents of .prototype/05-backend-impl.md]
    ### Frontend: [Insert contents of .prototype/06-frontend-impl.md]

    ## Deployment
    [Insert contents of .prototype/08-deployment.md]

    ## Instructions
    1. Write API documentation for new endpoints (request/response examples)
    2. Document the database schema changes and migration notes
    3. Update or create user-facing documentation if applicable
    4. Write a brief architecture decision record (ADR) explaining key design choices
    5. Create a handoff summary: what was built, how to test it, known limitations

    Write documentation files. Report what was created/modified.
```

Save output to `.prototype/09-documentation.md`.

Update `state.json`: set `current_step` to "complete", add step 9 to `completed_steps`.

---

## Completion

Update `state.json`:

- Set `status` to `"complete"`
- Set `last_updated` to current timestamp

Present the final summary:

```
Prototype complete: $FEATURE

## Files Created
[List all .prototype/ output files]

## Implementation Summary
- Requirements: .prototype/01-requirements.md
- Database Design: .prototype/02-database-design.md
- Architecture: .prototype/03-architecture.md
- Database Implementation: .prototype/04-database-impl.md
- Backend Implementation: .prototype/05-backend-impl.md
- Frontend Implementation: .prototype/06-frontend-impl.md
- Testing & Validation: .prototype/07-testing.md
- Deployment: .prototype/08-deployment.md
- Documentation: .prototype/09-documentation.md

## Next Steps
1. Review all generated code and documentation
2. Run the full test suite to verify everything passes
3. Create a pull request with the implementation
4. Deploy using the runbook in .prototype/08-deployment.md
```