Skip to content

ADR-0008: BMAD-Lite Concepts + Anthropic Agent Skills

Status: Accepted Date: 2025-10-20 Deciders: GetCimple Team Tags: process, tooling, ai-assisted-development, documentation

Context

GetCimple researched two planning frameworks for AI-assisted development: - GitHub spec-kit: Template-driven, executable specs, constitutional principles - BMAD-METHOD v6-alpha: Agent orchestration, 4-phase workflow, brownfield support

Both frameworks are designed for active software development (implementation phase), but GetCimple is in planning phase (comprehensive documentation, no code yet). Additionally, Anthropic released Agent Skills (Oct 16, 2025), a new way to provide domain-specific context to Claude.

Requirements: - Enhance planning quality without process overhead - Better Claude Code collaboration through structured context - Stakeholder clarity (Directors vs Management) - Compliance documentation rigor (ACSC Essential 8) - Risk visibility for boards

Constraints: - 3-person startup (time budget: <15 min/week for process overhead) - Planning phase, not implementation - Existing workflow (MkDocs + specs/ + Claude Code) works well - Cannot afford framework instability (BMAD v6-alpha is unstable)

Options Considered

Option A: Adopt GitHub spec-kit (Full Framework)

Description: Use .specify/ directory, /speckit.* commands, constitutional articles.

Pros: - ✅ Structured workflow automation - ✅ Constitutional principles for architecture - ✅ Proven in production

Cons: - ❌ Directory conflict (.specify/ vs specs/) - ❌ Generic templates (lose domain-specific stakeholder focus) - ❌ Implementation-focused (not planning-focused) - ❌ Would require restructuring existing 14+ specs

Estimated Effort: 1-2 weeks migration + ongoing maintenance

AI Consensus: Defer until MVP implementation phase

Option B: Adopt BMAD-METHOD v6-alpha (Full Framework)

Description: Use bmad/ directory, 4-phase workflow (Analysis → Planning → Solutioning → Implementation), agent orchestration.

Pros: - ✅ Brownfield support awareness (will need eventually) - ✅ Scale-adaptive (Level 0-4 complexity) - ✅ Rich agent ecosystem

Cons: - ❌ Alpha instability: "Frequent updates", "incomplete features", beta delayed - ❌ Brownfield incomplete: brownfield-analysis workflow is "TBD" - ❌ High complexity (4 phases, state machines, story tracking) - ❌ Implementation-focused (planning phase mismatch) - ❌ Maintenance burden for 3-person team

Estimated Effort: 2-3 weeks setup + high ongoing churn (alpha updates)

AI Consensus: Defer until beta/stable release + MVP implementation phase

Option C: BMAD-Lite Concepts + Agent Skills (Hybrid - No Framework)

Description: Cherry-pick valuable concepts from spec-kit and BMAD, implement as lightweight practices. Adopt Anthropic Agent Skills for Claude Code context management.

Pros: - ✅ Lightweight: ~2-3 hours setup, <15 min/week maintenance - ✅ No framework lock-in: Plain files and checklists - ✅ Preserves existing structure: No directory changes, keep specs/ - ✅ Agent Skills integration: Official Anthropic feature (stable, supported) - ✅ Enhances Claude Code: Better context management via progressive disclosure - ✅ Right-sized for startup: Avoid enterprise theater - ✅ Flexibility: Can adopt full frameworks later if needed

Cons: - ❌ Less automation than full frameworks - ❌ Manual tracking (no CLI tools) - ❌ DIY approach (no vendor support)

Estimated Effort: 3 hours setup, <15 min/week maintenance

AI Consensus: UNANIMOUS recommendation

Decision

We chose: Option C - BMAD-Lite + Agent Skills

Rationale: 1. Unanimous AI consensus: Claude, Codex, Gemini, GPT-5 all recommended this approach 2. Right-sized: 3 hours setup vs 1-3 weeks for full frameworks 3. Preserves momentum: No restructuring, no migration, no learning curve 4. Official Anthropic support: Agent Skills is stable, documented, integrated in Claude Code 5. Best of both worlds: Cherry-pick valuable concepts, avoid complexity traps 6. Startup-appropriate: Minimal process overhead, maximum value 7. Future-compatible: Can adopt full frameworks later if complexity justifies it

Concepts Adopted from BMAD: - Phase awareness (Planning → MVP → Iterate) - Light ADRs for irreversible decisions (cap at 3-5 until MVP) - Complexity indicator (simple/moderate/complex) - Risk log (HIGH/MEDIUM only) - Monthly retrospective (30 min process review)

Concepts Adopted from spec-kit: - [[NC:id @owner]] clarification markers - Spec Readiness Checklist (8 items) - Definition of Ready - Pre-implementation validation

Agent Skills Implementation: - 5 Skills created (analyst, architect, reviewer, spec-readiness, risk-scan) - Progressive disclosure reduces context bloat - Domain-specific to GetCimple (Directors vs Management, ACSC Essential 8)

Key Trade-offs Accepted: - We're accepting less automation (no CLI tools) for zero lock-in - We're accepting manual tracking for lightweight process - We're betting that concepts are more valuable than tools at this stage

Consequences

Positive

  • ✅ Enhanced Claude collaboration: Skills provide targeted, role-based context
  • ✅ Better spec quality: DoR and checklists catch gaps before implementation
  • ✅ Captured decisions: ADRs document architectural rationale for future reference
  • ✅ Risk visibility: Risk log surfaces compliance and technical risks for board
  • ✅ Explicit ambiguities: [[NC:]] markers prevent assumptions and miscommunication
  • ✅ Stakeholder alignment: Systematic Director vs Management analysis
  • ✅ Low overhead: <15 min/week process maintenance
  • ✅ Flexibility: Can adopt full frameworks later if complexity justifies

Negative

  • ⚠️ Manual process: No automated branch creation, numbering, or validation
  • ⚠️ DIY maintenance: No vendor to fix bugs or add features
  • ⚠️ Discipline required: Team must actually use checklists (no enforcement)

Risks

Risk Likelihood Impact Mitigation
Process becomes "theater" (overhead without value) MEDIUM MEDIUM Monthly retro to prune unused elements; red flag: >30 min/week
ADRs proliferate (>20 before MVP) LOW LOW Strict criteria: irreversible decisions only; raise bar if needed
Skills unused (team forgets to load them) MEDIUM LOW Document in CLAUDE.md; I'll remind when relevant; train team to ask "load analyst skill"
Complexity creeps in (more checklists, templates) MEDIUM MEDIUM Guard 2-hour setup budget; reject additions that don't save time weekly

Compliance Note

ACSC Essential 8 Impact: - Process improvement: Better documentation and decision capture supports audit trail - Risk management: Risk log provides visibility into compliance gaps - Not a control: This is process tooling, not a compliance control itself

Australian Data Residency: - Agent Skills: Local files in ai-docs/, no data sent to external services - Claude Code: Anthropic's Claude API (verify Australian region if concerns)

Audit Trail: - All ADRs, specs, and decisions tracked in Git - Risk log provides historical risk management documentation

Implementation Summary

Files Created (2025-10-20):

Agent Skills (ai-docs/skills/): - analyst/SKILL.md - Requirements elicitation & compliance analysis - architect/SKILL.md - Technical decisions & ADR creation - reviewer/SKILL.md - Full spec quality review - spec-readiness/SKILL.md - Quick DoR validation utility - risk-scan/SKILL.md - Risk detection & mitigation proposals

Shared Templates (ai-docs/shared/): - definition-of-ready.md - 8 readiness criteria - spec-checklist.md - Checkbox version - adr-template.md - Architectural Decision Record format - decision-log-template.md - Lightweight decision journal - risk-log-template.md - HIGH/MEDIUM risk tracking

Enhanced Spec Template: - specs/templates/enhanced-feature-spec-template.md - With frontmatter, [[NC:]] markers, DoR checklist

ADRs Created (docs-internal/docs/05-architecture/decisions/): - 0001-supabase-backend.md - 0002-cloudflare-hosting.md - 0003-kinde-authentication.md (includes [[NC:kinde-1]] for datacenter verification) - 0004-mkdocs-documentation.md - 0005-react-frontend.md - 0006-pnpm-package-manager.md - 0007-no-ai-mvp.md - 0008-bmad-lite-agent-skills.md (this document)

Integration Points: - Claude Code: Load Skills via file paths (ai-docs/skills/[role]/SKILL.md) - Specs: Reference templates in ai-docs/shared/ - MkDocs: Skills excluded from public site (internal only) - Git: All files version controlled

Time Invested: - Setup: 3 hours (skills creation, templates, ADRs) - Expected ongoing: <15 min/week (risk log updates, monthly retro)

Revisit

Revisit By: 2025-05-01 (after 3 months of use) Blast Radius: LOW - Additive practices, easy to abandon if not working

Conditions for Revisit: - Process overhead exceeds 30 min/week (prune immediately) - Skills unused (<1 load/week) (simplify or remove) - Full frameworks stabilize and offer compelling value - Team size increases (4+ people may need more structure)

Next Review: 2025-01-20 (monthly retro #1)

Success Metrics (After 1 Month): - [ ] Specs have no [[NC:]] markers at completion - [ ] 3-8 ADRs total (not 20+) - [ ] Risk log has 5-10 active items (not 30+) - [ ] Skills loaded 3+ times/week - [ ] Process overhead <15 min/week

Red Flags (Abandon if seen): - Process overhead >30 min/week - ADR count >15 before MVP - Risk log >20 items - Team skipping checklists (means they're not valuable) - Skills never loaded (means they're not helpful)

References

AI Model Consensus

All AI models consulted agreed on this approach:

Codex: "Keep lean scaffolding. Fold checklist + DoR. Add stakeholder mapping and compliance anchors."

Gemini: "Excellent balance for 3-person startup. All 8 concepts should be kept. Add decision log."

GPT-5: "Adopt Skills format now. Convert analyst/architect/review modes to Skills. Keep frontmatter minimal."

Claude (me): "BMAD-Lite is right-sized. Agent Skills is official Anthropic feature with zero lock-in."

Version History

Version Date Author Changes
1.0 2025-10-20 Claude ADR documenting BMAD-Lite + Agent Skills adoption decision