/kbd-init
Initialize the KBD orchestrator for the current project.
/kbd-initowns full project configuration discovery. Phase creation and advancement helpers ownproject.json.activePhase, preserve unrelated keys, and remove the legacyactive_phasealias. If metadata is missing, those helpers may bootstrap minimal identity and active-phase metadata; this does not replace/kbd-initfor full stack, policy, and constraint discovery.
OpenSpec lifecycle preflight
Before this stage, follow the orchestrator preflight: use the pinned OpenSpec 2.1.0 CLI through the managed runner — session start runs the read-only verify; phase entry runs refresh, which updates existing KBD/OpenSpec projects — then use that same runner for OpenSpec commands. Retry a pending phase-entry refresh before OpenSpec work; preserve authored specs and task state. Phase scripts run this automatically, including canonical-runtime paths.
What this does
Scans the current repository to auto-discover project identity and configuration, then generates two project-specific files:
.kbd-orchestrator/project.json— project context, stack commands, tool preferences.kbd-orchestrator/constraints.md— project-specific blocking/warning rules derived fromAGENTS.md"Never Do" section and known stack conventions
Resolve every references/ and scripts/ path in this skill relative to this
SKILL.md's own directory (skills/kbd-init/). Never resolve resources
through another checkout or a cached copy of this pack.
Discovery Algorithm
Step 1: Project Name & Description
Read in priority order:
- Explicit argument:
/kbd-init "My Project Name" AGENTS.md— first H1 or "Project Identity" sectionCLAUDE.md— first H1 or executive summary first sentenceREADME.md— first H1package.json→name+descriptionCargo.toml→[package] name+descriptionpyproject.toml→name+description- Repository directory name (last resort)
Step 2: Technology Stack Detection
Detect from lock files / config files:
| File Present | Stack |
|---|---|
pnpm-lock.yaml or package.json + next.config.* |
Next.js (pnpm) |
package.json + vite.config.* |
Vite/React |
package.json (no framework) |
Node.js |
Cargo.toml |
Rust |
pyproject.toml |
Python |
go.mod |
Go |
build.gradle |
JVM |
*.sln or *.csproj |
.NET |
Step 3: Build / Test / Lint Commands
Derive from package.json scripts, Cargo.toml, Makefile, or common conventions:
- Look for
build,test,lint,dev,checkscript keys - For Next.js: detect port from
pnpm run devscript or default to 3000 - For Rust:
cargo check --workspace,cargo test --workspace,cargo clippy - Read
AGENTS.md,CLAUDE.md, and equivalent project instructions for mandatory command wrappers, environment variables, toolchain selectors, and storage paths. - Prepend those requirements to every affected command (for example, an nvm path
or a mandatory
CARGO_TARGET_DIR). - Treat a command policy as transitive: apply it to
project.jsoncommand fields, every compilingcommand:inconstraints.md, and every generated workflow trigger. For chained commands, apply the required prefix to each affected command segment; a prefix on the firstcargocommand does not cover a latercargocommand after&&. - Never weaken, omit, or replace a mandatory external path merely because it is unavailable during initialization.
After deriving commands, perform a read-only prerequisite preflight:
- Check required external roots or mounts for existence and writability.
- Do not mount storage, create target directories, or substitute a local path.
- If a required path is unavailable, continue generating configuration and mark execution as blocked in the final summary.
- If the required command policy was not propagated to every affected command, stop and correct the generated configuration before reporting completion.
Step 4: Spec Paths
Check in order:
openspec/specs/*.md— ifopenspec/directory existsdocs/specs/*.md— ifdocs/specs/existsdocs/*.md— fallback- None — set
openspec_available: false
Step 4a: Spec engine
OpenSpec (2.0.0, pack-pinned) is the primary spec engine; GitHub Spec Kit is the supported
backup. Take --spec-engine openspec|speckit|native-kbd (default openspec)
and record the choice as "specBackend" in project.json.
Existing projects are never switched. If
project.jsonalready pinsspecBackend, or the project already hasopenspec/, a Spec Kit tree (.specify/orspecs/*/tasks.md) or native changes (.kbd-orchestrator/changes/*/tasks.json), keep that engine and record it.openspec— initialize through the managed runner, naming the harnesses in use (comma-separated OpenSpec tool ids, e.g.claude,codex,opencode):node "<mini-pack-root>/lib/platform/openspec/cli.mjs" init --project "<project-root>" --tools claude,codexThe receipt reports
already-initializedwhenopenspec/exists. A failed receipt (for example Node.js below 22.20.0) leaves the project unpinned; report it instead of falling back to native files.speckit— runspecify init --here --force --non-interactive --integration <harness>(Spec Kit CLI pinned inconfig/spec-engines.json, installed withuv tool install specify-cli --from git+https://github.com/github/spec-kit.git@v1.3.0). Ifspecifyis absent, report it as a prerequisite.native-kbd— only on explicit request; no external CLI is needed.
Set openspec_available to true only when openspec/ exists after this step.
OpenSpec 2.0 writes its skills once to .agents/skills/openspec-*; the pack copies
them (never links) into the other harness skill roots, and OpenSpec 2.0 creates no
/opsx:* commands. Never edit an openspec-* skill — put project instructions in
openspec/config.yaml (context, rules).
Step 4b: Verification method
Write "verificationMethod": "VLBV" to project.json (keep an existing value).
VLBV is the pack's single verification method: acceptance scenarios are adopted
before generation, and generated code executes only at the value-phase boundary
(B4) or an authorized repair (B5) —
kbd-process-orchestrator/references/boundaries.md. A phase that must deviate
records a signed KBD-METHOD decision naming the method, its execution cadence and
its reason; no per-phase decision is needed to use VLBV, and a different value in
project.json cannot deviate (method-context reports it as a blocker).
Step 5: Constraints
Read AGENTS.md sections:
- "Never Do" → blocking constraints
- "Always Do" → derive as warning constraints if they have machine-checkable form
- "Code Style" → derive as warning constraints
Preserve explicit ownership and path exceptions. Do not infer that a directory is disposable solely because it is hidden or named like tool state. Reconcile proposed constraints with explicit project rules and existing tracked paths, and scope each constraint so it does not contradict a documented exception.
Apply the command environment policy from Step 3 to every compiling command: or
workflow trigger emitted in this file.
If no AGENTS.md, use generic constraints from
skills/kbd-init/references/constraints.md in this project.
Step 6: VSCode Workspace Discovery
Search for a .code-workspace file starting from the focus project's parent directory:
<focus_project_path>/../*.code-workspace<focus_project_path>/../../*.code-workspace<focus_project_path>/*.code-workspace
If found, read all folders entries and auto-assign roles:
| Heuristic | Role |
|---|---|
Folder IS the focus project (cwd or contains AGENTS.md) |
focus |
Folder name contains MVP, legacy, spec, reference, old |
reference |
| Otherwise | Ask user: focus / reference / ignore |
For reference folders, detect useful read paths:
src/pages/Doc*.jsx,src/pages/DocPage*.jsx— legacy spec filesdocs/**/*.md— documentation- Root
*.mdfiles — readme/specs
Write the workspace block to project.json. If not found, set
workspace.workspace_file = null and use single-project mode.
See skills/kbd-init/references/workspace-context.md for the full specification.
Step 7: Agent Preferences
If AGENTS.md contains an "Agent-Specific Notes" section referring to specific
tools, use those to populate preferred_planning_agent and
preferred_execution_agents. Otherwise default to a sensible planning agent
name for this harness and leave execution as an empty list.
Output: .kbd-orchestrator/project.json
Generated from skills/kbd-init/references/schemas/project.template.json with
discovered values and conforming to
skills/kbd-init/references/schemas/project.schema.json:
{
"name": "<discovered project name>",
"description": "<discovered one-line description>",
"activePhase": null,
"verificationMethod": "VLBV",
"focus_project_path": "<absolute path to focus project root>",
"spec_paths": ["<discovered spec paths>"],
"openspec_available": true,
"constraint_file": ".kbd-orchestrator/constraints.md",
"build_health_command": "<detected build command>",
"test_command": "<detected test command>",
"lint_command": "<detected lint command>",
"dev_command": "<detected dev command or null>",
"preferred_planning_agent": "<from AGENTS.md or a sensible default>",
"preferred_execution_agents": ["<from AGENTS.md or empty>"],
"agents_config": { "...": "..." },
"workspace": {
"workspace_file": "<path to .code-workspace or null>",
"folders": [
{ "path": "<focus>", "role": "focus", "write_access": true },
{
"path": "<reference>",
"role": "reference",
"write_access": false,
"purpose": "<what to read from here>",
"read_paths": ["<glob>"]
}
]
}
}
Output: .kbd-orchestrator/constraints.md
Generated from skills/kbd-init/references/constraints.md in this project, with
project-specific blocking rules derived from AGENTS.md's "Never Do" section.
Mandatory command environments apply to every affected command in this file, and
documented path-ownership exceptions remain explicit.
Post-generation Validation
After writing both files, run the validator bundled beside this SKILL.md:
node skills/kbd-init/scripts/kbd-init-validate.mjs "<project-root>"
Resolve skills/kbd-init/scripts/kbd-init-validate.mjs from this project's
own root. The validator checks JSON readability and mandatory Cargo
environment propagation. It never writes project files.
- A configuration error is fatal: correct it before emitting the completion progress signal.
- An unavailable external prerequisite is non-fatal for initialization. Preserve
the configured path and report:
initialization complete; execution blocked: required path unavailable: <path>. - When prerequisites are available, report that execution prerequisites are ready.
Idempotency
- If
.kbd-orchestrator/project.jsonalready exists, print a diff of what would change and ask for confirmation before overwriting. - Using
/kbd-init --forceskips confirmation and overwrites. - Running
/kbd-init --dry-runprints the discovered values without writing files. Apply the same command-policy and prerequisite checks in memory, including the execution-blocked warning when an external path is unavailable.
Progress Signals (MANDATORY)
Before any other action, emit:
Starting kbd-init — <project-name or argument>
When all steps are complete, emit:
Completed kbd-init — <project-name or argument>
Use the project name from the argument or the discovered project name. Emit to plain response text — no tool call needed.
How to invoke
/kbd-init # Auto-discover everything
/kbd-init "HotSeaters" # Override project name
/kbd-init --force # Overwrite existing project.json
/kbd-init --dry-run # Preview without writing
/kbd-init --spec-engine speckit # Use GitHub Spec Kit instead of OpenSpec
After Init
Run /kbd-status to confirm KBD is correctly initialized, then start the
first phase — or run /kbd-assess directly if a phase is already defined in
activePhase (readers also accept the legacy active_phase alias).
Selected-method recovery and authority
Before dependent work, run node <pack-root>/scripts/kbd-method-context.mjs --project <project-root> --phase <canonical-phase-id> --write (or read the phase-local method-context.md when Node is unavailable) and act on its status:
RESOLVED_REFERENCES— continue with the recovered method, contract and stage authority; preserve the same references in role inputs, dispatch and handoff read order.BLOCKED— the contract, its binding, a calibration reference, a supersession or a deviation's cadence/reason is missing or changed, or canonical status is unavailable; resolve it explicitly. Prior commands, memory and tool inventories are not fresh authority.CONFLICT— a governing rule file the active harness loads grants an exception VLBV forbids (for example a compiler check or an hourly integration gate during generation). Stop before dependent work and show the conflict; continue only after the operator records aKBD-POLICY-ACKdecision for that file's current hash. Never rewrite operator-owned policy, and never treat an exception as authority for tests, builds, dry-runs or generated-code verification.
VLBV is the method for every phase (project default verificationMethod: "VLBV"); a deviation exists only as a signed KBD-METHOD decision naming the method, its execution cadence and its reason, and it is disclosed in the closure packet. Define acceptance before generation; generated code executes only at the value-phase boundary (B4) and, after an authorized repair, at B5 — see kbd-process-orchestrator/references/boundaries.md. Tasks, hours, commits, reviewer requests and compiler problems create no boundary. Preserve original evidence, consumed budgets and unresolved effects across resume and supersession; reconcile an uncertain effect before any retry. Full rules: kbd-process-orchestrator/references/method-context.md.
Host policy discovery
At this stage also discover the project's governing host instructions and the actual host capability (instruction-only, observed, enforced within a named boundary, or unsupported), and report an existing policy conflict, such as a compiler exception under VLBV, before dependent execution.