cc-dev-template 0.1.43 → 0.1.45

package/package.json

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

package/src/skills/claude-md/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: claude-md
+description: This skill should be used when working with CLAUDE.md files. Activate when the user asks to "audit CLAUDE.md", "create a CLAUDE.md", "update the CLAUDE.md", "clean up CLAUDE.md files", or "check CLAUDE.md best practices". Also activate proactively whenever about to create or modify any CLAUDE.md file - the skill contains required principles for how these files should be written.
+---
+
+# CLAUDE.md Management
+
+Base directory for this skill: ~/.claude/skills/claude-md
+
+## When This Activates
+
+- User asks to audit, create, update, or clean up CLAUDE.md files
+- You are about to create or modify any CLAUDE.md file
+
+**If you're about to touch a CLAUDE.md file, read this skill first.**
+
+## What To Do
+
+Determine the task:
+
+| Task | Action |
+|------|--------|
+| **Creating** a new CLAUDE.md | Read `references/create.md` |
+| **Modifying** an existing CLAUDE.md | Read `references/principles.md`, then edit |
+| **Auditing** a project's CLAUDE.md files | Read `references/audit.md` |
+
+## Core Principle
+
+CLAUDE.md files are **orientation prompts**. They answer: "Where am I? What matters here? What should I know that I can't read from the code?"
+
+The test: **Would Claude know where it is and what matters?**
+
+## Quick Reference
+
+**Belongs in CLAUDE.md:**
+- Why this folder/repo exists
+- Current focus (what matters NOW)
+- Where to find things (progressive disclosure)
+- Tribal knowledge, gotchas, non-obvious learnings
+- Project conventions not obvious from code
+
+**Does NOT belong:**
+- Content duplicated from parent CLAUDE.md (hierarchy is automatic)
+- Step-by-step workflows (put in docs or skills)
+- Detailed examples (trust the model)
+- Operational runbooks
+- Anything over ~100 lines (suspect)
+
+## Hierarchy Rule
+
+Claude automatically reads CLAUDE.md files up through the directory tree. A child file inherits everything from its parents.
+
+**Never duplicate parent content in child files.** Each file should only contain what's specific to that folder.
+
+For full principles, read `references/principles.md`.

package/src/skills/claude-md/references/audit.md

@@ -0,0 +1,115 @@
+# Auditing CLAUDE.md Files
+
+## Process
+
+1. **Discover** - Find all CLAUDE.md files in the project
+2. **Map hierarchy** - Understand parent-child relationships
+3. **Check each file** - Against principles
+4. **Fix issues** - Automatically apply best practices
+
+## Step 1: Discover
+
+Find all CLAUDE.md files:
+
+```bash
+find . -name "CLAUDE.md" -type f | head -20
+```
+
+Or use Glob:
+```
+**/CLAUDE.md
+```
+
+## Step 2: Map Hierarchy
+
+For each file, identify:
+- Its parent CLAUDE.md files (walking up the tree)
+- Its child CLAUDE.md files (in subdirectories)
+
+This matters because content flows down. Children inherit from parents.
+
+## Step 3: Check Each File
+
+Read each CLAUDE.md and check for these issues:
+
+### Length Issues
+| Check | Issue | Fix |
+|-------|-------|-----|
+| Over 100 lines | Probably bloated | Extract workflows to docs, remove duplication |
+| Over 150 lines | Definitely bloated | Aggressive pruning needed |
+
+### Content Issues
+| Check | Issue | Fix |
+|-------|-------|-----|
+| Step-by-step workflows | Doesn't belong | Move to docs/ or skills/, leave pointer |
+| Detailed examples | Over-explaining | Remove, trust the model |
+| Credentials/passwords | Security + bloat | Move to dedicated docs |
+| Duplicate of parent | Redundant | Remove entirely |
+
+### Structure Issues
+| Check | Issue | Fix |
+|-------|-------|-----|
+| No clear purpose statement | Disorienting | Add one-line description at top |
+| Missing "Current Focus" | For active projects | Add if this is active work |
+| Walls of text | Hard to scan | Break into sections, use bullets |
+
+### Hierarchy Issues
+| Check | Issue | Fix |
+|-------|-------|-----|
+| Child repeats parent content | Duplication | Remove from child |
+| Child has general project info | Wrong level | Move to root CLAUDE.md |
+| Deep file (3+ levels) exists | Probably unnecessary | Consider removing |
+
+## Step 4: Fix Issues
+
+For each issue found:
+
+1. **Read the file** (required before editing)
+2. **Apply the fix** using Edit tool
+3. **Move extracted content** to appropriate location (docs/, etc.)
+4. **Verify** the result
+
+### Common Fixes
+
+**Extracting a workflow:**
+1. Create `docs/workflows/[topic].md` with the detailed content
+2. Replace in CLAUDE.md with: "See `docs/workflows/[topic].md` for [description]"
+
+**Removing duplication:**
+1. Check parent file has the content
+2. Delete the duplicated section from child
+3. Optionally add: "Inherits [topic] from parent CLAUDE.md"
+
+**Pruning over-explanation:**
+1. Identify the core point
+2. Reduce to 1-2 lines that trust the model
+3. Remove examples, edge cases, detailed instructions
+
+## Audit Report
+
+After checking all files, summarize:
+
+```
+CLAUDE.md Audit Summary
+=======================
+Files checked: X
+Issues found: Y
+Issues fixed: Z
+
+Changes made:
+- [file]: [what was fixed]
+- [file]: [what was fixed]
+
+Remaining concerns:
+- [any issues that need human decision]
+```
+
+## Red Flags
+
+These indicate a CLAUDE.md that needs significant rework:
+
+- **200+ lines** - Needs major pruning
+- **Code blocks with >10 lines** - Workflows belong in docs
+- **Tables with >5 rows** - Probably too detailed
+- **Multiple "how to" sections** - Wrong content type
+- **Same content in parent and child** - Hierarchy violation

package/src/skills/claude-md/references/create.md

@@ -0,0 +1,72 @@
+# Creating a CLAUDE.md
+
+## Before Writing
+
+1. **Check the hierarchy** - Find all parent CLAUDE.md files up to the root
+2. **Read them** - Understand what's already covered
+3. **Identify the gap** - What does this folder need that parents don't provide?
+
+If the parent files already cover everything, you probably don't need a new CLAUDE.md.
+
+## Structure Template
+
+Use this as a starting point, not a rigid template. Include only sections that add value.
+
+```markdown
+# [Folder/Project Name]
+
+[One-line description of what this is and why it exists]
+
+## Current Focus
+
+[What's actively being worked on. What matters NOW.]
+
+## [Key Section]
+
+[Whatever is most important for this specific folder - could be dev commands, structure, rules, etc.]
+
+## Finding Information
+
+[Where to look for docs, workflows, detailed guides - progressive disclosure]
+
+## Gotchas
+
+[Non-obvious things that would save pain if known upfront]
+```
+
+## Guidelines
+
+### Keep It Short
+Aim for 40-80 lines. If you're going longer, you're probably including content that belongs elsewhere.
+
+### Lead with Purpose
+The first lines should orient Claude immediately. What is this? Why does it exist?
+
+### Current Focus Section
+Include this for active projects. It answers "what matters NOW?" and helps Claude prioritize.
+
+### Be Specific to This Folder
+Everything in this file should be specific to this directory. General project info belongs in the root CLAUDE.md.
+
+### Progressive Disclosure
+Point to docs, don't inline them:
+- Good: "See `docs/systems/M5_CLOUD.md` for server access"
+- Bad: [50 lines of SSH commands and credentials]
+
+## What NOT to Include
+
+- Content from parent CLAUDE.md files
+- Step-by-step workflows (put in docs/)
+- Detailed examples (trust the model)
+- Frequently changing content
+- Anything Claude could infer from the code
+
+## After Writing
+
+Verify:
+1. Under 100 lines?
+2. No duplication with parent files?
+3. Would Claude know where it is and what matters?
+4. Written as orientation, not documentation?
+
+If all yes, you're done.

package/src/skills/claude-md/references/principles.md

@@ -0,0 +1,132 @@
+# CLAUDE.md Principles
+
+## The Mental Model
+
+CLAUDE.md files are prompts for orienting Claude in a codebase. They're read automatically when Claude works in a directory.
+
+**Think of it as a briefing for a senior colleague joining the project** - not a manual for a junior who needs hand-holding.
+
+## The Test
+
+After reading a CLAUDE.md, would Claude know:
+1. Where it is (what is this folder/repo?)
+2. What matters NOW (current focus, active work)
+3. Where to find things (progressive disclosure to docs)
+4. What gotchas exist (tribal knowledge)
+
+If yes, the file is doing its job.
+
+## What Belongs
+
+### Purpose and Context
+- What this folder/repo is and why it exists
+- The mental model for how things fit together
+- Current focus - what's actively being worked on
+
+### Progressive Disclosure
+- Pointers to documentation ("See docs/INDEX.md for...")
+- Key reference docs listed by name
+- Where workflows and detailed guides live
+
+### Tribal Knowledge
+- Gotchas discovered during sessions
+- Non-obvious conventions
+- Things that would save pain if known upfront
+- "We use X instead of Y" (without spelling out examples)
+
+### Quick Reference (sparingly)
+- Dev commands if truly common (one-liners only)
+- Key URLs or entry points
+- Simple folder structure if it aids orientation
+
+## What Does NOT Belong
+
+### Duplicated Content
+Claude reads CLAUDE.md files up through the hierarchy automatically. If a parent file says "We use TypeScript", the child file should NOT repeat this.
+
+**Rule:** Before adding something, check if a parent already covers it.
+
+### Detailed Workflows
+Step-by-step processes belong in:
+- `docs/` folder
+- Skills (`.claude/skills/`)
+- Dedicated workflow files
+
+CLAUDE.md points to these, doesn't contain them.
+
+### Micromanagement
+Trust the model. If you say "We use Base UI instead of Radix", Claude understands the implications. Don't add:
+- Lists of every Radix component and its Base UI equivalent
+- Example code for each case
+- Exhaustive edge cases
+
+### Operational Runbooks
+SSH commands, database credentials, deployment scripts - these belong in dedicated docs, not CLAUDE.md.
+
+### Frequently Changing Content
+CLAUDE.md should be stable. If content changes often, it belongs elsewhere (like CURRENT_WORK.md or a status doc).
+
+## Length Guideline
+
+No hard limit, but **over 100 lines is suspect**.
+
+A good CLAUDE.md is typically 40-80 lines. If it's longer, ask:
+- Is there duplication with parent files?
+- Are there workflows that should be extracted?
+- Am I explaining things Claude already knows?
+
+## Writing Style
+
+CLAUDE.md files are prompts. Apply prompting best practices:
+
+### Explain WHY, Not Just WHAT
+Bad: "Run `npm run dev` to start the server"
+Good: "Dev server runs on :5173. Hot reload handles code changes - no restart needed."
+
+### Positive Framing
+Bad: "Don't put workflows in CLAUDE.md"
+Good: "Workflows belong in docs/ or skills/"
+
+### Be Direct
+Bad: "You might want to check the docs folder"
+Good: "Start at docs/INDEX.md for all documentation"
+
+### Trust Intelligence
+Bad: Listing every ShadCN component and how to use it
+Good: "Use ShadCN for all UI. Discuss before building custom components."
+
+## Hierarchy Examples
+
+**Root CLAUDE.md** (project level):
+- What the project is
+- Overall structure
+- Where documentation lives
+- External systems overview
+
+**Subdirectory CLAUDE.md** (e.g., `roost/CLAUDE.md`):
+- What this specific folder is
+- Rules specific to this codebase
+- Dev commands for this folder
+- Does NOT repeat project-level context
+
+**Deep subdirectory** (e.g., `src/components/CLAUDE.md`):
+- Only if there's something specific to know
+- Usually unnecessary - parent files cover it
+- If created, extremely focused (20-30 lines max)
+
+## Capturing Gotchas
+
+When a session reveals something painful:
+
+1. **Identify the learning** - What would have saved time if known upfront?
+2. **Find the right file** - Which CLAUDE.md is this specific to?
+3. **Add concisely** - One or two lines, not a full explanation
+4. **Trust the model** - State the gotcha, don't over-explain
+
+Example:
+```markdown
+## Gotchas
+
+- qrServer tracks `development` branch, not master
+- Convex queries can't be called from other queries - use actions for composition
+```

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`.