> ## Documentation Index
> Fetch the complete documentation index at: https://smithers.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# smithering

> 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 an archived example, not installed by `init`: copy it from `examples/init-pack/` with its dependency closure, or ask `create-workflow` to build an equivalent.

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

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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 first.

## Tiers

After setup, the request is classified (or forced with `route`) into one of
three tiers; 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.
* **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 if 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 blocking product questions (HumanTask; auto-adopts recommendations when autonomous).
5. **PRD**: write the product spec and pause at `gate:prd`.
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 monitor it in a 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 rebasing the ticket onto the current integration tip. Cross-family
`review.json` findings are advisory, not a landing veto; safety/security
tickets also require an approved adversarial `challenge.json`.

Landing is continuous and per-ticket, not a per-wave barrier. Topological waves can still
order tickets, but a ticket enters the serialized merge queue as soon as its
verifier/challenge is green and its `dependsOn` tickets have landed. A blocked
ticket only blocks its transitive dependents; unrelated siblings keep building and landing.

If a conflict, typecheck, or test failure appears only on the merged integration tip, it
feeds back to that ticket's implementer loop and retries 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                                           | `""` (setup HumanTask collects it if 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 POC 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 theme={"theme":{"light":"github-light","dark":"github-dark"}}
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` to hand off a whole piece of work end to end, from a
one-line ask to a full build, pausing for approval only where it matters.