standards/guides/new-project.md

New-project bootstrap — orchestration guide

Substance file per the portability protocol. Vendor wrappers (e.g. adapters/claude/commands/new-project.md) point here; this guide is self-contained and written as plain prose any orchestrating agent could follow. This is the inverse of guides/retrofit.md: retrofit moves an existing project's brain onto disk; this turns an idea into a repo that is standards-compliant from line one.

You are bootstrapping a brand-new project under ~/Projects. You run in the main thread — scoping a new project is a conversation, not a delegated job — so you talk to the user and ask for the judgment calls. Do not behave like a subagent.

The arc: locate the seed → frame it and confirm it's even a repo → workshop the scope → get the plan signed off → scaffold → publish → close the capture loop. Nothing lands on disk until the scaffold phase, and nothing is created without the user's sign-off at the plan gate. Two gates protect that work: a form-factor gate early (is this even a standalone repo?) and a worth-building gate at sign-off (is it worth the build and the ongoing tax?). Work the phases in order; at each decision point, ask and wait — don't guess on anything that lands on disk.

Posture (how to run the whole conversation)

Be a collaborator, not an interviewer. Propose a draft answer and ask for corrections rather than asking open-ended questions — the user is an expert on his own stack and intent, so a wrong draft he can fix in five words beats a questionnaire. At most a focused question or two per turn; one is better. Mine context before asking anything — the inbox seed, the other repos' conventions, memory, this conversation — and never ask what's already answered. Scale the ceremony to the idea: a one-off script might clear every gate in two turns; a new long-running service deserves the full walk. And push back — if the idea has a fuzzy user, a job an existing tool already does, or a "Phase 0" that's secretly three phases, name it. A workshop that only validates is worthless.

Phase 0 — Locate the seed

• New-project ideas are captured to the cross-project inbox as items tagged (new) or (new:working-name), type project (see ~/Projects/standards/INBOX.md). These are deliberately not drained by /triage — they wait for this command.
• Read INBOX.md and list any (new…) / type-project items. If one matches what the user wants to build (or they passed a name/idea as the argument), use it as the seed and carry its note into Phase 1. If several match, ask which. If none, that's fine — ask the user for the idea directly.
• Settle on a working name early (kebab-case; it becomes the folder and the repo name). Confirm ~/Projects/<name> does not already exist before going further.

Phase 1 — Frame, then the form-factor gate

Before workshopping a repo's scope, confirm it should be a repo. First draft a thin frame — a one-line objective and the single job-to-be-done — just enough to judge form, no more. Then walk the gate:

• What form should this take? Standalone repo / a feature of an existing repo / a skill / an agent / a slash-command / a one-off script. Lean on what already exists: could one of the user's current repos absorb this as a feature far more cheaply than a new repo carries its own lifecycle?
• Does it already exist? Check the user's own repos first, then OSS and the Start9 marketplace. If an existing tool does ≥80% of the job, present the best one or two candidates honestly, including the case for adopting them. The cheapest project is the one you don't build, and finding that out in minute ten beats finding it out in week three.
• Outcome. Only a standalone repo that doesn't already exist continues to Phase 2. If the right home is a feature/skill/agent/command of something that exists, or an existing tool wins, stop and reroute gracefully — re-capture the idea to INBOX.md tagged for the host repo (or point at the skill/agent authoring path), tell the user plainly why a standalone repo is the wrong shape, and don't scaffold. Bailing here is a success, not a failure.

Phase 2 — Workshop the scope (the high-value step)

This is the point of the command — don't rush it to get to scaffolding. Like /roundup, the reasoning is the user's; you're drawing it out, not deciding it. Hold the posture above and work through these a focused question or two at a time:

• Objective & non-goals — what the project is for in a sentence or two, what "working" looks like for v1, and — the cheapest way to keep scope honest — what it explicitly will not do.
• Placement — read ~/Projects/standards/guides/placement.md and walk its decision sequence against this idea: sensitivity/sovereignty, runtime shape, host (Mac vs Start9; if Start9, s9pk vs plain container), model routing, data layer, interface, repo home. Where a call is genuinely contested (s9pk-vs-container often is), surface it with a recommendation rather than picking silently. The resulting placement table seeds AGENTS.md.
• Key early decisions — the one or two architectural forks that are expensive to reverse later. Capture each as a decided call: what was chosen, the alternative it beat, and the concrete condition that would reopen it. This is what lands in AGENTS.md's "decisions already made" section (Phase 4), so the project never needs a separate decision-log file.
• First milestone — the thinnest end-to-end slice that proves the core loop; it becomes the seed of ## Current state. State its exit as falsifiable substance — a number or demonstrable behavior that could actually fail ("recap generated from a real 40-min call in under 2 minutes"), never a checkbox milestone ("set up the database"). If an exit can't fail, rewrite it until it can.

Once these are answered well enough to scaffold, move on — don't pad the conversation.

Phase 3 — Brief + scaffolding plan (sign-off gate)

Synthesize the workshop and show the user three things before creating anything on disk:

1. Project brief — the seed of AGENTS.md: one-paragraph purpose, the placement table, non-goals, the decided architectural calls, and the first milestone.
2. Scaffolding plan — the exact tree you'll create: the standards files (always: AGENTS.md + CLAUDE.md symlink, ROADMAP.md, README.md, the canonical .gitignore), the stack-specific starting files/dirs (kept minimal), and whether any .claude/ wiring is needed yet (usually just the directory — scoped guides come later, as the project grows).
3. Worth-building check — now that the cost is visible, state it honestly: the build effort for the first milestone and beyond, plus the ongoing tax (every running service is a pet that needs updates, backups, and debugging when it breaks at a bad time). Land on BUILD, PARK, or ADOPT. PARK is a respectable outcome — re-capture the idea to INBOX.md with a one-line epitaph (tagged parked) so it isn't lost or re-workshopped from scratch, and stop here.

Get explicit sign-off on BUILD. This is the last gate before disk.

Phase 4 — Scaffold (compliant from line one)

Create ~/Projects/<name>/ and write, matching the standard exactly (portability.md):

• AGENTS.md — from the brief: one-paragraph purpose; ## Stack and a ## Placement table (host, s9pk-vs-container, model routing, data layer, interface — from the placement workshop); ## Commands (stub the commands you expect, marked TODO where not yet runnable); ## Layout; a ## Decisions section listing each architectural call already made, the alternative it beat, and the condition that would reopen it (this absorbs what a separate decision-log file would hold — keep it here, don't spawn an ADR file); the sovereignty constraint stated plainly if the project touches sensitive data (local inference only — never wire a frontier API to payload data); the inbox-check line tagged (<name>) (canonical wording in the standards repo's own AGENTS.md); and an initial ## Current state ("Scaffolded ; next: ").
• CLAUDE.md — a relative symlink to AGENTS.md: run ln -s AGENTS.md CLAUDE.md inside the new dir (never an absolute symlink — it must clone correctly elsewhere).
• ROADMAP.md — seed with the phases beyond the first milestone (each with a falsifiable exit), plus the longer-term ideas and deferred non-goals from the workshop.
• README.md — human-facing: what it is and how to run it (a stub is fine; mark TODOs).
• .gitignore — the canonical block from portability.md's "What git tracks" (deny-by-default .claude/* + the shared-wiring allow-list; .env/.env.*/!.env.example; OS cruft) plus the stack's own ignores (e.g. node_modules/, __pycache__/, build artifacts). Read the block from portability.md so it stays in sync — don't reproduce it from memory.
• .claude/ — create the directory; add settings.json only if a deterministic hook is wanted now. Don't add rules/ symlinks until there's a docs/guides/ file to point at.
• Starting structure — the minimal stack-specific skeleton from the plan; no more.

The stack's quality gate (linter + pre-commit hook) is deliberately not hand-rolled here — that's the future /harden command (standards ROADMAP item 1). Note it as a next step rather than improvising one.

Sweep everything you write for secrets — reference env-var names, never real values.

Phase 5 — Publish (git + Gitea) and close the loop

• git init, stage, and make a single clear initial commit of the whole scaffold.
• Gitea publish gate (reuse retrofit-playbook.md Part 4). Creating the repo on the user's self-hosted Gitea is currently a manual web-UI step — there is no API automation yet (a /new-project Gitea-API enhancement is captured in INBOX.md). So: ask the user to create an empty repo in Gitea's UI (named <name>, no README) and paste its URL back. Then git remote add origin <url> and git push -u origin <branch>. The SSH key is one-time and assumed already set up; if the push fails on auth, point the user at the Part 4 SSH-key prompt. If they'd rather not publish yet, leave it local and say so — never add a GitHub remote.
• Close the capture loop: if this project came from a (new…) inbox item, remove that line from ~/Projects/standards/INBOX.md, then commit and push the standards repo (the same way /capture keeps the inbox durable).

Phase 6 — Verify compliance

Because you're the main thread, fan out portability-checker on the new repo to confirm it's compliant from line one — AGENTS.md canonical with a relative CLAUDE.md symlink, the deny-by-default .gitignore, no absolute in-repo symlinks. Relay only what needs a fix.

Final report

Short summary: the new repo's path, what was scaffolded, commit + push status (and the Gitea URL, or that it's local-only), whether the (new) inbox item was cleared, and the first milestone to start on. If you stopped at the Gitea gate waiting for a URL, make that the unmistakable next action. If you bailed at the form-factor gate or parked at the worth-building gate, say so plainly and where the idea was rerouted. If blocked at any point, report exactly what blocked you — never guess or fabricate.