cc-dev-template 0.1.1

package/src/skills/orchestration/references/planning/finalize.md

@@ -0,0 +1,169 @@
+# Planning Phase 4: Finalize
+
+## Purpose
+
+Validate the plan against architectural constraints and get user approval. This is the last step before the plan is ready for the execution workflow.
+
+Validation catches ADR conflicts while they're cheap to fix. Approval ensures the user agrees with what's about to be built.
+
+**Success looks like**: The plan complies with all relevant ADRs, the user has approved it, and it's ready for the execution workflow.
+
+## What To Do
+
+Complete each step in order before proceeding to the next.
+
+<steps>
+
+<step name="Validate Against ADRs">
+Spawn the adr-agent to validate the plan. The agent will:
+- Read the plan.yaml
+- Find ALL ADRs that might be relevant (not just the ones declared in the plan)
+- Check compliance for each: COMPLIANT, TENSION, or CONFLICT
+- Report what needs attention
+
+```
+Spawn adr-agent: "Validate the plan at .claude/plans/[slug]/plan.yaml.
+
+Find all ADRs that could be relevant to this work—check beyond what's
+declared in the plan's relevant_adrs field. Better to surface extra
+ADRs than miss important ones.
+
+For each relevant ADR, report:
+- COMPLIANT: Plan follows this ADR
+- TENSION: Potential friction, worth noting
+- CONFLICT: Plan violates this ADR, must resolve
+
+Return a validation report with findings for each ADR."
+```
+
+**Show the validation report to the user** before proceeding.
+</step>
+
+<step name="Handle Validation Results">
+**If all COMPLIANT (or only TENSION):**
+- Note any tensions for awareness
+- Proceed to user approval
+
+**If CONFLICT found:**
+- Present the conflicts to the user clearly
+- For each conflict, explain:
+  - Which ADR is violated
+  - What the ADR requires
+  - How the plan conflicts
+- Work with the user to resolve:
+  - Adjust the plan to comply
+  - Or discuss whether the ADR needs updating (spawn adr-agent to supersede if so)
+- Re-validate after changes
+
+Use AskUserQuestion to discuss conflicts:
+
+```
+AskUserQuestion:
+Question: "The plan conflicts with [ADR-XXX]. How should we resolve this?"
+Options:
+- "Adjust the plan" - I'll describe what to change
+- "The ADR is outdated" - Let's update or supersede the ADR
+- "Let's discuss" - I need more context before deciding
+- "Something else" - I have a different approach
+```
+
+Iterate until validation passes (no CONFLICT items).
+</step>
+
+<checkpoint>
+Before proceeding to approval:
+- adr-agent was spawned and returned results
+- Validation report was shown to user
+- Any CONFLICT items have been resolved
+</checkpoint>
+
+<step name="Present Final Plan">
+Once validation passes, present the plan summary to the user:
+
+```
+## Plan Ready for Approval
+
+**Title**: [plan title]
+**Type**: [feature / enhancement / refactor]
+
+**Problem**: [1-2 sentence summary]
+
+**Goals**:
+- [Goal 1]
+- [Goal 2]
+
+**Success Criteria**:
+- [Criterion 1]
+- [Criterion 2]
+
+**Key Components**:
+- [Data models, API contracts, integration points - high level]
+
+**Relevant ADRs**: [list with compliance status]
+
+The plan has been validated against architectural constraints.
+```
+</step>
+
+<step name="Get Approval">
+Use AskUserQuestion to get explicit approval:
+
+```
+AskUserQuestion:
+Question: "Approve this plan?"
+Options:
+- "Approved" - Mark as approved
+- "Needs changes" - I'll explain what to adjust
+- "Let's discuss first" - I have questions
+```
+
+**If approved:**
+1. Update plan.yaml: `status: approved`
+2. Update plan.yaml: `updated: [today's date]`
+
+**If changes requested:**
+- Make the requested changes
+- Re-validate if changes affect ADR compliance
+- Present again and get approval
+</step>
+
+<checkpoint>
+Before proceeding to execution handoff:
+- Plan summary was presented to user
+- User explicitly selected "Approved"
+- plan.yaml status is now `approved`
+</checkpoint>
+
+<step name="Offer Next Steps">
+Ask what the user wants to do next:
+
+```
+AskUserQuestion:
+Question: "Plan approved. What's next?"
+Options:
+- "Start the execution workflow" - Proceed to decomposition phase
+- "Stop here for now" - Save and exit
+```
+
+**If "Start the execution workflow":**
+Read `references/execution/start.md` to begin. The execution workflow starts with decomposition—breaking the plan into tasks. Agents handle implementation; you orchestrate.
+
+**If "Stop here for now":**
+End with: "Plan saved and approved. Run `/prime` when you're ready to start the execution workflow."
+</step>
+
+</steps>
+
+## Key Principles
+
+**Validate thoroughly.** The adr-agent should find ADRs beyond what's declared. Missing a relevant ADR now means discovering violations during execution.
+
+**Resolve conflicts before approval.** A plan with known ADR conflicts shouldn't be approved. Either fix the plan or update the ADR.
+
+**Get explicit approval.** The plan represents a commitment. Make sure the user consciously agrees before marking it approved.
+
+**Approval and next steps are separate decisions.** Get approval first. Then ask about execution. Don't combine these into one question.
+
+<transition>
+When the user chooses to start execution, read `references/execution/start.md` to begin the execution workflow.
+</transition>

package/src/skills/orchestration/references/planning/start.md

@@ -0,0 +1,115 @@
+# Planning Phase 1: Requirements
+
+## Purpose
+
+Transform a vague idea into a crystal clear understanding of WHAT we're building and what SUCCESS looks like.
+
+This phase is about understanding the problem, not solving it. Stay focused on goals, success criteria, and removing ambiguity. Implementation details (the HOW) come later in exploration and drafting phases.
+
+**Success looks like**: You can articulate exactly what the user wants to build, why it matters, and how we'll know when it's done—with zero ambiguity.
+
+## What To Do
+
+Complete each step in order before proceeding to the next.
+
+<steps>
+
+<step name="Ask What They Want to Plan">
+Start with a simple, open-ended question. Let the user describe their idea in their own words.
+
+Just ask: **"What do you want to plan?"**
+
+Let them write freely here (save AskUserQuestion for the clarifying questions). They'll dump out their thoughts, context, and initial ideas. Your job is to listen and absorb.
+</step>
+
+<step name="Probe for Clarity">
+After the user describes what they want, your job is to remove all ambiguity. Use `AskUserQuestion` to dig into anything that's unclear.
+
+**Focus on these areas:**
+
+1. **Goals**: What are they trying to achieve? What problem does this solve?
+2. **Success criteria**: How will we know when this is done? What does "working" look like?
+3. **Scope boundaries**: What's included? What's explicitly NOT included?
+4. **Ambiguities**: Anything in their description that could be interpreted multiple ways
+
+**Ask one clarifying question at a time.** After each answer, assess: Is there still ambiguity? If yes, ask another question. If no, move on.
+
+**Example clarifying questions:**
+
+```
+"You mentioned [X]. What specifically should happen when [X]?"
+
+"What does success look like for this? How will you know it's working?"
+
+"Is [Y] part of this work, or should we consider that out of scope?"
+
+"When you say [Z], do you mean [interpretation A] or [interpretation B]?"
+```
+
+**Always include an escape hatch** in your AskUserQuestion options—something like "Something else" or "Let me explain" so the user can provide context that doesn't fit your options.
+</step>
+
+<step name="Keep Going Until Clear">
+Continue asking clarifying questions until ONE of these is true:
+
+- **You have no more questions**: Every aspect of what they want is crystal clear
+- **The user says stop**: They indicate they've clarified enough ("I think that covers it", "Let's move on", etc.)
+
+Take your time here. Ambiguity discovered now is cheap to resolve. Ambiguity discovered during implementation is expensive.
+</step>
+
+<step name="Summarize What You Learned">
+Before moving on, summarize your understanding back to the user:
+
+```
+## Here's what I understand:
+
+**What we're building**: [1-2 sentence summary]
+
+**Goals**:
+- [Goal 1]
+- [Goal 2]
+
+**Success criteria** (how we'll know it's done):
+- [Criterion 1]
+- [Criterion 2]
+
+**Scope**:
+- Includes: [what's in]
+- Excludes: [what's out]
+
+**Type**: [feature / enhancement / refactor / bug fix]
+```
+
+Then confirm:
+
+```
+AskUserQuestion:
+Question: "Does this capture what you want to build?"
+Options:
+- "Yes, that's right" - Proceed to codebase exploration
+- "Mostly, but..." - I'll clarify what needs adjustment
+- "No, let's try again" - Start over with a fresh description
+```
+</step>
+
+<checkpoint>
+Before proceeding to the next phase:
+- User has described what they want
+- All ambiguities have been clarified
+- Summary has been presented and confirmed
+</checkpoint>
+
+</steps>
+
+## Key Principles
+
+**Stay focused on WHAT, not HOW.** Keep questions about goals, success criteria, and scope. Save implementation questions ("Which framework? What database?") for later phases.
+
+**Ask when uncertain.** If something is unclear, ask. Let the user fill in the blanks rather than assuming.
+
+**Invest time here.** This phase sets the foundation. A few extra minutes of clarity now saves hours of rework later.
+
+<transition>
+When the user confirms your summary is accurate, read `references/planning/explore.md` to continue to codebase exploration.
+</transition>

package/src/skills/orchestration/scripts/plan-status.js

@@ -0,0 +1,283 @@
+#!/usr/bin/env node
+
+/**
+ * plan-status.js - List active plans and debug sessions in the project
+ *
+ * This CLI script scans .claude/plans/ and .claude/debug/ for active work
+ * and outputs structured information. Completed items are filtered out
+ * since they're no longer actionable. Designed to support /prime command
+ * by quickly surfacing "where are we" and "what can we do" without manual
+ * file scanning.
+ *
+ * Usage:
+ *   node ~/.claude/scripts/plan-status.js
+ *
+ * Output:
+ *   JSON object to stdout:
+ *   {
+ *     "plans": [
+ *       {
+ *         "id": "plan-feature-auth",
+ *         "title": "Authentication Feature",
+ *         "status": "approved",
+ *         "path": ".claude/plans/feature-auth/"
+ *       }
+ *     ],
+ *     "debugSessions": [
+ *       {
+ *         "id": "debug-001",
+ *         "title": "Avatar not updating",
+ *         "status": "investigating",
+ *         "phase": "rca",
+ *         "path": ".claude/debug/avatar-not-updating/"
+ *       }
+ *     ]
+ *   }
+ *
+ * Directory structure:
+ *   .claude/plans/[slug]/
+ *     plan.yaml     - Plan definition (id, title, status)
+ *     manifest.yaml - Task manifest with completion status (optional)
+ *
+ *   .claude/debug/[slug]/
+ *     debug.yaml    - Debug session (id, title, status, hypotheses)
+ *
+ * Note: This script uses process.cwd() to find project-local files, since
+ * scripts install globally to ~/.claude/scripts/ but need to access the
+ * project's .claude/ directories.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const yaml = require('js-yaml');
+
+// Directories are in the project's .claude/ directory (relative to CWD)
+const PLANS_DIR = path.join(process.cwd(), '.claude', 'plans');
+const DEBUG_DIR = path.join(process.cwd(), '.claude', 'debug');
+
+/**
+ * Read and parse a YAML file
+ * @param {string} filePath - Absolute path to the YAML file
+ * @returns {object | null} - Parsed YAML data or null on error
+ */
+function parseYamlFile(filePath) {
+  try {
+    const content = fs.readFileSync(filePath, 'utf8');
+    return yaml.load(content);
+  } catch (error) {
+    // Log to stderr so it doesn't pollute JSON output
+    console.error(`Warning: Failed to parse ${filePath}: ${error.message}`);
+    return null;
+  }
+}
+
+/**
+ * Count completed and total tasks from a manifest
+ * @param {object} manifest - Parsed manifest.yaml data
+ * @returns {{ total: number, completed: number } | null}
+ */
+function countTasks(manifest) {
+  if (!manifest || !Array.isArray(manifest.tasks)) {
+    return null;
+  }
+
+  const total = manifest.tasks.length;
+  const completed = manifest.tasks.filter(task => task.status === 'completed').length;
+
+  return { total, completed };
+}
+
+/**
+ * Get plan information from a plan directory
+ * @param {string} planDir - Absolute path to the plan directory
+ * @param {string} slug - Directory name (slug)
+ * @returns {object | null} - Plan info object or null if invalid
+ */
+function getPlanInfo(planDir, slug) {
+  const planPath = path.join(planDir, 'plan.yaml');
+  const manifestPath = path.join(planDir, 'manifest.yaml');
+
+  // plan.yaml is required
+  if (!fs.existsSync(planPath)) {
+    return null;
+  }
+
+  const plan = parseYamlFile(planPath);
+  if (!plan) {
+    return null;
+  }
+
+  // Build plan info object
+  const planInfo = {
+    id: plan.id || `plan-${slug}`,
+    title: plan.title || '',
+    status: plan.status || 'unknown',
+    path: `.claude/plans/${slug}/`
+  };
+
+  // If manifest exists, use its status and add task counts
+  // The manifest represents actual execution progress, so it overrides plan.yaml status
+  if (fs.existsSync(manifestPath)) {
+    const manifest = parseYamlFile(manifestPath);
+
+    // Use manifest status if present (represents actual progress)
+    if (manifest && manifest.status) {
+      planInfo.status = manifest.status;
+    }
+
+    // Add task counts from manifest
+    const taskCounts = countTasks(manifest);
+    if (taskCounts) {
+      planInfo.tasks = taskCounts;
+    }
+  }
+
+  return planInfo;
+}
+
+/**
+ * Scan plans directory and collect all plan information
+ * @returns {Array<object>} - Array of plan info objects
+ */
+function collectPlans() {
+  const plans = [];
+
+  // Check if plans directory exists - return empty array if not
+  if (!fs.existsSync(PLANS_DIR)) {
+    return plans;
+  }
+
+  // Get all subdirectories in plans directory
+  let entries;
+  try {
+    entries = fs.readdirSync(PLANS_DIR, { withFileTypes: true });
+  } catch (error) {
+    console.error(`Warning: Failed to read plans directory: ${error.message}`);
+    return plans;
+  }
+
+  // Process each plan directory
+  const planDirs = entries
+    .filter(entry => entry.isDirectory())
+    .map(entry => entry.name)
+    .sort(); // Sort alphabetically for consistent ordering
+
+  for (const slug of planDirs) {
+    const planDir = path.join(PLANS_DIR, slug);
+    const planInfo = getPlanInfo(planDir, slug);
+
+    // Only include non-completed plans
+    if (planInfo && planInfo.status !== 'completed') {
+      plans.push(planInfo);
+    }
+  }
+
+  return plans;
+}
+
+/**
+ * Determine which debug phase based on debug.yaml state
+ * @param {object} debug - Parsed debug.yaml data
+ * @returns {string} - Phase name (describe, rca, verify, fix, learn)
+ */
+function determineDebugPhase(debug) {
+  if (!debug || debug.status === 'closed') {
+    return 'closed';
+  }
+
+  const hypotheses = debug.hypotheses || [];
+  if (hypotheses.length === 0) {
+    return 'rca';
+  }
+
+  // Check the latest hypothesis status
+  const latest = hypotheses[hypotheses.length - 1];
+  switch (latest.status) {
+    case 'investigating':
+      return 'rca';
+    case 'verified':
+      return 'fix';
+    case 'disproven':
+      return 'rca';
+    case 'fixed':
+      return 'learn';
+    default:
+      return 'rca';
+  }
+}
+
+/**
+ * Get debug session information from a debug directory
+ * @param {string} debugDir - Absolute path to the debug directory
+ * @param {string} slug - Directory name (slug)
+ * @returns {object | null} - Debug info object or null if invalid
+ */
+function getDebugInfo(debugDir, slug) {
+  const debugPath = path.join(debugDir, 'debug.yaml');
+
+  if (!fs.existsSync(debugPath)) {
+    return null;
+  }
+
+  const debug = parseYamlFile(debugPath);
+  if (!debug) {
+    return null;
+  }
+
+  return {
+    id: debug.id || `debug-${slug}`,
+    title: debug.title || '',
+    status: debug.status || 'unknown',
+    phase: determineDebugPhase(debug),
+    path: `.claude/debug/${slug}/`
+  };
+}
+
+/**
+ * Scan debug directory and collect all active debug sessions
+ * @returns {Array<object>} - Array of debug info objects
+ */
+function collectDebugSessions() {
+  const sessions = [];
+
+  if (!fs.existsSync(DEBUG_DIR)) {
+    return sessions;
+  }
+
+  let entries;
+  try {
+    entries = fs.readdirSync(DEBUG_DIR, { withFileTypes: true });
+  } catch (error) {
+    console.error(`Warning: Failed to read debug directory: ${error.message}`);
+    return sessions;
+  }
+
+  const debugDirs = entries
+    .filter(entry => entry.isDirectory())
+    .map(entry => entry.name)
+    .sort();
+
+  for (const slug of debugDirs) {
+    const debugDir = path.join(DEBUG_DIR, slug);
+    const debugInfo = getDebugInfo(debugDir, slug);
+
+    // Only include non-closed sessions
+    if (debugInfo && debugInfo.status !== 'closed') {
+      sessions.push(debugInfo);
+    }
+  }
+
+  return sessions;
+}
+
+// Main execution
+function main() {
+  const plans = collectPlans();
+  const debugSessions = collectDebugSessions();
+
+  // Output JSON to stdout
+  const output = { plans, debugSessions };
+  console.log(JSON.stringify(output, null, 2));
+}
+
+main();

package/src/skills/prompting/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: prompting
+description: Best practices for creating effective Claude prompts. Use when creating, reviewing, or modifying prompts for agents or commands.
+---
+
+# Prompting Skill
+
+Actionable guidance for crafting effective prompts for Claude 4.x models. Apply these principles when creating or reviewing agent prompts, command specifications, or any structured Claude interactions.
+
+## Core Principles
+
+Apply in order of importance:
+
+### 1. Explain WHY, Not Just WHAT (Most Important)
+
+Provide purpose and context rather than exhaustive implementation details. Trust Claude's intelligence.
+
+**Mental Model**: Treat Claude like a brilliant senior colleague, not a junior who needs hand-holding.
+
+**Provide**:
+- The goal or purpose of the task
+- Why this matters (business context, use case)
+- Constraints that exist (technical, business, regulatory)
+- What success looks like
+
+**Avoid providing**:
+- Every possible edge case
+- Step-by-step implementation unless genuinely needed
+- Obvious best practices for the domain
+
+### 2. Use Positive Framing
+
+Tell Claude what TO do, not what NOT to do. Negatives require extra processing and can prime unwanted behavior.
+
+| Negative Framing | Positive Framing |
+|------------------|------------------|
+| "Don't hallucinate facts" | "Only use information from the provided documents" |
+| "Don't be too formal" | "Write in a conversational, friendly tone" |
+| "Avoid long paragraphs" | "Keep paragraphs to 3-4 sentences" |
+| "Don't skip error handling" | "Include comprehensive error handling" |
+| "Don't make it complicated" | "Keep the solution simple and maintainable" |
+| "Avoid making assumptions" | "Base responses on the provided data" |
+
+### 3. Be Clear and Direct
+
+Claude 4.x models are more literal than previous versions. State exactly what you want without hedging.
+
+| Vague | Clear |
+|-------|-------|
+| "Can you maybe help me think about..." | "Redesign the authentication flow to support SSO" |
+| "It might be nice to have..." | "Add rate limiting to the login endpoint" |
+| "Create a dashboard" | "Create a fully-featured dashboard with charts, filters, export, and user preferences" |
+
+### 4. Provide Context
+
+Answer these questions:
+1. **Why does this matter?** (Purpose, goal, business context)
+2. **Who is this for?** (Audience, user type, skill level)
+3. **What does success look like?** (Outcomes, metrics, acceptance criteria)
+4. **What constraints exist?** (Technical limits, requirements, policies)
+
+## The Complete Framework Checklist
+
+Every good prompt should answer:
+
+- [ ] **WHAT** are you asking Claude to do?
+- [ ] **WHY** does this matter? (Purpose, goal)
+- [ ] **WHO** is this for? (Audience, user type)
+- [ ] **SUCCESS** looks like what?
+- [ ] Frame everything **POSITIVELY** (what TO do, not what NOT to do)
+
+Then trust Claude to:
+- Handle edge cases intelligently
+- Apply best practices for the domain
+- Make reasonable implementation choices
+- Ask clarifying questions if truly ambiguous
+
+## Quick Diagnostics
+
+When Claude's response is problematic:
+
+| Problem | Likely Cause | Fix |
+|---------|--------------|-----|
+| Too minimal/basic | Not explicit about expectations | Add "Create a fully-featured..." or "Go beyond basics..." |
+| Off-topic | Missing context about purpose | Explain WHY you need this and what it's for |
+| Inconsistent | Vague or ambiguous instructions | Be more direct and specific about requirements |
+| Overly cautious | Negative framing ("don't do X") | Reframe positively ("do Y instead") |
+| Missing key details | Didn't explain what success looks like | Define concrete success criteria |
+
+## Common Antipatterns
+
+### The Micromanager
+Providing step-by-step implementation instead of goals.
+
+**Fix**: Explain the goal, let Claude handle implementation.
+
+### The Negative Nancy
+String of "don't do X" instructions.
+
+**Fix**: Reframe every negative as a positive instruction.
+
+### The Context-Free Zone
+Bare instruction with no purpose or audience.
+
+**Fix**: Explain who will use it, why it exists, what success looks like.
+
+### The Vague Suggestion
+Hedged language like "maybe we could possibly..."
+
+**Fix**: Be direct and explicit about what you want.
+
+## Structural Elements
+
+For multi-step tasks where order matters, use numbered lists.
+
+For complex prompts with distinct sections, consider XML-style tags:
+- `<instructions>`, `<context>`, `<data>`
+- `<examples>`, `<input>`, `<output>`
+- `<requirements>`, `<constraints>`
+
+## ADR Compliance
+
+This skill implements the practices mandated by ADR-002 (Structured Prompting Practices for Agents and Commands). All agents and commands in this framework must follow these principles.