---
description: Automated workflow orchestrator with approval gates and sub-agent delegation
allowed-tools: Read, Write, Edit, Bash, Task, AskUserQuestion, TodoWrite
---

# Workflow Orchestrator - Spawn

**Input**: "$ARGUMENTS"

---

## ⛔ CRITICAL ENFORCEMENT RULES

**READ THESE RULES BEFORE ANY ACTION. VIOLATIONS WILL CORRUPT THE WORKFLOW.**

### 🔴 MUST DO (Non-Negotiable)
1. **MUST** run version_manager.py create BEFORE any design work
2. **MUST** verify phase state BEFORE each transition
3. **MUST** run validation script AFTER each phase completes
4. **MUST** capture and display script output (never assume success)
5. **MUST** create task files in `.workflow/versions/vXXX/tasks/` (version-specific)
6. **MUST** wait for Task agents to fully complete before proceeding
7. **MUST** run `npm run build` and verify exit code = 0 before approval

### 🚫 CANNOT DO (Strictly Forbidden)
1. **CANNOT** skip phases or combine phases
2. **CANNOT** proceed if any verification fails
3. **CANNOT** assume task files exist - must verify with `ls`
4. **CANNOT** assume build passes - must run and check exit code
5. **CANNOT** transition without running the transition script
6. **CANNOT** mark workflow complete if any task is not 'approved'
7. **CANNOT** proceed to IMPLEMENTING if no task files exist

### ⚠️ BLOCKING CONDITIONS
These conditions **HALT** the workflow immediately:

| Condition | Blocked Phase | Resolution |
|-----------|---------------|------------|
| `project_manifest.json` missing | INITIALIZE | Create manifest first |
| No task files created | DESIGNING → IMPLEMENTING | Architect must create tasks |
| Build fails | IMPLEMENTING → REVIEWING | Fix build errors |
| Files missing | REVIEWING | Implement missing files |
| Version mismatch | Any | Run `/workflow:status` |

---

## ARGUMENT PARSING

```
FULL_AUTO_MODE = "$ARGUMENTS" contains "--full-auto"
AUTO_MODE = "$ARGUMENTS" contains "--auto" AND NOT "--full-auto"
MANUAL_MODE = NOT AUTO_MODE AND NOT FULL_AUTO_MODE
FEATURE = "$ARGUMENTS" with "--auto" and "--full-auto" removed and trimmed
```

### Mode Comparison

| Aspect | Manual | --auto | --full-auto |
|--------|--------|--------|-------------|
| Requirements | User provides all | AI asks questions with options | AI expands autonomously |
| Questions | None | Until AI has enough info | Only acceptance criteria |
| Design Approval | Manual | Auto-approve | Auto-approve |
| Impl Approval | Manual | Auto if validation passes | Auto if validation passes |
| Best For | Full control | Guided discovery | Quick prototyping |

### --auto Behavior (Interactive Discovery)
- **PHASE 1.5**: AI asks clarifying questions with multiple-choice options
- Questions continue until AI determines requirements are complete
- Examples: "What auth method?", "Need password reset?", "Which OAuth providers?"
- Gate 1 (design approval): Auto-approve
- Gate 2 (impl approval): Auto-approve IF validation passes
- **STILL RUNS**: All validation checks, build verification

### --full-auto Behavior (AI-Driven Expansion)
- **PHASE 1.5**: AI autonomously analyzes and expands the idea
- AI generates comprehensive requirements from brief input
- **ONLY ASKS**: Acceptance criteria ("How will you know this is done?")
- Gate 1 (design approval): Auto-approve
- Gate 2 (impl approval): Auto-approve IF validation passes
- **STILL RUNS**: All validation checks, build verification

---

## PHASE EXECUTION PROTOCOL

### ═══════════════════════════════════════════════════════════════
### PHASE 1: INITIALIZE
### ═══════════════════════════════════════════════════════════════

**Entry Condition**: Command invoked
**Exit Condition**: Version created, session started, phase = DESIGNING

#### Step 1.1: Parse Arguments [MANDATORY]
```
Extract: AUTO_MODE, FEATURE
Validate: FEATURE is not empty
```
**BLOCK IF**: FEATURE is empty → Ask user for feature description

#### Step 1.2: Verify Prerequisites [MANDATORY]
```bash
# MUST run this check - do not skip
ls project_manifest.json
```
**BLOCK IF**: File does not exist → Error: "Run /guardrail:init or /guardrail:analyze first"

```bash
# Create workflow directory if missing (auto-recovery)
mkdir -p .workflow/versions
if [ ! -f .workflow/index.yml ]; then
  cat > .workflow/index.yml << 'EOF'
versions: []
latest_version: null
total_versions: 0
EOF
fi
```

#### Step 1.3: Create Version [MANDATORY]
```bash
python3 skills/guardrail-orchestrator/scripts/version_manager.py create "$FEATURE"
```
**MUST capture output** and extract VERSION_ID (e.g., "v004")
**BLOCK IF**: Script fails → Error with script output

#### Step 1.4: Display Start Banner [MANDATORY]
```
╔══════════════════════════════════════════════════════════════╗
║ 🚀 WORKFLOW STARTED                                          ║
╠══════════════════════════════════════════════════════════════╣
║ Version:  $VERSION_ID                                        ║
║ Feature:  $FEATURE                                           ║
║ Mode:     $MODE (AUTO/INTERACTIVE)                           ║
║ Tasks:    .workflow/versions/$VERSION_ID/tasks/              ║
╚══════════════════════════════════════════════════════════════╝
```

#### Step 1.5: Transition [MANDATORY]
```bash
python3 skills/guardrail-orchestrator/scripts/workflow_manager.py transition DESIGNING
```
**VERIFY**: Script exits with code 0

---

### ═══════════════════════════════════════════════════════════════
### PHASE 1.5: REQUIREMENTS GATHERING (--auto and --full-auto only)
### ═══════════════════════════════════════════════════════════════

**Entry Condition**: Phase = DESIGNING, Mode = AUTO_MODE or FULL_AUTO_MODE
**Exit Condition**: Requirements documented, ready for design
**SKIP IF**: MANUAL_MODE (proceed directly to PHASE 2)

---

#### IF AUTO_MODE: Interactive Requirements Discovery

**Purpose**: Ask clarifying questions until AI has enough information to design the system.

##### Step 1.5.1: Initialize Requirements Document
```bash
mkdir -p .workflow/versions/$VERSION_ID/requirements
```

Create requirements tracking:
```yaml
# .workflow/versions/$VERSION_ID/requirements/discovery.yml
feature: "$FEATURE"
status: gathering
questions_asked: 0
requirements: []
ready_for_design: false
```

##### Step 1.5.2: Question Loop [MANDATORY]

**REPEAT until ready_for_design = true:**

Use AskUserQuestion tool to gather requirements:

```
Use AskUserQuestion with intelligent questions based on feature type.

Question categories to explore:
1. SCOPE: What exactly should this feature do?
2. USERS: Who will use this? What roles?
3. DATA: What information needs to be stored?
4. ACTIONS: What operations can users perform?
5. AUTH: What security/permissions are needed?
6. UI: What screens/components are needed?
7. INTEGRATIONS: Any external services?
8. EDGE CASES: What happens when X fails?
```

**Example Question Flow for "add user authentication":**

```
Round 1 - Authentication Type:
  Question: "What authentication method do you need?"
  Options:
    - "Email/Password (Recommended)" - Traditional login with email and password
    - "OAuth Social Login" - Login with Google, GitHub, etc.
    - "Magic Link" - Passwordless email link login
    - "Multi-factor" - 2FA with authenticator apps
  [multiSelect: true]

Round 2 - (If OAuth selected) Providers:
  Question: "Which OAuth providers should be supported?"
  Options:
    - "Google (Recommended)" - Most common, easy setup
    - "GitHub" - Popular for developer tools
    - "Apple" - Required for iOS apps
    - "Microsoft" - Common for enterprise
  [multiSelect: true]

Round 3 - User Data:
  Question: "What user information should be stored?"
  Options:
    - "Basic (name, email)" - Minimal user profile
    - "Extended (+ avatar, bio)" - Social features
    - "Professional (+ company, role)" - B2B applications
    - "Custom fields" - I'll specify additional fields
  [multiSelect: false]

Round 4 - Features:
  Question: "Which additional features do you need?"
  Options:
    - "Password reset" - Email-based password recovery
    - "Email verification" - Confirm email ownership
    - "Remember me" - Persistent sessions
    - "Account deletion" - GDPR compliance
  [multiSelect: true]

Round 5 - UI Components:
  Question: "What UI components are needed?"
  Options:
    - "Login page" - Standalone login screen
    - "Registration page" - New user signup
    - "Profile page" - View/edit user info
    - "Settings page" - Account settings
  [multiSelect: true]
```

##### Step 1.5.3: Evaluate Completeness [MANDATORY]

After each round, evaluate if requirements are sufficient:

```
READY_FOR_DESIGN = true IF ALL of these are answered:
  - [ ] Core functionality is clear
  - [ ] Data model requirements are known
  - [ ] API operations are identified
  - [ ] UI screens are listed
  - [ ] Authentication/authorization is defined
  - [ ] Key edge cases are addressed
```

**If NOT ready**: Generate next question based on gaps
**If ready**: Proceed to Step 1.5.4

##### Step 1.5.4: Generate Requirements Summary [MANDATORY]

Save gathered requirements:
```yaml
# .workflow/versions/$VERSION_ID/requirements/summary.yml
feature: "$FEATURE"
gathered_at: <timestamp>
questions_asked: X
mode: auto

requirements:
  authentication:
    methods: [email_password, oauth_google]
    features: [password_reset, email_verification]

  data_model:
    user_fields: [name, email, avatar, bio]
    additional_entities: []

  ui_components:
    pages: [login, register, profile]
    components: [login_form, user_avatar]

  api_endpoints:
    - POST /api/auth/login
    - POST /api/auth/register
    - POST /api/auth/forgot-password
    - GET /api/users/me

acceptance_criteria:
  - User can register with email/password
  - User can login with Google OAuth
  - User can reset forgotten password
  - User profile displays correctly
```

##### Step 1.5.5: Display Requirements Summary [MANDATORY]
```
╔══════════════════════════════════════════════════════════════╗
║ 📋 REQUIREMENTS GATHERED                                     ║
╠══════════════════════════════════════════════════════════════╣
║ Feature:  $FEATURE                                           ║
║ Questions asked: X                                           ║
╠══════════════════════════════════════════════════════════════╣
║ SCOPE DEFINED                                                ║
║   ✅ Authentication: Email/Password + Google OAuth           ║
║   ✅ Features: Password reset, Email verification            ║
║   ✅ User Data: Name, email, avatar, bio                     ║
║   ✅ UI: Login, Register, Profile pages                      ║
╠══════════════════════════════════════════════════════════════╣
║ Proceeding to DESIGN phase...                                ║
╚══════════════════════════════════════════════════════════════╝
```

---

#### IF FULL_AUTO_MODE: AI-Driven Expansion

**Purpose**: AI autonomously expands brief input into comprehensive requirements.
Only asks user for acceptance criteria.

##### Step 1.5.1: Autonomous Analysis [MANDATORY]

Use Task tool to expand requirements:

```
Use Task tool with:
  subagent_type: "requirements-analyst"
  prompt: |
    # REQUIREMENTS ANALYST - Autonomous Expansion

    ## INPUT
    Feature request: "$FEATURE"

    ## YOUR MISSION
    Expand this brief feature request into comprehensive requirements.
    Think like a senior product manager.

    ## ANALYSIS PROCESS

    1. **Understand Intent**
       - What problem is the user trying to solve?
       - What is the core value proposition?
       - Who are the target users?

    2. **Expand Scope**
       - What are the obvious features needed?
       - What are commonly expected features users don't mention?
       - What are the MVP requirements vs nice-to-haves?

    3. **Data Requirements**
       - What entities need to be stored?
       - What are the relationships between entities?
       - What fields does each entity need?

    4. **API Design**
       - What CRUD operations are needed?
       - What custom operations are needed?
       - What authentication/authorization is required?

    5. **UI Components**
       - What pages/screens are needed?
       - What reusable components are needed?
       - What is the user flow?

    6. **Edge Cases**
       - What happens on errors?
       - What are the validation rules?
       - What are the security considerations?

    ## OUTPUT FORMAT

    Create: .workflow/versions/$VERSION_ID/requirements/expanded.yml

    ```yaml
    feature: "$FEATURE"
    expanded_at: <timestamp>
    mode: full_auto

    analysis:
      problem_statement: "<what problem this solves>"
      target_users: "<who will use this>"
      core_value: "<main benefit>"

    scope:
      mvp_features:
        - <feature 1>
        - <feature 2>
      future_features:
        - <feature for later>

    data_model:
      entities:
        - name: <Entity>
          fields: [<field1>, <field2>]
          relations: [<relation>]

    api_endpoints:
      - method: POST
        path: /api/xxx
        purpose: <what it does>

    ui_structure:
      pages:
        - name: <PageName>
          route: /<path>
          purpose: <what user does here>
      components:
        - name: <ComponentName>
          purpose: <what it displays/does>

    security:
      authentication: <method>
      authorization: <rules>

    edge_cases:
      - scenario: <what could go wrong>
        handling: <how to handle it>
    ```

    ## OUTPUT
    After creating the file, output a summary of your analysis.
```

##### Step 1.5.2: Display Expanded Requirements [MANDATORY]
```
╔══════════════════════════════════════════════════════════════╗
║ 🤖 AI-EXPANDED REQUIREMENTS                                  ║
╠══════════════════════════════════════════════════════════════╣
║ Original: "$FEATURE"                                         ║
╠══════════════════════════════════════════════════════════════╣
║ EXPANDED SCOPE                                               ║
║   Problem: <problem statement>                               ║
║   Users: <target users>                                      ║
║   Value: <core value>                                        ║
╠══════════════════════════════════════════════════════════════╣
║ MVP FEATURES                                                 ║
║   • Feature 1                                                ║
║   • Feature 2                                                ║
║   • Feature 3                                                ║
╠══════════════════════════════════════════════════════════════╣
║ DATA MODEL                                                   ║
║   📦 Entity1 (X fields)                                      ║
║   📦 Entity2 (Y fields)                                      ║
╠══════════════════════════════════════════════════════════════╣
║ API ENDPOINTS: X                                             ║
║ UI PAGES: X                                                  ║
║ COMPONENTS: X                                                ║
╚══════════════════════════════════════════════════════════════╝
```

##### Step 1.5.3: Ask for Acceptance Criteria [MANDATORY]

**This is the ONLY question in full-auto mode:**

```
Use AskUserQuestion:
  Question: "Based on the expanded requirements above, what are your acceptance criteria? How will you know this feature is complete and working?"

  Options:
    - "Looks good - use AI-suggested criteria"
      Description: "AI will generate acceptance criteria based on the requirements"
    - "I'll specify my own criteria"
      Description: "Enter your own acceptance criteria"
    - "Add to AI criteria"
      Description: "Use AI criteria plus add my own"
```

**If user chooses "Looks good"**: AI generates acceptance criteria
**If user chooses "I'll specify"**: Prompt user for criteria
**If user chooses "Add to"**: Combine AI + user criteria

##### Step 1.5.4: Finalize Requirements [MANDATORY]

Save final requirements with acceptance criteria:
```yaml
# .workflow/versions/$VERSION_ID/requirements/final.yml
feature: "$FEATURE"
mode: full_auto
finalized_at: <timestamp>

# ... expanded requirements ...

acceptance_criteria:
  - criterion: "User can successfully register"
    verification: "Submit registration form, verify account created"
  - criterion: "User can login with credentials"
    verification: "Login with valid credentials, verify session created"
  - criterion: "Invalid login shows error"
    verification: "Login with wrong password, verify error message"
  # ... more criteria
```

##### Step 1.5.5: Display Final Summary [MANDATORY]
```
╔══════════════════════════════════════════════════════════════╗
║ ✅ REQUIREMENTS FINALIZED                                    ║
╠══════════════════════════════════════════════════════════════╣
║ Feature:  $FEATURE                                           ║
║ Mode:     Full-Auto                                          ║
╠══════════════════════════════════════════════════════════════╣
║ ACCEPTANCE CRITERIA                                          ║
║   ☐ User can successfully register                           ║
║   ☐ User can login with credentials                          ║
║   ☐ Invalid login shows error                                ║
║   ☐ Password reset works via email                           ║
╠══════════════════════════════════════════════════════════════╣
║ Proceeding to DESIGN phase (auto-approved)...                ║
╚══════════════════════════════════════════════════════════════╝
```

---

#### IF MANUAL_MODE: Skip to Design

**No requirements gathering phase. Proceed directly to PHASE 2.**

---

### ═══════════════════════════════════════════════════════════════
### PHASE 2: DESIGNING (Enhanced with Design Document)
### ═══════════════════════════════════════════════════════════════

**Entry Condition**: Phase = DESIGNING (verified)
**Exit Condition**: Design document validated, dependency graph generated, tasks with context created

#### Step 2.1: Verify Phase State [MANDATORY]
```bash
python3 skills/guardrail-orchestrator/scripts/workflow_manager.py status
```
**BLOCK IF**: Current phase is not DESIGNING

#### Step 2.2: Create Design Directories [MANDATORY]
```bash
mkdir -p .workflow/versions/$VERSION_ID/design
mkdir -p .workflow/versions/$VERSION_ID/contexts
mkdir -p .workflow/versions/$VERSION_ID/tasks
```

#### Step 2.3: Spawn Architect Agent for Design Document [MANDATORY]
**MUST use Task tool to create comprehensive design document**:

```
Use Task tool with:
  subagent_type: "system-architect"
  prompt: |
    # SYSTEM ARCHITECT - Design Document Creation
    # VERSION $VERSION_ID

    ## STRICT REQUIREMENTS
    Create a COMPLETE design document. Partial designs = failure.

    ## INPUT
    Feature: "$FEATURE"
    Version: $VERSION_ID
    Output: .workflow/versions/$VERSION_ID/design/design_document.yml
    Schema: skills/guardrail-orchestrator/schemas/design_document.yml

    ## DESIGN PROCESS

    ### Phase A: Analyze Requirements
    1. Break down "$FEATURE" into user stories
    2. Identify data that needs to be stored
    3. Identify operations users can perform
    4. Plan the UI structure

    ### Phase B: Design Data Layer (LAYER 1)
    Create data_models section with:
    - id: model_<name>
    - name: PascalCase entity name
    - table_name: snake_case
    - fields: [name, type, constraints]
    - relations: [type, target, foreign_key, on_delete]
    - timestamps: true
    - validations: [field, rule, message]

    ### Phase C: Design API Layer (LAYER 2)
    Create api_endpoints section with:
    - id: api_<verb>_<resource>
    - method: GET|POST|PUT|PATCH|DELETE
    - path: /api/<path>
    - request_body: (for POST/PUT/PATCH)
    - responses: [{status, description, schema}]
    - depends_on_models: [model_ids]
    - auth: {required, roles}

    ### Phase D: Design UI Layer (LAYER 3)
    Create pages section with:
    - id: page_<name>
    - path: /<route>
    - data_needs: [{api_id, purpose, on_load}]
    - components: [component_ids]
    - auth: {required, roles, redirect}

    Create components section with:
    - id: component_<name>
    - name: PascalCaseName
    - props: [{name, type, required, description}]
    - events: [{name, payload, description}]
    - uses_apis: [api_ids]
    - uses_components: [component_ids]

    ## OUTPUT FORMAT
    Create file: .workflow/versions/$VERSION_ID/design/design_document.yml

    ```yaml
    workflow_version: "$VERSION_ID"
    feature: "$FEATURE"
    created_at: <timestamp>
    status: draft
    revision: 1

    data_models:
      - id: model_<name>
        name: <Name>
        # ... full model definition

    api_endpoints:
      - id: api_<verb>_<resource>
        method: <METHOD>
        path: /api/<path>
        # ... full endpoint definition

    pages:
      - id: page_<name>
        path: /<route>
        # ... full page definition

    components:
      - id: component_<name>
        name: <Name>
        # ... full component definition
    ```

    ## ALSO UPDATE project_manifest.json
    Add entities under appropriate sections with status: "PENDING"

    ## VERIFICATION
    Before finishing, verify the design document exists:
    ```bash
    cat .workflow/versions/$VERSION_ID/design/design_document.yml | head -20
    ```

    ## OUTPUT SUMMARY
    ```
    === DESIGN DOCUMENT CREATED ===
    Data Models:     X
    API Endpoints:   X
    Pages:           X
    Components:      X
    File: .workflow/versions/$VERSION_ID/design/design_document.yml
    ```
```

#### Step 2.4: Validate Design & Generate Artifacts [MANDATORY]
**Run design validation to generate dependency graph, contexts, and tasks**:

```bash
python3 skills/guardrail-orchestrator/scripts/validate_design.py \
  .workflow/versions/$VERSION_ID/design/design_document.yml \
  --output-dir .workflow/versions/$VERSION_ID
```

**This generates:**
- `dependency_graph.yml` - Layered execution order
- `contexts/*.yml` - Per-entity context snapshots for subagents
- `tasks/*.yml` - Implementation tasks with full context

**BLOCK IF**: Validation fails (exit code != 0) → Display errors, re-run design

#### Step 2.4.5: Generate API Contract & Shared Types [MANDATORY]
**Generate the API contract that binds frontend and backend implementations**:

```bash
python3 skills/guardrail-orchestrator/scripts/generate_api_contract.py \
  .workflow/versions/$VERSION_ID/design/design_document.yml \
  --output-dir .workflow/versions/$VERSION_ID
```

**This generates:**
- `contracts/api_contract.yml` - Strict API type definitions
- `app/types/api.ts` - Shared TypeScript interfaces

**CRITICAL**: Both frontend and backend agents MUST import from `app/types/api.ts`.
This ensures type safety and contract compliance.

**BLOCK IF**: Generation fails → Display errors, re-run design

#### Step 2.5: Verify Generated Artifacts [MANDATORY]
```bash
# Check dependency graph exists
ls .workflow/versions/$VERSION_ID/dependency_graph.yml

# Check API contract exists
ls .workflow/versions/$VERSION_ID/contracts/api_contract.yml

# Check shared types file exists
ls app/types/api.ts

# Count generated tasks
TASK_COUNT=$(ls .workflow/versions/$VERSION_ID/tasks/*.yml 2>/dev/null | wc -l)
echo "Tasks generated: $TASK_COUNT"

# Count context files
CONTEXT_COUNT=$(ls .workflow/versions/$VERSION_ID/contexts/*.yml 2>/dev/null | wc -l)
echo "Context files: $CONTEXT_COUNT"
```

**BLOCK IF**: TASK_COUNT = 0 → Error: "No tasks generated from design"
**BLOCK IF**: API contract missing → Error: "API contract not generated"

#### Step 2.6: Display Layered Execution Plan [MANDATORY]
Read dependency_graph.yml and display:

```
╔══════════════════════════════════════════════════════════════╗
║ 📊 EXECUTION LAYERS (Dependency Graph)                       ║
╠══════════════════════════════════════════════════════════════╣
║                                                              ║
║ Layer 1: DATA MODELS (Parallel)                              ║
║ ─────────────────────────────────────────────                ║
║   📦 model_xxx      → backend  [no deps]                     ║
║   📦 model_yyy      → backend  [no deps]                     ║
║                                                              ║
║ Layer 2: API ENDPOINTS (After Layer 1)                       ║
║ ─────────────────────────────────────────────                ║
║   🔌 api_xxx        → backend  [needs: model_xxx]            ║
║   🔌 api_yyy        → backend  [needs: model_xxx, model_yyy] ║
║                                                              ║
║ Layer 3: UI (After Layer 2)                                  ║
║ ─────────────────────────────────────────────                ║
║   🧩 component_xxx  → frontend [no deps]                     ║
║   📄 page_xxx       → frontend [needs: api_xxx, component_xxx]║
║                                                              ║
╠══════════════════════════════════════════════════════════════╣
║ EXECUTION SUMMARY                                            ║
║   Total tasks:      X                                        ║
║   Total layers:     X                                        ║
║   Max parallelism:  X tasks can run simultaneously           ║
╚══════════════════════════════════════════════════════════════╝
```

#### Step 2.7: Transition [MANDATORY]
```bash
python3 skills/guardrail-orchestrator/scripts/workflow_manager.py progress \
  --tasks-created $TASK_COUNT
python3 skills/guardrail-orchestrator/scripts/workflow_manager.py transition AWAITING_DESIGN_APPROVAL
```

#### Step 2.8: Display Design Summary [MANDATORY]
```
╔══════════════════════════════════════════════════════════════╗
║ 📐 DESIGN COMPLETE - AWAITING APPROVAL                       ║
╠══════════════════════════════════════════════════════════════╣
║ Feature:  $FEATURE                                           ║
║ Version:  $VERSION_ID                                        ║
╠══════════════════════════════════════════════════════════════╣
║ DESIGN DOCUMENT                                              ║
║   📦 Data Models:     X                                      ║
║   🔌 API Endpoints:   X                                      ║
║   📄 Pages:           X                                      ║
║   🧩 Components:      X                                      ║
╠══════════════════════════════════════════════════════════════╣
║ GENERATED ARTIFACTS                                          ║
║   ✅ Design document created                                 ║
║   ✅ Dependency graph calculated                             ║
║   ✅ Context snapshots: X files                              ║
║   ✅ Implementation tasks: X tasks                           ║
╠══════════════════════════════════════════════════════════════╣
║ Each subagent will receive FULL CONTEXT including:           ║
║   - Target entity definition                                 ║
║   - Related model/API definitions                            ║
║   - Input/output contracts                                   ║
║   - Acceptance criteria                                      ║
╠══════════════════════════════════════════════════════════════╣
║ 👆 Review the execution layers above                         ║
║                                                              ║
║ If design looks correct: /workflow:approve                   ║
║ If changes needed: /workflow:reject "reason"                 ║
╚══════════════════════════════════════════════════════════════╝
```

---

### ═══════════════════════════════════════════════════════════════
### PHASE 3: GATE 1 - Design Approval
### ═══════════════════════════════════════════════════════════════

**Entry Condition**: Phase = AWAITING_DESIGN_APPROVAL
**Exit Condition**: Design approved, phase = IMPLEMENTING

#### IF AUTO_MODE = true:
```bash
python3 skills/guardrail-orchestrator/scripts/workflow_manager.py approve design
python3 skills/guardrail-orchestrator/scripts/workflow_manager.py transition IMPLEMENTING
```
Output: "✅ Design auto-approved. Proceeding to implementation."

#### IF AUTO_MODE = false:
Use AskUserQuestion:
```
Question: "Review the design. How do you want to proceed?"
Options:
  1. "Approve - Continue to implementation"
  2. "Reject - Revise design" 
  3. "Pause - Save and exit"
```

**On Approve**: Run transition commands above
**On Reject**: Return to Phase 2
**On Pause**: Output resume command and stop

---

### ═══════════════════════════════════════════════════════════════
### PHASE 4: IMPLEMENTING (Team-Based Parallel Execution)
### ═══════════════════════════════════════════════════════════════

**Entry Condition**: Phase = IMPLEMENTING (verified)
**Exit Condition**: Both teams complete, build passes, API contract validated

**TEAM-BASED PARALLELISM**: Two specialized agents run in parallel:
- **Backend Team**: Implements models + APIs (Layer 1 + Layer 2)
- **Frontend Team**: Implements components + pages (Layer 3)

Both teams share the same API contract (`app/types/api.ts`) ensuring type safety.

#### Step 4.1: Verify Phase State [MANDATORY]
```bash
python3 skills/guardrail-orchestrator/scripts/workflow_manager.py status
```
**BLOCK IF**: Phase is not IMPLEMENTING

#### Step 4.2: Load Contract and Tasks [MANDATORY]
```bash
# Read API contract
cat .workflow/versions/$VERSION_ID/contracts/api_contract.yml

# Verify shared types exist
ls app/types/api.ts

# Count backend and frontend tasks
BACKEND_TASKS=$(grep -l 'agent: backend' .workflow/versions/$VERSION_ID/tasks/*.yml 2>/dev/null | wc -l)
FRONTEND_TASKS=$(grep -l 'agent: frontend' .workflow/versions/$VERSION_ID/tasks/*.yml 2>/dev/null | wc -l)
echo "Backend tasks: $BACKEND_TASKS"
echo "Frontend tasks: $FRONTEND_TASKS"
```

#### Step 4.3: Launch Both Teams IN PARALLEL [MANDATORY]
**CRITICAL**: Launch BOTH agents in a SINGLE message with TWO Task tool calls.
This enables true parallel execution.

```
╔══════════════════════════════════════════════════════════════╗
║ 🚀 LAUNCHING PARALLEL TEAMS                                  ║
╠══════════════════════════════════════════════════════════════╣
║                                                              ║
║   ┌─────────────────┐         ┌─────────────────┐           ║
║   │  BACKEND TEAM   │   ||    │  FRONTEND TEAM  │           ║
║   │                 │   ||    │                 │           ║
║   │  • Models       │   ||    │  • Components   │           ║
║   │  • APIs         │   ||    │  • Pages        │           ║
║   │                 │   ||    │                 │           ║
║   │  Exports:       │   ||    │  Imports:       │           ║
║   │  /api/* routes  │ ──→→ ──→│  app/types/api  │           ║
║   └─────────────────┘         └─────────────────┘           ║
║                                                              ║
║   SHARED CONTRACT: app/types/api.ts                          ║
║                                                              ║
╚══════════════════════════════════════════════════════════════╝
```

##### Step 4.3.1: Spawn Backend Team Agent [IN PARALLEL]
```
Use Task tool with:
  subagent_type: "backend-architect"
  prompt: |
    # BACKEND TEAM - VERSION $VERSION_ID

    ## YOUR MISSION
    Implement ALL backend tasks (models + APIs) for this workflow.
    You own the entire backend layer.

    ## CRITICAL: API CONTRACT COMPLIANCE
    You MUST import types from the shared types file:
    ```typescript
    import type { User, CreateUserRequest, ... } from '@/types/api';
    ```

    The API contract is at: .workflow/versions/$VERSION_ID/contracts/api_contract.yml
    The shared types are at: app/types/api.ts

    **DO NOT** create your own types. Use the shared types.

    ## TASK FILES
    Read all backend tasks:
    ```bash
    ls .workflow/versions/$VERSION_ID/tasks/task_*model*.yml
    ls .workflow/versions/$VERSION_ID/tasks/task_*api*.yml
    ```

    ## IMPLEMENTATION ORDER
    1. **First**: Implement ALL models (Layer 1)
       - Add to prisma/schema.prisma
       - Run: npx prisma generate

    2. **Then**: Implement ALL API endpoints (Layer 2)
       - Create app/api/*/route.ts files
       - Import shared types from @/types/api
       - Implement request validation
       - Return responses matching contract types

    ## FOR EACH TASK
    1. Read the task file and context file
    2. Read reference files for patterns
    3. Implement following the contract
    4. Verify with TypeScript

    ## VERIFICATION
    After all tasks:
    ```bash
    npx prisma generate 2>&1 || true
    npx tsc --noEmit 2>&1 || true
    ```

    ## OUTPUT FORMAT
    ```
    === BACKEND TEAM COMPLETE ===
    Models implemented:
      - model_xxx: app/api/... ✓

    APIs implemented:
      - api_xxx: app/api/.../route.ts ✓
      - api_yyy: app/api/.../route.ts ✓

    Contract compliance:
      - Types imported from @/types/api ✓
      - All endpoints match contract ✓

    TypeScript: PASS/FAIL
    Prisma: PASS/FAIL
    ```
```

##### Step 4.3.2: Spawn Frontend Team Agent [IN PARALLEL]
```
Use Task tool with:
  subagent_type: "frontend-architect"
  prompt: |
    # FRONTEND TEAM - VERSION $VERSION_ID

    ## YOUR MISSION
    Implement ALL frontend tasks (components + pages) for this workflow.
    You own the entire frontend layer.

    ## CRITICAL: API CONTRACT COMPLIANCE
    You MUST import types from the shared types file:
    ```typescript
    import type { User, ApiError, ... } from '@/types/api';
    import { API_PATHS } from '@/types/api';
    ```

    The API contract is at: .workflow/versions/$VERSION_ID/contracts/api_contract.yml
    The shared types are at: app/types/api.ts

    **DO NOT** create your own API types. Use the shared types.

    ## TASK FILES
    Read all frontend tasks:
    ```bash
    ls .workflow/versions/$VERSION_ID/tasks/task_*component*.yml
    ls .workflow/versions/$VERSION_ID/tasks/task_*page*.yml
    ```

    ## IMPLEMENTATION
    For EACH task:
    1. Read the task file and context file
    2. Read reference files for patterns
    3. Create component/page file
    4. Import types from @/types/api
    5. Use API_PATHS for fetch calls
    6. Type all props, state, and API responses

    ## API CALL PATTERN (USE THIS)
    ```typescript
    import type { User, CreateUserRequest } from '@/types/api';
    import { API_PATHS } from '@/types/api';

    // Type-safe API call
    const response = await fetch(API_PATHS.CREATE_USER, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(data satisfies CreateUserRequest),
    });
    const result: User = await response.json();
    ```

    ## VERIFICATION
    After all tasks:
    ```bash
    npx tsc --noEmit 2>&1 || true
    ```

    ## OUTPUT FORMAT
    ```
    === FRONTEND TEAM COMPLETE ===
    Components implemented:
      - component_xxx: app/components/Xxx.tsx ✓

    Pages implemented:
      - page_xxx: app/xxx/page.tsx ✓

    Contract compliance:
      - Types imported from @/types/api ✓
      - API calls use API_PATHS ✓

    TypeScript: PASS/FAIL
    ```
```

**IMPORTANT**: You MUST send BOTH Task tool calls in a SINGLE message.
This enables parallel execution. Do NOT wait for one to complete.

#### Step 4.4: Wait for Both Teams [MANDATORY]
**MUST wait for BOTH agents to complete before proceeding.**

Display progress:
```
╔══════════════════════════════════════════════════════════════╗
║ ⏳ TEAMS EXECUTING...                                        ║
╠══════════════════════════════════════════════════════════════╣
║ Backend Team:   🔄 In Progress                               ║
║ Frontend Team:  🔄 In Progress                               ║
╚══════════════════════════════════════════════════════════════╝
```

#### Step 4.5: Post-Implementation Verification [MANDATORY]
```bash
# Verify build passes
npm run build
echo "Exit code: $?"
```
**BLOCK IF**: Exit code != 0 → Error with build output

```bash
# Verify all task files have corresponding implementation files
for task in .workflow/versions/$VERSION_ID/tasks/*.yml; do
  grep "to_create:" -A 10 "$task" | grep -E "^\s+-" | sed 's/.*- //' | while read path; do
    if [ ! -f "$path" ]; then
      echo "MISSING: $path"
    fi
  done
done
```
**BLOCK IF**: Any file MISSING → List missing files, halt workflow

#### Step 4.6: Validate API Contract Compliance [MANDATORY]
```bash
# Run contract validation
python3 skills/guardrail-orchestrator/scripts/validate_against_contract.py \
  .workflow/versions/$VERSION_ID/contracts/api_contract.yml \
  --project-dir .
CONTRACT_EXIT=$?
echo "CONTRACT_EXIT=$CONTRACT_EXIT"
```

**Validates:**
- All backend routes exist and match contract methods
- All frontend components import from shared types
- All API calls use correct paths and methods

**BLOCK IF**: CONTRACT_EXIT != 0 → Display violations, halt workflow

#### Step 4.7: Display Implementation Summary [MANDATORY]
```
╔══════════════════════════════════════════════════════════════╗
║ ✅ PARALLEL IMPLEMENTATION COMPLETE                          ║
╠══════════════════════════════════════════════════════════════╣
║ Backend Team:                                                ║
║   Models:     X implemented                                  ║
║   APIs:       X implemented                                  ║
║                                                              ║
║ Frontend Team:                                               ║
║   Components: X implemented                                  ║
║   Pages:      X implemented                                  ║
╠══════════════════════════════════════════════════════════════╣
║ API Contract:    VALID ✓                                     ║
║ Shared Types:    app/types/api.ts ✓                          ║
║ Build:           PASS ✓                                      ║
╚══════════════════════════════════════════════════════════════╝
```

#### Step 4.8: Transition [MANDATORY]
```bash
python3 skills/guardrail-orchestrator/scripts/workflow_manager.py transition REVIEWING
```

---

### ═══════════════════════════════════════════════════════════════
### PHASE 5: REVIEWING
### ═══════════════════════════════════════════════════════════════

**Entry Condition**: Phase = REVIEWING (verified)
**Exit Condition**: All checks pass, ready for approval

#### Step 5.1: Verify Phase State [MANDATORY]
```bash
python3 skills/guardrail-orchestrator/scripts/workflow_manager.py status
```
**BLOCK IF**: Phase is not REVIEWING

#### IF AUTO_MODE = true: Automated Review

##### Step 5.2a: Run Build Validation [MANDATORY]
```bash
npm run build 2>&1
BUILD_EXIT=$?
```

##### Step 5.2b: Generate Implementation Visualization [MANDATORY]
**MUST show user what was built before review:**

```bash
python3 skills/guardrail-orchestrator/scripts/visualize_implementation.py --manifest project_manifest.json
```

This displays:
- 📱 Page structure with routes
- 🧩 Component hierarchy tree
- 🔌 API endpoints with methods
- 📊 Implementation statistics (lines, hooks, types)

##### Step 5.3a: Check All Files Exist [MANDATORY]
```bash
MISSING_COUNT=0
for task in .workflow/versions/$VERSION_ID/tasks/*.yml; do
  grep "file_paths:" -A 20 "$task" | grep -E "^\s+-\s+" | sed 's/.*- //' | while read path; do
    if [ ! -f "$path" ]; then
      echo "MISSING: $path"
      MISSING_COUNT=$((MISSING_COUNT + 1))
    fi
  done
done
echo "Missing files: $MISSING_COUNT"
```

##### Step 5.4a: Auto-Decision [MANDATORY]
```
IF BUILD_EXIT = 0 AND MISSING_COUNT = 0:
  → Display: "✅ AUTO-REVIEW PASSED"
  → Run: python3 .../workflow_manager.py transition SECURITY_REVIEW
  → Proceed to Phase 5.5 (Security Review)
ELSE:
  → Display: "❌ AUTO-REVIEW FAILED"
  → List all failures (build errors, missing files)
  → HALT workflow
  → Output: "Fix issues and run /workflow:resume"
```

##### Step 5.5a: Auto Review Report [MANDATORY]
```
╔══════════════════════════════════════════════════════════════╗
║ 🔍 AUTO REVIEW RESULTS                                       ║
╠══════════════════════════════════════════════════════════════╣
║ Build:       PASS / FAIL                                     ║
║ Files:       X/Y exist                                       ║
║ Decision:    AUTO-APPROVED / AUTO-REJECTED                   ║
╠══════════════════════════════════════════════════════════════╣
║ IMPLEMENTATION SUMMARY                                       ║
║   Pages:        X implemented                                ║
║   Components:   X implemented                                ║
║   API Endpoints: X implemented                               ║
║   Total Lines:  X                                            ║
╠══════════════════════════════════════════════════════════════╣
║ 👆 See visualization above for details                       ║
╠══════════════════════════════════════════════════════════════╣
║ [If failed, list specific failures here]                     ║
╚══════════════════════════════════════════════════════════════╝
```

---

#### IF AUTO_MODE = false: Agent Review

##### Step 5.2b: Generate Implementation Visualization [MANDATORY]
**MUST show user what was built before spawning reviewer:**

```bash
python3 skills/guardrail-orchestrator/scripts/visualize_implementation.py --manifest project_manifest.json
```

This shows the user:
- Pages with their routes and components
- Component hierarchy and relationships
- API endpoints with HTTP methods
- Code statistics and metrics

##### Step 5.3b: Spawn Reviewer Agent [MANDATORY]
```
Use Task tool with:
  subagent_type: "quality-engineer"
  prompt: |
    # REVIEWER AGENT - VERSION $VERSION_ID
    
    ## STRICT REQUIREMENTS
    Review ALL tasks. Report ALL issues. No partial reviews.
    
    ## REVIEW CHECKLIST (FOR EACH TASK)
    
    Task files: .workflow/versions/$VERSION_ID/tasks/*.yml
    
    For each task:
    1. [ ] Read task file
    2. [ ] Verify ALL file_paths exist
    3. [ ] Read each file, verify:
       - [ ] Exports match manifest
       - [ ] Types are correct
       - [ ] No TypeScript errors
       - [ ] Follows project patterns
    4. [ ] Check acceptance_criteria met
    
    ## VALIDATION (RUN THESE)
    ```bash
    npm run build
    npm run lint 2>/dev/null || echo "No lint configured"
    ```
    
    ## OUTPUT FORMAT (REQUIRED)
    ```
    === REVIEW REPORT ===
    
    TASK: task_create_xxx
    - Files: EXIST / MISSING (list)
    - Build: PASS / FAIL
    - Quality: PASS / ISSUES (list)
    - Verdict: APPROVED / NEEDS_CHANGES
    
    [Repeat for each task]
    
    SUMMARY
    - Total tasks: X
    - Approved: X
    - Need changes: X
    - Overall: PASS / FAIL
    ```
```

##### Step 5.3b: Transition to Security Review [MANDATORY]
```bash
python3 skills/guardrail-orchestrator/scripts/workflow_manager.py transition SECURITY_REVIEW
```

---

### ═══════════════════════════════════════════════════════════════
### PHASE 5.5: SECURITY REVIEW
### ═══════════════════════════════════════════════════════════════

**Entry Condition**: Phase = SECURITY_REVIEW (verified)
**Exit Condition**: Security scan passes (no CRITICAL issues), ready for approval

#### Step 5.5.1: Verify Phase State [MANDATORY]
```bash
python3 skills/guardrail-orchestrator/scripts/workflow_manager.py status
```
**BLOCK IF**: Phase is not SECURITY_REVIEW

#### Step 5.5.2: Run Security Scanner [MANDATORY]
```bash
python3 skills/guardrail-orchestrator/scripts/security_scan.py \
  --project-dir . \
  --severity HIGH
SECURITY_EXIT=$?
echo "SECURITY_EXIT=$SECURITY_EXIT"
```

**Exit codes:**
- 0 = PASS (no critical/high issues)
- 1 = HIGH issues found (warning in normal mode, blocks in --strict)
- 2 = CRITICAL issues found (always blocks)

#### Step 5.5.3: API Contract Validation [MANDATORY]
```bash
# Validate against generated contract (types and routes)
python3 skills/guardrail-orchestrator/scripts/validate_against_contract.py \
  .workflow/versions/$VERSION_ID/contracts/api_contract.yml \
  --project-dir .
CONTRACT_EXIT=$?
echo "CONTRACT_EXIT=$CONTRACT_EXIT"

# Also run static API analysis
python3 skills/guardrail-orchestrator/scripts/validate_api_contract.py \
  --project-dir .
API_EXIT=$?
echo "API_EXIT=$API_EXIT"
```

**Contract Validation Checks:**
- Backend routes exist and export correct HTTP methods
- Frontend files import from shared types (@/types/api)
- Types not recreated locally (must use shared types)

**Static API Validation Checks:**
- Frontend API calls have matching backend endpoints
- HTTP methods match (GET, POST, PUT, DELETE)
- Request bodies are sent where expected

#### Step 5.5.4: Security Decision [MANDATORY]

##### IF AUTO_MODE = true:
```
IF SECURITY_EXIT = 0 AND API_EXIT = 0 AND CONTRACT_EXIT = 0:
  → Display: "✅ SECURITY & CONTRACT VALIDATION PASSED"
  → Transition to AWAITING_IMPL_APPROVAL
ELSE IF SECURITY_EXIT = 2:
  → Display: "❌ CRITICAL SECURITY ISSUES - BLOCKING"
  → List all critical issues
  → Transition to IMPLEMENTING (must fix)
  → HALT workflow
ELSE IF CONTRACT_EXIT = 2:
  → Display: "❌ CONTRACT VIOLATIONS - BLOCKING"
  → List all contract violations
  → Transition to IMPLEMENTING (must fix)
  → HALT workflow
ELSE IF SECURITY_EXIT = 1 OR CONTRACT_EXIT = 1:
  → Display: "⚠️ HIGH SEVERITY ISSUES - WARNING"
  → List high severity issues and contract warnings
  → Continue to approval (warning only in auto mode)
```

##### IF AUTO_MODE = false:
Use AskUserQuestion:
```
Question: "Security scan found issues. How do you want to proceed?"
Options:
  1. "Accept risks - Continue to approval" (if no CRITICAL)
  2. "Fix issues - Return to implementation"
  3. "Run full audit - /workflow:security --full"
```

#### Step 5.5.5: Display Security Report [MANDATORY]
```
╔══════════════════════════════════════════════════════════════╗
║ 🔒 SECURITY & CONTRACT REVIEW RESULTS                        ║
╠══════════════════════════════════════════════════════════════╣
║ Security Scan:    PASS / WARNING / CRITICAL                  ║
║   Critical:       X issues                                   ║
║   High:           X issues                                   ║
║   Medium:         X issues                                   ║
║   Low:            X issues                                   ║
╠══════════════════════════════════════════════════════════════╣
║ Contract Compliance:  PASS / WARNING / FAIL                  ║
║   Backend routes:     X of X verified                        ║
║   Type imports:       X files checked                        ║
║   Violations:         X                                      ║
╠══════════════════════════════════════════════════════════════╣
║ API Static Analysis:  PASS / FAIL                            ║
║   Matched calls:      X                                      ║
║   Unmatched:          X                                      ║
║   Method errors:      X                                      ║
╠══════════════════════════════════════════════════════════════╣
║ [If issues found, list top 5 with file locations]            ║
╠══════════════════════════════════════════════════════════════╣
║ VERDICT: APPROVED / NEEDS_FIXES                              ║
╚══════════════════════════════════════════════════════════════╝
```

#### Step 5.5.6: Transition [MANDATORY]
```bash
# If security passed
python3 skills/guardrail-orchestrator/scripts/workflow_manager.py transition AWAITING_IMPL_APPROVAL

# If security failed (CRITICAL issues)
python3 skills/guardrail-orchestrator/scripts/workflow_manager.py transition IMPLEMENTING
```

---

### ═══════════════════════════════════════════════════════════════
### PHASE 6: GATE 2 - Implementation Approval
### ═══════════════════════════════════════════════════════════════

**Entry Condition**: Phase = AWAITING_IMPL_APPROVAL
**Exit Condition**: Implementation approved, phase = COMPLETING

**Note**: In AUTO_MODE, this gate is handled in Phase 5

#### IF AUTO_MODE = false:
Use AskUserQuestion:
```
Question: "Review complete. How do you want to proceed?"
Options:
  1. "Approve - Mark as complete"
  2. "Reject - Request fixes"
  3. "Pause - Save and exit"
```

**On Approve**:
```bash
python3 skills/guardrail-orchestrator/scripts/workflow_manager.py approve implementation
python3 skills/guardrail-orchestrator/scripts/workflow_manager.py transition COMPLETING
```

**On Reject**: Provide feedback, return to Phase 4
**On Pause**: Output resume command and stop

---

### ═══════════════════════════════════════════════════════════════
### PHASE 7: COMPLETING
### ═══════════════════════════════════════════════════════════════

**Entry Condition**: Phase = COMPLETING (verified)
**Exit Condition**: Version marked complete, success report displayed

#### Step 7.1: Verify Phase State [MANDATORY]
```bash
python3 skills/guardrail-orchestrator/scripts/workflow_manager.py status
```
**BLOCK IF**: Phase is not COMPLETING

#### Step 7.2: Update Task Statuses [MANDATORY]
```bash
# Mark all tasks as completed
for task in .workflow/versions/$VERSION_ID/tasks/*.yml; do
  sed -i '' 's/status: .*/status: completed/' "$task" 2>/dev/null || \
  sed -i 's/status: .*/status: completed/' "$task"
done
```

#### Step 7.3: Update Manifest Statuses [MANDATORY]
Update all entities referenced in tasks from "PENDING" to "IMPLEMENTED"

#### Step 7.4: Complete Version [MANDATORY]
```bash
python3 skills/guardrail-orchestrator/scripts/version_manager.py complete
```
**VERIFY**: Script exits with code 0

#### Step 7.5: Final Report [MANDATORY]

**IF AUTO_MODE = true**: Display completion-only report (NO next steps)
```
╔══════════════════════════════════════════════════════════════╗
║ ✅ WORKFLOW COMPLETED (AUTO)                                 ║
╠══════════════════════════════════════════════════════════════╣
║ Version:  $VERSION_ID                                        ║
║ Feature:  $FEATURE                                           ║
╠══════════════════════════════════════════════════════════════╣
║ SUMMARY                                                      ║
║   Tasks completed:  X                                        ║
║   Files created:    X                                        ║
║   Files modified:   X                                        ║
║   Build:            PASS                                     ║
╚══════════════════════════════════════════════════════════════╝
```
**DO NOT** include "NEXT STEPS" in AUTO mode - the workflow is complete.

**IF AUTO_MODE = false**: Display full report with next steps
```
╔══════════════════════════════════════════════════════════════╗
║ ✅ WORKFLOW COMPLETED                                        ║
╠══════════════════════════════════════════════════════════════╣
║ Version:  $VERSION_ID                                        ║
║ Feature:  $FEATURE                                           ║
║ Mode:     INTERACTIVE                                        ║
╠══════════════════════════════════════════════════════════════╣
║ SUMMARY                                                      ║
║   Tasks completed:  X                                        ║
║   Files created:    X                                        ║
║   Files modified:   X                                        ║
╠══════════════════════════════════════════════════════════════╣
║ NEXT STEPS                                                   ║
║   npm run dev              Test the feature                  ║
║   /workflow:history        View all versions                 ║
╚══════════════════════════════════════════════════════════════╝
```

---

## USAGE

```bash
# Manual mode (full control, stops at all gates)
/workflow:spawn add user profile page

# Auto mode (guided discovery with questions, auto-approves gates)
/workflow:spawn --auto add user authentication

# Full-auto mode (AI expands idea, only asks for acceptance criteria)
/workflow:spawn --full-auto add dark mode toggle
```

### Mode Selection Guide

| Use Case | Recommended Mode | Why |
|----------|------------------|-----|
| Complex feature, unclear requirements | `--auto` | AI guides you through requirements |
| Quick prototype, trust AI judgment | `--full-auto` | Fast, minimal input needed |
| Specific requirements already known | Manual | Full control over every step |
| Learning the workflow | Manual | See all gates and decisions |
| Production feature | `--auto` | Ensures requirements are complete |

### Examples

```bash
# Manual - full control
/workflow:spawn add user authentication

# Auto - AI asks questions until requirements are clear
/workflow:spawn --auto add user authentication
# AI asks: "What auth method?" → "OAuth providers?" → "Password reset?" → etc.

# Full-auto - AI expands idea, you approve criteria
/workflow:spawn --full-auto add user authentication
# AI expands: "I'll add login, register, password reset, OAuth, profile..."
# AI asks: "What are your acceptance criteria?"
```

---

## ERROR RECOVERY

| Error | Command |
|-------|---------|
| Workflow interrupted | `/workflow:resume` |
| Check current state | `/workflow:status` |
| View history | `/workflow:history` |
| Skip to specific phase | Not allowed - must follow sequence |

---

## ENFORCEMENT CHECKLIST

Before completing this command, verify:
- [ ] Version created with version_manager.py
- [ ] Phase transitions logged with workflow_manager.py  
- [ ] Task files exist in .workflow/versions/$VERSION_ID/tasks/
- [ ] Build passes (exit code 0)
- [ ] All file_paths in tasks exist
- [ ] Final report displayed