cc-codeconductor 0.4.3 → 1.0.0

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

@@ -0,0 +1,44 @@
+---
+description: >-
+  [cc: alias] Compact the session into gitignored `.codeconductor/sessions/handoff.md` (redact secrets).
+---
+
+# Handoff Workflow
+
+Handoff request: $ARGUMENTS
+
+## Step 0 — CCEP Bootstrap
+
+Command: `handoff` (fixed for this workflow — do not infer from user text)
+
+1. Run: `npx cc-codeconductor ccep parse --command handoff "$ARGUMENTS" --output json`
+2. Run: `npx cc-codeconductor ccep resolve --command handoff "$ARGUMENTS" --output json`
+3. Run: `npx cc-codeconductor ccep profile handoff --output json`
+4. After planner/intake JSON is available, run: `npx cc-codeconductor ccep evaluate --command handoff --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 — Compact (docs)
+
+Invoke `docs`. Write **only** `.codeconductor/sessions/handoff.md` (gitignored).
+Do not write `.codeconductor/handoff.md` or any tracked path.
+
+Before writing, redact secrets, tokens, API keys, passwords, connection strings,
+`.env` contents, and log/stack-trace lines that embed those values. Summarize
+errors instead of pasting dumps. If unresolved credential material remains, stop
+and wait for a human (CCEP `stopOnHighRisk`).
+
+Include: goal, Task Card status (no secret fields), files touched, test
+pass/fail (not log dumps), open questions, the next `/cc:` command, and the
+recommended `context_scope` (`isolated` | `continuation` | `full`) for the next
+session — derived from the Task Card status above, not invented, with a
+one-sentence justification.
+
+Do not edit source or tests.
+
+---
+
+## Completion
+
+Report the handoff path. Another session should be able to continue from that file alone.

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

@@ -0,0 +1,132 @@
+---
+description: >-
+  [cc: alias] Run the advanced iterative workflow — Wayfinding AST discovery,
+  Relentless Grilling, contract and spec design, TDD, council review, and docs.
+---
+
+# Advanced Iterative Workflow
+
+Iterative request: $ARGUMENTS
+
+---
+
+## Step 0 — CCEP Bootstrap
+
+Command: `iterative` (fixed for this workflow — do not infer from user text)
+
+1. Run: `npx cc-codeconductor ccep parse --command iterative "$ARGUMENTS" --output json`
+2. Run: `npx cc-codeconductor ccep resolve --command iterative "$ARGUMENTS" --output json`
+3. Run: `npx cc-codeconductor ccep profile iterative --output json`
+4. After planner/intake JSON is available, run: `npx cc-codeconductor ccep evaluate --command iterative --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 role)
+
+If `graphify-out/graph.json` exists, run `graphify query "$ARGUMENTS"` (and
+`graphify path` / `graphify explain` when two modules or one concept need a
+scoped subgraph). Then adopt the **Repo Explorer** role as defined in
+`CLAUDE.md` with that graph output.
+
+Map directory trees, conventions, god nodes, and affected modules. Do not write
+code in this step. Write a short phase handoff (scope, files, open questions)
+before the next phase — do not chain agents on unspoken context.
+
+---
+
+## Step 2 — Relentless Grilling & Task Card (Task Coach role)
+
+Adopt the **Task Coach** role as defined in `CLAUDE.md`.
+
+Produce a complete Task Card. The Task Card is ready when it contains: title,
+type, risk classification, scope, context, acceptance criteria, and
+constraints, and every assumption behind it has survived one grilling
+question (Grilling protocol).
+
+If any field is missing or ambiguous, ask one clarifying question at a time and
+wait for the answer. Do not proceed with an incomplete Task Card.
+
+**STOP here.** Unresolved grilling questions or missing fields populate
+`questionsForUser` in the CCEP-1 `planner-output`; the `ConfirmationGate`
+(`ccep evaluate`) reads that field and halts the workflow until a human
+answers. Show the completed Task Card and wait for that confirmation before
+continuing.
+
+---
+
+## Step 3 — Contract & Technical Plan (Architect role)
+
+Adopt the **Architect** role as defined in `CLAUDE.md`. Define contracts first,
+then the Technical Plan.
+
+1. Define API contracts, JSON Schemas, or TypeScript interfaces.
+2. Formulate the Technical Plan (chosen approach, affected files, trade-offs).
+3. Apply YAGNI, Simplicity First, and Stdlib-First.
+
+**STOP here. Show the Technical Plan and wait for explicit human approval. Do
+not proceed to tests until the plan is approved.**
+
+---
+
+## Step 4 — Test coverage (Tester role)
+
+Adopt the **Tester** role as defined in `CLAUDE.md`.
+
+1. Write or extend failing tests for the new behavior before implementation (RED).
+2. Ensure all acceptance criteria from the Task Card have at least one test.
+3. Produce a Test Report: test files added or modified, cases covered.
+
+---
+
+## Step 5 — Implementation (Implementer role)
+
+Adopt the **Implementer** role as defined in `CLAUDE.md`.
+
+Use the approved Technical Plan, contracts, and the failing tests.
+Create a Git Worktree before touching any file; all edits happen inside it.
+
+1. Read the Technical Plan before touching any file.
+2. Apply the minimal diff — only what the plan specifies.
+3. Run the project test suite and make the previously written failing tests pass.
+4. If tests fail, run up to 3 repair cycles (Implementer → Tester).
+5. Produce an Implementation Summary: what changed, which files, how to verify
+   locally.
+
+---
+
+## Step 6 — Multi-Perspective Council Review
+
+Invoke the `council` skill on the generated diff (`council-review` phase).
+
+The council evaluates Architecture, Security, Product, Delivery, DataOps, and
+Devil. `security-reviewer` may set `securityVeto: true`; that REJECTED verdict
+overrides majority consensus.
+
+If ANY agent votes CRITICAL:
+- The Review Report status is **BLOCKED**.
+- Return to Step 5 with the feedback.
+
+If APPROVED (no CRITICAL findings), continue.
+
+---
+
+## Step 7 — Documentation (Docs role)
+
+Adopt the **Docs** role as defined in `CLAUDE.md` when a public API, public
+module, or user-visible behavior changed.
+
+Update: README (if applicable), OpenAPI spec (if applicable), CHANGELOG
+(always when implementation changed), ADR (if an architectural decision was
+made).
+
+If `graphify-out/` is in use, run `graphify update .` (AST-only).
+
+---
+
+## Completion
+
+The iterative workflow is complete only when: all tests pass, the council
+approves the spec and the diff, no CRITICAL findings remain, and documentation
+and the knowledge graph reflect the implemented behavior.

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

@@ -0,0 +1,169 @@
+---
+description: >-
+  [cc: alias] Run OpenSpec backlog delivery — validate BACKLOG.md, plan TaskCards,
+  orchestrate agents by phase, review gate, and update backlog state.
+---
+
+# OpenSpec Backlog Workflow
+
+Scope: $ARGUMENTS
+
+Orchestrate FIFO delivery from `BACKLOG.md`. CodeConductor owns planning; agents execute one TaskCard per phase with the installed preset model for each role.
+
+---
+
+## Planning Principles — tracer bullet and blocking edges
+
+A **tracer bullet** is a vertical slice of work: one `BC-NNN` backlog item that goes discover → design → test → implement → review and produces a demoable result, sized to fit inside a single agent's context window without needing an intermediate `/clear`.
+
+**Quantitative heuristic**: a tracer bullet must fit within a maximum of 5 acceptance criteria and the 5 canonical phases (discover, design, test, implement, review) per context window. If an item needs more, split it into multiple `BC-NNN` items linked by `Depends on` instead of growing one tracer bullet past that budget.
+
+**Equivalence**: one `BC-NNN` item equals one tracer bullet equals one or more TaskCards. `cc openspec plan <BC-id>` generates the TaskCards (discover/design/test/implement/review) that implement that item's tracer bullet — each BC-NNN item corresponds to exactly one tracer bullet.
+
+**Blocking edges**: the `Depends on` field between `BC-NNN` items expresses a blocking dependency — an item cannot be selected in Step 2 until every item in its `Depends on` list is `DONE`. `Depends on` is the sole mechanism for sequencing tracer bullets; there is no separate edge syntax.
+
+---
+
+## Step 0 — Validate (mandatory gate)
+
+Run:
+
+```bash
+npx cc-codeconductor openspec validate
+```
+
+If validation fails:
+
+1. List all errors and recommendations from the CLI output.
+2. Show the canonical BACKLOG.md structure (## Global, ## Items, ### BC-001 | Title, Priority, Status, Type, Depends on, Description, Scope, Acceptance).
+3. **STOP.** Do not scan, plan, or execute until the user fixes BACKLOG.md.
+
+---
+
+## Step 0 — CCEP Bootstrap
+
+Command: `openspec` (fixed for this workflow — do not infer from user text)
+
+1. Run: `npx cc-codeconductor ccep parse --command openspec "$ARGUMENTS" --output json`
+2. Run: `npx cc-codeconductor ccep resolve --command openspec "$ARGUMENTS" --output json`
+3. Run: `npx cc-codeconductor ccep profile openspec --output json`
+4. After planner/intake JSON is available, run: `npx cc-codeconductor ccep evaluate --command openspec --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 — Scan
+
+Run:
+
+```bash
+npx cc-codeconductor openspec scan
+```
+
+Report: new items, modified items, closed/archived items, and whether the file changed.
+
+---
+
+## Step 2 — Select item
+
+If `$ARGUMENTS` contains a `BC-xxx` ID, use that item. Otherwise run:
+
+```bash
+npx cc-codeconductor openspec status
+```
+
+Pick the next `READY` item with satisfied dependencies (FIFO by priority). Skip items in `DONE` or `Archive`.
+
+**STOP if no eligible item.** Report backlog status and wait for the user.
+
+---
+
+## Step 3 — Plan
+
+Run:
+
+```bash
+npx cc-codeconductor openspec plan <BC-id>
+```
+
+Show:
+
+- Generated TaskCards (discover → design → test → implement → review when TDD required)
+- Path to `openspec/changes/<slug>/` (proposal, design, tasks, specs)
+
+Update BACKLOG item status to `PLANNED` (CLI does this automatically).
+
+---
+
+## Step 4 — Model matrix and execute loop
+
+Before executing phases, show resolved models:
+
+```bash
+npx cc-codeconductor scorecard models
+```
+
+For each pending TaskCard, run:
+
+```bash
+npx cc-codeconductor openspec next
+```
+
+Invoke the agent named on the card with **isolated** context (`/clear` between phases unless continuation is required):
+
+| Phase | Agent | Role |
+|-------|-------|------|
+| discover | repo-explorer | Map repo and impact |
+| design | architect | Technical plan |
+| test | tester | TDD tests (before implement if TDD required) |
+| implement | implementer | Minimal diff in worktree |
+| review | reviewer | Acceptance + scope gate |
+
+Use the model configured in the installed preset for each agent role.
+
+After each phase:
+
+- Mark progress in deliverable summary.
+- Set TaskCard status to `done` in `.codeconductor/openspec-state.json` when phase completes.
+
+Implementer: create a Git worktree before editing (`git worktree add ../<branch>-session <branch>`).
+
+---
+
+## Step 5 — Review gate
+
+Run regression when BACKLOG Global `Review required: yes`:
+
+```bash
+npx cc-codeconductor scorecard regression
+```
+
+The `reviewer` agent must verify:
+
+- All acceptance criteria from BACKLOG.md
+- Tests pass
+- Scope matches the backlog item
+- No architectural violations
+
+If **rejected**: set item status `IN_PROGRESS`, record findings in state, **STOP** and report to user.
+
+If **approved**: proceed to Step 6.
+
+---
+
+## Step 6 — Scorecard and update backlog
+
+1. `npx cc-codeconductor scorecard create --task <BC-id> --from-diff`
+2. Complete criteria; `scorecard record` with verdict and optional cost/tokens
+3. Set item `Progress: 100%`, `Status: DONE` if PASS
+4. Move item to `## Archive` in BACKLOG.md if DONE
+5. Run `npx cc-codeconductor openspec scan`
+
+Report completion: Task Cards executed, scorecard verdict, change folder path, files changed.
+
+---
+
+## Skill
+
+Apply `.claude/skills/openspec/SKILL.md` for backlog format rules and state transitions.

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

@@ -4,6 +4,18 @@ Audit web performance using the PageSpeed Insights API. Applies the 80/20
 principle: identify the 20% of changes that produce 80% of the performance gain.
 Produces a prioritized report in the current working directory.
 
+## Step 0 — CCEP Bootstrap
+
+Command: `pagespeed` (fixed for this workflow — do not infer from user text)
+
+1. Run: `npx cc-codeconductor ccep parse --command pagespeed "$ARGUMENTS" --output json`
+2. Run: `npx cc-codeconductor ccep resolve --command pagespeed "$ARGUMENTS" --output json`
+3. Run: `npx cc-codeconductor ccep profile pagespeed --output json`
+4. After planner/intake JSON is available, run: `npx cc-codeconductor ccep evaluate --command pagespeed --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.
+
+---
+
 ## Usage
 
 ```

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

@@ -0,0 +1,38 @@
+---
+description: >-
+  [cc: alias] Disposable spike in an isolated worktree. Not a merge candidate.
+---
+
+# Prototype Workflow
+
+Prototype request: $ARGUMENTS
+
+## Step 0 — CCEP Bootstrap
+
+Command: `prototype` (fixed for this workflow — do not infer from user text)
+
+1. Run: `npx cc-codeconductor ccep parse --command prototype "$ARGUMENTS" --output json`
+2. Run: `npx cc-codeconductor ccep resolve --command prototype "$ARGUMENTS" --output json`
+3. Run: `npx cc-codeconductor ccep profile prototype --output json`
+4. After planner/intake JSON is available, run: `npx cc-codeconductor ccep evaluate --command prototype --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 — Bounds (architect)
+
+Invoke `architect`. Define what the spike may touch, time-box, and what must not leak into main. Do not treat this as a production Technical Plan.
+
+**STOP here. Wait for approval of the spike bounds.**
+
+---
+
+## Step 2 — Spike (implementer)
+
+Invoke `implementer` in a Git worktree that is not a merge candidate. Label the Implementation Summary as disposable. Do not open a PR against protected branches.
+
+---
+
+## Completion
+
+Report bounds, worktree path, and what was learned. Recommend `/cc:feature` or `/cc:fix` if the spike should become real work.

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

@@ -33,6 +33,18 @@ If coverage is insufficient:
 
 ---
 
+## Step 0 — CCEP Bootstrap
+
+Command: `refactor` (fixed for this workflow — do not infer from user text)
+
+1. Run: `npx cc-codeconductor ccep parse --command refactor "$ARGUMENTS" --output json`
+2. Run: `npx cc-codeconductor ccep resolve --command refactor "$ARGUMENTS" --output json`
+3. Run: `npx cc-codeconductor ccep profile refactor --output json`
+4. After planner/intake JSON is available, run: `npx cc-codeconductor ccep evaluate --command refactor --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 — Architectural justification (Architect role)
 
 Adopt the **Architect** role as defined in `CLAUDE.md`. Always invoke this step
@@ -56,6 +68,141 @@ proceed without written approval of the plan.**
 
 ---
 
+## Step 1.5 — Blast Radius Assessment (Orchestrator role)
+
+After Architect approval, assess the scope of the refactor using impact analysis.
+Large refactors require staged sequencing to keep the tree green between batches.
+
+### When to apply Blast Radius Assessment
+
+Always run this step. It determines the route for implementation:
+
+- **Narrow refactor** (blast radius within limits) → proceed to Step 2 (normal routing by risk)
+- **Wide refactor** (blast radius exceeds limits) → proceed to expand-migrate-contract sequence
+
+### Measuring blast radius
+
+Run impact analysis on the files listed in the approved Refactor Plan:
+
+```bash
+cc impact --files <file1> <file2> ... <fileN>
+```
+
+The report returns three metrics:
+
+1. **affectedComponents** (array of strings) — distinct components/modules that depend on the refactored files
+2. **brokenContracts** (array of strings) — public interfaces or contracts that change
+3. **affectedFlows** (array of strings) — end-to-end user flows or business processes impacted
+
+### Threshold decision
+
+**Hardcoded heuristic thresholds** (adjust manually for your codebase size):
+
+```
+Wide refactor triggered if ANY condition is true:
+  - affectedComponents.length >= 6
+  - brokenContracts.length >= 3
+  - affectedFlows.length >= 2
+```
+
+If blast radius exceeds these thresholds, the refactor is classified as **wide**
+and requires staged batching. Otherwise, it is **narrow** and proceeds via
+normal risk-based routing.
+
+**Note:** These thresholds are heuristics meant for medium-sized codebases
+(5–20K lines). Adjust based on your repository's complexity and component
+density. A high-level import count alone does not guarantee impact.
+
+### Route: Narrow refactor
+
+If blast radius is within limits:
+
+1. Show the impact report: affectedComponents count, brokenContracts, affectedFlows.
+2. Proceed to Step 2 (Route by risk) using the risk level from the approved Refactor Plan.
+
+### Route: Wide refactor — expand-migrate-contract sequence
+
+If blast radius exceeds limits, the refactor must be delivered in sequenced
+batches to maintain tree-green guarantees between phases.
+
+**Process:**
+
+1. **Expand phase** (batch 1): Introduce the new interface alongside the old one
+   without removing the old interface. This allows consumers to adopt
+   incrementally. Tests for both old and new paths must pass in this batch.
+   
+   Example: If refactoring a component from function-based to class-based:
+   ```typescript
+   // OLD: function-based API (keep during expand)
+   export function transformData(input: Data): Output {
+     return Transform.apply(input);
+   }
+   
+   // NEW: class-based API (add during expand)
+   export class DataTransformer {
+     apply(input: Data): Output {
+       return Transform.apply(input);
+     }
+   }
+   
+   // Both exported; both tested; old not yet removed.
+   ```
+
+2. **Migrate batches** (batches 2–N): Each batch moves a logical subset of
+   consumers from the old interface to the new one, running tests to confirm
+   no regressions. If tests fail in any migrate batch, that batch is BLOCKED
+   (via `Depends on` in BACKLOG.md) and subsequent batches do not start until
+   the regression is fixed.
+   
+   Example: Migrate Service-A consumers in batch 2, Service-B consumers in
+   batch 3, etc. Each batch is a separate `BC-NNN` item in BACKLOG.md.
+
+3. **Contract phase** (final batch): Remove the old interface entirely after all
+   consumers are migrated. This is the point where the contract actually changes.
+
+**Sequencing batches via BACKLOG.md:**
+
+Create multiple `BC-NNN` items, one per batch (expand, then one per migrate, then
+contract). Use the `Depends on` field to enforce ordering:
+
+```
+### BC-001 | Expand Phase
+Status: READY
+Depends on: (none)
+Description: Introduce new interface alongside old...
+
+### BC-002 | Migrate Batch 1 (Service-A consumers)
+Status: READY (but not eligible until BC-001 done)
+Depends on: BC-001
+Description: Move Service-A from old to new interface...
+
+### BC-003 | Migrate Batch 2 (Service-B consumers)
+Status: READY (but not eligible until BC-002 done)
+Depends on: BC-002
+Description: Move Service-B from old to new interface...
+
+### BC-004 | Contract Phase (Remove old interface)
+Status: READY (but not eligible until BC-003 done)
+Depends on: BC-003
+Description: Delete old interface and consolidate tests...
+```
+
+**BLOCKED policy on test failures:**
+
+If any migrate batch's test suite fails after implementation, that batch item
+is marked BLOCKED (and stays BLOCKED in BACKLOG.md until the regression is
+fixed). Subsequent batches in the `Depends on` chain do not start — the
+orchestrator skips them and reports the blocker to the user.
+
+This ensures the tree remains green and no downstream consumer migration builds
+on unstable code.
+
+**STOP here. Show the Blast Radius Assessment report and the recommended route
+(narrow or wide). If wide, show the proposed batch structure and wait for
+user approval before proceeding.**
+
+---
+
 ## Step 2 — Route by risk
 
 Read the risk field from the Refactor Plan and follow the corresponding route.
@@ -140,9 +287,13 @@ findings block completion.
 
 ## Completion
 
-Report: Refactor Plan (approved), Implementation Summary, test results before
+Report: Refactor Plan (approved), Blast Radius Assessment (if applicable), Implementation Summary, test results before
 and after, Review Report (if applicable).
 
 The refactor is complete only when: all pre-existing tests still pass, the
 implementation matches the approved plan exactly, and no CRITICAL review
 findings remain.
+
+If using expand-migrate-contract: completion occurs only after all batches
+(expand, migrate, contract) are DONE and no BLOCKED items remain in the
+sequencing chain.