# The System

Project governance for Pi through one `/system` command.

## Commands

- `/system` shows help.
- `/system init [PROJECT-PREFIX]` initializes `.system`, updates machine schema markers, then offers agent-led bundle migration after config schema changes.
- `/system doctor` runs read-only validation.
- `/system view <path|id|slug>` renders one document to temporary HTML.
- `/system edit <path|id|slug>` opens one document in `VISUAL`, `EDITOR`, or a platform editor.
- `/system book` renders the full dossier to temporary HTML.
- `/system board` opens the interactive project board.
- `/system assess [instructions]` assesses implementation progress and proposes board changes.
- `/system research|spec|spec-verify|phase|plan|issue|exec [instructions]` injects stage prompts.

Lifecycle stages never auto-chain.
Agents may recommend the next stage, but humans invoke optional stages.

## Tool

Bundle-authoring commands temporarily enable `system_bundle_slot`.
It remains available through clarification, supports repeated reservations in the authoring run, then deactivates after that run settles.
The agent calls it for each new bundle after choosing a semantic title, then uses the returned ID and path exactly.
Context determines which bundles, if any, the command creates.

Assessment temporarily enables `system_board_propose` through clarification until one proposal submission completes.
Proposals remain ephemeral until a human applies selected changes through `/system board`.
Exec temporarily enables `system_board_update`, which writes verified states directly to `.system/board.json` with `source: agent` and a terse evidence note.
Board invariants reject unsupported claims, and the human overrides any entry in `/system board`.

## Board

Tracked operational state lives in `.system/board.json`; bundle content remains stateless about implementation progress.
Specs and plans use `todo|done`; issues use `open|done`.
Absent entries default to `todo` or `open`.
Each explicit entry records `state`, `updatedAt`, and `source: manual|assess|agent`, plus an optional `note` of at most 200 characters, without duplicating bundle content.
Later writes without a note clear it, so a manual override drops the agent claim.
Lifecycle prompts carry a board state block listing counts and up to 20 unfinished items; it is omitted when the board is unreadable.
The board serves every page from a live snapshot: a request for an HTML page re-renders it whenever any `.system` file changed, and the open page polls `GET /api/state` once per second.
Board state changes patch the page in place; document changes reload it and restore the disclosures that were open.
A plan's metadata box toggles `status` between `draft` and `approved` on disk, and a spec's metadata box toggles its board state.
A spec can be done without plans, but cannot be done while any linked plan is todo.
Spec toggles never change plan states.
Reopening a plan demotes its spec; issues never change spec state.
The board schema version is `0`; `/system init` updates mismatches mechanically before board or assessment can continue.

## Documents

Canonical bundles live at:

```text
.system/<type-plural>/<PREFIX>-<TYPE>-<8CHARS>-<slug>/index.md
```

Type dirs are `research`, `specs`, `phases`, `plans`, and `issues`.
IDs use uppercase `A-Z0-9_-` tokens.
Frontmatter references store IDs only.

Required fields:

- research: `id`, `type: research`, `title`
- spec: `id`, `type: spec`, `title`, optional `research`
- phase: `id`, `type: phase`, `title`, `label`
- plan: `id`, `type: plan`, `title`, `spec`, `status: draft|approved`
- issue: `id`, `type: issue`, `title`, `specs`

Issues intentionally have no status field.
Phases are project-wide operating epochs, not spec decomposition.
The optional config `currentPhase` selects one phase for prompt injection and the Pi footer.
Existing core documents and spec or phase files require one-shot human approval.
Current-phase transitions require human approval.
Approved plans are immutable.
Create a new plan instead.
The config schema version is `0`; a mismatch fails with instructions to run `/system init`.

## Resources

## Debug

Opt-in metadata diagnostics: [debug contract](../DEBUG.md).
Safe events: `session.start`, `session.shutdown`, `command.handle.start`, `command.handle.finish`, `command.handle.error`.

The extension exports no System skills or prompt templates statically.
Resource discovery always exposes the generic, manually invocable `vertical-slices` skill.
For valid initialized projects, it additionally exposes `the-system-gfm`, `the-system-tex`, and `the-system-mermaid`.
Format skills cover syntax and modeling; `/system` stage prompts select formats and govern System documents.
Outside `/system` stages, format skills can also guide related work within a valid System project.
Projects initialized during a live session require `/reload` before those format skills become available.