init-project git:20260828.20c0ba5A

Immutable. This exact content is served forever at /api/v1/blob/97c85bf635887f6f.

---
name: init-project
description: Use this skill to turn an idea into a structured new repo. It runs a trigger gate (throwaways and single scripts skip it), a value gate over fed-in discovery, records a foundation (an ADR plus a reference.md golden path), authors a walking-skeleton spec via new-spec and hands the build to work-loop, then hands off to the normal build loop. Triggers on "start a new project", "greenfield init", "idea to repo", "bootstrap a new codebase". Do NOT use inside an existing repo (use adapt-to-project) or to author one feature (use new-spec).
metadata:
  boundaries: [filesystem_read_untrusted, filesystem_write]
---

# Skill: init-project

The greenfield front door. An idea arrives and there is no repo yet — no
foundation recorded, no first slice built. The temptation is to *yolo* a
throwaway prototype, get it sort-of working, then retrofit structure and lose
the rationale. This skill gives that path a home: it turns an idea into a
structured repo by **composing the skills the repo already owns**. It
orchestrates; it does not reinvent, and it is **not** an autonomous code
generator — the human stays in the loop and the existing skills do the work.

It is the twin of `adapt-to-project` (the brownfield front door, for an
*existing* repo). Both converge on the same downstream loop:
`brief → reference.md → spec → low-level design → work-loop`.

## When to invoke

Invoke when the unit of work is a **brand-new repo from an idea** and there are
real **stack / structure / tooling decisions** ahead — a service, a library, a
multi-component app someone will maintain. The tells: "start a new project",
"bootstrap this idea into a repo", "we're greenfielding X".

Do **not** use it when:

- You are inside an existing codebase → `adapt-to-project` is the brownfield
  front door.
- You want to author one feature from scratch → `new-spec`.
- The thing ahead is a script, a spike, or a throwaway with no real structural
  decisions → the **trigger gate** (stage 1) sends it straight to scaffolding;
  don't force the flow onto it.

## The flow — five phases, fluid not waterfall

The five stages below are **fluid phases of attention, not a waterfall**. You
revisit them as understanding firms up — authoring the walking skeleton
routinely sends you back to amend the foundation, and that's the flow working,
not failing. Each phase practises a **scoped handoff**: it passes the next phase
only the artifacts that phase needs, nothing more.

The skill **composes** existing skills and assets by *reference* — it names them
and hands off to them; it never restates their procedures and never imports
their code.

### 1. Trigger gate — run this first

Before any other work, decide whether the flow even applies:

- **Real stack / structure / tooling decisions ahead?** (Which runtime? How is
  it partitioned? What's the persistence and transport story?) → **continue** to
  stage 2.
- **A script, a spike, or a throwaway?** → **scaffold it directly and skip the
  rest of this skill.** The flow's ceremony is wasted on code nobody will
  maintain.

Worked example. *"A 40-line script to rename files in a folder"* → no
architecture decisions → skip the flow, just write the script. *"A webhook
ingestion service with a queue, a worker, and a datastore"* → real decisions →
continue.

### 2. Value gate — over fed-in discovery

Discovery is **fed in**, never performed here (see anti-patterns). Consume a
discovery shape from one of four upstream sources:

- the `desk-research` skill's output (when the `desk-research` pack is installed),
- an `intent` shaped by `frame-intent` (when the `product-engineering` pack is
  installed) — its `frame → de-risk → decompose` loop hands its leaf in here: at
  `app` scale a feature-level leaf intent *is* a `core` brief,
- a provided PRD, or
- a delivery brief produced by `author-delivery-brief`.

The `product-engineering` source is **optional upstream**, named the same way the
`desk-research` source is — "when the pack is installed". A `core`-only adopter has the
other three and reads this one as a clearly-optional source, not a dangling
reference.

From that input, derive the **business value** and the **MVP**: what outcome
this serves and the smallest thing that delivers it. **Gate on it** — if you
cannot state the business value plainly, *pause and send discovery back
upstream* rather than guessing. Don't paper over a thin idea with a plausible
mission.

The phase's output is the first **brief** (`docs/product/briefs/<slug>.md`, the
artifact `author-delivery-brief` owns) — the *what / why* that the rest of the flow and
the downstream loop read. Hand that brief forward; nothing else.

### 3. Foundation — decide the stack, record the rationale

Choose the stack and architecture, and **record the decision with its
rationale** — a foundation you can hold later work to. Two artifacts:

Before creating either artifact, request two independent semantic destinations
through `work-intake`: `decision-record` for the ADR and
`current-architecture` for the normative golden path. Pass bounded candidates
from the adopter's explicit choice, declared policy or optional configuration,
and established convention to the shipped resolver; consume both
`semantic-surface-resolution.v1` results unchanged. Do not infer that the two
roles share a directory. A mandatory-policy refusal, ambiguity, absence, unsafe
repository locator, or external locator without an approved write adapter stops
that artifact before directory creation, ADR numbering, indexing, or writing.
The catalogue paths below are fallback candidates, not universal destinations.

- **An ADR** capturing *what* you chose, *why*, the *alternatives* weighed, and
  a *re-evaluation date*. Hand the resolved `decision-record` destination to
  `new-adr`; it retains ownership of numbering, filename, index, preview,
  confirmation, and lifecycle. A stack chosen with no recorded rationale is the
  thing to stop and fix before going further.
- **A normative golden path** at the resolved `current-architecture`
  destination. `docs/architecture/reference.md` is the catalogue fallback
  candidate. Instantiate it from the arc42 `reference.md` template the
  `adapt-to-project` skill bundles (the same golden-path template its
  reference-architecture harvest fills) — here you fill it forward from a
  decision rather than harvesting it from existing code. The core methodology
  stays stack-neutral; the chosen stack is *yours*, recorded in the ADR and
  golden path. If the project will deploy, this is also the moment to record the
  **deployment platform** and **where verification tooling will live** in the
  golden-path slots (and the matching one-liners in the `AGENTS.md` infra block)
  — optional grounding the work-loop infra preflight reads if present, never a
  prerequisite.

Hand the foundation forward as the steering every later design conforms to.

### 4. Walking skeleton — author the spec, hand the build to work-loop

Author a **walking skeleton**: a thin, end-to-end slice that links the main
architectural components — the smallest thing that exercises the real wiring
(an inbound request reaching a real datastore through the real transport, say),
not a sketch and not a throwaway. It is **kept and minimal**, held to a real
feature contract.

- Author it as a **single spec via `new-spec`** — one thin slice, with its own
  acceptance criteria and `Shape:`.
- **Hand the build to `work-loop`.** This skill orchestrates; `work-loop`
  executes. Do not build the skeleton here — that would duplicate the loop the
  repo already owns.

If building the skeleton reveals the foundation was wrong, go back to stage 3
and amend it — that's the fluid-phase posture, not a failure.

### 5. Handoff — into the normal build loop

From the skeleton onward, the project runs the ordinary loop:
`brief → spec → low-level design → work-loop`, with `reference.md` in place for
every feature's low-level design to conform to. The greenfield front door has
done its job: a recorded foundation, a validated walking skeleton, and the
normal loop running — instead of a throwaway someone has to clean up later.

## Output rendering

Status list — Lead each row with a status glyph — ● running, ✓ done, ○ idle, ⚠ blocked — status first, one item per line, labels aligned.

## Anti-patterns to refuse

- **Performing discovery / research yourself.** Discovery is fed *in* (stage 2)
  from the `desk-research` pack, an `intent` from `frame-intent` (when
  `product-engineering` is installed), a PRD, or an `author-delivery-brief` brief. This
  skill consumes a discovery shape; it does not own the research phase and does
  not shape product intent itself.
- **Building an autonomous multi-agent "software company" generator.** The human
  stays in the loop and the existing skills do the work. The wins of a swarm of
  agents auto-generating a codebase are survivorship-bias stories; the boring,
  composed, human-in-the-loop path is the one that ships maintainable code.
- **Forcing the flow onto throwaways.** The trigger gate exists to keep scripts
  and spikes on the fast path. A flow that adds ceremony to a 40-line script is
  friction, not discipline.
- **Producing a throwaway prototype in place of the walking skeleton.** The
  skeleton is kept and minimal, authored as a real spec and built through
  `work-loop` — not a sketch you'll discard.
- **Choosing a stack with no recorded rationale.** The foundation's ADR comes
  before the skeleton is authored, so the *why* survives.
- **Treating catalogue paths as the foundation contract.** Resolve
  `decision-record` and `current-architecture` independently through
  `work-intake`; adopter-owned destinations win when policy permits them.
- **Adding a new top-level directory, or importing another pack's code.** This
  skill lives beside the other core skills and composes the rest **by reference,
  not import** — it names `desk-research`, `author-delivery-brief`, the arc42 `reference.md`
  template, `new-spec`, and `work-loop`, and hands off to them. The
  `product-engineering` seam is by reference too: `frame-intent` is named only as
  an *upstream discovery shape this skill receives* (when that pack is installed),
  never imported.
- **Restating what a composed skill already documents.** Reference `new-spec`,
  `work-loop`, and the brief; don't copy their procedures into this file.

## When this skill is wrong

If you're inside an existing repo, this is the wrong door — use
`adapt-to-project`. If the idea is a one-off script, the trigger gate should
already have sent you to scaffold it directly. And if the flow ever feels like
ceremony getting in the way of a genuinely small thing, trust the trigger gate
over the procedure.