cc-dev-template 0.1.97 → 0.1.98

package/bin/install.js

@@ -254,6 +254,7 @@ if (fs.existsSync(mergeSettingsPath)) {
   const configs = [
     { file: 'task-output-guard-hook.json', name: 'TaskOutput context guard' },
     { file: 'statusline-config.json', name: 'Custom status line' },
+    { file: 'ship-policy-hook.json', name: 'Ship policy enforcement' },
     // Spinner verbs - choose one (Star Trek or Factorio)
     { file: 'spinner-verbs-startrek.json', name: 'Star Trek spinner verbs' }
     // { file: 'spinner-verbs-factorio.json', name: 'Factorio spinner verbs' }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cc-dev-template",
-  "version": "0.1.97",
+  "version": "0.1.98",
   "description": "Structured AI-assisted development framework for Claude Code",
   "bin": {
     "cc-dev-template": "./bin/install.js"

package/src/agents/question-generator.md

@@ -1,17 +1,17 @@
 ---
 name: question-generator
 description: Generates research questions from a feature intent document. Cannot explore the codebase — produces questions only.
-tools: Write
+tools: Read, Write
 permissionMode: bypassPermissions
 ---
 
-You are a question generator. You receive a feature intent document in your prompt and produce research questions that a senior engineer would need answered about the codebase before implementing this feature.
+You are a question generator. You read a feature intent document and produce research questions that a senior engineer would need answered about the codebase before implementing this feature.
 
-You generate questions only. You have no ability to read files or explore the codebase. Your only tool is Write — to write the questions file.
+You generate questions only. You can read the intent document and write the questions file — the ship policy hook restricts you to exactly those two paths.
 
 ## Process
 
-1. Analyze the intent document provided below in your prompt
+1. Read the intent document at the path provided in your prompt
 2. Think deeply about what you'd need to know to actually build this — not just what the system looks like, but how you'd hook into it
 3. Write organized, specific questions to the output path provided in your prompt
 

package/src/scripts/ship-policy-hook.json

@@ -0,0 +1,14 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ~/.claude/scripts/ship-policy.js"
+          }
+        ]
+      }
+    ]
+  }
+}

package/src/scripts/ship-policy.js

@@ -0,0 +1,224 @@
+#!/usr/bin/env node
+
+/**
+ * Ship Policy Hook — Phase-aware enforcement for the ship skill.
+ *
+ * PreToolUse hook that checks every tool call against a policy matrix
+ * of (phase, agent_type, tool_name, target_path) rules. No-op when
+ * ship is not active (state file missing or session mismatch).
+ *
+ * State: {cwd}/.claude/ship-hook-state.json
+ */
+
+const { readFileSync, writeFileSync, existsSync } = require('fs');
+const { join, resolve, relative } = require('path');
+
+// Tools that bypass all policy checks
+const BYPASS_TOOLS = new Set([
+  'AskUserQuestion', 'TaskCreate', 'TaskUpdate', 'TaskList', 'TaskGet',
+  'TaskOutput', 'TaskStop', 'ToolSearch', 'SendMessage', 'Agent',
+  'TeamCreate', 'TeamDelete',
+]);
+
+// Per-phase orchestrator write permissions (beyond state files)
+const ORCHESTRATOR_WRITES = {
+  intent:    (d) => [`${d}/intent.md`],
+  questions: () => [],
+  research:  (d) => [`${d}/research.md`],
+  design:    (d) => [`${d}/design.md`],
+  spec:      () => [],
+  verify:    () => [],
+  tasks:     () => [],
+  implement: () => [],
+  complete:  () => [],
+};
+
+// Spec artifacts that spec-implementer cannot overwrite
+const PROTECTED_ARTIFACTS = [
+  'spec.md', 'test-plan.md', 'design.md', 'intent.md',
+  'questions.md', 'research.md',
+];
+
+function block(reason) { return { blocked: true, reason }; }
+function allow() { return { blocked: false }; }
+
+/**
+ * Get the target path relative to cwd.
+ * Returns: string (relative path), null (outside project), or undefined (no path in input).
+ */
+function relPath(tool, input, cwd) {
+  let raw;
+  if (tool === 'Read' || tool === 'Write' || tool === 'Edit') raw = input.file_path;
+  else if (tool === 'Grep' || tool === 'Glob') raw = input.path;
+  if (!raw) return undefined;
+  const abs = resolve(raw);
+  if (abs !== cwd && !abs.startsWith(cwd + '/')) return null;
+  return relative(cwd, abs);
+}
+
+function under(p, prefix) {
+  const dir = prefix.replace(/\/$/, '');
+  return p === dir || p.startsWith(dir + '/');
+}
+
+// ── Orchestrator Policy ──
+
+function orchestratorPolicy(tool, input, cwd, specDir, phase) {
+  if (tool === 'Bash') return block('Orchestrator cannot run Bash — delegate to a sub-agent');
+
+  if (tool === 'Read' || tool === 'Grep' || tool === 'Glob') {
+    const p = relPath(tool, input, cwd);
+    if (p === null) return allow(); // Outside project (skill files, etc.)
+
+    // Grep/Glob with no path or project root — check pattern prefix
+    if ((tool === 'Grep' || tool === 'Glob') && (p === undefined || p === '')) {
+      const pat = input.pattern || '';
+      if (/^(docs|references|\.claude)(\/|$)/.test(pat)) return allow();
+      return block('Orchestrator cannot search the full project — use a path under docs/, references/, or .claude/');
+    }
+
+    if (p === undefined) return allow();
+    if (under(p, 'docs') || under(p, 'references') || under(p, '.claude')) return allow();
+    return block(`Orchestrator cannot read source code (${p}) — delegate to a research agent`);
+  }
+
+  if (tool === 'Write' || tool === 'Edit') {
+    const p = relPath(tool, input, cwd);
+    if (p === null || p === undefined) return allow();
+
+    // State files always writable
+    if (p === `${specDir}/state.yaml` || p === '.claude/ship-hook-state.json') return allow();
+
+    // Per-phase permissions
+    const permFn = ORCHESTRATOR_WRITES[phase];
+    if (permFn && permFn(specDir).includes(p)) return allow();
+
+    return block(`Orchestrator cannot write ${p} in ${phase} phase — delegate to a sub-agent`);
+  }
+
+  return allow();
+}
+
+// ── Sub-Agent Policies ──
+
+function questionGeneratorPolicy(tool, input, cwd, specDir) {
+  const p = relPath(tool, input, cwd);
+
+  if (tool === 'Read') {
+    if (p === null) return allow();
+    if (p === `${specDir}/intent.md`) return allow();
+    return block(`question-generator can only read ${specDir}/intent.md`);
+  }
+  if (tool === 'Write') {
+    if (p === null) return allow();
+    if (p === `${specDir}/questions.md`) return allow();
+    return block(`question-generator can only write ${specDir}/questions.md`);
+  }
+  return block(`question-generator cannot use ${tool}`);
+}
+
+function objectiveResearcherPolicy(tool, input, cwd, specDir) {
+  const p = relPath(tool, input, cwd);
+
+  if (tool === 'Read' || tool === 'Grep' || tool === 'Glob') {
+    if (p === null) return allow();
+    if (p === undefined) return allow(); // Grep/Glob with no path — project-wide search
+    if (p.startsWith(`${specDir}/research`) && p.endsWith('.md')) return allow(); // Own output
+    if (under(p, 'docs')) return block('objective-researcher cannot read docs/ — research must stay objective');
+    return allow();
+  }
+
+  if (tool === 'Write') {
+    if (p === null) return allow();
+    if (p !== undefined && p.startsWith(`${specDir}/research`) && p.endsWith('.md')) return allow();
+    return block(`objective-researcher can only write to ${specDir}/research-*.md`);
+  }
+
+  if (tool === 'Bash') return allow();
+  return block(`objective-researcher cannot use ${tool}`);
+}
+
+function specDirWriterPolicy(tool, input, cwd, specDir) {
+  if (tool === 'Read' || tool === 'Grep' || tool === 'Glob') return allow();
+  if (tool === 'Write' || tool === 'Edit') {
+    const p = relPath(tool, input, cwd);
+    if (p === null || p === undefined) return allow();
+    if (under(p, specDir)) return allow();
+    return block(`Cannot write outside ${specDir}`);
+  }
+  if (tool === 'Bash') return block('This agent cannot run Bash commands');
+  return allow();
+}
+
+function specImplementerPolicy(tool, input, cwd, specDir) {
+  if (tool === 'Write' || tool === 'Edit') {
+    const p = relPath(tool, input, cwd);
+    if (p === null || p === undefined) return allow();
+    for (const artifact of PROTECTED_ARTIFACTS) {
+      if (p === `${specDir}/${artifact}`) return block(`spec-implementer cannot modify ${artifact}`);
+    }
+  }
+  return allow();
+}
+
+function specValidatorPolicy(tool, input, cwd, specDir) {
+  if (tool === 'Write' || tool === 'Edit') {
+    const p = relPath(tool, input, cwd);
+    if (p === null || p === undefined) return allow();
+    if (under(p, `${specDir}/tasks`)) return allow(); // Review Notes in task files
+    return block('spec-validator cannot write outside task files');
+  }
+  return allow();
+}
+
+// ── Main ──
+
+const AGENT_POLICIES = {
+  'question-generator': questionGeneratorPolicy,
+  'objective-researcher': objectiveResearcherPolicy,
+  'spec-writer': specDirWriterPolicy,
+  'test-planner': specDirWriterPolicy,
+  'task-breakdown': specDirWriterPolicy,
+  'spec-implementer': specImplementerPolicy,
+  'spec-validator': specValidatorPolicy,
+};
+
+function main() {
+  const input = JSON.parse(readFileSync(0, 'utf-8'));
+  const cwd = process.cwd();
+  const stateFile = join(cwd, '.claude', 'ship-hook-state.json');
+
+  if (!existsSync(stateFile)) process.exit(0);
+
+  let state;
+  try { state = JSON.parse(readFileSync(stateFile, 'utf-8')); }
+  catch { process.exit(0); }
+
+  // First-touch: inject session_id if missing
+  if (!state.session_id) {
+    state.session_id = input.session_id;
+    try { writeFileSync(stateFile, JSON.stringify(state, null, 2)); } catch {}
+  }
+
+  if (state.session_id !== input.session_id) process.exit(0);
+  if (BYPASS_TOOLS.has(input.tool_name)) process.exit(0);
+
+  const caller = input.agent_type || 'orchestrator';
+  const tool = input.tool_name;
+  const toolInput = input.tool_input || {};
+
+  let result;
+  if (caller === 'orchestrator') {
+    result = orchestratorPolicy(tool, toolInput, cwd, state.spec_dir, state.phase);
+  } else {
+    const policyFn = AGENT_POLICIES[caller];
+    if (!policyFn) process.exit(0); // Unknown agent — not a ship agent
+    result = policyFn(tool, toolInput, cwd, state.spec_dir);
+  }
+
+  if (result.blocked) {
+    console.log(JSON.stringify({ decision: 'block', reason: result.reason }));
+  }
+}
+
+main();

package/src/scripts/statusline.js

@@ -560,11 +560,25 @@ function main() {
       usageLines.push(makeBoxLine(usageDisplay));
     }
 
+    // Ship phase line (if active)
+    const shipLines = [];
+    try {
+      const shipStatePath = join(data.workspace.project_dir, '.claude', 'ship-hook-state.json');
+      const shipStat = statSync(shipStatePath);
+      if (Date.now() - shipStat.mtimeMs < 300000) { // < 5 min old
+        const shipState = JSON.parse(readFileSync(shipStatePath, 'utf-8'));
+        const phase = (shipState.phase || '').toUpperCase();
+        const feature = shipState.feature || '';
+        const subPhase = shipState.sub_phase ? ` ${shipState.sub_phase}` : '';
+        shipLines.push(makeBoxLine(`SHIP: ${phase} [${feature}]${subPhase}`));
+      }
+    } catch {}
+
     // Bottom border (add 2 to match content line width)
     const bottomBorder = `${DIM_GREY}╚${'═'.repeat(width + 2)}╝${RESET}`;
 
     // Combine all lines
-    const allLines = [topBorder, line0, ...branchLines, ctxLine, ...usageLines, bottomBorder];
+    const allLines = [topBorder, line0, ...shipLines, ...branchLines, ctxLine, ...usageLines, bottomBorder];
     console.log(allLines.join('\n'));
   } catch (error) {
     // Log error for debugging (goes to stderr, not visible in status line)

package/src/skills/ship/SKILL.md

@@ -44,6 +44,8 @@ Look for `docs/specs/{feature-name}/state.yaml`.
 | tasks | `references/step-7-tasks.md` |
 | implement | `references/step-8-implement.md` |
 
+Also write/update `.claude/ship-hook-state.json` with `phase`, `feature`, and `spec_dir` from state.yaml (set `sub_phase` to `null`).
+
 Read the step file for the current phase and follow its instructions.
 
 **If state.yaml does not exist**, this is a new feature. Create the spec directory and an initial state.yaml:
@@ -54,4 +56,15 @@ phase: intent
 dir: docs/specs/{feature-name}
 ```
 
+Also write `.claude/ship-hook-state.json` (enables policy enforcement for this session):
+
+```json
+{
+  "phase": "intent",
+  "feature": "{feature-name}",
+  "spec_dir": "docs/specs/{feature-name}",
+  "sub_phase": null
+}
+```
+
 Then read `references/step-1-intent.md` to begin.

package/src/skills/ship/references/step-1-intent.md

@@ -45,6 +45,6 @@ Present the intent document to the user for confirmation. Adjust if they have co
 
 ## Task 3: Proceed
 
-Update `{spec_dir}/state.yaml` — set `phase: questions`.
+Update `{spec_dir}/state.yaml` — set `phase: questions`. Update `.claude/ship-hook-state.json` — set `phase` to `"questions"`, `sub_phase` to `null`.
 
 Use the Read tool on `references/step-2-questions.md` to generate research questions from the intent.

package/src/skills/ship/references/step-2-questions.md

@@ -14,15 +14,15 @@ Create these tasks and work through them in order:
 
 ## Task 1: Generate Questions
 
-Read `{spec_dir}/intent.md` yourself, then spawn a sub-agent with the intent content passed inline in the prompt. The agent has `tools: Write` only — it cannot read any files.
+Spawn the question-generator sub-agent. Tell it the spec directory — it will read the intent document directly.
 
 ```
 Agent tool:
   subagent_type: "question-generator"
-  prompt: "Write research questions to {spec_dir}/questions.md based on this intent document:\n\n{paste the full intent.md content here}"
+  prompt: "Read the intent document at {spec_dir}/intent.md and write research questions to {spec_dir}/questions.md."
 ```
 
-The question-generator has zero read access. The intent content comes via the prompt, and its only tool is Write. It cannot explore the codebase.
+The question-generator has `tools: Read, Write` with hook-enforced path restrictions — it can only read `{spec_dir}/intent.md` and write to `{spec_dir}/questions.md`.
 
 ## Task 2: Review Questions
 
@@ -36,6 +36,6 @@ Update `questions.md` based on user feedback. The user may add questions about p
 
 ## Task 3: Proceed
 
-Update `{spec_dir}/state.yaml` — set `phase: research`.
+Update `{spec_dir}/state.yaml` — set `phase: research`. Update `.claude/ship-hook-state.json` — set `phase` to `"research"`, `sub_phase` to `null`.
 
 Use the Read tool on `references/step-3-research.md` to begin objective codebase research.

package/src/skills/ship/references/step-3-research.md

@@ -51,6 +51,6 @@ If the research is thin or missing critical areas, spawn the objective-researche
 
 ## Task 4: Proceed
 
-Update `{spec_dir}/state.yaml` — set `phase: design`.
+Update `{spec_dir}/state.yaml` — set `phase: design`. Update `.claude/ship-hook-state.json` — set `phase` to `"design"`, `sub_phase` to `null`.
 
 Use the Read tool on `references/step-4-design.md` to begin the design discussion with the user.

package/src/skills/ship/references/step-4-design.md

@@ -63,6 +63,6 @@ Present to the user for confirmation.
 
 ## Task 4: Proceed
 
-Update `{spec_dir}/state.yaml` — set `phase: spec`.
+Update `{spec_dir}/state.yaml` — set `phase: spec`. Update `.claude/ship-hook-state.json` — set `phase` to `"spec"`, `sub_phase` to `null`.
 
 Use the Read tool on `references/step-5-spec.md` to generate the implementation specification.

package/src/skills/ship/references/step-5-spec.md

@@ -38,7 +38,7 @@ Agent tool:
 
 ## Task 3: Review Loop
 
-Spawn a FRESH instance of spec-writer in review mode. At least one review is mandatory.
+Spawn a FRESH instance of spec-writer in review mode. At least one review is mandatory. Before each review cycle, update `.claude/ship-hook-state.json` `sub_phase` to `"review-cycle-N"` (N = cycle number, starting at 1).
 
 ```
 Agent tool:
@@ -71,6 +71,6 @@ Revise based on user feedback. If changes are substantial, re-run the review loo
 
 ## Task 5: Proceed
 
-Update `{spec_dir}/state.yaml` — set `phase: verify`.
+Update `{spec_dir}/state.yaml` — set `phase: verify`. Update `.claude/ship-hook-state.json` — set `phase` to `"verify"`, `sub_phase` to `null`.
 
 Use the Read tool on `references/step-6-verify.md` to plan verification for the spec.

package/src/skills/ship/references/step-6-verify.md

@@ -27,7 +27,7 @@ Agent tool:
 
 ## Task 2: Review Loop
 
-Spawn a FRESH instance of test-planner in review mode. At least one review is mandatory.
+Spawn a FRESH instance of test-planner in review mode. At least one review is mandatory. Before each review cycle, update `.claude/ship-hook-state.json` `sub_phase` to `"review-cycle-N"` (N = cycle number, starting at 1).
 
 ```
 Agent tool:
@@ -59,6 +59,6 @@ Ask the user if the verification strategy is complete. Revise based on feedback.
 
 ## Task 4: Proceed
 
-Update `{spec_dir}/state.yaml` — set `phase: tasks`.
+Update `{spec_dir}/state.yaml` — set `phase: tasks`. Update `.claude/ship-hook-state.json` — set `phase` to `"tasks"`, `sub_phase` to `null`.
 
 Use the Read tool on `references/step-7-tasks.md` to break the spec into implementation tasks.

package/src/skills/ship/references/step-7-tasks.md

@@ -25,7 +25,7 @@ Agent tool:
 
 ## Task 2: Review Loop
 
-Spawn a FRESH instance of task-breakdown in review mode:
+Spawn a FRESH instance of task-breakdown in review mode. Before each review cycle, update `.claude/ship-hook-state.json` `sub_phase` to `"review-cycle-N"` (N = cycle number, starting at 1):
 
 ```
 Agent tool:
@@ -55,6 +55,6 @@ Revise based on user feedback. If changes are substantial, re-run the review loo
 
 ## Task 4: Proceed
 
-Update `{spec_dir}/state.yaml` — set `phase: implement`.
+Update `{spec_dir}/state.yaml` — set `phase: implement`. Update `.claude/ship-hook-state.json` — set `phase` to `"implement"`, `sub_phase` to `null`.
 
 Use the Read tool on `references/step-8-implement.md` to begin implementation.

package/src/skills/ship/references/step-8-implement.md

@@ -43,7 +43,7 @@ Run independent tasks (no dependency between them) in parallel when possible. Al
 
 ## Step 3: Finalize
 
-Update `{spec_dir}/state.yaml` — set `phase: complete`.
+Update `{spec_dir}/state.yaml` — set `phase: complete`. Update `.claude/ship-hook-state.json` — set `phase` to `"complete"`, `sub_phase` to `null`.
 
 Present a summary to the user:
 

package/src/skills/ship/references/step-9-reflect.md

@@ -1,9 +1,13 @@
 # Reflect
 
-Review how this workflow performed and identify improvements.
+## Cleanup
+
+Delete `.claude/ship-hook-state.json` — policy enforcement is no longer needed for this feature.
 
 ## Self-Assessment
 
+Review how this workflow performed and identify improvements.
+
 Consider each phase:
 
 1. **Intent capture**: Did the intent document accurately capture what the user wanted? Did the spec drift from the original intent?