@kontextmind/kxm 0.6.0 → 0.7.0

package/.claude-plugin/marketplace.json

@@ -11,7 +11,7 @@
       "name": "kxm",
       "source": "./plugins/kxm",
       "description": "Durable workflows, peer agents, and kxm tui",
-      "version": "0.6.0",
+      "version": "0.7.0",
       "category": "development",
       "tags": ["kxm", "multi-agent", "workflows", "mcp"]
     }

package/.kxm/agents/coordinator.yaml

@@ -0,0 +1,9 @@
+schema: kxm.agent.v1
+purpose: Coordinate the pinned workflow and emit schema-validated commands.
+tools:
+  preset: coordinator
+defaultRepositoryAccess: read
+repositories:
+  control: read
+network: provider-only
+resultSchema: kxm.assignment-result.v1

package/.kxm/agents/critic-arch.yaml

@@ -0,0 +1,13 @@
+schema: kxm.agent.v1
+purpose: Architecture critic for the approved workflow change.
+harness: claude
+model:
+  provider: anthropic
+  model: fable
+tools:
+  preset: read-only
+defaultRepositoryAccess: read
+repositories:
+  control: read
+network: provider-only
+resultSchema: kxm.assignment-result.v1

package/.kxm/agents/critic-cli.yaml

@@ -0,0 +1,13 @@
+schema: kxm.agent.v1
+purpose: CLI and verification critic for the approved workflow change.
+harness: codex
+model:
+  provider: openai
+  model: gpt-5.6-sol
+tools:
+  preset: read-only
+defaultRepositoryAccess: read
+repositories:
+  control: read
+network: provider-only
+resultSchema: kxm.assignment-result.v1

package/.kxm/agents/implementer.yaml

@@ -0,0 +1,13 @@
+schema: kxm.agent.v1
+purpose: Implement the approved change within the declared repository scope.
+harness: grok
+model:
+  provider: xai
+  model: grok-4.6
+tools:
+  preset: workspace-writer
+defaultRepositoryAccess: none
+repositories:
+  control: write
+network: provider-only
+resultSchema: kxm.assignment-result.v1

package/.kxm/gates.yaml

@@ -0,0 +1,8 @@
+schema: kxm.gate-registry.v1
+gates:
+  test:
+    kind: command
+    argv:
+      - npm
+      - test
+    timeoutMs: 3600000

package/.kxm/producers.yaml

@@ -0,0 +1,22 @@
+schema: kxm.producers.v1
+updatedAt: 2026-09-10T17:30:00.000Z
+promoted:
+  - anthropic/fable
+  - openai/gpt-5.6-sol
+  - xai/grok-4.6
+  - openrouter/qwen/qwen3-coder-plus
+demoted: []
+enabled:
+  - anthropic/fable
+  - openai/gpt-5.6-sol
+  - xai/grok-4.6
+  - openrouter/qwen/qwen3-coder-plus
+disabled: []
+roles:
+  implementer:
+    - xai/grok-4.6
+    - openrouter/qwen/qwen3-coder-plus
+  critic-arch:
+    - anthropic/fable
+  critic-cli:
+    - openai/gpt-5.6-sol

package/.kxm/project.yaml

@@ -0,0 +1,15 @@
+schema: kxm.project.v1
+id: prj_kxm_project
+name: KXM
+defaultWorkflow: default
+defaultExecutor: local
+defaultHarness: pi
+repositories:
+  - id: control
+    role: control
+    required: true
+    pathHint: .
+workspace:
+  dirtySnapshot:
+    untracked: ask
+    dirtySubmodules: fail

package/.kxm/roles/writer.yaml

@@ -0,0 +1,5 @@
+schema: kxm.role.v1
+id: writer
+roster:
+  - model: openrouter/qwen/qwen3-coder-plus
+    enabled: true

package/.kxm/workflows/default.yaml

@@ -0,0 +1,47 @@
+schema: kxm.workflow.v1
+description: Canonical 4-stage KXM delivery workflow
+coordinator: coordinator
+limits:
+  maxTransitions: 8
+steps:
+  - id: implement
+    kind: agent
+    agent: implementer
+    maxAttempts: 3
+    on:
+      passed: review-arch
+      failed:
+        target: $terminal
+        terminalStatus: failed
+  - id: review-arch
+    kind: agent
+    agent: critic-arch
+    maxAttempts: 2
+    on:
+      passed: review-cli
+      failed:
+        target: implement
+        maxTransitions: 2
+  - id: review-cli
+    kind: agent
+    agent: critic-cli
+    maxAttempts: 2
+    on:
+      passed: verify
+      failed:
+        target: implement
+        maxTransitions: 2
+  - id: verify
+    kind: gate
+    gate: test
+    expect: pass
+    repositories:
+      control: write
+    maxAttempts: 2
+    on:
+      passed:
+        target: $terminal
+        terminalStatus: completed
+      failed:
+        target: implement
+        maxTransitions: 2

package/CHANGELOG.md

@@ -4,15 +4,36 @@ All notable user-facing changes are documented here. The project follows [Semant
 
 ## Unreleased
 
+## 0.7.0 - 2026-09-11
+
 ### Added
 
-- **Public npm release automation unlatched (E7):** Unlatched `publish-npm` job
-  in `.github/workflows/release.yml` with `environment: npm-publish`. Added
-  `scripts/kxm-publish-npm.mjs` to enforce fail-closed verification: requires the
-  GitHub release for the tag to be published (`draft: false`), validates the
-  release asset presence and SHA-256 digest against the release manifest, and
-  executes `npm publish --access public`. Added `publishConfig.access: "public"`
-  in root `package.json` and unit test suite `test/core/kxm-publish-npm.test.ts`.
+- **vNext Architecture Engine and Multi-Phase Isolation (Phases 0–4):**
+  - **Dead Route Brake (Phase 0):** Fails closed and asserts 404 on obsolete `/dispatch`
+    endpoint in supervisor API to eliminate legacy unmonitored dispatch routes.
+  - **Objective Propagation (Phase 1):** Propagates accepted run objectives into the producer
+    context packet with cryptographic SHA-256 hash validation against execution drift.
+  - **Dynamic Permission Ceilings (Phase 2):** Dynamically derives sandbox permissions from step
+    repository access declarations (`birthMember`), failing closed immediately on unauthorized
+    live write access outside declared repository scopes.
+  - **Pinned Route Admission & Roster Verification (Phase 3):** Strictly validates producer model
+    resolution (`step.model -> agent.model -> refuse`), enforcing model admission policies and role
+    roster alignment before birth.
+  - **Asynchronous Scheduler & Graceful Lifecycle (Phase 4):** Asynchronous `/drive` execution via
+    `VnextRunScheduler` returning `202 Accepted` with `/v1/runs/:id` poll endpoints, duplicate run
+    rejection (`409 Conflict`), and supervisor graceful shutdown that awaits active drives.
+- **Oneshot Harness Isolation, Pricing Safety & Async Probes:**
+  - Standardized one-shot harness execution across Anthropic Claude, OpenAI Codex, Kimi, and Google AGY
+    with unmetered subscription vs metered cost separation, process stdin piping, and timeout protection.
+- **Universal KontextMind Knowledge-Plane Skill Suite:**
+  - Portable, harness-agnostic skill suite under `.agents/skills/` including repository delivery skills,
+    context memory recall, and lifecycle governance.
+- **Pi Workflow Progress TUI & Studio Dashboard:**
+  - Interactive Pi extension workflow progress terminal user interface with live status bars and web studio layout.
+- **Public npm Release Automation Unlatched (E7):**
+  - Unlatched `publish-npm` job in `.github/workflows/release.yml` with `environment: npm-publish`.
+  - Added `scripts/kxm-publish-npm.mjs` verifying published GitHub release assets, digests, and
+    publishing to npm registry.
 
 ## 0.6.0 - 2026-09-08
 
@@ -109,6 +130,17 @@ All notable user-facing changes are documented here. The project follows [Semant
 
 ### Fixed
 
+- **Windows Claude Code / npm shim detection (issue #168):** `kxm harness list`
+  treated Claude Code as `not_detected` when the CLI was only an npm
+  `claude.cmd` shim (no `claude.exe` on `PATH`). The probe now tries `.exe`,
+  then the allowlisted inner package `claude.exe` next to `claude.cmd`, then
+  `.cmd` on win32. Allowlisted `name.cmd` probes still use `shell: true` and
+  record `windows_shim` when that is what answered. Auth still requires
+  parseable `claude auth status`. Headless assignment (`just assign` /
+  `harness-run`) scans every PATH directory for `name.exe` before any `.cmd`
+  (so a user-bin `codex.cmd` cannot hide `codex.exe`), then unwraps the inner
+  npm `claude.exe` and Pi's `node.exe` plus `cli.js`, without running
+  unverified `.cmd` launchers through a shell.
 - Concurrent Runtime registry and event-store initialization now checks and
   creates the schema under one write transaction, preventing duplicate-table
   failures when a supervisor and status reader first open the same database.

package/README.md

@@ -214,6 +214,7 @@ The hub routes messages; it does not merge contexts, choose tasks, or bypass too
 | Complete a Pi-to-Pi or Pi-to-Claude setup | [Getting started](docs/getting-started.md) |
 | Configure the hub or an agent | [Configuration reference](docs/configuration.md) |
 | Understand components and message flow | [Architecture](docs/architecture.md) |
+| Learn about agent skills | [Agent Skills](docs/agent-skills.md) |
 | Run the hub responsibly | [Operations guide](docs/operations.md) |
 | Fix connection or delivery problems | [Troubleshooting](docs/troubleshooting.md) |
 | See which behaviors and examples are verified | [Test matrix](docs/test-matrix.md) |

package/docs/README.md

@@ -8,6 +8,7 @@ This documentation is organized by task. Start with the guide that matches what
 | [Getting started](getting-started.md) | Pi and Claude Code users | Complete the first successful multi-agent exchange |
 | [Configuration](configuration.md) | Users and operators | Understand every supported setting and default |
 | [Architecture](architecture.md) | Maintainers and integrators | Learn the component boundaries and message lifecycle |
+| [Agent Skills](agent-skills.md) | Users and integrators | Comprehensive skill suite covering all KXM commands with progressive disclosure |
 | [Operations](operations.md) | Hub operators | Run, monitor, secure, and recover the service |
 | [Troubleshooting](troubleshooting.md) | Everyone | Diagnose common installation and delivery failures |
 | [Test matrix](test-matrix.md) | Users and maintainers | Map features and use cases to automated evidence |
@@ -17,6 +18,7 @@ This documentation is organized by task. Start with the guide that matches what
 | [Workflow guide](workflow-guide.md) | Workflow designers and operators | Area -> Workflow -> Stage -> Role taxonomy with documentation slugs, dated research candidates, and selection policy |
 | [Agent Envelopes & Quality Gates](agent-communication-envelopes-and-gates.md) | Multi-agent workflow engineers | Production communication envelopes, quality gates, and work loops |
 | [Assignment runner](assignment-runner.md) | Maintainers and developers | Native developer assignments, deterministic witness verification, and multi-vendor dual-critic acceptance |
+| [This host's Pi packages](operator-pi-packages.md) | Maintainers on this development host | Snapshot of operator `pi list` packages and file extensions; not a KXM install requirement |
 | [vNext contract package](vnext/README.md) | Maintainers and reviewers | Review the accepted local-first target architecture and implementation contracts |
 
 Project-level policies live at the repository root:

package/docs/agent-skills.md

@@ -0,0 +1,118 @@
+# KXM Agent Skills
+
+This document describes the bundled KXM Agent Skills suite: focused skills
+that cover current KXM top-level command groups. The suite documents the
+existing CLI. It does **not** land unified YAML role/project/workflow
+authority, admit new writers, or replace trusted `.kxm/roster.json` policy.
+
+## Feature-to-Skill Matrix
+
+| Feature Area | Skill | Commands Covered | Purpose |
+|---|---|---|---|
+| Core Routing | `kxm` | — | Select the right suite skill; state universal safety rules and portable CLI convention |
+| Project Setup | `kxm-project-setup` | `init`, `migrate`, `trust`, `config`, `completion` | Initialize, migrate, review permission changes, configure, and add shell completion |
+| Harness & Auth | `kxm-harness-auth` | `harness`, `auth`, `update`, `runtime`, `agent` | Inspect authenticated harness capability and operate supported runtimes/workers |
+| Hub Operations | `kxm-hub-ops` | `hub`, `backup`, `restore` | Run and protect the local hub and its durable SQLite state |
+| Session Management | `kxm-session` | `session`, `dash`, `studio` | Resume/inspect operator work and use UI capabilities each harness supports |
+| Peer Communication | `kxm-peer` | `peer` | Discover, send, poll/await, cancel, fan out, inbox, and reply safely |
+| Workflow Management | `kxm-workflow` | `workflow`, `gate` | Operate webhook workflows, waits/signals, evidence checkpoints, provenance |
+| Definitions | `kxm-definitions` | `role` | Manage role YAML through configuration commands; role edits do not grant trusted writer admission |
+| Run Management | `kxm-runs` | `run`, `runs` | Create and inspect local vNext runs while preserving execution boundaries |
+| Context & Memory | `kxm-context-memory` | `context`, `memory` | Query role-aware context and manage Git-authored memory proposals |
+| Skill Lifecycle | `kxm-skill-lifecycle` | `skills` | Govern candidate/evaluate/promote/reject/verify lifecycle |
+| Routing & Improve | `kxm-routing-improve` | `routing`, `improve` | Inspect real route quality/cost and propose reviewed improvements |
+| Tasks & Goals | `kxm-tasks` | `suggest`, `goal`, `task` | Recommend workflows and manage goals/tasks with SCM/tracker boundaries |
+
+## Installation and Discovery
+
+### For Pi Users
+
+Pi automatically discovers skills in the `pi.skills` section of `package.json`. The KXM skills are included in the standard distribution:
+
+```json
+{
+  "pi.skills": [
+    "./plugins/kxm/skills"
+  ]
+}
+```
+
+### For Claude Users
+
+Claude plugins package the authored skills from `plugins/kxm/skills/` during the build process.
+
+### For Other Harnesses
+
+Skills in `.agents/skills/` follow the standard agent skill format. Discovery
+outside Pi and Claude remains harness-specific; do not assume every consumer
+loads this mirror.
+
+## Progressive Disclosure Usage
+
+1. Start with the core `kxm` skill to choose a specialized skill.
+2. Use the named skill for that command group.
+3. Teach only verbs and options that exist in `kxm <group> --help`.
+
+### Example Usage Patterns
+
+```bash
+kxm peer list --json
+kxm peer send --target alice --content "Please review" --json
+kxm workflow list --json
+kxm workflow checkpoint run_123 stage_a passed "Completed stage A" --json
+```
+
+## Verified vs Unverified Harness Limits
+
+### Verified Harnesses
+
+- **Pi**: Discovers `plugins/kxm/skills`
+- **Claude**: Plugin packaging of the authored skills
+- **Codex**: Consumes the generated `.agents/skills` mirror and AGENTS command block
+
+### Unverified Harnesses
+
+The following harnesses have discovery claims that remain explicitly unverified:
+
+- **Kimi**: `.agents/skills` consumer capability unverified
+- **Copilot**: Integration capability unverified
+- **OpenCode**: Compatibility unverified
+- **Other `.agents/skills` consumers**: Capabilities unverified
+
+## Distinguishing Operational vs Governed Skills
+
+### Bundled Operational Skills
+
+The skills in this suite (`kxm-*`) are bundled and operational by default. They map 1:1 with KXM's top-level command groups and are maintained as part of the core KXM distribution.
+
+### Governed Candidates
+
+Separately, `kxm skills` manages community or experimental candidates through
+create/evaluate/promote/reject/verify. Those governed skills are distinct from
+this bundled suite. Telemetry cannot auto-promote a skill.
+
+## Development and Maintenance
+
+### Authoring Location
+
+Skills are authored in `plugins/kxm/skills/` as the primary source of truth.
+
+### Generated Mirror
+
+`scripts/emit-codex-artifacts.mjs` copies owned skills byte-for-byte to
+`.agents/skills/` and leaves unrelated skills in that tree untouched. The
+suite manifest `plugins/kxm/skill-suite.json` is required; missing, symlink,
+or malformed manifests fail closed.
+
+### Build Process
+
+1. Validate `plugins/kxm/skill-suite.json`
+2. Replace owned generated skill directories
+3. Preserve foreign skills in `.agents/skills/`
+4. `scripts/check-generated.mjs` requires every owned mirror path
+
+### Testing
+
+- `test/core/skill-suite.test.ts` validates command coverage and mirrors
+- `test/core/commands-policy.test.ts` checks taught verbs against `cli.ts`
+- `test/core/generated-artifacts.test.ts` checks manifest-backed generated paths

package/docs/architecture.md

@@ -163,7 +163,7 @@ Workflow session isolation is a context-routing and accidental-cross-run safety
 
 | Path | Responsibility |
 |---|---|
-| `.kxm/config/` | Tracked workspace workflow and harness configuration |
+| `.kxm/` | Tracked workspace workflow and harness configuration |
 | `.kxm/logs/` | Ignored hub, worker, and Pi process logs |
 | `.kxm/assets/` | Intentional workflow inputs and outputs |
 | `.kxm/state/` | Ignored SQLite and restart-recovery state |

package/docs/assignment-runner.md

@@ -35,6 +35,17 @@ and models are admitted with strict permission and vendor boundaries:
   a requested harness/model is not in the admitted role lineup, or if permissions
   exceed the admitted ceiling (e.g. attempting to give edit permissions to a
   read-only reviewer).
+- **Trusted roster policy:** Dispatch (`assign` / `run`) and accept load
+  `.kxm/roster.json` through the trusted control Git loader
+  (`loadTrustedRosterPolicy`). Loader errors, missing/empty policy, and
+  malformed policy fail closed with `route_invalid`. There is no raw working-tree
+  JSON fallback and no null-policy acceptance. Tests may inject an explicit
+  policy object; that seam is not a CLI or environment bypass. The witness
+  verifies the bound candidate against the fixed gate (`npm run verify`) and
+  does not itself call the policy loader today. Unified YAML
+  role/project/workflow authority is still open and is not this runner's live
+  source. Passive `schemas/policy-draft` / `validatePolicyDraft` scaffolding is
+  not operator settings and is not admission.
 - **Deterministic witness beats extra models:** Implementers run `npm run verify`.
   Root re-runs the fixed witness. Reviewers verify candidate trees; they do not
   replace tests.
@@ -145,14 +156,16 @@ node scripts/assignment-run.mjs accept \
 
 `accept` validates all acceptance invariants:
 
-1. The commit exists and its tree matches the witness index tree.
-2. The writer record matches the latest passed witness.
-3. Both required critic roles (`review-arch` and `review-cli`) are present.
-4. Both critics judged the exact accepted tree and issued `PASS`.
-5. No unresolved `BLOCK` review exists for the tree in the task directory (unless
+1. Trusted roster policy is loaded and valid **before** acceptance artifacts are
+   written. Failure to obtain required policy refuses acceptance.
+2. The commit exists and its tree matches the witness index tree.
+3. The writer record matches the latest passed witness.
+4. Both required critic roles (`review-arch` and `review-cli`) are present.
+5. Both critics judged the exact accepted tree and issued `PASS`.
+6. No unresolved `BLOCK` review exists for the tree in the task directory (unless
    superseded by an unbroken `rework_of` lineage).
-6. The writer and all critics satisfy pairwise vendor independence.
-7. Writes `accepted.json` (`kxm.task-accepted.v1`) into the task directory.
+7. The writer and all critics satisfy pairwise vendor independence.
+8. Writes `accepted.json` (`kxm.task-accepted.v1`) into the task directory.
 
 ---
 
@@ -206,7 +219,7 @@ The runner fails closed with bounded error codes defined in `RUNNER_CODES`:
 
 | Code | Trigger condition | Remedy |
 |---|---|---|
-| `route_invalid` | Harness/model not admitted in lineup for the requested role, or permission exceeds route ceiling. | Check `.kxm/roster.json` lineup and permissions for the role. |
+| `route_invalid` | Harness/model not admitted in lineup for the requested role, permission exceeds route ceiling, or trusted roster policy cannot be loaded/validated. | Use a trusted clean control checkout; do not dispatch from a dirty implementation branch. Check `.kxm/roster.json` lineup and permissions for the role. |
 | `critic_invalid` | Missing required critic role, duplicate roles, wrong model, or vendor collision between writer and critics. | Ensure independent critics (Fable + Sol) from distinct providers. |
 | `critic_block` | An unresolved `BLOCK` verdict exists for the target tree. | Rework the changes, address findings, and pass review with a `rework_of` link. |
 | `commit_tree_mismatch` | Git commit tree does not equal the witnessed tree. | Commit the exact candidate tree verified by the witness before running accept. |

package/docs/configuration.md

@@ -269,7 +269,7 @@ Global flags: `--json`, `--dry-run`, `--workspace`. Project-root `kxm init` disc
 
 Configure either `KXM_WEBHOOK_WORKFLOWS` or `KXM_WEBHOOK_WORKFLOWS_FILE`, never both. A definition selects a provider source, project, coordinator, event and payload filters, prompt template, and ordered stages. Use `secretEnv` to resolve the workflow-start HMAC secret from another environment variable. Use the optional `signalSecretEnv` for a separate callback secret; otherwise external signals use the workflow-start secret. Do not store either secret in JSON.
 
-See [Webhook workflows](webhook-workflows.md) for the base schema and the complete Jira configuration under `.kxm/config/workflows`. See [Peer provenance and quorum gates](provenance-gates.md) for `evidencePolicies`, `workflowContext`, `evidenceRefs`, and explicit degradation.
+See [Webhook workflows](webhook-workflows.md) for the base schema and the complete Jira configuration under `.kxm/workflows`. See [Peer provenance and quorum gates](provenance-gates.md) for `evidencePolicies`, `workflowContext`, `evidenceRefs`, and explicit degradation.
 
 ## Delivery modes
 
@@ -279,7 +279,7 @@ See [Webhook workflows](webhook-workflows.md) for the base schema and the comple
 | `steer` | An active blocker requires a course change | Deliver at the next decision boundary |
 | `nextTurn` | Information should wait for a later turn | Queue context without immediate work |
 
-`followUp` is the safe default. Use [`.kxm/config/env.example`](../.kxm/config/env.example) as a reference, but load values through your shell, supervisor, container platform, or secret manager. Never commit real tokens.
+`followUp` is the safe default. Use [`.kxm/env.example`](../ .kxm/env.example) as a reference, but load values through your shell, supervisor, container platform, or secret manager. Never commit real tokens.
 
 ## Nous providers (opt-in)
 

package/docs/kxm-handbook.md

@@ -695,7 +695,7 @@ Claude MCP also exposes:
 Set exactly one of:
 
 ```text
-KXM_WEBHOOK_WORKFLOWS_FILE=.kxm/config/workflows/product.json
+KXM_WEBHOOK_WORKFLOWS_FILE=.kxm/workflows/default.yaml
 ```
 
 or:
@@ -712,7 +712,7 @@ required evidence, attempt limits, and optional peer policies.
 Validate before restart:
 
 ```powershell
-kxm gate validate --file .kxm/config/workflows/product.json
+kxm gate validate --file .kxm/workflows/default.yaml
 ```
 
 Secrets belong in environment variables named by `secretEnv` and
@@ -921,7 +921,7 @@ with content hashes. See `docs/skills.md` for the full lifecycle.
 
 ### Reference /fix workflow
 
-`.kxm/config/workflows/fix.json` implements the reference bug-fix flow:
+`.kxm/workflows/default.yaml` implements the reference bug-fix flow:
 read-only exploration, a tests-only reproduction draft, independent two-critic
 `repro-review` that captures the immutable oracle (a sibling API is invalid),
 plan review by independent critics, a human approval gate, bounded rework

package/docs/operator-pi-packages.md

@@ -0,0 +1,63 @@
+# This host's Pi packages
+
+Snapshot of the operator Pi user packages and file extensions on this KXM
+development host (2026-09-10). It is **not** a KXM install requirement and is
+**not** copied by `kxm init`. `pi list` is authoritative; this page is a
+checked-in copy for agents working in this repository.
+
+## User packages (`pi list`)
+
+| Source | Version | What it loads |
+|---|---|---|
+| `npm:pi-antigravity` | 0.7.2 | Antigravity / Cloud Code Assist provider (`./src/index.ts`) |
+| `git:git@github.com:kontextmind/kxm.git@main` | 0.6.0 (`10a1b77` at snapshot) | KXM Pi extension and Agent Skills |
+| `npm:@xynogen/pix-core` | 0.5.38 | pix UI/tool aggregator (`src/extension.ts`); activates bundled pix members, not separate `pi list` sources |
+| `npm:@tian.zuo/pi-antigravity` | 0.10.3 | Antigravity via `agy` stream-json (`./index.ts`) |
+| `npm:@latentminds/pi-quotas` | 0.5.0 | Quota and usage status commands |
+| `npm:pi-provider-kimi-code` | 0.6.12 | Kimi Code provider (`./index.ts`) |
+
+Install roots on this host:
+
+- npm: `%USERPROFILE%\.pi\agent\npm\node_modules\`
+- git KXM: `%USERPROFILE%\.pi\agent\git\github.com\kontextmind\kxm`
+
+Project-local Pi extension (gitignored `.pi/`): `.pi/extensions/rtk.ts` from
+`rtk init --agent pi`. User-level `~/.pi/agent/extensions/rtk.ts` is also
+installed.
+
+## File extensions
+
+Loaded from `%USERPROFILE%\.pi\agent\extensions\` (not shown by `pi list`):
+
+| File | Role |
+|---|---|
+| `rtk.ts` | RTK bash rewrite via `rtk rewrite`; needs `rtk` 0.23 or newer on `PATH` |
+| `quotas.json` | Config for `@latentminds/pi-quotas`, not an extension factory |
+
+`rtk` 0.48.0 is installed as winget `rtk-ai.rtk`. New shells pick up the User
+`PATH` entry. `pix-core` also activates `pix-optimizer`, which can rewrite
+commands for RTK independently of `rtk.ts`.
+
+## Notes
+
+- `pi-antigravity` and `@tian.zuo/pi-antigravity` are different Pi providers.
+  They do not replace the native `agy` harness used by the assignment runner.
+- For KXM development loads, prefer the working tree:
+  `pi --no-extensions -e ./plugins/kxm/src/extension.ts`. Add every required
+  provider extension with another `-e`; otherwise Pi discovery is disabled.
+  See [Troubleshooting](troubleshooting.md#pi-shows-huboff).
+- Refresh this page when `pi list` or
+  `%USERPROFILE%\.pi\agent\extensions\` changes.
+
+## Project-scoped RTK (this checkout)
+
+`rtk init` in this repository (2026-09-10). Not copied by `kxm init`.
+
+| Path | Role |
+|---|---|
+| `RTK.md` | Slim RTK instructions for Codex and `@RTK.md` includes |
+| `AGENTS.md` | `@RTK.md` reference (Codex / Kimi) |
+| `CLAUDE.md` | `@RTK.md` reference (Claude Code) |
+| `.rtk/filters.toml` | Project filter template |
+| `.agents/rules/antigravity-rtk-rules.md` | Antigravity rules |
+| `.pi/extensions/rtk.ts` | Project Pi rewrite extension (gitignored) |

package/docs/skills/repo-work-delivery.md

@@ -0,0 +1,102 @@
+# Repository Work Delivery Skill
+
+## Purpose
+
+`repo-work-delivery` is a reusable skill for converting an engineering request into an evidence-based, executable delivery prompt. It is designed for repository work that may need discovery, official documentation research, phased delivery, validation, pull requests, CI/review follow-through, policy-gated merge, and safe cleanup.
+
+The canonical skill is located at:
+
+```text
+.agents/skills/repo-work-delivery/SKILL.md
+```
+
+## What it does
+
+The skill requires the executor to:
+
+- Inspect repository instructions, architecture, workflow guidance, CI, package manifests, and existing patterns.
+- Identify material ambiguity and ask focused questions only when repository evidence cannot safely resolve it.
+- Select the workflow recommended by the repository’s workflow guide.
+- Assign explicit delivery roles, even when one agent performs several roles.
+- Use a one-shot workflow only for genuinely small, low-risk, self-contained changes.
+- Research fresh official documentation for every materially affected package, framework, SDK, platform, or API.
+- Create and maintain a living Markdown plan for multi-phase work.
+- Deliver buildable and testable phases with coherent commits and incremental pushes.
+- Run targeted and broader validation, record commands and outcomes, and inspect the final diff for security issues.
+- Create a pull request, monitor checks/reviews, apply only bounded low-risk fixes, and stop for user direction when scope or risk materially changes.
+- Auto-merge only where explicit authorization and repository policy allow it.
+- Clean up the workspace only after merge is verified and no local work can be lost.
+
+## Workflow selection
+
+The skill first reads the repository workflow guide. For KXM, that includes:
+
+```text
+.agents/skills/kxm-workflow/SKILL.md
+```
+
+It chooses the least complex safe workflow prescribed by that guidance.
+
+### One-shot work
+
+One-shot is suitable only when all of the following are true:
+
+- Scope is narrow and unambiguous.
+- The change is self-contained and can be validated as a single coherent unit.
+- No migration, public contract, authorization/security, irreversible side effect, or production-rollout complexity is involved.
+- No cross-service coordination is needed.
+- Repository policy does not require a phased plan.
+
+One-shot work still performs discovery, documentation research, focused validation, commit, push, and required PR work.
+
+### Phased work
+
+All other work uses a living plan. Each phase has an objective, owner role, dependencies, expected files, acceptance criteria, test commands, rollback notes when appropriate, commit boundary, and push requirement.
+
+## Required role coverage
+
+The generated prompt assigns relevant roles from this set:
+
+| Role | Primary responsibility |
+|---|---|
+| Delivery lead | Scope, decisions, workflow, plan, and final reporting |
+| Repository analyst | Architecture, instructions, existing patterns, affected paths |
+| Documentation researcher | Fresh official package/API/framework evidence |
+| Implementer | Minimal compatible code and configuration changes |
+| Test engineer | Focused, regression, integration, and acceptance validation |
+| Security reviewer | Secrets, dependencies, input handling, auth, and data-risk review |
+| Release/CI owner | Required checks, CI monitoring, and safe remediation |
+| Reviewer/merge steward | PR, review resolution, policy gates, merge, and cleanup |
+
+## Gap questions
+
+The skill asks the user only when unanswered details would materially affect behavior, scope, data/migration choices, permissions, external integrations, rollout, acceptance criteria, or merge authority. It does not ask for facts that can be established from the repository or official docs.
+
+## Documentation standard
+
+For material dependencies, research uses official maintainer or other authoritative primary documentation for the repository’s actual version. The plan or PR records the source, version/date where available, retrieval date, and decision supported.
+
+## Merge and cleanup safety
+
+Auto-merge happens only after explicit authorization or policy authorization, passing required checks, required approvals, resolved comments, clean security status, and compliance with branch protection.
+
+After verified merge, cleanup is guarded by checks for a clean workspace and fully merged branch. It updates the default branch, removes only safe merged local branches/worktrees, prunes stale references, and never discards uncommitted or user-owned artifacts.
+
+## Expected generated prompt sections
+
+A prompt produced with this skill includes:
+
+1. Desired outcome and acceptance criteria
+2. Gap-resolution gate
+3. Repository discovery
+4. Workflow selection and rationale
+5. Assigned roles
+6. Fresh official documentation research
+7. Scope, non-goals, assumptions, and constraints
+8. Design and integration expectations
+9. One-shot or phase plan
+10. Tests and validation
+11. Commit/push discipline
+12. PR, CI/review monitoring, bounded remediation, and merge gate
+13. Verified post-merge cleanup
+14. Completion report