@shipfast-ai/shipfast 1.1.0 → 1.3.1

package/commands/sf/discuss.md

@@ -1,121 +1,168 @@
 ---
 name: sf:discuss
-description: "Detect ambiguity and ask targeted questions before planning. Stores answers as locked decisions."
-argument-hint: "<task description>"
+description: "Detect ambiguity and ask domain-specific questions before planning. Stores answers as locked decisions."
+argument-hint: "<task description> [--batch] [--chain] [--assume]"
 allowed-tools:
   - Read
   - Bash
   - AskUserQuestion
+  - Skill
 ---
 
 <objective>
-Smart questioning system that detects ambiguity BEFORE planning.
+Domain-aware questioning system that detects ambiguity BEFORE planning.
 Prevents wasting tokens on plans built from wrong assumptions.
 
-Only asks questions for detected ambiguity types:
-- WHERE: unclear which files/components to change
-- WHAT: unclear expected behavior
-- HOW: multiple valid approaches
-- RISK: touches sensitive areas (auth/payment/data)
-- SCOPE: request covers multiple features
+Detects 6 domains automatically: UI, API, Database, Auth, Content, Infra.
+Asks domain-specific questions (not generic ones).
+
+Flags:
+- `--batch` — Group all questions into 1-2 AskUserQuestion calls
+- `--chain` — After discussion, auto-run /sf-plan → /sf-check-plan → ask to execute
+- `--assume` — Auto-resolve using brain.db patterns (no questions)
 </objective>
 
 <process>
 
-## Step 1: Detect Ambiguity (zero tokens — rule-based)
+## Step 1: Detect Domain + Ambiguity (zero tokens — rule-based)
+
+**Auto-detect domain** from task keywords:
+- **UI**: style, layout, component, page, form, button, modal, responsive, dark mode
+- **API**: endpoint, route, handler, webhook, rest, graphql, middleware
+- **Database**: migration, schema, model, table, orm, prisma, drizzle
+- **Auth**: login, signup, password, permission, role, token, session, oauth, jwt
+- **Content**: docs, blog, email, notification, i18n, template
+- **Infra**: deploy, ci/cd, docker, k8s, monitoring, terraform
 
-Analyze the user's input for ambiguity patterns:
+Then detect ambiguity types:
+- **WHERE**: No file paths, component names, or locations mentioned
+- **WHAT**: No specific behavior described, very short input
+- **HOW**: Contains alternatives or describes a generic feature
+- **RISK**: Mentions auth/payment/database/delete/production
+- **SCOPE**: More than 30 words with 2+ conjunctions
 
-**WHERE** — No file paths, component names, or locations mentioned
-**WHAT** — No specific behavior/output described, request is very short
-**HOW** — Contains "or", "either", "maybe", or describes a generic feature (auth, cache, search)
-**RISK** — Mentions auth, payment, database, delete, production, deploy
-**SCOPE** — More than 30 words with 2+ conjunctions (and, also, plus)
+Report domain detection: `Domain: [ui, auth] | Ambiguities: [HOW, WHERE, RISK]`
 
 ## Step 2: Check Locked Decisions
 
 Query brain.db for existing decisions tagged with detected ambiguity types.
 Skip any ambiguity that was already resolved in a previous session.
 
-## Step 3: Generate Questions
+## Step 3: Ask Domain-Specific Questions
 
-For each remaining ambiguity, ask a targeted question:
+**If `--batch` flag is set**: Group all questions into AskUserQuestion calls (max 4 per call).
 
-**Multiple choice** (when possible — saves user effort):
-```
-How should authentication work?
-  a) JWT tokens (stateless, good for APIs)
-  b) Session cookies (stateful, good for web apps)
-  c) OAuth (delegate to Google/GitHub)
-  d) Other (describe)
-```
+**If `--assume` flag is set**: Auto-resolve and present assumptions (see Assumptions Mode below).
 
-**Confirmation** (for RISK):
-```
-This will modify the payment processing flow. Confirm:
-  - Are you working in a development environment?
-  - Should existing billing data be preserved?
-```
+For each remaining ambiguity, ask a **domain-specific** question:
 
-**Free text** (only when choices aren't possible):
-```
-Where should the new component be placed?
-(Hint: mention a directory or existing component to place it near)
-```
+### UI Domain
+- HOW: "Layout density? [Compact | Comfortable | Spacious]"
+- HOW: "Interaction pattern? [Inline editing | Modal dialogs | Page navigation | Drawer panels]"
+- HOW: "Empty state behavior? [Placeholder | Onboarding CTA | Hide section]"
+- WHERE: "Which page/route should this appear on?"
+- RISK: "Does this affect existing UI users rely on?"
 
-## Step 4: Lock Decisions
+### API Domain
+- HOW: "Response format? [JSON REST | GraphQL | tRPC | JSON-RPC]"
+- HOW: "Error handling? [HTTP status codes | Always 200 | RFC 7807]"
+- HOW: "Auth mechanism? [Bearer token | API key | Session cookie | Public]"
+- WHERE: "Which endpoint prefix? (e.g., /api/v1/users)"
+- RISK: "Public-facing or internal API?"
 
-After each answer, store in brain.db as a locked decision:
-```
-Question: "Auth approach?"
-Decision: "JWT tokens — stateless"
-Tags: "HOW"
-Phase: current phase/task
-```
+### Database Domain
+- HOW: "ORM? [Prisma | Drizzle | TypeORM | Knex | Raw SQL | Match existing]"
+- HOW: "Migration strategy? [Auto-generate | Manual | Schema push]"
+- WHERE: "Which table/model?"
+- RISK: "Data migration needed? Existing production data?"
+
+### Auth Domain
+- HOW: "Auth approach? [JWT | Session cookies | OAuth2 | API keys]"
+- HOW: "Token storage? [httpOnly cookie | localStorage | Memory | Secure cookie + CSRF]"
+- HOW: "Role model? [Simple roles | RBAC | ABAC | No roles]"
+- RISK: "Affects existing user sessions?"
+
+### Content Domain
+- HOW: "Format? [Markdown | Rich text | Structured JSON | Plain text]"
+- HOW: "Tone? [Technical | Casual | Formal | Match existing]"
+- HOW: "i18n? [English only | Multi-language | i18n-ready]"
+
+### Infra Domain
+- HOW: "Deploy target? [Vercel | AWS | Docker | Self-hosted | Match existing]"
+- HOW: "CI/CD? [GitHub Actions | GitLab CI | CircleCI | None | Match existing]"
+
+Use **multiple choice** for HOW questions (saves user effort).
+Use **free text** for WHERE questions.
+Use **confirmation** for RISK questions.
+
+## Step 4: Follow-Up Depth
+
+After each answer, score it:
+- Multiple choice selection → sufficient (1.0)
+- Short free text (<3 words) → needs follow-up (0.5)
+- "I don't know" / "not sure" → needs follow-up (0.0)
+
+**If score < 0.5**: Ask ONE follow-up:
+- WHERE: "You mentioned [answer]. Can you be more specific — which file or directory?"
+- WHAT: "You said [answer]. What should the user see when this is done?"
+- HOW: "You picked [answer]. Any specific library or pattern to follow?"
+
+**Max 2 follow-up rounds per ambiguity**. After that, lock whatever we have.
+
+## Step 5: Lock Decisions
+
+Store each answer in brain.db with domain tag:
+
+Use the `brain_decisions` MCP tool with: `{ "action": "add", "question": "[question]", "decision": "[answer]", "reasoning": "User-provided via discussion", "phase": "discuss", "tags": "[TYPE],[domain]" }`
 
 These decisions are:
 - Injected into all downstream agent contexts
 - Never asked again (even across sessions)
 - Visible via `/sf-brain decisions`
 
-## Step 5: Report
+## Step 6: Report
 
 ```
-Resolved [N] ambiguities:
-  WHERE: [answer summary]
-  HOW: [answer summary]
-  RISK: [confirmed]
+Resolved [N] ambiguities (domains: [ui, auth]):
+  HOW (auth): JWT stateless tokens
+  HOW (ui): Compact layout, modal dialogs
+  WHERE: /app/auth/login page
+  RISK: Development only — confirmed
 
 Ready for planning. Run /sf-do to continue.
 ```
 
-## Assumptions Mode (when `--assume` flag is set)
+## Step 7: Chain Mode (when `--chain` flag is set)
 
-Instead of asking questions, auto-resolve ambiguities using codebase patterns:
+After all decisions locked:
+1. Auto-run `/sf-plan` with the task description + locked decisions
+2. After planning completes, auto-run `/sf-check-plan`
+3. If check passes, ask: "Plan ready. Execute now? [y/n]"
+4. If yes, auto-run `/sf-do`
 
-1. For each detected ambiguity, query brain.db for matching patterns:
-   - **WHERE**: Search nodes table for files matching task keywords
-   - **HOW**: Reuse past HOW decisions or domain learnings
-   - **WHAT**: Infer from task description
-   - **RISK**: Auto-confirm if `.env.local` or `.env.development` exists
-   - **SCOPE**: Default to "tackle all at once" for medium complexity
+## Assumptions Mode (when `--assume` flag is set)
+
+Auto-resolve ambiguities using codebase patterns:
+1. **WHERE**: Search brain.db nodes for files matching task keywords
+2. **HOW**: Reuse past HOW decisions from same domain, or domain learnings
+3. **WHAT**: Infer from task description
+4. **RISK**: Auto-confirm if `.env.local` or `.env.development` exists
+5. **SCOPE**: Default to "tackle all at once"
 
-2. Each auto-resolution has a confidence score (0-1):
-   - Confidence >= 0.5: Accept and lock as decision
-   - Confidence < 0.5: Fall back to asking the user
+Each resolution has a confidence score (0-1):
+- >= 0.5: Accept and lock
+- < 0.5: Fall back to asking
 
-3. Present assumptions to user before proceeding:
+Present assumptions:
 ```
 Assuming (based on codebase patterns):
-  WHERE: src/auth/login.ts, src/auth/session.ts (confidence: 0.8)
-  HOW: Follow existing pattern: jwt-auth (confidence: 0.7)
-  RISK: Confirmed — development environment detected (confidence: 0.7)
+  HOW (auth): JWT — reusing previous decision (confidence: 0.8)
+  WHERE: src/auth/login.ts — matched keyword "login" (confidence: 0.7)
+  RISK: Development env detected (confidence: 0.7)
 
-Say 'no' to override any of these, or press Enter to continue.
+Say 'no' to override, or Enter to continue.
 ```
 
-4. Lock accepted assumptions as decisions in brain.db.
-
 </process>
 
 <context>

package/commands/sf/do.md

@@ -33,6 +33,8 @@ Extract flags from `$ARGUMENTS` before processing. Flags start with `--` and are
 - `--no-plan` — Skip discuss (Step 3) and plan (Step 4), go straight to execute
 - `--cheap` — Force ALL agents to use haiku (fastest, cheapest, ~80% cost reduction)
 - `--quality` — Force builder/architect to sonnet, architect to opus for complex tasks
+- `--batch` — Batch all discussion questions into 1-2 AskUserQuestion calls
+- `--chain` — After each step, auto-run the next (discuss → plan → check → execute)
 
 **Parse procedure:**
 1. Extract all `--flag` tokens from the input
@@ -116,7 +118,7 @@ Pipeline: scout → architect → builder → critic (acceleration: partial, 35%
 
 ## STEP 2: CONTEXT GATHERING (0 tokens)
 
-**FIX #5: Git diff awareness** — Run `git diff --name-only HEAD` to see what files changed since last commit. Pass this list to Scout so it focuses on recent changes instead of searching blindly.
+**Git diff awareness** — Run `git diff --name-only HEAD` to see what files changed since last commit. Pass this list to Scout so it focuses on recent changes instead of searching blindly.
 
 If `.shipfast/brain.db` does not exist, tell user to run `shipfast init` first.
 
@@ -216,40 +218,53 @@ Launch ONE Builder agent with ALL tasks batched and `model: models.builder` from
 ### Complex workflow (per-task agents, fresh context each):
 
 **Check brain.db first** — if `/sf-plan` was run, tasks already exist:
-```bash
-sqlite3 -json .shipfast/brain.db "SELECT id, description, plan_text FROM tasks WHERE status = 'pending' ORDER BY created_at;" 2>/dev/null
-```
+
+Use the `brain_tasks` MCP tool with: `{ "action": "list", "status": "pending" }`
 
 If tasks found in brain.db, execute them. If not, run inline planning first.
 
 **Per-task execution (fresh context per task):**
+
+**REQUIRED — output progress for EVERY task (do NOT batch or skip):**
+
+Before each task:
+```
+[N/M] Building: [task description]...
+```
+After each task:
+```
+[N/M] ✓ [task description] (commit: [sha])
+```
+Or on failure:
+```
+[N/M] ✗ [task description] (error: [first 80 chars])
+```
+If you did not output these lines, this is a process failure.
+
 For each pending task in brain.db:
 1. Launch a SEPARATE sf-builder agent with ONLY that task + brain context + `model: models.builder` from Step 1.5. If `--tdd` flag is set, prepend `MODE: TDD (red→green→refactor). Write failing test FIRST.` to the task context.
 2. Builder gets fresh context — no accumulated garbage from previous tasks
 3. Builder executes: read → grep consumers → implement → build → verify → commit
 4. After Builder completes, update task status and record model outcome:
-   ```bash
-   sqlite3 .shipfast/brain.db "UPDATE tasks SET status='passed', commit_sha='[sha]' WHERE id='[id]';"
-   sqlite3 .shipfast/brain.db "INSERT INTO model_performance (agent, model, domain, task_id, outcome) VALUES ('builder', '[model used]', '[domain]', '[id]', 'success');"
-   ```
+
+   Use the `brain_tasks` MCP tool with: `{ "action": "update", "id": "[id]", "status": "passed", "commit_sha": "[sha]" }`
+
+   Use the `brain_model_outcome` MCP tool with: `{ "agent": "builder", "model": "[model used]", "domain": "[domain]", "task_id": "[id]", "outcome": "success" }`
+
 5. If Builder fails after 3 attempts:
-   ```bash
-   sqlite3 .shipfast/brain.db "UPDATE tasks SET status='failed', error='[error]' WHERE id='[id]';"
-   sqlite3 .shipfast/brain.db "INSERT INTO model_performance (agent, model, domain, task_id, outcome) VALUES ('builder', '[model used]', '[domain]', '[id]', 'failure');"
-   ```
+
+   Use the `brain_tasks` MCP tool with: `{ "action": "update", "id": "[id]", "status": "failed", "error": "[error]" }`
+
+   Use the `brain_model_outcome` MCP tool with: `{ "agent": "builder", "model": "[model used]", "domain": "[domain]", "task_id": "[id]", "outcome": "failure" }`
 6. Continue to next task regardless
 
-**Wave grouping:**
-- Independent tasks (no `depends`) → same wave → launch Builder agents in parallel
+**Wave grouping + parallel execution:**
+- Independent tasks (no `depends`) → same wave
 - Dependent tasks → later wave → wait for dependencies to complete
 - Tasks touching same files → sequential (never parallel)
 
-**After all tasks:**
-- Launch Critic agent (fresh context) with `model: models.critic` to review ALL changes: `git diff HEAD~N`
-- Launch Scribe agent (fresh context) with `model: models.scribe` to record decisions + learnings to brain.db
-- Save session state for `/sf-resume`
-
-**After execution, run `/sf-verify` for thorough verification.**
+**Parallel execution within waves:**
+If a wave has 2+ tasks, launch ALL Builder agents in that wave simultaneously using multiple Agent tool calls in a single response. Wait for all to complete before starting the next wave. This is safe because wave tasks are independent by definition.
 
 ### Builder behavior:
 - Follows deviation tiers: auto-fix bugs (T1-3), STOP for architecture changes (T4)
@@ -258,71 +273,106 @@ For each pending task in brain.db:
 - Stub detection before commit: scan for TODO/FIXME/placeholder
 - Commit hygiene: stage specific files, never `git add .`
 
-### If Critic finds CRITICAL issues:
-Send the issue back to Builder for fix (1 additional agent call, not a full re-run).
-
 ---
 
-## STEP 7: VERIFY (0-3K tokens)
+## STEP 7: MANDATORY POST-EXECUTION VERIFICATION
 
-**Skip if**: trivial tasks with passing build, UNLESS `--verify` flag is set
-**Force if**: `--verify` flag is set, regardless of complexity
+⚠️ **STOP-GATE: Do NOT output the final report or say "Done" until ALL checks below are complete. If you skip verification, the task is FAILED regardless of whether the code works. This is not optional.**
 
-Run goal-backward verification:
-1. Extract done-criteria from the original request + plan
-2. Check each criterion:
-   - File exists? → filesystem check
-   - Symbol exists? → grep check
-   - Build passes? → run build command
-   - No stubs? → scan changed files for TODO/FIXME/placeholder
-   - Behavior works? → mark as "manual verification needed"
-3. Score: N/M criteria met
-   - 100% → PASS
-   - 80%+ → PASS_WITH_WARNINGS (list gaps)
-   - Below 80% → FAIL (list what's missing)
+You MUST complete **ALL** of the following in order. Check each off as you go.
 
-Store verification results in brain.db.
+### 7A. Launch Critic agent (REQUIRED for medium/complex)
 
-### Auto-Fix on Failure
-If verification returns FAIL:
-1. Generate targeted fix tasks from each failure (~200 tokens each, not a fresh agent)
-2. Send fix tasks to Builder for one retry attempt
-3. Re-verify after fixes
-4. If still failing, report as DEFERRED — do not loop further
-
-### TDD Verification (when --tdd flag is set)
-After all tasks complete, verify git log contains the correct commit sequence:
-1. `test(...)` commit (RED phase) — must exist
-2. `feat(...)` commit after it (GREEN phase) — must exist
-3. Optional `refactor(...)` commit
-If sequence is violated, flag as TDD VIOLATION in the report.
-
-### Requirement Verification (when project has REQ-IDs)
-If brain.db has requirements for this phase:
-1. Check each v1 requirement mapped to this phase
-2. Mark as done/pending based on verification results
-3. Report coverage: "Requirements: N/M covered"
+Launch sf-critic agent with `model: models.critic` and the full diff:
+```bash
+git diff HEAD~[N commits]
+```
+Wait for Critic to return its verdict. If Critic finds CRITICAL issues → send to Builder for fix (1 additional agent call, not a full re-run).
 
----
+Report: `Critic: [PASS/PASS_WITH_WARNINGS/FAIL] — [N] findings`
 
-## STEP 8: LEARN
+### 7B. Build verification (REQUIRED)
 
-**FIX #9/#10: Explicitly record decisions and learnings using these exact commands:**
+Run the project's build/typecheck command:
+```bash
+npm run build  # or tsc --noEmit / cargo check
+```
+Report: `Build: [PASS/FAIL]`
 
-If you made any architectural decisions during this task, record each one:
+### 7C. Consumer integrity check (REQUIRED)
+
+For every function/type/export that was modified or removed across all tasks:
 ```bash
-sqlite3 .shipfast/brain.db "INSERT INTO decisions (question, decision, reasoning, phase) VALUES ('[what was decided]', '[the choice]', '[why]', '[current task]');"
+grep -r "removed_symbol" --include="*.ts" --include="*.tsx" --include="*.js" .
 ```
+Any remaining consumers = CRITICAL failure. Report: `Consumers: [CLEAN/N broken]`
 
-If you encountered and fixed any errors, record the pattern:
+### 7D. Stub scan (REQUIRED)
+
+Scan all changed files for incomplete work:
 ```bash
-sqlite3 .shipfast/brain.db "INSERT INTO learnings (pattern, problem, solution, domain, source, confidence) VALUES ('[short pattern name]', '[what went wrong]', '[what fixed it]', '[domain]', 'auto', 0.5);"
+git diff HEAD~[N] --name-only
 ```
+Then grep each for: TODO, FIXME, HACK, placeholder, console.log, debugger
+
+Report: `Stubs: [CLEAN/N found]`
+
+### 7E. Branch audit (REQUIRED when on non-default branch)
 
-If any improvement ideas, future features, or tech debt were surfaced during this task (including OUT_OF_SCOPE items), record them as seeds:
 ```bash
-sqlite3 .shipfast/brain.db "INSERT INTO seeds (idea, source_task, domain, priority) VALUES ('[idea]', '[current task]', '[domain]', 'someday');"
+CURRENT=$(git branch --show-current)
 ```
+Use the `brain_config` MCP tool with: `{ "action": "get", "key": "default_branch" }` — fall back to `"main"`.
+
+If `$CURRENT` ≠ `$DEFAULT`:
+- `git diff $DEFAULT...$CURRENT --diff-filter=D --name-only` → deleted files
+- For removed exports, check consumers via brain.db
+- Report: `Branch audit: [N] migrated | [N] missing | [N] safe`
+
+### 7F. TDD check (when --tdd flag is set)
+
+Verify `test(...)` commits come before `feat(...)` commits. Report: `TDD: [VALID/VIOLATION]`
+
+### 7G. Launch Scribe agent (REQUIRED for complex)
+
+Launch sf-scribe agent with `model: models.scribe` to record decisions + learnings to brain.db.
+
+### 7H. Score results
+
+Combine all checks:
+- All pass → **PASS**
+- Minor issues → **PASS_WITH_WARNINGS** (list them)
+- Critical issues → **FAIL** (list them, attempt auto-fix)
+
+### Auto-Fix on Failure
+If FAIL:
+1. Generate targeted fix tasks (~200 tokens each)
+2. Send to Builder for one retry
+3. Re-verify
+4. If still failing → DEFERRED
+
+Store verification results:
+Use the `brain_context` MCP tool with: `{ "action": "set", "scope": "session", "key": "verification", "value": "[JSON results]" }`
+
+Only AFTER 7A-7H are complete, proceed to STEP 8.
+
+---
+
+## STEP 8: LEARN
+
+**Explicitly record decisions and learnings using these exact commands:**
+
+If you made any architectural decisions during this task, record each one:
+
+Use the `brain_decisions` MCP tool with: `{ "action": "add", "question": "[what was decided]", "decision": "[the choice]", "reasoning": "[why]", "phase": "[current task]" }`
+
+If you encountered and fixed any errors, record the pattern:
+
+Use the `brain_learnings` MCP tool with: `{ "action": "add", "pattern": "[short pattern name]", "problem": "[what went wrong]", "solution": "[what fixed it]", "domain": "[domain]", "source": "auto", "confidence": 0.5 }`
+
+If any improvement ideas, future features, or tech debt were surfaced during this task (including OUT_OF_SCOPE items), record them as seeds:
+
+Use the `brain_seeds` MCP tool with: `{ "action": "add", "idea": "[idea]", "source_task": "[current task]", "domain": "[domain]", "priority": "someday" }`
 
 **These are not optional.** If decisions were made, errors were fixed, or ideas were surfaced, you MUST record them. This is how ShipFast gets smarter over time.
 
@@ -330,7 +380,18 @@ sqlite3 .shipfast/brain.db "INSERT INTO seeds (idea, source_task, domain, priori
 
 ## STEP 9: REPORT
 
-**Trivial tasks** (progressive disclosure — minimal output):
+**Before reporting, confirm all post-execution steps completed (complex tasks):**
+- [ ] Progress lines shown [N/M] for every task
+- [ ] Critic reviewed — verdict: ___
+- [ ] Build: ___
+- [ ] Consumer integrity: ___
+- [ ] Stubs: ___
+- [ ] Branch audit (if non-default): ___
+- [ ] Scribe recorded decisions/learnings
+
+**If any checkbox is unchecked, go back and complete it now. Do NOT report with incomplete verification.**
+
+**Trivial tasks**:
 ```
 Done: [one sentence summary]
 ```
@@ -338,15 +399,22 @@ Done: [one sentence summary]
 **Medium tasks**:
 ```
 Done: [summary]
-Commits: [N] | Verification: [PASS/WARN/FAIL]
+Commits: [N] | Build: [PASS/FAIL] | Critic: [verdict] | Consumers: [clean/N broken]
 ```
 
 **Complex tasks** (full dashboard):
 ```
 Done: [summary]
-Commits: [N] | Tasks: [completed]/[total] | Verification: [PASS/WARN/FAIL]
-Tokens: ~[estimate] | Time: [duration]
-Deferred: [list of issues that need manual attention, if any]
+Commits: [N] | Tasks: [completed]/[total]
+
+Verification:
+  Critic:    [PASS/WARNINGS/FAIL] — [N findings]
+  Build:     [PASS/FAIL]
+  Consumers: [CLEAN/N broken]
+  Stubs:     [CLEAN/N found]
+  Branch:    [N migrated, N missing, N safe] (or N/A if default branch)
+
+Deferred: [issues needing manual attention, if any]
 ```
 
 **If session state was saved** (context getting low):

package/commands/sf/help.md

@@ -37,18 +37,23 @@ SHIPPING
 SESSION
   /sf-status               Brain stats, tasks, checkpoints, version.
   /sf-resume               Resume from previous session.
-  /sf-undo [task-id]       Rollback a completed task.
+  /sf-undo [task-id]       Rollback a specific task by ID.
+  /sf-rollback [last|all|N] Rollback last task, last N, or entire session.
 
 KNOWLEDGE
   /sf-brain <query>        Query knowledge graph: files, decisions, learnings, hot files.
   /sf-learn <pattern>      Teach a reusable pattern.
   /sf-map                  Generate codebase report from brain.db.
+  /sf-cost                 Token usage breakdown by agent, domain, model.
+  /sf-diff                 Smart diff viewer — changes grouped by task.
 
 PARALLEL WORK
-  /sf-workstream list      Show all workstreams.
-  /sf-workstream create    Create namespaced workstream with branch.
-  /sf-workstream switch    Switch active workstream.
-  /sf-workstream complete  Complete and merge workstream.
+  /sf-worktree list        Show all worktrees.
+  /sf-worktree create      Create worktree — suggests branch name, supports multi-repo.
+  /sf-worktree switch      Show path to worktree (cd into it).
+  /sf-worktree status      Show uncommitted changes, commits, tasks for a worktree.
+  /sf-worktree check       Migration audit: migrated, missing, safe, modified, added.
+  /sf-worktree complete    Run audit, merge into default branch, remove worktree.
 
 CONFIG
   /sf-config               View or set model tiers and preferences.

package/commands/sf/map.md

@@ -15,44 +15,36 @@ Unlike GSD's 7 markdown mapper agents, this queries the existing SQLite brain di
 Run these queries and format the output. Do NOT modify the queries.
 
 ## File structure
-```bash
-sqlite3 .shipfast/brain.db "SELECT file_path FROM nodes WHERE kind = 'file' ORDER BY file_path;" 2>/dev/null | head -50
-```
+
+Use the `brain_search` MCP tool with: `{ "query": "kind:file", "limit": 50 }` — list all file nodes ordered by path.
 
 ## Symbol counts by kind
-```bash
-sqlite3 .shipfast/brain.db "SELECT kind, COUNT(*) as count FROM nodes GROUP BY kind ORDER BY count DESC;" 2>/dev/null
-```
+
+Use the `brain_search` MCP tool with: `{ "query": "group_by:kind" }` — get node counts grouped by kind.
 
 ## Top functions (most connected)
-```bash
-sqlite3 .shipfast/brain.db "SELECT n.name, n.file_path, n.signature, COUNT(e.target) as connections FROM nodes n LEFT JOIN edges e ON n.id = e.source WHERE n.kind = 'function' GROUP BY n.id ORDER BY connections DESC LIMIT 15;" 2>/dev/null
-```
+
+Use the `brain_search` MCP tool with: `{ "query": "kind:function order_by:connections", "limit": 15 }` — get functions with their connection counts.
 
 ## Hot files (most changed)
-```bash
-sqlite3 .shipfast/brain.db "SELECT file_path, change_count FROM hot_files ORDER BY change_count DESC LIMIT 15;" 2>/dev/null
-```
+
+Use the `brain_hot_files` MCP tool with: `{ "limit": 15 }` — returns files ordered by change_count descending.
 
 ## Import graph (top connections)
-```bash
-sqlite3 .shipfast/brain.db "SELECT REPLACE(source,'file:','') as from_file, REPLACE(target,'file:','') as to_file, kind FROM edges WHERE kind = 'imports' LIMIT 20;" 2>/dev/null
-```
+
+Use the `brain_graph_cochanges` MCP tool with: `{ "kind": "imports", "limit": 20 }` — get top import edges between files.
 
 ## Co-change clusters
-```bash
-sqlite3 .shipfast/brain.db "SELECT REPLACE(source,'file:','') as file_a, REPLACE(target,'file:','') as file_b, weight FROM edges WHERE kind = 'co_changes' AND weight > 0.3 ORDER BY weight DESC LIMIT 15;" 2>/dev/null
-```
+
+Use the `brain_graph_cochanges` MCP tool with: `{ "min_weight": 0.3, "limit": 15 }` — get co-change pairs with weight > 0.3 ordered by weight descending.
 
 ## Decisions made
-```bash
-sqlite3 .shipfast/brain.db "SELECT question, decision, phase FROM decisions ORDER BY created_at DESC LIMIT 10;" 2>/dev/null
-```
+
+Use the `brain_decisions` MCP tool with: `{ "action": "list", "limit": 10 }` — returns decisions ordered by created_at descending.
 
 ## Learnings
-```bash
-sqlite3 .shipfast/brain.db "SELECT pattern, problem, solution, confidence FROM learnings WHERE confidence > 0.3 ORDER BY confidence DESC LIMIT 10;" 2>/dev/null
-```
+
+Use the `brain_learnings` MCP tool with: `{ "action": "list", "min_confidence": 0.3, "limit": 10 }` — returns learnings with confidence > 0.3 ordered by confidence descending.
 
 Format as: