cc-dev-template 0.1.99 → 0.1.101

package/package.json

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

package/src/agents/objective-researcher.md

@@ -19,14 +19,14 @@ You do NOT know what feature is being built. You only have questions. Answer the
 
 1. Review the questions provided in your prompt
 2. For each question, explore the codebase using Grep, Glob, and Read
-3. Write findings to the output path provided in your prompt
+3. Use Edit to replace your placeholder in the research file with your findings (the placeholder and file path are specified in your prompt)
 
 ## Output Format
 
-For each question:
+Use Edit to replace your placeholder with content in this format — note the `###` heading level since `##` is used for category headers:
 
 ```markdown
-## Q: {Original question}
+### Q: {Original question}
 
 **Finding**: {Your answer with specific details}
 
@@ -42,7 +42,7 @@ For each question:
 After answering all questions, add a final section:
 
 ```markdown
-## Additional Observations
+### Additional Observations
 
 {Anything noteworthy you discovered while researching that wasn't directly asked about but seems relevant to understanding this area of the codebase}
 ```

package/src/scripts/ship-policy.js

@@ -5,12 +5,17 @@
  *
  * 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).
+ * ship is not active for the current session.
  *
- * State: {cwd}/.claude/ship-hook-state.json
+ * Per-session state: {cwd}/.claude/ship-sessions/{session_id}.json
+ *   Created/updated by this hook when it intercepts `ship-state.js`
+ *   Bash calls. The agent doesn't know its session_id — only the hook does.
+ *
+ * Feature state: {spec_dir}/state.yaml
+ *   Created/updated by ship-state.js (the CLI script the agent runs).
  */
 
-const { readFileSync, writeFileSync, existsSync } = require('fs');
+const { readFileSync, writeFileSync, existsSync, mkdirSync, unlinkSync, realpathSync } = require('fs');
 const { join, resolve, relative } = require('path');
 
 // Tools that bypass all policy checks
@@ -86,8 +91,8 @@ function orchestratorPolicy(tool, input, cwd, specDir, phase) {
     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();
+    // State file always writable
+    if (p === `${specDir}/state.yaml`) return allow();
 
     // Per-phase permissions
     const permFn = ORCHESTRATOR_WRITES[phase];
@@ -128,10 +133,10 @@ function objectiveResearcherPolicy(tool, input, cwd, specDir) {
     return allow();
   }
 
-  if (tool === 'Write') {
+  if (tool === 'Write' || tool === 'Edit') {
     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`);
+    return block(`objective-researcher can only write to ${specDir}/research.md`);
   }
 
   if (tool === 'Bash') return allow();
@@ -185,24 +190,58 @@ const AGENT_POLICIES = {
 
 function main() {
   const input = JSON.parse(readFileSync(0, 'utf-8'));
-  const cwd = process.cwd();
-  const stateFile = join(cwd, '.claude', 'ship-hook-state.json');
+  let cwd;
+  try { cwd = realpathSync(process.cwd()); } catch { cwd = process.cwd(); }
+  const sessionsDir = join(cwd, '.claude', 'ship-sessions');
+  const sessionFile = join(sessionsDir, `${input.session_id}.json`);
+
+  // Detect ship-state.js Bash calls — manage per-session state
+  if (input.tool_name === 'Bash' && input.tool_input) {
+    const cmd = input.tool_input.command || '';
+    const match = cmd.match(/ship-state\.js\s+(set|release)/);
+    if (match) {
+      const action = match[1];
+      if (action === 'set') {
+        const phaseMatch = cmd.match(/--phase\s+(\S+)/);
+        const featureMatch = cmd.match(/--feature\s+(\S+)/);
+        const specDirMatch = cmd.match(/--spec-dir\s+(\S+)/);
+        const subPhaseMatch = cmd.match(/--sub-phase\s+(?:"([^"]+)"|(\S+))/);
+        const subPhaseValue = subPhaseMatch ? (subPhaseMatch[1] || subPhaseMatch[2]) : null;
+
+        if (existsSync(sessionFile)) {
+          let state;
+          try { state = JSON.parse(readFileSync(sessionFile, 'utf-8')); } catch { state = {}; }
+          if (phaseMatch) { state.phase = phaseMatch[1]; state.sub_phase = null; }
+          if (featureMatch) state.feature = featureMatch[1];
+          if (specDirMatch) state.spec_dir = specDirMatch[1];
+          if (subPhaseValue) state.sub_phase = subPhaseValue;
+          writeFileSync(sessionFile, JSON.stringify(state, null, 2));
+        } else {
+          mkdirSync(sessionsDir, { recursive: true });
+          const state = {
+            phase: phaseMatch ? phaseMatch[1] : null,
+            feature: featureMatch ? featureMatch[1] : null,
+            spec_dir: specDirMatch ? specDirMatch[1] : null,
+            sub_phase: subPhaseValue,
+          };
+          writeFileSync(sessionFile, JSON.stringify(state, null, 2));
+        }
+      } else if (action === 'release') {
+        try { unlinkSync(sessionFile); } catch {}
+      }
+      process.exit(0);
+    }
+  }
 
-  if (!existsSync(stateFile)) process.exit(0);
+  // No per-session file = not a ship session — completely invisible
+  if (!existsSync(sessionFile)) process.exit(0);
+
+  if (BYPASS_TOOLS.has(input.tool_name)) process.exit(0);
 
   let state;
-  try { state = JSON.parse(readFileSync(stateFile, 'utf-8')); }
+  try { state = JSON.parse(readFileSync(sessionFile, '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 || {};

package/src/scripts/ship-state.js

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+
+/**
+ * Ship State CLI — manages feature state for the ship skill.
+ *
+ * Commands:
+ *   set --phase <p> --feature <f> --spec-dir <d>   Initial claim or resume
+ *   set --phase <p> --spec-dir <d>                  Phase transition
+ *   set --sub-phase <s>                             Review loop tracking (no-op here, hook handles it)
+ *   release                                         Cleanup sessions directory
+ *
+ * The PreToolUse hook (ship-policy.js) intercepts these Bash calls to manage
+ * per-session state files. This script handles feature-level state (state.yaml).
+ */
+
+const { readFileSync, writeFileSync, mkdirSync, rmSync, existsSync } = require('fs');
+const { join } = require('path');
+
+function parseArgs(args) {
+  const flags = {};
+  for (let i = 0; i < args.length; i++) {
+    if (args[i].startsWith('--')) {
+      const key = args[i].slice(2);
+      const val = args[i + 1] && !args[i + 1].startsWith('--') ? args[++i] : true;
+      flags[key] = val;
+    }
+  }
+  return flags;
+}
+
+const [command, ...rest] = process.argv.slice(2);
+
+if (command === 'set') {
+  const flags = parseArgs(rest);
+
+  // sub-phase only — hook handles per-session state, script is a no-op
+  if (flags['sub-phase'] && !flags.phase && !flags['spec-dir']) {
+    process.exit(0);
+  }
+
+  if (flags['spec-dir'] && flags.phase) {
+    const specDir = flags['spec-dir'];
+    mkdirSync(specDir, { recursive: true });
+
+    const stateFile = join(specDir, 'state.yaml');
+    const existed = existsSync(stateFile);
+    let yaml;
+
+    if (existed) {
+      yaml = readFileSync(stateFile, 'utf-8');
+      yaml = yaml.replace(/^phase:.*$/m, `phase: ${flags.phase}`);
+      if (flags.feature) {
+        yaml = yaml.replace(/^feature:.*$/m, `feature: ${flags.feature}`);
+      }
+    } else {
+      yaml = `feature: ${flags.feature || 'unknown'}\nphase: ${flags.phase}\ndir: ${specDir}\n`;
+    }
+
+    writeFileSync(stateFile, yaml);
+  }
+} else if (command === 'release') {
+  rmSync('.claude/ship-sessions/', { recursive: true, force: true });
+} else {
+  console.error(`Unknown command: ${command}`);
+  process.exit(1);
+}

package/src/scripts/statusline.js

@@ -560,13 +560,35 @@ function main() {
       usageLines.push(makeBoxLine(usageDisplay));
     }
 
-    // Ship phase line (if active)
+    // Ship phase line (if active) — read from per-session files
     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 sessionsDir = join(data.workspace.project_dir, '.claude', 'ship-sessions');
+      let shipState = null;
+
+      // Try session_id first (if available in input), otherwise most recently modified
+      if (data.session_id) {
+        const sessionFile = join(sessionsDir, `${data.session_id}.json`);
+        const st = statSync(sessionFile);
+        if (Date.now() - st.mtimeMs < 300000) {
+          shipState = JSON.parse(readFileSync(sessionFile, 'utf-8'));
+        }
+      } else {
+        // Fallback: most recently modified session file
+        const files = readdirSync(sessionsDir).filter(f => f.endsWith('.json'));
+        let latest = null;
+        let latestMtime = 0;
+        for (const f of files) {
+          const fp = join(sessionsDir, f);
+          const st = statSync(fp);
+          if (st.mtimeMs > latestMtime) { latestMtime = st.mtimeMs; latest = fp; }
+        }
+        if (latest && Date.now() - latestMtime < 300000) {
+          shipState = JSON.parse(readFileSync(latest, 'utf-8'));
+        }
+      }
+
+      if (shipState) {
         const phase = (shipState.phase || '').toUpperCase();
         const feature = shipState.feature || '';
         const subPhase = shipState.sub_phase ? ` ${shipState.sub_phase}` : '';

package/src/skills/ship/SKILL.md

@@ -44,27 +44,16 @@ 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`).
+Also run: `node ~/.claude/scripts/ship-state.js set --phase {phase} --feature {feature} --spec-dir {dir}` (using values from state.yaml).
 
 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:
+**If state.yaml does not exist**, this is a new feature. Run:
 
-```yaml
-feature: {feature-name}
-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
-}
+node ~/.claude/scripts/ship-state.js set --phase intent --feature {feature-name} --spec-dir docs/specs/{feature-name}
 ```
 
+This creates the spec directory, initializes state.yaml, and enables policy enforcement for this session.
+
 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 `.claude/ship-hook-state.json` — set `phase` to `"questions"`, `sub_phase` to `null`.
+Run: `node ~/.claude/scripts/ship-state.js set --phase questions --spec-dir {spec_dir}`
 
 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

@@ -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 `.claude/ship-hook-state.json` — set `phase` to `"research"`, `sub_phase` to `null`.
+Run: `node ~/.claude/scripts/ship-state.js set --phase research --spec-dir {spec_dir}`
 
 Use the Read tool on `references/step-3-research.md` to begin objective codebase research.

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

@@ -10,34 +10,41 @@ Questions are distributed across parallel researchers by category — each agent
 
 Create these tasks and work through them in order:
 
-1. "Group questions and distribute to parallel researchers" — spawn multiple objective-researchers
-2. "Merge research" — combine results into a single file
-3. "Review research with user" — present findings
-4. "Begin design discussion" — proceed to the next phase
+1. "Create research skeleton and distribute to parallel researchers" — spawn multiple objective-researchers
+2. "Review research with user" — present findings
+3. "Begin design discussion" — proceed to the next phase
 
 ## Task 1: Distribute Research
 
 Read `{spec_dir}/questions.md` yourself. Identify the category sections (the `##` headers the question-generator produces).
 
-For each category, spawn an `objective-researcher` with that category's questions passed inline. Spawn ALL agents in parallel — use multiple Agent tool calls in a single message.
+Create a skeleton `{spec_dir}/research.md` with a `## {Category Name}` header for each category and a unique placeholder line beneath it:
 
-Each agent writes to a separate file to avoid write conflicts:
+```markdown
+## Authentication
+
+<!-- PENDING: authentication -->
+
+## Database Schema
+
+<!-- PENDING: database-schema -->
+```
+
+Then for each category, spawn an `objective-researcher` with that category's questions passed inline. Spawn ALL agents in parallel — use multiple Agent tool calls in a single message.
+
+Tell each researcher to use Edit to replace its placeholder in the shared research file:
 
 ```
 Agent tool:
   subagent_type: "objective-researcher"
-  prompt: "Research the codebase to answer these questions. Write your findings to {spec_dir}/research-{category-slug}.md.\n\n{paste this category's questions here}"
+  prompt: "Research the codebase to answer these questions. Use Edit to replace the placeholder <!-- PENDING: {category-slug} --> in {spec_dir}/research.md with your findings.\n\n{paste this category's questions here}"
 ```
 
 If there are many small categories (6+), group related ones together to keep the agent count reasonable — 3 to 5 parallel agents is the sweet spot.
 
 The objective-researcher has full codebase access (Read, Grep, Glob, Bash) but no knowledge of the feature being built. It receives only the questions via its prompt — it never reads from docs/.
 
-## Task 2: Merge Research
-
-After all researchers complete, read each `research-{slug}.md` file. Concatenate them into a single `{spec_dir}/research.md` (preserving the section structure from each file). Then delete the individual `research-{slug}.md` files — downstream steps only need the merged file.
-
-## Task 3: Review Research
+## Task 2: Review Research
 
 Read `{spec_dir}/research.md` and present a summary to the user. Highlight:
 
@@ -49,8 +56,8 @@ The user may add context the researcher missed, or flag patterns that are outdat
 
 If the research is thin or missing critical areas, spawn the objective-researcher again with additional targeted questions.
 
-## Task 4: Proceed
+## Task 3: Proceed
 
-Update `{spec_dir}/state.yaml` — set `phase: design`. Update `.claude/ship-hook-state.json` — set `phase` to `"design"`, `sub_phase` to `null`.
+Run: `node ~/.claude/scripts/ship-state.js set --phase design --spec-dir {spec_dir}`
 
 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 `.claude/ship-hook-state.json` — set `phase` to `"spec"`, `sub_phase` to `null`.
+Run: `node ~/.claude/scripts/ship-state.js set --phase spec --spec-dir {spec_dir}`
 
 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. Before each review cycle, update `.claude/ship-hook-state.json` `sub_phase` to `"review-cycle-N"` (N = cycle number, starting at 1).
+Spawn a FRESH instance of spec-writer in review mode. At least one review is mandatory. Before each review cycle, run: `node ~/.claude/scripts/ship-state.js set --sub-phase "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 `.claude/ship-hook-state.json` — set `phase` to `"verify"`, `sub_phase` to `null`.
+Run: `node ~/.claude/scripts/ship-state.js set --phase verify --spec-dir {spec_dir}`
 
 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. Before each review cycle, update `.claude/ship-hook-state.json` `sub_phase` to `"review-cycle-N"` (N = cycle number, starting at 1).
+Spawn a FRESH instance of test-planner in review mode. At least one review is mandatory. Before each review cycle, run: `node ~/.claude/scripts/ship-state.js set --sub-phase "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 `.claude/ship-hook-state.json` — set `phase` to `"tasks"`, `sub_phase` to `null`.
+Run: `node ~/.claude/scripts/ship-state.js set --phase tasks --spec-dir {spec_dir}`
 
 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. Before each review cycle, update `.claude/ship-hook-state.json` `sub_phase` to `"review-cycle-N"` (N = cycle number, starting at 1):
+Spawn a FRESH instance of task-breakdown in review mode. Before each review cycle, run: `node ~/.claude/scripts/ship-state.js set --sub-phase "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 `.claude/ship-hook-state.json` — set `phase` to `"implement"`, `sub_phase` to `null`.
+Run: `node ~/.claude/scripts/ship-state.js set --phase implement --spec-dir {spec_dir}`
 
 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 `.claude/ship-hook-state.json` — set `phase` to `"complete"`, `sub_phase` to `null`.
+Run: `node ~/.claude/scripts/ship-state.js set --phase complete --spec-dir {spec_dir}`
 
 Present a summary to the user:
 

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

@@ -2,7 +2,7 @@
 
 ## Cleanup
 
-Delete `.claude/ship-hook-state.json` — policy enforcement is no longer needed for this feature.
+Run: `node ~/.claude/scripts/ship-state.js release` — this cleans up per-session state and the sessions directory.
 
 ## Self-Assessment