How it works

A change goes through three commands.

/theway:engineering <request>        writes spec.md and change.yaml
  or /theway:engineering --light <request>   writes a short spec for a small change
/theway:workflow <change-id>         implements the tasks inline, in your session
  or /theway:workflow --workflow agents <change-id>   implements them through agents and a PR
/theway:archive <change-id>          moves the finished change to the archive

1. EngineeringCopy Anchor Link

/theway:engineering runs the shipped engineering workflow, whose one input is the request, through /theway:workflow. Its scaffold step, in your session, runs theway context engineering for the standards, follows the TAMM framework, picks a change ID and validates it with theway validate-id, or, for a series, gets the member IDs from theway next-id. It investigates the code and the open questions, then writes spec.md and change.yaml from the template prompts, checks change.yaml with theway change, and design.md when the change needs API contracts, data models or diagrams. Its spec-review step then runs two critic agents on the spec and tasks, unless a question is already open; its spec-triage step verifies each finding, a fix agent fixes every confirmed gap that can be settled from facts, and the run stops if a finding needs your decision.

A fix- change uses the fix template for spec.md, and the command reproduces the bug before it writes anything. When the bug cannot be reproduced, may already be covered by another active change, or turns out to be intended behavior, it stops and asks you, and writes no change folder.

For a small change with nothing to decide, /theway:engineering --light writes a short spec (**Mode:** light) and 1 to 3 tasks, and one grounding critic reviews them. When it finds a decision, a contract change, a Medium or High risk or a series, it sends you to /theway:engineering without --light.

It writes the change files only under <home>/projects/<key>/changes/<change-id>/ (<home> is the folder theway path prints, ~/.theway by default); throwaway probes write to a temporary directory created with mktemp -d. If a question is still open, it reports the review and the question, then stops: the spec is not ready until it is answered.

2. WorkflowCopy Anchor Link

/theway:workflow runs the change through the steps of a workflow file, resolved by theway workflow with the change ID as its input: each step uses a prompt and answers pass, fail or blocked. The change steps read standards/develop.md, the standards theway context lists, the change's spec.md, change.yaml, design.md and notes.md, and docs/architecture/coding-standards.md when it exists (prompts/change.md). The spec is the contract: when the code contradicts it, the work stops and comes back to you with the options.

Each step runs in your session or through agents in the plugin workflow theway:run-pipeline, as its runs-on says. theway ships two workflows that run a change:

• develop, the default: one implement step in your session, with commit: "no". Your session implements the tasks, ticks each one with theway task done and reports how each Success Criterion was verified. Nothing is committed: the change stays in your working tree.
• agents: your session creates the feature branch; an implementer agent commits on it; reviewer agents, one per lens, review it; a triage judges their findings and a fix agent fixes the confirmed ones; then the branch is pushed once, the PR opened and CI driven to green. The fix rounds are capped by each step's tries. In a series, each PR is merged after you confirm it.

The other two shipped workflows, engineering and engineering-light, take a request: /theway:engineering runs them to write a change's spec.

Choosing between themCopy Anchor Link

Use develop to watch and steer the work in your session. Use --workflow agents when the change should end as a reviewed, CI-green PR, or to run a whole series. Between the two, your own workflow can mix them, for example implement in your session followed by the review and the PR through agents, or a step of your own.

3. ArchiveCopy Anchor Link

/theway:archive moves a finished change to <home>/projects/<key>/changes/archive/YYYY-MM-DD-<change-id>/. It runs only when you name the change and say to archive it. It refuses while a task in change.yaml is not done, or the file is invalid, unless you accept and it runs with --force.

See the Examples section: one change from request to passing tests, then a light fix, an escalation, a workflow run, a series and standards.