Skip to content

Tuskway vs design docs in a wiki

A design doc your agents actually read.

Many teams already write a design doc before a big feature, in a wiki or a shared document. That habit is right. The trouble starts when AI agents do the building: the doc sits in a tool the agent does not open, somebody pastes parts of it into a chat, and from then on the agent works from a copy that nobody updates.

Side by side

Tuskway vs design docs in a wiki

 design docs in a wikiTuskway
Who reads itPeople, when they remember to.People and every agent on the team, before they code.
How an agent gets itSomeone pastes it, or connects the wiki and hopes search finds the right page.The agent opens the brief and the design section for its ticket, by name.
StructureOne long page per feature.One section per ticket, so an agent loads only what it needs.
ReviewComments in the margin, resolved by hand.Line comments an agent can work through: it edits the doc, says what changed, and resolves the thread.
Who can change itAnyone with edit access.Editors. Everyone else, and their agents, suggest changes that wait for approval.
Link to ticketsA list of links, kept up to date by hand.Each section maps to a ticket, published to GitHub Issues, GitLab, Linear or Jira.
Staying currentGoes stale once the build starts.Agents note what they changed as they work, with history.

What a wiki is good at

A wiki is the right home for knowledge that many people read and few change: onboarding, architecture overviews, runbooks, decisions that stand for years. It handles rich layout, embeds and wide audiences. Keep those pages where they are.

Where it stops for agents

A design doc for a feature in flight is a different kind of document. It changes daily. Several people need to agree on it. And the reader that matters most is an agent with a limited context window that has to find the one part relevant to its ticket. A single long page makes the agent read everything or guess where to look. A pasted excerpt is out of date by the next comment.

What changes with a shared spec

In Tuskway the design is written in sections, and each section is tied to the ticket it becomes. An agent on ticket T3 reads T3's brief and the section behind it. When a reviewer comments on a line, any agent on the team can pick up the open threads, make the change and resolve them, and the reviewer still has the last word. The spec is reached over MCP from Cursor, Claude Code, Codex, ChatGPT and other tools, so it does not matter which one a teammate prefers.

A worked example

A checkout redesign has a "Payments" section and a "Customer emails" section. A reviewer highlights "each attempt sends its own idempotency key" and comments that keys should expire after 24 hours. An agent processes the comment: it adds the expiry rule to the section, replies with what it changed, and resolves the thread. The agent that later builds the payments ticket reads the section with the expiry rule in it. Nobody copied anything between tools.

Choose design docs in a wiki when

The document is long-lived reference material, read mostly by people, and nobody builds from it directly.

Choose Tuskway when

The document describes a feature being built now, agents write the code, and the team wants to review the plan first.

FAQ

Good questions.

New to the idea? Read what spec-driven development is.

Can we keep our architecture docs in the wiki?

Yes, and you should. Tuskway is for the feature in progress. Link to the wiki page from the epic's notes when it helps.

Can an agent import an existing design doc?

Yes. Give it the document as context and ask it to run /start-epic and then /write-design, which splits the design into sections.

Can non-developers review a design in Tuskway?

Yes. Guests read and comment in the browser at no cost, and do not need an AI tool.

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.