@yeison.restrepo.r/code-conductor 1.23.0

package/global/CLAUDE.md

@@ -0,0 +1,93 @@
+# Global Claude Configuration
+
+Applies to every project on this machine. Project CLAUDE.md adds project-specific overrides on top.
+
+## Workflow
+
+Always follow this sequence. No exceptions.
+
+1. `/cc-spec` — define the problem and wait for approval
+2. `/cc-plan` — map the implementation and wait for approval
+3. Implement — one step at a time, confirm between steps unless told otherwise
+
+Never write code without an approved spec. Never start implementing without an approved plan.
+
+## Token Efficiency
+
+- grep/find before read — never open a file without searching first
+- Never read a full file over 150 lines — use line offsets and limits
+- One tool call, one purpose — no exploratory reads during implementation
+
+## Orchestrator Protocol
+
+Before reading any file or spawning any search, classify the task and walk this chain. Stop at the first step that answers the question.
+
+1. **Memory**: check `.claude/memory/project.md`. If the answer is there, stop.
+2. **Graph** — structural question? Run `graphify query "<question>"` if `graphify` is installed. Stop.
+3. **Grep / Glob** — pattern search? Use `Grep` or `Glob` inline. Stop.
+4. **Explore sub-agent** — need 3+ files to answer one question? Spawn an `Explore` sub-agent. It returns a ≤200-word summary. Main context receives only the summary. Stop.
+5. **Parallel agents** — 2+ independent implementation tasks? Spawn parallel agents in worktrees. Each returns a ≤200-word summary.
+6. **Targeted read** — last resort. Always use `offset` + `limit`. Max 150 lines per call.
+
+Never jump to a later step if an earlier one can answer the question.
+
+## Safety
+
+- Check file exists before creating — use the pre-tool-use hook
+- Confirm before any write or destructive shell command
+- Never hardcode secrets, tokens, passwords, or API keys
+- Never run `rm -rf` without explicit user confirmation
+
+## Simplicity
+
+The code-simplifier skill is always active. Apply its rules to every change:
+
+- No speculative abstractions — solve today's problem only
+- Functions do one thing, max 30 lines
+- Flat over nested — guard clauses and early returns
+- Descriptive names — no Base/Abstract/Generic/Manager/Handler
+- Comments explain why, never what
+
+## Language
+
+- Default: English (responses + code comments + identifiers)
+- Switch: `/cc-lang [code]` changes response language for the session
+- Code identifiers, file names, and commit messages are always English
+- Supported codes: en es pt fr de it zh ja ko
+
+## Stack Detection
+
+Auto-run `/cc-stack` at the start of every session. It runs the dynamic detector and records the stack in the project `CLAUDE.md`. If a stack is already recorded, it asks whether anything changed before re-detecting.
+
+## Memory
+
+- `project.md` — in git, shared with the team. Decisions, conventions, debt, workarounds.
+- `personal.md` — local only, never committed. Developer preferences, personal shortcuts.
+- Run `/cc-checkpoint` before `/compact`, after feature completion, after key architectural decisions.
+
+## Delegation
+
+- Use Superpowers for isolated, parallelizable sub-tasks
+- Use Playwright MCP for visual debugging and E2E tests
+- Always confirm scope before spawning sub-agents
+
+## Response Format
+
+Always tag responses:
+
+- `[CHANGES]` — list of files changed and what changed
+- `[BUG]` — bug report with file:line reference
+- `[PLAN]` — ordered implementation steps
+- `[REASON]` — explanation of a decision or approach
+
+## Active Skills
+
+- `code-simplifier` — always active, loaded automatically
+- `ui-ux-pro-max` — activate via `/cc-stack` when frontend frameworks are detected
+- `verbosity` — always active; reads level from `memory/verbosity.md` (default: MIN)
+- `memory-first` — always active; enforces the orchestrator lookup chain
+- `agent-delegation` — always active; governs when and how to spawn sub-agents
+
+## Loaded Profiles
+
+`/cc-stack` detects your stack dynamically and writes the detected commands and a generated ruleset into the project `CLAUDE.md`. Never apply one language's conventions to another.

package/global/commands/cc-checkpoint.md

@@ -0,0 +1,50 @@
+---
+description: "(Conductor) Save session decisions, conventions, and debt to memory"
+---
+
+Read the conversation history from the current session.
+
+Identify and extract:
+1. **Decisions made** — architectural choices, approach selections, rejected alternatives
+2. **Conventions established** — naming patterns, file organization, code style choices
+3. **Technical debt** — shortcuts taken, known limitations, deferred work
+4. **Workarounds** — non-obvious solutions and why they were needed
+
+**Update `.claude/memory/project.md`** (append only, never delete):
+- Add a timestamped section: `## Checkpoint [YYYY-MM-DD HH:MM]`
+- List decisions, conventions, and debt from this session
+
+**Update `.claude/memory/personal.md`** (local only):
+- Add any developer preferences observed this session
+
+**Report:**
+- Timestamp of this checkpoint
+- What was saved to project.md (2–3 bullets)
+- What was saved to personal.md (1–2 bullets)
+
+Suggest running `/cc-checkpoint` automatically: before `/compact`, after completing a feature, after any key architectural decision.
+
+---
+
+## Fail-open DB tail (best-effort, synchronous)
+
+Run **only after** the `project.md` append succeeded (authoritative). Any failure here is non-fatal — never block or revert the `project.md` update.
+
+1. Ensure `.conductor/` exists (`mkdir -p .conductor`, best-effort); if that fails, skip the tail.
+2. Derive `c` — the **full-40** `git rev-parse HEAD` (lowercased, `/^[0-9a-f]{7,40}$/`, `"0000000"` fallback on non-zero/timeout/git-absent/format-mismatch; shell `timeout` only if the binary exists).
+3. Resolve the id: `id="$(node scripts/session-id.mjs 2>>.conductor/last-write.log)"`.
+4. Derive `ph` by carry-forward: with a bounded ~5 s outer timeout (only if `timeout` exists; `conductor-db`'s internal 2 s `busy_timeout` bounds real contention otherwise), run `node <probe-flags> scripts/conductor-db.mjs get-session "$id"`; if it prints a row whose `phase` is a non-empty enum member, reuse it. On no row, empty phase, DB unavailable, or timeout, default to `"impl"`.
+5. Set `pr` to the **verbatim `## Checkpoint …` section body** just appended to `project.md` (the same in-context string) — so `project.md` and the snapshot's `pr` are byte-identical. `pr` is always non-empty here, so the blob is always **v2**.
+6. Project `d` / `x` from that section (best-effort): match headings `/^#{2,4}[ \t]+(.+?)[ \t]*$/`; normalize the heading text by removing all `*`, `_`, `` ` `` then `.trim()` + lowercase; a heading containing `decision` or `convention` opens a `d` block, one containing `debt`, `workaround`, or `limitation` opens an `x` block. **The `d` set is tested first and wins** (a heading matching both opens one `d` block). The parent `## Checkpoint …` heading matches no keyword, so it opens no block and closes any open one. Within a block, bullet lines `/^[ \t]*[-*][ \t]+(\S.*?)[ \t]*$/` contribute their trimmed capture (line-based; continuation lines ignored — the full text survives in `pr`). If unstructured, `d`/`x` may be empty (valid).
+7. Defaults: `n=[]`, `f=[]`, `s`= the active spec stem or `"none"`.
+8. Build the v2 blob: pipe `{ph, c, s, n, f, d, x, pr}` on **stdin** to `node scripts/snap-build.mjs`; capture its stdout. If it exits non-zero, skip the DB write (fail-open).
+9. Write the rows (both argv double-quoted; blob on stdin; all output to the log):
+
+   `node <probe-flags> scripts/conductor-db.mjs session "$id" "$ph" "$s" "$c" >> .conductor/last-write.log 2>&1`
+   `printf '%s' "$snap_json" | node <probe-flags> scripts/conductor-db.mjs snapshot "$c" >> .conductor/last-write.log 2>&1`
+
+All DB-tail redirects use **append mode (`>>`)** so concurrent runs never truncate a preceding trace. **Cross-platform note:** the forms above are Unix-canonical; on Windows/PowerShell realize the same semantics — set `$OutputEncoding = [System.Text.UTF8Encoding]::new($false)` before piping, capture `$id = node …`, pipe `$snap_json | node … snapshot "$c"`, append the log via `… 2>&1 | Out-File -Append -Encoding utf8 .conductor/last-write.log` (not `*>>`), and `New-Item -ItemType Directory -Force .conductor`.
+
+**No checkpoint post-hook needed (fail-open, no orphaned state):** unlike `/cc-compact`, `/cc-checkpoint` does not clear history, so no `post-compact` hook fires after it — and none is needed. A mid-tail failure leaves no stale telemetry to clean: the session id is unchanged (same env-var session), a partial write (session ok / snapshot fail, or vice-versa) is **accepted** — ARCH-008-B tolerates each miss independently with no rollback — and the only temp file (`session-id.*.tmp`) is cleaned by `session-id.mjs` itself and swept at the next compaction boundary (T-006). Adding a dedicated checkpoint cleanup hook would be YAGNI.
+
+Report the checkpoint as usual regardless of the tail's outcome.

package/global/commands/cc-compact.md

@@ -0,0 +1,49 @@
+---
+description: "(Conductor) Serialize phase state and prompt for context compaction"
+---
+
+Run `git rev-parse HEAD` to get the current commit SHA (the **full 40-char** hash — NOT `--short`, whose abbreviation length auto-scales with repo size and is unstable across growth). Lowercase and trim it; if it does not match `/^[0-9a-f]{7,40}$/`, or the command exits non-zero (non-git workspace, no commits, git absent, or permission-denied), use `"0000000"`. Wrap the call with shell `timeout` only when `command -v timeout` (or `gtimeout`) succeeds; otherwise run it unwrapped. This same value is `sys.c` and the `sessions` / `snapshots` git-hash key.
+
+Determine `sys.s`: take the active specification file path from this phase's context, split on `/` and `\`, keep the last segment, strip a trailing `.md` extension, truncate to 200 characters. If no active spec file exists, use `"none"`.
+
+Collect from the current conversation context:
+- **Phase** (`sys.ph`): `spec` | `plan` | `impl` | `rev`, the phase that just completed
+- **Decisions** (`mem.d`): finalized decisions this phase, max 10 elements, each ≤300 chars (JSON-serialized length)
+- **Pending** (`ops.n`): next immediate step(s), max 3 elements, each ≤200 chars
+- **Files Touched** (`ops.f`): each entry `<relpath>:C|M|D` (uppercase only); replace any backslash in the path with `/`; if the path contains a literal `:`, percent-encode it as `%3A` before appending the suffix; max 20 elements, each ≤300 chars
+- **Constraints** (`mem.x`): hard constraints next phase must respect, max 5 elements, each ≤200 chars
+
+For all four array fields: filter out empty/whitespace-only strings, deduplicate by exact case-sensitive string equality (first occurrence wins), then truncate each surviving element to its per-element cap (Unicode-safe: `Array.from(str).slice(0, cap).join('')`), then if the array still exceeds its cap, drop from the **head** (oldest first) until it fits. Empty arrays are valid and must still be serialized (never omitted).
+
+Serialize by piping a flat JSON object `{ph, c, s, n, f, d, x}` (no `pr`) on **stdin** to `node scripts/snap-build.mjs`; its stdout is the canonical single-line **v1** SNAP JSON. `snap-build` performs all array normalization (filter/dedup/per-element cap/head-drop) and the 4096-char size trim internally — do not pre-serialize. If `snap-build` exits non-zero (malformed field object), report the error and stop; do not write the handoff file, do not run the DB tail, do not print the compact prompt.
+
+Write the single JSON line, followed by exactly one trailing newline, to `.claude/memory/session-snapshot.json`.
+
+If `.claude/memory/session-snapshot.md` exists, delete it as part of this write.
+
+Idempotently append `.claude/memory/session-snapshot.json` to the project's `.gitignore`: read the file; if any line, after stripping leading/trailing whitespace, exactly equals `.claude/memory/session-snapshot.json`, skip the append. Otherwise, check whether the last byte of `.gitignore` is a newline; if not, prepend a newline before the appended entry. If `.gitignore` cannot be read or written (permission or lock error), log a non-fatal warning to stderr and continue; do not block the snapshot write.
+
+If writing the snapshot fails (e.g., missing `.claude/memory/` directory), report the error and stop. Do NOT output the compact prompt.
+
+Once the snapshot is written successfully, output exactly:
+
+> Snapshot written. Run `/compact` now to clear history.
+
+---
+
+## Fail-open DB tail (best-effort, synchronous)
+
+After the handoff file is written and the compact prompt is ready — and **only** if the authoritative write succeeded — run this synchronous, fail-open tail. Any failure here is non-fatal: never revert the handoff file, never suppress the compact prompt.
+
+1. Ensure `.conductor/` exists (`mkdir -p .conductor`, best-effort). If that fails, skip the tail entirely.
+2. Resolve the session id: `id="$(node scripts/session-id.mjs 2>>.conductor/last-write.log)"`.
+3. Upsert the session row (Node-flag probe applies — same as the cc-implement Step 6 hook: no-flag-first, else `--experimental-sqlite --no-warnings`, else skip):
+
+   `node <probe-flags> scripts/conductor-db.mjs session "$id" "$ph" "$s" "$c" >> .conductor/last-write.log 2>&1`
+4. Insert the snapshot row, piping the v1 blob on **stdin** (never argv):
+
+   `printf '%s' "$snap_json" | node <probe-flags> scripts/conductor-db.mjs snapshot "$c" >> .conductor/last-write.log 2>&1`
+
+All argv scalars are double-quoted. **Every** DB-tail redirect uses **append mode (`>>`)** — never `>` — so a rapid or parallel second run never truncates a preceding trace; the log is gitignored, best-effort, and per-run growth is one line at most (rotation is out of scope). The lone `CONDUCTOR_DB:` degradation line (Node < 22.5 / `node:sqlite` absent) lands only in `.conductor/last-write.log`, never the UI. Finally print `> Snapshot written. Run /compact now to clear history.` regardless of the tail's outcome.
+
+**Cross-platform note:** the incantations above are the **Unix (bash) canonical form**; the `.md` file is an agent instruction, not a literal script — realize the same semantics on the host shell. On Windows/PowerShell: **first set `$OutputEncoding = [System.Text.UTF8Encoding]::new($false)`** (no-BOM UTF-8, so the piped snapshot string reaches Node's UTF-8 `TextDecoder` byte-clean); capture the id via `$id = node scripts/session-id.mjs`; pipe the blob with `$snap_json | node … snapshot "$c"`; append the log with `… 2>&1 | Out-File -Append -Encoding utf8 .conductor/last-write.log` (explicit UTF-8 append — never the bare `*>>`, whose default encoding is UTF-16LE on PS 5.1 and would corrupt the trace); ensure the dir with `New-Item -ItemType Directory -Force .conductor`. The stdin-only-for-payloads, double-quoted-argv, append-log, and fail-open rules are identical on both platforms.

package/global/commands/cc-lang.md

@@ -0,0 +1,32 @@
+---
+description: "(Conductor) Switch response language for this session"
+---
+
+Switch the response language for this session.
+
+**With argument** (`/lang es`, `/lang pt`, etc.):
+- Switch immediately to the requested language
+- Confirm in the new language (e.g., "Idioma cambiado a Español. ¿En qué puedo ayudarte?")
+- Scope: responses and code comments only
+- Never change: identifiers, file names, commit messages, branch names
+
+**Without argument** (`/lang`):
+Show current setting and list available codes:
+
+| Code | Language    |
+|------|-------------|
+| en   | English     |
+| es   | Spanish     |
+| pt   | Portuguese  |
+| fr   | French      |
+| de   | German      |
+| it   | Italian     |
+| zh   | Chinese     |
+| ja   | Japanese    |
+| ko   | Korean      |
+
+**Priority hierarchy:**
+1. Session setting (this command) — highest
+2. Project CLAUDE.md `language:` setting
+3. `personal.md` `response_language:` value
+4. Default: English

package/global/commands/cc-stack.md

@@ -0,0 +1,69 @@
+---
+description: "(Conductor) Detect the project stack and write commands + a generated ruleset into CLAUDE.md"
+---
+
+Detect the project stack dynamically and record it in the project's root `CLAUDE.md`. Do not pattern-match manifest files by hand and do not load any static profile; the detector owns detection.
+
+## 1. Resolve the repository root
+
+Run `git rev-parse --show-toplevel`. If it fails (not a git repo), fall back to the directory that contains `scripts/detect-stack.mjs`. Run every command below from that root, and treat the root-level `CLAUDE.md` as the only write target regardless of the user's current subdirectory.
+
+## 2. Verify Node is available
+
+Probe with `node --version`. If it exits non-zero or reports "not found", stop the write path: announce in one line `No stack detected (Node not found on PATH; Node >= 18 recommended)` and leave `CLAUDE.md` untouched.
+
+## 3. Run the detector
+
+Run `node scripts/detect-stack.mjs` from the repo root, capture stdout, and parse it as JSON. Nothing executes the JSON; consume it as data.
+
+Treat all of the following identically as "no stack detected" - announce it in one line and leave `CLAUDE.md` unmodified (surface stderr if any, but it is non-fatal):
+- non-zero exit code,
+- empty stdout,
+- stdout that does not parse as JSON,
+- a parsed object equal to `{}`.
+
+## 4. Read CLAUDE.md and branch
+
+If the root `CLAUDE.md` does not exist, do not create it: instruct the user to run `/cc-init` and stop.
+
+Otherwise read `CLAUDE.md` and look for the `- Stack:` line under `## Project Identity`:
+- **Stack line present and non-empty** -> ask: `I see you're using [stack]. Has anything changed?` This is a blocking yes/no prompt with no timeout.
+  - `no` -> acknowledge in one line and stop; make no edits.
+  - `yes`, or free text describing a change -> re-run the detector (step 3) and rewrite the managed sections from the fresh output. Free text is an additive hint only: fold user-named tools the detector missed into the ruleset, but detected facts always win on conflict.
+- **`## Project Identity` missing, or present without a `- Stack:` line** -> treat as "no recorded stack" (not an error). Proceed to the write path; append the `## Project Identity` header if absent, or surgically insert the `- Stack:` line if only that line is missing. Note in one line that a fresh stack identity was recorded.
+
+## 5. Write path
+
+Detect and preserve `CLAUDE.md`'s dominant EOL style (LF or CRLF); never convert wholesale. If the OS denies the write or the file is locked, abort that write with a single-line error naming the path and cause (e.g. `ERROR: cannot write CLAUDE.md: permission denied - no changes applied`), leave the file byte-for-byte untouched, and still report the detection result.
+
+### 5a. Development Commands (per-field surgical edits, BUG-015 pattern)
+
+For each of `Build`, `Test`, `Lint`, `Format`, `Setup`, if the detector JSON has a non-empty string for the matching key (`build`, `test`, `lint`, `format`, `setup`), replace that single line under `## Development Commands` with `- <Label>: <value>`. Edit one field line at a time (BUG-003). If a key is absent, leave the existing placeholder (e.g. `<command>` or `N/A`) unchanged - never fabricate a command. Also set the `- Stack:` line under `## Project Identity` from the `stack` key (or record the stack name derived from detection). If `## Development Commands` is absent, append the header and its five fields at the end of the file.
+
+### 5b. Active Stack Profiles (whole-block regeneration)
+
+Regenerate the entire body between the `## Active Stack Profiles` header and the next `##` (or end of file). If the header is absent, append it at the end of the file - never insert mid-document. The block is bounded and its prior content is fully replaced, not merged; all content outside it is preserved verbatim.
+
+Open the block with this sentinel line (colon separator, no em dash):
+
+    <!-- cc-stack:managed: regenerated by /cc-stack, manual edits inside are overwritten -->
+
+Then synthesize a concise ruleset from the detected stack(s):
+- One `### <stack>` subsection per distinct detected stack, in detector output order, each owning its own bullet list.
+- Secondary JSON properties (`packageManager`, `monorepo`, and any other non-command key) are optional inputs to the ruleset only - they are never `## Development Commands` fields. Emit a bullet for one only when its value is a non-empty string. If a key is absent, `null`, empty, or whitespace-only, omit its bullet entirely - never write a placeholder such as `null`, `<packageManager>`, or `N/A` for it, and never fabricate a value. This mirrors the BUG-015 fill guard (`typeof val !== 'string' || !val.trim()` is skipped).
+- For a monorepo, when `monorepo` is a non-empty string record the monorepo tool (pnpm/nx/melos/turbo) once as a single top-level bullet above the per-stack subsections; when it is null/empty/absent, write no monorepo bullet.
+- When `packageManager` is a non-empty string, it may inform one identity bullet (per trim keep-priority 2); when null/empty/absent, omit it.
+- Bullets are imperative, project-agnostic conventions grounded strictly in the detected stack (language, framework, package manager, test/lint tooling). No tutorials, no version-specific advice, no speculation about code not present. Match the tone of existing `CLAUDE.md` convention bullets. Prose paragraphs are disallowed.
+- Write the ruleset prose in the project language from the `- Language:` line (fallback: global `/cc-lang`, default `en`). Code identifiers, commands, and file names stay English.
+
+Enforce these hard caps; if synthesis would exceed any of them, trim lowest-value bullets first:
+- <= 8 bullets and <= 200 words per stack,
+- <= 500 words total across the whole block,
+- <= 2500 characters for the whole block,
+- <= 120 characters per bullet.
+
+Trim keep-priority (keep highest first): (1) build/test/lint/format command correctness, (2) package-manager + monorepo-tool identity, (3) primary language/framework conventions. Drop first: (a) generic stack-agnostic advice, (b) optional tooling niceties, (c) bullets already implied by a recorded command. Ties break toward the earlier-listed detected stack.
+
+## 6. Announce
+
+State the detected stack(s) in one line, name each managed section you regenerated, and note that prior managed content is recoverable from git history.

package/global/hooks/graphify-ast-refresh.py

@@ -0,0 +1,81 @@
+#!/usr/bin/env python3
+"""UserPromptSubmit hook: runs detect + AST extraction in background when graph is stale."""
+import os
+import sys
+import subprocess
+import platform
+import time
+from pathlib import Path
+
+try:
+    STALE_MINUTES = int(os.environ.get("GRAPHIFY_STALE_MINUTES", "60"))
+except ValueError:
+    STALE_MINUTES = 60
+
+AST_SCRIPT = """
+import json, sys
+from pathlib import Path
+from graphify.detect import detect
+from graphify.extract import collect_files, extract
+
+out = Path("graphify-out")
+
+try:
+    result = detect(Path("."))
+    code = result.get("files", {}).get("code", [])
+    if not code:
+        sys.exit(0)
+
+    out.mkdir(exist_ok=True)
+    (out / ".graphify_detect.json").write_text(json.dumps(result))
+
+    code_files = []
+    for f in code:
+        p = Path(f)
+        code_files.extend(collect_files(p) if p.is_dir() else [p])
+
+    if code_files:
+        ast_result = extract(code_files)
+        (out / ".graphify_ast.json").write_text(json.dumps(ast_result))
+
+    (out / ".graphify_ast_done").write_text("")
+except Exception:
+    pass
+"""
+
+
+def is_fresh(cwd: Path) -> bool:
+    sentinel = cwd / "graphify-out" / ".graphify_ast_done"
+    if not sentinel.exists():
+        return False
+    age_minutes = (time.time() - sentinel.stat().st_mtime) / 60
+    return age_minutes < STALE_MINUTES
+
+
+def main() -> None:
+    cwd = Path.cwd()
+
+    if is_fresh(cwd):
+        sys.exit(0)
+
+    try:
+        import graphify  # noqa: F401
+    except ImportError:
+        sys.exit(0)
+
+    kwargs: dict = {
+        "stdin": subprocess.DEVNULL,
+        "stdout": subprocess.DEVNULL,
+        "stderr": subprocess.DEVNULL,
+        "env": os.environ.copy(),
+    }
+    if platform.system() == "Windows":
+        kwargs["creationflags"] = subprocess.CREATE_NO_WINDOW
+    else:
+        kwargs["start_new_session"] = True
+
+    subprocess.Popen([sys.executable, "-c", AST_SCRIPT], cwd=str(cwd), **kwargs)
+
+
+if __name__ == "__main__":
+    main()