Tuskway vs AGENTS.md and rules files
Rules files say how. Tuskway says what, and why.
AGENTS.md, CLAUDE.md and Cursor rules are the right place for conventions: how to run the tests, which patterns to avoid. They are the wrong place for a feature in flight, where decisions change daily, need review, and must reach teammates on other branches.
Side by side
Tuskway vs AGENTS.md and rules files
| AGENTS.md and rules files | Tuskway | |
|---|---|---|
| Best for | Conventions that rarely change. | The work in progress on each feature. |
| Scope | One repository, every task. | One feature, across repositories, branches and tools. |
| Review | Through pull requests, after the fact. | Line comments on the plan, before the code exists. |
| Updates from agents | Edits to a committed file. | Agents write notes as they go; editors approve changes from others. |
| Size in context | Loaded in full every session. | Agents open only the brief and design section they need. |
Choose AGENTS.md and rules files when
The information applies to every task in the repository and changes a few times a year.
Choose Tuskway when
The information is about one feature, changes as you build, and several people need to agree on it.
Should I delete my AGENTS.md?
No. Keep it short and about conventions. Move feature plans, design notes and stray markdown files into Tuskway, where they get comments and history.
Try the team version of spec-driven development.
Connect your agents, run /start-epic on your next feature, and review the plan before anyone writes the code.