# Kbd Init

> Use once per project, before any other KBD command — auto-discovers project identity, stack, and constraints from existing context files (AGENTS.md, CLAUDE.md, README.md, package.json, Cargo.toml, pyproject.toml, etc.) and generates .kbd-orchestrator/project.json and .kbd-orchestrator/constraints.md.

- Skill: `prometheus-ags/kbd-init` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx get-skill add prometheus-ags/kbd-init`
- Raw SKILL.md: https://api.skillmd.com/api/skills/prometheus-ags/kbd-init/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: Prometheus-AGS (https://skillmd.com/u/prometheus-ags)
- Updated: 2026-11-18
- Page: https://skillmd.com/skills/prometheus-ags/kbd-init

---


# /kbd-init

Initialize the KBD orchestrator for the **current project**.

> `/kbd-init` owns full project configuration discovery. Phase creation and
> advancement helpers own `project.json.activePhase`, preserve unrelated keys,
> and remove the legacy `active_phase` alias. If metadata is missing, those
> helpers may bootstrap minimal identity and active-phase metadata; this does
> not replace `/kbd-init` for full stack, policy, and constraint discovery.

## OpenSpec lifecycle preflight

Before this stage, follow the [orchestrator preflight](../kbd-process-orchestrator/SKILL.md#openspec-lifecycle-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:

1. `.kbd-orchestrator/project.json` — project context, stack commands, tool preferences
2. `.kbd-orchestrator/constraints.md` — project-specific blocking/warning rules derived
   from `AGENTS.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:

1. Explicit argument: `/kbd-init "My Project Name"`
2. `AGENTS.md` — first H1 or "Project Identity" section
3. `CLAUDE.md` — first H1 or executive summary first sentence
4. `README.md` — first H1
5. `package.json` → `name` + `description`
6. `Cargo.toml` → `[package] name` + `description`
7. `pyproject.toml` → `name` + `description`
8. 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`, `check` script keys
- For Next.js: detect port from `pnpm run dev` script 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.json` command fields,
  every compiling `command:` in `constraints.md`, and every generated workflow
  trigger. For chained commands, apply the required prefix to each affected
  command segment; a prefix on the first `cargo` command does not cover a later
  `cargo` command 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:

1. Check required external roots or mounts for existence and writability.
2. Do not mount storage, create target directories, or substitute a local path.
3. If a required path is unavailable, continue generating configuration and mark
   execution as blocked in the final summary.
4. 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:

1. `openspec/specs/*.md` — if `openspec/` directory exists
2. `docs/specs/*.md` — if `docs/specs/` exists
3. `docs/*.md` — fallback
4. 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.json` already pins
  `specBackend`, or the project already has `openspec/`, a Spec Kit tree
  (`.specify/` or `specs/*/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`):

  ```text
  node "<mini-pack-root>/lib/platform/openspec/cli.mjs" init --project "<project-root>" --tools claude,codex
  ```

  The receipt reports `already-initialized` when `openspec/` 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`** — run `specify init --here --force --non-interactive --integration <harness>`
  (Spec Kit CLI pinned in `config/spec-engines.json`, installed with
  `uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@v1.3.0`).
  If `specify` is 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:

1. `<focus_project_path>/../*.code-workspace`
2. `<focus_project_path>/../../*.code-workspace`
3. `<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 files
- `docs/**/*.md` — documentation
- Root `*.md` files — 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`:

```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`:

```bash
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.json` already exists, print a diff of what
  would change and ask for confirmation before overwriting.
- Using `/kbd-init --force` skips confirmation and overwrites.
- Running `/kbd-init --dry-run` prints 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 a `KBD-POLICY-ACK` decision 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.


