Getting started

Create a repository from the template, check your setup, choose your agents, and plan your first project.

This page is the short route. The complete references are in the repository, for the version of the template your project has:

Full GitHub setup checklist Command reference Worked example

What you need

Sign in

Sign in to GitHub once with gh auth login. Each coding agent signs in through its own command-line tool. The workflow reads no tokens: do not put API keys or tokens in a file of the repository.

1. Create your repository

Create a repository from the template and clone it. Then delete documentation/ and .github/workflows/pages.yml: they are this website, not part of your project.

Then set up GitHub. The scripts point out risky changes, but only GitHub can enforce who merges:

The repository setup guide has every setting; Configuration and security explains why they matter.

2. Check your setup

./scripts/doctor.sh

The script checks that the tools above are installed and that the agents you configured can run. It tells you what is missing.

3. Choose your agents

Each role in the workflow has an agent and a model. Set them in .agents/agents.conf, one role per line:

implementer: codex <model>
reviewer: claude <model>

The file lists every role, including the planner and the planning reviewer; Configuration and security explains each one. A different agent for writing and for reviewing is a good default.

4. Plan your project

Write a short description of what you want to build, and start the planning with it:

./scripts/start-planning.sh --description path/to/idea.md

An agent asks you questions and writes the requirements for your approval. It then proposes an architecture and a roadmap in a planning worktree: a separate folder next to your repository, whose path the script prints. Go to that folder, then review the plan, address the findings, and approve it:

cd ../<repository>-planning-project-bootstrap
./scripts/review-planning.sh
./scripts/revise-planning.sh --review <review>
./scripts/finish-planning.sh

Each script ends by telling you the next command. Merge the planning pull request when you are done, then return to your repository and update it:

cd ../<repository>
git pull

5. Build your first feature

From your repository, on the updated main, create the issue of the first roadmap feature. Then let one command take it to a pull request:

./scripts/create-feature-issue.sh F01
./scripts/run-feature.sh <issue>

The run implements the feature, runs your checks, has it reviewed, fixes what the review finds, and opens a pull request. It does not merge. Read the pull request and the decisions about the review findings, then merge it yourself.

To stay closer to the work, run the steps one at a time, starting with ./scripts/start-feature.sh <issue>. The workflow explains each step.

Update an existing project

A repository created from the template does not receive later improvements of the workflow. To bring them over, run this from your repository, with no uncommitted changes:

./scripts/sync-template.sh

It updates only the files that belong to the template, and never commits or pushes. On main it first creates a branch; on another branch it works there, so start from main to keep the update apart from other work. Your code, your plan, and your own checks are not touched. More about updates.

If something goes wrong

A tool is missing, or GitHub is not signed in
Run ./scripts/doctor.sh. It names what is missing.
An agent does not start, or rejects the model
Check the agent and the model of that role in .agents/agents.conf, and that the agent's command-line tool is signed in. The workflow passes the model name on as you wrote it.
A check fails
./scripts/verify.sh prints which check failed and its output. A feature cannot be reviewed or committed until the checks pass.
A script says a review is no longer current
The code changed after the review. Run ./scripts/review-feature.sh <issue> again.
A script says the plan approval is not current
The requirements or the roadmap changed after you approved them. Changes to an approved plan go through the change process.
A session or a run was interrupted
Continue with ./scripts/start-feature.sh <issue> --resume, or run ./scripts/run-feature.sh <issue> again: it picks up where it stopped.

Where to go next