new-project
Use when the user asks to start, scaffold, or spin up a new project — a new repo, a new client or advisory engagement, or a new piece of work that needs its own agent.
SKILL.md.claude/skills/new-project/SKILL.md
GitHubScaffold a New Project
Create a fully set up project from scratch — GitHub repo, Claude Code configuration, documentation structure, registry entry, and a live session working on the first task.
Finish the job. The user asked for a project, which means a repo they can work in and an agent already on the first task — not a repo plus a list of things left for them to do. The last step is a running session with its goal, not instructions.
Steps
1. Gather only what you can't determine
Ask for what genuinely changes the work, in ONE batched message. Default the rest and say what you defaulted.
- Project name — repo name, directory name, tmux session name.
- What it is — enough to write an honest Overview. If the user has already described it (a brief, meeting notes, a linked doc), you have this; don't ask again.
- Language/stack — or none, for a docs-only or research project. "None" is a real answer; don't invent a stack to fill the template.
Default without asking, and state the default in your reply:
| Thing | Default | Override when |
|---|---|---|
| Visibility | private | The user says public, or it's an open-source utility |
| Linear | skip | The user asks for it. Only 8 of 24 registry projects use Linear — it is the exception, not the norm |
| Ship skill | ship-auto |
Advisory or team-owned repo → ship-push-only; production tool the user depends on → ship-guarded |
| Path | ~/dev/<project-name> |
Never, unless the user names one |
respawn |
true |
The project is a one-off with no ongoing work |
2. Create the GitHub repo
Use the gh CLI — the GitHub MCP plugin is unreliable for private and new repos (see docs/process/learnings.md).
gh repo create <owner>/<project-name> --private --description "<one-line>" --clone=false
git clone git@github.com:<owner>/<project-name>.git ~/dev/<project-name>
The clone at ~/dev/<project-name> is the project's permanent home. Everything after this reads from there.
Local-only projects (a synced Drive folder, a scratch dir) skip this entirely — no repo, no repo: field in the registry, and no git commands ever. See the registry section of the root CLAUDE.md.
3. Scaffold from templates/
Copy from this skill's templates/ directory:
| Template | Destination |
|---|---|
templates/settings/settings.json |
.claude/settings.json — add language plugins (pyright-lsp for Python, typescript-lsp for TS) |
templates/settings/settings.local.json |
.claude/settings.local.json — compaction ceilings, untracked |
templates/gitignore |
.gitignore |
templates/docs/process/learnings.md |
docs/process/learnings.md |
templates/docs/process/retrospective.md |
docs/process/retrospective.md |
templates/docs/process/process.md |
docs/process/process.md |
templates/docs/product/decisions.md |
docs/product/decisions.md |
templates/docs/product/vision.md |
docs/product/vision.md |
CLAUDE.md is different — templates/docs/CLAUDE.md.tmpl is an outline, not boilerplate. Write it from what you actually learned about the project. A CLAUDE.md of filled-in placeholders costs every future session tokens and teaches them nothing; cut any section you can't write honestly.
Compaction ceilings: the template ships assistant values (500000 / 80 → compacts at 400k). For a builder — a project that will run long implementation sessions — use 480k). Env is read at session start, so this must exist before step 6 spawns the session.600000 / 80 (
Do NOT copy skills or rules. The team-lead-fleet plugin provides them fleet-wide; a local copy just goes stale.
Also drop in any source material the user gave you — meeting notes, a brief, a spec. Commit it verbatim under docs/ as the primary source, so downstream analysis cites the original rather than your summary of it.
4. Commit and push
cd ~/dev/<project-name>
git add -A && git commit -m "Initial scaffold: <one-line>" && git push origin main
5. Register the project
Invoke /add-project, or append to registry.yaml directly. Required fields:
<project-key>:
type: personal | advisory | client
ship_method: ship-auto
path: ~/dev/<project-name>
repo: <owner>/<project-name> # omit entirely for local-only
respawn: true
session_name: "Display Name" # tmux session + agent display name
docs:
learnings: docs/process/learnings.md
retros: docs/process/retrospective.md
decisions: docs/product/decisions.md
claude_md: CLAUDE.md
skills_dir: .claude/skills
rules_dir: .claude/rules
registry.yaml is gitignored — never commit it. Adding the project here also makes its name a denylist term for the pre-push leak gate on the public repo, which matters for client work.
6. Spawn the session and hand off the goal
python3 .claude/skills/respawn-sessions/respawn.py --mode missing --execute
missing mode spawns only what isn't already running, so it's safe to run with the fleet up. Confirm the pane shows the session name and the /rc marker.
Then send the first task via claude-hive send_message: the outcome, who reads it, the deadline, where the source material is, and any constraint that genuinely narrows the answer. No step-by-step checklist and no "report back when done" — see feedback_delegating_to_peers and feedback_dont_wire_in_status_reports.
7. Report to the user
The repo URL, what you defaulted, what the session is now working on, and anything you deliberately left out. One short message — they don't need the file list.
Principles
- Fast and complete. Zero to a working project with an agent on the first task, in one invocation.
- Plugin first.
team-lead-fleetis the source of fleet skills and rules — never copy them in. - Default, don't interrogate. Ask only what changes the work; state every default you took so the user can correct one cheaply.
- Honest scaffolding beats complete scaffolding. A missing section is fixable; a section of confident filler has to be detected first.