fathom-cli 0.1.7 → 0.2.0

package/README.md

@@ -1,10 +1,6 @@
 # fathom-cli
 
-Workflow intelligence for AI-augmented development. Estimate token costs before work, automatically track actuals during work, reconcile and calibrate after work, and build velocity benchmarks over time.
-
-```
-intake → estimate → build (tracked) → reconcile → calibrate → velocity
-```
+Estimate AI token costs before work, track actuals during work, and calibrate your estimates after. One command runs the full loop.
 
 ## Install
 
@@ -12,179 +8,87 @@ intake → estimate → build (tracked) → reconcile → calibrate → velocity
 npm install -g fathom-cli
 ```
 
-## Quick Start
-
-```bash
-# Quick estimate — "how much will this cost?"
-# AI scores complexity automatically when ANTHROPIC_API_KEY is set
-fathom estimate "React dashboard with OAuth"
-
-# Generate a full spec sheet — "break this down into work items"
-fathom intake "Users say the calendar is slow and Zoom links are missing" --project myapp
-
-# Analyze a full spec with multiple features
-fathom analyze spec.md --project myapp
-
-# Scaffold tracking for an existing project
-fathom setup --project myapp
-
-# Import and auto-tag Claude Code sessions
-fathom track --project myapp
-
-# Compare estimates vs actuals
-fathom reconcile --project myapp
-
-# See velocity metrics
-fathom velocity --project myapp
-```
+Add `ANTHROPIC_API_KEY` to your project's `.env` file (auto-loaded).
 
-## Commands
-
-| Command | Description |
-|---------|-------------|
-| `fathom estimate <desc>` | Quick cost estimate — AI scores complexity, returns tokens + cost |
-| `fathom intake <text>` | Generate spec sheet — extracts work items, estimates each, outputs markdown |
-| `fathom analyze <spec>` | Parse spec, estimate all features, generate registry |
-| `fathom track` | Import Claude Code sessions, auto-tag to features |
-| `fathom reconcile` | Compare estimates vs actuals per feature |
-| `fathom calibrate` | Show drift and suggest profile adjustments |
-| `fathom velocity` | Velocity metrics and benchmarks |
-| `fathom status` | Project overview with tracking data |
-| `fathom pricing` | Show current model pricing |
-| `fathom setup` | Scaffold `.claude/` skill + hooks + registry |
-| `fathom rename <name>` | Rename project across all config files |
-| `fathom validate <spec>` | Validate spec file format |
-| `fathom init` | Initialize global config |
-
-## How It Works
-
-### 1. Estimate vs Intake (Before Work)
-
-**`estimate`** — quick cost number from a description:
+## One Command
 
 ```bash
-fathom estimate "Build a real-time chat system with WebSocket support"
-# AI analyzes → L complexity, 205K tokens, $2.51, recommends Sonnet
-# Use --complexity M to override, --no-ai for heuristic-only scoring
-```
-
-**`intake`** — full spec sheet from raw feedback:
-
-```bash
-# Interactive mode — auto-detects project, shows local files to pick from,
-# prompts where to save the spec
-fathom intake
-
-# Or pass everything directly
-fathom intake --file meeting-notes.md -o intake-specs/sprint-plan.md
+fathom
 ```
 
-Intake auto-detects your project name from `.claude/te/config.json`, scans the current directory for markdown files to offer as input, and saves specs to `intake-specs/` by default (configurable). Remembers your preferred output directory for next time.
+That's it. `fathom` with no arguments walks through the entire workflow:
 
-Use `estimate` when you want a quick number. Use `intake` when you want a plan.
+1. **Intake** — extracts work items from your requirements, estimates tokens + cost
+2. **Build** — generates a context-rich prompt and launches Claude Code
+3. **Review** — tracks sessions, reconciles estimates vs actuals, calibrates
 
-Both use a calibrated model: base tokens per task type × complexity multiplier × overhead (context resend, tool calls, thinking, error recovery, planning, review).
+New project? It auto-scaffolds everything. Returning project? Shows progress and offers contextual next steps:
 
-### 2. Track (During Work)
-
-Fathom automatically discovers Claude Code sessions from `~/.claude/projects/` and tags them to features using a 4-signal cascade:
-
-1. **Explicit feature ID** in conversation → 99% confidence
-2. **Git branch** pattern match → 85%
-3. **Keyword** match → 75%
-4. **File path** match → 70%
-
-Zero configuration needed — just run `fathom track`.
-
-### 3. Reconcile + Calibrate (After Work)
-
-```bash
-fathom reconcile --project myapp
-# Shows: Feature | Estimated | Actual | Drift% | Cost | Sessions
-
-fathom calibrate --project myapp
-# Shows: Feature | Drift | Suggested adjustment multiplier
 ```
+$ fathom
 
-Over time, your estimates get more accurate as the profiles learn from real data.
-
-### 4. Velocity Intelligence
+  Fathom — myproject
+  6/12 features complete (50%) — $8.40 of $14.20 spent
 
-```bash
-fathom velocity --project myapp --benchmarks
-# "M-complexity React components: $0.85 avg, 1.1 days, 2.8 sessions"
+  What would you like to do?
+  ❯ Continue building (next: payment-integration)
+    New intake — add more work
+    Review — reconcile recent sessions
+    Status overview
 ```
 
-## Dashboard
-
-Fathom includes a real-time web dashboard (Next.js + Convex) with 7 views: overview, projects, burn-down, intake queue, cost analytics, velocity benchmarks, and calibration health.
+Resume from any phase:
 
 ```bash
-# Set up Convex sync (optional — CLI works fully offline)
-export CONVEX_URL=https://your-deployment.convex.cloud
-
-# All commands auto-sync when CONVEX_URL is set
-fathom analyze spec.md --project myapp  # → syncs estimates
-fathom track --project myapp            # → syncs actuals
+fathom --from build     # Skip intake
+fathom --from review    # Just track + reconcile + calibrate
+fathom --auto           # Skip all confirmations
 ```
 
-See the [full repo](https://github.com/olivelliott/fathom) for dashboard setup.
+## Build Modes
 
-## Intake Pipeline
+Fathom offers three ways to build (choice is remembered):
 
-Turn raw feedback into estimated, structured work items:
+- **Launch Claude Code** — opens Claude with full project context, priority queue, and feature details
+- **Worktree** — creates an isolated git branch per feature, launches Claude in it
+- **Manual** — prints the spec path and build prompt so you can build however you want
 
-```bash
-# Interactive — detects files in cwd, prompts for everything
-fathom intake
-
-# Direct — pass input and output explicitly
-fathom intake --file meeting-notes.md -o intake-specs/plan.md
-
-# Pipe-friendly — markdown to stdout
-fathom intake --file feedback.md --markdown
-```
-
-When run interactively, intake will:
-1. Auto-detect your project name (or prompt + save it)
-2. List markdown/text files in your current directory to pick from
-3. Show a results table, then ask where to save the spec
-4. Remember your preferred output directory for next time
+## Individual Commands
 
-Output is a buildable markdown spec with task checkboxes, acceptance criteria, priority grouping, and cost estimates.
+All commands also work standalone:
 
-Requires `ANTHROPIC_API_KEY` environment variable (auto-loaded from `.env`).
+| Command | What it does |
+|---------|-------------|
+| `fathom` | **Full workflow** — intake → build → review |
+| `fathom intake` | Generate a spec from raw feedback (interactive) |
+| `fathom estimate <desc>` | Quick cost estimate for a single feature |
+| `fathom analyze <spec>` | Parse an existing spec and estimate all features |
+| `fathom setup` | Scaffold project tracking in `.claude/` |
+| `fathom track` | Import Claude Code sessions, auto-tag to features |
+| `fathom reconcile` | Compare estimates vs actuals |
+| `fathom calibrate` | Adjust profiles from real data |
+| `fathom velocity` | Throughput metrics and benchmarks |
+| `fathom status` | Project overview |
+| `fathom rename <name>` | Rename project across config files |
+| `fathom pricing` | Show model pricing |
 
 ## Environment Variables
 
-Fathom auto-loads `.env` files from the current directory, so you can set these in your project's `.env` instead of exporting them globally.
-
-| Variable | Required | Purpose |
-|----------|----------|---------|
-| `ANTHROPIC_API_KEY` | For `estimate` + `intake` | AI complexity scoring and work item extraction |
-| `CONVEX_URL` | Optional | Enable dashboard sync |
-
-## Spec Format
+Auto-loaded from `.env` in your project directory.
 
-Fathom parses markdown specs with `### Feature:` headings:
+| Variable | Purpose |
+|----------|---------|
+| `ANTHROPIC_API_KEY` | Required for `intake` and `estimate` |
+| `CONVEX_URL` | Optional — enables real-time dashboard sync |
 
-```markdown
-### Feature: User Authentication
-- **Complexity**: L
-- **Category**: Infrastructure
-- **Description**: OAuth2 with Google + email/password login
+## Dashboard
 
-### Feature: Dashboard
-- **Complexity**: M
-- **Category**: Frontend
-- **Description**: Main dashboard with metrics and charts
-```
+Optional web dashboard (Next.js + Convex) with project burn-down, velocity charts, cost analytics, and more. All CLI commands auto-sync when `CONVEX_URL` is set. See the [repo](https://github.com/olivelliott/fathom) for setup.
 
 ## Links
 
-- [GitHub Repository](https://github.com/olivelliott/fathom)
-- [Roadmap](https://github.com/olivelliott/fathom/blob/main/ROADMAP.md)
-- [Report an Issue](https://github.com/olivelliott/fathom/issues)
+- [GitHub](https://github.com/olivelliott/fathom)
+- [Issues](https://github.com/olivelliott/fathom/issues)
 
 ## License