CLAUDE.md

What this repo is

A plugin (bigin-skills) for Claude Code and Cursor — a collection of skills installed into other projects, not executed here. No build step, test suite, or dev server. All work is authoring markdown (and small guard scripts) in the right structure.

Structure

.claude-plugin/           ← plugin.json (version lives here) + marketplace.json
.cursor-plugin/           ← Cursor's manifests; declare paths into skills/ + agents/, no second copy
.claude/rules/            ← this repo's own path-scoped authoring rules
.claude/skills/           ← this repo's own user-only skills (harness-audit, skill-bench), never shipped
.claude/memory/           ← epic/plan/session state and archives
skills/<name>/SKILL.md    ← one skill per directory
skills/<name>/references/ ← supporting templates, relative to that skill
skills/<name>/evals/      ← should-trigger cases; docs_sync.mjs --check fails closed without one
skills/<name>/scripts/    ← that skill's own executables (13 skills have one), cited via ${CLAUDE_SKILL_DIR}
agents/<name>.md          ← plugin-level subagent definitions (spawned via Agent tool, not invoked as skills)
hooks/                    ← the plugin's own hooks, never templated into a repo: a SessionStart notice
                             for unapplied harness patch blocks
docs/                     ← hand-maintained deep-dives, indexed in README; docs/polyrepo/ is the six-repo standard
site/src/                 ← site sources: pages/ + _layouts/ + _partials/ + assets/
site/dist/                ← generated by tools/site_build.mjs, committed, published to bigin-skills.pages.dev
tools/site_build.mjs      ← the site build; --check fails the commit when dist/ is stale
tools/context_budget.mjs  ← budget gate (also templated for target repos)
tools/docs_sync.mjs       ← generates README's skills/agents tables; --check fails the commit on drift
tools/docs-manifest.json  ← its input; every new skill and agent needs an entry or --check fails closed
tools/regress.mjs         ← regression suite: manifests, inventory, detection, scaffolders, sync
                             scripts, guards, this release's patch blocks; --build adds a real
                             install+build of a scaffolded site
scripts/git-hooks/        ← pre-commit running the budget gate + docs_sync.mjs --check + site_build.mjs --check + regress.mjs
                             against the staged tree
.gitattributes            ← LF everywhere; the gates also normalise CRLF on read

Every skill's description: frontmatter is already loaded on every turn, so there's no inventory table here — the generated skills/agents tables live in README.md, and each SKILL.md covers how that skill works. Authoring conventions: .claude/rules/skill-authoring.md (loads when editing skills/ or agents/).

Gotchas

• A skills/*/SKILL.md description: is always-loaded context for every session in every repo that installs this plugin. The budget gate caps it at 350 chars.
• Most references/*.md under bigin-harness-setup template content written verbatim into target repos — hook-guard.md (the guards + commit scripts), knowledge-bundle.md, knowledge-migration.md (by patch block only), profile-*.md except profile-detection.md, ci.md, cursor-parity.md, graph.md, budget-gate.md, files-shared.md. The rest are the skill's own procedure and are never copied. summary-checklist.md is mixed — its ## Phase 6 README Templates section is appended verbatim to the target repo's README.md; the rest is procedure. Changing a templated one wants a CHANGELOG patch block, or already-scaffolded repos only get the change on a full re-run.
• Generated AI_TASK_GUIDE.md is deliberately just a pointer to task-workflow. Don't grow it back into a second copy of the workflow — that's how the two drifted before.
• The guard scripts in references/hook-guard.md are load-bearing, and one body serves both Claude Code and Cursor via lib/hook-io.mjs — never fork a guard per host. .claude/rules/skill-authoring.md lists the exact cases each one must still block and allow, on both payload shapes.

Versioning

Version lives in .claude-plugin/plugin.json and is the source of truth for the version in two other manifests (.cursor-plugin/plugin.json, and two fields in .cursor-plugin/marketplace.json) — four fields in three files, bumped together; docs_sync.mjs --check fails the commit on a mismatch. .claude-plugin/marketplace.json carries no version field, so nothing there can drift. Bump when publishing changes and add a CHANGELOG.md entry. Docs-only passes are exempt — copy edits, restructuring, link fixes: ship them as a docs: commit with no bump and no changelog entry, and let the commit message be the record. Before a major or minor bump, find and fix all stale docs first — the skills/agents tables in README.md are generated (run node tools/docs_sync.mjs), so sweep only the remaining manual surfaces: prose, cross-references, this file's own Structure tree, SKILL.mds, docs/, site/src/pages/ (counts and the version there are generated — only the prose is manual), and both marketplace.jsons. Patch bumps don't require this sweep. Pre-commit gates: activate once with git config core.hooksPath scripts/git-hooks (runs the budget gate + docs_sync.mjs --check + site_build.mjs --check + regress.mjs --skip-gates). node tools/regress.mjs runs the suite standalone, gates included. --build (group 9) is opt-in — network, ~3 min — and asserts one prerendered entry point per locale: run it for any change to nuxt-marketing-scaffold's templates, manifest or substitution map, since nothing cheaper proves that scaffolder's output compiles.

Session Handoff

When approaching usage limits, use the session-handoff skill to save state to .claude/memory/SESSION.md. On session start, if found with status: in-progress, prompt to resume or start fresh.