Skip to content

🔄 Planning Framework Decision

Executive Summary

This document captures our research and decision regarding planning frameworks for GetCimple. After comprehensive analysis of GitHub spec-kit and BMAD-METHOD v6-alpha, we decided to adopt BMAD-Lite concepts + Anthropic Agent Skills instead of full framework adoption.

Decision: See ADR-0008: BMAD-Lite + Agent Skills

Research Summary

Frameworks Evaluated

1. GitHub spec-kit - Template-driven, executable specs generating code - Constitutional principles (9 articles) - Designed for greenfield 0-to-1 development - Verdict: Defer until MVP implementation phase

2. BMAD-METHOD v6-alpha - Agent orchestration (Analyst, PM, Architect, SM, Dev) - 4-phase workflow: Analysis → Planning → Solutioning → Implementation - Scale-adaptive (Level 0-4 complexity) - Brownfield support (but incomplete in alpha) - Verdict: Defer until stable release (beta delayed, alpha instable)

Key Findings

Both frameworks: - ❌ Designed for implementation phase (we're in planning) - ❌ Add directory/workflow overhead - ❌ Generic templates (we have domain-specific stakeholder needs) - ✅ Have valuable concepts to learn from

AI Consensus (Claude, Codex, Gemini, GPT-5): - Unanimous: Do NOT adopt full frameworks now - Recommendation: Cherry-pick concepts, monitor framework evolution, re-evaluate at MVP implementation

What We Adopted Instead: BMAD-Lite + Agent Skills

See: ADR-0008 for complete details.

Adopted Concepts: 1. ✅ Complexity indicator (simple/moderate/complex) in spec frontmatter 2. ✅ Light ADRs (3-8 total, irreversible decisions only) 3. ✅ Phase awareness (Planning → MVP → Iterate) 4. ✅ [[NC:id @owner]] clarification markers 5. ✅ Spec Readiness Checklist (8 items) 6. ✅ Definition of Ready 7. ✅ Anthropic Agent Skills (5 skills created) 8. ✅ Risk log (HIGH/MEDIUM only) 9. ✅ Stakeholder mapping (Directors vs Management) 10. ✅ Compliance anchors (ACSC Essential 8 citations) 11. ✅ Decision log (lightweight journal) 12. ✅ Monthly retrospective (30 min process review)

Files Created (2025-10-20): - ai-docs/skills/ - 5 Agent Skills for Claude Code - ai-docs/shared/ - Templates and checklists - specs/templates/enhanced-feature-spec-template.md - 05-architecture/decisions/ - 8 ADRs

Time Investment: 3 hours setup, <15 min/week ongoing

Frameworks Monitoring Plan

GitHub spec-kit

Track: https://github.com/github/spec-kit Monitor for: - Release updates and stability improvements - Brownfield support additions - Community adoption and case studies

Re-evaluate at: MVP implementation kickoff (2025-Q2 estimated)

Adoption Triggers: - Stable release (production-ready) - Demonstrated value for implementation phase - Team comfortable with directory restructuring if needed

BMAD-METHOD

Track: https://github.com/bmad-code-org/BMAD-METHOD/tree/v6-alpha Monitor for: - v6-alpha → beta transition - Brownfield-analysis workflow completion - Stability improvements and feature completeness

Re-evaluate at: v6 beta release OR MVP implementation kickoff (whichever later)

Adoption Triggers: - Beta or stable release (not alpha) - Brownfield workflow implemented and documented - Case studies demonstrating end-to-end use - Ongoing maintenance <2-4 hours/month

Current Approach: BMAD-Lite

What We're Doing NOW

Agent Skills (ai-docs/skills/): - Analyst: Requirements elicitation & compliance analysis - Architect: Technical decisions & ADR creation - Reviewer: Spec quality assurance - Spec Readiness: Quick DoR validation - Risk Scan: Risk detection & mitigation

Planning Tools: - [[NC:id @owner]] markers for ambiguity tracking - 8-item Spec Readiness Checklist - Definition of Ready (quality gate) - Light ADRs (cap at 3-8 until MVP) - Risk log (HIGH/MEDIUM only) - Monthly retrospective

Time Budget: - Setup: 3 hours (COMPLETED 2025-10-20) - Ongoing: <15 min/week - Monthly retro: 30 min

Success Metrics (1 Month Check-in: 2025-11-20)

Expected Outcomes: - [ ] Specs have no [[NC:]] markers at completion - [ ] 3-8 ADRs documenting major decisions - [ ] 5-10 active risks in risk log - [ ] Skills loaded 3+ times/week - [ ] Process overhead <15 min/week - [ ] Faster spec iterations (fewer back-and-forth rounds with Claude)

Red Flags (Abandon elements if seen): - 🚩 Process overhead >30 min/week - 🚩 ADR count >15 before MVP - 🚩 Risk log >20 items - 🚩 Skills never used - 🚩 Team skipping checklists

Future Decision Points

MVP Implementation Kickoff (2025-Q2 estimated)

Re-evaluate: - Is BMAD v6 stable (beta or v1.0)? - Is spec-kit still relevant for our needs? - Are our BMAD-Lite practices working well?

Options: 1. Continue BMAD-Lite (if working well) 2. Adopt spec-kit (if it provides clear implementation value) 3. Adopt BMAD v6 (if stable and brownfield support complete) 4. Build custom slash commands inspired by both frameworks

Decision Criteria: - Adoption gates from ADR-0008 - Team satisfaction with current approach - Complexity level of upcoming features

Post-MVP Growth (2025-Q3+ estimated)

Triggers for framework adoption: - Team grows beyond 3-4 people - Multiple services/modules with cross-cutting concerns - Rising coordination costs (blocked PRs, unclear specs) - Need for brownfield integration (adding features to MVP codebase)

Archived Content

Original BMAD Integration Plan (2025-01-31)

This section preserved for historical reference

The original plan proposed: - Installing BMAD-METHOD v4 to create PRD - Using BMAD agents (Analyst, PM, Architect, PO) - Document sharding workflow - Parallel track approach

Why we changed course: - v6-alpha released (v4 superseded) - v6-alpha too unstable for startup needs - Planning phase mismatch (BMAD optimized for implementation) - BMAD-Lite provides concepts without complexity

Original document: Archived below for reference

Original BMAD Integration Plan (2025-01-31) ### Phase 1: Fast-Track Brief Creation (1-2 days) 
# Create BMAD project folder
mkdir getcimple-bmad && cd getcimple-bmad

# Install BMAD-METHOD (Archived)
npx bmad-method install
_[Original plan content continues below...]_ _[Full original document preserved for historical reference]_

References

Document Status: Updated to reflect BMAD-Lite decision (2025-10-20) Original Plan: Archived in collapsed section above Current Approach: See ADR-0008 and ai-docs/skills/ for implementation