purpose: Catalog proven AI Developer Workflows for common tasks type: workflow-library domain: agentic-development workflows: [bug-fix, feature, refactor, test, documentation] prerequisites: [adw-fundamentals] last-updated: 2025-09-30 This document provides battle-tested ADW implementations for the most common development tasks. Each workflow includes complete specifications, success criteria, and real-world usage metrics. Use these as-is or adapt them to your specific context. # COMMON AI DEVELOPER WORKFLOWS ## WORKFLOW CATEGORIES ``` BUG FIXES: - simple-bug-fix: Single file, clear cause - integration-bug-fix: Multiple components - regression-fix: Broken after change - performance-bug-fix: Speed/memory issues FEATURE IMPLEMENTATION: - api-endpoint: New REST/GraphQL endpoint - ui-component: New frontend component - data-model: Database schema addition - integration: Third-party service REFACTORING: - extract-function: Break down complex code - rename-symbol: Consistent naming - optimize-performance: Speed improvements - reduce-complexity: Simplify logic TESTING: - unit-test-generation: Function-level tests - integration-test-generation: Component tests - e2e-test-generation: Full flow tests - test-coverage-boost: Increase coverage DOCUMENTATION: - api-documentation: Endpoint docs - readme-update: Project overview - inline-comments: Code explanations - changelog-generation: Release notes ``` ## BUG FIX WORKFLOWS ### 1. SIMPLE BUG FIX **Use When**: Single file bug with clear reproduction steps. ```yaml name: simple-bug-fix version: 1.3.0 category: bug-fix complexity: low avg-duration: 8 minutes success-rate: 0.92 trigger: - Issue labeled "bug" and "good-first-fix" - PR comment "/fix-bug" - Manual invocation inputs: bug-description: type: string required: true example: "Login button doesn't respond when Enter key pressed" affected-file: type: string required: false example: "src/components/LoginForm.tsx" phases: phase-1-discovery: agent: bugsy duration: 2-4 minutes prompt: | TASK: Identify root cause of bug DESCRIPTION: {{bug-description}} FILE: {{affected-file || "search for it"}} STEPS: 1. If file not specified, search codebase for likely location 2. Read the file and related files 3. Identify exact line(s) causing the bug 4. Determine root cause (logic error, missing check, etc) 5. Verify bug can be reproduced OUTPUT (JSON): { "root_cause": "specific description", "bug_location": "file:line", "related_files": ["file1", "file2"], "reproduction_steps": ["step1", "step2"], "proposed_fix": "minimal change description" } validation: - JSON schema valid - Bug location exists in codebase - Proposed fix is minimal (< 10 lines) - No breaking changes mentioned on-failure: escalate: "Cannot identify root cause" phase-2-implementation: agent: bugsy duration: 3-6 minutes prompt: | TASK: Implement bug fix FIX: {{proposed_fix}} LOCATION: {{bug_location}} REQUIREMENTS: 1. Make minimal code change 2. Add test case that fails without fix, passes with fix 3. Preserve existing behavior for non-bug cases 4. Add inline comment explaining fix 5. Update any related documentation OUTPUT: - Changed files - Test results validation: syntax: - Run linter on changed files - Check for syntax errors tests: - Execute full test suite - Verify new test exists - Verify new test passes - Verify no existing tests broken coverage: - Measure coverage delta - Ensure coverage not decreased security: - Run security scan - Check for new vulnerabilities self-heal: enabled: true max-attempts: 3 on-test-failure: - Analyze test output - Correct implementation - Re-run tests on-failure: escalate: "Cannot fix bug after 3 attempts" provide: - Attempted solutions - Test failures - Error messages phase-3-verification: agent: validation duration: 2-3 minutes prompt: | TASK: Verify bug fix completeness CHANGED: {{changed_files}} VERIFICATION: 1. Confirm bug no longer reproduces 2. Check no regressions in related functionality 3. Verify test coverage adequate 4. Review code quality (readability, style) 5. Generate human-readable summary OUTPUT (JSON): { "bug_fixed": true/false, "regressions": [], "coverage_adequate": true/false, "code_quality_issues": [], "summary": "plain English explanation" } validation: - All tests passing - Coverage >= baseline - No lint errors - No security issues checkpoint: semi-automatic on-threshold-exceeded: - Coverage drop > 2% - Performance regression > 10% - New security vulnerability on-success: action: request-approval message: "Bug fix ready for review: {{summary}}" outputs: changed-files: array test-results: object coverage-delta: float summary: string metrics: - execution-time - files-changed - lines-changed - tests-added - self-heal-attempts rollback: trigger: "Validation failure or human rejection" action: "Revert all changes" success-criteria: - Bug no longer reproduces - All tests pass - No regressions - Coverage maintained - Human approval received ``` ### 2. INTEGRATION BUG FIX **Use When**: Bug spans multiple components or services. ```yaml name: integration-bug-fix version: 1.1.0 category: bug-fix complexity: medium avg-duration: 20 minutes success-rate: 0.78 inputs: bug-description: string suspected-components: array phases: phase-1-discovery: agent: bugsy duration: 5-8 minutes prompt: | TASK: Trace integration bug across components BUG: {{bug-description}} COMPONENTS: {{suspected-components}} STEPS: 1. Identify data flow between components 2. Trace where data becomes incorrect 3. Find the component introducing the bug 4. Determine if it's: - Data transformation error - Missing validation - Incorrect contract assumption - Race condition 5. Map all affected components OUTPUT (JSON): { "bug_source": "component_name", "bug_type": "data|validation|contract|race", "data_flow": ["comp1->comp2->comp3"], "affected_components": ["comp1", "comp2"], "root_cause": "description", "fix_approach": "strategy" } validation: - Bug source identified - Bug type categorized - Data flow mapped - All affected components listed phase-2-implementation: agent: bugsy duration: 8-12 minutes prompt: | TASK: Fix integration bug SOURCE: {{bug_source}} TYPE: {{bug_type}} APPROACH: {{fix_approach}} REQUIREMENTS: 1. Fix the source component 2. Add validation in affected components if needed 3. Update integration tests 4. Verify data flow end-to-end 5. Document the contract (if relevant) PARALLEL SUBTASKS: - Fix source component - Update affected components - Add/update integration tests - Update API documentation validation: - Unit tests pass for each component - Integration tests pass - End-to-end data flow validated - No side effects detected self-heal: enabled: true max-attempts: 3 phase-3-verification: agent: validation duration: 5-7 minutes prompt: | TASK: Verify integration fix COMPONENTS: {{affected_components}} VERIFICATION: 1. Test each component independently 2. Test integration points 3. Run full end-to-end flow 4. Check for cascading failures 5. Verify performance not degraded validation: - All component tests pass - Integration tests pass - E2E tests pass - No performance regression success-criteria: - Bug source identified and fixed - All affected components validated - Integration tests pass - No cascading failures - Documentation updated ``` ## FEATURE IMPLEMENTATION WORKFLOWS ### 3. API ENDPOINT **Use When**: Adding new REST or GraphQL endpoint. ```yaml name: api-endpoint version: 2.0.0 category: feature complexity: medium avg-duration: 25 minutes success-rate: 0.81 inputs: endpoint-spec: type: object required: true schema: method: "GET|POST|PUT|DELETE" path: string description: string request-schema: object response-schema: object auth-required: boolean phases: phase-1-design: agent: jsmaster duration: 5-8 minutes prompt: | TASK: Design API endpoint SPEC: {{endpoint-spec}} STEPS: 1. Review existing API patterns in codebase 2. Design endpoint following conventions 3. Define request/response schemas 4. Identify required validations 5. Determine error cases and status codes 6. Plan authentication/authorization OUTPUT (JSON): { "route": "/api/v1/...", "handler": "handlerName", "validations": ["validation1", "validation2"], "error_cases": [ {"case": "invalid input", "status": 400}, {"case": "unauthorized", "status": 401} ], "dependencies": ["service1", "service2"] } validation: - Route follows REST conventions - All error cases have status codes - Validations comprehensive - Dependencies identified phase-2-implementation: agent: jsmaster duration: 10-15 minutes prompt: | TASK: Implement API endpoint DESIGN: {{design}} REQUIREMENTS: 1. Create route handler 2. Implement request validation 3. Add business logic 4. Handle all error cases 5. Add response formatting 6. Include logging 7. Add JSDoc comments PARALLEL SUBTASKS: - Write handler function - Write validation middleware - Write unit tests - Update API documentation validation: - Linter passes - Unit tests pass (100% coverage for handler) - Input validation comprehensive - Error handling complete - Logging present phase-3-integration: agent: jsmaster duration: 5-7 minutes prompt: | TASK: Integrate endpoint into API HANDLER: {{handler}} ROUTE: {{route}} REQUIREMENTS: 1. Register route in router 2. Add to API documentation 3. Create integration test 4. Update OpenAPI/Swagger spec 5. Add example in docs validation: - Route registered correctly - Integration test passes - Documentation updated - OpenAPI spec valid phase-4-verification: agent: validation duration: 5-8 minutes prompt: | TASK: Verify API endpoint ENDPOINT: {{route}} VERIFICATION: 1. Test happy path 2. Test all error cases 3. Test authentication/authorization 4. Verify request/response schemas 5. Check API documentation completeness 6. Test with various payloads validation: - All tests pass - Documentation complete - No security issues - Performance acceptable outputs: endpoint-route: string test-coverage: float documentation-url: string success-criteria: - Endpoint responds correctly - All error cases handled - Tests pass with >95% coverage - Documentation complete - Security validated - Human approval received ``` ### 4. UI COMPONENT **Use When**: Adding new React/Vue/etc component. ```yaml name: ui-component version: 1.5.0 category: feature complexity: medium avg-duration: 30 minutes success-rate: 0.76 inputs: component-spec: type: object required: true schema: name: string description: string props: object state: object behaviors: array phases: phase-1-design: agent: fronty duration: 6-9 minutes prompt: | TASK: Design UI component SPEC: {{component-spec}} STEPS: 1. Review existing component patterns 2. Design component structure 3. Define props interface 4. Plan state management 5. Identify reusable sub-components 6. Design accessibility features OUTPUT (JSON): { "component_name": "ComponentName", "props_interface": {...}, "state_shape": {...}, "sub_components": ["SubComp1"], "hooks_needed": ["useState", "useEffect"], "accessibility": ["aria-label", "keyboard-nav"] } validation: - Component name follows conventions - Props interface typed correctly - Accessibility considered - Reusable components identified phase-2-implementation: agent: fronty duration: 12-18 minutes prompt: | TASK: Implement UI component DESIGN: {{design}} REQUIREMENTS: 1. Create component file 2. Implement props interface 3. Add state management 4. Implement behaviors 5. Add accessibility features 6. Style the component 7. Add PropTypes/TypeScript types 8. Add JSDoc comments PARALLEL SUBTASKS: - Write component code - Write component tests - Write Storybook stories - Update component library docs validation: - Component renders without errors - All props work correctly - Accessibility audit passes - Tests pass - TypeScript/PropTypes valid phase-3-integration: agent: fronty duration: 5-7 minutes prompt: | TASK: Integrate component COMPONENT: {{component_name}} REQUIREMENTS: 1. Export from component library 2. Add to Storybook 3. Update component index 4. Create usage examples 5. Add to design system docs validation: - Component exports correctly - Storybook loads without errors - Examples render correctly - Documentation complete phase-4-verification: agent: validation duration: 6-8 minutes prompt: | TASK: Verify UI component COMPONENT: {{component_name}} VERIFICATION: 1. Visual regression test 2. Accessibility audit (WCAG 2.1 AA) 3. Test all prop combinations 4. Test keyboard navigation 5. Test screen reader compatibility 6. Cross-browser check 7. Performance audit validation: - All tests pass - Accessibility score > 90 - No visual regressions - Performance acceptable - Works in all target browsers outputs: component-path: string storybook-url: string test-coverage: float accessibility-score: float success-criteria: - Component renders correctly - All behaviors work - Tests pass with >90% coverage - Accessibility score > 90 - Documentation complete - Human approval received ``` ## REFACTORING WORKFLOWS ### 5. EXTRACT FUNCTION **Use When**: Complex function needs to be broken down. ```yaml name: extract-function version: 1.2.0 category: refactor complexity: low avg-duration: 12 minutes success-rate: 0.88 inputs: file-path: string function-name: string complexity-target: number (default: 10) phases: phase-1-analysis: agent: bugsy duration: 3-5 minutes prompt: | TASK: Analyze function for extraction FILE: {{file-path}} FUNCTION: {{function-name}} STEPS: 1. Measure current complexity 2. Identify logical sections 3. Find extraction candidates 4. Check dependencies between sections 5. Propose extraction plan OUTPUT (JSON): { "current_complexity": number, "extraction_candidates": [ { "name": "suggestedName", "lines": [start, end], "complexity": number, "dependencies": ["var1", "var2"] } ], "extraction_order": ["extract1", "extract2"], "expected_final_complexity": number } validation: - Complexity measured correctly - Extraction candidates valid - Expected complexity < target - No circular dependencies phase-2-extraction: agent: bugsy duration: 5-8 minutes prompt: | TASK: Extract functions PLAN: {{extraction_plan}} REQUIREMENTS: 1. Extract in specified order 2. Create well-named functions 3. Pass dependencies as parameters 4. Preserve exact behavior 5. Add JSDoc to extracted functions 6. Update tests if needed validation: - All tests still pass - Behavior preserved (output identical) - Complexity reduced - No dead code introduced phase-3-verification: agent: validation duration: 4-5 minutes prompt: | TASK: Verify refactoring ORIGINAL: {{original_function}} REFACTORED: {{refactored_functions}} VERIFICATION: 1. Run full test suite 2. Measure complexity of all functions 3. Check for code duplication 4. Verify readability improved 5. Ensure no performance regression validation: - All tests pass - Complexity target met - No code duplication - Performance maintained outputs: original-complexity: number final-complexity: number extracted-functions: array test-results: object success-criteria: - Complexity reduced below target - All tests pass - Behavior preserved - Readability improved ``` ## TESTING WORKFLOWS ### 6. UNIT TEST GENERATION **Use When**: Need to increase test coverage for a module. ```yaml name: unit-test-generation version: 1.4.0 category: test complexity: low avg-duration: 15 minutes success-rate: 0.85 inputs: file-path: string target-coverage: float (default: 0.90) phases: phase-1-analysis: agent: bugsy duration: 4-6 minutes prompt: | TASK: Analyze code for test generation FILE: {{file-path}} STEPS: 1. Identify all exported functions/methods 2. Analyze each function's logic paths 3. Identify edge cases 4. Check existing test coverage 5. Find untested code paths 6. Generate test plan OUTPUT (JSON): { "functions": [ { "name": "functionName", "current_coverage": 0.60, "untested_paths": ["path1", "path2"], "edge_cases": ["null input", "empty array"], "needed_tests": ["test1", "test2"] } ], "test_plan": [...], "estimated_coverage": 0.92 } validation: - All functions analyzed - Coverage measured correctly - Edge cases identified - Test plan comprehensive phase-2-generation: agent: bugsy duration: 7-10 minutes prompt: | TASK: Generate unit tests PLAN: {{test_plan}} REQUIREMENTS: 1. Follow existing test patterns 2. Test happy paths 3. Test edge cases 4. Test error cases 5. Use descriptive test names 6. Add comments for complex assertions 7. Mock external dependencies validation: - All tests run - All tests pass - Coverage target met - No flaky tests phase-3-verification: agent: validation duration: 4-5 minutes prompt: | TASK: Verify test quality TESTS: {{generated_tests}} VERIFICATION: 1. Run tests 10 times (check for flakiness) 2. Measure coverage 3. Check test naming 4. Verify edge cases covered 5. Check for over-mocking validation: - Tests pass consistently - Coverage >= target - Test names descriptive - Edge cases covered outputs: tests-added: number coverage-before: float coverage-after: float coverage-delta: float success-criteria: - Coverage >= target - All tests pass - No flaky tests - Test quality high ``` ## DOCUMENTATION WORKFLOWS ### 7. API DOCUMENTATION **Use When**: Need to document API endpoints. ```yaml name: api-documentation version: 1.3.0 category: documentation complexity: low avg-duration: 10 minutes success-rate: 0.91 inputs: api-file: string format: "openapi|markdown|jsdoc" phases: phase-1-extraction: agent: scribe duration: 3-5 minutes prompt: | TASK: Extract API information FILE: {{api-file}} STEPS: 1. Identify all endpoints 2. Extract route, method, handler 3. Identify request/response schemas 4. Find validation rules 5. Extract error cases 6. Find authentication requirements OUTPUT (JSON): { "endpoints": [ { "method": "POST", "path": "/api/users", "description": "Create new user", "request_schema": {...}, "response_schema": {...}, "auth_required": true, "error_cases": [...] } ] } validation: - All endpoints found - Schemas complete - Error cases documented phase-2-generation: agent: scribe duration: 5-7 minutes prompt: | TASK: Generate API documentation DATA: {{extracted_data}} FORMAT: {{format}} REQUIREMENTS: 1. Follow {{format}} specifications 2. Include request/response examples 3. Document all error codes 4. Add authentication info 5. Include rate limiting details 6. Add usage examples validation: - Format valid (passes linter) - All endpoints documented - Examples present - Error codes listed phase-3-verification: agent: validation duration: 2-3 minutes prompt: | TASK: Verify documentation completeness DOCS: {{generated_docs}} VERIFICATION: 1. Check all endpoints documented 2. Verify examples are runnable 3. Confirm error codes match code 4. Check authentication info correct 5. Validate schema accuracy validation: - Documentation complete - Examples valid - Schemas match code - No broken links outputs: documentation-path: string endpoints-documented: number examples-included: number success-criteria: - All endpoints documented - Examples runnable - Format valid - Human approval received ``` ## WORKFLOW COMPOSITION EXAMPLE ### FULL FEATURE WORKFLOW **Combining multiple workflows for complete feature delivery.** ```yaml name: full-feature-delivery version: 1.0.0 category: composition complexity: high avg-duration: 60-90 minutes inputs: feature-spec: object workflow-sequence: step-1-backend: workflow: api-endpoint inputs: endpoint-spec: "{{feature-spec.backend}}" step-2-frontend: workflow: ui-component depends-on: step-1-backend inputs: component-spec: "{{feature-spec.frontend}}" step-3-integration: workflow: integration-test-generation depends-on: [step-1-backend, step-2-frontend] inputs: components: ["backend", "frontend"] step-4-docs: parallel: - workflow: api-documentation inputs: api-file: "{{step-1-backend.outputs.handler-path}}" - workflow: readme-update inputs: feature-name: "{{feature-spec.name}}" step-5-verification: depends-on: [step-1-backend, step-2-frontend, step-3-integration, step-4-docs] agent: validation verify: - Backend tests pass - Frontend tests pass - Integration tests pass - Documentation complete - No security issues success-criteria: - All workflows complete successfully - All tests pass - Documentation complete - Human approval received ``` ## WORKFLOW METRICS SUMMARY ``` WORKFLOW TYPE | AVG TIME | SUCCESS RATE | COMPLEXITY -----------------------|-----------|--------------|------------ simple-bug-fix | 8 min | 92% | low integration-bug-fix | 20 min | 78% | medium api-endpoint | 25 min | 81% | medium ui-component | 30 min | 76% | medium extract-function | 12 min | 88% | low unit-test-generation | 15 min | 85% | low api-documentation | 10 min | 91% | low full-feature-delivery | 75 min | 68% | high ``` ## CONCLUSION These proven workflows provide starting points for common development tasks. Adapt them to your specific: - Tech stack - Code conventions - Quality requirements - Team preferences **Key Success Factors**: 1. Clear inputs and outputs 2. Comprehensive validation 3. Self-healing capabilities 4. Human approval at right points 5. Continuous metrics collection Select workflows relevant to your codebase Customize prompts and validation to your stack Measure and optimize based on 08-KPI-METRICS/ Build your custom workflow library