cc-dev-template 0.1.42 → 0.1.44

package/bin/install.js

@@ -233,8 +233,7 @@ if (fs.existsSync(mergeSettingsPath)) {
     { file: 'read-guard-hook.json', name: 'Context guard for large reads' },
     { file: 'statusline-config.json', name: 'Custom status line' },
     { file: 'bash-overflow-hook.json', name: 'Bash overflow guard hook' },
-    { file: 'bash-precheck-hook.json', name: 'Bash precheck hook' },
-    { file: 'plan-agent-hook.json', name: 'Plan agent context injection hook' }
+    { file: 'bash-precheck-hook.json', name: 'Bash precheck hook' }
   ];
 
   configs.forEach(({ file, name }) => {

package/package.json

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

package/src/commands/done.md

@@ -21,14 +21,9 @@ This requires full conversation context. Handle it yourself rather than delegati
 
 **1. Run the code simplifier**
 
-Run the code-simplifier agent on your staged changes before committing. This refines code for clarity and consistency.
+Stage your changes, then use the code simplifier agent to refine them for clarity and consistency. Run tests afterward to verify nothing broke.
 
-1. Stage your changes with `git add`
-2. Launch the code-simplifier agent (look for it in available subagent types) targeting the staged files
-3. Run the build and tests to verify nothing broke
-4. Fix any issues before proceeding to commit
-
-Note: The code-simplifier is a plugin. If no code-simplifier agent is available, proceed to step 2.
+Skip this step if no code simplifier agent is available.
 
 **2. Commit your work**
 

package/src/skills/creating-agent-skills/references/create.md

@@ -9,8 +9,7 @@
 - [Step 4: Write the Skill](#step-4-write-the-skill)
 - [Step 5: Choose Install Location](#step-5-choose-install-location)
 - [Step 6: Validate](#step-6-validate-feedback-loop)
-- [Step 7: Create Slash Command](#step-7-create-slash-command-optional)
-- [Step 8: Test](#step-8-test)
+- [Step 7: Test](#step-7-test)
 - [Key Principles](#key-principles)
 - [Quality Check](#quality-check)
 
@@ -27,7 +26,6 @@ Copy and track progress:
 - [ ] Wrote skill as instructions (not docs)
 - [ ] Chose install location
 - [ ] Validated (loop until clean)
-- [ ] Offered slash command (optional)
 - [ ] Tested activation
 ```
 
@@ -130,42 +128,11 @@ Then manually verify:
 - Would Claude know what to DO after reading this?
 - Is heavy content in references/, not inline?
 
-## Step 7: Create Slash Command (Optional)
-
-Ask the user: "Would you like a slash command to explicitly invoke this skill?"
-
-**When to recommend a command:**
-- Skills that users will invoke frequently
-- Skills where explicit invocation is clearer than description matching
-- Skills that are the entry point to complex workflows
-
-**If yes, create a command file:**
-
-```markdown
----
-description: [Same as or similar to skill description]
----
-
-Invoke the [skill-name] skill immediately:
-
-```
-Skill(skill: "[skill-name]")
-```
-
-The skill contains all workflow instructions. Do not proceed until you have invoked the skill.
-```
-
-**Location:**
-- User level: `~/.claude/commands/[command-name].md`
-- Project level: `.claude/commands/[command-name].md`
-
-**Naming:** Command name is typically the skill name without gerund (e.g., skill `creating-reports` → command `/create-report`).
-
-## Step 8: Test
+## Step 7: Test
 
 Guide the user:
 1. Restart Claude Code
-2. Say one of the trigger phrases (or use the slash command if created)
+2. Say one of the trigger phrases or use `/skill-name` to invoke directly
 3. Verify the skill activates and behaves as expected
 
 If it doesn't work, iterate. The conversation isn't over until the skill works.

package/src/skills/creating-agent-skills/references/principles.md

@@ -250,15 +250,10 @@ Claude reads skill descriptions and decides when to activate based on user reque
 - Fails if description is too detailed
 
 **2. Explicit (Slash Command)**
-A slash command forces skill activation:
-```markdown
-# /create-skill command
-Activate the creating-agent-skills skill to guide the user through skill creation.
-```
-Most reliable method.
+Every skill automatically works as a slash command using `/skill-name`. This is the most reliable activation method.
 
 **3. Hybrid (Recommended)**
-Slash command for explicit invocation + good description for autonomous discovery.
+Use `/skill-name` for explicit invocation when needed, while a good description enables autonomous discovery for natural conversations.
 
 ## Iterative Development
 

package/src/skills/spec-interview/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: spec-interview
+description: This skill helps create thorough feature specifications through conversation. Use when the user says "spec out a feature", "create a specification", "design a feature", "I need to plan a feature", or wants to document requirements before building.
+argument-hint: <spec-name>
+---
+
+# Spec Interview
+
+Guide the user through creating a complete feature specification via structured conversation.
+
+## What To Do Now
+
+1. **Ask what feature they want to spec out** using AskUserQuestion
+2. **Create the spec directory** at `docs/specs/<feature-name>/`
+3. **Begin the interview** - read `references/interview-guide.md`
+
+## Key Principles
+
+**Interviewer, not form.** Have a natural conversation. Ask follow-up questions. Dig into details that seem unclear.
+
+**Subagents for research.** Offload exploration and research to subagents to keep the main interview context clean. They return only relevant findings.
+
+**One or two questions at a time.** Use AskUserQuestion liberally. This is a conversation, not an interrogation.
+
+**Implementation-ready output.** The finished spec should enable hands-off implementation with zero clarification needed.
+
+## Spec Location
+
+Specs live at: `docs/specs/<feature-name>/spec.md`
+
+The feature name is derived from the user's description (kebab-case, concise).
+
+## When You Think the Spec is Complete
+
+Before finalizing, invoke the `spec-review` skill to check for gaps. It will return specific feedback. If gaps exist, ask follow-up questions to address them.
+
+Only finalize when review passes.

package/src/skills/spec-interview/references/interview-guide.md

@@ -0,0 +1,123 @@
+# Interview Guide
+
+## The Interview Flow
+
+This is a conversation, not a checklist march. But ensure all areas get covered naturally.
+
+### Opening
+
+Start with open-ended understanding:
+- "Tell me about this feature. What problem does it solve?"
+- "Who will use this? What's their goal?"
+- "Walk me through what success looks like."
+
+Let the user talk. Ask follow-ups on anything unclear.
+
+### Areas to Cover
+
+Cover these naturally through conversation. Don't force the order.
+
+**Intent & Goals**
+- What is the user trying to accomplish?
+- Why does this matter? What's the business/user value?
+- What does success look like? How will we know it's working?
+
+**Integration Points**
+- What existing parts of the system does this touch?
+- Are there external services, APIs, or libraries involved?
+- What data flows in and out?
+
+→ *Use subagents to investigate the current codebase when integration questions arise.*
+
+**Data Model**
+- What entities/objects are involved?
+- What are the relationships between them?
+- What constraints exist (required fields, validations, limits)?
+- Are we extending existing models or creating new ones?
+
+**Behavior & Flows**
+- What are the main user flows?
+- What triggers this feature? What happens step by step?
+- Are there different modes or variations?
+
+**Edge Cases & Error Handling**
+- What can go wrong?
+- What happens with invalid input?
+- What are the boundary conditions?
+- How do we handle partial failures?
+
+**Acceptance Criteria**
+- How do we verify this works?
+- What are the specific, testable requirements?
+- What would make this "done"?
+
+**Blockers & Dependencies**
+- What external dependencies exist? (APIs, services, libraries)
+- Are there credentials, API keys, or access needed?
+- Are there decisions that need to be made before implementation?
+- Is anything waiting on external input?
+
+### Research During Interview
+
+When you need to understand something about the current system, external libraries, or technical feasibility:
+
+- Use **Explore agents** to investigate the codebase or research external APIs/libraries
+- Use **Plan agents** to evaluate technical approaches or architectural decisions
+
+Keep the main interview context clean. Agents return only the relevant findings you need to continue the conversation.
+
+### Writing the Spec
+
+As you gather information, write to `docs/specs/<name>/spec.md`. Update it incrementally during the conversation.
+
+**Spec structure:**
+
+```markdown
+# [Feature Name]
+
+## Overview
+[2-3 sentences: what this is and why it matters]
+
+## Goals
+- [Primary goal]
+- [Secondary goals if any]
+
+## Integration Points
+[How this connects to existing system]
+- Touches: [existing components]
+- External: [APIs, services, libraries]
+- Data flows: [in/out]
+
+## Data Model
+[Entities, relationships, constraints]
+
+## Behavior
+### [Flow 1]
+[Step by step]
+
+### [Flow 2]
+[Step by step]
+
+## Edge Cases
+- [Edge case]: [how handled]
+
+## Acceptance Criteria
+- [ ] [Testable requirement]
+- [ ] [Testable requirement]
+
+## Blockers
+- [ ] [Blocker]: [what's needed]
+- [ ] [Decision needed]: [options]
+```
+
+### Completion Check
+
+When the spec seems complete, invoke the `spec-review` skill and specify which spec to review in the prompt. It analyzes the spec and returns feedback. If gaps are found, ask follow-up questions. Repeat until review passes.
+
+### Finalizing
+
+Once review passes:
+1. Confirm with user and show the final spec
+2. Ask if they want to proceed to task breakdown
+
+If yes, invoke the `spec-to-tasks` skill and specify which spec to break down.

package/src/skills/spec-review/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: spec-review
+description: Reviews a feature specification for completeness. Called by spec-interview when a spec seems complete, or invoke directly with "review the spec", "check spec completeness", "is this spec ready".
+argument-hint: <spec-name>
+context: fork
+---
+
+# Spec Review
+
+Analyze a specification for completeness and identify gaps.
+
+## What To Do
+
+1. **Identify the spec to review** - use the spec path if specified in the prompt, otherwise check git for the most recently modified spec in `docs/specs/`
+2. **Read the spec file**
+3. **Evaluate against the checklist below**
+4. **Return structured feedback**
+
+## Completeness Checklist
+
+A spec is implementation-ready when ALL of these are satisfied:
+
+### Must Have (Blocking if missing)
+
+- [ ] **Clear intent** - What is being built and why is unambiguous
+- [ ] **Data model defined** - Entities, relationships, and constraints are explicit
+- [ ] **Integration points mapped** - What existing code this touches is documented
+- [ ] **Core behavior specified** - Main flows are step-by-step clear
+- [ ] **Acceptance criteria exist** - Testable requirements are listed
+
+### Should Have (Gaps that cause implementation friction)
+
+- [ ] **Edge cases covered** - Error conditions and boundaries are addressed
+- [ ] **External dependencies documented** - APIs, libraries, services are listed
+- [ ] **Blockers section exists** - Missing credentials, pending decisions are called out
+
+### Implementation Readiness
+
+Ask yourself: "Could someone implement this feature completely hands-off, with zero questions?"
+
+Check for:
+- Vague language ("should handle errors appropriately" → HOW?)
+- Missing details ("integrates with auth" → WHERE? HOW?)
+- Unstated assumptions ("uses the standard pattern" → WHICH pattern?)
+- Blocking dependencies ("needs API access" → DO WE HAVE IT?)
+
+## Output Format
+
+Return the review as:
+
+```
+## Spec Review: [Feature Name]
+
+### Status: [READY | NEEDS WORK]
+
+### Missing (Blocking)
+- [Item]: [What's missing and why it blocks implementation]
+
+### Gaps (Non-blocking but should address)
+- [Item]: [What's unclear or incomplete]
+
+### Blocking Dependencies
+- [Dependency]: [What's needed before implementation can start]
+
+### Recommendation
+[Specific questions to ask the user, or "Spec is implementation-ready"]
+```
+
+If status is READY, the spec can proceed to task breakdown.
+If status is NEEDS WORK, list the specific questions that need answers.

package/src/skills/spec-to-tasks/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: spec-to-tasks
+description: Breaks a feature specification into implementation tasks. Use when the user says "break down the spec", "create tasks from spec", "generate task list", or after a spec review passes.
+argument-hint: <spec-name>
+context: fork
+---
+
+# Spec to Tasks
+
+Convert a completed specification into an ordered list of atomic implementation tasks.
+
+## What To Do
+
+1. **Identify the spec** - use the spec path if specified in the prompt, otherwise check git for the most recently modified spec in `docs/specs/`
+2. **Explore the codebase** - use a subagent to identify existing patterns, conventions, and where code should live
+3. **Generate the task manifest** - create `tasks.yaml` in the same directory as the spec
+4. **Review with user** - show the task list for approval
+
+## Task Principles
+
+**Atomic tasks.** Each task is a single, focused change:
+- One model/entity
+- One endpoint/route
+- One component
+- One test file
+
+A task should take an AI agent one focused session to complete.
+
+**Ordered by dependency.** Tasks are sequenced so each can be completed in order without blocking.
+
+**Include file paths.** Each task specifies the target file(s) based on codebase exploration.
+
+**No code in tasks.** Tasks describe WHAT to do, not HOW. Implementation details are in the spec.
+
+## Task Format
+
+Write to `docs/specs/<name>/tasks.yaml`:
+
+```yaml
+spec: <name>
+spec_path: docs/specs/<name>/spec.md
+generated: <ISO timestamp>
+
+tasks:
+  - id: T001
+    title: <Short descriptive title>
+    description: |
+      <What to implement>
+      <Reference to spec section if applicable>
+    files:
+      - <path/to/file.ts>
+    depends_on: []
+    acceptance: |
+      <How to verify this task is complete>
+
+  - id: T002
+    title: <Next task>
+    description: |
+      <What to implement>
+    files:
+      - <path/to/file.ts>
+    depends_on: [T001]
+    acceptance: |
+      <Verification criteria>
+```
+
+## Generating File Paths
+
+Before writing tasks, explore the codebase to understand:
+- Existing file patterns (where do models live? services? routes?)
+- Specific files that need modification
+- New files that need creation and where they should go
+
+Use these findings to populate the `files` field for each task.
+
+## Ordering Tasks
+
+Sequence by dependency:
+1. **Data layer first** - Models, schemas, database changes
+2. **Business logic** - Services, utilities, core functions
+3. **API layer** - Routes, controllers, endpoints
+4. **Integration** - Connecting components, wiring up
+5. **Tests** - Can be parallel with implementation or after
+
+If tasks are independent, give them the same `depends_on`. This signals they could run in parallel.
+
+## Output
+
+After generating:
+1. Show the user a summary: number of tasks, estimated scope
+2. List the task titles in order
+3. Ask if they want to see the full YAML or proceed to implementation
+
+Save the manifest to `docs/specs/<name>/tasks.yaml`.

package/src/hooks/plan-agent-context.js

@@ -1,154 +0,0 @@
-#!/usr/bin/env node
-/**
- * plan-agent-context.js - PreToolUse hook for Task sub-agents
- *
- * Intercepts ALL Task calls and:
- * 1. Forces model: "opus" on every Task call
- * 2. For Plan agents (subagent_type: "Plan"), also injects ADRs and planning guidance
- */
-
-const fs = require('fs');
-const path = require('path');
-
-// js-yaml is loaded lazily in collectADRs() to handle missing dependency gracefully
-
-// Read hook input from stdin
-let input = '';
-process.stdin.setEncoding('utf8');
-process.stdin.on('data', chunk => input += chunk);
-process.stdin.on('end', () => {
-  try {
-    const hookInput = JSON.parse(input);
-    const result = processHook(hookInput);
-    console.log(JSON.stringify(result));
-  } catch (err) {
-    // On error, allow the tool call to proceed unchanged
-    console.log(JSON.stringify({
-      hookSpecificOutput: {
-        hookEventName: "PreToolUse",
-        permissionDecision: "allow"
-      }
-    }));
-  }
-});
-
-function processHook(hookInput) {
-  const toolInput = hookInput.tool_input || {};
-
-  // Base override: force opus model on ALL Task calls
-  const updatedInput = {
-    ...toolInput,
-    model: "opus"
-  };
-
-  // For Plan agent calls, also inject ADRs and planning guidance
-  if (toolInput.subagent_type === 'Plan') {
-    const adrs = collectADRs();
-    const planningGuidance = buildPlanningGuidance(adrs);
-    const originalPrompt = toolInput.prompt || '';
-    updatedInput.prompt = `${planningGuidance}\n\n---\n\nORIGINAL TASK:\n${originalPrompt}`;
-  }
-
-  return {
-    hookSpecificOutput: {
-      hookEventName: "PreToolUse",
-      permissionDecision: "allow",
-      updatedInput
-    }
-  };
-}
-
-function collectADRs() {
-  const adrDir = path.join(process.cwd(), '.claude', 'adrs');
-  const adrs = [];
-
-  // Try to load js-yaml - if unavailable, skip ADR collection entirely
-  let yaml;
-  try {
-    yaml = require('js-yaml');
-  } catch (err) {
-    // js-yaml not available - return empty array (ADR injection is best-effort)
-    return adrs;
-  }
-
-  if (!fs.existsSync(adrDir)) {
-    return adrs;
-  }
-
-  const files = fs.readdirSync(adrDir).filter(f => f.endsWith('.yaml'));
-
-  for (const file of files) {
-    try {
-      const content = fs.readFileSync(path.join(adrDir, file), 'utf8');
-      const adr = yaml.load(content);
-      if (adr && adr.status !== 'Superseded') {
-        adrs.push({
-          id: adr.id,
-          title: adr.title,
-          description: adr.description,
-          constraints: adr.constraints,
-          decision: adr.decision
-        });
-      }
-    } catch (err) {
-      // Skip malformed ADRs
-    }
-  }
-
-  return adrs;
-}
-
-function buildPlanningGuidance(adrs) {
-  let guidance = `<plan-agent-context>
-## Planning Guidelines
-
-You are creating an implementation plan. Follow these principles:
-
-### Research Before Planning
-- If the plan involves third-party libraries, APIs, or features not yet in the codebase, use WebSearch or WebFetch to get current documentation
-- Do not assume library APIs - verify them with up-to-date sources
-- Check compatibility with the project's infrastructure and existing patterns
-
-### Remove Ambiguity
-- Each step in your plan should be concrete and actionable
-- If requirements are unclear, surface the ambiguity rather than making assumptions
-- Identify decision points that need user input before execution
-
-### ADR Compliance
-The plan must respect these architectural decisions:
-
-`;
-
-  if (adrs.length === 0) {
-    guidance += `(No ADRs found in this project)\n`;
-  } else {
-    for (const adr of adrs) {
-      guidance += `### ${adr.id}: ${adr.title}\n`;
-      if (adr.description) {
-        guidance += `${adr.description.trim()}\n`;
-      }
-      if (adr.constraints) {
-        if (adr.constraints.must && adr.constraints.must.length > 0) {
-          guidance += `**MUST:**\n`;
-          for (const c of adr.constraints.must) {
-            guidance += `- ${c}\n`;
-          }
-        }
-        if (adr.constraints.must_not && adr.constraints.must_not.length > 0) {
-          guidance += `**MUST NOT:**\n`;
-          for (const c of adr.constraints.must_not) {
-            guidance += `- ${c}\n`;
-          }
-        }
-      }
-      if (adr.decision) {
-        guidance += `**Decision:** ${adr.decision.trim()}\n`;
-      }
-      guidance += `\n`;
-    }
-  }
-
-  guidance += `</plan-agent-context>`;
-
-  return guidance;
-}

package/src/hooks/plan-agent-hook.json

@@ -1,15 +0,0 @@
-{
-  "hooks": {
-    "PreToolUse": [
-      {
-        "matcher": "Task",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node $HOME/.claude/hooks/plan-agent-context.js"
-          }
-        ]
-      }
-    ]
-  }
-}