attckdigital/smith/smith-help

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)