Who writes the spec when the work is internal refactors?

Tares writes it with you in a spec session. You run tares factory spec in the repo, and the session interviews you one question at a time. It then writes the spec, the plan, the project’s AGENTS.md and the milestones with their acceptance checks, which the crew builds from. Internal refactors go through the same session as any other work.

How it works

The spec session is a Claude Code session that starts when you run tares factory spec in your repo. You describe the work, for example the refactor you want, and it asks you questions one at a time.

When the interview ends, the session produces four things and stores them in Tares:

• The spec, a statement of what the project must achieve.
• The plan, the route to get there. A second model challenges the plan before it is stored.
• The project’s AGENTS.md, the instructions every session that builds the project reads.
• Milestones, each with acceptance checks that say when the milestone is done.

At the end, the session asks whether to hand the project to the crew. When you say yes, the orchestrator picks it up and starts a builder for the first milestone. In the worked example in A project, end to end, the spec session produced a spec, a plan, an AGENTS.md and three milestones. The first covered tests and CI, the second kept payout history stable, and the third covered merge and deploy.

The plan can grow after the spec. If the reviewer finds smaller issues outside the ticket it reviews, the orchestrator turns them into a new ticket and places it in the right milestone.

Set it up

The steps below follow the order the factory expects. Steps marked local apply to a local Tares, and steps marked cloud apply to Tares Cloud. The full walkthrough is in Get started.

1. Check that Claude Code is signed in, that gh is signed in with write access to the repos the crew works in, and that git, jq and curl are installed.

gh auth login

2. Install the CLI.

uv tool install tares     # or: brew install glassflow/tap/tares

3. Local only: start Tares.

tares up

4. Local only: in a second terminal, start the MCP endpoint every crew session shares.

tares mcp --transport streamable-http

5. Cloud only: sign in and pick your workspace in the browser.

tares login

6. Give Tares access to GitHub. On a local Tares, use Settings > GitHub. On Tares Cloud, use Connect GitHub.
7. Bring up the crew.

tares factory crew up

8. Run the spec session from your repo and describe the refactor in the prompt.

tares factory spec "what you want to build"

9. Answer the questions one at a time. Say yes at the end to hand the project to the crew.

What you get

• A written spec and plan that you shaped by answering questions, rather than documents you have to draft.
• A project AGENTS.md that every session building the project reads.
• Milestones with acceptance checks, so each stage of the work has a stated definition of done.
• A project page in the console. Its Docs fold holds the starting prompt, the spec, the plan and the AGENTS.md. Its Tickets fold lists the milestones with their acceptance checks. Open All docs to edit any of them.
• A record of your answers. Every question the crew asks you later goes into the Decisions fold in your own words, up to 4,000 characters per answer. Choices the crew makes on its own are listed in the Assumptions fold, and the orchestrator brings them to you at the end of each milestone.
• A build you can follow. Open the Crew page at http://127.0.0.1:8787/crew on a local Tares to see each station, its state and the projects it holds.

When something else fits

• If you want to change direction while a project is building, talk to the orchestrator instead of starting a new spec session. It answers the builders and brings you what needs you.
• To pick up a finished project again, hand it to the crew again, for example with a follow-up spec.
• The software factory for Claude Code requires Claude Code. If you do not use it, the spec session is not available to you.

Related