Introduction

theway is a set of Claude Code slash commands for planning and implementing changes in a codebase. It turns a request into a spec and an ordered task list, then implements the tasks, either inline in your session or through agents that open a pull request, run review rounds and drive CI green.

It is for Claude Code users who want the reasoning behind a change written down before its code.

Why spec-firstCopy Anchor Link

/theway:engineering writes only the spec, through the shipped engineering workflow. It investigates the code, settles the unknowns and records what it found, the decisions and their reasons, the risks and the tasks. The code is written later, by /theway:workflow, inline in your session or through agents, from that spec. For a small change with nothing to decide, /theway:engineering --light writes a shorter spec, still before any code.

Writing the spec first means the blockers and alternatives are weighed before any code exists. A spec written after the code describes that code instead of the problem. During implementation, a gap between the spec and the code is brought back to you as a decision, not smoothed over.

Every full spec (/theway:engineering) includes a TAMM hardpoints table that names the Medium and High risks of the change and their countermeasures.

Where things liveCopy Anchor Link

theway keeps its files in a data home, ~/.theway by default, or the folder chosen at install (the install question or --home), or THEWAY_HOME (see Installation). The config is <home>/config.yaml.

Each change is a folder under <home>/projects/<key>/changes/, where <key> is your repository's path with every non-alphanumeric character turned into - (/home/you/code/my-api gives -home-you-code-my-api). The folder holds spec.md, change.yaml (the tasks) and, when needed, design.md and notes.md. A finished change moves to changes/archive/, so the history of every change stays in the data home. See Changes.

Your own workflowsCopy Anchor Link

/theway:workflow runs a workflow: a YAML file listing the steps of a change, each run in your session or through agents. Each step uses a Markdown prompt and answers pass, fail or blocked; a fail can run a fix and the step again. theway ships its workflows and prompts written the same way as yours: develop (in your session) and agents (implement, review and pull request through agents), and the two engineering workflows. You add your own workflows and prompts in <home>/, or per project. See Workflows.

Next stepsCopy Anchor Link

• Install theway.
• Read How it works: engineering, workflow, archive.