/theway:engineering

The spec is written so that someone else can implement it without guessing: the problem, what was found out, and the decisions and why. The code comes later, from /theway:workflow.

For a small change with nothing to decide, --light is the light path: a short spec, 1 to 3 tasks and one critic (see Light).

/theway:engineering is an alias: /theway:engineering <request> runs /theway:workflow --workflow engineering <request>, and /theway:engineering --light <request> runs /theway:workflow --workflow engineering-light <request>. Both are shipped workflows with one required input, request, built from prompts like any other, so you can change them (see Customize).

UsageCopy Anchor Link

/theway:engineering [--light] <request>

For a series, ask for a series or for several sequential changes, or pass an argument that ends in -NN: theway next-id removes that ordinal.

ExampleCopy Anchor Link

On my-api, a series request (see A series for the whole run):

/theway:engineering add-user-auth as a series: password storage, the login endpoint, docs

$ theway next-id add-user-auth --count 3
add-user-auth-01
add-user-auth-02
add-user-auth-03

Each member is its own change folder; the series' total is the number of members. The report ends with the triage's report, trimmed here to one verdict:

3.spec-triage (round 2): pass
1: confirmed, settled: add-user-auth-02 does not say what POST /login returns on success. -02 returns 204 with no body: my-api has no sessions, and -02's Out of Scope excludes tokens. Resolved: spec.md of -02 says so.

StepsCopy Anchor Link

The shipped engineering workflow:

# workflows/engineering.yaml
version: theway.workflow/v1beta
description: Investigate a request and write its spec and tasks, then review them
inputs:
  request:
    description: What the change should do
    required: true
runs-on: agents
steps:
  - uses: prompts/scaffold.md
    runs-on: session
    with:
      request: ${{ inputs.request }}
  - uses: prompts/spec-review.md
    matrix:
      lens: [prompts/grounding.md, prompts/implementability.md]
    with:
      lens: ${{ matrix.lens }}
  - uses: prompts/spec-triage.md
    on-fail: prompts/fix-spec.md
    tries: 1

1. Load: /theway:workflow resolves the workflow with the request as its request input and runs theway authority. There is no branch and no commit: the run writes only the change folders it creates, and throwaway probes in mktemp -d directories.

2. scaffold, in your session: the scaffold prompt, which reads scaffold-rules, tamm-framework and spec-investigation first.

   • Change folder: it picks a change ID and validates it with theway validate-id <change-id>. It must exit 0 before any folder is written. For a series, theway next-id <series-id> --count <N> validates the series ID and prints the member IDs.

   • Investigate: read the code involved, check how it behaves today and settle the unknowns, for example by cloning a repository, running a small throwaway script or calling a service. Each investigation answers one question. What it learns goes into the spec as findings (question, method, result), not as code or diffs.

     For a fix- change, it reproduces the bug first, with a throwaway probe in a mktemp -d directory or the project's existing commands and tests, without changing the repository. The command and its output go into the spec, quoted: reasoning about the code is not a reproduction. Three outcomes stop the scaffold before any change file is written:

     • Not reproduced: it asks you, listing each attempt with its command and output, and what would help (an environment, a log, exact steps).
     • Possibly already covered: an active change ID from theway list plausibly names the same bug; it asks you whether that change covers it. The members of the series being continued do not count, nor does the change ID this run picked, whose folder it writes over. It judges from the IDs only and never opens other change folders.
     • Works as intended: it reports the code and docs that show the behavior is intended.

     After a stop, run /theway:engineering again with the new information: it keeps no state between runs.

   • Documents: the spec-template prompt produces spec.md (the fix-spec-template prompt for a fix- change), the change-template prompt produces change.yaml, following each template's frontmatter instructions, and the scaffold runs theway change <change-id> until it exits 0; in a fix- change, task 1 writes the regression test. design.md is optional, for API contracts and data models, architecture decisions, and diagrams.

   • Answer: pass with each change folder and the findings that shaped the spec; blocked with each open question (one it cannot settle, or an open point recorded in the spec), or with a fix- stop report. A blocked scaffold stops the run: the review does not run.

3. spec-review, through agents: one critic per lens, at the same time, each reading the spec-review prompt and its lens prompt, covering every member of a series together:

   • the grounding critic checks the spec's claims about the code, tools, providers and libraries against the code and official docs; for a fix- change, it also re-runs the recorded reproduction and reports it when the output differs;
   • the implementability critic checks whether a cold-start implementer could carry out the change without guessing: choices left open, Success Criteria that cannot be checked or have no task, tasks outside the Scope, tasks that cannot be done as written, contradictions, and a spec or task that contradicts a standard.

   Critics never edit anything, always answer pass, and their probes answer one question each and write only to a temporary directory.

4. spec-triage, through agents: verifies each finding and gives it a verdict (confirmed, false_positive, duplicate, nit or out_of_scope) and, when confirmed, a final kind: fixable or decision. It answers fail when a finding is confirmed. Then fix-spec edits the change files for every confirmed fixable finding, and answers blocked with open question: and each question when a confirmed finding is a decision; otherwise the triage runs again and checks each fix (tries: 1).

Every agent's prompt starts with the output of theway authority, and a line of a report starting Authority report: is quoted in the run's report.

Action words in the request, such as "rename X" or "try the fix", describe what the spec should plan, not something to do now. It does not suggest plan mode, whose approval step starts implementation.

Writing under ~/.theway asks for your approval: install grants no edit permission on the theway home, so each write of the change files, the scaffold's or an agent's, pauses the run on its permission prompt. To avoid the prompts, allow edits under the home with /permissions, or use auto mode.

OutputCopy Anchor Link

Everything is written under <home>/projects/<key>/changes/<change-id>/:

• spec.md: problem and solution, technical decisions, scope, the TAMM hardpoints table, phases and Success Criteria.
  • For a fix- change, the fix spec instead: the problem, the symptom, the reproduction (command and observed output), the root cause with file and line evidence, the fix, the regression test, scope, hardpoints (often "None at Medium or High.") and Success Criteria. Its first two criteria are always the same: the regression test fails on the base commit for the reason in Root Cause and passes with the fix, and the reproduction no longer reproduces.
• change.yaml: the change's one-line description and its tasks, in the order they are done (see theway change).
• design.md, when needed.

The run's report gives each step's result and the full report of the last step: on success, the triage's verdicts; when the run stops, the open question, the stop report or the confirmed decisions, verbatim. If a question is open, the spec is not ready until it is answered.

When a fix- change stopped in the scaffold, no folder is written and no review runs: the report gives the outcome, the attempts or the evidence, and the question for you.

A decision the triage settled from the code, the docs or the spec's own decisions reads confirmed, settled, with the choice made in its reason, so you can overturn it.

LightCopy Anchor Link

With --light, for a small change with nothing to decide: a known cause, a local change, no contract that others rely on. It writes a short spec and 1 to 3 tasks, and one critic reviews them. The code comes later, from /theway:workflow, as for any change.

UsageCopy Anchor Link

/theway:engineering --light <request>

Use it when you already know what changes and why. When the change needs a decision, a contract change or a risk analysis, run /theway:engineering without --light: the light path sends you there itself.

ExampleCopy Anchor Link

On my-api, a bug with a known cause (see A light fix):

/theway:engineering --light fix-health-query-limited: GET /health?probe=1 counts against the rate limit

Workflow: engineering-light (/home/you/.theway/workflows/engineering-light.yaml)
- 1.scaffold-light: pass (inline)
- 2.spec-review: pass
- 3.spec-triage: pass

3.spec-triage: no finding confirmed.

A request that needs a decision writes nothing and sends you to /theway:engineering without --light: see An escalation.

StepsCopy Anchor Link

The shipped engineering-light workflow:

# workflows/engineering-light.yaml
version: theway.workflow/v1beta
description: A short spec and 1 to 3 tasks, reviewed by one grounding critic
inputs:
  request:
    description: What the change should do
    required: true
runs-on: agents
steps:
  - uses: prompts/scaffold-light.md
    runs-on: session
    with:
      request: ${{ inputs.request }}
  - uses: prompts/spec-review.md
    with:
      lens: prompts/grounding.md
  - uses: prompts/spec-triage.md
    on-fail:
      uses: prompts/fix-spec.md
      with:
        on_decision: "escalated: run /theway:engineering without --light for this request"
    tries: 1

1. Load: the same as without --light.
2. scaffold-light, in your session: the scaffold-light prompt, which reads scaffold-rules, tamm-framework and spec-investigation first.
   • Series: a light change is never a series member: a series request answers blocked before anything else, writes nothing, and tells you to run /theway:engineering without --light.
   • Change folder: it validates the change ID with theway validate-id <change-id>. It must exit 0 before any folder is written.
   • Investigate: as without --light; what it learns goes into the spec's Evidence. For a fix- change, it reproduces the bug first and has the same three stop outcomes; after a stop, run /theway:engineering --light again with the new information. A question the investigation cannot settle is a decision, and escalates.
   • Escalation check: it escalates when the investigation finds a decision to make, a public contract change, a TAMM risk at Medium or High, or a request for a series, and when the request contradicts a standard. It writes no change file and answers blocked with escalated: <what was found>; run /theway:engineering <request> without --light.
   • Documents: the light-spec-template prompt produces spec.md, with **Mode:** light under its title; the change-template prompt produces change.yaml, with 1 to 3 tasks, checked with theway change <change-id>. In a fix- change, task 1 writes the regression test. A light change has no design.md.
3. spec-review: one grounding critic, which also reports a spec or task that contradicts a standard.
4. spec-triage: as without --light, except that a confirmed decision escalates: the light files stay, and fix-spec answers blocked with escalated: run /theway:engineering without --light for this request, followed by each question; that command writes over them.

OutputCopy Anchor Link

Everything is written under <home>/projects/<key>/changes/<change-id>/:

• spec.md: **Mode:** light, then Problem, Evidence, Change and Success Criteria.
  • Problem says what is wrong or missing; for a fix- change, also the cause, with file and line evidence.
  • Evidence holds the findings; for a fix- change, the reproduction (command, observed output, expected result).
  • Change lists each file and what changes in it, and ends with "Nothing else changes.": it is the change's scope.
  • For a fix- change, the first two Success Criteria are always the same: the regression test fails before the fix and passes with it, and the reproduction no longer reproduces.
• change.yaml: the description and 1 to 3 tasks.

The run's report is the same as without --light. An escalation reports what was found and the command to run.

DownstreamCopy Anchor Link

The change's prompts read **Mode:** light: the run of /theway:workflow proves a light fix- change's regression test without the base-commit worktree (fix checks), the test running before the fix and failing, then after it and passing; it reviews it as any change, and the conformance lens prompt checks the diff against the Change section.

CustomizeCopy Anchor Link

The engineering workflows are files under the theway home like any other, so a project changes them with its own copies under <home>/projects/<key>/ (see Workflows):

• Add a critic: write its lens as a prompt, for example <home>/projects/<key>/prompts/security.md, and add it to the matrix in a project copy of engineering.yaml:

  Copy Text

  # <home>/projects/<key>/workflows/engineering.yaml, the shipped file with one more lens
    - uses: prompts/spec-review.md
      matrix:
        lens: [prompts/grounding.md, prompts/implementability.md, prompts/security.md]
      with:
        lens: ${{ matrix.lens }}

• Override a template: a project prompts/spec-template.md replaces the shipped one for that project; the scaffold reads it by path.

• Another model, more fix rounds: set model on the step, or in a project copy of its prompt's header; raise tries on spec-triage for more fix rounds. To skip the review, use a project copy of the workflow without spec-review and spec-triage.

• Run the scaffold through an agent: remove runs-on: session from the scaffold step; its prompt's header sets model: opus.