⚠️ SUPERSEDED 2026-05-24T21:20 BST — Path D was reverted to Path E (Spec-Kit per-repo) after empirical research surfaced that the 2 reasons that knocked Spec-Kit from #1 to #5 in the 2026-05-23 scorecard (multi-repo gap + Linear-MCP-as-OpenSpec-exclusive) both collapse on inspection. Content below preserved for audit trail only — do NOT execute as policy. See Path E pivot SCF for the substrate-correcting findings.
Rich-locked 2026-05-23T~19:30 BST after 3-iteration scorecard convergence: Path D = BMAD METHOD + OpenSpec hybrid, scored 96% on the 10-criterion weighted scorecard. Both frameworks adopted together; one alone does not suffice for TT’s specific shape.
What each framework contributes
| Framework | Role in TT adoption | Key capability |
|---|---|---|
| BMAD METHOD v6.6+ | Agent + role layer | Cross Platform Agent Team works across Claude Code + Cursor + Codex without reconfig; 12+ specialised role agents (PM / architect / UX / dev / QA / SM) map to TT’s role model (Rich = PM/CEO; Claude = multi-role architect+dev+QA; Steven = dev on Codex; Paul = QA/legal-SME); MIT licensed; 46,700+ GitHub stars (largest SDD ecosystem); YAML project state files |
| OpenSpec | Spec structure + Linear MCP layer | First-class multi-repo support via Owner Repo pattern (docs-strategy owns arch-state.md; code-* repos reference informationally); brownfield-focused; delta-based Propose / Apply / Archive cycle matches TT’s amendment-cycle discipline; first-class Linear MCP integration documented Jan 2026 — /opsx:new reads Linear tickets to generate proposals; /opsx:apply auto-updates Linear status to “In Progress”; /opsx:archive → “Ready for Review” when PR opened; bidirectional sync; PM-in-Linear + agent-in-code pattern |
Why D (not Spec Kit, not BMAD alone, not Path C hybrid convention)
3-iteration scorecard journey:
| Lock version | Date | Choice | Score | Trigger for next iteration |
|---|---|---|---|---|
| v1 | 2026-05-23T~18:00 | Spec Kit | (initial enthusiasm) | Deeper multi-repo research surfaced Spec Kit’s multi-repo as community-preset only |
| v2 | 2026-05-23T~18:30 | Path C Hybrid Convention | 86% | BMAD METHOD finding (46,700+ stars; Cross Platform Agent Team) underweighted in v1 |
| v3 (LOCKED) | 2026-05-23T~19:30 | Path D BMAD + OpenSpec hybrid | 96% | Linear integration research: OpenSpec has first-class Linear MCP; BMAD + Spec Kit Linear is in-dev or indirect |
Other paths scored:
- Path C Hybrid Convention (Spec Kit filenames + OpenSpec multi-repo + no CLI): 85% — loses on Linear automation
- Path A BMAD alone: 84% — Linear support in-development only
- Path E Spec Kit alone: 82% — multi-repo gap + indirect Linear via GitHub Issues bridge
- Path B OpenSpec alone: 74% — smaller ecosystem; no role structure
Sensitivity test: even if Spec Kit’s multi-repo + Linear gaps close optimistically, Path D maintains a 5-7 point lead.
Phase D” scope (the dual-framework adoption)
Scope is significantly bigger than the original D’ draft (which was just AGENTS.md + SKILL.md alignment). Now:
-
OpenSpec layer:
- Install OpenSpec per-repo (per Model D — one openspec/ root per project + nested specs)
- Owner Repo pattern: docs-strategy owns arch-state.md; code-* repos reference it informationally
- Configure Linear MCP integration for bidirectional sync
- Migrate cascade-Q files → openspec/specs/ tree per repo
- Adopt Propose/Apply/Archive cycle for new architectural decisions
-
BMAD layer:
- Install BMAD v6.6+
- Configure Cross Platform Agent Team (works across Claude+Cursor+Codex)
- Map TT roles to BMAD agents: Rich = PM; Claude = architect+dev+QA (multi-role); Steven = dev on Codex; Paul = QA/legal-SME
- YAML state files align with TT’s existing Shape A frontmatter
-
Convergence:
- BMAD agents emit specs that land in OpenSpec’s structure (per-feature)
- OpenSpec syncs spec status to Linear via MCP automatically
- TT’s existing arch-state §15 amendment registry continues — OpenSpec changes layer ON TOP, not replace
- Pre-commit hooks (frontmatter pin-drift + lock-cascade) remain; both frameworks have to coexist with them
-
TT discipline preservation:
- arch-state §15 amendment registry stays canonical
- cascade-Q files remain forensic record (migrate to openspec/specs/ format but content preserved)
- CLAUDE.md → AGENTS.md symlink across 8 repos (sub-step of D”; was original D’ scope)
- Existing memories + frontmatter-conventions.md absorbed into D” migration
-
Phase B compatibility:
- Phase B (in-flight) Shape A migration of BUILD-PLAN.md → plan.md aligns with both BMAD’s plan-as-state and OpenSpec’s spec/plan separation
- Post-Phase-B BUILD-PLAN.md files become input to D” migration; no conflict
Verification gaps that need closing at Phase D” launch-prompt §0 PRECONDITION GATE
| Gap | Verification action |
|---|---|
| BMAD multi-repo case studies for TT-class 7-repo shape | Research + verify before installing |
| OpenSpec + BMAD used together in production | Search for prior art or accept TT as early adopter |
| Codex + BMAD + OpenSpec triple integration smoke-test | Steven-readiness gate; run before locking the install |
OpenSpec’s /opsx:* commands work with both Claude Code + Codex CLI | Cross-tool verification |
| Linear MCP server + OpenSpec MCP server coexistence | Verify no conflicts with installed Linear MCP from Phase C |
Phase ordering after D” lock
| Phase | Status | Scope |
|---|---|---|
| A | LANDED (A-285) | Native Tasks migration |
| D | LANDED (A-286) | tt-inherit-v2 cross-device sync |
| B | IN-FLIGHT | BUILD-PLAN.md Shape A — fully compatible with D” |
| C | Partially absorbed by D” | OpenSpec’s native Linear MCP integration replaces most of original Phase C scope; what remains of Phase C scope is the optional active-step-projection skill (may not even be needed given OpenSpec’s /opsx:new//opsx:apply//opsx:archive lifecycle) |
| D’ | Superseded by D” | Cross-tool standard alignment (AGENTS.md + SKILL.md + EARS notation + .codex/config.toml) becomes a sub-step of D” |
| D” | Pending Phase B + verification gap closure | Dual-framework adoption (BMAD + OpenSpec); ~10-15h Claude execution; interactive; per-repo Rich-lock |
| E | Future candidate | Dual-agent (Claude + Codex) parallel pattern; naturally surfaces once Steven onboards on BMAD’s Cross Platform Agent Team |
Honest framing
This is the most ambitious of the candidate locks. Two-framework adoption has real complexity. The scorecard justifies it but the operational risk is higher than Path C. Mitigation:
- Phase B lands first (no conflict; in-flight remains valid)
- Verification gaps close before Phase D” starts (case studies + smoke-test)
- Adoption sequence: OpenSpec first (multi-repo + Linear), BMAD second (agents + cross-platform), convergence checks at each layer
- Rollback: TT’s underlying discipline (arch-state + cascade-Q + CLAUDE.md + pre-commit hooks) survives even if either framework is later removed
Setup investment accepted (Rich-directive 2026-05-23T~late evening BST)
Important addendum — after observing BMAD’s workspace-level install complexity (5 dirs + 44 skills) Rich briefly considered pivoting to Spec Kit alone for simplicity. Reconsidered same evening: “i am happy to do a lot of work to setup the optimal configuration. short term work is fine, if it helps us finish with a great solution”. This confirms the Path D lock rather than supersedes it; setup-complexity is acknowledged as acceptable cost for the 96%-scorecard long-haul solution.
Phase D” execution model — STAGED (updated 2026-05-23 evening after missed-opportunities sweep — see feedback-phase-d-double-prime-missed-opportunities): now 12 workstreams; ~20-25h Claude execution (up from ~15-20h); Rich-lock-per-stage checkpoints. Two NEW stages added: Stage 2.5 (BMAD MCP server install) + Stage 5.5 (superpowers ↔ BMAD skill coexistence policy + GSD ↔ BMAD agent coexistence). Several existing stages expanded (Stage 3 absorbs Phase B.1 spec/plan/tasks 3-file split; Stage 4 adds locked .codex/config.toml defaults + optional .cursor/rules/; Stage 6 expands with TDD-inversion default workflow; Stage 7 expands with check-build-plan-sync.py hook extension + Skills/Tools/MCP three-layer §3.8; Stage 10 expands with acquirer-DD readiness narrative). Original 10-stage list below remains as the spine; the additions above layer on top. Original stages:
- Clean up any workspace-level BMAD install (per-repo install instead) — DONE 2026-05-23 evening
- Per-repo BMAD install via federated-knowledge pattern (
npx bmad-method install --directory ~/testatetech/<repo>× 7 repos +bmad-federated-knowledgeextension at coordination layer) - Per-repo OpenSpec init (
openspec init --tools claude,codex× 7 repos; Owner Repo pattern — docs-strategy owns arch-state.md) - Cross-tool config (CLAUDE.md → AGENTS.md
git mv+ symlink; tool-agnostic content audit;.codex/config.tomltemplate) - SKILL.md schema audit at code-inheritkit/skills/{faraid,hsa,halakhic,…} against agentskills.io
- EARS-notation adoption for new step-N
exit_criteria(going-forward from Phase D”) - TT discipline → framework discipline mapping documented in
frontmatter-conventions.mdv1.4 - Linear MCP smoke-test (OpenSpec → Linear MCP bidirectional sync end-to-end)
- Codex smoke-test (skill-based invocation via
$openspec-*workaround for codex-cli v0.117.0 regression; deferred until Codex installed) - arch-state §15 A-NNN amendment + ledger increment capturing Phase D” landing
Stage 1 status (cleanup) — DONE 2026-05-23 evening: workspace-level BMAD install (from --directory ~/testatetech gate command) was cleaned. ~/testatetech/_bmad/, ~/testatetech/_bmad-output/, ~/testatetech/docs/, ~/testatetech/.claude/skills/ all absent at end-of-session verification. Preserved: OpenSpec 1.3.1, uv 0.11.16, Linear MCP at https://mcp.linear.app/mcp, npm npx cache (for fast BMAD reinstall at Stage 2).
Phase D” precondition gate (verified 2026-05-23 evening; ready for execution when Phase B lands):
# Install gates (corrected — actual commands, not comments-after-OR)
command -v openspec >/dev/null || npm install -g @fission-ai/openspec
command -v bmad >/dev/null || npx bmad-method install --directory <per-repo-path> # PER-REPO not --directory ~/testatetech
test -d ~/.codex || echo " codex: install deferred (Steven onboarding gate)"
command -v uv >/dev/null || pipx install uv
# Node + Python version check (FIXED awk bug — strip v prefix)
NODE_VER=$(node --version | sed 's/^v//')
NODE_MAJOR=$(echo "$NODE_VER" | cut -d. -f1)
NODE_MINOR=$(echo "$NODE_VER" | cut -d. -f2)
if [ "$NODE_MAJOR" -lt 20 ] || { [ "$NODE_MAJOR" -eq 20 ] && [ "$NODE_MINOR" -lt 12 ]; }; then echo " Node version too old: $NODE_VER (need 20.12+)"; else echo " Node: $NODE_VER ✓"; fi
# Linear MCP gate
claude mcp list 2>&1 | grep -q linear-server || claude mcp add --transport http linear-server https://mcp.linear.app/mcp
# bmad-federated-knowledge availability
curl -sI https://registry.npmjs.org/bmad-federated-knowledge | head -1 | grep -q "200"
# Phase B landed gate (FIXED silent-failure-mode — explicit echo)
PHASE_B_COUNT=$(git -C ~/testatetech/docs-strategy show origin/main:docs/superpowers/specs/inherit-v2-architecture-state.md 2>/dev/null | grep -cE '^### A-(288|289|290)')
echo " Phase B closure amendment count: $PHASE_B_COUNT (need ≥1)"
# Working tree gate
for r in code-inherit-v2 code-inheritkit code-ias code-inheritv2-www code-inheritv2-test-suite docs-strategy docs-admin; do
test -z "$(git -C ~/testatetech/$r status -s)" || echo "DIRTY: $r"
doneRelated: feedback-adopt-github-spec-kit (SUPERSEDED v1 lock; preserved for forensic record); feedback-build-plan-hybrid-shape-a-narrative-plus-native-tasks (Shape A still applies; aligns with both BMAD + OpenSpec); feedback-prompts-comprehensive-and-fully-detailed (Phase D” launch-prompt will be comprehensive); feedback-research-artefact-forward-traceability (cite forward to Phase D” launch-prompt when authored).