@yeison.restrepo.r/code-conductor 1.23.0

package/LICENSE

@@ -0,0 +1,185 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship made available under
+      the License, as indicated by a copyright notice that is included in
+      or attached to the work (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and derivative works thereof.
+
+      "Contribution" shall mean, as submitted to the Licensor for inclusion
+      in the Work by the copyright owner or by an individual or Legal Entity
+      authorized to submit on behalf of the copyright owner. For the purposes
+      of this definition, "submitted" means any form of electronic, verbal,
+      or written communication sent to the Licensor or its representatives,
+      including but not limited to communication on electronic mailing lists,
+      source code control systems, and issue tracking systems that are managed
+      by, or on behalf of, the Licensor for the purpose of discussing and
+      improving the Work, but excluding communication that is conspicuously
+      marked or otherwise designated in writing by the copyright owner as
+      "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any Legal Entity on behalf of
+      whom a Contribution has been received by the Licensor and subsequently
+      incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contributions
+      with the Work to which such Contributions were submitted. If You
+      institute patent litigation against any entity (including a cross-claim
+      or counterclaim in a lawsuit) alleging that the Work or any
+      Contribution incorporated within the Work constitutes direct or
+      contributory patent infringement, then any patent licenses granted
+      to You under this License for that Work shall terminate as of the
+      date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or Derivative
+          Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, You must include a readable copy of the
+          attribution notices contained within such NOTICE file, in
+          at least one of the following places: within a NOTICE text
+          file distributed as part of the Derivative Works; within
+          the Source form or documentation, if provided along with the
+          Derivative Works; or, within a display generated by the
+          Derivative Works, if and wherever such third-party notices
+          normally appear. The contents of the NOTICE file are for
+          informational purposes only and do not modify the License.
+          You may add Your own attribution notices within Derivative
+          Works that You distribute, alongside or as an additional
+          addendum to the NOTICE text from the Work, provided that
+          such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own license statement for Your modifications and
+      may provide additional grant of rights to use, copy, modify, merge,
+      publish, distribute, sublicense, and/or sell copies of the
+      Derivative Works, and to permit persons to whom the Derivative Works
+      are furnished to do so.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any conditions of title,
+      merchantability, or fitness for a particular purpose. You are
+      solely responsible for determining the appropriateness of using
+      or redistributing the Work and assume any risks associated with
+      Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or exemplary damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or all other
+      commercial damages or losses), even if such Contributor has been
+      advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2026 Yeison Restrepo
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+   implied. See the License for the specific language governing
+   permissions and limitations under the License.

package/README.md

@@ -0,0 +1,314 @@
+# code-conductor
+
+A spec-first, token-efficient Claude Code configuration that turns AI-assisted coding into a disciplined, repeatable engineering workflow.
+
+---
+
+## 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
+
+```bash
+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
+
+```bash
+code-conductor --project      # also 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 `graphify-out` or `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. Use relative paths if this layout is unavoidable.
+
+---
+
+## 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, refresh the project graph, 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](#local-state-cache--session-persistence--v1220)).
+| `/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](https://github.com/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:
+
+1. **Pre-Flight** — Happy Path, Failure Points, and Boundary Conditions identified before any code is written
+2. **Adversarial Review** — RESILIENCE (silent failures), EFFICIENCY (code smells), FRICTION (happy-path friction)
+3. **Self-Correction** — each weakness refactored and re-verified in isolation
+4. **`[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:
+
+1. **Project memory**: `.claude/memory/project.md`
+2. **Graphify graph** — structural/relational queries (`what calls X`, `what depends on Y`)
+3. **Grep / Glob** — pattern searches
+4. **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.
+
+### graphify-ast-refresh *(global)*
+
+Fires on every `UserPromptSubmit`. Checks whether `graphify-out/.graphify_ast_done` is fresh (default: 60 min, override with `GRAPHIFY_STALE_MINUTES`). If stale or missing, spawns a non-blocking background Python process that runs file detection and AST extraction — no LLM calls, no tokens. The main session inherits a ready graph without paying the generation cost.
+
+Works on Windows, Linux, and macOS. Exits in under 5ms when the graph is current.
+
+### pre-tool-use
+
+Fires before every tool call. Three guards:
+
+**Large-file Read guard** — if Claude tries to read a file with more than 150 lines without specifying an `offset` and `limit`, the call is blocked and Claude is redirected to the orchestrator lookup chain (memory → graph → grep → targeted read). Prevents reading entire codebases when a targeted search would do.
+
+**Duplicate file guard** — if Claude tries to write or create a file that already exists, it prints a warning showing the file path, line count, and last-modified timestamp, then presents three options: overwrite, edit in place, or cancel. Prevents silently replacing files you've already configured.
+
+**Bash scan guard (Guard 3)** — intercepts every Bash tool call and pattern-matches the command string against 12 mass content-dump patterns before execution: deep `find` without `maxdepth 1`, `find -exec` with readers/shells, `xargs` with readers, `cat`/pager/grep with unquoted globs, command substitution with readers, shell loops, `mapfile`/`readarray`, `eval`/`source`/dot operator, alias remapping to readers, and obfuscation sequences. Commands over 8192 characters and unclosed quotes are blocked fail-closed. Operators can whitelist specific directory prefixes or exact tokens via `BASH_SCAN_ALLOWLIST` in the hook file.
+
+### 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/
+│   │   └── graphify-ast-refresh.py  Background AST refresh on UserPromptSubmit
+│   └── memory/
+│       └── personal.md           Template (never committed)
+├── project-template/
+│   ├── CLAUDE.md
+│   └── .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.sh   Large-file read guard + duplicate file guard + bash scan guard
+│       │   ├── 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-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.md        Always active — complexity and simplicity rules
+    ├── critical-review.md        Always active — 4-phase adversarial review protocol
+    ├── verbosity.md              Always active — MIN/INFO/VERBOSE response rules
+    ├── memory-first.md           Always active — memory → graph → grep → read chain
+    └── agent-delegation.md       Always active — sub-agent spawn rules
+    # ui-ux-pro-max installed from github.com/nextlevelbuilder/ui-ux-pro-max-skill
+```
+
+---
+
+## .gitignore Note
+
+When installed with `--project`, the installer appends `.claude/memory/personal.md` to your project's `.gitignore`. This keeps personal preferences local and out of the shared repo.
+
+---
+
+## 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.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.

package/bin/code-conductor.mjs

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+import { readFileSync, realpathSync } from 'node:fs';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { resolveAssetRoot, resolveHome, nodeMajorAtLeast } from '../lib/installer/env.mjs';
+import { assertAssets, deployGlobal, deployProject, chmodHooks } from '../lib/installer/deploy.mjs';
+import { verbosityHookCommand, mergeVerbosityHook } from '../lib/installer/settings.mjs';
+import { writeVerbosity, seedMemoryFile, writeVersionFile } from '../lib/installer/config.mjs';
+
+const USAGE = `Usage: code-conductor [--project] [--verbosity MIN|INFO|VERBOSE] [--version] [--help]`;
+
+// Hand-rolled parser (four flags only). Deliberately NOT node:util's parseArgs —
+// the CLI honors the zero-runtime-dependency rule and node:util adds no value for
+// this tiny surface, so nothing is imported for argument handling.
+// Conflict policy: flags are LAST-WINS. `--verbosity MIN --verbosity VERBOSE`
+// yields VERBOSE (each match overwrites opts.verbosity); a repeated `--project`
+// is idempotent. No "conflicting flags" error is raised — last-wins is the least
+// surprising CLI convention and keeps the parser branchless.
+function parseArgs(argv) {
+  const opts = { project: false, verbosity: undefined, verbosityGiven: false, version: false, help: false, unknown: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--project') opts.project = true;
+    else if (a === '--verbosity' || a.startsWith('--verbosity=')) {
+      opts.verbosityGiven = true;
+      if (a.startsWith('--verbosity=')) {
+        // Inline form: --verbosity=INFO. Empty (`--verbosity=`) leaves value ''.
+        // Surrounding whitespace (e.g. a quoted `--verbosity= VERBOSE `) is NOT
+        // stripped here — normalizeVerbosity() trims before matching, so whitespace
+        // is tolerated and a whitespace-only/`=`-only value normalizes to null → MIN+warn.
+        opts.verbosity = a.slice('--verbosity='.length);
+      } else {
+        // Space-separated form: consume the next token only if it is a real value,
+        // not another flag or the end of argv (`--verbosity` passed last). A missing
+        // value stays undefined and falls back to MIN + warning in writeVerbosity.
+        const next = argv[i + 1];
+        if (next !== undefined && !next.startsWith('--')) { opts.verbosity = next; i++; }
+      }
+    }
+    else if (a === '--version' || a === '-v') opts.version = true;
+    else if (a === '--help' || a === '-h') opts.help = true;
+    // Unrecognized flags / stray positionals are collected, not fatal: the install
+    // still proceeds (exit 0) but run() emits one stderr warning so typos surface.
+    else opts.unknown.push(a);
+  }
+  return opts;
+}
+
+function pkgVersion(assetRoot) {
+  return JSON.parse(readFileSync(join(assetRoot, 'package.json'), 'utf8')).version;
+}
+
+// log(stream, msg) is injected so tests capture output without spawning a process.
+export function run(argv, env = process.env, { cwd = process.cwd(), log } = {}) {
+  const emit = log || ((stream, msg) => process[stream].write(`${msg}\n`));
+
+  // Hard runtime floor: refuse to run on Node < 20 with a clear message rather than
+  // failing obscurely inside cpSync/ESM later. env.node lets tests inject a version.
+  if (!nodeMajorAtLeast(20, env.node)) {
+    emit('stderr', `code-conductor: Node >=20 required, found ${env.node || process.versions.node}`);
+    return 1;
+  }
+
+  const assetRoot = resolveAssetRoot();
+  const opts = parseArgs(argv);
+
+  if (opts.unknown.length) emit('stderr', `code-conductor: ignoring unrecognized argument(s): ${opts.unknown.join(' ')}`);
+
+  // --help and --version are explicit informational OUTPUT (not diagnostics), so they
+  // go to STDOUT and exit 0 — this lets `code-conductor --version` be captured in a
+  // shell substitution. Only warnings/errors ever go to stderr.
+  if (opts.help) { emit('stdout', USAGE); return 0; }
+  if (opts.version) { emit('stdout', pkgVersion(assetRoot)); return 0; }
+
+  const home = resolveHome(env);
+  if (!home) { emit('stderr', 'code-conductor: cannot resolve home directory (HOME/USERPROFILE unset)'); return 1; }
+
+  // `writing` gates the two exit classes the constraints mandate:
+  //   false → pre-flight/environment failure (missing asset, EROFS/EACCES before
+  //           the first copy) → exit 1;
+  //   true  → any error once a copy has begun is a mid-copy PARTIAL_WRITE → exit 2,
+  //           recoverable by an idempotent re-run.
+  // The flag is a SINGLE gate spanning BOTH deployment tracks: global runs first and
+  // flips it, so by the time --project's deployProject runs, writing is already true.
+  // A mid-copy failure in either track is therefore treated identically (exit 2),
+  // except the two tagged precondition errors (MISSING_ASSET, PROJECT_TARGET_NOT_DIR)
+  // and the environment codes (EROFS/EACCES/EPERM), which are exit 1 regardless.
+  let writing = false;
+  try {
+    assertAssets(assetRoot, ['global', 'skills', 'project-template']); // pre-flight
+    writing = true;                                                    // copy phase begins
+    const claudeDir = deployGlobal(assetRoot, home);
+    chmodHooks(claudeDir);
+    seedMemoryFile(home, 'personal.md', assetRoot);
+    const v = writeVerbosity(home, assetRoot, opts.verbosity, opts.verbosityGiven);
+    if (v.warn) emit('stderr', v.warn);
+    mergeVerbosityHook(join(claudeDir, 'settings.json'), verbosityHookCommand(home));
+    writeVersionFile(home, pkgVersion(assetRoot));
+    if (opts.project) deployProject(assetRoot, cwd);
+    return 0;
+  } catch (err) {
+    // Pre-flight failures (nothing written yet) → exit 1.
+    if (!writing) {
+      if (err.code === 'MISSING_ASSET') emit('stderr', `code-conductor: ${err.message}`);
+      else if (err.code === 'EROFS') emit('stderr', `code-conductor: cannot write to ${err.path} (read-only file system) — remount writable or adjust permissions`);
+      else emit('stderr', `code-conductor: cannot start install: ${err.message}`);
+      return 1;
+    }
+    // Precondition conflict (--project target is a non-directory) → exit 1, not 2:
+    // nothing was partially written for the project, the path is simply unusable.
+    if (err.code === 'PROJECT_TARGET_NOT_DIR') { emit('stderr', `code-conductor: ${err.message}`); return 1; }
+    // Environment errors that surface on the very first write are still exit 1.
+    if (err.code === 'EROFS') { emit('stderr', `code-conductor: cannot write to ${err.path} (read-only file system) — remount writable or adjust permissions`); return 1; }
+    if (err.code === 'EACCES' || err.code === 'EPERM') { emit('stderr', `code-conductor: permission denied writing ${err.path} — fix with chmod/chown`); return 1; }
+    // Any other error mid-copy is a partial write → exit 2 (idempotent re-run repairs it).
+    emit('stderr', `code-conductor: PARTIAL_WRITE at ${err.path || 'unknown path'}: ${err.message} — re-run to complete the partial install`);
+    return 2;
+  }
+}
+
+// Compare as file URLs so a Windows path (C:\...\bin\code-conductor.mjs) matches
+// import.meta.url; naive `file://` + backslash string concat never would. Node's ESM
+// loader sets import.meta.url to the module's REALPATH, so argv[1] must be realpath-
+// resolved too — otherwise a symlinked launch path (npx cache, a global prefix, or
+// macOS /tmp -> /private/var) never matches and the CLI exits 0 doing nothing.
+function invokedDirectly() {
+  const argv1 = process.argv[1];
+  if (!argv1) return false;
+  let resolved;
+  try { resolved = realpathSync(argv1); } catch { resolved = argv1; }
+  return import.meta.url === pathToFileURL(resolved).href;
+}
+if (invokedDirectly()) process.exit(run(process.argv.slice(2)));