agentic-kit

A starter kit for running coding agents (Claude Code) autonomously and safely — built on one hard-won lesson: a convention that competes with the task gets skipped unless it's mechanically enforced.

Observed live, on a real project: the merge-time pull request — forced by a protected branch — was followed 100% of the time. The identical claim-your-work-before-you-start step, only written down in a rules file, was followed 0%. Same model, same instructions. The difference was the gate.

So this kit turns the things that matter into hooks, not prose:

Hook (event)	What it does
claim-guard.js (PreToolUse)	Denies the first edit on a work branch until you've opened a Draft PR claiming it. .claude/ and the default branch are exempt; fails open if GitHub is unreachable.
check-readfile-secrets.sh (PreToolUse)	Blocks reads of secret/credential files (.env, private keys, credentials.*) into model context. Reference secrets by handle; fails open if jq is missing.
memspec-reflect-gate.js (Stop)	If a session did real work but wrote nothing to project memory, blocks the first stop once and asks you to record it — or to say why nothing's worth recording.
memspec-session-start.js (SessionStart)	Pushes the most relevant active memories into the opening context (memspec context) — the static top-N that prompt-search then extends per turn.
memspec-prompt-search.js (UserPromptSubmit)	Pulls keywords from each prompt, searches project memory, and injects the matches as task-relevant context — at the moment the task is stated.
inject-rules.js (SessionStart)	Injects a compact index of .claude/rules/ so a fresh session knows the binding rules exist, without dumping 30 KB.
peer-claim-awareness.js (SessionStart)	Surfaces other agents'/humans' open PRs so you coordinate instead of overwriting.
reconcile-awareness.js (SessionStart)	Surfaces your own uncommitted work and unmerged agent/* branches so a returning session reconciles instead of re-deriving. Also ages out expired memory (memspec decay).
memspec-session-baseline.js (SessionStart)	Records the start-of-session commit so the reflect gate can scope "what did this session do."
provenance-log.js (PostToolUse)	Appends a redacted one-line audit trail of every mutating tool call to .claude/agent-activity.jsonl.

Every hook fails open: if a tool is missing or errors, the session continues. The gates nudge; they never brick a session.

An optional global layer (global/) adds memspec-central-sync.js — a Stop hook that auto-commits and pushes a shared cross-repo memory store on session end, secret-scanning the diff first. Install it only if you want a "team brain" shared across all your repos. See global/README.md.

What's inside

.claude/
  settings.json          # wires all the hooks
  scripts/               # the hooks above + agent-claim.sh
  commands/              # /claim, /verify, /meta-reasoning
  rules/
    common/              # multi-agent-coordination, agent-memory, security  (always-read)
    ai-tools/            # git-commands, project-context                      (always-read)
    examples/            # sample language pack to copy
  skills/                # code review, simplifier, quality/security checks, diagrams, etc.
.memspec/                # project memory (memspec) — config + markdown, in git
.mcp.json                # registers the memspec MCP server
CLAUDE.md                # routing-table template — adapt it to your project
docs/                    # PHILOSOPHY.md and SETUP.md
global/                  # OPTIONAL: cross-repo "team brain" — central-sync Stop hook

Coordination model

Work is claimed as a GitHub Draft PR on an agent/<slug> branch — visible to every concurrent agent session and every human:

.claude/scripts/agent-claim.sh wire-up-search "wire the search endpoint"

This is reversible and tiny in blast radius (a draft branch + a draft PR; never a merge, never the default branch), so agents run it autonomously. The claim-guard.js hook makes it non-optional once you start editing.

Uses GitLab instead? The two coordination scripts (agent-claim.sh, claim-guard.js) are thin wrappers over the gh CLI — swap gh pr for glab mr and you're done.

Memory model

Durable knowledge lives in memspec — file-canonical memory for agents, kept under .memspec/ in git (no vendor backend). Facts/decisions/procedures are searchable, decay over time, and are surfaced into sessions by the hooks above. Architectural decisions belong in decision records (e.g. docs/decisions/); memspec links to them, never copies them.

Quick start

Prerequisites: Claude Code, Node.js (for the hooks), the GitHub CLI (gh auth login), memspec (memspec + memspec-mcp on PATH), and jq (optional — only for the secret-read guard).

# 1. Copy the kit into your repo (or start a new repo from it)
cp -r agentic-kit/. your-project/   # brings .claude, .memspec, .mcp.json, CLAUDE.md

# 2. Initialise project memory
cd your-project && memspec init      # if not already initialised

# 3. Edit CLAUDE.md — replace the [bracketed] bits with your project's reality

# 4. Protect your default branch (PR-only, require green CI) on GitHub.
#    The gate is the safety; the hooks assume it exists.

Then open Claude Code in the repo. The SessionStart hooks fire immediately; the claim gate engages the first time you edit a file on a work branch.

See docs/SETUP.md for the full walk-through and the env-var toggles (CLAIM_GUARD_OFF, MEMSPEC_REFLECT_OFF, …), and docs/PHILOSOPHY.md for the reasoning behind every gate.

Credits

This kit operationalizes two pieces of work by Siim Vene (@siimvene):

• memspec — the file-canonical agent-memory layer the kit's memory hooks build on.
• the Trust Equation — Trust = (Observability × Reversibility × Blast Radius) / Autonomy (S. Vene, Agent-Enhanced Platform Engineering, after Mayer et al. 1995) — the coordination doctrine the gates implement.

The hooks, gates, mechanical enforcement, rules, and overall structure — turning that doctrine into controls an agent can't skip — are my own work.

License

MIT — see LICENSE.