Kit Reference

This page indexes every file in the Agent Team Kit: the scripts you run, the hooks, the skills, the snippets for CLAUDE.md, the docs, the hub tooling, and the memory pack, each with a one-line description and a link to it on GitHub. The column “Installed?” says whether install.sh copies the file into your repo. How the pieces fit together is on The Agent Team Kit and From Spec to Release.

Scripts you run

File	What it does	Installed?
install.sh	Wires the kit into a repo: copies hooks, skills, launchers, and build specs; appends to .gitignore and CLAUDE.md; seeds team memory; sets core.hooksPath. Safe to re-run	Run from the kit
bootstrap.sh	A teammate’s one-time setup after cloning: sets core.hooksPath, restores exec bits, checks Node and the settings file	Yes, repo root
worktree-commands.sh	The launchers: cs <name>, wt <name>, cockpit, wtls. Source it from your shell	Yes, repo root

Claude Code hooks

Installed to scripts/hooks/ and wired by .claude/settings.json. Per-hook detail is in HOOKS.md.

File	Event	What it does
hooks/settings.json	(wiring)	Registers the hooks below; installed as .claude/settings.json unless one exists
dev-port.mjs	SessionStart	Claims a free dev-server port for this session from a pool, skipping the human’s port, and tells the session how to start on it
team-memory.mjs	SessionStart	Links the tracked .claude/team-memory/ files into this session’s memory and writes their index lines into MEMORY.md
bash-guard.sh	PreToolUse (Bash)	A shell-only filter that passes harmless commands and sends possible matches to bash-guard.mjs
bash-guard.mjs	PreToolUse (Bash)	Git safety, the commit-sweep guard, the schema lock, and the psql DDL block
file-size-nudge.mjs	PostToolUse (Edit, Write)	Tells the agent at once when an edit breaks an architecture guard
session-release.mjs	SessionEnd	Frees this session’s port claim and schema lock
agent-coord.mjs	(helper)	Shared code: reads the hook payload, finds .git/.wg-agent/ through the common git dir, detects a linked worktree
file-size-budget.mjs	(config)	The file-size ratchet: BUDGET, FROZEN, EXEMPT, isGoverned
import-boundaries.mjs	(config)	The import-boundary guard: RESTRICTED_RE, ALLOWLIST
arch-check.mjs	(CLI)	Runs both architecture guards on the files given, or on all of src/; used by pre-commit and in CI

Git hooks

Installed to .githooks/; git runs them once core.hooksPath is set.

File	When	What it does
post-merge	After a pull or merge	Lists migration files that just arrived and the commands to apply and check them
pre-commit	Before a commit	Runs the architecture guards on staged files, with a slot for your formatter or linter. Not copied if you already have one
pre-push	Before a push	Runs CHECK_CMD and TEST_CMD (typecheck and tests, plus @critical end-to-end tests). Not copied if you already have one

Skills

Installed to .claude/skills/. Per-skill detail and how to write your own are in SKILLS.md. Several come from one real project, so their paths and table names are placeholders to adapt.

Skill	What it does
spec	Turns an exploration into .specs/<slug>/spec.md and a punch list, every criterion tagged walk, unit, or structure, then stops for approval
spec/TEMPLATE.md	The spec template, including the required Access and release section
build-spec	Works an approved punch list one committed item at a time and closes each criterion by its check; writes check.md for the browser checks
mockup	A throwaway, high-fidelity mockup in .mockups/, edited from a frozen copy of the real page, or a clickable multi-screen prototype with a numbered storyboard
push	Cuts a release (notes, version bump, commit) and pushes; the only sanctioned push
stage	Puts a release candidate on staging: migrate staging, check parity, tag -rcN, push atomically, watch, smoke-test the commit
promote	Ships to production exactly the commit staging is serving, even if main has moved on
remove-flag	Takes a release flag out of the code once it is on for everyone, in one commit
merge-worktree	From the cockpit, merges a worker’s branch into main, stops on conflicts, prunes the worktree, never pushes
share-memory	Promotes a personal memory into .claude/team-memory/, scrubbed of secrets, customer data, and names, and commits it
regression-check	Before finishing a change to shared code: map every caller, judge each affected feature, add behavior tests
fix-bug	Loads an in-app bug report by id from the database and fixes it only after reproducing it
ux-critique	Drives a flow in a real browser, compares each step with what a user would expect, files the gaps as bug reports
userflow-map	Maintains a data-driven map of the app’s screens and transitions, with issues flagged by screen

Snippets for CLAUDE.md and .gitignore

File	What it is	Installed?
CLAUDE-md-main.md	“Concurrent agents on main”: the stay-on-main rules	Appended
CLAUDE-md-worktree.md	The worktree-mode version of that section; use it instead of the one above	No
CLAUDE-md-working-discipline.md	The definition of done: green checks, regression pass, diff review, real build, verify in proportion to risk	Appended
CLAUDE-md-mockups.md	Mockups in gitignored .mockups/, a clickable link, desktop and mobile by default	Appended
CLAUDE-md-release-flags.md	Release-flag rules, for once the project has flags	No
CLAUDE-md-access-model.md	Who sees what: this project’s roles, entitlements, preferences, and capability function, to fill in	No
gitignore-additions.txt	The .gitignore lines that share settings, skills, and team memory and ignore .mockups/ and .specs/	Equivalent lines appended

Docs

Doc	What it covers
README.md	Overview, the two-mode decision, setup, and the collaboration model
ADOPT.md	Start here to install: prerequisites, the no-nesting install, and three adoption paths
SETUP-PROJECT.md	Owner install reference: the settings to change per stack, what is tracked, how to verify
SETUP-COLLABORATOR.md	Joining a repo that already has the kit
WORKTREE-MODE.md	Worktree mode: the feature-by-feature comparison, the launchers, the integration loop
TENDING-AGENTS.md	Verbose mode, Remote Control, and keeping a Mac or Windows machine awake
HOOKS.md	Every hook and git gate: what it does, why, what to change, its limits
SKILLS.md	Every skill, the pattern each one teaches, and how to write your own
WRITING-CLAUDE-MD.md	The sections worth having in a project’s CLAUDE.md
CONVENTIONS.md	Transferable repo conventions: scratch files, formatting, secrets, commits, release flags, verification
HUB-AND-SPOKES.md	One neutral launch folder per project, with content mounted by --add-dir
DRIVING-THE-APP.md	Screenshots, recorded walkthroughs, and driving the app as a user to verify it
HANDS-ON-EDITS.md	Editing by hand: jumping from a page element to its source, and committing one file safely from an editor
DISPOSABLE-ENVIRONMENT.md	Where agents drive: a wipeable copy, stubs as a separate setting, guards against reaching production
RELEASE-PIPELINE.md	Push runs CI, an -rc tag deploys staging, a final tag deploys production; the two roads
STAGING-TWIN-SPEC.md	Build spec: staging as production’s twin, with a parity check, a data slice, and an egress fence
RELEASE-FLAGS-SPEC.md	Build spec: ship dark, release by audience from an admin page, remove the flag when done; the six levers
MOCKUP-SHELLS-SPEC.md	Build spec: freeze a real page into one editable HTML file for mockups, and build a clickable prototype of every screen (mock:flow, mock:serve)
FEEDBACK-LOOP-SPEC.md	Build spec: the in-app feedback widget, inbox, /fix-bug hand-off, and close-on-commit hook
SIDEBAR-SPEC.md	Build spec: a collapsible left navigation rail, with the version chip and release notes push updates
IMPERSONATION-SPEC.md	Build spec: “View as” any user or role, enforced on the server, read-only by default, audited
CRAWLERS-SPEC.md	Build spec: route, form-action, and browser crawlers that find errors on a disposable copy
WALKS-AND-SWEEPS-SPEC.md	Build spec: scripted browser walks of a journey and sweeps that click every control, filed as bug reports
DESIGN-NOTES.md	The reasoning behind each piece
ORIGIN-CONVERSATION.md	A redacted account of the working session the kit was designed in

The installer copies seven of these into your repo’s docs/: the feedback loop, sidebar, mockup shells, release pipeline, staging twin, and release flags specs, and the driving-the-app guide.

Hub tooling

Run from a clone of the kit, once per machine. See HUB-AND-SPOKES.md.

File	What it does
hub/README.md	Quick start and defaults for the hub tooling
hub/install-hub.sh	Creates ~/hubs, installs the dispatcher and template, adds a hub alias to your shell
hub/hub	The dispatcher: hub ls, hub new <name>, hub <name>
hub/_template/launch	A hub’s launch script: list SPOKES, launch from the hub; permission prompts on by default
hub/_template/CLAUDE.md	A hub’s routing map, to fill in

Memory pack

install.sh copies the pack into .claude/team-memory/, and the team-memory.mjs hook loads it into every session. Each file is one lesson with Why and How to apply.

File	What it is
memory-pack/README.md	What the pack is and how to adopt it, with or without team memory
memory-pack/MEMORY.md	The one-line-per-memory index
memory-pack/TEAM-MEMORY-README.md	Becomes .claude/team-memory/README.md in your repo

The 32 lessons:

Memory	The lesson
never-amend-on-shared-main	No --amend or rebase on a shared branch; a sibling may have moved HEAD
commit-pathspec-uses-working-tree	git commit -- <path> commits the working tree of that path, not what you staged
format-only-touched-files	Never format the whole repo; format the files you touched
sequential-ids-collide-in-parallel	Parallel agents take the same next number for migrations and fixtures
run-your-own-dev-server	Never trust the default port; run your own, read the real port, stop only your process
verify-with-the-real-build	A typecheck can pass while the build fails; build before pushing import changes
verify-proportional-to-risk	Typecheck trivial changes; run behavior and layout changes in the browser
keep-a-small-green-critical-suite	Test the existing behavior a change could break; gate a small @critical suite before push
develop-against-a-disposable-copy	Once real users exist, local development never points at the production database
subtraction-audit-on-redesign	When a redesign replaces a surface, delete what it made obsolete in the same change
throwaway-mockups-gitignored	High-fidelity HTML mockups in a gitignored folder, shared as a file:// link
ai-surface-full-lifecycle	Every AI-working surface needs start, live progress, and stop
ai-status-motion-one-system	Put all “working” indicators on a few shared components
every-mutating-button-gives-feedback	Instant press plus an in-flight state that replaces the label and disables the button
arch-guards-as-alarms	A red guard is a prompt to check whether the file still does one job
design-first-then-verify	Show the tradeoffs and a quick mockup before building; verify honestly
communicate-direct-and-plain	Answer first, short reason, plain drafted copy
no-em-dashes	No em dashes in copy, comments, commits, notes, or replies
commit-freely-never-push	Commit each unit of work without asking; the owner decides when to push
real-icons-not-emoji	Use the project’s icon set in the interface, never emoji
deploy-is-not-release	A push runs CI, a tag deploys, a flag releases to an audience
promote-the-staged-commit	After a rehearsal, ship exactly the commit staging served, read from staging itself
staging-is-a-twin-not-a-demo	Same build and configuration as production, differences on a list a parity check enforces
fence-outward-writes-at-one-chokepoint	Every outbound write through one helper with allowlists, and a test that fails on any bypass
check-before-flagging-a-shipped-feature	A new flag with no audience hides a live feature; set the audience before the deploy
check-a-secrets-shape-never-print-it	Diagnose a credential by its length and characters and a harmless test call; never print it
decide-the-release-at-spec-time	The spec names kind, key, seam, whose flags, off path, and rollout; a flagged build reports “shipped dark”
flag-or-staging-is-whose-data	A flag controls who; rehearse deploy-time changes, and per-request ones only if the first audience could harm outsiders irreversibly
branch-once-at-a-seam	One flag check at one seam, a plain if/else, off returns nothing new
env-flags-are-for-what-stays	Environment variables hold kill switches, stubs, and configuration; rollouts are release flags
removing-a-flag-check-silent-callers	Before deleting the off branch, read deployed config and find callers that omit the flag
pick-the-lever-by-lifetime-and-owner	Release flag, kill switch, role, entitlement, or preference, chosen by how long it lasts and who changes it