A spec-first workflow
for Claude Code

How it works

1. Write the spec before the code

   /theway:engineering investigates the request, then writes spec.md and change.yaml, and critic agents review them. No code is written in this step: it is the shipped engineering workflow, whose steps and prompts you can change.

   > /theway:engineering add rate limiting to the public API

   ● Bash(theway context engineering)

   ● Read(src/api/router.ts)

   ● Write(~/.theway/projects/-home-you-code-my-api/changes/add-rate-limit/spec.md)

   ● Write(~/.theway/projects/-home-you-code-my-api/changes/add-rate-limit/change.yaml)

   ● Spec and tasks written. Review them before developing.

   > ▍

   • Facts first

     Questions the design depends on are investigated and written into the spec as findings.

   • TAMM hardpoints

     Medium and High risks across Time, Autonomy, Mastery and Machine, each with countermeasures.

   • Ordered tasks

     change.yaml lists the work as ordered tasks (a light change: 1 to 3 tasks).

2. Implement task by task

   /theway:workflow runs the steps of a YAML workflow: by default it works through the tasks in your session; the agents workflow hands them to agents that implement and review locally, then opens a pull request.

   1

   - [x] 1. Add the limiter middleware

   2

   - [x] 2. Read limits from config

   3

   - [ ] 3. Return 429 with Retry-After

   > /theway:workflow --workflow agents add-rate-limit

   ● Agent(implement add-rate-limit)

   ⎿ committed on add-rate-limit

   ● Agent(review add-rate-limit)

   ⎿ 2 findings, 2 confirmed

   ● Agent(fix add-rate-limit)

   ⎿ 2 resolved

   ● Bash(gh pr create)

   ⎿ PR #42 opened

   ● Bash(gh pr checks 42)

   ⎿ test pass

   ● PR #42 is ready for you to merge.

   • Verified against the spec

     Each Success Criterion is reported with the command or test that verified it, or flagged as unverified.

   • Adversarial review

     Reviewer agents try to break the diff; a fix agent addresses confirmed findings, and a fix check confirms them.

   • CI driven to green

     Failed runs are diagnosed from the real error line, within a set number of attempts.

3. Compose your own workflow

   Write a workflow as a YAML file of steps. Each step uses one of your Markdown prompts, and runs in your session or through agents. /theway:workflow --workflow <name> runs it.

   1

   version: theway.workflow/v1beta

   2

   description: Implement, review with a security lens, audit and open the PR

   3

   inputs:

   4

   change: {description: The change to implement, required: true, type: change}

   5

   runs-on: agents

   6

   steps:

   7

   - uses: prompts/implement.md

   8

   runs-on: session

   9

   with:

   10

   change: ${{ inputs.change }}

   11

   - uses: prompts/review.md

   12

   matrix: {lens: [prompts/correctness.md, prompts/security.md]}

   13

   with:

   14

   change: ${{ inputs.change }}

   15

   lens: ${{ matrix.lens }}

   16

   - uses: prompts/security-audit.md

   17

   with:

   18

   change: ${{ inputs.change }}

   19

   - uses: prompts/open-pr.md

   20

   with:

   21

   change: ${{ inputs.change }}

   • Inline or through agents

     Each step runs in your session, where you can steer it, or through subagents. Mix them: implement it yourself, have agents review it, and open the PR.

   • Steps and prompts you write

     A workflow is a flat list of steps, each using a Markdown prompt that answers pass, fail or blocked, with on-fail to fix and retry and matrix to run copies at once. Add a security-audit step, or a security.md lens to the review, and every change that workflow runs gets it.

   • Your conventions, your git host

     Commit messages, branch names and the git host commands live in commits.md and git-host.md, which you replace per project.

4. Keep the history

   /theway:archive moves a finished change to changes/archive/, dated, and only when you ask for it by name.

   > /theway:archive add-rate-limit

   ● Bash(theway archive add-rate-limit)

   ⎿ Archived: ~/.theway/projects/-home-you-code-my-api/changes/archive/2026-10-28-add-rate-limit

   • Explicit only

     "It's merged" or "ship it" never archives a change: you name the change and ask.

   • No open tasks

     Archiving refuses while a task in change.yaml is not done, unless you accept the open tasks.

   • Dated archive

     Every archived change keeps its spec and tasks under a dated folder.