cc-dev-template 0.1.98 → 0.1.100

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cc-dev-template",
-  "version": "0.1.98",
+  "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/creating-agent-skills/references/create-step-2-design.md

@@ -57,6 +57,45 @@ Configuration: No special setting needed
 
 Configuration: `context: fork` (optionally add `agent: Explore` or `agent: Plan` for specialized behavior)
 
+## Design Constraints
+
+Only relevant for skills that orchestrate sub-agents or have clear role boundaries. Skip this section for simple informational skills or single-step workflows.
+
+### Constraint Mechanisms
+
+From weakest to strongest:
+
+| Mechanism | What It Does | Use When |
+|-----------|-------------|----------|
+| Prompt instructions | Advisory guidance in skill/agent text | Soft guidance, not security-critical |
+| `allowed-tools` (skill frontmatter) | Auto-approves listed tools (no user prompt). Does NOT block anything. | Reducing user friction for known-safe tools |
+| `tools` (agent frontmatter) | Grants ONLY listed tools to sub-agent. Everything else denied. | Coarse tool-level restriction (e.g., read-only agent) |
+| PreToolUse hook (settings.json) | Script checks every tool call against policy rules. Can inspect file paths, commands, agent identity. | Path-level enforcement, per-phase rules, cross-agent policies |
+| Inline content passing | Pass file contents in Agent prompt instead of letting agent read files. Combined with restricted `tools`, agent physically cannot access unauthorized files. | Contamination prevention, strongest isolation |
+
+### Constraint Design Questions
+
+Ask the user these questions when the skill involves sub-agents:
+
+- Should the orchestrator be restricted? (e.g., blocked from source code, forced to delegate)
+- Should sub-agents only access specific files/directories?
+- Are there contamination concerns? (agents that should be blind to certain information)
+- Should certain deliverables only be writable by specific agents?
+
+### Constraint Map
+
+If constraints are needed, produce a constraint map before designing frontmatter: which agent can do what, and which mechanism enforces each rule. This feeds into the frontmatter design and may require a hook script.
+
+Example format:
+```
+Orchestrator: no Bash, no source code reads → PreToolUse hook
+Researcher agent: tools: Read, Grep, Glob, Write → agent frontmatter
+Writer agent: only writes to docs/output/ → PreToolUse hook (path check)
+Reviewer agent: receives content inline, no file reads → inline content passing + tools: Write
+```
+
+Reference the creating-sub-agents skill for detailed sub-agent constraint configuration (tool sets, permission modes, hook examples).
+
 ## Design the Frontmatter
 
 Every skill has YAML frontmatter. Required and optional fields:
@@ -75,7 +114,7 @@ Every skill has YAML frontmatter. Required and optional fields:
 | `argument-hint` | Placeholder shown after slash command (e.g., `[issue-number]`, `[filename]`) |
 | `disable-model-invocation` | Set `true` to prevent Claude from auto-activating — use for side-effect workflows like deploy or commit |
 | `user-invocable` | Set `false` to hide from the `/` menu — use for background knowledge skills |
-| `allowed-tools` | Restrict which tools the skill can use (e.g., `Read, Grep, Glob` for read-only) |
+| `allowed-tools` | Pre-approve tools for auto-acceptance (user won't be prompted for these). Does NOT restrict — unlisted tools still work, they just require user approval. |
 | `model` | Override the model used when this skill is active |
 | `context` | Set `fork` to run in an isolated sub-agent context |
 | `agent` | Sub-agent type when `context: fork` is set (`Explore`, `Plan`, `general-purpose`, or custom) |

package/src/skills/creating-agent-skills/references/create-step-4-review.md

@@ -49,6 +49,12 @@ Go through each file and verify:
 - For informational skills: reflection section at the end of SKILL.md?
 - For forked-context skills: "Skill Observations" section in the output format?
 
+### Constraints
+- If the skill spawns sub-agents: are tool grants appropriate for each agent's role?
+- Is `allowed-tools` used correctly? (auto-approval only, not restriction)
+- If path-level restrictions are needed: is a PreToolUse hook designed?
+- Are constraint decisions documented in the skill (so future editors understand why)?
+
 ## Run Validation
 
 ```bash

package/src/skills/creating-agent-skills/scripts/validate-skill.js

@@ -167,6 +167,14 @@ if (!frontmatter.valid) {
       null,
       'Remove all < and > characters from frontmatter values');
   }
+
+  // Check: allowed-tools usage awareness
+  if (frontmatter.data['allowed-tools']) {
+    addFinding('CONSTRAINT', 'info',
+      'Skill uses allowed-tools — this pre-approves tools for auto-acceptance, it does NOT restrict tool access. If restriction is intended, use the tools field on sub-agent definitions instead.',
+      null,
+      'See creating-sub-agents skill for sub-agent tool restriction patterns');
+  }
 }
 
 // Check 3: Second person violations

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