Part 1: Software factory

Make your own copy of the starter

Clone it too. Pick any name:

gh repo create my-link-shortener --private --template glassflow/factory-workshop-starter
gh repo clone my-link-shortener
cd my-link-shortener

You can also open github.com/glassflow/factory-workshop-starter  and click Use this template. GitHub runs CI on your copy by itself; it should pass.

See what the app does today

Start it in your repo folder:

uv sync
uv run uvicorn app.main:app --reload

In another terminal, make a short link and keep its code in CODE:

CODE=$(curl -s -X POST localhost:8000/links -H 'content-type: application/json' -d '{"url":"https://glassflow.ai"}' | jq -r .code)
echo $CODE

You should see a 6-character code. Open it:

curl -i localhost:8000/$CODE

You should see HTTP/1.1 307 Temporary Redirect and location: https://glassflow.ai/. Now try the stats endpoint the crew will build:

curl localhost:8000/links/$CODE/stats

You should see {"detail":"Not Found"}: it does not exist yet. Leave the app running; you use it again in step 13.

Start Tares

In a new terminal:

tares up

The console opens at http://127.0.0.1:8787 . Leave it running.

• By default Tares listens on port 8787 and keeps its data in ~/.tares.
• Already have a Tares on 8787, or want a clean one? Pick another port and folder: tares up --port 8797 --data-dir ~/tares-workshop. Then add --taresd http://127.0.0.1:8797 to the command in step 4, and run export TARESD_URL=http://127.0.0.1:8797 in every terminal you use for tares factory commands. Read 8797 wherever this guide says 8787.

Start the MCP endpoint the crew talks to

In another terminal:

tares mcp --transport streamable-http

It listens on port 8788. Leave it running.

Check everything

Back in your repo folder:

tares factory doctor

You should see ok on every line except two: “Claude Code has not trusted the crew home” (FIX) and “no crew yet” (warn). Starting the crew in step 7 clears both.

Give Tares access to GitHub

So it can follow your pull requests, CI and reviews by itself.

• Copy the token gh already holds:

  gh auth token

• In the console at http://127.0.0.1:8787 , open Settings, then GitHub, and click Add a personal token.

• Name: github. Token: paste what gh auth token printed. Save.

Without this the crew still works, but it checks GitHub itself and Tares does not show the pull request state.

Start the crew

tares factory crew up

• It asks to open Claude Code in the crew’s folder: pick 1. Yes, open it. In Claude Code pick Yes, I trust this folder, then type /exit.
• Then it asks five questions, one per tab. Pick:
  • Merging: The crew, once its reviewer approves and tests pass
  • Releasing: No, it stops when work is merged to main
  • Codex check: No (pick Yes only if you have the Codex CLI signed in)
  • Builders: 1 (not the recommended 2: one builder is enough for this feature and saves your plan’s limits)
  • Grants: Nothing more
• On Your answers, pick Save and start the crew.

You should see “started crew-orchestrator”, “started crew-reviewer” and “started the watch”. About 2 minutes. The crew now waits for work: the orchestrator hands projects to builders, and the reviewer reviews every pull request.

Plan the feature

In your repo folder:

tares factory spec "add a click counter: count each redirect and show it at GET /links/{code}/stats"

Claude Code opens in a new spec session; trust the folder if asked. It reads the repo, then asks one question at a time, each with a suggested answer. In our run it asked four:

• The goal and the project name. Accept the suggestion.
• What the stats endpoint returns, for example the code, the URL, the click count and the time of the last click. Accept the suggestion, and add: keep it small: two tickets at most, one milestone.
• Who builds it. Pick the tares-factory crew.
• Where the tickets live: Linear or Tares. Pick Tares.

It then writes the plan to Tares: a spec, one milestone with its checks, and two tickets. About 7 minutes. Short on time? Use the ready-made spec instead.

Hand the plan to the crew

The spec session ends with “Hand this to the orchestrator now?”. Say yes.

• The spec session tells the orchestrator there is a new project, with your repo.
• The orchestrator starts a builder: a new Claude Code session that works in your repo, one ticket at a time.
• From here the crew owns the project. Type /exit to close the spec session; you do not need it again.

Watch it build

You can follow it in three places.

• The Tares console. Open http://127.0.0.1:8787/crew .

  • The crew shows the orchestrator and the reviewer.
  • Under Projects is your project and its builder. Click it.
  • The project page has four columns, Spec, Build, Review and Done, with each ticket and its pull request.

• GitHub. Your repo gets one pull request per ticket. The builder opens it, the reviewer reviews it, CI runs, and the builder merges it. In our run the first ticket merged 7 minutes after the hand-over and the second 5 minutes later.

• The crew’s own sessions. Open the orchestrator in your terminal:

  tares factory crew attach orchestrator

  To see the builder at work, run tares factory crew status to find its name (it ends in -build-m1), then tares factory crew attach <that name>. Only watch the builder; it needs no input from you. To leave any session and keep the crew running, press ← (Claude Code shows its list of sessions), then Esc.

Say it is done

When both tickets are merged, the project page shows “1 question waiting for you”: “Is it done?”. Answer it in the orchestrator’s session (tares factory crew attach orchestrator): type A. Then press ← and Esc to leave it.

Look at what Tares kept

Open the project in http://127.0.0.1:8787/crew : the spec, the milestone and its checks, both tickets in Done with their pull requests, and the reviewer’s verdict on each.

Try the feature

In your repo folder, get the merged code and run the tests:

git pull
uv run pytest

You should see every test pass, including the new click tests. The app from step 2 reloads by itself after git pull, and it starts with no links, so make a new one and open it twice:

CODE=$(curl -s -X POST localhost:8000/links -H 'content-type: application/json' -d '{"url":"https://glassflow.ai"}' | jq -r .code)
curl -s -o /dev/null localhost:8000/$CODE
curl -s -o /dev/null localhost:8000/$CODE
curl -s localhost:8000/links/$CODE/stats

You should see your code, the URL and "clicks": 2. If the app is no longer running, start it again with uv run uvicorn app.main:app --reload.