shipr-agent 0.1.0 → 0.1.2

package/README.md

@@ -2,33 +2,307 @@
 
 > Fully autonomous terminal-based coding agent
 
-Shipr takes a plain-English mission description and produces a 100% working, committed, production-ready codebase — or halts cleanly without touching git.
+Shipr takes a plain-English mission description and produces a production-ready, committed codebase — or halts cleanly without touching git.
 
 ## Install
 
 ```bash
-npm install -g shipr
+npm install -g shipr-agent
 ```
 
-## Usage
+Or run directly without installing:
+
+```bash
+npx shipr-agent --help
+```
+
+## Quick Start
+
+```bash
+# 1. Authenticate with an AI provider
+shipr auth add github-copilot    # GitHub Device Flow (opens browser)
+shipr auth add openai             # paste your API key
+shipr auth add anthropic          # paste your API key
+
+# 2. Verify authentication
+shipr auth list
+
+# 3. Navigate to your project
+cd my-project/
+
+# 4. Run a mission
+shipr run "Add user authentication with JWT and refresh tokens"
+```
+
+## Commands
+
+### `shipr run <mission>`
+
+Run an autonomous coding mission. This is the main command.
+
+```bash
+# Basic usage — uses the first authenticated provider
+shipr run "Build a REST API with CRUD endpoints for users and posts"
+
+# Choose a specific provider
+shipr run --provider github-copilot "Add WebSocket real-time notifications"
+shipr run --provider openai "Refactor the database layer to use Prisma"
+shipr run --provider anthropic "Write comprehensive test coverage"
+
+# Dry run — plan without executing (no files changed)
+shipr run --simulate "Migrate from Express to Fastify"
+
+# Set a cost budget (halts if exceeded)
+shipr run --budget 5.00 "Build an admin dashboard"
+
+# Run slices in parallel (up to 4)
+shipr run --parallel 4 "Add search, filtering, and pagination"
+
+# Use the rich Ink-based TUI
+shipr run --rich "Build a payment integration"
+```
+
+**What happens during a mission:**
+
+```
+PREFLIGHT  →  Analyzes your codebase (files, frameworks, dependencies)
+CLARIFY    →  Asks clarifying questions (press Enter to accept defaults)
+RESEARCH   →  Studies codebase structure + web research
+PLAN       →  Creates a task DAG (directed acyclic graph) of work
+EXECUTE    →  Dispatches tasks to the AI, writes code, validates each step
+VERIFY     →  Runs 6-layer verification (typecheck, lint, test, build, custom, security)
+COMMIT     →  Squash-merges all changes into a clean commit
+```
+
+### `shipr new <name>`
+
+Scaffold a new project from a template.
+
+```bash
+shipr new my-api --type api          # Express + TypeScript API
+shipr new my-app --type web-app      # React + Vite web app
+shipr new my-cli --type cli          # Commander CLI tool
+shipr new my-lib --type library      # npm library with build
+shipr new my-svc --type monorepo     # Turborepo monorepo
+shipr new my-bot --type fullstack    # Full-stack app
+```
+
+### `shipr status`
+
+Show the current mission's state and progress.
 
 ```bash
-shipr run "add user authentication with JWT"
-shipr new my-app --type web-app
 shipr status
-shipr cost
 ```
 
-## Features
+```
+  Shipr  Mission: Build a REST API with auth
+  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  ✓ Status: EXECUTING
+  Slices: 3/6 done   Tasks: 9/18 done
+  Estimated cost: $2.00
+  Actual cost: $0.3280 (34 API calls)
+  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+### `shipr resume`
+
+Resume a previously interrupted or failed mission.
+
+```bash
+shipr resume                        # auto-find the most recent resumable mission
+shipr resume --mission m_abc123     # resume a specific mission
+shipr resume --provider anthropic   # resume with a different provider
+```
+
+### `shipr steer <instruction>`
+
+Send a mid-mission steering directive. Picked up at the next slice boundary.
+
+```bash
+shipr steer "Use PostgreSQL instead of SQLite"
+shipr steer "Skip the admin dashboard, focus on the API"
+shipr steer "Add rate limiting to all endpoints"
+```
 
-- 16 AI provider integrations (Anthropic, OpenAI, Gemini, Groq, and more)
-- Mission → Slice → Task execution hierarchy
-- 6-layer verification gate (typecheck, lint, test, build, custom, security)
-- TF-IDF context retrieval with 8-slot packet system
-- Git worktree isolation per mission
-- Cost/token tracking with budget enforcement
-- OAuth + OS keychain credential management
-- Rich terminal UI (chalk+ora default, Ink+React optional)
+### `shipr cost`
+
+Show cost and token usage across all missions.
+
+```bash
+shipr cost                    # all missions
+shipr cost --mission m_abc123 # specific mission
+```
+
+```
+  💰 Cost Summary
+
+  m_abc123  Build a REST API with auth
+     Cost: $0.3280  Input: 186.4K  Output: 34.2K  Calls: 34
+  m_def456  Add WebSocket notifications
+     Cost: $0.1890  Input: 98.1K   Output: 19.7K  Calls: 22
+  ──────────────────────────────────────────────────
+  Total  Cost: $0.5170  Input: 284.5K  Output: 53.9K  Calls: 56
+```
+
+### `shipr auth`
+
+Manage API credentials. Stored in OS keychain (macOS Keychain, Linux libsecret) — never on disk.
+
+```bash
+shipr auth add openai          # add API key for a provider
+shipr auth add github-copilot  # GitHub Device Flow (browser-based)
+shipr auth list                # show all providers and auth status
+shipr auth revoke openai       # remove stored credentials
+```
+
+### `shipr providers`
+
+List all 16 supported AI providers with models, pricing, and context windows.
+
+```bash
+shipr providers
+```
+
+### `shipr missions`
+
+List all past and current missions.
+
+```bash
+shipr missions
+```
+
+## Supported Providers
+
+| Provider | Auth | Models |
+|---|---|---|
+| **Anthropic** | API key | Claude Sonnet 4, Opus 4, Haiku 3.5 |
+| **OpenAI** | API key | GPT-4o, GPT-4o-mini, o3 |
+| **Google Gemini** | API key | Gemini 2.5 Pro, 2.5 Flash |
+| **GitHub Copilot** | Device Flow | GPT-4o, Claude Sonnet 4 (free with subscription) |
+| **Groq** | API key | Llama 3.3 70B, Mixtral |
+| **Mistral** | API key | Mistral Large, Codestral |
+| **xAI** | API key | Grok 2 |
+| **DeepSeek** | API key | DeepSeek V3, Coder V3 |
+| **OpenRouter** | API key | 20+ models from all providers |
+| **Cohere** | API key | Command R+, Command R |
+| **Perplexity** | API key | Sonar Large, Sonar Small |
+| **AWS Bedrock** | AWS credentials | Claude, Llama, Mistral on AWS |
+| **Azure OpenAI** | OAuth | GPT-4o, GPT-4 on Azure |
+| **Ollama** | Local | Any local model |
+| **LM Studio** | Local | Any local model |
+| **vLLM** | Local | Any local model |
+
+## How It Works
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  "Add user authentication with JWT"                     │
+└──────────────────────┬──────────────────────────────────┘
+                       │
+          ┌────────────▼────────────┐
+          │      PREFLIGHT          │  Analyze codebase
+          │  Files, frameworks,     │  Estimate cost
+          │  dependencies, tests    │  Zero LLM tokens
+          └────────────┬────────────┘
+                       │
+          ┌────────────▼────────────┐
+          │      CLARIFY            │  Ask smart questions
+          │  "JWT or sessions?"     │  LLM-generated
+          │  "Which database?"      │
+          └────────────┬────────────┘
+                       │
+          ┌────────────▼────────────┐
+          │      RESEARCH           │  Codebase: static analysis
+          │  Import graph, deps,    │  Web: LLM-powered search
+          │  frameworks, patterns   │
+          └────────────┬────────────┘
+                       │
+          ┌────────────▼────────────┐
+          │      PLAN               │  Create task DAG
+          │  S01: Schema setup      │  Ordered by risk
+          │  S02: Auth middleware    │  Dependencies tracked
+          │  S03: CRUD endpoints    │
+          └────────────┬────────────┘
+                       │
+          ┌────────────▼────────────┐
+          │      EXECUTE            │  For each task:
+          │  Build context packet   │   → LLM generates code
+          │  Dispatch to LLM        │   → Apply file changes
+          │  Apply changes          │   → Hallucination guard
+          │  Run guards             │   → Stub detector
+          └────────────┬────────────┘
+                       │
+          ┌────────────▼────────────┐
+          │      VERIFY             │  6-layer gate:
+          │  ✓ typecheck            │   TypeScript compiler
+          │  ✓ lint                 │   Biome/ESLint
+          │  ✓ test                 │   bun test/jest
+          │  ✓ build                │   Build command
+          │  ✓ custom               │   User scripts
+          │  ✓ security             │   Pattern scanning
+          └────────────┬────────────┘
+                       │
+          ┌────────────▼────────────┐
+          │      COMMIT             │  Squash-merge
+          │  Clean commit message   │  Generate REPORT.md
+          │  Back to main branch    │  Cleanup worktree
+          └─────────────────────────┘
+```
+
+## Safety Guarantees
+
+- **No commit unless all 6 verify layers pass** — zero errors tolerated
+- **Git worktree isolation** — mission work happens on a separate branch
+- **Test immutability** — tests are never modified to make them pass
+- **Hallucination guard** — rejects empty/unchanged file responses
+- **Stub detector** — rejects TODO/FIXME/placeholder code
+- **Stuck detector** — halts on repeated identical responses or zero progress
+- **Budget enforcement** — halts if cost exceeds per-mission or monthly limit
+- **No force push** — ever
+- **Atomic file writes** — temp + rename for crash safety
+- **No plaintext credentials** — OS keychain or AES-256-GCM encrypted fallback
+
+## Configuration
+
+Create `.shipr/config.yaml` in your project (or `~/.shipr/config.yaml` for global defaults):
+
+```yaml
+# Default provider and model
+provider: github-copilot
+model: gpt-4o
+
+# Budget limits
+budget:
+  perMission: 5.00    # USD per mission
+  perMonth: 50.00     # USD per calendar month
+
+# Execution
+parallel: 2            # max concurrent slices (1-8)
+
+# Verify gate
+verify:
+  custom: "npm run check"   # custom verification command
+```
+
+## Project Structure
+
+After a mission, Shipr creates a `.shipr/` directory in your project:
+
+```
+.shipr/
+  config.yaml          # project-level configuration
+  missions/
+    M-abc123/
+      MISSION.json     # mission metadata
+      STATE.json       # state machine state
+      PLAN.json        # task DAG
+      RESEARCH.json    # codebase + web research findings
+      LEDGER.json      # cost/token tracking
+      CONTEXT.md       # task summaries and context
+      STEER.md         # steering directives
+      REPORT.md        # narrative completion report
+```
 
 ## License