code-conductor

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.

Quickstart

Three commands, from nothing to a guarded session. The output below is real, captured by running exactly these commands in a scratch directory.

mkdir demo && cd demo && git init -q && npm init -y >/dev/null
npx @yeison.restrepo.r/code-conductor --project

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").

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:

# scene 1: a mass content dump is denied, with a message that says what to do instead
cat *.ts

BASH SCAN BLOCKED. The command triggered a mass content-dump pattern. Pattern ids: P4.
Authorized alternatives: 1. Grep for targeted content search with file and pattern scope.
2. Glob for path listing without file content. 3. Read with an explicit offset and limit.
A permanent exception is operator policy, not a self-serve step: entries live in
.claude/memory/bash-scan-allowlist.txt, are reviewed in git, and an agent may propose one
but must not add it to clear its own denial.

# scene 2: the decomposed form runs
grep -n 'export' src/index.ts

Nothing is printed by the hook. The command runs.

Guard 3, and what it learned

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).

The interesting part is what it got wrong, because that is what the record documents.

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.

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.

The honest numbers

Every figure here is cited, and none of them is rounded in the project's favour.

measurement	value	source
Guard 3 denials recovered from one real working session	47 events, 43 unique commands	`.claude/memory/project.md:991`
...of which flipped `deny` to `allow` after the `1.31.x` fixes	36 of 43	same table
unplanned regressions from those fixes	0	same table
this session's own denials, replayed verbatim against today's hook	3: one now allowed, two still denied	reproducible, below
...of the two still denied, the guard being right	1 (a genuine shell loop)	corpus control row
...the guard being wrong	1 (a surviving `P7` parity inversion)	recorded in `[BUG-041]`'s entry

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.

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.

Instruments: releases that verify their own record

Three checks live in tools/ as tracked repository infrastructure, and two of them run against the live repository in CI, so a divergence blocks the merge rather than waiting for someone to remember:

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.
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.
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.

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.

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.

What this is not

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.
Not a model. It is configuration, hooks and scripts around Claude Code.
Not finished. See the limits below.

Known limits

[BUG-045] is the one open filed defect: 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.
The P7 false positive above, still live.
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, 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.
Two open dossiers, which are the evidence-collection pipeline working rather than a backlog: a session denial tally, and one for interleaved-artifact reports. 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.

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.

Dependencies

code-conductor assumes these are already in place — the installer does not set them up for you:

Dependency	Required for	How to get it
Node.js `>= 20`	Running the `code-conductor` CLI itself	Any current Node LTS
Claude Code	The environment every command/skill/hook in this repo runs inside	—
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
ui-ux-pro-max skill	UI/UX guidance on frontend projects	No manual step — the installer downloads it from GitHub automatically when `/cc-stack` detects a frontend stack

The Problem

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.

Without code-conductor	With code-conductor
Free-form prompt → agent guesses, overwrites, drifts	`/cc-spec` → approved spec → `/cc-plan` → confirmed steps → implement
Full files read on every turn	grep/find before read — targeted tool calls only
Conventions reset every session	Stack profile + memory loaded at session start
Frontend code with no UX consideration	UI/UX skill activated automatically for frontend stacks
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
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

Install

npx @yeison.restrepo.r/code-conductor            # one-shot global setup
# or
npm install -g @yeison.restrepo.r/code-conductor && code-conductor

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:

code-conductor --project      # global setup + scaffold ./.claude in the current repo

Flags

By default, the installer installs only the global core files. Use flags to extend this behavior.

Flag	Description
`--project` / `-Project`	Also install the project template into the current directory
`--no-deps` / `-NoDeps`	Skip dependency installation (Node tooling, Playwright MCP, plugins); copy agent files only
`--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.

Update

Re-run the same install command. User-configured files are never overwritten; agent-managed files are always updated.

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.

How It Works

code-conductor operates at three layers:

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.

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.

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.

Available Commands

All commands are tagged (Conductor) in the Claude Code command palette so they're easy to spot alongside commands from other sources.

Global (all projects)

Command	Description
`/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.
`/cc-stack`	Run the dynamic detector to identify your framework and write the detected commands and a generated ruleset into your project `CLAUDE.md`.
`/cc-lang [code]`	Switch response language for this session. Code identifiers, filenames, and commit messages remain English regardless.

Project (requires `--project` install)

Command	Description
`/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.
`/cc-init`	Initialize or re-sync the project environment: detect stack, checkpoint memory, and verify hook integrity. Run at the start of every session.
`/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.
`/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.
`/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.
`/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).

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).
| /cc-review [file\|dir] | Review code in three layers - Critical / Important / Suggestion - then deliver a verdict and offer to auto-fix. |
| /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. |
| /cc-refactor [file\|module] | Diagnose complexity, plan ordered changes, apply one step at a time, and verify tests pass after each step. |
| /cc-test [scope] | Analyze coverage gaps, write tests in AAA pattern, add Playwright E2E where applicable, run after confirmation, and report results. |
| /cc-docs [scope] | Audit existing documentation, write inline docs in the correct format for your stack (JSDoc / docstrings / JavaDoc / GoDoc), and preview before writing. |

Skills

Skills extend agent behavior for cross-cutting concerns that apply regardless of stack.

code-simplifier — always active

Applied to every piece of code written or reviewed in every session. Enforces:

No speculative abstractions — solve today's problem only
Functions ≤30 lines, doing one thing
Flat over nested — guard clauses and early returns
Descriptive names — no Base, Abstract, Manager, Handler
Comments explain why, never what

ui-ux-pro-max — frontend projects

Activated automatically when /cc-stack detects a frontend stack (React, Angular, Next.js, and similar). Installed from nextlevelbuilder/ui-ux-pro-max-skill — the installer downloads it directly from GitHub. Enforces visual hierarchy, spacing grids, semantic color tokens, component states, WCAG AA accessibility, and framework-specific UI conventions.

critical-review — always active during implementation

Applied to every implementation task via a 4-phase adversarial protocol:

Pre-Flight — Happy Path, Failure Points, and Boundary Conditions identified before any code is written
Adversarial Review — RESILIENCE (silent failures), EFFICIENCY (code smells), FRICTION (happy-path friction)
Self-Correction — each weakness refactored and re-verified in isolation
[VALIDATION] — required closing section on every implementation: edge cases covered, best-outcome justification, residual risks

verbosity — always active

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.

Level	Behavior
`MIN`	One declarative sentence. `[CHANGES]` tag with file list only.
`INFO`	Bullet list of what changed and why. Max 5 bullets. `[CHANGES]` + `[REASON]`.
`VERBOSE`	Full explanation, prose allowed. All response tags.

memory-first — always active

Before reading any file, Claude walks a priority lookup chain and stops at the first step that answers the question:

Project memory: .claude/memory/project.md
Grep / Glob — pattern searches
Targeted read — last resort, always with offset + limit, max 150 lines

agent-delegation — always active

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.

Hooks

Hooks run automatically at specific points in a Claude Code session. They require no manual setup.

pre-tool-use

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.

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.

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.

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.

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.

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.

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.

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.

context-guard (global + project) — v1.15.0

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.

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.

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 run /cc-checkpoint if context from this session hasn't been saved yet. Prevents losing decisions and conventions when the context window is compressed.

verbosity-remind (global + project) — v1.11.0

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).

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.

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.

Local State Cache & Session Persistence — v1.22.0

/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.

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.
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.
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.
Gitignored: .conductor/ is local-only and never committed.

Phase-entry resume — v1.22.0

/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).

Memory Architecture

~/.claude/
  memory/
    personal.md     ← local only, never committed
                       dev preferences, shortcuts
    verbosity.md    ← agent-managed, set by installer
                       active verbosity level (MIN/INFO/VERBOSE)

project-root/
  .claude/
    memory/
      project.md    ← in git, shared with team
                       decisions, conventions, debt, workarounds

/cc-checkpoint writes to both. Run it before /compact, after completing a feature, and after any key architectural decision.

/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.

Language Support

Priority	Source	How to set
1 (highest)	Session	`/lang [code]`
2	Project	`language:` in project `CLAUDE.md`
3	Personal	`response_language:` in `personal.md`
4 (default)	Global	English

Supported codes: en es pt fr de it zh ja ko

Code identifiers, file names, and commit messages are always English.

File Structure

code-conductor/
├── README.md
├── VERSION
├── .gitignore
├── bin/code-conductor.mjs        npm CLI entry (npx code-conductor)
├── lib/installer/                CLI modules (env, deploy, settings, config)
├── global/
│   ├── CLAUDE.md                 Global agent behavior (all projects)
│   ├── settings.json
│   ├── commands/
│   │   ├── cc-checkpoint.md      /cc-checkpoint
│   │   ├── cc-stack.md           /cc-stack
│   │   └── cc-lang.md            /cc-lang
│   ├── hooks/
│   │   └── verbosity-remind.sh       Verbosity reminder on UserPromptSubmit
│   └── memory/
│       └── personal.md           Template (never committed)
├── project-template/
│   ├── CLAUDE.md
│   ├── gitignore                 Merged into the host project's .gitignore
│   └── .claude/
│       ├── settings.json         Hooks wiring (pre-tool-use, post-compact)
│       ├── commands/
│       │   ├── cc-init.md        /cc-init — session initialization
│       │   ├── cc-resume.md      /cc-resume — session context restore
│       │   ├── cc-spec.md        /cc-spec
│       │   ├── cc-plan.md        /cc-plan
│       │   ├── cc-implement.md   /cc-implement
│       │   ├── cc-review.md      /cc-review
│       │   ├── cc-compact.md     /cc-compact — phase boundary compaction
│       │   ├── cc-debug.md       /cc-debug
│       │   ├── cc-refactor.md    /cc-refactor
│       │   ├── cc-test.md        /cc-test
│       │   └── cc-docs.md        /cc-docs
│       ├── hooks/
│       │   ├── pre-tool-use.mjs  Node front door: large-file, duplicate-write and node_modules guards
│       │   ├── context-guard.sh  Turn-counter warning (.sh + .ps1)
│       │   └── post-compact.sh   Checkpoint reminder + cache sweep after `/compact` (.sh + .ps1)
│       └── memory/
│           └── project.md        Shared team memory (in git)
├── scripts/
│   ├── conductor-db.mjs          Zero-dep node:sqlite engine (.conductor/cache.db)
│   ├── resume-read.mjs           Phase-entry resume reader (DB snapshot → handoff fallback)
│   ├── snap-contract.mjs         SNAP limits, caps, field sets, version ceiling
│   ├── snap-build.mjs            SNAP v1/v2 handoff serializer
│   ├── snap-validate.mjs         SNAP schema validator
│   ├── session-id.mjs            Stable session-id resolver
│   └── detect-stack.mjs          Stack auto-detection scanner
└── skills/
    ├── code-simplifier/SKILL.md   Always active — complexity and simplicity rules
    ├── critical-review/SKILL.md   Always active — 4-phase adversarial review protocol
    ├── verbosity/SKILL.md         Always active — MIN/INFO/VERBOSE response rules
    ├── memory-first/SKILL.md      Always active — memory → grep → read chain
    └── agent-delegation/SKILL.md  Always active — sub-agent spawn rules
    # Claude Code registers personal skills only at ~/.claude/skills/<name>/SKILL.md
    # ui-ux-pro-max installed from github.com/nextlevelbuilder/ui-ux-pro-max-skill

.gitignore Note

When installed with --project, the installer appends these rules to your project's
.gitignore, and only the ones you are missing — your own entries are never touched:

.claude/memory/turn-count.txt
*.installer-backup.*
*.installer-tmp.*

The last two keep the installer's own backups and crash-stranded temp files out of
git status. 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.

How the installer treats your CLAUDE.md

CLAUDE.md and .gitignore are merged, never overwritten. Everything else the
installer ships (settings.json, hooks, commands, scripts/) is replaced on every run.

Managed sections live between  and .
Code Conductor owns that block and replaces its contents wholesale on every upgrade, so
released improvements reach existing installs. Edits inside the block are lost.
Everything outside the block is yours. Existing sections are preserved byte-for-byte;
sections the template has and your file lacks are appended once, immediately above the
managed block. Sections you wrote that the template has never heard of are never touched.
Before any change, the installer copies your file to
CLAUDE.md.installer-backup.<UTC timestamp> and keeps the five most recent.

One-time migration on your first 1.24 install. If your CLAUDE.md predates the
sentinel markers and already contains sections that the managed block also defines
(## Agent Identity, ## Hard Constraints, …), those sections are removed and
replaced by the managed block, so you do not end up with two copies of each. This is the
only path that discards content you wrote. Your pre-migration file is preserved in the
.installer-backup. copy beside it — diff it after upgrading and move anything you
want to keep into a section outside the managed block.

A cosmetic wart of that same migration, in ~/.claude/CLAUDE.md only. The managed
block carries the file's intro sentence ("Applies to every project on this machine…"),
and your pre-sentinel copy keeps its own above the block, so you will see that one
sentence twice after the first upgrade. Delete the copy above the block — it is outside
the managed region, so your deletion sticks.

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.

Uninstall Notes

git revert in non-repository environments (CI/CD, Docker, bare installs):
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.

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.