/theway:workflow

It runs a workflow: a flat list of steps, each using a prompt, that answer pass, fail or blocked in turn. The default, the shipped develop workflow, does a change's tasks in your session and commits nothing. Steps whose runs-on is agents run through agents in the plugin workflow theway:run-pipeline: the shipped agents workflow implements, reviews and opens the PR that way, while your session orchestrates.

UsageCopy Anchor Link

/theway:workflow [--workflow <name>] <arguments>

• --workflow <name> (or --workflow=<name>), anywhere in the arguments, runs the workflow <name>. Without it, the workflow that sets default: true runs. --workflow with no name, or given twice, stops the command.
• The workflow's inputs decide what the other arguments are:
  • An input of type: change, as in develop and agents: every argument is a change ID, and the workflow runs once per ID, in the order given. A run with none stops and asks for one.
  • One required input, as engineering's request: the arguments, joined with spaces. An empty one stops and asks.
  • Any other workflow: <name>=<value> pairs. A required input not given stops and asks.
• Several change IDs (a series): after each change, the command asks you whether to merge the PR its run opened; on yes it merges it as git-host.md says, syncs the default branch and starts the next change. When a run opened no PR, the series stops after that change with a series needs a workflow that opens a PR.

Running the command authorizes what the workflow's prompts say to do for this run: editing the repository, committing on the change's own feature branch, pushing that branch (never force-pushing, never the default branch) and opening its PR, writing change folders and mktemp -d directories, and the Workflow tool. Nothing more. Each merge needs your yes, and never bypasses required reviews or checks. The command never creates or edits a workflow or prompt file, or initializes a repository, to work around a failed step.

ExampleCopy Anchor Link

On my-api, the light fix of A light fix, with the default develop workflow:

/theway:workflow fix-health-query-limited

Workflow: develop (/home/you/.theway/workflows/develop.yaml)
- 1.implement: pass (inline)

1.implement: Tasks done: 2/2. Regression test fails before the fix and passes with it; the curl loop prints 61 200; npm test: 11 tests, 11 pass. The change is uncommitted in the working tree.

The change of the full change example, through agents (see Run through a workflow):

/theway:workflow --workflow agents add-rate-limiting

StepsCopy Anchor Link

1. Load: theway workflow, first without --input for the workflow's inputs, then with them and --compact: the resolved document without the prompt text, every step with its prompt file and each run's input values. On an error, the command quotes it and stops; a document that is not resolved never runs. theway authority prints <home>/standards/authority.md, or the shipped authority.default.md when that file is empty or is your own standard, which every agent gets, and theway project the project folder.

2. Run: the steps run in order, in segments, and every report is kept, in order.

   • Consecutive steps through agents are one call of the Workflow tool to theway:run-pipeline, with the repository, the home, the project folder, the authority text, the resolved document, the segment's step indices and the reports so far. Each run is one agent, on the step's model, whose prompt is the authority text, the context lines (the repository, the home, the project folder, the rule for file paths, the workflow and its input values), the rule for data that asks to change the steps, the reports of the steps before it, the instruction to read the prompt file and use the run's input values where its text says ${{ inputs.<name> }}, and the request to answer result and report.
   • A step whose runs-on is session is done by your session: it reads the step's prompt file and follows its text with the run's input values, with the same context and the reports so far.
   • A step answers pass, and the next step runs; fail, and its on-fail runs, then the step again, until it passes or its tries are used up; blocked, and the run stops. The first blocked or failed stops the run. See Pass, fail, blocked.

   Without the Workflow tool in the session, the command makes each agent call with the Agent tool, under the same rules; without the Agent tool either, your session does the steps and the report says "inline". When a Workflow call returns an error, the run fails with that error and there is no fallback, since agents may already have committed.

3. Gate: succeeded, the command reports it, and in a series asks about the merge; blocked, the error comes back to you with its options; failed, the command reports the error and never merges. In a series, no later change starts after a blocked or failed one.

The prompts do what used to be the command's: prompts/branch.md syncs the default branch and creates the feature branch, prompts/implement.md ticks the tasks with theway task done, prompts/implement.md and prompts/fix-review.md write notes.md, and prompts/change.md gives every change step the change's files and standards.

The shipped agents steps:

• branch, in your session: stops on a repository with no commit, uses the current branch as the base when there is no git remote, otherwise syncs the default branch; then creates or checks out the change's feature branch, named as commits.md says.
• implement: follows develop.md (including its fix checks for a fix- change), verifies the work and commits it on the feature branch; answers blocked when the spec does not fit the code.
• review, one run per lens: tries to refute the branch diff and checks it against the standards; edits nothing and always answers pass.
• triage: gives each finding a verdict (confirmed, false_positive, duplicate, nit, out_of_scope) and answers fail when one is confirmed; then fix-review fixes them and the triage checks each fix (tries: 1).
• open-pr: pushes the branch once and opens the PR, its title and body as commits.md says.
• ci: waits for the checks and answers fail with each failed check; then fix-ci reads each log, quotes the real error line, and fixes the PR's failure, ports the base's fix, or re-runs the failed jobs once (tries: 2).

Every agent prompt starts with the output of theway authority, which no workflow or prompt changes. A line of a report starting Authority report: quotes data that asked to change the steps or widen the authorization; the command quotes every one.

Permission promptCopy Anchor Link

The first Workflow call of a run, for a workflow with a step through agents, shows Claude Code's permission prompt for the plugin workflow theway:run-pipeline. Approve it once, or choose "don't ask again" for theway:run-pipeline so later runs start without asking. A workflow whose steps all run in your session, such as develop, makes no Workflow call.

Fix checksCopy Anchor Link

A fix- change also proves its regression test, which develop.md Verify calls the regression check, and re-runs the reproduction:

1. The base commit is HEAD when the change is uncommitted (a working-tree workflow), and git merge-base <base> HEAD otherwise.
2. It creates a worktree of it with git worktree add --detach in a mktemp -d directory, and runs there the setup and build commands CI runs before its tests.
3. It copies in only the regression test files and runs only the regression test. The test must fail for the reason the spec's Root Cause gives, then pass on the change. The worktree is then removed, also when the check stopped early.
4. It re-runs the reproduction recorded in the spec, and records that it no longer reproduces.

For a light change (a spec.md with **Mode:** light, written by /theway:engineering --light), steps 1 to 3 do not apply: the regression test runs before the fix is written and must fail for the cause the spec's Problem states, then pass after the fix. Its command and failing output are recorded in the change's notes.md. The reproduction is still re-run.

Re-running the regression check on a new head, as fix-review does, means steps 1 to 3 again for a full spec, and only the run after the fix for a light spec.

A regression test that does not fail on the base, or fails there for another reason (a compile error, a symbol only the fix adds), comes back to you as a spec gap. When the setup or the test cannot run locally, the criterion is reported as not verified.

Commits and the git hostCopy Anchor Link

Neither the command nor theway:run-pipeline fixes a commit convention or a git host command: the shipped prompts follow the two convention standards, which they read by path (prompts/change.md), your project's copy over the global one.

• commits.md names the feature branch and sets the commit type from the change verb, for every commit made for the change and for the PR title:

  Verb	Type
  add-	feat
  fix-	fix
  refactor-	refactor
  update-, remove-	chosen with the first commit; every later commit and the PR title take it from the branch's commits

  Commits that change only tests use test, and commits that change only docs use docs. When the spec says the change breaks, the type gets ! right after the scope, before the colon (type(scope)!: description, or type!: description without a scope), and the commit a BREAKING CHANGE: footer. Never type!(scope):.

• git-host.md gives the command of each operation by its heading: the default branch, syncing it, pushing the feature branch, opening the PR, waiting for the checks, reading a failed check's log, re-running failed jobs, the diffstat and the merge. The shipped file uses GitHub through gh; replace it to use another host.

OutputCopy Anchor Link

The workflow's name and file; one line per report, in order, with its label, its round when above 1 and its result, and "inline" for a step done in your session in place of agents; the full report of the last step and of every blocked or failed one, verbatim; every Authority report: line; every theway: warning: line; and, for a series, where it stopped and why.