create-pmos 0.4.0 → 0.6.0

package/payload/skills-native/ingest-repo/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: ingest-repo
+description: Scan an existing product repository read-only and emit a DRAFT OKF reference layer (architecture, per-table, capability ledger, integrations, conventions, ADR seeds) + register the repo, so a build agent starts warm. Use when a PM brings a product that already ships and has a repo. Never writes the tenant repo; never emits secrets.
+license: MIT
+metadata:
+  pmos-version: 1.0.0
+  pmos-owner: wawan
+  pmos-risk: medium
+  pmos-category: onboarding
+  pmos-scope: read:tenant-repo, write:tenant-okf-drafts, write:product_repos
+---
+
+# ingest-repo — Warm-start an existing product from its code
+
+This skill is the **existing-repo on-ramp**: a PM arrives with a product that already ships and already
+has a repo, and PMOS needs knowledge of it so a build agent doesn't cold-start on every run (re-deriving
+the stack, assuming wrong, producing work the PM must heavily correct — the north-star cost). It is the
+**inverse of [analyze-product-infra](/build-skills/analyze-product-infra.skill)** (which goes PRD →
+what the product *needs*): ingest-repo goes **code → what the product *is***. It emits a **draft** OKF
+reference layer + a repo registration and then **stops for PM approval**.
+
+> **Format:** three-level progressive disclosure ([SKILL-FORMAT](/skills/core/SKILL-FORMAT.md)). L1
+> frontmatter above is the trigger; this L2 body is the full procedure.
+> **Where it runs:** in **the interactive agent runtime** (any capable coding agent; PMOS-self uses
+> Claude Code), in the tenant's own conversation, read-only — never a server-side scanner
+> ([D51](/okf/products/pmos/adr/d51-scan-location.md); heavy reasoning runs in the interactive agent
+> per [D09](/okf/products/pmos/adr/d09-skills-execute-in-claude-code.md), amended 2026-07-23).
+
+## Non-negotiable stance
+
+- **Read-only, at control altitude ([D01](/okf/products/pmos/adr/d01-control-plane.md)).** Zero writes
+  to the tenant repo — no files, no branches, no commits. If `git status` is not clean after the run,
+  that is a defect.
+- **No secrets, ever ([D08](/okf/products/pmos/adr/d08-never-log-request-headers.md)).** Read only env
+  var *names* (`.env.example`, config keys). **Secret-scan the repo content AND git history** (real
+  repos leak keys in committed code/history); if a secret value is found, **never** place it in a doc,
+  a log, or the registry — note only that a leak exists and where, by path, so the PM can rotate it.
+- **Default-to-refute on capability** (the [design-reconcile](/skills/core/design-reconcile.skill)
+  stance applied to code): a control/route is **watermelon** until a concrete backend read/write path
+  is found in the code. Unbacked controls land in **§D**, not invented as capability.
+- **Everything is a DRAFT ([D37](/okf/products/pmos/adr/d37-tenant-okf-db-native.md)/[D12](/okf/products/pmos/adr/d12-three-tier-eval-gate.md)).**
+  `save_okf_doc(... status:'draft')`. The agent proposes; the **PM approves in-app**. Retrieval note:
+  a PM's own build agent *can* read its own tenant drafts (get_okf_concepts returns owner-scoped drafts,
+  the ratified 2026-07-02 draft-visible-to-own-agent stance), so warm-start works immediately; approval
+  governs promotion/trust, not visibility to the owner's own agent.
+- **Tenant-only.** `save_okf_doc` rejects `pmos`; this never writes the PMOS-self git bundle.
+- **Idempotent.** Re-running upserts docs (on `id`) and reconciles the registry (on `product_slug`) —
+  no duplicates.
+
+## Procedure
+
+1. **Read [AGENTS.md](/AGENTS.md)** and confirm the target `product_slug` (owner-scoped; one product).
+2. **Read-only scan** of the tenant repo, gathering *cited* evidence (every claim will carry the repo
+   path it came from):
+   - **Stack & app surface** — manifests/lockfiles (`package.json`, `pyproject.toml`, `go.mod`, …),
+     framework config, entrypoints.
+   - **Architecture** — directory tree, entrypoints, module boundaries.
+   - **Data model** — migrations / schema / ORM models: one asset per table/model (columns + RLS/perm
+     shape where expressed).
+   - **Capability map** — trace **routes ↔ handlers ↔ queries**: which UI control/route reaches which
+     backend read/write. This is the raw material for the ledger.
+   - **Integrations** — config + SDK imports + `.env.example` **names only** (maps, transcription,
+     push, payments, storage, …).
+   - **Decisions & conventions** — README / ADRs / CHANGELOG / commit history (existing decisions);
+     CI config, lint rules, observed patterns (conventions).
+3. **Secret-scan** repo content + git history (e.g. high-entropy strings, known key prefixes). Emit
+   **no** value; record only "possible secret at `<path>`" for the PM.
+4. **Emit the reference layer** — via `save_okf_doc(..., status:'draft', product_slug:<slug>)`,
+   namespaced `products/<slug>/...`, **each body carrying situating context + the exact repo path(s)**
+   it was derived from (the [source-to-concept](/skills/core/source-to-concept.skill) rule + the
+   analyze-product-infra cited-line bar, applied to code). Minimum six kinds:
+
+   | Doc | OKF `type` | id (under `products/<slug>/`) | derived from |
+   |---|---|---|---|
+   | Architecture / stack overview | `Concept` | `concepts/architecture` | manifests + tree + entrypoints |
+   | Per-table/model schema (one each) | `Reference` | `data-model/<table>` | migrations / ORM models |
+   | **Capability ledger** | `Reference` | `references/capability-ledger` | routes ↔ handlers ↔ queries |
+   | Integration map | `Reference` | `references/integrations` | config + SDK imports + .env.example names |
+   | Conventions | `Concept` | `concepts/conventions` | CI/lint config + observed patterns |
+   | ADR seed(s) | `ADR` | `adr/<slug>-<n>-<topic>` | README / ADRs / commit history |
+
+5. **Bootstrap the per-tenant capability ledger** (the artifact
+   [design-reconcile](/skills/core/design-reconcile.skill) consumes, [D50](/okf/products/pmos/adr/d50-design-loop-product-scoped.md)
+   pattern — generic method, per-tenant instance). Classify **every** user-facing control/route into
+   exactly one bucket; each §A/§B entry **names the concrete read/write path** in the code:
+   - **§A — read-backed:** maps to a real backend read (query/endpoint) — cite it.
+   - **§B — write-backed:** maps to a real backend write (mutation/endpoint) — cite it.
+   - **§C — data-exists-unsurfaced:** the data exists but no control surfaces it (opt-in opportunity).
+   - **§D — no-backing (watermelon):** a control with no backend path found — flagged, not invented.
+6. **Register the repo** — `register_product_repo({ product_slug, repo:'owner/name',
+   app_surface:<observed>, backend_model:<observed>, status:'active', irs_ref:<repo-profile doc id>,
+   webhook_secret_ref: <name-or-null> })`. Fields are **observed** here (not IRS-derived); pass **no
+   secret value**. Add an "observed, not IRS-derived" provenance note.
+7. **STOP for PM approval.** Present the drafted layer + the ledger's §D watermelon list + any secret
+   findings. The PM approves docs in-app; you do not self-approve. Log the run + friction.
+
+## Guardrails
+
+- **Provenance is a hard gate.** An emitted doc with an un-sourced assertion is a defect — the
+  evaluator's provenance dimension hunts for exactly this ([rubric](/planning/evals/ingest-repo-eval-rubric.md)).
+- **Large/polyglot monorepos:** flag scope to the PM and do a per-package pass; do **not** emit a
+  shallow single profile.
+- **`register_product_repo` semantics:** designed for provisioning output — here `app_surface`/
+  `backend_model` are *observed*, a usage-only difference (no schema change); note it.
+- **B5 measurability:** the value thesis is "warm start → fewer corrections"; the first post-ingest
+  build run should retrieve these concepts (B5 > 0 for the tenant, via
+  [v_knowledge_reuse](/okf/products/pmos/references/metrics/v_knowledge_reuse.md) — now written by
+  get_okf_concepts FETCH). That real correction-delta, not the doc count, is the win.
+
+## Level 3 — references
+
+- The write path + PM gate: [okf-author](/build-skills/okf-author.skill) Mode B, [D37](/okf/products/pmos/adr/d37-tenant-okf-db-native.md).
+- The ledger method: [design-loop concept](/okf/core/concepts/design-loop.md),
+  [design-reconcile](/skills/core/design-reconcile.skill), [watermelon-flag](/okf/core/concepts/watermelon-flag.md).
+- Extraction discipline: [source-to-concept](/skills/core/source-to-concept.skill).
+- Scan location: [D51](/okf/products/pmos/adr/d51-scan-location.md). Registry:
+  [register_product_repo](/okf/products/pmos/references/mcp-tools/register_product_repo.md),
+  [product_repos](/okf/products/pmos/data-model/product_repos.md).
+- Sibling on-ramps: [analyze-product-infra](/build-skills/analyze-product-infra.skill),
+  [product-onboarding playbook](/okf/core/playbooks/product-onboarding.md).

package/payload/skills-native/okr/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: okr
+description: Draft or revise an OKR set for a planning period — objectives with measurable key results that initiatives ladder up to. Use when setting quarterly strategy or re-anchoring drifting work.
+license: MIT
+metadata:
+  pmos-version: 1.0.0
+  pmos-owner: wawan
+  pmos-risk: low
+  pmos-category: planning
+  pmos-scope: read:okf, write:planning/okrs
+---
+
+# okr — Draft or Revise an OKR Set
+
+This skill produces an OKR instance for a planning period: a small set of objectives, each with
+measurable key results, structured as a tree that initiatives and agent runs ladder up to. It
+operationalizes the [okr-tree](/okf/core/concepts/okr-tree.md) concept.
+
+> **Format note:** three-level progressive disclosure
+> ([SKILL-FORMAT](/skills/core/SKILL-FORMAT.md)). Level 1 above is the trigger; this body is the
+> procedure; rare variants go to Level 3 sub-files.
+
+## When to use vs. not
+
+- **Use** to set strategy for a planning period, or to re-anchor an initiative that has drifted from
+  its parent KR.
+- **Do not use** to spec a single piece of work — that is the [PRD skill](/skills/core/prd.skill).
+  OKRs sit one level above initiatives.
+
+## Procedure
+
+1. **Objectives: qualitative and few.** 2–4 objectives for the period. Each is directional and
+   inspirational, carries no number itself, and states a "what we want to be true."
+2. **Key results: measurable outcomes.** 2–5 KRs per objective. Each is a **change in the world**,
+   not a count of work done — "reduce human correction rate to < 0.5", not "ship 5 features". KRs
+   that measure output invite the [watermelon flag](/okf/core/concepts/watermelon-flag.md).
+3. **Ladder to the north star.** Every KR should move, directly or indirectly, the north-star metric
+   — **human correction rate per agent run** (lower is better). If a KR ladders to nothing, cut it.
+4. **Baseline and target.** Each KR states current baseline, target, and the measurement source.
+   "From X to Y, measured by Z."
+5. **Leave room for initiatives.** OKRs are parents; do not pre-assign every initiative. The tree is
+   filled in as work is chosen.
+6. **Set the review cadence.** State when KRs are checked and that reporting follows
+   [anti-optimism](/okf/core/concepts/okr-anti-optimism.md): report the red, separate confidence
+   from status.
+
+## Required content
+
+- **Period & identity** — planning period, `product_slug`, `pm_slug`.
+- **Objectives** — numbered, qualitative.
+- **Key results** — per objective: baseline → target, measurement source, confidence.
+- **North-star linkage** — how the set ladders to human correction rate.
+- **Cadence** — review rhythm and reporting stance.
+
+## Output and placement
+
+- OKR instances are **operational** — under `/planning/okrs/`, not in the OKF bundle.
+- Filename: period-slugged, e.g. `okrs-q3-2026.md`.
+
+## Quality bar
+
+Before handoff: objectives are qualitative; KRs are outcomes with baseline+target+source; every KR
+ladders toward the north star; reporting stance is anti-optimist; no initiative is smuggled in as a
+KR.
+
+## Level 3 sub-cases
+
+- Mid-period KR revision / re-baselining without resetting objectives: see `okr-rebaseline.md`
+  (author on first need).
+- Multi-product objective rollups: see `okr-rollup.md` (author on first need).

package/payload/skills-native/pmos-router/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: pmos-router
+description: Not sure which lane or flow a piece of work takes — START HERE. Maps any entry ("I have an idea", "it's broken", "is this feasible?", "we need copy", "upkeep") to its lane, spec artifacts, next skill, and gates; runs the intake sharpness test and the prior-rejection check on the way. The explicit front door for the D56/D58/D60 lane map.
+license: MIT
+metadata:
+  pmos-version: 1.0.0
+  pmos-owner: wawan
+  pmos-risk: low
+  pmos-category: planning
+  pmos-scope: read:okf, read:planning
+---
+
+# pmos-router — Route work to its lane
+
+The explicit front door. The lane map grew across
+[D56](/okf/products/pmos/adr/d56-initiative-lanes.md)/[D58](/okf/products/pmos/adr/d58-builder-profiles.md)/[D60](/okf/products/pmos/adr/d60-prototype-loop.md)
+while living implicitly across AGENTS.md, CLAUDE.md and the intake checklist — and the recorded cost
+of an implicit map is the `prototype-loop` discoverability failure (the PM could not find a flow
+whose pieces half-existed). This skill performs the mapping. **It decides nothing** — it routes to
+lanes and gates that already exist; where it and an authority disagree, the authority wins and the
+router is the bug (fix it via the weekly harness scan).
+
+> **Format note:** three-level progressive disclosure ([SKILL-FORMAT](/skills/core/SKILL-FORMAT.md)).
+> Sources of truth: the AGENTS.md lane list, `.github/scripts/initiative-gate.sh`, D56/D58/D60.
+
+## Step 0 — three checks before any route
+
+1. **Sharpness (the fog/ticket test):** *can the PM state the question or idea precisely now — not
+   answer it, state it?* If not, it is **fog**: not ready for intake. Name what would sharpen it
+   (a conversation, a datum, a spike) and stop — do not open an initiative to hold fog.
+2. **Prior rejection:** check [planning/out-of-scope/](/planning/out-of-scope/README.md) for the
+   concept. If a file exists, **read it first** and surface it to the PM — the concept returns only
+   if the PM overrides the recorded reasoning, and the file is updated either way.
+3. **The specimen test — ASK it, do not wait to be told** (D60 as amended 2026-07-24):
+
+   > **Can the PM judge this from a description, or do they need an instance of it in front of them?**
+
+   Put it to the PM in their own terms for this piece of work. If no description settles it, the
+   route is **prototype**, *whether or not the work has a user interface* — the lane is no longer
+   UI-gated. This check is asked here because the recorded failure is discoverability: a PM who does
+   not know the lane exists cannot ask for it, and a step left to memory decays to never.
+
+   **It must discriminate in both directions.** Most feature work — an MCP tool, a migration, a CI
+   gate — *is* judgeable from a description and routes straight to its PRD untaxed. Over-firing twice
+   running is a D41 tripwire on the test's wording.
+
+4. **Existing-surface check — does the PM understand what is already there?** Ask:
+
+   > **Would specifying this honestly require reading code that already exists?**
+
+   Yes → an [explain-surface](/build-skills/explain-surface.skill) pass runs **first**, before the
+   spike brief / prototype brief / PRD is authored, in a fresh context. Greenfield → skip it. This is
+   standard, not optional: the PRD skill's own rule ("look it up rather than asking") means the
+   *agent* acquires the understanding and the PM does not, and a spec built on facts the PM never saw
+   is a watermelon at the root.
+
+## The routes
+
+| The PM says… | Route | Lane / artifacts / next skill | Gates to expect |
+|---|---|---|---|
+| "I have an idea" the PM **can't judge from a description** — they need an **instance** in front of them (a UI not yet seen; equally *does this skill's output teach?*, *does this API feel right to call?*) | **Prototype first — before any PRD** | `type: prototype`; quick brief at `prd_path` declaring **the judgement exercised + the specimen format** (**no rubric BY DESIGN** — grilled, never scored); [prototype skill](/skills/core/prototype.skill). Format fits the work: lookable UI, a worked sample output, call/response transcripts, a schema sketch. **The class's conventions are a BLOCKING precondition** (design system for UI; SKILL-FORMAT, D19 ACI, migration/RLS conventions elsewhere) — absent → the agent authors them from the same brief, PM approves, first. | Initiative Gate (brief exists); web-ci quarantine; PM disposition (promote/iterate/kill) |
+| A **new bet** — new product/capability/direction whose *whether* is unargued | **Offer the strategic brief** (recommended, skippable — D61) | [strategic-brief skill](/skills/core/strategic-brief.skill) → `planning/briefs/<id>-brief.md`; go → feature route below; no-go → file in out-of-scope/ | none (the brief is never a gate) |
+| A **validated direction or known feature** (incl. a promoted prototype) | **Feature lane** | `type: feature`; PRD + eval rubric ([prd](/skills/core/prd.skill) + [eval-rubric](/skills/core/eval-rubric.skill) skills), rubric authored alongside (D13); contract before build (D16). A promoted prototype's PRD is **derived from the validated option**. New surface → leg B: [design-brief](/skills/core/design-brief.skill) as the build's reference, held to the [design-reference rubric](/planning/evals/design-reference-eval-rubric.md) | Initiative Gate (PRD+rubric); full three-tier gate |
+| "**Is this feasible / should we / how would we…?**" — a **question** with an unknown answer, findable by investigation | **Discovery lane** | `type: discovery`; spike brief at `prd_path` ([discovery skill](/skills/core/discovery.skill)); question + timebox + disposition. Deliverable is a **learning**, and it closes on the **timebox** ("inconclusive" is a recordable outcome). Contrast the row above: that one holds a **candidate** whose rightness no description settles, delivers a **validated direction**, and closes on a **disposition against a specimen**. Widening this lane to cover that was considered and **rejected** in D60 | Initiative Gate (spike brief) |
+| "**Production is broken**" | **Incident lane** | `type: incident`; fix now, record post-hoc within 48h at `prd_path` (the one sanctioned inversion; [incident template](/okf/core/templates/incident-record-template.md)) | Initiative Gate (record, post-hoc) |
+| A **text deliverable** (landing page, microcopy, release notes, campaign) | **Content lane** | `type: content`; content brief at `prd_path`, rubric recommended not required (D58); [copywriting skill](/skills/domains/copywriting.skill). Copy for a prototype rides the prototype instead (D60) | Initiative Gate (content brief) |
+| **Upkeep** — refactor/ops/security with no honest KR | **Chore lane, health-anchored** | `type: chore`; one-paragraph intent in `status`; anchor `health:<id>` from [health-budgets](/planning/okrs/health-budgets.md) (D59) — never a faked KR | Initiative Gate (intent + anchor) |
+
+**Every route** still takes the universal steps: anchored initiative row (`create_initiative`),
+branch `initiative/<id>`, and the human Acceptance Gate at the end (D12) — the router never bypasses
+[working-in-pmos](/okf/core/playbooks/working-in-pmos.md).
+
+## Edge rules
+
+- **Two shapes at once** (an idea that is also a bet): sharpness first, then the brief-offer, then
+  prototype — *whether* precedes *look*, but only when the whether is genuinely open; if the PM has
+  already decided to explore, go straight to prototype.
+- **Anchor-free trivia** (a typo, a broken link): the `no-initiative` label, no lane. Real work
+  never takes the hatch.
+- **Unknown shape after the checks:** ask the PM one routing question with a recommended answer —
+  do not guess a lane.

package/payload/skills-native/prd/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: prd
+description: Write a Product Requirements Document for an initiative. Use when an initiative has been chosen and needs a spec — the what and why — before any build or contract work begins.
+license: MIT
+metadata:
+  pmos-version: 1.1.0
+  pmos-owner: wawan
+  pmos-risk: low
+  pmos-category: planning
+  pmos-scope: read:okf, write:planning/prd
+---
+
+# prd — Write a Product Requirements Document
+
+This skill produces a PRD instance for one initiative. The PRD is the **spec** stage of the
+[SDLC loop](/okf/core/concepts/sdlc-loop.md): it says *what* to build and *why*, anchored to
+strategy, so a generator agent and the PM share one definition of the work before a contract is
+agreed.
+
+> **Format note:** this skill follows three-level progressive disclosure
+> ([SKILL-FORMAT](/skills/core/SKILL-FORMAT.md)). Level 1 above is the trigger; this body is Level 2;
+> rare variants are pushed to Level 3 sub-files referenced by name.
+
+## When to use vs. not
+
+- **Use** when an initiative is selected and needs a spec before build work.
+- **Do not use** to make the strategic case for *whether* to do the initiative — that is the
+  `strategic-brief` skill. The PRD assumes the initiative is already chosen.
+- **Do not use** to define how output is judged — that is the
+  [eval-rubric skill](/skills/core/eval-rubric.skill). PRD and rubric are authored together (see
+  [eval-driven-pm](/okf/core/concepts/eval-driven-pm.md)) but are separate artifacts.
+
+## Procedure
+
+0a. **Existing surface? Understand it first — before grilling.** If specifying this honestly
+   requires reading code that already exists, an [explain-surface](/build-skills/explain-surface.skill)
+   pass runs on that region **first**, in a fresh context and **not by you**. Its *Open questions*
+   section is a declared input to the grilling below: those are the things that could not be
+   determined from the code, and they must be resolved with the PM or carried explicitly into the
+   PRD's risks — never silently answered by assumption. Greenfield → skip. This exists because step 0b's
+   boundary rule, on its own, gives the **agent** the understanding and the PM none.
+0. **Grill before you write.** Before any authoring, interrogate the PM's intent as a dialogue —
+   **one question at a time, a recommended answer offered with each**, no authoring until shared
+   understanding is confirmed. Stop when the intent is **unambiguous**, not at a count — there is
+   deliberately **no question cap** (under-specification needs unlimited digging; a redundant
+   question is a quality bug, not a quantity bug). A batch questionnaire is **not** compliant with
+   this step. Boundary rule, near-verbatim from AGENTS.md: *if a fact can be found by exploring the
+   environment, look it up rather than asking — the decisions, though, are the PM's* (D12 at
+   optimal altitude). A stated requirement that later goes unhonored in a build (the recorded
+   "too many navigations" class) is exactly what this step exists to pin down in writing.
+1. **Anchor to strategy first.** Identify the parent KR in the
+   [OKR tree](/okf/core/concepts/okr-tree.md) — or, for maintenance work with no honest KR, the
+   declared [health budget](/okf/core/concepts/health-anchors.md) (`health:<id>`, D59). If the
+   initiative has neither, stop — it is unanchored work and the structural seed of
+   [silent drift](/okf/core/concepts/watermelon-flag.md). Resolve the anchor before writing the
+   PRD; never force a KR link that isn't real.
+2. **Start from the template.** Use
+   [prd-template](/okf/core/templates/prd-template.md) as the scaffold. Do not invent a new
+   structure.
+3. **Write the problem before the solution.** State the user/PM problem and why it matters now.
+   A PRD that opens with a solution has skipped the only part the agent cannot reconstruct.
+4. **Make scope explicit on both sides.** In-scope *and* out-of-scope. The out-of-scope list is the
+   primary defense against agents over-building.
+5. **State success as outcomes, not output.** Success criteria describe a change in the world tied
+   to the anchor — the parent KR, or the declared budget's purpose (D59) — not a list of artifacts
+   produced.
+6. **Pair with a rubric.** Flag that the [eval-rubric](/skills/core/eval-rubric.skill) must be
+   authored before the build starts — the eval is written first.
+7. **Write for durability.** The PRD (and the contract derived from it) waits while work is
+   scheduled, so write what stays true: name **interfaces, types, and behavioral contracts — never
+   file paths or line numbers** (they stale while work waits and mislead the builder that follows).
+   Criteria are **behavioral, not procedural** — what must be true of the outcome, never the tool
+   sequence (D14 applied to authoring). Acceptance criteria must be **independently verifiable**.
+   One exception: a **prototype-derived snippet** that encodes a decision more precisely than prose
+   may be inlined, trimmed to its decision-rich parts (the D60 promote path).
+8. **Keep it at control altitude.** The PRD specs *what and why*; it does not write the
+   application code or dictate the agent's path
+   ([control-plane](/okf/core/concepts/control-plane.md)).
+
+## Required content
+
+A complete PRD instance contains:
+
+- **Frontmatter** — the file opens with OKF YAML frontmatter: `type: PRD`, `title`, `timestamp` (the repo-wide convention, D63; [frontmatter-format](/okf/core/concepts/frontmatter-format.md)).
+- **Identity** — `initiative_id`, `product_slug`, `pm_slug`, parent `KR`.
+- **Problem** — who has it, why now, what it costs to leave unsolved.
+- **Goal & non-goals** — the change sought; explicit out-of-scope.
+- **Requirements** — what must be true of the solution (capabilities, constraints).
+- **Success criteria** — outcome-based, tied to the anchor (KR or budget purpose).
+- **Risks & open questions** — including anything to escalate to the PM.
+- **Links** — parent KR, the paired eval rubric, relevant OKF concepts. **Dual-audience rule
+  (D58):** every link carries ONE situating sentence (what it is and why it matters here — the
+  source-to-concept rule applied to planning artifacts), and the parent-KR line quotes the KR
+  *text*, not just its id (health-anchored: name the budget and why the work fits its coverage). The body stays agent-optimized; the references must stand alone for a
+  human stakeholder reading the PRD without the OKF bundle in context.
+
+## Output and placement
+
+- PRD instances are **operational**, not OKF knowledge. They live under `/planning/prd/`, not in the
+  bundle ([okf-governance](/okf/core/concepts/okf-governance.md)).
+- Filename: descriptive and slugged, e.g. `p0-prd.md`.
+
+## Quality bar
+
+Before handing off, confirm: anchor present — parent KR (text quoted, not just the id) or
+`health:<id>` (D59); problem precedes
+solution; out-of-scope is non-empty; success criteria are outcomes not output; every link carries
+its situating sentence (D58); the eval rubric is queued to be written first.
+
+## Level 3 sub-cases
+
+- Multi-product or platform PRDs that span more than one `product_slug`: see `prd-multiproduct.md`
+  (author on first need).
+- Spike / discovery work where the deliverable is a learning, not a feature, is **not a PRD
+  case** — take the discovery lane ([D56](/okf/products/pmos/adr/d56-initiative-lanes.md)):
+  [discovery skill](/skills/core/discovery.skill) +
+  [spike-brief template](/okf/core/templates/spike-brief-template.md).

package/payload/skills-native/prototype/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: prototype
+description: Run a pre-PRD validation through the prototype lane (D60) — the PM gives a QUICK brief, an agent produces 2–3 divergent specimens in whatever format fits the work (lookable UI options, a worked sample output, call/response transcripts, a schema sketch with example rows), a grilling sharpens them (dialogue, never a score), and the PM disposes promote/iterate/kill. Use when an idea's rightness cannot be settled by a description and the PM needs an INSTANCE in front of them — whether or not the work has a user interface; requires the artifact class's conventions (blocking — author them first if absent).
+license: MIT
+metadata:
+  pmos-version: 1.1.0
+  pmos-owner: wawan
+  pmos-risk: low
+  pmos-category: design
+  pmos-scope: read:okf, write:prototype, write:planning
+---
+
+# prototype — Run a leg-A validation through the prototype lane
+
+The [D60](/okf/products/pmos/adr/d60-prototype-loop.md) lane skill. The division of labour is the
+point: **the PM briefs; the agent builds the specimen.** The PM should never have to author a design
+system, a convention set, or a prototype to validate an idea.
+
+> **Format note:** three-level progressive disclosure ([SKILL-FORMAT](/skills/core/SKILL-FORMAT.md)).
+> Level 1 above is the trigger; this body is Level 2.
+> **Scope note (2026-07-24 amendment):** this lane is **no longer gated on the work being a user
+> interface**. D60's mechanism — *make it examinable, then grill it, before committing to a spec* —
+> is general; it was only ever *expressed* visually. The visual path below is unchanged and stays
+> first-class; it is now one shape among several.
+
+## When to use vs. not
+
+**The entry rule is the specimen test:**
+
+> **Can the PM judge this from a description, or do they need an instance of it in front of them?**
+
+- **Use** when no description settles it. The measured cost of skipping this is the
+  console-redesign series: four post-build rejections that a lookable artifact would have caught
+  pre-spec — a *visual* judgement that could only be made once the thing existed. The class is wider
+  than the instance: *does this skill's output actually teach?*, *does this API feel right to call?*,
+  *does this rubric actually discriminate?*, *does this error message actually help?* are the same
+  judgement in a different medium.
+- **Do not use** when a description does settle it — which is most feature work. An MCP tool, a
+  migration, a CI gate: the PM can read what it will do and decide. Those go straight to their PRD.
+  **A lane that fires on everything has failed as surely as one that fires on nothing**; over-firing
+  twice running is a D41 tripwire on the test's wording.
+- **Do not use** for leg B (the post-PRD, high-fidelity design reference — that is the
+  [design loop](/okf/core/concepts/design-loop.md): design-brief → design → reconcile, open to new
+  surfaces per D60's D48 amendment).
+- **Do not use** when you hold a *question* rather than a *candidate* — that is the
+  [discovery lane](/skills/core/discovery.skill):
+
+  | | You hold | Deliverable | Closes on |
+  |---|---|---|---|
+  | **discovery** | a **question** with an unknown answer, findable by investigation | a **learning** | the timebox — "inconclusive" is a recordable outcome |
+  | **prototype** | a **candidate** whose rightness no description settles | a **validated direction** | a disposition against a specimen |
+
+  Widening `discovery` to cover this was considered and **rejected** in D60 and stays rejected:
+  "discovery" is not the word a PM reaches for when they want to *see* something, and
+  discoverability was the whole failure.
+
+## Procedure
+
+1. **Open the lane.** `create_initiative({id, title, parent_kr, type:'prototype', stage:'intake'})` —
+   anchored like all work (D21/D59). Branch `initiative/<id>`.
+1b. **Improving something that already exists? Understand it first.** If the specimen will replace
+   or alter an existing surface, run an [explain-surface](/build-skills/explain-surface.skill) pass on
+   it — fresh context, **before** the brief. Divergent options against a surface nobody has
+   characterised diverge from a guess, and the PM cannot grill them honestly. Brand-new → skip.
+2. **Take the quick brief.** The PM fills the
+   [prototype-brief template](/okf/core/templates/prototype-brief-template.md) — minutes not hours —
+   into `prototype/<id>/brief.md`; set it as `prd_path`. It declares **the judgement being
+   exercised** and **the specimen format chosen** (step 4), because those are what the grilling and
+   the disposition hang on. **`rubric_path` stays null by design** (grilled, never scored). If the PM
+   starts writing requirements, stop them: that detail belongs in the PRD that *follows*.
+3. **Precondition check — BLOCKING (D60(c), generalised).** A specimen built against no shared
+   vocabulary produces something nobody can consistently build from. Before producing anything, confirm
+   the artifact class has **conventions** and **craft knowledge** to reason from:
+
+   | Class | Its conventions live in |
+   |---|---|
+   | A user interface | the product's **design system** — tokens, type scale, components (PMOS's own app: [D38](/DECISIONS.md); tenants checked at onboarding) |
+   | A skill | [SKILL-FORMAT](/skills/core/SKILL-FORMAT.md) — three-level progressive disclosure |
+   | A tool or API | [D19](/okf/products/pmos/adr/d19-aci-design.md)'s ACI principle |
+   | A knowledge doc | the OKF spec + [frontmatter-format](/okf/core/concepts/frontmatter-format.md) |
+   | A schema | the repo's migration + RLS conventions |
+
+   In PMOS most already exist, so this usually passes on inspection. **Where a class has neither,
+   authoring them is the first initiative** — propose a minimal set, get the PM's approval, record it
+   in the product's namespace, and only then prototype. Never silently invent per-prototype
+   conventions; that is how inconsistent products happen.
+4. **Retrieve the craft, and choose the format.** `get_okf_concepts` the class's craft — for a user
+   interface, `core/concepts/design-craft` (perception/cognition evidence, craft moves, accessibility
+   floors, recorded anti-patterns); for other classes, the conventions named in step 3. **Reason from
+   principles to THIS brief; two briefs must not produce the same specimen.** D60(e) is explicit that
+   without a craft layer to reason from, an agent told to "apply practice" produces generic output —
+   if you cannot name what you are reasoning from, you are in the blocking case above.
+
+   Then choose the format by the principle — **the cheapest specimen that lets the PM exercise the
+   judgement in question**. A starting vocabulary, deliberately **not a closed enum**; an unlisted
+   shape takes whatever actually fits, named in the brief:
+
+   | Work shape | A specimen might be |
+   |---|---|
+   | A user interface | a low-fidelity lookable artifact (static HTML is usually right) |
+   | A skill / agent capability | a worked sample output on real input |
+   | A tool or API shape | sample call + response transcripts |
+   | A data model | a schema sketch with example rows |
+   | An eval rubric | the rubric scored against 2–3 real past artifacts |
+   | Error text, CLI, protocol | the actual strings, or a session transcript |
+
+5. **Produce divergent specimens** into `prototype/<id>/` — low-fidelity, self-contained, examinable
+   (whatever renders or reads fastest). **2–3 genuinely different directions, not one safe one with
+   variants** — divergence is the point in any medium. **Real draft content, never placeholder**
+   (D60: copy rides the prototype — [copywriting.skill](/skills/domains/copywriting.skill) craft
+   applies in-loop; claim-sourcing waits for the content lane at production). The non-visual analogue
+   is the same rule: real inputs and real outputs, because fake ones hide exactly the friction the
+   specimen exists to surface. Respect the accessibility floors even at low fidelity.
+6. **Grill — dialogue, never a score.** A craft-grade critic (fresh context, default-to-refute
+   stance, the class's craft loaded) interrogates each specimen: *why this structure? what job does
+   the focal element serve? what would the best practitioner in this class say is wrong? what was NOT
+   tried?* One question at a time, a recommended answer with each, no action until shared
+   understanding is confirmed. Sharpen the specimens from it. **Produces no score, no verdict, no
+   threshold, no `evals` row** — re-introducing scoring here under any name is a D60 violation.
+7. **PM disposition** (the only gate on leg A, and it is the PM's):
+   - **promote** → open a **new feature-lane initiative**; its PRD and rubric are **derived from the
+     validated specimen** (what was seen and chosen becomes the spec's substance). Leg B, where the
+     work has a surface, then runs inside that initiative's Build.
+   - **iterate** → back to step 5 with the PM's reaction folded in.
+   - **kill** → record one honest line on the initiative, **file the concept into
+     [planning/out-of-scope/](/planning/out-of-scope/README.md)** (decision, reasoning, what would
+     reopen it) so it is not re-prototyped from scratch, and close. A cheap kill is this lane
+     *succeeding*.
+8. **Log.** `log_agent_run` with the disposition; friction to discoveries.md (`#friction`).
+
+## Hard rules
+
+- Artifacts live in **`prototype/<id>/` only** — never `web/`, never a tenant app. The `web-ci`
+  quarantine assertion enforces this for the visual case; it is the *instance* of D01's general rule,
+  which binds every medium. Do not fight it, and do not read "the assertion only covers `web/`" as
+  permission to let a non-visual specimen leak into product code.
+- **A prototype never ships.** Promote produces a *spec*, not a deploy. Quality bars are suspended in
+  `prototype/` precisely because nothing there can reach production (D01).
+- **No score on leg A, no skipped grilling on leg A.** Both PM rules bind; **neither may be satisfied
+  by dropping the other**. This holds for non-visual specimens too, where the temptation is sharper:
+  a schema or an API *looks* like it has objective criteria, and that is exactly the argument that
+  produces safe, scoreable output — the criteria you can score are the ones you already know to look
+  for. A technically correct schema can still be the wrong one to live with, and *fit* is what leg A
+  is for. (The console log's twin: the evaluator graded *correct* design; the PM judged *desirable*
+  design.)
+- If the PM stops looking and promotes on autopilot, say so — an unreviewed disposition is the
+  [meta-watermelon](/okf/core/concepts/watermelon-flag.md) in a new place.

package/payload/templates/agent-run-eval-rubric.md

@@ -1,3 +1,13 @@
+---
+type: Rubric
+title: "Eval Rubric: Agent-run capability baseline (kit seed — copy per initiative)"
+timestamp: 2026-07-19
+eval_type: capability
+initiative_id: (set per initiative)
+pass_threshold: 0.80
+canonical_path: pmos/planning/evals/agent-run-eval-rubric.md
+---
+
 # Eval Rubric: Agent-run capability baseline (kit seed — copy per initiative)
 
 > Kit-seeded generic rubric (D54). Two purposes: (1) it is the TEMPLATE to copy to
@@ -6,13 +16,6 @@
 > meaningful from day one. It scores a generic agent run outcome-only (D14) with weighted partial
 > credit (D15).
 
-## Frontmatter
-- type: Rubric
-- eval_type: capability
-- initiative_id: (set per initiative)
-- pass_threshold: 0.80
-- canonical_path: pmos/planning/evals/agent-run-eval-rubric.md
-
 ## Gate assignment
 - **Quality Gate (deterministic):** repo CI green; `pmos-gate` (anchored + rubrics) green.
 - **Review Gate (adversarial):** the weighted dimensions below — evaluator skill, default-to-refute,

package/payload/templates/ticket-template.md

@@ -0,0 +1,20 @@
+---
+type: Template
+timestamp: 2026-07-23
+id: "001"
+title: short imperative title — one deliverable
+status: todo            # todo | doing | done
+blocked_by: []         # e.g. ["002", "005"] — ticket ids that must be done first
+---
+
+# 001 — <title>
+
+**One deliverable.** What "done" looks like, behaviorally — not the steps to get there. Name
+interfaces, types, and behavioral contracts; never file paths or line numbers (they stale while the
+work waits).
+
+## Done when
+- [ ] <a single, independently verifiable acceptance check>
+
+## Notes
+<context a builder needs; links to the initiative/PRD this ticket decomposes>