Registry item prompt (SPEC-195)¶

The one prompt contract for every skill that adds an item to the toolkit's project registry, intake/projects.yaml: /vt-c-project-register (Steps 4–5), /vt-d-scaffold (Step 6.5) and /vt-t-toolkit-review --scan. The questions live here; every rule about valid values lives in registry_write.sh, which refuses what does not pass. Contract: specs/195-project-identity-and-spec-location/contracts/project-registry.md (C1, C4).

Values the calling skill already has¶

Field	Source
`path`	the project directory (`$PWD` or the scanned path)
`name`	the calling skill's name detection (for example `basename`)
`type`	`coding`, `mixed`, `design` or `knowledge` from the calling skill's own detection
`domain`	optional — `VisiTrans`, `VisiMatch`, `VisiFair`, `VisiArea`, or none for private projects
`location`	optional — `local-git` or `local-folder`

Questions¶

Ask with AskUserQuestion, in this order.

1. `id` — the short project id¶

The id is the cross-project key: the Spec-Board shows <id>:SPEC-NNN. It must match ^[A-Z][0-9]{2,3}(-[0-9]{2})?$.

Proposal: the name prefix up to the first - or space, when that prefix matches the pattern (F055-VisiFair Social Media → F055, P01-Notfallsani-Lernsystem → P01).
Sub-repository of a project that numbers its own specs: the parent's number plus a two-digit component number (F015-01, F015-02).
Private project: offer "exclude from cross-project views" → write board: false and no id.

Options: the proposed id (Recommended, only when a prefix matched) · another id · private project (board: false). Never invent an id from a name without a project number — reason: a guessed id such as WORK looks valid to a reader but names no project, and the board key built from it points nowhere.

2. `parent` — only for a sub-repository¶

Ask only when the answer to question 1 was a component id (F015-02). The parent is the id of the owning project's registry item (F015). Default: no parent.

3. `spec_root` — only when the repository does not declare its spec folder¶

Skip this question when the repository's .design-state.yaml has a top-level specs_directory: key — specs_directory: null counts as declared. Ask the file of the project being registered, by absolute path, never a bare relative one:

grep -q '^specs_directory:' '<project path>/.design-state.yaml' 2>/dev/null && echo declared

⚠ The path is not decoration. /vt-t-toolkit-review --scan registers OTHER projects while its cwd stays the toolkit, and the toolkit's own .design-state.yaml declares specs_directory: specs/ (measured 2026-10-03). A bare relative grep therefore answered "declared" for every project under --scan, so this question was ALWAYS skipped, the item was written without a spec_root, and the resolver fell through to its probe — reproducing the exact C010 defect this spec exists to close. Two currently-registered projects are in that shape: one has no .design-state.yaml at all and one has the file without the key.

A declaration the resolver refused does not count: when resolve_project.sh printed invalid specs_directory: … for this repository, ask for the spec folder as if none were declared (the resolver ignores the invalid value and would otherwise fall through to a probe).

Otherwise propose the first folder that exists of specs/, 05-specs/, docs/specs/, 02-specs/. When none exists, skip the question: the resolver then returns an empty spec folder (field 6) and the consumer skills handle that case themselves — /vt-d-activate and /vt-d-spec-from-requirements ask, /vt-d-specs-from-prd defaults to specs/.

Write¶

bash ~/.claude/skills/vt-c-project-register/scripts/registry_write.sh add \
  --path '<path>' --name '<name>' --type '<type>' --id '<id>' \
  --parent '<parent>' --domain '<domain>' --spec-root '<spec_root>' --location '<location>'

Omit every flag whose value is empty; for a private project replace --id '<id>' with --board false. Put each value inside single quotes and first reject any value containing a ' — reason: names and paths come from the repository and from the user, and inside double quotes a $(...) in them would run as shell code.

Writer exit codes¶

Exit	Meaning	Do
exit 0	written	show the writer's summary line
exit 3	refused, value-level — invalid or duplicate id, unknown parent, invalid or declared-none `spec_root`, a path that is not absolute, a value with a control byte or that is not one YAML scalar	show the reason from stderr, ask again for the offending value, retry
exit 3	refused, terminal — the toolkit itself (D13), a path already registered (`add`), a path not registered (`set`)	show the reason and stop; there is no value to re-ask
exit 2	toolkit defect — registry or library missing, bad arguments	report "Toolkit defect: " and stop registering

Never append to intake/projects.yaml by hand when the writer refuses — reason: the refusal is the validation; a hand-written item skips it and turns the id guard red for everyone.