cc-codeconductor 0.5.0 → 1.1.0

package/presets/claude/commands/cc/security.md

@@ -0,0 +1,179 @@
+---
+description: >-
+  [cc: alias] Run the authorized defensive security workflow — domain
+  security-* skills, authorization gate, risk-based routing, hardening, and review.
+---
+
+# Defensive Security Workflow
+
+Security objective: $ARGUMENTS
+
+Provide the following information in $ARGUMENTS:
+
+- What must be reviewed or hardened, and why
+- Domain: a `security-*` skill id (recon, vuln-assessment, web, cloud, IR,
+  hunting, GRC, …) or `web-app` / `api` / `cloud-config` /
+  `dependency-supply-chain` / `secrets`
+- Authorization: who authorized this work on this target, and the scope boundary
+- Risk classification (`low`, `medium`, or `high`), if known
+- Scope: which files, modules, repos, or environments are in and out of bounds
+
+---
+
+## Scope and authorization
+
+This workflow performs **authorized defensive security work only**: threat
+modeling, hardening, secure configuration, dependency and supply-chain review,
+secret hygiene, and detection coverage.
+
+Refuse outright and offer the defensive equivalent instead (threat model,
+hardening, detection coverage, dependency audit):
+
+- Exploit or proof-of-concept development
+- Malware authoring, or malware analysis intended for reuse
+- Reverse engineering aimed at bypassing a control
+- Red-team playbooks
+- Any unauthorized-access procedure
+
+Scope is limited to the repository under analysis. Do not scan, probe, or
+perform reconnaissance against third-party hosts.
+
+Do not proceed without an authorization statement. Do not produce exploit
+payloads, malware, or attack procedures.
+
+---
+
+## Step 0 — CCEP Bootstrap
+
+Command: `security` (fixed for this workflow — do not infer from user text)
+
+1. Run: `npx cc-codeconductor ccep parse --command security "$ARGUMENTS" --output json`
+2. Run: `npx cc-codeconductor ccep resolve --command security "$ARGUMENTS" --output json`
+3. Run: `npx cc-codeconductor ccep profile security --output json`
+4. After planner/intake JSON is available, run: `npx cc-codeconductor ccep evaluate --command security --input <planner.json> --output json`. If `stop` is true, show questions or risks and wait for human input.
+5. Delegate to subagents using compiled CCEP prompts — never forward raw `$ARGUMENTS` to planners.
+   Canonical delivery order is test-before-implement whenever both phases apply.
+
+---
+
+## Step 1 — Wayfinding (repo-explorer)
+
+If `graphify-out/graph.json` exists, run `graphify query "$ARGUMENTS"` (and
+`graphify path` / `graphify explain` when needed). Then invoke `repo-explorer`
+to map modules, conventions, and impact radius. Do not write code in this step.
+Record a Repo Map artifact before intake. Load the matching `security-*` skill
+for the named domain (see `.claude/skills/security-*/SKILL.md`). Keep the OWASP
+`security` skill for application-security reviews.
+
+---
+
+## Step 2 — Task Card validation (task-coach)
+
+Invoke `task-coach` with the security objective above.
+
+task-coach must produce a Task Card that includes:
+
+- Objective: what must be reviewed or hardened, in one sentence
+- Domain: which `security-*` skill applies, or `web-app` / `api` /
+  `cloud-config` / `dependency-supply-chain` / `secrets`
+- Authorization: who authorized this work on this target, and the scope boundary
+- Risk classification: `low`, `medium`, or `high`
+- Scope: which files or modules are likely affected
+
+If authorization is absent, unclear, or names a system the requester does not
+own or operate, **STOP and refuse. Do not route the task.**
+
+Redact secrets, tokens, and credentials from any evidence before it enters the
+Task Card. Summarize logs; do not paste env files.
+
+**STOP here. Show the Task Card and wait for human confirmation.**
+
+---
+
+## Step 3 — Route by risk
+
+Read the risk field from the Task Card and follow the corresponding route.
+
+### Low-risk route
+
+Applies when: the weakness is isolated, not exploitable in the current
+configuration, and no authentication, secret, or dependency boundary is
+involved.
+
+Route: `task-coach` → `tester` → `implementer`
+
+Proceed directly to Step 4 (tests), then Step 5a.
+
+### Medium or high-risk route
+
+Applies when: the work touches authentication, authorization, secrets,
+cryptography, trust-boundary input validation, or a dependency upgrade.
+
+Route: `task-coach` → `architect` → `tester` → `implementer` → `reviewer`
+
+Invoke `architect` before implementation. architect must:
+
+- Identify the weakness and the affected trust boundary
+- Define the hardening approach and affected files
+- Flag any regression risk to adjacent components
+- Produce a Technical Plan
+
+On **high** risk, also invoke `security-reviewer` before Reviewer.
+
+**STOP here if high-risk. Show the Technical Plan and wait for human approval
+before continuing.**
+
+---
+
+## Step 4 — Tests (tester)
+
+Invoke `tester` for all risk levels.
+
+tester must:
+
+1. Write a regression test that proves the weakness exists and confirm it fails
+   before any change (RED)
+2. Verify that existing tests still pass
+3. Produce a Coverage Summary: test added, case covered
+
+---
+
+## Step 5a — Implementation, low-risk (implementer)
+
+Invoke `implementer` with the Task Card.
+Implementer creates a Git Worktree before touching any file; all edits happen inside it.
+
+implementer must:
+
+1. Apply the minimal hardening change — no unrelated changes
+2. Run the suite and make the RED regression test pass
+3. Produce an Implementation Summary: weakness, change applied, files changed
+
+---
+
+## Step 5b — Implementation, medium/high-risk (implementer)
+
+Invoke `implementer` with the approved Technical Plan and the Task Card.
+Implementer creates a Git Worktree before touching any file; all edits happen inside it.
+
+implementer must follow the plan exactly. Any deviation requires a new Technical
+Plan approval. After implementation, run the full test suite. No exploit code.
+
+---
+
+## Step 6 — Review (Reviewer role) — medium/high-risk only
+
+Invoke `reviewer` with the diff and Task Card. The Reviewer must apply the OWASP
+rules in the `security` skill.
+
+reviewer produces a Review Report with CRITICAL / WARNING / SUGGESTION findings.
+If any CRITICAL findings exist, **STOP**. Do not close the task until they are
+resolved.
+
+---
+
+## Completion
+
+Report: Task Card, Implementation Summary, regression test added, Review Report
+(if applicable). The task is complete only when: the regression test passes, the
+full suite passes, and no CRITICAL review findings remain.

package/presets/claude/commands/cc/tdd-cycle.md

@@ -18,6 +18,19 @@ Describe what behavior you want to implement. Include:
 
 ---
 
+## Step 0 — CCEP Bootstrap
+
+Command: `tdd-cycle` (fixed for this workflow — do not infer from user text)
+
+1. Run: `npx cc-codeconductor ccep parse --command tdd-cycle "$ARGUMENTS" --output json`
+2. Run: `npx cc-codeconductor ccep resolve --command tdd-cycle "$ARGUMENTS" --output json`
+3. Run: `npx cc-codeconductor ccep profile tdd-cycle --output json`
+4. After planner/intake JSON is available, run: `npx cc-codeconductor ccep evaluate --command tdd-cycle --input <planner.json> --output json`. If `stop` is true, show questions or risks and wait for human input.
+5. Delegate to subagents using compiled CCEP prompts — never forward raw `$ARGUMENTS` to planners.
+   Canonical delivery order is test-before-implement whenever both phases apply.
+
+---
+
 ## Before you begin — mandatory pre-check
 
 This command enforces strict TDD discipline. The three phases are sequential and
@@ -30,13 +43,38 @@ non-negotiable:
 Do not write implementation code during RED. Do not refactor during GREEN.
 Mixing phases invalidates the cycle.
 
+## Verifiable phase gates
+
+RED → GREEN and GREEN → REFACTOR are enforced by `tddCycleStateMachine` in
+`domain/loop`. Evidence must be captured with `captureTddSuiteEvidence` (verification
+runner) — do not hand-edit JSON under `.codeconductor/evidence/`.
+
+- RED→GREEN requires runner evidence that the suite **failed**.
+- GREEN→REFACTOR requires runner evidence that the suite **passed**.
+
+Do not advance phases until that evidence exists.
+
+Each cycle covers a single vertical slice of behavior — one cycle, one
+behavior — and follows red-before-green: RED must complete before GREEN
+starts.
+
 ---
 
 ## Phase 1 — RED (Tester role)
 
 Adopt the **Tester** role as defined in `CLAUDE.md`.
 
-### 1a — Scope clarification
+### 1a — Agree on the seam
+
+Before writing any test, identify and state the seam — the point where the
+behavior under test can be exercised and observed in isolation (a function
+boundary, an interface, an injectable dependency). Confirm the seam does not
+require reaching into implementation internals.
+
+If no seam exists yet (the code is not structured to allow isolated testing),
+say so and agree on the minimal seam to introduce before continuing.
+
+### 1b — Scope clarification
 
 Before writing any test, confirm:
 
@@ -47,7 +85,7 @@ Before writing any test, confirm:
 
 If the scope is ambiguous, ask one clarifying question and wait for the answer.
 
-### 1b — Write the failing test
+### 1c — Write the failing test
 
 Write a test that:
 
@@ -61,7 +99,19 @@ Write a test that:
 Do not write the implementation. Do not make the test pass by any means other
 than the implementation that will follow in Phase 2.
 
-### 1c — Run the test suite and confirm RED
+### 1d — Anti-pattern checklist
+
+Before declaring the test ready, verify none of these anti-patterns apply:
+
+- **Implementation-coupled** — asserts internal details instead of observable
+  behavior.
+- **Tautological** — cannot fail given the test's own setup.
+- **Horizontal slicing** — spans multiple unrelated behaviors instead of one
+  vertical slice.
+
+If any anti-pattern applies, rewrite the test before continuing.
+
+### 1e — Run the test suite and confirm RED
 
 Run the test suite. The new test must fail. Existing tests must pass.
 

package/presets/claude/commands/cc/test-plan.md

@@ -20,6 +20,18 @@ proceeding.
 
 ---
 
+## Step 0 — CCEP Bootstrap
+
+Command: `test-plan` (fixed for this workflow — do not infer from user text)
+
+1. Run: `npx cc-codeconductor ccep parse --command test-plan "$ARGUMENTS" --output json`
+2. Run: `npx cc-codeconductor ccep resolve --command test-plan "$ARGUMENTS" --output json`
+3. Run: `npx cc-codeconductor ccep profile test-plan --output json`
+4. After planner/intake JSON is available, run: `npx cc-codeconductor ccep evaluate --command test-plan --input <planner.json> --output json`. If `stop` is true, show questions or risks and wait for human input.
+5. Delegate to subagents using compiled CCEP prompts — never forward raw `$ARGUMENTS` to planners.
+
+---
+
 ## Step 1 — Scope confirmation
 
 Before generating the test plan, confirm the scope is well-defined.

package/presets/claude/commands/cc/triage.md

@@ -0,0 +1,34 @@
+---
+description: >-
+  [cc: alias] Classify a request into type, risk, and the destination CodeConductor command.
+---
+
+# Triage Workflow
+
+Triage request: $ARGUMENTS
+
+## Step 0 — CCEP Bootstrap
+
+Command: `triage` (fixed for this workflow — do not infer from user text)
+
+1. Run: `npx cc-codeconductor ccep parse --command triage "$ARGUMENTS" --output json`
+2. Run: `npx cc-codeconductor ccep resolve --command triage "$ARGUMENTS" --output json`
+3. Run: `npx cc-codeconductor ccep profile triage --output json`
+4. After planner/intake JSON is available, run: `npx cc-codeconductor ccep evaluate --command triage --input <planner.json> --output json`. If `stop` is true, show questions or risks and wait for human input.
+5. Delegate to subagents using compiled CCEP prompts — never forward raw `$ARGUMENTS` to planners.
+
+---
+
+## Step 1 — Classify (task-coach)
+
+Invoke `task-coach`. Produce: title, type (`feature` | `fix` | `refactor` | `review` | `docs` | `test`), risk, named scope, and the destination command (`feature`, `fix`, `refactor`, `review`, `explore`, …).
+
+Ask one question per unresolved branch. If the human is unavailable, emit a Markdown questionnaire and stop at ConfirmationGate.
+
+**STOP here. Show the classification and wait for confirmation before running the destination workflow.**
+
+---
+
+## Completion
+
+Do not implement. Hand the human a destination slash command and a partial Task Card.

package/presets/claude/gates/pre-commit/GATE.md

@@ -0,0 +1,137 @@
+# Pre-commit Gate: Typecheck, Lint, and Test
+
+Este gate instala un hook `pre-commit` que ejecuta `bun run typecheck`, `bun run lint` y `bun run test` antes de permitir commits en el repositorio. Si cualquiera de estos comandos falla, el commit es bloqueado.
+
+## Cuándo usar
+
+**Para agentes**: Integra este gate en flujos de desarrollo local cuando quieras garantizar que los cambios typecheck correctamente y pasan los tests antes de ser cometidos.
+
+**Para equipos**: Utiliza este gate como barrera de calidad local (sin dependencias externas) para prevenir commits con errores de tipado o tests fallidos.
+
+## Instalación
+
+### Paso 1: Descarga el script
+
+El script está embebido abajo (sección "Script Installer").
+
+### Paso 2: Ejecuta en la raíz de tu proyecto
+
+Desde la raíz del repositorio (o cualquier subdirectorio), extrae el bloque ```bash de este archivo y ejecuta:
+
+    bash << 'SCRIPT_EOF'
+    #!/bin/bash
+    set -e
+    # [contenido del bloque bash de abajo]
+    SCRIPT_EOF
+
+O, más simplemente, guarda el script en un archivo temporal y ejecútalo:
+
+    curl -s https://raw.githubusercontent.com/.../ | bash
+
+### Paso 3: Verifica
+
+Después de la instalación, debería verse:
+
+    Pre-commit hook installed successfully.
+
+## Script Installer
+
+```bash
+#!/bin/bash
+set -e
+
+# Resolver git directory dinámicamente (worktree-safe)
+GIT_DIR=$(git rev-parse --git-dir)
+HOOK_PATH="$GIT_DIR/hooks/pre-commit"
+
+# Detectar Husky o lint-staged en package.json
+if grep -q '"husky"' package.json 2>/dev/null || grep -q '"lint-staged"' package.json 2>/dev/null; then
+  echo "Warning: Husky or lint-staged detected in package.json. Installation skipped."
+  exit 0
+fi
+
+# Verificar si un pre-commit hook ya existe
+if [ -f "$HOOK_PATH" ]; then
+  echo "Warning: Pre-commit hook already exists at $HOOK_PATH. Not overwriting."
+  exit 0
+fi
+
+# Crear directorio hooks si no existe
+mkdir -p "$GIT_DIR/hooks"
+
+# Escribir el hook pre-commit
+cat > "$HOOK_PATH" << 'HOOK_EOF'
+#!/bin/bash
+bun run typecheck || exit 1
+bun run lint || exit 1
+bun run test || exit 1
+HOOK_EOF
+
+# Hacer el hook ejecutable
+chmod +x "$HOOK_PATH"
+
+echo "Pre-commit hook installed successfully."
+```
+
+## Notas de implementación
+
+- **Sin dependencias externas**: El script no instala Husky, lint-staged, ni ninguna otra herramienta. Solo escribe un archivo shell y configura permisos.
+- **Resolución dinámica de git dir**: Usa `git rev-parse --git-dir` para localizar el directorio correcto, incluso en worktrees.
+- **Detección de conflictos**: Si Husky o lint-staged ya está en `package.json`, el script avisa y no instala para evitar conflictos.
+- **Protección de hooks existentes**: Si ya existe un `.git/hooks/pre-commit`, el script no lo sobrescribe.
+- **Solo Bun**: El hook ejecuta `bun run typecheck`, `bun run lint` y `bun run test`. Asegúrate de que estos scripts están definidos en `package.json`.
+
+## Verificación
+
+Después de instalar, verifica que el hook está en su lugar.
+
+Para verificar, ejecuta:
+
+    ls -la .git/hooks/pre-commit
+
+Debe mostrar algo como:
+
+    -rwxr-xr-x  user  group  ... .git/hooks/pre-commit
+
+Luego, intenta hacer un commit. Si hay errores de tipo o tests fallidos, el commit será bloqueado:
+
+    git add .
+    git commit -m "test"
+    # Si typecheck o test falla, verás el error y el commit será abortado.
+
+## Troubleshooting
+
+### "Warning: Pre-commit hook already exists"
+
+Ya hay un hook pre-commit. Revisa su contenido:
+
+    cat .git/hooks/pre-commit
+
+Si quieres reemplazarlo, bórralo y ejecuta el script nuevamente:
+
+    rm .git/hooks/pre-commit
+    bash /path/to/installer
+
+### "Warning: Husky or lint-staged detected"
+
+Tu proyecto usa Husky o lint-staged. Este gate no se instala para evitar conflictos. Si quieres usar este gate, remove Husky/lint-staged de `package.json` y ejecuta de nuevo.
+
+### Hook no se ejecuta al hacer commit
+
+Verifica que el hook es ejecutable:
+
+    chmod +x .git/hooks/pre-commit
+
+Verifica que `bun run typecheck`, `bun run lint` y `bun run test` existen en `package.json`:
+
+    cat package.json | grep -A 5 '"scripts"'
+
+### "command not found: bun"
+
+Bun no está instalado o no está en PATH. Instala Bun desde https://bun.sh o configura PATH adecuadamente.
+
+## Adicional: Desinstalación
+
+Para remover el hook, simplemente bórralo:
+
+    rm .git/hooks/pre-commit

package/presets/claude/settings.json

@@ -2,7 +2,7 @@
   "$schema": "https://json.schemastore.org/claude-code-settings.json",
   "env": {
     "CLAUDE_CODE_ATTRIBUTION_HEADER": "0",
-    "CLAUDE_CODE_DISABLE_1M_CONTEXT": "1",
+    "CLAUDE_CODE_DISABLE_1M_CONTEXT": "0",
     "CLAUDE_CODE_DISABLE_AUTO_MEMORY": "1",
     "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1",
     "CLAUDE_CODE_DISABLE_TERMINAL_TITLE": "1",
@@ -13,7 +13,7 @@
     "CLAUDE_CODE_SIMPLE_SYSTEM_PROMPT": "1",
     "ENABLE_TOOL_SEARCH": "auto",
     "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "80",
-    "CLAUDE_CODE_SUBPROCESS_ENV_SCRUB": "1",
+    "CLAUDE_CODE_SUBPROCESS_ENV_SCRUB": "0",
     "CLAUDE_CODE_SUBAGENT_MODEL": "haiku",
     "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1",
     "MAX_THINKING_TOKENS": "24000",
@@ -85,20 +85,6 @@
       "Bash(docker compose ps*)",
       "Bash(docker compose logs*)",
       "Read(**)",
-      "Write(./src/**)",
-      "Write(./app/**)",
-      "Write(./pages/**)",
-      "Write(./components/**)",
-      "Write(./lib/**)",
-      "Write(./tests/**)",
-      "Write(./test/**)",
-      "Write(./__tests__/**)",
-      "Write(./prisma/**)",
-      "Write(./drizzle/**)",
-      "Write(./public/**)",
-      "Write(./styles/**)",
-      "Write(./scripts/**)",
-      "Write(./docs/**)",
       "Edit(**)",
       "WebFetch(*)"
     ],
@@ -144,34 +130,18 @@
       "Read(~/.ssh/**)",
       "Read(~/.aws/**)",
       "Read(~/.gnupg/**)",
-      "Write(./.env)",
-      "Write(./.env.*)",
-      "Write(./**/.env)",
       "Edit(./.env)",
       "Edit(./.env.*)",
       "Edit(./**/.env)"
     ],
     "ask": [
-      "Bash(git push*)",
       "Bash(git push --force*)",
       "Bash(git reset --hard*)",
-      "Bash(npm install*)",
-      "Bash(npm i *)",
-      "Bash(pnpm install*)",
-      "Bash(pnpm add *)",
-      "Bash(yarn add *)",
-      "Bash(pip install*)",
       "Bash(docker run*)",
       "Bash(docker compose up*)",
-      "Bash(docker compose down*)",
-      "Bash(./gradlew build*)",
-      "Bash(./gradlew bootRun*)",
-      "Bash(mvn install*)",
-      "Bash(mvn deploy*)",
-      "Bash(vercel*)",
-      "Bash(npx vercel*)"
+      "Bash(docker compose down*)"
     ],
-    "defaultMode": "acceptEdits",
+    "defaultMode": "bypassPermissions",
     "disableBypassPermissionsMode": "disable"
   },
   "hooks": {
@@ -200,7 +170,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "if echo \"$CLAUDE_TOOL_INPUT_COMMAND\" | grep -qE '(\\.env|secrets/|id_rsa|\\.pem|\\.key)\\b' && echo \"$CLAUDE_TOOL_INPUT_COMMAND\" | grep -qE '(cat|less|more|head|tail|cp |mv |scp )'; then echo 'Bloqueado: intento de leer archivos sensibles' >&2; exit 2; fi"
+            "command": "if echo \"$CLAUDE_TOOL_INPUT_COMMAND\" | grep -qE '(\\.env|secrets/|id_rsa|\\.pem|\\.key)\\b' && echo \"$CLAUDE_TOOL_INPUT_COMMAND\" | grep -qE '(cat|less|more|head|tail|cp |mv |scp )'; then echo 'Bloqueado: intento de leer archivos sensibles' >&2; exit 2; elif echo \"$CLAUDE_TOOL_INPUT_COMMAND\" | grep -qE '^\\s*git\\s+(push|reset\\s+--hard)' || echo \"$CLAUDE_TOOL_INPUT_COMMAND\" | grep -qE '^\\s*git\\s+clean\\s+(-[a-z]*f[a-z]*|--force)' || echo \"$CLAUDE_TOOL_INPUT_COMMAND\" | grep -qE '^\\s*git\\s+branch\\s+(-D|--delete\\s+--force)' || echo \"$CLAUDE_TOOL_INPUT_COMMAND\" | grep -qE '^\\s*git\\s+checkout\\s+(-f|--force|--discard-changes|--theirs|--ours|-\\s|-$)' || echo \"$CLAUDE_TOOL_INPUT_COMMAND\" | grep -qE '^\\s*git\\s+restore\\s+(-f|--force|--discard-changes|--theirs|--ours)'; then echo \"Bloqueado: El agente no tiene autoridad sobre este comando.\" >&2; exit 2; fi"
           }
         ]
       }
@@ -240,17 +210,9 @@
       "allowLocalBinding": true
     },
     "filesystem": {
-      "denyRead": [
-        "~/.ssh",
-        "~/.aws",
-        "~/.gnupg",
-        "./.env",
-        "./.env.*"
-      ]
+      "denyRead": ["~/.ssh", "~/.aws", "~/.gnupg", "./.env", "./.env.*"]
     },
-    "excludedCommands": [
-      "docker *"
-    ]
+    "excludedCommands": ["docker *"]
   },
   "extraKnownMarketplaces": {
     "agricidaniel-claude-seo": {
@@ -264,7 +226,7 @@
   "feedbackSurveyRate": 0,
   "spinnerTipsEnabled": false,
   "alwaysThinkingEnabled": true,
-  "effortLevel": "xhigh",
+  "effortLevel": "medium",
   "awaySummaryEnabled": false,
   "showClearContextOnPlanAccept": true,
   "autoUpdatesChannel": "stable",

package/presets/claude/skills/backlog/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: backlog
+description: >
+  Author BACKLOG.md and OpenSpec change folders for CodeConductor.
+  Trigger: /cc-backlog, /cc:backlog, creating or appending backlog items,
+  writing BACKLOG.md, or preparing work for /cc-openspec.
+---
+
+# Backlog authoring
+
+Use this skill to **create or append** `BACKLOG.md` and generate OpenSpec
+change docs. Delivery of an existing item is `/cc-openspec` (skill `openspec`).
+
+## BACKLOG.md contract
+
+Canonical template: `presets/templates/BACKLOG.md` (or the installed copy).
+Required sections:
+
+- `## Global` — Product, Strategy, Policy, Review required, TDD required
+- `## Items` — active entries
+- `## Archive` — completed entries (never re-execute; never rewrite)
+
+Each item: `### BC-001 | Short title` with Priority (P0–P3), Status, Type,
+Depends on, Description, Scope, Out of scope, Acceptance (measurable checklist).
+
+Status after grilling: `READY`. `openspec plan` then moves the item to `PLANNED`.
+
+## Create vs append
+
+- **No `BACKLOG.md`:** create it from the template. Set Global `Product` from
+  `package.json` `name` when present.
+- **File exists:** append new `### BC-xxx` blocks under `## Items`. Do not
+  rewrite `## Global` or `## Archive`.
+
+Next ID = max numeric suffix across Items and Archive, plus one, zero-padded
+to three digits (`BC-013` after `BC-012`).
+
+## Wayfinding (before Scope)
+
+If `graphify-out/graph.json` exists, run `graphify query "<objectives>"` (and
+`graphify path` / `graphify explain` when needed). Then invoke `repo-explorer`.
+Scope must name real files or modules. Do not write `BACKLOG.md` in this step.
+
+## Grilling (before write)
+
+Invoke `task-coach`. One grilling question per assumption. Reject vague
+acceptance ("improve UX", "fix bugs"). Criteria must be measurable (same rules
+as `openspec validate` / `VAGUE_ACCEPTANCE`).
+
+Unresolved questions go in `questionsForUser`. Run `ccep evaluate --command
+backlog`. If `stop` is true, **STOP** and wait for the human.
+
+Do not write items until the gate passes.
+
+## Validate loop
+
+After writing:
+
+```bash
+npx cc-codeconductor openspec validate
+```
+
+Local CodeConductor dogfood: `bun run dev openspec validate`.
+
+If invalid: list errors and recommendations, show the canonical structure,
+fix the file, re-validate. Do not plan until valid.
+
+## Plan new items only
+
+For each **new** `BC-xxx` this run:
+
+```bash
+npx cc-codeconductor openspec plan BC-xxx
+```
+
+That writes `openspec/changes/<slug>/` (`proposal.md`, `design.md`, `tasks.md`,
+`specs/`). Then tell the user to run `/cc-openspec` (optionally with the ID).
+
+## Local artifacts — do not version
+
+In consumer projects these paths are gitignored (see `init`):
+
+- `BACKLOG.md`
+- `openspec/`
+- `.codeconductor/openspec-state.json`
+
+Do **not** `git add` them. Do not edit `openspec-state.json` by hand.
+
+## Delivery
+
+Format and state machine: skill `openspec`. Authoring is this skill.

package/presets/claude/skills/openspec/SKILL.md

@@ -2,11 +2,15 @@
 name: openspec
 description:
   OpenSpec backlog format, state machine, and delivery workflow for CodeConductor.
-  Use when running /cc:openspec or editing BACKLOG.md.
+  Use when running /cc:openspec or delivering a BACKLOG.md item.
+  To create or append BACKLOG.md, use /cc:backlog (skill backlog).
 ---
 
 # OpenSpec / BACKLOG Skill
 
+Authoring (create or append `BACKLOG.md`, then `openspec validate` / `plan`) is
+`/cc:backlog` and skill `backlog`. This skill is **delivery**.
+
 ## BACKLOG.md contract
 
 `BACKLOG.md` at repo root is the operational queue. Required sections: