cc-dev-template 0.1.99 → 0.1.100

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cc-dev-template",
-  "version": "0.1.99",
+  "version": "0.1.100",
   "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
+ * Shared mailbox: {cwd}/.claude/ship-hook-state.json
+ *   Written by orchestrator (doesn't know its session_id).
+ *
+ * Per-session: {cwd}/.claude/ship-sessions/{session_id}.json
+ *   Created by the hook when it intercepts a Write to the mailbox.
+ *   This is what the hook reads for enforcement.
  */
 
-const { readFileSync, writeFileSync, existsSync } = require('fs');
+const { readFileSync, writeFileSync, existsSync, mkdirSync, realpathSync } = require('fs');
 const { join, resolve, relative } = require('path');
 
 // Tools that bypass all policy checks
@@ -56,6 +61,16 @@ function relPath(tool, input, cwd) {
   return relative(cwd, abs);
 }
 
+function realResolve(p) {
+  const abs = resolve(p);
+  try { return realpathSync(abs); } catch {}
+  // File may not exist yet — resolve parent
+  const dir = resolve(abs, '..');
+  const base = require('path').basename(abs);
+  try { return join(realpathSync(dir), base); } catch {}
+  return abs;
+}
+
 function under(p, prefix) {
   const dir = prefix.replace(/\/$/, '');
   return p === dir || p.startsWith(dir + '/');
@@ -86,7 +101,7 @@ function orchestratorPolicy(tool, input, cwd, specDir, phase) {
     const p = relPath(tool, input, cwd);
     if (p === null || p === undefined) return allow();
 
-    // State files always writable
+    // State/mailbox files always writable
     if (p === `${specDir}/state.yaml` || p === '.claude/ship-hook-state.json') return allow();
 
     // Per-phase permissions
@@ -128,10 +143,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 +200,35 @@ const AGENT_POLICIES = {
 
 function main() {
   const input = JSON.parse(readFileSync(0, 'utf-8'));
-  const cwd = process.cwd();
+  let cwd;
+  try { cwd = realpathSync(process.cwd()); } catch { cwd = process.cwd(); }
   const stateFile = join(cwd, '.claude', 'ship-hook-state.json');
+  const sessionsDir = join(cwd, '.claude', 'ship-sessions');
+  const sessionFile = join(sessionsDir, `${input.session_id}.json`);
+
+  // Detect writes to the shared mailbox — copy content to per-session file
+  if ((input.tool_name === 'Write' || input.tool_name === 'Edit') && input.tool_input) {
+    const targetPath = input.tool_input.file_path;
+    if (targetPath && realResolve(targetPath) === stateFile) {
+      if (input.tool_name === 'Write') {
+        try {
+          mkdirSync(sessionsDir, { recursive: true });
+          writeFileSync(sessionFile, input.tool_input.content);
+        } catch {}
+      }
+      process.exit(0); // Allow the write (Edit is allowed too, per-session file stays slightly stale)
+    }
+  }
 
-  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/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/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,7 +56,7 @@ 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`.
 

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.
+Delete `.claude/ship-hook-state.json` and the `.claude/ship-sessions/` directory — policy enforcement is no longer needed for this feature.
 
 ## Self-Assessment