--- name: kxm-project-setup description: Set up KXM in a new or existing Git repository and run a first workflow, especially with Claude Code. The agent runs kxm init, adds a first workflow from the spec-and-plan template, runs kxm trust diff and check, and drives a model-free first run, while the user starts the hub, installs the kxm Claude Code plugin, and reviews and commits .kxm permission changes. Use when asked to install, set up, onboard, initialize, upgrade, or get started with KXM. --- # KXM project setup and first workflow One guide from a Git repository to a completed first run. Run the agent steps in order and stop at every STOP. Everything under Operator steps is the user's to run in their own terminal or in Claude Code. - Read `kxm --help` before a mutation; flags differ per command. - Never commit `.kxm` changes yourself. The user's reviewed commit is the trust approval, and `kxm trust --help` lists only `diff` and `check`. - Never generate, print, read, or store a hub admin token or project token. ## Agent steps ### Initialize the project 1. `kxm init --dry-run --json` plans without writing. `mode` is `create`, `ready`, `repair`, or `legacy`, and `issues` lists anything to fix first. 2. `kxm init --name ""` prints `initialized KXM project at `. It writes `.kxm/project.yaml`, `.kxm/agents/planner.yaml`, `.kxm/agents/writer.yaml`, `.kxm/gates.yaml`, `.kxm/repo/repo.yaml`, `.kxm/template-provenance.yaml`, and `.kxm/workflows/default.yaml`. Outside Git it fails with `git_root_required`. In an existing project, plain `kxm init` validates, prints `validated KXM project at `, and keeps local edits; there is no `--force`. 3. Add `.kxm/state/` and `.kxm/logs/` to `.gitignore`. `kxm init` writes no ignore rules. 4. `kxm hub view` reads hub health. It exits 1 with `hub health=false` until the user has started a hub; that does not block the first workflow or the first run. 5. STOP. Ask the user to review `.kxm/` and `.gitignore` and commit them. Until they do, `kxm trust diff` fails with `resource_missing` for `.kxm/project.yaml` at base `HEAD`. ### Add a first workflow from a template After the user's commit: 1. `kxm workflow add first --template spec-and-plan` prints `Added workflow 'first' to local (/.kxm/workflows/first.yaml)`. Add `--dry-run` first to see the path without writing. The template has two steps, `plan` then `reviewer-arch`, both run by the `planner` agent with `repositories: control: read`. It writes nothing and runs no test command, and a failed review goes back to `plan` at most twice. 2. `kxm init` validates it and prints `validated KXM project at `. 3. `kxm workflow definitions` lists `default` and `first`. 4. `kxm trust diff`, then `kxm trust check`. Both print `EXPANSION .kxm/workflows/first.yaml added (expansion)` and `1 expansion(s) require explicit reviewed trust action`. `kxm trust check` adds `trust check failed: review every expansion above before merging` and exits 1. 5. STOP. Show the user each EXPANSION line, ask them to review the file and commit it themselves, and wait. Never commit `.kxm` changes yourself; the reviewed commit is the trust approval. ### Drive a model-free first run After the user's commit: 1. `kxm trust check` prints `no authority-bearing or prose changes` and exits 0. 2. `kxm run first "" --dry-run` prints `run plan: workflow first at sha256:… (no run created)`. Keep secrets out of the prompt: its full text is kept on disk (`kxm-runs`). 3. `kxm run first ""` prints `run created: run_ …` and starts the Runtime supervisor. 4. `kxm runs status ` prints `created`. 5. `kxm runs drive --simulated --wait --timeout-ms 60000` prints a `kxm.drive-receipt.v1` whose settlement is terminal `completed`, and exits 0. The run moves from `plan` to `reviewer-arch` to `completed`. Always pass `--simulated`; without it, drive calls live harnesses. 6. `kxm runs status ` prints `completed … (receipt verified)`. 7. `kxm runs receipt ` and `kxm runs list`. Cancel a stuck run with `kxm runs cancel `. 8. `kxm runtime stop` when you are done. To add more workflows, run `kxm workflow add --template ` with `implement-and-verify` (an `implement` step with write access, then the `test` gate) or `dual-critic-review` (`implement`, two reviews, then the `test` gate), or write the YAML by hand; see `kxm workflow add --help`. A gate step runs its command from `.kxm/gates.yaml` even in a simulated drive. Validate any new definition with `kxm init --dry-run --json`, then repeat the trust review and the user's commit. ## Operator steps Ask the user to run these in their own terminal. Never generate, print, read, or store the admin or project token in the conversation. The user enters `auth_token` at the plugin prompt. 1. Create a project token and export `KXM_PROJECT_TOKENS` before starting the hub. The map must list every project's token, because it replaces the saved map rather than merging with it. When a hub already serves other projects, use the merge command in the KXM documentation's Claude Code quick start (docs/start/quickstart-claude-code.md, section "Start the hub"). 2. `kxm hub start` in a second terminal. It generates and persists an admin credential in `hub-env.json` under the user state root; that token never goes to an agent. 3. `kxm hub bind http://127.0.0.1:7331`. 4. In Claude Code, `/plugin marketplace add kontextmind/kxm`, `/plugin install kxm@kxm`, then `/plugin configure kxm@kxm` for `server_url`, `auth_token`, `agent_name`, `agent_purpose`, and `project`. 5. Review and commit `.kxm/` and `.gitignore` after `kxm init`, and every `kxm trust diff` EXPANSION after adding a workflow, for example `git add .kxm .gitignore && git commit`. 6. `kxm session token --clear` when kxm_* tools report `tool_policy_denied` for an expired or malformed session token file. 7. `kxm session brief`, in any form including `--status`. Until kxm session brief stops minting tokens, running it saves a 24-hour operator session token; when that token expires every kxm_* tool fails with tool_policy_denied. ## Pitfalls - `kxm init` says `legacy state is not migrated by this build`: run `kxm init --dry-run --json` and fix every listed issue whose code is not `legacy_state_unsupported`, for example a `schema_additionalProperties` typo in a workflow step, then run `kxm init` again. Only when `.kxm/project.yaml` does not exist yet, ask the user to follow the README's move-aside workaround; never do that in a committed project. - The template `default` workflow can be driven, but even a simulated drive runs its `npm test` gate, and a live drive spends Claude and Grok and lets Grok edit the checkout. Use `first` for the first run. - `kxm run` starts the Runtime supervisor. Stop it with `kxm runtime stop`. - Only run workflow IDs that `kxm workflow definitions` lists; any other ID fails with `run_workflow_unknown`. - `kxm workflow list` shows hub webhook runs, not these runs; use `kxm runs list`. - `KXM_SKIP_COMPLETION_PROMPT=1` and `KXM_SKIP_GUIDE_SETUP_PROMPT=1` suppress the interactive offers after `kxm init`. ## Commands | Command | Purpose | Options / arguments | |---|---|---| | `kxm init` | Create, validate, repair, or join a KXM project (a legacy tree is reported as `mode: "legacy"` and never converted) | `--json`, `--dry-run`, `--name`, `--project-id`, `--repository ` | | `kxm trust diff` | Structured permission diff against a Git revision | `--base ` (default `HEAD`) | | `kxm trust check` | Exit 1 when the working tree expands permissions | `--base ` (default `HEAD`) | | `kxm config get ` | Get a configuration value | `--json` | | `kxm config set ` | Set a configuration value | `--scope user\|project` | | `kxm config list` | List resolved configuration | `--json` | | `kxm completion install` | Install tab completion for the detected shell and ensure kxm is on `PATH` | `--shell `, `--no-path`, `--dry-run`, `--json` | `kxm completion ` prints the script without installing it. `kxm trust` reviews configuration permission diffs; it does not add website domains. `kxm init` is project-only and does not start the hub.