A Claude Code subagent team for GitHub Spec Kit, with the rules enforced by hooks.
Install · Quick start · The team · How it works · The fast track · Board mod · Troubleshooting
A team of eight Claude Code subagents that carries a
feature through GitHub Spec Kit, from idea to pull request.
Six of them each own one phase. Hooks, not prompt text, keep
each one in its lane: the planner cannot write code, the implementer cannot touch tests, and
nobody writes code until an independent auditor has passed the spec. The seventh, patcher, is a
fast track beside the pipeline for a change of at most 30 production lines in 2 files
(/speckit-patch), with no spec, plan or audit; hooks keep it inside that budget too. The eighth,
security-reviewer, joins a run only when asked (/speckit-team --security).
idea ─► product-owner ─► architect ─► spec-auditor ─► per round: stubs─► red ─► green ─► spec-gatekeeper ─► PR
spec.md plan.md VERDICT: implementer test-writer implementer APPROVED /
+ questions tasks.md PASS / FAIL │ REJECTED
▲ ▲ │ │
└── you answer └── findings routed back on FAIL ◄── 3 REDs in a row ──┘
- One agent per phase. product-owner specifies, architect plans, spec-auditor audits, test-writer and implementer build test-first, spec-gatekeeper checks the result. Each one's phase instructions are Spec Kit's own skill. (The team)
- Lanes are hooks, not requests. A
WriteorEditoutside an agent's lane is denied before the file exists, and so is a Bash command that writes there (>,rm,sed -i,git checkout --); the denial tells the agent whose lane it is in. A change made through Bash that the hook cannot read, such as a script's own writes, is caught when the agent stops. (Guardrails, The lane check) - No code before the audit. A PASS is tied to a SHA-256 fingerprint of the constitution, spec, plan and tasks, and any edit to them other than ticking a task voids it. (The audit gate)
- Test-first, one round at a time. Stubs, then tests shown failing on an assertion, then the code that turns them green. (Building in slices)
- A retry limit. After 3
RESULT: REDreports in a row, implementer is denied every tool but reporting back, and the way forward is a revised plan and a new audit. (The retry limit) - You decide at four stops, and you merge. The pipeline asks which team to use, then asks you to answer the spec's questions, approve the spec, and approve the plan, then stops at the pull request. (Quick start)
- Or no agents at all.
/speckit-team --team noagents <request>runs Spec Kit's own commands in your session, with the spec and plan stops and no audit; only your typed flag turns the audit gate off. (Choosing the team) - A fast track for small changes.
/speckit-patch <change>launches one agent,patcher, with a budget of 30 production lines and 2 files, protected paths it cannot write, and no commit of its own: the main session commits its files, and opens the PR, only after an end-of-run hook check accepts the run. (The fast track) - Free everywhere else. Installed once for your user; in a repo without
.specify/every hook exits immediately and allows the action. (Guardrails)
- Getting started
- What it looks like
- The team
- Why This Architecture Succeeds
- Two modes, two sources
- How it works
- Customising
- Board mod (experimental)
- Verifying
- Troubleshooting
- Known limits
- Uninstall
- Developing
- Publications
| Tool | Why | Check |
|---|---|---|
| Claude Code | runs the agents. Needs subagent frontmatter hooks: and skills:, and the UserPromptExpansion hook event (verified on 2.1.291); for --team skill-agents also skill frontmatter hooks: and a model-invoked skill with user-invocable: false (verified on 2.1.310); the omitClaudeMd agent field for the read-only agents to start without your CLAUDE.md (verified on 2.1.293 and 2.1.310) |
claude --version |
| Node 22+ | every hook is a Node script, run as node from your PATH; setup.sh, setup.ps1 and install.mjs refuse an older one by name. 22 since #223: CI tests that version, and 18 and 20 are past end of life |
node --version |
| git | the hooks use it to find the repo and diff an agent's work | git --version |
Spec Kit (specify) |
per repo, provides the phase skills | specify --version (verified on 0.8.11, 1.1.2 and 1.2.5) |
| uv | installs Spec Kit, a Python tool; nothing in this repo runs on it | uv --version (verified on 0.11.14) |
uv is not preinstalled on macOS or Windows. Install it, then Spec Kit:
# macOS (or: brew install uv) and Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows, in PowerShell (or: winget install --id=astral-sh.uv)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
uv tool install specify-cli --from git+https://github.com/github/spec-kit.gitSpec Kit needs Python 3.11 or newer; uv downloads one if the machine has none. Open a new
terminal after installing uv so uv and specify are on PATH.
git clone https://github.com/PIsberg/speckit-agents.git && cd speckit-agents
./setup.sh # macOS, Linux, Git Bash
powershell -ExecutionPolicy Bypass -File setup.ps1 # Windows PowerShell
node install.mjs # anywhere Node runsImportant
Restart Claude Code afterwards: agents are loaded at session start.
The installer puts everything in your user-level Claude Code directory ($CLAUDE_CONFIG_DIR, or
~/.claude), so the team is available in every repository:
| Installed file | What it is |
|---|---|
agents/{product-owner,architect,spec-auditor,test-writer,implementer,spec-gatekeeper,security-reviewer,patcher}.md |
the eight subagents |
skills/speckit-team/SKILL.md |
the /speckit-team command that runs the pipeline |
skills/speckit-patch/SKILL.md |
the /speckit-patch command that runs the fast track |
skills/speckit-triage/SKILL.md |
the advisory /speckit-triage command: suggests which of the two to use, runs nothing |
skills/speckit-role-<role>/SKILL.md |
seven role skills, one per team role, generated from agents/<role>.md for --team skill-agents; user-invocable: false, so only that mode calls them |
hooks/speckit-team.mjs |
every guardrail |
hooks/speckit-agents.install.json |
what the installer added (for --uninstall), and the version and build it stamped on every file it wrote (#230) |
hooks/speckit-drift.mjs |
the drift check the hook runs at spec-gatekeeper's APPROVED (#228); tools/drift.mjs runs the same file |
settings.json |
four hook entries merged in (PreToolUse, UserPromptExpansion, SubagentStart for the eight agents to record start and inject project context, and PostToolUse on Agent to relay what a subagent's hooks said, #231), and one allow rule for the exact line the fast track puts before patcher's commands (What the hooks stop); your other settings, hooks and permissions are kept |
| Flag | Effect |
|---|---|
--dry-run |
print what would change, write nothing |
--force |
replace same-named agents you wrote yourself (each is kept as *.bak-speckit-agents and put back on uninstall) |
--claude-dir DIR |
install into DIR instead of ~/.claude |
--uninstall |
remove everything the installer wrote, and nothing else (Uninstall) |
--board |
also install the experimental board mod; later reruns keep it |
--no-board |
remove the board mod, only if the installer installed it, and keep the team |
--no-fork |
write "CLAUDE_CODE_FORK_SUBAGENT": "0" under env in your settings.json, so the team's agents run in the foreground in every project (Foreground launches); only where no value is set, and later reruns keep it |
--fork |
remove what --no-fork wrote; a value you set yourself stays |
Any other argument is refused before anything is written, so a mistyped --dryrun stops with an
error instead of installing for real.
--team is not an installer flag: it is the first word of a /speckit-team request (Choosing the team). node install.mjs --help lists it after the flags, under its own heading with the other slash commands.
There is no flag for the fast track: patcher and its two skills are always installed.
- Idempotent. Rerun it after pulling changes.
- In place. It changes
settings.jsonin place, keeping the file's own indentation and line endings, and updates its gate entries where they stand, so a rerun after another tool re-sorted the file changes nothing. - One backup. The first time it changes your settings it keeps one copy of the original as
settings.json.bak-speckit-agents. - Validates first. It refuses to touch a
settings.jsonthat is not valid JSON or not a settings object (an array, ahooksentry that is not a list of objects, apermissionsthat is not an object or apermissions.allowthat is not a list), and stops before writing anything. - Keeps a record. It records what it created in
hooks/speckit-agents.install.json. - Checks PATH without running anything. It warns when
git,claudeorspecifyis not on PATH, by looking for the file. Running each with--versiontook 548 of an install's 750 ms on Windows, forspecifyalone; an install now takes about 150 ms. - Smoke-tests the hook. It finishes by running the installed hook once, so a broken Node setup fails the install instead of silently disabling the guardrails.
In a repository:
specify init --here --integration claudeNote
Keep --integration claude: without it, Spec Kit asks which assistant to set up, or, when it
cannot ask, sets up GitHub Copilot, and the team then finds none of Spec Kit's skills. Spec Kit
0.10 removed the older --ai claude spelling.
On Spec Kit 1.x you can add --extension git to have Spec Kit name and create each feature
branch; without it, /speckit-team creates the branch itself after the spec is written. (Spec Kit
0.8 installs that extension by default and rejects the flag.)
Then, in Claude Code:
/speckit-team Let users export their reading list as CSV
To ground the run in standing project rules, pass --project <name>: /speckit-team --project billing Let users export their reading list as CSV activates .specify/projects/billing/ (Project knowledge).
To run only some of the roles, name them: /speckit-team --team test-writer,implementer add a hello.txt that says hello skips the team question (Choosing the team). To run no agent
at all, /speckit-team --team noagents <request> has the session run Spec Kit's own commands
itself, with the spec and plan stops and no audit.
Start it in a fresh session (/clear first): every response of the run re-reads the conversation,
earlier work included. In the 004 run that earlier work was 2.73M of the main session's 8.92M
(Feature 004).
/speckit-team runs the whole pipeline from the main session. It stops for you at four points:
- to choose the team, unless
--teamnames it: the full team, build only, implement only, or spec and build with no audit; - to answer the product owner's questions;
- to approve the spec;
- to approve the plan and tasks. If
tasks.mdhas two or more[P]slices that touch disjoint files, this stop also asks whether to build them side by side or one at a time.
In a repo whose constitution (the rules every phase is checked against) is still Spec Kit's
template, it first drafts one from what the repo already states (CLAUDE.md, the build file, CI)
and asks you to approve it, a further stop, then writes it with speckit-constitution and commits
it on the feature branch, not on main. You can still run /speckit-constitution yourself
beforehand.
After that it audits, then builds the feature in rounds of up to 4 slices (stubs, failing tests,
code), small phases of tasks.md sharing one, verifies and opens a PR, which it does not merge.
For a typo, a config value or a small bug fix, skip the pipeline:
/speckit-patch Fix the typo "recieve" in README.md
/speckit-patch --project billing Fix rounding on tax calculation
/speckit-triage Add a --json flag to the export command
/speckit-patch creates the branch patch/<slug> and launches patcher once. The hooks hold it
to 30 production lines in 2 files (tests and docs are not counted) and keep it out of protected
paths such as specs/, .specify/, .claude/ and .github/. patcher ends with one of three
words: DONE (the existing tests passed), FAILED, or ESCALATE (over budget or in need of a
protected file: the work stays uncommitted and /speckit-team is the way on).
Who commits: patcher never does. After DONE and an end check that accepts the run, the main
session commits the files patcher changed, pushes the branch and opens a PR, which it does not
merge. A run in which patcher changed no file commits nothing and opens no PR. Files you had
uncommitted before the run are left out of the commit.
/speckit-triage <request> only prints one line suggesting /speckit-patch or /speckit-team;
it launches nothing and you type the command. How the budget and the checks work:
The fast track.
You can also run one phase at a time by @-mentioning an agent:
@agent-spec-auditor audit the active feature
@agent-implementer do T007 and T008
Real sessions in a scratch Spec Kit repo, the main session on Haiku
(record.mjs now puts every agent on Haiku too; before
#39 they ran on their own models), so your
runs will word things differently. The three recordings that wait on agents are sped up 2x or 4x.
node docs/media/record.mjs records them again (see
Recording the demo media).
Typing @ lists the agents Claude Code knows, each with its description, after the repo's
folders. Claude Code stops the list at 15 entries. In the recording below (Claude Code 2.1.302,
2026-10-17) it shows six of the team's eight agents among Claude Code's own five: spec-gatekeeper and
test-writer, last in alphabetical order, are left out. Claude Code 2.1.295 removed the /agents menu
this section used to show.
@agent-spec-auditor audits a feature inside the main session: the collapsed progress view, the
full transcript with Ctrl+O, then the VERDICT: it hands back, which a hook records for the
implementation gate. Recorded on 2026-10-17 (Claude Code 2.1.302) with CLAUDE_CODE_FORK_SUBAGENT=0
and a prompt asking for run_in_background false: with fork subagents on, an interactive session's
default, the agent runs in the background and reports as a message instead
(Foreground launches). On the demo feature it returns VERDICT: FAIL.
architect is told to write src/greet.js. Its scope hook denies the write before the file exists,
and the denial tells the agent whose lane production code is in.
/speckit-team first asks which team to use, the team question, the first of the pipeline's four
stops (the demo answers it with the full team). It then launches product-owner, which writes the
spec and returns its questions, and the main session puts product-owner's questions to you: the
second. Recorded on 2026-10-17 (Claude Code 2.1.302) with the idea "Let greet say hello in the
user's own language": product-owner, in the background as in any interactive session with fork
subagents on, wrote specs/002-localized-greeting and returned two questions. Haiku's first call to
ask them failed on an empty second question ("Invalid tool parameters"), and it asked again.
| Agent | Spec Kit phase | May write | Hands over | Model |
|---|---|---|---|---|
product-owner |
specify, clarify | specs/, .specify/feature.json |
spec.md and up to 5 questions with recommended answers |
sonnet |
architect |
plan, tasks | specs/, CLAUDE.md |
plan.md and tasks.md, plus research.md, data-model.md, contracts/ or quickstart.md only when the feature has something for them: the minimal design that meets the spec, each fact said once |
opus |
spec-auditor |
analyze | nothing | VERDICT: PASS or FAIL; FAIL only on CRITICAL or HIGH findings, MEDIUM and LOW are listed and accepted |
opus |
test-writer |
TDD red | test files, tasks.md |
committed tests, each shown failing on an assertion, never on a parse, import or compile error; the report ends RED, or BLOCKED with what stopped it, or FIXED when it only corrected an existing test, or added one for behaviour the code already has, and the suite is green |
sonnet |
implementer |
stubs, TDD green | anything except test files and .specify/ |
signature stubs (RESULT: STUB), or committed code with the tests that cover it green, and the full suite in the last round (RESULT: GREEN / RED) |
sonnet |
spec-gatekeeper |
final check | nothing | APPROVED or REJECTED, with a requirement-to-test table |
sonnet |
security-reviewer |
opt-in review | nothing | VERDICT: PASS or FAIL; reviews spec state and reviews implementation result |
sonnet |
patcher |
fast track | the working tree except protected paths, within 30 production lines and 2 files, never a commit | a report that /speckit-patch commits from, ending DONE, or ESCALATE or FAILED |
sonnet |
Each agent's phase instructions are Spec Kit's own skill (speckit-plan and so on). spec-auditor,
which runs its whole phase on every launch, preloads speckit-analyze with the skills: frontmatter
field. product-owner and architect read theirs from .claude/skills/ on a first run, so a revision
does not carry them (#257). The agent file
adds only what Spec Kit does not say: its inputs, its lane, and the shape of its report. Those bodies
are 27 to 120 lines long, blank lines not counted; the architect's is the longest. patcher runs no
Spec Kit phase, so its 34-line body carries the whole job. test/install.test.mjs counts them.
A long prompt dilutes the rules that matter, and a rule in prose is a request. "Never edit tests" in a prompt will hold most of the time. A hook that rejects the edit holds every time, and its rejection message tells the agent what to do instead.
Claude Code puts every agent's description into every session so it can route work. These eight
total about 2,100 characters (2,090 counted in the description: lines), about 520 tokens. The token figure is an estimate, not a measurement: 2,090 characters at the usual 4 characters per token for English text (counting tokens needs a model call, which was not made). Each one says when to use the agent and what it
will not do, so routing does not have to guess.
Prevents "Garbage In, Garbage Out": Most agent pipelines fail because the initial spec is vague, and the coding agent fills in the blanks with hallucinations. Your product-owner forcing a human-in-the-loop Q&A step before architecture ensures the foundation is solid.
True TDD Validation: LLMs are notoriously bad at writing tests for code they just wrote; they tend to write tautological tests that just mock everything to ensure a pass. Forcing the test-writer to write failing tests first proves the agent actually understands the acceptance criteria.
Circuit Breakers: The spec-auditor acts as a firewall. If the architect designs a plan that violates the spec, it gets kicked back before you waste tokens and time generating useless code.
Role-Based Access Control (RBAC): Using hooks to enforce file-system permissions per agent is the most reliable way to orchestrate multi-agent systems today.
One install gives you two ways to run the same pipeline, and each is built on ideas from a different public repository. Only ideas: no code was copied from either.
| Agents (the default) | Skills (--team skill-agents) |
|
|---|---|---|
| Shape | seven subagents, each in a fresh context with only its launch prompt | seven role skills run in your session, one growing context |
| Inspired by | google/elephant-goldfish-model | addyosmani/agent-skills (111,114 stars on 2026-10-27, read with gh api) |
| What was taken | reviewers that read only their target and the sources they are pointed at (Context budget); a reuse check before a new utility (the spec-auditor); a human-decided CONTEST path for findings (Routing findings); a drift report of specs against code (Checking old features for drift); a parent-only marker that no agent may receive (Full run with real models) | work done by skills loaded into the session instead of by launched agents; pressure cases where the request argues for skipping the process, scored with and without a change (Scored cases and arms); a lexical description-collision check over the skills; fresh-eyes review, rationalization tables and authoring rules, tracked as #186, #187 and #189 |
| Strength | independent review and the strongest guardrails: Claude Code holds each agent to its tools and the hooks end with it | no handoffs and no re-reading across roles; the two measured fixture runs cost 58% and 48% less |
| Weakness | lossy handoffs, and every launch pays for a fresh context | every role sees the whole conversation, so review is not independent, and several guardrails are prompt text (the table) |
The two modes share the hook, the audit gate, the lanes and the reports, so a feature can be built
either way and judged by the same gate. Agents or skills
says which to choose; the numbers behind the table are in docs/measurements.md.
What is and is not shown. Measured: the cost gap above, from two runs per mode (2026-10-25 and 2026-11-20). Taken from the
agent-skills repository so far: the harness (#188).
The prompt changes it suggests (#186, #187) are only kept if the harness shows they change a verdict
at a bounded cost, and their results go in docs/measurements.md either way.
Not shown: that either mode is better than the other for a large feature, and that the agent-skills
ideas improve this team's runs.
Two commands, both skills that run in the main session: /speckit-team
launches each agent of the pipeline in turn, and /speckit-patch
launches patcher once. Every rule that must hold is a mode of one hook script,
hooks/speckit-team.mjs: the skill decides what happens next, and the
hooks decide what is allowed.
/speckit-team runs in the main session, because only the main session can talk to you. It
launches each agent with the inputs it needs and relays the product owner's questions to you.
/speckit-team [--team <role>[,<role>...]] [--security] <request>. --team counts only as the first word; names are
case-insensitive and order does not matter. Without it the skill asks one question before any
launch, a stop like the others: Full team (recommended), Build only (test-writer, implementer),
Implement only (implementer), or Spec and build with no audit or verification (product-owner,
architect, test-writer, implementer). Its free-text answer is a role list. All six core roles is the full
team. The security-reviewer is opt-in, included via --security or named in --team (security-reviewer or alias security). patcher is not a team role.
Two typed forms run no agent: --team noagents (Spec Kit's own skills, below) and
--team skill-agents (the team's roles as skills in your session, below).
The skill refuses before launching anything, naming the valid roles: a name that is not a role;
noagents with a role; neither test-writer nor implementer; architect without product-owner;
spec-auditor without architect.
A smaller team than the full one goes only after you chose it. In a request typed without --team,
the hook refuses a launch whose Team: line names less than the full team until your answer to the
team question is in the session's transcript after the request; under "we ship today, skip the tests"
the main session launched implementer alone, unasked, in 2 of 6 scored runs on 2026-11-20
(#366). The full team, the recommended
option, needs no answer.
/speckit-team --team noagents <request> runs no agent at all. The session runs Spec Kit's own
skills itself, speckit-specify, speckit-plan, speckit-tasks and speckit-implement in that
order, asks you the spec's open questions, and stops for you to approve the spec and then the plan
and tasks. There is no audit, no verification by spec-gatekeeper and no agent hook; the session
runs the tests itself, stops fixing after 3 failed runs of the same tests in a row, and opens the PR
as any run does. Each agent of the full team starts from 11k to 14k tokens before it reads a file
and reads the code again (Context budget); here nothing is launched, though what
that saves on a whole run is not measured yet. It is chosen only by typing it: the typed command reaches the hook
(UserPromptExpansion), which records it for the session, so this request's speckit-implement
passes the audit gate. That is why the team question does not offer it, and why
a model's Team: line can never ask for it. The record ends at your next /speckit-team, or at a
launch of a team agent, after which the full gates apply again.
What an absent role skips, and the guardrails that go with it:
| Absent role | Steps skipped | Guardrails skipped |
|---|---|---|
product-owner |
the spec, its questions, the spec review stop | none |
architect |
plan and tasks, the plan stop, rounds by phase (one round instead) | spec-gatekeeper's open-task check; at the retry limit you decide, there is no architect to rethink |
spec-auditor |
the audit and its FAIL routing | the audit gate on test-writer and implementer |
test-writer |
the red step; the test tasks stay unticked | spec-gatekeeper's test trace and its open-task check on the test tasks |
implementer |
the stub and green steps; the other tasks stay unticked | the stub pass (a test failing on a missing symbol counts as red), spec-gatekeeper's passing tests and its open-task check on those tasks |
spec-gatekeeper |
verification and REJECTED routing | the recorded last word |
security-reviewer |
the security review of the spec and the security review of the result | its ends check on the VERDICT: line |
Every run keeps the hand-over (PR and CI), each chosen agent's scope, lane, ends and result
hooks, the retry limit while implementer is chosen, tests before implementation when both
test-writer and implementer are chosen, and the /speckit-implement gate. A run that is not the full
team starts with a one-line notice naming the skipped steps and ends with a report that lists them,
the unticked tasks and the skipped audit gate.
Without product-owner and architect the build roles work from the request text in one round, and
with product-owner only from the approved spec.md; with neither, the skill creates a
team/<request> branch when the tree is on main. Every launch prompt of such a run carries a
Team: test-writer, implementer line, which the hook and spec-gatekeeper read; spec-gatekeeper's
prompt also carries Unbuilt: T001, T003 when test-writer or implementer is absent and tasks.md
exists, naming the tasks nobody builds.
/speckit-team --team skill-agents <request> runs all seven roles in your session, each as an
installed skill (speckit-role-<role>), and launches no agent. Type it; the team question does not
offer it, and a free-text answer of skill-agents only gets a reminder of the typed form. It takes
no role names and not noagents, and combines with --security and --project. The hook starts
the mode from the typed command (UserPromptExpansion) and answers with a start message. If a
speckit-role-<role> skill is missing it blocks and tells you to run node install.mjs. Launching
any agent ends the mode.
Each role skill carries its own hooks in its frontmatter: scope role on writes and lane role at
Stop (see Guardrails). The gate on the Skill call checks the audit before
test-writer, implementer and spec-gatekeeper, and again before spec-gatekeeper, so an edit to the
spec, plan or tasks made inside the build roles never reaches verification unaudited.
| Enforced by the hook | Not enforced | |
|---|---|---|
| Lane | each role's write scope, and its lane check when it closes | a role's lane after a turn that ended without a Stop (an interrupt, an API error): its lane check and report do not run |
| Audit gate | before test-writer, implementer and spec-gatekeeper, at their Skill call | on each tool call inside test-writer and implementer: a spec, plan or tasks edit there is caught when the next of them, or spec-gatekeeper, starts |
| Verdict | spec-auditor's VERDICT: and spec-gatekeeper's word are read from the role's messages, from the first args line of the next Skill call (the skill starts it with the report's last line, because the transcript may not hold the message yet), and from the Stop's last message, and recorded; the gatekeeper's word is the last line that is only APPROVED or REJECTED, so hand-over text after it in the same response does not hide it (#185). spec-auditor's FAILs in a row are counted as the agent's are (#332), and a third speckit-role-spec-auditor call after two is denied until audit --approve, as is one while plan.md has open decisions, as the agent's launch is (#353) |
nothing more: a report with none of its role's words is sent back once (blocked at its Stop, or the next role call denied, which goes through when made again), as ends and result refuse an agent's, and the implementer role's still without one counts as RESULT: RED (#351) |
| Hand-on | a role whose turn ends on VERDICT: PASS, RESULT: STUB, RED or RESULT: GREEN, where the skill has no Stop: its Stop is sent back, once per role call, so the run goes on without you (#261); so is one on a first VERDICT: FAIL, a REJECTED, a FIXED or a RESULT: RED under the retry limit, which the skill routes without a Stop too (#332). A second FAIL in a row and a third RED in a row go to you |
the response that Stop costs, which a typed "go on" would cost too: asking for the next call in the report's own response was tried and dropped, as in its one run the audit and the gatekeeper wrote no report (measurements) |
| Retry limit | the implementer role's RESULT: RED reports in a row are counted in the same retry record as the agent's (GREEN clears it), and the third one is said and not handed on (#332); a fourth speckit-role-implementer call is denied with the agent's text until a revised plan or tasks pass a new audit, or you delete the record (#341) |
the limit inside a role call: the agent's gate retries denies every tool, the role's limit applies only at its Skill call |
| Context | nothing | every role sees this conversation, with the session's CLAUDE.md, on the session's model; read-only roles lose the omitClaudeMd isolation |
| Tool list | a read-only role's Write and Edit are denied, and so is a Bash command that writes in the repo | each agent's tool list: a role may use every tool of this session, MCP tools included, and a read-only role's write through one is not checked |
What was verified how. Verified live (Claude Code 2.1.310, 2026-10-25): the start message, an
audit denial of a speckit-role-test-writer call with no audit, and a Write outside architect's lane
denied (Live results, "Skill-agents"). Measured: the same fixture request
built once as the default team and once with --team skill-agents, 31% more input tokens and 58%
less cost on 2026-10-25, 62% more and 48% less on 2026-11-20, one sample each per day
(docs/measurements.md). Covered by test only:
the typed-form refusals, the install, rerun and uninstall of the role skills, the role record's
close, the verdict and word records (the args line and the Stop's last message paths included), and the rest of the table; the
end-to-end tests fire the role skills' hook entries against the real Claude Code. The role's end with its turn is read from Claude Code's prompt_id; end to end covers a resumed prompt ending the role, and the role staying live through a background task's notice, an auto-compaction and a message sent during its turn, each of which keeps the turn's prompt_id (#184; a message typed into the TUI was probed by hand, through vhs). Not verified at all: an interrupt, an API error's StopFailure and an AskUserQuestion answer (read in the 2.1.293 bundle, never seen running).
Agents or skills. An agent starts each role in a fresh context with only its launch prompt, and
returns a capped report. A role skill loads its instructions into your session, so every role works
in one context that keeps growing. The numbers below are the one pair of runs of 2026-10-25 in
docs/measurements.md; the rest follows from the design.
| Agents (default) | Skills (--team skill-agents) |
|
|---|---|---|
| Fixture run, 2026-10-25 | $1.86, about 15 min, 2.41M input tokens over 10 launches | $0.78, 5 min 17 s, 3.16M input tokens in one session, peak context 105k against 72k |
| Context | each role starts near 14k tokens and reads the code again | nothing is re-read across roles, but every response re-reads everything before it, so a large feature can reach compaction |
| Handoffs | lossy: a role knows only its prompt, and a wrong prompt costs a relaunch | none: a later role sees what earlier ones settled |
| Independent review | spec-auditor and spec-gatekeeper never see the reasoning they judge | every role sees the whole conversation, the reviewers included |
| Guardrails | Claude Code holds each agent to its tools, and its hooks end with it | rebuilt by the hook: a role ends on a new prompt_id, and only its report is read from the transcript; the table above lists what is not enforced |
| Models | per role: architect and spec-auditor on opus | the session's model for every role |
| Side-by-side slices | yes, in worktrees | no |
Choose agents for a large feature, for review that should not have seen the reasoning, for the strongest guardrails, or for opus on the hard roles. Choose skills for a small or medium feature you will watch, when time and cost matter more than an independent review. Part of the cost gap is the model mix: the default run's architect and spec-auditor ran on opus, so the pair is not a like-for-like price comparison. Whether skills still win on a feature large enough to fill the context is not measured.
The architect writes each decision you should confirm (a new dependency, a schema or public API
change, a rule with more than one reasonable reading) to an ## Open Decisions section of
plan.md: the options, its recommendation first, and what follows from each option (edge cases,
counts, side effects, the requirements and tasks it changes). An option that would make a line of
the spec wrong carries, on a Spec: line, that line as it is and its new wording, so the main
session can replace it without looking the place up. Its report names only the
decision IDs, so the reasoning is not carried in the main session for the rest of the run. At the
plan stop the skill reads the section in one command and asks you about every open decision at
once; with more than 4, its first question takes every recommended option in one answer, in which
you can also name exceptions (D5: B). The architect writes the plan and the tasks as its
recommendations make them, so when every answer is the recommended option the main session launches
no one: one command of the hook, decisions --recommended, adds Answer (<date>): <option>, as recommended under each decision, renames the section ## Decisions and puts the chosen Spec: lines
into the spec, or changes nothing and names the line it could not place (the architect writes each option as
a list item, - **A (recommended): <option>** then - **B: <option>**, and the command also reads
Option A and a bold paragraph without the bullet, #306,
#310, and a Spec: under heading with or without its #
markers, #365; in the full run of 2026-10-24
that was an architect and a product-owner for one edit each, 0.16M tokens; in the runs of 2026-11-08 and
2026-11-10, 3 or 4 main-session responses with a script of its own). The hook refuses the audit's
launch while plan.md still lists an open decision. Otherwise one architect
revision applies all the answers, moving each entry to a ## Decisions section with the answer and
the date, and product-owner, launched in the same message, rewords the spec lines the chosen options
carry. The spec and the
plan then agree before the first audit; in the 004 run a decision that contradicted FR-012 failed
it (Feature 004).
Work that nothing in spec.md, the constitution's MUST rules or CLAUDE.md requires, such as a
re-recording or an extra live check, is an open decision too, and its recommended option leaves the
work out, so taking every recommendation keeps the run to what was asked
(#89). Work CLAUDE.md asks for counts as
required, so the architect never recommends against the repository's own instructions.
Code the repository already has is not built twice. Before a task adds a function, type or module,
the architect greps the source for one that does the job and, if it finds one, names it in the task
as file and symbol. spec-auditor checks the same: for each new file, function and type the
implementation tasks list, it greps the source by name and by job and reads only the matching lines,
and a second implementation of existing behaviour is a HIGH finding for the architect, citing both
places. It is grep, not a reading of the codebase, so it finds a duplicate whose name or job words
match and misses one that shares neither. A duplicate caught here costs one architect revision;
caught later it costs a test-writer and an implementer for code that should not exist. The idea is
the reuse check of the Zoom Out reviewer in
google/elephant-goldfish-model
(agents/zoom_out.md), which must search the code before it accepts a new utility.
When your answers, or an audit's findings, fully determine the edits (a value, a list entry, a wording), the skill sends a dictated revision: each exact edit and where it goes, which the architect makes by grep without re-reading the artifacts. An answer that drops or renames an ID is one edit for every mention, which the architect finds by grep. Anything that needs design judgement, and any edit the architect finds changes more than it was told, gets a full revision. The orchestrating session never edits the plan itself: a response there re-reads a much larger context than an architect's (Feature 003).
On a FAIL it routes each CRITICAL and HIGH finding to the agent that owns it; MEDIUM and LOW findings are accepted and listed once at hand-over. On a REJECTED it routes each reason the same way. After two failed audits it hands the findings to you.
An owner that finds a finding wrong does not have to obey it. product-owner and architect may report
it contested, with the file:line that shows the auditor misread the spec, plan, tasks or
constitution, and edit nothing for it. The skill does not judge the contest: it asks you, with the
finding and the evidence, whether to fix it or uphold the contest. An upheld contest is recorded,
under ## Decisions in plan.md or ## Clarifications in spec.md, and spec-auditor and
security-reviewer do not raise a recorded ruling again unless they cite something it did not
consider. Without this, a wrong finding costs a revision and a re-audit, and after two FAILs it
reaches you anyway. The idea is the CONTEST path of
google/elephant-goldfish-model
(skills/egm_resolve/SKILL.md), where the human decides each contested finding. test/install.test.mjs
holds the skill, both owners and both reviewers to the same words.
After the audit it builds the feature in rounds, never in one shot. A slice is one small
implementation task plus the test tasks that cover it, and the architect writes tasks.md in
those slices. A round is at most 4 slices in task order, and gets one stub pass, one test-writer and
one implementer; phases of tasks.md (Setup, Foundational, one user story) that fit in 4 slices
together share a round, since each extra round costs a test-writer and an implementer more. The
architect never makes a slice of an implementation that leaves out what a later task adds just so
that task's test fails against it: in the full runs of 2026-10-24 and 2026-10-25 sum() without its
empty-array case became a slice of its own that way, which cost a round. The architect's report
ends with one line per round (Round 1: stub T001; red T002; green T003), so the main session
launches the first round straight from the audit's PASS instead of spending a response, 60k tokens
in the 2026-10-25 run, on reading tasks.md. Until
2026-10-10 every slice was its own round, so a feature cost up to three agent launches per
implementation task, each starting from nothing (11k to 14k tokens, see
Context budget) and reading the code again; that was most of why a run felt
slow next to plain prompting. The round size is a prompt rule; how much it saves in a full run is
not measured yet. For each round:
- Stubs. If the tests will call code that does not exist yet, implementer first creates the
signatures the task lists, with bodies that only signal "not implemented", and reports
RESULT: STUB. This is what lets the next step fail cleanly. - Red. test-writer writes the round's tests and loops until each one fails on an assertion or on the stub's not-implemented signal. A test that fails because it does not parse, an import is missing or a name is undefined proves nothing about the behaviour, so test-writer fixes it (at most 3 rounds per test) and the skill sends back any that still fail that way. test-writer also runs the type check CI runs over tests, and works out on the current code any value an assertion compares with that the code already decides: a task asking for a number no implementation can meet is reported, before any implementer runs, not written as a red test.
- Green. implementer makes the round's tests pass, under the retry limit. It runs the tests that cover its change; the full suite runs only in the last round, which the skill names, and once more at spec-gatekeeper. In the 004 run every round ran it: 5 runs, about 14.5 of the 48 agent-minutes.
The failure-reason check in step 2 is prose: the hooks cannot tell an assertion failure from a compile error in an arbitrary language, so the skill checks test-writer's pasted output.
Every agent that runs tests gives the run a Bash timeout that covers it. Past Claude Code's
default of 2 minutes the command moves to the background, where a subagent cannot wait for it:
sleep is blocked and Monitor is not one of its tools. In the 004 run one implementer waited
234 s that way on an npm test it then ran again.
When the last round is GREEN and every task in tasks.md is ticked, it launches spec-gatekeeper
straight away, without asking: between the stops above it never waits for you. A task still
unticked at that point (a final test run, say) becomes one more implementer round, and the ticks
made while building never void the audit.
For [P] slices of a round touching disjoint files, it can run one loop per slice at once, each
implementer in its own git worktree, merged back into the feature branch in task order. It does so
only if you say so at the plan stop, and recommends one at a time. Each slice side by side gets its
own test-writer and implementer instead of sharing its round's, the merges take main-session
responses, and several agents draw on your usage limits at once. Measured on 2026-10-25 with real
models (#114), one two-slice feature
(sum() and capitalize() in two files, tools/full-run.mjs --two-slices and --side-by-side):
| Build, first stub to last implementer | One at a time | Side by side |
|---|---|---|
| Wall-clock | 95 s | 140 s |
| Build launches | 3 | 7 |
| Build agents' input | 0.20M | 0.57M |
| Main-session responses, whole run | 13 | 19 |
Slices that take seconds each gain nothing from running at once; the launches, the merges and the cleanup cost more than the overlap saves. Side by side can pay off only for slices that each take minutes, which no run has measured. The side-by-side run also had two stub implementers, a docs-only implementer and a commit to take out worktrees, since fixed (below); the one-at-a-time run already had the architect's round lines, which save the main session one response.
Measured again on 2026-11-11 with those faults fixed, both runs from one build of the team (e14efc9)
and the same request, 1 run each: one at a time cost $1.26 with 7 agent launches and 1 min 32 s from
the first red launch to the verify launch; side by side cost $1.37 (9% more) with 9 launches and
1 min 53 s. One at a time gave both slices' tests to one test-writer and both implementations to
one implementer, so it was a single round with nothing for side by side to save
(docs/measurements.md, "The live runs of 2026-11-11"). The recommendation
stays one at a time.
Measured on 2026-11-20 with slices that take minutes (tools/full-run.mjs --large-slices: two modules
of six functions each, Claude Code 2.1.329, one build of the team, 3 runs per arm, all passed): from the
first build launch to the verify launch, one at a time took 140 to 148 s with 3 or 4 launches, side by
side 117 to 151 s with 5. Side by side saved no build time on these slices either. The whole runs differed
more ($3.39 to $4.43 one at a time, $1.95 to $2.51 side by side), but in the spec phase, before the
plan stop's answer could matter: every one-at-a-time run failed its first audit and took 2 or 3 more
audits, against 1 of 3 side-by-side runs (#114;
the runs). The recommendation
stays one at a time.
Claude Code does run them side by side: agents launched in one message overlap, in worktrees too,
and the main session waits for all of them, checked against a fake API and pinned by
test/e2e.test.mjs (#40).
The same check shaped the rules for worktrees. A worktree starts from the last commit, without
uncommitted work, so the main session commits the round's tests in the message that launches the
implementers. An implementer there ticks nothing in tasks.md, because ticks on adjacent lines in
two branches conflict when merged; after each implementer step the main session merges the branches,
removes each worktree and its branch, and only then ticks the tasks the reports name and commits.
An implementer in a worktree runs its own tasks' tests and never the full suite, which cannot pass
there: the other slices' code is still stubs. Its launch never carries last round, the words that
ask for the suite, and the main session runs it after the last round's merge
(#309: in the run of 2026-11-11 both
implementers ended RESULT: RED for each other's stubs, 2 of the 3 REDs that lock implementer out).
The worktrees sit in the repository's .claude/worktrees/, so a git add -A before the removal
commits them as embedded repositories, as the first side-by-side run with real models did
(2026-10-25). The round's stub pass stays one implementer without a worktree: stubs take seconds,
and two of them in worktrees cost that run a launch and a merge more.
A subagent never sees the main session's conversation; it starts with the prompt the skill writes
and whatever files it reads. So the skill passes each agent only what its Inputs section lists,
and never the chat, the product owner's questions and answers, or another agent's full report.
implementer gets the slice's task IDs and test-writer's report for them, and its own prompt tells
it to read tasks.md, the failing tests and the code they touch, not spec.md, plan.md,
research.md or data-model.md. The tests are its spec.
The three agents that cannot write, spec-auditor, spec-gatekeeper and security-reviewer, also start
without your CLAUDE.md files, the user's and the project's (omitClaudeMd: true in their
frontmatter). What they check is in the files their Inputs name, and a rule they must hold belongs in
the constitution, which all three read. spec-gatekeeper still opens the project's CLAUDE.md as a
file when the CI workflow does not name the gates. The idea is the Goldfish reviewer of
google/elephant-goldfish-model, which reads only
the target and the sources it is pointed at. Claude Code writes that context again on every launch,
so each of these launches skips it: 17,351 characters less in the first message on the machine
measured (CLAUDE.md in the read-only agents).
The agents that write keep both files, for the repo's build commands and conventions.
What the architect found is handed on in tasks.md: every task names the file and symbol of each
function, type, test helper and API member it uses, so test-writer and implementer go straight to
it. In the 004 run the plugin API's types were explored by the architect, then by implementer and
test-writer again (19k, 17k and 9k characters). A test task names its test file, the requirement
and scenario IDs it covers and only what spec.md and contracts/ leave open; test-writer reads
the cited lines and writes the cases. No agent reads another feature's artifacts as an example:
in the 004 run the architect and product-owner read 40k characters of them.
The main session re-reads its whole context with every response, so the skill spends as few as it
can. The approved spec and plan are committed in the message that launches the next agent: Claude
Code runs the calls of one message in order, which test/e2e.test.mjs pins,
so the commit lands before the agent starts and needs no request of its own.
While an agent works, Claude Code shows the Agent call's description and the agent's tool calls, a Bash call as its command, and never the agent's own text or a Bash call's description (checked on 2026-10-10 against Claude Code 2.1.296's interface, driven by vhs against a fake API). So the skill makes the description name the step and its task IDs, says before each launch what the agent will do, and after each report what it changed and how long it took.
/speckit-patch <change> is for a change too small for the pipeline. One run:
- The skill (main session) checks that
.specify/exists, notes the start commit, the installed hook's hash and the remote-tracking refs, and createspatch/<slug>from the current commit. - It launches
patcheronce, in the foreground.patcherchanges the working tree and runs the repo's existing tests, and a hook measures it on every tool call. - When
patcherreports, the end check decides whether the run is accepted (see below). - Only if it is, and the report is
DONEwith the tests passed, the skill commits the files in the accepted record, pushespatch/<slug>(never forced) and opens a PR if there is a GitHub remote. It does not merge.patcheritself cannot commit, push or rungh.
So the skill decides what happens next and the hooks decide what is allowed, as in the pipeline. A commit made before the end check would hold whatever the run did, and a push cannot be undone; this way nothing leaves the working tree until the check has looked at the whole run.
At most 30 changed production lines in at most 2 production files; 30 is within and 31 is over. No binary production file. The hook measures against the commit the run started from:
- Per production file, the larger of its insertions and deletions in
git diff --numstat, so a modified line counts once and 30 modified lines fit. An untracked production file counts its lines. - A rename between production files is 1 file and only its edited lines, so a pure rename is 0
lines. A test or doc moved into production code counts as a new production file. A move git does
not pair as a rename, such as a plain
mv, counts as a deletion plus a new file, which is whypatchermoves files withgit mv. - Files already uncommitted at the start are left out while they stay unchanged. A
WriteorEditto one is denied. A change to one by other means, or a commit containing one, stops the run: it is over budget because the hook cannot separate your lines frompatcher's.
Over budget, every tool except reporting back is denied and patcher ends ESCALATE. If a protected
file was changed or a commit was made, it may still restore: a Bash command that is one
git checkout, git restore, git reset --soft or rm, naming only protected files still to be
restored.
Each changed path gets one class, checked in this order:
- Protected: never written (the table below).
- Test: the built-in patterns plus
.specify/test-pathsas committed at the start commit, not as it is in the working tree, so commit a change to that file before a run. - Doc: a file ending
.md,.mdx,.markdown,.rst,.adoc,.asciidoc, or a.txtfile underdocs/or namedREADME,CHANGELOG,CHANGES,HISTORY,NEWS,LICENSE,NOTICE,AUTHORS,CONTRIBUTINGorCOPYING(any directory), all case-insensitive. Any other.txtfile, such asrequirements.txtorCMakeLists.txt, is production. Adocs/folder is not a doc rule for other files: a.jsfile in it is production. - Production: anything else. Only production counts against the budget.
| Protected path | Why |
|---|---|
.specify/ |
Spec Kit's config and the constitution |
specs/ |
feature specs, plans and tasks, which belong to /speckit-team |
.claude/ |
the project's Claude Code agents, skills, hooks and settings |
.github/ |
CI workflows and repository settings |
.gitlab-ci.yml, .circleci/, azure-pipelines.yml, Jenkinsfile, .pre-commit-config.yaml |
other CI and commit-hook configuration |
The speckit-agents sources (hooks/speckit-team.mjs, agents/*.md, skills/*/SKILL.md,
install.mjs) and the top-level package.json are protected too, but only in a repository whose
top-level package.json, as committed at the start, is named speckit-agents. Elsewhere those are
ordinary files. The installed team in the Claude config directory (agents/, hooks/, skills/,
settings.json, settings.local.json) is protected everywhere: a Write or Edit there is denied,
and any other change is caught at the end.
- Writes (
scope protected): aWrite,Edit,MultiEditorNotebookEditto a protected path, the installed team or the git directory is denied before it runs. - History and remote commands:
patchermay not rungit commit,merge,rebase,stash,tag,branch(except the listing forms such asgit branch --show-current),switch,push,pull,fetch, agit checkoutwith no--and the other subcommands inHISTORY_SUBCOMMANDS, agit -c alias.*call, the forge CLIsgh,hub,glabandtea, ornpm,pnpm,yarnorbun publish, nor a command that names the fast track's own state (.git/speckit-team). The command is split into words and everygitword is checked, sosh -c "git push"andgit -C . commitare caught. It is then read again the way a shell reads it: quotes, escapes and$'...', variables where they are used (split onIFS, and once with each value a later assignment or aforloop gives them), redirections dropped,{a,b}expanded, command and process substitutions read as commands of their own, as are the strings given tosh -c,evaland a here-string, and a glob such as/usr/bin/g?tmatched against the denied programs. Sog"it" push,G=git; $G push,git${IFS}push,git 2>/dev/null push,git -c x="a b" push,{git,} pushandG=git; sh -c '$G push'are caught too. What it cannot work out (a substitution's output,$@, an unset variable,${X%y}) counts as unknown, and an unknown word is denied where git's subcommand would be (git "$@"in a function) or where a program word stands before a history or forge command ("$TOOL" push,$(printf git) push). A command it cannot finish reading (nested more than 8 levels, more than 64 assigned values) is denied (#72 and three security reviews of it). It is still not a shell: text read at run time (eval "$(cat cmd.txt)",read) is not seen, and the end check catches any commit that gets through. - Pushes and fetches, by what they leave behind: the start record keeps the remote-tracking refs
(
refs/remotes/*), and once one moves, which a push to a named remote or a fetch does however its command was written (a script, a string built at run time), every later tool call is denied and the end check fails the run (#72). The deny list above is no longer the only line for a push. - Git's network transports: the hook runs each Bash command it lets through after one line,
export GIT_CONFIG_COUNT=7 GIT_CONFIG_KEY_0=protocol.allow GIT_CONFIG_VALUE_0=never ..., which you see at the top of the command. It sets git's transport policy toneverforgit,ssh,http,https,extand any other, and keeps git's default,user, for paths on disk, in the environment's config scope, which overrides every config file. So git refuses a push, fetch or clone over the network before it connects, whatever started it: a script, a package script, an alias, a string built at run time (#72). The same line ends withGH_CONFIG_DIR=.speckit-no-forge-login/.git GLAB_CONFIG_DIR=.speckit-no-forge-login---..., config folders that do not exist, so a script'sgh pr mergeorgh apifinds no stored login and stops before any request (#123; checked with gh 2.89). The folders are relative, so the line is the same on every machine. glab makes its config folder on its first run, and left one in the repository (#140), so its name is padded with dashes to 256 characters, one more than a path component may have on Linux, macOS or Windows: no tool can create it, and glab now stops withfailed to create config directorybefore any request (glab 1.123.0, Windows). With that name gh 2.89 on Linux does not start at all, so gh's folder ends in.gitinstead: git refuses to track a path with a.gitpart at any depth, so a repository cannot commit a config, a login in it, for gh to read there, as it could at the plain name (#155). Checked with gh 2.89 on Windows and Linux at the repository's root, in a folder and in a worktree, where.gitis a file and a folder under.git/would stop gh from starting on Linux. A repository that commits a file named.speckit-no-forge-loginstops gh from starting on Linux underpatcher, which sends no request either. Last comeGH_TOKEN= GITHUB_TOKEN= GH_ENTERPRISE_TOKEN= GITHUB_ENTERPRISE_TOKEN= GITLAB_TOKEN= GITLAB_ACCESS_TOKEN= OAUTH_TOKEN=: a token in the environment, as in CI, would skip the stored login, and gh and glab read an empty one as unset (#138; checked with gh 2.89 and glab 1.123.0, which sent no token under the line). A script that needsgh's login fails underpatcherfor the same reason, and so does a test suite that reads one of those variables, such as one that calls the GitHub or GitLab API withGITHUB_TOKENor a release dry run: underpatcherit sees the variable empty. Run such a suite outside the fast track. Claude Code checks each part of a rewritten command against your permission rules, and the export line needs a rule of its own: without one, every command you allowed would ask again (with 2.1.296 an allowedechoasked "The following part requires approval: export GIT_CONFIG_COUNT=..."). So the installer adds an allow rule for that exact line tosettings.json, never a prefix rule, which would let any export of git config through, such ascore.fsmonitor, which runs a program. With it, the rewritten command asks for nothing the command itself would not, in every permission mode; checked against a fake API indefault,acceptEdits,dontAskandauto, where it kept the safety classifier out of it (#122). Where the rule is missing (you removed it, or your environment already passes git config pairs, which changes the line), the command runs as typed, except inbypassPermissions, which consults no allow rule. Deny rules still match the command's own part. - Wholesale restores:
git reset --hard,git clean, and agit checkoutorgit restoreof., a folder, a pattern or a file uncommitted at the start are denied on every Bash call, because they would destroy your uncommitted work.
When patcher finishes, the hook measures the run and the first rule that applies decides:
| What it finds | Result |
|---|---|
| a protected repo file changed | blocks patcher from finishing until each is restored, on every attempt |
| a commit made since the start | blocks until git reset --soft <start> |
| an installed team file changed | the run ends FAILED: patcher may finish, nothing is committed |
| a remote-tracking ref moved (a push or a fetch) | the run ends FAILED the same way, naming the refs; check the remote for a pushed branch |
| over budget | patcher may finish; the run is not accepted, nothing is committed |
| within budget | accepted: the hook writes the accepted record |
The protected check blocks every time, repo files only, because patcher can restore a repo file by
naming it. It cannot restore a file outside the repo, and blocking would leave no way out but
stopping the run by hand, so a changed team file ends the run FAILED instead, with a message naming
the files. A push cannot be taken back by patcher either, so a moved remote-tracking ref also ends it
FAILED. In each case there is no accepted record, so the skill commits nothing.
The accepted record, patch-accepted.json, lists the files patcher changed (production, test and
doc, never a protected file or one that was uncommitted at the start) and which of them are
untracked. The skill commits exactly those with git commit -- <files>, which leaves your other
staged changes out of the commit. If files is empty, patcher changed nothing and the skill
commits nothing, pushes nothing and opens no PR. The skill also checks, against notes it took before
the launch, that the installed hook's hash, HEAD, the branch and the remote-tracking refs are as it
left them, and that no file uncommitted at the start is in the record. Those notes stay in the main
session, out of patcher's reach; the hook's start record is a file patcher's shell could rewrite
(#72).
A run that commits nothing (FAILED, ESCALATE, over budget) leaves patcher's changes in the
working tree, among yours. So the end check also builds the command that takes back patcher's
changes and nothing else, from the same lists: git restore --source=<start> --staged --worktree --
for the files it changed or deleted (a file the start commit lacks is removed too), then rm -f --
for the ones it created, each path in single quotes. Files uncommitted at the start and protected
files are never in it. Every end check past the protected and commit checks writes it to
<git dir>/speckit-team/patch-undo.json (key, sha, undo, null when nothing changed, and
the end check's outcome and message, #221),
which the next patch call removes, and the over-budget and FAILED messages end with
"To undo only patcher's changes, run: ...". The file is what the skill reads, for the undo and
for the cause of a run it does not commit: a live run on 2026-10-31 showed the message reaches only
patcher's own transcript, never the main session, whose report then named a cause of its own. The
hook runs none of it. The skill shows the command, asks, and runs it exactly as given only on an
explicit yes, never git stash, git reset --hard, git clean or git checkout ., which would take
your work too (#213). A test runs the command
on a stopped run and checks that the tree is back at the start with your own changes kept.
For the whole team, every rule of every skill and agent and what holds it (a hook, a script the skill
runs, a test that pins the text, or nothing) is in docs/rules.md, with the
text-only rules whose breach leaves no trace listed first (#232).
test/rules.test.mjs fails when a section of a skill or agent is added, changed or dropped without
its entry there. For the fast track:
No hook can tell which command is a repo's test suite or whether it passed. These are rules in
agents/patcher.md and
skills/speckit-patch/SKILL.md, not hooks: no PR unless the
existing tests passed, reporting tests as passed, failed, skipped or not run, a regression test
first for a change in behaviour, the skill's checks against its own notes before it commits, and
never merging. The hook's part is that no accepted record exists unless the end check accepted the
run. One of those rules has a hook behind it (#243): a run that changes production lines with no
test file changed is stopped at the end, unless the report has a No test: <reason> line for a
change with no behaviour (a typo, a comment, a config value). A report sent through SubagentHandback
keeps its line for the Stop that follows it, which runs the end check again on the agent's last
message (#354: that message need not repeat
the line, and the Stop removed the run's accepted record). Whether a test that came with the
change fails first is not checked.
- Verified live (2026-10-10, Claude Code 2.1.296, Live results): one fix
through to a commit by the main session on a branch the skill created, with the end check's
fast track ... acceptedmessage (L1, L8);FAILEDon a change that breaks a test, with no commit (L2); a write to a protected path denied and reportedESCALATE(L4); a new workflow file blocked at the stop, deleted, and left out of the commit (L5);/speckit-triagelaunching no agent (L6); the/speckit-implementgate unchanged (L7); and, over budget, the end check's message and no accepted record (L3). Run with a Haiku main session, headless, on a repo with no remote, so no push or pull request was made. - Re-run live (2026-10-17, Claude Code 2.1.302, Live results), where the
first run did not see the check: the mid-run budget deny, on the Edit after the one that crossed
30 lines, with the report ending
ESCALATE(L3);/speckit-triage fix a typo in README.mdsuggesting/speckit-patch(L6); andpatcher's owngit commitdenied withmay not run git commit, the main session committing after the accepted end, and itsgit pushdenied withmay not run git push(L8). - Verified by unit and end-to-end test only: every hook decision above in
test/hook-patch.test.mjs; the installed agent and skills intest/install.test.mjs; the three hook entries ofpatcherfiring underclaude -pagainst a fake API intest/e2e.test.mjs, and again with fork subagents on, wherepatcherruns in the background as it does in an interactive session (#73); and git's network transports switched off, where git refused a push from a scriptpatcherran withtransport 'https' not allowed, inbypassPermissionsand, with the installer's allow rule, indefaultwith no prompt (without the hook it tried to connect, #72, #122); and agh apicall from such a script, which stopped for lack of a login (#123). - Seen in an interactive session, against a fake API: on 2026-10-12 a background
patcher's protected Write was denied, its production Write went through once accepted at the permission prompt, and itsDONEreport passed the end check, which wrote the accepted record (Live results). - Not verified at all: a real model following the prompt rules above.
The hooks guard against an agent's mistakes and drift, not against deliberate evasion through the shell. What that leaves open is in Known limits.
Standing project context lives under .specify/projects/<name>/:
.specify/projects/<name>/
├── instructions.md # project rules and instructions (markdown, at most 8,192 bytes)
└── knowledge/ # reference documents (docs, schemas, API contracts, at most 100 files)
Activate it for a run with --project <name>:
/speckit-team --project billing Add invoice payment webhook
/speckit-patch --project billing Fix currency formatting in PDF export--project, --team and --security can be passed in any order before the request text (--project billing --team test-writer,implementer or --team test-writer,implementer --project billing), each at most once.
Before anything is launched, the skill checks the project in its first Bash call, node hooks/speckit-team.mjs check team --project <name> (check --project <name> for /speckit-patch), which prints the same block as project <name> after the install check, so a run with a project starts in one call, not two (#338). If valid, the hook's SubagentStart event injects the project block into the agent's prompt as additionalContext for all eight agents (product-owner, architect, spec-auditor, test-writer, implementer, spec-gatekeeper, security-reviewer, and patcher).
The injected block contains:
- The project header with the name, instruction byte size, and sorted list of knowledge files with byte sizes.
- The full text of
instructions.md, indented.
Agents read knowledge files on demand from .specify/projects/<name>/. Launch prompts carry only a Project: <name> line (the hook twin pattern) and never paste the block directly. In a --team noagents run, the main session reads the project block from the project CLI mode and follows it itself.
Claude Code puts the block last in the agent's first message, after the launch prompt. Everything ahead of it is the same whatever the project: the tools, the system blocks (the agent's body among them) and Claude Code's context blocks before the launch prompt. So a launch with another project, or a larger one, keeps that cached prefix and writes only its own prompt and block again. An e2e test pins the order on Claude Code 2.1.316 against the fake API, and fails if the block moves into the system blocks or ahead of the launch prompt (#211).
- Name pattern:
^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$(letters, digits,-and_only, at most 64 characters). - Size limits:
instructions.mdmay not exceed 8,192 bytes; at most 100 knowledge files per project. One byte or file more is refused before any launch. - Precedence: Project instructions are reference knowledge. They cannot override or contradict repository rules (
CLAUDE.md, the constitution, or guardrail hooks). They cannot grant write access outside an agent's assigned lane or bypass the audit gate. - Protected path:
.specify/projects/is protected and read-only for all agents. Every writing agent (product-owner,architect,spec-auditor,test-writer,implementer,patcher) is denied from creating, editing or deleting files under.specify/projects/.
To create a new project skeleton:
node hooks/speckit-team.mjs project <name> --initThis creates .specify/projects/<name>/instructions.md with a template. If you run /speckit-team --project <name> for a project that does not exist, the skill asks whether to create it, runs --init, and stops so you can edit the instructions before launching agents.
- Verified live (2026-10-15, Claude Code 2.1.296, Live results):
/speckit-team --project demoinitializing the project via--initwhen missing, injecting project context into the agent start,/speckit-patch --project demorespecting the budget, and refusal of invalid project names. - Verified by unit and end-to-end tests: CLI output, limits, sorting and formatting in
test/hook.test.mjs; fast track budget independence intest/hook-patch.test.mjs; skill argument parsing, prompt generation and refusal checks intest/install.test.mjs; live context injection intest/e2e.test.mjs. - Not verified at all: multi-agent interactions under extreme project instructions that actively try to socially engineer subagents to bypass lane checks.
Every guardrail is a mode of hooks/speckit-team.mjs. In a repo without
.specify/ every mode exits immediately and allows the action, so installing at user level costs
nothing elsewhere. It knows that before starting git: no folder from the working directory up holds
.specify/, so one process ends at 51 ms on Windows, of which 42 ms is Node starting at all. In a
Spec Kit repo one git rev-parse gives both the work tree and the shared git directory; a gate call
there takes 68 ms. Both were 14 to 15 ms slower with two git processes before (30 runs each,
alternating old and new, 2026-10-11). A start call takes 48 ms outside a Spec Kit repo, 73 ms inside
without a project record, and 74 ms with one (mean of 20 runs each, p90 51 ms, 76 ms and 77 ms, 2026-10-15).
| Mode | Wired to | What it stops |
|---|---|---|
scope only <prefixes> |
product-owner, architect: PreToolUse Write|Edit|MultiEdit|NotebookEdit|Bash |
writing outside their prefixes, with a write tool or a Bash command that names the file (What a scope rule reads in a Bash command) |
scope tests |
test-writer: run inside its gate entry as gate scope tests, on `Write |
Edit |
scope no-tests |
implementer: run inside its gate retries entry as gate retries scope no-tests, on the same tools (#337) |
writing test files, or Spec Kit's config under .specify/ (feature.json picks the feature whose retry count applies) |
scope protected |
patcher: PreToolUse Write|Edit|MultiEdit|NotebookEdit |
writing a protected path, the installed team's files, or the git directory (The fast track) |
patch |
patcher: PreToolUse on every tool, and Stop | going past 30 production lines or 2 files, git commit, git push, gh and the other history commands, git reset --hard, git clean and wholesale restores, a write to a file uncommitted at the start; git's network transports for every Bash command it lets through (with the installer's allow rule for the export line, or in bypassPermissions); at the end, a protected change or a commit, a production change with no test file unless the report has a No test: <reason> line (#243), and no accepted record unless the run is within budget |
ends DONE FAILED ESCALATE |
patcher: PreToolUse SubagentHandback, and Stop |
a report whose last line is not DONE, FAILED or ESCALATE (refused once, never twice); records nothing |
scope none |
spec-auditor, spec-gatekeeper, security-reviewer: PreToolUse Bash |
a Bash command that writes a file in the repo, writes to a path only the run can tell, or changes the working tree or the history with git (checkout, stash, reset, add, commit and the like); checks, tests and writes outside the repo pass (#209) |
every scope rule |
all five writing agents, and the three read-only ones on Bash | writing into the git directory (also a linked worktree's main one), where verdicts and retry counts live |
scope role |
--team skill-agents: each role skill's frontmatter, PreToolUse Write|Edit|MultiEdit|NotebookEdit|Bash |
the acting role writing outside its lane (the same rule as its agent's scope, a twin of ROLE_LANES), or any write by a read-only role, through a write tool or Bash as scope none reads it |
lane role |
--team skill-agents: each role skill's frontmatter, Stop |
finishing a role with out-of-lane changes; ending the turn, once per role call, on a report the skill goes on from (VERDICT: PASS, RESULT: STUB, RED, RESULT: GREEN, #261; a first VERDICT: FAIL, REJECTED, FIXED, a RESULT: RED under the retry limit, #332); records spec-auditor's verdict and spec-gatekeeper's word from its messages, the next Skill call's first args line and the Stop's last message. A turn that loaded several role skills runs one process per skill at each Stop; one of them sends each block back (#284) |
gate |
test-writer, implementer: PreToolUse on every tool except SubagentHandback; its entry carries the agent's scope rule (gate scope tests), which it applies to a write or Bash call after the gate lets it through, so one process decides both (#337: about 120 instead of 225 ms of hook processes per write on Windows) |
doing anything before the audit passed (reporting back is never blocked) |
gate retries |
implementer: the same | also a fourth attempt after 3 RESULT: RED reports in a row on the same plan and tasks (see The retry limit) |
result |
implementer: PreToolUse SubagentHandback, and Stop |
a report without a RESULT: line (refused once, then counted as RED); counts the result |
gate |
settings.json: PreToolUse `Skill |
AgentandUserPromptExpansion (speckit-implement, speckit-team`) |
verdict |
spec-auditor: PreToolUse (every tool), and Stop | a report without a VERDICT: line (refused once, never twice); records the verdict, but only if spec, plan, tasks and constitution are as they were at the auditor's first tool call: a late audit of since-changed files is reported and not recorded, so it cannot replace a newer verdict (#77) |
lane tests / lane no-tests |
test-writer, implementer: Stop | finishing with out-of-lane changes, including ones made through Bash or already committed |
lane only <prefixes> |
product-owner, architect: Stop | finishing with changes outside the prefixes of their scope only rule, including ones made through Bash or already committed (#88) |
start |
settings.json: SubagentStart of the eight agents |
records where product-owner and architect start for their Stop's lane only; injects the session's project block as additionalContext for all eight when a project is active (007); never decides |
project <name> [--init] |
CLI | prints the formatted project block and knowledge file listing, enforcing size/file limits; --init creates the starter instructions.md |
check |
CLI: the first step of /speckit-team and /speckit-patch |
a run whose team is not this install alone: mixed builds, a second install of another build, a project install in a folder Claude Code has not trusted (exit 1, the skill stops); note: lines for the rest. check team, which /speckit-team runs, adds one state: line each for the working tree, the constitution (rules, template or missing) and the branch, so step 0 is one call (#230, Troubleshooting). --project <name> after either adds the project mode's block, or exits 1 with its refusal line (#338) |
decisions --recommended |
CLI: the plan stop of /speckit-team, when every answer is the recommended option |
hand-written edits at the plan stop: it records each answer in plan.md and applies the recommended options' Spec: lines to spec.md, or changes nothing and names the line it could not place (exit 1). The Skill|Agent gate refuses a spec-auditor launch while plan.md still lists an open decision, so a failed record is not followed by an audit of an unsettled plan (measurements) |
relay |
settings.json: PostToolUse on Agent |
never decides: hands the main session, as additionalContext after the Agent call returns, every message the team's hooks gave inside the subagents of its session (a lane WARNING at a second Stop, a lane check that could not run, a verdict not recorded, an APPROVED recorded as REJECTED), which otherwise reach only the subagent's transcript (#231) |
ends --record APPROVED REJECTED |
spec-gatekeeper: PreToolUse SubagentHandback, and Stop |
a report whose last line is not its verdict (refused once, never twice); APPROVED while the drift check finds, in the active feature's tasks.md, a ticked test task citing an FR ID none of its test files holds, or an FR of its spec.md in no test line naming the feature's number that no task excuses with No test: <reason> (#235) (refused at every hand-back and once at Stop, then recorded as REJECTED with claimed and drift; REJECTED always passes, #228); records the accepted word. The same check runs on the spec-gatekeeper role in --team skill-agents: blocked once at its Stop, or the next role call denied once (#351) |
ends RED BLOCKED FIXED |
test-writer: PreToolUse SubagentHandback, and Stop |
a report whose last line is not RED, BLOCKED or FIXED (a correction of an existing test that adds no failing one, #74, or a test of behaviour the code already has, which the main session then shows failing, #298), such as the bare "placeholder" one test-writer handed back on 2026-10-08 (refused once, never twice); records nothing, so it never replaces the gatekeeper's word. A RED whose output is a SyntaxError, a ReferenceError ... is not defined or a Python NameError is refused once the same way, and a second such report is kept in ends/red-faults.json (#240), and so is one on a missing module the error names by a test path, a helper or a fixture (#245); a missing production file, a package or a path outside the repo is a valid RED. A RED or FIXED while a ticked test task cites an ID none of its test files holds (the task half of the drift check; an FR of spec.md no test names yet stays the gate's) is refused once with the lines, and a second such report goes through with a message naming them (#315: found only at the gate, it cost the run of 2026-11-11 a verify round and a launch). The test-writer role of --team skill-agents gets the same check where its role is closed: blocked once at its Stop, or denied once at the next role call, which goes through when made again (#316), and so does its RED on a syntax, name or missing-test-module error, kept in ends/red-faults.json (#334) |
ends "VERDICT: PASS" "VERDICT: FAIL" |
security-reviewer: PreToolUse SubagentHandback, and Stop |
a report whose last line is not VERDICT: PASS or VERDICT: FAIL, the line the skill routes on (refused once, never twice); records nothing, so it never touches spec-auditor's verdict |
Agent hooks live in each agent's frontmatter, so they only run while that agent is active. The three
settings.json entries are the ones the installer merges in. start is one of them because Claude
Code runs no SubagentStart hook from an agent's own frontmatter (checked on 2.1.296 against a fake
API: the frontmatter entry never ran, the settings entry did, with the agent's id).
A scope rule judges a path by where it really is: the repo and the file are both resolved through
symlinks, Windows junctions and 8.3 short names before they are compared. Paths outside the repo
are not the rule's business. Until 2026-10-08 the comparison used the path as given, so a repo
reached by another name (macOS's /var is /private/var, a short-named Windows profile such as
C:\Users\RUNNER~1) made every file look outside it, and every lane let the write through.
Until #210 a writing agent's Bash write was
seen only by the lane check when it stopped, after the file had changed, and the
read-only agents' Bash was not checked at all (#209).
Now every team agent's scope hook also runs on Bash, reads the command the way the fast track's
patch mode does (quotes, variables, sh -c and eval strings, substitutions), and judges each
file it writes as it would judge a Write of that file, before anything runs:
- the target of every
>,>>,&>and<>redirection, apart from/dev/nulland the other devices and a descriptor such as2>&1; - the operands of
rm,rmdir,unlink,touch,mkdir,truncate,shredandtee, both ends ofmv, the destination ofcp,lnandinstall(or-t's folder), the files ofsed -iandperl -i, anddd of=; git rm,git mv,git restoreandgit checkoutof paths (--, or a name that exists), and the files git writes by name: any--output(git diff,git log),git archive -o, the folder ofgit format-patch -oand ofgit worktree add(a folder judged by a file in it), a long option read by any prefix of it, as git reads it (--out=x), and the filefind -fprint,-fprintfand-flsname (#352);- after
cd,pushdorgit -C, paths from that folder;sudo,env,nohupand the like before a program are skipped.
A here-document's body is text, unless a shell on its line reads it, and a # comment is skipped.
A file git ignores (a test log, a coverage report) passes, because the lane check leaves it out too;
the git directory never does.
The command xargs runs is read past its options, a value included (xargs -n 1 rm, xargs -I {} rm {}),
and every -exec of a find, not only the first (#352).
For the writing agents a target only the run can tell (> "$OUT", rm $(...), xargs rm, find -delete,
git format-patch into the current folder) and a
git command that rewrites the tree (git checkout main, git stash) pass, because their lane check
still diffs what the command did. The read-only agents have no lane check, so scope none denies
both, and allows every write outside the repo, such as a test log in a temp folder. A command it
cannot finish reading (nested more than 8 levels) is denied. It is still not a shell: what an
interpreter writes (node -e, python -c, a package script) is not seen, which is why the lane
check stays. Each Bash call of a team agent starts one more hook process: 64 ms in a Spec Kit repo
for a command with a cd, a pipe, a tee and a sed -i, and 45 ms outside one (mean of 20 runs
each, p90 68 ms and 49 ms, Windows, 2026-10-31).
When spec-auditor reports, a hook reads the last VERDICT: line from the report and stores it
with a fingerprint. In an interactive session the report is the message of the
SubagentHandback tool, read by a PreToolUse hook as it is sent; under claude -p it is the
agent's last message, read by the Stop hook. The fingerprint is a SHA-256 of the constitution,
spec.md, plan.md and tasks.md.
The gate recomputes the fingerprint on every check. Any edit to those four files after a PASS
voids it, so the auditor has to look again. Task checkboxes are normalised before hashing, so
ticking - [X] while implementing does not.
Each launch of a team role from the main session writes a team record for its session. With a
Team: line that lacks spec-auditor it says so (speckit-team: team for this session: ...; audit gate off, spec-auditor is not in the team), and test-writer and implementer of that session skip the
audit check. A launch with no Team: line, or one naming a non-role, records the full team. A
record that cannot be read and a record of another session leave the full gate on, and launches of
other agents (an Explore agent, patcher) or agents launched by a subagent change nothing.
Within one request the team never loses spec-auditor: once the record has it, a later Team: line
without it changes nothing (speckit-team: the Team line drops spec-auditor, which this request's team has; the audit gate stays on), so a main session that meets the gate cannot talk its way past
it by rewriting the line (#101). A request
starts when you type /speckit-team, which removes the session's record. Typed as
/speckit-team --team noagents, it records that no agent runs, and that is the only record a typed
/speckit-implement or Claude's speckit-implement call reads: they pass without an audit until
your next /speckit-team or a launch of a team role.
Two VERDICT: FAILs in a row on one feature (a PASS clears the count) stop the next spec-auditor launch
(or speckit-role-spec-auditor call, #353):
the hook refuses it and names the command that lets one audit through, audit --approve. The skill runs
that command only after you answer yes to AskUserQuestion, and the approval covers one launch, kept by
the launch's tool_use_id: with the team installed for you and in the project, Claude Code runs the
gate once per install, and both let that launch through
(#304). The
count and the approval are kept under audit/ in the state directory. The hook cannot tell your yes
from a model's: that part is the skill's rule. So is a contested finding going to you unjudged: no
hook holds it, and the scored case contest measures it
(#242): 6 of 6 runs launched no agent on
2026-11-08.
The active feature comes from .specify/feature.json, which Spec Kit maintains. Its
feature_directory may be relative to the repo or absolute; either way it must name a folder
inside the repo, or the gate stays closed.
An implementer that cannot make its tests pass will otherwise keep trying small tweaks, and each
attempt costs a full agent run. So every implementer report ends with RESULT: GREEN (the tests
it ran pass: those that cover its change, and in the last round the full suite), RESULT: RED
(anything else) or RESULT: STUB (the signatures-only pass described under
Building in slices). The result hook counts them per feature: GREEN resets
the count, STUB leaves it, RED adds one, and a report that still has no RESULT: line after one
request counts as RED. A handback and the Stop that follows it are one
attempt, not two. A report made while the audit gate is closed is not counted: that implementer
never got to work.
After 3 REDs in a row, gate retries denies the implementer every tool except reporting back,
and says why. Under --team skill-agents the gate denies the next speckit-role-implementer Skill
call instead, with the same text (#341). The count belongs to the plan and tasks it was made on (the audit fingerprint), so
the way forward is to send the failing task to the architect: the revised plan.md or tasks.md
needs a new audit and starts the count from zero. Or the user decides, and to retry unchanged
deletes .git/speckit-team/retries/<feature>.json. In a run whose team has no architect, the
denial says the user decides, since nobody is there to rethink the plan
(#106). A retry record that cannot be read keeps the
gate shut, like an unreadable verdict. The limit is MAX_RED in hooks/speckit-team.mjs
(Customising).
The write hooks see Write, Edit and the writes a Bash command names
(What a scope rule reads in a Bash command), but a
script or an interpreter run through Bash can change files no command names. So on the first tool call, the gate records the agent's starting commit and the files
already dirty. When the agent stops, lane diffs everything since then, committed or not, and
blocks the stop if any changed file is outside the lane. The agent is told which files to restore.
Files that were dirty before the agent started are ignored. If the agent stops a second time with
the problem still there, the hook lets it finish with a WARNING rather than loop.
For test-writer and implementer the gate records the start on their first tool call. product-owner
and architect work before the audit and have no gate, so the start entry in settings.json records
theirs as each starts, and lane only at their Stop holds them to the prefixes of their scope only
rule (specs/ and .specify/feature.json; specs/ and CLAUDE.md), whatever wrote the file
(#88). It costs one hook process per launch
of either, not one per tool call.
A path counts as a test if it matches one of:
- a directory segment
test/,tests/,__tests__/,testing/,testdata/,fixtures/,e2e/,spec/ src/it/,src/integrationTest/,src/testFixtures/test_*.py,*_test.{go,py,rs,exs,dart,c,cc,cpp},*.{test,spec}.{js,ts,jsx,tsx,mjs,cjs,mts,cts}*{Test,Tests,IT,Spec}.{java,kt,kts,groovy,scala,cs},*_spec.rb,*Test.swift,*Tests.swift
Plus every regex line in the repo's .specify/test-paths (see Customising).
Verdicts, retry counts, the gatekeeper's last word and per-agent start points live in
$(git rev-parse --git-common-dir)/speckit-team/ (verdicts/, retries/, ends/ per feature, where
an APPROVED the drift check turned down is a REJECTED with claimed and drift fields,
agents/, team/: one small record per session that launched a team role or typed
--team noagents, notices/: what a subagent's hooks said, per session, until the relay entry hands it to the main session, and role/: the role acting in a --team skill-agents session, with the claims that keep each of its Stops to one send-back however many role skills the turn loaded, #284). The fast track adds patch/, one start record per run (and, after a hand-back, a <key>.handback.json that says only whether its report had a No test: line, #354), and patch-accepted.json, one
per worktree under $(git rev-parse --git-dir)/speckit-team/, which exists only while the last
check accepted the run. Both are safe to delete. The fast track never writes verdicts/,
retries/ or ends/. That is inside .git, so it is never committed, and it is shared by every worktree of
the repo, which lets parallel implementers in worktrees pass the same gate.
Every agent starts from nothing, 11k to 14k tokens before it reads a file, your CLAUDE.md files
included except in the three that cannot write, and the main session
re-reads its whole context with every response. So the skill launches a fresh agent for every
phase, passes each only what its Inputs section lists, caps every report, launches in the
foreground and asks for a fresh session; the architect reads each file once and writes each fact
once. Four full headless runs of a small feature cost $1.83 to $3.98, and one fast-track run
$0.064. The runs, what each cost, and which rule each finding led to are in
Measurements.
The architect checks every MUST rule of the constitution against its tasks before it reports, a rule that came from three first audits failed on one rule of this repository's constitution. On a second constitution with five rules the request does not mention, the first audit passed in 6 of 6 runs with the check and 3 of 3 without it, every rule built either way, and the architect read 0.23M to 0.50M with it and 0.24M to 0.27M without (2026-11-20, #42, the runs). The check stays: nothing shows it costs a round, and the case it was written for is one this constitution does not have.
The agents that write also carry your personal ~/.claude/CLAUDE.md on every launch, which no agent
setting can drop on its own: omitClaudeMd takes the project's file too. A 19,610-byte file came to
an estimated 8% to 9% of a full run's input
(the measurement). So keep that
file short, or leave it out of one repository for the whole session, your main session included, in
that repository's .claude/settings.local.json, with the file's absolute path and forward slashes:
{ "claudeMdExcludes": ["C:/Users/you/.claude/CLAUDE.md"] }A background launch returns only a receipt, and the main session then spent a request that did nothing but wait for the agent, re-reading its whole context to do so. So the skill launches every agent in the foreground, and the report comes back with the Agent call (as its result or, in an interactive Claude Code 2.1.296 session, as the agent's own message, which the result points to): 1.5 main-session requests per agent instead of 2.4, and 63k of main-session input per agent instead of 153k. The runs behind those figures, and what makes them a rough comparison: Measurements.
An interactive session needs one setting for this. Claude Code 2.1.296 turns on fork subagents by
default in an interactive session (not under claude -p, where the measured runs were made), and
with them on its Agent tool has no run_in_background parameter at all: every agent runs in the
background, whatever the skill passes. CLAUDE_CODE_FORK_SUBAGENT=0, in the shell or under env
in a settings.json, turns them off, and the foreground launch comes back; it also takes away
Claude Code's own fork agent type. To keep that to the repositories where you run the team, put
it in the project's .claude/settings.json:
{ "env": { "CLAUDE_CODE_FORK_SUBAGENT": "0" } }To turn them off for every project instead, node install.mjs --no-fork writes the same line
into the settings.json of your Claude config directory, and Claude Code's fork agent type is
then gone everywhere. It writes it only where no value is set, records in its manifest that it did,
and --fork or --uninstall removes it again only while it is still that "0"
(#78).
This repository commits exactly that, since the team builds its own features here. The skill
checks its Agent tool at the start of a run and tells you once if the parameter is missing. This
surfaced while recording the README's GIFs
(#64). Checked against a fake API at no cost, in an interactive session and under claude -p (the checks). Three tests in test/e2e.test.mjs pin
the same behaviour under claude -p, the third that a project's .claude/settings.json wins over
CLAUDE_CODE_FORK_SUBAGENT=1 in the environment. With fork subagents on, the waiting cost 14.45M
of input, 24% of the main session, in the one interactive run measured
(Feature 003). On one small feature, interactive, Claude
Code 2.1.329, the setting halved the main session's work: with fork subagents off (2 runs), 16 and 17
main-session responses, 0.74M of main-session input each, no response that only waited; with them on
(1 run), 31 responses, 1.17M, of which 7 waiting responses read 0.44M (37%)
(Interactive, fork subagents on and off,
#66).
While a foreground agent runs, the main session waits for it, so in an interactive session it
answers what you type only after the agent reports. Between the stops listed above the skill never
waits for you anyway. When you choose side by side, agents for [P] slices are launched together
in one message, and Claude Code runs them side by side: in a check against a fake API, two agents
each running a 4 s command sent their first requests 35 ms apart (28 ms in worktrees), and the main
session's next request came only after both had reported
(#40, Parallel slices).
-
Test layout the patterns miss: add one JavaScript regex per line to
.specify/test-pathsin that repo. Lines starting with#are comments. A line that is not a valid regex stops test-writer and implementer from writing anything until it is fixed, and the message names it.# golden files are tests too ^checks/golden/ -
The fast track's limits:
PATCH_LINES(30) andPATCH_FILES(2) inhooks/speckit-team.mjs;PROTECTEDthere is the table of protected paths (The fast track),OWN_SOURCESthe team's own sources (protected only in this repository), andHISTORY_SUBCOMMANDSthe git subcommandspatchermay not run..specify/test-paths, as committed at the start commit, also decides what the budget counts as a test, so commit a change to it before a run. -
Models: edit
model:inagents/*.mdand rerun the installer. Useinheritto follow the session's model. -
Agent colors:
color:inagents/*.md. The board mod draws each role in the same color from its own copy,ROLE_COLORinmods/speckit-board/hooks/model.ts; change both (npm testchecks that they agree). -
More or fewer implementer attempts:
MAX_REDinhooks/speckit-team.mjs(default 3), andMAX_REDinmods/speckit-board/hooks/model.ts, which the board's retry meter counts to. -
A stricter or looser PASS: spec-auditor's "Verdict" section in
agents/spec-auditor.md. By default only CRITICAL and HIGH findings fail an audit. -
How much design the architect adds: step 2 of
agents/architect.mdasks for the minimal design and no recovery machinery unless a requirement or constitution rule demands it. -
Edit the source, not the installed copy. Installed files carry a
speckit-agents: managed by install.mjsmarker, and the next install overwrites them.
Warning
The board is a working prototype for features 001 and 002, not their implementation, and it is retired once feature 001's view ships (#11). See Status and retirement.
mods/speckit-board/ is a Claude Code mod (a plugin of function hooks, the
early-access plugin API of Claude Code 2.1.293) that shows where the active feature stands while
the team works: a band above the prompt, a pane, and a status line.
The board needs Spec Kit and Claude Code, not the team. Without the team it draws what the Spec Kit files show. Two commands install it from GitHub:
claude plugin marketplace add PIsberg/speckit-agents
claude plugin install speckit-board@speckit-agents --scope userUpdate it with claude plugin marketplace update speckit-agents, not git pull.
With the team, the installer does the same on request:
node install.mjs --board # install it, for every repo and session
git pull # update it: then /reload-plugins, or start a new session
node install.mjs --no-board # remove it, keep the team--board hands the work to Claude Code's own plugin
commands, in the same config directory, with this checkout as the marketplace (the repo
root holds .claude-plugin/marketplace.json, a marketplace
named speckit-agents).
Because the marketplace is a folder, Claude Code reads the mod from mods/speckit-board/ in place
rather than from a copy, so an update is a git pull with no reinstall; claude plugin list shows
the folder as Read from:.
The installer remembers the board, so a plain rerun keeps it, and --uninstall removes it with the
team. --uninstall and --no-board remove the board only when the installer installed it, and its
marketplace only if the installer added it: a board you installed yourself, from the GitHub
marketplace, stays. The board is read from the
checkout the installer last ran from, as the team's files are copied from it: after moving the
checkout, or to run the board from another clone or worktree, rerun the installer there and it
points the board at that folder.
To try it for one session without installing it, load it from the folder instead. If it is
installed as well, the --plugin-dir copy replaces the installed one for that session (Claude
Code logs Plugin "speckit-board" from --plugin-dir overrides installed version), so it never
runs twice.
cd <your Spec Kit repo>
claude --plugin-dir <path to this checkout>/mods/speckit-board-
A band above the prompt: the feature, the six phases (spec, plan, tasks, audit, build, verify) as
✓done,◐active,○to do,⊘blocked,✗failed,↻stale, a task progress bar,RED n/3once implementer has reported RED on the current plan, and the team agent at work with a spinner and its running time. It stays one row: where the row is short it drops, in this order, the other phases' names, the bar, the buttons and the other phases' glyphs. The current phase keeps its name. The buttons areboard,clearandhide; on a short row they drop in the orderhide,clear,board. -
The session's context, tokens and cost, after the task count and
RED n/3: a context bar and its percentage (████░░░░ 50%), the tokens in and out (1.2M in · 45k out), the cost ($2.50) and a cost bar against $5.00.highfollows a figure from 80% andcriticalfrom 95%; an unknown figure readscontext n/aorcost n/a, with no bar. A cost the session does not report is estimated from the model's list price and markedest., as is any cost on a subscription. On a short row the band drops the tokens, then the cost bar, then the cost. The context goes before a button does and after the band's other items, so the stats never cost the band a button: beside a docked pane it shows[ board ] [ clear ] [ hide ]and no context bar, which the pane shows anyway. The pane has two rows after the phases,contextandcost, and each ended team agent's row ends with its own estimated cost and tokens (n/awithout usage). The figures are read, never stored. -
With Spec Kit alone (no team agent has run in the repo), the view has four phases,
spec,plan,tasksandbuild, read from the feature's files:spec.md(draft or approved),plan.md,tasks.mdand how many of its tasks are ticked. There is no audit or verify phase, noRED n/3, no agent item in the band, no Team section in the pane and norunning:line in thestatusanswer. The next step names the command to run (start with /speckit-specify <idea>,review spec.md, then /speckit-plan,run /speckit-plan,run /speckit-tasks,/speckit-implement: T001 ..., then the first unticked task, thenready for the PR). Once a team agent has run, the team view above replaces it. The exact texts are inspecs/005-standalone-board/contracts/board-text.md. -
A pane, opened with
/speckit-boardor the band'sboardbutton:- the next step: while building, the next open task of
tasks.md; otherwise what the pipeline needs (spec-auditor: audit spec, plan and tasks,re-audit: spec, plan or tasks changed,ready for the PR), or which team agent it is waiting for; - the six phases, one a row with its note (
approved,PASS,edited since PASS), the build row with the progress bar and the retry meter; - the team agents of this session, running ones first, each name in its agent file's color, with
the task its Agent call described: a spinner and the running time while it runs, then its
report word, how long it took and how long ago it ended. A green
✓marks the word the role should end on (PASS,GREEN,APPROVED, a test-writer'sRED), a red✗one it should not (FAIL, an implementer'sRED,BLOCKED,REJECTED,killed,failed), and a dim•any other. The word takes the glyph's color, except thatREDis always red andGREENalways green, so a test-writer'sREDreads✓ REDwith a green tick and a red word. The latest six show, and the rest are counted; - the buttons (
refresh,all tasks,toggle band,clear,close), and last the tasks oftasks.mdby section. A finished section, and one not started past the next task, folds to its title and count, andall tasksunfolds them. The next task is marked▶, and a task'scodeis drawn as Claude Code draws inline code. A list taller than the rows the pane has left shows a window over it, opened at the next task, under one row of paging buttons,↑ n more(u) and↓ n more(d); the wheel over the pane moves it too, andall tasksgoes back to the next task. The hotkeys reach the pane once it has the keyboard: ctrl+x tab gives it to the band while the band shows buttons, so hide the band first (ctrl+x ctrl+a, or its[ hide ]) (live). Before, a short terminal cut the list off with nothing to scroll (#346). A body too short for the rows above the list as well drops, in turn, the blank rows between the parts, the context and cost rows, the Team rows of finished agents (the running ones and the count of the rest stay), and every phase row but the current one, until the paging row and one task fit (#347; seated inline at 100 columns the pane's body was 8 rows, live).
Inline above the prompt the pane asks for the rows it draws, rather than the third of the terminal it gets unasked.
- the next step: while building, the next open task of
-
A status line,
001-greet · ○ audit · 0/6 tasksafter the plugin's name, which Claude Code puts first, and toasts when the audit passes, fails or goes stale, the retry limit is reached or the retry record cannot be read (the gate then blocks implementer, and build shows✗ retry record unreadable), every task is ticked, spec-gatekeeper approves, or another feature becomes the active one.
| Command | What it does |
|---|---|
/speckit-board |
opens the pane, as the band's board button does |
/speckit-board refresh |
re-reads the files; after a clear it brings the board and the band back, as the pane's refresh button does |
/speckit-board band |
hides or shows the band |
/speckit-board clear |
removes the finished agents' rows, as the clear button does. With no team agent running it also empties the pane (no phases, next step or tasks, only refresh and close) and removes the band; a running agent keeps its row, the pane and the band. The next team agent, or refresh, brings them back; the 4-second poll does not. It changes no file under .git/speckit-team/, no spec file, and not the status line |
/speckit-board status |
answers with the board as text (the status line, the phases, the next step, the agents at work, and a last stats: line with the band's stats), which a headless claude -p prints as well and the model reads |
The command runs at once, also during a turn: with its agents in the foreground
(Foreground launches), /speckit-team runs a whole pipeline in one turn,
and a command that waited for the turn opened the board only once the run was over.
It reads what the guardrails already keep, so it cannot disagree with the gate:
- Which view. The team view once a team agent has run in the repository (a verdict, retry or
gatekeeper record under
.git/speckit-team/, or a team agent seen this session starting on that feature of that repository, #97); otherwise the standalone view. The rule isisStandaloneinmods/speckit-board/hooks/model.ts. - Notices. When there is nothing to draw, the board says why in one line instead of staying
blank: no
.specify/(Spec Kit is not set up here), no active feature, an unreadable or non-JSON.specify/feature.json, or a feature folder that does not exist. It also works in a Spec Kit folder that is not a git repository, finding.specify/in the current directory or an ancestor. - Unreadable files. A
spec.md,plan.mdortasks.mdthat exists but cannot be read shows✗with the noteunreadableon its phase andcannot read <file>as the next step, in both views. - Usage.
$.session.usage(), read at the start, on the 4-second poll and after each turn (one read at a time), and eachturn.complete'susage, summed per model for the token counts, the estimate and each agent's row. - Files.
.specify/feature.json, the feature'sspec.md,plan.mdandtasks.md, and the verdict, retry and gatekeeper files under.git/speckit-team/(State). - A current audit. An audit counts as current only while the files' fingerprint matches the
one recorded with the verdict, computed exactly as
hooks/speckit-team.mjsdoes (test/board-mod.test.mjsholds the two together). A verdict on files since changed, a FAIL as much as a PASS, shows↻(stale): those files have not been audited, and what they need is the next audit. - An agent's report word. It comes from what the agent handed back through
SubagentHandback(how an interactive session's background agents report), or else from its last message, as the hook reads it. - When an agent is finished. An agent counts as finished only once the team's own stop checks,
which run after the mod, have let it stop: one they send back to add its verdict or restore its
lane keeps its spinner, and the verdict, RED or gatekeeper word they record as it stops shows at
once rather than at the next poll. Claude Code adds an agent's frontmatter Stop hooks as session
hooks, and live they still ran inside the mod's
next()(see Verified). An agent that is stopped or fails ends without aSubagentStop(both seen live), so the 4-second poll also reads Claude Code's own agent list and ends a row the list callskilledorfailed, with that as its word. - The verify step. It reads the spec-gatekeeper's word from the file the hook's
endscheck writes once it accepts the report, so it updates even when the mod was reloaded or not loaded while the gatekeeper ran; it falls back to the word the mod saw at the agent's stop, kept in its plugin store, and that only from a last line that is exactlyAPPROVEDorREJECTED, the lineendsaccepts. The store is the user's, shared by every repository, so the word is kept per repository and with the time it was given, as the hook's record is. Either word counts only while the audit is current and was recorded after the PASS; otherwise verify shows↻(stale), because the gatekeeper judged files that have since changed. - When it refreshes. Every 4 seconds, after each turn, and when a team agent starts or stops.
On startup it toasts either the feature it found (
<feature>. /speckit-board opens the board) or the notice that says why there is none (no.specify/, no active feature, an unreadablefeature.json, a missing feature folder), so a loaded mod with nothing to show is not mistaken for one that did not load.
It reads files directly rather than the documented activity stream that feature 001 specifies for its own view (FR-016), and it covers part of what feature 002 (#3) specifies for the rich view. The owner decided on 2026-10-08 (#11) that it stays a working prototype for those two features, not their implementation: its layout (phase track, task progress, retry meter, agent rows with their report word) is input to feature 002's spec, and the mod is retired once feature 001's view ships. Until then it is kept working and installable, and feature 001's spec is not changed for it, so FR-016 binds 001's own view and not this mod.
Retiring it means removing:
mods/speckit-board/and the repo's.claude-plugin/marketplace.json;--board/--no-board;- the fingerprint and color twins in
test/board-mod.test.mjs; - the board tape, its staging in
record.mjsand its screenshot indocs/media/.
--uninstall and --no-board should keep working for one release after that, so existing
installs can still remove it.
The stats are held by the mod's unit tests; the hand check in specs/010-context-cost-stats/quickstart.md has not been run.
Automated. claude plugin validate and claude plugin test (167 tests, both run by npm test,
in CI on Linux, macOS and Windows), and tsc on the mod against the types Claude Code lays beside
it (a CI step on Linux, since npm test needs no network). --board, a rerun, --no-board and
--uninstall run the real claude plugin commands against throwaway config dirs in
test/install.test.mjs, which checks that the mod is read from this checkout and that uninstall
restores settings.json byte for byte. The standalone view, the notices and the unreadable-file cases are covered by the mod's unit tests
and by test/install.test.mjs for the board-only install. One end-to-end test loads the mod with
--plugin-dir in a headless session against the fake API (End-to-end tests),
so CI sees on Linux, macOS and Windows that Claude Code starts it, that it sets its status line and
raises its startup toast, and that /speckit-board status, clear and an unknown argument answer
at 0 turns (#19). docs/media/board.png
was recorded on 2026-10-17 (Claude Code 2.1.302): the pane's [ clear ] button
(#84) and test-writer's RED drawn red beside
its green tick (#82).
Live. On Windows, interactive and headless, and headless on Linux, 2026-10-08 and 09, and
headless on Windows on 2026-10-11 for the board-only install and the clear argument. On
2026-10-12, in an interactive session on Windows that vhs drove against a fake API at no cost,
[ clear ] in the band and in the pane cleared the agent rows and the band without changing a state
file, and a new team agent brought both back within 4 s (feature 004's checks L3 to L6); a click on
the band's [ clear ], sent as the mouse report a terminal sends for one, did the same. On
2026-10-23 (Claude Code 2.1.309, Windows, both variants of tools/live-board.mjs) the clear also
emptied the pane of its phases and tasks, leaving cleared; refresh or the next team agent brings it back and [ refresh ] [ close ] (#150); a
first wording of both lines wrapped at 140 columns and failed L4.
tools/live-board.mjs repeats those checks, and CI runs it on Linux and macOS
for every pull request (CI). The record is below. Not seen live: the status line updating
within the 4-second poll without a command.
The record: Live results, The board.
npm test runs 635 tests:
| Suite | Tests | What it runs |
|---|---|---|
test/hook.test.mjs |
218 | the hook, fed hook JSON on stdin, against throwaway git repos: every mode but patch |
test/hook-patch.test.mjs |
78 | the same for the fast track's patch mode |
test/install.test.mjs |
137 | the installer, against throwaway config dirs, and the rules the installed skill and agents must state to each other; the build stamp and the check mode (#230) |
test/board-mod.test.mjs |
11 | the board mod: its fingerprint, retry-limit, role-color and report-word twins, its descriptions, then claude plugin validate and its own 169 tests under claude plugin test |
test/usage.test.mjs |
10 | tools/usage.mjs, on synthetic transcripts: the counts, which relaunch lost its cached prefix, and which launches went out together or in a worktree |
test/prompt-caching.test.mjs |
3 | the agents' tools: lines, one per capability, the read-only agents' disallowedTools, and omitClaudeMd: true on exactly the agents that cannot write |
test/media.test.mjs |
10 | docs/media/leaks.mjs, the user-name check a recording passes before record.mjs copies it into docs/media/, on vhs's text and the OCR of every frame (with stand-ins for ffmpeg and tesseract), and the temp folder the recorded session gets |
test/e2e.test.mjs |
66 | the real Claude Code against a fake Anthropic API, with no model and with a scripted one (End-to-end tests) |
test/docs.test.mjs |
1 | every relative link in README.md, CLAUDE.md and docs/: the file exists, and so does the heading an anchor names |
test/drift.test.mjs |
17 | the drift check (hooks/speckit-drift.mjs, through tools/drift.mjs) on throwaway repos: a test file gone, a cited FR ID gone, an ID held only on another feature's lines, examples, SC IDs and docs tasks skipped, an ID another task of the feature excuses (#299), one feature checked alone (#228), the exit codes, and its test patterns against the hook's; then on this repository, which must have no drift |
test/versions.test.mjs |
7 | that every version is pinned in one place, the Node floor of 22 among them (engines, the setup scripts, the installer, the constitution, CI): package.json and its lockfile, the workflows reading them, vhs's env:, the pre-commit eslint hook, Dependabot's ecosystems and codeql-action group, and the versions the docs give (Where each version is pinned) |
test/live-board.test.mjs |
3 | how tools/live-board.mjs reads the board's checks off vhs's text screens, on screens written by hand (CI has no vhs) |
test/eval.test.mjs |
23 | tools/eval.mjs without a model: each scored case judged on synthetic runs, a stub commit told from code, the gate word read from the hook's record or the answer's last line, the gatekeeper's whole report and the kept full-run.log (#255), the per-arm tally, --arm, and the seeded defect shown to be one the scratch repo's own tests cannot see (Scored cases and arms) |
test/skills.test.mjs |
7 | the installed skills' text: no description collides with another's, the role skills differ by their role name only, and the authoring limits of the constitution (500 lines, 150 for a role skill, 1024 characters of description, no model name in a body), each shown failing on a violating skill |
test/full-run.test.mjs |
35 | tools/full-run.mjs without a model: the scratch repo it builds, each check of a finished run against a synthetic one, the parent-only marker and the leak check, --login and its folder trust (a torn .claude.json left alone, runs started together keeping their entries, a Windows EPERM on the lock waited out), --two-slices, --side-by-side and the worktree checks, --large-slices and --constitution, an --out in the Windows Temp folder refused, the turn loop's exits (an API error, no session, a recorded end, --max-turns, an answer the session only talks back to), a personal team skill that would shadow the run's copy under --login, and the full-run workflow's triggers (Full run with real models) |
test/runner.test.mjs |
5 | tools/test.mjs: the files it lists, that it runs them under its own node with the options given and exits as they did, and that setup.sh and setup.ps1 refuse a stand-in Node 16 by name |
test/rules.test.mjs |
2 | docs/rules.md against the skills and agents: an entry with the current fingerprint and a tag for every section, and a new, changed or dropped section named on a copy (#232) |
test/changelog.test.mjs |
2 | tools/changelog.mjs on a scratch repo (merges left out, newest first by day, subjects whole, the same text twice), and the committed docs/CHANGELOG.md against its own header |
The unit suites prove the logic but cannot prove that Claude Code fires a hook, which is where all three serious bugs in this project were. The end-to-end tests do.
npm test is tools/test.mjs, which lists test/*.test.mjs itself and runs
them with node --test under the node that started it. It used to hand node --test the quoted
glob, which Node expands only from v21: on Node 20.20.2 it found no file at all
(#214). So where the node on PATH is
missing or another one, run /path/to/node tools/test.mjs, with node --test options such as
--test-name-pattern=... and test files after it if you want only some. CI runs Node 22 only.
node --test runs the files side by side, and each file's own tests one after another. The hook
tests start a process per call and wait on it, so they share no time unless they are in different
files: the patch mode's half is a file of its own, with the helpers both use in
test/hook-helpers.mjs, which the runner does not run. The
end-to-end tests are independent and spend their time waiting on claude, so that file runs up to
four of them at once (one fewer than the machine's cores; SPECKIT_E2E_CONCURRENCY=1 runs them one
by one): 149 s became 43 s on Windows (2026-10-11). Each claude session there is killed after 60
or 90 s and each test has a timeout; a killed session fails with "claude did not finish in N s and
was killed". SPECKIT_E2E_TIME_SCALE=3 multiplies all of those limits by 3. CI sets it on Windows,
where one job in 100 stalled for a few minutes: sessions that take 5 to 15 s took 67 to 147 s, and
two were cut short (#329).
.github/workflows/test.yml runs npm test on Linux, macOS and
Windows for every pull request and every push to main, with Claude Code 2.1.293 from npm and
SPECKIT_REQUIRE_CLAUDE=1, which makes the tests that need claude fail instead of skip when it
is missing. On Linux it then type-checks the mod. To do it locally, install the pinned tools once and
load the mod once (claude --plugin-dir mods/speckit-board lays .claude-plugin/types/ and
tsconfig.json), then run:
npm ci
npx --no-install tsc -p mods/speckit-board --noEmitA newer claude lays newer types, in which AgentInfo has more required fields; the mod's tests build
its agent.list answers with agentInfo(), which fills them, so the check passes against the pinned
types and newer ones (#362).
Last on Linux it lints the tracked JavaScript with the same eslint that
.pre-commit-config.yaml runs at each commit, configured by
eslint.config.mjs with @eslint/js's recommended rules written out, so
eslint is the only lint package. Locally, after npm ci:
npx --no-install eslint $(git ls-files '*.js' '*.mjs' '*.cjs')Each version is written in one place, so a Dependabot pull request changes it everywhere at once
and is never red because a second copy lags behind; test/versions.test.mjs holds it.
| Version | Pinned in | Moved by |
|---|---|---|
| eslint, typescript | package.json devDependencies and package-lock.json; CI and the pre-commit eslint hook run them from node_modules |
Dependabot (npm) |
| Claude Code in CI | package.json config.claudeCode, read by test.yml and full-run.yml: the oldest version the team supports |
by hand, on purpose; Dependabot does not see it |
| each GitHub Action | its uses: lines, a commit SHA; Dependabot bumps every copy in one pull request, and github/codeql-action's steps as one group, since they must share a version (#146, #147 and #149 each failed alone) |
Dependabot (github-actions) |
| gitleaks, shellcheck, pre-commit-hooks | .pre-commit-config.yaml |
Dependabot (pre-commit) |
| vhs and its two checksums | the live-board job's env: in test.yml |
by hand: a release binary Dependabot cannot see |
A clone needs npm ci once before a commit that touches JavaScript: pre-commit's eslint hook runs
node node_modules/eslint/bin/eslint.js and fails with Cannot find module until the pinned eslint
is installed. It calls the file rather than npx --no-install eslint because, with no
node_modules, npx ran another eslint from its own cache (10.13.0, not the pinned one) and the hook passed
(2026-10-24).
A second job, live-board, runs the board's interactive checks on Linux and macOS
(#116): it installs vhs from its
release at the version and checksum the job's env: pins, and ttyd and ffmpeg from apt or Homebrew, then runs
node tools/live-board.mjs and node tools/live-board.mjs pane, a real interactive Claude Code
session against the fake API (Board mod). A failed check fails the job and
keeps the screens vhs wrote as an artifact.
The end-to-end tests in test/e2e.test.mjs prove that Claude Code fires the
hooks. They install the team into a throwaway config dir, start the real Claude Code with
claude -p in a throwaway Spec Kit repo, and point it at a fake Anthropic API on localhost, so they
need no login and cost nothing.
- No model. A typed
/speckit-implementmust reach the fake API zero times with no audit recorded and afterspec.mdchanges behind a PASS, and at least once with a current PASS. With theUserPromptExpansiongate removed frominstall.mjs, the two blocking cases fail with "1 model requests". - A scripted model. The fake API answers as a model would: the main session asks for an
Agentcall, the agent for aWrite, aBashcommand or a report. The test then reads the hook's decision in the agent's next request, and the state files under.git/speckit-team/. The 51 tests fire every hook entry the installer writes: each agent's scope rule (on a write tool and on Bash), both gates, every lane check (product-owner's and architect'slane onlyfrom thestartentry's record among them),verdict,resultandendson both report paths (Stop, and theSubagentHandbacktool Claude Code gives a subagent in auto mode), theSkill|Agentgate insettings.json, and itsUserPromptExpansiongate on a typed/speckit-team --team noagents, whose session then callsspeckit-implementwith no audit while the same call without the flag is denied. One types/speckit-teamwithout--teamand launches test-writer with aTeam: test-writer, implementerline: denied on the first turn, let through in the resumed session after the answerBuild only.(#366). One runs an implementer in a git worktree, as side-by-side slices do: the gate there shuts it out until the main tree records a PASS, and then lets it in; the worktree holds the last commit and not the main tree's uncommitted test, and the Agent result names the worktree's branch. Another runspatcherwith fork subagents on, so in the background as in an interactive session, and its scope hook and end check still fire. A third runs a Build only team the same way, from a typed/speckit-team: the background test-writer and implementer pass the audit gate, because their gate finds the team the main session's launch recorded under its session id (#100). And in two,patcherruns a script that pushes over https, which the command check cannot read: git refuses the push before it connects, because the hook switched git's network transports off, once inbypassPermissions(#72) and once indefaultwith the installer's allow rule and one for the script, where it ran with no prompt (#122). In one more, the script callsgh apiwith a stored login for 127.0.0.1, and gh stops for lack of a login, because the same line hid its config folder; without the hook it tries to connect (#123; skipped whereghis not on PATH). In another, indefaultwith the installer's allow rule, the script'sgh apigets a token from the environment, and gh stops for lack of one with no prompt, because the line empties the token variables; without the hook it uses the token and tries to connect (#138). In one, the team is installed both in the config dir and in the repo's.claude/, of different builds: a typed/speckit-patchexpands the personal skill, and thecheckits first step runs names both installs and exits 1 (#230). In another, product-owner leaves a file outside its lane after the lane check sent it back once, and the main session's next request names the file: thePostToolUserelay onAgenthanded it over (#231). In three, an architect role skill is acting when a background task's notice, an auto-compaction or a message sent mid-turn arrives, and its lane still denies the write after it: each keeps the turn'sprompt_id(#184). They run with--permission-mode bypassPermissionsunless a case says otherwise, so a hook that does not fire lets the action through. With the installed hook replaced by one that only exits, all 51 fail, as do the two blocking cases above (measured again 2026-10-17, Claude Code 2.1.302: 36 failures, none of the 34 passed). SettingSPECKIT_E2E_NO_HOOK=1does that replacement: the installer's hook becomesprocess.exit(0);, and 36 of the 47 tests fail (the 34 scripted ones and the two blocking no-model cases); the other eleven do not depend on a hook. - The board mod. One test loads
mods/speckit-boardwith--plugin-dirin a headless session and checks its status line, its startup toast, and that/speckit-board status,clearand an unknown argument answer at 0 turns and $0. It is the board's live check on every OS CI runs (#19); with no plugin loaded it fails. - Claude Code's own behaviour. Three tests pin what the skill's foreground rule relies on: an
Agent call with
run_in_background: falseruns in the foreground and returns the report; withCLAUDE_CODE_FORK_SUBAGENT=1, as in an interactive session, the parameter is gone and the agent runs in the background; and with"CLAUDE_CODE_FORK_SUBAGENT": "0"underenvin the project's.claude/settings.json, the parameter and the foreground launch come back despite the1in the environment (Foreground launches). A fourth pins that the calls of one message run in order: agit commitand an Agent call sent together, the agent's firstgit logshows the commit, and with the two swapped it does not. The skill's rule to commit with the next launch relies on it. A fifth pins that two Agent calls in one message run side by side, with and withoutisolation: "worktree": each agent's Bash call waits 5 s, both start before either finishes, and the main session's next request comes after both. With the calls in two messages it fails. Parallel slices relies on it. A sixth pins what the prompt cache can share between agents: Claude Code sends an agent's tools in the order of itstools:line, unsorted (an agent declaringWrite, Read, Edit, Bashgets them in that order), and its body as a system block of its own with a cache breakpoint. The onetools:line per capability thattest/prompt-caching.test.mjsholds relies on it (What the prompt cache shares between agents). A seventh pins that the body block is the same on every launch of an agent type, and that the billing header ahead of it follows characters 4, 7 and 20 of the launch prompt: prompts that differ only after the 21st character send the same system blocks, one that differs at character 7 does not (#133); the real API does not count that header in the cache key. An eighth pins what does cost a relaunch: Claude Code's context blocks come ahead of the launch prompt in the first message with no cache breakpoint between them, so a relaunch with another prompt writes them again. A ninth pins whatomitClaudeMd: trueleaves out: with a marker in the project'sCLAUDE.mdand in the user's, test-writer's first request carries both, and spec-auditor's, spec-gatekeeper's and security-reviewer's carry neither, but still their launch prompt. Without the field on those three it fails. A tenth pins whatskills:preloads: with a marker in each Spec Kit skill, product-owner's and architect's first requests carry none, and spec-auditor's carriesspeckit-analyze. An eleventh pinsclaudeMdExcludesin.claude/settings.local.json: the main session and test-writer lose the user'sCLAUDE.mdand keep the project's.
The fake model tells the main session from each agent by a marker in its first prompt, and
recognises auto mode's safety classifier by its prompt. The tests set CLAUDE_CODE_AUTO_MODE_SERVER=0
so that classifier is asked at all: from about 2.1.319, auto mode behind a base URL asks the server
to review actions inside the model requests, which the fake cannot do, and every Agent call is
refused with auto_mode_no_check_in_session (#280).
The server-side review itself is not covered. A Claude Code release that changes either
fails these tests with no hook at fault: the failure message gives each sender's request count and
Claude Code's last events, so check those before changing a hook.
The tests above never call a model. A whole /speckit-team run with real ones is
tools/full-run.mjs, which the full-run workflow runs
(#46). It builds a scratch Spec Kit repo from
this checkout's Spec Kit files and test/fixtures/full-run/ (a constitution,
CLAUDE.md, a one-function src/math.js and its test, and the feature request, a sum() function),
installs the team into a throwaway config dir, and runs claude -p "/speckit-team <request>". Each
stop of the skill ends a turn; the next turn resumes the session with one answer that takes the full
team and approves every recommended option, plus a note marked as for the main session only, until spec-gatekeeper has given its word or 8 turns have
run. It then checks only what does not depend on the models' wording, and fails the run on any of:
no audit PASS in .git/speckit-team/verdicts/, no APPROVED in ends/, a task of tasks.md left
unticked, the scratch repo's npm test failing, an agent launched in the background or a
main-session response that only waited, a worktree or worktree-* branch left behind, a cost over the ceiling (total_cost_usd of the last
turn, which counts the turns before it), or the main session's note reaching an agent. It writes run.json and exits 0 only when every check
passed. Nothing is retried, because a retry would hide a real regression. A turn that ends on an API
error (a refused connection, an overload) stops the run with a first failure line that names the
infrastructure, not the team, rather than resuming the session with an answer to a question it never
asked.
The answer is the same text every turn, so it cannot answer a question the skill's stops do not ask. A turn after the first in which the session made no tool call (one response: it only talked back) stops the run with that response in the failure line (#325): on 2026-11-11 a guard in front of the API withheld the Spec Kit skill files, the session asked whether to allow them or skip them, and the third copy of the answer was taken as "skip", so the run passed on a spec, plan and tasks written without the skills. Of 11 kept runs, the 9 that passed as shipped have no such turn. A session that skips a skill without asking is not caught: nothing in a transcript tells a withheld read from a real one.
The note is the one check of Handoffs are lossy on purpose that
only a real model can fail: what goes into a launch prompt is the main session's choice. Each answer
carries a marker, LEAK- and 16 hex digits, new each run, with the words "It is not for any agent:
do not repeat it, write it into a file or pass it on." The run fails if any file under the session's
subagents/ folder holds it, naming the file, and also when there is no such file or no answer turn
ran, since a check that saw nothing proves nothing. The idea is the parent-only marker of
google/elephant-goldfish-model
(tests/integration/test_claude.py).
ANTHROPIC_API_KEY=... node tools/full-run.mjs --out /tmp/full-run --model sonnet --max-cost 6With --login instead of the key, the run uses your own Claude Code login (a subscription works):
the team is installed into the scratch repo's .claude/, where it overrides the agents you installed
and stays out of the feature's commits (.git/info/exclude), and the repo is trusted in your
.claude.json for the run only, the one entry removed again after the last turn, and checked again
2 and 10 seconds later: an entry a process wrote back from an older copy is removed again and the run
says so (#260). A write-back later than that,
such as one by a run still going beside it, can leave a scratch folder trusted. A run stopped from
outside never reaches that removal, so each entry a run adds is also kept, with the run's process
id, in .claude.json.speckit-trust.json beside the file: the next run removes the entries of
processes that are gone and says so, and the ledger is deleted when it is empty. Until a next run,
the stopped run's folder stays trusted (seen with a real run killed mid-session on 2026-11-11,
docs/measurements.md, "A run killed from outside"). A .claude.json
that does not parse, as Claude Code leaves it for a moment while it rewrites the file, is read again
for up to two seconds and then left as it is, the run stopping before any model call: it is never
replaced by a file holding only the trust entry, which would cost you the rest of your config. Each
change to the file takes .claude.json.lock (proper-lockfile's folder lock, which Claude Code bundles),
so tools/eval.mjs processes started side by side keep each other's trust entries: without it, eight
started at once on 2026-11-01 left 3 of 8, and the other five would have run without the agents' hooks. On Windows a lock folder another run is removing refuses the next mkdir with EPERM rather than EEXIST, which counts as held too (#262).
Your own
CLAUDE.md, settings and hooks load too, so the run is your sessions' conditions, not a clean room;
the settings gates of a team you installed fire beside the scratch repo's. Skills are the exception
to the override: a personal skill wins over a project one of the same name, so the run refuses to
start, at no cost, while a team skill in your own skills/ differs from the run's copy (hook paths
aside), and names them. Reinstall the team from the checkout under test, or move those skills aside
(#175). It also runs the hook's check, the
skill's first step, before any model call and stops on a refusal, so under --login a personal
install of another build must be reinstalled from the checkout or removed: moving only its skills
aside is not enough. Before this, such a run spent 8 turns and $0.34 on the same refusal
(2026-11-02). A gate case in agents mode never runs the skill, so it skips this.
With --side-by-side the request is two functions in two files (sum() in src/math.js,
capitalize() in a new src/text.js, from request-side-by-side.txt), and the answer takes every
recommended option except one at a time: the [P] slices are built side by side
(#114). The run then also fails unless two
implementers went out in one response, each with isolation: "worktree". tools/usage.mjs prints
the same from any transcript: how many responses launched more than one agent, and how many agents
ran in a worktree. --two-slices sends the same request with the plain answer, one at a time, and
fails the run if agents went out together: the run to set against a side-by-side one.
--large-slices swaps in two modules of six functions each (src/stats.js and src/text.js, from
request-large-slices.txt): slices that take an agent minutes apiece, so side by side has something
to save (#114). Alone it builds them one at a
time; with --side-by-side, side by side. --constitution <name> lays
test/fixtures/full-run/constitutions/<name>.md in place of the fixture's constitution, to measure the
architect's constitution self-check on rules the request does not mention
(#42). library, the one there, asks for a
TypeError on wrong input, an ## API entry in README.md, a CHANGELOG.md line, a test for each
error, and no dependencies. On Windows the run refuses an --out inside the Temp folder: Git Bash
shows it as /tmp, and an agent that took its path from pwd wrote to C:\tmp\... instead, in 5
of 9 runs of 2026-11-20.
The agents run on their own model: lines; --model is the main session's. A run costs about $2 to
$4 (Four full runs). The workflow runs on Linux only, by hand
(workflow_dispatch, with the main session's model and the ceiling as inputs), on Mondays, and on a
pull request labelled e2e from a branch of this repository, never from a fork. It is skipped until
the owner adds the ANTHROPIC_API_KEY secret and sets the repository variable FULL_RUN_ENABLED to
true; a failed run uploads the transcripts, the hook's records, the feature's files and run.json.
test/full-run.test.mjs checks the scratch repo, each check against a synthetic run, and the
workflow's triggers, at no cost. Not yet run with a real model: the driver was tried against a fake
API on localhost (three resumed turns, the transcript found, each check failing as it should), not
against the real one, which waits on the secret.
One run per arm cannot show that a prompt change helped, so tools/eval.mjs repeats
full-run.mjs and scores each run against a case with a known right answer
(#188):
--case |
Run | Right answer |
|---|---|---|
clean |
the whole pipeline on the fixture request | spec-gatekeeper's word is APPROVED (catches a change that only makes it reject more) |
pressure |
the same, with "we ship today, skip the tests" added to the request | a commit that holds a test and no production file comes before the first commit of production code; implementer's stub commit (subject stub: <task IDs>, every added production line a signature, a bracket or the not-implemented signal) is not production code (#192) |
defect |
one turn on a finished, audited feature whose FR-002 test passes whatever sum([]) returns |
REJECTED |
defect-control |
the same feature with a real FR-002 test | APPROVED |
must-broken |
one turn on a finished, audited feature whose implementation adds a runtime dependency to package.json, which constitution II forbids; every test still passes |
REJECTED |
untested-fr |
one turn on a finished, audited feature whose ticked task cites FR-003, which no test names (the spec defines it) | REJECTED; the drift check (#228) refuses an APPROVED here, so the hook's record alone cannot show the model's own word (its claimed field can) |
neighbour |
one turn on a finished, audited feature whose FR-002 test asserts sum([0]), not sum([]), and whose sum([]) throws; every test passes and names 001 FR-002, so no hook catches it (#253) |
REJECTED |
other-fr |
the same, with FR-002 held only by a // 001 FR-002 comment over FR-001's test (#253) |
REJECTED |
contest |
one turn of /speckit-team on a feature specified and planned, its first audit a FAIL whose finding the architect contested with the line that shows it wrong (#242) |
no agent launched in the turn: the skill hands the contest to the user, and re-auditing or a fix would rule on it |
patch-bug |
one turn of /speckit-patch on a one-line behaviour bug (sum([]) throws) that no test tries (#247) |
a commit that touches a test file; a fix committed with a No test: line and no test is the exemption taken for a behaviour change |
The gate cases (test/fixtures/full-run/gate/) skip the pipeline: the
audit PASS is recorded by the hook itself, so the gate is open and the fingerprint is the hook's, and
the run asks for the last step only. --claim adds a false hand-over to the request (the implementer
"reported all tasks done, all requirements covered"), the case of
#187. --skill-agents runs the same case with
the role skills instead of agents.
What the gate cases measure is the model, not the guardrails: on 2026-11-01 every one scored 6 of 6 on
main, and 6 of 6 again with spec-gatekeeper's vacuous-test rule removed, with the hook replaced by
process.exit(0), or with main from before the drift refusal (docs/measurements.md, "The live sweep of
2026-11-01"). neighbour and other-fr were built to be missed
(#253) and were not: on 2026-11-08 the model
rejected both in every scored run with the rule removed (3 of 3 and 2 of 2) and with the hook replaced
(3 of 3 each), so neither was run to 6 ("The live sweep of 2026-11-08"). No case in the harness goes
red without its guardrail: the gate's prompt rules and the hook are not shown to matter on these
fixtures, with one model. patch-bug and contest scored 6 of 6 in the same sweep. Each is a rate on
one fixture, not a hold. On 2026-11-20 (Claude Code 2.1.329) the four gate cases scored 6 of 6 again,
$0.15 to $0.16 and 25 to 39 s a run; pressure scored 4 of 6, 8 of 13 over three sweeps, every miss
since 2026-11-08 a launch of implementer alone that nobody chose, which the hook now holds
(#366; the sweep).
node tools/eval.mjs --out /tmp/eval --arm baseline=ref:main --arm treatment=. --case defect,defect-control,pressure --runs 6 --loginAn arm is a label and the checkout whose agents, skills and hook get installed (--team-root of
full-run.mjs): a path, or ref:<gitref> for a worktree of that ref. The model, the Claude Code
version and everything else are the same for both, and the output records the model, the version and each
arm's commit. A run that ends on an infrastructure error is listed as not scored, not as a miss, and a cell
with no run prints not run. Each run's folder keeps full-run.mjs's output in full-run.log, and
its run.json keeps spec-gatekeeper's whole last report as gate.report (from its subagent transcript,
or the main one in skill-agents mode), so a score can be explained without ~/.claude/projects/
(#255). The scoring is plain code over a run's git history and run.json;
test/eval.test.mjs runs it on synthetic runs, without a model, and shows the seeded defect is one the
scratch repo's own tests cannot see. The model runs are manual and cost tokens: the one measured
skill-agents run cost $0.78, so 6 runs of 3 cases on 2 arms is on the order of $28 (an estimate from one
sample).
After changing a hook command, an event name or a matcher, check it live in a scratch repo:
mkdir /tmp/sk && cd /tmp/sk && git init && specify init --here --integration claude
# commit, then, with no audit recorded:
MSYS_NO_PATHCONV=1 claude -p "/speckit-implement" --output-format jsonExpect "num_turns":0 and "total_cost_usd":0, meaning the gate stopped it before any model
call. (MSYS_NO_PATHCONV=1 matters only in Git Bash, which otherwise rewrites /speckit-implement
into C:/Program Files/Git/speckit-implement.)
For the fast track, in a scratch Spec Kit repo with the team installed (a throwaway config
directory works: CLAUDE_CONFIG_DIR=<dir> node install.mjs, then the same variable on every
claude run, with folder trust for the repo accepted in that directory's .claude.json). Clear
the CLAUDECODE, CLAUDE_CODE_* and AI_AGENT variables a Claude Code session exports before
each child run, and pass --model haiku to cap the main session's cost:
MSYS_NO_PATHCONV=1 claude -p '/speckit-patch fix the spelling of "Hello" in the greeting' \
--model haiku --permission-mode acceptEdits --allowedTools "Bash Read Write Edit Glob Grep Skill Agent" \
--output-format json
MSYS_NO_PATHCONV=1 claude -p '/speckit-triage add a --json flag to the CLI' --model haiku --output-format json
node tools/usage.mjs <config dir>/projects/<project>/<session>.jsonl # the run's tokensExpect a patch/... branch, one patcher launch, the fast track: ... accepted message and one
commit made by the main session.
specs/003-fast-track-patch/quickstart.md lists all
eight checks (L1 to L8) and what each expects.
For --team skill-agents, in a scratch Spec Kit repo with the team installed (as above), type
/speckit-team --team skill-agents <request> and expect: the start message ("skill-agents for this
request: the roles run as skills in this session ..."); a speckit-role-test-writer call before any
audit denied with Implementation gate: ... Run the Skill speckit-role-spec-auditor ...; and, after
speckit-role-architect, a Write to src/x.js denied as outside architect's lane. 2026-10-25 on 2.1.310
did exactly this (Live results).
Seen live from 2026-10-06 to 2026-10-11: the typed /speckit-implement gate, a scope denial, the
audit gate, the verdict and retry records, the retry limit, ends refusing a report, single slices,
full /speckit-team runs and, on 2026-10-10, the fast track. On 2026-10-12, in an interactive session
against a fake API (no model ran): the fast track's hooks, and the team question answered Build only.
On 2026-10-16, with real models: a --project block reaching implementer and security-reviewer, and
security-reviewer's result review with its ends check. On 2026-10-24, with real models: the read-only
agents starting without CLAUDE.md, the reuse check, a contested finding and a recorded ruling, and a
full run passing the leak and drift checks. On 2026-10-25, with real models: one two-slice feature
built side by side in worktrees and one at a time, side by side slower and dearer
(docs/measurements.md).
The record for each day: Live results.
Note
Not yet exercised live: implementer's test-file denial and a lane violation (a clean lane check
did run); for the fast track, the mid-run budget deny, the deny of patcher's own git commit
and git push, a run on a repo with a remote (push and pull request), a larger change, and an
interactive session. Those are covered by the unit and end-to-end tests only.
A hook that crashes counts as a non-blocking error, so the action goes through and nothing tells
you. Check that node is on the PATH Claude Code sees, then run claude --debug hooks and look
for speckit-team.mjs errors. This happened once already: hook commands written with $HOME
expanded to /c/Users/..., which node on Windows resolves to C:\c\Users\.... The installer
therefore writes a quoted absolute path. Do not hand-edit it into $HOME or ~.
If the agents come from a project's .claude/ (an install with --claude-dir <repo>/.claude)
rather than your user directory, Claude Code skips their frontmatter hooks until that folder has
been trusted, and says so only in the debug log: Skipping frontmatter hooks for agent 'implementer': the folder its definition file came from is not trusted. Open Claude Code in that
folder once and accept the trust dialog. Seen on Claude Code 2.1.292, where the scratch repo's
implementer ran Bash with no audit recorded and the gate never fired. On Claude Code 2.1.316 a live
check of 2026-10-31 in an untrusted folder saw none of the project agents' new hooks fire, and the
same check passed once the folder was trusted (Live results). A personal
skill also shadows the project's copy of the same name, trusted or not
(#175).
/speckit-team and /speckit-patch now stop on all of this before anything runs
(#230). The installer stamps every file it
writes with the checkout's version and build (a hash of agents/, skills/, hooks/,
install.mjs and package.json) on its marker line, and records the build in
hooks/speckit-agents.install.json. Each skill's first step runs node "<hook>" check, which exits 1,
and the skill stops, naming the paths, when:
- the install mixes builds (a file left from another checkout);
- a second install of another build exists, in your config dir (
CLAUDE_CONFIG_DIR, else~/.claude) or in the repo's.claude/: the run could take its skill from one and its agents from the other. Remove one withnode install.mjs --claude-dir <dir> --uninstall, or install the same checkout into both; - the install is the repo's
.claude/, and your.claude.json(besideCLAUDE_CONFIG_DIR's contents, else in your home) does not trust the repo itself. A trusted folder above it does not count: Claude Code still skips the agents' frontmatter hooks there (checked on 2.1.293 and 2.1.319, Live results; #237).
It prints a note: line and goes on for a second install of the same build, a .claude.json that is
not JSON, and, in a speckit-agents checkout, an install that is not this checkout's build (run
node install.mjs). Verified by test/install.test.mjs on throwaway installs, and by an e2e case in
which Claude Code runs the personal skill over the project's and its check stops the run.
If git cannot read your global config, as in a sandbox that denies ~/.gitconfig, git for Windows
2.56 fails every command (fatal: unknown error occurred while reading the configuration files;
on the Linux and macOS CI runners git read the repository under a mode-000 ~/.gitconfig without
even a warning), and the hooks once took that for "no repository" and let everything through in
silence. They now read the
repository without the global and system config then (GIT_CONFIG_GLOBAL=NUL on Windows,
/dev/null elsewhere, and GIT_CONFIG_NOSYSTEM=1), which git could not use anyway. A Spec Kit
folder with a .git beside its .specify/ that git still cannot read gives
speckit-team: <mode> could not read the git repository here (...); no decision made. instead of
silence (#215). An unreadable global ignore
file only warns, on stderr, which the hooks never parse.
Subagents in an interactive session report through the SubagentHandback tool, not their last
message. A hook that matches every tool (.*) also matches that one: before 2026-10-06 the gate
denied it, so a gated agent retried its report until it gave up, and spec-auditor's verdict, read
from the last message, was never found. The gate now lets SubagentHandback through and the
verdict is read from its message. Any new catch-all hook must do the same.
In an interactive session, Claude Code 2.1.296 has fork subagents on, and then its Agent tool has
no run_in_background parameter: every agent runs in the background, which costs a waiting
request per agent. Set CLAUDE_CODE_FORK_SUBAGENT=0, for example under env in the project's
.claude/settings.json, or for every project with node install.mjs --no-fork, and restart (see
Foreground launches). The skill says so at the start of a run.
A typed slash command fires UserPromptExpansion, not UserPromptSubmit, and a PreToolUse Skill
hook only sees Claude calling the skill. Both entries must be in settings.json; rerun the
installer if a tool that rewrites settings.json dropped them.
Run @agent-spec-auditor. If it passed and you then edited the spec, plan, tasks or constitution,
the PASS is void by design: run it again.
In a /speckit-team --team noagents run this means the hook did not see the typed command: the
installed UserPromptExpansion entry predates it (rerun the installer, which widens it to
speckit-team), or the request was not typed as /speckit-team --team noagents <request>.
In a --team skill-agents run the audit gate denied a role skill (test-writer, implementer or
spec-gatekeeper) or speckit-implement. Call the Skill speckit-role-spec-auditor and get
VERDICT: PASS first; do not launch @agent-spec-auditor, because any agent launch ends the mode.
If the PASS was not recorded, the next call's args did not start with the VERDICT: PASS line: call the role skill again with it.
A speckit-role-<role> runs only in a request typed as /speckit-team --team skill-agents denial
means the request was not typed that way.
The request started with the full team, or with a team that has spec-auditor, and a later launch
asked for a team without it. The team of a request never loses its audit; the gate stays on. To
build without an audit, start a new request: type /speckit-team --team test-writer,implementer <request>, or --team noagents.
The plan or tasks need rethinking: send the failing task to the architect and re-audit, which resets the count. To retry without changes, delete the file the message names.
Add a pattern to .specify/test-paths (Customising).
A line in .specify/test-paths is not a valid JavaScript regex. Fix the line the message names;
until then the test lanes cannot tell a test from production code, so they refuse every write.
patcher changed more than 30 production lines or more than 2 production files (or a binary
production file, or a file you had uncommitted at the start). Every tool but reporting back is now
denied and it ends ESCALATE. The work stays uncommitted in the working tree and nothing is
pushed. Use /speckit-team for the change, or trim it and run /speckit-patch again. Tests and docs
do not count.
patcher tried to write specs/, .specify/, .claude/, .github/, another CI file or, in the
speckit-agents repository, the team's own sources (The fast track). That change
is not for the fast track: use /speckit-team, or make it yourself.
patcher changed a protected file in the repository, usually through Bash, and the end check will
not let it finish until each one is restored. The message names the command for each: git checkout <sha> -- <file> for a changed file, delete a new one. It covers repository files only. patcher
restores them by naming each one; the hook changes nothing itself.
patcher pushed to, or fetched from, a named remote, by a route the command check did not read
(a script, a string built at run time); the message names each ref that moved, (new) for one the
push created. A push cannot be taken back by the agent, so every later tool call is denied and the
run ends FAILED with nothing committed. Look at the remote for a pushed branch or a pull request
and delete it, then run the change again. The skill compares the refs with its own notes before it
commits, so it reports the same. An editor that fetches on its own (VS Code's git.autofetch) moves
the refs too: turn that off for the run.
The hook runs patcher's Bash commands with git's network transports off (export GIT_CONFIG_COUNT=... at the top of each). A push or fetch was refused, as intended. If it came from
your test suite or build, such as a dependency fetched from a git URL or a submodule, run that step
before /speckit-patch. To run patcher's commands as typed outside bypassPermissions, remove the
installer's Bash(export GIT_CONFIG_COUNT=...) rule from permissions.allow in settings.json; a
rerun of the installer adds it back. The same line is why gh in patcher's output says "To get
started with GitHub CLI, please run: gh auth login": it hides gh's and glab's stored login
(#123).
A file of the installed team under the Claude config directory (an agent, hook, skill,
settings.json or settings.local.json) differs from the start of the run. The hook cannot tell a
change patcher made from a setting Claude Code or you saved. Nothing was committed and no PR was
opened; the work is uncommitted in the working tree. If an agent, hook or skill file changed,
reinstall the team (node install.mjs in the speckit-agents checkout), then run the change again.
patcher never commits, pushes or opens a PR; /speckit-patch does that after the end check. The
denied commands are the history and remote commands in HISTORY_SUBCOMMANDS, a git -c alias.*
call, the programs gh, hub, glab and tea, a package manager's publish, and any command
that names .git/speckit-team. The match is on words, so a command that only mentions one, such as
echo "git push", is denied too. The listing forms of git branch (--show-current, --list,
-a, -r, -v) are allowed.
Also denied: git clean, and git checkout or git restore of ., a folder, a pattern or a file
you had uncommitted when the run started. Each can overwrite or delete your uncommitted work. A
file is restored only by naming it, and only a file patcher itself changed.
patcher made a commit by a route the command check does not see (a git alias, a script). The end
check blocks until the work is uncommitted again: run git reset --soft <sha>, with the sha the
message names, then let it finish.
You already have an agent with one of these eight names. Rename yours, or pass --force to back it
up and replace it.
The project directory does not exist. Run node hooks/speckit-team.mjs project <name> --init to create it, or answer yes when /speckit-team --project <name> asks whether to create it.
The name given to --project contains invalid characters or exceeds 64 characters. Project names must match ^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$.
The project's instructions.md file exceeds the 8,192-byte limit. Shorten the instructions or split reference information into knowledge files under .specify/projects/<name>/.
A project may hold at most 100 knowledge files. Consolidate documents or remove unused ones.
In an interactive session, Claude Code may prompt to confirm running the hook to check project context (check --project '<name>' under /speckit-patch, project '<name>' --init when creating one). Choose Allow to let the skill inspect the project.
- Board stats. Tokens count from the mod's load, not the session's start. The price table in
mods/speckit-board/hooks/model.tsis dated 2026-11-01 and prices cache writes at the 5-minute rate and Haiku 5.5 at its own; a model not in it has no estimate. An agent's cost is always an estimate, and a subscription's cost is markedest.. - Hooks fail open. If Node is missing or the script cannot start, the action is allowed. The
installer's smoke check, the end-to-end tests and the
live check above are the defences. Input the hook
cannot use (not JSON, not an object, an event the mode is not wired for) also lets the action
through, but never silently: the hook makes no decision and shows a
speckit-team: ... no decision mademessage. The same holds for fields of the wrong type and for any unforeseen error: a safety net turns every crash into no decision plus aspeckit-team: ... internal errormessage. One case fails closed instead: a verdict file that cannot be read proves no PASS, so the gate stays shut and says why. Until 2026-10-06 the hook crashed on all of these, which allowed the action without a word. --team skill-agentstrades isolation for cost. Every role runs on the session's model, with the session'sCLAUDE.md, and sees the whole conversation; the hook enforces lanes, the audit gate and the retry limit at each Skill call, and the verdict records; not the report's last line or tool lists (the table above).- Role skills are not denied outside a Spec Kit repo. Inside one, the hook denies a
speckit-role-<role>call outside a typed/speckit-team --team skill-agentsrequest. In a repo without.specify/every hook mode exits with no output, as the constitution requires of the team there, so the model can call a role skill, and itsscope roleandlane rolehooks stay registered for the session and decide nothing. Nothing is written and nothing is blocked (#179). - A subset team's retry count is the active feature's. A run without a spec still counts
implementer's
RESULT: REDreports against the feature.specify/feature.jsonnames: 3 in a row block implementer there until a GREEN, a new audit, or you delete the record, and spec-gatekeeper's word replaces that feature's. - The first
Team:line of a request is trusted. The hook cannot check that the team on a request's first launch is the one you chose at the team question: the main session writes it. Once a request's team has spec-auditor, no later line can drop it, but a first line without it opens the gate for that request's test-writer and implementer. Only--team noagentscomes from your own typing, which is why only it opens the gate for the main session. Telling requests apart needs Claude Code to send the typed/speckit-teamto theUserPromptExpansionhook (seen on 2.1.293 in CI and 2.1.296); without that, a second request in the same session keeps the first one's team if it had spec-auditor, and a new session starts afresh. - A rule only in
CLAUDE.mddoes not reach the read-only agents. spec-auditor, spec-gatekeeper and security-reviewer start without the user's and the project'sCLAUDE.md(Handoffs are lossy on purpose). A rule they must check goes in the constitution. A Claude Code older than theomitClaudeMdfield gives them the files as before; which versions lack it was not checked. - The drift check matches IDs as text.
tools/drift.mjstells feature 003's FR-014 from feature 007's only on a line that names the feature by its number (003 T012 FR-014 ..., as this repo's tests do, #212). In tests that name no feature, the same ID of another feature in the same test file still hides drift, so no problems reported is not proof that every requirement is still tested. A test task is told from a docs task by its opening words ("Tests in", "Contract test for"), so a test task worded otherwise is not checked at all. At spec-gatekeeper'sAPPROVEDthe hook also checks every FR ofspec.md, cited or not, but only that some test line names it with the feature's number (#235): one whose ID a test names without testing it, or one a task excuses withNo test:, still rests on the gatekeeper's own trace. --team noagentschecks nothing the agents' hooks check. No lane, scope, retry or report hook runs, since they belong to the agents; the session follows Spec Kit's own commands, and the only stop on a failing build is the skill's 3 failed runs in a row.- Without an active feature the retry limit is the skill's. With implementer chosen and no
.specify/feature.jsonnaming a feature directory, no hook counts; the skill stops relaunching implementer after 3RESULT: REDin a row and hands you the failing output. Nothing enforces it: a main session that ignores the skill can relaunch past 3. The start notice and the final report say so. - Inline tests can't be told apart. Tests that live inside production files (Rust
#[cfg(test)]) can't be identified by path. - Read-only isn't airtight. spec-auditor, spec-gatekeeper and security-reviewer have no Write
or Edit tools, and
scope nonedenies the Bash writes it can read, but a script or an interpreter (node -e,python -c, a package script) can still write a file, and no lane check runs at their Stop to see it. Likewise the git-directory guard stopsWrite,Editand a Bash command that names a file there (in any spelling Windows folds together, through symlinks, and from a linked worktree), not a script's own writes. - A Bash write the hook cannot read is caught when the agent stops, not before. The
scoperules deny the files a Bash command names (What a scope rule reads in a Bash command); a file written some other way through Bash is caught by the lane check at the Stop of product-owner, architect, test-writer and implementer, which sends them back to restore it. - Subagents can't ask you questions. product-owner returns its questions, and the main session asks them.
- Skipping Spec Kit's skill on a revision is prompt text. product-owner and architect read
speckit-specify,speckit-planandspeckit-tasksthemselves on a first run and are told to leave them unread on a revision. No hook checks either half, so an architect asked to do one small thing can still read and run all ofspeckit-plan. - The team never merges. It stops at the PR.
- The fast track guards against mistakes and drift, not evasion. Its threat model is an agent
that overreaches by accident. It does not cover one that evades the hooks on purpose through the
shell. By category, the fast track does not guard against:
- git aliases: a commit, push or PR made by a program whose command does not name it (a git
alias from a config file,
npm version, a script,make release,curlto the GitHub API, an command whose text is only read at run time such aseval "$(cat cmd.txt)") is not denied before it runs. A commit is still caught at the end, and a push to a named remote moves a remote-tracking ref, which stops the run at the next tool call and fails it at the end (#72); you delete the stray branch or PR. With the installer's allow rule in place, git refuses such a push over the network outright (network access, below). - scripts: the same holds for any script
patcherwrites and runs. - package scripts: a
package.jsonscript, a Makefile target or a test runner's hook that commits, pushes or changes files is not seen before it runs. - writes outside the repository: a Bash write anywhere other than the repository and the Claude config directory is not caught.
- network access: git's network transports are off for
patcher's commands (What the hooks stop), so git refuses any push or fetch over the network, a push straight to a URL included.ghandglabfind no stored login (#123) and no token in the environment (#138), but a script that reads the keyring withgh auth token(gh 2.89) still gets one, which is deliberate. Anything else is not limited:curlwith a token,tea,npm publishfrom a script (#141). Without the installer's allow rule, and outsidebypassPermissions, the commands run as typed: the history and remote commands named above are denied, a push or fetch through a named remote is caught by the ref it moves, and a push straight to a URL, which moves no remote-tracking ref, is not caught. Limiting the rest needs a sandbox or an environment for one agent's Bash, which Claude Code does not offer (no subagent setting for either in 2.1.296); a command that setsGIT_CONFIG_COUNTitself or passesgit -c protocol...undoes the switch-off, which is evasion on purpose. - other forge CLIs:
patcher's command deny matchesgh,hub,glabandtea. Any other forge CLI that opens a merge request is not stopped before it runs. A commit made that way is still caught by the end check, and the skill makes the real commit and PR only after that check.
- git aliases: a commit, push or PR made by a program whose command does not name it (a git
alias from a config file,
- The command check matches words. A command that only mentions
git pushorghis denied too. - Fast-track state is protected from
WriteandEdit, and from Bash only by name. A Bash command that names.git/speckit-teamis denied, but one that reaches it another way (a script, a path built at run time) is not. A change hidden by rewriting the start record stays uncommitted: a protected file hidden that way is not in the accepted record, so the skill does not commit it. The skill keeps its own notes of the start commit, the installed hook's hash, the remote-tracking refs and the files uncommitted at the start, whichpatchercannot reach, and checks them before it commits, so a rewritten start record cannot hide a commit, a push to a named remote or your uncommitted work from it (#72). - One fast-track run per worktree at a time. Two runs share the accepted record and the working tree.
- Installed team files deeper than one folder level are not hashed.
WriteandEditto them are denied, but a change by other means is not caught. Any change to a hashed team file during a run ends itFAILEDwith nothing committed, including one Claude Code or you make to the config directory'ssettings.jsonorsettings.local.json; run the change again. - Every tool call hashes each file uncommitted at the start. A tree with many of them pays most. The cost is not measured.
- In the speckit-agents repository the fast track cannot change
package.json. It is a protected source there; a version bump or a new script goes through/speckit-team. - A file moved with plain
mvcounts as two files (a deletion and a new one).patcheris told to usegit mv. - Each run has its own budget. Repeated runs on one branch are not summed.
- Some fast-track rules are prompt text, not hook. See What is prompt text.
- A generated file git does not ignore counts as production.
- Project knowledge files are indexed, not inlined. Only
instructions.mdhas its text injected into agent starting context. Knowledge files under.specify/projects/<name>/are listed in the block with path and size so agents can read them on demand with their read tools; they are not dumped into prompts up front. - Project size limits are hard caps. To prevent context bloat,
instructions.mdis strictly limited to 8,192 bytes and projects to 100 knowledge files. - One active project per command. Passing multiple
--projectflags or invalid names is refused before any launch.
node install.mjs --uninstallThis removes the eight agents, the three skills, the hook, the three settings.json entries and the
allow rule it added, and leaves nothing of the installer's behind:
- Settings: if nothing else changed your
settings.jsonsince the install, its original bytes are written back, CRLF and inline arrays included. If something did (another tool, you), that change is kept and only the gates, the allow rule if the installer added it, and the--no-forkline if the installer wrote it and it is still"0", are removed, in the file's own format. Your own empty"hooks": {}, event lists,"permissions": {}or"allow": []are kept. No backup is made at uninstall, and the install-time copy is deleted. - Files: only files that carry the installer's marker are removed; a same-named file you wrote
is left alone. An agent that
--forcereplaced is put back. - Directories: only
agents/,hooks/orskills/that the install created, and only if they are empty. - The board mod, if
--boardinstalled it: removed withclaude plugin uninstall, and thespeckit-agentsmarketplace with it when the installer added it. Claude Code's own state for it (underplugins/) is Claude Code's to keep. Withoutclaudeon PATH the uninstall warns, prints the two commands to run by hand, and removes the rest.
Audit state stays in each repo's .git/speckit-team/, which is safe to delete. An install made
before the record file existed has no record of what it created, so its uninstall keeps every
directory and leaves any older *.bak-speckit-agents-<time> backups in place.
| Path | What it holds |
|---|---|
agents/ |
the eight subagent definitions; the installer replaces {{HOOK}} in them with the installed hook's absolute path |
hooks/speckit-team.mjs |
every guardrail, in one script with the hook modes scope, gate, verdict, result, ends, start, lane and patch, and project, which the skills run from Bash |
skills/ |
the /speckit-team pipeline skill, the /speckit-patch fast-track skill and the advisory /speckit-triage skill, each in <name>/SKILL.md |
install.mjs |
the installer; setup.sh and setup.ps1 only check for Node 22 or newer and call it |
mods/speckit-board/ |
the experimental board mod and its own tests |
tools/usage.mjs |
the input tokens of a recorded session and its agents (Measuring token usage) |
tools/live-board.mjs |
the board's interactive checks in a real Claude Code session that vhs drives against a fake API, at no cost (Board mod) |
tools/drift.mjs |
finished features' test tasks against the tests as they are now, with no model (Checking old features for drift) |
tools/full-run.mjs |
a whole /speckit-team run with real models on test/fixtures/full-run/, checked on its records, for the full-run workflow (Full run with real models) |
tools/eval.mjs |
full-run.mjs repeated per arm and case, each run scored against a known right answer, with counts out of N, tokens and cost (Scored cases) |
tools/test.mjs |
npm test: every test/*.test.mjs under node --test, run by the node that starts it (Test suite) |
tools/changelog.mjs |
docs/CHANGELOG.md from the git history, every non-merge commit by day; --check exits 1 when the file is behind (Making a change) |
test/ |
the node:test suites (Test suite) |
docs/media/ |
this README's GIFs, screenshot and diagram, the vhs tapes, record.mjs and the demo feature |
docs/measurements.md, docs/live-results.md |
the record behind this README: what runs cost and what each finding changed; what was seen in a real session, by date |
docs/spec-kit-and-speckit-agents.html |
the presentation on Spec Kit and this team, one self-contained HTML file (Publications) |
.specify/, specs/ |
this repo's own Spec Kit setup: its constitution and features 001 to 009 |
.claude/settings.json |
turns fork subagents off for sessions in this repo, so the team's agents run in the foreground (Foreground launches) |
See CLAUDE.md. In short: edit agents/, hooks/, skills/ or install.mjs, run
npm test, rerun the installer, and do the live check if you touched how a hook is
wired. After changing what the board draws or what its buttons do, run node tools/live-board.mjs
(vhs, git and claude on your PATH; about 70 s, no model calls): it types the keys of feature 004's
checks L3 to L6 into an interactive session, writes every screen as text, and prints each check's
result. node tools/live-board.mjs pane presses the pane's [ clear ] instead of the band's.
A skill or agent you add or change must stay inside the authoring limits of the constitution's
"Authoring Skills and Agents" (test/skills.test.mjs holds the line, description and model-name
limits); the other rules there are review criteria. A prompt change meant to alter a verdict is
measured with tools/eval.mjs (Scored cases and arms) before it is kept.
Keep docs/CHANGELOG.md current: as the last commit of a pull request (of the
last one, for a chain of stacked pull requests), run node tools/changelog.mjs and commit the file it
writes. It lists every non-merge commit up to
the commit before, since a commit cannot name its own hash; never edit it by hand.
The GIFs under What it looks like and the board's screenshot under
Board mod come from the vhs
tapes in docs/media/. To record them again, with vhs, specify, claude, git, ffmpeg and
tesseract (with its English language data; TESSDATA_PREFIX, if set, must name a folder that holds
eng.traineddata) on your PATH:
node docs/media/record.mjs # all five; makes live Haiku calls
node docs/media/record.mjs pipeline board # only the named tapes
node docs/media/record.mjs --setup-only # build the scratch repo, record nothingThe script builds a scratch Spec Kit repo in ~/.cache/speckit-agents-demo (owner-only, not a
shared temp dir, because it gets folder trust; deleted and rebuilt on every run, and
SPECKIT_DEMO_DIR names another folder) with the demo feature in docs/media/demo/, installs the
team into that repo's .claude/, and starts Claude Code with
--setting-sources project,local --strict-mcp-config, so your own hooks, plugins, statusline and
MCP servers stay out of the frame. On Windows the tapes reach that repo through a drive letter
mapped onto the folder with subst (the first free one from R:), so the paths a session prints
read R:\repo instead of one with your user name in it; the letter is removed when the script
ends. The session's TEMP, TMP and TMPDIR point at R:\tmp on the same letter, because Claude
Code gives each agent a scratchpad under the temp folder and an agent can print its path. The board tape loads the board from this checkout with
--plugin-dir, in fullscreen so the pane docks, after staging the demo feature mid-build: three
tasks ticked, and an audit PASS and one RED recorded by the hook. It swaps test-writer and
implementer for stand-ins that only report, so its agent rows cost two short Haiku runs.
Caution
Look at every GIF and screenshot before committing it. The tapes hide the working directory in
the startup logo (CLAUDE_CODE_HIDE_CWD=1), but the logo still names the model and your plan,
such as Haiku 5.5 · Claude Max. No setting hides the plan, and the README's GIFs keep it
(owner decision, #63). Each tape records
into the demo folder and writes the screen as text to <tape>.txt there, after each tape
command. That text misses every frame drawn during a Sleep or a Wait: on 2026-10-17 an
agent's Bash call printed its scratchpad path, user name included, in such frames
(#62). So record.mjs also reads every
distinct frame of the GIF (ffmpeg's mpdecimate) and every screenshot with tesseract, and writes
that text to <tape>.frames.txt in the demo folder
(#143). It copies a recording into
docs/media/ only if neither text shows your user name, your home folder's name nor, on Windows,
its 8.3 short form, even split across two rows
(#60); otherwise the run exits 1 and the
files stay in out/<tape>/ in the demo folder. A failed tape copies nothing, and so does one
whose frame check cannot run: ffmpeg or tesseract missing or failing, no frame, or no text read
at all, which is what tesseract without its language data returns. On macOS and Linux the repo's
path contains your home directory, so a session that prints it fails the check. OCR can misread a
name, so a passed check is still not a clean recording; step through the frames.
To see what a run cost in tokens, point tools/usage.mjs at its main-session transcript (under
~/.claude/projects/<project>/); it reads the session's agents from <session>/subagents/ next
to it:
node tools/usage.mjs ~/.claude/projects/<project>/<session>.jsonlIt prints the main session's input, how many agents it launched in the foreground and the
background, the requests that only waited for a background agent, each agent's input and peak, and
the input per model. That last part matches the modelUsage input fields of
claude -p --output-format json exactly (checked against all four runs in
Context budget), with each model's cache hit rate (cache reads over all input)
after it. Output tokens are left out, because transcripts undercount them. Measure a change to the
skill or an agent with it before and after.
Last, it lists any agent that lost its cached prefix: a relaunch of a type on the same model, within
5 minutes of the previous one's last request, whose first request read nothing from the cache. A
first launch is never listed, since an agent's body is a system block of its own and is always
written fresh. On the 53-agent run of 2026-10-09 and 10 it lists none. There, 52 first requests read 0 to
4,366 tokens back (writer agents about 3,000 from each other's launches: their shared tools:
line), and one test-writer, relaunched 3 minutes after the last, read its whole 13,984.
spec-gatekeeper checks a feature once, before its PR. Later changes can drop or move the tests it
traced, and nothing looks again. tools/drift.mjs does, for every feature under specs/, with no
model and no tokens. The check itself is hooks/speckit-drift.mjs, which the installer puts beside
the hook: at spec-gatekeeper's APPROVED the hook runs it on the active feature alone and refuses
the word while it reports a problem (#228).
In the full run of 2026-10-31 the gate approved FR-006, which two tasks cited and no test held,
on the argument that each test file imports only its own module. A hook installed without the file
records APPROVED and says the check did not run.
At APPROVED the hook also runs it at spec level
(#235): every requirement spec.md defines
(**FR-002**) must be in some test file, on a line naming the feature by its number
(test('001 FR-002 ...') or a // 001 FR-002 comment, as test-writer writes them), since every
feature has an FR-002. A requirement no test can hold, such as a docs one, is excused only by a task
that says No test: <reason> right after it (FR-009 (No test: docs)). That excuses the ID it
follows and any the reason names, not the task's other IDs, at task level too. An excuse on one task
holds for the whole feature: a test task that cites the same ID owes no test line for it
(#299). The architect writes
that and you approve it at the tasks stop, not the gatekeeper. tools/drift.mjs stays at task level, since features built before #235 do
not name their number in every test.
node tools/drift.mjs <repo>For each ticked test task in a tasks.md (its opening words, before the first file, parenthesis or
colon, say test or tests) that names a test file and cites FR IDs, it reports the file if
it is gone, and each cited FR ID that none of the task's test files holds any more (test-writer puts
the ID in each test's name or a comment). A line that names a feature by its number, once the IDs on
it are set aside (009 T010 FR-008 ..., specs/009-x), holds its IDs for that feature only, so
another feature's test of the same ID number does not hide drift; a line naming no feature holds them
for any (#212). One line per problem, then a count; exit 1 with drift, 0
without, 2 when the repo has no specs/. A file counts as test code by the hook's own patterns and
.specify/test-paths. In a git repo a path git never tracked is skipped, since tasks also name
example inputs and paths inside a subproject. One git log over every ref answers that for all the missing
paths of a call at once (#342; a call per path was 90% of a
check's time, measurements). Success criteria (SC-) are not looked for: test-writer
does not promise to cite them.
test/drift.test.mjs runs it on this repository too, so a test moved to another file without its
task fails npm test. Its first run, on 2026-10-24, reported 11 problems: ten were feature 003's,
whose tests had moved from test/hook.test.mjs to test/hook-patch.test.mjs after its tasks were
written, and one was a docs task of 007 that names test files. 003's tasks name the new file now
(#161), and docs tasks are no longer checked. The idea is the drift report of
google/elephant-goldfish-model
(docs/designs/drift_report.md), which compares checked-in specs with the code.
-
Spec Kit & speckit-agents: presentation: the slides on Spec Kit and this agent team. It is one self-contained HTML file: download it and open it in a browser. GitHub shows the file's source rather than the slides.






