@damper/cli 0.1.0 → 0.1.1

package/README.md

@@ -0,0 +1,202 @@
+# @damper/cli
+
+Agent orchestration CLI for working on [Damper](https://usedamper.com) roadmap tasks with Claude Code.
+
+## What it does
+
+1. **Picks a task** from your Damper roadmap (interactive or by ID)
+2. **Creates an isolated git worktree** for the task
+3. **Bootstraps context** - fetches task details, project docs, and critical rules from Damper
+4. **Launches Claude Code** with full context ready to go
+
+Claude then handles the task lifecycle via Damper MCP - logging commits, adding notes, and completing/abandoning tasks.
+
+## Installation
+
+```bash
+# Run directly with npx (recommended)
+npx @damper/cli
+
+# Or install globally
+npm install -g @damper/cli
+```
+
+### Prerequisites
+
+- [Claude Code CLI](https://claude.ai/code) installed
+- A Damper account with an API key
+
+## Quick Start
+
+```bash
+# First time? Run setup to configure MCP and API key
+npx @damper/cli setup
+
+# Start working on a task
+npx @damper/cli
+```
+
+## Commands
+
+### `npx @damper/cli` (default)
+
+Interactive task picker. Shows:
+- **In Progress** - Tasks with existing worktrees you can resume
+- **Available** - Planned tasks from your roadmap
+
+```bash
+npx @damper/cli                    # Interactive picker
+npx @damper/cli --task 42          # Start specific task
+npx @damper/cli --type bug         # Filter by type
+npx @damper/cli --status planned   # Filter by status
+```
+
+### `npx @damper/cli setup`
+
+Configure Damper MCP in Claude Code. Run this first if you haven't set up MCP yet.
+
+- Checks if Claude CLI is installed
+- Configures `~/.claude/settings.json` with Damper MCP
+- Prompts for API key if not in environment
+
+### `npx @damper/cli status`
+
+Show all tracked worktrees and their task status.
+
+```
+Tracked Worktrees:
+
+myproject (current)
+  /Users/me/projects/myproject
+
+  ● #42 [in_progress]
+    Path: myproject-oauth-support
+    Branch: feature/oauth-support
+    Created: 2/5/2025
+```
+
+### `npx @damper/cli cleanup`
+
+Remove worktrees for completed or abandoned tasks. Interactive selection with auto-detection of:
+- Completed tasks
+- Abandoned tasks (unlocked in Damper)
+- Missing worktree directories
+
+## Workflow
+
+### Starting a New Task
+
+```
+$ npx @damper/cli
+
+? Select a task to work on:
+  --- Available Tasks ---
+❯ #42 Add OAuth support [feature] !
+  #38 Fix login timeout [bug] ~
+
+✓ Task locked in Damper
+✓ Created worktree: ../myproject-oauth-support
+✓ Created TASK_CONTEXT.md
+✓ Updated CLAUDE.md with task section
+
+Starting Claude Code for task #42: Add OAuth support
+```
+
+### Resuming Work
+
+```
+$ npx @damper/cli
+
+? Select a task to work on:
+  --- In Progress (your worktrees) ---
+❯ #42 Add OAuth support [feature] !
+    Worktree: myproject-oauth-support
+  --- Available Tasks ---
+  #38 Fix login timeout [bug] ~
+
+✓ Resuming: #42 Add OAuth support
+✓ Updated TASK_CONTEXT.md with latest notes
+```
+
+### Generated Files
+
+The CLI creates these files in the worktree:
+
+**`TASK_CONTEXT.md`** - Full task context for Claude:
+- Critical rules (must-follow patterns)
+- Damper workflow instructions
+- Task description and implementation plan
+- Previous session notes and commits
+- Project architecture docs
+- Available templates and modules
+- Linked customer feedback
+
+**`CLAUDE.md`** (appended) - Task-specific section pointing to TASK_CONTEXT.md
+
+### Task Lifecycle (handled by Claude via MCP)
+
+Once Claude is running, it handles:
+- `add_commit` - Log commits to Damper
+- `add_note` - Record decisions and progress
+- `complete_task` - Mark done with summary
+- `abandon_task` - Hand off with notes for next agent
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `DAMPER_API_KEY` | Your Damper API key (or configure via `setup`) |
+| `DAMPER_API_URL` | API URL override (default: `https://api.usedamper.com`) |
+
+## How it Works
+
+### Worktree Isolation
+
+Each task gets its own git worktree:
+```
+myproject/                    # Main repo
+../myproject-oauth-support/   # Task #42 worktree
+../myproject-fix-login/       # Task #38 worktree
+```
+
+The CLI automatically:
+- Creates the worktree with a feature branch
+- Symlinks `node_modules` (detects monorepo structure)
+- Copies `.env` files
+
+### Context from Damper
+
+The CLI fetches from Damper:
+- Task details (description, plan, subtasks)
+- Project context (architecture, conventions)
+- Critical rules (shown prominently to Claude)
+- Templates (code patterns to follow)
+- Modules (monorepo structure)
+- Previous agent notes (for continuity)
+
+This context survives Claude conversation compaction because it's in local files.
+
+### State Tracking
+
+Worktree-to-task mappings are stored in `~/.damper/worktrees.json`. This enables:
+- Showing "resume" options for in-progress tasks
+- Detecting stale worktrees for cleanup
+- Tracking across multiple projects
+
+## Parallel Work
+
+Run multiple instances in different terminals:
+
+```bash
+# Terminal 1
+npx @damper/cli --task 42
+
+# Terminal 2
+npx @damper/cli --task 38
+```
+
+Each task gets its own worktree and Claude session.
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@damper/cli",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "CLI tool for orchestrating Damper task workflows with Claude Code",
   "author": "Damper <hello@usedamper.com>",
   "repository": {