create-pmos 0.4.0 → 0.5.0

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

@@ -0,0 +1,109 @@
+---
+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
+
+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:
+
+- **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,82 @@
+---
+name: prototype
+description: Run a pre-PRD visual validation through the prototype lane (D60) — the PM gives a QUICK brief, a design agent produces divergent low-fidelity lookable options with real draft copy, a designer-grade grilling sharpens them (dialogue, never a score), and the PM disposes promote/iterate/kill. Use when a user-facing idea needs to be SEEN before a PRD can honestly be written; requires the product's design system (blocking — author it first if absent).
+license: MIT
+metadata:
+  pmos-version: 1.0.0
+  pmos-owner: wawan
+  pmos-risk: low
+  pmos-category: design
+  pmos-scope: read:okf, write:prototype, write:planning
+---
+
+# prototype — Run a leg-A visual 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 designs.** The PM should never have to author a design system or
+build 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.
+
+## When to use vs. not
+
+- **Use** when a user-facing idea — new product, new feature, or an improvement to an existing
+  surface — needs visual confirmation **before** a PRD exists. The measured cost of skipping this is
+  the console-redesign series: four post-build rejections that a lookable artifact would have caught
+  pre-spec.
+- **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, now open to
+  new surfaces per D60's D48 amendment).
+- **Do not use** for non-visual questions ("is this feasible?") — that is the
+  [discovery lane](/skills/core/discovery.skill), whose deliverable is a learning, not a look.
+
+## Procedure
+
+1. **Open the lane.** `create_initiative({id, title, parent_kr, type:'prototype', stage:'intake'})` —
+   anchored like all work (D21/D59). Branch `initiative/<id>`.
+2. **Take the quick brief.** The PM fills the
+   [prototype-brief template](/okf/core/templates/prototype-brief-template.md) — two required
+   sections, minutes not hours — into `prototype/<id>/brief.md`; set it as `prd_path`.
+   **`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. **Design-system check — BLOCKING (D60).** Does this product have a design system (tokens,
+   type scale, components — PMOS's own app: D38)? **If not, author one first**: from the same brief,
+   propose a minimal system (palette + type scale + spacing unit + core component shapes), get the
+   PM's approval, record it in the product's namespace. Only then prototype. Never silently invent
+   per-prototype styling — that is how inconsistent products happen.
+4. **Retrieve the craft.** `get_okf_concepts({concept_ids:['core/concepts/design-craft']})` — the
+   perception/cognition evidence, craft moves, accessibility floors, and the recorded anti-patterns.
+   Reason from principles to THIS brief; two briefs must not produce the same design.
+5. **Produce divergent options** into `prototype/<id>/` — low-fidelity, self-contained, lookable
+   (static HTML is usually right; whatever renders fastest). **2–3 genuinely different directions**,
+   not one safe one with variants. **Real draft copy** (D60: copy rides the prototype —
+   [copywriting.skill](/skills/domains/copywriting.skill) craft applies in-loop; claim-sourcing waits
+   for the content lane at production). Respect the accessibility floors even at low fidelity.
+6. **Grill — dialogue, never a score.** A designer-grade critic (fresh context, default-to-refute
+   stance, [design-craft](/okf/core/concepts/design-craft.md) loaded) interrogates each option: *why
+   this structure? what job does the focal element serve? what would the best product designer 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 options 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 option** (what was seen and chosen becomes the spec's substance). Leg B 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; do not fight it.
+- **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.
+- 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/ticket-template.md

@@ -0,0 +1,18 @@
+---
+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>