create-pmos 0.1.0 → 0.1.1

package/README.md

@@ -1,30 +1,206 @@
 # create-pmos
 
-Scaffold the **PMOS portable kit**: run a disciplined, eval-driven product-management workflow —
-initiative → PRD → eval rubric → pre-run contract → build → Quality/Review/Acceptance gates —
-**entirely inside your own repo**. All state is git-versioned files. No database, no account,
-no network calls, no telemetry.
+**A product manager's operating system you can adopt in five minutes — no coding expertise
+required.** One command puts a disciplined, eval-driven PM workflow inside your own repo:
+initiative → PRD → eval rubric → agreed contract → build → three gates. Your AI coding agent
+(e.g. Claude Code) does the building. You do the judging. Everything stays in your folder — no
+database, no account, no network calls, no telemetry.
+
+## Whose task is what
+
+This kit is built on a simple separation of tasks:
+
+- **Your task** is direction and judgment: choose the goals, say what "good" means *before* the
+  work starts, and accept or return what comes back. That's it — and no one else can do it.
+- **The agent's task** is the building: code, documents, analysis, following the written protocol.
+- **The kit's task** is keeping both of you honest: gates that can't be sweet-talked, records that
+  don't rely on memory, and metrics that show the red first.
+
+You never need to write code. You need the courage to say what you want, and the final word on
+whether you got it — which you already have.
+
+## Getting started (5 minutes)
+
+**Have an existing project?**
 
 ```bash
-npx create-pmos@latest              # vendor a pmos/ kit into the current directory
-npx create-pmos@latest my-product   # ...or into my-product/
-npx create-pmos@latest --update     # refresh the kit kernel (never touches your state)
+cd my-product
+npx create-pmos@latest
+```
+
+**Starting from nothing but an idea?**
+
+```bash
+mkdir my-product && cd my-product
+git init          # git is required (its branches/merges ARE the workflow); GitHub is optional
+npx create-pmos@latest
+```
+
+What you'll see:
+
+```
+✅ PMOS kit vendored at /home/you/my-product/pmos (kernel-source: pmos@1740a5e)
+
+Next steps in /home/you/my-product:
+  1. cp pmos/templates/pmos-gate.yml .github/workflows/pmos-gate.yml   (only if on GitHub)
+  2. Add to the repo's CLAUDE.md: "This product is PMOS-managed (file mode) — read pmos/AGENTS.md before any work."
+  3. Commit the pmos/ folder. Then follow pmos/AGENTS.md for every run.
 ```
 
-Then open the folder with your coding agent (e.g. Claude Code) and start at `pmos/AGENTS.md` —
-it is the whole protocol. `pmos/README.md` is the operator guide; `pmos/scripts/metrics.py`
-prints your north-star metrics from the recorded state.
+Do those three lines and setup is over. A fresh kit with zero history is not behind — it is
+exactly where every product starts.
+
+## Your first conversation
+
+Open the folder with your coding agent and talk to it like a colleague — clear about the goal,
+open about what you don't know. Copy-paste starters:
+
+**You have an existing product** (let the agent learn it first):
+
+> 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.
+
+**You have only an idea:**
+
+> Read pmos/AGENTS.md. This is a new product: [two sentences on what it is and who it serves].
+> Help me seed pmos/planning/okrs/ with one objective and 2–3 key results, then propose one small
+> first initiative — optimized for a fast first win, not for completeness.
+
+**You know exactly what you want built:**
+
+> Read pmos/AGENTS.md. I want: [describe the outcome]. Create the initiative file, then draft the
+> PRD and the eval rubric for my approval before you build anything.
+
+## The rhythm (every piece of work)
+
+1. **Name the work.** An initiative file is created in `pmos/state/initiatives/` — anchored to one
+   of your goals, so nothing exists "just because."
+2. **Define "good" first.** The agent drafts a PRD and a scoring rubric; you approve the contract
+   (`PM_approved: true`) before any building. Deciding the standard in advance is your task —
+   it is also what makes the agent's verdicts mean something later.
+3. **The agent builds** on its own branch and opens the work for review. A gate checks that every
+   change is anchored. If someone (including the agent) skips the protocol, you'll see:
+
+   ```
+   ❌ initiative gate FAILED — Not anchored. Name the branch 'initiative/<id>' or add
+      'Initiative: <id>' to the PR body ... See pmos/AGENTS.md.
+   ```
+
+   The gate isn't scolding anyone — it's protecting your standard when you're not looking.
+   (No GitHub? Run it yourself before merging:
+   `HEAD_REF=$(git branch --show-current) bash pmos/scripts/gate-initiative.sh`)
+4. **An evaluator scores the work** against your rubric — adversarial by design, and advisory:
+
+   > Read pmos/AGENTS.md, then follow pmos/skills/evaluator.skill: score the work on branch
+   > initiative/[id] against its rubric. Be skeptical — try to refute it. Append your verdict to
+   > pmos/state/evals.jsonl.
+
+5. **You accept — or return it.** Your merge is the final gate. Returning imperfect work is not
+   conflict; it's the job. Record your call:
 
-## What's inside
+   > I accept this run. Append the acceptance to pmos/state/acceptances.jsonl with pm_label
+   > "pass" and corrections: [how many things you had to fix].
+
+## Your weekly ten minutes
+
+```bash
+python3 pmos/scripts/metrics.py
+```
+
+What you'll see:
+
+```
+PMOS kit metrics — 4 run(s), 4 eval(s), 3 acceptance record(s)
+
+B1 north star: 0.33 human corrections per accepted run (over 3 accepted run(s); lower is better)
+B2 throughput: 3 accepted run(s)
+   eval pass rate: 75% (3/4)
+B4 calibration (n=3): raw agreement 100%, TPR 100%, TNR n/a — no PM fails seen (leniency blind spot), ...
+```
+
+Reds print first, on purpose — facing facts without flinching is how the numbers stay honest. On
+day one it says `UNMEASURABLE — no accepted runs yet`. That's not failure; that's a truthful
+starting line. And if the evaluator starts passing everything while you keep fixing things, a
+tripwire fires and tells you the judge has gone soft. A weekly prompt, if you'd rather talk than
+read:
+
+> Read pmos/state/discoveries.md and run pmos/scripts/metrics.py. Tell me: what's red, what
+> friction appeared more than once, and what one improvement you'd propose. Don't change anything
+> yet.
+
+## How it guardrails the SDLC
+
+Each stage of the loop has a mechanism behind it — not a promise, a mechanism:
+
+| Without the kit | With the kit |
+|---|---|
+| Work starts because someone felt like it | **Nothing exists without an initiative** anchored to a goal — the gate rejects unanchored work, automatically on GitHub, by one command locally |
+| "Good" gets defined after seeing the output (so everything looks fine) | **The rubric and contract are written first** — building is blocked until you've flipped `PM_approved: true` |
+| The builder grades their own homework | **A separate adversarial evaluator scores against your rubric** — and even its verdict is advisory; the merge is yours alone |
+| History gets quietly rewritten | **State files are append-only** — corrections are added, never erased; git keeps the audit trail |
+| Metrics flatter you | **Reds print first**, and a tripwire fires if the evaluator passes everything while you keep fixing things — a green that hides red gets caught |
+| Tool updates overwrite your data | **Kernel updates never touch your records** — `state/`, `planning/`, `okf/product/` are structurally off-limits to `--update` |
+
+Notice none of these guardrails restrict *you* — they restrict the process, so your judgment is
+exercised at the two moments it matters: defining "good" and accepting the result.
+
+## Staying on the path (drift protection)
+
+Drift never announces itself — it's always "just this once, it's small." The kit assumes that and
+defends structurally rather than relying on discipline:
+
+- **The protocol is re-taught, not remembered.** The `CLAUDE.md` line makes every fresh agent
+  session read `pmos/AGENTS.md` before working — so a new session, a new model, or a new teammate
+  starts on-protocol by default instead of drifting from a stale memory.
+- **The gate makes skipping visible.** On GitHub it's a failing check nobody can miss; locally
+  it's the one command before a merge. Keep the `no-initiative` escape hatch for genuine chores
+  only — if you find yourself reaching for it weekly, that's a signal, not a shortcut.
+- **The weekly ten minutes is the ritual.** Put `metrics.py` + the discoveries scan on your
+  calendar. A friction that shows up twice with no decision gets promoted to a rule — that's how
+  the process improves instead of eroding.
+- **Ask the agent to audit itself.** Any time you feel drift:
+
+  > 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.
+
+- **A lapse is data, not a verdict.** If you skipped the ritual for a month, the files show
+  exactly where the record stops — restart from there. The kit never shames a gap; it just makes
+  the gap visible enough that you can choose to close it.
+
+## See your workflow — build your own dashboard
+
+The entire state is plain, open files (`state/*.jsonl`, `state/initiatives/*.md`) — which means
+**any AI platform can turn it into a dashboard on demand.** No product to buy, no service to
+connect. In Claude (or Claude Code) in your product folder, paste:
+
+> Read pmos/state/initiatives/*.md, pmos/state/runs.jsonl, evals.jsonl, acceptances.jsonl, and
+> pmos/state/discoveries.md. Generate a single, self-contained HTML file at pmos/dashboard.html —
+> no external scripts or network calls — showing: (1) a board with initiatives as cards in columns
+> by stage (intake / spec / build / eval / accepted); (2) the north star (corrections per accepted
+> run) and eval pass rate as stat tiles; (3) a recent-runs timeline with verdicts; (4) open
+> frictions. Reds and gaps first, then greens.
+
+Open `pmos/dashboard.html` in a browser. Regenerate it whenever you want a fresh view (or ask for
+it weekly as part of the ritual) — it's disposable by design. On other platforms the same works:
+upload or paste the state files to ChatGPT/Gemini and ask for the same artifact. Two rules keep
+this safe: the dashboard is a **read-only view, never the system of record** (the files stay the
+truth), and if your product is confidential, generate it with a tool that runs where the files
+live rather than uploading them elsewhere.
+
+## Keeping the kit fresh
+
+```bash
+npx create-pmos@latest --update
+```
 
-- `pmos/AGENTS.md` — the run protocol + the state adapter (every workflow action is a file convention)
-- `pmos/skills/` — the working skills (PRD, eval rubric, OKR, adversarial evaluator, repo ingest)
-- `pmos/okf/core/` — the concept kernel (the SDLC loop, three-tier gates, watermelon flags, …)
-- `pmos/scripts/` — a fail-closed CI gate for unanchored PRs, metrics, kernel updater
-- `pmos/state/` — your append-only operational record (initiatives, runs, evals, acceptances)
+Refreshes the skills, concepts, and scripts only. Your records — `state/`, `planning/`,
+`okf/product/` — are yours, and an update never touches them. `pmos/KIT-VERSION` always says
+exactly what you're running.
 
 ## Scope & support
 
-This package contains only the PMOS workflow **kernel** — it holds no reference to, and never
-contacts, any PMOS backend. Provided **as-is** (MIT); it is a snapshot published from a private
-upstream, updated when the maintainer publishes. Issues/PRs are not currently monitored.
+This package contains only the PMOS workflow kernel. It holds no reference to, and never
+contacts, any external backend — the publish pipeline verifies that on every release. MIT,
+provided as-is: a snapshot from a private upstream, updated when the maintainer publishes.
+Issues/PRs are not currently monitored — the kit is deliberately self-sufficient; everything it
+needs to teach you is in `pmos/AGENTS.md` and `pmos/README.md`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-pmos",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Scaffold the PMOS portable kit — run the PMOS product-management workflow (initiative → PRD → eval rubric → contract → build → three gates) entirely inside your own repo, with all state as git-versioned files. No database, no network, no telemetry.",
   "license": "MIT",
   "bin": {

package/payload/KIT-VERSION

@@ -1,3 +1,3 @@
-kernel-source: pmos@1740a5e
+kernel-source: pmos@30a011b
 assembled: 2026-07-17
 mode: vendor

package/payload/README.md

@@ -30,6 +30,16 @@ printed next steps (wire the CI workflow, point CLAUDE.md at `pmos/AGENTS.md`, c
 From a PMOS checkout the equivalent is `kit/build-kit.sh <this-repo-root>`; 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/<id>` 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.
+
+**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/<id>.md` (stage `intake`, anchored to a KR in `planning/okrs/`).
@@ -42,6 +52,34 @@ payload is assembled by that same script at publish time, so the two never drift
 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."
+- **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 <path-to-pmos-checkout>` from a