gsd-core-hooks
Skill6 starsChanged 33 days agoMITView on GitHub
A full PreToolUse/PostToolUse hook suite that machine-enforces a project's workflow rules instead of leaving them as prose — a passing test-runner verdict bound to the exact commit sha before push, no local `node --test`, blast-radius evidence (CodeGraph or Memtrace) required on a PR approval, no-defer artifact gating for long directives, and a family of guards against harness poll/timeout false-negatives (backgrounded dispatch, foreground poll-loop kills, self-matching pgrep waits, unpinned bench contention, double-dispatch). Use when an agent keeps skipping "ABSOLUTE"/"MANDATORY" rules in CLAUDE.md despite them being written down, when a CI/test gate needs to be unbypassable rather than self-attested, when local test runs are orphaning processes or leaving container relics, or when a long-running remote job's poll loop keeps dying against the harness's own timeout ceiling. Companion to `commands/` — those directives *describe* these rules in prose; this ships the mechanism that actually holds the line.
- Commits and pushes
In this repository79 other files it gives its agents.
- adr-phase-coverageSkill
- aposd-red-flag-reviewSkill
- apple-on-device-aiSkill
- artifact-gatesSkill
- asc-app-create-uiSkill
- asc-build-lifecycleSkill
- asc-cli-usageSkill
- asc-crash-triageSkill
- asc-id-resolverSkill
- asc-localize-metadataSkill
- asc-metadata-syncSkill
- asc-notarizationSkill
- asc-ppp-pricingSkill
- asc-release-flowSkill
- asc-revenuecat-catalog-syncSkill
- asc-shots-pipelineSkill
- asc-signing-setupSkill
- asc-submission-healthSkill
- asc-subscription-localizationSkill
- asc-testflight-orchestrationSkill
- asc-wall-submitSkill
- asc-workflowSkill
- asc-xcode-buildSkill
- choose-boring-technologySkill
- ci-preflightSkill
- conways-lawSkill
- cost-routingSkill
- cost-tier-routingSkill
- cunninghams-lawSkill
- ddd-strategic-auditSkill
- ddd-tactical-reviewSkill
- debug-test-captureSkill
- developing-ios-appsSkill
- doerrs-lawSkill
- fitts-lawSkill
- fix-regression-guardSkill
- galls-lawSkill
- goodharts-lawSkill
- greenspuns-tenth-ruleSkill
- hofstadters-lawSkill
- hyrums-lawSkill
- ios-accessibilitySkill
- ios-simulator-boot-healthSkill
- kerckhoffs-principleSkill
- kernighans-lawSkill
- knuths-optimization-principleSkill
- lady-lovelaces-objectionSkill
- leaky-abstractionsSkill
- linuss-lawSkill
- mobile-ios-designSkill
- money-boundary-judgmentSkill
- moores-lawSkill
- no-deferSkill
- norvigs-lawSkill
- parkinsons-lawSkill
- peter-principleSkill
- postels-lawSkill
- post-fix-traceSkill
- qa-test-architectSkill
- rubber-duckSkill
- The first 60 shown.
The file
We split this skill into the rules it gives an agent
1 rule. About 0 are common, 0 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 42
None of this is generic: Every script assumes gsd-core's specific toolchain: a remote dockerized test runner called gsd-test that emits a …
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
gsd-core-hooks
A rule an agent can read once and forget is not enforced — it's remembered, which is a different thing.
What this is
The .claude/hooks/ directory from one real project (gsd-core), lifted wholesale. Every file here
exists because a specific incident happened first and the hook was written afterward to close the
gap — the header comment on each script names the incident, the date, and the exact failure mode.
This is not a designed-in-advance framework; it is a project's actual scar tissue, in installable
form.
It backs the rules stated in ../commands/ (bug-fixer.md, feature-builder.md,
triage-review.md, test.md) — those files say things like "gsd-test MUST exit 0 before any git
push" and "NEVER run node --test locally"; the hooks in this folder are what make those true
regardless of whether the agent remembers reading them.
The three failure classes it guards against
- Self-attestation. "I ran the tests" / "the review passed" is cheap to claim and expensive to
check by hand.
pre-pr-gate.sh+record-gsd-verdict.shbind a push/PR action to a machine-read verdict line for the exact commit sha being shipped — not "tests passed at some point," but "tests passed for this sha, recorded by the one sanctioned writer, checked at the moment of push." - Prose that goes stale mid-session. A directive is read once, at the start, then hours of
tool calls go by with nothing re-presenting it.
gsd-phase-gate.cjsis the original, project-specific incident behind this project's separately-shipped../artifact-gates/engine — see the note in this folder'sREADME.mdbefore installing both. - Harness ceiling false-negatives. A backgrounded or foregrounded long-running dispatch dies at
the tool harness's own timeout (commonly 600000ms) with no distinguishing signal from a real
failure — and a
pgrep -f "<cmd>"waiter can match its own argv and spin forever even after the watched job finished.gsd-async-poll-guard.sh,gsd-foreground-poll-guard.sh,gsd-pgrep-waiter-guard.sh,gsd-bench-pin-guard.sh, andgsd-test-single-flight-guard.sheach close one verified instance of this.
Read this before installing
None of this is generic. Every script assumes gsd-core's specific toolchain: a remote dockerized
test runner called gsd-test that emits a {"type":"verdict","outcome":"passed"} line, a per-sha
pass-marker file under <git-common-dir>/gsd-passes/, CodeGraph (or Memtrace) as the graph tool whose blast-radius call
require-memtrace-evidence.sh audits, and
(in emitted-cjs-read-guard.cjs) a .cts → .cjs build pipeline specific to that repo. Installing
these unedited against a different project will produce confident denials referencing tools you do
not have.
Full per-hook breakdown, what each one assumes, and what to repoint: README.md.
When to reach for this vs. artifact-gates/
- Want the general "blocking step needs a produced artifact" engine, config-driven, with tests and
two example contracts? Use
../artifact-gates/. - Want to see the concrete, incident-driven version that engine was generalized from, or want the rest of this bundle (test-verdict gating, no-local-test, poll-loop guards) as a starting shape for your own project's hooks? Use this folder.
Installing both leaves two independent engines answering the same "was the artifact produced"
question for Edit|Write|Bash — pick one, or scope them to disjoint tool matchers.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

