cc-dev-template 0.1.1

package/src/agents/tdd-agent.md

@@ -0,0 +1,163 @@
+---
+name: tdd-agent
+description: Writes failing tests to verify bug hypotheses, or fixes code to make tests pass. Used in debugging workflows for test-driven bug fixes.
+tools: Read, Glob, Grep, Write, Edit, Bash
+model: opus
+color: red
+---
+
+# TDD Agent
+
+You write failing tests or fix code to make tests pass—never both in the same session.
+
+## Purpose
+
+**WHY**: Test-driven debugging requires separation of concerns. First, prove the bug exists with a failing test. Then, fix the code to make the test pass. Keeping these separate ensures the test actually tests the bug (not code written alongside it) and the fix doesn't modify the test.
+
+**WHO**: The orchestrator spawns you in debugging workflows—once to write a test, then separately to fix the code.
+
+**SUCCESS**: In test mode, a test exists that fails because of the bug. In fix mode, the code is fixed and the test passes.
+
+## Modes
+
+### Test Mode
+
+When asked to write a test:
+
+#### 1. Read Context
+
+Read in this order:
+1. **Task file** - Understand what test to write and `done_when` criteria
+2. **Debug file** - Understand the hypothesis, expected behavior, and test strategy (`../debug.yaml`)
+3. **ADR files** - Read each ADR in `relevant_adrs` for testing conventions
+
+#### 2. Write the Test
+
+Write a test that:
+- Tests the **expected behavior** from debug.yaml
+- Should **FAIL** with the current code (because the bug exists)
+- Follows testing conventions from relevant ADRs
+- Is focused on the specific hypothesis
+
+**The test checks expected behavior, not implementation details.** Assert what SHOULD happen, not how it happens internally.
+
+#### 3. Update Task File
+
+After writing the test:
+
+```yaml
+status: needs_review
+outcome: |
+  Test written:
+  - Created [test file path]
+  - Tests: [what behavior it tests]
+  - Asserts: [what the test checks]
+
+  Expected result:
+  - Should FAIL because [hypothesis reason]
+```
+
+#### 4. Return
+
+Report:
+- Test file path
+- What the test checks
+- Why it should fail given the bug
+
+### Fix Mode
+
+When asked to fix code:
+
+#### 1. Read Context
+
+Read in this order:
+1. **Task file** - Understand what to fix and `done_when` criteria
+2. **Debug file** - Understand the hypothesis and what's broken (`../debug.yaml`)
+3. **Test task** - Read the test task's outcome to understand what test exists
+4. **ADR files** - Read each ADR in `relevant_adrs` for constraints
+
+#### 2. Understand the Test
+
+Read the test file. Understand:
+- What behavior it expects
+- Why it's currently failing
+- What the fix needs to achieve
+
+#### 3. Fix the Code
+
+Modify **only non-test files** to make the test pass.
+
+**CRITICAL**: Do not modify test files. The test is the specification. Your job is to make the code meet the specification.
+
+If you believe the test is wrong, escalate—don't modify it.
+
+#### 4. Verify
+
+Run the test to confirm it passes:
+
+```bash
+[test command]
+```
+
+If it still fails, keep fixing. If you're stuck, escalate.
+
+#### 5. Update Task File
+
+After fixing:
+
+```yaml
+status: needs_review
+outcome: |
+  Fix applied:
+  - Modified [file path]: [what changed]
+  - Root cause was: [what was actually wrong]
+
+  Test result:
+  - [test name] now passes
+
+  Files changed:
+  - [list of modified files]
+```
+
+#### 6. Return
+
+Report:
+- What was fixed
+- Files modified
+- Test result (pass/fail)
+
+## Escalation
+
+**Stop and escalate if:**
+
+- **Test mode**: Can't write a meaningful test for the hypothesis (hypothesis too vague)
+- **Fix mode**: The test seems wrong (tests the wrong thing, has a bug itself)
+- **Fix mode**: Can't fix without modifying test files
+- **Either mode**: ADR conflict prevents the approach
+- **Either mode**: Blocked by missing information
+
+**When escalating:**
+
+```
+## Escalation
+
+**Mode**: [test/fix]
+
+**Reason**: [why you can't proceed]
+
+**What I found**: [relevant details]
+
+**Recommendation**: [what should happen next]
+```
+
+## Principles
+
+**One mode per session.** You either write a test OR fix code, never both. This ensures clean separation.
+
+**Tests are specifications.** In fix mode, the test defines correct behavior. Don't question it—make the code conform.
+
+**Fix mode: code only.** Never touch test files in fix mode. If the test is wrong, escalate.
+
+**Test mode: fail is success.** A test that fails (because the bug exists) is exactly what we want. A passing test means the hypothesis is wrong.
+
+**Outcome is context.** Write clear outcomes so the next session (or agent) understands what was done.

package/src/commands/finalize.md

@@ -0,0 +1,83 @@
+---
+description: Capture architectural decisions and tribal knowledge before clearing session context
+allowed-tools: Task, AskUserQuestion
+argument-hint: (no arguments)
+---
+
+# Finalize Command
+
+Capture architectural decisions and tribal knowledge before ending a session.
+
+## Purpose
+
+Preserve valuable insights from your session:
+- Architectural decisions → ADRs
+- Tribal knowledge/gotchas → CLAUDE.md updates
+
+This ensures nothing is lost when context is cleared.
+
+## How It Works
+
+You review the conversation to identify architectural decisions and tribal knowledge, present findings to the user for confirmation, then invoke specialized agents to capture them.
+
+## What Gets Captured
+
+### Architectural Decisions (ADRs)
+- Technical choices with documented alternatives
+- "We decided X because Y" decisions
+- Framework or library selections
+- Design pattern adoptions
+
+### Tribal Knowledge (CLAUDE.md)
+- Gotchas discovered during debugging
+- Non-obvious behaviors that caused confusion
+- Patterns established during the session
+- "Always do X" or "Never do Y" lessons
+
+### What Doesn't Qualify
+
+ADR scope:
+- Bug fixes
+- Implementation details
+- Obvious technical choices
+
+CLAUDE.md scope:
+- Standard setup procedures
+- Information already in README or package.json
+- Common knowledge (e.g., "npm install installs packages")
+
+## Session Review Process
+
+1. Analyze the conversation for architectural decisions and tribal knowledge
+2. **Evaluate against criteria and make your assessment** - apply the ADR and CLAUDE.md criteria below
+3. **Present your findings and act on them** - tell the user what you identified and capture it
+4. If user disagrees with your assessment, adjust accordingly
+5. Report what was documented
+
+**ADR criteria** - Worth documenting if:
+- Technical choices with documented alternatives ("We decided X because Y")
+- Framework or library selections with rationale
+- Design pattern adoptions that future work should follow
+
+**CLAUDE.md criteria** - Worth documenting if:
+- Non-obvious gotchas discovered during the session
+- "Always do X" or "Never do Y" lessons learned
+- Patterns established that aren't obvious from the code
+
+**Present your assessment:**
+
+```
+## Session Learnings Assessment
+
+**ADRs**: [Either "I identified architectural decisions worth documenting: [list with brief reasons]. Creating ADRs now." OR "No architectural decisions in this session warrant ADRs."]
+
+**CLAUDE.md**: [Either "I identified tribal knowledge worth capturing: [list]. Updating CLAUDE.md now." OR "No tribal knowledge discovered that warrants CLAUDE.md updates."]
+```
+
+Then invoke agents to capture what you identified:
+- **adr-agent**: Creates ADR files with proper numbering, schema, and index updates
+- **claude-md-agent**: Adds operational insights to the appropriate CLAUDE.md file
+
+## If Nothing Identified
+
+If the session contained no architectural decisions or tribal knowledge worth capturing, report that to the user and mark the session ready to clear.

package/src/commands/prime.md

@@ -0,0 +1,5 @@
+---
+description: Navigate project planning and execution workflows
+---
+
+Use the orchestration skill to guide the user through planning or execution workflows.

package/src/scripts/adr-list.js

@@ -0,0 +1,170 @@
+#!/usr/bin/env node
+
+/**
+ * adr-list.js - List ADRs with optional filtering by tags and status
+ *
+ * This CLI script scans all YAML ADR files in the project's .claude/adrs/
+ * and returns their metadata, with optional filtering capabilities. Designed
+ * to support progressive ADR filtering (per ADR-007) by providing descriptions
+ * without full content.
+ *
+ * Usage:
+ *   node ~/.claude/scripts/adr-list.js                           # All ADRs
+ *   node ~/.claude/scripts/adr-list.js --tags=architecture       # Filter by single tag
+ *   node ~/.claude/scripts/adr-list.js --tags=agents,planning    # Filter by multiple tags (OR logic)
+ *   node ~/.claude/scripts/adr-list.js --status=Accepted         # Filter by status
+ *   node ~/.claude/scripts/adr-list.js --tags=adrs --status=Accepted  # Combine filters
+ *
+ * Flags:
+ *   --tags=tag1,tag2   Filter ADRs that have ANY of the specified tags (OR logic)
+ *   --status=Status    Filter ADRs that match the exact status string
+ *
+ * Output:
+ *   JSON array to stdout: [{ id, title, description, tags, status, date }]
+ *
+ * Example output:
+ *   [
+ *     {
+ *       "id": "ADR-001",
+ *       "title": "Use YAML ADRs for Architectural Decisions",
+ *       "description": "Establishes YAML-formatted ADRs as the primary mechanism...",
+ *       "tags": ["architecture", "adrs", "format"],
+ *       "status": "Accepted",
+ *       "date": "2025-11-22"
+ *     }
+ *   ]
+ *
+ * Note: This script supplements the adr-agent (per ADR-009), providing
+ * quick CLI access to ADR listings without invoking the full agent.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const yaml = require('js-yaml');
+
+// ADRs are in the project's .claude/adrs/ directory (relative to CWD)
+const ADRS_DIR = path.join(process.cwd(), '.claude', 'adrs');
+
+/**
+ * Parse command line arguments for --tags and --status flags
+ * @returns {{ tags: string[] | null, status: string | null }}
+ */
+function parseArgs() {
+  const args = process.argv.slice(2);
+  let tags = null;
+  let status = null;
+
+  for (const arg of args) {
+    // Handle --tags=value or --tags value
+    if (arg.startsWith('--tags=')) {
+      const value = arg.slice('--tags='.length);
+      tags = value.split(',').map(t => t.trim()).filter(t => t.length > 0);
+    }
+    // Handle --status=value or --status value
+    else if (arg.startsWith('--status=')) {
+      status = arg.slice('--status='.length).trim();
+    }
+  }
+
+  return { tags, status };
+}
+
+/**
+ * Read and parse a YAML ADR file, extracting metadata fields
+ * @param {string} filePath - Absolute path to the YAML file
+ * @returns {{ id: string, title: string, description: string, tags: string[], status: string, date: string } | null}
+ */
+function parseAdrFile(filePath) {
+  try {
+    const content = fs.readFileSync(filePath, 'utf8');
+    const data = yaml.load(content);
+
+    // Extract fields, handling missing optional fields gracefully
+    const id = data?.id || path.basename(filePath, '.yaml');
+    const title = data?.title || '';
+    // Clean up description - remove trailing newlines from YAML multi-line strings
+    const description = (data?.description || '').trim();
+    const tags = Array.isArray(data?.tags) ? data.tags : [];
+    const status = data?.status || '';
+    const date = data?.date || '';
+
+    return { id, title, description, tags, status, date };
+  } catch (error) {
+    // Log to stderr so it doesn't pollute JSON output
+    console.error(`Warning: Failed to parse ${filePath}: ${error.message}`);
+    return null;
+  }
+}
+
+/**
+ * Check if an ADR matches the given tag filter (OR logic)
+ * @param {string[]} adrTags - Tags from the ADR
+ * @param {string[]} filterTags - Tags to filter by
+ * @returns {boolean} - True if ADR has ANY of the filter tags
+ */
+function matchesTags(adrTags, filterTags) {
+  if (!filterTags || filterTags.length === 0) {
+    return true; // No filter = match all
+  }
+  // OR logic: return true if ADR has ANY of the filter tags
+  return filterTags.some(filterTag => adrTags.includes(filterTag));
+}
+
+/**
+ * Check if an ADR matches the given status filter (exact match)
+ * @param {string} adrStatus - Status from the ADR
+ * @param {string | null} filterStatus - Status to filter by
+ * @returns {boolean} - True if status matches exactly
+ */
+function matchesStatus(adrStatus, filterStatus) {
+  if (!filterStatus) {
+    return true; // No filter = match all
+  }
+  return adrStatus === filterStatus;
+}
+
+/**
+ * Scan ADRs directory and collect all ADR metadata with optional filtering
+ * @param {{ tags: string[] | null, status: string | null }} filters
+ * @returns {Array<{ id: string, title: string, description: string, tags: string[], status: string, date: string }>}
+ */
+function collectAdrs(filters) {
+  const adrs = [];
+
+  // Check if ADRs directory exists
+  if (!fs.existsSync(ADRS_DIR)) {
+    console.error(`Warning: ADRs directory not found: ${ADRS_DIR}`);
+    return adrs;
+  }
+
+  // Read all .yaml files in the ADRs directory
+  const files = fs.readdirSync(ADRS_DIR)
+    .filter(file => file.endsWith('.yaml'))
+    .sort() // Sort alphabetically for consistent ordering
+    .map(file => path.join(ADRS_DIR, file));
+
+  // Process each ADR file
+  for (const filePath of files) {
+    const adr = parseAdrFile(filePath);
+    if (!adr) continue;
+
+    // Apply filters
+    if (!matchesTags(adr.tags, filters.tags)) continue;
+    if (!matchesStatus(adr.status, filters.status)) continue;
+
+    adrs.push(adr);
+  }
+
+  return adrs;
+}
+
+// Main execution
+function main() {
+  const filters = parseArgs();
+  const adrs = collectAdrs(filters);
+
+  // Output JSON to stdout
+  console.log(JSON.stringify(adrs, null, 2));
+}
+
+main();

package/src/scripts/adr-tags.js

@@ -0,0 +1,125 @@
+#!/usr/bin/env node
+
+/**
+ * adr-tags.js - List all distinct tags across all ADRs with usage counts
+ *
+ * This CLI script scans all YAML ADR files in the project's .claude/adrs/
+ * and extracts tag information, producing a sorted summary of tag usage.
+ *
+ * Usage:
+ *   node ~/.claude/scripts/adr-tags.js
+ *
+ * Output:
+ *   JSON array to stdout: [{ tag, count, adrs }] sorted by count descending
+ *
+ * Example output:
+ *   [
+ *     { "tag": "architecture", "count": 8, "adrs": ["ADR-001", "ADR-003"] },
+ *     { "tag": "agents", "count": 4, "adrs": ["ADR-003", "ADR-004"] }
+ *   ]
+ *
+ * Note: This script supplements the adr-agent (per ADR-009), providing
+ * quick CLI access to tag information without invoking the full agent.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const yaml = require('js-yaml');
+
+// ADRs are in the project's .claude/adrs/ directory (relative to CWD)
+const ADRS_DIR = path.join(process.cwd(), '.claude', 'adrs');
+
+/**
+ * Read and parse a YAML ADR file, extracting id and tags
+ * @param {string} filePath - Absolute path to the YAML file
+ * @returns {{ id: string, tags: string[] } | null} - Parsed data or null on error
+ */
+function parseAdrFile(filePath) {
+  try {
+    const content = fs.readFileSync(filePath, 'utf8');
+    const data = yaml.load(content);
+
+    // Extract id and tags, handling missing fields gracefully
+    const id = data?.id || path.basename(filePath, '.yaml');
+    const tags = Array.isArray(data?.tags) ? data.tags : [];
+
+    return { id, tags };
+  } catch (error) {
+    // Log to stderr so it doesn't pollute JSON output
+    console.error(`Warning: Failed to parse ${filePath}: ${error.message}`);
+    return null;
+  }
+}
+
+/**
+ * Scan ADRs directory and collect all tag information
+ * @returns {Map<string, string[]>} - Map of tag -> array of ADR ids
+ */
+function collectTags() {
+  const tagMap = new Map();
+
+  // Check if ADRs directory exists
+  if (!fs.existsSync(ADRS_DIR)) {
+    console.error(`Warning: ADRs directory not found: ${ADRS_DIR}`);
+    return tagMap;
+  }
+
+  // Read all .yaml files in the ADRs directory
+  const files = fs.readdirSync(ADRS_DIR)
+    .filter(file => file.endsWith('.yaml'))
+    .map(file => path.join(ADRS_DIR, file));
+
+  // Process each ADR file
+  for (const filePath of files) {
+    const adr = parseAdrFile(filePath);
+    if (!adr) continue;
+
+    // Add this ADR's id to each of its tags
+    for (const tag of adr.tags) {
+      if (!tagMap.has(tag)) {
+        tagMap.set(tag, []);
+      }
+      tagMap.get(tag).push(adr.id);
+    }
+  }
+
+  return tagMap;
+}
+
+/**
+ * Format tag data as sorted output array
+ * @param {Map<string, string[]>} tagMap - Map of tag -> array of ADR ids
+ * @returns {Array<{ tag: string, count: number, adrs: string[] }>}
+ */
+function formatOutput(tagMap) {
+  const result = [];
+
+  for (const [tag, adrs] of tagMap.entries()) {
+    result.push({
+      tag,
+      count: adrs.length,
+      adrs: adrs.sort() // Sort ADR ids alphabetically within each tag
+    });
+  }
+
+  // Sort by count descending, then alphabetically by tag name for ties
+  result.sort((a, b) => {
+    if (b.count !== a.count) {
+      return b.count - a.count;
+    }
+    return a.tag.localeCompare(b.tag);
+  });
+
+  return result;
+}
+
+// Main execution
+function main() {
+  const tagMap = collectTags();
+  const output = formatOutput(tagMap);
+
+  // Output JSON to stdout
+  console.log(JSON.stringify(output, null, 2));
+}
+
+main();