Rule (Phase D” Stage 7): extend frontmatter-conventions.md v1.3 → v1.4 with 8 SDD-ecosystem-standard fields. TT’s existing frontmatter becomes a superset of SDD-required fields + TT-specific extensions (companion_files / phase_q_relevance / inherits_substrate_from / gold_value all retained).
Why: BMAD + OpenSpec hybrid lock (Path D, 96% scorecard) requires TT artefacts be machine-readable to the SDD framework tooling. Research surfaced 8 fields that SDD ecosystems converged on (SKILL.md required; Cursor .mdc required; OpenSpec spec.md metadata; BMAD workflow files; Spec Kit / Kiro common). TT had ~60% of these natively (status / lastmod / supersedes / companion_files etc.); the remaining ~40% gap is what blocks cross-tool readability.
Specifically: without description, agents using progressive-disclosure (Claude Code + Codex + Cursor + Gemini + 8+ other tools per agentskills.io) can’t decide whether to load a TT spec at startup — they only see filename. Without framework_artifact_type, SDD tooling can’t tell a cascade-Q file (spec) from a BUILD-PLAN.md (plan) from an arch-state amendment (constitution). Without linear_story_id, the OpenSpec → Linear MCP bidirectional sync (the killer Linear-integration finding from scorecard v3) has nothing to bind to.
How to apply: Phase D” Stage 7 (~5-7h Claude) authors v1.4 with the 8 fields below + EARS-notation §3.7 + framework_artifact_type mapping table + pin-drift hook regression-tested + targeted backfill on constitution-level docs.
The 8 new fields
| # | Field | Type | Required | Purpose | Source convention |
|---|---|---|---|---|---|
| 1 | description | string ≤120 chars | YES (v1.4 onwards) | Progressive-disclosure hook agents read at startup to decide load-or-skip; complements verbose title + canonical_role | SKILL.md required minimum (name + description); Cursor .mdc required |
| 2 | globs | array of glob patterns | No | Auto-attach to code paths when agent edits matching files (e.g., ["**/*.catala_en"] for Catala rule specs) | Cursor .mdc |
| 3 | always_apply | bool (default false) | No | TRUE for constitution-level docs (CLAUDE.md / AGENTS.md / arch-state.md); FALSE for most | Cursor .mdc |
| 4 | framework_artifact_type | enum: spec / plan / tasks / constitution / skill / change-proposal / audit-record / memory | No | Maps TT artefacts to SDD primitives; machine-readable across Spec Kit / OpenSpec / BMAD / Kiro / Cursor | Spec Kit / OpenSpec / Kiro common |
| 5 | depends_on | array of doc IDs/paths | No | Document-level dependencies (sister to per-step depends_on Phase B adds at row level) | SDD common; OpenSpec |
| 6 | acceptance_criteria | array of EARS-notation strings | No | Top-level success conditions: ["WHEN partner-firm pilot completes, THE SYSTEM SHALL produce F1 ≥0.85"] | Spec Kit / Kiro / EARS standard |
| 7 | linear_story_id | string | No | OpenSpec pattern — issue-tracker linking when spec mirrors to Linear; load-bearing for OpenSpec /opsx:new ↔ Linear MCP bidirectional sync | OpenSpec |
| 8 | id | string (kebab-case) | No | Stable document identifier for cross-references (independent of filename which can change) | SDD common |
TT artefact → framework_artifact_type mapping table
| TT artefact | framework_artifact_type | Notes |
|---|---|---|
~/.claude/CLAUDE.md / ~/.claude/AGENTS.md / per-repo CLAUDE.md/AGENTS.md | constitution | always_apply: true |
arch-state.md (Tier-1 cross-repo) | constitution | always_apply: true |
inheritkit-architecture-state.md / ias-architecture-state.md (Tier-2/3) | constitution | always_apply: true for in-tier scope |
Cascade-Q files (Q-NNN-zeta-*-locked.md) | spec | One spec per locked decision |
| Critique-ready-spec / option scorecards | spec | |
BUILD-PLAN.md (post-Phase-B Shape A) | plan | After Phase B Shape A migration |
inherit-v2-phase-1-master-plan.md | plan | Cross-repo orchestration plan |
sprint-backlog.md (generated) | tasks | Re-generated by script; don’t hand-edit |
| Native Tasks JSON files | tasks | Already in shape after Phase A |
Audit-records (audit-records/<date>-*/) | audit-record | Historical batch closures |
Memory files (feedback_*.md / project_*.md / gsd-*.md) | memory | Cross-session recall substrate |
| OpenSpec change proposals (Phase D” onwards) | change-proposal | OpenSpec Propose/Apply/Archive cycle |
code-inheritkit/skills/*/SKILL.md | skill | Existing partner-firm-Claude-Code skills |
Spike T-files (~/off-github/library/projects/inherit/T-*.md) | spec | Research-source-for-decision specs |
3 Rich-locks deferred to Phase D” authoring time
-
Is
descriptionREQUIRED on new docs from v1.4 onwards? Recommended yes — progressive disclosure becomes load-bearing once SDD tooling lands (Codex/Cursor/Gemini all consumedescriptionnatively for agent-decided rule inclusion). -
Backfill scope — all docs or just constitution-level? Recommended just constitution-level (~20 docs: 8 CLAUDE.md/AGENTS.md + arch-state.md + inheritkit-arch-state.md + ias-arch-state.md + master-plan + canonical specs + critique-ready-spec). Let other docs adopt incrementally as they’re touched.
-
EARS notation enforcement — pre-commit hook or convention-only? Recommended convention-only initially; hook-enforce after Phase D”+1 retro (need to see whether teams actually write good EARS-notation in practice before mechanically enforcing it).
Implementation cost (Phase D” Stage 7)
| Step | Effort | Risk |
|---|---|---|
Update frontmatter-conventions.md v1.3 → v1.4 with 8 new fields + mapping table | ~1-2h Claude | Low — additive |
| Add §3.7 EARS-notation primer + examples to v1.4 | ~30 min | None |
Update check-frontmatter-pins.py pre-commit hook to validate new field types (esp. framework_artifact_type enum + EARS-notation pattern in acceptance_criteria) | ~2-3h Claude | Medium — hook regression risk; thorough test against existing docs before commit |
Backfill description field on ~20 constitution-level docs | ~1-2h Claude | Low |
Document framework_artifact_type mapping table in v1.4 (table above) | ~30 min | None |
Total: ~5-7h Claude as Phase D” Stage 7. Bounded; durable; high-leverage.
Strategic alignment
After v1.4 lands, TT’s artefacts become directly addressable by SDD framework tooling:
- Spec Kit can recognise TT cascade-Q files via
framework_artifact_type: spec - BMAD can find TT BUILD-PLANs via
framework_artifact_type: plan - Cursor can auto-attach Catala-related TT specs via
globs: ["**/*.catala_en"] - OpenSpec can link TT specs to Linear via
linear_story_id - Any agent in the agentskills.io 12-tool ecosystem (Claude Code / Codex / Cursor / Gemini / Copilot / Cline / Roo Code / Goose / Aider / Windsurf / Kilo / OpenCode / Augment / Antigravity) can read
descriptionfor progressive disclosure
Cross-tool portability becomes automatic, not a per-tool re-authoring exercise.
Related: feedback-adopt-bmad-plus-openspec-hybrid (the Path D lock this serves); feedback-build-plan-hybrid-shape-a-narrative-plus-native-tasks (Phase B’s 10-improvement Shape A already adds per-step depends_on + exit_criteria; v1.4 adds the document-level analogues); feedback-prompts-comprehensive-and-fully-detailed (Phase D” launch-prompt covers this as Stage 7); feedback-research-artefact-forward-traceability (companion_files + phase_q_relevance discipline preserved as TT-specific extensions on top of SDD standard fields).