cc-dev-template 0.1.32 → 0.1.33

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

@@ -1,119 +0,0 @@
-# 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. **Submodule scope**: If in a repo with submodules, which submodules does this work affect?
-5. **Ambiguities**: Anything in their description that could be interpreted multiple ways
-
-**Ask only what the user alone can answer.** Questions about goals, preferences, success criteria, and scope belong here. Questions about codebase state (what exists, how things work) belong in exploration (Phase 2)—discover those yourself by reading the code.
-
-**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]
-- Submodules affected: [list submodules if relevant, or "N/A"]
-
-**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

@@ -1,355 +0,0 @@
-#!/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/skills/orchestration/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.md       - Plan definition with YAML frontmatter (preferred)
- *     plan.yaml     - Plan definition (legacy, fallback)
- *     manifest.yaml - Task manifest with completion status (optional)
- *
- *   .claude/debug/[slug]/
- *     debug.md      - Debug session with YAML frontmatter (preferred)
- *     debug.yaml    - Debug session (legacy, fallback)
- *
- * 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;
-  }
-}
-
-/**
- * Parse YAML frontmatter from Markdown content
- * Frontmatter is delimited by --- at start and end
- * @param {string} content - File content as string
- * @returns {object | null} - Parsed YAML object or null if no frontmatter
- */
-function parseFrontmatter(content) {
-  if (!content || typeof content !== 'string') {
-    return null;
-  }
-
-  // Frontmatter must start at the beginning of the file with ---
-  if (!content.startsWith('---')) {
-    return null;
-  }
-
-  // Find the closing ---
-  const endIndex = content.indexOf('\n---', 3);
-  if (endIndex === -1) {
-    return null;
-  }
-
-  // Extract the YAML content between the delimiters
-  const frontmatterContent = content.slice(4, endIndex).trim();
-  if (!frontmatterContent) {
-    return null;
-  }
-
-  try {
-    return yaml.load(frontmatterContent);
-  } catch (error) {
-    console.error(`Warning: Failed to parse frontmatter: ${error.message}`);
-    return null;
-  }
-}
-
-/**
- * Read and parse a Markdown file with YAML frontmatter
- * @param {string} filePath - Absolute path to the Markdown file
- * @returns {object | null} - Parsed frontmatter data or null on error
- */
-function parseMarkdownFile(filePath) {
-  try {
-    const content = fs.readFileSync(filePath, 'utf8');
-    return parseFrontmatter(content);
-  } catch (error) {
-    console.error(`Warning: Failed to read ${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
- * Prefers plan.md (Markdown with frontmatter), falls back to plan.yaml
- * @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 planMdPath = path.join(planDir, 'plan.md');
-  const planYamlPath = path.join(planDir, 'plan.yaml');
-  const manifestPath = path.join(planDir, 'manifest.yaml');
-
-  // Try plan.md first (preferred format), fall back to plan.yaml
-  let plan = null;
-  if (fs.existsSync(planMdPath)) {
-    plan = parseMarkdownFile(planMdPath);
-  } else if (fs.existsSync(planYamlPath)) {
-    plan = parseYamlFile(planYamlPath);
-  }
-
-  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}/`
-  };
-
-  // Include affected_submodules if present in the plan
-  if (Array.isArray(plan.affected_submodules) && plan.affected_submodules.length > 0) {
-    planInfo.affected_submodules = plan.affected_submodules;
-  }
-
-  // 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;
-
-      // Derive completion status: if all tasks are completed, the plan is completed
-      if (taskCounts.total > 0 && taskCounts.completed === taskCounts.total) {
-        planInfo.status = 'completed';
-      }
-    }
-  }
-
-  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
- * Prefers debug.md (Markdown with frontmatter), falls back to debug.yaml
- * @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 debugMdPath = path.join(debugDir, 'debug.md');
-  const debugYamlPath = path.join(debugDir, 'debug.yaml');
-
-  // Try debug.md first (preferred format), fall back to debug.yaml
-  let debug = null;
-  if (fs.existsSync(debugMdPath)) {
-    debug = parseMarkdownFile(debugMdPath);
-  } else if (fs.existsSync(debugYamlPath)) {
-    debug = parseYamlFile(debugYamlPath);
-  }
-
-  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();