--- type: Reference title: "PMOS Portable Kit (file mode)" timestamp: 2026-07-23 --- # PMOS Portable Kit (file mode) Run the PMOS workflow — initiative → PRD → eval rubric → pre-run contract → build → Quality/Review/Acceptance gates — **entirely inside this repo**, with every piece of state as git-versioned files. No database, no MCP connection, no network calls to any PMOS backend (D54). Built for products whose data must not leave their own remote (e.g. company-owned products vs a personally-owned PMOS backend). ## What's in the folder - `AGENTS.md` — the run protocol. **Start here; every agent session reads it first.** Contains the state adapter: the table mapping each hosted PMOS tool to a file convention. - `AGENTS-HUMAN.md` — the same loop for a **human** builder (D58): plain terms + the `scripts/pmos-log.sh` helper that appends validated state records in one command. Mixed human+agent teams share the same state. - `SECURITY.md` — the kit's **security posture**: skills are executable instructions, what the kit does structurally to be safe to install, and what stays your responsibility. Read it before you install skills into your agent. - `skills/` — the PMOS skill kernel (prd, eval-rubric, okr, evaluator, …). Single-sourced from the PMOS repo; where a skill names a hosted tool, apply the AGENTS.md state adapter. - `skills-native/` — the same skills in **Agent-Skills standard** form (`/SKILL.md` directories), generated from `skills/` so a Claude Code / Codex / skills.sh harness can load them. The flat `skills/` files stay the source of truth; this is the portable mirror. - `okf/core/` — kernel concepts (the sdlc loop, the three-tier gate, watermelon flags, …). `okf/product/` — YOUR product's knowledge; drafted by ingest, approved via PR review. - `planning/` — okrs, PRDs, rubrics (`agent-run-eval-rubric.md` is the per-initiative template), `eval-calibration.md` (append every PM override of an evaluator verdict). - `state/` — the operational record, **append-only**: `initiatives/.md`, `runs.jsonl`, `evals.jsonl`, `acceptances.jsonl`, `discoveries.md`. `tickets/NNN-slug.md` decompose an initiative into ordered, dependency-numbered work (file-mode's board — see AGENTS.md). - `scripts/` — `gate-initiative.sh` (the fail-closed CI gate), `metrics.py` (north star + calibration + Goodhart tripwire), `kit-update.sh` (kernel refresh), `frontier.sh` (lists the workable tickets — those not done whose blockers are all done), `workflow-sweep.js` (audits the state everything above derives from — see below), plus `workflow-state.js`, `anchor-resolve.js` and `delivery-index.js`, the readers it and the ladder share. - **`scripts/workflow-sweep.js` — the state audit.** Everything PMOS reports is *derived*, which makes it self-maintaining and does **not** make it self-correcting: a derivation is only as true as what it reads. Run `node pmos/scripts/workflow-sweep.js` to find state that misreports — ledger lines that do not parse (every reader drops them silently, so a torn acceptance reads as "never accepted"), rows naming an initiative that does not exist, duplicate `run_id`s, records pointing at files nobody wrote, merged branches with no record. It separates two things and never mixes them: a **defect** is state that contradicts reality — the board is lying — and an **owed** finding is work that honestly has not happened. `--fix` repairs only the mechanical defects (a stale pointer, text an earlier commit can restore); it **never** writes a run, an eval, an acceptance or any `.jsonl`, because a tool that closes your loops by writing the rows produces a green board out of evidence nobody produced. `--gate` exits non-zero on defects only, so it can run in CI without failing on your backlog. - `templates/pmos-gate.yml` — CI drop-in; copy to `.github/workflows/`. - `KIT-VERSION` — which PMOS kernel this was assembled from. ## Install (once) No PMOS repo access needed (D55): **`npx create-pmos@latest [target-dir]`** — then follow its printed next steps (wire the CI workflow, point CLAUDE.md at `pmos/AGENTS.md`, commit). From a PMOS checkout the equivalent is `kit/build-kit.sh `; the npm package's payload is assembled by that same script at publish time, so the two never drift. **Empty folder / no repo yet?** `git init` first — git is required (branches and merges ARE the workflow: `initiative/` branches, merge = Acceptance), but GitHub is optional. With no existing code there is nothing to ingest: start by seeding `planning/okrs/` (the okr skill) and a first right-sized initiative; the product's code grows in the same folder. **403 on `npx` (corporate proxy/mirror)?** Try a plain terminal (not a sandboxed AI session); ask IT to allowlist `create-pmos` (zero deps, no install scripts, no network code); or install registry-free — download the `.tgz` from `registry.npmjs.org/create-pmos/-/create-pmos-.tgz` on any allowed network, then `tar xzf create-pmos-*.tgz && node package/bin/create-pmos.js `. **No GitHub?** Skip the workflow file and run the gate by hand before merging any initiative branch: `HEAD_REF=$(git branch --show-current) bash pmos/scripts/gate-initiative.sh` — green means anchored; your local `git merge` is the Acceptance Gate. If the repo later lands on GitHub, copy `templates/pmos-gate.yml` into `.github/workflows/` and the gate becomes automatic. ## Operate (every piece of work) 1. Create `pmos/state/initiatives/.md` (stage `intake`, anchored to a KR in `planning/okrs/` — or to a health budget, `parent_kr: health:` from `planning/okrs/health-budgets.md` (D59)), with its **work-type lane**: `type: feature` (default) `| discovery | chore | incident | content` (D56/D58 — the lane table in `AGENTS.md` says what each requires). 2. Author the lane's spec artifacts **before building** — feature: PRD + rubric (copy the templates), sprint contract, PM flips `PM_approved: true`; discovery: a spike brief (question + timebox) the PM approves; chore: a one-paragraph `intent:`; incident: fix first, record within 48h. 3. Branch `initiative/`, build, open a PR — the `pmos-gate` CI check fails any PR that isn't anchored (branch or `Initiative: ` in the PR body; `no-initiative` label for anchor-free trivia ONLY — a chore, spike, or incident takes its lane, D56). 4. Review Gate: run the evaluator skill against the rubric; append the verdict to `state/evals.jsonl`. The verdict is advisory until locally calibrated. 5. Acceptance Gate: the **human PM** merges and disposes; append to `state/acceptances.jsonl` (`accepted`, `pm_label`, corrections). Weekly: run `scripts/metrics.py`, read the red first. ## Sample prompts (copy-paste, no coding required) Talk to your agent like a colleague; your task is direction and judgment, its task is the build. - **Onboard an existing product:** "Read pmos/AGENTS.md. Then follow pmos/skills/ingest-repo.skill: scan this repository read-only and draft what you learn under pmos/okf/product/ for my review. Don't change any product code." - **Greenfield:** "Read pmos/AGENTS.md. This is a new product: [two sentences]. Seed pmos/planning/okrs/ with one objective and 2–3 key results, then propose one small first initiative — fast first win, not completeness." - **Start a piece of work:** "Read pmos/AGENTS.md. I want: [outcome]. Create the initiative file, then draft the PRD and eval rubric for my approval before you build anything." - **Explore before committing (discovery lane):** "Read pmos/AGENTS.md. I don't know yet whether [idea] is worth building. Open a discovery initiative per pmos/skills/discovery.skill: draft the spike brief — one question, a timebox — for my approval. Prototype code is throwaway." - **Quick maintenance (chore lane):** "Read pmos/AGENTS.md. Open a chore initiative: [one-sentence intent]. No PRD or rubric — just state the intent in the initiative file and do it." - **Review Gate:** "Follow pmos/skills/evaluator.skill: score the work on branch initiative/[id] against its rubric. Be skeptical — try to refute it. Append the verdict to pmos/state/evals.jsonl." - **Acceptance:** "I accept this run. Append the acceptance to pmos/state/acceptances.jsonl with pm_label 'pass' and corrections: [n]." - **Weekly review:** "Read pmos/state/discoveries.md and run pmos/scripts/metrics.py. Tell me what's red, what friction appeared more than once, and one improvement you'd propose. Don't change anything yet." - **Drift audit:** "List every merge in the last two weeks. For each: which initiative anchors it, did the rubric exist before the build, and is there an acceptance record? Report gaps without fixing them." - **Dashboard on demand:** "Read pmos/state/ (initiatives, runs.jsonl, evals.jsonl, acceptances.jsonl, discoveries.md). Generate a self-contained pmos/dashboard.html — no external scripts or network — with a stage-column board of initiatives, north-star + pass-rate tiles, a recent-runs timeline, and open frictions. Reds and gaps first." (Read-only view — the files stay the system of record.) ## Update the kernel (occasionally) `npx create-pmos@latest --update` (or `pmos/scripts/kit-update.sh ` from a PMOS checkout) — refreshes ONLY the kernel (skills/okf-core/scripts/AGENTS.md/README/templates), stamps `KIT-VERSION`, never touches `state/`, `planning/`, or `okf/product/`. Updates flow one-way, PMOS → kit; review the diff as a normal PR. > Upgrade note (D59 kernel): the gate now rejects an initiative file with **no `parent_kr`** > (hosted parity, D21). If a pre-D59 vendored file trips it, that file was always unanchored — > add a real KR, or `parent_kr: health:` from `planning/okrs/health-budgets.md` if it is > honest maintenance. The gate failing is the fix working, not a regression. ## The containment guarantee The assembly script greps its own output and fails on any reference to the hosted PMOS backend. Nothing in this folder phones home; the AGENTS.md protocol forbids connecting sessions from this repo to any personal PMOS MCP. Isolation is the point.