@shipfast-ai/shipfast 0.6.1 → 1.0.0

package/commands/sf/check-plan.md

@@ -0,0 +1,76 @@
+---
+name: sf:check-plan
+description: "Verify planned tasks before execution. Checks scope, consumers, dependencies, must-haves coverage."
+allowed-tools:
+  - Read
+  - Bash
+  - Glob
+  - Grep
+---
+
+<objective>
+Plan-checker: verifies tasks in brain.db are safe to execute before /sf-do runs them.
+Catches scope creep, missing consumers, broken dependencies, and uncovered must-haves.
+</objective>
+
+<process>
+
+## Step 1: Load tasks and must-haves
+
+```bash
+sqlite3 -json .shipfast/brain.db "SELECT id, description, plan_text FROM tasks WHERE status = 'pending' ORDER BY created_at;" 2>/dev/null
+sqlite3 -json .shipfast/brain.db "SELECT value FROM context WHERE key LIKE 'must_haves:%' LIMIT 1;" 2>/dev/null
+```
+
+## Step 2: Check each task
+
+For each task, verify:
+
+**Files exist**: every file path mentioned in plan_text exists on disk (or is marked as "create")
+**Consumers checked**: if task removes/modifies exports, grep confirms consumer list is complete
+**Dependencies**: if task depends on another task, that task is also pending (not missing)
+**Scope**: no banned words (v1, simplified, placeholder, hardcoded for now)
+**Verify command**: task has a concrete verify command (not vague)
+
+## Step 3: Check must-haves coverage
+
+Every truth in must-haves must be addressed by at least one task.
+Every artifact must have a task that creates/modifies it.
+Flag orphaned must-haves (not covered by any task).
+
+## Step 4: STRIDE threat check (Feature #1)
+
+For tasks that create new endpoints, auth flows, or data access:
+
+| Threat | Check |
+|---|---|
+| **S**poofing | Does the task include auth/identity verification? |
+| **T**ampering | Is input validated before processing? |
+| **R**epudiation | Are actions logged/auditable? |
+| **I**nformation disclosure | Are errors sanitized (no stack traces to users)? |
+| **D**enial of service | Is there rate limiting or input size validation? |
+| **E**levation of privilege | Are permissions checked before sensitive operations? |
+
+For each applicable threat, output: `THREAT: [S/T/R/I/D/E] [component] — [mitigation needed]`
+
+## Step 5: Report
+
+```
+Plan Check: [PASS / ISSUES FOUND]
+
+Tasks: [N] pending
+Must-haves: [N]/[M] covered
+Threats: [N] flagged
+
+[If issues:]
+  ISSUE: Task [id] — [file not found / missing consumer / scope creep / etc.]
+  THREAT: [S/T/R/I/D/E] [component] — [what's needed]
+
+Fix plan with /sf-plan, then re-check with /sf-check-plan.
+```
+
+</process>
+
+<context>
+$ARGUMENTS
+</context>

package/commands/sf/do.md

@@ -123,31 +123,65 @@ Before execution:
 
 ## STEP 6: EXECUTE (2-30K tokens)
 
-### Trivial workflow (no agent spawn):
-Execute inline in this context. No separate Builder agent.
-- Read the relevant file
-- Make the change
-- Run build/test if applicable
-- Commit with conventional format
+**CRITICAL RULE FOR ALL WORKFLOWS:**
+Before removing, deleting, or modifying any function/type/selector/export/component:
+1. `grep -r "name" --include="*.ts" --include="*.tsx" .` to find ALL consumers
+2. If other files use it, update them or keep it
+3. NEVER remove without checking consumers first
+4. Run build/typecheck AFTER each task, BEFORE committing
+
+### Trivial workflow (fast-mode, ≤3 edits, no agent spawn):
+Execute inline. No planning, no Scout, no Architect, no Critic.
+1. Read the file(s) + grep for consumers of what you'll change
+2. Make the change (match existing patterns)
+3. Run build: `tsc --noEmit` / `npm run build` / `cargo check`
+4. If build fails, fix (up to 3 attempts)
+5. Commit with conventional format
+6. Done. No SUMMARY, no verification.
+**Redirect**: if work exceeds 3 file edits or needs research → upgrade to medium workflow.
 
 ### Medium workflow (1 Builder agent):
 Launch ONE Builder agent with ALL tasks batched:
-- Agent gets: base prompt (~1.5K) + brain context (~500) + all task descriptions
+- Agent gets: base prompt + brain context + all task descriptions
 - Agent executes tasks sequentially within its context
-- One agent call instead of one per task = massive token savings
+- One agent call instead of one per task = token savings
 - If Critic is not skipped, launch Critic after Builder completes
 
-### Complex workflow (wave-based):
-Group tasks into dependency waves:
-- Wave 1: all independent tasks (can run in parallel)
-- Wave 2: tasks that depend on Wave 1
-- etc.
-For each wave:
-- Launch Builder agent with wave tasks + shared brain context
-- If a task fails after 3 attempts: document as DEFERRED, continue next task
-- Save state to brain.db after each wave (enables resume)
-- Launch Critic after all waves complete
-- Launch Scribe to record decisions and prepare PR description
+### 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
+```
+
+If tasks found in brain.db, execute them. If not, run inline planning first.
+
+**Per-task execution (fresh context per task):**
+For each pending task in brain.db:
+1. Launch a SEPARATE sf-builder agent with ONLY that task + brain 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 in brain.db:
+   ```bash
+   sqlite3 .shipfast/brain.db "UPDATE tasks SET status='passed', commit_sha='[sha]' WHERE id='[id]';"
+   ```
+5. If Builder fails after 3 attempts:
+   ```bash
+   sqlite3 .shipfast/brain.db "UPDATE tasks SET status='failed', error='[error]' WHERE id='[id]';"
+   ```
+6. Continue to next task regardless
+
+**Wave grouping:**
+- Independent tasks (no `depends`) → same wave → launch Builder agents in parallel
+- Dependent tasks → later wave → wait for dependencies to complete
+- Tasks touching same files → sequential (never parallel)
+
+**After all tasks:**
+- Launch Critic agent (fresh context) to review ALL changes: `git diff HEAD~N`
+- Launch Scribe agent (fresh context) to record decisions + learnings to brain.db
+- Save session state for `/sf-resume`
+
+**After execution, run `/sf-verify` for thorough verification.**
 
 ### Builder behavior:
 - Follows deviation tiers: auto-fix bugs (T1-3), STOP for architecture changes (T4)

package/commands/sf/help.md

@@ -17,39 +17,47 @@ ShipFast — Autonomous Context-Engineered Development
 =====================================================
 
 CORE
-  /sf-do <task>         The one command. Describe what you want in natural language.
-                        Auto-detects complexity: trivial (3K tokens) → medium (15K) → complex (40K)
+  /sf-do <task>            Execute a task. Auto-detects complexity.
+                           Trivial: inline (~3K) | Medium: 1 agent (~15K) | Complex: per-task (~40K)
 
 PLANNING
-  /sf-discuss <task>    Detect ambiguity and ask targeted questions before planning.
-                        Stores answers as locked decisions in brain.db.
-  /sf-project <desc>    Decompose a large project into phases with REQ-ID tracing.
-                        Each phase runs through /sf-do independently.
+  /sf-discuss <task>       Detect ambiguity, ask questions, lock decisions.
+  /sf-plan <task>          Research (Scout) + Plan (Architect). Stores tasks in brain.db.
+  /sf-check-plan           Verify plan before execution: scope, consumers, STRIDE threats.
+  /sf-project <desc>       Decompose large project into phases with REQ-ID tracing.
+
+EXECUTION
+  /sf-do                   Execute tasks from brain.db. Per-task fresh context for complex.
+  /sf-verify               Verify: 3-level artifacts, data flow, stubs, build, consumers.
 
 SHIPPING
-  /sf-ship [branch]     Create branch, push, output PR link with auto-generated description.
+  /sf-ship [branch]        Create branch, push, output PR link.
+  /sf-milestone            Complete or start a milestone.
 
 SESSION
-  /sf-status            Show brain stats, tasks, checkpoints.
-  /sf-resume            Resume work from a previous session. Loads state from brain.db.
-  /sf-undo [task-id]    Rollback a completed task via git revert or stash.
+  /sf-status               Brain stats, tasks, checkpoints, version.
+  /sf-resume               Resume from previous session.
+  /sf-undo [task-id]       Rollback a completed task.
 
 KNOWLEDGE
-  /sf-brain <query>     Query the codebase knowledge graph directly.
-                        Examples: "files like auth", "decisions", "hot files", "stats"
-  /sf-learn <pattern>   Teach a reusable pattern. Persists across sessions.
-                        Example: /sf-learn tailwind-v4: Use @import not @tailwind
+  /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.
 
-CONFIG
-  /sf-config [key val]  View or set model tiers and preferences.
-  /sf-help              Show this help message.
+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.
 
-WORKFLOW
-  /sf-do runs a 9-step pipeline that adapts to task complexity:
+CONFIG
+  /sf-config               View or set model tiers and preferences.
+  /sf-help                 Show this help.
 
-  TRIVIAL (fix typo)     → Builder only, no planning, ~3K tokens
-  MEDIUM (add feature)   → Scout → Architect → Builder → Critic, ~15K tokens
-  COMPLEX (new system)   → Full pipeline + discussion + verification, ~40K tokens
+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 → /sf-discuss → /sf-plan → /sf-check-plan → /sf-do → /sf-verify → /sf-ship
 
   Steps: Analyze → Init Brain → Discuss → Plan → Checkpoint → Execute → Verify → Learn → Report
   Each step is skippable — the system only runs what's needed.

package/commands/sf/map.md

@@ -0,0 +1,84 @@
+---
+name: sf:map
+description: "Generate human-readable codebase report from brain.db. Shows architecture, structure, hot files, conventions."
+allowed-tools:
+  - Bash
+---
+
+<objective>
+Generate a readable codebase summary from brain.db data.
+Unlike GSD's 7 markdown mapper agents, this queries the existing SQLite brain directly — zero LLM tokens for data retrieval.
+</objective>
+
+<process>
+
+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
+```
+
+## 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
+```
+
+## 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
+```
+
+## 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
+```
+
+## 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
+```
+
+## 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
+```
+
+## Decisions made
+```bash
+sqlite3 .shipfast/brain.db "SELECT question, decision, phase FROM decisions ORDER BY created_at DESC LIMIT 10;" 2>/dev/null
+```
+
+## 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
+```
+
+Format as:
+
+```
+Codebase Map
+============
+
+Structure: [N] files | [N] functions | [N] types | [N] components
+
+Top Functions (most connected):
+  [name] in [file] — [connections] deps
+
+Hot Files (most changed):
+  [file] — [N] changes
+
+Co-Change Clusters (files that change together):
+  [file_a] ↔ [file_b] ([weight])
+
+Decisions: [N] recorded
+Learnings: [N] stored ([N] high confidence)
+```
+
+STOP after output. No analysis.
+
+</process>
+
+<context>
+$ARGUMENTS
+</context>

package/commands/sf/plan.md

@@ -0,0 +1,106 @@
+---
+name: sf:plan
+description: "Research and plan a phase. Scout gathers findings, Architect creates task list. Stores tasks in brain.db."
+argument-hint: "<describe what to build>"
+allowed-tools:
+  - Read
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+
+<objective>
+Dedicated planning command. Produces a precise task list stored in brain.db.
+Does NOT execute — that's /sf-do's job.
+
+Separation matters: planning uses different context than execution.
+Fresh context for each phase = no degradation.
+</objective>
+
+<process>
+
+## Step 1: Analyze
+
+Classify intent and complexity (same as /sf-do Step 1):
+- fix/feature/refactor/test/ship/perf/security/style/data/remove
+- trivial/medium/complex
+
+If trivial: skip planning. Tell user to run `/sf-do` directly.
+
+## Step 2: Scout (fresh agent)
+
+Launch sf-scout agent to research the task:
+- Provide: task description + brain.db context (decisions, learnings, hot files)
+- Scout returns: files, functions, consumers, conventions, risks, recommendation
+- Scout tags findings with confidence: [VERIFIED], [CITED], [ASSUMED]
+
+**Scout runs in its own agent = fresh context, no pollution.**
+
+Wait for Scout to complete before proceeding.
+
+## Step 3: Discuss (if complex or ambiguous)
+
+Check for ambiguity (rule-based, zero tokens):
+- WHERE: no file paths mentioned
+- WHAT: no behavior described
+- HOW: multiple approaches possible
+- RISK: touches auth/payment/data
+- SCOPE: >30 words with conjunctions
+
+If ambiguous: ask 2-5 targeted questions. Store answers as locked decisions in brain.db:
+```bash
+sqlite3 .shipfast/brain.db "INSERT INTO decisions (question, decision, reasoning, phase) VALUES ('[Q]', '[A]', '[why]', '[phase]');"
+```
+
+## Step 4: Architect (fresh agent)
+
+Launch sf-architect agent to create task list:
+- Provide: task description + Scout findings + locked decisions from brain.db
+- Architect returns: must-haves (truths/artifacts/links) + ordered task list
+
+**Architect runs in its own agent = fresh context, no pollution.**
+
+Architect's output must include for EACH task:
+- Exact file paths
+- Consumer list (who uses what's being changed)
+- Specific action instructions
+- Verify command
+- Measurable done criteria
+
+## Step 5: Store tasks in brain.db
+
+For each task from Architect, store in brain.db:
+```bash
+sqlite3 .shipfast/brain.db "INSERT INTO tasks (id, phase, description, plan_text, status) VALUES ('[id]', '[phase]', '[description]', '[full task details]', 'pending');"
+```
+
+Also store must-haves:
+```bash
+sqlite3 .shipfast/brain.db "INSERT OR REPLACE INTO context (id, scope, key, value, version, updated_at) VALUES ('phase:[name]:must_haves', 'phase', 'must_haves:[name]', '[JSON must-haves]', 1, strftime('%s', 'now'));"
+```
+
+## Step 6: Report
+
+```
+Plan ready: [N] tasks stored in brain.db
+
+Must-haves:
+  Truths: [list]
+  Artifacts: [list]
+  Key links: [list]
+
+Tasks:
+  1. [description] — [files] — [size]
+  2. [description] — [files] — [size]
+  ...
+
+Run /sf-do to execute. Tasks will run with fresh context per task.
+```
+
+</process>
+
+<context>
+$ARGUMENTS
+</context>

package/commands/sf/project.md

@@ -30,6 +30,22 @@ Read the user's project description. If brain.db exists, load:
 
 If the project description is ambiguous, run the ambiguity detection from /sf-discuss first.
 
+## Step 1.5: Parallel Domain Research (for new/complex projects)
+
+If the project involves unfamiliar technology or external integrations, launch **up to 4 Scout agents in parallel** to research:
+
+1. **Stack Scout** — What's the standard stack for this domain? Libraries, versions, frameworks.
+2. **Architecture Scout** — How are similar systems typically structured? Patterns, tiers, boundaries.
+3. **Pitfalls Scout** — What do projects like this commonly get wrong? Gotchas, anti-patterns.
+4. **Integration Scout** — What external services/APIs are needed? Auth, webhooks, SDKs.
+
+Each Scout runs in its own context. Findings are stored in brain.db:
+```bash
+sqlite3 .shipfast/brain.db "INSERT OR REPLACE INTO context (id, scope, key, value, version, updated_at) VALUES ('project:research:[topic]', 'project', 'research:[topic]', '[findings JSON]', 1, strftime('%s', 'now'));"
+```
+
+Skip this step for simple projects or projects where brain.db already has relevant decisions.
+
 ### Multi-Repo Detection
 Check if the workspace contains multiple git repositories (submodules, monorepo packages):
 ```bash

package/commands/sf/verify.md

@@ -0,0 +1,140 @@
+---
+name: sf:verify
+description: "Verify completed work against must-haves. Checks artifacts, data flow, stubs, build, consumers."
+allowed-tools:
+  - Read
+  - Bash
+  - Glob
+  - Grep
+  - AskUserQuestion
+---
+
+<objective>
+Dedicated verification command. Runs AFTER /sf-do completes.
+Checks the codebase delivers what was planned — not just "tests pass".
+
+Separation matters: verification needs fresh context to see the code objectively,
+without the biases accumulated during execution.
+</objective>
+
+<process>
+
+## Step 1: Load must-haves from brain.db
+
+```bash
+sqlite3 -json .shipfast/brain.db "SELECT value FROM context WHERE key LIKE 'must_haves:%' ORDER BY updated_at DESC LIMIT 1;" 2>/dev/null
+```
+
+If no must-haves stored, extract from the task descriptions:
+```bash
+sqlite3 -json .shipfast/brain.db "SELECT description FROM tasks WHERE status = 'passed' ORDER BY created_at;" 2>/dev/null
+```
+
+## Step 2: Check observable truths
+
+For each truth in must-haves, verify:
+- Does the code actually implement this?
+- Grep for the function/component/route that delivers it
+- Is it wired (imported and used), not just existing?
+
+Score: VERIFIED / FAILED / NEEDS_HUMAN
+
+## Step 3: 3-Level artifact validation
+
+For each artifact in must-haves:
+
+**Level 1 — Exists**: `[ -f path ] && echo OK || echo MISSING`
+**Level 2 — Substantive**: File has >3 non-comment lines (not empty/stub)
+**Level 3 — Wired**: `grep -r "basename" --include="*.ts" .` shows imports from other files
+
+Score per artifact: L1/L2/L3 or MISSING
+
+## Step 4: Data flow check
+
+For new components/APIs, check they receive real data:
+- Not hardcoded empty arrays: `grep "data: \[\]" [file]`
+- Not returning null: `grep "return null" [file]`
+- Not empty handlers: `grep "() => {}" [file]`
+- Fetch calls have response handling
+
+## Step 5: Stub detection (deep)
+
+Scan all files changed in this session:
+```bash
+git diff --name-only HEAD~[N commits]
+```
+
+Check each for:
+- TODO, FIXME, HACK, "not implemented", "placeholder"
+- Empty click/submit handlers
+- console.log debug statements
+- debugger statements
+- Commented-out code blocks
+
+## Step 6: Build verification
+
+```bash
+npm run build 2>&1 | tail -5
+# or: tsc --noEmit
+# or: cargo check
+```
+
+## Step 7: Consumer integrity
+
+For every function/type/export that was modified or removed:
+```bash
+grep -r "removed_function_name" --include="*.ts" --include="*.tsx" .
+```
+Any remaining consumers = CRITICAL failure.
+
+## Step 8: Score and report
+
+```
+Verification Results
+====================
+
+Truths: [N]/[M] verified
+Artifacts: [N]/[M] at Level 3 (wired)
+Data flow: [PASS/ISSUES]
+Stubs: [N] found
+Build: [PASS/FAIL]
+Consumers: [CLEAN/BROKEN]
+
+Verdict: PASS | PASS_WITH_WARNINGS | FAIL
+
+[If FAIL:]
+Failed items:
+  - [truth/artifact]: [what's wrong]
+  - [truth/artifact]: [what's wrong]
+
+Fix with: /sf-do [fix description]
+```
+
+## Step 9: Store results
+
+```bash
+sqlite3 .shipfast/brain.db "INSERT OR REPLACE INTO context (id, scope, key, value, version, updated_at) VALUES ('verify:latest', 'session', 'verification', '[JSON results]', 1, strftime('%s', 'now'));"
+```
+
+## Step 10: Interactive UAT (if complex)
+
+For complex features, offer manual testing:
+```
+Manual checks (answer pass/issue/skip):
+
+Test 1: [what to test]
+  Expected: [behavior]
+  Result?
+
+Test 2: [what to test]
+  Expected: [behavior]
+  Result?
+```
+
+For each issue reported, generate a fix task and store in brain.db.
+
+</process>
+
+<context>
+$ARGUMENTS
+</context>

package/commands/sf/workstream.md

@@ -0,0 +1,51 @@
+---
+name: sf:workstream
+description: "Manage parallel workstreams — create, list, switch, complete."
+argument-hint: "list | create <name> | switch <name> | complete <name>"
+allowed-tools:
+  - Bash
+  - AskUserQuestion
+---
+
+<objective>
+Workstreams let you work on multiple features in parallel, each with its own branch and task tracking.
+Each workstream gets a namespaced set of tasks in brain.db.
+</objective>
+
+<process>
+
+## Parse subcommand from $ARGUMENTS
+
+### list
+```bash
+sqlite3 -json .shipfast/brain.db "SELECT key, value FROM context WHERE scope = 'workstream' ORDER BY updated_at DESC;" 2>/dev/null
+git branch --list "sf/*" 2>/dev/null
+```
+Show all workstreams with status (active/complete) and branch name.
+
+### create <name>
+1. Create git branch: `git checkout -b sf/[name]`
+2. Store in brain.db:
+```bash
+sqlite3 .shipfast/brain.db "INSERT OR REPLACE INTO context (id, scope, key, value, version, updated_at) VALUES ('workstream:[name]', 'workstream', '[name]', '{\"status\":\"active\",\"branch\":\"sf/[name]\",\"created\":\"[timestamp]\"}', 1, strftime('%s', 'now'));"
+```
+3. Report: `Workstream [name] created on branch sf/[name]`
+
+### switch <name>
+1. `git checkout sf/[name]`
+2. Report: `Switched to workstream [name]`
+
+### complete <name>
+1. Ask: "Merge sf/[name] into current branch? [y/n]"
+2. If yes: `git merge sf/[name]` then `git branch -d sf/[name]`
+3. Update brain.db:
+```bash
+sqlite3 .shipfast/brain.db "UPDATE context SET value = replace(value, 'active', 'complete') WHERE id = 'workstream:[name]';"
+```
+4. Report: `Workstream [name] completed and merged.`
+
+</process>
+
+<context>
+$ARGUMENTS
+</context>