claude-code-pilot 3.2.0 → 3.3.1

package/src/commands/ccp/cost-report.md

@@ -0,0 +1,107 @@
+---
+description: Generate a local Claude Code cost report from a cost-tracker SQLite database.
+argument-hint: [csv]
+---
+
+# Cost Report
+
+Query the local cost-tracking database and present a spending report by day,
+project, tool, and session. This command assumes a cost-tracking hook or plugin
+is already writing usage rows to `~/.claude-cost-tracker/usage.db`.
+
+## What This Command Does
+
+1. Check that `sqlite3` is available.
+2. Check that `~/.claude-cost-tracker/usage.db` exists.
+3. Run aggregate queries against the `usage` table.
+4. Present a compact report, or export recent rows as CSV when the argument is
+   `csv`.
+
+## Prerequisites
+
+The database must be populated by a local cost tracker. If the file is missing,
+tell the user the tracker is not set up and suggest installing or enabling a
+trusted Claude Code cost-tracking hook/plugin first.
+
+```bash
+test -f ~/.claude-cost-tracker/usage.db && echo "Database found" || echo "Database not found"
+```
+
+## Summary Query
+
+```bash
+sqlite3 -header -column ~/.claude-cost-tracker/usage.db "
+  SELECT
+    ROUND(COALESCE(SUM(CASE WHEN date(timestamp) = date('now') THEN cost_usd END), 0), 4) AS today_cost,
+    ROUND(COALESCE(SUM(CASE WHEN date(timestamp) = date('now', '-1 day') THEN cost_usd END), 0), 4) AS yesterday_cost,
+    ROUND(COALESCE(SUM(cost_usd), 0), 4) AS total_cost,
+    COUNT(*) AS total_calls,
+    COUNT(DISTINCT session_id) AS sessions
+  FROM usage;
+"
+```
+
+## Project Breakdown
+
+```bash
+sqlite3 -header -column ~/.claude-cost-tracker/usage.db "
+  SELECT project, ROUND(SUM(cost_usd), 4) AS cost, COUNT(*) AS calls
+  FROM usage
+  GROUP BY project
+  ORDER BY cost DESC;
+"
+```
+
+## Tool Breakdown
+
+```bash
+sqlite3 -header -column ~/.claude-cost-tracker/usage.db "
+  SELECT tool_name, ROUND(SUM(cost_usd), 4) AS cost, COUNT(*) AS calls
+  FROM usage
+  GROUP BY tool_name
+  ORDER BY cost DESC;
+"
+```
+
+## Last Seven Days
+
+```bash
+sqlite3 -header -column ~/.claude-cost-tracker/usage.db "
+  SELECT date(timestamp) AS date, ROUND(SUM(cost_usd), 4) AS cost, COUNT(*) AS calls
+  FROM usage
+  GROUP BY date(timestamp)
+  ORDER BY date DESC
+  LIMIT 7;
+"
+```
+
+## CSV Export
+
+If the user asks for `/cost-report csv`, export the most recent usage rows with
+an explicit column list:
+
+```bash
+sqlite3 -csv -header ~/.claude-cost-tracker/usage.db "
+  SELECT timestamp, project, tool_name, input_tokens, output_tokens, cost_usd, session_id, model
+  FROM usage
+  ORDER BY timestamp DESC
+  LIMIT 100;
+"
+```
+
+## Report Format
+
+Format the response as:
+
+1. Summary: today, yesterday, total, calls, sessions.
+2. By project: projects ranked by total cost.
+3. By tool: tools ranked by total cost.
+4. Last seven days: date, cost, call count.
+
+Use four decimal places for sub-dollar amounts. Do not estimate pricing from raw
+tokens in this command; rely on the precomputed `cost_usd` values written by the
+tracker.
+
+## Source
+
+Salvaged from stale community PR #1304 by `MayurBhavsar`.

package/src/commands/ccp/intel.md

@@ -24,7 +24,7 @@ Then proceed to Step 1.
 
 Check if intel is enabled by reading `.planning/config.json` directly using the Read tool.
 
-**DO NOT use the gsd-tools config get-value command** -- it hard-exits on missing keys.
+**DO NOT use the config get-value CLI** -- it hard-exits on missing keys. Read `.planning/config.json` directly instead.
 
 1. Read `.planning/config.json` using the Read tool
 2. If the file does not exist: display the disabled message below and **STOP**
@@ -137,7 +137,7 @@ Task(
   prompt="You are the gsd-intel-updater agent. Your job is to analyze this codebase and write/update intelligence files in .planning/intel/.
 
 Project root: ${CWD}
-Prefer: gsd-sdk query <subcommand> (installed gsd-sdk on PATH). Legacy: node $HOME/.claude/pilot/bin/gsd-tools.cjs
+Use: node "$HOME/.claude/pilot/bin/ccp-tools.cjs" <subcommand>
 
 Instructions:
 1. Analyze the codebase structure, dependencies, APIs, and architecture
@@ -176,4 +176,4 @@ Display a summary showing:
 1. DO NOT spawn an agent for query/status/diff operations -- these are inline CLI calls
 2. DO NOT modify intel files directly -- the agent handles writes during refresh
 3. DO NOT skip the config gate check
-4. DO NOT use the gsd-tools config get-value CLI for the config gate -- it exits on missing keys
+4. DO NOT use the config get-value CLI for the config gate -- it exits on missing keys

package/src/commands/ccp/mvp-phase.md

@@ -0,0 +1,45 @@
+---
+name: ccp:mvp-phase
+description: Plan a phase as a vertical MVP slice — user story, SPIDR splitting, then plan-phase
+argument-hint: "<phase-number>"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+requires: [new-project, plan-phase]
+---
+<objective>
+Guide the user through MVP-mode planning for a phase. The command:
+
+1. Prompts for an "As a / I want to / So that" user story (three structured questions)
+2. Runs SPIDR splitting check — if the story is too large, walks through Spike/Paths/Interfaces/Data/Rules and offers to split into multiple phases
+3. Writes `**Mode:** mvp` and the reformatted `**Goal:**` to the phase's ROADMAP.md section
+4. Delegates to `/ccp:plan-phase <N>` which auto-detects MVP mode via the roadmap field
+
+Phase 1 of the vertical-mvp-slice PRD shipped the planner-side machinery; this command is the user entry point for it.
+</objective>
+
+<execution_context>
+@~/.claude/pilot/workflows/mvp-phase.md
+@~/.claude/pilot/references/spidr-splitting.md
+@~/.claude/pilot/references/user-story-template.md
+</execution_context>
+
+<runtime_note>
+**Copilot (VS Code):** Use `vscode_askquestions` wherever this workflow calls `AskUserQuestion`. Equivalent API.
+</runtime_note>
+
+<context>
+Phase number: $ARGUMENTS (required — integer or decimal like `2.1`)
+
+The phase must already exist in ROADMAP.md (created via `/ccp:new-project`, `/ccp:add-phase`, or `/ccp:insert-phase`). This command does not create new phases — it converts an existing phase to MVP mode.
+</context>
+
+<process>
+Execute the mvp-phase workflow from @~/.claude/pilot/workflows/mvp-phase.md end-to-end.
+Preserve all gates: phase existence, status guard (refuse in_progress/completed), user-story format validation, SPIDR splitting check, ROADMAP write confirmation, plan-phase delegation.
+</process>

package/src/commands/ccp/plan-prd.md

@@ -0,0 +1,160 @@
+---
+description: "Generate a lean, problem-first PRD and hand off to /plan for implementation planning."
+argument-hint: "[product/feature idea] (blank = start with questions)"
+---
+
+# PRD Command
+
+Produces a **Product Requirements Document** — the requirements-phase artifact of the SDLC. Captures *what* must be true for success and *why*, and stops before *how*. Implementation decomposition is delegated to `/plan`.
+
+**Input**: `$ARGUMENTS`
+
+## Scope of this command
+
+| This command does | This command does NOT do |
+|---|---|
+| Frame the problem and users | Design the architecture |
+| Capture success criteria and scope | Pick files or write patterns |
+| List open questions and risks | Enumerate implementation tasks |
+| Write `.claude/prds/{name}.prd.md` | Produce an implementation plan — that's `/plan` |
+
+If you find yourself writing implementation detail, stop and cut it. It belongs in `/plan`.
+
+**Anti-fluff rule**: When information is missing, write `TBD — needs validation via {method}`. Never invent plausible-sounding requirements.
+
+## Workflow
+
+Four phases. Each phase is a single gate — ask the questions, wait for the user, then move on. No nested loops, no parallel research ceremony.
+
+### Phase 1 — FRAME
+
+If `$ARGUMENTS` is empty, ask:
+
+> What do you want to build? One or two sentences.
+
+If provided, restate in one sentence and ask:
+
+> I understand: *{restated}*. Correct, or should I adjust?
+
+Then ask the framing questions in a single set:
+
+> 1. **Who** has this problem? (specific role or segment)
+> 2. **What** is the observable pain? (describe behavior, not assumed needs)
+> 3. **Why** can't they solve it with what exists today?
+> 4. **Why now?** — what changed that makes this worth doing?
+
+Wait for the user. Do not proceed without answers (or explicit "skip").
+
+### Phase 2 — GROUND
+
+Ask for evidence. This is the shortest phase and the most load-bearing:
+
+> What evidence do you have that this problem is real and worth solving? (user quotes, support tickets, metrics, observed behavior, failed workarounds — anything concrete)
+
+If the user has none, record the PRD's Evidence section as `Assumption — needs validation via {user research | analytics | prototype}`. This keeps the PRD honest.
+
+### Phase 3 — DECIDE
+
+Scope and hypothesis in a single set:
+
+> 1. **Hypothesis** — Complete: *We believe **{capability}** will **{solve problem}** for **{users}**. We'll know we're right when **{measurable outcome}**.*
+> 2. **MVP** — The minimum needed to test the hypothesis?
+> 3. **Out of scope** — What are you explicitly **not** building (even if users ask)?
+> 4. **Open questions** — Uncertainties that could change the approach?
+
+Wait for responses.
+
+### Phase 4 — GENERATE & HAND OFF
+
+Create the directory if needed, write the PRD, and report.
+
+```bash
+mkdir -p .claude/prds
+```
+
+**Output path**: `.claude/prds/{kebab-case-name}.prd.md`
+
+#### PRD Template
+
+```markdown
+# {Product / Feature Name}
+
+## Problem
+{2–3 sentences: who has what problem, and what's the cost of leaving it unsolved?}
+
+## Evidence
+- {User quote, data point, or observation}
+- {OR: "Assumption — needs validation via {method}"}
+
+## Users
+- **Primary**: {role, context, what triggers the need}
+- **Not for**: {who this explicitly excludes}
+
+## Hypothesis
+We believe **{capability}** will **{solve problem}** for **{users}**.
+We'll know we're right when **{measurable outcome}**.
+
+## Success Metrics
+| Metric | Target | How measured |
+|---|---|---|
+| {primary} | {number} | {method} |
+
+## Scope
+**MVP** — {the minimum to test the hypothesis}
+
+**Out of scope**
+- {item} — {why deferred}
+
+## Delivery Milestones
+<!-- Business outcomes, not engineering tasks. /plan turns each into a plan. -->
+<!-- Status: pending | in-progress | complete -->
+
+| # | Milestone | Outcome | Status | Plan |
+|---|---|---|---|---|
+| 1 | {name} | {user-visible change} | pending | — |
+| 2 | {name} | {user-visible change} | pending | — |
+
+## Open Questions
+- [ ] {question that could change scope or approach}
+
+## Risks
+| Risk | Likelihood | Impact | Mitigation |
+|---|---|---|---|
+
+---
+*Status: DRAFT — requirements only. Implementation planning pending via /plan.*
+```
+
+#### Report to user
+
+```
+PRD created: .claude/prds/{name}.prd.md
+
+Problem:    {one line}
+Hypothesis: {one line}
+MVP:        {one line}
+
+Validation status:
+  Problem  {validated | assumption}
+  Users    {concrete | generic — refine}
+  Metrics  {defined | TBD}
+
+Open questions: {count}
+
+Next step: /plan .claude/prds/{name}.prd.md
+  → /plan will pick the next pending milestone and produce an implementation plan.
+```
+
+## Integration
+
+- `/plan <prd-path>` — consume the PRD and produce an implementation plan for the next pending milestone.
+- `tdd-workflow` skill — implement the plan test-first.
+- `/pr` — open a PR that references the PRD and plan.
+
+## Success criteria
+
+- **PROBLEM_CLEAR**: problem is specific and evidenced (or flagged as assumption).
+- **USER_CONCRETE**: primary user is a specific role, not "users".
+- **HYPOTHESIS_TESTABLE**: measurable outcome included.
+- **SCOPE_BOUNDED**: explicit MVP and explicit out-of-scope.
+- **NO_IMPLEMENTATION_DETAIL**: file paths, libraries, or task breakdowns are absent — if they appeared, move them to the `/plan` step.

package/src/commands/ccp/pr-ecc.md

@@ -0,0 +1,184 @@
+---
+description: "Create a GitHub PR from current branch with unpushed commits — discovers templates, analyzes changes, pushes"
+argument-hint: "[base-branch] (default: main)"
+---
+
+# Create Pull Request
+
+**Input**: `$ARGUMENTS` — optional, may contain a base branch name and/or flags (e.g., `--draft`).
+
+**Parse `$ARGUMENTS`**:
+- Extract any recognized flags (`--draft`)
+- Treat remaining non-flag text as the base branch name
+- Default base branch to `main` if none specified
+
+---
+
+## Phase 1 — VALIDATE
+
+Check preconditions:
+
+```bash
+git branch --show-current
+git status --short
+git log origin/<base>..HEAD --oneline
+```
+
+| Check | Condition | Action if Failed |
+|---|---|---|
+| Not on base branch | Current branch ≠ base | Stop: "Switch to a feature branch first." |
+| Clean working directory | No uncommitted changes | Warn: "You have uncommitted changes. Commit or stash first." |
+| Has commits ahead | `git log origin/<base>..HEAD` not empty | Stop: "No commits ahead of `<base>`. Nothing to PR." |
+| No existing PR | `gh pr list --head <branch> --json number` is empty | Stop: "PR already exists: #<number>. Use `gh pr view <number> --web` to open it." |
+
+If all checks pass, proceed.
+
+---
+
+## Phase 2 — DISCOVER
+
+### PR Template
+
+Search for PR template in order:
+
+1. `.github/PULL_REQUEST_TEMPLATE/` directory — if exists, list files and let user choose (or use `default.md`)
+2. `.github/PULL_REQUEST_TEMPLATE.md`
+3. `.github/pull_request_template.md`
+4. `docs/pull_request_template.md`
+
+If found, read it and use its structure for the PR body.
+
+### Commit Analysis
+
+```bash
+git log origin/<base>..HEAD --format="%h %s" --reverse
+```
+
+Analyze commits to determine:
+- **PR title**: Use conventional commit format with type prefix — `feat: ...`, `fix: ...`, etc.
+  - If multiple types, use the dominant one
+  - If single commit, use its message as-is
+- **Change summary**: Group commits by type/area
+
+### File Analysis
+
+```bash
+git diff origin/<base>..HEAD --stat
+git diff origin/<base>..HEAD --name-only
+```
+
+Categorize changed files: source, tests, docs, config, migrations.
+
+### Planning Artifacts
+
+Check for related artifacts produced by `/plan-prd`, `/plan`, or the legacy PRP workflow:
+- `.claude/prds/` — PRDs this PR implements a milestone of
+- `.claude/plans/` — Plans executed by this PR
+- `.claude/PRPs/prds/` — legacy PRP PRDs
+- `.claude/PRPs/plans/` — legacy PRP implementation plans
+- `.claude/PRPs/reports/` — legacy PRP implementation reports
+
+Reference these in the PR body if they exist.
+
+---
+
+## Phase 3 — PUSH
+
+```bash
+git push -u origin HEAD
+```
+
+If push fails due to divergence:
+```bash
+git fetch origin
+git rebase origin/<base>
+git push -u origin HEAD
+```
+
+If rebase conflicts occur, stop and inform the user.
+
+---
+
+## Phase 4 — CREATE
+
+### With Template
+
+If a PR template was found in Phase 2, fill in each section using the commit and file analysis. Preserve all template sections — leave sections as "N/A" if not applicable rather than removing them.
+
+### Without Template
+
+Use this default format:
+
+```markdown
+## Summary
+
+<1-2 sentence description of what this PR does and why>
+
+## Changes
+
+<bulleted list of changes grouped by area>
+
+## Files Changed
+
+<table or list of changed files with change type: Added/Modified/Deleted>
+
+## Testing
+
+<description of how changes were tested, or "Needs testing">
+
+## Related Issues
+
+<linked issues with Closes/Fixes/Relates to #N, or "None">
+```
+
+### Create the PR
+
+```bash
+gh pr create \
+  --title "<PR title>" \
+  --base <base-branch> \
+  --body "<PR body>"
+  # Add --draft if the --draft flag was parsed from $ARGUMENTS
+```
+
+---
+
+## Phase 5 — VERIFY
+
+```bash
+gh pr view --json number,url,title,state,baseRefName,headRefName,additions,deletions,changedFiles
+gh pr checks --json name,status,conclusion 2>/dev/null || true
+```
+
+---
+
+## Phase 6 — OUTPUT
+
+Report to user:
+
+```
+PR #<number>: <title>
+URL: <url>
+Branch: <head> → <base>
+Changes: +<additions> -<deletions> across <changedFiles> files
+
+CI Checks: <status summary or "pending" or "none configured">
+
+Artifacts referenced:
+  - <any PRDs/plans linked in PR body>
+
+Next steps:
+  - gh pr view <number> --web   → open in browser
+  - /code-review <number>       → review the PR
+  - gh pr merge <number>        → merge when ready
+```
+
+---
+
+## Edge Cases
+
+- **No `gh` CLI**: Stop with: "GitHub CLI (`gh`) is required. Install: <https://cli.github.com/>"
+- **Not authenticated**: Stop with: "Run `gh auth login` first."
+- **Force push needed**: If remote has diverged and rebase was done, use `git push --force-with-lease` (never `--force`).
+- **Multiple PR templates**: If `.github/PULL_REQUEST_TEMPLATE/` has multiple files, list them and ask user to choose.
+- **Large PR (>20 files)**: Warn about PR size. Suggest splitting if changes are logically separable.

package/src/commands/ccp/security-scan.md

@@ -0,0 +1,74 @@
+---
+description: Scan your .claude/ configuration for security issues via AgentShield (external, opt-in via npx).
+argument-hint: [path] [--format json|markdown|html] [--min-severity low|medium|high|critical] [--fix]
+---
+
+# Security Scan
+
+Scan a project (agents, hooks, MCP servers, permissions, and secrets) for
+security issues. This command is a thin wrapper around the external
+`ecc-agentshield` scanner: nothing is installed at CCP install time — you opt in
+at run time via `npx`, so the scanner is fetched on demand and never vendored.
+
+## Usage
+
+`/ccp:security-scan [path] [--format json|markdown|html] [--min-severity low|medium|high|critical] [--fix]`
+
+- `path` (optional): defaults to the current project. Use a `.claude/` path, a
+  repo root, or a checked-in template directory.
+- `--format`: output format. Use `json` for CI, `markdown` for handoffs, `html`
+  for standalone review reports.
+- `--min-severity`: filters lower-priority findings.
+- `--fix`: applies only fixes the scanner explicitly marks safe and auto-fixable.
+
+## Deterministic Engine
+
+Run the external scanner against the target path:
+
+```bash
+npx ecc-agentshield scan --path "${TARGET_PATH:-.}"
+```
+
+For a plain-text report instead of the default output:
+
+```bash
+npx ecc-agentshield scan --path "${TARGET_PATH:-.}" --format text
+```
+
+Use AgentShield output as the source of truth; do not invent findings. Keep
+scanner facts separate from your follow-up judgment.
+
+## Remediation
+
+For each critical or high finding, return:
+
+- file path
+- severity
+- why it matters
+- the exact fix
+- whether `--fix` is safe to apply
+
+If `--fix` is requested, state the planned edits before applying them, then
+re-scan and report the before/after grade.
+
+## Full Reference
+
+The complete CLI surface, output formats, severity grades, and the policy schema
+live in the skill — read it for anything beyond the invocation above:
+
+@.claude/skills/security-scan/SKILL.md
+
+The policy schema and example documents are under
+`references/agentshield-policy-exception/` within that skill.
+
+## Arguments
+
+$ARGUMENTS:
+- optional target path
+- optional AgentShield flags (`--format`, `--min-severity`, `--fix`)
+
+## Source
+
+Thin wrapper for AgentShield (https://github.com/affaan-m/agentshield);
+external, not vendored. Pinned in `manifest.json` under
+`external.agentshield` (1.4.0).

package/src/hooks/ccp-bash-hook-dispatcher.js

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+'use strict';
+
+const { isHookEnabled } = require('../lib/hook-flags');
+
+const MAX_STDIN = 1024 * 1024;
+
+// GateGuard is the sole pre-bash chain member in CCP's minimal dispatcher.
+// It is lazy-required so this file does NOT hard-depend on the GateGuard hook
+// (ccp-write-gateguard, delivered by Plan 04) landing first. If the module is
+// absent, the member is a no-op that returns rawInput unchanged.
+//
+// NOTE: The upstream tmux / git-push / commit-quality / auto-tmux /
+// block-no-verify members are intentionally NOT ported. Those are external
+// workflow opinions; CCP ships a minimal, profile-gated dispatcher whose only
+// job is the GateGuard Bash branch. The runHooks loop below is preserved as an
+// extensible scaffold so future members can be appended to PRE_BASH_HOOKS.
+let _gateguardRun = null;
+try {
+  _gateguardRun = require('./ccp-write-gateguard').run;
+} catch (_) {
+  _gateguardRun = null;
+}
+
+const PRE_BASH_HOOKS = [
+  {
+    id: 'pre:bash:gateguard-fact-force',
+    profiles: 'standard,strict',
+    run: rawInput => (_gateguardRun ? _gateguardRun(rawInput) : rawInput),
+  },
+];
+
+function normalizeHookResult(previousRaw, output) {
+  if (typeof output === 'string' || Buffer.isBuffer(output)) {
+    return {
+      raw: String(output),
+      stderr: '',
+      exitCode: 0,
+    };
+  }
+
+  if (output && typeof output === 'object') {
+    const nextRaw = Object.prototype.hasOwnProperty.call(output, 'stdout')
+      ? String(output.stdout ?? '')
+      : !Number.isInteger(output.exitCode) || output.exitCode === 0
+        ? previousRaw
+        : '';
+
+    return {
+      raw: nextRaw,
+      stderr: typeof output.stderr === 'string' ? output.stderr : '',
+      exitCode: Number.isInteger(output.exitCode) ? output.exitCode : 0,
+    };
+  }
+
+  return {
+    raw: previousRaw,
+    stderr: '',
+    exitCode: 0,
+  };
+}
+
+function runHooks(rawInput, hooks) {
+  let currentRaw = rawInput;
+  let stderr = '';
+
+  for (const hook of hooks) {
+    if (!isHookEnabled(hook.id, { profiles: hook.profiles })) {
+      continue;
+    }
+
+    try {
+      const result = normalizeHookResult(currentRaw, hook.run(currentRaw));
+      currentRaw = result.raw;
+      if (result.stderr) {
+        stderr += result.stderr.endsWith('\n') ? result.stderr : `${result.stderr}\n`;
+      }
+      if (result.exitCode !== 0) {
+        return { output: currentRaw, stderr, exitCode: result.exitCode };
+      }
+    } catch (error) {
+      stderr += `[Hook] ${hook.id} failed: ${error.message}\n`;
+    }
+  }
+
+  return { output: currentRaw, stderr, exitCode: 0 };
+}
+
+function runPreBash(rawInput) {
+  return runHooks(rawInput, PRE_BASH_HOOKS);
+}
+
+module.exports = { PRE_BASH_HOOKS, runPreBash };
+
+// MAX_STDIN is exported indirectly for parity with the entrypoint cap.
+module.exports.MAX_STDIN = MAX_STDIN;