feat: unified workflow format with semantic tags (GSD-style)
Phase 4: Unified Single-File Workflow Format - Convert super-dev-pipeline workflow.md to GSD-style format - Add semantic tags: <purpose>, <philosophy>, <config>, <process>, <step> - Inline config (previously separate workflow.yaml) - Steps have names and priority attributes - Agent prompts use <execution_context>, <objective>, <constraints> - Reconciliation step explicitly marked as orchestrator work - Cleaner, more readable format Old: 523 lines (prose + code blocks mixed) New: 397 lines (semantic structure) - 24% reduction Next: Apply same pattern to batch-super-dev workflow.
This commit is contained in:
Jonah Schulte
parent
46ec840235
commit
f46926cb25
|
|
@ -1,522 +1,396 @@
|
||||||
# Super-Dev-Pipeline v2.1 - Multi-Agent Architecture
|
# Super-Dev-Pipeline v3.0 - Unified Workflow
|
||||||
|
|
||||||
**Version:** 2.1.0
|
<purpose>
|
||||||
**Architecture:** GSDMAD (GSD + BMAD)
|
Implement a story using 4 independent agents with orchestrator-driven reconciliation.
|
||||||
**Philosophy:** Agents do creative work, orchestrator does bookkeeping
|
Each agent has single responsibility. No agent validates its own work.
|
||||||
|
Orchestrator handles bookkeeping (story file updates, verification).
|
||||||
|
</purpose>
|
||||||
|
|
||||||
---
|
<philosophy>
|
||||||
|
**Agents do creative work. Orchestrator does bookkeeping.**
|
||||||
|
|
||||||
## Overview
|
- Builder implements (creative)
|
||||||
|
- Inspector validates (verification)
|
||||||
|
- Reviewer finds issues (adversarial)
|
||||||
|
- Fixer resolves issues (creative)
|
||||||
|
- Orchestrator reconciles story file (mechanical)
|
||||||
|
|
||||||
This workflow implements a story using **4 independent agents** with orchestrator-driven reconciliation.
|
Trust but verify. Fresh context per phase. Adversarial review.
|
||||||
|
</philosophy>
|
||||||
|
|
||||||
**Key Innovation:**
|
<config>
|
||||||
- Each agent has single responsibility and fresh context
|
name: super-dev-pipeline
|
||||||
- No agent validates its own work
|
version: 3.0.0
|
||||||
- **Orchestrator does bookkeeping** (story file updates, verification) - not agents
|
execution_mode: multi_agent
|
||||||
|
|
||||||
---
|
agents:
|
||||||
|
builder: {steps: 1-4, trust: low, timeout: 60min}
|
||||||
|
inspector: {steps: 5-6, trust: medium, fresh_context: true, timeout: 30min}
|
||||||
|
reviewer: {steps: 7, trust: high, adversarial: true, timeout: 30min}
|
||||||
|
fixer: {steps: 8-9, trust: medium, timeout: 40min}
|
||||||
|
|
||||||
## Execution Flow
|
complexity_routing:
|
||||||
|
micro: {skip: [reviewer], description: "Low-risk stories"}
|
||||||
|
standard: {skip: [], description: "Normal stories"}
|
||||||
|
complex: {skip: [], enhanced_review: true, description: "High-risk stories"}
|
||||||
|
</config>
|
||||||
|
|
||||||
```
|
<execution_context>
|
||||||
┌─────────────────────────────────────────────────────────────┐
|
@patterns/hospital-grade.md
|
||||||
│ Main Orchestrator (Claude) │
|
@patterns/agent-completion.md
|
||||||
│ - Loads story │
|
</execution_context>
|
||||||
│ - Spawns agents sequentially │
|
|
||||||
│ - Verifies each phase │
|
<process>
|
||||||
│ - DOES RECONCILIATION DIRECTLY (not via agent) │
|
|
||||||
│ - Final quality gate │
|
<step name="load_story" priority="first">
|
||||||
└─────────────────────────────────────────────────────────────┘
|
Load and validate the story file.
|
||||||
│
|
|
||||||
├──> Phase 1: Builder (Steps 1-4) [AGENT]
|
```bash
|
||||||
│ - Load story, analyze gaps
|
STORY_FILE="docs/sprint-artifacts/{{story_key}}.md"
|
||||||
│ - Write tests (TDD)
|
[ -f "$STORY_FILE" ] || { echo "ERROR: Story file not found"; exit 1; }
|
||||||
│ - Implement code
|
|
||||||
│ - Report what was built (NO VALIDATION)
|
|
||||||
│
|
|
||||||
├──> Phase 2: Inspector (Steps 5-6) [AGENT]
|
|
||||||
│ - Fresh context, no Builder knowledge
|
|
||||||
│ - Verify files exist
|
|
||||||
│ - Run tests independently
|
|
||||||
│ - Run quality checks
|
|
||||||
│ - PASS or FAIL verdict
|
|
||||||
│
|
|
||||||
├──> Phase 3: Reviewer (Step 7) [AGENT]
|
|
||||||
│ - Fresh context, adversarial stance
|
|
||||||
│ - Find security vulnerabilities
|
|
||||||
│ - Find performance problems
|
|
||||||
│ - Find logic bugs
|
|
||||||
│ - Report issues with severity
|
|
||||||
│
|
|
||||||
├──> Phase 4: Fixer (Steps 8-9) [AGENT]
|
|
||||||
│ - Fix CRITICAL issues (all)
|
|
||||||
│ - Fix HIGH issues (all)
|
|
||||||
│ - Fix MEDIUM issues (if time)
|
|
||||||
│ - Skip LOW issues (gold-plating)
|
|
||||||
│ - Commit code changes
|
|
||||||
│
|
|
||||||
├──> Phase 5: Reconciliation (Step 10) [ORCHESTRATOR] 🔧
|
|
||||||
│ - Orchestrator uses Bash/Read/Edit tools directly
|
|
||||||
│ - Check off completed tasks in story file
|
|
||||||
│ - Fill Dev Agent Record with details
|
|
||||||
│ - Verify updates with bash commands
|
|
||||||
│ - BLOCKER if verification fails
|
|
||||||
│
|
|
||||||
└──> Final Verification [ORCHESTRATOR]
|
|
||||||
- Check git commits exist
|
|
||||||
- Check story checkboxes updated (count > 0)
|
|
||||||
- Check Dev Agent Record filled
|
|
||||||
- Check sprint-status updated
|
|
||||||
- Check tests passed
|
|
||||||
- Mark COMPLETE or FAILED
|
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
Use Read tool on the story file. Parse:
|
||||||
|
- Complexity level (micro/standard/complex)
|
||||||
|
- Task count
|
||||||
|
- Acceptance criteria count
|
||||||
|
|
||||||
## Agent Spawning Instructions
|
Determine which agents to spawn based on complexity routing.
|
||||||
|
</step>
|
||||||
|
|
||||||
### Phase 1: Spawn Builder
|
<step name="spawn_builder">
|
||||||
|
**Phase 1: Builder Agent (Steps 1-4)**
|
||||||
|
|
||||||
```javascript
|
```
|
||||||
|
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||||
|
🔨 PHASE 1: BUILDER
|
||||||
|
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||||
|
```
|
||||||
|
|
||||||
|
Spawn Builder agent:
|
||||||
|
|
||||||
|
```
|
||||||
Task({
|
Task({
|
||||||
subagent_type: "general-purpose",
|
subagent_type: "general-purpose",
|
||||||
description: "Implement story {{story_key}}",
|
description: "Implement story {{story_key}}",
|
||||||
prompt: `
|
prompt: `
|
||||||
You are the BUILDER agent for story {{story_key}}.
|
You are the BUILDER agent for story {{story_key}}.
|
||||||
|
|
||||||
Load and execute: {agents_path}/builder.md
|
<execution_context>
|
||||||
|
@patterns/hospital-grade.md
|
||||||
|
@patterns/tdd.md
|
||||||
|
@patterns/agent-completion.md
|
||||||
|
</execution_context>
|
||||||
|
|
||||||
Story file: {{story_file}}
|
<context>
|
||||||
|
Story: [inline story file content]
|
||||||
|
</context>
|
||||||
|
|
||||||
Complete Steps 1-4:
|
<objective>
|
||||||
1. Init - Load story
|
Implement the story requirements:
|
||||||
2. Pre-Gap - Analyze what exists
|
1. Load and understand requirements
|
||||||
3. Write Tests - TDD approach
|
2. Analyze what exists vs needed
|
||||||
4. Implement - Write production code
|
3. Write tests first (TDD)
|
||||||
|
4. Implement production code
|
||||||
|
</objective>
|
||||||
|
|
||||||
DO NOT:
|
<constraints>
|
||||||
- Validate your work
|
- DO NOT validate your own work
|
||||||
- Review your code
|
- DO NOT review your code
|
||||||
- Update checkboxes
|
- DO NOT update story checkboxes
|
||||||
- Commit changes
|
- DO NOT commit changes
|
||||||
|
</constraints>
|
||||||
|
|
||||||
Just build it and report what you created.
|
<success_criteria>
|
||||||
`
|
- [ ] Tests written for all requirements
|
||||||
});
|
- [ ] Production code implements tests
|
||||||
|
- [ ] Return ## AGENT COMPLETE with file lists
|
||||||
|
</success_criteria>
|
||||||
|
`
|
||||||
|
})
|
||||||
```
|
```
|
||||||
|
|
||||||
**Wait for Builder to complete. Store agent_id in agent-history.json.**
|
**Wait for completion. Parse structured output.**
|
||||||
|
|
||||||
### Phase 2: Spawn Inspector
|
Verify files exist:
|
||||||
|
```bash
|
||||||
|
# For each file in "Files Created" and "Files Modified":
|
||||||
|
[ -f "$file" ] || echo "MISSING: $file"
|
||||||
|
```
|
||||||
|
|
||||||
```javascript
|
If files missing or status FAILED: halt pipeline.
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step name="spawn_inspector">
|
||||||
|
**Phase 2: Inspector Agent (Steps 5-6)**
|
||||||
|
|
||||||
|
```
|
||||||
|
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||||
|
🔍 PHASE 2: INSPECTOR
|
||||||
|
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||||
|
```
|
||||||
|
|
||||||
|
Spawn Inspector agent with **fresh context** (no Builder knowledge):
|
||||||
|
|
||||||
|
```
|
||||||
Task({
|
Task({
|
||||||
subagent_type: "general-purpose",
|
subagent_type: "general-purpose",
|
||||||
description: "Validate story {{story_key}} implementation",
|
description: "Validate story {{story_key}} implementation",
|
||||||
prompt: `
|
prompt: `
|
||||||
You are the INSPECTOR agent for story {{story_key}}.
|
You are the INSPECTOR agent for story {{story_key}}.
|
||||||
|
|
||||||
Load and execute: {agents_path}/inspector.md
|
<execution_context>
|
||||||
|
@patterns/verification.md
|
||||||
|
@patterns/hospital-grade.md
|
||||||
|
@patterns/agent-completion.md
|
||||||
|
</execution_context>
|
||||||
|
|
||||||
Story file: {{story_file}}
|
<context>
|
||||||
|
Story: [inline story file content]
|
||||||
|
</context>
|
||||||
|
|
||||||
You have NO KNOWLEDGE of what the Builder did.
|
<objective>
|
||||||
|
Independently verify the implementation:
|
||||||
|
1. Verify files exist and have content
|
||||||
|
2. Run type-check, lint, build
|
||||||
|
3. Run tests yourself
|
||||||
|
4. Give honest PASS/FAIL verdict
|
||||||
|
</objective>
|
||||||
|
|
||||||
Complete Steps 5-6:
|
<constraints>
|
||||||
5. Post-Validation - Verify files exist and have content
|
- You have NO KNOWLEDGE of what Builder did
|
||||||
6. Quality Checks - Run type-check, lint, build, tests
|
- Run all checks yourself
|
||||||
|
- Don't trust any claims
|
||||||
|
</constraints>
|
||||||
|
|
||||||
Run all checks yourself. Don't trust Builder claims.
|
<success_criteria>
|
||||||
|
- [ ] All files verified to exist
|
||||||
Output: PASS or FAIL verdict with evidence.
|
- [ ] Type check passes (0 errors)
|
||||||
`
|
- [ ] Lint passes (0 warnings)
|
||||||
});
|
- [ ] Tests pass
|
||||||
|
- [ ] Return ## AGENT COMPLETE with evidence
|
||||||
|
</success_criteria>
|
||||||
|
`
|
||||||
|
})
|
||||||
```
|
```
|
||||||
|
|
||||||
**Wait for Inspector to complete. If FAIL, halt pipeline.**
|
**Wait for completion. Parse verdict.**
|
||||||
|
|
||||||
### Phase 3: Spawn Reviewer
|
If FAIL: halt pipeline, report specific failures.
|
||||||
|
</step>
|
||||||
|
|
||||||
```javascript
|
<step name="spawn_reviewer" if="complexity != micro">
|
||||||
|
**Phase 3: Reviewer Agent (Step 7)**
|
||||||
|
|
||||||
|
```
|
||||||
|
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||||
|
🔎 PHASE 3: REVIEWER
|
||||||
|
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||||
|
```
|
||||||
|
|
||||||
|
Spawn Reviewer agent with **adversarial stance**:
|
||||||
|
|
||||||
|
```
|
||||||
Task({
|
Task({
|
||||||
subagent_type: "bmad_bmm_multi-agent-review",
|
subagent_type: "general-purpose",
|
||||||
description: "Adversarial review of story {{story_key}}",
|
description: "Review story {{story_key}} code",
|
||||||
prompt: `
|
prompt: `
|
||||||
You are the ADVERSARIAL REVIEWER for story {{story_key}}.
|
You are the ADVERSARIAL REVIEWER for story {{story_key}}.
|
||||||
|
|
||||||
Load and execute: {agents_path}/reviewer.md
|
<execution_context>
|
||||||
|
@patterns/security-checklist.md
|
||||||
|
@patterns/hospital-grade.md
|
||||||
|
@patterns/agent-completion.md
|
||||||
|
</execution_context>
|
||||||
|
|
||||||
Story file: {{story_file}}
|
<context>
|
||||||
Complexity: {{complexity_level}}
|
Story: [inline story file content]
|
||||||
|
</context>
|
||||||
|
|
||||||
Your goal is to FIND PROBLEMS.
|
<objective>
|
||||||
|
Find problems. Be critical. Look for:
|
||||||
|
- Security vulnerabilities (CRITICAL)
|
||||||
|
- Logic bugs and edge cases (HIGH)
|
||||||
|
- Performance issues (MEDIUM)
|
||||||
|
- Code style issues (LOW)
|
||||||
|
</objective>
|
||||||
|
|
||||||
Complete Step 7:
|
<constraints>
|
||||||
7. Code Review - Find security, performance, logic issues
|
- Your goal is to FIND ISSUES
|
||||||
|
- Don't rubber-stamp
|
||||||
|
- Be thorough
|
||||||
|
</constraints>
|
||||||
|
|
||||||
Be critical. Look for flaws.
|
<success_criteria>
|
||||||
|
- [ ] All new files reviewed
|
||||||
Output: List of issues with severity ratings.
|
- [ ] Security checks completed
|
||||||
`
|
- [ ] Issues categorized by severity
|
||||||
});
|
- [ ] Return ## AGENT COMPLETE with issue list
|
||||||
|
</success_criteria>
|
||||||
|
`
|
||||||
|
})
|
||||||
```
|
```
|
||||||
|
|
||||||
**Wait for Reviewer to complete. Parse issues by severity.**
|
**Wait for completion. Parse issue counts.**
|
||||||
|
</step>
|
||||||
|
|
||||||
### Phase 4: Spawn Fixer
|
<step name="spawn_fixer">
|
||||||
|
**Phase 4: Fixer Agent (Steps 8-9)**
|
||||||
|
|
||||||
```javascript
|
```
|
||||||
|
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||||
|
🔧 PHASE 4: FIXER
|
||||||
|
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||||
|
```
|
||||||
|
|
||||||
|
Spawn Fixer agent:
|
||||||
|
|
||||||
|
```
|
||||||
Task({
|
Task({
|
||||||
subagent_type: "general-purpose",
|
subagent_type: "general-purpose",
|
||||||
description: "Fix issues in story {{story_key}}",
|
description: "Fix issues in story {{story_key}}",
|
||||||
prompt: `
|
prompt: `
|
||||||
You are the FIXER agent for story {{story_key}}.
|
You are the FIXER agent for story {{story_key}}.
|
||||||
|
|
||||||
Load and execute: {agents_path}/fixer.md
|
<execution_context>
|
||||||
|
@patterns/hospital-grade.md
|
||||||
|
@patterns/agent-completion.md
|
||||||
|
</execution_context>
|
||||||
|
|
||||||
Story file: {{story_file}}
|
<context>
|
||||||
Review issues: {{review_findings}}
|
Story: [inline story file content]
|
||||||
|
Review issues: [inline reviewer findings]
|
||||||
|
</context>
|
||||||
|
|
||||||
Complete Steps 8-9:
|
<objective>
|
||||||
8. Review Analysis - Categorize issues, filter gold-plating
|
Fix CRITICAL and HIGH issues:
|
||||||
9. Fix Issues - Fix CRITICAL/HIGH, consider MEDIUM, skip LOW
|
1. Fix ALL CRITICAL issues (security)
|
||||||
|
2. Fix ALL HIGH issues (bugs)
|
||||||
|
3. Fix MEDIUM if time allows
|
||||||
|
4. Skip LOW (gold-plating)
|
||||||
|
5. Commit with descriptive message
|
||||||
|
</objective>
|
||||||
|
|
||||||
After fixing:
|
<constraints>
|
||||||
- Update story checkboxes
|
- DO NOT skip CRITICAL issues
|
||||||
- Update sprint-status.yaml
|
- DO NOT update story checkboxes (orchestrator does this)
|
||||||
- Commit with descriptive message
|
- DO NOT update sprint-status (orchestrator does this)
|
||||||
|
</constraints>
|
||||||
|
|
||||||
Output: Fix summary with git commit hash.
|
<success_criteria>
|
||||||
`
|
- [ ] All CRITICAL fixed
|
||||||
});
|
- [ ] All HIGH fixed
|
||||||
|
- [ ] Tests still pass
|
||||||
|
- [ ] Git commit created
|
||||||
|
- [ ] Return ## AGENT COMPLETE with fix summary
|
||||||
|
</success_criteria>
|
||||||
|
`
|
||||||
|
})
|
||||||
```
|
```
|
||||||
|
|
||||||
**Wait for Fixer to complete.**
|
**Wait for completion. Parse commit hash and fix counts.**
|
||||||
|
</step>
|
||||||
|
|
||||||
### Phase 5: Orchestrator Reconciliation (MANDATORY)
|
<step name="reconcile_story">
|
||||||
|
**Phase 5: Orchestrator Reconciliation**
|
||||||
|
|
||||||
🚨 **THIS PHASE IS MANDATORY. ORCHESTRATOR DOES THIS DIRECTLY. NO AGENT SPAWN.** 🚨
|
```
|
||||||
|
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||||
|
🔧 PHASE 5: RECONCILIATION (Orchestrator)
|
||||||
|
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||||
|
```
|
||||||
|
|
||||||
**Why orchestrator, not agent?** Agents ignore instructions. The orchestrator has the context
|
**YOU (orchestrator) do this directly. No agent spawn.**
|
||||||
and can use tools directly. This is bookkeeping work, not creative work.
|
|
||||||
|
|
||||||
**YOU (the orchestrator) must execute these commands directly:**
|
|
||||||
|
|
||||||
**Step 5.1: Get what was built**
|
**Step 5.1: Get what was built**
|
||||||
```bash
|
```bash
|
||||||
# Get commit for this story
|
git log -3 --oneline | grep "{{story_key}}"
|
||||||
COMMIT_INFO=$(git log -5 --oneline | grep "{{story_key}}" | head -1)
|
git diff HEAD~1 --name-only | head -20
|
||||||
echo "Commit: $COMMIT_INFO"
|
|
||||||
|
|
||||||
# Get files changed (production code only)
|
|
||||||
FILES_CHANGED=$(git diff HEAD~1 --name-only | grep -v "__tests__" | grep -v "\.test\." | grep -v "\.spec\.")
|
|
||||||
echo "Files changed:"
|
|
||||||
echo "$FILES_CHANGED"
|
|
||||||
```
|
```
|
||||||
|
|
||||||
**Step 5.2: Read story file tasks**
|
**Step 5.2: Read story file**
|
||||||
Use Read tool: `{{story_file}}`
|
Use Read tool: `docs/sprint-artifacts/{{story_key}}.md`
|
||||||
|
|
||||||
Find the Tasks section and identify which tasks relate to the files changed.
|
|
||||||
|
|
||||||
**Step 5.3: Check off completed tasks**
|
**Step 5.3: Check off completed tasks**
|
||||||
Use Edit tool for EACH task that was completed:
|
For each task related to files changed, use Edit tool:
|
||||||
```
|
```
|
||||||
old_string: "- [ ] Task description here"
|
old_string: "- [ ] Task description"
|
||||||
new_string: "- [x] Task description here"
|
new_string: "- [x] Task description"
|
||||||
```
|
```
|
||||||
|
|
||||||
**Step 5.4: Fill Dev Agent Record**
|
**Step 5.4: Fill Dev Agent Record**
|
||||||
Use Edit tool to update the Dev Agent Record section:
|
Use Edit tool to update Dev Agent Record section with:
|
||||||
```
|
- Agent Model: Claude Sonnet 4 (multi-agent pipeline)
|
||||||
old_string: "### Dev Agent Record
|
- Implementation Date: {{date}}
|
||||||
- **Agent Model Used:** [Not set]
|
- Files Created/Modified: [list from git diff]
|
||||||
- **Implementation Date:** [Not set]
|
- Tests Added: [count from Inspector]
|
||||||
- **Files Created/Modified:** [Not set]
|
- Completion Notes: [brief summary]
|
||||||
- **Tests Added:** [Not set]
|
|
||||||
- **Completion Notes:** [Not set]"
|
|
||||||
|
|
||||||
new_string: "### Dev Agent Record
|
**Step 5.5: Verify updates**
|
||||||
- **Agent Model Used:** Claude Sonnet 4 (multi-agent: Builder + Inspector + Reviewer + Fixer)
|
|
||||||
- **Implementation Date:** {{date}}
|
|
||||||
- **Files Created/Modified:**
|
|
||||||
{{#each files_changed}}
|
|
||||||
- {{this}}
|
|
||||||
{{/each}}
|
|
||||||
- **Tests Added:** [count from Inspector report]
|
|
||||||
- **Completion Notes:** [brief summary of what was implemented]"
|
|
||||||
```
|
|
||||||
|
|
||||||
**Step 5.5: Verify updates (BLOCKER)**
|
|
||||||
```bash
|
```bash
|
||||||
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
|
CHECKED=$(grep -c "^- \[x\]" docs/sprint-artifacts/{{story_key}}.md)
|
||||||
echo "🔍 RECONCILIATION VERIFICATION"
|
|
||||||
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
|
|
||||||
|
|
||||||
# Count checked tasks
|
|
||||||
CHECKED=$(grep -c "^- \[x\]" {{story_file}})
|
|
||||||
echo "Checked tasks: $CHECKED"
|
|
||||||
|
|
||||||
if [ "$CHECKED" -eq 0 ]; then
|
if [ "$CHECKED" -eq 0 ]; then
|
||||||
echo "❌ BLOCKER: Zero checked tasks"
|
echo "❌ BLOCKER: Zero checked tasks"
|
||||||
echo "Go back to Step 5.3 and check off tasks"
|
|
||||||
exit 1
|
exit 1
|
||||||
fi
|
fi
|
||||||
|
echo "✅ Verified: $CHECKED tasks checked"
|
||||||
# Verify Dev Agent Record
|
|
||||||
RECORD=$(grep -A 5 "### Dev Agent Record" {{story_file}} | grep -c "Implementation Date:")
|
|
||||||
if [ "$RECORD" -eq 0 ]; then
|
|
||||||
echo "❌ BLOCKER: Dev Agent Record not filled"
|
|
||||||
echo "Go back to Step 5.4 and fill it"
|
|
||||||
exit 1
|
|
||||||
fi
|
|
||||||
|
|
||||||
echo "✅ Reconciliation verified: $CHECKED tasks checked"
|
|
||||||
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
|
|
||||||
```
|
```
|
||||||
|
|
||||||
**If verification fails:** DO NOT proceed. Fix immediately using Edit tool, then re-verify.
|
If verification fails: fix using Edit, then re-verify.
|
||||||
|
</step>
|
||||||
|
|
||||||
---
|
<step name="final_verification">
|
||||||
|
**Final Quality Gate**
|
||||||
## Final Verification (Main Orchestrator)
|
|
||||||
|
|
||||||
🚨 **CRITICAL: This verification is MANDATORY. DO NOT skip.** 🚨
|
|
||||||
|
|
||||||
**After all agents complete (including Reconciler), YOU (the main orchestrator) must:**
|
|
||||||
|
|
||||||
1. **Use the Bash tool** to run these commands
|
|
||||||
2. **Read the output** to see if verification passed
|
|
||||||
3. **If verification fails**, use Edit and Bash tools to fix it NOW
|
|
||||||
4. **Do not proceed** until verification passes
|
|
||||||
|
|
||||||
**COMMAND TO RUN WITH BASH TOOL:**
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
|
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
|
||||||
echo "🔍 FINAL VERIFICATION (MANDATORY)"
|
echo "🔍 FINAL VERIFICATION"
|
||||||
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
|
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
|
||||||
|
|
||||||
# 1. Check git commits exist
|
# 1. Git commit exists
|
||||||
echo "Checking git commits..."
|
git log --oneline -3 | grep "{{story_key}}" || { echo "❌ No commit"; exit 1; }
|
||||||
git log --oneline -3 | grep "{{story_key}}"
|
|
||||||
if [ $? -ne 0 ]; then
|
|
||||||
echo "❌ FAILED: No commit found for {{story_key}}"
|
|
||||||
echo "The Fixer agent did not commit changes."
|
|
||||||
exit 1
|
|
||||||
fi
|
|
||||||
echo "✅ Git commit found"
|
echo "✅ Git commit found"
|
||||||
|
|
||||||
# 2. Check story file has checked tasks (ABSOLUTE BLOCKER)
|
# 2. Story tasks checked
|
||||||
echo "Checking story file updates..."
|
CHECKED=$(grep -c "^- \[x\]" docs/sprint-artifacts/{{story_key}}.md)
|
||||||
CHECKED_COUNT=$(grep -c '^- \[x\]' {{story_file}})
|
[ "$CHECKED" -gt 0 ] || { echo "❌ No tasks checked"; exit 1; }
|
||||||
echo "Checked tasks: $CHECKED_COUNT"
|
echo "✅ $CHECKED tasks checked"
|
||||||
|
|
||||||
if [ "$CHECKED_COUNT" -eq 0 ]; then
|
# 3. Dev Agent Record filled
|
||||||
echo ""
|
grep -A 3 "### Dev Agent Record" docs/sprint-artifacts/{{story_key}}.md | grep -q "202" || { echo "❌ Record not filled"; exit 1; }
|
||||||
echo "❌ BLOCKER: Story file has ZERO checked tasks"
|
|
||||||
echo ""
|
|
||||||
echo "This means the Fixer agent did NOT update the story file."
|
|
||||||
echo "The story CANNOT be marked complete without checked tasks."
|
|
||||||
echo ""
|
|
||||||
echo "You must:"
|
|
||||||
echo " 1. Read the git commit to see what was built"
|
|
||||||
echo " 2. Read the story Tasks section"
|
|
||||||
echo " 3. Use Edit tool to check off completed tasks"
|
|
||||||
echo " 4. Fill in Dev Agent Record"
|
|
||||||
echo " 5. Verify with grep"
|
|
||||||
echo " 6. Re-run this verification"
|
|
||||||
echo ""
|
|
||||||
exit 1
|
|
||||||
fi
|
|
||||||
echo "✅ Story file has $CHECKED_COUNT checked tasks"
|
|
||||||
|
|
||||||
# 3. Check Dev Agent Record filled
|
|
||||||
echo "Checking Dev Agent Record..."
|
|
||||||
RECORD_FILLED=$(grep -A 20 "^### Dev Agent Record" {{story_file}} | grep -c "Agent Model")
|
|
||||||
if [ "$RECORD_FILLED" -eq 0 ]; then
|
|
||||||
echo "❌ BLOCKER: Dev Agent Record NOT filled"
|
|
||||||
echo "The Fixer agent did not document what was built."
|
|
||||||
exit 1
|
|
||||||
fi
|
|
||||||
echo "✅ Dev Agent Record filled"
|
echo "✅ Dev Agent Record filled"
|
||||||
|
|
||||||
# 4. Check sprint-status updated
|
|
||||||
echo "Checking sprint-status..."
|
|
||||||
git diff HEAD~1 {{sprint_status}} | grep "{{story_key}}"
|
|
||||||
if [ $? -ne 0 ]; then
|
|
||||||
echo "❌ FAILED: Sprint status not updated for {{story_key}}"
|
|
||||||
exit 1
|
|
||||||
fi
|
|
||||||
echo "✅ Sprint status updated"
|
|
||||||
|
|
||||||
# 5. Check test evidence (optional - may have test failures)
|
|
||||||
echo "Checking test evidence..."
|
|
||||||
if [ -f "inspector_output.txt" ]; then
|
|
||||||
grep -E "PASS|tests.*passing" inspector_output.txt && echo "✅ Tests passing"
|
|
||||||
fi
|
|
||||||
|
|
||||||
echo ""
|
echo ""
|
||||||
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
|
echo "✅ STORY COMPLETE"
|
||||||
echo "✅ STORY COMPLETE - All verifications passed"
|
|
||||||
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
|
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
|
||||||
```
|
```
|
||||||
|
|
||||||
**IF VERIFICATION FAILS:**
|
**Update sprint-status.yaml:**
|
||||||
- DO NOT mark story as "done"
|
Use Edit tool to change story status from `ready-for-dev` to `done`.
|
||||||
- DO NOT proceed to next story
|
</step>
|
||||||
- FIX the failure immediately
|
|
||||||
- Re-run verification until it passes
|
|
||||||
|
|
||||||
---
|
</process>
|
||||||
|
|
||||||
## Benefits Over Single-Agent
|
<failure_handling>
|
||||||
|
**Builder fails:** Don't spawn Inspector. Report failure.
|
||||||
|
**Inspector fails:** Don't spawn Reviewer. Report specific failures.
|
||||||
|
**Reviewer finds CRITICAL:** Fixer must fix (not optional).
|
||||||
|
**Fixer fails:** Report unfixed issues. Manual intervention needed.
|
||||||
|
**Reconciliation fails:** Fix using Edit tool. Re-verify.
|
||||||
|
</failure_handling>
|
||||||
|
|
||||||
### Separation of Concerns
|
<complexity_routing>
|
||||||
- Builder doesn't validate own work
|
| Complexity | Agents | Notes |
|
||||||
- Inspector has no incentive to lie
|
|------------|--------|-------|
|
||||||
- Reviewer approaches with fresh eyes
|
| micro | Builder → Inspector → Fixer | Skip Reviewer (low risk) |
|
||||||
- Fixer can't skip issues
|
| standard | Builder → Inspector → Reviewer → Fixer | Full pipeline |
|
||||||
|
| complex | Builder → Inspector → Reviewer (enhanced) → Fixer | Extra scrutiny |
|
||||||
|
</complexity_routing>
|
||||||
|
|
||||||
### Fresh Context Each Phase
|
<success_criteria>
|
||||||
- Each agent starts at 0% context
|
- [ ] All agents completed successfully
|
||||||
- No accumulated fatigue
|
- [ ] Git commit exists for story
|
||||||
- No degraded quality
|
- [ ] Story file has checked tasks (count > 0)
|
||||||
- Honest reporting
|
- [ ] Dev Agent Record filled
|
||||||
|
- [ ] Sprint status updated to "done"
|
||||||
### Adversarial Review
|
</success_criteria>
|
||||||
- Reviewer WANTS to find issues
|
|
||||||
- Not defensive about the code
|
|
||||||
- More thorough than self-review
|
|
||||||
|
|
||||||
### Honest Verification
|
|
||||||
- Inspector runs tests independently
|
|
||||||
- Main orchestrator verifies everything
|
|
||||||
- Can't fake completion
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Complexity Routing
|
|
||||||
|
|
||||||
**MICRO stories:**
|
|
||||||
- Skip Reviewer (low risk)
|
|
||||||
- 2 agents: Builder → Inspector → Fixer
|
|
||||||
|
|
||||||
**STANDARD stories:**
|
|
||||||
- Full pipeline
|
|
||||||
- 4 agents: Builder → Inspector → Reviewer → Fixer
|
|
||||||
|
|
||||||
**COMPLEX stories:**
|
|
||||||
- Enhanced review (6 reviewers instead of 4)
|
|
||||||
- Full pipeline + extra scrutiny
|
|
||||||
- 4 agents: Builder → Inspector → Reviewer (enhanced) → Fixer
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Agent Tracking
|
|
||||||
|
|
||||||
Track all agents in `agent-history.json`:
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"version": "1.0",
|
|
||||||
"max_entries": 50,
|
|
||||||
"entries": [
|
|
||||||
{
|
|
||||||
"agent_id": "abc123",
|
|
||||||
"story_key": "17-10",
|
|
||||||
"phase": "builder",
|
|
||||||
"steps": [1,2,3,4],
|
|
||||||
"timestamp": "2026-01-25T21:00:00Z",
|
|
||||||
"status": "completed",
|
|
||||||
"completion_timestamp": "2026-01-25T21:15:00Z"
|
|
||||||
},
|
|
||||||
{
|
|
||||||
"agent_id": "def456",
|
|
||||||
"story_key": "17-10",
|
|
||||||
"phase": "inspector",
|
|
||||||
"steps": [5,6],
|
|
||||||
"timestamp": "2026-01-25T21:16:00Z",
|
|
||||||
"status": "completed",
|
|
||||||
"completion_timestamp": "2026-01-25T21:20:00Z"
|
|
||||||
}
|
|
||||||
]
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
**Benefits:**
|
|
||||||
- Resume interrupted sessions
|
|
||||||
- Track agent performance
|
|
||||||
- Debug failed pipelines
|
|
||||||
- Audit trail
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Error Handling
|
|
||||||
|
|
||||||
**If Builder fails:**
|
|
||||||
- Don't spawn Inspector
|
|
||||||
- Report failure to user
|
|
||||||
- Option to resume or retry
|
|
||||||
|
|
||||||
**If Inspector fails:**
|
|
||||||
- Don't spawn Reviewer
|
|
||||||
- Report specific failures
|
|
||||||
- Resume Builder to fix issues
|
|
||||||
|
|
||||||
**If Reviewer finds CRITICAL issues:**
|
|
||||||
- Must spawn Fixer (not optional)
|
|
||||||
- Cannot mark story complete until fixed
|
|
||||||
|
|
||||||
**If Fixer fails:**
|
|
||||||
- Report unfixed issues
|
|
||||||
- Cannot mark story complete
|
|
||||||
- Manual intervention required
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Comparison: v1.x vs v2.0
|
|
||||||
|
|
||||||
| Aspect | v1.x (Single-Agent) | v2.0 (Multi-Agent) |
|
|
||||||
|--------|--------------------|--------------------|
|
|
||||||
| Agents | 1 | 4 |
|
|
||||||
| Validation | Self (conflict of interest) | Independent (no conflict) |
|
|
||||||
| Code Review | Self-review | Adversarial (fresh eyes) |
|
|
||||||
| Honesty | Low (can lie) | High (verified) |
|
|
||||||
| Context | Degrades over 11 steps | Fresh each phase |
|
|
||||||
| Catches Issues | Low | High |
|
|
||||||
| Completion Accuracy | ~60% (agents lie) | ~95% (verified) |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Migration from v1.x
|
|
||||||
|
|
||||||
**Backward Compatibility:**
|
|
||||||
```yaml
|
|
||||||
execution_mode: "single_agent" # Use v1.x
|
|
||||||
execution_mode: "multi_agent" # Use v2.0 (new)
|
|
||||||
```
|
|
||||||
|
|
||||||
**Gradual Rollout:**
|
|
||||||
1. Week 1: Test v2.0 on 3-5 stories
|
|
||||||
2. Week 2: Make v2.0 default for new stories
|
|
||||||
3. Week 3: Migrate existing stories to v2.0
|
|
||||||
4. Week 4: Deprecate v1.x
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Hospital-Grade Standards
|
|
||||||
|
|
||||||
⚕️ **Lives May Be at Stake**
|
|
||||||
|
|
||||||
- Independent validation catches errors
|
|
||||||
- Adversarial review finds security flaws
|
|
||||||
- Multiple checkpoints prevent shortcuts
|
|
||||||
- Final verification prevents false completion
|
|
||||||
|
|
||||||
**QUALITY >> SPEED**
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
**Key Takeaway:** Don't trust a single agent to build, validate, review, and commit its own work. Use independent agents with fresh context at each phase.
|
|
||||||
|
|
|
||||||
|
|
@ -1,522 +1,396 @@
|
||||||
# Super-Dev-Pipeline v2.1 - Multi-Agent Architecture
|
# Super-Dev-Pipeline v3.0 - Unified Workflow
|
||||||
|
|
||||||
**Version:** 2.1.0
|
<purpose>
|
||||||
**Architecture:** GSDMAD (GSD + BMAD)
|
Implement a story using 4 independent agents with orchestrator-driven reconciliation.
|
||||||
**Philosophy:** Agents do creative work, orchestrator does bookkeeping
|
Each agent has single responsibility. No agent validates its own work.
|
||||||
|
Orchestrator handles bookkeeping (story file updates, verification).
|
||||||
|
</purpose>
|
||||||
|
|
||||||
---
|
<philosophy>
|
||||||
|
**Agents do creative work. Orchestrator does bookkeeping.**
|
||||||
|
|
||||||
## Overview
|
- Builder implements (creative)
|
||||||
|
- Inspector validates (verification)
|
||||||
|
- Reviewer finds issues (adversarial)
|
||||||
|
- Fixer resolves issues (creative)
|
||||||
|
- Orchestrator reconciles story file (mechanical)
|
||||||
|
|
||||||
This workflow implements a story using **4 independent agents** with orchestrator-driven reconciliation.
|
Trust but verify. Fresh context per phase. Adversarial review.
|
||||||
|
</philosophy>
|
||||||
|
|
||||||
**Key Innovation:**
|
<config>
|
||||||
- Each agent has single responsibility and fresh context
|
name: super-dev-pipeline
|
||||||
- No agent validates its own work
|
version: 3.0.0
|
||||||
- **Orchestrator does bookkeeping** (story file updates, verification) - not agents
|
execution_mode: multi_agent
|
||||||
|
|
||||||
---
|
agents:
|
||||||
|
builder: {steps: 1-4, trust: low, timeout: 60min}
|
||||||
|
inspector: {steps: 5-6, trust: medium, fresh_context: true, timeout: 30min}
|
||||||
|
reviewer: {steps: 7, trust: high, adversarial: true, timeout: 30min}
|
||||||
|
fixer: {steps: 8-9, trust: medium, timeout: 40min}
|
||||||
|
|
||||||
## Execution Flow
|
complexity_routing:
|
||||||
|
micro: {skip: [reviewer], description: "Low-risk stories"}
|
||||||
|
standard: {skip: [], description: "Normal stories"}
|
||||||
|
complex: {skip: [], enhanced_review: true, description: "High-risk stories"}
|
||||||
|
</config>
|
||||||
|
|
||||||
```
|
<execution_context>
|
||||||
┌─────────────────────────────────────────────────────────────┐
|
@patterns/hospital-grade.md
|
||||||
│ Main Orchestrator (Claude) │
|
@patterns/agent-completion.md
|
||||||
│ - Loads story │
|
</execution_context>
|
||||||
│ - Spawns agents sequentially │
|
|
||||||
│ - Verifies each phase │
|
<process>
|
||||||
│ - DOES RECONCILIATION DIRECTLY (not via agent) │
|
|
||||||
│ - Final quality gate │
|
<step name="load_story" priority="first">
|
||||||
└─────────────────────────────────────────────────────────────┘
|
Load and validate the story file.
|
||||||
│
|
|
||||||
├──> Phase 1: Builder (Steps 1-4) [AGENT]
|
```bash
|
||||||
│ - Load story, analyze gaps
|
STORY_FILE="docs/sprint-artifacts/{{story_key}}.md"
|
||||||
│ - Write tests (TDD)
|
[ -f "$STORY_FILE" ] || { echo "ERROR: Story file not found"; exit 1; }
|
||||||
│ - Implement code
|
|
||||||
│ - Report what was built (NO VALIDATION)
|
|
||||||
│
|
|
||||||
├──> Phase 2: Inspector (Steps 5-6) [AGENT]
|
|
||||||
│ - Fresh context, no Builder knowledge
|
|
||||||
│ - Verify files exist
|
|
||||||
│ - Run tests independently
|
|
||||||
│ - Run quality checks
|
|
||||||
│ - PASS or FAIL verdict
|
|
||||||
│
|
|
||||||
├──> Phase 3: Reviewer (Step 7) [AGENT]
|
|
||||||
│ - Fresh context, adversarial stance
|
|
||||||
│ - Find security vulnerabilities
|
|
||||||
│ - Find performance problems
|
|
||||||
│ - Find logic bugs
|
|
||||||
│ - Report issues with severity
|
|
||||||
│
|
|
||||||
├──> Phase 4: Fixer (Steps 8-9) [AGENT]
|
|
||||||
│ - Fix CRITICAL issues (all)
|
|
||||||
│ - Fix HIGH issues (all)
|
|
||||||
│ - Fix MEDIUM issues (if time)
|
|
||||||
│ - Skip LOW issues (gold-plating)
|
|
||||||
│ - Commit code changes
|
|
||||||
│
|
|
||||||
├──> Phase 5: Reconciliation (Step 10) [ORCHESTRATOR] 🔧
|
|
||||||
│ - Orchestrator uses Bash/Read/Edit tools directly
|
|
||||||
│ - Check off completed tasks in story file
|
|
||||||
│ - Fill Dev Agent Record with details
|
|
||||||
│ - Verify updates with bash commands
|
|
||||||
│ - BLOCKER if verification fails
|
|
||||||
│
|
|
||||||
└──> Final Verification [ORCHESTRATOR]
|
|
||||||
- Check git commits exist
|
|
||||||
- Check story checkboxes updated (count > 0)
|
|
||||||
- Check Dev Agent Record filled
|
|
||||||
- Check sprint-status updated
|
|
||||||
- Check tests passed
|
|
||||||
- Mark COMPLETE or FAILED
|
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
Use Read tool on the story file. Parse:
|
||||||
|
- Complexity level (micro/standard/complex)
|
||||||
|
- Task count
|
||||||
|
- Acceptance criteria count
|
||||||
|
|
||||||
## Agent Spawning Instructions
|
Determine which agents to spawn based on complexity routing.
|
||||||
|
</step>
|
||||||
|
|
||||||
### Phase 1: Spawn Builder
|
<step name="spawn_builder">
|
||||||
|
**Phase 1: Builder Agent (Steps 1-4)**
|
||||||
|
|
||||||
```javascript
|
```
|
||||||
|
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||||
|
🔨 PHASE 1: BUILDER
|
||||||
|
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||||
|
```
|
||||||
|
|
||||||
|
Spawn Builder agent:
|
||||||
|
|
||||||
|
```
|
||||||
Task({
|
Task({
|
||||||
subagent_type: "general-purpose",
|
subagent_type: "general-purpose",
|
||||||
description: "Implement story {{story_key}}",
|
description: "Implement story {{story_key}}",
|
||||||
prompt: `
|
prompt: `
|
||||||
You are the BUILDER agent for story {{story_key}}.
|
You are the BUILDER agent for story {{story_key}}.
|
||||||
|
|
||||||
Load and execute: {agents_path}/builder.md
|
<execution_context>
|
||||||
|
@patterns/hospital-grade.md
|
||||||
|
@patterns/tdd.md
|
||||||
|
@patterns/agent-completion.md
|
||||||
|
</execution_context>
|
||||||
|
|
||||||
Story file: {{story_file}}
|
<context>
|
||||||
|
Story: [inline story file content]
|
||||||
|
</context>
|
||||||
|
|
||||||
Complete Steps 1-4:
|
<objective>
|
||||||
1. Init - Load story
|
Implement the story requirements:
|
||||||
2. Pre-Gap - Analyze what exists
|
1. Load and understand requirements
|
||||||
3. Write Tests - TDD approach
|
2. Analyze what exists vs needed
|
||||||
4. Implement - Write production code
|
3. Write tests first (TDD)
|
||||||
|
4. Implement production code
|
||||||
|
</objective>
|
||||||
|
|
||||||
DO NOT:
|
<constraints>
|
||||||
- Validate your work
|
- DO NOT validate your own work
|
||||||
- Review your code
|
- DO NOT review your code
|
||||||
- Update checkboxes
|
- DO NOT update story checkboxes
|
||||||
- Commit changes
|
- DO NOT commit changes
|
||||||
|
</constraints>
|
||||||
|
|
||||||
Just build it and report what you created.
|
<success_criteria>
|
||||||
`
|
- [ ] Tests written for all requirements
|
||||||
});
|
- [ ] Production code implements tests
|
||||||
|
- [ ] Return ## AGENT COMPLETE with file lists
|
||||||
|
</success_criteria>
|
||||||
|
`
|
||||||
|
})
|
||||||
```
|
```
|
||||||
|
|
||||||
**Wait for Builder to complete. Store agent_id in agent-history.json.**
|
**Wait for completion. Parse structured output.**
|
||||||
|
|
||||||
### Phase 2: Spawn Inspector
|
Verify files exist:
|
||||||
|
```bash
|
||||||
|
# For each file in "Files Created" and "Files Modified":
|
||||||
|
[ -f "$file" ] || echo "MISSING: $file"
|
||||||
|
```
|
||||||
|
|
||||||
```javascript
|
If files missing or status FAILED: halt pipeline.
|
||||||
|
</step>
|
||||||
|
|
||||||
|
<step name="spawn_inspector">
|
||||||
|
**Phase 2: Inspector Agent (Steps 5-6)**
|
||||||
|
|
||||||
|
```
|
||||||
|
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||||
|
🔍 PHASE 2: INSPECTOR
|
||||||
|
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||||
|
```
|
||||||
|
|
||||||
|
Spawn Inspector agent with **fresh context** (no Builder knowledge):
|
||||||
|
|
||||||
|
```
|
||||||
Task({
|
Task({
|
||||||
subagent_type: "general-purpose",
|
subagent_type: "general-purpose",
|
||||||
description: "Validate story {{story_key}} implementation",
|
description: "Validate story {{story_key}} implementation",
|
||||||
prompt: `
|
prompt: `
|
||||||
You are the INSPECTOR agent for story {{story_key}}.
|
You are the INSPECTOR agent for story {{story_key}}.
|
||||||
|
|
||||||
Load and execute: {agents_path}/inspector.md
|
<execution_context>
|
||||||
|
@patterns/verification.md
|
||||||
|
@patterns/hospital-grade.md
|
||||||
|
@patterns/agent-completion.md
|
||||||
|
</execution_context>
|
||||||
|
|
||||||
Story file: {{story_file}}
|
<context>
|
||||||
|
Story: [inline story file content]
|
||||||
|
</context>
|
||||||
|
|
||||||
You have NO KNOWLEDGE of what the Builder did.
|
<objective>
|
||||||
|
Independently verify the implementation:
|
||||||
|
1. Verify files exist and have content
|
||||||
|
2. Run type-check, lint, build
|
||||||
|
3. Run tests yourself
|
||||||
|
4. Give honest PASS/FAIL verdict
|
||||||
|
</objective>
|
||||||
|
|
||||||
Complete Steps 5-6:
|
<constraints>
|
||||||
5. Post-Validation - Verify files exist and have content
|
- You have NO KNOWLEDGE of what Builder did
|
||||||
6. Quality Checks - Run type-check, lint, build, tests
|
- Run all checks yourself
|
||||||
|
- Don't trust any claims
|
||||||
|
</constraints>
|
||||||
|
|
||||||
Run all checks yourself. Don't trust Builder claims.
|
<success_criteria>
|
||||||
|
- [ ] All files verified to exist
|
||||||
Output: PASS or FAIL verdict with evidence.
|
- [ ] Type check passes (0 errors)
|
||||||
`
|
- [ ] Lint passes (0 warnings)
|
||||||
});
|
- [ ] Tests pass
|
||||||
|
- [ ] Return ## AGENT COMPLETE with evidence
|
||||||
|
</success_criteria>
|
||||||
|
`
|
||||||
|
})
|
||||||
```
|
```
|
||||||
|
|
||||||
**Wait for Inspector to complete. If FAIL, halt pipeline.**
|
**Wait for completion. Parse verdict.**
|
||||||
|
|
||||||
### Phase 3: Spawn Reviewer
|
If FAIL: halt pipeline, report specific failures.
|
||||||
|
</step>
|
||||||
|
|
||||||
```javascript
|
<step name="spawn_reviewer" if="complexity != micro">
|
||||||
|
**Phase 3: Reviewer Agent (Step 7)**
|
||||||
|
|
||||||
|
```
|
||||||
|
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||||
|
🔎 PHASE 3: REVIEWER
|
||||||
|
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||||
|
```
|
||||||
|
|
||||||
|
Spawn Reviewer agent with **adversarial stance**:
|
||||||
|
|
||||||
|
```
|
||||||
Task({
|
Task({
|
||||||
subagent_type: "bmad_bmm_multi-agent-review",
|
subagent_type: "general-purpose",
|
||||||
description: "Adversarial review of story {{story_key}}",
|
description: "Review story {{story_key}} code",
|
||||||
prompt: `
|
prompt: `
|
||||||
You are the ADVERSARIAL REVIEWER for story {{story_key}}.
|
You are the ADVERSARIAL REVIEWER for story {{story_key}}.
|
||||||
|
|
||||||
Load and execute: {agents_path}/reviewer.md
|
<execution_context>
|
||||||
|
@patterns/security-checklist.md
|
||||||
|
@patterns/hospital-grade.md
|
||||||
|
@patterns/agent-completion.md
|
||||||
|
</execution_context>
|
||||||
|
|
||||||
Story file: {{story_file}}
|
<context>
|
||||||
Complexity: {{complexity_level}}
|
Story: [inline story file content]
|
||||||
|
</context>
|
||||||
|
|
||||||
Your goal is to FIND PROBLEMS.
|
<objective>
|
||||||
|
Find problems. Be critical. Look for:
|
||||||
|
- Security vulnerabilities (CRITICAL)
|
||||||
|
- Logic bugs and edge cases (HIGH)
|
||||||
|
- Performance issues (MEDIUM)
|
||||||
|
- Code style issues (LOW)
|
||||||
|
</objective>
|
||||||
|
|
||||||
Complete Step 7:
|
<constraints>
|
||||||
7. Code Review - Find security, performance, logic issues
|
- Your goal is to FIND ISSUES
|
||||||
|
- Don't rubber-stamp
|
||||||
|
- Be thorough
|
||||||
|
</constraints>
|
||||||
|
|
||||||
Be critical. Look for flaws.
|
<success_criteria>
|
||||||
|
- [ ] All new files reviewed
|
||||||
Output: List of issues with severity ratings.
|
- [ ] Security checks completed
|
||||||
`
|
- [ ] Issues categorized by severity
|
||||||
});
|
- [ ] Return ## AGENT COMPLETE with issue list
|
||||||
|
</success_criteria>
|
||||||
|
`
|
||||||
|
})
|
||||||
```
|
```
|
||||||
|
|
||||||
**Wait for Reviewer to complete. Parse issues by severity.**
|
**Wait for completion. Parse issue counts.**
|
||||||
|
</step>
|
||||||
|
|
||||||
### Phase 4: Spawn Fixer
|
<step name="spawn_fixer">
|
||||||
|
**Phase 4: Fixer Agent (Steps 8-9)**
|
||||||
|
|
||||||
```javascript
|
```
|
||||||
|
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||||
|
🔧 PHASE 4: FIXER
|
||||||
|
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||||
|
```
|
||||||
|
|
||||||
|
Spawn Fixer agent:
|
||||||
|
|
||||||
|
```
|
||||||
Task({
|
Task({
|
||||||
subagent_type: "general-purpose",
|
subagent_type: "general-purpose",
|
||||||
description: "Fix issues in story {{story_key}}",
|
description: "Fix issues in story {{story_key}}",
|
||||||
prompt: `
|
prompt: `
|
||||||
You are the FIXER agent for story {{story_key}}.
|
You are the FIXER agent for story {{story_key}}.
|
||||||
|
|
||||||
Load and execute: {agents_path}/fixer.md
|
<execution_context>
|
||||||
|
@patterns/hospital-grade.md
|
||||||
|
@patterns/agent-completion.md
|
||||||
|
</execution_context>
|
||||||
|
|
||||||
Story file: {{story_file}}
|
<context>
|
||||||
Review issues: {{review_findings}}
|
Story: [inline story file content]
|
||||||
|
Review issues: [inline reviewer findings]
|
||||||
|
</context>
|
||||||
|
|
||||||
Complete Steps 8-9:
|
<objective>
|
||||||
8. Review Analysis - Categorize issues, filter gold-plating
|
Fix CRITICAL and HIGH issues:
|
||||||
9. Fix Issues - Fix CRITICAL/HIGH, consider MEDIUM, skip LOW
|
1. Fix ALL CRITICAL issues (security)
|
||||||
|
2. Fix ALL HIGH issues (bugs)
|
||||||
|
3. Fix MEDIUM if time allows
|
||||||
|
4. Skip LOW (gold-plating)
|
||||||
|
5. Commit with descriptive message
|
||||||
|
</objective>
|
||||||
|
|
||||||
After fixing:
|
<constraints>
|
||||||
- Update story checkboxes
|
- DO NOT skip CRITICAL issues
|
||||||
- Update sprint-status.yaml
|
- DO NOT update story checkboxes (orchestrator does this)
|
||||||
- Commit with descriptive message
|
- DO NOT update sprint-status (orchestrator does this)
|
||||||
|
</constraints>
|
||||||
|
|
||||||
Output: Fix summary with git commit hash.
|
<success_criteria>
|
||||||
`
|
- [ ] All CRITICAL fixed
|
||||||
});
|
- [ ] All HIGH fixed
|
||||||
|
- [ ] Tests still pass
|
||||||
|
- [ ] Git commit created
|
||||||
|
- [ ] Return ## AGENT COMPLETE with fix summary
|
||||||
|
</success_criteria>
|
||||||
|
`
|
||||||
|
})
|
||||||
```
|
```
|
||||||
|
|
||||||
**Wait for Fixer to complete.**
|
**Wait for completion. Parse commit hash and fix counts.**
|
||||||
|
</step>
|
||||||
|
|
||||||
### Phase 5: Orchestrator Reconciliation (MANDATORY)
|
<step name="reconcile_story">
|
||||||
|
**Phase 5: Orchestrator Reconciliation**
|
||||||
|
|
||||||
🚨 **THIS PHASE IS MANDATORY. ORCHESTRATOR DOES THIS DIRECTLY. NO AGENT SPAWN.** 🚨
|
```
|
||||||
|
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||||
|
🔧 PHASE 5: RECONCILIATION (Orchestrator)
|
||||||
|
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||||
|
```
|
||||||
|
|
||||||
**Why orchestrator, not agent?** Agents ignore instructions. The orchestrator has the context
|
**YOU (orchestrator) do this directly. No agent spawn.**
|
||||||
and can use tools directly. This is bookkeeping work, not creative work.
|
|
||||||
|
|
||||||
**YOU (the orchestrator) must execute these commands directly:**
|
|
||||||
|
|
||||||
**Step 5.1: Get what was built**
|
**Step 5.1: Get what was built**
|
||||||
```bash
|
```bash
|
||||||
# Get commit for this story
|
git log -3 --oneline | grep "{{story_key}}"
|
||||||
COMMIT_INFO=$(git log -5 --oneline | grep "{{story_key}}" | head -1)
|
git diff HEAD~1 --name-only | head -20
|
||||||
echo "Commit: $COMMIT_INFO"
|
|
||||||
|
|
||||||
# Get files changed (production code only)
|
|
||||||
FILES_CHANGED=$(git diff HEAD~1 --name-only | grep -v "__tests__" | grep -v "\.test\." | grep -v "\.spec\.")
|
|
||||||
echo "Files changed:"
|
|
||||||
echo "$FILES_CHANGED"
|
|
||||||
```
|
```
|
||||||
|
|
||||||
**Step 5.2: Read story file tasks**
|
**Step 5.2: Read story file**
|
||||||
Use Read tool: `{{story_file}}`
|
Use Read tool: `docs/sprint-artifacts/{{story_key}}.md`
|
||||||
|
|
||||||
Find the Tasks section and identify which tasks relate to the files changed.
|
|
||||||
|
|
||||||
**Step 5.3: Check off completed tasks**
|
**Step 5.3: Check off completed tasks**
|
||||||
Use Edit tool for EACH task that was completed:
|
For each task related to files changed, use Edit tool:
|
||||||
```
|
```
|
||||||
old_string: "- [ ] Task description here"
|
old_string: "- [ ] Task description"
|
||||||
new_string: "- [x] Task description here"
|
new_string: "- [x] Task description"
|
||||||
```
|
```
|
||||||
|
|
||||||
**Step 5.4: Fill Dev Agent Record**
|
**Step 5.4: Fill Dev Agent Record**
|
||||||
Use Edit tool to update the Dev Agent Record section:
|
Use Edit tool to update Dev Agent Record section with:
|
||||||
```
|
- Agent Model: Claude Sonnet 4 (multi-agent pipeline)
|
||||||
old_string: "### Dev Agent Record
|
- Implementation Date: {{date}}
|
||||||
- **Agent Model Used:** [Not set]
|
- Files Created/Modified: [list from git diff]
|
||||||
- **Implementation Date:** [Not set]
|
- Tests Added: [count from Inspector]
|
||||||
- **Files Created/Modified:** [Not set]
|
- Completion Notes: [brief summary]
|
||||||
- **Tests Added:** [Not set]
|
|
||||||
- **Completion Notes:** [Not set]"
|
|
||||||
|
|
||||||
new_string: "### Dev Agent Record
|
**Step 5.5: Verify updates**
|
||||||
- **Agent Model Used:** Claude Sonnet 4 (multi-agent: Builder + Inspector + Reviewer + Fixer)
|
|
||||||
- **Implementation Date:** {{date}}
|
|
||||||
- **Files Created/Modified:**
|
|
||||||
{{#each files_changed}}
|
|
||||||
- {{this}}
|
|
||||||
{{/each}}
|
|
||||||
- **Tests Added:** [count from Inspector report]
|
|
||||||
- **Completion Notes:** [brief summary of what was implemented]"
|
|
||||||
```
|
|
||||||
|
|
||||||
**Step 5.5: Verify updates (BLOCKER)**
|
|
||||||
```bash
|
```bash
|
||||||
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
|
CHECKED=$(grep -c "^- \[x\]" docs/sprint-artifacts/{{story_key}}.md)
|
||||||
echo "🔍 RECONCILIATION VERIFICATION"
|
|
||||||
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
|
|
||||||
|
|
||||||
# Count checked tasks
|
|
||||||
CHECKED=$(grep -c "^- \[x\]" {{story_file}})
|
|
||||||
echo "Checked tasks: $CHECKED"
|
|
||||||
|
|
||||||
if [ "$CHECKED" -eq 0 ]; then
|
if [ "$CHECKED" -eq 0 ]; then
|
||||||
echo "❌ BLOCKER: Zero checked tasks"
|
echo "❌ BLOCKER: Zero checked tasks"
|
||||||
echo "Go back to Step 5.3 and check off tasks"
|
|
||||||
exit 1
|
exit 1
|
||||||
fi
|
fi
|
||||||
|
echo "✅ Verified: $CHECKED tasks checked"
|
||||||
# Verify Dev Agent Record
|
|
||||||
RECORD=$(grep -A 5 "### Dev Agent Record" {{story_file}} | grep -c "Implementation Date:")
|
|
||||||
if [ "$RECORD" -eq 0 ]; then
|
|
||||||
echo "❌ BLOCKER: Dev Agent Record not filled"
|
|
||||||
echo "Go back to Step 5.4 and fill it"
|
|
||||||
exit 1
|
|
||||||
fi
|
|
||||||
|
|
||||||
echo "✅ Reconciliation verified: $CHECKED tasks checked"
|
|
||||||
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
|
|
||||||
```
|
```
|
||||||
|
|
||||||
**If verification fails:** DO NOT proceed. Fix immediately using Edit tool, then re-verify.
|
If verification fails: fix using Edit, then re-verify.
|
||||||
|
</step>
|
||||||
|
|
||||||
---
|
<step name="final_verification">
|
||||||
|
**Final Quality Gate**
|
||||||
## Final Verification (Main Orchestrator)
|
|
||||||
|
|
||||||
🚨 **CRITICAL: This verification is MANDATORY. DO NOT skip.** 🚨
|
|
||||||
|
|
||||||
**After all agents complete (including Reconciler), YOU (the main orchestrator) must:**
|
|
||||||
|
|
||||||
1. **Use the Bash tool** to run these commands
|
|
||||||
2. **Read the output** to see if verification passed
|
|
||||||
3. **If verification fails**, use Edit and Bash tools to fix it NOW
|
|
||||||
4. **Do not proceed** until verification passes
|
|
||||||
|
|
||||||
**COMMAND TO RUN WITH BASH TOOL:**
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
|
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
|
||||||
echo "🔍 FINAL VERIFICATION (MANDATORY)"
|
echo "🔍 FINAL VERIFICATION"
|
||||||
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
|
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
|
||||||
|
|
||||||
# 1. Check git commits exist
|
# 1. Git commit exists
|
||||||
echo "Checking git commits..."
|
git log --oneline -3 | grep "{{story_key}}" || { echo "❌ No commit"; exit 1; }
|
||||||
git log --oneline -3 | grep "{{story_key}}"
|
|
||||||
if [ $? -ne 0 ]; then
|
|
||||||
echo "❌ FAILED: No commit found for {{story_key}}"
|
|
||||||
echo "The Fixer agent did not commit changes."
|
|
||||||
exit 1
|
|
||||||
fi
|
|
||||||
echo "✅ Git commit found"
|
echo "✅ Git commit found"
|
||||||
|
|
||||||
# 2. Check story file has checked tasks (ABSOLUTE BLOCKER)
|
# 2. Story tasks checked
|
||||||
echo "Checking story file updates..."
|
CHECKED=$(grep -c "^- \[x\]" docs/sprint-artifacts/{{story_key}}.md)
|
||||||
CHECKED_COUNT=$(grep -c '^- \[x\]' {{story_file}})
|
[ "$CHECKED" -gt 0 ] || { echo "❌ No tasks checked"; exit 1; }
|
||||||
echo "Checked tasks: $CHECKED_COUNT"
|
echo "✅ $CHECKED tasks checked"
|
||||||
|
|
||||||
if [ "$CHECKED_COUNT" -eq 0 ]; then
|
# 3. Dev Agent Record filled
|
||||||
echo ""
|
grep -A 3 "### Dev Agent Record" docs/sprint-artifacts/{{story_key}}.md | grep -q "202" || { echo "❌ Record not filled"; exit 1; }
|
||||||
echo "❌ BLOCKER: Story file has ZERO checked tasks"
|
|
||||||
echo ""
|
|
||||||
echo "This means the Fixer agent did NOT update the story file."
|
|
||||||
echo "The story CANNOT be marked complete without checked tasks."
|
|
||||||
echo ""
|
|
||||||
echo "You must:"
|
|
||||||
echo " 1. Read the git commit to see what was built"
|
|
||||||
echo " 2. Read the story Tasks section"
|
|
||||||
echo " 3. Use Edit tool to check off completed tasks"
|
|
||||||
echo " 4. Fill in Dev Agent Record"
|
|
||||||
echo " 5. Verify with grep"
|
|
||||||
echo " 6. Re-run this verification"
|
|
||||||
echo ""
|
|
||||||
exit 1
|
|
||||||
fi
|
|
||||||
echo "✅ Story file has $CHECKED_COUNT checked tasks"
|
|
||||||
|
|
||||||
# 3. Check Dev Agent Record filled
|
|
||||||
echo "Checking Dev Agent Record..."
|
|
||||||
RECORD_FILLED=$(grep -A 20 "^### Dev Agent Record" {{story_file}} | grep -c "Agent Model")
|
|
||||||
if [ "$RECORD_FILLED" -eq 0 ]; then
|
|
||||||
echo "❌ BLOCKER: Dev Agent Record NOT filled"
|
|
||||||
echo "The Fixer agent did not document what was built."
|
|
||||||
exit 1
|
|
||||||
fi
|
|
||||||
echo "✅ Dev Agent Record filled"
|
echo "✅ Dev Agent Record filled"
|
||||||
|
|
||||||
# 4. Check sprint-status updated
|
|
||||||
echo "Checking sprint-status..."
|
|
||||||
git diff HEAD~1 {{sprint_status}} | grep "{{story_key}}"
|
|
||||||
if [ $? -ne 0 ]; then
|
|
||||||
echo "❌ FAILED: Sprint status not updated for {{story_key}}"
|
|
||||||
exit 1
|
|
||||||
fi
|
|
||||||
echo "✅ Sprint status updated"
|
|
||||||
|
|
||||||
# 5. Check test evidence (optional - may have test failures)
|
|
||||||
echo "Checking test evidence..."
|
|
||||||
if [ -f "inspector_output.txt" ]; then
|
|
||||||
grep -E "PASS|tests.*passing" inspector_output.txt && echo "✅ Tests passing"
|
|
||||||
fi
|
|
||||||
|
|
||||||
echo ""
|
echo ""
|
||||||
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
|
echo "✅ STORY COMPLETE"
|
||||||
echo "✅ STORY COMPLETE - All verifications passed"
|
|
||||||
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
|
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
|
||||||
```
|
```
|
||||||
|
|
||||||
**IF VERIFICATION FAILS:**
|
**Update sprint-status.yaml:**
|
||||||
- DO NOT mark story as "done"
|
Use Edit tool to change story status from `ready-for-dev` to `done`.
|
||||||
- DO NOT proceed to next story
|
</step>
|
||||||
- FIX the failure immediately
|
|
||||||
- Re-run verification until it passes
|
|
||||||
|
|
||||||
---
|
</process>
|
||||||
|
|
||||||
## Benefits Over Single-Agent
|
<failure_handling>
|
||||||
|
**Builder fails:** Don't spawn Inspector. Report failure.
|
||||||
|
**Inspector fails:** Don't spawn Reviewer. Report specific failures.
|
||||||
|
**Reviewer finds CRITICAL:** Fixer must fix (not optional).
|
||||||
|
**Fixer fails:** Report unfixed issues. Manual intervention needed.
|
||||||
|
**Reconciliation fails:** Fix using Edit tool. Re-verify.
|
||||||
|
</failure_handling>
|
||||||
|
|
||||||
### Separation of Concerns
|
<complexity_routing>
|
||||||
- Builder doesn't validate own work
|
| Complexity | Agents | Notes |
|
||||||
- Inspector has no incentive to lie
|
|------------|--------|-------|
|
||||||
- Reviewer approaches with fresh eyes
|
| micro | Builder → Inspector → Fixer | Skip Reviewer (low risk) |
|
||||||
- Fixer can't skip issues
|
| standard | Builder → Inspector → Reviewer → Fixer | Full pipeline |
|
||||||
|
| complex | Builder → Inspector → Reviewer (enhanced) → Fixer | Extra scrutiny |
|
||||||
|
</complexity_routing>
|
||||||
|
|
||||||
### Fresh Context Each Phase
|
<success_criteria>
|
||||||
- Each agent starts at 0% context
|
- [ ] All agents completed successfully
|
||||||
- No accumulated fatigue
|
- [ ] Git commit exists for story
|
||||||
- No degraded quality
|
- [ ] Story file has checked tasks (count > 0)
|
||||||
- Honest reporting
|
- [ ] Dev Agent Record filled
|
||||||
|
- [ ] Sprint status updated to "done"
|
||||||
### Adversarial Review
|
</success_criteria>
|
||||||
- Reviewer WANTS to find issues
|
|
||||||
- Not defensive about the code
|
|
||||||
- More thorough than self-review
|
|
||||||
|
|
||||||
### Honest Verification
|
|
||||||
- Inspector runs tests independently
|
|
||||||
- Main orchestrator verifies everything
|
|
||||||
- Can't fake completion
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Complexity Routing
|
|
||||||
|
|
||||||
**MICRO stories:**
|
|
||||||
- Skip Reviewer (low risk)
|
|
||||||
- 2 agents: Builder → Inspector → Fixer
|
|
||||||
|
|
||||||
**STANDARD stories:**
|
|
||||||
- Full pipeline
|
|
||||||
- 4 agents: Builder → Inspector → Reviewer → Fixer
|
|
||||||
|
|
||||||
**COMPLEX stories:**
|
|
||||||
- Enhanced review (6 reviewers instead of 4)
|
|
||||||
- Full pipeline + extra scrutiny
|
|
||||||
- 4 agents: Builder → Inspector → Reviewer (enhanced) → Fixer
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Agent Tracking
|
|
||||||
|
|
||||||
Track all agents in `agent-history.json`:
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"version": "1.0",
|
|
||||||
"max_entries": 50,
|
|
||||||
"entries": [
|
|
||||||
{
|
|
||||||
"agent_id": "abc123",
|
|
||||||
"story_key": "17-10",
|
|
||||||
"phase": "builder",
|
|
||||||
"steps": [1,2,3,4],
|
|
||||||
"timestamp": "2026-01-25T21:00:00Z",
|
|
||||||
"status": "completed",
|
|
||||||
"completion_timestamp": "2026-01-25T21:15:00Z"
|
|
||||||
},
|
|
||||||
{
|
|
||||||
"agent_id": "def456",
|
|
||||||
"story_key": "17-10",
|
|
||||||
"phase": "inspector",
|
|
||||||
"steps": [5,6],
|
|
||||||
"timestamp": "2026-01-25T21:16:00Z",
|
|
||||||
"status": "completed",
|
|
||||||
"completion_timestamp": "2026-01-25T21:20:00Z"
|
|
||||||
}
|
|
||||||
]
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
**Benefits:**
|
|
||||||
- Resume interrupted sessions
|
|
||||||
- Track agent performance
|
|
||||||
- Debug failed pipelines
|
|
||||||
- Audit trail
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Error Handling
|
|
||||||
|
|
||||||
**If Builder fails:**
|
|
||||||
- Don't spawn Inspector
|
|
||||||
- Report failure to user
|
|
||||||
- Option to resume or retry
|
|
||||||
|
|
||||||
**If Inspector fails:**
|
|
||||||
- Don't spawn Reviewer
|
|
||||||
- Report specific failures
|
|
||||||
- Resume Builder to fix issues
|
|
||||||
|
|
||||||
**If Reviewer finds CRITICAL issues:**
|
|
||||||
- Must spawn Fixer (not optional)
|
|
||||||
- Cannot mark story complete until fixed
|
|
||||||
|
|
||||||
**If Fixer fails:**
|
|
||||||
- Report unfixed issues
|
|
||||||
- Cannot mark story complete
|
|
||||||
- Manual intervention required
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Comparison: v1.x vs v2.0
|
|
||||||
|
|
||||||
| Aspect | v1.x (Single-Agent) | v2.0 (Multi-Agent) |
|
|
||||||
|--------|--------------------|--------------------|
|
|
||||||
| Agents | 1 | 4 |
|
|
||||||
| Validation | Self (conflict of interest) | Independent (no conflict) |
|
|
||||||
| Code Review | Self-review | Adversarial (fresh eyes) |
|
|
||||||
| Honesty | Low (can lie) | High (verified) |
|
|
||||||
| Context | Degrades over 11 steps | Fresh each phase |
|
|
||||||
| Catches Issues | Low | High |
|
|
||||||
| Completion Accuracy | ~60% (agents lie) | ~95% (verified) |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Migration from v1.x
|
|
||||||
|
|
||||||
**Backward Compatibility:**
|
|
||||||
```yaml
|
|
||||||
execution_mode: "single_agent" # Use v1.x
|
|
||||||
execution_mode: "multi_agent" # Use v2.0 (new)
|
|
||||||
```
|
|
||||||
|
|
||||||
**Gradual Rollout:**
|
|
||||||
1. Week 1: Test v2.0 on 3-5 stories
|
|
||||||
2. Week 2: Make v2.0 default for new stories
|
|
||||||
3. Week 3: Migrate existing stories to v2.0
|
|
||||||
4. Week 4: Deprecate v1.x
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Hospital-Grade Standards
|
|
||||||
|
|
||||||
⚕️ **Lives May Be at Stake**
|
|
||||||
|
|
||||||
- Independent validation catches errors
|
|
||||||
- Adversarial review finds security flaws
|
|
||||||
- Multiple checkpoints prevent shortcuts
|
|
||||||
- Final verification prevents false completion
|
|
||||||
|
|
||||||
**QUALITY >> SPEED**
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
**Key Takeaway:** Don't trust a single agent to build, validate, review, and commit its own work. Use independent agents with fresh context at each phase.
|
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue