How do I write a spec a Claude Code crew can build docs updates from in a Node/TypeScript app?

Tares writes the spec with you. Run tares factory spec with a one-line idea in your Node/TypeScript repo, and /tares:spec interviews you one question at a time. A second model attacks the plan, and the result lands in a Tares project as a spec, milestones, tickets and an AGENTS.md. You then hand the project to the crew, which builds the tickets into pull requests merged on main.

How it works

You do not draft the spec by hand. /tares:spec is a Claude Code skill that runs the planning conversation for you.

• One question at a time. The interview asks a single question per turn, so you answer about your docs updates in small steps instead of writing a long brief.
• A second model attacks the plan. Before anything is saved, a second model challenges the plan, so weak points surface while they are cheap to fix.
• The plan is written to Tares. Tares creates a project holding the spec, milestones with acceptance checks, tickets with a working doc each, and an AGENTS.md.
• You decide on the hand-over. The interview ends by asking whether to give the project to the crew. If you say yes, the orchestrator picks it up.

The crew is an orchestrator, a reviewer and builders, with an optional releaser. Builders are started per milestone and repo. Each builder takes a ticket, works on its own branch, opens a pull request and merges it once the reviewer passes it and CI is green. Tares keeps the plan, tickets, reviews and your answers, so a crew that restarts carries on where it stopped. The Get started page covers the full crew.

For a Node/TypeScript app, tsconfig.json marks the repo as TypeScript and package.json marks it as JavaScript. tares factory doctor reads those manifests and tells you whether Claude Code has a language server for each. With one, builders and the reviewer can find definitions, references and callers instead of searching text.

Set it up

1. Check the prerequisites: Claude Code signed in on a plan that allows background sessions, gh signed in with write access to the repo, and git, jq and curl installed.

2. Install the CLI and start Tares locally. On Tares Cloud, run tares login instead and skip the MCP step.

   uv tool install tares     # or: brew install glassflow/tap/tares
   tares up                  # console on http://127.0.0.1:8787

3. On a local Tares, start the MCP endpoint in a second terminal. Every crew session reaches Tares through it.

   tares mcp --transport streamable-http     # http://127.0.0.1:8788/mcp

4. Give Tares access to GitHub, so it can read each ticket’s pull request, CI and merge state. On a local Tares add a token or App under Settings > GitHub. On Tares Cloud choose Connect GitHub.

5. Bring up the crew. The first run asks how far the crew may go, such as merging on its own after review and green CI or waiting for your yes.

   tares factory crew up

6. From the root of your Node/TypeScript repo, or a folder that holds its repos, start the interview with a one-line idea that names the docs work.

   tares factory spec "what you want to build"

7. Answer each question as it comes. Name the docs you want changed and what done looks like for each milestone, because the acceptance checks come from your answers. Read the attack on the plan and decide what to change.

8. If you want the tickets in GitHub Issues, say so during the interview and name the repo. Claude creates the issues with gh and links them. Sign in with the repo scope first. For Linear, connect it in Settings > Linear, then click Use a Linear project on the project’s Tickets page.

9. Say yes when asked whether to hand the project to the crew. Answer its questions in the orchestrator’s session.

   tares factory crew attach orchestrator

10. Run tares factory doctor at any point to check everything the crew needs, including language servers for your repo.

What you get

• A Tares project that holds the spec, milestones with acceptance checks, and tickets with a working doc each.
• An AGENTS.md that the crew’s sessions share.
• A plan that a second model has already challenged, so you review a tested plan instead of a first draft.
• Pull requests built by the crew, reviewed to a fixed bar and merged on main once CI is green.
• A single place to answer questions: the orchestrator asks them one at a time, each with a recommendation, and the Crew page in the console shows progress.
• A record that survives restarts, including the assumptions the crew made and your answers in your own words, so you can check them at the end of each milestone.

When something else fits

• For a small change, run tares factory session with your idea. It plans a short spec and ticket list and builds it in your own Claude Code session, and it offers the full spec and crew hand-over if the plan turns out big.
• The software factory is for solo developers and very small teams who already work with Claude Code. It runs on one machine, on your own Claude Code login, against your own GitHub repos.

Related