@shipfast-ai/shipfast 1.1.0 → 1.3.1

package/README.md

@@ -4,7 +4,12 @@
 
 **Autonomous context-engineered development system with SQLite brain.**
 
-**5 agents. 17 commands. Per-task fresh context. 70-90% fewer tokens.**
+**5 agents. 20 commands. Per-task fresh context. 70-90% fewer tokens.**
+
+[![npm version](https://img.shields.io/npm/v/@shipfast-ai/shipfast)](https://www.npmjs.com/package/@shipfast-ai/shipfast)
+[![npm downloads](https://img.shields.io/npm/dw/@shipfast-ai/shipfast)](https://www.npmjs.com/package/@shipfast-ai/shipfast)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Tests](https://github.com/shipfast-ai/shipfast/actions/workflows/test.yml/badge.svg)](https://github.com/shipfast-ai/shipfast/actions/workflows/test.yml)
 
 Claude Code, OpenCode, Gemini CLI, Kilo, Codex, Copilot, Cursor, Windsurf, Antigravity, Augment, Trae, Qwen Code, CodeBuddy, Cline
 
@@ -20,19 +25,19 @@ Works on Mac, Windows, and Linux.
 
 ## Why ShipFast?
 
-Context rot kills AI coding quality. As the context window fills up, output degrades.
+Context rot kills AI coding quality. As the context window fills up, output degrades — Task 5 is worse than Task 1.
 
 ShipFast fixes this with a **SQLite knowledge graph** that gives each agent fresh context and gets smarter every session.
 
-- **17 commands, 5 composable agents** — simple to learn, covers the full workflow
-- **SQLite brain** — queryable knowledge graph, no per-task state files
+- **SQLite brain** — queryable knowledge graph replaces markdown state files
+- **Fresh context per task** — each Builder agent starts clean, quality stays consistent
 - **3K-40K tokens per feature** — 70-90% less than typical AI dev workflows
-- **Fresh context per task** — no accumulated garbage between tasks
-- **Cross-session learning** — records decisions and patterns, gets cheaper over time
-- **Codebase indexing in <1 second** — 973 files indexed in 636ms
-- **Graph-derived architecture** — auto-detects layers from import graph
-- **Cross-repo linking** — search across multiple repos with `shipfast link`
-- **17 MCP tools** — structured brain access, no SQL improvisation
+- **Self-improving** — records patterns and decisions, gets cheaper over time
+- **Smart model selection** — dynamically picks haiku/sonnet/opus based on task + feedback loop
+- **Domain-aware questioning** — 6 domains, 20+ question templates, zero LLM cost
+- **Wave-based execution** — independent tasks run in parallel, dependent tasks run sequentially
+- **Cross-repo support** — link repos, search across brains, cross-repo blast radius
+- **22 languages indexed** in <1 second — architecture layers auto-derived from import graph
 - **Works with 14 AI coding tools** — auto-detects and installs for all
 
 ---
@@ -41,45 +46,64 @@ ShipFast fixes this with a **SQLite knowledge graph** that gives each agent fres
 
 ```bash
 npm i -g @shipfast-ai/shipfast
-```
-
-Auto-detects your AI tools and installs for all of them. Then index your repo:
-
-```bash
 cd your-project
 shipfast init
 ```
 
-Verify: run `/sf-help` in your AI tool.
-
-### Staying Updated
-
-```bash
-shipfast update
-```
-
-Updates the package and re-detects runtimes (catches newly installed AI tools).
+Auto-detects your AI tools and installs for all of them. Verify: run `/sf-help` in your AI tool.
 
 ### Terminal Commands
 
 ```bash
-shipfast init           # Index current repo into .shipfast/brain.db
+shipfast init           # Index repo + auto-configure permissions (no --dangerously-skip-permissions needed)
 shipfast init --fresh   # Full reindex (clears existing brain)
 shipfast link <path>    # Link another repo for cross-repo search
 shipfast unlink [path]  # Unlink a repo (or all)
+shipfast doctor         # Check brain.db health + diagnose issues
+shipfast permissions    # Show configured permission allowlist
 shipfast status         # Show installed runtimes + brain + links
 shipfast update         # Update + re-detect runtimes
 shipfast uninstall      # Remove from all AI tools
-shipfast help           # Show all commands
 ```
 
+### Permissions (Zero Prompts)
+
+`shipfast init` auto-configures safe permission rules in `.claude/settings.json`. ShipFast operations (Read, Edit, Write, git, build, test, grep) run without permission prompts. Destructive commands (rm, curl, ssh, sudo) still require approval.
+
+No `--dangerously-skip-permissions` needed. Run `shipfast permissions` to view the allowlist.
+
+If auto-configured permissions don't work for your setup, you can fall back to:
+```bash
+claude --dangerously-skip-permissions
+```
+This skips ALL permission checks — use only in trusted environments.
+
 ---
 
 ## How It Works
 
-Already have code? `shipfast init` indexes your codebase in under 1 second — functions, types, imports, git history. All stored in a SQLite database.
+### 1. Discuss (when needed)
+
+```
+/sf-discuss Add authentication
+```
 
-### 1. Plan Phase
+**Domain-aware** ambiguity detection — zero LLM tokens:
+
+| Domain | Example Questions |
+|--------|-------------------|
+| **UI** | Layout density? Interaction pattern? Empty state? Responsive approach? |
+| **API** | Response format? Error handling? Auth mechanism? Versioning? |
+| **Database** | ORM? Migration strategy? Data access pattern? |
+| **Auth** | JWT/session/OAuth? Token storage? Role model? |
+| **Content** | Markdown/rich text? Tone? i18n? |
+| **Infra** | Deploy target? CI/CD pipeline? |
+
+Auto-detects domain from task keywords. Answers stored as locked decisions — never asked again, even across sessions.
+
+**Flags**: `--batch` (group questions), `--chain` (auto-run discuss → plan → check → execute), `--assume` (auto-resolve from brain.db patterns)
+
+### 2. Plan
 
 ```
 /sf-plan Add Stripe billing with webhooks
@@ -87,112 +111,103 @@ Already have code? `shipfast init` indexes your codebase in under 1 second — f
 
 Spawns two agents in fresh contexts:
 
-**Scout** — Researches the codebase. Finds relevant files, functions, consumers. Tags findings with confidence levels: [VERIFIED], [CITED], [ASSUMED].
+**Scout** — Researches the codebase. Finds relevant files, functions, consumers. Tags findings: [VERIFIED], [CITED], [ASSUMED].
 
-**Architect** — Creates a precise task list using goal-backward methodology. Starts from "what does done look like" and works backward to tasks. Each task has exact file paths, consumer lists, verify commands, and measurable done criteria.
+**Architect** — Creates tasks using goal-backward methodology. Each task has exact file paths, consumer lists, verify commands, and done criteria. Sets dependency graph for wave grouping.
 
-Tasks are stored in brain.db. No PLAN.md files.
+Tasks stored in brain.db.
 
-### 2. Execute
+### 3. Execute
 
 ```
 /sf-do
 ```
 
-Reads tasks from brain.db and executes them.
+**Complexity auto-detection** routes to the right workflow:
 
-**Trivial tasks** (fix a typo, add an import) — executes inline. No agents, no planning. ~3K tokens.
+**Trivial** (fix a typo) — executes inline, no agents. ~3K tokens.
 
-**Medium tasks** (add a component, refactor a module) — one Builder agent with all tasks batched. ~15K tokens.
+**Medium** (add a component) — one Builder agent with all tasks batched. ~15K tokens.
 
-**Complex tasks** (new feature across multiple files) — **per-task Builder agents with fresh context each.** No accumulated garbage between tasks. Each Builder:
+**Complex** (new feature across files) — per-task Builder agents with **fresh context each**:
 
-1. Reads files + greps for consumers of anything it'll change
-2. Implements following existing patterns
-3. Runs build/typecheck — fixes errors before committing
-4. Commits with conventional format
-5. Updates task status in brain.db
+```
+[1/6] Building: Split LocationList into layouts...
+[1/6] ✓ Split LocationList (commit: a1b2c3d)
 
-After all tasks: Critic reviews the diff. Scribe records decisions and learnings to brain.db.
+[2/6] Building: Extract RectangleTile sub-components...
+[2/6] ✓ Extract RectangleTile (commit: e4f5g6h)
 
-### 3. Verify
+...
 
-```
-/sf-verify
+[6/6] ✓ Extract Featured hooks (commit: m7n8o9p)
 ```
 
-Separate verification in fresh context:
+Each Builder gets fresh context — no accumulated garbage from previous tasks. Quality stays consistent from Task 1 to Task 6.
 
-- **3-level artifact validation**: exists → substantive (not stubs) → wired (imported and used)
-- **Data flow tracing**: components receive real data, not hardcoded empty arrays
-- **Consumer integrity**: removed exports have zero remaining consumers
-- **Stub detection**: TODO, FIXME, placeholder, empty handlers, console.log, debugger
-- **Build verification**: runs build command, reports pass/fail
-
-Scores: PASS / PASS_WITH_WARNINGS / FAIL with specific failure details.
-
-### 4. Discuss (when needed)
+**Wave-based parallel execution:**
 
 ```
-/sf-discuss Add authentication
+Independent tasks (no shared files) → same wave → run in parallel
+Dependent tasks (shared files/imports) → separate waves → run sequentially
 ```
 
-Detects ambiguity before planning (zero LLM tokens — rule-based):
+The Architect sets the dependency graph. `groupIntoWaves()` computes waves. Independent tasks in the same wave launch simultaneously — multiple Builder agents at once.
 
-- **WHERE**: No file paths mentioned
-- **WHAT**: No behavior described
-- **HOW**: Multiple approaches possible
-- **RISK**: Touches auth/payment/data
-- **SCOPE**: Broad request with conjunctions
+**After all tasks complete:**
+- **Critic** agent (fresh context) reviews the entire `git diff` — checks consumer integrity, import consistency, security
+- **Scribe** agent (fresh context) records decisions + learnings to brain.db
+- **Branch audit** (automatic on non-default branches) — reports MIGRATED / MISSING / SAFELY REMOVED vs default branch
 
-Asks 2-5 targeted questions. Stores answers as locked decisions in brain.db. Never asks the same question twice (even across sessions).
+**Dynamic model selection** per agent:
 
-### 5. Ship
+| Condition | Model |
+|-----------|-------|
+| Well-known domain (2+ high-confidence learnings) | **Haiku** (cheapest) |
+| Standard task | **Sonnet** (default) |
+| Complex multi-area, no prior patterns | **Opus** (best reasoning) |
+| Budget low (<40%) | **All Haiku** (degradation) |
+| `--cheap` flag | **All Haiku** |
+| `--quality` flag | **Sonnet/Opus** |
 
-```
-/sf-ship
-```
+Models auto-adjust via feedback loop — tracks success/failure rates per model+domain, upgrades haiku→sonnet when failing, downgrades when consistently succeeding.
 
-Creates branch, generates PR description from brain.db (decisions, tasks, changes), pushes, outputs PR link.
+**All execution flags**: `--tdd` (test-first), `--research` (force Scout), `--verify` (force verification), `--no-plan` (skip planning), `--discuss` (force discussion), `--cheap` (all haiku), `--quality` (sonnet/opus)
 
-### 6. Repeat → Complete → Next Milestone
+### 4. Verify
 
 ```
-/sf-discuss Phase 2
-/sf-plan Phase 2: Payment webhooks
-/sf-do
 /sf-verify
-/sf-ship
-...
-/sf-milestone complete
-/sf-milestone new v2.0
 ```
 
-Or for simple tasks, just run directly:
+Fresh context verification:
 
-```
-/sf-do fix the login bug
-```
+- **3-level artifact validation**: exists → substantive (not stubs) → wired (imported and used)
+- **Data flow tracing**: components receive real data, not hardcoded empty arrays
+- **Consumer integrity**: removed exports have zero remaining consumers
+- **Stub detection**: TODO, FIXME, placeholder, empty handlers, console.log, debugger
+- **Schema drift detection**: warns when ORM models change without migrations (Prisma, Drizzle, TypeORM, Django, Rails, Knex)
+- **TDD sequence check**: verifies test(...) commits before feat(...) commits
+- **Build verification**: runs build command, reports pass/fail
+- **Branch audit**: compares changes vs default branch, flags missing migrations
 
-ShipFast auto-detects complexity and runs the right workflow.
+Scores: **PASS** / **PASS_WITH_WARNINGS** / **FAIL** with specific details.
 
----
-
-## Why Fresh Context Matters
+### 5. Ship
 
-Context rot is the #1 quality killer. As the context window fills with file reads, error messages, and previous task artifacts, Claude's output quality degrades.
+```
+/sf-ship
+```
 
-ShipFast solves this:
+Creates branch, generates PR description from brain.db (decisions, tasks, changes), pushes, outputs PR link. Runs configurable post-ship hook if set.
 
-| Phase | Agent | Context |
-|---|---|---|
-| Research | Scout (Haiku) | Fresh — only brain.db context |
-| Planning | Architect (Sonnet) | Fresh — Scout findings + brain.db |
-| Execution | Builder (Sonnet) × N | Fresh per task — task plan + brain.db |
-| Review | Critic (Haiku) | Fresh — git diff only |
-| Documentation | Scribe (Haiku) | Fresh — session summary |
+### 6. Workflows
 
-Each agent starts clean. No accumulated garbage. Quality stays consistent from first task to last.
+```
+Simple:     /sf-do fix the typo in header
+Standard:   /sf-plan add dark mode → /sf-check-plan → /sf-do → /sf-verify
+Complex:    /sf-project Build billing → /sf-discuss → /sf-plan → /sf-do → /sf-verify → /sf-ship
+```
 
 ---
 
@@ -202,154 +217,102 @@ All state lives in `.shipfast/brain.db`. Zero markdown files.
 
 | Table | What it stores |
 |---|---|
-| `nodes` | Functions, types, classes, components (auto-extracted) |
+| `nodes` | Functions, types, classes, components (auto-extracted, 22 languages) |
 | `edges` | Import/call/dependency relationships + git co-change patterns |
-| `decisions` | Compact Q&A pairs (~40 tokens each, not ~500 like markdown) |
-| `learnings` | Error→fix patterns with confidence scoring |
-| `tasks` | Execution history with commit SHAs |
-| `requirements` | REQ-IDs mapped to phases for tracing |
+| `decisions` | Locked Q&A pairs with domain tags (~40 tokens each) |
+| `learnings` | Error→fix patterns with confidence scoring (0.0-1.0) |
+| `tasks` | Execution history with commit SHAs, tokens used, duration |
+| `seeds` | Forward ideas captured during work for future milestones |
+| `model_performance` | Success/failure tracking per model+domain (feedback loop) |
 | `checkpoints` | Git stash refs for rollback |
-| `hot_files` | Most frequently changed files from git history |
+| `requirements` | REQ-IDs mapped to phases for tracing |
 | `architecture` | Auto-computed layers from import graph (zero hardcoding) |
-| `folders` | Directory roles auto-detected from import patterns |
-
-**Incremental indexing**: only re-indexes changed files (~300ms). Deleted files auto-cleaned.
-
-**MCP Server**: brain.db is exposed as 17 structured MCP tools. LLMs call these instead of improvising SQL.
-
----
-
-## Architecture Intelligence
-
-ShipFast auto-derives architecture layers from the import graph — **zero hardcoded folder patterns**. Works with any project structure, any language.
-
-**How it works**:
-1. BFS from entry points (files nothing imports) assigns layer depth
-2. Fuzzy import resolution handles `@/`, `~/`, and alias paths
-3. Folder roles detected from aggregate import/export ratios
-4. Recomputed on every `shipfast init` (instant)
-
-**What it produces**:
-
-- **Layer 0** (entry): files nothing imports — pages, routes, App.tsx
-- **Layer 1-N** (deeper): each layer imported by the layer above
-- **Leaf layer**: files that import nothing — types, constants
-- **Folder roles**: entry (imports many), shared (imported by many), consumer, leaf, foundation
+| `folders` | Directory roles: entry, shared, consumer, leaf, foundation |
+| `hot_files` | Most frequently changed files from git history |
+| `config` | Token budget, model tiers, post-ship hooks, default branch |
 
-**Why it matters**: Scout knows which layer a file lives in. Builder knows to check upstream consumers before modifying a shared layer. Critic can detect skip-layer violations. Verifier traces data flow from entry to data source.
+**Incremental indexing**: ~300ms for changed files. Deleted files auto-cleaned. Stale learnings auto-pruned.
 
-All exposed as MCP tools: `brain_arch_layers`, `brain_arch_folders`, `brain_arch_file`, `brain_arch_data_flow`, `brain_arch_most_connected`.
+**MCP Server**: 23 structured tools for IDE integration. Commands and agents use MCP tools — no raw SQL.
 
 ---
 
 ## Agents
 
-5 composable agents with compressed behavioral rules.
-
-| Agent | Role | Model | Key Rules |
+| Agent | Role | Default Model | Key Behaviors |
 |---|---|---|---|
-| **Scout** | Research | Haiku | Confidence tagging, 12-call limit, architecture mapping, consumer lists |
-| **Architect** | Planning | Sonnet | Goal-backward, exact file paths, consumer checks, scope prohibition, must-haves |
-| **Builder** | Execution | Sonnet | Impact analysis before every change, per-task build verify, 3-attempt limit, deviation tracking, threat scan |
-| **Critic** | Review | Haiku | 3 depths (quick/standard/deep), import graph tracing, consumer integrity check |
-| **Scribe** | Documentation | Haiku | Records decisions + learnings to brain.db via sqlite3, PR descriptions |
-
-### Builder's Rule Zero
-
-Before deleting, removing, or modifying ANY function, type, or export:
+| **Scout** | Research | Haiku | 6-direction flow tracing, confidence tagging, consumer discovery |
+| **Architect** | Planning | Sonnet (Opus for complex) | Goal-backward, dependency graph, STRIDE threats, scope guard |
+| **Builder** | Execution | Sonnet (Haiku if learned) | Impact analysis before every change, per-task build verify, 3-attempt limit |
+| **Critic** | Review | Haiku (Sonnet for security) | Auto-depth (quick/standard/deep), import graph tracing, consumer integrity |
+| **Scribe** | Documentation | Haiku | Records decisions + learnings to brain.db, generates PR descriptions |
 
-```bash
-grep -r "functionName" --include="*.ts" --include="*.tsx" .
-```
-
-If other files use it → update them or keep it. **NEVER remove without checking consumers.** This single rule prevents 80% of refactoring bugs.
+Models are **dynamically selected** — not fixed. The feedback loop tracks which model succeeds for which domain and auto-adjusts.
 
 ---
 
 ## Commands
 
-### Core Workflow
-
-| Command | What it does |
-|---|---|
-| `/sf-do <task>` | Execute a task. Auto-detects complexity: trivial → medium → complex |
-| `/sf-plan <task>` | Research (Scout) + Plan (Architect). Stores tasks in brain.db |
-| `/sf-check-plan` | Verify plan before execution: scope, consumers, deps, STRIDE threats |
-| `/sf-verify` | Verify completed work: artifacts, data flow, stubs, build, consumers |
-| `/sf-discuss <task>` | Detect ambiguity, ask targeted questions, lock decisions |
-
-### Projects
+### Core
 
 | Command | What it does |
 |---|---|
-| `/sf-project <desc>` | Decompose large project into phases with REQ-ID tracing + 4 parallel researchers |
-| `/sf-milestone [complete\|new]` | Complete current milestone or start next version |
-| `/sf-workstream <action>` | Parallel feature branches: create, list, switch, complete |
+| `/sf-do <task>` | The one command. Auto-detects complexity, runs the right workflow. |
+| `/sf-plan <task>` | Research (Scout) + Plan (Architect). Stores tasks in brain.db. |
+| `/sf-discuss <task>` | Domain-aware questioning. 6 domains, 20+ templates, zero LLM cost. |
+| `/sf-check-plan` | Validate plan: scope, consumers, dependencies, STRIDE threats. |
+| `/sf-verify` | Verify: artifacts, data flow, stubs, schema drift, build, consumers. |
 
-### Shipping
+### Projects & Worktrees
 
 | Command | What it does |
 |---|---|
-| `/sf-ship` | Create branch, push, output PR link with auto-generated description |
+| `/sf-project <desc>` | Decompose large project into phases with REQ-ID tracing. |
+| `/sf-milestone` | Complete current milestone or start next version. |
+| `/sf-worktree create` | Create isolated worktree with smart branch naming + multi-repo support. |
+| `/sf-worktree check` | Migration audit: MIGRATED / MISSING / SAFELY REMOVED / MODIFIED / ADDED. |
+| `/sf-worktree list\|switch\|status\|complete` | Manage parallel worktrees. |
 
-### Session
+### Shipping & Session
 
 | Command | What it does |
 |---|---|
-| `/sf-status` | Show brain stats, tasks, checkpoints, version |
-| `/sf-resume` | Resume from previous session (loads state from brain.db) |
-| `/sf-undo [task-id]` | Rollback a completed task via git revert |
+| `/sf-ship` | Create branch, push, PR link + post-ship hook. |
+| `/sf-status` | Brain stats, tasks, checkpoints, version. |
+| `/sf-resume` | Resume from previous session. |
+| `/sf-undo [task-id]` | Rollback a specific task. |
+| `/sf-rollback [last\|all\|N]` | Rollback last task, last N, or entire session. |
 
-### Knowledge
+### Knowledge & Analysis
 
 | Command | What it does |
 |---|---|
-| `/sf-brain <query>` | Query knowledge graph: files, decisions, learnings, hot files |
-| `/sf-learn <pattern>` | Teach a reusable pattern (persists across sessions) |
-| `/sf-map` | Generate codebase report: architecture layers, hot files, co-change clusters |
+| `/sf-brain <query>` | Query knowledge graph: files, decisions, learnings, seeds, hot files. |
+| `/sf-learn <pattern>` | Teach a reusable pattern (persists across sessions). |
+| `/sf-map` | Codebase report: architecture layers, hot files, co-change clusters. |
+| `/sf-cost` | Token usage breakdown by agent, domain, model + success rates. |
+| `/sf-diff` | Smart diff — changes grouped by task with file stats. |
 
 ### Config
 
 | Command | What it does |
 |---|---|
-| `/sf-config` | View or set model tiers and preferences |
-| `/sf-help` | Show all commands with workflows |
-
----
-
-## Workflows
-
-```
-Simple:     /sf-do fix the typo in header
-Standard:   /sf-plan add dark mode → /sf-check-plan → /sf-do → /sf-verify
-Complex:    /sf-project Build billing → /sf-discuss → /sf-plan → /sf-check-plan → /sf-do → /sf-verify → /sf-ship
-```
+| `/sf-config` | View or set model tiers, token budget, post-ship hooks. |
+| `/sf-help` | Show all commands. |
 
 ---
 
 ## Self-Improving Memory
 
-ShipFast gets cheaper and smarter every session:
-
-1. **First time** doing X → full pipeline (scout + architect + builder + critic)
-2. **Second time** → skip scout + architect (brain has the patterns)
-3. **Third time** → skip critic too (high confidence learnings)
-
-Learnings are confidence-weighted (0.0-1.0). Boost on successful reuse. Auto-prune after 30 days of non-use. Users teach directly with `/sf-learn`.
-
----
+ShipFast gets cheaper every session:
 
-## Configuration
+1. **First time** doing X → full pipeline (scout + architect + builder + critic). ~30K tokens.
+2. **Second time** → skip scout + architect (brain has the patterns). ~15K tokens.
+3. **Third time** → skip critic too (high confidence). ~8K tokens.
 
-Model tiers per agent (configurable with `/sf-config`):
+Learnings are confidence-weighted (0.0-1.0). Boosted on successful reuse. Auto-pruned after 30 days of non-use.
 
-```
-Scout:     haiku    (reading is cheap)
-Architect: sonnet   (planning needs reasoning)
-Builder:   sonnet   (coding needs quality)
-Critic:    haiku    (diff review is pattern matching)
-Scribe:    haiku    (writing commit msgs is simple)
-```
+**Seeds**: Ideas surfaced during work are captured for future milestones — not lost, not distracting.
 
 ---
 
@@ -357,9 +320,7 @@ Scribe:    haiku    (writing commit msgs is simple)
 
 22 languages indexed: JavaScript, TypeScript, Rust, Python, Go, Java, Kotlin, Swift, C, C++, Ruby, PHP, Dart, Elixir, Scala, Zig, Lua, R, Julia, C#, F#, Vue/Svelte/Astro.
 
-50+ directories skipped (node_modules, dist, target, __pycache__, .venv, Pods, etc.) sourced from GitHub's official gitignore templates.
-
-25+ lock files skipped (package-lock.json, Cargo.lock, poetry.lock, go.sum, etc.).
+50+ directories skipped. 25+ lock files skipped.
 
 ---
 
@@ -370,7 +331,11 @@ shipfast uninstall
 npm uninstall -g @shipfast-ai/shipfast
 ```
 
-Auto-detects and removes from all runtimes. Cleans settings.json hooks.
+---
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for architecture overview, code style, and how to help.
 
 ---
 

package/agents/architect.md

@@ -1,7 +1,7 @@
 ---
 name: sf-architect
 description: Planning agent. Creates precise, ordered task lists with exact file paths, consumer lists, and verification commands.
-model: sonnet
+model: sonnet  # default — overridden by applyGuardrails() (may use opus for complex multi-area tasks)
 tools: Read, Glob, Grep, Bash
 ---
 
@@ -34,7 +34,7 @@ Must-haves:
 </methodology>
 
 <task_rules>
-## Task Anatomy — 4 required fields (gap #13)
+## Task Anatomy — 4 required fields
 
 Every task MUST have:
 
@@ -52,7 +52,7 @@ Every task MUST have:
 </task_rules>
 
 <consumer_checking>
-## CRITICAL: Consumer list per task (gap #13)
+## CRITICAL: Consumer list per task
 
 For every task that modifies/removes a function, type, selector, export, or component:
 
@@ -64,13 +64,13 @@ This prevents cascading breaks. GSD's planner embeds interface context. We list
 </consumer_checking>
 
 <ordering>
-## Interface-first ordering (gap #18)
+## Interface-first ordering
 
 1. **First task**: Define types, interfaces, exports (contracts)
 2. **Middle tasks**: Implement against defined contracts
 3. **Last task**: Wire implementations to consumers
 
-## Dependency ordering (gap #15)
+## Dependency ordering
 
 Tasks are ordered by dependency:
 - Task B depends on Task A if: B reads files A creates, B calls functions A implements
@@ -86,7 +86,7 @@ If tasks touch the SAME file → they MUST be sequential (not parallel).
 </ordering>
 
 <scope_guard>
-## Scope reduction prohibition (gap #16)
+## Scope reduction prohibition
 
 BANNED language in task descriptions:
 - "v1", "v2", "simplified version", "hardcoded for now"
@@ -126,7 +126,7 @@ Only include for tasks that create/modify security-relevant code. Skip for pure
 </threat_model>
 
 <user_decisions>
-## Honor locked decisions (gap #20)
+## Honor locked decisions
 
 If brain.db has decisions for this area:
 - User said "use library X" → task MUST use X, not alternative

package/agents/builder.md

@@ -1,7 +1,7 @@
 ---
 name: sf-builder
 description: Execution agent. Checks consumers before changing. Builds and verifies per task. Follows existing patterns exactly.
-model: sonnet
+model: sonnet  # default — overridden by applyGuardrails() (may use haiku for well-known domains)
 tools: Read, Write, Edit, Bash, Glob, Grep
 ---
 
@@ -54,16 +54,15 @@ Track every deviation: `[Tier N] Fixed: [what] in [file]`
 **Tier 4 — Architecture**: New DB tables, schema changes, library swaps, breaking APIs
 → STOP. Report: "This requires [change]. Proceed?"
 
-## Scope boundary (gap #2)
+## Scope boundary
 
 Only fix issues DIRECTLY caused by your current task.
 Pre-existing problems in other files → do NOT fix. Output:
 `OUT_OF_SCOPE: [file:line] [issue]`
 
 For each out-of-scope issue, also record it as a seed for future work:
-```bash
-sqlite3 .shipfast/brain.db "INSERT INTO seeds (idea, source_task, domain, priority) VALUES ('[improvement idea]', '[current task id]', '[domain]', 'someday');"
-```
+
+Use the `brain_seeds` MCP tool with: `{ "action": "add", "idea": "[improvement idea]", "source_task": "[current task id]", "domain": "[domain]", "priority": "someday" }`
 </deviation_tiers>
 
 <patterns>
@@ -91,11 +90,11 @@ State blocker in one sentence. Write code or report what's missing.
 - Attempt 2: Re-read relevant code, different approach
 - Attempt 3: STOP. `DEFERRED: [task] — [error] — [tried]`
 
-## Auth Gate Detection (gap #11)
+## Auth Gate Detection
 401, 403, "Not authenticated", "Please login" = NOT a bug.
 STOP. Report: `AUTH_GATE: [service] needs [action]`
 
-## Continuation Protocol (gap #10)
+## Continuation Protocol
 If resuming from a previous session:
 1. `git log --oneline -10` — verify previous commits exist
 2. Do NOT redo completed tasks
@@ -123,7 +122,7 @@ NEVER: `git add .`, `--no-verify`, `--force`, `git clean`, `git reset --hard`, a
 </commit_protocol>
 
 <quality_checks>
-## Before EVERY commit (gap #3, #9, #12)
+## Before EVERY commit
 
 1. **Build passes** — `tsc --noEmit` / `npm run build` / `cargo check`. Fix first.
 2. **Task verify passes** — run the verify command from the plan
@@ -135,7 +134,7 @@ If stubs found: complete them or `STUB: [what's incomplete]`
 </quality_checks>
 
 <self_check>
-## Before reporting done (gap #7)
+## Before reporting done
 
 1. Verify every file you claimed to create EXISTS: `[ -f path ] && echo OK || echo MISSING`
 2. Verify every commit exists: `git log --oneline -5`
@@ -145,7 +144,7 @@ Output: `SELF_CHECK: [PASSED/FAILED] [details]`
 </self_check>
 
 <threat_scan>
-## Before reporting done (gap #8)
+## Threat scan before reporting done
 
 Check if your changes introduced:
 - New API endpoints not in original plan