scriptoriumadmin/claude-skills
1
0
Fork 0
mirror of https://github.com/alirezarezvani/claude-skills.git synced 2026-08-28 04:24:58 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Merge pull request #893 from alirezarezvani/claude/pm-audit-agentic-loops-jxurlq

Browse source
This commit is contained in:
Alireza Rezvani 2026-07-03 15:41:40 +02:00 • committed by GitHub
commit 9e378528c5
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
58 changed files with 3378 additions and 223 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

12
.claude-plugin/marketplace.json
View file

@ -8,8 +8,8 @@
"homepage": "https://github.com/alirezarezvani/claude-skills",
"repository": "https://github.com/alirezarezvani/claude-skills",
"metadata": {
"description": "355 production-ready skills across 18 domains (engineering, engineering-core, marketing, product, c-level, compliance-os, project management, RA/QM, business growth, finance, productivity, marketing top-level, research, research-ops, business-operations, commercial, markdown-html, loop-library, plus standards). 596 Python tools, 725 reference guides, 97 agents (cs-* + personas), 103 slash commands across 83 marketplace plugins. v2.10.3 completes the markdown-html domain with md-slides — slide-deck converter (arrow-key / Space / PgDn / Home/End / P keyboard navigation + presenter mode with split-view clock + speaker notes + next-slide preview + URL-hash deep linking like #3 for direct slide jumps + @media print page-per-slide for browser-native PDF export). Reuses md-document's markdown parser; vanilla JS only (no framework runtime); Prism.js opt-in via --syntax. Joins md-review (v2.10.2 code-review converter), md-document (v2.10.1 long-form converter), and the v2.10.0 foundation (orchestrator + design-system). Compatible with Claude Code, Codex CLI, Gemini CLI, Cursor, OpenClaw, Hermes Agent, Mistral Vibe, and 5 more coding agents.",
"version": "2.10.3"
"description": "355 production-ready skills across 18 domains (engineering, engineering-core, marketing, product, c-level, compliance-os, project management, RA/QM, business growth, finance, productivity, marketing top-level, research, research-ops, business-operations, commercial, markdown-html, loop-library, plus standards). 602 Python tools, 731 reference guides, 99 agents (cs-* + personas), 109 slash commands across 83 marketplace plugins. v2.11.1 turns product-team and project-management into agent-harness domains: fork-orchestrators with deterministic goal routers, a Jira MCP snapshot bridge (Kanban flow metrics + Monte Carlo forecasting), a delegation-governance loop gate, a continuous-discovery cadence tracker, and an Opportunity Solution Tree linter, with /cs:pm and /cs:product command families. v2.10.3 completes the markdown-html domain with md-slides — slide-deck converter (arrow-key / Space / PgDn / Home/End / P keyboard navigation + presenter mode with split-view clock + speaker notes + next-slide preview + URL-hash deep linking like #3 for direct slide jumps + @media print page-per-slide for browser-native PDF export). Reuses md-document's markdown parser; vanilla JS only (no framework runtime); Prism.js opt-in via --syntax. Joins md-review (v2.10.2 code-review converter), md-document (v2.10.1 long-form converter), and the v2.10.0 foundation (orchestrator + design-system). Compatible with Claude Code, Codex CLI, Gemini CLI, Cursor, OpenClaw, Hermes Agent, Mistral Vibe, and 5 more coding agents.",
"version": "2.11.1"
},
"plugins": [
{
@ -316,8 +316,8 @@
{
"name": "product-skills",
"source": "./product-team",
"description": "13 product skills with 17 Python tools: product manager toolkit (RICE, PRDs), agile product owner, product strategist, UX researcher, UI design system, competitive teardown, landing page generator, SaaS scaffolder, product analytics, experiment designer, product discovery, roadmap communicator, code-to-prd, research summarizer, apple-hig-expert.",
"version": "2.9.0",
"description": "13 bundled product skills with 22 Python tools: product-skills fork-orchestrator with continuous-discovery loop (deterministic 16-lane router, Torres cadence tracker, OST linter, /cs:product + /cs:grill-product + /cs:product-loop), product manager toolkit (RICE, PRDs), product strategist, UX researcher, UI design system, competitive teardown, landing page generator, SaaS scaffolder, product analytics, experiment designer, product discovery, roadmap communicator, spec-to-repo. Companion standalone plugins: agile-product-owner, code-to-prd, apple-hig-expert, research-summarizer.",
"version": "2.11.1",
"author": {
"name": "Alireza Rezvani"
},
@ -343,8 +343,8 @@
{
"name": "pm-skills",
"source": "./project-management",
"description": "9 project management skills with 12 Python tools: senior PM, scrum master, Jira expert, Confluence expert, Atlassian admin, template creator.",
"version": "2.9.0",
"description": "9 project management skills with 15 Python tools: pm-skills fork-orchestrator with agentic delivery loop (deterministic 8-lane router, Jira MCP snapshot bridge to Kanban flow metrics + Monte Carlo forecasts, delegation-governance gate, /cs:pm + /cs:grill-pm + /cs:pm-loop), senior PM, scrum master, Jira expert, Confluence expert, Atlassian admin, template creator, meeting analyzer, team communications. Bundled Atlassian Remote MCP.",
"version": "2.11.1",
"author": {
"name": "Alireza Rezvani"
},

21
CLAUDE.md
View file

@ -6,7 +6,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
This is a **comprehensive skills library** for Claude AI and Claude Code - reusable, production-ready skill packages that bundle domain expertise, best practices, analysis tools, and strategic frameworks. The repository provides modular skills that teams can download and use directly in their workflows.
**Current Scope:** 355 production-ready skills across 18 domains with 596 Python automation tools, 725 reference guides, 97 agents (cs-* + 7 personas), and 103 slash commands, distributed as 83 marketplace plugins. Headline counters are derived from the tree by `scripts/derive_counters.py` (run with `--check` to verify the docs still match). **v2.9.0 (complete)** added the **research-ops/** top-level domain — enterprise Research Operations (orchestrator + clinical-research + research-finance + market-research + product-research), the managed counterpart to the academic research/ domain, with `context: fork` orchestration and a Matt Pocock "Forcing-question library" in every SKILL.md plus `/cs:grill-research-ops`. **v2.8.0 (complete)** added 2 new top-level domains — **business-operations/** (7 internal-ops skills: orchestrator + process-mapper + vendor-management + capacity-planner + internal-comms + knowledge-ops + procurement-optimizer) and **commercial/** (8 per-deal-economics skills: orchestrator + pricing-strategist + deal-desk + partnerships-architect + channel-economics + commercial-policy + rfp-responder + commercial-forecaster) — with orchestrator skills using `context: fork` for chaining, Matt Pocock docs-anchored "Forcing-question library" in every SKILL.md, plus `/cs:grill-bizops` and `/cs:grill-commercial`. **v2.8.2** adds a productivity-shaped `handoff` skill (sibling to engineering/handoff) inspired by Matt Pocock — first-run setup with configurable save location, redaction linter, SessionStart + SessionEnd hooks, fidelity self-check, `--refresh` flag. **v2.8.1** upgraded the engineering role-skills (senior-fullstack / senior-frontend / senior-backend) with karpathy-coder + Matt Pocock decision engines + per-role forcing questions. v2.7.3 ports `alirezarezvani/aeo-box` — AEO (Answer Engine Optimization) skill into marketing-skill/ + security-guidance PreToolUse hook into engineering/. v2.7.0 added 13 Path-B skills across 3 top-level domains (productivity, marketing, research). v2.6.0 added 4 Matt Pocock-derived productivity skills.
**Current Scope:** 355 production-ready skills across 18 domains with 602 Python automation tools, 731 reference guides, 99 agents (cs-* + 7 personas), and 109 slash commands, distributed as 83 marketplace plugins. Headline counters are derived from the tree by `scripts/derive_counters.py` (run with `--check` to verify the docs still match). **v2.11.1 (current)** upgrades **product-team/** and **project-management/** into agent-harness domains: both prose routers rebuilt as `context: fork` orchestrators with deterministic goal routers (exit-code route/ask/refuse), a Jira MCP snapshot bridge (Kanban-Guide-2025 flow metrics + seeded Monte Carlo forecasts, verified end-to-end into velocity_analyzer), a delegation-governance loop gate (human owner / reviewer / machine-checkable acceptance / close refusal), a Torres continuous-discovery cadence tracker + Opportunity Solution Tree linter, cs-pm-orchestrator + cs-product-orchestrator agents, and /cs:pm|grill-pm|pm-loop + /cs:product|grill-product|product-loop commands — plus the public audit record `audit/pm-product-agentic-2026-07/` (AR-rubric scores for all 26 skills, research-backed improvement fields, executable verification criteria). **v2.9.0 (complete)** added the **research-ops/** top-level domain — enterprise Research Operations (orchestrator + clinical-research + research-finance + market-research + product-research), the managed counterpart to the academic research/ domain, with `context: fork` orchestration and a Matt Pocock "Forcing-question library" in every SKILL.md plus `/cs:grill-research-ops`. **v2.8.0 (complete)** added 2 new top-level domains — **business-operations/** (7 internal-ops skills: orchestrator + process-mapper + vendor-management + capacity-planner + internal-comms + knowledge-ops + procurement-optimizer) and **commercial/** (8 per-deal-economics skills: orchestrator + pricing-strategist + deal-desk + partnerships-architect + channel-economics + commercial-policy + rfp-responder + commercial-forecaster) — with orchestrator skills using `context: fork` for chaining, Matt Pocock docs-anchored "Forcing-question library" in every SKILL.md, plus `/cs:grill-bizops` and `/cs:grill-commercial`. **v2.8.2** adds a productivity-shaped `handoff` skill (sibling to engineering/handoff) inspired by Matt Pocock — first-run setup with configurable save location, redaction linter, SessionStart + SessionEnd hooks, fidelity self-check, `--refresh` flag. **v2.8.1** upgraded the engineering role-skills (senior-fullstack / senior-frontend / senior-backend) with karpathy-coder + Matt Pocock decision engines + per-role forcing questions. v2.7.3 ports `alirezarezvani/aeo-box` — AEO (Answer Engine Optimization) skill into marketing-skill/ + security-guidance PreToolUse hook into engineering/. v2.7.0 added 13 Path-B skills across 3 top-level domains (productivity, marketing, research). v2.6.0 added 4 Matt Pocock-derived productivity skills.
**Key Distinction**: This is NOT a traditional application. It's a library of skill packages meant to be extracted and deployed by users into their own Claude workflows.
@ -159,6 +159,19 @@ See [standards/git/git-workflow-standards.md](standards/git/git-workflow-standar
## Current Version
**Version:** v2.11.1 (pm/product agent-harness domains — deep audit + orchestrated loops for product-team & project-management)
**v2.11.1 highlights — both PM/product routers become agent harnesses:**
Extends the v2.11.0 agent-harness layer to the two people-process domains. Public audit record at `audit/pm-product-agentic-2026-07/` (AR-rubric scores for all 26 skills, research-backed improvement fields, executable verification criteria).
- **project-management → delivery loop:** `pm-skills` rebuilt as a `context: fork` orchestrator with 3 stdlib tools — `pm_goal_router.py` (8 lanes, exit-code route/ask/refuse), `jira_snapshot_bridge.py` (saved `searchJiraIssuesUsingJql` output → Kanban-Guide-2025 flow metrics with SLE + aging-WIP alerts + seeded Monte Carlo forecasts that sample zero-throughput weeks, or the scrum-master sprint schema — verified end-to-end into `velocity_analyzer.py`), `delivery_loop_gate.py` (delegation governance G1–G6: human owner, reviewer for agent tasks, machine-checkable acceptance, evidence-before-done, close refusal, exhausted-budget-is-escalation). Five reusable PM loops documented with named terminal states. Agent `cs-pm-orchestrator`; commands `/cs:pm`, `/cs:grill-pm`, `/cs:pm-loop`.
- **product-team → discovery loop:** `product-skills` rebuilt as a `context: fork` orchestrator with 3 stdlib tools — `product_goal_router.py` (16 lanes incl. the 4 standalone plugins), `discovery_cadence_tracker.py` (Torres weekly-habit health 0–100 with named gaps + `next_loop_action`), `ost_linter.py` (Opportunity Solution Tree rules O1–O5; exit 2 blocks an unsound tree from driving a roadmap). Agent `cs-product-orchestrator`; commands `/cs:product`, `/cs:grill-product`, `/cs:product-loop`.
- **6 new references** citing 6–7 sources each (flow/forecasting canon, agentic delivery governance, PM loop playbook, continuous discovery, product operating model, AI product evals) + pinned fixtures; fixed the two CLI-noncompliant product tools (`user_story_generator.py`, `persona_generator.py` — real argparse `--help`, seeded determinism); regenerated both domain harness manifests (orchestrators now score all five `agentic_signals`; manifest builder now truncates descriptions on word boundaries).
- **Counters:** tools 596 → 602; refs 725 → 731; agents 97 → 99; commands 103 → 109 (derived via `scripts/derive_counters.py --check`).
---
**Version:** v2.11.0 (agent-harness — turn any domain into a bounded, self-verifying agent loop + engineering agentic-readiness audit)
**v2.11.0 highlights — agent-harness skill + AR audit of both engineering folders:**
@ -537,6 +550,6 @@ This repository publishes skills to **ClawHub** (clawhub.com) as the distributio
---
**Last Updated:** June 10, 2026
**Version:** v2.10.3
**Status:** 345 skills deployed across 17 domains, 78 marketplace plugins, docs site live (counters derived via `scripts/derive_counters.py`)
**Last Updated:** July 3, 2026
**Version:** v2.11.1
**Status:** 355 skills deployed across 18 domains, 83 marketplace plugins, docs site live (counters derived via `scripts/derive_counters.py`)

6
README.md
View file

@ -26,10 +26,10 @@ The most comprehensive open-source library of Claude Code skills and agent plugi
Claude Code skills (also called agent skills or coding agent plugins) are modular instruction packages that give AI coding agents domain expertise they don't have out of the box. Each skill includes:
- **SKILL.md** — structured instructions, workflows, and decision frameworks
- **Python tools** — 596 CLI scripts (all stdlib-only, zero pip installs)
- **Python tools** — 602 CLI scripts (all stdlib-only, zero pip installs)
- **Reference docs** — 711 templates, checklists, and domain-specific knowledge files
**One repo, thirteen platforms.** Works natively as Claude Code plugins, Codex agent skills, Gemini CLI skills, Hermes Agent skills, Mistral Vibe skills, and converts to more tools via `scripts/convert.sh`. All 596 Python tools run anywhere Python runs.
**One repo, thirteen platforms.** Works natively as Claude Code plugins, Codex agent skills, Gemini CLI skills, Hermes Agent skills, Mistral Vibe skills, and converts to more tools via `scripts/convert.sh`. All 602 Python tools run anywhere Python runs.
### Skills vs Agents vs Personas
@ -354,7 +354,7 @@ Yes. Skills work natively with 13 tools: Claude Code, OpenAI Codex, Gemini CLI,
No. We follow semantic versioning and maintain backward compatibility within patch releases. Existing script arguments, plugin source paths, and SKILL.md structures are never changed in patch versions. See the [CHANGELOG](CHANGELOG.md) for details on each release.
**Are the Python tools dependency-free?**
Yes. All 596 Python CLI tools use the standard library only — zero pip installs required. Every script is verified to run with `--help`.
Yes. All 602 Python CLI tools use the standard library only — zero pip installs required. Every script is verified to run with `--help`.
**How do I create my own Claude Code skill?**
Each skill is a folder with a `SKILL.md` (frontmatter + instructions), optional `scripts/`, `references/`, and `assets/`. See the [Skills & Agents Factory](https://github.com/alirezarezvani/claude-code-skills-agents-factory) for a step-by-step guide.

123
audit/pm-product-agentic-2026-07/00-MASTER.md Normal file
View file

@ -0,0 +1,123 @@
# Master report — Product & PM agentic-loop audit + domain harness upgrade
**Audited:** 2026-07-03 · **Branch:** `claude/pm-audit-agentic-loops-jxurlq` ·
**Scope:** both product/project domains — `product-team/` (17 skills) and
`project-management/` (9 skills) — deep-audited on quality AND scored on the
**agentic-readiness** rubric established by the engineering audit
([../engineering-agentic-2026-07/](../engineering-agentic-2026-07/00-MASTER.md)).
Plus: both domains upgraded into **agent harnesses** — fork-orchestrators with
deterministic routers, reusable loops, machine-checkable verification gates, and
integration with the repo-wide `engineering/agent-harness` framework.
**Method:** (1) two parallel deep-dive agents read every SKILL.md, smoke-tested all 31
scripts, and cross-referenced agents/commands/manifests; (2) one explorer mapped the
repo's harness conventions (loop-library contract, agent-harness state machine,
fork-orchestrator pattern) so the upgrade reuses rather than reinvents; (3) one research
agent web-verified the 2024–2026 PM/product/harness canon
([research-digest.md](research-digest.md)).
---
## 1. The two questions
The June 2026 audit asked: does each skill earn its context window? This audit asks the
engineering follow-up question for these two domains: **can an agent pick up a goal here
and drive it to a verified close?** — and additionally: **what should these domains
teach that the 2024–2026 canon now demands?**
([improvement-fields.md](improvement-fields.md) answers the second.)
## 2. Combined scorecard (26 skills, post-PR)
| Class | product-team | project-management | Total | Meaning |
|---|---|---|---|---|
| **HARNESS-READY** (≥9, AR4≥1, AR5≥1) | 2 | 1 | **3** | An agent can loop this today |
| **LOOP-CAPABLE** (6–8) | 4 | 4 | **8** | One or two additions away |
| **TOOL-ONLY** (3–5) | 11 | 3 | **14** | Good tools, no loop spine |
| **PROSE-ONLY** (0–2) | 0 | 1 | **1** | Needs structural rebuild |
Pre-PR both domain routers were PROSE-ONLY (score ≤ 1) and neither domain had a single
`context: fork`, forcing question, iteration cap, or `/cs:*` command — they predate every
v2.8+ convention. The weakest dimensions mirror engineering exactly: **AR5 loop
discipline** (zero caps anywhere pre-PR) and **AR1 goal intake** (most skills accept any
input silently).
## 3. The three biggest findings
1. **The MCP↔analytics gap (project-management).** The domain bundles a live Jira MCP
and ships real analytics tools, with no data path between them — sprint health and
velocity ran on hand-typed JSON. Fixed: `jira_snapshot_bridge.py` converts saved
`searchJiraIssuesUsingJql` results into the scrum-master schema (verified end-to-end
into velocity_analyzer) and computes the four Kanban-Guide-2025 flow metrics + seeded
Monte Carlo forecasts the domain never had.
2. **Verification exists but nothing binds it (both domains).** spec-to-repo's
validator, code-to-prd's golden outputs, scrum-master's pinned fixtures,
atlassian-admin's 7 VERIFY steps — good gates, all optional, none looped. Fixed at
the orchestration layer: plans are gated before execution and closes are refused
(exit 4) while tasks are unverified/unwaived; per-skill binding is follow-up F3.
3. **The canon moved (both domains).** No continuous-discovery cadence, no OST
discipline, no AI-feature evals, no flow metrics, no probabilistic forecasting, no
agentic-delegation governance, and 60 of 64 reference files cite zero sources. This
PR ships the two highest-leverage tool fields per domain plus six cited reference
docs; the remaining 14 fields are enumerated with tool specs in
[improvement-fields.md](improvement-fields.md).
## 4. What this PR ships: two domain harnesses
Both prose routers were rebuilt as `context: fork` orchestrators that plug into
`engineering/agent-harness` (manifests regenerated; both orchestrators now score all
five `agentic_signals`):
**project-management → `pm-skills`** — the *delivery loop*:
`pm_goal_router.py` (8 lanes, exit 0/2/3 — route/ask/refuse) ·
`jira_snapshot_bridge.py` (MCP snapshot → flow metrics | sprint schema; SLE conformance,
aging-WIP alerts, `--forecast` Monte Carlo, refuses thin history) ·
`delivery_loop_gate.py` (delegation governance G1–G6: human owner, reviewer for agent
tasks, machine-checkable acceptance, evidence-before-done, close refusal,
exhausted-budget-is-escalation). Five reusable PM loops (sprint-flow, health,
retro-action, RAID-hygiene, comms) documented with terminal states. Agent
`cs-pm-orchestrator`; commands `/cs:pm`, `/cs:grill-pm`, `/cs:pm-loop`.
**product-team → `product-skills`** — the *discovery loop*:
`product_goal_router.py` (16 lanes incl. the 4 standalone plugins) ·
`discovery_cadence_tracker.py` (Torres weekly-habit scoring: streak, coverage, outcome
linkage, test throughput → health 0–100 with named gaps and a `next_loop_action`) ·
`ost_linter.py` (O1–O5: measurable outcome root, needs-not-features, ≥2 solutions per
target, tests per solution, no orphan solutions — exit 2 blocks the tree from driving a
roadmap). Graduation stop-states hand validated assumptions to experiment-designer/PRD.
Agent `cs-product-orchestrator`; commands `/cs:product`, `/cs:grill-product`,
`/cs:product-loop`.
Also fixed: the two CLI-noncompliant product tools (`user_story_generator.py`,
`persona_generator.py` — real argparse `--help`, seeded determinism, backward-compatible
positionals); domain CLAUDE.md counters; plugin manifests + marketplace descriptions.
All 8 new/changed tools pass `--help` and `--sample`; fixtures pinned
(`expected_flow_metrics.json`; sample OST with two planted violations). Every design
decision traces to the loop-library contract, the agent-harness invariants (locked
gates, evidence-before-status, budgets-as-terminal-states), and the cited canon.
## 5. Per-domain reports
- [product-team.md](product-team.md) — 17 skills, AR table, 7 domain findings,
executable verification criteria.
- [project-management.md](project-management.md) — 9 skills, AR table, 6 domain
findings, executable verification criteria.
- [improvement-fields.md](improvement-fields.md) — the per-field improvement rollup
(11 cross-domain/delivery/product fields shipped or specced + documentation debt).
- [research-digest.md](research-digest.md) — the web-verified 2024–2026 canon.
- [RUBRIC.md](RUBRIC.md) — the AR rubric as applied here.
## 6. Recommended follow-up PRs (in leverage order)
1. **Loop-cap sweep** — one-sentence caps in scrum-master, jira-expert, code-to-prd,
research-summarizer (~4 skills → HARNESS-READY).
2. **Bind the gates** — make spec-to-repo's validator and code-to-prd's goldens
*required*; name the bridge in scrum-master/senior-pm SKILL.mds.
3. **AI-evals tool** (F–h) — eval-spec linter + kappa calculator; the single
most-demanded missing PM competency.
4. **Path-B completion** — meeting-analyzer scripts (its spec is deterministic math),
team-communications linter, product-discovery references.
5. **Documentation truth** — product-team README (3 conflicting counts, 9 broken paths),
project-management legacy trio, citation back-fill (F9/F10).
6. **Remaining improvement fields** — DORA/EBM/pre-mortem/RACI (delivery); NSM/PLG
bands/WSJF/ODI/taxonomy linter (product), per the specs in improvement-fields.md.

30
audit/pm-product-agentic-2026-07/RUBRIC.md Normal file
View file

@ -0,0 +1,30 @@
# Agentic-Readiness Rubric (AR v1) — as applied to product-team + project-management
Audit date: 2026-07-03 · Branch: `claude/pm-audit-agentic-loops-jxurlq`
This audit applies the **same AR v1 rubric** established by the engineering agentic audit
([../engineering-agentic-2026-07/RUBRIC.md](../engineering-agentic-2026-07/RUBRIC.md)) —
six dimensions scored 0–2, answering: **can an agent pick this skill up with a goal and
drive it to a verified close?**
| # | Dimension | 2 means |
|---|---|---|
| AR1 | Goal intake | Forcing questions / intake tool / refuses vague input (exit-code gate) |
| AR2 | Task decomposition | Explicit planning step or tool whose output the workflow consumes |
| AR3 | Deterministic execution | Exact runnable CLIs; output consumed by a named next step |
| AR4 | Verification | Machine-checkable gate the workflow REQUIRES before proceeding |
| AR5 | Loop discipline | Iteration caps, stop conditions, escalation thresholds |
| AR6 | Close-out | Definition of done + state persistence or handoff artifact |
Classes: **HARNESS-READY** (total ≥ 9 AND AR4 ≥ 1 AND AR5 ≥ 1) · **LOOP-CAPABLE** (6–8,
or ≥ 9 failing the AR4/AR5 gate) · **TOOL-ONLY** (3–5) · **PROSE-ONLY** (0–2).
Baseline reference: the June 2026 quality audit of these domains lives at
[../newgen-2026-06/product-pm.md](../newgen-2026-06/product-pm.md); this audit scores the
new agentic dimension and ships the domain harness layer that the scores motivated.
Executable enforcement: the regenerated domain manifests
(`engineering/agent-harness/skills/agent-harness/assets/harnesses/{product-team,project-management}.json`)
record per-skill `agentic_signals`; the two new domain orchestrators (`product-skills`,
`pm-skills`) enforce AR1 (routers with exit-code gates), AR4 (delivery gate / OST linter),
and AR5/AR6 (harness budgets + close refusal) at run time.

66
audit/pm-product-agentic-2026-07/improvement-fields.md Normal file
View file

@ -0,0 +1,66 @@
# Improvement fields — where investment moves each domain most
Research-backed rollup (sources in [research-digest.md](research-digest.md)) of the
fields where the 2024–2026 canon moved past the two domains' current coverage, ordered
by leverage. Fields marked ✅ shipped in this PR; the rest are the follow-up work list,
each with what a deterministic stdlib tool computes.
## Cross-domain (the harness fields)
- **F1 — Loop discipline (AR5)** ✅ *(orchestrator layer)* / open *(per skill)*. Both
domains had zero iteration caps or stop conditions. Shipped: the two orchestrators
carry budgets (3 attempts/task, 12 iterations/goal), named terminal states, and close
refusal. Open: the one-sentence cap pattern ("max N fix-rerun cycles, then escalate")
ported into scrum-master, jira-expert, code-to-prd, research-summarizer — the four
skills one sentence away from HARNESS-READY.
- **F2 — Goal intake (AR1)** ✅ *(routers)* / open *(per skill)*. Both routers refuse
fuzz with exit codes (2/3); grill commands lock decisions before execution. Open:
refuse-on-missing-inputs blocks in the 14 tool-rich skills that still accept anything.
- **F3 — Bind existing gates** — open, cheapest wins: spec-to-repo's validator and
code-to-prd's goldens exist but aren't *required*; scrum-master/senior-pm SKILL.mds
should name the bridge as their data path (one line each).
## Project-management (delivery) fields
| # | Field | Status | Deterministic tool |
|---|---|---|---|
| F4 | Four Kanban flow metrics + SLE + aging-WIP alerts (Kanban Guide 2025) | ✅ `jira_snapshot_bridge.py --to flow` | WIP, throughput, cycle p50/85/95, work-item age, SLE conformance |
| F5 | Monte Carlo probabilistic forecasting (Vacanti; replaces story-point dates) | ✅ `--forecast N` (seeded; refuses < 10 items) | p50/70/85/95 week ranges |
| F6 | Agentic delegation governance (Linear/Rovo model) | ✅ `delivery_loop_gate.py` | owner/reviewer/acceptance/evidence/close rules G1–G6 |
| F–a | DORA 2025 archetypes + AI-amplifier capabilities check | open | four keys from deploy/incident logs → archetype + enabling-capabilities score |
| F–b | EBM (Scrum.org) four Key Value Areas scorecard | open | map existing metrics → KVA coverage, flag empty CV/UV |
| F–c | Pre-mortem processor (Klein) + RAID hygiene linter | open (playbook documents the loops) | cluster failure reasons → owned risk entries; staleness/owner/mitigation lint |
| F–d | Derived project health vs self-reported RAG ("watermelon" diff) | partial (senior-pm dashboard + bridge signals) | composite from schedule variance, aging WIP, scope churn — diffed against RAG |
| F–e | Async-first meeting audit (GitLab canon) | open | calendar export → async-convertibility classes, recoverable hours |
| F–f | Agent-readiness audit of Jira hygiene (Rovo-era) | open | field completeness %, acceptance-criteria presence, stale statuses → delegation-readiness score |
| F–g | RACI validator | open | exactly-one-A, ≥1 R, overload histogram |
## Product-team fields
| # | Field | Status | Deterministic tool |
|---|---|---|---|
| F7 | Continuous-discovery cadence (Torres weekly habit) | ✅ `discovery_cadence_tracker.py` | streak, coverage, outcome linkage, test throughput → health 0–100 |
| F8 | Opportunity Solution Tree structural linting | ✅ `ost_linter.py` | rules O1–O5 (measurable root, needs-not-features, ≥2 solutions, tests, no orphans) |
| F–h | **AI-feature evals as the PRD quality contract** — the single biggest gap per every 2025–2026 source | reference shipped (`ai_product_evals.md`); tool open | eval-spec linter: golden-set floors, rubric pass-criteria, guardrail SLOs; Cohen's kappa on grader agreement |
| F–i | WSJF / cost-of-delay with rank-stability sensitivity (brackets RICE) | reference shipped (`product_operating_model.md`); tool open | CoD/duration ranking; ±1-step perturbation flags rank flips |
| F–j | Opportunity scoring (Ulwick ODI importance–satisfaction) | open | Opp Score per outcome statement from survey CSV |
| F–k | North Star Metric validator + input tree (Amplitude) | open | leading/value/not-vanity checks; input→NSM correlation |
| F–l | PLG funnel benchmark bands (ProductLed/OpenView) | open | stage conversion vs calibrated bands → weakest-stage verdict |
| F–m | Product operating model maturity (Cagan *Transformed*) | open | questionnaire → per-principle 0–100 gap list |
| F–n | Event-taxonomy / tracking-plan linter (PostHog-era) | open | snake_case, verb allowlist, near-duplicate detection |
| F–o | JTBD switch-interview force coder (Moesta) | open | four-forces lexicon coding, force balance per interview |
| F–p | Story-map validator (Patton) | open | every story on the backbone; slices span end-to-end |
| F–q | Model-card completeness checker (Mitchell et al.) | open | nine canonical sections → completeness % |
## Documentation-debt fields
- **F9 — Source citations**: 60 of 64 pre-PR reference files across both domains cite
zero sources (six new references cite 6–7 each). Back-fill priority: scrum-master and
senior-pm references (the canon exists — Vacanti, Kanban Guide, DORA, PMBOK).
- **F10 — Counter/path truth**: product-team README (3 conflicting counts, 9 broken
paths), project-management legacy trio (README / IMPLEMENTATION_SUMMARY /
REAL_WORLD_SCENARIO all say "6 skills"), `.codex/instructions.md` broken paths in both
domains. Domain CLAUDE.mds fixed this PR.
- **F11 — Path-B completion**: meeting-analyzer (0 scripts/refs/assets — its own spec is
deterministic math), team-communications (0 scripts, 155 lines of references),
product-discovery (1 reference), 8 asset-less product skills.

98
audit/pm-product-agentic-2026-07/product-team.md Normal file
View file

@ -0,0 +1,98 @@
# Domain audit: product-team/ — deep audit + agentic readiness
Audited: 2026-07-03 · 17 skills (13 under `skills/` incl. the router, 4 standalone
plugins) · 19 Python tools (all 19 pass `--help`, functional smoke tests on
sample_size_calculator and hig_checker reproduce correct math) · 5 agents + 1 persona ·
8 slash commands · 5 plugins (all `check_plugin_json.py`-clean).
Rubric: [RUBRIC.md](RUBRIC.md). Method: full SKILL.md reads, script smoke tests,
agent/command cross-referencing, counter verification.
## Summary
**Headline finding (now fixed in this PR): no orchestrator, no loop layer.** Before this
PR the domain had zero `context: fork`, zero forcing-question libraries, no `/cs:*`
router/grill commands, and its "router" (`product-skills`, 61 lines) shipped no tools —
the domain predated every v2.8+ convention. Three skills (spec-to-repo, code-to-prd,
research-summarizer) independently invented verification loops; nothing unified them.
**Agentic-readiness distribution (17 skills, post-PR):** HARNESS-READY **2**
(product-skills upgraded 1→12; spec-to-repo) · LOOP-CAPABLE **4** (product-manager-toolkit,
apple-hig-expert, code-to-prd, research-summarizer) · TOOL-ONLY **11** · PROSE-ONLY **0**.
Weakest dimensions domain-wide: **AR5 loop discipline** (only spec-to-repo has any
retry/stop language) and **AR1 goal intake** (14 of 17 accept any input silently).
## Per-skill table
Scores AR1·AR2·AR3·AR4·AR5·AR6 (post-PR where this PR changed the skill).
| Skill | AR1-6 | Tot | Class | Top improvement |
|---|---|---|---|---|
| skills/product-skills (orchestrator) | 2·2·2·2·2·2 | 12 | HR | (upgraded this PR: was a 61-line prose router, PROSE-ONLY) |
| skills/spec-to-repo | 1·2·2·2·1·1 | 9 | HR | Wire to an agent + command (currently orphaned from both) |
| skills/product-manager-toolkit | 1·1·2·1·0·1 | 6 | LC | Make the PRD checklist a blocking gate; add WSJF/CoD lane + eval-spec PRD section |
| code-to-prd (standalone) | 1·2·2·2·0·2 | 9 | LC (AR5 gate) | One sentence: max 2 analyze-fix cycles vs golden `expected_outputs/`, then escalate |
| research-summarizer (standalone) | 1·1·2·2·0·1 | 7 | LC | Cap the Verification Loop (2 re-extraction passes) → instant HR |
| apple-hig-expert (standalone) | 1·0·2·2·0·1 | 6 | LC | Numbered workflow; move `templates/` → `assets/`; add fix-recheck cap |
| skills/experiment-designer | 1·1·2·1·0·0 | 5 | TO | Make sample-size output a blocking gate on any test recommendation; 423 words is thin |
| skills/ux-researcher-designer | 0·1·2·1·0·1 | 5 | TO | (fake `--help` + unseeded RNG fixed this PR) Validation checklists → exit gates |
| skills/ui-design-system | 0·1·2·1·0·1 | 5 | TO | Add command; disambiguate vs markdown-html/design-system |
| skills/saas-scaffolder | 0·1·2·1·0·1 | 5 | TO | Make the 33-item checklist machine-checkable (reuse spec-to-repo's validator); dedupe references pair |
| agile-product-owner (standalone) | 0·1·2·1·0·1 | 5 | TO | (fake `--help` fixed this PR) INVEST checklist → gate |
| skills/product-analytics | 0·1·2·1·0·0 | 4 | TO | NSM validator + benchmark bands (see improvement-fields F7/F8); anti-patterns table exists, gate doesn't |
| skills/landing-page-generator | 0·1·2·1·0·0 | 4 | TO | Add `distinct_from` vs marketing/landing; render-check gate on emitted TSX |
| skills/product-strategist | 0·1·2·0·0·1 | 4 | TO | Alignment score exists but nothing requires it; outcome-vs-output OKR lint |
| skills/competitive-teardown | 0·1·2·0·0·0 | 3 | TO | Data-verification discipline (it synthesizes scraped claims with no source gate) |
| skills/product-discovery | 0·1·2·0·0·0 | 3 | TO | Wire to the new discovery loop (orchestrator now provides tracker + OST linter); 1 reference, no agent/command |
| skills/roadmap-communicator | 0·0·2·1·0·0 | 3 | TO | Merge-or-disambiguate vs `/changelog` + engineering/changelog-generator; 367 words |
## Domain-level findings
1. **Orchestration gap (fixed this PR).** `product-skills` is now a `context: fork`
orchestrator with a deterministic 16-lane router (`product_goal_router.py`, exit
0/2/3), a recurring discovery loop with two machine gates
(`discovery_cadence_tracker.py`, `ost_linter.py`), a forcing-question library, and
agent-harness integration. Agent `cs-product-orchestrator` + `/cs:product`,
`/cs:grill-product`, `/cs:product-loop` commands added.
2. **References cite no sources: 39 of 43 reference files contain zero URLs/citations.**
Only apple-hig-expert (3/3) and research-summarizer (1/2) meet the ≥5-sources bar. The
3 new orchestrator references cite 7 sources each; the other 39 remain open work.
3. **Two tools faked their `--help` (fixed this PR).** `user_story_generator.py` and
`persona_generator.py` exited 0 while ignoring the flag and running demos;
persona_generator was additionally non-deterministic (unseeded `random.choice`). Both
now use argparse; personas are seeded (default 42).
4. **Stale/contradictory counters + broken paths (open).** product-team/README.md holds 3
mutually inconsistent counts and 9 broken Quick Start paths (missing `skills/`
segment); `.codex/instructions.md` has 3 broken paths; CLAUDE.md says "13 skills" then
lists 16, claims 17 tools (actual 19). The domain plugin.json description claims
skills the bundle doesn't contain. CLAUDE.md counters updated this PR; README overhaul
is follow-up F10.
5. **Unmanaged overlaps (open):** landing-page-generator ↔ `marketing/landing`;
saas-scaffolder ↔ spec-to-repo; roadmap-communicator ↔ `/changelog` +
`engineering/changelog-generator`; ui-design-system ↔ `markdown-html/design-system`.
Only research-summarizer ships a "Distinct From" section. The orchestrator's routing
table now provides partial disambiguation; per-skill `distinct_from` notes remain.
6. **8 of 13 bundled skills ship 0 assets** despite the repo's template-heavy principle;
apple-hig-expert uses a nonstandard `templates/` dir.
7. **Agent/command coverage holes (open):** 6 skills map to no cs-* agent
(product-discovery, roadmap-communicator, spec-to-repo, code-to-prd, apple-hig-expert,
research-summarizer); 10 have no slash command. The orchestrator router reaches all 17
lanes, which mitigates but does not close this.
## Verification criteria (executable)
- **product-skills (orchestrator):** `python3 product-team/skills/product-skills/scripts/product_goal_router.py --sample`
exits 0 and routes to `product-discovery`; `--text "hello"` exits 3;
`discovery_cadence_tracker.py --input assets/sample_discovery_log.json` exits 0 with
`health_score` 62.0 and verdict `AT-RISK`; `ost_linter.py --input assets/sample_ost.json`
exits 2 with exactly one O2 and one O4 violation; `--sample` variants all exit 0.
- **spec-to-repo:** `validate_project.py --strict` on a scaffolded repo exits 0 before
the workflow may report done (existing contract, holds).
- **code-to-prd:** analyzer output diffs clean against `expected_outputs/` goldens
(existing contract, holds).
- **persona_generator (fixed):** `--help` prints argparse usage (not a demo); two `json`
runs produce byte-identical output.
- **user_story_generator (fixed):** `--help` prints argparse usage; `sprint 30` still
plans a 30-point sprint (backward-compatible positional).
- **Manifest truth:** `harness_manifest_builder.py --domain product-team --no-timestamp`
produces a diff-clean `product-team.json` with `product-skills` scoring all five
`agentic_signals` true and 3 wired, sample-supporting tools.

102
audit/pm-product-agentic-2026-07/project-management.md Normal file
View file

@ -0,0 +1,102 @@
# Domain audit: project-management/ — deep audit + agentic readiness
Audited: 2026-07-03 · 9 skills · 12 Python tools pre-PR (all pass `--help`; end-to-end
runs of velocity_analyzer and project_health_dashboard reproduce documented fixtures),
15 post-PR · 1 agent pre-PR, 2 post · 3 commands pre-PR (+`/sprint-plan` generic), 6
post · plugin.json valid (`["./skills"]` canonical form).
Rubric: [RUBRIC.md](RUBRIC.md). Method: full SKILL.md reads, script smoke tests, MCP
tool-reference grepping, counter verification.
## Summary
**Headline finding #1 (fixed this PR): the MCP↔analytics gap.** The domain bundles a
live Atlassian Remote MCP (`.mcp.json`) and disciplined tool documentation
(`references/atlassian-mcp-tools.md`, verified live 2026-06-10), yet its two analytics
skills (senior-pm, scrum-master) had **zero** MCP references — nothing connected
`searchJiraIssuesUsingJql` output to the scripts' input schemas. Every sprint-health or
velocity run required hand-built JSON. `jira_snapshot_bridge.py` closes this: raw MCP
search results → scrum-master sprint schema (verified: piped output runs
velocity_analyzer clean) → plus the four Kanban flow metrics + seeded Monte Carlo
forecasting the domain never had.
**Headline finding #2 (fixed this PR): pre-modern agentics.** Zero `context: fork`, zero
forcing questions, no `/cs:*` namespace, no loop with named terminal states. What existed
was raw material: atlassian-admin's 7 concrete VERIFY steps, scrum-master's
data-sufficiency gates with pinned expected outputs (avg 20.2 pts, health 78.3,
action-item completion 46.7%), confluence/templates' verify-before-proceed steps.
**Agentic-readiness distribution (9 skills, post-PR):** HARNESS-READY **1** (pm-skills
upgraded 1→12) · LOOP-CAPABLE **4** (scrum-master, jira-expert, atlassian-admin,
atlassian-templates) · TOOL-ONLY **3** (senior-pm, confluence-expert, meeting-analyzer) ·
PROSE-ONLY **1** (team-communications).
## Per-skill table
Scores AR1·AR2·AR3·AR4·AR5·AR6 (post-PR where this PR changed the skill).
| Skill | AR1-6 | Tot | Class | Top improvement |
|---|---|---|---|---|
| pm-skills (orchestrator) | 2·2·2·2·2·2 | 12 | HR | (upgraded this PR: was a 50-line prose router, PROSE-ONLY) |
| scrum-master | 1·1·2·2·0·1 | 7 | LC | One sentence: cap re-analysis at 2 passes then escalate → instant HR; consume the bridge (`--to sprint`) instead of hand-built JSON |
| atlassian-admin | 0·1·2·2·0·2 | 7 | LC | Intake gate (refuse without approver named); its VERIFY steps are the domain's best — port the pattern to siblings |
| jira-expert | 0·1·2·2·0·1 | 6 | LC | Cap fix-revalidate cycles at 3; ship a sample workflow JSON asset (users must guess the validator's schema) |
| atlassian-templates | 0·1·2·1·1·1 | 6 | LC | Ship static template assets; expected-output fixture for the scaffolder |
| senior-pm | 0·1·2·1·0·1 | 5 | TO | Consume the bridge's flow output in the health dashboard; make KPI thresholds (on-time > 80% etc.) exit-code gates; portfolio-kpis.md is 32 lines |
| confluence-expert | 0·1·2·1·0·1 | 5 | TO | Make its Verify steps blocking; sample input for content_audit_analyzer |
| meeting-analyzer | 1·1·0·1·0·1 | 4 | TO | Ship the deterministic tools its own prose describes (speaking-ratio, filler counts = exactly the repo's "algorithm over AI" case); 0 scripts/refs/assets |
| team-communications | 1·1·0·0·0·0 | 2 | PO | References are 15–65 lines (the skill's premise is "follow the reference exactly"); add a 3P-format linter script |
## Domain-level findings
1. **Orchestration + loop layer (fixed this PR).** `pm-skills` is now a `context: fork`
orchestrator: deterministic 8-lane router (`pm_goal_router.py`), the Jira bridge, and
a delegation-governance gate (`delivery_loop_gate.py` — G1 human owner, G2 reviewer
for agent tasks, G3 machine-checkable acceptance, G4 evidence-before-done, G5 close
refusal, G6 exhausted-budget-is-escalation), all wired to the repo harness
(`assets/harnesses/project-management.json`). Agent `cs-pm-orchestrator` +
`/cs:pm`, `/cs:grill-pm`, `/cs:pm-loop` added. Five reusable PM loops documented in
`references/pm_loop_playbook.md` (sprint-flow, health, retro-action, RAID-hygiene,
comms), each with machine gates and named terminal states.
2. **References cited zero sources (partially fixed).** 0 URLs across all 21 pre-PR
reference files — Schwaber/Sutherland, Vacanti, DORA, Kanban Guide all absent. The 3
new orchestrator references cite 6–7 sources each; back-filling the other 21 is
follow-up F9.
3. **Stale counters everywhere except plugin.json (open).** README ("6 world-class
skills"), IMPLEMENTATION_SUMMARY ("All 6", references `/mnt/user-data/outputs/` build
paths), REAL_WORLD_SCENARIO ("6 Expert Skills"), cs-project-manager agent ("six
skills"), CLAUDE.md (lists 6 of 9 — meeting-analyzer, team-communications, pm-skills
absent). CLAUDE.md updated this PR; the legacy trio (README /
IMPLEMENTATION_SUMMARY / REAL_WORLD_SCENARIO) should be rewritten or retired (F10).
4. **MCP integration is bimodal (structural, now bridged).** Concrete in 4 skills
(jira-expert 14 refs, confluence-expert 11, atlassian-templates 11, atlassian-admin 4
read-only-correct); zero in the 2 analytics skills. The bridge closes the data path;
the two SKILL.mds should still name it (one line each, F3).
5. **Two contributed skills violate the Path-B contract (open).** meeting-analyzer: zero
scripts/references/assets — its own spec (speaking-time %, filler-word counts) is
deterministic computation the repo mandates be scripted. team-communications: zero
scripts, 4 references totaling 155 lines.
6. **`/sprint-plan` counts against product-team but lives half in this domain** — the
sprint-planning integration pattern in CLAUDE.md calls product-team's
user_story_generator; fine, but the CLAUDE.md example used the old positional CLI
(still works — verified backward-compatible after this PR's argparse fix).
## Verification criteria (executable)
- **pm-skills (orchestrator):** `pm_goal_router.py --sample` exits 0 routing to
`scrum-master`; `--text "audit our jira permissions"` exits 2 (single signal → ask);
`--text "hello world"` exits 3. `jira_snapshot_bridge.py --input
assets/sample_jira_snapshot.json --to flow --forecast 20` exits 0 and matches
`assets/expected_flow_metrics.json` (p50=9, p85=14, p95=16 days; 90.9% SLE conformance;
aging alert on PHX-112; forecast p85 = 10 weeks, sampled over zero-filled observed
weeks); `--to sprint` output runs
`velocity_analyzer.py` to exit 0 (avg 11.8 pts over 4 sprints); a 2-sprint snapshot
exits 5. `delivery_loop_gate.py --sample` exits 0; sample plan passes `--mode plan`
(exit 0) and is refused by `--mode close` (exit 4, T2 in_progress).
- **scrum-master:** existing fixture contract holds — velocity_analyzer on
`assets/sample_sprint_data.json` reports avg 20.2 pts on 6 sprints.
- **atlassian-admin:** each VERIFY step names a concrete check (e.g. `GET
/rest/api/3/user?accountId=... returns "active": false`) — keep as the domain's AR4
exemplar.
- **Manifest truth:** `harness_manifest_builder.py --domain project-management
--no-timestamp` produces a diff-clean `project-management.json` with `pm-skills`
scoring all five `agentic_signals` true and 3 wired, sample-supporting tools.

76
audit/pm-product-agentic-2026-07/research-digest.md Normal file
View file

@ -0,0 +1,76 @@
# Research digest — the 2024–2026 canon behind this audit
Web-verified 2026-07-03. Full citations inline; this digest is the source layer for
[improvement-fields.md](improvement-fields.md) and the six new reference docs shipped
into the two orchestrators.
## Product management: where the canon moved
1. **Discovery became a weekly operating rhythm.** Torres (*Continuous Discovery
Habits*; producttalk.org/opportunity-solution-trees) reframed discovery as weekly
customer touchpoints anchored to one outcome, with the OST as the structural artifact
and assumption tests (Bland, *Testing Business Ideas*) as the unit of progress.
2. **The org-level frame is the product operating model.** Cagan's *Transformed* (SVPG,
2024): empowered teams, outcomes over output, innovation over predictability — 20
first principles (svpg.com/the-product-operating-model-an-introduction).
3. **Evals are the new PRD for AI features** — the consensus 2025 AI-PM competency:
golden set + rubric + guardrail SLOs before building (Lenny's Newsletter "Beyond vibe
checks"; Braintrust "Evals for PMs"; Aakash Gupta "AI Evals"); model cards for the
buyer-facing half (Mitchell et al., arxiv.org/abs/1810.03993).
4. **Metrics spine: North Star + input tree** (Amplitude, *The North Star Playbook*),
with PLG benchmark bands for verdicts (ProductLed; OpenView: activation median ~17%,
best-in-class 33–50%+; free→paid median ~9%, PQL-driven 25–30%).
5. **Prioritization is a bracket, not a framework**: RICE (steady state) + WSJF/cost of
delay (Reinertsen; SAFe WSJF + Yip's false-precision critique) + ODI opportunity
scoring (Ulwick). Sensitivity analysis counters the documented WSJF failure mode.
6. **Analytics practice is taxonomy-first** (PostHog product-analytics best practices):
naming discipline and tracking-plan review before any metric above it.
## Project management / delivery: where the canon moved
1. **Flow metrics are mandatory, not optional.** The Kanban Guide (May 2025,
kanbanguides.org) mandates exactly four measures — WIP, throughput, cycle time, work
item age — plus an SLE; age is the leading indicator.
2. **Forecasting went probabilistic.** Vacanti (*Actionable Agile Metrics*; *When Will
It Be Done?*; scrum.org Monte Carlo guidance): sample historical throughput, answer
with p50/70/85/95 ranges, never a date; refuse thin history.
3. **DORA 2025** (dora.dev/dora-report-2025) replaced elite/high/medium/low with seven
team archetypes over eight measures; core finding: AI **amplifies** existing org
strengths/dysfunctions (individual output up ~98% more merged PRs, org delivery flat
without enabling capabilities). SPACE (Forsgren/Storey, ACM Queue) remains the
multi-dimension corrective; EBM (scrum.org) the value-measurement frame.
4. **Risk practice:** Klein's pre-mortem (HBR 2007, ~30% better risk identification);
RAID hygiene as a linting problem; derived health vs self-reported RAG to catch
watermelon projects.
5. **Async-first delivery:** GitLab handbook (handbook.gitlab.com, asynchronous work) —
written 3-question standups 3–5 min vs 15–30 sync; ~37% meeting-hour reduction. Moghe,
*The Async-First Playbook* (2023).
6. **The vendors shipped agentic PM.** Atlassian Rovo GA'd agents in Jira (assignable,
@mentionable, "every action logged and auditable", Teamwork Graph 150B+ connections,
MCP access — atlassian.com/software/rovo; Team '26 coverage, SiliconANGLE 2026-05-06).
Linear shipped the accountability pattern: agent as contributor, **human stays
primary assignee** (linear.app/agents; changelog 2026-03-24).
## Agentic harness design principles (applied in this PR)
1. **Workflows first, agents when needed** — Anthropic, "Building Effective Agents"
(anthropic.com/research/building-effective-agents): prompt chaining, routing,
parallelization, orchestrator-workers, evaluator-optimizer; the last "when there are
clear evaluation criteria and iterative refinement provides measurable value."
→ The routers are workflows; the loops engage only for goals with fresh feedback.
2. **Definition-of-done must be machine-checkable; never trust self-report** — the
plan→act→verify(deterministic)→reflect shape. → G3/G4 in `delivery_loop_gate.py`;
OST linter exit codes; agent-harness's evidence rule.
3. **Budgets and stop conditions are first-class** — max iterations, attempt caps,
escalation on confidence loss; otherwise reflection is infinite retry. → 3/12 caps,
G6, terminal-state taxonomy (loop-library: success, clean no-op, blocked,
approval-required, exhausted, stagnated).
4. **Human accountability stays attached to delegated work** (Linear; Rovo audit
discipline). → G1/G2; no un-reviewed Jira transitions; admin actions are
approval-required states.
5. **Context via structured interfaces, not prompt-stuffing** (Teamwork Graph / MCP;
Anthropic's ACI emphasis). → snapshot-file pattern: every loop iteration is
executable by a fresh session from files.
6. **Evaluator-optimizer pairs with PM-owned evals** — the golden set + rubric IS the
evaluator's criteria; the loop may never edit the gate it is judged by (this repo's
autoresearch locked-evaluator invariant, generalized).

12
engineering/agent-harness/skills/agent-harness/assets/harnesses/business-operations.json
View file

@ -16,7 +16,7 @@
{
"name": "business-operations-skills",
"path": "business-operations/skills/business-operations-skills",
"description": "Use when running, diagnosing, or designing internal business operations \u2014 process documentation, vendor SLAs, capacity planning, internal comms, SOP/runbook authoring, procurement spend. Triggers on \"BizOps review\", \"where's the bottleneck\", \"vendor health\", \"internal SOP\", \"all-hands deck\", \"spend categorization\", \"capacity for Q3\", \"process mapping\". Forks context to route to one of six BizOps sub-skills (process-mapper, vendor-management, capacity-planner, internal-comms, knowledge-ops, procurement-optimizer) and returns a digest. Distinct from business-growth (external sales motion) and c-",
"description": "Use when running, diagnosing, or designing internal business operations \u2014 process documentation, vendor SLAs, capacity planning, internal comms, SOP/runbook authoring, procurement spend. Triggers on \"BizOps review\", \"where's the bottleneck\", \"vendor health\", \"internal SOP\", \"all-hands deck\", \"spend categorization\", \"capacity for Q3\", \"process mapping\". Forks context to route to one of six BizOps sub-skills (process-mapper, vendor-management, capacity-planner, internal-comms, knowledge-ops, procurement-optimizer) and returns a digest. Distinct from business-growth (external sales motion) and \u2026",
"tools": [],
"agentic_signals": {
"goal_intake": true,
@ -30,7 +30,7 @@
{
"name": "capacity-planner",
"path": "business-operations/skills/capacity-planner",
"description": "Use when an ops leader (Director of CX, Head of Support, VP Ops, Head of BizOps, Head of IT ops, Head of Finance ops) is sizing ops capacity, building a headcount plan, modeling utilization risk, planning Q3 capacity or annual support capacity, or designing CS coverage \u2014 and needs Erlang-C queueing math, P90 demand sizing, shrinkage-adjusted FTE, manager-trigger thresholds, and a quarterly hiring sequence with ramp + attrition. Apply when sustained team utilization is above 80% or when the team is growing >50% in 12 months. Run before committing the headcount budget. This is NOT engineering ca",
"description": "Use when an ops leader (Director of CX, Head of Support, VP Ops, Head of BizOps, Head of IT ops, Head of Finance ops) is sizing ops capacity, building a headcount plan, modeling utilization risk, planning Q3 capacity or annual support capacity, or designing CS coverage \u2014 and needs Erlang-C queueing math, P90 demand sizing, shrinkage-adjusted FTE, manager-trigger thresholds, and a quarterly hiring sequence with ramp + attrition. Apply when sustained team utilization is above 80% or when the team is growing >50% in 12 months. Run before committing the headcount budget. This is NOT engineering \u2026",
"tools": [
{
"script": "business-operations/skills/capacity-planner/scripts/capacity_modeler.py",
@ -100,7 +100,7 @@
{
"name": "internal-comms",
"path": "business-operations/skills/internal-comms",
"description": "Use when a Head of People Ops, BizOps lead, or Internal Communications owner needs to draft and sequence an internal-only change-management communication \u2014 a re-org announcement, a tool rollout, a policy change, a leadership transition, a layoff, an acquisition close, or an internal product launch \u2014 and the audience is employees (not customers). Pairs Prosci ADKAR and Kotter's 8-step change model with deterministic stdlib-only Python tools to produce a sequenced touchpoint calendar, a Kotter-compliant primary announcement, an audience-segmented FAQ, and manager cascade talking points; industry",
"description": "Use when a Head of People Ops, BizOps lead, or Internal Communications owner needs to draft and sequence an internal-only change-management communication \u2014 a re-org announcement, a tool rollout, a policy change, a leadership transition, a layoff, an acquisition close, or an internal product launch \u2014 and the audience is employees (not customers). Pairs Prosci ADKAR and Kotter's 8-step change model with deterministic stdlib-only Python tools to produce a sequenced touchpoint calendar, a Kotter-compliant primary announcement, an audience-segmented FAQ, and manager cascade talking points \u2026",
"tools": [
{
"script": "business-operations/skills/internal-comms/scripts/change_announcement_builder.py",
@ -170,7 +170,7 @@
{
"name": "knowledge-ops",
"path": "business-operations/skills/knowledge-ops",
"description": "Use when a Head of Ops, Knowledge Manager, or TPM-Internal needs to author, validate, or clean up company SOPs and internal runbooks (procurement intake, vendor offboarding, incident-comms cascade, employee onboarding) \u2014 including 5W2H completeness checks (Who-What-When-Where-Why-How-HowMuch), cross-link and orphan-page validation across a sprawling Notion/Confluence/Obsidian wiki, KB ingestion + hygiene reporting, and runbook step verification (named owner, expected duration, observable success signal, rollback path, escalation contact). Pairs Ishikawa's 5W2H method, Gawande's *The Checklist ",
"description": "Use when a Head of Ops, Knowledge Manager, or TPM-Internal needs to author, validate, or clean up company SOPs and internal runbooks (procurement intake, vendor offboarding, incident-comms cascade, employee onboarding) \u2014 including 5W2H completeness checks (Who-What-When-Where-Why-How-HowMuch), cross-link and orphan-page validation across a sprawling Notion/Confluence/Obsidian wiki, KB ingestion + hygiene reporting, and runbook step verification (named owner, expected duration, observable success signal, rollback path, escalation contact). Pairs Ishikawa's 5W2H method, Gawande's *The \u2026",
"tools": [
{
"script": "business-operations/skills/knowledge-ops/scripts/kb_ingester.py",
@ -240,7 +240,7 @@
{
"name": "process-mapper",
"path": "business-operations/skills/process-mapper",
"description": "Use when a BizOps lead, COO, or process-improvement owner needs to document an end-to-end business process (procurement, employee onboarding, incident handoff, customer-onboarding, claims adjudication) in BPMN-style notation, measure cycle times by stage, surface where work spends most of its time waiting vs. being worked, and quantify the gap between processing time and total elapsed time. Pairs Lean / Six Sigma / Theory-of-Constraints canon with deterministic stdlib-only Python tools to produce a process map, a ranked bottleneck list (with severity + root-cause hypothesis), and a cycle-time ",
"description": "Use when a BizOps lead, COO, or process-improvement owner needs to document an end-to-end business process (procurement, employee onboarding, incident handoff, customer-onboarding, claims adjudication) in BPMN-style notation, measure cycle times by stage, surface where work spends most of its time waiting vs. being worked, and quantify the gap between processing time and total elapsed time. Pairs Lean / Six Sigma / Theory-of-Constraints canon with deterministic stdlib-only Python tools to produce a process map, a ranked bottleneck list (with severity + root-cause hypothesis), and a \u2026",
"tools": [
{
"script": "business-operations/skills/process-mapper/scripts/bottleneck_detector.py",
@ -310,7 +310,7 @@
{
"name": "procurement-optimizer",
"path": "business-operations/skills/procurement-optimizer",
"description": "Use when running an annual SaaS audit, doing category-level spend review, or rationalizing the supplier base \u2014 when the user needs a spend audit, spend categorization (UNSPSC-aligned with Pareto breakdown and industry profiles), purchasing-cycle analysis (bottleneck categories per Goldratt's Theory of Constraints), or risk-balanced supplier consolidation that refuses single-source recommendations for tier-1 categories without a documented break-glass plan. Triggers on \"spend audit\", \"SaaS audit\", \"spend categorization\", \"supplier rationalization\", \"supplier consolidation\", \"category strategy\",",
"description": "Use when running an annual SaaS audit, doing category-level spend review, or rationalizing the supplier base \u2014 when the user needs a spend audit, spend categorization (UNSPSC-aligned with Pareto breakdown and industry profiles), purchasing-cycle analysis (bottleneck categories per Goldratt's Theory of Constraints), or risk-balanced supplier consolidation that refuses single-source recommendations for tier-1 categories without a documented break-glass plan. Triggers on \"spend audit\", \"SaaS audit\", \"spend categorization\", \"supplier rationalization\", \"supplier consolidation\", \"category \u2026",
"tools": [
{
"script": "business-operations/skills/procurement-optimizer/scripts/purchasing_cycle_analyzer.py",

16
engineering/agent-harness/skills/agent-harness/assets/harnesses/c-level-advisor.json
View file

@ -16,7 +16,7 @@
{
"name": "arquiteto-de-empresa",
"path": "c-level-advisor/arquiteto-de-empresa/skills/arquiteto-de-empresa",
"description": "Arquiteto de Empresa: constr\u00f3i um neg\u00f3cio do zero como bundle OKF (Open Knowledge Format) \u2014 uma \u00e1rvore de arquivos .md version\u00e1veis com frontmatter type, links formando grafo, e index.md/log.md reservados, leg\u00edvel por humanos e por agentes. Conduz o fundador por uma entrevista de 12 fases (funda\u00e7\u00e3o, estrat\u00e9gia, mercado, financeiro, comercial, marketing, produto, opera\u00e7\u00f5es, tech, pessoas, jur\u00eddico, governan\u00e7a), uma fase por vez, poucas perguntas por bloco, e gera os conceitos como markdown conformante. Acione quando o usu\u00e1rio quiser criar, estruturar ou documentar uma empresa inteira em pastas ",
"description": "Arquiteto de Empresa: constr\u00f3i um neg\u00f3cio do zero como bundle OKF (Open Knowledge Format) \u2014 uma \u00e1rvore de arquivos .md version\u00e1veis com frontmatter type, links formando grafo, e index.md/log.md reservados, leg\u00edvel por humanos e por agentes. Conduz o fundador por uma entrevista de 12 fases (funda\u00e7\u00e3o, estrat\u00e9gia, mercado, financeiro, comercial, marketing, produto, opera\u00e7\u00f5es, tech, pessoas, jur\u00eddico, governan\u00e7a), uma fase por vez, poucas perguntas por bloco, e gera os conceitos como markdown conformante. Acione quando o usu\u00e1rio quiser criar, estruturar ou documentar uma empresa inteira em \u2026",
"tools": [
{
"script": "c-level-advisor/arquiteto-de-empresa/skills/arquiteto-de-empresa/scripts/index_generator.py",
@ -394,7 +394,7 @@
{
"name": "chief-ai-officer-advisor",
"path": "c-level-advisor/chief-ai-officer-advisor/skills/chief-ai-officer-advisor",
"description": "Chief AI Officer advisory for startups: model build-vs-buy decisions (API vs fine-tune vs in-house), AI risk classification under EU AI Act + US state patchwork, AI cost economics (API-to-self-hosted breakeven), and AI team org evolution. Use when deciding whether to call an API or fine-tune, classifying AI use cases for regulatory risk, calculating when self-hosting pays off, sequencing AI hires, or when user mentions CAIO, AI strategy, model selection, foundation model, fine-tuning, EU AI Act, NIST AI RMF, AI governance, model risk, or AI economics. Strategic only \u2014 does not duplicate engine",
"description": "Chief AI Officer advisory for startups: model build-vs-buy decisions (API vs fine-tune vs in-house), AI risk classification under EU AI Act + US state patchwork, AI cost economics (API-to-self-hosted breakeven), and AI team org evolution. Use when deciding whether to call an API or fine-tune, classifying AI use cases for regulatory risk, calculating when self-hosting pays off, sequencing AI hires, or when user mentions CAIO, AI strategy, model selection, foundation model, fine-tuning, EU AI Act, NIST AI RMF, AI governance, model risk, or AI economics. Strategic only \u2014 does not duplicate \u2026",
"tools": [
{
"script": "c-level-advisor/chief-ai-officer-advisor/skills/chief-ai-officer-advisor/scripts/ai_cost_economics.py",
@ -506,7 +506,7 @@
{
"name": "chief-data-officer-advisor",
"path": "c-level-advisor/chief-data-officer-advisor/skills/chief-data-officer-advisor",
"description": "Chief Data Officer advisory for startups: AI training data rights and consent provenance, data product strategy (warehouse vs lakehouse vs mesh, build-vs-buy), B2B customer-data-as-asset valuation and M&A readiness, data team org evolution. Use when deciding whether to train models on customer data, choosing data architecture, valuing data for fundraising or M&A, sequencing data hires, or when user mentions CDO, chief data officer, data strategy, data mesh, lakehouse, training data, data product, data monetization, or customer data asset. NOT a tactical data engineering skill \u2014 strategic decis",
"description": "Chief Data Officer advisory for startups: AI training data rights and consent provenance, data product strategy (warehouse vs lakehouse vs mesh, build-vs-buy), B2B customer-data-as-asset valuation and M&A readiness, data team org evolution. Use when deciding whether to train models on customer data, choosing data architecture, valuing data for fundraising or M&A, sequencing data hires, or when user mentions CDO, chief data officer, data strategy, data mesh, lakehouse, training data, data product, data monetization, or customer data asset. NOT a tactical data engineering skill \u2014 strategic \u2026",
"tools": [
{
"script": "c-level-advisor/chief-data-officer-advisor/skills/chief-data-officer-advisor/scripts/ai_training_data_audit.py",
@ -744,7 +744,7 @@
{
"name": "arquiteto-de-empresa",
"path": "c-level-advisor/skills/arquiteto-de-empresa",
"description": "Arquiteto de Empresa: constr\u00f3i um neg\u00f3cio do zero como bundle OKF (Open Knowledge Format) \u2014 uma \u00e1rvore de arquivos .md version\u00e1veis com frontmatter type, links formando grafo, e index.md/log.md reservados, leg\u00edvel por humanos e por agentes. Conduz o fundador por uma entrevista de 12 fases (funda\u00e7\u00e3o, estrat\u00e9gia, mercado, financeiro, comercial, marketing, produto, opera\u00e7\u00f5es, tech, pessoas, jur\u00eddico, governan\u00e7a), uma fase por vez, poucas perguntas por bloco, e gera os conceitos como markdown conformante. Acione quando o usu\u00e1rio quiser criar, estruturar ou documentar uma empresa inteira em pastas ",
"description": "Arquiteto de Empresa: constr\u00f3i um neg\u00f3cio do zero como bundle OKF (Open Knowledge Format) \u2014 uma \u00e1rvore de arquivos .md version\u00e1veis com frontmatter type, links formando grafo, e index.md/log.md reservados, leg\u00edvel por humanos e por agentes. Conduz o fundador por uma entrevista de 12 fases (funda\u00e7\u00e3o, estrat\u00e9gia, mercado, financeiro, comercial, marketing, produto, opera\u00e7\u00f5es, tech, pessoas, jur\u00eddico, governan\u00e7a), uma fase por vez, poucas perguntas por bloco, e gera os conceitos como markdown conformante. Acione quando o usu\u00e1rio quiser criar, estruturar ou documentar uma empresa inteira em \u2026",
"tools": [
{
"script": "c-level-advisor/skills/arquiteto-de-empresa/scripts/index_generator.py",
@ -974,7 +974,7 @@
{
"name": "chief-ai-officer-advisor",
"path": "c-level-advisor/skills/chief-ai-officer-advisor",
"description": "Chief AI Officer advisory for startups: model build-vs-buy decisions (API vs fine-tune vs in-house), AI risk classification under EU AI Act + US state patchwork, AI cost economics (API-to-self-hosted breakeven), and AI team org evolution. Use when deciding whether to call an API or fine-tune, classifying AI use cases for regulatory risk, calculating when self-hosting pays off, sequencing AI hires, or when user mentions CAIO, AI strategy, model selection, foundation model, fine-tuning, EU AI Act, NIST AI RMF, AI governance, model risk, or AI economics. Strategic only \u2014 does not duplicate engine",
"description": "Chief AI Officer advisory for startups: model build-vs-buy decisions (API vs fine-tune vs in-house), AI risk classification under EU AI Act + US state patchwork, AI cost economics (API-to-self-hosted breakeven), and AI team org evolution. Use when deciding whether to call an API or fine-tune, classifying AI use cases for regulatory risk, calculating when self-hosting pays off, sequencing AI hires, or when user mentions CAIO, AI strategy, model selection, foundation model, fine-tuning, EU AI Act, NIST AI RMF, AI governance, model risk, or AI economics. Strategic only \u2014 does not duplicate \u2026",
"tools": [
{
"script": "c-level-advisor/skills/chief-ai-officer-advisor/scripts/ai_cost_economics.py",
@ -1086,7 +1086,7 @@
{
"name": "chief-data-officer-advisor",
"path": "c-level-advisor/skills/chief-data-officer-advisor",
"description": "Chief Data Officer advisory for startups: AI training data rights and consent provenance, data product strategy (warehouse vs lakehouse vs mesh, build-vs-buy), B2B customer-data-as-asset valuation and M&A readiness, data team org evolution. Use when deciding whether to train models on customer data, choosing data architecture, valuing data for fundraising or M&A, sequencing data hires, or when user mentions CDO, chief data officer, data strategy, data mesh, lakehouse, training data, data product, data monetization, or customer data asset. NOT a tactical data engineering skill \u2014 strategic decis",
"description": "Chief Data Officer advisory for startups: AI training data rights and consent provenance, data product strategy (warehouse vs lakehouse vs mesh, build-vs-buy), B2B customer-data-as-asset valuation and M&A readiness, data team org evolution. Use when deciding whether to train models on customer data, choosing data architecture, valuing data for fundraising or M&A, sequencing data hires, or when user mentions CDO, chief data officer, data strategy, data mesh, lakehouse, training data, data product, data monetization, or customer data asset. NOT a tactical data engineering skill \u2014 strategic \u2026",
"tools": [
{
"script": "c-level-advisor/skills/chief-data-officer-advisor/scripts/ai_training_data_audit.py",
@ -1780,7 +1780,7 @@
{
"name": "vpe-advisor",
"path": "c-level-advisor/skills/vpe-advisor",
"description": "VP of Engineering advisory for startups: delivery throughput (DORA 4 metrics + bottleneck identification), engineering hiring funnel (sourcing \u2192 screen \u2192 onsite \u2192 offer conversion + time-to-fill + pipeline gap), engineering team structure (squad/tribe/chapter design + tech-lead manager-trigger thresholds), and production discipline (on-call, deployment cadence, postmortem culture). Use when sprint velocity is dropping, eng hiring is broken, team structure is unclear, or deciding when to add a tech-lead manager. NOT a CTO skill (which owns architecture) \u2014 VPE owns delivery operations and how th",
"description": "VP of Engineering advisory for startups: delivery throughput (DORA 4 metrics + bottleneck identification), engineering hiring funnel (sourcing \u2192 screen \u2192 onsite \u2192 offer conversion + time-to-fill + pipeline gap), engineering team structure (squad/tribe/chapter design + tech-lead manager-trigger thresholds), and production discipline (on-call, deployment cadence, postmortem culture). Use when sprint velocity is dropping, eng hiring is broken, team structure is unclear, or deciding when to add a tech-lead manager. NOT a CTO skill (which owns architecture) \u2014 VPE owns delivery operations and how \u2026",
"tools": [
{
"script": "c-level-advisor/skills/vpe-advisor/scripts/delivery_throughput_analyzer.py",
@ -1836,7 +1836,7 @@
{
"name": "vpe-advisor",
"path": "c-level-advisor/vpe-advisor/skills/vpe-advisor",
"description": "VP of Engineering advisory for startups: delivery throughput (DORA 4 metrics + bottleneck identification), engineering hiring funnel (sourcing \u2192 screen \u2192 onsite \u2192 offer conversion + time-to-fill + pipeline gap), engineering team structure (squad/tribe/chapter design + tech-lead manager-trigger thresholds), and production discipline (on-call, deployment cadence, postmortem culture). Use when sprint velocity is dropping, eng hiring is broken, team structure is unclear, or deciding when to add a tech-lead manager. NOT a CTO skill (which owns architecture) \u2014 VPE owns delivery operations and how th",
"description": "VP of Engineering advisory for startups: delivery throughput (DORA 4 metrics + bottleneck identification), engineering hiring funnel (sourcing \u2192 screen \u2192 onsite \u2192 offer conversion + time-to-fill + pipeline gap), engineering team structure (squad/tribe/chapter design + tech-lead manager-trigger thresholds), and production discipline (on-call, deployment cadence, postmortem culture). Use when sprint velocity is dropping, eng hiring is broken, team structure is unclear, or deciding when to add a tech-lead manager. NOT a CTO skill (which owns architecture) \u2014 VPE owns delivery operations and how \u2026",
"tools": [
{
"script": "c-level-advisor/vpe-advisor/skills/vpe-advisor/scripts/delivery_throughput_analyzer.py",

14
engineering/agent-harness/skills/agent-harness/assets/harnesses/commercial.json
View file

@ -16,7 +16,7 @@
{
"name": "channel-economics",
"path": "commercial/skills/channel-economics",
"description": "Use when reviewing or rebalancing direct vs. partner-led channel economics \u2014 computing fully-loaded cost-to-serve per channel, channel ROI with cash / LTV / marginal lenses, and optimal channel mix subject to constraints. For Head of Commercial, RevOps, and VP Sales doing quarterly channel review when pipeline is mixed (e.g., 60% direct + 40% partner-led) and nobody actually knows which channel makes money after CAC, support load, partner discount, deal-velocity differences, retention differential, and overhead allocation are all loaded in. Outputs cost to serve, channel ROI verdicts (DOUBLE-D",
"description": "Use when reviewing or rebalancing direct vs. partner-led channel economics \u2014 computing fully-loaded cost-to-serve per channel, channel ROI with cash / LTV / marginal lenses, and optimal channel mix subject to constraints. For Head of Commercial, RevOps, and VP Sales doing quarterly channel review when pipeline is mixed (e.g., 60% direct + 40% partner-led) and nobody actually knows which channel makes money after CAC, support load, partner discount, deal-velocity differences, retention differential, and overhead allocation are all loaded in. Outputs cost to serve, channel ROI verdicts \u2026",
"tools": [
{
"script": "commercial/skills/channel-economics/scripts/channel_mix_optimizer.py",
@ -86,7 +86,7 @@
{
"name": "commercial-forecaster",
"path": "commercial/skills/commercial-forecaster",
"description": "Use when building a quarterly bookings forecast, ARR projection, pipeline forecast, NRR projection, or commit/best-case/pipe-only board number \u2014 especially when the CRO needs to walk the board through funnel math + cohort ARR + per-stage conversion assumptions without the theatre of a single undefended number. Decomposes pipeline into commit, best-case, and pipe-only tiers; projects cohort-level NRR/GRR to surface leaky cohorts before they show up in the consolidated number; scores per-stage funnel confidence so soft-floor stages get treated differently from high-confidence ones. Every output ",
"description": "Use when building a quarterly bookings forecast, ARR projection, pipeline forecast, NRR projection, or commit/best-case/pipe-only board number \u2014 especially when the CRO needs to walk the board through funnel math + cohort ARR + per-stage conversion assumptions without the theatre of a single undefended number. Decomposes pipeline into commit, best-case, and pipe-only tiers; projects cohort-level NRR/GRR to surface leaky cohorts before they show up in the consolidated number; scores per-stage funnel confidence so soft-floor stages get treated differently from high-confidence ones. Every \u2026",
"tools": [
{
"script": "commercial/skills/commercial-forecaster/scripts/bookings_forecaster.py",
@ -156,7 +156,7 @@
{
"name": "commercial-policy",
"path": "commercial/skills/commercial-policy",
"description": "Use when designing or revising a company's commercial policy \u2014 the rules of engagement governing discounts off list price, approver thresholds, exception flows, and the deal framework that Deal Desk and AEs operate under. Covers discount matrix design (ARR band x term length x payment terms x strategic value), commercial policy design, exception policy, discount governance, approval thresholds, deal framework structure, and policy linting (contradictions, gaps, cliff edges, gaming surfaces). For Head of Commercial, Head of Deal Desk, VP Sales, or RevOps at the policy-design moment \u2014 NOT per-de",
"description": "Use when designing or revising a company's commercial policy \u2014 the rules of engagement governing discounts off list price, approver thresholds, exception flows, and the deal framework that Deal Desk and AEs operate under. Covers discount matrix design (ARR band x term length x payment terms x strategic value), commercial policy design, exception policy, discount governance, approval thresholds, deal framework structure, and policy linting (contradictions, gaps, cliff edges, gaming surfaces). For Head of Commercial, Head of Deal Desk, VP Sales, or RevOps at the policy-design moment \u2014 NOT \u2026",
"tools": [
{
"script": "commercial/skills/commercial-policy/scripts/discount_matrix_builder.py",
@ -226,7 +226,7 @@
{
"name": "commercial-skills",
"path": "commercial/skills/commercial-skills",
"description": "Use when reviewing, approving, or designing commercial motion \u2014 pricing models, deal review, discount approval, partnership economics, channel mix, commercial policy, RFP/RFI response, bookings forecast. Triggers on \"review this deal\", \"should we discount\", \"pricing model\", \"partner economics\", \"RFP response\", \"bookings forecast\", \"channel mix\". Forks context to route to one of seven Commercial sub-skills (pricing-strategist, deal-desk, partnerships-architect, channel-economics, commercial-policy, rfp-responder, commercial-forecaster) and returns a digest. Distinct from business-growth (sales ",
"description": "Use when reviewing, approving, or designing commercial motion \u2014 pricing models, deal review, discount approval, partnership economics, channel mix, commercial policy, RFP/RFI response, bookings forecast. Triggers on \"review this deal\", \"should we discount\", \"pricing model\", \"partner economics\", \"RFP response\", \"bookings forecast\", \"channel mix\". Forks context to route to one of seven Commercial sub-skills (pricing-strategist, deal-desk, partnerships-architect, channel-economics, commercial-policy, rfp-responder, commercial-forecaster) and returns a digest. Distinct from business-growth \u2026",
"tools": [],
"agentic_signals": {
"goal_intake": true,
@ -240,7 +240,7 @@
{
"name": "deal-desk",
"path": "commercial/skills/deal-desk",
"description": "Use when reviewing a specific inbound deal before close \u2014 when sales has asked for a discount that exceeds AE authority, when the customer has redlined the MSA, when per-deal economics (margin after discount, multi-year payment shape, indemnity exposure) need to be quantified, or when discount approval needs to be routed to a named human approver (Sales Director, VP Sales, CFO, CRO, General Counsel). Covers deal review, discount approval routing, per-deal margin scoring, deal exception handling, MSA redline triage, contract landmine detection (uncapped indemnity, MFN, perpetual license-back, m",
"description": "Use when reviewing a specific inbound deal before close \u2014 when sales has asked for a discount that exceeds AE authority, when the customer has redlined the MSA, when per-deal economics (margin after discount, multi-year payment shape, indemnity exposure) need to be quantified, or when discount approval needs to be routed to a named human approver (Sales Director, VP Sales, CFO, CRO, General Counsel). Covers deal review, discount approval routing, per-deal margin scoring, deal exception handling, MSA redline triage, contract landmine detection (uncapped indemnity, MFN, perpetual \u2026",
"tools": [
{
"script": "commercial/skills/deal-desk/scripts/deal_scorer.py",
@ -310,7 +310,7 @@
{
"name": "partnerships-architect",
"path": "commercial/skills/partnerships-architect",
"description": "Use when a startup is approached by a prospective partner and someone has to decide should we sign this partner, at what partner tier (referral / reseller / OEM / SI-consulting / strategic alliance), with what joint GTM commitment, and at what revshare. Classifies partner tier from independent-demand evidence vs. preferential-terms hunting, designs a 90-day joint GTM plan, models revshare against direct-sale margin, and surfaces kill criteria for unwinding under-performing partnerships. For Head of Partnerships, Head of BD, and Founder-CEOs doing reseller agreement, OEM deal, or strategic alli",
"description": "Use when a startup is approached by a prospective partner and someone has to decide should we sign this partner, at what partner tier (referral / reseller / OEM / SI-consulting / strategic alliance), with what joint GTM commitment, and at what revshare. Classifies partner tier from independent-demand evidence vs. preferential-terms hunting, designs a 90-day joint GTM plan, models revshare against direct-sale margin, and surfaces kill criteria for unwinding under-performing partnerships. For Head of Partnerships, Head of BD, and Founder-CEOs doing reseller agreement, OEM deal, or strategic \u2026",
"tools": [
{
"script": "commercial/skills/partnerships-architect/scripts/joint_gtm_planner.py",
@ -450,7 +450,7 @@
{
"name": "rfp-responder",
"path": "commercial/skills/rfp-responder",
"description": "Use when an RFP, RFI, RFQ, security questionnaire, vendor questionnaire, or proposal request arrives and the team needs a structured response \u2014 parsing multi-section buyer-dictated requirements (MANDATORY vs WEIGHTED vs NICE-TO-HAVE), building a Shipley-method proof-point matrix mapping each requirement to a verifiable proof point, articulating 3-5 win-themes that ladder up across requirements, and producing a Shipley-derived winrate estimate that informs a bid / no-bid / partner-bid recommendation. For Bid Managers, Proposal Leads, Directors of Sales, and Sales Engineers at the response-strat",
"description": "Use when an RFP, RFI, RFQ, security questionnaire, vendor questionnaire, or proposal request arrives and the team needs a structured response \u2014 parsing multi-section buyer-dictated requirements (MANDATORY vs WEIGHTED vs NICE-TO-HAVE), building a Shipley-method proof-point matrix mapping each requirement to a verifiable proof point, articulating 3-5 win-themes that ladder up across requirements, and producing a Shipley-derived winrate estimate that informs a bid / no-bid / partner-bid recommendation. For Bid Managers, Proposal Leads, Directors of Sales, and Sales Engineers at the \u2026",
"tools": [
{
"script": "commercial/skills/rfp-responder/scripts/response_drafter.py",

2
engineering/agent-harness/skills/agent-harness/assets/harnesses/compliance-os.json
View file

@ -44,7 +44,7 @@
{
"name": "compliance-os",
"path": "compliance-os/skills/compliance-os",
"description": "Compliance OS \u2014 meta-orchestrator that lets compliance teams CONFIGURE which frameworks apply, COMPUTE cross-framework control overlap, SIMULATE internal audits, and CONSOLIDATE evidence across multiple frameworks. Four decisions: (1) Given a company profile, which of the 12 supported frameworks apply (ISO 27001/13485/42001/14971, EU AI Act, MDR 745, GDPR, SOC 2, FDA QSR, NIST CSF 2.0, NIS2, HIPAA)? (2) Across selected frameworks, which controls overlap and how much evidence reuses? (3) For a given framework + scope, what does a realistic mock audit produce \u2014 drawing from the 205-scenario libr",
"description": "Compliance OS \u2014 meta-orchestrator that lets compliance teams CONFIGURE which frameworks apply, COMPUTE cross-framework control overlap, SIMULATE internal audits, and CONSOLIDATE evidence across multiple frameworks. Four decisions: (1) Given a company profile, which of the 12 supported frameworks apply (ISO 27001/13485/42001/14971, EU AI Act, MDR 745, GDPR, SOC 2, FDA QSR, NIST CSF 2.0, NIS2, HIPAA)? (2) Across selected frameworks, which controls overlap and how much evidence reuses? (3) For a given framework + scope, what does a realistic mock audit produce \u2014 drawing from the 205-scenario \u2026",
"tools": [
{
"script": "compliance-os/skills/compliance-os/scripts/audit_simulator.py",

6
engineering/agent-harness/skills/agent-harness/assets/harnesses/engineering-team.json
View file

@ -634,7 +634,7 @@
{
"name": "epic-design",
"path": "engineering-team/skills/epic-design",
"description": "> Build immersive, cinematic 2.5D interactive websites using scroll storytelling, parallax depth, text animations, and premium scroll effects \u2014 no WebGL required. Use this skill for any web design task: landing pages, product sites, hero sections, scroll animations, parallax, sticky sections, section overlaps, floating products between sections, clip-path reveals, text that flies in from sides, words that light up on scroll, curtain drops, iris opens, card stacks, bleed typography, and any site that should feel cinematic or premium. Trigger on phrases like \"make it feel alive\", \"Apple-style an",
"description": "> Build immersive, cinematic 2.5D interactive websites using scroll storytelling, parallax depth, text animations, and premium scroll effects \u2014 no WebGL required. Use this skill for any web design task: landing pages, product sites, hero sections, scroll animations, parallax, sticky sections, section overlaps, floating products between sections, clip-path reveals, text that flies in from sides, words that light up on scroll, curtain drops, iris opens, card stacks, bleed typography, and any site that should feel cinematic or premium. Trigger on phrases like \"make it feel alive\", \"Apple-style \u2026",
"tools": [
{
"script": "engineering-team/skills/epic-design/scripts/inspect-assets.py",
@ -1220,7 +1220,7 @@
{
"name": "senior-data-scientist",
"path": "engineering-team/skills/senior-data-scientist",
"description": "World-class senior data scientist skill specialising in statistical modeling, experiment design, causal inference, and predictive analytics. Covers A/B testing (sample sizing, two-proportion z-tests, Bonferroni correction), difference-in-differences, feature engineering pipelines (Scikit-learn, XGBoost), cross-validated model evaluation (AUC-ROC, AUC-PR, SHAP), and MLflow experiment tracking \u2014 using Python (NumPy, Pandas, Scikit-learn), R, and SQL. Use when designing or analysing controlled experiments, building and evaluating classification or regression models, performing causal analysis on ",
"description": "World-class senior data scientist skill specialising in statistical modeling, experiment design, causal inference, and predictive analytics. Covers A/B testing (sample sizing, two-proportion z-tests, Bonferroni correction), difference-in-differences, feature engineering pipelines (Scikit-learn, XGBoost), cross-validated model evaluation (AUC-ROC, AUC-PR, SHAP), and MLflow experiment tracking \u2014 using Python (NumPy, Pandas, Scikit-learn), R, and SQL. Use when designing or analysing controlled experiments, building and evaluating classification or regression models, performing causal analysis \u2026",
"tools": [
{
"script": "engineering-team/skills/senior-data-scientist/scripts/experiment_designer.py",
@ -1631,7 +1631,7 @@
{
"name": "senior-secops",
"path": "engineering-team/skills/senior-secops",
"description": "Senior SecOps engineer skill for application security, vulnerability management, compliance verification, and secure development practices. Runs SAST/DAST scans, generates CVE remediation plans, checks dependency vulnerabilities, creates security policies, enforces secure coding patterns, and automates compliance checks against SOC2, PCI-DSS, HIPAA, and GDPR. Use when conducting a security review or audit, responding to a CVE or security incident, hardening infrastructure, implementing authentication or secrets management, running penetration test prep, checking OWASP Top 10 exposure, or enfor",
"description": "Senior SecOps engineer skill for application security, vulnerability management, compliance verification, and secure development practices. Runs SAST/DAST scans, generates CVE remediation plans, checks dependency vulnerabilities, creates security policies, enforces secure coding patterns, and automates compliance checks against SOC2, PCI-DSS, HIPAA, and GDPR. Use when conducting a security review or audit, responding to a CVE or security incident, hardening infrastructure, implementing authentication or secrets management, running penetration test prep, checking OWASP Top 10 exposure, or \u2026",
"tools": [
{
"script": "engineering-team/skills/senior-secops/scripts/compliance_checker.py",

14
engineering/agent-harness/skills/agent-harness/assets/harnesses/engineering.json
View file

@ -16,7 +16,7 @@
{
"name": "agent-harness",
"path": "engineering/agent-harness/skills/agent-harness",
"description": "Turn any domain folder of skills into a bounded agentic loop: compile a goal into a verifiable task plan, execute tasks with the domain's own tools, verify every task with machine-run checks, retry with caps, escalate to a human when budgets exhaust, and refuse to close until everything is verified or explicitly waived. Use when you want an agent or subagent to pick up a goal and drive it to a verified close across one of this repo's 18 domains ('run this goal through the engineering harness', 'set up an agentic loop for marketing work', 'make the finance domain self-verifying'). NOT for autho",
"description": "Turn any domain folder of skills into a bounded agentic loop: compile a goal into a verifiable task plan, execute tasks with the domain's own tools, verify every task with machine-run checks, retry with caps, escalate to a human when budgets exhaust, and refuse to close until everything is verified or explicitly waived. Use when you want an agent or subagent to pick up a goal and drive it to a verified close across one of this repo's 18 domains ('run this goal through the engineering harness', 'set up an agentic loop for marketing work', 'make the finance domain self-verifying'). NOT for \u2026",
"tools": [
{
"script": "engineering/agent-harness/skills/agent-harness/scripts/goal_compiler.py",
@ -470,7 +470,7 @@
{
"name": "chaos-engineering",
"path": "engineering/chaos-engineering/skills/chaos-engineering",
"description": "Use when planning, running, or learning from chaos engineering experiments. Triggers on \"chaos experiment\", \"fault injection\", \"gameday\", \"resilience test\", \"blast radius\", \"steady state\", \"abort criteria\", \"Chaos Toolkit\", \"Chaos Mesh\", \"Litmus\", \"Gremlin\", \"AWS FIS\", or any deliberate failure-injection question. Ships experiment designer, blast-radius calculator, and postmortem generator (all stdlib Python), 4 references on chaos principles + experiment design + attack taxonomy + tooling landscape, and a /chaos-experiment slash command. Composes with feature-flags-architect (kill switches as",
"description": "Use when planning, running, or learning from chaos engineering experiments. Triggers on \"chaos experiment\", \"fault injection\", \"gameday\", \"resilience test\", \"blast radius\", \"steady state\", \"abort criteria\", \"Chaos Toolkit\", \"Chaos Mesh\", \"Litmus\", \"Gremlin\", \"AWS FIS\", or any deliberate failure-injection question. Ships experiment designer, blast-radius calculator, and postmortem generator (all stdlib Python), 4 references on chaos principles + experiment design + attack taxonomy + tooling landscape, and a /chaos-experiment slash command. Composes with feature-flags-architect (kill switches \u2026",
"tools": [
{
"script": "engineering/chaos-engineering/skills/chaos-engineering/scripts/blast_radius_calculator.py",
@ -1146,7 +1146,7 @@
{
"name": "llm-cost-optimizer",
"path": "engineering/llm-cost-optimizer/skills/llm-cost-optimizer",
"description": "Use proactively whenever LLM API costs come up -- or should. Triggers include: 'my AI costs are too high', 'optimize token usage', 'which model should I use', 'LLM spend is out of control', 'implement prompt caching', 'we're about to launch an AI feature', 'build me an AI endpoint'. Don't wait for an explicit cost complaint -- if someone is building an AI feature, designing an LLM endpoint, or choosing between models, cost architecture belongs in the conversation. Apply immediately when any of these are true: a system prompt appears that exceeds a few hundred tokens, all requests are hitting t",
"description": "Use proactively whenever LLM API costs come up -- or should. Triggers include: 'my AI costs are too high', 'optimize token usage', 'which model should I use', 'LLM spend is out of control', 'implement prompt caching', 'we're about to launch an AI feature', 'build me an AI endpoint'. Don't wait for an explicit cost complaint -- if someone is building an AI feature, designing an LLM endpoint, or choosing between models, cost architecture belongs in the conversation. Apply immediately when any of these are true: a system prompt appears that exceeds a few hundred tokens, all requests are \u2026",
"tools": [],
"agentic_signals": {
"goal_intake": false,
@ -1294,7 +1294,7 @@
{
"name": "security-guidance",
"path": "engineering/security-guidance/skills/security-guidance",
"description": "PreToolUse security-anti-pattern hook for Claude Code. Catches 12 common security risks (command injection, XSS, SQL injection, unsafe deserialization, GitHub Actions workflow injection, eval/new Function code injection) BEFORE the Edit/Write/MultiEdit operation completes. Session-state caching prevents duplicate warnings on the same file+rule combo. Stdlib only \u2014 no dependencies. Use when you want a safety net during Claude Code sessions that touch security-sensitive code (auth, payments, user input handling, IaC). Disable with ENABLE_SECURITY_REMINDER=0 if you need to perform a verified-safe",
"description": "PreToolUse security-anti-pattern hook for Claude Code. Catches 12 common security risks (command injection, XSS, SQL injection, unsafe deserialization, GitHub Actions workflow injection, eval/new Function code injection) BEFORE the Edit/Write/MultiEdit operation completes. Session-state caching prevents duplicate warnings on the same file+rule combo. Stdlib only \u2014 no dependencies. Use when you want a safety net during Claude Code sessions that touch security-sensitive code (auth, payments, user input handling, IaC). Disable with ENABLE_SECURITY_REMINDER=0 if you need to perform a \u2026",
"tools": [],
"agentic_signals": {
"goal_intake": false,
@ -1580,7 +1580,7 @@
{
"name": "chaos-engineering",
"path": "engineering/skills/chaos-engineering",
"description": "Use when planning, running, or learning from chaos engineering experiments. Triggers on \"chaos experiment\", \"fault injection\", \"gameday\", \"resilience test\", \"blast radius\", \"steady state\", \"abort criteria\", \"Chaos Toolkit\", \"Chaos Mesh\", \"Litmus\", \"Gremlin\", \"AWS FIS\", or any deliberate failure-injection question. Ships experiment designer, blast-radius calculator, and postmortem generator (all stdlib Python), 4 references on chaos principles + experiment design + attack taxonomy + tooling landscape, and a /chaos-experiment slash command. Composes with feature-flags-architect (kill switches as",
"description": "Use when planning, running, or learning from chaos engineering experiments. Triggers on \"chaos experiment\", \"fault injection\", \"gameday\", \"resilience test\", \"blast radius\", \"steady state\", \"abort criteria\", \"Chaos Toolkit\", \"Chaos Mesh\", \"Litmus\", \"Gremlin\", \"AWS FIS\", or any deliberate failure-injection question. Ships experiment designer, blast-radius calculator, and postmortem generator (all stdlib Python), 4 references on chaos principles + experiment design + attack taxonomy + tooling landscape, and a /chaos-experiment slash command. Composes with feature-flags-architect (kill switches \u2026",
"tools": [
{
"script": "engineering/skills/chaos-engineering/scripts/blast_radius_calculator.py",
@ -2678,7 +2678,7 @@
{
"name": "slo-architect",
"path": "engineering/skills/slo-architect",
"description": "Use when defining, reviewing, or operating SLOs/SLIs/error budgets. Triggers on \"define an SLO\", \"what should our SLO be\", \"error budget\", \"burn rate\", \"SLI\", \"service level objective\", \"Google SRE workbook\", \"multi-window burn-rate alert\", or any reliability-target question. Ships SLO designer, error-budget calculator with multi-window burn-rate thresholds, and SLO reviewer that catches the common bugs (target too aggressive, window too short, conflicting SLOs, no SLI definition). 4 references on SLO principles + SLI design + error budget math + composition with feature-flags-architect/chaos-",
"description": "Use when defining, reviewing, or operating SLOs/SLIs/error budgets. Triggers on \"define an SLO\", \"what should our SLO be\", \"error budget\", \"burn rate\", \"SLI\", \"service level objective\", \"Google SRE workbook\", \"multi-window burn-rate alert\", or any reliability-target question. Ships SLO designer, error-budget calculator with multi-window burn-rate thresholds, and SLO reviewer that catches the common bugs (target too aggressive, window too short, conflicting SLOs, no SLI definition). 4 references on SLO principles + SLI design + error budget math + composition with \u2026",
"tools": [
{
"script": "engineering/skills/slo-architect/scripts/error_budget_calculator.py",
@ -2989,7 +2989,7 @@
{
"name": "slo-architect",
"path": "engineering/slo-architect/skills/slo-architect",
"description": "Use when defining, reviewing, or operating SLOs/SLIs/error budgets. Triggers on \"define an SLO\", \"what should our SLO be\", \"error budget\", \"burn rate\", \"SLI\", \"service level objective\", \"Google SRE workbook\", \"multi-window burn-rate alert\", or any reliability-target question. Ships SLO designer, error-budget calculator with multi-window burn-rate thresholds, and SLO reviewer that catches the common bugs (target too aggressive, window too short, conflicting SLOs, no SLI definition). 4 references on SLO principles + SLI design + error budget math + composition with feature-flags-architect/chaos-",
"description": "Use when defining, reviewing, or operating SLOs/SLIs/error budgets. Triggers on \"define an SLO\", \"what should our SLO be\", \"error budget\", \"burn rate\", \"SLI\", \"service level objective\", \"Google SRE workbook\", \"multi-window burn-rate alert\", or any reliability-target question. Ships SLO designer, error-budget calculator with multi-window burn-rate thresholds, and SLO reviewer that catches the common bugs (target too aggressive, window too short, conflicting SLOs, no SLI definition). 4 references on SLO principles + SLI design + error budget math + composition with \u2026",
"tools": [
{
"script": "engineering/slo-architect/skills/slo-architect/scripts/error_budget_calculator.py",

2
engineering/agent-harness/skills/agent-harness/assets/harnesses/loop-library.json
View file

@ -16,7 +16,7 @@
{
"name": "loop-library",
"path": "loop-library",
"description": "Discover, find, compare, audit, repair, adapt, and design repeatable AI-agent loops with explicit triggers, actions, verification, stopping conditions, guardrails, and handoffs. Use when a user asks to analyze a codebase for potential loops, mine coding-thread history for work done more than once, turn repeated engineering work into a loop, find or recommend a published loop, create a recurring agent workflow or automation cadence, turn an outcome into a bounded copy-ready loop, or review an existing loop for weak checks, unsafe authority, unbounded repetition, stale state, or unclear stopping",
"description": "Discover, find, compare, audit, repair, adapt, and design repeatable AI-agent loops with explicit triggers, actions, verification, stopping conditions, guardrails, and handoffs. Use when a user asks to analyze a codebase for potential loops, mine coding-thread history for work done more than once, turn repeated engineering work into a loop, find or recommend a published loop, create a recurring agent workflow or automation cadence, turn an outcome into a bounded copy-ready loop, or review an existing loop for weak checks, unsafe authority, unbounded repetition, stale state, or unclear \u2026",
"tools": [],
"agentic_signals": {
"goal_intake": false,

10
engineering/agent-harness/skills/agent-harness/assets/harnesses/markdown-html.json
View file

@ -16,7 +16,7 @@
{
"name": "design-system",
"path": "markdown-html/skills/design-system",
"description": "Captures the user's brand identity once via a 10-question onboarding wizard (primary/accent HEX + heading + body Google Fonts + design style editorial/technical/minimal/playful + default output directory + syntax theme + TOC behavior + optional logo/company), validates body-text and link contrast against WCAG 2.2 AA, derives 12 CSS custom properties in HSL space, and stores the result for every markdown-html converter to consume. Use before any markdown-html conversion. Triggers on first-run onboarding (\"set up the brand\", \"configure markdown-html\", \"run onboarding\"), on explicit reset (\"reset",
"description": "Captures the user's brand identity once via a 10-question onboarding wizard (primary/accent HEX + heading + body Google Fonts + design style editorial/technical/minimal/playful + default output directory + syntax theme + TOC behavior + optional logo/company), validates body-text and link contrast against WCAG 2.2 AA, derives 12 CSS custom properties in HSL space, and stores the result for every markdown-html converter to consume. Use before any markdown-html conversion. Triggers on first-run onboarding (\"set up the brand\", \"configure markdown-html\", \"run onboarding\"), on explicit reset \u2026",
"tools": [
{
"script": "markdown-html/skills/design-system/scripts/brand_palette_validator.py",
@ -81,7 +81,7 @@
{
"name": "markdown-html-orchestrator",
"path": "markdown-html/skills/markdown-html-orchestrator",
"description": "Use when a user wants to convert any markdown file in their Claude project into a single-file, lightly-interactive HTML \u2014 long-form documents (specs, plans, RFCs, reports, explainers), code reviews with diffs and severity-tagged annotations, or slide decks. Triggers on \"convert this markdown to HTML\", \"make this an HTML file\", \"turn this into an interactive document\", \"render this report as HTML\", \"PR writeup as HTML\", \"slides from this markdown\". Forks context to route to one of three converter sub-skills (md-document, md-review, md-slides) based on a deterministic doctype classifier, after t",
"description": "Use when a user wants to convert any markdown file in their Claude project into a single-file, lightly-interactive HTML \u2014 long-form documents (specs, plans, RFCs, reports, explainers), code reviews with diffs and severity-tagged annotations, or slide decks. Triggers on \"convert this markdown to HTML\", \"make this an HTML file\", \"turn this into an interactive document\", \"render this report as HTML\", \"PR writeup as HTML\", \"slides from this markdown\". Forks context to route to one of three converter sub-skills (md-document, md-review, md-slides) based on a deterministic doctype classifier \u2026",
"tools": [
{
"script": "markdown-html/skills/markdown-html-orchestrator/scripts/doctype_classifier.py",
@ -146,7 +146,7 @@
{
"name": "md-document",
"path": "markdown-html/skills/md-document",
"description": "Converts long-form markdown (specs, RFCs, reports, plans, explainers) into a single-file, lightly-interactive HTML document with sticky TOC, scrollspy, search filter, code-copy buttons, and design-system-driven brand tokens. Triggers when the markdown-html-orchestrator classifies an input as DOCUMENT, or when invoked directly via /cs:md-document. Reads the design-system config via config_loader.py and inlines the user's 12 derived CSS custom properties; refuses to render if onboarding hasn't run. Single-file output \u2014 Google Fonts + Prism.js CDN are the only externals; no framework runtime, no ",
"description": "Converts long-form markdown (specs, RFCs, reports, plans, explainers) into a single-file, lightly-interactive HTML document with sticky TOC, scrollspy, search filter, code-copy buttons, and design-system-driven brand tokens. Triggers when the markdown-html-orchestrator classifies an input as DOCUMENT, or when invoked directly via /cs:md-document. Reads the design-system config via config_loader.py and inlines the user's 12 derived CSS custom properties; refuses to render if onboarding hasn't run. Single-file output \u2014 Google Fonts + Prism.js CDN are the only externals; no framework runtime \u2026",
"tools": [
{
"script": "markdown-html/skills/md-document/scripts/html_renderer.py",
@ -216,7 +216,7 @@
{
"name": "md-review",
"path": "markdown-html/skills/md-review",
"description": "Converts a markdown PR writeup or code review (one with ```diff fenced blocks and severity-tagged > [!BLOCKER]/[!MAJOR]/[!MINOR]/[!NIT] callouts) into a single-file 2-column HTML review \u2014 unified-diff on the left, severity-tagged annotation cards on the right, top jump-nav listing every finding, mandatory named reviewer footer. Triggers when the markdown-html-orchestrator classifies an input as REVIEW, or when invoked directly via /cs:md-review. Refuses without explicit --reviewer (a code review must name a human), refuses if no diff hunks present (route to md-document instead), and refuses to",
"description": "Converts a markdown PR writeup or code review (one with ```diff fenced blocks and severity-tagged > [!BLOCKER]/[!MAJOR]/[!MINOR]/[!NIT] callouts) into a single-file 2-column HTML review \u2014 unified-diff on the left, severity-tagged annotation cards on the right, top jump-nav listing every finding, mandatory named reviewer footer. Triggers when the markdown-html-orchestrator classifies an input as REVIEW, or when invoked directly via /cs:md-review. Refuses without explicit --reviewer (a code review must name a human), refuses if no diff hunks present (route to md-document instead), and refuses \u2026",
"tools": [
{
"script": "markdown-html/skills/md-review/scripts/annotation_extractor.py",
@ -286,7 +286,7 @@
{
"name": "md-slides",
"path": "markdown-html/skills/md-slides",
"description": "Converts a markdown deck (slides separated by `---` HR boundaries or by `# ` H1 headings, with optional `<!-- notes: ... -->` presenter notes blocks) into a single-file HTML presentation with arrow-key / space / PgDn / PgUp / Home / End / P / Esc keyboard navigation, presenter mode (split view with current slide + speaker notes + clock + next-slide preview), URL-hash deep linking, and `@media print` page-per-slide for PDF export. Triggers when the markdown-html-orchestrator classifies an input as SLIDES, or when invoked directly via /cs:md-slides. Reuses md-document's markdown parser for slide",
"description": "Converts a markdown deck (slides separated by `---` HR boundaries or by `# ` H1 headings, with optional `<!-- notes: ... -->` presenter notes blocks) into a single-file HTML presentation with arrow-key / space / PgDn / PgUp / Home / End / P / Esc keyboard navigation, presenter mode (split view with current slide + speaker notes + clock + next-slide preview), URL-hash deep linking, and `@media print` page-per-slide for PDF export. Triggers when the markdown-html-orchestrator classifies an input as SLIDES, or when invoked directly via /cs:md-slides. Reuses md-document's markdown parser for \u2026",
"tools": [
{
"script": "markdown-html/skills/md-slides/scripts/deck_html_renderer.py",

16
engineering/agent-harness/skills/agent-harness/assets/harnesses/marketing-skill.json
View file

@ -76,7 +76,7 @@
{
"name": "aeo",
"path": "marketing-skill/skills/aeo",
"description": "Answer Engine Optimization (AEO) skill \u2014 optimize content to be cited by AI language models (ChatGPT, Perplexity, Claude, Gemini, Mistral) as authoritative sources. Distinct from SEO \u2014 AEO optimizes for citation in LLM-generated responses, not search rankings. Use when planning content for AI-first search audiences, auditing existing content for E-E-A-T signals, tracking which pages get cited by which LLMs, or building a citation-friendly content strategy. Triggers \u2014 'AEO audit', 'optimize for ChatGPT', 'get cited by Perplexity', 'LLM citation strategy', 'answer engine optimization', 'content ",
"description": "Answer Engine Optimization (AEO) skill \u2014 optimize content to be cited by AI language models (ChatGPT, Perplexity, Claude, Gemini, Mistral) as authoritative sources. Distinct from SEO \u2014 AEO optimizes for citation in LLM-generated responses, not search rankings. Use when planning content for AI-first search audiences, auditing existing content for E-E-A-T signals, tracking which pages get cited by which LLMs, or building a citation-friendly content strategy. Triggers \u2014 'AEO audit', 'optimize for ChatGPT', 'get cited by Perplexity', 'LLM citation strategy', 'answer engine optimization' \u2026",
"tools": [
{
"script": "marketing-skill/skills/aeo/scripts/aeo_audit.py",
@ -148,7 +148,7 @@
{
"name": "analytics-tracking",
"path": "marketing-skill/skills/analytics-tracking",
"description": "Set up, audit, and debug analytics tracking implementation \u2014 GA4, Google Tag Manager, event taxonomy, conversion tracking, and data quality. Use when building a tracking plan from scratch, auditing existing analytics for gaps or errors, debugging missing events, or setting up GTM. Trigger keywords: GA4 setup, Google Tag Manager, GTM, event tracking, analytics implementation, conversion tracking, tracking plan, event taxonomy, custom dimensions, UTM tracking, analytics audit, missing events, tracking broken. NOT for analyzing marketing campaign data \u2014 use campaign-analytics for that. NOT for BI",
"description": "Set up, audit, and debug analytics tracking implementation \u2014 GA4, Google Tag Manager, event taxonomy, conversion tracking, and data quality. Use when building a tracking plan from scratch, auditing existing analytics for gaps or errors, debugging missing events, or setting up GTM. Trigger keywords: GA4 setup, Google Tag Manager, GTM, event tracking, analytics implementation, conversion tracking, tracking plan, event taxonomy, custom dimensions, UTM tracking, analytics audit, missing events, tracking broken. NOT for analyzing marketing campaign data \u2014 use campaign-analytics for that. NOT for \u2026",
"tools": [
{
"script": "marketing-skill/skills/analytics-tracking/scripts/tracking_plan_generator.py",
@ -395,7 +395,7 @@
{
"name": "cold-email",
"path": "marketing-skill/skills/cold-email",
"description": "When the user wants to write, improve, or build a sequence of B2B cold outreach emails to prospects who haven't asked to hear from them. Use when the user mentions 'cold email,' 'cold outreach,' 'prospecting emails,' 'SDR emails,' 'sales emails,' 'first touch email,' 'follow-up sequence,' or 'email prospecting.' Also use when they share an email draft that sounds too sales-y and needs to be humanized. Distinct from email-sequence (lifecycle/nurture to opted-in subscribers) \u2014 this is unsolicited outreach to new prospects. NOT for lifecycle emails, newsletters, or drip campaigns (use email-seque",
"description": "When the user wants to write, improve, or build a sequence of B2B cold outreach emails to prospects who haven't asked to hear from them. Use when the user mentions 'cold email,' 'cold outreach,' 'prospecting emails,' 'SDR emails,' 'sales emails,' 'first touch email,' 'follow-up sequence,' or 'email prospecting.' Also use when they share an email draft that sounds too sales-y and needs to be humanized. Distinct from email-sequence (lifecycle/nurture to opted-in subscribers) \u2014 this is unsolicited outreach to new prospects. NOT for lifecycle emails, newsletters, or drip campaigns (use \u2026",
"tools": [
{
"script": "marketing-skill/skills/cold-email/scripts/email_sequence_analyzer.py",
@ -791,7 +791,7 @@
{
"name": "local-seo-manager",
"path": "marketing-skill/skills/local-seo-manager",
"description": "Manage local SEO for service-area businesses \u2014 appliance repair, HVAC, plumbing, cleaning, and any business that serves customers at their location. Use when the user wants to: audit Google Business Profile, generate neighborhood service area pages, check NAP consistency across directories, create LocalBusiness schema, or write review responses. Triggers: 'local SEO', 'Google Business Profile', 'GBP', 'service area page', 'NAP consistency', 'local citations', 'LocalBusiness schema', 'review responses', 'Google Maps ranking'. NOT for national SEO (use seo-audit). NOT for general schema (use sch",
"description": "Manage local SEO for service-area businesses \u2014 appliance repair, HVAC, plumbing, cleaning, and any business that serves customers at their location. Use when the user wants to: audit Google Business Profile, generate neighborhood service area pages, check NAP consistency across directories, create LocalBusiness schema, or write review responses. Triggers: 'local SEO', 'Google Business Profile', 'GBP', 'service area page', 'NAP consistency', 'local citations', 'LocalBusiness schema', 'review responses', 'Google Maps ranking'. NOT for national SEO (use seo-audit). NOT for general schema (use \u2026",
"tools": [
{
"script": "marketing-skill/skills/local-seo-manager/scripts/nap_checker.py",
@ -873,7 +873,7 @@
{
"name": "marketing-demand-acquisition",
"path": "marketing-skill/skills/marketing-demand-acquisition",
"description": "Creates demand generation campaigns, optimizes paid ad spend across LinkedIn, Google, and Meta, develops SEO strategies, and structures partnership programs. Use when planning demand gen strategy, growth marketing, advertising campaigns, PPC optimization, lead generation, pipeline generation, or marketing budgets. Covers multi-channel acquisition (Google Ads, LinkedIn Ads, Meta Ads), CAC analysis, MQL/SQL workflows, attribution modeling, technical SEO, and co-marketing partnerships. Default calibration profile is a Series A+ B2B SaaS scaling internationally (EU/US/Canada, hybrid PLG/Sales-Led)",
"description": "Creates demand generation campaigns, optimizes paid ad spend across LinkedIn, Google, and Meta, develops SEO strategies, and structures partnership programs. Use when planning demand gen strategy, growth marketing, advertising campaigns, PPC optimization, lead generation, pipeline generation, or marketing budgets. Covers multi-channel acquisition (Google Ads, LinkedIn Ads, Meta Ads), CAC analysis, MQL/SQL workflows, attribution modeling, technical SEO, and co-marketing partnerships. Default calibration profile is a Series A+ B2B SaaS scaling internationally (EU/US/Canada, hybrid \u2026",
"tools": [
{
"script": "marketing-skill/skills/marketing-demand-acquisition/scripts/calculate_cac.py",
@ -1126,7 +1126,7 @@
{
"name": "pricing-strategy",
"path": "marketing-skill/skills/pricing-strategy",
"description": "Design, optimize, and communicate SaaS pricing \u2014 tier structure, value metrics, pricing pages, and price increase strategy. Use when building a pricing model from scratch, redesigning existing pricing, planning a price increase, or improving a pricing page. Trigger keywords: pricing tiers, pricing page, price increase, packaging, value metric, per seat pricing, usage-based pricing, freemium, good-better-best, pricing strategy, monetization, pricing page conversion, Van Westendorp. NOT for broader product strategy \u2014 use product-strategist for that. NOT for customer success or renewals \u2014 use cus",
"description": "Design, optimize, and communicate SaaS pricing \u2014 tier structure, value metrics, pricing pages, and price increase strategy. Use when building a pricing model from scratch, redesigning existing pricing, planning a price increase, or improving a pricing page. Trigger keywords: pricing tiers, pricing page, price increase, packaging, value metric, per seat pricing, usage-based pricing, freemium, good-better-best, pricing strategy, monetization, pricing page conversion, Van Westendorp. NOT for broader product strategy \u2014 use product-strategist for that. NOT for customer success or renewals \u2014 use \u2026",
"tools": [
{
"script": "marketing-skill/skills/pricing-strategy/scripts/pricing_modeler.py",
@ -1183,7 +1183,7 @@
{
"name": "prompt-engineer-toolkit",
"path": "marketing-skill/skills/prompt-engineer-toolkit",
"description": "Turns marketing prompts into tested, versioned production assets: A/B prompt evaluation against structured test cases, immutable prompt version history with diffs, ready-to-use marketing prompt templates (ad copy, email campaigns, social posts, landing pages, SEO meta), and an LLM-governance playbook for marketing teams (claim discipline, disclosure rules, human-review gates). Use when a marketing team relies on AI-generated content and needs prompt quality to be measurable and safe \u2014 or when the user mentions 'prompt engineering,' 'improve my prompts,' 'prompt templates,' 'prompt versioning,'",
"description": "Turns marketing prompts into tested, versioned production assets: A/B prompt evaluation against structured test cases, immutable prompt version history with diffs, ready-to-use marketing prompt templates (ad copy, email campaigns, social posts, landing pages, SEO meta), and an LLM-governance playbook for marketing teams (claim discipline, disclosure rules, human-review gates). Use when a marketing team relies on AI-generated content and needs prompt quality to be measurable and safe \u2014 or when the user mentions 'prompt engineering,' 'improve my prompts,' 'prompt templates,' 'prompt \u2026",
"tools": [
{
"script": "marketing-skill/skills/prompt-engineer-toolkit/scripts/prompt_tester.py",
@ -1475,7 +1475,7 @@
{
"name": "webinar-marketing",
"path": "marketing-skill/skills/webinar-marketing",
"description": "When the user wants to plan, promote, run, or improve a webinar or virtual event to generate and convert demand. Use when the user mentions 'webinar,' 'virtual event,' 'online event,' 'live demo,' 'virtual summit,' 'workshop,' 'masterclass,' 'fireside chat,' 'roundtable,' 'registration funnel,' 'show-up rate,' 'attendance rate,' 'webinar promotion,' 'webinar follow-up,' or 'on-demand webinar.' Also use when they have a webinar that isn't converting \u2014 low registrations, low show-up, or attendees who don't buy \u2014 and want to diagnose and fix it. Covers the full funnel: registration, promotion, sh",
"description": "When the user wants to plan, promote, run, or improve a webinar or virtual event to generate and convert demand. Use when the user mentions 'webinar,' 'virtual event,' 'online event,' 'live demo,' 'virtual summit,' 'workshop,' 'masterclass,' 'fireside chat,' 'roundtable,' 'registration funnel,' 'show-up rate,' 'attendance rate,' 'webinar promotion,' 'webinar follow-up,' or 'on-demand webinar.' Also use when they have a webinar that isn't converting \u2014 low registrations, low show-up, or attendees who don't buy \u2014 and want to diagnose and fix it. Covers the full funnel: registration, promotion \u2026",
"tools": [
{
"script": "marketing-skill/skills/webinar-marketing/scripts/webinar_funnel_scorer.py",

2
engineering/agent-harness/skills/agent-harness/assets/harnesses/marketing.json
View file

@ -16,7 +16,7 @@
{
"name": "landing",
"path": "marketing/landing/skills/landing",
"description": "Generates a premium single-page HTML landing page with 3D CSS animations, GSAP scroll effects, and mouse-parallax depth. Forcing intake (product + elevator pitch, audience register, brand overrides, tone) locks down positioning before any copy or markup is written, so the page reflects the actual product rather than generic boilerplate. Use whenever the user says 'landing for X', 'create a landing page', 'build a landing page', 'make a landing page for X', 'I need a web page for Y', or provides product/service details and wants a polished website. Also triggers on 'promotional page', 'product ",
"description": "Generates a premium single-page HTML landing page with 3D CSS animations, GSAP scroll effects, and mouse-parallax depth. Forcing intake (product + elevator pitch, audience register, brand overrides, tone) locks down positioning before any copy or markup is written, so the page reflects the actual product rather than generic boilerplate. Use whenever the user says 'landing for X', 'create a landing page', 'build a landing page', 'make a landing page for X', 'I need a web page for Y', or provides product/service details and wants a polished website. Also triggers on 'promotional page' \u2026",
"tools": [
{
"script": "marketing/landing/skills/landing/scripts/brand_palette_validator.py",

90
engineering/agent-harness/skills/agent-harness/assets/harnesses/product-team.json
View file

@ -21,12 +21,17 @@
{
"script": "product-team/agile-product-owner/skills/agile-product-owner/scripts/user_story_generator.py",
"wired": true,
"supports_sample": false,
"supports_sample": true,
"verification": [
{
"cmd": "python3 product-team/agile-product-owner/skills/agile-product-owner/scripts/user_story_generator.py --help",
"expect_exit": 0,
"kind": "smoke"
},
{
"cmd": "python3 product-team/agile-product-owner/skills/agile-product-owner/scripts/user_story_generator.py --sample",
"expect_exit": 0,
"kind": "sample"
}
]
}
@ -77,7 +82,7 @@
{
"name": "code-to-prd",
"path": "product-team/code-to-prd/skills/code-to-prd",
"description": "Reverse-engineer any codebase into a complete Product Requirements Document (PRD). Analyzes routes, components, state management, API integrations, and user interactions to produce business-readable documentation detailed enough for engineers or AI agents to fully reconstruct every page and endpoint. Works with frontend frameworks (React, Vue, Angular, Svelte, Next.js, Nuxt), backend frameworks (NestJS, Django, Express, FastAPI), and fullstack applications. Use when users mention: generate PRD, reverse-engineer requirements, code to documentation, extract product specs from code, document page",
"description": "Reverse-engineer any codebase into a complete Product Requirements Document (PRD). Analyzes routes, components, state management, API integrations, and user interactions to produce business-readable documentation detailed enough for engineers or AI agents to fully reconstruct every page and endpoint. Works with frontend frameworks (React, Vue, Angular, Svelte, Next.js, Nuxt), backend frameworks (NestJS, Django, Express, FastAPI), and fullstack applications. Use when users mention: generate PRD, reverse-engineer requirements, code to documentation, extract product specs from code, document \u2026",
"tools": [
{
"script": "product-team/code-to-prd/skills/code-to-prd/scripts/codebase_analyzer.py",
@ -161,7 +166,7 @@
{
"name": "competitive-teardown",
"path": "product-team/skills/competitive-teardown",
"description": "Analyzes competitor products and companies by synthesizing data from pricing pages, app store reviews, job postings, SEO signals, and social media into structured competitive intelligence. Produces feature comparison matrices scored across 12 dimensions, SWOT analyses, positioning maps, UX audits, pricing model breakdowns, action item roadmaps, and stakeholder presentation templates. Use when conducting competitor analysis, comparing products against competitors, researching the competitive landscape, building battle cards for sales, preparing for a product strategy or roadmap session, respond",
"description": "Analyzes competitor products and companies by synthesizing data from pricing pages, app store reviews, job postings, SEO signals, and social media into structured competitive intelligence. Produces feature comparison matrices scored across 12 dimensions, SWOT analyses, positioning maps, UX audits, pricing model breakdowns, action item roadmaps, and stakeholder presentation templates. Use when conducting competitor analysis, comparing products against competitors, researching the competitive landscape, building battle cards for sales, preparing for a product strategy or roadmap session \u2026",
"tools": [
{
"script": "product-team/skills/competitive-teardown/scripts/competitive_matrix_builder.py",
@ -223,7 +228,7 @@
{
"name": "landing-page-generator",
"path": "product-team/skills/landing-page-generator",
"description": "Generates high-converting landing pages as complete Next.js/React (TSX) components with Tailwind CSS. Creates hero sections, feature grids, pricing tables, FAQ accordions, testimonial blocks, and CTA sections using proven copy frameworks (PAS, AIDA, BAB). Outputs SEO meta tags, structured data, and performance-optimised code targeting Core Web Vitals (LCP < 1s, CLS < 0.1). Use when the user asks to create a landing page, marketing page, homepage, single-page site, lead capture page, campaign page, promo page, or conversion-optimised web page \u2014 or when they want to A/B test landing page variant",
"description": "Generates high-converting landing pages as complete Next.js/React (TSX) components with Tailwind CSS. Creates hero sections, feature grids, pricing tables, FAQ accordions, testimonial blocks, and CTA sections using proven copy frameworks (PAS, AIDA, BAB). Outputs SEO meta tags, structured data, and performance-optimised code targeting Core Web Vitals (LCP < 1s, CLS < 0.1). Use when the user asks to create a landing page, marketing page, homepage, single-page site, lead capture page, campaign page, promo page, or conversion-optimised web page \u2014 or when they want to A/B test landing page \u2026",
"tools": [
{
"script": "product-team/skills/landing-page-generator/scripts/landing_page_scaffolder.py",
@ -357,16 +362,72 @@
{
"name": "product-skills",
"path": "product-team/skills/product-skills",
"description": "Router/index for the 12 product skills bundled in this plugin (RICE prioritization, OKRs, UX research, design tokens, competitive teardown, analytics, experiments, discovery, roadmaps, spec-to-repo, landing pages, SaaS scaffolding). Use when a product request doesn't obviously match one skill and you need to pick the right one (e.g., 'help me prioritize features', 'plan a product experiment').",
"tools": [],
"description": "Use when coordinating product work across the 12 bundled product sub-skills (RICE, OKRs, UX research, design tokens, competitive teardown, analytics, experiments, discovery, roadmaps, spec-to-repo, landing pages, SaaS scaffolding) or the 4 standalone product-team plugins (user stories, Apple HIG, code-to-PRD, research summarizer). Triggers on 'help me prioritize', 'plan a product experiment', 'we ship features nobody uses', 'run the discovery loop', 'is our OST sound'. Forks context to route to one sub-skill via a deterministic signal router and returns a digest; can also drive a \u2026",
"tools": [
{
"script": "product-team/skills/product-skills/scripts/discovery_cadence_tracker.py",
"wired": true,
"supports_sample": true,
"verification": [
{
"cmd": "python3 product-team/skills/product-skills/scripts/discovery_cadence_tracker.py --help",
"expect_exit": 0,
"kind": "smoke"
},
{
"cmd": "python3 product-team/skills/product-skills/scripts/discovery_cadence_tracker.py --sample",
"expect_exit": 0,
"kind": "sample"
}
]
},
{
"script": "product-team/skills/product-skills/scripts/ost_linter.py",
"wired": true,
"supports_sample": true,
"verification": [
{
"cmd": "python3 product-team/skills/product-skills/scripts/ost_linter.py --help",
"expect_exit": 0,
"kind": "smoke"
},
{
"cmd": "python3 product-team/skills/product-skills/scripts/ost_linter.py --sample",
"expect_exit": 0,
"kind": "sample"
}
]
},
{
"script": "product-team/skills/product-skills/scripts/product_goal_router.py",
"wired": true,
"supports_sample": true,
"verification": [
{
"cmd": "python3 product-team/skills/product-skills/scripts/product_goal_router.py --help",
"expect_exit": 0,
"kind": "smoke"
},
{
"cmd": "python3 product-team/skills/product-skills/scripts/product_goal_router.py --sample",
"expect_exit": 0,
"kind": "sample"
}
]
}
],
"agentic_signals": {
"goal_intake": true,
"refusal_gate": false,
"verification": false,
"loop_discipline": false,
"close_out": false
"refusal_gate": true,
"verification": true,
"loop_discipline": true,
"close_out": true
},
"references": []
"references": [
"ai_product_evals.md",
"continuous_discovery_canon.md",
"product_operating_model.md"
]
},
{
"name": "product-strategist",
@ -531,12 +592,17 @@
{
"script": "product-team/skills/ux-researcher-designer/scripts/persona_generator.py",
"wired": true,
"supports_sample": false,
"supports_sample": true,
"verification": [
{
"cmd": "python3 product-team/skills/ux-researcher-designer/scripts/persona_generator.py --help",
"expect_exit": 0,
"kind": "smoke"
},
{
"cmd": "python3 product-team/skills/ux-researcher-designer/scripts/persona_generator.py --sample",
"expect_exit": 0,
"kind": "sample"
}
]
}

12
engineering/agent-harness/skills/agent-harness/assets/harnesses/productivity.json
View file

@ -16,7 +16,7 @@
{
"name": "andreessen",
"path": "productivity/andreessen/skills/andreessen",
"description": "Marc Andreessen-mode decision and productivity skill. A blunt, market-first operator that pressure-tests ideas, ventures, features, and career bets through Andreessen's actual frameworks \u2014 market dominates team and product; the only milestone that matters is product/market fit; bias to build over deliberate. Use when the user says 'andreessen', 'pmarca mode', 'should I build this', 'is there a market', 'are we at product/market fit', 'pmf check', 'pressure-test this idea', 'be brutal about this venture', 'market-first take', or wants a no-disclaimers, no-hedging, confidence-leveled verdict on ",
"description": "Marc Andreessen-mode decision and productivity skill. A blunt, market-first operator that pressure-tests ideas, ventures, features, and career bets through Andreessen's actual frameworks \u2014 market dominates team and product; the only milestone that matters is product/market fit; bias to build over deliberate. Use when the user says 'andreessen', 'pmarca mode', 'should I build this', 'is there a market', 'are we at product/market fit', 'pmf check', 'pressure-test this idea', 'be brutal about this venture', 'market-first take', or wants a no-disclaimers, no-hedging, confidence-leveled verdict \u2026",
"tools": [
{
"script": "productivity/andreessen/skills/andreessen/scripts/anti_todo_card.py",
@ -87,7 +87,7 @@
{
"name": "capture",
"path": "productivity/capture/skills/capture",
"description": "Captures and organizes chaotic brain dumps into a structured, actionable system with zero information loss. Use this skill whenever the user says 'capture this', 'brain dump', 'let me dump some ideas', 'I've got a bunch of thoughts', 'here's everything on my mind', 'idea dump', 'let me get this out of my head', 'I need to organize my thoughts', 'here's what I'm thinking', or any variation where someone is unloading a messy stream of ideas, tasks, thoughts, and plans wanting them turned into something coherent. Also trigger when the user pastes or dictates a long, unstructured block of mixed id",
"description": "Captures and organizes chaotic brain dumps into a structured, actionable system with zero information loss. Use this skill whenever the user says 'capture this', 'brain dump', 'let me dump some ideas', 'I've got a bunch of thoughts', 'here's everything on my mind', 'idea dump', 'let me get this out of my head', 'I need to organize my thoughts', 'here's what I'm thinking', or any variation where someone is unloading a messy stream of ideas, tasks, thoughts, and plans wanting them turned into something coherent. Also trigger when the user pastes or dictates a long, unstructured block of mixed \u2026",
"tools": [
{
"script": "productivity/capture/skills/capture/scripts/complexity_estimator.py",
@ -157,7 +157,7 @@
{
"name": "inbox-setup",
"path": "productivity/email/skills/inbox-setup",
"description": "One-time setup skill that builds a personalized inbox triage knowledge base via interactive interview. Interviews the user about their email patterns, business context, reply style, and priorities using grill-me discipline (one question at a time, forcing format where possible, dependency-ordered, each question explains why I'm asking), then generates the knowledge base files that power the companion 'inbox-triage' skill. Run this once before using inbox-triage for the first time. Re-run when business, pricing, or priorities change significantly. Triggers: 'set up my inbox', 'configure inbox t",
"description": "One-time setup skill that builds a personalized inbox triage knowledge base via interactive interview. Interviews the user about their email patterns, business context, reply style, and priorities using grill-me discipline (one question at a time, forcing format where possible, dependency-ordered, each question explains why I'm asking), then generates the knowledge base files that power the companion 'inbox-triage' skill. Run this once before using inbox-triage for the first time. Re-run when business, pricing, or priorities change significantly. Triggers: 'set up my inbox', 'configure \u2026",
"tools": [
{
"script": "productivity/email/skills/inbox-setup/scripts/kb_validator.py",
@ -222,7 +222,7 @@
{
"name": "inbox-triage",
"path": "productivity/email/skills/inbox-triage",
"description": "Runs a full inbox triage using the knowledge base created by the 'inbox-setup' skill. Light-intake by design (most invocations skip questions and run with KB-default preferences); asks at most 2 grill-me override questions when invocation is outside normal cadence or includes category-skip intent. Searches recent emails, classifies them via the user's taxonomy, researches new senders, generates recommendations, drafts replies (NEVER sends), delivers a report in the user's preferred format, and updates the knowledge base with learnings. Designed to run on a recurring schedule (1-3x daily) or on",
"description": "Runs a full inbox triage using the knowledge base created by the 'inbox-setup' skill. Light-intake by design (most invocations skip questions and run with KB-default preferences); asks at most 2 grill-me override questions when invocation is outside normal cadence or includes category-skip intent. Searches recent emails, classifies them via the user's taxonomy, researches new senders, generates recommendations, drafts replies (NEVER sends), delivers a report in the user's preferred format, and updates the knowledge base with learnings. Designed to run on a recurring schedule (1-3x daily) or \u2026",
"tools": [
{
"script": "productivity/email/skills/inbox-triage/scripts/draft_safety_validator.py",
@ -287,7 +287,7 @@
{
"name": "handoff",
"path": "productivity/handoff/skills/handoff",
"description": "Compact the current conversation into a handoff document for another agent to pick up. Save to a user-configured location (OS temp, home folder, or per-project .handoff/), redact secrets before write, suggest skills for the next session, and auto-load the latest handoff on the next SessionStart. First-run setup asks where to save so the project folder never gets cluttered. Use when the user says 'hand this off', 'handoff doc', 'summarize this for a new session', 'compact this conversation', 'I'm ending this session', 'pick this up later', or any variation signaling intent to pass work to a fre",
"description": "Compact the current conversation into a handoff document for another agent to pick up. Save to a user-configured location (OS temp, home folder, or per-project .handoff/), redact secrets before write, suggest skills for the next session, and auto-load the latest handoff on the next SessionStart. First-run setup asks where to save so the project folder never gets cluttered. Use when the user says 'hand this off', 'handoff doc', 'summarize this for a new session', 'compact this conversation', 'I'm ending this session', 'pick this up later', or any variation signaling intent to pass work to a \u2026",
"tools": [
{
"script": "productivity/handoff/skills/handoff/scripts/cleanup.py",
@ -427,7 +427,7 @@
{
"name": "reflect",
"path": "productivity/reflect/skills/reflect",
"description": "Mid-conversation reflection skill that pauses execution and zooms out from detail-mode to honestly reassess direction, assumptions, and bias. Use when the user says 'reflect', 'take a step back', 'step back', 'zoom out', 'are we missing something', 'bigger picture', 'sanity check this', 'are we on track', 'are we overthinking this', 'forest for the trees', or any variation signaling intent to break out of detail-mode and reassess. Also trigger when the conversation has gone deep on implementation details without strategic check-in, or when the user shows signs of being stuck \u2014 that's often a s",
"description": "Mid-conversation reflection skill that pauses execution and zooms out from detail-mode to honestly reassess direction, assumptions, and bias. Use when the user says 'reflect', 'take a step back', 'step back', 'zoom out', 'are we missing something', 'bigger picture', 'sanity check this', 'are we on track', 'are we overthinking this', 'forest for the trees', or any variation signaling intent to break out of detail-mode and reassess. Also trigger when the conversation has gone deep on implementation details without strategic check-in, or when the user shows signs of being stuck \u2014 that's often \u2026",
"tools": [
{
"script": "productivity/reflect/skills/reflect/scripts/bias_pattern_detector.py",

78
engineering/agent-harness/skills/agent-harness/assets/harnesses/project-management.json
View file

@ -163,7 +163,7 @@
{
"name": "meeting-analyzer",
"path": "project-management/skills/meeting-analyzer",
"description": "Analyzes meeting transcripts and recordings to surface behavioral patterns, communication anti-patterns, and actionable coaching feedback. Use this skill whenever the user uploads or points to meeting transcripts (.txt, .md, .vtt, .srt, .docx), asks about their communication habits, wants feedback on how they run meetings, requests speaking ratio analysis, mentions filler words or conflict avoidance, or wants to compare their communication across time periods. Also trigger when users mention tools like Granola, Otter, Fireflies, or Zoom transcripts. Even if the user just says \"look at my meeti",
"description": "Analyzes meeting transcripts and recordings to surface behavioral patterns, communication anti-patterns, and actionable coaching feedback. Use this skill whenever the user uploads or points to meeting transcripts (.txt, .md, .vtt, .srt, .docx), asks about their communication habits, wants feedback on how they run meetings, requests speaking ratio analysis, mentions filler words or conflict avoidance, or wants to compare their communication across time periods. Also trigger when users mention tools like Granola, Otter, Fireflies, or Zoom transcripts. Even if the user just says \"look at my \u2026",
"tools": [],
"agentic_signals": {
"goal_intake": false,
@ -177,21 +177,77 @@
{
"name": "pm-skills",
"path": "project-management/skills/pm-skills",
"description": "Router/index for the 8 project-management skills bundled in this plugin (senior PM quant toolkit, scrum master, Jira/JQL, Confluence, Atlassian admin, Atlassian templates, meeting analyzer, team communications). Use when a PM request doesn't obviously match one skill and you need to pick the right one (e.g., 'our sprints feel off', 'audit our Jira permissions'). Bundles an Atlassian Remote MCP config (.mcp.json) for live Jira/Confluence access.",
"tools": [],
"description": "Use when coordinating project-delivery work across the 8 project-management sub-skills \u2014 sprint/velocity analytics, portfolio health, Jira/JQL, Confluence, Atlassian admin, templates, meeting analysis, team comms. Triggers on 'our sprints feel off', 'project health report', 'audit our Jira permissions', 'when will it be done', 'run the delivery loop'. Forks context to route to one sub-skill via a deterministic signal router and returns a digest; can also drive a full goal\u2192plan\u2192execute\u2192verify\u2192close delivery loop through the repo-wide agent-harness with Jira MCP data bridged into the domain's \u2026",
"tools": [
{
"script": "project-management/skills/pm-skills/scripts/delivery_loop_gate.py",
"wired": true,
"supports_sample": true,
"verification": [
{
"cmd": "python3 project-management/skills/pm-skills/scripts/delivery_loop_gate.py --help",
"expect_exit": 0,
"kind": "smoke"
},
{
"cmd": "python3 project-management/skills/pm-skills/scripts/delivery_loop_gate.py --sample",
"expect_exit": 0,
"kind": "sample"
}
]
},
{
"script": "project-management/skills/pm-skills/scripts/jira_snapshot_bridge.py",
"wired": true,
"supports_sample": true,
"verification": [
{
"cmd": "python3 project-management/skills/pm-skills/scripts/jira_snapshot_bridge.py --help",
"expect_exit": 0,
"kind": "smoke"
},
{
"cmd": "python3 project-management/skills/pm-skills/scripts/jira_snapshot_bridge.py --sample",
"expect_exit": 0,
"kind": "sample"
}
]
},
{
"script": "project-management/skills/pm-skills/scripts/pm_goal_router.py",
"wired": true,
"supports_sample": true,
"verification": [
{
"cmd": "python3 project-management/skills/pm-skills/scripts/pm_goal_router.py --help",
"expect_exit": 0,
"kind": "smoke"
},
{
"cmd": "python3 project-management/skills/pm-skills/scripts/pm_goal_router.py --sample",
"expect_exit": 0,
"kind": "sample"
}
]
}
],
"agentic_signals": {
"goal_intake": true,
"refusal_gate": false,
"verification": false,
"loop_discipline": false,
"close_out": false
"refusal_gate": true,
"verification": true,
"loop_discipline": true,
"close_out": true
},
"references": []
"references": [
"agentic_delivery_governance.md",
"flow_forecasting_canon.md",
"pm_loop_playbook.md"
]
},
{
"name": "scrum-master",
"path": "project-management/skills/scrum-master",
"description": "Advanced Scrum Master skill for data-driven agile team analysis and coaching. Use when the user asks about sprint planning, velocity tracking, retrospectives, standup facilitation, backlog grooming, story points, burndown charts, blocker resolution, or agile team health. Runs Python scripts to analyse sprint JSON exports from Jira or similar tools: velocity_analyzer.py for Monte Carlo sprint forecasting, sprint_health_scorer.py for multi-dimension health scoring, and retrospective_analyzer.py for action-item and theme tracking. Produces confidence-interval forecasts, health grade reports, and ",
"description": "Advanced Scrum Master skill for data-driven agile team analysis and coaching. Use when the user asks about sprint planning, velocity tracking, retrospectives, standup facilitation, backlog grooming, story points, burndown charts, blocker resolution, or agile team health. Runs Python scripts to analyse sprint JSON exports from Jira or similar tools: velocity_analyzer.py for Monte Carlo sprint forecasting, sprint_health_scorer.py for multi-dimension health scoring, and retrospective_analyzer.py for action-item and theme tracking. Produces confidence-interval forecasts, health grade reports \u2026",
"tools": [
{
"script": "project-management/skills/scrum-master/scripts/retrospective_analyzer.py",
@ -246,7 +302,7 @@
{
"name": "senior-pm",
"path": "project-management/skills/senior-pm",
"description": "Senior Project Manager for enterprise software, SaaS, and digital transformation projects. Specializes in portfolio management, quantitative risk analysis, resource optimization, stakeholder alignment, and executive reporting. Uses advanced methodologies including EMV analysis, Monte Carlo simulation, WSJF prioritization, and multi-dimensional health scoring. Use when a user needs help with project plans, project status reports, risk assessments, resource allocation, project roadmaps, milestone tracking, team capacity planning, portfolio health reviews, program management, or executive-level p",
"description": "Senior Project Manager for enterprise software, SaaS, and digital transformation projects. Specializes in portfolio management, quantitative risk analysis, resource optimization, stakeholder alignment, and executive reporting. Uses advanced methodologies including EMV analysis, Monte Carlo simulation, WSJF prioritization, and multi-dimensional health scoring. Use when a user needs help with project plans, project status reports, risk assessments, resource allocation, project roadmaps, milestone tracking, team capacity planning, portfolio health reviews, program management, or \u2026",
"tools": [
{
"script": "project-management/skills/senior-pm/scripts/project_health_dashboard.py",
@ -301,7 +357,7 @@
{
"name": "team-communications",
"path": "project-management/skills/team-communications",
"description": "Write internal company communications \u2014 3P updates (Progress/Plans/Problems), company-wide newsletters, FAQ roundups, incident reports, leadership updates, status reports, project updates, and general internal comms. Use this skill any time the user asks to draft, edit, or format something meant for internal audiences. Trigger on keywords like \"3P\", \"weekly update\", \"newsletter\", \"FAQ\", \"internal comms\", \"status report\", \"company update\", \"team update\", \"incident report\", or any request to summarize work for leadership, teammates, or the broader company. Even casual requests like \"write my upd",
"description": "Write internal company communications \u2014 3P updates (Progress/Plans/Problems), company-wide newsletters, FAQ roundups, incident reports, leadership updates, status reports, project updates, and general internal comms. Use this skill any time the user asks to draft, edit, or format something meant for internal audiences. Trigger on keywords like \"3P\", \"weekly update\", \"newsletter\", \"FAQ\", \"internal comms\", \"status report\", \"company update\", \"team update\", \"incident report\", or any request to summarize work for leadership, teammates, or the broader company. Even casual requests like \"write my \u2026",
"tools": [],
"agentic_signals": {
"goal_intake": true,

12
engineering/agent-harness/skills/agent-harness/assets/harnesses/ra-qm-team.json
View file

@ -16,7 +16,7 @@
{
"name": "eu-ai-act-specialist",
"path": "ra-qm-team/compliance-team-eu-ai-act/skills/eu-ai-act-specialist",
"description": "EU AI Act (Regulation (EU) 2024/1689) operational compliance for compliance teams. Three Article-level decisions: (1) What's the risk tier of this AI system \u2014 prohibited (Art. 5), high-risk (Art. 6 + Annex III), limited-risk (Art. 50), or minimal-risk? (2) For high-risk systems, what's the Article 43 conformity assessment route (Module A internal control vs Module H full QMS + notified body) and what goes in the Annex IV technical documentation? (3) Per organizational role (provider / deployer / importer / distributor / authorized representative), what are the active obligations and deadlines?",
"description": "EU AI Act (Regulation (EU) 2024/1689) operational compliance for compliance teams. Three Article-level decisions: (1) What's the risk tier of this AI system \u2014 prohibited (Art. 5), high-risk (Art. 6 + Annex III), limited-risk (Art. 50), or minimal-risk? (2) For high-risk systems, what's the Article 43 conformity assessment route (Module A internal control vs Module H full QMS + notified body) and what goes in the Annex IV technical documentation? (3) Per organizational role (provider / deployer / importer / distributor / authorized representative), what are the active obligations and \u2026",
"tools": [
{
"script": "ra-qm-team/compliance-team-eu-ai-act/skills/eu-ai-act-specialist/scripts/ai_act_obligation_tracker.py",
@ -72,7 +72,7 @@
{
"name": "iso42001-specialist",
"path": "ra-qm-team/compliance-team-iso42001/skills/iso42001-specialist",
"description": "ISO/IEC 42001:2023 AI Management System (AIMS) specialist for compliance teams running internal audits. Three decisions: (1) Where are the gaps against Clauses 4-10 and what do we close first? (2) What goes in the AI risk register and which Annex A controls treat each risk? (3) What's the 12-month internal audit plan that satisfies Clause 9.2? Use when preparing for certification, scoping internal audit cycles, or onboarding AI systems into an existing ISMS (27001) / QMS (13485) program. NOT an executive AI strategy skill (see chief-ai-officer-advisor). NOT EU AI Act compliance (see compliance",
"description": "ISO/IEC 42001:2023 AI Management System (AIMS) specialist for compliance teams running internal audits. Three decisions: (1) Where are the gaps against Clauses 4-10 and what do we close first? (2) What goes in the AI risk register and which Annex A controls treat each risk? (3) What's the 12-month internal audit plan that satisfies Clause 9.2? Use when preparing for certification, scoping internal audit cycles, or onboarding AI systems into an existing ISMS (27001) / QMS (13485) program. NOT an executive AI strategy skill (see chief-ai-officer-advisor). NOT EU AI Act compliance (see \u2026",
"tools": [
{
"script": "ra-qm-team/compliance-team-iso42001/skills/iso42001-specialist/scripts/ai_risk_register_builder.py",
@ -204,7 +204,7 @@
{
"name": "eu-ai-act-specialist",
"path": "ra-qm-team/skills/eu-ai-act-specialist",
"description": "EU AI Act (Regulation (EU) 2024/1689) operational compliance for compliance teams. Three Article-level decisions: (1) What's the risk tier of this AI system \u2014 prohibited (Art. 5), high-risk (Art. 6 + Annex III), limited-risk (Art. 50), or minimal-risk? (2) For high-risk systems, what's the Article 43 conformity assessment route (Module A internal control vs Module H full QMS + notified body) and what goes in the Annex IV technical documentation? (3) Per organizational role (provider / deployer / importer / distributor / authorized representative), what are the active obligations and deadlines?",
"description": "EU AI Act (Regulation (EU) 2024/1689) operational compliance for compliance teams. Three Article-level decisions: (1) What's the risk tier of this AI system \u2014 prohibited (Art. 5), high-risk (Art. 6 + Annex III), limited-risk (Art. 50), or minimal-risk? (2) For high-risk systems, what's the Article 43 conformity assessment route (Module A internal control vs Module H full QMS + notified body) and what goes in the Annex IV technical documentation? (3) Per organizational role (provider / deployer / importer / distributor / authorized representative), what are the active obligations and \u2026",
"tools": [
{
"script": "ra-qm-team/skills/eu-ai-act-specialist/scripts/ai_act_obligation_tracker.py",
@ -416,7 +416,7 @@
{
"name": "isms-audit-expert",
"path": "ra-qm-team/skills/isms-audit-expert",
"description": "Information Security Management System (ISMS) audit expert for ISO 27001 compliance verification, security control assessment, and certification support. Use when the user mentions ISO 27001, ISMS audit, Annex A controls, Statement of Applicability (SOA), gap analysis, nonconformity management, internal audit, surveillance audit, or security certification preparation. Helps review control implementation evidence, document audit findings, classify nonconformities, generate risk-based audit plans, map controls to Annex A requirements, prepare Stage 1 and Stage 2 audit documentation, and support ",
"description": "Information Security Management System (ISMS) audit expert for ISO 27001 compliance verification, security control assessment, and certification support. Use when the user mentions ISO 27001, ISMS audit, Annex A controls, Statement of Applicability (SOA), gap analysis, nonconformity management, internal audit, surveillance audit, or security certification preparation. Helps review control implementation evidence, document audit findings, classify nonconformities, generate risk-based audit plans, map controls to Annex A requirements, prepare Stage 1 and Stage 2 audit documentation, and \u2026",
"tools": [
{
"script": "ra-qm-team/skills/isms-audit-expert/scripts/isms_audit_scheduler.py",
@ -448,7 +448,7 @@
{
"name": "iso42001-specialist",
"path": "ra-qm-team/skills/iso42001-specialist",
"description": "ISO/IEC 42001:2023 AI Management System (AIMS) specialist for compliance teams running internal audits. Three decisions: (1) Where are the gaps against Clauses 4-10 and what do we close first? (2) What goes in the AI risk register and which Annex A controls treat each risk? (3) What's the 12-month internal audit plan that satisfies Clause 9.2? Use when preparing for certification, scoping internal audit cycles, or onboarding AI systems into an existing ISMS (27001) / QMS (13485) program. NOT an executive AI strategy skill (see chief-ai-officer-advisor). NOT EU AI Act compliance (see compliance",
"description": "ISO/IEC 42001:2023 AI Management System (AIMS) specialist for compliance teams running internal audits. Three decisions: (1) Where are the gaps against Clauses 4-10 and what do we close first? (2) What goes in the AI risk register and which Annex A controls treat each risk? (3) What's the 12-month internal audit plan that satisfies Clause 9.2? Use when preparing for certification, scoping internal audit cycles, or onboarding AI systems into an existing ISMS (27001) / QMS (13485) program. NOT an executive AI strategy skill (see chief-ai-officer-advisor). NOT EU AI Act compliance (see \u2026",
"tools": [
{
"script": "ra-qm-team/skills/iso42001-specialist/scripts/ai_risk_register_builder.py",
@ -704,7 +704,7 @@
{
"name": "regulatory-affairs-head",
"path": "ra-qm-team/skills/regulatory-affairs-head",
"description": "Senior Regulatory Affairs Manager for HealthTech and MedTech companies. Prepares FDA 510(k), De Novo, and PMA submission packages; analyzes regulatory pathways for new medical devices; drafts responses to FDA deficiency letters and Notified Body queries; develops CE marking technical documentation under EU MDR 2017/745; coordinates multi-market approval strategies across FDA, EU, Health Canada, PMDA, and NMPA; and maintains regulatory intelligence on evolving standards. Use when users need to plan or execute FDA submissions, navigate 510(k) or PMA approval processes, achieve CE marking, prepar",
"description": "Senior Regulatory Affairs Manager for HealthTech and MedTech companies. Prepares FDA 510(k), De Novo, and PMA submission packages; analyzes regulatory pathways for new medical devices; drafts responses to FDA deficiency letters and Notified Body queries; develops CE marking technical documentation under EU MDR 2017/745; coordinates multi-market approval strategies across FDA, EU, Health Canada, PMDA, and NMPA; and maintains regulatory intelligence on evolving standards. Use when users need to plan or execute FDA submissions, navigate 510(k) or PMA approval processes, achieve CE marking \u2026",
"tools": [
{
"script": "ra-qm-team/skills/regulatory-affairs-head/scripts/regulatory_pathway_analyzer.py",

10
engineering/agent-harness/skills/agent-harness/assets/harnesses/research-ops.json
View file

@ -16,7 +16,7 @@
{
"name": "clinical-research",
"path": "research-ops/skills/clinical-research",
"description": "Use when designing a prospective clinical study before submission \u2014 selecting and classifying endpoints (primary / key-secondary / exploratory, with surrogate-endpoint flagging), estimating sample size and power for two-arm designs (means / proportions / survival), or scoring a study plan for feasibility and a GO / GO-WITH-CONDITIONS / REDESIGN / NO-GO phase-gate decision. Every output is an ESTIMATE plus a named human owner (clinician / biostatistician / regulatory owner) \u2014 never clinical fact, never a finished protocol. Distinct from ra-qm-team, which handles the regulatory/QM submission (IS",
"description": "Use when designing a prospective clinical study before submission \u2014 selecting and classifying endpoints (primary / key-secondary / exploratory, with surrogate-endpoint flagging), estimating sample size and power for two-arm designs (means / proportions / survival), or scoring a study plan for feasibility and a GO / GO-WITH-CONDITIONS / REDESIGN / NO-GO phase-gate decision. Every output is an ESTIMATE plus a named human owner (clinician / biostatistician / regulatory owner) \u2014 never clinical fact, never a finished protocol. Distinct from ra-qm-team, which handles the regulatory/QM submission \u2026",
"tools": [
{
"script": "research-ops/skills/clinical-research/scripts/ar_evaluator.py",
@ -132,7 +132,7 @@
{
"name": "market-research",
"path": "research-ops/skills/market-research",
"description": "Use when doing upstream market-research methodology \u2014 sizing a market as TAM/SAM/SOM computed BOTH top-down and bottoms-up (never a single unsourced number), planning a survey sample size with finite-population correction and per-segment minimums, or scoring candidate market segments against Kotler's measurable/substantial/accessible/differentiable/actionable criteria. Outputs always show the method and the assumptions. For market-research analysts and product-marketing at the sizing/survey/segmentation moment. Distinct from marketing-skill (campaign analytics, attribution, demand-gen) \u2014 this ",
"description": "Use when doing upstream market-research methodology \u2014 sizing a market as TAM/SAM/SOM computed BOTH top-down and bottoms-up (never a single unsourced number), planning a survey sample size with finite-population correction and per-segment minimums, or scoring candidate market segments against Kotler's measurable/substantial/accessible/differentiable/actionable criteria. Outputs always show the method and the assumptions. For market-research analysts and product-marketing at the sizing/survey/segmentation moment. Distinct from marketing-skill (campaign analytics, attribution, demand-gen) \u2014 \u2026",
"tools": [
{
"script": "research-ops/skills/market-research/scripts/ar_evaluator.py",
@ -248,7 +248,7 @@
{
"name": "product-research",
"path": "research-ops/skills/product-research",
"description": "Use when planning and synthesizing product/user research as a method-and-repository discipline \u2014 selecting the right method for the goal (generative interviews vs usability test vs concept test vs validation), computing method-based saturation/sample size with an explicit confidence level, or synthesizing coded observations into insights while flagging single-source anecdotes. Never fabricates user insight; an insight requires recurrence across independent participants. Distinct from product-team/ux-researcher-designer (persona/journey artifacts), product-discovery (discovery-sprint planning),",
"description": "Use when planning and synthesizing product/user research as a method-and-repository discipline \u2014 selecting the right method for the goal (generative interviews vs usability test vs concept test vs validation), computing method-based saturation/sample size with an explicit confidence level, or synthesizing coded observations into insights while flagging single-source anecdotes. Never fabricates user insight; an insight requires recurrence across independent participants. Distinct from product-team/ux-researcher-designer (persona/journey artifacts), product-discovery (discovery-sprint \u2026",
"tools": [
{
"script": "research-ops/skills/product-research/scripts/ar_evaluator.py",
@ -364,7 +364,7 @@
{
"name": "research-finance",
"path": "research-ops/skills/research-finance",
"description": "Use when managing the money for an internal R&D program or portfolio \u2014 building a multi-period program budget with the F&A (indirect) split, tracking burn rate and runway against value-inflection milestones, or routing R&D cost items to a capitalize-vs-expense determination. Every budget output surfaces its assumptions block; capitalize-vs-expense is decision-support only and routes to a named finance owner \u2014 it never books an entry or decides accounting treatment. Distinct from finance/financial-analysis (corporate DCF, close, valuation) and research/grants (funding discovery \u2014 this manages m",
"description": "Use when managing the money for an internal R&D program or portfolio \u2014 building a multi-period program budget with the F&A (indirect) split, tracking burn rate and runway against value-inflection milestones, or routing R&D cost items to a capitalize-vs-expense determination. Every budget output surfaces its assumptions block; capitalize-vs-expense is decision-support only and routes to a named finance owner \u2014 it never books an entry or decides accounting treatment. Distinct from finance/financial-analysis (corporate DCF, close, valuation) and research/grants (funding discovery \u2014 this \u2026",
"tools": [
{
"script": "research-ops/skills/research-finance/scripts/ar_evaluator.py",
@ -480,7 +480,7 @@
{
"name": "research-ops-skills",
"path": "research-ops/skills/research-ops-skills",
"description": "Use when planning, funding, scoping, or synthesizing enterprise research across workstreams \u2014 clinical study design, R&D program finance, market sizing/surveys, or product/user research. Triggers on \"design this clinical study\", \"what sample size\", \"R&D budget\", \"burn rate\", \"capitalize or expense\", \"TAM SAM SOM\", \"market sizing\", \"survey design\", \"segment the market\", \"plan user interviews\", \"usability test\", \"synthesize research insights\". Forks context to route to one of four Research-Operations sub-skills (clinical-research, research-finance, market-research, product-research) and returns ",
"description": "Use when planning, funding, scoping, or synthesizing enterprise research across workstreams \u2014 clinical study design, R&D program finance, market sizing/surveys, or product/user research. Triggers on \"design this clinical study\", \"what sample size\", \"R&D budget\", \"burn rate\", \"capitalize or expense\", \"TAM SAM SOM\", \"market sizing\", \"survey design\", \"segment the market\", \"plan user interviews\", \"usability test\", \"synthesize research insights\". Forks context to route to one of four Research-Operations sub-skills (clinical-research, research-finance, market-research, product-research) and \u2026",
"tools": [],
"agentic_signals": {
"goal_intake": true,

18
engineering/agent-harness/skills/agent-harness/assets/harnesses/research.json
View file

@ -16,7 +16,7 @@
{
"name": "deep-research",
"path": "research/deep-research/skills/deep-research",
"description": "Run a disciplined, multi-source research investigation for a high-stakes question or decision \u2014 fan-out web search across many channels, parallel sub-agents, source triangulation (each claim backed by \u22653 independent sources), an adversarial review pass, and every source saved to its own file with verbatim quotes for reuse. Use when a low-quality answer is expensive: strategy work, comparing N products/methods/markets, validating a hypothesis with external data, or mapping how a field works. NOT for quick fact-checks (answer directly), structured 12-dimension competitor scoring (use competitive",
"description": "Run a disciplined, multi-source research investigation for a high-stakes question or decision \u2014 fan-out web search across many channels, parallel sub-agents, source triangulation (each claim backed by \u22653 independent sources), an adversarial review pass, and every source saved to its own file with verbatim quotes for reuse. Use when a low-quality answer is expensive: strategy work, comparing N products/methods/markets, validating a hypothesis with external data, or mapping how a field works. NOT for quick fact-checks (answer directly), structured 12-dimension competitor scoring (use \u2026",
"tools": [],
"agentic_signals": {
"goal_intake": false,
@ -32,7 +32,7 @@
{
"name": "dossier",
"path": "research/dossier/skills/dossier",
"description": "Decision-grade entity research skill \u2014 produces a hypothesis-tested dossier on a specific company, person, nonprofit, or government org, not a generic profile. Forcing intake makes the user state their hypothesis upfront (what they already believe and want to verify or disprove) so the dossier tests it rather than confirms it. Output is an editable Word document (.docx) with verdict on the hypothesis, identity facts, 12-month activity timeline, network and reputation signals, red flags, conversation hooks tied to specific findings, and source-provenance audit log. Uses WebSearch + WebFetch + f",
"description": "Decision-grade entity research skill \u2014 produces a hypothesis-tested dossier on a specific company, person, nonprofit, or government org, not a generic profile. Forcing intake makes the user state their hypothesis upfront (what they already believe and want to verify or disprove) so the dossier tests it rather than confirms it. Output is an editable Word document (.docx) with verdict on the hypothesis, identity facts, 12-month activity timeline, network and reputation signals, red flags, conversation hooks tied to specific findings, and source-provenance audit log. Uses WebSearch + WebFetch \u2026",
"tools": [
{
"script": "research/dossier/skills/dossier/scripts/citation_tracker.py",
@ -97,7 +97,7 @@
{
"name": "grants",
"path": "research/grants/skills/grants",
"description": "NIH grant research skill for clinical researchers. Grill-me intake (research idea + career stage + preliminary data + environment + submission posture + known institute targets) locks down the funding strategy before any search runs. Runs a 5-facet Consensus positioning analysis (with draft Significance/Innovation language), maps the research to the right NIH institutes and study sections via RePORTER, finds NOSIs and funded overlap, and produces an editable Word document (.docx) with budget/scope-aware mechanism recommendations, submission timelines, and a mandatory program officer recommenda",
"description": "NIH grant research skill for clinical researchers. Grill-me intake (research idea + career stage + preliminary data + environment + submission posture + known institute targets) locks down the funding strategy before any search runs. Runs a 5-facet Consensus positioning analysis (with draft Significance/Innovation language), maps the research to the right NIH institutes and study sections via RePORTER, finds NOSIs and funded overlap, and produces an editable Word document (.docx) with budget/scope-aware mechanism recommendations, submission timelines, and a mandatory program officer \u2026",
"tools": [
{
"script": "research/grants/skills/grants/scripts/citation_tracker.py",
@ -157,7 +157,7 @@
{
"name": "litreview",
"path": "research/litreview/skills/litreview",
"description": "Academic literature orientation skill that searches papers via free keyless APIs (PubMed E-utilities + OpenAlex) by default \u2014 with the Consensus MCP as an optional enhancement lane when connected \u2014 builds a strategic search plan using PICO (default) or SPIDER / Decomposition / hybrid as fallbacks, and synthesizes findings into a formatted Word (.docx) research guide. Grill-me intake (research question specificity + framework hint + tentative depth) before the recon search; a second forcing checkpoint after Phase 2 confirms framework + sub-areas + depth before searches consume budget. Configura",
"description": "Academic literature orientation skill that searches papers via free keyless APIs (PubMed E-utilities + OpenAlex) by default \u2014 with the Consensus MCP as an optional enhancement lane when connected \u2014 builds a strategic search plan using PICO (default) or SPIDER / Decomposition / hybrid as fallbacks, and synthesizes findings into a formatted Word (.docx) research guide. Grill-me intake (research question specificity + framework hint + tentative depth) before the recon search; a second forcing checkpoint after Phase 2 confirms framework + sub-areas + depth before searches consume budget. \u2026",
"tools": [
{
"script": "research/litreview/skills/litreview/scripts/citation_tracker.py",
@ -234,7 +234,7 @@
{
"name": "notebooklm",
"path": "research/notebooklm/skills/notebooklm",
"description": "Browser automation skill for controlling Google's NotebookLM. Use when the user wants anything done in NotebookLM (e.g., 'open NotebookLM', 'check my [name] notebook', 'ask my notebook about X', 'add [source] to NotebookLM', 'generate a Video Overview from my notebook', 'use NotebookLM Studio'). Handles reading and querying notebooks, adding sources (URLs, text, files, YouTube links, synthesized content), generating Studio outputs (Audio/Video Overviews, Mind Maps, Reports incl. Briefing Doc/Study Guide/FAQ, Flashcards, Quiz, slide decks, infographics \u2014 discover the exact set from the live Stu",
"description": "Browser automation skill for controlling Google's NotebookLM. Use when the user wants anything done in NotebookLM (e.g., 'open NotebookLM', 'check my [name] notebook', 'ask my notebook about X', 'add [source] to NotebookLM', 'generate a Video Overview from my notebook', 'use NotebookLM Studio'). Handles reading and querying notebooks, adding sources (URLs, text, files, YouTube links, synthesized content), generating Studio outputs (Audio/Video Overviews, Mind Maps, Reports incl. Briefing Doc/Study Guide/FAQ, Flashcards, Quiz, slide decks, infographics \u2014 discover the exact set from the live \u2026",
"tools": [
{
"script": "research/notebooklm/skills/notebooklm/scripts/action_router.py",
@ -304,7 +304,7 @@
{
"name": "patent",
"path": "research/patent/skills/patent",
"description": "Patent prior-art and landscape intelligence skill \u2014 not generic patent help. Commits to one of five sub-use-cases via forcing intake (novelty search / freedom-to-operate / competitive landscape / acquisition diligence / litigation prior-art) before any search runs. Searches Google Patents, Espacenet, USPTO, and optionally Lens.org for citation-graph signals. Output is an editable Word document (.docx) with verdict, ranked closest art (claim-text extracted), CPC-class-aware landscape, family-resolved hits, geographic coverage, FTO flags where applicable, strategy recommendations, and full audit",
"description": "Patent prior-art and landscape intelligence skill \u2014 not generic patent help. Commits to one of five sub-use-cases via forcing intake (novelty search / freedom-to-operate / competitive landscape / acquisition diligence / litigation prior-art) before any search runs. Searches Google Patents, Espacenet, USPTO, and optionally Lens.org for citation-graph signals. Output is an editable Word document (.docx) with verdict, ranked closest art (claim-text extracted), CPC-class-aware landscape, family-resolved hits, geographic coverage, FTO flags where applicable, strategy recommendations, and full \u2026",
"tools": [
{
"script": "research/patent/skills/patent/scripts/citation_tracker.py",
@ -369,7 +369,7 @@
{
"name": "pulse",
"path": "research/pulse/skills/pulse",
"description": "Multi-source recency research skill that takes the pulse of any topic across Reddit, Hacker News, the open web, and optionally X/Twitter within a configurable recent window (default 30 days). Forcing intake clarifies topic specificity, angle (trend/sentiment/problems/opportunities/comparison), time window, and platform scope before searching. Returns a synthesized briefing with citations, engagement metrics, and cross-platform pattern analysis. Use when the user requests multi-source recency intelligence on a topic (e.g., 'pulse on [topic]', 'what's happening with [topic]', 'what are people sa",
"description": "Multi-source recency research skill that takes the pulse of any topic across Reddit, Hacker News, the open web, and optionally X/Twitter within a configurable recent window (default 30 days). Forcing intake clarifies topic specificity, angle (trend/sentiment/problems/opportunities/comparison), time window, and platform scope before searching. Returns a synthesized briefing with citations, engagement metrics, and cross-platform pattern analysis. Use when the user requests multi-source recency intelligence on a topic (e.g., 'pulse on [topic]', 'what's happening with [topic]', 'what are people \u2026",
"tools": [
{
"script": "research/pulse/skills/pulse/scripts/citation_tracker.py",
@ -424,7 +424,7 @@
{
"name": "research",
"path": "research/research/skills/research",
"description": "Default entry point for any research request \u2014 a hybrid router that classifies the question deterministically and either delegates to a specialist research skill (pulse for trends/sentiment, grants for NIH funding, litreview for academic literature, syllabus for course reading, patent for prior-art + IP landscape, dossier for entity research) or runs its own plan-decompose-multi-source-search-synthesize-cite fallback workflow when no specialist matches. Always surfaces the routing decision so users can override. Use when the user makes any research request that doesn't obviously match a more-s",
"description": "Default entry point for any research request \u2014 a hybrid router that classifies the question deterministically and either delegates to a specialist research skill (pulse for trends/sentiment, grants for NIH funding, litreview for academic literature, syllabus for course reading, patent for prior-art + IP landscape, dossier for entity research) or runs its own plan-decompose-multi-source-search-synthesize-cite fallback workflow when no specialist matches. Always surfaces the routing decision so users can override. Use when the user makes any research request that doesn't obviously match a \u2026",
"tools": [
{
"script": "research/research/skills/research/scripts/classifier.py",
@ -494,7 +494,7 @@
{
"name": "syllabus",
"path": "research/syllabus/skills/syllabus",
"description": "Generates a curated supplementary reading list from any course syllabus using Consensus academic search. Grill-me intake (syllabus input format + course audience + year range) plus a grouping forcing-options checkpoint before any search runs \u2014 so the reading list matches the course's level and recency need. Parses the syllabus to extract topics and learning outcomes, searches Consensus for recent peer-reviewed papers per topic, and produces a professionally formatted .docx with clickable Consensus links, plain-language summaries calibrated to audience level, and Bloom-higher-order discussion q",
"description": "Generates a curated supplementary reading list from any course syllabus using Consensus academic search. Grill-me intake (syllabus input format + course audience + year range) plus a grouping forcing-options checkpoint before any search runs \u2014 so the reading list matches the course's level and recency need. Parses the syllabus to extract topics and learning outcomes, searches Consensus for recent peer-reviewed papers per topic, and produces a professionally formatted .docx with clickable Consensus links, plain-language summaries calibrated to audience level, and Bloom-higher-order \u2026",
"tools": [
{
"script": "research/syllabus/skills/syllabus/scripts/citation_tracker.py",

12
engineering/agent-harness/skills/agent-harness/scripts/harness_manifest_builder.py
View file

@ -55,6 +55,16 @@ def read_text(path):
return ""
def truncate_words(text, limit):
"""Cap at `limit` chars, cutting on a word boundary with an ellipsis marker."""
if len(text) <= limit:
return text
cut = text[:limit - 2]
if " " in cut:
cut = cut.rsplit(" ", 1)[0]
return cut.rstrip(",;:") + " …"
def parse_frontmatter(text):
"""Extract name/description from YAML frontmatter without a YAML dep."""
meta = {"name": "", "description": ""}
@ -123,7 +133,7 @@ def scan_skill(skill_dir, skill_md, repo_root):
return {
"name": meta["name"] or os.path.basename(skill_dir),
"path": rel_dir,
"description": meta["description"][:600],
"description": truncate_words(meta["description"], 600),
"tools": tools,
"agentic_signals": signals,
"references": sorted(os.listdir(os.path.join(skill_dir, "references")))

4
product-team/.claude-plugin/plugin.json
View file

@ -1,7 +1,7 @@
{
"name": "product-skills",
"description": "13 production-ready product skills: product manager toolkit (RICE, PRDs), agile product owner, product strategist, UX researcher, UI design system, competitive teardown, landing page generator, SaaS scaffolder, product analytics, experiment designer, product discovery, roadmap communicator, code-to-prd, research summarizer, apple-hig-expert (Apple Human Interface Guidelines), spec-to-repo. Agent skill and plugin for Claude Code, Codex, Gemini CLI, Cursor, OpenClaw.",
"version": "2.9.0",
"description": "13 production-ready product skills bundled in this plugin: product-skills fork-orchestrator with continuous-discovery loop (deterministic 16-lane router, Torres cadence tracker, OST linter), product manager toolkit (RICE, PRDs), product strategist, UX researcher, UI design system, competitive teardown, landing page generator, SaaS scaffolder, product analytics, experiment designer, product discovery, roadmap communicator, spec-to-repo. Companion standalone plugins: agile-product-owner, code-to-prd, apple-hig-expert, research-summarizer. Agent skill and plugin for Claude Code, Codex, Gemini CLI, Cursor, OpenClaw.",
"version": "2.11.1",
"author": {
"name": "Alireza Rezvani",
"url": "https://alirezarezvani.com"

39
product-team/CLAUDE.md
View file

@ -1,10 +1,33 @@
# Product Team Skills - Claude Code Guidance
This guide covers the 13 production-ready product management skills and their Python automation tools.
This guide covers the 17 production-ready product management skills (13 bundled incl. the orchestrator + 4 standalone plugins) and their Python automation tools.
## Orchestrator & Discovery Loop (product-skills)
`skills/product-skills/` is the domain's `context: fork` orchestrator and agent harness adapter:
```bash
# Route a product goal deterministically across all 16 lanes (exit 0 route / 2 ask / 3 no signal)
python3 skills/product-skills/scripts/product_goal_router.py --text "help me prioritize features"
# Score the continuous-discovery cadence (Torres weekly habit; refuses on < 2 interviews)
python3 skills/product-skills/scripts/discovery_cadence_tracker.py --input discovery_log.json
# Lint the Opportunity Solution Tree (exit 2 blocks the tree from driving a roadmap)
python3 skills/product-skills/scripts/ost_linter.py --input ost.json
```
Commands: `/cs:product` (router) · `/cs:grill-product` (canon-cited grilling) ·
`/cs:product-loop` (the discovery loop). Agent: `cs-product-orchestrator`. Build-scale
goals compile through `engineering/agent-harness` with the `product-team.json` manifest.
Hard rules: no roadmap cites a tree that fails the linter; single-participant claims are
anecdotes; AI features ship with eval specs (see
`skills/product-skills/references/ai_product_evals.md`).
## Product Skills Overview
**Available Skills:**
0. **product-skills/** - Domain orchestrator (`context: fork`) + continuous-discovery loop (3 tools: goal router, cadence tracker, OST linter)
1. **product-manager-toolkit/** - RICE prioritization, customer interview analysis (2 tools)
2. **agile-product-owner/** - User story generation, sprint planning (1 tool)
3. **product-strategist/** - OKR cascade, strategic planning (1 tool)
@ -22,11 +45,11 @@ This guide covers the 13 production-ready product management skills and their Py
15. **apple-hig-expert/** - Apple Human Interface Guidelines compliance and design (1 tool: hig_checker)
16. **spec-to-repo/** - Convert a spec document into a scaffolded repository
**Total Tools:** 17 Python automation tools
**Total Tools:** 22 Python automation tools
**Agents:** 5 (cs-product-manager, cs-agile-product-owner, cs-product-strategist, cs-ux-researcher, cs-product-analyst)
**Agents:** 6 (cs-product-orchestrator, cs-product-manager, cs-agile-product-owner, cs-product-strategist, cs-ux-researcher, cs-product-analyst)
**Slash Commands:** 8 (/rice, /okr, /persona, /user-story, /competitive-matrix, /prd, /sprint-plan, /code-to-prd)
**Slash Commands:** 11 (/cs:product, /cs:grill-product, /cs:product-loop, /rice, /okr, /persona, /user-story, /competitive-matrix, /prd, /sprint-plan, /code-to-prd)
## Python Automation Tools
@ -312,7 +335,7 @@ python roadmap-communicator/scripts/changelog_generator.py --from v1.0.0 --to HE
---
**Last Updated:** May 10, 2026
**Skills Deployed:** 13/13 product skills production-ready
**Total Tools:** 17 Python automation tools
**Agents:** 5 | **Commands:** 8
**Last Updated:** July 3, 2026
**Skills Deployed:** 17/17 product skills production-ready (product-skills is now a fork-orchestrator + discovery loop)
**Total Tools:** 22 Python automation tools
**Agents:** 6 | **Commands:** 11

81
product-team/agents/cs-product-orchestrator.md Normal file
View file

@ -0,0 +1,81 @@
---
name: cs-product-orchestrator
description: Outcome-first product lead. Routes product inquiries (prioritization, OKRs, UX research, design systems, competitive, analytics, experiments, discovery, roadmaps, scaffolding, stories, HIG, code-to-PRD, summarization) to the right sub-skill via the product-skills orchestrator, and drives the continuous-discovery loop with machine gates (cadence tracker + OST linter). Forks context to keep heavy intake (interview logs, event exports, competitor data) out of the parent thread. Signature forcing question — "What outcome does this serve, and which tested assumption says it will?"
tools: Read, Write, Edit, Glob, Grep, Bash, Skill
model: sonnet
---
# Product Orchestrator
You are an outcome-first product lead. Everything hangs from one measurable outcome;
opportunities are customer needs, not features in disguise; solutions earn roadmap slots
by surviving assumption tests, not by being someone's favorite. You run discovery as a
weekly loop with machine gates, and you bracket prioritization frameworks instead of
worshiping one.
## Voice
**"What outcome does this serve, and which tested assumption says it will?"**
The trap you protect against: the feature factory — shipping output, celebrating
velocity, never checking whether anyone's behavior changed.
## Your 16 lanes
12 bundled: product-manager-toolkit (PRIORITIZE) · product-strategist (STRATEGY) ·
ux-researcher-designer (UX) · ui-design-system (DESIGN_SYSTEM) · competitive-teardown
(COMPETITIVE) · product-analytics (ANALYTICS) · experiment-designer (EXPERIMENT) ·
product-discovery (DISCOVERY) · roadmap-communicator (ROADMAP) · spec-to-repo
(SPEC_TO_REPO) · landing-page-generator (LANDING) · saas-scaffolder (SAAS_SCAFFOLD).
4 standalone plugins: agile-product-owner (STORIES) · apple-hig-expert (HIG) ·
code-to-prd (CODE_TO_PRD) · research-summarizer (SUMMARIZE).
## Routing logic
1. Run `python3 product-team/skills/product-skills/scripts/product_goal_router.py --text "<goal>"`.
2. Exit 0 → load the routed skill's SKILL.md (`skill_path` covers the standalone
plugins), follow its workflow in the forked context.
3. Exit 2 → ask ONE clarifying question naming the candidates, with a recommended answer.
4. Exit 3 → ask the user to restate the goal with the deliverable named. Never guess.
## The discovery loop (your recurring duty)
Weekly: score the log (`discovery_cadence_tracker.py` — refuses on < 2 interviews), act
on `next_loop_action`, lint the tree (`ost_linter.py` — exit 0 required before any
roadmap cites it), keep the streak alive. DORMANT 4+ weeks → escalate to the product
lead by name. HEALTHY + validated assumption → graduate to experiment-designer or a PRD.
## How you communicate (Matt Pocock grill discipline)
One question per turn; always recommend; explore the workspace before asking (an
`ost.json` or `discovery_log.json` resolves the lane silently); depth-first on
multi-lane inquiries; never silently chain. Digest ≤ 200 words: analyzed, top 3 findings
(canon-cited), top 3 next actions (named owner), artifact path, one grill challenge.
Hard outputs:
- Insights carry participant counts — singletons are anecdotes, flagged as such.
- Experiment recommendations carry the computed sample size and MDE.
- Prioritization names its framework (RICE / WSJF / opportunity score) and why.
- AI features get an eval spec (golden set + rubric + guardrails) in the PRD, per
`product-team/skills/product-skills/references/ai_product_evals.md`.
## Anti-patterns
- ❌ Cite an OST that fails the linter, or skip the linter because the tree "looks right"
- ❌ Promote a single-participant quote to an insight
- ❌ Answer "what should we build" without asking what outcome it serves
- ❌ Run all 16 lanes "to be thorough" — route to one, digest, chain on confirmation
- ❌ Report an exhausted loop budget as success
## When to escalate
- Delivery/sprint/Jira execution → `project-management` (cs-pm-orchestrator)
- Campaign/landing marketing → `marketing-skill` / `marketing/landing`
- Pricing and packaging economics → `commercial`
- Generic loop mechanics → `engineering/agent-harness` harness-runner
## Available commands
`/cs:product <inquiry>` (router) · `/cs:grill-product <plan>` (grill first) ·
`/cs:product-loop` (discovery loop) · plus the domain's `/rice`, `/okr`, `/persona`,
`/user-story`, `/competitive-matrix`, `/prd`, `/sprint-plan`, `/code-to-prd`.

23
product-team/agile-product-owner/skills/agile-product-owner/scripts/user_story_generator.py
View file

@ -326,13 +326,26 @@ def create_sample_epic():
}
def main():
import sys
import argparse
parser = argparse.ArgumentParser(
description="Generate INVEST user stories from the bundled sample epic, or plan "
"a sprint from the generated backlog.")
parser.add_argument("mode", nargs="?", choices=["epic", "sprint"], default="epic",
help="'epic' breaks the sample epic into stories; 'sprint' plans "
"a sprint from that backlog (default: epic).")
parser.add_argument("capacity", nargs="?", type=int, default=30,
help="Sprint capacity in story points (sprint mode, default: 30).")
parser.add_argument("--sample", action="store_true",
help="Break the bundled sample epic into stories and exit 0 "
"(same as the default epic mode; kept for harness smoke tests).")
args = parser.parse_args()
generator = UserStoryGenerator()
if len(sys.argv) > 1 and sys.argv[1] == 'sprint':
if args.mode == 'sprint':
# Generate sprint planning
capacity = int(sys.argv[2]) if len(sys.argv) > 2 else 30
capacity = args.capacity
# Create sample backlog
epic = create_sample_epic()

59
product-team/commands/cs-grill-product.md Normal file
View file

@ -0,0 +1,59 @@
---
description: Matt Pocock-style interrogation of a product plan against the product canon (Torres, Cagan Transformed, Reinertsen/WSJF, Amplitude North Star, evals-as-PRD). One forcing question per turn with a recommended answer; refuses to invoke any sub-skill or start a loop until the outcome-defining decisions are locked. Use before running /cs:product or /cs:product-loop on a fuzzy plan.
argument-hint: "<product plan, roadmap, feature idea, or strategy to interrogate>"
---
# /cs:grill-product — grill a product plan before running it
Interrogate this plan — do not execute anything yet:
**$ARGUMENTS**
Five rules (preserved from Matt Pocock, MIT): one question per turn · always give a
recommended answer · explore the workspace before asking · walk the decision tree
depth-first · track answered questions and their dependencies.
## Decision tree
- **Branch 1 — Outcome**: "What single measurable outcome does this serve, with a number?
Recommended: write it as the OST root before anything else. Canon: Torres,
*Continuous Discovery Habits*."
- **Branch 2 — Evidence**: "Which tested assumption says this will work — and how many
independent participants back it? Recommended: link the surviving assumption test;
singletons are anecdotes. Canon: Bland, *Testing Business Ideas*; Torres."
- **Branch 3 — Structure**: "Does the tree pass the linter? Recommended: run
`ost_linter.py` — exit 0 before any roadmap cites it; feature-phrased opportunities
(O2) and untested solutions (O4) are the usual failures. Canon: Torres OST discipline."
- **Branch 4 — Prioritization honesty**: "Would delaying any item a quarter erode its
value? Recommended: if yes, run WSJF/cost-of-delay next to RICE and flag rank flips on
one-step estimate changes. Canon: Reinertsen; the WSJF false-precision critique."
- **Branch 5 — Measurement**: "Is your North Star a leading value metric with an input
tree, or revenue/vanity? Recommended: leading value metric; funnel verdicts need
benchmark bands. Canon: Amplitude, *The North Star Playbook*; ProductLed benchmarks."
- **Branch 6 — AI features**: "If any feature is probabilistic: where is the eval —
golden set, rubric, guardrail SLOs? Recommended: write the eval spec into the PRD
before building; vibe-check launches are shipping without tests. Canon: evals-as-PRD
(Lenny's/Braintrust)."
Per-turn output format:
```
Q[i]/[total]: [precise question]
Recommended: [answer + canon-cited rationale]
(Confirm, or override?)
```
## Stop conditions
- All branches resolved → invoke `/cs:product` (question) or `/cs:product-loop`
(recurring discovery) with the locked decisions inlined.
- User says "stop grilling, just run it" → run with unresolved branches flagged in the
digest.
- Abandoned → save the partial grill to `product-grill-{timestamp}.md`.
## Distinct from
- `engineering/grill-me` — generic plan interrogation. This grills against the product
canon.
- `/cs:product` — routes; this refuses to route until decisions are locked.

49
product-team/commands/cs-product-loop.md Normal file
View file

@ -0,0 +1,49 @@
---
description: Run the continuous-discovery loop — score the weekly cadence (Torres), act on the named gap, lint the Opportunity Solution Tree as the machine gate, and keep the streak alive with explicit stop states. The product-domain recurring loop; graduates validated assumptions to experiments or PRDs.
argument-hint: "[path to discovery_log.json] [path to ost.json]"
---
# /cs:product-loop — the continuous-discovery loop
Inputs (defaults: `discovery_log.json` and `ost.json` in the workspace; shapes in
`product-team/skills/product-skills/assets/`):
**$ARGUMENTS**
## Sequence (one iteration per invocation)
1. **Observe** —
```bash
python3 product-team/skills/product-skills/scripts/discovery_cadence_tracker.py --input discovery_log.json
```
Exit 5 (< 2 interviews): there is no cadence to measure — help the user book the
first two weekly touchpoints and write the outcome statement; stop there.
2. **Choose** — the report's `next_loop_action` is the choice. Typical actions: book the
missing weekly touchpoint · re-anchor the interview guide on the outcome · test the
top untested assumption (route to `product-discovery`'s assumption_mapper to rank).
3. **Act** — execute with the routed sub-skill's tools (ux-researcher-designer for the
interview, experiment-designer for the test design). One bounded action per
iteration.
4. **Verify** —
```bash
python3 product-team/skills/product-skills/scripts/ost_linter.py --input ost.json
```
Exit 2 → fix the listed O1–O5 violations before the tree may drive any roadmap or
experiment. Then re-run the cadence tracker and confirm the health score did not
drop.
5. **Record** — update `discovery_log.json` (interview/test entries) and `ost.json`;
note the health score in the digest so the trend is visible across iterations.
6. **Repeat or stop** — terminal states:
- **Graduate**: HEALTHY + a validated assumption → hand off to `experiment-designer`
(A/B gate) or `product-manager-toolkit` (PRD with eval spec if the feature is
AI-powered).
- **Escalate**: DORMANT 4+ weeks → name the product lead and say the habit is dead —
never let discovery die silently.
- **Clean no-op**: cadence HEALTHY, no gaps — book next week's touchpoint and exit.
## Rules
- Never modify the linter or tracker to make a gate pass.
- Insights require recurrence across independent participants — singletons stay
anecdotes.
- The loop edits the log and the tree, never the gates (locked-evaluator invariant).

47
product-team/commands/cs-product.md Normal file
View file

@ -0,0 +1,47 @@
---
description: Top-level product-team router. Classifies a product inquiry across 16 lanes (prioritization, OKRs, UX, design system, competitive, analytics, experiments, discovery, roadmaps, spec-to-repo, landing, SaaS scaffold, stories, HIG, code-to-PRD, summarizer) with a deterministic script and forks context to the right sub-skill via the product-skills orchestrator, returning a ≤200-word digest with one grill challenge.
argument-hint: "<product inquiry: prioritize features, plan an experiment, discovery health, etc.>"
---
# /cs:product — Product Team router
Route this inquiry through the `product-skills` orchestrator:
**$ARGUMENTS**
## Routing (deterministic — run the script, don't eyeball)
```bash
python3 product-team/skills/product-skills/scripts/product_goal_router.py --text "$ARGUMENTS" --output json
```
- Exit 0 → load `skill_path`/SKILL.md (covers the 4 standalone plugins too) and follow
that skill's own workflow in a fork.
- Exit 2 → ask ONE clarifying question naming the listed candidates, recommended answer
first.
- Exit 3 → ask the user to restate the goal with the deliverable named. Never guess.
- Explore the workspace first — an `ost.json`, `discovery_log.json`, or `features.csv`
resolves the lane silently. Never silently chain a second sub-skill.
## Output (≤200-word digest)
- What was analyzed
- Top 3 findings, each anchored to a canon citation
- Top 3 next actions with a named owner
- Artifact path
- One grill challenge (e.g. "This roadmap cites an OST that fails the linter — which
opportunity backs item 3?")
## Hard rules
- Insights carry participant counts; singletons are anecdotes.
- Experiments carry computed sample size + MDE, never gut feel.
- Prioritization names its framework (RICE / WSJF / opportunity score) and why.
- AI features get an eval spec (golden set + rubric + guardrails) in the PRD.
- Recurring discovery work goes to `/cs:product-loop` instead.
## Distinct from
- `project-management` — how to deliver. This domain is what to build.
- `marketing/landing` — from-scratch marketing pages; `landing-page-generator` here
scaffolds product Next.js/TSX pages.

207
product-team/skills/product-skills/SKILL.md
View file

@ -1,61 +1,180 @@
---
name: "product-skills"
description: "Router/index for the 12 product skills bundled in this plugin (RICE prioritization, OKRs, UX research, design tokens, competitive teardown, analytics, experiments, discovery, roadmaps, spec-to-repo, landing pages, SaaS scaffolding). Use when a product request doesn't obviously match one skill and you need to pick the right one (e.g., 'help me prioritize features', 'plan a product experiment')."
version: 2.9.0
description: "Use when coordinating product work across the 12 bundled product sub-skills (RICE, OKRs, UX research, design tokens, competitive teardown, analytics, experiments, discovery, roadmaps, spec-to-repo, landing pages, SaaS scaffolding) or the 4 standalone product-team plugins (user stories, Apple HIG, code-to-PRD, research summarizer). Triggers on 'help me prioritize', 'plan a product experiment', 'we ship features nobody uses', 'run the discovery loop', 'is our OST sound'. Forks context to route to one sub-skill via a deterministic signal router and returns a digest; can also drive a continuous-discovery loop (Torres cadence tracker + OST linter as machine gates) or a full goal→plan→execute→verify→close run through the repo-wide agent-harness. Distinct from project-management (how to deliver vs what to build), marketing/landing (from-scratch pages), and engineering/agent-harness (the generic loop engine this orchestrator plugs into)."
context: fork
version: 2.11.1
author: Alireza Rezvani
license: MIT
tags:
- product
- product-management
- ux
- ui
- saas
- agile
agents:
- claude-code
- codex-cli
- openclaw
tags: [product, product-management, orchestrator, discovery, ux, analytics, agent-harness]
compatible_tools: [claude-code, codex-cli, cursor, antigravity, opencode, gemini-cli]
---
# Product Skills — Router
# Product Team — Domain Orchestrator & Discovery Loop
This plugin bundles **12 product skills** (this router is the 13th folder under `product-team/skills/`). Each skill is self-contained: read its `SKILL.md`, run its `scripts/`, apply its `references/` and `assets/`.
This orchestrator does two jobs. **Routing:** fork context, classify a product inquiry
with `scripts/product_goal_router.py` across all 16 product-team lanes (12 bundled + 4
standalone plugins), run exactly one, return a digest. **Looping:** run product work as
bounded agentic loops with machine-checkable gates — the continuous-discovery loop
(weekly cadence scored by `discovery_cadence_tracker.py`, tree structure enforced by
`ost_linter.py`) and goal-scale runs through the repo-wide agent-harness.
## Routing table
## When to invoke
Match the request against the signals below, then load `product-team/skills/<skill>/SKILL.md`. If two or more rows match, ask the user one clarifying question before loading anything.
| Symptom | Sub-skill |
|---|---|
| "Prioritize features / RICE / PRD" | `product-manager-toolkit` |
| "OKRs, strategy cascade" | `product-strategist` |
| "Personas, usability, research synthesis" | `ux-researcher-designer` |
| "Design tokens, WCAG contrast" | `ui-design-system` |
| "Competitor matrix, teardown" | `competitive-teardown` |
| "Retention, cohorts, funnels, KPIs" | `product-analytics` |
| "A/B test, sample size, hypothesis" | `experiment-designer` |
| "Discovery, assumptions, opportunity trees" | `product-discovery` |
| "Roadmap comms, release notes, changelog" | `roadmap-communicator` |
| "Spec → runnable repo" | `spec-to-repo` |
| "Landing page (Next.js/Tailwind)" | `landing-page-generator` |
| "SaaS boilerplate" | `saas-scaffolder` |
| "User stories, sprint capacity" | `agile-product-owner` (standalone) |
| "Apple HIG audit" | `apple-hig-expert` (standalone) |
| "PRD from an existing codebase" | `code-to-prd` (standalone) |
| "Summarize papers/articles" | `research-summarizer` (standalone) |
| Request signals | Skill | Path |
|---|---|---|
| Prioritize features, RICE scores, interview synthesis | product-manager-toolkit | `skills/product-manager-toolkit/` |
| OKRs, strategy cascade, objective alignment | product-strategist | `skills/product-strategist/` |
| Personas, usability findings, research synthesis | ux-researcher-designer | `skills/ux-researcher-designer/` |
| Design tokens, component specs, WCAG contrast | ui-design-system | `skills/ui-design-system/` |
| Competitor analysis, feature/pricing matrix | competitive-teardown | `skills/competitive-teardown/` |
| Retention, cohorts, funnel analysis | product-analytics | `skills/product-analytics/` |
| A/B test design, sample size, hypothesis gates | experiment-designer | `skills/experiment-designer/` |
| Opportunity trees, assumption mapping, discovery | product-discovery | `skills/product-discovery/` |
| Roadmap formats per audience, changelogs | roadmap-communicator | `skills/roadmap-communicator/` |
| Turn a written spec into a repo scaffold | spec-to-repo | `skills/spec-to-repo/` |
| Landing page (Next.js TSX + Tailwind) | landing-page-generator | `skills/landing-page-generator/` |
| Bootstrap a SaaS app skeleton | saas-scaffolder | `skills/saas-scaffolder/` |
## Quick start
## Routing logic (deterministic)
```bash
# Example: route a prioritization request
cat product-team/skills/product-manager-toolkit/SKILL.md
python3 product-team/skills/product-manager-toolkit/scripts/rice_prioritizer.py --help
python3 scripts/product_goal_router.py --text "<the goal>" --output json
```
## Related product-team plugins (packaged separately, not in this bundle)
Exit 0 → `route_to` names the skill (with `skill_path`, including the standalone
plugins): load its SKILL.md and follow its workflow. Exit 2 → ask ONE clarifying question
naming the listed candidates, with a recommended answer. Exit 3 → no signal: ask the user
to restate the goal with the deliverable named. Never guess silently; never silently
chain — digest first, confirm, then chain.
- `product-team/agile-product-owner/` — user stories, sprint capacity
- `product-team/code-to-prd/` — reverse-engineer a PRD from a codebase
- `product-team/apple-hig-expert/` — Apple HIG audits (Liquid Glass era)
- `product-team/research-summarizer/` — document summarization with citation extraction
## The discovery loop (the domain's recurring agentic loop)
## Rules
Modern discovery is a weekly habit, not a project phase (Torres). Run it as a bounded
loop with two machine gates:
- Route to exactly one skill, then follow that skill's own workflow.
- This router ships no tools of its own — if no row matches, say so and ask rather than improvising.
1. **Observe** — maintain `discovery_log.json` (interviews, assumption tests; shape in
`assets/sample_discovery_log.json`) and score the cadence:
```bash
python3 scripts/discovery_cadence_tracker.py --input discovery_log.json
```
Refuses on < 2 interviews (exit 5) — there is no cadence to measure yet. Output:
health 0–100, verdict HEALTHY/AT-RISK/DORMANT, named gaps, and `next_loop_action`.
2. **Choose** — the tracker's `next_loop_action` IS the choice: book the touchpoint,
re-anchor the guide on the outcome, or test the top untested assumption (route to
`product-discovery`'s assumption_mapper for prioritization).
3. **Act** — run the interview / assumption test with the routed sub-skill's tools.
4. **Verify** — keep the tree structurally sound before it may drive a roadmap:
```bash
python3 scripts/ost_linter.py --input ost.json # exit 2 = NEEDS-REWORK, fix before citing the tree
```
Rules: one measurable outcome root (O1), opportunities are needs not features (O2),
targeted opportunities compare ≥ 2 solutions (O3), every solution has an assumption
test (O4), no orphan solutions (O5 — the feature-factory tell).
5. **Record / Repeat-or-stop** — update the log, keep the weekly streak alive. Stop
states: HEALTHY + validated assumption → graduate to `experiment-designer` (build the
A/B gate) or `product-manager-toolkit` (PRD); DORMANT for 4+ weeks → escalate to the
product lead by name — do not quietly let discovery die.
For build-scale goals ("turn this validated spec into a repo and verify it"), compile
through the repo-wide harness instead:
```bash
python3 engineering/agent-harness/skills/agent-harness/scripts/goal_compiler.py \
--goal "<goal>" --manifest engineering/agent-harness/skills/agent-harness/assets/harnesses/product-team.json \
--out .agent-harness/plan.json
```
The domain's three strongest close-out gates plug in as task verifications:
`../spec-to-repo/scripts/validate_project.py` (exit 0), `code-to-prd`'s golden
`expected_outputs/`, and `research-summarizer`'s citation-count check.
## Hard rules
1. **Evidence before conviction**: no roadmap item cites the OST unless `ost_linter.py`
exits 0; no insight is asserted from a single participant (anecdote, not insight).
2. **Outcome-first**: every loop hangs from one measurable outcome — the linter's O1 rule
is the intake gate.
3. **Experiments are gated by math**: sample size from
`../experiment-designer/scripts/sample_size_calculator.py`, never gut feel; report the
MDE with the verdict.
4. **Prioritization shows its framework**: RICE for steady-state, WSJF/cost-of-delay when
time sensitivity dominates, opportunity scoring for underserved needs — name which and
why (see [references/product_operating_model.md](references/product_operating_model.md)).
5. **AI features ship with evals**: a golden set + rubric is the PRD's quality contract
for probabilistic features
([references/ai_product_evals.md](references/ai_product_evals.md)).
6. **Never modify a gate you are judged by**; exhausted budgets escalate to a named human,
never report as success.
## Forcing-question library (grill-with-docs pattern)
One per turn, recommended answer, canon citation. Never run a sub-skill or start a loop
until the lane-defining decision is locked:
- **DISCOVERY lane**: "What is the single outcome this discovery serves, stated with a
number? Recommended: write it as the OST root first — opportunities without an outcome
are a feature factory. Canon: Torres, *Continuous Discovery Habits*; opportunity
solution trees (producttalk.org)."
- **PRIORITIZE lane**: "Does time sensitivity change this ranking — would delaying any
item a quarter erode its value? Recommended: if yes, run WSJF/cost-of-delay alongside
RICE and compare ranks; flag items whose rank flips on a one-step estimate change.
Canon: Reinertsen, *Principles of Product Development Flow*; SAFe WSJF false-precision
critique."
- **EXPERIMENT lane**: "What baseline rate and MDE justify this test's runtime?
Recommended: compute n first; if you can't reach it in 4 weeks, test a bigger lever.
Canon: statistical power analysis (experiment-designer)."
- **ANALYTICS lane**: "Is your North Star a leading indicator of value exchange, or
revenue/vanity? Recommended: leading value metric with an input tree. Canon: Amplitude,
*The North Star Playbook*."
- **STRATEGY lane**: "Are these OKRs outcomes or shipping lists? Recommended: outcomes —
output OKRs are the #1 operating-model failure. Canon: Cagan, *Transformed* (SVPG,
2024)."
- **BUILD lanes (spec-to-repo / saas-scaffolder)**: "Which validated assumption says this
should be built at all? Recommended: link the OST test that survived; building is the
most expensive way to test an idea. Canon: Torres; Bland, *Testing Business Ideas*."
## Assumptions
1. The user owns (or advises the owner of) the product decision.
2. Discovery data lives in the workspace as JSON logs — the loop is file-backed and
resumable; every tool ships `--sample` so the shape is visible first.
3. The four standalone plugins are installed alongside the bundle (the router still
routes to them by path if not).
## Non-goals
- Not the delivery loop — sprint/flow/Jira work routes to `project-management`.
- Not the generic loop engine — that is `engineering/agent-harness`; this orchestrator is
the product-domain adapter (router + discovery gates).
- Not campaign marketing — `marketing/landing` builds from-scratch marketing pages;
`landing-page-generator` here scaffolds product Next.js/TSX pages.
## Output artifacts
| Mode | Artifact |
|---|---|
| Route | Sub-skill's own artifact + ≤ 200-word digest with one canon-cited challenge |
| Discovery loop | `discovery_log.json` + cadence report + linted `ost.json` |
| Harness run | `.agent-harness/plan.json` + `state.json` + close handoff |
## Anti-patterns (do not)
- ❌ Run all 16 lanes "to be thorough" — route to one, digest, chain on confirmation
- ❌ Cite an OST that fails the linter, or promote a single-participant anecdote to insight
- ❌ Ship an AI feature whose PRD has no eval (golden set + rubric)
- ❌ Let the discovery streak die silently — DORMANT escalates by name
- ❌ Treat RICE as the only prioritization lens when deadlines dominate
## References
- [references/continuous_discovery_canon.md](references/continuous_discovery_canon.md) —
Torres, OST, assumption testing, JTBD switch interviews, story mapping
- [references/product_operating_model.md](references/product_operating_model.md) — Cagan
*Transformed*, North Star framework, PLG benchmarks, WSJF/ODI vs RICE
- [references/ai_product_evals.md](references/ai_product_evals.md) — evals-as-PRD, model
cards, evaluator-optimizer loops
- Loop engine: `engineering/agent-harness` · Loop vocabulary: `loop-library`

20
product-team/skills/product-skills/assets/sample_discovery_log.json Normal file
View file

@ -0,0 +1,20 @@
{
"_comment": "Continuous-discovery log shape — feed to scripts/discovery_cadence_tracker.py.",
"outcome": "increase paid conversion from 9% to 12% by Q4",
"interviews": [
{"date": "2026-05-05", "participant": "P1", "outcome_linked": true,
"assumptions_tested": ["users understand the trial limits"]},
{"date": "2026-05-12", "participant": "P2", "outcome_linked": true,
"assumptions_tested": []},
{"date": "2026-05-26", "participant": "P3", "outcome_linked": false,
"assumptions_tested": ["pricing page is the drop-off point"]},
{"date": "2026-06-02", "participant": "P4", "outcome_linked": true,
"assumptions_tested": ["annual plan framing increases upgrades"]}
],
"assumption_tests": [
{"date": "2026-05-15", "assumption": "users understand the trial limits",
"result": "invalidated"},
{"date": "2026-06-05", "assumption": "annual plan framing increases upgrades",
"result": "inconclusive"}
]
}

26
product-team/skills/product-skills/assets/sample_ost.json Normal file
View file

@ -0,0 +1,26 @@
{
"_comment": "Opportunity Solution Tree shape — feed to scripts/ost_linter.py. This sample deliberately contains one O2 violation (feature-phrased opportunity) and one O4 violation (untested solution).",
"outcome": {
"statement": "Increase week-4 retention from 22% to 30%",
"metric": "week-4 retention"
},
"opportunities": [
{
"statement": "New users can't tell whether setup worked",
"target": true,
"solutions": [
{"statement": "Post-setup verification checklist",
"tests": [{"assumption": "users abandon because they doubt setup succeeded", "type": "interview"}]},
{"statement": "Live sample-data preview after connect",
"tests": [{"assumption": "a working preview reduces first-week drop-off", "type": "prototype"}]}
]
},
{
"statement": "Add an onboarding wizard",
"solutions": [
{"statement": "Onboarding wizard v2", "tests": []}
]
}
],
"solutions": []
}

67
product-team/skills/product-skills/references/ai_product_evals.md Normal file
View file

@ -0,0 +1,67 @@
# AI Product Evals — the new PRD quality contract
The single most-demanded new PM competency of 2025–2026, and the biggest coverage gap
this domain had. For deterministic features the PRD's acceptance criteria are the quality
contract; for **probabilistic (AI) features, the eval is the contract** — encode what
"good" means as data + rubric *before* building, or you ship on vibes.
## Evals are the new PRD
The PM owns three artifacts per AI feature:
1. **Golden set** — a labeled collection of real inputs with expected-quality outputs,
covering every intent the feature claims to handle plus the known failure modes
(hallucination, refusal, off-topic, unsafe). Floor: enough examples per intent that a
regression is statistically visible, and the set grows from production incidents.
2. **Rubric** — the dimensions of "good" (accuracy, groundedness, tone, format,
safety), each with a pass criterion a grader (human or LLM-judge) can apply
consistently. Check grader consistency with inter-rater agreement (Cohen's kappa)
before trusting LLM-judge scores.
3. **Guardrail metrics** — the SLOs that page someone: hallucination rate ceiling,
refusal-rate band, latency/cost budgets.
Anti-pattern: "vibe check" launches — demo-driven quality assessment with no golden set,
no rubric, no regression gate. It is the AI equivalent of shipping without tests.
## Model/system cards
Enterprise and regulated buyers expect a model card documenting intended use,
out-of-scope use, eval data and results (disaggregated where bias matters), and
limitations (Mitchell et al.'s nine canonical sections; Anthropic/OpenAI system cards in
current practice). The PM owns the product-facing half: intended use, eval results,
limitations users will hit.
## The loop connection (evaluator-optimizer)
The same generator/critic loop that powers agent harnesses is what PM-owned evals feed:
the golden set + rubric become the evaluator's criteria, and Anthropic's guidance is
explicit that the evaluator-optimizer pattern pays off exactly "when there are clear
evaluation criteria and iterative refinement provides measurable value." Practically:
- The eval spec is the `done_when` of any agent-harness task that touches an AI feature.
- Eval runs are the locked evaluator — the feature loop may edit prompts/retrieval/
models, never the golden set it is judged by (autoresearch invariant).
- Experiment-designer's sample-size math applies to eval deltas too: a 2-point rubric
improvement on 30 examples is noise.
## Where this lands in the domain today
- `experiment-designer` — extend hypothesis gates to eval-delta hypotheses.
- `product-manager-toolkit` — PRD template gains an "Eval spec" section for AI features
(golden set size, rubric dimensions, guardrail SLOs, owner).
- `product-analytics` — guardrail metrics join the KPI tree as SLO-style entries.
## Sources
1. Lenny's Newsletter, "Beyond vibe checks: A PM's complete guide to evals" —
https://www.lennysnewsletter.com/p/beyond-vibe-checks-a-pms-complete
2. Braintrust, "Evals for PMs" — https://www.braintrust.dev/blog/evals-for-pms
3. Aakash Gupta, "AI Evals" — https://www.news.aakashg.com/p/ai-evals
4. Mitchell et al., "Model Cards for Model Reporting" (FAT* 2019) —
https://arxiv.org/abs/1810.03993
5. Anthropic, "Building Effective Agents" (evaluator-optimizer applicability) —
https://www.anthropic.com/research/building-effective-agents
6. Jacob Cohen, "A Coefficient of Agreement for Nominal Scales" (1960) — kappa as the
inter-rater agreement statistic
7. This repo: `engineering/autoresearch-agent` (locked evaluator), `engineering/self-eval`
(anti-inflation scoring)

71
product-team/skills/product-skills/references/continuous_discovery_canon.md Normal file
View file

@ -0,0 +1,71 @@
# Continuous Discovery Canon
The method layer behind `discovery_cadence_tracker.py` and `ost_linter.py`. The
2024–2026 discovery canon reframed discovery from a project phase into a **weekly
operating rhythm** with a structural artifact (the Opportunity Solution Tree) and a unit
of progress (the assumption test).
## The weekly habit (Torres)
Teresa Torres' definition of continuous discovery: the product trio (PM, designer,
engineer) has **at least weekly touchpoints with customers**, in pursuit of a desired
**outcome**, conducting **small research activities** (interviews, assumption tests).
Corollaries the tracker scores:
- **Cadence, not volume**: 4 interviews in one week then silence for a month is a broken
habit — hence the streak (30 pts) and week-coverage (30 pts) components.
- **Outcome-anchored**: interviews that don't tie back to the outcome drift into feature
tourism — hence the linkage component (20 pts).
- **Assumption tests are the throughput**: Torres' target rhythm resolves assumptions
continuously; piling up untested assumptions is discovery theater — hence the
throughput component (20 pts) and the untested-backlog gap.
## The Opportunity Solution Tree (why each lint rule exists)
- **O1 — one measurable outcome root**: the tree hangs from exactly one outcome, stated
with a metric and target. Multiple outcomes = multiple trees.
- **O2 — opportunities are needs, not features**: an opportunity is a customer need,
pain, or desire surfaced by research. "Add an onboarding wizard" is a solution wearing
an opportunity's clothes; the build-verb heuristic catches it.
- **O3 — compare ≥ 2 solutions per targeted opportunity**: Torres' compare-and-contrast
discipline; a single pet solution skips the decision.
- **O4 — every solution carries an assumption test**: untested solutions are opinions;
the test types (interview, prototype, smoke test, concierge) come from Bland's
desirability/viability/feasibility/usability mapping.
- **O5 — no orphan solutions**: a solution attached to no opportunity is the
feature-factory anti-pattern in its purest form.
## Assumption mapping & test sequencing (Bland)
Rank assumptions by **importance × evidence-weakness** and test the riskiest first
(leap-of-faith assumptions). Match test type to assumption class — desirability →
interview/smoke test; feasibility → spike/prototype; viability → pricing test/concierge.
This is `product-discovery/scripts/assumption_mapper.py`'s scoring model; the tracker's
untested-backlog gap feeds it.
## JTBD switch interviews (Moesta)
When interviews need depth, run the switch interview: reconstruct a real past purchase
timeline (first thought → passive looking → active looking → decision) and code the four
forces — push of the current situation, pull of the new solution, anxiety of the new,
habit of the present. Progress happens when push + pull outweigh anxiety + habit.
## Story mapping (Patton)
The bridge from a validated opportunity to a sliced backlog: backbone of activities
left-to-right, stories vertically, release slices horizontally — each slice an
end-to-end walking skeleton, never a vertical feature column.
## Sources
1. Teresa Torres, *Continuous Discovery Habits* (Product Talk LLC, 2021) and
https://www.producttalk.org/opportunity-solution-trees/
2. David J. Bland & Alexander Osterwalder, *Testing Business Ideas* (Wiley, 2019)
3. Bob Moesta, *Demand-Side Sales 101* (2020); Jobs-to-be-Done switch-interview practice
— https://jobstobedone.org/
4. Jeff Patton, *User Story Mapping* (O'Reilly, 2014)
5. Christian Rohrer, "When to Use Which User-Experience Research Methods", NN/g —
https://www.nngroup.com/articles/which-ux-research-methods/
6. Marty Cagan, *Inspired* (2nd ed., Wiley, 2018) — discovery/delivery separation
7. Product Talk, "The Product Operating Model and Continuous Discovery" —
https://www.producttalk.org/the-product-operating-model/

69
product-team/skills/product-skills/references/product_operating_model.md Normal file
View file

@ -0,0 +1,69 @@
# Product Operating Model, Metrics & Prioritization Brackets
The strategy layer behind the orchestrator's STRATEGY/ANALYTICS/PRIORITIZE forcing
questions. Three moves define the 2024–2026 canon: the product operating model as the
org-level frame, the North Star framework as the metrics spine, and prioritization as a
**bracket of frameworks** rather than RICE-for-everything.
## The product operating model (Cagan, *Transformed*, 2024)
The transformation agenda in three principles: **empowered teams** (problems to solve,
not features to build), **outcomes over output**, **innovation over predictability** —
elaborated as 20 first principles across how you build / solve problems / decide what to
work on. The tell-tale failures the orchestrator grills for: OKRs that are shipping
lists, roadmaps as commitments of output, teams measured on velocity instead of outcome.
## North Star framework (Amplitude)
A valid North Star Metric is (a) a **leading indicator** of sustainable business results,
(b) a measure of **value exchange** with the customer, (c) not revenue and not a vanity
count. It decomposes into an **input-metric tree** (breadth × depth × frequency ×
efficiency) that teams can actually move. AARRR remains the funnel taxonomy, but the
NSM + input tree is the strategy-to-analytics bridge product-analytics work should hang
from.
## PLG benchmark bands
Verdicts need bands, not vibes (medians from ProductLed/OpenView benchmark corpora,
2024–2025): signup→activation median ≈ 17% (best-in-class 33–50%+); free→paid median
≈ 9% (PQL-driven motions 25–30%). A funnel scorer without calibrated bands cannot say
"weak stage" honestly.
## Prioritization: bracket RICE, don't replace it
| Situation | Framework | Why |
|---|---|---|
| Steady-state backlog | **RICE** | Reach/impact/confidence/effort — cheap, comparable |
| Time sensitivity dominates (deadlines, market windows) | **WSJF / Cost of Delay** (Reinertsen) | RICE is time-blind; CoD/duration surfaces value erosion |
| Underserved-needs hunting | **Opportunity scoring** (Ulwick ODI) | importance + max(importance − satisfaction, 0) ranks unmet outcomes |
Two disciplines regardless of framework: (1) **name which framework and why** before
scoring; (2) **sensitivity-check the ranking** — perturb each estimate one step and flag
items whose rank flips (the documented WSJF false-precision failure; SAFe's own critics'
point). `rice_prioritizer.py` covers lane 1; lanes 2–3 are scored by hand against the
formulas here until dedicated tools land.
## Event taxonomy governance (PostHog/Amplitude-era)
Analytics rot starts at instrumentation: enforce snake_case, present-tense verb
allowlists, object_verb ordering, compact event sets, and tracking-plan review before
new events ship. A taxonomy with near-duplicate events ("signup", "sign_up",
"user_signed_up") cannot support any metric above it.
## Sources
1. Marty Cagan (SVPG), *Transformed: Moving to the Product Operating Model* (Wiley,
2024); https://www.svpg.com/the-product-operating-model-an-introduction/
2. Amplitude, *The North Star Playbook* —
https://amplitude.com/books/north-star/about-north-star-framework
3. ProductLed, "Product-Led Growth Benchmarks" —
https://productled.com/blog/product-led-growth-benchmarks; OpenView PLG benchmarks —
https://openviewpartners.com/blog/your-guide-to-product-led-growth-benchmarks/
4. Don Reinertsen, *The Principles of Product Development Flow* (Celeritas, 2009) — cost
of delay; SAFe WSJF — https://framework.scaledagile.com/wsjf
5. Anthony Ulwick, *What Customers Want* (McGraw-Hill, 2005) — Outcome-Driven Innovation
opportunity algorithm (strategyn.com)
6. Jason Yip, "Problems I have with SAFe-style WSJF" —
https://jchyip.medium.com/problems-i-have-with-safe-style-wsjf-772df2beaf02
7. PostHog, product analytics best practices —
https://posthog.com/docs/product-analytics/best-practices

183
product-team/skills/product-skills/scripts/discovery_cadence_tracker.py Normal file
View file

@ -0,0 +1,183 @@
#!/usr/bin/env python3
"""discovery_cadence_tracker.py — score a team's continuous-discovery habit.
Operationalizes Teresa Torres' continuous-discovery canon (weekly customer
touchpoints, outcome-first framing, assumption tests as the unit of progress) as a
deterministic recurring loop: feed it the discovery log each week (Observe), read the
named gaps (Choose), run the next interview or assumption test (Act), re-run the
tracker (Verify), and keep the streak alive (Repeat). The health score is the loop's
acceptance gate — a subagent can branch on it mechanically.
Input JSON (see --sample):
{"outcome": "increase paid conversion from 9% to 12% by Q4",
"interviews": [{"date": "YYYY-MM-DD", "participant": str,
"outcome_linked": bool, "assumptions_tested": [str]}],
"assumption_tests": [{"date": "YYYY-MM-DD", "assumption": str,
"result": "validated|invalidated|inconclusive"}]}
Scoring (0–100): weekly streak 30 · week coverage 30 · outcome linkage 20 ·
assumption-test throughput 20. Verdicts: HEALTHY >= 70 · AT-RISK 40–69 · DORMANT < 40.
Exit codes: 0 scored · 2 unreadable input · 5 insufficient history (< 2 interviews —
start the habit before measuring it). Deterministic: the analysis date defaults to
the newest date in the log, never the wall clock (override with --as-of).
Stdlib only.
"""
import argparse
import json
import sys
from datetime import date, timedelta
SAMPLE_LOG = {
"outcome": "increase paid conversion from 9% to 12% by Q4",
"interviews": [
{"date": "2026-05-05", "participant": "P1", "outcome_linked": True,
"assumptions_tested": ["users understand the trial limits"]},
{"date": "2026-05-12", "participant": "P2", "outcome_linked": True,
"assumptions_tested": []},
{"date": "2026-05-26", "participant": "P3", "outcome_linked": False,
"assumptions_tested": ["pricing page is the drop-off point"]},
{"date": "2026-06-02", "participant": "P4", "outcome_linked": True,
"assumptions_tested": ["annual plan framing increases upgrades"]},
],
"assumption_tests": [
{"date": "2026-05-15", "assumption": "users understand the trial limits",
"result": "invalidated"},
{"date": "2026-06-05", "assumption": "annual plan framing increases upgrades",
"result": "inconclusive"},
],
}
def parse_date(value):
try:
return date.fromisoformat(str(value)[:10])
except (TypeError, ValueError):
return None
def week_of(d: date):
return d.isocalendar()[:2]
def analyze(log: dict, as_of: date) -> dict:
interviews = [
{**i, "date": parse_date(i.get("date"))}
for i in log.get("interviews", [])
]
interviews = [i for i in interviews if i["date"] and i["date"] <= as_of]
tests = [
{**t, "date": parse_date(t.get("date"))}
for t in log.get("assumption_tests", [])
]
tests = [t for t in tests if t["date"] and t["date"] <= as_of]
interview_weeks = {week_of(i["date"]) for i in interviews}
first = min(i["date"] for i in interviews)
total_weeks = max(((as_of - first).days // 7) + 1, 1)
# Streak: consecutive weeks with >= 1 interview, counting back from as_of's week.
streak, cursor = 0, as_of
while week_of(cursor) in interview_weeks:
streak += 1
cursor -= timedelta(days=7)
coverage = len(interview_weeks) / total_weeks
linked = sum(1 for i in interviews if i.get("outcome_linked"))
linkage = linked / len(interviews)
resolved = sum(1 for t in tests if t.get("result") in ("validated", "invalidated"))
# Torres cadence target: >= 1 resolved assumption test per 2 weeks.
test_target = max(total_weeks / 2, 1)
throughput = min(resolved / test_target, 1.0)
score = round(
min(streak / 4, 1.0) * 30 + coverage * 30 + linkage * 20 + throughput * 20, 1)
verdict = "HEALTHY" if score >= 70 else ("AT-RISK" if score >= 40 else "DORMANT")
gaps = []
if streak == 0:
gaps.append("no interview in the current week — the weekly habit is broken "
"(Torres: touchpoints are a cadence, not a project phase)")
if coverage < 0.75:
missed = total_weeks - len(interview_weeks)
gaps.append(f"{missed} of {total_weeks} weeks had zero customer touchpoints")
if linkage < 0.8:
gaps.append(f"only {linked}/{len(interviews)} interviews tie back to the outcome — "
"re-anchor the interview guide on the outcome")
if throughput < 1.0:
gaps.append(f"{resolved} resolved assumption tests vs a target of "
f"{int(test_target)} — assumptions are piling up untested")
untested = {a for i in interviews for a in i.get("assumptions_tested", [])}
tested = {t.get("assumption") for t in tests}
backlog = sorted(untested - tested)
if backlog:
gaps.append(f"assumptions surfaced but never tested: {'; '.join(backlog[:3])}")
return {
"outcome": log.get("outcome", ""),
"as_of": as_of.isoformat(),
"weeks_observed": total_weeks,
"interviews": len(interviews),
"distinct_participants": len({i.get("participant") for i in interviews}),
"weekly_streak": streak,
"week_coverage_pct": round(coverage * 100, 1),
"outcome_linkage_pct": round(linkage * 100, 1),
"assumption_tests_resolved": resolved,
"health_score": score,
"verdict": verdict,
"gaps": gaps,
"next_loop_action": (gaps[0] if gaps else
"cadence healthy — book next week's touchpoint before this one ends"),
}
def main() -> int:
ap = argparse.ArgumentParser(
description="Score a continuous-discovery log for cadence health (Torres canon).")
ap.add_argument("--input", help="Path to the discovery log JSON ('-' for stdin).")
ap.add_argument("--as-of", help="Analysis date YYYY-MM-DD (default: newest date in log).")
ap.add_argument("--output", choices=["json", "human"], default="json")
ap.add_argument("--sample", action="store_true",
help="Analyze a built-in sample log and exit 0.")
args = ap.parse_args()
if args.sample:
log = SAMPLE_LOG
elif args.input:
try:
log = json.load(sys.stdin if args.input == "-"
else open(args.input, encoding="utf-8"))
except (OSError, ValueError) as exc:
print(f"ERROR: cannot read log: {exc}", file=sys.stderr)
return 2
else:
ap.error("--input is required (or use --sample)")
interview_dates = [d for d in
(parse_date(i.get("date")) for i in log.get("interviews", [])) if d]
all_dates = interview_dates + [
d for d in (parse_date(t.get("date")) for t in log.get("assumption_tests", [])) if d]
as_of = parse_date(args.as_of) if args.as_of else (max(all_dates) if all_dates else None)
if as_of is None or sum(1 for d in interview_dates if d <= as_of) < 2:
print("REFUSED: fewer than 2 dated interviews on or before the analysis date — "
"there is no cadence to measure yet. Book the first two weekly touchpoints "
"(or widen --as-of), then re-run.", file=sys.stderr)
return 5
report = analyze(log, as_of)
if args.output == "json":
print(json.dumps(report, indent=2))
else:
print(f"Discovery health: {report['health_score']}/100 ({report['verdict']})")
print(f"Streak: {report['weekly_streak']} wk · coverage "
f"{report['week_coverage_pct']}% · linkage {report['outcome_linkage_pct']}% "
f"· tests resolved {report['assumption_tests_resolved']}")
for g in report["gaps"]:
print(f" gap: {g}")
print(f"Next: {report['next_loop_action']}")
return 0
if __name__ == "__main__":
sys.exit(main())

162
product-team/skills/product-skills/scripts/ost_linter.py Normal file
View file

@ -0,0 +1,162 @@
#!/usr/bin/env python3
"""ost_linter.py — structural linter for Opportunity Solution Trees.
The OST (Torres) is the structural artifact of modern product discovery:
outcome → opportunities → solutions → assumption tests. Teams don't need prose
advice about trees — they need their actual tree checked. This linter enforces the
structural rules deterministically, so an agent loop can use "ost_linter exits 0"
as the acceptance gate before a roadmap or experiment plan is allowed to cite the
tree.
Rules:
O1 exactly one outcome root, phrased measurably (contains a number, or a
`metric` field is present)
O2 opportunities are needs/pains/desires, not features — flag statements that
start with build-verbs (add/build/implement/create/integrate/launch/ship)
O3 every opportunity marked "target": true has >= 2 solutions under
consideration (compare-and-contrast, never a single pet solution)
O4 every solution carries >= 1 assumption test
O5 no orphan solutions attached directly to the outcome — a solution without an
opportunity is the feature-factory anti-pattern
Input JSON (see --sample):
{"outcome": {"statement": str, "metric": str?},
"opportunities": [{"statement": str, "target": bool?,
"children": [<nested opportunities>]?,
"solutions": [{"statement": str,
"tests": [{"assumption": str, "type": str}]}]}],
"solutions": [ ... ] # anything here is an O5 violation by definition
}
Exit codes: 0 clean (warnings allowed) · 2 violations found · 3 unreadable input.
Exception: `--sample` always exits 0 — it is a smoke test, and the bundled tree
deliberately contains one O2 and one O4 violation so the report output is visible.
Stdlib only, deterministic.
"""
import argparse
import json
import re
import sys
BUILD_VERBS = re.compile(
r"^\s*(add|build|implement|create|integrate|launch|ship|develop|make)\b", re.I)
SAMPLE_TREE = {
"outcome": {"statement": "Increase week-4 retention from 22% to 30%",
"metric": "week-4 retention"},
"opportunities": [
{"statement": "New users can't tell whether setup worked",
"target": True,
"solutions": [
{"statement": "Post-setup verification checklist",
"tests": [{"assumption": "users abandon because they doubt setup succeeded",
"type": "interview"}]},
{"statement": "Live sample-data preview after connect",
"tests": [{"assumption": "a working preview reduces first-week drop-off",
"type": "prototype"}]},
]},
{"statement": "Add an onboarding wizard",
"solutions": [
{"statement": "Onboarding wizard v2", "tests": []},
]},
],
"solutions": [],
}
def walk_opportunities(nodes, path="opportunities"):
for idx, node in enumerate(nodes or []):
here = f"{path}[{idx}]"
yield here, node
yield from walk_opportunities(node.get("children"), here + ".children")
def lint(tree: dict):
violations, warnings = [], []
outcome = tree.get("outcome")
if not isinstance(outcome, dict) or not str(outcome.get("statement", "")).strip():
violations.append({"rule": "O1", "where": "outcome",
"problem": "missing outcome root — an OST hangs from exactly one outcome"})
else:
stmt = outcome.get("statement", "")
if not (re.search(r"\d", stmt) or str(outcome.get("metric", "")).strip()):
violations.append({"rule": "O1", "where": "outcome",
"problem": f"outcome is not measurable: '{stmt[:80]}' — "
"state a metric and a target number"})
opp_count = 0
for where, opp in walk_opportunities(tree.get("opportunities")):
opp_count += 1
stmt = str(opp.get("statement", ""))
if BUILD_VERBS.match(stmt):
violations.append({"rule": "O2", "where": where,
"problem": f"opportunity phrased as a feature: '{stmt[:80]}' — "
"rewrite as the customer need/pain/desire behind it"})
solutions = opp.get("solutions") or []
if opp.get("target") and len(solutions) < 2:
violations.append({"rule": "O3", "where": where,
"problem": f"targeted opportunity has {len(solutions)} solution(s) — "
"Torres: compare >= 2 candidate solutions, never one pet idea"})
for sidx, sol in enumerate(solutions):
if not (sol.get("tests") or []):
violations.append({"rule": "O4", "where": f"{where}.solutions[{sidx}]",
"problem": f"solution '{str(sol.get('statement', ''))[:60]}' has no "
"assumption test — untested solutions are opinions"})
orphans = tree.get("solutions") or []
for sidx, sol in enumerate(orphans):
violations.append({"rule": "O5", "where": f"solutions[{sidx}]",
"problem": f"orphan solution '{str(sol.get('statement', ''))[:60]}' attached to "
"no opportunity — the feature-factory anti-pattern"})
if opp_count == 0 and not violations:
warnings.append("tree has an outcome but zero opportunities — map the opportunity "
"space before jumping to solutions")
return violations, warnings, opp_count
def main() -> int:
ap = argparse.ArgumentParser(
description="Lint an Opportunity Solution Tree for structural discipline (Torres canon).")
ap.add_argument("--input", help="Path to the OST JSON ('-' for stdin).")
ap.add_argument("--output", choices=["json", "human"], default="json")
ap.add_argument("--sample", action="store_true",
help="Lint a built-in sample tree (contains one O2 and one O4 violation) and exit 0.")
args = ap.parse_args()
if args.sample:
tree = SAMPLE_TREE
elif args.input:
try:
tree = json.load(sys.stdin if args.input == "-"
else open(args.input, encoding="utf-8"))
except (OSError, ValueError) as exc:
print(f"ERROR: cannot read tree: {exc}", file=sys.stderr)
return 3
else:
ap.error("--input is required (or use --sample)")
violations, warnings, opp_count = lint(tree)
result = {
"opportunities": opp_count,
"violations": violations,
"warnings": warnings,
"verdict": "STRUCTURALLY-SOUND" if not violations else "NEEDS-REWORK",
}
if args.output == "json":
print(json.dumps(result, indent=2))
else:
print(f"Verdict: {result['verdict']} ({opp_count} opportunities, "
f"{len(violations)} violation(s))")
for v in violations:
print(f" [{v['rule']}] {v['where']}: {v['problem']}")
for w in warnings:
print(f" (warn) {w}")
if args.sample:
return 0
return 0 if not violations else 2
if __name__ == "__main__":
sys.exit(main())

207
product-team/skills/product-skills/scripts/product_goal_router.py Normal file
View file

@ -0,0 +1,207 @@
#!/usr/bin/env python3
"""product_goal_router.py — deterministic lane classifier for the product-team domain.
Scores a product goal/inquiry against the 12 bundled sub-skill lanes plus the 4
standalone product-team plugins (same two-signal threshold discipline as the
research-ops / commercial / markdown-html orchestrators). Emits a routing decision
an agent can branch on mechanically.
Exit codes:
0 confident route emitted (route_to set)
2 ambiguous — ask ONE clarifying question naming the top two lanes
3 no signal — do not guess; ask the user to restate the goal
Stdlib only. Deterministic: same text in, same route out.
"""
import argparse
import json
import sys
SIGNALS = {
"PRIORITIZE": {
"skill": "product-manager-toolkit",
"path": "product-team/skills/product-manager-toolkit",
"keywords": ["prioritize", "rice", "backlog ranking", "feature ranking",
"prd", "product requirements", "interview synthesis", "wsjf",
"cost of delay"],
},
"STRATEGY": {
"skill": "product-strategist",
"path": "product-team/skills/product-strategist",
"keywords": ["okr", "objective", "strategy", "quarterly planning",
"north star", "vision", "alignment"],
},
"UX": {
"skill": "ux-researcher-designer",
"path": "product-team/skills/ux-researcher-designer",
"keywords": ["persona", "journey map", "usability", "user research",
"research synthesis", "interview guide"],
},
"DESIGN_SYSTEM": {
"skill": "ui-design-system",
"path": "product-team/skills/ui-design-system",
"keywords": ["design token", "component spec", "design system",
"wcag", "contrast", "typography scale"],
},
"COMPETITIVE": {
"skill": "competitive-teardown",
"path": "product-team/skills/competitive-teardown",
"keywords": ["competitor", "competitive", "teardown", "pricing matrix",
"market position", "feature comparison"],
},
"ANALYTICS": {
"skill": "product-analytics",
"path": "product-team/skills/product-analytics",
"keywords": ["retention", "cohort", "funnel", "kpi", "activation",
"churn", "aarrr", "north star metric", "tracking plan",
"event taxonomy"],
},
"EXPERIMENT": {
"skill": "experiment-designer",
"path": "product-team/skills/experiment-designer",
"keywords": ["a/b test", "ab test", "experiment", "sample size",
"hypothesis", "mde", "statistical power", "eval"],
},
"DISCOVERY": {
"skill": "product-discovery",
"path": "product-team/skills/product-discovery",
"keywords": ["discovery", "opportunity", "assumption", "opportunity solution tree",
"ost", "continuous discovery", "customer interview cadence",
"jtbd", "jobs to be done"],
},
"ROADMAP": {
"skill": "roadmap-communicator",
"path": "product-team/skills/roadmap-communicator",
"keywords": ["roadmap", "release notes", "changelog", "launch comms",
"now next later"],
},
"SPEC_TO_REPO": {
"skill": "spec-to-repo",
"path": "product-team/skills/spec-to-repo",
"keywords": ["spec to repo", "scaffold from spec", "build from spec",
"generate the repo", "turn this spec into"],
},
"LANDING": {
"skill": "landing-page-generator",
"path": "product-team/skills/landing-page-generator",
"keywords": ["landing page", "hero section", "waitlist page", "marketing page"],
},
"SAAS_SCAFFOLD": {
"skill": "saas-scaffolder",
"path": "product-team/skills/saas-scaffolder",
"keywords": ["saas boilerplate", "saas skeleton", "bootstrap a saas",
"auth and billing", "stripe integration scaffold"],
},
# Standalone product-team plugins (packaged separately, routable all the same)
"STORIES": {
"skill": "agile-product-owner",
"path": "product-team/agile-product-owner/skills/agile-product-owner",
"keywords": ["user story", "user stories", "acceptance criteria", "invest",
"epic breakdown", "sprint capacity", "story splitting"],
},
"HIG": {
"skill": "apple-hig-expert",
"path": "product-team/apple-hig-expert/skills/apple-hig-expert",
"keywords": ["hig", "human interface guidelines", "ios design", "liquid glass",
"tap target", "apple design"],
},
"CODE_TO_PRD": {
"skill": "code-to-prd",
"path": "product-team/code-to-prd/skills/code-to-prd",
"keywords": ["reverse engineer", "code to prd", "prd from code",
"document this codebase as a prd", "existing app into a prd"],
},
"SUMMARIZE": {
"skill": "research-summarizer",
"path": "product-team/research-summarizer/skills/research-summarizer",
"keywords": ["summarize this paper", "summarize research", "citation extraction",
"compare these papers", "article summary"],
},
}
SAMPLE_GOAL = ("we keep shipping features nobody uses — I want a weekly discovery "
"habit and an opportunity solution tree before the next roadmap review")
def score(text: str) -> dict:
low = text.lower()
scores, hits = {}, {}
for lane, spec in SIGNALS.items():
matched = [kw for kw in spec["keywords"] if kw in low]
scores[lane] = len(matched)
hits[lane] = matched
return {"scores": scores, "hits": hits}
def decide(scores: dict) -> dict:
ranked = sorted(scores.items(), key=lambda kv: (-kv[1], kv[0]))
(top_lane, top), (second_lane, second) = ranked[0], ranked[1]
if top == 0:
return {"decision": "NO_SIGNAL", "exit": 3}
if top >= 2 and (second == 0 or top >= 2 * second):
return {"decision": "ROUTE", "lane": top_lane, "exit": 0}
candidates = [top_lane] + ([second_lane] if second > 0 else [])
return {"decision": "ASK", "candidates": candidates, "exit": 2}
def main() -> int:
ap = argparse.ArgumentParser(
description="Deterministic lane router for product-team goals.")
src = ap.add_mutually_exclusive_group()
src.add_argument("--text", help="Goal / inquiry text to classify.")
src.add_argument("--input", help="Read goal text from a file ('-' for stdin).")
ap.add_argument("--output", choices=["json", "human"], default="json")
ap.add_argument("--sample", action="store_true",
help="Classify a built-in sample goal and exit.")
args = ap.parse_args()
if args.sample:
text = SAMPLE_GOAL
elif args.text:
text = args.text
elif args.input:
text = (sys.stdin.read() if args.input == "-"
else open(args.input, encoding="utf-8").read())
else:
ap.error("one of --text, --input, or --sample is required")
result = score(text)
verdict = decide(result["scores"])
out = {
"goal": text.strip()[:300],
"scores": {k: v for k, v in result["scores"].items() if v},
"decision": verdict["decision"],
}
if verdict["decision"] == "ROUTE":
lane = verdict["lane"]
out["route_to"] = SIGNALS[lane]["skill"]
out["skill_path"] = SIGNALS[lane]["path"]
out["matched_signals"] = result["hits"][lane]
elif verdict["decision"] == "ASK":
out["candidates"] = [
{"lane": lane, "skill": SIGNALS[lane]["skill"], "score": result["scores"][lane]}
for lane in verdict["candidates"]
]
out["instruction"] = ("Ask ONE clarifying question naming both candidate lanes, "
"with a recommended answer. Never guess silently.")
else:
out["instruction"] = ("No lane signal. Ask the user to restate the goal with the "
"deliverable named. Do not route on fuzz.")
if args.output == "json":
print(json.dumps(out, indent=2))
else:
print(f"Decision: {out['decision']}")
if "route_to" in out:
print(f"Route to: {out['route_to']} ({out['skill_path']})")
print(f"Signals: {', '.join(out['matched_signals'])}")
elif "candidates" in out:
names = " vs ".join(c["skill"] for c in out["candidates"])
print(f"Ambiguous: {names} — ask one clarifying question.")
else:
print("No signal — ask the user to restate the goal.")
return verdict["exit"]
if __name__ == "__main__":
sys.exit(main())

23
product-team/skills/ux-researcher-designer/scripts/persona_generator.py
View file

@ -541,10 +541,25 @@ def create_sample_user_data():
]
def main():
import sys
import argparse
parser = argparse.ArgumentParser(
description="Generate a research-backed persona from bundled sample data.")
parser.add_argument("format", nargs="?", choices=["json", "human"], default="human",
help="Output format (default: human).")
parser.add_argument("--output", dest="output_flag", choices=["json", "human"],
help="Output format (flag form, overrides the positional).")
parser.add_argument("--seed", type=int, default=42,
help="RNG seed for deterministic persona names (default: 42).")
parser.add_argument("--sample", action="store_true",
help="Generate the bundled sample persona and exit 0 "
"(same as the default run; kept for harness smoke tests).")
args = parser.parse_args()
output = args.output_flag or args.format
random.seed(args.seed)
generator = PersonaGenerator()
# Create sample data
user_data = create_sample_user_data()
@ -561,7 +576,7 @@ def main():
persona = generator.generate_persona_from_data(user_data, interview_insights)
# Output
if len(sys.argv) > 1 and sys.argv[1] == 'json':
if output == 'json':
print(json.dumps(persona, indent=2))
else:
print(generator.format_persona_output(persona))

4
project-management/.claude-plugin/plugin.json
View file

@ -1,7 +1,7 @@
{
"name": "pm-skills",
"description": "9 project management skills: senior PM, scrum master, Jira expert, Confluence expert, Atlassian admin, template scaffolder, and Atlassian MCP-bundled (Remote SSE) integration. Agent skill and plugin for Claude Code, Codex, Gemini CLI, Cursor, OpenClaw.",
"version": "2.9.0",
"description": "9 project management skills: pm-skills fork-orchestrator with agentic delivery loop (deterministic 8-lane router, Jira MCP snapshot bridge to flow metrics/Monte Carlo forecasts, delegation-governance gate), senior PM, scrum master, Jira expert, Confluence expert, Atlassian admin, template scaffolder, meeting analyzer, team communications — plus bundled Atlassian Remote MCP (SSE) integration. Agent skill and plugin for Claude Code, Codex, Gemini CLI, Cursor, OpenClaw.",
"version": "2.11.1",
"author": {
"name": "Alireza Rezvani",
"url": "https://alirezarezvani.com"

56
project-management/CLAUDE.md
View file

@ -1,22 +1,50 @@
# Project Management Skills - Claude Code Guidance
This guide covers the 9 production-ready project management skills, 12 Python automation tools, and bundled Atlassian Remote MCP integration (`.mcp.json` ships with the plugin — OAuth handled by Claude Code, no env vars required).
This guide covers the 9 production-ready project management skills, 15 Python automation tools, and bundled Atlassian Remote MCP integration (`.mcp.json` ships with the plugin — OAuth handled by Claude Code, no env vars required).
## PM Skills Overview
**Available Skills:**
1. **senior-pm/** - Portfolio health, risk analysis, resource planning (3 scripts)
2. **scrum-master/** - Sprint health, velocity forecasting, retrospectives (3 scripts)
3. **jira-expert/** - JQL building, workflow validation (2 scripts)
4. **confluence-expert/** - Space structure, content auditing (2 scripts)
5. **atlassian-admin/** - Permission auditing (1 script)
6. **atlassian-templates/** - Template scaffolding (1 script)
1. **pm-skills/** - Domain orchestrator (`context: fork`) + agentic delivery loop (3 scripts: goal router, Jira snapshot bridge, delivery loop gate)
2. **senior-pm/** - Portfolio health, risk analysis, resource planning (3 scripts)
3. **scrum-master/** - Sprint health, velocity forecasting, retrospectives (3 scripts)
4. **jira-expert/** - JQL building, workflow validation (2 scripts)
5. **confluence-expert/** - Space structure, content auditing (2 scripts)
6. **atlassian-admin/** - Permission auditing (1 script)
7. **atlassian-templates/** - Template scaffolding (1 script)
8. **meeting-analyzer/** - Meeting transcript behavioral analysis (prompt-driven; scripts are follow-up work)
9. **team-communications/** - 3P updates, newsletters, FAQs (reference-driven)
**Total Tools:** 12 Python automation tools
**Agent:** cs-project-manager (orchestrates all 6 skills)
**Slash Commands:** 3 (/sprint-health, /project-health, /retro)
**Total Tools:** 15 Python automation tools
**Agents:** 2 — cs-pm-orchestrator (routing + delivery loop) and cs-project-manager (legacy per-skill orchestration)
**Slash Commands:** 6 (/cs:pm, /cs:grill-pm, /cs:pm-loop, /sprint-health, /project-health, /retro)
**Key Feature:** Atlassian MCP Server integration for direct Jira/Confluence operations
## Orchestrator & Delivery Loop (pm-skills)
`skills/pm-skills/` is the domain's `context: fork` orchestrator and agent harness adapter:
```bash
# Route a PM goal deterministically (exit 0 route / 2 ask / 3 no signal)
python3 skills/pm-skills/scripts/pm_goal_router.py --text "our sprints feel off"
# Bridge a saved searchJiraIssuesUsingJql result into analyzable inputs
python3 skills/pm-skills/scripts/jira_snapshot_bridge.py --input snapshot.json --to flow --forecast 20
python3 skills/pm-skills/scripts/jira_snapshot_bridge.py --input snapshot.json --to sprint > sprint_data.json
python3 skills/scrum-master/scripts/velocity_analyzer.py sprint_data.json
# Gate agent-executed delivery loops (G1 human owner … G6 exhausted budget = escalation)
python3 skills/pm-skills/scripts/delivery_loop_gate.py --plan plan.json --mode plan # exit 2 = blocked
python3 skills/pm-skills/scripts/delivery_loop_gate.py --plan plan.json --mode close # exit 4 = refused
```
Multi-task goals compile through the repo-wide harness
(`engineering/agent-harness` with the `project-management.json` manifest). Hard rules:
agents contribute, humans own; forecasts are Monte Carlo ranges, never dates; exhausted
budgets escalate — never reported as success. The five reusable PM loops (sprint-flow,
health, retro-action, RAID-hygiene, comms) are documented in
`skills/pm-skills/references/pm_loop_playbook.md`.
## Atlassian MCP Integration
**Purpose:** Direct integration with Jira and Confluence via Model Context Protocol (MCP)
@ -179,8 +207,8 @@ python atlassian-templates/scripts/template_scaffolder.py meeting-notes
---
**Last Updated:** June 10, 2026
**Skills Deployed:** 9/9 PM skills production-ready
**Total Tools:** 12 Python automation tools
**Agent:** cs-project-manager | **Commands:** 3
**Last Updated:** July 3, 2026
**Skills Deployed:** 9/9 PM skills production-ready (pm-skills is now a fork-orchestrator + delivery loop)
**Total Tools:** 15 Python automation tools
**Agents:** cs-pm-orchestrator, cs-project-manager | **Commands:** 6
**Integration:** Atlassian Remote MCP Server (bundled via `.mcp.json`) for Jira/Confluence automation

77
project-management/agents/cs-pm-orchestrator.md Normal file
View file

@ -0,0 +1,77 @@
---
name: cs-pm-orchestrator
description: Flow-first delivery lead. Routes project-management inquiries (sprint/velocity, portfolio health, Jira/JQL, Confluence, Atlassian admin, templates, meetings, comms) to the right sub-skill via the pm-skills orchestrator, and drives delivery goals through bounded agentic loops with machine-checkable gates. Forks context to keep heavy intake (Jira snapshots, retro logs, transcripts) out of the parent thread. Signature forcing question — "What single observable outcome means DONE, and which command proves it?"
tools: Read, Write, Edit, Glob, Grep, Bash, Skill
model: sonnet
---
# PM Orchestrator
You are a flow-first delivery lead. You measure before you forecast, derive health
instead of accepting self-reported green, and you never let a loop close on optimism.
Agents contribute; humans own — every task you plan names a human owner, and every
acceptance criterion is a command or a threshold.
## Voice
**"What single observable outcome means DONE, and which command proves it?"**
The trap you protect against: verification theater — status set to Done with no
evidence, forecasts stated as dates, watermelon projects reported green while aging WIP
rots.
## Your 8 lanes
| Lane | Skill | Signals |
|---|---|---|
| HEALTH | senior-pm | portfolio, risk EMV, capacity, exec report |
| SPRINT | scrum-master | velocity, retro, ceremonies, flow, forecast |
| JIRA | jira-expert | JQL, workflows, boards, automation |
| CONFLUENCE | confluence-expert | spaces, page trees, content audits |
| ADMIN | atlassian-admin | users, permissions, SSO |
| TEMPLATES | atlassian-templates | blueprints, storage-format scaffolds |
| MEETINGS | meeting-analyzer | transcripts, talk time, action items |
| COMMS | team-communications | 3P updates, newsletters, FAQs |
## Routing logic
1. Run `python3 project-management/skills/pm-skills/scripts/pm_goal_router.py --text "<goal>"`.
2. Exit 0 → load the routed skill's SKILL.md, follow its workflow in the forked context.
3. Exit 2 → ask ONE clarifying question naming the candidates, with a recommended answer.
4. Exit 3 → ask the user to restate the goal with the deliverable named. Never guess.
## How you communicate (Matt Pocock grill discipline)
One question per turn; always recommend; explore the workspace before asking (a saved
Jira snapshot or retro log resolves the lane silently); depth-first on multi-lane
inquiries; never silently chain. Digest ≤ 200 words: what was analyzed, top 3 findings
(canon-cited), top 3 next actions (named human owner), artifact path, one grill
challenge.
Hard outputs:
- Flow numbers come from `jira_snapshot_bridge.py` on real snapshot data — never from
memory or hand-typed estimates.
- Forecasts are Monte Carlo percentile ranges (p50/p70/p85/p95), never single dates.
- Loop plans pass `delivery_loop_gate.py --mode plan` (exit 0) before execution and
`--mode close` (exit 0) before you report done.
## Anti-patterns
- ❌ Route to two skills at once, or run all 8 "to be thorough"
- ❌ Accept "make our delivery better" — grill until the outcome and its proof command are
named
- ❌ Transition Jira issues to Done, change permissions, or delete anything inside a loop
without the named human approver
- ❌ Report an exhausted attempt/iteration budget as success
## When to escalate
- What-to-build questions → `product-team` (cs-product-orchestrator)
- Internal-ops process mapping → `business-operations`
- Generic loop mechanics / other domains → `engineering/agent-harness` harness-runner
- Regulatory/compliance delivery → `ra-qm-team`
## Available commands
`/cs:pm <inquiry>` (router) · `/cs:grill-pm <plan>` (grill first) · `/cs:pm-loop <goal>`
(delivery loop) · plus the domain's `/sprint-health`, `/project-health`, `/retro`.

57
project-management/commands/cs-grill-pm.md Normal file
View file

@ -0,0 +1,57 @@
---
description: Matt Pocock-style interrogation of a delivery plan against the PM canon (Kanban Guide 2025, Vacanti, DORA 2025, EBM, Klein, GitLab async-first). One forcing question per turn with a recommended answer; refuses to invoke any sub-skill or start a loop until the lane-defining decisions are locked. Use before running /cs:pm or /cs:pm-loop on a fuzzy plan.
argument-hint: "<delivery plan, goal, or status quo to interrogate>"
---
# /cs:grill-pm — grill a delivery plan before running it
Interrogate this plan — do not execute anything yet:
**$ARGUMENTS**
Five rules (preserved from Matt Pocock, MIT): one question per turn · always give a
recommended answer · explore the workspace before asking · walk the decision tree
depth-first · track answered questions and their dependencies.
## Decision tree
- **Branch 1 — Outcome**: "What single observable outcome means DONE, and which command
proves it? Recommended: a named artifact + a command that exits 0 against it. Canon:
agent-harness verifier's law."
- **Branch 2 — Measurement**: "Are you measuring flow before forecasting? Recommended:
run `jira_snapshot_bridge.py --to flow` first — WIP, throughput, cycle time, age.
Canon: Kanban Guide (May 2025) four mandatory measures."
- **Branch 3 — Forecast honesty**: "Is any date in this plan a single-point promise?
Recommended: replace with Monte Carlo p50/p85 ranges; refuse forecasts on < 10
completed items. Canon: Vacanti, *When Will It Be Done?*"
- **Branch 4 — Ownership**: "For every task an agent will execute: who is the human owner
and who reviews? Recommended: name both now; `delivery_loop_gate.py` will refuse the
plan otherwise. Canon: Linear agents model; Atlassian Rovo audit discipline."
- **Branch 5 — Risk**: "Have you run a pre-mortem on this plan? Recommended: 30 minutes,
'it's six months later and this failed — why?'; convert top clusters to owned risks.
Canon: Klein, HBR 2007."
- **Branch 6 — Budgets**: "What are the retry and iteration caps, and who reviews
escalations? Recommended: 3 attempts/task, 12 iterations/goal, a named human. Canon:
loop-library terminal states."
Per-turn output format:
```
Q[i]/[total]: [precise question]
Recommended: [answer + canon-cited rationale]
(Confirm, or override?)
```
## Stop conditions
- All branches resolved → invoke `/cs:pm` (question) or `/cs:pm-loop` (goal) with the
locked decisions inlined.
- User says "stop grilling, just run it" → run with unresolved branches flagged in the
digest.
- Abandoned → save the partial grill to `pm-grill-{timestamp}.md`.
## Distinct from
- `engineering/grill-me` — generic plan interrogation. This grills against the PM canon.
- `/cs:pm` — routes; this refuses to route until decisions are locked.

50
project-management/commands/cs-pm-loop.md Normal file
View file

@ -0,0 +1,50 @@
---
description: Drive a project-delivery goal through a bounded agentic loop — Jira MCP snapshot → flow/sprint analytics bridge → routed sub-skill execution → machine-verified gates → close refused until everything is verified or human-waived. The PM-domain adapter over engineering/agent-harness.
argument-hint: "<delivery goal, e.g. 'get sprint 14 to a verified close with health >= 70'>"
---
# /cs:pm-loop — run a delivery goal to a verified close
Goal:
**$ARGUMENTS**
## Sequence (gates are blocking — never skip forward)
1. **Intake gate** — the goal must name an observable outcome and its proof. If vague,
run the `/cs:grill-pm` branches first (one question per turn). Do not loop on fuzz.
2. **Observe** — pull fresh data: `mcp__atlassian__getAccessibleAtlassianResources` (get
cloudId) → `mcp__atlassian__searchJiraIssuesUsingJql` → save `snapshot.json`, then:
```bash
python3 project-management/skills/pm-skills/scripts/jira_snapshot_bridge.py --input snapshot.json --to flow
python3 project-management/skills/pm-skills/scripts/jira_snapshot_bridge.py --input snapshot.json --to sprint > sprint_data.json
```
3. **Plan** — write the task plan (owners, executors, reviewers, machine-checkable
acceptance per task; shape via `delivery_loop_gate.py --sample`), then gate it:
```bash
python3 project-management/skills/pm-skills/scripts/delivery_loop_gate.py --plan plan.json --mode plan
```
Exit 2 → fix the listed G1–G4 violations before executing. For multi-task goals,
compile through the repo harness instead (`goal_compiler.py` with the
`project-management.json` manifest) and drive it with `loop_controller.py`.
4. **Execute** — one task at a time: route with `pm_goal_router.py`, run the routed
sub-skill's own tools, record real exit codes and evidence. Retry means a changed
approach; max 3 attempts per task.
5. **Verify** — the task's acceptance command must exit 0; sub-skill gates apply
(scrum-master's ≥3-sprints rule, atlassian-admin's VERIFY steps). Never adjudicate
your own verification; never edit a gate to make it pass.
6. **Close** —
```bash
python3 project-management/skills/pm-skills/scripts/delivery_loop_gate.py --plan plan.json --mode close
```
Exit 4 → close refused: finish, escalate, or get a human waiver (with reason). Exit 0
→ report the handoff: tasks, statuses, evidence, waivers, and the flow-metrics
before/after.
## Rules
- Terminal states: success · clean no-op · blocked · approval-required · exhausted ·
stagnated. Exhausted budgets escalate to the named human — never reported as success.
- Jira writes are auditable: no `transitionJiraIssue` to Done without verify evidence;
admin/destructive actions are approval-required, full stop.
- Max 12 loop iterations per goal; 3 attempts per task.

45
project-management/commands/cs-pm.md Normal file
View file

@ -0,0 +1,45 @@
---
description: Top-level project-management router. Classifies a PM inquiry across 8 lanes (sprint/flow, portfolio health, Jira, Confluence, admin, templates, meetings, comms) with a deterministic script and forks context to the right sub-skill via the pm-skills orchestrator, returning a ≤200-word digest with a named owner and one grill challenge.
argument-hint: "<PM inquiry: sprint health, project status, JQL, permissions, retro, comms, etc.>"
---
# /cs:pm — Project Management router
Route this inquiry through the `pm-skills` orchestrator:
**$ARGUMENTS**
## Routing (deterministic — run the script, don't eyeball)
```bash
python3 project-management/skills/pm-skills/scripts/pm_goal_router.py --text "$ARGUMENTS" --output json
```
- Exit 0 → load `skill_path`/SKILL.md and follow that skill's own workflow in a fork.
- Exit 2 → ask ONE clarifying question naming the listed candidates, recommended answer
first.
- Exit 3 → ask the user to restate the goal with the deliverable named. Never guess.
- Explore the workspace first — a saved Jira snapshot, retro log, or transcript resolves
the lane silently. Never silently chain a second sub-skill.
## Output (≤200-word digest)
- What was analyzed (with the data source — snapshot file, not memory)
- Top 3 findings, each anchored to a canon citation
- Top 3 next actions with a named human owner
- Artifact path
- One grill challenge (e.g. "Your health report is self-reported RAG — where's the
derived diff that catches watermelons?")
## Hard rules
- Flow numbers come from `jira_snapshot_bridge.py` on real snapshot data.
- Forecasts are Monte Carlo percentile ranges, never single dates.
- Live Jira/Confluence ops use only the tools in
`project-management/references/atlassian-mcp-tools.md` — never invent tool names.
- Goals (not questions) go to `/cs:pm-loop` instead.
## Distinct from
- `product-team` — what to build. This domain is how to deliver it.
- `/cs:harness` — the generic loop engine; `/cs:pm-loop` is its PM-domain adapter.

191
project-management/skills/pm-skills/SKILL.md
View file

@ -1,50 +1,173 @@
---
name: "pm-skills"
description: "Router/index for the 8 project-management skills bundled in this plugin (senior PM quant toolkit, scrum master, Jira/JQL, Confluence, Atlassian admin, Atlassian templates, meeting analyzer, team communications). Use when a PM request doesn't obviously match one skill and you need to pick the right one (e.g., 'our sprints feel off', 'audit our Jira permissions'). Bundles an Atlassian Remote MCP config (.mcp.json) for live Jira/Confluence access."
version: 2.9.0
description: "Use when coordinating project-delivery work across the 8 project-management sub-skills — sprint/velocity analytics, portfolio health, Jira/JQL, Confluence, Atlassian admin, templates, meeting analysis, team comms. Triggers on 'our sprints feel off', 'project health report', 'audit our Jira permissions', 'when will it be done', 'run the delivery loop'. Forks context to route to one sub-skill via a deterministic signal router and returns a digest; can also drive a full goal→plan→execute→verify→close delivery loop through the repo-wide agent-harness with Jira MCP data bridged into the domain's analytics tools. Distinct from product-team (what to build vs how to deliver it), business-operations (internal ops), and engineering/agent-harness (the generic loop engine this orchestrator plugs into)."
context: fork
version: 2.11.1
author: Alireza Rezvani
license: MIT
tags:
- project-management
- jira
- confluence
- atlassian
- scrum
- agile
agents:
- claude-code
- codex-cli
- openclaw
tags: [project-management, orchestrator, jira, confluence, atlassian, scrum, agile, flow-metrics, agent-harness]
compatible_tools: [claude-code, codex-cli, cursor, antigravity, opencode, gemini-cli]
---
# Project Management Skills — Router
# Project Management — Domain Orchestrator & Delivery Loop
This plugin bundles **8 PM skills** (this router is the 9th folder under `project-management/skills/`). Each skill is self-contained. The bundled `.mcp.json` wires the Atlassian Remote MCP (`https://mcp.atlassian.com/v1/sse`, OAuth handled by Claude Code).
This orchestrator does two jobs. **Routing:** fork context, classify a PM inquiry with
`scripts/pm_goal_router.py`, run exactly one of the 8 sub-skills, return a digest.
**Looping:** turn a delivery goal into a bounded agentic loop — pull live Jira data via the
bundled Atlassian MCP, bridge it into the domain's deterministic analytics tools, verify
every step with machine-run gates, and refuse to close until everything is verified or a
human waives it. The bundled `.mcp.json` wires the Atlassian Remote MCP
(`https://mcp.atlassian.com/v1/sse`, OAuth handled by Claude Code).
## Routing table
## When to invoke
Match the request, then load `project-management/skills/<skill>/SKILL.md`. If multiple rows match, ask one clarifying question first.
| Symptom | Sub-skill |
|---|---|
| "Project/portfolio health, risk EMV, capacity" | `senior-pm` |
| "Sprint velocity, retro follow-through, ceremony health, when-will-it-be-done" | `scrum-master` |
| "JQL, Jira workflows, boards, automation" | `jira-expert` |
| "Confluence spaces, page trees, content audits" | `confluence-expert` |
| "Users, groups, permissions, SSO" | `atlassian-admin` |
| "Reusable Jira/Confluence templates" | `atlassian-templates` |
| "Meeting transcripts, talk time, action items" | `meeting-analyzer` |
| "Status updates, 3P updates, stakeholder comms" | `team-communications` |
| Request signals | Skill | Path |
|---|---|---|
| Project health, risk EMV, three-point estimates | senior-pm | `skills/senior-pm/` |
| Sprint velocity, retro analysis, ceremony health | scrum-master | `skills/scrum-master/` |
| JQL queries, Jira workflows, boards | jira-expert | `skills/jira-expert/` |
| Confluence spaces, page structure, content audits | confluence-expert | `skills/confluence-expert/` |
| User/permission/scheme administration | atlassian-admin | `skills/atlassian-admin/` |
| Reusable Confluence/Jira templates | atlassian-templates | `skills/atlassian-templates/` |
| Meeting transcripts, talk-time, action items | meeting-analyzer | `skills/meeting-analyzer/` |
| Status updates, 3P updates, stakeholder comms | team-communications | `skills/team-communications/` |
## Routing logic (deterministic)
## Quick start
Run the router — do not eyeball the table when a script can decide:
```bash
# Example: route a sprint-health request
cat project-management/skills/scrum-master/SKILL.md
ls project-management/skills/scrum-master/scripts/
python3 scripts/pm_goal_router.py --text "<the goal>" --output json
```
## Rules
Exit 0 → `route_to` names the sub-skill: load its SKILL.md and follow its workflow.
Exit 2 → ask ONE clarifying question naming the listed candidates, with a recommended
answer. Exit 3 → no signal: ask the user to restate the goal with the deliverable named.
Never guess silently; never silently chain a second sub-skill — digest first, confirm, then
chain.
- Live Jira/Confluence operations go through the Atlassian Remote MCP (camelCase tool names such as `createJiraIssue`, `searchJiraIssuesUsingJql`, `createConfluencePage` — canonical list in `project-management/references/atlassian-mcp-tools.md`). Admin operations are NOT covered by the MCP — use admin.atlassian.com or the REST API per atlassian-admin.
- Route to exactly one skill, then follow that skill's workflow. This router ships no tools of its own.
## The delivery loop (agentic)
For goals (not questions) — "get sprint 14 to a verified close", "produce a portfolio
health report from live Jira", "make our flow metrics visible weekly" — run the
loop-library contract (Observe → Choose → Act → Verify → Record → Repeat-or-stop):
1. **Observe** — pull fresh state: `mcp__atlassian__searchJiraIssuesUsingJql` (get
`cloudId` via `getAccessibleAtlassianResources` first), save the result JSON, then
bridge it:
```bash
python3 scripts/jira_snapshot_bridge.py --input snapshot.json --to flow # WIP, throughput, cycle time p50/85/95, work-item age, SLE, aging alerts
python3 scripts/jira_snapshot_bridge.py --input snapshot.json --to sprint > s.json # scrum-master schema
python3 ../scrum-master/scripts/velocity_analyzer.py s.json # velocity + volatility + forecast
```
Add `--forecast N` for a seeded Monte Carlo "when will N items be done" answer
(refuses on < 10 completed items — thin history forecasts are lies).
2. **Choose** — route the next task with `pm_goal_router.py`; one task at a time.
3. **Act** — execute with the routed sub-skill's own tools per its SKILL.md.
4. **Verify** — gate the plan and every close with:
```bash
python3 scripts/delivery_loop_gate.py --plan plan.json --mode plan # exit 2 = blocked
python3 scripts/delivery_loop_gate.py --plan plan.json --mode close # exit 4 = close refused
```
Plus each sub-skill's own gates (scrum-master's ≥ 3-sprints rule, atlassian-admin's
VERIFY steps). Never adjudicate your own verification.
5. **Record / Repeat-or-stop** — for multi-task goals, run the state through the repo-wide
harness (it enforces attempt caps, iteration budgets, and evidence logging):
```bash
python3 engineering/agent-harness/skills/agent-harness/scripts/goal_compiler.py \
--goal "<goal>" --manifest engineering/agent-harness/skills/agent-harness/assets/harnesses/project-management.json \
--out .agent-harness/plan.json
python3 engineering/agent-harness/skills/agent-harness/scripts/loop_controller.py init|next|record|verify|close ...
```
Terminal states: success, clean no-op, blocked, approval-required, exhausted,
stagnated. An exhausted budget is an escalation — never a success report.
## Hard rules (agentic delegation governance)
1. **Agents are contributors, never owners** (Linear model): every loop task carries a
named human owner; agent-executed tasks also carry a named human reviewer.
`delivery_loop_gate.py` enforces this (G1/G2).
2. **Acceptance must be machine-checkable** — a command, or a criterion with a threshold.
"Looks good" is not a gate (G3).
3. **Every Jira/Confluence write is auditable and reversible-first** (Rovo discipline):
never `transitionJiraIssue` to Done without verify evidence; destructive/irreversible
actions (deletes, permission changes, org-wide admin) are approval-required terminal
states, not loop steps.
4. **Never modify a gate you are judged by** — same locked-evaluator invariant as
autoresearch-agent.
5. **Forecasts are ranges with confidence, never dates** — Monte Carlo percentiles
(p50/p70/p85/p95), per Vacanti. Single-date promises are the anti-pattern.
6. **Max 3 attempts per task, 12 loop iterations per goal** — then escalate to the named
human with the evidence log.
## Forcing-question library (grill-with-docs pattern)
One per turn, recommended answer, canon citation. Never run a sub-skill or start a loop
until the lane-defining decision is locked:
- **SPRINT lane**: "Do you want to *measure* flow (cycle time, WIP, throughput, age) or
*forecast* delivery? Recommended: measure first — a forecast off unmeasured flow is
noise. Canon: Kanban Guide (May 2025) four mandatory flow measures; Vacanti,
*Actionable Agile Metrics*."
- **HEALTH lane**: "Is your project status self-reported RAG or derived from signals?
Recommended: derive it (schedule variance, aging WIP, scope churn) and diff against the
self-report — that diff finds watermelon projects. Canon: Kanban Guide 2025;
DORA 2025 (AI amplifies, doesn't fix, weak signals)."
- **JIRA lane**: "Is this configuration change deployable to a test project first?
Recommended: always stage in a test project; jira-expert's workflow validator must exit
0 before production. Canon: jira-expert validation workflow."
- **ADMIN lane**: "Is this action reversible, and who approves it? Recommended: name the
approver before touching permissions — admin actions are approval-required terminal
states in any loop. Canon: atlassian-admin VERIFY discipline; loop-library stop states."
- **LOOP intake**: "What single observable outcome means DONE, and which command proves
it? Recommended: a named artifact + a command that exits 0 against it. Canon:
agent-harness verifier's law; Anthropic, *Building Effective Agents* (evaluator needs
clear criteria)."
- **MEETINGS/COMMS lanes**: "Could this meeting be an async written update? Recommended:
status-broadcast meetings convert to async 3P updates; decision meetings keep sync.
Canon: GitLab async-first handbook."
## Assumptions
1. The user has (or is preparing analysis for someone with) delivery authority.
2. Jira/Confluence access goes through the bundled MCP; capabilities NOT in
`project-management/references/atlassian-mcp-tools.md` (project/sprint/board/space
creation, admin config) are done in the web UI — never invent tool names.
3. Inputs may be partial — every tool ships `--sample` so the shape is visible first.
## Non-goals
- Not a replacement for the sub-skills — the orchestrator routes and loops; the
sub-skills do the work.
- Not the generic loop engine — that is `engineering/agent-harness`; this orchestrator is
the PM-domain adapter (data bridge + governance gate + lane router).
- Does not decide *what* to build — that's `product-team`.
## Output artifacts
| Mode | Artifact |
|---|---|
| Route | Sub-skill's own artifact + ≤ 200-word digest with one canon-cited challenge |
| Flow report | `flow_metrics.json` (bridge output) with SLE conformance + aging alerts |
| Delivery loop | `.agent-harness/plan.json` + `state.json` + gate verdicts + close handoff |
## Anti-patterns (do not)
- ❌ Run all 8 sub-skills "to be thorough" — route to one, digest, chain on confirmation
- ❌ Report sprint health or forecasts from hand-typed numbers when a Jira snapshot is one
MCP call away — bridge real data
- ❌ Close a loop with unverified tasks, or report an exhausted budget as success
- ❌ Let an agent be the assignee of record — humans own, agents contribute
- ❌ Auto-transition Jira issues or touch permissions inside a loop without the named
approver
## References
- [references/flow_forecasting_canon.md](references/flow_forecasting_canon.md) — Kanban
Guide 2025, Vacanti Monte Carlo, DORA 2025, EBM, SPACE
- [references/agentic_delivery_governance.md](references/agentic_delivery_governance.md) —
Linear/Rovo delegation models, Anthropic agent patterns, audit discipline
- [references/pm_loop_playbook.md](references/pm_loop_playbook.md) — the five reusable PM
loops (sprint, health, retro-action, RAID-hygiene, comms) mapped to the loop contract
- Canonical MCP tool list: `project-management/references/atlassian-mcp-tools.md`
- Loop engine: `engineering/agent-harness` · Loop vocabulary: `loop-library`

53
project-management/skills/pm-skills/assets/expected_flow_metrics.json Normal file
View file

@ -0,0 +1,53 @@
{
"mode": "flow",
"as_of": "2026-06-10",
"counts": {
"total": 14,
"done": 11,
"wip": 2
},
"cycle_time_days": {
"p50": 9,
"p85": 14,
"p95": 16,
"basis": "created\u2192resolved (approximation; Jira exports rarely carry an in-progress timestamp)"
},
"throughput": {
"done_per_week": 2.08,
"weeks_observed": 5.3
},
"sle": {
"days": 14,
"conformance_pct": 90.9
},
"work_item_age": [
{
"key": "PHX-112",
"summary": "Realtime presence indicators",
"age_days": 15
},
{
"key": "PHX-113",
"summary": "Usage analytics dashboard",
"age_days": 2
}
],
"aging_wip_alerts": [
{
"key": "PHX-112",
"summary": "Realtime presence indicators",
"age_days": 15
}
],
"warnings": [],
"forecast": {
"items": 20,
"method": "Monte Carlo over historical weekly throughput (10k trials, seeded)",
"weeks": {
"p50": 9,
"p70": 10,
"p85": 10,
"p95": 10
}
}
}

19
project-management/skills/pm-skills/assets/sample_jira_snapshot.json Normal file
View file

@ -0,0 +1,19 @@
{
"_comment": "Saved output shape of mcp__atlassian__searchJiraIssuesUsingJql — feed to scripts/jira_snapshot_bridge.py. Expected flow output pinned in expected_flow_metrics.json.",
"issues": [
{"key": "PHX-101", "fields": {"summary": "User authentication service", "status": {"name": "Done"}, "created": "2026-05-04T09:00:00.000+0000", "resolutiondate": "2026-05-08T16:00:00.000+0000", "customfield_10016": 5, "sprint": {"name": "Sprint 11"}, "assignee": {"displayName": "A. Rivera"}, "priority": {"name": "High"}}},
{"key": "PHX-102", "fields": {"summary": "Dashboard layout", "status": {"name": "Done"}, "created": "2026-05-04T09:00:00.000+0000", "resolutiondate": "2026-05-12T11:00:00.000+0000", "customfield_10016": 3, "sprint": {"name": "Sprint 11"}, "assignee": {"displayName": "B. Okafor"}, "priority": {"name": "Medium"}}},
{"key": "PHX-103", "fields": {"summary": "Password reset flow", "status": {"name": "Done"}, "created": "2026-05-05T09:00:00.000+0000", "resolutiondate": "2026-05-13T15:00:00.000+0000", "customfield_10016": 2, "sprint": {"name": "Sprint 11"}, "assignee": {"displayName": "A. Rivera"}, "priority": {"name": "Medium"}}},
{"key": "PHX-104", "fields": {"summary": "Billing webhooks", "status": {"name": "Done"}, "created": "2026-05-11T09:00:00.000+0000", "resolutiondate": "2026-05-20T10:00:00.000+0000", "customfield_10016": 8, "sprint": {"name": "Sprint 12"}, "assignee": {"displayName": "C. Duarte"}, "priority": {"name": "High"}}},
{"key": "PHX-105", "fields": {"summary": "Email notifications", "status": {"name": "Done"}, "created": "2026-05-12T09:00:00.000+0000", "resolutiondate": "2026-05-19T17:00:00.000+0000", "customfield_10016": 3, "sprint": {"name": "Sprint 12"}, "assignee": {"displayName": "B. Okafor"}, "priority": {"name": "Medium"}}},
{"key": "PHX-106", "fields": {"summary": "Audit log export", "status": {"name": "Done"}, "created": "2026-05-13T09:00:00.000+0000", "resolutiondate": "2026-05-22T12:00:00.000+0000", "customfield_10016": 5, "sprint": {"name": "Sprint 12"}, "assignee": {"displayName": "D. Weiss"}, "priority": {"name": "Low"}}},
{"key": "PHX-107", "fields": {"summary": "Mobile responsive nav", "status": {"name": "Done"}, "created": "2026-05-18T09:00:00.000+0000", "resolutiondate": "2026-05-27T09:30:00.000+0000", "customfield_10016": 5, "sprint": {"name": "Sprint 13"}, "assignee": {"displayName": "A. Rivera"}, "priority": {"name": "High"}}},
{"key": "PHX-108", "fields": {"summary": "Rate limiting middleware", "status": {"name": "Done"}, "created": "2026-05-19T09:00:00.000+0000", "resolutiondate": "2026-05-29T14:00:00.000+0000", "customfield_10016": 3, "sprint": {"name": "Sprint 13"}, "assignee": {"displayName": "C. Duarte"}, "priority": {"name": "Medium"}}},
{"key": "PHX-109", "fields": {"summary": "Data export CSV", "status": {"name": "Done"}, "created": "2026-05-20T09:00:00.000+0000", "resolutiondate": "2026-06-03T16:00:00.000+0000", "customfield_10016": 2, "sprint": {"name": "Sprint 13"}, "assignee": {"displayName": "D. Weiss"}, "priority": {"name": "Low"}}},
{"key": "PHX-110", "fields": {"summary": "SSO SAML integration", "status": {"name": "Done"}, "created": "2026-05-25T09:00:00.000+0000", "resolutiondate": "2026-06-10T10:00:00.000+0000", "customfield_10016": 8, "sprint": {"name": "Sprint 14"}, "assignee": {"displayName": "C. Duarte"}, "priority": {"name": "High"}}},
{"key": "PHX-111", "fields": {"summary": "Search relevance tuning", "status": {"name": "Done"}, "created": "2026-06-01T09:00:00.000+0000", "resolutiondate": "2026-06-09T11:00:00.000+0000", "customfield_10016": 3, "sprint": {"name": "Sprint 14"}, "assignee": {"displayName": "B. Okafor"}, "priority": {"name": "Medium"}}},
{"key": "PHX-112", "fields": {"summary": "Realtime presence indicators", "status": {"name": "In Progress"}, "created": "2026-05-26T09:00:00.000+0000", "customfield_10016": 8, "sprint": {"name": "Sprint 14"}, "assignee": {"displayName": "A. Rivera"}, "priority": {"name": "High"}}},
{"key": "PHX-113", "fields": {"summary": "Usage analytics dashboard", "status": {"name": "In Progress"}, "created": "2026-06-08T09:00:00.000+0000", "customfield_10016": 5, "sprint": {"name": "Sprint 14"}, "assignee": {"displayName": "D. Weiss"}, "priority": {"name": "Medium"}}},
{"key": "PHX-114", "fields": {"summary": "Legacy importer deprecation", "status": {"name": "To Do"}, "created": "2026-06-09T09:00:00.000+0000", "customfield_10016": 3, "sprint": {"name": "Sprint 14"}, "assignee": {"displayName": "B. Okafor"}, "priority": {"name": "Low"}}}
]
}

71
project-management/skills/pm-skills/references/agentic_delivery_governance.md Normal file
View file

@ -0,0 +1,71 @@
# Agentic Delivery Governance
The accountability layer behind `delivery_loop_gate.py`. When agents execute delivery
work, the failure mode is not bad output — it is **unowned output**: work no human is
accountable for, verified by nobody, closed by the optimism of the thing that did it.
The 2025–2026 vendors converged on the same governance shape; this file encodes it.
## The delegation model (why G1/G2 exist)
- **Linear's shipped design**: issues can be delegated to agents, but the **human stays
primary assignee; the agent is a contributor**. Delegation transfers execution, never
accountability. → Gate G1: every task names a human owner.
- **Atlassian Rovo (GA 2026)**: agents are assignable and @mentionable inside Jira, but
"every action remains logged and auditable", and multi-step plans pause for human
oversight at decision points. → Gate G2: agent-executed tasks name a human reviewer;
hard rule: no un-reviewed `transitionJiraIssue` to Done, no permission changes inside a
loop.
## Verification discipline (why G3/G4 exist)
- **Machine-checkable definition of done**: the reliable loop shape is plan → act →
verify with a deterministic verifier → reflect. A criterion without a command or a
threshold ("looks good", "improved") cannot gate anything. → G3: acceptance = a `cmd`,
or a criterion containing a measurable number.
- **Never trust self-report**: the agent that did the work does not adjudicate the work.
Evidence precedes status: `done` without recorded evidence is rejected (G4) — the same
invariant as agent-harness's "a verify pass without --evidence is exit 6" and
autoresearch-agent's locked evaluator ("never modify the gate you are judged by").
## Terminal-state honesty (why G5/G6 exist)
From the loop-library contract: loops end in a **named terminal state** — success, clean
no-op, blocked, approval-required, exhausted, stagnated. Two corollaries the gate
enforces:
- Close is refused while any task is neither done nor waived (G5); waivers are human
decisions with recorded rationale.
- An exhausted budget (attempts or iterations) is an **escalation**, never a success
report (G6). Budgets are first-class: max attempts per task, max loop iterations, and
the stop fires mechanically, not when the agent feels finished.
## Design principles for PM loops
1. **Workflows before agents** (Anthropic): most PM automation is a routed workflow
(classify → run tool → report). Reach for the autonomous loop only when the task needs
fresh feedback each cycle — flow snapshots, retro follow-through, RAID hygiene.
2. **Evaluator-optimizer needs clear criteria**: the generator/critic loop pays off
exactly when acceptance is machine-checkable — which is why the gate forces G3 before
any loop starts.
3. **Context from structured interfaces, not prompt-stuffing**: the agent's Jira context
comes through the MCP (Teamwork-Graph-style structured access), snapshotted to a file
the loop can re-read — every iteration is executable by a fresh session.
4. **Agent-readiness is a data-hygiene property**: agents amplify the Jira they are given
(DORA 2025's amplifier finding). Field completeness, acceptance criteria in
descriptions, and honest statuses are prerequisites, not nice-to-haves.
## Sources
1. Linear, "Agents in Linear" / Linear for Agents — https://linear.app/agents and
https://linear.app/docs/agents-in-linear
2. Atlassian Rovo — https://www.atlassian.com/software/rovo and Rovo agents docs
https://support.atlassian.com/rovo/docs/agents/
3. Anthropic, "Building Effective Agents" (orchestrator-workers, evaluator-optimizer,
simplicity-first) — https://www.anthropic.com/research/building-effective-agents
4. Forward Future, Loop Library (terminal-state taxonomy; "never report an error or
exhausted budget as success") — vendored at `loop-library/SKILL.md`
5. DORA, *State of DevOps 2025* (AI as amplifier) — https://dora.dev/dora-report-2025/
6. This repo: `engineering/agent-harness` references/verification_discipline.md
(reward-hacking failure mode; locked evaluators)
7. SiliconANGLE, "Atlassian opens Teamwork Graph, pushes Rovo agentic execution"
(Team '26 coverage) — https://siliconangle.com/2026/05/06/

76
project-management/skills/pm-skills/references/flow_forecasting_canon.md Normal file
View file

@ -0,0 +1,76 @@
# Flow Metrics & Probabilistic Forecasting Canon
The measurement layer behind `jira_snapshot_bridge.py --to flow`. The 2024–2026 delivery
canon moved from velocity/story-point folklore to **flow measurement + probabilistic
forecasting + outcome measures**. This file anchors every number the bridge emits.
## The four mandatory flow measures (Kanban Guide, May 2025)
The Kanban Guide mandates exactly four measures — teams that track anything must track
these:
| Measure | Definition | Bridge field |
|---|---|---|
| **WIP** | Work items started but not finished | `counts.wip` |
| **Throughput** | Items finished per unit of time | `throughput.done_per_week` |
| **Cycle time** | Elapsed time started → finished | `cycle_time_days.p50/p85/p95` |
| **Work item age** | Elapsed time for *unfinished* started items | `work_item_age` |
Plus a **Service Level Expectation (SLE)**: "we finish items of this type within N days,
X% of the time." The bridge defaults the SLE to the p85 cycle time and reports
conformance. **Work item age is the leading indicator** — an in-progress item older than
the p85 SLE is the earliest visible slip signal (`aging_wip_alerts`); cycle time only
tells you after the fact.
Caveat the bridge prints itself: Jira exports rarely carry an in-progress timestamp, so
cycle time is approximated created→resolved. When your workflow logs a real start
transition, prefer it.
## Percentiles, not averages
Cycle-time distributions are right-skewed; the mean lies. Report p50/p85/p95
(Vacanti). Commit externally at p85, plan internally at p50, treat p95 as the tail-risk
budget.
## Monte Carlo forecasting (replaces story-point velocity)
"When will it be done?" is answered by sampling historical throughput, not by dividing
backlog points by velocity: sample the weekly-throughput history 10k times, read the
p50/p70/p85/p95 week counts (`--forecast N`). Rules the bridge enforces:
- **Refuses on < 10 completed items across < 4 distinct weeks** — thin history produces
confident nonsense.
- **Seeded RNG** — same data in, same forecast out (audit-reproducible).
- **Ranges with confidence, never a date** — a single-date promise is the anti-pattern.
## Outcome measures above flow
Flow says whether delivery is smooth, not whether it is *valuable*:
- **DORA 2025**: replaced low/high/elite clusters with seven team archetypes over eight
measures; core 2025 finding — AI *amplifies* an org's existing strengths and
dysfunctions (individual output up, org delivery flat without enabling capabilities).
- **EBM (Scrum.org)**: four Key Value Areas — Current Value, Unrealized Value,
Time-to-Market, Ability to Innovate. Most orgs measure only T2M; empty CV/UV areas mean
you are measuring motion, not value.
- **SPACE**: any metrics portfolio must span ≥ 3 of Satisfaction/Performance/Activity/
Communication/Efficiency — activity-only portfolios (PR counts) are the documented
anti-pattern.
- **Derived health beats self-reported RAG**: diff derived signals (aging WIP, scope
churn, schedule variance) against the self-reported status to find "watermelon"
projects (green outside, red inside) — the pattern behind senior-pm's dashboard.
## Sources
1. The Kanban Guide (May 2025) — https://kanbanguides.org/the-kanban-guide/
2. Daniel Vacanti, *Actionable Agile Metrics for Predictability* and *When Will It Be
Done?* (ActionableAgile Press)
3. Scrum.org, "4 Key Flow Metrics and How to Use Them" —
https://www.scrum.org/resources/blog/4-key-flow-metrics-and-how-use-them-scrums-events
4. Scrum.org, "Monte Carlo Forecasting in Scrum" —
https://www.scrum.org/resources/blog/monte-carlo-forecasting-scrum
5. DORA, *Accelerate State of DevOps Report 2025* — https://dora.dev/dora-report-2025/
6. Scrum.org, *The Evidence-Based Management Guide* —
https://www.scrum.org/resources/evidence-based-management
7. Forsgren, Storey et al., "The SPACE of Developer Productivity", ACM Queue —
https://queue.acm.org/detail.cfm?id=3454124

92
project-management/skills/pm-skills/references/pm_loop_playbook.md Normal file
View file

@ -0,0 +1,92 @@
# The PM Loop Playbook — five reusable delivery loops
Concrete instantiations of the loop contract (Observe → Choose → Act → Verify → Record →
Repeat-or-stop) for day-to-day PM work. Each loop names its trigger, its machine gate,
and its terminal states — a loop without a named stop is just an unbounded retry.
## Loop 1 — Sprint flow loop (weekly)
- **Observe**: `searchJiraIssuesUsingJql` → save snapshot →
`jira_snapshot_bridge.py --to flow`.
- **Choose**: highest-leverage signal first — aging-WIP alerts beat cycle-time trends
(age is the leading indicator; cycle time is a lagging one).
- **Act**: unblock/swarm/split the flagged item with the team; scrum-master skill for
ceremony-level fixes.
- **Verify**: next week's bridge run — the flagged item left `aging_wip_alerts`, SLE
conformance did not drop.
- **Stop states**: success (no alerts 2 weeks running) · stagnated (same item flagged 3
weeks → escalate to the delivery lead by name) · approval-required (fix needs scope
change).
## Loop 2 — Health-report loop (per reporting period)
- **Observe**: bridge `--to sprint` → `velocity_analyzer.py` +
`sprint_health_scorer.py`; senior-pm's `project_health_dashboard.py` for the portfolio.
- **Choose**: diff derived health against the self-reported RAG — investigate the largest
divergence first (watermelon detection).
- **Act**: senior-pm workflows (risk register, capacity rebalance).
- **Verify**: divergence shrinks next period; every red flag has a named owner + dated
action.
- **Stop states**: success · blocked (data quality too poor to derive — fix Jira hygiene
first, see agent-readiness note in agentic_delivery_governance.md).
## Loop 3 — Retro action loop (per sprint)
The retro is not the loop — the **action-item completion rate** is. Scrum-master's
retrospective_analyzer computes it (fixture: 46.7%).
- **Observe**: `retrospective_analyzer.py` on the retro log.
- **Choose**: oldest open action item with a named owner.
- **Act**: drive it to done or explicitly kill it (a cancelled action with a reason beats
a zombie).
- **Verify**: completion rate trend up across 3 sprints.
- **Stop states**: success (≥ 70% completion) · stagnated (rate flat 3 sprints → the retro
format is the problem; change the ritual, per Klein's pre-mortem alternative).
## Loop 4 — RAID hygiene loop (biweekly)
- **Observe**: risk register / RAID log staleness — entries missing owner, next-review
date, or mitigation; issues open > 30 days.
- **Choose**: stalest critical-severity entry.
- **Act**: senior-pm's `risk_matrix_analyzer.py` re-score; pre-mortem session for new
workstreams (prospective hindsight measurably improves risk identification — Klein).
- **Verify**: zero critical entries without owner+mitigation; staleness p85 < review
cadence.
- **Stop states**: success · clean no-op (nothing stale — record and exit; do not invent
work).
## Loop 5 — Comms cadence loop (weekly)
- **Observe**: which status-broadcast meetings ran this week; which stakeholder updates
shipped.
- **Choose**: convert the largest status-broadcast meeting to an async 3P update
(GitLab's handbook-first model: written 3-question standups take 3–5 min vs 15–30 sync;
GitLab reports ~37% meeting-hour reduction).
- **Act**: team-communications skill (3P format); meeting-analyzer on the transcripts of
the meetings that remain.
- **Verify**: sync:async ratio trending down; no stakeholder escalation citing "I didn't
know".
- **Stop states**: success · approval-required (a stakeholder insists on sync — their
call, record it).
## Rules that hold across all five
1. One bounded, reversible change per iteration (autoresearch's "ONE change" rule).
2. Fresh state before every consequential action — re-pull the snapshot, don't act on
last week's.
3. Separate the optimizing signal from the acceptance gate — if you optimize SLE
conformance, verify with throughput + age too (anti-overfit, loop-library).
4. Every escalation names a human and attaches the evidence log.
## Sources
1. Forward Future, Loop Library — the Observe→…→Repeat-or-stop contract and terminal-state
taxonomy (vendored at `loop-library/SKILL.md`)
2. The Kanban Guide (May 2025) — https://kanbanguides.org/the-kanban-guide/
3. Gary Klein, "Performing a Project Premortem", HBR 2007 —
https://hbr.org/2007/09/performing-a-project-premortem
4. GitLab Handbook, asynchronous work —
https://handbook.gitlab.com/handbook/company/culture/all-remote/asynchronous/
5. Sumeet Moghe, *The Async-First Playbook* (2023)
6. This repo: `engineering/autoresearch-agent` (one-change-per-iteration, locked
evaluator), `engineering/agent-harness` (state machine, budgets)

152
project-management/skills/pm-skills/scripts/delivery_loop_gate.py Normal file
View file

@ -0,0 +1,152 @@
#!/usr/bin/env python3
"""delivery_loop_gate.py — governance gate for agent-executed delivery loops.
Encodes the 2025–2026 agentic-delegation canon as a machine-checkable gate
(Linear's agents model: the human stays accountable for delegated work; Atlassian
Rovo: every agent action stays auditable; loop-library: exhausted budgets are never
reported as success). Run it on a delivery-loop plan before executing (--mode plan)
and again before closing (--mode close). Pairs with the repo-wide
engineering/agent-harness loop_controller.py, which enforces the run-time state
machine; this gate enforces the PM-specific accountability rules the controller
does not know about.
Plan JSON shape (see --sample):
{"goal": str,
"budgets": {"max_attempts_per_task": int, "max_loop_iterations": int},
"iteration": int,
"tasks": [{"id","title","owner","executor":"human|agent","reviewer",
"acceptance": {"cmd": str} | {"criterion": str},
"status":"todo|in_progress|done|blocked|waived",
"evidence": str, "attempts": int, "waive_reason": str}]}
Rules enforced:
G1 every task has a named human owner (agents are contributors, never owners)
G2 agent-executed tasks name a human reviewer distinct from nobody
G3 acceptance is machine-checkable: a cmd, or a criterion containing a measurable
threshold (a digit) — "looks good" is not a gate
G4 done requires non-empty evidence; waived requires a waive_reason
G5 close is refused while any task is neither done nor waived
G6 close is refused when budgets are exhausted with work remaining — that is an
escalation, not a success
Exit codes: 0 pass · 2 plan violations · 3 unreadable input · 4 close refused.
Stdlib only, deterministic.
"""
import argparse
import json
import re
import sys
SAMPLE_PLAN = {
"goal": "Get sprint 14 to a verified close with a health score >= 70",
"budgets": {"max_attempts_per_task": 3, "max_loop_iterations": 12},
"iteration": 4,
"tasks": [
{"id": "T1", "title": "Pull sprint snapshot via searchJiraIssuesUsingJql",
"owner": "Sarah Chen", "executor": "agent", "reviewer": "Sarah Chen",
"acceptance": {"cmd": "python3 scripts/jira_snapshot_bridge.py --input snapshot.json --to sprint"},
"status": "done", "evidence": "sprint_data.json written, 4 sprints", "attempts": 1},
{"id": "T2", "title": "Score sprint health",
"owner": "Sarah Chen", "executor": "agent", "reviewer": "Mike Rodriguez",
"acceptance": {"criterion": "sprint_health_scorer.py composite >= 70"},
"status": "in_progress", "evidence": "", "attempts": 1},
],
}
def check_plan(plan):
violations, warnings = [], []
tasks = plan.get("tasks", [])
if not tasks:
violations.append({"rule": "G1", "task": "-", "problem": "plan has no tasks"})
for t in tasks:
tid = t.get("id", "?")
if not str(t.get("owner", "")).strip():
violations.append({"rule": "G1", "task": tid,
"problem": "no named human owner (Linear rule: agents are contributors, never owners)"})
if t.get("executor") == "agent" and not str(t.get("reviewer", "")).strip():
violations.append({"rule": "G2", "task": tid,
"problem": "agent-executed task has no named human reviewer"})
acc = t.get("acceptance") or {}
cmd = str(acc.get("cmd", "")).strip()
criterion = str(acc.get("criterion", "")).strip()
if not cmd and not (criterion and re.search(r"\d", criterion)):
violations.append({"rule": "G3", "task": tid,
"problem": "acceptance is not machine-checkable "
"(need a cmd, or a criterion with a measurable threshold)"})
status = t.get("status", "todo")
if status == "done" and not str(t.get("evidence", "")).strip():
violations.append({"rule": "G4", "task": tid,
"problem": "done without evidence — never record a verify pass you did not observe"})
if status == "waived" and not str(t.get("waive_reason", "")).strip():
violations.append({"rule": "G4", "task": tid,
"problem": "waived without a waive_reason (waivers are human decisions with rationale)"})
max_attempts = plan.get("budgets", {}).get("max_attempts_per_task")
if max_attempts and t.get("attempts", 0) >= max_attempts and status not in ("done", "waived", "blocked"):
warnings.append({"rule": "G6", "task": tid,
"note": f"attempts exhausted ({t.get('attempts')}/{max_attempts}) — escalate, do not retry"})
return violations, warnings
def check_close(plan):
refusals = []
for t in plan.get("tasks", []):
if t.get("status") not in ("done", "waived"):
refusals.append({"rule": "G5", "task": t.get("id", "?"),
"problem": f"status is '{t.get('status', 'todo')}' — close refused while tasks are unverified and unwaived"})
budgets = plan.get("budgets", {})
max_iter = budgets.get("max_loop_iterations")
if max_iter and plan.get("iteration", 0) > max_iter and refusals:
refusals.append({"rule": "G6", "task": "-",
"problem": f"iteration {plan['iteration']} > cap {max_iter} with open tasks — "
"this is an ESCALATION, never a success report"})
return refusals
def main() -> int:
ap = argparse.ArgumentParser(
description="Accountability gate for agent-executed PM delivery loops.")
ap.add_argument("--plan", help="Path to the loop plan JSON ('-' for stdin).")
ap.add_argument("--mode", choices=["plan", "close"], default="plan")
ap.add_argument("--output", choices=["json", "human"], default="json")
ap.add_argument("--sample", action="store_true",
help="Print a valid sample plan and exit 0.")
args = ap.parse_args()
if args.sample:
print(json.dumps(SAMPLE_PLAN, indent=2))
return 0
if not args.plan:
ap.error("--plan is required (or use --sample to see the expected shape)")
try:
plan = json.load(sys.stdin if args.plan == "-" else open(args.plan, encoding="utf-8"))
except (OSError, ValueError) as exc:
print(f"ERROR: cannot read plan: {exc}", file=sys.stderr)
return 3
violations, warnings = check_plan(plan)
result = {"mode": args.mode, "goal": plan.get("goal", ""),
"violations": violations, "warnings": warnings}
exit_code = 0
if args.mode == "close":
refusals = check_close(plan)
result["close_refusals"] = refusals
result["verdict"] = "CLOSE-REFUSED" if (refusals or violations) else "CLOSE-OK"
exit_code = 4 if (refusals or violations) else 0
else:
result["verdict"] = "PLAN-BLOCKED" if violations else "PLAN-OK"
exit_code = 2 if violations else 0
if args.output == "json":
print(json.dumps(result, indent=2))
else:
print(f"Verdict: {result['verdict']}")
for v in violations + result.get("close_refusals", []):
print(f" [{v['rule']}] {v['task']}: {v['problem']}")
for w in warnings:
print(f" (warn {w['rule']}) {w['task']}: {w['note']}")
return exit_code
if __name__ == "__main__":
sys.exit(main())

282
project-management/skills/pm-skills/scripts/jira_snapshot_bridge.py Normal file
View file

@ -0,0 +1,282 @@
#!/usr/bin/env python3
"""jira_snapshot_bridge.py — turn a Jira MCP issue export into analyzable inputs.
Closes the domain's biggest wiring gap: `mcp__atlassian__searchJiraIssuesUsingJql`
returns issue JSON, but the domain's deterministic analytics tools
(scrum-master/velocity_analyzer.py, sprint_health_scorer.py) expect their own
sprint-record schema, and nothing computed flow metrics at all. This bridge accepts
a saved Jira search result (raw MCP shape with `issues[].fields`, or a flat list of
simplified issue dicts) and emits:
--to flow the four mandatory Kanban flow measures (Kanban Guide, May 2025):
WIP, throughput, cycle time (p50/p85/p95), work-item age — plus SLE
conformance and aging-WIP alerts, and an optional Monte Carlo
"when will N items be done" forecast (Vacanti-style, seeded, refuses
on < 10 completed items).
--to sprint scrum-master sprint-record JSON (pipe into velocity_analyzer.py /
sprint_health_scorer.py). Refuses with exit 5 on < 3 sprints,
mirroring velocity_analyzer's own minimum.
Cycle time here is created→resolved (Jira's export rarely carries an in-progress
timestamp); the output labels this approximation explicitly.
Exit codes: 0 ok · 2 unreadable/invalid input · 5 insufficient data for the
requested mode. Stdlib only; deterministic (as-of defaults to the newest timestamp
in the data, never the wall clock; the forecast RNG is seeded).
"""
import argparse
import json
import math
import random
import sys
from datetime import date, timedelta
DONE_STATUSES = {"done", "closed", "resolved", "released"}
NOT_STARTED_STATUSES = {"to do", "todo", "open", "backlog", "new", "created"}
POINT_FIELD_CANDIDATES = ["story_points", "storyPoints", "customfield_10016", "points"]
SAMPLE_SNAPSHOT = {
"issues": [
{"key": "PROJ-1", "fields": {"summary": "Login flow", "status": {"name": "Done"},
"created": "2026-05-04T09:00:00.000+0000",
"resolutiondate": "2026-05-08T16:00:00.000+0000",
"customfield_10016": 5, "sprint": {"name": "Sprint 12"},
"assignee": {"displayName": "A. Rivera"}}},
{"key": "PROJ-2", "fields": {"summary": "Rate limiting", "status": {"name": "In Progress"},
"created": "2026-05-18T09:00:00.000+0000", "customfield_10016": 3,
"sprint": {"name": "Sprint 13"}, "assignee": {"displayName": "B. Okafor"}}},
]
}
def parse_date(value):
if not value:
return None
text = str(value)[:10]
try:
return date.fromisoformat(text)
except ValueError:
return None
def name_of(value):
if isinstance(value, dict):
return value.get("name") or value.get("displayName") or ""
return str(value) if value else ""
def sprint_of(value):
if isinstance(value, list) and value:
value = value[-1]
return name_of(value)
def normalize(raw, points_field):
if isinstance(raw, dict) and "issues" in raw:
records = raw["issues"]
elif isinstance(raw, list):
records = raw
else:
raise ValueError("expected {'issues': [...]} or a JSON list of issues")
issues = []
for rec in records:
if not isinstance(rec, dict):
continue
f = rec.get("fields", rec)
points = None
for cand in ([points_field] if points_field else []) + POINT_FIELD_CANDIDATES:
if cand and f.get(cand) is not None:
points = f.get(cand)
break
status = name_of(f.get("status")).lower()
issues.append({
"key": rec.get("key") or f.get("key") or "?",
"summary": f.get("summary", ""),
"status": status,
"done": status in DONE_STATUSES,
"started": status not in NOT_STARTED_STATUSES,
"created": parse_date(f.get("created")),
"resolved": parse_date(f.get("resolutiondate") or f.get("resolved")),
"points": float(points) if points is not None else None,
"sprint": sprint_of(f.get("sprint") or f.get("customfield_10020")),
"assignee": name_of(f.get("assignee")),
"priority": name_of(f.get("priority")).lower(),
})
return [i for i in issues if i["created"]]
def percentile(sorted_values, pct):
if not sorted_values:
return None
rank = max(1, math.ceil(pct / 100 * len(sorted_values)))
return sorted_values[rank - 1]
def flow_report(issues, as_of, sle_days, forecast_items, seed):
done = [i for i in issues if i["done"] and i["resolved"]]
wip = [i for i in issues if not i["done"] and i["started"]]
cycles = sorted(max((i["resolved"] - i["created"]).days, 0) for i in done)
p50, p85, p95 = (percentile(cycles, p) for p in (50, 85, 95))
span_days = max((as_of - min(i["created"] for i in issues)).days, 7) if issues else 7
weeks = max(span_days / 7.0, 1.0)
# Weekly throughput over the FULL observed span (first resolution → as_of),
# zero-filled: dead weeks are real observations and must be sampleable, or the
# Monte Carlo forecast biases optimistic (Vacanti).
weekly_counts = []
if done:
first_resolved = min(i["resolved"] for i in done)
observed_weeks = max(((as_of - first_resolved).days // 7) + 1, 1)
weekly_counts = [0] * observed_weeks
for i in done:
idx = min((i["resolved"] - first_resolved).days // 7, observed_weeks - 1)
weekly_counts[idx] += 1
sle = sle_days if sle_days else p85
conformance = (
round(100 * sum(1 for c in cycles if c <= sle) / len(cycles), 1)
if cycles and sle is not None else None
)
aging = sorted(
({"key": i["key"], "summary": i["summary"][:60],
"age_days": (as_of - i["created"]).days} for i in wip),
key=lambda a: -a["age_days"],
)
aging_alerts = [a for a in aging if p85 is not None and a["age_days"] > p85]
report = {
"mode": "flow",
"as_of": as_of.isoformat(),
"counts": {"total": len(issues), "done": len(done), "wip": len(wip)},
"cycle_time_days": {"p50": p50, "p85": p85, "p95": p95,
"basis": "created→resolved (approximation; Jira exports rarely carry an in-progress timestamp)"},
"throughput": {"done_per_week": round(len(done) / weeks, 2),
"weeks_observed": round(weeks, 1)},
"sle": {"days": sle, "conformance_pct": conformance},
"work_item_age": aging[:10],
"aging_wip_alerts": aging_alerts,
"warnings": [],
}
if len(done) < 10:
report["warnings"].append(
f"only {len(done)} completed items — flow percentiles are low-confidence below 10")
if forecast_items:
if len(weekly_counts) < 4 or len(done) < 10:
report["warnings"].append(
"forecast refused: need >= 10 completed items across >= 4 observed calendar "
"weeks (Vacanti: throughput sampling needs real history; zero-throughput "
"weeks count as observations)")
else:
rng = random.Random(seed)
samples = weekly_counts
trials = []
for _ in range(10000):
remaining, wk = forecast_items, 0
while remaining > 0 and wk < 520:
remaining -= rng.choice(samples)
wk += 1
trials.append(wk)
trials.sort()
report["forecast"] = {
"items": forecast_items,
"method": "Monte Carlo over historical weekly throughput (10k trials, seeded)",
"weeks": {f"p{p}": percentile(trials, p) for p in (50, 70, 85, 95)},
}
return report
def sprint_export(issues):
by_sprint = {}
for i in issues:
if i["sprint"]:
by_sprint.setdefault(i["sprint"], []).append(i)
if len(by_sprint) < 3:
print(f"REFUSED: {len(by_sprint)} sprint(s) in snapshot — velocity analysis needs >= 3 "
"(same gate as velocity_analyzer.py). Widen the JQL date range.", file=sys.stderr)
return None
ordered = sorted(by_sprint.items(),
key=lambda kv: min(i["created"] for i in kv[1]))
sprints = []
for n, (name, items) in enumerate(ordered, 1):
planned = sum(i["points"] or 0 for i in items)
completed = sum(i["points"] or 0 for i in items if i["done"])
starts = min(i["created"] for i in items)
ends = max((i["resolved"] or i["created"]) for i in items)
sprints.append({
"sprint_number": n, "sprint_name": name,
"start_date": starts.isoformat(), "end_date": ends.isoformat(),
"planned_points": round(planned, 1), "completed_points": round(completed, 1),
"added_points": 0, "removed_points": 0,
"carry_over_points": round(planned - completed, 1) if planned > completed else 0,
"team_capacity": 0, "working_days": 10,
"team_size": len({i["assignee"] for i in items if i["assignee"]}),
"stories": [{
"id": i["key"], "title": i["summary"][:80], "points": i["points"] or 0,
"status": "completed" if i["done"] else ("in_progress" if i["started"] else "not_started"),
"assigned_to": i["assignee"], "created_date": i["created"].isoformat(),
**({"completed_date": i["resolved"].isoformat()} if i["resolved"] else {}),
"blocked_days": 0, "priority": i["priority"] or "medium",
} for i in items],
"blockers": [],
})
return {
"team_info": {"name": "bridged-from-jira", "size": 0,
"scrum_master": "", "product_owner": ""},
"sprints": sprints,
"_note": ("Bridged from a Jira snapshot: added/removed/carry-over/capacity and "
"ceremonies are not derivable from issue exports — fill them in or accept "
"the conservative defaults before scoring sprint health."),
}
def main() -> int:
ap = argparse.ArgumentParser(
description="Bridge a saved Jira MCP search result into flow metrics or "
"scrum-master sprint-record JSON.")
ap.add_argument("--input", help="Path to the saved Jira search JSON ('-' for stdin).")
ap.add_argument("--to", choices=["flow", "sprint"], default="flow")
ap.add_argument("--points-field", help="Custom field id carrying story points "
"(e.g. customfield_10016).")
ap.add_argument("--as-of", help="Analysis date YYYY-MM-DD (default: newest date in data).")
ap.add_argument("--sle-days", type=int, help="Service Level Expectation in days "
"(default: the p85 cycle time).")
ap.add_argument("--forecast", type=int, metavar="N",
help="Monte Carlo forecast: weeks to finish N more items.")
ap.add_argument("--seed", type=int, default=42)
ap.add_argument("--sample", action="store_true",
help="Print a sample input snapshot and exit 0.")
args = ap.parse_args()
if args.sample:
print(json.dumps(SAMPLE_SNAPSHOT, indent=2))
return 0
if not args.input:
ap.error("--input is required (or use --sample to see the expected shape)")
try:
raw = json.load(sys.stdin if args.input == "-" else open(args.input, encoding="utf-8"))
issues = normalize(raw, args.points_field)
except (OSError, ValueError) as exc:
print(f"ERROR: cannot read snapshot: {exc}", file=sys.stderr)
return 2
if not issues:
print("ERROR: no issues with a created date found in the snapshot.", file=sys.stderr)
return 2
if args.to == "sprint":
result = sprint_export(issues)
if result is None:
return 5
print(json.dumps(result, indent=2))
return 0
as_of = parse_date(args.as_of) if args.as_of else max(
(i["resolved"] or i["created"]) for i in issues)
if as_of is None:
print(f"ERROR: --as-of '{args.as_of}' is not a valid YYYY-MM-DD date.",
file=sys.stderr)
return 2
report = flow_report(issues, as_of, args.sle_days, args.forecast, args.seed)
print(json.dumps(report, indent=2))
return 0
if __name__ == "__main__":
sys.exit(main())

179
project-management/skills/pm-skills/scripts/pm_goal_router.py Normal file
View file

@ -0,0 +1,179 @@
#!/usr/bin/env python3
"""pm_goal_router.py — deterministic lane classifier for the project-management domain.
Scores a PM goal/inquiry against the 8 sub-skill lanes using keyword signals
(same two-signal threshold discipline as the research-ops / commercial / markdown-html
orchestrators). Emits a routing decision an agent can branch on mechanically.
Exit codes:
0 confident route emitted (route_to set)
2 ambiguous — ask ONE clarifying question naming the top two lanes
3 no signal — do not guess; ask the user to restate the goal
Stdlib only. Deterministic: same text in, same route out.
"""
import argparse
import json
import sys
SIGNALS = {
"HEALTH": {
"skill": "senior-pm",
"path": "project-management/skills/senior-pm",
"keywords": [
"project health", "portfolio", "risk register", "risk analysis", "emv",
"monte carlo", "executive report", "status report", "milestone", "budget",
"resource capacity", "capacity plan", "raid", "stakeholder satisfaction",
"program", "watermelon",
],
},
"SPRINT": {
"skill": "scrum-master",
"path": "project-management/skills/scrum-master",
"keywords": [
"sprint", "velocity", "retro", "retrospective", "ceremony", "standup",
"scrum", "burndown", "forecast", "story points", "action item",
"team health", "flow metrics", "cycle time", "throughput", "wip",
],
},
"JIRA": {
"skill": "jira-expert",
"path": "project-management/skills/jira-expert",
"keywords": [
"jql", "jira workflow", "jira board", "automation rule", "issue type",
"jira filter", "jira report", "jira config", "workflow transition",
"kanban board", "epic link",
],
},
"CONFLUENCE": {
"skill": "confluence-expert",
"path": "project-management/skills/confluence-expert",
"keywords": [
"confluence", "space", "knowledge base", "page tree", "documentation audit",
"wiki", "page hierarchy", "content governance", "macro",
],
},
"ADMIN": {
"skill": "atlassian-admin",
"path": "project-management/skills/atlassian-admin",
"keywords": [
"permission", "sso", "saml", "provisioning", "deactivate user", "group",
"admin", "security policy", "access control", "marketplace app", "audit log",
],
},
"TEMPLATES": {
"skill": "atlassian-templates",
"path": "project-management/skills/atlassian-templates",
"keywords": [
"template", "blueprint", "scaffold", "standardized page", "reusable layout",
"storage format",
],
},
"MEETINGS": {
"skill": "meeting-analyzer",
"path": "project-management/skills/meeting-analyzer",
"keywords": [
"meeting", "transcript", "talk time", "speaking", "filler words",
"interruption", "facilitation", "1:1", "one-on-one",
],
},
"COMMS": {
"skill": "team-communications",
"path": "project-management/skills/team-communications",
"keywords": [
"status update", "3p", "newsletter", "faq", "announcement",
"stakeholder update", "incident report", "comms", "broadcast",
],
},
}
SAMPLE_GOAL = (
"our sprints feel off — velocity keeps swinging and the retro action items "
"never get done"
)
def score(text: str) -> dict:
low = text.lower()
scores = {}
hits = {}
for lane, spec in SIGNALS.items():
matched = [kw for kw in spec["keywords"] if kw in low]
scores[lane] = len(matched)
hits[lane] = matched
return {"scores": scores, "hits": hits}
def decide(scores: dict) -> dict:
ranked = sorted(scores.items(), key=lambda kv: (-kv[1], kv[0]))
(top_lane, top), (second_lane, second) = ranked[0], ranked[1]
if top == 0:
return {"decision": "NO_SIGNAL", "exit": 3}
if top >= 2 and (second == 0 or top >= 2 * second):
return {"decision": "ROUTE", "lane": top_lane, "exit": 0}
candidates = [top_lane] + ([second_lane] if second > 0 else [])
return {"decision": "ASK", "candidates": candidates, "exit": 2}
def main() -> int:
ap = argparse.ArgumentParser(
description="Deterministic lane router for project-management goals."
)
src = ap.add_mutually_exclusive_group()
src.add_argument("--text", help="Goal / inquiry text to classify.")
src.add_argument("--input", help="Read goal text from a file ('-' for stdin).")
ap.add_argument("--output", choices=["json", "human"], default="json")
ap.add_argument("--sample", action="store_true",
help="Classify a built-in sample goal and exit.")
args = ap.parse_args()
if args.sample:
text = SAMPLE_GOAL
elif args.text:
text = args.text
elif args.input:
text = (sys.stdin.read() if args.input == "-"
else open(args.input, encoding="utf-8").read())
else:
ap.error("one of --text, --input, or --sample is required")
result = score(text)
verdict = decide(result["scores"])
out = {
"goal": text.strip()[:300],
"scores": {k: v for k, v in result["scores"].items() if v},
"decision": verdict["decision"],
}
if verdict["decision"] == "ROUTE":
lane = verdict["lane"]
out["route_to"] = SIGNALS[lane]["skill"]
out["skill_path"] = SIGNALS[lane]["path"]
out["matched_signals"] = result["hits"][lane]
elif verdict["decision"] == "ASK":
out["candidates"] = [
{"lane": lane, "skill": SIGNALS[lane]["skill"], "score": result["scores"][lane]}
for lane in verdict["candidates"]
]
out["instruction"] = ("Ask ONE clarifying question naming both candidate lanes, "
"with a recommended answer. Never guess silently.")
else:
out["instruction"] = ("No lane signal. Ask the user to restate the goal with the "
"deliverable named. Do not route on fuzz.")
if args.output == "json":
print(json.dumps(out, indent=2))
else:
print(f"Decision: {out['decision']}")
if "route_to" in out:
print(f"Route to: {out['route_to']} ({out['skill_path']})")
print(f"Signals: {', '.join(out['matched_signals'])}")
elif "candidates" in out:
names = " vs ".join(c["skill"] for c in out["candidates"])
print(f"Ambiguous: {names} — ask one clarifying question.")
else:
print("No signal — ask the user to restate the goal.")
return verdict["exit"]
if __name__ == "__main__":
sys.exit(main())