BMAD-METHOD/.patch/821/plan.md

PR #821 Analysis and Integration Plan

Executive Summary

PR #821 introduces a comprehensive subagent system for Claude/OpenCode, creating an alternative lightweight approach to the BMAD Method. The PR adds 27,699 lines across 152 files in a new subagentic/claude-subagents/ directory.

Key Observations from PR Comments

1. Isolation: Author isolated everything in a folder to avoid confusion with original BMAD Method
2. Purpose: Provides global-level subagent installation (not just project-level)
3. Optimization: Compacted and optimized for Claude subagent format to reduce context
4. Directory Fix: Corrects OpenCode installation to /agent not /agents
5. New Personas: Adds 3 simple workflow agents (create-prd, generate-tasks, process-task-list)
6. Integration Concerns: Discussion around whether this fits into v6 architecture and sidecar model

Current State Analysis

What PR #821 Adds

• New Directory: subagentic/claude-subagents/
  • 13 agent definitions (markdown with frontmatter)
  • 4 team configurations (YAML)
  • 5 quality checklists (markdown)
  • AGENTS.md documentation
  • .idea/ IntelliJ project files

Potential Issues to Investigate

1. Architecture Alignment

   • Does this duplicate or conflict with existing v6 agent architecture in bmad/, bmd/, src/?
   • How does this relate to the sidecar pattern mentioned in v6?
   • Does this create parallel/competing agent systems?

2. File Structure Conflicts

   • .idea/ files should likely be in .gitignore (IDE-specific)
   • Does subagentic/ directory align with v6 naming conventions?
   • Are there any file path conflicts?

3. Integration Points

   • How should this integrate with existing BMAD CLI tools?
   • Should this be a module/plugin rather than core?
   • Does this need build/installer integration?

4. Documentation Consistency

   • Are agent definitions compatible with v6 schema validation?
   • Do the new agents follow v6 conventions?
   • Is there duplication with existing agent definitions?

5. Testing Coverage

   • No tests appear to be included in the PR
   • How do we validate the agent definitions?
   • How do we test the integration?

Investigation Strategy

Phase 1: Conflict Detection

1. Structural Analysis

   • Compare subagentic/ agents with bmad/, bmd/, src/modules/ agents
   • Identify overlapping/duplicate functionality
   • Check for file naming conflicts
   • Verify against v6 architecture principles

2. Schema Validation

   • Test agent YAML/markdown files against existing validators
   • Check frontmatter format compatibility
   • Validate team configuration structure

3. Integration Analysis

   • Review how this would work with existing CLI tools
   • Check compatibility with module installer system
   • Assess impact on existing workflows

Phase 2: Test Development

1. Unit Tests

   • Agent definition schema validation
   • Team configuration parsing
   • Checklist format validation

2. Integration Tests

   • CLI integration scenarios
   • Module installer compatibility
   • Agent activation/discovery

3. Regression Tests

   • Ensure existing v6 functionality unchanged
   • Verify no breaking changes to current agents

Phase 3: Issue Resolution

Based on findings, likely scenarios:

Scenario A: Accept as Module

• Move to src/modules/subagentic/
• Add proper installer configuration
• Update build/bundler configs
• Add tests

Scenario B: Merge with Existing

• Identify unique agents to keep
• Merge duplicate functionality
• Standardize format
• Update existing agents with improvements

Scenario C: Recommend External

• PR doesn't fit v6 architecture
• Recommend as separate repo/fork
• Document integration path
• Provide migration guide

Phase 4: Fix Implementation

1. Address identified conflicts
2. Add missing tests
3. Update documentation
4. Ensure build compatibility
5. Validate against all existing tests

Decision Points

Critical Questions to Answer

1. Does this PR align with v6's architectural vision?

   • Review v6-alpha README and architecture docs
   • Compare with sidecar pattern goals
   • Assess module system fit

2. Is the value proposition clear?

   • What does this provide that v6 doesn't?
   • Is the "lightweight" approach complementary or competing?
   • Does this serve a different user persona?

3. What's the maintenance burden?

   • 152 files is significant
   • Will this need ongoing sync with core agents?
   • Who maintains the subagent system?

4. Should this be core or extension?

   • Module/plugin architecture
   • Separate installation path
   • Optional vs. required

Success Criteria

For Integration Approval

• No conflicts with existing v6 structure
• Passes all existing test suites
• Adds comprehensive test coverage
• Documentation is clear and complete
• Aligns with v6 architectural principles
• Provides clear unique value
• Has defined maintenance plan
• IDE files (.idea/) properly excluded

For Alternative Recommendation

• Clear explanation of architectural mismatch
• Documented benefits of external approach
• Migration/integration guide provided
• Recommendation for separate repo structure
• Clear user guidance on when to use each approach

Timeline Estimate

• Phase 1 (Detection): 4-6 hours
• Phase 2 (Tests): 6-8 hours
• Phase 3 (Resolution): 8-12 hours (varies by scenario)
• Phase 4 (Implementation): 4-8 hours
• Total: 22-34 hours

Next Steps

1. Review existing v6-alpha architecture documentation
2. Run existing test suite baseline
3. Begin structural comparison analysis
4. Document findings in detailed report
5. Make integration recommendation