diff --git a/.claude/commands/workflow/spawn.md b/.claude/commands/workflow/spawn.md new file mode 100644 index 0000000..9ebb856 --- /dev/null +++ b/.claude/commands/workflow/spawn.md @@ -0,0 +1,1956 @@ +--- +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 +8. **MUST** run `npx tsc --noEmit` (type check) and verify exit code = 0 +9. **MUST** run `npm run lint` and verify exit code = 0 + +### 🚫 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 | +| Type check fails | IMPLEMENTING β†’ REVIEWING | Fix TypeScript errors | +| Lint fails | IMPLEMENTING β†’ REVIEWING | Fix lint 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.0: Gate Entry Check [MANDATORY - BLOCKING] +```bash +# Initialize gate state for new workflow +python3 skills/guardrail-orchestrator/scripts/phase_gate.py can-enter INITIALIZING +GATE_EXIT=$? +if [ $GATE_EXIT -ne 0 ]; then + echo "❌ BLOCKED: Cannot start workflow" + python3 skills/guardrail-orchestrator/scripts/phase_gate.py blockers + exit 1 +fi + +# Enter the phase (records entry timestamp) +python3 skills/guardrail-orchestrator/scripts/phase_gate.py enter INITIALIZING +``` + +#### 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: Complete Phase & Transition [MANDATORY] +```bash +# Save checkpoints +python3 skills/guardrail-orchestrator/scripts/phase_gate.py checkpoint manifest_exists \ + --phase INITIALIZING --status passed +python3 skills/guardrail-orchestrator/scripts/phase_gate.py checkpoint version_created \ + --phase INITIALIZING --status passed \ + --data "{\"version\": \"$VERSION_ID\"}" + +# Complete the phase +python3 skills/guardrail-orchestrator/scripts/phase_gate.py complete INITIALIZING +COMPLETE_EXIT=$? +if [ $COMPLETE_EXIT -ne 0 ]; then + echo "❌ BLOCKED: Cannot complete INITIALIZING phase" + python3 skills/guardrail-orchestrator/scripts/phase_gate.py blockers + exit 1 +fi + +# Transition to next phase +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: +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: + mode: full_auto + + analysis: + problem_statement: "" + target_users: "" + core_value: "
" + + scope: + mvp_features: + - + - + future_features: + - + + data_model: + entities: + - name: + fields: [, ] + relations: [] + + api_endpoints: + - method: POST + path: /api/xxx + purpose: + + ui_structure: + pages: + - name: + route: / + purpose: + components: + - name: + purpose: + + security: + authentication: + authorization: + + edge_cases: + - scenario: + handling: + ``` + + ## 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: β•‘ +β•‘ Users: β•‘ +β•‘ 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: + +# ... 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 via gate check) +**Exit Condition**: Design document validated, dependency graph generated, tasks with context created + +#### Step 2.0: Gate Entry Check [MANDATORY - BLOCKING] +```bash +# MUST pass before proceeding - HALT if fails +python3 skills/guardrail-orchestrator/scripts/phase_gate.py can-enter DESIGNING +GATE_EXIT=$? +if [ $GATE_EXIT -ne 0 ]; then + echo "❌ BLOCKED: Cannot enter DESIGNING phase" + python3 skills/guardrail-orchestrator/scripts/phase_gate.py blockers + exit 1 +fi + +# Enter the phase (records entry timestamp) +python3 skills/guardrail-orchestrator/scripts/phase_gate.py enter DESIGNING +``` + +#### 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: 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__ + - method: GET|POST|PUT|PATCH|DELETE + - path: /api/ + - 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_ + - path: / + - data_needs: [{api_id, purpose, on_load}] + - components: [component_ids] + - auth: {required, roles, redirect} + + Create components section with: + - id: component_ + - 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: + status: draft + revision: 1 + + data_models: + - id: model_ + name: + # ... full model definition + + api_endpoints: + - id: api__ + method: + path: /api/ + # ... full endpoint definition + + pages: + - id: page_ + path: / + # ... full page definition + + components: + - id: component_ + 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.5: Verify Generated Artifacts [MANDATORY] +```bash +# Check dependency graph exists +ls .workflow/versions/$VERSION_ID/dependency_graph.yml + +# 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" + +#### 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: Complete Phase & Transition [MANDATORY] +```bash +# Save checkpoints +python3 skills/guardrail-orchestrator/scripts/phase_gate.py checkpoint design_document_created \ + --phase DESIGNING --status passed +python3 skills/guardrail-orchestrator/scripts/phase_gate.py checkpoint design_validated \ + --phase DESIGNING --status passed +python3 skills/guardrail-orchestrator/scripts/phase_gate.py checkpoint tasks_generated \ + --phase DESIGNING --status passed \ + --data "{\"task_count\": $TASK_COUNT, \"context_count\": $CONTEXT_COUNT}" + +# Complete the phase +python3 skills/guardrail-orchestrator/scripts/phase_gate.py complete DESIGNING +COMPLETE_EXIT=$? +if [ $COMPLETE_EXIT -ne 0 ]; then + echo "❌ BLOCKED: Cannot complete DESIGNING phase" + python3 skills/guardrail-orchestrator/scripts/phase_gate.py blockers + exit 1 +fi + +# Update progress and transition +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 (verified via gate check) +**Exit Condition**: Design approved, phase = IMPLEMENTING + +#### Step 3.0: Gate Entry Check [MANDATORY - BLOCKING] +```bash +# MUST pass before proceeding - HALT if fails +python3 skills/guardrail-orchestrator/scripts/phase_gate.py can-enter AWAITING_DESIGN_APPROVAL +GATE_EXIT=$? +if [ $GATE_EXIT -ne 0 ]; then + echo "❌ BLOCKED: Cannot enter AWAITING_DESIGN_APPROVAL phase" + python3 skills/guardrail-orchestrator/scripts/phase_gate.py blockers + exit 1 +fi + +# Enter the phase (records entry timestamp) +python3 skills/guardrail-orchestrator/scripts/phase_gate.py enter AWAITING_DESIGN_APPROVAL +``` + +#### IF AUTO_MODE = true: +```bash +# Save approval checkpoint +python3 skills/guardrail-orchestrator/scripts/phase_gate.py checkpoint design_approved \ + --phase AWAITING_DESIGN_APPROVAL --status passed \ + --data "{\"approver\": \"auto\", \"mode\": \"auto\"}" + +# Complete the phase +python3 skills/guardrail-orchestrator/scripts/phase_gate.py complete AWAITING_DESIGN_APPROVAL + +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**: +```bash +# Save approval checkpoint +python3 skills/guardrail-orchestrator/scripts/phase_gate.py checkpoint design_approved \ + --phase AWAITING_DESIGN_APPROVAL --status passed \ + --data "{\"approver\": \"user\", \"mode\": \"manual\"}" + +# Complete the phase +python3 skills/guardrail-orchestrator/scripts/phase_gate.py complete AWAITING_DESIGN_APPROVAL + +python3 skills/guardrail-orchestrator/scripts/workflow_manager.py approve design +python3 skills/guardrail-orchestrator/scripts/workflow_manager.py transition IMPLEMENTING +``` +**On Reject**: Return to Phase 2 +**On Pause**: Output resume command and stop + +--- + +### ═══════════════════════════════════════════════════════════════ +### PHASE 4: IMPLEMENTING (Layer-Based Parallel Execution) +### ═══════════════════════════════════════════════════════════════ + +**Entry Condition**: Phase = IMPLEMENTING (verified via gate check) +**Exit Condition**: All layers implemented in order, build passes + +**KEY CHANGE**: Tasks are now executed LAYER BY LAYER with FULL CONTEXT. +Each subagent receives a context snapshot with all dependencies. + +#### Step 4.0: Gate Entry Check [MANDATORY - BLOCKING] +```bash +# MUST pass before proceeding - HALT if fails +python3 skills/guardrail-orchestrator/scripts/phase_gate.py can-enter IMPLEMENTING +GATE_EXIT=$? +if [ $GATE_EXIT -ne 0 ]; then + echo "❌ BLOCKED: Cannot enter IMPLEMENTING phase" + python3 skills/guardrail-orchestrator/scripts/phase_gate.py blockers + exit 1 +fi + +# Enter the phase (records entry timestamp) +python3 skills/guardrail-orchestrator/scripts/phase_gate.py enter IMPLEMENTING +``` + +#### 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 Dependency Graph [MANDATORY] +```bash +# Read dependency graph to get layers +cat .workflow/versions/$VERSION_ID/dependency_graph.yml +``` + +Extract layer information: +- Layer count +- Tasks per layer +- Dependencies per task + +#### Step 4.3: Execute Layers Sequentially [MANDATORY] + +**FOR EACH LAYER (1, 2, 3, ...):** + +##### Step 4.3.1: Get Layer Tasks +```bash +# Get all tasks for current layer +LAYER_TASKS=$(grep -l "layer: $LAYER_NUM" .workflow/versions/$VERSION_ID/tasks/*.yml) +``` + +##### Step 4.3.2: Spawn Parallel Agents for Layer [MANDATORY] +**Launch ALL tasks in current layer IN PARALLEL using multiple Task tool calls** + +For EACH task in layer, spawn agent with FULL CONTEXT: + +``` +Use Task tool with: + subagent_type: "backend-architect" OR "frontend-architect" # Based on task.agent + prompt: | + # IMPLEMENTATION AGENT - $TASK_ID + # VERSION $VERSION_ID | LAYER $LAYER_NUM + + ## YOUR SINGLE TASK + You are implementing ONE entity with FULL CONTEXT provided. + + ## CONTEXT (Read this first!) + Context file: .workflow/versions/$VERSION_ID/contexts/$ENTITY_ID.yml + + Read the context file. It contains: + - target: The entity you are implementing (full definition) + - related: All models/APIs/components you need to know about + - dependencies: What this entity depends on (already implemented) + - files: Files to create and reference files for patterns + - acceptance: Criteria that must be met + + ## TASK DETAILS + Task file: .workflow/versions/$VERSION_ID/tasks/$TASK_ID.yml + + ## IMPLEMENTATION PROCESS + + 1. **Read Context File** [MANDATORY] + ```bash + cat .workflow/versions/$VERSION_ID/contexts/$ENTITY_ID.yml + ``` + + 2. **Read Task File** [MANDATORY] + ```bash + cat .workflow/versions/$VERSION_ID/tasks/$TASK_ID.yml + ``` + + 3. **Read Reference Files** (from context.files.reference) + These show existing patterns to follow. + + 4. **Implement** + Create file(s) at exact paths from context.files.to_create + Follow patterns from reference files + Meet all acceptance criteria + + 5. **Verify** + ```bash + # Check file exists + ls + + # Check TypeScript + npx tsc --noEmit 2>&1 || true + ``` + + ## OUTPUT FORMAT + ``` + === TASK COMPLETE: $TASK_ID === + Entity: $ENTITY_ID + Layer: $LAYER_NUM + Files created: + - βœ“ + TypeScript: PASS/FAIL + Acceptance criteria: + - [criterion 1]: PASS/FAIL + - [criterion 2]: PASS/FAIL + ``` +``` + +**IMPORTANT**: Launch ALL tasks in the same layer using PARALLEL Task tool calls in a single message. + +##### Step 4.3.3: Wait for Layer Completion [MANDATORY] +**MUST wait for ALL agents in current layer to complete before proceeding to next layer** + +##### Step 4.3.4: Verify Layer [MANDATORY] +```bash +# Check all files for this layer exist +for task in $LAYER_TASKS; do + # Extract file_paths and verify + grep "to_create:" -A 5 .workflow/versions/$VERSION_ID/contexts/*.yml | grep "app/" | while read path; do + ls "$path" 2>/dev/null || echo "MISSING: $path" + done +done +``` + +**BLOCK IF**: Any files missing in layer β†’ Do not proceed to next layer + +##### Step 4.3.5: Display Layer Progress [MANDATORY] +``` +╔══════════════════════════════════════════════════════════════╗ +β•‘ βœ… LAYER $LAYER_NUM COMPLETE β•‘ +╠══════════════════════════════════════════════════════════════╣ +β•‘ Tasks completed: X β•‘ +β•‘ Files created: X β•‘ +β•‘ Proceeding to Layer $NEXT_LAYER... β•‘ +β•šβ•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β• +``` + +**REPEAT for next layer until all layers complete** + +#### Step 4.4: Post-Implementation Verification [MANDATORY] +```bash +# Verify build passes +npm run build +BUILD_EXIT=$? +echo "Build exit code: $BUILD_EXIT" + +# Verify type check passes +npx tsc --noEmit +TYPE_EXIT=$? +echo "Type check exit code: $TYPE_EXIT" + +# Verify lint passes +npm run lint +LINT_EXIT=$? +echo "Lint exit code: $LINT_EXIT" + +# Check all passed +if [ $BUILD_EXIT -ne 0 ] || [ $TYPE_EXIT -ne 0 ] || [ $LINT_EXIT -ne 0 ]; then + echo "❌ VERIFICATION FAILED" + [ $BUILD_EXIT -ne 0 ] && echo " - Build failed" + [ $TYPE_EXIT -ne 0 ] && echo " - Type check failed" + [ $LINT_EXIT -ne 0 ] && echo " - Lint failed" + exit 1 +fi +``` +**BLOCK IF**: Any exit code != 0 β†’ Error with 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.5: Display Implementation Summary [MANDATORY] +``` +╔══════════════════════════════════════════════════════════════╗ +β•‘ βœ… ALL LAYERS IMPLEMENTED β•‘ +╠══════════════════════════════════════════════════════════════╣ +β•‘ Layer 1: X tasks (models) βœ“ β•‘ +β•‘ Layer 2: X tasks (APIs) βœ“ β•‘ +β•‘ Layer 3: X tasks (UI) βœ“ β•‘ +╠══════════════════════════════════════════════════════════════╣ +β•‘ Total files created: X β•‘ +β•‘ Build: PASS β•‘ +β•šβ•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β• +``` + +#### Step 4.6: Complete Phase & Transition [MANDATORY] +```bash +# Save checkpoints for each completed layer +for layer in $(seq 1 $TOTAL_LAYERS); do + python3 skills/guardrail-orchestrator/scripts/phase_gate.py checkpoint layer_${layer}_complete \ + --phase IMPLEMENTING --status passed +done + +# Save build checkpoint +python3 skills/guardrail-orchestrator/scripts/phase_gate.py checkpoint build_passes \ + --phase IMPLEMENTING --status passed \ + --data "{\"exit_code\": 0}" + +# Save type-check checkpoint +python3 skills/guardrail-orchestrator/scripts/phase_gate.py checkpoint type_check_passes \ + --phase IMPLEMENTING --status passed \ + --data "{\"exit_code\": 0}" + +# Save lint checkpoint +python3 skills/guardrail-orchestrator/scripts/phase_gate.py checkpoint lint_passes \ + --phase IMPLEMENTING --status passed \ + --data "{\"exit_code\": 0}" + +# Complete the phase +python3 skills/guardrail-orchestrator/scripts/phase_gate.py complete IMPLEMENTING +COMPLETE_EXIT=$? +if [ $COMPLETE_EXIT -ne 0 ]; then + echo "❌ BLOCKED: Cannot complete IMPLEMENTING phase" + python3 skills/guardrail-orchestrator/scripts/phase_gate.py blockers + exit 1 +fi + +# Transition to next phase +python3 skills/guardrail-orchestrator/scripts/workflow_manager.py transition REVIEWING +``` + +--- + +### ═══════════════════════════════════════════════════════════════ +### PHASE 5: REVIEWING (With Fix Loop Enforcement) +### ═══════════════════════════════════════════════════════════════ + +**Entry Condition**: Phase = REVIEWING (verified via gate check) +**Exit Condition**: All checks pass, review_passed checkpoint set +**Fix Loop**: If issues found β†’ Return to IMPLEMENTING β†’ Fix β†’ Re-run review + +#### Step 5.0: Gate Entry Check [MANDATORY - BLOCKING] +```bash +# MUST pass before proceeding - HALT if fails +python3 skills/guardrail-orchestrator/scripts/phase_gate.py can-enter REVIEWING +GATE_EXIT=$? +if [ $GATE_EXIT -ne 0 ]; then + echo "❌ BLOCKED: Cannot enter REVIEWING phase" + python3 skills/guardrail-orchestrator/scripts/phase_gate.py blockers + exit 1 +fi + +# Enter the phase (records entry timestamp) +python3 skills/guardrail-orchestrator/scripts/phase_gate.py enter REVIEWING +``` + +#### Step 5.1: Run Build, Type-Check, and Lint Validation [MANDATORY] +```bash +# Run build +npm run build 2>&1 +BUILD_EXIT=$? + +# Run type check +npx tsc --noEmit 2>&1 +TYPE_EXIT=$? + +# Run lint +npm run lint 2>&1 +LINT_EXIT=$? + +# Save checkpoints +python3 skills/guardrail-orchestrator/scripts/phase_gate.py checkpoint build_verified \ + --phase REVIEWING \ + --status $([ $BUILD_EXIT -eq 0 ] && echo "passed" || echo "failed") \ + --data "{\"exit_code\": $BUILD_EXIT}" + +python3 skills/guardrail-orchestrator/scripts/phase_gate.py checkpoint type_check_verified \ + --phase REVIEWING \ + --status $([ $TYPE_EXIT -eq 0 ] && echo "passed" || echo "failed") \ + --data "{\"exit_code\": $TYPE_EXIT}" + +python3 skills/guardrail-orchestrator/scripts/phase_gate.py checkpoint lint_verified \ + --phase REVIEWING \ + --status $([ $LINT_EXIT -eq 0 ] && echo "passed" || echo "failed") \ + --data "{\"exit_code\": $LINT_EXIT}" +``` +**BLOCK IF**: Any exit != 0 β†’ Trigger fix loop + +#### Step 5.2: Spawn Code Review Agent [MANDATORY] +**Run comprehensive code review on all implemented files** + +``` +Use Task tool with: + subagent_type: "code-reviewer" + prompt: | + # CODE REVIEW AGENT - Quality Enhancement + # VERSION $VERSION_ID + + ## YOUR MISSION + Review ALL implemented files for this workflow version and identify issues + that need fixing before the workflow can proceed. + + ## REVIEW SCOPE + Task files: .workflow/versions/$VERSION_ID/tasks/*.yml + + For EACH task file: + 1. Read the task to find implementation file paths + 2. Review each implemented file + + ## REVIEW CRITERIA + + ### 1. Code Quality (CRITICAL) + - [ ] DRY violations - duplicated code that should be abstracted + - [ ] SOLID principle violations + - [ ] Dead code or unused imports + - [ ] Overly complex functions (cyclomatic complexity) + - [ ] Missing error handling + + ### 2. TypeScript Best Practices (CRITICAL) + - [ ] Any use of `any` type (should be properly typed) + - [ ] Missing type annotations on function parameters/returns + - [ ] Incorrect type assertions + - [ ] Unused type imports + + ### 3. Security Issues (CRITICAL - BLOCKING) + - [ ] Hardcoded secrets or API keys + - [ ] SQL injection vulnerabilities + - [ ] XSS vulnerabilities (unescaped user input) + - [ ] Insecure data handling + - [ ] Missing input validation + + ### 4. Performance Concerns (WARNING) + - [ ] N+1 query patterns + - [ ] Missing memoization in React components + - [ ] Unnecessary re-renders + - [ ] Large bundle imports that could be lazy-loaded + - [ ] Missing pagination for lists + + ### 5. Framework Best Practices (WARNING) + - [ ] React hooks rules violations + - [ ] Missing cleanup in useEffect + - [ ] Prop drilling that should use context + - [ ] Missing loading/error states + - [ ] Accessibility issues (missing aria labels, alt text) + + ### 6. Code Style & Maintainability (INFO) + - [ ] Inconsistent naming conventions + - [ ] Missing or outdated comments for complex logic + - [ ] Overly long files that should be split + - [ ] Magic numbers/strings that should be constants + + ## REVIEW PROCESS + + 1. **List all files to review** + ```bash + for task in .workflow/versions/$VERSION_ID/tasks/*.yml; do + grep -A 10 "to_create:" "$task" | grep -E "^\s+-" | sed 's/.*- //' + done + ``` + + 2. **For each file, run review** + - Read the file + - Check against ALL criteria above + - Note line numbers for issues + + 3. **Categorize findings by severity** + - CRITICAL: Must fix before proceeding (security, type errors) + - WARNING: Should fix, may cause problems + - INFO: Suggestions for improvement + + ## OUTPUT FORMAT + + ```yaml + # .workflow/versions/$VERSION_ID/review/code_review_report.yml + version: $VERSION_ID + reviewed_at: + reviewer: code-review-agent + + summary: + files_reviewed: X + critical_issues: X + warnings: X + info: X + verdict: PASS | NEEDS_FIX | BLOCKED + + files: + - path: "src/app/api/xxx/route.ts" + issues: + - severity: CRITICAL + line: 45 + category: security + message: "Hardcoded API key found" + suggestion: "Use environment variable" + auto_fixable: true + - severity: WARNING + line: 23 + category: performance + message: "Missing error boundary" + suggestion: "Wrap component in ErrorBoundary" + auto_fixable: false + + auto_fix_commands: + - file: "src/app/api/xxx/route.ts" + line: 45 + action: "Replace hardcoded key with process.env.API_KEY" + ``` + + ## FINAL OUTPUT + + After creating the report file, output a summary: + + ``` + === CODE REVIEW COMPLETE === + Files reviewed: X + Critical issues: X (must fix) + Warnings: X (should fix) + Info: X (suggestions) + + VERDICT: [PASS/NEEDS_FIX/BLOCKED] + + [If NEEDS_FIX or BLOCKED, list top 5 critical issues] + ``` +``` + +**Capture review results**: +```bash +REVIEW_REPORT=".workflow/versions/$VERSION_ID/review/code_review_report.yml" +if [ -f "$REVIEW_REPORT" ]; then + CRITICAL_ISSUES=$(grep "severity: CRITICAL" "$REVIEW_REPORT" | wc -l) + WARNINGS=$(grep "severity: WARNING" "$REVIEW_REPORT" | wc -l) + + python3 skills/guardrail-orchestrator/scripts/phase_gate.py checkpoint code_review_run \ + --phase REVIEWING --status passed \ + --data "{\"critical\": $CRITICAL_ISSUES, \"warnings\": $WARNINGS}" +fi +``` + +**Auto-Fix Critical Issues** (if auto_fixable): +``` +IF CRITICAL_ISSUES > 0 AND AUTO_MODE = true: + Use Task tool with: + subagent_type: "refactoring-expert" + prompt: | + # AUTO-FIX AGENT - Critical Issues + + ## MISSION + Apply automatic fixes for CRITICAL issues found in code review. + + ## SOURCE + Review report: .workflow/versions/$VERSION_ID/review/code_review_report.yml + + ## INSTRUCTIONS + 1. Read the review report + 2. For each issue with auto_fixable: true: + - Apply the suggested fix + - Verify the fix doesn't break anything + 3. Run: npm run build && npx tsc --noEmit && npm run lint + 4. If all pass, report success + 5. If any fail, report which issues couldn't be auto-fixed + + ## OUTPUT + List of: + - Successfully auto-fixed issues + - Issues requiring manual intervention +``` + +#### Step 5.3: Generate Implementation Visualization [MANDATORY] +```bash +python3 skills/guardrail-orchestrator/scripts/visualize_implementation.py --manifest project_manifest.json +``` + +#### Step 5.4: Verify All Task Files Exist [MANDATORY] +```bash +python3 skills/guardrail-orchestrator/scripts/verify_implementation.py --version $VERSION_ID +VERIFY_EXIT=$? +ISSUES_FOUND=$(python3 skills/guardrail-orchestrator/scripts/verify_implementation.py --version $VERSION_ID --json | jq '.missing_files | length') + +# Save checkpoint +python3 skills/guardrail-orchestrator/scripts/phase_gate.py checkpoint all_files_verified \ + --phase REVIEWING \ + --status $([ $VERIFY_EXIT -eq 0 ] && echo "passed" || echo "failed") \ + --data "{\"missing_count\": $ISSUES_FOUND}" +``` + +#### Step 5.5: Review Decision with Fix Loop [MANDATORY] + +##### Collect All Issues +```bash +REVIEW_ISSUES=() + +if [ $BUILD_EXIT -ne 0 ]; then + REVIEW_ISSUES+=("Build failed with exit code $BUILD_EXIT") +fi + +if [ $TYPE_EXIT -ne 0 ]; then + REVIEW_ISSUES+=("Type check failed with exit code $TYPE_EXIT") +fi + +if [ $LINT_EXIT -ne 0 ]; then + REVIEW_ISSUES+=("Lint failed with exit code $LINT_EXIT") +fi + +if [ $ISSUES_FOUND -gt 0 ]; then + REVIEW_ISSUES+=("$ISSUES_FOUND implementation files missing") +fi + +# Check code review results +REVIEW_REPORT=".workflow/versions/$VERSION_ID/review/code_review_report.yml" +if [ -f "$REVIEW_REPORT" ]; then + CODE_CRITICAL=$(grep "severity: CRITICAL" "$REVIEW_REPORT" | wc -l | tr -d ' ') + if [ "$CODE_CRITICAL" -gt 0 ]; then + REVIEW_ISSUES+=("Code review found $CODE_CRITICAL CRITICAL issues") + fi +fi +``` + +##### IF Issues Found β†’ TRIGGER FIX LOOP [CRITICAL] +```bash +if [ ${#REVIEW_ISSUES[@]} -gt 0 ]; then + echo "❌ REVIEW FAILED - FIX LOOP TRIGGERED" + echo "" + echo "╔══════════════════════════════════════════════════════════════╗" + echo "β•‘ πŸ”§ FIX LOOP: Returning to IMPLEMENTING β•‘" + echo "╠══════════════════════════════════════════════════════════════╣" + echo "β•‘ Issues that MUST be fixed: β•‘" + for issue in "${REVIEW_ISSUES[@]}"; do + echo "β•‘ β€’ $issue" + done + echo "╠══════════════════════════════════════════════════════════════╣" + echo "β•‘ πŸ‘‰ NEXT STEPS: β•‘" + echo "β•‘ 1. Fix the issues listed above β•‘" + echo "β•‘ 2. Run: npm run build (verify it passes) β•‘" + echo "β•‘ 3. Run: npx tsc --noEmit (verify type check passes) β•‘" + echo "β•‘ 4. Run: npm run lint (verify lint passes) β•‘" + echo "β•‘ 5. Fix any CRITICAL code review issues β•‘" + echo "β•‘ 6. Run: /workflow:resume β•‘" + echo "β•‘ β•‘" + echo "β•‘ The workflow will automatically re-run REVIEWING after fix β•‘" + echo "β•šβ•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•" + + # Show code review details if issues exist + REVIEW_REPORT=".workflow/versions/$VERSION_ID/review/code_review_report.yml" + if [ -f "$REVIEW_REPORT" ]; then + echo "" + echo "πŸ“‹ CODE REVIEW ISSUES:" + echo "────────────────────────────────────────────────────────────────" + grep -A 5 "severity: CRITICAL" "$REVIEW_REPORT" | head -30 + echo "" + echo "Full report: $REVIEW_REPORT" + echo "────────────────────────────────────────────────────────────────" + fi + + # Trigger fix loop - returns to IMPLEMENTING + python3 skills/guardrail-orchestrator/scripts/phase_gate.py fix-loop REVIEWING \ + --issues "${REVIEW_ISSUES[@]}" + + # Transition back to IMPLEMENTING + python3 skills/guardrail-orchestrator/scripts/workflow_manager.py transition IMPLEMENTING + + # HALT - Must fix before continuing + exit 1 +fi +``` + +##### IF No Issues β†’ PASS Review +```bash +# All checks passed - save code_review_passed checkpoint +python3 skills/guardrail-orchestrator/scripts/phase_gate.py checkpoint code_review_passed \ + --phase REVIEWING \ + --status passed \ + --data "{\"critical_issues\": 0}" + +# Save review_passed checkpoint (umbrella checkpoint) +python3 skills/guardrail-orchestrator/scripts/phase_gate.py checkpoint review_passed \ + --phase REVIEWING \ + --status passed \ + --data "{\"build\": \"passed\", \"type_check\": \"passed\", \"lint\": \"passed\", \"files\": \"verified\", \"code_review\": \"passed\"}" + +# Mark phase complete +python3 skills/guardrail-orchestrator/scripts/phase_gate.py complete REVIEWING +``` + +#### Step 5.6: Display Review Report [MANDATORY] +``` +╔══════════════════════════════════════════════════════════════╗ +β•‘ πŸ” REVIEW RESULTS β•‘ +╠══════════════════════════════════════════════════════════════╣ +β•‘ Build: βœ… PASS β•‘ +β•‘ Type Check: βœ… PASS β•‘ +β•‘ Lint: βœ… PASS β•‘ +β•‘ Files: βœ… All exist β•‘ +β•‘ Code Review: βœ… No CRITICAL issues β•‘ +╠══════════════════════════════════════════════════════════════╣ +β•‘ IMPLEMENTATION SUMMARY β•‘ +β•‘ Pages: X implemented β•‘ +β•‘ Components: X implemented β•‘ +β•‘ API Endpoints: X implemented β•‘ +╠══════════════════════════════════════════════════════════════╣ +β•‘ βœ… Proceeding to SECURITY_REVIEW... β•‘ +β•šβ•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β• +``` + +#### Step 5.7: Transition to Security Review [MANDATORY] +```bash +python3 skills/guardrail-orchestrator/scripts/workflow_manager.py transition SECURITY_REVIEW +``` + +--- + +### ═══════════════════════════════════════════════════════════════ +### PHASE 5.5: SECURITY REVIEW (With Fix Loop Enforcement) +### ═══════════════════════════════════════════════════════════════ + +**Entry Condition**: Phase = SECURITY_REVIEW (verified via gate check) +**Exit Condition**: Security scan passes, security_passed checkpoint set +**Fix Loop**: If CRITICAL/HIGH issues found β†’ Return to IMPLEMENTING β†’ Fix β†’ Re-run security + +#### Step 5.5.0: Gate Entry Check [MANDATORY - BLOCKING] +```bash +# MUST pass before proceeding - HALT if fails +python3 skills/guardrail-orchestrator/scripts/phase_gate.py can-enter SECURITY_REVIEW +GATE_EXIT=$? +if [ $GATE_EXIT -ne 0 ]; then + echo "❌ BLOCKED: Cannot enter SECURITY_REVIEW phase" + python3 skills/guardrail-orchestrator/scripts/phase_gate.py blockers + exit 1 +fi + +# Enter the phase (records entry timestamp) +python3 skills/guardrail-orchestrator/scripts/phase_gate.py enter SECURITY_REVIEW +``` + +#### Step 5.5.1: Run Security Scanner [MANDATORY] +```bash +python3 skills/guardrail-orchestrator/scripts/security_scan.py \ + --project-dir . \ + --severity HIGH +SECURITY_EXIT=$? + +# Capture security report for fix loop +SECURITY_REPORT=$(python3 skills/guardrail-orchestrator/scripts/security_scan.py \ + --project-dir . --severity HIGH --json 2>/dev/null || echo '{}') +CRITICAL_COUNT=$(echo "$SECURITY_REPORT" | jq '.by_severity.CRITICAL // 0') +HIGH_COUNT=$(echo "$SECURITY_REPORT" | jq '.by_severity.HIGH // 0') + +# Save checkpoint +python3 skills/guardrail-orchestrator/scripts/phase_gate.py checkpoint security_scan_run \ + --phase SECURITY_REVIEW \ + --status $([ $SECURITY_EXIT -le 1 ] && echo "passed" || echo "failed") \ + --data "{\"exit_code\": $SECURITY_EXIT, \"critical\": $CRITICAL_COUNT, \"high\": $HIGH_COUNT}" +``` + +**Exit codes:** +- 0 = PASS (no critical/high issues) +- 1 = HIGH issues found (triggers fix loop in strict mode) +- 2 = CRITICAL issues found (ALWAYS triggers fix loop) + +#### Step 5.5.2: API Contract Validation [MANDATORY] +```bash +python3 skills/guardrail-orchestrator/scripts/validate_api_contract.py \ + --project-dir . +API_EXIT=$? + +# Save checkpoint +python3 skills/guardrail-orchestrator/scripts/phase_gate.py checkpoint api_contract_validated \ + --phase SECURITY_REVIEW \ + --status $([ $API_EXIT -eq 0 ] && echo "passed" || echo "failed") \ + --data "{\"exit_code\": $API_EXIT}" +``` + +#### Step 5.5.3: Security Decision with Fix Loop [MANDATORY - CRITICAL] + +##### Collect All Security Issues +```bash +SECURITY_ISSUES=() + +if [ $SECURITY_EXIT -eq 2 ]; then + SECURITY_ISSUES+=("CRITICAL: $CRITICAL_COUNT critical security vulnerabilities found") +fi + +if [ $SECURITY_EXIT -eq 1 ]; then + SECURITY_ISSUES+=("HIGH: $HIGH_COUNT high severity security issues found") +fi + +if [ $API_EXIT -ne 0 ]; then + SECURITY_ISSUES+=("API Contract: Frontend-backend API mismatch detected") +fi +``` + +##### IF CRITICAL Issues Found β†’ TRIGGER FIX LOOP [MANDATORY] +```bash +if [ $SECURITY_EXIT -eq 2 ]; then + echo "❌ CRITICAL SECURITY ISSUES - FIX LOOP TRIGGERED" + echo "" + echo "╔══════════════════════════════════════════════════════════════╗" + echo "β•‘ 🚨 SECURITY FIX REQUIRED - CRITICAL ISSUES β•‘" + echo "╠══════════════════════════════════════════════════════════════╣" + echo "β•‘ CRITICAL issues MUST be fixed before workflow can continue β•‘" + echo "╠══════════════════════════════════════════════════════════════╣" + echo "β•‘ Issues found: β•‘" + for issue in "${SECURITY_ISSUES[@]}"; do + echo "β•‘ β€’ $issue" + done + echo "╠══════════════════════════════════════════════════════════════╣" + echo "β•‘ πŸ‘‰ REQUIRED ACTIONS: β•‘" + echo "β•‘ 1. Review security report above β•‘" + echo "β•‘ 2. Fix ALL critical vulnerabilities β•‘" + echo "β•‘ 3. Run: /workflow:resume β•‘" + echo "β•‘ β•‘" + echo "β•‘ Common fixes: β•‘" + echo "β•‘ - Remove hardcoded secrets β†’ use env vars β•‘" + echo "β•‘ - Fix SQL injection β†’ use parameterized queries β•‘" + echo "β•‘ - Fix XSS β†’ sanitize user input β•‘" + echo "β•šβ•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•" + + # Trigger fix loop - returns to IMPLEMENTING + python3 skills/guardrail-orchestrator/scripts/phase_gate.py fix-loop SECURITY_REVIEW \ + --issues "${SECURITY_ISSUES[@]}" + + # Transition back to IMPLEMENTING + python3 skills/guardrail-orchestrator/scripts/workflow_manager.py transition IMPLEMENTING + + # HALT - Must fix before continuing + exit 1 +fi +``` + +##### IF HIGH Issues Found (--auto mode) β†’ WARNING but allow continue +```bash +if [ $SECURITY_EXIT -eq 1 ]; then + echo "⚠️ HIGH SEVERITY SECURITY ISSUES FOUND" + echo "" + echo "╔══════════════════════════════════════════════════════════════╗" + echo "β•‘ ⚠️ SECURITY WARNING - HIGH SEVERITY ISSUES β•‘" + echo "╠══════════════════════════════════════════════════════════════╣" + echo "β•‘ $HIGH_COUNT high severity issues detected β•‘" + echo "β•‘ β•‘" + echo "β•‘ In AUTO mode: Proceeding with warning β•‘" + echo "β•‘ Recommendation: Fix these issues before production deploy β•‘" + echo "β•šβ•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•" + + # Log warning but continue in auto mode + # In manual mode, this would ask the user +fi +``` + +##### IF API Contract Failed β†’ TRIGGER FIX LOOP [MANDATORY] +```bash +if [ $API_EXIT -ne 0 ]; then + echo "❌ API CONTRACT VALIDATION FAILED - FIX LOOP TRIGGERED" + echo "" + echo "╔══════════════════════════════════════════════════════════════╗" + echo "β•‘ πŸ”Œ API CONTRACT MISMATCH β•‘" + echo "╠══════════════════════════════════════════════════════════════╣" + echo "β•‘ Frontend API calls don't match backend endpoints β•‘" + echo "╠══════════════════════════════════════════════════════════════╣" + echo "β•‘ πŸ‘‰ REQUIRED ACTIONS: β•‘" + echo "β•‘ 1. Check that all frontend fetch/axios calls exist β•‘" + echo "β•‘ 2. Verify HTTP methods match (GET/POST/PUT/DELETE) β•‘" + echo "β•‘ 3. Ensure request bodies are correct β•‘" + echo "β•‘ 4. Run: /workflow:resume β•‘" + echo "β•šβ•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•" + + # Trigger fix loop + python3 skills/guardrail-orchestrator/scripts/phase_gate.py fix-loop SECURITY_REVIEW \ + --issues "API contract validation failed" + + python3 skills/guardrail-orchestrator/scripts/workflow_manager.py transition IMPLEMENTING + exit 1 +fi +``` + +##### IF All Passed β†’ Complete Security Review +```bash +# All checks passed - save security_passed checkpoint +python3 skills/guardrail-orchestrator/scripts/phase_gate.py checkpoint security_passed \ + --phase SECURITY_REVIEW \ + --status passed \ + --data "{\"security\": \"passed\", \"api_contract\": \"passed\"}" + +# Mark phase complete +python3 skills/guardrail-orchestrator/scripts/phase_gate.py complete SECURITY_REVIEW +``` + +#### Step 5.5.4: Display Security Report [MANDATORY] +``` +╔══════════════════════════════════════════════════════════════╗ +β•‘ πŸ”’ SECURITY REVIEW RESULTS β•‘ +╠══════════════════════════════════════════════════════════════╣ +β•‘ Security Scan: βœ… PASS / ⚠️ WARNING / ❌ CRITICAL β•‘ +β•‘ Critical: X issues β•‘ +β•‘ High: X issues β•‘ +β•‘ Medium: X issues β•‘ +β•‘ Low: X issues β•‘ +╠══════════════════════════════════════════════════════════════╣ +β•‘ API Contract: βœ… PASS / ❌ FAIL β•‘ +β•‘ Matched calls: X β•‘ +β•‘ Unmatched: X β•‘ +β•‘ Method errors: X β•‘ +╠══════════════════════════════════════════════════════════════╣ +β•‘ VERDICT: βœ… APPROVED / πŸ”§ NEEDS_FIXES β•‘ +β•šβ•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β• +``` + +#### Step 5.5.5: Transition to Approval [MANDATORY] +```bash +python3 skills/guardrail-orchestrator/scripts/workflow_manager.py transition AWAITING_IMPL_APPROVAL +``` + +--- + +### ═══════════════════════════════════════════════════════════════ +### PHASE 6: GATE 2 - Implementation Approval +### ═══════════════════════════════════════════════════════════════ + +**Entry Condition**: Phase = AWAITING_IMPL_APPROVAL (verified via gate check) +**Exit Condition**: Implementation approved, phase = COMPLETING + +#### Step 6.0: Gate Entry Check [MANDATORY - BLOCKING] +```bash +# MUST pass before proceeding - HALT if fails +python3 skills/guardrail-orchestrator/scripts/phase_gate.py can-enter AWAITING_IMPL_APPROVAL +GATE_EXIT=$? +if [ $GATE_EXIT -ne 0 ]; then + echo "❌ BLOCKED: Cannot enter AWAITING_IMPL_APPROVAL phase" + python3 skills/guardrail-orchestrator/scripts/phase_gate.py blockers + exit 1 +fi + +# Enter the phase (records entry timestamp) +python3 skills/guardrail-orchestrator/scripts/phase_gate.py enter AWAITING_IMPL_APPROVAL +``` + +#### IF AUTO_MODE = true: +```bash +# Auto-approve since review and security checks passed +python3 skills/guardrail-orchestrator/scripts/phase_gate.py checkpoint implementation_approved \ + --phase AWAITING_IMPL_APPROVAL --status passed \ + --data "{\"approver\": \"auto\", \"mode\": \"auto\"}" + +# Complete the phase +python3 skills/guardrail-orchestrator/scripts/phase_gate.py complete AWAITING_IMPL_APPROVAL + +python3 skills/guardrail-orchestrator/scripts/workflow_manager.py approve implementation +python3 skills/guardrail-orchestrator/scripts/workflow_manager.py transition COMPLETING +``` +Output: "βœ… Implementation auto-approved. Proceeding to completion." + +#### 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 +# Save approval checkpoint +python3 skills/guardrail-orchestrator/scripts/phase_gate.py checkpoint implementation_approved \ + --phase AWAITING_IMPL_APPROVAL --status passed \ + --data "{\"approver\": \"user\", \"mode\": \"manual\"}" + +# Complete the phase +python3 skills/guardrail-orchestrator/scripts/phase_gate.py complete AWAITING_IMPL_APPROVAL + +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 via gate check) +**Exit Condition**: Version marked complete, success report displayed + +#### Step 7.0: Gate Entry Check [MANDATORY - BLOCKING] +```bash +# MUST pass before proceeding - HALT if fails +python3 skills/guardrail-orchestrator/scripts/phase_gate.py can-enter COMPLETING +GATE_EXIT=$? +if [ $GATE_EXIT -ne 0 ]; then + echo "❌ BLOCKED: Cannot enter COMPLETING phase" + python3 skills/guardrail-orchestrator/scripts/phase_gate.py blockers + exit 1 +fi + +# Enter the phase (records entry timestamp) +python3 skills/guardrail-orchestrator/scripts/phase_gate.py enter COMPLETING +``` + +#### 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 & Phase [MANDATORY] +```bash +# Save checkpoints +python3 skills/guardrail-orchestrator/scripts/phase_gate.py checkpoint tasks_marked_complete \ + --phase COMPLETING --status passed +python3 skills/guardrail-orchestrator/scripts/phase_gate.py checkpoint manifest_updated \ + --phase COMPLETING --status passed + +# Complete the version +python3 skills/guardrail-orchestrator/scripts/version_manager.py complete +VERSION_EXIT=$? + +# Save version completion checkpoint +python3 skills/guardrail-orchestrator/scripts/phase_gate.py checkpoint version_finalized \ + --phase COMPLETING --status $([ $VERSION_EXIT -eq 0 ] && echo "passed" || echo "failed") + +if [ $VERSION_EXIT -ne 0 ]; then + echo "❌ BLOCKED: Version finalization failed" + exit 1 +fi + +# Complete the COMPLETING phase +python3 skills/guardrail-orchestrator/scripts/phase_gate.py complete COMPLETING + +# Transition to final COMPLETED state +python3 skills/guardrail-orchestrator/scripts/phase_gate.py enter COMPLETED +python3 skills/guardrail-orchestrator/scripts/phase_gate.py complete COMPLETED +``` +**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 diff --git a/skills/documentation-generator/agents/doc-writer.yml b/skills/documentation-generator/agents/doc-writer.yml new file mode 100644 index 0000000..06f8b56 --- /dev/null +++ b/skills/documentation-generator/agents/doc-writer.yml @@ -0,0 +1,152 @@ +# Documentation Writer Agent +# Specialized agent for generating dual-audience documentation + +name: doc-writer +role: Documentation Specialist +description: | + Expert in creating comprehensive documentation that serves both technical + and non-technical audiences. Specializes in translating complex technical + concepts into accessible language while maintaining technical accuracy. + +capabilities: + - Analyze project structure and extract key information + - Generate visual ASCII diagrams for architecture + - Write plain-language descriptions of technical features + - Create technical reference documentation + - Build glossaries for technical terms + - Structure documentation for multiple audience levels + +allowed_tools: + - Read + - Write + - Edit + - Glob + - Grep + - Bash + +blocked_tools: + - Task # Should not spawn sub-agents + +allowed_files: + - "docs/**/*" + - "*.md" + - "package.json" + - "project_manifest.json" + - "tsconfig.json" + - "requirements.txt" + - "pyproject.toml" + - "Cargo.toml" + - "go.mod" + +responsibilities: + - Analyze source code to understand functionality + - Extract API endpoints and document them + - Document components with props and usage + - Create ER diagrams for data models + - Write executive summaries for stakeholders + - Build glossaries for technical terms + - Generate quick reference cards + +outputs: + - PROJECT_DOCUMENTATION.md (main documentation) + - QUICK_REFERENCE.md (one-page summary) + - API_REFERENCE.md (detailed API docs) + - COMPONENTS.md (component catalog) + - GLOSSARY.md (term definitions) + +cannot_do: + - Modify source code + - Change project configuration + - Run tests or builds + - Deploy or publish + +writing_principles: + non_technical: + - Lead with "What" and "Why", not "How" + - Use analogies and real-world comparisons + - Avoid acronyms; spell them out first time + - Use bullet points over paragraphs + - Include visual diagrams + - Focus on value and outcomes + + technical: + - Include in collapsible
sections + - Provide code examples with syntax highlighting + - Reference file paths and line numbers + - Include type definitions and interfaces + - Link to source files + - Document edge cases and error handling + +documentation_sections: + executive_summary: + audience: everyone + purpose: Project purpose, value proposition, key capabilities + format: Plain English, no jargon + + architecture_overview: + audience: everyone + purpose: Visual system understanding + format: ASCII diagrams, technology tables + + getting_started: + audience: semi-technical + purpose: Quick onboarding + format: Step-by-step with explanations + + feature_guide: + audience: non-technical + purpose: Feature documentation + format: What/Why/How (simplified) + + api_reference: + audience: developers + purpose: API documentation + format: Endpoints, schemas, examples + + component_catalog: + audience: developers + purpose: UI component documentation + format: Props, events, usage examples + + data_models: + audience: both + purpose: Data structure documentation + format: ER diagrams + plain descriptions + + glossary: + audience: non-technical + purpose: Term definitions + format: Term -> Plain English definition + +ascii_diagram_templates: + system_architecture: | + β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” + β”‚ [System Name] β”‚ + β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ + β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ + β”‚ β”‚ [Layer] │───▢│ [Layer] │───▢│ [Layer] β”‚ β”‚ + β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ + β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + + entity_relationship: | + β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” + β”‚ [Entity] β”‚ β”‚ [Entity] β”‚ + β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ + β”‚ id (PK) │──────▢│ id (PK) β”‚ + β”‚ field β”‚ β”‚ foreign_key β”‚ + β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + + data_flow: | + [Source] ──▢ [Process] ──▢ [Output] + β”‚ β”‚ β”‚ + β–Ό β–Ό β–Ό + [Storage] [Transform] [Display] + +quality_checklist: + - All referenced files exist + - All code examples are syntactically correct + - No broken internal links + - Technical details wrapped in
+ - Plain English explanations for all features + - Glossary includes all technical terms used + - ASCII diagrams render correctly in markdown diff --git a/skills/documentation-generator/schemas/documentation_output.yml b/skills/documentation-generator/schemas/documentation_output.yml new file mode 100644 index 0000000..2a3e335 --- /dev/null +++ b/skills/documentation-generator/schemas/documentation_output.yml @@ -0,0 +1,274 @@ +# Documentation Output Schema +# Defines the structure for generated documentation + +version: "1.0" +description: Schema for dual-audience project documentation + +output_files: + main_documentation: + filename: PROJECT_DOCUMENTATION.md + required: true + sections: + - executive_summary + - quick_start + - architecture_overview + - features + - for_developers + - glossary + + quick_reference: + filename: QUICK_REFERENCE.md + required: true + sections: + - commands + - key_files + - api_endpoints + - environment_variables + + api_reference: + filename: API_REFERENCE.md + required: false + condition: has_api_endpoints + sections: + - authentication + - endpoints_by_resource + - error_codes + - rate_limiting + + components: + filename: COMPONENTS.md + required: false + condition: has_ui_components + sections: + - component_index + - component_details + - usage_examples + +section_schemas: + executive_summary: + description: High-level project overview for all audiences + fields: + project_name: + type: string + required: true + tagline: + type: string + required: true + max_length: 100 + description: One-line description in plain English + what_it_does: + type: string + required: true + description: 2-3 sentences, no technical jargon + who_its_for: + type: string + required: true + description: Target audience in plain English + key_capabilities: + type: array + items: + capability: string + description: string + min_items: 3 + max_items: 8 + + quick_start: + description: Getting started guide for new users + fields: + prerequisites: + type: array + items: + tool: string + purpose: string # Plain English explanation + install_command: string + installation_steps: + type: array + items: + step: integer + command: string + explanation: string # What this does + basic_usage: + type: string + description: Simple example of how to use + + architecture_overview: + description: Visual system architecture + fields: + system_diagram: + type: string + format: ascii_art + required: true + technology_stack: + type: array + items: + layer: string + technology: string + purpose: string # Plain English + directory_structure: + type: string + format: tree + required: true + + features: + description: Feature documentation for all audiences + fields: + features: + type: array + items: + name: string + what_it_does: string # Plain English + how_to_use: string # Simple instructions + example: string # Code or usage example + technical_notes: string # For engineers, optional + + api_endpoint: + description: Single API endpoint documentation + fields: + method: + type: enum + values: [GET, POST, PUT, PATCH, DELETE] + path: + type: string + pattern: "^/api/" + summary: + type: string + description: Plain English description + description: + type: string + description: Detailed explanation + authentication: + type: object + fields: + required: boolean + type: string # bearer, api_key, session + request: + type: object + fields: + content_type: string + body_schema: object + query_params: array + path_params: array + responses: + type: array + items: + status: integer + description: string + schema: object + examples: + type: array + items: + name: string + request: object + response: object + + component: + description: UI component documentation + fields: + name: + type: string + pattern: "^[A-Z][a-zA-Z]*$" # PascalCase + path: + type: string + description: + type: string + description: Plain English purpose + props: + type: array + items: + name: string + type: string + required: boolean + default: any + description: string + events: + type: array + items: + name: string + payload: string + description: string + usage_example: + type: string + format: code + dependencies: + type: array + items: string + + data_model: + description: Data model documentation + fields: + name: + type: string + description: + type: string + description: What data it represents (plain English) + table_name: + type: string + fields: + type: array + items: + name: string + type: string + description: string # Plain English + constraints: array + relations: + type: array + items: + type: enum + values: [has_one, has_many, belongs_to, many_to_many] + target: string + description: string + + glossary_term: + description: Technical term definition + fields: + term: + type: string + required: true + definition: + type: string + required: true + description: Plain English definition + see_also: + type: array + items: string + description: Related terms + +audience_markers: + non_technical: + indicator: "πŸ“–" + description: "For all readers" + technical: + indicator: "πŸ”§" + description: "For developers" + wrapper: "
πŸ”§ Technical Details...content...
" + +formatting_rules: + headings: + h1: "# Title" + h2: "## Section" + h3: "### Subsection" + code_blocks: + language_hints: required + max_lines: 30 + tables: + alignment: left + max_columns: 5 + diagrams: + format: ascii_art + max_width: 80 + links: + internal: "[text](#anchor)" + external: "[text](url)" + file_reference: "`path/to/file`" + +validation_rules: + - name: no_broken_links + description: All internal links must resolve + - name: code_syntax + description: All code blocks must be syntactically valid + - name: file_references + description: All referenced files must exist + - name: glossary_coverage + description: All technical terms must be in glossary + - name: diagram_rendering + description: ASCII diagrams must render correctly diff --git a/skills/documentation-generator/schemas/project_analysis.yml b/skills/documentation-generator/schemas/project_analysis.yml new file mode 100644 index 0000000..23ad329 --- /dev/null +++ b/skills/documentation-generator/schemas/project_analysis.yml @@ -0,0 +1,272 @@ +# Project Analysis Schema +# Defines the structure for project analysis output + +version: "1.0" +description: Schema for analyzing project structure before documentation generation + +project_analysis: + project: + type: object + required: true + fields: + name: + type: string + required: true + source: package.json/name or directory name + version: + type: string + required: false + source: package.json/version + description: + type: string + required: false + source: package.json/description or README.md first paragraph + type: + type: enum + values: [node, python, rust, go, java, dotnet, ruby, php, other] + detection: + node: package.json + python: requirements.txt, pyproject.toml, setup.py + rust: Cargo.toml + go: go.mod + java: pom.xml, build.gradle + dotnet: "*.csproj, *.sln" + ruby: Gemfile + php: composer.json + repository: + type: string + source: package.json/repository or .git/config + + tech_stack: + type: object + required: true + fields: + language: + type: string + description: Primary programming language + framework: + type: string + description: Main application framework + detection: + next: "next" in dependencies + react: "react" in dependencies without "next" + vue: "vue" in dependencies + angular: "@angular/core" in dependencies + express: "express" in dependencies + fastapi: "fastapi" in requirements + django: "django" in requirements + flask: "flask" in requirements + rails: "rails" in Gemfile + database: + type: string + description: Database system if any + detection: + prisma: "@prisma/client" in dependencies + mongoose: "mongoose" in dependencies + typeorm: "typeorm" in dependencies + sequelize: "sequelize" in dependencies + sqlalchemy: "sqlalchemy" in requirements + ui_framework: + type: string + description: UI component framework if any + detection: + tailwind: "tailwindcss" in devDependencies + mui: "@mui/material" in dependencies + chakra: "@chakra-ui/react" in dependencies + shadcn: "shadcn" patterns in components + key_dependencies: + type: array + items: + name: string + version: string + purpose: string # Plain English explanation + categorization: + core: Framework, runtime dependencies + database: ORM, database clients + auth: Authentication libraries + ui: UI component libraries + testing: Test frameworks + build: Build tools, bundlers + utility: Helper libraries + + structure: + type: object + required: true + fields: + source_dir: + type: string + description: Main source code directory + detection: + - src/ + - app/ + - lib/ + - source/ + directories: + type: array + items: + path: string + purpose: string # Plain English description + file_count: integer + key_files: array + common_mappings: + src/components: "UI components" + src/pages: "Application pages/routes" + src/api: "API route handlers" + src/lib: "Utility functions and shared code" + src/hooks: "Custom React hooks" + src/context: "React context providers" + src/store: "State management" + src/types: "TypeScript type definitions" + src/styles: "Global styles and themes" + prisma/: "Database schema and migrations" + public/: "Static assets" + tests/: "Test files" + __tests__/: "Test files (Jest convention)" + + features: + type: array + description: Main features/capabilities of the project + items: + name: string + description: string # Plain English + technical_notes: string # For engineers + files: array # Key file paths + detection_patterns: + authentication: + keywords: [auth, login, logout, session, jwt, oauth] + files: ["**/auth/**", "**/login/**"] + user_management: + keywords: [user, profile, account, register, signup] + files: ["**/user/**", "**/users/**"] + api: + keywords: [api, endpoint, route, handler] + files: ["**/api/**", "**/routes/**"] + database: + keywords: [model, entity, schema, migration, prisma] + files: ["**/models/**", "**/prisma/**"] + file_upload: + keywords: [upload, file, storage, s3, blob] + files: ["**/upload/**", "**/storage/**"] + search: + keywords: [search, filter, query] + files: ["**/search/**"] + notifications: + keywords: [notification, email, sms, push] + files: ["**/notification/**", "**/email/**"] + + components: + type: array + description: UI components found in the project + items: + id: string # component_ + name: string # PascalCase + path: string + description: string + props: string # Props summary + dependencies: array # Imported components + detection: + react: "export (default )?(function|const) [A-Z]" + vue: "