1543 lines
64 KiB
Markdown
1543 lines
64 KiB
Markdown
---
|
|
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
|