Transfer spec-kit patterns: knowledge.md, clarify, coverage gate, spec self-checklist

[codevibesmatter]

Summary

Selectively transfer the highest-ROI patterns from github/spec-kit into kata, without its bloat (multi-agent layer, nested spec dirs, 4-level template override, extensions/presets).

Motivation

Spec-kit and baseplane's layered-docs system independently arrived at similar ideas kata is missing:

• A referenced constitution (not just advisory ceremony)
• A post-draft clarify pass (distinct from pre-spec interview)
• Cross-artifact coverage gates (behaviors ↔ phases ↔ VP)
• Self-validating specs (checklist baked into the artifact)
• Layered project knowledge with change-cadence lifecycles

Scope

New

1. .kata/knowledge.md — project knowledge TOC with change-cadence table. Principles inline, links to project layers. Layer count is project-declared, not kata-prescribed.
2. kata-clarify skill — reads draft spec, emits ambiguity list, patches spec in place. Runs between spec-draft and spec-review.
3. Coverage-matrix gate in kata-spec-review — every B-ID must map to ≥1 phase task and ≥1 VP step; review fails on gaps.
4. Spec template self-checklist — spec isn't complete until its own acceptance checks pass.

Modified

• kata-setup skill: interviews user for knowledge layers, generates knowledge.md.
• kata-spec-writing, kata-spec-review, kata-clarify all load knowledge.md.
• Planning flow: research → interview → knowledge-load → spec draft → clarify → spec final → review+coverage → approved.

Out of scope (explicitly skipped from spec-kit)

• Multi-agent abstraction (Claude-native)
• Separate /plan vs /specify artifacts
• specs/NNN-feature/ nested dirs with 5+ files
• Extensions/presets template override system
• Per-user-story checkpoint validation

Acceptance

• Fresh project: kata-setup produces minimal knowledge.md (principles + rules).
• Mature project (baseplane-style): knowledge.md references 5 layers with change-cadence.
• Spec-writing cites principles from knowledge.md.
• Spec with missing VP coverage for a B-ID fails review.
• Spec with unresolved ambiguities fails clarify.
• Spec template includes self-checklist section; review gates on it.

Estimated effort

~20 hours total. MVP bundle (knowledge.md + self-checklist + coverage gate) is ~9 hours.

References

• Spec-kit: https://github.com/github/spec-kit
• Baseplane layered docs: /data/projects/baseplane-dev1/docs/index.md