The 50-page PRD HTML totals ~520KB; loading it all costs Claude ~222K
tokens just for context. This adds a token-efficient sibling layer:
- scripts/extract-spec.js → npm run spec:extract / spec:check
Walks docs/prd/newfunction/*.html and produces stripped MD into _spec/.
Strategy varies per page (full-extract for SDD/process/data,
shell-strip for agents to keep long system prompts intact).
Result: 327.9KB MD (~84K tokens) — 38% of full load, saves ~138K tokens
for every Agent invocation that reads the spec.
- scripts/git-hooks/pre-commit + scripts/install-hooks.sh
Pre-commit guard: when any docs/prd/newfunction/*.html changes, the
hook checks the corresponding _spec/*.md is up to date; fails commit
if stale, telling user to `npm run spec:extract`. Auto-installed via
package.json `prepare` script on `npm install`.
- docs/prd/newfunction/_spec/ (51 .md files + CONVENTIONS.md)
Machine-readable mirror of HTML. Used by:
- Coder/Architect/Tester agents when reading spec at runtime
- External Claude Code sessions doing reproducibility
- CI checks (npm run spec:check)
NOT hand-edited; regenerated from HTML by extract-spec.js.
- CLAUDE.md: 1-line note directing future agents to read _spec/*.md
preferentially, fall back to *.html only for wireframes/SVG/full
human-readable context.
This is the user's pre-existing scaffolding that the previous commits
hadn't pulled in yet. Now tracked + enforced by hook.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
