Creating a project

A project can start from a tech spec instead of a repository with code. Pitwall files its first ticket, KEY-1 · Create the project, and runs it: your runner creates the repository on GitHub with your own login and commits the spec, an agent sets the project up from it, and you merge its pull request. The project is then at milestone 01, ready to plan.

The quick path

1. Open New project and choose From a tech spec.
2. Paste or drop the tech spec, and add the files it came from: designs, briefs, notes, a zip.
3. Name the project, which suggests its key, and give the repository as owner/name. It is private unless you turn Public on.
4. Pick one of your runners marked can create repositories, and press Create project.
5. Answer the agent’s questions in the inbox or on Telegram, then review and merge its pull request.

From a terminal, the same is pitwall project create (pitwall CLI).

Three ways in

You have	Choose	The repository
A tech spec, pasted or as a file, and its files	From a tech spec	Created by your runner, or an empty one you name
A repository with a tech spec and no code	From a repository with a tech spec	Read as it is
A planning chat that wrote a tech spec	Create project, in the chat	Created by your runner, with the chat’s files

A repository that already holds code is added with Add an existing repository instead: creating a project there is refused.

What happens

The project’s Overview reads being created while KEY-1 runs, through four stages:

Stage	What happens
seed-repo	Your runner creates the repository if it does not exist and commits the spec and its files to the default branch, as one commit, Add the tech spec. It says what it did
init-project	An agent checks the spec, moves it to docs/tech-spec.md and the files to docs/inputs/, and writes the project’s structure: CLAUDE.md, README.md, docs/progress.md, its first ADRs and specs/
pull request	The agent opens a pull request with all of it
merge	You merge it. KEY-1 is done

The agent asks what a person setting the project up by hand would: a gap in the spec, a file the spec does not mention, an alternative an ADR needs, whether the milestone list is right. Each question waits in your inbox and on Telegram.

Nothing reaches the default branch but the files you gave, until your merge.

What the runner needs

The runner must be yours, and gh must be logged in on it: it creates the repository with that machine’s GitHub login. pitwall-runner doctor says whether it is (Runners). The GitHub App must be installed on the account or organization the repository goes to, or the pull request cannot be opened.

When it stops

repository_has_code and unreachable block the run at once: another attempt would find the same. The others fail one attempt, and the run blocks after three.

The run says	Means	Do
repository_has_code	The repository holds code: a build manifest, a lockfile or a source tree	Add it as an existing repository instead
gh_unavailable	The runner’s gh is missing or not logged in	Run gh auth login on it, then resume the run
repository_create_failed	GitHub refused to create the repository	Check the name and your access, then resume
unreachable	The GitHub App cannot see the repository	Install the app on it (Connecting GitHub), then resume

After the merge

The Overview lists the project’s milestones, the first one not planned yet. Plan it in a terminal with the pitwall-milestone-md skill and push; Pitwall then runs it (Milestones). The repository needs nothing from Pitwall to be continued in a terminal.