II.
Page JSON
Structured · livepage:docs-user-guide-tutorials-advanced-multi-phase
Advanced Tutorial: Multi-Phase Feature Development json
Inspect the normalized record payload exactly as the atlas UI reads it.
{
"id": "page:docs-user-guide-tutorials-advanced-multi-phase",
"_kind": "Page",
"_file": "wiki/docs/user-guide/tutorials/advanced-multi-phase.md",
"_cluster": "wiki",
"attributes": {
"nodeKind": "Page",
"sourcePath": "docs/user-guide/tutorials/advanced-multi-phase.md",
"sourceKind": "repo-docs",
"title": "Advanced Tutorial: Multi-Phase Feature Development",
"displayName": "Advanced Tutorial: Multi-Phase Feature Development",
"slug": "docs/user-guide/tutorials/advanced-multi-phase",
"articlePath": "wiki/docs/user-guide/tutorials/advanced-multi-phase.md",
"article": "\n# Advanced Tutorial: Multi-Phase Feature Development\n\n**Version:** 1.0\n**Date:** 2026-01-25\nLast refreshed: 2026-04-25\n**Category:** Tutorial\n**Level:** Advanced\n**Estimated Time:** 90-120 minutes\n**Primary Personas:** Marcus Thompson (Technical Lead), Sarah Chen (advanced usage)\n\n---\n\n## Learning Objectives\n\nBy the end of this tutorial, you will be able to:\n\n1. **Design multi-phase workflows** that follow Research-Plan-Implement-Test-Deploy patterns\n2. **Implement quality convergence loops** with agent-based scoring\n3. **Configure team collaboration patterns** with strategic breakpoints\n4. **Use parallel quality checks** to accelerate feedback cycles\n5. **Create governance-ready processes** with comprehensive audit trails\n6. **Handle complex iteration logic** with quality thresholds and early exits\n\n---\n\n## Prerequisites\n\nBefore starting this tutorial, you should have:\n\n- [ ] Completed **[Beginner Tutorial: Build a Simple REST API](./beginner-rest-api.md)**\n- [ ] Completed **[Intermediate Tutorial: Custom Process Definition](./intermediate-custom-process.md)**\n- [ ] Strong understanding of **async/await** and **Promise patterns**\n- [ ] Familiarity with **software development methodologies** (TDD, Agile)\n- [ ] Experience with **team collaboration tools** and workflows\n- [ ] A team project where you want to implement structured feature development\n\n### Verify Environment\n\n```bash\n# Verify Babysitter CLI\nbabysitter --version\n```\n\n### About Breakpoints\n\nThis tutorial involves team collaboration breakpoints. How they work depends on your mode:\n\n**Interactive Mode (Claude Code)**: Breakpoints are handled directly in the chat. Great for single-developer workflows.\n\n**Non-Interactive Mode (Team Collaboration)**: For team approval workflows, breakpoints are disabled.\n\nChoose the mode that fits your workflow. For learning, interactive mode (no setup) is easiest.\n\n---\n\n## What We're Building\n\nIn this tutorial, we will create a **comprehensive feature development workflow** suitable for team environments. This process implements the full software development lifecycle:\n\n### The Five Phases\n\n```\n┌─────────────────────────────────────────────────────────────────────────────┐\n│ MULTI-PHASE FEATURE DEVELOPMENT │\n├─────────────────────────────────────────────────────────────────────────────┤\n│ │\n│ PHASE 1: RESEARCH │\n│ ┌──────────────────────────────────────────────────────────────────────┐ │\n│ │ - Analyze codebase patterns │ │\n│ │ - Identify existing implementations │ │\n│ │ - Review dependencies and constraints │ │\n│ │ - Output: Research Report │ │\n│ └──────────────────────────────────────────────────────────────────────┘ │\n│ │ │\n│ ▼ │\n│ PHASE 2: PLANNING │ BREAKPOINT: Research Review │\n│ ┌──────────────────────────────────────────────────────────────────────┐ │\n│ │ - Generate technical specifications │ │\n│ │ - Define acceptance criteria │ │\n│ │ - Create implementation plan │ │\n│ │ - Output: Detailed Plan │ │\n│ └──────────────────────────────────────────────────────────────────────┘ │\n│ │ │\n│ ▼ │\n│ PHASE 3: IMPLEMENTATION │ BREAKPOINT: Plan Approval │\n│ ┌──────────────────────────────────────────────────────────────────────┐ │\n│ │ - Write tests first (TDD) │ │\n│ │ - Implement code to pass tests │ │\n│ │ - Run quality checks in parallel │ │\n│ │ - Agent scores quality │ │\n│ │ - ITERATE until quality target met │ │\n│ │ - Output: Working Code + Tests │ │\n│ └──────────────────────────────────────────────────────────────────────┘ │\n│ │ │\n│ ▼ │\n│ PHASE 4: VERIFICATION │ Quality Convergence Loop │\n│ ┌──────────────────────────────────────────────────────────────────────┐ │\n│ │ - Run comprehensive test suite │ │\n│ │ - Security vulnerability scan │ │\n│ │ - Performance benchmarks │ │\n│ │ - Documentation check │ │\n│ │ - Output: Verification Report │ │\n│ └──────────────────────────────────────────────────────────────────────┘ │\n│ │ │\n│ ▼ │\n│ PHASE 5: DEPLOYMENT │ BREAKPOINT: Final Approval │\n│ ┌──────────────────────────────────────────────────────────────────────┐ │\n│ │ - Create pull request │ │\n│ │ - Request code review │ │\n│ │ - Merge after approval │ │\n│ │ - Deploy to target environment │ │\n│ │ - Output: Deployed Feature │ │\n│ └──────────────────────────────────────────────────────────────────────┘ │\n│ │\n└─────────────────────────────────────────────────────────────────────────────┘\n```\n\n### Key Features\n\n1. **Quality Convergence**: The implementation phase iterates until a quality target is met\n2. **Agent-Based Scoring**: LLM evaluates code quality with detailed feedback\n3. **Team Breakpoints**: Strategic approval gates for collaboration\n4. **Parallel Quality Checks**: Coverage, lint, security, and tests run simultaneously\n5. **Comprehensive Audit Trail**: Every decision tracked for compliance\n\n---\n\n## Step 1: Understanding Quality Convergence\n\nBefore we dive into code, let's understand the core concept of **quality convergence**.\n\n### What is Quality Convergence?\n\nQuality convergence is an iterative process where:\n\n1. **Implementation** produces code\n2. **Quality checks** measure various metrics\n3. **Agent scoring** evaluates overall quality\n4. **If below threshold**: iterate with feedback to improve\n5. **If at/above threshold**: proceed to next phase\n\n```\n┌───────────────────────────────────────────────────────────────────┐\n│ QUALITY CONVERGENCE LOOP │\n├───────────────────────────────────────────────────────────────────┤\n│ │\n│ ┌─────────────┐ │\n│ │ START │ │\n│ └──────┬──────┘ │\n│ │ │\n│ ▼ │\n│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │\n│ │ Implement │────▶│ Quality │────▶│ Agent │ │\n│ │ Code │ │ Checks │ │ Scoring │ │\n│ └─────────────┘ └─────────────┘ └──────┬──────┘ │\n│ ▲ │ │\n│ │ ▼ │\n│ │ ┌───────────────┐ │\n│ │ │ Score >= 85? │ │\n│ │ └───────┬───────┘ │\n│ │ │ │ │\n│ │ NO │ │ YES │\n│ │ │ │ │\n│ │ ▼ ▼ │\n│ │ ┌─────────┐ ┌─────────┐ │\n│ └───────────────────────────│ Iterate │ │ EXIT │ │\n│ feedback: issues, │ with │ │(success)│ │\n│ recommendations │ feedback│ └─────────┘ │\n│ └─────────┘ │\n│ │\n└───────────────────────────────────────────────────────────────────┘\n```\n\n### Quality Scoring Dimensions\n\nThe agent evaluates code across multiple dimensions:\n\n| Dimension | Weight | What It Measures |\n|-----------|--------|------------------|\n| **Correctness** | 30% | Tests pass, requirements met |\n| **Coverage** | 20% | Code coverage percentage |\n| **Code Quality** | 20% | Lint errors, complexity, style |\n| **Security** | 15% | Vulnerability scan results |\n| **Documentation** | 15% | Comments, README, API docs |\n\n**Checkpoint 1:** You understand how quality convergence and agent scoring work.\n\n---\n\n## Step 2: Set Up the Project Structure\n\nCreate the project structure for our multi-phase workflow:\n\n```bash\n# Create project directory\nmkdir multi-phase-tutorial\ncd multi-phase-tutorial\n\n# Initialize project\nnpm init -y\n\n# Create directory structure\nmkdir -p .a5c/processes\nmkdir -p .a5c/templates\nmkdir -p src\nmkdir -p tests\nmkdir -p docs\n\n# Install development dependencies\nnpm install --save-dev jest eslint prettier\n```\n\nUpdate `package.json`:\n\n```json\n{\n \"name\": \"multi-phase-tutorial\",\n \"version\": \"1.0.0\",\n \"type\": \"module\",\n \"scripts\": {\n \"test\": \"jest --coverage\",\n \"lint\": \"eslint src/\",\n \"format\": \"prettier --check src/\",\n \"security\": \"npm audit --audit-level=moderate\"\n }\n}\n```\n\n---\n\n## Step 3: Define the Task Definitions\n\nCreate comprehensive task definitions for each phase:\n\n```bash\ntouch .a5c/processes/tasks.js\n```\n\n```javascript\n// .a5c/processes/tasks.js\n// Task definitions for multi-phase feature development\n\n// ============================================\n// RESEARCH PHASE TASKS\n// ============================================\n\n/**\n * Research Task: Codebase Analysis\n * Uses an agent to analyze the existing codebase\n */\nexport const codebaseAnalysisTask = {\n type: 'agent',\n name: 'codebase-analysis',\n description: 'Analyze existing codebase patterns and structures',\n prompt: `\n Analyze the codebase for the following feature request:\n {{featureDescription}}\n\n Examine:\n 1. Existing code patterns and architecture\n 2. Similar implementations that can be referenced\n 3. Dependencies and their versions\n 4. Potential integration points\n 5. Code conventions and style guides\n\n Provide a structured analysis report with:\n - existingPatterns: Array of identified patterns\n - relevantFiles: Array of files to reference\n - dependencies: Object of relevant dependencies\n - constraints: Array of technical constraints\n - recommendations: Array of implementation recommendations\n `,\n timeout: 120000,\n};\n\n/**\n * Research Task: Requirements Analysis\n * Extracts and clarifies requirements\n */\nexport const requirementsAnalysisTask = {\n type: 'agent',\n name: 'requirements-analysis',\n description: 'Analyze and clarify feature requirements',\n prompt: `\n Analyze the following feature request and extract clear requirements:\n {{featureDescription}}\n\n For each requirement, provide:\n - id: Unique identifier (REQ-001, REQ-002, etc.)\n - description: Clear description\n - type: functional | non-functional | constraint\n - priority: must-have | should-have | nice-to-have\n - acceptanceCriteria: Array of testable criteria\n\n Return a JSON object with:\n - requirements: Array of requirement objects\n - assumptions: Array of assumptions made\n - clarifications: Array of questions for stakeholders\n `,\n timeout: 60000,\n};\n\n// ============================================\n// PLANNING PHASE TASKS\n// ============================================\n\n/**\n * Planning Task: Technical Specification\n * Generates detailed technical specifications\n */\nexport const technicalSpecTask = {\n type: 'agent',\n name: 'technical-specification',\n description: 'Generate technical specifications from requirements',\n prompt: `\n Based on the research and requirements:\n\n Research: {{researchReport}}\n Requirements: {{requirements}}\n\n Generate a technical specification including:\n 1. Architecture Overview\n - Components and their responsibilities\n - Data flow diagrams (text representation)\n - API contracts\n\n 2. Implementation Details\n - File structure changes\n - New modules/classes to create\n - Modifications to existing code\n\n 3. Data Models\n - New entities or modifications\n - Validation rules\n - Relationships\n\n 4. API Design (if applicable)\n - Endpoints\n - Request/Response formats\n - Error handling\n\n 5. Testing Strategy\n - Unit tests needed\n - Integration tests needed\n - Edge cases to cover\n\n Return as structured JSON.\n `,\n timeout: 180000,\n};\n\n/**\n * Planning Task: Implementation Plan\n * Creates step-by-step implementation plan\n */\nexport const implementationPlanTask = {\n type: 'agent',\n name: 'implementation-plan',\n description: 'Create detailed implementation plan',\n prompt: `\n Based on the technical specification:\n {{technicalSpec}}\n\n Create a detailed implementation plan with:\n\n 1. Implementation Steps (ordered)\n For each step:\n - stepNumber: Number\n - description: What to implement\n - files: Files to create/modify\n - dependencies: Previous steps required\n - estimatedComplexity: low | medium | high\n - testCriteria: How to verify completion\n\n 2. Risk Assessment\n - technicalRisks: Array of potential technical issues\n - mitigations: Mitigation strategies\n\n 3. Milestones\n - Key checkpoints for progress tracking\n\n Return as structured JSON.\n `,\n timeout: 120000,\n};\n\n// ============================================\n// IMPLEMENTATION PHASE TASKS\n// ============================================\n\n/**\n * Implementation Task: Write Tests\n * Writes tests based on specifications\n */\nexport const writeTestsTask = {\n type: 'agent',\n name: 'write-tests',\n description: 'Write test cases before implementation',\n prompt: `\n Based on the implementation plan and current iteration context:\n\n Plan: {{implementationPlan}}\n Iteration: {{iteration}}\n Previous Issues: {{previousIssues}}\n\n Write comprehensive test cases that:\n 1. Cover all acceptance criteria\n 2. Include edge cases\n 3. Test error handling\n 4. Are structured for the project's test framework (Jest)\n\n For iteration {{iteration}}, focus on:\n {{iterationFocus}}\n\n Return the test code with clear descriptions.\n `,\n timeout: 180000,\n};\n\n/**\n * Implementation Task: Implement Code\n * Implements code to pass the tests\n */\nexport const implementCodeTask = {\n type: 'agent',\n name: 'implement-code',\n description: 'Implement code to pass tests',\n prompt: `\n Based on the tests and implementation plan:\n\n Tests: {{tests}}\n Plan: {{implementationPlan}}\n Iteration: {{iteration}}\n Previous Issues: {{previousIssues}}\n\n Implement code that:\n 1. Passes all tests\n 2. Follows project conventions\n 3. Is well-documented\n 4. Handles errors appropriately\n\n For iteration {{iteration}}, address these specific issues:\n {{issuesToAddress}}\n\n Return the implementation code with inline comments.\n `,\n timeout: 300000,\n};\n\n// ============================================\n// QUALITY CHECK TASKS\n// ============================================\n\n/**\n * Quality Task: Run Tests\n * Executes test suite and captures results\n */\nexport const runTestsTask = {\n type: 'shell',\n name: 'run-tests',\n description: 'Run test suite with coverage',\n command: 'npm test -- --coverage --json --outputFile=coverage/test-results.json',\n timeout: 300000,\n retries: 0,\n};\n\n/**\n * Quality Task: Lint Check\n * Runs linting on the codebase\n */\nexport const lintCheckTask = {\n type: 'shell',\n name: 'lint-check',\n description: 'Run ESLint on source code',\n command: 'npm run lint -- --format json --output-file lint-results.json || true',\n timeout: 60000,\n retries: 0,\n};\n\n/**\n * Quality Task: Security Scan\n * Runs security vulnerability scan\n */\nexport const securityScanTask = {\n type: 'shell',\n name: 'security-scan',\n description: 'Run security vulnerability scan',\n command: 'npm run security -- --json > security-results.json 2>&1 || true',\n timeout: 120000,\n retries: 0,\n};\n\n/**\n * Quality Task: Documentation Check\n * Verifies documentation completeness\n */\nexport const documentationCheckTask = {\n type: 'agent',\n name: 'documentation-check',\n description: 'Verify documentation completeness',\n prompt: `\n Analyze the following code for documentation completeness:\n\n {{code}}\n\n Check for:\n 1. Function/method documentation (JSDoc or similar)\n 2. Module-level documentation\n 3. README updates if needed\n 4. API documentation if applicable\n 5. Inline comments for complex logic\n\n Return:\n - score: 0-100 documentation score\n - missingDocs: Array of items needing documentation\n - suggestions: Array of improvement suggestions\n `,\n timeout: 60000,\n};\n\n// ============================================\n// AGENT SCORING TASK\n// ============================================\n\n/**\n * Agent Scoring Task\n * Evaluates overall quality and provides detailed feedback\n */\nexport const agentScoringTask = {\n type: 'agent',\n name: 'quality-scoring',\n description: 'AI-powered quality assessment with detailed feedback',\n prompt: `\n Evaluate the quality of this implementation based on:\n\n Test Results: {{testResults}}\n Coverage: {{coverage}}\n Lint Results: {{lintResults}}\n Security Scan: {{securityResults}}\n Documentation Score: {{documentationScore}}\n\n Requirements: {{requirements}}\n Acceptance Criteria: {{acceptanceCriteria}}\n\n Score each dimension (0-100):\n 1. Correctness (30% weight): Do tests pass? Are requirements met?\n 2. Coverage (20% weight): Is code coverage adequate?\n 3. Code Quality (20% weight): Lint errors, complexity, style?\n 4. Security (15% weight): Any vulnerabilities?\n 5. Documentation (15% weight): Is code well-documented?\n\n Calculate weighted overall score.\n\n If score < target, provide:\n - issues: Array of specific issues to fix\n - recommendations: Array of improvement recommendations\n - prioritizedFixes: Array of fixes ordered by impact\n\n Return JSON:\n {\n \"scores\": {\n \"correctness\": number,\n \"coverage\": number,\n \"codeQuality\": number,\n \"security\": number,\n \"documentation\": number\n },\n \"overallScore\": number,\n \"issues\": string[],\n \"recommendations\": string[],\n \"prioritizedFixes\": string[],\n \"readyForNextPhase\": boolean\n }\n `,\n timeout: 120000,\n};\n\n// ============================================\n// VERIFICATION PHASE TASKS\n// ============================================\n\n/**\n * Verification Task: Integration Tests\n * Runs integration test suite\n */\nexport const integrationTestsTask = {\n type: 'shell',\n name: 'integration-tests',\n description: 'Run integration tests',\n command: 'npm run test:integration || echo \"No integration tests configured\"',\n timeout: 600000,\n retries: 1,\n};\n\n/**\n * Verification Task: Performance Benchmark\n * Runs performance benchmarks\n */\nexport const performanceBenchmarkTask = {\n type: 'shell',\n name: 'performance-benchmark',\n description: 'Run performance benchmarks',\n command: 'npm run benchmark || echo \"No benchmarks configured\"',\n timeout: 300000,\n retries: 0,\n};\n\n// ============================================\n// DEPLOYMENT PHASE TASKS\n// ============================================\n\n/**\n * Deployment Task: Create Pull Request\n * Creates a pull request with changes\n */\nexport const createPullRequestTask = {\n type: 'shell',\n name: 'create-pull-request',\n description: 'Create pull request for changes',\n command: `\n git checkout -b feature/{{branchName}} &&\n git add -A &&\n git commit -m \"{{commitMessage}}\" &&\n git push -u origin feature/{{branchName}} &&\n gh pr create --title \"{{prTitle}}\" --body \"{{prBody}}\"\n `,\n timeout: 120000,\n retries: 0,\n};\n\n/**\n * Deployment Task: Deploy to Environment\n * Deploys to specified environment\n */\nexport const deployTask = {\n type: 'shell',\n name: 'deploy',\n description: 'Deploy to target environment',\n command: 'echo \"Deploying to {{environment}}...\" && sleep 2 && echo \"Deployment complete\"',\n timeout: 300000,\n retries: 1,\n};\n```\n\n**Checkpoint 2:** All task definitions are in place.\n\n---\n\n## Step 4: Create the Multi-Phase Process Definition\n\nNow let's create the main process that orchestrates all phases:\n\n```bash\ntouch .a5c/processes/multi-phase-feature.js\n```\n\n```javascript\n// .a5c/processes/multi-phase-feature.js\n// Multi-Phase Feature Development Process with Quality Convergence\n\nimport {\n // Research tasks\n codebaseAnalysisTask,\n requirementsAnalysisTask,\n // Planning tasks\n technicalSpecTask,\n implementationPlanTask,\n // Implementation tasks\n writeTestsTask,\n implementCodeTask,\n // Quality tasks\n runTestsTask,\n lintCheckTask,\n securityScanTask,\n documentationCheckTask,\n agentScoringTask,\n // Verification tasks\n integrationTestsTask,\n performanceBenchmarkTask,\n // Deployment tasks\n createPullRequestTask,\n deployTask,\n} from './tasks.js';\n\n/**\n * Multi-Phase Feature Development Process\n *\n * Implements a complete feature development lifecycle with:\n * - Research and planning phases\n * - TDD implementation with quality convergence\n * - Verification and deployment phases\n * - Team collaboration breakpoints\n *\n * @param {Object} inputs - Process inputs\n * @param {string} inputs.featureDescription - Description of the feature to build\n * @param {number} inputs.qualityTarget - Target quality score (default: 85)\n * @param {number} inputs.maxIterations - Maximum implementation iterations (default: 5)\n * @param {string} inputs.targetEnvironment - Deployment target (default: 'staging')\n * @param {boolean} inputs.requireTeamApproval - Require team approval at breakpoints\n * @param {Object} ctx - Babysitter context object\n */\nexport async function process(inputs, ctx) {\n const {\n featureDescription,\n qualityTarget = 85,\n maxIterations = 5,\n targetEnvironment = 'staging',\n requireTeamApproval = true,\n } = inputs;\n\n ctx.log('============================================');\n ctx.log('MULTI-PHASE FEATURE DEVELOPMENT');\n ctx.log('============================================');\n ctx.log(`Feature: ${featureDescription}`);\n ctx.log(`Quality Target: ${qualityTarget}/100`);\n ctx.log(`Max Iterations: ${maxIterations}`);\n ctx.log(`Target Environment: ${targetEnvironment}`);\n ctx.log('============================================');\n\n // ============================================\n // PHASE 1: RESEARCH\n // ============================================\n ctx.log('');\n ctx.log('PHASE 1: RESEARCH');\n ctx.log('------------------');\n\n ctx.log('Analyzing codebase patterns...');\n const codebaseAnalysis = await ctx.task(codebaseAnalysisTask, {\n featureDescription,\n });\n\n ctx.log('Analyzing requirements...');\n const requirementsAnalysis = await ctx.task(requirementsAnalysisTask, {\n featureDescription,\n });\n\n // Store research results\n const researchReport = {\n codebaseAnalysis,\n requirements: requirementsAnalysis,\n timestamp: new Date().toISOString(),\n };\n ctx.setState('researchReport', researchReport);\n\n ctx.log('Research phase complete');\n ctx.log(` - Identified ${codebaseAnalysis.existingPatterns?.length || 0} existing patterns`);\n ctx.log(` - Extracted ${requirementsAnalysis.requirements?.length || 0} requirements`);\n\n // Team Review Breakpoint: Research Results\n if (requireTeamApproval) {\n await ctx.breakpoint({\n question: 'Review research findings and requirements before proceeding to planning?',\n title: 'PHASE 1 COMPLETE: Research Review',\n context: {\n phase: 'research',\n researchReport,\n nextPhase: 'planning',\n reviewItems: [\n 'Codebase analysis accuracy',\n 'Requirements completeness',\n 'Identified constraints',\n 'Any clarifications needed',\n ],\n },\n approvers: ['tech-lead', 'product-owner'],\n timeout: 86400000, // 24 hours\n });\n ctx.log('Research review approved');\n }\n\n // ============================================\n // PHASE 2: PLANNING\n // ============================================\n ctx.log('');\n ctx.log('PHASE 2: PLANNING');\n ctx.log('------------------');\n\n ctx.log('Generating technical specification...');\n const technicalSpec = await ctx.task(technicalSpecTask, {\n researchReport: JSON.stringify(researchReport),\n requirements: JSON.stringify(requirementsAnalysis.requirements),\n });\n\n ctx.log('Creating implementation plan...');\n const implementationPlan = await ctx.task(implementationPlanTask, {\n technicalSpec: JSON.stringify(technicalSpec),\n });\n\n // Store planning results\n const planningResults = {\n technicalSpec,\n implementationPlan,\n timestamp: new Date().toISOString(),\n };\n ctx.setState('planningResults', planningResults);\n\n ctx.log('Planning phase complete');\n ctx.log(` - ${implementationPlan.steps?.length || 0} implementation steps defined`);\n ctx.log(` - ${implementationPlan.milestones?.length || 0} milestones identified`);\n\n // Team Review Breakpoint: Plan Approval\n if (requireTeamApproval) {\n await ctx.breakpoint({\n question: 'Review and approve the technical specification and implementation plan?',\n title: 'PHASE 2 COMPLETE: Plan Approval',\n context: {\n phase: 'planning',\n technicalSpec,\n implementationPlan,\n nextPhase: 'implementation',\n criticalDecisions: [\n 'Architecture approach',\n 'API design',\n 'Testing strategy',\n 'Risk mitigations',\n ],\n },\n approvers: ['tech-lead', 'architect'],\n severity: 'high',\n timeout: 86400000, // 24 hours\n });\n ctx.log('Plan approved');\n }\n\n // ============================================\n // PHASE 3: IMPLEMENTATION (Quality Convergence Loop)\n // ============================================\n ctx.log('');\n ctx.log('PHASE 3: IMPLEMENTATION');\n ctx.log('------------------------');\n ctx.log(`Starting TDD implementation with quality convergence...`);\n ctx.log(`Target: ${qualityTarget}/100 | Max iterations: ${maxIterations}`);\n\n let iteration = 0;\n let currentScore = 0;\n let previousIssues = [];\n let implementationComplete = false;\n\n while (iteration < maxIterations && !implementationComplete) {\n iteration++;\n ctx.log('');\n ctx.log(`--- ITERATION ${iteration}/${maxIterations} ---`);\n\n // Determine iteration focus based on previous issues\n const iterationFocus = iteration === 1\n ? 'Initial implementation of core functionality'\n : `Addressing issues: ${previousIssues.slice(0, 3).join(', ')}`;\n\n ctx.log(`Focus: ${iterationFocus}`);\n\n // Step 3.1: Write Tests (TDD)\n ctx.log('Writing tests...');\n const tests = await ctx.task(writeTestsTask, {\n implementationPlan: JSON.stringify(implementationPlan),\n iteration,\n previousIssues: JSON.stringify(previousIssues),\n iterationFocus,\n });\n\n // Step 3.2: Implement Code\n ctx.log('Implementing code...');\n const implementation = await ctx.task(implementCodeTask, {\n tests: JSON.stringify(tests),\n implementationPlan: JSON.stringify(implementationPlan),\n iteration,\n previousIssues: JSON.stringify(previousIssues),\n issuesToAddress: previousIssues.slice(0, 5).join('\\n'),\n });\n\n // Step 3.3: Run Quality Checks in Parallel\n ctx.log('Running quality checks in parallel...');\n\n const [testResults, lintResults, securityResults, docResults] = await ctx.parallel.all([\n () => ctx.task(runTestsTask, {}),\n () => ctx.task(lintCheckTask, {}),\n () => ctx.task(securityScanTask, {}),\n () => ctx.task(documentationCheckTask, { code: JSON.stringify(implementation) }),\n ]);\n\n ctx.log('Quality checks complete:');\n ctx.log(` - Tests: ${testResults.exitCode === 0 ? 'PASS' : 'FAIL'}`);\n ctx.log(` - Lint: ${lintResults.exitCode === 0 ? 'PASS' : 'WARNINGS'}`);\n ctx.log(` - Security: ${securityResults.exitCode === 0 ? 'PASS' : 'REVIEW'}`);\n ctx.log(` - Documentation: ${docResults.score || 'N/A'}/100`);\n\n // Step 3.4: Agent Quality Scoring\n ctx.log('Performing agent quality assessment...');\n\n const qualityAssessment = await ctx.task(agentScoringTask, {\n testResults: JSON.stringify(testResults),\n coverage: testResults.coverage || '0%',\n lintResults: JSON.stringify(lintResults),\n securityResults: JSON.stringify(securityResults),\n documentationScore: docResults.score || 0,\n requirements: JSON.stringify(requirementsAnalysis.requirements),\n acceptanceCriteria: JSON.stringify(\n requirementsAnalysis.requirements?.flatMap(r => r.acceptanceCriteria) || []\n ),\n });\n\n currentScore = qualityAssessment.overallScore || 0;\n previousIssues = qualityAssessment.issues || [];\n\n ctx.log('');\n ctx.log(`QUALITY ASSESSMENT - Iteration ${iteration}:`);\n ctx.log(` Overall Score: ${currentScore}/100 (target: ${qualityTarget})`);\n ctx.log(` Scores by dimension:`);\n ctx.log(` - Correctness: ${qualityAssessment.scores?.correctness || 0}/100`);\n ctx.log(` - Coverage: ${qualityAssessment.scores?.coverage || 0}/100`);\n ctx.log(` - Code Quality: ${qualityAssessment.scores?.codeQuality || 0}/100`);\n ctx.log(` - Security: ${qualityAssessment.scores?.security || 0}/100`);\n ctx.log(` - Documentation: ${qualityAssessment.scores?.documentation || 0}/100`);\n\n if (previousIssues.length > 0) {\n ctx.log(` Issues to address (${previousIssues.length}):`);\n previousIssues.slice(0, 5).forEach((issue, i) => {\n ctx.log(` ${i + 1}. ${issue}`);\n });\n }\n\n // Check if quality target is met\n if (currentScore >= qualityTarget) {\n ctx.log('');\n ctx.log(`QUALITY TARGET MET! Score: ${currentScore}/${qualityTarget}`);\n implementationComplete = true;\n } else if (iteration < maxIterations) {\n ctx.log('');\n ctx.log(`Score ${currentScore} < target ${qualityTarget}. Continuing to iteration ${iteration + 1}...`);\n } else {\n ctx.log('');\n ctx.log(`Max iterations reached. Final score: ${currentScore}`);\n }\n\n // Store iteration results\n ctx.setState(`iteration_${iteration}`, {\n score: currentScore,\n issues: previousIssues,\n assessment: qualityAssessment,\n });\n }\n\n // Implementation Summary\n const implementationSummary = {\n finalScore: currentScore,\n iterationsUsed: iteration,\n targetMet: currentScore >= qualityTarget,\n remainingIssues: previousIssues,\n };\n ctx.setState('implementationSummary', implementationSummary);\n\n ctx.log('');\n ctx.log('Implementation phase complete');\n ctx.log(` - Final Score: ${currentScore}/100`);\n ctx.log(` - Iterations Used: ${iteration}/${maxIterations}`);\n ctx.log(` - Target Met: ${currentScore >= qualityTarget ? 'YES' : 'NO'}`);\n\n // Handle case where quality target not met\n if (!implementationComplete) {\n await ctx.breakpoint({\n question: `Quality target not met (${currentScore}/${qualityTarget}). Continue to verification phase anyway?`,\n title: 'QUALITY TARGET NOT MET',\n context: {\n finalScore: currentScore,\n qualityTarget,\n iterationsUsed: iteration,\n remainingIssues: previousIssues,\n recommendation: 'Consider increasing max iterations or lowering quality target',\n },\n severity: 'warning',\n });\n ctx.log('Proceeding to verification despite quality target not being met');\n }\n\n // ============================================\n // PHASE 4: VERIFICATION\n // ============================================\n ctx.log('');\n ctx.log('PHASE 4: VERIFICATION');\n ctx.log('----------------------');\n\n ctx.log('Running comprehensive verification...');\n\n // Run verification tasks in parallel\n const [integrationResults, performanceResults] = await ctx.parallel.all([\n () => ctx.task(integrationTestsTask, {}),\n () => ctx.task(performanceBenchmarkTask, {}),\n ]);\n\n const verificationResults = {\n integrationTests: integrationResults.exitCode === 0 ? 'PASS' : 'FAIL',\n performanceBenchmarks: performanceResults.exitCode === 0 ? 'PASS' : 'REVIEW',\n qualityScore: currentScore,\n timestamp: new Date().toISOString(),\n };\n ctx.setState('verificationResults', verificationResults);\n\n ctx.log('Verification phase complete');\n ctx.log(` - Integration Tests: ${verificationResults.integrationTests}`);\n ctx.log(` - Performance: ${verificationResults.performanceBenchmarks}`);\n\n // Team Review Breakpoint: Final Approval\n if (requireTeamApproval) {\n await ctx.breakpoint({\n question: `Approve feature for deployment to ${targetEnvironment}?`,\n title: 'PHASE 4 COMPLETE: Final Approval',\n context: {\n phase: 'verification',\n featureDescription,\n qualityScore: currentScore,\n verificationResults,\n implementationSummary,\n targetEnvironment,\n criticalChecks: [\n 'All tests passing',\n 'Quality score acceptable',\n 'No critical security issues',\n 'Documentation complete',\n ],\n },\n approvers: ['tech-lead', 'qa-lead'],\n severity: 'critical',\n timeout: 86400000, // 24 hours\n });\n ctx.log('Final approval received');\n }\n\n // ============================================\n // PHASE 5: DEPLOYMENT\n // ============================================\n ctx.log('');\n ctx.log('PHASE 5: DEPLOYMENT');\n ctx.log('--------------------');\n\n // Generate branch name and commit message\n const branchName = `feature-${Date.now()}`;\n const commitMessage = `feat: ${featureDescription.slice(0, 50)}`;\n const prTitle = `Feature: ${featureDescription.slice(0, 100)}`;\n const prBody = `\n## Summary\n${featureDescription}\n\n## Quality Metrics\n- Quality Score: ${currentScore}/100\n- Iterations: ${iteration}/${maxIterations}\n- Tests: PASS\n- Security: REVIEWED\n\n## Verification\n- Integration Tests: ${verificationResults.integrationTests}\n- Performance: ${verificationResults.performanceBenchmarks}\n\n---\nGenerated by Babysitter Multi-Phase Feature Development Process\n`;\n\n ctx.log('Creating pull request...');\n const prResult = await ctx.task(createPullRequestTask, {\n branchName,\n commitMessage,\n prTitle,\n prBody,\n });\n\n if (prResult.exitCode === 0) {\n ctx.log('Pull request created successfully');\n } else {\n ctx.log('Pull request creation failed (may require manual intervention)');\n }\n\n ctx.log(`Deploying to ${targetEnvironment}...`);\n const deployResult = await ctx.task(deployTask, {\n environment: targetEnvironment,\n });\n\n ctx.log('Deployment phase complete');\n\n // ============================================\n // COMPLETE: Return Final Summary\n // ============================================\n ctx.log('');\n ctx.log('============================================');\n ctx.log('FEATURE DEVELOPMENT COMPLETE');\n ctx.log('============================================');\n\n const finalSummary = {\n success: true,\n feature: featureDescription,\n phases: {\n research: 'COMPLETE',\n planning: 'COMPLETE',\n implementation: {\n status: 'COMPLETE',\n finalScore: currentScore,\n iterations: iteration,\n targetMet: currentScore >= qualityTarget,\n },\n verification: 'COMPLETE',\n deployment: deployResult.exitCode === 0 ? 'COMPLETE' : 'PARTIAL',\n },\n metrics: {\n qualityScore: currentScore,\n qualityTarget,\n iterationsUsed: iteration,\n maxIterations,\n },\n artifacts: {\n researchReport: true,\n technicalSpec: true,\n implementationPlan: true,\n tests: true,\n implementation: true,\n pullRequest: prResult.exitCode === 0,\n },\n completedAt: new Date().toISOString(),\n };\n\n return finalSummary;\n}\n```\n\n**Checkpoint 3:** The complete multi-phase process definition is ready.\n\n---\n\n## Step 5: Register the Process\n\nCreate the process manifest:\n\n```bash\ntouch .a5c/processes/manifest.json\n```\n\n```json\n{\n \"processes\": [\n {\n \"name\": \"multi-phase-feature\",\n \"description\": \"Complete feature development lifecycle with research, planning, TDD implementation, verification, and deployment\",\n \"file\": \"./multi-phase-feature.js\",\n \"inputs\": {\n \"featureDescription\": {\n \"type\": \"string\",\n \"required\": true,\n \"description\": \"Description of the feature to build\"\n },\n \"qualityTarget\": {\n \"type\": \"number\",\n \"default\": 85,\n \"description\": \"Target quality score (0-100)\"\n },\n \"maxIterations\": {\n \"type\": \"number\",\n \"default\": 5,\n \"description\": \"Maximum implementation iterations\"\n },\n \"targetEnvironment\": {\n \"type\": \"string\",\n \"default\": \"staging\",\n \"enum\": [\"development\", \"staging\", \"production\"],\n \"description\": \"Target deployment environment\"\n },\n \"requireTeamApproval\": {\n \"type\": \"boolean\",\n \"default\": true,\n \"description\": \"Require team approval at phase transitions\"\n }\n }\n }\n ]\n}\n```\n\n---\n\n## Step 6: Run the Multi-Phase Process\n\nStart Claude Code and run the process:\n\n```bash\nclaude\n```\n\n```\n/babysitter:call run multi-phase-feature with featureDescription=\"Add user authentication with JWT tokens, including login, logout, and token refresh endpoints\" qualityTarget=85 maxIterations=5 targetEnvironment=staging\n```\n\nOr in natural language:\n\n```\nUse the babysitter skill to run the multi-phase-feature process.\nBuild user authentication with JWT tokens - login, logout, and token refresh.\nTarget 85% quality with max 5 iterations, deploy to staging.\n```\n\n**What you should see:**\n\n```\n============================================\nMULTI-PHASE FEATURE DEVELOPMENT\n============================================\nFeature: Add user authentication with JWT tokens...\nQuality Target: 85/100\nMax Iterations: 5\nTarget Environment: staging\n============================================\n\nPHASE 1: RESEARCH\n------------------\nAnalyzing codebase patterns...\nAnalyzing requirements...\nResearch phase complete\n - Identified 3 existing patterns\n - Extracted 8 requirements\n\nWaiting for breakpoint approval...\nBreakpoint: PHASE 1 COMPLETE: Research Review\nVisit http://localhost:3184 to approve or reject.\n```\n\n---\n\n## Step 7: Navigate the Breakpoints\n\nAs you progress through the process, you will encounter several breakpoints:\n\n### Breakpoint 1: Research Review\n\n**What to review:**\n- Are the identified patterns relevant?\n- Are all requirements captured?\n- Any clarifications needed?\n\n### Breakpoint 2: Plan Approval\n\n**What to review:**\n- Is the architecture approach sound?\n- Are all edge cases considered?\n- Is the testing strategy comprehensive?\n\n### Breakpoint 3: Quality Target Warning (if applicable)\n\n**What to decide:**\n- Accept lower quality score?\n- Request more iterations?\n- Stop and investigate issues?\n\n### Breakpoint 4: Final Approval\n\n**What to verify:**\n- All critical checks passed?\n- Ready for target environment?\n- Stakeholder sign-off obtained?\n\n**Checkpoint 4:** You understand how to navigate team collaboration breakpoints.\n\n---\n\n## Step 8: Monitor Quality Convergence\n\nWatch the implementation phase carefully. You will see the quality score improve across iterations:\n\n```\n--- ITERATION 1/5 ---\nFocus: Initial implementation of core functionality\nWriting tests...\nImplementing code...\nRunning quality checks in parallel...\n\nQUALITY ASSESSMENT - Iteration 1:\n Overall Score: 62/100 (target: 85)\n Scores by dimension:\n - Correctness: 75/100\n - Coverage: 45/100\n - Code Quality: 70/100\n - Security: 60/100\n - Documentation: 40/100\n Issues to address (5):\n 1. Test coverage below 80%\n 2. Missing error handling for invalid tokens\n 3. No rate limiting on auth endpoints\n 4. JSDoc comments missing on public functions\n 5. Password requirements not validated\n\nScore 62 < target 85. Continuing to iteration 2...\n\n--- ITERATION 2/5 ---\nFocus: Addressing issues: Test coverage below 80%, Missing error handling...\n...\n\nQUALITY ASSESSMENT - Iteration 2:\n Overall Score: 78/100 (target: 85)\n Issues to address (3):\n 1. Rate limiting still missing\n 2. Token refresh edge case not tested\n 3. README needs updating\n\nScore 78 < target 85. Continuing to iteration 3...\n\n--- ITERATION 3/5 ---\n...\n\nQUALITY ASSESSMENT - Iteration 3:\n Overall Score: 89/100 (target: 85)\n\nQUALITY TARGET MET! Score: 89/85\n```\n\n---\n\n## Step 9: Review the Audit Trail\n\nAfter the process completes, examine the comprehensive audit trail:\n\n```bash\n# View the journal\ncat .a5c/runs/<runId>/journal/journal.jsonl | jq -s '.'\n```\n\n**Key events to look for:**\n\n```json\n[\n {\"type\": \"RUN_STARTED\", \"inputs\": {...}},\n {\"type\": \"TASK_COMPLETED\", \"taskId\": \"codebase-analysis-001\"},\n {\"type\": \"TASK_COMPLETED\", \"taskId\": \"requirements-analysis-001\"},\n {\"type\": \"BREAKPOINT_REQUESTED\", \"title\": \"Research Review\"},\n {\"type\": \"BREAKPOINT_APPROVED\", \"approver\": \"tech-lead\"},\n {\"type\": \"TASK_COMPLETED\", \"taskId\": \"technical-spec-001\"},\n {\"type\": \"TASK_COMPLETED\", \"taskId\": \"implementation-plan-001\"},\n {\"type\": \"BREAKPOINT_APPROVED\", \"title\": \"Plan Approval\"},\n {\"type\": \"ITERATION_STARTED\", \"iteration\": 1},\n {\"type\": \"QUALITY_SCORE\", \"iteration\": 1, \"score\": 62},\n {\"type\": \"ITERATION_STARTED\", \"iteration\": 2},\n {\"type\": \"QUALITY_SCORE\", \"iteration\": 2, \"score\": 78},\n {\"type\": \"ITERATION_STARTED\", \"iteration\": 3},\n {\"type\": \"QUALITY_SCORE\", \"iteration\": 3, \"score\": 89},\n {\"type\": \"BREAKPOINT_APPROVED\", \"title\": \"Final Approval\"},\n {\"type\": \"TASK_COMPLETED\", \"taskId\": \"deploy-001\"},\n {\"type\": \"RUN_COMPLETED\", \"status\": \"success\"}\n]\n```\n\nThis journal provides:\n- **Complete traceability** of all decisions\n- **Quality progression** across iterations\n- **Approval records** for compliance\n- **Timing information** for performance analysis\n\n---\n\n## Step 10: Customize for Your Team\n\nHere are patterns to customize the process for your team's needs:\n\n### Adding Custom Quality Dimensions\n\n```javascript\n// Add a custom security scoring component\nconst customSecurityTask = {\n type: 'agent',\n name: 'custom-security-score',\n prompt: `\n Evaluate security based on our company's security checklist:\n {{companySecurityChecklist}}\n\n Score each item and provide overall security score.\n `,\n};\n```\n\n### Configuring Approver Roles\n\n```javascript\nawait ctx.breakpoint({\n title: 'Production Deployment',\n approvers: ['tech-lead', 'security-officer', 'product-owner'],\n requiredApprovals: 2, // Need at least 2 approvals\n timeout: 172800000, // 48 hours\n});\n```\n\n### Adding Slack/Teams Notifications\n\n```javascript\n// Add a notification task\nconst notifyTeamTask = {\n type: 'shell',\n command: `curl -X POST $SLACK_WEBHOOK -d '{\"text\": \"Feature ready for review: {{featureName}}\"}'`,\n};\n\n// Use in process\nawait ctx.task(notifyTeamTask, { featureName: featureDescription });\n```\n\n---\n\n## Summary\n\nCongratulations! You have completed the advanced tutorial on multi-phase feature development. Let's review what you accomplished:\n\n### What You Built\n\n- A **complete feature development workflow** with 5 phases\n- **Quality convergence loop** with agent-based scoring\n- **Team collaboration** with strategic breakpoints\n- **Parallel quality checks** for fast feedback\n- **Comprehensive audit trail** for compliance\n\n### Key Concepts Mastered\n\n| Concept | What You Learned |\n|---------|------------------|\n| **Multi-Phase Workflows** | Orchestrating complex development lifecycles |\n| **Quality Convergence** | Iterating until quality targets are met |\n| **Agent Scoring** | Using LLMs to evaluate code quality |\n| **Parallel Quality Checks** | Running independent checks simultaneously |\n| **Team Breakpoints** | Strategic approval gates for collaboration |\n| **Audit Trails** | Tracking all decisions for compliance |\n\n### Quality Convergence Best Practices\n\n1. **Set realistic targets** - Start with 80%, increase as team matures\n2. **Limit iterations** - 5-10 iterations prevents infinite loops\n3. **Prioritize fixes** - Agent should suggest highest-impact fixes first\n4. **Track trends** - Monitor score progression across iterations\n5. **Allow overrides** - Breakpoints let humans override when needed\n\n### Team Collaboration Best Practices\n\n1. **Strategic breakpoints** - At irreversible decisions (deployments, API changes)\n2. **Clear context** - Provide all information needed to make decisions\n3. **Role-based approvals** - Different roles for different decisions\n4. **Timeout policies** - Don't let workflows block indefinitely\n5. **Escalation paths** - Define what happens if approval times out\n\n---\n\n## Next Steps\n\nYou have completed the advanced tutorials. Here are paths to continue your expertise:\n\n### Apply Your Knowledge\n- **Implement in your team** - Customize for your team's workflow\n- **Create team templates** - Share processes across projects\n- **Build governance policies** - Define approval requirements\n\n### Go Deeper\n- **[Process Engine Architecture](../features/process-definitions.md)** - Understand internals\n- **[Configuration Reference](../reference/configuration.md)** - Meet regulatory requirements\n- **[FAQ](../reference/faq.md)** - Common questions and answers\n\n### Contribute\n- **Share your processes** - Contribute to the community\n- **Report issues** - Help improve Babysitter\n- **Write tutorials** - Help others learn\n\n---\n\n## Troubleshooting\n\n### Issue: \"Quality score not improving between iterations\"\n\n**Symptom:** Score stays the same or decreases.\n\n**Solution:**\n1. Check if agent feedback is being incorporated\n2. Verify `previousIssues` is being passed correctly\n3. Review agent scoring prompt for clarity\n4. Consider adjusting scoring weights\n\n### Issue: \"Process stuck at breakpoint\"\n\n**Symptom:** Workflow waiting indefinitely.\n\n**Solution (Interactive Mode - Claude Code):**\n1. Look for Claude's question in the chat - scroll up if needed\n2. If the session disconnected, resume with `/babysitter:call resume`\n3. Ensure you respond to the question to continue\n\n### Issue: \"Parallel tasks failing intermittently\"\n\n**Symptom:** Random failures in parallel tasks.\n\n**Solution:**\n1. Check for shared resource conflicts\n2. Add retry logic to flaky tasks\n3. Consider running problematic tasks sequentially\n4. Review system resource limits\n\n### Issue: \"Agent scoring inconsistent\"\n\n**Symptom:** Quality scores vary significantly for similar code.\n\n**Solution:**\n1. Make scoring prompts more specific\n2. Add concrete examples in prompt\n3. Use structured output format\n4. Consider caching previous assessments for comparison\n\n---\n\n## See Also\n\n- [Event Sourcing Explained](../features/journal-system.md) - Architecture concepts\n- [Quality Convergence Explained](../features/quality-convergence.md) - Deep dive\n- [FAQ](../reference/faq.md) - Common questions and rollout strategies\n\n---\n\n**Document Status:** Complete\n**Last Updated:** 2026-01-25\n**Feedback:** Found an issue? [Report it on GitHub](https://github.com/a5c-ai/babysitter/issues)\n",
"documents": []
},
"outgoingEdges": [],
"incomingEdges": [
{
"from": "page:docs-user-guide-tutorials",
"to": "page:docs-user-guide-tutorials-advanced-multi-phase",
"kind": "contains_page"
}
]
}