Orchestrator Guide

TL;DR. The orchestrator recommends which registry items a project should provision, reading declarative metadata on each item instead of a hardcoded shell table. Ask "what should I provision for this project?" and it answers from the registry. Engine: scripts/orchestrator/recommend.js.

The orchestrator is the system that recommends which BoB registry items (registry/skills/, registry/agents/, registry/commands/) a project should provision. It replaces the historical hardcoded stack_to_items() table inside scripts/provision.sh with a declarative metadata contract that lives on each registry item itself.

When you ask "what should I provision for this project?" or "is doc-keeper applicable here?" the orchestrator answers from the registry's metadata, not from a hardcoded list inside a shell script.

How the orchestrator runs

There are two invocation modes, both consuming the same engine and the same question bank:

Mode	Entry point	When to use
Claude Code (#162)	/provision init (interactive in Claude)	When you're already in a Claude Code session and want a guided set-up
Pure CLI (#163)	cdprov --interview	From a terminal without Claude — useful for CI / scripts / first-machine bootstrap

Both produce byte-identical manifests for identical inputs because they:

1. Run the same stack detection (detect_stack() in scripts/provision.sh).
2. Walk the same question bank (scripts/orchestrator/questions.json).
3. Call the same recommendation engine (scripts/orchestrator/recommend.js).
4. Write to the same provisions/<project>.json shape.

Interview flow

detect_stack(project_dir)              # auto-detect tech stack
       ↓
load questions.json                    # dynamic question bank
       ↓
ask question 1 (project_type)
ask question 2 (lifecycle_stage)
ask question 3 (capabilities, multi)
[ask question 4 (deploy_target) if applies_when matches]
       ↓
merge implies[] from each answer       # post-processing
       ↓
recommend.js --stack ... --project-type ... --lifecycle ... --capabilities ...
       ↓
[show diff against existing manifest if --existing-manifest supplied]    ← #164
       ↓
[confirm changes]                                                        ← #164
       ↓
write provisions/<project>.json
       ↓
re-run cdprov refresh                  # apply symlinks based on the manifest

Steps 1–3 are documented in detail below. Step 4 (diff-and-confirm) is #164.

---

---

Registry metadata contract

Every registry item (skill, agent, or command) declares orchestrator metadata in its YAML frontmatter. The full schema lives at schemas/registry-item.schema.json (JSON Schema draft-07). The fields:

Field	Required	Type	Purpose
name	yes	string (kebab-case)	Stable identifier — must match the file/dir basename
description	yes	string	One- or two-line summary surfaced in interview UIs
model	no	sonnet / haiku / opus	Preferred Claude model (agents only)
applies_to.stacks	no	string array	Tech stacks (from detect_stack) that auto-include this item
applies_to.project_types	no	string array	Project archetypes that auto-include this item (api, web-app, cms, ...)
applies_to.phases	no	string array	Project lifecycle phases this item applies to (inception, build, stabilize, maintain, any). Absent = every phase (#1133)
recommended_for	no	string array	Activity categories (development, testing, ops, governance, ...)
category	no	enum	UI grouping (backend-runtime, testing, review, ...)
required_with	no	qualified-id array	Other items this implies (e.g. skills/api-designing)
conflicts_with	no	qualified-id array	Mutually exclusive items
default	no	boolean	Always include for every project, regardless of stack

Example — registry/skills/cloudflare-dev/SKILL.md:

---
name: cloudflare-dev
description: "Cloudflare development expertise..."
applies_to:
  stacks: [cloudflare-workers, cloudflare-pages, d1, r2, kv]
  project_types: [api, backend, web-app]
recommended_for: [development, ops]
category: backend-runtime
required_with: [skills/api-designing]
---

Example — registry/agents/code-reviewer.md:

---
name: code-reviewer
description: ...
model: sonnet
applies_to:
  stacks: [any]
  project_types: [any]
recommended_for: [review, development]
category: review
default: true
---

default: true means every project gets this item regardless of stack — useful for cross-cutting agents (code-reviewer, code-debugger, unit-test-generator) and process commands (research, retrospective, standup, status).

Stack enum — must match one of the values detect_stack() produces in scripts/provision.sh:

cloudflare-workers, cloudflare-pages, d1, r2, kv, typescript, javascript, node, deno, bun, hono, express, fastify, sveltekit, nextjs, react, vue, solidjs, astro, drupal, wordpress, strapi, ghost, vitest, jest, playwright, python, rust, go, ruby, php, tailwind, shadcn, any.

Project-type enum: api, backend, web-app, cms, research, cli, library, framework, mixed, any.

---

Validating metadata

Validator script

scripts/checks/validate-registry-metadata.sh walks every registry item and reports its state:

• ok — item declares migrated frontmatter and validates against the schema
• unmigrated — item exists but hasn't been migrated to the new contract yet (no orchestrator fields). Not an error — rollout is incremental.
• error: <details> — item declares migrated fields but they don't validate. Fatal.

bash scripts/checks/validate-registry-metadata.sh /path/to/bob-source

Output (last line is the summary):

registry/skills/cloudflare-dev/SKILL.md: ok
registry/skills/api-designing/SKILL.md: unmigrated (legacy frontmatter only)
registry/agents/code-reviewer.md: ok
...
[validate-registry] total=75 migrated=3 unmigrated=72 errors=0

Makefile target

make check-registry-metadata runs the validator and exits non-zero on errors (not on unmigrated items). This target is part of make check, so the canonical verification entry point now gates on schema correctness for every migrated item.

make check-registry-metadata     # standalone
make check                       # bundles it with the other checks
make ci                          # full check + test + docs-check

---

Migration status

Category	Migrated examples
Skills	registry/skills/cloudflare-dev
Agents	registry/agents/code-reviewer.md
Commands	registry/commands/research.md

The remaining items (~72 of 75) will be migrated in #159. Until then, the validator reports them as unmigrated and make check does not fail. The recommendation engine (#160) falls back to the existing stack_to_items() table for any item that hasn't been migrated yet, so the orchestrator never breaks during rollout.

---

Downstream features

The schema is the foundation for the rest of the orchestrator capability:

• #159 — Backfill metadata across the entire registry. After this lands, unmigrated count goes to zero and make check becomes strict.
• #160 — Recommendation engine. Reads applies_to, recommended_for, default, required_with, conflicts_with and emits a per-project manifest.
• #161 — Interview question bank. Maps user answers (project type, activities) to applies_to.project_types and recommended_for.
• #162 — Claude Code invocation path (/provision init interactive).
• #163 — Pure-CLI invocation path (cdprov --interview).
• #164 — Diff-and-confirm UX for re-runs.
• #165 — Golden-manifest test fixtures.
• #166 — Final orchestrator documentation (this guide gets expanded).

---

Recommendation engine (#160)

The engine at scripts/orchestrator/recommend.js is the single source of truth for "given this stack + project type + capabilities, which items belong in the manifest?" Both the Claude Code path (#162) and the pure-CLI path (#163) call it directly so identical inputs always produce byte-identical manifests.

node scripts/orchestrator/recommend.js \
  --stack cloudflare-workers,d1,hono \
  --project-type api \
  --lifecycle development,testing \
  --capabilities development,review,testing \
  --existing-manifest provisions/foo.json

Output is a manifest JSON to stdout that conforms to schemas/manifest.schema.json. Fields:

• _meta.project — the project name (from --project-name, falling back to the existing manifest's _meta.project, then basename(cwd))
• _meta.path / _meta.stack / _meta.cloudflare_account — the schema's declared metadata; path and cloudflare_account are preserved from --existing-manifest when present
• _meta.manual — items that were in --existing-manifest but not in the recommended set (preserved as user customisations)
• skills, commands, agents, runbooks — sorted item lists

The engine emits no provenance block (generated_at, generator, version, input) — git history records when/how a manifest was generated, and a volatile timestamp would defeat idempotent re-runs (#1269).

The engine implements five selection rules in order:

1. default: true → always included.
2. applies_to.stacks ∩ user stack (or any wildcard).
3. applies_to.project_types contains the user's project_type (or any).
4. recommended_for ∩ capabilities/lifecycle (or empty user list = unconditional match).
5. applies_to.phases contains the project's phase (or any; absent field = every phase; no declared phase = no filtering — #1133).

After filtering, expandRequirements() walks required_with edges and pulls in implied items. Then checkConflicts() returns non-zero with details if any conflicts_with edges overlap the selected set.

Phase as a recommendation input (#1133)

The provision manifest's _meta.phase is the single declared home for a project's lifecycle phase — vocabulary inception / build / stabilize / maintain, enforced by schemas/manifest.schema.json. recommend.js --phase overrides it for a one-off run; without the flag the engine reads it from --existing-manifest, and it writes the resolved phase back into _meta.phase so recompute stays self-contained and deterministic. A phase edit is therefore a normal manifest edit: edit _meta.phase → recompute → review the diff → cdprov refresh — a previously provisioned item that falls out of phase scope is preserved as a _meta.manual keep (reviewable, never a silent drop), and a fresh recompute at the new phase yields the leaner set. The loop is guarded end-to-end by make test-phase-transition.

Flight-plan scope derivation (plan-scope.js, #1133)

scripts/orchestrator/plan-scope.js turns a flight-plan issue (#1068) into a provision overlay — the registry items the plan's issues need, on top of the base manifest, never a mutation of it:

node scripts/orchestrator/plan-scope.js derive <plan-N> --project <name>   # overlay doc (JSON)
node scripts/orchestrator/plan-scope.js diff   <plan-N> --project <name>   # reviewable +added diff

Signals are derived deterministically from the plan's issues: stack tokens matched word-bounded in title/body, labels mapped to capabilities (bug → testing, documentation → docs, literal capability labels), and area:<slug> labels matched against the capability/category vocabularies — all vocabularies read from schemas/registry-item.schema.json at runtime. An item is overlay-relevant when any signal hits it; required_with is expanded, base-manifest items are subtracted, default: true items are excluded (the base recompute owns them). The overlay is applied/restored by cdprov overlay — see the provisioning docs and the warp-drive how-to's flight-plan section for the session lifecycle (#1133).

Capability blocks (beyond item lists)

The engine also emits opt-in capability blocks that aren't symlinked items. The versioning block (#277) is emitted whenever the versioning command is selected (it is default: true, so effectively every project — the BoB-wide-versioning goal of #275), with a per-project-type trigger_paths filter (VERSIONING_TRIGGER_PATHS in recommend.js): docroot/** for cms, the full source surface for framework, src/**+package.json for apps/libraries, no filter for research/mixed. An existing manifest's versioning block is always preserved, so opt-outs (enabled:false) and customizations survive a re-run. cdprov refresh then copies the versioning template set into the project — see the versioning guide.

The docs_site block (#735) recommends a documentation site for applicable project types — web-app, api, backend, cms, library, framework, mixed — and is gracefully skipped for CLI-only and research repos. It records the recommendation and the default engine ({ "enabled": true, "engine": "vitepress" }); VitePress is the single default and Starlight is an explicit, evaluation-only opt-in (#734). Unlike the registry skills, docs-site is a universal skill (always present), so the block is a recommendation to run /docs-site init rather than a symlinked item — that's why it gates on the skill's own applies_to.project_types (read from skills/docs-site/SKILL.md) instead of being one of the scanned registry/ items. An existing docs_site block is always preserved, so an opt-out or engine choice survives a re-run. See the docs-site skill (skills/docs-site/SKILL.md).

Inference from vision and code (#1873)

The interview is one way to tell the engine what a project is. The vision-aware pipeline is the other: the same (stack, project_type, lifecycle, capabilities[]) tuple the questionnaire produces is inferred from the project's prose and code, fed to the engine, explained item by item, and re-derived on demand when the project moves. Every stage is a separate script with a stable document contract, so each can be run — and tested — alone.

docs/vision.md + README.md + CLAUDE.md ─┐
                                        ├─ infer-profile.js ─ profile ─ recommend.js --profile ─ manifest
package.json, wrangler.*, workflows, … ─┘         │                          │
                                                  └─ explain.js ─────────────┴─ why: / would-add / would-remove
                                                        │                           │
                                       gap-detect.js divergence              cdprov reconcile [--apply]
                                       (/vision, /groom nudge)               (apply the delta)

Stage	Script	Surfaces it	Issue
Infer the profile	scripts/orchestrator/infer-profile.js	cdprov --init (default), recommend.js --infer	#1877
Recommend from it	scripts/orchestrator/recommend.js --profile	cdprov --init [--auto], /provision init	#1878
Explain the recommendation	scripts/orchestrator/explain.js	cdprov --init --auto, cdprov --diff [--json]	#1879
Reconcile the manifest	scripts/provision.sh reconcile	cdprov reconcile [--apply] [--allow-remove]	#1880
Nudge on divergence	scripts/orchestrator/gap-detect.js divergence	/vision, /groom	#1881

Inputs

infer-profile.js reads, per project and each optional:

• Prose — docs/vision.md, README.md, CLAUDE.md. Matched against the registry's own category cue words (recommended_for vocabulary: testing, ops, governance, docs, review, …). There is no per-item keyword table and no new taxonomy.
• Code — package.json (deps, bin, scripts), wrangler.*, dev.json / checks.json, .github/workflows/*, tests/, docs-site.json, tsconfig / composer / Cargo / go.mod / pyproject, plus a shell signal from bin/ / scripts/ entrypoints. Stack detection is scripts/fleet/readiness.js detectStack — the same detector the fleet audit uses, so inference and audit can never disagree about what a project is built with.

node scripts/orchestrator/infer-profile.js --root <dir>          # human: fields + evidence
node scripts/orchestrator/infer-profile.js --root <dir> --json   # schema bob-orchestrator-profile/1

The output is deterministic and side-effect-free — file reads only, no processes, no network, fixed key and array order — so the same tree is byte-identical across runs and machines. Golden fixture projects under tests/fixtures/orchestrator/ pin the outcomes (#1882: a CF Workers API with a vision, a shell CLI without one, a docs-only repo); make test-infer-profile runs them.

Evidence model

Every inferred field carries evidence. The profile's evidence[] rows are {field, value, source, note}:

• source is a file:line for prose (docs/vision.md:L12) and a file:key for code (package.json:bin, package.json:devDependencies.vitest, .github/workflows/ci.yml, tests/).
• A conflict — vision says "website", package.json:bin says CLI — is recorded as a conflict: note on the field's evidence row (the code value, the prose source and its excerpt). It is never silently resolved.
• Absence is evidence too. Missing prose degrades to stack-only inference, and the profile's sources.absent names what was not there, so a stack-only result is distinguishable from a vision that simply evidenced nothing.

The evidence rows are what make every later stage explainable: explain.js maps each recommended item's matching facet back to the row that produced it, and the divergence nudge quotes the same row (vision now mentions capability governance (docs/vision.md:L9)).

Precedence

Three sources can describe the same project — interview answers, code, prose — and they do not carry equal weight:

Field	Wins	Then	Notes
stack	interview answer (explicit flag)	code	prose never sets a stack
project_type	interview answer	code	prose is used only when code gives no signal; a prose/code conflict is recorded, code applies
lifecycle	interview answer	code	prose may refine it
capabilities	interview answer	vision prose	code adds testing / ops / docs signals; README / CLAUDE.md prose contributes only when a vision exists

In short: interview > code > vision for stack and type; vision contributes capabilities.

• Explicit flags override inferred fields, field by field. recommend.js --stack, --project-type, --capabilities, --lifecycle given alongside --profile win — that is how interview answers layer on top of inference.
• Vision gate. Prose-derived capabilities are applied only when docs/vision.md was among the profile's consulted sources. Without a vision the profile contributes stack + type only, so the result is the stack-only baseline — a CLI tool with no vision gets exactly what it got before #1878. The baseline is the wider set (no capability filter); a vision narrows it to the capabilities it evidences.
• Lifecycle is folded, not filtered. The inferred stage is translated into capabilities through the interview's own implies table (questions.json lifecycle_stage — maintenance adds ops + review, and so on) and deliberately not passed as --lifecycle: that match is a restrictive filter on recommended_for, and an active stage would veto every docs/governance item the vision asked for.

Limits

Inference is a heuristic, and its limits are by design:

• Prose matching is cue-word matching. A vision that says "we value rigorous verification" does not evidence testing; one that says "unit tests and e2e" does. Phrasing that misses the cue list is a missed capability, not an error — the interview (or an explicit --capabilities) is the override.
• Prose never sets the stack, and sets the type only in a codeless tree. A vision describing a future stack contributes nothing until the code exists.
• No vision, no capability filter. The stack-only baseline is intentionally wide; the first /vision write is what narrows it (and what triggers the divergence nudge).
• Evidence is per file:line, not per sentence meaning. Two capabilities cued from one line share a source; the note distinguishes them.
• Registry items without orchestrator metadata are invisible to inference and explain alike: they are never recommended and, if declared, surface as a would-remove whose reason is not a registry item with orchestrator metadata (cannot be evidenced) — a metadata gap to fix, not an item to drop.

Feeding the engine (--profile / --infer, #1878)

The profile document is an input source for recommend.js equivalent to interview answers:

node scripts/orchestrator/recommend.js --profile <profile.json|->   # a saved / piped profile
node scripts/orchestrator/recommend.js --infer <project-dir>        # infer in-process, then recommend

cdprov --init and cdprov --init --auto take this path by default: they run infer-profile.js on the project, print the inferred stack / type / capabilities (and which prose was consulted), and hand the profile to the engine. --no-infer restores the stack-only input (detect_stack + infer_project_type, no capabilities); an inference failure falls back to the same path with a warning rather than aborting. The existing-manifest contract is unchanged — a re-run over a manifest keeps items the new recommendation drops as _meta.manual, so switching between --no-infer and the default never silently removes anything.

Explainable output (explain.js, why: lines, #1879)

Every recommendation is explainable. scripts/orchestrator/explain.js re-runs the engine's matching rule with the facets that fired recorded (explainInclude() in recommend.js — the same rule shouldInclude() answers, so the explanation can never disagree with the manifest) and maps each facet back to the profile's evidence:

node scripts/orchestrator/explain.js --project <dir> [--manifest <path>] [--json]
#   + skill cloudflare-dev — why: stack cloudflare-workers (wrangler.toml); capability ops (.github/workflows/ci.yml); required by skills/d1-expert
#   = agent qa-strategist  — why: capability testing (package.json:devDependencies.vitest); capability governance (docs/vision.md)
#   - skill shell-cli-design — would-remove: no evidence supports it: not matched by stack/project type/capabilities, not default, not required_with by a recommended item

• + would-add — recommended, not in the manifest; = keep — recommended and declared. The why: names the facet(s) that matched — one stack (with its file), the project type, every matched capability with its source (docs/vision.md:L9 for prose, package.json:… for code), default for every project, or required by <kind/name>.
• - would-remove — a manifest item that neither evidence, default: true, nor a required_with edge from a recommended item supports. Items listed in _meta.manual are flagged (kept).
• Report-only, never silent. explain.js writes nothing, and no provisioning write removes a manifest item: cdprov --init --auto re-runs preserve unsupported items as _meta.manual, and only an explicit cdprov remove <type> <name> or an accepted cdprov reconcile --apply --allow-remove drops one. A would-remove is a prompt for a human decision, not an action.
• --json carries the same structure for tooling — schema bob-orchestrator-explain/1: recommended[] {kind, name, status, why, evidence[] {facet, value, source, note}}, would_remove[] {kind, name, manual, why}, counts, context, sources.

cdprov surfaces it in two places: cdprov --init --auto prints a Recommendation block with a why: line per item after generating the manifest, and cdprov --diff appends a Recommendation (inferred) section — would-add with why:, would-remove with its reason — after the link diff. cdprov --diff --json emits the explain.js document instead of the human report. Both honour --no-infer.

Reconcile (cdprov reconcile, #1880)

The explain document is also the input to reconciliation — re-deriving a long-lived project's manifest after its vision or code has moved, instead of hand-editing it:

cdprov reconcile                         # dry run: + would-add (why) / - would-remove (reason); nothing written
cdprov reconcile --apply                 # apply: single-item delta at L2+ fast-paths end-to-end;
                                         #        multi-item delta or L1 opens the staged review PR
cdprov reconcile --apply --allow-remove  # also drop would-remove items (never by default)

cdprov --diff --infer is the same dry run. --apply builds the new manifest and hands it to exactly the machinery cdprov add/remove use — the #785 staged review PR with the #1478 config-fastpath on top, --now, or the ungated apply route; the #791 pending-PR manifest is the edit base when one is open. It is idempotent (a reconcile after an applied one reports no delta and creates no git refs), removals are withheld unless --allow-remove is passed or an interactive run answers yes, and _meta.manual items are never removal candidates. Full routing rules: handbook §3.4. Tests: make test-cdprov-reconcile.

Divergence nudge (gap-detect.js divergence, #1881)

The last stage closes the loop from a vision edit back to provisioning. gap-detect.js divergence takes the inferred profile instead of a free-text task and nudges — with the same #412 dedupe, the same fix: line and the same exit codes as the mid-session match — for every registry item the explain document would-add but the manifest does not declare:

gap-detect: 2 unprovisioned registry item(s) implied by the inferred profile (action: confirm, L2):
  skills   policy-audit  — vision now mentions capability governance (docs/vision.md:L9) — registry item policy-audit covers it
           fix: cdprov add skills/policy-audit --now

/vision runs it after writing or updating docs/vision.md; /groom runs it once per reconciliation pass (step 2c). Both print the nudges verbatim and never apply them — the manifest is edited only by cdprov add or cdprov reconcile --apply. make test-gap-detect covers it alongside match.

cdprov flags for the pipeline

Invocation	What it does	Writes?
cdprov --init	Infer the profile (default), recommend, stage the manifest for review (#785)	manifest (staged)
cdprov --init --auto	Same, applied directly in one shot, then refreshed; prints a why: line per item	manifest
cdprov --init --no-infer	Stack-only input — detect_stack + infer_project_type, no capabilities	manifest
cdprov --diff	Link diff + Recommendation (inferred): would-add with why:, would-remove with reason	no
cdprov --diff --json	The explain.js document	no
cdprov reconcile / --diff --infer	The would-add / would-remove delta against the manifest	no
cdprov reconcile --json	The same delta as the explain document	no
cdprov reconcile --apply	Apply adds (single item L2+ → fast path; multi-item / L1 → review PR); removals withheld	manifest (routed)
cdprov reconcile --apply --allow-remove	Also apply would-remove items	manifest (routed)
cdprov detect	Stack + project type as JSON — the stack-only input, for tooling	no

--no-infer is honoured by every inferring invocation (--init, --diff, reconcile). A would-remove is never applied by --init, --init --auto, --diff or a bare reconcile --apply.

Interview question bank (#161)

Both invocation paths share a data-driven question bank at scripts/orchestrator/questions.json (validated by make check against schemas/orchestrator-questions.schema.json). Editing the JSON is the canonical way to change interview behavior — no code changes needed.

Each question declares:

Field	Purpose
id	Stable identifier
prompt	What the user sees
help (optional)	Extra context for the user
type	single or multi
maps_to	Which engine flag this question feeds (project_type, lifecycle, capabilities, stack)
applies_when (optional)	Predicate gating when the question is asked (e.g. only ask "deploy target" when project_type ∈ {web-app, api, backend, cms})
options[]	Each option has label, value, and an optional implies[] for additional values to union into related flags

The question bank's option values use the same enums as schemas/registry-item.schema.json — project_types, stack names, and capability categories all match. That alignment is what lets the engine route an answer directly into a flag without translation.

The four current questions:

1. project_type (single) — web-app / api / backend / cms / research / cli / library / mixed
2. lifecycle_stage (single) — greenfield / active / maintenance / audit-only (each implies a default capability set)
3. capabilities (multi) — pre-selected from the engine's recommendation; categories come from registry metadata
4. deploy_target (single, conditional) — Cloudflare Workers / Node / self-hosted / unknown

Adding a new registry item

When you add a new skill, agent, or command, declare orchestrator metadata in its frontmatter:

---
name: my-new-skill              # required, kebab-case, must match dirname/filename
description: One-line summary.   # required
applies_to:
  stacks: [<from the schema enum>]   # auto-include for these tech stacks
  project_types: [api, backend, ...] # auto-include for these archetypes
recommended_for: [<activity categories>]   # capability-driven inclusion
category: <ui-grouping>           # how the interview groups this item
required_with: [skills/some-other]  # implies these other items
default: false                    # set true to always include
---

Then run make check-registry-metadata — the validator catches schema violations early. If you're stuck on which category or recommended_for value to use, look at how a similar existing item is tagged: grep -rl "^category: testing" registry/.

When in doubt, use any for stacks/project_types — the engine's other rules (capability match, required_with) still scope the item appropriately.

Adding a new question

The interview is data-driven; no code changes needed.

1. Edit scripts/orchestrator/questions.json.
2. Add an entry under questions[]:

   {
     "id": "my_question",
     "prompt": "What ...?",
     "type": "single",
     "maps_to": "capabilities",
     "applies_when": { "project_type": ["web-app", "api"] },
     "options": [
       { "label": "...", "value": "option-1", "implies": ["..."] }
     ]
   }

3. Run make check-schemas — the schema validates the question's shape.
4. Both invocation paths pick up the new question on next run; no rebuild needed.

maps_to must be one of project_type, lifecycle, capabilities, or stack. option.values should match the enums in schemas/registry-item.schema.json (otherwise the engine won't know what to do with them). implies is the canonical extension point for unioning extra values into related flags.

Troubleshooting

"I asked for X but didn't get item Y"

Check the engine's filter rules in order:

1. Does the item have default: true? If so, it's always included regardless of inputs.
2. applies_to.stacks — does it intersect your --stack? any is a wildcard.
3. applies_to.project_types — does it contain your --project-type? any is a wildcard.
4. recommended_for — does it intersect your --capabilities or --lifecycle? Empty user list means unconditional match.
5. After matching, required_with edges are pulled in. Did the item arrive because something else's required_with listed it?

If everything looks right but the item is still missing, run the engine with explicit flags and inspect the filter:

node scripts/orchestrator/recommend.js --root . --stack <yours> --project-type <yours> --capabilities <yours> 2>&1

"I got a conflict error"

checkConflicts() returned non-zero because two items in the recommended set declare each other in conflicts_with. The error message lists the offending pair. Resolution paths:

• Remove one of the items from the registry (if conflicting items shouldn't both exist).
• Tighten the applies_to of one so they don't both match the same project (if they're alternatives for different stacks).
• Remove the conflicts_with declaration if it's overly aggressive.

"Same inputs produce different manifests"

That should never happen. The engine sorts items by name within each kind and its output is fully deterministic (since #1269 there is no timestamp or other volatile field). Diff the two outputs directly to compare.

If the diff is still non-empty, file a bug — there's a non-determinism somewhere (a Set traversal order, an unordered readdir, etc.).

"An item shows up in the manifest with _meta.manual"

That's intentional — the item was in the existing manifest but not in the engine's recommended set, so it was preserved as a user customisation. To remove it, edit the manifest manually and re-run.

"validate-registry-metadata.sh reports unmigrated"

Items that haven't been migrated to the orchestrator schema yet (applies_to, recommended_for, or category missing). Run scripts/migrate-registry-metadata.sh --force to backfill from the rule table, then audit the result.

If the rule table doesn't have an entry for the item, add one and re-run. The migration script is idempotent — re-runs only touch items the rules cover.

---

Pure-CLI interview (#163)

cdprov --interview (or the PATH-friendly cdprov-interview binary) runs the same interview from a terminal — no Claude Code session required. It picks the best-available TUI:

Preference	Tool	Usage
1	gum	gum choose for single-select, gum choose --no-limit --selected="…" for multi-select with pre-checks
2	fzf	fzf for single, fzf --multi for multi-select (no native pre-check; suggested set shown in the header instead)
3	whiptail	--menu / --checklist
4	plain read	Numbered list fallback

cdprov --interview              # interactive
cdprov --interview --yes        # skip the confirm step (interview still runs)
cdprov --interview --non-interactive < answers.txt   # CI / scripted

cdprov-interview                # same thing, PATH-friendly

CI mode (--non-interactive)

Stdin is read line-by-line in question order:

project_type
lifecycle_stage
capabilities (comma-separated)
deploy_target  (only when project_type ∈ web-app | api | backend | cms)
confirm        (Apply | Cancel — omit if --yes)

The interview's manifest must match the engine's manifest for the same inputs — verified by tests/orchestrator/test-interview.sh (5 smoke tests covering write, key shape, engine parity, cancel path, and re-run no-op).

Diff engine (#164)

scripts/orchestrator/diff.js is the shared diff library used by both the Claude Code path (#162) and the pure-CLI path (#163). It compares a proposed manifest (from recommend.js) against an existing manifest and groups every entry into one of four buckets:

Marker	Meaning
+	Added — in proposed only (the engine's recommendation will introduce this)
-	Removed — in existing only (the proposed manifest does not include it; it will be dropped unless preserved)
=	Unchanged — in both
!	Manually-added — in both, and proposed._meta.manual flagged it (the engine preserved a hand-added entry verbatim, even though it isn't in the current recommendation set)

CLI

node scripts/orchestrator/diff.js --proposed <path> [--existing <path>] [--json] [--quiet]

Exit codes: 0 no diff, 1 changes present, 2 invalid input. Designed so caller scripts (#162 / #163) can if diff.js ...; then echo "no-op"; fi and only prompt the user when there's something to confirm.

Library

const { diffManifests, formatDiff } = require('./diff');
const d = diffManifests(proposed, existing);   // pure function, no I/O
if (d.no_diff) { /* skip the confirm prompt */ }
process.stdout.write(formatDiff(d));

Manual-preservation contract

recommend.js already populates proposed._meta.manual with kind/name entries for any item in the existing manifest that the current recommendation didn't pick. diff.js reads that list to mark those entries as ! rather than =, so the user sees they're being kept on purpose. Re-running with the same answers is therefore a guaranteed no-op (covered by the re-run no-op test in tests/orchestrator/test-diff.js).

Downstream features (still to land)

• #162 — Claude Code invocation path: /provision init runs the interview interactively inside Claude Code. Calls recommend.js + diff.js and writes the manifest.
• #163 — Pure-CLI invocation path: cdprov --interview for terminal use. Reads questions.json, prompts via gum (with fzf/whiptail fallbacks), and pipes inputs to the engine. Same output shape as #162.
• #506 ✅ — Retired stack_to_items() in scripts/provision.sh and routed --init (and the one-shot --init --auto) through the engine, so --init and --interview recommend identical items from identical metadata.
• #1877 / #1878 ✅ — Profile inference (infer-profile.js) and recommend.js --profile / --infer; cdprov --init feeds the inferred profile by default (--no-infer = stack-only). Fixture projects pin the outcomes (#1882).
• #1879 ✅ — Explainable provisioning: explain.js why: lines from evidence, would-remove for unsupported manifest items (report-only, never silent), surfaced by cdprov --init --auto and cdprov --diff / --diff --json.
• #1881 ✅ — gap-detect.js divergence: the inferred-profile nudge for unprovisioned registry items (vision now mentions … — registry item … covers it + cdprov add fix), run by /vision after a vision write and by /groom once per pass; observable-only.
• #1880 ✅ — cdprov reconcile [--apply] [--allow-remove]: re-infer and apply the manifest delta through the staged-PR / fast-path route; dry run by default, idempotent, removals never applied without --allow-remove.
• (follow-up) — A recorded asciinema demo for the guide.

---

See also

• schemas/registry-item.schema.json — full schema source
• schemas/orchestrator-questions.schema.json — question bank schema
• scripts/orchestrator/recommend.js — recommendation engine (#160)
• scripts/orchestrator/diff.js — diff engine (#164)
• scripts/orchestrator/questions.json — interview question bank (#161)
• scripts/checks/validate-registry-metadata.sh — registry validator
• scripts/provision.sh — detect_stack + infer_project_type; --init / --init --auto route through the engine (#506, stack_to_items retired)
• PROJECT-ORCHESTRATION-HANDBOOK §3.4 — manifest provisioning workflow