@pieerry/harness-kit 3.0.0

package/.claude/plugins/product-manager/evals/prd-readiness.md

@@ -0,0 +1,66 @@
+# Eval: PRD Readiness
+
+Type: rule-based stage gate
+Mode: advisory
+
+Decides whether a PRD has enough content for its declared stage to advance. Run after prd-quality passes.
+
+## Stage gates
+
+### Team Kickoff
+
+Required:
+- problem in 1-2 sentences
+- hypothesis with numeric direction
+- customer list with at least 1 named segment
+- primary success metric named
+
+Word count: 250-600
+Next stage: Planning Review
+
+### Planning Review
+
+Inherits Team Kickoff, plus:
+- baseline, target, horizon for every metric
+- guardrail metrics named
+- strategy fit explained
+- impact sizing with at least one quantified figure
+
+Word count: 400-900
+Next stage: Solution Review
+
+### Solution Review
+
+Inherits Planning Review, plus:
+- solution overview with user flow (Mermaid or numbered)
+- at least 1 user story (As / I want / so that)
+- edge cases documented or explicit none-apply statement
+- non-goals listed with reasons
+- risk table with at least 2 risks and mitigations
+- UX reference or "no UI change"
+
+Word count: 700-1400
+Next stage: Launch Readiness
+
+### Launch Readiness
+
+Inherits Solution Review, plus:
+- phased rollout table with audience, duration, pass criteria per phase
+- kill criteria with numeric thresholds
+- owners and reviewers
+- open questions resolved or assigned to owner
+- feature flag or rollback plan
+
+Word count: 1200-2500
+Next stage: Shipped
+
+## Output format
+
+```json
+{
+  "current_stage": "Team Kickoff | Planning Review | Solution Review | Launch Readiness",
+  "ready_for_next": true,
+  "missing_for_next": ["item", "item"],
+  "warnings": ["soft issue"]
+}
+```

package/.claude/plugins/product-manager/evals/prp-context-readiness.md

@@ -0,0 +1,51 @@
+# Eval: PRP Context Readiness
+
+Type: composite (executor simulation plus sensor pass-through)
+Mode: handoff gate
+
+Pass criteria:
+- all structural sensors passed
+- shippable in {yes, partial}
+- blocking_questions count <= 2
+- one_shot_likelihood >= 0.7
+
+Run last, after prp-quality passes.
+
+## Phase 1: structural
+
+Pass-through. Required green:
+- sensors/prp-structure.md
+- sensors/prp-context-quality.md
+- sensors/prp-links.md
+
+If any fail, abort and return sensor feedback.
+
+## Phase 2: executor simulation
+
+You are a coding agent that has never seen this codebase. You are handed only this PRP. You may not ask the PM follow-up questions. Read it end-to-end and answer:
+
+1. Could you ship with only what is in the PRP plus linked files? (yes / partial / no)
+2. List every place where you would need to stop and ask a human.
+3. List every claim that looks plausible but you cannot verify from the PRP alone.
+4. Rate one-shot-success likelihood from 0 to 1.
+
+## Output format
+
+```json
+{
+  "shippable": "yes | partial | no",
+  "blocking_questions": ["question"],
+  "unverifiable_claims": ["claim"],
+  "one_shot_likelihood": 0.0
+}
+```
+
+## Phase 3: PM signoff (manual)
+
+PM confirms or requests another iteration.
+
+## On failure
+
+Phase 1 fails: re-run failing sensor, regenerate failed sections.
+Phase 2 fails criteria: regenerate weakest section based on blocking_questions.
+Phase 3 rejects: collect PM feedback, retry the loop.

package/.claude/plugins/product-manager/evals/prp-quality.md

@@ -0,0 +1,88 @@
+# Eval: PRP Quality
+
+Type: LLM-judge
+Mode: quality gate
+Threshold: weighted total >= 8.0
+
+Read as if you are the executor: would you hit a dead end? Score 0-10 per dimension. Cite line numbers when below 7. Weighted total = sum(score x weight%) / 100.
+
+## Rubric
+
+### Goal clarity (weight 15%)
+One paragraph, concrete, tied to source PRD?
+
+- 10: unambiguous
+- 5: clear but loose scope
+- 0: "improve X" with no scope
+
+### Context completeness (weight 20%)
+Context section gives file paths, patterns with examples, external docs, gotchas? Executor never needs to leave?
+
+- 10: self-contained
+- 5: most context present, some gaps
+- 0: "go look at the repo"
+
+### Implementation concreteness (weight 20%)
+Blueprint specific enough that executor never decides naming, file location, or API shape?
+
+- 10: numbered steps with concrete identifiers
+- 5: outline present, some decisions open
+- 0: prose handwaving
+
+### Validation executability (weight 15%)
+Validation gates are real commands the executor copy-pastes? Manual checks specific?
+
+- 10: copy-paste ready
+- 5: commands with placeholders
+- 0: "make sure it works"
+
+### Pattern referencing (weight 10%)
+Codebase patterns named with file:line references?
+
+- 10: at least 2 concrete patterns
+- 5: 1 pattern
+- 0: no analogies
+
+### Scope discipline (weight 10%)
+"Out of scope" explicit? One feature, no bundled unrelated work?
+
+- 10: tight
+- 5: 1 unrelated item slipped in
+- 0: scope creep
+
+### Gap honesty (weight 5%)
+Unknowns marked with NEEDS REVIEW or TBD with owners? Marker count <= 5?
+
+- 10: honest, low marker count
+- 5: markers without owners
+- 0: too many gaps or pretends to know
+
+### Voice (weight 5%)
+No banned words. No em-dashes. Mermaid not ASCII.
+
+- 10: clean
+- 5: 1-2 violations
+- 0: 3+ violations
+
+## On failure (total below 8.0)
+
+Retry. Identify lowest-scoring dimensions, regenerate those sections only. Max 3 attempts.
+
+## Output format
+
+```json
+{
+  "scores": {
+    "goal_clarity": 0,
+    "context_completeness": 0,
+    "implementation_concreteness": 0,
+    "validation_executability": 0,
+    "pattern_referencing": 0,
+    "scope_discipline": 0,
+    "gap_honesty": 0,
+    "voice": 0
+  },
+  "weighted_total": 0.0,
+  "feedback": ["dimension: specific issue with line ref"]
+}
+```

package/.claude/plugins/product-manager/guides/examples/good-prd-example.md

@@ -0,0 +1,121 @@
+# PRD: Invoice Deadline Timezone Fix
+
+**Squad:** Billing | **DRI (PM):** @pm-lead | **Date:** 2026-05-08
+**Stage:** Solution Review
+**Bet:** N/A (bug-driven refinement)
+**Status:** In Review
+
+## 1) Problem and Hypothesis
+
+**Problem:** Customer success reports that 3% of invoices are flagged as overdue even when the customer is still inside their local payment window. The deadline calculation runs in UTC, but US-EAST customers operate in UTC-5 and EU-WEST customers in UTC+1.
+
+**Hypothesis:** If we apply each customer's registered timezone offset when computing the deadline, then false-overdue invoices will drop to zero within 30 days, because the only cause we have seen across 12 weekly support tickets is the UTC mismatch.
+
+**Strategy fit:** Supports the Billing reliability pillar for Q2 2026. False-overdue flags trigger automated dunning emails and finance write-offs; cleaning this up is table stakes before we offer SLA-backed payment-window guarantees in H2.
+
+**Evidence:**
+- 12 weekly support tickets in the last 6 weeks, all from customers in US-EAST and EU-WEST
+- Finance: $14k in disputed late fees traced to false-overdue invoices (Q1 2026)
+- Customer success confirmed the issue affects only customers in non-UTC timezones. UTC-aligned customers (UK) have zero false-overdue reports.
+- Quote, CUST-001 ops manager: "Our payment deadline is 17:00 local. The dunning email arrived at 14:00 saying we missed it. That's just wrong."
+
+## 2) Customers
+
+| Customer | Why it matters |
+|----------|----------------|
+| Customer ops (US, EU, others in non-UTC) | Daily friction; one weekly escalation each |
+| Customer success | Triages the false-overdue tickets, ~3h/week of avoidable work |
+| Finance | Reconciles disputed late fees manually |
+| End customers | Receive incorrect dunning notifications, hurts trust |
+
+## 3) Scope and Non-Goals
+
+**In scope:**
+- Read `customers.timezone` when computing the deadline for any invoice.
+- Apply offset in both the daily report and the real-time invoice screen.
+- Backfill the last 90 days of flagged invoices to clear false positives.
+
+**Non-goals (max 3):**
+- Schema changes to `customers`. The timezone column already exists and is populated.
+- Per-segment deadline rules. Separate refinement.
+- Surfacing deadline time in customer-facing API responses. Out of scope, request from customers but not blocking.
+
+**Trade-offs accepted:**
+- The fix runs in application code, not the database. About +5ms per invoice lookup; acceptable given current latency budget.
+- Backfill is a one-off script, not a recurring job. Anything older than 90 days stays as-is.
+
+## 4) Solution Overview
+
+**Summary:** When the billing service evaluates whether an invoice is overdue, it currently compares the invoice's deadline timestamp against a UTC clock. We change the comparison to convert both timestamps into the customer's local timezone before evaluating. The customer timezone is already stored in `customers.timezone` and populated for every active customer.
+
+We add an integration test per timezone tier (UTC, UTC-5, UTC+1) using fixed clock fixtures. A one-time backfill script re-evaluates invoices flagged as overdue in the last 90 days and clears false positives.
+
+**User flow:**
+
+```mermaid
+flowchart LR
+  INV[Invoice evaluated] --> Lookup[Lookup customer.timezone]
+  Lookup --> Convert[Convert deadline + now to customer local time]
+  Convert --> Compare[Compare in local time]
+  Compare -->|on time| Green[Green status]
+  Compare -->|overdue| Red[Red status + dunning]
+```
+
+**User stories:**
+- As a customer ops lead, I want the invoice report to use my local payment deadline, so that on-time invoices are not flagged as overdue.
+- As a customer success analyst, I want false-overdue invoices from the last 90 days cleared, so that I stop triaging the same complaints every week.
+- As a finance analyst, I want disputed late fees traceable to the bug to reconcile automatically, so that I do not process them by hand.
+
+**UX reference:** No UI changes. The invoice screen and the daily report read from the corrected backend.
+
+## 5) Success Metrics
+
+| Metric | Baseline | Target | Horizon |
+|--------|----------|--------|---------|
+| False-overdue rate (non-UTC customers) | 3.1% | 0% | 30 days |
+| Weekly support tickets about deadlines | 12 | 0 | 30 days |
+| Disputed late fees ($) | 14k/quarter | 0 | 90 days |
+
+**Guardrails:**
+- Invoice evaluation latency P95: must stay below 200ms (current 145ms; +5ms acceptable).
+- No regression in UTC-aligned customers (UK reference cohort): false-overdue rate must stay 0%.
+
+**Kill criteria:** If P95 latency rises above 220ms or if any UTC-aligned customer starts flagging false-overdue after rollout, disable the feature flag and roll back the backfill.
+
+## 6) Rollout
+
+| Phase | Audience | Duration | Pass criteria |
+|-------|----------|----------|---------------|
+| 1 | Internal staging + CUST-001 only | 7 days | Zero false-overdue in CUST-001, latency unchanged |
+| 2 | All non-UTC customers | 14 days | False-overdue rate drops to 0%, no UTC regressions |
+| 3 | Full rollout + 90-day backfill | 1 day cutover, 7-day monitoring | Ticket count drops to 0 within 14 days |
+
+Feature flag: `deadline_local_tz_v1`. Default off, enabled per phase.
+
+## 7) Risks
+
+| Risk | Likelihood | Impact | Mitigation |
+|------|-----------|--------|------------|
+| Customer timezone misconfigured | Low | High | Pre-rollout audit: query `customers` for nulls or invalid TZ strings, fix before phase 2 |
+| Backfill clears legitimately overdue invoices | Low | High | Backfill script writes to an audit table; ops reviews before flipping statuses |
+| New customers added without timezone | Medium | Medium | Add NOT NULL constraint after backfill complete |
+
+## 8) Owners and Open Questions
+
+**DRI:** @pm-lead
+**Reviewers:** Engineering (Billing tech lead), Customer success lead, Finance ops, Sales ops
+
+**Open questions:**
+- [ ] Should we notify customers about the backfill correction, or just clear the records silently? Owner: @customer-success
+- [ ] Does finance want a per-customer dispute reconciliation report, or aggregated? Owner: @finance-ops
+
+## 9) Appendix
+
+**Alternatives considered:**
+- Store deadlines in UTC and force customers to provide their deadlines in UTC. Rejected because it pushes the conversion burden onto every customer and is error-prone.
+- Database-side timezone conversion via view. Rejected because the deadline logic lives in the billing service and splitting it across layers makes future changes harder.
+
+**Research quotes:**
+> "Our payment deadline is 17:00 local. The dunning email arrived at 14:00 saying we missed it. That's just wrong." CUST-001 ops manager, ticket #4421
+
+> "Every Monday I open the report and there are five fake overdue ones from US-EAST. I just close them. Waste of time." Customer success analyst, weekly retro 2026-04-29

package/.claude/plugins/product-manager/guides/examples/good-prp-example.md

@@ -0,0 +1,128 @@
+# PRP: Invoice Deadline Timezone Fix
+
+**Source PRD:** `outputs/prd/2026-05-08-billing-invoice-deadline-tz-fix.md`
+**Target executor:** coding-agent
+**Squad:** Billing | **Tech lead:** @tech-lead | **Date:** 2026-05-10
+
+## 1) Goal
+
+Make the billing service evaluate invoice payment deadlines in the customer's local timezone instead of UTC. Add an integration-test suite proving correctness across UTC, UTC-3, and UTC-5 customers. Ship a one-time backfill script that re-evaluates invoices flagged as overdue in the last 90 days and clears false positives via an audit-table review step.
+
+## 2) Why
+
+- 3% of invoices from non-UTC customers are flagged overdue incorrectly (PRD §1).
+- 12 weekly support tickets, $14k in disputed late fees per quarter (PRD §1).
+- Prerequisite for SLA-backed payment-window guarantees planned for H2 2026 (PRD §1, strategy fit).
+
+## 3) What
+
+**User-visible behavior:**
+- Invoice daily report shows overdue status using customer-local deadline comparison.
+- Real-time invoice screen (`/invoices` view) shows the same.
+- No UI changes; backend correction only.
+- Backfill output: invoices reclassified from overdue to on-time within the 90-day window, after ops sign-off on the audit table.
+
+**Out of scope:**
+- Adding new columns to `customers`. `customers.timezone` already exists.
+- Schema migration for `invoice_evaluations`. Reuse existing table.
+- Refactoring the broader deadline-rule engine.
+
+**Success criteria (verifiable):**
+- [ ] Given an invoice with deadline `2026-05-10T20:00:00Z` for customer `CUST-001` (UTC-3, deadline 17:00 local), When the billing service evaluates, Then status = on-time.
+- [ ] Given an invoice with deadline `2026-05-10T22:00:00Z` for customer `CUST-001`, When the billing service evaluates, Then status = overdue.
+- [ ] Backfill script outputs a CSV of (invoice_id, old_status, new_status, customer_id, tz) and writes to `audit_invoice_tz_backfill` table. No rows are flipped without a manual approval step.
+- [ ] Latency P95 stays below 220ms in load test.
+
+## 4) Context
+
+### Repos and files touched
+
+| Repo | File | Change type | Reference |
+|------|------|-------------|-----------|
+| billing-service | `src/main/java/com/example/billing/deadline/DeadlineEvaluator.java:42` | modify | core comparison logic |
+| billing-service | `src/main/java/com/example/billing/deadline/DeadlineEvaluator.java:88` | new | `convertToCustomerLocal(Instant, ZoneId)` |
+| billing-service | `src/main/resources/db/migration/V20260510__audit_invoice_tz_backfill.sql` | new | audit table migration |
+| billing-service | `src/test/java/com/example/billing/deadline/DeadlineEvaluatorTest.java` | modify | add UTC-3 / UTC-5 cases |
+| billing-service | `src/main/resources/scripts/backfill/invoice_deadline_tz_backfill.sql` | new | one-time backfill script |
+
+### Patterns to follow
+
+- **Pattern:** Customer lookup with timezone
+ **Example in codebase:** `src/main/java/com/example/billing/customer/CustomerRepository.java:33`
+ **Why follow it:** Existing helper returns customer with TZ already deserialized as `ZoneId`. Reusing it avoids a second query.
+
+- **Pattern:** Feature flag wrapping
+ **Example in codebase:** `src/main/java/com/example/billing/dunning/DunningService.java:67`
+ **Why follow it:** Same per-customer gating model. Use flag name `deadline_local_tz_v1`.
+
+- **Pattern:** Integration test with fixed clock
+ **Example in codebase:** `src/test/java/com/example/billing/dunning/DunningServiceTest.java:120`
+ **Why follow it:** Avoids flaky tests around DST or runtime TZ.
+
+### External documentation
+
+- Java `ZonedDateTime` semantics: https://docs.oracle.com/javase/8/docs/api/java/time/ZonedDateTime.html. Read the section on `withZoneSameInstant` vs `withZoneSameLocal`. We want `withZoneSameInstant`.
+- Feature flag service ADR: `docs/adr/0014-feature-flags.md`. For `featureFlags.isEnabled` per-entity semantics.
+
+### Known gotchas
+
+- **DST transitions:** Some customer timezones (US-EAST, EU-WEST) observe DST. Test suite must pin to known fixed dates either side of DST boundaries to remain stable.
+- **Null timezone:** If `customers.timezone IS NULL` (some legacy customers), fall back to UTC and log a warning at WARN level with `customer_id`. Do not throw: that would block invoice evaluation entirely.
+- **Backfill idempotency:** Run-twice safety. The audit-table insert must be `INSERT … ON CONFLICT (invoice_id) DO NOTHING`.
+
+## 5) Implementation blueprint
+
+```
+1. Add featureFlags injection to DeadlineEvaluator (see DunningService.java:67 pattern).
+2. In DeadlineEvaluator.evaluate(Invoice invoice):
+ a. Lookup customer via CustomerRepository.findByIdWithTimezone(invoice.customerId).
+ b. If customer.timezone == null, log WARN, fall back to ZoneId.of("UTC").
+ c. Convert invoice.deadline into customer.timezone using withZoneSameInstant.
+ d. Compare in local zone, return InvoiceStatus.OVERDUE or ON_TIME.
+3. Guard the new path with featureFlags.isEnabled("deadline_local_tz_v1", customerId).
+ If disabled, run legacy UTC comparison.
+4. Update DeadlineEvaluatorTest with 6 cases (CUST-001 on-time/late, CUST-002 on-time/late, CUST-003 regression).
+5. Write invoice_deadline_tz_backfill.sql with ON CONFLICT DO NOTHING and audit-only writes.
+```
+
+**Data:**
+- No schema changes to operational tables.
+- New table `audit_invoice_tz_backfill` via migration `V20260510__audit_invoice_tz_backfill.sql`. Columns: `invoice_id UUID PK`, `old_status VARCHAR(16)`, `new_status VARCHAR(16)`, `customer_id UUID`, `tz VARCHAR(64)`, `created_at TIMESTAMPTZ DEFAULT now()`.
+- Volume: about 3% of 90 days × 50k invoices/day = about 135k rows.
+
+**Observability:**
+- Logs: `INFO` on flag check ("deadline_local_tz_v1 enabled for customer={customer_id}"), `WARN` on null timezone fallback.
+- Metrics: `billing.deadline.evaluation.duration` histogram, tagged with `tz`. Dashboard: `billing/deadline-health` (existing: add a TZ panel).
+- Alerts: P95 latency above 220ms for 5 min triggers pager. Existing alert; raise threshold from 200 to 220 for the flag-on cohort.
+
+## 6) Validation gates
+
+```bash
+./gradlew :billing-service:build
+./gradlew :billing-service:test --tests "com.example.billing.deadline.DeadlineEvaluatorTest*"
+./gradlew :billing-service:detekt
+psql $STAGING_DB_URL -f src/main/resources/scripts/backfill/invoice_deadline_tz_backfill.sql --single-transaction --dry-run
+```
+
+**Manual verification:**
+- [ ] In staging, set feature flag for `CUST-001`. Create one invoice with deadline `20:00 UTC` (17:00 customer-local, on the deadline). Confirm status = on-time.
+- [ ] Run backfill script in staging. Inspect `audit_invoice_tz_backfill` for CUST-001: confirm 90-day window populated, no UTC customers included.
+- [ ] In Grafana `billing/deadline-health`, confirm new TZ panel renders.
+
+## 7) Rollout
+
+- [ ] Feature flag: `deadline_local_tz_v1`, per-customer gating.
+- [ ] Migration required: yes. `V20260510__audit_invoice_tz_backfill.sql`. Forward-only, safe; no data movement.
+- [ ] Rollback plan: disable flag, drop `audit_invoice_tz_backfill` only if backfill was applied incorrectly (data is read-only, so this is reversible).
+
+## 8) Open items
+
+- [ ] Confirm web frontend reads invoice status from API and not from its own clock: @web-tech-lead
+- [ ] Decide who triggers the backfill apply step in production: @ops-lead
+
+## 9) References
+
+- PRD: `outputs/prd/2026-05-08-billing-invoice-deadline-tz-fix.md`
+- ADR feature flags: `docs/adr/0014-feature-flags.md`
+- Deadline dashboard: https://grafana.example.com/d/billing-deadline-health
+- Pattern reference: `billing-service/src/main/java/com/example/billing/dunning/DunningService.java:67`

package/.claude/plugins/product-manager/guides/pipeline.md

@@ -0,0 +1,84 @@
+# Pipeline
+
+Shared rules for PRD and PRP generation. Edit retry, approval, publish, and token accounting here.
+
+## Stages per artifact
+
+1. Generate the artifact using the template in skills/{prd|prp}/SKILL.md.
+2. Apply sensors listed in skills/{prd|prp}/SKILL.md.
+3. Apply evals listed in skills/{prd|prp}/SKILL.md.
+4. Append the approval marker. Publish hook fires.
+
+## Retry policy
+
+Max attempts: 3 per artifact.
+
+Trigger on:
+- any sensor returns non-zero
+- eval weighted total below threshold (default 8.0)
+
+Strategy:
+1. Read the feedback.
+2. Regenerate only failed or low-scoring sections.
+3. Re-run sensors and eval.
+
+Hard stop after 3 attempts: return blocker, do not proceed.
+
+## Approval marker
+
+PRD:
+```
+<!-- approved: {YYYY-MM-DD} score={weighted-total} -->
+```
+
+PRP:
+```
+<!-- approved: {YYYY-MM-DD} score={weighted-total} ready-for-handoff: true -->
+```
+
+Triggers hooks/post-eval-{prd|prp}.sh.
+
+## Publish
+
+Local: file stays in outputs/{prd|prp}/.
+
+Confluence: fires if JIRA_USERNAME and JIRA_API_TOKEN are set. Calls scripts/confluence-publish.py. Missing creds skips silently.
+
+After publish, hook appends:
+```
+<!-- published: {ISO-timestamp} -->
+```
+
+## Token accounting
+
+Each phase brackets a measurable token window. Phases for this plugin:
+- prd-generate: from skill invocation to first save in outputs/prd/
+- prd-validate: from first save to approval marker (covers sensors and evals)
+- prp-generate: from skill invocation to first save in outputs/prp/
+- prp-validate: from first save to approval marker
+
+Markers live in outputs/.markers/{feature_id}.{phase}.{start|end}, each with `{"timestamp": ISO, "session_id": ""}`. Skill writes the .start marker; hooks write the .end markers.
+
+After each artifact's eval passes, the publish hook runs scripts/token-phase.py for both of its phases. The script reads the Claude transcript JSONL, sums usage tokens (input, output, cache_read, cache_creation) within each window, and appends a phase entry to outputs/tokens/{feature_id}.json. Markers are deleted after consumption.
+
+The post-eval hook also appends an inline summary comment to the artifact:
+```
+<!-- tokens: outputs/tokens/{feature_id}.json in={N} out={N} cache_r={N} -->
+```
+
+Future phases (dev, code review, launch) append new entries to the same outputs/tokens/{feature_id}.json by reusing the feature_id slug.
+
+If the transcript is not readable, the script logs a warning and exits 0. Token accounting never blocks publish.
+
+## Orchestrator order
+
+1. PRD: stages 1-4.
+2. hooks/pre-prp-check.sh validates the PRD approved marker.
+3. PRP: stages 1-4.
+4. Return summary.
+
+## Stop conditions
+
+- 3 failed attempts on the same artifact
+- missing required input after one clarification
+- pre-prp-check.sh denies PRP start

package/.claude/plugins/product-manager/guides/prd-guidelines.md

@@ -0,0 +1,27 @@
+# PRD Guidelines
+
+Rules specific to PRDs. General PM rules in product-guidelines.md.
+
+Business only. Zero technical detail. File paths, APIs, schemas belong in the PRP.
+
+User stories: As a {persona}, I want {action}, so that {benefit}.
+
+Metrics need baseline, target, horizon in every row. No empty cells.
+
+Mermaid only, never ASCII.
+
+Gaps: `NOT FOUND - NEEDS REVIEW: {detail}`. Never invent.
+
+Word count by stage:
+- Team Kickoff: 300-500
+- Planning Review: 500-800
+- Solution Review: 800-1200
+- Launch Readiness: 1500-2000
+
+Required sections at each stage:
+- Team Kickoff: 1, 2, 8
+- Planning Review: + 5
+- Solution Review: + 4, 7
+- Launch Readiness: all
+
+Stage progression: do not skip stages. Each gate adds requirements, never removes them.

package/.claude/plugins/product-manager/guides/product-guidelines.md

@@ -0,0 +1,75 @@
+# Product Guidelines
+
+How PMs think about product. Read before drafting a PRD.
+
+## We ship outcomes, not features
+
+Every PRD touches a real user or customer cohort. Always answer:
+- Who pays for the pain today?
+- Whose workflow changes?
+- What metric in the customer's business or experience moves?
+
+If you cannot answer all three, the PRD is not ready.
+
+## Squads
+
+Defined per org in `context-library/business-info.md` and `context-library/squads/`. Multi-squad PRDs: name a primary squad, call out cross-squad interfaces.
+
+## Customer hierarchy
+
+When prioritizing, make trade-offs between cohorts explicit, not invisible. A common ranking template (override per org):
+
+1. Paying customers with high operational impact
+2. Reliability partners (SLAs, contracts)
+3. End consumers (NPS, support volume)
+4. Internal ops (cost-to-serve)
+
+## Metrics
+
+Prefer metrics already on existing dashboards. New metrics need an owner to instrument.
+
+Strong examples (the shape of a strong metric — specific, owned, instrumented):
+- error rate of X by segment
+- first-attempt success rate
+- latency P95 of Y action
+- generation time for Z artifact
+- compliance rate per cohort
+
+Weak:
+- "User satisfaction" with no source
+- "Improved efficiency" with no number
+- "Reduced friction" with no baseline
+
+## Non-goals are mandatory
+
+Every PRD lists at least one non-goal. If you cannot think of one, you have not scoped the feature.
+
+## Rollout is not "ship it"
+
+Every PRD ends with phases, audience per phase, pass criteria per phase, rollback. Feature flags by default.
+
+## Kill criteria
+
+Decide before launch what makes you turn the feature off. Examples:
+- error rate above X%
+- latency P95 above Yms
+- adoption below Z% after N days
+
+## PRD vs PRP boundary
+
+In PRD:
+- why we are building
+- who feels the pain
+- success metric and target
+- open questions about scope
+
+In PRP:
+- file paths, class names, schemas
+- API endpoints, validation commands
+- open questions about implementation
+
+If the question is "should we build this", PRD. If it is "how do we build this", PRP.
+
+## Diagrams
+
+Mermaid always. Never ASCII.