---
title: smithering
description: Route a request by size. Trivial work goes straight to a fast agent, complex work to an autonomous coder, and full builds run the whole plan, build, validate, launch, review, and deliver pipeline.
---

`smithering` is the "replace the human operator" meta-workflow. You describe what
you want and it decides how much process the request deserves, then runs it end to
end. The premise is that you never type CLI commands yourself: your operating agent
runs smithers on your behalf, answers the workflow's HumanTasks, and clears its
approval gates after checking with you.

```bash
bunx smithers-orchestrator workflow run smithering \
  --prompt "Add SAML SSO to the admin console"
```

When `prompt` is omitted, the workflow opens with a setup interview (a HumanTask)
that collects the request before anything else runs.

## Tiers

After setup, the request is classified (or forced with `route`) into one of three
tiers, and only the matching path spends real work:

- **trivial**: a fast agent just does it, then verifies, evidences, and reports.
- **complex**: an autonomous coder drives it to completion on its own.
- **full-build**: the entire pipeline below, for work that needs a spec, a design,
  tickets, and a generated implementation workflow.

Set `route` to `trivial`, `complex`, or `full-build` to skip the classifier, or
leave it `auto` to let the workflow decide.

## Stages (full-build)

1. **setup / route**: collect the request (HumanTask when there is no `prompt`) and pick the tier.
2. **preflight + intake**: check the repo and frame the problem.
3. **brainstorm**: widen the solution space before committing.
4. **research + questions**: study the domain and prior art, then ask the blocking product questions (HumanTask; auto-adopts recommendations when autonomous).
5. **PRD**: write the product spec and pause at `gate:prd` for approval.
6. **design**: draft and review a design doc in a loop, then finalize it.
7. **eng doc**: draft and review the engineering plan, then pause at `gate:eng`.
8. **backpressure**: map every success criterion to a verification gate.
9. **probes**: run third-party assumption probes and stop at `gate:probes`.
10. **tickets**: break the work into ordered tickets.
11. **orchestration**: design and scaffold a real implementation workflow (plus an optional POC when `poc` is set).
12. **validate**: verify, review, fix blocking issues, and smoke-test the generated workflow before launch.
13. **launch + monitor**: clear `gate:launch`, run the implementation workflow, and watch it in a monitor loop that polls, reports, and triages.
14. **review**: independent reviews from multiple agents, synthesized into one verdict.
15. **polish**: a scan, fix, and verify pass over the result.
16. **deliver**: gather an evidence report and hand off at `gate:delivery`.

## Full-build merge policy

The generated implementation workflow lands ticket branches only onto the integration
branch. The independent verifier is the authoritative pre-merge signal: `verify.json.pass`
must be true after checking the ticket rebased onto the current integration tip. Cross-family
`review.json` findings are advisory feedback, not a hard landing veto; safety/security
tickets additionally require an approved adversarial `challenge.json`.

Landing is continuous and per-ticket, not a per-wave barrier. Topological waves may still
be used for stable ordering, but a ticket enters the serialized merge queue as soon as its
own verifier/challenge is green and all of its `dependsOn` tickets have landed. A blocked
ticket only blocks its transitive dependents; unrelated siblings continue to build and land.

If a conflict, typecheck, or test failure appears only on the merged integration tip, the
failure is fed back to that ticket's implementer loop and retried up to its iteration budget
instead of permanently blocking dependents. Fresh runs are idempotent: tickets whose land
commits already appear in `git log <base>..integration` are treated as done and skipped.

## Inputs

| Input | Type | Default |
| --- | --- | --- |
| `prompt` | string | `""` (the setup HumanTask collects it when empty) |
| `repo` | string | `null` (the current repo) |
| `route` | `auto` \| `trivial` \| `complex` \| `full-build` | `auto` |
| `review` | boolean | `true` (pause at gates; `false` runs fully autonomous) |
| `poc` | boolean | `false` (build a proof of concept before the real workflow) |
| `smokeTest` | boolean | `true` (smoke-test the generated workflow before launch) |
| `baseBranch` | string | `"main"` |
| `maxMonitorHours` | number | `24` (cap on the launch monitor loop) |

With `review: false` the workflow runs without stopping: every approval gate
auto-passes and every product question auto-adopts its recommended answer.

## Monitor it

```bash
bunx smithers-orchestrator workflow run smithering --prompt "…" -d   # detach
bunx smithers-orchestrator ps                                        # active / paused / recent
bunx smithers-orchestrator logs RUN_ID -f                            # follow events
bunx smithers-orchestrator approve RUN_ID --node gate:prd            # clear an approval gate
```

Reach for `smithering` when you want to hand off a whole piece of work, from a
one-line ask to a full build, and have Smithers run the operator role: size it,
plan it, build it, validate it, launch it, review it, and deliver an evidence
report, pausing for your approval only where it matters.
