Facet deep-dive (rules / skills / agents / hooks / output-contracts / knowledge)
This series is a record based on the harness environment as it existed at the time of writing (file contents, run logs, file counts). The harness has kept evolving since this series was written, so quoted file contents, counts, and procedures may differ from the current state. The focus of this series is the design ideas (five-facet separation, verification gates, growth discipline) rather than the specific values.
This chapter walks through each layer of the 5 facets + hooks + knowledge as a dictionary, with real-code excerpts.
A dictionary form is chosen so this series can be read not just as a usage guide but as a reference catalog for building your own harness. By bringing responsibility, boundary, and concrete code into one place per facet, it becomes possible to say "for that purpose, I can use this as the reference."
The originals (~/.claude/rules/*.md, etc.) are written in Japanese. To keep this English series readable, the excerpts below are translations of the originals, not the original wording verbatim. The structure, ordering, and intent are preserved.
Below, the responsibilities of agents/, rules/, skills/, hooks/, output-contracts/, and knowledge/ are each laid out dictionary-style, narrowed down to representative examples (excluding CLAUDE.md, settings.json, .gitignore, and docs/). Because usage-driven addition keeps these facets growing and shrinking over time, this isn't a complete enumeration — it's an excerpt meant to show what kinds of patterns each facet holds.
5.1. rules/ — representative Policy examples
rules/*.md is the Policy (norm, how) facet. All files are constantly loaded (no paths:) and reach subagents. It started as a small bootstrap set, and reached its current shape through usage-driven addition (a facet is added only after the same instruction was given twice by hand — the growth discipline covered in Chapter 7). Below are representative examples showing a few different kinds of discipline patterns.
rules/verification.md
Role: back claims with evidence; for state-changing operations re-confirm the post-state independently
Delivery: constantly loaded (required by developer / auditor)
Opening (translated excerpt):
# Policy: verification
> No paths = constantly loaded. Not path-scoped because developer / auditor
> (subagents) depend on it.
## Back claims with evidence
- Show test / grep / command **output as evidence**. Don't claim "fixed" /
"works" without output.
- Verify command output **in full** before concluding. Don't falsely conclude
"no match" from a truncated `head` / `tail`.
- **State-changing operations (delete / move / create / overwrite / commit /
push) must first verify the execution result (exit code + output), and for
destructive ones, re-verify the actual state independently before reporting
"done"** (`ls` / `git status` / re-Read etc.).
The autodev / smi-auto-dev verification-contract section is in the same file, covering spec freezing, developer evidence recording, and auditor's re-derivation comparison across three pillars.
rules/fact-check.md
Role: source-check before making external-knowledge claims; MCP-first
Delivery: constantly loaded
Opening:
# Policy: fact-check
> No paths = constantly loaded. Mainly the discipline for **main agent before
> presenting information**, to source-check external-knowledge or
> memory-based claims against primary sources. Evidence for work results and
> code is canonically owned by verification.md (not duplicated here).
## Source-check before stating
- For external-knowledge or memory-based technical claims, "verify first, state
second." If you can't verify, **avoid assertive form** and label it
"unverified."
- **Assertive claims are the most dangerous** — without hedging ("probably,"
"should") there's no "unverified" marker and an error reads as fact.
The "assertive claims are the most dangerous" and "don't fill primary-source null-results via memory" lines in particular are the ones consciously applied throughout this series (for example, Chapter 3 explicitly cites nrslib/takt's official docs URLs as primary sources, precisely because of this discipline).
rules/interaction.md
Role: AskUserQuestion required; no plain-text questions; one question at a time
Delivery: constantly loaded
Opening:
# Policy: interaction
## Use AskUserQuestion (no plain-text questions)
- For design judgments, direction confirmations, and option proposals, use
AskUserQuestion **instead of plain-text questions in prose**.
- **Forbidden patterns** (illustrative, not exhaustive): confirmation /
request / implicit-choice prose like "is that OK? / what should we do? /
please decide / could you tell me / shall we adopt it? / does this look
right?" — never write them in prose, always route through AskUserQuestion.
- If there is a recommended option, put it **first** with "(recommended)" at
the end of the label.
This Policy is enforced by hooks/check-plain-question.sh (details in the "hooks/" section later in this chapter).
rules/git.md
Role: Conventional Commits / explicit-trigger-word requirement / worktree discipline
Delivery: constantly loaded (developer / auditor must reach it)
Opening:
# Policy: git
> No paths = constantly loaded. Not path-scoped because developer / auditor
> (subagents) handle commits / diffs.
## Commits
- **Conventional Commits** (`feat:` / `fix:` / `chore:` / `docs:` etc. + scope).
Body explains the "why" concisely.
- Don't put personal names anywhere in **third-party-visible text in
general** — commit messages, PR titles, code, or code comments.
- commit / push execute only when the human's **explicit trigger word**
(`commit` / `push` / `merge` / `apply` etc., verbs) appears in **the most
recent user turn**.
The "Branch" and "worktree (developer isolation in autodev)" sections follow, covering the worktree design (baseRef=head / task branch / handoff dir cross-traversal) in the autodev flow. This Policy is enforced by hooks/check-git-commit-gate.sh (PreToolUse / Bash matcher). Details in Chapter 6.
rules/adversarial-review.md
Role: main agent has a devil-advocate subagent adversarially pre-critique the plan / implementation summary right before presenting it to the human — a gate with iteration built in
Delivery: constantly loaded (main-agent only; no self-recursion for the subagent itself)
Opening:
# Policy: adversarial-review
> No paths = constantly loaded. **Main-agent only**. Not applied inside
> subagents (architect / plan-reviewer / auditor / developer / devil-advocate
> itself) (no self-recursion).
## When to spawn devil-advocate
- **Right before presenting a plan / design proposal to the human** (3+
lines of direction explanation / comparing multiple options / making
trade-offs explicit)
- **Right before presenting an implementation-result summary**, when it
spans multiple files / creates new files / involves a design judgment /
risks conflicting with existing code
## Integrating critique (iteration protocol)
- An iterative loop of **critique → fix → re-critique → present**. A fix
addressing a Critical / Major finding requires a re-critique. Re-critique
judges each finding as **resolved / remaining / new** (3-way), with 1 line
of grounding each.
- Ends on either: zero remaining Critical/Major and zero new Critical / a
maximum of 3 iterations / stagnation.
The devil-advocate agent's own responsibility definition is covered in this chapter's "5.3. agents/" section. This Policy governs when and how to invoke it, and to avoid double-firing with plan-reviewer / auditor inside the autodev flow (= built-in critique that fires automatically within the subagent chain), it's designed not to apply inside the autodev chain.
Other rules/ files (overview)
Beyond the ones above, there's a lineup of Policies each broken out by purpose. For example:
- Pre-implementation primary-source check (
implementation.md): before writing code, confirm the API of the library / framework being adopted via context7 MCP or similar - Symbol grounding before writing code (
search-before-coding.md): confirm an existing API / function actually exists via grep before calling it - Response tone and closing (
output-style.md): no filler phrases; a 3-axis summary when editing completes - Spec-structuring discipline (
spec-discipline.md): EARS notation, explicit in-scope/out-of-scope - Cross-session handoff discipline (
handoff-discipline.md): required items to leave behind on a context reset
A distinguishing feature is that fact-check.md (before stating) / implementation.md (before adopting) / search-before-coding.md (before writing code) / verification.md (after execution) form a split along the timeline axis. Splitting the same "source-check" discipline across points in time keeps each facet's responsibility simple.
5.2. skills/ — representative Instruction examples
skills/*/SKILL.md is the Instruction (procedure) facet. Below are representative examples chosen to show different kinds of procedures: autodev, which drives the entire autonomous-dev flow; spec-design, specialized for the human-dialogue procedure; harness-prune, self-referentially preventing its own bloat; japanese-tech-writing, which keeps its body light and pushes detail into a separate file; and pr-review, which forbids auto-invocation because of its destructive side effects.
skills/autodev/
Launch: /autodev <spec path>
Role: orchestrate from spec to implementation through a subagent chain
Excerpt of the core phases:
## ⓪' Pre-launch assert + resume judgment
- realpath the spec-path argument → extract `<repo>` from
`~/.claude/repos/<repo>/...` → Read/trim `.repo_root` → get repo_root
## ① architect spawn (read-only, fresh)
Inject spec.md + per-repo knowledge into the spawn prompt by absolute path.
## ①' plan-reviewer spawn (read-only, fresh)
Match spec ⇔ plan → review.md. Branch via `grep '^VERDICT:'`.
## ② Human approval (only PASS plans arrive here)
AskUserQuestion 3-way (approve / specify changes / abort).
## ③ developer spawn (worktree isolation, baseRef=head)
story.md is the sole input → install dependencies → implement → pass
conditions → done.md → task branch commit.
## ④ auditor spawn (read-only, fresh = --bare)
done.md evidence ⇔ spec original re-derivation + code ⇔ spec + doc-update
omissions → review.md.
## ⑤ VERDICT branching (fail-closed)
Read only `grep '^VERDICT:'` → PASS: human review / merge / FAIL: re-spawn ③.
Walked through with a real run in Chapter 6 (06. Walking the autodev flow). There's also smi-auto-dev, a learning-oriented variant that layers understanding gates (G1/G2/G3) on top — used when quality gates need to stay fully intact while still reaching merge in a state the human can read.
skills/spec-design/
Launch: /spec-design <feature description>
Role: Human + AI co-design spec.md, freeze pass conditions, SHA-pin on approval
Opening:
---
name: spec-design
description: Co-design specs with the human and AI. Phase 0 adaptive
questioning → co-author spec.md + pass conditions and freeze on
approval.
---
Launch with `/spec-design <feature description>`.
## Phase 0: adaptive questioning
1. **Explicit AC check**: does the human's utterance contain acceptance
criteria or judgment conditions?
- YES → straight to spec (avoid friction on light tasks)
- NO → one-question-at-a-time interview
2. Don't list multiple points at once.
Where autodev is an orchestration-procedure Instruction, spec-design is an Instruction that disciplines "the procedure for talking with a human." Even within the same facet, the nature of the content varies quite a bit.
skills/harness-prune/
Launch: /harness-prune
Role: monthly inventory (reverse-ratchet's exit guard)
Opening:
---
name: harness-prune
description: Reverse-ratchet exit guard. Detect 30-day-zero-references /
size-cap-overrun / orphan hooks / dangling references, and
process deletions via inverted approval (ask why to keep).
---
## 4 detection items
1. **Facets with 30-day-zero references**: rules / agents / skills / knowledge
/ output-contracts unreferenced for 30 days from other files or git history
2. **Size-cap overrun**: CLAUDE.md > 100 / policy > 30 / persona > 40 (gating
> 60) / skill > 80 (autodev > 100)
3. **Orphan hooks**: hooks without a corresponding facet file
4. **Dangling references**: `~/.claude/<path>` mentions in rules / skills /
agents that don't resolve
## Inverted approval (the asymmetry core)
Ask not "OK to delete?" but **"what's the reason to keep this candidate?"**
(burden of proof on the keeper).
Detailed in Chapter 7 (07. Growth discipline and reverse ratchet). This skill itself also has a fixed size cap and a fixed set of detection items, designed so that "the tool that does the inventory doesn't bloat itself."
skills/japanese-tech-writing/
Role: writing norms for writing / polishing / rewriting Japanese technical documents (book manuscripts / chapters / articles / explanatory writing)
Launch: auto-invoked (description trigger includes "write / draft / polish / rewrite / fix / tidy Japanese technical documents")
Delivery: model-invocable
Structure:
0. Top-level principle (the 3-layer structure of "AI-ish": style / information design / absence of thought)
1-10. Detailed norms → on-demand Read regulations.md
11. Self-check
12. Japanese-writing classics (Kinoshita's "Rikei no Sakubun Gijutsu" /
Honda's "Nihongo no Sakubun Gijutsu" / Yuuki's "Suugaku
Bunshou Sahou" / Kyodo News's "Kisha Handbook")
The skill body (SKILL.md) contains only chapter 0 and chapter 11 (= the top-level principle and the self-check); the detailed chapters 1-10 plus chapter 12 are on-demand Read from regulations.md. This follows the keep SKILL.md light, split deep-dives into a separate file pattern, and this series itself is written under this skill's norms.
skills/pr-review/
Role: review a GitHub PR from multiple angles and post each finding as an individual inline review comment in Japanese, labeled [must] [imo] [ask] [nit]
Launch: /pr-review [PR number]
Delivery: disable-model-invocation: true (posting comments to a PR is a destructive side effect, so it suppresses Claude's own auto-invocation and only runs when launched by hand)
Main structure:
- Repurposes multiple agents via persona injection
- Supplements with a frontend rubric on conditional trigger (rubrics/frontend.md)
- Classifies findings into 4 labels: [must]/[imo]/[ask]/[nit] (labels.md / label-mapping.md)
- A soft Japanese tone norm (tone.md)
This skill isn't a standalone SKILL.md — it's a multi-file skill accompanied by several supporting docs, following the same "keep SKILL.md light / details in a separate file" pattern as japanese-tech-writing/regulations.md.
Other skills/ files (overview)
Beyond the ones above, there's a lineup of Instructions independent by purpose: project-init, which scaffolds the project layer zero-footprint; learn, which records learnings into learnings/; next, which proposes "what to do next"; next-session-prompt, which generates the handoff prompt for the next session; and a group of skills handling Backlog issue filing and batch-processing PR review comments, among others. skills/ is also a facet that grows and shrinks via usage-driven addition, so a complete current list isn't covered here.
5.3. agents/ — representative Persona examples
agents/*.md is the Persona (who, the behavioral subject) facet. Pre-rebuild it had a larger cast, which was narrowed down to "the roles essential to the autodev flow," and then devil-advocate was added for pre-presentation critique on the main-agent path. Unlike other facets, agents/ changes at a much slower pace given the nature of these roles, so what follows is close to a complete introduction of the current set.
agents/architect.md
Role: design plan.md from spec
tools: Read / Grep / Glob / Write (handoff dir only)
Generator/Evaluator: Evaluator-ish (designs but doesn't implement)
---
name: architect
description: Design an implementation plan (plan.md) from spec and code
exploration. Read-only; doesn't implement.
model: inherit
tools: Read, Grep, Glob, Write
---
You are a design-first implementation planner. Based on spec.md and the
per-repo knowledge injected via the spawn prompt, explore the codebase
read-only and Write plan.md into the handoff dir (Write is handoff-only;
don't change code).
## Responsibilities
- Cover every spec pass condition in the plan
- Architecture choices with trade-offs (adopted vs rejected with reasons)
- List the impact range (files / API / DB schema touched)
- **List doc-updates in plan.md** (used by auditor for matching)
## Constraints
- **Code is read-only**. Don't implement; no worktree
- Per-repo knowledge arrives via spawn-prompt injection
- Don't guess uncertain library specs; mark "needs verification" in plan.md
agents/plan-reviewer.md
Role: match spec ⇔ plan, emit VERDICT: PASS|FAIL as a gating agent
tools: Read / Grep / Glob / Write (review.md only)
Generator/Evaluator: Evaluator
---
name: plan-reviewer
description: Gating agent that compares architect's plan.md against the spec
original.
model: inherit
tools: Read, Grep, Glob, Write
---
You are a critical plan verifier. Compare spec.md original with plan.md and
emit a VERDICT.
## Verification angles
- **Spec coverage**: does the plan cover every pass condition
- **5 adversarial-critique angles** (same scope as devil-advocate): failure
conditions / pass conditions an empty implementation would satisfy /
conflicts with existing code / hidden assumptions / unexamined alternatives
- **Even a "none" verdict needs 1 line of grounding**: back a "no issues"
conclusion with a grep result or a referenced line number too
## Output contract (output-contracts/review.md)
- First line VERDICT + primary signal + findings
- **The first line of the final utterance** must be a single word, either
`VERDICT: PASS` or `VERDICT: FAIL` (the literal string `PASS|FAIL` doesn't
count)
## ratchet surface
On observing the same finding twice, end with "ratchet candidate: ..."
The "5 adversarial-critique angles" bakes the same angles devil-advocate uses directly into plan-reviewer itself, giving it the responsibility of proactively hunting for conditions that would break the plan.
agents/developer.md
Role: implement inside the worktree from story.md, run pass conditions, commit to the task branch
tools: Read / Write / Edit / Bash
Generator/Evaluator: Generator
---
name: developer
description: Implement inside the worktree with story.md as the sole input.
Run pass conditions and record evidence.
model: inherit
tools: Read, Write, Edit, Bash
---
You are a spec-faithful implementer. story.md is your sole primary input;
implement inside the worktree (branched from HEAD).
## Implementation flow
1. Install dependencies (`npm install` etc.)
2. Implement faithful to story.md's plan (red → green)
3. Run pass conditions (story's acceptance verification commands) **inside the
worktree**
4. Record evidence in done.md: per pass condition, cmd + exit code + output
summary + PASS/FAIL
5. Doc updates (those listed in story's "doc-update obligations")
6. Commit to the task branch
## Constraints
- **story.md is the sole input** (spec / plan are embedded in story)
- Pass conditions are run by developer (auditor doesn't run them)
- done.md evidence is the verification ground truth — **record honestly**
(faked exit codes break the circular defense)
- **Don't change acceptance criteria mid-implementation**. If changes are
needed, stop and bounce to the orchestrator
agents/auditor.md
Role: match done.md ⇔ spec original re-derivation + code ⇔ spec + doc updates across 3 pillars, emit VERDICT as a gating agent
tools: Read / Grep / Glob / Bash (git diff) / Write (review.md only)
Generator/Evaluator: Evaluator
---
name: auditor
description: Gating agent that compares done.md execution evidence with the
spec original. Read-only; doesn't run anything itself.
model: inherit
tools: Read, Grep, Glob, Bash, Write
---
You are an evidence-based auditor. Compare done.md execution evidence with
expectations re-derived from spec.md and emit a VERDICT. **You don't run pass
conditions yourself** (code stays read-only; fresh --bare maintained).
## Three pillars
1. **Primary signal (done.md evidence ⇔ spec original re-derivation)**:
compare developer's done.md cmd + exit code + output with expectations
re-derived from spec.md pass conditions
2. **code ⇔ spec**: use `git -C <repo_root> diff <base-SHA>...<task-branch>`
to get the diff (worktree-non-invasive); does the diff contradict spec /
constraints
3. **Doc-update omissions**: omissions of items listed in story's "doc-update
obligations" = FAIL; unlisted inconsistencies = Minor warning
## Output contract
- Write review.md into the handoff dir (first line VERDICT)
- **The first line of the final utterance** must be a single word, either
`VERDICT: PASS` or `VERDICT: FAIL` (the literal string `PASS|FAIL` doesn't
count)
"You don't run pass conditions yourself" is the heart of takt's "Separation Improves Quality" principle (one of the 8 design principles); see Chapter 3, which covered this.
agents/devil-advocate.md
Role: adversarially critique the plan / implementation summary / a high-stakes AskUserQuestion right before the main agent presents it to the human (read-only; only points out failure modes, no fix proposals)
tools: Read / Grep / Glob (no Bash / Write, can't execute pass conditions)
model: inherit
frontmatter excerpt:
---
name: devil-advocate
description: Adversarially critique the plan / implementation summary / a
high-stakes AskUserQuestion right before the main agent presents it to the
human. Read-only; only points out failure modes, no fix proposals.
model: inherit
tools: Read, Grep, Glob
---
Responsibilities (critique only — fix proposals forbidden):
1. Failure conditions: name at least 1 concrete scenario where the plan / implementation breaks
2. Empty-implementation pass: could the acceptance criteria pass on a no-op / mock?
3. Existing conflicts: does it contradict spec / per-repo policy / existing API (grep-verified)?
4. Hidden assumptions: force "taken for granted" assumptions into the open
5. Unexamined alternatives: where existing practice was the stated reason for
a choice, is there any trace of an independent
best-practice comparison?
As its output contract, the first line is CRITIQUE: <breakdown | unclear | none>, followed by 1-2 lines per finding tagged with a severity of Critical / Major / Minor. Forbidding fix proposals is the heart of the Generator-Evaluator separation. Letting it write fix proposals would erode the main agent's ownership of fixes and push the loop into double judgment. devil-advocate stops at pointing out failures, and the main agent owns "adopt / rebut / fix direction."
Because its role can look like it overlaps with plan-reviewer (the gating agent matching architect's plan against the spec original) / auditor (the gating agent matching developer's done.md against the spec original) inside the /autodev chain, rules/adversarial-review.md explicitly states the rule that this agent isn't double-invoked inside the autodev chain (§5.1 of this chapter).
5.4. hooks/ — representative enforcement examples
hooks/ serves as the enforcement layer of Computational Sensors. Out of the norms written in Inferential Guides (rules), the ones whose probabilistic failure has real impact are stopped or logged deterministically. Below are representative examples of both the block type and the log-only type (hooks/ is also a facet that grows via usage-driven addition, so this isn't the complete set).
| hook | matcher | block/log | Policy facet enforced |
|---|---|---|---|
check-git-commit-gate.sh | PreToolUse / Bash | block (exit 2) | rules/git.md (explicit trigger-word requirement) |
check-plain-question.sh | Stop | block (exit 2) | rules/interaction.md (no plain questions) |
check-action-completion.sh | Stop | log-only | rules/verification.md (completion-report for state-changing operations) |
check-pre-edit-search.sh | PreToolUse / Edit・Write・MultiEdit | log-only | rules/search-before-coding.md (detect missing pre-edit Read) |
Each hook has a false-positive escape hatch, but they differ. check-git-commit-gate.sh uses a marker-file bypass (touch ~/.claude/.skip-git-commit-gate-once), while check-plain-question.sh uses an environment variable (CLAUDE_HOOK_SKIP_PLAIN_QUESTION=1 — though an in-session export doesn't reach the hook process, so this only works as a permanent opt-out exported before launching the CLI). The bypass mechanism differs per hook because Claude Code's spec has cases where environment variables aren't inherited by the hook process; the commit gate moved from the env approach to the marker-file approach after running into this constraint (covered in Chapter 8's fix example).
hooks/tests/ contains unit tests for each hook, treating each hook itself as "tested enforcement" — a safety valve against silently changing detection logic.
Inside check-git-commit-gate.sh
The detection logic of the core hook check-git-commit-gate.sh (main parts):
# Detect git commit subcommand (option-passed; excludes log --grep=commit)
COMMIT_PATTERN='(^|[^A-Za-z0-9_-])git[[:space:]]+(-[A-Za-z][A-Za-z0-9-]*([= ][^[:space:]]+)?[[:space:]]+)*commit([[:space:]]|$)'
echo "$COMMAND" | grep -Eq "$COMMIT_PATTERN" || exit 0
# Extract the text of the most recent user-origin message (lenient parse)
# user role mixes (a) human/orchestrator utterance and (b) tool_result.
# In subagent transcripts the last user message is often tool_result, missing
# (a). To compensate, among (b) only the AskUserQuestion answer (a tool_result
# starting with "Your questions have been answered:" — equivalent to an
# explicit human judgment) gets special-cased through; other tool_results
# (Bash output etc.) are excluded, keeping pure-text user messages.
LAST_USER_TEXT=$(
jq -R 'fromjson?' "$TRANSCRIPT_PATH" 2>/dev/null \
| jq -s -r '
def extract:
.message.content
| if type == "string" then .
elif type == "array" then
[ .[]
| if (type == "object" and has("tool_use_id")) then
if ((.content // "" | type == "string")
and (.content // "" | startswith("Your questions have been answered:")))
then .content
else empty
end
else (.text // .content // "")
end
] | join("\n")
else "" end;
[ .[]
| select(.type=="user")
| extract
| select(. != null and . != "")
] | last // ""
' 2>/dev/null
)
# Trigger words: verb-based (commit / push / merge / apply)
TRIGGER_PATTERN='commit|コミット|push|プッシュ|マージ|merge|反映'
if [ -n "$LAST_USER_TEXT" ] && echo "$LAST_USER_TEXT" | grep -iqE "$TRIGGER_PATTERN"; then
exit 0
fi
cat >&2 <<EOF
Detected: no explicit trigger word in the most recent user turn for git commit.
Norm: ~/.claude/rules/git.md \`## Commits\` section (explicit trigger-word requirement)
EOF
exit 2
Naively excluding all tool_results would also exclude an AskUserQuestion answer choosing to commit, causing the immediately following commit to get blocked. So the logic special-cases just the AskUserQuestion answer out of all tool_results — one branch more complex than a blanket exclusion. The trick that lets the spawn-prompt trigger word be picked up correctly even in a subagent is still very much alive. Full background in Chapter 8.
Inside check-plain-question.sh
check-plain-question.sh greps for plain questions using several kinds of detection patterns (explicit interrogatives like "what should we do?", euphemistic confirmations, juxtaposed options, approval-assuming progress statements, and more):
EXPLICIT='どうしますか|どうしましょうか|よろしいですか|...'
SOFT='(修正|追加|削除|...).{0,10}(ましょうか|ますか)[[:space:]]*[?？]?[[:space:]]*$'
QUESTION_MARK='(進め|続け|...).{0,30}[?？][[:space:]]*$'
IMPLICIT_CHOICE='(\([abcde]\)|...)[^。\n]{0,60}(か|なら|...)[^。\n]{0,60}(\([abcde]\)|...)'
CONFIRMATION='(ここまで|...)\s*(OK|ok|...)\s*(です|...)?(か)?[?？]|...'
Patterns for declaring progress in plain prose while assuming approval (e.g. "I'll proceed," advancing without explicitly stating that approval is pending) and, conversely, declaring a wait in plain prose (e.g. "I'll hold off until an explicit instruction") were both added to the detection patterns later. For loop-prevention, it passes if STOP_HOOK_ACTIVE=true, and skips if a recent AskUserQuestion / ExitPlanMode tool_use was used.
check-action-completion.sh as log-only
Unlike the other Stop hooks, check-action-completion.sh runs log-only (doesn't block):
# log-only material (don't block). CLAUDE_HOOK_LOG_DIR is for test isolation.
LOG_DIR="${CLAUDE_HOOK_LOG_DIR:-$HOME/.claude/logs}"
mkdir -p "$LOG_DIR" 2>/dev/null || true
{
echo "[$TS] action-completion DETECTED (log-only): kind=$DETECT"
echo " claim(head): $(log_head "$LAST_ASSISTANT_TEXT")"
} >> "$LOG_DIR/action-completion.log" 2>/dev/null || true
exit 0
The policy is to accumulate logs and only later promote to block for detections of unknown precision. This is the same pattern as Ratchet (don't promote on a single failure; accumulate 2-3 materials, then promote).
check-pre-edit-search.sh's log-only design
check-pre-edit-search.sh, added after bootstrap, observes, log-only, the "ground symbols before editing" norm from rules/search-before-coding.md. Quoting its header comment:
#!/bin/bash
# Computational Sensor (log-only): before an Edit / Write / MultiEdit tool call,
# checks whether the target file_path was Read within this session's
# transcript, and if not, logs it as material to
# ~/.claude/logs/pre-edit-search.log.
# Always exits 0 (never blocks).
#
# Background: the Edit tool's description enforces "Read before Edit," but
# Write (including overwrites) and MultiEdit enforce it weakly. A Sensor
# against the hallucination risk of assembling a file_path from memory and
# editing it.
#
# Honest limitation: only checks the jsonl Read history. Cases confirmed via
# Glob/Grep are treated as unread (false positive). Since precision is
# unknown, it's log-only (promoting to block is a separate decision after
# accumulating logs + measuring).
The notable point is the "honest limitation" comment. It explicitly treats cases confirmed via Glob/Grep as false positives, and defers promotion to block as "a separate decision after accumulating logs + measuring." This is a concrete application of ~/.claude/CLAUDE.md's "hooks come after evidence" discipline (= premised on the same failure occurring twice + the corresponding facet already existing), landing on an operational pattern that measures precision via logs before promoting. The Computational Sensor was introduced early using the bootstrap-concurrent-allowance exception clause, and whether to promote it to block or delete it will be decided based on the log results.
5.5. output-contracts/ — representative Output Contract examples
output-contracts/*.md is the Claude Code implementation of nrslib/takt's official facet "Output Contract" (corresponding to the output_contracts: field each step carries in takt's Workflow YAML). It holds the subagent artifact templates. Here are the 5 representative types that form the core of the autodev flow (this facet, too, may grow further).
| File | Use | Producer subagent | Machine-judged by |
|---|---|---|---|
spec.md | Spec with acceptance (pass conditions) | spec-design (human + AI co-design) | pass-condition SHA256 (frozen in state.md) |
plan.md | Plan / arch choices / impact range / doc obligations | architect | plan-reviewer VERDICT |
story.md | Single input merged from spec + plan for developer | orchestrator (composition) | (transitive file) |
done.md | Execution evidence (cmd + exit code + output + PASS/FAIL per pass) | developer | auditor VERDICT |
review.md | VERDICT report | plan-reviewer / auditor | orchestrator grep '^VERDICT:' |
plan.md template (column-form doc obligations)
Full plan.md template:
# plan: <feature name>
> Output Contract (template). architect generates from spec.md + per-repo
> knowledge; passed through plan-reviewer's VERDICT.
## Implementation plan
<step-by-step. each step traceable to a spec pass condition>
1. ...
## Architecture decisions
<list choices with trade-offs; reasons for adopted vs rejected>
## Impact range
<touched files / API / DB schema>
## Doc-update obligations
<list: target path + tier (pointer / real repo) + updater (developer /
orchestrator delegate) + verification path in column form. Used by auditor
for matching; transcribed verbatim into story.md by the orchestrator>
| Target path | Tier | Updater | Verification path |
| --- | --- | --- | --- |
| ... | pointer / real repo | developer (worktree commit) / orchestrator
(delegate) | auditor Read / git diff |
The "Tier" column splitting pointer / real repo is important. Pointer tier (under ~/.claude/repos/<repo>/) is outside the worktree, so developer can't commit it — the orchestrator updates by delegation. Real repo (inside worktree) is committed by developer.
This template wasn't column-form at bootstrap; it became so via fixes made during actual operation (Chapter 8).
review.md template (VERDICT first line)
Full review.md template (the PASS|FAIL on the first line is template notation — actual output is a single word, either PASS or FAIL):
VERDICT: PASS|FAIL
> Output Contract (template). Generic verification report. Shared by
> plan-reviewer (spec ⇔ plan) and auditor (done.md evidence ⇔ spec original).
> **The first line of the final utterance** and review.md's first line must
> always carry a single word, either `VERDICT: PASS` or `VERDICT: FAIL` (the
> literal string `PASS|FAIL` doesn't count; the orchestrator branches
> fail-closed via `grep '^VERDICT:' review.md`).
## Primary signal
<plan-reviewer: pass-condition coverage / auditor: result of comparing done.md
evidence with expectations re-derived from spec.md>
## Comparison details (N/A allowed)
- Spec coverage / non-triviality (does an empty / no-op implementation pass?):
- code ⇔ spec (auditor: any contradiction between `git diff
<base>...<branch>` and spec):
- Doc-update omissions (story-listed = FAIL / unlisted = Minor warning):
- Per-repo policy violations:
## Findings (when FAIL)
<paths to revisit and concrete fix instructions>
## ratchet candidate (one line, if applicable)
<on the same finding twice, report "ratchet candidate: ...">
The fixed first line VERDICT: PASS|FAIL lets the orchestrator decide by grep '^VERDICT:' alone, structurally avoiding the context-pressure cost of long review bodies.
5.6. knowledge/ — the shared Knowledge pool
knowledge/ is the facet that collects Knowledge (descriptive knowledge, Read on demand). It was empty at bootstrap, but reference pools for domains that turned out to be needed during actual operation have been added little by little (a coding best-practices collection, API/DB design, UI/QA review criteria, and more).
As a representative example, quoting the opening of coding-accuracy-2026.md:
# Knowledge: 2026 coding-accuracy best-practices pool
> Created at Kuro's discretion. This file is not a norm but a
> **reference pool**. When writing norm bodies, re-verify from here via
> context7 / WebFetch before committing to prose.
> Subject to `/harness-prune`'s 30-day-zero-reference detection.
## Primary source URLs (spot-checked at Step 0.4)
| URL | Status | Use |
|---|---|---|
| code.claude.com/docs/en/best-practices | 200 OK | Claude Code itself |
| platform.claude.com/.../extended-thinking | 200 OK | manual / adaptive thinking |
| platform.claude.com/.../claude-4-best-practices | 200 OK | prompt-engineering |
The important design decisions are that it's "a reference pool, not a norm" and that "when writing a norm, re-verify starting from here." Unlike other facets, Knowledge holds excerpts pulled from primary sources, but writing a norm body directly on that basis creates "a dependency on an external spec whose change-date is unknown." So this facet is kept as a waypoint, and the header note explicitly states the practice of re-verifying via context7 / WebFetch before committing to a norm body (consistent with rules/fact-check.md's "MCP first").
In addition, the fact that knowledge/ is included in /harness-prune's 30-day-zero-reference detection is a structural safeguard against Knowledge running away (bloating as a memory substitute) (reverse ratchet is covered in Chapter 7).
5.7. Summary of this chapter
- rules: a Policy collection that keeps growing little by little via usage-driven addition. Every file is constantly loaded (no paths:) and reaches subagents too. verification / fact-check / interaction / git / adversarial-review, and more, line up with different discipline patterns
- skills: an Instruction collection split by purpose — autonomous-dev (spec-design / autodev / smi-auto-dev / project-init), maintenance (harness-prune), learning (learn), orchestration (next / next-session-prompt), and more
- agents: architect (design) / plan-reviewer (matching) / developer (implementation) / auditor (audit) + devil-advocate (pre-presentation critique). Generator-Evaluator separation enforced structurally by tool constraints
- hooks: block-type (
check-git-commit-gatecheck-plain-questionand more) and log-only-type (check-action-completioncheck-pre-edit-searchand more) coexist. Policy is to measure precision via logs before promoting to block. Test bodies live underhooks/tests/ - output-contracts: spec / plan / story / done / review. review.md's first-line VERDICT discipline is what makes the autodev flow's fail-closed branching work
- knowledge/: operated as a reference pool, not a norm — a waypoint re-verified via context7 / WebFetch before being committed to a norm body. Domains keep growing via usage-driven addition
The next chapter walks through the autodev flow where these facets actually combine and run, using the anagram-check task in autodev-smoke from start to finish.