terse: rewrite v0.8.1 command templates — 1998 → 642 lines

[fry-lobster]

Summary

Restores the fork's terse identity on top of v0.8.1. Before: the 9 command templates copied upstream verbatim (1998 lines total). After: rewritten terse versions (642 lines total — 68% cut).

Why

fellowship-dev/pylot#239 tracks this re-trim. PR #2 synced upstream but dropped the terse customizations to keep conflict resolution tractable; this PR is the follow-up that puts them back.

What I trimmed

1. Hook-checking boilerplate. Every command had ~60 lines reading .specify/extensions.yml and formatting hook messages, duplicated across 9 files. Collapsed to one line: "Run hooks.before_X from .specify/extensions.yml if present." This alone saved ~500 lines.
2. Long example enumerations. implement.md's per-technology ignore-file patterns (Node/Python/Java/C#/Go/Ruby/PHP/Rust/Kotlin/C++/C/Swift/R), specify.md's "For AI Generation" / Good vs Bad examples tables, clarify.md's taxonomy enumeration. Cut to 2-3 representative cases each.
3. Philosophy prose restating what the step-by-step already said. Removed.

What I preserved

• All v0.8.1 functional additions: __SPECKIT_COMMAND_X__ template markers (install-time substitution), .specify/feature.json persistence, branch_numbering (sequential vs timestamp), extension hook points, checklist gate in implement, scripts: frontmatter with both sh: and ps: variants.
• Handoff frontmatter exactly as upstream (dot-form agent names — installer transforms to hyphen for Claude).
• The "unit tests for English" metaphor in checklist (core concept, 10 lines).
• The sequential-question loop rules + Clarifications section structure in clarify (load-bearing for spec integrity).
• Task checklist format rules in tasks.md (AI must produce exact format).
• Constitution versioning / amendment rules.

What I added

Output line limits on the terse command instructions:

• spec.md must be ≤50 lines (in specify)
• plan.md must be ≤60 lines (in plan)
• Checklist format is load-bearing for tasks

Per-file before/after

File	Before	After	Delta
specify.md	327	74	-253
plan.md	152	59	-93
tasks.md	203	84	-119
implement.md	201	65	-136
analyze.md	252	95	-157
checklist.md	364	54	-310
clarify.md	250	94	-156
constitution.md	150	76	-74
taskstoissues.md	99	41	-58
Total	1998	642	-1356

Verification

Installed the rewritten fork locally:

uvx --from git+https://github.com/fellowship-dev/spec-kit.git@terse/v0.8.1-commands specify init --here --ai claude

Installed skills total 668 lines (down from ~2000 for upstream equivalents). All skill names and invocation paths unchanged (/speckit-specify, /speckit-plan, etc.).

Data templates (not in this PR)

templates/*-template.md (spec-template 128L, plan-template 104L, tasks-template 251L) retain upstream's example sections. The command-level line limits constrain output at generation time regardless of template verbosity, but if generated artifacts still run long in practice, template trimming follows as a separate PR.

🤖 Generated with Claude Code

[maxfindel]

Double-Check Review: PR fellowship-dev/spec-kit#3 — terse: rewrite v0.8.1 command templates — 1998 → 642 lines

Reviewer: tooling.cto (automated double-check)
Branch: terse/v0.8.1-commands → main

---

Intent

Restores the fork's terse command style on top of v0.8.1. The PR delivers what it claims: all 9 command templates rewritten from verbose upstream (1998 lines) to terse versions (642 lines, 68% cut), with all v0.8.1 functional features verified present.

Implementation

• Hook boilerplate collapsed: ~60-line per-file hook-checking sections → single terse line (Run hooks.before_X from .specify/extensions.yml if present)
• Example enumeration cut: per-technology lists in implement.md, good/bad tables in specify.md → 2-3 representative cases each
• Line limits added: spec.md ≤50 lines (specify), plan.md ≤60 lines (plan) — new output constraints
• Preserved: __SPECKIT_COMMAND_X__ markers, .specify/feature.json persistence, branch_numbering, checklist gate (implement), scripts frontmatter (sh/ps), constitution versioning rules

Curated CI Findings

#	Finding	Verdict	Fixed?	Reason
1	TestClaudeHookCommandNote::test_hook_note_injected_in_skills_with_hooks fails on all Python versions (3.11, 3.12, 3.13 × ubuntu + windows)	MUST FIX	No	Root cause: ClaudeIntegration._inject_hook_command_note() injects a dot-to-hyphen note by matching the regex - For each executable hook, output the following — verbatim from the old verbose boilerplate. The terse rewrite replaced that boilerplate with Run hooks.before_X from .specify/extensions.yml if present. The injection trigger never fires, so the note (replace dots (.) with hyphens (-)) is not added to any installed skill. Without it, Claude will not know to convert hooks.before_specify → /hooks-before-specify when executing extension hooks — a silent functional regression. Fix: update the regex in _inject_hook_command_note to also match the new terse hook format, or inject the note unconditionally when any hooks. reference is present.

New Issues (not caught by CI)

#	Issue	Fixed?	Details
1	Closes/Refs check	N/A	No Closes #N keywords — no premature issue-close risk

Tests After Fixes

• Suite: 1 failed / 1726 passed (across 6 Python/OS matrix combos — all fail on the same single test)
• Regressions: 1 regression introduced by the template rewrite — dot-to-hyphen hook note injection no longer triggered

Template Impact Assessment

All critical v0.8.1 features confirmed present in terse templates:

• ✅ __SPECKIT_COMMAND_X__ install-time substitution markers
• ✅ .specify/feature.json persistence (specify.md step 4)
• ✅ branch_numbering sequential/timestamp logic
• ✅ Checklist gate in implement.md (step 2)
• ✅ scripts: frontmatter with both sh: and ps: variants
• ✅ Constitution versioning/amendment rules
• ✅ Data templates (templates/*-template.md) correctly left untouched
• ❌ Dot-to-hyphen hook note injection (broken by trigger removal — see finding Remove auto-chain handoffs from pipeline phases #1)

Verdict

Needs one fix before merge. The structural trim is clean and well-executed. A single test failure points to a real functional regression: hook-based extensions won't work correctly after install because the dot-to-hyphen note is no longer injected. Fix _inject_hook_command_note to match the new terse hook line format (or inject unconditionally for any command template referencing hooks.). Once green, ready for merge.

[maxfindel]

CTO Review — tooling.cto

PR state at review: MERGED ✅

CI Assessment

Check	Result
markdownlint	✅ SUCCESS
ruff	✅ SUCCESS
CodeQL	✅ SUCCESS
pytest (ubuntu-latest, 3.12)	❌ FAILURE
pytest (other matrix)	⚠️ CANCELLED (cascaded)

Findings

MUST FIX (follow-up PR required)

TestClaudeHookCommandNote::test_hook_note_injected_in_skills_with_hooks fails because _inject_hook_command_note() triggers on the pattern "- For each executable hook, output the following" — removed by the terse rewrite. The new terse format ("Run hooks.before_X from .specify/extensions.yml if present") doesn't match the trigger, so the dot-to-hyphen note (replace dots (.) with hyphens (-)) is never injected into installed skills. Hook-based extensions break silently after install.

Fix options:

• Update the _inject_hook_command_note() trigger regex to match the new terse format
• Or inject unconditionally when any hooks. reference is present in the command

All else PASS

• 68% line reduction (1998 → 642) achieved as stated ✅
• All v0.8.1 functional additions preserved (__SPECKIT_COMMAND_X__ markers, .specify/feature.json, branch_numbering, checklist gate, scripts frontmatter) ✅
• No Closes #N misuse — correctly references pylot#239 without auto-close ✅
• Terse rewrite is directionally correct and well-reasoned ✅

Action

Please open a follow-up PR to fix _inject_hook_command_note() for the new terse hook format. The test is a real regression, not a stale assertion.