Menu
Central reference for all Smith commands — overview, detailed help per command, syntax, flags, and workflow context.
Instalar com Codex ou Claude Copie este prompt, cole no Codex, Claude ou outro assistente e deixe que ele revise a página da skill e instale para você.
Baseado na classificação ocupacional SOC
Thorough, fact-based, hallucination-resistant research on a target website and the company behind it. Crawls the whole site, indexes it into a local vector store, runs deep background research (Bing/Reddit via stealth Playwright), then synthesizes a single fully-cited report where every published sentence is citation-gated and adversarially verified against stored evidence. Correctness over speed. All artifacts land in ~/Documents/smith-research/.
Initialize SpecKit on a new or existing project — scans the codebase, interviews you about project details, and generates CLAUDE.md, constitution.md, and the full .specify/ scaffolding with commands and agents.
Lightweight fix workflow for bugs and small changes. Autonomous from invocation through merged PR — no questions gate, no spec generation, no planning phase.
Diagnostic workflow that systematically gathers evidence, identifies root causes, and produces a structured debug report. Read-only — does not modify code. Output feeds into /smith-bugfix if a fix is needed.
Start a new feature from scratch or from conversation context. Conversational requirements gathering, planning, questions gate, then fully autonomous build.
Autonomous build phase — generates tasks, implements, tests, commits, pushes, merges, and produces release notes. Runs without user interaction.
| name | smith-help |
| description | Central reference for all Smith commands — overview, detailed help per command, syntax, flags, and workflow context. |
| argument-hint | ["<command>"] |
Display help for Smith commands. With no arguments, shows the full command overview. With a command name, shows detailed help including syntax, flags, examples, and workflow context.
Arguments: $ARGUMENTS
This action is read-only — it does not modify any files. It should always be handled directly by the current session, never delegated to a sub-agent.
When invoked with no arguments, display this overview:
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
After displaying the overview, also scan .claude/commands/ for any smith.*.md files not listed above. If found, append them under a "ADDITIONAL" section with their description from frontmatter. This ensures newly added commands appear in help even without explicit entries.
When $ARGUMENTS contains a command name, display detailed help for that command.
Match the argument against known commands. Accept with or without the smith- prefix (e.g., both queue and smith-queue work). Also accept partial matches for sub-commands (e.g., queue process matches smith-queue process).
new/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.
specify/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
clarify/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
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
tasks/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
analyze/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.
implement/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.
build/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
debug/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)
bugfix/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
checklist/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.
queue/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)
vault/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
report/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
constitution/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.
taskstoissues/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.
migrate-specs/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.
migrate-system-paths/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.
bank/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.
reflect/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)
ledger/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)
finish/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
helpYou're looking at it.
/smith-help Full command overview
/smith-help <command> Detailed help for a specific command
If $ARGUMENTS doesn't match any known command:
.claude/commands/ for files matching smith.*$ARGUMENTS*.mddescription field and first paragraph after frontmatter<argument>. Run /smith-help for the full command list."