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 <date>; next: <first milestone>").
- **`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.