agent-workflow.md
1 # Agent Workflow System 2 3 ## Overview 4 5 The agent system implements a formal approval workflow for significant changes to ensure architectural review and Product Owner alignment. 6 7 **Key Principles:** 8 9 - **Architect-first design**: Significant changes require design proposals before implementation 10 - **Product Owner approval**: Breaking changes, migrations, and large features require PO sign-off 11 - **Technical review**: All implementation plans reviewed by Architect for soundness 12 - **Quality gates**: 85%+ test coverage required, max 150 lines per file 13 14 ## Workflow States 15 16 Tasks can be in the following states: 17 18 - `pending` - Ready to work on 19 - `running` - Currently being processed 20 - `awaiting_po_approval` - Design proposal awaiting Product Owner approval 21 - `awaiting_architect_approval` - Implementation plan awaiting Architect technical review 22 - `completed` - Successfully finished 23 - `failed` - Failed to complete 24 - `blocked` - Blocked on external dependency 25 26 ## Standard Workflows 27 28 ### Feature Implementation (Significant) 29 30 ``` 31 1. Product change request → CREATE design_proposal task (Architect) 32 2. Architect analyzes → Creates design document → Status: awaiting_po_approval 33 3. PO reviews in human_review_queue → Approves/Rejects 34 4. If approved → CREATE implementation_plan task (Developer) 35 5. Developer creates detailed plan → Status: awaiting_architect_approval 36 6. Architect reviews plan → CREATE technical_review task → Approves/Requests changes 37 7. If approved → Original task status: pending 38 8. Developer implements → CREATE verify_fix task (QA) 39 9. QA tests → Completes or sends feedback 40 ``` 41 42 **Triggers PO approval when:** 43 44 - Breaking changes detected 45 - Database migration required 46 - Estimated effort > 4 hours 47 - Explicitly marked as "significant" 48 49 ### Feature Implementation (Minor) 50 51 ``` 52 1. Product change request → CREATE design_proposal task (Architect) 53 2. Architect analyzes → Auto-approves (no PO needed) 54 3. Immediately CREATE implementation_plan task (Developer) 55 4. Developer creates plan → Status: awaiting_architect_approval 56 5. Architect approves → Developer implements → QA tests 57 ``` 58 59 **Auto-approved when:** 60 61 - No breaking changes 62 - No database migrations 63 - Estimated effort ≤ 4 hours 64 - Marked as "minor" 65 66 ### Bug Fix (Architectural) 67 68 ``` 69 1. Triage classifies as architectural → CREATE design_proposal task (Architect) 70 2. Architect analyzes fix approach → Status: awaiting_po_approval 71 3. PO approves → Developer creates implementation plan 72 4. Architect approves → Developer fixes → QA verifies 73 ``` 74 75 **Classified as architectural when:** 76 77 - Affects multiple modules 78 - Requires schema changes 79 - Changes core business logic 80 - Impacts API contracts 81 82 ### Bug Fix (Standard) 83 84 ``` 85 1. Triage classifies as simple bug → CREATE fix_bug task (Developer) 86 2. Developer fixes → QA verifies 87 ``` 88 89 **No approval needed for:** 90 91 - Isolated bugs in single file 92 - No schema changes 93 - No breaking changes 94 - Low complexity 95 96 ## Task Types 97 98 ### design_proposal 99 100 - **Assigned to:** Architect 101 - **Purpose:** Analyze feature requirements and create design document 102 - **Outputs:** Design document with impact analysis, approach, risks, alternatives 103 - **Context fields:** 104 - `feature_description` - What to build 105 - `requirements` - Array of requirements 106 - `significance` - "significant" or "minor" 107 - `workflow_type` - "feature_with_approval" or "bug_fix_architectural" 108 - **Next steps:** 109 - If significant: Request PO approval → Status: `awaiting_po_approval` 110 - If minor: Auto-approve and create `implementation_plan` task 111 112 **Example:** 113 114 ```javascript 115 createAgentTask({ 116 task_type: 'design_proposal', 117 assigned_to: 'architect', 118 priority: 7, 119 context: { 120 feature_description: 'Add dark mode toggle to settings', 121 requirements: ['Toggle in UI', 'Persist to localStorage', 'Apply globally'], 122 significance: 'significant', 123 workflow_type: 'feature_with_approval', 124 }, 125 }); 126 ``` 127 128 ### implementation_plan 129 130 - **Assigned to:** Developer 131 - **Purpose:** Break down design into specific implementation steps 132 - **Outputs:** Step-by-step plan, file list, test plan 133 - **Context fields:** 134 - `design_proposal` - Approved design document 135 - **Next steps:** Request Architect approval → Status: `awaiting_architect_approval` 136 137 **Example:** 138 139 ```javascript 140 // Created automatically by Architect after PO approval 141 createAgentTask({ 142 task_type: 'implementation_plan', 143 assigned_to: 'developer', 144 parent_task_id: 42, // design_proposal task 145 context: { 146 design_proposal: { ... }, 147 }, 148 }); 149 ``` 150 151 ### technical_review 152 153 - **Assigned to:** Architect 154 - **Purpose:** Review implementation plan for technical soundness 155 - **Outputs:** Approval or feedback for revision 156 - **Context fields:** 157 - `implementation_plan` - Developer's implementation plan 158 - `original_task_id` - ID of implementation_plan task being reviewed 159 - **Checks:** 160 - File complexity (will any file exceed 150 lines?) 161 - Test coverage plan (target ≥ 85%) 162 - Documentation updates planned 163 - Architectural soundness 164 - **Next steps:** 165 - If approved: Original task status → `pending` 166 - If rejected: Send feedback to Developer for revision 167 168 **Example:** 169 170 ```javascript 171 // Created automatically by Developer when plan is ready 172 createAgentTask({ 173 task_type: 'technical_review', 174 assigned_to: 'architect', 175 parent_task_id: 43, // implementation_plan task 176 context: { 177 implementation_plan: { ... }, 178 original_task_id: 43, 179 }, 180 }); 181 ``` 182 183 ## Approval Gates 184 185 ### Product Owner Approval 186 187 **When required:** 188 189 - Breaking changes 190 - Schema migrations 191 - Features requiring >4 hours effort 192 - Significant architectural changes 193 194 **How it works:** 195 196 1. Architect calls `requestPoApproval(taskId, proposal)` 197 2. Task status → `awaiting_po_approval` 198 3. Item added to `human_review_queue` table 199 4. PO reviews via dashboard or CLI 200 5. PO runs: `npm run agent:approve -- --task-id X --decision approved --reviewer "Jason"` 201 6. Task status → `completed` with approval metadata 202 7. Next task in workflow created automatically 203 204 **Approval decisions:** 205 206 - `approved` - Proceed with implementation 207 - `approved_with_conditions` - Proceed but with constraints (e.g., "Keep under 150 lines") 208 - `rejected` - Do not proceed, task marked as failed 209 210 ### Architect Approval 211 212 **When required:** 213 214 - All implementation plans 215 - Refactoring proposals 216 - Performance optimizations 217 218 **How it works:** 219 220 1. Developer calls `requestArchitectApproval(taskId, plan)` 221 2. Task status → `awaiting_architect_approval` 222 3. `technical_review` task created for Architect 223 4. Architect reviews and approves/rejects 224 5. If approved, original task status → `pending` 225 6. Developer proceeds with implementation 226 227 **Review criteria:** 228 229 - Files won't exceed 150 lines 230 - Test coverage target ≥ 85% 231 - Documentation updates included 232 - Complexity within acceptable limits 233 - No over-engineering (factories, builders, unnecessary abstractions) 234 235 ## Validation Rules 236 237 Tasks are validated before creation using `validateWorkflowDependencies()`: 238 239 1. **implement_feature** requires approved `design_proposal` parent 240 - Parent must exist 241 - Parent must be `completed` 242 - Parent must have `approval_json` with `decision: 'approved'` 243 244 2. **Developer implementation** requires approved `implementation_plan` 245 - Checked at task start 246 - If validation fails, task fails with clear reason 247 248 3. **QA verification** requires completed Developer task 249 - Standard parent-child relationship 250 - Parent must be `completed` before child starts 251 252 4. **Parent tasks** must be completed before children start 253 - Enforced by task polling logic 254 - Children with incomplete parents remain `pending` 255 256 ## Database Schema 257 258 ```sql 259 -- agent_tasks additions (migration 051) 260 reviewed_by TEXT -- Who approved the task 261 approval_json TEXT -- {decision, reviewer, timestamp, notes, conditions} 262 status CHECK(..., 'awaiting_po_approval', 'awaiting_architect_approval') 263 264 -- approval_json structure 265 { 266 "decision": "approved", -- approved|approved_with_conditions|rejected 267 "reviewer": "Jason", -- Human name or agent name 268 "timestamp": "2026-02-15T10:30:00Z", 269 "notes": "Looks good, proceed", 270 "conditions": ["Keep files under 150 lines"] 271 } 272 ``` 273 274 **Indexes:** 275 276 ```sql 277 CREATE INDEX idx_agent_tasks_approval 278 ON agent_tasks(status, assigned_to) 279 WHERE status IN ('awaiting_po_approval', 'awaiting_architect_approval'); 280 ``` 281 282 ## CLI Commands 283 284 ### View Pending Approvals 285 286 ```bash 287 npm run agent:approvals 288 289 # Filter by approval type 290 npm run agent:approvals -- --status awaiting_po_approval 291 npm run agent:approvals -- --status awaiting_architect_approval 292 ``` 293 294 **Output:** 295 296 ``` 297 📋 Tasks Awaiting Approval (2) 298 299 ID Type Status Priority Created 300 ───────────────────────────────────────────────────────────────────────────── 301 42 design_proposal awaiting_po_approval 7 2026-02-15 10:00:00 302 📝 Implement dark mode toggle for settings page 303 43 implementation_plan awaiting_architect_approval 6 2026-02-15 11:00:00 304 📝 Implementation plan for dark mode feature 305 ``` 306 307 ### Approve Design Proposal (PO) 308 309 ```bash 310 # Simple approval 311 npm run agent:approve -- --task-id 42 --reviewer "Jason" --decision approved 312 313 # Approval with notes 314 npm run agent:approve -- --task-id 42 --reviewer "Jason" --decision approved --notes "Great idea, proceed" 315 316 # Approval with conditions 317 npm run agent:approve -- \ 318 --task-id 42 \ 319 --reviewer "Jason" \ 320 --decision approved_with_conditions \ 321 --notes "Approved, but keep it simple" \ 322 --conditions "Max 2 files,No new dependencies" 323 ``` 324 325 ### Reject Proposal 326 327 ```bash 328 npm run agent:approve -- \ 329 --task-id 42 \ 330 --reviewer "Jason" \ 331 --decision rejected \ 332 --notes "Scope too large, break into phases" 333 ``` 334 335 ### View Workflow Status 336 337 ```bash 338 # Show entire workflow tree 339 npm run agent:workflow:status -- --workflow-id 42 340 ``` 341 342 **Output:** 343 344 ``` 345 📋 Workflow Status: Task #42 346 347 ID Type Agent Status Created 348 ───────────────────────────────────────────────────────────────────────────── 349 42 design_proposal architect ✅ completed 2026-02-15 10:00:00 350 43 implementation_plan developer ⏳ awaiting_architect_approval 2026-02-15 11:00:00 351 44 technical_review architect 🔄 running 2026-02-15 11:30:00 352 ``` 353 354 ## Code Examples 355 356 ### Example 1: Feature with PO Approval 357 358 **User request:** "Add dark mode toggle to settings" 359 360 **Workflow execution:** 361 362 ```javascript 363 // 1. Create workflow (via CLI or Monitor agent) 364 const workflowId = createAgentTask({ 365 task_type: 'design_proposal', 366 assigned_to: 'architect', 367 priority: 7, 368 context: { 369 feature_description: 'Add dark mode toggle to settings', 370 requirements: ['Toggle in settings page', 'Persist to localStorage', 'Apply globally'], 371 significance: 'significant', 372 }, 373 }); 374 // workflowId = 42 375 376 // 2. Architect processes design_proposal 377 // - Analyzes codebase 378 // - Identifies files to modify: src/settings.js, src/theme.js 379 // - Estimates 6 hours 380 // - Requires migration: false 381 // - Breaking changes: none 382 // - Decision: Needs PO approval (effort > 4 hours) 383 await architect.requestPoApproval(42, { 384 title: 'Design: Dark mode toggle', 385 summary: 'Add dark mode toggle to settings', 386 approach: 'Use CSS variables and localStorage', 387 files_affected: ['src/settings.js', 'src/theme.js'], 388 estimated_effort: 6, 389 requires_migration: false, 390 breaking_changes: [], 391 }); 392 // Task 42 status: awaiting_po_approval 393 // human_review_queue: New item added 394 395 // 3. PO reviews and approves 396 $ npm run agent:approve -- --task-id 42 --reviewer "Jason" --decision approved 397 // Task 42 status: completed 398 // Task 43 created: implementation_plan (developer) 399 400 // 4. Developer creates implementation plan 401 // - Step 1: Update settings.js 402 // - Step 2: Update theme.js 403 // - Step 3: Write tests 404 // - Test coverage target: 85% 405 await developer.requestArchitectApproval(43, plan); 406 // Task 43 status: awaiting_architect_approval 407 // Task 44 created: technical_review (architect) 408 409 // 5. Architect reviews implementation plan 410 // - Checks file complexity: OK 411 // - Checks test coverage plan: 85% target ✓ 412 // - Approves 413 await architect.approveTask(43, 'architect', { 414 decision: 'approved', 415 notes: 'Implementation plan is sound', 416 }); 417 // Task 43 status: completed 418 // Task 44 status: completed 419 420 // 6. Developer implements 421 // Task 43 transitioned to pending 422 // Developer picks up task and implements 423 // Creates Task 45: verify_fix (QA) 424 425 // 7. QA tests 426 // QA verifies implementation, tests pass 427 // Workflow complete 428 ``` 429 430 ### Example 2: Bug Fix (No Approval) 431 432 **Monitor detects:** TypeError in scoring.js 433 434 **Workflow execution:** 435 436 ```javascript 437 // 1. Monitor creates classification task 438 const triageTaskId = createAgentTask({ 439 task_type: 'classify_error', 440 assigned_to: 'triage', 441 context: { 442 error_message: 'TypeError: Cannot read property score of null', 443 stack_trace: '...', 444 stage: 'scoring', 445 }, 446 }); 447 // triageTaskId = 47 448 449 // 2. Triage classifies 450 // - Error type: null_pointer 451 // - Severity: medium 452 // - Architectural: false (isolated bug) 453 // - Creates fix_bug task (no approval needed) 454 const fixTaskId = createAgentTask({ 455 task_type: 'fix_bug', 456 assigned_to: 'developer', 457 parent_task_id: 47, 458 context: { 459 error_type: 'null_pointer', 460 error_message: 'TypeError: Cannot read property score of null', 461 suggested_fix: 'Add null check with optional chaining', 462 }, 463 }); 464 // fixTaskId = 48 465 466 // 3. Developer fixes 467 // - Adds null check: score?.value 468 // - Runs tests 469 // - Creates verify_fix task 470 const qaTaskId = createAgentTask({ 471 task_type: 'verify_fix', 472 assigned_to: 'qa', 473 parent_task_id: 48, 474 context: { 475 original_error: 'TypeError: Cannot read property score of null', 476 files_changed: ['src/scoring.js'], 477 }, 478 }); 479 // qaTaskId = 49 480 481 // 4. QA verifies 482 // - Runs tests 483 // - Checks coverage 484 // - Completes task 485 // Workflow complete (no approvals needed) 486 ``` 487 488 ### Example 3: Architectural Bug Fix 489 490 **Triage detects:** Fundamental flaw in scoring algorithm 491 492 **Workflow execution:** 493 494 ```javascript 495 // 1. Triage classifies as architectural 496 const designTaskId = createAgentTask({ 497 task_type: 'design_proposal', 498 assigned_to: 'architect', 499 context: { 500 feature_description: 'Fix scoring algorithm architectural flaw', 501 requirements: ['Recalculate scores', 'Update schema'], 502 significance: 'significant', 503 workflow_type: 'bug_fix_architectural', 504 }, 505 }); 506 // designTaskId = 50 507 508 // 2. Architect creates design 509 // - Requires migration: true 510 // - Breaking changes: Score schema changes 511 // - Needs PO approval 512 await architect.requestPoApproval(50, proposal); 513 // Task 50: awaiting_po_approval 514 515 // 3. PO approves 516 $ npm run agent:approve -- --task-id 50 --reviewer "Jason" --decision approved 517 // Task 51 created: implementation_plan 518 519 // 4. Developer creates plan → Architect reviews → Developer implements → QA tests 520 // (Same flow as Feature Implementation) 521 ``` 522 523 ## Best Practices 524 525 ### For Architects 526 527 1. **Design Proposals:** 528 - Clearly document alternatives considered 529 - Provide realistic effort estimates 530 - Identify all affected files upfront 531 - Flag breaking changes early 532 533 2. **Technical Reviews:** 534 - Focus on architectural soundness, not style 535 - Check for over-engineering (factories, unnecessary abstractions) 536 - Verify test coverage plan is comprehensive 537 - Ensure documentation updates are planned 538 539 3. **Approval Decisions:** 540 - Use `approved_with_conditions` for minor concerns 541 - Use `rejected` only when fundamental issues exist 542 - Provide clear, actionable feedback 543 544 ### For Developers 545 546 1. **Implementation Plans:** 547 - Break down into concrete, testable steps 548 - Include specific test cases in test plan 549 - Plan for 85%+ coverage from the start 550 - Update documentation as a required step 551 552 2. **Workflow Validation:** 553 - Don't bypass workflow checks 554 - If validation fails, understand why 555 - Create missing prerequisite tasks 556 557 3. **Feedback Handling:** 558 - If plan rejected, create new plan (don't reuse failed task) 559 - Address all high-severity issues before resubmitting 560 561 ### For Product Owners 562 563 1. **Approval Reviews:** 564 - Review proposals promptly (within 24 hours) 565 - Focus on business alignment and scope appropriateness 566 - Use conditions to constrain scope, not to micromanage 567 568 2. **Rejection Criteria:** 569 - Scope too large → Reject with phased approach suggestion 570 - Misaligned with roadmap → Reject with explanation 571 - Insufficient detail → Request more information via conditions 572 573 ### For QA 574 575 1. **Verification:** 576 - Verify both functionality and test coverage 577 - Check that coverage meets 85%+ requirement 578 - Block tasks if coverage gate fails 579 580 ## Troubleshooting 581 582 ### Task stuck in awaiting_po_approval 583 584 **Symptoms:** 585 586 - Task status `awaiting_po_approval` for >24 hours 587 - No item in `human_review_queue` 588 589 **Solutions:** 590 591 ```sql 592 -- Check if review item exists 593 SELECT * FROM human_review_queue WHERE metadata LIKE '%"task_id":42%'; 594 595 -- Manually add review item if missing 596 INSERT INTO human_review_queue (file, reason, type, priority, metadata) 597 VALUES ( 598 'Task #42: Dark mode feature', 599 'Design proposal requires Product Owner approval', 600 'architecture', 601 'high', 602 '{"task_id":42,"type":"po_approval"}' 603 ); 604 ``` 605 606 ### Workflow validation failed 607 608 **Symptoms:** 609 610 - Task fails with "Features require design_proposal parent task" 611 - Task fails with "Design requires Product Owner approval before implementation" 612 613 **Solutions:** 614 615 ```bash 616 # Check parent task status 617 npm run agent:tasks -- --status completed | grep design_proposal 618 619 # Check approval metadata 620 sqlite3 db/sites.db "SELECT id, approval_json FROM agent_tasks WHERE id = 42;" 621 622 # If parent not approved, approve it 623 npm run agent:approve -- --task-id 42 --reviewer "System" --decision approved 624 ``` 625 626 ### Architect approval loop 627 628 **Symptoms:** 629 630 - Implementation plan repeatedly rejected 631 - Developer keeps revising same task 632 633 **Solutions:** 634 635 1. **Check rejection reasons:** 636 637 ```bash 638 npm run agent:logs -- --task-id 44 --level error 639 ``` 640 641 2. **Create new task for revision:** 642 ```javascript 643 // Don't reuse failed task - create new one with revisions 644 createAgentTask({ 645 task_type: 'implementation_plan', 646 assigned_to: 'developer', 647 parent_task_id: 42, 648 context: { 649 design_proposal: proposal, 650 previous_attempt: 43, // Reference to failed task 651 revisions: ['Reduced file count', 'Increased coverage target to 90%'], 652 }, 653 }); 654 ``` 655 656 ### Task shows as completed but workflow didn't continue 657 658 **Symptoms:** 659 660 - design_proposal marked completed 661 - No implementation_plan task created 662 663 **Solutions:** 664 665 ```bash 666 # Check if approval triggered next step 667 sqlite3 db/sites.db " 668 SELECT id, task_type, status, approval_json 669 FROM agent_tasks 670 WHERE parent_task_id = 42 671 ORDER BY created_at DESC; 672 " 673 674 # Manually create next task if missing 675 npm run agent:create -- \ 676 --agent developer \ 677 --task implementation_plan \ 678 --context '{"design_proposal":{...}}' \ 679 --priority 6 680 ``` 681 682 ## Integration with Existing Workflows 683 684 ### Bug Fix Workflow 685 686 **File:** `src/agents/workflows/bug-fix.js` 687 688 **Integration points:** 689 690 1. Triage classifies error severity and architectural impact 691 2. If architectural → Create `design_proposal` task (enters approval flow) 692 3. If simple → Create `fix_bug` task (bypasses approval) 693 694 **Decision criteria:** 695 696 ```javascript 697 const isArchitectural = 698 affectsMultipleModules || 699 requiresSchemaChanges || 700 changesCoreBusinessLogic || 701 impactsApiContracts; 702 703 if (isArchitectural) { 704 return createAgentTask({ 705 task_type: 'design_proposal', 706 assigned_to: 'architect', 707 context: { 708 workflow_type: 'bug_fix_architectural', 709 // ... 710 }, 711 }); 712 } else { 713 return createStandardBugFixWorkflow(errorMessage, stackTrace, stage); 714 } 715 ``` 716 717 ### Feature Workflow 718 719 **File:** `src/agents/workflows/feature.js` 720 721 **Integration points:** 722 723 1. All features start with `design_proposal` 724 2. Architect determines if PO approval needed 725 3. If significant → Enter approval flow 726 4. If minor → Auto-approve, skip to implementation 727 728 **Significance detection:** 729 730 ```javascript 731 const significant = 732 hasBreakingChanges || requiresMigration || estimatedEffort > 4 || explicitlyMarkedSignificant; 733 ``` 734 735 ### Refactor Workflow 736 737 **File:** `src/agents/workflows/refactor.js` 738 739 **Integration points:** 740 741 1. Large refactors (>2 files or >300 lines changed) → `design_proposal` 742 2. Small refactors → Direct to developer 743 3. All refactors → Architect review via `technical_review` 744 745 ## Metrics and Monitoring 746 747 ### Key Metrics 748 749 ```sql 750 -- Approval turnaround time 751 SELECT 752 AVG(JULIANDAY(completed_at) - JULIANDAY(created_at)) * 24 as avg_hours 753 FROM agent_tasks 754 WHERE status IN ('awaiting_po_approval', 'awaiting_architect_approval') 755 AND completed_at IS NOT NULL; 756 757 -- Approval rejection rate 758 SELECT 759 COUNT(CASE WHEN approval_json LIKE '%"decision":"rejected"%' THEN 1 END) * 100.0 / COUNT(*) as rejection_rate_pct 760 FROM agent_tasks 761 WHERE status IN ('failed', 'completed') 762 AND approval_json IS NOT NULL; 763 764 -- Tasks blocked on approval 765 SELECT COUNT(*) 766 FROM agent_tasks 767 WHERE status IN ('awaiting_po_approval', 'awaiting_architect_approval'); 768 ``` 769 770 ### Dashboard Integration 771 772 **View pending approvals:** 773 774 - Page: Human Review 775 - Section: Approval Queue 776 - Shows: Tasks awaiting approval with proposal summaries 777 - Actions: Approve, Reject, View details 778 779 **View workflow progress:** 780 781 - Page: Agent Dashboard 782 - Section: Workflow Trees 783 - Shows: Visual tree of parent-child task relationships 784 - Filters: By workflow type, date range, status