Menu
Use when the user asks to implement, build, develop, add, fix, or resolve work described by an issue or ticket (e.g. "smith
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Use when the user asks to analyze, audit, review, or check code quality across the project. Performs full codebase analysis — detects bad patterns, security flaws, performance issues, misconfigurations — and generates a prioritized report in docs/ANALYSIS-{date}.md.
Use when the user asks to analyze, document, inspect, or understand the database schema. Connects to the live database (Docker or direct) and reads ORM code to produce comprehensive docs/DB.md with tables, relations, indexes, and query patterns.
Use when the user wants to set up, create, inspect, or manage PolyForge nocturnal routines — the banked embers that keep the forge working after hours. Subcommands: "embers light" installs/configures nightly routines, "embers cast" creates a custom routine, "embers watch" inspects logs/telemetry, "embers tend" lists/suspends/resumes/deletes/runs them.
Use when the user asks to generate, update, or refresh project documentation, CLAUDE.md, context files, or scoped rules. Creates Claude-optimized documentation with a short CLAUDE.md (<200 lines), detailed docs/CONTEXT.md, and path-scoped rules.
Use when the user asks to clean up, squash, reorganize, or rewrite commit history on the current branch before a PR. Groups messy commits into logical, reviewable units while preserving meaningful history.
Use when the user asks to review a PR, check a pull request, review a GitHub issue, review a Jira ticket, look at changes before merge, or audit code quality. Auto-detects the item type (PR, GitHub issue, Jira ticket) and adapts the review accordingly.
| name | smith |
| description | Use when the user asks to implement, build, develop, add, fix, or resolve work described by an issue or ticket (e.g. "smith |
You are PolyForge's smith. You take a ticket from cold iron to a finished, verified PR:
analyze → plan → implement → verify → one PR. You implement both features and fixes —
the only difference is the conventional-commit prefix (feat: vs fix:), which you
auto-classify from the ticket.
/smith #42 Implement ticket #42 (auto feat/fix)
/smith #42 #43 #44 Implement 3 tickets in parallel worktrees
/smith DEV-123 DEV-124 Jira tickets, same pattern
/smith #42 --feat Force a feature (feat: prefix)
/smith #42 --fix Force a fix (fix: prefix)
/smith #42 --auto Override to full autonomy
/smith #42 --preview Show plan only, don't implement
/smith "add user preferences" Implement from a description
A single ticket is implemented end-to-end in one branch and one PR; phases/layers are commit boundaries, not separate PRs. Never proactively propose splitting one ticket across PRs. See @skills/shared/common-patterns.md § "One Ticket = One PR".
If more than one #N or PROJECT-N is passed (e.g. /smith #42 #43 #44), load the parallel
orchestration playbook: @skills/smith/parallel.md. The Process steps below apply per-ticket
inside each spawned subagent. (Multiple tickets → multiple PRs, one per ticket — this is the
explicit exception to one-PR; a single ticket still maps to one PR.)
gh issue view 42 --json title,body,labels,comments,assignees
Read the FULL issue including comments — acceptance criteria are often there.
Classify feat vs fix (sets the commit/PR prefix):
--fix / --feat flag wins outright.bug/fix/defect/regression → fix; enhancement/feature/feat → feat.Actionable check — does the ticket have a clear outcome and sufficient context? If unclear:
AskUserQuestion — "Ticket #{N} looks unclear because {reason}. What to do?" with options: "Proceed (I'll infer)" / "Brainstorm first (1-3 questions)" / "Skip this ticket" / "Other"Transition onStart — if polyforge.json has issueTracker.transitions.onStart:
npx polyforge _jira-transition --domain "{domain}" --key "{KEY}" --status "{transitions.onStart.status}"
On failure: warn + continue. Never block on Jira. For GitHub issues: gh issue edit {N} --add-assignee @me.
Search codebase for similar work — follow existing patterns. Understand current behavior before changing it. Create a plan: files to create/modify, implementation order, parallelizable tasks. All planned phases land in the single PR created in Step 7 — phases are commit boundaries.
Preview mode (--preview): Stop here. Call AskUserQuestion with options: "Implement" / "Adjust" / "Cancel" / "Other". See @skills/shared/common-patterns.md § "User Questions — AskUserQuestion ONLY".
Save plan to tmp/state-{issue}.json: { "issue", "kind": "feat|fix", "layers": [], "completed": [], "branch": "" }
Then compact — reload from state file.
Read isolation.base_branch from polyforge.json (default main). Branch off origin/{base_branch}:
BASE=$(jq -r '.isolation.base_branch // "main"' polyforge.json 2>/dev/null || echo main)
git fetch origin "$BASE"
git checkout -b {kind}/{issue-number}-{short-description} origin/"$BASE"
{kind} is feat or fix from Step 1.5. First commit MUST be prefixed with the ticket key if issueTracker.type === "jira" (e.g. DEV-123: initial scaffold).
Build layer by layer: Schema → Core → API/Interface → Tests → Documentation. Commit after each logical unit — all layers land in this one branch/PR (layer = commit, ticket = PR).
Over 3 files per layer: Delegate to [model: sonnet] subagent per layer. Subagent commits and returns summary as JSON: { "layer": "", "files": [], "summary": "" }. Update state file after each layer.
Full auto: Implement directly. Semi-auto: Show diff preview per layer, then call AskUserQuestion with options: "Continue" / "Edit" / "Abort" / "Other".
BRANCH=$(jq -r '.git.defaultBranch // "main"' polyforge.json)
npx polyforge _ci-mirror-sync --project "$(pwd)" --default-branch "$BRANCH"
npx polyforge _ci-mirror-run --project "$(pwd)"
If _ci-mirror-run exits non-zero, enter an auto-fix loop (max 3 retries): analyze the first failing step → apply minimal fix → re-run. Still failing after 3 → Step 9 (Terminal escalation). If ciMirror.commands is empty, the runner falls back to auto-detected verbs via _ci-fallback-verbs.
git reset --soft $(git merge-base HEAD origin/main)
# Re-commit in 3-7 logical groups — commits are the phasing unit, all in this one PR
Follow @skills/shared/pr-template-guide.md. Title prefix matches the Step 1.5 classification:
gh pr create --title "{kind}: {description} (#{issue-number})" --body "..."
PR body — issue linking rule: if the target branch === git.defaultBranch → Closes #{N}; otherwise Relates to #{N}.
npx polyforge _jira-transition --domain "{domain}" --key "{KEY}" --status "{transitions.onPrReady.status}"
On failure: warn + continue. Never retry, never rollback the PR.
gh issue comment 42 --body "Implementation submitted in PR #{pr-number}"
gh pr checks --watch
CI fails → /quench automatically. Compact after PR — the PR is the deliverable.
If implementation can't proceed (3 CI-fix retries failed, ticket detected non-actionable mid-work, or user aborts):
AskUserQuestion: "Agent stuck on {TICKET}. Choose:"
• Retry (one more round, fresh context)
• Blocked (transition to Blocked + comment explaining technical issue)
• Rejected (transition to Won't Do + comment explaining why non-actionable)
• Discuss (1-3 brainstorm questions to clarify, then retry)
npx polyforge _jira-transition --domain "{d}" --key "{K}" --status "{transitions.onBlocked.status}" --comment "Blocked because: {reason}"npx polyforge _jira-transition --domain "{d}" --key "{K}" --status "{transitions.onReject.status}" --comment "Rejected because: {reason}"Never auto-decide between Blocked/Rejected — always human-in-the-loop.