Skip to main content
/pm:init bootstraps PM in your project. Run it once in any directory — it creates the .conductor/ state directory, scans for existing OpenSpec proposals to register as epics, writes the managed rules block into CLAUDE.md, and renders the initial PROJECT.md. Until you run this command, all of PM’s hooks stay dormant in your project, so this is always your first step. Before scaffolding, your agent should also load the conductor skill — the agent-facing how-to (mental model, lanes, statuses, the detour → PUSH/POP → reconcile workflow). For deeper reference beyond that skill and README.md, llms.txt is a lightweight (~7KB) index of every doc page on this site; llms-full.txt is the entire site as one document (~200KB, tens of thousands of tokens) — fetch it only if you genuinely need the complete reference, not as a default.

​
What it creates

.conductor/state.json

The single source of truth for every epic, the detour stack, tracker config, and the pmVersion stamp. All engine operations read and write this file.

CLAUDE.md rules block

A managed section injected into your project’s CLAUDE.md that carries the PM discipline — lanes, statuses, detour workflow, and decision rules — into every Claude Code session automatically.

PROJECT.md

A generated project briefing view rendered from state.json. Re-rendered on every /pm:status, /pm:sync, and /pm:upgrade call.

​
What happens during init

1

Engine scaffolds state

The conductor engine creates .conductor/state.json with an empty epic index, an empty detour stack, and a pmVersion stamp matching your installed version.
2

Scans for existing work

PM scans for OpenSpec change directories (openspec/changes/<id>/). Any found are registered as untriaged epics in the openspec lane so no prior work is lost.
3

Writes the CLAUDE.md rules block

The managed rules block is inserted into CLAUDE.md (or the file is created if it doesn’t exist). The block is delimited so future /pm:upgrade calls can refresh it without touching your surrounding content.
4

Renders PROJECT.md

The engine renders the initial project briefing from state, giving you a human-readable snapshot of every registered epic and the current detour stack (empty at this point).
5

Offers tracker mirroring (conditional)

If PM detects real signals of active issue-tracker usage — a connected tracker MCP, issue-key conventions in your history, or an explicit note in your codebase — it offers to connect an external mirror. Being hosted on GitHub, GitLab, or Bitbucket is not a signal. Saying no loses nothing; PM tracks everything locally regardless.
6

Asks for the execution profile (0.51.0)

init writes no model on its own — it asks, and records what you choose with set-profile. As of 0.52.0 it recommends accepting the built-in defaults, which records nothing (plan opus high, implement sonnet medium, test sonnet low, review opus high, mechanical sonnet low, rudimentary haiku; see /pm:profile). Before 0.52.0 it recommended opus at medium effort for the three roles then existing, and offers a cheaper option as an alternative: sonnet for implement and haiku for test (haiku takes no effort; every other model needs one). It also offers lane overrides, such as a lower review for the claude-code lane. If you decline, nothing is recorded and every field resolves to its default. See /pm:profile.
7

Shows /pm:status output

Init finishes by printing the full conductor briefing so you can see your registered epics and immediately begin triage.

​
After init

Once init completes, PM prompts you to triage your epics. Triage means:
  • Designating exactly one epic as active (the thing being built right now)
  • Assigning each epic a priority of P0, P1, P2, or P3
  • Setting each epic’s status to active, queued, or later
Until you triage them, any epics discovered during the scan sit in the untriaged lane. PM won’t recommend untriaged epics via /pm:next — triage is the gate that admits work into the priority queue.

​
Session files are git-ignored (0.51.0)

init writes pm’s per-checkout files into .gitignore by name, .conductor/brief.txt, .conductor/write-conflicts.log.prev and .conductor/honcho-memories.log among them, instead of relying on a global *.log rule. An ignore line does nothing for a file git already tracks, so when any of them is in the index init prints an ⚠ UNTRACK PM'S SESSION FILES block with the exact git rm -r --cached line and a commit line. pm never runs it. See /pm:upgrade.

​
Idempotency

If .conductor/state.json already exists, init is a complete no-op — you can re-run it safely. If you genuinely need to reset your project’s PM state, delete .conductor/state.json and run /pm:init again, though this is rarely the right move. For version migrations after installing a new PM release, use /pm:upgrade instead — it preserves your epic history and runs the correct migration scripts.

​
What init refuses (0.44.0)

init takes no positional arguments and one flag of its own, --platform <claude-code|hermes|codex> (see /pm:upgrade), plus the --force every mutating verb accepts. A valueless or unknown --platform, or any other flag, is refused before anything is created, so a failed init leaves no .conductor/ behind to end pm’s dormancy: conductor: --platform must be one of claude-code|hermes|codex. It used to create .conductor/state.json first and then exit 1. init --help prints its flags and creates nothing. init refuses, with exit 11 and nothing written, in two more cases — both mean a file it depends on is in a state the engine will not guess about, and a human fixes the file:
  • .conductor/state.json exists but cannot be read (conflict markers, truncation, the wrong shape). init loads it before its first write, so it never writes over, beside or around it — not even .gitignore. The refusal names the reason and the remedies (see /pm:gate-guard for the full message). For a file git has never had, move it aside and re-run: mv .conductor/state.json .conductor/state.json.damaged, then /pm:init.
  • The rules file’s managed-block markers are ambiguous. A BEGIN marker line with no END, an END with no BEGIN, or two blocks. Markers are whole lines — a marker string quoted in prose or inline code is ordinary text. The check runs before anything is created, so a fresh repo gets no .conductor/:
    Delete the stray lines by hand, then run init again.

​
Example output after init

PM’s hooks stay dormant in your project until /pm:init runs. This is intentional, matching the same design as openspec init. Running init is what arms the hooks for all future sessions.