create-agent-rig 0.2.0 → 0.3.0

package/templates/agent-os/universal/.claude/skills/worktree-task/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: worktree-task
+description: Start and finish a task in its own git worktree — creation off the remote default branch, and the full cleanup after the merge. Use at the start of every implementation task and after every merge, and whenever two sessions might touch this repo at once.
+allowed-tools: Bash, Read
+---
+
+# Worktree task lifecycle
+
+`.claude/rules/workflow.md` says **one task, one branch**. A worktree is how
+that rule survives a second session: two branches checked out at once, in two
+directories, with one `.git`. Without it, an unattended run and a hand-driven
+session share a working tree and overwrite each other's edits.
+
+**Use one when** anything else may touch this repo while you work — an
+unattended `loop` run, a colleague, a second Claude session. A single attended
+session on a quiet repo can just use a branch; the discipline that is never
+optional is the branch, not the worktree.
+
+## Start
+
+```bash
+cd "$(git rev-parse --show-toplevel)"   # ALWAYS anchor cwd first — see gotcha 1
+git fetch origin
+git worktree add -b <type>/<slug> .claude/worktrees/<slug> origin/HEAD
+git worktree list                       # verify the path is DIRECTLY under .claude/worktrees/
+```
+
+- **Branch off the remote default branch**, never a local copy — a stale local
+  default is how a task gets built on code that was replaced last week
+  (`.claude/rules/autonomy.md`, "Session staleness"). If `origin/HEAD` is not
+  set locally, name the branch explicitly: `origin/<default-branch>`.
+- **Branch name: `<type>/<slug>`**, type one of `feat|fix|docs|chore|refactor`.
+  If the project's queue gives work an id, the branch carries it —
+  `feat/<id>-<slug>` — because the branch name is often the only thread between
+  a queue item and its code. Work with no queue item keeps the plain form: **do
+  not invent an id.**
+- If tests will run there, install inside the worktree first. A worktree gets a
+  fresh, empty `node_modules`; a missing install fails as a confusing
+  module-resolution error rather than as "you forgot to install".
+
+## Finish (after the PR is merged)
+
+```bash
+cd "$(git -C <repo root> rev-parse --show-toplevel)"   # cd OUT of the worktree first — gotcha 2
+git worktree remove .claude/worktrees/<slug> --force
+git worktree prune
+git branch -D <type>/<slug>
+git push origin --delete <type>/<slug>    # if the merge did not already delete it
+rm -rf .claude/worktrees/<slug>           # only if `remove` left the directory behind
+```
+
+Add `.claude/worktrees/` to `.gitignore` once, so a live worktree never shows
+up as untracked noise in every `git status`.
+
+## Gotchas
+
+1. **A stale cwd creates worktrees inside dead paths.** If your shell sits in a
+   directory that has been removed (typically the *previous* task's worktree), a
+   relative `git worktree add .claude/worktrees/x` recreates the dead path and
+   nests the new worktree inside it. Always `cd` to the repo root by an
+   **absolute** path first, and verify with `git worktree list` afterwards.
+2. **`git worktree remove` fails while your shell is inside it** — or while a
+   watcher or install still holds a handle on `node_modules`. `cd` out first. If
+   the directory survives `remove --force`, run `git worktree prune` (the
+   metadata is then clean) and delete the leftover directory; retry later if it
+   is still busy.
+3. **Never touch a worktree you did not create.** Concurrent sessions make
+   worktrees appear and vanish mid-task. Removing another session's worktree
+   destroys unmerged work — and it is indistinguishable, afterwards, from that
+   session never having done the work.
+4. **One worktree per task.** Do not reuse a finished task's worktree: its
+   branch state and its install are both stale, and the reuse is invisible in
+   the diff.

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

@@ -46,18 +46,68 @@ them all; they are one rulebook.
   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").
+  `.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.** `guard-core-purity` catches an impure edit to
   the core the moment it lands; `guard-web-boundary` keeps the frontend off the
-  backend; `block-no-verify` refuses pre-commit bypasses; `gate-stop-dod`
-  refuses to end the session while a Definition-of-Done check fails. If a hook
-  blocks you, fix the cause; never route around a hook.
-- **Work comes from the queue.** The Agent queue in `PLAN.md` is where
-  autonomous work is picked up (the `loop` skill drives it); an empty queue
-  ends the session — it is never a cue to invent work.
+  backend; `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. 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.
+
+## 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
+packages/db/src/
+.claude/
+.github/workflows/
+```
+
+`.claude/` and `.github/workflows/` 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. `packages/db/src/` is the one the generated shape
+has.
+
+**They are a seed, not a law — the list is yours to extend.** It is what every
+generated shape has; a real project accumulates more (auth handlers, billing, a
+credentials module, a migration directory). Add a path the same day you add the
+code, because the gap between the two is exactly the window in which a change
+slips through unreviewed.
+
+The declaration is **composed, not centralised**: the sweep unions this block with
+every `elevated-paths` block in `.claude/rules/`, so a stack layer declares the
+paths that only exist in its shape. A gate declared over a directory this project
+does not have would report "clean" while looking nowhere.
+
+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
 

package/templates/agent-os/universal/PLAN.md

@@ -23,5 +23,31 @@ journal records history; the queues state only what is next.
 
 ## Journal
 
-<!-- One line per session, newest first: date-free, what moved, what blocked.
-     Prune freely — this is an operational log, not an archive. -->
+Newest first, date-free — order carries the sequence. Prune freely: this is
+operational memory, not an archive. An unattended run writes an entry at every
+stop **and** at checkpoints along the way, because a run that dies unexpectedly
+must not take its history with it.
+
+The fields exist so an entry can be visibly **incomplete**. A journal with no
+stated shape decays into a diary that reads fine and proves nothing.
+
+<!-- Template — copy the block, drop the fields that do not apply:
+
+### <one-line summary of the session>
+
+- **done** — what landed, one line each, with the PR reference
+- **escalated** — what stopped, and the diagnosis: what failed, what was tried,
+  the current hypothesis, and the one question whose answer unblocks it
+- **reviewed** — changes that went through a reviewer gate, and what it returned
+- **stopped at** — which stop condition ended the session (or "checkpoint,
+  still running")
+- **queue hygiene** — queue items fixed in passing: stale state, a dependency
+  that was already satisfied, an item that describes work already done
+- **cost** — the counts the session actually observed: reviewer subagents run,
+  CI runs consumed (re-runs included — the cheapest signal that a task fought
+  its tests), deploys triggered
+
+     A field the session cannot observe stays **visibly empty — never estimated**.
+     A plausible number will be believed, by the next reader and by the next run
+     reasoning about its own budget. Leave the gap; it is information.
+-->

package/templates/agent-os/universal/layers.json

@@ -2,14 +2,30 @@
   "process": [
     ".claude/rules/workflow.md",
     ".claude/rules/autonomy.md",
+    ".claude/rules/invariants.md",
+    ".claude/skills/new-invariant/SKILL.md",
+    ".claude/skills/new-invariant/guard-invariant.example.mjs",
+    ".claude/skills/new-invariant/guard-invariant.example.test.mjs",
     ".claude/agents/test-writer.md",
     ".claude/agents/code-reviewer.md",
     ".claude/agents/security-scanner.md",
     ".claude/hooks/block-no-verify.mjs",
+    ".claude/hooks/guard-bash.mjs",
     ".claude/hooks/gate-stop-dod.mjs",
     ".claude/hooks/inject-rules.mjs",
     ".claude/skills/pr-ship/SKILL.md",
     ".claude/skills/loop/SKILL.md",
+    ".claude/skills/worktree-task/SKILL.md",
+    ".claude/scripts/detect-missed-gate.mjs",
+    ".claude/scripts/reconcile-external-prs.mjs",
+    ".claude/scripts/stop-flag.mjs",
+    ".claude/scripts/preflight.mjs",
+    ".claude/scripts/queue/core.mjs",
+    ".claude/scripts/queue/plan-md.mjs",
+    ".claude/scripts/queue/github-issues.mjs",
+    ".claude/scripts/queue/jira.mjs",
+    ".claude/scripts/queue/index.mjs",
+    ".claude/queue.json",
     "PLAN.md"
   ],
   "architecture": [
@@ -17,5 +33,8 @@
     ".claude/hooks/guard-core-purity.mjs",
     ".claude/hooks/guard-web-boundary.mjs"
   ],
-  "meta": [".claude/settings.json", "CLAUDE.md"]
+  "meta": [
+    ".claude/settings.json",
+    "CLAUDE.md"
+  ]
 }

package/templates/skeleton/aws-serverless/.github/workflows/ci.yml

@@ -1,5 +1,10 @@
 name: CI
 
+# The default token is read-only for this job: CI needs nothing else, and a
+# workflow that can write is a workflow a compromised dependency can write with.
+permissions:
+  contents: read
+
 on:
   push:
   pull_request:
@@ -16,7 +21,7 @@ jobs:
         with:
           node-version: 22
           cache: pnpm
-      - run: pnpm install --no-frozen-lockfile
+      - run: pnpm install --frozen-lockfile
       - run: pnpm lint
       - run: pnpm typecheck
       - run: pnpm test

package/templates/skeleton/aws-serverless/gitignore

@@ -7,3 +7,11 @@ cdk.out/
 .next/
 out/
 next-env.d.ts
+.claude/worktrees/
+
+# secrets — never commit these
+.env
+.env.*
+!.env.example
+*.pem
+*.key

package/templates/skeleton/node-service/.github/workflows/ci.yml

@@ -1,5 +1,10 @@
 name: CI
 
+# The default token is read-only for this job: CI needs nothing else, and a
+# workflow that can write is a workflow a compromised dependency can write with.
+permissions:
+  contents: read
+
 on:
   push:
   pull_request:
@@ -16,7 +21,7 @@ jobs:
         with:
           node-version: 22
           cache: pnpm
-      - run: pnpm install --no-frozen-lockfile
+      - run: pnpm install --frozen-lockfile
       - run: pnpm lint
       - run: pnpm typecheck
       - run: pnpm test

package/templates/skeleton/node-service/gitignore

@@ -8,3 +8,11 @@ var/
 out/
 next-env.d.ts
 dist/
+.claude/worktrees/
+
+# secrets — never commit these
+.env
+.env.*
+!.env.example
+*.pem
+*.key