Use Smithers Workflows

This skill is for choosing and using workflow patterns, not for mechanically forcing Smithers into every task.

Use it when the user wants behavior like:

• implement, review, fix, loop until clean
• monitor CI over time and keep acting
• monitor a PR and keep reacting to checks or comments
• compose multiple known workflow patterns into one higher-level flow

Do not use it merely because files happen to live in the workflow repo.

If the task is mainly:

• debugging Smithers itself
• investigating an upstream Smithers runtime bug
• changing the workflow library internals

then use this skill only for local repo conventions when needed, not as the framing for the whole task.

Current baseline

Check these files first before making changes:

• package.json
• smithers.config.ts
• .smithers/workflows/implement-review-fix.tsx
• .smithers/workflows/ci-babysit.tsx
• .smithers/workflows/ci-watch-babysit.tsx
• .smithers/workflows/pr-babysit.tsx
• .smithers/components/ImplementReviewFixLoop.tsx
• .smithers/components/ReviewLean.tsx

As of this repository state:

• Smithers runtime dependency is smithers-orchestrator from npm.
• The repo is configured around typescript ~5.9.3.
• The repo expects zod ^4.3.6.
• Hooks are managed with prek.

If the dependency stack changes, update this skill to match the current repository rather than preserving stale instructions.

Workflow selection

Start from the nearest existing workflow:

• implement-review-fix
  • Use for coding loops that should implement, validate, review for safety/correctness/leanness, fix findings, and converge.
• ci-babysit
  • Use for GitHub Actions inspection, failure classification, deterministic fix-up, and rerun decisions.
• ci-watch-babysit
  • Use for long-running GitHub Actions monitoring with durable timer-based backoff, reruns, and fix loops.
• pr-babysit
  • Use for pull request inspection, actionable review handling, and deterministic patching.

When a request can be expressed as a composition or refinement of one of these, modify or derive that workflow.

Common target-repo mappings:

• feature implementation with iterative review
  • start from implement-review-fix
• investigate a failing GitHub Actions run once
  • start from ci-babysit
• monitor a GitHub Actions run over time and keep acting
  • start from ci-watch-babysit
• inspect or babysit a PR
  • start from pr-babysit
• implement -> review -> fix -> push draft PR -> watch CI/PR -> keep fixing
  • compose implement-review-fix with ci-watch-babysit and pr-babysit
  • if that composition becomes a recurring pattern, derive a new workflow instead of repeating ad hoc glue

Only create a brand-new workflow when:

• no existing workflow is structurally close, and
• forcing reuse would make the result harder to understand or maintain.

Editing rules

• Reuse existing components before adding new ones.
• Reuse existing prompts before adding new prompts.
• Add a new component only when logic would otherwise be duplicated across workflows.
• Add a new prompt only when the behavior is meaningfully distinct and reusable.
• Remove dead scaffold or unused files instead of accumulating alternatives.
• Keep code lean. The best new node is the one not added.

Invocation

Use the repo-local Smithers CLI, not bunx smithers-orchestrator. This repository relies on its installed runtime and workflow pack:

./node_modules/.bin/smithers

When invoked from another repo, keep the working-repo boundary explicit:

• run Smithers commands from /Users/work/code/smithers-workflows
• pass the target repo or GitHub identifiers as workflow input
• make code changes in the target repo, not in the workflow repo, unless the task is to evolve the workflow library itself

List available workflows:

bun run workflow:list

Run a workflow directly:

./node_modules/.bin/smithers up .smithers/workflows/<workflow>.tsx

Typical examples:

./node_modules/.bin/smithers up .smithers/workflows/implement-review-fix.tsx --input '{"prompt":"Implement the requested change."}'
./node_modules/.bin/smithers up .smithers/workflows/ci-babysit.tsx --input '{"repo":"owner/name","run":"123456789"}'
./node_modules/.bin/smithers up .smithers/workflows/pr-babysit.tsx --input '{"repo":"owner/name","pr":"42"}'

Local dashboard

When a workflow is launched for monitoring, babysitting, or any long-running task, also make the local dashboard available unless it is clearly unnecessary.

For long-running workflows, a detached run alone is not sufficient. Timer-based workflows persist state in smithers.db, but they do not keep resuming themselves unless a supervisor loop is running.

For these workflows:

• ci-watch-babysit
• any workflow that uses Timer
• any workflow expected to keep acting while the user is away

Preferred approach: use tmux so the supervisor is owned by the OS session rather than the launching chat/tool process.

Launch all three:

1. the run in detached mode
2. the supervisor loop in a long-lived tmux session
3. the dashboard

Use:

./node_modules/.bin/smithers up -d .smithers/workflows/<workflow>.tsx --input '{...}'
bun run supervisor:start
bun run dashboard

Supervisor lifecycle commands:

bun run supervisor:start
bun run supervisor:status
bun run supervisor:stop-if-idle

Do not present smithers up by itself as durable monitoring. Without supervise, the run will reach waiting-timer, the CLI will exit, and nothing will resume it.

Operational notes:

• supervisor:start must be treated as idempotent.

• Reuse one supervisor per Smithers DB / repo runtime, not one per workflow.

• Prefer reusing the same tmux session name: smithers-supervisor.

• If the supervisor command changes, replace the session intentionally instead of spawning duplicates.

• Report to the user that the long-lived supervisor is running in tmux, not inside the chat process.

• If tmux is unavailable, state that clearly and fall back to a normal long-lived terminal process only as a weaker alternative.

• Start the dashboard with:

bun run dashboard

• Tell the user to open: