@yeison.restrepo.r/code-conductor 1.39.1 → 1.39.3
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
|
[](https://www.npmjs.com/package/@yeison.restrepo.r/code-conductor)
|
|
4
|
+
[](https://www.npmjs.com/package/@yeison.restrepo.r/code-conductor)
|
|
4
5
|
[](https://github.com/yeisonrestrepo/code-conductor/blob/main/LICENSE)
|
|
5
6
|
[](https://github.com/yeisonrestrepo/code-conductor/issues)
|
|
6
7
|
|
|
7
|
-
**
|
|
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.
|
|
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
|
|
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,518 +66,510 @@ but must not add it to clear its own denial.
|
|
|
38
66
|
```
|
|
39
67
|
|
|
40
68
|
```bash
|
|
41
|
-
# scene 2: the
|
|
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
|
-
|
|
77
|
+
### Dependencies
|
|
50
78
|
|
|
51
|
-
|
|
79
|
+
code-conductor assumes these are already in place; the installer does not set them up for you:
|
|
52
80
|
|
|
53
|
-
|
|
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
|
-
|
|
89
|
+
---
|
|
56
90
|
|
|
57
|
-
|
|
91
|
+
## The ideal workflow, day to day
|
|
58
92
|
|
|
59
|
-
|
|
93
|
+
A typical session looks like this:
|
|
60
94
|
|
|
61
|
-
|
|
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
|
-
|
|
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
|
-
|
|
109
|
+
Two things make this cheaper than it sounds:
|
|
73
110
|
|
|
74
|
-
**
|
|
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
|
-
##
|
|
116
|
+
## Walkthrough: hands-off delivery with `/cc-orchestrate`
|
|
79
117
|
|
|
80
|
-
|
|
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
|
-
|
|
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
|
-
|
|
122
|
+
```bash
|
|
123
|
+
claude --permission-mode auto --settings .claude/review-loop.settings.json
|
|
124
|
+
```
|
|
88
125
|
|
|
89
|
-
|
|
126
|
+
Then, inside the session:
|
|
90
127
|
|
|
91
|
-
|
|
128
|
+
```
|
|
129
|
+
/cc-orchestrate FEAT-123
|
|
130
|
+
```
|
|
92
131
|
|
|
93
|
-
|
|
132
|
+
What happens:
|
|
94
133
|
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
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
|
-
|
|
140
|
+
Useful variations:
|
|
100
141
|
|
|
101
|
-
-
|
|
102
|
-
|
|
103
|
-
- Inside a live run, a non-role agent the main session dispatched may write the orchestrator's write surface, the band envelope included.
|
|
104
|
-
- R7 protects live runs only.
|
|
105
|
-
- An agent writing after its hand-back is bounded only by the envelope in force, so a same-role next task inherits it.
|
|
106
|
-
- Under auto permission mode no human stands behind a Bash write or a hook `ask`.
|
|
107
|
-
- 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`.
|
|
108
144
|
|
|
109
|
-
|
|
110
|
-
|---|---|---|---|
|
|
111
|
-
| stderr | `auto` | no | no |
|
|
112
|
-
| `systemMessage` (Guard 6's channel) | `auto` | no; a hook `ask` does not prompt under `auto` | yes, behind `PreToolUse:Write says: ` |
|
|
113
|
-
| `systemMessage` | `default` | no | yes, in full |
|
|
114
|
-
| `systemMessage` | `default` | yes, for example Guard 2's overwrite prompt | no: the warning is lost |
|
|
115
|
-
- Agent definitions provided by plugins are not searched.
|
|
116
|
-
- 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`.
|
|
117
146
|
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
- A gate certifies protocol position and the claim its role states, never the truth of the work beyond that claim.
|
|
124
|
-
- **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.
|
|
125
|
-
- **The `P7` false positive above**, still live.
|
|
126
|
-
- **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.
|
|
127
|
-
- **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:
|
|
128
152
|
|
|
129
|
-
|
|
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.
|
|
130
160
|
|
|
131
161
|
---
|
|
132
162
|
|
|
133
|
-
##
|
|
163
|
+
## Walkthrough: diagnosis before surgery with `/cc-debug`
|
|
134
164
|
|
|
135
|
-
|
|
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:
|
|
136
166
|
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
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.
|
|
144
178
|
|
|
145
179
|
---
|
|
146
180
|
|
|
147
|
-
##
|
|
181
|
+
## Where the token savings come from
|
|
148
182
|
|
|
149
|
-
|
|
183
|
+
Claude Code is priced in tokens, and unstructured sessions waste them in predictable ways. code-conductor attacks each one:
|
|
150
184
|
|
|
151
|
-
|
|
|
185
|
+
| Mechanism | What it does |
|
|
152
186
|
|---|---|
|
|
153
|
-
|
|
|
154
|
-
|
|
|
155
|
-
|
|
|
156
|
-
|
|
|
157
|
-
|
|
|
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. |
|
|
158
195
|
|
|
159
196
|
---
|
|
160
197
|
|
|
161
|
-
##
|
|
162
|
-
|
|
163
|
-
**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.
|
|
164
|
-
|
|
165
|
-
```bash
|
|
166
|
-
npx @yeison.restrepo.r/code-conductor@latest # one-shot global setup
|
|
167
|
-
# or
|
|
168
|
-
npm install -g @yeison.restrepo.r/code-conductor && code-conductor
|
|
169
|
-
```
|
|
198
|
+
## Guard 3, and what it learned
|
|
170
199
|
|
|
171
|
-
|
|
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)).
|
|
172
201
|
|
|
173
|
-
|
|
202
|
+
The interesting part is what it got wrong, because that is what the record documents.
|
|
174
203
|
|
|
175
|
-
|
|
176
|
-
code-conductor --project # global setup + scaffold ./.claude in the current repo
|
|
177
|
-
```
|
|
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.
|
|
178
205
|
|
|
179
|
-
|
|
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.**
|
|
180
207
|
|
|
181
|
-
|
|
208
|
+
### The honest numbers
|
|
182
209
|
|
|
183
|
-
|
|
184
|
-
|------|-------------|
|
|
185
|
-
| `--project` / `-Project` | Also install the project template into the current directory |
|
|
186
|
-
| `--no-deps` / `-NoDeps` | Skip dependency installation (Node tooling, Playwright MCP, plugins); copy agent files only |
|
|
187
|
-
| `--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.
|
|
188
211
|
|
|
189
|
-
|
|
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 |
|
|
190
220
|
|
|
191
|
-
|
|
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.
|
|
192
222
|
|
|
193
|
-
|
|
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.
|
|
194
224
|
|
|
195
225
|
---
|
|
196
226
|
|
|
197
|
-
## How
|
|
227
|
+
## How it works
|
|
198
228
|
|
|
199
229
|
code-conductor operates at three layers:
|
|
200
230
|
|
|
201
|
-
**Global core** (`~/.claude/`)
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
**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.
|
|
206
234
|
|
|
207
235
|
---
|
|
208
236
|
|
|
209
|
-
##
|
|
237
|
+
## Command reference
|
|
210
238
|
|
|
211
|
-
All commands are tagged `(Conductor)` in the Claude Code command palette so they
|
|
239
|
+
All commands are tagged `(Conductor)` in the Claude Code command palette, so they are easy to spot alongside commands from other sources.
|
|
212
240
|
|
|
213
241
|
### Global (all projects)
|
|
214
242
|
|
|
215
|
-
| Command |
|
|
216
|
-
|
|
217
|
-
| `/cc-checkpoint` | Read the current session, extract decisions, conventions
|
|
218
|
-
| `/cc-stack` | Run the dynamic detector
|
|
219
|
-
| `/cc-lang [code]` | Switch response language for this session. Code identifiers, filenames
|
|
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. |
|
|
220
249
|
|
|
221
250
|
### Project (requires `--project` install)
|
|
222
251
|
|
|
223
|
-
| Command |
|
|
224
|
-
|
|
225
|
-
| `/cc-
|
|
226
|
-
| `/cc-
|
|
227
|
-
| `/cc-spec [name]` | Search the codebase first, ask only for missing context,
|
|
228
|
-
| `/cc-plan` |
|
|
229
|
-
| `/cc-
|
|
230
|
-
| `/cc-
|
|
231
|
-
| `/cc-
|
|
232
|
-
|
|
233
|
-
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)).
|
|
234
|
-
| `/cc-review [file\|dir]` | Review code in three layers - Critical / Important / Suggestion - then deliver a verdict and offer to auto-fix. |
|
|
235
|
-
| `/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). |
|
|
236
262
|
| `/cc-refactor [file\|module]` | Diagnose complexity, plan ordered changes, apply one step at a time, and verify tests pass after each step. |
|
|
237
|
-
| `/cc-test [scope]` |
|
|
238
|
-
| `/cc-docs [scope]` | Audit
|
|
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. |
|
|
239
265
|
|
|
240
266
|
---
|
|
241
267
|
|
|
242
|
-
|
|
268
|
+
## Skills
|
|
243
269
|
|
|
244
|
-
|
|
270
|
+
Skills extend agent behavior for cross-cutting concerns that apply regardless of stack.
|
|
245
271
|
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
| Default (ask) permission mode | 0 wakes; one approval per revision write, plus the orchestrator's `review` calls and report writes |
|
|
250
|
-
| 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`.
|
|
251
275
|
|
|
252
|
-
|
|
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. |
|
|
253
281
|
|
|
254
|
-
|
|
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.
|
|
255
285
|
|
|
256
|
-
|
|
286
|
+
---
|
|
257
287
|
|
|
258
|
-
|
|
288
|
+
## Guardrails (hooks)
|
|
259
289
|
|
|
260
|
-
|
|
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.
|
|
261
291
|
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
-
|
|
265
|
-
|
|
266
|
-
-
|
|
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. |
|
|
267
301
|
|
|
268
|
-
|
|
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.
|
|
269
303
|
|
|
270
|
-
|
|
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.
|
|
271
305
|
|
|
272
|
-
|
|
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.
|
|
273
307
|
|
|
274
|
-
|
|
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.
|
|
275
309
|
|
|
276
|
-
|
|
277
|
-
2. **Adversarial Review** — RESILIENCE (silent failures), EFFICIENCY (code smells), FRICTION (happy-path friction)
|
|
278
|
-
3. **Self-Correction** — each weakness refactored and re-verified in isolation
|
|
279
|
-
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).
|
|
280
311
|
|
|
281
|
-
|
|
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.
|
|
282
313
|
|
|
283
|
-
|
|
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.
|
|
284
315
|
|
|
285
|
-
|
|
286
|
-
|-------|----------|
|
|
287
|
-
| `MIN` | One declarative sentence. `[CHANGES]` tag with file list only. |
|
|
288
|
-
| `INFO` | Bullet list of what changed and why. Max 5 bullets. `[CHANGES]` + `[REASON]`. |
|
|
289
|
-
| `VERBOSE` | Full explanation, prose allowed. All response tags. |
|
|
316
|
+
### The other hooks
|
|
290
317
|
|
|
291
|
-
|
|
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.
|
|
292
321
|
|
|
293
|
-
|
|
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.
|
|
294
323
|
|
|
295
|
-
|
|
296
|
-
2. **Grep / Glob** — pattern searches
|
|
297
|
-
3. **Targeted read** — last resort, always with `offset` + `limit`, max 150 lines
|
|
324
|
+
---
|
|
298
325
|
|
|
299
|
-
|
|
326
|
+
## Memory architecture
|
|
300
327
|
|
|
301
|
-
|
|
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
|
|
302
332
|
|
|
303
|
-
|
|
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.
|
|
304
348
|
|
|
305
|
-
|
|
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).
|
|
306
350
|
|
|
307
|
-
|
|
351
|
+
---
|
|
308
352
|
|
|
309
|
-
|
|
353
|
+
## Install
|
|
310
354
|
|
|
311
|
-
|
|
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.
|
|
312
356
|
|
|
313
|
-
|
|
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
|
+
```
|
|
314
362
|
|
|
315
|
-
**
|
|
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:
|
|
316
364
|
|
|
317
|
-
|
|
365
|
+
```bash
|
|
366
|
+
npx @yeison.restrepo.r/code-conductor@latest --project # global setup + scaffold ./.claude
|
|
367
|
+
```
|
|
318
368
|
|
|
319
|
-
|
|
369
|
+
By default, the installer installs only the global core files. Flags extend that:
|
|
320
370
|
|
|
321
|
-
|
|
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. |
|
|
322
376
|
|
|
323
|
-
**
|
|
377
|
+
**Updating:** re-run the same install command. User-configured files are never overwritten; agent-managed files are always updated.
|
|
324
378
|
|
|
325
|
-
|
|
379
|
+
Two cautions:
|
|
326
380
|
|
|
327
|
-
|
|
328
|
-
- `
|
|
329
|
-
- Under auto permission mode no human stands behind a Bash write or a hook `ask`.
|
|
330
|
-
- 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.
|
|
331
|
-
- 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.
|
|
332
383
|
|
|
333
|
-
|
|
384
|
+
### How the installer treats your CLAUDE.md
|
|
334
385
|
|
|
335
|
-
|
|
386
|
+
`CLAUDE.md` and `.gitignore` are **merged**, never overwritten. Everything else the installer ships (`settings.json`, hooks, commands, `scripts/`) is replaced on every run.
|
|
336
387
|
|
|
337
|
-
|
|
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:
|
|
338
392
|
|
|
339
|
-
|
|
393
|
+
```
|
|
394
|
+
code-conductor: backed up CLAUDE.md to CLAUDE.md.installer-backup.20260930T120000Z before merging (git-ignored by design)
|
|
395
|
+
```
|
|
340
396
|
|
|
341
|
-
|
|
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.
|
|
342
398
|
|
|
343
|
-
|
|
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.
|
|
344
400
|
|
|
345
|
-
|
|
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.
|
|
346
402
|
|
|
347
|
-
###
|
|
403
|
+
### The .gitignore block
|
|
348
404
|
|
|
349
|
-
|
|
405
|
+
When installed with `--project`, the installer keeps its rules in one labelled block in your project's `.gitignore`:
|
|
350
406
|
|
|
351
|
-
|
|
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`.
|
|
352
418
|
|
|
353
|
-
|
|
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.
|
|
354
420
|
|
|
355
421
|
---
|
|
356
422
|
|
|
357
|
-
##
|
|
423
|
+
## What this is not
|
|
358
424
|
|
|
359
|
-
|
|
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.
|
|
360
428
|
|
|
361
|
-
|
|
362
|
-
|
|
363
|
-
- **
|
|
364
|
-
-
|
|
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.
|
|
365
447
|
|
|
366
|
-
|
|
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
|
+
- **The `P7` false positive** described under [Guard 3, and what it learned](#guard-3-and-what-it-learned), still live.
|
|
461
|
+
- **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.
|
|
462
|
+
- **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.
|
|
367
463
|
|
|
368
|
-
|
|
464
|
+
**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.
|
|
369
465
|
|
|
370
466
|
---
|
|
371
467
|
|
|
372
|
-
##
|
|
468
|
+
## Instruments: releases that verify their own record
|
|
373
469
|
|
|
374
|
-
|
|
375
|
-
~/.claude/
|
|
376
|
-
memory/
|
|
377
|
-
personal.md ← local only, never committed
|
|
378
|
-
dev preferences, shortcuts
|
|
379
|
-
verbosity.md ← agent-managed, set by installer
|
|
380
|
-
active verbosity level (MIN/INFO/VERBOSE)
|
|
381
|
-
|
|
382
|
-
project-root/
|
|
383
|
-
.claude/
|
|
384
|
-
memory/
|
|
385
|
-
project.md ← in git, shared with team
|
|
386
|
-
decisions, conventions, debt, workarounds
|
|
387
|
-
```
|
|
470
|
+
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:
|
|
388
471
|
|
|
389
|
-
|
|
472
|
+
- **`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.
|
|
473
|
+
- **`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.
|
|
474
|
+
- **`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.
|
|
475
|
+
- **`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.
|
|
476
|
+
|
|
477
|
+
**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.
|
|
390
478
|
|
|
391
|
-
|
|
479
|
+
`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.
|
|
392
480
|
|
|
393
481
|
---
|
|
394
482
|
|
|
395
|
-
## Language
|
|
483
|
+
## Language support
|
|
396
484
|
|
|
397
485
|
| Priority | Source | How to set |
|
|
398
|
-
|
|
399
|
-
| 1 (highest) | Session | `/lang [code]` |
|
|
486
|
+
|---|---|---|
|
|
487
|
+
| 1 (highest) | Session | `/cc-lang [code]` |
|
|
400
488
|
| 2 | Project | `language:` in project `CLAUDE.md` |
|
|
401
489
|
| 3 | Personal | `response_language:` in `personal.md` |
|
|
402
490
|
| 4 (default) | Global | English |
|
|
403
491
|
|
|
404
492
|
**Supported codes:** `en` `es` `pt` `fr` `de` `it` `zh` `ja` `ko`
|
|
405
493
|
|
|
406
|
-
Code identifiers, file names
|
|
494
|
+
Code identifiers, file names and commit messages are always English.
|
|
407
495
|
|
|
408
496
|
---
|
|
409
497
|
|
|
410
|
-
## File
|
|
498
|
+
## File structure
|
|
411
499
|
|
|
412
500
|
```
|
|
413
501
|
code-conductor/
|
|
414
|
-
|
|
415
|
-
|
|
416
|
-
|
|
417
|
-
|
|
418
|
-
|
|
419
|
-
|
|
420
|
-
|
|
421
|
-
|
|
422
|
-
|
|
423
|
-
|
|
424
|
-
|
|
425
|
-
|
|
426
|
-
|
|
427
|
-
|
|
428
|
-
|
|
429
|
-
|
|
430
|
-
|
|
431
|
-
|
|
432
|
-
|
|
433
|
-
|
|
434
|
-
|
|
435
|
-
|
|
436
|
-
|
|
437
|
-
|
|
438
|
-
|
|
439
|
-
|
|
440
|
-
|
|
441
|
-
|
|
442
|
-
|
|
443
|
-
|
|
444
|
-
|
|
445
|
-
|
|
446
|
-
|
|
447
|
-
|
|
448
|
-
|
|
449
|
-
|
|
450
|
-
|
|
451
|
-
|
|
452
|
-
|
|
453
|
-
|
|
454
|
-
|
|
455
|
-
|
|
456
|
-
|
|
457
|
-
|
|
458
|
-
|
|
459
|
-
|
|
460
|
-
|
|
461
|
-
|
|
462
|
-
|
|
463
|
-
|
|
464
|
-
|
|
465
|
-
|
|
466
|
-
|
|
467
|
-
├── code-simplifier/SKILL.md Always active — complexity and simplicity rules
|
|
468
|
-
├── critical-review/SKILL.md Always active — 4-phase adversarial review protocol
|
|
469
|
-
├── verbosity/SKILL.md Always active — MIN/INFO/VERBOSE response rules
|
|
470
|
-
├── memory-first/SKILL.md Always active — memory → grep → read chain
|
|
471
|
-
└── agent-delegation/SKILL.md Always active — sub-agent spawn rules
|
|
472
|
-
# Claude Code registers personal skills only at ~/.claude/skills/<name>/SKILL.md
|
|
473
|
-
```
|
|
474
|
-
|
|
475
|
-
---
|
|
476
|
-
|
|
477
|
-
## .gitignore Note
|
|
478
|
-
|
|
479
|
-
When installed with `--project`, the installer keeps its rules in one labelled block in
|
|
480
|
-
your project's `.gitignore`:
|
|
481
|
-
|
|
482
|
-
```
|
|
483
|
-
# Code Conductor (added by the installer; safe to keep)
|
|
484
|
-
.claude/memory/turn-count.txt
|
|
485
|
-
*.installer-backup.*
|
|
486
|
-
*.installer-tmp.*
|
|
502
|
+
+-- README.md
|
|
503
|
+
+-- VERSION
|
|
504
|
+
+-- bin/code-conductor.mjs npm CLI entry (npx code-conductor)
|
|
505
|
+
+-- lib/installer/ CLI modules (env, deploy, settings, merges, heal)
|
|
506
|
+
+-- global/
|
|
507
|
+
| +-- CLAUDE.md Global agent behavior (all projects)
|
|
508
|
+
| +-- settings.json
|
|
509
|
+
| +-- commands/ /cc-checkpoint, /cc-stack, /cc-lang, /cc-compact
|
|
510
|
+
| +-- hooks/
|
|
511
|
+
| | +-- verbosity-remind.sh Verbosity reminder on UserPromptSubmit
|
|
512
|
+
| +-- memory/
|
|
513
|
+
| +-- personal.md Template (never committed)
|
|
514
|
+
| +-- verbosity.md Active verbosity level
|
|
515
|
+
+-- project-template/
|
|
516
|
+
| +-- CLAUDE.md
|
|
517
|
+
| +-- gitignore Merged into the host project's .gitignore
|
|
518
|
+
| +-- .claude/
|
|
519
|
+
| +-- settings.json Hooks wiring
|
|
520
|
+
| +-- review-loop.settings.json Auto mode exception for the review loop (FEAT-041)
|
|
521
|
+
| +-- agents/ Band roles: spec, plan, code, audit, qa (FEAT-012);
|
|
522
|
+
| | define-review (FEAT-041)
|
|
523
|
+
| +-- commands/ /cc-init, /cc-resume, /cc-spec, /cc-plan, /cc-implement,
|
|
524
|
+
| | /cc-orchestrate, /cc-review, /cc-debug, /cc-refactor,
|
|
525
|
+
| | /cc-test, /cc-docs
|
|
526
|
+
| +-- hooks/
|
|
527
|
+
| | +-- pre-tool-use.mjs Node front door: Guards 1 to 7
|
|
528
|
+
| | +-- context-guard.sh Turn-counter warning (.sh + .ps1)
|
|
529
|
+
| | +-- post-compact.sh Checkpoint reminder + cache sweep after /compact (.sh + .ps1)
|
|
530
|
+
| | +-- verbosity-remind.sh Project-level verbosity reminder
|
|
531
|
+
| +-- memory/
|
|
532
|
+
| +-- project.md Shared team memory (in git)
|
|
533
|
+
| +-- bash-scan-allowlist.txt Guard 3 operator exceptions (commented template)
|
|
534
|
+
| +-- context-threshold.txt Turn-counter threshold
|
|
535
|
+
+-- scripts/
|
|
536
|
+
| +-- conductor-db.mjs Zero-dep node:sqlite engine (.conductor/cache.db)
|
|
537
|
+
| +-- resume-read.mjs Phase-entry resume reader (DB snapshot, then handoff)
|
|
538
|
+
| +-- snap-contract.mjs SNAP limits, caps, field sets, version ceiling
|
|
539
|
+
| +-- snap-build.mjs SNAP handoff serializer
|
|
540
|
+
| +-- snap-validate.mjs SNAP schema validator
|
|
541
|
+
| +-- session-id.mjs Stable session-id resolver
|
|
542
|
+
| +-- orchestrate.mjs Band router: run file, envelopes, hand-backs (FEAT-011)
|
|
543
|
+
| +-- ticket.mjs Ticket intake and writeback through gh (FEAT-031)
|
|
544
|
+
| +-- detect-stack.mjs Stack auto-detection scanner
|
|
545
|
+
| +-- claude-md-fields.mjs CLAUDE.md field reader/writer
|
|
546
|
+
| +-- init-wizard.mjs /cc-init helper
|
|
547
|
+
+-- skills/
|
|
548
|
+
| +-- code-simplifier/SKILL.md Always active: complexity and simplicity rules
|
|
549
|
+
| +-- critical-review/SKILL.md Always active: 4-phase adversarial review protocol
|
|
550
|
+
| +-- verbosity/SKILL.md Always active: MIN/INFO/VERBOSE response rules
|
|
551
|
+
| +-- memory-first/SKILL.md Always active: memory, grep, read chain
|
|
552
|
+
| +-- agent-delegation/SKILL.md Always active: sub-agent spawn rules
|
|
553
|
+
+-- tools/ Release instruments (repository only, not shipped)
|
|
554
|
+
+-- README.md Instrument notes and the retired-instrument registry
|
|
487
555
|
```
|
|
488
556
|
|
|
489
|
-
|
|
490
|
-
exactly one of these three rules (earlier versions appended them one at a time) is moved
|
|
491
|
-
into the block, so each rule appears once; a line you changed, such as
|
|
492
|
-
`/.claude/memory/turn-count.txt`, is not an exact match and stays where it is. If your
|
|
493
|
-
`.gitignore` has any `!` line, nothing is moved, because moving a rule past a `!` can
|
|
494
|
-
change what is ignored: the block then holds only the rules you lack, and the installer
|
|
495
|
-
says so. A change to `.gitignore` is backed up and reported exactly as for `CLAUDE.md`.
|
|
496
|
-
|
|
497
|
-
The last two keep the installer's own backups and crash-stranded temp files out of
|
|
498
|
-
`git status`. The rules ship inside the package as `project-template/gitignore`
|
|
499
|
-
(no leading dot) because npm strips any file literally named `.gitignore` from every
|
|
500
|
-
published tarball; the installer restores the dot when it writes to your project.
|
|
557
|
+
Claude Code registers personal skills only at `~/.claude/skills/<name>/SKILL.md`, which is where the installer puts them.
|
|
501
558
|
|
|
502
559
|
---
|
|
503
560
|
|
|
504
|
-
##
|
|
505
|
-
|
|
506
|
-
`CLAUDE.md` and `.gitignore` are **merged**, never overwritten. Everything else the
|
|
507
|
-
installer ships (`settings.json`, hooks, commands, `scripts/`) is replaced on every run.
|
|
508
|
-
|
|
509
|
-
- **Code Conductor owns one block and nothing else.** Its content lives between
|
|
510
|
-
`<!-- cc:managed:start -->` and `<!-- cc:managed:end -->`, and those two markers alone
|
|
511
|
-
decide ownership; a heading's name never does. Every upgrade replaces the block's
|
|
512
|
-
contents wholesale, so released improvements reach existing installs. Edits inside the
|
|
513
|
-
block are lost, and recoverable from the backup.
|
|
514
|
-
- **Everything outside the block is yours, byte for byte.** Nothing outside it is
|
|
515
|
-
removed, rewritten, reordered or added.
|
|
516
|
-
- **A file without the markers gets the block appended at the end**, after one blank
|
|
517
|
-
line and in your file's line endings, and nothing else changes. If your file already
|
|
518
|
-
has sections named like the block's (`## Agent Identity`, `## Hard Constraints`, …),
|
|
519
|
-
you will see both: yours above, Code Conductor's inside the block. That is deliberate.
|
|
520
|
-
The installer never decides which of your sections are really its own; reconciling
|
|
521
|
-
them is planned for `/cc-stack` as `[FEAT-040]`.
|
|
522
|
-
- **Before any change, the installer copies your file to
|
|
523
|
-
`CLAUDE.md.installer-backup.<UTC timestamp>`**, keeps the five most recent, and prints
|
|
524
|
-
where it put it:
|
|
525
|
-
|
|
526
|
-
```
|
|
527
|
-
code-conductor: backed up CLAUDE.md to CLAUDE.md.installer-backup.20260930T120000Z before merging (git-ignored by design)
|
|
528
|
-
```
|
|
561
|
+
## Uninstall notes
|
|
529
562
|
|
|
530
|
-
|
|
531
|
-
teammate's `git status`; the printed line is how you find yours. A fresh install, and a
|
|
532
|
-
re-run that changes nothing, print nothing.
|
|
563
|
+
Hook removal (`rm ~/.claude/hooks/verbosity-remind.sh`) and `settings.json` cleanup work identically in every environment; no git is required.
|
|
533
564
|
|
|
534
|
-
|
|
535
|
-
path. If your file ends inside a code fence that is never closed, the installer leaves it
|
|
536
|
-
untouched with a warning, because a block appended there would be hidden inside the fence.
|
|
537
|
-
|
|
538
|
-
If the markers in your file are damaged — a `start` with no `end`, two blocks, an `end`
|
|
539
|
-
before its `start` — the installer prints a warning, leaves the file completely untouched,
|
|
540
|
-
and finishes the rest of the install. Fix the markers and re-run.
|
|
541
|
-
|
|
542
|
-
---
|
|
543
|
-
|
|
544
|
-
## Uninstall Notes
|
|
545
|
-
|
|
546
|
-
> **`git revert` in non-repository environments (CI/CD, Docker, bare installs):**
|
|
547
|
-
> 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.
|
|
548
|
-
>
|
|
549
|
-
> **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.
|
|
565
|
+
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`.
|
|
550
566
|
|
|
551
567
|
---
|
|
552
568
|
|
|
553
569
|
## Contributing
|
|
554
570
|
|
|
555
571
|
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.
|
|
572
|
+
|
|
573
|
+
## License
|
|
574
|
+
|
|
575
|
+
See [LICENSE](https://github.com/yeisonrestrepo/code-conductor/blob/main/LICENSE).
|
package/bin/code-conductor.mjs
CHANGED
|
@@ -52,13 +52,15 @@ function pkgVersion(assetRoot) {
|
|
|
52
52
|
}
|
|
53
53
|
|
|
54
54
|
// log(stream, msg) is injected so tests capture output without spawning a process.
|
|
55
|
-
export function run(argv, env = process.env, { cwd = process.cwd(), log } = {}) {
|
|
55
|
+
export function run(argv, env = process.env, { cwd = process.cwd(), log, nodeVersion = process.versions.node } = {}) {
|
|
56
56
|
const emit = log || ((stream, msg) => process[stream].write(`${msg}\n`));
|
|
57
57
|
|
|
58
58
|
// Hard runtime floor: refuse to run on Node < 20 with a clear message rather than
|
|
59
|
-
// failing obscurely inside cpSync/ESM later.
|
|
60
|
-
|
|
61
|
-
|
|
59
|
+
// failing obscurely inside cpSync/ESM later. The version comes from options, never env:
|
|
60
|
+
// on Windows env lookups are case-insensitive and npm sets NODE to node.exe's path,
|
|
61
|
+
// so a lowercase node key read that path (BUG-060).
|
|
62
|
+
if (!nodeMajorAtLeast(20, nodeVersion)) {
|
|
63
|
+
emit('stderr', `code-conductor: Node >=20 required, found ${nodeVersion}`);
|
|
62
64
|
return 1;
|
|
63
65
|
}
|
|
64
66
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@yeison.restrepo.r/code-conductor",
|
|
3
|
-
"version": "1.39.
|
|
3
|
+
"version": "1.39.3",
|
|
4
4
|
"description": "A governance layer for Claude Code sessions: hooks that check an agent's commands before they run, a spec-first workflow, and project memory the next session reads.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"agentic-development",
|
|
@@ -86,7 +86,7 @@ Run `/cc-checkpoint`. Persist current architectural state to `.claude/memory/pro
|
|
|
86
86
|
|
|
87
87
|
## Step 5 — Hook integrity check
|
|
88
88
|
|
|
89
|
-
Verify `.claude/hooks/pre-tool-use.mjs` exists. It is
|
|
89
|
+
Verify `.claude/hooks/pre-tool-use.mjs` exists. It is loaded by `node` through the PreToolUse command in `.claude/settings.json`, so it needs no execute bit:
|
|
90
90
|
|
|
91
91
|
```bash
|
|
92
92
|
HOOK=".claude/hooks/pre-tool-use.mjs"
|
|
@@ -622,10 +622,12 @@ const G3_CHECKS = [
|
|
|
622
622
|
// Present-but-unreadable means an empty list PLUS a debug line, because that is a
|
|
623
623
|
// fault worth seeing, and neither condition may throw: a permissions problem on a
|
|
624
624
|
// policy file must never escalate into denying every tool call in the session.
|
|
625
|
+
// The root is CLAUDE_PROJECT_DIR because the session's cwd drifts; cwd is only the
|
|
626
|
+
// fallback for a launcher that does not set it (BUG-061).
|
|
625
627
|
function g3ReadAllowlist() {
|
|
626
628
|
let raw;
|
|
627
629
|
try {
|
|
628
|
-
raw = readFileSync(join(process.cwd(), ...G3_ALLOWLIST_REL), 'utf8');
|
|
630
|
+
raw = readFileSync(join(process.env.CLAUDE_PROJECT_DIR || process.cwd(), ...G3_ALLOWLIST_REL), 'utf8');
|
|
629
631
|
} catch (e) {
|
|
630
632
|
if (e.code !== 'ENOENT') debug(`guard 3 allowlist unreadable: ${e.message}`);
|
|
631
633
|
return [];
|
|
@@ -6,7 +6,7 @@
|
|
|
6
6
|
"hooks": [
|
|
7
7
|
{
|
|
8
8
|
"type": "command",
|
|
9
|
-
"command": "node .claude/hooks/pre-tool-use.mjs"
|
|
9
|
+
"command": "node --input-type=commonjs -e \"import(require('url').pathToFileURL(require('path').resolve(process.env.CLAUDE_PROJECT_DIR||'.','.claude/hooks/pre-tool-use.mjs')).href)\""
|
|
10
10
|
}
|
|
11
11
|
]
|
|
12
12
|
}
|