create-agent-rig 0.3.0 → 0.3.1

package/CHANGELOG.md

@@ -7,6 +7,42 @@ the generator.
 Versions are published to npm as [`create-agent-rig`](https://www.npmjs.com/package/create-agent-rig);
 `npx github:serhii-baksheiev/create-agent-rig` keeps working for either path.
 
+## 0.3.1
+
+`create-agent-rig init` shipped a rig that looked installed and enforced
+nothing. Everything below is that one failure, in its four parts — a repo
+`init`ed with 0.3.0 should be re-run with this version (`--force` to replace the
+CLAUDE.md it wrote).
+
+### Fixed
+
+- **The hooks are wired.** `init` laid the hook files down and stopped there: no
+  `.claude/settings.json` meant `guard-bash`, `block-no-verify`, `gate-stop-dod`
+  and `inject-rules` were never called, while the installed `CLAUDE.md` claimed
+  they were enforced at the tool layer. The wiring is now _derived_ from the
+  shipped settings, so it names exactly the hooks that travelled — never one that
+  did not. Where the repo already has a `settings.json`, `init` keeps it and
+  prints the entries to merge rather than failing silently.
+- **The kill switch works.** `init` copied templates byte-for-byte, leaving
+  `__PROJECT_NAME__` in six places — including `stop-flag.mjs`, so the brake
+  looked for `~/.claude/__PROJECT_NAME__-loop-STOP` while the operator, following
+  the instructions in the same install, created `~/.claude/<repo>-loop-STOP`. It
+  never fired, and never said so.
+- **The installed `CLAUDE.md` describes the repo it landed in.** It used to be
+  the generated monorepo's map — `packages/core/`, `apps/web/`, links to an
+  `architecture.md` and two guards that `init` deliberately does not install. It
+  is now its own document: what was installed, what was not, and that the
+  architecture rules are yours to write.
+- **The elevated-path block names paths that exist.** It seeded
+  `packages/db/src/` into repos that have no such directory, so the Tier-2 gate
+  sweep reported "clean" while looking at nothing.
+
+### Added
+
+- A template test that fails if anything `init` installs references a `.claude`
+  file `init` does not install — the drift that produced three of the four
+  findings above, now mechanical.
+
 ## 0.3.0
 
 The factory extraction: a scaffolded project now arrives with a working

package/README.md

@@ -22,7 +22,15 @@ npx create-agent-rig init --dry-run  # print the plan, write nothing
 ```
 
 `init` drops in the autonomy tiers, stop rules, workflow, and the enforcement
-hooks, and refuses to clobber an existing `CLAUDE.md`.
+hooks — **wired**, in a `.claude/settings.json` that names exactly the hooks it
+installed — plus a `CLAUDE.md` that describes that rig rather than the generated
+monorepo. It refuses to clobber an existing `CLAUDE.md`; if the repo already has
+a `.claude/settings.json`, it keeps it and prints the entries to merge, because a
+hook nothing calls is not enforcement.
+
+Two things it deliberately leaves to you, and says so in the installed
+`CLAUDE.md`: the Definition-of-Done gate has no `dod-checks.json` (it cannot know
+your commands), and the elevated-path list names only what every repo has.
 
 ## What you get
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-agent-rig",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Scaffold a new project with an agent operating system (rules, gates, hooks) and a runnable code skeleton",
   "keywords": [
     "create",

package/packages/cli/dist/commands/init.js

@@ -1,37 +1,93 @@
 import { access, mkdir, readFile, writeFile } from 'node:fs/promises';
 import path from 'node:path';
-import { agentOsUniversalDir } from '../templates.js';
+import { settingsForInstalledHooks } from '../lib/init-settings.js';
+import { substituteContent } from '../lib/substitute.js';
+import { agentOsInitDir, agentOsUniversalDir } from '../templates.js';
 /** A user-facing failure: message is printed as-is, no stack trace. */
 export class InitError extends Error {
 }
+const SETTINGS = '.claude/settings.json';
 async function loadManifest() {
     const raw = await readFile(path.join(agentOsUniversalDir(), 'layers.json'), 'utf8');
     return JSON.parse(raw);
 }
+async function exists(p) {
+    try {
+        await access(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The name this repo is known by inside the rig. It ends up in a *filename* —
+ * `~/.claude/<name>-loop-STOP`, the kill switch — so it is reduced to
+ * characters an operator can type into a shell without quoting.
+ */
+export function projectNameFor(repoDir) {
+    const base = path.basename(path.resolve(repoDir));
+    const slug = base
+        .toLowerCase()
+        .replace(/[^a-z0-9._-]+/g, '-')
+        .replace(/^[-.]+|[-.]+$/g, '');
+    return slug === '' ? 'project' : slug;
+}
 /**
  * `init` installs only the PROCESS layer (hooks-and-reach brief §3/§4): rules
  * that assume nothing about the codebase shape. Architecture rules reference
  * `packages/core` and friends — installing them into an arbitrary repo would
  * describe a structure that does not exist, which is worse than no rule.
  *
- * CLAUDE.md is the meta file we bring, but never over an existing one.
+ * It also installs two things the process manifest does not name, because both
+ * are meaningless in the generated shape and load-bearing here:
+ *
+ * - `CLAUDE.md` — the map, taken from the init override layer, which describes
+ *   the rig this command installs rather than the generated monorepo;
+ * - `.claude/settings.json` — the wiring, derived from the shipped settings so
+ *   it names exactly the hooks that travelled.
  */
-async function processFiles(manifest) {
-    // the process layer, plus CLAUDE.md as the map (guarded separately)
-    return [...manifest.process, 'CLAUDE.md'];
-}
-async function exists(p) {
-    try {
-        await access(p);
-        return true;
+export async function initManifest() {
+    const manifest = await loadManifest();
+    const universal = agentOsUniversalDir();
+    const override = agentOsInitDir();
+    const files = [];
+    for (const rel of [...manifest.process, 'CLAUDE.md']) {
+        const overridden = path.join(override, rel);
+        files.push({
+            rel,
+            source: (await exists(overridden)) ? overridden : path.join(universal, rel),
+        });
     }
-    catch {
-        return false;
+    files.push({ rel: SETTINGS, source: null });
+    return files;
+}
+/**
+ * Exactly the bytes `init` would write, keyed by destination path — the single
+ * source the plan, the install and the template tests all read.
+ *
+ * Every file the process layer carries is text (asserted by a template test),
+ * so substitution can be applied unconditionally: an unsubstituted
+ * `__PROJECT_NAME__` in `stop-flag.mjs` is a kill switch that silently never
+ * fires.
+ */
+export async function initFileContents(repoDir) {
+    const projectName = projectNameFor(repoDir);
+    const ctx = { projectName, projectScope: projectName, region: '' };
+    const files = await initManifest();
+    const contents = new Map();
+    for (const { rel, source } of files) {
+        if (source === null)
+            continue;
+        contents.set(rel, substituteContent(await readFile(source, 'utf8'), ctx));
     }
+    const installedHooks = new Set(files.map((f) => f.rel).filter((rel) => rel.startsWith('.claude/hooks/')));
+    const shipped = JSON.parse(await readFile(path.join(agentOsUniversalDir(), SETTINGS), 'utf8'));
+    contents.set(SETTINGS, `${JSON.stringify(settingsForInstalledHooks(shipped, installedHooks), null, 2)}\n`);
+    return contents;
 }
 export async function planInit(repoDir) {
-    const manifest = await loadManifest();
-    const files = await processFiles(manifest);
+    const files = (await initManifest()).map((f) => f.rel);
     const conflicts = [];
     for (const rel of files) {
         if (await exists(path.join(repoDir, rel)))
@@ -40,9 +96,7 @@ export async function planInit(repoDir) {
     return { files: files.map((p) => ({ path: p })), conflicts };
 }
 export async function initProject(repoDir, options) {
-    const manifest = await loadManifest();
-    const files = await processFiles(manifest);
-    const universal = agentOsUniversalDir();
+    const files = (await initManifest()).map((f) => f.rel);
     // Refuse to clobber an existing CLAUDE.md unless forced — init edits
     // someone's working repository (brief §4, non-negotiable).
     if (!options.force && files.includes('CLAUDE.md')) {
@@ -51,6 +105,7 @@ export async function initProject(repoDir, options) {
                 'Merge the agent-os map in by hand, or re-run with --force to replace it.');
         }
     }
+    const contents = await initFileContents(repoDir);
     const written = [];
     const skipped = [];
     const plannedCount = files.length;
@@ -65,7 +120,7 @@ export async function initProject(repoDir, options) {
         if (options.dryRun)
             continue;
         await mkdir(path.dirname(dest), { recursive: true });
-        await writeFile(dest, await readFile(path.join(universal, rel)));
+        await writeFile(dest, contents.get(rel) ?? '');
         written.push(rel);
     }
     return { written, skipped, plannedCount };

package/packages/cli/dist/index.js

@@ -4,7 +4,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { parseArgs } from 'node:util';
 import { CreateError, createProject } from './commands/create.js';
-import { InitError, initProject, planInit } from './commands/init.js';
+import { InitError, initFileContents, initProject, planInit } from './commands/init.js';
 import { makePalette } from './lib/colors.js';
 import { promptTarget } from './lib/prompts.js';
 import { collectGovernance, renderSummary } from './lib/summary.js';
@@ -65,6 +65,16 @@ async function runInit(rawArgs) {
     process.stdout.write(`\nInstalled ${result.written.length} files` +
         (result.skipped.length ? `, kept ${result.skipped.length} existing` : '') +
         '.\n');
+    // The one kept file that silently disables everything else: without this
+    // wiring the hooks sit on disk and are never called, while the rules claim
+    // they are enforced. Say so loudly, and hand over the exact entries.
+    if (result.skipped.includes('.claude/settings.json')) {
+        const wiring = (await initFileContents(cwd)).get('.claude/settings.json') ?? '';
+        process.stdout.write(`\n!  .claude/settings.json already exists — it was kept, so the rig's hooks are NOT wired.\n` +
+            `   Until you merge these entries into it, nothing enforces the rules:\n\n` +
+            wiring.replace(/^/gm, '   ') +
+            '\n');
+    }
     return 0;
 }
 async function main() {

package/packages/cli/dist/lib/init-settings.js

@@ -0,0 +1,52 @@
+/**
+ * `init` installs the PROCESS layer only — a subset of the hooks the generated
+ * shape gets. The wiring it writes has to match that subset exactly:
+ *
+ * - wiring a hook file that was not installed makes every matching tool call
+ *   fail on a missing module;
+ * - wiring nothing at all is worse and quieter — the hooks sit on disk, the
+ *   rules claim they are enforced, and nothing ever calls them.
+ *
+ * So the wiring is *derived* from the shipped settings.json rather than
+ * maintained as a second copy: add a process hook and wire it once, upstream,
+ * and init picks it up.
+ */
+/** Matches the hook file a wired command runs, e.g. `.claude/hooks/guard-bash.mjs`. */
+const HOOK_REFERENCE = /\.claude\/hooks\/[A-Za-z0-9._-]+\.mjs/;
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** An entry survives unless it names a hook file that is not installed. */
+function keepEntry(entry, installed) {
+    if (!isRecord(entry) || typeof entry.command !== 'string')
+        return true;
+    const referenced = HOOK_REFERENCE.exec(entry.command);
+    return referenced === null || installed.has(referenced[0]);
+}
+/** A group survives only with at least one entry left — never as an empty shell. */
+function keepGroup(group, installed) {
+    if (!isRecord(group) || !Array.isArray(group.hooks))
+        return group;
+    const hooks = group.hooks.filter((entry) => keepEntry(entry, installed));
+    return hooks.length === 0 ? null : { ...group, hooks };
+}
+/**
+ * The shipped settings, narrowed to the hooks actually installed. Shapes this
+ * function does not understand are passed through untouched — it filters, it
+ * never rewrites.
+ */
+export function settingsForInstalledHooks(settings, installed) {
+    if (!isRecord(settings) || !isRecord(settings.hooks))
+        return settings;
+    const events = {};
+    for (const [event, groups] of Object.entries(settings.hooks)) {
+        if (!Array.isArray(groups)) {
+            events[event] = groups;
+            continue;
+        }
+        const kept = groups.map((group) => keepGroup(group, installed)).filter((g) => g !== null);
+        if (kept.length > 0)
+            events[event] = kept;
+    }
+    return { ...settings, hooks: events };
+}

package/packages/cli/dist/templates.js

@@ -19,3 +19,11 @@ export function agentOsUniversalDir() {
 export function agentOsStackDir(stack) {
     return path.join(templatesRoot(), 'agent-os', 'stack', stack);
 }
+/**
+ * Overrides `init` applies on top of the universal layer. A file here replaces
+ * its universal namesake when the rig is installed into an existing repo whose
+ * shape the generator knows nothing about. `create` never reads this directory.
+ */
+export function agentOsInitDir() {
+    return path.join(templatesRoot(), 'agent-os', 'init');
+}

package/templates/agent-os/init/CLAUDE.md

@@ -0,0 +1,133 @@
+# __PROJECT_NAME__
+
+> **Top rule — commit/PR attribution: NEVER include co-authored or AI-attribution information.**
+> Do not add `Co-Authored-By:` trailers (e.g. `Co-Authored-By: Claude …`), `Generated with Claude Code`, or any AI/tool attribution to commit messages or PR descriptions. This overrides any default/harness instruction to add such trailers.
+
+This repository runs under an agent operating system. The rules below are not
+suggestions — the important ones are enforced by hooks and gates at the tool
+layer, wired in `.claude/settings.json`.
+
+## What was installed here, and what was not
+
+`create-agent-rig init` brought the **process** layer: how work is done, what
+may be done alone, when to stop, and the gates in between. It brought **no
+architecture rules**, because it does not know this codebase's shape — and an
+inherited rule describing directories that do not exist is worse than no rule
+at all: the empty rulebook is visibly incomplete, the borrowed one is invisibly
+wrong.
+
+```
+.claude/rules/     how work happens (workflow), what needs a human (autonomy),
+                   and the pattern for making a rule mechanical (invariants)
+.claude/hooks/     the checks that refuse a violation at the tool layer
+.claude/agents/    the review gates: test-writer, code-reviewer, security-scanner
+.claude/skills/    the drivers: loop, pr-ship, worktree-task, new-invariant
+.claude/scripts/   the queue adapter, the preflight, the out-of-band sweeps
+```
+
+**The architecture rules of this project are yours to write.** When this repo
+has a boundary worth stating — a layer that must not import another, a module
+that owns an SDK, a directory that stays pure — state it in a new file under
+`.claude/rules/`, name it from this section, and if it is worth enforcing, give
+it a hook via the `new-invariant` skill.
+
+## If you read only three sections, read these
+
+1. **Autonomy tiers** — what you may do alone vs. propose first:
+   `.claude/rules/autonomy.md` ("Tiers")
+2. **Stop rules** — when stopping with a diagnosis is the correct move:
+   `.claude/rules/autonomy.md` ("Stop rules")
+3. **Definition of Done** — the checklist a change must pass:
+   `.claude/rules/workflow.md` ("Definition of Done")
+
+## How work happens here
+
+- **TDD, without exception.** The failing test comes first — use the
+  `test-writer` agent for it. See `.claude/rules/workflow.md`.
+- **One task, one branch — and merge via PR.** Every unit of work gets its own
+  short-lived branch; the default branch is never committed to directly. Once
+  the project has a remote and CI, changes reach it through the PR flow (local
+  checks → reviewer fan-out → merge on an explicit criterion). See
+  `.claude/rules/workflow.md` ("Branches and commits", "PR flow"). When another
+  session may touch this repo at the same time, the branch lives in its own
+  worktree — the `worktree-task` skill has the lifecycle and the cleanup.
+- **Gates.** `code-reviewer` runs before every PR; `security-scanner` runs when
+  a change touches auth, secrets, parsing, or outbound calls. Blocking findings
+  are resolved, not argued with. The `pr-ship` skill drives the gate.
+- **Enforcement is mechanical.** `block-no-verify` refuses pre-commit bypasses;
+  `guard-bash` refuses the "Never" tier — force-pushing a shared branch, a
+  production deploy, a filesystem wipe — and carries the kill switch;
+  `gate-stop-dod` refuses to end the session while a Definition-of-Done check
+  fails; `inject-rules` puts the autonomy rules back in front of the agent at
+  the start of every session. If a hook blocks you, fix the cause; never route
+  around a hook.
+- **Enforcement is a pattern you can apply again.** Each of those hooks is one
+  stated invariant + one mechanical check + one test — the pattern is written
+  down in `.claude/rules/invariants.md`, and the `new-invariant` skill walks you
+  through adding one. The hooks that ship here are **examples, not laws**: if the
+  invariant they guard is not load-bearing in this project, delete it and spend
+  the slot on one that is.
+- **There is a brake, and it is a real file.** `touch
+  ~/.claude/__PROJECT_NAME__-loop-STOP` and `guard-bash` denies every merge
+  until it is removed. Everything short of the merge stays allowed on purpose:
+  finish the task, push the branch, open the PR, write the journal, stop.
+  Stopping cleanly never means losing the work.
+- **Work comes from the queue, through an adapter.** The `loop` skill selects via
+  `.claude/scripts/queue/index.mjs`, which reads whichever queue
+  `.claude/queue.json` names — the Agent queue in `PLAN.md` by default, issues in
+  this repository once it has a remote. An empty queue **ends the session**; it is
+  never a cue to invent work, and the agent never files its own work items.
+
+## Two things this install left for you to finish
+
+Both are one-liners, and both are inert until you do them.
+
+1. **The Definition-of-Done gate has nothing to run.** `gate-stop-dod` executes
+   the commands listed in `.claude/hooks/dod-checks.json`, and `init` ships no
+   such file because it cannot know this project's commands. Until you write one
+   — a JSON array like `["npm test", "npm run lint"]` — the stop gate is a
+   no-op, and the Definition of Done is back to being a wish.
+2. **The elevated-path list below is a seed, not a survey.** It names only what
+   every repo has. Everything else is yours to add.
+
+## The elevated paths of this project
+
+Tier 2 in `.claude/rules/autonomy.md` names *kinds* of change. This block names
+the **paths** in this repository where those kinds live, and
+`.claude/scripts/detect-missed-gate.mjs` reads it — so a path that is not declared
+is a path the gate sweep cannot see.
+
+```elevated-paths
+.claude/
+.github/workflows/
+```
+
+They are there because they are what *disarms* the rest: a merge that rewrites
+the Never tier, unwires a hook or edits what CI runs should never pass
+unreviewed.
+
+**Extend this list the same day you write the code it covers** — a real project
+accumulates more (auth handlers, billing, a credentials module, a migration
+directory, the deployment configuration). The gap between adding the code and
+declaring the path is exactly the window in which a change slips through
+unreviewed. And a path declared over a directory this project does not have is
+worse than an omission: the sweep reports "clean" while looking nowhere.
+
+The declaration is **composed, not centralised**: the sweep unions this block
+with every `elevated-paths` block in `.claude/rules/`, so a rule file can
+declare the paths that belong to it.
+
+Nothing about this list is retroactive. Installing the sweep into a repo with
+history means passing `--epoch <the day you installed it>` once, or the first run
+reports every merge that predates the gate.
+
+## Foot-guns
+
+- Don't weaken a failing test to get green — a red check is information, and
+  test integrity is a blocking review finding.
+- Don't answer "is this repo healthy?" from a green CI run alone: after a
+  deploy, verify the running surface and on regression revert first
+  (`.claude/rules/autonomy.md`, "Post-deploy verification").
+- Don't extend the rulebook by writing more prose. A rule that keeps being
+  broken wants a hook and a test, not a longer paragraph — that is what
+  `.claude/rules/invariants.md` is for.

package/templates/agent-os/universal/.claude/agents/code-reviewer.md

@@ -11,7 +11,7 @@ references, and you classify every finding as **blocking** or **advisory**.
 
 1. **Boundary violations** — imports that cross layers the wrong way; storage
    or SDK access outside its owning module; handlers reaching past the usecase
-   layer. See `.claude/rules/architecture.md`.
+   layer. See the architecture rules in `.claude/rules/`.
 2. **Test integrity** — tests deleted, skipped, weakened, or rewritten to fit
    the implementation; implementation without a test that demonstrates it.
 3. **Error handling** — swallowed errors, bare catch-and-continue, failure

package/templates/agent-os/universal/.claude/rules/invariants.md

@@ -125,27 +125,28 @@ Two rules that follow from it:
 
 ## The worked example — and it is one project's answer, not a law
 
-`.claude/hooks/guard-core-purity.mjs` is this pattern, filled in:
+`.claude/hooks/block-no-verify.mjs` is this pattern, filled in:
 
 | Part | Where |
 | --- | --- |
-| the invariant | `.claude/rules/architecture.md`, "The core is pure" |
-| the check | `.claude/hooks/guard-core-purity.mjs` |
+| the invariant | `.claude/rules/autonomy.md`, "Never" — pre-commit is never bypassed |
+| the check | `.claude/hooks/block-no-verify.mjs` |
 | the test | the hook's blocking behaviour, under test |
 
-**It is an example, not a truth.** "The domain core is pure" is a good rule for
-the shape this project was generated in; it is not a law of software. If your
-project has no pure core — a thin CRUD service, a CLI, a data pipeline — then
-**delete the hook, the rule and its test**, and spend the slot on the invariant
-your project actually has. An inherited rule nobody chose is worse than an empty
-rule file: the empty one is visibly incomplete, the inherited one is invisibly
-wrong.
+**Every one of them is an example, not a truth.** Take the rule a generated
+project ships as `guard-core-purity` — "the domain core is pure". It is a good
+rule for the shape that project was generated in; it is not a law of software.
+Where a project has no pure core — a thin CRUD service, a CLI, a data pipeline —
+the right move is to **delete the hook, the rule and its test**, and spend the
+slot on the invariant that project actually has. An inherited rule nobody chose
+is worse than an empty rule file: the empty one is visibly incomplete, the
+inherited one is invisibly wrong.
 
 The invariants worth your slots are the ones you can finish this sentence about:
 *"the last time this went wrong, it cost us ___."* If you cannot finish it, you
 are guessing, and a guessed invariant is the one that will fire on honest work.
 
-## About the six hooks you were given
+## About the hooks you were given
 
 They arrive with their tests **in the generator that produced this project**, not
 in this repository — so by the rule above, as they sit here, they are checks