SMITH — Forge Your Workflow
 
FEATURE DEVELOPMENT
  /smith-new              Start a new feature end-to-end
  /smith-specify          Create or update a feature spec
  /smith-clarify          Ask clarification questions on a spec
  /smith-plan             Generate implementation plan from spec
  /smith-tasks            Break plan into ordered tasks
  /smith-analyze          Check consistency across spec/plan/tasks
  /smith-implement        Execute all tasks sequentially
  /smith-build            Autonomous build (tasks → implement → test → PR → merge)
  /smith-checklist        Generate quality checklist for spec/plan
  /smith-bugfix           Autonomous bugfix (branch → fix → test → PR → merge)
  /smith-debug            Diagnostic investigation (gather evidence → report → optional bugfix)
 
VAULT
  /smith-vault            Dashboard — recent sessions, agents, queue status
  /smith-vault sessions   List session logs
  /smith-vault agents     List sub-agent types and history
  /smith-vault queue      Show pending queue items
  /smith-vault projects   List all registered projects
  /smith-vault status     Vault health and routing metrics
 
QUEUE
  /smith-queue add        Add a task to the queue
  /smith-queue list       Show pending tasks by priority
  /smith-queue process    Pick and process a task (interactive, --next, --all, or <file>)
  /smith-queue batch      Alias for process --all
  /smith-queue status     Show tasks grouped by status
  /smith-queue schedule   Schedule a task for a specific time
  /smith-queue history    View completed and failed tasks
  /smith-queue edit       Modify a queued task
  /smith-queue promote    Change task from autonomous to interactive
  /smith-queue demote     Change task from interactive to autonomous
  /smith-queue requeue    Reset a failed task to pending
  /smith-queue scheduler  Manage the automated 2am batch scheduler
 
BANK
  /smith-bank               Deposit an idea from the current conversation
  /smith-bank list           Show all banked ideas (--priority, --system filters)
  /smith-bank process <id>   Withdraw idea and start /smith-new workflow
  /smith-bank edit <id>      Edit a banked idea's details
  /smith-bank remove <id>    Archive a banked idea
  /smith-bank prioritize <id> --priority <level>  Change priority
 
LEARNING
  /smith-reflect          Analyze completed workflow and extract lessons to the Ledger
  /smith-reflect --last N Analyze last N workflows in batch
  /smith-reflect --failure Learn from recent failures specifically
  /smith-ledger           Browse the Ledger dashboard
  /smith-ledger list      List all learned patterns by category
  /smith-ledger search    Search across all Ledger entries
  /smith-ledger prune     Remove stale low-confidence entries
  /smith-ledger reset     Archive and restart the Ledger
  /smith-ledger reconcile           Trigger Ledger self-maintenance (merge, prune, budget enforce)
  /smith-ledger reconcile --dry-run Preview reconciliation without modifying files
  /smith-ledger reconcile --force   Bypass lock and threshold checks
  /smith-ledger reconcile --status  Check if reconciliation is needed
 
REPORTS
  /smith-report           Generate client-facing project report
 
PROJECT
  /smith                  Bootstrap a new project with Smith workflow
  /smith-constitution     Create or update project constitution
  /smith-taskstoissues    Convert tasks.md to GitHub Issues
  /smith-migrate-specs    Migrate flat specs into system-based hierarchy
  /smith-migrate-system-paths  Add `paths:` frontmatter to existing system specs
 
SESSION
  /smith-finish           Commit, push, merge, update specs, clean workspace
  /smith-sync             Sweep & push team-shareable .smith/ artifacts to the default branch
 
HELP
  /smith-help             This overview
  /smith-help <command>   Detailed help for a specific command

/smith-new — New Feature Workflow
 
The primary entry point for building features. Combines conversational
requirements gathering, spec generation, planning, a mandatory questions
gate, and autonomous build into a single flow.
 
USAGE
  /smith-new <feature description>
  /smith-new                           (prompts for description interactively)
 
NATURAL LANGUAGE TRIGGERS
  "let's smith this"
  "start a smith workflow"
  "kick off a new feature for this"
  "let's build this"
 
PHASES
  1. Branch Safety    Check current branch, pull main if needed
  2. Requirements     Conversational gathering or parse $ARGUMENTS
  3. Spec & Branch    Auto-detect system, create branch, generate spec.md
  4. Plan             Generate plan.md, research.md, data-model.md
  5. Questions Gate   Generate questions.md — MANDATORY STOP for user answers
  6. Build            Launch /smith-build for autonomous execution
 
SYSTEM DETECTION
  Automatically determines primary_system and also_affects by analyzing
  the feature description against .specify/systems/system-*/spec.md.
  Feature spec is created at:
    .specify/systems/<primary-system>/features/<NNN-short-name>/
 
CHAINS INTO
  /smith-build (Phase 6 — autonomous from tasks through merged PR)
 
VAULT LOGGING
  Logs invocation, system detection, spec creation, questions generated,
  questions answered, and build handoff to the vault session log.

/smith-specify — Feature Specification
 
Create or update a feature specification from a natural language description.
 
USAGE
  /smith-specify <feature description>
 
BEHAVIOR
  1. Generate branch short-name (2-4 words)
  2. Find next feature number across branches and specs
  3. Auto-detect primary system from .specify/systems/
  4. Create feature branch and spec folder
  5. Write spec.md with frontmatter (primary_system, also_affects, branch, status)
  6. Generate quality checklist at <feature>/checklists/requirements.md
  7. Validate spec (up to 3 iterations)
 
NEXT STEPS
  /smith-clarify → /smith-plan

/smith-clarify — Spec Clarification
 
Identify underspecified areas in the current feature spec and resolve them
through up to 5 targeted questions.
 
USAGE
  /smith-clarify
 
BEHAVIOR
  Runs on the current feature branch. Scans the spec for ambiguities across
  10 taxonomy categories. Presents one question at a time with recommended
  answers. Updates the spec inline after each answer.
 
QUESTIONS FILE
  Stored at <feature-folder>/questions.md (inside the spec folder, not specs/questions/)
 
NEXT STEP
  /smith-plan

/smith-plan — Implementation Planning
 
Generate a technical implementation plan from the feature spec.
 
USAGE
  /smith-plan
 
ARTIFACTS PRODUCED
  plan.md          Architecture, file structure, tech decisions
  research.md      Resolved unknowns, dependency research
  data-model.md    Entity definitions and relationships
  contracts/       API specifications
  quickstart.md    Integration scenarios
 
NEXT STEPS
  /smith-tasks → /smith-analyze → /smith-implement

/smith-tasks — Task Generation
 
Break the implementation plan into ordered, executable tasks.
 
USAGE
  /smith-tasks
 
OUTPUT
  tasks.md with phases:
    Phase 1: Setup (project initialization)
    Phase 2: Foundational (blocking prerequisites)
    Phase 3+: User Stories in priority order
    Final: Polish & Cross-Cutting Concerns
 
NEXT STEPS
  /smith-analyze → /smith-implement

/smith-analyze — Consistency Analysis
 
Non-destructive cross-artifact analysis across spec.md, plan.md, and tasks.md.
 
USAGE
  /smith-analyze
 
CHECKS
  - Spec ↔ plan alignment
  - Plan ↔ tasks coverage
  - Constitution compliance
  - Duplicate or contradictory requirements
  - Missing test coverage
 
OUTPUT
  Analysis report with findings by severity (CRITICAL/HIGH/MEDIUM/LOW)
 
QUEUE INTEGRATION
  After analysis, offers: "Implement now or queue for later?"
  If queued, packages spec/plan/tasks into an autonomous queue entry.

/smith-implement — Task Execution
 
Execute all tasks defined in tasks.md sequentially.
 
USAGE
  /smith-implement
 
BEHAVIOR
  Reads tasks.md, executes each task in order, marks completed with [X],
  runs tests after each task. Logs per-task status to vault.

/smith-build — Autonomous Build Pipeline
 
Full build from tasks through merged PR. Runs without user interaction.
 
USAGE
  /smith-build                     (normal — on a feature branch with spec/plan)
  /smith-build                     (recovery — detects state and resumes)
 
PHASES
  0. Context Discovery    Load spec, plan, questions, tasks
  1. Task Generation      Generate tasks.md if missing
  2. Implementation       Execute tasks phase-by-phase in subagents
  3. Testing              Unit tests + Playwright E2E (if frontend changed)
  4. Spec Updates         Update system specs in .specify/systems/ and specs/
  5. Commit & PR          Stage, commit, push, create PR, squash-merge
  6. Service Rebuild      Docker rebuild affected services, health check
  7. Release Notes        Generate release.md, commit to main
 
RECOVERY
  Detects current state and resumes from the right phase:
    No tasks.md → Phase 1
    Tasks partially done → Phase 2
    All done, uncommitted → Phase 5
    PR exists → Phase 5.3
    PR merged → Phase 6

/smith-debug — Diagnostic Investigation
 
Read-only workflow that systematically gathers evidence, identifies root
causes, and produces a structured debug report. Does not modify code.
The report feeds into /smith-bugfix if a fix is needed.
 
USAGE
  /smith-debug <symptom description>
  /smith-debug                           (prompts for details interactively)
 
NATURAL LANGUAGE TRIGGERS
  "debug this", "help me debug...", "I'm getting this error...",
  "why is X failing", "something is broken", "can you investigate..."
 
PHASES
  1. Symptom Capture    Extract or ask for: error, trigger, conditions, frequency
  2. System Detection   Map symptom to .specify/systems/<system>/
  3. Automated Triage   Parallel sub-agents: infra-health, log-scan,
                        dependency-trace, spec-cross-reference
  4. Diagnosis          Synthesize findings, rank hypotheses by evidence
  5. Debug Report       Write to .specify/systems/<system>/debug/debug-YYYY-MM-DD-<slug>.md
  6. Decision Gate      User chooses: fix (/smith-bugfix), investigate deeper, or close
 
SUB-AGENTS (launched in parallel based on symptom type)
  infra-health         docker ps, health-check.sh, docker stats, port checks
  log-scan             docker logs for affected + upstream services
  dependency-trace     map request path, check each hop end-to-end
  spec-cross-ref       prior debug reports, recent git changes, GitHub issues
 
REPORT STORAGE
  .specify/systems/<primary-system>/debug/debug-YYYY-MM-DD-<slug>.md
 
CHAINS INTO
  /smith-bugfix (if user selects "Fix it" at the decision gate)

/smith-bugfix — Autonomous Bugfix
 
Streamlined alternative to /smith-new for bugs and small changes.
Fully autonomous from invocation to merged PR.
 
USAGE
  /smith-bugfix <bug description>
 
NATURAL LANGUAGE TRIGGERS
  "fix this", "bugfix this", "quick fix for...", "patch this", "just fix..."
 
PIPELINE
  checkout main → create fix/<slug> branch → cross-reference specs →
  implement → rebuild Docker → test → update specs & changelog →
  commit → PR → squash-merge → return to main

/smith-checklist — Quality Checklist
 
Generate a checklist that validates spec quality, clarity, and completeness.
Functions as "unit tests for requirements writing."
 
USAGE
  /smith-checklist
 
NOT FOR
  Verifying implementation or testing code — only validates the spec itself.

/smith-queue — Task Queue Management
 
Manage deferred work through a persistent task queue. Supports priority
ordering, dependency tracking, scheduled execution, and batch processing
with git worktree isolation.
 
ADD
  /smith-queue add "<description>"
  /smith-queue add "<description>" --priority high
  /smith-queue add "<description>" --depends-on <filename>
 
  Complexity flags (set during add or auto-detected):
    autonomous     Can run unattended (default for clear instructions)
    interactive    Needs user input, won't run in batch
    review         Runs unattended but stages for approval
 
LIST & STATUS
  /smith-queue list                    Show pending tasks by priority
  /smith-queue status                  Show all tasks grouped by lifecycle status
 
PROCESS (primary command for running tasks)
  /smith-queue process                 Interactive picker — choose a task
  /smith-queue process <filename>      Process a specific task
  /smith-queue process --next          Process highest-priority task only
  /smith-queue process --all           Process all autonomous tasks sequentially
  /smith-queue process --all --dry-run Show what would be processed
  /smith-queue process --all --limit N Process only first N tasks
  /smith-queue process --all --priority high  Only high+ priority
  /smith-queue process --all --model haiku    Override model
  /smith-queue process --all --all-projects   Across all projects
  /smith-queue process --all --abort   Stop after current task
  /smith-queue batch [flags]           Alias for process --all
 
SCHEDULE
  /smith-queue schedule <file> --at "<time>"
  /smith-queue schedule-batch --at "tonight"
  /smith-queue unschedule <filename>
 
EDIT
  /smith-queue edit <filename>         Modify task properties
  /smith-queue promote <filename>      autonomous → interactive
  /smith-queue demote <filename>       interactive → autonomous
  /smith-queue requeue <filename>      Reset failed → pending
  /smith-queue prioritize              Interactive priority reordering
  /smith-queue remove <filename>       Delete a task from the queue
 
HISTORY
  /smith-queue history                 List completed/failed tasks
  /smith-queue history --status failed Only show failed tasks
  /smith-queue history --since "last week"
  /smith-queue history clear --before "<date>"
 
SCHEDULER
  /smith-queue scheduler install       Install daily 2am scheduler (launchd)
  /smith-queue scheduler uninstall     Remove scheduler
  /smith-queue scheduler status        Check scheduler and show recent logs
  /smith-queue scheduler set-time HH:MM  Change daily run time
  /smith-queue scheduler logs          Tail scheduler log
 
STORAGE
  Queue:   .smith/vault/queue/
  History: .smith/vault/queue/history/
  Config:  .smith/config.json > security (allowlist for batch operations)

/smith-vault — Vault Browser
 
Browse the Smith vault persistent memory system.
 
USAGE
  /smith-vault                         Dashboard summary
  /smith-vault sessions                List all session logs
  /smith-vault sessions <file>         Show a specific session log
  /smith-vault agents                  List sub-agent types and identifiers
  /smith-vault agents <type>           Show history for an agent type
  /smith-vault queue                   Show pending queue items
  /smith-vault status                  Health metrics + routing breakdown
  /smith-vault projects                List all registered projects
 
VAULT LOCATION
  .smith/vault/
    sessions/      Session logs (created by hooks)
    agents/        Sub-agent memory by type
    queue/         Task queue entries
    timesheets/    Generated timesheets
    reports/       Generated project reports
    specs/         Spec change tracking

/smith-report — Client Report Generation
 
Generate client-facing project reports from vault data.
 
USAGE
  /smith-report
  /smith-report --range week --type progress
 
DATE RANGE
  week, month, or YYYY-MM-DD:YYYY-MM-DD
 
REPORT TYPES
  progress     What was built, in progress, next steps
  decisions    Key decisions and their reasoning
  specs        Specs created, modified, completed
  full         All of the above plus audit summary and metrics
 
OUTPUT
  Saved to .smith/vault/reports/
  Also printed in chat

/smith-constitution — Project Constitution
 
Create or update the project constitution at .specify/memory/constitution.md.
 
USAGE
  /smith-constitution
 
BEHAVIOR
  Interactive principle input, fills placeholder tokens, propagates
  amendments across dependent templates and artifacts.

/smith-taskstoissues — Tasks to GitHub Issues
 
Convert tasks.md entries into dependency-ordered GitHub Issues.
 
USAGE
  /smith-taskstoissues
 
Maps task dependencies to issue references so the backlog reflects
the same execution order as the task breakdown.

/smith-migrate-specs — Spec Migration
 
One-time migration of existing flat spec folders in specs/ into the
system-based hierarchy at .specify/systems/<system>/features/.
 
USAGE
  /smith-migrate-specs
  /smith-migrate-specs --dry-run       Show proposed mappings without moving
  /smith-migrate-specs --all           Skip individual confirmations
 
BEHAVIOR
  Processes one feature at a time with user confirmation.
  Copies files (originals preserved in specs/ until manually removed).
  Adds frontmatter with primary_system, also_affects, status.

/smith-migrate-system-paths — Add `paths:` Frontmatter to System Specs
 
One-time migration that scans existing .specify/systems/system-*/spec.md
prose for path-like references (services/<X>/, backend/<X>/, frontend/<X>/,
etc.), proposes a paths: list per system, and after operator confirmation
injects YAML frontmatter ABOVE the existing body. Body bytes are preserved
verbatim. Re-runs are idempotent (skips files that already have paths:).
 
USAGE
  /smith-migrate-system-paths
  /smith-migrate-system-paths --dry-run             Show proposals without writing
  /smith-migrate-system-paths --top-n N             Max proposals per system (default 5)
  /smith-migrate-system-paths --auto-confirm        Accept all (tests only)
 
WHEN TO USE
  After Smith manifest v2 is in use and you want path-resolver tier 1
  (declared paths) to take over from tier 3 (heuristic). Run this once
  per project that grew system specs as prose.
 
WHEN NOT TO USE
  - No .specify/systems/ exists — use `/smith` Phase 4.8 instead.
  - System specs already have paths: in frontmatter — skipped automatically.
  - You want to migrate feature folders — that's `/smith-migrate-specs`.
 
NEXT STEPS
  Run `/smith-index` after migration so per-system manifests pick up the
  new tier-1 buckets. Optionally run `/smith-index --describe` to backfill
  description layer.

/smith-bank — Idea Bank
 
Capture ideas mid-conversation and store them in the vault for later
processing. The bank is a section of the vault where ideas get deposited
for safekeeping until you're ready to withdraw them.
 
USAGE
  /smith-bank                            Bank the current conversation's idea
  /smith-bank list                       Show all banked ideas
  /smith-bank list --priority high       Filter by priority
  /smith-bank list --system system-13    Filter by affected system
  /smith-bank process BANK-001           Withdraw idea → /smith-new workflow
  /smith-bank edit BANK-001              Edit a banked idea
  /smith-bank remove BANK-001            Archive a banked idea (with confirmation)
  /smith-bank prioritize BANK-001 --priority high  Change priority
 
NATURAL LANGUAGE TRIGGERS
  "bank this idea"
  "bank this for later"
  "save this for later"
  "let's come back to this"
  "park this idea"
  "stash this thought"
  "deposit this"
 
STORAGE
  Bank:    .smith/vault/bank/
  Archive: .smith/vault/bank/archive/
 
BANK FILE FORMAT
  Each banked idea is a markdown file with YAML frontmatter containing:
  id, title, created, source_session, primary_system, also_affects,
  status (banked|in-progress|completed|queued), priority (critical|high|medium|low)
 
  Sections: Origin, Idea, Requirements (Draft), Systems Affected,
  Open Questions, Conversation Reference
 
PROCESS WORKFLOW
  /smith-bank process <id> reads the banked idea and feeds its description,
  requirements, systems, and open questions directly into /smith-new so the
  user doesn't have to re-explain anything. The bank entry status updates
  through the lifecycle: banked → in-progress → completed/queued.

/smith-reflect — Workflow Reflection & Learning
 
Analyze a completed workflow and extract lessons to the Ledger. Identifies
patterns, antipatterns, tool preferences, and edge cases from real execution
history so future workflows benefit from accumulated experience.
 
USAGE
  /smith-reflect                   Analyze the most recently completed workflow
  /smith-reflect --last N          Analyze last N completed workflows in batch
  /smith-reflect --failure         Learn specifically from recent failures
 
BEHAVIOR
  1. Reads the vault session log for the target workflow(s)
  2. Identifies what worked, what failed, and any non-obvious decisions
  3. Classifies findings into Ledger categories (patterns, antipatterns,
     tool-preferences, edge-cases, project-quirks)
  4. Writes entries to .smith/vault/ledger/ with confidence scores
  5. Skips entries that duplicate existing high-confidence Ledger content
 
CONFIDENCE LEVELS
  high     Observed 3+ times or confirmed by explicit user feedback
  medium   Observed 1-2 times, plausible but not yet confirmed
  low      Single observation, may be coincidental
 
LEDGER FILES WRITTEN
  .smith/vault/ledger/patterns.md
  .smith/vault/ledger/antipatterns.md
  .smith/vault/ledger/tool-preferences.md
  .smith/vault/ledger/edge-cases.md
  .smith/vault/ledger/project-quirks.md
 
OUTPUT
  Summary of new entries added, entries updated, and entries skipped (duplicate)

/smith-ledger — Ledger Browser & Management
 
Browse, search, and maintain the accumulated learning stored in the Ledger.
The Ledger is the persistent memory that grows through /smith-reflect and
is read by /smith-implement and /smith-report.
 
USAGE
  /smith-ledger                    Dashboard — overview stats per file
  /smith-ledger list               List all entries grouped by category
  /smith-ledger list --category <name>   Filter by category
  /smith-ledger list --confidence high   Filter by confidence level
  /smith-ledger search <term>      Full-text search across all Ledger files
  /smith-ledger prune              Interactive review of low-confidence entries
                                   for removal or promotion
  /smith-ledger reset              Archive current Ledger to
                                   .smith/vault/ledger/archive/<date>/ and
                                   start fresh (with confirmation prompt)
 
LEDGER LOCATION
  .smith/vault/ledger/
    patterns.md          Known-good approaches and successful patterns
    antipatterns.md      Known failure modes and what to avoid
    tool-preferences.md  Preferred tools, libraries, flags for this project
    edge-cases.md        Non-obvious edge cases encountered
    project-quirks.md    Project-specific gotchas (infra, env, conventions)
    meta.yaml            Entry counts, last-reflect timestamp, confidence summary
    archive/             Past Ledger snapshots from reset operations
 
PRUNE BEHAVIOR
  Lists all low-confidence entries with: title, category, first-observed date,
  observation count. For each entry, offers: keep / promote to medium / remove.
  Writes changes back to the relevant Ledger file.
 
RECONCILE
  /smith-ledger reconcile           Run Ledger self-maintenance pipeline
  /smith-ledger reconcile --dry-run Preview what would change without modifying files
  /smith-ledger reconcile --force   Bypass lock and minimum-interval checks
  /smith-ledger reconcile --status  Report whether reconciliation is currently needed
 
  PHASES (run in order):
    1. Merge          Deduplicate entries with >90% title similarity across files
    2. Prune          Auto-remove entries below confidence threshold (no prompt)
    3. Budget Enforce Trim each Ledger file to the configured token budget
    4. Meta Update    Recompute .meta.json counts, reset reinforcement counter
    5. Lock Release   Remove reconcile lock file (.smith/vault/ledger/.reconcile-lock)
 
  TRIGGERS (auto-reconcile via post-reflection check):
    - estimated_tokens > thresholds.total_tokens_max (default 30000)
    - context_budget_violations > thresholds.context_violations_threshold (default 3)
    - reinforcements_since_reconcile > thresholds.reinforcements_threshold (default 50)
    - Minimum interval between reconciles: thresholds.minimum_hours_between_reconciles (default 6h)
 
  SAFEGUARDS:
    - Lock file prevents concurrent reconcile runs
    - --dry-run always safe — reads only, no writes
    - Pruned entries are moved to .smith/vault/ledger/archive/ not deleted
 
  CONFIGURATION (in .smith/config.json under ledger.reconcile):
    auto_reconcile, reconcile_model, thresholds (total_tokens_max,
    context_violations_threshold, reinforcements_threshold,
    minimum_hours_between_reconciles)

/smith-finish — Session Finish
 
End-of-session workflow that commits, pushes, merges, updates specs,
and verifies clean workspace state.
 
USAGE
  /smith-finish
 
STEPS
  1. Inventory current state (branch, changes, PRs)
  2. Commit (explicit file staging, conventional commits)
  3. Push to remote
  4. Update system specs and changelog
  5. Create PR and squash-merge
  6. Verify clean state on main
  7. Rebuild Docker services if needed

You're looking at it.
 
/smith-help             Full command overview
/smith-help <command>   Detailed help for a specific command