@yeison.restrepo.r/code-conductor 1.39.0 → 1.39.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,10 +1,38 @@
1
1
  # code-conductor
2
2
 
3
3
  [![npm version](https://img.shields.io/npm/v/%40yeison.restrepo.r%2Fcode-conductor.svg)](https://www.npmjs.com/package/@yeison.restrepo.r/code-conductor)
4
+ [![npm downloads](https://img.shields.io/npm/dw/%40yeison.restrepo.r%2Fcode-conductor.svg)](https://www.npmjs.com/package/@yeison.restrepo.r/code-conductor)
4
5
  [![License](https://img.shields.io/github/license/yeisonrestrepo/code-conductor.svg)](https://github.com/yeisonrestrepo/code-conductor/blob/main/LICENSE)
5
6
  [![GitHub issues](https://img.shields.io/github/issues/yeisonrestrepo/code-conductor.svg)](https://github.com/yeisonrestrepo/code-conductor/issues)
6
7
 
7
- **A governance layer for Claude Code sessions.** Hooks, guards, memory and release discipline that make an agent's work verifiable: what it may run is checked before it runs, what it decided is written where the next session will read it, and what shipped is asserted against the record by instruments that run in CI. It is a spec-first workflow, but the part worth your sixty seconds is that every claim below is checkable against a commit in this repository.
8
+ **Make Claude Code work like a senior engineer, not an enthusiastic intern.**
9
+
10
+ code-conductor is a drop-in governance layer for [Claude Code](https://www.anthropic.com/claude-code): slash commands, hooks, guardrails and a persistent memory system that turn free-form AI coding sessions into a disciplined, repeatable engineering workflow. What an agent may run is checked before it runs, what it decided is written where the next session will read it, and what shipped is asserted against the record by instruments that run in CI. It cuts token usage along the way.
11
+
12
+ One command to install. No code changes to your project. Works with any stack. And every claim below is checkable against a commit in this repository.
13
+
14
+ ---
15
+
16
+ ## Why this exists
17
+
18
+ If you have used Claude Code for more than a week, you have probably seen all of this:
19
+
20
+ - **It reads entire files, or entire codebases, to answer a one-line question.** Every one of those reads burns tokens and fills the context window with noise.
21
+ - **It forgets everything between sessions.** The conventions you explained yesterday, the architectural decision from last sprint, the workaround for that flaky test: gone. You explain them again, and pay for the tokens again.
22
+ - **It starts coding before anyone agreed on *what* to build.** Fast output, wrong problem, full rewrite.
23
+ - **The context window fills up silently**, the session auto-compacts at the worst possible moment, and the agent loses the thread mid-task.
24
+ - **It overwrites files it should not**, and nobody finds out until the diff.
25
+
26
+ None of these are model problems. They are *process* problems, and process is exactly what code-conductor installs.
27
+
28
+ | Without code-conductor | With code-conductor |
29
+ |---|---|
30
+ | Free-form prompt, then the agent guesses, overwrites, drifts | `/cc-spec`, approved spec, `/cc-plan`, confirmed steps, implement |
31
+ | Full files read on every turn | **Guards deny mass reads before they run**: memory first, then grep, then a bounded read |
32
+ | Conventions re-explained every session | Project memory and the detected stack loaded at session start |
33
+ | Context fills up until it breaks | A turn counter warns at 80%, and `/cc-compact` snapshots state before you compact |
34
+ | Verbose markdown handoffs eat context | **SNAP**: minified single-line JSON handoffs, schema-validated by `scripts/snap-validate.mjs`, at least 15% smaller than the markdown snapshot they replaced |
35
+ | Hand-tuned CLAUDE.md per project | **Stack auto-detection** fills in your build/test/lint/format commands from `package.json`, `go.mod`, `Cargo.toml` and friends |
8
36
 
9
37
  ---
10
38
 
@@ -12,7 +40,7 @@
12
40
 
13
41
  Three commands, from nothing to a guarded session. The output below is **real**, captured by running exactly these commands in a scratch directory.
14
42
 
15
- **Minimum safe version: `1.34.4`.** Older versions can strip or damage an existing `CLAUDE.md`: every release before `1.24` overwrote it with no backup, `1.24` through `1.34.3` silently removed your sections whose headings matched the managed block's, and an older pre-sentinel version left at least one field file with damaged lines. Install with `@latest`, as below.
43
+ **Minimum safe version: `1.34.4`.** Older versions can strip or damage an existing `CLAUDE.md`: every release before `1.24` overwrote it with no backup, `1.24` through `1.34.3` silently removed your sections whose headings matched the managed block's, and an older pre-sentinel version left at least one field file with damaged lines. Always install `code-conductor@latest`, as below.
16
44
 
17
45
  ```bash
18
46
  mkdir demo && cd demo && git init -q && npm init -y >/dev/null
@@ -21,7 +49,7 @@ npx @yeison.restrepo.r/code-conductor@latest --project
21
49
 
22
50
  The installer prints **nothing** and exits 0. That silence is deliberate and is asserted by a test: the stub-detection check runs *before* the seed, so a fresh scaffold cannot warn about the file it was just given (`tests/installer/deploy.test.js`, "says nothing on a fresh scaffold, whose stub it just wrote").
23
51
 
24
- You now have `.claude/` with `commands/`, `hooks/`, `memory/`, `scripts/` and `settings.json`. The third command is any command at all, because the guard is already live:
52
+ You now have `.claude/` with `commands/`, `hooks/`, `memory/`, `scripts/` and `settings.json`, and the guardrails are already live. The third command is any command at all:
25
53
 
26
54
  ```bash
27
55
  # scene 1: a mass content dump is denied, with a message that says what to do instead
@@ -38,525 +66,511 @@ but must not add it to clear its own denial.
38
66
  ```
39
67
 
40
68
  ```bash
41
- # scene 2: the decomposed form runs
69
+ # scene 2: the targeted form runs with no friction
42
70
  grep -n 'export' src/index.ts
43
71
  ```
44
72
 
45
73
  Nothing is printed by the hook. The command runs.
46
74
 
47
- ---
75
+ Commit `.claude/` to your repository and your whole team gets the same workflow, the same guardrails and the same shared memory.
48
76
 
49
- ## Guard 3, and what it learned
77
+ ### Dependencies
50
78
 
51
- Guard 3 scans every Bash command for **mass content dumps**: `cat *.ts`, `find` without a depth bound, a pager over a glob, a shell loop reading files. It denies before the command runs and names an alternative. It is not a sandbox and not a security boundary (see [What this is not](#what-this-is-not)).
79
+ code-conductor assumes these are already in place; the installer does not set them up for you:
52
80
 
53
- The interesting part is what it got wrong, because that is what the record documents.
81
+ | Dependency | Required for | How to get it |
82
+ |---|---|---|
83
+ | Node.js `>= 20` | Running the `code-conductor` CLI itself | Any current Node LTS |
84
+ | Claude Code | The environment every command, skill and hook here runs inside | See Anthropic's Claude Code docs |
85
+ | **superpowers plugin** | `/cc-spec` (`brainstorming`), `/cc-plan` (`writing-plans`), and `/cc-debug`, `/cc-refactor`, `/cc-review`, `/cc-test` (all four via `subagent-driven-development`) | Install from Claude Code's `/plugin` marketplace, then run `/reload-plugins`, **before** using these commands; without it, their `Skill(...)` calls fail |
86
+ | GitHub CLI (`gh`), authenticated | Only `/cc-orchestrate --ticket` and `ticket.mjs writeback`. code-conductor holds no credential; `gh` owns authentication | Install GitHub CLI, then run `gh auth login` |
87
+ | ui-ux-pro-max skill | Nothing: retired guidance | No shipped code downloads, installs or activates it. Its replacement is filed as `[FEAT-037]` |
54
88
 
55
- **It read quoted content as code.** A grep pattern, a commit message, an English sentence with a period: all scanned as though they were shell. Fixed in `1.31.x` by masking quoted spans before the checks, with two checks kept unmasked on purpose because a grep pattern and an alias value are the data those checks exist to read.
89
+ ---
56
90
 
57
- **It read heredoc bodies as code.** Writing a file whose content contained `[`, `?`, a `$(...)`, or an odd number of apostrophes was denied by patterns written to catch *reads*. Four specimens accumulated across four consecutive working sessions before it was fixed in `1.33.0` by giving both scanners a sixth state. The argument is one sentence: **a heredoc body is content being written and is already inside the command string the scanner is holding, so it cannot flood anything.**
91
+ ## The ideal workflow, day to day
58
92
 
59
- ### The honest numbers
93
+ A typical session looks like this:
60
94
 
61
- Every figure here is cited, and none of them is rounded in the project's favour.
95
+ ```
96
+ /cc-resume # restore context: memory, latest spec/plan, git state, detected stack
97
+ /cc-spec user-auth # agent searches the codebase, asks only for what is missing,
98
+ # writes a full spec, and WAITS for your approval
99
+ /cc-plan # from the approved spec: ordered tasks with exact file paths,
100
+ # tests, commit order and risks. You approve again.
101
+ /cc-implement # executes tasks one at a time, flipping [ ] to [>] to [X],
102
+ # without ever re-reading the whole plan
103
+ /cc-checkpoint # writes decisions, conventions and debt to memory
104
+ /cc-compact # snapshots phase state to a one-line JSON, then you /compact safely
105
+ ```
62
106
 
63
- | measurement | value | source |
64
- |---|---|---|
65
- | Guard 3 denials recovered from one real working session | **47 events, 43 unique commands** | `.claude/memory/project.md:991` |
66
- | ...of which flipped `deny` to `allow` after the `1.31.x` fixes | **36 of 43** | same table |
67
- | unplanned regressions from those fixes | **0** | same table |
68
- | this session's own denials, replayed verbatim against today's hook | **3: one now allowed, two still denied** | reproducible, below |
69
- | ...of the two still denied, the guard being **right** | **1** (a genuine shell loop) | corpus control row |
70
- | ...the guard being **wrong** | **1** (a surviving `P7` parity inversion) | recorded in `[BUG-041]`'s entry |
107
+ The key idea: **nothing gets built until a human approved what will be built.** The spec gate and the plan gate are cheap, a page of markdown to review, and they eliminate the single most expensive failure mode of AI coding: perfectly executed solutions to the wrong problem.
71
108
 
72
- The population in row 1 grew from 41 to 43 *mid-measurement, because two of the scripts written to perform the measurement were themselves denied by the bug they were measuring.* That sentence is in the record, not in the marketing.
109
+ Two things make this cheaper than it sounds:
73
110
 
74
- **One known false positive remains**, and it is named rather than buried: a mixed `grep` with pager pipelines still denies under `P7`. It is the residual the `[BUG-041]` entry describes, where the fragment starts inside an enclosing quoted region and every subsequent quote is parity-inverted.
111
+ - **Every phase opens with a resume read.** `/cc-spec`, `/cc-plan` and `/cc-implement` restore any context stored for the current git commit, so work survives branch switches, rollbacks and multi-day gaps (see [Local state cache and session persistence](#local-state-cache-and-session-persistence)).
112
+ - **Memory does the remembering.** Decisions land in `.claude/memory/project.md` (committed, shared with the team) and preferences in `~/.claude/memory/personal.md` (local). The next session reads them instead of asking you.
75
113
 
76
114
  ---
77
115
 
78
- ## Instruments: releases that verify their own record
116
+ ## Walkthrough: hands-off delivery with `/cc-orchestrate`
79
117
 
80
- Four checks live in `tools/` as tracked repository infrastructure. Three of them run on every pull request, so a divergence blocks the merge rather than waiting for someone to remember, and the fourth is a query run by hand:
118
+ For a well-defined backlog item, you do not have to drive every phase yourself. The orchestrator routes the item through **Define, Build and Verify** using five role agents (`spec`, `plan`, `code`, `audit`, `qa`), each boxed in by its own scope envelope.
81
119
 
82
- - **`version-gate.mjs`** takes `VERSION` as the authority and checks four other locations against it. Agreement reports as agreement, which sounds trivial until you learn that its predecessor reported `FAIL` on five locations that agreed, because it compared against a literal frozen two releases earlier. It runs at the merge gate through `tests/tools/repo-invariants.test.js`, and by hand at closeout.
83
- - **`record-parity.mjs`** asserts that every item the `CHANGELOG` claims has a closed backlog entry naming the version it shipped in. It exists because `[BUG-044]` shipped, was closed out in memory, and left its backlog entry reading `[ ]` for an entire release with no instrument comparing the two documents. It runs at the merge gate through `tests/tools/repo-invariants.test.js`, and by hand at closeout.
84
- - **`skip-baseline.mjs`** asserts each CI leg's exact skipped-test set against `tools/skip-baseline.json`, where every set is copied from that leg's own run rather than typed. It runs directly in `.github/workflows/test.yml` on the Node 20 and Node 24 legs, after the suite. It exists because CI was green with 96 tests skipped on Node 20 against 12 locally, and nothing asserted either number.
85
- - **`id-ceiling.mjs`** reports the highest filed id over the working tree **union** `origin/main`, counting only filed headings. Its predecessor counted id-shaped tokens anywhere, so it once read a plan file's prediction of its own output back as evidence. It is local-only by ruling: a person or agent runs it, over both legs, before minting an id. Its remote leg needs history the CI checkout does not fetch, so CI asserts only its duplicate-free half.
120
+ Launch Claude Code with the shipped review-loop exception, so the define review loop runs with zero owner wakes:
86
121
 
87
- **The example worth checking.** `[BUG-046]`'s own release ran those instruments against itself, then proved the green rather than trusting it: with the item's backlog heading deliberately flipped to `[ ]`, `record-parity` reported `FAIL [A] 1.32.2 claims BUG-046 but its heading reads [ ]` once per claim bullet and exited 1; flipped back, `RECORD_PARITY_OK`. The first release whose record cannot silently diverge is the release that made divergence detectable.
122
+ ```bash
123
+ claude --permission-mode auto --settings .claude/review-loop.settings.json
124
+ ```
88
125
 
89
- `tools/README.md` carries a **registry of five retired instruments**, each with the failure mode that retired it, so the sixth one gets written by someone who has met the list.
126
+ Then, inside the session:
90
127
 
91
- ---
128
+ ```
129
+ /cc-orchestrate FEAT-123
130
+ ```
92
131
 
93
- ## What this is not
132
+ What happens:
94
133
 
95
- - **Not a sandbox and not a security boundary.** Guard 3 is advisory tooling against context exhaustion and sloppy habits. It does not contain a hostile process and was never built to.
96
- - **Not a model.** It is configuration, hooks and scripts around Claude Code.
97
- - **Not finished.** See the limits below.
134
+ 1. **Start.** The orchestrator resolves your project's test command and records it in the run file. That exact command, and nothing else, is the only shell access the build roles will have. It is the package manager's `test` invocation when a root `package.json` has a `test` script (`npm test`, `pnpm test`, `yarn test`, or `bun run test` by lockfile, and `npm test` with none), detect-stack's test command when there is no `package.json`, and otherwise a halt (`ORCH_TEST_COMMAND_UNRESOLVED`). A resolved command carrying a chaining character halts too (`ORCH_TEST_COMMAND_UNSAFE`), so nothing is recorded that Guard 7 would deny.
135
+ 2. **Define.** A `spec` agent writes the spec. Before you approve it, a review loop runs: a fresh read-only `define-review` agent checks it against a declared checklist and sends open rows back to the author (see [Review loop configurations](#review-loop-configurations)). Then the same happens for the `plan` agent. **Both documents pause for your explicit approval**, shown with their SHA-256 hash and re-hashed immediately before approval, so what you approved is what ships.
136
+ 3. **Build.** A `code` agent is dispatched once per plan task, serially. For each role the orchestrator builds, validates (`snap-validate --to`) and installs a SNAP v3 band envelope, dispatches the agent named after the role, waits for its completion notice, and checks the one `SNAP_HANDBACK` line of its hand-back before the next. A wall of prose never reaches your context.
137
+ 4. **Verify.** An `audit` agent reviews the work statically, then a `qa` agent runs the recorded test command. `qa` cannot write files (enforced by Guard 5), so it only ever tests code it did not write.
138
+ 5. **Report.** You get every hand-back, both approvals and each review-loop outcome. **Release stays human.**
98
139
 
99
- ## Known limits
140
+ Useful variations:
100
141
 
101
- - **`[BUG-045]`, open:** the Guard 3 allowlist cannot cover a quoted path, because the boundary sets it interpolates contain no quote character, so an entry `docs/` does not cover `cat "docs/x.md" *.md`. Filed with its ritual priced, untouched pending its own change.
102
- - **`[BUG-032]`, open:** global memory preferences sit outside the documented lookup chain. Nothing in the chain points at `~/.claude/memory/personal.md`, and the installer never deploys `global/memory/`, so a preference filed there is never read by the agent it was written for.
103
- - **`[BUG-050]`, open:** the release instruments are silent on sub-shaped ids. `tools/record-parity.mjs` and `tools/id-ceiling.mjs` neither read nor reject an id like `[ARCH-008-S1]`, so a release claiming one would pass record parity having read nothing. No shipped release does; releases claim top-level ids until the item's spec chooses its repair.
104
- - **`[BUG-051]`, open:** two shipped commands run `scripts/detect-stack.mjs`, but the installer deploys the detector to `.claude/scripts/`. In an installed project, `/cc-stack` fails loud (`MODULE_NOT_FOUND`, "no stack"), and `/cc-resume`'s blank-command auto-fill silently skips. Until it is fixed, `/cc-init`, which already uses the deployed path, records the stack and commands.
105
- - **`[BUG-052]`, open:** the installer has no self-install guard. Its sweep of the 1.23.2 legacy root `scripts/` matches by exact file list, which the development repository satisfies by identity, so running `--project` inside this repository deletes tracked source. Do not run the installer against a clone of code-conductor itself.
106
- - **`[BUG-053]`, open:** the pre-commit test gate that the retired `install.sh` appended runs `npm test` with git's hook environment. From a linked worktree, git hands hooks an absolute `GIT_DIR` and `GIT_INDEX_FILE`, so the suite's fixture `git` commands write into the real repository's refs, config and index. Do not run the gate from a linked worktree.
107
- - **`[BUG-054]`, open:** `/cc-plan` generates staging steps that leave out the plan file itself, so a task's ticked checkboxes have no commit to ride. Until it is fixed, add the plan path to each task's `git add -u` list when you review a generated plan.
108
- - **The orchestrator (`1.36.0`) assumes cooperative agents.**
109
- - Guard 6 does not cover `Bash` writes, `claude -p` children included.
110
- - Inside a live run, a non-role agent the main session dispatched may write the orchestrator's write surface, the band envelope included.
111
- - R7 protects live runs only.
112
- - An agent writing after its hand-back is bounded only by the envelope in force, so a same-role next task inherits it.
113
- - Under auto permission mode no human stands behind a Bash write or a hook `ask`.
114
- - A Guard 6 warning reaches you, never the model's tool result, and not in every case. Measured on `claude` 2.1.287:
142
+ - `--auto` skips the pause between role dispatches. The spec and plan approvals always pause.
143
+ - `--ticket 42` (or an issue URL) binds the run to a GitHub issue. `start` fetches it once through `gh`, halts on a pull request, a closed issue, or an empty or over-65536-byte body, and writes the body into a fenced, hashed snapshot at `.conductor/ticket/<ITEM>.md`, which **only the spec role reads, as untrusted requirement input**. After release, the owner runs `node .claude/scripts/ticket.mjs writeback <ITEM> --version <v> --pr <N|url> [--changelog <file>] [--close]`, which posts one outcome comment to the bound issue, never twice for the same version, and closes it only with `--close`.
115
144
 
116
- | Channel | Permission mode | A prompting decision rides along | You see the warning |
117
- |---|---|---|---|
118
- | stderr | `auto` | no | no |
119
- | `systemMessage` (Guard 6's channel) | `auto` | no; a hook `ask` does not prompt under `auto` | yes, behind `PreToolUse:Write says: ` |
120
- | `systemMessage` | `default` | no | yes, in full |
121
- | `systemMessage` | `default` | yes, for example Guard 2's overwrite prompt | no: the warning is lost |
122
- - Agent definitions provided by plugins are not searched.
123
- - A halted run cannot be resumed, only ended and restarted.
145
+ What it needs: agent definitions named `spec`, `plan`, `code`, `audit` and `qa` in `.claude/agents/` or `~/.claude/agents/` (they ship from `1.37.0`); a resolvable test command, as above; and plans in the writing-plans format (`### Task N` with a `**Files:**` block). A failed validation halts the run, terminally in this version: recover with `end`, then `start`.
124
146
 
125
- The five role agent definitions it dispatches ship from `1.37.0`; their limits are the next item.
126
- - **The role agents (`1.37.0`) are bounded by their tool masks, and Guard 7 bounds one thing beneath them: the shell.**
127
- - `qa`'s test command is enforcement: Guard 5 keeps qa from writing, so qa only ever runs files it did not write. `code`'s identical allowance is process discipline, not a security boundary, because code writes the tests that command runs.
128
- - The profiles are live in this repository, because the mirror convention puts them in `.claude/agents/`. The standing rule forbids starting an orchestrator run here; it does not forbid the files being present. A role dispatched by hand through `/agents` or `Agent` creates no band envelope, so Guard 5 allows every write its mask holds, which is `[ARCH-010]`'s no-envelope rule. Guard 7 still denies it the shell. This is named, not fixed.
129
- - Installing or updating copies `.claude/agents/{spec,plan,code,audit,qa,define-review}.md` over the host project's files of the same names, as it does every shipped `.claude/` asset.
130
- - A gate certifies protocol position and the claim its role states, never the truth of the work beyond that claim.
131
- - **The review loop (`1.39.0`) is process discipline.** The spec or plan envelope stays installed after its hand-back, so the role can revise. Outside a round, its writes are bounded by its tool mask, Guard 5's scope, the re-hash before `approve`, and your review. Gating Guard 5 on an open round is a follow-up candidate.
132
- - **The `P7` false positive above**, still live.
133
- - **A re-run against an untouched `project.md` prints a recovery hint it cannot prove is needed.** If you install, never write anything into `.claude/memory/project.md`, and install again, you get a line suggesting the file may have been overwritten by a pre-`1.30.0` re-run. It was not; it equals the stub because it was seeded and never edited. The check compares content and **cannot distinguish "seeded and untouched" from "clobbered"**, which is why the wording is hedged to "may have been" rather than "was". This residual is named and accepted in [`BUG-039`'s spec at `:129`](docs/superpowers/specs/2026-09-27-bug039-installer-host-owned-state-design.md), where the alternative (restoring from the host's own git history) was rejected as writing host files out of the host's history with new failure modes. A **fresh** install is silent, which the Quickstart shows.
134
- - **Four open dossiers**, which are the evidence-collection pipeline working rather than a backlog: a session denial tally, one for interleaved-artifact reports, an intermittent commit-hook hang in the `snap-build` suite, and detect-stack failing whole on a non-string `package.json` script. A dossier holds specimens until a mechanism is characterized by probe; an id is minted only when the written condition is met. `[BUG-047]` is what that pipeline produces when it completes: an out-of-scope note, then a dossier, then four specimens across four sessions, then a mint, then a release.
147
+ While a run is live, hooks enforce the boundaries: the orchestrator itself cannot write tracked files, role agents can only write inside their envelope, and only the orchestrator can dispatch agents. These are process guardrails for cooperative agents, not a security sandbox; see [What this is not](#what-this-is-not) and [Known limits](#known-limits).
148
+
149
+ ### Review loop configurations
150
+
151
+ Before each define approval, `/cc-orchestrate` runs a review loop (`[FEAT-041]`): a fresh read-only `define-review` agent checks the spec or plan against a declared checklist, and while rows stay open the orchestrator sends them back to the role that wrote the document, up to three reviewer passes and two revisions. It is advisory: it never gates, never halts the run, and never replaces your approval, which only a message you send gives. What a round costs depends on how you launched Claude Code, measured on `claude` 2.1.292:
135
152
 
136
- **The living artifact is `AGENT-READABLE BACKLOG.md`.** It is not a tidy issue list. It carries amendments above the text they amend, premises that measurement later corrected, and wrong guesses recorded beside the probe that overturned them.
153
+ | Configuration | Per round |
154
+ |---|---|
155
+ | Auto mode with the shipped exception: `claude --permission-mode auto --settings .claude/review-loop.settings.json` | 0 owner wakes, 0 prompts |
156
+ | Default (ask) permission mode | 0 wakes; one approval per revision write, plus the orchestrator's `review` calls and report writes |
157
+ | Plain auto mode | the auto mode classifier denies the first revision request; the loop closes `skipped:denied`, and you get round 1's findings, unrevised |
158
+
159
+ `.claude/review-loop.settings.json` holds one auto mode allow rule that names this protocol. The installer never writes `autoMode` into `~/.claude/settings.json`, and Claude Code ignores `autoMode` in project settings, so the rule applies only when you pass the file yourself. Read it before you pass it: a cloned repository could ship a different file under the same name.
137
160
 
138
161
  ---
139
162
 
140
- ## Dependencies
163
+ ## Walkthrough: diagnosis before surgery with `/cc-debug`
141
164
 
142
- code-conductor assumes these are already in place — the installer does not set them up for you:
165
+ Most AI debugging goes: paste the error, watch the agent grep around, accept whatever fix it lands on. `/cc-debug` replaces that with a method:
143
166
 
144
- | Dependency | Required for | How to get it |
145
- |---|---|---|
146
- | Node.js `>= 20` | Running the `code-conductor` CLI itself | Any current Node LTS |
147
- | Claude Code | The environment every command/skill/hook in this repo runs inside | — |
148
- | **superpowers plugin** | `/cc-spec` (`brainstorming`), `/cc-plan` (`writing-plans`), and `/cc-debug`, `/cc-refactor`, `/cc-review`, `/cc-test` (all four via `subagent-driven-development`) | Install from Claude Code's `/plugin` marketplace, then run `/reload-plugins`, **before** using these commands — without it, their `Skill(...)` calls fail |
149
- | GitHub CLI (`gh`), authenticated | Only `/cc-orchestrate --ticket` and `ticket.mjs writeback`. conductor holds no credential; `gh` owns authentication | Install GitHub CLI, then run `gh auth login` |
150
- | ui-ux-pro-max skill | Nothing: retired guidance | No shipped code downloads, installs or activates it. Its replacement is filed as `[FEAT-037]` |
167
+ ```
168
+ /cc-debug "checkout total is wrong when a coupon is applied twice"
169
+ ```
170
+
171
+ 1. **Characterize first.** The agent states the symptom, expected behavior, reproduction steps, frequency and context, before touching anything.
172
+ 2. **Hypothesize.** It lists 2 to 4 root-cause hypotheses **ordered by probability** and asks which to investigate first. You stay in control of where the tokens go.
173
+ 3. **Investigate surgically.** Sub-agents do the digging with grep and `git log`; whole files are never read inline, and raw file contents never flood the main context. For visual or UI bugs, it offers to inspect through Playwright MCP.
174
+ 4. **Report with evidence.** Root cause at `file:line`, why it happens, what else could be affected, and the exact proposed change.
175
+ 5. **Fix only after you confirm.** The fix passes an adversarial resilience check (does it introduce a silent failure? a new boundary condition?) before it is applied. Afterward, it suggests the test that would have caught the bug.
176
+
177
+ The result is a debugging session that reads like an incident write-up, not a casino.
151
178
 
152
179
  ---
153
180
 
154
- ## The Problem
181
+ ## Where the token savings come from
155
182
 
156
- AI coding assistants are only as good as the structure you put around them. Without it, sessions drift: the agent overwrites files it shouldn't, skips the spec, reads entire codebases line by line, and produces code that solves the wrong problem efficiently. The result is fast output with slow outcomes — more rewrites, more context lost, more tokens burned. code-conductor is the structure.
183
+ Claude Code is priced in tokens, and unstructured sessions waste them in predictable ways. code-conductor attacks each one:
157
184
 
158
- | Without code-conductor | With code-conductor |
185
+ | Mechanism | What it does |
159
186
  |---|---|
160
- | Free-form prompt → agent guesses, overwrites, drifts | `/cc-spec` → approved spec → `/cc-plan` → confirmed steps → implement |
161
- | Full files read on every turn | grep/find before read — targeted tool calls only |
162
- | Conventions reset every session | Stack profile + memory loaded at session start |
163
- | Manual CLAUDE.md with `<command>` placeholders | **Stack auto-detection** — `code-conductor --project` reads your `package.json`, `go.mod`, `Cargo.toml`, etc. and auto-fills CLAUDE.md Development Commands so the agent never guesses your build/test/lint commands |
164
- | Verbose markdown handoffs eat context | **SNAP v1**: minified single-line JSON handoff format, schema-validated by `scripts/snap-validate.mjs`, ≥15% smaller than the markdown snapshot it replaces |
187
+ | **memory-first lookup chain** | Before reading any file, the agent checks project and personal memory, then grep/glob, and only then does a targeted read, always bounded, max 150 lines. |
188
+ | **Guard 1: large-file reads** | A `Read` of a file over 150 lines with no `limit` is **denied before it runs**, with a redirect to the lookup chain. |
189
+ | **Guard 3: mass content dumps** | Every Bash command is scanned against twelve dump patterns (`cat *.ts`, unbounded `find`, recursive match-all greps, shell read-loops and more) and denied with a targeted alternative. In one measured real-world session it caught **47 denial events across 43 unique commands**. |
190
+ | **Guard 4: node_modules** | Reads into `node_modules` are denied outright. Your context window is not for vendored code. |
191
+ | **Agent delegation** | Exploration runs in sub-agents that return a summary of at most 200 words. Intermediate data never enters the main context. |
192
+ | **SNAP handoffs** | Phase state is serialized as minified single-line JSON, schema-validated, at least 15% smaller than the markdown format it replaced. |
193
+ | **Context turn counter** | A hook counts turns and warns at 80% of a configurable threshold, then flags critical, so you compact on *your* schedule, at a phase boundary, with state snapshotted, instead of letting auto-compact shred the session. |
194
+ | **Verbosity control** | Responses default to `MIN` (one sentence plus a change list). A hook re-injects the level every turn so it never drifts as the window fills. `INFO` and `VERBOSE` are available per install. |
165
195
 
166
196
  ---
167
197
 
168
- ## Install
169
-
170
- **Minimum safe version: `1.34.4`.** Older versions can strip or damage an existing `CLAUDE.md`: every release before `1.24` overwrote it with no backup, `1.24` through `1.34.3` silently removed your sections whose headings matched the managed block's, and an older pre-sentinel version left at least one field file with damaged lines. Install with `@latest`, as below.
171
-
172
- ```bash
173
- npx @yeison.restrepo.r/code-conductor@latest # one-shot global setup
174
- # or
175
- npm install -g @yeison.restrepo.r/code-conductor && code-conductor
176
- ```
198
+ ## Guard 3, and what it learned
177
199
 
178
- ### Add to a project
200
+ Guard 3 scans every Bash command for **mass content dumps**: `cat *.ts`, `find` without a depth bound, a pager over a glob, a shell loop reading files. It denies before the command runs and names an alternative. It is not a sandbox and not a security boundary (see [What this is not](#what-this-is-not)).
179
201
 
180
- `--project` performs the global setup **and** scaffolds the project template in one call — there is no separate step to run first:
202
+ The interesting part is what it got wrong, because that is what the record documents.
181
203
 
182
- ```bash
183
- code-conductor --project # global setup + scaffold ./.claude in the current repo
184
- ```
204
+ **It read quoted content as code.** A grep pattern, a commit message, an English sentence with a period: all scanned as though they were shell. Fixed in `1.31.x` by masking quoted spans before the checks, with two checks kept unmasked on purpose because a grep pattern and an alias value are the data those checks exist to read.
185
205
 
186
- ### Flags
206
+ **It read heredoc bodies as code.** Writing a file whose content contained `[`, `?`, a `$(...)`, or an odd number of apostrophes was denied by patterns written to catch *reads*. Four specimens accumulated across four consecutive working sessions before it was fixed in `1.33.0` by giving both scanners a sixth state. The argument is one sentence: **a heredoc body is content being written and is already inside the command string the scanner is holding, so it cannot flood anything.**
187
207
 
188
- By default, the installer installs only the global core files. Use flags to extend this behavior.
208
+ ### The honest numbers
189
209
 
190
- | Flag | Description |
191
- |------|-------------|
192
- | `--project` / `-Project` | Also install the project template into the current directory |
193
- | `--no-deps` / `-NoDeps` | Skip dependency installation (Node tooling, Playwright MCP, plugins); copy agent files only |
194
- | `--verbosity MIN\|INFO\|VERBOSE` / `-Verbosity` | Set the default response verbosity (default: `MIN`). `MIN` = one sentence per response. `INFO` = bullet list. `VERBOSE` = full explanation. Re-run the installer to change it. |
210
+ Every figure here is cited, and none of them is rounded in the project's favour.
195
211
 
196
- ### Update
212
+ | measurement | value | source |
213
+ |---|---|---|
214
+ | Guard 3 denials recovered from one real working session | **47 events, 43 unique commands** | `.claude/memory/project.md:991` |
215
+ | ...of which flipped `deny` to `allow` after the `1.31.x` fixes | **36 of 43** | same table |
216
+ | unplanned regressions from those fixes | **0** | same table |
217
+ | this session's own denials, replayed verbatim against today's hook | **3: one now allowed, two still denied** | reproducible, below |
218
+ | ...of the two still denied, the guard being **right** | **1** (a genuine shell loop) | corpus control row |
219
+ | ...the guard being **wrong** | **1** (a surviving `P7` parity inversion) | recorded in `[BUG-041]`'s entry |
197
220
 
198
- Re-run the same install command. User-configured files are never overwritten; agent-managed files are always updated.
221
+ The population in row 1 grew from 41 to 43 *mid-measurement, because two of the scripts written to perform the measurement were themselves denied by the bug they were measuring.* That sentence is in the record, not in the marketing.
199
222
 
200
- > **Note:** Do not clone this repository into a parent directory named `node_modules`. Guard 4 checks path components and will block agent `Read` calls on source files if the repository root is nested inside such a directory.
223
+ **One known false positive remains**, and it is named rather than buried: a mixed `grep` with pager pipelines still denies under `P7`. It is the residual the `[BUG-041]` entry describes, where the fragment starts inside an enclosing quoted region and every subsequent quote is parity-inverted.
201
224
 
202
225
  ---
203
226
 
204
- ## How It Works
227
+ ## How it works
205
228
 
206
229
  code-conductor operates at three layers:
207
230
 
208
- **Global core** (`~/.claude/`) — applies to every project on your machine. Enforces the spec-first workflow, token efficiency rules, safety checks, code simplicity rules, and memory conventions. Installed once; always active.
209
-
210
- **Project template** (`.claude/`) — lives in your repo and is shared with your team via git. Adds project-specific slash commands, hooks that guard file writes, and a shared memory file for decisions, conventions, and technical debt.
211
-
212
- **Dynamic stack discovery + skills** — `/cc-stack` runs the bundled `detect-stack.mjs` scanner and writes your detected build/test/lint/format commands plus a concise, generated ruleset straight into your project `CLAUDE.md`. Skills extend the agent's behavior for cross-cutting concerns like code simplicity and UI/UX.
231
+ - **Global core** (`~/.claude/`) applies to every project on your machine: the spec-first workflow, token-efficiency rules, safety checks, simplicity rules and memory conventions. Installed once; always active.
232
+ - **Project template** (`.claude/`) lives in your repository and is shared with your team through git: project slash commands, write-guarding hooks, role agent definitions and the shared memory file for decisions, conventions and technical debt.
233
+ - **Dynamic stack discovery and skills.** `/cc-stack` runs the bundled `detect-stack.mjs` scanner and writes your detected build/test/lint/format commands, plus a concise generated ruleset, straight into your project `CLAUDE.md`, so the agent never guesses them. Skills enforce cross-cutting behavior (code simplicity, adversarial self-review, verbosity, memory-first, delegation) in every session.
213
234
 
214
235
  ---
215
236
 
216
- ## Available Commands
237
+ ## Command reference
217
238
 
218
- All commands are tagged `(Conductor)` in the Claude Code command palette so they're easy to spot alongside commands from other sources.
239
+ All commands are tagged `(Conductor)` in the Claude Code command palette, so they are easy to spot alongside commands from other sources.
219
240
 
220
241
  ### Global (all projects)
221
242
 
222
- | Command | Description |
223
- |---------|-------------|
224
- | `/cc-checkpoint` | Read the current session, extract decisions, conventions, and debt, then write them to `project.md` and `personal.md` with a timestamp. Run before `/compact`, after completing a feature, and after key architectural decisions. |
225
- | `/cc-stack` | Run the dynamic detector to identify your framework and write the detected commands and a generated ruleset into your project `CLAUDE.md`. |
226
- | `/cc-lang [code]` | Switch response language for this session. Code identifiers, filenames, and commit messages remain English regardless. |
243
+ | Command | What it does |
244
+ |---|---|
245
+ | `/cc-checkpoint` | Read the current session, extract decisions, conventions and debt, and write them to `project.md` and `personal.md` with a timestamp. Run before `/compact`, after completing a feature, and after key architectural decisions. |
246
+ | `/cc-stack` | Run the dynamic detector and write the detected commands and a generated ruleset into your project `CLAUDE.md` (the `- Stack:` line and the `## Active Stack Profiles` block). On later sessions it asks whether anything changed before re-detecting. |
247
+ | `/cc-lang [code]` | Switch response language for this session (`en` `es` `pt` `fr` `de` `it` `zh` `ja` `ko`). Code identifiers, filenames and commit messages stay English. |
248
+ | `/cc-compact` | Phase-boundary command. Serializes the current phase's essential state (decisions, pending steps, files touched, constraints) into a single-line SNAP JSON snapshot at `.claude/memory/session-snapshot.json` and, on Node `>= 22.5`, a git-hash-keyed row in the local `.conductor/cache.db`, then prompts you to run `/compact`. Run it at the end of every phase. |
227
249
 
228
250
  ### Project (requires `--project` install)
229
251
 
230
- | Command | Description |
231
- |---------|-------------|
232
- | `/cc-resume` | Restore full session context in one command: reads project identity, memory, latest spec and plan, git state, and loads the stack profile. Scans the active plan for `[>]` (interrupted) and `[!]` (failed) task markers and surfaces them in the session report. Run at the start of every session after initialization. |
233
- | `/cc-init` | Initialize or re-sync the project environment: detect stack, checkpoint memory, and verify hook integrity. Run at the start of every session. |
234
- | `/cc-spec [name]` | Search the codebase first, ask only for missing context, generate a full feature spec, and wait for your approval before any plan is made. |
235
- | `/cc-plan` | Require an approved spec, map the codebase, and generate an ordered implementation plan with exact file paths, a test list, a commit order, and identified risks. Every generated task line carries a unique `[T-NNN]` ID (min 3 digits, unlimited suffix depth) using plain ASCII checkboxes — enforced at generation time. |
236
- | `/cc-compact` | Phase-boundary command. Serializes the current phase's essential state (decisions, pending steps, files touched, constraints) into a single-line SNAP JSON snapshot at `.claude/memory/session-snapshot.json` — and, when Node `>= 22.5` is available, a git-hash-keyed row in the local `.conductor/cache.db` — then prompts you to run `/compact` to clear conversation history. Run at the end of every phase to prevent context overflow. |
237
- | `/cc-implement` | Execute implementation tasks from an approved plan using a surgical 5-step ritual: Grep-locate pending tasks → single-line Read verify → pre-flip `[ ]` to `[>]` → execute → post-flip to `[X]` or `[!]`. Never reads or rewrites the full plan file. Includes dependency evaluation, drift detection, and a Step 6 hook that records each task's final state to a local SQLite cache (see below). |
238
- | `/cc-orchestrate <ITEM> [--auto] [--ticket <N\|issue URL>]` | Route one backlog item through Define, Build and Verify. For each role it builds, validates (`snap-validate --to`) and installs a SNAP v3 band envelope, dispatches the agent named after the role, waits for its completion notice, and checks the one `SNAP_HANDBACK` line of its delivered hand-back before the next. It pauses before every dispatch unless `--auto`; the spec and plan approvals always pause. Before each, a review loop checks the document with a fresh read-only `define-review` agent and sends open rows back to its author, at most three passes; it is advisory and fails open (see Review loop configurations). A failed validation halts the run, terminally in this version (recover with `end`, then `start`). It needs agent definitions named `spec`, `plan`, `code`, `audit` and `qa` in `.claude/agents/` or `~/.claude/agents/`, which ship from `1.37.0`; a root `package.json` with a `test` script, or a stack whose test command detect-stack names, since `start` records the one command `code` and `qa` may run and halts when none resolves; and plans in the writing-plans format (`### Task N` with a `**Files:**` block). Release stays human. `--ticket` binds the run to a GitHub issue: `start` fetches it once through `gh`, halts on a pull request, a closed issue, or an empty or over-65536-byte body, and writes the body into a fenced, hashed snapshot at `.conductor/ticket/<ITEM>.md`, which only the spec role reads, as untrusted requirement input. After release, the owner runs `node .claude/scripts/ticket.mjs writeback <ITEM> --version <v> --pr <N\|url> [--changelog <file>] [--close]`, which posts one outcome comment to the bound issue, never twice for the same version, and closes it only with `--close`. |
239
-
240
- Each of `/cc-spec`, `/cc-plan`, and `/cc-implement` opens its phase with a **resume read** (`scripts/resume-read.mjs`): it restores any context stored for the current git commit, so work survives branch switches and rollbacks (see [Local State Cache & Session Persistence](#local-state-cache--session-persistence--v1220)).
241
- | `/cc-review [file\|dir]` | Review code in three layers - Critical / Important / Suggestion - then deliver a verdict and offer to auto-fix. |
242
- | `/cc-debug [problem]` | Generate hypotheses ordered by probability, confirm before investigating, use Playwright MCP for visual bugs, and report the root cause with a targeted fix. |
252
+ | Command | What it does |
253
+ |---|---|
254
+ | `/cc-init` | Initialize or re-sync the project environment: detect stack, checkpoint memory, verify hook integrity. Run at the start of every session. |
255
+ | `/cc-resume` | Restore full session context in one command: project identity, memory, latest spec and plan, git state and the detected stack. Scans the active plan for `[>]` (interrupted) and `[!]` (failed) task markers and surfaces them. |
256
+ | `/cc-spec [name]` | Search the codebase first, ask only for missing context, write a full feature spec, and **wait for your approval** before any plan is made. |
257
+ | `/cc-plan` | From an approved spec, map the codebase and write an ordered plan with exact file paths, a test list, a commit order and risks. Every task line carries a unique `[T-NNN]` ID (at least 3 digits, unlimited suffix depth) with plain ASCII checkboxes. |
258
+ | `/cc-implement` | Execute plan tasks with a surgical 5-step ritual: grep-locate pending tasks, single-line Read verify, pre-flip `[ ]` to `[>]`, execute, post-flip to `[X]` or `[!]`. Never reads or rewrites the full plan file. Includes dependency evaluation, drift detection, and a Step 6 hook that records each task's final state to the local SQLite cache. |
259
+ | `/cc-orchestrate <ITEM> [--auto] [--ticket <N\|issue URL>]` | Route one backlog item through Define, Build and Verify with role agents, validated SNAP envelopes, a review loop and human approval gates. See the [walkthrough](#walkthrough-hands-off-delivery-with-cc-orchestrate). |
260
+ | `/cc-review [file\|dir]` | Review in three layers (Critical / Important / Suggestion), deliver a verdict, and offer to auto-fix. |
261
+ | `/cc-debug [problem]` | Hypothesis-driven debugging. See the [walkthrough](#walkthrough-diagnosis-before-surgery-with-cc-debug). |
243
262
  | `/cc-refactor [file\|module]` | Diagnose complexity, plan ordered changes, apply one step at a time, and verify tests pass after each step. |
244
- | `/cc-test [scope]` | Analyze coverage gaps, write tests in AAA pattern, add Playwright E2E where applicable, run after confirmation, and report results. |
245
- | `/cc-docs [scope]` | Audit existing documentation, write inline docs in the correct format for your stack (JSDoc / docstrings / JavaDoc / GoDoc), and preview before writing. |
263
+ | `/cc-test [scope]` | Find coverage gaps, write AAA-pattern tests (plus Playwright E2E where applicable), run after confirmation, and report results. |
264
+ | `/cc-docs [scope]` | Audit documentation, write inline docs in your stack's format (JSDoc / docstrings / JavaDoc / GoDoc), and preview before writing. |
246
265
 
247
266
  ---
248
267
 
249
- ### Review loop configurations
268
+ ## Skills
250
269
 
251
- Before each define approval, `/cc-orchestrate` runs a review loop (`[FEAT-041]`): a fresh read-only `define-review` agent checks the spec or plan against a declared checklist, and while rows stay open the orchestrator sends them back to the role that wrote the document, up to three reviewer passes and two revisions. It is advisory: it never gates, never halts the run, and never replaces your approval, which only a message you send gives. What a round costs depends on how you launched Claude Code, measured on `claude` 2.1.292:
270
+ Skills extend agent behavior for cross-cutting concerns that apply regardless of stack.
252
271
 
253
- | Configuration | Per round |
254
- |---|---|
255
- | Auto mode with the shipped exception: `claude --permission-mode auto --settings .claude/review-loop.settings.json` | 0 owner wakes, 0 prompts |
256
- | Default (ask) permission mode | 0 wakes; one approval per revision write, plus the orchestrator's `review` calls and report writes |
257
- | Plain auto mode | the auto mode classifier denies the first revision request; the loop closes `skipped:denied`, and you get round 1's findings, unrevised |
272
+ - **code-simplifier (always active).** Applied to every piece of code written or reviewed: no speculative abstractions; functions of at most 30 lines doing one thing; flat over nested, with guard clauses and early returns; descriptive names (no `Base`, `Abstract`, `Manager`, `Handler`); comments explain why, never what.
273
+ - **critical-review (always active during implementation).** A 4-phase adversarial protocol: (1) **Pre-Flight**, identifying the happy path, failure points and boundary conditions before any code is written; (2) **Adversarial Review** for RESILIENCE (silent failures), EFFICIENCY (code smells) and FRICTION (happy-path friction); (3) **Self-Correction**, each weakness refactored and re-verified in isolation; (4) a required **`[VALIDATION]`** closing section: edge cases covered, justification, residual risks.
274
+ - **verbosity (always active).** Controls how much Claude writes per turn. The level is set at install time with `--verbosity` and stored in `~/.claude/memory/verbosity.md`; the default is `MIN`.
258
275
 
259
- `.claude/review-loop.settings.json` holds one auto mode allow rule that names this protocol. The installer never writes `autoMode` into `~/.claude/settings.json`, and Claude Code ignores `autoMode` in project settings, so the rule applies only when you pass the file yourself. Read it before you pass it: a cloned repository could ship a different file under the same name.
276
+ | Level | Behavior |
277
+ |---|---|
278
+ | `MIN` | One declarative sentence. `[CHANGES]` tag with file list only. |
279
+ | `INFO` | Bullet list of what changed and why, at most 5 bullets. `[CHANGES]` + `[REASON]`. |
280
+ | `VERBOSE` | Full explanation, prose allowed. All response tags. |
260
281
 
261
- ## Skills
282
+ - **memory-first (always active).** Before reading any file, Claude walks a lookup chain and stops at the first step that answers: (1) memory, both `.claude/memory/project.md` and `~/.claude/memory/personal.md`; (2) Grep / Glob; (3) a targeted read, last resort, always with `offset` + `limit`, at most 150 lines.
283
+ - **agent-delegation (always active).** Keeps the main context clean. Sub-agents handle exploration and parallel work and return a summary of at most 200 words; raw file contents and intermediate data never enter the main context.
284
+ - **ui-ux-pro-max (retired guidance, pending `[FEAT-037]`).** Earlier releases described this skill as installed from GitHub and switched on when `/cc-stack` detects a frontend stack. No shipped code does either. The `CLAUDE.md` templates still name it; `[FEAT-037]` replaces it with a frontend design skill stack, and this entry changes when that ships.
262
285
 
263
- Skills extend agent behavior for cross-cutting concerns that apply regardless of stack.
286
+ ---
264
287
 
265
- ### code-simplifier — always active
288
+ ## Guardrails (hooks)
266
289
 
267
- Applied to every piece of code written or reviewed in every session. Enforces:
290
+ Hooks run automatically at specific points in a Claude Code session and need no manual setup. The pre-tool-use front door is a single zero-dependency Node script (`pre-tool-use.mjs`): it fires before `Read`, `Write`, `Edit`, `create_file`, `write_file` and `Bash`, reads the `PreToolUse` payload from stdin, dispatches on `tool_name`, and returns its verdict as `hookSpecificOutput.permissionDecision`. Every path exits 0: a denial is data, never a crash.
268
291
 
269
- - No speculative abstractions — solve today's problem only
270
- - Functions ≤30 lines, doing one thing
271
- - Flat over nested — guard clauses and early returns
272
- - Descriptive names — no `Base`, `Abstract`, `Manager`, `Handler`
273
- - Comments explain why, never what
292
+ | Guard | Fires on | What it enforces |
293
+ |---|---|---|
294
+ | **1: Large-file read** | `Read` | A file over 150 lines needs an explicit `limit`; otherwise denied with a redirect to memory, grep, then a bounded read. |
295
+ | **2: Duplicate write** | `Write`, `create_file`, `write_file` | Writing to an existing path asks first, showing the path, line count and last-modified time: edit in place, confirm the overwrite, or cancel. `Edit` is deliberately not gated, because editing in place is what this guard recommends. |
296
+ | **3: Bash scan** | `Bash` | Twelve mass content-dump patterns denied before execution. Commands over 8192 characters and unclosed quotes are denied fail-closed. |
297
+ | **4: node_modules** | `Read` | A path carrying `node_modules` as an exact path component is denied, with backslashes and `..` resolved first. Use Glob for existence checks. |
298
+ | **5: Band scope** | role-agent writes | During orchestration, a band role can only write inside its installed envelope's scope. |
299
+ | **6: Orchestrator writes** | live orchestrate runs | The orchestrator session can only write its own run-state surface; nested agent dispatch is denied. |
300
+ | **7: Role shell** | role-agent `Bash` | `spec`, `plan` and `audit` get no shell; `code` and `qa` may run exactly one command, the recorded test command, byte for byte, no chaining. |
274
301
 
275
- ### ui-ux-pro-max — retired guidance, pending [FEAT-037]
302
+ **Guard 3 in detail.** The twelve patterns are: deep `find` without `-maxdepth 1`, `find -exec` with readers or shells, `xargs` with readers, `cat` or a pager followed by an unquoted glob, command substitution as a reader's argument, `grep -r` with a match-all pattern, `ls -R`, shell loops, `mapfile` and `readarray`, `eval`, `source` and the dot operator, alias remapping to a reader, and obfuscation sequences.
276
303
 
277
- Earlier releases described this skill as installed from GitHub and activated when `/cc-stack` detects a frontend stack. No shipped code does either. The `CLAUDE.md` templates still name it; `[FEAT-037]` replaces it with a frontend design skill stack, and this section changes when that ships.
304
+ Permanent exceptions live in `.claude/memory/bash-scan-allowlist.txt`, one entry per line, blank lines and `#` comments ignored and whitespace trimmed. An entry ending in `/` covers paths under that prefix, rejecting any suffix that walks up the tree with `..`; any other entry matches a whole command token. **Entries match literally: regex metacharacters carry no special meaning, so `file.ts` matches `file.ts` and nothing else.** The installer ships this file once as a commented template and creates it only when it is absent; it never overwrites an existing one. Every line in it disarms patterns for matching commands, so give each entry a comment saying why it exists; an uncommented entry is a review smell. An agent may *propose* an entry but must never add one to clear its own denial.
278
305
 
279
- ### critical-review — always active during implementation
306
+ Hit a block you believe is wrong? Re-run the command with `CC_GUARD3_WARN=1` and the guard asks instead of denying, carrying the same pattern ids. That is a triage aid for reporting a false positive while you keep working, not a configuration mode: the allowlist is the sanctioned permanent exception. The variable affects Guard 3 alone.
280
307
 
281
- Applied to every implementation task via a 4-phase adversarial protocol:
308
+ **Guard 5 in detail.** A `Write`, `Edit`, `create_file` or `write_file` from a subagent whose `agent_type` names a band role (`spec`, `plan`, `code`, `audit`, `qa`) is checked against the nearest `.claude/memory/band-envelope.json` above its working directory, a SNAP v3 envelope. A malformed envelope, an agent that is not the envelope's role, a role not holding `RW`, or a path outside the envelope's `scope` globs (anchored at the band root, the directory whose `.claude/` holds the envelope) is denied with a named reason. The main session, any other agent, and any project without an envelope are untouched. It assumes cooperative agents: `agent_type` is a name taken on trust, and `Bash`, `NotebookEdit`, MCP write tools and symlinked paths are not covered.
282
309
 
283
- 1. **Pre-Flight** — Happy Path, Failure Points, and Boundary Conditions identified before any code is written
284
- 2. **Adversarial Review** — RESILIENCE (silent failures), EFFICIENCY (code smells), FRICTION (happy-path friction)
285
- 3. **Self-Correction** — each weakness refactored and re-verified in isolation
286
- 4. **`[VALIDATION]`** — required closing section on every implementation: edge cases covered, best-outcome justification, residual risks
310
+ **Guard 6 in detail.** While a `/cc-orchestrate` run is live, its run file `.claude/memory/orchestrator-run.json` binds it to one session by `session_id`. In that session, a `Write`, `Edit`, `create_file` or `write_file` from anything but a band role (the main session, a payload carrying only `agent_id`, any other agent) is denied with `ORCH_WRITE_DENIED` unless its target lies inside the orchestrator's write surface, anchored at the run root: `.claude/memory/orchestrator-run.json`, `.claude/memory/band-envelope.json`, `.claude/memory/session-snapshot.json` and `.conductor/**`. Band roles stay under Guard 5. A run file from another session is stale and an unreadable one is invalid: both warn (`ORCH_RUN_STALE`, `ORCH_RUN_INVALID`) with the cleanup command and never block. While the run is live, a subagent's `Agent` or `SendMessage` call is denied with `ORCH_NESTED_DISPATCH`, so only the orchestrator dispatches or messages agents (R7; the hook's matcher names both tools). Outside a live run there is no Guard 6. Its limits are listed under [Known limits](#known-limits).
287
311
 
288
- ### verbosity — always active
312
+ **Guard 7 in detail.** A `Bash` call from a subagent whose `agent_type` names a band role is decided before Guard 3, so Guard 3's `CC_GUARD3_WARN` ask can never outrank it. `spec`, `plan` and `audit` have no shell (`ROLE_SHELL_DENIED`). `code` and `qa` may run exactly one command, byte for byte: the `test_command` that `orchestrate.mjs start` recorded in the run file of a run live in their session. A command carrying `;`, `&`, `|`, a backtick, `$(`, `<`, `>` or a line break is denied first (`ROLE_SHELL_CHAINING`). No run file, a run of another session, or no recorded command is denied (`ROLE_SHELL_UNRESOLVED`), and any other command is denied naming the allowed one (`ROLE_SHELL_NOT_ALLOWED`). An error inside the guard denies too, and `CC_HOOK_ALLOW` does not reach it. The main session and every other agent are untouched.
289
313
 
290
- Controls how much Claude writes per turn. The level is set at install time via `--verbosity` and stored in `~/.claude/memory/verbosity.md`. Default: `MIN`.
314
+ **Unparseable input fails closed.** It is denied with one stderr line naming `CC_HOOK_ALLOW=1`, which overrides that denial alone and leaves every guard fully active on every payload the hook can read. Set `CC_HOOK_DEBUG=1` to see the diagnostic lines it otherwise swallows.
291
315
 
292
- | Level | Behavior |
293
- |-------|----------|
294
- | `MIN` | One declarative sentence. `[CHANGES]` tag with file list only. |
295
- | `INFO` | Bullet list of what changed and why. Max 5 bullets. `[CHANGES]` + `[REASON]`. |
296
- | `VERBOSE` | Full explanation, prose allowed. All response tags. |
316
+ ### The other hooks
297
317
 
298
- ### memory-first — always active
318
+ - **context-guard** (global + project). Fires on every `UserPromptSubmit` and atomically increments a turn counter in `.claude/memory/turn-count.txt`. At 80% of the threshold it emits a CONTEXT WARNING; at or above the threshold, CONTEXT CRITICAL. The threshold is read from `.claude/memory/context-threshold.txt` (default 25). Ships for Unix (`context-guard.sh`) and Windows (`context-guard.ps1`). `CC_GUARD_DEBUG=1` prints debug info to stderr; `CC_PROJECT_ROOT` overrides the project root used for the memory directory.
319
+ - **post-compact.** Fires after `/compact`. Resets the turn counter to 0, reads `project.md`, shows the timestamp of the last `/cc-checkpoint`, and reminds you to checkpoint if this session's context has not been saved. Ships for Unix and Windows.
320
+ - **verbosity-remind** (global + project). Fires on every `UserPromptSubmit` and re-injects the active MIN/INFO/VERBOSE constraint, so the level does not drift as the window fills (BUG-014). The global hook defers to a project-level hook if one exists (upward traversal from `$PWD`), and the level is read from the nearest `.claude/memory/verbosity.md` ancestor file. Set `CC_VERBOSITY_SKIP=1` to disable it in CI/CD.
299
321
 
300
- Before reading any file, Claude walks a priority lookup chain and stops at the first step that answers the question:
322
+ When `$HOME` is unset (some CI containers, `sudo -H` shells, minimal Docker images), `verbosity-remind.sh` exits 0 with no output and Claude falls back to MIN. Set `HOME` to the appropriate home directory in the container to restore full hook behavior. The hook never raises an error when `$HOME` is absent, so your session is never blocked.
301
323
 
302
- 1. **Project memory**: `.claude/memory/project.md`
303
- 2. **Grep / Glob** — pattern searches
304
- 3. **Targeted read** — last resort, always with `offset` + `limit`, max 150 lines
324
+ ---
305
325
 
306
- ### agent-delegation — always active
326
+ ## Memory architecture
307
327
 
308
- Keeps the main context clean. Sub-agents handle exploration and parallel work; they return a ≤200-word summary to the main context. Raw file contents and intermediate data never enter the main context.
328
+ ```
329
+ ~/.claude/memory/
330
+ personal.md local only, never committed: your preferences and shortcuts
331
+ verbosity.md agent-managed, set by the installer: active MIN/INFO/VERBOSE level
309
332
 
310
- ---
333
+ <project>/.claude/memory/
334
+ project.md in git, shared with the team: decisions, conventions,
335
+ debt, workarounds
336
+ ```
337
+
338
+ `/cc-checkpoint` writes to both. Run it before `/compact`, after completing a feature, and after any key architectural decision. The payoff compounds: every decision captured once is a conversation, and a few thousand tokens, the team never has again.
339
+
340
+ ### Local state cache and session persistence
341
+
342
+ On top of the markdown memory, `/cc-implement`'s Step 6 hook records each task's final state to a local SQLite cache at `.conductor/cache.db`, written by the bundled `scripts/conductor-db.mjs` engine, a zero-dependency ES module wrapping Node's built-in `node:sqlite`.
343
+
344
+ - **Schema (v2, ARCH-008):** `task_state(plan_file, task_id, state, updated_at)` keyed by `(plan_file, task_id)`, with `plan_file` normalized to a repo-relative POSIX path so the same plan de-duplicates across working directories; plus `sessions`, `snapshots` (one verbatim SNAP blob per git commit, newest wins) and `raw_history`. Upserts on every write.
345
+ - **Runtime-gated:** `node:sqlite` needs Node `>= 22.5`, so every caller probes the Node version and self-disables below it. `engines.node` stays `>=20`; the cache is an optimization, never a requirement.
346
+ - **Non-authoritative and fail-safe:** the plan markdown and the `.claude/memory/session-snapshot.json` handoff remain the sources of truth. Every failure path (absent `node:sqlite`, a corrupt or non-regular file at the db path, `SQLITE_BUSY`, a newer schema, CLI misuse) degrades to a single `CONDUCTOR_DB:` stderr line and exit 0. A corrupt db is renamed aside, never deleted, and recreated.
347
+ - **Gitignored:** `.conductor/` is local-only and never committed.
311
348
 
312
- ## Hooks
349
+ **Phase-entry resume.** `/cc-spec`, `/cc-plan` and `/cc-implement` open each phase by running `scripts/resume-read.mjs`, which resolves the current git commit hash and restores any context stored for it, surviving branch switches and rollbacks. A valid DB snapshot for the commit wins; otherwise it falls back to the `.claude/memory/session-snapshot.json` handoff written by `/cc-compact`. A hit prints a `RESUME_HIT` block the command adopts as its starting context; a clean miss proceeds fresh; a readable-but-corrupt handoff halts the phase (exit `4`) with a `SNAP_INVALID` notice so you can inspect it. This completed the **ARCH-008** milestone: relational schema (v1.20.0), checkpoint/compact writers (v1.21.0), phase-entry readers (v1.22.0).
313
350
 
314
- Hooks run automatically at specific points in a Claude Code session. They require no manual setup.
351
+ ---
315
352
 
316
- ### pre-tool-use
353
+ ## Install
317
354
 
318
- Fires before `Read`, `Write`, `Edit`, `create_file`, `write_file` and `Bash`. A single zero-dependency Node front door (`pre-tool-use.mjs`) reads the `PreToolUse` payload from stdin, dispatches on `tool_name`, and returns its verdict as `hookSpecificOutput.permissionDecision`. Every path exits 0: a denial is data, never an exit code.
355
+ **Minimum safe version: `1.34.4`.** Older versions can strip or damage an existing `CLAUDE.md`: every release before `1.24` overwrote it with no backup, `1.24` through `1.34.3` silently removed your sections whose headings matched the managed block's, and an older pre-sentinel version left at least one field file with damaged lines. Install `code-conductor@latest`, as below.
319
356
 
320
- **Large-file Read guard (Guard 1)** - a `Read` of a file over 150 lines that names no `limit` is denied, and the reason redirects Claude to the orchestrator lookup chain (memory, grep, targeted read). Prevents reading entire codebases when a targeted search would do.
357
+ ```bash
358
+ npx @yeison.restrepo.r/code-conductor@latest # one-shot global setup
359
+ # or
360
+ npm install -g @yeison.restrepo.r/code-conductor && code-conductor
361
+ ```
321
362
 
322
- **Duplicate file guard (Guard 2)** - a `Write`, `create_file` or `write_file` naming a path that already exists returns `ask`, showing the path, line count and last-modified timestamp with three options: edit in place, confirm the overwrite, or cancel. `Edit` is deliberately not gated, because editing in place is the action this guard recommends.
363
+ **Add to a project.** `--project` performs the global setup **and** scaffolds the project template in one call; there is no separate step to run first:
323
364
 
324
- **Bash scan guard (Guard 3)** - every `Bash` command is matched against twelve mass content-dump patterns before it runs: deep `find` without `-maxdepth 1`, `find -exec` with readers or shells, `xargs` with readers, `cat` or a pager followed by an unquoted glob, command substitution as a reader's argument, `grep -r` with a match-all pattern, `ls -R`, shell loops, `mapfile` and `readarray`, `eval`, `source` and the dot operator, alias remapping to a reader, and obfuscation sequences. Commands over 8192 characters and unclosed quotes are denied fail-closed.
365
+ ```bash
366
+ npx @yeison.restrepo.r/code-conductor@latest --project # global setup + scaffold ./.claude
367
+ ```
325
368
 
326
- Permanent exceptions live in `.claude/memory/bash-scan-allowlist.txt`, one entry per line, blank lines and `#` comments ignored and whitespace trimmed. An entry ending in `/` covers paths under that prefix, rejecting any suffix that walks up the tree with `..`; any other entry matches a whole command token. **Entries match literally: regex metacharacters carry no special meaning, so `file.ts` matches `file.ts` and nothing else.** The installer ships this file once as a commented template and creates it only when it is absent; it never overwrites an existing one. Every line in it disarms patterns for matching commands, so give each entry a comment saying why it exists; an uncommented entry is a review smell.
369
+ By default, the installer installs only the global core files. Flags extend that:
327
370
 
328
- Hit a block you believe is wrong? Re-run the command with `CC_GUARD3_WARN=1` and the guard asks instead of denying, carrying the same pattern ids. That is a triage aid for reporting a false positive while you keep working, not a configuration mode: the allowlist is the sanctioned permanent exception. The variable affects Guard 3 alone.
371
+ | Flag | Description |
372
+ |---|---|
373
+ | `--project` / `-Project` | Also install the project template into the current directory |
374
+ | `--no-deps` / `-NoDeps` | Skip dependency installation (Node tooling, Playwright MCP, plugins); copy agent files only |
375
+ | `--verbosity MIN\|INFO\|VERBOSE` / `-Verbosity` | Default response verbosity (default `MIN`). `MIN` = one sentence per response, `INFO` = bullet list, `VERBOSE` = full explanation. Re-run the installer to change it. |
329
376
 
330
- **node_modules guard (Guard 4)** - a `Read` whose path carries `node_modules` as an exact path component is denied, with backslashes and `..` resolved first. Use Glob for existence checks.
377
+ **Updating:** re-run the same install command. User-configured files are never overwritten; agent-managed files are always updated.
331
378
 
332
- **Band scope guard (Guard 5)** - a `Write`, `Edit`, `create_file` or `write_file` from a subagent whose `agent_type` names a band role (`spec`, `plan`, `code`, `audit`, `qa`) is checked against the nearest `.claude/memory/band-envelope.json` above its working directory, a SNAP v3 envelope. A malformed envelope, an agent that is not the envelope's role, a role not holding `RW`, or a path outside the envelope's `scope` globs (anchored at the band root, the directory whose `.claude/` holds the envelope) is denied with a named reason. The main session, any other agent, and any project without an envelope are untouched. It assumes cooperative agents: `agent_type` is a name taken on trust, and `Bash`, `NotebookEdit`, MCP write tools and symlinked paths are not covered.
379
+ Two cautions:
333
380
 
334
- **Orchestrator write guard (Guard 6)** - while a `/cc-orchestrate` run is live, its run file `.claude/memory/orchestrator-run.json` binds it to one session by `session_id`. In that session, a `Write`, `Edit`, `create_file` or `write_file` from anything but a band role (the main session, a payload carrying only `agent_id`, any other agent) is denied with `ORCH_WRITE_DENIED` unless its target lies inside the orchestrator's write surface, anchored at the run root: `.claude/memory/orchestrator-run.json`, `.claude/memory/band-envelope.json`, `.claude/memory/session-snapshot.json` and `.conductor/**`. Band roles stay under Guard 5. A run file from another session is stale and an unreadable one is invalid: both warn (`ORCH_RUN_STALE`, `ORCH_RUN_INVALID`) with the cleanup command and never block. While the run is live, a subagent's `Agent` or `SendMessage` call is denied with `ORCH_NESTED_DISPATCH`, so only the orchestrator dispatches or messages agents (R7; the hook's matcher names both tools). Outside a live run there is no Guard 6: any agent can dispatch agents, as before. Limits are stated, not closed:
335
- - `Bash` writes are not covered, as under Guard 5. That includes a role spawning `claude -p`, whose child session carries another `session_id` and is warned, not blocked.
336
- - Under auto permission mode no human stands behind a Bash write or a hook `ask`.
337
- - Inside the live session, only a main-session-dispatched non-role agent can write the surface itself, the band envelope included. So Guard 6 bounds where the orchestrator writes, not who writes inside that surface.
338
- - An agent that keeps writing after its hand-back is bounded only by the envelope in force.
381
+ - Do **not** clone this repository under a directory named `node_modules`. Guard 4 checks path components and will block agent `Read` calls on its source files.
382
+ - `--project` refuses to run in a directory whose `package.json` names this package, such as a clone of this repository (`[BUG-052]`, fixed in `1.39.1`): the installer exits 1 before writing anything, global half included, because its project half would land on its own source tree.
339
383
 
340
- **Role shell guard (Guard 7)** - a `Bash` call from a subagent whose `agent_type` names a band role is decided before Guard 3, so Guard 3's `CC_GUARD3_WARN` ask can never outrank it. `spec`, `plan` and `audit` have no shell (`ROLE_SHELL_DENIED`). `code` and `qa` may run exactly one command, byte for byte: the `test_command` that `orchestrate.mjs start` recorded in the run file of a run live in their session. A command carrying `;`, `&`, `|`, a backtick, `$(`, `<`, `>` or a line break is denied first (`ROLE_SHELL_CHAINING`). No run file, a run of another session, or no recorded command is denied (`ROLE_SHELL_UNRESOLVED`), and any other command is denied naming the allowed one (`ROLE_SHELL_NOT_ALLOWED`). An error inside the guard denies too, and `CC_HOOK_ALLOW` does not reach it. The main session and every other agent are untouched. The two allowances differ in kind: for `qa`, which Guard 5 keeps from writing, the guard is enforcement; for `code`, which writes the tests the command runs, it is process discipline, not a security boundary. `start` resolves the command before it writes anything: the package manager's `test` invocation when a root `package.json` has a `test` script (`npm test`, `pnpm test`, `yarn test`, or `bun run test` by lockfile, and `npm test` with none), detect-stack's test command when there is no `package.json`, and otherwise a halt (`ORCH_TEST_COMMAND_UNRESOLVED`). A resolved command carrying a chaining character halts too (`ORCH_TEST_COMMAND_UNSAFE`), so nothing is recorded that Guard 7 would deny.
384
+ ### How the installer treats your CLAUDE.md
341
385
 
342
- Input the hook cannot parse fails closed: it is denied with one stderr line naming `CC_HOOK_ALLOW=1`, which overrides that denial alone and leaves every guard fully active on every payload the hook can read. Set `CC_HOOK_DEBUG=1` to see the diagnostic lines it otherwise swallows.
386
+ `CLAUDE.md` and `.gitignore` are **merged**, never overwritten. Everything else the installer ships (`settings.json`, hooks, commands, `scripts/`) is replaced on every run.
343
387
 
344
- ### context-guard *(global + project)* — v1.15.0
388
+ - **code-conductor owns one block and nothing else.** Its content lives between `<!-- cc:managed:start -->` and `<!-- cc:managed:end -->`, and those two markers alone decide ownership; a heading's name never does. Every upgrade replaces the block's contents wholesale, so released improvements reach existing installs. Edits inside the block are lost, and recoverable from the backup.
389
+ - **Everything outside the block is yours, byte for byte.** Nothing outside it is removed, rewritten, reordered or added.
390
+ - **A file without the markers gets the block appended at the end**, after one blank line and in your file's line endings, and nothing else changes. If your file already has sections named like the block's (`## Agent Identity`, `## Hard Constraints` and so on), you will see both: yours above, code-conductor's inside the block. That is deliberate. The installer never decides which of your sections are really its own; reconciling them is planned for `/cc-stack` as `[FEAT-040]`.
391
+ - **Before any change, the installer copies your file to `CLAUDE.md.installer-backup.<UTC timestamp>`**, keeps the five most recent, and prints where it put it:
345
392
 
346
- Fires on every `UserPromptSubmit`. Atomically increments a turn counter in `.claude/memory/turn-count.txt`. At 80% of the configured threshold it emits ⚠ CONTEXT WARNING; at or above the threshold it emits 🚨 CONTEXT CRITICAL. The threshold is read from `.claude/memory/context-threshold.txt` (default: 25). After `/compact`, the `post-compact` hook resets the counter to 0.
393
+ ```
394
+ code-conductor: backed up CLAUDE.md to CLAUDE.md.installer-backup.20260930T120000Z before merging (git-ignored by design)
395
+ ```
347
396
 
348
- Available on both Unix (`context-guard.sh`) and Windows (`context-guard.ps1`). Set `CC_GUARD_DEBUG=1` to print debug info to stderr. Set `CC_PROJECT_ROOT` to override the project root used for the memory directory.
397
+ Backups are git-ignored so nobody commits one by accident and they stay out of every teammate's `git status`; the printed line is how you find yours. A fresh install, and a re-run that changes nothing, print nothing.
349
398
 
350
- ### post-compact
399
+ The same rules apply to `~/.claude/CLAUDE.md`, whose backup line names the `~/.claude/` path. If your file ends inside a code fence that is never closed, the installer leaves it untouched with a warning, because a block appended there would be hidden inside the fence.
351
400
 
352
- Fires after `/compact`. Resets the turn counter to 0, reads `project.md`, shows the timestamp of the last `/cc-checkpoint`, and reminds you to run `/cc-checkpoint` if context from this session hasn't been saved yet. Prevents losing decisions and conventions when the context window is compressed.
401
+ If the markers in your file are damaged (a `start` with no `end`, two blocks, an `end` before its `start`), the installer prints a warning, leaves the file completely untouched, and finishes the rest of the install. Fix the markers and re-run.
353
402
 
354
- ### verbosity-remind *(global + project)* — v1.11.0
403
+ ### The .gitignore block
355
404
 
356
- Fires on every `UserPromptSubmit`. Re-injects the active MIN/INFO/VERBOSE verbosity constraint before every Claude response, preventing level drift as the context window fills (BUG-014).
405
+ When installed with `--project`, the installer keeps its rules in one labelled block in your project's `.gitignore`:
357
406
 
358
- The global hook defers to a project-level hook if one exists (upward traversal from `$PWD`). The active level is read from the nearest `.claude/memory/verbosity.md` ancestor file. Set `CC_VERBOSITY_SKIP=1` to disable in CI/CD environments.
407
+ ```
408
+ # Code Conductor (added by the installer; safe to keep)
409
+ .claude/memory/turn-count.txt
410
+ *.installer-backup.*
411
+ *.installer-tmp.*
412
+ .claude/memory/band-envelope.json
413
+ .claude/memory/orchestrator-run.json
414
+ .conductor/
415
+ ```
416
+
417
+ The block ends at the first blank line. Your own lines are never edited. A line that is exactly one of these rules (earlier versions appended them one at a time) is moved into the block, so each rule appears once; a line you changed, such as `/.claude/memory/turn-count.txt`, is not an exact match and stays where it is. If your `.gitignore` has any `!` line, nothing is moved, because moving a rule past a `!` can change what is ignored: the block then holds only the rules you lack, and the installer says so. A change to `.gitignore` is backed up and reported exactly as for `CLAUDE.md`.
359
418
 
360
- > **Note — `$HOME` unset environments:** When `$HOME` is unset (e.g., some CI containers, `sudo -H` shells, minimal Docker images), `verbosity-remind.sh` exits immediately with code 0 and emits no output. Claude falls back to MIN verbosity by default. Set `HOME=/root` (or the appropriate home directory) in the container environment to restore full hook behavior. The hook never raises an error when `$HOME` is absent — it degrades gracefully to ensure the user's session is never blocked.
419
+ The backup and temp rules keep the installer's own backups and crash-stranded temp files out of `git status`; the rest keep orchestrator run state and the local cache out of commits. The rules ship inside the package as `project-template/gitignore` (no leading dot) because npm strips any file literally named `.gitignore` from every published tarball; the installer restores the dot when it writes to your project.
361
420
 
362
421
  ---
363
422
 
364
- ## Local State Cache & Session Persistence — v1.22.0
423
+ ## What this is not
365
424
 
366
- `/cc-implement`'s Step 6 hook records each task's final state to a local SQLite cache at `.conductor/cache.db`, written by the bundled `scripts/conductor-db.mjs` engine — a zero-dependency ES module wrapping Node's built-in `node:sqlite`.
425
+ - **Not a sandbox and not a security boundary.** The guards are advisory tooling against context exhaustion and sloppy habits, built for cooperative agents. They do not contain a hostile process and were never built to.
426
+ - **Not a model.** It is configuration, hooks and scripts around Claude Code.
427
+ - **Not finished.** See the limits below.
367
428
 
368
- - **Schema (v2, ARCH-008):** `task_state(plan_file, task_id, state, updated_at)` keyed by `(plan_file, task_id)` — `plan_file` normalized to a repo-relative POSIX path so the same plan de-duplicates across working directories — plus `sessions`, `snapshots` (one verbatim SNAP blob per git commit, newest wins), and `raw_history`. Upserts on every write.
369
- - **Runtime-gated:** `node:sqlite` needs Node `>= 22.5`, so every caller probes the Node version and self-disables below it. `engines.node` stays `>=20`; the cache is an optimization, never a requirement.
370
- - **Non-authoritative + fail-safe:** the plan markdown and the `.claude/memory/session-snapshot.json` handoff remain the sources of truth. Every failure path — absent `node:sqlite`, a corrupt or non-regular file at the db path, `SQLITE_BUSY`, a newer schema, CLI misuse — degrades to a single `CONDUCTOR_DB:` stderr line and exit 0. A corrupt db is renamed aside (never `rm -r`) and recreated.
371
- - **Gitignored:** `.conductor/` is local-only and never committed.
429
+ ## Known limits
430
+
431
+ - **The orchestrator (`1.36.0`) assumes cooperative agents.**
432
+ - Guard 6 does not cover `Bash` writes, `claude -p` children included.
433
+ - Inside a live run, a non-role agent the main session dispatched may write the orchestrator's write surface, the band envelope included.
434
+ - R7 protects live runs only.
435
+ - An agent writing after its hand-back is bounded only by the envelope in force, so a same-role next task inherits it.
436
+ - Under auto permission mode no human stands behind a Bash write or a hook `ask`.
437
+ - A Guard 6 warning reaches you, never the model's tool result, and not in every case. Measured on `claude` 2.1.287:
438
+
439
+ | Channel | Permission mode | A prompting decision rides along | You see the warning |
440
+ |---|---|---|---|
441
+ | stderr | `auto` | no | no |
442
+ | `systemMessage` (Guard 6's channel) | `auto` | no; a hook `ask` does not prompt under `auto` | yes, behind `PreToolUse:Write says: ` |
443
+ | `systemMessage` | `default` | no | yes, in full |
444
+ | `systemMessage` | `default` | yes, for example Guard 2's overwrite prompt | no: the warning is lost |
445
+ - Agent definitions provided by plugins are not searched.
446
+ - A halted run cannot be resumed, only ended and restarted.
372
447
 
373
- ### Phase-entry resume — v1.22.0
448
+ The five role agent definitions it dispatches ship from `1.37.0`; their limits are the next item.
449
+ - **The role agents (`1.37.0`) are bounded by their tool masks, and Guard 7 bounds one thing beneath them: the shell.**
450
+ - `qa`'s test command is enforcement: Guard 5 keeps qa from writing, so qa only ever runs files it did not write. `code`'s identical allowance is process discipline, not a security boundary, because code writes the tests that command runs.
451
+ - The profiles are live in this repository, because the mirror convention puts them in `.claude/agents/`. The standing rule forbids starting an orchestrator run here; it does not forbid the files being present. A role dispatched by hand through `/agents` or `Agent` creates no band envelope, so Guard 5 allows every write its mask holds, which is `[ARCH-010]`'s no-envelope rule. Guard 7 still denies it the shell. This is named, not fixed.
452
+ - Installing or updating copies `.claude/agents/{spec,plan,code,audit,qa,define-review}.md` over the host project's files of the same names, as it does every shipped `.claude/` asset.
453
+ - A gate certifies protocol position and the claim its role states, never the truth of the work beyond that claim.
454
+ - **The review loop (`1.39.0`) is process discipline.** The spec or plan envelope stays installed after its hand-back, so the role can revise. Outside a round, its writes are bounded by its tool mask, Guard 5's scope, the re-hash before `approve`, and your review. Gating Guard 5 on an open round is a follow-up candidate.
455
+ - **`[BUG-055]`, open:** detect-stack exits 0 with `{}` when a truthy non-string `package.json` `description`, or a truthy non-string script with no detector matched, crashes it; when a detector matches, a non-string script or `name` passes through raw. Until it is fixed, keep `name`, `description` and the `build`/`test`/`lint`/`format` scripts as strings, or `/cc-stack` reports no stack.
456
+ - **`[BUG-056]`, open:** the context-guard turn counter persists across sessions — only `/compact`'s PostCompact hook resets `.claude/memory/turn-count.txt` — so a fresh session inherits the previous session's count and can show the CONTEXT WARNING or CRITICAL banner on its first prompt. Until it is fixed, delete that file when starting a fresh session, or disregard a banner that appears before the session has done any work.
457
+ - **`[BUG-057]`, open:** `.claude/memory/project.md` is append-only and the phase commands instruct a full read of it, which collides with Guard 1's 150-line read limit once the file grows; on a long-lived project the read cost rises with project age. Until it is fixed, prune or archive old checkpoint sections by hand when the file gets large.
458
+ - **`[BUG-058]`, open:** the test suite does not pass on a Windows checkout (CRLF checkout of `.mjs` files, `--import` given a bare path, symlink and `chmod` fixtures, `spawnSync('npm')` without a shell), and CI has no Windows leg to show it. Until it is fixed, develop against the suite on Linux/macOS or WSL; the shipped product itself is unaffected.
459
+ - **`[BUG-059]`, open:** the test helper that fakes the `gh` CLI is POSIX-only, so on a Windows machine where the suites load, tests can reach a real, logged-in `gh` and perform live GitHub writes. Until it is fixed, do not run `npm test` on Windows while authenticated to `gh`, or log out (`gh auth logout`) first.
460
+ - **`[BUG-061]`, open:** the PreToolUse hook command is a cwd-relative `node .claude/hooks/pre-tool-use.mjs`, so on Windows nearly every tool call can report a non-blocking `node:internal/modules/cjs/loader` error, and the guards are skipped for that call. Until it is fixed, keep the session's working directory at the project root.
461
+ - **The `P7` false positive** described under [Guard 3, and what it learned](#guard-3-and-what-it-learned), still live.
462
+ - **A re-run against an untouched `project.md` prints a recovery hint it cannot prove is needed.** If you install, never write anything into `.claude/memory/project.md`, and install again, you get a line suggesting the file may have been overwritten by a pre-`1.30.0` re-run. It was not; it equals the stub because it was seeded and never edited. The check compares content and **cannot distinguish "seeded and untouched" from "clobbered"**, which is why the wording is hedged to "may have been" rather than "was". This residual is named and accepted in [`BUG-039`'s spec at `:129`](docs/superpowers/specs/2026-09-27-bug039-installer-host-owned-state-design.md), where the alternative (restoring from the host's own git history) was rejected as writing host files out of the host's history with new failure modes. A **fresh** install is silent, which the Quickstart shows.
463
+ - **Three open dossiers**, which are the evidence-collection pipeline working rather than a backlog: a session denial tally, one for interleaved-artifact reports, and an intermittent commit-hook hang in the `snap-build` suite. A dossier holds specimens until a mechanism is characterized by probe; an id is minted only when the written condition is met. `[BUG-047]` is what that pipeline produces when it completes: an out-of-scope note, then a dossier, then four specimens across four sessions, then a mint, then a release.
374
464
 
375
- `/cc-spec`, `/cc-plan`, and `/cc-implement` open each phase by running `scripts/resume-read.mjs`, which resolves the current git commit hash and restores any context stored for it — surviving branch switches and rollbacks. A valid DB snapshot for the commit wins; otherwise it falls back to the `.claude/memory/session-snapshot.json` handoff written by `/cc-compact`. A hit prints a `RESUME_HIT` block the command adopts as its starting context; a clean miss proceeds fresh; a readable-but-corrupt handoff halts the phase (exit `4`) with a `SNAP_INVALID` notice so you can inspect it. This completes the **ARCH-008** milestone: relational schema (v1.20.0) → checkpoint/compact writers (v1.21.0) → phase-entry readers (v1.22.0).
465
+ **The living artifact is [`AGENT-READABLE BACKLOG.md`](AGENT-READABLE%20BACKLOG.md).** It is not a tidy issue list. It carries amendments above the text they amend, premises that measurement later corrected, and wrong guesses recorded beside the probe that overturned them. If you are evaluating this for a team, that file is the best due-diligence read in the repository.
376
466
 
377
467
  ---
378
468
 
379
- ## Memory Architecture
469
+ ## Instruments: releases that verify their own record
380
470
 
381
- ```
382
- ~/.claude/
383
- memory/
384
- personal.md ← local only, never committed
385
- dev preferences, shortcuts
386
- verbosity.md ← agent-managed, set by installer
387
- active verbosity level (MIN/INFO/VERBOSE)
388
-
389
- project-root/
390
- .claude/
391
- memory/
392
- project.md ← in git, shared with team
393
- decisions, conventions, debt, workarounds
394
- ```
471
+ Four checks live in `tools/` as tracked repository infrastructure. Three of them run on every pull request, so a divergence blocks the merge rather than waiting for someone to remember, and the fourth is a query run by hand:
395
472
 
396
- `/cc-checkpoint` writes to both. Run it before `/compact`, after completing a feature, and after any key architectural decision.
473
+ - **`version-gate.mjs`** takes `VERSION` as the authority and checks four other locations against it, five in all. Agreement reports as agreement, which sounds trivial until you learn that its predecessor reported `FAIL` on five locations that agreed, because it compared against a literal frozen two releases earlier. It runs at the merge gate through `tests/tools/repo-invariants.test.js`, and by hand at closeout.
474
+ - **`record-parity.mjs`** asserts that every item the `CHANGELOG` claims has a closed backlog entry naming the version it shipped in. It exists because `[BUG-044]` shipped, was closed out in memory, and left its backlog entry reading `[ ]` for an entire release with no instrument comparing the two documents. It runs at the merge gate through `tests/tools/repo-invariants.test.js`, and by hand at closeout.
475
+ - **`skip-baseline.mjs`** asserts each CI leg's exact skipped-test set against `tools/skip-baseline.json`, where every set is copied from that leg's own run rather than typed. It runs directly in `.github/workflows/test.yml` on the Node 20 and Node 24 legs, after the suite. It exists because CI was green with 96 tests skipped on Node 20 against 12 locally, and nothing asserted either number.
476
+ - **`id-ceiling.mjs`** reports the highest filed id over the working tree **union** `origin/main`, counting only filed headings. Its predecessor counted id-shaped tokens anywhere, so it once read a plan file's prediction of its own output back as evidence. It is local-only by ruling: a person or agent runs it, over both legs, before minting an id. Its remote leg needs history the CI checkout does not fetch, so CI asserts only its duplicate-free half.
477
+
478
+ **The example worth checking.** `[BUG-046]`'s own release ran those instruments against itself, then proved the green rather than trusting it: with the item's backlog heading deliberately flipped to `[ ]`, `record-parity` reported `FAIL [A] 1.32.2 claims BUG-046 but its heading reads [ ]` once per claim bullet and exited 1; flipped back, `RECORD_PARITY_OK`. The first release whose record cannot silently diverge is the release that made divergence detectable.
397
479
 
398
- `/cc-stack` records the detected stack in your project `CLAUDE.md` (the `- Stack:` line and the `## Active Stack Profiles` block); on later sessions it asks whether anything changed before re-detecting.
480
+ `tools/README.md` carries a **registry of five retired instruments**, each with the failure mode that retired it, so the sixth one gets written by someone who has met the list.
399
481
 
400
482
  ---
401
483
 
402
- ## Language Support
484
+ ## Language support
403
485
 
404
486
  | Priority | Source | How to set |
405
- |----------|--------|------------|
406
- | 1 (highest) | Session | `/lang [code]` |
487
+ |---|---|---|
488
+ | 1 (highest) | Session | `/cc-lang [code]` |
407
489
  | 2 | Project | `language:` in project `CLAUDE.md` |
408
490
  | 3 | Personal | `response_language:` in `personal.md` |
409
491
  | 4 (default) | Global | English |
410
492
 
411
493
  **Supported codes:** `en` `es` `pt` `fr` `de` `it` `zh` `ja` `ko`
412
494
 
413
- Code identifiers, file names, and commit messages are always English.
495
+ Code identifiers, file names and commit messages are always English.
414
496
 
415
497
  ---
416
498
 
417
- ## File Structure
499
+ ## File structure
418
500
 
419
501
  ```
420
502
  code-conductor/
421
- ├── README.md
422
- ├── VERSION
423
- ├── .gitignore
424
- ├── bin/code-conductor.mjs npm CLI entry (npx code-conductor)
425
- ├── lib/installer/ CLI modules (env, deploy, settings, config)
426
- ├── global/
427
- │ ├── CLAUDE.md Global agent behavior (all projects)
428
- │ ├── settings.json
429
- │ ├── commands/
430
- │ │ ├── cc-checkpoint.md /cc-checkpoint
431
- │ │ ├── cc-stack.md /cc-stack
432
- │ │ └── cc-lang.md /cc-lang
433
- │ ├── hooks/
434
- │ │ └── verbosity-remind.sh Verbosity reminder on UserPromptSubmit
435
- │ └── memory/
436
- │ └── personal.md Template (never committed)
437
- ├── project-template/
438
- │ ├── CLAUDE.md
439
- │ ├── gitignore Merged into the host project's .gitignore
440
- │ └── .claude/
441
- │ ├── settings.json Hooks wiring (pre-tool-use, post-compact)
442
- │ ├── review-loop.settings.json Auto mode exception for the review loop (FEAT-041)
443
- │ ├── agents/ Band roles: spec, plan, code, audit, qa (FEAT-012); define-review (FEAT-041)
444
- │ ├── commands/
445
- │ │ ├── cc-init.md /cc-init — session initialization
446
- │ │ ├── cc-resume.md /cc-resume — session context restore
447
- │ │ ├── cc-spec.md /cc-spec
448
- │ │ ├── cc-plan.md /cc-plan
449
- │ │ ├── cc-implement.md /cc-implement
450
- │ │ ├── cc-orchestrate.md /cc-orchestrate
451
- │ │ ├── cc-review.md /cc-review
452
- │ │ ├── cc-compact.md /cc-compact — phase boundary compaction
453
- │ │ ├── cc-debug.md /cc-debug
454
- │ │ ├── cc-refactor.md /cc-refactor
455
- │ │ ├── cc-test.md /cc-test
456
- │ │ └── cc-docs.md /cc-docs
457
- │ ├── hooks/
458
- │ │ ├── pre-tool-use.mjs Node front door: large-file, duplicate-write and node_modules guards
459
- │ │ ├── context-guard.sh Turn-counter warning (.sh + .ps1)
460
- │ │ └── post-compact.sh Checkpoint reminder + cache sweep after `/compact` (.sh + .ps1)
461
- │ └── memory/
462
- │ └── project.md Shared team memory (in git)
463
- ├── scripts/
464
- │ ├── conductor-db.mjs Zero-dep node:sqlite engine (.conductor/cache.db)
465
- │ ├── resume-read.mjs Phase-entry resume reader (DB snapshot → handoff fallback)
466
- │ ├── snap-contract.mjs SNAP limits, caps, field sets, version ceiling
467
- │ ├── snap-build.mjs SNAP v1/v2 handoff serializer
468
- │ ├── snap-validate.mjs SNAP schema validator
469
- │ ├── session-id.mjs Stable session-id resolver
470
- │ ├── orchestrate.mjs Band router: run file, envelopes, hand-backs (FEAT-011)
471
- │ ├── ticket.mjs Ticket intake and writeback through gh (FEAT-031)
472
- │ └── detect-stack.mjs Stack auto-detection scanner
473
- └── skills/
474
- ├── code-simplifier/SKILL.md Always active — complexity and simplicity rules
475
- ├── critical-review/SKILL.md Always active — 4-phase adversarial review protocol
476
- ├── verbosity/SKILL.md Always active — MIN/INFO/VERBOSE response rules
477
- ├── memory-first/SKILL.md Always active — memory → grep → read chain
478
- └── agent-delegation/SKILL.md Always active — sub-agent spawn rules
479
- # Claude Code registers personal skills only at ~/.claude/skills/<name>/SKILL.md
480
- ```
481
-
482
- ---
483
-
484
- ## .gitignore Note
485
-
486
- When installed with `--project`, the installer keeps its rules in one labelled block in
487
- your project's `.gitignore`:
488
-
489
- ```
490
- # Code Conductor (added by the installer; safe to keep)
491
- .claude/memory/turn-count.txt
492
- *.installer-backup.*
493
- *.installer-tmp.*
503
+ +-- README.md
504
+ +-- VERSION
505
+ +-- bin/code-conductor.mjs npm CLI entry (npx code-conductor)
506
+ +-- lib/installer/ CLI modules (env, deploy, settings, merges, heal)
507
+ +-- global/
508
+ | +-- CLAUDE.md Global agent behavior (all projects)
509
+ | +-- settings.json
510
+ | +-- commands/ /cc-checkpoint, /cc-stack, /cc-lang, /cc-compact
511
+ | +-- hooks/
512
+ | | +-- verbosity-remind.sh Verbosity reminder on UserPromptSubmit
513
+ | +-- memory/
514
+ | +-- personal.md Template (never committed)
515
+ | +-- verbosity.md Active verbosity level
516
+ +-- project-template/
517
+ | +-- CLAUDE.md
518
+ | +-- gitignore Merged into the host project's .gitignore
519
+ | +-- .claude/
520
+ | +-- settings.json Hooks wiring
521
+ | +-- review-loop.settings.json Auto mode exception for the review loop (FEAT-041)
522
+ | +-- agents/ Band roles: spec, plan, code, audit, qa (FEAT-012);
523
+ | | define-review (FEAT-041)
524
+ | +-- commands/ /cc-init, /cc-resume, /cc-spec, /cc-plan, /cc-implement,
525
+ | | /cc-orchestrate, /cc-review, /cc-debug, /cc-refactor,
526
+ | | /cc-test, /cc-docs
527
+ | +-- hooks/
528
+ | | +-- pre-tool-use.mjs Node front door: Guards 1 to 7
529
+ | | +-- context-guard.sh Turn-counter warning (.sh + .ps1)
530
+ | | +-- post-compact.sh Checkpoint reminder + cache sweep after /compact (.sh + .ps1)
531
+ | | +-- verbosity-remind.sh Project-level verbosity reminder
532
+ | +-- memory/
533
+ | +-- project.md Shared team memory (in git)
534
+ | +-- bash-scan-allowlist.txt Guard 3 operator exceptions (commented template)
535
+ | +-- context-threshold.txt Turn-counter threshold
536
+ +-- scripts/
537
+ | +-- conductor-db.mjs Zero-dep node:sqlite engine (.conductor/cache.db)
538
+ | +-- resume-read.mjs Phase-entry resume reader (DB snapshot, then handoff)
539
+ | +-- snap-contract.mjs SNAP limits, caps, field sets, version ceiling
540
+ | +-- snap-build.mjs SNAP handoff serializer
541
+ | +-- snap-validate.mjs SNAP schema validator
542
+ | +-- session-id.mjs Stable session-id resolver
543
+ | +-- orchestrate.mjs Band router: run file, envelopes, hand-backs (FEAT-011)
544
+ | +-- ticket.mjs Ticket intake and writeback through gh (FEAT-031)
545
+ | +-- detect-stack.mjs Stack auto-detection scanner
546
+ | +-- claude-md-fields.mjs CLAUDE.md field reader/writer
547
+ | +-- init-wizard.mjs /cc-init helper
548
+ +-- skills/
549
+ | +-- code-simplifier/SKILL.md Always active: complexity and simplicity rules
550
+ | +-- critical-review/SKILL.md Always active: 4-phase adversarial review protocol
551
+ | +-- verbosity/SKILL.md Always active: MIN/INFO/VERBOSE response rules
552
+ | +-- memory-first/SKILL.md Always active: memory, grep, read chain
553
+ | +-- agent-delegation/SKILL.md Always active: sub-agent spawn rules
554
+ +-- tools/ Release instruments (repository only, not shipped)
555
+ +-- README.md Instrument notes and the retired-instrument registry
494
556
  ```
495
557
 
496
- The block ends at the first blank line. Your own lines are never edited. A line that is
497
- exactly one of these three rules (earlier versions appended them one at a time) is moved
498
- into the block, so each rule appears once; a line you changed, such as
499
- `/.claude/memory/turn-count.txt`, is not an exact match and stays where it is. If your
500
- `.gitignore` has any `!` line, nothing is moved, because moving a rule past a `!` can
501
- change what is ignored: the block then holds only the rules you lack, and the installer
502
- says so. A change to `.gitignore` is backed up and reported exactly as for `CLAUDE.md`.
503
-
504
- The last two keep the installer's own backups and crash-stranded temp files out of
505
- `git status`. The rules ship inside the package as `project-template/gitignore`
506
- (no leading dot) because npm strips any file literally named `.gitignore` from every
507
- published tarball; the installer restores the dot when it writes to your project.
558
+ Claude Code registers personal skills only at `~/.claude/skills/<name>/SKILL.md`, which is where the installer puts them.
508
559
 
509
560
  ---
510
561
 
511
- ## How the installer treats your CLAUDE.md
512
-
513
- `CLAUDE.md` and `.gitignore` are **merged**, never overwritten. Everything else the
514
- installer ships (`settings.json`, hooks, commands, `scripts/`) is replaced on every run.
515
-
516
- - **Code Conductor owns one block and nothing else.** Its content lives between
517
- `<!-- cc:managed:start -->` and `<!-- cc:managed:end -->`, and those two markers alone
518
- decide ownership; a heading's name never does. Every upgrade replaces the block's
519
- contents wholesale, so released improvements reach existing installs. Edits inside the
520
- block are lost, and recoverable from the backup.
521
- - **Everything outside the block is yours, byte for byte.** Nothing outside it is
522
- removed, rewritten, reordered or added.
523
- - **A file without the markers gets the block appended at the end**, after one blank
524
- line and in your file's line endings, and nothing else changes. If your file already
525
- has sections named like the block's (`## Agent Identity`, `## Hard Constraints`, …),
526
- you will see both: yours above, Code Conductor's inside the block. That is deliberate.
527
- The installer never decides which of your sections are really its own; reconciling
528
- them is planned for `/cc-stack` as `[FEAT-040]`.
529
- - **Before any change, the installer copies your file to
530
- `CLAUDE.md.installer-backup.<UTC timestamp>`**, keeps the five most recent, and prints
531
- where it put it:
532
-
533
- ```
534
- code-conductor: backed up CLAUDE.md to CLAUDE.md.installer-backup.20260930T120000Z before merging (git-ignored by design)
535
- ```
562
+ ## Uninstall notes
536
563
 
537
- Backups are git-ignored so nobody commits one by accident and they stay out of every
538
- teammate's `git status`; the printed line is how you find yours. A fresh install, and a
539
- re-run that changes nothing, print nothing.
564
+ Hook removal (`rm ~/.claude/hooks/verbosity-remind.sh`) and `settings.json` cleanup work identically in every environment; no git is required.
540
565
 
541
- The same rules apply to `~/.claude/CLAUDE.md`, whose backup line names the `~/.claude/`
542
- path. If your file ends inside a code fence that is never closed, the installer leaves it
543
- untouched with a warning, because a block appended there would be hidden inside the fence.
544
-
545
- If the markers in your file are damaged — a `start` with no `end`, two blocks, an `end`
546
- before its `start` — the installer prints a warning, leaves the file completely untouched,
547
- and finishes the rest of the install. Fix the markers and re-run.
548
-
549
- ---
550
-
551
- ## Uninstall Notes
552
-
553
- > **`git revert` in non-repository environments (CI/CD, Docker, bare installs):**
554
- > Uninstall steps that use `git checkout <tag>` or `git revert <sha>` require a git working tree. In CI/CD pipelines, Docker containers, or directories that are not git repositories, these commands will fail with `fatal: not a git repository`. This is expected and non-fatal.
555
- >
556
- > **In non-repo environments:** manually delete or restore `skills/verbosity/SKILL.md` and remove the `verbosity-remind` entry from `~/.claude/settings.json`. Hook removal (`rm ~/.claude/hooks/verbosity-remind.sh`) and `settings.json` cleanup work identically in all environments — no git is required.
566
+ Uninstall steps that use `git checkout <tag>` or `git revert <sha>` need a git working tree. In CI/CD pipelines, Docker containers, or directories that are not git repositories, they fail with `fatal: not a git repository`. That is expected and non-fatal: in those environments, manually delete or restore `skills/verbosity/SKILL.md` and remove the `verbosity-remind` entry from `~/.claude/settings.json`.
557
567
 
558
568
  ---
559
569
 
560
570
  ## Contributing
561
571
 
562
572
  GitHub Issues are the inbox: an issue or PR is a candidate until the owner mints it an id. Nothing merges without a minted id and owner review, one item per PR. Versions, release branches, tags and GitHub Releases are owner-only. Read [CONTRIBUTING.md](CONTRIBUTING.md) before opening a PR; its hard constraints bind AI agents working on a contributor's behalf as well.
573
+
574
+ ## License
575
+
576
+ See [LICENSE](https://github.com/yeisonrestrepo/code-conductor/blob/main/LICENSE).