cc-sidebar 0.1.5 → 0.1.8

package/README.md

@@ -90,11 +90,37 @@ Data is stored in `~/.claude-sidebar/`:
 
 ## Claude Code Setup
 
-Two optional integrations to make Claude aware of the sidebar:
+Three optional integrations to make Claude aware of the sidebar:
 
-### 1. Auto-completion (Recommended)
+### 1. TodoWrite Sync Hook (Recommended)
 
-Add this to your `~/.claude/CLAUDE.md` so Claude automatically marks sidebar tasks as done:
+This hook syncs Claude's TodoWrite output to the sidebar, so you can see Claude's progress in real-time.
+
+Add to your `~/.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "TodoWrite",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bun ~/.bun/install/global/node_modules/cc-sidebar/src/sync-todos.ts"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+If you already have other hooks, merge the `PostToolUse` array with your existing hooks.
+
+### 2. Auto-completion (Optional)
+
+Add this to your `~/.claude/CLAUDE.md` so Claude automatically marks sidebar tasks as done when it finishes work:
 
 ```markdown
 ## Sidebar Integration
@@ -122,13 +148,13 @@ Keep it simple - if no clear match, don't move anything. User can manually mark
 ```
 ```
 
-### 2. Install Skills (Recommended)
+### 3. Install Skills
 
 cc-sidebar includes skills that integrate with Claude Code:
 
 | Skill | Trigger | What it does |
 |-------|---------|--------------|
-| `/brain-dump` | `/brain-dump` | Interview to extract tasks from messy thoughts, creates plan + todos |
+| `/clarify` | `/clarify` | Interview to clarify tasks, creates plan + todos (works for new or existing tasks) |
 | `/prioritize` | `/prioritize` | Re-prioritize all sidebar tasks as a staff engineer |
 | `sidebar-awareness` | (always on) | Gives Claude context about sidebar data files |
 
@@ -142,7 +168,7 @@ cp -r ~/.bun/install/global/node_modules/cc-sidebar/skills/* ~/.claude/skills/
 Or install individually:
 
 ```bash
-cp -r ~/.bun/install/global/node_modules/cc-sidebar/skills/brain-dump ~/.claude/skills/
+cp -r ~/.bun/install/global/node_modules/cc-sidebar/skills/clarify ~/.claude/skills/
 cp -r ~/.bun/install/global/node_modules/cc-sidebar/skills/prioritize ~/.claude/skills/
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cc-sidebar",
-  "version": "0.1.5",
+  "version": "0.1.8",
   "description": "Visual sidebar for managing todos, tasks, and context alongside Claude Code",
   "author": "Tyler Nishida",
   "license": "MIT",
@@ -24,7 +24,8 @@
   "files": [
     "src",
     "skills",
-    "commands"
+    "commands",
+    "scripts"
   ],
   "scripts": {
     "start": "bun run src/cli.ts",

package/scripts/statusline.sh

@@ -0,0 +1,61 @@
+#!/bin/bash
+# Claude Code statusline script for claude-sidebar
+# Receives JSON from Claude Code via stdin, extracts key metrics, writes to shared file
+#
+# Install: Add to ~/.claude/settings.json:
+# { "statusline": { "script": "/path/to/claude-sidebar/scripts/statusline.sh" } }
+
+set -e
+
+# Read JSON from stdin
+input=$(cat)
+
+# Extract context window data
+CTX_SIZE=$(echo "$input" | jq -r '.context_window.context_window_size // 200000')
+USAGE=$(echo "$input" | jq -r '.context_window.current_usage // {}')
+INPUT_TOKENS=$(echo "$USAGE" | jq -r '(.input_tokens // 0) + (.cache_creation_input_tokens // 0) + (.cache_read_input_tokens // 0)')
+OUTPUT_TOKENS=$(echo "$input" | jq -r '.context_window.current_usage.output_tokens // 0')
+
+# Calculate context percentage (input + output tokens)
+TOTAL_TOKENS=$((INPUT_TOKENS + OUTPUT_TOKENS))
+if [ "$CTX_SIZE" -gt 0 ]; then
+  CTX_PERCENT=$((TOTAL_TOKENS * 100 / CTX_SIZE))
+else
+  CTX_PERCENT=0
+fi
+
+# Extract cost and duration
+COST=$(echo "$input" | jq -r '.cost.total_cost_usd // 0')
+DURATION_MS=$(echo "$input" | jq -r '.cost.total_duration_ms // 0')
+DURATION_MIN=$((DURATION_MS / 60000))
+
+# Extract model
+MODEL=$(echo "$input" | jq -r '.model.display_name // "Unknown"')
+
+# Get project directory and git info
+PROJECT_DIR=$(echo "$input" | jq -r '.workspace.project_dir // ""')
+BRANCH=""
+REPO=""
+if [ -n "$PROJECT_DIR" ] && [ -d "$PROJECT_DIR" ]; then
+  cd "$PROJECT_DIR" 2>/dev/null || true
+  BRANCH=$(git branch --show-current 2>/dev/null || echo "")
+  REPO=$(basename "$PROJECT_DIR")
+fi
+
+# Ensure directory exists
+mkdir -p ~/.claude-sidebar
+
+# Write processed data
+cat > ~/.claude-sidebar/statusline.json << EOF
+{
+  "contextPercent": $CTX_PERCENT,
+  "contextTokens": $TOTAL_TOKENS,
+  "contextSize": $CTX_SIZE,
+  "costUsd": $COST,
+  "durationMin": $DURATION_MIN,
+  "model": "$MODEL",
+  "branch": "$BRANCH",
+  "repo": "$REPO",
+  "updatedAt": "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+}
+EOF

package/skills/clarify/SKILL.md

@@ -0,0 +1,247 @@
+---
+name: clarify
+description: |
+  Clarify tasks through deep conversation - works for new ideas or existing sidebar tasks.
+
+  Use when: (1) You have thoughts/ideas that need clarification before becoming actionable,
+  (2) You want to clarify a single task through conversation,
+  (3) The sidebar sends a task for clarification (via `c` key).
+
+  Triggers: "/clarify", "clarify this", "let me explain this task".
+
+  Requires: Claude Code sidebar for todo integration.
+---
+
+# Clarify Skill
+
+Clarify tasks through structured, in-depth conversation. Creates a **spec for each todo** (not a shared plan).
+
+## Invocation
+
+- `/clarify` - Start interviewing from scratch
+- `/clarify [text]` - Clarify provided text (single task or many)
+- `/clarify --task-id <id> [task content]` - Clarify existing sidebar task (sent by sidebar `c` key)
+
+## Process
+
+### 1. Detect Mode
+
+Check if invoked with `--task-id`:
+- **With task ID**: Updating an existing sidebar task
+- **Without task ID**: Creating new todo(s) from scratch
+
+### 2. Interview Phase
+
+**Interview me in detail using AskUserQuestion about literally anything:**
+- Technical implementation details
+- UI & UX considerations
+- Concerns and risks
+- Tradeoffs between approaches
+- Edge cases and error handling
+- Dependencies and blockers
+- Success criteria
+
+**CRITICAL RULES:**
+- Make sure questions are NOT obvious - don't ask things that are clear from context
+- Be very in-depth - continue interviewing continually until complete
+- Multiple rounds of questions are expected and encouraged
+- Always end with "Anything else I should know?" as a final question
+
+**If the user provided text** (`/clarify [text]`):
+- Skip opening invitation - go straight to clarifying questions
+
+**If no text was provided** (`/clarify` alone):
+- Start with: "What's on your mind? Tell me everything - tasks, concerns, ideas, whatever's floating around."
+- Let them ramble, then ask clarifying questions
+
+### 3. Write Spec for Each Todo
+
+After interviewing, create a **spec for each todo**. The spec is stored directly on the task (in the `spec` field), not in a separate plan file.
+
+**Spec format:**
+```
+## [Task Title]
+
+### What
+[Clear description of what needs to be done]
+
+### Why
+[The purpose/motivation]
+
+### How
+[Implementation approach based on interview]
+
+### Acceptance Criteria
+- [ ] Criterion 1
+- [ ] Criterion 2
+
+### Notes
+[Any constraints, risks, or considerations from interview]
+```
+
+### 4. Update or Create Todos
+
+**If updating existing task** (has `--task-id`):
+
+```bash
+node << 'SCRIPT'
+const fs = require('fs');
+const crypto = require('crypto');
+const path = require('path');
+const sidebarDir = path.join(require('os').homedir(), '.claude-sidebar');
+const hash = crypto.createHash('sha256').update(process.cwd()).digest('hex').slice(0, 12);
+const tasksPath = path.join(sidebarDir, 'projects', hash, 'tasks.json');
+let tasks = JSON.parse(fs.readFileSync(tasksPath, 'utf-8'));
+const task = tasks.find(t => t.id === 'TASK_ID_HERE');  // REPLACE with actual task ID
+if (task) {
+  task.clarified = true;
+  task.section = 'clarified';
+  task.spec = `SPEC_CONTENT_HERE`;  // REPLACE with actual spec
+  fs.writeFileSync(tasksPath, JSON.stringify(tasks, null, 2));
+  console.log('Task clarified with spec');
+}
+SCRIPT
+```
+
+**If creating new todos** (no `--task-id`):
+
+Extract discrete, actionable tasks. Each todo should be:
+- **Specific**: Clear what needs to be done
+- **Actionable**: Can be worked on independently
+- **Has a spec**: Detailed specification from interview
+
+**Prioritization (act as staff engineer):**
+- Dependencies first (blockers)
+- Urgency (bugs, deadlines)
+- Impact (high-value over nice-to-have)
+- Quick wins for momentum
+
+Mark top 3 as "recommended".
+
+```bash
+node << 'SCRIPT'
+const fs = require('fs');
+const crypto = require('crypto');
+const path = require('path');
+
+const sidebarDir = path.join(require('os').homedir(), '.claude-sidebar');
+const hash = crypto.createHash('sha256').update(process.cwd()).digest('hex').slice(0, 12);
+const projectDir = path.join(sidebarDir, 'projects', hash);
+const tasksPath = path.join(projectDir, 'tasks.json');
+
+fs.mkdirSync(projectDir, { recursive: true });
+
+let existing = [];
+try { existing = JSON.parse(fs.readFileSync(tasksPath, 'utf-8')); } catch {}
+
+// REPLACE with extracted tasks - each has its own spec
+const newTodos = [
+  {
+    content: "Task 1 here",
+    priority: 1,
+    recommended: true,
+    spec: `## Task 1\n\n### What\n...\n\n### Why\n...\n\n### How\n...\n\n### Acceptance Criteria\n- [ ] ...`
+  },
+  // ... more tasks
+].map(task => ({
+  id: crypto.randomUUID(),
+  content: task.content,
+  createdAt: new Date().toISOString(),
+  section: 'clarified',
+  clarified: true,
+  priority: task.priority,
+  recommended: task.recommended,
+  spec: task.spec
+}));
+
+const combined = [...existing, ...newTodos];
+fs.writeFileSync(tasksPath, JSON.stringify(combined, null, 2));
+console.log('Added ' + newTodos.length + ' clarified todos to sidebar');
+SCRIPT
+```
+
+### 5. Present and Prompt
+
+After creating/updating todos:
+
+1. Show summary of what was clarified
+2. Show the spec for each task
+3. Ask: **"Execute this task now, or save for later?"**
+   - Execute → start working immediately
+   - Save → confirm clarified and stop
+
+**Example output:**
+```
+Clarified 2 todos:
+
+1. ★ Implement user authentication
+   Spec: JWT-based auth with 24hr expiry, refresh tokens...
+
+2. ★ Add rate limiting to API
+   Spec: 100 req/min per user, 429 response, Redis backend...
+
+Execute the first task now, or save for later?
+```
+
+## Relationship to Other Skills
+
+| Skill | Purpose |
+|-------|---------|
+| `/clarify` | Interview and write spec for task(s) |
+| `/prioritize` | Re-evaluate all tasks as staff engineer |
+| Atomic Plans | Track execution progress when working on task |
+
+**Flow:**
+1. **Clarify** creates specs (the "what")
+2. **Prioritize** decides what's next
+3. **Atomic Plans** tracks execution (the "how/progress")
+
+## Example Session
+
+```
+User: /clarify I need to add dark mode support
+
+Claude: [AskUserQuestion]
+- Should this affect the entire app or just certain components?
+- Do you want system preference detection (prefers-color-scheme)?
+- Are there specific colors/themes you want, or should I design them?
+- Should the preference persist across sessions (localStorage)?
+
+User: [Answers each question]
+
+Claude: [AskUserQuestion - follow-up]
+- For the color palette, do you have brand colors to work with?
+- Should transitions be animated when switching themes?
+- Any components that should NOT support dark mode?
+- Anything else I should know?
+
+User: [Answers]
+
+Claude: [Creates todo with spec]
+
+Clarified 1 todo:
+
+★ Add dark mode support
+  Spec:
+  ## Dark Mode Support
+
+  ### What
+  Add system-wide dark mode toggle with OS preference detection
+
+  ### Why
+  User requested for better nighttime usability
+
+  ### How
+  - CSS custom properties for colors
+  - React context for theme state
+  - localStorage for persistence
+  - prefers-color-scheme media query for initial
+
+  ### Acceptance Criteria
+  - [ ] Toggle switches between light/dark
+  - [ ] Respects OS preference on first visit
+  - [ ] Persists choice in localStorage
+  - [ ] Smooth transition animation
+
+Execute this task now, or save for later?
+```

package/skills/prioritize/SKILL.md

@@ -51,6 +51,8 @@ As a staff engineer, evaluate each task considering:
 - **Impact**: High-value features over nice-to-haves.
 - **Effort**: Quick wins can build momentum; large tasks may need breakdown.
 - **Context**: If user provided context, weight it heavily.
+- **Specs**: Read the `spec` field of clarified tasks for detailed requirements.
+- **Section**: Clarified tasks (with specs) are generally ready to execute.
 
 Assign each task:
 - `priority`: Numeric (1 = most important, higher = less important)
@@ -124,9 +126,18 @@ Other tasks:
 Tasks have been re-prioritized in your sidebar.
 ```
 
+## Skill Flow
+
+This skill is part of a chain:
+
+1. **Clarify** → Creates specs for each task (the "what")
+2. **Prioritize** → Staff engineer decides what's next (this skill)
+3. **Atomic Plans** → Track execution progress when working
+
 ## Notes
 
 - This skill reads and modifies the sidebar's tasks.json directly
-- It preserves all existing task fields (id, content, clarified, planPath, etc.)
+- It preserves all existing task fields (id, content, clarified, spec, etc.)
 - Only updates `priority` and `recommended` fields
 - Can be run anytime - safe to run multiple times
+- Read specs to understand task complexity when prioritizing