Prototype

> Based on wshobson/agents full-stack-feature (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:

{
  "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?"

1. Dependencies: "Does this feature depend on or affect other features/services?"

After gathering answers, write the requirements document:

Output file: .prototype/01-requirements.md

# 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=" ")

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

…

## 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.