chq 0.1.0

package/README.md

@@ -0,0 +1,271 @@
+# chq
+
+Orchestrate multi-repo tasks with [Claude Code](https://docs.anthropic.com/en/docs/claude-code) in parallel.
+
+`chq` breaks down a large cross-repository objective into isolated tasks, creates git worktrees for each, and dispatches parallel Claude Code sessions via [WezTerm](https://wezfurlong.org/wezterm/) panes — automatically respecting dependency order.
+
+## How It Works
+
+```
+chq init my-project          # Create a project
+chq plan "Migrate to EKS"    # Plan tasks with Claude Code
+chq setup                    # Create worktrees & CLAUDE.md
+chq dispatch                 # Launch Claude Code per task
+chq watch                    # Auto-dispatch as deps complete
+chq status                   # Check progress
+chq review                   # Review cross-repo consistency
+chq clean                    # Remove worktrees
+```
+
+### Workflow
+
+```
+ plan ──► setup ──► dispatch ──► watch ──► review ──► clean
+                        │           │
+                        ▼           ▼
+                   Claude Code   Auto-dispatch
+                   (per task)    (on completion)
+```
+
+1. **Plan** — Claude Code decomposes a goal into repo-scoped, PR-sized tasks with dependency edges
+2. **Setup** — Creates a git worktree per task (topologically sorted), stacking branches for same-repo dependencies
+3. **Dispatch** — Opens a WezTerm pane per ready task, each running Claude Code with a solve prompt
+4. **Watch** — Polls for PR creation, marks tasks done, and dispatches newly unblocked tasks
+5. **Review** — Claude Code reviews all worktrees for cross-repo consistency
+
+## Prerequisites
+
+| Tool | Purpose |
+|------|---------|
+| [Bun](https://bun.sh/) | Runtime & build |
+| [git](https://git-scm.com/) | Worktree operations |
+| [ghq](https://github.com/x-motemen/ghq) | Local repo path resolution |
+| [gh](https://cli.github.com/) | PR status checks |
+| [WezTerm](https://wezfurlong.org/wezterm/) | Pane splitting for parallel sessions |
+| [Claude Code](https://docs.anthropic.com/en/docs/claude-code) | AI coding agent |
+
+## Installation
+
+```bash
+git clone https://github.com/shoppingjaws/chq.git
+cd chq
+bun install
+bun run build
+bun link
+```
+
+## Quick Start
+
+```bash
+# 1. Initialize global config (optional)
+chq config init
+
+# 2. Create a project
+chq init my-migration
+
+# 3. Plan tasks interactively with Claude Code
+cd ~/chq/my-migration
+chq plan "Migrate authentication from session-based to JWT"
+
+# 4. Create worktrees
+chq setup
+
+# 5. Launch all ready tasks
+chq dispatch
+
+# 6. Or auto-dispatch on completion
+chq watch
+```
+
+## Commands
+
+### `chq init <project-name>`
+
+Creates `~/chq/<project-name>/` with an empty `chq.json`.
+
+### `chq plan <goal>`
+
+Launches an interactive Claude Code session that decomposes the goal into tasks and writes them to `chq.json`.
+
+### `chq setup`
+
+For each task in `chq.json`:
+- Resolves the local repo path via `ghq`
+- Creates a git worktree at `~/chq/<project>/sub-<task-id>`
+- Stacks branches for same-repo dependencies (e.g., `main <- chq/proj/t1 <- chq/proj/t3`)
+- Generates a `CLAUDE.md` with the task overview
+
+### `chq status`
+
+Displays a table with status icons:
+
+```
+Project: my-migration
+
+ ID   Title                  Repo              Blocked By  Status       PR
+ t1   Add JWT middleware     org/api-server    -           done         Merged
+ t2   Update auth client     org/web-app       -           running      Open
+ t3   Migration script       org/api-server    t1          ready        -
+ t4   Update docs            org/docs          t1,t2       pending      -
+```
+
+| Icon | Meaning |
+|------|---------|
+| `pending` | Blocked by unfinished dependencies |
+| `ready` | All dependencies done, waiting to dispatch |
+| `running` | Claude Code session active |
+| `done` | PR created |
+| `failed` | Dispatch failed |
+
+### `chq dispatch`
+
+Finds tasks that are `pending` with all `blockedBy` tasks `done`, updates them to `running`, and opens a WezTerm pane for each with Claude Code.
+
+### `chq watch`
+
+Polling loop that:
+1. Checks running tasks for PR creation (marks them `done`)
+2. Dispatches newly unblocked tasks
+3. Prints status
+4. Exits when all tasks are done
+
+Poll interval: `CHQ_POLL_INTERVAL` env var or `pollInterval` in global config (default: 30s).
+
+### `chq review`
+
+Launches Claude Code to review all worktrees for cross-repo consistency, API compatibility, and merge-order safety.
+
+### `chq clean [--force] [--all]`
+
+Removes worktrees. `--force` skips confirmation, `--all` deletes the project directory entirely.
+
+### `chq list`
+
+Lists all projects under `~/chq/` with done/total counts.
+
+### `chq config`
+
+Manage global configuration at `~/.config/chq/`.
+
+```bash
+chq config init          # Scaffold config.json + prompt templates
+chq config init --force  # Overwrite existing files
+chq config show          # Display current settings
+chq config path          # Print config directory path
+```
+
+## Configuration
+
+### Global Config (`~/.config/chq/config.json`)
+
+```json
+{
+  "chqHome": "~/chq",
+  "pollInterval": 30
+}
+```
+
+| Key | Default | Description |
+|-----|---------|-------------|
+| `chqHome` | `~/chq` | Root directory for projects |
+| `pollInterval` | `30` | Watch polling interval in seconds |
+
+### Custom Prompts (`~/.config/chq/prompts/`)
+
+Override the built-in prompts by placing Markdown files with `{{variable}}` placeholders:
+
+| File | Used by | Available variables |
+|------|---------|-------------------|
+| `solve.md` | `chq dispatch` | `{{projectName}}`, `{{projectDescription}}`, `{{taskId}}`, `{{taskTitle}}`, `{{taskDescription}}`, `{{taskRepo}}`, `{{blockedBy}}`, `{{baseBranch}}`, `{{branchName}}`, `{{draftFlag}}` |
+| `plan.md` | `chq plan` | `{{projectName}}`, `{{goal}}` |
+| `review.md` | `chq review` | (none) |
+
+Run `chq config init` to scaffold the default templates, then edit them.
+
+### Project Config (`~/chq/<project>/chq.json`)
+
+```json
+{
+  "name": "my-migration",
+  "description": "Migrate auth from session to JWT",
+  "createdAt": "2025-01-15T10:00:00.000Z",
+  "tasks": [
+    {
+      "id": "t1",
+      "title": "Add JWT middleware",
+      "description": "Implement JWT validation middleware in the API server...",
+      "repo": "org/api-server",
+      "blockedBy": [],
+      "status": "pending"
+    }
+  ]
+}
+```
+
+## Branch Strategy
+
+`chq` uses stacked branches for same-repo dependency chains:
+
+```
+main
+ └── chq/my-project/t1    (PR base: main)
+      └── chq/my-project/t3  (PR base: t1's branch)
+```
+
+When `t1`'s PR is merged, GitHub automatically rebases `t3`'s PR onto `main`.
+
+Cross-repo dependencies create Draft PRs to signal they depend on external changes.
+
+## FAQ
+
+### Do I need WezTerm?
+
+Yes. `chq dispatch` and `chq watch` use `wezterm cli split-pane` to open parallel Claude Code sessions. Support for other terminal multiplexers (tmux, Zellij) is not yet implemented.
+
+### Can I use this without `ghq`?
+
+Not currently. `chq setup` resolves local repository paths using `ghq list --full-path`. If the repo is not found, it suggests running `ghq get <repo>`.
+
+### What happens if Claude Code fails mid-task?
+
+The task stays in `running` status. You can:
+1. Manually fix the issue in the worktree (`~/chq/<project>/sub-<task-id>/`)
+2. Create the PR yourself, and `chq watch` will detect it and mark the task `done`
+3. Edit `chq.json` directly to reset the task to `pending` and re-dispatch
+
+### Can I edit `chq.json` manually?
+
+Yes. `chq.json` is the single source of truth. You can add/remove/reorder tasks, change dependencies, or reset statuses manually. Just ensure the JSON is valid.
+
+### How does task completion detection work?
+
+Two mechanisms:
+1. **Primary**: The Claude Code solve prompt instructs Claude to update `chq.json` status to `"done"` after creating a PR
+2. **Fallback**: `chq watch` checks for PR existence via `gh pr list --head <branch>`
+
+### Can I run `chq dispatch` multiple times?
+
+Yes. It only dispatches tasks that are `pending` with all dependencies `done`. Already `running` or `done` tasks are skipped.
+
+### How do I customize what Claude Code does for each task?
+
+Run `chq config init` to export the default prompt templates to `~/.config/chq/prompts/`. Edit `solve.md` to change the implementation instructions, PR format, or completion behavior.
+
+### What if I have a circular dependency?
+
+`chq setup` runs a topological sort and will error with a clear message:
+```
+Error: Circular dependency detected: t1 -> t3 -> t5 -> t1
+```
+
+### Can two tasks modify the same repository?
+
+Yes. Each task gets its own git worktree with a unique branch (`chq/<project>/<task-id>`). If one task depends on another in the same repo, the branch is stacked on top of the dependency's branch.
+
+### How do I resume after closing my terminal?
+
+Run `chq status` to see where things stand, then `chq dispatch` to launch any pending-and-ready tasks, or `chq watch` to resume the full automation loop.
+
+## License
+
+MIT

package/dist/commands/clean.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare function createCleanCommand(): Command;

package/dist/commands/config.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare function createConfigCommand(): Command;

package/dist/commands/dispatch.d.ts

@@ -0,0 +1,3 @@
+import { Command } from "commander";
+export declare function dispatchTasks(projectDir: string): void;
+export declare function createDispatchCommand(): Command;

package/dist/commands/init.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare function createInitCommand(): Command;

package/dist/commands/list.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare function createListCommand(): Command;

package/dist/commands/plan.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare function createPlanCommand(): Command;

package/dist/commands/review.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare function createReviewCommand(): Command;

package/dist/commands/setup.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare function createSetupCommand(): Command;

package/dist/commands/status.d.ts

@@ -0,0 +1,3 @@
+import { Command } from "commander";
+export declare function printStatus(projectDir: string): void;
+export declare function createStatusCommand(): Command;

package/dist/commands/watch.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare function createWatchCommand(): Command;

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+export {};