From 486196cd4fe2d0efaa75a5b75a31da4718aa3966 Mon Sep 17 00:00:00 2001 From: Jonah Schulte Date: Mon, 26 Jan 2026 21:24:52 -0500 Subject: [PATCH] feat: add mandatory Reconciler agent to ensure story files are always updated MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit **Critical Addition:** New Reconciler agent (Phase 5, Step 10) **Why This Matters:** After Builder/Inspector/Reviewer/Fixer complete, story files were NOT being updated. User had no way to know what was built or mark stories complete. **Solution:** - Added dedicated Reconciler agent that runs LAST - Single responsibility: Update story file and verify - Mandatory: true (cannot be skipped) - Has bash verification commands that exit 1 on failure - Main orchestrator must spawn this agent - Main orchestrator must verify it succeeded **Enforcement:** - Reconciler runs explicit bash verification (checked tasks count, Dev Agent Record filled) - If verification fails, agent exits 1 - Main orchestrator sees failure and stops - Story cannot be marked complete until reconciliation passes **Agent Flow:** Builder → Inspector → Reviewer → Fixer → Reconciler (NEW) → Final Verification **Version:** 6.0.0-Beta.5 --- .../super-dev-pipeline/agents/reconciler.md | 226 ++++++++++++++++++ .../super-dev-pipeline/workflow.md | 60 ++++- .../super-dev-pipeline/workflow.yaml | 10 + 3 files changed, 293 insertions(+), 3 deletions(-) create mode 100644 src/modules/bmm/workflows/4-implementation/super-dev-pipeline/agents/reconciler.md diff --git a/src/modules/bmm/workflows/4-implementation/super-dev-pipeline/agents/reconciler.md b/src/modules/bmm/workflows/4-implementation/super-dev-pipeline/agents/reconciler.md new file mode 100644 index 00000000..d821c4ce --- /dev/null +++ b/src/modules/bmm/workflows/4-implementation/super-dev-pipeline/agents/reconciler.md @@ -0,0 +1,226 @@ +# Reconciler Agent - Story File Update (MANDATORY) + +**Role:** Update story file with implementation results +**Step:** 10 (final - runs after Fixer completes) +**Trust Level:** HIGH (simple, focused task) +**Mandatory:** YES (cannot be skipped) + +--- + +## Your Mission + +You are the **RECONCILER** agent. Your ONLY job is to update the story file to reflect what was built. + +🚨 **THIS IS THE MOST IMPORTANT STEP** 🚨 + +Without this step, no one knows what was built. The story file is the source of truth. + +--- + +## What You Must Do + +### Step 1: Read the Git Commit + +```bash +# Get the commit message for this story +git log -1 --pretty=format:"%H %s %b" | head -20 + +# Get files changed +git diff HEAD~1 --name-only | grep -v "^test/" | grep -v "__tests__" +``` + +**Extract:** +- Commit SHA +- Files created/modified (production code only, exclude tests for now) +- What was built (from commit message) + +--- + +### Step 2: Read the Story File + +```bash +# Read the full story file +cat docs/sprint-artifacts/{{story_key}}.md +``` + +**Find:** +- Tasks section (look for `## Tasks`) +- Dev Agent Record section (look for `### Dev Agent Record`) +- Current completion status + +--- + +### Step 3: Check Off Completed Tasks + +**For EACH task in the Tasks section:** + +1. **Read the task description** +2. **Check if related code exists in git diff** + - Does the task mention a file that was created/modified? + - Does the task mention a function/service that now exists? +3. **If YES: Use Edit tool to check it off** + - Change `- [ ]` to `- [x]` + - Use exact string matching +4. **Verify the edit worked:** + ```bash + grep "^\- \[x\].*{{task keyword}}" docs/sprint-artifacts/{{story_key}}.md + ``` + +**Example:** + +Task: `- [ ] Create BillingWorker service` + +Check if it exists: +```bash +git diff HEAD~1 --name-only | grep -i "worker" +# Returns: lib/billing/worker.ts +``` + +Edit the story file: +```typescript +old_string: "- [ ] Create BillingWorker service" +new_string: "- [x] Create BillingWorker service" +``` + +Verify: +```bash +grep "^\- \[x\].*BillingWorker" docs/sprint-artifacts/{{story_key}}.md +# Should return the checked line +``` + +--- + +### Step 4: Fill Dev Agent Record + +Find the Dev Agent Record section and replace it with actual data: + +**BEFORE:** +```markdown +### Dev Agent Record +- **Agent Model Used:** [Not set] +- **Implementation Date:** [Not set] +- **Files Created/Modified:** [Not set] +- **Tests Added:** [Not set] +- **Completion Notes:** [Not set] +``` + +**AFTER:** +```markdown +### Dev Agent Record +- **Agent Model Used:** Claude Sonnet 4.5 (multi-agent: Builder + Inspector + Reviewer + Fixer + Reconciler) +- **Implementation Date:** 2026-01-26 +- **Files Created/Modified:** + - lib/billing/worker.ts + - lib/billing/payment-processor.ts + - lib/billing/retry-scheduler.ts + - [ALL files from git diff --name-only HEAD~1] +- **Tests Added:** + - lib/billing/__tests__/worker.test.ts + - lib/billing/__tests__/payment-processor.test.ts + - lib/billing/__tests__/retry-scheduler.test.ts +- **Completion Notes:** + - Implemented retry logic with exponential backoff + - Fixed 8 CRITICAL/HIGH code review findings + - All type checks passing, lint clean + - Tests: [status from Inspector report] +``` + +Use the Edit tool to replace the entire Dev Agent Record section. + +--- + +### Step 5: Verify Your Work (BLOCKER) + +🚨 **THIS VERIFICATION IS MANDATORY. YOU MUST RUN IT.** 🚨 + +```bash +echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" +echo "🔍 RECONCILIATION VERIFICATION" +echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" + +# Check 1: Count checked tasks +CHECKED_COUNT=$(grep -c "^\- \[x\]" docs/sprint-artifacts/{{story_key}}.md) +echo "Checked tasks: $CHECKED_COUNT" + +if [ "$CHECKED_COUNT" -eq 0 ]; then + echo "" + echo "❌ RECONCILIATION FAILED" + echo "Story file has ZERO checked tasks." + echo "You MUST go back to Step 3 and check off tasks." + echo "" + exit 1 +fi + +# Check 2: Verify Dev Agent Record filled +RECORD_FILLED=$(grep -A 20 "^### Dev Agent Record" docs/sprint-artifacts/{{story_key}}.md | grep -c "Claude Sonnet") +echo "Dev Agent Record filled: $RECORD_FILLED" + +if [ "$RECORD_FILLED" -eq 0 ]; then + echo "" + echo "❌ RECONCILIATION FAILED" + echo "Dev Agent Record NOT filled." + echo "You MUST go back to Step 4 and fill it in." + echo "" + exit 1 +fi + +echo "" +echo "✅ RECONCILIATION SUCCESSFUL" +echo " - Checked tasks: $CHECKED_COUNT" +echo " - Dev Agent Record: FILLED" +echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" +``` + +**If verification fails:** +- STOP immediately +- Fix the issue +- Re-run verification +- DO NOT report "COMPLETE" until verification passes + +**If verification passes:** +- Report success with task count +- Story is now officially complete + +--- + +## Output Requirements + +**Provide Reconciliation Summary:** + +```markdown +## Reconciliation Complete + +**Story File Updated:** +- ✅ Tasks checked: X/Y tasks marked complete +- ✅ Dev Agent Record filled with implementation details +- ✅ Verification passed + +**What Was Built:** +- File 1: lib/billing/worker.ts (BillingWorker service) +- File 2: lib/billing/payment-processor.ts (Payment processing) +- File 3: lib/billing/retry-scheduler.ts (Retry scheduling) +- [List ALL production files from git diff] + +**Tests:** +- X tests added +- Y tests passing +- Coverage: Z% + +**Story Status:** READY FOR COMPLETION +``` + +--- + +## Remember + +🚨 **Your job is RECONCILIATION, not implementation** 🚨 + +- Don't write code +- Don't fix bugs +- Don't run tests +- ONLY update the story file +- ONLY verify it worked + +If you do this right, the user will know EXACTLY what was built and can mark the story done with confidence. + +**This is the last step. Make it count.** diff --git a/src/modules/bmm/workflows/4-implementation/super-dev-pipeline/workflow.md b/src/modules/bmm/workflows/4-implementation/super-dev-pipeline/workflow.md index da48209d..18cd2670 100644 --- a/src/modules/bmm/workflows/4-implementation/super-dev-pipeline/workflow.md +++ b/src/modules/bmm/workflows/4-implementation/super-dev-pipeline/workflow.md @@ -50,12 +50,19 @@ This workflow implements a story using **4 independent agents** with external va │ - Fix HIGH issues (all) │ - Fix MEDIUM issues (if time) │ - Skip LOW issues (gold-plating) - │ - Update story + sprint-status - │ - Commit changes + │ - Commit code changes + │ + ├──> Phase 5: Reconciler (Step 10) 🚨 MANDATORY + │ - Read git commit to see what was built + │ - Check off completed tasks in story file + │ - Fill Dev Agent Record with details + │ - VERIFY updates with bash commands + │ - BLOCKER: Exit 1 if verification fails │ └──> Final Verification (Main) - Check git commits exist - - Check story checkboxes updated + - Check story checkboxes updated (count > 0) + - Check Dev Agent Record filled - Check sprint-status updated - Check tests passed - Mark COMPLETE or FAILED @@ -183,6 +190,53 @@ Task({ **Wait for Fixer to complete.** +### Phase 5: Spawn Reconciler (MANDATORY) + +🚨 **THIS PHASE IS MANDATORY. ALWAYS RUN. CANNOT BE SKIPPED.** 🚨 + +```javascript +Task({ + subagent_type: "general-purpose", + description: "Reconcile story {{story_key}}", + prompt: ` + You are the RECONCILER agent for story {{story_key}}. + + Load and execute: {agents_path}/reconciler.md + + Story file: {{story_file}} + Story key: {{story_key}} + + Complete Step 10 - Story Reconciliation: + + Your ONLY job: + 1. Read git commit to see what was built + 2. Check off completed tasks in story file (Edit tool) + 3. Fill Dev Agent Record with files/dates/notes + 4. Verify updates worked (bash grep commands) + 5. Exit 1 if verification fails + + DO NOT: + - Write code + - Fix bugs + - Run tests + - Do anything except update the story file + + This is the LAST step. The story cannot be marked complete + without your verification passing. + + Output: Reconciliation summary with checked task count. + ` +}); +``` + +**Wait for Reconciler to complete. Verification MUST pass.** + +**If Reconciler verification fails (exit 1):** +- DO NOT proceed +- DO NOT mark story complete +- Fix the reconciliation immediately +- Re-run Reconciler until it passes + --- ## Final Verification (Main Orchestrator) diff --git a/src/modules/bmm/workflows/4-implementation/super-dev-pipeline/workflow.yaml b/src/modules/bmm/workflows/4-implementation/super-dev-pipeline/workflow.yaml index 122750d3..f3165c02 100644 --- a/src/modules/bmm/workflows/4-implementation/super-dev-pipeline/workflow.yaml +++ b/src/modules/bmm/workflows/4-implementation/super-dev-pipeline/workflow.yaml @@ -67,6 +67,16 @@ agents: trust_level: "medium" # Incentive to minimize work timeout: 2400 # 40 minutes + reconciler: + description: "Story reconciliation - MANDATORY story file updates" + steps: [10] + subagent_type: "general-purpose" + prompt_file: "{agents_path}/reconciler.md" + trust_level: "high" # Simple, focused task + timeout: 600 # 10 minutes + mandatory: true # Cannot be skipped + runs_after: "fixer" + # Complexity level (determines which steps to execute) complexity_level: "standard" # micro | standard | complex