From 894fd233349b7289e98a0de9f7d168142cfa3e00 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 11 Jun 2026 03:58:42 +0000 Subject: [PATCH] feat(agents,commands): trigger descriptions + gated workflow upgrades - 17 root agents gained 'Use when...' trigger descriptions (<=1024 chars); cs-product-analyst placeholder body rewritten around real tools - 21 commands had invalid YAML frontmatter fixed (unquoted inner colons); 14 commands gained argument-hint; 6 duplicate commands marked with canonical-copy sync comments - /prd: forcing questions + refuse-to-draft gate + required-sections checklist - /sprint-plan: capacity math + carry-over check + definition-of-ready gate - /tdd: rebuilt around the real tdd-guide assets with smoke-tested snippets - cs-senior-engineer repointed from retired release-manager to changelog-generator https://claude.ai/code/session_019AJddAL1NADWMXsy1qNPQF --- agents/c-level/cs-ceo-advisor.md | 2 +- agents/c-level/cs-cto-advisor.md | 2 +- agents/engineering/cs-senior-engineer.md | 4 +- agents/marketing/cs-content-creator.md | 2 +- agents/marketing/cs-demand-gen-specialist.md | 2 +- agents/personas/content-strategist.md | 2 +- agents/personas/devops-engineer.md | 2 +- agents/personas/finance-lead.md | 2 +- agents/personas/growth-marketer.md | 2 +- agents/personas/product-manager.md | 2 +- agents/personas/solo-founder.md | 2 +- agents/personas/startup-cto.md | 2 +- agents/product/cs-agile-product-owner.md | 2 +- agents/product/cs-product-analyst.md | 80 +++++++++++++++--- agents/product/cs-product-manager.md | 2 +- agents/product/cs-product-strategist.md | 2 +- agents/product/cs-ux-researcher.md | 2 +- .../project-management/cs-project-manager.md | 2 +- commands/a11y-audit.md | 3 +- commands/changelog.md | 3 +- commands/code-to-prd.md | 3 +- commands/competitive-matrix.md | 3 +- commands/cs-engineer-grill.md | 2 +- commands/financial-health.md | 3 +- commands/focused-fix.md | 2 +- commands/google-workspace.md | 1 + commands/karpathy-check.md | 1 + commands/okr.md | 2 +- commands/persona.md | 2 +- commands/pipeline.md | 3 +- commands/plugin-audit.md | 1 + commands/prd.md | 61 +++++++++++--- commands/project-health.md | 3 +- commands/retro.md | 2 +- commands/rice.md | 2 +- commands/saas-health.md | 3 +- commands/seo-auditor.md | 3 +- commands/sprint-health.md | 3 +- commands/sprint-plan.md | 64 ++++++++++++--- commands/tc.md | 2 +- commands/tdd.md | 82 ++++++++++++++----- commands/tech-debt.md | 3 +- commands/user-story.md | 3 +- commands/wiki-ingest.md | 1 + commands/wiki-init.md | 1 + commands/wiki-lint.md | 1 + commands/wiki-log.md | 1 + commands/wiki-query.md | 1 + 48 files changed, 291 insertions(+), 90 deletions(-) diff --git a/agents/c-level/cs-ceo-advisor.md b/agents/c-level/cs-ceo-advisor.md index 487217e4..62ee739a 100644 --- a/agents/c-level/cs-ceo-advisor.md +++ b/agents/c-level/cs-ceo-advisor.md @@ -1,6 +1,6 @@ --- name: cs-ceo-advisor -description: Strategic leadership advisor for CEOs covering vision, strategy, board management, investor relations, and organizational culture +description: Strategic leadership advisor for CEOs covering vision, strategy, board management, investor relations, and organizational culture. Use when a founder or CEO faces a company-level strategic decision — e.g., preparing the narrative and metrics for a quarterly board meeting, or stress-testing a pivot or market-expansion decision against vision, runway, and stakeholder expectations. skills: c-level-advisor/skills/ceo-advisor domain: c-level model: opus diff --git a/agents/c-level/cs-cto-advisor.md b/agents/c-level/cs-cto-advisor.md index 5ea55e95..0e71debc 100644 --- a/agents/c-level/cs-cto-advisor.md +++ b/agents/c-level/cs-cto-advisor.md @@ -1,6 +1,6 @@ --- name: cs-cto-advisor -description: Technical leadership advisor for CTOs covering technology strategy, team scaling, architecture decisions, and engineering excellence +description: Technical leadership advisor for CTOs covering technology strategy, team scaling, architecture decisions, and engineering excellence. Use when a CTO or technical founder needs company-level technology judgment — e.g., deciding build-vs-buy for a core platform component, or planning how to scale the engineering org from 5 to 30 engineers without losing delivery velocity. skills: c-level-advisor/skills/cto-advisor domain: c-level model: opus diff --git a/agents/engineering/cs-senior-engineer.md b/agents/engineering/cs-senior-engineer.md index 7bdaa5d8..791e8cb3 100644 --- a/agents/engineering/cs-senior-engineer.md +++ b/agents/engineering/cs-senior-engineer.md @@ -31,7 +31,7 @@ Cross-cutting senior engineer covering architecture, backend, DevOps, security, ### DevOps & Delivery - `engineering/ci-cd-pipeline-builder` — Pipeline generation (GitHub Actions, GitLab CI) -- `engineering/release-manager` — Release planning and execution +- `engineering/skills/changelog-generator` — Changelog generation, version bumping, release notes - `engineering-team/senior-devops` — Infrastructure and deployment - `engineering/observability-designer` — Monitoring and alerting @@ -62,7 +62,7 @@ Cross-cutting senior engineer covering architecture, backend, DevOps, security, 2. Generate pipeline config (build, test, lint, deploy stages) 3. Add security scanning via `dependency-auditor` 4. Configure observability via `observability-designer` -5. Set up release process via `release-manager` +5. Set up release process via `changelog-generator` ### 4. Feature Repair (Deep-Dive Debugging) 1. Identify broken feature scope via `focused-fix` Phase 1 (SCOPE) diff --git a/agents/marketing/cs-content-creator.md b/agents/marketing/cs-content-creator.md index 8a8942a1..4ac26375 100644 --- a/agents/marketing/cs-content-creator.md +++ b/agents/marketing/cs-content-creator.md @@ -1,6 +1,6 @@ --- name: cs-content-creator -description: AI-powered content creation specialist for brand voice consistency, SEO optimization, and multi-platform content strategy +description: AI-powered content creation specialist for brand voice consistency, SEO optimization, and multi-platform content strategy. Use when producing or reviewing marketing content that must stay on-brand and rank — e.g., turning one pillar blog post into a LinkedIn/X/newsletter bundle, or auditing draft copy against an established brand voice profile before publishing. skills: marketing-skill/content-creator domain: marketing model: sonnet diff --git a/agents/marketing/cs-demand-gen-specialist.md b/agents/marketing/cs-demand-gen-specialist.md index e6bcf848..e2edd2ee 100644 --- a/agents/marketing/cs-demand-gen-specialist.md +++ b/agents/marketing/cs-demand-gen-specialist.md @@ -1,6 +1,6 @@ --- name: cs-demand-gen-specialist -description: Demand generation and customer acquisition specialist for lead generation, conversion optimization, and multi-channel acquisition campaigns +description: Demand generation and customer acquisition specialist for lead generation, conversion optimization, and multi-channel acquisition campaigns. Use when building or fixing the acquisition funnel — e.g., diagnosing why MQL-to-SQL conversion dropped after a pricing change, or designing a multi-channel campaign plan with budget split across paid, content, and email. skills: marketing-skill/marketing-demand-acquisition domain: marketing model: sonnet diff --git a/agents/personas/content-strategist.md b/agents/personas/content-strategist.md index ecac08a9..d8dca130 100644 --- a/agents/personas/content-strategist.md +++ b/agents/personas/content-strategist.md @@ -1,6 +1,6 @@ --- name: Content Strategist -description: Builds content engines that rank, convert, and compound. Thinks in systems — topic clusters, not individual posts. Every piece earns its place or gets killed. +description: Builds content engines that rank, convert, and compound. Thinks in systems — topic clusters, not individual posts. Every piece earns its place or gets killed. Use when content needs to behave like a system rather than a stream of posts — e.g., designing a topic-cluster plan to grow organic traffic from zero, or auditing an editorial calendar and killing pieces that don't convert after 90 days. (For single-asset, on-brand copy production, see cs-content-creator.) color: purple emoji: ✍️ vibe: Turns a blank editorial calendar into a traffic machine — then optimizes every word until it converts. diff --git a/agents/personas/devops-engineer.md b/agents/personas/devops-engineer.md index e1ba9bbd..608d84de 100644 --- a/agents/personas/devops-engineer.md +++ b/agents/personas/devops-engineer.md @@ -1,6 +1,6 @@ --- name: DevOps Engineer -description: Builds infrastructure that scales without babysitting. Automates everything worth automating. Monitors before it breaks. Treats clicking in consoles as a production incident waiting to happen. +description: Builds infrastructure that scales without babysitting. Automates everything worth automating. Monitors before it breaks. Treats clicking in consoles as a production incident waiting to happen. Use when infrastructure or delivery needs automation and observability — e.g., designing a CI/CD pipeline for a small team that deploys daily, or adding monitoring, alerts, and runbooks before a launch. color: orange emoji: 🔧 vibe: If it's not automated, it's broken. If it's not monitored, it's already down. diff --git a/agents/personas/finance-lead.md b/agents/personas/finance-lead.md index e7f28863..d6a37a49 100644 --- a/agents/personas/finance-lead.md +++ b/agents/personas/finance-lead.md @@ -1,6 +1,6 @@ --- name: Finance Lead -description: Startup CFO who builds models that survive contact with reality. Handles fundraising, unit economics, pricing, burn rate, and board reporting. Speaks fluent spreadsheet but translates to English for founders who'd rather build product. +description: Startup CFO who builds models that survive contact with reality. Handles fundraising, unit economics, pricing, burn rate, and board reporting. Speaks fluent spreadsheet but translates to English for founders who'd rather build product. Use when a money question needs a model, not a vibe — e.g., building an 18-month runway plan with three scenarios, or pressure-testing unit economics and pricing before a fundraise. (For DCF and SaaS-metrics tooling, see cs-financial-analyst.) color: gold emoji: 💰 vibe: Turns "we're running out of money" panic into a calm 18-month runway plan — with three scenarios. diff --git a/agents/personas/growth-marketer.md b/agents/personas/growth-marketer.md index 059a5a65..c526bccf 100644 --- a/agents/personas/growth-marketer.md +++ b/agents/personas/growth-marketer.md @@ -1,6 +1,6 @@ --- name: Growth Marketer -description: Growth marketing specialist for bootstrapped startups and indie hackers. Builds content engines, optimizes funnels, runs launch sequences, and finds scalable acquisition channels — all on a budget that makes enterprise marketers cry. +description: Growth marketing specialist for bootstrapped startups and indie hackers. Builds content engines, optimizes funnels, runs launch sequences, and finds scalable acquisition channels — all on a budget that makes enterprise marketers cry. Use when growth has to come before budget — e.g., planning a Product Hunt launch sequence, or choosing which organic channel (SEO, content, community) to invest in first at zero ad spend. (For funnel diagnostics with paid budget, see cs-demand-gen-specialist.) color: green emoji: 🚀 vibe: Finds the growth channel nobody's exploited yet — then scales it before the budget runs out. diff --git a/agents/personas/product-manager.md b/agents/personas/product-manager.md index 0f449292..42f17f78 100644 --- a/agents/personas/product-manager.md +++ b/agents/personas/product-manager.md @@ -1,6 +1,6 @@ --- name: Product Manager -description: Ships outcomes, not features. Writes specs engineers actually read. Prioritizes ruthlessly. Kills darlings when the data says so. Operates at the intersection of user needs, business goals, and engineering reality. +description: Ships outcomes, not features. Writes specs engineers actually read. Prioritizes ruthlessly. Kills darlings when the data says so. Operates at the intersection of user needs, business goals, and engineering reality. Use when product work needs ruthless prioritization and a success metric — e.g., turning vague stakeholder asks into a 2-page spec, or deciding which of three competing roadmap bets to fund this quarter. (For framework-heavy RICE/PRD tooling, see cs-product-manager.) color: blue emoji: 📋 vibe: Turns vague stakeholder wishes into shippable specs — then measures if anyone cared. diff --git a/agents/personas/solo-founder.md b/agents/personas/solo-founder.md index 8e440328..acf0169c 100644 --- a/agents/personas/solo-founder.md +++ b/agents/personas/solo-founder.md @@ -1,6 +1,6 @@ --- name: Solo Founder -description: Your co-founder who doesn't exist yet. Covers product, engineering, marketing, and strategy for one-person startups — because nobody's stopping you from making bad decisions and somebody should. +description: Your co-founder who doesn't exist yet. Covers product, engineering, marketing, and strategy for one-person startups — because nobody's stopping you from making bad decisions and somebody should. Use when a solo founder or indie hacker needs a cross-functional thinking partner — e.g., deciding what to cut from an MVP to ship this month, or choosing between building one more feature and talking to ten users. color: purple emoji: 🦄 vibe: The co-founder you can't afford yet — covers product, eng, marketing, and the hard questions. diff --git a/agents/personas/startup-cto.md b/agents/personas/startup-cto.md index 262a6384..003e6fc9 100644 --- a/agents/personas/startup-cto.md +++ b/agents/personas/startup-cto.md @@ -1,6 +1,6 @@ --- name: Startup CTO -description: Technical co-founder who's been through two startups and learned what actually matters. Makes architecture decisions, selects tech stacks, builds engineering culture, and prepares for technical due diligence — all while shipping fast with a small team. +description: Technical co-founder who's been through two startups and learned what actually matters. Makes architecture decisions, selects tech stacks, builds engineering culture, and prepares for technical due diligence — all while shipping fast with a small team. Use when an early-stage team needs pragmatic, ship-first technical leadership — e.g., picking a boring-but-fast stack for an MVP with two engineers, or prepping architecture answers for investor due diligence. (For company-scale CTO strategy, see cs-cto-advisor.) color: blue emoji: 🏗️ vibe: Ships fast, stays pragmatic, and won't let you Kubernetes your way out of 50 users. diff --git a/agents/product/cs-agile-product-owner.md b/agents/product/cs-agile-product-owner.md index 51c225ca..4b7d1962 100644 --- a/agents/product/cs-agile-product-owner.md +++ b/agents/product/cs-agile-product-owner.md @@ -1,6 +1,6 @@ --- name: cs-agile-product-owner -description: Agile product owner agent for epic breakdown, sprint planning, backlog refinement, and INVEST-compliant user story generation +description: Agile product owner agent for epic breakdown, sprint planning, backlog refinement, and INVEST-compliant user story generation. Use when preparing work for a development team — e.g., decomposing a large epic into INVEST-compliant stories with acceptance criteria, or refining a messy backlog ahead of sprint planning. skills: product-team/agile-product-owner, product-team/product-manager-toolkit domain: product model: sonnet diff --git a/agents/product/cs-product-analyst.md b/agents/product/cs-product-analyst.md index a54e8805..4d5a00ea 100644 --- a/agents/product/cs-product-analyst.md +++ b/agents/product/cs-product-analyst.md @@ -1,6 +1,6 @@ --- name: cs-product-analyst -description: Product analytics agent for KPI definition, dashboard setup, experiment design, and test result interpretation. +description: Product analytics agent for KPI definition, dashboard setup, experiment design, and test result interpretation. Use when a product question needs numbers — e.g., defining activation/retention KPIs and a dashboard spec for a new feature, or sizing an A/B test and judging whether the result is significant enough to ship. skills: - product-team/product-analytics - product-team/experiment-designer @@ -11,21 +11,77 @@ tools: [Read, Write, Bash, Grep, Glob] # Product Analyst Agent -## Skill Links -- `../../product-team/skills/product-analytics/SKILL.md` -- `../../product-team/skills/experiment-designer/SKILL.md` +## Purpose -## Primary Workflows -1. Metric framework and KPI definition -2. Dashboard design and cohort/retention analysis -3. Experiment design with hypothesis + sample sizing -4. Result interpretation and decision recommendations +The cs-product-analyst agent turns product questions into measurable answers. It orchestrates the product-analytics and experiment-designer skills to define metric frameworks, compute retention/cohort/funnel metrics from raw CSV exports, size experiments before they run, and interpret results after they finish — separating statistical significance from practical business significance. -## Tooling -- `../../product-team/skills/product-analytics/scripts/metrics_calculator.py` -- `../../product-team/skills/experiment-designer/scripts/sample_size_calculator.py` +Use this agent instead of cs-product-manager when the work is quantitative: the PM agent decides *what* to build; this agent measures *whether it worked*. + +## Skill Integration + +**Skill Locations:** +- `../../product-team/skills/product-analytics/` ([SKILL.md](../../product-team/skills/product-analytics/SKILL.md)) +- `../../product-team/skills/experiment-designer/` ([SKILL.md](../../product-team/skills/experiment-designer/SKILL.md)) + +### Python Tools + +1. **Metrics Calculator** + - **Purpose:** Retention by day, cohort retention matrices, and funnel conversion by stage from CSV event data + - **Path:** `../../product-team/skills/product-analytics/scripts/metrics_calculator.py` + - **Usage:** `python ../../product-team/skills/product-analytics/scripts/metrics_calculator.py retention events.csv` (subcommands: `retention`, `cohort`, `funnel`) + +2. **Sample Size Calculator** + - **Purpose:** Two-proportion experiment sizing with alpha/power and absolute or relative MDE + - **Path:** `../../product-team/skills/experiment-designer/scripts/sample_size_calculator.py` + - **Usage:** `python ../../product-team/skills/experiment-designer/scripts/sample_size_calculator.py --baseline-rate 0.12 --mde 0.02 --mde-type absolute --daily-samples 800` + +## Workflows + +### Workflow 1: Metric Framework and KPI Definition + +**Goal:** Define the decision metric, supporting metrics, and guardrails for a feature before any analysis runs. + +**Steps:** +1. **Name the decision** the metric will drive (ship/iterate/kill) — refuse to pick KPIs without it +2. **Choose one primary metric** (activation, retention, conversion) plus 2-3 guardrails (latency, support tickets, churn) +3. **Specify the dashboard**: data source, granularity, owner, and review cadence + +**Expected Output:** A one-page metric spec with primary KPI, guardrails, and dashboard layout. + +### Workflow 2: Retention / Cohort / Funnel Analysis + +**Goal:** Quantify how users actually behave from raw event exports. + +**Steps:** +1. Export events to CSV (user_id, timestamp, event) +2. Run `metrics_calculator.py retention|cohort|funnel` on the export +3. Annotate the output: where the curve flattens, which cohort improved, which funnel stage leaks most + +**Expected Output:** Retention curve / cohort matrix / funnel table with a written interpretation and one recommended action. + +### Workflow 3: Experiment Design and Result Interpretation + +**Goal:** Size a test before launch; judge the result after. + +**Steps:** +1. State hypothesis and minimum detectable effect worth acting on +2. Run `sample_size_calculator.py` to get required n and runtime at current traffic +3. After the test, compare observed lift against the MDE; check guardrails; pair statistical significance with practical significance before recommending ship/iterate/kill + +**Expected Output:** Pre-registered test plan, then a decision memo with effect size, confidence, guardrail status, and recommendation. ## Usage Notes + - Define decision metrics before analysis to avoid post-hoc bias. - Pair statistical interpretation with practical business significance. - Use guardrail metrics to prevent local optimization mistakes. + +## Related Agents + +- [cs-product-manager](cs-product-manager.md) - Prioritization and PRDs; hands measurement questions to this agent +- [cs-ux-researcher](cs-ux-researcher.md) - Qualitative evidence to explain the "why" behind metric movements + +## References + +- [Product Analytics Skill](../../product-team/skills/product-analytics/SKILL.md) +- [Experiment Designer Skill](../../product-team/skills/experiment-designer/SKILL.md) diff --git a/agents/product/cs-product-manager.md b/agents/product/cs-product-manager.md index a8e5774d..b429814a 100644 --- a/agents/product/cs-product-manager.md +++ b/agents/product/cs-product-manager.md @@ -1,6 +1,6 @@ --- name: cs-product-manager -description: Product management agent for feature prioritization, customer discovery, PRD development, and roadmap planning using RICE framework +description: Product management agent for feature prioritization, customer discovery, PRD development, and roadmap planning using RICE framework. Use when a product decision needs structure and evidence — e.g., RICE-scoring a backlog of 20 feature requests before quarterly planning, or drafting a PRD from raw customer-interview notes. skills: product-team/product-manager-toolkit, product-team/agile-product-owner, product-team/product-strategist, product-team/ux-researcher-designer, product-team/ui-design-system, product-team/competitive-teardown, product-team/landing-page-generator, product-team/saas-scaffolder domain: product model: sonnet diff --git a/agents/product/cs-product-strategist.md b/agents/product/cs-product-strategist.md index 86b1f228..5fa7161b 100644 --- a/agents/product/cs-product-strategist.md +++ b/agents/product/cs-product-strategist.md @@ -1,6 +1,6 @@ --- name: cs-product-strategist -description: Product strategy agent for quarterly OKR planning, competitive landscape analysis, product vision development, and strategy pivot evaluation +description: Product strategy agent for quarterly OKR planning, competitive landscape analysis, product vision development, and strategy pivot evaluation. Use when the question is direction rather than delivery — e.g., cascading company OKRs into product-team objectives for next quarter, or running a competitive teardown to decide whether to enter an adjacent market. skills: product-team/product-strategist, product-team/competitive-teardown, product-team/product-manager-toolkit domain: product model: sonnet diff --git a/agents/product/cs-ux-researcher.md b/agents/product/cs-ux-researcher.md index 830cb519..3c3969d3 100644 --- a/agents/product/cs-ux-researcher.md +++ b/agents/product/cs-ux-researcher.md @@ -1,6 +1,6 @@ --- name: cs-ux-researcher -description: UX research agent for research planning, persona generation, journey mapping, and usability test analysis +description: UX research agent for research planning, persona generation, journey mapping, and usability test analysis. Use when product decisions need user evidence — e.g., planning interview scripts and recruiting criteria for a discovery study, or synthesizing usability-test sessions into prioritized findings and updated personas. skills: product-team/ux-researcher-designer, product-team/product-manager-toolkit, product-team/ui-design-system domain: product model: sonnet diff --git a/agents/project-management/cs-project-manager.md b/agents/project-management/cs-project-manager.md index 8a06df65..094a508b 100644 --- a/agents/project-management/cs-project-manager.md +++ b/agents/project-management/cs-project-manager.md @@ -1,6 +1,6 @@ --- name: cs-project-manager -description: Project Manager agent for sprint planning, Jira/Confluence workflows, Scrum ceremonies, and stakeholder reporting. Orchestrates project-management skills. +description: Project Manager agent for sprint planning, Jira/Confluence workflows, Scrum ceremonies, and stakeholder reporting. Orchestrates project-management skills. Use when running delivery operations — e.g., planning a sprint with capacity and carry-over math in Jira, or assembling a portfolio health report for stakeholders from ticket and velocity data. skills: project-management domain: pm model: sonnet diff --git a/commands/a11y-audit.md b/commands/a11y-audit.md index 9a8ff7e0..0b9309f1 100644 --- a/commands/a11y-audit.md +++ b/commands/a11y-audit.md @@ -1,6 +1,7 @@ --- name: a11y-audit -description: Scan a frontend project for WCAG 2.2 accessibility violations and fix them. Usage: /a11y-audit [path] +description: "Scan a frontend project for WCAG 2.2 accessibility violations and fix them. Usage: /a11y-audit [path]" +argument-hint: "[path]" --- # /a11y-audit diff --git a/commands/changelog.md b/commands/changelog.md index d7978893..711c1e97 100644 --- a/commands/changelog.md +++ b/commands/changelog.md @@ -1,6 +1,7 @@ --- name: changelog -description: Generate changelogs from git history and validate conventional commits. Usage: /changelog [options] +description: "Generate changelogs from git history and validate conventional commits. Usage: /changelog [options]" +argument-hint: " [options]" --- # /changelog diff --git a/commands/code-to-prd.md b/commands/code-to-prd.md index ac6f88c4..3ba85b42 100644 --- a/commands/code-to-prd.md +++ b/commands/code-to-prd.md @@ -1,6 +1,7 @@ --- name: code-to-prd -description: Reverse-engineer a frontend codebase into a PRD. Usage: /code-to-prd [path] +description: "Reverse-engineer a frontend codebase into a PRD. Usage: /code-to-prd [path]" +argument-hint: "[path]" --- # /code-to-prd diff --git a/commands/competitive-matrix.md b/commands/competitive-matrix.md index 3e9122af..394615cd 100644 --- a/commands/competitive-matrix.md +++ b/commands/competitive-matrix.md @@ -1,6 +1,7 @@ --- name: competitive-matrix -description: Build competitive analysis matrices with scoring and gap analysis. Usage: /competitive-matrix [options] +description: "Build competitive analysis matrices with scoring and gap analysis. Usage: /competitive-matrix [options]" +argument-hint: " [options]" --- # /competitive-matrix diff --git a/commands/cs-engineer-grill.md b/commands/cs-engineer-grill.md index a8aeabda..1393882b 100644 --- a/commands/cs-engineer-grill.md +++ b/commands/cs-engineer-grill.md @@ -1,5 +1,5 @@ --- -description: Cross-role engineering grill — Matt Pocock 7 questions per role × 3 roles (fullstack / frontend / backend) = up to 21 forcing questions, one per turn, with canon citations and kill criteria. Default: ask which lane first; `--all` runs all 21. +description: "Cross-role engineering grill — Matt Pocock 7 questions per role × 3 roles (fullstack / frontend / backend) = up to 21 forcing questions, one per turn, with canon citations and kill criteria. Default: ask which lane first; `--all` runs all 21." argument-hint: " [--lane fullstack|frontend|backend|all]" --- diff --git a/commands/financial-health.md b/commands/financial-health.md index f39d366f..7b606f4e 100644 --- a/commands/financial-health.md +++ b/commands/financial-health.md @@ -1,6 +1,7 @@ --- name: financial-health -description: Run financial ratio analysis, DCF valuation, budget variance analysis, and rolling forecasts. Usage: /financial-health +description: "Run financial ratio analysis, DCF valuation, budget variance analysis, and rolling forecasts. Usage: /financial-health " +argument-hint: " " --- # /financial-health diff --git a/commands/focused-fix.md b/commands/focused-fix.md index 90ba532c..ea4c493e 100644 --- a/commands/focused-fix.md +++ b/commands/focused-fix.md @@ -1,6 +1,6 @@ --- name: focused-fix -description: Deep-dive feature repair — systematically fix an entire feature/module across all its files and dependencies. Usage: /focused-fix +description: "Deep-dive feature repair — systematically fix an entire feature/module across all its files and dependencies. Usage: /focused-fix " --- # /focused-fix diff --git a/commands/google-workspace.md b/commands/google-workspace.md index 02c18ebf..9796f26f 100644 --- a/commands/google-workspace.md +++ b/commands/google-workspace.md @@ -1,6 +1,7 @@ --- name: google-workspace description: "Google Workspace CLI operations: setup diagnostics, security audit, recipe discovery, and output analysis. Usage: /google-workspace [options]" +argument-hint: " [options]" --- # /google-workspace diff --git a/commands/karpathy-check.md b/commands/karpathy-check.md index a2262dd5..b754e523 100644 --- a/commands/karpathy-check.md +++ b/commands/karpathy-check.md @@ -2,6 +2,7 @@ name: karpathy-check description: Run Karpathy's 4-principle review on staged changes or the last commit. Checks complexity, diff noise, hidden assumptions, and goal verification. Usage /karpathy-check [--last-commit] --- + # /karpathy-check diff --git a/commands/okr.md b/commands/okr.md index f17bec33..7121bf8a 100644 --- a/commands/okr.md +++ b/commands/okr.md @@ -1,6 +1,6 @@ --- name: okr -description: Generate OKR cascades from company strategy to team objectives. Usage: /okr generate +description: "Generate OKR cascades from company strategy to team objectives. Usage: /okr generate " --- # /okr diff --git a/commands/persona.md b/commands/persona.md index fb9a1b75..f4257000 100644 --- a/commands/persona.md +++ b/commands/persona.md @@ -1,6 +1,6 @@ --- name: persona -description: Generate data-driven user personas for UX research and product design. Usage: /persona generate [options] +description: "Generate data-driven user personas for UX research and product design. Usage: /persona generate [options]" --- # /persona diff --git a/commands/pipeline.md b/commands/pipeline.md index 2319666e..10b18247 100644 --- a/commands/pipeline.md +++ b/commands/pipeline.md @@ -1,6 +1,7 @@ --- name: pipeline -description: Detect stack and generate CI/CD pipeline configs. Usage: /pipeline [options] +description: "Detect stack and generate CI/CD pipeline configs. Usage: /pipeline [options]" +argument-hint: " [options]" --- # /pipeline diff --git a/commands/plugin-audit.md b/commands/plugin-audit.md index f68e44c8..8424c7b6 100644 --- a/commands/plugin-audit.md +++ b/commands/plugin-audit.md @@ -5,6 +5,7 @@ description: | quality, security, marketplace compliance, cross-platform compatibility, and ecosystem integration. Runs all built-in validation tools, invokes domain-appropriate agents for code review, and produces a pass/fail gate report. Usage: /plugin-audit +argument-hint: "" --- # /plugin-audit diff --git a/commands/prd.md b/commands/prd.md index cdb35dd2..00f4c11d 100644 --- a/commands/prd.md +++ b/commands/prd.md @@ -1,11 +1,12 @@ --- name: prd -description: Quick PRD generation command. Usage: /prd +description: "Gated PRD generation — interrogates problem, user, and metric before drafting; refuses to draft on unknowns. Usage: /prd " +argument-hint: --- # /prd -Generate a concise product requirements document for a feature, initiative, or problem statement. +Generate a concise, evidence-gated product requirements document for `$ARGUMENTS`. ## Usage @@ -13,13 +14,53 @@ Generate a concise product requirements document for a feature, initiative, or p /prd ``` -## Output Structure +`$ARGUMENTS` is the feature, initiative, or problem statement. If empty, ask for it before doing anything else. -- Problem statement -- Goals and non-goals -- User stories and acceptance criteria -- Metrics and success thresholds -- Scope and timeline assumptions +## Phase 1 — Forcing Questions (before any drafting) -## Skill Reference -- `product-team/skills/product-manager-toolkit/SKILL.md` +Walk these one at a time. Do not batch them. Each answer feeds a required PRD section. + +1. **Problem** — What user problem does this solve, and how do you know it exists? (Evidence: support tickets, interview quotes, funnel data — "the CEO wants it" is not evidence.) +2. **User** — Who specifically has this problem? (Segment, role, frequency of pain. "Everyone" is a non-answer.) +3. **Metric** — What single number moves if this works, by how much, measured where? +4. **Alternatives** — What do these users do today instead? Why is that not good enough? +5. **Non-goals** — What adjacent asks are explicitly out of scope for v1? + +## Drafting Gate (hard refusal) + +**Refuse to draft the PRD if the answer to question 1 (problem), 2 (user), or 3 (metric) is unknown, circular, or "we'll figure it out later."** Instead, output the open questions and the cheapest way to answer each (e.g., 5 customer interviews, a funnel query, a fake-door test). A PRD without a problem, a user, and a metric is a feature wish, not a requirements document. + +## Phase 2 — Draft (required-sections checklist) + +Every PRD must contain all of these sections — emit the checklist at the end and mark each: + +- [ ] Problem statement (with the evidence from Q1) +- [ ] Target user and segment (from Q2) +- [ ] Goals and explicit non-goals (from Q5) +- [ ] User stories with acceptance criteria +- [ ] Success metric + threshold + measurement source (from Q3) +- [ ] Alternatives considered / "do nothing" baseline (from Q4) +- [ ] Scope, dependencies, and timeline assumptions +- [ ] Open questions and risks + +Keep it to ~2 pages. Use the repo template as the skeleton. + +## Phase 3 — Prioritization hook (optional) + +If the user has multiple candidate features, offer to RICE-score them before committing the PRD: + +```bash +python3 product-team/skills/product-manager-toolkit/scripts/rice_prioritizer.py features.csv --capacity 20 +``` + +## Repo Assets (verified paths) + +- Skill: `product-team/skills/product-manager-toolkit/SKILL.md` +- PRD template: `product-team/skills/product-manager-toolkit/assets/prd_template.md` +- PRD patterns reference: `product-team/skills/product-manager-toolkit/references/prd_templates.md` +- RICE tool: `product-team/skills/product-manager-toolkit/scripts/rice_prioritizer.py` + +## Related + +- `/code-to-prd` — reverse-engineer a PRD from an existing codebase +- `/rice` — standalone RICE prioritization diff --git a/commands/project-health.md b/commands/project-health.md index 34c1d2b8..a27744e4 100644 --- a/commands/project-health.md +++ b/commands/project-health.md @@ -1,6 +1,7 @@ --- name: project-health -description: Portfolio health dashboard and risk matrix analysis. Usage: /project-health [options] +description: "Portfolio health dashboard and risk matrix analysis. Usage: /project-health [options]" +argument-hint: " [options]" --- # /project-health diff --git a/commands/retro.md b/commands/retro.md index 52c67471..e7688042 100644 --- a/commands/retro.md +++ b/commands/retro.md @@ -1,6 +1,6 @@ --- name: retro -description: Analyze sprint retrospectives for patterns and action item tracking. Usage: /retro analyze +description: "Analyze sprint retrospectives for patterns and action item tracking. Usage: /retro analyze " --- # /retro diff --git a/commands/rice.md b/commands/rice.md index 93390ea0..692c0377 100644 --- a/commands/rice.md +++ b/commands/rice.md @@ -1,6 +1,6 @@ --- name: rice -description: RICE feature prioritization with scoring and capacity planning. Usage: /rice prioritize [options] +description: "RICE feature prioritization with scoring and capacity planning. Usage: /rice prioritize [options]" --- # /rice diff --git a/commands/saas-health.md b/commands/saas-health.md index 58ed3a29..4add2248 100644 --- a/commands/saas-health.md +++ b/commands/saas-health.md @@ -1,6 +1,7 @@ --- name: saas-health -description: Calculate SaaS health metrics (ARR, MRR, churn, CAC, LTV, NRR) and benchmark against industry standards. Usage: /saas-health [options] +description: "Calculate SaaS health metrics (ARR, MRR, churn, CAC, LTV, NRR) and benchmark against industry standards. Usage: /saas-health [options]" +argument-hint: " [options]" --- # /saas-health diff --git a/commands/seo-auditor.md b/commands/seo-auditor.md index 6f1cfbbb..41d7d65d 100644 --- a/commands/seo-auditor.md +++ b/commands/seo-auditor.md @@ -4,6 +4,7 @@ description: | Scan and optimize documentation files for SEO. Audits README.md files and docs/ pages for meta tags, headings, keywords, readability, duplicate content, and broken links. Applies fixes, updates sitemap.xml, and generates a report. Usage: /seo-auditor [path] +argument-hint: "[path]" --- # /seo-auditor @@ -333,7 +334,7 @@ These pages rank well for their target keywords. Only fix critical issues (broke | Reference | Path | Use | |-----------|------|-----| | SEO Audit Framework | `marketing-skill/skills/seo-audit/references/seo-audit-reference.md` | Priority order for SEO fixes | -| AI Search Optimization | `marketing-skill/skills/ai-seo/references/content-patterns.md` | Make content citable by AI | +| AI Search Optimization | `marketing-skill/skills/aeo/references/extractable_content_patterns.md` | Make content citable by AI | | Content Optimization | `marketing-skill/skills/content-production/references/optimization-checklist.md` | Pre-publish checklist | | URL Design Guide | `marketing-skill/skills/site-architecture/references/url-design-guide.md` | URL structure best practices | | Internal Linking | `marketing-skill/skills/site-architecture/references/internal-linking-playbook.md` | Internal linking strategy | diff --git a/commands/sprint-health.md b/commands/sprint-health.md index ce39bff3..f9a0266d 100644 --- a/commands/sprint-health.md +++ b/commands/sprint-health.md @@ -1,6 +1,7 @@ --- name: sprint-health -description: Sprint health scoring and velocity analysis for agile teams. Usage: /sprint-health [options] +description: "Sprint health scoring and velocity analysis for agile teams. Usage: /sprint-health [options]" +argument-hint: " [options]" --- # /sprint-health diff --git a/commands/sprint-plan.md b/commands/sprint-plan.md index 0355d2ee..03af357d 100644 --- a/commands/sprint-plan.md +++ b/commands/sprint-plan.md @@ -1,25 +1,69 @@ --- name: sprint-plan -description: Sprint planning shortcut. Usage: /sprint-plan [capacity] +description: "Capacity-gated sprint planning — runs capacity math, carry-over check, and a definition-of-ready gate before committing scope. Usage: /sprint-plan [capacity]" +argument-hint: [capacity-in-points-or-person-days] --- # /sprint-plan -Create a sprint plan with prioritized stories and capacity guardrails. +Create a sprint plan for `$ARGUMENTS` with explicit capacity math, a carry-over check, and a definition-of-ready gate. The first token(s) of `$ARGUMENTS` are the sprint goal; a trailing number is treated as team capacity (story points or person-days). If no capacity is given, compute it in Phase 1 — never invent it. ## Usage ```bash /sprint-plan [capacity] +# e.g. /sprint-plan "Checkout v2 ready for beta" 34 ``` -## Output Structure +## Phase 1 — Capacity Math (do the arithmetic, show it) -- Sprint goal -- Committed scope -- Stretch scope -- Risks and dependencies -- Story-level acceptance criteria checks +1. **Raw capacity** = team size × working days in sprint × focus factor (default 0.7; ask if unknown) +2. **Deductions** — subtract, explicitly and line by line: holidays/PTO, on-call/support rotation, ceremonies (~10%), known interrupts +3. **Velocity cross-check** — compare against the rolling average of the last 3 sprints' *completed* (not committed) points. If computed capacity exceeds trailing velocity by >15%, plan to trailing velocity and say so. -## Skill Reference -- `product-team/agile-product-owner/skills/agile-product-owner/SKILL.md` +Output a small table: raw → deductions → net capacity → trailing velocity → planning number. + +## Phase 2 — Carry-Over Check (before adding anything new) + +1. List every item carried over from the last sprint (not Done at sprint close) +2. Re-estimate *remaining* effort — never carry the original estimate +3. Carry-over consumes capacity **first**; new scope only gets what is left +4. If carry-over exceeds ~30% of capacity, flag it as a systemic over-commitment signal and recommend a smaller commitment this sprint, not a bigger push + +## Phase 3 — Definition-of-Ready Gate (per story) + +A story may enter the committed scope only if **all** of these hold — otherwise it goes to "needs refinement", not the sprint: + +- [ ] User story has a clear actor, action, and outcome (INVEST-compliant) +- [ ] Acceptance criteria written and testable +- [ ] Estimated by the team (not by the planner alone) +- [ ] Dependencies identified and either resolved or scheduled +- [ ] Small enough to finish within the sprint (split if not) + +Generate INVEST-checked stories from an epic with: + +```bash +python3 product-team/agile-product-owner/skills/agile-product-owner/scripts/user_story_generator.py +``` + +## Phase 4 — Output Structure + +- **Sprint goal** — one sentence; everything committed must serve it +- **Capacity table** — from Phase 1 +- **Carry-over** — from Phase 2, listed first in committed scope +- **Committed scope** — stories that passed the DoR gate, summing to ≤ planning number +- **Stretch scope** — clearly separated; pulled only if committed scope finishes +- **Risks and dependencies** — with named owners +- **DoR exceptions** — empty if the gate was honored; otherwise justify each + +## Repo Assets (verified paths) + +- Skill: `product-team/agile-product-owner/skills/agile-product-owner/SKILL.md` +- Sprint planning template: `product-team/agile-product-owner/skills/agile-product-owner/assets/sprint_planning_template.md` +- Sprint planning guide: `product-team/agile-product-owner/skills/agile-product-owner/references/sprint-planning-guide.md` +- Story generator: `product-team/agile-product-owner/skills/agile-product-owner/scripts/user_story_generator.py` + +## Related + +- `/sprint-health` — mid-sprint health check +- `/user-story` — single-story generation with INVEST checks diff --git a/commands/tc.md b/commands/tc.md index 85e034ed..5bf4bd4d 100644 --- a/commands/tc.md +++ b/commands/tc.md @@ -1,6 +1,6 @@ --- name: tc -description: Track technical changes with structured records, a state machine, and session handoff. Usage: /tc [args] +description: "Track technical changes with structured records, a state machine, and session handoff. Usage: /tc [args]" --- # /tc — Technical Change Tracker diff --git a/commands/tdd.md b/commands/tdd.md index d7b23ee9..f1c5f6f5 100644 --- a/commands/tdd.md +++ b/commands/tdd.md @@ -1,36 +1,76 @@ --- name: tdd -description: Generate tests, analyze coverage, and run TDD workflows. Usage: /tdd [options] +description: "Run a red-green-refactor TDD workflow — generate failing tests first, implement to green, then check coverage gaps. Usage: /tdd [target]" +argument-hint: [file-or-dir] --- # /tdd -Generate tests, analyze coverage, and validate test quality using the TDD Guide skill. +Drive a test-first workflow for `$ARGUMENTS` using the TDD Guide skill. The first word of `$ARGUMENTS` selects the mode (`generate`, `coverage`, or `validate`); the rest is the target file or directory. If `$ARGUMENTS` is empty, ask which mode and target. -## Usage +> **Note on tooling:** the tdd-guide scripts are **Python library modules, not CLI tools** — import them; do not invoke them as commands. Runnable patterns below. -``` -/tdd generate Generate tests for source files -/tdd coverage Analyze test coverage and gaps -/tdd validate Validate test quality (assertions, edge cases) +## Modes + +### `/tdd generate ` — write failing tests FIRST + +1. Read `engineering-team/skills/tdd-guide/SKILL.md` and `engineering-team/skills/tdd-guide/references/tdd-best-practices.md` for the red-green-refactor discipline and test-case taxonomy (happy path, edge cases, error cases) +2. Detect the project's test framework — use `engineering-team/skills/tdd-guide/references/framework-guide.md` for Jest/Vitest/pytest/JUnit conventions +3. Write the tests **before** any implementation; run them and confirm they FAIL (red) +4. Implement the minimum code to pass (green), then refactor with tests staying green +5. Optionally use the library for stub scaffolding: + +```bash +cd engineering-team/skills/tdd-guide/scripts && python3 -c " +from test_generator import TestGenerator, TestFramework +g = TestGenerator(framework=TestFramework.PYTEST, language='python') +cases = g.generate_from_requirements({'acceptance_criteria': [ + {'id': 'AC1', 'description': 'validates email format'}, + {'id': 'AC2', 'description': 'rejects duplicate emails'}]}) +print(g.generate_test_file('registration', cases)) +" ``` -## Examples +### `/tdd coverage ` — analyze gaps against a threshold -``` -/tdd generate src/auth/login.ts -/tdd coverage tests/ --threshold 80 -/tdd validate tests/auth.test.ts +1. Generate a real coverage report with the project's native runner first (`pytest --cov --cov-report=lcov`, `vitest run --coverage`, `jest --coverage`) +2. Parse it and list prioritized gaps: + +```bash +cd engineering-team/skills/tdd-guide/scripts && python3 -c " +from coverage_analyzer import CoverageAnalyzer +a = CoverageAnalyzer() +a.parse_coverage_report(open('').read(), 'lcov') # or 'json' / 'xml' +print(a.calculate_summary()) +for gap in a.identify_gaps(threshold=80.0): print(gap) +" ``` -## Scripts -- `engineering-team/skills/tdd-guide/scripts/test_generator.py` — Test case generation (library module) -- `engineering-team/skills/tdd-guide/scripts/coverage_analyzer.py` — Coverage analysis (library module) -- `engineering-team/skills/tdd-guide/scripts/tdd_workflow.py` — TDD workflow orchestration (library module) -- `engineering-team/skills/tdd-guide/scripts/fixture_generator.py` — Test fixture generation (library module) -- `engineering-team/skills/tdd-guide/scripts/metrics_calculator.py` — TDD metrics calculation (library module) +(Smoke-test input available at `engineering-team/skills/tdd-guide/assets/sample_coverage_report.lcov`.) -> **Note:** These scripts are library modules without CLI entry points. Import them in Python or use via the SKILL.md workflow guidance. +3. For each gap, return to `/tdd generate` — coverage gaps are filled with tests, not excuses -## Skill Reference -→ `engineering-team/skills/tdd-guide/SKILL.md` +### `/tdd validate ` — review test quality + +Read the test file and check it against `engineering-team/skills/tdd-guide/references/tdd-best-practices.md`: + +- [ ] Every test has at least one meaningful assertion (no assertion-free tests) +- [ ] Edge cases and error paths covered, not just happy path +- [ ] Tests are independent (no order coupling, no shared mutable state) +- [ ] Test names describe behavior, not implementation +- [ ] No testing of private internals — behavior only + +Report failures with concrete rewrite suggestions. + +## CI Integration + +For wiring coverage thresholds into CI, follow `engineering-team/skills/tdd-guide/references/ci-integration.md`. + +## Repo Assets (verified paths) + +- Skill: `engineering-team/skills/tdd-guide/SKILL.md` (+ `HOW_TO_USE.md`) +- Best practices: `engineering-team/skills/tdd-guide/references/tdd-best-practices.md` +- Framework conventions: `engineering-team/skills/tdd-guide/references/framework-guide.md` +- CI integration: `engineering-team/skills/tdd-guide/references/ci-integration.md` +- Library modules: `engineering-team/skills/tdd-guide/scripts/` (test_generator, coverage_analyzer, tdd_workflow, fixture_generator, metrics_calculator — import-only) +- Sample inputs: `engineering-team/skills/tdd-guide/assets/` diff --git a/commands/tech-debt.md b/commands/tech-debt.md index db153ef7..f87d251a 100644 --- a/commands/tech-debt.md +++ b/commands/tech-debt.md @@ -1,6 +1,7 @@ --- name: tech-debt -description: Scan, prioritize, and report technical debt. Usage: /tech-debt [options] +description: "Scan, prioritize, and report technical debt. Usage: /tech-debt [options]" +argument-hint: " [options]" --- # /tech-debt diff --git a/commands/user-story.md b/commands/user-story.md index 37cf215c..b885e649 100644 --- a/commands/user-story.md +++ b/commands/user-story.md @@ -1,6 +1,7 @@ --- name: user-story -description: Generate user stories with acceptance criteria and sprint planning. Usage: /user-story [options] +description: "Generate user stories with acceptance criteria and sprint planning. Usage: /user-story [options]" +argument-hint: " [options]" --- # /user-story diff --git a/commands/wiki-ingest.md b/commands/wiki-ingest.md index 92de1198..9b847d53 100644 --- a/commands/wiki-ingest.md +++ b/commands/wiki-ingest.md @@ -2,6 +2,7 @@ name: wiki-ingest description: Ingest a source file from raw/ into the LLM Wiki — read, discuss, write summary page, update cross-references across 5-15 pages, regenerate index, append to log. Usage /wiki-ingest --- + # /wiki-ingest diff --git a/commands/wiki-init.md b/commands/wiki-init.md index 3859f540..18c31a0e 100644 --- a/commands/wiki-init.md +++ b/commands/wiki-init.md @@ -2,6 +2,7 @@ name: wiki-init description: Bootstrap a fresh LLM Wiki vault with the three-layer structure, schema files, and starter templates. Usage /wiki-init --topic "" [--tool all|claude-code|codex|cursor|antigravity] --- + # /wiki-init diff --git a/commands/wiki-lint.md b/commands/wiki-lint.md index 27a5e3db..20029ddf 100644 --- a/commands/wiki-lint.md +++ b/commands/wiki-lint.md @@ -2,6 +2,7 @@ name: wiki-lint description: Run a health check on the LLM Wiki vault — mechanical checks (orphans, broken links, stale pages, missing frontmatter, log gap, duplicates) plus semantic checks (contradictions, cross-reference gaps, concepts missing their own page). Outputs a markdown report with suggested actions. Usage /wiki-lint [--stale-days N] [--log-gap-days N] --- + # /wiki-lint diff --git a/commands/wiki-log.md b/commands/wiki-log.md index 575c626f..9fa174bf 100644 --- a/commands/wiki-log.md +++ b/commands/wiki-log.md @@ -2,6 +2,7 @@ name: wiki-log description: Show recent entries from the LLM Wiki log (wiki/log.md). Uses the standardized ## [YYYY-MM-DD] header format so grep + tail works. Usage /wiki-log [--last N] [--op ingest|query|lint|...] --- + # /wiki-log diff --git a/commands/wiki-query.md b/commands/wiki-query.md index 1e485f69..f540d7ae 100644 --- a/commands/wiki-query.md +++ b/commands/wiki-query.md @@ -2,6 +2,7 @@ name: wiki-query description: Query the LLM Wiki — reads index.md first, drills into 3-10 relevant pages, synthesizes an answer with inline [[wikilink]] citations, and offers to file the answer back as a new comparison or synthesis page. Usage /wiki-query "" --- + # /wiki-query