---
name: scaffold-project-spec
description: "Partial Skill: invoke by name only — lay out an SDD project-spec"
user-invocable: false
---

# scaffold-project-spec — lay out a project's spec

The procedure the **conductor** follows, **once at bootstrap**, when `start-mission` explore finds a project
with **no spec yet**. It chooses *how the spec is organized*, scaffolds that skeleton, and
**declares the choice**, so the per-unit explore that follows (`spec-producer-governance`) slots work into known
homes. It is **internal** — reached through `start-mission`, never a user entry — and leaves the tree at
`status: draft`; it authors no node's `## Use Cases`/`.feature`, renders no gate verdict, and freezes nothing.

**Load `sdd:spec-structure-governance`** for the layout law it applies: the node taxonomy (three
spec-types, the concept axis), the two-level depth cap on capability nodes, screaming architecture and the
non-capability folders, root-files-not-folders, and the colocate-or-hoist test. This skill does not
restate that law — it **runs** it, and owns only what is genuinely its own: the **strategy menu**,
the **shared envelope**, and the seven-step procedure below.

Run the seven steps in order, surfacing each choice to the user (recommended-first), never assuming
silently.

## 0 — Pick the evidence mode

**Detected, not chosen.** Ask one question of the tree, not of the user: **does this project have source to
read?** Scope it to the **project**, never the repo — a new package inside an existing monorepo is a
greenfield *project* in a populated *repo*.

- **detection mode** — the project's source exists. Steps 1-3 read it.
- **intent mode** — the project's source does not exist yet. Steps 1-3 have nothing to read for it, so they
  run off what the user states the project *will* be.

**The repo around an intent-mode project is still readable**, and reading it is not a mode switch: an
existing monorepo's shape, conventions, and sibling packages inform the recommendation even when the
project itself is empty. Intent mode means *this project* has no source — not that the disk is blank.

Steps 4-6 are identical under both modes. Never run detection's signal-reading against an empty project and
never let intent mode fall through to a silent default.

## 1 — Establish the project shape

**Detection mode** — read signals, do not guess: an **agentic plugin** (`.plugin/` + `skills/` + `agents/`);
a **monorepo** (`apps/`+`packages/`, or multiple package anchors each with their own manifest); whether
`src/` is **feature-** or **layer-organized**; framework markers; owners (`CODEOWNERS`); size.

**Intent mode** — the project has no signals of its own. Establish by asking (reading the surrounding repo
where it helps) the three things detection would otherwise have read:

1. **What kind of project** — a repo harness, an agent plugin, an npm package, a website, an app
   (`project-unit.md`). This is what the plugin/monorepo/plain classification stood for.
2. **Where it will live** — the repo-relative dir its source will occupy. This is the **`project-path`** step
   5 must write, and in a greenfield project that directory does not exist yet, so it can only be asked.
   Confirm it rather than inventing a path.
3. **What it will do** — the intended capabilities, which step 3 recommends a strategy from.

(2) gives the `project-path`; (1) decides the **location**, per step 2 — nesting does not.

## 2 — Choose the spec location

Recommend, let the user override, never assume:

**Colocate by default.** Hoist only when the spec **cannot be kept out of what ships** — nesting alone is
never the reason.

- **`<project>/.agents/spec/`** (colocated).
  An npm package colocates fine: `files` / `.npmignore` excludes `.agents/` from the tarball.
- **`<repo>/.agents/specs/<name>/`** (hoisted — named by the package). Only when the project dir is
  distributed **wholesale**, with no include/exclude mechanism to leave the spec behind. The one identified
  case is an **agentic plugin**: plugin install distributes the whole plugin directory, so a colocated spec
  would ship to every consumer. If a new packaging format has the same all-or-nothing distribution, it joins
  this case; otherwise colocate.
- **monorepo** — offer to lay out **every package** (each hoisted to `<repo>/.agents/specs/<name>/`) plus the
  outer project (`<repo>/.agents/spec/`). Run steps 1–6 **per selected project**, producing several draft
  trees (the evidence mode is picked once, in step 0, for the whole run).

In **intent mode** apply the same test to the **kind of project** established in step 1: an agentic plugin
hoists, everything else colocates at the `project-path` given. Confirm with the user; never re-ask location
as an independent choice, and never hoist merely because the path is nested.

## 3 — Recommend + choose the strategy

Present **one recommendation + its rationale + the alternative**; the user chooses. Shipped menu:

- **capability-first** *(default)* — top-level folders by what the project *does*. Recommend when a capability
  decomposition is discernible. For a fixed-layout plugin this is a spec-side abstraction over fixed source —
  accepted for legibility; name the spec↔source divergence as a known cost.
- **mirror-source** — spec nodes track the source tree. Offer whenever the team **navigates by code**;
  a **feature-first** `src/` is the best case, not a precondition. Over a **layered** source, still
  offer it — but name the cost: the folder partition is coarse, so the scheduler sees more collisions
  and the schedule is slower (never wrong — an unresolved collision serializes, `sdd:spec-structure-governance`).
  Say what recovers it (the collision ladder resolves most shared-node pairs at the file or symbol
  rung) and what the exit looks like (concept tags accumulate; hoist a capability when the
  false-conflict rate earns it). Mirror is **boundary-aligned** (step 4). **Detection mode only** —
  there is no source tree to mirror in intent mode.

**Offer to measure, rather than argue.** In **detection mode** on a repo with real history, offer to
run `sdd:check-partition-quality` before the choice is made: it reports, from this project's own
commits, how much parallel work each candidate layout would permit. Opt-in — it reads `git log`, so
it is slow on a large repo and says nothing useful on a young one, and it renders no verdict. When it
runs, present its parallelizable shares alongside the recommendation so the user chooses on their own
numbers rather than on doctrine. Skip it silently in intent mode: a greenfield project has no history
to measure.

**Do not require a restructuring before the first spec.** An existing project adopting SDD keeps the
shape it has; capability-first is the destination, reached on evidence, not an entry toll. Recommend
capability-first, accept mirror-source with its cost stated, and let the data drive the migration.

In **intent mode**, recommend from the capabilities the user stated in step 1. If they have not stated any,
**ask for them** — never apply the capability-first default silently. (Detection mode's no-signal fallback
*is* the capability-first default; intent mode has no equivalent, because a greenfield project always has an
intent to state.)

Never offer **layering** or **arc42 sections** as the *top* level — they nest *inside* a capability. **ADR is
not a strategy** — it is the decisions facet (step 4). The deferred strategies (bounded-context, layered,
doc-envelope) are off the shipped menu; surface them only on an explicit "show more options".

## 4 — Scaffold the envelope + skeleton

Write the **shared envelope** every strategy ships:

- root **`spec.md`** (the index + the `project-path` frontmatter + the placement map + the reserved by-concept
  index block — step 5);
- **`design/`** — the rules/model home, **including `design/decisions/`** (the ADR log: append-only,
  descriptive, ungated — the project-scope sibling of a unit's `<unit>.solution.md`; *organize no node as an
  ADR body*);
- **`workflows/`** — the workflows suite home (cross-capability usage flows);
- a **tooling/project** home (build, CI, packaging, deps);
- **`glossary.md`** — a root file beside `spec.md` (never a folder): the project's ubiquitous
  language, every load-bearing term defined once in plain words. Seed it with the terms the scaffold
  already commits to; per-unit explore adds the rest.

Then the chosen strategy's **top-level skeleton** of **stub node READMEs**, each declaring a legal
**`spec-type`** via the classifier:

- a **testable surface** → `behavioral` (`## Use Cases`; its `.feature` is authored later, in explore);
- a **shipped suite-less artifact** (a governance, a config) → `reference` (`## Subject`, no
  `.feature`);
- an **index / rule / structural grouping** → **descriptive** (no marker).

The skeleton obeys the **two-level depth cap** under **every** strategy: a capability node is
`<capability>/<unit>` and **never three deep** — a sub-grouping inside a capability is a `concept:` tag
recovered by the by-concept index, not a third folder level. Under **mirror-source**, mirror **only to the
unit boundary**: a folder with a testable surface becomes one behavioral leaf that owns its subtree; create
**no node below a behavioral leaf** (nested `src/` there is impl detail). A capability node README carries
**only** its `spec-type` marker — never a lifecycle field; its cross-cutting **`concept:`** tag is assigned
later in per-unit explore (via the `place-node` skill), not at scaffold.

## 5 — Declare the organization (do not leave it to be re-derived)

In the same act that writes root `spec.md`, record both so a later edit reads, never re-scans:

- **`project-path` frontmatter** — the repo-relative source dir this spec governs (the package for a
  hoisted spec; the project root for a colocated one). It is the router's source→spec map; the spec
  **location mode** (`colocated | hoisted | monorepo-member`) is *derived* from it, not stored. There is
  **no `spec-layout` block** (ADR-0017: frontmatter is the router index — the strategy is not something the
  router needs).
- **`name` frontmatter (the project name)** — write it when the project's name is **not reliably
  derivable** from the location (`discover-specs` derives `repo` for a repo-root single-project and the
  folder for a `.agents/specs/<project>`, but only **guesses** a nested project's folder basename). For a
  **hoisted / nested** project, **ask the user for the name and store it** (infer a default from the
  invocation when the user named the project — e.g. `backfill <this-project>`); confirm before writing.
  Skip it when the derived name is already right (a plain colocated repo-root project).
- the **placement map** in the body — the maintained "a concept of kind K lives in home H" taxonomy + the
  nesting rule, **naming the chosen strategy** in its heading/intro, so a newcomer routes a new concept
  without holding the tree in their head and `start-mission` / the Warden read the strategy on demand.
- the **reserved by-concept index block** beside it (generated by the `concept-index` skill) — the
  cross-cutting `concept → its nodes` view. Reserve the block; **leave it for `concept-index` to
  generate** from `concept:` frontmatter — pure derivation, never hand-maintained.

Validate the result with the `spec-gate` skill's `check-spec-state` script (`check-spec-state.mjs --root
<specs-dir>`): the root lifecycle tuple must be legal.

## 6 — Hand back

Backfill ends with **stub** behavioral nodes (`## Use Cases` present, no `.feature`), not filled ones —
filling them is the **per-unit explore grill** (`spec-producer-governance`), the interactive live loop. **Do
not auto-continue into it.** Present the count of stub nodes and **ask the user**:

- **Continue now** — proceed into per-unit explore in this session, node by node, to the spec gate.
- **Defer to a mission** — stop at `status: draft`; the stubs stay a worklist any later `start-mission` /
  `resume-mission` picks up (the explore grill may want a different model or session).

Either way, **propose** the node placement for the formation **Warden** to confirm or relocate, and leave
`status: draft`.

## Output boundary

Write the skeleton, the root envelope (`project-path` frontmatter + placement map + the reserved by-concept
index block), the `design/decisions/` home, and `glossary.md` — nothing else. Do **not** author any node's `## Use Cases`/`.feature`, render a gate verdict,
freeze, or write `status` / `approval` / `produced-by` (the conductor's and `spec-gate`'s; see
`ownership-governance`).