claude-flow 1.0.30 โ†’ 1.0.31

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -23,8 +23,9 @@
23
23
 
24
24
  - **๐Ÿš€ 10x Faster Development**: Parallel AI agent execution with intelligent task distribution
25
25
  - **๐Ÿง  Persistent Memory**: Agents learn and share knowledge across sessions
26
+ - **โšก SPARC Methodology**: Systematic development with Specification โ†’ Pseudocode โ†’ Architecture โ†’ Refinement โ†’ Completion
26
27
  - **๐Ÿ”„ Zero Configuration**: Works out-of-the-box with sensible defaults
27
- - **โšก VSCode Native**: Seamless integration with your favorite IDE
28
+ - **๐Ÿค– VSCode Native**: Seamless integration with your favorite IDE
28
29
  - **๐Ÿ”’ Enterprise Ready**: Production-grade security, monitoring, and scaling
29
30
  - **๐ŸŒ MCP Compatible**: Full Model Context Protocol support for tool integration
30
31
 
@@ -32,9 +33,14 @@
32
33
 
33
34
  ```bash
34
35
  # ๐Ÿš€ Get started in 30 seconds
35
- npx claude-flow init
36
+ npx claude-flow init --sparc
36
37
  npx claude-flow start
37
38
 
39
+ # โšก SPARC Development Workflow
40
+ npx claude-flow sparc modes # List development modes
41
+ npx claude-flow sparc tdd "user auth" # Run TDD workflow
42
+ npx claude-flow sparc run architect "design API" # Architecture mode
43
+
38
44
  # ๐Ÿค– Spawn a research team
39
45
  npx claude-flow agent spawn researcher --name "Senior Researcher"
40
46
  npx claude-flow agent spawn analyst --name "Data Analyst"
@@ -67,8 +73,8 @@ Advanced CRDT-based memory system with SQLite performance and Markdown readabili
67
73
  </td>
68
74
  <td width="33%" align="center">
69
75
 
70
- ### โšก **Enhanced Claude Integration**
71
- Spawn Claude instances with comprehensive Claude-Flow guidance, teaching them to use memory, coordination, and system commands effectively.
76
+ ### โšก **SPARC Development**
77
+ Systematic AI-assisted development using Specification โ†’ Pseudocode โ†’ Architecture โ†’ Refinement โ†’ Completion methodology with 16+ specialized modes.
72
78
 
73
79
  </td>
74
80
  </tr>
@@ -145,12 +151,14 @@ Comprehensive documentation is available to help you get the most out of Claude-
145
151
 
146
152
  ### 1. **Initialize Claude Code Integration**
147
153
  ```bash
148
- npx claude-flow init
154
+ npx claude-flow init --sparc
149
155
  ```
150
156
  This creates:
151
- - `CLAUDE.md` - Claude Code configuration
157
+ - `CLAUDE.md` - SPARC-enhanced Claude Code configuration
152
158
  - `memory-bank.md` - Memory system documentation
153
159
  - `coordination.md` - Agent coordination documentation
160
+ - `.roomodes` - SPARC development mode configurations
161
+ - `.roo/` - SPARC templates and workflows
154
162
  - Memory folder structure with placeholders
155
163
 
156
164
  ### 2. **Start the Orchestrator**
@@ -237,6 +245,50 @@ npx claude-flow monitor
237
245
  npx claude-flow mcp tools
238
246
  ```
239
247
 
248
+ ## ๐Ÿš€ **SPARC Development Methodology**
249
+
250
+ Claude-Flow integrates the **SPARC** (Specification, Pseudocode, Architecture, Refinement, Completion) methodology for systematic AI-assisted development:
251
+
252
+ ### **Available SPARC Modes**
253
+ ```bash
254
+ # List all development modes
255
+ npx claude-flow sparc modes
256
+
257
+ # Key modes include:
258
+ # ๐Ÿ—๏ธ architect - System design and architecture
259
+ # ๐Ÿง  code - Clean, modular implementation
260
+ # ๐Ÿงช tdd - Test-driven development
261
+ # ๐Ÿ›ก๏ธ security-review - Security analysis
262
+ # ๐Ÿ“š docs-writer - Documentation creation
263
+ # ๐Ÿ”— integration - System integration
264
+ ```
265
+
266
+ ### **SPARC Workflow**
267
+ ```bash
268
+ # 1. Specification - Define requirements
269
+ npx claude-flow sparc run spec-pseudocode "user authentication system"
270
+
271
+ # 2. Architecture - Design system structure
272
+ npx claude-flow sparc run architect "auth service architecture"
273
+
274
+ # 3. Refinement - TDD implementation
275
+ npx claude-flow sparc tdd "implement JWT authentication"
276
+
277
+ # 4. Integration - Connect components
278
+ npx claude-flow sparc run integration "auth with user management"
279
+
280
+ # 5. Completion - Documentation and validation
281
+ npx claude-flow sparc run docs-writer "authentication API docs"
282
+ ```
283
+
284
+ ### **SPARC Features**
285
+ - **16+ Specialized AI Modes** for different development phases
286
+ - **Memory Persistence** across SPARC sessions with namespaced storage
287
+ - **TDD Enforcement** with Red-Green-Refactor cycle automation
288
+ - **Modular Design** with <500 line file constraints
289
+ - **Environment Safety** preventing credential exposure
290
+ - **Quality Gates** with automated code analysis and security review
291
+
240
292
  ## Architecture
241
293
 
242
294
  Claude-Flow uses a modular architecture with the following components:
@@ -396,6 +448,18 @@ npx claude-flow monitor [options]
396
448
  -f, --focus <component> Focus on specific component
397
449
  ```
398
450
 
451
+ #### `sparc` - SPARC Development Methodology ๐Ÿ†•
452
+ ```bash
453
+ npx claude-flow sparc <subcommand>
454
+ modes [--verbose] List available SPARC development modes
455
+ info <mode> Show detailed mode information
456
+ run <mode> "<task>" Execute specific SPARC mode
457
+ tdd "<feature>" Run full TDD workflow
458
+ --namespace <ns> Use custom memory namespace
459
+ --dry-run Show configuration without executing
460
+ --verbose Show detailed output
461
+ ```
462
+
399
463
  #### `claude` - Spawn Claude Instances with Enhanced Guidance ๐Ÿ†•
400
464
  ```bash
401
465
  npx claude-flow claude <subcommand>
@@ -493,6 +557,27 @@ npx claude-flow agent spawn coordinator --name "Tech Lead"
493
557
  npx claude-flow workflow development-pipeline.json --watch
494
558
  ```
495
559
 
560
+ **SPARC Development Workflow:**
561
+ ```bash
562
+ # Initialize SPARC environment
563
+ npx claude-flow init --sparc
564
+
565
+ # Complete feature development using SPARC methodology
566
+ npx claude-flow sparc run spec-pseudocode "user authentication system"
567
+ npx claude-flow sparc run architect "JWT auth service design"
568
+ npx claude-flow sparc tdd "implement secure authentication"
569
+ npx claude-flow sparc run security-review "auth vulnerability scan"
570
+ npx claude-flow sparc run integration "connect auth to user service"
571
+
572
+ # TDD-focused development
573
+ npx claude-flow sparc tdd "payment processing system"
574
+ npx claude-flow sparc tdd "real-time notifications"
575
+
576
+ # Architecture and design
577
+ npx claude-flow sparc run architect "microservices architecture"
578
+ npx claude-flow sparc run docs-writer "API documentation"
579
+ ```
580
+
496
581
  **Enhanced Claude Spawn Examples:**
497
582
  ```bash
498
583
  # Backend API development with high test coverage
@@ -627,7 +712,7 @@ Claude-Flow seamlessly integrates with Claude Code through the `CLAUDE.md` file
627
712
  - **Build Command Integration**: All build/test commands are available to Claude
628
713
  - **Memory Persistence**: Claude remembers context across sessions
629
714
  - **Enhanced Guidance**: Spawned Claude instances receive detailed Claude-Flow instructions
630
- - **SPARC Methodology**: Built-in support for structured AI development
715
+ - **SPARC Methodology**: Built-in support for systematic development with 16+ specialized AI modes
631
716
 
632
717
  Use with Claude Code:
633
718
  ```bash
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "claude-flow",
3
- "version": "1.0.30",
3
+ "version": "1.0.31",
4
4
  "description": "Advanced AI agent orchestration system for Claude Code",
5
5
  "main": "src/cli/main.ts",
6
6
  "bin": {
@@ -13,7 +13,7 @@ import {
13
13
  } from './command-registry.js';
14
14
  import { parseFlags } from './utils.js';
15
15
 
16
- const VERSION = '1.0.30';
16
+ const VERSION = '1.0.31';
17
17
 
18
18
  function printHelp() {
19
19
  console.log(`
@@ -25,7 +25,7 @@ USAGE:
25
25
  KEY COMMANDS:
26
26
  init [--sparc] Initialize project with Claude integration
27
27
  agent spawn <type> [--name <name>] Create AI agent (researcher, coder, analyst)
28
- sparc <subcommand> SPARC-based TDD development
28
+ sparc <subcommand> SPARC-based development modes
29
29
  memory <subcommand> Manage persistent memory
30
30
  start Start orchestration system
31
31
  status Show system status
@@ -0,0 +1,53 @@
1
+ // architect.js - Architect mode orchestration template
2
+ export function getArchitectOrchestration(taskDescription, memoryNamespace) {
3
+ return `
4
+ ## Task Orchestration Steps
5
+
6
+ 1. **Requirements Analysis** (10 mins)
7
+ - Analyze the user's request: "${taskDescription}"
8
+ - Query existing project context: \`npx claude-flow memory query ${memoryNamespace}\`
9
+ - Identify core components, services, and modular boundaries
10
+ - List external dependencies and integration points
11
+ - Document scalability and security requirements
12
+ - Store findings: \`npx claude-flow memory store ${memoryNamespace}_requirements "Core components: X, Y, Z. External deps: API-A, Service-B. Security: OAuth2, RLS policies needed."\`
13
+
14
+ 2. **System Architecture Design** (20 mins)
15
+ - Create modular architecture diagram using Mermaid syntax
16
+ - Define clear service boundaries and responsibilities
17
+ - Design API contracts between components
18
+ - Plan data flow and state management patterns
19
+ - Ensure NO hardcoded secrets or env values in design
20
+ - Create extensible integration points
21
+ - Store architecture: \`npx claude-flow memory store ${memoryNamespace}_architecture "Microservices: auth-service, user-service, data-processor. APIs: REST for external, gRPC for internal. State: Event-sourced with CQRS."\`
22
+
23
+ 3. **Technical Specifications** (15 mins)
24
+ - Define detailed interface contracts (OpenAPI/AsyncAPI)
25
+ - Specify data models and database schemas
26
+ - Plan security boundaries and authentication flows
27
+ - Document performance and scaling considerations
28
+ - Define configuration management strategy
29
+ - Store specs: \`npx claude-flow memory store ${memoryNamespace}_tech_specs "Auth: JWT with refresh tokens. DB: PostgreSQL with read replicas. Cache: Redis. Config: Environment-based with secrets manager."\`
30
+
31
+ 4. **Modular Implementation Plan** (10 mins)
32
+ - Break system into modules < 500 lines each
33
+ - Create development phases with clear milestones
34
+ - Define testing strategy (unit, integration, e2e)
35
+ - Plan deployment and rollback procedures
36
+ - Identify tasks for other SPARC modes
37
+ - Store plan: \`npx claude-flow memory store ${memoryNamespace}_implementation_plan "Phase 1: Core auth (tdd mode). Phase 2: User management (code mode). Phase 3: Integration (integration mode)."\`
38
+
39
+ 5. **Deliverables**
40
+ - architecture/
41
+ - system-overview.md (with Mermaid diagrams)
42
+ - api-specifications.md (OpenAPI/AsyncAPI specs)
43
+ - data-models.md (schemas with relationships)
44
+ - security-architecture.md (auth flows, boundaries)
45
+ - deployment-architecture.md (infrastructure design)
46
+ - implementation-plan.md (phased approach with SPARC mode assignments)
47
+
48
+ ## Next Steps
49
+ After completing architecture, delegate to appropriate modes:
50
+ - \`npx claude-flow sparc run spec-pseudocode "Create detailed pseudocode for ${taskDescription}" --non-interactive\`
51
+ - \`npx claude-flow sparc run tdd "Implement core authentication module" --non-interactive\`
52
+ - \`npx claude-flow sparc run security-review "Review architecture for vulnerabilities" --non-interactive\``;
53
+ }
@@ -0,0 +1,126 @@
1
+ // ask.js - Ask mode orchestration template
2
+ export function getAskOrchestration(taskDescription, memoryNamespace) {
3
+ return `
4
+ ## โ“ Ask Mode - SPARC Navigation Guide
5
+
6
+ I'll help you navigate the SPARC methodology and determine the best approach for: "${taskDescription}"
7
+
8
+ ## Understanding Your Request
9
+
10
+ Let me analyze your needs and guide you to the right SPARC mode:
11
+
12
+ ### 1. **Project Phase Analysis** (5 mins)
13
+ - What stage is your project in?
14
+ - What type of help do you need?
15
+ - What's your end goal?
16
+
17
+ ### 2. **SPARC Mode Recommendations**
18
+
19
+ Based on your request, here are the relevant SPARC modes:
20
+
21
+ #### ๐Ÿ“‹ Planning & Design Modes:
22
+ - **\`spec-pseudocode\`** - For creating detailed specifications, requirements, and high-level logic
23
+ - Use when: Starting a new feature, defining requirements, planning algorithms
24
+ - Example: \`npx claude-flow sparc run spec-pseudocode "Create user authentication flow" --non-interactive\`
25
+
26
+ - **\`architect\`** - For system design, API boundaries, and service architecture
27
+ - Use when: Designing system structure, defining APIs, planning microservices
28
+ - Example: \`npx claude-flow sparc run architect "Design e-commerce platform architecture" --non-interactive\`
29
+
30
+ #### ๐Ÿง  Implementation Modes:
31
+ - **\`code\`** - For implementing features with clean architecture
32
+ - Use when: Building new features, writing production code
33
+ - Example: \`npx claude-flow sparc run code "Implement payment processing service" --non-interactive\`
34
+
35
+ - **\`tdd\`** - For test-first development with comprehensive coverage
36
+ - Use when: Want high quality code, need test coverage, following TDD practices
37
+ - Example: \`npx claude-flow sparc run tdd "Build shopping cart with TDD" --non-interactive\`
38
+
39
+ #### ๐Ÿ”ง Quality & Maintenance Modes:
40
+ - **\`debug\`** - For troubleshooting issues and fixing bugs
41
+ - Use when: Something's broken, need to trace errors, fix runtime issues
42
+ - Example: \`npx claude-flow sparc run debug "Fix memory leak in data processor" --non-interactive\`
43
+
44
+ - **\`security-review\`** - For security audits and vulnerability checks
45
+ - Use when: Need security audit, checking for exposed secrets, compliance review
46
+ - Example: \`npx claude-flow sparc run security-review "Audit user data handling" --non-interactive\`
47
+
48
+ - **\`refinement-optimization-mode\`** - For performance optimization and refactoring
49
+ - Use when: Code needs optimization, files too large, performance issues
50
+ - Example: \`npx claude-flow sparc run refinement-optimization-mode "Optimize database queries" --non-interactive\`
51
+
52
+ #### ๐Ÿ“š Documentation & Integration:
53
+ - **\`docs-writer\`** - For creating documentation and guides
54
+ - Use when: Need README, API docs, user guides
55
+ - Example: \`npx claude-flow sparc run docs-writer "Create API documentation" --non-interactive\`
56
+
57
+ - **\`integration\`** - For connecting services and ensuring system cohesion
58
+ - Use when: Integrating components, connecting APIs, system integration
59
+ - Example: \`npx claude-flow sparc run integration "Connect auth service to user service" --non-interactive\`
60
+
61
+ #### ๐Ÿš€ Deployment & Operations:
62
+ - **\`devops\`** - For deployment, CI/CD, and infrastructure
63
+ - Use when: Setting up deployment, configuring CI/CD, provisioning infrastructure
64
+ - Example: \`npx claude-flow sparc run devops "Deploy to AWS with auto-scaling" --non-interactive\`
65
+
66
+ - **\`post-deployment-monitoring-mode\`** - For production monitoring
67
+ - Use when: Setting up monitoring, configuring alerts, tracking metrics
68
+ - Example: \`npx claude-flow sparc run post-deployment-monitoring-mode "Setup DataDog monitoring" --non-interactive\`
69
+
70
+ #### ๐Ÿ” Specialized Modes:
71
+ - **\`supabase-admin\`** - For Supabase database and auth management
72
+ - Use when: Working with Supabase, setting up database, configuring auth
73
+ - Example: \`npx claude-flow sparc run supabase-admin "Setup user authentication database" --non-interactive\`
74
+
75
+ - **\`mcp\`** - For MCP (Model Context Protocol) integrations
76
+ - Use when: Integrating external tools via MCP, API connections
77
+ - Example: \`npx claude-flow sparc run mcp "Integrate Stripe payment API" --non-interactive\`
78
+
79
+ ### 3. **Workflow Recommendations**
80
+
81
+ For "${taskDescription}", I recommend this workflow:
82
+
83
+ \`\`\`bash
84
+ # Step 1: Define requirements
85
+ npx claude-flow sparc run spec-pseudocode "${taskDescription} - requirements and pseudocode" --non-interactive
86
+
87
+ # Step 2: Design architecture (if needed)
88
+ npx claude-flow sparc run architect "${taskDescription} - system design" --non-interactive
89
+
90
+ # Step 3: Implement with TDD
91
+ npx claude-flow sparc run tdd "${taskDescription} - implementation" --non-interactive
92
+
93
+ # Step 4: Security review
94
+ npx claude-flow sparc run security-review "${taskDescription} - security audit" --non-interactive
95
+
96
+ # Step 5: Documentation
97
+ npx claude-flow sparc run docs-writer "${taskDescription} - documentation" --non-interactive
98
+ \`\`\`
99
+
100
+ ### 4. **Best Practices Reminder**
101
+ When using any SPARC mode, remember:
102
+ โœ… Keep files modular (< 500 lines)
103
+ โœ… Never hardcode environment variables
104
+ โœ… Use configuration files for env-specific values
105
+ โœ… Write tests for critical functionality
106
+ โœ… Document your decisions in memory
107
+
108
+ ### 5. **Memory Management**
109
+ Track your progress across modes:
110
+ \`\`\`bash
111
+ # Store project context
112
+ npx claude-flow memory store ${memoryNamespace}_context "Working on: ${taskDescription}"
113
+
114
+ # Query previous work
115
+ npx claude-flow memory query ${memoryNamespace}
116
+
117
+ # List all memory entries
118
+ npx claude-flow memory list
119
+ \`\`\`
120
+
121
+ ## Next Steps
122
+
123
+ Based on your request "${taskDescription}", which SPARC mode would you like to use? Or would you like me to help you break down your task into smaller, mode-specific subtasks?
124
+
125
+ Remember: The SPARC methodology ensures systematic, high-quality development. Each mode has a specific purpose - use them in combination for best results!`;
126
+ }
@@ -0,0 +1,85 @@
1
+ // code.js - Auto-Coder mode orchestration template
2
+ export function getCodeOrchestration(taskDescription, memoryNamespace) {
3
+ return `
4
+ ## Task Orchestration Steps
5
+
6
+ 1. **Context & Architecture Review** (5 mins)
7
+ - Review implementation task: "${taskDescription}"
8
+ - Query architecture and pseudocode:
9
+ \`\`\`bash
10
+ npx claude-flow memory query ${memoryNamespace}_architecture
11
+ npx claude-flow memory query ${memoryNamespace}_pseudocode
12
+ npx claude-flow memory query ${memoryNamespace}_tech_specs
13
+ \`\`\`
14
+ - Identify modules to implement and their boundaries
15
+ - Review configuration requirements
16
+ - Check for any blocking dependencies
17
+
18
+ 2. **Project Setup & Configuration** (10 mins)
19
+ - Initialize project structure following clean architecture
20
+ - Set up environment configuration (NO hardcoded values):
21
+ - Create .env.example with all required variables
22
+ - Set up config/ directory with environment loaders
23
+ - Implement secrets management abstraction
24
+ - Install dependencies based on tech specs
25
+ - Create module structure (each file < 500 lines)
26
+ - Store setup: \`npx claude-flow memory store ${memoryNamespace}_setup "Project structure: src/{domain,application,infrastructure}. Config: dotenv + vault integration. Dependencies: express, joi, winston."\`
27
+
28
+ 3. **Modular Implementation** (30 mins)
29
+ - Implement features using clean architecture principles:
30
+ - Domain layer: Business entities and rules
31
+ - Application layer: Use cases and workflows
32
+ - Infrastructure layer: External integrations
33
+ - Follow SOLID principles and dependency injection
34
+ - Keep each module/file under 500 lines
35
+ - Use configuration for ALL environment-specific values
36
+ - Implement comprehensive error handling
37
+ - Add structured logging with context
38
+ - Store progress: \`npx claude-flow memory store ${memoryNamespace}_implementation "Completed: auth-service (3 modules), user-repository (2 modules). Remaining: notification-service."\`
39
+
40
+ 4. **Integration & Basic Testing** (15 mins)
41
+ - Wire up dependency injection container
42
+ - Connect modules following architecture design
43
+ - Implement health checks and monitoring endpoints
44
+ - Add input validation and sanitization
45
+ - Create smoke tests for critical paths
46
+ - Verify configuration loading works correctly
47
+ - Test error scenarios and graceful degradation
48
+ - Store results: \`npx claude-flow memory store ${memoryNamespace}_tests "Smoke tests passing. Health checks operational. Error handling verified. Ready for TDD mode deep testing."\`
49
+
50
+ 5. **Code Quality & Documentation** (10 mins)
51
+ - Run linters and formatters
52
+ - Add inline documentation for complex logic
53
+ - Create API documentation (if applicable)
54
+ - Generate dependency graphs
55
+ - Update README with setup instructions
56
+ - Store completion: \`npx claude-flow memory store ${memoryNamespace}_code_complete "Implementation complete. All modules < 500 lines. No hardcoded secrets. Ready for testing and integration."\`
57
+
58
+ ## Deliverables
59
+ - src/
60
+ - domain/ (business logic, < 500 lines per file)
61
+ - application/ (use cases, < 500 lines per file)
62
+ - infrastructure/ (external integrations)
63
+ - config/ (environment management)
64
+ - tests/
65
+ - smoke/ (basic functionality tests)
66
+ - fixtures/ (test data)
67
+ - config/
68
+ - .env.example (all required variables)
69
+ - config.js (environment loader)
70
+ - docs/
71
+ - API.md (if applicable)
72
+ - SETUP.md (detailed setup guide)
73
+
74
+ ## Tool Usage Reminders
75
+ - Use \`insert_content\` for new files or empty targets
76
+ - Use \`apply_diff\` for modifying existing code with complete search/replace blocks
77
+ - Avoid \`search_and_replace\` unless absolutely necessary
78
+ - Always verify all tool parameters before execution
79
+
80
+ ## Next Steps
81
+ After implementation, delegate to:
82
+ - \`npx claude-flow sparc run tdd "Write comprehensive tests for ${taskDescription}" --non-interactive\`
83
+ - \`npx claude-flow sparc run integration "Integrate ${taskDescription} with existing systems" --non-interactive\`
84
+ - \`npx claude-flow sparc run security-review "Security audit for ${taskDescription}" --non-interactive\``;
85
+ }
@@ -0,0 +1,112 @@
1
+ // debug.js - Debugger mode orchestration template
2
+ export function getDebugOrchestration(taskDescription, memoryNamespace) {
3
+ return `
4
+ ## Task Orchestration Steps
5
+
6
+ 1. **Issue Analysis & Reproduction** (10 mins)
7
+ - Understand the reported issue: "${taskDescription}"
8
+ - Query relevant context and previous issues:
9
+ \`\`\`bash
10
+ npx claude-flow memory query ${memoryNamespace}_bugs
11
+ npx claude-flow memory query ${memoryNamespace}_implementation
12
+ npx claude-flow memory query ${memoryNamespace}_tests
13
+ \`\`\`
14
+ - Set up debugging environment:
15
+ - Enable verbose logging
16
+ - Configure debugging tools
17
+ - Prepare monitoring setup
18
+ - Reproduce the issue consistently
19
+ - Collect error messages, stack traces, and logs
20
+ - Identify affected components and dependencies
21
+ - Store findings: \`npx claude-flow memory store ${memoryNamespace}_issue_analysis "Issue: ${taskDescription}. Reproduction: Steps 1-3. Error: Stack trace at line X. Affected: auth-service, user-repository."\`
22
+
23
+ 2. **Root Cause Investigation** (20 mins)
24
+ - Add strategic debug logging:
25
+ - Entry/exit points of suspect functions
26
+ - State before/after transformations
27
+ - External service call results
28
+ - Use debugging tools:
29
+ - Debugger breakpoints
30
+ - Memory profilers (if memory issue)
31
+ - Network analyzers (if API issue)
32
+ - Trace execution flow systematically:
33
+ - Follow data through the system
34
+ - Check assumptions at each step
35
+ - Verify external dependencies
36
+ - Analyze patterns:
37
+ - When does it fail? (timing, load, specific data)
38
+ - What changed recently? (code, config, dependencies)
39
+ - Avoid changing env configuration directly
40
+ - Store investigation: \`npx claude-flow memory store ${memoryNamespace}_root_cause "Root cause: Race condition in auth token refresh. Occurs under high load when token expires during request processing. Fix approach: Implement token refresh mutex."\`
41
+
42
+ 3. **Solution Development** (15 mins)
43
+ - Develop targeted fix approach:
44
+ - Minimal change to resolve issue
45
+ - Maintain backward compatibility
46
+ - Consider edge cases
47
+ - Implement the solution:
48
+ - Keep changes modular
49
+ - Don't exceed 500 lines per file
50
+ - Add inline comments explaining the fix
51
+ - Add regression tests:
52
+ - Test the specific failure scenario
53
+ - Test related edge cases
54
+ - Ensure fix doesn't break existing tests
55
+ - Implement defensive coding:
56
+ - Add validation where missing
57
+ - Improve error messages
58
+ - Add circuit breakers if needed
59
+ - Store solution: \`npx claude-flow memory store ${memoryNamespace}_solution "Fix: Added mutex lock for token refresh. Tests: 3 regression tests added. Validation: Added token expiry check. No breaking changes."\`
60
+
61
+ 4. **Validation & Performance Check** (10 mins)
62
+ - Run comprehensive test suite:
63
+ \`\`\`bash
64
+ npm test
65
+ npm run test:integration
66
+ npm run test:e2e
67
+ \`\`\`
68
+ - Verify original issue is resolved
69
+ - Check performance impact:
70
+ - Run performance benchmarks
71
+ - Monitor memory usage
72
+ - Check response times
73
+ - Test in conditions that triggered the bug
74
+ - Verify no new issues introduced
75
+ - Document the fix with context
76
+ - Store validation: \`npx claude-flow memory store ${memoryNamespace}_debug_validation "All tests passing. Performance impact: <5ms latency increase. Memory usage unchanged. Original issue resolved."\`
77
+
78
+ 5. **Documentation & Cleanup** (5 mins)
79
+ - Create detailed fix documentation
80
+ - Remove debug logging (keep useful ones)
81
+ - Update error handling guides
82
+ - Create runbook for similar issues
83
+ - Submit for code review
84
+
85
+ ## Deliverables
86
+ - Fixed code with:
87
+ - Inline comments explaining the fix
88
+ - Improved error messages
89
+ - Defensive coding additions
90
+ - tests/regression/
91
+ - Test cases for the specific bug
92
+ - Edge case coverage
93
+ - docs/
94
+ - DEBUG_REPORT.md (root cause analysis)
95
+ - FIX_DOCUMENTATION.md (what was changed and why)
96
+ - RUNBOOK.md (guide for similar issues)
97
+ - Performance comparison report
98
+
99
+ ## Debugging Best Practices
100
+ - Use structured logging with correlation IDs
101
+ - Avoid changing production env during debugging
102
+ - Keep debug changes isolated and reversible
103
+ - Test fixes under same conditions as bug
104
+ - Document investigation process for future reference
105
+ - Consider using feature flags for gradual rollout
106
+
107
+ ## Next Steps
108
+ After debugging completes:
109
+ - \`npx claude-flow sparc run security-review "Review security impact of ${taskDescription} fix" --non-interactive\`
110
+ - \`npx claude-flow sparc run refinement-optimization-mode "Refactor affected modules for better maintainability" --non-interactive\`
111
+ - \`npx claude-flow sparc run post-deployment-monitoring-mode "Monitor ${taskDescription} fix in production" --non-interactive\``;
112
+ }