diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 709ebec7..77c7c35d 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -4,18 +4,18 @@ "name": "Alireza Rezvani", "url": "https://alirezarezvani.com" }, - "description": "343 production-ready skill packages for Claude AI across 17 domains: engineering advanced (78, incl. v2.9.0 workflow-builder for Claude Code Workflow-tool authoring), engineering core (51), marketing (46 — incl. AEO/Answer Engine Optimization), c-level advisory (66), product (17), regulatory/QMS (18), compliance-os (9), project management (9), business growth (5), finance (4), productivity (6), marketing top-level (1), research (8), research-ops (5, v2.9.0), business-operations (7), commercial (8), and markdown-html (5, v2.10.3 — markdown-to-interactive-HTML converter complete: orchestrator + design-system + md-document long-form + md-review code-review + md-slides slide-deck). Includes 548 Python tools, 691 reference documents, 51+ agents, 90+ slash commands across 64 marketplace plugins.", + "description": "346 production-ready skill packages for Claude AI across 17 domains: engineering advanced (78, incl. v2.9.0 workflow-builder for Claude Code Workflow-tool authoring), engineering core (51), marketing (46 — incl. AEO/Answer Engine Optimization), c-level advisory (66), product (17), regulatory/QMS (18), compliance-os (9), project management (9), business growth (5), finance (4), productivity (6), marketing top-level (1), research (8), research-ops (5, v2.9.0), business-operations (7), commercial (8), and markdown-html (5, v2.10.3 — markdown-to-interactive-HTML converter complete: orchestrator + design-system + md-document long-form + md-review code-review + md-slides slide-deck). Includes 579 Python tools, 701 reference documents, 93 agents, 99 slash commands across 78 marketplace plugins.", "homepage": "https://github.com/alirezarezvani/claude-skills", "repository": "https://github.com/alirezarezvani/claude-skills", "metadata": { - "description": "343 production-ready skills across 17 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, plus standards). 548 Python tools, 691 reference guides, 51+ agents (cs-* + personas), 90+ slash commands across 64 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.", + "description": "345 production-ready skills across 17 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, plus standards). 579 Python tools, 702 reference guides, 93 agents (cs-* + personas), 99 slash commands across 78 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" }, "plugins": [ { "name": "marketing-skills", "source": "./marketing-skill", - "description": "44 marketing skills across 7 pods: Content, SEO, CRO, Channels, Growth, Intelligence, Sales enablement, and X/Twitter growth. 51 Python tools, 73 reference docs.", + "description": "44 marketing skills across 8 pods: Content, SEO & AEO, CRO, Channels, Growth, Intelligence, Sales enablement, and X/Twitter growth. 59 Python tools, 86 reference docs.", "version": "2.9.0", "author": { "name": "Alireza Rezvani" @@ -224,7 +224,7 @@ { "name": "engineering-advanced-skills", "source": "./engineering", - "description": "40 advanced engineering skills: agent designer, agent workflow designer, AgentHub, RAG architect, database designer, focused-fix, browser-automation, spec-driven-workflow, secrets-vault-manager, sql-database-assistant, migration architect, observability designer, dependency auditor, release manager, API reviewer, CI/CD pipeline builder, MCP server builder, skill security auditor, performance profiler, Helm chart builder, Terraform patterns, self-eval, llm-cost-optimizer, prompt-governance, behuman, code-tour, demo-video, data-quality-auditor, statistical-analyst, llm-wiki (second brain for Obsidian + Claude Code, Karpathy pattern), feature-flags-architect (flag debt scanner, rollout planner, kill-switch audit), kubernetes-operator (CRD validator, reconcile linter, capability auditor), chaos-engineering (experiment designer, blast-radius calculator, postmortem generator), ship-gate (pre-production 8-category audit with deploy-intent intercept), slo-architect (SLO designer, error-budget calculator with multi-window burn-rate alerts, SLO reviewer per Google SRE Workbook), and more.", + "description": "37 advanced engineering skills: agent designer, agent workflow designer, RAG architect, database designer + schema designer + SQL assistant, migration architect, observability designer, dependency auditor, changelog generator (with semantic version bumper and hotfix/rollback procedures), API design reviewer, API test suite builder, CI/CD pipeline builder, MCP server builder, skill security auditor, skill tester, performance profiler, focused-fix, browser-automation, full-page-screenshot, git-worktree-manager, monorepo-navigator, codebase-onboarding, interview-system-designer, runbook-generator, spec-driven-workflow, secrets-vault-manager, env-secrets-manager, pr-review-expert, self-eval, tc-tracker (task context tracker with lifecycle and handoff format), feature-flags-architect, kubernetes-operator, chaos-engineering, ship-gate (pre-production 8-category audit with deploy-intent intercept), slo-architect (SLO designer, error-budget calculator with multi-window burn-rate alerts, SLO reviewer per Google SRE Workbook), and tech-debt-tracker. Agent skill and plugin for Claude Code, Codex, Gemini CLI, Cursor, OpenClaw.", "version": "2.9.0", "author": { "name": "Alireza Rezvani" @@ -1448,6 +1448,227 @@ "transcriptapi" ], "category": "marketing" + }, + { + "name": "compliance-os", + "source": "./compliance-os", + "description": "Compliance OS — meta-orchestrator for multi-framework compliance programs spanning 9 frameworks (ISO 27001, ISO 13485, ISO 42001, ISO 14971, EU AI Act, MDR 745, GDPR, SOC 2, FDA QSR). Framework selector, cross-framework control mapper, audit simulator, and consolidated evidence-pool generator (stdlib Python), plus 3 cs-* compliance agents and 3 /cs:* readiness commands.", + "version": "2.9.0", + "author": { + "name": "Alireza Rezvani" + }, + "keywords": [ + "compliance", + "iso-27001", + "iso-42001", + "eu-ai-act", + "gdpr", + "soc2", + "audit", + "evidence", + "framework-mapping" + ], + "category": "compliance" + }, + { + "name": "snowflake-development", + "source": "./engineering-team/snowflake-development", + "description": "Snowflake SQL, data pipelines (Dynamic Tables, Streams+Tasks), Cortex AI functions, Snowpark Python, and dbt integration. Includes query helper script, reference guides, and troubleshooting.", + "version": "2.9.0", + "author": { + "name": "Alireza Rezvani" + }, + "keywords": [ + "snowflake", + "sql", + "data-pipelines", + "snowpark", + "dbt", + "cortex", + "data-warehouse" + ], + "category": "development" + }, + { + "name": "behuman", + "source": "./engineering/behuman", + "description": "Self-Mirror consciousness loop for human-like AI responses. Adds inner dialogue (Self → Mirror → Conscious Response) to make AI output feel authentic, not robotic. Zero dependencies — pure prompt technique.", + "version": "2.9.0", + "author": { + "name": "Alireza Rezvani" + }, + "keywords": [ + "prompting", + "voice", + "authenticity", + "self-mirror", + "writing" + ], + "category": "development" + }, + { + "name": "claude-coach", + "source": "./engineering/claude-coach", + "description": "Personal Claude power-user coach. Delivers a personalized, ranked cheat-code glossary on first activation, then surfaces at most one tip per turn when it would genuinely improve the next attempt. Ships cheat-codes glossary, coaching-rules decision tree, three stdlib Python tools, cs-claude-coach agent, and /cs:claude-coach command.", + "version": "2.9.0", + "author": { + "name": "Alireza Rezvani" + }, + "keywords": [ + "claude-code", + "coaching", + "power-user", + "tips", + "productivity" + ], + "category": "development" + }, + { + "name": "grill-with-docs", + "source": "./engineering/grill-with-docs", + "description": "Docs-anchored grilling session — interrogates a plan against the project's existing language (CONTEXT.md) and recorded decisions (docs/adr/), updating those files inline as terminology and decisions crystallise. Derived from Matt Pocock's MIT-licensed grill-with-docs with stdlib validators (CONTEXT.md linter, ADR scanner, glossary-code consistency), reference docs, cs-grill-with-docs agent, and /cs:grill-with-docs command.", + "version": "2.9.0", + "author": { + "name": "Alireza Rezvani" + }, + "keywords": [ + "planning", + "adr", + "context", + "ubiquitous-language", + "interrogation", + "matt-pocock" + ], + "category": "development" + }, + { + "name": "llm-cost-optimizer", + "source": "./engineering/llm-cost-optimizer", + "description": "Cut LLM API spend via model routing, prompt caching, prompt compression, and per-feature cost observability. Use when AI costs are too high, choosing between models, or launching an AI feature without cost architecture. NOT for RAG design or prompt quality (separate skills).", + "version": "2.9.0", + "author": { + "name": "Alireza Rezvani" + }, + "keywords": [ + "llm", + "cost-optimization", + "token-usage", + "model-routing", + "prompt-caching", + "observability" + ], + "category": "development" + }, + { + "name": "prompt-governance", + "source": "./engineering/prompt-governance", + "description": "Manage prompts in production at scale: prompt versioning, A/B testing, prompt registries, regression prevention, and eval pipelines for production AI features. NOT for writing individual prompts, RAG design, or cost reduction (separate skills).", + "version": "2.9.0", + "author": { + "name": "Alireza Rezvani" + }, + "keywords": [ + "prompts", + "versioning", + "ab-testing", + "registry", + "evals", + "regression", + "production-ai" + ], + "category": "development" + }, + { + "name": "business-investment-advisor", + "source": "./finance/business-investment-advisor", + "description": "Business investment analysis and capital allocation advisor. Evaluates equipment, real estate, new-business, hiring, and technology investments with ROI, IRR, NPV, payback period, build-vs-buy, lease-vs-buy, and vendor evaluation frameworks for allocating limited budget.", + "version": "2.9.0", + "author": { + "name": "Alireza Rezvani" + }, + "keywords": [ + "investment", + "capital-allocation", + "roi", + "irr", + "npv", + "build-vs-buy", + "finance" + ], + "category": "finance" + }, + { + "name": "video-content-strategist", + "source": "./marketing-skill/video-content-strategist", + "description": "Video content strategy: video scripts, YouTube channel optimization and SEO, short-form video pipelines (Reels, TikTok, Shorts), and repurposing long-form content into video. NOT for written blog content or caption-only social posts (separate skills).", + "version": "2.9.0", + "author": { + "name": "Alireza Rezvani" + }, + "keywords": [ + "video", + "youtube", + "short-form", + "scripts", + "content-strategy", + "tiktok", + "reels" + ], + "category": "marketing" + }, + { + "name": "compliance-team-eu-ai-act", + "source": "./ra-qm-team/compliance-team-eu-ai-act", + "description": "EU AI Act (Regulation (EU) 2024/1689) operational compliance specialist: AI system risk classifier (Articles 5/6/50 + Annex III), conformity assessment planner (Article 43 + Annex IV checklist), and obligation tracker (provider/deployer/importer/distributor + GPAI Articles 51-55). Article-level references and cross-framework mapping to ISO 42001, NIST AI RMF, GDPR. Stdlib-only.", + "version": "2.9.0", + "author": { + "name": "Alireza Rezvani" + }, + "keywords": [ + "eu-ai-act", + "compliance", + "risk-classification", + "conformity-assessment", + "gpai", + "ai-regulation" + ], + "category": "compliance" + }, + { + "name": "compliance-team-iso42001", + "source": "./ra-qm-team/compliance-team-iso42001", + "description": "ISO/IEC 42001:2023 AI Management System (AIMS) specialist: AIMS gap analyzer (Clauses 4-10 coverage + remediation priority), AI risk register builder (Annex A 38 controls per ISO 23894), and AIMS audit scheduler (Clause 9.2 cadence + auditor independence). Cross-framework mapping to EU AI Act, NIST AI RMF, ISO 23894. Stdlib-only.", + "version": "2.9.0", + "author": { + "name": "Alireza Rezvani" + }, + "keywords": [ + "iso-42001", + "aims", + "ai-governance", + "risk-register", + "internal-audit", + "compliance" + ], + "category": "compliance" + }, + { + "name": "collab-proof", + "source": "./engineering/collab-proof", + "description": "Assisted retrospective: after a session, calibrates what Claude contributed vs what the developer drove. LLM-assessed 4-frame analysis with explicit rubric, zero dependencies.", + "version": "1.0.0", + "author": { + "name": "dong7812", + "url": "https://github.com/dong7812" + }, + "keywords": [ + "ai-collaboration", + "session-retrospective", + "git-analysis", + "decision-logging", + "collab-proof" + ], + "category": "engineering" } ] } diff --git a/.codex/skills-index.json b/.codex/skills-index.json index 3f60fafd..8ce77a9e 100644 --- a/.codex/skills-index.json +++ b/.codex/skills-index.json @@ -3,13 +3,13 @@ "name": "claude-code-skills", "description": "Production-ready skill packages for AI agents - Marketing, Engineering, Product, C-Level, PM, and RA/QM", "repository": "https://github.com/alirezarezvani/claude-skills", - "total_skills": 346, + "total_skills": 344, "skills": [ { "name": "business-growth-skills", "source": "../../business-growth/skills/business-growth-skills", "category": "business-growth", - "description": "4 business growth agent skills and plugins for Claude Code, Codex, Gemini CLI, Cursor, OpenClaw. Customer success (health scoring, churn), sales engineer (RFP), revenue operations (pipeline, GTM), contract & proposal writer. Python tools (stdlib-only)." + "description": "Router/index for the 4 business & growth skills bundled in this plugin: customer-success-manager (health scoring, churn risk, expansion), sales-engineer (RFP analysis, competitive matrices, PoC planning), revenue-operations (pipeline, forecast accuracy, GTM efficiency), and contract-and-proposal-writer. Use when a growth/revenue request doesn't obviously match one skill and you need to pick the right one (e.g., 'which accounts are at risk', 'should we bid on this RFP')." }, { "name": "contract-and-proposal-writer", @@ -51,13 +51,13 @@ "name": "internal-comms", "source": "../../business-operations/skills/internal-comms", "category": "business-operations", - "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 benefit change, a leadership transition, a layoff, an acquisition close, or an internal product launch \u2014 and the audience is employees (not customers). Triggers on \"all-hands announcement\", \"town-hall script\", \"change comms\", \"internal newsletter\", \"rollout comms\", \"policy change announcement\", \"re-org announcement\", \"internal FAQ\", \"manager talking points\", \"Prosci ADKAR\", \"Kotter 8-step\", \"layoff comms\", \"RIF comms\", \"internal memo\". Pairs Prosci ADKAR (Awareness / Desire / Knowledge / Ability / Reinforcement) 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-tuned via --profile {tech-startup, scaleup, enterprise, public-company, non-profit}. Distinct from marketing-skill/* (external/customer-facing), c-level-advisor/internal-narrative (strategic framing, not tactical drafts), and c-level-advisor/change-management (executive change strategy, not the comms package itself)." + "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-tuned via --profile {tech-startup, scaleup, enterprise, public-company, non-profit}. Triggers on \"all-hands announcement\", \"change comms\", \"rollout comms\", \"re-org announcement\", \"manager talking points\", \"layoff comms\"." }, { "name": "knowledge-ops", "source": "../../business-operations/skills/knowledge-ops", "category": "business-operations", - "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, expense reimbursement, system-access provisioning, customer-escalation playbook) \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, ops onboarding doc generation, and runbook step verification (named owner, expected duration, observable success signal, rollback path, escalation contact). Pairs Kaoru Ishikawa's 5W2H method, Atul Gawande's *The Checklist Manifesto*, ISO 9001, ITIL v4 Service Operation, FDA 21 CFR Part 211, and Google SRE Workbook runbook discipline with deterministic stdlib-only Python tools that score completeness, detect anti-patterns, and emit prioritized cleanup lists. Distinct from `engineering/llm-wiki` (Karpathy-style personal PKM second brain), `engineering-team/runbook-generator` (system-ops production debugging runbook), `project-management/*` (Jira/Confluence delivery + ticket tracking), and sibling `business-operations/process-mapper` (BPMN process *design*, while knowledge-ops is process *documentation*)." + "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 Manifesto*, ISO 9001, ITIL v4, and Google SRE Workbook runbook discipline with deterministic stdlib-only Python tools that score completeness, detect anti-patterns, and emit prioritized cleanup lists (e.g., \"validate this runbook before it goes into rotation\", \"audit our Confluence wiki for stale and orphaned SOPs\")." }, { "name": "process-mapper", @@ -69,13 +69,13 @@ "name": "procurement-optimizer", "source": "../../business-operations/skills/procurement-optimizer", "category": "business-operations", - "description": "Use when running an annual SaaS audit, doing category-level spend review, or rationalizing the supplier base \u2014 when the user needs to do a spend audit, spend categorization (UNSPSC-aligned), purchasing-cycle analysis, or risk-balanced supplier consolidation. Triggers on \"spend audit\", \"SaaS audit\", \"spend categorization\", \"supplier rationalization\", \"supplier consolidation\", \"purchasing cycle\", \"procurement review\", \"category strategy\", \"duplicate SaaS\", \"renewal cluster\". Ships 3 stdlib-only Python tools (UNSPSC-aligned spend categorizer with Pareto breakdown and industry profiles, purchasing-cycle analyzer that surfaces bottleneck categories per Goldratt's Theory of Constraints, supplier-consolidation planner that refuses single-source recommendations for tier-1 categories without a documented break-glass plan), 3 reference docs each citing 7+ authoritative sources (A.T. Kearney / Hackett / Spend Matters / UNSPSC / Productiv / Vendr / Tropic / IACCM / ISM / BCG), and a 20-minute spend-intake template. Distinct from sibling vendor-management (performance scoring of vendors you keep paying), finance/financial-analysis (close + report, not category strategy), and c-level-advisor/general-counsel-advisor (contract law, not category rationalization)." + "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\", \"duplicate SaaS\", \"renewal cluster\"." }, { "name": "vendor-management", "source": "../../business-operations/skills/vendor-management", "category": "business-operations", - "description": "Use when reviewing, scoring, or auditing third-party SaaS / vendor relationships \u2014 running a vendor scorecard, tracking SLA compliance, classifying third-party risk, preparing a tier-1 vendor review, or auditing the SaaS portfolio. Triggers on \"vendor SLA\", \"vendor scorecard\", \"third-party risk\", \"TPRM\", \"vendor review\", \"SaaS audit\", \"supplier performance\", \"vendor health check\", \"renewal review\". Forks context so large vendor catalogs (50-500 line items) and SLA logs don't pollute the parent thread. Ships 3 stdlib-only Python tools (vendor scorer with industry tuning, SLA compliance tracker with credit-claim flags, vendor risk classifier across 4 risk vectors), 3 reference docs each citing 7+ authoritative sources (Gartner / Shared Assessments / NIST / ISO 27036 / breach post-mortems), and a 5-vendor catalog template. Distinct from c-level-advisor/general-counsel-advisor (contract law, not operational management), business-growth/contract-and-proposal-writer (outbound proposals, not inbound vendor scoring), and sibling procurement-optimizer (spend categorization, not vendor performance)." + "description": "Use when reviewing, scoring, or auditing third-party SaaS / vendor relationships \u2014 running a vendor scorecard with industry tuning, tracking SLA compliance with credit-claim flags, classifying third-party risk across 4 risk vectors, preparing a tier-1 vendor review, or auditing the SaaS portfolio. Forks context so large vendor catalogs (50-500 line items) and SLA logs don't pollute the parent thread. Triggers on \"vendor SLA\", \"vendor scorecard\", \"third-party risk\", \"TPRM\", \"vendor review\", \"supplier performance\", \"vendor health check\", \"renewal review\"." }, { "name": "agent-protocol", @@ -93,7 +93,7 @@ "name": "board-meeting", "source": "../../c-level-advisor/skills/board-meeting", "category": "c-level", - "description": "Multi-agent board meeting protocol for strategic decisions. Runs a structured 6-phase deliberation: context loading, independent C-suite contributions (isolated, no cross-pollination), critic analysis, synthesis, founder review, and decision extraction. Use when the user invokes /cs:board, calls a board meeting, or wants structured multi-perspective executive deliberation on a strategic question." + "description": "Multi-agent board meeting protocol for strategic decisions. Runs a structured 6-phase deliberation: context loading, independent C-suite contributions (isolated, no cross-pollination), critic analysis, synthesis, founder review, and decision extraction. Use when the user invokes /cs:boardroom, calls a board meeting, or wants structured multi-perspective executive deliberation on a strategic question." }, { "name": "board-prep", @@ -105,43 +105,43 @@ "name": "boardroom", "source": "../../c-level-advisor/c-level-agents/skills/boardroom", "category": "c-level", - "description": "/cs:boardroom \u2014 6-phase multi-role deliberation across the C-suite with Phase 2 isolation, critic pre-screen, and synthesis. Outputs a board memo." + "description": "/cs:boardroom \u2014 6-phase multi-role deliberation across the C-suite with Phase 2 isolation, critic pre-screen, and synthesis. Outputs a board memo. Use when a decision spans multiple executive domains \u2014 e.g. a pricing change touching finance, positioning, and product, or a raise-vs-cut runway call." }, { "name": "brief", "source": "../../c-level-advisor/c-level-agents/skills/brief", "category": "c-level", - "description": "/cs:brief \u2014 Generate a one-page strategy brief from an office-hours intake. First step in the strategic sprint pipeline." + "description": "/cs:brief \u2014 Generate a one-page strategy brief from an office-hours intake. First step in the strategic sprint pipeline. Use when a strategic question needs to be framed before boardroom deliberation \u2014 e.g. locking options, assumptions, and success criteria for a pricing change or a market-entry decision." }, { "name": "c-level-agents", "source": "../../c-level-advisor/c-level-agents/skills/c-level-agents", "category": "c-level", - "description": "Founder-mode executive team. 8 cs-* C-suite agents (CFO, CMO, CRO, CPO, COO, CHRO, CISO, Chief of Staff) and 17 /cs:* slash commands for forcing-question office hours, multi-role boardroom deliberation, strategic sprint pipeline, and meta routing. Use when the founder needs a virtual executive team, when invoking /cs:* commands, or when orchestrating multi-role decisions." + "description": "Founder-mode executive team. 13 cs-* C-suite agents (CFO, CMO, CRO, CPO, COO, CHRO, CISO, GC, CDO, CAIO, CCO, VPE, Chief of Staff) and 21 /cs:* slash commands for forcing-question office hours, multi-role boardroom deliberation, strategic sprint pipeline, and meta routing. Use when the founder needs a virtual executive team, when invoking /cs:* commands, or when orchestrating multi-role decisions." }, { "name": "c-level-skills", "source": "../../c-level-advisor/skills/c-level-skills", "category": "c-level", - "description": "10 C-level advisory agent skills and plugins for Claude Code, Codex, Gemini CLI, Cursor, OpenClaw. CEO, CTO, COO, CPO, CMO, CFO, CRO, CISO, CHRO, Executive Mentor. Multi-role board meetings, strategy routing, structured recommendations. For founders needing executive-level decision support." + "description": "Index and router for the C-level advisory bundle: 33 skills covering 14 C-suite roles, orchestration, cross-cutting capabilities, and culture. Use when exploring what the c-level-advisor bundle contains, deciding which advisor skill fits a question, or finding the entry points (cs-onboard interview, chief-of-staff routing, board-meeting protocol)." }, { "name": "caio-review", "source": "../../c-level-advisor/c-level-agents/skills/caio-review", "category": "c-level", - "description": "/cs:caio-review \u2014 Eval-demanding Chief AI Officer interrogation of any plan that involves AI: model selection, risk classification, cost economics, or AI hiring." + "description": "/cs:caio-review \u2014 Eval-demanding Chief AI Officer interrogation of any plan that involves AI: model selection, risk classification, cost economics, or AI hiring. Use when shipping an AI feature without an eval set, choosing between API, fine-tune, and self-hosted, or classifying a use case under the EU AI Act." }, { "name": "cco-review", "source": "../../c-level-advisor/c-level-agents/skills/cco-review", "category": "c-level", - "description": "/cs:cco-review \u2014 Retention-obsessed Chief Customer Officer interrogation of any plan that touches customer retention, segmentation, CS team sizing, or CS team hiring." + "description": "/cs:cco-review \u2014 Retention-obsessed Chief Customer Officer interrogation of any plan that touches customer retention, segmentation, CS team sizing, or CS team hiring. Use when gross retention is slipping, before approving CSM headcount, or when deciding which customer segments to keep or fire." }, { "name": "cdo-review", "source": "../../c-level-advisor/c-level-agents/skills/cdo-review", "category": "c-level", - "description": "/cs:cdo-review \u2014 Decision-driven Chief Data Officer interrogation of any plan that touches training data, data architecture, data productization, or data team hiring." + "description": "/cs:cdo-review \u2014 Decision-driven Chief Data Officer interrogation of any plan that touches training data, data architecture, data productization, or data team hiring. Use when validating training-data rights before model work, choosing warehouse vs lakehouse vs mesh, or valuing data assets for productization or M&A." }, { "name": "ceo-advisor", @@ -159,7 +159,7 @@ "name": "cfo-review", "source": "../../c-level-advisor/c-level-agents/skills/cfo-review", "category": "c-level", - "description": "/cs:cfo-review \u2014 Numerate-skeptic interrogation of any plan that touches money. Unit economics, runway, dilution, capital allocation." + "description": "/cs:cfo-review \u2014 Numerate-skeptic interrogation of any plan that touches money. Unit economics, runway, dilution, capital allocation. Use when a plan commits meaningful spend \u2014 e.g. a hiring wave, a fundraise decision, or a new channel budget." }, { "name": "challenge", @@ -213,7 +213,7 @@ "name": "chief-of-staff", "source": "../../c-level-advisor/skills/chief-of-staff", "category": "c-level", - "description": "C-suite orchestration layer. Routes founder questions to the right advisor role(s), triggers multi-role board meetings for complex decisions, synthesizes outputs, and tracks decisions. Every C-suite interaction starts here. Loads company context automatically." + "description": "C-suite orchestration layer. Routes founder questions to the right advisor role(s), triggers multi-role board meetings for complex decisions, synthesizes outputs, and tracks decisions. Every C-suite interaction starts here. Loads company context automatically. Use when a founder question needs routing to the right advisor \u2014 e.g. 'should we raise now or cut burn?' \u2014 or when a multi-domain decision needs a board meeting convened." }, { "name": "chro-advisor", @@ -231,7 +231,7 @@ "name": "ciso-review", "source": "../../c-level-advisor/c-level-agents/skills/ciso-review", "category": "c-level", - "description": "/cs:ciso-review \u2014 Risk-paranoid interrogation of any plan that touches data, compliance, or production access." + "description": "/cs:ciso-review \u2014 Risk-paranoid interrogation of any plan that touches data, compliance, or production access. Use when launching features that handle customer data, before a SOC 2 / ISO audit, or after any incident or near-miss." }, { "name": "cmo-advisor", @@ -243,7 +243,7 @@ "name": "cmo-review", "source": "../../c-level-advisor/c-level-agents/skills/cmo-review", "category": "c-level", - "description": "/cs:cmo-review \u2014 Narrative-first interrogation of positioning, ICP, message house, and channel mix." + "description": "/cs:cmo-review \u2014 Narrative-first interrogation of positioning, ICP, message house, and channel mix. Use when launching a campaign or repositioning, or when CAC is rising and the one-sentence positioning test fails." }, { "name": "company-os", @@ -261,7 +261,7 @@ "name": "context-engine", "source": "../../c-level-advisor/skills/context-engine", "category": "c-level", - "description": "Loads and manages company context for all C-suite advisor skills. Reads ~/.claude/company-context.md, detects stale context (>90 days), enriches context during conversations, and enforces privacy/anonymization rules before external API calls." + "description": "Loads and manages company context for all C-suite advisor skills. Reads ~/.claude/company-context.md, detects stale context (>90 days), enriches context during conversations, and enforces privacy/anonymization rules before external API calls. Use when starting any C-suite advisor session, when context looks stale or missing, or before sending company data to an external service." }, { "name": "coo-advisor", @@ -279,7 +279,7 @@ "name": "cpo-review", "source": "../../c-level-advisor/c-level-agents/skills/cpo-review", "category": "c-level", - "description": "/cs:cpo-review \u2014 JTBD-driven interrogation of product roadmap, PMF signal, and portfolio focus." + "description": "/cs:cpo-review \u2014 JTBD-driven interrogation of product roadmap, PMF signal, and portfolio focus. Use when committing a quarter's roadmap, deciding whether to kill a feature, or claiming PMF without a retention curve." }, { "name": "cro-advisor", @@ -291,19 +291,19 @@ "name": "cro-review", "source": "../../c-level-advisor/c-level-agents/skills/cro-review", "category": "c-level", - "description": "/cs:cro-review \u2014 Pipeline-paranoid interrogation of revenue, win rate, NRR, and ramp time." + "description": "/cs:cro-review \u2014 Pipeline-paranoid interrogation of revenue, win rate, NRR, and ramp time. Use when the forecast misses pipeline coverage, win rates drop, or before scaling the sales team." }, { "name": "cross-eval", "source": "../../c-level-advisor/c-level-agents/skills/cross-eval", "category": "c-level", - "description": "/cs:cross-eval \u2014 Multi-model consensus on a board memo or strategy brief. Claude + Codex + Gemini cross-review with graceful degradation." + "description": "/cs:cross-eval \u2014 Multi-model consensus on a board memo or strategy brief. Claude + Codex + Gemini cross-review with graceful degradation. Use when a high-stakes memo needs an independent sanity check before the boardroom \u2014 e.g. a bet-the-company pivot or fundraise terms." }, { "name": "cs-onboard", "source": "../../c-level-advisor/skills/cs-onboard", "category": "c-level", - "description": "Founder onboarding interview that captures company context across 7 dimensions. Invoke with /cs:setup for initial interview or /cs:update for quarterly refresh. Generates ~/.claude/company-context.md used by all C-suite advisor skills." + "description": "Founder onboarding interview that captures company context across 7 dimensions. Invoke with /cs:setup for initial interview or /cs:update for quarterly refresh. Generates ~/.claude/company-context.md used by all C-suite advisor skills. Use when setting up the C-suite advisors for the first time, or when company context is missing or more than 90 days old \u2014 e.g. after a fundraise or pivot." }, { "name": "cto-advisor", @@ -315,7 +315,7 @@ "name": "cto-review", "source": "../../c-level-advisor/c-level-agents/skills/cto-review", "category": "c-level", - "description": "/cs:cto-review \u2014 Architecture and scaling interrogation. Tech debt, scaling cliffs, team scaling, build-vs-buy." + "description": "/cs:cto-review \u2014 Architecture and scaling interrogation. Tech debt, scaling cliffs, team scaling, build-vs-buy. Use when committing to an architecture, planning for 10x load, or weighing a rebuild against a vendor." }, { "name": "culture-architect", @@ -327,7 +327,7 @@ "name": "decide", "source": "../../c-level-advisor/c-level-agents/skills/decide", "category": "c-level", - "description": "/cs:decide \u2014 Log a decision to two-layer memory via decision-logger. Approved memo becomes durable; raw transcripts kept for reference." + "description": "/cs:decide \u2014 Log a decision to two-layer memory via decision-logger. Approved memo becomes durable; raw transcripts kept for reference. Use when the founder has approved a boardroom memo and the decision must become durable company memory \u2014 e.g. right after /cs:boardroom concludes." }, { "name": "decision-logger", @@ -339,7 +339,7 @@ "name": "execute", "source": "../../c-level-advisor/c-level-agents/skills/execute", "category": "c-level", - "description": "/cs:execute \u2014 Generate a 90-day execution plan with weekly milestones, DRIs, and check-in cadence from an approved decision." + "description": "/cs:execute \u2014 Generate a 90-day execution plan with weekly milestones, DRIs, and check-in cadence from an approved decision. Use when a logged decision needs to become an operating plan \u2014 e.g. turning an approved market-entry call into weekly milestones with DRIs." }, { "name": "executive-mentor", @@ -357,19 +357,19 @@ "name": "founder-mode", "source": "../../c-level-advisor/c-level-agents/skills/founder-mode", "category": "c-level", - "description": "/cs:founder-mode \u2014 Auto-routes any founder question to the right C-role advisor or to /cs:boardroom for multi-role topics. The single-command entry point." + "description": "/cs:founder-mode \u2014 Auto-routes any founder question to the right C-role advisor or to /cs:boardroom for multi-role topics. The single-command entry point. Use when a founder asks any strategic question without knowing which advisor or command fits \u2014 e.g. 'runway pressure' routes to the CFO, 'gross retention dropped' routes to the CCO." }, { "name": "freeze", "source": "../../c-level-advisor/c-level-agents/skills/freeze", "category": "c-level", - "description": "/cs:freeze \u2014 Lock a strategic decision for a cooldown period to prevent impulse reversal. Mirrors gstack's safety primitives for the business layer." + "description": "/cs:freeze \u2014 Lock a strategic decision for a cooldown period to prevent impulse reversal. Mirrors gstack's safety primitives for the business layer. Use when an irreversible decision was made under pressure \u2014 e.g. a layoff plan or multi-year contract \u2014 and deserves a cooling-off lock before execution." }, { "name": "gc-review", "source": "../../c-level-advisor/c-level-agents/skills/gc-review", "category": "c-level", - "description": "/cs:gc-review \u2014 General Counsel interrogation of contracts, IP, regulatory, term sheets, and employment-law surface." + "description": "/cs:gc-review \u2014 General Counsel interrogation of contracts, IP, regulatory, term sheets, and employment-law surface. Use when reviewing a term sheet before signing, redlining a customer MSA, or checking IP assignment and regulatory exposure on a new product." }, { "name": "general-counsel-advisor", @@ -387,7 +387,7 @@ "name": "hard-call", "source": "../../c-level-advisor/executive-mentor/skills/hard-call", "category": "c-level", - "description": "/em -hard-call \u2014 Framework for Decisions With No Good Options" + "description": "/em:hard-call \u2014 Framework for decisions with no good options. Use when every option is painful and a structured 10/10/10 + regret-minimization pass is needed \u2014 e.g. choosing between a layoff and a down round, or killing a beloved product line." }, { "name": "internal-narrative", @@ -411,13 +411,13 @@ "name": "office-hours", "source": "../../c-level-advisor/c-level-agents/skills/office-hours", "category": "c-level", - "description": "/cs:office-hours \u2014 YC-style 6-question founder interrogation before any advice. Forces clarity on problem, customer, distribution, defensibility, capital, and founder fit." + "description": "/cs:office-hours \u2014 YC-style 6-question founder interrogation before any advice. Forces clarity on problem, customer, distribution, defensibility, capital, and founder fit. Use when a founder question is too vague to route \u2014 e.g. 'should we grow faster?' \u2014 or before drafting a strategy brief." }, { "name": "onboard", "source": "../../c-level-advisor/c-level-agents/skills/onboard", "category": "c-level", - "description": "/cs:onboard \u2014 Founder interview that populates ~/.claude/company-context.md. The first command to run when starting with c-level-agents." + "description": "/cs:onboard \u2014 Founder interview that populates ~/.claude/company-context.md using the canonical 7-dimension cs-onboard schema. The first command to run when starting with c-level-agents. Use when setting up the virtual C-suite for a new company, or when advisors lack company context \u2014 e.g. before a first /cs:boardroom or after a fundraise changes the numbers." }, { "name": "org-health-diagnostic", @@ -429,13 +429,13 @@ "name": "post-mortem", "source": "../../c-level-advisor/c-level-agents/skills/post-mortem", "category": "c-level", - "description": "/cs:post-mortem \u2014 Honest retrospective on an executed decision, scored against original assumptions and dissent. Closes the strategic sprint loop." + "description": "/cs:post-mortem \u2014 Honest retrospective on an executed decision, scored against original assumptions and dissent. Closes the strategic sprint loop. Use when a decision hits its 90-day review checkpoint or its kill criteria trigger \u2014 e.g. scoring last quarter's pricing change against its pre-committed success metrics." }, { "name": "postmortem", "source": "../../c-level-advisor/executive-mentor/skills/postmortem", "category": "c-level", - "description": "/em -postmortem \u2014 Honest Analysis of What Went Wrong" + "description": "/em:postmortem \u2014 Honest analysis of what went wrong. Use after a failed launch, missed quarter, or bad hire to run a blameless 5-Whys retrospective with a change register \u2014 e.g. dissecting why the Q3 release slipped six weeks." }, { "name": "scenario-war-room", @@ -453,7 +453,7 @@ "name": "stress-test", "source": "../../c-level-advisor/executive-mentor/skills/stress-test", "category": "c-level", - "description": "/em -stress-test \u2014 Business Assumption Stress Testing" + "description": "/em:stress-test \u2014 Business assumption stress testing. Use before betting on a plan whose core assumptions are unvalidated \u2014 e.g. stress-testing 'enterprise buyers will tolerate a 6-month pilot' or a hockey-stick revenue model." }, { "name": "vpe-advisor", @@ -471,13 +471,13 @@ "name": "vpe-review", "source": "../../c-level-advisor/c-level-agents/skills/vpe-review", "category": "c-level", - "description": "/cs:vpe-review \u2014 Throughput-first VP of Engineering interrogation of any plan that touches delivery, eng hiring, team structure, or production discipline." + "description": "/cs:vpe-review \u2014 Throughput-first VP of Engineering interrogation of any plan that touches delivery, eng hiring, team structure, or production discipline. Use when cycle time balloons, DORA metrics slide, or before committing to an eng hiring wave or a reorg." }, { "name": "channel-economics", "source": "../../commercial/skills/channel-economics", "category": "commercial", - "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-DOWN / MAINTAIN / DEFUND / EXIT), a sensitivity-tested channel-mix recommendation, and the diminishing-returns inflection. Not channel structure (that's partnerships-architect \u2014 tiers, joint GTM, revshare). Not RevOps process (that's business-growth/revenue-operations \u2014 lead routing, SDR motion). Not strategic CRO judgment (that's c-level-advisor/cro-advisor \u2014 comp plans, when-to-hire-a-VP-Sales). Not historical close-and-report (that's finance/financial-analysis). This skill answers: direct vs partner profitability, channel profitability, channel mix, 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-DOWN / MAINTAIN / DEFUND / EXIT), a sensitivity-tested channel-mix recommendation, and the diminishing-returns inflection (e.g., 'which channel actually makes money \u2014 direct or partner?')." }, { "name": "commercial-forecaster", @@ -669,7 +669,7 @@ "name": "engineering-skills", "source": "../../engineering-team/skills/engineering-skills", "category": "engineering", - "description": "23 engineering agent skills and plugins for Claude Code, Codex, Gemini CLI, Cursor, OpenClaw, and 6 more tools. Architecture, frontend, backend, QA, DevOps, security, AI/ML, data engineering, Playwright, Stripe, AWS, MS365. 30+ Python tools (stdlib-only)." + "description": "Index of the engineering-team skills bundle for Claude Code, Codex, Gemini CLI, Cursor, OpenClaw, and 6 more tools. Architecture, frontend, backend, QA, DevOps, security, AI/ML, data engineering, Playwright, Stripe, AWS, MS365 (stdlib-only Python tools). Use when browsing or choosing among engineering-team role skills \u2014 load only the one specialist SKILL.md you need, never bulk-load the bundle." }, { "name": "epic-design", @@ -681,7 +681,7 @@ "name": "extract", "source": "../../engineering-team/self-improving-agent/skills/extract", "category": "engineering", - "description": "Turn a proven pattern or debugging solution into a standalone reusable skill with SKILL.md, reference docs, and examples." + "description": "Turn a proven pattern or debugging solution into a standalone reusable skill with SKILL.md, reference docs, and examples. Use when the user runs /si:extract or asks to package a recurring solution from memory into a skill." }, { "name": "fix", @@ -705,7 +705,7 @@ "name": "google-workspace-cli", "source": "../../engineering-team/google-workspace-cli/skills/google-workspace-cli", "category": "engineering", - "description": "Google Workspace administration via the gws CLI. Install, authenticate, and automate Gmail, Drive, Sheets, Calendar, Docs, Chat, and Tasks. Run security audits, execute 43 built-in recipes, and use 10 persona bundles. Use for Google Workspace admin, gws CLI setup, Gmail automation, Drive management, or Calendar scheduling." + "description": "Google Workspace administration via the gws CLI (github.com/googleworkspace/cli). Install, authenticate, and automate Gmail, Drive, Sheets, Calendar, Docs, Chat, and Tasks. Run security audits and use local recipe templates and persona bundles. Use for Google Workspace admin, gws CLI setup, Gmail automation, Drive management, or Calendar scheduling." }, { "name": "incident-commander", @@ -741,7 +741,7 @@ "name": "promote", "source": "../../engineering-team/self-improving-agent/skills/promote", "category": "engineering", - "description": "Graduate a proven pattern from auto-memory (MEMORY.md) to CLAUDE.md or .claude/rules/ for permanent enforcement." + "description": "Graduate a proven pattern from auto-memory (MEMORY.md) to CLAUDE.md or .claude/rules/ for permanent enforcement. Use when the user runs /si:promote or asks to make a learned behavior permanent." }, { "name": "pw", @@ -767,18 +767,18 @@ "category": "engineering", "description": ">-" }, - { - "name": "review", - "source": "../../engineering-team/self-improving-agent/skills/review", - "category": "engineering", - "description": "Analyze auto-memory for promotion candidates, stale entries, consolidation opportunities, and health metrics." - }, { "name": "review", "source": "../../engineering-team/playwright-pro/skills/review", "category": "engineering", "description": ">-" }, + { + "name": "review", + "source": "../../engineering-team/self-improving-agent/skills/review", + "category": "engineering", + "description": "Analyze auto-memory for promotion candidates, stale entries, consolidation opportunities, and health metrics. Use when the user runs /si:review or asks what has been learned and what should be promoted or pruned." + }, { "name": "security-pen-testing", "source": "../../engineering-team/skills/security-pen-testing", @@ -849,7 +849,7 @@ "name": "senior-prompt-engineer", "source": "../../engineering-team/skills/senior-prompt-engineer", "category": "engineering", - "description": "This skill should be used when the user asks to \"optimize prompts\", \"design prompt templates\", \"evaluate LLM outputs\", \"build agentic systems\", \"implement RAG\", \"create few-shot examples\", \"analyze token usage\", or \"design AI workflows\". Use for prompt engineering patterns, LLM evaluation frameworks, agent architectures, and structured output design." + "description": "Use when the user asks to optimize prompts, design prompt templates, evaluate LLM outputs with an eval set, measure RAG retrieval quality, validate agent/tool configurations, analyze token usage, or design structured-output contracts. Covers eval-driven prompt iteration, RAG metrics (relevance, faithfulness, coverage), agent workflow validation, and token/cost budgeting \u2014 all model-agnostic, with three stdlib Python tools." }, { "name": "senior-qa", @@ -867,7 +867,7 @@ "name": "senior-security", "source": "../../engineering-team/skills/senior-security", "category": "engineering", - "description": "Security engineering toolkit for threat modeling, vulnerability analysis, secure architecture, and penetration testing. Includes STRIDE analysis, OWASP guidance, cryptography patterns, and security scanning tools. Use when the user asks about security reviews, threat analysis, vulnerability assessments, secure coding practices, security audits, attack surface analysis, CVE remediation, or security best practices." + "description": "Use when the user asks for STRIDE threat modeling, DREAD risk scoring, data-flow-diagram threat analysis, or a quick secret scan \u2014 or when a security request needs routing to the right specialist skill (pen-testing, incident response, cloud posture, red team, AI security, threat hunting, secure code review). This skill owns threat modeling; everything else routes to a sibling." }, { "name": "snowflake-development", @@ -879,7 +879,7 @@ "name": "status", "source": "../../engineering-team/self-improving-agent/skills/status", "category": "engineering", - "description": "Memory health dashboard showing line counts, topic files, capacity, stale entries, and recommendations." + "description": "Memory health dashboard showing line counts, topic files, capacity, stale entries, and recommendations. Use when the user runs /si:status or asks how full or healthy the agent memory is." }, { "name": "stripe-integration-expert", @@ -915,7 +915,7 @@ "name": "agent-designer", "source": "../../engineering/skills/agent-designer", "category": "engineering-advanced", - "description": "Use when the user asks to design multi-agent systems, create agent architectures, define agent communication patterns, or build autonomous agent workflows." + "description": "Use when the user asks to design a multi-agent system, pick an orchestration pattern (supervisor/swarm/pipeline), generate tool schemas for agents, or evaluate agent execution logs for cost, latency, and failure bottlenecks. Examples: 'design an agent architecture for research automation', 'generate Anthropic tool schemas from these tool descriptions', 'analyze these agent run logs for bottlenecks'. NOT for Claude Code workflow files (use workflow-builder) or single-agent prompt design (use agent-workflow-designer)." }, { "name": "agent-workflow-designer", @@ -957,7 +957,7 @@ "name": "board", "source": "../../engineering/agenthub/skills/board", "category": "engineering-advanced", - "description": "Read, write, and browse the AgentHub message board for agent coordination." + "description": "Read, write, and browse the AgentHub message board for agent coordination. Use when the user runs /hub:board or asks to post, read, or inspect coordination messages between competing AgentHub agents." }, { "name": "browser-automation", @@ -975,7 +975,7 @@ "name": "changelog-generator", "source": "../../engineering/skills/changelog-generator", "category": "engineering-advanced", - "description": "Produce consistent, auditable release notes from Conventional Commits. Separates commit parsing, semantic-bump logic, and changelog rendering for automated releases with editorial control. Use when cutting a release, generating CHANGELOG.md from git history, or automating release notes in CI." + "description": "Produce consistent, auditable release notes from Conventional Commits. Separates commit parsing, semantic-bump logic, and changelog rendering for automated releases with editorial control. Use when cutting a release, generating CHANGELOG.md from git history, computing the next semantic version from commits, automating release notes in CI, or planning a hotfix/rollback. Examples: 'generate the changelog for v1.4.0', 'what version bump do these commits require', 'we need an emergency hotfix process'." }, { "name": "chaos-engineering", @@ -1014,16 +1014,16 @@ "description": "Analyze a codebase and generate onboarding documentation for engineers, tech leads, and contractors. Fast fact-gathering and repeatable onboarding outputs. Use when onboarding a new engineer, writing architecture-overview docs for a new project, or producing tech-lead briefings for unfamiliar repos." }, { - "name": "command-guide", - "source": "../../engineering/skills/command-guide", + "name": "collab-proof", + "source": "../../engineering/collab-proof/skills/collab-proof", "category": "engineering-advanced", - "description": ">" + "description": "Use when you want to understand what Claude contributed vs what you drove in a session. Triggers on: /collab-proof, session retrospective, ai contribution analysis, collaboration evidence, what did claude do." }, { "name": "data-quality-auditor", "source": "../../engineering/data-quality-auditor/skills/data-quality-auditor", "category": "engineering-advanced", - "description": "Audit datasets for completeness, consistency, accuracy, and validity. Profile data distributions, detect anomalies and outliers, surface structural issues, and produce an actionable remediation plan." + "description": "Audit datasets for completeness, consistency, accuracy, and validity. Profile data distributions, detect anomalies and outliers, surface structural issues, and produce an actionable remediation plan. Use when the user asks to check data quality, profile a dataset, hunt outliers or missing values, or validate data before analysis or model training." }, { "name": "database-designer", @@ -1047,7 +1047,7 @@ "name": "dependency-auditor", "source": "../../engineering/skills/dependency-auditor", "category": "engineering-advanced", - "description": "Audit and manage dependencies across multi-language projects. Identifies vulnerabilities, license conflicts, transitive dependency risks, and safe-upgrade paths. Use when auditing third-party packages before release, investigating a CVE, planning a major version bump, or running a license-compliance review." + "description": "Audit and manage dependencies across multi-language projects. Identifies vulnerabilities, license conflicts, transitive dependency risks, and safe-upgrade paths. Use when auditing third-party packages before release, investigating a CVE, planning a major version bump, or running a license-compliance review. Examples: 'audit our npm dependencies', 'do we have GPL contamination', 'plan the upgrade to React 19'." }, { "name": "docker-development", @@ -1059,7 +1059,7 @@ "name": "engineering-advanced-skills", "source": "../../engineering/skills/engineering-advanced-skills", "category": "engineering-advanced", - "description": "25 advanced engineering agent skills and plugins for Claude Code, Codex, Gemini CLI, Cursor, OpenClaw. Agent design, RAG, MCP servers, CI/CD, database design, observability, security auditing, release management, platform ops." + "description": "Index of 37 advanced engineering agent skills for Claude Code, Codex, Gemini CLI, Cursor, OpenClaw. Use when browsing or choosing among the POWERFUL-tier engineering skills: agent design, RAG, MCP servers, CI/CD, database design, observability, security auditing, changelog/release automation, reliability (SLO/chaos/flags/operators), platform ops." }, { "name": "env-secrets-manager", @@ -1071,7 +1071,7 @@ "name": "eval", "source": "../../engineering/agenthub/skills/eval", "category": "engineering-advanced", - "description": "Evaluate and rank agent results by metric or LLM judge for an AgentHub session." + "description": "Evaluate and rank agent results by metric or LLM judge for an AgentHub session. Use when the user runs /hub:eval or asks to score, compare, or pick a winner among completed AgentHub agents." }, { "name": "feature-flags-architect", @@ -1131,7 +1131,7 @@ "name": "init", "source": "../../engineering/agenthub/skills/init", "category": "engineering-advanced", - "description": "Create a new AgentHub collaboration session with task, agent count, and evaluation criteria." + "description": "Create a new AgentHub collaboration session with task, agent count, and evaluation criteria. Use when the user runs /hub:init or asks to start a multi-agent competition on a task." }, { "name": "interview-system-designer", @@ -1173,7 +1173,7 @@ "name": "loop", "source": "../../engineering/autoresearch-agent/skills/loop", "category": "engineering-advanced", - "description": "Start an autonomous experiment loop with user-selected interval (10min, 1h, daily, weekly, monthly). Uses CronCreate for scheduling." + "description": "Start an autonomous experiment loop with user-selected interval (10min, 1h, daily, weekly, monthly). Uses CronCreate for scheduling. Use when the user runs /ar:loop or asks to run an autoresearch experiment continuously on a schedule." }, { "name": "mcp-server-builder", @@ -1185,7 +1185,7 @@ "name": "merge", "source": "../../engineering/agenthub/skills/merge", "category": "engineering-advanced", - "description": "Merge the winning agent's branch into base, archive losers, and clean up worktrees." + "description": "Merge the winning agent's branch into base, archive losers, and clean up worktrees. Use when the user runs /hub:merge or asks to land the winning AgentHub result and tidy the session." }, { "name": "migration-architect", @@ -1227,31 +1227,25 @@ "name": "rag-architect", "source": "../../engineering/skills/rag-architect", "category": "engineering-advanced", - "description": "Use when the user asks to design RAG pipelines, optimize retrieval strategies, choose embedding models, implement vector search, or build knowledge retrieval systems." - }, - { - "name": "release-manager", - "source": "../../engineering/skills/release-manager", - "category": "engineering-advanced", - "description": "Use when the user asks to plan releases, manage changelogs, coordinate deployments, create release branches, or automate versioning." + "description": "Use when the user asks to design a RAG pipeline, choose a chunking strategy or embedding model, pick a vector database, or evaluate retrieval quality (precision@k, recall@k, NDCG). Examples: 'design a RAG system for our docs', 'what chunk size should I use for this corpus', 'evaluate my retriever against ground truth'. NOT for general LLM cost tuning (use llm-cost-optimizer) or agent loops over retrieval (use agenthub)." }, { "name": "resume", "source": "../../engineering/autoresearch-agent/skills/resume", "category": "engineering-advanced", - "description": "Resume a paused experiment. Checkout the experiment branch, read results history, continue iterating." + "description": "Resume a paused experiment. Checkout the experiment branch, read results history, continue iterating. Use when the user runs /ar:resume or asks to pick up a previously started autoresearch experiment." }, { "name": "run", "source": "../../engineering/agenthub/skills/run", "category": "engineering-advanced", - "description": "One-shot lifecycle command that chains init \u2192 baseline \u2192 spawn \u2192 eval \u2192 merge in a single invocation." + "description": "One-shot lifecycle command that chains init \u2192 baseline \u2192 spawn \u2192 eval \u2192 merge in a single invocation. Use when the user runs /hub:run or asks to execute a full AgentHub competition end-to-end." }, { "name": "run", "source": "../../engineering/autoresearch-agent/skills/run", "category": "engineering-advanced", - "description": "Run a single experiment iteration. Edit the target file, evaluate, keep or discard." + "description": "Run a single experiment iteration. Edit the target file, evaluate, keep or discard. Use when the user runs /ar:run or asks for one manual autoresearch iteration." }, { "name": "runbook-generator", @@ -1281,7 +1275,7 @@ "name": "setup", "source": "../../engineering/autoresearch-agent/skills/setup", "category": "engineering-advanced", - "description": "Set up a new autoresearch experiment interactively. Collects domain, target file, eval command, metric, direction, and evaluator." + "description": "Set up a new autoresearch experiment interactively. Collects domain, target file, eval command, metric, direction, and evaluator. Use when the user runs /ar:setup or asks to start optimizing a file with the autoresearch loop." }, { "name": "ship-gate", @@ -1317,7 +1311,7 @@ "name": "spawn", "source": "../../engineering/agenthub/skills/spawn", "category": "engineering-advanced", - "description": "Launch N parallel subagents in isolated git worktrees to compete on the session task." + "description": "Launch N parallel subagents in isolated git worktrees to compete on the session task. Use when the user runs /hub:spawn or asks to start the competing agents for an initialized AgentHub session." }, { "name": "spec-driven-workflow", @@ -1341,13 +1335,13 @@ "name": "status", "source": "../../engineering/agenthub/skills/status", "category": "engineering-advanced", - "description": "Show DAG state, agent progress, and branch status for an AgentHub session." + "description": "Show DAG state, agent progress, and branch status for an AgentHub session. Use when the user runs /hub:status or asks how the AgentHub agents are doing." }, { "name": "status", "source": "../../engineering/autoresearch-agent/skills/status", "category": "engineering-advanced", - "description": "Show experiment dashboard with results, active loops, and progress." + "description": "Show experiment dashboard with results, active loops, and progress. Use when the user runs /ar:status or asks how an autoresearch experiment is going." }, { "name": "tc-tracker", @@ -1369,7 +1363,7 @@ }, { "name": "universal-scraping-architect", - "source": "../../engineering/universal-scraping-architect", + "source": "../../engineering/universal-scraping-architect/skills/universal-scraping-architect", "category": "engineering-advanced", "description": "Use for web scraping, crawling, document extraction, API parsing, or building validation-heavy data pipelines using Firecrawl or local Python scripts." }, @@ -1395,7 +1389,7 @@ "name": "finance-skills", "source": "../../finance/skills/finance-skills", "category": "finance", - "description": "Financial analyst agent skill and plugin for Claude Code, Codex, Gemini CLI, Cursor, OpenClaw. Ratio analysis, DCF valuation, budget variance, rolling forecasts. 4 Python tools (stdlib-only)." + "description": "Router/index for the 2 finance skills bundled in this plugin: financial-analyst (ratio analysis, DCF valuation, budget variance, rolling forecasts) and saas-metrics-coach (ARR/MRR, churn, CAC/LTV, NRR, quick ratio). Use when a finance request doesn't obviously match one skill and you need to pick the right one (e.g., 'analyze these financials', 'how healthy are my SaaS metrics')." }, { "name": "financial-analyst", @@ -1427,12 +1421,6 @@ "category": "marketing", "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 for AI search', 'E-E-A-T audit'. Output is a markdown audit report (default) or JSON for pipeline integration. Stdlib-only Python tools." }, - { - "name": "ai-seo", - "source": "../../marketing-skill/skills/ai-seo", - "category": "marketing", - "description": "Optimize content to get cited by AI search engines \u2014 ChatGPT, Perplexity, Google AI Overviews, Claude, Gemini, Copilot. Use when you want your content to appear in AI-generated answers, not just ranked in blue links. Triggers: 'optimize for AI search', 'get cited by ChatGPT', 'AI Overviews', 'Perplexity citations', 'AI SEO', 'generative search', 'LLM visibility', 'GEO' (generative engine optimization). NOT for traditional SEO ranking (use seo-audit). NOT for content creation (use content-production)." - }, { "name": "analytics-tracking", "source": "../../marketing-skill/skills/analytics-tracking", @@ -1551,7 +1539,7 @@ "name": "marketing-demand-acquisition", "source": "../../marketing-skill/skills/marketing-demand-acquisition", "category": "marketing", - "description": "Creates demand generation campaigns, optimizes paid ad spend across LinkedIn, Google, and Meta, develops SEO strategies, and structures partnership programs for Series A+ startups scaling internationally. Use when planning marketing strategy, growth marketing, advertising campaigns, PPC optimization, lead generation, pipeline generation, or startup 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 for hybrid PLG/Sales-Led motions in EU/US/Canada markets." + "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) \u2014 adapt benchmarks for other stages and motions rather than skipping the skill." }, { "name": "marketing-ideas", @@ -1575,7 +1563,7 @@ "name": "marketing-skills", "source": "../../marketing-skill/skills/marketing-skills", "category": "marketing", - "description": "42 marketing agent skills and plugins for Claude Code, Codex, Gemini CLI, Cursor, OpenClaw, and 6 more coding agents. 7 pods: content, SEO, CRO, channels, growth, intelligence, sales. Foundation context + orchestration router. 27 Python tools (stdlib-only)." + "description": "Directory and router for the marketing skills library. Use when you need to find the right marketing skill for a task, see what marketing capabilities exist, or get oriented in this plugin. 44 specialist skills across 8 pods (content, SEO + AEO, CRO, channels, growth, intelligence, sales enablement, ops), 59 stdlib Python tools. Routes to one skill \u2014 it does not execute marketing work itself." }, { "name": "marketing-strategy-pmm", @@ -1629,7 +1617,7 @@ "name": "prompt-engineer-toolkit", "source": "../../marketing-skill/skills/prompt-engineer-toolkit", "category": "marketing", - "description": "Analyzes and rewrites prompts for better AI output, creates reusable prompt templates for marketing use cases (ad copy, email campaigns, social media), and structures end-to-end AI content workflows. Use when the user wants to improve prompts for AI-assisted marketing, build prompt templates, or optimize AI content workflows. Also use when the user mentions 'prompt engineering,' 'improve my prompts,' 'AI writing quality,' 'prompt templates,' or 'AI content workflow.'" + "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,' 'AI content workflow,' or 'AI governance for marketing.'" }, { "name": "referral-program", @@ -1671,7 +1659,7 @@ "name": "social-media-analyzer", "source": "../../marketing-skill/skills/social-media-analyzer", "category": "marketing", - "description": "Social media campaign analysis and performance tracking. Calculates engagement rates, ROI, and benchmarks across platforms. Use for analyzing social media performance, calculating engagement rate, measuring campaign ROI, comparing platform metrics, or benchmarking against industry standards." + "description": "Social media campaign analysis and performance tracking. Calculates engagement rates, ROI, and benchmarks across platforms. Use when analyzing social media performance, calculating engagement rate, measuring campaign ROI, comparing platform metrics, or benchmarking against industry standards. Also use when the user mentions \"social media audit,\" \"engagement rate,\" or \"which platform performs best.\"" }, { "name": "social-media-manager", @@ -1707,19 +1695,19 @@ "name": "agile-product-owner", "source": "../../product-team/agile-product-owner/skills/agile-product-owner", "category": "product", - "description": "Agile product ownership for backlog management and sprint execution. Covers user story writing, acceptance criteria, sprint planning, and velocity tracking. Use for writing user stories, creating acceptance criteria, planning sprints, estimating story points, breaking down epics, or prioritizing backlog." + "description": "Agile product ownership for backlog management and sprint execution. Covers user story writing, acceptance criteria, sprint planning, and velocity tracking. Use when writing user stories, creating acceptance criteria, planning sprints, estimating story points, breaking down epics, or prioritizing the backlog." }, { "name": "apple-hig-expert", "source": "../../product-team/apple-hig-expert/skills/apple-hig-expert", "category": "product", - "description": "Expert guidance on Apple Human Interface Guidelines (HIG). Covers iOS, macOS, and visionOS with 2026 Liquid Glass aesthetics and accessibility-first design." + "description": "Audits and designs iOS/macOS/watchOS/visionOS interfaces against the Apple Human Interface Guidelines, including the Liquid Glass design language (announced WWDC25, shipped with iOS 26/macOS Tahoe, Sept 2025). Use when reviewing an Apple-platform mockup or app for HIG compliance, checking contrast or tap-target sizes, or designing native-feeling Apple UI (e.g., 'audit my iOS app against the HIG', 'is this text readable on Liquid Glass?')." }, { "name": "code-to-prd", "source": "../../product-team/code-to-prd/skills/code-to-prd", "category": "product", - "description": "|" + "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 logic, analyze page fields and interactions, create a functional inventory, write requirements from an existing codebase, document API endpoints, or analyze backend routes." }, { "name": "competitive-teardown", @@ -1755,13 +1743,13 @@ "name": "product-manager-toolkit", "source": "../../product-team/skills/product-manager-toolkit", "category": "product", - "description": "Comprehensive toolkit for product managers including RICE prioritization, customer interview analysis, PRD templates, discovery frameworks, and go-to-market strategies. Use for feature prioritization, user research synthesis, requirement documentation, and product strategy development." + "description": "Comprehensive toolkit for product managers including RICE prioritization, customer interview analysis, PRD templates, discovery frameworks, and go-to-market strategies. Use when prioritizing features, synthesizing user research, writing requirement documentation, or developing product strategy." }, { "name": "product-skills", "source": "../../product-team/skills/product-skills", "category": "product", - "description": "10 product agent skills and plugins for Claude Code, Codex, Gemini CLI, Cursor, OpenClaw. PM toolkit (RICE), agile PO, product strategist (OKR), UX researcher, UI design system, competitive teardown, landing page generator, SaaS scaffolder, research summarizer. Python tools (stdlib-only)." + "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')." }, { "name": "product-strategist", @@ -1797,13 +1785,13 @@ "name": "ui-design-system", "source": "../../product-team/skills/ui-design-system", "category": "product", - "description": "UI design system toolkit for Senior UI Designer including design token generation, component documentation, responsive design calculations, and developer handoff tools. Use for creating design systems, maintaining visual consistency, and facilitating design-dev collaboration." + "description": "UI design system toolkit for Senior UI Designer including design token generation, component documentation, responsive design calculations, and developer handoff tools. Use when creating design systems, generating design tokens, maintaining visual consistency, or facilitating design-dev collaboration and developer handoff." }, { "name": "ux-researcher-designer", "source": "../../product-team/skills/ux-researcher-designer", "category": "product", - "description": "UX research and design toolkit for Senior UX Designer/Researcher including data-driven persona generation, journey mapping, usability testing frameworks, and research synthesis. Use for user research, persona creation, journey mapping, and design validation." + "description": "UX research and design toolkit for Senior UX Designer/Researcher including data-driven persona generation, journey mapping, usability testing frameworks, and research synthesis. Use when conducting user research, creating personas, mapping user journeys, planning usability tests, or validating designs." }, { "name": "andreessen", @@ -1833,7 +1821,7 @@ "name": "inbox-triage", "source": "../../productivity/email/skills/inbox-triage", "category": "productivity", - "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 demand. Triggers: 'triage my inbox', 'inbox triage', 'check my email', 'run email triage', 'process my inbox', 'what's new in my email', 'handle my email', 'email triage', or any variation where the user wants their inbox processed. Requires the inbox-setup skill to have been run first." + "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 demand. Use when the user wants their inbox processed, in any variation (e.g., 'triage my inbox', 'inbox triage', 'check my email', 'run email triage', 'process my inbox', 'what's new in my email', 'handle my email', 'email triage'). Requires the inbox-setup skill to have been run first." }, { "name": "reflect", @@ -1863,7 +1851,7 @@ "name": "jira-expert", "source": "../../project-management/skills/jira-expert", "category": "project-management", - "description": "Atlassian Jira expert for creating and managing projects, planning, product discovery, JQL queries, workflows, custom fields, automation, reporting, and all Jira features. Use for Jira project setup, configuration, advanced search, dashboard creation, workflow design, and technical Jira operations." + "description": "Atlassian Jira expert for creating and managing projects, planning, product discovery, JQL queries, workflows, custom fields, automation, reporting, and all Jira features. Use when setting up or configuring Jira projects, writing JQL and advanced searches, creating dashboards, designing workflows, or performing technical Jira operations." }, { "name": "meeting-analyzer", @@ -1875,7 +1863,7 @@ "name": "pm-skills", "source": "../../project-management/skills/pm-skills", "category": "project-management", - "description": "6 project management agent skills and plugins for Claude Code, Codex, Gemini CLI, Cursor, OpenClaw. Senior PM, scrum master, Jira expert (JQL), Confluence expert, Atlassian admin, template creator. MCP integration for live Jira/Confluence automation." + "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." }, { "name": "scrum-master", @@ -1899,7 +1887,7 @@ "name": "capa-officer", "source": "../../ra-qm-team/skills/capa-officer", "category": "ra-qm", - "description": "CAPA system management for medical device QMS. Covers root cause analysis, corrective action planning, effectiveness verification, and CAPA metrics. Use for CAPA investigations, 5-Why analysis, fishbone diagrams, root cause determination, corrective action tracking, effectiveness verification, or CAPA program optimization." + "description": "CAPA system management for medical device QMS. Covers root cause analysis, corrective action planning, effectiveness verification, and CAPA metrics. Use when running CAPA investigations, 5-Why analysis, fishbone diagrams, root cause determination, corrective action tracking, effectiveness verification, or CAPA program optimization." }, { "name": "eu-ai-act-specialist", @@ -1917,19 +1905,19 @@ "name": "fda-consultant-specialist", "source": "../../ra-qm-team/skills/fda-consultant-specialist", "category": "ra-qm", - "description": "FDA regulatory consultant for medical device companies. Provides 510(k)/PMA/De Novo pathway guidance, QSR (21 CFR 820) compliance, HIPAA assessments, and device cybersecurity. Use when user mentions FDA submission, 510(k), PMA, De Novo, QSR, premarket, predicate device, substantial equivalence, HIPAA medical device, or FDA cybersecurity." + "description": "FDA regulatory consultant for medical device companies. Provides 510(k)/PMA/De Novo pathway guidance, QMSR (21 CFR 820, which incorporates ISO 13485:2016 by reference since 2026-02-02; formerly QSR) compliance, HIPAA assessments, and device cybersecurity. Use when user mentions FDA submission, 510(k), PMA, De Novo, QMSR, QSR, ISO 13485 for FDA, premarket, predicate device, substantial equivalence, HIPAA medical device, or FDA cybersecurity." }, { "name": "gdpr-dsgvo-expert", "source": "../../ra-qm-team/skills/gdpr-dsgvo-expert", "category": "ra-qm", - "description": "GDPR and German DSGVO compliance automation. Scans codebases for privacy risks, generates DPIA documentation, tracks data subject rights requests. Use for GDPR compliance assessments, privacy audits, data protection planning, DPIA generation, and data subject rights management." + "description": "GDPR and German DSGVO compliance automation. Scans codebases for privacy risks, generates DPIA documentation, tracks data subject rights requests with Art. 12(3) one-month deadlines. Use when running GDPR compliance assessments, privacy audits, data protection planning, DPIA generation, or data subject rights (DSAR) management (e.g., 'check this service for GDPR risks', 'track an access request deadline'). Final compliance determinations route to the DPO or legal counsel." }, { "name": "information-security-manager-iso27001", "source": "../../ra-qm-team/skills/information-security-manager-iso27001", "category": "ra-qm", - "description": "ISO 27001 ISMS implementation and cybersecurity governance for HealthTech and MedTech companies. Use for ISMS design, security risk assessment, control implementation, ISO 27001 certification, security audits, incident response, and compliance verification. Covers ISO 27001, ISO 27002, healthcare security, and medical device cybersecurity." + "description": "ISO 27001 ISMS implementation and cybersecurity governance for HealthTech and MedTech companies. Use when designing an ISMS, running security risk assessments, implementing controls, pursuing ISO 27001 certification, preparing security audits, responding to security incidents, or verifying compliance. Covers ISO 27001, ISO 27002, healthcare security, and medical device cybersecurity." }, { "name": "isms-audit-expert", @@ -1953,25 +1941,25 @@ "name": "mdr-745-specialist", "source": "../../ra-qm-team/skills/mdr-745-specialist", "category": "ra-qm", - "description": "EU MDR 2017/745 compliance specialist for medical device classification, technical documentation, clinical evidence, and post-market surveillance. Covers Annex VIII classification rules, Annex II/III technical files, Annex XIV clinical evaluation, and EUDAMED integration." + "description": "EU MDR 2017/745 compliance specialist for medical device classification, technical documentation, clinical evidence, and post-market surveillance. Covers Annex VIII classification rules, Annex II/III technical files, Annex XIV clinical evaluation, Art. 86 PSUR schedules, and EUDAMED integration. Use when classifying a medical device under MDR, building or gap-checking a technical file, planning clinical evaluation or PMS/PSUR cadence, or preparing for notified body review (e.g., 'what class is my device under MDR', 'review my PSUR schedule')." }, { "name": "qms-audit-expert", "source": "../../ra-qm-team/skills/qms-audit-expert", "category": "ra-qm", - "description": "ISO 13485 internal audit expertise for medical device QMS. Covers audit planning, execution, nonconformity classification, and CAPA verification. Use for internal audit planning, audit execution, finding classification, external audit preparation, or audit program management." + "description": "ISO 13485 internal audit expertise for medical device QMS. Covers audit planning, execution, nonconformity classification, and CAPA verification. Use when planning internal audits, executing audits, classifying findings, preparing for external audits, or managing an audit program." }, { "name": "quality-documentation-manager", "source": "../../ra-qm-team/skills/quality-documentation-manager", "category": "ra-qm", - "description": "Document control system management for medical device QMS. Covers document numbering, version control, change management, and 21 CFR Part 11 compliance. Use for document control procedures, change control workflow, document numbering, version management, electronic signature compliance, or regulatory documentation review." + "description": "Document control system management for medical device QMS. Covers document numbering, version control, change management, and 21 CFR Part 11 compliance. Use when working on document control procedures, change control workflows, document numbering, version management, electronic signature compliance, or regulatory documentation review." }, { "name": "quality-manager-qmr", "source": "../../ra-qm-team/skills/quality-manager-qmr", "category": "ra-qm", - "description": "Senior Quality Manager Responsible Person (QMR) for HealthTech and MedTech companies. Provides quality system governance, management review leadership, regulatory compliance oversight, and quality performance monitoring per ISO 13485 Clause 5.5.2." + "description": "Senior Quality Manager Responsible Person (QMR) for HealthTech and MedTech companies. Provides quality system governance, management review leadership, regulatory compliance oversight, and quality performance monitoring per ISO 13485 Clause 5.5.2. Use when leading management reviews, setting quality policy and objectives, monitoring quality KPIs and cost of quality, or exercising QMR governance and regulatory oversight responsibilities." }, { "name": "quality-manager-qms-iso13485", @@ -1983,7 +1971,7 @@ "name": "ra-qm-skills", "source": "../../ra-qm-team/skills/ra-qm-skills", "category": "ra-qm", - "description": "12 regulatory & QM agent skills and plugins for Claude Code, Codex, Gemini CLI, Cursor, OpenClaw. ISO 13485 QMS, MDR 2017/745, FDA 510(k)/PMA, ISO 27001 ISMS, GDPR/DSGVO, risk management (ISO 14971), CAPA, document control, auditing. Python tools (stdlib-only)." + "description": "Router/index for the 15 regulatory & quality-management skills bundled in this plugin (ISO 13485 QMS, EU MDR 2017/745, FDA submissions under QMSR, ISO 14971 risk, CAPA, document control, ISO 27001/ISMS, ISO 42001 AIMS, EU AI Act, GDPR/DSGVO, SOC 2, auditing). Use when a compliance request doesn't obviously match one skill and you need to pick the right one (e.g., 'prepare us for an ISO 13485 audit', 'is my AI system high-risk under the AI Act')." }, { "name": "regulatory-affairs-head", @@ -2007,49 +1995,49 @@ "name": "dossier", "source": "../../research/dossier/skills/dossier", "category": "research", - "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 signals, reputation signals, red flags, 3-5 conversation hooks tied to specific findings, and source-provenance audit log. Uses WebSearch + WebFetch + free APIs (SEC EDGAR, GitHub, ProPublica Nonprofit Explorer) as workhorses; optional BYOK MCPs (LinkedIn, Crunchbase, Apollo, Pitchbook, SimilarWeb) enhance coverage. Triggers: 'research [company]', 'dossier on [person/company]', 'background check on [entity]', 'prep me for a meeting with [person/company]', 'due diligence on [company]', 'what should I know about [entity]', 'research [person] before I [meet/hire/invest]', 'competitor research on [company]', 'investor diligence [company]', 'interview prep for [company]'. Honors sensitivity exclusions for journalism + personal-vetting contexts." + "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 + free APIs (SEC EDGAR, GitHub, ProPublica) as workhorses; optional BYOK MCPs enhance coverage. Use when the user asks for background research, diligence, or meeting prep on a specific entity (e.g., 'prep me for a meeting with [person/company]', 'due diligence on [company]'). Honors sensitivity exclusions for journalism + personal-vetting contexts." }, { "name": "grants", "source": "../../research/grants/skills/grants", "category": "research", - "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 recommendation. Triggers: 'grants for [topic]', 'find grants for my research idea', 'what grants match my research', 'help me find NIH funding', 'grant opportunities for my research', or any grant-related request. NIH-only scope \u2014 non-NIH funders (PCORI, DOD CDMRP, VA, foundations) are out of scope and flagged at intake." + "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 recommendation. Use when the user asks about research funding or makes any grant-related request (e.g., 'grants for [topic]', 'find grants for my research idea', 'what grants match my research', 'help me find NIH funding', 'grant opportunities for my research'). NIH-only scope \u2014 non-NIH funders (PCORI, DOD CDMRP, VA, foundations) are out of scope and flagged at intake." }, { "name": "litreview", "source": "../../research/litreview/skills/litreview", "category": "research", - "description": "Academic literature orientation skill that searches papers via Consensus, builds a strategic search plan using PICO (default) or SPIDER / Decomposition / hybrid as fallbacks, and synthesizes findings into a professionally formatted Word document (.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. Configurable depth (5/10/20 queries) controls coverage vs. speed. Output is a 'launching pad' \u2014 not a finished review, but an orientation guide that lets a researcher dive in confidently. Triggers: 'litreview on [topic]', 'literature review on [topic]', 'I'm starting a literature review on X', 'I'm writing a paper on X', 'help me research X', 'I'm doing research on X', 'can you help me research X'. Do NOT trigger for single one-off paper searches where the user just wants a quick list \u2014 that's a plain Consensus search." + "description": "Academic literature orientation skill that searches papers via Consensus, 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. Configurable depth (5/10/20 queries) controls coverage vs. speed. Output is a 'launching pad' \u2014 an orientation guide that lets a researcher dive in confidently, not a finished review. Use when the user starts literature-oriented research (e.g., 'litreview on [topic]', 'literature review on [topic]', 'I'm starting a literature review on X', 'I'm writing a paper on X', 'help me research X', 'I'm doing research on X', 'can you help me research X'). Do NOT use for single one-off paper searches wanting a quick list \u2014 that's a plain Consensus search." }, { "name": "notebooklm", "source": "../../research/notebooklm/skills/notebooklm", "category": "research", - "description": "Browser automation skill for controlling Google's NotebookLM. Handles reading and querying notebooks, adding sources (URLs, text, files, YouTube links, synthesized content), generating Studio outputs (Audio Overview, infographics, slide decks, study guides, briefing docs, mind maps, timelines, FAQs), and creating new notebooks. Triggers on any phrase involving NotebookLM \u2014 'open NotebookLM', 'check my [name] notebook', 'pull info from NotebookLM', 'ask my notebook about X', 'add [source] to NotebookLM', 'create an infographic in NotebookLM', 'use NotebookLM Studio', 'generate a slide deck from my notebook', or any variation where the goal involves NotebookLM. Requires browser automation environment \u2014 fails gracefully when unavailable." + "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 Studio panel; the UI evolves fast), and creating new notebooks. Requires browser automation environment \u2014 fails gracefully when unavailable." }, { "name": "patent", "source": "../../research/patent/skills/patent", "category": "research", - "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 log. Triggers: 'prior art search for [invention]', 'patent search on [topic]', 'freedom to operate analysis', 'FTO for [product]', 'patent landscape for [field]', 'is [invention] novel', 'patents on [topic]', 'competitive patent analysis', 'prior art for litigation', 'patent diligence on [company]'. Produces search signal, not legal advice \u2014 always recommends consulting a patent attorney before filing or licensing decisions. Trademark, copyright, and trade-secret questions are out of scope." + "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 log. Use when the user asks for patent searching or analysis (e.g., 'prior art search for [invention]', 'freedom to operate analysis for [product]'). Produces search signal, not legal advice \u2014 always recommends consulting a patent attorney before filing or licensing decisions. Trademark, copyright, and trade-secret questions are out of scope." }, { "name": "pulse", "source": "../../research/pulse/skills/pulse", "category": "research", - "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. Triggers: 'pulse on [topic]', 'what's happening with [topic]', 'what are people saying about [topic]', 'current conversation about [topic]', 'take the pulse of [topic]', 'trending: [topic]', 'find me info on [topic]', or any variation requesting multi-source recency intelligence on a topic. Also use for competitor research, trend discovery, tool comparisons, and audience sentiment analysis." + "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 saying about [topic]', 'current conversation about [topic]', 'take the pulse of [topic]', 'trending: [topic]', 'find me info on [topic]'), and for competitor research, trend discovery, tool comparisons, and audience sentiment analysis." }, { "name": "research", "source": "../../research/research/skills/research", "category": "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. Triggers \u2014 \"research [topic]\", \"look into [topic]\", \"what do we know about [topic]\", \"investigate [topic]\", \"find me information on [topic]\", \"do some research on [topic]\", \"I need to understand [topic]\", or any research request that doesn't obviously match a more-specific specialist skill. Output is a markdown briefing (default) or .docx document (on request) with full citations and an audit log." + "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-specific specialist skill (e.g., \"research [topic]\", \"look into [topic]\", \"what do we know about [topic]\", \"investigate [topic]\", \"find me information on [topic]\", \"do some research on [topic]\", \"I need to understand [topic]\"). Output is a markdown briefing (default) or .docx document (on request) with full citations and an audit log." }, { "name": "syllabus", "source": "../../research/syllabus/skills/syllabus", "category": "research", - "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 questions tied to course learning goals. Triggers whenever a user uploads a syllabus, course outline, or curriculum document and wants supplementary readings. Also triggers on: 'syllabus reading list', 'find papers for my course', 'create a reading list from this syllabus', 'recent research for my class', 'supplementary readings', 'find journal articles for these topics', 'what recent papers cover this material', 'any new research on these course topics', 'update my syllabus with recent papers'. Even casual mentions when a syllabus is attached should trigger this skill." + "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 questions tied to course learning goals. Use when the user uploads a syllabus, course outline, or curriculum document and wants supplementary readings (e.g., 'create a reading list from this syllabus', 'find recent papers for my course') \u2014 even casual mentions with a syllabus attached should trigger this skill." }, { "name": "clinical-research", @@ -2119,7 +2107,7 @@ "description": "Software engineering and technical skills" }, "engineering-advanced": { - "count": 79, + "count": 78, "source": "../../engineering", "description": "Advanced engineering skills - agents, RAG, MCP, CI/CD, databases, observability" }, @@ -2129,7 +2117,7 @@ "description": "Financial analysis, valuation, and forecasting skills" }, "marketing": { - "count": 49, + "count": 48, "source": "../../marketing-skill", "description": "Marketing, content, and demand generation skills" }, diff --git a/.codex/skills/ai-seo b/.codex/skills/ai-seo deleted file mode 120000 index 680ba044..00000000 --- a/.codex/skills/ai-seo +++ /dev/null @@ -1 +0,0 @@ -../../marketing-skill/skills/ai-seo \ No newline at end of file diff --git a/.codex/skills/collab-proof b/.codex/skills/collab-proof new file mode 120000 index 00000000..e5b91243 --- /dev/null +++ b/.codex/skills/collab-proof @@ -0,0 +1 @@ +../../engineering/collab-proof/skills/collab-proof \ No newline at end of file diff --git a/.codex/skills/command-guide b/.codex/skills/command-guide deleted file mode 120000 index 305c24ea..00000000 --- a/.codex/skills/command-guide +++ /dev/null @@ -1 +0,0 @@ -../../engineering/skills/command-guide \ No newline at end of file diff --git a/.codex/skills/release-manager b/.codex/skills/release-manager deleted file mode 120000 index 02eba022..00000000 --- a/.codex/skills/release-manager +++ /dev/null @@ -1 +0,0 @@ -../../engineering/skills/release-manager \ No newline at end of file diff --git a/.codex/skills/review b/.codex/skills/review index 647ec915..b4fa2536 120000 --- a/.codex/skills/review +++ b/.codex/skills/review @@ -1 +1 @@ -../../engineering-team/playwright-pro/skills/review \ No newline at end of file +../../engineering-team/self-improving-agent/skills/review \ No newline at end of file diff --git a/.codex/skills/universal-scraping-architect b/.codex/skills/universal-scraping-architect index 12d64987..513a1a12 120000 --- a/.codex/skills/universal-scraping-architect +++ b/.codex/skills/universal-scraping-architect @@ -1 +1 @@ -../../engineering/universal-scraping-architect \ No newline at end of file +../../engineering/universal-scraping-architect/skills/universal-scraping-architect \ No newline at end of file diff --git a/.gemini/skills-index.json b/.gemini/skills-index.json index 09c73621..bd63544b 100644 --- a/.gemini/skills-index.json +++ b/.gemini/skills-index.json @@ -1,7 +1,7 @@ { "version": "1.0.0", "name": "gemini-cli-skills", - "total_skills": 410, + "total_skills": 418, "skills": [ { "name": "README", @@ -16,7 +16,7 @@ { "name": "content-strategist", "category": "agent", - "description": "Builds content engines that rank, convert, and compound. Thinks in systems \u2014 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 \u2014 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 \u2014 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.)" }, { "name": "cs-aeo", @@ -26,7 +26,7 @@ { "name": "cs-agile-product-owner", "category": "agent", - "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 \u2014 e.g., decomposing a large epic into INVEST-compliant stories with acceptance criteria, or refining a messy backlog ahead of sprint planning." }, { "name": "cs-backend-engineer", @@ -36,22 +36,22 @@ { "name": "cs-ceo-advisor", "category": "agent", - "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 \u2014 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." }, { "name": "cs-content-creator", "category": "agent", - "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 \u2014 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." }, { "name": "cs-cto-advisor", "category": "agent", - "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 \u2014 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." }, { "name": "cs-demand-gen-specialist", "category": "agent", - "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 \u2014 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." }, { "name": "cs-engineering-lead", @@ -86,22 +86,22 @@ { "name": "cs-product-analyst", "category": "agent", - "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 \u2014 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." }, { "name": "cs-product-manager", "category": "agent", - "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 \u2014 e.g., RICE-scoring a backlog of 20 feature requests before quarterly planning, or drafting a PRD from raw customer-interview notes." }, { "name": "cs-product-strategist", "category": "agent", - "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 \u2014 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." }, { "name": "cs-project-manager", "category": "agent", - "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 \u2014 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." }, { "name": "cs-quality-regulatory", @@ -116,7 +116,12 @@ { "name": "cs-ux-researcher", "category": "agent", - "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 \u2014 e.g., planning interview scripts and recruiting criteria for a discovery study, or synthesizing usability-test sessions into prioritized findings and updated personas." + }, + { + "name": "cs-webinar-marketer", + "category": "agent", + "description": "Webinar & virtual-event marketing specialist agent. Use when planning, promoting, running, or rescuing a webinar, virtual event, live demo, workshop, masterclass, fireside chat, or virtual summit. Orchestrates the webinar-marketing skill \u2014 sizes the funnel backward from the business goal, builds the promotion runway, designs the show-up and live-to-close sequences, scores an existing funnel to find the broken stage, and plans evergreen/on-demand automation. Treats a webinar as a funnel, not an event. Voice \u2014 outcome-obsessed demand operator; refuses to celebrate registrations when nobody shows up or buys; fixes the stage that's actually broken instead of rewriting the landing page by reflex." }, { "name": "cs-wiki-ingestor", @@ -141,37 +146,37 @@ { "name": "devops-engineer", "category": "agent", - "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 \u2014 e.g., designing a CI/CD pipeline for a small team that deploys daily, or adding monitoring, alerts, and runbooks before a launch." }, { "name": "finance-lead", "category": "agent", - "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 \u2014 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.)" }, { "name": "growth-marketer", "category": "agent", - "description": "Growth marketing specialist for bootstrapped startups and indie hackers. Builds content engines, optimizes funnels, runs launch sequences, and finds scalable acquisition channels \u2014 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 \u2014 all on a budget that makes enterprise marketers cry. Use when growth has to come before budget \u2014 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.)" }, { "name": "product-manager", "category": "agent", - "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 \u2014 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.)" }, { "name": "solo-founder", "category": "agent", - "description": "Your co-founder who doesn't exist yet. Covers product, engineering, marketing, and strategy for one-person startups \u2014 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 \u2014 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 \u2014 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." }, { "name": "startup-cto", "category": "agent", - "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 \u2014 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 \u2014 all while shipping fast with a small team. Use when an early-stage team needs pragmatic, ship-first technical leadership \u2014 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.)" }, { "name": "business-growth-skills", "category": "business-growth", - "description": "4 business growth agent skills and plugins for Claude Code, Codex, Gemini CLI, Cursor, OpenClaw. Customer success (health scoring, churn), sales engineer (RFP), revenue operations (pipeline, GTM), contract & proposal writer. Python tools (stdlib-only)." + "description": "Router/index for the 4 business & growth skills bundled in this plugin: customer-success-manager (health scoring, churn risk, expansion), sales-engineer (RFP analysis, competitive matrices, PoC planning), revenue-operations (pipeline, forecast accuracy, GTM efficiency), and contract-and-proposal-writer. Use when a growth/revenue request doesn't obviously match one skill and you need to pick the right one (e.g., 'which accounts are at risk', 'should we bid on this RFP')." }, { "name": "contract-and-proposal-writer", @@ -206,12 +211,12 @@ { "name": "internal-comms", "category": "business-operations", - "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 benefit change, a leadership transition, a layoff, an acquisition close, or an internal product launch \u2014 and the audience is employees (not customers). Triggers on \"all-hands announcement\", \"town-hall script\", \"change comms\", \"internal newsletter\", \"rollout comms\", \"policy change announcement\", \"re-org announcement\", \"internal FAQ\", \"manager talking points\", \"Prosci ADKAR\", \"Kotter 8-step\", \"layoff comms\", \"RIF comms\", \"internal memo\". Pairs Prosci ADKAR (Awareness / Desire / Knowledge / Ability / Reinforcement) 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-tuned via --profile {tech-startup, scaleup, enterprise, public-company, non-profit}. Distinct from marketing-skill/* (external/customer-facing), c-level-advisor/internal-narrative (strategic framing, not tactical drafts), and c-level-advisor/change-management (executive change strategy, not the comms package itself)." + "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-tuned via --profile {tech-startup, scaleup, enterprise, public-company, non-profit}. Triggers on \"all-hands announcement\", \"change comms\", \"rollout comms\", \"re-org announcement\", \"manager talking points\", \"layoff comms\"." }, { "name": "knowledge-ops", "category": "business-operations", - "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, expense reimbursement, system-access provisioning, customer-escalation playbook) \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, ops onboarding doc generation, and runbook step verification (named owner, expected duration, observable success signal, rollback path, escalation contact). Pairs Kaoru Ishikawa's 5W2H method, Atul Gawande's *The Checklist Manifesto*, ISO 9001, ITIL v4 Service Operation, FDA 21 CFR Part 211, and Google SRE Workbook runbook discipline with deterministic stdlib-only Python tools that score completeness, detect anti-patterns, and emit prioritized cleanup lists. Distinct from `engineering/llm-wiki` (Karpathy-style personal PKM second brain), `engineering-team/runbook-generator` (system-ops production debugging runbook), `project-management/*` (Jira/Confluence delivery + ticket tracking), and sibling `business-operations/process-mapper` (BPMN process *design*, while knowledge-ops is process *documentation*)." + "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 Manifesto*, ISO 9001, ITIL v4, and Google SRE Workbook runbook discipline with deterministic stdlib-only Python tools that score completeness, detect anti-patterns, and emit prioritized cleanup lists (e.g., \"validate this runbook before it goes into rotation\", \"audit our Confluence wiki for stale and orphaned SOPs\")." }, { "name": "process-mapper", @@ -221,12 +226,12 @@ { "name": "procurement-optimizer", "category": "business-operations", - "description": "Use when running an annual SaaS audit, doing category-level spend review, or rationalizing the supplier base \u2014 when the user needs to do a spend audit, spend categorization (UNSPSC-aligned), purchasing-cycle analysis, or risk-balanced supplier consolidation. Triggers on \"spend audit\", \"SaaS audit\", \"spend categorization\", \"supplier rationalization\", \"supplier consolidation\", \"purchasing cycle\", \"procurement review\", \"category strategy\", \"duplicate SaaS\", \"renewal cluster\". Ships 3 stdlib-only Python tools (UNSPSC-aligned spend categorizer with Pareto breakdown and industry profiles, purchasing-cycle analyzer that surfaces bottleneck categories per Goldratt's Theory of Constraints, supplier-consolidation planner that refuses single-source recommendations for tier-1 categories without a documented break-glass plan), 3 reference docs each citing 7+ authoritative sources (A.T. Kearney / Hackett / Spend Matters / UNSPSC / Productiv / Vendr / Tropic / IACCM / ISM / BCG), and a 20-minute spend-intake template. Distinct from sibling vendor-management (performance scoring of vendors you keep paying), finance/financial-analysis (close + report, not category strategy), and c-level-advisor/general-counsel-advisor (contract law, not category rationalization)." + "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\", \"duplicate SaaS\", \"renewal cluster\"." }, { "name": "vendor-management", "category": "business-operations", - "description": "Use when reviewing, scoring, or auditing third-party SaaS / vendor relationships \u2014 running a vendor scorecard, tracking SLA compliance, classifying third-party risk, preparing a tier-1 vendor review, or auditing the SaaS portfolio. Triggers on \"vendor SLA\", \"vendor scorecard\", \"third-party risk\", \"TPRM\", \"vendor review\", \"SaaS audit\", \"supplier performance\", \"vendor health check\", \"renewal review\". Forks context so large vendor catalogs (50-500 line items) and SLA logs don't pollute the parent thread. Ships 3 stdlib-only Python tools (vendor scorer with industry tuning, SLA compliance tracker with credit-claim flags, vendor risk classifier across 4 risk vectors), 3 reference docs each citing 7+ authoritative sources (Gartner / Shared Assessments / NIST / ISO 27036 / breach post-mortems), and a 5-vendor catalog template. Distinct from c-level-advisor/general-counsel-advisor (contract law, not operational management), business-growth/contract-and-proposal-writer (outbound proposals, not inbound vendor scoring), and sibling procurement-optimizer (spend categorization, not vendor performance)." + "description": "Use when reviewing, scoring, or auditing third-party SaaS / vendor relationships \u2014 running a vendor scorecard with industry tuning, tracking SLA compliance with credit-claim flags, classifying third-party risk across 4 risk vectors, preparing a tier-1 vendor review, or auditing the SaaS portfolio. Forks context so large vendor catalogs (50-500 line items) and SLA logs don't pollute the parent thread. Triggers on \"vendor SLA\", \"vendor scorecard\", \"third-party risk\", \"TPRM\", \"vendor review\", \"supplier performance\", \"vendor health check\", \"renewal review\"." }, { "name": "agent-protocol", @@ -241,7 +246,7 @@ { "name": "board-meeting", "category": "c-level", - "description": "Multi-agent board meeting protocol for strategic decisions. Runs a structured 6-phase deliberation: context loading, independent C-suite contributions (isolated, no cross-pollination), critic analysis, synthesis, founder review, and decision extraction. Use when the user invokes /cs:board, calls a board meeting, or wants structured multi-perspective executive deliberation on a strategic question." + "description": "Multi-agent board meeting protocol for strategic decisions. Runs a structured 6-phase deliberation: context loading, independent C-suite contributions (isolated, no cross-pollination), critic analysis, synthesis, founder review, and decision extraction. Use when the user invokes /cs:boardroom, calls a board meeting, or wants structured multi-perspective executive deliberation on a strategic question." }, { "name": "board-prep", @@ -251,37 +256,37 @@ { "name": "boardroom", "category": "c-level", - "description": "/cs:boardroom \u2014 6-phase multi-role deliberation across the C-suite with Phase 2 isolation, critic pre-screen, and synthesis. Outputs a board memo." + "description": "/cs:boardroom \u2014 6-phase multi-role deliberation across the C-suite with Phase 2 isolation, critic pre-screen, and synthesis. Outputs a board memo. Use when a decision spans multiple executive domains \u2014 e.g. a pricing change touching finance, positioning, and product, or a raise-vs-cut runway call." }, { "name": "brief", "category": "c-level", - "description": "/cs:brief \u2014 Generate a one-page strategy brief from an office-hours intake. First step in the strategic sprint pipeline." + "description": "/cs:brief \u2014 Generate a one-page strategy brief from an office-hours intake. First step in the strategic sprint pipeline. Use when a strategic question needs to be framed before boardroom deliberation \u2014 e.g. locking options, assumptions, and success criteria for a pricing change or a market-entry decision." }, { "name": "c-level-agents", "category": "c-level", - "description": "Founder-mode executive team. 8 cs-* C-suite agents (CFO, CMO, CRO, CPO, COO, CHRO, CISO, Chief of Staff) and 17 /cs:* slash commands for forcing-question office hours, multi-role boardroom deliberation, strategic sprint pipeline, and meta routing. Use when the founder needs a virtual executive team, when invoking /cs:* commands, or when orchestrating multi-role decisions." + "description": "Founder-mode executive team. 13 cs-* C-suite agents (CFO, CMO, CRO, CPO, COO, CHRO, CISO, GC, CDO, CAIO, CCO, VPE, Chief of Staff) and 21 /cs:* slash commands for forcing-question office hours, multi-role boardroom deliberation, strategic sprint pipeline, and meta routing. Use when the founder needs a virtual executive team, when invoking /cs:* commands, or when orchestrating multi-role decisions." }, { "name": "c-level-skills", "category": "c-level", - "description": "10 C-level advisory agent skills and plugins for Claude Code, Codex, Gemini CLI, Cursor, OpenClaw. CEO, CTO, COO, CPO, CMO, CFO, CRO, CISO, CHRO, Executive Mentor. Multi-role board meetings, strategy routing, structured recommendations. For founders needing executive-level decision support." + "description": "Index and router for the C-level advisory bundle: 33 skills covering 14 C-suite roles, orchestration, cross-cutting capabilities, and culture. Use when exploring what the c-level-advisor bundle contains, deciding which advisor skill fits a question, or finding the entry points (cs-onboard interview, chief-of-staff routing, board-meeting protocol)." }, { "name": "caio-review", "category": "c-level", - "description": "/cs:caio-review \u2014 Eval-demanding Chief AI Officer interrogation of any plan that involves AI: model selection, risk classification, cost economics, or AI hiring." + "description": "/cs:caio-review \u2014 Eval-demanding Chief AI Officer interrogation of any plan that involves AI: model selection, risk classification, cost economics, or AI hiring. Use when shipping an AI feature without an eval set, choosing between API, fine-tune, and self-hosted, or classifying a use case under the EU AI Act." }, { "name": "cco-review", "category": "c-level", - "description": "/cs:cco-review \u2014 Retention-obsessed Chief Customer Officer interrogation of any plan that touches customer retention, segmentation, CS team sizing, or CS team hiring." + "description": "/cs:cco-review \u2014 Retention-obsessed Chief Customer Officer interrogation of any plan that touches customer retention, segmentation, CS team sizing, or CS team hiring. Use when gross retention is slipping, before approving CSM headcount, or when deciding which customer segments to keep or fire." }, { "name": "cdo-review", "category": "c-level", - "description": "/cs:cdo-review \u2014 Decision-driven Chief Data Officer interrogation of any plan that touches training data, data architecture, data productization, or data team hiring." + "description": "/cs:cdo-review \u2014 Decision-driven Chief Data Officer interrogation of any plan that touches training data, data architecture, data productization, or data team hiring. Use when validating training-data rights before model work, choosing warehouse vs lakehouse vs mesh, or valuing data assets for productization or M&A." }, { "name": "ceo-advisor", @@ -296,7 +301,7 @@ { "name": "cfo-review", "category": "c-level", - "description": "/cs:cfo-review \u2014 Numerate-skeptic interrogation of any plan that touches money. Unit economics, runway, dilution, capital allocation." + "description": "/cs:cfo-review \u2014 Numerate-skeptic interrogation of any plan that touches money. Unit economics, runway, dilution, capital allocation. Use when a plan commits meaningful spend \u2014 e.g. a hiring wave, a fundraise decision, or a new channel budget." }, { "name": "challenge", @@ -326,7 +331,7 @@ { "name": "chief-of-staff", "category": "c-level", - "description": "C-suite orchestration layer. Routes founder questions to the right advisor role(s), triggers multi-role board meetings for complex decisions, synthesizes outputs, and tracks decisions. Every C-suite interaction starts here. Loads company context automatically." + "description": "C-suite orchestration layer. Routes founder questions to the right advisor role(s), triggers multi-role board meetings for complex decisions, synthesizes outputs, and tracks decisions. Every C-suite interaction starts here. Loads company context automatically. Use when a founder question needs routing to the right advisor \u2014 e.g. 'should we raise now or cut burn?' \u2014 or when a multi-domain decision needs a board meeting convened." }, { "name": "chro-advisor", @@ -341,7 +346,7 @@ { "name": "ciso-review", "category": "c-level", - "description": "/cs:ciso-review \u2014 Risk-paranoid interrogation of any plan that touches data, compliance, or production access." + "description": "/cs:ciso-review \u2014 Risk-paranoid interrogation of any plan that touches data, compliance, or production access. Use when launching features that handle customer data, before a SOC 2 / ISO audit, or after any incident or near-miss." }, { "name": "cmo-advisor", @@ -351,7 +356,7 @@ { "name": "cmo-review", "category": "c-level", - "description": "/cs:cmo-review \u2014 Narrative-first interrogation of positioning, ICP, message house, and channel mix." + "description": "/cs:cmo-review \u2014 Narrative-first interrogation of positioning, ICP, message house, and channel mix. Use when launching a campaign or repositioning, or when CAC is rising and the one-sentence positioning test fails." }, { "name": "company-os", @@ -366,7 +371,7 @@ { "name": "context-engine", "category": "c-level", - "description": "Loads and manages company context for all C-suite advisor skills. Reads ~/.claude/company-context.md, detects stale context (>90 days), enriches context during conversations, and enforces privacy/anonymization rules before external API calls." + "description": "Loads and manages company context for all C-suite advisor skills. Reads ~/.claude/company-context.md, detects stale context (>90 days), enriches context during conversations, and enforces privacy/anonymization rules before external API calls. Use when starting any C-suite advisor session, when context looks stale or missing, or before sending company data to an external service." }, { "name": "coo-advisor", @@ -381,7 +386,7 @@ { "name": "cpo-review", "category": "c-level", - "description": "/cs:cpo-review \u2014 JTBD-driven interrogation of product roadmap, PMF signal, and portfolio focus." + "description": "/cs:cpo-review \u2014 JTBD-driven interrogation of product roadmap, PMF signal, and portfolio focus. Use when committing a quarter's roadmap, deciding whether to kill a feature, or claiming PMF without a retention curve." }, { "name": "cro-advisor", @@ -391,17 +396,17 @@ { "name": "cro-review", "category": "c-level", - "description": "/cs:cro-review \u2014 Pipeline-paranoid interrogation of revenue, win rate, NRR, and ramp time." + "description": "/cs:cro-review \u2014 Pipeline-paranoid interrogation of revenue, win rate, NRR, and ramp time. Use when the forecast misses pipeline coverage, win rates drop, or before scaling the sales team." }, { "name": "cross-eval", "category": "c-level", - "description": "/cs:cross-eval \u2014 Multi-model consensus on a board memo or strategy brief. Claude + Codex + Gemini cross-review with graceful degradation." + "description": "/cs:cross-eval \u2014 Multi-model consensus on a board memo or strategy brief. Claude + Codex + Gemini cross-review with graceful degradation. Use when a high-stakes memo needs an independent sanity check before the boardroom \u2014 e.g. a bet-the-company pivot or fundraise terms." }, { "name": "cs-onboard", "category": "c-level", - "description": "Founder onboarding interview that captures company context across 7 dimensions. Invoke with /cs:setup for initial interview or /cs:update for quarterly refresh. Generates ~/.claude/company-context.md used by all C-suite advisor skills." + "description": "Founder onboarding interview that captures company context across 7 dimensions. Invoke with /cs:setup for initial interview or /cs:update for quarterly refresh. Generates ~/.claude/company-context.md used by all C-suite advisor skills. Use when setting up the C-suite advisors for the first time, or when company context is missing or more than 90 days old \u2014 e.g. after a fundraise or pivot." }, { "name": "cto-advisor", @@ -411,7 +416,7 @@ { "name": "cto-review", "category": "c-level", - "description": "/cs:cto-review \u2014 Architecture and scaling interrogation. Tech debt, scaling cliffs, team scaling, build-vs-buy." + "description": "/cs:cto-review \u2014 Architecture and scaling interrogation. Tech debt, scaling cliffs, team scaling, build-vs-buy. Use when committing to an architecture, planning for 10x load, or weighing a rebuild against a vendor." }, { "name": "culture-architect", @@ -421,7 +426,7 @@ { "name": "decide", "category": "c-level", - "description": "/cs:decide \u2014 Log a decision to two-layer memory via decision-logger. Approved memo becomes durable; raw transcripts kept for reference." + "description": "/cs:decide \u2014 Log a decision to two-layer memory via decision-logger. Approved memo becomes durable; raw transcripts kept for reference. Use when the founder has approved a boardroom memo and the decision must become durable company memory \u2014 e.g. right after /cs:boardroom concludes." }, { "name": "decision-logger", @@ -431,7 +436,7 @@ { "name": "execute", "category": "c-level", - "description": "/cs:execute \u2014 Generate a 90-day execution plan with weekly milestones, DRIs, and check-in cadence from an approved decision." + "description": "/cs:execute \u2014 Generate a 90-day execution plan with weekly milestones, DRIs, and check-in cadence from an approved decision. Use when a logged decision needs to become an operating plan \u2014 e.g. turning an approved market-entry call into weekly milestones with DRIs." }, { "name": "executive-mentor", @@ -446,17 +451,17 @@ { "name": "founder-mode", "category": "c-level", - "description": "/cs:founder-mode \u2014 Auto-routes any founder question to the right C-role advisor or to /cs:boardroom for multi-role topics. The single-command entry point." + "description": "/cs:founder-mode \u2014 Auto-routes any founder question to the right C-role advisor or to /cs:boardroom for multi-role topics. The single-command entry point. Use when a founder asks any strategic question without knowing which advisor or command fits \u2014 e.g. 'runway pressure' routes to the CFO, 'gross retention dropped' routes to the CCO." }, { "name": "freeze", "category": "c-level", - "description": "/cs:freeze \u2014 Lock a strategic decision for a cooldown period to prevent impulse reversal. Mirrors gstack's safety primitives for the business layer." + "description": "/cs:freeze \u2014 Lock a strategic decision for a cooldown period to prevent impulse reversal. Mirrors gstack's safety primitives for the business layer. Use when an irreversible decision was made under pressure \u2014 e.g. a layoff plan or multi-year contract \u2014 and deserves a cooling-off lock before execution." }, { "name": "gc-review", "category": "c-level", - "description": "/cs:gc-review \u2014 General Counsel interrogation of contracts, IP, regulatory, term sheets, and employment-law surface." + "description": "/cs:gc-review \u2014 General Counsel interrogation of contracts, IP, regulatory, term sheets, and employment-law surface. Use when reviewing a term sheet before signing, redlining a customer MSA, or checking IP assignment and regulatory exposure on a new product." }, { "name": "general-counsel-advisor", @@ -466,7 +471,7 @@ { "name": "hard-call", "category": "c-level", - "description": "/em -hard-call \u2014 Framework for Decisions With No Good Options" + "description": "/em:hard-call \u2014 Framework for decisions with no good options. Use when every option is painful and a structured 10/10/10 + regret-minimization pass is needed \u2014 e.g. choosing between a layoff and a down round, or killing a beloved product line." }, { "name": "internal-narrative", @@ -486,12 +491,12 @@ { "name": "office-hours", "category": "c-level", - "description": "/cs:office-hours \u2014 YC-style 6-question founder interrogation before any advice. Forces clarity on problem, customer, distribution, defensibility, capital, and founder fit." + "description": "/cs:office-hours \u2014 YC-style 6-question founder interrogation before any advice. Forces clarity on problem, customer, distribution, defensibility, capital, and founder fit. Use when a founder question is too vague to route \u2014 e.g. 'should we grow faster?' \u2014 or before drafting a strategy brief." }, { "name": "onboard", "category": "c-level", - "description": "/cs:onboard \u2014 Founder interview that populates ~/.claude/company-context.md. The first command to run when starting with c-level-agents." + "description": "/cs:onboard \u2014 Founder interview that populates ~/.claude/company-context.md using the canonical 7-dimension cs-onboard schema. The first command to run when starting with c-level-agents. Use when setting up the virtual C-suite for a new company, or when advisors lack company context \u2014 e.g. before a first /cs:boardroom or after a fundraise changes the numbers." }, { "name": "org-health-diagnostic", @@ -501,12 +506,12 @@ { "name": "post-mortem", "category": "c-level", - "description": "/cs:post-mortem \u2014 Honest retrospective on an executed decision, scored against original assumptions and dissent. Closes the strategic sprint loop." + "description": "/cs:post-mortem \u2014 Honest retrospective on an executed decision, scored against original assumptions and dissent. Closes the strategic sprint loop. Use when a decision hits its 90-day review checkpoint or its kill criteria trigger \u2014 e.g. scoring last quarter's pricing change against its pre-committed success metrics." }, { "name": "postmortem", "category": "c-level", - "description": "/em -postmortem \u2014 Honest Analysis of What Went Wrong" + "description": "/em:postmortem \u2014 Honest analysis of what went wrong. Use after a failed launch, missed quarter, or bad hire to run a blameless 5-Whys retrospective with a change register \u2014 e.g. dissecting why the Q3 release slipped six weeks." }, { "name": "scenario-war-room", @@ -546,7 +551,7 @@ { "name": "stress-test", "category": "c-level", - "description": "/em -stress-test \u2014 Business Assumption Stress Testing" + "description": "/em:stress-test \u2014 Business assumption stress testing. Use before betting on a plan whose core assumptions are unvalidated \u2014 e.g. stress-testing 'enterprise buyers will tolerate a 6-month pilot' or a hockey-stick revenue model." }, { "name": "vpe-advisor", @@ -556,7 +561,7 @@ { "name": "vpe-review", "category": "c-level", - "description": "/cs:vpe-review \u2014 Throughput-first VP of Engineering interrogation of any plan that touches delivery, eng hiring, team structure, or production discipline." + "description": "/cs:vpe-review \u2014 Throughput-first VP of Engineering interrogation of any plan that touches delivery, eng hiring, team structure, or production discipline. Use when cycle time balloons, DORA metrics slide, or before committing to an eng hiring wave or a reorg." }, { "name": "changelog", @@ -613,6 +618,11 @@ "category": "command", "description": "Fullstack engineering review \u2014 walks the 7 Matt Pocock forcing questions, picks the profile, forks into POWERFUL specialists (api-design-reviewer, database-designer, slo-architect). Invokes the cs-fullstack-engineer agent with context fork." }, + { + "name": "cs-webinar", + "category": "command", + "description": "/cs:webinar \u2014 Webinar & virtual-event marketing workflow. Plan a webinar from scratch (sized backward from the business goal), rescue one whose numbers disappointed (score the funnel, fix the broken stage), or turn a past webinar into an evergreen on-demand lead engine. Covers the full funnel: registration, promotion runway, show-up, live engagement, live-to-close, and segmented follow-up. Treats a webinar as a funnel, not an event." + }, { "name": "financial-health", "category": "command", @@ -661,7 +671,7 @@ { "name": "prd", "category": "command", - "description": "Quick PRD generation command. Usage: /prd " + "description": "Gated PRD generation \u2014 interrogates problem, user, and metric before drafting; refuses to draft on unknowns. Usage: /prd " }, { "name": "project-health", @@ -701,7 +711,7 @@ { "name": "sprint-plan", "category": "command", - "description": "Sprint planning shortcut. Usage: /sprint-plan [capacity]" + "description": "Capacity-gated sprint planning \u2014 runs capacity math, carry-over check, and a definition-of-ready gate before committing scope. Usage: /sprint-plan [capacity]" }, { "name": "tc", @@ -711,7 +721,7 @@ { "name": "tdd", "category": "command", - "description": "Generate tests, analyze coverage, and run TDD workflows. Usage: /tdd [options]" + "description": "Run a red-green-refactor TDD workflow \u2014 generate failing tests first, implement to green, then check coverage gaps. Usage: /tdd [target]" }, { "name": "tech-debt", @@ -751,7 +761,7 @@ { "name": "channel-economics", "category": "commercial", - "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-DOWN / MAINTAIN / DEFUND / EXIT), a sensitivity-tested channel-mix recommendation, and the diminishing-returns inflection. Not channel structure (that's partnerships-architect \u2014 tiers, joint GTM, revshare). Not RevOps process (that's business-growth/revenue-operations \u2014 lead routing, SDR motion). Not strategic CRO judgment (that's c-level-advisor/cro-advisor \u2014 comp plans, when-to-hire-a-VP-Sales). Not historical close-and-report (that's finance/financial-analysis). This skill answers: direct vs partner profitability, channel profitability, channel mix, 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-DOWN / MAINTAIN / DEFUND / EXIT), a sensitivity-tested channel-mix recommendation, and the diminishing-returns inflection (e.g., 'which channel actually makes money \u2014 direct or partner?')." }, { "name": "commercial-forecaster", @@ -886,7 +896,7 @@ { "name": "engineering-skills", "category": "engineering", - "description": "23 engineering agent skills and plugins for Claude Code, Codex, Gemini CLI, Cursor, OpenClaw, and 6 more tools. Architecture, frontend, backend, QA, DevOps, security, AI/ML, data engineering, Playwright, Stripe, AWS, MS365. 30+ Python tools (stdlib-only)." + "description": "Index of the engineering-team skills bundle for Claude Code, Codex, Gemini CLI, Cursor, OpenClaw, and 6 more tools. Architecture, frontend, backend, QA, DevOps, security, AI/ML, data engineering, Playwright, Stripe, AWS, MS365 (stdlib-only Python tools). Use when browsing or choosing among engineering-team role skills \u2014 load only the one specialist SKILL.md you need, never bulk-load the bundle." }, { "name": "epic-design", @@ -896,7 +906,7 @@ { "name": "extract", "category": "engineering", - "description": "Turn a proven pattern or debugging solution into a standalone reusable skill with SKILL.md, reference docs, and examples." + "description": "Turn a proven pattern or debugging solution into a standalone reusable skill with SKILL.md, reference docs, and examples. Use when the user runs /si:extract or asks to package a recurring solution from memory into a skill." }, { "name": "fix", @@ -916,7 +926,7 @@ { "name": "google-workspace-cli", "category": "engineering", - "description": "Google Workspace administration via the gws CLI. Install, authenticate, and automate Gmail, Drive, Sheets, Calendar, Docs, Chat, and Tasks. Run security audits, execute 43 built-in recipes, and use 10 persona bundles. Use for Google Workspace admin, gws CLI setup, Gmail automation, Drive management, or Calendar scheduling." + "description": "Google Workspace administration via the gws CLI (github.com/googleworkspace/cli). Install, authenticate, and automate Gmail, Drive, Sheets, Calendar, Docs, Chat, and Tasks. Run security audits and use local recipe templates and persona bundles. Use for Google Workspace admin, gws CLI setup, Gmail automation, Drive management, or Calendar scheduling." }, { "name": "incident-commander", @@ -941,7 +951,7 @@ { "name": "promote", "category": "engineering", - "description": "Graduate a proven pattern from auto-memory (MEMORY.md) to CLAUDE.md or .claude/rules/ for permanent enforcement." + "description": "Graduate a proven pattern from auto-memory (MEMORY.md) to CLAUDE.md or .claude/rules/ for permanent enforcement. Use when the user runs /si:promote or asks to make a learned behavior permanent." }, { "name": "pw", @@ -966,7 +976,7 @@ { "name": "review", "category": "engineering", - "description": "Analyze auto-memory for promotion candidates, stale entries, consolidation opportunities, and health metrics." + "description": "Analyze auto-memory for promotion candidates, stale entries, consolidation opportunities, and health metrics. Use when the user runs /si:review or asks what has been learned and what should be promoted or pruned." }, { "name": "security-pen-testing", @@ -1056,7 +1066,7 @@ { "name": "skills-status-2", "category": "engineering", - "description": "Memory health dashboard showing line counts, topic files, capacity, stale entries, and recommendations." + "description": "Memory health dashboard showing line counts, topic files, capacity, stale entries, and recommendations. Use when the user runs /si:status or asks how full or healthy the agent memory is." }, { "name": "snowflake-development", @@ -1091,7 +1101,7 @@ { "name": "agent-designer", "category": "engineering-advanced", - "description": "Use when the user asks to design multi-agent systems, create agent architectures, define agent communication patterns, or build autonomous agent workflows." + "description": "Use when the user asks to design a multi-agent system, pick an orchestration pattern (supervisor/swarm/pipeline), generate tool schemas for agents, or evaluate agent execution logs for cost, latency, and failure bottlenecks. Examples: 'design an agent architecture for research automation', 'generate Anthropic tool schemas from these tool descriptions', 'analyze these agent run logs for bottlenecks'. NOT for Claude Code workflow files (use workflow-builder) or single-agent prompt design (use agent-workflow-designer)." }, { "name": "agent-workflow-designer", @@ -1126,7 +1136,7 @@ { "name": "board", "category": "engineering-advanced", - "description": "Read, write, and browse the AgentHub message board for agent coordination." + "description": "Read, write, and browse the AgentHub message board for agent coordination. Use when the user runs /hub:board or asks to post, read, or inspect coordination messages between competing AgentHub agents." }, { "name": "browser-automation", @@ -1141,7 +1151,7 @@ { "name": "changelog-generator", "category": "engineering-advanced", - "description": "Produce consistent, auditable release notes from Conventional Commits. Separates commit parsing, semantic-bump logic, and changelog rendering for automated releases with editorial control. Use when cutting a release, generating CHANGELOG.md from git history, or automating release notes in CI." + "description": "Produce consistent, auditable release notes from Conventional Commits. Separates commit parsing, semantic-bump logic, and changelog rendering for automated releases with editorial control. Use when cutting a release, generating CHANGELOG.md from git history, computing the next semantic version from commits, automating release notes in CI, or planning a hotfix/rollback. Examples: 'generate the changelog for v1.4.0', 'what version bump do these commits require', 'we need an emergency hotfix process'." }, { "name": "chaos-engineering", @@ -1169,14 +1179,14 @@ "description": "Analyze a codebase and generate onboarding documentation for engineers, tech leads, and contractors. Fast fact-gathering and repeatable onboarding outputs. Use when onboarding a new engineer, writing architecture-overview docs for a new project, or producing tech-lead briefings for unfamiliar repos." }, { - "name": "command-guide", + "name": "collab-proof", "category": "engineering-advanced", - "description": ">" + "description": "Use when you want to understand what Claude contributed vs what you drove in a session. Triggers on: /collab-proof, session retrospective, ai contribution analysis, collaboration evidence, what did claude do." }, { "name": "data-quality-auditor", "category": "engineering-advanced", - "description": "Audit datasets for completeness, consistency, accuracy, and validity. Profile data distributions, detect anomalies and outliers, surface structural issues, and produce an actionable remediation plan." + "description": "Audit datasets for completeness, consistency, accuracy, and validity. Profile data distributions, detect anomalies and outliers, surface structural issues, and produce an actionable remediation plan. Use when the user asks to check data quality, profile a dataset, hunt outliers or missing values, or validate data before analysis or model training." }, { "name": "database-designer", @@ -1196,7 +1206,7 @@ { "name": "dependency-auditor", "category": "engineering-advanced", - "description": "Audit and manage dependencies across multi-language projects. Identifies vulnerabilities, license conflicts, transitive dependency risks, and safe-upgrade paths. Use when auditing third-party packages before release, investigating a CVE, planning a major version bump, or running a license-compliance review." + "description": "Audit and manage dependencies across multi-language projects. Identifies vulnerabilities, license conflicts, transitive dependency risks, and safe-upgrade paths. Use when auditing third-party packages before release, investigating a CVE, planning a major version bump, or running a license-compliance review. Examples: 'audit our npm dependencies', 'do we have GPL contamination', 'plan the upgrade to React 19'." }, { "name": "docker-development", @@ -1206,7 +1216,7 @@ { "name": "engineering-advanced-skills", "category": "engineering-advanced", - "description": "25 advanced engineering agent skills and plugins for Claude Code, Codex, Gemini CLI, Cursor, OpenClaw. Agent design, RAG, MCP servers, CI/CD, database design, observability, security auditing, release management, platform ops." + "description": "Index of 37 advanced engineering agent skills for Claude Code, Codex, Gemini CLI, Cursor, OpenClaw. Use when browsing or choosing among the POWERFUL-tier engineering skills: agent design, RAG, MCP servers, CI/CD, database design, observability, security auditing, changelog/release automation, reliability (SLO/chaos/flags/operators), platform ops." }, { "name": "env-secrets-manager", @@ -1216,7 +1226,7 @@ { "name": "eval", "category": "engineering-advanced", - "description": "Evaluate and rank agent results by metric or LLM judge for an AgentHub session." + "description": "Evaluate and rank agent results by metric or LLM judge for an AgentHub session. Use when the user runs /hub:eval or asks to score, compare, or pick a winner among completed AgentHub agents." }, { "name": "feature-flags-architect", @@ -1256,7 +1266,7 @@ { "name": "init", "category": "engineering-advanced", - "description": "Create a new AgentHub collaboration session with task, agent count, and evaluation criteria." + "description": "Create a new AgentHub collaboration session with task, agent count, and evaluation criteria. Use when the user runs /hub:init or asks to start a multi-agent competition on a task." }, { "name": "interview-system-designer", @@ -1286,7 +1296,7 @@ { "name": "loop", "category": "engineering-advanced", - "description": "Start an autonomous experiment loop with user-selected interval (10min, 1h, daily, weekly, monthly). Uses CronCreate for scheduling." + "description": "Start an autonomous experiment loop with user-selected interval (10min, 1h, daily, weekly, monthly). Uses CronCreate for scheduling. Use when the user runs /ar:loop or asks to run an autoresearch experiment continuously on a schedule." }, { "name": "mcp-server-builder", @@ -1296,7 +1306,7 @@ { "name": "merge", "category": "engineering-advanced", - "description": "Merge the winning agent's branch into base, archive losers, and clean up worktrees." + "description": "Merge the winning agent's branch into base, archive losers, and clean up worktrees. Use when the user runs /hub:merge or asks to land the winning AgentHub result and tidy the session." }, { "name": "migration-architect", @@ -1331,22 +1341,17 @@ { "name": "rag-architect", "category": "engineering-advanced", - "description": "Use when the user asks to design RAG pipelines, optimize retrieval strategies, choose embedding models, implement vector search, or build knowledge retrieval systems." - }, - { - "name": "release-manager", - "category": "engineering-advanced", - "description": "Use when the user asks to plan releases, manage changelogs, coordinate deployments, create release branches, or automate versioning." + "description": "Use when the user asks to design a RAG pipeline, choose a chunking strategy or embedding model, pick a vector database, or evaluate retrieval quality (precision@k, recall@k, NDCG). Examples: 'design a RAG system for our docs', 'what chunk size should I use for this corpus', 'evaluate my retriever against ground truth'. NOT for general LLM cost tuning (use llm-cost-optimizer) or agent loops over retrieval (use agenthub)." }, { "name": "resume", "category": "engineering-advanced", - "description": "Resume a paused experiment. Checkout the experiment branch, read results history, continue iterating." + "description": "Resume a paused experiment. Checkout the experiment branch, read results history, continue iterating. Use when the user runs /ar:resume or asks to pick up a previously started autoresearch experiment." }, { "name": "run", "category": "engineering-advanced", - "description": "Run a single experiment iteration. Edit the target file, evaluate, keep or discard." + "description": "Run a single experiment iteration. Edit the target file, evaluate, keep or discard. Use when the user runs /ar:run or asks for one manual autoresearch iteration." }, { "name": "runbook-generator", @@ -1376,7 +1381,7 @@ { "name": "setup", "category": "engineering-advanced", - "description": "Set up a new autoresearch experiment interactively. Collects domain, target file, eval command, metric, direction, and evaluator." + "description": "Set up a new autoresearch experiment interactively. Collects domain, target file, eval command, metric, direction, and evaluator. Use when the user runs /ar:setup or asks to start optimizing a file with the autoresearch loop." }, { "name": "ship-gate", @@ -1416,7 +1421,7 @@ { "name": "skills-run", "category": "engineering-advanced", - "description": "One-shot lifecycle command that chains init \u2192 baseline \u2192 spawn \u2192 eval \u2192 merge in a single invocation." + "description": "One-shot lifecycle command that chains init \u2192 baseline \u2192 spawn \u2192 eval \u2192 merge in a single invocation. Use when the user runs /hub:run or asks to execute a full AgentHub competition end-to-end." }, { "name": "skills-slo-architect", @@ -1426,7 +1431,7 @@ { "name": "skills-status", "category": "engineering-advanced", - "description": "Show DAG state, agent progress, and branch status for an AgentHub session." + "description": "Show DAG state, agent progress, and branch status for an AgentHub session. Use when the user runs /hub:status or asks how the AgentHub agents are doing." }, { "name": "slo-architect", @@ -1436,7 +1441,7 @@ { "name": "spawn", "category": "engineering-advanced", - "description": "Launch N parallel subagents in isolated git worktrees to compete on the session task." + "description": "Launch N parallel subagents in isolated git worktrees to compete on the session task. Use when the user runs /hub:spawn or asks to start the competing agents for an initialized AgentHub session." }, { "name": "spec-driven-workflow", @@ -1456,7 +1461,7 @@ { "name": "status", "category": "engineering-advanced", - "description": "Show experiment dashboard with results, active loops, and progress." + "description": "Show experiment dashboard with results, active loops, and progress. Use when the user runs /ar:status or asks how an autoresearch experiment is going." }, { "name": "tc-tracker", @@ -1473,6 +1478,11 @@ "category": "engineering-advanced", "description": "Terraform infrastructure-as-code agent skill and plugin for Claude Code, Codex, Gemini CLI, Cursor, OpenClaw. Covers module design patterns, state management strategies, provider configuration, security hardening, policy-as-code with Sentinel/OPA, and CI/CD plan/apply workflows. Use when: user wants to design Terraform modules, manage state backends, review Terraform security, implement multi-region deployments, or follow IaC best practices." }, + { + "name": "universal-scraping-architect", + "category": "engineering-advanced", + "description": "Use for web scraping, crawling, document extraction, API parsing, or building validation-heavy data pipelines using Firecrawl or local Python scripts." + }, { "name": "workflow-builder", "category": "engineering-advanced", @@ -1491,7 +1501,7 @@ { "name": "finance-skills", "category": "finance", - "description": "Financial analyst agent skill and plugin for Claude Code, Codex, Gemini CLI, Cursor, OpenClaw. Ratio analysis, DCF valuation, budget variance, rolling forecasts. 4 Python tools (stdlib-only)." + "description": "Router/index for the 2 finance skills bundled in this plugin: financial-analyst (ratio analysis, DCF valuation, budget variance, rolling forecasts) and saas-metrics-coach (ARR/MRR, churn, CAC/LTV, NRR, quick ratio). Use when a finance request doesn't obviously match one skill and you need to pick the right one (e.g., 'analyze these financials', 'how healthy are my SaaS metrics')." }, { "name": "financial-analyst", @@ -1503,6 +1513,31 @@ "category": "finance", "description": "SaaS financial health advisor. Use when a user shares revenue or customer numbers, or mentions ARR, MRR, churn, LTV, CAC, NRR, or asks how their SaaS business is doing." }, + { + "name": "design-system", + "category": "markdown-html", + "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 the design system\", \"re-onboard\"), and is checked by every converter via config_loader.py before rendering. Refuses to save if body-text contrast fails AA 4.5:1 or the output dir isn't writable. Precedence: project (./.markdown-html/) > global (~/.config/markdown-html/) > built-in defaults; MARKDOWN_HTML_NO_CONFIG=1 bypasses." + }, + { + "name": "markdown-html-orchestrator", + "category": "markdown-html", + "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 the user has run the design-system onboarding once. Refuses if input is under 100 lines (per Shihipar \u2014 markdown still wins below the threshold) or design-system isn't onboarded. Distinct from Anthropic's official Playground plugin (which is interactive prompt-tuning controls with sliders/knobs/prompt-copy-back) and from marketing/landing/ (which is a landing-page generator)." + }, + { + "name": "md-document", + "category": "markdown-html", + "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 build step. Use after orchestrator routing or after design-system onboarding is confirmed." + }, + { + "name": "md-review", + "category": "markdown-html", + "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 encode severity in color only (every badge ships color + icon + aria-label per WCAG 1.4.1). Use after orchestrator routing." + }, + { + "name": "md-slides", + "category": "markdown-html", + "description": "Converts a markdown deck (slides separated by `" + }, { "name": "ab-test-setup", "category": "marketing", @@ -1518,11 +1553,6 @@ "category": "marketing", "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 for AI search', 'E-E-A-T audit'. Output is a markdown audit report (default) or JSON for pipeline integration. Stdlib-only Python tools." }, - { - "name": "ai-seo", - "category": "marketing", - "description": "Optimize content to get cited by AI search engines \u2014 ChatGPT, Perplexity, Google AI Overviews, Claude, Gemini, Copilot. Use when you want your content to appear in AI-generated answers, not just ranked in blue links. Triggers: 'optimize for AI search', 'get cited by ChatGPT', 'AI Overviews', 'Perplexity citations', 'AI SEO', 'generative search', 'LLM visibility', 'GEO' (generative engine optimization). NOT for traditional SEO ranking (use seo-audit). NOT for content creation (use content-production)." - }, { "name": "analytics-tracking", "category": "marketing", @@ -1616,7 +1646,7 @@ { "name": "marketing-demand-acquisition", "category": "marketing", - "description": "Creates demand generation campaigns, optimizes paid ad spend across LinkedIn, Google, and Meta, develops SEO strategies, and structures partnership programs for Series A+ startups scaling internationally. Use when planning marketing strategy, growth marketing, advertising campaigns, PPC optimization, lead generation, pipeline generation, or startup 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 for hybrid PLG/Sales-Led motions in EU/US/Canada markets." + "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) \u2014 adapt benchmarks for other stages and motions rather than skipping the skill." }, { "name": "marketing-ideas", @@ -1636,7 +1666,7 @@ { "name": "marketing-skills", "category": "marketing", - "description": "42 marketing agent skills and plugins for Claude Code, Codex, Gemini CLI, Cursor, OpenClaw, and 6 more coding agents. 7 pods: content, SEO, CRO, channels, growth, intelligence, sales. Foundation context + orchestration router. 27 Python tools (stdlib-only)." + "description": "Directory and router for the marketing skills library. Use when you need to find the right marketing skill for a task, see what marketing capabilities exist, or get oriented in this plugin. 44 specialist skills across 8 pods (content, SEO + AEO, CRO, channels, growth, intelligence, sales enablement, ops), 59 stdlib Python tools. Routes to one skill \u2014 it does not execute marketing work itself." }, { "name": "marketing-strategy-pmm", @@ -1681,7 +1711,7 @@ { "name": "prompt-engineer-toolkit", "category": "marketing", - "description": "Analyzes and rewrites prompts for better AI output, creates reusable prompt templates for marketing use cases (ad copy, email campaigns, social media), and structures end-to-end AI content workflows. Use when the user wants to improve prompts for AI-assisted marketing, build prompt templates, or optimize AI content workflows. Also use when the user mentions 'prompt engineering,' 'improve my prompts,' 'AI writing quality,' 'prompt templates,' or 'AI content workflow.'" + "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,' 'AI content workflow,' or 'AI governance for marketing.'" }, { "name": "referral-program", @@ -1716,7 +1746,7 @@ { "name": "social-media-analyzer", "category": "marketing", - "description": "Social media campaign analysis and performance tracking. Calculates engagement rates, ROI, and benchmarks across platforms. Use for analyzing social media performance, calculating engagement rate, measuring campaign ROI, comparing platform metrics, or benchmarking against industry standards." + "description": "Social media campaign analysis and performance tracking. Calculates engagement rates, ROI, and benchmarks across platforms. Use when analyzing social media performance, calculating engagement rate, measuring campaign ROI, comparing platform metrics, or benchmarking against industry standards. Also use when the user mentions \"social media audit,\" \"engagement rate,\" or \"which platform performs best.\"" }, { "name": "social-media-manager", @@ -1728,11 +1758,21 @@ "category": "marketing", "description": "Use when planning video content strategy, writing video scripts, optimizing YouTube channels, building short-form video pipelines (Reels, TikTok, Shorts), or repurposing long-form content into video. Triggers: 'start a YouTube channel', 'video content strategy', 'write a video script', 'repurpose into video', 'YouTube SEO', 'short-form video'. NOT for written blog content (use content-production). NOT for social captions without video (use social-media-manager)." }, + { + "name": "webinar-marketing", + "category": "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, show-up, live engagement, live-to-close, and post-event nurture. Distinct from launch-strategy (full product launches) and email-sequence (lifecycle nurture) \u2014 this is the end-to-end webinar/event motion. NOT for in-person field events logistics, and NOT for generic lifecycle email (use email-sequence)." + }, { "name": "x-twitter-growth", "category": "marketing", "description": "X/Twitter growth engine for building audience, crafting viral content, and analyzing engagement. Use when the user wants to grow on X/Twitter, write tweets or threads, analyze their X profile, research competitors on X, plan a posting strategy, or optimize engagement. Complements social-content (generic multi-platform) with X-specific depth: algorithm mechanics, thread engineering, reply strategy, profile optimization, and competitive intelligence via web search." }, + { + "name": "youtube-full", + "category": "marketing", + "description": "Use when the user needs YouTube transcripts, video search, channel browsing, playlist extraction, or content monitoring. Trigger phrases: 'get the transcript for', 'search YouTube for', 'what are the latest videos on', 'list this playlist', 'monitor this channel', or any request involving a YouTube URL, video ID, or @handle. Do NOT use for downloading video or audio files, YouTube engagement data (likes, comments), or private/age-restricted videos." + }, { "name": "landing", "category": "marketing-top-level", @@ -1741,17 +1781,17 @@ { "name": "agile-product-owner", "category": "product", - "description": "Agile product ownership for backlog management and sprint execution. Covers user story writing, acceptance criteria, sprint planning, and velocity tracking. Use for writing user stories, creating acceptance criteria, planning sprints, estimating story points, breaking down epics, or prioritizing backlog." + "description": "Agile product ownership for backlog management and sprint execution. Covers user story writing, acceptance criteria, sprint planning, and velocity tracking. Use when writing user stories, creating acceptance criteria, planning sprints, estimating story points, breaking down epics, or prioritizing the backlog." }, { "name": "apple-hig-expert", "category": "product", - "description": "Expert guidance on Apple Human Interface Guidelines (HIG). Covers iOS, macOS, and visionOS with 2026 Liquid Glass aesthetics and accessibility-first design." + "description": "Audits and designs iOS/macOS/watchOS/visionOS interfaces against the Apple Human Interface Guidelines, including the Liquid Glass design language (announced WWDC25, shipped with iOS 26/macOS Tahoe, Sept 2025). Use when reviewing an Apple-platform mockup or app for HIG compliance, checking contrast or tap-target sizes, or designing native-feeling Apple UI (e.g., 'audit my iOS app against the HIG', 'is this text readable on Liquid Glass?')." }, { "name": "code-to-prd", "category": "product", - "description": "|" + "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 logic, analyze page fields and interactions, create a functional inventory, write requirements from an existing codebase, document API endpoints, or analyze backend routes." }, { "name": "competitive-teardown", @@ -1781,12 +1821,12 @@ { "name": "product-manager-toolkit", "category": "product", - "description": "Comprehensive toolkit for product managers including RICE prioritization, customer interview analysis, PRD templates, discovery frameworks, and go-to-market strategies. Use for feature prioritization, user research synthesis, requirement documentation, and product strategy development." + "description": "Comprehensive toolkit for product managers including RICE prioritization, customer interview analysis, PRD templates, discovery frameworks, and go-to-market strategies. Use when prioritizing features, synthesizing user research, writing requirement documentation, or developing product strategy." }, { "name": "product-skills", "category": "product", - "description": "10 product agent skills and plugins for Claude Code, Codex, Gemini CLI, Cursor, OpenClaw. PM toolkit (RICE), agile PO, product strategist (OKR), UX researcher, UI design system, competitive teardown, landing page generator, SaaS scaffolder, research summarizer. Python tools (stdlib-only)." + "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')." }, { "name": "product-strategist", @@ -1816,12 +1856,12 @@ { "name": "ui-design-system", "category": "product", - "description": "UI design system toolkit for Senior UI Designer including design token generation, component documentation, responsive design calculations, and developer handoff tools. Use for creating design systems, maintaining visual consistency, and facilitating design-dev collaboration." + "description": "UI design system toolkit for Senior UI Designer including design token generation, component documentation, responsive design calculations, and developer handoff tools. Use when creating design systems, generating design tokens, maintaining visual consistency, or facilitating design-dev collaboration and developer handoff." }, { "name": "ux-researcher-designer", "category": "product", - "description": "UX research and design toolkit for Senior UX Designer/Researcher including data-driven persona generation, journey mapping, usability testing frameworks, and research synthesis. Use for user research, persona creation, journey mapping, and design validation." + "description": "UX research and design toolkit for Senior UX Designer/Researcher including data-driven persona generation, journey mapping, usability testing frameworks, and research synthesis. Use when conducting user research, creating personas, mapping user journeys, planning usability tests, or validating designs." }, { "name": "andreessen", @@ -1846,7 +1886,7 @@ { "name": "inbox-triage", "category": "productivity", - "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 demand. Triggers: 'triage my inbox', 'inbox triage', 'check my email', 'run email triage', 'process my inbox', 'what's new in my email', 'handle my email', 'email triage', or any variation where the user wants their inbox processed. Requires the inbox-setup skill to have been run first." + "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 demand. Use when the user wants their inbox processed, in any variation (e.g., 'triage my inbox', 'inbox triage', 'check my email', 'run email triage', 'process my inbox', 'what's new in my email', 'handle my email', 'email triage'). Requires the inbox-setup skill to have been run first." }, { "name": "reflect", @@ -1871,7 +1911,7 @@ { "name": "jira-expert", "category": "project-management", - "description": "Atlassian Jira expert for creating and managing projects, planning, product discovery, JQL queries, workflows, custom fields, automation, reporting, and all Jira features. Use for Jira project setup, configuration, advanced search, dashboard creation, workflow design, and technical Jira operations." + "description": "Atlassian Jira expert for creating and managing projects, planning, product discovery, JQL queries, workflows, custom fields, automation, reporting, and all Jira features. Use when setting up or configuring Jira projects, writing JQL and advanced searches, creating dashboards, designing workflows, or performing technical Jira operations." }, { "name": "meeting-analyzer", @@ -1881,7 +1921,7 @@ { "name": "pm-skills", "category": "project-management", - "description": "6 project management agent skills and plugins for Claude Code, Codex, Gemini CLI, Cursor, OpenClaw. Senior PM, scrum master, Jira expert (JQL), Confluence expert, Atlassian admin, template creator. MCP integration for live Jira/Confluence automation." + "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." }, { "name": "scrum-master", @@ -1901,7 +1941,7 @@ { "name": "capa-officer", "category": "ra-qm", - "description": "CAPA system management for medical device QMS. Covers root cause analysis, corrective action planning, effectiveness verification, and CAPA metrics. Use for CAPA investigations, 5-Why analysis, fishbone diagrams, root cause determination, corrective action tracking, effectiveness verification, or CAPA program optimization." + "description": "CAPA system management for medical device QMS. Covers root cause analysis, corrective action planning, effectiveness verification, and CAPA metrics. Use when running CAPA investigations, 5-Why analysis, fishbone diagrams, root cause determination, corrective action tracking, effectiveness verification, or CAPA program optimization." }, { "name": "eu-ai-act-specialist", @@ -1911,17 +1951,17 @@ { "name": "fda-consultant-specialist", "category": "ra-qm", - "description": "FDA regulatory consultant for medical device companies. Provides 510(k)/PMA/De Novo pathway guidance, QSR (21 CFR 820) compliance, HIPAA assessments, and device cybersecurity. Use when user mentions FDA submission, 510(k), PMA, De Novo, QSR, premarket, predicate device, substantial equivalence, HIPAA medical device, or FDA cybersecurity." + "description": "FDA regulatory consultant for medical device companies. Provides 510(k)/PMA/De Novo pathway guidance, QMSR (21 CFR 820, which incorporates ISO 13485:2016 by reference since 2026-02-02; formerly QSR) compliance, HIPAA assessments, and device cybersecurity. Use when user mentions FDA submission, 510(k), PMA, De Novo, QMSR, QSR, ISO 13485 for FDA, premarket, predicate device, substantial equivalence, HIPAA medical device, or FDA cybersecurity." }, { "name": "gdpr-dsgvo-expert", "category": "ra-qm", - "description": "GDPR and German DSGVO compliance automation. Scans codebases for privacy risks, generates DPIA documentation, tracks data subject rights requests. Use for GDPR compliance assessments, privacy audits, data protection planning, DPIA generation, and data subject rights management." + "description": "GDPR and German DSGVO compliance automation. Scans codebases for privacy risks, generates DPIA documentation, tracks data subject rights requests with Art. 12(3) one-month deadlines. Use when running GDPR compliance assessments, privacy audits, data protection planning, DPIA generation, or data subject rights (DSAR) management (e.g., 'check this service for GDPR risks', 'track an access request deadline'). Final compliance determinations route to the DPO or legal counsel." }, { "name": "information-security-manager-iso27001", "category": "ra-qm", - "description": "ISO 27001 ISMS implementation and cybersecurity governance for HealthTech and MedTech companies. Use for ISMS design, security risk assessment, control implementation, ISO 27001 certification, security audits, incident response, and compliance verification. Covers ISO 27001, ISO 27002, healthcare security, and medical device cybersecurity." + "description": "ISO 27001 ISMS implementation and cybersecurity governance for HealthTech and MedTech companies. Use when designing an ISMS, running security risk assessments, implementing controls, pursuing ISO 27001 certification, preparing security audits, responding to security incidents, or verifying compliance. Covers ISO 27001, ISO 27002, healthcare security, and medical device cybersecurity." }, { "name": "isms-audit-expert", @@ -1936,22 +1976,22 @@ { "name": "mdr-745-specialist", "category": "ra-qm", - "description": "EU MDR 2017/745 compliance specialist for medical device classification, technical documentation, clinical evidence, and post-market surveillance. Covers Annex VIII classification rules, Annex II/III technical files, Annex XIV clinical evaluation, and EUDAMED integration." + "description": "EU MDR 2017/745 compliance specialist for medical device classification, technical documentation, clinical evidence, and post-market surveillance. Covers Annex VIII classification rules, Annex II/III technical files, Annex XIV clinical evaluation, Art. 86 PSUR schedules, and EUDAMED integration. Use when classifying a medical device under MDR, building or gap-checking a technical file, planning clinical evaluation or PMS/PSUR cadence, or preparing for notified body review (e.g., 'what class is my device under MDR', 'review my PSUR schedule')." }, { "name": "qms-audit-expert", "category": "ra-qm", - "description": "ISO 13485 internal audit expertise for medical device QMS. Covers audit planning, execution, nonconformity classification, and CAPA verification. Use for internal audit planning, audit execution, finding classification, external audit preparation, or audit program management." + "description": "ISO 13485 internal audit expertise for medical device QMS. Covers audit planning, execution, nonconformity classification, and CAPA verification. Use when planning internal audits, executing audits, classifying findings, preparing for external audits, or managing an audit program." }, { "name": "quality-documentation-manager", "category": "ra-qm", - "description": "Document control system management for medical device QMS. Covers document numbering, version control, change management, and 21 CFR Part 11 compliance. Use for document control procedures, change control workflow, document numbering, version management, electronic signature compliance, or regulatory documentation review." + "description": "Document control system management for medical device QMS. Covers document numbering, version control, change management, and 21 CFR Part 11 compliance. Use when working on document control procedures, change control workflows, document numbering, version management, electronic signature compliance, or regulatory documentation review." }, { "name": "quality-manager-qmr", "category": "ra-qm", - "description": "Senior Quality Manager Responsible Person (QMR) for HealthTech and MedTech companies. Provides quality system governance, management review leadership, regulatory compliance oversight, and quality performance monitoring per ISO 13485 Clause 5.5.2." + "description": "Senior Quality Manager Responsible Person (QMR) for HealthTech and MedTech companies. Provides quality system governance, management review leadership, regulatory compliance oversight, and quality performance monitoring per ISO 13485 Clause 5.5.2. Use when leading management reviews, setting quality policy and objectives, monitoring quality KPIs and cost of quality, or exercising QMR governance and regulatory oversight responsibilities." }, { "name": "quality-manager-qms-iso13485", @@ -1961,7 +2001,7 @@ { "name": "ra-qm-skills", "category": "ra-qm", - "description": "12 regulatory & QM agent skills and plugins for Claude Code, Codex, Gemini CLI, Cursor, OpenClaw. ISO 13485 QMS, MDR 2017/745, FDA 510(k)/PMA, ISO 27001 ISMS, GDPR/DSGVO, risk management (ISO 14971), CAPA, document control, auditing. Python tools (stdlib-only)." + "description": "Router/index for the 15 regulatory & quality-management skills bundled in this plugin (ISO 13485 QMS, EU MDR 2017/745, FDA submissions under QMSR, ISO 14971 risk, CAPA, document control, ISO 27001/ISMS, ISO 42001 AIMS, EU AI Act, GDPR/DSGVO, SOC 2, auditing). Use when a compliance request doesn't obviously match one skill and you need to pick the right one (e.g., 'prepare us for an ISO 13485 audit', 'is my AI system high-risk under the AI Act')." }, { "name": "regulatory-affairs-head", @@ -1991,42 +2031,42 @@ { "name": "dossier", "category": "research", - "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 signals, reputation signals, red flags, 3-5 conversation hooks tied to specific findings, and source-provenance audit log. Uses WebSearch + WebFetch + free APIs (SEC EDGAR, GitHub, ProPublica Nonprofit Explorer) as workhorses; optional BYOK MCPs (LinkedIn, Crunchbase, Apollo, Pitchbook, SimilarWeb) enhance coverage. Triggers: 'research [company]', 'dossier on [person/company]', 'background check on [entity]', 'prep me for a meeting with [person/company]', 'due diligence on [company]', 'what should I know about [entity]', 'research [person] before I [meet/hire/invest]', 'competitor research on [company]', 'investor diligence [company]', 'interview prep for [company]'. Honors sensitivity exclusions for journalism + personal-vetting contexts." + "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 + free APIs (SEC EDGAR, GitHub, ProPublica) as workhorses; optional BYOK MCPs enhance coverage. Use when the user asks for background research, diligence, or meeting prep on a specific entity (e.g., 'prep me for a meeting with [person/company]', 'due diligence on [company]'). Honors sensitivity exclusions for journalism + personal-vetting contexts." }, { "name": "grants", "category": "research", - "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 recommendation. Triggers: 'grants for [topic]', 'find grants for my research idea', 'what grants match my research', 'help me find NIH funding', 'grant opportunities for my research', or any grant-related request. NIH-only scope \u2014 non-NIH funders (PCORI, DOD CDMRP, VA, foundations) are out of scope and flagged at intake." + "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 recommendation. Use when the user asks about research funding or makes any grant-related request (e.g., 'grants for [topic]', 'find grants for my research idea', 'what grants match my research', 'help me find NIH funding', 'grant opportunities for my research'). NIH-only scope \u2014 non-NIH funders (PCORI, DOD CDMRP, VA, foundations) are out of scope and flagged at intake." }, { "name": "litreview", "category": "research", - "description": "Academic literature orientation skill that searches papers via Consensus, builds a strategic search plan using PICO (default) or SPIDER / Decomposition / hybrid as fallbacks, and synthesizes findings into a professionally formatted Word document (.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. Configurable depth (5/10/20 queries) controls coverage vs. speed. Output is a 'launching pad' \u2014 not a finished review, but an orientation guide that lets a researcher dive in confidently. Triggers: 'litreview on [topic]', 'literature review on [topic]', 'I'm starting a literature review on X', 'I'm writing a paper on X', 'help me research X', 'I'm doing research on X', 'can you help me research X'. Do NOT trigger for single one-off paper searches where the user just wants a quick list \u2014 that's a plain Consensus search." + "description": "Academic literature orientation skill that searches papers via Consensus, 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. Configurable depth (5/10/20 queries) controls coverage vs. speed. Output is a 'launching pad' \u2014 an orientation guide that lets a researcher dive in confidently, not a finished review. Use when the user starts literature-oriented research (e.g., 'litreview on [topic]', 'literature review on [topic]', 'I'm starting a literature review on X', 'I'm writing a paper on X', 'help me research X', 'I'm doing research on X', 'can you help me research X'). Do NOT use for single one-off paper searches wanting a quick list \u2014 that's a plain Consensus search." }, { "name": "notebooklm", "category": "research", - "description": "Browser automation skill for controlling Google's NotebookLM. Handles reading and querying notebooks, adding sources (URLs, text, files, YouTube links, synthesized content), generating Studio outputs (Audio Overview, infographics, slide decks, study guides, briefing docs, mind maps, timelines, FAQs), and creating new notebooks. Triggers on any phrase involving NotebookLM \u2014 'open NotebookLM', 'check my [name] notebook', 'pull info from NotebookLM', 'ask my notebook about X', 'add [source] to NotebookLM', 'create an infographic in NotebookLM', 'use NotebookLM Studio', 'generate a slide deck from my notebook', or any variation where the goal involves NotebookLM. Requires browser automation environment \u2014 fails gracefully when unavailable." + "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 Studio panel; the UI evolves fast), and creating new notebooks. Requires browser automation environment \u2014 fails gracefully when unavailable." }, { "name": "patent", "category": "research", - "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 log. Triggers: 'prior art search for [invention]', 'patent search on [topic]', 'freedom to operate analysis', 'FTO for [product]', 'patent landscape for [field]', 'is [invention] novel', 'patents on [topic]', 'competitive patent analysis', 'prior art for litigation', 'patent diligence on [company]'. Produces search signal, not legal advice \u2014 always recommends consulting a patent attorney before filing or licensing decisions. Trademark, copyright, and trade-secret questions are out of scope." + "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 log. Use when the user asks for patent searching or analysis (e.g., 'prior art search for [invention]', 'freedom to operate analysis for [product]'). Produces search signal, not legal advice \u2014 always recommends consulting a patent attorney before filing or licensing decisions. Trademark, copyright, and trade-secret questions are out of scope." }, { "name": "pulse", "category": "research", - "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. Triggers: 'pulse on [topic]', 'what's happening with [topic]', 'what are people saying about [topic]', 'current conversation about [topic]', 'take the pulse of [topic]', 'trending: [topic]', 'find me info on [topic]', or any variation requesting multi-source recency intelligence on a topic. Also use for competitor research, trend discovery, tool comparisons, and audience sentiment analysis." + "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 saying about [topic]', 'current conversation about [topic]', 'take the pulse of [topic]', 'trending: [topic]', 'find me info on [topic]'), and for competitor research, trend discovery, tool comparisons, and audience sentiment analysis." }, { "name": "research-bundle", "category": "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. Triggers \u2014 \"research [topic]\", \"look into [topic]\", \"what do we know about [topic]\", \"investigate [topic]\", \"find me information on [topic]\", \"do some research on [topic]\", \"I need to understand [topic]\", or any research request that doesn't obviously match a more-specific specialist skill. Output is a markdown briefing (default) or .docx document (on request) with full citations and an audit log." + "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-specific specialist skill (e.g., \"research [topic]\", \"look into [topic]\", \"what do we know about [topic]\", \"investigate [topic]\", \"find me information on [topic]\", \"do some research on [topic]\", \"I need to understand [topic]\"). Output is a markdown briefing (default) or .docx document (on request) with full citations and an audit log." }, { "name": "syllabus", "category": "research", - "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 questions tied to course learning goals. Triggers whenever a user uploads a syllabus, course outline, or curriculum document and wants supplementary readings. Also triggers on: 'syllabus reading list', 'find papers for my course', 'create a reading list from this syllabus', 'recent research for my class', 'supplementary readings', 'find journal articles for these topics', 'what recent papers cover this material', 'any new research on these course topics', 'update my syllabus with recent papers'. Even casual mentions when a syllabus is attached should trigger this skill." + "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 questions tied to course learning goals. Use when the user uploads a syllabus, course outline, or curriculum document and wants supplementary readings (e.g., 'create a reading list from this syllabus', 'find recent papers for my course') \u2014 even casual mentions with a syllabus attached should trigger this skill." }, { "name": "clinical-research", @@ -2056,7 +2096,7 @@ ], "categories": { "agent": { - "count": 33, + "count": 34, "description": "Agent resources" }, "business-growth": { @@ -2072,7 +2112,7 @@ "description": "C-level resources" }, "command": { - "count": 38, + "count": 39, "description": "Command resources" }, "commercial": { @@ -2095,8 +2135,12 @@ "count": 4, "description": "Finance resources" }, + "markdown-html": { + "count": 5, + "description": "Markdown-html resources" + }, "marketing": { - "count": 46, + "count": 47, "description": "Marketing resources" }, "marketing-top-level": { diff --git a/.gemini/skills/ai-seo/SKILL.md b/.gemini/skills/ai-seo/SKILL.md deleted file mode 120000 index 7f46ba6e..00000000 --- a/.gemini/skills/ai-seo/SKILL.md +++ /dev/null @@ -1 +0,0 @@ -../../../marketing-skill/skills/ai-seo/SKILL.md \ No newline at end of file diff --git a/.gemini/skills/collab-proof/SKILL.md b/.gemini/skills/collab-proof/SKILL.md new file mode 120000 index 00000000..38979678 --- /dev/null +++ b/.gemini/skills/collab-proof/SKILL.md @@ -0,0 +1 @@ +../../../engineering/collab-proof/skills/collab-proof/SKILL.md \ No newline at end of file diff --git a/.gemini/skills/command-guide/SKILL.md b/.gemini/skills/command-guide/SKILL.md deleted file mode 120000 index fd5f5ab6..00000000 --- a/.gemini/skills/command-guide/SKILL.md +++ /dev/null @@ -1 +0,0 @@ -../../../engineering/skills/command-guide/SKILL.md \ No newline at end of file diff --git a/.gemini/skills/cs-webinar-marketer/SKILL.md b/.gemini/skills/cs-webinar-marketer/SKILL.md new file mode 120000 index 00000000..40c21a6b --- /dev/null +++ b/.gemini/skills/cs-webinar-marketer/SKILL.md @@ -0,0 +1 @@ +../../../agents/marketing/cs-webinar-marketer.md \ No newline at end of file diff --git a/.gemini/skills/cs-webinar/SKILL.md b/.gemini/skills/cs-webinar/SKILL.md new file mode 120000 index 00000000..39f0b903 --- /dev/null +++ b/.gemini/skills/cs-webinar/SKILL.md @@ -0,0 +1 @@ +../../../commands/cs-webinar.md \ No newline at end of file diff --git a/.gemini/skills/design-system/SKILL.md b/.gemini/skills/design-system/SKILL.md new file mode 120000 index 00000000..29dd3d6d --- /dev/null +++ b/.gemini/skills/design-system/SKILL.md @@ -0,0 +1 @@ +../../../markdown-html/skills/design-system/SKILL.md \ No newline at end of file diff --git a/.gemini/skills/markdown-html-orchestrator/SKILL.md b/.gemini/skills/markdown-html-orchestrator/SKILL.md new file mode 120000 index 00000000..03a354fb --- /dev/null +++ b/.gemini/skills/markdown-html-orchestrator/SKILL.md @@ -0,0 +1 @@ +../../../markdown-html/skills/markdown-html-orchestrator/SKILL.md \ No newline at end of file diff --git a/.gemini/skills/md-document/SKILL.md b/.gemini/skills/md-document/SKILL.md new file mode 120000 index 00000000..3b887c05 --- /dev/null +++ b/.gemini/skills/md-document/SKILL.md @@ -0,0 +1 @@ +../../../markdown-html/skills/md-document/SKILL.md \ No newline at end of file diff --git a/.gemini/skills/md-review/SKILL.md b/.gemini/skills/md-review/SKILL.md new file mode 120000 index 00000000..173635d7 --- /dev/null +++ b/.gemini/skills/md-review/SKILL.md @@ -0,0 +1 @@ +../../../markdown-html/skills/md-review/SKILL.md \ No newline at end of file diff --git a/.gemini/skills/md-slides/SKILL.md b/.gemini/skills/md-slides/SKILL.md new file mode 120000 index 00000000..4f19b9b9 --- /dev/null +++ b/.gemini/skills/md-slides/SKILL.md @@ -0,0 +1 @@ +../../../markdown-html/skills/md-slides/SKILL.md \ No newline at end of file diff --git a/.gemini/skills/release-manager/SKILL.md b/.gemini/skills/release-manager/SKILL.md deleted file mode 120000 index b696d38f..00000000 --- a/.gemini/skills/release-manager/SKILL.md +++ /dev/null @@ -1 +0,0 @@ -../../../engineering/skills/release-manager/SKILL.md \ No newline at end of file diff --git a/.gemini/skills/universal-scraping-architect/SKILL.md b/.gemini/skills/universal-scraping-architect/SKILL.md new file mode 120000 index 00000000..98645361 --- /dev/null +++ b/.gemini/skills/universal-scraping-architect/SKILL.md @@ -0,0 +1 @@ +../../../engineering/universal-scraping-architect/skills/universal-scraping-architect/SKILL.md \ No newline at end of file diff --git a/.gemini/skills/webinar-marketing/SKILL.md b/.gemini/skills/webinar-marketing/SKILL.md new file mode 120000 index 00000000..3851a453 --- /dev/null +++ b/.gemini/skills/webinar-marketing/SKILL.md @@ -0,0 +1 @@ +../../../marketing-skill/skills/webinar-marketing/SKILL.md \ No newline at end of file diff --git a/.gemini/skills/youtube-full/SKILL.md b/.gemini/skills/youtube-full/SKILL.md new file mode 120000 index 00000000..1121a760 --- /dev/null +++ b/.gemini/skills/youtube-full/SKILL.md @@ -0,0 +1 @@ +../../../marketing-skill/skills/youtube-full/SKILL.md \ No newline at end of file diff --git a/.github/workflows/ci-quality-gate.yml b/.github/workflows/ci-quality-gate.yml index 89b9c452..8e0b9fcd 100644 --- a/.github/workflows/ci-quality-gate.yml +++ b/.github/workflows/ci-quality-gate.yml @@ -77,15 +77,48 @@ jobs: - name: Python syntax check (blocking) run: | + # Covers every top-level skill domain + scripts/. When adding a new + # domain folder, add it here (audit gate G9: this list previously + # skipped 8 post-v2.7 domains). python -m compileall \ marketing-skill product-team c-level-advisor \ engineering-team ra-qm-team engineering \ - business-growth finance project-management scripts + business-growth finance project-management \ + productivity marketing research \ + business-operations commercial research-ops \ + compliance-os markdown-html scripts - name: Validate plugin.json manifests (blocking — guards #539 + #686) run: | python scripts/check_plugin_json.py --all + # ---- Audit guardrails (newgen-2026-06 gates) ---------------------- + # BLOCKING since PR-2 (flipped ahead of the 2026-07-01 SLA — every + # advisory run was green through PR #835). If a gate misfires on a + # legitimate edge case, extend its in-repo allowlist + # (scripts/check_paths_allowlist.txt, scripts/smoke_exceptions.txt) + # rather than re-adding continue-on-error. + - name: Path-existence linter (gate G1 — blocking) + run: | + python3 scripts/check_paths.py --all + + - name: Dual-publish drift guard (gate G4 — blocking) + run: | + python3 scripts/check_dual_publish.py + + - name: Script --help smoke gate (gate G8 — blocking) + run: | + python3 scripts/smoke_scripts.py + + - name: JSON-output sample gate (gate G9 — advisory) + continue-on-error: true + run: | + python3 scripts/smoke_json_output.py + + - name: Counter derivation check (gate G3 — blocking) + run: | + python3 scripts/derive_counters.py --check + - name: Safety dependency audit (requirements*.txt) run: | set -e @@ -96,7 +129,9 @@ jobs: fi for f in $files; do echo "Auditing $f" - safety check --full-report --file "$f" || true + if ! safety check --full-report --file "$f"; then + echo "::warning file=$f::safety found vulnerabilities in $f (advisory)" + fi done - name: Markdown link spot-check diff --git a/.github/workflows/enforce-pr-target.yml b/.github/workflows/enforce-pr-target.yml index e67cced4..78151aad 100644 --- a/.github/workflows/enforce-pr-target.yml +++ b/.github/workflows/enforce-pr-target.yml @@ -3,7 +3,7 @@ name: Enforce PR Target Branch on: pull_request_target: - types: [opened] + types: [opened, edited, ready_for_review] branches: [main] permissions: @@ -13,45 +13,63 @@ jobs: check-target: runs-on: ubuntu-latest steps: - - name: Block PRs targeting main from non-maintainers + - name: Block PRs targeting main (only dev -> main promotion allowed) uses: actions/github-script@v7 with: script: | const pr = context.payload.pull_request; const author = pr.user.login; + const headRef = pr.head.ref; + const sameRepo = pr.head.repo.full_name === context.payload.repository.full_name; - // Maintainers who can PR to main directly - const maintainers = ['alirezarezvani']; - - if (maintainers.includes(author)) { - console.log(`✅ ${author} is a maintainer — PR to main allowed.`); + // HARD RULE (CLAUDE.md > Git Workflow): main only receives + // dev -> main promotion PRs. Branch-based, not author-based — + // maintainers are not exempt. + if (sameRepo && headRef === 'dev') { + console.log(`✅ dev -> main promotion PR — allowed.`); return; } - const message = `👋 Hi @${author}, thanks for your contribution! + // Maintainers: fail the check and explain, but don't auto-close + // (avoids nuking intentional work; retarget instead). + const maintainers = ['alirezarezvani']; + const isMaintainer = maintainers.includes(author); - All community PRs should target the \`dev\` branch, not \`main\`. The \`main\` branch is reserved for releases. + const nextStep = isMaintainer + ? 'This check will re-run automatically once the base branch is changed.' + : 'This PR has been closed automatically; reopen it after retargeting, ' + + 'or open a new PR against `dev`.'; - **How to fix:** - 1. Close this PR - 2. Reopen it targeting \`dev\` instead of \`main\` - - Or I can do it for you — just click "Edit" at the top right of this PR and change the base branch to \`dev\`. - - See our [Contributing Guide](https://github.com/alirezarezvani/claude-skills/blob/dev/CONTRIBUTING.md) for details.`; + const message = [ + `👋 Hi @${author}, thanks for your contribution!`, + '', + 'All PRs must target the `dev` branch, not `main`. The `main` branch', + 'only receives `dev -> main` promotion PRs (see CLAUDE.md > Git Workflow).', + '', + '**How to fix:** click "Edit" at the top right of this PR and change', + 'the base branch to `dev`.', + '', + nextStep, + '', + 'See our [Contributing Guide]' + + '(https://github.com/alirezarezvani/claude-skills/blob/dev/CONTRIBUTING.md)' + + ' for details.', + ].join('\n'); await github.rest.issues.createComment({ owner: context.repo.owner, repo: context.repo.repo, issue_number: pr.number, - body: message.split('\n').map(l => l.trim()).join('\n'), + body: message, }); - await github.rest.pulls.update({ - owner: context.repo.owner, - repo: context.repo.repo, - pull_number: pr.number, - state: 'closed', - }); + if (!isMaintainer) { + await github.rest.pulls.update({ + owner: context.repo.owner, + repo: context.repo.repo, + pull_number: pr.number, + state: 'closed', + }); + } - core.setFailed(`PR #${pr.number} targets main. Closed automatically.`); + core.setFailed(`PR #${pr.number} targets main from '${headRef}' (not dev). ${isMaintainer ? 'Retarget to dev.' : 'Closed automatically.'}`); diff --git a/.hermes/skills/claude-skills/engineering/command-guide b/.hermes/skills/claude-skills/engineering/command-guide deleted file mode 120000 index b54c7bee..00000000 --- a/.hermes/skills/claude-skills/engineering/command-guide +++ /dev/null @@ -1 +0,0 @@ -../../../../engineering/skills/command-guide \ No newline at end of file diff --git a/.hermes/skills/claude-skills/engineering/release-manager b/.hermes/skills/claude-skills/engineering/release-manager deleted file mode 120000 index cb313c21..00000000 --- a/.hermes/skills/claude-skills/engineering/release-manager +++ /dev/null @@ -1 +0,0 @@ -../../../../engineering/skills/release-manager \ No newline at end of file diff --git a/.hermes/skills/claude-skills/marketing-skill/ai-seo b/.hermes/skills/claude-skills/marketing-skill/ai-seo deleted file mode 120000 index 63287ebc..00000000 --- a/.hermes/skills/claude-skills/marketing-skill/ai-seo +++ /dev/null @@ -1 +0,0 @@ -../../../../marketing-skill/skills/ai-seo \ No newline at end of file diff --git a/.vibe/skills/claude-skills/engineering/command-guide b/.vibe/skills/claude-skills/engineering/command-guide deleted file mode 120000 index b54c7bee..00000000 --- a/.vibe/skills/claude-skills/engineering/command-guide +++ /dev/null @@ -1 +0,0 @@ -../../../../engineering/skills/command-guide \ No newline at end of file diff --git a/.vibe/skills/claude-skills/engineering/release-manager b/.vibe/skills/claude-skills/engineering/release-manager deleted file mode 120000 index cb313c21..00000000 --- a/.vibe/skills/claude-skills/engineering/release-manager +++ /dev/null @@ -1 +0,0 @@ -../../../../engineering/skills/release-manager \ No newline at end of file diff --git a/.vibe/skills/claude-skills/marketing-skill/ai-seo b/.vibe/skills/claude-skills/marketing-skill/ai-seo deleted file mode 120000 index 63287ebc..00000000 --- a/.vibe/skills/claude-skills/marketing-skill/ai-seo +++ /dev/null @@ -1 +0,0 @@ -../../../../marketing-skill/skills/ai-seo \ No newline at end of file diff --git a/CHANGELOG.md b/CHANGELOG.md index c71f653f..abdd773e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,23 @@ All notable changes to the Claude Skills Library will be documented in this file The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## [Unreleased] — newgen audit follow-up: P0 fixes, path sweep, CI guards + +### Deprecated / Removed Skills (migration notes) + +Three skills were retired or merged in the newgen-audit follow-up (PR #835). If +you installed or pinned any of these, migrate as follows: + +| Removed skill | Why | Migrate to | +|---|---|---| +| `engineering/skills/command-guide` | Documented a different repository's commands and agents; instructed models to invoke agents that don't exist here | No replacement needed — the root `commands/` folder and each plugin's own commands are the canonical command surface | +| `marketing-skill/skills/ai-seo` | Near-total overlap with the newer, tool-backed AEO skill | `marketing-skill/skills/aeo` — unique ai-seo content was preserved in `aeo/references/bot_access_and_monitoring.md` and `aeo/references/extractable_content_patterns.md` | +| `engineering/skills/release-manager` | 489-line SemVer/Git-Flow textbook duplicating changelog-generator; its readiness checker crashed | `engineering/skills/changelog-generator` — now includes `version_bumper.py`, hotfix/rollback procedures, and the severity-SLA table. For release-readiness audits use `engineering/skills/ship-gate` | + +Also restructured (no content change): `engineering/universal-scraping-architect` +moved its SKILL.md from plugin root to the standard `skills/universal-scraping-architect/` +layout. Marketplace source path is unchanged. + ## [Unreleased] — code-reviewer: C-specific smell detector + fixtures ### Added — language-specific smell pack for C (this PR) diff --git a/CLAUDE.md b/CLAUDE.md index 69b90b8e..bfdaa8ac 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -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:** 338 production-ready skills across 16 domains with 533 Python automation tools, 676 reference guides, 51+ agents (cs-* + 7 personas), and 87+ slash commands, distributed as 62 marketplace plugins. **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:** 345 production-ready skills across 17 domains with 579 Python automation tools, 702 reference guides, 93 agents (cs-* + 7 personas), and 99 slash commands, distributed as 78 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. **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. @@ -21,6 +21,13 @@ The following exist on the maintainer's disk but are excluded from the public Gi - `.autoresearch/` — autoresearch agent workspace - `AUDIT_REPORT.md` — internal audit snapshots +**Distinct from the above:** the top-level `audit/` directory (e.g. +`audit/newgen-2026-06/`) is an **intentional, public** audit record — rubric + +per-domain reports with per-skill verification criteria that follow-up PRs use +as acceptance gates. It is excluded from headline counters by +`scripts/derive_counters.py`, but it is committed and visible to cloners. +`AUDIT_REPORT.md` (gitignored, above) is the older internal-snapshot format. + In-repo references to paths under these folders (e.g. `documentation/implementation/...`) resolve locally for the maintainer but appear as dead links on GitHub. This is intentional. ## Navigation Map @@ -95,6 +102,13 @@ skill-name/ **Branch Strategy:** feature → dev → main (PR only) +> **⛔ HARD RULE — PR TARGET IS ALWAYS `dev`, NEVER `main`.** +> Every PR (human or AI-created) must use `--base dev`. Nothing merges into `main` +> directly — `main` only receives periodic `dev → main` promotion PRs opened by the +> maintainer. If you find a PR targeting `main`, retarget it to `dev` before review. +> AI agents (Claude Code included): set the base branch explicitly when creating PRs; +> never rely on the repository default branch. + **Branch Protection Active:** Main branch requires PR approval. Direct pushes blocked. ### Quick Start @@ -159,7 +173,7 @@ Completes the `markdown-html/` domain at 5 skills. The Tier-3 use case from Shih - **1 template asset** documenting the canonical single-file deck shape. - **`/cs:md-slides` slash command** with 6 pre-flight gates + pipeline + output digest. - **Empirical footprint**: 5-slide sample deck (3 with presenter notes) → 12.2 KB single-file HTML with keyboard nav + presenter mode + print-to-PDF. By comparison, equivalent Google Slides / Keynote / reveal.js multi-file exports are 200 KB+ of CSS/JS chrome. -- **Plugin manifest:** `markdown-html-skills` plugin.json `skills` array now lists 5 paths (orchestrator + design-system + md-document + md-review + md-slides). Marketplace counters updated: 64 plugins, 17 domains, **343 skills**, **548 Python tools**, **691 references**, **90+ slash commands**. +- **Plugin manifest:** `markdown-html-skills` plugin.json `skills` array now lists 5 paths (orchestrator + design-system + md-document + md-review + md-slides). Marketplace counters updated (trued up 2026-06-10 via `scripts/derive_counters.py`): 77 plugins, 17 domains, **345 skills**, **579 Python tools**, **702 references**, **99 slash commands**. - **Domain status: COMPLETE.** All 5 planned skills shipped across 4 PRs (#780 foundation, #793 md-document, #795 md-review, this PR md-slides). The markdown-html/ domain operationalizes Shihipar's central claim — markdown collapses past 100 lines; HTML restores density, clarity, shareability, and lightweight interaction — across all three layout families (long-form documents, code reviews, slide decks). --- @@ -510,6 +524,6 @@ This repository publishes skills to **ClawHub** (clawhub.com) as the distributio --- -**Last Updated:** May 27, 2026 -**Version:** v2.9.0 -**Status:** 338 skills deployed across 16 domains, 62 marketplace plugins, docs site live +**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`) diff --git a/README.md b/README.md index 62b2468d..d8001265 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Claude Code Skills & Plugins — Agent Skills for Every Coding Tool -**338 production-ready Claude Code skills, plugins, and agent skills for 13 AI coding tools.** +**345 production-ready Claude Code skills, plugins, and agent skills for 13 AI coding tools.** The most comprehensive open-source library of Claude Code skills and agent plugins — also works with OpenAI Codex, Gemini CLI, Cursor, and 9 more coding agents. Reusable expertise packages covering engineering, DevOps, marketing (incl. AEO — Answer Engine Optimization for LLM citation), security (PreToolUse hooks), compliance, C-level advisory (incl. founder-mode CFO/CMO/CRO/CPO/COO/CHRO/CISO/GC/CDO/CAIO/CCO/VPE personas + 21 /cs:* slash commands), productivity (capture/email/reflect), an academic research stack (litreview/grants/dossier/patent/syllabus/pulse/notebooklm + hybrid router), and enterprise Research Operations (clinical-research/research-finance/market-research/product-research, v2.9.0). @@ -10,10 +10,10 @@ The most comprehensive open-source library of Claude Code skills and agent plugi [^vibe]: Mistral Vibe is also **BYO-sync tier**: the repo ships a pre-generated `.vibe/skills/claude-skills/` tree, run `./scripts/vibe-install.sh` once locally to install into `~/.vibe/skills/`. Same agentskills.io SKILL.md standard — no format conversion. Docs: . [![License: MIT](https://img.shields.io/badge/License-MIT-yellow?style=for-the-badge)](https://opensource.org/licenses/MIT) -[![Skills](https://img.shields.io/badge/Skills-338-brightgreen?style=for-the-badge)](#skills-overview) -[![Agents](https://img.shields.io/badge/Agents-51+-blue?style=for-the-badge)](#agents) +[![Skills](https://img.shields.io/badge/Skills-346-brightgreen?style=for-the-badge)](#skills-overview) +[![Agents](https://img.shields.io/badge/Agents-93-blue?style=for-the-badge)](#agents) [![Personas](https://img.shields.io/badge/Personas-7-purple?style=for-the-badge)](#personas) -[![Commands](https://img.shields.io/badge/Commands-87+-orange?style=for-the-badge)](#commands) +[![Commands](https://img.shields.io/badge/Commands-99-orange?style=for-the-badge)](#commands) [![Stars](https://img.shields.io/github/stars/alirezarezvani/claude-skills?style=for-the-badge)](https://github.com/alirezarezvani/claude-skills/stargazers) [![SkillCheck Validated](https://img.shields.io/badge/SkillCheck-Validated-4c1?style=for-the-badge)](https://getskillcheck.com) @@ -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** — 533 CLI scripts (all stdlib-only, zero pip installs) -- **Reference docs** — 676 templates, checklists, and domain-specific knowledge files +- **Python tools** — 579 CLI scripts (all stdlib-only, zero pip installs) +- **Reference docs** — 702 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 533 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 579 Python tools run anywhere Python runs. ### Skills vs Agents vs Personas @@ -108,7 +108,7 @@ git clone https://github.com/alirezarezvani/claude-skills.git ## Multi-Tool Support (New) -**Convert all 338 skills to 9 AI coding tools** with a single script: +**Convert all 345 skills to 9 AI coding tools** with a single script: | Tool | Format | Install | |------|--------|---------| @@ -135,11 +135,11 @@ git clone https://github.com/alirezarezvani/claude-skills.git ./scripts/install.sh --tool aider --target . --force # 3. Verify -find .cursor/rules -name "*.mdc" | wc -l # Should show 338 +find .cursor/rules -name "*.mdc" | wc -l # Should show 346 ``` **Each tool gets:** -- ✅ All 338 skills converted to native format +- ✅ All 345 skills converted to native format - ✅ Per-tool README with install/verify/update steps - ✅ Support for scripts, references, templates where applicable - ✅ Zero manual conversion work @@ -150,7 +150,7 @@ Run `./scripts/convert.sh --tool all` to generate tool-specific outputs locally. ## Skills Overview -**338 skills across 16 domains:** +**345 skills across 17 domains:** | Domain | Skills | Highlights | Details | |--------|--------|------------|---------| @@ -239,7 +239,6 @@ See [orchestration/ORCHESTRATION.md](orchestration/ORCHESTRATION.md) for the ful | **api-design-reviewer** | REST API linter, breaking change detector, design scorecard | | **api-test-suite-builder** | Scan API routes → generate complete test suites | | **dependency-auditor** | Multi-language scanner, license compliance, upgrade planner | -| **release-manager** | Changelog generator, semantic version bumper, readiness checker | | **observability-designer** | SLO designer, alert optimizer, dashboard generator | | **performance-profiler** | Node/Python/Go profiling, bundle analysis, load testing | | **monorepo-navigator** | Turborepo/Nx/pnpm workspace management & impact analysis | @@ -306,7 +305,7 @@ for MDR Annex II compliance gaps. ## Python Analysis Tools -533 CLI tools ship with the skills (all verified, stdlib-only): +579 CLI tools ship with the skills (all verified, stdlib-only): ```bash # SaaS health check @@ -353,7 +352,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 533 Python CLI tools use the standard library only — zero pip installs required. Every script is verified to run with `--help`. +Yes. All 579 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. diff --git a/agents/CLAUDE.md b/agents/CLAUDE.md index ee1dd1da..bb40db39 100644 --- a/agents/CLAUDE.md +++ b/agents/CLAUDE.md @@ -1,13 +1,13 @@ # Agent Development Guide -This guide provides comprehensive instructions for creating **cs-* prefixed agents** that seamlessly integrate with the 42 production skills in this repository. +This guide provides comprehensive instructions for creating **cs-* prefixed agents** that seamlessly integrate with the 346 production skills in this repository (count derived via `scripts/derive_counters.py`). ## Agent Architecture ### What are cs-* Agents? -**cs-* agents** are specialized Claude Code agents that orchestrate the 177 existing skills. Each agent: -- References skills via relative paths (`../../marketing-skill/`) +**cs-* agents** are specialized Claude Code agents that orchestrate the repository's 346 skills. Each agent: +- References skills via relative paths (`../marketing-skill/`) - Executes Python automation tools from skill packages - Follows established workflows and templates - Maintains skill portability and independence @@ -24,7 +24,7 @@ When skills are published to **ClawHub** (clawhub.com): ### Production Agents -**16 Agents Currently Available**: +**33 agents live in this folder** (93 agent files repo-wide, including plugin-bundled agents). A representative selection: | Agent | Domain | Description | |-------|--------|-------------| @@ -108,17 +108,17 @@ After YAML frontmatter, include these sections: All skill references use the `../../` pattern: ```markdown -**Skill Location:** `../../marketing-skill/content-creator/` +**Skill Location:** `../marketing-skill/skills/content-creator/` ### Python Tools 1. **Brand Voice Analyzer** - - **Path:** `../../marketing-skill/content-creator/scripts/brand_voice_analyzer.py` - - **Usage:** `python ../../marketing-skill/content-creator/scripts/brand_voice_analyzer.py content.txt` + - **Path:** `../marketing-skill/skills/content-production/scripts/brand_voice_analyzer.py` + - **Usage:** `python ../marketing-skill/skills/content-production/scripts/brand_voice_analyzer.py content.txt` 2. **SEO Optimizer** - - **Path:** `../../marketing-skill/content-creator/scripts/seo_optimizer.py` - - **Usage:** `python ../../marketing-skill/content-creator/scripts/seo_optimizer.py article.md "keyword"` + - **Path:** `../marketing-skill/skills/content-production/scripts/seo_optimizer.py` + - **Usage:** `python ../marketing-skill/skills/content-production/scripts/seo_optimizer.py article.md "keyword"` ``` ### Why `../../`? @@ -138,13 +138,13 @@ Agents execute Python tools from skill packages: ```bash # From agent context -python ../../marketing-skill/content-creator/scripts/brand_voice_analyzer.py input.txt +python ../marketing-skill/skills/content-production/scripts/brand_voice_analyzer.py input.txt # With JSON output -python ../../marketing-skill/content-creator/scripts/brand_voice_analyzer.py input.txt json +python ../marketing-skill/skills/content-production/scripts/brand_voice_analyzer.py input.txt json # With arguments -python ../../product-team/product-manager-toolkit/scripts/rice_prioritizer.py features.csv --capacity 20 +python ../product-team/skills/product-manager-toolkit/scripts/rice_prioritizer.py features.csv --capacity 20 ``` ### Tool Requirements @@ -188,7 +188,7 @@ Each workflow must include: **Example:** \`\`\`bash # Concrete example command -python ../../marketing-skill/content-creator/scripts/seo_optimizer.py article.md "primary keyword" +python ../marketing-skill/skills/content-production/scripts/seo_optimizer.py article.md "primary keyword" \`\`\` ``` @@ -278,12 +278,12 @@ python ../../domain-skill/skill-name/scripts/tool.py input.txt ## Related Agents -- [cs-related-agent](../domain/cs-related-agent.md) - How they relate +- [cs-related-agent](..//cs-related-agent.md) - How they relate ## References - [Skill Documentation](../../domain-skill/skill-name/SKILL.md) -- [Domain Roadmap](../../domain-skill/roadmap.md) +- [Domain Roadmap](../..//roadmap.md) ``` ## Quality Standards @@ -311,7 +311,7 @@ Test these aspects: ```bash # From agent directory cd agents/marketing/ -ls ../../marketing-skill/content-creator/ # Should list contents +ls ../marketing-skill/skills/content-creator/ # Should list contents ``` **2. Python Tool Execution** @@ -320,7 +320,7 @@ ls ../../marketing-skill/content-creator/ # Should list contents echo "Test content" > test-input.txt # Execute tool -python ../../marketing-skill/content-creator/scripts/brand_voice_analyzer.py test-input.txt +python ../marketing-skill/skills/content-production/scripts/brand_voice_analyzer.py test-input.txt # Verify output ``` @@ -328,29 +328,29 @@ python ../../marketing-skill/content-creator/scripts/brand_voice_analyzer.py tes **3. Knowledge Base Access** ```bash # Verify reference files exist -cat ../../marketing-skill/content-creator/references/brand_guidelines.md +cat ../marketing-skill/skills/content-creator/references/brand_guidelines.md ``` ## Domain-Specific Guidelines ### Marketing Agents (agents/marketing/) - Focus on content creation, SEO, demand generation -- Reference: `../../marketing-skill/` +- Reference: `../marketing-skill/` - Tools: brand_voice_analyzer.py, seo_optimizer.py ### Product Agents (agents/product/) - Focus on prioritization, user research, agile workflows -- Reference: `../../product-team/` +- Reference: `../product-team/` - Tools: rice_prioritizer.py, user_story_generator.py, okr_cascade_generator.py ### C-Level Agents (agents/c-level/) - Focus on strategic decision-making -- Reference: `../../c-level-advisor/` +- Reference: `../c-level-advisor/` - Tools: Strategic analysis and planning tools ### Engineering Agents (agents/engineering/) - Focus on scaffolding, code quality, fullstack development -- Reference: `../../engineering-team/` +- Reference: `engineering-team/` - Tools: project_scaffolder.py, code_quality_analyzer.py ## Common Pitfalls @@ -378,6 +378,6 @@ After creating an agent: --- -**Last Updated:** March 11, 2026 -**Current:** 16 agents across 8 domains +**Last Updated:** June 10, 2026 +**Current:** 33 agents in this folder across 10 domain subfolders (93 agent files repo-wide) **Related:** See [main CLAUDE.md](../CLAUDE.md) for repository overview 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 6d723f70..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 @@ -396,7 +396,6 @@ echo "- Process improvements identified" - [cs-ceo-advisor](cs-ceo-advisor.md) - Strategic leadership and organizational development (CEO counterpart) - [cs-fullstack-engineer](../engineering/cs-fullstack-engineer.md) - Fullstack development coordination (planned) -- [cs-devops-specialist](../engineering/cs-devops-specialist.md) - DevOps and infrastructure automation (planned) ## References diff --git a/agents/engineering-team/cs-workspace-admin.md b/agents/engineering-team/cs-workspace-admin.md index c0b9a5e2..82381f8d 100644 --- a/agents/engineering-team/cs-workspace-admin.md +++ b/agents/engineering-team/cs-workspace-admin.md @@ -21,44 +21,44 @@ Google Workspace administration specialist orchestrating the gws CLI for email a ### Python Tools 1. **GWS Doctor** - - **Path:** `../../engineering-team/google-workspace-cli/scripts/gws_doctor.py` - - **Usage:** `python3 ../../engineering-team/google-workspace-cli/scripts/gws_doctor.py [--json]` + - **Path:** `../../engineering-team/google-workspace-cli/skills/google-workspace-cli/scripts/gws_doctor.py` + - **Usage:** `python3 ../../engineering-team/google-workspace-cli/skills/google-workspace-cli/scripts/gws_doctor.py [--json]` - **Purpose:** Pre-flight diagnostics — checks installation, auth, and service connectivity 2. **Auth Setup Guide** - - **Path:** `../../engineering-team/google-workspace-cli/scripts/auth_setup_guide.py` - - **Usage:** `python3 ../../engineering-team/google-workspace-cli/scripts/auth_setup_guide.py --guide oauth` + - **Path:** `../../engineering-team/google-workspace-cli/skills/google-workspace-cli/scripts/auth_setup_guide.py` + - **Usage:** `python3 ../../engineering-team/google-workspace-cli/skills/google-workspace-cli/scripts/auth_setup_guide.py --guide oauth` - **Purpose:** Guided auth setup, scope listing, .env generation, validation 3. **Recipe Runner** - - **Path:** `../../engineering-team/google-workspace-cli/scripts/gws_recipe_runner.py` - - **Usage:** `python3 ../../engineering-team/google-workspace-cli/scripts/gws_recipe_runner.py --list` + - **Path:** `../../engineering-team/google-workspace-cli/skills/google-workspace-cli/scripts/gws_recipe_runner.py` + - **Usage:** `python3 ../../engineering-team/google-workspace-cli/skills/google-workspace-cli/scripts/gws_recipe_runner.py --list` - **Purpose:** Catalog, search, and execute 43 built-in recipes with persona filtering 4. **Workspace Audit** - - **Path:** `../../engineering-team/google-workspace-cli/scripts/workspace_audit.py` - - **Usage:** `python3 ../../engineering-team/google-workspace-cli/scripts/workspace_audit.py [--json]` + - **Path:** `../../engineering-team/google-workspace-cli/skills/google-workspace-cli/scripts/workspace_audit.py` + - **Usage:** `python3 ../../engineering-team/google-workspace-cli/skills/google-workspace-cli/scripts/workspace_audit.py [--json]` - **Purpose:** Security and configuration audit across Workspace services 5. **Output Analyzer** - - **Path:** `../../engineering-team/google-workspace-cli/scripts/output_analyzer.py` - - **Usage:** `gws ... --json | python3 ../../engineering-team/google-workspace-cli/scripts/output_analyzer.py --count` + - **Path:** `../../engineering-team/google-workspace-cli/skills/google-workspace-cli/scripts/output_analyzer.py` + - **Usage:** `gws ... --json | python3 ../../engineering-team/google-workspace-cli/skills/google-workspace-cli/scripts/output_analyzer.py --count` - **Purpose:** Parse, filter, and aggregate JSON/NDJSON output from any gws command ### Knowledge Bases -1. **Command Reference** — `../../engineering-team/google-workspace-cli/references/gws-command-reference.md` +1. **Command Reference** — `../../engineering-team/google-workspace-cli/skills/google-workspace-cli/references/gws-command-reference.md` - 18 services, 22 helpers, global flags, environment variables -2. **Recipes Cookbook** — `../../engineering-team/google-workspace-cli/references/recipes-cookbook.md` +2. **Recipes Cookbook** — `../../engineering-team/google-workspace-cli/skills/google-workspace-cli/references/recipes-cookbook.md` - 43 recipes organized by category with persona mapping -3. **Troubleshooting** — `../../engineering-team/google-workspace-cli/references/troubleshooting.md` +3. **Troubleshooting** — `../../engineering-team/google-workspace-cli/skills/google-workspace-cli/references/troubleshooting.md` - Common errors, auth issues, platform-specific fixes ### Templates -1. **Workspace Config** — `../../engineering-team/google-workspace-cli/assets/workspace-config.json` +1. **Workspace Config** — `../../engineering-team/google-workspace-cli/skills/google-workspace-cli/assets/workspace-config.json` - Automation config template with auth, defaults, scheduled tasks -2. **Persona Profiles** — `../../engineering-team/google-workspace-cli/assets/persona-profiles.md` +2. **Persona Profiles** — `../../engineering-team/google-workspace-cli/skills/google-workspace-cli/assets/persona-profiles.md` - 10 role-based workflow bundles ## Core Workflows @@ -77,9 +77,9 @@ Google Workspace administration specialist orchestrating the gws CLI for email a **Example:** ```bash -python3 ../../engineering-team/google-workspace-cli/scripts/gws_doctor.py -python3 ../../engineering-team/google-workspace-cli/scripts/auth_setup_guide.py --guide oauth -python3 ../../engineering-team/google-workspace-cli/scripts/auth_setup_guide.py --validate --json +python3 ../../engineering-team/google-workspace-cli/skills/google-workspace-cli/scripts/gws_doctor.py +python3 ../../engineering-team/google-workspace-cli/skills/google-workspace-cli/scripts/auth_setup_guide.py --guide oauth +python3 ../../engineering-team/google-workspace-cli/skills/google-workspace-cli/scripts/auth_setup_guide.py --validate --json ``` ### 2. Daily Operations @@ -94,9 +94,9 @@ python3 ../../engineering-team/google-workspace-cli/scripts/auth_setup_guide.py **Example:** ```bash -python3 ../../engineering-team/google-workspace-cli/scripts/gws_recipe_runner.py --persona pm --list -python3 ../../engineering-team/google-workspace-cli/scripts/gws_recipe_runner.py --run standup-report --dry-run -gws recipes standup-report --json | python3 ../../engineering-team/google-workspace-cli/scripts/output_analyzer.py --format table +python3 ../../engineering-team/google-workspace-cli/skills/google-workspace-cli/scripts/gws_recipe_runner.py --persona pm --list +python3 ../../engineering-team/google-workspace-cli/skills/google-workspace-cli/scripts/gws_recipe_runner.py --run standup-report --dry-run +gws recipes standup-report --json | python3 ../../engineering-team/google-workspace-cli/skills/google-workspace-cli/scripts/output_analyzer.py --format table ``` ### 3. Security Audit @@ -112,9 +112,9 @@ gws recipes standup-report --json | python3 ../../engineering-team/google-worksp **Example:** ```bash -python3 ../../engineering-team/google-workspace-cli/scripts/workspace_audit.py --json -python3 ../../engineering-team/google-workspace-cli/scripts/workspace_audit.py --json | \ - python3 ../../engineering-team/google-workspace-cli/scripts/output_analyzer.py --filter "status=FAIL" +python3 ../../engineering-team/google-workspace-cli/skills/google-workspace-cli/scripts/workspace_audit.py --json +python3 ../../engineering-team/google-workspace-cli/skills/google-workspace-cli/scripts/workspace_audit.py --json | \ + python3 ../../engineering-team/google-workspace-cli/skills/google-workspace-cli/scripts/output_analyzer.py --filter "status=FAIL" ``` ### 4. Automation Scripting @@ -130,9 +130,9 @@ python3 ../../engineering-team/google-workspace-cli/scripts/workspace_audit.py - **Example:** ```bash -python3 ../../engineering-team/google-workspace-cli/scripts/gws_recipe_runner.py --describe morning-briefing +python3 ../../engineering-team/google-workspace-cli/skills/google-workspace-cli/scripts/gws_recipe_runner.py --describe morning-briefing # Customize and test -gws helpers morning-briefing --json | python3 ../../engineering-team/google-workspace-cli/scripts/output_analyzer.py --select "type,summary,time" --format table +gws helpers morning-briefing --json | python3 ../../engineering-team/google-workspace-cli/skills/google-workspace-cli/scripts/output_analyzer.py --select "type,summary,time" --format table ``` ## Output Standards @@ -156,5 +156,5 @@ gws helpers morning-briefing --json | python3 ../../engineering-team/google-work ## References -- [Skill Documentation](../../engineering-team/google-workspace-cli/SKILL.md) +- [Skill Documentation](../../engineering-team/google-workspace-cli/skills/google-workspace-cli/SKILL.md) - [gws CLI Repository](https://github.com/googleworkspace/cli) diff --git a/agents/engineering/cs-backend-engineer.md b/agents/engineering/cs-backend-engineer.md index d3579d27..5a6d6eff 100644 --- a/agents/engineering/cs-backend-engineer.md +++ b/agents/engineering/cs-backend-engineer.md @@ -123,8 +123,8 @@ python ../../engineering/karpathy-coder/skills/karpathy-coder/scripts/diff_surge - [cs-frontend-engineer](cs-frontend-engineer.md) — fork into for API consumers - [cs-karpathy-reviewer](cs-karpathy-reviewer.md) — invoke before every commit - [cs-cto-advisor](../c-level/cs-cto-advisor.md) — escalate strategic build-vs-buy -- [cs-vpe-advisor](../c-level/cs-vpe-advisor.md) — escalate throughput / org / DORA -- [cs-ciso-advisor](../c-level/cs-ciso-advisor.md) — escalate regulated-data exposure +- [cs-vpe-advisor](../../c-level-advisor/c-level-agents/agents/cs-vpe-advisor.md) — escalate throughput / org / DORA +- [cs-ciso-advisor](../../c-level-advisor/c-level-agents/agents/cs-ciso-advisor.md) — escalate regulated-data exposure ## Invocation Contract diff --git a/agents/engineering/cs-fullstack-engineer.md b/agents/engineering/cs-fullstack-engineer.md index 94cb262e..69a49073 100644 --- a/agents/engineering/cs-fullstack-engineer.md +++ b/agents/engineering/cs-fullstack-engineer.md @@ -163,7 +163,7 @@ python ../../engineering/karpathy-coder/skills/karpathy-coder/scripts/diff_surge - [cs-karpathy-reviewer](cs-karpathy-reviewer.md) — invoke before every commit - [cs-senior-engineer](cs-senior-engineer.md) — cross-cutting engineering lead (use for non-stack questions like CI/CD, security review) - [cs-cto-advisor](../c-level/cs-cto-advisor.md) — escalate for strategic build-vs-buy or technical debt prioritization -- [cs-vpe-advisor](../c-level/cs-vpe-advisor.md) — escalate for org-design + throughput +- [cs-vpe-advisor](../../c-level-advisor/c-level-agents/agents/cs-vpe-advisor.md) — escalate for org-design + throughput ## Invocation Contract 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/engineering/cs-wiki-ingestor.md b/agents/engineering/cs-wiki-ingestor.md index 185f08ac..16aa1dbe 100644 --- a/agents/engineering/cs-wiki-ingestor.md +++ b/agents/engineering/cs-wiki-ingestor.md @@ -24,7 +24,7 @@ You are spawned **per-ingest**, not as a long-running agent. You do one source a ## Workflow -Follow `references/ingest-workflow.md` in the llm-wiki skill. Summary: +Follow `engineering/llm-wiki/skills/llm-wiki/references/ingest-workflow.md` in the llm-wiki skill. Summary: ### 1. Prep Run `python /scripts/ingest_source.py --vault . --source --json` to get the brief (title guess, word count, preview, suggested summary path, whether a summary already exists). diff --git a/agents/engineering/cs-wiki-librarian.md b/agents/engineering/cs-wiki-librarian.md index 7e2b7a2e..023681e7 100644 --- a/agents/engineering/cs-wiki-librarian.md +++ b/agents/engineering/cs-wiki-librarian.md @@ -23,7 +23,7 @@ You are spawned **per-query**, not as a long-running agent. ## Workflow -Follow `references/query-workflow.md`. Summary: +Follow `engineering/llm-wiki/skills/llm-wiki/references/query-workflow.md`. Summary: ### 1. Read `index.md` first The index is the catalog. Scan it and pick the 3-10 pages most likely to contain the answer. Pick across categories: @@ -62,7 +62,7 @@ This is the compounding move. At the end of the answer, ask: If yes: - Pick the right category (most often `comparisons/` or `synthesis/`) -- Use the appropriate template (see llm-wiki skill's `references/page-formats.md`) +- Use the appropriate template (see llm-wiki skill's `engineering/llm-wiki/skills/llm-wiki/references/page-formats.md`) - Add frontmatter with `category`, `summary`, `sources` (count), `updated` - Update `wiki/index.md` (inline or via script) - Append to `log.md`: `python /scripts/append_log.py --vault . --op create --title "" --detail "filed query response to "` diff --git a/agents/engineering/cs-wiki-linter.md b/agents/engineering/cs-wiki-linter.md index 19c45a7f..82d4f989 100644 --- a/agents/engineering/cs-wiki-linter.md +++ b/agents/engineering/cs-wiki-linter.md @@ -18,7 +18,7 @@ You are spawned **per-lint-pass**, not as a long-running agent. ## Workflow -Follow `references/lint-workflow.md`. Three passes. +Follow `engineering/llm-wiki/skills/llm-wiki/references/lint-workflow.md`. Three passes. ### Pass 1 — Mechanical (scripts) diff --git a/agents/finance/cs-financial-analyst.md b/agents/finance/cs-financial-analyst.md index b399ca66..d7956583 100644 --- a/agents/finance/cs-financial-analyst.md +++ b/agents/finance/cs-financial-analyst.md @@ -85,23 +85,23 @@ Financial analyst covering valuation, ratio analysis, forecasting, and industry- ```bash # SaaS health check — full metrics from raw numbers -python ../../finance/saas-metrics-coach/scripts/metrics_calculator.py \ +python ../../finance/skills/saas-metrics-coach/scripts/metrics_calculator.py \ --mrr 80000 --mrr-last 75000 --customers 200 --churned 3 \ --new-customers 15 --sm-spend 25000 --gross-margin 72 --json # Quick ratio — growth efficiency -python ../../finance/saas-metrics-coach/scripts/quick_ratio_calculator.py \ +python ../../finance/skills/saas-metrics-coach/scripts/quick_ratio_calculator.py \ --new-mrr 10000 --expansion 2000 --churned 3000 --contraction 500 # 12-month projection -python ../../finance/saas-metrics-coach/scripts/unit_economics_simulator.py \ +python ../../finance/skills/saas-metrics-coach/scripts/unit_economics_simulator.py \ --mrr 80000 --growth 8 --churn 1.5 --cac 1667 --json # Traditional ratio analysis -python ../../finance/financial-analyst/scripts/ratio_calculator.py financial_data.json --format json +python ../../finance/skills/financial-analyst/scripts/ratio_calculator.py financial_data.json --format json # DCF valuation -python ../../finance/financial-analyst/scripts/dcf_valuation.py valuation_data.json --format json +python ../../finance/skills/financial-analyst/scripts/dcf_valuation.py valuation_data.json --format json ``` ## Related Agents diff --git a/agents/marketing/cs-aeo.md b/agents/marketing/cs-aeo.md index c190d262..7b8b0d3a 100644 --- a/agents/marketing/cs-aeo.md +++ b/agents/marketing/cs-aeo.md @@ -72,14 +72,14 @@ Differentiates from siblings: ### Reference docs (each cites 7+ sources) -- `references/aeo_eeat_canon.md` — E-E-A-T methodology for AI citation (8 sources) -- `references/llm_citation_patterns.md` — How each major LLM chooses sources (8 sources) -- `references/aeo_vs_seo.md` — The two disciplines, overlap, and strategic choice (8 sources) +- `marketing-skill/skills/aeo/references/aeo_eeat_canon.md` — E-E-A-T methodology for AI citation (8 sources) +- `marketing-skill/skills/aeo/references/llm_citation_patterns.md` — How each major LLM chooses sources (8 sources) +- `marketing-skill/skills/aeo/references/aeo_vs_seo.md` — The two disciplines, overlap, and strategic choice (8 sources) ## Related Agents -- [cs-content-creator](../../agents/cs-content-creator.md) — marketing-domain content writer -- [seo-audit](https://github.com/alirezarezvani/claude-skills/tree/main/marketing-skill/skills/seo-audit) — companion SEO audit skill (often run together) +- [cs-content-creator](cs-content-creator.md) — marketing-domain content writer +- [seo-audit skill](../../marketing-skill/skills/seo-audit/SKILL.md) — companion SEO audit (often run together) - DIFFERENT use case: `engineering/autoresearch-agent` (Karpathy's file-optimization loop — orthogonal) --- diff --git a/agents/marketing/cs-content-creator.md b/agents/marketing/cs-content-creator.md index f03b7446..94f928e3 100644 --- a/agents/marketing/cs-content-creator.md +++ b/agents/marketing/cs-content-creator.md @@ -1,247 +1,139 @@ --- name: cs-content-creator -description: AI-powered content creation specialist for brand voice consistency, SEO optimization, and multi-platform content strategy -skills: marketing-skill/content-creator +description: Long-form marketing content producer orchestrating the content-production skill (research → brief → draft → optimize → gate). Use when content must be written, scored, or made publish-ready — e.g., drafting a 2,000-word blog post against a target keyword and blocking publish until content_quality_gates.py passes, or auditing a draft for brand-voice drift with brand_voice_analyzer.py before it ships. Routes planning requests (topic clusters, calendars) to content-strategy. Supersedes the deprecated content-creator skill. +skills: marketing-skill/skills/content-production domain: marketing model: sonnet -tools: [Read, Write, Bash, Grep, Glob] +tools: [Read, Write, Bash, Grep] --- # Content Creator Agent ## Purpose -The cs-content-creator agent is a specialized marketing agent that orchestrates the content-creator skill package to help teams produce high-quality, on-brand content at scale. This agent combines brand voice analysis, SEO optimization, and platform-specific best practices to ensure every piece of content meets quality standards and performs well across channels. +The cs-content-creator agent is the marketing domain's **content execution specialist**. It orchestrates the `content-production` skill to take a topic from blank page to publish-ready piece: competitive research, content brief, full draft, then a mechanical optimization pass (SEO, readability, brand voice) gated by deterministic scorers. -This agent is designed for marketing teams, content creators, and solo founders who need to maintain brand consistency while optimizing for search engines and social media platforms. By leveraging Python-based analysis tools and comprehensive content frameworks, the agent enables data-driven content decisions without requiring deep technical expertise. +It is the execution engine, not the strategy layer: -The cs-content-creator agent bridges the gap between creative content production and technical SEO requirements, ensuring that content is both engaging for humans and optimized for search engines. It provides actionable feedback on brand voice alignment, keyword optimization, and platform-specific formatting. +- **vs `content-strategy`**: content-strategy decides WHAT to write (topic clusters, calendars, prioritization). This agent writes and polishes the piece. Route planning-only requests there. +- **vs `cs-aeo`**: cs-aeo optimizes finished content for LLM citation (AEO). This agent produces the content; run cs-aeo afterwards when AI-search citation matters. +- **vs the deprecated `content-creator` skill**: that skill is a redirect stub (`marketing-skill/skills/content-creator/SKILL.md`, status: deprecated). Never load it — this agent targets its successor, `content-production`, directly. + +**Hard rule:** no draft is "done" until the quality gates pass. A failing gate from `content_quality_gates.py` blocks publish; fix and re-run until clean. + +## Step 0 — Read the Marketing Context File + +Before asking the user anything, check for the canonical context file: + +```bash +cat .claude/product-marketing-context.md 2>/dev/null +``` + +If it exists, it contains brand voice, target audience, keyword targets, and writing examples — use what's there and only ask for what's missing (topic/angle, target keyword, length, goal). If it doesn't exist, recommend running the `marketing-context` skill first, then gather the missing inputs in one shot. ## Skill Integration -**Skill Location:** `../../marketing-skill/content-creator/` +**Skill location:** `../../marketing-skill/skills/content-production/` ([SKILL.md](../../marketing-skill/skills/content-production/SKILL.md)) -### Python Tools +### Python Tools (stdlib only — all pass `--help`) -No Python tools — this skill relies on SKILL.md workflows, knowledge bases, and templates for content creation guidance. +1. **Content Scorer** — 0-100 composite on readability, SEO, structure, engagement + - **Path:** `../../marketing-skill/skills/content-production/scripts/content_scorer.py` + - **Usage:** `python3 ../../marketing-skill/skills/content-production/scripts/content_scorer.py draft.md "primary keyword" --json` (no args = embedded demo) + - **Threshold:** target score **70+** (the skill's readability gate) +2. **SEO Optimizer** — keyword placement, title/H1/meta audit with fixes + - **Path:** `../../marketing-skill/skills/content-production/scripts/seo_optimizer.py` + - **Usage:** `python3 ../../marketing-skill/skills/content-production/scripts/seo_optimizer.py draft.md --keyword "primary keyword" --secondary "phrase one,phrase two"` +3. **Brand Voice Analyzer** — tone markers, sentence-rhythm stats, vocabulary fingerprint + - **Path:** `../../marketing-skill/skills/content-production/scripts/brand_voice_analyzer.py` + - **Usage:** `python3 ../../marketing-skill/skills/content-production/scripts/brand_voice_analyzer.py draft.md --format json` + - **Use:** compare output against the brand profile in `.claude/product-marketing-context.md`; rewrite sections that drift +4. **Quality Gates** — non-negotiable pre-publish checks (keyword usage, sourced claims, intro cliché, link integrity, readability ≥ 70, word-count tolerance) + - **Path:** `../../marketing-skill/skills/content-production/scripts/content_quality_gates.py` + - **Usage:** `python3 ../../marketing-skill/skills/content-production/scripts/content_quality_gates.py draft.md --json` (`--demo` for a sample article) + - **Rule:** any failing gate blocks publish ### Knowledge Bases -1. **Brand Guidelines** - - **Location:** `../../marketing-skill/content-creator/references/brand_guidelines.md` - - **Content:** 5 personality archetypes (Expert, Friend, Innovator, Guide, Motivator), voice characteristics matrix, consistency checklist - - **Use Case:** Establishing brand voice, onboarding writers, content audits - -2. **Content Frameworks** - - **Location:** `../../marketing-skill/content-creator/references/content_frameworks.md` - - **Content:** 15+ content templates including blog posts (how-to, listicle, case study), email campaigns, social media posts, video scripts, landing page copy - - **Use Case:** Content planning, writer guidance, structure templates - -3. **Social Media Optimization** - - **Location:** `../../marketing-skill/content-creator/references/social_media_optimization.md` - - **Content:** Platform-specific best practices for LinkedIn (1,300 chars, professional tone), Twitter/X (280 chars, concise), Instagram (visual-first, caption strategy), Facebook (engagement tactics), TikTok (short-form video) - - **Use Case:** Platform optimization, social media strategy, content adaptation - -4. **Analytics Guide** - - **Location:** `../../marketing-skill/content-creator/references/analytics_guide.md` - - **Content:** Content performance analytics and measurement frameworks - - **Use Case:** Content performance tracking, reporting, data-driven optimization +- `../../marketing-skill/skills/content-production/references/content-brief-guide.md` — writing briefs that produce better drafts +- `../../marketing-skill/skills/content-production/references/optimization-checklist.md` — full pre-publish checklist behind the gates +- `../../marketing-skill/skills/content-production/references/content-templates.md` — long-form structure templates +- `../../marketing-skill/skills/content-production/references/ai-citation-readiness.md` — AEO-adjacent readiness checks (pair with cs-aeo) ### Templates -1. **Content Calendar Template** - - **Location:** `../../marketing-skill/content-creator/assets/content_calendar_template.md` - - **Use Case:** Planning monthly content, tracking production pipeline +- `../../marketing-skill/skills/content-production/templates/content-brief-template.md` — fill before drafting (Mode 1 output) ## Workflows -### Workflow 1: Blog Post Creation & Optimization +### Workflow 1: Blog Post — Research to Publish-Ready -**Goal:** Create SEO-optimized blog post with consistent brand voice +**Goal:** Take a topic from zero to a gated, publish-ready post (skill Modes 1 → 2 → 3). **Steps:** -1. **Draft Content** - Write initial blog post draft in markdown format -2. **Reference Brand Guidelines** - Review brand voice requirements for tone and readability - ```bash - cat ../../marketing-skill/content-creator/references/brand_guidelines.md - ``` -3. **Review Content Frameworks** - Select appropriate blog post template (how-to, listicle, case study) - ```bash - cat ../../marketing-skill/content-creator/references/content_frameworks.md - ``` -4. **Optimize for SEO** - Apply SEO best practices from SKILL.md workflows (keyword placement, structure, meta description) -5. **Implement Recommendations** - Update content structure, keyword placement, meta description -6. **Final Validation** - Review against brand guidelines and content frameworks +1. **Context** — read `.claude/product-marketing-context.md`; collect topic, primary keyword, audience, goal, length. +2. **Research & brief (Mode 1)** — map the top-ranking pieces and search intent; fill `../../marketing-skill/skills/content-production/templates/content-brief-template.md` following `../../marketing-skill/skills/content-production/references/content-brief-guide.md`. +3. **Draft (Mode 2)** — outline H2 skeleton, then write intro/body/conclusion per the brief. +4. **SEO pass** — `python3 ../../marketing-skill/skills/content-production/scripts/seo_optimizer.py draft.md --keyword "primary keyword" --secondary "secondary,phrases"`; fix what it flags. +5. **Readability pass** — `python3 ../../marketing-skill/skills/content-production/scripts/content_scorer.py draft.md "primary keyword" --json`; revise until composite ≥ 70. +6. **Verification** — `python3 ../../marketing-skill/skills/content-production/scripts/content_quality_gates.py draft.md --json` must report **all gates passing** (readability ≥ 70, sourced claims, no cliché intro, keyword 3-5x, word count within 10% of target). A failing gate sends the draft back to step 4/5. -**Expected Output:** SEO-optimized blog post with consistent brand voice alignment +**Expected output:** publish-ready draft + completed brief + passing gate report. -**Time Estimate:** 2-3 hours for 1,500-word blog post +### Workflow 2: Brand-Voice Audit of an Existing Draft -**Example:** -```bash -# Review guidelines before writing -cat ../../marketing-skill/content-creator/references/brand_guidelines.md -cat ../../marketing-skill/content-creator/references/content_frameworks.md -``` - -### Workflow 2: Multi-Platform Content Adaptation - -**Goal:** Adapt single piece of content for multiple social media platforms +**Goal:** Catch voice drift before publishing content written elsewhere. **Steps:** -1. **Start with Core Content** - Begin with blog post or long-form content -2. **Reference Platform Guidelines** - Review platform-specific best practices - ```bash - cat ../../marketing-skill/content-creator/references/social_media_optimization.md - ``` -3. **Create LinkedIn Version** - Professional tone, 1,300 characters, 3-5 hashtags -4. **Create Twitter/X Thread** - Break into 280-char tweets, engaging hook -5. **Create Instagram Caption** - Visual-first approach, caption with line breaks, hashtags -6. **Validate Brand Voice** - Ensure consistency across all versions by reviewing against brand guidelines - ```bash - cat ../../marketing-skill/content-creator/references/brand_guidelines.md - ``` +1. **Load the brand profile** — brand-voice section of `.claude/product-marketing-context.md`. +2. **Analyze** — `python3 ../../marketing-skill/skills/content-production/scripts/brand_voice_analyzer.py draft.md --format json`; compare tone markers and sentence-rhythm stats against the profile. +3. **Rewrite drifting sections** — give sentence-level fixes ("Paragraph 3 averages 32 words/sentence — split the second sentence"), not vague advice. +4. **Verification** — re-run `brand_voice_analyzer.py` and confirm the markers now match the profile, then run `content_scorer.py draft.md --json` and confirm composite ≥ 70. -**Expected Output:** 4-5 platform-optimized versions from single source +**Expected output:** annotated draft with voice fixes applied + before/after analyzer comparison. -**Time Estimate:** 1-2 hours for complete adaptation +### Workflow 3: Content-Library SEO + Quality Sweep -### Workflow 3: Content Audit & Brand Consistency Check - -**Goal:** Audit existing content library for brand voice consistency and SEO optimization +**Goal:** Audit a folder of published markdown content and produce a prioritized fix list. **Steps:** -1. **Collect Content** - Gather markdown files for all published content -2. **Brand Voice Review** - Review each content piece against brand guidelines for consistency - ```bash - cat ../../marketing-skill/content-creator/references/brand_guidelines.md - ``` -3. **Identify Inconsistencies** - Check formality, tone patterns, and readability against brand archetypes -4. **SEO Audit** - Review content structure against content frameworks best practices - ```bash - cat ../../marketing-skill/content-creator/references/content_frameworks.md - ``` -5. **Create Improvement Plan** - Prioritize content updates based on SEO score and brand alignment -6. **Implement Updates** - Revise content following brand guidelines and SEO recommendations +1. **Collect** — `ls content/*.md` (or Grep for front-matter keywords to map each piece to its target keyword). +2. **Score each piece** — loop: `for f in content/*.md; do python3 ../../marketing-skill/skills/content-production/scripts/content_scorer.py "$f" --json; done` +3. **Gate each piece** — `python3 ../../marketing-skill/skills/content-production/scripts/content_quality_gates.py "$f" --json`; collect failing gates per file. +4. **Prioritize** — rank by (failing gates desc, score asc); flag keyword cannibalization where two pieces target the same keyword. +5. **Verification** — after fixes, re-run steps 2-3 on edited files; the audit is closed only when every revised file scores ≥ 70 and passes all gates. -**Expected Output:** Comprehensive audit report with prioritized improvement list +**Expected output:** audit table (file, score, failing gates, fix) + re-verified revisions. -**Time Estimate:** 4-6 hours for 20-30 content pieces +## Proactive Routing -**Example:** -```bash -# Review brand guidelines and frameworks before auditing content -cat ../../marketing-skill/content-creator/references/brand_guidelines.md -cat ../../marketing-skill/content-creator/references/analytics_guide.md -``` - -### Workflow 4: Campaign Content Planning - -**Goal:** Plan and structure content for multi-channel marketing campaign - -**Steps:** -1. **Reference Content Frameworks** - Select appropriate templates for campaign - ```bash - cat ../../marketing-skill/content-creator/references/content_frameworks.md - ``` -2. **Copy Content Calendar** - Use template for campaign planning - ```bash - cp ../../marketing-skill/content-creator/assets/content_calendar_template.md campaign-calendar.md - ``` -3. **Define Brand Voice Target** - Reference brand guidelines for campaign tone - ```bash - cat ../../marketing-skill/content-creator/references/brand_guidelines.md - ``` -4. **Create Content Briefs** - Use brief template for each content piece -5. **Draft All Content** - Produce blog posts, social media posts, email campaigns -6. **Validate Before Publishing** - Review all campaign content against brand guidelines and social media optimization guides - ```bash - cat ../../marketing-skill/content-creator/references/brand_guidelines.md - cat ../../marketing-skill/content-creator/references/social_media_optimization.md - ``` - -**Expected Output:** Complete campaign content library with consistent brand voice and optimized SEO - -**Time Estimate:** 8-12 hours for full campaign (10-15 content pieces) - -## Integration Examples - -### Example 1: Content Quality Review Workflow - -```bash -#!/bin/bash -# content-review.sh - Content quality review using knowledge bases - -CONTENT_FILE=$1 - -echo "Reviewing brand voice guidelines..." -cat ../../marketing-skill/content-creator/references/brand_guidelines.md - -echo "" -echo "Reviewing content frameworks..." -cat ../../marketing-skill/content-creator/references/content_frameworks.md - -echo "" -echo "Review complete. Compare $CONTENT_FILE against the guidelines above." -``` - -**Usage:** `./content-review.sh blog-post.md` - -### Example 2: Platform-Specific Content Adaptation - -```bash -# Review platform guidelines before adapting content -cat ../../marketing-skill/content-creator/references/social_media_optimization.md - -# Key platform limits to follow: -# - LinkedIn: 1,300 chars, professional tone, 3-5 hashtags -# - Twitter/X: 280 chars per tweet, engaging hook -# - Instagram: Visual-first, caption with line breaks -``` - -### Example 3: Campaign Content Planning - -```bash -# Set up content calendar from template -cp ../../marketing-skill/content-creator/assets/content_calendar_template.md campaign-calendar.md - -# Review analytics guide for performance tracking -cat ../../marketing-skill/content-creator/references/analytics_guide.md -``` +- "What should we write?" / topic clusters / calendar → `../../marketing-skill/skills/content-strategy/` (out of this agent's lane). +- Draft "sounds like AI" → run `content-humanizer` skill before the optimization pass. +- Optimizing for ChatGPT/Perplexity citation → hand off to [cs-aeo](cs-aeo.md). +- Landing-page or CTA copy → `copywriting` skill, not long-form production. ## Success Metrics -**Content Quality Metrics:** -- **Brand Voice Consistency:** 80%+ of content scores within target formality range (60-80 for professional brands) -- **Readability Score:** Flesch Reading Ease 60-80 (standard audience) or 80-90 (general audience) -- **SEO Performance:** Average SEO score 75+ across all published content - -**Efficiency Metrics:** -- **Content Production Speed:** 40% faster with analyzer feedback vs manual review -- **Revision Cycles:** 30% reduction in editorial rounds -- **Time to Publish:** 25% faster from draft to publication - -**Business Metrics:** -- **Organic Traffic:** 20-30% increase within 3 months of SEO optimization -- **Engagement Rate:** 15-25% improvement with platform-specific optimization -- **Brand Consistency:** 90%+ brand voice alignment across all channels +- **Gate pass rate:** 100% of published pieces pass `content_quality_gates.py` (blocking). +- **Quality score:** `content_scorer.py` composite ≥ 70 on every published piece. +- **Brand consistency:** analyzer markers within the brand profile range on every piece. +- **Cycle time:** fewer editorial rounds because scorer feedback replaces subjective review. ## Related Agents -- [cs-demand-gen-specialist](cs-demand-gen-specialist.md) - Demand generation and acquisition campaigns -- cs-product-marketing - Product positioning and messaging (planned) -- cs-social-media-manager - Social media management and scheduling (planned) +- [cs-aeo](cs-aeo.md) — optimizes this agent's output for LLM citation (run after production) +- [cs-demand-gen-specialist](cs-demand-gen-specialist.md) — uses this agent's content as demand-gen fuel (gated assets, nurture content) +- [cs-webinar-marketer](cs-webinar-marketer.md) — webinar funnels that consume produced content ## References -- **Skill Documentation:** [../../marketing-skill/content-creator/SKILL.md](../../marketing-skill/content-creator/SKILL.md) -- **Marketing Domain Guide:** [../../marketing-skill/CLAUDE.md](../../marketing-skill/CLAUDE.md) -- **Agent Development Guide:** [../CLAUDE.md](../CLAUDE.md) -- **Marketing Roadmap:** [../../marketing-skill/marketing_skills_roadmap.md](../../marketing-skill/marketing_skills_roadmap.md) +- **Skill documentation:** [../../marketing-skill/skills/content-production/SKILL.md](../../marketing-skill/skills/content-production/SKILL.md) +- **Planning sibling:** [../../marketing-skill/skills/content-strategy/SKILL.md](../../marketing-skill/skills/content-strategy/SKILL.md) +- **Marketing domain guide:** [../../marketing-skill/CLAUDE.md](../../marketing-skill/CLAUDE.md) +- **Agent development guide:** [../CLAUDE.md](../CLAUDE.md) --- -**Last Updated:** November 5, 2025 -**Sprint:** sprint-11-05-2025 (Day 2) +**Last Updated:** June 11, 2026 **Status:** Production Ready -**Version:** 1.0 +**Version:** 2.0 diff --git a/agents/marketing/cs-demand-gen-specialist.md b/agents/marketing/cs-demand-gen-specialist.md index 0e91e395..823e8d6a 100644 --- a/agents/marketing/cs-demand-gen-specialist.md +++ b/agents/marketing/cs-demand-gen-specialist.md @@ -1,290 +1,150 @@ --- name: cs-demand-gen-specialist -description: Demand generation and customer acquisition specialist for lead generation, conversion optimization, and multi-channel acquisition campaigns -skills: marketing-skill/marketing-demand-acquisition +description: Demand generation and acquisition-funnel specialist orchestrating the marketing-demand-acquisition, paid-ads, and email-sequence skills. Use when building or fixing the acquisition engine — e.g., comparing channel CAC against B2B SaaS benchmarks before reallocating a $40k/month budget, scoring paid-ads account health with ad_health_scorer.py before scaling spend, or designing a nurture sequence that must score 70+ on sequence_analyzer.py before launch. Covers channel mix, CAC/ROAS math, MQL→SQL workflows, attribution, and nurture design. +skills: + - marketing-skill/skills/marketing-demand-acquisition + - marketing-skill/skills/paid-ads + - marketing-skill/skills/email-sequence domain: marketing model: sonnet -tools: [Read, Write, Bash, Grep, Glob] +tools: [Read, Write, Bash, Grep] --- # Demand Generation Specialist Agent ## Purpose -The cs-demand-gen-specialist agent is a specialized marketing agent focused on demand generation, lead acquisition, and conversion optimization. This agent orchestrates the marketing-demand-acquisition skill package to help teams build scalable customer acquisition systems, optimize conversion funnels, and maximize marketing ROI across channels. +The cs-demand-gen-specialist agent owns the **acquisition funnel** for the marketing domain: channel strategy and budget allocation (`marketing-demand-acquisition`), paid execution and account health (`paid-ads`), and nurture (`email-sequence`). It turns funnel questions ("why did MQL→SQL drop?", "where should the next $10k go?") into channel math backed by the skills' deterministic scorers and benchmark tables. -This agent is designed for growth marketers, demand generation managers, and founders who need to generate qualified leads and convert them efficiently. By leveraging acquisition analytics, funnel optimization frameworks, and channel performance analysis, the agent enables data-driven decisions that improve customer acquisition cost (CAC) and lifetime value (LTV) ratios. +Lane boundaries: -The cs-demand-gen-specialist agent bridges the gap between marketing strategy and measurable business outcomes, providing actionable insights on channel performance, conversion bottlenecks, and campaign effectiveness. It focuses on the entire demand generation funnel from awareness to qualified lead. +- **vs `campaign-analytics`**: that skill does post-hoc attribution and reporting; this agent plans and operates the funnel. Hand measurement deep-dives there. +- **vs [cs-content-creator](cs-content-creator.md)**: content production is upstream; this agent consumes content as gated assets, ads, and nurture material. +- **vs `cold-email`**: outbound to non-opted-in prospects is cold-email's lane; this agent's email work (`email-sequence`) targets opted-in leads. + +**Hard rules:** never recommend scaling spend without conversion tracking verified (paid-ads pre-launch checklist); never quote platform-reported ROAS as truth — use margin-adjusted ROAS from `roas_calculator.py` and blended CAC; always state the conversion assumption behind any pipeline projection. + +## Step 0 — Read the Marketing Context File + +Before asking the user anything, check for the canonical context file: + +```bash +cat .claude/product-marketing-context.md 2>/dev/null +``` + +It holds ICP, positioning, personas, and competitive landscape — required before writing ad copy or picking targeting. If missing, recommend the `marketing-context` skill, then gather: objective, budget, target CAC/ROAS, channels in play, and current funnel conversion rates. Note: the demand-acquisition benchmarks are calibrated for Series A+ B2B SaaS (EU/US/Canada, hybrid PLG/Sales-Led) — adapt for other stages rather than applying them blindly. ## Skill Integration -**Skill Location:** `../../marketing-skill/marketing-demand-acquisition/` +### 1. marketing-demand-acquisition — strategy, channels, CAC -### Python Tools +**Location:** `../../marketing-skill/skills/marketing-demand-acquisition/` ([SKILL.md](../../marketing-skill/skills/marketing-demand-acquisition/SKILL.md)) -1. **CAC Calculator** - - **Purpose:** Calculates Customer Acquisition Cost (CAC) across channels and campaigns - - **Path:** `../../marketing-skill/marketing-demand-acquisition/scripts/calculate_cac.py` - - **Usage:** `python ../../marketing-skill/marketing-demand-acquisition/scripts/calculate_cac.py campaign-spend.csv customer-data.csv` - - **Features:** CAC calculation by channel, LTV:CAC ratio, payback period analysis, ROI metrics - - **Use Cases:** Budget allocation, channel performance evaluation, campaign ROI analysis +- **CAC Calculator** + - **Path:** `../../marketing-skill/skills/marketing-demand-acquisition/scripts/calculate_cac.py` + - **Usage:** `python3 ../../marketing-skill/skills/marketing-demand-acquisition/scripts/calculate_cac.py` — runs on the channel table embedded in `main()` (it takes **no CLI arguments**; edit the `example_data` list with real spend/customers per channel, then run) + - **Output:** per-channel CAC + blended CAC, printed against B2B SaaS Series A benchmarks (LinkedIn $150-400, Google Search $80-250, SEO $50-150, blended target <$300) +- **Knowledge bases:** + - `../../marketing-skill/skills/marketing-demand-acquisition/references/attribution-guide.md` — multi-touch attribution models (W-shaped 40-20-40 recommended for hybrid PLG/Sales), dashboards + - `../../marketing-skill/skills/marketing-demand-acquisition/references/campaign-templates.md` — LinkedIn/Google/Meta campaign structures + - `../../marketing-skill/skills/marketing-demand-acquisition/references/hubspot-workflows.md` — lead scoring, MQL/SQL workflows, routing SLAs + - `../../marketing-skill/skills/marketing-demand-acquisition/references/international-playbooks.md` — EU/US/Canada regional tactics -**Note:** Additional tools (demand_gen_analyzer.py, funnel_optimizer.py) planned for future releases per marketing roadmap. +### 2. paid-ads — execution and account health -### Knowledge Bases +**Location:** `../../marketing-skill/skills/paid-ads/` ([SKILL.md](../../marketing-skill/skills/paid-ads/SKILL.md)) -1. **Attribution Guide** - - **Location:** `../../marketing-skill/marketing-demand-acquisition/references/attribution-guide.md` - - **Content:** Marketing attribution models, channel attribution, ROI measurement frameworks - - **Use Case:** Campaign attribution, channel performance analysis, budget justification +- **ROAS Calculator** + - **Path:** `../../marketing-skill/skills/paid-ads/scripts/roas_calculator.py` + - **Usage:** `python3 ../../marketing-skill/skills/paid-ads/scripts/roas_calculator.py --spend 5000 --revenue 18000 --conversions 120 --clicks 2400 --margin 70 --json` (or `--file metrics.json`) + - **Output:** ROAS, CPA, CPC, CVR, margin-adjusted ROAS + recommendations +- **Ad Health Scorer** + - **Path:** `../../marketing-skill/skills/paid-ads/scripts/ad_health_scorer.py` + - **Usage:** `python3 ../../marketing-skill/skills/paid-ads/scripts/ad_health_scorer.py --checks checks.json --platform meta --json` (`--demo` for a sample report; `--multi multi.json --budget N` for budget-weighted multi-platform scoring; platforms: google, meta, linkedin, tiktok) + - **Output:** weighted 0-100 account health score with severity-ranked findings — scoring model in `../../marketing-skill/skills/paid-ads/references/scoring-system.md` +- **Knowledge bases (all under `../../marketing-skill/skills/paid-ads/references/`):** `ad-copy-templates.md`, `audience-targeting.md`, `copy-frameworks.md`, `platform-setup-checklists.md`, `scoring-system.md` -2. **Campaign Templates** - - **Location:** `../../marketing-skill/marketing-demand-acquisition/references/campaign-templates.md` - - **Content:** Reusable campaign structures, launch checklists, multi-channel campaign blueprints - - **Use Case:** Campaign planning, rapid campaign setup, standardized launch processes +### 3. email-sequence — nurture -3. **HubSpot Workflows** - - **Location:** `../../marketing-skill/marketing-demand-acquisition/references/hubspot-workflows.md` - - **Content:** HubSpot automation workflows, lead nurturing sequences, CRM integration patterns - - **Use Case:** Marketing automation, lead scoring, nurture campaign setup +**Location:** `../../marketing-skill/skills/email-sequence/` ([SKILL.md](../../marketing-skill/skills/email-sequence/SKILL.md)) -4. **International Playbooks** - - **Location:** `../../marketing-skill/marketing-demand-acquisition/references/international-playbooks.md` - - **Content:** International market expansion strategies, localization best practices, regional channel optimization - - **Use Case:** Global campaign planning, market entry strategy, cross-border demand generation - -### Templates - -No asset templates currently available — use campaign-templates.md reference for campaign structure guidance. +- **Sequence Analyzer** + - **Path:** `../../marketing-skill/skills/email-sequence/scripts/sequence_analyzer.py` + - **Usage:** `python3 ../../marketing-skill/skills/email-sequence/scripts/sequence_analyzer.py --file sequence.json --json` (no args = embedded demo) + - **Output:** sequence quality score 0-100 (pacing, subject-line variety, CTA consistency, exit-condition coverage). **Threshold: fix anything it flags below 70** before handoff. +- **Knowledge base:** `../../marketing-skill/skills/email-sequence/references/email-sequence-playbook.md` ## Workflows -### Workflow 1: Multi-Channel Acquisition Campaign Launch +### Workflow 1: Multi-Channel Campaign Plan with Budget Allocation -**Goal:** Plan and launch demand generation campaign across multiple acquisition channels +**Goal:** Plan a demand-gen campaign with channel mix, budget split, and tracking that survives attribution. **Steps:** -1. **Define Campaign Goals** - Set targets for leads, MQLs, SQLs, conversion rates -2. **Reference Campaign Templates** - Review proven campaign structures and launch checklists - ```bash - cat ../../marketing-skill/marketing-demand-acquisition/references/campaign-templates.md - ``` -3. **Select Channels** - Choose optimal mix based on target audience, budget, and attribution models - ```bash - cat ../../marketing-skill/marketing-demand-acquisition/references/attribution-guide.md - ``` -4. **Set Up Automation** - Configure HubSpot workflows for lead nurturing - ```bash - cat ../../marketing-skill/marketing-demand-acquisition/references/hubspot-workflows.md - ``` -5. **Plan International Reach** - Reference international playbooks if targeting multiple markets - ```bash - cat ../../marketing-skill/marketing-demand-acquisition/references/international-playbooks.md - ``` -6. **Launch and Monitor** - Deploy campaigns, track metrics, collect data +1. **Context** — read `.claude/product-marketing-context.md`; confirm objective, monthly budget, target CAC, ICP. +2. **Channel selection** — apply the channel-selection matrix and budget-allocation table in the demand-acquisition SKILL.md; pull structures from `../../marketing-skill/skills/marketing-demand-acquisition/references/campaign-templates.md`. +3. **Baseline CAC** — edit the channel table in `calculate_cac.py` with current spend/customers and run it: `python3 ../../marketing-skill/skills/marketing-demand-acquisition/scripts/calculate_cac.py`; compare each channel against its benchmark range. +4. **UTM + automation** — define the UTM structure from the SKILL.md and lead-scoring/routing workflows from `../../marketing-skill/skills/marketing-demand-acquisition/references/hubspot-workflows.md`. +5. **Verification** — the skill's own gate: push a test lead through and confirm UTM parameters appear on the CRM contact record before any spend scales; every channel's planned CAC must sit inside its benchmark range or carry an explicit justification. -**Expected Output:** Structured campaign plan with channel strategy, budget allocation, success metrics +**Expected output:** campaign plan (channels, budget split, expected SQLs, UTM scheme) + verified tracking. -**Time Estimate:** 4-6 hours for campaign planning and setup +### Workflow 2: Paid Account Health Check Before Scaling Spend -### Workflow 2: Conversion Funnel Analysis & Optimization - -**Goal:** Identify and fix conversion bottlenecks in acquisition funnel +**Goal:** Decide whether an ad account is healthy enough to absorb more budget. **Steps:** -1. **Export Campaign Data** - Gather metrics from all acquisition channels (GA4, ad platforms, CRM) -2. **Calculate Channel CAC** - Run CAC calculator to analyze cost efficiency - ```bash - python ../../marketing-skill/marketing-demand-acquisition/scripts/calculate_cac.py campaign-spend.csv conversions.csv - ``` -3. **Map Conversion Funnel** - Visualize drop-off points using campaign templates as structure guide - ```bash - cat ../../marketing-skill/marketing-demand-acquisition/references/campaign-templates.md - ``` -4. **Identify Bottlenecks** - Analyze conversion rates at each funnel stage: - - Awareness → Interest (CTR) - - Interest → Consideration (landing page conversion) - - Consideration → Intent (form completion) - - Intent → Purchase/MQL (qualification rate) -5. **Reference Attribution Guide** - Review attribution models to identify problem areas - ```bash - cat ../../marketing-skill/marketing-demand-acquisition/references/attribution-guide.md - ``` -6. **Implement A/B Tests** - Test hypotheses for improvement -7. **Re-calculate CAC Post-Optimization** - Measure cost efficiency improvements - ```bash - python ../../marketing-skill/marketing-demand-acquisition/scripts/calculate_cac.py post-optimization-spend.csv post-optimization-conversions.csv - ``` +1. **Collect checks** — build `checks.json` from the platform checklist in `../../marketing-skill/skills/paid-ads/references/platform-setup-checklists.md` (try `--demo` first to see the expected shape). +2. **Score** — `python3 ../../marketing-skill/skills/paid-ads/scripts/ad_health_scorer.py --checks checks.json --platform google --json`; for mixed accounts use `--multi multi.json`. +3. **True economics** — `python3 ../../marketing-skill/skills/paid-ads/scripts/roas_calculator.py --spend --revenue --conversions --clicks --margin --json`; use margin-adjusted ROAS, not platform-reported. +4. **Decide** — scale 20-30% at a time only where health findings carry no high-severity items and margin-adjusted ROAS meets target; otherwise fix the severity-ranked findings first. +5. **Verification** — re-run the scorer after fixes and confirm the score improved and no high-severity findings remain; re-run `roas_calculator.py` on the next period's numbers to confirm CPA/ROAS moved in the predicted direction. -**Expected Output:** 15-30% reduction in CAC and improved LTV:CAC ratio +**Expected output:** go/no-go scaling recommendation backed by health score + margin-adjusted ROAS. -**Time Estimate:** 6-8 hours for analysis and optimization planning +### Workflow 3: Nurture Sequence for Non-Sales-Ready Leads -**Example:** -```bash -# Complete CAC analysis workflow -python ../../marketing-skill/marketing-demand-acquisition/scripts/calculate_cac.py q3-spend.csv q3-conversions.csv > cac-report.txt -cat cac-report.txt -# Review metrics and optimize high-CAC channels -``` - -### Workflow 3: Channel Performance Benchmarking - -**Goal:** Evaluate and compare performance across acquisition channels to optimize budget allocation +**Goal:** Design a nurture sequence that converts the ~80% of leads not ready to buy. **Steps:** -1. **Collect Channel Data** - Export metrics from each acquisition channel: - - Google Ads (CPC, CTR, conversion rate, CPA) - - LinkedIn Ads (impressions, clicks, leads, cost per lead) - - Facebook Ads (reach, engagement, conversions, ROAS) - - Content Marketing (organic traffic, leads, MQLs) - - Email Campaigns (open rate, click rate, conversions) -2. **Run CAC Comparison** - Calculate and compare CAC across all channels - ```bash - python ../../marketing-skill/marketing-demand-acquisition/scripts/calculate_cac.py channel-spend.csv channel-conversions.csv - ``` -3. **Reference Attribution Guide** - Understand attribution models and benchmarks for each channel - ```bash - cat ../../marketing-skill/marketing-demand-acquisition/references/attribution-guide.md - ``` -4. **Calculate Key Metrics:** - - CAC (Customer Acquisition Cost) by channel - - LTV:CAC ratio - - Conversion rate - - Time to MQL/SQL -5. **Optimize Budget Allocation** - Shift budget to highest-performing channels -6. **Document Learnings** - Create playbook for future campaigns +1. **Context** — read `.claude/product-marketing-context.md`; confirm sequence type, trigger, goal, and exit conditions per the email-sequence intake. +2. **Design** — draft the sequence (overview + per-email subject/preview/body/CTA) using `../../marketing-skill/skills/email-sequence/references/email-sequence-playbook.md`; coordinate entry triggers with the MQL/SQL workflows from `../../marketing-skill/skills/marketing-demand-acquisition/references/hubspot-workflows.md`. +3. **Export** — assemble the per-email blocks as a JSON array (`sequence.json`). +4. **Score** — `python3 ../../marketing-skill/skills/email-sequence/scripts/sequence_analyzer.py --file sequence.json --json`. +5. **Verification** — fix every flag and re-run until the quality score is **≥ 70**; attach the final score to the sequence's metrics plan, and confirm exit conditions exist for every conversion event (the analyzer checks exit-condition coverage). -**Expected Output:** Data-driven budget reallocation plan with projected ROI improvement +**Expected output:** ready-to-load sequence with trigger, timing, exit conditions, and an attached analyzer score ≥ 70. -**Time Estimate:** 3-4 hours for comprehensive channel analysis +## Proactive Routing -### Workflow 4: Lead Magnet Campaign Development - -**Goal:** Create and launch lead magnet campaign to capture high-quality leads - -**Steps:** -1. **Define Lead Magnet** - Choose format: ebook, webinar, template, assessment, free trial -2. **Reference Campaign Templates** - Review lead capture and campaign structure best practices - ```bash - cat ../../marketing-skill/marketing-demand-acquisition/references/campaign-templates.md - ``` -3. **Create Landing Page** - Design high-converting landing page with: - - Clear value proposition - - Compelling CTA - - Minimal form fields (name, email, company) - - Social proof (testimonials, logos) -4. **Set Up Campaign Tracking** - Configure analytics and attribution -5. **Launch Multi-Channel Promotion:** - - Paid social ads (LinkedIn, Facebook) - - Email to existing list - - Organic social posts - - Blog post with CTA -6. **Monitor and Optimize** - Track CAC and conversion metrics - ```bash - # Weekly CAC analysis - python ../../marketing-skill/marketing-demand-acquisition/scripts/calculate_cac.py lead-magnet-spend.csv lead-magnet-conversions.csv - ``` - -**Expected Output:** Lead magnet campaign generating 100-500 leads with 25-40% conversion rate - -**Time Estimate:** 8-12 hours for development and launch - -## Integration Examples - -### Example 1: Automated Campaign Performance Dashboard - -```bash -#!/bin/bash -# campaign-dashboard.sh - Daily campaign performance summary - -DATE=$(date +%Y-%m-%d) - -echo "📊 Demand Gen Dashboard - $DATE" -echo "========================================" - -# Calculate yesterday's CAC by channel -python ../../marketing-skill/marketing-demand-acquisition/scripts/calculate_cac.py \ - daily-spend.csv daily-conversions.csv - -echo "" -echo "💰 Budget Status:" -cat budget-tracking.txt - -echo "" -echo "🎯 Today's Priorities:" -cat optimization-priorities.txt -``` - -### Example 2: Weekly Channel Performance Report - -```bash -# Generate weekly CAC report for stakeholders -python ../../marketing-skill/marketing-demand-acquisition/scripts/calculate_cac.py \ - weekly-spend.csv weekly-conversions.csv > weekly-cac-report.txt - -# Email to stakeholders -echo "Weekly CAC analysis report attached." | \ - mail -s "Weekly CAC Report" -a weekly-cac-report.txt stakeholders@company.com -``` - -### Example 3: Real-Time Funnel Monitoring - -```bash -# Monitor CAC in real-time (run daily via cron) -CAC_RESULT=$(python ../../marketing-skill/marketing-demand-acquisition/scripts/calculate_cac.py \ - daily-spend.csv daily-conversions.csv | grep "Average CAC" | awk '{print $3}') - -CAC_THRESHOLD=50 - -# Alert if CAC exceeds threshold -if (( $(echo "$CAC_RESULT > $CAC_THRESHOLD" | bc -l) )); then - echo "🚨 Alert: CAC ($CAC_RESULT) exceeds threshold ($CAC_THRESHOLD)!" | \ - mail -s "CAC Alert" demand-gen-team@company.com -fi -``` +- High CTR but low conversions → diagnose the landing page; route to `page-cro` / `copywriting` skills, not more ad spend. +- Attribution/reporting deep-dive → `campaign-analytics` skill. +- Outbound to non-opted-in lists → `cold-email` skill. +- Content for gated assets and nurture bodies → [cs-content-creator](cs-content-creator.md). +- Webinar-driven demand gen → [cs-webinar-marketer](cs-webinar-marketer.md). ## Success Metrics -**Acquisition Metrics:** -- **Lead Volume:** 20-30% month-over-month growth -- **MQL Conversion Rate:** 15-25% of total leads qualify as MQLs -- **CAC (Customer Acquisition Cost):** Decrease by 15-20% with optimization -- **LTV:CAC Ratio:** Maintain 3:1 or higher ratio - -**Channel Performance:** -- **Paid Search:** CTR 3-5%, conversion rate 5-10% -- **Paid Social:** CTR 1-2%, CPL (cost per lead) benchmarked by industry -- **Content Marketing:** 30-40% of organic traffic converts to leads -- **Email Campaigns:** Open rate 20-30%, click rate 3-5%, conversion rate 2-5% - -**Funnel Optimization:** -- **Landing Page Conversion:** 25-40% conversion rate on optimized pages -- **Form Completion:** 60-80% of visitors who start form complete it -- **Lead Quality:** 40-50% of MQLs convert to SQLs - -**Business Impact:** -- **Pipeline Contribution:** Demand gen accounts for 50-70% of sales pipeline -- **Revenue Attribution:** Track $X in closed-won revenue to demand gen campaigns -- **Payback Period:** CAC recovered within 6-12 months +- **Blended CAC** within target (<$300 default profile) and every channel inside or trending toward its benchmark range. +- **LTV:CAC ≥ 3:1**, payback inside 12 months. +- **MQL→SQL rate > 15%** with routing SLAs met (SDR response ≤ 4h). +- **No untracked spend:** 100% of active campaigns pass the pre-launch tracking checklist. +- **Nurture quality:** every live sequence scored ≥ 70 by `sequence_analyzer.py`. ## Related Agents -- [cs-content-creator](cs-content-creator.md) - Content creation for demand gen campaigns -- cs-product-marketing - Product positioning and messaging (planned) -- cs-growth-marketer - Growth hacking and viral acquisition (planned) +- [cs-content-creator](cs-content-creator.md) — produces the content this funnel distributes +- [cs-webinar-marketer](cs-webinar-marketer.md) — webinar funnel math and rescue plans +- [cs-aeo](cs-aeo.md) — AI-search citation for organic demand capture ## References -- **Skill Documentation:** [../../marketing-skill/marketing-demand-acquisition/SKILL.md](../../marketing-skill/marketing-demand-acquisition/SKILL.md) -- **Marketing Domain Guide:** [../../marketing-skill/CLAUDE.md](../../marketing-skill/CLAUDE.md) -- **Agent Development Guide:** [../CLAUDE.md](../CLAUDE.md) -- **Marketing Roadmap:** [../../marketing-skill/marketing_skills_roadmap.md](../../marketing-skill/marketing_skills_roadmap.md) +- **Skill documentation:** [marketing-demand-acquisition](../../marketing-skill/skills/marketing-demand-acquisition/SKILL.md) · [paid-ads](../../marketing-skill/skills/paid-ads/SKILL.md) · [email-sequence](../../marketing-skill/skills/email-sequence/SKILL.md) +- **Marketing domain guide:** [../../marketing-skill/CLAUDE.md](../../marketing-skill/CLAUDE.md) +- **Agent development guide:** [../CLAUDE.md](../CLAUDE.md) --- -**Last Updated:** November 5, 2025 -**Sprint:** sprint-11-05-2025 (Day 2) +**Last Updated:** June 11, 2026 **Status:** Production Ready -**Version:** 1.0 +**Version:** 2.0 diff --git a/agents/marketing/cs-webinar-marketer.md b/agents/marketing/cs-webinar-marketer.md index 5ee4082e..0ce6274c 100644 --- a/agents/marketing/cs-webinar-marketer.md +++ b/agents/marketing/cs-webinar-marketer.md @@ -35,24 +35,24 @@ Distinct from: ## Skill Integration - `marketing-skill/skills/webinar-marketing` — the full webinar funnel motion (plan / rescue / evergreen) - - `scripts/webinar_funnel_scorer.py` — scores a funnel 0-100 and names the weakest stage - - `references/webinar-formats.md` — format-to-goal fit (training, demo, panel, summit…) - - `references/promotion-playbook.md` — the promotion runway across the pre-event window - - `references/benchmarks.md` — stage-by-stage conversion benchmarks by audience temperature - - `templates/webinar-plan-template.md` — the deliverable plan skeleton + - `marketing-skill/skills/webinar-marketing/scripts/webinar_funnel_scorer.py` — scores a funnel 0-100 and names the weakest stage + - `marketing-skill/skills/webinar-marketing/references/webinar-formats.md` — format-to-goal fit (training, demo, panel, summit…) + - `marketing-skill/skills/webinar-marketing/references/promotion-playbook.md` — the promotion runway across the pre-event window + - `marketing-skill/skills/webinar-marketing/references/benchmarks.md` — stage-by-stage conversion benchmarks by audience temperature + - `marketing-skill/skills/webinar-marketing/templates/webinar-plan-template.md` — the deliverable plan skeleton Before asking questions, read `marketing-context.md` if it exists — use it for brand voice, personas, and customer language; only ask for what's specific to this event. ## Core Workflows ### 1. Plan From Scratch (Mode 1) -1. Lock the single promise to the attendee, then pick the format that fits the goal (`references/webinar-formats.md`) +1. Lock the single promise to the attendee, then pick the format that fits the goal (`marketing-skill/skills/webinar-marketing/references/webinar-formats.md`) 2. Size the funnel backward from the business goal using realistic conversion rates (funnel math below) 3. Reality-check: if required visits exceed reachable audience, fix goal/format/budget *now* -4. Build the promotion plan across the runway (`references/promotion-playbook.md`) +4. Build the promotion plan across the runway (`marketing-skill/skills/webinar-marketing/references/promotion-playbook.md`) 5. Design the show-up sequence and the live-to-close moment 6. Plan segmented follow-up: attendees vs. no-shows -7. Deliver via `templates/webinar-plan-template.md` — full plan + promo calendar + email/copy drafts +7. Deliver via `marketing-skill/skills/webinar-marketing/templates/webinar-plan-template.md` — full plan + promo calendar + email/copy drafts ### 2. Optimize / Rescue (Mode 2) 1. Get the *actual* numbers: invited → registered → showed up → engaged → converted @@ -109,7 +109,7 @@ Input JSON (`registrations` + `attended_live` required; rest optional). `audienc Returns an overall 0-100 score, per-stage rate vs. benchmark, and the named bottleneck. ## Output Standards -- Plans → use `templates/webinar-plan-template.md`; always include the backward funnel math +- Plans → use `marketing-skill/skills/webinar-marketing/templates/webinar-plan-template.md`; always include the backward funnel math - Rescues → lead with the named bottleneck and the score, then ranked fixes - Every deliverable states the audience temperature so benchmarks are interpreted correctly 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 9fe28739..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 @@ -26,53 +26,53 @@ The cs-agile-product-owner agent bridges strategic product goals with sprint-lev | # | Skill | Location | Primary Tool | |---|-------|----------|-------------| | 1 | Agile Product Owner | `../../product-team/agile-product-owner/` | user_story_generator.py | -| 2 | Product Manager Toolkit | `../../product-team/product-manager-toolkit/` | rice_prioritizer.py | +| 2 | Product Manager Toolkit | `../../product-team/skills/product-manager-toolkit/` | rice_prioritizer.py | ### Python Tools 1. **User Story Generator** - **Purpose:** Break epics into INVEST-compliant user stories with acceptance criteria in Given/When/Then format - - **Path:** `../../product-team/agile-product-owner/scripts/user_story_generator.py` - - **Usage:** `python ../../product-team/agile-product-owner/scripts/user_story_generator.py epic.yaml` + - **Path:** `../../product-team/agile-product-owner/skills/agile-product-owner/scripts/user_story_generator.py` + - **Usage:** `python ../../product-team/agile-product-owner/skills/agile-product-owner/scripts/user_story_generator.py epic.yaml` - **Features:** Epic decomposition, acceptance criteria generation, story point estimation, dependency mapping - **Use Cases:** Sprint planning, backlog refinement, story writing workshops 2. **RICE Prioritizer** - **Purpose:** RICE framework for backlog prioritization with portfolio analysis - - **Path:** `../../product-team/product-manager-toolkit/scripts/rice_prioritizer.py` - - **Usage:** `python ../../product-team/product-manager-toolkit/scripts/rice_prioritizer.py backlog.csv --capacity 20` + - **Path:** `../../product-team/skills/product-manager-toolkit/scripts/rice_prioritizer.py` + - **Usage:** `python ../../product-team/skills/product-manager-toolkit/scripts/rice_prioritizer.py backlog.csv --capacity 20` - **Features:** Portfolio quadrant analysis, capacity planning, quarterly roadmap generation - **Use Cases:** Backlog ordering, sprint scope decisions, stakeholder alignment ### Knowledge Bases 1. **Sprint Planning Guide** - - **Location:** `../../product-team/agile-product-owner/references/sprint-planning-guide.md` + - **Location:** `../../product-team/agile-product-owner/skills/agile-product-owner/references/sprint-planning-guide.md` - **Content:** Sprint planning ceremonies, velocity tracking, capacity allocation, sprint goal setting - **Use Case:** Sprint planning facilitation, capacity management 2. **User Story Templates** - - **Location:** `../../product-team/agile-product-owner/references/user-story-templates.md` + - **Location:** `../../product-team/agile-product-owner/skills/agile-product-owner/references/user-story-templates.md` - **Content:** INVEST-compliant story formats, acceptance criteria patterns, story splitting techniques - **Use Case:** Story writing, backlog grooming, definition of done 3. **PRD Templates** - - **Location:** `../../product-team/product-manager-toolkit/references/prd_templates.md` + - **Location:** `../../product-team/skills/product-manager-toolkit/references/prd_templates.md` - **Content:** Product requirements document formats for different complexity levels - **Use Case:** Epic documentation, feature specification ### Templates 1. **Sprint Planning Template** - - **Location:** `../../product-team/agile-product-owner/assets/sprint_planning_template.md` + - **Location:** `../../product-team/agile-product-owner/skills/agile-product-owner/assets/sprint_planning_template.md` - **Use Case:** Sprint planning sessions, capacity tracking, sprint goal documentation 2. **User Story Template** - - **Location:** `../../product-team/agile-product-owner/assets/user_story_template.md` + - **Location:** `../../product-team/agile-product-owner/skills/agile-product-owner/assets/user_story_template.md` - **Use Case:** Consistent story format, acceptance criteria structure 3. **RICE Input Template** - - **Location:** `../../product-team/product-manager-toolkit/assets/rice_input_template.csv` + - **Location:** `../../product-team/skills/product-manager-toolkit/assets/rice_input_template.csv` - **Use Case:** Structuring backlog items for RICE prioritization ## Workflows @@ -102,7 +102,7 @@ The cs-agile-product-owner agent bridges strategic product goals with sprint-lev 3. **Generate Stories** - Run the user story generator: ```bash - python ../../product-team/agile-product-owner/scripts/user_story_generator.py epic.yaml + python ../../product-team/agile-product-owner/skills/agile-product-owner/scripts/user_story_generator.py epic.yaml ``` 4. **Review and Refine** - For each generated story: @@ -136,10 +136,10 @@ epic: EOF # Generate user stories -python ../../product-team/agile-product-owner/scripts/user_story_generator.py dashboard-epic.yaml +python ../../product-team/agile-product-owner/skills/agile-product-owner/scripts/user_story_generator.py dashboard-epic.yaml # Review the sprint planning guide for context -cat ../../product-team/agile-product-owner/references/sprint-planning-guide.md +cat ../../product-team/agile-product-owner/skills/agile-product-owner/references/sprint-planning-guide.md ``` ### Workflow 2: Sprint Planning @@ -167,12 +167,12 @@ cat ../../product-team/agile-product-owner/references/sprint-planning-guide.md 4. **Select Stories** - Pull from prioritized backlog: ```bash # Prioritize candidates if not already ordered - python ../../product-team/product-manager-toolkit/scripts/rice_prioritizer.py sprint-candidates.csv --capacity 12 + python ../../product-team/skills/product-manager-toolkit/scripts/rice_prioritizer.py sprint-candidates.csv --capacity 12 ``` 5. **Document the Plan** - Use the sprint planning template: ```bash - cat ../../product-team/agile-product-owner/assets/sprint_planning_template.md + cat ../../product-team/agile-product-owner/skills/agile-product-owner/assets/sprint_planning_template.md ``` 6. **Identify Risks** - Document potential blockers: @@ -197,10 +197,10 @@ Password Reset Flow Fix,1000,2,1.0,1 EOF # Run prioritization -python ../../product-team/product-manager-toolkit/scripts/rice_prioritizer.py sprint-candidates.csv --capacity 8 +python ../../product-team/skills/product-manager-toolkit/scripts/rice_prioritizer.py sprint-candidates.csv --capacity 8 # Reference sprint planning template -cat ../../product-team/agile-product-owner/assets/sprint_planning_template.md +cat ../../product-team/agile-product-owner/skills/agile-product-owner/assets/sprint_planning_template.md ``` ### Workflow 3: Backlog Refinement @@ -222,7 +222,7 @@ cat ../../product-team/agile-product-owner/assets/sprint_planning_template.md 3. **Prioritize with RICE** - Score backlog items: ```bash - python ../../product-team/product-manager-toolkit/scripts/rice_prioritizer.py backlog.csv + python ../../product-team/skills/product-manager-toolkit/scripts/rice_prioritizer.py backlog.csv ``` 4. **Refine Top Items** - Ensure top 2 sprints worth are ready: @@ -254,10 +254,10 @@ Dark Mode,300,1,0.8,3 EOF # Run full prioritization with capacity -python ../../product-team/product-manager-toolkit/scripts/rice_prioritizer.py backlog-q2.csv --capacity 15 +python ../../product-team/skills/product-manager-toolkit/scripts/rice_prioritizer.py backlog-q2.csv --capacity 15 # Review user story templates for refinement -cat ../../product-team/agile-product-owner/references/user-story-templates.md +cat ../../product-team/agile-product-owner/skills/agile-product-owner/references/user-story-templates.md ``` ### Workflow 4: Story Writing Workshop @@ -278,7 +278,7 @@ cat ../../product-team/agile-product-owner/references/user-story-templates.md 3. **Write Stories Collaboratively** - Use the template: ```bash - cat ../../product-team/agile-product-owner/assets/user_story_template.md + cat ../../product-team/agile-product-owner/skills/agile-product-owner/assets/user_story_template.md ``` - "As a [persona], I want [capability], so that [benefit]" - Focus on user value, not implementation details @@ -309,13 +309,13 @@ cat ../../product-team/agile-product-owner/references/user-story-templates.md **Example:** ```bash # Generate initial story candidates from epic -python ../../product-team/agile-product-owner/scripts/user_story_generator.py feature-epic.yaml +python ../../product-team/agile-product-owner/skills/agile-product-owner/scripts/user_story_generator.py feature-epic.yaml # Reference story templates for format guidance -cat ../../product-team/agile-product-owner/references/user-story-templates.md +cat ../../product-team/agile-product-owner/skills/agile-product-owner/references/user-story-templates.md # Reference sprint planning guide for estimation practices -cat ../../product-team/agile-product-owner/references/sprint-planning-guide.md +cat ../../product-team/agile-product-owner/skills/agile-product-owner/references/sprint-planning-guide.md ``` ## Integration Examples @@ -335,17 +335,17 @@ echo "==========================" # Step 1: Prioritize backlog echo "" echo "1. Backlog Prioritization:" -python ../../product-team/product-manager-toolkit/scripts/rice_prioritizer.py backlog.csv --capacity $CAPACITY +python ../../product-team/skills/product-manager-toolkit/scripts/rice_prioritizer.py backlog.csv --capacity $CAPACITY # Step 2: Generate stories for top epic echo "" echo "2. Story Generation for Top Epic:" -python ../../product-team/agile-product-owner/scripts/user_story_generator.py top-epic.yaml +python ../../product-team/agile-product-owner/skills/agile-product-owner/scripts/user_story_generator.py top-epic.yaml # Step 3: Reference planning template echo "" echo "3. Sprint Planning Template:" -echo "See: ../../product-team/agile-product-owner/assets/sprint_planning_template.md" +echo "See: ../../product-team/agile-product-owner/skills/agile-product-owner/assets/sprint_planning_template.md" ``` ### Example 2: Backlog Health Check @@ -366,12 +366,12 @@ echo "items in backlog" # Run prioritization echo "" echo "Current Priorities:" -python ../../product-team/product-manager-toolkit/scripts/rice_prioritizer.py backlog.csv --capacity 20 +python ../../product-team/skills/product-manager-toolkit/scripts/rice_prioritizer.py backlog.csv --capacity 20 # Check story templates echo "" echo "Story Template Reference:" -echo "Location: ../../product-team/agile-product-owner/references/user-story-templates.md" +echo "Location: ../../product-team/agile-product-owner/skills/agile-product-owner/references/user-story-templates.md" ``` ## Success Metrics @@ -399,15 +399,15 @@ echo "Location: ../../product-team/agile-product-owner/references/user-story-tem - [cs-product-manager](cs-product-manager.md) - Full product management lifecycle (RICE, interviews, PRDs) - [cs-product-strategist](cs-product-strategist.md) - OKR cascade and strategic planning for roadmap alignment - [cs-ux-researcher](cs-ux-researcher.md) - User research to inform story requirements and acceptance criteria -- Scrum Master - Velocity context and sprint execution (see `../../project-management/scrum-master/`) +- Scrum Master - Velocity context and sprint execution (see `../../project-management/skills/scrum-master/`) ## References -- **Primary Skill:** [../../product-team/agile-product-owner/SKILL.md](../../product-team/agile-product-owner/SKILL.md) -- **RICE Framework:** [../../product-team/product-manager-toolkit/SKILL.md](../../product-team/product-manager-toolkit/SKILL.md) +- **Primary Skill:** [../../product-team/agile-product-owner/skills/agile-product-owner/SKILL.md](../../product-team/agile-product-owner/skills/agile-product-owner/SKILL.md) +- **RICE Framework:** [../../product-team/skills/product-manager-toolkit/SKILL.md](../../product-team/skills/product-manager-toolkit/SKILL.md) - **Product Domain Guide:** [../../product-team/CLAUDE.md](../../product-team/CLAUDE.md) - **Agent Development Guide:** [../CLAUDE.md](../CLAUDE.md) -- **Scrum Master Skill:** [../../project-management/scrum-master/SKILL.md](../../project-management/scrum-master/SKILL.md) +- **Scrum Master Skill:** [../../project-management/skills/scrum-master/SKILL.md](../../project-management/skills/scrum-master/SKILL.md) --- diff --git a/agents/product/cs-product-analyst.md b/agents/product/cs-product-analyst.md index d80dcb38..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/product-analytics/SKILL.md` -- `../../product-team/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/product-analytics/scripts/metrics_calculator.py` -- `../../product-team/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 b55013d2..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 @@ -19,144 +19,144 @@ The cs-product-manager agent bridges the gap between customer insights and produ ## Skill Integration -**Primary Skill:** `../../product-team/product-manager-toolkit/` +**Primary Skill:** `../../product-team/skills/product-manager-toolkit/` ### All Orchestrated Skills | # | Skill | Location | Primary Tool | |---|-------|----------|-------------| -| 1 | Product Manager Toolkit | `../../product-team/product-manager-toolkit/` | rice_prioritizer.py, customer_interview_analyzer.py | +| 1 | Product Manager Toolkit | `../../product-team/skills/product-manager-toolkit/` | rice_prioritizer.py, customer_interview_analyzer.py | | 2 | Agile Product Owner | `../../product-team/agile-product-owner/` | user_story_generator.py | -| 3 | Product Strategist | `../../product-team/product-strategist/` | okr_cascade_generator.py | -| 4 | UX Researcher & Designer | `../../product-team/ux-researcher-designer/` | persona_generator.py | -| 5 | UI Design System | `../../product-team/ui-design-system/` | design_token_generator.py | -| 6 | Competitive Teardown | `../../product-team/competitive-teardown/` | competitive_matrix_builder.py | -| 7 | Landing Page Generator | `../../product-team/landing-page-generator/` | landing_page_scaffolder.py | -| 8 | SaaS Scaffolder | `../../product-team/saas-scaffolder/` | project_bootstrapper.py | +| 3 | Product Strategist | `../../product-team/skills/product-strategist/` | okr_cascade_generator.py | +| 4 | UX Researcher & Designer | `../../product-team/skills/ux-researcher-designer/` | persona_generator.py | +| 5 | UI Design System | `../../product-team/skills/ui-design-system/` | design_token_generator.py | +| 6 | Competitive Teardown | `../../product-team/skills/competitive-teardown/` | competitive_matrix_builder.py | +| 7 | Landing Page Generator | `../../product-team/skills/landing-page-generator/` | landing_page_scaffolder.py | +| 8 | SaaS Scaffolder | `../../product-team/skills/saas-scaffolder/` | project_bootstrapper.py | ### Python Tools 1. **RICE Prioritizer** - **Purpose:** RICE framework implementation for feature prioritization with portfolio analysis and capacity planning - - **Path:** `../../product-team/product-manager-toolkit/scripts/rice_prioritizer.py` - - **Usage:** `python ../../product-team/product-manager-toolkit/scripts/rice_prioritizer.py features.csv --capacity 20` + - **Path:** `../../product-team/skills/product-manager-toolkit/scripts/rice_prioritizer.py` + - **Usage:** `python ../../product-team/skills/product-manager-toolkit/scripts/rice_prioritizer.py features.csv --capacity 20` - **Formula:** RICE Score = (Reach × Impact × Confidence) / Effort - **Features:** Portfolio analysis (quick wins vs big bets), quarterly roadmap generation, capacity planning, JSON/CSV export - **Use Cases:** Feature prioritization, roadmap planning, stakeholder alignment, resource allocation 2. **Customer Interview Analyzer** - **Purpose:** NLP-based interview transcript analysis to extract pain points, feature requests, and themes - - **Path:** `../../product-team/product-manager-toolkit/scripts/customer_interview_analyzer.py` - - **Usage:** `python ../../product-team/product-manager-toolkit/scripts/customer_interview_analyzer.py interview.txt` + - **Path:** `../../product-team/skills/product-manager-toolkit/scripts/customer_interview_analyzer.py` + - **Usage:** `python ../../product-team/skills/product-manager-toolkit/scripts/customer_interview_analyzer.py interview.txt` - **Features:** Pain point extraction with severity, feature request identification, jobs-to-be-done patterns, sentiment analysis, theme extraction - **Use Cases:** User research synthesis, discovery validation, problem prioritization, insight generation 3. **User Story Generator** - **Purpose:** Break epics into INVEST-compliant user stories with acceptance criteria - - **Path:** `../../product-team/agile-product-owner/scripts/user_story_generator.py` - - **Usage:** `python ../../product-team/agile-product-owner/scripts/user_story_generator.py epic.yaml` + - **Path:** `../../product-team/agile-product-owner/skills/agile-product-owner/scripts/user_story_generator.py` + - **Usage:** `python ../../product-team/agile-product-owner/skills/agile-product-owner/scripts/user_story_generator.py epic.yaml` - **Use Cases:** Sprint planning, backlog refinement, story decomposition 4. **OKR Cascade Generator** - **Purpose:** Generate cascaded OKRs from company objectives to team-level key results - - **Path:** `../../product-team/product-strategist/scripts/okr_cascade_generator.py` - - **Usage:** `python ../../product-team/product-strategist/scripts/okr_cascade_generator.py growth` + - **Path:** `../../product-team/skills/product-strategist/scripts/okr_cascade_generator.py` + - **Usage:** `python ../../product-team/skills/product-strategist/scripts/okr_cascade_generator.py growth` - **Use Cases:** Quarterly planning, strategic alignment, goal setting 5. **Persona Generator** - **Purpose:** Create data-driven user personas from research inputs - - **Path:** `../../product-team/ux-researcher-designer/scripts/persona_generator.py` - - **Usage:** `python ../../product-team/ux-researcher-designer/scripts/persona_generator.py research-data.json` + - **Path:** `../../product-team/skills/ux-researcher-designer/scripts/persona_generator.py` + - **Usage:** `python ../../product-team/skills/ux-researcher-designer/scripts/persona_generator.py research-data.json` - **Use Cases:** User research synthesis, persona development, journey mapping 6. **Design Token Generator** - **Purpose:** Generate design tokens for consistent UI implementation - - **Path:** `../../product-team/ui-design-system/scripts/design_token_generator.py` - - **Usage:** `python ../../product-team/ui-design-system/scripts/design_token_generator.py theme.json` + - **Path:** `../../product-team/skills/ui-design-system/scripts/design_token_generator.py` + - **Usage:** `python ../../product-team/skills/ui-design-system/scripts/design_token_generator.py theme.json` - **Use Cases:** Design system creation, developer handoff, theming 7. **Competitive Matrix Builder** - **Purpose:** Build competitive analysis matrices and feature comparison grids - - **Path:** `../../product-team/competitive-teardown/scripts/competitive_matrix_builder.py` - - **Usage:** `python ../../product-team/competitive-teardown/scripts/competitive_matrix_builder.py competitors.csv` + - **Path:** `../../product-team/skills/competitive-teardown/scripts/competitive_matrix_builder.py` + - **Usage:** `python ../../product-team/skills/competitive-teardown/scripts/competitive_matrix_builder.py competitors.csv` - **Use Cases:** Competitive intelligence, market positioning, feature gap analysis 8. **Landing Page Scaffolder** - **Purpose:** Generate conversion-optimized landing page scaffolds - - **Path:** `../../product-team/landing-page-generator/scripts/landing_page_scaffolder.py` - - **Usage:** `python ../../product-team/landing-page-generator/scripts/landing_page_scaffolder.py config.yaml` + - **Path:** `../../product-team/skills/landing-page-generator/scripts/landing_page_scaffolder.py` + - **Usage:** `python ../../product-team/skills/landing-page-generator/scripts/landing_page_scaffolder.py config.yaml` - **Use Cases:** Product launches, A/B testing, GTM campaigns 9. **Project Bootstrapper** - **Purpose:** Scaffold SaaS project structures with boilerplate and configurations - - **Path:** `../../product-team/saas-scaffolder/scripts/project_bootstrapper.py` - - **Usage:** `python ../../product-team/saas-scaffolder/scripts/project_bootstrapper.py --stack nextjs --name my-saas` + - **Path:** `../../product-team/skills/saas-scaffolder/scripts/project_bootstrapper.py` + - **Usage:** `python ../../product-team/skills/saas-scaffolder/scripts/project_bootstrapper.py --stack nextjs --name my-saas` - **Use Cases:** MVP scaffolding, project kickoff, SaaS prototype creation ### Knowledge Bases 1. **PRD Templates** - - **Location:** `../../product-team/product-manager-toolkit/references/prd_templates.md` + - **Location:** `../../product-team/skills/product-manager-toolkit/references/prd_templates.md` - **Content:** Multiple PRD formats (Standard PRD, One-Page PRD, Feature Brief, Agile Epic), structure guidelines, best practices - **Use Case:** Requirements documentation, stakeholder communication, engineering handoff 2. **Sprint Planning Guide** - - **Location:** `../../product-team/agile-product-owner/references/sprint-planning-guide.md` + - **Location:** `../../product-team/agile-product-owner/skills/agile-product-owner/references/sprint-planning-guide.md` - **Content:** Sprint planning ceremonies, velocity tracking, capacity allocation - **Use Case:** Sprint execution, backlog refinement, agile ceremonies 3. **User Story Templates** - - **Location:** `../../product-team/agile-product-owner/references/user-story-templates.md` + - **Location:** `../../product-team/agile-product-owner/skills/agile-product-owner/references/user-story-templates.md` - **Content:** INVEST-compliant story formats, acceptance criteria patterns, story splitting techniques - **Use Case:** Story writing, backlog grooming, definition of done 4. **OKR Framework** - - **Location:** `../../product-team/product-strategist/references/okr_framework.md` + - **Location:** `../../product-team/skills/product-strategist/references/okr_framework.md` - **Content:** OKR methodology, cascade patterns, scoring guidelines - **Use Case:** Quarterly planning, strategic alignment, goal tracking 5. **Strategy Types** - - **Location:** `../../product-team/product-strategist/references/strategy_types.md` + - **Location:** `../../product-team/skills/product-strategist/references/strategy_types.md` - **Content:** Product strategy frameworks, competitive positioning, growth strategies - **Use Case:** Strategic planning, market analysis, product vision 6. **Persona Methodology** - - **Location:** `../../product-team/ux-researcher-designer/references/persona-methodology.md` + - **Location:** `../../product-team/skills/ux-researcher-designer/references/persona-methodology.md` - **Content:** Research-backed persona creation methodology, data collection, validation - **Use Case:** Persona development, user segmentation, research planning 7. **Example Personas** - - **Location:** `../../product-team/ux-researcher-designer/references/example-personas.md` + - **Location:** `../../product-team/skills/ux-researcher-designer/references/example-personas.md` - **Content:** Sample persona documents with demographics, goals, pain points, behaviors - **Use Case:** Persona templates, research documentation 8. **Journey Mapping Guide** - - **Location:** `../../product-team/ux-researcher-designer/references/journey-mapping-guide.md` + - **Location:** `../../product-team/skills/ux-researcher-designer/references/journey-mapping-guide.md` - **Content:** Customer journey mapping methodology, touchpoint analysis, emotion mapping - **Use Case:** Experience design, touchpoint optimization, service design 9. **Usability Testing Frameworks** - - **Location:** `../../product-team/ux-researcher-designer/references/usability-testing-frameworks.md` + - **Location:** `../../product-team/skills/ux-researcher-designer/references/usability-testing-frameworks.md` - **Content:** Usability test planning, task design, analysis methods - **Use Case:** Usability studies, prototype validation, UX evaluation 10. **Component Architecture** - - **Location:** `../../product-team/ui-design-system/references/component-architecture.md` + - **Location:** `../../product-team/skills/ui-design-system/references/component-architecture.md` - **Content:** Component hierarchy, atomic design patterns, composition strategies - **Use Case:** Design system architecture, component libraries 11. **Developer Handoff** - - **Location:** `../../product-team/ui-design-system/references/developer-handoff.md` + - **Location:** `../../product-team/skills/ui-design-system/references/developer-handoff.md` - **Content:** Design-to-dev handoff process, specification formats, asset delivery - **Use Case:** Engineering collaboration, implementation specs 12. **Responsive Calculations** - - **Location:** `../../product-team/ui-design-system/references/responsive-calculations.md` + - **Location:** `../../product-team/skills/ui-design-system/references/responsive-calculations.md` - **Content:** Responsive design formulas, breakpoint strategies, fluid typography - **Use Case:** Responsive implementation, cross-device design 13. **Token Generation** - - **Location:** `../../product-team/ui-design-system/references/token-generation.md` + - **Location:** `../../product-team/skills/ui-design-system/references/token-generation.md` - **Content:** Design token standards, naming conventions, platform-specific output - **Use Case:** Design system tokens, theming, multi-platform consistency @@ -188,7 +188,7 @@ The cs-product-manager agent bridges the gap between customer insights and produ 3. **Run RICE Prioritization** - Execute analysis with team capacity ```bash - python ../../product-team/product-manager-toolkit/scripts/rice_prioritizer.py features.csv --capacity 20 + python ../../product-team/skills/product-manager-toolkit/scripts/rice_prioritizer.py features.csv --capacity 20 ``` 4. **Analyze Portfolio** - Review output for: @@ -214,7 +214,7 @@ The cs-product-manager agent bridges the gap between customer insights and produ **Example:** ```bash # Complete prioritization workflow -python ../../product-team/product-manager-toolkit/scripts/rice_prioritizer.py q4-features.csv --capacity 20 > roadmap.txt +python ../../product-team/skills/product-manager-toolkit/scripts/rice_prioritizer.py q4-features.csv --capacity 20 > roadmap.txt cat roadmap.txt # Review quick wins, big bets, and generate quarterly plan ``` @@ -240,7 +240,7 @@ cat roadmap.txt 3. **Run Interview Analyzer** - Extract structured insights ```bash - python ../../product-team/product-manager-toolkit/scripts/customer_interview_analyzer.py interview-001.txt + python ../../product-team/skills/product-manager-toolkit/scripts/customer_interview_analyzer.py interview-001.txt ``` 4. **Review Analysis Output** - Study extracted insights: @@ -254,9 +254,9 @@ cat roadmap.txt 5. **Synthesize Across Interviews** - Aggregate insights: ```bash # Analyze multiple interviews - python ../../product-team/product-manager-toolkit/scripts/customer_interview_analyzer.py interview-001.txt json > insights-001.json - python ../../product-team/product-manager-toolkit/scripts/customer_interview_analyzer.py interview-002.txt json > insights-002.json - python ../../product-team/product-manager-toolkit/scripts/customer_interview_analyzer.py interview-003.txt json > insights-003.json + python ../../product-team/skills/product-manager-toolkit/scripts/customer_interview_analyzer.py interview-001.txt json > insights-001.json + python ../../product-team/skills/product-manager-toolkit/scripts/customer_interview_analyzer.py interview-002.txt json > insights-002.json + python ../../product-team/skills/product-manager-toolkit/scripts/customer_interview_analyzer.py interview-003.txt json > insights-003.json # Aggregate JSON files to find patterns ``` @@ -282,7 +282,7 @@ cat roadmap.txt **Steps:** 1. **Choose PRD Template** - Select based on complexity: ```bash - cat ../../product-team/product-manager-toolkit/references/prd_templates.md + cat ../../product-team/skills/product-manager-toolkit/references/prd_templates.md ``` - **Standard PRD**: Complex features (6-8 weeks dev) - **One-Page PRD**: Simple features (2-4 weeks) @@ -341,12 +341,12 @@ cat roadmap.txt 2. **Run Feature Prioritization** - Use RICE for candidate features ```bash - python ../../product-team/product-manager-toolkit/scripts/rice_prioritizer.py q4-candidates.csv --capacity 18 + python ../../product-team/skills/product-manager-toolkit/scripts/rice_prioritizer.py q4-candidates.csv --capacity 18 ``` 3. **Generate OKR Cascade** - Use the OKR cascade generator to create aligned objectives ```bash - python ../../product-team/product-strategist/scripts/okr_cascade_generator.py growth + python ../../product-team/skills/product-strategist/scripts/okr_cascade_generator.py growth ``` 4. **Define Product OKRs** - Set ambitious but achievable goals: @@ -396,22 +396,22 @@ cat roadmap.txt 2. **Review Persona Methodology** - Understand research-backed persona creation ```bash - cat ../../product-team/ux-researcher-designer/references/persona-methodology.md + cat ../../product-team/skills/ux-researcher-designer/references/persona-methodology.md ``` 3. **Generate Personas** - Create structured personas from research inputs ```bash - python ../../product-team/ux-researcher-designer/scripts/persona_generator.py research-data.json + python ../../product-team/skills/ux-researcher-designer/scripts/persona_generator.py research-data.json ``` 4. **Map Customer Journeys** - Reference journey mapping guide for each persona ```bash - cat ../../product-team/ux-researcher-designer/references/journey-mapping-guide.md + cat ../../product-team/skills/ux-researcher-designer/references/journey-mapping-guide.md ``` 5. **Review Example Personas** - Compare output against proven persona formats ```bash - cat ../../product-team/ux-researcher-designer/references/example-personas.md + cat ../../product-team/skills/ux-researcher-designer/references/example-personas.md ``` 6. **Validate and Iterate** - Share personas with stakeholders: @@ -426,13 +426,13 @@ cat roadmap.txt **Example:** ```bash # Complete persona generation workflow -python ../../product-team/ux-researcher-designer/scripts/persona_generator.py user-research-q4.json > personas.md +python ../../product-team/skills/ux-researcher-designer/scripts/persona_generator.py user-research-q4.json > personas.md # Cross-reference with interview analysis -python ../../product-team/product-manager-toolkit/scripts/customer_interview_analyzer.py interviews-batch.txt > insights.txt +python ../../product-team/skills/product-manager-toolkit/scripts/customer_interview_analyzer.py interviews-batch.txt > insights.txt # Review journey mapping methodology -cat ../../product-team/ux-researcher-designer/references/journey-mapping-guide.md +cat ../../product-team/skills/ux-researcher-designer/references/journey-mapping-guide.md ``` ### Workflow 6: Sprint Story Generation @@ -448,17 +448,17 @@ cat ../../product-team/ux-researcher-designer/references/journey-mapping-guide.m 2. **Review Story Templates** - Load INVEST-compliant story patterns ```bash - cat ../../product-team/agile-product-owner/references/user-story-templates.md + cat ../../product-team/agile-product-owner/skills/agile-product-owner/references/user-story-templates.md ``` 3. **Generate User Stories** - Break the epic into sprint-sized stories ```bash - python ../../product-team/agile-product-owner/scripts/user_story_generator.py epic.yaml + python ../../product-team/agile-product-owner/skills/agile-product-owner/scripts/user_story_generator.py epic.yaml ``` 4. **Review Sprint Planning Guide** - Ensure stories fit sprint capacity ```bash - cat ../../product-team/agile-product-owner/references/sprint-planning-guide.md + cat ../../product-team/agile-product-owner/skills/agile-product-owner/references/sprint-planning-guide.md ``` 5. **Refine and Estimate** - Groom generated stories: @@ -469,7 +469,7 @@ cat ../../product-team/ux-researcher-designer/references/journey-mapping-guide.m 6. **Prioritize for Sprint** - Use RICE scores to sequence stories ```bash - python ../../product-team/product-manager-toolkit/scripts/rice_prioritizer.py sprint-stories.csv --capacity 8 + python ../../product-team/skills/product-manager-toolkit/scripts/rice_prioritizer.py sprint-stories.csv --capacity 8 ``` **Expected Output:** Sprint-ready backlog of INVEST-compliant user stories with acceptance criteria, story points, and priority order @@ -479,13 +479,13 @@ cat ../../product-team/ux-researcher-designer/references/journey-mapping-guide.m **Example:** ```bash # End-to-end story generation workflow -python ../../product-team/agile-product-owner/scripts/user_story_generator.py onboarding-epic.yaml > stories.md +python ../../product-team/agile-product-owner/skills/agile-product-owner/scripts/user_story_generator.py onboarding-epic.yaml > stories.md # Prioritize stories for sprint -python ../../product-team/product-manager-toolkit/scripts/rice_prioritizer.py stories.csv --capacity 8 > sprint-plan.txt +python ../../product-team/skills/product-manager-toolkit/scripts/rice_prioritizer.py stories.csv --capacity 8 > sprint-plan.txt # Review sprint planning best practices -cat ../../product-team/agile-product-owner/references/sprint-planning-guide.md +cat ../../product-team/agile-product-owner/skills/agile-product-owner/references/sprint-planning-guide.md ``` ### Workflow 7: Competitive Intelligence @@ -508,7 +508,7 @@ cat ../../product-team/agile-product-owner/references/sprint-planning-guide.md 3. **Build Competitive Matrix** - Generate visual comparison ```bash - python ../../product-team/competitive-teardown/scripts/competitive_matrix_builder.py competitors.csv + python ../../product-team/skills/competitive-teardown/scripts/competitive_matrix_builder.py competitors.csv ``` 4. **Analyze Gaps** - Identify strategic opportunities: @@ -520,7 +520,7 @@ cat ../../product-team/agile-product-owner/references/sprint-planning-guide.md 5. **Feed Into Prioritization** - Use gaps to inform roadmap ```bash # Add competitive gap features to RICE analysis - python ../../product-team/product-manager-toolkit/scripts/rice_prioritizer.py competitive-features.csv --capacity 20 + python ../../product-team/skills/product-manager-toolkit/scripts/rice_prioritizer.py competitive-features.csv --capacity 20 ``` 6. **Track Over Time** - Update competitive matrix quarterly: @@ -535,10 +535,10 @@ cat ../../product-team/agile-product-owner/references/sprint-planning-guide.md **Example:** ```bash # Full competitive intelligence workflow -python ../../product-team/competitive-teardown/scripts/competitive_matrix_builder.py q4-competitors.csv > competitive-matrix.md +python ../../product-team/skills/competitive-teardown/scripts/competitive_matrix_builder.py q4-competitors.csv > competitive-matrix.md # Prioritize competitive gap features -python ../../product-team/product-manager-toolkit/scripts/rice_prioritizer.py gap-features.csv --capacity 12 > competitive-roadmap.txt +python ../../product-team/skills/product-manager-toolkit/scripts/rice_prioritizer.py gap-features.csv --capacity 12 > competitive-roadmap.txt ``` ## Integration Examples @@ -555,13 +555,13 @@ echo "==========================================" # Current roadmap status echo "" echo "🎯 Roadmap Priorities (RICE Sorted):" -python ../../product-team/product-manager-toolkit/scripts/rice_prioritizer.py current-roadmap.csv --capacity 20 +python ../../product-team/skills/product-manager-toolkit/scripts/rice_prioritizer.py current-roadmap.csv --capacity 20 # Recent interview insights echo "" echo "💡 Latest Customer Insights:" if [ -f latest-interview.txt ]; then - python ../../product-team/product-manager-toolkit/scripts/customer_interview_analyzer.py latest-interview.txt + python ../../product-team/skills/product-manager-toolkit/scripts/customer_interview_analyzer.py latest-interview.txt else echo "No new interviews this week" fi @@ -570,7 +570,7 @@ fi echo "" echo "📝 PRD Templates:" echo "Standard PRD, One-Page PRD, Feature Brief, Agile Epic" -echo "Location: ../../product-team/product-manager-toolkit/references/prd_templates.md" +echo "Location: ../../product-team/skills/product-manager-toolkit/references/prd_templates.md" ``` ### Example 2: Discovery Sprint Workflow @@ -585,11 +585,11 @@ echo "==============================" echo "Conducting 5 customer interviews..." # Day 3-5: Analyze insights -python ../../product-team/product-manager-toolkit/scripts/customer_interview_analyzer.py interview-001.txt > insights-001.txt -python ../../product-team/product-manager-toolkit/scripts/customer_interview_analyzer.py interview-002.txt > insights-002.txt -python ../../product-team/product-manager-toolkit/scripts/customer_interview_analyzer.py interview-003.txt > insights-003.txt -python ../../product-team/product-manager-toolkit/scripts/customer_interview_analyzer.py interview-004.txt > insights-004.txt -python ../../product-team/product-manager-toolkit/scripts/customer_interview_analyzer.py interview-005.txt > insights-005.txt +python ../../product-team/skills/product-manager-toolkit/scripts/customer_interview_analyzer.py interview-001.txt > insights-001.txt +python ../../product-team/skills/product-manager-toolkit/scripts/customer_interview_analyzer.py interview-002.txt > insights-002.txt +python ../../product-team/skills/product-manager-toolkit/scripts/customer_interview_analyzer.py interview-003.txt > insights-003.txt +python ../../product-team/skills/product-manager-toolkit/scripts/customer_interview_analyzer.py interview-004.txt > insights-004.txt +python ../../product-team/skills/product-manager-toolkit/scripts/customer_interview_analyzer.py interview-005.txt > insights-005.txt echo "" echo "🔍 Discovery Sprint - Week 2" @@ -599,7 +599,7 @@ echo "==============================" echo "Creating solution candidates..." # Day 9-10: RICE prioritization -python ../../product-team/product-manager-toolkit/scripts/rice_prioritizer.py solution-candidates.csv +python ../../product-team/skills/product-manager-toolkit/scripts/rice_prioritizer.py solution-candidates.csv echo "" echo "✅ Discovery Complete - Ready for PRD creation" @@ -619,7 +619,7 @@ echo "====================" # Step 1: Prioritize backlog echo "" echo "1. Feature Prioritization:" -python ../../product-team/product-manager-toolkit/scripts/rice_prioritizer.py backlog.csv --capacity $CAPACITY > $QUARTER-roadmap.txt +python ../../product-team/skills/product-manager-toolkit/scripts/rice_prioritizer.py backlog.csv --capacity $CAPACITY > $QUARTER-roadmap.txt # Step 2: Extract quick wins echo "" @@ -673,7 +673,7 @@ echo "Report: $QUARTER-roadmap.txt" ## References -- **Skill Documentation:** [../../product-team/product-manager-toolkit/SKILL.md](../../product-team/product-manager-toolkit/SKILL.md) +- **Skill Documentation:** [../../product-team/skills/product-manager-toolkit/SKILL.md](../../product-team/skills/product-manager-toolkit/SKILL.md) - **Product Domain Guide:** [../../product-team/CLAUDE.md](../../product-team/CLAUDE.md) - **Agent Development Guide:** [../CLAUDE.md](../CLAUDE.md) diff --git a/agents/product/cs-product-strategist.md b/agents/product/cs-product-strategist.md index a77ed228..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 @@ -19,74 +19,74 @@ The cs-product-strategist agent operates at the intersection of business strateg ## Skill Integration -**Primary Skill:** `../../product-team/product-strategist/` +**Primary Skill:** `../../product-team/skills/product-strategist/` ### All Orchestrated Skills | # | Skill | Location | Primary Tool | |---|-------|----------|-------------| -| 1 | Product Strategist | `../../product-team/product-strategist/` | okr_cascade_generator.py | -| 2 | Competitive Teardown | `../../product-team/competitive-teardown/` | competitive_matrix_builder.py | -| 3 | Product Manager Toolkit | `../../product-team/product-manager-toolkit/` | rice_prioritizer.py | +| 1 | Product Strategist | `../../product-team/skills/product-strategist/` | okr_cascade_generator.py | +| 2 | Competitive Teardown | `../../product-team/skills/competitive-teardown/` | competitive_matrix_builder.py | +| 3 | Product Manager Toolkit | `../../product-team/skills/product-manager-toolkit/` | rice_prioritizer.py | ### Python Tools 1. **OKR Cascade Generator** - **Purpose:** Generate cascaded OKRs from company objectives to team-level key results with initiative mapping - - **Path:** `../../product-team/product-strategist/scripts/okr_cascade_generator.py` - - **Usage:** `python ../../product-team/product-strategist/scripts/okr_cascade_generator.py growth` + - **Path:** `../../product-team/skills/product-strategist/scripts/okr_cascade_generator.py` + - **Usage:** `python ../../product-team/skills/product-strategist/scripts/okr_cascade_generator.py growth` - **Features:** Multi-level cascade (company > product > team), initiative mapping, scoring framework, tracking cadence - **Use Cases:** Quarterly planning, strategic alignment, goal setting, annual planning 2. **Competitive Matrix Builder** - **Purpose:** Build competitive analysis matrices, feature comparison grids, and positioning maps - - **Path:** `../../product-team/competitive-teardown/scripts/competitive_matrix_builder.py` - - **Usage:** `python ../../product-team/competitive-teardown/scripts/competitive_matrix_builder.py competitors.csv` + - **Path:** `../../product-team/skills/competitive-teardown/scripts/competitive_matrix_builder.py` + - **Usage:** `python ../../product-team/skills/competitive-teardown/scripts/competitive_matrix_builder.py competitors.csv` - **Features:** Multi-dimensional scoring, weighted comparison, gap analysis, positioning visualization - **Use Cases:** Competitive intelligence, market positioning, feature gap analysis, strategic differentiation 3. **RICE Prioritizer** - **Purpose:** Strategic initiative prioritization using RICE framework for portfolio-level decisions - - **Path:** `../../product-team/product-manager-toolkit/scripts/rice_prioritizer.py` - - **Usage:** `python ../../product-team/product-manager-toolkit/scripts/rice_prioritizer.py initiatives.csv --capacity 50` + - **Path:** `../../product-team/skills/product-manager-toolkit/scripts/rice_prioritizer.py` + - **Usage:** `python ../../product-team/skills/product-manager-toolkit/scripts/rice_prioritizer.py initiatives.csv --capacity 50` - **Features:** Portfolio quadrant analysis (big bets, quick wins), capacity planning, strategic roadmap generation - **Use Cases:** Initiative prioritization, resource allocation, strategic portfolio management ### Knowledge Bases 1. **OKR Framework** - - **Location:** `../../product-team/product-strategist/references/okr_framework.md` + - **Location:** `../../product-team/skills/product-strategist/references/okr_framework.md` - **Content:** OKR methodology, cascade patterns, scoring guidelines, common pitfalls - **Use Case:** OKR education, quarterly planning preparation 2. **Strategy Types** - - **Location:** `../../product-team/product-strategist/references/strategy_types.md` + - **Location:** `../../product-team/skills/product-strategist/references/strategy_types.md` - **Content:** Product strategy frameworks, competitive positioning models, growth strategies - **Use Case:** Strategy formulation, market analysis, product vision development 3. **Data Collection Guide** - - **Location:** `../../product-team/competitive-teardown/references/data-collection-guide.md` + - **Location:** `../../product-team/skills/competitive-teardown/references/data-collection-guide.md` - **Content:** Sources and methods for gathering competitive intelligence ethically - **Use Case:** Competitive research planning, data source identification 4. **Scoring Rubric** - - **Location:** `../../product-team/competitive-teardown/references/scoring-rubric.md` + - **Location:** `../../product-team/skills/competitive-teardown/references/scoring-rubric.md` - **Content:** Standardized scoring criteria for competitive dimensions (1-10 scale) - **Use Case:** Consistent competitor evaluation, bias mitigation 5. **Analysis Templates** - - **Location:** `../../product-team/competitive-teardown/references/analysis-templates.md` + - **Location:** `../../product-team/skills/competitive-teardown/references/analysis-templates.md` - **Content:** SWOT, Porter's Five Forces, positioning maps, battle cards, win/loss analysis - **Use Case:** Structured competitive analysis, sales enablement ### Templates 1. **OKR Template** - - **Location:** `../../product-team/product-strategist/assets/okr_template.md` + - **Location:** `../../product-team/skills/product-strategist/assets/okr_template.md` - **Use Case:** Quarterly OKR documentation with tracking structure 2. **PRD Template** - - **Location:** `../../product-team/product-manager-toolkit/assets/prd_template.md` + - **Location:** `../../product-team/skills/product-manager-toolkit/assets/prd_template.md` - **Use Case:** Documenting strategic initiatives as formal requirements ## Workflows @@ -105,7 +105,7 @@ The cs-product-strategist agent operates at the intersection of business strateg 2. **Analyze Market Context** - Understand external factors: ```bash # Build competitive landscape - python ../../product-team/competitive-teardown/scripts/competitive_matrix_builder.py competitors.csv + python ../../product-team/skills/competitive-teardown/scripts/competitive_matrix_builder.py competitors.csv ``` - Review competitive movements from past quarter - Identify market trends and opportunities @@ -114,7 +114,7 @@ The cs-product-strategist agent operates at the intersection of business strateg 3. **Generate OKR Cascade** - Create aligned objectives: ```bash # Generate OKRs for growth strategy - python ../../product-team/product-strategist/scripts/okr_cascade_generator.py growth + python ../../product-team/skills/product-strategist/scripts/okr_cascade_generator.py growth ``` 4. **Define Product Objectives** - Set 2-3 product objectives: @@ -130,7 +130,7 @@ The cs-product-strategist agent operates at the intersection of business strateg 6. **Map Initiatives to KRs** - Connect work to outcomes: ```bash # Prioritize strategic initiatives - python ../../product-team/product-manager-toolkit/scripts/rice_prioritizer.py initiatives.csv --capacity 50 + python ../../product-team/skills/product-manager-toolkit/scripts/rice_prioritizer.py initiatives.csv --capacity 50 ``` 7. **Stakeholder Alignment** - Present and iterate: @@ -140,7 +140,7 @@ The cs-product-strategist agent operates at the intersection of business strateg 8. **Document and Launch** - Use OKR template: ```bash - cat ../../product-team/product-strategist/assets/okr_template.md + cat ../../product-team/skills/product-strategist/assets/okr_template.md ``` **Expected Output:** Quarterly OKR document with 2-3 objectives, 8-12 key results, mapped initiatives, and stakeholder alignment @@ -154,16 +154,16 @@ echo "Q3 2026 OKR Planning" echo "====================" # Step 1: Competitive context -python ../../product-team/competitive-teardown/scripts/competitive_matrix_builder.py q3-competitors.csv +python ../../product-team/skills/competitive-teardown/scripts/competitive_matrix_builder.py q3-competitors.csv # Step 2: Generate OKR cascade -python ../../product-team/product-strategist/scripts/okr_cascade_generator.py growth +python ../../product-team/skills/product-strategist/scripts/okr_cascade_generator.py growth # Step 3: Prioritize initiatives -python ../../product-team/product-manager-toolkit/scripts/rice_prioritizer.py q3-initiatives.csv --capacity 45 +python ../../product-team/skills/product-manager-toolkit/scripts/rice_prioritizer.py q3-initiatives.csv --capacity 45 # Step 4: Review OKR template -cat ../../product-team/product-strategist/assets/okr_template.md +cat ../../product-team/skills/product-strategist/assets/okr_template.md ``` ### Workflow 2: Competitive Landscape Review @@ -178,7 +178,7 @@ cat ../../product-team/product-strategist/assets/okr_template.md 2. **Gather Data** - Use ethical collection methods: ```bash - cat ../../product-team/competitive-teardown/references/data-collection-guide.md + cat ../../product-team/skills/competitive-teardown/references/data-collection-guide.md ``` - Public sources: G2, Capterra, pricing pages, changelogs - Market reports: Gartner, Forrester, analyst briefings @@ -186,7 +186,7 @@ cat ../../product-team/product-strategist/assets/okr_template.md 3. **Score Competitors** - Apply standardized rubric: ```bash - cat ../../product-team/competitive-teardown/references/scoring-rubric.md + cat ../../product-team/skills/competitive-teardown/references/scoring-rubric.md ``` - Score across 7 dimensions (UX, features, pricing, integrations, support, performance, security) - Use multiple scorers to reduce bias @@ -194,7 +194,7 @@ cat ../../product-team/product-strategist/assets/okr_template.md 4. **Build Competitive Matrix** - Generate comparison: ```bash - python ../../product-team/competitive-teardown/scripts/competitive_matrix_builder.py competitors-scored.csv + python ../../product-team/skills/competitive-teardown/scripts/competitive_matrix_builder.py competitors-scored.csv ``` 5. **Identify Gaps and Opportunities** - Analyze the matrix: @@ -204,7 +204,7 @@ cat ../../product-team/product-strategist/assets/okr_template.md 6. **Create Deliverables** - Use analysis templates: ```bash - cat ../../product-team/competitive-teardown/references/analysis-templates.md + cat ../../product-team/skills/competitive-teardown/references/analysis-templates.md ``` - SWOT analysis per major competitor - Positioning map (2x2) @@ -226,7 +226,7 @@ Competitor B,9,6,8,5,8,6,6 Competitor C,5,9,5,7,5,8,9 EOF -python ../../product-team/competitive-teardown/scripts/competitive_matrix_builder.py competitors.csv +python ../../product-team/skills/competitive-teardown/scripts/competitive_matrix_builder.py competitors.csv ``` ### Workflow 3: Product Vision Document @@ -250,7 +250,7 @@ python ../../product-team/competitive-teardown/scripts/competitive_matrix_builde 3. **Map the Strategy** - Connect vision to execution: ```bash # Review strategy frameworks - cat ../../product-team/product-strategist/references/strategy_types.md + cat ../../product-team/skills/product-strategist/references/strategy_types.md ``` - Choose strategic posture (category leader, disruptor, fast follower) - Define competitive moats (technology, network effects, data, brand) @@ -292,7 +292,7 @@ python ../../product-team/competitive-teardown/scripts/competitive_matrix_builde 2. **Quantify Current Performance** - Baseline analysis: ```bash # Assess current initiative portfolio - python ../../product-team/product-manager-toolkit/scripts/rice_prioritizer.py current-initiatives.csv + python ../../product-team/skills/product-manager-toolkit/scripts/rice_prioritizer.py current-initiatives.csv ``` - Revenue trajectory and unit economics - Customer acquisition cost trends @@ -310,7 +310,7 @@ python ../../product-team/competitive-teardown/scripts/competitive_matrix_builde 4. **Score Each Option** - Structured evaluation: ```bash # Build comparison matrix for pivot options - python ../../product-team/competitive-teardown/scripts/competitive_matrix_builder.py pivot-options.csv + python ../../product-team/skills/competitive-teardown/scripts/competitive_matrix_builder.py pivot-options.csv ``` - Market size and growth potential - Competitive intensity in new direction @@ -327,7 +327,7 @@ python ../../product-team/competitive-teardown/scripts/competitive_matrix_builde 6. **Set Pivot OKRs** - Define success for the new direction: ```bash - python ../../product-team/product-strategist/scripts/okr_cascade_generator.py pivot + python ../../product-team/skills/product-strategist/scripts/okr_cascade_generator.py pivot ``` **Expected Output:** Pivot analysis document with current state assessment, option evaluation, recommended path, transition plan, and pivot-specific OKRs @@ -345,10 +345,10 @@ Problem Pivot to Workflow,8,6,7,5,6 Technology Pivot to AI-Native,9,4,8,4,7 EOF -python ../../product-team/competitive-teardown/scripts/competitive_matrix_builder.py pivot-options.csv +python ../../product-team/skills/competitive-teardown/scripts/competitive_matrix_builder.py pivot-options.csv # Generate OKRs for recommended pivot direction -python ../../product-team/product-strategist/scripts/okr_cascade_generator.py growth +python ../../product-team/skills/product-strategist/scripts/okr_cascade_generator.py growth ``` ## Integration Examples @@ -367,22 +367,22 @@ echo "================================" # Competitive landscape echo "" echo "1. Competitive Analysis:" -python ../../product-team/competitive-teardown/scripts/competitive_matrix_builder.py annual-competitors.csv +python ../../product-team/skills/competitive-teardown/scripts/competitive_matrix_builder.py annual-competitors.csv # Strategy reference echo "" echo "2. Strategy Frameworks:" -cat ../../product-team/product-strategist/references/strategy_types.md | head -50 +cat ../../product-team/skills/product-strategist/references/strategy_types.md | head -50 # Annual OKR cascade echo "" echo "3. Annual OKR Cascade:" -python ../../product-team/product-strategist/scripts/okr_cascade_generator.py growth +python ../../product-team/skills/product-strategist/scripts/okr_cascade_generator.py growth # Initiative prioritization echo "" echo "4. Strategic Initiative Prioritization:" -python ../../product-team/product-manager-toolkit/scripts/rice_prioritizer.py annual-initiatives.csv --capacity 180 +python ../../product-team/skills/product-manager-toolkit/scripts/rice_prioritizer.py annual-initiatives.csv --capacity 180 ``` ### Example 2: Monthly Strategy Review @@ -397,17 +397,17 @@ echo "============================================" # Competitive movements echo "" echo "Competitive Updates:" -echo "Review: ../../product-team/competitive-teardown/references/data-collection-guide.md" +echo "Review: ../../product-team/skills/competitive-teardown/references/data-collection-guide.md" # OKR progress echo "" echo "OKR Progress:" -echo "Review: ../../product-team/product-strategist/assets/okr_template.md" +echo "Review: ../../product-team/skills/product-strategist/assets/okr_template.md" # Initiative status echo "" echo "Initiative Portfolio:" -python ../../product-team/product-manager-toolkit/scripts/rice_prioritizer.py current-initiatives.csv +python ../../product-team/skills/product-manager-toolkit/scripts/rice_prioritizer.py current-initiatives.csv ``` ### Example 3: Board Preparation @@ -424,17 +424,17 @@ echo "=============================" # Strategic metrics echo "" echo "1. Product Strategy Performance:" -python ../../product-team/product-manager-toolkit/scripts/rice_prioritizer.py $QUARTER-delivered.csv +python ../../product-team/skills/product-manager-toolkit/scripts/rice_prioritizer.py $QUARTER-delivered.csv # Competitive position echo "" echo "2. Competitive Positioning:" -python ../../product-team/competitive-teardown/scripts/competitive_matrix_builder.py board-competitors.csv +python ../../product-team/skills/competitive-teardown/scripts/competitive_matrix_builder.py board-competitors.csv # Next quarter OKRs echo "" echo "3. Next Quarter OKR Proposal:" -python ../../product-team/product-strategist/scripts/okr_cascade_generator.py growth +python ../../product-team/skills/product-strategist/scripts/okr_cascade_generator.py growth ``` ## Success Metrics @@ -469,14 +469,14 @@ python ../../product-team/product-strategist/scripts/okr_cascade_generator.py gr - [cs-agile-product-owner](cs-agile-product-owner.md) - Sprint-level planning and backlog management - [cs-ux-researcher](cs-ux-researcher.md) - User research to validate strategic assumptions - [cs-ceo-advisor](../c-level/cs-ceo-advisor.md) - Company-level strategic alignment -- Senior PM Skill - Portfolio context (see `../../project-management/senior-pm/`) +- Senior PM Skill - Portfolio context (see `../../project-management/skills/senior-pm/`) ## References -- **Primary Skill:** [../../product-team/product-strategist/SKILL.md](../../product-team/product-strategist/SKILL.md) -- **Competitive Teardown Skill:** [../../product-team/competitive-teardown/SKILL.md](../../product-team/competitive-teardown/SKILL.md) -- **OKR Framework:** [../../product-team/product-strategist/references/okr_framework.md](../../product-team/product-strategist/references/okr_framework.md) -- **Strategy Types:** [../../product-team/product-strategist/references/strategy_types.md](../../product-team/product-strategist/references/strategy_types.md) +- **Primary Skill:** [../../product-team/skills/product-strategist/SKILL.md](../../product-team/skills/product-strategist/SKILL.md) +- **Competitive Teardown Skill:** [../../product-team/skills/competitive-teardown/SKILL.md](../../product-team/skills/competitive-teardown/SKILL.md) +- **OKR Framework:** [../../product-team/skills/product-strategist/references/okr_framework.md](../../product-team/skills/product-strategist/references/okr_framework.md) +- **Strategy Types:** [../../product-team/skills/product-strategist/references/strategy_types.md](../../product-team/skills/product-strategist/references/strategy_types.md) - **Product Domain Guide:** [../../product-team/CLAUDE.md](../../product-team/CLAUDE.md) - **Agent Development Guide:** [../CLAUDE.md](../CLAUDE.md) diff --git a/agents/product/cs-ux-researcher.md b/agents/product/cs-ux-researcher.md index 27a3917a..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 @@ -19,78 +19,78 @@ The cs-ux-researcher agent ensures that user needs drive product development. It ## Skill Integration -**Primary Skill:** `../../product-team/ux-researcher-designer/` +**Primary Skill:** `../../product-team/skills/ux-researcher-designer/` ### All Orchestrated Skills | # | Skill | Location | Primary Tool | |---|-------|----------|-------------| -| 1 | UX Researcher & Designer | `../../product-team/ux-researcher-designer/` | persona_generator.py | -| 2 | Product Manager Toolkit | `../../product-team/product-manager-toolkit/` | customer_interview_analyzer.py | -| 3 | UI Design System | `../../product-team/ui-design-system/` | design_token_generator.py | +| 1 | UX Researcher & Designer | `../../product-team/skills/ux-researcher-designer/` | persona_generator.py | +| 2 | Product Manager Toolkit | `../../product-team/skills/product-manager-toolkit/` | customer_interview_analyzer.py | +| 3 | UI Design System | `../../product-team/skills/ui-design-system/` | design_token_generator.py | ### Python Tools 1. **Persona Generator** - **Purpose:** Create data-driven user personas from research inputs including demographics, goals, pain points, and behavioral patterns - - **Path:** `../../product-team/ux-researcher-designer/scripts/persona_generator.py` - - **Usage:** `python ../../product-team/ux-researcher-designer/scripts/persona_generator.py research-data.json` + - **Path:** `../../product-team/skills/ux-researcher-designer/scripts/persona_generator.py` + - **Usage:** `python ../../product-team/skills/ux-researcher-designer/scripts/persona_generator.py research-data.json` - **Features:** Multiple persona generation, behavioral segmentation, needs hierarchy mapping, empathy map creation - **Use Cases:** Persona development, user segmentation, design alignment, stakeholder communication 2. **Customer Interview Analyzer** - **Purpose:** NLP-based analysis of interview transcripts to extract pain points, feature requests, themes, and sentiment - - **Path:** `../../product-team/product-manager-toolkit/scripts/customer_interview_analyzer.py` - - **Usage:** `python ../../product-team/product-manager-toolkit/scripts/customer_interview_analyzer.py interview.txt` + - **Path:** `../../product-team/skills/product-manager-toolkit/scripts/customer_interview_analyzer.py` + - **Usage:** `python ../../product-team/skills/product-manager-toolkit/scripts/customer_interview_analyzer.py interview.txt` - **Features:** Pain point extraction with severity scoring, feature request identification, jobs-to-be-done patterns, theme clustering, key quote extraction - **Use Cases:** Interview synthesis, discovery validation, problem prioritization, insight aggregation 3. **Design Token Generator** - **Purpose:** Generate design tokens for consistent UI implementation across platforms - - **Path:** `../../product-team/ui-design-system/scripts/design_token_generator.py` - - **Usage:** `python ../../product-team/ui-design-system/scripts/design_token_generator.py theme.json` + - **Path:** `../../product-team/skills/ui-design-system/scripts/design_token_generator.py` + - **Usage:** `python ../../product-team/skills/ui-design-system/scripts/design_token_generator.py theme.json` - **Use Cases:** Research-informed design system updates, accessibility token adjustments ### Knowledge Bases 1. **Persona Methodology** - - **Location:** `../../product-team/ux-researcher-designer/references/persona-methodology.md` + - **Location:** `../../product-team/skills/ux-researcher-designer/references/persona-methodology.md` - **Content:** Research-backed persona creation methodology, data collection strategies, validation approaches - **Use Case:** Methodological guidance for persona projects 2. **Example Personas** - - **Location:** `../../product-team/ux-researcher-designer/references/example-personas.md` + - **Location:** `../../product-team/skills/ux-researcher-designer/references/example-personas.md` - **Content:** Sample persona documents with demographics, goals, pain points, behaviors, scenarios - **Use Case:** Persona format reference, team training 3. **Journey Mapping Guide** - - **Location:** `../../product-team/ux-researcher-designer/references/journey-mapping-guide.md` + - **Location:** `../../product-team/skills/ux-researcher-designer/references/journey-mapping-guide.md` - **Content:** Customer journey mapping methodology, touchpoint analysis, emotion mapping, opportunity identification - **Use Case:** Journey map creation, experience design, service design 4. **Usability Testing Frameworks** - - **Location:** `../../product-team/ux-researcher-designer/references/usability-testing-frameworks.md` + - **Location:** `../../product-team/skills/ux-researcher-designer/references/usability-testing-frameworks.md` - **Content:** Test planning, task design, analysis methods, severity ratings, reporting formats - **Use Case:** Usability study design, prototype validation, UX evaluation 5. **Component Architecture** - - **Location:** `../../product-team/ui-design-system/references/component-architecture.md` + - **Location:** `../../product-team/skills/ui-design-system/references/component-architecture.md` - **Content:** Component hierarchy, atomic design patterns, composition strategies - **Use Case:** Research-to-design translation, component recommendations 6. **Developer Handoff** - - **Location:** `../../product-team/ui-design-system/references/developer-handoff.md` + - **Location:** `../../product-team/skills/ui-design-system/references/developer-handoff.md` - **Content:** Design-to-dev handoff process, specification formats, asset delivery - **Use Case:** Translating research findings into implementation specs ### Templates 1. **Research Plan Template** - - **Location:** `../../product-team/ux-researcher-designer/assets/research_plan_template.md` + - **Location:** `../../product-team/skills/ux-researcher-designer/assets/research_plan_template.md` - **Use Case:** Structuring research studies with methodology, participants, and analysis plan 2. **Design System Documentation Template** - - **Location:** `../../product-team/ui-design-system/assets/design_system_doc_template.md` + - **Location:** `../../product-team/skills/ui-design-system/assets/design_system_doc_template.md` - **Use Case:** Documenting research-informed design system decisions ## Workflows @@ -109,7 +109,7 @@ The cs-ux-researcher agent ensures that user needs drive product development. It 2. **Select Methodology** - Choose the right approach: ```bash # Review usability testing frameworks for method selection - cat ../../product-team/ux-researcher-designer/references/usability-testing-frameworks.md + cat ../../product-team/skills/ux-researcher-designer/references/usability-testing-frameworks.md ``` - **Exploratory** (interviews, contextual inquiry): When learning about problem space - **Evaluative** (usability testing, A/B tests): When validating solutions @@ -125,7 +125,7 @@ The cs-ux-researcher agent ensures that user needs drive product development. It 4. **Create Study Materials** - Prepare research instruments: ```bash # Use the research plan template - cat ../../product-team/ux-researcher-designer/assets/research_plan_template.md + cat ../../product-team/skills/ux-researcher-designer/assets/research_plan_template.md ``` - Interview guide or test script - Task scenarios (for usability tests) @@ -145,13 +145,13 @@ The cs-ux-researcher agent ensures that user needs drive product development. It **Example:** ```bash # Create research plan from template -cp ../../product-team/ux-researcher-designer/assets/research_plan_template.md onboarding-research-plan.md +cp ../../product-team/skills/ux-researcher-designer/assets/research_plan_template.md onboarding-research-plan.md # Review methodology options -cat ../../product-team/ux-researcher-designer/references/usability-testing-frameworks.md +cat ../../product-team/skills/ux-researcher-designer/references/usability-testing-frameworks.md # Review persona methodology for participant criteria -cat ../../product-team/ux-researcher-designer/references/persona-methodology.md +cat ../../product-team/skills/ux-researcher-designer/references/persona-methodology.md ``` ### Workflow 2: Persona Generation @@ -169,9 +169,9 @@ cat ../../product-team/ux-researcher-designer/references/persona-methodology.md 2. **Analyze Interview Data** - Extract structured insights: ```bash # Analyze each interview transcript - python ../../product-team/product-manager-toolkit/scripts/customer_interview_analyzer.py interview-001.txt > insights-001.json - python ../../product-team/product-manager-toolkit/scripts/customer_interview_analyzer.py interview-002.txt > insights-002.json - python ../../product-team/product-manager-toolkit/scripts/customer_interview_analyzer.py interview-003.txt > insights-003.json + python ../../product-team/skills/product-manager-toolkit/scripts/customer_interview_analyzer.py interview-001.txt > insights-001.json + python ../../product-team/skills/product-manager-toolkit/scripts/customer_interview_analyzer.py interview-002.txt > insights-002.json + python ../../product-team/skills/product-manager-toolkit/scripts/customer_interview_analyzer.py interview-003.txt > insights-003.json ``` 3. **Identify Behavioral Segments** - Cluster users by: @@ -184,7 +184,7 @@ cat ../../product-team/ux-researcher-designer/references/persona-methodology.md 4. **Generate Personas** - Create data-backed personas: ```bash # Generate personas from aggregated research - python ../../product-team/ux-researcher-designer/scripts/persona_generator.py research-data.json + python ../../product-team/skills/ux-researcher-designer/scripts/persona_generator.py research-data.json ``` 5. **Validate Personas** - Ensure accuracy: @@ -196,7 +196,7 @@ cat ../../product-team/ux-researcher-designer/references/persona-methodology.md 6. **Socialize Personas** - Make personas actionable: ```bash # Review example personas for format guidance - cat ../../product-team/ux-researcher-designer/references/example-personas.md + cat ../../product-team/skills/ux-researcher-designer/references/example-personas.md ``` - Create one-page persona cards for team walls/wikis - Present to product, engineering, and design teams @@ -216,18 +216,18 @@ echo "===========================" # Step 1: Analyze interviews for f in interviews/*.txt; do base=$(basename "$f" .txt) - python ../../product-team/product-manager-toolkit/scripts/customer_interview_analyzer.py "$f" json > "insights-$base.json" + python ../../product-team/skills/product-manager-toolkit/scripts/customer_interview_analyzer.py "$f" json > "insights-$base.json" echo "Analyzed: $f" done # Step 2: Review persona methodology -cat ../../product-team/ux-researcher-designer/references/persona-methodology.md +cat ../../product-team/skills/ux-researcher-designer/references/persona-methodology.md # Step 3: Generate personas -python ../../product-team/ux-researcher-designer/scripts/persona_generator.py research-data.json +python ../../product-team/skills/ux-researcher-designer/scripts/persona_generator.py research-data.json # Step 4: Review example format -cat ../../product-team/ux-researcher-designer/references/example-personas.md +cat ../../product-team/skills/ux-researcher-designer/references/example-personas.md ``` ### Workflow 3: Journey Mapping @@ -243,7 +243,7 @@ cat ../../product-team/ux-researcher-designer/references/example-personas.md 2. **Review Journey Mapping Methodology** - Understand the framework: ```bash - cat ../../product-team/ux-researcher-designer/references/journey-mapping-guide.md + cat ../../product-team/skills/ux-researcher-designer/references/journey-mapping-guide.md ``` 3. **Map Journey Stages** - Identify key phases: @@ -278,7 +278,7 @@ cat ../../product-team/ux-researcher-designer/references/example-personas.md Self-service help in context,600,2,0.8,2 Upgrade prompt optimization,400,3,0.6,2 EOF - python ../../product-team/product-manager-toolkit/scripts/rice_prioritizer.py journey-opportunities.csv + python ../../product-team/skills/product-manager-toolkit/scripts/rice_prioritizer.py journey-opportunities.csv ``` **Expected Output:** Visual journey map with stages, touchpoints, emotions, pain points, and prioritized improvement opportunities @@ -292,14 +292,14 @@ echo "Journey Mapping - Onboarding Flow" echo "==================================" # Review journey mapping methodology -cat ../../product-team/ux-researcher-designer/references/journey-mapping-guide.md +cat ../../product-team/skills/ux-researcher-designer/references/journey-mapping-guide.md # Analyze relevant interview transcripts for journey insights -python ../../product-team/product-manager-toolkit/scripts/customer_interview_analyzer.py onboarding-interview-01.txt -python ../../product-team/product-manager-toolkit/scripts/customer_interview_analyzer.py onboarding-interview-02.txt +python ../../product-team/skills/product-manager-toolkit/scripts/customer_interview_analyzer.py onboarding-interview-01.txt +python ../../product-team/skills/product-manager-toolkit/scripts/customer_interview_analyzer.py onboarding-interview-02.txt # Prioritize improvement opportunities -python ../../product-team/product-manager-toolkit/scripts/rice_prioritizer.py journey-opportunities.csv +python ../../product-team/skills/product-manager-toolkit/scripts/rice_prioritizer.py journey-opportunities.csv ``` ### Workflow 4: Usability Test Analysis @@ -310,7 +310,7 @@ python ../../product-team/product-manager-toolkit/scripts/rice_prioritizer.py jo 1. **Plan the Test** - Design the study: ```bash # Review usability testing frameworks - cat ../../product-team/ux-researcher-designer/references/usability-testing-frameworks.md + cat ../../product-team/skills/ux-researcher-designer/references/usability-testing-frameworks.md ``` - Define test objectives (what decisions will this inform) - Select test type (moderated/unmoderated, remote/in-person) @@ -324,7 +324,7 @@ python ../../product-team/product-manager-toolkit/scripts/rice_prioritizer.py jo - Note-taking template for observers - Use research plan template for documentation: ```bash - cat ../../product-team/ux-researcher-designer/assets/research_plan_template.md + cat ../../product-team/skills/ux-researcher-designer/assets/research_plan_template.md ``` 3. **Conduct Sessions** - Run 5-8 sessions: @@ -347,8 +347,8 @@ python ../../product-team/product-manager-toolkit/scripts/rice_prioritizer.py jo 5. **Analyze Verbal Feedback** - Extract qualitative insights: ```bash # Analyze session transcripts for themes - python ../../product-team/product-manager-toolkit/scripts/customer_interview_analyzer.py usability-session-01.txt - python ../../product-team/product-manager-toolkit/scripts/customer_interview_analyzer.py usability-session-02.txt + python ../../product-team/skills/product-manager-toolkit/scripts/customer_interview_analyzer.py usability-session-01.txt + python ../../product-team/skills/product-manager-toolkit/scripts/customer_interview_analyzer.py usability-session-02.txt ``` 6. **Create Report and Recommendations** - Deliver findings: @@ -362,7 +362,7 @@ python ../../product-team/product-manager-toolkit/scripts/rice_prioritizer.py jo - Review findings with design team - Map issues to components in design system: ```bash - cat ../../product-team/ui-design-system/references/component-architecture.md + cat ../../product-team/skills/ui-design-system/references/component-architecture.md ``` - Create Jira tickets for each issue - Plan re-test for critical issues after fixes @@ -378,17 +378,17 @@ echo "Usability Test Analysis" echo "=======================" # Review frameworks -cat ../../product-team/ux-researcher-designer/references/usability-testing-frameworks.md +cat ../../product-team/skills/ux-researcher-designer/references/usability-testing-frameworks.md # Analyze each session transcript for i in 1 2 3 4 5; do echo "Session $i Analysis:" - python ../../product-team/product-manager-toolkit/scripts/customer_interview_analyzer.py "usability-session-0$i.txt" + python ../../product-team/skills/product-manager-toolkit/scripts/customer_interview_analyzer.py "usability-session-0$i.txt" echo "" done # Review component architecture for design recommendations -cat ../../product-team/ui-design-system/references/component-architecture.md +cat ../../product-team/skills/ui-design-system/references/component-architecture.md ``` ## Integration Examples @@ -411,7 +411,7 @@ echo "-------------------------------------" for f in discovery-interviews/*.txt; do base=$(basename "$f" .txt) echo "Analyzing: $base" - python ../../product-team/product-manager-toolkit/scripts/customer_interview_analyzer.py "$f" json > "insights/$base.json" + python ../../product-team/skills/product-manager-toolkit/scripts/customer_interview_analyzer.py "$f" json > "insights/$base.json" done # Week 2: Synthesis @@ -420,10 +420,10 @@ echo "Week 2: Generate Personas & Journey Map" echo "----------------------------------------" # Generate personas from aggregated data -python ../../product-team/ux-researcher-designer/scripts/persona_generator.py aggregated-research.json +python ../../product-team/skills/ux-researcher-designer/scripts/persona_generator.py aggregated-research.json # Reference journey mapping guide -echo "Journey mapping guide: ../../product-team/ux-researcher-designer/references/journey-mapping-guide.md" +echo "Journey mapping guide: ../../product-team/skills/ux-researcher-designer/references/journey-mapping-guide.md" ``` ### Example 2: Research Repository Update @@ -439,15 +439,15 @@ echo "================================================" echo "" echo "New Interview Analysis:" for f in new-interviews/*.txt; do - python ../../product-team/product-manager-toolkit/scripts/customer_interview_analyzer.py "$f" + python ../../product-team/skills/product-manager-toolkit/scripts/customer_interview_analyzer.py "$f" echo "---" done # Review and refresh personas echo "" echo "Persona Review:" -echo "Current personas: ../../product-team/ux-researcher-designer/references/example-personas.md" -echo "Methodology: ../../product-team/ux-researcher-designer/references/persona-methodology.md" +echo "Current personas: ../../product-team/skills/ux-researcher-designer/references/example-personas.md" +echo "Methodology: ../../product-team/skills/ux-researcher-designer/references/persona-methodology.md" ``` ### Example 3: Design Handoff with Research Context @@ -462,22 +462,22 @@ echo "========================" # Persona context echo "" echo "1. Active Personas:" -cat ../../product-team/ux-researcher-designer/references/example-personas.md | head -30 +cat ../../product-team/skills/ux-researcher-designer/references/example-personas.md | head -30 # Journey context echo "" echo "2. Journey Map Reference:" -echo "See: ../../product-team/ux-researcher-designer/references/journey-mapping-guide.md" +echo "See: ../../product-team/skills/ux-researcher-designer/references/journey-mapping-guide.md" # Design system alignment echo "" echo "3. Component Architecture:" -echo "See: ../../product-team/ui-design-system/references/component-architecture.md" +echo "See: ../../product-team/skills/ui-design-system/references/component-architecture.md" # Developer handoff process echo "" echo "4. Handoff Process:" -echo "See: ../../product-team/ui-design-system/references/developer-handoff.md" +echo "See: ../../product-team/skills/ui-design-system/references/developer-handoff.md" ``` ## Success Metrics @@ -511,16 +511,16 @@ echo "See: ../../product-team/ui-design-system/references/developer-handoff.md" - [cs-product-manager](cs-product-manager.md) - Product management lifecycle, interview analysis, PRD development - [cs-agile-product-owner](cs-agile-product-owner.md) - Translating research findings into user stories - [cs-product-strategist](cs-product-strategist.md) - Strategic research to validate product vision and positioning -- UI Design System - Design handoff and component recommendations (see `../../product-team/ui-design-system/`) +- UI Design System - Design handoff and component recommendations (see `../../product-team/skills/ui-design-system/`) ## References -- **Primary Skill:** [../../product-team/ux-researcher-designer/SKILL.md](../../product-team/ux-researcher-designer/SKILL.md) -- **Interview Analyzer:** [../../product-team/product-manager-toolkit/SKILL.md](../../product-team/product-manager-toolkit/SKILL.md) -- **Persona Methodology:** [../../product-team/ux-researcher-designer/references/persona-methodology.md](../../product-team/ux-researcher-designer/references/persona-methodology.md) -- **Journey Mapping Guide:** [../../product-team/ux-researcher-designer/references/journey-mapping-guide.md](../../product-team/ux-researcher-designer/references/journey-mapping-guide.md) -- **Usability Testing:** [../../product-team/ux-researcher-designer/references/usability-testing-frameworks.md](../../product-team/ux-researcher-designer/references/usability-testing-frameworks.md) -- **Design System:** [../../product-team/ui-design-system/SKILL.md](../../product-team/ui-design-system/SKILL.md) +- **Primary Skill:** [../../product-team/skills/ux-researcher-designer/SKILL.md](../../product-team/skills/ux-researcher-designer/SKILL.md) +- **Interview Analyzer:** [../../product-team/skills/product-manager-toolkit/SKILL.md](../../product-team/skills/product-manager-toolkit/SKILL.md) +- **Persona Methodology:** [../../product-team/skills/ux-researcher-designer/references/persona-methodology.md](../../product-team/skills/ux-researcher-designer/references/persona-methodology.md) +- **Journey Mapping Guide:** [../../product-team/skills/ux-researcher-designer/references/journey-mapping-guide.md](../../product-team/skills/ux-researcher-designer/references/journey-mapping-guide.md) +- **Usability Testing:** [../../product-team/skills/ux-researcher-designer/references/usability-testing-frameworks.md](../../product-team/skills/ux-researcher-designer/references/usability-testing-frameworks.md) +- **Design System:** [../../product-team/skills/ui-design-system/SKILL.md](../../product-team/skills/ui-design-system/SKILL.md) - **Product Domain Guide:** [../../product-team/CLAUDE.md](../../product-team/CLAUDE.md) - **Agent Development Guide:** [../CLAUDE.md](../CLAUDE.md) diff --git a/agents/project-management/cs-project-manager.md b/agents/project-management/cs-project-manager.md index db3c2f75..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 @@ -21,103 +21,103 @@ The cs-project-manager agent bridges the gap between project execution and strat ### Senior PM -**Skill Location:** `../../project-management/senior-pm/` +**Skill Location:** `../../project-management/skills/senior-pm/` **Python Tools:** 1. **Project Health Dashboard** - **Purpose:** Generate portfolio-level health dashboard with RAG status across all active projects - - **Path:** `../../project-management/senior-pm/scripts/project_health_dashboard.py` - - **Usage:** `python ../../project-management/senior-pm/scripts/project_health_dashboard.py sample_project_data.json` + - **Path:** `../../project-management/skills/senior-pm/scripts/project_health_dashboard.py` + - **Usage:** `python ../../project-management/skills/senior-pm/scripts/project_health_dashboard.py sample_project_data.json` - **Features:** Schedule variance, budget tracking, risk exposure, milestone status, RAG indicators 2. **Risk Matrix Analyzer** - **Purpose:** Quantitative risk analysis with probability-impact matrices and Expected Monetary Value (EMV) - - **Path:** `../../project-management/senior-pm/scripts/risk_matrix_analyzer.py` - - **Usage:** `python ../../project-management/senior-pm/scripts/risk_matrix_analyzer.py risks.json` + - **Path:** `../../project-management/skills/senior-pm/scripts/risk_matrix_analyzer.py` + - **Usage:** `python ../../project-management/skills/senior-pm/scripts/risk_matrix_analyzer.py risks.json` - **Features:** Risk scoring, heat map generation, mitigation tracking, EMV calculation 3. **Resource Capacity Planner** - **Purpose:** Team resource allocation and capacity forecasting across sprints and projects - - **Path:** `../../project-management/senior-pm/scripts/resource_capacity_planner.py` - - **Usage:** `python ../../project-management/senior-pm/scripts/resource_capacity_planner.py team_data.json` + - **Path:** `../../project-management/skills/senior-pm/scripts/resource_capacity_planner.py` + - **Usage:** `python ../../project-management/skills/senior-pm/scripts/resource_capacity_planner.py team_data.json` - **Features:** Utilization analysis, over-allocation detection, capacity forecasting, cross-project balancing **Knowledge Bases:** -- `../../project-management/senior-pm/references/portfolio-prioritization-models.md` -- WSJF, MoSCoW, Cost of Delay, portfolio scoring frameworks -- `../../project-management/senior-pm/references/risk-management-framework.md` -- Risk identification, qualitative/quantitative analysis, response strategies -- `../../project-management/senior-pm/references/portfolio-kpis.md` -- KPI definitions, tracking cadences, executive reporting metrics +- `../../project-management/skills/senior-pm/references/portfolio-prioritization-models.md` -- WSJF, MoSCoW, Cost of Delay, portfolio scoring frameworks +- `../../project-management/skills/senior-pm/references/risk-management-framework.md` -- Risk identification, qualitative/quantitative analysis, response strategies +- `../../project-management/skills/senior-pm/references/portfolio-kpis.md` -- KPI definitions, tracking cadences, executive reporting metrics **Templates:** -- `../../project-management/senior-pm/assets/executive_report_template.md` -- Executive status report with RAG, risks, decisions needed -- `../../project-management/senior-pm/assets/project_charter_template.md` -- Project charter with scope, objectives, constraints, stakeholders -- `../../project-management/senior-pm/assets/raci_matrix_template.md` -- Responsibility assignment matrix for cross-functional teams +- `../../project-management/skills/senior-pm/assets/executive_report_template.md` -- Executive status report with RAG, risks, decisions needed +- `../../project-management/skills/senior-pm/assets/project_charter_template.md` -- Project charter with scope, objectives, constraints, stakeholders +- `../../project-management/skills/senior-pm/assets/raci_matrix_template.md` -- Responsibility assignment matrix for cross-functional teams ### Scrum Master -**Skill Location:** `../../project-management/scrum-master/` +**Skill Location:** `../../project-management/skills/scrum-master/` **Python Tools:** 1. **Sprint Health Scorer** - **Purpose:** Quantitative sprint health assessment across scope, velocity, quality, and team morale - - **Path:** `../../project-management/scrum-master/scripts/sprint_health_scorer.py` - - **Usage:** `python ../../project-management/scrum-master/scripts/sprint_health_scorer.py sample_sprint_data.json` + - **Path:** `../../project-management/skills/scrum-master/scripts/sprint_health_scorer.py` + - **Usage:** `python ../../project-management/skills/scrum-master/scripts/sprint_health_scorer.py sample_sprint_data.json` - **Features:** Multi-dimensional scoring (0-100), trend analysis, health indicators, actionable recommendations 2. **Velocity Analyzer** - **Purpose:** Historical velocity analysis with forecasting and confidence intervals - - **Path:** `../../project-management/scrum-master/scripts/velocity_analyzer.py` - - **Usage:** `python ../../project-management/scrum-master/scripts/velocity_analyzer.py sprint_history.json` + - **Path:** `../../project-management/skills/scrum-master/scripts/velocity_analyzer.py` + - **Usage:** `python ../../project-management/skills/scrum-master/scripts/velocity_analyzer.py sprint_history.json` - **Features:** Rolling averages, standard deviation, sprint-over-sprint trends, capacity prediction 3. **Retrospective Analyzer** - **Purpose:** Structured retrospective analysis with action item tracking and theme extraction - - **Path:** `../../project-management/scrum-master/scripts/retrospective_analyzer.py` - - **Usage:** `python ../../project-management/scrum-master/scripts/retrospective_analyzer.py retro_notes.json` + - **Path:** `../../project-management/skills/scrum-master/scripts/retrospective_analyzer.py` + - **Usage:** `python ../../project-management/skills/scrum-master/scripts/retrospective_analyzer.py retro_notes.json` - **Features:** Theme clustering, sentiment analysis, action item extraction, trend tracking across sprints **Knowledge Bases:** -- `../../project-management/scrum-master/references/retro-formats.md` -- Start/Stop/Continue, 4Ls, Sailboat, Mad/Sad/Glad, Starfish formats -- `../../project-management/scrum-master/references/team-dynamics-framework.md` -- Tuckman stages, psychological safety, conflict resolution -- `../../project-management/scrum-master/references/velocity-forecasting-guide.md` -- Monte Carlo simulation, confidence ranges, capacity planning +- `../../project-management/skills/scrum-master/references/retro-formats.md` -- Start/Stop/Continue, 4Ls, Sailboat, Mad/Sad/Glad, Starfish formats +- `../../project-management/skills/scrum-master/references/team-dynamics-framework.md` -- Tuckman stages, psychological safety, conflict resolution +- `../../project-management/skills/scrum-master/references/velocity-forecasting-guide.md` -- Monte Carlo simulation, confidence ranges, capacity planning **Templates:** -- `../../project-management/scrum-master/assets/sprint_report_template.md` -- Sprint review report with burndown, velocity, demo notes -- `../../project-management/scrum-master/assets/team_health_check_template.md` -- Spotify-style team health check across 8 dimensions +- `../../project-management/skills/scrum-master/assets/sprint_report_template.md` -- Sprint review report with burndown, velocity, demo notes +- `../../project-management/skills/scrum-master/assets/team_health_check_template.md` -- Spotify-style team health check across 8 dimensions ### Jira Expert -**Skill Location:** `../../project-management/jira-expert/` +**Skill Location:** `../../project-management/skills/jira-expert/` **Knowledge Bases:** -- `../../project-management/jira-expert/references/jql-examples.md` -- JQL query patterns for backlog grooming, sprint reporting, SLA tracking -- `../../project-management/jira-expert/references/automation-examples.md` -- Jira automation rule templates for common workflows -- `../../project-management/jira-expert/references/AUTOMATION.md` -- Comprehensive automation guide with triggers, conditions, actions -- `../../project-management/jira-expert/references/WORKFLOWS.md` -- Workflow design patterns, transition rules, validators, post-functions +- `../../project-management/skills/jira-expert/references/jql-examples.md` -- JQL query patterns for backlog grooming, sprint reporting, SLA tracking +- `../../project-management/skills/jira-expert/references/automation-examples.md` -- Jira automation rule templates for common workflows +- `../../project-management/skills/jira-expert/references/AUTOMATION.md` -- Comprehensive automation guide with triggers, conditions, actions +- `../../project-management/skills/jira-expert/references/WORKFLOWS.md` -- Workflow design patterns, transition rules, validators, post-functions ### Confluence Expert -**Skill Location:** `../../project-management/confluence-expert/` +**Skill Location:** `../../project-management/skills/confluence-expert/` **Knowledge Bases:** -- `../../project-management/confluence-expert/references/templates.md` -- Page templates for sprint plans, meeting notes, decision logs, architecture docs +- `../../project-management/skills/confluence-expert/references/templates.md` -- Page templates for sprint plans, meeting notes, decision logs, architecture docs ### Atlassian Admin -**Skill Location:** `../../project-management/atlassian-admin/` +**Skill Location:** `../../project-management/skills/atlassian-admin/` Covers user provisioning, permission schemes, project configuration, and integration setup. No scripts or references yet -- relies on SKILL.md workflows. ### Atlassian Templates -**Skill Location:** `../../project-management/atlassian-templates/` +**Skill Location:** `../../project-management/skills/atlassian-templates/` Covers blueprint creation, custom page layouts, and reusable Confluence/Jira components. No scripts or references yet -- relies on SKILL.md workflows. @@ -131,37 +131,37 @@ Covers blueprint creation, custom page layouts, and reusable Confluence/Jira com 1. **Analyze Velocity History** - Review past sprint performance to set realistic capacity: ```bash - python ../../project-management/scrum-master/scripts/velocity_analyzer.py sprint_history.json + python ../../project-management/skills/scrum-master/scripts/velocity_analyzer.py sprint_history.json ``` - Review rolling average velocity and standard deviation - Identify trends (accelerating, decelerating, stable) - Set sprint capacity at 80% of average velocity (buffer for unknowns) 2. **Query Backlog via JQL** - Use jira-expert JQL patterns to pull prioritized candidates: - - Reference: `../../project-management/jira-expert/references/jql-examples.md` + - Reference: `../../project-management/skills/jira-expert/references/jql-examples.md` - Filter by priority, story points estimated, team assignment - Identify blocked items, external dependencies, carry-overs from previous sprint 3. **Check Resource Availability** - Verify team capacity for the sprint window: ```bash - python ../../project-management/senior-pm/scripts/resource_capacity_planner.py team_data.json + python ../../project-management/skills/senior-pm/scripts/resource_capacity_planner.py team_data.json ``` - Account for PTO, holidays, shared resources - Flag over-allocated team members - Adjust sprint capacity based on actual availability 4. **Select Sprint Backlog** - Commit items within capacity: - - Apply WSJF or priority-based selection (ref: `../../project-management/senior-pm/references/portfolio-prioritization-models.md`) + - Apply WSJF or priority-based selection (ref: `../../project-management/skills/senior-pm/references/portfolio-prioritization-models.md`) - Ensure sprint goal alignment -- every item should contribute to 1-2 goals - Include 10-15% capacity for bug fixes and operational work 5. **Document Sprint Plan** - Create Confluence sprint plan page: - - Use template from `../../project-management/confluence-expert/references/templates.md` + - Use template from `../../project-management/skills/confluence-expert/references/templates.md` - Include sprint goal, committed stories, capacity breakdown, risks - Link to Jira sprint board for live tracking 6. **Set Up Sprint Tracking** - Configure dashboards and automation: - - Create burndown/burnup dashboard (ref: `../../project-management/jira-expert/references/AUTOMATION.md`) + - Create burndown/burnup dashboard (ref: `../../project-management/skills/jira-expert/references/AUTOMATION.md`) - Set up daily standup reminder automation - Configure sprint scope change alerts @@ -172,8 +172,8 @@ Covers blueprint creation, custom page layouts, and reusable Confluence/Jira com **Example:** ```bash # Full sprint planning workflow -python ../../project-management/scrum-master/scripts/velocity_analyzer.py sprint_history.json > velocity_report.txt -python ../../project-management/senior-pm/scripts/resource_capacity_planner.py team_data.json > capacity_report.txt +python ../../project-management/skills/scrum-master/scripts/velocity_analyzer.py sprint_history.json > velocity_report.txt +python ../../project-management/skills/senior-pm/scripts/resource_capacity_planner.py team_data.json > capacity_report.txt cat velocity_report.txt cat capacity_report.txt # Use velocity average and capacity data to commit sprint items @@ -193,7 +193,7 @@ cat capacity_report.txt 2. **Generate Health Dashboard** - Run project health analysis: ```bash - python ../../project-management/senior-pm/scripts/project_health_dashboard.py portfolio_data.json + python ../../project-management/skills/senior-pm/scripts/project_health_dashboard.py portfolio_data.json ``` - Review per-project RAG status (Red/Amber/Green) - Identify projects requiring intervention @@ -201,7 +201,7 @@ cat capacity_report.txt 3. **Analyze Risk Exposure** - Quantify portfolio-level risk: ```bash - python ../../project-management/senior-pm/scripts/risk_matrix_analyzer.py portfolio_risks.json + python ../../project-management/skills/senior-pm/scripts/risk_matrix_analyzer.py portfolio_risks.json ``` - Calculate EMV for each risk - Identify top-10 risks by exposure @@ -210,20 +210,20 @@ cat capacity_report.txt 4. **Review Resource Utilization** - Check cross-project allocation: ```bash - python ../../project-management/senior-pm/scripts/resource_capacity_planner.py all_teams.json + python ../../project-management/skills/senior-pm/scripts/resource_capacity_planner.py all_teams.json ``` - Identify over-allocated individuals (>100% utilization) - Find under-utilized capacity for rebalancing - Forecast resource needs for next quarter 5. **Prepare Executive Report** - Assemble findings into report: - - Use template: `../../project-management/senior-pm/assets/executive_report_template.md` + - Use template: `../../project-management/skills/senior-pm/assets/executive_report_template.md` - Include RAG summary, risk heatmap, resource utilization chart - Highlight decisions needed from leadership - Provide recommendations with supporting data 6. **Publish to Confluence** - Create executive dashboard page: - - Reference KPI definitions from `../../project-management/senior-pm/references/portfolio-kpis.md` + - Reference KPI definitions from `../../project-management/skills/senior-pm/references/portfolio-kpis.md` - Embed Jira macros for live data - Set up weekly refresh cadence @@ -234,9 +234,9 @@ cat capacity_report.txt **Example:** ```bash # Portfolio health review automation -python ../../project-management/senior-pm/scripts/project_health_dashboard.py portfolio_data.json > health_dashboard.txt -python ../../project-management/senior-pm/scripts/risk_matrix_analyzer.py portfolio_risks.json > risk_report.txt -python ../../project-management/senior-pm/scripts/resource_capacity_planner.py all_teams.json > resource_report.txt +python ../../project-management/skills/senior-pm/scripts/project_health_dashboard.py portfolio_data.json > health_dashboard.txt +python ../../project-management/skills/senior-pm/scripts/risk_matrix_analyzer.py portfolio_risks.json > risk_report.txt +python ../../project-management/skills/senior-pm/scripts/resource_capacity_planner.py all_teams.json > resource_report.txt cat health_dashboard.txt cat risk_report.txt cat resource_report.txt @@ -250,14 +250,14 @@ cat resource_report.txt 1. **Gather Sprint Metrics** - Collect quantitative data before the retro: ```bash - python ../../project-management/scrum-master/scripts/sprint_health_scorer.py sprint_data.json + python ../../project-management/skills/scrum-master/scripts/sprint_health_scorer.py sprint_data.json ``` - Review sprint health score (0-100) - Identify scoring dimensions that dropped (scope, velocity, quality, morale) - Compare against previous sprint scores for trend analysis 2. **Select Retro Format** - Choose format based on team needs: - - Reference: `../../project-management/scrum-master/references/retro-formats.md` + - Reference: `../../project-management/skills/scrum-master/references/retro-formats.md` - **Start/Stop/Continue**: General-purpose, good for new teams - **4Ls (Liked/Learned/Lacked/Longed For)**: Focuses on learning and growth - **Sailboat**: Visual metaphor for anchors (blockers) and wind (accelerators) @@ -268,11 +268,11 @@ cat resource_report.txt - Present sprint metrics as context (not judgment) - Time-box each section (5 min brainstorm, 10 min discuss, 5 min vote) - Use dot voting to prioritize discussion topics - - Reference team dynamics from `../../project-management/scrum-master/references/team-dynamics-framework.md` + - Reference team dynamics from `../../project-management/skills/scrum-master/references/team-dynamics-framework.md` 4. **Analyze Retro Output** - Extract structured insights: ```bash - python ../../project-management/scrum-master/scripts/retrospective_analyzer.py retro_notes.json + python ../../project-management/skills/scrum-master/scripts/retrospective_analyzer.py retro_notes.json ``` - Identify recurring themes across sprints - Cluster related items into improvement areas @@ -285,7 +285,7 @@ cat resource_report.txt - Add action items to next sprint backlog 6. **Document in Confluence** - Publish retro summary: - - Use sprint report template: `../../project-management/scrum-master/assets/sprint_report_template.md` + - Use sprint report template: `../../project-management/skills/scrum-master/assets/sprint_report_template.md` - Include sprint health score, retro themes, action items, metrics trends - Link to previous retro pages for longitudinal tracking @@ -301,11 +301,11 @@ cat resource_report.txt **Example:** ```bash # Pre-retro data collection -python ../../project-management/scrum-master/scripts/sprint_health_scorer.py sprint_data.json > health_score.txt -python ../../project-management/scrum-master/scripts/velocity_analyzer.py sprint_history.json > velocity_trend.txt +python ../../project-management/skills/scrum-master/scripts/sprint_health_scorer.py sprint_data.json > health_score.txt +python ../../project-management/skills/scrum-master/scripts/velocity_analyzer.py sprint_history.json > velocity_trend.txt cat health_score.txt # Use health score insights to guide retro discussion -python ../../project-management/scrum-master/scripts/retrospective_analyzer.py retro_notes.json > retro_analysis.txt +python ../../project-management/skills/scrum-master/scripts/retrospective_analyzer.py retro_notes.json > retro_analysis.txt cat retro_analysis.txt ``` @@ -328,22 +328,22 @@ cat retro_analysis.txt - Define priority scheme and SLA targets 3. **Design Workflows** - Build workflows matching team process: - - Reference: `../../project-management/jira-expert/references/WORKFLOWS.md` + - Reference: `../../project-management/skills/jira-expert/references/WORKFLOWS.md` - Map states: Backlog > Ready > In Progress > Review > QA > Done - Add transitions with conditions (e.g., assignee required for In Progress) - Configure validators (e.g., story points required before Done) - Set up post-functions (e.g., auto-assign reviewer, notify channel) 4. **Configure Automation** - Set up time-saving automation rules: - - Reference: `../../project-management/jira-expert/references/AUTOMATION.md` - - Examples from: `../../project-management/jira-expert/references/automation-examples.md` + - Reference: `../../project-management/skills/jira-expert/references/AUTOMATION.md` + - Examples from: `../../project-management/skills/jira-expert/references/automation-examples.md` - Auto-transition: Move to In Progress when branch created - Auto-assign: Rotate assignments based on workload - Notifications: Slack alerts for blocked items, SLA breaches - Cleanup: Auto-close stale items after 30 days 5. **Set Up Confluence Space** - Create team knowledge base: - - Reference: `../../project-management/confluence-expert/references/templates.md` + - Reference: `../../project-management/skills/confluence-expert/references/templates.md` - Create space with standard page hierarchy: - Home (team overview, quick links) - Sprint Plans (per-sprint documentation) @@ -357,7 +357,7 @@ cat retro_analysis.txt - Burndown/burnup chart gadget - Velocity chart for historical tracking - SLA compliance tracker - - Use JQL patterns from `../../project-management/jira-expert/references/jql-examples.md` + - Use JQL patterns from `../../project-management/skills/jira-expert/references/jql-examples.md` 7. **Onboard Team** - Walk team through the setup: - Document workflow rules and why they exist @@ -383,22 +383,22 @@ echo "============================================" # Sprint health assessment echo "" echo "Sprint Health:" -python ../../project-management/scrum-master/scripts/sprint_health_scorer.py current_sprint.json +python ../../project-management/skills/scrum-master/scripts/sprint_health_scorer.py current_sprint.json # Velocity trend echo "" echo "Velocity Trend:" -python ../../project-management/scrum-master/scripts/velocity_analyzer.py sprint_history.json +python ../../project-management/skills/scrum-master/scripts/velocity_analyzer.py sprint_history.json # Risk exposure echo "" echo "Active Risks:" -python ../../project-management/senior-pm/scripts/risk_matrix_analyzer.py active_risks.json +python ../../project-management/skills/senior-pm/scripts/risk_matrix_analyzer.py active_risks.json # Resource utilization echo "" echo "Team Capacity:" -python ../../project-management/senior-pm/scripts/resource_capacity_planner.py team_data.json +python ../../project-management/skills/senior-pm/scripts/resource_capacity_planner.py team_data.json ``` ### Example 2: Sprint Retrospective Pipeline @@ -414,19 +414,19 @@ echo "==========================================" # Step 1: Score sprint health echo "" echo "1. Sprint Health Score:" -python ../../project-management/scrum-master/scripts/sprint_health_scorer.py sprint_${SPRINT_NUM}.json > sprint_health.txt +python ../../project-management/skills/scrum-master/scripts/sprint_health_scorer.py sprint_${SPRINT_NUM}.json > sprint_health.txt cat sprint_health.txt # Step 2: Analyze velocity trend echo "" echo "2. Velocity Analysis:" -python ../../project-management/scrum-master/scripts/velocity_analyzer.py velocity_history.json > velocity.txt +python ../../project-management/skills/scrum-master/scripts/velocity_analyzer.py velocity_history.json > velocity.txt cat velocity.txt # Step 3: Process retro notes echo "" echo "3. Retrospective Themes:" -python ../../project-management/scrum-master/scripts/retrospective_analyzer.py retro_sprint_${SPRINT_NUM}.json > retro_analysis.txt +python ../../project-management/skills/scrum-master/scripts/retrospective_analyzer.py retro_sprint_${SPRINT_NUM}.json > retro_analysis.txt cat retro_analysis.txt echo "" @@ -446,24 +446,24 @@ echo "================================" # Project health across portfolio echo "" echo "Project Health (All Active):" -python ../../project-management/senior-pm/scripts/project_health_dashboard.py portfolio_$MONTH.json > dashboard.txt +python ../../project-management/skills/senior-pm/scripts/project_health_dashboard.py portfolio_$MONTH.json > dashboard.txt cat dashboard.txt # Risk heatmap echo "" echo "Risk Exposure Summary:" -python ../../project-management/senior-pm/scripts/risk_matrix_analyzer.py risks_$MONTH.json > risks.txt +python ../../project-management/skills/senior-pm/scripts/risk_matrix_analyzer.py risks_$MONTH.json > risks.txt cat risks.txt # Resource forecast echo "" echo "Resource Utilization:" -python ../../project-management/senior-pm/scripts/resource_capacity_planner.py resources_$MONTH.json > capacity.txt +python ../../project-management/skills/senior-pm/scripts/resource_capacity_planner.py resources_$MONTH.json > capacity.txt cat capacity.txt echo "" echo "Dashboard generated. Use executive_report_template.md to assemble final report." -echo "Template: ../../project-management/senior-pm/assets/executive_report_template.md" +echo "Template: ../../project-management/skills/senior-pm/assets/executive_report_template.md" ``` ## Success Metrics @@ -500,11 +500,11 @@ echo "Template: ../../project-management/senior-pm/assets/executive_report_templ ## References -- **Senior PM Skill:** [../../project-management/senior-pm/SKILL.md](../../project-management/senior-pm/SKILL.md) -- **Scrum Master Skill:** [../../project-management/scrum-master/SKILL.md](../../project-management/scrum-master/SKILL.md) -- **Jira Expert Skill:** [../../project-management/jira-expert/SKILL.md](../../project-management/jira-expert/SKILL.md) -- **Confluence Expert Skill:** [../../project-management/confluence-expert/SKILL.md](../../project-management/confluence-expert/SKILL.md) -- **Atlassian Admin Skill:** [../../project-management/atlassian-admin/SKILL.md](../../project-management/atlassian-admin/SKILL.md) +- **Senior PM Skill:** [../../project-management/skills/senior-pm/SKILL.md](../../project-management/skills/senior-pm/SKILL.md) +- **Scrum Master Skill:** [../../project-management/skills/scrum-master/SKILL.md](../../project-management/skills/scrum-master/SKILL.md) +- **Jira Expert Skill:** [../../project-management/skills/jira-expert/SKILL.md](../../project-management/skills/jira-expert/SKILL.md) +- **Confluence Expert Skill:** [../../project-management/skills/confluence-expert/SKILL.md](../../project-management/skills/confluence-expert/SKILL.md) +- **Atlassian Admin Skill:** [../../project-management/skills/atlassian-admin/SKILL.md](../../project-management/skills/atlassian-admin/SKILL.md) - **PM Domain Guide:** [../../project-management/CLAUDE.md](../../project-management/CLAUDE.md) - **Agent Development Guide:** [../CLAUDE.md](../CLAUDE.md) diff --git a/audit/newgen-2026-06/00-MASTER.md b/audit/newgen-2026-06/00-MASTER.md new file mode 100644 index 00000000..091fb8c5 --- /dev/null +++ b/audit/newgen-2026-06/00-MASTER.md @@ -0,0 +1,117 @@ +# Master Audit Report — New-Generation Model Optimization + +**Audited:** 2026-06-10 · **Branch:** `claude/skills-plugins-audit-vrttx1` · **Scope:** every canonical skill, plugin, agent, slash command, script, and registry surface (sync copies under `.codex/ .gemini/ .hermes/ .vibe/` excluded as derived artifacts). + +**Method:** two automated sweep layers (the repo's own `audit_skills.py` checklist + a custom new-gen sweep for triggers, verification loops, placeholders, stale models, dead links, duplicate content) followed by 10 parallel domain deep-dives that read every SKILL.md, spot-checked references and scripts, and **executed** empirical claims where the skills make them. Rubric: [RUBRIC.md](RUBRIC.md). + +--- + +## 1. Repo-wide scorecard + +**324 unique skills** audited (346 SKILL.md files minus dual-published copies and meta/index files counted once): + +| Verdict | Count | % | Meaning | +|---|---|---|---| +| **KEEP** | 190 | 59% | Ships as-is; verification criteria recorded per skill in domain reports | +| **OPTIMIZE** | 102 | 31% | Targeted edits (wiring, triggers, freshness) — content core is sound | +| **REWRITE** | 16 | 5% | Structure salvageable, content is not | +| **CUT-OR-MERGE** | 16 | 5% | Does not earn its context window | + +Per domain (links go to the detailed reports with **per-skill custom verification criteria**): + +| Domain report | Skills | KEEP | OPT | REW | CUT | Health | +|---|---|---|---|---|---|---| +| [productivity + markdown-html](productivity-markdown-html.md) | 11 | 9 | 2 | 0 | 0 | ★ best — 24/27 live checks pass | +| [research + research-ops](research.md) | 13 | 5 | 7 | 1 | 0 | research-ops all-KEEP; research/ needs wiring | +| [bizops + commercial + finance + growth](bizops-commercial-finance.md) | 24 | 14 | 8 | 0 | 2 | v2.8.0 verified; finance/ legacy | +| [c-level-advisor](c-level-advisor.md) | 61 | 40 | 20 | 0 | 1 | strong content, broken wiring | +| [engineering](engineering.md) | 63 | 44 | 8 | 7 | 4 | two generations coexist | +| [engineering-team](engineering-team.md) | 51 | 35 | 13 | 2 | 1 | code-corruption + stale-era issues | +| [compliance (ra-qm + compliance-os)](compliance.md) | 26 | 13 | 11 | 1 | 1 | P0 regulatory staleness | +| [marketing](marketing.md) | 49 | 20 | 24 | 1 | 4 | orphan scripts + path schism | +| [product-team + project-management](product-pm.md) | 26 | 10 | 9 | 4 | 3 | fabricated MCP wiring | +| [cross-cutting infra](cross-cutting.md) | — | — | — | — | — | registries, CI, root agents/commands | + +**Other artifact classes:** 92 agents (17 of 32 root agents lack trigger descriptions; 7 of 13 c-level personas cite phantom reference files; 2 missing frontmatter) · 99 commands (9 root commands are cut/merge candidates; 28 of 39 root commands invoke phantom script paths) · 77 plugin manifests (all schema-valid; **11 not registered in marketplace.json**) · 593 scripts (583 pass `--help`; 1 real crash; 9 by-design). + +--- + +## 2. P0 — Correctness defects (fix before anything else) + +These cause a model following the skill to produce **wrong or dangerous output today**: + +| # | Defect | Where | Evidence | +|---|---|---|---| +| P0-1 | **Repealed regulation taught as current law.** QSR (21 CFR 820 subsections) presented as in force; QMSR (effective 2026-02-02) never mentioned. Reference + `qsr_compliance_checker.py --section 820.30` built on removed section numbers. | `ra-qm-team/skills/fda-consultant-specialist` | [compliance.md](compliance.md) | +| P0-2 | **ALARP table violates EU MDR.** Risk-acceptability framework includes "cost-benefit of further reduction," which MDR Annex I + EN ISO 14971:2019/A11 prohibit. A notified body would flag this exact table. | `ra-qm-team/skills/risk-management-specialist` | [compliance.md](compliance.md) | +| P0-3 | **EU AI Act Article 5 mis-taught.** Default sample classifies *retail* emotion recognition as prohibited; Art. 5(1)(f) covers workplace/education only. | `ra-qm-team/skills/eu-ai-act-specialist` | [compliance.md](compliance.md) | +| P0-4 | **Silent zero-output finance tools.** All 4 scripts read the wrong JSON shape vs their own bundled sample: zero ratios, $0.00 forecasts, error message then `exit 0`. Invisible to `--help` smoke tests. | `finance/financial-analyst` | [bizops-commercial-finance.md](bizops-commercial-finance.md) | +| P0-5 | **Contradictory discount-margin math.** SKILL.md states the correct fixed-COGS formula; `deal_scorer.py` + reference use a different one (script docstring writes the correct formula, then discards it). Margin dimension (weight 0.30) understates discount damage. | `commercial/deal-desk` | [bizops-commercial-finance.md](bizops-commercial-finance.md) | +| P0-6 | **Corrupted code examples from a past bulk YAML-quoting sweep.** E.g. `z.string().min(1).max(100)` → `"zstringmin1max100"`. 4 confirmed sites; models copying these emit broken code. | `engineering-team` senior-qa:123/244, senior-backend:253, senior-frontend:425 | [engineering-team.md](engineering-team.md) | +| P0-7 | **Fabricated MCP tool names.** 3 Atlassian skills + project-management/CLAUDE.md document four different invented naming conventions; none match the bundled Remote MCP's real tools (`createJiraIssue`, `searchJiraIssuesUsingJql`, …). Every documented tool call fails. | `project-management/` (jira-expert, confluence-expert, atlassian-templates) | [product-pm.md](product-pm.md) | +| P0-8 | **Fabricated install coordinates.** Whole skill teaches a `gws` CLI from `npm i -g @anthropic/gws` / `github.com/googleworkspace/cli` — both almost certainly nonexistent; 43 recipes + 5 wrappers unusable. | `engineering-team/skills/google-workspace-cli` | [engineering-team.md](engineering-team.md) | +| P0-9 | **Skill instructs invoking agents that don't exist in this repo** (documents a different ecosystem: `planner`, `/build-fix`, …). | `engineering/skills/command-guide` | [engineering.md](engineering.md) | +| P0-10 | **Stale orchestrator text bypasses shipped converters.** "v2.10.0 foundation" wording tells the model to hand-render HTML instead of routing to md-document/md-review/md-slides, which shipped. Behavioral, not cosmetic. | `markdown-html/` orchestrator (+ domain CLAUDE.md, README) | [productivity-markdown-html.md](productivity-markdown-html.md) | +| P0-11 | **Script crash:** no argparse; `--help` (or any flag) treated as input filename → FileNotFoundError. Skill's only tool. | `marketing-skill/skills/webinar-marketing/scripts/webinar_funnel_scorer.py` | [marketing.md](marketing.md) | + +--- + +## 3. P1 — Systemic wiring failures (one fix clears many skills) + +1. **Phantom-path epidemic (the single biggest repo-wide defect).** A directory reorg added a `skills/` path segment; references never followed. **28 of 39 root commands** invoke scripts at `//scripts/…` that live at `/skills//scripts/…`; same stale shorthand in agents' `skills:` frontmatter, `orchestration/ORCHESTRATION.md` (points at skills that exist only as .zip archives), product/PM routers, c-level persona agents (~16 phantom reference filenames across 7 agents), email agents (`engineering/email/...` → `productivity/email/`), and **5 research skills whose final verification step calls `scripts/office/validate.py` — a file that exists nowhere**. → Build a path-existence linter (see §5) and fix in one sweep. +2. **Orphan-script epidemic.** 40+ working, `--help`-passing scripts are never named in their own SKILL.md (24 in marketing, 8 in product/PM, 6+ in engineering, reflect's all-3, ms365, incident-commander). The model loading these skills cannot use their best assets. → A3 wiring pass: exact CLI + consume-the-output step per script. +3. **Counter drift is structural.** Seven surfaces disagree (README 338 skills / CLAUDE.md header 338 / CLAUDE.md v2.10.3 block 343 / marketplace.json description 64 plugins while containing 66 / actual: **346-347 skills, 66 registered + 11 unregistered plugins, 555 tools, 700 references, 17 domains**). agents/CLAUDE.md says 16 agents; folder has 32. → Derive all counters from the tree via script; never hand-edit again. +4. **11 shippable plugins not in marketplace.json** — compliance-os (advertised in the marketplace's own description yet uninstallable), snowflake-development, behuman, claude-coach, grill-with-docs, llm-cost-optimizer, prompt-governance, business-investment-advisor, video-content-strategist, 2× ra-qm compliance-team. +5. **Marketing context-file path schism.** 19 skills read `.claude/product-marketing-context.md`, 16 read `marketing-context.md`, the creator skill writes `.agents/marketing-context.md`. The domain's "read context first" pattern silently no-ops for half its consumers. +6. **c-level role-registry drift.** Routing tables (agent-protocol, chief-of-staff, board-meeting, founder-mode, brief, c-level-agents frontmatter) stopped at 9 roles; domain has 14. CCO/CDO/CAIO/VPE questions silently misroute. Plus three competing decision-memory architectures and two onboarding interviews writing different schemas to the same file. +7. **Dual-publishing without a guard.** 11 byte-identical skill pairs (engineering ×4, c-level ×5, ra-qm ×2). Zero drift today — but no sync script and no CI check; drift is a matter of time. +8. **Trigger-description gap.** 79 skills and 77 of 92 agents lack "use when" phrasing — weak auto-invocation for new-gen models. Root cause for agents: `templates/agent-template.md` mandates a sub-150-char description with no trigger requirement. 8 v2.8.0 descriptions exceed the 1024-char spec limit (knowledge-ops 1,314 — this, not content, is why it "scored worst"). +9. **Meta-tooling violates its own rubric.** `audit_skills.py --help` runs the full 30s audit; `generate-docs.py --help` **rewrites docs/ as a side effect** (verified live — this explains the dirty docs/ files found at session start); hermes/vibe/gemini sync scripts, convert.sh, and generate-docs don't know `markdown-html/` exists; CI's blocking `compileall` skips 8 post-v2.7 domains. +10. **35 stale .zip archives** in the public tree (engineering-team 18, compliance 12, marketing 5) plus 4 internal planning docs in the marketing plugin root. + +--- + +## 4. What's already excellent (the template to copy) + +- **research-ops/** — every hard rule verified in execution: ESTIMATE banners, dual-method TAM with triangulation-failure flag, anecdote-vs-insight recurrence gate, named-owner routing on every output. All-KEEP. +- **markdown-html/ + productivity/** — 24/27 empirical checks passed live: exit-code refusal gates, WCAG-AA validation, redaction linter (16 patterns, not the claimed 17 — fix the count), idempotent injection, kill-gate behavior in andreessen. +- **v2.8.0 bizops/commercial orchestrators** — `context: fork` signal-table routing with 2-signal thresholds and no-silent-chain gates verified real, not prose. +- **v2.2 security suite, playwright-pro, self-improving-agent, slo-architect, chaos-engineering, karpathy-coder, Pocock ports** — exit-code contracts, forcing questions, kill criteria, exact CLIs. +- **compliance-os layer** — Article-cited verdicts, explicit NOT-boundaries, outside-counsel routing; **no skill in the repo auto-decides compliance verdicts**. + +The repo's quality story is generational, not random: everything built v2.4+ with forcing questions, refusal gates, and wired tools is KEEP-grade; v2.0–v2.1-era skills are capability brochures. The optimization play is to **retrofit the new-gen pattern onto the old generation, not to invent anything new**. + +--- + +## 5. Recommended verification harness (CI gates to add) + +Each gate below is the generalized guardrail derived from a defect class this audit found. Suggested home: `scripts/` + `ci-quality-gate.yml`. + +| Gate | Catches | Spec | +|---|---|---| +| **G1 path-existence linter** | P1-1 phantom paths | Extract every `scripts/…`, `references/…`, `skills:` and relative-path mention from SKILL.md/agents/commands; assert the file exists. Fails today on ~40 surfaces; burn down, then make blocking. | +| **G2 semantic `--sample` smoke** | P0-4 silent zero-output | For every script with `--sample`/bundled sample data: run it, assert exit 0 **and** output passes a per-skill assertion (non-zero metric count, required JSON keys, banner strings). Per-skill assertions are already written: see "Verify (definition of done)" blocks in every domain report. | +| **G3 counter derivation** | P1-3 drift | `scripts/derive_counters.py` counts skills/plugins/tools/refs/agents/commands from the tree and rewrites the counter blocks in README/CLAUDE.md/marketplace.json. CI fails if claimed ≠ derived. | +| **G4 dual-publish drift guard** | P1-7 | `diff -rq` the 11 known pairs; fail on first divergence. | +| **G5 marketplace registration check** | P1-4 | Every `*/.claude-plugin/plugin.json` has a marketplace.json entry (or an explicit `unlisted` allowlist). | +| **G6 description linter upgrade** | P1-8 | Extend `skill_description_validator.py`: hard-fail >1024 chars, warn missing trigger phrasing, apply to agents too; fix `templates/agent-template.md` so new agents start compliant. | +| **G7 model-name freshness** | stale GPT-4/claude-3 era refs | Regex deny-list for retired model identifiers outside historical-context sentences (2 SKILL.md + 2 scripts today). | +| **G8 argparse contract** | P0-11 | Every `scripts/*.py` must exit 0 on `--help` within 5s unless listed in a by-design exceptions file (hooks, fixed evaluators). | +| **G9 meta-tool hygiene** | P1-9 | `generate-docs.py --help` must be side-effect-free; sync scripts/convert.sh/compileall enumerate domains from the tree, not a hardcoded list. | + +--- + +## 6. Suggested execution order (follow-up PRs) + +1. **PR-1 (P0 batch, ~1 day):** fix the 11 P0 defects. Highest stakes first: FDA/QMSR, ALARP, AI-Act sample, financial-analyst JSON shape, deal-desk formula, corrupted code literals, Atlassian tool-name appendix, webinar argparse, markdown-html orchestrator status text, retire command-guide + google-workspace-cli (or re-verify the CLI exists). +2. **PR-2 (path sweep):** G1 linter + one mechanical fix-all for the `skills/` segment; fix c-level agent KB filenames, research `office/validate.py` (write it or drop the step), email agent paths. +3. **PR-3 (registries):** G3 counter derivation + marketplace registration of the 11 plugins + c-level role-registry update (6 files) + marketing context-file unification. +4. **PR-4 (wiring):** orphan-script A3 pass per domain report lists; trigger-description batch (79 skills, 77 agents) using each report's per-skill suggested descriptions. +5. **PR-5 (CI):** land gates G2, G4–G9; remove 35 .zip archives; fix meta-tooling. +6. **PR-6+ (content):** the 16 REWRITE skills, then OPTIMIZE queue per domain, using the per-skill "Verify (definition of done)" blocks as acceptance criteria. + +--- + +## 7. Where the per-skill verification criteria live + +The user-requested **customized verification loops and validation criteria for every skill, plugin, agent, and command** are in the domain reports: every OPTIMIZE/REWRITE/CUT entry carries a "Verify (definition of done)" block of 2–4 executable checks, and every KEEP skill has a one-line verification contract in its report's "KEEP-verdict verification criteria" section. Those blocks are the input for gate G2. diff --git a/audit/newgen-2026-06/RUBRIC.md b/audit/newgen-2026-06/RUBRIC.md new file mode 100644 index 00000000..03a56a28 --- /dev/null +++ b/audit/newgen-2026-06/RUBRIC.md @@ -0,0 +1,55 @@ +# New-Generation Model Optimization Rubric (v1) + +Audit date: 2026-06-10 · Branch: `claude/skills-plugins-audit-vrttx1` + +This rubric defines what "optimized for new-generation models" means for every artifact +type in this repository. New-gen frontier models (Claude Fable/Opus 4.x class) differ from +the models many of these skills were written for: they need **less hand-holding, more +context economy, and machine-checkable verification**. A skill earns its context window +or it gets cut. + +## A. SKILL.md — 7 dimensions + +| # | Dimension | What PASS looks like | +|---|-----------|----------------------| +| A1 | **Trigger quality** | Frontmatter `description` states what the skill does AND when to fire, in third person, < 1024 chars, with concrete trigger phrases ("Use when…", example user requests). Never just the skill name. | +| A2 | **Context economy** | Body is instruction-dense. Progressive disclosure: SKILL.md holds the workflow + decision rules; deep knowledge lives in `references/` and is loaded on demand. No "You are an expert…" filler, no restating what a frontier model already knows (generic advice = dead weight). | +| A3 | **Tool wiring** | Every referenced script exists, has exact CLI invocations in SKILL.md, and its output is consumed by a named next step. No orphan scripts, no phantom paths. | +| A4 | **Verification loop** | The workflow ends with a check the model can execute: run a script and assert exit code/output shape, validate against an explicit checklist, or hit a refusal gate. Skills without one get a *proposed* custom loop in this audit. | +| A5 | **Real-world expertise** | A practitioner would recognize domain mastery: named frameworks with thresholds, formulas, regulatory citations, decision trees — not "communicate clearly with stakeholders". | +| A6 | **Freshness** | No stale model names (claude-3-x, GPT-3.5-era), dead prices, or 2024-isms presented as current. | +| A7 | **No filler files** | Every file in the package earns its place. References cite sources and say something non-obvious. Assets are usable, not shells. No duplicated boilerplate. | + +Verdicts: **KEEP** (ship as is) · **OPTIMIZE** (targeted edits, listed) · **REWRITE** (structure salvageable, content not) · **CUT-OR-MERGE** (does not earn its context). + +## B. Agents (`agents/*.md`) + +- B1 Frontmatter: `name`, `description` with trigger phrasing ("Use when…" / "Use PROACTIVELY…"), minimal `tools` list. +- B2 Differentiation: the system prompt could not be swapped with a sibling agent's without someone noticing. Personas must change behavior, not adjectives. +- B3 No placeholder/boilerplate body. + +## C. Slash commands (`commands/*.md`) + +- C1 Frontmatter description present and accurate. +- C2 `$ARGUMENTS` / argument-hint handled. +- C3 The command does something a bare prompt could not (orchestrates tools, enforces gates). Otherwise: candidate for merge or cut. + +## D. Scripts (`scripts/*.py`) + +- D1 `--help` exits 0 (verified repo-wide this audit: 583/593 pass). +- D2 Stdlib-only, no LLM calls, deterministic. +- D3 Output is machine-parseable where a workflow consumes it (JSON mode). +- D4 By-design exceptions (hooks reading stdin, fixed-contract evaluators) documented where they live. + +## E. Plugins (`.claude-plugin/plugin.json`) + +- E1 Schema valid (verified repo-wide: all pass `check_plugin_json.py --all`). +- E2 Description matches actual contents (pod/skill counts drift). +- E3 Version coherent with marketplace.json. + +## Custom verification criteria — the contract + +For **every skill** audited, the domain report includes 2–4 *executable* "definition of +done" checks specific to that skill (e.g. "`python3 scripts/x.py --sample` exits 0 and +emits JSON with keys `verdict`, `score`; verdict ∈ {GO, NO-GO}"). These are the +guardrails future optimization PRs must keep green. diff --git a/audit/newgen-2026-06/bizops-commercial-finance.md b/audit/newgen-2026-06/bizops-commercial-finance.md new file mode 100644 index 00000000..a4b1b6c1 --- /dev/null +++ b/audit/newgen-2026-06/bizops-commercial-finance.md @@ -0,0 +1,133 @@ +# Domain audit: business-operations/ + commercial/ + finance/ + business-growth/ — new-gen model optimization +Audited: 2026-06-10 · Skills: 24 · Agents: 2 · Commands: 17 (+2 root finance commands) · Plugins: 5 + +## Scorecard + +| Skill | Verdict | Top issue | +|---|---|---| +| business-operations/business-operations-skills | KEEP | — (orchestrator routing is real: signal table + 2-signal threshold + no-silent-chain) | +| business-operations/process-mapper | KEEP | — (deterministic VA% bands, 3 detection rules, profiles) | +| business-operations/vendor-management | OPTIMIZE | Frontmatter description 1,106 chars (> 1024 A1 limit) | +| business-operations/capacity-planner | KEEP | — (Erlang-C, P50/P90/P99, manager-trigger; best forcing-question library in scope) | +| business-operations/internal-comms | OPTIMIZE | Description 1,284 chars (> 1024) | +| business-operations/knowledge-ops | OPTIMIZE | Description 1,314 chars (> 1024) — the actual cause of its 2/6 repo-checklist infamy; content itself is strong | +| business-operations/procurement-optimizer | OPTIMIZE | Description 1,266 chars (> 1024) | +| commercial/commercial-skills | KEEP | — (orchestrator; 7-lane signal table, depth-first chaining gates) | +| commercial/pricing-strategist | KEEP | — (model+range hard rule operationalized in workflow Step 5 + anti-pattern #1) | +| commercial/deal-desk | OPTIMIZE | Margin math is internally contradictory (SKILL.md says 37.5% loss; script computes 24-pt / 30% via a different formula) | +| commercial/partnerships-architect | KEEP | — (deterministic tier floors, kill-criteria mandate) | +| commercial/channel-economics | OPTIMIZE | Description 1,178 chars (> 1024) | +| commercial/commercial-policy | KEEP | — (4-dim matrix, 10-rule linter, precedent-risk flag verified) | +| commercial/rfp-responder | KEEP | — (GAP-never-invent rule, no-bid < 20% threshold; winrate sample verified) | +| commercial/commercial-forecaster | KEEP | — (assumption block verified NON-OPTIONAL in script output) | +| finance/finance-skills | CUT-OR-MERGE | 55-line plugin README posing as a skill; broken paths; no trigger description | +| finance/financial-analyst | OPTIMIZE | All 4 scripts silently fail (exit 0, zeros) against their own bundled sample — schema mismatch | +| finance/saas-metrics-coach | KEEP | — (benchmark tables with thresholds, strict output contract, status labels) | +| finance/business-investment-advisor | OPTIMIZE | Nested plugin unregistered in marketplace; manifest description truncated mid-word | +| business-growth/business-growth-skills | CUT-OR-MERGE | References phantom "BizDev-toolkit" skill; broken quick-start paths | +| business-growth/contract-and-proposal-writer | OPTIMIZE | 423-line SKILL.md with full contract templates inline; no scripts/references/assets at all | +| business-growth/customer-success-manager | KEEP | — (weighted scorers with explicit weights/thresholds, segment-aware) | +| business-growth/revenue-operations | KEEP | — (formula+threshold tables, CRM cross-check verification steps) | +| business-growth/sales-engineer | KEEP | — (executable validation checkpoints between phases; strongest A4 in scope) | + +**Counts: 14 KEEP · 8 OPTIMIZE · 0 REWRITE · 2 CUT-OR-MERGE** + +## Domain-level findings + +1. **The v2.8.0 claims hold.** Both orchestrators (`business-operations-skills`, `commercial-skills`) have `context: fork` in frontmatter and real routing logic — signal tables, a 2-signal confidence threshold, single-question fallback with recommended answer, and explicit "never silently chain" gates. Every one of the 13 bizops/commercial sub-skills ships a 5-8 question forcing-question library with per-question recommended answer + canon citation. This is not vague prose. +2. **Hard rules are operationalized, not just claimed.** Verified by execution: `deal_scorer.py --sample` emits an approver chain and "2 critical signal(s) detected; cannot APPROVE" (never auto-approves); `bookings_forecaster.py --sample` emits an "Assumption block (NON-OPTIONAL)" section; pricing-strategist's workflow Step 5 and anti-pattern #1 enforce model+range-never-a-number; vendor/procurement outputs are framed as "inputs to a human decision" with refusal logic (single-source tier-1 consolidation refused without break-glass). +3. **Systemic A1 failure in the v2.8.0 batch: 5 of 15 frontmatter descriptions exceed the 1,024-char limit** (knowledge-ops 1,314 · internal-comms 1,284 · procurement-optimizer 1,266 · channel-economics 1,178 · vendor-management 1,106). They cram "Distinct from" and tool inventories into the trigger field. This — not content quality — is what tanked knowledge-ops/procurement-optimizer on the repo's own checklist. One-pass fix: move everything after the trigger sentence into the body. +4. **Systemic A3 gap in the v2.8.0 batch: almost no fenced CLI examples.** 8 of 13 sub-skills score "0 code blocks" on the repo checklist; invocations live in prose/tables. deal-desk and commercial-policy (which have "Quick examples" sections) show the right pattern. +5. **finance/ and business-growth/ are a different generation.** No forcing questions, no profiles, no named-owner routing, meta-skills (`finance-skills`, `business-growth-skills`) that are plugin READMEs with broken paths. The per-skill content (saas-metrics-coach, customer-success-manager, revenue-operations, sales-engineer) still earns KEEP on calibrated thresholds, but the wrappers are dead weight. +6. **One genuinely broken tool chain: financial-analyst.** Its `assets/sample_financial_data.json` nests data under per-tool keys (`ratio_analysis`, `dcf_valuation`, `budget_variance`, `forecast`) while all four scripts read top-level keys. Result: every documented quick-start command "succeeds" (exit 0) while emitting all-zero ratios, "Error: Historical revenue data is required" (still exit 0), `Total Items: 0`, and $0.00 forecasts. The repo-wide `--help` smoke test cannot catch this class of failure. +7. **Domain-math inconsistency in deal-desk.** SKILL.md (citing `discount_economics.md`) says "a 30% discount on an 80% gross-margin product loses 37.5% of margin, not 30%" — correct under fixed COGS: margin dollars fall 30/80 = 37.5%. But `deal_scorer.py` and `discount_economics.md` actually use `net_margin = G − D·(G/100)` (proportional COGS) → 24-pt loss / 30% relative. The script's own docstring writes the correct `(G−D)/(1−D/100)` formulation, then discards it. Pick one model; the scorer's margin dimension (weight 0.30) currently understates discount damage. + +## Per-skill findings + +### business-operations/vendor-management — OPTIMIZE +- Issues: (1) description 1,106 chars > 1024 — trim to trigger sentence, move "Ships 3 tools…" and "Distinct from…" into the body; (2) no fenced CLI examples (checklist rule 5); (3) SKILL.md 170 lines — body content fine, but Steps 2-4 partially duplicate script-level docs. +- Verify: `python3 -c "import re;t=open('business-operations/skills/vendor-management/SKILL.md').read();d=re.search(r'description:(.*?)\n\w+:',t,re.S).group(1);assert len(d.strip())<1024"` · `python3 skills/vendor-management/scripts/vendor_scorer.py --sample` exits 0 with KEEP/REVIEW/REPLACE verdicts · `--profile healthcare` output differs from `--profile saas` · SKILL.md contains ≥ 1 fenced ```bash block. + +### business-operations/internal-comms — OPTIMIZE +- Issues: (1) description 1,284 chars > 1024; (2) zero fenced CLI examples; (3) "Distinct from" appears in both description and body (duplicated context cost). +- Verify: description < 1024 chars · all 3 scripts pass `--sample` exit 0 · `change_announcement_builder.py` still rejects "exciting news" tone on `disruptive` magnitude (magnitude/tone validation preserved) · ≥ 1 fenced code block in SKILL.md. + +### business-operations/knowledge-ops — OPTIMIZE +- Issues: (1) description 1,314 chars > 1024 — worst in repo, and the real driver of its 2/6 checklist score; (2) zero fenced CLI examples; (3) "a procurement tool sunset in 2024" tripped the time-sensitivity rule — rephrase relatively; (4) content (5W2H validator thresholds, SAFE ≥ 80 / NOT-SAFE < 60 bands, staleness×inbound-links ranking) is genuinely strong — do not rewrite. +- Verify: description < 1024 chars · `kb_ingester.py --sample` exits 0 and reports orphan/stale/glossary-drift counts on the synthetic 8-page vault · `runbook_validator.py --sample` returns NOT-SAFE on the deliberately-broken runbook · repo checklist (`skill_review_checklist_runner.py `) reaches ≥ 4/6. + +### business-operations/procurement-optimizer — OPTIMIZE +- Issues: (1) description 1,266 chars > 1024; (2) zero fenced CLI examples; (3) SKILL.md 167 lines with tool inventory repeated 3× (description, Workflow, Scripts table). +- Verify: description < 1024 chars · `supplier_consolidation.py --sample` exits 0 and still emits the "DO NOT CONSOLIDATE — tier-1 cluster, no break-glass" refusal on a tier-1 cluster without break-glass flag · `spend_categorizer.py --sample --profile enterprise` differs from `--profile tech-startup`. + +### commercial/deal-desk — OPTIMIZE +- Issues: (1) margin-formula contradiction: SKILL.md claims 37.5% margin loss (fixed-COGS, correct), `deal_scorer.py:123-133` + `references/discount_economics.md` compute `G − D·G/100` = 24 pts (proportional-COGS); the docstring names the correct `(G−D)/(1−D/100)` formula then ignores it — reconcile to one model across all three files; (2) discount_economics.md "Why the conventional shorthand is wrong" section is itself wrong under the standard fixed-COGS assumption. +- Verify: `deal_scorer.py --sample` exits 0, verdict DECLINE, output contains "cannot APPROVE" and a ≥ 4-hop approver chain · SKILL.md margin example, `discount_economics.md` worked table, and `score_margin()` produce the same number for (G=80, D=30) · `--profile services` composite differs from `--profile saas` · `terms_redliner.py --sample` flags uncapped indemnity as CRITICAL. + +### commercial/channel-economics — OPTIMIZE +- Issues: (1) description 1,178 chars > 1024 — it embeds four "Not X (that's Y)" disambiguations plus a keyword list; (2) zero fenced CLI examples. +- Verify: description < 1024 chars · all 3 scripts pass `--sample` exit 0 · `channel_roi_analyzer.py --sample` emits one of DOUBLE-DOWN/MAINTAIN/DEFUND/EXIT per channel · cost-to-serve output contains both per-deal and per-$-ARR lines. + +### finance/finance-skills — CUT-OR-MERGE +- Issues: (1) it is a plugin README, not a skill — no workflow, no decision rules, no trigger phrasing ("Financial analyst agent skill and plugin for Claude Code, Codex…"); (2) quick-start path `finance/financial-analyst/SKILL.md` doesn't exist (actual: `finance/skills/financial-analyst/`); (3) wholly duplicates plugin.json + finance/CLAUDE.md. Merge useful lines into README.md/plugin.json and delete, or rebuild as a real router (the bizops/commercial orchestrator pattern exists to copy). +- Verify (if merged): `finance/skills/finance-skills/` removed AND `finance/.claude-plugin/plugin.json` `skills` array updated AND `check_plugin_json.py --all` passes · no references to `finance/financial-analyst/` (without `/skills/`) remain: `grep -r "finance/financial-analyst" finance/ | grep -v skills/` returns nothing. + +### finance/financial-analyst — OPTIMIZE +- Issues: (1) **broken tool wiring**: all 4 scripts read top-level keys (`income_statement`, …) while `assets/sample_financial_data.json` nests them under `ratio_analysis`/`dcf_valuation`/`budget_variance`/`forecast` — every documented quick-start emits zeros; (2) error masking: `dcf_valuation.py` prints "Error: Historical revenue data is required" and exits 0; (3) `references/financial-ratios-guide.md` cites zero sources (A7); (4) Phase 1/5 of the workflow is filler a frontier model doesn't need ("Define analysis objectives and stakeholder requirements"). +- Verify: `ratio_calculator.py assets/sample_financial_data.json` produces zero "Insufficient data" lines and a nonzero Gross Margin · `dcf_valuation.py ` exits nonzero · `budget_variance_analyzer.py assets/sample_financial_data.json` reports Total Items > 0 · `forecast_builder.py` base-case revenue > $0 on the bundled sample. + +### finance/business-investment-advisor — OPTIMIZE +- Issues: (1) nested plugin `finance/business-investment-advisor/.claude-plugin/plugin.json` is not registered in marketplace.json — either register it or fold the skill into the finance plugin's `skills` array and delete the nested manifest; (2) that manifest's description is truncated mid-word ("Also use f"); (3) prompt-only skill claiming "show all math" with no deterministic tool — acceptable for an advisor, but the IRR/NPV sections restate model-known formulas (A2); the rubric + proactive-triggers + anti-pattern table are the parts that earn context — trim the formula restatements. +- Verify: skill is reachable via exactly one registered plugin (`python3 scripts/check_plugin_json.py --all` passes; marketplace lookup finds it) · manifest description is a complete sentence < 1024 chars · SKILL.md ≤ ~150 lines after trimming formula primers. + +### business-growth/business-growth-skills — CUT-OR-MERGE +- Issues: (1) names a fifth skill "BizDev-toolkit" that does not exist anywhere in the repo; (2) quick-start path `business-growth/customer-success-manager/SKILL.md` is wrong (actual: `business-growth/skills/customer-success-manager/`); (3) body says "4 production-ready skills", description says 5 — neither matches a real router; (4) duplicates plugin.json + CLAUDE.md. Same disposition as finance-skills: delete-and-merge, or rebuild on the bizops orchestrator pattern. +- Verify (if merged): folder removed, plugin.json skills path still valid, `grep -ri "bizdev-toolkit" business-growth/` returns nothing, `check_plugin_json.py --all` passes. + +### business-growth/contract-and-proposal-writer — OPTIMIZE +- Issues: (1) 423-line SKILL.md with three full contract templates + a GDPR DPA block inline — move Templates A/B/C and the DPA block to `assets/` and keep selection logic + jurisdiction notes + pitfalls in SKILL.md (progressive disclosure, A2); (2) only single-file skill in scope — no references/assets despite being template-heavy by nature; (3) static legal claims (§126 BGB, §74 HGB, "post-Brexit") carry freshness risk with no last-reviewed marker; add one; (4) overlaps `commercial/rfp-responder` and `c-level-advisor/general-counsel-advisor` — the existing scope sentence is good, keep it. +- Verify: SKILL.md ≤ ~150 lines · `assets/` contains ≥ 4 template files referenced by name from SKILL.md · description still trigger-phrased ("Use when drafting…") · a "last legal review" date line exists. + +## KEEP-verdict verification criteria + +- **business-operations-skills**: frontmatter retains `context: fork`; signal table lists exactly 6 lanes matching plugin.json skill paths; "Do NOT chain silently" and ≤ 200-word digest rules present. +- **process-mapper**: 3 scripts pass `--sample` exit 0; `cycle_time_analyzer` emits VA% verdict ∈ {HEALTHY, TYPICAL, WASTE-HEAVY} with 25%/10% bounds; `bottleneck_detector.py --profile healthcare` ≠ `--profile saas` output. +- **capacity-planner**: `capacity_modeler.py --sample` exits 0 with risk band ∈ {SAFE, WATCH, AT_RISK, CRITICAL} and a P50/P90/P99 breach table; `hiring_sequencer` triggers a manager hire when span crosses 7; 7 forcing questions remain canon-cited. +- **commercial-skills**: `context: fork` retained; 7-lane signal table matches the 7 sub-skill folders; anti-pattern list keeps "recommend a range + model" and "never auto-approve" lines. +- **pricing-strategist**: `wtp_analyzer.py --sample` exits 0, emits OPP/IDP/PMC/PME + a sub-100-N sample-size warning; `packaging_designer.py --sample` flags ≥ 1 anti-pattern; SKILL.md anti-pattern #1 ("Recommending a specific number") intact. +- **partnerships-architect**: `partner_tier_classifier.py --sample` exits 0; STRATEGIC floor still requires named_accounts ≥ 5 AND multi-year commit AND dedicated resources; kill-criteria mandate in Assumptions. +- **commercial-policy**: `policy_linter.py --sample` exits FAIL-by-design with 4 BLOCKERs; `exception_router.py --sample` routes the 42% exception with ≥ 3 compensating commitments; precedent-risk (3+ similar exceptions) flag preserved. +- **rfp-responder**: `winrate_predictor.py --sample` exits 0 with estimate + confidence band + verdict ∈ {BID, PARTNER-BID, NO-BID}; < 20% auto-no-bid threshold intact; "never invents claims" GAP rule in both description and Step 2. +- **commercial-forecaster**: `bookings_forecaster.py --sample` output contains "Assumption block (NON-OPTIONAL"; three tiers (commit/best-case/pipe-only) emitted; CoV bands (10/25/50%) in `funnel_confidence_scorer` unchanged. +- **finance/saas-metrics-coach**: `metrics_calculator.py --mrr 50000 --customers 100 --churned 5 --json` exits 0 with `_missing` array; quick-ratio bands (<1 CRITICAL, >4 EXCELLENT) match references/benchmarks.md; output-format template (Metrics at a Glance → 90-Day Focus) preserved. +- **customer-success-manager**: all 3 scripts exit 0 against `assets/sample_customer_data.json` (its sample actually works — unlike financial-analyst's); dimension weights sum to 100% in both SKILL.md tables and scripts; Green/Yellow/Red bounds 75/50 unchanged. +- **revenue-operations**: 3 scripts exit 0 against bundled samples; coverage target 3-4x, MAPE rating table, and Rule-of-40 thresholds present in both SKILL.md and script output. +- **sales-engineer**: the inline python validation one-liners in Phases 1/3/4 execute without KeyError against `--format json` output of the corresponding scripts (these are the skill's A4 backbone — keep them runnable). + +## Agents + +2 agents in scope (`business-operations/agents/cs-bizops-orchestrator.md`, `commercial/agents/cs-commercial-orchestrator.md`); finance/ and business-growth/ ship none. + +- **B1**: both have name/description/tools/model. Descriptions are persona-stated rather than "Use when…"-phrased — minor A1-style gap; routing context is otherwise clear. Both pin `model: sonnet` — verify that's intended for orchestration-heavy work on new-gen defaults. +- **B2**: genuinely differentiated — different signature questions ("Where does the work spend most of its time waiting?" vs "What's the margin at full discount?"), different lane tables, different hard-output contracts (named approver / model+range / disclosed assumption). Not swappable. +- **B3**: no boilerplate. One staleness bug in both: the "Available commands" sections still annotate 9 commands with "(Sprint 2)" although all shipped — delete the annotations. +- Gap: business-growth and finance rely on root-level `/saas-health`, `/financial-health` and no persona agent; acceptable for legacy skills, but if the meta-skills are rebuilt as routers, add agents then — not before. + +## Commands + +17 in scope (8 bizops, 9 commercial) + 2 root finance commands (`/saas-health`, `/financial-health`). + +- **C1/C2**: all sampled commands have accurate frontmatter descriptions and `argument-hint`, and interpolate `$ARGUMENTS`. +- **C3**: routers (`/cs:bizops`, `/cs:commercial`) and grills (`/cs:grill-bizops`, `/cs:grill-commercial`) clearly orchestrate (signal scoring, one-question discipline, refusal-to-route gates) — pass. Per-skill commands (`/cs:vendor-review`, `/cs:deal-review`, `/cs:knowledge-ops`, etc.) mostly restate their SKILL.md's tool table + "Distinct from" section; they pass C3 only because they name exact tools/profiles/verdicts. If context budget ever matters, these 13 per-skill commands are the first merge candidates into their routers — but no action required now. +- `/saas-health` and `/financial-health` are thin wrappers over the scripts; `/financial-health` inherits the financial-analyst sample-schema bug (its documented `ratios ` path silently zeroes). Fix rides on the financial-analyst OPTIMIZE. +- business-growth/ has zero commands — its 4 real skills are invocable only by description-matching. Acceptable; note for any future refresh. + +## Plugin manifests + +All 5 schema-valid (repo-wide E1 pass confirmed); versions coherent at 2.9.0 where registered. E2 drift everywhere: + +1. **business-operations**: claims "24+ reference docs each citing ≥7 authoritative sources" — actual count is 18 (6 sub-skills × 3). Fix the number. +2. **commercial**: claims "28+ reference docs" — actual is 21 (7 × 3). Fix the number. +3. **finance**: description counts business-investment-advisor among its "3 finance skills", but `"skills": ["./skills"]` excludes it (it lives at `finance/business-investment-advisor/`, outside the path). Either move the skill under `finance/skills/` or correct the description. +4. **business-investment-advisor** (nested): description truncated mid-word ("…Also use f"); not registered in `.claude-plugin/marketplace.json` — it is currently undiscoverable as a plugin. Register or fold into finance-skills. +5. **business-growth**: description enumerates "BizDev-toolkit", a skill that does not exist; "5 business & growth skills" counts the meta-README skill. Correct to the 4 real skills (or 5 only after the meta-skill is rebuilt as a real router). diff --git a/audit/newgen-2026-06/c-level-advisor.md b/audit/newgen-2026-06/c-level-advisor.md new file mode 100644 index 00000000..27194695 --- /dev/null +++ b/audit/newgen-2026-06/c-level-advisor.md @@ -0,0 +1,281 @@ +# Domain audit: c-level-advisor/ — new-gen model optimization +Audited: 2026-06-10 · Unique skills: 61 (of 66 SKILL.md files incl. dual-published) · Agents: 14 (13 cs-* in c-level-agents/agents/ + devils-advocate; cs-ceo/cs-cto live outside the folder in /agents/c-level/) · Plugins: 8 + +## Scorecard + +| Skill | Verdict | Top issue | +|---|---|---| +| **skills/ (main bundle, 33)** | | | +| agent-protocol | OPTIMIZE | Valid-roles list frozen at 9 roles; 5 newer roles (GC/CDO/CAIO/CCO/VPE) can't be invoked per protocol | +| board-deck-builder | OPTIMIZE | Phantom `/board-deck` command in Quick Start | +| board-meeting | OPTIMIZE | Role tables omit 5 newer roles; `/cs:board` vs `/cs:boardroom` naming clash | +| c-level-skills | CUT-OR-MERGE | Bundle README posing as a skill; contradicts cs-onboard and board-meeting on protocol details | +| ceo-advisor | KEEP | ~30 lines of shared boilerplate (Communication/Context Integration) duplicated across all role skills | +| cfo-advisor | KEEP | — | +| change-management | KEEP | — | +| chief-ai-officer-advisor | KEEP | A6 watch: hardcoded 2026 API/GPU pricing will rot | +| chief-customer-officer-advisor | KEEP | — | +| chief-data-officer-advisor | KEEP | — | +| chief-of-staff | OPTIMIZE | "28 skills" stale (33); routing matrix omits 5 roles; 3rd divergent decision-log path | +| chro-advisor | KEEP | — | +| ciso-advisor | KEEP | — | +| cmo-advisor | KEEP | — | +| company-os | KEEP | — | +| competitive-intel | OPTIMIZE | 5 phantom `/ci:*` commands in Quick Start | +| context-engine | KEEP | — | +| coo-advisor | KEEP | — | +| cpo-advisor | KEEP | — | +| cro-advisor | KEEP | — | +| cs-onboard | OPTIMIZE | Conflicts with c-level-agents `/cs:onboard` (7-dimension vs 12-question interview, same output file) | +| cto-advisor | KEEP | — | +| culture-architect | KEEP | — | +| decision-logger | KEEP | Memory path conflict with `/cs:decide` (flagged there) | +| founder-coach | KEEP | — | +| general-counsel-advisor | KEEP | — | +| internal-narrative | KEEP | — | +| intl-expansion | OPTIMIZE | Thin; no tool; no verification loop | +| ma-playbook | OPTIMIZE | Thinnest skill in domain; valuation numbers unsourced; no tool | +| org-health-diagnostic | KEEP | — | +| scenario-war-room | KEEP | Phantom `/war-room` invocation (minor) | +| strategic-alignment | KEEP | — | +| vpe-advisor | KEEP (dual-published) | Workflow CLI paths inconsistent with Quick Start paths | +| **executive-mentor/skills/ (6)** | | | +| executive-mentor | KEEP | — | +| challenge | KEEP | — | +| board-prep | KEEP | — | +| hard-call | OPTIMIZE | Placeholder description (A1 fail) | +| postmortem | OPTIMIZE | Placeholder description (A1 fail) | +| stress-test | OPTIMIZE | Placeholder description (A1 fail) | +| **c-level-agents/skills/ (22)** | | | +| c-level-agents (overview) | OPTIMIZE | Frontmatter says 8 agents / 17 commands; reality is 13 / 21 | +| founder-mode | OPTIMIZE | Routing table omits CDO/CAIO/CCO/VPE — auto-router can't reach 4 of 13 advisors | +| office-hours | KEEP | — | +| onboard | OPTIMIZE | Second, divergent founder interview writing the same `~/.claude/company-context.md` | +| brief | OPTIMIZE | Affected-roles checklist omits 5 newer advisors | +| boardroom | KEEP | — | +| decide | OPTIMIZE | Writes `~/.claude/decisions/` while decision-logger skill specifies `memory/board-meetings/` | +| execute | KEEP | — | +| post-mortem | KEEP | — | +| freeze | KEEP | `/cs:unfreeze` has no skill file (handled in-file; minor) | +| cross-eval | KEEP | — | +| cfo-review | KEEP | — | +| cmo-review | KEEP | — | +| cpo-review | KEEP | — | +| cro-review | KEEP | — | +| cto-review | KEEP | — | +| ciso-review | KEEP | — | +| gc-review | KEEP | — | +| cdo-review | OPTIMIZE | Routes to phantom `/cs:chro-review` | +| caio-review | OPTIMIZE | Routes to phantom `/cs:chro-review` | +| cco-review | OPTIMIZE | Routes to phantom `/cs:chro-review` | +| vpe-review | OPTIMIZE | Routes to phantom `/cs:chro-review` | +| **Dual-published standalone copies** | (counted above) | chief-ai-officer-advisor, chief-customer-officer-advisor, chief-data-officer-advisor, general-counsel-advisor, vpe-advisor | + +**Totals: KEEP 40 · OPTIMIZE 20 · REWRITE 0 · CUT-OR-MERGE 1** + +## Domain-level findings + +### 1. Dual-publication map (5 pairs, zero drift today — but no guard) + +Each of these exists twice, byte-identical (verified with `diff -rq` across SKILL.md + all references + all scripts): + +| Bundle copy (`c-level-advisor/skills//`) | Standalone copy (`c-level-advisor//skills//`) | Drifted? | +|---|---|---| +| chief-ai-officer-advisor | chief-ai-officer-advisor | No | +| chief-customer-officer-advisor | chief-customer-officer-advisor | No | +| chief-data-officer-advisor | chief-data-officer-advisor | No | +| general-counsel-advisor | general-counsel-advisor | No | +| vpe-advisor | vpe-advisor | No | + +The duplication is intentional (standalone-installable plugin AND bundled in c-level-skills) but there is **no sync script, no CI check, and no comment in either copy declaring the other copy exists**. Any future edit to one side silently forks the skill. **Recommendation:** add a `scripts/check_dual_published.py` (or extend ci-quality-gate) that diffs the 5 pairs and fails on divergence; alternatively replace standalone copies with a build step. This is the single highest-leverage guard for the domain. Drift status: GREEN today, unprotected. + +### 2. Role-registry drift — the domain's 9-role core never learned about its 5 newest roles + +The domain grew from 9 C-roles to 14 (GC v2.5.1, CDO v2.5.2, CAIO v2.5.3, CCO v2.5.4, VPE v2.5.5), but the orchestration core was never updated: + +- `agent-protocol/SKILL.md` — "Valid roles: ceo, cfo, cro, cmo, cpo, cto, chro, coo, ciso". Per the protocol's own hard rules, `[INVOKE:gc|...]` etc. is undefined. +- `chief-of-staff/SKILL.md` — routing matrix and "routes to 28 skills total" (now 33) omit the 5 roles entirely. +- `board-meeting/SKILL.md` — Phase 1 role-activation table and Phase 2 ordering list only the original 9. +- `c-level-agents/skills/founder-mode/SKILL.md` — keyword routing table has no rows for data/AI/customer/VPE topics; "retention dropped" routes to CRO, never CCO. +- `c-level-agents/skills/brief/SKILL.md` — affected-roles checklist stops at cs-chief-of-staff. +- `c-level-agents/skills/c-level-agents/SKILL.md` frontmatter — "8 cs-* agents… 17 /cs:* commands" vs actual 13 / 21. +Fix once, in all six files, in one PR. + +### 3. Three competing decision-memory architectures + +- `decision-logger` skill: `memory/board-meetings/decisions.md` (Layer 2) + `YYYY-MM-DD-raw.md` (Layer 1) +- `chief-of-staff` skill: `~/.claude/decision-log.md` +- `/cs:decide`: `~/.claude/decisions/approved/` + `~/.claude/decisions/raw/` + +All three claim to be "the" two-layer memory. An agent following decision-logger will never find decisions written by `/cs:decide`. Pick one canonical layout (the `~/.claude/decisions/` form is most portable) and update the other two. + +### 4. Two competing founder-onboarding interviews + +`cs-onboard` (7 dimensions, ~45 min, conversational probes) and `c-level-agents/onboard` (12 structured questions) both write `~/.claude/company-context.md` with **different schemas**; `c-level-skills/SKILL.md` describes a third, 7-question variant that writes to "the project root". The context-engine "Required Context Fields" match only the cs-onboard schema. Reconcile to one interview + one schema. + +### 5. Phantom slash commands + +Referenced but existing nowhere in `commands/` nor as plugin command/skill files: `/board-deck`, `/war-room`, `/health`, `/health:dimension`, `/ci:landscape|battlecard|winloss|update|map`, `/cs:chro-review`, `/cs:coo-review` (routed-to from 4+ review skills), `/cs:board` + `/cs:decisions` + `/cs:review` + `/cs:setup` + `/cs:update` (pre-date the c-level-agents `/cs:*` namespace and now collide with it). Either create thin command files or rewrite the Quick Starts as natural-language triggers. + +### 6. Agent reference-file hallucinations (see Agents section) + +7 of 13 cs-* agents cite knowledge-base filenames that do not exist on disk — apparently written from memory of what the references *should* be called. New-gen models will attempt to Read these paths and fail. + +### 7. Shared boilerplate tax + +Every role-advisor SKILL.md carries the identical ~25-line Communication / Context Integration / Internal Quality Loop block that `agent-protocol/SKILL.md` already owns. Across ~15 skills that's ~375 lines of duplicated context. A one-line pointer ("Output passes the Internal Quality Loop — see agent-protocol/SKILL.md") would reclaim it. Also: `Keywords` sections (10–40 terms each) are dead weight for new-gen trigger matching since the frontmatter description already carries triggers. + +### 8. Repo hygiene + +- `ceo-advisor.zip` (32K) and `cto-advisor.zip` (28K) are stray build artifacts at the domain root — delete. +- `c_level_leadership_skills_overview.md` at domain root duplicates CLAUDE.md content. +- `c-level-advisor/CLAUDE.md` says "Skills Deployed: 33 … + 21 /cs:* sub-skills" but also "28 skills" in the architecture intro of chief-of-staff; CLAUDE.md itself says "13 cs-* persona agents" correctly but root repo CLAUDE.md says "51+ agents (cs-* + 7 personas)" — counts drift in 3 places. + +## Per-skill findings + +### c-level-skills (skills/c-level-skills/) +- **Verdict: CUT-OR-MERGE** +- Issues: (1) It's the bundle's README wearing a SKILL.md frontmatter — `name: "c-level-advisor"` doesn't even match its folder. (2) Describes `/cs:setup` as a 7-question form writing company-context.md "to the project root", contradicting cs-onboard (7 dimensions, `~/.claude/`) and c-level-agents/onboard (12 questions). (3) Describes `/cs:board` as 3 phases; board-meeting skill defines 6. (4) Stale counts (28 skills, 25 tools). (5) As a trigger surface it competes with chief-of-staff for the same routing job. +- Verify: `grep -c "Phase" skills/c-level-skills/SKILL.md` no longer describes a board protocol that disagrees with `board-meeting/SKILL.md`; content merged into README.md or CLAUDE.md; `find c-level-advisor/skills -name SKILL.md | wc -l` drops by 1 (or file becomes a pure router stub < 40 lines). + +### agent-protocol +- **Verdict: OPTIMIZE** +- Issues: (1) Valid-roles list omits gc/cdo/caio/cco/vpe. (2) Peer-verification table has no rows for legal/data/AI/customer claims. (3) At 418 lines it carries the Communication Standard that 15 sibling skills then duplicate — the duplication should collapse toward this file. +- Verify: `grep -E "gc|cdo|caio|cco|vpe" skills/agent-protocol/SKILL.md` returns the invocation registry rows; the 5 newer role SKILL.mds still render the `[INVOKE:role|...]` examples without contradiction; sibling role skills reference (not restate) the quality loop. + +### chief-of-staff +- **Verdict: OPTIMIZE** +- Issues: (1) "routes to 28 skills total" — 33 exist. (2) Routing matrix has no rows for legal, data strategy, AI strategy, customer/retention, eng-delivery topics. (3) Decision log path `~/.claude/decision-log.md` is a third memory location (see domain finding 3). (4) References `references/routing-matrix.md` — confirm it covers all 14 roles too. +- Verify: routing matrix includes GC/CDO/CAIO/CCO/VPE rows; `grep "28 skills" SKILL.md` → no hits; decision-log path identical to decision-logger's canonical path. + +### board-meeting +- **Verdict: OPTIMIZE** +- Issues: (1) Phase 1 activation table + Phase 2 ordering cover 9 roles. (2) Invoked as `/cs:board` here but `/cs:boardroom` in c-level-agents — two names, one protocol. (3) Memory paths must match the canonical decision-memory layout chosen in domain finding 3. +- Verify: one command name used in both files (`grep -r "cs:board\b" c-level-advisor/` returns 0 or all-consistent); activation table lists 14 roles; memory paths match decision-logger. + +### board-deck-builder +- **Verdict: OPTIMIZE** +- Issues: (1) `/board-deck [quarterly|monthly|fundraising]` doesn't exist as a command anywhere. (2) No CISO/GC/data sections cross-referenced to the 5 newer roles where relevant (minor). Content itself (4-act structure, bad-news framework, asks slide) is genuinely good. +- Verify: Quick Start either points at an existing command file or is rephrased as a trigger sentence; `references/deck-frameworks.md` + `templates/board-deck-template.md` exist (they do — keep green). + +### competitive-intel +- **Verdict: OPTIMIZE** +- Issues: (1) Five phantom `/ci:*` commands as the entire Quick Start. (2) No script despite tabular scoring (threat matrix, feature-gap) being mechanizable — optional. Frameworks (8 tracking dimensions, win/loss interview protocol, over/under-tracking signals) are real. +- Verify: Quick Start contains no `/ci:` strings OR `commands/ci-*.md` files exist; battlecard template still referenced and present. + +### cs-onboard +- **Verdict: OPTIMIZE** +- Issues: (1) Same output file as c-level-agents/onboard with a different schema (see domain finding 4). (2) `/cs:setup` + `/cs:update` names collide with the c-level-agents `/cs:` namespace without skill files behind them. +- Verify: exactly one interview skill owns `~/.claude/company-context.md`; context-engine "Required Context Fields" match the surviving schema; `grep -rl "company-context.md" c-level-advisor | xargs grep -l "project root"` → 0 hits. + +### intl-expansion +- **Verdict: OPTIMIZE** +- Issues: (1) No script, no verification loop — ends at a checklist. (2) Market-selection scoring matrix is the mechanizable core; a 20-line stdlib scorer would lift this to KEEP. (3) Weakest A5 in the cross-cutting set: most rows ("research local buying behavior") a frontier model already knows. +- Verify: add `scripts/market_entry_scorer.py --sample` exits 0 emitting JSON with per-market weighted score; SKILL.md Quick Start invokes it; `references/regional-guide.md` retains region-specific regulatory facts (data residency, entity requirements) that aren't generic. + +### ma-playbook +- **Verdict: OPTIMIZE** +- Issues: (1) Thinnest skill in domain (98 lines), pure checklist. (2) "2-15x ARR for SaaS" and "$1-3M per engineer" unsourced and freshness-fragile (A6). (3) No tool — a DD red-flag scanner or earnout-structure checker would be in-pattern with general-counsel-advisor. (4) Overlaps general-counsel-advisor (LOI/negotiation) and chief-data-officer-advisor (data diligence) without cross-references. +- Verify: multiples carry a source + as-of date; Adjacent Skills section cross-links gc-advisor + cdo-advisor; either a script exists passing `--help`, or the skill explicitly delegates quantitative work to cfo-advisor tools. + +### executive-mentor/hard-call, postmortem, stress-test (3 skills) +- **Verdict: OPTIMIZE** (each) +- Issues: descriptions are literal placeholders (`"/em -hard-call — Framework for Decisions With No Good Options"`) — no trigger phrasing, malformed command name (`/em -hard-call` vs `/em:hard-call`). Bodies are excellent (10/10/10, Grove test, proper 5-Whys, change-register-with-verification-date); only the frontmatter fails. +- Verify: `python3 scripts/audit_skills.py` (repo validator) no longer flags these three for missing trigger; each description ≥ 1 "Use when" clause and < 1024 chars. + +### c-level-agents (overview skill) +- **Verdict: OPTIMIZE** +- Issues: (1) Frontmatter `agents:` lists 8 (13 exist), `commands:` lists 17 (21 exist) — a new-gen router using this metadata will never surface vpe/cdo/caio/cco surfaces. (2) References block links `../../references/persona-voices.md` and `../references/persona-voices.md` inconsistently (one resolves, one doesn't). +- Verify: frontmatter agent/command lists match `ls agents/ | wc -l` = 13 and `ls skills/ | wc -l` − 1 = 21; all relative links resolve from the file's own directory. + +### founder-mode +- **Verdict: OPTIMIZE** +- Issues: (1) Routing table has no signal rows for retention/CS (CCO), data architecture/training data (CDO), model selection/AI risk (CAIO), DORA/eng hiring (VPE) — the self-described "killer command" silently misroutes 4 domains to the wrong advisor. (2) Claims routing knowledge of decisions via decision-logger — path depends on domain finding 3. +- Verify: table includes the 4 missing roles with ≥ 4 keywords each; example "`the win rate dropped`" vs "`gross retention dropped`" route to CRO vs CCO respectively. + +### onboard (c-level-agents) +- **Verdict: OPTIMIZE** — see domain finding 4. Verify: one canonical schema; symlink guidance (llm-wiki bridge) unchanged. + +### brief +- **Verdict: OPTIMIZE** +- Issues: affected-roles checklist (drives boardroom panel composition) omits cs-general-counsel/cdo/caio/cco/vpe — a pricing-with-data-licensing brief can't seat the right panel. +- Verify: checklist lists all 14 advisors; `grep -c "cs-" skills/brief/SKILL.md` ≥ 14. + +### decide +- **Verdict: OPTIMIZE** +- Issues: writes `~/.claude/decisions/{raw,approved}/` while decision-logger (the skill it claims to invoke) specifies `memory/board-meetings/`. The "two-layer memory" exists in two incompatible places. +- Verify: `grep -r "decisions/approved\|board-meetings/decisions" c-level-advisor/ -l` shows one canonical layout across decide, decision-logger, chief-of-staff, board-meeting. + +### cdo-review, caio-review, cco-review, vpe-review (4 skills) +- **Verdict: OPTIMIZE** (each, same one-line fix) +- Issues: Routing sections send follow-ups to `/cs:chro-review` (and vpe-review also implies `/cs:coo-review`) — neither exists. Everything else is exemplary: role-specific forcing questions with thresholds, exact CLI to the backing skill's tools, structured output with verdict gates. +- Verify: every `/cs:*` string in the Routing sections resolves to a file under `c-level-agents/skills/*/SKILL.md`; `grep -r "cs:chro-review\|cs:coo-review" c-level-agents/` → 0 hits (or the two commands are created). + +## KEEP-verdict verification criteria + +- **ceo-advisor** — metrics dashboard targets present (burn multiple < 2x, NPS > 40); `python3 skills/ceo-advisor/scripts/strategy_analyzer.py` exits 0; boilerplate block replaced by agent-protocol pointer without losing the Tree-of-Thought section. +- **cfo-advisor** — all 3 scripts exit 0 bare; SKILL.md keeps burn-multiple/Rule-of-40/NDR thresholds table; "not a financial analyst skill" disambiguation to finance/ retained. +- **cto-advisor** — tech-debt priority formula `(Severity × Blast Radius) / Cost-to-fix` intact; both scripts exit 0; ADR template with 3-year-TCO checklist retained. +- **coo-advisor** — process-maturity 5-level table + both scripts green; VPE-vs-COO scope note added when role registry is fixed (advisory). +- **cpo-advisor** — D30 retention thresholds (20% consumer / 40% B2B) + invest/maintain/kill table intact; `pmf_scorer.py` exits 0. +- **cmo-advisor** — channel-level CAC discipline + pipeline-coverage 3–4x targets intact; both scripts green. +- **cro-advisor** — Magic Number + CAC-payback formulas verbatim; NRR benchmark table intact; both scripts green. +- **ciso-advisor** — `ALE = SLE × ARO` formula + compliance sequencing (SOC2 T1 → T2 → ISO/HIPAA) intact; both scripts green. +- **chro-advisor** — calibrated rating distribution table + compa-ratio 0.95–1.05 target intact; both scripts green. +- **chief-data-officer-advisor** (dual) — `ai_training_data_audit.py` bare-run exits 0 with GO/MITIGATE/NO-GO verdicts; both copies stay byte-identical (`diff -rq` clean); GDPR Art. 6 citations present in references. +- **chief-ai-officer-advisor** (dual) — 3 scripts exit 0; EU AI Act tier table retains Article citations; pricing figures carry an as-of date (A6 guard); copies identical. +- **chief-customer-officer-advisor** (dual) — `retention_decomposition_analyzer.py` flags leaky-bucket (NRR>100 ∧ GRR<85) on sample; GRR/NRR threshold table intact; copies identical. +- **general-counsel-advisor** (dual) — `contract_risk_scanner.py` bare-run flags ≥ 1 finding on bundled sample; "Not legal advice" disclaimer in SKILL.md + both tools; copies identical. +- **vpe-advisor** (dual) — `delivery_throughput_analyzer.py` emits DORA verdict + bottleneck (verified: exits 0, "Overall DORA level: High", bottleneck stage + % of cycle); fix workflow paths `../../skills/vpe-advisor/...` → `scripts/...`; copies identical. +- **context-engine** — 90-day staleness gate + anonymization never-send list intact; aligned to surviving onboarding schema. +- **decision-logger** — `python3 scripts/decision_tracker.py --demo` exits 0; DO_NOT_RESURFACE enforcement block intact; canonical path winner of domain finding 3. +- **scenario-war-room** — max-3-variables rule + cascade map + trigger-point examples intact; `scenario_modeler.py` exits 0; `/war-room` string removed or backed by a command. +- **org-health-diagnostic** — `health_scorer.py --json` emits machine-parseable dimension scores; 8-dimension thresholds + dimension-interaction table intact. +- **strategic-alignment** — `alignment_checker.py` detects orphans/conflicts/coverage-gaps on sample JSON; 5-people articulation test intact. +- **culture-architect** — values→behavioral-anchors table + culture-health score bands (80/65/50) intact. +- **company-os** — L10 agenda + IDS + rocks 3–7 cap intact; no phantom commands introduced. +- **founder-coach** — Skill×Will matrix + delegation ladder + calendar-audit target % table intact. +- **change-management** — ADKAR per-change-type timelines + resistance-pattern table intact. +- **internal-narrative** — audience translation matrix + contradiction check + 4-hour crisis rule intact. +- **executive-mentor / challenge / board-prep** — both scripts exit 0; challenge keeps assumption-confidence×impact matrix; board-prep keeps numbers-cold list. +- **office-hours / boardroom / execute / post-mortem / freeze / cross-eval** — pipeline artifact paths (`~/.claude/briefs|boardroom|execution|postmortems|freezes`) mutually consistent; each Routing section's `/cs:*` targets resolve; boardroom keeps Phase-2 isolation + dissent column; post-mortem keeps pre-committed-criteria scoring; freeze keeps default-period table. +- **cfo/cmo/cpo/cro/cto/ciso/gc-review** — every relative `python ../../../skills/...` path resolves from the file's directory; six questions per role remain role-specific (no copy-paste across roles); verdict gates (🟢/🟡/🔴) intact. + +## Agents + +| Agent | B1 (frontmatter) | B2 (differentiation) | B3 (body) | Top issue | +|---|---|---|---|---| +| cs-cfo-advisor | ⚠️ no "Use when" | PASS — burn-multiple/dilution forcing Qs, bear-case rule | PASS | model: opus justified? | +| cs-cmo-advisor | ⚠️ | PASS — one-sentence-positioning gate | **FAIL refs** — cites `growth_playbooks.md`, `marketing_operations.md` (don't exist; actual: growth_frameworks.md, marketing_org.md) | phantom KB files | +| cs-cro-advisor | ⚠️ | PASS — coverage>forecast, discount-creep tell | **FAIL refs** — all 3 KB names wrong (`revenue_operations/sales_motion/retention_expansion` vs actual sales_playbook/pricing_strategy/nrr_playbook) | phantom KB files | +| cs-cpo-advisor | ⚠️ | PASS — retention-curve-before-roadmap | **FAIL refs** — all 3 wrong (`product_vision/portfolio_strategy/pmf_framework` vs product_strategy/product_org_design/pmf_playbook) | phantom KB files | +| cs-coo-advisor | ⚠️ | PASS — DRI/cadence refusal gate | **FAIL refs** — all 3 wrong (`operating_cadence/okr_execution/scaling_playbooks` vs ops_cadence/process_frameworks/scaling_playbook) | phantom KB files | +| cs-chro-advisor | ⚠️ | PASS — no-promotion-without-ladder refusal | **FAIL refs** — all 3 wrong (`hiring_systems/comp_philosophy/leveling_ladders` vs people_strategy/comp_frameworks/org_design) | phantom KB files | +| cs-ciso-advisor | ⚠️ | PASS — assume-breach, $-quantified risk | **FAIL ref** — cites `threat_modeling.md` (doesn't exist; actual security_strategy.md) | phantom KB file | +| cs-chief-of-staff | ⚠️ | PASS — pure router, distinct job | **FAIL refs** — `routing_logic.md`/`synthesis_patterns.md` vs actual routing-matrix.md/synthesis-framework.md; routing table omits 5 roles | phantom KB files + role drift | +| cs-general-counsel-advisor | PASS (has disclaimer + scope) | PASS — escalate-to-counsel hard rule | PASS — exact tool wiring, correct paths | — | +| cs-cdo-advisor | PASS | PASS — "what decision does this data drive" refusal gate | PASS | — | +| cs-caio-advisor | PASS | PASS — no-eval-no-ship gate | PASS | — | +| cs-cco-advisor | PASS | PASS — gross-over-NRR, which-customer-would-you-fire | PASS | — | +| cs-vpe-advisor | PASS | PASS — explicit 4-way differentiation (CTO/eng-lead/CHRO/COO) | PASS | — | +| devils-advocate (executive-mentor) | no frontmatter at all (prose file) | PASS — exactly-3-concerns + never-clean-approval rules; behavior-changing | PASS — worked example | add YAML frontmatter | + +**B2 assessment:** the personas genuinely pass the swap test. Each agent has different refusal gates (CFO: no scale on broken unit economics; CAIO: no eval set, no ship; CCO: no CS hire without a named customer outcome; CHRO: no promotion without ladder step), different tool wiring, and different success metrics — swapping cs-cfo-advisor's prompt into cs-cmo-advisor would be noticed immediately. The voice bookending ("opening/forcing/closing") is thin but the underlying workflows differ structurally. + +**The systemic agent defect is B-side tool wiring, not differentiation:** 7 of 13 agents (the v2.5.0 batch: cfo is clean; cmo, cro, cpo, coo, chro, ciso, chief-of-staff are not) cite knowledge-base filenames that don't exist on disk. The 5 newer agents (gc, cdo, caio, cco, vpe — written against real files) are clean. Fix: one PR correcting ~16 filenames; verify with a link-checker pass (`for f in agents/*.md; do grep -o '\.\./\.\./skills/[a-z-]*/references/[a-z_-]*\.md' $f | while read p; do test -f "$(dirname $f)/$p" || echo "$f → $p"; done; done` → empty). + +Also: `cs-ceo-advisor` and `cs-cto-advisor` live in `/agents/c-level/` outside this folder while 11 sibling links point at them via `../../../../agents/c-level/` — fragile but currently resolving. + +## Plugin manifests + +8 manifests, all schema-valid, all version 2.9.0 and consistent with marketplace.json (E1/E3 PASS). E2 findings: + +| Plugin | Drift | +|---|---| +| c-level-skills (root) | Description says "33 skills + 13 agents + 21 commands" — accurate. But `"skills": ["./skills"]` only ships the bundle dir; the c-level-agents layer named in the description is NOT included in this plugin's skills path (it's a separate plugin) — description overpromises the install. | +| c-level-agents | Accurate (13 agents / 21 commands) — but the bundled overview SKILL.md frontmatter still says 8/17 (see per-skill). Manifest is ahead of its own skill. | +| executive-mentor | Accurate. CLAUDE.md claims it is "the only skill with a plugin.json (namespace: em)" — false since v2.5.x; 7 other plugin.json files exist in the domain. CLAUDE.md statement is the drift, not the manifest. | +| chief-ai-officer-advisor | Accurate, rich. "2026 pricing" claim is a freshness liability shared with the skill (A6). | +| chief-customer-officer-advisor / chief-data-officer-advisor / general-counsel-advisor / vpe-advisor | Accurate; descriptions correctly state "Standalone-installable; also bundled in c-level-skills" — the only place the dual-publication is documented. Mirror this sentence into the SKILL.md of each pair so editors learn about the twin copy. | + +Scripts: all 25 bundle scripts pass repo-wide smoke tests (D1); spot-runs of `delivery_throughput_analyzer.py` (DORA verdict + bottleneck %), `decision_tracker.py --demo`, and `health_scorer.py --json` confirm deterministic, sample-embedded, machine-parseable output (D2/D3 PASS). diff --git a/audit/newgen-2026-06/compliance.md b/audit/newgen-2026-06/compliance.md new file mode 100644 index 00000000..f0dfa805 --- /dev/null +++ b/audit/newgen-2026-06/compliance.md @@ -0,0 +1,219 @@ +# Domain audit: ra-qm-team/ + compliance-os/ — new-gen model optimization +Audited: 2026-06-10 · Skills: 26 distinct (17 ra-qm-team incl. meta + 9 compliance-os; +2 verbatim sub-plugin duplicates) · Agents: 9 (8 compliance-os + cs-quality-regulatory) · Commands: 0 standalone (8 compliance-os skills are /cs:* command-shaped) · Plugins: 4 manifests (1 in marketplace) + +## Scorecard + +| Skill | Verdict | Top issue | +|---|---|---| +| ra-qm-team/capa-officer | OPTIMIZE | Cites 21 CFR 820.100 as current; removed by QMSR (eff. 2026-02-02) | +| ra-qm-team/eu-ai-act-specialist | OPTIMIZE | Embedded sample mis-teaches Art. 5(1)(f): tags RETAIL emotion recognition as prohibited (workplace/education only) | +| ra-qm-team/fda-consultant-specialist | REWRITE | Entire QSR section presents pre-QMSR 21 CFR 820 as current law; FY2024 user fees | +| ra-qm-team/gdpr-dsgvo-expert | OPTIMIZE | "30 days" deadlines (Art. 12(3) says one month + 2-month extension); WP29 framing; score-without-owner output | +| ra-qm-team/information-security-manager-iso27001 | OPTIMIZE | "Overall Compliance: 87%" auto-verdict example; thin clause citation; generic IR section | +| ra-qm-team/isms-audit-expert | KEEP | — | +| ra-qm-team/iso42001-specialist | KEEP | — (exemplary; template for the rest of the domain) | +| ra-qm-team/mdr-745-specialist | OPTIMIZE | PSUR table contradicts MDR Art. 86(1); IIb conformity-route table garbled; no Reg. 2023/607 transition note | +| ra-qm-team/qms-audit-expert | KEEP | — | +| ra-qm-team/quality-documentation-manager | OPTIMIZE | FDA table cites removed 820.40/.180/.181/.184/.186 as current | +| ra-qm-team/quality-manager-qmr | OPTIMIZE | Compliance matrix: "21 CFR 820 / QSR compliance" stale; "MPG/MPDG" half-stale | +| ra-qm-team/quality-manager-qms-iso13485 | OPTIMIZE | Record-retention table cites removed 820.30/.181/.184/.198 sections | +| ra-qm-team/ra-qm-skills (meta) | CUT-OR-MERGE | 66-line catalog with wrong paths and wrong skill count; adds no behavior | +| ra-qm-team/regulatory-affairs-head | OPTIMIZE | "~$22K (2024)" fee labeled current; QSR framing in pathway step 2 | +| ra-qm-team/risk-management-specialist | OPTIMIZE | ALARP w/ cost-benefit ("Proportionality") contradicts EU MDR "as far as possible" (EN ISO 14971:2019/A11:2021) | +| ra-qm-team/soc2-compliance | KEEP | — | +| ra-qm-team/compliance-team-eu-ai-act/* (dup) | CUT-OR-MERGE | Byte-identical copy of skills/eu-ai-act-specialist; drift risk | +| ra-qm-team/compliance-team-iso42001/* (dup) | CUT-OR-MERGE | Byte-identical copy of skills/iso42001-specialist; drift risk | +| compliance-os/compliance-os | KEEP | — (plugin.json description drift noted under Plugins) | +| compliance-os/compliance-readiness | KEEP | — | +| compliance-os/aims-audit | KEEP | — | +| compliance-os/ai-act-readiness | KEEP | — (phasing dates 2025-02-02/2025-08-02/2026-08-02/2027-08-02 correct) | +| compliance-os/gdpr-audit-prep | KEEP | — | +| compliance-os/iso27001-audit-prep | KEEP | — (typo: "Article 9.3" should be "Clause 9.3") | +| compliance-os/iso13485-audit-prep | KEEP | — | +| compliance-os/soc2-audit-prep | KEEP | — | +| compliance-os/fda-qsr-audit-prep | OPTIMIZE | Acknowledges QMSR yet cites removed 820.75/.100/.180/.198/.250 as live citations | + +**Counts:** KEEP 13 · OPTIMIZE 11 · REWRITE 1 · CUT-OR-MERGE 1 (+2 duplicate copies) + +## Domain-level findings + +**1. The domain is two generations in one tree.** The 2026-05 wave (eu-ai-act-specialist, iso42001-specialist, all of compliance-os) is the best compliance work in the repo: Article/Clause-cited verdicts, explicit NOT-boundaries, deterministic tools with embedded samples, "Your Decision: [the call only the compliance officer can make]" output blocks, outside-counsel routing. The legacy 2025-era wave (the other 14 ra-qm-team skills) is competent practitioner content but pre-dates the citation-discipline pattern and has not been re-baselined against 2026 regulatory state. + +**2. FDA QMSR is the single largest freshness failure (REWRITE/OPTIMIZE driver for 6 skills).** The FDA Quality Management System Regulation (final rule 89 FR 7496) replaced the QSR effective 2026-02-02 — four months before this audit. It incorporates ISO 13485:2016 by reference and REMOVES the subsection structure the legacy skills cite as current: 820.20/.30/.40/.50/.70/.75/.100/.180/.181/.184/.186/.198 no longer exist (retained/renumbered: 820.10 requirements, 820.35 records, 820.45 labeling+packaging; 21 CFR 801/803/806/830 unchanged). `fda-consultant-specialist` (skill + qsr_compliance_requirements.md reference + qsr_compliance_checker.py `--section 820.30` interface) has ZERO mentions of QMSR. Ironically, the compliance-os agent `cs-fda-qsr-auditor` and `fda-qsr-audit-prep` correctly state "substantially harmonized post-Feb 2026" — the fresh layer knows what the underlying skill it wraps does not. + +**3. Citation precision: good-to-excellent in the new wave, mixed in legacy.** New-wave outputs cite Article+paragraph by contract ("do not paraphrase without cite"). Legacy skills cite at clause level (ISO 13485 4.2.3, 7.5.6, 8.5.2; GDPR Art. 6/9/35; MDR Annex II/VIII/XIV; MDCG 2019-11) — adequate — but carry concrete precision errors a notified-body auditor would flag: (a) mdr-745-specialist PSUR table says Class IIb "every 2 years" / IIa "when necessary" — MDR Art. 86(1) requires IIb+III at least annually and IIa at least every two years; (b) risk-management-specialist's ALARP framework includes "Cost-benefit of further reduction", which EU MDR Annex I §2 + the EN ISO 14971:2019/A11:2021 Z-annexes explicitly disallow (risk reduction "as far as possible" without economic consideration); (c) the eu-ai-act-specialist embedded sample tags a retail-store CCTV emotion-recognition system with `article_5_practice: emotion_recognition_in_workplace_or_education` — retail emotion recognition is Art. 50(3) transparency, not Art. 5 prohibited; the default `--sample` run teaches the wrong rule. + +**4. Auto-decide vs route-to-human: NO skill auto-decides compliance verdicts; discipline is explicit in the new wave, implicit in legacy.** Every compliance-os and 2026-wave skill ends with a named-human handoff ("Your Decision: … compliance officer or legal counsel", "Outside Counsel Required" sections, cs-dpo-gdpr hard rule routing novel cases to GC). Legacy skills embed human signoff in workflows (CAPA approval signatures, "Classification confirmed with Notified Body", CER "reviewed by qualified evaluator") but lack an explicit handoff block, and two tool-output examples drift toward verdict-shaped numbers without an owner: information-security-manager's "Overall Compliance: 87%" and gdpr_compliance_checker's "Compliance score (0-100)". Not REWRITE-level — they are framed as prep/self-check tools — but every OPTIMIZE pass should add the new-wave "Your Decision" block. + +**5. The "49 no-source references" repo flag is ~80% false positive in this domain.** 63 reference files in scope (55 distinct after sub-plugin dedup). Only ~8 have a formal "Sources" heading — which is what the repo validator keys on — but ~45 carry dense inline regulatory citations (Article/Clause/§/CFR/Annex markers; the AI Act and 13485 playbooks run 37–94 citation markers per file). Genuine zero-citation gaps ≈ 9 files, all generic-methodology docs: capa-officer/rca-methodologies.md + effectiveness-verification-guide.md, risk-management-specialist/risk-analysis-methods.md + risk-assessment-templates.md (77 lines, thin), quality-manager-qmr/quality-kpi-framework.md, information-security-manager-iso27001/incident-response.md, soc2-compliance/type1_vs_type2.md + evidence_collection_guide.md, qms-audit-expert/nonconformity-classification.md (1 marker). Fix: add a Sources block to those 9; do not bulk-rewrite the other 45. + +**6. New-gen model lens.** Frontier models know ISO/GDPR/MDR basics; what earns context here is exactly what the new wave ships: clause-keyed gap analyzers with readiness verdicts, mock-audit scenario libraries (205 scenarios), evidence-reuse maps with confidence ratings, audit-prep interrogations with sample-driven "show me the record" questions. Legacy skills that mostly restate standard structure (info-sec manager's ISMS-implementation prose, parts of quality-manager-qmr) are the weakest A2 performers; their tools and checklists still earn their place. + +**7. Cross-plugin coupling.** compliance-os skills invoke `../../../ra-qm-team/skills/*/scripts/*.py` by relative path. Works in the monorepo; breaks when plugins install independently (compliance-os plugin does not ship those scripts). Violates the repo "skills are self-contained" principle — at minimum document the ra-qm-skills co-install requirement in the manifest. + +**8. Cruft.** 12 legacy `.zip` archives + `final-complete-skills-collection.md` committed at ra-qm-team/ root; ra-qm-team/CLAUDE.md says "14/14 skills" (folder has 16 + meta; omits eu-ai-act + iso42001 entirely, so the domain's own nav file hides its two best skills). + +## Per-skill findings + +### ra-qm-team/fda-consultant-specialist — REWRITE +Issues: +1. QSR section ("Quality System Regulation (21 CFR Part 820)") + subsystem table (820.20–820.181) presented as current; QMSR replaced this structure effective 2026-02-02 — wrong regulatory guidance in the highest-stakes lane. +2. `references/qsr_compliance_requirements.md` (753 lines) and `qsr_compliance_checker.py --section 820.30` interface built entirely on removed section numbers; zero QMSR mentions anywhere in the skill. +3. Fee table is FY2024 ($21,760 510(k) / $134,676 De Novo / $425,000+ PMA) with no fiscal-year label or MDUFA pointer. +4. Description still sells "QSR (21 CFR 820) compliance" — trigger text itself stale. +5. Pathway/eSTAR/cybersecurity/HIPAA content remains sound — structure salvageable, QSR third needs rebuild around ISO 13485-by-reference + retained 820.10/.35/.45 + unchanged 801/803/806/830. +Verify: +- `grep -ri QMSR ra-qm-team/skills/fda-consultant-specialist/ | wc -l` ≥ 5 (SKILL.md, description, qsr reference, checker help). +- `grep -rE '820\.(20|30|40|50|70|100|181|198)' SKILL.md references/` returns only lines explicitly marked historical/pre-2026. +- `python3 scripts/qsr_compliance_checker.py --help` exits 0 and help text names QMSR/ISO 13485, not "21 CFR 820 compliance" alone. +- Fee table rows carry an explicit FY label and "verify at fda.gov MDUFA" note. + +### ra-qm-team/ra-qm-skills — CUT-OR-MERGE +Issues: +1. 66-line catalog page; duplicates README/plugin.json function; no workflow, no tools, no verification — fails A2/A4. +2. Says "12 skills" while the folder ships 16 and plugin.json says 14 — three conflicting counts. +3. Quick-start path `ra-qm-team/regulatory-affairs-head/SKILL.md` is wrong (missing `skills/` segment). +4. Omits eu-ai-act-specialist, iso42001-specialist, soc2-compliance from its table. +Verify: +- Folder removed (catalog content merged into ra-qm-team/README.md), OR rewritten as a real router; if kept: skill count matches `ls ra-qm-team/skills | wc -l` minus itself, and every path in the table resolves (`test -f` loop exits 0). + +### ra-qm-team/risk-management-specialist — OPTIMIZE +Issues: +1. ALARP used as the acceptability framework incl. "Proportionality | Cost-benefit of further reduction" — EU MDR Annex I §2 + EN ISO 14971:2019/A11:2021 Z-annexes prohibit economic considerations; for CE-marked devices the criterion is "as far as possible" (AFAP). A notified body flags this exact table. +2. ISO 14971:2019 itself dropped ALARP from the normative body; skill presents it as the standard's method. +3. `references/risk-analysis-methods.md` + `risk-assessment-templates.md` (77 lines) cite zero sources. +4. No explicit named-human handoff for residual-risk acceptance (it's implied via "management signoff" only in iso42001-specialist, not here). +Verify: +- `grep -c 'as far as possible\|AFAP' SKILL.md` ≥ 2 and ALARP appears only with an explicit "non-EU / not acceptable under MDR" caveat. +- `grep -c 'Cost-benefit' SKILL.md` = 0 in the EU acceptability context. +- `python3 scripts/risk_matrix_calculator.py -p 4 -s 5 --output json` exits 0, emits `risk_level` key. + +### ra-qm-team/mdr-745-specialist — OPTIMIZE +Issues: +1. PSUR table wrong vs MDR Art. 86(1): says IIb "Every 2 years", IIa "When necessary" — regulation requires IIb (all, not just implantable) at least annually, IIa at least every 2 years. +2. Conformity-route row "IIb | Annex IX + X or X + XI" garbled (routes are Annex IX, or Annex X+XI). +3. No mention of Reg. (EU) 2023/607 extended transition (legacy MDD devices to 2027/2028) — the question every MDR client asks first in 2026. +4. PMS table cites "PMS Plan | Article 84" correctly but omits Art. 83 (system) and Art. 86 (PSUR) cites where the schedule lives. +Verify: +- PSUR table matches Art. 86(1) verbatim cadence (`grep -A4 'PSUR Schedule' SKILL.md` shows IIb=annual, IIa=every 2 years). +- `grep -c '2023/607' SKILL.md references/` ≥ 1. +- `python3 scripts/mdr_gap_analyzer.py --device Test --class IIa --output json` exits 0 with gap list. + +### ra-qm-team/eu-ai-act-specialist — OPTIMIZE +Issues: +1. Embedded sample system "Emotion recognition in retail store CCTV" is hard-tagged `article_5_practice: emotion_recognition_in_workplace_or_education` → default `--sample` output declares retail emotion recognition PROHIBITED. Correct treatment: Art. 50(3) transparency (limited-risk). Wrong teaching in the default demo of a flagship skill. +2. Classifier trusts caller-supplied `article_5_practice` flags rather than deriving from context fields it already collects (`users`, `intended_purpose`) — at minimum the docstring should state the flag is the user's legal pre-determination. +3. Verbatim duplicate at compliance-team-eu-ai-act/ (see Plugins). +Verify: +- `python3 scripts/ai_system_risk_classifier.py` sample output classifies the retail-CCTV system as LIMITED-RISK citing Art. 50(3), or the sample is changed to a genuine workplace context. +- All 3 scripts exit 0 on `--help` and bare run; every verdict line contains "Article". + +### ra-qm-team/gdpr-dsgvo-expert — OPTIMIZE +Issues: +1. Rights table + body say "30 days" / "extendable to 90" — Art. 12(3) is one month, extendable by two further months; in a deadline-tracking tool the month/30-day distinction loses up to 3 days. +2. "WP29 high-risk criteria" — EDPB-endorsed but should be cited as EDPB/WP248 rev.01. +3. Compliance checker emits 0-100 score with no named-DPO routing block; SKILL.md has no "Your Decision" handoff (contrast gdpr-audit-prep which does this right). +4. No mention of EU-US Data Privacy Framework / Chapter V transfer tooling in SKILL.md (playbook reference covers it; surface a pointer). +Verify: +- `grep -c 'one month' SKILL.md` ≥ 1; `grep -c '30 days' SKILL.md` = 0 in the Art. 12 deadline context. +- `python3 scripts/data_subject_rights_tracker.py add --type access --subject T --email t@x.de` then `list` exits 0; due-date computed by calendar month. +- SKILL.md gains an output block routing final determinations to DPO/counsel. + +### ra-qm-team/information-security-manager-iso27001 — OPTIMIZE +Issues: +1. Worked example ends "Overall Compliance: 87%" with no owner/handoff — the closest thing to an auto-verdict in the domain. +2. Body is clause-thin (only 6.1.2 cited); 2022 control IDs appear only in the example; A5 weak for a new-gen model (ISMS-implementation prose a frontier model already knows). +3. `references/incident-response.md` (420 lines) cites zero sources and duplicates engineering-team incident-response ground. +4. CLI surface in SKILL.md (`--template healthcare`, `--domains`) must be verified against actual argparse (legacy doc drift risk). +Verify: +- Every documented flag exists: `python3 scripts/risk_assessment.py --help` and `compliance_checker.py --help` list `--scope/--template/--standard/--gap-analysis`. +- Worked example ends with a named-human review step (ISMS owner / CISO) instead of bare percentage. +- incident-response.md gains a Sources block (≥3: ISO 27035, NIST SP 800-61r3, A.5.24-26) or is cut in favor of a pointer. + +### ra-qm-team/capa-officer — OPTIMIZE +Issues: +1. "FDA 21 CFR 820.100" requirements section presents removed regulation as current (QMSR: CAPA now flows through ISO 13485 8.5.2/8.5.3 incorporated by reference). +2. `references/rca-methodologies.md` + `effectiveness-verification-guide.md` (917 lines combined) cite zero sources. +3. Otherwise the strongest legacy skill (decision trees, validated 5-Why example, metrics with formulas) — targeted edits only. +Verify: +- 820.100 section reframed as "pre-2026 QSR / now via ISO 13485 8.5 under QMSR" (`grep -c QMSR SKILL.md` ≥ 1). +- `python3 scripts/capa_tracker.py --sample > /tmp/c.json && python3 scripts/capa_tracker.py --capas /tmp/c.json --output json` exits 0 with summary metrics keys. + +### ra-qm-team/quality-documentation-manager — OPTIMIZE +Issues: +1. "FDA 21 CFR 820" table (820.40/.180/.181/.184/.186) presents removed sections as current; under QMSR records requirements live in 820.35 + ISO 13485 4.2.4/4.2.5. +2. Part 11 content is solid and unaffected — single-table fix plus reference sweep of 21cfr11-compliance-guide.md for cross-refs into old 820. +Verify: +- FDA table updated to QMSR structure; `grep -E '820\.(40|181|184|186)' SKILL.md` only in historical context. +- `python3 scripts/document_validator.py --sample > /tmp/d.json && python3 scripts/document_validator.py --doc /tmp/d.json --output json` exits 0. + +### ra-qm-team/quality-manager-qms-iso13485 — OPTIMIZE +Issues: +1. Record-retention table regulatory basis column cites removed 820.181/.184/.30/.198. +2. Otherwise strong (exclusion table, validation standards ISO 11135/11137/17665, supplier scoring) — single-table fix. +Verify: +- Retention table bases updated to QMSR/ISO 13485 cites. +- `python3 scripts/qms_audit_checklist.py --clause 7.3` exits 0 and emits 7.3-specific questions. + +### ra-qm-team/quality-manager-qmr — OPTIMIZE +Issues: +1. Multi-jurisdiction matrix: "USA | 21 CFR 820 | FDA registration, QSR compliance" stale post-QMSR; "Germany | MPG/MPDG" — MPG repealed 2021, list MPDG/MPEUAnpG only. +2. Generic culture-survey and KPI content is the domain's weakest A2 (frontier model knows it); KPI reference cites zero sources. +Verify: +- Matrix row reads QMSR; `grep -c 'MPG/' SKILL.md` = 0. +- `python3 scripts/management_review_tracker.py --help` exits 0. + +### ra-qm-team/regulatory-affairs-head — OPTIMIZE +Issues: +1. Pathway matrix fees "~$22K (2024)" — stale FY presented as current; needs FY label + MDUFA pointer. +2. Step 2 lists "FDA (US): 21 CFR Part 820" as applicable regulation without QMSR framing. +3. Overlap with mdr-745-specialist + fda-consultant-specialist is acceptable (strategy vs execution split) but should cross-link rather than restate the SE table. +Verify: +- Fee cells carry FY labels; `grep -c QMSR SKILL.md` ≥ 1. +- `python3 scripts/regulatory_tracker.py --help` exits 0. + +### compliance-os/fda-qsr-audit-prep — OPTIMIZE +Issues: +1. Correctly states post-Feb-2026 harmonization, then cites removed sections as live law throughout (820.198, 820.75, 820.100, 820.180, 820.250) — internally inconsistent; the right cites are ISO 13485 clauses (8.2.2, 7.5.6, 8.5.2, 4.2.5) + retained 820.35/.45 + unchanged 803/801/830/806. +2. Workflow shells into fda-consultant-specialist scripts whose interfaces are themselves pre-QMSR (`--section 820.30`) — blocked on the REWRITE above. +Verify: +- Each of the six questions cites the QMSR-era source (ISO 13485 clause or retained CFR section); `grep -E '820\.(75|100|180|198|250)' SKILL.md` only with "pre-QMSR" annotation. +- Workflow paths resolve after the fda-consultant-specialist rewrite. + +### Duplicate sub-plugins (compliance-team-eu-ai-act/, compliance-team-iso42001/) — CUT-OR-MERGE +Issues: +1. `diff -r` confirms byte-identical copies of ra-qm-team/skills/{eu-ai-act,iso42001}-specialist — two sources of truth; the Art. 5 sample bug must now be fixed twice. +2. Neither sub-plugin is registered in marketplace.json, so the duplication currently buys nothing. +Verify: +- Either sub-plugins deleted (standalone install served by marketplace entry pointing at the skills/ copy), or a sync script/CI check asserts `diff -r` emptiness on every PR. + +## KEEP-verdict verification criteria + +- **iso42001-specialist:** `python3 scripts/aims_gap_analyzer.py` exits 0, prints `Certification readiness:` ∈ {ready, stage_2_candidate, not_ready} + weighted coverage %; all 3 tools pass bare run; every gap line carries a Clause number. +- **isms-audit-expert:** `python3 scripts/isms_audit_scheduler.py --year 2026 --format markdown` exits 0 and emits a quarter-bucketed plan; finding template retains Requirement/Evidence/Gap triple. +- **qms-audit-expert:** `python3 scripts/audit_schedule_optimizer.py --interactive` help path exits 0; clause-scope table keeps 4.2→8.5 coverage; classification decision tree intact. +- **soc2-compliance:** `python3 scripts/control_matrix_builder.py --categories security --format json` exits 0 with ≥1 control per CC1–CC9; gap_analyzer distinguishes type1/type2 modes. +- **compliance-os (orchestrator):** all 4 tools exit 0 on bare run; `audit_simulator.py` output reports `healthy=` against the ≥40% observation / ≤15% critical rule; `assets/mock_audit_library.json` parses with 205 scenarios. +- **compliance-readiness:** output template retains the 🟢/🟡/🔴 verdict + "Top 3 Actions with owners" + routing block; all 4 workflow script paths resolve from the skill dir. +- **aims-audit:** 6 questions each name a Clause or Annex A control; workflow paths into ra-qm-team resolve; routes verdict to `/cs:decide`. +- **ai-act-readiness:** phasing dates remain exactly 2025-02-02 / 2025-08-02 / 2026-08-02 / 2027-08-02; "Legal Review Required" section retained; every question keeps its Article cite. +- **gdpr-audit-prep:** Art. 12(3) one-month language retained; Art. 30/35(7)/33(5) cites intact; "Outside Counsel Required" section retained. +- **iso27001-audit-prep:** fix "Article 9.3"→"Clause 9.3"; 3-year-coverage question + auditor-independence check retained; scheduler path resolves. +- **iso13485-audit-prep:** Clause cites (8.2.4, 7.5.6, 5.6.2/5.6.3) intact; DHF-sampling question retains stratification by class. +- **soc2-audit-prep:** observation-period discipline questions (cycle skips, first-month evidence, exception materiality) retained; AT-C 205 cite intact. + +## Agents + +All 9 pass B1–B3. The 8 compliance-os personas are the best-differentiated agent set audited: each has a distinct voice that changes behavior (cs-ciso-iso27001 "samples, not demos"; cs-dpo-gdpr refuses to paraphrase the Regulation; cs-fda-qsr-auditor tracks Form 483 gradient distinct from ISO NC grades), explicit vs-sibling differentiation paragraphs, and hard rules that route novel/legal calls to GC or outside counsel — the route-to-human discipline the legacy skills lack lives here. cs-fda-qsr-auditor is also the only artifact in either domain that correctly states the QMSR transition. +Issues: (1) cs-fda-qsr-auditor still cites removed 820.x section numbers in its forcing questions — inherits the fda-qsr-audit-prep fix. (2) All 8 pin `model: opus` — pre-Fable-era pin; revisit per repo model policy. (3) `skills:` frontmatter uses repo-relative paths (`ra-qm-team/skills/...`) that break outside the monorepo. (4) cs-quality-regulatory (agents/ra-qm-team/) is generic by comparison (sonnet, catalog-style body, no voice/forcing questions, no QMSR awareness) — OPTIMIZE to the compliance-os persona pattern, and its skill paths omit the `skills/` segment. + +## Plugin manifests + +| Manifest | E1 schema | E2 description | E3 marketplace | +|---|---|---|---| +| ra-qm-team/.claude-plugin/plugin.json | PASS (`"skills": ["./skills"]`) | DRIFT — "14 skills"; folder ships 16 + meta (eu-ai-act + iso42001 + soc2 uncounted) | Registered (v2.9.0) | +| compliance-os/.claude-plugin/plugin.json | PASS (9 explicit paths) | DRIFT — claims "9 supported frameworks" + "3 cs-* agents + 3 commands"; SKILL.md/tools support 12 frameworks, 8 agents, 8 command-skills ship | **NOT in marketplace.json** (66 plugins, none sourced from ./compliance-os) | +| ra-qm-team/compliance-team-eu-ai-act/plugin.json | PASS | OK | **NOT in marketplace.json** | +| ra-qm-team/compliance-team-iso42001/plugin.json | PASS | OK | **NOT in marketplace.json** | + +Findings: (1) Three of four manifests are orphans — built as plugins, never registered; either register them or delete the sub-plugin duplicates and fold compliance-os registration into the next marketplace bump. (2) compliance-os skills depend at runtime on ra-qm-team scripts via `../../../` paths — manifest must declare the co-install requirement or vendor the scripts. (3) ra-qm-team ships 12 stale `.zip` skill archives + `final-complete-skills-collection.md` at domain root — remove from the public tree. (4) ra-qm-team/CLAUDE.md ("14/14 skills", omits the domain's two flagship 2026 skills) and root CLAUDE.md ("18 RA/QM skills") disagree with each other and with the folder; reconcile counts in one pass. diff --git a/audit/newgen-2026-06/cross-cutting.md b/audit/newgen-2026-06/cross-cutting.md new file mode 100644 index 00000000..f8e03120 --- /dev/null +++ b/audit/newgen-2026-06/cross-cutting.md @@ -0,0 +1,179 @@ +# Cross-cutting audit: root agents, commands, standards, templates, marketplace, CI — new-gen model optimization +Audited: 2026-06-10 + +Scope: root `agents/` (32), root `commands/` (39), `standards/`, `templates/`, `orchestration/`, `custom-gpt/`, `assets/`, `.claude-plugin/marketplace.json`, `scripts/`, `.github/workflows/`, root README.md + CLAUDE.md. Rubric dimensions B/C/D/E. + +--- + +## Counter-drift reconciliation table + +Measured today (canonical tree, excluding `.codex/.gemini/.hermes/.vibe` sync copies and `docs/`): + +| Metric | **Actual (measured)** | README.md | CLAUDE.md header (L9) | CLAUDE.md v2.10.3 block | CLAUDE.md footer (L515) | marketplace.json metadata | agents/CLAUDE.md | +|---|---|---|---|---|---|---|---| +| Skills (SKILL.md) | **346** (`audit_skills.py` count) / 347 (`find`) | 338 | 338 | 343 | 338 | 343 | "42 production skills" AND "177 existing skills" (same page) | +| Marketplace plugins | **66 entries** in marketplace.json; **77 plugin.json manifests** on disk (78 incl. `.codex-plugin` sync artifact) | — | 62 | 64 | 62 | **claims 64 — its own `plugins` array has 66** | — | +| Python tools (in-skill `scripts/*.py`) | **555** | 533 | 533 | 548 | — | 548 | — | +| Reference docs (`references/*.md`) | **700** | 676 | 676 | 691 | — | 691 | — | +| Agents (repo-wide / root) | **92 / 32** | 51+ | 51+ ("32 standalone") | — | — | 51+ | "16 Agents Currently Available" (table actually lists 19; folder has 32) | +| Slash commands (repo-wide / root) | **99 / 39** | 87+ | 87+ | 90+ | — | 90+ | — | +| Domains | **17** top-level skill domains | 16 | 16 | 17 | 16 | 17 | — | +| Version | — | — | — | v2.10.3 | **v2.9.0** | v2.10.3 | — | + +Key drift facts: + +1. **marketplace.json is internally inconsistent**: `metadata.description` and `description` both say "64 marketplace plugins" while the `plugins` array contains **66** entries (v2.10.x additions `universal-scraping-architect` and `youtube-full` were appended without bumping the counter). +2. **11 plugin.json manifests exist on disk but are NOT registered in marketplace.json** (invisible to marketplace installs): + `compliance-os/`, `engineering-team/snowflake-development/`, `engineering/behuman/`, `engineering/claude-coach/`, `engineering/grill-with-docs/`, `engineering/llm-cost-optimizer/`, `engineering/prompt-governance/`, `finance/business-investment-advisor/`, `marketing-skill/video-content-strategist/`, `ra-qm-team/compliance-team-eu-ai-act/`, `ra-qm-team/compliance-team-iso42001/`. (Plus `.codex-plugin/plugin.json`, a sync artifact.) Notably, `compliance-os` is *named as a domain* in the marketplace description yet has no marketplace entry. +3. **CLAUDE.md disagrees with itself in three places** (header 338/62/16, v2.10.3 block 343/64/17, footer v2.9.0/338/62/16). README still carries the pre-v2.10 numbers everywhere, including the shields badge (`Skills-338`). +4. Even the freshest claimed numbers (343/64/548/691) trail reality (346/66-77/555/700) — the counters were last trued up at v2.10.3 and have drifted again. + +--- + +## Root agents + +32 agents (25 `cs-*` + 7 personas). **17 of 32 (53%) lack trigger phrasing** ("Use when…" / "Spawn when…" / "Invoke via…") in `description` — B1 fail. All but 2 agents carry the identical generic `tools: [Read, Write, Bash, Grep, Glob]` list (B1 "minimal tools" not practiced). The personas use a non-standard frontmatter schema (`name` with spaces, `color`, `emoji`, `vibe` fields — not Claude Code agent fields). + +| Agent | Verdict | Issue | +|---|---|---| +| engineering/cs-backend-engineer | KEEP | Exemplary: trigger + invocation path + `context: fork` + differentiated forcing questions | +| engineering/cs-frontend-engineer | KEEP | Same pattern; good | +| engineering/cs-fullstack-engineer | KEEP | Same pattern; good | +| engineering/cs-karpathy-reviewer | KEEP | Good trigger; near-duplicate of `engineering/karpathy-coder/agents/karpathy-reviewer.md` (differs, but two sources of truth) | +| engineering/cs-wiki-ingestor / -librarian / -linter (3) | KEEP | Good triggers; near-duplicates of `engineering/llm-wiki/agents/wiki-*.md` — pick one canonical home | +| engineering/cs-senior-engineer | OPTIMIZE | Trigger OK but scope ("architecture, code review, DevOps, API design") overlaps cs-engineering-lead + the 3 role engineers — B2 differentiation weak | +| engineering-team/cs-engineering-lead | OPTIMIZE | Trigger OK; differentiate from cs-senior-engineer or merge | +| engineering-team/cs-workspace-admin | KEEP | Specific, trigger present | +| marketing/cs-aeo | KEEP | Model trigger + voice + refusal rule | +| marketing/cs-webinar-marketer | KEEP | Model trigger + voice | +| marketing/cs-content-creator | OPTIMIZE | No trigger phrasing; description is a topic list | +| marketing/cs-demand-gen-specialist | OPTIMIZE | No trigger phrasing | +| c-level/cs-ceo-advisor | OPTIMIZE | No trigger; 360-line body is content-rich but description is a noun phrase | +| c-level/cs-cto-advisor | OPTIMIZE | No trigger | +| product/cs-product-manager | OPTIMIZE | No trigger; claims 8 skills incl. those owned by sibling agents (strategist, ux-researcher) — B2 overlap | +| product/cs-product-strategist | OPTIMIZE | No trigger; skill overlap with cs-product-manager | +| product/cs-agile-product-owner | OPTIMIZE | No trigger | +| product/cs-ux-researcher | OPTIMIZE | No trigger | +| product/cs-product-analyst | REWRITE | No trigger AND 31-line near-placeholder body (B3) — thinnest agent in the folder | +| project-management/cs-project-manager | OPTIMIZE | No trigger; 515-line body | +| business-growth/cs-growth-strategist | KEEP | "Spawn when…" present | +| finance/cs-financial-analyst | KEEP | "Spawn when…" present | +| ra-qm-team/cs-quality-regulatory | KEEP | "Spawn when…" present | +| personas/solo-founder | OPTIMIZE | No trigger; no `skills:` mapping; non-standard frontmatter | +| personas/startup-cto | OPTIMIZE | No trigger; overlaps cs-cto-advisor (B2 pair) | +| personas/growth-marketer | OPTIMIZE | No trigger; no `skills:`; overlaps cs-demand-gen-specialist | +| personas/content-strategist | OPTIMIZE | No trigger; overlaps cs-content-creator | +| personas/product-manager | OPTIMIZE | No trigger; overlaps cs-product-manager | +| personas/finance-lead | OPTIMIZE | No trigger; skills list (`ceo-advisor`, `cost-estimator`) is bare-name shorthand that doesn't resolve to paths; overlaps cs-financial-analyst | +| personas/devops-engineer | OPTIMIZE | No trigger; references `ms365-tenant-manager` / `aws-solution-architect` which exist only as **.zip archives** in engineering-team/ | + +Cross-cutting agent issues: +- **`skills:` frontmatter shorthand is one directory level stale repo-wide**: e.g. `product-team/product-manager-toolkit` — actual path is `product-team/skills/product-manager-toolkit`. Every domain-prefixed `skills:` value resolves only via the `skills/` insertion. +- `templates/agent-template.md` is the root cause of the missing-trigger pattern: it mandates "One-line description… under 150 characters" with **no trigger-phrase requirement**, contradicting agents/CLAUDE.md's own current guidance and rubric B1. + +--- + +## Root commands + +39 commands. **34 of 39 never reference `$ARGUMENTS`** despite advertising `Usage: /cmd ` in descriptions (C2 weak; only focused-fix, tc, and the 4 cs-*-review/grill commands handle it). Only the 4 newest commands use `argument-hint`. + +**Systemic C3 defect — phantom script paths: 28 of 39 commands contain ≥1 path that does not exist.** Root commands consistently reference `//scripts/x.py`, but skills were reorganized into `/skills//scripts/x.py` (and single-skill plugins into `/skills//scripts/`). Every "Scripts" section pointing at e.g. `engineering/changelog-generator/...`, `finance/financial-analyst/...`, `product-team/product-manager-toolkit/...` is a dead path; the scripts exist one level deeper. A model following these commands hits file-not-found on first invocation. + +| Command | Verdict | Issue | +|---|---|---| +| plugin-audit | KEEP | Real 8-phase orchestration; 4 stale paths to fix | +| seo-auditor | KEEP | Real pipeline; 8 stale paths | +| tc | KEEP | State machine + $ARGUMENTS dispatch; 6 stale paths | +| cs-aeo, cs-webinar | KEEP | Tool-wired workflows | +| cs-backend-review, cs-frontend-review, cs-fullstack-review, cs-engineer-grill | KEEP | argument-hint + agent fork + gates — the model pattern for the rest | +| a11y-audit | KEEP | Uses `{skill_path}` placeholder (resilient); fix Skill Reference path | +| code-to-prd | KEEP | `{skill_path}` placeholder pattern; 3 stale refs | +| chaos-experiment, slo-design, operator-audit, flag-cleanup | KEEP | Interactive wizards/gates; no stale paths detected | +| google-workspace | OPTIMIZE | Good content; 6 stale script paths | +| changelog, pipeline, okr, rice, persona, retro, user-story, saas-health, tech-debt, competitive-matrix, financial-health, project-health, sprint-health | OPTIMIZE | Script-wired (passes C3 in spirit) but **all script paths are phantoms** (missing `skills/` segment) | +| focused-fix | OPTIMIZE | Strong 5-phase protocol + $ARGUMENTS; "Related Skills" points to `engineering/focused-fix` (actual: `engineering/skills/focused-fix`) and to external `superpowers:systematic-debugging` (not in this repo). **Known-issue verified FALSE POSITIVE: the "TODO/FIXME" string is instructional content in the Phase 3 diagnostic checklist, not a real marker** — no actual TODO/FIXME/placeholder markers in commands/ or agents/ | +| karpathy-check | CUT-OR-MERGE (dedupe) | **Byte-identical** to `engineering/karpathy-coder/commands/karpathy-check.md`; also references bare `scripts/complexity_checker.py` which only resolves inside the plugin | +| wiki-ingest, wiki-init, wiki-lint, wiki-query, wiki-log (5) | CUT-OR-MERGE (dedupe) | **Byte-identical** to `engineering/llm-wiki/commands/wiki-*.md` — root copies are second sources of truth that will drift | +| prd | CUT-OR-MERGE | Bare-prompt restatement: 25 lines = output bullet list + skill pointer. A frontier model produces this without the command | +| sprint-plan | CUT-OR-MERGE | Same: 25 lines, no script, no gate, no $ARGUMENTS | +| tdd | CUT-OR-MERGE | References 4 scripts explicitly labeled "(library module)" — not CLI-invocable, so the command orchestrates nothing a bare prompt couldn't | + +**Cut-or-merge candidates: 9** (6 byte-identical duplicates + prd + sprint-plan + tdd). + +--- + +## standards/ + templates/ + orchestration/ + custom-gpt/ + assets/ + +**standards/** — NOT orphaned: referenced by `.github/workflows/skill-quality-review.yml`, `skill-security-audit.yml`, `commands/plugin-audit.md`, root CLAUDE.md, `.claude/commands/update-docs.md`. No stale model names or dead dates. Caveat: `communication-standards.md` is only **38 lines** (vs 319–545 for siblings) — underweight for a "standards" file. The other 4 are substantive. + +**templates/** — Stale meta-documentation: +- `templates/CLAUDE.md` says `agent-template.md` exists "**(when created)**" — it has existed for a long time; also promises `command-template.md` and workflow templates "(when created)" that were **never created** (phantom inventory). +- `templates/agent-template.md` (318 lines) actively teaches the B1 anti-pattern: "description… under 150 characters", no trigger-phrase requirement, generic 5-tool list. This template is why 17/32 root agents fail B1. Verdict: REWRITE the frontmatter section. + +**orchestration/ORCHESTRATION.md** (262 lines) — Referenced from README + agents/CLAUDE.md + mkdocs (not orphaned). Concept is sound, but its load examples are stale: `engineering/aws-solution-architect/SKILL.md` and `engineering/mcp-server-builder/SKILL.md` — `aws-solution-architect` exists only as `engineering-team/aws-solution-architect.zip` (an archive!) and mcp-server-builder lives at `engineering/skills/mcp-server-builder/`. Verdict: OPTIMIZE (fix example paths). + +**custom-gpt/README.md** (128 lines) — Referenced from README + mkdocs; 6 ChatGPT GPT links. Not orphaned; external links unverifiable from here. Verdict: KEEP. + +**assets/icon.png** — **Orphan.** Zero references from marketplace.json, any plugin.json, README, or mkdocs (grep across .json/.md/.yml). Either wire it into marketplace metadata or remove. + +**engineering-team/*.zip** (12 archives: senior-fullstack.zip, aws-solution-architect.zip, etc.) — observed while tracing paths; zipped skill archives sitting in the published tree, referenced by personas/orchestration as if unzipped. Flagging for the engineering-team domain auditor. + +--- + +## scripts/ (build & sync) + +| Script | --help | Finding | +|---|---|---| +| check_plugin_json.py | PASS (argparse) | `--all` validates all 77 manifests, 0 WARN/FAIL today. Solid (D1–D3) | +| sync-codex-skills.py | PASS | Knows all 17 domains incl. markdown-html | +| sync-gemini-skills.py | PASS | **Missing `markdown-html` domain** — 5 skills never sync to Gemini | +| sync-hermes-skills.py | PASS | **Missing `markdown-html`** — never syncs to Hermes | +| sync-vibe-skills.py | PASS | **Missing `markdown-html`** — never syncs to Vibe | +| sync_skill_bundles.py | PASS (argparse) | OK | +| extract_release_notes.py | PASS (argparse) | OK | +| **audit_skills.py** | **FAIL** | No argparse; `--help` is ignored and the **full 346-skill audit runs** (~30s). D1 violation in the repo's own meta-audit tool | +| **generate-docs.py** | **FAIL — destructive** | No argparse; `--help` silently **regenerates the entire docs/ tree** (verified: modified 5 + created 4 files during this audit; reverted). A help invocation must never write. Also lacks markdown-html coverage (no docs pages exist for the 5 markdown-html skills) | +| convert.sh / install.sh / openclaw-install.sh / review-new-skills.sh / *-install.sh | header-documented | No hardcoded `/Users/...` or maintainer-specific paths found anywhere in scripts/ (good). `convert.sh` also has no markdown-html awareness | + +--- + +## CI workflows + +12 workflows. What actually gates PRs: + +- **ci-quality-gate.yml** — runs on every PR. **CONFIRMED: `python scripts/check_plugin_json.py --all` runs as a blocking step**, exactly as CLAUDE.md claims (labeled "guards #539 + #686"). yamllint + workflow schema check (schema check is `|| true` — advisory). **Gap: the blocking `compileall` step covers only 9 pre-v2.7 folders** (`marketing-skill product-team c-level-advisor engineering-team ra-qm-team engineering business-growth finance project-management scripts`) — **8 newer domains are never syntax-checked in CI**: `productivity/`, `marketing/`, `research/`, `research-ops/`, `business-operations/`, `commercial/`, `markdown-html/`, `compliance-os/`. Safety scan and link check are `|| true` (advisory). +- **skill-quality-review.yml / skill-security-audit.yml** — PR-triggered, reference standards/; Tessl review depends on external secrets. +- **enforce-pr-target.yml** — pull_request_target gate (branch strategy enforcement). Runs. +- **claude.yml / claude-code-review.yml / pr-issue-auto-close.yml / virustotal-scan.yml** — event-driven; not quality gates per se. +- **release.yml** (push→main), **static.yml** (Pages), **sync-codex-skills.yml** (push), **smart-sync.yml** (issues; excluded from schema validation due to `projects_v2_item`). + +Net: the only **blocking** code-quality gates are compileall (with the 8-domain hole) and check_plugin_json. Everything else is advisory or external-dependent. Note: `tests/` pytest suite is maintainer-local (gitignored) — no test gate runs in CI by design, but CLAUDE.md's claim "run locally; not in CI" is accurate. + +--- + +## README/CLAUDE.md accuracy + +- README header, badge, and FAQ all say **338 skills / 533 tools / 676 references / 51+ agents / 87+ commands / 16 domains** — all five numbers are stale (actual: 346 / 555 / 700 / 92 / 99 / 17). The shields badge hardcodes `Skills-338`. +- README relative links: all resolve in-tree (CHANGELOG.md, CONTRIBUTING.md, personas, orchestration). **No 404-for-cloners links found beyond the documented gitignored-folder exception.** CLAUDE.md's `documentation/...` links are covered by the Maintainer-Local Folders note (intentional). +- CLAUDE.md is **self-contradictory**: header (L9) 338/62/16, v2.10.3 block 343/64/17, footer "Last Updated May 27, 2026 / Version v2.9.0 / 338 skills…16 domains / 62 plugins". Three different repo states in one file. +- agents/CLAUDE.md is the worst offender: "42 production skills" and "177 existing skills" in adjacent paragraphs, "16 Agents Currently Available" heading over a 19-row table, while the folder holds 32 agent files. +- README claim "All 533 Python CLI tools… verified to run with `--help`" — falsified twice in scripts/ alone (audit_skills.py, generate-docs.py), and the count is 555. + +--- + +## Top recommendations + +1. **Single-source the counters.** Add a `scripts/update_counters.py` (or extend audit_skills.py) that computes skills/plugins/tools/references/agents/commands from the tree and rewrites README badge, CLAUDE.md header+footer, and marketplace.json metadata in one pass; wire it as a blocking CI check ("counters match tree"). Today 7 locations disagree, including marketplace.json with itself (says 64, contains 66). +2. **Fix the phantom-path epidemic in root commands (28/39 affected).** Mechanical fix: insert the missing `skills/` segment (`/skills//scripts/…`); add a CI grep that fails on any in-repo path reference in commands/ + agents/ that doesn't exist. Same fix applies to agents' `skills:` shorthand, orchestration/ORCHESTRATION.md examples, and templates. +3. **Reconcile marketplace.json with disk**: register or explicitly de-list the 11 unregistered plugin.json manifests (compliance-os is even advertised in the marketplace description but uninstallable from it); bump the self-described plugin count to the real entry count. +4. **De-duplicate the 6 byte-identical root commands** (karpathy-check + 5 wiki-*) — keep the plugin copies as canonical; cut `prd`, `sprint-plan`, `tdd` or merge them into their skills (bare-prompt-replaceable). +5. **Repair the meta-tooling**: give audit_skills.py and generate-docs.py argparse (`--help` must be side-effect-free — generate-docs.py currently rewrites docs/ on `--help`); add `markdown-html` to sync-hermes/vibe/gemini + convert.sh + generate-docs; extend ci-quality-gate compileall to the 8 uncovered domains. +6. **Fix the template that breeds B1 failures**: add a mandatory trigger-phrase line ("Use when… / Spawn when…") to templates/agent-template.md, then backfill the 17 root agents missing triggers (the 4 v2.8.1 engineering agents are the pattern to copy); update templates/CLAUDE.md's "(when created)" phantom inventory. + +### Custom verification criteria (cross-cutting contract) + +- `python3 scripts/check_plugin_json.py --all` exits 0 with 77+ manifests OK (keep green). +- `python3 -c "import json; m=json.load(open('.claude-plugin/marketplace.json')); n=len(m['plugins']); assert str(n) in m['metadata']['description'], (n, 'not in metadata')"` exits 0 after counter fix. +- For every `*.py` path matched by `` grep -rhoE '`[a-z-]+(/[a-zA-Z0-9_.-]+)+\.py`' commands/*.md ``: the file exists relative to repo root (0 misses; today: 28 commands fail). +- `python3 scripts/audit_skills.py --help` and `python3 scripts/generate-docs.py --help` exit 0 in <2s with **zero filesystem writes** (`git status --porcelain` empty after). +- `grep -RLE "Use when|Spawn when|Invoke via|Use PROACTIVELY" $(find agents -name 'cs-*.md')` returns empty after trigger backfill. diff --git a/audit/newgen-2026-06/engineering-team.md b/audit/newgen-2026-06/engineering-team.md new file mode 100644 index 00000000..c5f06969 --- /dev/null +++ b/audit/newgen-2026-06/engineering-team.md @@ -0,0 +1,305 @@ +# Domain audit: engineering-team/ — new-gen model optimization +Audited: 2026-06-10 · Skills: 51 · Agents: 5 · Commands: 0 · Plugins: 6 + +## Scorecard +| Skill | Verdict | Top issue | +|---|---|---| +| skills/adversarial-reviewer | KEEP | — | +| skills/ai-security | KEEP | — | +| skills/aws-solution-architect | KEEP | cost figures unverified (minor A6) | +| skills/azure-cloud-architect | KEEP | Bicep API versions pinned to 2023 (minor A6) | +| skills/cloud-security | KEEP | — | +| skills/code-reviewer | KEEP | — | +| skills/email-template-builder | OPTIMIZE | 439-line code dump, zero scripts/references (A3, A7) | +| skills/engineering-skills | OPTIMIZE | index skill claims "23 skills" — actual 32; weak as a skill | +| skills/epic-design | KEEP | "You are a world-class expert" filler (minor A2) | +| skills/gcp-cloud-architect | KEEP | — | +| skills/incident-commander | OPTIMIZE | 3 orphan duplicate scripts; SEV taxonomy duplicates incident-response | +| skills/incident-response | KEEP | — | +| skills/ms365-tenant-manager | OPTIMIZE | 3 scripts exist but never referenced in SKILL.md (A3) | +| skills/red-team | KEEP | — | +| skills/security-pen-testing | KEEP | — | +| skills/senior-architect | OPTIMIZE | generic monolith-vs-microservices prose; no verification loop | +| skills/senior-backend | OPTIMIZE | corrupted code snippet (`name: "zstringmin1max100"`) | +| skills/senior-computer-vision | KEEP | — | +| skills/senior-data-engineer | OPTIMIZE | thin body; generic batch-vs-streaming tables (A2) | +| skills/senior-data-scientist | OPTIMIZE | phantom scripts referenced; real 3 scripts orphaned (A3 hard fail) | +| skills/senior-devops | KEEP | — | +| skills/senior-frontend | OPTIMIZE | corrupted snippet (`"cdnexamplecom"`); mid-file generic React dump | +| skills/senior-fullstack | KEEP | — | +| skills/senior-ml-engineer | OPTIMIZE | GPT-4/GPT-3.5/Claude 3 Opus pricing tables (A6 fail) | +| skills/senior-prompt-engineer | REWRITE | entire skill is GPT-4-era prompt engineering; stale models hardcoded in scripts | +| skills/senior-qa | OPTIMIZE | 2 corrupted code snippets; generic RTL cheatsheet content | +| skills/senior-secops | KEEP | trim BAD/GOOD security basics (minor A2) | +| skills/senior-security | CUT-OR-MERGE | duplicates senior-secops/pen-testing/incident-response; no exact CLI for its 2 scripts | +| skills/stripe-integration-expert | OPTIMIZE | pinned `apiVersion: "2024-04-10"`; pure code dump, no tools | +| skills/tdd-guide | KEEP | — | +| skills/tech-stack-evaluator | OPTIMIZE | "ecosystem health from GitHub/npm metrics" is offline static data — staleness unlabeled | +| skills/threat-detection | KEEP | — | +| a11y-audit/skills/a11y-audit | KEEP | — | +| google-workspace-cli/skills/google-workspace-cli | REWRITE | install coordinates almost certainly fabricated (`npm i -g @anthropic/gws`, `github.com/googleworkspace/cli`) | +| snowflake-development/skills/snowflake-development | KEEP | — | +| playwright-pro/skills/pw | KEEP | — | +| playwright-pro/skills/init | KEEP | — | +| playwright-pro/skills/generate | KEEP | — | +| playwright-pro/skills/review | KEEP | — | +| playwright-pro/skills/fix | KEEP | — | +| playwright-pro/skills/migrate | KEEP | — | +| playwright-pro/skills/coverage | KEEP | — | +| playwright-pro/skills/report | KEEP | — | +| playwright-pro/skills/testrail | KEEP | — | +| playwright-pro/skills/browserstack | KEEP | — | +| self-improving-agent/skills/self-improving-agent | KEEP | — | +| self-improving-agent/skills/review | KEEP | — | +| self-improving-agent/skills/promote | KEEP | — | +| self-improving-agent/skills/extract | KEEP | — | +| self-improving-agent/skills/remember | KEEP | — | +| self-improving-agent/skills/status | KEEP | — | + +**Totals: KEEP 35 · OPTIMIZE 13 · REWRITE 2 · CUT-OR-MERGE 1** + +## Domain-level findings + +1. **Bulk-edit code corruption (systemic, 4 confirmed sites).** A past YAML/quoting sweep mangled string literals inside code blocks: `senior-qa/SKILL.md:123` (`name: "click-mei-tobeinthedocument"` — was `getByRole('button', { name: /click me/i })` + `toBeInTheDocument()`), `senior-qa:244` (`"submiti"`), `senior-backend:253` (`name: "zstringmin1max100"` — was `z.string().min(1).max(100)`), `senior-frontend:425` (`hostname: "cdnexamplecom"` — dots stripped). Any model copying these examples emits broken code. Grep pattern to find more: strings that are concatenated identifiers with punctuation stripped. +2. **Stale LLM-era content concentrated in 2 skills + their scripts.** senior-prompt-engineer and senior-ml-engineer present GPT-4/GPT-3.5/Claude 3 Opus model names, 8K context windows, and 2024 pricing as current — in SKILL.md, references (`llm_integration_guide.md`), and hardcoded in scripts (`prompt_optimizer.py` MODEL choices/prices, `agent_orchestrator.py` cost tables). A6 fail across the whole package, not just prose. +3. **Two generations of skills coexist.** The 2026-upgraded trio (senior-fullstack/frontend/backend: decision engines, profiles, forcing questions, composition maps, kill criteria) and the v2.2 security suite (ai-security, threat-detection, incident-response, cloud-security, red-team: exit-code contracts, ATT&CK/ATLAS mapping, anti-patterns) are the new-gen template. The 2025-era role skills (architect, data-scientist, data-engineer, prompt-engineer, qa) still carry "cheatsheet" bodies — generic tables (HTTP status codes, RTL queries, zero-shot vs few-shot) that a frontier model embodies and that cost context for nothing. +4. **Security skill sprawl with duplicated incident-response content.** Four skills carry SEV1-SEV4 frameworks + IR phase checklists (senior-secops, senior-security, incident-response, incident-commander), and OWASP Top 10 appears in 4 places. The v2.2 suite has explicit "this is NOT X" disambiguation tables; the older senior-security does not and is ~80% subsumed. +5. **Orphan/phantom script wiring (A3).** senior-data-scientist references `scripts/train.py`/`evaluate.py`/`health_check.py` (don't exist) while its 3 real scripts go unmentioned; ms365-tenant-manager never references its 3 scripts; incident-commander ships 6 scripts but wires only 3 (`severity_classifier.py`, `incident_timeline_builder.py`, `postmortem_generator.py` are duplicates of the wired ones). +6. **Count drift everywhere.** README says 18 skills, START_HERE says 14, engineering-skills SKILL.md says 23, plugin.json says 32, root CLAUDE.md says 51. engineering-team/CLAUDE.md documents 7 scripts that don't exist under those names (`fullstack_scaffolder.py`, `statistical_analyzer.py`, `etl_generator.py`, `mlops_setup_tool.py`, `llm_integration_builder.py`, `rag_system_builder.py` under prompt-engineer, `video_processor.py`). +7. **18 stale .zip archives at domain root** (senior-*.zip, code-reviewer.zip, etc.) — dead weight shipped to every cloner; almost certainly out of sync with the live folders. +8. **Unverifiable external-tool provenance.** google-workspace-cli teaches a `gws` CLI installed via `npm install -g @anthropic/gws` (not an Anthropic package) with releases at `github.com/googleworkspace/cli` (not a real repo). If the CLI doesn't exist under these coordinates, the entire 373-line skill + 43 recipes is unusable. +9. **Bright spots worth templating:** playwright-pro sub-skills end every workflow with an executable gate ("run `--repeat-each=10`, all 10 must pass"); code-reviewer ships regression fixtures with committed expected `--json` outputs; the security suite's exit-code contracts (0/1/2 with required action) are exactly the A4 pattern the rubric wants. + +## Per-skill findings + +### engineering-team/skills/senior-prompt-engineer +Verdict: REWRITE +Issues: +- A6 hard fail: GPT-4 cost estimates in sample output (line 57), `--model gpt-4` examples (line 72); `prompt_optimizer.py` restricts `--model` to gpt-4/gpt-3.5-turbo/claude-3-* with 2024 prices; `agent_orchestrator.py` defaults to `model: gpt-4` with stale cost table. +- A2: zero-shot/few-shot/CoT/role-prompting tables and "add format enforcement" guidance are 2023-era basics a frontier model embodies. +- A5 gap: nothing on current practice — structured outputs/tool-use APIs, prompt caching, eval-driven iteration, agent context engineering. +- No verification loop beyond "run both prompts against your eval set" (manual). +Verify (definition of done): +- `grep -rE "gpt-4|gpt-3\.5|claude-3-" skills/senior-prompt-engineer/` returns 0 hits. +- `python3 scripts/prompt_optimizer.py /tmp/p.txt --analyze` exits 0 and model list contains only current-generation model IDs (or is model-agnostic). +- SKILL.md workflow ends with an executable eval gate (script run + exit-code assertion), not "compare outputs". + +### engineering-team/google-workspace-cli/skills/google-workspace-cli +Verdict: REWRITE +Issues: +- Install section points to `npm install -g @anthropic/gws` and `github.com/googleworkspace/cli/releases` — neither coordinate is verifiable as real; skill is unusable if the CLI doesn't exist as described. +- All 43 recipes, persona bundles, and command syntax inherit this provenance risk (A5/A6). +- The 5 Python wrappers (`gws_doctor.py` etc.) are fine but only meaningful if `gws` resolves. +Verify (definition of done): +- Documented install command succeeds on a clean machine (`gws --version` exits 0), or the skill is rebuilt around a verifiable tool (GAM7 / Google Workspace Admin SDK + gcloud). +- `python3 scripts/gws_doctor.py` exits non-zero with a clear "gws not installed" message (graceful degradation check). +- 5 randomly sampled recipe commands validated against the CLI's actual `--help` output. + +### engineering-team/skills/senior-security +Verdict: CUT-OR-MERGE (fold into senior-secops; keep threat modeling) +Issues: +- ~80% duplicates siblings: incident-response workflow (also in senior-secops + incident-response), secure-code-review checklist (code-reviewer), security headers (senior-secops), tool lists (security-pen-testing). +- A3: scripts section says "see the script source files directly" — no exact CLI invocations for `threat_modeler.py`/`secret_scanner.py`, no output consumption. +- Unique value is only the STRIDE-per-element matrix + DREAD scoring + threat_modeler.py. +Verify (definition of done): +- `python3 scripts/threat_modeler.py --help` exits 0 and the surviving SKILL.md (wherever it lands) shows an exact invocation whose JSON output feeds a named next step. +- After merge, `grep -l "STRIDE" engineering-team/skills/*/SKILL.md` returns exactly one file. +- No SEV/IR phase table remains in the merged body (route to incident-response instead). + +### engineering-team/skills/senior-ml-engineer +Verdict: OPTIMIZE +Issues: +- A6: cost table (lines 154-157) lists GPT-4/GPT-3.5/Claude 3 Opus/Haiku at 2024 prices; `references/llm_integration_guide.md` repeats it plus "GPT-4 8,192 context" and `model="gpt-4"` defaults. +- Provider abstraction + tenacity retry code is generic boilerplate (A2). +- Tools shown with one-line CLI but no output-consumption step (`--deploy` flag semantics unstated). +Verify (definition of done): +- `grep -rE "GPT-4|GPT-3\.5|Claude 3 " skills/senior-ml-engineer/` returns 0 hits. +- `python3 scripts/model_deployment_pipeline.py --help` exits 0 and SKILL.md states what artifact each tool emits and which workflow step consumes it. + +### engineering-team/skills/senior-data-scientist +Verdict: OPTIMIZE +Issues: +- A3 hard fail: "Common Commands" references `scripts/train.py`, `scripts/evaluate.py`, `scripts/health_check.py` — none exist; the real scripts (`experiment_designer.py`, `feature_engineering_pipeline.py`, `model_evaluation_suite.py`) are never mentioned. +- Body is inline Python a frontier model writes on demand; the embedded checklists (SRM check <0.01, Bonferroni, parallel trends, HC3) are the actual value — keep those, cut the function bodies. +- Generic kubectl/docker/helm command block is irrelevant filler (A7). +Verify (definition of done): +- Every script path in SKILL.md exists: `grep -o "scripts/[a-z_]*\.py" SKILL.md | xargs -I{} test -f skills/senior-data-scientist/{}` all pass. +- `python3 scripts/experiment_designer.py --help` exits 0 and SKILL.md shows an exact invocation per tool. + +### engineering-team/skills/senior-qa +Verdict: OPTIMIZE +Issues: +- Corrupted snippets at lines 123 and 244 (mangled `getByRole` calls) — copy-paste hazards. +- RTL query/async/MSW quick-reference is frontier-model-embodied content (A2); MSW example uses deprecated `rest` API (v1) — current msw is `http` (A6). +- `actions/upload-artifact@v3` in CI example is deprecated. +- Coverage workflow is good (threshold + `--strict` exit 1) — keep. +Verify (definition of done): +- All TS/TSX code blocks in SKILL.md parse (extract fenced blocks, run through `tsc --noEmit` or eslint-parse smoke check). +- `python3 scripts/coverage_analyzer.py assets-or-sample --threshold 80` documented and exits per stated contract (0 pass / 1 below threshold). + +### engineering-team/skills/senior-frontend +Verdict: OPTIMIZE +Issues: +- Corrupted config at line 425: `remotePatterns: [{ hostname: "cdnexamplecom" }]` (dots stripped). +- Lines 197-465: compound-components/render-props/Image/Suspense dump duplicates what the model knows and what `references/react_patterns.md` already holds — violates progressive disclosure (A2). +- The 2026 wrapper (profiles, decision engine, forcing questions) is excellent; the legacy middle dilutes it. +Verify (definition of done): +- `python3 scripts/frontend_decision_engine.py --primary-device mobile-4g --lcp-target-ms 2000 --seo-dependent true --auth-walled false --team-size 5` exits 0 and emits matched profile + thresholds. +- SKILL.md under 350 lines with pattern code moved to references/; corrupted snippet fixed. + +### engineering-team/skills/senior-backend +Verdict: OPTIMIZE +Issues: +- Corrupted Zod snippet at line 253 (`name: "zstringmin1max100"`). +- HTTP status-code table, REST response formats = frontier-embodied filler (A2). +- Load-tester flags shown (`--expect-rate-limit`, `--expect-status`) need verification against actual argparse surface. +Verify (definition of done): +- `python3 scripts/backend_decision_engine.py --team-size 8 --qps-p99 50 --read-write-ratio 20 --tenancy shared-multi-tenant --data-sensitivity pii --pattern modular-monolith --language-preference typescript` exits 0 with profile + SLO floor + approver chain. +- `python3 scripts/api_load_tester.py --help` lists every flag SKILL.md uses. + +### engineering-team/skills/senior-architect +Verdict: OPTIMIZE +Issues: +- Monolith-vs-microservices checkboxes and team-size tables are generic (A2) — senior-fullstack's forcing-question + kill-criterion treatment of the same decision is strictly better; cross-link instead of duplicating. +- No verification loop: workflows end at "document decision" (A4). +- Tools are well-wired (exact CLI, sample outputs) — keep. +Verify (definition of done): +- `python3 scripts/dependency_analyzer.py . --output json` exits 0 and emits `circular` + `coupling_score` keys; SKILL.md workflow ends with "re-run analyzer, assert circular = 0". +- ADR step references a concrete template file that exists in the package. + +### engineering-team/skills/senior-data-engineer +Verdict: OPTIMIZE +Issues: +- 34-line trigger-phrase section is frontmatter duplication (A2); body's batch-vs-streaming and Lambda-vs-Kappa tables are textbook content. +- "Workflows → See references/workflows.md" and "Troubleshooting → See ..." one-liners make the body a stub while references hold the substance — inverted disclosure (workflows.md is solid at 624 lines). +- Tool subcommand contracts (`generate`/`validate`/`analyze`) shown but outputs not consumed by named steps. +Verify (definition of done): +- `python3 scripts/data_quality_validator.py --help` exits 0 and supports the `validate --checks freshness,completeness,uniqueness` syntax shown. +- SKILL.md inlines a 10-line decision rule per workflow with the deep dive staying in references/. + +### engineering-team/skills/incident-commander +Verdict: OPTIMIZE +Issues: +- Orphan scripts: `severity_classifier.py`, `incident_timeline_builder.py`, `postmortem_generator.py` duplicate the 3 wired tools (A3/A7) — delete or wire. +- SEV1-SEV4 definitions overlap incident-response (security flavor) with no disambiguation table; add "this is NOT security incident triage" routing. +- Marketing-prose header block ("battle-tested practices ... at scale") is filler (A2). +Verify (definition of done): +- `ls scripts/ | wc -l` equals the number of scripts referenced in SKILL.md. +- `echo '{"description":"...","affected_users":"80%","business_impact":"high"}' | python3 scripts/incident_classifier.py` exits 0 and output matches `expected_outputs/incident_classification_text_output.txt` semantics. + +### engineering-team/skills/ms365-tenant-manager +Verdict: OPTIMIZE +Issues: +- 3 scripts (`powershell_generator.py`, `tenant_setup.py`, `user_management.py`) never referenced in SKILL.md; root-level `sample_input.json`/`expected_output.json` orphaned too (A3). +- PowerShell content is genuinely expert (Graph SDK, CA report-only-first) — keep; just wire or delete the Python layer. +- Verify Graph cmdlet names still current (MSOnline/AzureAD modules retired; this correctly uses Mg* — confirm references do too). +Verify (definition of done): +- Either SKILL.md shows exact CLI for all 3 scripts with consumed output, or `scripts/` is removed. +- `python3 scripts/powershell_generator.py --help` exits 0 (if retained). + +### engineering-team/skills/stripe-integration-expert +Verdict: OPTIMIZE +Issues: +- Pinned `apiVersion: "2024-04-10"` presented as current (A6). +- 476 lines of TSX/route-handler code a frontier model writes; the durable value (lifecycle state machine, webhook event ordering, idempotency discipline) should lead, code moved to references/. +- No scripts, no references, no verification loop (A3/A4) — e.g., no webhook-handler checklist gate. +Verify (definition of done): +- `grep -c "apiVersion" SKILL.md` hits use a placeholder + "check current API version" instruction, not a pinned date. +- Workflow ends with executable check: `stripe listen`/`stripe trigger checkout.session.completed` smoke procedure with expected handler behavior stated. + +### engineering-team/skills/email-template-builder +Verdict: OPTIMIZE (merge candidate with marketing email skills if it stays code-only) +Issues: +- Entire skill is one 439-line code dump: no scripts/, references/, assets/ (A3/A7). +- React Email component code is frontier-embodied; the value is the pitfalls list (600px, inline styles, dark-mode `!important`, separate sending domains) and provider matrix — invert the ratio. +- No verification loop (no spam-score check step, no preview-render gate) (A4). +Verify (definition of done): +- SKILL.md ≤ 200 lines centered on client-compatibility rules + deliverability checklist; full code in references/. +- Workflow ends with an executable gate (e.g., render template via `npx react-email` preview + checklist assertion of plain-text part present). + +### engineering-team/skills/tech-stack-evaluator +Verdict: OPTIMIZE +Issues: +- "Ecosystem health from GitHub, npm metrics" is a stdlib offline tool — data is embedded snapshots with no as-of date; comparisons silently age (A6). +- Quick-start examples are bare prose prompts, not tool invocations — wire them to the scripts. +- 7 scripts but SKILL.md gives exact CLI for only 5 (format_detector, report_generator unmentioned). +Verify (definition of done): +- `python3 scripts/tco_calculator.py --input assets/sample_input_tco.json` exits 0 and matches `assets/expected_output_comparison.json` schema. +- Every embedded-data script prints a `data_as_of` field in JSON output and SKILL.md tells the model to label conclusions with it. + +### engineering-team/skills/engineering-skills +Verdict: OPTIMIZE +Issues: +- Claims "23 production-ready engineering skills"; `skills/` holds 32; plugin.json says 32; README says 18; START_HERE says 14 — pick one truth (A6/E2). +- As a skill it's a static catalog; its only durable instruction ("load one SKILL.md, don't bulk-load") could live in the plugin description. +- `npx agent-skills-cli add ...` install path needs verification. +Verify (definition of done): +- `ls -d engineering-team/skills/*/ | wc -l` equals the count stated in SKILL.md, plugin.json, README.md, and START_HERE.md. +- Skill table lists every actual folder (no missing security-suite rows). + +## KEEP-verdict verification criteria + +- **adversarial-reviewer** — review output contains all 3 persona sections each with ≥1 finding and ends with verdict ∈ {BLOCK, CONCERNS, CLEAN}; promotion rule applied when 2+ personas overlap. +- **ai-security** — `python3 scripts/ai_threat_scanner.py --target-type llm --access-level black-box --json` exits 0/1/2 per contract and JSON has `overall_risk` + `findings[].finding_type`; `--access-level gray-box` without `--authorized` exits 2. +- **aws-solution-architect** — `python3 scripts/architecture_designer.py --input ` emits `recommended_pattern` + `estimated_monthly_cost_usd`; CloudFormation output passes `aws cloudformation validate-template` (or cfn-lint) when run. +- **azure-cloud-architect** — `python3 scripts/bicep_generator.py --arch-type web-app --output /tmp/main.bicep` exits 0 and output parses with `az bicep build` where available. +- **cloud-security** — `python3 scripts/cloud_posture_check.py .json --check iam --json` exits 2 on a PassRole+CreateFunction policy and 0 on least-privilege sample. +- **code-reviewer** — `python3 scripts/code_quality_checker.py assets/sample_java_smells.java --json | diff - expected_outputs/sample_java_smells_quality.json` is empty (regression fixture green); dispatch table covers every `languages/*.md` file. +- **epic-design** — `python3 scripts/inspect-assets.py --help` exits 0 without Pillow installed; output format matches references/asset-pipeline.md Step 4 contract. +- **gcp-cloud-architect** — `python3 scripts/cost_optimizer.py --resources .json --monthly-spend 2000` exits 0 with itemized savings. +- **incident-response** — `echo '{"event_type":"ransomware","host":"x","raw_payload":{}}' | python3 scripts/incident_triage.py --classify --json` exits 2 (SEV1) and maps T1486. +- **red-team** — `python3 scripts/engagement_planner.py --techniques T1059 --access-level external --json` (no `--authorized`) exits 1; with `--authorized` exits 0 and orders phases by kill chain. +- **security-pen-testing** — `python3 scripts/vulnerability_scanner.py --target web --scope quick --json` exits 0 and emits OWASP A01-A10 checklist items; `dependency_auditor.py --file package.json --json` parses. +- **senior-computer-vision** — `python3 scripts/dataset_pipeline_builder.py --help` lists `--analyze/--clean/--split/--generate-config` flags used in SKILL.md; `inference_optimizer.py --help` lists `--benchmark/--export`. +- **senior-devops** — `python3 scripts/terraform_scaffolder.py /tmp/infra --provider=aws --module=ecs-service` exits 0; generated HCL passes `terraform validate` where available; rollback procedure's `curl -sf .../healthz` gate retained. +- **senior-fullstack** — `python3 scripts/fullstack_decision_engine.py --sample --output json` exits 0 with `ranked_matches[0].profile_name` and empty `kill_criteria_tripped` (verified this audit); engine refuses (non-zero) when any of the 4 required inputs missing. +- **senior-secops** — `python3 scripts/security_scanner.py ` exit codes follow 0/1/2 contract; `compliance_checker.py --framework soc2 --json` emits per-control results; CVE-triage SLA table retained (9.0+ internet-facing = 24h). +- **tdd-guide** — `python3 scripts/coverage_analyzer.py --report assets/sample_coverage_report.lcov --threshold 80` exits per contract and P0/P1/P2 buckets present; `test_generator.py --input --framework pytest` output compiles. +- **threat-detection** — `python3 scripts/threat_signal_analyzer.py --mode anomaly --events-file --baseline-mean 100 --baseline-std 25 --json` exits 2 only when z ≥ 3.0; IOC mode flags >30-day-old IPs as `stale`. +- **a11y-audit** — `python3 scripts/contrast_checker.py --fg "#777777" --bg "#ffffff"` reports fail at 4.5:1; `a11y_scanner.py --ci` exits non-zero only on critical findings; `--baseline` comparison runs. +- **snowflake-development** — `python3 scripts/snowflake_query_helper.py merge --target t --source s --key id --columns a,b` exits 0 and emitted SQL contains colon-prefix rule compliance in proc templates. +- **playwright-pro/pw** — all 9 sub-skill routes listed exist as skill folders; Quick Start sequence references only shipped commands. +- **playwright-pro/init** — generated `playwright.config.ts` sets `retries: 2` in CI / `0` local and `trace: 'on-first-retry'`; first smoke test runs. +- **playwright-pro/generate** — workflow step 7 retained: `npx playwright test --reporter=list` must run before reporting done; no `waitForTimeout` in output. +- **playwright-pro/review** — review loads `anti-patterns.md` (file exists) and flags a seeded `page.waitForTimeout()` fixture. +- **playwright-pro/fix** — fix loads `flaky-taxonomy.md` (file exists); completion requires `--repeat-each=10` 10/10 green. +- **playwright-pro/migrate** — post-migration step routes to `/pw:coverage` parity check before decommissioning old suite. +- **playwright-pro/coverage** — output lists tested vs untested routes with priority ranking. +- **playwright-pro/report** — report generation consumes `playwright-report/` or JSON reporter output, errors clearly when absent. +- **playwright-pro/testrail** — refuses gracefully with setup instructions when `TESTRAIL_URL/USER/API_KEY` unset. +- **playwright-pro/browserstack** — refuses gracefully when `BROWSERSTACK_USERNAME/ACCESS_KEY` unset. +- **self-improving-agent (root)** — memory-paths table matches current Claude Code memory layout (`~/.claude/projects//memory/MEMORY.md`, 200-line load) — recheck against docs each release. +- **si/review** — spawns memory-analyst; output buckets = promotion candidates / stale / consolidation / conflicts / health. +- **si/promote** — promotion writes to CLAUDE.md or `.claude/rules/` AND removes the MEMORY.md source entry (both halves verified). +- **si/extract** — extracted skill passes `scripts/audit_skills.py` (repo validator) with no FAIL. +- **si/remember** — entry written with timestamp + category into the active memory dir. +- **si/status** — dashboard reports line counts vs 200-line budget and flags overflow topic files. + +## Agents + +| Agent | B1 frontmatter | B2 differentiation | B3 body | Verdict | +|---|---|---|---|---| +| playwright-pro/agents/test-architect | PASS (read-only tools) | PASS — plans, explicitly does not write tests | PASS | KEEP | +| playwright-pro/agents/test-debugger | PASS — exemplary scoped `Bash(npx playwright test *)` allowlist + disallowedTools | PASS — taxonomy-driven diagnosis | PASS | KEEP | +| playwright-pro/agents/migration-planner | PASS (read-only) | PASS — detection protocol per framework | PASS | KEEP | +| self-improving-agent/agents/memory-analyst | PASS (Read/Glob/Grep, maxTurns 30) | PASS — read-only analyst, distinct outputs | PASS | KEEP | +| self-improving-agent/agents/skill-extractor | PASS (Write/Edit + disallowedTools) | PASS — portability rules (no hardcoded paths) | PASS | KEEP | + +Note: agent descriptions use "Invoked by /pw:..." rather than "Use when..." trigger phrasing — acceptable since they are command-spawned, not auto-triggered. + +## Commands + +None in scope. engineering-team/ ships no `commands/` directory; the `/pw:*` and `/si:*` surfaces are skills-as-commands (audited above). The grep hits under `commands*` are reference docs, not slash commands. + +## Plugin manifests + +| Plugin | Issue | +|---|---| +| `.claude-plugin/plugin.json` (engineering-skills) | Says "32 skills" — matches `skills/` dir count, but conflicts with SKILL.md (23), README (18), START_HERE (14). Description is a 1,100-char wall; trim. | +| `a11y-audit` | Clean; description matches contents. | +| `google-workspace-cli` | Description repeats the unverifiable `gws` CLI claims; fix alongside the skill REWRITE. | +| `playwright-pro` (name: `pw`) | Clean; "55+ templates, 3 agents" — template count not verified file-by-file but folder structure exists. | +| `self-improving-agent` (name: `si`) | Clean; commands listed all exist as sub-skills. | +| `snowflake-development` | Description's "query helper script, 3 reference guides" verified accurate (1 script, 3 refs). Clean. | + +Additional manifest-adjacent debt: 18 stale `.zip` archives at engineering-team root; engineering-team/CLAUDE.md documents 7 nonexistent script filenames and a "32 skills / 39+ tools" inventory that predates the security suite and sub-plugins. diff --git a/audit/newgen-2026-06/engineering.md b/audit/newgen-2026-06/engineering.md new file mode 100644 index 00000000..d12a2852 --- /dev/null +++ b/audit/newgen-2026-06/engineering.md @@ -0,0 +1,333 @@ +# Domain audit: engineering/ — new-gen model optimization +Audited: 2026-06-10 · Skills: 80 SKILL.md (63 distinct skills; 12 sub-command skills under agenthub/autoresearch; 4 dual-published duplicates; 1 sample asset excluded) · Agents: 14 · Commands: 14 · Plugins: 28 manifests + +## Scorecard + +Bundle = `engineering/skills/`; standalone = `engineering//`. + +| Skill | Verdict | Top issue | +|---|---|---| +| skills/agent-designer | REWRITE | 279 lines of taxonomy prose a frontier model already knows; 3 root-level scripts never wired | +| skills/agent-workflow-designer | OPTIMIZE | Thin body; overlaps agent-designer + workflow-builder | +| skills/api-design-reviewer | OPTIMIZE | ~300 lines of textbook REST; scripts named but no exact CLI in workflow | +| skills/api-test-suite-builder | KEEP | — | +| skills/browser-automation | KEEP | — | +| skills/changelog-generator | KEEP | — (absorb release-manager into it) | +| skills/chaos-engineering (+ standalone dup) | KEEP | — (deduplicate copies) | +| skills/ci-cd-pipeline-builder | KEEP | — | +| skills/codebase-onboarding | OPTIMIZE | Thin; 1 script, low expertise density | +| skills/command-guide | CUT-OR-MERGE | Documents another repo's (ECC) commands/agents that don't exist here | +| skills/database-designer | CUT-OR-MERGE | Overlaps 2 siblings; claims "included tools" with zero CLI wiring | +| skills/database-schema-designer | CUT-OR-MERGE | No scripts; broken seed-code example; overlaps database family | +| skills/dependency-auditor | REWRITE | Marketing brochure ("Future Enhancements", "Planned Features"); unverifiable claims | +| skills/engineering-advanced-skills | OPTIMIZE | Index says "25 skills", plugin says 40; wrong load paths | +| skills/env-secrets-manager | KEEP | — (fix dead cross-refs) | +| skills/feature-flags-architect (+ dup) | KEEP | — (deduplicate copies) | +| skills/focused-fix | KEEP | — (references external `superpowers:*` skills) | +| skills/full-page-screenshot | KEEP | — | +| skills/git-worktree-manager | KEEP | — | +| skills/interview-system-designer | OPTIMIZE | HR skill in engineering domain; 4 scripts, 1 wired | +| skills/kubernetes-operator (+ dup) | KEEP | — (deduplicate copies) | +| skills/mcp-server-builder | KEEP | — | +| skills/migration-architect | REWRITE | 477 lines textbook; scripts named only in "Tools" section, no CLI | +| skills/monorepo-navigator | KEEP | — | +| skills/observability-designer | REWRITE | Brochure prose; no exact CLI; overlaps slo-architect | +| skills/performance-profiler | KEEP | — | +| skills/pr-review-expert | KEEP | — | +| skills/rag-architect | REWRITE | Stale (ada-002, 2024 Pinecone pricing); 3 scripts never wired; textbook | +| skills/release-manager | CUT-OR-MERGE | 489-line textbook; duplicates changelog-generator; scripts unwired | +| skills/runbook-generator | OPTIMIZE | Thin skeleton generator, low expertise density | +| skills/secrets-vault-manager | KEEP | — | +| skills/self-eval | KEEP | — | +| skills/ship-gate | KEEP | — | +| skills/skill-security-auditor | KEEP | — | +| skills/skill-tester | REWRITE | 390-line brochure incl. "Future Enhancements"; CLI shown without paths | +| skills/slo-architect (+ dup) | KEEP | — (deduplicate copies) | +| skills/spec-driven-workflow | KEEP | — | +| skills/sql-database-assistant | KEEP | — (merge target for the database trio) | +| skills/tc-tracker | KEEP | — | +| skills/tech-debt-tracker | REWRITE | Roadmap/KPI filler; 5 passing scripts, zero CLI wiring | +| agenthub (8 SKILL.md) | KEEP | — | +| autoresearch-agent (6 SKILL.md) | KEEP | — (document evaluator --help exception in SKILL.md) | +| behuman | KEEP | — (not registered in marketplace) | +| caveman | KEEP | — | +| claude-coach | OPTIMIZE | Duplicate frontmatter keys; README content pasted into SKILL.md tail | +| code-tour | KEEP | — | +| data-quality-auditor | KEEP | — | +| demo-video | KEEP | — | +| docker-development | KEEP | — | +| grill-me | KEEP | — | +| grill-with-docs | KEEP | — (not registered in marketplace) | +| handoff (engineering) | KEEP | — | +| helm-chart-builder | KEEP | — | +| karpathy-coder | KEEP | — | +| llm-cost-optimizer | KEEP | — (not registered in marketplace) | +| llm-wiki | KEEP | — | +| prompt-governance | KEEP | — (not registered in marketplace) | +| security-guidance | KEEP | — | +| statistical-analyst | KEEP | — | +| terraform-patterns | KEEP | — | +| universal-scraping-architect | OPTIMIZE | 3 orphan scripts; placeholder agent + command; non-stdlib deps | +| workflow-builder | KEEP | — | +| write-a-skill | KEEP | — | + +**Totals: KEEP 44 · OPTIMIZE 8 · REWRITE 7 · CUT-OR-MERGE 4** (63 distinct skills) + +## Domain-level findings + +1. **Two clear generations.** v2.4+ skills (slo-architect, chaos-engineering, kubernetes-operator, feature-flags-architect, karpathy-coder, workflow-builder, the Pocock ports, agenthub, autoresearch) are exemplary: trigger-rich descriptions, exact CLI per tool, refusal gates, "Verifiable success" sections. ~10 v2.0-era skills in `engineering/skills/` are capability brochures ("Future Enhancements", "Conclusion", "Planned Features" sections) whose body is knowledge a frontier model already has — pure context dead weight. +2. **Orphan-script epidemic in v2.0-era skills.** agent-designer, rag-architect, release-manager, database-designer (root-level `.py`), tech-debt-tracker and skill-tester (in `scripts/`) all ship working scripts (`--help` passes) that SKILL.md never invokes with a runnable command. A model following the SKILL.md will never run them — A3 failure across the board. universal-scraping-architect same pattern. +3. **Overlap clusters burning context.** (a) Database trio: database-designer / database-schema-designer / sql-database-assistant — sql-database-assistant alone covers ~90%; (b) release pair: release-manager vs changelog-generator (changelog-generator is the wired, lean one); (c) observability-designer vs slo-architect (slo-architect is strictly better on the SLO half). +4. **Byte-identical dual-published copies.** slo-architect, chaos-engineering, kubernetes-operator, feature-flags-architect each exist in both `engineering/skills/` and `engineering//skills//` (verified `diff` identical). No single source of truth; edits will diverge. +5. **Counter and registry drift.** Bundle index SKILL.md says "25 advanced engineering skills"; its plugin.json says 40; the marketplace description for `engineering-advanced-skills` lists skills (llm-cost-optimizer, prompt-governance, behuman, code-tour, demo-video, data-quality-auditor, statistical-analyst, llm-wiki…) that live in standalone plugin folders OUTSIDE the manifest's `"skills": ["./skills"]` path. Separately, 5 plugins with valid plugin.json (behuman, claude-coach, grill-with-docs, llm-cost-optimizer, prompt-governance) are not registered in marketplace.json at all. +6. **Dead cross-references.** env-secrets-manager points to `engineering/senior-secops`, `engineering/infrastructure-as-code`, `engineering/container-orchestration` (none exist; senior-secops lives in engineering-team/); sql-database-assistant points to nonexistent `observability-platform`; focused-fix references external `superpowers:*` skills; command-guide is entirely about a foreign ecosystem. +7. **Freshness spots.** rag-architect: `text-embedding-ada-002` as "quality model", "$70/month Pinecone 1M vectors" — 2023/24 facts presented as current. command-guide: `/fast` "(Opus 4.6 only)". api-design-reviewer example timestamps "2024-…". +8. **Reference quality is bimodal.** v2.0-era references (rag-architect, dependency-auditor, agent-designer) are uncited encyclopedic prose a frontier model regenerates on demand; v2.6+ references cite canon by name (Evans/Nygard/Google SRE Workbook/Pocock). +9. **By-design script exceptions partly documented.** autoresearch evaluators carry "DO NOT MODIFY — fixed evaluator" headers, but the SKILL.md never states they intentionally fail `--help`; security-guidance hook's stdin contract IS documented in its SKILL.md (good). + +## Per-skill findings + +### engineering/skills/agent-designer +Verdict: REWRITE +Issues: +- Entire 279-line body is generic multi-agent taxonomy (Supervisor/Swarm/Pipeline pros-cons) — A2/A5 fail; a frontier model knows all of it. +- 3 working scripts (`agent_planner.py`, `tool_schema_generator.py`, `agent_evaluator.py`, all pass `--help`) are never mentioned in SKILL.md — A3 fail; assets/expected_outputs unused. +- Description is bare trigger sentence with no mention of tools. +- Overlaps agent-workflow-designer and workflow-builder. +Verify: `python3 engineering/skills/agent-designer/agent_planner.py --help` exits 0 AND SKILL.md contains the literal string `agent_planner.py` with a runnable invocation; SKILL.md < 150 lines; `grep -c "Pros:" SKILL.md` returns 0. + +### engineering/skills/agent-workflow-designer +Verdict: OPTIMIZE +Issues: +- 83-line body is mostly headers; pattern map duplicates `references/workflow-patterns.md` one-liners. +- No verification loop — scaffolder output is never validated by a named next step. +- Scope collision with workflow-builder (Claude Code Workflow tool) and agent-designer; needs explicit "NOT for" routing. +Verify: `python3 scripts/workflow_scaffolder.py sequential --name t` exits 0 and emits JSON; SKILL.md gains a "When NOT to use" block naming workflow-builder. + +### engineering/skills/api-design-reviewer +Verdict: OPTIMIZE +Issues: +- Lines 41–333 restate REST conventions/pagination/status codes any frontier model knows — cut to references or delete. +- Tools section describes features but the only invocations are inside CI YAML examples; no first-class Quick Start CLI. +- Example timestamp `2024-02-16` (A6 nit). +Verify: `python3 scripts/api_linter.py --help` exits 0; SKILL.md has a Quick Start with all 3 script invocations; body ≤ 200 lines. + +### engineering/skills/codebase-onboarding +Verdict: OPTIMIZE +Issues: +- 84 lines, single analyzer script; "Tailor output depth by audience" is the only non-obvious content. +- No verification loop (generated doc never validated against repo facts). +Verify: `python3 scripts/codebase_analyzer.py . --json` exits 0 and emits JSON with language/file-count keys; SKILL.md adds a post-generation check (e.g. "every setup command in the doc was executed once"). + +### engineering/skills/command-guide +Verdict: CUT-OR-MERGE +Issues: +- Documents commands/agents from the ECC ecosystem (`planner`, `build-error-resolver`, `tdd-guide`, `/build-fix`, `/learn`, `/remember`) — none ship in this repo; actively misleads the model into invoking nonexistent tools. +- `/fast` "(Opus 4.6 only)" — stale model gating (A6). +- Zero scripts, zero references; auto-trigger table tells the model to "immediately invoke" agents that don't exist here. +Verify (if kept at all): every command/agent named in the file resolves to a file in this repo (`grep -o '/[a-z-]*' SKILL.md` cross-checked against commands/); otherwise delete from plugin. + +### engineering/skills/database-designer +Verdict: CUT-OR-MERGE (fold unique tables into sql-database-assistant) +Issues: +- "The included tools automate common analysis" but no script invocation anywhere; 3 root scripts orphaned (A3). +- JOIN/CTE/window-function content is textbook (A2); decision matrices duplicate sql-database-assistant's. +- Three-way overlap with database-schema-designer and sql-database-assistant; cross-refs to both admit it. +Verify: after merge, `engineering/skills/sql-database-assistant/SKILL.md` contains the sharding/replication tables; `schema_analyzer.py`/`index_optimizer.py`/`migration_generator.py` either wired into sql-database-assistant or deleted. + +### engineering/skills/database-schema-designer +Verdict: CUT-OR-MERGE +Issues: +- No scripts at all; SKILL.md is one worked example + RLS snippets. +- Seed-data example is syntactically broken (`name: "fakercompanycatchphrase"` — missing comma, dead faker call, line ~155). +- ERD/normalization mandate duplicates database-designer's claims. +Verify: RLS policy block and pitfalls table migrated into the surviving database skill; broken seed example deleted or fixed to parse with `npx tsc --noEmit`. + +### engineering/skills/dependency-auditor +Verdict: REWRITE +Issues: +- ~250 of 337 lines are brochure ("Use Cases & Applications", "Future Enhancements", "Metrics & KPIs") — A2/A7 fail. +- Claims "built-in vulnerability database with 500+ CVE patterns", live "PyPI/npm advisory" cross-referencing — SKILL.md's own scripts are offline pattern matchers; over-claims capability. +- Quick Start has 3 CLI lines buried at the bottom; no output-consumption step, no verification loop. +Verify: `python3 scripts/dep_scanner.py --help` exits 0; rewritten SKILL.md ≤ 150 lines, leads with the 3 CLIs + JSON keys consumed; no "Future Enhancements"/"Planned Features" headings remain. + +### engineering/skills/engineering-advanced-skills +Verdict: OPTIMIZE +Issues: +- H1/body says "25 advanced engineering skills"; plugin.json says 40; folder has 39 + index — three different counts. +- Quick Start path `/read engineering/agent-designer/SKILL.md` is wrong (real path `engineering/skills/agent-designer/SKILL.md`). +- Table lists 25 of 39 skills; missing the reliability quartet, ship-gate, self-eval, tc-tracker, etc. +Verify: `ls engineering/skills | wc -l` matches the count stated in SKILL.md and plugin.json description; every path in the table resolves. + +### engineering/skills/interview-system-designer +Verdict: OPTIMIZE +Issues: +- Hiring-process skill living in the engineering plugin — domain misfit (product-team/c-level fit better). +- 4 scripts present, only `interview_planner.py` wired; 59-line body with generic best practices. +Verify: all shipped scripts referenced with exact CLI in SKILL.md or removed; `python3 scripts/interview_planner.py --role "SWE" --level senior --json` exits 0 with JSON. + +### engineering/skills/migration-architect +Verdict: REWRITE +Issues: +- 477 lines; Strangler Fig/CDC/blue-green content is textbook (A2); "Communication Templates" and "Success Metrics" sections are filler (A7). +- Scripts (`migration_planner.py`, `compatibility_checker.py`, `rollback_generator.py`) appear only as bullet names + one CI YAML snippet — no Quick Start CLI (A3). +- No verification loop; checklists are prose, not machine-checkable. +Verify: `python3 engineering/skills/migration-architect/migration_planner.py --help` exits 0; rewritten SKILL.md ≤ 200 lines with all 3 CLIs and a "plan must pass compatibility_checker with 0 CRITICAL" gate. + +### engineering/skills/observability-designer +Verdict: REWRITE +Issues: +- 268 lines of golden-signals/RED/USE/three-pillars prose — pure frontier-model knowledge (A2/A5). +- "Scripts Overview" describes I/O shapes but gives zero runnable commands (A3); scripts pass `--help`. +- Overlaps slo-architect (which does the SLO half with thresholds + math + refusal gates); this skill should shrink to dashboards + alert-noise tooling and route SLO work to slo-architect. +Verify: `python3 scripts/slo_designer.py --help`, `alert_optimizer.py --help`, `dashboard_generator.py --help` all exit 0 AND appear as exact CLIs in SKILL.md; "When NOT to use → slo-architect" block present. + +### engineering/skills/rag-architect +Verdict: REWRITE +Issues: +- Stale facts as current: `text-embedding-ada-002` as the quality tier, "Pinecone $70/month for 1M vectors", model lists from 2023/24 (A6). +- 3 root scripts (`chunking_optimizer.py`, `rag_pipeline_designer.py`, `retrieval_evaluator.py`, all pass `--help`) never referenced in SKILL.md (A3). +- 318 lines of chunking/retrieval taxonomy a frontier model knows; only 1 reference doc, uncited (A7). +Verify: `python3 engineering/skills/rag-architect/chunking_optimizer.py --help` exits 0 AND is invoked in SKILL.md; zero occurrences of `ada-002` / hardcoded vendor prices; body ≤ 200 lines. + +### engineering/skills/release-manager +Verdict: CUT-OR-MERGE (into changelog-generator) +Issues: +- 489-line SemVer/Git-Flow/conventional-commits textbook (A2); changelog-generator already ships the wired, lean version of the changelog/bump core. +- 3 root scripts named in "Key Components" but never invoked (A3). +- Hotfix SLAs and rollback triggers are the only practitioner content — migrate those tables. +Verify: hotfix-severity and rollback-trigger tables present in the surviving skill; `version_bumper.py`/`release_planner.py` wired with exact CLI or deleted; no duplicate conventional-commit spec across the two skills. + +### engineering/skills/runbook-generator +Verdict: OPTIMIZE +Issues: +- 76 lines, one template-skeleton script, generic best practices; weakest of the wired DevOps set. +- No verification loop (runbook never validated — e.g., "every command block has an expected-output check"). +Verify: `python3 scripts/runbook_generator.py payments-api --owner x` exits 0 and emits the standard sections; SKILL.md adds a post-generation checklist the model executes (rollback section non-empty, every step has a verify line). + +### engineering/skills/skill-tester +Verdict: REWRITE +Issues: +- 390 lines, heavy brochure: "Performance & Scalability", "Security & Safety", "Future Enhancements", "Conclusion" (A7). +- CLI examples lack paths (`skill_validator.py path/to/skill` won't run from repo root); one example references nonexistent `trend_analyzer.py` (phantom script, A3). +- Tier line-count requirements conflict with write-a-skill's "SKILL.md under 100 lines" doctrine — repo-internal contradiction. +Verify: `python3 engineering/skills/skill-tester/scripts/skill_validator.py engineering/skills/self-eval --json` exits 0 with JSON; no reference to `trend_analyzer.py`; body ≤ 200 lines. + +### engineering/skills/tech-debt-tracker +Verdict: REWRITE +Issues: +- Body is a 6-week "Implementation Roadmap" + aspirational KPIs ("25% reduction in debt interest rate") — filler, zero operational instructions (A2/A5). +- 5 scripts incl. `debt_scanner.py`/`debt_prioritizer.py`/`debt_dashboard.py` all pass `--help` but SKILL.md contains not one CLI invocation (A3) — worst wiring gap in the domain relative to tooling quality. +- 4 references + 4 assets unreferenced from the body (A7). +Verify: SKILL.md Quick Start runs all 3 core scripts with exact flags; `python3 scripts/debt_scanner.py --help` exits 0; scan→prioritize→dashboard pipeline shows which JSON keys flow between steps. + +### engineering/claude-coach +Verdict: OPTIMIZE +Issues: +- Frontmatter has duplicate/case-variant keys (`Name:` + `name:`, `Version: 1.0.0` + `version: 2.9.0`, stray `Tier/Category/Dependencies`) — undefined parse behavior. +- Lines 145–205 re-paste Name/Description/Features/Usage (README content) after the body ends — duplication (A7). +- Scripts listed at the very bottom with no CLI; `coach_tip_classifier.py` is core to Rule 5 but never invoked. +Verify: `python3 -c "import yaml,io; yaml.safe_load(open('engineering/claude-coach/skills/claude-coach/SKILL.md').read().split('---')[1])"` yields exactly one `name`/`version`; `python3 scripts/coach_tip_classifier.py --help` exits 0 and appears as a CLI in the body. + +### engineering/universal-scraping-architect +Verdict: OPTIMIZE +Issues: +- 3 scripts (`validate_extraction.py`, `firecrawl_example.py`, `local_bs4_example.py`) never referenced in SKILL.md (A3). +- Agent (`cs-scraping-architect.md`, 6 lines) and command (`cs-scrape.md`, 6 lines) are placeholders — B3/C3 fail. +- "You are an expert…" opener (A2 filler); non-stdlib deps (firecrawl/pandas/bs4) acceptable (BYOK documented) but should be listed per-script. +- Layout anomaly: only engineering plugin with SKILL.md at plugin root (no `skills/` dir). +Verify: `python3 engineering/universal-scraping-architect/scripts/validate_extraction.py --help` exits 0 and is invoked in SKILL.md step 4 ("Validate & Clean"); agent file ≥ 40 lines with tools + triggers or deleted. + +## KEEP-verdict verification criteria + +- **api-test-suite-builder** — Next.js route-scan command from SKILL.md runs against a sample app dir without error; auth matrix table retains all 6 rows. +- **browser-automation** — `python3 scripts/anti_detection_checker.py --help` exits 0; all 3 referenced reference files exist. +- **changelog-generator** — `printf 'feat: x\nfix: y\n' | python3 scripts/generate_changelog.py --next-version v1.0.0 --format json` exits 0 with `Added`/`Fixed` sections; `commit_linter.py --strict` exits non-zero on `bad message`. +- **chaos-engineering** — `python3 scripts/blast_radius_calculator.py --traffic-share 0.05 --user-pop 1000000 --duration-min 15` exits 0, output contains GREEN/YELLOW/RED; bundle and standalone copies stay byte-identical (`diff -r`) until deduped. +- **ci-cd-pipeline-builder** — `python3 scripts/stack_detector.py --repo . --format json` exits 0 with detected-language keys; generated YAML parses (`python3 -c "import yaml,sys; yaml.safe_load(open('out.yml'))"`). +- **env-secrets-manager** — `python3 scripts/env_auditor.py . --json` exits 0 with severity-tagged findings; cross-reference table contains no path that fails `ls`. +- **feature-flags-architect** — `python3 scripts/rollout_planner.py --population 100000 --target-percent 100 --duration-days 14 --strategy ring` exits 0 with a phased table; `kill_switch_audit.py --help` exits 0. +- **focused-fix** — 5-phase headings (SCOPE/TRACE/DIAGNOSE/FIX/VERIFY) and the 3-strike escalation rule remain; `superpowers:` references either resolve or are reworded as optional externals. +- **full-page-screenshot** — `node scripts/full-page-screenshot.mjs --check` exits with documented status; anti-pattern table intact. +- **git-worktree-manager** — `python3 scripts/worktree_manager.py --help` and `worktree_cleanup.py --help` exit 0; validation checklist (ports file, env copy) retained. +- **kubernetes-operator** — `python3 scripts/crd_validator.py --help` exits 0; capability levels L1–L5 retained; dedupe with bundle copy. +- **mcp-server-builder** — `python3 scripts/openapi_to_mcp.py --help` and `mcp_validator.py --help` exit 0; strict mode returns non-zero on a manifest with a duplicate tool name. +- **monorepo-navigator** — `python3 scripts/monorepo_analyzer.py . --json` exits 0; pitfalls table keeps the `--filter` and `git filter-repo` rows. +- **performance-profiler** — `python3 scripts/performance_profiler.py . --json` exits 0; before/after template and "Measure First" rule retained. +- **pr-review-expert** — security-scan grep block runs against a sample diff without syntax errors; 30+ item checklist count ≥ 30. +- **secrets-vault-manager** — 3 tool names in the Tools table map to existing files in scripts/ (add exact CLI when touched); Vault HCL snippets parse visually. +- **self-eval** — composite matrix unchanged (Low ambition caps at 2; 5 requires High+Strong); scores append to `.self-eval-scores.jsonl`. +- **ship-gate** — `references/checks.md` and `references/patterns.md` exist; category table sums (55 auto + 27 manual) match checks.md entries. +- **skill-security-auditor** — `python3 scripts/skill_security_auditor.py engineering/skills/self-eval --json` exits 0 with verdict ∈ {PASS, WARN, FAIL}. +- **slo-architect** — `python3 scripts/error_budget_calculator.py --target 99.9 --window-days 30` exits 0 and prints 43.20 min allowed downtime (verified this audit); `slo_review.py` flags `target ≥ 99.99` docs. +- **spec-driven-workflow** — `python3 scripts/spec_validator.py --help` and `test_extractor.py --help` exit 0; Iron Law + bounded-autonomy STOP list retained. +- **sql-database-assistant** — `python3 scripts/query_optimizer.py --query "SELECT * FROM t" --dialect postgres` exits 0 with findings; dialect table retains all 4 engines. +- **tc-tracker** — `python3 scripts/tc_init.py --project T --root /tmp/tc-test && python3 scripts/tc_validator.py --registry /tmp/tc-test/docs/TC/tc_registry.json` both exit 0; state machine rejects `planned → deployed`. +- **agenthub** — `python3 scripts/hub_init.py --help`, `dag_analyzer.py --help`, `result_ranker.py --help` exit 0; all 7 `/hub:*` sub-skills name a script or Agent-tool call. +- **autoresearch-agent** — `python3 scripts/run_experiment.py --help` exits 0; evaluators intentionally fail `--help` (fixed contract) — add one sentence to SKILL.md documenting this; `setup_experiment.py --help` exits 0. +- **behuman** — Show/Quiet mode contract + 3 worked examples retained; token-cost table present. Register in marketplace or document why not. +- **caveman** — Matt's persistence + auto-clarity rules verbatim; `python3 scripts/caveman_lint.py "Sure! I'd be happy to help" ` flags filler. +- **code-tour** — schema block contains `$schema: https://aka.ms/codetour-schema`; validation checklist (verified line numbers, ≤2 content steps) intact. +- **data-quality-auditor** — `python3 scripts/data_profiler.py --help`, `missing_value_analyzer.py --help`, `outlier_detector.py --help` all exit 0; DQS weights sum to 100%. +- **demo-video** — fallback ladder (MCPs → manual build.sh) retained; output artifact list (scenes/, narration/, scenes.json, build.sh) unchanged. +- **docker-development** — `python3 scripts/dockerfile_analyzer.py --help` and `compose_validator.py --help` exit 0; 3 multi-stage patterns + base-image decision tree retained. +- **grill-me / grill-with-docs** — one-question-per-turn + recommended-answer rules verbatim; `python3 scripts/context_md_linter.py --help` (grill-with-docs) exits 0. Register grill-with-docs in marketplace. +- **handoff** — `mktemp` convention + no-duplication rule verbatim; 5 sections list unchanged. +- **helm-chart-builder** — `python3 scripts/chart_analyzer.py --help` exits 0; scaffold tree includes pdb.yaml + networkpolicy.yaml. +- **karpathy-coder** — `python3 scripts/complexity_checker.py --help` and `diff_surgeon.py --help` exit 0; 4 principles + relax conditions retained. +- **llm-cost-optimizer** — ROI-ordered 6 techniques with % ranges retained; proactive-flag table (max_tokens unset, >2k-token system prompt) intact; model-tier examples refreshed when model names rotate. +- **llm-wiki** — `python3 scripts/init_vault.py --help` and `lint_wiki.py --help` exit 0; Iron rule (never write raw/) retained; 8 references exist. +- **prompt-governance** — registry YAML schema + eval-type table retained; golden-dataset minimums (20/100+) intact. +- **security-guidance** — `echo '{}' | python3 hooks/security_reminder_hook.py` exits 0 (clean input); pattern table has all 12 rows; attribution block in plugin.json present. +- **statistical-analyst** — `python3 scripts/hypothesis_tester.py --test ztest --control-n 5000 --control-x 250 --treatment-n 5000 --treatment-x 310` exits 0 reporting +1.2pp (verified this audit); effect-size tables intact. +- **terraform-patterns** — `python3 scripts/tf_module_analyzer.py --help` and `tf_security_scanner.py --help` exit 0; review checklist (state, providers, security) retained. +- **workflow-builder** — `python3 scripts/validate_workflow.py --sample` and `workflow_intake.py --help` exit 0; hard-rules list (pure-literal meta, no Date.now, thunks) retained. +- **write-a-skill** — Matt's 3-phase flow + description requirements verbatim; `python3 scripts/skill_review_checklist_runner.py engineering/write-a-skill/skills/write-a-skill` exits 0. + +## Agents + +| Agent | Verdict | Issue | +|---|---|---| +| agenthub/hub-coordinator | KEEP | Strong: scoped tools allowlist/denylist, hard rules, re-spawn policy | +| autoresearch/experiment-runner | OPTIMIZE | No YAML frontmatter at all (no name/description/tools) — B1 fail; body is good | +| caveman/cs-caveman-mode | KEEP | — | +| claude-coach/cs-claude-coach | KEEP | — | +| grill-me/cs-grill-master | KEEP | Distinct voice + forcing-question pattern | +| grill-with-docs/cs-grill-with-docs | KEEP | — | +| handoff/cs-handoff-author | KEEP | Hard refusals make persona behavioral, not adjectival | +| karpathy-coder/karpathy-reviewer | KEEP | Model exemplar: tool allow/deny lists, exact workflow, report shape | +| llm-wiki/wiki-ingestor | KEEP | — | +| llm-wiki/wiki-librarian | KEEP | — | +| llm-wiki/wiki-linter | KEEP | — | +| universal-scraping-architect/cs-scraping-architect | REWRITE | 6-line placeholder: no tools, no triggers, no workflow — B1/B2/B3 fail | +| workflow-builder/cs-workflow-architect | KEEP | — | +| write-a-skill/cs-skill-author | KEEP | — | + +## Commands + +| Command | Verdict | Issue | +|---|---|---| +| caveman/cs-caveman | KEEP | Enforces persistence + auto-clarity; wires 3 scripts | +| claude-coach/cs-claude-coach | KEEP | Handles $ARGUMENTS, fixed activation sequence | +| grill-me/cs-grill-me | KEEP | — | +| grill-with-docs/cs-grill-with-docs | KEEP | — | +| handoff/cs-handoff | KEEP | — | +| karpathy-coder/karpathy-check | KEEP | Orchestrates 2 scripts + sub-agent — earns its slot | +| llm-wiki/wiki-init | KEEP | — | +| llm-wiki/wiki-ingest | KEEP | — | +| llm-wiki/wiki-query | KEEP | — | +| llm-wiki/wiki-lint | KEEP | — | +| llm-wiki/wiki-log | KEEP | — | +| universal-scraping-architect/cs-scrape | CUT-OR-MERGE | 6-line placeholder; a bare prompt does strictly more — C3 fail; no $ARGUMENTS handling | +| workflow-builder/cs-workflow-build | KEEP | — | +| write-a-skill/cs-write-a-skill | KEEP | — | + +Note: agenthub's 7 `/hub:*` and autoresearch's 5 `/ar:*` surfaces ship as command-style sub-skills (frontmatter `command:` key) rather than `commands/*.md` files — all are substantive and wired; counted under their parent skill verdicts. + +## Plugin manifests + +1. **engineering-advanced-skills (engineering/.claude-plugin/plugin.json + marketplace.json:227)** — description claims skills not shipped by the manifest: llm-cost-optimizer, prompt-governance, behuman, code-tour, demo-video, data-quality-auditor, statistical-analyst, llm-wiki live in standalone plugin folders, while `"skills": ["./skills"]` only packages `engineering/skills/` (40 dirs). E2 fail. +2. **Triple count mismatch** — bundle index SKILL.md "25 skills" vs plugin description "40" vs 39 actual skills + 1 index dir. +3. **Five orphan plugins** — behuman, claude-coach, grill-with-docs, llm-cost-optimizer, prompt-governance have valid `.claude-plugin/plugin.json` but no marketplace.json entry (handoff is registered as `handoff-engineering`; these five aren't registered at all). +4. **Dual-published duplicates** — slo-architect, chaos-engineering, kubernetes-operator, feature-flags-architect exist byte-identical in two paths; only the standalone copies are marketplace-registered, but the bundle copies also ship via engineering-advanced-skills → users installing both get duplicates with identical trigger descriptions. +5. **Version coherence** — workflow-builder plugin.json is `1.0.0` while every sibling is `2.9.0` (marketplace itself is at v2.10.x per root CLAUDE.md — domain-wide version lag is cosmetic but uniform). diff --git a/audit/newgen-2026-06/marketing.md b/audit/newgen-2026-06/marketing.md new file mode 100644 index 00000000..50ddbbdf --- /dev/null +++ b/audit/newgen-2026-06/marketing.md @@ -0,0 +1,246 @@ +# Domain audit: marketing-skill/ + marketing/ — new-gen model optimization +Audited: 2026-06-10 · Skills: 49 (47 in marketing-skill/skills + video-content-strategist + marketing/landing) · Agents: 6 · Commands: 4 · Plugins: 5 + +## Scorecard + +| Skill | Verdict | Top issue | +|---|---|---| +| ab-test-setup | OPTIMIZE | Orphan script `sample_size_calculator.py` never named in SKILL.md | +| ad-creative | OPTIMIZE | Stale Meta ">20% image text = reduced distribution" rule (retired 2021) presented as current | +| aeo | KEEP | — | +| ai-seo | CUT-OR-MERGE | Near-total overlap with `aeo` (same goal, no tooling); two skills own one lane | +| analytics-tracking | OPTIMIZE | GA4 "Conversions" terminology (renamed Key events, Mar 2024); script wiring vague | +| app-store-optimization | KEEP | — | +| brand-guidelines | CUT-OR-MERGE | 93-line generic checklist a frontier model already knows; hardcoded Anthropic identity | +| campaign-analytics | KEEP | — | +| churn-prevention | KEEP | — | +| cold-email | KEEP | — | +| competitor-alternatives | OPTIMIZE | Orphan script `comparison_matrix_builder.py` | +| content-creator | CUT-OR-MERGE | Deprecated redirect still shipping 4 refs + 1 asset + agent + zip | +| content-humanizer | OPTIMIZE | 2/6 on repo checklist (worst in domain); AI-tell list itself aging ("delve" era) | +| content-production | OPTIMIZE | 3 of 4 scripts orphaned in SKILL.md | +| content-strategy | OPTIMIZE | Hollow core ("→ see references"); orphan `topic_cluster_mapper.py` | +| copy-editing | OPTIMIZE | Both scripts (`ai_content_detector`, `readability_scorer`) orphaned | +| copywriting | OPTIMIZE | Orphan `headline_scorer.py` | +| email-sequence | OPTIMIZE | Phantom `../../tools/REGISTRY.md` + 5 integration guide links; none exist | +| form-cro | OPTIMIZE | Hollow core; orphan `form_field_analyzer.py` | +| free-tool-strategy | KEEP | — | +| launch-strategy | OPTIMIZE | 74-line shell; orphan `launch_readiness_scorer.py` | +| marketing-context | OPTIMIZE | Writes `.agents/marketing-context.md` while siblings read 2 other paths | +| marketing-demand-acquisition | OPTIMIZE | `updated: 2025-01`, "q1-2025" examples; persona-narrow (Series A+ EU/US) | +| marketing-ideas | KEEP | — | +| marketing-ops | OPTIMIZE | Router missing 11 of 47 skills (incl. aeo, webinar, ASO, x-twitter) | +| marketing-psychology | KEEP | — | +| marketing-skills | CUT-OR-MERGE | Index-as-skill: stale counts (42/7/27 vs actual 47/8/58+), all example paths broken | +| marketing-strategy-pmm | KEEP | — | +| onboarding-cro | OPTIMIZE | Orphan `activation_funnel_analyzer.py` | +| page-cro | OPTIMIZE | Orphan `conversion_audit.py` | +| paid-ads | OPTIMIZE | Phantom tools/REGISTRY.md; 2 orphan scripts; "2024Q1/Mar24" naming examples | +| paywall-upgrade-cro | KEEP | — | +| popup-cro | OPTIMIZE | Hollow core ("→ see references"); zero tooling | +| pricing-strategy | KEEP | — | +| programmatic-seo | OPTIMIZE | Orphan `url_pattern_generator.py` | +| prompt-engineer-toolkit | REWRITE | All 3 references are stubs (328 B / 675 B / 1.5 KB); body ≠ marketing description | +| referral-program | KEEP | — | +| schema-markup | KEEP | — | +| seo-audit | OPTIMIZE | Hollow core; both scripts orphaned | +| signup-flow-cro | OPTIMIZE | Orphan `funnel_drop_analyzer.py` | +| site-architecture | KEEP | — | +| social-content | KEEP | — | +| social-media-analyzer | KEEP | — | +| social-media-manager | OPTIMIZE | Orphan `social_calendar_generator.py` | +| webinar-marketing | OPTIMIZE | `webinar_funnel_scorer.py` has no argparse — `--help` crashes (only D1 fail in domain) | +| x-twitter-growth | KEEP | — | +| youtube-full | KEEP | — | +| video-content-strategist | KEEP | — | +| landing (marketing/) | KEEP | — | + +Verdict counts: **KEEP 20 · OPTIMIZE 24 · REWRITE 1 · CUT-OR-MERGE 4** + +## Domain-level findings + +1. **24 orphan scripts (systemic A3 failure).** Scripts exist and pass `--help` (583/593 repo sweep) but are never named in their own SKILL.md, so a model loading the skill never knows they exist: ab-test-setup, cold-email, competitor-alternatives, content-production (×3), content-strategy, copy-editing (×2), copywriting, email-sequence, form-cro, launch-strategy, marketing-context, marketing-ops, onboarding-cro, page-cro, paid-ads (×2), programmatic-seo, seo-audit (×2), signup-flow-cro, social-media-manager. One repo-wide wiring PR fixes ~half the OPTIMIZE verdicts. +2. **Context-file path schism (foundational pattern silently no-ops).** 19 skills check `.claude/product-marketing-context.md`, 16 check `marketing-context.md`, and the `marketing-context` skill that *creates* the file writes `.agents/marketing-context.md`. Whatever path the user's file is at, half the domain won't find it. Pick one canonical path. +3. **Count drift in 4 places.** marketing-skills SKILL.md: "42 skills / 7 pods / 27 tools"; marketplace.json: "44 skills / 7 pods"; plugin.json + CLAUDE.md: "45 skills / 8 pods"; actual: 47 skill dirs (incl. 1 deprecated redirect and 1 index). All example invocation paths in marketing-skills/SKILL.md omit the `skills/` segment and are broken. +4. **Duplicate AI-search lane.** `aeo` (v2.7.3 port, 3 working scripts, calibrated industry thresholds) and `ai-seo` (older, prose-only) both own "get cited by ChatGPT/Perplexity." The router routes AI-search queries to `ai-seo` and doesn't know `aeo` exists. Merge ai-seo's bot-access/robots.txt + content-pattern material into aeo references. +5. **Router drift.** marketing-ops claims to be the central router but its matrix omits 11 skills: aeo, app-store-optimization, brand-guidelines, marketing-demand-acquisition, marketing-strategy-pmm, prompt-engineer-toolkit, social-media-analyzer, webinar-marketing, x-twitter-growth, youtube-full (+ the marketing-skills index). +6. **Plugin hygiene.** marketing-skill/ root ships 5 .zip archives (~120 KB) and 4 internal planning docs (MARKETING-AUDIT-REPORT.md, -EXECUTION-PLAN.md, -EXPANSION-PLAN.md, marketing_skills_roadmap.md — 1,194 lines) inside the public plugin folder. +7. **Phantom references.** email-sequence and paid-ads link `../../tools/REGISTRY.md` and 5 `../../tools/integrations/*.md` guides; no `tools/` directory exists anywhere in marketing-skill/. +8. **Freshness is better than feared, with 3 specific stales:** Meta's 20%-image-text rule (retired 2021) in ad-creative SKILL + reference; GA4 "Conversions" (renamed "Key events" March 2024) in analytics-tracking; 2024/2025 dating in paid-ads naming examples and marketing-demand-acquisition metadata. x-twitter-growth explicitly labels its algorithm table "2025-2026" — the right pattern. +9. **New-gen model lens: the domain splits cleanly.** Skills that pair calibrated thresholds with deterministic scorers (aeo, campaign-analytics, ASO, churn-prevention, webinar funnel math, landing's validator gate) earn their context. ~8 skills are persona-prompt shells ("Core Principles → see references") whose body adds nothing a frontier model lacks — the value is locked in references the SKILL.md barely indexes. +10. **video-content-strategist plugin not registered.** It has `.claude-plugin/plugin.json` but no entry in root marketplace.json (E3). + +## Per-skill findings + +### ab-test-setup — OPTIMIZE +Issues: (1) `scripts/sample_size_calculator.py` orphaned — SKILL.md points users to external web calculators instead of its own tool; (2) sample-size quick table good but unverified against the script's output. +Verify: `python3 scripts/sample_size_calculator.py --help` exits 0; SKILL.md contains the literal string `sample_size_calculator.py` with an invocation; script output for baseline 5%/MDE 20% matches the table's ~7k/variant. + +### ad-creative — OPTIMIZE +Issues: (1) "Image text <20%" Meta rule stated in SKILL.md spec table and references/platform-specs.md as causing "reduced distribution" — Meta retired the enforcement in 2021; (2) `ad_copy_validator.py` wired but invocation lacks args/format. +Verify: `grep -c "20%" references/platform-specs.md` returns 0 (or the claim is rewritten as historical); `python3 scripts/ad_copy_validator.py --help` exits 0; SKILL.md shows an exact CLI line with input format. + +### ai-seo — CUT-OR-MERGE +Issues: (1) duplicates `aeo`'s mission with zero tooling (0 scripts vs aeo's 3); (2) router sends AI-search traffic here, starving aeo; (3) unique value (robots.txt bot matrix, 6 content patterns, GSC AI Overviews monitoring) belongs in aeo/references. +Verify: after merge, `marketing-ops/SKILL.md` routes "AI search/AEO/GEO" triggers to `aeo`; aeo references contain the bot-access table; `ai-seo/` directory removed or reduced to a redirect stub ≤ 30 lines. + +### analytics-tracking — OPTIMIZE +Issues: (1) "GA4 → Admin → Conversions" + "Max 30 conversion events" uses pre-2024 terminology (now Key events); (2) `tracking_plan_generator.py` only mentioned in passing in the artifacts table — no CLI invocation or output contract. +Verify: SKILL.md says "Key events"; SKILL.md contains `python3 scripts/tracking_plan_generator.py` with args; `python3 scripts/tracking_plan_generator.py --json` emits parseable JSON. + +### brand-guidelines — CUT-OR-MERGE +Issues: (1) 93 lines of generic audit checklist any frontier model reproduces unprompted (A5 fail); (2) "Anthropic Brand Identity" section hardcodes one company's identity into a generic skill; (3) no scripts, 1 reference; (4) overlaps marketing-context §10-11 (Brand Voice + Style Guide). +Verify: brand dimensions folded into marketing-context template (§10/§11 expanded); references/brand-identity-and-framework.md content preserved or moved; routing matrix no longer lists it OR skill rewritten with a deterministic brand-audit scorer. + +### competitor-alternatives — OPTIMIZE +Issues: (1) `comparison_matrix_builder.py` orphaned; (2) otherwise strong 4-format framework. +Verify: SKILL.md names `comparison_matrix_builder.py` with exact CLI + consuming step; script `--help` exits 0. + +### content-creator — CUT-OR-MERGE +Issues: (1) deprecated redirect skill still ships 4 references + 1 asset that the redirect never uses (A7); (2) `cs-content-creator` agent and `personas/content-strategist` still target it; (3) `content-creator.zip` lingers in plugin root; (4) routing duplicate of one row in marketing-ops. +Verify: references/ + assets/ removed (≤ 1 file redirect remains) or skill deleted with router rows updated; `grep -r "content-creator" agents/` returns no skill-target hits; zip deleted. + +### content-humanizer — OPTIMIZE +Issues: (1) 2/6 on repo's own checklist (261 lines, time-sensitive content flags); (2) the AI-tell vocabulary ("delve", "landscape", em-dash) is itself a 2023-24 snapshot — new-gen models have different tells, list needs dating + refresh cadence; (3) "HubSpot published... in 2023" dated example; (4) `humanizer_scorer.py` wired only in artifacts table, no CLI contract. +Verify: `skill_review_checklist_runner.py content-humanizer` ≥ 4/6; SKILL.md shows `python3 scripts/humanizer_scorer.py ` with score interpretation thresholds; references/ai-tells-checklist.md carries a "last validated" date. + +### content-production — OPTIMIZE +Issues: (1) `brand_voice_analyzer.py`, `content_quality_gates.py`, `seo_optimizer.py` all orphaned — only `content_scorer.py` is named; (2) marketing-skills index advertises these very scripts while the owning skill doesn't. +Verify: all 4 scripts named in SKILL.md with exact CLI; `python3 scripts/content_scorer.py --json` emits JSON with a 0-100 score; Mode 3 consumes brand_voice_analyzer + content_quality_gates outputs by name. + +### content-strategy — OPTIMIZE +Issues: (1) core knowledge deferred ("Searchable vs Shareable → see references") leaving a 127-line shell; (2) `topic_cluster_mapper.py` orphaned. +Verify: SKILL.md names `topic_cluster_mapper.py` with invocation; the searchable-vs-shareable decision rule (not just pointer) appears inline; script `--help` exits 0. + +### copy-editing — OPTIMIZE +Issues: (1) both scripts (`ai_content_detector.py`, `readability_scorer.py`) orphaned; (2) Seven Sweeps framework is genuinely good — wiring is the only gap. +Verify: each sweep that has a matching script names it (Sweep on AI patterns → ai_content_detector; clarity → readability_scorer); both `--help` exit 0; outputs consumed in the sweep workflow text. + +### copywriting — OPTIMIZE +Issues: (1) `headline_scorer.py` orphaned; (2) headline formula section never points at its own scorer. +Verify: SKILL.md "Above the Fold" section invokes `python3 scripts/headline_scorer.py ""`; script exits 0 with a numeric score. + +### email-sequence — OPTIMIZE +Issues: (1) phantom `../../tools/REGISTRY.md` + 5 `tools/integrations/*.md` links — directory doesn't exist; (2) `sequence_analyzer.py` orphaned; (3) core principles deferred to one reference, 135-line shell. +Verify: `grep -c "tools/REGISTRY" SKILL.md` returns 0; `sequence_analyzer.py` named with CLI; all relative links in SKILL.md resolve (`find` check). + +### form-cro — OPTIMIZE +Issues: (1) `form_field_analyzer.py` orphaned; (2) hollow core ("Core Principles → see references"). +Verify: script named with CLI and consumed in the audit output format; field-count/friction thresholds inline in SKILL.md (not only in playbook). + +### launch-strategy — OPTIMIZE +Issues: (1) 74 lines — everything substantive deferred to one reference; (2) `launch_readiness_scorer.py` orphaned; (3) thinnest non-deprecated skill in domain. +Verify: SKILL.md ≥ inline ORB definition + phase model summary; `launch_readiness_scorer.py` named with CLI; `--help` exits 0. + +### marketing-context — OPTIMIZE +Issues: (1) writes `.agents/marketing-context.md` while 19 sibling skills read `.claude/product-marketing-context.md` and 16 read `marketing-context.md` — the foundation file is invisible to half its consumers; (2) `context_validator.py` orphaned. +Verify: one canonical path declared and used by this skill's output instruction; `grep -rl "product-marketing-context" skills/*/SKILL.md` and `grep -rl "marketing-context.md"` agree with that path; `python3 scripts/context_validator.py --json` emits completeness score 0-100 and is named in SKILL.md. + +### marketing-demand-acquisition — OPTIMIZE +Issues: (1) `metadata.updated: 2025-01`, "q1-2025-linkedin-enterprise" examples; (2) description hard-scopes to "Series A+ scaling internationally EU/US/Canada hybrid PLG/Sales-Led" — over-narrow trigger for a general demand-gen skill; (3) HubSpot-specific workflows presented as the default stack. +Verify: dates refreshed or genericized; description triggers cover demand-gen broadly with the persona as a default profile not a gate; campaign workflow validation step still names the UTM-in-CRM check. + +### marketing-ops — OPTIMIZE +Issues: (1) routing matrix omits 11 skills (aeo, ASO, webinar-marketing, x-twitter-growth, social-media-analyzer, marketing-strategy-pmm, marketing-demand-acquisition, brand-guidelines, prompt-engineer-toolkit, youtube-full, video-content-strategist); (2) AI-search row routes to ai-seo only; (3) `campaign_tracker.py` orphaned. +Verify: `for d in skills/*/; do grep -q "$(basename $d)" marketing-ops/SKILL.md || echo MISS; done` prints nothing (minus deliberate exclusions); aeo present in SEO pod rows; `campaign_tracker.py` named with CLI. + +### marketing-skills — CUT-OR-MERGE +Issues: (1) it's a README/index in SKILL.md clothing — no workflow, no trigger utility; (2) stale counts (42 skills/7 pods/27 tools vs actual 47/8/58+); (3) every example path broken (omits `skills/` segment: `marketing-skill/content-production/scripts/...`); (4) references 6 scripts that live in other skills (phantom `scripts/*.py` paths); (5) duplicates marketing-ops (router) and README.md (index). +Verify: file demoted to README.md (or deleted) and removed from skill counts; if kept as SKILL.md, all paths resolve (`grep -oE "marketing-skill[^ )]*" | xargs -I{} test -e {}`) and counts match `ls skills/ | wc -l`. + +### onboarding-cro — OPTIMIZE +Issues: (1) `activation_funnel_analyzer.py` orphaned; (2) no references dir — all knowledge inline (acceptable) but no verification loop. +Verify: script named with CLI; `--help` exits 0; output (drop-off by step) consumed in the audit output format section. + +### page-cro — OPTIMIZE +Issues: (1) `conversion_audit.py` orphaned; (2) framework is solid but ends with no machine-checkable gate (A4). +Verify: SKILL.md invokes `python3 scripts/conversion_audit.py` and the audit report format references its score; `--help` exits 0. + +### paid-ads — OPTIMIZE +Issues: (1) phantom `../../tools/REGISTRY.md` reference; (2) `ad_health_scorer.py` + `roas_calculator.py` both orphaned; (3) naming-convention examples dated "2024Q1"/"Mar24"; (4) 5 refs exist but only 1 linked from SKILL.md. +Verify: zero phantom links; both scripts named with CLI; `python3 scripts/roas_calculator.py --help` exits 0; example campaign names use current-year placeholders or `{YYYY}` tokens. + +### popup-cro — OPTIMIZE +Issues: (1) hollow core ("Core Principles → see references/popup-cro-playbook.md"); (2) zero tooling; (3) experiment lists are the kind of generic ideation a frontier model produces unaided (A5 risk). +Verify: trigger-timing and frequency-cap thresholds (the calibrated part of the playbook) surfaced inline; SKILL.md ≤ 250 lines with decision rules, not idea lists. + +### programmatic-seo — OPTIMIZE +Issues: (1) `url_pattern_generator.py` orphaned; (2) otherwise strong (data-defensibility hierarchy, penalty avoidance). +Verify: script named with CLI in the page-generation workflow; `--help` exits 0. + +### prompt-engineer-toolkit — REWRITE +Issues: (1) references are stubs: evaluation-rubric.md 328 B, technique-guide.md 675 B, prompt-templates.md 1.5 KB — no citations, no marketing templates despite the description promising "prompt templates for marketing use cases (ad copy, email campaigns, social media)" (A1/A7 fail); (2) body is generic LLM-feature governance, not marketing — arguably belongs in engineering/; (3) scripts (`prompt_tester.py`, `prompt_versioner.py`) are real and wired — keep them. +Verify: each reference ≥ 3 KB with ≥ 5 cited sources OR skill relocated to engineering/ with description rewritten to match the body; prompt-templates.md contains ≥ 5 concrete marketing prompt templates if it stays in marketing; both scripts still pass `--help`. + +### seo-audit — OPTIMIZE +Issues: (1) both scripts (`seo_checker.py`, `seo_health_scorer.py`) orphaned; (2) audit framework wholly deferred ("→ See references/seo-audit-reference.md"); (3) 4 references are good (CWV thresholds, E-E-A-T) but SKILL.md gives the model no decision rules inline. +Verify: both scripts named with CLI and consumed in the report structure; CWV pass/fail thresholds (LCP/INP/CLS numbers) inline in SKILL.md; `--help` exits 0 on both. + +### signup-flow-cro — OPTIMIZE +Issues: (1) `funnel_drop_analyzer.py` orphaned. +Verify: script named with CLI; `--help` exits 0; output consumed in audit format. + +### social-media-manager — OPTIMIZE +Issues: (1) `social_calendar_generator.py` orphaned; (2) overlaps social-content's platform tables (duplicate cadence specs that can drift independently). +Verify: script named with CLI; cadence table either deduplicated with social-content or marked as the canonical copy; `--help` exits 0. + +### webinar-marketing — OPTIMIZE +Issues: (1) **confirmed known issue:** `scripts/webinar_funnel_scorer.py` has no argparse — `python3 ... --help` raises FileNotFoundError treating `--help` as a JSON filename (only D1 failure in marketing scope; it is the skill's only script, no affected siblings); (2) SKILL.md itself is among the best in the domain (backward funnel math, benchmark-tagged outputs) — fix is surgical. +Verify: `python3 scripts/webinar_funnel_scorer.py --help` exits 0 and prints usage; no-arg run still executes embedded sample and prints `WEBINAR FUNNEL SCORE: \d+/100` plus a JSON block; `echo '{}' | python3 scripts/webinar_funnel_scorer.py -` doesn't crash. + +## KEEP-verdict verification criteria + +- **aeo** — all 3 scripts pass `--help`; `aeo_audit.py --input --output json` emits composite 0-100 + 4 dimension keys; industry table thresholds (healthcare/finance/legal ≥ 85) unchanged. +- **app-store-optimization** — all 8 scripts pass `--help`; `metadata_optimizer.py --platform ios --title "<31 chars>"` flags the over-limit title; char-limit table matches Apple 30/30/100 + Play 50/80. +- **campaign-analytics** — 3 scripts run on `assets/sample_campaign_data.json` with `--format json` exit 0; attribution output includes all 5 models; funnel analyzer names a bottleneck stage. +- **churn-prevention** — `churn_impact_calculator.py` runs no-arg with sample, exits 0; benchmark table retains save-rate ≥ 10-15% / recovery 25-35% calibration. +- **cold-email** — 3 references resolve; deliverability section still names SPF/DKIM/DMARC + warmup ramp; orphan `email_sequence_analyzer.py` gets wired (carryover from A3 sweep). +- **free-tool-strategy** — `tool_idea_scorer`-class script passes `--help` and is named in Mode 1; 6-factor evaluation framework present. +- **marketing-ideas** — references/ideas-by-category.md contains all 139 numbered ideas; SKILL.md stage-mapping numbers (#79, #81...) resolve to entries in the reference. +- **marketing-psychology** — references/mental-models-catalog.md contains ≥ 70 models; the 6-category count table matches the catalog's actual counts. +- **marketing-strategy-pmm** — 4 references resolve; April Dunford positioning workflow + ICP validation checklist intact; no scripts claimed (none promised). +- **paywall-upgrade-cro** — self-contained; description's distinct-from-pricing-page boundary preserved; router row intact. +- **pricing-strategy** — `pricing_modeler.py` passes `--help` and stays named in SKILL.md; three-axes model + Van Westendorp trigger words remain in description. +- **referral-program** — incentive-structure script passes `--help` and is named; LTV-ceiling logic for incentive sizing intact. +- **schema-markup** — `schema_validator.py` named in Mode 1 step 1 and passes `--help`; schema selection table covers FAQ/HowTo/Article/Product/Organization/Person. +- **site-architecture** — `sitemap_analyzer.py` named in Mode 1 and passes `--help`; subfolder-over-subdomain rule intact. +- **social-content** — references/platforms.md + post-templates.md resolve; cadence table consistent with social-media-manager's (post-dedup). +- **social-media-analyzer** — both scripts pass `--help`; engagement-rate formula (engagements/reach×100) and validation gates (ER < 100%) intact. +- **x-twitter-growth** — all 5 scripts pass `--help` and stay named; algorithm-signal table keeps an explicit date label ("2025-2026" or refreshed); cadence-by-account-size table intact. +- **youtube-full** — BYOK note + OSS fallback table intact; fix 3 cross-reference paths (`marketing-skill/skills/video-content-strategist` → actual location); endpoint table matches credit-cost table. +- **video-content-strategist** — niche/positioning framework + 90-day plan intact; plugin gets registered in marketplace.json (currently missing). +- **landing (marketing/)** — 3 scripts pass `--help`; `html_validator.py --file .html` checks all 8 listed gates; GSAP CDN pins resolve; SKILL.md keeps gsap.set()-before-timeline FOUC rule. + +## Agents + +| Agent | Verdict | Notes | +|---|---|---| +| agents/marketing/cs-aeo.md | KEEP | B1-B3 pass; differentiated voice (refuses fake authority, AEO≠SEO routing); trigger phrasing present. | +| agents/marketing/cs-webinar-marketer.md | KEEP | Differentiated (refuses vanity metrics; fixes the broken stage); trigger phrasing present. | +| marketing/landing/agents/cs-landing.md | KEEP | Forcing-intake persona with concrete refusals; wired to skill + scripts. | +| agents/marketing/cs-content-creator.md | CUT-OR-MERGE | Targets the **deprecated** content-creator skill via a wrong path (`marketing-skill/content-creator`); no trigger phrasing (B1 fail); 3 paragraphs of swappable boilerplate (B2/B3 fail). Retarget to content-production or delete. | +| agents/marketing/cs-demand-gen-specialist.md | REWRITE | No trigger phrasing; wrong skill path (`marketing-skill/marketing-demand-acquisition`, missing `skills/`); body is the same boilerplate template as cs-content-creator — swappable (B2 fail). | +| agents/personas/content-strategist.md | OPTIMIZE | Skills list includes deprecated `content-creator`; otherwise differentiated persona frontmatter. | + +## Commands + +| Command | Verdict | Notes | +|---|---|---| +| commands/cs-aeo.md | KEEP | C1-C3 pass; orchestrates 3 scripts with modes; explicit when-NOT-to-run; distinct from /cs:seo-audit documented. | +| commands/cs-webinar.md | KEEP | C1-C3 pass; plan/rescue/evergreen modes; gates on funnel-math feasibility. | +| marketing/landing/commands/cs-landing.md | KEEP | C1-C3 pass; 4-question forcing intake + validator gate; routes away to landing-page-generator when conversion-optimized output needed. | +| commands/seo-auditor.md | KEEP | Repo-docs SEO utility (not marketing-skill plugin surface); 7-phase pipeline with report-only flag; does real orchestration. | + +Gap: no `/cs:*` commands exist for the other 45 marketing skills — the domain relies on skill triggers alone. Acceptable, but the marketing-skills index promises slash-command-grade entry points it doesn't have. + +## Plugin manifests + +| Manifest | Verdict | Notes | +|---|---|---| +| marketing-skill/.claude-plugin/plugin.json | OPTIMIZE | Schema valid (`"skills": ["./skills"]` ✓). E2 fail: description says "45 skills across 8 pods" — actual 47 skill dirs (incl. deprecated redirect + index); marketplace.json entry says 44/7; marketing-skills SKILL.md says 42/7. Three counts, four places. | +| marketing-skill/skills/aeo/.claude-plugin/plugin.json | KEEP | Schema valid; `source` extension block documented; description matches contents. | +| marketing-skill/skills/youtube-full/.claude-plugin/plugin.json | KEEP | Schema valid; attribution block present; BYOK disclosed (ClawHub rule 3 satisfied — free tier + OSS fallbacks documented). | +| marketing-skill/video-content-strategist/.claude-plugin/plugin.json | OPTIMIZE | Schema valid but **not registered in root marketplace.json** (E3 fail) — plugin is undiscoverable. | +| marketing/landing/.claude-plugin/plugin.json | OPTIMIZE | Schema valid; `source` block present. E2 drift: marketplace.json description for `landing` describes the *other* landing skill ("4 design styles, brand palette validation" = product-team TSX generator language), not this GSAP/HTML one. | + +Hygiene: marketing-skill/ plugin root ships 5 .zip archives and 4 internal planning markdown docs (1,194 lines) that don't belong in a distributed plugin. diff --git a/audit/newgen-2026-06/product-pm.md b/audit/newgen-2026-06/product-pm.md new file mode 100644 index 00000000..fca1fade --- /dev/null +++ b/audit/newgen-2026-06/product-pm.md @@ -0,0 +1,150 @@ +# Domain audit: product-team/ + project-management/ — new-gen model optimization +Audited: 2026-06-10 · Skills: 26 (17 product-team + 9 project-management) · Agents: 6 · Commands: 11 · Plugins: 6 (+1 .mcp.json) + +## Scorecard + +| Skill | Verdict | Top issue | +|---|---|---| +| product-team/skills/product-skills (router) | CUT-OR-MERGE | 61-line index with broken `/read` paths and stale counts; adds no orchestration | +| product-team/skills/product-manager-toolkit | OPTIMIZE | Two contradictory RICE CSV schemas in one file; ~120 lines of generic PM advice | +| product-team/agile-product-owner | KEEP | — | +| product-team/skills/product-strategist | OPTIMIZE | Generator emits canned OKR prose a frontier model writes better; keep the alignment scorer | +| product-team/skills/ux-researcher-designer | KEEP | — | +| product-team/skills/ui-design-system | KEEP | — | +| product-team/skills/competitive-teardown | OPTIMIZE | Its only script (competitive_matrix_builder.py) is never referenced in SKILL.md | +| product-team/skills/landing-page-generator | OPTIMIZE | Own script + all 4 references orphaned; overlaps marketing/landing | +| product-team/skills/saas-scaffolder | OPTIMIZE | project_bootstrapper.py orphaned; stack pins aging (Next.js 14, NextAuth v4) | +| product-team/skills/product-analytics | KEEP | — | +| product-team/skills/experiment-designer | KEEP | — | +| product-team/skills/product-discovery | KEEP | — | +| product-team/skills/roadmap-communicator | OPTIMIZE | Mostly framework-explainer prose; value is the changelog tool + templates | +| product-team/skills/spec-to-repo | KEEP | — | +| product-team/code-to-prd | OPTIMIZE | Malformed frontmatter (duplicate `Name:`/`name:` + non-standard keys) | +| product-team/research-summarizer | CUT-OR-MERGE | Duplicates research/ domain (litreview/dossier); phantom `/research:*` commands | +| product-team/apple-hig-expert | REWRITE | Known 3/6; persona filler, no exact CLI, citation-free references with dubious claims | +| project-management/skills/pm-skills (router) | CUT-OR-MERGE | Thin index; broken paths; says 6 skills, domain has 9 | +| project-management/skills/senior-pm | OPTIMIZE | Strong quant core buried in ~150 lines of governance boilerplate; invented KPI targets | +| project-management/skills/scrum-master | KEEP | — | +| project-management/skills/jira-expert | REWRITE | Fabricated MCP syntax (`mcp jira create_project --flags`) naming tools the bundled server doesn't have | +| project-management/skills/confluence-expert | REWRITE | Fabricated MCP tool names + phantom MACROS.md/PERMISSIONS.md + legacy wiki markup for Cloud | +| project-management/skills/atlassian-admin | OPTIMIZE | Factual errors (DELETE /rest/api/3/user ≠ deactivate; "7 years for GDPR"); script orphaned | +| project-management/skills/atlassian-templates | REWRITE | Claims "exact parameter names expected by the Atlassian MCP server" for tools that don't exist | +| project-management/skills/meeting-analyzer | KEEP | — | +| project-management/skills/team-communications | KEEP | — | + +**Totals:** KEEP 10 · OPTIMIZE 9 · REWRITE 4 · CUT-OR-MERGE 3 + +## Domain-level findings + +1. **MCP wiring is fiction in 3 of the 4 Atlassian skills (highest-severity finding).** The bundled `.mcp.json` correctly points to the Atlassian Remote MCP (`https://mcp.atlassian.com/v1/sse`, SSE), whose real tools are camelCase: `createJiraIssue`, `editJiraIssue`, `searchJiraIssuesUsingJql`, `transitionJiraIssue`, `createConfluencePage`, `updateConfluencePage`, `searchConfluenceUsingCql`, etc. The skills document three different *invented* conventions, none matching: jira-expert uses CLI-flag pseudo-syntax (`mcp jira create_project --name ... --type scrum`), confluence-expert uses snake_case JS calls (`create_space({...})`, `delete_page`, `add_label`), atlassian-templates uses JSON tool blocks (`confluence_create_page`, `jira_update_field_configuration`) while asserting these are "the exact parameter names expected by the Atlassian MCP server." Several referenced capabilities (`create_project`, `create_sprint`, `create_filter`, `create_space`, field-configuration editing) do not exist on the Remote MCP at all. `project-management/CLAUDE.md` adds a fourth convention (`mcp__atlassian__create_issue`, `mcp__atlassian__create_sprint`, `mcp__atlassian__link_issue`). A new-gen model following any of these will emit failing tool calls. +2. **8 orphaned scripts (A3 systemic).** Script dirs exist but SKILL.md never invokes them: competitive-teardown, landing-page-generator, saas-scaffolder, atlassian-admin (1 each); jira-expert, confluence-expert (2 each); atlassian-templates (1). The repo-wide smoke test passes them (D1 fine) but no workflow consumes their output — dead weight per the rubric. +3. **Stale path layout in agents, commands, and routers.** Skills moved under `*/skills/` subdirs but `agents/product/*` reference `../../product-team/product-manager-toolkit/`, commands reference `project-management/scrum-master/SKILL.md`, and both router skills instruct `/read product-team/product-manager-toolkit/SKILL.md`. All resolve to nothing. +4. **Count drift everywhere.** product-skills plugin.json: "13 production-ready product skills" then lists 16 names. product-skills SKILL.md: "10" in description, "8" in body, 13 on disk. pm-skills: 9 in marketplace, 6 in plugin description and SKILL.md, 9 on disk. project-management/CLAUDE.md claims 9 skills but documents only 6 — meeting-analyzer and team-communications (two of the three best skills in the domain) are invisible to it. +5. **PM references are citation-free**, consistent with the repo-wide flag: jql-examples.md (0 sources), team-dynamics-framework.md (0), governance-framework.md (0), template-design-patterns.md (0), retro-formats.md (1). Only senior-pm's prioritization/risk references cite anything. +6. **Generic-knowledge dead weight (A2).** "Handoff Protocols", "Best Practices", "Common Pitfalls" sections across senior-pm, jira-expert, confluence-expert, product-manager-toolkit, roadmap-communicator restate what a frontier model already knows. The skills that skip this (product-analytics, experiment-designer, meeting-analyzer, scrum-master) are the domain's best. + +## Per-skill findings + +### product-team/skills/product-skills — CUT-OR-MERGE +- Issues: (1) Pure index page — no routing logic, no classifier, nothing a model can execute. (2) Quick Start path `/read product-team/product-manager-toolkit/SKILL.md` is wrong (missing `skills/`). (3) Description says 10 skills, body table lists 8, directory holds 13. (4) Duplicates product-team/CLAUDE.md content. +- Verify: `grep -c "product-team/skills/" product-team/skills/product-skills/SKILL.md` ≥ 1 if retained; otherwise plugin.json `"skills"` array still validates via `python3 scripts/check_plugin_json.py --all` after removal. + +### product-team/skills/product-manager-toolkit — OPTIMIZE +- Issues: (1) Two incompatible RICE CSV schemas shown — Quick Start (`feature,reach,impact,confidence,effort` numeric) vs Tools Reference (`name,reach,impact,confidence,effort,description` with `high`/`massive`/`l` categorical values); only one can match the script's parser. (2) ~120 lines of generic PM advice (Best Practices, Pitfalls tables) a frontier model already knows. (3) Verification loop is checklist-only — no machine-checkable gate. +- Verify: `python3 scripts/rice_prioritizer.py sample && python3 scripts/rice_prioritizer.py sample_features.csv --output json` exits 0 and emits JSON with per-feature `rice_score`; the single canonical CSV header in SKILL.md matches `sample_features.csv` byte-for-byte; `python3 scripts/customer_interview_analyzer.py json` exits 0 emitting `pain_points` key. + +### product-team/skills/product-strategist — OPTIMIZE +- Issues: (1) Generator output is canned objective prose ("Build viral product features...") — new-gen models write better OKRs unaided; the durable value is the 4-score alignment math (vertical/horizontal/coverage/balance) and thresholds. (2) Sample output hardcodes "Q1 2025" (A6 minor). (3) No verification loop beyond a checklist. +- Verify: `python3 scripts/okr_cascade_generator.py growth --json | python3 -c "import json,sys; d=json.load(sys.stdin); assert d['alignment_scores']['overall']>0"` exits 0; thresholds table (>90/>75/>80/>80) still present in SKILL.md after trimming. + +### product-team/skills/competitive-teardown — OPTIMIZE +- Issues: (1) `scripts/competitive_matrix_builder.py` exists but is never mentioned — the 12-dimension rubric is manual-only. (2) Step 4 templates live in `references/analysis-templates.md`; the workflow never says when to load it vs the inline summary (mild progressive-disclosure confusion). (3) No final verification gate after step 6. +- Verify: `python3 scripts/competitive_matrix_builder.py --help` exits 0 AND SKILL.md contains an exact `python3 scripts/competitive_matrix_builder.py` invocation whose output feeds step 3 (scorecard); validation checkpoint at step 2 (pricing + ≥20 reviews + job counts) retained. + +### product-team/skills/landing-page-generator — OPTIMIZE +- Issues: (1) `scripts/landing_page_scaffolder.py` (the tool product-team/CLAUDE.md advertises for this skill) is never referenced — only marketing-skill's brand_voice_analyzer is. (2) All 4 reference files (conversion-patterns, copy-frameworks, landing-page-patterns, seo-checklist) unreferenced. (3) Functional overlap with `marketing/landing` (v2.7.0) — needs an explicit distinct-from note (TSX/Next.js vs single-file HTML). (4) SEO "validation step" is honor-system, no executable check. +- Verify: `python3 scripts/landing_page_scaffolder.py --help` exits 0 and SKILL.md shows `--format tsx|html` invocation consumed by the generation workflow; a "distinct from marketing/landing" sentence exists; all 4 reference files cited or deleted. + +### product-team/skills/saas-scaffolder — OPTIMIZE +- Issues: (1) `scripts/project_bootstrapper.py` orphaned — phase checklist never calls it. (2) Freshness: NextAuth v4 patterns (`NextAuthOptions`, `getServerSession`) and "Next.js 14+" pins will mislead in 2026 (Auth.js v5 / Next 15 era). (3) Reference Files section asks the model to *generate* CUSTOMIZATION.md/PITFALLS.md/BEST_PRACTICES.md rather than shipping them (A7 — shells). +- Verify: `python3 scripts/project_bootstrapper.py --help` exits 0 and is invoked in Phase 1 of the checklist; Phase 4 webhook idempotency validation retained; stack-version claims dated or generalized. + +### product-team/skills/roadmap-communicator — OPTIMIZE +- Issues: (1) ~70% of body is audience-framing advice a frontier model knows (board = outcomes, engineers = dependencies). (2) Only real asset is `changelog_generator.py` + two template references; quality checklist is non-executable. (3) No JSON-mode mention despite the script supporting `--json` (per CLAUDE.md). +- Verify: from a git repo, `python3 scripts/changelog_generator.py --from --to HEAD --json` exits 0 emitting grouped conventional-commit entries; both `references/roadmap-templates.md` and `references/communication-templates.md` load (exist, non-empty). + +### product-team/code-to-prd — OPTIMIZE +- Issues: (1) Frontmatter contains duplicate keys (`Name:` and `name:`) plus non-standard `Tier/Category/Dependencies/Author/Version` at top level — fragile under strict YAML parsers and fails the repo's own description conventions. (2) 507 lines; the README/per-page templates could move to `references/` (progressive disclosure). (3) Otherwise the strongest large skill in the domain (mock-detection signals, enum exhaustiveness, [TBC] uncertainty rule). +- Verify: `python3 -c "import yaml; yaml.safe_load(open('SKILL.md').read().split('---')[1])"` parses with exactly one `name` key; `python3 scripts/codebase_analyzer.py -o analysis.json && python3 scripts/prd_scaffolder.py analysis.json -o /tmp/prd` exits 0 producing `prd/README.md`. + +### product-team/research-summarizer — CUT-OR-MERGE +- Issues: (1) Core capability (structured summarization) is native frontier-model behavior; wrapper value is one regex citation extractor. (2) Direct overlap with `research/litreview`, `research/dossier`, `research/notebooklm` (v2.7.0) — no disambiguation anywhere. (3) Advertises `/research:summarize|compare|cite` slash commands that exist nowhere in `commands/` (phantom). (4) `format_summary.py` emits empty templates — a template printer, not analysis. (5) Installation section references `./scripts/convert.sh` not shipped with the skill. +- Verify: if retained, `grep -r "research:summarize" commands/` returns ≥1 file or the Slash Commands section is removed; a "distinct from research/litreview" note exists; `python3 scripts/extract_citations.py --output json` exits 0 with deduplicated entries. + +### product-team/apple-hig-expert — REWRITE +- Issues: (1) Confirmed 3/6 on repo checklist: description has no "Use when" trigger phrases; "You are a Senior Apple Design Lead with decades of experience" is exactly the A2 filler the rubric bans; zero concrete examples (no sample audit, no before/after). (2) A3 fail: "Run the `hig_checker.py` tool" with no invocation — actual CLI is `hig_checker.py {contrast,target,batch}` with subcommand args the SKILL.md never shows. (3) References cite zero sources (no developer.apple.com links) and contain unverifiable claims ("SF Camera" as a public SF variant; "Liquid Glass introduced in late 2025" — WWDC25 was June 2025) — for a freshness-critical Apple skill this is fatal. (4) 90 lines of pointers with the actual expertise missing: no Liquid Glass API names (`glassEffect`, materials hierarchy), no per-platform metric tables in SKILL.md. (5) Scorecard "0-100" output promised with no rubric to compute it. +- Verify: `python3 scripts/hig_checker.py contrast --help && python3 scripts/hig_checker.py batch --help` exit 0 and both invocations appear verbatim in SKILL.md; description matches `Use when` trigger regex of `scripts/audit_skills.py` (skill scores ≥5/6 on `skill_review_checklist_runner.py`); every reference doc cites ≥3 developer.apple.com URLs; at least one worked audit example (input mockup description → scored findings) present. + +### project-management/skills/pm-skills — CUT-OR-MERGE +- Issues: (1) Index-only router; `/read project-management/jira-expert/SKILL.md` path wrong (missing `skills/`). (2) Claims 6 skills; domain ships 9 — meeting-analyzer, team-communications invisible. (3) Example tool paths (`senior-pm/scripts/...`) also missing the `skills/` segment. +- Verify: every path in the file resolves (`while read p; do test -e "$p"; done`) or the file is removed and pm-skills plugin.json still passes `check_plugin_json.py --all`. + +### project-management/skills/senior-pm — OPTIMIZE +- Issues: (1) ~150 lines of Handoff Protocols / Continuous Improvement / Stakeholder Feedback boilerplate (A2 dead weight). (2) Success-metric targets (">70% risk prediction accuracy", "10% transformational") presented with no source or basis (A5 weakness). (3) Description promises "Monte Carlo simulation" — confirm `risk_matrix_analyzer.py` actually simulates rather than just the formula snippets shown. (4) Quant core (EMV, category weights, three-point estimation, response thresholds >18/12-18/8-12/<8, STOP gates) is genuinely good — keep all of it. +- Verify: all three scripts run against `assets/sample_project_data.json` exiting 0; `project_health_dashboard.py ... --format json` emits composite score + RAG consistent with the >80/60-80/<60 thresholds documented; if Monte Carlo isn't in the scripts, the claim is removed from the description. + +### project-management/skills/jira-expert — REWRITE +- Issues: (1) Every "MCP" example uses invented CLI syntax (`mcp jira create_project --name "My Project" --type scrum`) — not MCP, not the bundled server. Real server: `createJiraIssue`, `searchJiraIssuesUsingJql`, `editJiraIssue`, `transitionJiraIssue`; it has NO project/sprint/filter creation. (2) Both scripts (`jql_query_builder.py`, `workflow_validator.py` — which work and produce useful JQL) are never mentioned. (3) `--startDate "2024-06-01"` 2024-ism (A6). (4) JQL operator/function content is generic knowledge a frontier model has; the JQL examples references cite 0 sources. (5) Verdict REWRITE not CUT: the JQL recipes + escalation framework + the two scripts are a salvageable core. +- Verify: every MCP call in SKILL.md names a tool that exists on the Atlassian Remote MCP (assert each appears in the server's tool list; non-existent operations rewritten as REST-API or UI steps); `python3 scripts/jql_query_builder.py "high priority bugs assigned to me"` exits 0 emitting valid JQL and is wired into the JQL workflow; no pre-2026 literal dates. + +### project-management/skills/confluence-expert — REWRITE +- Issues: (1) MCP examples (`create_space`, `update_page`, `delete_page`, `get_children`, `add_label`) don't match the real server (`createConfluencePage`, `updateConfluencePage`, `getConfluencePage`, `getConfluencePageDescendants`, `searchConfluenceUsingCql`; no space-creation/delete/label tools). (2) Phantom references: cites `MACROS.md`, `TEMPLATES.md`, `PERMISSIONS.md` — actual files are `macro-cheat-sheet.md`, `templates.md`, `space-architecture-patterns.md`; PERMISSIONS.md doesn't exist at all. (3) Macro sections teach legacy wiki markup (`{info}`, `{section}{column}`) which Confluence Cloud pages (what the MCP writes, storage-format XHTML/ADF) won't accept. (4) Scripts (`space_structure_generator.py`, `content_audit_analyzer.py`) orphaned. (5) Long generic sections (governance, handoffs) a model already knows. +- Verify: every file path cited in SKILL.md exists (`grep -oE '[A-Za-z-]+\.md' SKILL.md` all resolve under references/); every MCP example names a real Remote-MCP tool; macro examples shown in storage format with a note on wiki-markup legacy; both scripts invoked with exact CLI and outputs consumed by Space Creation / KB audit workflows. + +### project-management/skills/atlassian-admin — OPTIMIZE +- Issues: (1) Factual errors: `DELETE /rest/api/3/user` deletes (org-admin deactivation is a different endpoint) yet documented as "Deactivate"; "minimum 7 years for SOC 2/GDPR compliance" is invented — GDPR mandates no such retention and pushes minimization. (2) `permission_audit_tool.py` orphaned. (3) Strength: admin.atlassian.com click-paths and REST endpoints are real specificity (A5 pass) — admin operations aren't covered by the Remote MCP, so the "Atlassian MCP Integration" closing section over-promises and should be cut or scoped. (4) References dir exists but is never pointed to from the workflows. +- Verify: `python3 scripts/permission_audit_tool.py --help` exits 0 and an exact invocation appears in the Permission Scheme Design workflow; deactivation step cites the org API (`POST /admin/v1/orgs/{orgId}/directory/users/{accountId}/suspend-access`) or the console path only; retention claim sourced or deleted. + +### project-management/skills/atlassian-templates — REWRITE +- Issues: (1) States "All MCP calls below use the exact parameter names expected by the Atlassian MCP server" — then lists `confluence_create_page`, `confluence_update_page`, `confluence_get_page`, `jira_update_field_configuration`, none of which exist (real: `createConfluencePage`/`updateConfluencePage`/`getConfluencePage`; no field-configuration tool at all). False precision is worse than vagueness. (2) Phantom references: `TEMPLATES.md` and `HANDOFFS.md` cited; actual files are `governance-framework.md`, `template-design-patterns.md`. (3) Conflates "Confluence storage format (wiki markup)" — storage format is XHTML, wiki markup is a different legacy syntax; the example is wiki markup and will not round-trip through the Cloud API. (4) `template_scaffolder.py` (which generates storage-format XHTML per CLAUDE.md — the actually-correct artifact) is never mentioned. +- Verify: `python3 scripts/template_scaffolder.py meeting-notes` exits 0 emitting storage-format XHTML and is the documented deployment path; every MCP tool named in SKILL.md exists on the Remote MCP; cited reference filenames resolve on disk; "storage format" vs "wiki markup" used correctly throughout. + +## KEEP-verdict verification criteria + +- **agile-product-owner**: AC-count-by-points table (1-2→3-4 … 13+→split) and availability-factor table intact; `python3 scripts/user_story_generator.py sprint 30` exits 0 emitting committed ≤85% of capacity; weighted prioritization (40/30/15/15) unchanged. +- **ux-researcher-designer**: `python3 scripts/persona_generator.py json` exits 0 with `confidence` field; sample-size confidence table (5-10 low / 11-30 med / 31+ high) and severity 1-4 table retained. +- **ui-design-system**: `python3 scripts/design_token_generator.py "#0066CC" modern json` exits 0 emitting color/typography/spacing token groups; WCAG AA thresholds (4.5:1 / 3:1) stated in Workflow 1 step 5. +- **product-analytics**: all three subcommands (`retention`, `cohort`, `funnel`) run against documented CSV headers with `--format json` exiting 0; anti-pattern table (6 rows) retained. +- **experiment-designer**: `python3 scripts/sample_size_calculator.py --baseline-rate 0.12 --mde 0.02 --mde-type absolute` exits 0 printing `n_per_group`/`n_total`; If/Then/Because hypothesis gate and peeking warning retained. +- **product-discovery**: `python3 scripts/assumption_mapper.py ` exits 0 emitting prioritized test plan; OST quality gates (≥3 opportunities, ≥2 experiments/opportunity) retained. +- **spec-to-repo**: `python3 scripts/validate_project.py --format json` exits 0; Phase 4 checklist wired to the script; anti-pattern table (9 rows incl. phantom-imports) retained. +- **scrum-master**: all 3 scripts run on `assets/sample_sprint_data.json` matching `assets/expected_output.json` anchors (velocity avg ≈20.2, CV ≈12.7%, health ≈78.3); <3-sprint refusal gate fires on truncated input. +- **meeting-analyzer**: calibrated thresholds preserved (filler >3/100 words, speaking share >60%, interruption >2:1, 3+ meetings for trends); no script claims introduced without scripts existing. +- **team-communications**: all 4 routing targets (`references/3p-updates.md` etc.) exist and load; ambiguity rule ("ask one clarifying question") retained. + +## Agents + +6 agents (5 product + 1 PM), all `model: sonnet`, all `tools: [Read, Write, Bash, Grep, Glob]`. + +- **B1 partial fail (all 6):** descriptions state capability but no trigger phrasing ("Use when…" / "Use PROACTIVELY") — they read like catalog blurbs. +- **Stale skill paths (all 6):** `skills:` values and body paths (`../../product-team/product-manager-toolkit/`, `../../project-management/senior-pm/scripts/...`) predate the `skills/` subdirectory move; none resolve. cs-project-manager's `skills: project-management` is the only one that survives by accident (directory-level). +- **B2 weak:** cs-product-manager orchestrates all 8 legacy skills (incl. landing-page + saas-scaffolder — scope sprawl into build work); cs-product-strategist and cs-product-manager bodies are interchangeable catalog tables, not differentiated behavior. cs-product-analyst is the cleanest (2 skills, focused). +- Verify: every path in each agent file resolves from `agents//`; each description gains a trigger clause; cs-product-manager skill list trimmed to PM-decision skills. + +## Commands + +11 in scope: /rice, /okr, /persona, /user-story, /competitive-matrix, /prd, /sprint-plan, /code-to-prd (product); /sprint-health, /project-health, /retro (PM). + +- **C1 pass** all 11 (frontmatter description present, usage string embedded). +- **C3 strong:** /sprint-health, /project-health, /retro, /code-to-prd — wire exact scripts with input schemas and JSON examples. Keep. +- **C3 weak:** /prd and /sprint-plan are thin prompt wrappers (output-structure bullets a bare prompt produces) — merge candidates into /rice and /user-story or beef up with script gates. +- **Stale skill-reference paths (all that cite SKILL.md):** `project-management/scrum-master/SKILL.md`, `product-team/product-manager-toolkit/SKILL.md` etc. all miss the `skills/` segment. +- **Mismatch:** /retro and /sprint-health input JSON schemas (flat per-sprint objects) don't match the scripts' actual schema (`team_info` + `sprints[]` + `retrospectives[]` per scrum-master SKILL.md) — a model following the command's example will feed the script malformed input. Verify: run each command's documented example JSON through its script; exit 0 required. + +## Plugin manifests + MCP wiring + +- **E1 pass:** all 6 plugin.json files schema-valid (`"skills": ["./skills"]` / `["./skills"]` canonical forms); repo-wide `check_plugin_json.py --all` green. +- **E2 fail — count/description drift:** product-skills plugin.json says "13 production-ready product skills" then enumerates 16 (incl. code-to-prd, research-summarizer, apple-hig-expert, spec-to-repo — three of which are *separate* plugins, so the description oversells what `./skills` ships). pm-skills plugin description lists 6 skills; marketplace.json says 9; disk has 9 (meeting-analyzer + team-communications + router undocumented). product-team/CLAUDE.md header says 13, lists 16, footer says "13/13". project-management/CLAUDE.md says 9, documents 6. +- **E3 pass:** all at 2.9.0, coherent with marketplace.json. +- **.mcp.json:** correct and minimal (`atlassian` → SSE `https://mcp.atlassian.com/v1/sse`). This is the only accurate piece of MCP wiring in the domain. +- **MCP documentation contradiction (cross-cutting):** four different fabricated tool-naming conventions across project-management/CLAUDE.md (`mcp__atlassian__create_issue`, `create_sprint`, `link_issue`), jira-expert (CLI flags), confluence-expert (snake_case JS), atlassian-templates (JSON blocks) — zero match the live Remote MCP surface (`createJiraIssue`, `editJiraIssue`, `searchJiraIssuesUsingJql`, `getJiraIssue`, `transitionJiraIssue`, `createConfluencePage`, `updateConfluencePage`, `getConfluencePage`, `searchConfluenceUsingCql`, `getConfluenceSpaces`, …). One canonical tool-name appendix should be written once and referenced from all four places. Verify: `grep -rE "mcp jira |mcp__atlassian__[a-z_]+|confluence_create_page|create_space\(" project-management/` returns 0 hits after fix. diff --git a/audit/newgen-2026-06/productivity-markdown-html.md b/audit/newgen-2026-06/productivity-markdown-html.md new file mode 100644 index 00000000..feed5c2b --- /dev/null +++ b/audit/newgen-2026-06/productivity-markdown-html.md @@ -0,0 +1,131 @@ +# Domain audit: productivity/ + markdown-html/ — new-gen model optimization +Audited: 2026-06-10 · Skills: 11 · Agents: 7 · Commands: 14 · Plugins: 6 · Hooks: 2 + +## Scorecard +| Skill | Verdict | Top issue | +|---|---|---| +| markdown-html-orchestrator | OPTIMIZE | Stale v2.10.0 "foundation status" text instructs the model NOT to use the (now-shipped) converters | +| design-system | KEEP | Validator script exits 0 even on FAIL verdict (refusal lives in onboard.py — documented, but easy to misread) | +| md-document | KEEP | <100-line "hard rule" is prose/command-enforced, not script-enforced (parser accepted a 70-line file) | +| md-review | KEEP | — | +| md-slides | KEEP | Boundary-less 1-slide file exits 6 (no-boundary), not 5 (poster) — doc nuance | +| capture | KEEP | dump_classifier CLI shape (positional arg) not documented in SKILL.md tooling table | +| inbox-setup | KEEP | — (its agent has a phantom skills path; see Agents) | +| inbox-triage | KEEP | — (same agent issue) | +| reflect | OPTIMIZE | 3 scripts are unwired — no CLI invocations in SKILL.md, no step consumes their output | +| handoff | KEEP | "17 regex patterns" claim is actually 16; tools table lacks exact CLI invocations | +| andreessen | KEEP | — | + +Verdicts: 9 KEEP · 2 OPTIMIZE · 0 REWRITE · 0 CUT-OR-MERGE + +## Empirical verification results + +All runs used `MARKDOWN_HTML_NO_CONFIG=1` or an isolated `HOME` to avoid touching real config. Scratch: /tmp/audit-pmh. + +| # | Check | Expected | Actual | Result | +|---|---|---|---|---| +| 1 | md-document pipeline (parser → renderer → injector) on 515-line repo CLAUDE.md | valid single-file HTML | 88 KB HTML, parses clean, 16 sections, all 4 JS features injected (+5,081 B) | PASS | +| 2 | Output single-file discipline | only Google Fonts + Prism externals | external hosts: `fonts.googleapis.com`, `cdn.jsdelivr.net` (+ content links) | PASS | +| 3 | interactivity_injector idempotency | re-inject is no-op | "no-op: marker … already present", exit 0 | PASS | +| 4 | md-document <100-line refusal at script level | refuse per SKILL.md hard rule #1 | parser/renderer accepted a 70-line file (gate lives in orchestrator `route_explainer.py` + command prose `wc -l`) | PARTIAL — claim overstates script behavior | +| 5 | slide_splitter 1-slide deck → exit 5 | exit 5 | exit 5 (with `--boundary h1` single-H1, and 3-HR degenerate deck) | PASS | +| 6 | slide_splitter no-boundary → exit 6 | exit 6 | exit 6 on 120-line prose file (also on plain 1-slide file — exit 6 fires before exit 5 when no boundaries detected) | PASS | +| 7 | md-slides happy path (5 slides, 3 with notes) | working deck | 10.8 KB single-file HTML, 5 `
`, keydown handlers, 1 `@media print`, 60% notes coverage reported | PASS | +| 8 | md-review diff_parser on real ```diff block | hunks JSON | 1 file / 1 hunk parsed; extractor found 2 annotations (1 BLOCKER, 1 NIT) | PASS | +| 9 | review_html_renderer without `--reviewer` → exit 3 | exit 3 | exit 3, "A code review must name a human reviewer" | PASS | +| 10 | review_html_renderer with 0 hunks → exit 4 | exit 4 | exit 4, "route to md-document instead" | PASS | +| 11 | LGTM approval capture | approvals counted | standalone `LGTM` line → 1 approval (regex requires standalone line; "LGTM otherwise." is not counted — by design) | PASS | +| 12 | brand_palette_validator refuses AA-failing palette | FAIL verdict | `--text #CCCCCC --bg #FFFFFF` → FAIL 1.61:1; but script exit 0 (verdict-only); save refusal is onboard.py | PASS (with caveat) | +| 13 | onboard.py exit 4 on AA-fail save | exit 4 | exit 4, "refusing to save: WCAG AA contrast failed" | PASS | +| 14 | onboard.py exit 3 on empty/unwritable output dir | exit 3 | exit 3 on empty path (unwritable case untestable as root — `os.access` always true; code path present at line 226) | PASS | +| 15 | orchestrator <100-line refusal | REFUSE | exit 3, Shihipar citation, design-system status surfaced | PASS | +| 16 | orchestrator silent-route on review doc | ROUTE_SILENTLY → md-review | score 13 vs runner-up 1, routed silently | PASS | +| 17 | orchestrator ambiguity → ASK_USER | one question | CLAUDE.md scored slides 18 / document 15 → ASK_USER with recommended answer (correct: CLAUDE.md is full of `---` HRs) | PASS | +| 18 | handoff redaction_linter on fake AWS key (strict) | exit 1, block | exit 1, `[high] aws_access_key`, fix suggestion + whitelist tip | PASS | +| 19 | redaction_linter whitelist `` | exit 0 | exit 0, "OK: no findings" | PASS | +| 20 | "17 patterns" claim | 17 Pattern() defs | **16** Pattern() defs (aws×2, github, openai, anthropic, slack, google, stripe, private-key, jwt, env-assign, db-conn, bearer, email, phone, url-token) | FAIL (off-by-one in docs) | +| 21 | handoff hooks | stdin-safe, env-disable | SessionStart: exit 0 disabled + exit 0 no-handoff; SessionEnd prints reminder, exit 0; hooks.json wires both via `${CLAUDE_PLUGIN_ROOT}` | PASS | +| 22 | andreessen market_first_evaluator --sample | verdict + weights | BUILD-POUR-FUEL, market weighted 0.55 (contribution 4.4) | PASS | +| 23 | andreessen kill gate: market 3.0, team/product 10 | KILL despite 6.15 composite | KILL-OR-REPICK-MARKET + explicit "trap" note that team/product cannot override sub-4 market | PASS | +| 24 | anti_todo_card 6th must-do | reject | exit 2, "the cap IS the discipline" | PASS | +| 25 | operating prompt operationalized | posture table | references/operating_prompt.md: verbatim prompt + 6-row instruction→behavior mapping + binding confidence-level discipline + "what this is NOT" | PASS | +| 26 | inbox-triage draft_safety_validator | exit 1 on send-shaped call | `--sample-fail` exit 1 / `--sample-pass` exit 0 | PASS | +| 27 | all 22 productivity scripts `--help` | exit 0 | 22/22 exit 0 | PASS | + +Tally: **24 PASS · 1 PARTIAL · 1 FAIL** (plus 1 caveat). The domains' empirical claims are overwhelmingly real. + +## Domain-level findings + +1. **Staleness cascade in markdown-html/ (the one real defect).** The domain shipped complete at v2.10.3, but three files still describe the v2.10.0 foundation: `markdown-html/CLAUDE.md` (skills table marks md-document/review/slides "v2.10.1"), `markdown-html/README.md` ("Status — v2.10.0 (foundation)", converters "v2.10.1 (next PR)"), and the orchestrator SKILL.md ("Until v2.10.1, the orchestrator's job stops at step 4 — … lets Claude do the rendering inline"). A new-gen model following the orchestrator SKILL.md today is **instructed to bypass the shipped converters** and hand-render. This is an A6 failure with behavioral consequence, not cosmetic. +2. **Refusal gates split between scripts and prose — mostly fine, but SKILL.md wording overclaims twice.** md-document's "Hard rule 1: Refuses input < 100 lines" and design-system's validator both read as script-level gates; in reality the 100-line gate lives in the orchestrator's `route_explainer.py` and in the converter commands' `wc -l` instruction, and the palette refusal lives in `onboard.py` (validator exits 0 on FAIL verdict). Direct script invocation skips both. Acceptable for a model that follows the commands, but the prose should say where each gate is enforced. +3. **A3 weakness across productivity/: tool tables without exact CLI invocations.** reflect, handoff, and capture (dump_classifier) list scripts in a table but never show how to call them — I had to discover arg shapes by trial (`redaction_linter.py FILE` positional, not `--file`; `bias_pattern_detector.py --conversation`). markdown-html/ does this right (every SKILL.md has copy-pasteable invocations); productivity/ should match. +4. **Counter/spec drift.** Redaction patterns 16 vs claimed 17 (root CLAUDE.md v2.8.2 notes). reflect's spec is `megaprompts/02-reflect-megaprompt.md` per SKILL.md + plugin.json, but root CLAUDE.md v2.7.0 notes call reflect "megaprompt 08". Minor, but counters are this repo's brand — keep them true. +5. **Trigger quality is uniformly strong (A1).** Every skill in scope has concrete trigger phrases, third-person descriptions, refusal conditions in the description itself, and "distinct from" disambiguation. This is the best trigger discipline of any domain pattern observed; no action needed. +6. **Context economy is good but markdown-html SKILL.md bodies duplicate the domain CLAUDE.md hard rules ~3×** (domain CLAUDE.md, SKILL.md "Hard rules", command "Pre-flight gates"). Tolerable since skills ship standalone, but the duplication is what made the staleness cascade possible — single-source the version/status table. + +## Per-skill findings + +### markdown-html-orchestrator — OPTIMIZE +- **Verdict:** OPTIMIZE (targeted edits; routing logic and scripts are excellent and fully verified) +- **Issues:** + 1. SKILL.md "Foundation status (v2.10.0)" paragraph + Step 5 ("Until v2.10.1 … lets Claude do the rendering inline") + Output-artifacts table ("v2.10.1" status column) instruct the model to bypass shipped converters. Delete the transitional text. + 2. Frontmatter `version: 2.10.0` while plugin is 2.10.3. + 3. `markdown-html/CLAUDE.md` skills table and `README.md` status section carry the same stale v2.10.0 framing (fix together). + 4. Pipeline snippets use `skills/markdown-html-orchestrator/...` relative paths while Step-1 uses repo-rooted `markdown-html/skills/...` — pick one convention. +- **Verify:** + - `grep -c "v2.10.1" markdown-html/skills/markdown-html-orchestrator/SKILL.md` returns 0 + - `grep -c "foundation" markdown-html/README.md markdown-html/CLAUDE.md` returns 0 stale-status hits (status table lists all 5 skills "✓ live") + - `printf '# s\n' > /tmp/s.md && python3 markdown-html/skills/markdown-html-orchestrator/scripts/doctype_classifier.py --input /tmp/s.md --output json | python3 .../route_explainer.py; test $? -eq 3` (refusal stays green) + - review-shaped ≥100-line input still yields `ROUTE_SILENTLY -> md-review` + +### reflect — OPTIMIZE +- **Verdict:** OPTIMIZE (the prompt body is strong; the script layer is dead weight as wired) +- **Issues:** + 1. A3: no CLI invocations anywhere in SKILL.md for the 3 scripts; no workflow step consumes their output. For an in-conversation reflection skill the model cannot trivially produce a transcript file, so `bias_pattern_detector.py --conversation FILE` and `conversation_depth_analyzer.py` have no realistic input path described. + 2. A4: `directional_recommendation_validator.py` is the natural verification loop (assert output ends Continue/Pivot/Pause) but is never invoked in the workflow. Wire it: "pipe your draft reflection through the validator before sending; exit 0 required." + 3. Either wire all 3 scripts with exact invocations + an input-capture step, or cut detector/analyzer and keep only the validator (A7). +- **Verify:** + - SKILL.md "Tooling" section contains ≥1 fenced `python3 …` invocation per retained script + - `printf 'analysis...\nContinue. Because X and Y are verified.\n' | python3 productivity/reflect/skills/reflect/scripts/directional_recommendation_validator.py -` (or documented file form) exits 0; output missing a closing recommendation exits non-zero + - `python3 .../bias_pattern_detector.py --sample --output json` exits 0 with keys `biases_detected`, `biases_clear`, `details` (if retained) + +## KEEP-verdict verification criteria + +- **design-system:** `HOME=$(mktemp -d) python3 markdown-html/skills/design-system/scripts/onboard.py --defaults` exits 0; `--set brand.text='#CCCCCC' --set brand.bg='#FFFFFF'` exits 4; `--set default_output_dir=` exits 3; `config_loader.py --status` reports `setup_completed: true` after defaults. +- **md-document:** full 3-script pipeline on a ≥100-line file exits 0×3 and produces HTML whose only external hosts are `fonts.googleapis.com` + `cdn.jsdelivr.net`; second injector run prints `no-op` and exits 0. (Optimization PRs must also fix Hard-rule-1 wording to name where the 100-line gate is enforced.) +- **md-review:** renderer without `--reviewer` exits 3; with 0-hunk input exits 4; with valid input exits 0 and output contains the reviewer name + per-severity counts; standalone `LGTM` line yields `approvals: 1`. +- **md-slides:** `slide_splitter.py` exits 5 on a boundary-detected 1-slide deck, 6 on boundary-less input, 0 on a 5-slide HR deck; rendered deck contains 5 `class="slide"` sections, `addEventListener`, and `@media print`. +- **capture:** `dump_classifier.py ` and `--sample` exit 0; `workspace_inventory.py --root . --keywords "a,b"` exits 0 (documented invocation stays true); `complexity_estimator.py --sample small` recommends compressed format. +- **inbox-setup:** `kb_validator.py --sample` exits 0 with verdict PASS and 7-file contract checks; SKILL.md section count stays 8 with S4 skip-logic intact. +- **inbox-triage:** `draft_safety_validator.py --sample-fail` exits 1, `--sample-pass` exits 0; SKILL.md states DRAFTS-ONLY in ≥3 places; `search_window_calculator.py --help` exits 0. +- **handoff:** `redaction_linter.py ` exits 1 strict / 0 with ``; `echo '{}' | HANDOFF_SESSIONSTART=0 python3 hooks/session_start.py` exits 0; `handoff_self_check.py --sample` exits 0; fix the "17 patterns" claim to 16 (or add the 17th) wherever it appears. +- **andreessen:** `market_first_evaluator.py --size 3 --growth 3 --timing 3 --pull 3 --team 10 --product 10` verdict is KILL-OR-REPICK-MARKET; `anti_todo_card.py --new --must-do a b c d e f` exits 2; `references/operating_prompt.md` retains the verbatim prompt + 6-row posture table. + +## Agents + +7 agents. One real bug, otherwise differentiated and non-boilerplate (B2/B3 pass — capture's 210-line persona, inbox pair's halting rules, and andreessen's binding voice could not be swapped unnoticed). + +- **BUG — `cs-inbox-setup.md` and `cs-inbox-triage.md` declare `skills: engineering/email/skills/inbox-setup` / `...inbox-triage`. The skills live at `productivity/email/skills/...`; `engineering/email/` does not exist.** Phantom path (B1). Fix: `skills: productivity/email/skills/inbox-setup` (resp. `-triage`). +- B1 trigger phrasing: only `cs-handoff-author` uses explicit "Invoke when…" language. The other six describe the persona but not when to fire; cheap win to prepend "Use when…" to each description. +- `cs-markdown-html-orchestrator` (model: sonnet) carries the same stale assumption indirectly via the skill it wraps — no edit needed once the SKILL.md is fixed. +- Frontmatter style is inconsistent across the set (`tools: [..]` vs `tools: "..."` vs quoted lists; `model: opus`/`sonnet`/`inherit`) — harmless but worth normalizing in an optimization PR. + +## Commands + +14 commands. All have accurate descriptions (C1). All orchestrate tools or enforce gates a bare prompt would not (C3): the six markdown-html commands embed pre-flight refusal gates + exact pipelines; `/cs:handoff` enforces checklist→linter→save ordering; `/cs:inbox-*` enforce the one-question-per-turn and DRAFTS-ONLY disciplines; `/cs:andreessen` + `/cs:pmf-check` bind verdict tools. + +- C2: markdown-html commands + handoff pair carry `argument-hint`; the 6 productivity megaprompt-era commands (andreessen, pmf-check, capture, inbox-setup, inbox-triage, reflect) embed usage in the body instead of `argument-hint` frontmatter — minor normalization. +- `/cs:grill-markdown-html` and `/cs:design-system` are genuinely distinct surfaces (grill vs route vs onboard); no merge candidates. + +## Plugin manifests + +6 plugins, all schema-valid (repo-wide `check_plugin_json.py --all` green), all using canonical `./`-prefixed skills arrays. + +- **markdown-html-skills (2.10.3):** description counts verified — 15 tools (3×5 ✓), 15 references (3×5 ✓), 4 assets (1 schema + 3 templates ✓), 5 skill paths ✓. E2/E3 pass. Best manifest in scope. +- **Productivity five (all 2.9.0):** coherent with their marketplace.json entries (E3 pass), though frozen at 2.9.0 while the repo is at 2.10.3 — per repo policy versions should track releases; bump at next touch. +- **Name drift (low):** marketplace entry names differ from plugin.json `name` for four plugins — `capture-skill`/`capture`, `email-pair`/`email`, `reflect-skill`/`reflect`, `handoff-productivity`/`handoff`. If intentional (ClawHub slug conflicts), document it; otherwise align. +- `handoff` plugin correctly omits a `hooks` key in plugin.json while shipping `hooks/hooks.json` — Claude Code's auto-discovery convention; hooks verified working via `${CLAUDE_PLUGIN_ROOT}` commands. + +## Hooks + +2 hooks (handoff SessionStart + SessionEnd). Both stdlib-only, fail-open (`sys.exit(0)` on import error — "hook must never break a session"), env-disable verified (`HANDOFF_SESSIONSTART=0` / `HANDOFF_SESSIONEND=0`), 12,000-char body cap on injected handoff prevents context blowout. D4 by-design stdin exception documented in-file. PASS. diff --git a/audit/newgen-2026-06/research.md b/audit/newgen-2026-06/research.md new file mode 100644 index 00000000..5b3d7d93 --- /dev/null +++ b/audit/newgen-2026-06/research.md @@ -0,0 +1,133 @@ +# Domain audit: research/ + research-ops/ — new-gen model optimization +Audited: 2026-06-10 · Skills: 13 (8 research/ + 5 research-ops/) · Agents: 9 · Commands: 14 · Plugins: 9 + +## Scorecard +| Skill | Verdict | Top issue | +|---|---|---| +| research-ops/research-ops-skills (orchestrator) | KEEP | Routing is prose-only (no classifier script like research/ ships) — acceptable, but inconsistent with sibling | +| research-ops/clinical-research | KEEP | — (model citizen; all hard rules verified in tool output) | +| research-ops/research-finance | KEEP | — (capex router never auto-decides; named owner verified) | +| research-ops/market-research | KEEP | — (both-methods TAM + triangulation flag verified) | +| research-ops/product-research | KEEP | — (INSIGHT vs ANECDOTE gate verified) | +| research/research (orchestrator) | OPTIMIZE | Single-keyword signals ("funding", "fda", "patent", "grant") cause weak-match misroutes; 319-line body restates generic search methodology | +| research/pulse | OPTIMIZE | Unauthenticated reddit.com/search.json is post-2023-API fragile; duplicated Agent Integrity boilerplate | +| research/litreview | OPTIMIZE | Hard Consensus-MCP dependency with no free-API fallback; phantom `scripts/office/validate.py` | +| research/grants | OPTIMIZE | Phantom `scripts/office/validate.py`; otherwise the strongest skill in the pack (RePORTER POST, dynamic FY, correct NIH receipt dates) | +| research/dossier | OPTIMIZE | Phantom `scripts/office/validate.py`; 318-line body | +| research/patent | OPTIMIZE | Phantom validate.py; `patents.uspto.gov/patent/...` hyperlink pattern is wrong (PPS lives at ppubs.uspto.gov) | +| research/syllabus | OPTIMIZE | Phantom validate.py; bundled JS requires npm `docx` (fails clean, but install path undocumented in plugin) | +| research/notebooklm | REWRITE | Hardcoded UI inventory of a fast-moving Google product has already rotted; description (8 Studio types) contradicts body (9) | + +Verdict counts: **KEEP 5 · OPTIMIZE 7 · REWRITE 1 · CUT-OR-MERGE 0** + +## Domain-level findings + +1. **Phantom tool path across 5 research/ skills (A3 fail).** `python scripts/office/validate.py ` is referenced as the DOCX validation step in litreview, grants, dossier, patent, and syllabus SKILL.md (plus litreview's README/agent/command and two reference docs). The file exists nowhere in the repo (`find -path "*office/validate.py"` → empty). Every DOCX workflow ends with an instruction the model cannot execute. One fix (ship the validator or delete the step) clears 5 skills at once. +2. **research-ops/ hard rules are genuinely operationalized — all sample runs passed.** `sample_size_estimator.py --sample` prints the "ESTIMATE ONLY — confirm with a biostatistician" banner + assumptions block + named-owner requirement; `market_sizer.py --sample` prints top-down AND bottoms-up TAM/SAM/SOM, a 73.4% divergence figure, and a "TRIANGULATION FAILED" flag; `insight_synthesizer.py --sample` promotes the 3-participant cluster to INSIGHT and flags 1- and 2-participant clusters as ANECDOTE; `capex_vs_opex_router.py --sample` routes all three verdicts to "R&D Finance Controller (+ External Auditor)"; `phase_gate_scorer.py --sample --output json` emits `verdict: GO` with a 3-name owner chain. Config consumption is real (tools import `config_loader`, CLI overrides, `RESEARCH_OPS_NO_CONFIG=1` bypass). This domain is the template the research/ pack should be refactored toward. +3. **research/ context economy is poor and boilerplate is forked, not shared.** SKILL.md bodies run 251–319 lines each; the "Agent Integrity Rules (Research-Pack Convention)" block is repeated near-verbatim in 7 files; `citation_tracker.py` exists as **6 divergent copies** (217–303 lines, all different md5s, 1,556 lines total). Per-skill self-containment is repo policy, but the variants have already drifted — a bug fix in one will not propagate. A shared reference + per-skill thin wrapper would cut ~40% of the pack's context weight. +4. **The repo's own checklist flags are partly a phrasing artifact, partly real.** Re-ran `skill_review_checklist_runner.py` on all 13: research-ops = 4/6 across the board (only fails the under-100-lines rule + the light 'skill'/'tool' terminology heuristic); research/ = 2–4/6. The "Missing trigger" failures on 7 of 8 research/ skills are because descriptions say `Triggers: 'pulse on [topic]'…` instead of the validator's `Use when…` pattern — the descriptions themselves are substantively rich (A1 passes on content, fails the repo gate on phrasing). The notebooklm 2/6 and research 2/6 KNOWN scores reproduce; research additionally trips the time-sensitive check ("in 2026"). +5. **External-surface fragility is concentrated in research/.** Consensus MCP is a hard dependency for litreview, syllabus, and grants Phase 2A with zero fallback to free academic APIs (PubMed E-utilities, OpenAlex, Semantic Scholar — all keyless); pulse leans on unauthenticated Reddit JSON endpoints that Reddit increasingly blocks from datacenter IPs; notebooklm hardcodes a Google SPA's UI inventory. New-gen models with native WebSearch/WebFetch make free-API fallbacks cheap to specify — the skills predate that assumption. +6. **The orchestrator routing claim verifies.** `classifier.py` SIGNALS dict matches the SKILL.md table phrase-for-phrase; live tests: 3-signal litreview question → `route_to: litreview`, "research Microsoft" → `fallback` (as the SKILL.md explicitly promises), "dossier on Acme Corp for due diligence" → `dossier` (2 signals). The ≥2-signal threshold, single-weak-match rule, and fallback rule are all implemented. The followability problem is precision, not existence (see per-skill). +7. **All 48 Python scripts across both domains pass `--help` exit 0**; stdlib-only confirmed. The one non-Python script (`generate_reading_list.js`) fails without `npm install docx` but fails with a clear actionable message (acceptable, documented). +8. **Stray `__pycache__/*.pyc` committed under 4 research-ops script dirs** — repo hygiene, should be gitignored. + +## Per-skill findings + +### research/research (orchestrator) — OPTIMIZE +- Single-keyword signals over-trigger: "funding", "fda", "grant" (grants), "patent", "invention" (patent), "curriculum" (syllabus) each score 1 alone → the "single weak match" rule silently routes e.g. "research FDA approval trends" to grants. Multi-word phrases route reliably; bare nouns don't. +- 319 lines; Phase 3b fallback (decompose → search → synthesize → cite) restates what a frontier model does unprompted — keep the budget numbers + audit-log contract, cut the how-to prose. +- "Waits 1 turn… or auto-proceeds after 5s" is an un-executable affordance (the model cannot wait wall-clock time); checklist also flags "in 2026" as time-sensitive. +- Description lacks `Use when` phrasing → fails repo A1 gate (2/6 known score reproduces). +- Verify: `python3 scripts/classifier.py --question "research Microsoft" --output json` → `route_to: "fallback"`. +- Verify: `python3 scripts/classifier.py --question "literature review on PICO meta-analysis" --output json` → `route_to: "litreview"`, ≥2 signals. +- Verify: bare-noun precision test added: "research FDA approval trends" must NOT route to grants (after signal-list fix). +- Verify: checklist runner item 1 (trigger) and item 3 (time-sensitive) pass. + +### research/pulse — OPTIMIZE +- Reddit phase depends on unauthenticated `reddit.com/search.json`; since the 2023 API changes these endpoints are routinely 403'd from non-browser/datacenter clients. Fallbacks exist (`raw_json=1`, subreddit-restricted) but a "Reddit fully blocked → degrade to Web-phase reddit site: search" path is missing. +- Hardcoded trusted-publisher `site:` list (NYT/WSJ/Wired/Verge/TechCrunch) is US-tech-centric and will silently skew non-tech topics. +- 258 lines incl. duplicated Agent Integrity block; checklist fails under-100-lines + terminology. +- Verify: `python3 scripts/time_window_calculator.py --window 30d` exits 0 and emits both HN `created_at_i` timestamp and Reddit `t=month`. +- Verify: `python3 scripts/citation_tracker.py --help` exits 0; session file lands at `~/.pulse_sessions/`. +- Verify: SKILL.md documents an explicit all-Reddit-blocked degradation path. + +### research/litreview — OPTIMIZE +- Hard Consensus-MCP dependency; no fallback to free academic APIs (PubMed E-utilities / OpenAlex / Semantic Scholar are keyless) — the skill is inert in any harness without that one MCP. +- References phantom `python scripts/office/validate.py output.docx` (file does not exist anywhere in repo). +- Plan-tier detection parses marketing copy ("Showing top 10" / "upgrade") — brittle heuristic; will mis-detect when Consensus rewords. +- Verify: `python3 scripts/framework_recommender.py --help` and `cross_search_aggregator.py --help` exit 0. +- Verify: no reference to `scripts/office/validate.py` remains (grep returns empty) OR the validator ships. +- Verify: SKILL.md names at least one free-API fallback for the no-Consensus case. + +### research/grants — OPTIMIZE +- Phantom `scripts/office/validate.py` in Phase 4 (only blocking edit — domain expertise is otherwise the best in the pack: RePORTER v2 POST templates, NOSI URL pattern, scope-aware mechanism matrix, dynamic FY window, NIH standard receipt dates all check out). +- Phase 2A (5 Consensus searches) has no free fallback; RePORTER core works without it but the SKILL treats Consensus as mandatory. +- Description fails the `Use when` gate (phrasing only). +- Verify: `python3 scripts/fiscal_year_calculator.py --output json` → `current_fy` correct for today's date (Oct 1 boundary), 4-year window. +- Verify: `python3 scripts/mechanism_matcher.py --career-stage early_career --prelim-data pilot --environment r01_eligible --scope single_site --output json` → shortlist excludes R01, includes R21/K-series. +- Verify: phantom validate.py reference removed or implemented. + +### research/dossier — OPTIMIZE +- Phantom `scripts/office/validate.py` in Phase 10; 318-line body (longest in pack) with duplicated integrity boilerplate. +- The ≥30% disconfirming-evidence rule, source-tier tagging, and mandatory-hypothesis gate are excellent new-gen design (forces the model out of confirmation mode) — preserve verbatim. +- Glassdoor/Comparably scraping listed as a source will be blocked in practice; "degrade gracefully" is stated but the degraded output shape isn't. +- Verify: `python3 scripts/disconfirming_evidence_balance.py --help` exits 0; given a session with <30% disconfirming queries it returns a non-zero/warn signal. +- Verify: `python3 scripts/source_tier_classifier.py --help` exits 0; sec.gov → primary, a substack URL → tertiary. +- Verify: phantom validate.py reference removed or implemented. + +### research/patent — OPTIMIZE +- Phantom `scripts/office/validate.py` in Phase 7. +- DOCX styling section gives `https://patents.uspto.gov/patent/...` as the USPTO hyperlink pattern — that host pattern is wrong (the skill's own source list correctly says `ppubs.uspto.gov`); links generated from it will 404. +- Sub-use-case routing, date discipline (filing/priority/publication/grant per use case), and CPC class follow-up are real practitioner expertise — keep. +- Verify: `python3 scripts/sub_use_case_router.py --sub-use-case novelty --jurisdictions "" --risk strict --known-art "US10000000B2"` exits 0 and emits a 5-8 query plan. +- Verify: `python3 scripts/family_resolver.py --help` exits 0. +- Verify: no `patents.uspto.gov/patent/` literal remains in SKILL.md. + +### research/syllabus — OPTIMIZE +- Phantom `python scripts/office/validate.py` in Phase 6; Consensus-MCP hard dependency (same fix as litreview). +- `generate_reading_list.js` requires npm `docx`; fails with a clear message (verified) but neither SKILL.md Portability note nor plugin docs give the install one-liner next to the invocation. +- Applied-domain weaving + Bloom higher-order validator are genuinely non-obvious value — keep. +- Verify: `node scripts/generate_reading_list.js --help` without docx installed exits non-zero with the "npm install docx" message (graceful-fail contract). +- Verify: `python3 scripts/discussion_question_validator.py --help` and `topic_grouper.py --help` exit 0. +- Verify: phantom validate.py reference removed or implemented. + +### research/notebooklm — REWRITE +- Freshness rot on a fast-iterating Google SPA: the hardcoded Studio inventory (9 types incl. "Table of Contents") no longer matches the product — NotebookLM added Video Overviews (2025) and Flashcards/Quiz, and reorganized report-style outputs; none appear anywhere in skill, scripts, or references (moderate-high confidence; needs re-verification against the live UI). +- Internal inconsistency: frontmatter description lists 8 Studio types, body Action 3 lists 9 — the plugin.json mirrors the stale 8. +- Known 2/6 checklist score reproduces: no `Use when` trigger phrasing, 290 lines, zero code blocks (no concrete invocation examples). +- Structure is salvageable (Step-0 environment gate, fire-and-notify async table, screenshot-first, find()-before-click are all sound discipline; `async_action_classifier.py` works); the rot-prone content is the hardcoded UI inventory + timing estimates. Rewrite to discover output types from the live Studio panel screenshot instead of enumerating them, add a "verified against NotebookLM as of " maintenance marker, fix the 8-vs-9 contradiction. +- Verify: `python3 scripts/async_action_classifier.py --action "audio overview"` → `FIRE_AND_NOTIFY`; `--action "add source"` → wait verdict. +- Verify: frontmatter description and Action 3 list enumerate the same set (or neither enumerates). +- Verify: SKILL.md contains ≥1 fenced concrete-example block and a `Use when`-style trigger; checklist item 5 passes. +- Verify: a dated "UI verified" marker exists and is < 6 months old at release time. + +## KEEP-verdict verification criteria + +- **research-ops-skills (orchestrator):** SKILL.md signal table lists exactly 4 lanes matching the 4 sub-skill folder names; `grep -c "Never silently chain" SKILL.md` ≥ 1; every `skills//scripts/onboard.py` path it references resolves from `research-ops/`. +- **clinical-research:** `python3 scripts/sample_size_estimator.py --sample` exits 0, output contains "ESTIMATE" banner and `n_group1_with_dropout` > `n_group1_raw`; `phase_gate_scorer.py --sample --output json` → `verdict` ∈ {GO, GO-WITH-CONDITIONS, REDESIGN, NO-GO} and `named_owners` non-empty; `endpoint_selector.py --sample` flags the unvalidated surrogate below PRIMARY. +- **research-finance:** `capex_vs_opex_router.py --sample --standard ifrs` exits 0, every item carries `route to:` a named owner and the "DECISION SUPPORT ONLY" banner prints; `burn_runway_tracker.py --sample --output json` → `runway_months_approx` float + per-milestone `verdict`. +- **market-research:** `market_sizer.py --sample` prints BOTH `[top-down]` and `[bottoms-up]` TAM/SAM/SOM lines, a divergence %, and "TRIANGULATION FAILED" when delta > tolerance; `sample_size_planner.py --population 62000 --confidence 0.95 --moe 0.05` exits 0 with FPC-corrected n; `segmentation_scorer.py --sample` drops the solopreneur slice. +- **product-research:** `insight_synthesizer.py --sample --min-sources 3` promotes the 3-source cluster to INSIGHT and labels 1–2-source clusters ANECDOTE; `saturation_planner.py --method thematic --segments 3` emits a confidence label and the "not a power calculation" disclaimer; `study_designer.py --goal evaluative --stage live` redirects live A/B to experiment-designer. + +## Agents + +9 agents total (8 in `research//agents/`, 1 in `research-ops/agents/`). **All pass B2/B3 strongly** — each persona has distinct refusal behaviors that change outcomes (cs-dossier refuses without a hypothesis; cs-patent refuses without a sub-use-case; cs-research surfaces routing + override; cs-research-ops-orchestrator demands method-before-number) and verbatim voice lines, not adjective swaps. B1 issues: +- research/ agent descriptions describe behavior but lack `Use when`/`Use PROACTIVELY` trigger phrasing (same artifact as the SKILL.md gate). +- All 8 research/ agents pin `model: opus` — for a deterministic-routing front door (cs-research) sonnet would do; cost note only. +- research/ agents carry non-standard `skills:`/`domain:` frontmatter keys (harmless, but not part of the agent schema the repo's other domains use). +- cs-research-ops-orchestrator is the cleanest: standard frontmatter, `model: sonnet`, Skill tool wired for fork-routing. + +## Commands + +14 total: 8 `/cs:*` in research/ plugins, 6 in research-ops/. All pass C1 + C3 (each orchestrates intake gates, tool sequences, and refusal rules a bare prompt would not enforce). Findings: +- **research-ops commands are the better pattern:** proper `argument-hint:` field + explicit `$ARGUMENTS` interpolation + per-command three-tool workflow. `/cs:grill-research-ops` adds real value (docs-anchored one-question-at-a-time gate before any sub-skill). +- **research/ commands** embed the argument shape inside the description string and omit `argument-hint` / `$ARGUMENTS` (C2 partial) — they read as documentation pages for the agent rather than parameterized commands. Targeted fix: add `argument-hint` + `$ARGUMENTS` block to all 8. +- Mild redundancy: `/cs:research` + 6 specialist commands + the router skill itself is three entry points to the same routing logic; acceptable, but the specialist commands should state "or just use /cs:research" to avoid user confusion. + +## Plugin manifests + +All 9 pass `scripts/check_plugin_json.py --all` (E1). Versions uniformly 2.9.0 and present in marketplace.json (E3). Issues: +- **Name mismatch (E3 minor):** marketplace entry `research-orchestrator` points at `./research/research` whose plugin.json `name` is `research`. Intentional slug-disambiguation per ClawHub rules, but the inconsistency is undocumented in either file. +- **Stale content drift (E2):** `notebooklm` plugin.json description carries the 8-type Studio list (mirrors the stale SKILL.md frontmatter) — fix together with the notebooklm rewrite. +- research-ops single-domain-plugin description accurately enumerates the 4 sub-skills + orchestrator; matches contents. +- Hygiene: committed `__pycache__/*.pyc` under `research-ops/skills/{clinical-research,market-research,product-research,research-finance}/scripts/` should be removed/ignored. diff --git a/business-growth/.claude-plugin/plugin.json b/business-growth/.claude-plugin/plugin.json index 6945ceb6..e268459b 100644 --- a/business-growth/.claude-plugin/plugin.json +++ b/business-growth/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "business-growth-skills", - "description": "5 business & growth skills: customer success manager, sales engineer, revenue operations, contract & proposal writer, and BizDev-toolkit. Agent skill and plugin for Claude Code, Codex, Gemini CLI, Cursor, OpenClaw.", + "description": "4 business & growth skills plus a router: customer success manager (health scoring, churn), sales engineer (RFP analysis, PoC planning), revenue operations (pipeline, forecast accuracy, GTM), and contract & proposal writer. Agent skill and plugin for Claude Code, Codex, Gemini CLI, Cursor, OpenClaw.", "version": "2.9.0", "author": { "name": "Alireza Rezvani", @@ -12,4 +12,4 @@ "skills": [ "./skills" ] -} +} \ No newline at end of file diff --git a/business-growth/skills/business-growth-skills/SKILL.md b/business-growth/skills/business-growth-skills/SKILL.md index 15f595f3..4c5fb183 100644 --- a/business-growth/skills/business-growth-skills/SKILL.md +++ b/business-growth/skills/business-growth-skills/SKILL.md @@ -1,6 +1,6 @@ --- name: "business-growth-skills" -description: "4 business growth agent skills and plugins for Claude Code, Codex, Gemini CLI, Cursor, OpenClaw. Customer success (health scoring, churn), sales engineer (RFP), revenue operations (pipeline, GTM), contract & proposal writer. Python tools (stdlib-only)." +description: "Router/index for the 4 business & growth skills bundled in this plugin: customer-success-manager (health scoring, churn risk, expansion), sales-engineer (RFP analysis, competitive matrices, PoC planning), revenue-operations (pipeline, forecast accuracy, GTM efficiency), and contract-and-proposal-writer. Use when a growth/revenue request doesn't obviously match one skill and you need to pick the right one (e.g., 'which accounts are at risk', 'should we bid on this RFP')." version: 2.9.0 author: Alireza Rezvani license: MIT @@ -16,41 +16,30 @@ agents: - openclaw --- -# Business & Growth Skills +# Business & Growth Skills — Router -4 production-ready skills for customer success, sales, and revenue operations. +This plugin bundles **4 skills** (this router is the 5th folder under `business-growth/skills/`). Each skill is self-contained. -## Quick Start +## Routing table -### Claude Code -``` -/read business-growth/customer-success-manager/SKILL.md -``` +Match the request, then load `business-growth/skills//SKILL.md`. If multiple rows match, ask one clarifying question first. -### Codex CLI -```bash -npx agent-skills-cli add alirezarezvani/claude-skills/business-growth -``` +| Request signals | Skill | Path | +|---|---|---| +| Customer health scores, churn risk, expansion plays | customer-success-manager | `skills/customer-success-manager/` | +| RFP/RFI coverage, competitive positioning, PoC plans | sales-engineer | `skills/sales-engineer/` | +| Pipeline coverage, forecast accuracy (MAPE), GTM efficiency | revenue-operations | `skills/revenue-operations/` | +| Proposals, contracts, statements of work, DPAs | contract-and-proposal-writer | `skills/contract-and-proposal-writer/` | -## Skills Overview - -| Skill | Folder | Focus | -|-------|--------|-------| -| Customer Success Manager | `customer-success-manager/` | Health scoring, churn prediction, expansion | -| Sales Engineer | `sales-engineer/` | RFP analysis, competitive matrices, PoC planning | -| Revenue Operations | `revenue-operations/` | Pipeline analysis, forecast accuracy, GTM metrics | -| Contract & Proposal Writer | `contract-and-proposal-writer/` | Proposal generation, contract templates | - -## Python Tools - -9 scripts, all stdlib-only: +## Quick start ```bash -python3 customer-success-manager/scripts/health_score_calculator.py --help -python3 revenue-operations/scripts/pipeline_analyzer.py --help +# Example: route an account-health request +cat business-growth/skills/customer-success-manager/SKILL.md +python3 business-growth/skills/customer-success-manager/scripts/health_score_calculator.py --help ``` ## Rules -- Load only the specific skill SKILL.md you need -- Use Python tools for scoring and metrics, not manual estimates +- Route to exactly one skill, then follow that skill's workflow. This router ships no tools of its own. +- Use the skills' Python scorers for metrics, not manual estimates; deal/contract outputs are drafts for human legal/commercial review. diff --git a/business-growth/skills/sales-engineer/SKILL.md b/business-growth/skills/sales-engineer/SKILL.md index dc1e5fad..912f6d2d 100644 --- a/business-growth/skills/sales-engineer/SKILL.md +++ b/business-growth/skills/sales-engineer/SKILL.md @@ -211,9 +211,9 @@ python scripts/poc_planner.py poc_data.json --format json # JSON output ## Integration Points -- **Marketing Skills** - Leverage competitive intelligence and messaging frameworks from `../../marketing-skill/` -- **Product Team** - Coordinate on roadmap items flagged as "Planned" in RFP analysis from `../../product-team/` -- **C-Level Advisory** - Escalate strategic deals requiring executive engagement from `../../c-level-advisor/` +- **Marketing Skills** - Leverage competitive intelligence and messaging frameworks from `marketing-skill/` +- **Product Team** - Coordinate on roadmap items flagged as "Planned" in RFP analysis from `product-team/` +- **C-Level Advisory** - Escalate strategic deals requiring executive engagement from `c-level-advisor/` - **Customer Success** - Hand off POC results and success criteria to CSM from `../customer-success-manager/` --- diff --git a/business-operations/skills/capacity-planner/SKILL.md b/business-operations/skills/capacity-planner/SKILL.md index 59ff19ed..a6ba39ee 100644 --- a/business-operations/skills/capacity-planner/SKILL.md +++ b/business-operations/skills/capacity-planner/SKILL.md @@ -83,6 +83,13 @@ It produces three artifacts: All three accept `--input ` (JSON), `--output {markdown,json}`, `--sample` (built-in example), and `--help`. Stdlib only. +## Quick example + +```bash +# Emits an Erlang-C capacity model (required headcount + P50/P90/P99 breach probabilities) for the built-in example +cd business-operations/skills/capacity-planner && python3 scripts/capacity_modeler.py --sample +``` + ## References - `references/queueing_theory_canon.md` — Erlang, Little, Hopp & diff --git a/business-operations/skills/internal-comms/SKILL.md b/business-operations/skills/internal-comms/SKILL.md index 312fba79..49cdb79a 100644 --- a/business-operations/skills/internal-comms/SKILL.md +++ b/business-operations/skills/internal-comms/SKILL.md @@ -1,6 +1,6 @@ --- name: 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 — a re-org announcement, a tool rollout, a policy change, a benefit change, a leadership transition, a layoff, an acquisition close, or an internal product launch — and the audience is employees (not customers). Triggers on "all-hands announcement", "town-hall script", "change comms", "internal newsletter", "rollout comms", "policy change announcement", "re-org announcement", "internal FAQ", "manager talking points", "Prosci ADKAR", "Kotter 8-step", "layoff comms", "RIF comms", "internal memo". Pairs Prosci ADKAR (Awareness / Desire / Knowledge / Ability / Reinforcement) 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-tuned via --profile {tech-startup, scaleup, enterprise, public-company, non-profit}. Distinct from marketing-skill/* (external/customer-facing), c-level-advisor/internal-narrative (strategic framing, not tactical drafts), and c-level-advisor/change-management (executive change strategy, not the comms package itself). +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 — a re-org announcement, a tool rollout, a policy change, a leadership transition, a layoff, an acquisition close, or an internal product launch — 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-tuned via --profile {tech-startup, scaleup, enterprise, public-company, non-profit}. Triggers on "all-hands announcement", "change comms", "rollout comms", "re-org announcement", "manager talking points", "layoff comms". version: 2.8.0 author: claude-code-skills license: MIT @@ -59,6 +59,13 @@ Five-step deterministic flow. Follow in order. All three: stdlib only, `--help` and `--sample` exit 0, accept `--input ` and `--output {markdown,json}`. +## Quick example + +```bash +# Emits the 4-artifact comms package (pre-comm, announcement, FAQ, follow-up) for the built-in tool-rollout example +cd business-operations/skills/internal-comms && python3 scripts/comms_template_filler.py --sample +``` + ## References - `references/change_management_canon.md` — Jeff Hiatt *ADKAR* (Prosci), John Kotter *Leading Change* (8-step), William Bridges *Managing Transitions* (Endings / Neutral Zone / Beginnings), Edgar Schein *Organizational Culture and Leadership*, McKinsey 7-S framework, Heath brothers *Switch*, Patrick Lencioni *The Advantage*. diff --git a/business-operations/skills/knowledge-ops/SKILL.md b/business-operations/skills/knowledge-ops/SKILL.md index 334484ba..06902b76 100644 --- a/business-operations/skills/knowledge-ops/SKILL.md +++ b/business-operations/skills/knowledge-ops/SKILL.md @@ -1,6 +1,6 @@ --- name: 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, expense reimbursement, system-access provisioning, customer-escalation playbook) — 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, ops onboarding doc generation, and runbook step verification (named owner, expected duration, observable success signal, rollback path, escalation contact). Pairs Kaoru Ishikawa's 5W2H method, Atul Gawande's *The Checklist Manifesto*, ISO 9001, ITIL v4 Service Operation, FDA 21 CFR Part 211, and Google SRE Workbook runbook discipline with deterministic stdlib-only Python tools that score completeness, detect anti-patterns, and emit prioritized cleanup lists. Distinct from `engineering/llm-wiki` (Karpathy-style personal PKM second brain), `engineering-team/runbook-generator` (system-ops production debugging runbook), `project-management/*` (Jira/Confluence delivery + ticket tracking), and sibling `business-operations/process-mapper` (BPMN process *design*, while knowledge-ops is process *documentation*). +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) — 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 Manifesto*, ISO 9001, ITIL v4, and Google SRE Workbook runbook discipline with deterministic stdlib-only Python tools that score completeness, detect anti-patterns, and emit prioritized cleanup lists (e.g., "validate this runbook before it goes into rotation", "audit our Confluence wiki for stale and orphaned SOPs"). context: fork version: 2.8.0 author: claude-code-skills @@ -18,7 +18,7 @@ Company SOP + internal runbook authoring, 5W2H completeness validation, and KB h An ops organization three years in accumulates a sprawl: 600 Notion pages, 200 Confluence runbooks, three Obsidian vaults, a `Drive/SOPs/` folder, and a `Slack #ops-questions` channel that exists because nobody can find the canonical doc. Predictable failure modes: 1. **No owner** — 40% of SOPs name "the team" instead of a person. When the doc rots, nobody is accountable. -2. **No last-reviewed date** — a 2023 vendor-offboarding SOP still references a procurement tool sunset in 2024. +2. **No last-reviewed date** — a years-old vendor-offboarding SOP still references a procurement tool that was sunset over a year ago. 3. **Vague success signals** — runbook step 4 says "verify the service is up". A new operator can't tell what that means. 4. **No rollback path** — incident-comms cascade runbook tells you how to send the alert. It doesn't tell you how to retract it when the alert was wrong. 5. **Orphan pages** — half the KB has no inbound links. Nobody finds them via navigation; they only exist because somebody knew the URL. @@ -52,6 +52,13 @@ Four-step deterministic flow (matches the ops org's actual workflow, not an abst **`scripts/kb_ingester.py`** — Walks a directory of markdown files (Notion export, Confluence space export, Obsidian vault, `Drive/SOPs/` directory). Extracts: (a) cross-link map (which page references which, via markdown `[link](path)` syntax), (b) glossary candidates (frequently used proper nouns and acronyms that recur in 3+ docs without a single canonical definition page), (c) orphan pages (no inbound links from anywhere in the vault), (d) glossary drift (the same term defined or used inconsistently across docs — e.g., "CSM" expanded differently in two places), (e) stale pages (no edit in > 12 months, detected via filesystem mtime or YAML `last_reviewed` frontmatter), (f) missing-owner pages (no `owner:` field in frontmatter). Emits a KB health report markdown with a prioritized top-20 cleanup list ranked by `staleness × inbound-link-count` (high-traffic stale docs first). `--sample` builds a tiny synthetic 8-page vault in a tmpdir and runs the full pipeline against it. Stdlib only. +## Quick example + +```bash +# Builds a synthetic 8-page vault and emits a KB health report (orphans, stale pages, glossary drift, top-20 cleanup list) +cd business-operations/skills/knowledge-ops && python3 scripts/kb_ingester.py --sample +``` + ## References - `references/5w2h_sop_canon.md` — Kaoru Ishikawa's 5W2H method, Toyota standard-work discipline, Atul Gawande's checklist manifesto, Atlassian Confluence SOP guidance, ISO 9001 SOP requirements, ITIL v4 Service Operation, FDA 21 CFR Part 211. Eight cited sources covering SOP authoring canon. diff --git a/business-operations/skills/process-mapper/SKILL.md b/business-operations/skills/process-mapper/SKILL.md index d15c9aaf..0043d906 100644 --- a/business-operations/skills/process-mapper/SKILL.md +++ b/business-operations/skills/process-mapper/SKILL.md @@ -47,6 +47,13 @@ Five-step deterministic flow: **`scripts/cycle_time_analyzer.py`** — Computes total P50 and P90 cycle time, value-add ratio (VA%), wait %, rework %, and a Little's-Law throughput estimate (WIP / cycle time). Per Lean canon: VA% > 25% = HEALTHY, 10–25% = TYPICAL (most non-manufacturing processes land here), < 10% = WASTE-HEAVY. +## Quick example + +```bash +# Renders a BPMN-style swim-lane diagram + normalized JSON for the built-in 6-stage procurement-intake example +cd business-operations/skills/process-mapper && python3 scripts/process_documenter.py --sample +``` + ## References - `references/lean_six_sigma_canon.md` — TIMWOOD wastes, value-stream mapping, Theory of Constraints, Kanban WIP, Little's Law. Cites Womack & Jones, Rother & Shook, Goldratt, Ohno, Liker, Pyzdek, Anderson. diff --git a/business-operations/skills/procurement-optimizer/SKILL.md b/business-operations/skills/procurement-optimizer/SKILL.md index 6c9d05c7..e0e02526 100644 --- a/business-operations/skills/procurement-optimizer/SKILL.md +++ b/business-operations/skills/procurement-optimizer/SKILL.md @@ -1,6 +1,6 @@ --- name: procurement-optimizer -description: Use when running an annual SaaS audit, doing category-level spend review, or rationalizing the supplier base — when the user needs to do a spend audit, spend categorization (UNSPSC-aligned), purchasing-cycle analysis, or risk-balanced supplier consolidation. Triggers on "spend audit", "SaaS audit", "spend categorization", "supplier rationalization", "supplier consolidation", "purchasing cycle", "procurement review", "category strategy", "duplicate SaaS", "renewal cluster". Ships 3 stdlib-only Python tools (UNSPSC-aligned spend categorizer with Pareto breakdown and industry profiles, purchasing-cycle analyzer that surfaces bottleneck categories per Goldratt's Theory of Constraints, supplier-consolidation planner that refuses single-source recommendations for tier-1 categories without a documented break-glass plan), 3 reference docs each citing 7+ authoritative sources (A.T. Kearney / Hackett / Spend Matters / UNSPSC / Productiv / Vendr / Tropic / IACCM / ISM / BCG), and a 20-minute spend-intake template. Distinct from sibling vendor-management (performance scoring of vendors you keep paying), finance/financial-analysis (close + report, not category strategy), and c-level-advisor/general-counsel-advisor (contract law, not category rationalization). +description: Use when running an annual SaaS audit, doing category-level spend review, or rationalizing the supplier base — 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", "duplicate SaaS", "renewal cluster". version: 2.8.0 author: claude-code-skills license: MIT @@ -99,6 +99,13 @@ Combine the 3 artifacts into a BizOps-ready digest: All three accept `--input` (JSON), `--output` (markdown path), `--sample` (run with built-in sample data), and `--help`. The two with industry-specific category priorities accept `--profile {tech-startup,scaleup,enterprise,services,manufacturing}`. +## Quick example + +```bash +# Emits a UNSPSC-aligned spend categorization with Pareto breakdown for the built-in sample spend file +cd business-operations/skills/procurement-optimizer && python3 scripts/spend_categorizer.py --sample +``` + ## References - `references/spend_management_canon.md` — A.T. Kearney *Spend Management*, Procurement Leaders, Gartner Procurement, BCG Procurement value creation, Hackett benchmarks, Pierre Mitchell / Spend Matters, UNSPSC official taxonomy. diff --git a/business-operations/skills/vendor-management/SKILL.md b/business-operations/skills/vendor-management/SKILL.md index 8eec66e4..490714c8 100644 --- a/business-operations/skills/vendor-management/SKILL.md +++ b/business-operations/skills/vendor-management/SKILL.md @@ -1,6 +1,6 @@ --- name: vendor-management -description: Use when reviewing, scoring, or auditing third-party SaaS / vendor relationships — running a vendor scorecard, tracking SLA compliance, classifying third-party risk, preparing a tier-1 vendor review, or auditing the SaaS portfolio. Triggers on "vendor SLA", "vendor scorecard", "third-party risk", "TPRM", "vendor review", "SaaS audit", "supplier performance", "vendor health check", "renewal review". Forks context so large vendor catalogs (50-500 line items) and SLA logs don't pollute the parent thread. Ships 3 stdlib-only Python tools (vendor scorer with industry tuning, SLA compliance tracker with credit-claim flags, vendor risk classifier across 4 risk vectors), 3 reference docs each citing 7+ authoritative sources (Gartner / Shared Assessments / NIST / ISO 27036 / breach post-mortems), and a 5-vendor catalog template. Distinct from c-level-advisor/general-counsel-advisor (contract law, not operational management), business-growth/contract-and-proposal-writer (outbound proposals, not inbound vendor scoring), and sibling procurement-optimizer (spend categorization, not vendor performance). +description: Use when reviewing, scoring, or auditing third-party SaaS / vendor relationships — running a vendor scorecard with industry tuning, tracking SLA compliance with credit-claim flags, classifying third-party risk across 4 risk vectors, preparing a tier-1 vendor review, or auditing the SaaS portfolio. Forks context so large vendor catalogs (50-500 line items) and SLA logs don't pollute the parent thread. Triggers on "vendor SLA", "vendor scorecard", "third-party risk", "TPRM", "vendor review", "supplier performance", "vendor health check", "renewal review". context: fork version: 2.8.0 author: claude-code-skills @@ -110,6 +110,13 @@ Combine the 3 artifacts into a final BizOps / VMO digest: All three accept `--input` (JSON), `--output` (markdown path), `--sample` (run with built-in sample data), and `--help`. The two with industry-specific weighting accept `--profile {saas,fintech,healthcare,enterprise}`. +## Quick example + +```bash +# Emits a weighted vendor scorecard (industry-tuned dimensions + per-vendor verdict) for the built-in sample catalog +cd business-operations/skills/vendor-management && python3 scripts/vendor_scorer.py --sample +``` + ## References - `references/vendor_management_canon.md` — Gartner / Shared Assessments / ISO 27036 / NIST 800-161 / Forrester / ISACA / Vendr industry reports diff --git a/c-level-advisor/README.md b/c-level-advisor/README.md index 302ca3cf..fdc2ffea 100644 --- a/c-level-advisor/README.md +++ b/c-level-advisor/README.md @@ -36,10 +36,10 @@ npx ai-agent-skills install alirezarezvani/claude-skills/c-level-advisor --agent ```bash # CEO Advisor -npx ai-agent-skills install alirezarezvani/claude-skills/c-level-advisor/ceo-advisor +npx ai-agent-skills install alirezarezvani/claude-skills/c-level-advisor/skills/ceo-advisor # CTO Advisor -npx ai-agent-skills install alirezarezvani/claude-skills/c-level-advisor/cto-advisor +npx ai-agent-skills install alirezarezvani/claude-skills/c-level-advisor/skills/cto-advisor ``` **Supported Agents:** Claude Code, Cursor, VS Code, Copilot, Goose, Amp, Codex @@ -148,7 +148,7 @@ This C-Level advisory skills collection provides executive leadership guidance f 1. **Install CEO Advisor:** ```bash - npx ai-agent-skills install alirezarezvani/claude-skills/c-level-advisor/ceo-advisor + npx ai-agent-skills install alirezarezvani/claude-skills/c-level-advisor/skills/ceo-advisor ``` 2. **Evaluate Strategic Initiative:** @@ -170,7 +170,7 @@ This C-Level advisory skills collection provides executive leadership guidance f 1. **Install CTO Advisor:** ```bash - npx ai-agent-skills install alirezarezvani/claude-skills/c-level-advisor/cto-advisor + npx ai-agent-skills install alirezarezvani/claude-skills/c-level-advisor/skills/cto-advisor ``` 2. **Analyze Technical Debt:** diff --git a/c-level-advisor/c-level-agents/agents/cs-caio-advisor.md b/c-level-advisor/c-level-agents/agents/cs-caio-advisor.md index 080cf5ca..7a0cc9be 100644 --- a/c-level-advisor/c-level-agents/agents/cs-caio-advisor.md +++ b/c-level-advisor/c-level-agents/agents/cs-caio-advisor.md @@ -158,7 +158,7 @@ python ../../skills/chief-ai-officer-advisor/scripts/ai_cost_economics.py worklo ## Related Agents - [cs-cdo-advisor](cs-cdo-advisor.md) — Training data rights, data strategy (chains directly to model decisions) -- [cs-cto-advisor](../../../../agents/c-level/cs-cto-advisor.md) — Architecture capacity, scaling cliffs +- [cs-cto-advisor](../../../agents/c-level/cs-cto-advisor.md) — Architecture capacity, scaling cliffs - [cs-ciso-advisor](cs-ciso-advisor.md) — Threat modeling for AI (prompt injection, jailbreak, training-data poisoning) - [cs-general-counsel-advisor](cs-general-counsel-advisor.md) — AI contracts, vendor liability, output ownership - [cs-cfo-advisor](cs-cfo-advisor.md) — Build-vs-buy TCO, multi-year vendor commitments diff --git a/c-level-advisor/c-level-agents/agents/cs-cco-advisor.md b/c-level-advisor/c-level-agents/agents/cs-cco-advisor.md index c6ccfa9c..7971f5fc 100644 --- a/c-level-advisor/c-level-agents/agents/cs-cco-advisor.md +++ b/c-level-advisor/c-level-agents/agents/cs-cco-advisor.md @@ -160,7 +160,7 @@ python ../../skills/chief-customer-officer-advisor/scripts/cs_coverage_calculato - [cs-cmo-advisor](cs-cmo-advisor.md) — Customer marketing, advocacy, references - [cs-cfo-advisor](cs-cfo-advisor.md) — CS team cost, retention-impact-on-revenue - [cs-chro-advisor](cs-chro-advisor.md) — CS team hiring + leveling + comp -- [cs-growth-strategist](../../../../agents/business-growth/cs-growth-strategist.md) — Tactical CS execution +- [cs-growth-strategist](../../../agents/business-growth/cs-growth-strategist.md) — Tactical CS execution ## References diff --git a/c-level-advisor/c-level-agents/agents/cs-cdo-advisor.md b/c-level-advisor/c-level-agents/agents/cs-cdo-advisor.md index 9cca3b6a..0ce1b0ce 100644 --- a/c-level-advisor/c-level-agents/agents/cs-cdo-advisor.md +++ b/c-level-advisor/c-level-agents/agents/cs-cdo-advisor.md @@ -104,7 +104,7 @@ python ../../skills/chief-data-officer-advisor/scripts/data_asset_valuator.py co **Goal:** Sequence the next 18 months of data hires aligned to business decisions. 1. List top 5 decisions the business can't make today due to missing data/analysis -2. Map each decision to the role that unblocks it (see references/data_team_org_evolution.md) +2. Map each decision to the role that unblocks it (see ../../skills/chief-data-officer-advisor/references/data_team_org_evolution.md) 3. Sequence hires (one at a time, ramp before next) 4. Cross-check with cs-chro-advisor on comp bands + leveling 5. Identify centralize-vs-embed trigger date @@ -144,7 +144,7 @@ echo "Kill criteria + checkpoint dates in each output." ## Related Agents -- [cs-cto-advisor](../../../../agents/c-level/cs-cto-advisor.md) — architecture capacity +- [cs-cto-advisor](../../../agents/c-level/cs-cto-advisor.md) — architecture capacity - [cs-ciso-advisor](cs-ciso-advisor.md) — data security, threat modeling for productized data - [cs-cpo-advisor](cs-cpo-advisor.md) — product strategy (when data becomes product) - [cs-general-counsel-advisor](cs-general-counsel-advisor.md) — contractual constraints, DPA, training-rights diff --git a/c-level-advisor/c-level-agents/agents/cs-cfo-advisor.md b/c-level-advisor/c-level-agents/agents/cs-cfo-advisor.md index 8fb8d025..d5953347 100644 --- a/c-level-advisor/c-level-agents/agents/cs-cfo-advisor.md +++ b/c-level-advisor/c-level-agents/agents/cs-cfo-advisor.md @@ -114,9 +114,9 @@ echo "Artifacts ready in /tmp/. Feed into /cs:boardroom brief." ## Related Agents -- [cs-ceo-advisor](../../../../agents/c-level/cs-ceo-advisor.md) — strategy & capital allocation partner +- [cs-ceo-advisor](../../../agents/c-level/cs-ceo-advisor.md) — strategy & capital allocation partner - [cs-cro-advisor](cs-cro-advisor.md) — revenue forecast feed -- [cs-financial-analyst](../../../../agents/finance/cs-financial-analyst.md) — deep modeling +- [cs-financial-analyst](../../../agents/finance/cs-financial-analyst.md) — deep modeling - [cs-chief-of-staff](cs-chief-of-staff.md) — routes financial questions here ## References diff --git a/c-level-advisor/c-level-agents/agents/cs-chief-of-staff.md b/c-level-advisor/c-level-agents/agents/cs-chief-of-staff.md index d60ac0aa..3149fc62 100644 --- a/c-level-advisor/c-level-agents/agents/cs-chief-of-staff.md +++ b/c-level-advisor/c-level-agents/agents/cs-chief-of-staff.md @@ -29,8 +29,8 @@ This is the agent the founder talks to **first**. It pulls company-context.md, p ### Knowledge Bases -- `../../skills/chief-of-staff/references/routing_logic.md` — keywords → role mapping, multi-role triggers -- `../../skills/chief-of-staff/references/synthesis_patterns.md` — how to combine inputs from multiple advisors +- `../../skills/chief-of-staff/references/routing-matrix.md` — keywords → role mapping, multi-role triggers +- `../../skills/chief-of-staff/references/synthesis-framework.md` — how to combine inputs from multiple advisors ### Coordination Skills @@ -119,7 +119,7 @@ echo "Decision logged to ~/.claude/decisions/raw/$(date +%Y-%m-%d)-$RANDOM.md" ## Related Agents - All cs-* C-level advisors (routes to them) -- [cs-ceo-advisor](../../../../agents/c-level/cs-ceo-advisor.md) — primary upward report +- [cs-ceo-advisor](../../../agents/c-level/cs-ceo-advisor.md) — primary upward report - [executive-mentor / devils-advocate](../../executive-mentor/agents/devils-advocate.md) — pre-decision adversarial check ## References diff --git a/c-level-advisor/c-level-agents/agents/cs-chro-advisor.md b/c-level-advisor/c-level-agents/agents/cs-chro-advisor.md index fbc36e91..0776beb4 100644 --- a/c-level-advisor/c-level-agents/agents/cs-chro-advisor.md +++ b/c-level-advisor/c-level-agents/agents/cs-chro-advisor.md @@ -39,9 +39,9 @@ Pairs with `cs-coo-advisor` (org design), `cs-cfo-advisor` (comp budget), and `c ### Knowledge Bases -- `../../skills/chro-advisor/references/hiring_systems.md` — sourcing channels, interview rubrics, scorecards, time-to-fill -- `../../skills/chro-advisor/references/comp_philosophy.md` — band design, equity strategy, refresh policy -- `../../skills/chro-advisor/references/leveling_ladders.md` — IC + manager tracks, level expectations, promotion criteria +- `../../skills/chro-advisor/references/people_strategy.md` — sourcing channels, interview rubrics, scorecards, time-to-fill +- `../../skills/chro-advisor/references/comp_frameworks.md` — band design, equity strategy, refresh policy +- `../../skills/chro-advisor/references/org_design.md` — IC + manager tracks, level expectations, promotion criteria ## Workflows @@ -92,7 +92,7 @@ python ../../skills/chro-advisor/scripts/hiring_plan_modeler.py echo "👥 CHRO Quarterly Review" python ../../skills/chro-advisor/scripts/hiring_plan_modeler.py python ../../skills/chro-advisor/scripts/comp_benchmarker.py -echo "Ladder reference: ../../skills/chro-advisor/references/leveling_ladders.md" +echo "Ladder reference: ../../skills/chro-advisor/references/org_design.md" ``` ## Success Metrics @@ -107,8 +107,8 @@ echo "Ladder reference: ../../skills/chro-advisor/references/leveling_ladders.md - [cs-coo-advisor](cs-coo-advisor.md) — org design partner - [cs-cfo-advisor](cs-cfo-advisor.md) — comp budget -- [cs-ceo-advisor](../../../../agents/c-level/cs-ceo-advisor.md) — exec team -- [cs-workspace-admin](../../../../agents/engineering-team/cs-workspace-admin.md) — onboarding tooling +- [cs-ceo-advisor](../../../agents/c-level/cs-ceo-advisor.md) — exec team +- [cs-workspace-admin](../../../agents/engineering-team/cs-workspace-admin.md) — onboarding tooling ## References diff --git a/c-level-advisor/c-level-agents/agents/cs-ciso-advisor.md b/c-level-advisor/c-level-agents/agents/cs-ciso-advisor.md index d4ae4fed..b3ed0303 100644 --- a/c-level-advisor/c-level-agents/agents/cs-ciso-advisor.md +++ b/c-level-advisor/c-level-agents/agents/cs-ciso-advisor.md @@ -39,7 +39,7 @@ Pairs with `cs-cto-advisor` (security architecture), `cs-cfo-advisor` (risk quan ### Knowledge Bases -- `../../skills/ciso-advisor/references/threat_modeling.md` — STRIDE, PASTA, attacker journey +- `../../skills/ciso-advisor/references/security_strategy.md` — STRIDE, PASTA, attacker journey - `../../skills/ciso-advisor/references/compliance_roadmap.md` — SOC 2 Type 2, ISO 27001, GDPR sequencing - `../../skills/ciso-advisor/references/incident_response.md` — IR runbooks, comms plan, regulator notification windows @@ -110,10 +110,10 @@ echo "IR runbook check: ../../skills/ciso-advisor/references/incident_response.m ## Related Agents -- [cs-cto-advisor](../../../../agents/c-level/cs-cto-advisor.md) — security architecture +- [cs-cto-advisor](../../../agents/c-level/cs-cto-advisor.md) — security architecture - [cs-cfo-advisor](cs-cfo-advisor.md) — risk → insurance, audit budget -- [cs-quality-regulatory](../../../../agents/ra-qm-team/cs-quality-regulatory.md) — ISO 27001, GDPR execution -- [cs-senior-engineer](../../../../agents/engineering/cs-senior-engineer.md) — secure coding +- [cs-quality-regulatory](../../../agents/ra-qm-team/cs-quality-regulatory.md) — ISO 27001, GDPR execution +- [cs-senior-engineer](../../../agents/engineering/cs-senior-engineer.md) — secure coding ## References diff --git a/c-level-advisor/c-level-agents/agents/cs-cmo-advisor.md b/c-level-advisor/c-level-agents/agents/cs-cmo-advisor.md index ea6f4d26..0b8d6f3e 100644 --- a/c-level-advisor/c-level-agents/agents/cs-cmo-advisor.md +++ b/c-level-advisor/c-level-agents/agents/cs-cmo-advisor.md @@ -40,8 +40,8 @@ Pairs with `cs-cpo-advisor` (positioning ↔ product), `cs-cro-advisor` (positio ### Knowledge Bases - `../../skills/cmo-advisor/references/brand_positioning.md` — category design, message house, narrative arcs -- `../../skills/cmo-advisor/references/growth_playbooks.md` — channel-specific motions, PLG vs sales-led -- `../../skills/cmo-advisor/references/marketing_operations.md` — attribution, cadence, content ops +- `../../skills/cmo-advisor/references/growth_frameworks.md` — channel-specific motions, PLG vs sales-led +- `../../skills/cmo-advisor/references/marketing_org.md` — attribution, cadence, content ops ### Adjacent Execution @@ -111,8 +111,8 @@ echo "📚 Reference: positioning + playbooks" - [cs-cpo-advisor](cs-cpo-advisor.md) — positioning ↔ product alignment - [cs-cro-advisor](cs-cro-advisor.md) — pipeline contribution -- [cs-content-creator](../../../../agents/marketing/cs-content-creator.md) — execution -- [cs-demand-gen-specialist](../../../../agents/marketing/cs-demand-gen-specialist.md) — execution +- [cs-content-creator](../../../agents/marketing/cs-content-creator.md) — execution +- [cs-demand-gen-specialist](../../../agents/marketing/cs-demand-gen-specialist.md) — execution ## References diff --git a/c-level-advisor/c-level-agents/agents/cs-coo-advisor.md b/c-level-advisor/c-level-agents/agents/cs-coo-advisor.md index 9b64fae1..443116d6 100644 --- a/c-level-advisor/c-level-agents/agents/cs-coo-advisor.md +++ b/c-level-advisor/c-level-agents/agents/cs-coo-advisor.md @@ -39,9 +39,9 @@ Pairs with `cs-cfo-advisor` (finance cadence), `cs-cro-advisor` (revenue cadence ### Knowledge Bases -- `../../skills/coo-advisor/references/operating_cadence.md` — weekly/monthly/quarterly rhythm, meeting design -- `../../skills/coo-advisor/references/okr_execution.md` — OKR design, scoring, cascading -- `../../skills/coo-advisor/references/scaling_playbooks.md` — 1-10, 10-100, 100-1000 transitions +- `../../skills/coo-advisor/references/ops_cadence.md` — weekly/monthly/quarterly rhythm, meeting design +- `../../skills/coo-advisor/references/process_frameworks.md` — OKR design, scoring, cascading +- `../../skills/coo-advisor/references/scaling_playbook.md` — 1-10, 10-100, 100-1000 transitions ### Adjacent Skills @@ -97,7 +97,7 @@ python ../../skills/coo-advisor/scripts/okr_tracker.py echo "⚙️ COO Quarterly Review" python ../../skills/coo-advisor/scripts/okr_tracker.py python ../../skills/coo-advisor/scripts/ops_efficiency_analyzer.py -echo "Reference: ../../skills/coo-advisor/references/operating_cadence.md" +echo "Reference: ../../skills/coo-advisor/references/ops_cadence.md" ``` ## Success Metrics @@ -113,7 +113,7 @@ echo "Reference: ../../skills/coo-advisor/references/operating_cadence.md" - [cs-cfo-advisor](cs-cfo-advisor.md) — finance cadence - [cs-cro-advisor](cs-cro-advisor.md) — revenue cadence - [cs-chief-of-staff](cs-chief-of-staff.md) — decision logging -- [cs-engineering-lead](../../../../agents/engineering-team/cs-engineering-lead.md) — eng ops +- [cs-engineering-lead](../../../agents/engineering-team/cs-engineering-lead.md) — eng ops ## References diff --git a/c-level-advisor/c-level-agents/agents/cs-cpo-advisor.md b/c-level-advisor/c-level-agents/agents/cs-cpo-advisor.md index 9e3aa06d..e2116d57 100644 --- a/c-level-advisor/c-level-agents/agents/cs-cpo-advisor.md +++ b/c-level-advisor/c-level-agents/agents/cs-cpo-advisor.md @@ -39,13 +39,13 @@ Pairs with `cs-cmo-advisor` (positioning ↔ product), `cs-cro-advisor` (win/los ### Knowledge Bases -- `../../skills/cpo-advisor/references/product_vision.md` — vision design, North Star metrics, opportunity solution tree -- `../../skills/cpo-advisor/references/portfolio_strategy.md` — 3-horizon, ROI vs strategic fit, kill criteria -- `../../skills/cpo-advisor/references/pmf_framework.md` — Sean Ellis, retention, organic pull, what PMF actually looks like +- `../../skills/cpo-advisor/references/product_strategy.md` — vision design, North Star metrics, opportunity solution tree +- `../../skills/cpo-advisor/references/product_org_design.md` — 3-horizon, ROI vs strategic fit, kill criteria +- `../../skills/cpo-advisor/references/pmf_playbook.md` — Sean Ellis, retention, organic pull, what PMF actually looks like ### Adjacent Execution -- `../../../../product-team/product-manager-toolkit/` — RICE, OKR cascade, user stories +- `../../../product-team/skills/product-manager-toolkit/` — RICE, OKR cascade, user stories ## Workflows @@ -96,7 +96,7 @@ python ../../skills/cpo-advisor/scripts/pmf_scorer.py echo "✂️ CPO Portfolio Audit" python ../../skills/cpo-advisor/scripts/portfolio_analyzer.py python ../../skills/cpo-advisor/scripts/pmf_scorer.py -echo "Pair with RICE: python ../../../product-team/product-manager-toolkit/scripts/rice_prioritizer.py" +echo "Pair with RICE: python ../../../product-team/skills/product-manager-toolkit/scripts/rice_prioritizer.py" ``` ## Success Metrics @@ -111,8 +111,8 @@ echo "Pair with RICE: python ../../../product-team/product-manager-toolkit/scrip - [cs-cmo-advisor](cs-cmo-advisor.md) — positioning alignment - [cs-cro-advisor](cs-cro-advisor.md) — win/loss feedback -- [cs-product-manager](../../../../agents/product/cs-product-manager.md) — execution -- [cs-product-strategist](../../../../agents/product/cs-product-strategist.md) — OKR cascade +- [cs-product-manager](../../../agents/product/cs-product-manager.md) — execution +- [cs-product-strategist](../../../agents/product/cs-product-strategist.md) — OKR cascade ## References diff --git a/c-level-advisor/c-level-agents/agents/cs-cro-advisor.md b/c-level-advisor/c-level-agents/agents/cs-cro-advisor.md index d191d8ec..0a16b2e5 100644 --- a/c-level-advisor/c-level-agents/agents/cs-cro-advisor.md +++ b/c-level-advisor/c-level-agents/agents/cs-cro-advisor.md @@ -39,9 +39,9 @@ Pairs with `cs-cfo-advisor` (revenue → cash conversion), `cs-cmo-advisor` (pip ### Knowledge Bases -- `../../skills/cro-advisor/references/revenue_operations.md` — pipeline cadence, win/loss process, forecasting hygiene -- `../../skills/cro-advisor/references/sales_motion.md` — PLG vs sales-led, hiring profiles, ramp curves -- `../../skills/cro-advisor/references/retention_expansion.md` — NRR levers, customer success cadence, expansion plays +- `../../skills/cro-advisor/references/sales_playbook.md` — pipeline cadence, win/loss process, forecasting hygiene +- `../../skills/cro-advisor/references/pricing_strategy.md` — PLG vs sales-led, hiring profiles, ramp curves +- `../../skills/cro-advisor/references/nrr_playbook.md` — NRR levers, customer success cadence, expansion plays ## Workflows @@ -109,7 +109,7 @@ echo "Pipeline coverage and retention dashboard ready." - [cs-cfo-advisor](cs-cfo-advisor.md) — revenue → cash conversion - [cs-cmo-advisor](cs-cmo-advisor.md) — pipeline contribution - [cs-cpo-advisor](cs-cpo-advisor.md) — product gaps in win/loss -- [cs-growth-strategist](../../../../agents/business-growth/cs-growth-strategist.md) — execution +- [cs-growth-strategist](../../../agents/business-growth/cs-growth-strategist.md) — execution ## References diff --git a/c-level-advisor/c-level-agents/agents/cs-general-counsel-advisor.md b/c-level-advisor/c-level-agents/agents/cs-general-counsel-advisor.md index 36507c69..bc90a4e9 100644 --- a/c-level-advisor/c-level-agents/agents/cs-general-counsel-advisor.md +++ b/c-level-advisor/c-level-agents/agents/cs-general-counsel-advisor.md @@ -152,8 +152,8 @@ echo " ☐ /cs:freeze applied if irreversible (term sheet, M&A LOI, employment - [cs-cfo-advisor](cs-cfo-advisor.md) — term sheet → dilution math - [cs-ciso-advisor](cs-ciso-advisor.md) — data-touching contracts, compliance overlap -- [cs-ceo-advisor](../../../../agents/c-level/cs-ceo-advisor.md) — board / fundraising strategic context -- [cs-quality-regulatory](../../../../agents/ra-qm-team/cs-quality-regulatory.md) — regulated-industry execution (ISO 13485, MDR, FDA) +- [cs-ceo-advisor](../../../agents/c-level/cs-ceo-advisor.md) — board / fundraising strategic context +- [cs-quality-regulatory](../../../agents/ra-qm-team/cs-quality-regulatory.md) — regulated-industry execution (ISO 13485, MDR, FDA) ## References diff --git a/c-level-advisor/c-level-agents/agents/cs-vpe-advisor.md b/c-level-advisor/c-level-agents/agents/cs-vpe-advisor.md index 1d65ae86..96bdcf04 100644 --- a/c-level-advisor/c-level-agents/agents/cs-vpe-advisor.md +++ b/c-level-advisor/c-level-agents/agents/cs-vpe-advisor.md @@ -145,11 +145,11 @@ python ../../skills/vpe-advisor/scripts/eng_team_structure_designer.py current-t ## Related Agents -- [cs-cto-advisor](../../../../agents/c-level/cs-cto-advisor.md) — Architecture, scaling cliffs (CTO decides what to build; VPE decides how to ship) +- [cs-cto-advisor](../../../agents/c-level/cs-cto-advisor.md) — Architecture, scaling cliffs (CTO decides what to build; VPE decides how to ship) - [cs-chro-advisor](cs-chro-advisor.md) — Hiring systems (ladders, bands) - [cs-coo-advisor](cs-coo-advisor.md) — Operating cadence company-wide - [cs-cfo-advisor](cs-cfo-advisor.md) — Cost-per-hire envelope, eng budget -- [cs-engineering-lead](../../../../agents/engineering-team/cs-engineering-lead.md) — Day-to-day incident + on-call coordination +- [cs-engineering-lead](../../../agents/engineering-team/cs-engineering-lead.md) — Day-to-day incident + on-call coordination ## References diff --git a/c-level-advisor/c-level-agents/skills/boardroom/SKILL.md b/c-level-advisor/c-level-agents/skills/boardroom/SKILL.md index d2fec095..d969594d 100644 --- a/c-level-advisor/c-level-agents/skills/boardroom/SKILL.md +++ b/c-level-advisor/c-level-agents/skills/boardroom/SKILL.md @@ -1,6 +1,6 @@ --- name: "boardroom" -description: "/cs:boardroom — 6-phase multi-role deliberation across the C-suite with Phase 2 isolation, critic pre-screen, and synthesis. Outputs a board memo." +description: "/cs:boardroom — 6-phase multi-role deliberation across the C-suite with Phase 2 isolation, critic pre-screen, and synthesis. Outputs a board memo. Use when a decision spans multiple executive domains — e.g. a pricing change touching finance, positioning, and product, or a raise-vs-cut runway call." --- # /cs:boardroom — Multi-Role Boardroom Deliberation diff --git a/c-level-advisor/c-level-agents/skills/brief/SKILL.md b/c-level-advisor/c-level-agents/skills/brief/SKILL.md index 61f98d50..aa5f7a8a 100644 --- a/c-level-advisor/c-level-agents/skills/brief/SKILL.md +++ b/c-level-advisor/c-level-agents/skills/brief/SKILL.md @@ -1,6 +1,6 @@ --- name: "brief" -description: "/cs:brief — Generate a one-page strategy brief from an office-hours intake. First step in the strategic sprint pipeline." +description: "/cs:brief — Generate a one-page strategy brief from an office-hours intake. First step in the strategic sprint pipeline. Use when a strategic question needs to be framed before boardroom deliberation — e.g. locking options, assumptions, and success criteria for a pricing change or a market-entry decision." --- # /cs:brief — One-Page Strategy Brief @@ -68,6 +68,11 @@ A single Markdown file under `~/.claude/briefs/YYYY-MM-DD-.md` with this s - [ ] cs-coo-advisor - [ ] cs-chro-advisor - [ ] cs-ciso-advisor +- [ ] cs-general-counsel-advisor +- [ ] cs-cdo-advisor +- [ ] cs-caio-advisor +- [ ] cs-cco-advisor +- [ ] cs-vpe-advisor - [ ] cs-chief-of-staff ## Success Criteria diff --git a/c-level-advisor/c-level-agents/skills/c-level-agents/SKILL.md b/c-level-advisor/c-level-agents/skills/c-level-agents/SKILL.md index 4972955b..ca59e815 100644 --- a/c-level-advisor/c-level-agents/skills/c-level-agents/SKILL.md +++ b/c-level-advisor/c-level-agents/skills/c-level-agents/SKILL.md @@ -1,6 +1,6 @@ --- name: "c-level-agents" -description: "Founder-mode executive team. 8 cs-* C-suite agents (CFO, CMO, CRO, CPO, COO, CHRO, CISO, Chief of Staff) and 17 /cs:* slash commands for forcing-question office hours, multi-role boardroom deliberation, strategic sprint pipeline, and meta routing. Use when the founder needs a virtual executive team, when invoking /cs:* commands, or when orchestrating multi-role decisions." +description: "Founder-mode executive team. 13 cs-* C-suite agents (CFO, CMO, CRO, CPO, COO, CHRO, CISO, GC, CDO, CAIO, CCO, VPE, Chief of Staff) and 21 /cs:* slash commands for forcing-question office hours, multi-role boardroom deliberation, strategic sprint pipeline, and meta routing. Use when the founder needs a virtual executive team, when invoking /cs:* commands, or when orchestrating multi-role decisions." license: MIT metadata: version: 1.0.0 @@ -8,8 +8,8 @@ metadata: category: c-level domain: executive-orchestration updated: 2026-05-12 - agents: cs-cfo-advisor, cs-cmo-advisor, cs-cro-advisor, cs-cpo-advisor, cs-coo-advisor, cs-chro-advisor, cs-ciso-advisor, cs-chief-of-staff - commands: cs-office-hours, cs-cfo-review, cs-cmo-review, cs-cpo-review, cs-cro-review, cs-cto-review, cs-ciso-review, cs-gc-review, cs-brief, cs-boardroom, cs-decide, cs-execute, cs-post-mortem, cs-founder-mode, cs-onboard, cs-cross-eval, cs-freeze + agents: cs-cfo-advisor, cs-cmo-advisor, cs-cro-advisor, cs-cpo-advisor, cs-coo-advisor, cs-chro-advisor, cs-ciso-advisor, cs-general-counsel-advisor, cs-cdo-advisor, cs-caio-advisor, cs-cco-advisor, cs-vpe-advisor, cs-chief-of-staff + commands: cs-office-hours, cs-cfo-review, cs-cmo-review, cs-cpo-review, cs-cro-review, cs-cto-review, cs-ciso-review, cs-gc-review, cs-cdo-review, cs-caio-review, cs-cco-review, cs-vpe-review, cs-brief, cs-boardroom, cs-decide, cs-execute, cs-post-mortem, cs-founder-mode, cs-onboard, cs-cross-eval, cs-freeze --- # c-level-agents — Founder-Mode Executive Team @@ -22,7 +22,7 @@ founder mode, virtual c-suite, executive team, boardroom, office hours, cfo revi ## What This Plugin Provides -### 8 cs-* Agents (in `agents/`) +### 13 cs-* Agents (in `agents/`) Each agent wraps an existing c-level skill and adds: - A distinct cognitive voice (numerate skeptic, narrative-first, etc.) @@ -30,11 +30,11 @@ Each agent wraps an existing c-level skill and adds: - Workflow orchestration tied to skill Python tools - Output template: Bottom Line → What → Why → How to Act → Your Decision -See `../references/persona-voices.md` for voice specs. +See `../../references/persona-voices.md` for voice specs. -### 17 /cs:* Slash Commands (in `skills/`) +### 21 /cs:* Slash Commands (in `skills/`) -**Forcing-question office hours (8):** +**Forcing-question office hours (12):** - `/cs:office-hours` — YC-style 6-question intake - `/cs:cfo-review` — unit economics, runway, dilution - `/cs:cmo-review` — ICP, CAC payback, positioning @@ -43,6 +43,10 @@ See `../references/persona-voices.md` for voice specs. - `/cs:cto-review` — architecture risk, scaling cliff - `/cs:ciso-review` — threat model, blast radius, compliance - `/cs:gc-review` — contracts, IP, regulatory, term sheets +- `/cs:cdo-review` — training-data rights, data products, data assets +- `/cs:caio-review` — model selection, evals, AI risk, AI costs +- `/cs:cco-review` — GRR/NRR decomposition, churn root cause, CS coverage +- `/cs:vpe-review` — DORA metrics, cycle time, eng hiring funnel, team structure **Strategic sprint pipeline (5):** - `/cs:brief` → `/cs:boardroom` → `/cs:decide` → `/cs:execute` → `/cs:post-mortem` @@ -86,11 +90,11 @@ User question ## Integration Points -- **Existing 28 c-level skills** — wrapped, not replaced +- **Existing 33 c-level skills** — wrapped, not replaced - **decision-logger** — every `/cs:decide` writes here - **chief-of-staff** — routing layer the agent orchestrates - **board-meeting** — protocol the `/cs:boardroom` command runs -- **llm-wiki** — optional persistent memory bridge (see `../references/llm-wiki-bridge.md`) +- **llm-wiki** — optional persistent memory bridge (see `../../references/llm-wiki-bridge.md`) - **executive-mentor** — adversarial `/em:*` commands stack cleanly on top ## Design Principles diff --git a/c-level-advisor/c-level-agents/skills/caio-review/SKILL.md b/c-level-advisor/c-level-agents/skills/caio-review/SKILL.md index ae62b020..dd135a23 100644 --- a/c-level-advisor/c-level-agents/skills/caio-review/SKILL.md +++ b/c-level-advisor/c-level-agents/skills/caio-review/SKILL.md @@ -1,6 +1,6 @@ --- name: "caio-review" -description: "/cs:caio-review — Eval-demanding Chief AI Officer interrogation of any plan that involves AI: model selection, risk classification, cost economics, or AI hiring." +description: "/cs:caio-review — Eval-demanding Chief AI Officer interrogation of any plan that involves AI: model selection, risk classification, cost economics, or AI hiring. Use when shipping an AI feature without an eval set, choosing between API, fine-tune, and self-hosted, or classifying a use case under the EU AI Act." --- # /cs:caio-review — CAIO Forcing Questions @@ -125,7 +125,7 @@ python ../../../skills/chief-ai-officer-advisor/scripts/ai_cost_economics.py wor - `/cs:gc-review` — for AI vendor contracts, output liability, training-data licensing - `/cs:ciso-review` — for prompt injection / jailbreak / training-data poisoning threat model - `/cs:cfo-review` — for multi-year vendor or GPU commitment TCO -- `/cs:chro-review` — for AI team hires (comp, ladder, leveling) +- `cs-chro-advisor` agent — for AI team hires (comp, ladder, leveling) - `/cs:decide` — log the verdict - `/cs:freeze 60` — on multi-year AI commitments diff --git a/c-level-advisor/c-level-agents/skills/cco-review/SKILL.md b/c-level-advisor/c-level-agents/skills/cco-review/SKILL.md index b3af502f..9de92d43 100644 --- a/c-level-advisor/c-level-agents/skills/cco-review/SKILL.md +++ b/c-level-advisor/c-level-agents/skills/cco-review/SKILL.md @@ -1,6 +1,6 @@ --- name: "cco-review" -description: "/cs:cco-review — Retention-obsessed Chief Customer Officer interrogation of any plan that touches customer retention, segmentation, CS team sizing, or CS team hiring." +description: "/cs:cco-review — Retention-obsessed Chief Customer Officer interrogation of any plan that touches customer retention, segmentation, CS team sizing, or CS team hiring. Use when gross retention is slipping, before approving CSM headcount, or when deciding which customer segments to keep or fire." --- # /cs:cco-review — CCO Forcing Questions @@ -115,7 +115,7 @@ python ../../../skills/chief-customer-officer-advisor/scripts/cs_coverage_calcul - `/cs:cpo-review` — if churn root cause is product_fit or no_value_realized - `/cs:cro-review` — if expansion math or comp alignment is in question - `/cs:cfo-review` — for CS cost commitments and retention-impact-on-revenue -- `/cs:chro-review` — for CS hires, comp, ladder +- `cs-chro-advisor` agent — for CS hires, comp, ladder - `/cs:decide` — log the verdict - `/cs:freeze 30` — on multi-year CS comp plan changes diff --git a/c-level-advisor/c-level-agents/skills/cdo-review/SKILL.md b/c-level-advisor/c-level-agents/skills/cdo-review/SKILL.md index f5d3aaba..b962d71d 100644 --- a/c-level-advisor/c-level-agents/skills/cdo-review/SKILL.md +++ b/c-level-advisor/c-level-agents/skills/cdo-review/SKILL.md @@ -1,6 +1,6 @@ --- name: "cdo-review" -description: "/cs:cdo-review — Decision-driven Chief Data Officer interrogation of any plan that touches training data, data architecture, data productization, or data team hiring." +description: "/cs:cdo-review — Decision-driven Chief Data Officer interrogation of any plan that touches training data, data architecture, data productization, or data team hiring. Use when validating training-data rights before model work, choosing warehouse vs lakehouse vs mesh, or valuing data assets for productization or M&A." --- # /cs:cdo-review — CDO Forcing Questions @@ -111,7 +111,7 @@ python ../../../skills/chief-data-officer-advisor/scripts/data_asset_valuator.py - `/cs:gc-review` — for any productization or licensing path - `/cs:ciso-review` — for any architecture change touching customer data - `/cs:cfo-review` — for build-vs-buy TCO and M&A valuation math -- `/cs:chro-review` — for data team hires (comp, ladder, leveling) +- `cs-chro-advisor` agent — for data team hires (comp, ladder, leveling) - `/cs:decide` — log the verdict - `/cs:freeze 90` — on multi-year infrastructure contracts diff --git a/c-level-advisor/c-level-agents/skills/cfo-review/SKILL.md b/c-level-advisor/c-level-agents/skills/cfo-review/SKILL.md index 526fa37f..bc59bd04 100644 --- a/c-level-advisor/c-level-agents/skills/cfo-review/SKILL.md +++ b/c-level-advisor/c-level-agents/skills/cfo-review/SKILL.md @@ -1,6 +1,6 @@ --- name: "cfo-review" -description: "/cs:cfo-review — Numerate-skeptic interrogation of any plan that touches money. Unit economics, runway, dilution, capital allocation." +description: "/cs:cfo-review — Numerate-skeptic interrogation of any plan that touches money. Unit economics, runway, dilution, capital allocation. Use when a plan commits meaningful spend — e.g. a hiring wave, a fundraise decision, or a new channel budget." --- # /cs:cfo-review — CFO Forcing Questions diff --git a/c-level-advisor/c-level-agents/skills/ciso-review/SKILL.md b/c-level-advisor/c-level-agents/skills/ciso-review/SKILL.md index 607040c8..db874772 100644 --- a/c-level-advisor/c-level-agents/skills/ciso-review/SKILL.md +++ b/c-level-advisor/c-level-agents/skills/ciso-review/SKILL.md @@ -1,6 +1,6 @@ --- name: "ciso-review" -description: "/cs:ciso-review — Risk-paranoid interrogation of any plan that touches data, compliance, or production access." +description: "/cs:ciso-review — Risk-paranoid interrogation of any plan that touches data, compliance, or production access. Use when launching features that handle customer data, before a SOC 2 / ISO audit, or after any incident or near-miss." --- # /cs:ciso-review — CISO Forcing Questions diff --git a/c-level-advisor/c-level-agents/skills/cmo-review/SKILL.md b/c-level-advisor/c-level-agents/skills/cmo-review/SKILL.md index f0c13f65..755ae792 100644 --- a/c-level-advisor/c-level-agents/skills/cmo-review/SKILL.md +++ b/c-level-advisor/c-level-agents/skills/cmo-review/SKILL.md @@ -1,6 +1,6 @@ --- name: "cmo-review" -description: "/cs:cmo-review — Narrative-first interrogation of positioning, ICP, message house, and channel mix." +description: "/cs:cmo-review — Narrative-first interrogation of positioning, ICP, message house, and channel mix. Use when launching a campaign or repositioning, or when CAC is rising and the one-sentence positioning test fails." --- # /cs:cmo-review — CMO Forcing Questions diff --git a/c-level-advisor/c-level-agents/skills/cpo-review/SKILL.md b/c-level-advisor/c-level-agents/skills/cpo-review/SKILL.md index c8613c21..1e32640f 100644 --- a/c-level-advisor/c-level-agents/skills/cpo-review/SKILL.md +++ b/c-level-advisor/c-level-agents/skills/cpo-review/SKILL.md @@ -1,6 +1,6 @@ --- name: "cpo-review" -description: "/cs:cpo-review — JTBD-driven interrogation of product roadmap, PMF signal, and portfolio focus." +description: "/cs:cpo-review — JTBD-driven interrogation of product roadmap, PMF signal, and portfolio focus. Use when committing a quarter's roadmap, deciding whether to kill a feature, or claiming PMF without a retention curve." --- # /cs:cpo-review — CPO Forcing Questions @@ -37,7 +37,7 @@ The JTBD-driven builder cuts the roadmap in half. Six questions to surface what ### 4. RICE Score **Reach, Impact, Confidence, Effort — what's the score and where does this rank in the queue?** ```bash -python ../../../../product-team/product-manager-toolkit/scripts/rice_prioritizer.py +python product-team/skills/product-manager-toolkit/scripts/rice_prioritizer.py ``` ### 5. Opportunity Cost @@ -103,7 +103,7 @@ python ../../../../product-team/product-manager-toolkit/scripts/rice_prioritizer - Agent: [`cs-cpo-advisor`](../../agents/cs-cpo-advisor.md) - Skill: [`cpo-advisor`](../../../skills/cpo-advisor/SKILL.md) -- Execution: `../../../../product-team/product-manager-toolkit/` +- Execution: `product-team/skills/product-manager-toolkit/` --- diff --git a/c-level-advisor/c-level-agents/skills/cro-review/SKILL.md b/c-level-advisor/c-level-agents/skills/cro-review/SKILL.md index 169d32ca..b3f068d2 100644 --- a/c-level-advisor/c-level-agents/skills/cro-review/SKILL.md +++ b/c-level-advisor/c-level-agents/skills/cro-review/SKILL.md @@ -1,6 +1,6 @@ --- name: "cro-review" -description: "/cs:cro-review — Pipeline-paranoid interrogation of revenue, win rate, NRR, and ramp time." +description: "/cs:cro-review — Pipeline-paranoid interrogation of revenue, win rate, NRR, and ramp time. Use when the forecast misses pipeline coverage, win rates drop, or before scaling the sales team." --- # /cs:cro-review — CRO Forcing Questions diff --git a/c-level-advisor/c-level-agents/skills/cross-eval/SKILL.md b/c-level-advisor/c-level-agents/skills/cross-eval/SKILL.md index 578a2781..5b7936fa 100644 --- a/c-level-advisor/c-level-agents/skills/cross-eval/SKILL.md +++ b/c-level-advisor/c-level-agents/skills/cross-eval/SKILL.md @@ -1,6 +1,6 @@ --- name: "cross-eval" -description: "/cs:cross-eval — Multi-model consensus on a board memo or strategy brief. Claude + Codex + Gemini cross-review with graceful degradation." +description: "/cs:cross-eval — Multi-model consensus on a board memo or strategy brief. Claude + Codex + Gemini cross-review with graceful degradation. Use when a high-stakes memo needs an independent sanity check before the boardroom — e.g. a bet-the-company pivot or fundraise terms." --- # /cs:cross-eval — Multi-Model Consensus diff --git a/c-level-advisor/c-level-agents/skills/cto-review/SKILL.md b/c-level-advisor/c-level-agents/skills/cto-review/SKILL.md index 26850b60..e28ee69a 100644 --- a/c-level-advisor/c-level-agents/skills/cto-review/SKILL.md +++ b/c-level-advisor/c-level-agents/skills/cto-review/SKILL.md @@ -1,6 +1,6 @@ --- name: "cto-review" -description: "/cs:cto-review — Architecture and scaling interrogation. Tech debt, scaling cliffs, team scaling, build-vs-buy." +description: "/cs:cto-review — Architecture and scaling interrogation. Tech debt, scaling cliffs, team scaling, build-vs-buy. Use when committing to an architecture, planning for 10x load, or weighing a rebuild against a vendor." --- # /cs:cto-review — CTO Forcing Questions diff --git a/c-level-advisor/c-level-agents/skills/decide/SKILL.md b/c-level-advisor/c-level-agents/skills/decide/SKILL.md index e081111d..43d5b54b 100644 --- a/c-level-advisor/c-level-agents/skills/decide/SKILL.md +++ b/c-level-advisor/c-level-agents/skills/decide/SKILL.md @@ -1,6 +1,6 @@ --- name: "decide" -description: "/cs:decide — Log a decision to two-layer memory via decision-logger. Approved memo becomes durable; raw transcripts kept for reference." +description: "/cs:decide — Log a decision to two-layer memory via decision-logger. Approved memo becomes durable; raw transcripts kept for reference. Use when the founder has approved a boardroom memo and the decision must become durable company memory — e.g. right after /cs:boardroom concludes." --- # /cs:decide — Log the Decision diff --git a/c-level-advisor/c-level-agents/skills/execute/SKILL.md b/c-level-advisor/c-level-agents/skills/execute/SKILL.md index e3897d4b..dce7266d 100644 --- a/c-level-advisor/c-level-agents/skills/execute/SKILL.md +++ b/c-level-advisor/c-level-agents/skills/execute/SKILL.md @@ -1,6 +1,6 @@ --- name: "execute" -description: "/cs:execute — Generate a 90-day execution plan with weekly milestones, DRIs, and check-in cadence from an approved decision." +description: "/cs:execute — Generate a 90-day execution plan with weekly milestones, DRIs, and check-in cadence from an approved decision. Use when a logged decision needs to become an operating plan — e.g. turning an approved market-entry call into weekly milestones with DRIs." --- # /cs:execute — 90-Day Execution Plan diff --git a/c-level-advisor/c-level-agents/skills/founder-mode/SKILL.md b/c-level-advisor/c-level-agents/skills/founder-mode/SKILL.md index 2f3203a6..89fbba96 100644 --- a/c-level-advisor/c-level-agents/skills/founder-mode/SKILL.md +++ b/c-level-advisor/c-level-agents/skills/founder-mode/SKILL.md @@ -1,6 +1,6 @@ --- name: "founder-mode" -description: "/cs:founder-mode — Auto-routes any founder question to the right C-role advisor or to /cs:boardroom for multi-role topics. The single-command entry point." +description: "/cs:founder-mode — Auto-routes any founder question to the right C-role advisor or to /cs:boardroom for multi-role topics. The single-command entry point. Use when a founder asks any strategic question without knowing which advisor or command fits — e.g. 'runway pressure' routes to the CFO, 'gross retention dropped' routes to the CCO." --- # /cs:founder-mode — The Auto-Router @@ -18,14 +18,18 @@ The router (via `cs-chief-of-staff`) does keyword + intent matching: | Signal in question | Route | |---|---| | burn, runway, fundraise, dilution, model, LTV, CAC | `cs-cfo-advisor` | -| pipeline, win rate, forecast, NRR, churn, ramp | `cs-cro-advisor` | +| pipeline, win rate, forecast, quota, ramp, sales motion | `cs-cro-advisor` | | positioning, ICP, message, brand, channel, campaign | `cs-cmo-advisor` | | roadmap, PMF, JTBD, North Star, RICE, kill | `cs-cpo-advisor` | | cadence, OKR, scorecard, DRI, operating system, rhythm | `cs-coo-advisor` | | hiring, comp, ladder, level, attrition, eNPS, equity | `cs-chro-advisor` | | security, threat, breach, compliance, audit, SOC 2 | `cs-ciso-advisor` | | architecture, scaling, tech debt, SLO, latency | `cs-cto-advisor` | -| contract, IP, term sheet, regulator, license | `/cs:gc-review` | +| contract, IP, term sheet, regulator, license | `cs-general-counsel-advisor` | +| retention, GRR, NRR, churn, customer success, CSM, time-to-value, renewals | `cs-cco-advisor` | +| training data, data rights, consent, data asset, warehouse, lakehouse, data mesh | `cs-cdo-advisor` | +| model selection, eval, hallucination, AI risk, EU AI Act, fine-tune, build vs buy AI | `cs-caio-advisor` | +| DORA, cycle time, deploy frequency, eng hiring funnel, team topology, delivery throughput | `cs-vpe-advisor` | | strategy, vision, board, M&A, raise, exit | `cs-ceo-advisor` | | **2+ signals from different roles** | `/cs:boardroom` | | **ambiguous** | `/cs:office-hours` first, then route | @@ -83,6 +87,9 @@ gstack requires the founder to know all 23 slash commands and pick the right one /cs:founder-mode "the win rate dropped 20% this month" → cs-cro-advisor +/cs:founder-mode "gross retention dropped 5 points this quarter" + → cs-cco-advisor + /cs:founder-mode "let's hire a VP Marketing" → boardroom (CHRO + CMO + CFO touched) diff --git a/c-level-advisor/c-level-agents/skills/freeze/SKILL.md b/c-level-advisor/c-level-agents/skills/freeze/SKILL.md index 72d85901..9b14684e 100644 --- a/c-level-advisor/c-level-agents/skills/freeze/SKILL.md +++ b/c-level-advisor/c-level-agents/skills/freeze/SKILL.md @@ -1,6 +1,6 @@ --- name: "freeze" -description: "/cs:freeze — Lock a strategic decision for a cooldown period to prevent impulse reversal. Mirrors gstack's safety primitives for the business layer." +description: "/cs:freeze — Lock a strategic decision for a cooldown period to prevent impulse reversal. Mirrors gstack's safety primitives for the business layer. Use when an irreversible decision was made under pressure — e.g. a layoff plan or multi-year contract — and deserves a cooling-off lock before execution." --- # /cs:freeze — Cooldown Lock on a Decision diff --git a/c-level-advisor/c-level-agents/skills/gc-review/SKILL.md b/c-level-advisor/c-level-agents/skills/gc-review/SKILL.md index a6f3a2ab..dc9b7c73 100644 --- a/c-level-advisor/c-level-agents/skills/gc-review/SKILL.md +++ b/c-level-advisor/c-level-agents/skills/gc-review/SKILL.md @@ -1,6 +1,6 @@ --- name: "gc-review" -description: "/cs:gc-review — General Counsel interrogation of contracts, IP, regulatory, term sheets, and employment-law surface." +description: "/cs:gc-review — General Counsel interrogation of contracts, IP, regulatory, term sheets, and employment-law surface. Use when reviewing a term sheet before signing, redlining a customer MSA, or checking IP assignment and regulatory exposure on a new product." --- # /cs:gc-review — General Counsel Forcing Questions diff --git a/c-level-advisor/c-level-agents/skills/office-hours/SKILL.md b/c-level-advisor/c-level-agents/skills/office-hours/SKILL.md index 504e698f..727feebe 100644 --- a/c-level-advisor/c-level-agents/skills/office-hours/SKILL.md +++ b/c-level-advisor/c-level-agents/skills/office-hours/SKILL.md @@ -1,6 +1,6 @@ --- name: "office-hours" -description: "/cs:office-hours — YC-style 6-question founder interrogation before any advice. Forces clarity on problem, customer, distribution, defensibility, capital, and founder fit." +description: "/cs:office-hours — YC-style 6-question founder interrogation before any advice. Forces clarity on problem, customer, distribution, defensibility, capital, and founder fit. Use when a founder question is too vague to route — e.g. 'should we grow faster?' — or before drafting a strategy brief." --- # /cs:office-hours — Six-Question Founder Interrogation diff --git a/c-level-advisor/c-level-agents/skills/onboard/SKILL.md b/c-level-advisor/c-level-agents/skills/onboard/SKILL.md index 2230e23e..47cbdef2 100644 --- a/c-level-advisor/c-level-agents/skills/onboard/SKILL.md +++ b/c-level-advisor/c-level-agents/skills/onboard/SKILL.md @@ -1,6 +1,6 @@ --- name: "onboard" -description: "/cs:onboard — Founder interview that populates ~/.claude/company-context.md. The first command to run when starting with c-level-agents." +description: "/cs:onboard — Founder interview that populates ~/.claude/company-context.md using the canonical 7-dimension cs-onboard schema. The first command to run when starting with c-level-agents. Use when setting up the virtual C-suite for a new company, or when advisors lack company context — e.g. before a first /cs:boardroom or after a fundraise changes the numbers." --- # /cs:onboard — Founder Interview @@ -40,7 +40,9 @@ The first command to run when adopting c-level-agents. A structured founder inte ## Output Format -Saved to `~/.claude/company-context.md`: +**Canonical schema:** `~/.claude/company-context.md` is owned by the [`cs-onboard`](../../../skills/cs-onboard/SKILL.md) skill and follows its 7-dimension schema (`../../../skills/cs-onboard/templates/company-context-template.md`): Company Identity, Stage & Scale, Founder Profile, Team & Culture, Market & Competition, Current Challenges, Goals & Ambition. The 12 questions above are a faster structured intake that populates that same file — Identity/Business/Financial → Stage & Scale, Team → Team & Culture, Quarter priorities/risks → Current Challenges + Goals & Ambition. Write `[not captured]` for dimensions the quick intake doesn't reach (Founder Profile, Market & Competition); run the full `cs-onboard` interview to fill them. Never create a second context file or a divergent layout. + +The intake summary captured by the 12 questions: ```markdown # Company Context diff --git a/c-level-advisor/c-level-agents/skills/post-mortem/SKILL.md b/c-level-advisor/c-level-agents/skills/post-mortem/SKILL.md index 0bee3e88..37d7245a 100644 --- a/c-level-advisor/c-level-agents/skills/post-mortem/SKILL.md +++ b/c-level-advisor/c-level-agents/skills/post-mortem/SKILL.md @@ -1,6 +1,6 @@ --- name: "post-mortem" -description: "/cs:post-mortem — Honest retrospective on an executed decision, scored against original assumptions and dissent. Closes the strategic sprint loop." +description: "/cs:post-mortem — Honest retrospective on an executed decision, scored against original assumptions and dissent. Closes the strategic sprint loop. Use when a decision hits its 90-day review checkpoint or its kill criteria trigger — e.g. scoring last quarter's pricing change against its pre-committed success metrics." --- # /cs:post-mortem — Honest Retrospective diff --git a/c-level-advisor/c-level-agents/skills/vpe-review/SKILL.md b/c-level-advisor/c-level-agents/skills/vpe-review/SKILL.md index c34c3770..ee73496d 100644 --- a/c-level-advisor/c-level-agents/skills/vpe-review/SKILL.md +++ b/c-level-advisor/c-level-agents/skills/vpe-review/SKILL.md @@ -1,6 +1,6 @@ --- name: "vpe-review" -description: "/cs:vpe-review — Throughput-first VP of Engineering interrogation of any plan that touches delivery, eng hiring, team structure, or production discipline." +description: "/cs:vpe-review — Throughput-first VP of Engineering interrogation of any plan that touches delivery, eng hiring, team structure, or production discipline. Use when cycle time balloons, DORA metrics slide, or before committing to an eng hiring wave or a reorg." --- # /cs:vpe-review — VPE Forcing Questions @@ -112,7 +112,7 @@ python ../../../skills/vpe-advisor/scripts/eng_team_structure_designer.py team.j ## Routing - `/cs:cto-review` — for architectural causes of throughput problems -- `/cs:chro-review` — for hiring funnel comp/leveling issues +- `cs-chro-advisor` agent — for hiring funnel comp/leveling issues - `/cs:cfo-review` — for cost-per-hire envelope and eng budget - `/cs:ciso-review` — for production discipline + compliance overlap - `/cs:decide` — log the verdict diff --git a/c-level-advisor/chief-ai-officer-advisor/skills/chief-ai-officer-advisor/SKILL.md b/c-level-advisor/chief-ai-officer-advisor/skills/chief-ai-officer-advisor/SKILL.md index 38b1bb0c..349a7d43 100644 --- a/c-level-advisor/chief-ai-officer-advisor/skills/chief-ai-officer-advisor/SKILL.md +++ b/c-level-advisor/chief-ai-officer-advisor/skills/chief-ai-officer-advisor/SKILL.md @@ -210,17 +210,17 @@ python scripts/ai_cost_economics.py workload.json ## Adjacent Skills -- `../chief-data-officer-advisor/` — Training data rights, data product strategy (chains directly to model decisions) -- `../cto-advisor/` — Architecture capacity, scaling cliffs (esp. for self-hosted inference) -- `../ciso-advisor/` — Threat modeling for AI (prompt injection, jailbreak, training data poisoning) -- `../general-counsel-advisor/` — AI contracts (vendor liability, output ownership, training-data licensing) -- `../cfo-advisor/` — Build-vs-buy TCO math, multi-year vendor commitments -- `../chro-advisor/` — AI team hiring + comp -- `../../../engineering/rag-architect/` — Tactical RAG implementation -- `../../../engineering/agent-designer/` — Tactical agent architecture -- `../../../engineering/prompt-governance/` — Tactical prompt management -- `../../../engineering/self-eval/` — Tactical eval infrastructure -- `../../../engineering/llm-cost-optimizer/` — Tactical inference cost optimization +- `c-level-advisor/skills/chief-data-officer-advisor/` — Training data rights, data product strategy (chains directly to model decisions) +- `c-level-advisor/skills/cto-advisor/` — Architecture capacity, scaling cliffs (esp. for self-hosted inference) +- `c-level-advisor/skills/ciso-advisor/` — Threat modeling for AI (prompt injection, jailbreak, training data poisoning) +- `c-level-advisor/skills/general-counsel-advisor/` — AI contracts (vendor liability, output ownership, training-data licensing) +- `c-level-advisor/skills/cfo-advisor/` — Build-vs-buy TCO math, multi-year vendor commitments +- `c-level-advisor/skills/chro-advisor/` — AI team hiring + comp +- `engineering/skills/rag-architect/` — Tactical RAG implementation +- `engineering/skills/agent-designer/` — Tactical agent architecture +- `engineering/prompt-governance/` — Tactical prompt management +- `engineering/skills/self-eval/` — Tactical eval infrastructure +- `engineering/llm-cost-optimizer/` — Tactical inference cost optimization ## References diff --git a/c-level-advisor/chief-customer-officer-advisor/skills/chief-customer-officer-advisor/SKILL.md b/c-level-advisor/chief-customer-officer-advisor/skills/chief-customer-officer-advisor/SKILL.md index 76f581d4..1ae14b1b 100644 --- a/c-level-advisor/chief-customer-officer-advisor/skills/chief-customer-officer-advisor/SKILL.md +++ b/c-level-advisor/chief-customer-officer-advisor/skills/chief-customer-officer-advisor/SKILL.md @@ -189,12 +189,12 @@ python scripts/cs_coverage_calculator.py book.json ## Adjacent Skills -- `../cro-advisor/` — Revenue math, NRR, expansion comp (CCO owns customer experience; CRO owns revenue math; clean split) -- `../cpo-advisor/` — Product strategy, JTBD (CCO surfaces product gaps; CPO decides roadmap) -- `../cmo-advisor/` — Customer marketing, advocacy, references -- `../cfo-advisor/` — CS team cost, retention-impact-on-revenue math -- `../chro-advisor/` — CS team hiring + leveling -- `../../../business-growth/` — Tactical CS execution: health scores, CRM workflows, onboarding tooling +- `c-level-advisor/skills/cro-advisor/` — Revenue math, NRR, expansion comp (CCO owns customer experience; CRO owns revenue math; clean split) +- `c-level-advisor/skills/cpo-advisor/` — Product strategy, JTBD (CCO surfaces product gaps; CPO decides roadmap) +- `c-level-advisor/skills/cmo-advisor/` — Customer marketing, advocacy, references +- `c-level-advisor/skills/cfo-advisor/` — CS team cost, retention-impact-on-revenue math +- `c-level-advisor/skills/chro-advisor/` — CS team hiring + leveling +- `business-growth/` — Tactical CS execution: health scores, CRM workflows, onboarding tooling ## References diff --git a/c-level-advisor/chief-data-officer-advisor/skills/chief-data-officer-advisor/SKILL.md b/c-level-advisor/chief-data-officer-advisor/skills/chief-data-officer-advisor/SKILL.md index 6e049636..365a66ae 100644 --- a/c-level-advisor/chief-data-officer-advisor/skills/chief-data-officer-advisor/SKILL.md +++ b/c-level-advisor/chief-data-officer-advisor/skills/chief-data-officer-advisor/SKILL.md @@ -182,14 +182,14 @@ python scripts/data_product_strategy_picker.py profile.json ## Adjacent Skills -- `../cto-advisor/` — architecture capacity, scaling cliffs -- `../ciso-advisor/` — data security, threat modeling for productized data -- `../general-counsel-advisor/` — contractual constraints, DPA, training-data rights -- `../cfo-advisor/` — build-vs-buy TCO, M&A valuation math -- `../chro-advisor/` — data team hiring, leveling, comp -- `../../../engineering/database-designer/` — tactical schema design -- `../../../engineering/rag-architect/` — tactical AI/RAG implementation -- `../../../engineering/llm-cost-optimizer/` — model cost management +- `c-level-advisor/skills/cto-advisor/` — architecture capacity, scaling cliffs +- `c-level-advisor/skills/ciso-advisor/` — data security, threat modeling for productized data +- `c-level-advisor/skills/general-counsel-advisor/` — contractual constraints, DPA, training-data rights +- `c-level-advisor/skills/cfo-advisor/` — build-vs-buy TCO, M&A valuation math +- `c-level-advisor/skills/chro-advisor/` — data team hiring, leveling, comp +- `engineering/skills/database-designer/` — tactical schema design +- `engineering/skills/rag-architect/` — tactical AI/RAG implementation +- `engineering/llm-cost-optimizer/` — model cost management ## References diff --git a/c-level-advisor/executive-mentor/skills/executive-mentor/SKILL.md b/c-level-advisor/executive-mentor/skills/executive-mentor/SKILL.md index 8c54885b..ec8a3d3d 100644 --- a/c-level-advisor/executive-mentor/skills/executive-mentor/SKILL.md +++ b/c-level-advisor/executive-mentor/skills/executive-mentor/SKILL.md @@ -71,19 +71,19 @@ This isn't therapy. It's preparation. ## Commands in Detail ### `/em:challenge ` -Takes any plan — roadmap, GTM, hiring, fundraising — and finds what breaks first. Identifies assumptions, rates confidence, maps dependencies. Output: numbered vulnerabilities with severity (Critical / High / Medium). See `skills/challenge/SKILL.md` +Takes any plan — roadmap, GTM, hiring, fundraising — and finds what breaks first. Identifies assumptions, rates confidence, maps dependencies. Output: numbered vulnerabilities with severity (Critical / High / Medium). See `../challenge/SKILL.md` ### `/em:board-prep ` -48 hours before investors. What are the 10 hardest questions? What data do you need cold? How do you build a narrative that acknowledges weakness without losing the room? Prepares you for the adversarial board, not the friendly one. See `skills/board-prep/SKILL.md` +48 hours before investors. What are the 10 hardest questions? What data do you need cold? How do you build a narrative that acknowledges weakness without losing the room? Prepares you for the adversarial board, not the friendly one. See `../board-prep/SKILL.md` ### `/em:hard-call ` -Reversibility test. 10/10/10 framework. Stakeholder impact mapping. Communication planning. For decisions with no good answer — only less bad ones. See `skills/hard-call/SKILL.md` +Reversibility test. 10/10/10 framework. Stakeholder impact mapping. Communication planning. For decisions with no good answer — only less bad ones. See `../hard-call/SKILL.md` ### `/em:stress-test ` -"$5B market." "$2M ARR by December." "3-year moat." Every plan is built on assumptions. Surfaces counter-evidence, models the downside, proposes the hedge. See `skills/stress-test/SKILL.md` +"$5B market." "$2M ARR by December." "3-year moat." Every plan is built on assumptions. Surfaces counter-evidence, models the downside, proposes the hedge. See `../stress-test/SKILL.md` ### `/em:postmortem ` -Lost deal. Failed feature. Missed quarter. No blame sessions, no whitewash. 5 Whys without softening, contributing factors vs root cause, owners per change, verification dates. See `skills/postmortem/SKILL.md` +Lost deal. Failed feature. Missed quarter. No blame sessions, no whitewash. 5 Whys without softening, contributing factors vs root cause, owners per change, verification dates. See `../postmortem/SKILL.md` ## Agents & References @@ -128,7 +128,7 @@ Assume the plan will fail. Find the three most likely failure modes. For each, i ## Communication -All output passes the Internal Quality Loop before reaching the founder (see `agent-protocol/SKILL.md`). +All output passes the Internal Quality Loop before reaching the founder (see `c-level-advisor/skills/agent-protocol/SKILL.md`). - Self-verify: source attribution, assumption audit, confidence scoring - Peer-verify: cross-functional claims validated by the owning role - Critic pre-screen: high-stakes decisions reviewed by Executive Mentor diff --git a/c-level-advisor/executive-mentor/skills/hard-call/SKILL.md b/c-level-advisor/executive-mentor/skills/hard-call/SKILL.md index 3e827e7f..b1f9fac6 100644 --- a/c-level-advisor/executive-mentor/skills/hard-call/SKILL.md +++ b/c-level-advisor/executive-mentor/skills/hard-call/SKILL.md @@ -1,6 +1,6 @@ --- name: "hard-call" -description: "/em -hard-call — Framework for Decisions With No Good Options" +description: "/em:hard-call — Framework for decisions with no good options. Use when every option is painful and a structured 10/10/10 + regret-minimization pass is needed — e.g. choosing between a layoff and a down round, or killing a beloved product line." --- # /em:hard-call — Framework for Decisions With No Good Options @@ -91,7 +91,7 @@ Hard decisions almost always get harder if communication is bad. The decision it For every hard call, plan: - **Who needs to know first** (the person directly affected, before anyone else) - **How you'll tell them** (in person when possible, never via email for personal impact) -- **What you'll say** (honest, direct, compassionate — see `references/hard_things.md`) +- **What you'll say** (honest, direct, compassionate — see `../executive-mentor/references/hard_things.md`) - **What they can ask** (be ready for every question) - **What comes next** (give them a clear picture of what happens after) @@ -100,7 +100,7 @@ For every hard call, plan: ## Decision-Specific Frameworks ### Firing a Co-Founder -See `references/hard_things.md — Co-Founder Conflicts` for full framework. +See `../executive-mentor/references/hard_things.md — Co-Founder Conflicts` for full framework. Key questions to answer first: - Is this a performance problem or a values/culture problem? (Different conversations) diff --git a/c-level-advisor/executive-mentor/skills/postmortem/SKILL.md b/c-level-advisor/executive-mentor/skills/postmortem/SKILL.md index 20112c6c..32c2caf7 100644 --- a/c-level-advisor/executive-mentor/skills/postmortem/SKILL.md +++ b/c-level-advisor/executive-mentor/skills/postmortem/SKILL.md @@ -1,6 +1,6 @@ --- name: "postmortem" -description: "/em -postmortem — Honest Analysis of What Went Wrong" +description: "/em:postmortem — Honest analysis of what went wrong. Use after a failed launch, missed quarter, or bad hire to run a blameless 5-Whys retrospective with a change register — e.g. dissecting why the Q3 release slipped six weeks." --- # /em:postmortem — Honest Analysis of What Went Wrong diff --git a/c-level-advisor/executive-mentor/skills/stress-test/SKILL.md b/c-level-advisor/executive-mentor/skills/stress-test/SKILL.md index c39e0b65..39fac20f 100644 --- a/c-level-advisor/executive-mentor/skills/stress-test/SKILL.md +++ b/c-level-advisor/executive-mentor/skills/stress-test/SKILL.md @@ -1,6 +1,6 @@ --- name: "stress-test" -description: "/em -stress-test — Business Assumption Stress Testing" +description: "/em:stress-test — Business assumption stress testing. Use before betting on a plan whose core assumptions are unvalidated — e.g. stress-testing 'enterprise buyers will tolerate a 6-month pilot' or a hockey-stick revenue model." --- # /em:stress-test — Business Assumption Stress Testing diff --git a/c-level-advisor/general-counsel-advisor/skills/general-counsel-advisor/SKILL.md b/c-level-advisor/general-counsel-advisor/skills/general-counsel-advisor/SKILL.md index 9f562b23..1d1cef3d 100644 --- a/c-level-advisor/general-counsel-advisor/skills/general-counsel-advisor/SKILL.md +++ b/c-level-advisor/general-counsel-advisor/skills/general-counsel-advisor/SKILL.md @@ -142,11 +142,11 @@ See `references/ip_and_regulatory.md` for sequencing. ## Adjacent Skills -- `../ciso-advisor/` — Compliance overlap (SOC 2, ISO 27001, HIPAA technical safeguards) -- `../cfo-advisor/` — Term sheet → dilution math -- `../ma-playbook/` — Acquisition agreements, integration playbooks -- `../../../ra-qm-team/` — ISO 13485, MDR, FDA 510(k), GDPR execution -- `../../c-level-agents/skills/gc-review/SKILL.md` — `/cs:gc-review` slash command +- `c-level-advisor/skills/ciso-advisor/` — Compliance overlap (SOC 2, ISO 27001, HIPAA technical safeguards) +- `c-level-advisor/skills/cfo-advisor/` — Term sheet → dilution math +- `c-level-advisor/skills/ma-playbook/` — Acquisition agreements, integration playbooks +- `ra-qm-team/` — ISO 13485, MDR, FDA 510(k), GDPR execution +- `c-level-advisor/c-level-agents/skills/gc-review/SKILL.md` — `/cs:gc-review` slash command ## References diff --git a/c-level-advisor/skills/agent-protocol/SKILL.md b/c-level-advisor/skills/agent-protocol/SKILL.md index 35ef75cd..b8576adf 100644 --- a/c-level-advisor/skills/agent-protocol/SKILL.md +++ b/c-level-advisor/skills/agent-protocol/SKILL.md @@ -34,7 +34,15 @@ Any agent can query another using: [INVOKE:cro|What does our pipeline look like for the next 90 days?] ``` -**Valid roles:** `ceo`, `cfo`, `cro`, `cmo`, `cpo`, `cto`, `chro`, `coo`, `ciso` +**Valid roles:** `ceo`, `cfo`, `cro`, `cmo`, `cpo`, `cto`, `chro`, `coo`, `ciso`, `gc`, `cdo`, `caio`, `cco`, `vpe` + +| Role token | Advisor skill | +|---|---| +| `gc` | general-counsel-advisor (legal, contracts, term sheets) | +| `cdo` | chief-data-officer-advisor (data strategy, training-data rights) | +| `caio` | chief-ai-officer-advisor (AI strategy, evals, AI risk) | +| `cco` | chief-customer-officer-advisor (retention, customer success) | +| `vpe` | vpe-advisor (engineering delivery, DORA, eng hiring) | ## Response Format @@ -160,6 +168,26 @@ CEO can broadcast to all roles simultaneously: Responses come back independently (no agent sees another's response before forming its own). Aggregate after all respond. +## Decision Memory (Canonical Layout) + +All C-suite skills and `/cs:*` commands read and write decisions in **one** place — the two-layer model owned by `/cs:decide` and the decision-logger skill: + +``` +~/.claude/decisions/ +├── raw/YYYY-MM-DD-.md # Layer 1 — full transcripts/deliberations (never auto-loaded) +├── raw/archive/YYYY/ # Raw files after 90 days +├── approved/YYYY-MM-DD-.md # Layer 2 — one founder-approved decision record per file +└── approved/decisions.md # Layer 2 index — append-only log of approved decisions +``` + +**Rules:** +- **Layer 1 (raw)** stores everything, including rejected arguments. Reference only — never feeds future sessions automatically. +- **Layer 2 (approved)** stores only founder-approved decisions. This is what board meetings, `/cs:office-hours`, and `/cs:founder-mode` load. Prevents hallucinated consensus. +- Writers: `/cs:decide` and the Chief of Staff (post board-meeting Phase 5). Individual role agents never write decisions directly. +- decision-logger, chief-of-staff, and board-meeting all use this layout. Their SKILL.md files link here rather than defining their own paths. + +**Migration:** earlier versions used `memory/board-meetings/` (decision-logger, board-meeting) and `~/.claude/decision-log.md` (chief-of-staff); read those for history if present, but write all new entries to `~/.claude/decisions/`. + ## Quick Reference | Rule | Behavior | @@ -217,6 +245,11 @@ When a recommendation impacts another role's domain, that role validates BEFORE | Customer-facing changes | CRO + CPO | Churn risk, product roadmap conflict | | Security or compliance claims | CISO | Actual posture, regulation requirements | | Market or positioning claims | CMO | Data backing, competitive reality | +| Legal exposure, contracts, term sheets | GC | Clause risk, IP ownership, regulatory triggers | +| Data rights, training-data provenance | CDO | Consent basis, GDPR Art. 6, data-asset impact | +| AI model claims, eval results, AI risk | CAIO | Eval coverage, hallucination SLO, EU AI Act tier | +| Retention, churn, customer-health claims | CCO | GRR/NRR decomposition, churn root cause | +| Delivery timelines, eng throughput | VPE | DORA metrics, cycle-time reality, team capacity | **Peer validation format:** ``` diff --git a/c-level-advisor/skills/board-deck-builder/SKILL.md b/c-level-advisor/skills/board-deck-builder/SKILL.md index 734a68ab..eb25bfc7 100644 --- a/c-level-advisor/skills/board-deck-builder/SKILL.md +++ b/c-level-advisor/skills/board-deck-builder/SKILL.md @@ -20,9 +20,10 @@ board deck, investor update, board meeting, board pack, investor relations, quar ## Quick Start -``` -/board-deck [quarterly|monthly|fundraising] [stage: seed|seriesA|seriesB] -``` +Ask for a board deck in natural language, naming cadence and stage: + +> "Build a quarterly board deck — we're Series A." +> "Draft a fundraising board deck for a seed-stage company." Provide available metrics. The builder fills gaps with explicit placeholders — never invents numbers. diff --git a/c-level-advisor/skills/board-meeting/SKILL.md b/c-level-advisor/skills/board-meeting/SKILL.md index 1b1702c3..1b4b0576 100644 --- a/c-level-advisor/skills/board-meeting/SKILL.md +++ b/c-level-advisor/skills/board-meeting/SKILL.md @@ -1,6 +1,6 @@ --- name: "board-meeting" -description: "Multi-agent board meeting protocol for strategic decisions. Runs a structured 6-phase deliberation: context loading, independent C-suite contributions (isolated, no cross-pollination), critic analysis, synthesis, founder review, and decision extraction. Use when the user invokes /cs:board, calls a board meeting, or wants structured multi-perspective executive deliberation on a strategic question." +description: "Multi-agent board meeting protocol for strategic decisions. Runs a structured 6-phase deliberation: context loading, independent C-suite contributions (isolated, no cross-pollination), critic analysis, synthesis, founder review, and decision extraction. Use when the user invokes /cs:boardroom, calls a board meeting, or wants structured multi-perspective executive deliberation on a strategic question." license: MIT metadata: version: 1.0.0 @@ -16,29 +16,34 @@ metadata: Structured multi-agent deliberation that prevents groupthink, captures minority views, and produces clean, actionable decisions. ## Keywords -board meeting, executive deliberation, strategic decision, C-suite, multi-agent, /cs:board, founder review, decision extraction, independent perspectives +board meeting, executive deliberation, strategic decision, C-suite, multi-agent, /cs:boardroom, founder review, decision extraction, independent perspectives ## Invoke -`/cs:board [topic]` — e.g. `/cs:board Should we expand to Spain in Q3?` +`/cs:boardroom [topic]` — e.g. `/cs:boardroom Should we expand to Spain in Q3?` --- ## The 6-Phase Protocol ### PHASE 1: Context Gathering -1. Load `memory/company-context.md` -2. Load `memory/board-meetings/decisions.md` **(Layer 2 ONLY — never raw transcripts)** +1. Load `~/.claude/company-context.md` +2. Load Layer 2 approved decisions from `~/.claude/decisions/approved/` **(Layer 2 ONLY — never raw transcripts)** 3. Reset session state — no bleed from previous conversations 4. Present agenda + activated roles → wait for founder confirmation -**Chief of Staff selects relevant roles** based on topic (not all 9 every time): +**Chief of Staff selects relevant roles** based on topic (not all 14 every time): | Topic | Activate | |-------|----------| | Market expansion | CEO, CMO, CFO, CRO, COO | | Product direction | CEO, CPO, CTO, CMO | -| Hiring/org | CEO, CHRO, CFO, COO | +| Hiring/org | CEO, CHRO, CFO, COO (+ VPE for eng hiring) | | Pricing | CMO, CFO, CRO, CPO | | Technology | CTO, CPO, CFO, CISO | +| Contracts / term sheets / legal exposure | GC, CEO, CFO | +| Data strategy / training-data rights | CDO, CAIO, GC, CISO | +| AI strategy / model selection / AI risk | CAIO, CTO, CDO, CFO | +| Retention / churn / customer success | CCO, CRO, CPO | +| Eng delivery / DORA / team structure | VPE, CTO, CHRO, CFO | --- @@ -46,9 +51,9 @@ board meeting, executive deliberation, strategic decision, C-suite, multi-agent, **No cross-pollination. Each agent runs before seeing others' outputs.** -Order: Research (if needed) → CMO → CFO → CEO → CTO → COO → CHRO → CRO → CISO → CPO +Order: Research (if needed) → CMO → CFO → CEO → CTO → COO → CHRO → CRO → CISO → CPO → GC → CDO → CAIO → CCO → VPE (activated roles only) -**Reasoning techniques:** CEO: Tree of Thought (3 futures) | CFO: Chain of Thought (show the math) | CMO: Recursion of Thought (draft→critique→refine) | CPO: First Principles | CRO: Chain of Thought (pipeline math) | COO: Step by Step (process map) | CTO: ReAct (research→analyze→act) | CISO: Risk-Based (P×I) | CHRO: Empathy + Data +**Reasoning techniques:** CEO: Tree of Thought (3 futures) | CFO: Chain of Thought (show the math) | CMO: Recursion of Thought (draft→critique→refine) | CPO: First Principles | CRO: Chain of Thought (pipeline math) | COO: Step by Step (process map) | CTO: ReAct (research→analyze→act) | CISO: Risk-Based (P×I) | CHRO: Empathy + Data | GC: Risk-Based (clause exposure) | CDO: Decision-Driven (what decision does this data drive) | CAIO: Eval-Demanding (no eval, no ship) | CCO: Retention-Obsessed (GRR over NRR) | VPE: Throughput-First (cycle-time math) **Contribution format (max 5 key points, self-verified):** ``` @@ -81,7 +86,7 @@ Checklist: --- ### PHASE 4: Synthesis -Chief of Staff delivers using the **Board Meeting Output** format (defined in `agent-protocol/SKILL.md`): +Chief of Staff delivers using the **Board Meeting Output** format (defined in `../agent-protocol/SKILL.md`): - Decision Required (one sentence) - Perspectives (one line per contributing role) - Where They Agree / Where They Disagree @@ -104,29 +109,35 @@ Options: ✅ Approve | ✏️ Modify | ❌ Reject | ❓ Ask follow-up **Rules:** - User corrections OVERRIDE agent proposals. No pushback. No "but the CFO said..." - 30-min inactivity → auto-close as "pending review" -- Reopen any time with `/cs:board resume` +- Reopen any time with `/cs:boardroom resume` --- ### PHASE 6: Decision Extraction After founder approval: -- **Layer 1:** Write full transcript → `memory/board-meetings/YYYY-MM-DD-raw.md` -- **Layer 2:** Append approved decisions → `memory/board-meetings/decisions.md` +- **Layer 1:** Write full transcript → `~/.claude/decisions/raw/YYYY-MM-DD-.md` +- **Layer 2:** Write approved decision record → `~/.claude/decisions/approved/YYYY-MM-DD-.md` and append to the index `~/.claude/decisions/approved/decisions.md` - Mark rejected proposals `[DO_NOT_RESURFACE]` - Confirm to founder with count of decisions logged, actions tracked, flags added --- ## Memory Structure + +Uses the canonical two-layer decision memory (see `../agent-protocol/SKILL.md` → "Decision Memory (Canonical Layout)"): + ``` -memory/board-meetings/ -├── decisions.md # Layer 2 — founder-approved only (Phase 1 loads this) -├── YYYY-MM-DD-raw.md # Layer 1 — full transcripts (never auto-loaded) -└── archive/YYYY/ # Raw transcripts after 90 days +~/.claude/decisions/ +├── raw/YYYY-MM-DD-.md # Layer 1 — full transcripts (never auto-loaded) +├── raw/archive/YYYY/ # Raw transcripts after 90 days +├── approved/YYYY-MM-DD-.md # Layer 2 — founder-approved records (Phase 1 loads these) +└── approved/decisions.md # Layer 2 index — append-only ``` **Future meetings load Layer 2 only.** Never Layer 1. This prevents hallucinated consensus. +Migration: a legacy `memory/board-meetings/` folder may exist from earlier versions; read it for history but write new transcripts and decisions to `~/.claude/decisions/`. + --- ## Failure Mode Quick Reference @@ -136,7 +147,7 @@ memory/board-meetings/ | Analysis paralysis | Cap at 5 points; force recommendation even with Low confidence | | Bikeshedding | Log as async action item; return to main agenda | | Role bleed (CFO making product calls) | Critic flags; exclude from synthesis | -| Layer contamination | Phase 1 loads decisions.md only — hard rule | +| Layer contamination | Phase 1 loads `~/.claude/decisions/approved/` only — hard rule | --- diff --git a/c-level-advisor/skills/board-meeting/references/meeting-facilitation.md b/c-level-advisor/skills/board-meeting/references/meeting-facilitation.md index 60437d8a..7d73254e 100644 --- a/c-level-advisor/skills/board-meeting/references/meeting-facilitation.md +++ b/c-level-advisor/skills/board-meeting/references/meeting-facilitation.md @@ -164,4 +164,4 @@ After each board meeting, score it: | Roles activated | 3–6 | All 9 (too many = noise) | | Phase 2 conflicts surfaced | At least 1 | 0 (groupthink risk) | -Track these in `memory/board-meetings/meeting-health.md` over time. Pattern: if action items consistently exceed 8, meetings are too infrequent. If conflicts are consistently 0, isolation is broken. +Track these in `~/.claude/decisions/meeting-health.md` over time. Pattern: if action items consistently exceed 8, meetings are too infrequent. If conflicts are consistently 0, isolation is broken. diff --git a/c-level-advisor/skills/board-meeting/templates/meeting-agenda.md b/c-level-advisor/skills/board-meeting/templates/meeting-agenda.md index b491937f..51896634 100644 --- a/c-level-advisor/skills/board-meeting/templates/meeting-agenda.md +++ b/c-level-advisor/skills/board-meeting/templates/meeting-agenda.md @@ -1,7 +1,7 @@ # Board Meeting Agenda Template -Use this to structure a board meeting before invoking `/cs:board`. -Paste it into the conversation or save it as `memory/board-meetings/agenda-YYYY-MM-DD.md`. +Use this to structure a board meeting before invoking `/cs:boardroom`. +Paste it into the conversation or save it as `~/.claude/decisions/agenda-YYYY-MM-DD.md`. --- @@ -70,7 +70,7 @@ List topics that might come up but are NOT on today's agenda: ## Pre-Read Materials all participants should review before the meeting: -- [ ] `memory/board-meetings/decisions.md` (Chief of Staff loads automatically) +- [ ] `~/.claude/decisions/approved/decisions.md` (Chief of Staff loads automatically) - [ ] [Link or filename] - [ ] [Link or filename] diff --git a/c-level-advisor/skills/board-meeting/templates/meeting-minutes.md b/c-level-advisor/skills/board-meeting/templates/meeting-minutes.md index bd165e6b..d41db40c 100644 --- a/c-level-advisor/skills/board-meeting/templates/meeting-minutes.md +++ b/c-level-advisor/skills/board-meeting/templates/meeting-minutes.md @@ -2,9 +2,9 @@ This is the Layer 2 output — the founder-approved record of what was decided. Written by Chief of Staff after Phase 5 (founder approval). -Appended to `memory/board-meetings/decisions.md`. +Appended to the Layer 2 index `~/.claude/decisions/approved/decisions.md`. -Do NOT include raw agent debate here. That lives in `YYYY-MM-DD-raw.md` (Layer 1). +Do NOT include raw agent debate here. That lives in `~/.claude/decisions/raw/YYYY-MM-DD-.md` (Layer 1). --- @@ -88,4 +88,4 @@ These were not resolved in this meeting. They carry forward. --- *Minutes approved by: [Founder name] on [DATE]* -*Raw transcript: `memory/board-meetings/[DATE]-raw.md`* +*Raw transcript: `~/.claude/decisions/raw/[DATE]-.md`* diff --git a/c-level-advisor/skills/c-level-skills/SKILL.md b/c-level-advisor/skills/c-level-skills/SKILL.md index cc05f631..7e40a382 100644 --- a/c-level-advisor/skills/c-level-skills/SKILL.md +++ b/c-level-advisor/skills/c-level-skills/SKILL.md @@ -1,153 +1,47 @@ --- -name: "c-level-advisor" -description: "10 C-level advisory agent skills and plugins for Claude Code, Codex, Gemini CLI, Cursor, OpenClaw. CEO, CTO, COO, CPO, CMO, CFO, CRO, CISO, CHRO, Executive Mentor. Multi-role board meetings, strategy routing, structured recommendations. For founders needing executive-level decision support." +name: "c-level-skills" +description: "Index and router for the C-level advisory bundle: 33 skills covering 14 C-suite roles, orchestration, cross-cutting capabilities, and culture. Use when exploring what the c-level-advisor bundle contains, deciding which advisor skill fits a question, or finding the entry points (cs-onboard interview, chief-of-staff routing, board-meeting protocol)." license: MIT metadata: - version: 2.0.0 + version: 2.1.0 author: Alireza Rezvani category: c-level domain: executive-advisory - updated: 2026-03-05 - skills_count: 28 - scripts_count: 25 - references_count: 52 + updated: 2026-06-11 + skills_count: 33 + scripts_count: 37 + references_count: 68 --- -# C-Level Advisory Ecosystem +# C-Level Advisory Bundle — Index -A complete virtual board of directors for founders and executives. +This is the bundle index, not an advisor. It tells you what exists and where to start; the skills below do the work. -## Quick Start +## Start Here -``` -1. Run /cs:setup → creates company-context.md (all agents read this) - ✓ Verify company-context.md was created and contains your company name, - stage, and core metrics before proceeding. -2. Ask any strategic question → Chief of Staff routes to the right role -3. For big decisions → /cs:board triggers a multi-role board meeting - ✓ Confirm at least 3 roles have weighed in before accepting a conclusion. -``` +1. **Onboard** — the `cs-onboard` skill runs the founder interview (`/cs:setup`, 7 dimensions, ~45 min) and writes `~/.claude/company-context.md`. Refresh quarterly with `/cs:update`. This is the canonical context schema every advisor reads. +2. **Ask** — the `chief-of-staff` skill routes any question to the right advisor(s). See its routing matrix for all 14 roles. +3. **Big decisions** — the `board-meeting` skill runs a **6-phase** deliberation: (1) context gathering → (2) independent contributions (isolated) → (3) critic analysis → (4) synthesis → (5) founder review (full stop) → (6) decision extraction. Invoked via `/cs:boardroom` in the c-level-agents plugin. +4. **Memory** — decisions land in the canonical two-layer layout `~/.claude/decisions/{raw,approved}/` (see `../agent-protocol/SKILL.md` → "Decision Memory (Canonical Layout)"). -### Commands +## What's in the Bundle (33 skills) -#### `/cs:setup` — Onboarding Questionnaire +**14 C-suite roles + critic (15):** ceo-advisor, cfo-advisor, cto-advisor, coo-advisor, cpo-advisor, cmo-advisor, cro-advisor, ciso-advisor, chro-advisor, general-counsel-advisor, chief-data-officer-advisor, chief-ai-officer-advisor, chief-customer-officer-advisor, vpe-advisor — plus the executive-mentor critic (sibling plugin). -Walks through the following prompts and writes `company-context.md` to the project root. Run once per company or when context changes significantly. +**Orchestration (6):** cs-onboard, chief-of-staff, board-meeting, decision-logger, agent-protocol, context-engine. -``` -Q1. What is your company name and one-line description? -Q2. What stage are you at? (Idea / Pre-seed / Seed / Series A / Series B+) -Q3. What is your current ARR (or MRR) and runway in months? -Q4. What is your team size and structure? -Q5. What industry and customer segment do you serve? -Q6. What are your top 3 priorities for the next 90 days? -Q7. What is your biggest current risk or blocker? -``` +**Cross-cutting (6):** board-deck-builder, scenario-war-room, competitive-intel, org-health-diagnostic, ma-playbook, intl-expansion. -After collecting answers, the agent writes structured output: +**Culture & collaboration (6):** culture-architect, company-os, founder-coach, strategic-alignment, change-management, internal-narrative. -```markdown -# Company Context -- Name: -- Stage: -- Industry: -- Team size: -- Key metrics: -- Top priorities: -- Key risks: -``` +Plus this index (1). 37 stdlib-only Python tools and 68 reference docs across the bundle. -#### `/cs:board` — Full Board Meeting +## Routing Quick Reference -Convenes all relevant executive roles in three phases: +Full matrix in `../chief-of-staff/SKILL.md` and `../chief-of-staff/references/routing-matrix.md`. Primary roles: CFO (capital/burn), CRO (pipeline/sales), CMO (positioning), CPO (roadmap/PMF), CTO (architecture), COO (ops/OKRs), CHRO (people), CISO (security), GC (contracts/term sheets), CDO (data strategy/training-data rights), CAIO (AI strategy/evals), CCO (retention/GRR), VPE (delivery/DORA), CEO (direction). Multi-domain or irreversible → board meeting. -``` -Phase 1 — Framing: Chief of Staff states the decision and success criteria. -Phase 2 — Isolation: Each role produces independent analysis (no cross-talk). -Phase 3 — Debate: Roles surface conflicts, stress-test assumptions, align on - a recommendation. Dissenting views are preserved in the log. -``` +## Related Layers -Use for high-stakes or cross-functional decisions. Confirm at least 3 roles have weighed in before accepting a conclusion. - -### Chief of Staff Routing Matrix - -When a question arrives without a role prefix, the Chief of Staff maps it to the appropriate executive using these primary signals: - -| Topic Signal | Primary Role | Supporting Roles | -|---|---|---| -| Fundraising, valuation, burn | CFO | CEO, CRO | -| Architecture, build vs. buy, tech debt | CTO | CPO, CISO | -| Hiring, culture, performance | CHRO | CEO, Executive Mentor | -| GTM, demand gen, positioning | CMO | CRO, CPO | -| Revenue, pipeline, sales motion | CRO | CMO, CFO | -| Security, compliance, risk | CISO | CTO, CFO | -| Product roadmap, prioritisation | CPO | CTO, CMO | -| Ops, process, scaling | COO | CFO, CHRO | -| Vision, strategy, investor relations | CEO | Executive Mentor | -| Career, founder psychology, leadership | Executive Mentor | CEO, CHRO | -| Multi-domain / unclear | Chief of Staff convenes board | All relevant roles | - -### Invoking a Specific Role Directly - -To bypass Chief of Staff routing and address one executive directly, prefix your question with the role name: - -``` -CFO: What is our optimal burn rate heading into a Series A? -CTO: Should we rebuild our auth layer in-house or buy a solution? -CHRO: How do we design a performance review process for a 15-person team? -``` - -The Chief of Staff still logs the exchange; only routing is skipped. - -### Example: Strategic Question - -**Input:** "Should we raise a Series A now or extend runway and grow ARR first?" - -**Output format:** -- **Bottom Line:** Extend runway 6 months; raise at $2M ARR for better terms. -- **What:** Current $800K ARR is below the threshold most Series A investors benchmark. -- **Why:** Raising now increases dilution risk; 6-month extension is achievable with current burn. -- **How to Act:** Cut 2 low-ROI channels, hit $2M ARR, then run a 6-week fundraise sprint. -- **Your Decision:** Proceed with extension / Raise now anyway (choose one). - -### Example: company-context.md (after /cs:setup) - -```markdown -# Company Context -- Name: Acme Inc. -- Stage: Seed ($800K ARR) -- Industry: B2B SaaS -- Team size: 12 -- Key metrics: 15% MoM growth, 18-month runway -- Top priorities: Series A readiness, enterprise GTM -``` - -## What's Included - -### 10 C-Suite Roles -CEO, CTO, COO, CPO, CMO, CFO, CRO, CISO, CHRO, Executive Mentor - -### 6 Orchestration Skills -Founder Onboard, Chief of Staff (router), Board Meeting, Decision Logger, Agent Protocol, Context Engine - -### 6 Cross-Cutting Capabilities -Board Deck Builder, Scenario War Room, Competitive Intel, Org Health Diagnostic, M&A Playbook, International Expansion - -### 6 Culture & Collaboration -Culture Architect, Company OS, Founder Coach, Strategic Alignment, Change Management, Internal Narrative - -## Key Features - -- **Internal Quality Loop:** Self-verify → peer-verify → critic pre-screen → present -- **Two-Layer Memory:** Raw transcripts + approved decisions only (prevents hallucinated consensus) -- **Board Meeting Isolation:** Phase 2 independent analysis before cross-examination -- **Proactive Triggers:** Context-driven early warnings without being asked -- **Structured Output:** Bottom Line → What → Why → How to Act → Your Decision -- **25 Python Tools:** All stdlib-only, CLI-first, JSON output, zero dependencies - -## See Also - -- `CLAUDE.md` — full architecture diagram and integration guide -- `agent-protocol/SKILL.md` — communication standard and quality loop details -- `chief-of-staff/SKILL.md` — routing matrix for all 28 skills +- `../../c-level-agents/` — 13 cs-* persona agents + 21 `/cs:*` slash commands on top of these skills +- `../../executive-mentor/` — adversarial `/em:*` critic commands +- `../../CLAUDE.md` — full architecture diagram and integration guide diff --git a/c-level-advisor/skills/ceo-advisor/SKILL.md b/c-level-advisor/skills/ceo-advisor/SKILL.md index 6396c197..4fbe8eb3 100644 --- a/c-level-advisor/skills/ceo-advisor/SKILL.md +++ b/c-level-advisor/skills/ceo-advisor/SKILL.md @@ -150,7 +150,7 @@ Explore multiple futures. For every strategic decision, generate at least 3 path ## Communication -All output passes the Internal Quality Loop before reaching the founder (see `agent-protocol/SKILL.md`). +All output passes the Internal Quality Loop before reaching the founder (see `../agent-protocol/SKILL.md`). - Self-verify: source attribution, assumption audit, confidence scoring - Peer-verify: cross-functional claims validated by the owning role - Critic pre-screen: high-stakes decisions reviewed by Executive Mentor diff --git a/c-level-advisor/skills/cfo-advisor/SKILL.md b/c-level-advisor/skills/cfo-advisor/SKILL.md index be2397ef..c4e4492a 100644 --- a/c-level-advisor/skills/cfo-advisor/SKILL.md +++ b/c-level-advisor/skills/cfo-advisor/SKILL.md @@ -126,7 +126,7 @@ Work through financial logic step by step. Show all math. Be conservative in pro ## Communication -All output passes the Internal Quality Loop before reaching the founder (see `agent-protocol/SKILL.md`). +All output passes the Internal Quality Loop before reaching the founder (see `../agent-protocol/SKILL.md`). - Self-verify: source attribution, assumption audit, confidence scoring - Peer-verify: cross-functional claims validated by the owning role - Critic pre-screen: high-stakes decisions reviewed by Executive Mentor diff --git a/c-level-advisor/skills/chief-ai-officer-advisor/SKILL.md b/c-level-advisor/skills/chief-ai-officer-advisor/SKILL.md index 38b1bb0c..349a7d43 100644 --- a/c-level-advisor/skills/chief-ai-officer-advisor/SKILL.md +++ b/c-level-advisor/skills/chief-ai-officer-advisor/SKILL.md @@ -210,17 +210,17 @@ python scripts/ai_cost_economics.py workload.json ## Adjacent Skills -- `../chief-data-officer-advisor/` — Training data rights, data product strategy (chains directly to model decisions) -- `../cto-advisor/` — Architecture capacity, scaling cliffs (esp. for self-hosted inference) -- `../ciso-advisor/` — Threat modeling for AI (prompt injection, jailbreak, training data poisoning) -- `../general-counsel-advisor/` — AI contracts (vendor liability, output ownership, training-data licensing) -- `../cfo-advisor/` — Build-vs-buy TCO math, multi-year vendor commitments -- `../chro-advisor/` — AI team hiring + comp -- `../../../engineering/rag-architect/` — Tactical RAG implementation -- `../../../engineering/agent-designer/` — Tactical agent architecture -- `../../../engineering/prompt-governance/` — Tactical prompt management -- `../../../engineering/self-eval/` — Tactical eval infrastructure -- `../../../engineering/llm-cost-optimizer/` — Tactical inference cost optimization +- `c-level-advisor/skills/chief-data-officer-advisor/` — Training data rights, data product strategy (chains directly to model decisions) +- `c-level-advisor/skills/cto-advisor/` — Architecture capacity, scaling cliffs (esp. for self-hosted inference) +- `c-level-advisor/skills/ciso-advisor/` — Threat modeling for AI (prompt injection, jailbreak, training data poisoning) +- `c-level-advisor/skills/general-counsel-advisor/` — AI contracts (vendor liability, output ownership, training-data licensing) +- `c-level-advisor/skills/cfo-advisor/` — Build-vs-buy TCO math, multi-year vendor commitments +- `c-level-advisor/skills/chro-advisor/` — AI team hiring + comp +- `engineering/skills/rag-architect/` — Tactical RAG implementation +- `engineering/skills/agent-designer/` — Tactical agent architecture +- `engineering/prompt-governance/` — Tactical prompt management +- `engineering/skills/self-eval/` — Tactical eval infrastructure +- `engineering/llm-cost-optimizer/` — Tactical inference cost optimization ## References diff --git a/c-level-advisor/skills/chief-customer-officer-advisor/SKILL.md b/c-level-advisor/skills/chief-customer-officer-advisor/SKILL.md index 76f581d4..1ae14b1b 100644 --- a/c-level-advisor/skills/chief-customer-officer-advisor/SKILL.md +++ b/c-level-advisor/skills/chief-customer-officer-advisor/SKILL.md @@ -189,12 +189,12 @@ python scripts/cs_coverage_calculator.py book.json ## Adjacent Skills -- `../cro-advisor/` — Revenue math, NRR, expansion comp (CCO owns customer experience; CRO owns revenue math; clean split) -- `../cpo-advisor/` — Product strategy, JTBD (CCO surfaces product gaps; CPO decides roadmap) -- `../cmo-advisor/` — Customer marketing, advocacy, references -- `../cfo-advisor/` — CS team cost, retention-impact-on-revenue math -- `../chro-advisor/` — CS team hiring + leveling -- `../../../business-growth/` — Tactical CS execution: health scores, CRM workflows, onboarding tooling +- `c-level-advisor/skills/cro-advisor/` — Revenue math, NRR, expansion comp (CCO owns customer experience; CRO owns revenue math; clean split) +- `c-level-advisor/skills/cpo-advisor/` — Product strategy, JTBD (CCO surfaces product gaps; CPO decides roadmap) +- `c-level-advisor/skills/cmo-advisor/` — Customer marketing, advocacy, references +- `c-level-advisor/skills/cfo-advisor/` — CS team cost, retention-impact-on-revenue math +- `c-level-advisor/skills/chro-advisor/` — CS team hiring + leveling +- `business-growth/` — Tactical CS execution: health scores, CRM workflows, onboarding tooling ## References diff --git a/c-level-advisor/skills/chief-data-officer-advisor/SKILL.md b/c-level-advisor/skills/chief-data-officer-advisor/SKILL.md index 6e049636..365a66ae 100644 --- a/c-level-advisor/skills/chief-data-officer-advisor/SKILL.md +++ b/c-level-advisor/skills/chief-data-officer-advisor/SKILL.md @@ -182,14 +182,14 @@ python scripts/data_product_strategy_picker.py profile.json ## Adjacent Skills -- `../cto-advisor/` — architecture capacity, scaling cliffs -- `../ciso-advisor/` — data security, threat modeling for productized data -- `../general-counsel-advisor/` — contractual constraints, DPA, training-data rights -- `../cfo-advisor/` — build-vs-buy TCO, M&A valuation math -- `../chro-advisor/` — data team hiring, leveling, comp -- `../../../engineering/database-designer/` — tactical schema design -- `../../../engineering/rag-architect/` — tactical AI/RAG implementation -- `../../../engineering/llm-cost-optimizer/` — model cost management +- `c-level-advisor/skills/cto-advisor/` — architecture capacity, scaling cliffs +- `c-level-advisor/skills/ciso-advisor/` — data security, threat modeling for productized data +- `c-level-advisor/skills/general-counsel-advisor/` — contractual constraints, DPA, training-data rights +- `c-level-advisor/skills/cfo-advisor/` — build-vs-buy TCO, M&A valuation math +- `c-level-advisor/skills/chro-advisor/` — data team hiring, leveling, comp +- `engineering/skills/database-designer/` — tactical schema design +- `engineering/skills/rag-architect/` — tactical AI/RAG implementation +- `engineering/llm-cost-optimizer/` — model cost management ## References diff --git a/c-level-advisor/skills/chief-of-staff/SKILL.md b/c-level-advisor/skills/chief-of-staff/SKILL.md index d4b77e41..9dfb8953 100644 --- a/c-level-advisor/skills/chief-of-staff/SKILL.md +++ b/c-level-advisor/skills/chief-of-staff/SKILL.md @@ -1,6 +1,6 @@ --- name: "chief-of-staff" -description: "C-suite orchestration layer. Routes founder questions to the right advisor role(s), triggers multi-role board meetings for complex decisions, synthesizes outputs, and tracks decisions. Every C-suite interaction starts here. Loads company context automatically." +description: "C-suite orchestration layer. Routes founder questions to the right advisor role(s), triggers multi-role board meetings for complex decisions, synthesizes outputs, and tracks decisions. Every C-suite interaction starts here. Loads company context automatically. Use when a founder question needs routing to the right advisor — e.g. 'should we raise now or cut burn?' — or when a multi-domain decision needs a board meeting convened." license: MIT metadata: version: 1.0.0 @@ -81,6 +81,11 @@ Full rules in `references/routing-matrix.md`. | Company direction, investor relations | CEO | Board | | Market strategy, positioning | CMO | CRO | | M&A, pivots | CEO | Board | +| Contracts, term sheets, legal exposure, IP | GC | CEO | +| Data strategy, training-data rights, data assets | CDO | CAIO | +| AI strategy, model selection, evals, AI risk | CAIO | CTO | +| Retention, churn, customer success, NRR/GRR | CCO | CRO | +| Eng delivery, DORA metrics, eng hiring, team structure | VPE | CTO | --- @@ -133,7 +138,10 @@ Full framework in `references/synthesis-framework.md`. ## Decision Log -Track decisions to `~/.claude/decision-log.md`. +Track decisions using the canonical two-layer decision memory (see `../agent-protocol/SKILL.md` → "Decision Memory (Canonical Layout)"): + +- **Layer 1 (raw):** `~/.claude/decisions/raw/YYYY-MM-DD-{slug}.md` — full deliberation transcript +- **Layer 2 (approved):** `~/.claude/decisions/approved/YYYY-MM-DD-{slug}.md` — founder-approved decisions only ``` ## Decision: [Name] @@ -144,14 +152,16 @@ Owner: [Who executes] Review: [When to check back] ``` -At session start: if a review date has passed, flag it: *"You decided [X] on [date]. Worth a check-in?"* +At session start: scan `~/.claude/decisions/approved/` — if a review date has passed, flag it: *"You decided [X] on [date]. Worth a check-in?"* + +Migration: a legacy single-file log at `~/.claude/decision-log.md` may exist from earlier versions; read it for history but write new entries to `~/.claude/decisions/`. --- ## Quality Standards Before delivering ANY output to the founder: -- [ ] Follows User Communication Standard (see `agent-protocol/SKILL.md`) +- [ ] Follows User Communication Standard (see `../agent-protocol/SKILL.md`) - [ ] Bottom line is first — no preamble, no process narration - [ ] Company context loaded (not generic advice) - [ ] Every finding has WHAT + WHY + HOW @@ -166,9 +176,9 @@ Before delivering ANY output to the founder: ## Ecosystem Awareness -The Chief of Staff routes to **28 skills total**: -- **10 C-suite roles** — CEO, CTO, COO, CPO, CMO, CFO, CRO, CISO, CHRO, Executive Mentor -- **6 orchestration skills** — cs-onboard, context-engine, board-meeting, decision-logger, agent-protocol +The Chief of Staff routes to **33 skills total**: +- **15 C-suite roles** — CEO, CTO, COO, CPO, CMO, CFO, CRO, CISO, CHRO, General Counsel, CDO, CAIO, CCO, VPE, Executive Mentor +- **6 orchestration skills** — cs-onboard, context-engine, board-meeting, decision-logger, agent-protocol, chief-of-staff - **6 cross-cutting skills** — board-deck-builder, scenario-war-room, competitive-intel, org-health-diagnostic, ma-playbook, intl-expansion - **6 culture & collaboration skills** — culture-architect, company-os, founder-coach, strategic-alignment, change-management, internal-narrative diff --git a/c-level-advisor/skills/chief-of-staff/references/routing-matrix.md b/c-level-advisor/skills/chief-of-staff/references/routing-matrix.md index 2c94ac08..4048f57c 100644 --- a/c-level-advisor/skills/chief-of-staff/references/routing-matrix.md +++ b/c-level-advisor/skills/chief-of-staff/references/routing-matrix.md @@ -102,6 +102,52 @@ Detailed routing rules for the Chief of Staff. When a founder asks a question, f | What's our security posture? | CISO | CTO | 1 | | A regulator is asking questions | CISO | CEO, COO | 4 | +### Legal & Contracts + +| Question type | Primary | Secondary | Score | +|--------------|---------|-----------|-------| +| Is this contract safe to sign? | GC | CFO | 2 | +| What's wrong with this term sheet? | GC | CFO, CEO | 3 | +| Do we own the IP our contractors wrote? | GC | CTO | 2 | +| A customer wants an MSA redline — what matters? | GC | CRO | 2 | +| Are we exposed on data privacy / GDPR? | GC | CISO, CDO | 3 | + +### Data Strategy + +| Question type | Primary | Secondary | Score | +|--------------|---------|-----------|-------| +| Can we train models on our customer data? | CDO | GC, CAIO | 3 | +| Warehouse, lakehouse, or mesh? | CDO | CTO | 2 | +| Is our data an asset we can productize or sell? | CDO | CFO, GC | 3 | +| How do we value our data in M&A diligence? | CDO | CFO | 3 | + +### AI Strategy + +| Question type | Primary | Secondary | Score | +|--------------|---------|-----------|-------| +| Should we use an API, fine-tune, or build our own model? | CAIO | CTO, CFO | 3 | +| What does the EU AI Act mean for this feature? | CAIO | GC, CISO | 3 | +| Our AI costs are exploding — what now? | CAIO | CFO | 2 | +| How do we eval / set a hallucination SLO? | CAIO | CTO | 2 | + +### Customer & Retention + +| Question type | Primary | Secondary | Score | +|--------------|---------|-----------|-------| +| Gross retention dropped — why? | CCO | CRO, CPO | 3 | +| How many CSMs do we need per ARR tier? | CCO | CFO, CHRO | 2 | +| Which customers should we fire? | CCO | CRO | 2 | +| NRR looks fine but logos keep leaving | CCO | CRO, CPO | 3 | + +### Engineering Delivery + +| Question type | Primary | Secondary | Score | +|--------------|---------|-----------|-------| +| Why is shipping so slow? (cycle time, DORA) | VPE | CTO | 2 | +| How should we structure eng teams at this headcount? | VPE | CHRO | 2 | +| Our eng hiring funnel is leaking — where? | VPE | CHRO | 2 | +| Eng delivery vs architecture debt trade-off | VPE | CTO, CPO | 3 | + ### Strategic Direction | Question type | Primary | Secondary | Score | @@ -165,6 +211,11 @@ Automatically escalate to board meeting when any of these apply: | CMO | cmo-advisor | Marketing, brand, positioning | | CHRO | chro-advisor | People, culture, hiring | | CISO | ciso-advisor | Security, compliance, risk | +| GC | general-counsel-advisor | Legal, contracts, term sheets, IP | +| CDO | chief-data-officer-advisor | Data strategy, training-data rights, data assets | +| CAIO | chief-ai-officer-advisor | AI strategy, model selection, evals, AI risk | +| CCO | chief-customer-officer-advisor | Retention, churn, customer success | +| VPE | vpe-advisor | Eng delivery, DORA, eng hiring, team structure | **If a role file doesn't exist:** Note the gap. Answer from first principles with domain expertise. Log that the role is missing. @@ -179,7 +230,7 @@ These skills are invoked for specific cross-cutting needs, not for general domai |-------|---------|------| | C-Suite Onboard | `/cs:setup`, first-time setup, "tell me about your company" | cs-onboard | | Context Engine | Auto-loaded; staleness check | context-engine | -| Board Meeting | `/cs:board`, multi-role decisions, score ≥ 4 | board-meeting | +| Board Meeting | `/cs:boardroom`, multi-role decisions, score ≥ 4 | board-meeting | | Decision Logger | After board meetings, `/cs:decisions`, `/cs:review` | decision-logger | | Agent Protocol | Inter-role invocations, loop detection | agent-protocol | diff --git a/c-level-advisor/skills/chro-advisor/SKILL.md b/c-level-advisor/skills/chro-advisor/SKILL.md index a846122d..e522976b 100644 --- a/c-level-advisor/skills/chro-advisor/SKILL.md +++ b/c-level-advisor/skills/chro-advisor/SKILL.md @@ -130,7 +130,7 @@ Start with the human impact, then validate with metrics. Every people decision m ## Communication -All output passes the Internal Quality Loop before reaching the founder (see `agent-protocol/SKILL.md`). +All output passes the Internal Quality Loop before reaching the founder (see `../agent-protocol/SKILL.md`). - Self-verify: source attribution, assumption audit, confidence scoring - Peer-verify: cross-functional claims validated by the owning role - Critic pre-screen: high-stakes decisions reviewed by Executive Mentor diff --git a/c-level-advisor/skills/ciso-advisor/SKILL.md b/c-level-advisor/skills/ciso-advisor/SKILL.md index ef7d035c..fd3d3b19 100644 --- a/c-level-advisor/skills/ciso-advisor/SKILL.md +++ b/c-level-advisor/skills/ciso-advisor/SKILL.md @@ -121,7 +121,7 @@ Evaluate every decision through probability × impact. Quantify risks in busines ## Communication -All output passes the Internal Quality Loop before reaching the founder (see `agent-protocol/SKILL.md`). +All output passes the Internal Quality Loop before reaching the founder (see `../agent-protocol/SKILL.md`). - Self-verify: source attribution, assumption audit, confidence scoring - Peer-verify: cross-functional claims validated by the owning role - Critic pre-screen: high-stakes decisions reviewed by Executive Mentor diff --git a/c-level-advisor/skills/cmo-advisor/SKILL.md b/c-level-advisor/skills/cmo-advisor/SKILL.md index f8fc3298..2582531e 100644 --- a/c-level-advisor/skills/cmo-advisor/SKILL.md +++ b/c-level-advisor/skills/cmo-advisor/SKILL.md @@ -155,7 +155,7 @@ Draft a marketing strategy, then critique it from the customer's perspective. Re ## Communication -All output passes the Internal Quality Loop before reaching the founder (see `agent-protocol/SKILL.md`). +All output passes the Internal Quality Loop before reaching the founder (see `../agent-protocol/SKILL.md`). - Self-verify: source attribution, assumption audit, confidence scoring - Peer-verify: cross-functional claims validated by the owning role - Critic pre-screen: high-stakes decisions reviewed by Executive Mentor diff --git a/c-level-advisor/skills/competitive-intel/SKILL.md b/c-level-advisor/skills/competitive-intel/SKILL.md index ef4223d8..49036073 100644 --- a/c-level-advisor/skills/competitive-intel/SKILL.md +++ b/c-level-advisor/skills/competitive-intel/SKILL.md @@ -20,13 +20,13 @@ competitive intelligence, competitor analysis, battlecard, win/loss analysis, co ## Quick Start -``` -/ci:landscape — Map your competitive space (direct, indirect, future) -/ci:battlecard [name] — Build a sales battlecard for a specific competitor -/ci:winloss — Analyze recent wins and losses by reason -/ci:update [name] — Track what a competitor did recently -/ci:map — Build competitive positioning map -``` +Ask in natural language for the deliverable you need: + +> "Map our competitive landscape" — direct, indirect, and future competitors +> "Build a battlecard for [competitor]" — sales-ready battlecard +> "Run a win/loss analysis" — recent wins and losses by reason +> "What did [competitor] do recently?" — competitor update tracking +> "Build a competitive positioning map" — 2x2 positioning map ## Framework: 5-Layer Intelligence System diff --git a/c-level-advisor/skills/context-engine/SKILL.md b/c-level-advisor/skills/context-engine/SKILL.md index 4d99a510..b29d5625 100644 --- a/c-level-advisor/skills/context-engine/SKILL.md +++ b/c-level-advisor/skills/context-engine/SKILL.md @@ -1,6 +1,6 @@ --- name: "context-engine" -description: "Loads and manages company context for all C-suite advisor skills. Reads ~/.claude/company-context.md, detects stale context (>90 days), enriches context during conversations, and enforces privacy/anonymization rules before external API calls." +description: "Loads and manages company context for all C-suite advisor skills. Reads ~/.claude/company-context.md, detects stale context (>90 days), enriches context during conversations, and enforces privacy/anonymization rules before external API calls. Use when starting any C-suite advisor session, when context looks stale or missing, or before sending company data to an external service." license: MIT metadata: version: 1.0.0 diff --git a/c-level-advisor/skills/coo-advisor/SKILL.md b/c-level-advisor/skills/coo-advisor/SKILL.md index 26d76131..6f1f855c 100644 --- a/c-level-advisor/skills/coo-advisor/SKILL.md +++ b/c-level-advisor/skills/coo-advisor/SKILL.md @@ -123,7 +123,7 @@ Map processes sequentially. Identify each step, handoff, and decision point. Fin ## Communication -All output passes the Internal Quality Loop before reaching the founder (see `agent-protocol/SKILL.md`). +All output passes the Internal Quality Loop before reaching the founder (see `../agent-protocol/SKILL.md`). - Self-verify: source attribution, assumption audit, confidence scoring - Peer-verify: cross-functional claims validated by the owning role - Critic pre-screen: high-stakes decisions reviewed by Executive Mentor diff --git a/c-level-advisor/skills/cpo-advisor/SKILL.md b/c-level-advisor/skills/cpo-advisor/SKILL.md index d7456a4f..0b159f9d 100644 --- a/c-level-advisor/skills/cpo-advisor/SKILL.md +++ b/c-level-advisor/skills/cpo-advisor/SKILL.md @@ -186,7 +186,7 @@ Decompose to fundamental user needs. Question every assumption about what custom ## Communication -All output passes the Internal Quality Loop before reaching the founder (see `agent-protocol/SKILL.md`). +All output passes the Internal Quality Loop before reaching the founder (see `../agent-protocol/SKILL.md`). - Self-verify: source attribution, assumption audit, confidence scoring - Peer-verify: cross-functional claims validated by the owning role - Critic pre-screen: high-stakes decisions reviewed by Executive Mentor diff --git a/c-level-advisor/skills/cro-advisor/SKILL.md b/c-level-advisor/skills/cro-advisor/SKILL.md index e52a3786..bd314059 100644 --- a/c-level-advisor/skills/cro-advisor/SKILL.md +++ b/c-level-advisor/skills/cro-advisor/SKILL.md @@ -169,7 +169,7 @@ Pipeline math must be explicit: leads → MQLs → SQLs → opportunities → cl ## Communication -All output passes the Internal Quality Loop before reaching the founder (see `agent-protocol/SKILL.md`). +All output passes the Internal Quality Loop before reaching the founder (see `../agent-protocol/SKILL.md`). - Self-verify: source attribution, assumption audit, confidence scoring - Peer-verify: cross-functional claims validated by the owning role - Critic pre-screen: high-stakes decisions reviewed by Executive Mentor diff --git a/c-level-advisor/skills/cs-onboard/SKILL.md b/c-level-advisor/skills/cs-onboard/SKILL.md index 3ad0c7fa..e908b96a 100644 --- a/c-level-advisor/skills/cs-onboard/SKILL.md +++ b/c-level-advisor/skills/cs-onboard/SKILL.md @@ -1,6 +1,6 @@ --- name: "cs-onboard" -description: "Founder onboarding interview that captures company context across 7 dimensions. Invoke with /cs:setup for initial interview or /cs:update for quarterly refresh. Generates ~/.claude/company-context.md used by all C-suite advisor skills." +description: "Founder onboarding interview that captures company context across 7 dimensions. Invoke with /cs:setup for initial interview or /cs:update for quarterly refresh. Generates ~/.claude/company-context.md used by all C-suite advisor skills. Use when setting up the C-suite advisors for the first time, or when company context is missing or more than 90 days old — e.g. after a fundraise or pivot." license: MIT metadata: version: 1.0.0 diff --git a/c-level-advisor/skills/cto-advisor/SKILL.md b/c-level-advisor/skills/cto-advisor/SKILL.md index e53d04f8..d42356a5 100644 --- a/c-level-advisor/skills/cto-advisor/SKILL.md +++ b/c-level-advisor/skills/cto-advisor/SKILL.md @@ -238,7 +238,7 @@ Research the technical landscape first. Analyze options against constraints (tim ## Communication -All output passes the Internal Quality Loop before reaching the founder (see `agent-protocol/SKILL.md`). +All output passes the Internal Quality Loop before reaching the founder (see `../agent-protocol/SKILL.md`). - Self-verify: source attribution, assumption audit, confidence scoring - Peer-verify: cross-functional claims validated by the owning role - Critic pre-screen: high-stakes decisions reviewed by Executive Mentor diff --git a/c-level-advisor/skills/decision-logger/SKILL.md b/c-level-advisor/skills/decision-logger/SKILL.md index b29c2694..b5245622 100644 --- a/c-level-advisor/skills/decision-logger/SKILL.md +++ b/c-level-advisor/skills/decision-logger/SKILL.md @@ -46,20 +46,24 @@ python scripts/decision_tracker.py --search "pricing" # Search decisions ## Two-Layer Architecture +Storage follows the canonical two-layer decision memory (see `../agent-protocol/SKILL.md` → "Decision Memory (Canonical Layout)") — the same layout `/cs:decide` writes. + ### Layer 1 — Raw Transcripts -**Location:** `memory/board-meetings/YYYY-MM-DD-raw.md` +**Location:** `~/.claude/decisions/raw/YYYY-MM-DD-.md` - Full Phase 2 agent contributions, Phase 3 critique, Phase 4 synthesis - All debates, including rejected arguments - **NEVER auto-loaded.** Only on explicit founder request. -- Archive after 90 days → `memory/board-meetings/archive/YYYY/` +- Archive after 90 days → `~/.claude/decisions/raw/archive/YYYY/` ### Layer 2 — Approved Decisions -**Location:** `memory/board-meetings/decisions.md` +**Location:** `~/.claude/decisions/approved/` — one record per decision (`YYYY-MM-DD-.md`) plus the append-only index `decisions.md` - ONLY founder-approved decisions, action items, user corrections - **Loaded automatically in Phase 1 of every board meeting** - Append-only. Decisions are never deleted — only superseded. - Managed by Chief of Staff after Phase 5. Never written by agents directly. +Migration: a legacy `memory/board-meetings/` folder may exist from earlier versions; read it for history but write all new entries to `~/.claude/decisions/`. + --- ## Decision Entry Format @@ -83,7 +87,7 @@ python scripts/decision_tracker.py --search "pricing" # Search decisions **Supersedes:** [DATE of previous decision on same topic, if any] **Superseded by:** [Filled in retroactively if overridden later] -**Raw transcript:** memory/board-meetings/[DATE]-raw.md +**Raw transcript:** ~/.claude/decisions/raw/[DATE]-.md ``` --- @@ -115,10 +119,10 @@ To reopen: founder must explicitly say "reopen [topic] from [DATE]". ## Logging Workflow (Post Phase 5) 1. Founder approves synthesis -2. Write Layer 1 raw transcript → `YYYY-MM-DD-raw.md` -3. Check conflicts against `decisions.md` +2. Write Layer 1 raw transcript → `~/.claude/decisions/raw/YYYY-MM-DD-.md` +3. Check conflicts against `~/.claude/decisions/approved/decisions.md` 4. Surface conflicts → wait for founder resolution -5. Append approved entries to `decisions.md` +5. Write the approved record to `~/.claude/decisions/approved/YYYY-MM-DD-.md` and append to the index `decisions.md` 6. Confirm: decisions logged, actions tracked, DO_NOT_RESURFACE flags added --- @@ -136,10 +140,11 @@ Never delete completed items. The history is the record. ## File Structure ``` -memory/board-meetings/ -├── decisions.md # Layer 2: append-only, founder-approved -├── YYYY-MM-DD-raw.md # Layer 1: full transcript per meeting -└── archive/YYYY/ # Raw files after 90 days +~/.claude/decisions/ +├── raw/YYYY-MM-DD-.md # Layer 1: full transcript per meeting +├── raw/archive/YYYY/ # Raw files after 90 days +├── approved/YYYY-MM-DD-.md # Layer 2: one record per approved decision +└── approved/decisions.md # Layer 2 index: append-only, founder-approved ``` --- diff --git a/c-level-advisor/skills/decision-logger/scripts/decision_tracker.py b/c-level-advisor/skills/decision-logger/scripts/decision_tracker.py index 7a9020df..36a68983 100644 --- a/c-level-advisor/skills/decision-logger/scripts/decision_tracker.py +++ b/c-level-advisor/skills/decision-logger/scripts/decision_tracker.py @@ -3,7 +3,8 @@ decision_tracker.py — Board Meeting Decision Parser & Reporter Part of the C-Level Advisor / Decision Logger skill. -Parses memory/board-meetings/decisions.md and produces actionable reports. +Parses the Layer 2 index ~/.claude/decisions/approved/decisions.md and produces actionable reports. +(Legacy location memory/board-meetings/decisions.md still works via --file.) Stdlib only. No dependencies. Usage: @@ -471,7 +472,7 @@ This file contains ONLY founder-approved decisions. **Supersedes:** **Superseded by:** -**Raw transcript:** memory/board-meetings/2026-02-15-raw.md +**Raw transcript:** ~/.claude/decisions/raw/2026-02-15-pricing-tier-restructure.md --- @@ -496,7 +497,7 @@ This file contains ONLY founder-approved decisions. **Supersedes:** **Superseded by:** -**Raw transcript:** memory/board-meetings/2026-02-28-raw.md +**Raw transcript:** ~/.claude/decisions/raw/2026-02-28-enterprise-sales-hire.md --- @@ -521,7 +522,7 @@ This file contains ONLY founder-approved decisions. **Supersedes:** **Superseded by:** -**Raw transcript:** memory/board-meetings/2026-03-04-raw.md +**Raw transcript:** ~/.claude/decisions/raw/2026-03-04-eu-expansion.md """ @@ -537,7 +538,7 @@ def load_decisions(decisions_path: Path, demo: bool) -> list[Decision]: else: print(f" ⚠️ decisions.md not found at: {decisions_path}") print(f" Run with --demo to see sample output.") - print(f" To initialize: mkdir -p memory/board-meetings && touch memory/board-meetings/decisions.md") + print(f" To initialize: mkdir -p ~/.claude/decisions/approved && touch ~/.claude/decisions/approved/decisions.md") sys.exit(1) return parse_decisions(content) @@ -548,8 +549,8 @@ def main(): formatter_class=argparse.RawDescriptionHelpFormatter, epilog=__doc__, ) - parser.add_argument("--file", default="memory/board-meetings/decisions.md", - help="Path to decisions.md (default: memory/board-meetings/decisions.md)") + parser.add_argument("--file", default=os.path.expanduser("~/.claude/decisions/approved/decisions.md"), + help="Path to decisions.md (default: ~/.claude/decisions/approved/decisions.md)") parser.add_argument("--demo", action="store_true", help="Run with built-in sample data (no file needed)") parser.add_argument("--summary", action="store_true", diff --git a/c-level-advisor/skills/decision-logger/templates/decision-entry.md b/c-level-advisor/skills/decision-logger/templates/decision-entry.md index e83a2af7..0412fa80 100644 --- a/c-level-advisor/skills/decision-logger/templates/decision-entry.md +++ b/c-level-advisor/skills/decision-logger/templates/decision-entry.md @@ -1,6 +1,6 @@ # Decision Entry Template -Single entry for `memory/board-meetings/decisions.md`. +Single entry for the Layer 2 index `~/.claude/decisions/approved/decisions.md`. Copy this block and fill it in after each approved board decision. --- @@ -32,7 +32,7 @@ Copy this block and fill it in after each approved board decision. **Supersedes:** **Superseded by:** -**Raw transcript:** memory/board-meetings/[YYYY-MM-DD]-raw.md +**Raw transcript:** ~/.claude/decisions/raw/[YYYY-MM-DD]-.md ``` --- diff --git a/c-level-advisor/skills/general-counsel-advisor/SKILL.md b/c-level-advisor/skills/general-counsel-advisor/SKILL.md index 9f562b23..1d1cef3d 100644 --- a/c-level-advisor/skills/general-counsel-advisor/SKILL.md +++ b/c-level-advisor/skills/general-counsel-advisor/SKILL.md @@ -142,11 +142,11 @@ See `references/ip_and_regulatory.md` for sequencing. ## Adjacent Skills -- `../ciso-advisor/` — Compliance overlap (SOC 2, ISO 27001, HIPAA technical safeguards) -- `../cfo-advisor/` — Term sheet → dilution math -- `../ma-playbook/` — Acquisition agreements, integration playbooks -- `../../../ra-qm-team/` — ISO 13485, MDR, FDA 510(k), GDPR execution -- `../../c-level-agents/skills/gc-review/SKILL.md` — `/cs:gc-review` slash command +- `c-level-advisor/skills/ciso-advisor/` — Compliance overlap (SOC 2, ISO 27001, HIPAA technical safeguards) +- `c-level-advisor/skills/cfo-advisor/` — Term sheet → dilution math +- `c-level-advisor/skills/ma-playbook/` — Acquisition agreements, integration playbooks +- `ra-qm-team/` — ISO 13485, MDR, FDA 510(k), GDPR execution +- `c-level-advisor/c-level-agents/skills/gc-review/SKILL.md` — `/cs:gc-review` slash command ## References diff --git a/c-level-advisor/skills/ma-playbook/SKILL.md b/c-level-advisor/skills/ma-playbook/SKILL.md index 4abdeafe..a5b4f86a 100644 --- a/c-level-advisor/skills/ma-playbook/SKILL.md +++ b/c-level-advisor/skills/ma-playbook/SKILL.md @@ -41,10 +41,15 @@ M&A, mergers and acquisitions, due diligence, acquisition, acqui-hire, integrati | Customers | Churn rate, NPS, contract terms | High churn, short contracts | ### Valuation Approaches -- **Revenue multiple:** Industry-dependent (2-15x ARR for SaaS) -- **Comparable transactions:** What similar companies sold for + +The ranges below are **illustrative, not current market data** — always verify against current market comps before using them in a model or negotiation. + +- **Revenue multiple:** Industry-dependent (illustrative range: 2-15x ARR for SaaS, varying with growth rate, NRR, and rate environment) +- **Comparable transactions:** What similar companies sold for — the most defensible anchor - **DCF:** For profitable companies only (most startups: use multiples) -- **Acqui-hire:** $1-3M per engineer in hot markets +- **Acqui-hire:** Illustrative range: $1-3M per engineer in hot talent markets + +**Sources to verify against (check the latest edition):** the SaaS Capital Index (private SaaS revenue multiples, updated monthly), Software Equity Group (SEG) Annual/Quarterly SaaS M&A Reports (transaction multiples), and Aventis Advisors' SaaS valuation multiples reports. Cross-check at least two before anchoring a price. ### Integration Frameworks See `references/integration-playbook.md` for the 100-day integration plan. @@ -82,12 +87,24 @@ See `references/integration-playbook.md` for the 100-day integration plan. - Integration plan doesn't exist or is "we'll figure it out" - Valuation based on projections, not actuals +## Verification Loop (before any LOI or signature) + +This skill frames the deal; two sibling skills verify it. Hand off — don't duplicate: + +1. **Legal terms** → `general-counsel-advisor`: run the LOI/term sheet through `../general-counsel-advisor/scripts/term_sheet_analyzer.py` (12-dimension 0-100 score) and the definitive docs through `../general-counsel-advisor/scripts/contract_risk_scanner.py` (12 founder-killer patterns: earnout traps, uncapped indemnity, vague IP, etc.). Any 🔴 finding goes to outside counsel before signing. +2. **Data diligence** → `chief-data-officer-advisor`: run `../chief-data-officer-advisor/scripts/ai_training_data_audit.py` (training-data rights, GDPR Art. 6 basis) and `../chief-data-officer-advisor/scripts/data_asset_valuator.py` (data-asset value, M&A multiplier with carve-out penalties) on the target's data estate. Undocumented consent provenance is a price-reduction or walk-away item. +3. **Valuation math** → `cfo-advisor` tools for the quantitative model; this playbook stays qualitative. + +Loop the findings back into the negotiation-points table above before the next counter. + ## Integration with C-Suite Roles | Role | Contribution to M&A | |------|-------------------| | CEO | Strategic rationale, negotiation lead | | CFO | Valuation, deal structure, financing | +| GC | LOI/term sheet review, contract risk scan, regulatory triggers | +| CDO | Data diligence: training-data rights, data-asset valuation | | CTO | Technical due diligence, integration architecture | | CHRO | People due diligence, retention planning | | COO | Integration execution, process merge | @@ -96,3 +113,5 @@ See `references/integration-playbook.md` for the 100-day integration plan. ## Resources - `references/integration-playbook.md` — 100-day post-acquisition integration plan - `references/due-diligence-checklist.md` — comprehensive DD checklist by domain +- `../general-counsel-advisor/SKILL.md` — term sheet analyzer + contract risk scanner +- `../chief-data-officer-advisor/SKILL.md` — data diligence + data-asset valuation diff --git a/c-level-advisor/skills/org-health-diagnostic/SKILL.md b/c-level-advisor/skills/org-health-diagnostic/SKILL.md index a1c36d9b..ff1af94c 100644 --- a/c-level-advisor/skills/org-health-diagnostic/SKILL.md +++ b/c-level-advisor/skills/org-health-diagnostic/SKILL.md @@ -26,11 +26,10 @@ python scripts/health_scorer.py # Guided CLI — enter metrics, get score python scripts/health_scorer.py --json # Output raw JSON for integration ``` -Or describe your metrics: -``` -/health [paste your key metrics or answer prompts] -/health:dimension [financial|revenue|product|engineering|people|ops|security|market] -``` +Or describe your metrics in natural language: + +> "Run an org health check" — paste your key metrics or answer prompts +> "Score our [financial|revenue|product|engineering|people|ops|security|market] health" — single-dimension deep dive ## The 8 Dimensions diff --git a/c-level-advisor/skills/scenario-war-room/SKILL.md b/c-level-advisor/skills/scenario-war-room/SKILL.md index ad6c5428..d52e33ea 100644 --- a/c-level-advisor/skills/scenario-war-room/SKILL.md +++ b/c-level-advisor/skills/scenario-war-room/SKILL.md @@ -25,12 +25,11 @@ scenario planning, war room, what-if analysis, risk modeling, cascading effects, python scripts/scenario_modeler.py # Interactive scenario builder with cascade modeling ``` -Or describe the scenario: -``` -/war-room "What if we lose our top customer AND miss the Q3 fundraise?" -/war-room "What if 3 engineers quit AND we need to ship by Q3?" -/war-room "What if our market shrinks 30% AND a competitor raises $50M?" -``` +Or describe the scenario in natural language: + +> "What if we lose our top customer AND miss the Q3 fundraise?" +> "What if 3 engineers quit AND we need to ship by Q3?" +> "What if our market shrinks 30% AND a competitor raises $50M?" ## What This Is Not diff --git a/c-level-advisor/skills/vpe-advisor/SKILL.md b/c-level-advisor/skills/vpe-advisor/SKILL.md index 3319a2f9..7792c1a2 100644 --- a/c-level-advisor/skills/vpe-advisor/SKILL.md +++ b/c-level-advisor/skills/vpe-advisor/SKILL.md @@ -208,13 +208,13 @@ python ../../skills/vpe-advisor/scripts/eng_team_structure_designer.py team.json ## Adjacent Skills -- `../cto-advisor/` — Architecture, scaling cliffs, tech debt strategy (CTO decides what to build; VPE decides how to ship) -- `../chro-advisor/` — Hiring systems (ladders, bands, leveling rubrics company-wide); VPE owns eng-specific funnel execution -- `../coo-advisor/` — Operating cadence company-wide; VPE owns eng-specific cadence -- `../../../engineering/slo-architect/` — SLO design (tactical; VPE owns the policy that SLOs are required) -- `../../../engineering/chaos-engineering/` — Chaos experiment design (tactical resilience) -- `../../../engineering/feature-flags-architect/` — Progressive delivery (tactical deployment) -- `../../../engineering/kubernetes-operator/` — K8s operator pattern (tactical infra) +- `c-level-advisor/skills/cto-advisor/` — Architecture, scaling cliffs, tech debt strategy (CTO decides what to build; VPE decides how to ship) +- `c-level-advisor/skills/chro-advisor/` — Hiring systems (ladders, bands, leveling rubrics company-wide); VPE owns eng-specific funnel execution +- `c-level-advisor/skills/coo-advisor/` — Operating cadence company-wide; VPE owns eng-specific cadence +- `engineering/skills/slo-architect/` — SLO design (tactical; VPE owns the policy that SLOs are required) +- `engineering/skills/chaos-engineering/` — Chaos experiment design (tactical resilience) +- `engineering/skills/feature-flags-architect/` — Progressive delivery (tactical deployment) +- `engineering/skills/kubernetes-operator/` — K8s operator pattern (tactical infra) - `cs-engineering-lead` agent — Day-to-day incident + on-call coordination (VPE owns the operating model that engineering-lead executes) ## References diff --git a/c-level-advisor/vpe-advisor/skills/vpe-advisor/SKILL.md b/c-level-advisor/vpe-advisor/skills/vpe-advisor/SKILL.md index 3319a2f9..7792c1a2 100644 --- a/c-level-advisor/vpe-advisor/skills/vpe-advisor/SKILL.md +++ b/c-level-advisor/vpe-advisor/skills/vpe-advisor/SKILL.md @@ -208,13 +208,13 @@ python ../../skills/vpe-advisor/scripts/eng_team_structure_designer.py team.json ## Adjacent Skills -- `../cto-advisor/` — Architecture, scaling cliffs, tech debt strategy (CTO decides what to build; VPE decides how to ship) -- `../chro-advisor/` — Hiring systems (ladders, bands, leveling rubrics company-wide); VPE owns eng-specific funnel execution -- `../coo-advisor/` — Operating cadence company-wide; VPE owns eng-specific cadence -- `../../../engineering/slo-architect/` — SLO design (tactical; VPE owns the policy that SLOs are required) -- `../../../engineering/chaos-engineering/` — Chaos experiment design (tactical resilience) -- `../../../engineering/feature-flags-architect/` — Progressive delivery (tactical deployment) -- `../../../engineering/kubernetes-operator/` — K8s operator pattern (tactical infra) +- `c-level-advisor/skills/cto-advisor/` — Architecture, scaling cliffs, tech debt strategy (CTO decides what to build; VPE decides how to ship) +- `c-level-advisor/skills/chro-advisor/` — Hiring systems (ladders, bands, leveling rubrics company-wide); VPE owns eng-specific funnel execution +- `c-level-advisor/skills/coo-advisor/` — Operating cadence company-wide; VPE owns eng-specific cadence +- `engineering/skills/slo-architect/` — SLO design (tactical; VPE owns the policy that SLOs are required) +- `engineering/skills/chaos-engineering/` — Chaos experiment design (tactical resilience) +- `engineering/skills/feature-flags-architect/` — Progressive delivery (tactical deployment) +- `engineering/skills/kubernetes-operator/` — K8s operator pattern (tactical infra) - `cs-engineering-lead` agent — Day-to-day incident + on-call coordination (VPE owns the operating model that engineering-lead executes) ## References diff --git a/commands/a11y-audit.md b/commands/a11y-audit.md index dbafa25f..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 @@ -40,7 +41,7 @@ For each finding (starting with critical): 1. Read the affected file 2. Show the violation with context (before) -3. Apply the fix from `references/framework-a11y-patterns.md` +3. Apply the fix from `engineering-team/a11y-audit/skills/a11y-audit/references/framework-a11y-patterns.md` 4. Show the result (after) **Auto-fixable issues** (apply without asking): @@ -76,9 +77,9 @@ Generate a markdown report at `a11y-report.md`: ## Skill Reference -- `engineering-team/a11y-audit/SKILL.md` -- `engineering-team/a11y-audit/scripts/a11y_scanner.py` -- `engineering-team/a11y-audit/scripts/contrast_checker.py` -- `engineering-team/a11y-audit/references/wcag-quick-ref.md` -- `engineering-team/a11y-audit/references/aria-patterns.md` -- `engineering-team/a11y-audit/references/framework-a11y-patterns.md` +- `engineering-team/a11y-audit/skills/a11y-audit/SKILL.md` +- `engineering-team/a11y-audit/skills/a11y-audit/scripts/a11y_scanner.py` +- `engineering-team/a11y-audit/skills/a11y-audit/scripts/contrast_checker.py` +- `engineering-team/a11y-audit/skills/a11y-audit/references/wcag-quick-ref.md` +- `engineering-team/a11y-audit/skills/a11y-audit/references/aria-patterns.md` +- `engineering-team/a11y-audit/skills/a11y-audit/references/framework-a11y-patterns.md` diff --git a/commands/changelog.md b/commands/changelog.md index e9b04f22..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 @@ -23,8 +24,8 @@ Generate Keep a Changelog entries from git history and validate commit message f ``` ## Scripts -- `engineering/changelog-generator/scripts/generate_changelog.py` — Parse commits, render changelog (`--from-tag`, `--to-tag`, `--from-ref`, `--to-ref`, `--format markdown|json`) -- `engineering/changelog-generator/scripts/commit_linter.py` — Validate conventional commit format (`--from-ref`, `--to-ref`, `--strict`, `--format text|json`) +- `engineering/skills/changelog-generator/scripts/generate_changelog.py` — Parse commits, render changelog (`--from-tag`, `--to-tag`, `--from-ref`, `--to-ref`, `--format markdown|json`) +- `engineering/skills/changelog-generator/scripts/commit_linter.py` — Validate conventional commit format (`--from-ref`, `--to-ref`, `--strict`, `--format text|json`) ## Skill Reference -→ `engineering/changelog-generator/SKILL.md` +→ `engineering/skills/changelog-generator/SKILL.md` diff --git a/commands/code-to-prd.md b/commands/code-to-prd.md index 1bace0d0..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 @@ -72,7 +73,7 @@ A `prd/` directory containing: ## Skill Reference -- `product-team/code-to-prd/SKILL.md` -- `product-team/code-to-prd/scripts/codebase_analyzer.py` -- `product-team/code-to-prd/scripts/prd_scaffolder.py` -- `product-team/code-to-prd/references/prd-quality-checklist.md` +- `product-team/code-to-prd/skills/code-to-prd/SKILL.md` +- `product-team/code-to-prd/skills/code-to-prd/scripts/codebase_analyzer.py` +- `product-team/code-to-prd/skills/code-to-prd/scripts/prd_scaffolder.py` +- `product-team/code-to-prd/skills/code-to-prd/references/prd-quality-checklist.md` diff --git a/commands/competitive-matrix.md b/commands/competitive-matrix.md index a60466c4..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 @@ -34,7 +35,7 @@ Build competitive matrices with weighted scoring, gap analysis, and market posit ``` ## Scripts -- `product-team/competitive-teardown/scripts/competitive_matrix_builder.py` — Matrix builder +- `product-team/skills/competitive-teardown/scripts/competitive_matrix_builder.py` — Matrix builder ## Skill Reference -→ `product-team/competitive-teardown/SKILL.md` +→ `product-team/skills/competitive-teardown/SKILL.md` diff --git a/commands/cs-aeo.md b/commands/cs-aeo.md index b67c5d31..ec9e2d63 100644 --- a/commands/cs-aeo.md +++ b/commands/cs-aeo.md @@ -154,8 +154,8 @@ Content for YMYL topics scoring below threshold is unlikely to be cited regardle ## Related -- Agent: [`cs-aeo`](../agents/cs-aeo.md) -- Skill: [`aeo`](../skills/aeo/SKILL.md) +- Agent: [`cs-aeo`](agents/marketing/cs-aeo.md) +- Skill: [`aeo`](marketing-skill/skills/aeo/SKILL.md) - Companion: `/cs:seo-audit` (SEO + AEO often run together) - Source: ported from [`alirezarezvani/aeo-box`](https://github.com/alirezarezvani/aeo-box) 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/cs-webinar.md b/commands/cs-webinar.md index d05cc99e..d1ed5118 100644 --- a/commands/cs-webinar.md +++ b/commands/cs-webinar.md @@ -32,7 +32,7 @@ The `cs-webinar` command is the **entry point for webinar workflows**: plan → Walks the intake, locks the promise + format, sizes the funnel backward from the business goal, builds the promotion runway, and designs show-up + live-to-close + follow-up. Delivers a full plan -using `templates/webinar-plan-template.md`. +using `marketing-skill/skills/webinar-marketing/templates/webinar-plan-template.md`. ### `rescue` — Diagnose and fix an underperforming webinar diff --git a/commands/financial-health.md b/commands/financial-health.md index 10a4e1fc..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 @@ -26,13 +27,13 @@ Analyze financial statements, build valuation models, assess budget variances, a ``` ## Scripts -- `finance/financial-analyst/scripts/ratio_calculator.py` — Profitability, liquidity, leverage, efficiency, valuation ratios -- `finance/financial-analyst/scripts/dcf_valuation.py` — DCF enterprise and equity valuation with sensitivity analysis -- `finance/financial-analyst/scripts/budget_variance_analyzer.py` — Actual vs budget vs prior year variance analysis -- `finance/financial-analyst/scripts/forecast_builder.py` — Driver-based revenue forecasting with scenario modeling +- `finance/skills/financial-analyst/scripts/ratio_calculator.py` — Profitability, liquidity, leverage, efficiency, valuation ratios +- `finance/skills/financial-analyst/scripts/dcf_valuation.py` — DCF enterprise and equity valuation with sensitivity analysis +- `finance/skills/financial-analyst/scripts/budget_variance_analyzer.py` — Actual vs budget vs prior year variance analysis +- `finance/skills/financial-analyst/scripts/forecast_builder.py` — Driver-based revenue forecasting with scenario modeling ## Skill Reference -→ `finance/financial-analyst/SKILL.md` +→ `finance/skills/financial-analyst/SKILL.md` ## Related Commands - `/saas-health` — SaaS-specific metrics (ARR, MRR, churn, CAC, LTV, Quick Ratio) 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 704ef5c4..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 @@ -33,45 +34,45 @@ Google Workspace CLI administration via the `gws` CLI. Run setup diagnostics, se ## Scripts -- `engineering-team/google-workspace-cli/scripts/gws_doctor.py` — Pre-flight diagnostics -- `engineering-team/google-workspace-cli/scripts/auth_setup_guide.py` — Auth setup guide -- `engineering-team/google-workspace-cli/scripts/gws_recipe_runner.py` — Recipe catalog & runner -- `engineering-team/google-workspace-cli/scripts/workspace_audit.py` — Security audit -- `engineering-team/google-workspace-cli/scripts/output_analyzer.py` — JSON/NDJSON analyzer +- `engineering-team/google-workspace-cli/skills/google-workspace-cli/scripts/gws_doctor.py` — Pre-flight diagnostics +- `engineering-team/google-workspace-cli/skills/google-workspace-cli/scripts/auth_setup_guide.py` — Auth setup guide +- `engineering-team/google-workspace-cli/skills/google-workspace-cli/scripts/gws_recipe_runner.py` — Recipe catalog & runner +- `engineering-team/google-workspace-cli/skills/google-workspace-cli/scripts/workspace_audit.py` — Security audit +- `engineering-team/google-workspace-cli/skills/google-workspace-cli/scripts/output_analyzer.py` — JSON/NDJSON analyzer ## Subcommands ### setup Run pre-flight diagnostics and auth validation. ```bash -python3 engineering-team/google-workspace-cli/scripts/gws_doctor.py [--json] -python3 engineering-team/google-workspace-cli/scripts/auth_setup_guide.py --validate [--json] +python3 engineering-team/google-workspace-cli/skills/google-workspace-cli/scripts/gws_doctor.py [--json] +python3 engineering-team/google-workspace-cli/skills/google-workspace-cli/scripts/auth_setup_guide.py --validate [--json] ``` ### audit Run security and configuration audit. ```bash -python3 engineering-team/google-workspace-cli/scripts/workspace_audit.py [--services gmail,drive,calendar] [--json] +python3 engineering-team/google-workspace-cli/skills/google-workspace-cli/scripts/workspace_audit.py [--services gmail,drive,calendar] [--json] ``` ### recipe Browse, search, and execute the 43 built-in gws recipes. ```bash -python3 engineering-team/google-workspace-cli/scripts/gws_recipe_runner.py --list [--persona ] [--json] -python3 engineering-team/google-workspace-cli/scripts/gws_recipe_runner.py --search [--json] -python3 engineering-team/google-workspace-cli/scripts/gws_recipe_runner.py --describe -python3 engineering-team/google-workspace-cli/scripts/gws_recipe_runner.py --run [--dry-run] +python3 engineering-team/google-workspace-cli/skills/google-workspace-cli/scripts/gws_recipe_runner.py --list [--persona ] [--json] +python3 engineering-team/google-workspace-cli/skills/google-workspace-cli/scripts/gws_recipe_runner.py --search [--json] +python3 engineering-team/google-workspace-cli/skills/google-workspace-cli/scripts/gws_recipe_runner.py --describe +python3 engineering-team/google-workspace-cli/skills/google-workspace-cli/scripts/gws_recipe_runner.py --run [--dry-run] ``` ### analyze Parse, filter, and aggregate JSON output from any gws command. ```bash -gws --json | python3 engineering-team/google-workspace-cli/scripts/output_analyzer.py [options] -python3 engineering-team/google-workspace-cli/scripts/output_analyzer.py --demo --format table +gws --json | python3 engineering-team/google-workspace-cli/skills/google-workspace-cli/scripts/output_analyzer.py [options] +python3 engineering-team/google-workspace-cli/skills/google-workspace-cli/scripts/output_analyzer.py --demo --format table ``` ## Skill Reference --> `engineering-team/google-workspace-cli/SKILL.md` +-> `engineering-team/google-workspace-cli/skills/google-workspace-cli/SKILL.md` ## Related Commands - No direct dependencies (self-contained Google Workspace skill) diff --git a/commands/karpathy-check.md b/commands/karpathy-check.md index cb060b0d..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 @@ -16,8 +17,8 @@ Review your staged changes (or last commit) against Karpathy's 4 coding principl ## What it runs -1. **Principle #2 (Simplicity):** `scripts/complexity_checker.py` on all changed files — detects over-engineering, premature abstractions, deep nesting, long functions -2. **Principle #3 (Surgical):** `scripts/diff_surgeon.py` on the diff — detects comment-only changes, whitespace noise, style drift, drive-by refactors +1. **Principle #2 (Simplicity):** `engineering/karpathy-coder/skills/karpathy-coder/scripts/complexity_checker.py` on all changed files — detects over-engineering, premature abstractions, deep nesting, long functions +2. **Principle #3 (Surgical):** `engineering/karpathy-coder/skills/karpathy-coder/scripts/diff_surgeon.py` on the diff — detects comment-only changes, whitespace noise, style drift, drive-by refactors 3. **Principles #1 + #4 (Think + Goals):** The `karpathy-reviewer` agent reads the diff and applies human-judgment checks — hidden assumptions, missing verification ## Output @@ -36,11 +37,11 @@ Dispatches the `karpathy-reviewer` agent. See `agents/karpathy-reviewer.md`. ## Scripts -- `engineering/karpathy-coder/scripts/complexity_checker.py` -- `engineering/karpathy-coder/scripts/diff_surgeon.py` -- `engineering/karpathy-coder/scripts/assumption_linter.py` -- `engineering/karpathy-coder/scripts/goal_verifier.py` +- `engineering/karpathy-coder/skills/karpathy-coder/scripts/complexity_checker.py` +- `engineering/karpathy-coder/skills/karpathy-coder/scripts/diff_surgeon.py` +- `engineering/karpathy-coder/skills/karpathy-coder/scripts/assumption_linter.py` +- `engineering/karpathy-coder/skills/karpathy-coder/scripts/goal_verifier.py` ## Skill Reference -→ `engineering/karpathy-coder/SKILL.md` +→ `engineering/karpathy-coder/skills/karpathy-coder/SKILL.md` diff --git a/commands/okr.md b/commands/okr.md index 5d5f9105..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 @@ -31,7 +31,7 @@ Pass a strategy keyword directly. The generator produces company, department, an ``` ## Scripts -- `product-team/product-strategist/scripts/okr_cascade_generator.py` — OKR cascade generator (` [--teams "A,B,C"] [--contribution 0.3] [--json]`) +- `product-team/skills/product-strategist/scripts/okr_cascade_generator.py` — OKR cascade generator (` [--teams "A,B,C"] [--contribution 0.3] [--json]`) ## Skill Reference -> `product-team/product-strategist/SKILL.md` +> `product-team/skills/product-strategist/SKILL.md` diff --git a/commands/persona.md b/commands/persona.md index c37b1e00..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 @@ -34,7 +34,7 @@ Interactive mode prompts for product context. Alternatively, provide context inl ``` ## Scripts -- `product-team/ux-researcher-designer/scripts/persona_generator.py` — Persona generator (positional `json` arg for JSON output) +- `product-team/skills/ux-researcher-designer/scripts/persona_generator.py` — Persona generator (positional `json` arg for JSON output) ## Skill Reference -> `product-team/ux-researcher-designer/SKILL.md` +> `product-team/skills/ux-researcher-designer/SKILL.md` diff --git a/commands/pipeline.md b/commands/pipeline.md index 727f8688..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 @@ -23,8 +24,8 @@ Detect project stack and generate CI/CD pipeline configurations for GitHub Actio ``` ## Scripts -- `engineering/ci-cd-pipeline-builder/scripts/stack_detector.py` — Detect stack and tooling (`--repo `, `--format text|json`) -- `engineering/ci-cd-pipeline-builder/scripts/pipeline_generator.py` — Generate pipeline YAML (`--platform github|gitlab`, `--repo `, `--input `, `--output `) +- `engineering/skills/ci-cd-pipeline-builder/scripts/stack_detector.py` — Detect stack and tooling (`--repo `, `--format text|json`) +- `engineering/skills/ci-cd-pipeline-builder/scripts/pipeline_generator.py` — Generate pipeline YAML (`--platform github|gitlab`, `--repo `, `--input `, `--output `) ## Skill Reference -→ `engineering/ci-cd-pipeline-builder/SKILL.md` +→ `engineering/skills/ci-cd-pipeline-builder/SKILL.md` diff --git a/commands/plugin-audit.md b/commands/plugin-audit.md index 04c3573a..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 @@ -60,7 +61,7 @@ Auditing: code-to-prd Run the skill-tester validator. ```bash -python3 engineering/skill-tester/scripts/skill_validator.py {skill_path} --tier {detected_tier} --json +python3 engineering/skills/skill-tester/scripts/skill_validator.py {skill_path} --tier {detected_tier} --json ``` Parse the JSON output. Extract: @@ -83,7 +84,7 @@ Parse the JSON output. Extract: Run the quality scorer. ```bash -python3 engineering/skill-tester/scripts/quality_scorer.py {skill_path} --detailed --json +python3 engineering/skills/skill-tester/scripts/quality_scorer.py {skill_path} --detailed --json ``` Parse the JSON output. Extract: @@ -100,7 +101,7 @@ Parse the JSON output. Extract: If the skill has `scripts/` with `.py` files, run the script tester. ```bash -python3 engineering/skill-tester/scripts/script_tester.py {skill_path} --json --verbose +python3 engineering/skills/skill-tester/scripts/script_tester.py {skill_path} --json --verbose ``` Parse the JSON output. For each script, extract: @@ -118,7 +119,7 @@ Parse the JSON output. For each script, extract: Run the skill security auditor. ```bash -python3 engineering/skill-security-auditor/scripts/skill_security_auditor.py {skill_path} --strict --json +python3 engineering/skills/skill-security-auditor/scripts/skill_security_auditor.py {skill_path} --strict --json ``` Parse the JSON output. Extract: @@ -303,10 +304,10 @@ Present results as a structured table: | Tool | Path | |------|------| -| Skill Validator | `engineering/skill-tester/scripts/skill_validator.py` | -| Quality Scorer | `engineering/skill-tester/scripts/quality_scorer.py` | -| Script Tester | `engineering/skill-tester/scripts/script_tester.py` | -| Security Auditor | `engineering/skill-security-auditor/scripts/skill_security_auditor.py` | +| Skill Validator | `engineering/skills/skill-tester/scripts/skill_validator.py` | +| Quality Scorer | `engineering/skills/skill-tester/scripts/quality_scorer.py` | +| Script Tester | `engineering/skills/skill-tester/scripts/script_tester.py` | +| Security Auditor | `engineering/skills/skill-security-auditor/scripts/skill_security_auditor.py` | | Quality Standards | `standards/quality/quality-standards.md` | | Security Standards | `standards/security/security-standards.md` | | Git Standards | `standards/git/git-workflow-standards.md` | diff --git a/commands/prd.md b/commands/prd.md index 2c005423..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/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 9bc4d4cc..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 @@ -36,8 +37,8 @@ Generate portfolio health dashboards and risk matrices for project oversight. ``` ## Scripts -- `project-management/senior-pm/scripts/project_health_dashboard.py` — Health dashboard (` [--format text|json]`) -- `project-management/senior-pm/scripts/risk_matrix_analyzer.py` — Risk matrix analyzer (` [--format text|json]`) +- `project-management/skills/senior-pm/scripts/project_health_dashboard.py` — Health dashboard (` [--format text|json]`) +- `project-management/skills/senior-pm/scripts/risk_matrix_analyzer.py` — Risk matrix analyzer (` [--format text|json]`) ## Skill Reference -> `project-management/senior-pm/SKILL.md` +> `project-management/skills/senior-pm/SKILL.md` diff --git a/commands/retro.md b/commands/retro.md index c7656625..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 @@ -36,7 +36,7 @@ Analyze retrospective data for recurring themes, sentiment trends, and action it ``` ## Scripts -- `project-management/scrum-master/scripts/retrospective_analyzer.py` — Retrospective analyzer (` [--format text|json]`) +- `project-management/skills/scrum-master/scripts/retrospective_analyzer.py` — Retrospective analyzer (` [--format text|json]`) ## Skill Reference -> `project-management/scrum-master/SKILL.md` +> `project-management/skills/scrum-master/SKILL.md` diff --git a/commands/rice.md b/commands/rice.md index 726e0f91..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 @@ -33,7 +33,7 @@ Mobile app,20000,3,0.5,13 ``` ## Scripts -- `product-team/product-manager-toolkit/scripts/rice_prioritizer.py` — RICE prioritizer (` [--capacity N] [--output text|json|csv]`) +- `product-team/skills/product-manager-toolkit/scripts/rice_prioritizer.py` — RICE prioritizer (` [--capacity N] [--output text|json|csv]`) ## Skill Reference -> `product-team/product-manager-toolkit/SKILL.md` +> `product-team/skills/product-manager-toolkit/SKILL.md` diff --git a/commands/saas-health.md b/commands/saas-health.md index a5ac6e49..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 @@ -24,12 +25,12 @@ Calculate SaaS financial health metrics from raw business numbers, benchmark aga ``` ## Scripts -- `finance/saas-metrics-coach/scripts/metrics_calculator.py` — Core SaaS metrics (ARR, MRR, churn, CAC, LTV, NRR, payback) -- `finance/saas-metrics-coach/scripts/quick_ratio_calculator.py` — Growth efficiency ratio -- `finance/saas-metrics-coach/scripts/unit_economics_simulator.py` — 12-month forward projection +- `finance/skills/saas-metrics-coach/scripts/metrics_calculator.py` — Core SaaS metrics (ARR, MRR, churn, CAC, LTV, NRR, payback) +- `finance/skills/saas-metrics-coach/scripts/quick_ratio_calculator.py` — Growth efficiency ratio +- `finance/skills/saas-metrics-coach/scripts/unit_economics_simulator.py` — 12-month forward projection ## Skill Reference -→ `finance/saas-metrics-coach/SKILL.md` +→ `finance/skills/saas-metrics-coach/SKILL.md` ## Related Commands - `/financial-health` — Traditional financial analysis (ratios, DCF, budgets) diff --git a/commands/seo-auditor.md b/commands/seo-auditor.md index 167a3048..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 @@ -91,7 +92,7 @@ For every file with YAML frontmatter, check and fix: Run on each file that has HTML output in `site/`: ```bash -python3 marketing-skill/seo-audit/scripts/seo_checker.py --file site/{path}/index.html +python3 marketing-skill/skills/seo-audit/scripts/seo_checker.py --file site/{path}/index.html ``` Parse the score. Flag any page scoring below 60. @@ -117,7 +118,7 @@ For each target file, analyze and improve: Run the content scorer on each file: ```bash -python3 marketing-skill/content-production/scripts/content_scorer.py {file_path} +python3 marketing-skill/skills/content-production/scripts/content_scorer.py {file_path} ``` Check scores for: @@ -138,10 +139,10 @@ Check scores for: Run the humanizer scorer on non-generated content (README.md files, static pages): ```bash -python3 marketing-skill/content-humanizer/scripts/humanizer_scorer.py {file_path} +python3 marketing-skill/skills/content-humanizer/scripts/humanizer_scorer.py {file_path} ``` -Flag pages scoring below 50 (too AI-sounding). For these pages, apply voice techniques from `marketing-skill/content-humanizer/references/voice-techniques.md`: +Flag pages scoring below 50 (too AI-sounding). For these pages, apply voice techniques from `marketing-skill/skills/content-humanizer/references/voice-techniques.md`: - Replace AI clichés ("delve into", "leverage", "it's important to note") - Vary sentence length - Add specific examples instead of generic statements @@ -242,7 +243,7 @@ This regenerates `site/sitemap.xml` automatically (MkDocs Material generates it Check the generated sitemap: ```bash -python3 marketing-skill/site-architecture/scripts/sitemap_analyzer.py site/sitemap.xml +python3 marketing-skill/skills/site-architecture/scripts/sitemap_analyzer.py site/sitemap.xml ``` Verify: @@ -319,22 +320,22 @@ These pages rank well for their target keywords. Only fix critical issues (broke | Tool | Path | Use | |------|------|-----| -| SEO Checker | `marketing-skill/seo-audit/scripts/seo_checker.py` | Score HTML pages 0-100 | -| Content Scorer | `marketing-skill/content-production/scripts/content_scorer.py` | Score content readability/structure/engagement | -| Humanizer Scorer | `marketing-skill/content-humanizer/scripts/humanizer_scorer.py` | Detect AI-sounding content | -| Headline Scorer | `marketing-skill/copywriting/scripts/headline_scorer.py` | Score title quality | -| SEO Optimizer | `marketing-skill/content-production/scripts/seo_optimizer.py` | Optimize content for target keyword | -| Sitemap Analyzer | `marketing-skill/site-architecture/scripts/sitemap_analyzer.py` | Analyze sitemap structure | -| Schema Validator | `marketing-skill/schema-markup/scripts/schema_validator.py` | Validate structured data | -| Topic Cluster Mapper | `marketing-skill/content-strategy/scripts/topic_cluster_mapper.py` | Group pages into content clusters | +| SEO Checker | `marketing-skill/skills/seo-audit/scripts/seo_checker.py` | Score HTML pages 0-100 | +| Content Scorer | `marketing-skill/skills/content-production/scripts/content_scorer.py` | Score content readability/structure/engagement | +| Humanizer Scorer | `marketing-skill/skills/content-humanizer/scripts/humanizer_scorer.py` | Detect AI-sounding content | +| Headline Scorer | `marketing-skill/skills/copywriting/scripts/headline_scorer.py` | Score title quality | +| SEO Optimizer | `marketing-skill/skills/content-production/scripts/seo_optimizer.py` | Optimize content for target keyword | +| Sitemap Analyzer | `marketing-skill/skills/site-architecture/scripts/sitemap_analyzer.py` | Analyze sitemap structure | +| Schema Validator | `marketing-skill/skills/schema-markup/scripts/schema_validator.py` | Validate structured data | +| Topic Cluster Mapper | `marketing-skill/skills/content-strategy/scripts/topic_cluster_mapper.py` | Group pages into content clusters | ### Reference Docs | Reference | Path | Use | |-----------|------|-----| -| SEO Audit Framework | `marketing-skill/seo-audit/references/seo-audit-reference.md` | Priority order for SEO fixes | -| AI Search Optimization | `marketing-skill/ai-seo/references/content-patterns.md` | Make content citable by AI | -| Content Optimization | `marketing-skill/content-production/references/optimization-checklist.md` | Pre-publish checklist | -| URL Design Guide | `marketing-skill/site-architecture/references/url-design-guide.md` | URL structure best practices | -| Internal Linking | `marketing-skill/site-architecture/references/internal-linking-playbook.md` | Internal linking strategy | -| AI Writing Detection | `marketing-skill/content-humanizer/references/ai-tells-checklist.md` | AI cliché removal | +| SEO Audit Framework | `marketing-skill/skills/seo-audit/references/seo-audit-reference.md` | Priority order for SEO fixes | +| 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 | +| AI Writing Detection | `marketing-skill/skills/content-humanizer/references/ai-tells-checklist.md` | AI cliché removal | diff --git a/commands/sprint-health.md b/commands/sprint-health.md index 76708e75..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 @@ -36,8 +37,8 @@ Score sprint health across delivery, quality, and team metrics with velocity tre ``` ## Scripts -- `project-management/scrum-master/scripts/sprint_health_scorer.py` — Sprint health scorer (` [--format text|json]`) -- `project-management/scrum-master/scripts/velocity_analyzer.py` — Velocity analyzer (` [--format text|json]`) +- `project-management/skills/scrum-master/scripts/sprint_health_scorer.py` — Sprint health scorer (` [--format text|json]`) +- `project-management/skills/scrum-master/scripts/velocity_analyzer.py` — Velocity analyzer (` [--format text|json]`) ## Skill Reference -> `project-management/scrum-master/SKILL.md` +> `project-management/skills/scrum-master/SKILL.md` diff --git a/commands/sprint-plan.md b/commands/sprint-plan.md index a504d239..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/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 e5c0cbc6..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 @@ -28,7 +28,7 @@ Otherwise, parse `$ARGUMENTS` as ` ` and dispatch to the match 1. Run: ```bash - python3 engineering/tc-tracker/scripts/tc_init.py --root . --json + python3 engineering/skills/tc-tracker/scripts/tc_init.py --root . --json ``` 2. If status is `already_initialized`, report current statistics and stop. 3. Otherwise report what was created and suggest `/tc create ` as the next step. @@ -44,7 +44,7 @@ Otherwise, parse `$ARGUMENTS` as ` ` and dispatch to the match - Motivation 3. Run: ```bash - python3 engineering/tc-tracker/scripts/tc_create.py --root . \ + python3 engineering/skills/tc-tracker/scripts/tc_create.py --root . \ --name "" --title "" --scope <scope> --priority <priority> \ --summary "<summary>" --motivation "<motivation>" --json ``` @@ -62,7 +62,7 @@ Otherwise, parse `$ARGUMENTS` as `<subcommand> <rest>` and dispatch to the match - **Add a tag** → `--tag <tag>` 3. Run: ```bash - python3 engineering/tc-tracker/scripts/tc_update.py --root . --tc-id <tc-id> [flags] --json + python3 engineering/skills/tc-tracker/scripts/tc_update.py --root . --tc-id <tc-id> [flags] --json ``` 4. If exit code is non-zero, surface the error verbatim. The state machine and validator will reject invalid moves — do not retry blindly. @@ -70,24 +70,24 @@ Otherwise, parse `$ARGUMENTS` as `<subcommand> <rest>` and dispatch to the match - If `<tc-id>` is provided: ```bash - python3 engineering/tc-tracker/scripts/tc_status.py --root . --tc-id <tc-id> + python3 engineering/skills/tc-tracker/scripts/tc_status.py --root . --tc-id <tc-id> ``` - Otherwise: ```bash - python3 engineering/tc-tracker/scripts/tc_status.py --root . --all + python3 engineering/skills/tc-tracker/scripts/tc_status.py --root . --all ``` ### `resume <tc-id>` 1. Run: ```bash - python3 engineering/tc-tracker/scripts/tc_status.py --root . --tc-id <tc-id> --json + python3 engineering/skills/tc-tracker/scripts/tc_status.py --root . --tc-id <tc-id> --json ``` 2. Display the handoff block prominently: `progress_summary`, `next_steps` (numbered), `blockers`, `key_context`. 3. Ask: "Resume <tc-id> and pick up at next step 1? (y/n)" 4. If yes, run an update to record the resumption: ```bash - python3 engineering/tc-tracker/scripts/tc_update.py --root . --tc-id <tc-id> \ + python3 engineering/skills/tc-tracker/scripts/tc_update.py --root . --tc-id <tc-id> \ --note "Session resumed" --reason "session handoff" ``` 5. Begin executing the first item in `next_steps`. Do NOT re-derive context — trust the handoff. @@ -103,7 +103,7 @@ Otherwise, parse `$ARGUMENTS` as `<subcommand> <rest>` and dispatch to the match - "Test coverage status: none / partial / full" 5. Run: ```bash - python3 engineering/tc-tracker/scripts/tc_update.py --root . --tc-id <tc-id> \ + python3 engineering/skills/tc-tracker/scripts/tc_update.py --root . --tc-id <tc-id> \ --set-status deployed --reason "Approved by <approver>" --note "Approval: <approver> — <notes>" ``` Then directly edit the `approval` block via a follow-up update if your script version supports it; otherwise instruct the user to record approval in `notes`. @@ -116,11 +116,11 @@ There is no automatic HTML export in this skill. Re-validate everything instead: 1. Read the registry. 2. For each record, run: ```bash - python3 engineering/tc-tracker/scripts/tc_validator.py --record <path> --json + python3 engineering/skills/tc-tracker/scripts/tc_validator.py --record <path> --json ``` 3. Run: ```bash - python3 engineering/tc-tracker/scripts/tc_validator.py --registry docs/TC/tc_registry.json --json + python3 engineering/skills/tc-tracker/scripts/tc_validator.py --registry docs/TC/tc_registry.json --json ``` 4. Report: total records validated, any errors, paths to anything invalid. @@ -128,7 +128,7 @@ There is no automatic HTML export in this skill. Re-validate everything instead: Run the all-records summary: ```bash -python3 engineering/tc-tracker/scripts/tc_status.py --root . --all +python3 engineering/skills/tc-tracker/scripts/tc_status.py --root . --all ``` ## Iron Rules diff --git a/commands/tdd.md b/commands/tdd.md index 9eb41c62..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 <generate|coverage|validate> [options] +description: "Run a red-green-refactor TDD workflow — generate failing tests first, implement to green, then check coverage gaps. Usage: /tdd <generate|coverage|validate> [target]" +argument-hint: <generate|coverage|validate> [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 <file-or-dir> Generate tests for source files -/tdd coverage <test-dir> Analyze test coverage and gaps -/tdd validate <test-file> Validate test quality (assertions, edge cases) +## Modes + +### `/tdd generate <file-or-dir>` — 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 <coverage-report>` — 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('<path-to-lcov-or-json>').read(), 'lcov') # or 'json' / 'xml' +print(a.calculate_summary()) +for gap in a.identify_gaps(threshold=80.0): print(gap) +" ``` -## Scripts -- `engineering-team/tdd-guide/scripts/test_generator.py` — Test case generation (library module) -- `engineering-team/tdd-guide/scripts/coverage_analyzer.py` — Coverage analysis (library module) -- `engineering-team/tdd-guide/scripts/tdd_workflow.py` — TDD workflow orchestration (library module) -- `engineering-team/tdd-guide/scripts/fixture_generator.py` — Test fixture generation (library module) -- `engineering-team/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/tdd-guide/SKILL.md` +### `/tdd validate <test-file>` — 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 042300aa..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 <scan|prioritize|report> [options] +description: "Scan, prioritize, and report technical debt. Usage: /tech-debt <scan|prioritize|report> [options]" +argument-hint: "<scan|prioritize|report> [options]" --- # /tech-debt @@ -24,9 +25,9 @@ Scan codebases for technical debt, score severity, and generate prioritized reme ``` ## Scripts -- `engineering/tech-debt-tracker/scripts/debt_scanner.py` — Scan for debt patterns (`debt_scanner.py <directory> [--format json] [--output file]`) -- `engineering/tech-debt-tracker/scripts/debt_prioritizer.py` — Prioritize debt backlog (`debt_prioritizer.py <inventory.json> [--framework cost_of_delay|wsjf|rice] [--format json]`) -- `engineering/tech-debt-tracker/scripts/debt_dashboard.py` — Generate debt dashboard (`debt_dashboard.py [files...] [--input-dir dir] [--period weekly|monthly|quarterly] [--format json]`) +- `engineering/skills/tech-debt-tracker/scripts/debt_scanner.py` — Scan for debt patterns (`debt_scanner.py <directory> [--format json] [--output file]`) +- `engineering/skills/tech-debt-tracker/scripts/debt_prioritizer.py` — Prioritize debt backlog (`debt_prioritizer.py <inventory.json> [--framework cost_of_delay|wsjf|rice] [--format json]`) +- `engineering/skills/tech-debt-tracker/scripts/debt_dashboard.py` — Generate debt dashboard (`debt_dashboard.py [files...] [--input-dir dir] [--period weekly|monthly|quarterly] [--format json]`) ## Skill Reference -→ `engineering/tech-debt-tracker/SKILL.md` +→ `engineering/skills/tech-debt-tracker/SKILL.md` diff --git a/commands/user-story.md b/commands/user-story.md index 4a4d97e8..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 <generate|sprint> [options] +description: "Generate user stories with acceptance criteria and sprint planning. Usage: /user-story <generate|sprint> [options]" +argument-hint: "<generate|sprint> [options]" --- # /user-story @@ -37,7 +38,7 @@ Interactive mode prompts for feature context. For sprint planning, provide capac ``` ## Scripts -- `product-team/agile-product-owner/scripts/user_story_generator.py` — User story generator (positional args: `sprint <capacity>`) +- `product-team/agile-product-owner/skills/agile-product-owner/scripts/user_story_generator.py` — User story generator (positional args: `sprint <capacity>`) ## Skill Reference -> `product-team/agile-product-owner/SKILL.md` +> `product-team/agile-product-owner/skills/agile-product-owner/SKILL.md` diff --git a/commands/wiki-ingest.md b/commands/wiki-ingest.md index e640ca2f..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 <path-to-source> --- +<!-- canonical copy: engineering/llm-wiki/commands/wiki-ingest.md — keep in sync (root copy uses repo-root-relative script paths) --> # /wiki-ingest @@ -21,13 +22,13 @@ A typical ingest touches **5-15 wiki pages**. You (the user) are in the loop: th ## What happens -1. **Prep** — runs `scripts/ingest_source.py` to get title, preview, and suggested summary path +1. **Prep** — runs `engineering/llm-wiki/skills/llm-wiki/scripts/ingest_source.py` to get title, preview, and suggested summary path 2. **Read** — reads the source directly 3. **Discuss** — reports TL;DR, key claims, which pages will be touched, any contradictions 4. **Confirm** — waits for your go-ahead (or redirects) 5. **Write** — creates the source summary, updates 5-15 pages, flags contradictions -6. **Index** — runs `scripts/update_index.py` or edits `wiki/index.md` inline -7. **Log** — runs `scripts/append_log.py --op ingest --title "<title>"` +6. **Index** — runs `engineering/llm-wiki/skills/llm-wiki/scripts/update_index.py` or edits `wiki/index.md` inline +7. **Log** — runs `engineering/llm-wiki/skills/llm-wiki/scripts/append_log.py --op ingest --title "<title>"` 8. **Report** — bulleted wikilinks to every touched page ## Sub-agent @@ -36,9 +37,9 @@ This command dispatches the `wiki-ingestor` sub-agent for the heavy lifting. See ## Scripts -- `engineering/llm-wiki/scripts/ingest_source.py` — source prep (metadata + preview) -- `engineering/llm-wiki/scripts/update_index.py` — regenerate index -- `engineering/llm-wiki/scripts/append_log.py` — log the ingest +- `engineering/llm-wiki/skills/llm-wiki/scripts/ingest_source.py` — source prep (metadata + preview) +- `engineering/llm-wiki/skills/llm-wiki/scripts/update_index.py` — regenerate index +- `engineering/llm-wiki/skills/llm-wiki/scripts/append_log.py` — log the ingest ## Rules @@ -48,5 +49,5 @@ This command dispatches the `wiki-ingestor` sub-agent for the heavy lifting. See ## Skill Reference -→ `engineering/llm-wiki/SKILL.md` -→ `engineering/llm-wiki/references/ingest-workflow.md` +→ `engineering/llm-wiki/skills/llm-wiki/SKILL.md` +→ `engineering/llm-wiki/skills/llm-wiki/references/ingest-workflow.md` diff --git a/commands/wiki-init.md b/commands/wiki-init.md index e62f9575..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 <path> --topic "<topic>" [--tool all|claude-code|codex|cursor|antigravity] --- +<!-- canonical copy: engineering/llm-wiki/commands/wiki-init.md — keep in sync --> # /wiki-init @@ -53,8 +54,8 @@ After init: ## Script -- `engineering/llm-wiki/scripts/init_vault.py` +- `engineering/llm-wiki/skills/llm-wiki/scripts/init_vault.py` ## Skill Reference -→ `engineering/llm-wiki/SKILL.md` +→ `engineering/llm-wiki/skills/llm-wiki/SKILL.md` diff --git a/commands/wiki-lint.md b/commands/wiki-lint.md index 1822a2f8..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] --- +<!-- canonical copy: engineering/llm-wiki/commands/wiki-lint.md — keep in sync (root copy uses repo-root-relative script paths) --> # /wiki-lint @@ -21,8 +22,8 @@ Run this weekly, after batch ingests, and always before sharing the wiki. ### Pass 1 — Mechanical (scripts) -- `scripts/lint_wiki.py` — orphans, broken links, stale pages, missing frontmatter, duplicate titles, log gap -- `scripts/graph_analyzer.py` — hubs, sinks, connected components, graph stats +- `engineering/llm-wiki/skills/llm-wiki/scripts/lint_wiki.py` — orphans, broken links, stale pages, missing frontmatter, duplicate titles, log gap +- `engineering/llm-wiki/skills/llm-wiki/scripts/graph_analyzer.py` — hubs, sinks, connected components, graph stats ### Pass 2 — Semantic (LLM reads and thinks) @@ -64,9 +65,9 @@ Dispatches the `wiki-linter` sub-agent. See `agents/wiki-linter.md`. ## Scripts -- `engineering/llm-wiki/scripts/lint_wiki.py` -- `engineering/llm-wiki/scripts/graph_analyzer.py` -- `engineering/llm-wiki/scripts/append_log.py` +- `engineering/llm-wiki/skills/llm-wiki/scripts/lint_wiki.py` +- `engineering/llm-wiki/skills/llm-wiki/scripts/graph_analyzer.py` +- `engineering/llm-wiki/skills/llm-wiki/scripts/append_log.py` ## Frequency @@ -79,5 +80,5 @@ Dispatches the `wiki-linter` sub-agent. See `agents/wiki-linter.md`. ## Skill Reference -→ `engineering/llm-wiki/SKILL.md` -→ `engineering/llm-wiki/references/lint-workflow.md` +→ `engineering/llm-wiki/skills/llm-wiki/SKILL.md` +→ `engineering/llm-wiki/skills/llm-wiki/references/lint-workflow.md` diff --git a/commands/wiki-log.md b/commands/wiki-log.md index 404c38c4..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|...] --- +<!-- canonical copy: engineering/llm-wiki/commands/wiki-log.md — keep in sync --> # /wiki-log @@ -61,4 +62,4 @@ Filed back to comparisons/sae-vs-probing.md. ## Skill Reference -→ `engineering/llm-wiki/SKILL.md` +→ `engineering/llm-wiki/skills/llm-wiki/SKILL.md` diff --git a/commands/wiki-query.md b/commands/wiki-query.md index d209dc52..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 "<question>" --- +<!-- canonical copy: engineering/llm-wiki/commands/wiki-query.md — keep in sync (root copy uses repo-root-relative script paths) --> # /wiki-query @@ -22,7 +23,7 @@ Ask the wiki a question. The librarian reads `index.md` first, picks relevant pa 1. **Index-first read** — reads `wiki/index.md` to find relevant pages 2. **Drill-in** — reads 3-10 pages in full (synthesis + concepts + sources + entities) 3. **Follow links** — opportunistically follows wikilinks between pages -4. **Fallback search** — if the index isn't enough, runs `scripts/wiki_search.py` (BM25) +4. **Fallback search** — if the index isn't enough, runs `engineering/llm-wiki/skills/llm-wiki/scripts/wiki_search.py` (BM25) 5. **Synthesize** — composes a direct answer + supporting detail + inline `[[sources/xxx]]` citations + "Related pages" section 6. **Offer to file back** — asks whether to save this as a new wiki page (usually in `comparisons/` or `synthesis/`) @@ -43,8 +44,8 @@ This command dispatches the `wiki-librarian` sub-agent. See `agents/wiki-librari ## Scripts -- `engineering/llm-wiki/scripts/wiki_search.py` — BM25 fallback search -- `engineering/llm-wiki/scripts/append_log.py` — log filed answers +- `engineering/llm-wiki/skills/llm-wiki/scripts/wiki_search.py` — BM25 fallback search +- `engineering/llm-wiki/skills/llm-wiki/scripts/append_log.py` — log filed answers ## Rules @@ -54,5 +55,5 @@ This command dispatches the `wiki-librarian` sub-agent. See `agents/wiki-librari ## Skill Reference -→ `engineering/llm-wiki/SKILL.md` -→ `engineering/llm-wiki/references/query-workflow.md` +→ `engineering/llm-wiki/skills/llm-wiki/SKILL.md` +→ `engineering/llm-wiki/skills/llm-wiki/references/query-workflow.md` diff --git a/commercial/skills/channel-economics/SKILL.md b/commercial/skills/channel-economics/SKILL.md index cf4c6f2c..9a7cbe73 100644 --- a/commercial/skills/channel-economics/SKILL.md +++ b/commercial/skills/channel-economics/SKILL.md @@ -1,6 +1,6 @@ --- name: channel-economics -description: "Use when reviewing or rebalancing direct vs. partner-led channel economics — 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-DOWN / MAINTAIN / DEFUND / EXIT), a sensitivity-tested channel-mix recommendation, and the diminishing-returns inflection. Not channel structure (that's partnerships-architect — tiers, joint GTM, revshare). Not RevOps process (that's business-growth/revenue-operations — lead routing, SDR motion). Not strategic CRO judgment (that's c-level-advisor/cro-advisor — comp plans, when-to-hire-a-VP-Sales). Not historical close-and-report (that's finance/financial-analysis). This skill answers: direct vs partner profitability, channel profitability, channel mix, channel economics." +description: "Use when reviewing or rebalancing direct vs. partner-led channel economics — 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-DOWN / MAINTAIN / DEFUND / EXIT), a sensitivity-tested channel-mix recommendation, and the diminishing-returns inflection (e.g., 'which channel actually makes money — direct or partner?')." version: 2.8.0 author: claude-code-skills license: MIT @@ -79,6 +79,13 @@ Take the three reports into the quarterly channel review. The skill recommends; All scripts: stdlib only. `--help`, `--sample`, `--input`, `--output` work on all three. Industry tuning via `--profile {saas,api,enterprise-software,marketplace,hardware}` on the two analyzers. +## Quick example + +```bash +# Emits fully-loaded cost-to-serve per channel (direct vs partner-led) for the built-in sample channel data +cd commercial/skills/channel-economics && python3 scripts/cost_to_serve_calculator.py --sample +``` + ## References - `references/channel_economics_canon.md` — Skok, Bessemer State of the Cloud, Tunguz, Pacific Crest / KeyBanc SaaS Survey, Ramanujam, Jay McBain (Canalys) diff --git a/commercial/skills/deal-desk/SKILL.md b/commercial/skills/deal-desk/SKILL.md index 5e76dc4b..c4d4bcb5 100644 --- a/commercial/skills/deal-desk/SKILL.md +++ b/commercial/skills/deal-desk/SKILL.md @@ -101,7 +101,7 @@ python3 scripts/terms_redliner.py --sample python3 scripts/terms_redliner.py --input my_deal_terms.json --output json ``` -The sample (a 28%-discount enterprise SaaS deal with uncapped indemnity + MFN) correctly DECLINEs at 55.4 / 100 composite and routes to AE → Deal Desk → VP Sales → CFO → CRO → General Counsel. +The sample (a 28%-discount enterprise SaaS deal with uncapped indemnity + MFN) correctly DECLINEs at 52.7 / 100 composite — the 28% discount destroys 35.9% of the deal's margin dollars under fixed COGS — and routes to AE → Deal Desk → VP Sales → CFO → CRO → General Counsel. ## Forcing-question library (Matt Pocock grill discipline) diff --git a/commercial/skills/deal-desk/references/deal_desk_canon.md b/commercial/skills/deal-desk/references/deal_desk_canon.md index d924d12a..cd62c09c 100644 --- a/commercial/skills/deal-desk/references/deal_desk_canon.md +++ b/commercial/skills/deal-desk/references/deal_desk_canon.md @@ -18,7 +18,7 @@ Without a deal desk, every above-band deal becomes a 1:1 negotiation between an These are the non-negotiables — adopted across every reference cited below. 1. **Never auto-approve.** Even green deals get a named approver. The skill outputs *who must sign*, not *the deal is fine*. -2. **Margin, not discount.** A 30% discount on an 80%-gross-margin product reduces *margin* by 24 points (to 56%) — not 30%. See `discount_economics.md` for the math. +2. **Margin, not discount.** A 30% discount on an 80%-gross-margin product destroys *37.5% of the margin dollars* (COGS is fixed, so every discounted dollar comes straight out of margin) — not 30%. See `discount_economics.md` for the math. 3. **The chain stops at the lowest hop that has authority.** Over-routing trains reps to over-discount because they expect VP attention anyway. 4. **Critical signals override composite.** A high-composite deal with uncapped indemnity is still a DECLINE. 5. **Modifiers must be explicit.** Enterprise floor (large ARR forces VP review) and SMB fast-lane (small deals can skip a hop) are surfaced; hidden adjustments destroy audit trails. diff --git a/commercial/skills/deal-desk/references/discount_economics.md b/commercial/skills/deal-desk/references/discount_economics.md index ef28bdd7..9efab026 100644 --- a/commercial/skills/deal-desk/references/discount_economics.md +++ b/commercial/skills/deal-desk/references/discount_economics.md @@ -4,39 +4,42 @@ The math of what a discount actually costs. Most sales discounts are described a ## The fundamental formula -A discount of D% on a product with gross margin G% reduces net margin by: +The model is **fixed COGS**: discounting the price does not shrink the cost of delivering the product. At list price P with gross margin G%, COGS = (1 − G/100) × P and stays fixed when the price drops to (1 − D/100) × P. Two numbers follow: - margin_loss_points = D * (G / 100) - net_margin = G - margin_loss_points + net_margin_pct = (G - D) / (100 - D) * 100 # post-discount margin % + margin_dollars_destroyed_pct = D / G * 100 # share of margin $ given up + +Every discounted dollar comes straight out of margin dollars — the discount amount IS the margin loss in dollars. ### Worked examples -| List discount | Gross margin | Margin loss | Net margin | +| List discount | Gross margin | Margin $ destroyed | Net margin % | |---|---|---|---| -| 10% | 80% | 8 pts | 72% | -| 20% | 80% | 16 pts | 64% | -| **30%** | **80%** | **24 pts** | **56%** | -| 30% | 60% | 18 pts | 42% | -| 40% | 80% | 32 pts | 48% | -| 50% | 80% | 40 pts | 40% | +| 10% | 80% | 12.5% | 77.8% | +| 20% | 80% | 25.0% | 75.0% | +| **30%** | **80%** | **37.5%** | **71.4%** | +| 30% | 60% | 50.0% | 42.9% | +| 40% | 80% | 50.0% | 66.7% | +| 50% | 80% | 62.5% | 60.0% | -**A 30% discount on an 80%-gross-margin product wipes 24 points of margin** — that's a 30% margin loss in *relative* terms (24/80 = 30%), but the conventional shorthand "30% discount = 30% margin hit" understates the absolute hit on a low-margin product. +**A 30% discount on an 80%-gross-margin product destroys 37.5% of the margin dollars** (30/80), even though the margin *percentage* only slips from 80% to 71.4%. The percentage is cosmetic; the dollars fund the P&L. ### Why the conventional shorthand is wrong -People often say "a 30% discount loses 30% of margin." That's only true for a 100%-margin product. For an 80%-margin SaaS, the discount cuts the **revenue** by 30% but the **margin** by 30% × (80/100) = 24 points, or 30% in relative terms. The dollar impact compounds across the contract term. +People often say "a 30% discount loses 30% of margin." Under fixed COGS that *understates* the damage: the discount cuts revenue by 30% but COGS doesn't move, so the entire discount comes out of margin dollars — 30/80 = **37.5%** of the margin is gone. The lower the starting margin, the worse it gets: the same 30% discount on a 60%-margin business destroys half its margin. This is why the deal scorer's margin dimension penalizes margin-dollar destruction directly, not just the post-discount margin percentage. ## LTV impact -Discount also compounds across multi-year contracts. A 24-month deal at 30% discount loses: +Discount also compounds across multi-year contracts. Because COGS is fixed, every discounted dollar is a lost margin dollar — the gross margin % determines what *fraction* of margin that represents (D/G), not the dollar amount: - lifetime_margin_loss = (D / 100) * G/100 * list_price * (term_months / 12) + lifetime_margin_loss = (D / 100) * list_arr * (term_months / 12) -For a $200K-ARR deal at 30% discount, 80% gross margin, 24-month term: +For a $200K-list-ARR deal at 30% discount, 24-month term: - = 0.30 * 0.80 * 200,000 * 2 = $96,000 of gross margin given up + = 0.30 * 200,000 * 2 = $120,000 of gross margin given up + (= 37.5% of the $320K margin the deal would have carried at 80% GM) -That's $96K of fully-loaded P&L impact for one deal. Across 50 deals/quarter at the same discount, the company is giving up $19.2M/year in gross margin. +That's $120K of fully-loaded P&L impact for one deal. Across 50 deals/quarter at the same discount and terms, the company signs away $24M/year of contracted gross margin. ## Discount creep diff --git a/commercial/skills/deal-desk/scripts/deal_scorer.py b/commercial/skills/deal-desk/scripts/deal_scorer.py index 0c1c5a38..d4e00e8a 100644 --- a/commercial/skills/deal-desk/scripts/deal_scorer.py +++ b/commercial/skills/deal-desk/scripts/deal_scorer.py @@ -5,7 +5,7 @@ Stdlib-only. NEVER auto-approves. Output is always a numeric breakdown plus a ve (APPROVE / REVIEW / ESCALATE / DECLINE) and a NAMED HUMAN APPROVER chain. The 5 dimensions (each 0-100, weighted into a composite): - 1. margin - post-discount gross margin vs profile target + 1. margin - post-discount margin (fixed-COGS) vs target + margin-$ destroyed 2. risk - payment terms + redline count + customer tier 3. strategic - logo / reference / expansion / renewal value 4. commercial - is the discount within the profile policy band @@ -122,24 +122,47 @@ def _clamp(x: float, lo: float = 0.0, hi: float = 100.0) -> float: def score_margin(deal: dict, profile: dict) -> DimensionScore: """Effective margin after discount, compared to profile target. - Math: a D% discount on a product with gross_margin_pct G% drops margin to - new_margin = (G - D) / (1 - D/100) approximately, but the canonical - formulation we use is: net_margin = G - (D * (1 - cost_ratio)) which - resolves to: - net_margin = G - D * (G / 100) - i.e. a 30% discount on an 80% margin product wipes 24 points of margin, - leaving 56% — well below an 75% SaaS target. + Math (fixed-COGS model — COGS does not shrink when you discount the price): + Price P, gross margin G% -> COGS = (1 - G/100) * P, fixed. + Discounted price = (1 - D/100) * P. + Post-discount margin %: + net_margin_pct = (G - D) / (100 - D) * 100 + Share of margin DOLLARS destroyed by the discount: + margin_dollars_destroyed_pct = D / G * 100 + i.e. a 30% discount on an 80%-margin product leaves a 71.4% margin + percentage but destroys 37.5% of the margin dollars — every discounted + dollar comes straight out of margin, because the cost side is fixed. + + Score = min(position score, destruction score): + - position: 100 if net_margin_pct >= target, sliding to 0 at + (target - 30 pts) + - destruction: 100 at 0% of margin dollars destroyed, sliding to 0 at + 50% destroyed (2 pts of score per 1% of margin dollars given up) + The min() means a high starting margin cannot hide discount damage. """ g = float(deal.get("gross_margin_pct", 0.0)) d = float(deal.get("discount_pct", 0.0)) - net_margin = g - (d * (g / 100.0)) target = profile["target_gross_margin"] - # Score: 100 if net_margin >= target, sliding to 0 at (target - 30 pts) + + if g <= 0.0 or d >= 100.0: + rationale = ( + f"Gross margin {g:.1f}% with {d:.1f}% discount -> no margin left " + f"(vs profile target {target:.1f}%)" + ) + return DimensionScore("margin", 0.0, 0.30, rationale) + + net_margin = (g - d) / (100.0 - d) * 100.0 + margin_dollars_destroyed = (d / g) * 100.0 + delta = net_margin - target - score = _clamp(100.0 + (delta / 30.0) * 100.0) + position_score = _clamp(100.0 + (delta / 30.0) * 100.0) + destruction_score = _clamp(100.0 - 2.0 * margin_dollars_destroyed) + score = min(position_score, destruction_score) + rationale = ( f"Gross margin {g:.1f}% with {d:.1f}% discount -> net margin {net_margin:.1f}% " - f"vs profile target {target:.1f}% (delta {delta:+.1f} pts)" + f"vs profile target {target:.1f}% (delta {delta:+.1f} pts); " + f"{margin_dollars_destroyed:.1f}% of margin dollars destroyed (fixed-COGS)" ) return DimensionScore("margin", round(score, 1), 0.30, rationale) @@ -244,10 +267,14 @@ def _detect_critical_signals(deal: dict, dims: list[DimensionScore]) -> list[str for r in redlines: if any(ct in r for ct in critical_terms): sigs.append(f"critical redline: {r}") - # margin below 35% is a critical economic signal on any profile + # margin dimension below 30 is a critical economic signal on any profile + # (net margin deep below target, or >35% of margin dollars destroyed) for d in dims: if d.name == "margin" and d.score < 30.0: - sigs.append("margin below target by >30 pts") + sigs.append( + "margin critically impaired (deep below target or >35% of " + "margin dollars destroyed)" + ) if d.name == "commercial" and d.score < 30.0: sigs.append("discount far outside policy band") return sigs diff --git a/commercial/skills/partnerships-architect/SKILL.md b/commercial/skills/partnerships-architect/SKILL.md index 96fac356..a83b53ab 100644 --- a/commercial/skills/partnerships-architect/SKILL.md +++ b/commercial/skills/partnerships-architect/SKILL.md @@ -89,6 +89,13 @@ when triggered. All scripts: stdlib only. `--help` and `--sample` work on all three. +## Quick example + +```bash +# Emits a 5-tier partner classification with deterministic floors per tier for the built-in sample partner +cd commercial/skills/partnerships-architect && python3 scripts/partner_tier_classifier.py --sample +``` + ## References - `references/channel_partner_canon.md` — Caro on HP indirect channels, Chintagunta on channel economics, Hessling on partner programs, Forrester channel software stack, IDC channel research, Tien Tzuo subscription-channel models, Geoffrey Moore whole-product partnerships diff --git a/commercial/skills/pricing-strategist/SKILL.md b/commercial/skills/pricing-strategist/SKILL.md index 361ae722..6e02242e 100644 --- a/commercial/skills/pricing-strategist/SKILL.md +++ b/commercial/skills/pricing-strategist/SKILL.md @@ -67,6 +67,13 @@ Take model + range + packaging into the pricing committee. Skill does not commit All scripts: stdlib only. `--help` and `--sample` work on all three. +## Quick example + +```bash +# Emits a scored 5-model pricing-fit recommendation (subscription / usage / value / freemium / hybrid) for the built-in example +cd commercial/skills/pricing-strategist && python3 scripts/pricing_model_picker.py --sample +``` + ## References - `references/saas_pricing_canon.md` — Skok, Tunguz, Campbell, Ramanujam, BVP, Shevlin, Stanford GSB diff --git a/compliance-os/skills/ai-act-readiness/SKILL.md b/compliance-os/skills/ai-act-readiness/SKILL.md index 423ac418..18e8c4cf 100644 --- a/compliance-os/skills/ai-act-readiness/SKILL.md +++ b/compliance-os/skills/ai-act-readiness/SKILL.md @@ -68,13 +68,13 @@ The EU AI Act compliance operator pressure-tests any AI system before EU deploym ```bash # 1. Risk classification -python ../../ra-qm-team/skills/eu-ai-act-specialist/scripts/ai_system_risk_classifier.py systems.json +python ra-qm-team/skills/eu-ai-act-specialist/scripts/ai_system_risk_classifier.py systems.json # 2. If high-risk: conformity assessment -python ../../ra-qm-team/skills/eu-ai-act-specialist/scripts/conformity_assessment_planner.py system.json +python ra-qm-team/skills/eu-ai-act-specialist/scripts/conformity_assessment_planner.py system.json # 3. Per-role obligation matrix -python ../../ra-qm-team/skills/eu-ai-act-specialist/scripts/ai_act_obligation_tracker.py roles.json +python ra-qm-team/skills/eu-ai-act-specialist/scripts/ai_act_obligation_tracker.py roles.json # 4. Cross-framework reuse (ISO 42001 etc.) python ../../skills/compliance-os/scripts/cross_framework_mapper.py program.json diff --git a/compliance-os/skills/aims-audit/SKILL.md b/compliance-os/skills/aims-audit/SKILL.md index e8ea82ba..4b75644c 100644 --- a/compliance-os/skills/aims-audit/SKILL.md +++ b/compliance-os/skills/aims-audit/SKILL.md @@ -62,13 +62,13 @@ The ISO 42001 AIMS specialist pressure-tests any AI Management System work. Six ```bash # 1. AIMS gap analysis -python ../../ra-qm-team/skills/iso42001-specialist/scripts/aims_gap_analyzer.py evidence.json +python ra-qm-team/skills/iso42001-specialist/scripts/aims_gap_analyzer.py evidence.json # 2. AI risk register -python ../../ra-qm-team/skills/iso42001-specialist/scripts/ai_risk_register_builder.py risks.json +python ra-qm-team/skills/iso42001-specialist/scripts/ai_risk_register_builder.py risks.json # 3. Internal audit plan -python ../../ra-qm-team/skills/iso42001-specialist/scripts/aims_audit_scheduler.py audit_scope.json +python ra-qm-team/skills/iso42001-specialist/scripts/aims_audit_scheduler.py audit_scope.json # 4. Cross-framework reuse map (via compliance-os) python ../../skills/compliance-os/scripts/cross_framework_mapper.py program.json diff --git a/compliance-os/skills/compliance-os/SKILL.md b/compliance-os/skills/compliance-os/SKILL.md index a61fb6ca..1b510c5e 100644 --- a/compliance-os/skills/compliance-os/SKILL.md +++ b/compliance-os/skills/compliance-os/SKILL.md @@ -180,17 +180,17 @@ python scripts/evidence_pool_generator.py program.json ## Adjacent Skills -- `../../ra-qm-team/skills/iso42001-specialist/` — ISO 42001 deep-dive (paired with compliance-team-iso42001 plugin) -- `../../ra-qm-team/skills/eu-ai-act-specialist/` — EU AI Act deep-dive (paired with compliance-team-eu-ai-act plugin) -- `../../ra-qm-team/skills/information-security-manager-iso27001/` — ISO 27001 ISMS deep-dive -- `../../ra-qm-team/skills/quality-manager-qms-iso13485/` — ISO 13485 QMS deep-dive -- `../../ra-qm-team/skills/gdpr-dsgvo-expert/` — GDPR deep-dive -- `../../ra-qm-team/skills/soc2-compliance/` — SOC 2 deep-dive -- `../../ra-qm-team/skills/fda-consultant-specialist/` — FDA QSR deep-dive -- `../../ra-qm-team/skills/mdr-745-specialist/` — EU MDR 745 deep-dive -- `../../ra-qm-team/skills/risk-management-specialist/` — ISO 14971 deep-dive -- `../../c-level-advisor/chief-ai-officer-advisor/` — Executive AI risk decisions (build-vs-buy, model selection) -- `../../c-level-advisor/skills/general-counsel-advisor/` — Legal review for novel cases +- `ra-qm-team/skills/iso42001-specialist/` — ISO 42001 deep-dive (paired with compliance-team-iso42001 plugin) +- `ra-qm-team/skills/eu-ai-act-specialist/` — EU AI Act deep-dive (paired with compliance-team-eu-ai-act plugin) +- `ra-qm-team/skills/information-security-manager-iso27001/` — ISO 27001 ISMS deep-dive +- `ra-qm-team/skills/quality-manager-qms-iso13485/` — ISO 13485 QMS deep-dive +- `ra-qm-team/skills/gdpr-dsgvo-expert/` — GDPR deep-dive +- `ra-qm-team/skills/soc2-compliance/` — SOC 2 deep-dive +- `ra-qm-team/skills/fda-consultant-specialist/` — FDA QSR deep-dive +- `ra-qm-team/skills/mdr-745-specialist/` — EU MDR 745 deep-dive +- `ra-qm-team/skills/risk-management-specialist/` — ISO 14971 deep-dive +- `c-level-advisor/chief-ai-officer-advisor/` — Executive AI risk decisions (build-vs-buy, model selection) +- `c-level-advisor/skills/general-counsel-advisor/` — Legal review for novel cases ## References diff --git a/compliance-os/skills/compliance-readiness/SKILL.md b/compliance-os/skills/compliance-readiness/SKILL.md index f347c316..7675e7a8 100644 --- a/compliance-os/skills/compliance-readiness/SKILL.md +++ b/compliance-os/skills/compliance-readiness/SKILL.md @@ -129,7 +129,7 @@ python ../../skills/compliance-os/scripts/audit_simulator.py scope.json - Agent: [`cs-compliance-officer`](../../agents/cs-compliance-officer.md) - Skill: [`compliance-os`](../compliance-os/SKILL.md) -- Adjacent: `../../ra-qm-team/skills/iso42001-specialist/`, `../../ra-qm-team/skills/eu-ai-act-specialist/`, `../../ra-qm-team/skills/information-security-manager-iso27001/`, `../../ra-qm-team/skills/soc2-compliance/`, `../../ra-qm-team/skills/gdpr-dsgvo-expert/` +- Adjacent: `ra-qm-team/skills/iso42001-specialist/`, `ra-qm-team/skills/eu-ai-act-specialist/`, `ra-qm-team/skills/information-security-manager-iso27001/`, `ra-qm-team/skills/soc2-compliance/`, `ra-qm-team/skills/gdpr-dsgvo-expert/` --- diff --git a/compliance-os/skills/fda-qsr-audit-prep/SKILL.md b/compliance-os/skills/fda-qsr-audit-prep/SKILL.md index 2acd01be..6737d65c 100644 --- a/compliance-os/skills/fda-qsr-audit-prep/SKILL.md +++ b/compliance-os/skills/fda-qsr-audit-prep/SKILL.md @@ -69,13 +69,13 @@ The FDA QSR auditor pressure-tests any US medical-device QSR work. Six questions ```bash # 1. QSR compliance posture -python ../../ra-qm-team/skills/fda-consultant-specialist/scripts/qsr_compliance_checker.py compliance_state.json +python ra-qm-team/skills/fda-consultant-specialist/scripts/qsr_compliance_checker.py compliance_state.json # 2. FDA submission tracking (510(k) / PMA / IDE) -python ../../ra-qm-team/skills/fda-consultant-specialist/scripts/fda_submission_tracker.py submissions.json +python ra-qm-team/skills/fda-consultant-specialist/scripts/fda_submission_tracker.py submissions.json # 3. HIPAA overlap (if connected device handles PHI) -python ../../ra-qm-team/skills/fda-consultant-specialist/scripts/hipaa_risk_assessment.py phi_inventory.json +python ra-qm-team/skills/fda-consultant-specialist/scripts/hipaa_risk_assessment.py phi_inventory.json # 4. Mock FDA inspection python ../../skills/compliance-os/scripts/audit_simulator.py fda_qsr_scope.json diff --git a/compliance-os/skills/gdpr-audit-prep/SKILL.md b/compliance-os/skills/gdpr-audit-prep/SKILL.md index 525ad620..675fe8ad 100644 --- a/compliance-os/skills/gdpr-audit-prep/SKILL.md +++ b/compliance-os/skills/gdpr-audit-prep/SKILL.md @@ -72,13 +72,13 @@ The GDPR DPO auditor pressure-tests any privacy compliance work. Six Article-cit ```bash # 1. Compliance posture -python ../../ra-qm-team/skills/gdpr-dsgvo-expert/scripts/gdpr_compliance_checker.py compliance_state.json +python ra-qm-team/skills/gdpr-dsgvo-expert/scripts/gdpr_compliance_checker.py compliance_state.json # 2. DPIA for high-risk activities -python ../../ra-qm-team/skills/gdpr-dsgvo-expert/scripts/dpia_generator.py processing_activity.json +python ra-qm-team/skills/gdpr-dsgvo-expert/scripts/dpia_generator.py processing_activity.json # 3. DSAR workflow validation -python ../../ra-qm-team/skills/gdpr-dsgvo-expert/scripts/data_subject_rights_tracker.py dsar_log.json +python ra-qm-team/skills/gdpr-dsgvo-expert/scripts/data_subject_rights_tracker.py dsar_log.json # 4. Cross-framework reuse with ISO 27001 + SOC 2 + ISO 42001 python ../../skills/compliance-os/scripts/cross_framework_mapper.py program.json diff --git a/compliance-os/skills/iso13485-audit-prep/SKILL.md b/compliance-os/skills/iso13485-audit-prep/SKILL.md index 8008fe38..33da4a63 100644 --- a/compliance-os/skills/iso13485-audit-prep/SKILL.md +++ b/compliance-os/skills/iso13485-audit-prep/SKILL.md @@ -69,7 +69,7 @@ The ISO 13485 QMS auditor pressure-tests any medical-device QMS work. Six tracea ```bash # 1. Audit programme optimization -python ../../ra-qm-team/skills/qms-audit-expert/scripts/audit_schedule_optimizer.py audit_scope.json +python ra-qm-team/skills/qms-audit-expert/scripts/audit_schedule_optimizer.py audit_scope.json # 2. Mock audit for readiness check python ../../skills/compliance-os/scripts/audit_simulator.py iso13485_scope.json diff --git a/compliance-os/skills/iso27001-audit-prep/SKILL.md b/compliance-os/skills/iso27001-audit-prep/SKILL.md index 642a90df..35f3400b 100644 --- a/compliance-os/skills/iso27001-audit-prep/SKILL.md +++ b/compliance-os/skills/iso27001-audit-prep/SKILL.md @@ -65,7 +65,7 @@ The ISO 27001 ISMS auditor pressure-tests any ISMS work. Six sample-driven quest ```bash # 1. Audit programme planning -python ../../ra-qm-team/skills/isms-audit-expert/scripts/isms_audit_scheduler.py audit_scope.json +python ra-qm-team/skills/isms-audit-expert/scripts/isms_audit_scheduler.py audit_scope.json # 2. Mock audit for readiness check python ../../skills/compliance-os/scripts/audit_simulator.py iso27001_scope.json diff --git a/compliance-os/skills/soc2-audit-prep/SKILL.md b/compliance-os/skills/soc2-audit-prep/SKILL.md index 74c6b91a..a4080ac2 100644 --- a/compliance-os/skills/soc2-audit-prep/SKILL.md +++ b/compliance-os/skills/soc2-audit-prep/SKILL.md @@ -68,13 +68,13 @@ The SOC 2 Type II auditor pressure-tests any SOC 2 work. Six observation-period- ```bash # 1. Scoping + gap analysis (pre-observation) -python ../../ra-qm-team/skills/soc2-compliance/scripts/gap_analyzer.py current_state.json +python ra-qm-team/skills/soc2-compliance/scripts/gap_analyzer.py current_state.json # 2. Control matrix with ISO 27001 cross-walk -python ../../ra-qm-team/skills/soc2-compliance/scripts/control_matrix_builder.py program.json +python ra-qm-team/skills/soc2-compliance/scripts/control_matrix_builder.py program.json # 3. Continuous evidence tracking (during observation) -python ../../ra-qm-team/skills/soc2-compliance/scripts/evidence_tracker.py evidence_log.json +python ra-qm-team/skills/soc2-compliance/scripts/evidence_tracker.py evidence_log.json # 4. Mock audit (pre-field-test month 10) python ../../skills/compliance-os/scripts/audit_simulator.py soc2_scope.json diff --git a/docs/agents/cs-aeo.md b/docs/agents/cs-aeo.md index fbb25046..1bdc67f3 100644 --- a/docs/agents/cs-aeo.md +++ b/docs/agents/cs-aeo.md @@ -75,14 +75,14 @@ Differentiates from siblings: ### Reference docs (each cites 7+ sources) -- `references/aeo_eeat_canon.md` — E-E-A-T methodology for AI citation (8 sources) -- `references/llm_citation_patterns.md` — How each major LLM chooses sources (8 sources) -- `references/aeo_vs_seo.md` — The two disciplines, overlap, and strategic choice (8 sources) +- `marketing-skill/skills/aeo/references/aeo_eeat_canon.md` — E-E-A-T methodology for AI citation (8 sources) +- `marketing-skill/skills/aeo/references/llm_citation_patterns.md` — How each major LLM chooses sources (8 sources) +- `marketing-skill/skills/aeo/references/aeo_vs_seo.md` — The two disciplines, overlap, and strategic choice (8 sources) ## Related Agents - [cs-content-creator](cs-content-creator.md) — marketing-domain content writer -- [seo-audit](https://github.com/alirezarezvani/claude-skills/tree/main/marketing-skill/skills/seo-audit) — companion SEO audit skill (often run together) +- [seo-audit skill](https://github.com/alirezarezvani/claude-skills/tree/main/marketing-skill/skills/seo-audit/SKILL.md) — companion SEO audit (often run together) - DIFFERENT use case: `engineering/autoresearch-agent` (Karpathy's file-optimization loop — orthogonal) --- diff --git a/docs/agents/cs-agile-product-owner.md b/docs/agents/cs-agile-product-owner.md index 5e8bea97..176a3519 100644 --- a/docs/agents/cs-agile-product-owner.md +++ b/docs/agents/cs-agile-product-owner.md @@ -1,6 +1,6 @@ --- title: "Agile Product Owner Agent — AI Coding Agent & Codex Skill" -description: "Agile product owner agent for epic breakdown, sprint planning, backlog refinement, and INVEST-compliant user story generation. Agent-native orchestrator for Claude Code, Codex, Gemini CLI." +description: "Agile product owner agent for epic breakdown, sprint planning, backlog refinement, and INVEST-compliant user story generation. Use when preparing. Agent-native orchestrator for Claude Code, Codex, Gemini CLI." --- # Agile Product Owner Agent @@ -29,53 +29,53 @@ The cs-agile-product-owner agent bridges strategic product goals with sprint-lev | # | Skill | Location | Primary Tool | |---|-------|----------|-------------| | 1 | Agile Product Owner | [`product-team/agile-product-owner`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/agile-product-owner) | user_story_generator.py | -| 2 | Product Manager Toolkit | [`product-team/product-manager-toolkit`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/product-manager-toolkit) | rice_prioritizer.py | +| 2 | Product Manager Toolkit | [`skills/product-manager-toolkit`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/skills/product-manager-toolkit) | rice_prioritizer.py | ### Python Tools 1. **User Story Generator** - **Purpose:** Break epics into INVEST-compliant user stories with acceptance criteria in Given/When/Then format - - **Path:** [`scripts/user_story_generator.py`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/agile-product-owner/scripts/user_story_generator.py) - - **Usage:** `python ../../product-team/agile-product-owner/scripts/user_story_generator.py epic.yaml` + - **Path:** [`scripts/user_story_generator.py`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/agile-product-owner/skills/agile-product-owner/scripts/user_story_generator.py) + - **Usage:** `python ../../product-team/agile-product-owner/skills/agile-product-owner/scripts/user_story_generator.py epic.yaml` - **Features:** Epic decomposition, acceptance criteria generation, story point estimation, dependency mapping - **Use Cases:** Sprint planning, backlog refinement, story writing workshops 2. **RICE Prioritizer** - **Purpose:** RICE framework for backlog prioritization with portfolio analysis - - **Path:** [`scripts/rice_prioritizer.py`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/product-manager-toolkit/scripts/rice_prioritizer.py) - - **Usage:** `python ../../product-team/product-manager-toolkit/scripts/rice_prioritizer.py backlog.csv --capacity 20` + - **Path:** [`scripts/rice_prioritizer.py`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/skills/product-manager-toolkit/scripts/rice_prioritizer.py) + - **Usage:** `python ../../product-team/skills/product-manager-toolkit/scripts/rice_prioritizer.py backlog.csv --capacity 20` - **Features:** Portfolio quadrant analysis, capacity planning, quarterly roadmap generation - **Use Cases:** Backlog ordering, sprint scope decisions, stakeholder alignment ### Knowledge Bases 1. **Sprint Planning Guide** - - **Location:** [`references/sprint-planning-guide.md`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/agile-product-owner/references/sprint-planning-guide.md) + - **Location:** [`references/sprint-planning-guide.md`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/agile-product-owner/skills/agile-product-owner/references/sprint-planning-guide.md) - **Content:** Sprint planning ceremonies, velocity tracking, capacity allocation, sprint goal setting - **Use Case:** Sprint planning facilitation, capacity management 2. **User Story Templates** - - **Location:** [`references/user-story-templates.md`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/agile-product-owner/references/user-story-templates.md) + - **Location:** [`references/user-story-templates.md`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/agile-product-owner/skills/agile-product-owner/references/user-story-templates.md) - **Content:** INVEST-compliant story formats, acceptance criteria patterns, story splitting techniques - **Use Case:** Story writing, backlog grooming, definition of done 3. **PRD Templates** - - **Location:** [`references/prd_templates.md`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/product-manager-toolkit/references/prd_templates.md) + - **Location:** [`references/prd_templates.md`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/skills/product-manager-toolkit/references/prd_templates.md) - **Content:** Product requirements document formats for different complexity levels - **Use Case:** Epic documentation, feature specification ### Templates 1. **Sprint Planning Template** - - **Location:** [`assets/sprint_planning_template.md`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/agile-product-owner/assets/sprint_planning_template.md) + - **Location:** [`assets/sprint_planning_template.md`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/agile-product-owner/skills/agile-product-owner/assets/sprint_planning_template.md) - **Use Case:** Sprint planning sessions, capacity tracking, sprint goal documentation 2. **User Story Template** - - **Location:** [`assets/user_story_template.md`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/agile-product-owner/assets/user_story_template.md) + - **Location:** [`assets/user_story_template.md`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/agile-product-owner/skills/agile-product-owner/assets/user_story_template.md) - **Use Case:** Consistent story format, acceptance criteria structure 3. **RICE Input Template** - - **Location:** [`assets/rice_input_template.csv`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/product-manager-toolkit/assets/rice_input_template.csv) + - **Location:** [`assets/rice_input_template.csv`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/skills/product-manager-toolkit/assets/rice_input_template.csv) - **Use Case:** Structuring backlog items for RICE prioritization ## Workflows @@ -105,7 +105,7 @@ The cs-agile-product-owner agent bridges strategic product goals with sprint-lev 3. **Generate Stories** - Run the user story generator: ```bash - python ../../product-team/agile-product-owner/scripts/user_story_generator.py epic.yaml + python ../../product-team/agile-product-owner/skills/agile-product-owner/scripts/user_story_generator.py epic.yaml ``` 4. **Review and Refine** - For each generated story: @@ -139,10 +139,10 @@ epic: EOF # Generate user stories -python ../../product-team/agile-product-owner/scripts/user_story_generator.py dashboard-epic.yaml +python ../../product-team/agile-product-owner/skills/agile-product-owner/scripts/user_story_generator.py dashboard-epic.yaml # Review the sprint planning guide for context -cat ../../product-team/agile-product-owner/references/sprint-planning-guide.md +cat ../../product-team/agile-product-owner/skills/agile-product-owner/references/sprint-planning-guide.md ``` ### Workflow 2: Sprint Planning @@ -170,12 +170,12 @@ cat ../../product-team/agile-product-owner/references/sprint-planning-guide.md 4. **Select Stories** - Pull from prioritized backlog: ```bash # Prioritize candidates if not already ordered - python ../../product-team/product-manager-toolkit/scripts/rice_prioritizer.py sprint-candidates.csv --capacity 12 + python ../../product-team/skills/product-manager-toolkit/scripts/rice_prioritizer.py sprint-candidates.csv --capacity 12 ``` 5. **Document the Plan** - Use the sprint planning template: ```bash - cat ../../product-team/agile-product-owner/assets/sprint_planning_template.md + cat ../../product-team/agile-product-owner/skills/agile-product-owner/assets/sprint_planning_template.md ``` 6. **Identify Risks** - Document potential blockers: @@ -200,10 +200,10 @@ Password Reset Flow Fix,1000,2,1.0,1 EOF # Run prioritization -python ../../product-team/product-manager-toolkit/scripts/rice_prioritizer.py sprint-candidates.csv --capacity 8 +python ../../product-team/skills/product-manager-toolkit/scripts/rice_prioritizer.py sprint-candidates.csv --capacity 8 # Reference sprint planning template -cat ../../product-team/agile-product-owner/assets/sprint_planning_template.md +cat ../../product-team/agile-product-owner/skills/agile-product-owner/assets/sprint_planning_template.md ``` ### Workflow 3: Backlog Refinement @@ -225,7 +225,7 @@ cat ../../product-team/agile-product-owner/assets/sprint_planning_template.md 3. **Prioritize with RICE** - Score backlog items: ```bash - python ../../product-team/product-manager-toolkit/scripts/rice_prioritizer.py backlog.csv + python ../../product-team/skills/product-manager-toolkit/scripts/rice_prioritizer.py backlog.csv ``` 4. **Refine Top Items** - Ensure top 2 sprints worth are ready: @@ -257,10 +257,10 @@ Dark Mode,300,1,0.8,3 EOF # Run full prioritization with capacity -python ../../product-team/product-manager-toolkit/scripts/rice_prioritizer.py backlog-q2.csv --capacity 15 +python ../../product-team/skills/product-manager-toolkit/scripts/rice_prioritizer.py backlog-q2.csv --capacity 15 # Review user story templates for refinement -cat ../../product-team/agile-product-owner/references/user-story-templates.md +cat ../../product-team/agile-product-owner/skills/agile-product-owner/references/user-story-templates.md ``` ### Workflow 4: Story Writing Workshop @@ -281,7 +281,7 @@ cat ../../product-team/agile-product-owner/references/user-story-templates.md 3. **Write Stories Collaboratively** - Use the template: ```bash - cat ../../product-team/agile-product-owner/assets/user_story_template.md + cat ../../product-team/agile-product-owner/skills/agile-product-owner/assets/user_story_template.md ``` - "As a [persona], I want [capability], so that [benefit]" - Focus on user value, not implementation details @@ -312,13 +312,13 @@ cat ../../product-team/agile-product-owner/references/user-story-templates.md **Example:** ```bash # Generate initial story candidates from epic -python ../../product-team/agile-product-owner/scripts/user_story_generator.py feature-epic.yaml +python ../../product-team/agile-product-owner/skills/agile-product-owner/scripts/user_story_generator.py feature-epic.yaml # Reference story templates for format guidance -cat ../../product-team/agile-product-owner/references/user-story-templates.md +cat ../../product-team/agile-product-owner/skills/agile-product-owner/references/user-story-templates.md # Reference sprint planning guide for estimation practices -cat ../../product-team/agile-product-owner/references/sprint-planning-guide.md +cat ../../product-team/agile-product-owner/skills/agile-product-owner/references/sprint-planning-guide.md ``` ## Integration Examples @@ -338,17 +338,17 @@ echo "==========================" # Step 1: Prioritize backlog echo "" echo "1. Backlog Prioritization:" -python ../../product-team/product-manager-toolkit/scripts/rice_prioritizer.py backlog.csv --capacity $CAPACITY +python ../../product-team/skills/product-manager-toolkit/scripts/rice_prioritizer.py backlog.csv --capacity $CAPACITY # Step 2: Generate stories for top epic echo "" echo "2. Story Generation for Top Epic:" -python ../../product-team/agile-product-owner/scripts/user_story_generator.py top-epic.yaml +python ../../product-team/agile-product-owner/skills/agile-product-owner/scripts/user_story_generator.py top-epic.yaml # Step 3: Reference planning template echo "" echo "3. Sprint Planning Template:" -echo "See: ../../product-team/agile-product-owner/assets/sprint_planning_template.md" +echo "See: ../../product-team/agile-product-owner/skills/agile-product-owner/assets/sprint_planning_template.md" ``` ### Example 2: Backlog Health Check @@ -369,12 +369,12 @@ echo "items in backlog" # Run prioritization echo "" echo "Current Priorities:" -python ../../product-team/product-manager-toolkit/scripts/rice_prioritizer.py backlog.csv --capacity 20 +python ../../product-team/skills/product-manager-toolkit/scripts/rice_prioritizer.py backlog.csv --capacity 20 # Check story templates echo "" echo "Story Template Reference:" -echo "Location: ../../product-team/agile-product-owner/references/user-story-templates.md" +echo "Location: ../../product-team/agile-product-owner/skills/agile-product-owner/references/user-story-templates.md" ``` ## Success Metrics @@ -402,15 +402,15 @@ echo "Location: ../../product-team/agile-product-owner/references/user-story-tem - [cs-product-manager](cs-product-manager.md) - Full product management lifecycle (RICE, interviews, PRDs) - [cs-product-strategist](cs-product-strategist.md) - OKR cascade and strategic planning for roadmap alignment - [cs-ux-researcher](cs-ux-researcher.md) - User research to inform story requirements and acceptance criteria -- Scrum Master - Velocity context and sprint execution (see [`project-management/scrum-master`](https://github.com/alirezarezvani/claude-skills/tree/main/project-management/scrum-master)) +- Scrum Master - Velocity context and sprint execution (see [`skills/scrum-master`](https://github.com/alirezarezvani/claude-skills/tree/main/project-management/skills/scrum-master)) ## References -- **Primary Skill:** [../../product-team/agile-product-owner/SKILL.md](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/agile-product-owner/SKILL.md) -- **RICE Framework:** [../../product-team/product-manager-toolkit/SKILL.md](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/product-manager-toolkit/SKILL.md) +- **Primary Skill:** [../../product-team/agile-product-owner/skills/agile-product-owner/SKILL.md](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/agile-product-owner/skills/agile-product-owner/SKILL.md) +- **RICE Framework:** [../../product-team/skills/product-manager-toolkit/SKILL.md](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/skills/product-manager-toolkit/SKILL.md) - **Product Domain Guide:** [../../product-team/CLAUDE.md](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/CLAUDE.md) - **Agent Development Guide:** [../CLAUDE.md](https://github.com/alirezarezvani/claude-skills/tree/main/agents/CLAUDE.md) -- **Scrum Master Skill:** [../../project-management/scrum-master/SKILL.md](https://github.com/alirezarezvani/claude-skills/tree/main/project-management/scrum-master/SKILL.md) +- **Scrum Master Skill:** [../../project-management/skills/scrum-master/SKILL.md](https://github.com/alirezarezvani/claude-skills/tree/main/project-management/skills/scrum-master/SKILL.md) --- diff --git a/docs/agents/cs-andreessen.md b/docs/agents/cs-andreessen.md index 0f52e1e1..ef45c1d4 100644 --- a/docs/agents/cs-andreessen.md +++ b/docs/agents/cs-andreessen.md @@ -76,17 +76,17 @@ Differentiates from siblings: ### Python Tools (Stdlib) -1. **Market-First Evaluator** — `scripts/market_first_evaluator.py` — weighted market > team > +1. **Market-First Evaluator** — `skills/andreessen/scripts/market_first_evaluator.py` — weighted market > team > product; sub-4 market is a hard kill gate. -2. **PMF Signal Scorer** — `scripts/pmf_signal_scorer.py` — 4 qualitative signals + Sean Ellis 40% gate. -3. **Anti-Todo 3x5 Card** — `scripts/anti_todo_card.py` — front capped at 3-5, back is the Anti-Todo log. +2. **PMF Signal Scorer** — `skills/andreessen/scripts/pmf_signal_scorer.py` — 4 qualitative signals + Sean Ellis 40% gate. +3. **Anti-Todo 3x5 Card** — `skills/andreessen/scripts/anti_todo_card.py` — front capped at 3-5, back is the Anti-Todo log. ### Knowledge Bases -- `references/operating_prompt.md` — verbatim operating prompt + posture mapping (5 sources) -- `references/market_first_canon.md` — market > team > product (7 sources) -- `references/pmf_and_build_canon.md` — PMF phases + Ellis 40% + "It's Time to Build" (7 sources) -- `references/personal_productivity_system.md` — 3x5 card + Anti-Todo + scheduling reversal (7 sources) +- `skills/andreessen/references/operating_prompt.md` — verbatim operating prompt + posture mapping (5 sources) +- `skills/andreessen/references/market_first_canon.md` — market > team > product (7 sources) +- `skills/andreessen/references/pmf_and_build_canon.md` — PMF phases + Ellis 40% + "It's Time to Build" (7 sources) +- `skills/andreessen/references/personal_productivity_system.md` — 3x5 card + Anti-Todo + scheduling reversal (7 sources) ## Related Agents diff --git a/docs/agents/cs-backend-engineer.md b/docs/agents/cs-backend-engineer.md index d2fda9a7..0b2ce730 100644 --- a/docs/agents/cs-backend-engineer.md +++ b/docs/agents/cs-backend-engineer.md @@ -126,8 +126,8 @@ python ../../engineering/karpathy-coder/skills/karpathy-coder/scripts/diff_surge - [cs-frontend-engineer](cs-frontend-engineer.md) — fork into for API consumers - [cs-karpathy-reviewer](cs-karpathy-reviewer.md) — invoke before every commit - [cs-cto-advisor](https://github.com/alirezarezvani/claude-skills/tree/main/agents/c-level/cs-cto-advisor.md) — escalate strategic build-vs-buy -- [cs-vpe-advisor](https://github.com/alirezarezvani/claude-skills/tree/main/agents/c-level/cs-vpe-advisor.md) — escalate throughput / org / DORA -- [cs-ciso-advisor](https://github.com/alirezarezvani/claude-skills/tree/main/agents/c-level/cs-ciso-advisor.md) — escalate regulated-data exposure +- [cs-vpe-advisor](https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor/c-level-agents/agents/cs-vpe-advisor.md) — escalate throughput / org / DORA +- [cs-ciso-advisor](https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor/c-level-agents/agents/cs-ciso-advisor.md) — escalate regulated-data exposure ## Invocation Contract diff --git a/docs/agents/cs-caio-advisor.md b/docs/agents/cs-caio-advisor.md index 4f3bf1b3..f088874f 100644 --- a/docs/agents/cs-caio-advisor.md +++ b/docs/agents/cs-caio-advisor.md @@ -161,7 +161,7 @@ python ../../skills/chief-ai-officer-advisor/scripts/ai_cost_economics.py worklo ## Related Agents - [cs-cdo-advisor](cs-cdo-advisor.md) — Training data rights, data strategy (chains directly to model decisions) -- [cs-cto-advisor](https://github.com/alirezarezvani/claude-skills/tree/main/../agents/c-level/cs-cto-advisor.md) — Architecture capacity, scaling cliffs +- [cs-cto-advisor](https://github.com/alirezarezvani/claude-skills/tree/main/agents/c-level/cs-cto-advisor.md) — Architecture capacity, scaling cliffs - [cs-ciso-advisor](cs-ciso-advisor.md) — Threat modeling for AI (prompt injection, jailbreak, training-data poisoning) - [cs-general-counsel-advisor](cs-general-counsel-advisor.md) — AI contracts, vendor liability, output ownership - [cs-cfo-advisor](cs-cfo-advisor.md) — Build-vs-buy TCO, multi-year vendor commitments diff --git a/docs/agents/cs-capture.md b/docs/agents/cs-capture.md index b4199a5b..b27a2d86 100644 --- a/docs/agents/cs-capture.md +++ b/docs/agents/cs-capture.md @@ -38,10 +38,10 @@ The cs-capture agent orchestrates the `capture` skill across brain-dump-organize 1. **Detect the trigger** — explicit phrase OR implicit unstructured block paste 2. **Capture everything** — no item is too trivial; user prunes later -3. **Classify items** — task vs decision vs question vs project-component (use `scripts/dump_classifier.py` as a heuristic seed) +3. **Classify items** — task vs decision vs question vs project-component (use `skills/capture/scripts/dump_classifier.py` as a heuristic seed) 4. **Cluster** — only when natural clustering exists; don't force structure on small dumps -5. **Inventory the workspace** — `scripts/workspace_inventory.py` for real Glob+Grep matches; never fabricate -6. **Compress when warranted** — `scripts/complexity_estimator.py` recommends full 4-section vs compressed +5. **Inventory the workspace** — `skills/capture/scripts/workspace_inventory.py` for real Glob+Grep matches; never fabricate +6. **Compress when warranted** — `skills/capture/scripts/complexity_estimator.py` recommends full 4-section vs compressed 7. **Deliver + wait** — output the sections; wait for the user's pick before any further action Differentiates clearly: @@ -196,8 +196,8 @@ Which should I tackle? ## Related Agents -- [cs-grill-master](https://github.com/alirezarezvani/claude-skills/tree/main/productivity/grill-me/agents/cs-grill-master.md) — slow, deliberate plan interrogator (different mode) -- [cs-grill-with-docs](https://github.com/alirezarezvani/claude-skills/tree/main/productivity/grill-with-docs/agents/cs-grill-with-docs.md) — docs-anchored grill (different scope) +- [cs-grill-master](https://github.com/alirezarezvani/claude-skills/tree/main/engineering/grill-me/agents/cs-grill-master.md) — slow, deliberate plan interrogator (different mode) +- [cs-grill-with-docs](https://github.com/alirezarezvani/claude-skills/tree/main/engineering/grill-with-docs/agents/cs-grill-with-docs.md) — docs-anchored grill (different scope) - [cs-handoff-author](https://github.com/alirezarezvani/claude-skills/tree/main/productivity/handoff/agents/cs-handoff-author.md) — different artifact (continuation prompt) ## References diff --git a/docs/agents/cs-cco-advisor.md b/docs/agents/cs-cco-advisor.md index df8c386b..888d9b5f 100644 --- a/docs/agents/cs-cco-advisor.md +++ b/docs/agents/cs-cco-advisor.md @@ -163,7 +163,7 @@ python ../../skills/chief-customer-officer-advisor/scripts/cs_coverage_calculato - [cs-cmo-advisor](cs-cmo-advisor.md) — Customer marketing, advocacy, references - [cs-cfo-advisor](cs-cfo-advisor.md) — CS team cost, retention-impact-on-revenue - [cs-chro-advisor](cs-chro-advisor.md) — CS team hiring + leveling + comp -- [cs-growth-strategist](https://github.com/alirezarezvani/claude-skills/tree/main/../agents/business-growth/cs-growth-strategist.md) — Tactical CS execution +- [cs-growth-strategist](https://github.com/alirezarezvani/claude-skills/tree/main/agents/business-growth/cs-growth-strategist.md) — Tactical CS execution ## References diff --git a/docs/agents/cs-cdo-advisor.md b/docs/agents/cs-cdo-advisor.md index 17b8b9a2..8ecc82ad 100644 --- a/docs/agents/cs-cdo-advisor.md +++ b/docs/agents/cs-cdo-advisor.md @@ -107,7 +107,7 @@ python ../../skills/chief-data-officer-advisor/scripts/data_asset_valuator.py co **Goal:** Sequence the next 18 months of data hires aligned to business decisions. 1. List top 5 decisions the business can't make today due to missing data/analysis -2. Map each decision to the role that unblocks it (see references/data_team_org_evolution.md) +2. Map each decision to the role that unblocks it (see ../../skills/chief-data-officer-advisor/references/data_team_org_evolution.md) 3. Sequence hires (one at a time, ramp before next) 4. Cross-check with cs-chro-advisor on comp bands + leveling 5. Identify centralize-vs-embed trigger date @@ -147,7 +147,7 @@ echo "Kill criteria + checkpoint dates in each output." ## Related Agents -- [cs-cto-advisor](https://github.com/alirezarezvani/claude-skills/tree/main/../agents/c-level/cs-cto-advisor.md) — architecture capacity +- [cs-cto-advisor](https://github.com/alirezarezvani/claude-skills/tree/main/agents/c-level/cs-cto-advisor.md) — architecture capacity - [cs-ciso-advisor](cs-ciso-advisor.md) — data security, threat modeling for productized data - [cs-cpo-advisor](cs-cpo-advisor.md) — product strategy (when data becomes product) - [cs-general-counsel-advisor](cs-general-counsel-advisor.md) — contractual constraints, DPA, training-rights diff --git a/docs/agents/cs-ceo-advisor.md b/docs/agents/cs-ceo-advisor.md index 34d56280..a842df1e 100644 --- a/docs/agents/cs-ceo-advisor.md +++ b/docs/agents/cs-ceo-advisor.md @@ -1,6 +1,6 @@ --- title: "CEO Advisor Agent — AI Coding Agent & Codex Skill" -description: "Strategic leadership advisor for CEOs covering vision, strategy, board management, investor relations, and organizational culture. Agent-native orchestrator for Claude Code, Codex, Gemini CLI." +description: "Strategic leadership advisor for CEOs covering vision, strategy, board management, investor relations, and organizational culture. Use when a founder. Agent-native orchestrator for Claude Code, Codex, Gemini CLI." --- # CEO Advisor Agent diff --git a/docs/agents/cs-cfo-advisor.md b/docs/agents/cs-cfo-advisor.md index f0811c91..83aa6f32 100644 --- a/docs/agents/cs-cfo-advisor.md +++ b/docs/agents/cs-cfo-advisor.md @@ -117,9 +117,9 @@ echo "Artifacts ready in /tmp/. Feed into /cs:boardroom brief." ## Related Agents -- [cs-ceo-advisor](https://github.com/alirezarezvani/claude-skills/tree/main/../agents/c-level/cs-ceo-advisor.md) — strategy & capital allocation partner +- [cs-ceo-advisor](https://github.com/alirezarezvani/claude-skills/tree/main/agents/c-level/cs-ceo-advisor.md) — strategy & capital allocation partner - [cs-cro-advisor](cs-cro-advisor.md) — revenue forecast feed -- [cs-financial-analyst](https://github.com/alirezarezvani/claude-skills/tree/main/../agents/finance/cs-financial-analyst.md) — deep modeling +- [cs-financial-analyst](https://github.com/alirezarezvani/claude-skills/tree/main/agents/finance/cs-financial-analyst.md) — deep modeling - [cs-chief-of-staff](cs-chief-of-staff.md) — routes financial questions here ## References diff --git a/docs/agents/cs-chief-of-staff.md b/docs/agents/cs-chief-of-staff.md index 06275041..2b001f45 100644 --- a/docs/agents/cs-chief-of-staff.md +++ b/docs/agents/cs-chief-of-staff.md @@ -32,8 +32,8 @@ This is the agent the founder talks to **first**. It pulls company-context.md, p ### Knowledge Bases -- [`references/routing_logic.md`](https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor/skills/chief-of-staff/references/routing_logic.md) — keywords → role mapping, multi-role triggers -- [`references/synthesis_patterns.md`](https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor/skills/chief-of-staff/references/synthesis_patterns.md) — how to combine inputs from multiple advisors +- [`references/routing-matrix.md`](https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor/skills/chief-of-staff/references/routing-matrix.md) — keywords → role mapping, multi-role triggers +- [`references/synthesis-framework.md`](https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor/skills/chief-of-staff/references/synthesis-framework.md) — how to combine inputs from multiple advisors ### Coordination Skills @@ -122,7 +122,7 @@ echo "Decision logged to ~/.claude/decisions/raw/$(date +%Y-%m-%d)-$RANDOM.md" ## Related Agents - All cs-* C-level advisors (routes to them) -- [cs-ceo-advisor](https://github.com/alirezarezvani/claude-skills/tree/main/../agents/c-level/cs-ceo-advisor.md) — primary upward report +- [cs-ceo-advisor](https://github.com/alirezarezvani/claude-skills/tree/main/agents/c-level/cs-ceo-advisor.md) — primary upward report - [executive-mentor / devils-advocate](https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor/executive-mentor/agents/devils-advocate.md) — pre-decision adversarial check ## References diff --git a/docs/agents/cs-chro-advisor.md b/docs/agents/cs-chro-advisor.md index 2304cfa9..0f78fdc4 100644 --- a/docs/agents/cs-chro-advisor.md +++ b/docs/agents/cs-chro-advisor.md @@ -42,9 +42,9 @@ Pairs with `cs-coo-advisor` (org design), `cs-cfo-advisor` (comp budget), and `c ### Knowledge Bases -- [`references/hiring_systems.md`](https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor/skills/chro-advisor/references/hiring_systems.md) — sourcing channels, interview rubrics, scorecards, time-to-fill -- [`references/comp_philosophy.md`](https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor/skills/chro-advisor/references/comp_philosophy.md) — band design, equity strategy, refresh policy -- [`references/leveling_ladders.md`](https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor/skills/chro-advisor/references/leveling_ladders.md) — IC + manager tracks, level expectations, promotion criteria +- [`references/people_strategy.md`](https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor/skills/chro-advisor/references/people_strategy.md) — sourcing channels, interview rubrics, scorecards, time-to-fill +- [`references/comp_frameworks.md`](https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor/skills/chro-advisor/references/comp_frameworks.md) — band design, equity strategy, refresh policy +- [`references/org_design.md`](https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor/skills/chro-advisor/references/org_design.md) — IC + manager tracks, level expectations, promotion criteria ## Workflows @@ -95,7 +95,7 @@ python ../../skills/chro-advisor/scripts/hiring_plan_modeler.py echo "👥 CHRO Quarterly Review" python ../../skills/chro-advisor/scripts/hiring_plan_modeler.py python ../../skills/chro-advisor/scripts/comp_benchmarker.py -echo "Ladder reference: ../../skills/chro-advisor/references/leveling_ladders.md" +echo "Ladder reference: ../../skills/chro-advisor/references/org_design.md" ``` ## Success Metrics @@ -110,8 +110,8 @@ echo "Ladder reference: ../../skills/chro-advisor/references/leveling_ladders.md - [cs-coo-advisor](cs-coo-advisor.md) — org design partner - [cs-cfo-advisor](cs-cfo-advisor.md) — comp budget -- [cs-ceo-advisor](https://github.com/alirezarezvani/claude-skills/tree/main/../agents/c-level/cs-ceo-advisor.md) — exec team -- [cs-workspace-admin](https://github.com/alirezarezvani/claude-skills/tree/main/../agents/engineering-team/cs-workspace-admin.md) — onboarding tooling +- [cs-ceo-advisor](https://github.com/alirezarezvani/claude-skills/tree/main/agents/c-level/cs-ceo-advisor.md) — exec team +- [cs-workspace-admin](https://github.com/alirezarezvani/claude-skills/tree/main/agents/engineering-team/cs-workspace-admin.md) — onboarding tooling ## References diff --git a/docs/agents/cs-ciso-advisor.md b/docs/agents/cs-ciso-advisor.md index 7365dd3e..6940ce6d 100644 --- a/docs/agents/cs-ciso-advisor.md +++ b/docs/agents/cs-ciso-advisor.md @@ -42,7 +42,7 @@ Pairs with `cs-cto-advisor` (security architecture), `cs-cfo-advisor` (risk quan ### Knowledge Bases -- [`references/threat_modeling.md`](https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor/skills/ciso-advisor/references/threat_modeling.md) — STRIDE, PASTA, attacker journey +- [`references/security_strategy.md`](https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor/skills/ciso-advisor/references/security_strategy.md) — STRIDE, PASTA, attacker journey - [`references/compliance_roadmap.md`](https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor/skills/ciso-advisor/references/compliance_roadmap.md) — SOC 2 Type 2, ISO 27001, GDPR sequencing - [`references/incident_response.md`](https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor/skills/ciso-advisor/references/incident_response.md) — IR runbooks, comms plan, regulator notification windows @@ -113,10 +113,10 @@ echo "IR runbook check: ../../skills/ciso-advisor/references/incident_response.m ## Related Agents -- [cs-cto-advisor](https://github.com/alirezarezvani/claude-skills/tree/main/../agents/c-level/cs-cto-advisor.md) — security architecture +- [cs-cto-advisor](https://github.com/alirezarezvani/claude-skills/tree/main/agents/c-level/cs-cto-advisor.md) — security architecture - [cs-cfo-advisor](cs-cfo-advisor.md) — risk → insurance, audit budget -- [cs-quality-regulatory](https://github.com/alirezarezvani/claude-skills/tree/main/../agents/ra-qm-team/cs-quality-regulatory.md) — ISO 27001, GDPR execution -- [cs-senior-engineer](https://github.com/alirezarezvani/claude-skills/tree/main/../agents/engineering/cs-senior-engineer.md) — secure coding +- [cs-quality-regulatory](https://github.com/alirezarezvani/claude-skills/tree/main/agents/ra-qm-team/cs-quality-regulatory.md) — ISO 27001, GDPR execution +- [cs-senior-engineer](https://github.com/alirezarezvani/claude-skills/tree/main/agents/engineering/cs-senior-engineer.md) — secure coding ## References diff --git a/docs/agents/cs-claude-coach.md b/docs/agents/cs-claude-coach.md index ea778c3d..2bf5f9ca 100644 --- a/docs/agents/cs-claude-coach.md +++ b/docs/agents/cs-claude-coach.md @@ -33,7 +33,7 @@ You are the persona behind the `claude-coach` skill. Your job is to teach the us ## When to invoke -Activate on first explicit request to learn Claude ("coach me", "make me a power user", "Claude cheat codes"). Stay on for the remainder of the conversation. On every subsequent turn, run the 5-gate decision tree from `references/coaching-rules.md` before deciding whether to surface a tip. +Activate on first explicit request to learn Claude ("coach me", "make me a power user", "Claude cheat codes"). Stay on for the remainder of the conversation. On every subsequent turn, run the 5-gate decision tree from `skills/claude-coach/references/coaching-rules.md` before deciding whether to surface a tip. ## On-demand modes diff --git a/docs/agents/cs-cmo-advisor.md b/docs/agents/cs-cmo-advisor.md index d1e19ffa..6e3625c4 100644 --- a/docs/agents/cs-cmo-advisor.md +++ b/docs/agents/cs-cmo-advisor.md @@ -43,8 +43,8 @@ Pairs with `cs-cpo-advisor` (positioning ↔ product), `cs-cro-advisor` (positio ### Knowledge Bases - [`references/brand_positioning.md`](https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor/skills/cmo-advisor/references/brand_positioning.md) — category design, message house, narrative arcs -- [`references/growth_playbooks.md`](https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor/skills/cmo-advisor/references/growth_playbooks.md) — channel-specific motions, PLG vs sales-led -- [`references/marketing_operations.md`](https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor/skills/cmo-advisor/references/marketing_operations.md) — attribution, cadence, content ops +- [`references/growth_frameworks.md`](https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor/skills/cmo-advisor/references/growth_frameworks.md) — channel-specific motions, PLG vs sales-led +- [`references/marketing_org.md`](https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor/skills/cmo-advisor/references/marketing_org.md) — attribution, cadence, content ops ### Adjacent Execution @@ -114,8 +114,8 @@ echo "📚 Reference: positioning + playbooks" - [cs-cpo-advisor](cs-cpo-advisor.md) — positioning ↔ product alignment - [cs-cro-advisor](cs-cro-advisor.md) — pipeline contribution -- [cs-content-creator](https://github.com/alirezarezvani/claude-skills/tree/main/../agents/marketing/cs-content-creator.md) — execution -- [cs-demand-gen-specialist](https://github.com/alirezarezvani/claude-skills/tree/main/../agents/marketing/cs-demand-gen-specialist.md) — execution +- [cs-content-creator](https://github.com/alirezarezvani/claude-skills/tree/main/agents/marketing/cs-content-creator.md) — execution +- [cs-demand-gen-specialist](https://github.com/alirezarezvani/claude-skills/tree/main/agents/marketing/cs-demand-gen-specialist.md) — execution ## References diff --git a/docs/agents/cs-content-creator.md b/docs/agents/cs-content-creator.md index a2abf27b..67056b78 100644 --- a/docs/agents/cs-content-creator.md +++ b/docs/agents/cs-content-creator.md @@ -1,6 +1,6 @@ --- title: "Content Creator Agent — AI Coding Agent & Codex Skill" -description: "AI-powered content creation specialist for brand voice consistency, SEO optimization, and multi-platform content strategy. Agent-native orchestrator for Claude Code, Codex, Gemini CLI." +description: "Long-form marketing content producer orchestrating the content-production skill (research → brief → draft → optimize → gate). Use when content must. Agent-native orchestrator for Claude Code, Codex, Gemini CLI." --- # Content Creator Agent @@ -14,237 +14,129 @@ description: "AI-powered content creation specialist for brand voice consistency ## Purpose -The cs-content-creator agent is a specialized marketing agent that orchestrates the content-creator skill package to help teams produce high-quality, on-brand content at scale. This agent combines brand voice analysis, SEO optimization, and platform-specific best practices to ensure every piece of content meets quality standards and performs well across channels. +The cs-content-creator agent is the marketing domain's **content execution specialist**. It orchestrates the `content-production` skill to take a topic from blank page to publish-ready piece: competitive research, content brief, full draft, then a mechanical optimization pass (SEO, readability, brand voice) gated by deterministic scorers. -This agent is designed for marketing teams, content creators, and solo founders who need to maintain brand consistency while optimizing for search engines and social media platforms. By leveraging Python-based analysis tools and comprehensive content frameworks, the agent enables data-driven content decisions without requiring deep technical expertise. +It is the execution engine, not the strategy layer: -The cs-content-creator agent bridges the gap between creative content production and technical SEO requirements, ensuring that content is both engaging for humans and optimized for search engines. It provides actionable feedback on brand voice alignment, keyword optimization, and platform-specific formatting. +- **vs `content-strategy`**: content-strategy decides WHAT to write (topic clusters, calendars, prioritization). This agent writes and polishes the piece. Route planning-only requests there. +- **vs `cs-aeo`**: cs-aeo optimizes finished content for LLM citation (AEO). This agent produces the content; run cs-aeo afterwards when AI-search citation matters. +- **vs the deprecated `content-creator` skill**: that skill is a redirect stub (`marketing-skill/skills/content-creator/SKILL.md`, status: deprecated). Never load it — this agent targets its successor, `content-production`, directly. + +**Hard rule:** no draft is "done" until the quality gates pass. A failing gate from `content_quality_gates.py` blocks publish; fix and re-run until clean. + +## Step 0 — Read the Marketing Context File + +Before asking the user anything, check for the canonical context file: + +```bash +cat .claude/product-marketing-context.md 2>/dev/null +``` + +If it exists, it contains brand voice, target audience, keyword targets, and writing examples — use what's there and only ask for what's missing (topic/angle, target keyword, length, goal). If it doesn't exist, recommend running the `marketing-context` skill first, then gather the missing inputs in one shot. ## Skill Integration -**Skill Location:** [`marketing-skill/content-creator`](https://github.com/alirezarezvani/claude-skills/tree/main/marketing-skill/content-creator) +**Skill location:** [`skills/content-production`](https://github.com/alirezarezvani/claude-skills/tree/main/marketing-skill/skills/content-production) ([SKILL.md](https://github.com/alirezarezvani/claude-skills/tree/main/marketing-skill/skills/content-production/SKILL.md)) -### Python Tools +### Python Tools (stdlib only — all pass `--help`) -No Python tools — this skill relies on SKILL.md workflows, knowledge bases, and templates for content creation guidance. +1. **Content Scorer** — 0-100 composite on readability, SEO, structure, engagement + - **Path:** [`scripts/content_scorer.py`](https://github.com/alirezarezvani/claude-skills/tree/main/marketing-skill/skills/content-production/scripts/content_scorer.py) + - **Usage:** `python3 ../../marketing-skill/skills/content-production/scripts/content_scorer.py draft.md "primary keyword" --json` (no args = embedded demo) + - **Threshold:** target score **70+** (the skill's readability gate) +2. **SEO Optimizer** — keyword placement, title/H1/meta audit with fixes + - **Path:** [`scripts/seo_optimizer.py`](https://github.com/alirezarezvani/claude-skills/tree/main/marketing-skill/skills/content-production/scripts/seo_optimizer.py) + - **Usage:** `python3 ../../marketing-skill/skills/content-production/scripts/seo_optimizer.py draft.md --keyword "primary keyword" --secondary "phrase one,phrase two"` +3. **Brand Voice Analyzer** — tone markers, sentence-rhythm stats, vocabulary fingerprint + - **Path:** [`scripts/brand_voice_analyzer.py`](https://github.com/alirezarezvani/claude-skills/tree/main/marketing-skill/skills/content-production/scripts/brand_voice_analyzer.py) + - **Usage:** `python3 ../../marketing-skill/skills/content-production/scripts/brand_voice_analyzer.py draft.md --format json` + - **Use:** compare output against the brand profile in `.claude/product-marketing-context.md`; rewrite sections that drift +4. **Quality Gates** — non-negotiable pre-publish checks (keyword usage, sourced claims, intro cliché, link integrity, readability ≥ 70, word-count tolerance) + - **Path:** [`scripts/content_quality_gates.py`](https://github.com/alirezarezvani/claude-skills/tree/main/marketing-skill/skills/content-production/scripts/content_quality_gates.py) + - **Usage:** `python3 ../../marketing-skill/skills/content-production/scripts/content_quality_gates.py draft.md --json` (`--demo` for a sample article) + - **Rule:** any failing gate blocks publish ### Knowledge Bases -1. **Brand Guidelines** - - **Location:** [`references/brand_guidelines.md`](https://github.com/alirezarezvani/claude-skills/tree/main/marketing-skill/content-creator/references/brand_guidelines.md) - - **Content:** 5 personality archetypes (Expert, Friend, Innovator, Guide, Motivator), voice characteristics matrix, consistency checklist - - **Use Case:** Establishing brand voice, onboarding writers, content audits - -2. **Content Frameworks** - - **Location:** [`references/content_frameworks.md`](https://github.com/alirezarezvani/claude-skills/tree/main/marketing-skill/content-creator/references/content_frameworks.md) - - **Content:** 15+ content templates including blog posts (how-to, listicle, case study), email campaigns, social media posts, video scripts, landing page copy - - **Use Case:** Content planning, writer guidance, structure templates - -3. **Social Media Optimization** - - **Location:** [`references/social_media_optimization.md`](https://github.com/alirezarezvani/claude-skills/tree/main/marketing-skill/content-creator/references/social_media_optimization.md) - - **Content:** Platform-specific best practices for LinkedIn (1,300 chars, professional tone), Twitter/X (280 chars, concise), Instagram (visual-first, caption strategy), Facebook (engagement tactics), TikTok (short-form video) - - **Use Case:** Platform optimization, social media strategy, content adaptation - -4. **Analytics Guide** - - **Location:** [`references/analytics_guide.md`](https://github.com/alirezarezvani/claude-skills/tree/main/marketing-skill/content-creator/references/analytics_guide.md) - - **Content:** Content performance analytics and measurement frameworks - - **Use Case:** Content performance tracking, reporting, data-driven optimization +- [`references/content-brief-guide.md`](https://github.com/alirezarezvani/claude-skills/tree/main/marketing-skill/skills/content-production/references/content-brief-guide.md) — writing briefs that produce better drafts +- [`references/optimization-checklist.md`](https://github.com/alirezarezvani/claude-skills/tree/main/marketing-skill/skills/content-production/references/optimization-checklist.md) — full pre-publish checklist behind the gates +- [`references/content-templates.md`](https://github.com/alirezarezvani/claude-skills/tree/main/marketing-skill/skills/content-production/references/content-templates.md) — long-form structure templates +- [`references/ai-citation-readiness.md`](https://github.com/alirezarezvani/claude-skills/tree/main/marketing-skill/skills/content-production/references/ai-citation-readiness.md) — AEO-adjacent readiness checks (pair with cs-aeo) ### Templates -1. **Content Calendar Template** - - **Location:** [`assets/content_calendar_template.md`](https://github.com/alirezarezvani/claude-skills/tree/main/marketing-skill/content-creator/assets/content_calendar_template.md) - - **Use Case:** Planning monthly content, tracking production pipeline +- [`templates/content-brief-template.md`](https://github.com/alirezarezvani/claude-skills/tree/main/marketing-skill/skills/content-production/templates/content-brief-template.md) — fill before drafting (Mode 1 output) ## Workflows -### Workflow 1: Blog Post Creation & Optimization +### Workflow 1: Blog Post — Research to Publish-Ready -**Goal:** Create SEO-optimized blog post with consistent brand voice +**Goal:** Take a topic from zero to a gated, publish-ready post (skill Modes 1 → 2 → 3). **Steps:** -1. **Draft Content** - Write initial blog post draft in markdown format -2. **Reference Brand Guidelines** - Review brand voice requirements for tone and readability - ```bash - cat ../../marketing-skill/content-creator/references/brand_guidelines.md - ``` -3. **Review Content Frameworks** - Select appropriate blog post template (how-to, listicle, case study) - ```bash - cat ../../marketing-skill/content-creator/references/content_frameworks.md - ``` -4. **Optimize for SEO** - Apply SEO best practices from SKILL.md workflows (keyword placement, structure, meta description) -5. **Implement Recommendations** - Update content structure, keyword placement, meta description -6. **Final Validation** - Review against brand guidelines and content frameworks +1. **Context** — read `.claude/product-marketing-context.md`; collect topic, primary keyword, audience, goal, length. +2. **Research & brief (Mode 1)** — map the top-ranking pieces and search intent; fill [`templates/content-brief-template.md`](https://github.com/alirezarezvani/claude-skills/tree/main/marketing-skill/skills/content-production/templates/content-brief-template.md) following [`references/content-brief-guide.md`](https://github.com/alirezarezvani/claude-skills/tree/main/marketing-skill/skills/content-production/references/content-brief-guide.md). +3. **Draft (Mode 2)** — outline H2 skeleton, then write intro/body/conclusion per the brief. +4. **SEO pass** — `python3 ../../marketing-skill/skills/content-production/scripts/seo_optimizer.py draft.md --keyword "primary keyword" --secondary "secondary,phrases"`; fix what it flags. +5. **Readability pass** — `python3 ../../marketing-skill/skills/content-production/scripts/content_scorer.py draft.md "primary keyword" --json`; revise until composite ≥ 70. +6. **Verification** — `python3 ../../marketing-skill/skills/content-production/scripts/content_quality_gates.py draft.md --json` must report **all gates passing** (readability ≥ 70, sourced claims, no cliché intro, keyword 3-5x, word count within 10% of target). A failing gate sends the draft back to step 4/5. -**Expected Output:** SEO-optimized blog post with consistent brand voice alignment +**Expected output:** publish-ready draft + completed brief + passing gate report. -**Time Estimate:** 2-3 hours for 1,500-word blog post +### Workflow 2: Brand-Voice Audit of an Existing Draft -**Example:** -```bash -# Review guidelines before writing -cat ../../marketing-skill/content-creator/references/brand_guidelines.md -cat ../../marketing-skill/content-creator/references/content_frameworks.md -``` - -### Workflow 2: Multi-Platform Content Adaptation - -**Goal:** Adapt single piece of content for multiple social media platforms +**Goal:** Catch voice drift before publishing content written elsewhere. **Steps:** -1. **Start with Core Content** - Begin with blog post or long-form content -2. **Reference Platform Guidelines** - Review platform-specific best practices - ```bash - cat ../../marketing-skill/content-creator/references/social_media_optimization.md - ``` -3. **Create LinkedIn Version** - Professional tone, 1,300 characters, 3-5 hashtags -4. **Create Twitter/X Thread** - Break into 280-char tweets, engaging hook -5. **Create Instagram Caption** - Visual-first approach, caption with line breaks, hashtags -6. **Validate Brand Voice** - Ensure consistency across all versions by reviewing against brand guidelines - ```bash - cat ../../marketing-skill/content-creator/references/brand_guidelines.md - ``` +1. **Load the brand profile** — brand-voice section of `.claude/product-marketing-context.md`. +2. **Analyze** — `python3 ../../marketing-skill/skills/content-production/scripts/brand_voice_analyzer.py draft.md --format json`; compare tone markers and sentence-rhythm stats against the profile. +3. **Rewrite drifting sections** — give sentence-level fixes ("Paragraph 3 averages 32 words/sentence — split the second sentence"), not vague advice. +4. **Verification** — re-run `brand_voice_analyzer.py` and confirm the markers now match the profile, then run `content_scorer.py draft.md --json` and confirm composite ≥ 70. -**Expected Output:** 4-5 platform-optimized versions from single source +**Expected output:** annotated draft with voice fixes applied + before/after analyzer comparison. -**Time Estimate:** 1-2 hours for complete adaptation +### Workflow 3: Content-Library SEO + Quality Sweep -### Workflow 3: Content Audit & Brand Consistency Check - -**Goal:** Audit existing content library for brand voice consistency and SEO optimization +**Goal:** Audit a folder of published markdown content and produce a prioritized fix list. **Steps:** -1. **Collect Content** - Gather markdown files for all published content -2. **Brand Voice Review** - Review each content piece against brand guidelines for consistency - ```bash - cat ../../marketing-skill/content-creator/references/brand_guidelines.md - ``` -3. **Identify Inconsistencies** - Check formality, tone patterns, and readability against brand archetypes -4. **SEO Audit** - Review content structure against content frameworks best practices - ```bash - cat ../../marketing-skill/content-creator/references/content_frameworks.md - ``` -5. **Create Improvement Plan** - Prioritize content updates based on SEO score and brand alignment -6. **Implement Updates** - Revise content following brand guidelines and SEO recommendations +1. **Collect** — `ls content/*.md` (or Grep for front-matter keywords to map each piece to its target keyword). +2. **Score each piece** — loop: `for f in content/*.md; do python3 ../../marketing-skill/skills/content-production/scripts/content_scorer.py "$f" --json; done` +3. **Gate each piece** — `python3 ../../marketing-skill/skills/content-production/scripts/content_quality_gates.py "$f" --json`; collect failing gates per file. +4. **Prioritize** — rank by (failing gates desc, score asc); flag keyword cannibalization where two pieces target the same keyword. +5. **Verification** — after fixes, re-run steps 2-3 on edited files; the audit is closed only when every revised file scores ≥ 70 and passes all gates. -**Expected Output:** Comprehensive audit report with prioritized improvement list +**Expected output:** audit table (file, score, failing gates, fix) + re-verified revisions. -**Time Estimate:** 4-6 hours for 20-30 content pieces +## Proactive Routing -**Example:** -```bash -# Review brand guidelines and frameworks before auditing content -cat ../../marketing-skill/content-creator/references/brand_guidelines.md -cat ../../marketing-skill/content-creator/references/analytics_guide.md -``` - -### Workflow 4: Campaign Content Planning - -**Goal:** Plan and structure content for multi-channel marketing campaign - -**Steps:** -1. **Reference Content Frameworks** - Select appropriate templates for campaign - ```bash - cat ../../marketing-skill/content-creator/references/content_frameworks.md - ``` -2. **Copy Content Calendar** - Use template for campaign planning - ```bash - cp ../../marketing-skill/content-creator/assets/content_calendar_template.md campaign-calendar.md - ``` -3. **Define Brand Voice Target** - Reference brand guidelines for campaign tone - ```bash - cat ../../marketing-skill/content-creator/references/brand_guidelines.md - ``` -4. **Create Content Briefs** - Use brief template for each content piece -5. **Draft All Content** - Produce blog posts, social media posts, email campaigns -6. **Validate Before Publishing** - Review all campaign content against brand guidelines and social media optimization guides - ```bash - cat ../../marketing-skill/content-creator/references/brand_guidelines.md - cat ../../marketing-skill/content-creator/references/social_media_optimization.md - ``` - -**Expected Output:** Complete campaign content library with consistent brand voice and optimized SEO - -**Time Estimate:** 8-12 hours for full campaign (10-15 content pieces) - -## Integration Examples - -### Example 1: Content Quality Review Workflow - -```bash -#!/bin/bash -# content-review.sh - Content quality review using knowledge bases - -CONTENT_FILE=$1 - -echo "Reviewing brand voice guidelines..." -cat ../../marketing-skill/content-creator/references/brand_guidelines.md - -echo "" -echo "Reviewing content frameworks..." -cat ../../marketing-skill/content-creator/references/content_frameworks.md - -echo "" -echo "Review complete. Compare $CONTENT_FILE against the guidelines above." -``` - -**Usage:** `./content-review.sh blog-post.md` - -### Example 2: Platform-Specific Content Adaptation - -```bash -# Review platform guidelines before adapting content -cat ../../marketing-skill/content-creator/references/social_media_optimization.md - -# Key platform limits to follow: -# - LinkedIn: 1,300 chars, professional tone, 3-5 hashtags -# - Twitter/X: 280 chars per tweet, engaging hook -# - Instagram: Visual-first, caption with line breaks -``` - -### Example 3: Campaign Content Planning - -```bash -# Set up content calendar from template -cp ../../marketing-skill/content-creator/assets/content_calendar_template.md campaign-calendar.md - -# Review analytics guide for performance tracking -cat ../../marketing-skill/content-creator/references/analytics_guide.md -``` +- "What should we write?" / topic clusters / calendar → [`skills/content-strategy`](https://github.com/alirezarezvani/claude-skills/tree/main/marketing-skill/skills/content-strategy) (out of this agent's lane). +- Draft "sounds like AI" → run `content-humanizer` skill before the optimization pass. +- Optimizing for ChatGPT/Perplexity citation → hand off to [cs-aeo](cs-aeo.md). +- Landing-page or CTA copy → `copywriting` skill, not long-form production. ## Success Metrics -**Content Quality Metrics:** -- **Brand Voice Consistency:** 80%+ of content scores within target formality range (60-80 for professional brands) -- **Readability Score:** Flesch Reading Ease 60-80 (standard audience) or 80-90 (general audience) -- **SEO Performance:** Average SEO score 75+ across all published content - -**Efficiency Metrics:** -- **Content Production Speed:** 40% faster with analyzer feedback vs manual review -- **Revision Cycles:** 30% reduction in editorial rounds -- **Time to Publish:** 25% faster from draft to publication - -**Business Metrics:** -- **Organic Traffic:** 20-30% increase within 3 months of SEO optimization -- **Engagement Rate:** 15-25% improvement with platform-specific optimization -- **Brand Consistency:** 90%+ brand voice alignment across all channels +- **Gate pass rate:** 100% of published pieces pass `content_quality_gates.py` (blocking). +- **Quality score:** `content_scorer.py` composite ≥ 70 on every published piece. +- **Brand consistency:** analyzer markers within the brand profile range on every piece. +- **Cycle time:** fewer editorial rounds because scorer feedback replaces subjective review. ## Related Agents -- [cs-demand-gen-specialist](cs-demand-gen-specialist.md) - Demand generation and acquisition campaigns -- cs-product-marketing - Product positioning and messaging (planned) -- cs-social-media-manager - Social media management and scheduling (planned) +- [cs-aeo](cs-aeo.md) — optimizes this agent's output for LLM citation (run after production) +- [cs-demand-gen-specialist](cs-demand-gen-specialist.md) — uses this agent's content as demand-gen fuel (gated assets, nurture content) +- [cs-webinar-marketer](cs-webinar-marketer.md) — webinar funnels that consume produced content ## References -- **Skill Documentation:** [../../marketing-skill/content-creator/SKILL.md](https://github.com/alirezarezvani/claude-skills/tree/main/marketing-skill/content-creator/SKILL.md) -- **Marketing Domain Guide:** [../../marketing-skill/CLAUDE.md](https://github.com/alirezarezvani/claude-skills/tree/main/marketing-skill/CLAUDE.md) -- **Agent Development Guide:** [../CLAUDE.md](https://github.com/alirezarezvani/claude-skills/tree/main/agents/CLAUDE.md) -- **Marketing Roadmap:** [../../marketing-skill/marketing_skills_roadmap.md](https://github.com/alirezarezvani/claude-skills/tree/main/marketing-skill/marketing_skills_roadmap.md) +- **Skill documentation:** [../../marketing-skill/skills/content-production/SKILL.md](https://github.com/alirezarezvani/claude-skills/tree/main/marketing-skill/skills/content-production/SKILL.md) +- **Planning sibling:** [../../marketing-skill/skills/content-strategy/SKILL.md](https://github.com/alirezarezvani/claude-skills/tree/main/marketing-skill/skills/content-strategy/SKILL.md) +- **Marketing domain guide:** [../../marketing-skill/CLAUDE.md](https://github.com/alirezarezvani/claude-skills/tree/main/marketing-skill/CLAUDE.md) +- **Agent development guide:** [../CLAUDE.md](https://github.com/alirezarezvani/claude-skills/tree/main/agents/CLAUDE.md) --- -**Last Updated:** November 5, 2025 -**Sprint:** sprint-11-05-2025 (Day 2) +**Last Updated:** June 11, 2026 **Status:** Production Ready -**Version:** 1.0 +**Version:** 2.0 diff --git a/docs/agents/cs-coo-advisor.md b/docs/agents/cs-coo-advisor.md index a5a83799..83837792 100644 --- a/docs/agents/cs-coo-advisor.md +++ b/docs/agents/cs-coo-advisor.md @@ -42,9 +42,9 @@ Pairs with `cs-cfo-advisor` (finance cadence), `cs-cro-advisor` (revenue cadence ### Knowledge Bases -- [`references/operating_cadence.md`](https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor/skills/coo-advisor/references/operating_cadence.md) — weekly/monthly/quarterly rhythm, meeting design -- [`references/okr_execution.md`](https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor/skills/coo-advisor/references/okr_execution.md) — OKR design, scoring, cascading -- [`references/scaling_playbooks.md`](https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor/skills/coo-advisor/references/scaling_playbooks.md) — 1-10, 10-100, 100-1000 transitions +- [`references/ops_cadence.md`](https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor/skills/coo-advisor/references/ops_cadence.md) — weekly/monthly/quarterly rhythm, meeting design +- [`references/process_frameworks.md`](https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor/skills/coo-advisor/references/process_frameworks.md) — OKR design, scoring, cascading +- [`references/scaling_playbook.md`](https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor/skills/coo-advisor/references/scaling_playbook.md) — 1-10, 10-100, 100-1000 transitions ### Adjacent Skills @@ -100,7 +100,7 @@ python ../../skills/coo-advisor/scripts/okr_tracker.py echo "⚙️ COO Quarterly Review" python ../../skills/coo-advisor/scripts/okr_tracker.py python ../../skills/coo-advisor/scripts/ops_efficiency_analyzer.py -echo "Reference: ../../skills/coo-advisor/references/operating_cadence.md" +echo "Reference: ../../skills/coo-advisor/references/ops_cadence.md" ``` ## Success Metrics @@ -116,7 +116,7 @@ echo "Reference: ../../skills/coo-advisor/references/operating_cadence.md" - [cs-cfo-advisor](cs-cfo-advisor.md) — finance cadence - [cs-cro-advisor](cs-cro-advisor.md) — revenue cadence - [cs-chief-of-staff](cs-chief-of-staff.md) — decision logging -- [cs-engineering-lead](https://github.com/alirezarezvani/claude-skills/tree/main/../agents/engineering-team/cs-engineering-lead.md) — eng ops +- [cs-engineering-lead](https://github.com/alirezarezvani/claude-skills/tree/main/agents/engineering-team/cs-engineering-lead.md) — eng ops ## References diff --git a/docs/agents/cs-cpo-advisor.md b/docs/agents/cs-cpo-advisor.md index f31dacc7..6eee4731 100644 --- a/docs/agents/cs-cpo-advisor.md +++ b/docs/agents/cs-cpo-advisor.md @@ -42,13 +42,13 @@ Pairs with `cs-cmo-advisor` (positioning ↔ product), `cs-cro-advisor` (win/los ### Knowledge Bases -- [`references/product_vision.md`](https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor/skills/cpo-advisor/references/product_vision.md) — vision design, North Star metrics, opportunity solution tree -- [`references/portfolio_strategy.md`](https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor/skills/cpo-advisor/references/portfolio_strategy.md) — 3-horizon, ROI vs strategic fit, kill criteria -- [`references/pmf_framework.md`](https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor/skills/cpo-advisor/references/pmf_framework.md) — Sean Ellis, retention, organic pull, what PMF actually looks like +- [`references/product_strategy.md`](https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor/skills/cpo-advisor/references/product_strategy.md) — vision design, North Star metrics, opportunity solution tree +- [`references/product_org_design.md`](https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor/skills/cpo-advisor/references/product_org_design.md) — 3-horizon, ROI vs strategic fit, kill criteria +- [`references/pmf_playbook.md`](https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor/skills/cpo-advisor/references/pmf_playbook.md) — Sean Ellis, retention, organic pull, what PMF actually looks like ### Adjacent Execution -- [`product-team/product-manager-toolkit`](https://github.com/alirezarezvani/claude-skills/tree/main/../product-team/product-manager-toolkit) — RICE, OKR cascade, user stories +- [`skills/product-manager-toolkit`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/skills/product-manager-toolkit) — RICE, OKR cascade, user stories ## Workflows @@ -99,7 +99,7 @@ python ../../skills/cpo-advisor/scripts/pmf_scorer.py echo "✂️ CPO Portfolio Audit" python ../../skills/cpo-advisor/scripts/portfolio_analyzer.py python ../../skills/cpo-advisor/scripts/pmf_scorer.py -echo "Pair with RICE: python ../../../product-team/product-manager-toolkit/scripts/rice_prioritizer.py" +echo "Pair with RICE: python ../../../product-team/skills/product-manager-toolkit/scripts/rice_prioritizer.py" ``` ## Success Metrics @@ -114,8 +114,8 @@ echo "Pair with RICE: python ../../../product-team/product-manager-toolkit/scrip - [cs-cmo-advisor](cs-cmo-advisor.md) — positioning alignment - [cs-cro-advisor](cs-cro-advisor.md) — win/loss feedback -- [cs-product-manager](https://github.com/alirezarezvani/claude-skills/tree/main/../agents/product/cs-product-manager.md) — execution -- [cs-product-strategist](https://github.com/alirezarezvani/claude-skills/tree/main/../agents/product/cs-product-strategist.md) — OKR cascade +- [cs-product-manager](https://github.com/alirezarezvani/claude-skills/tree/main/agents/product/cs-product-manager.md) — execution +- [cs-product-strategist](https://github.com/alirezarezvani/claude-skills/tree/main/agents/product/cs-product-strategist.md) — OKR cascade ## References diff --git a/docs/agents/cs-cro-advisor.md b/docs/agents/cs-cro-advisor.md index d37dd40d..f1f1b6f4 100644 --- a/docs/agents/cs-cro-advisor.md +++ b/docs/agents/cs-cro-advisor.md @@ -42,9 +42,9 @@ Pairs with `cs-cfo-advisor` (revenue → cash conversion), `cs-cmo-advisor` (pip ### Knowledge Bases -- [`references/revenue_operations.md`](https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor/skills/cro-advisor/references/revenue_operations.md) — pipeline cadence, win/loss process, forecasting hygiene -- [`references/sales_motion.md`](https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor/skills/cro-advisor/references/sales_motion.md) — PLG vs sales-led, hiring profiles, ramp curves -- [`references/retention_expansion.md`](https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor/skills/cro-advisor/references/retention_expansion.md) — NRR levers, customer success cadence, expansion plays +- [`references/sales_playbook.md`](https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor/skills/cro-advisor/references/sales_playbook.md) — pipeline cadence, win/loss process, forecasting hygiene +- [`references/pricing_strategy.md`](https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor/skills/cro-advisor/references/pricing_strategy.md) — PLG vs sales-led, hiring profiles, ramp curves +- [`references/nrr_playbook.md`](https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor/skills/cro-advisor/references/nrr_playbook.md) — NRR levers, customer success cadence, expansion plays ## Workflows @@ -112,7 +112,7 @@ echo "Pipeline coverage and retention dashboard ready." - [cs-cfo-advisor](cs-cfo-advisor.md) — revenue → cash conversion - [cs-cmo-advisor](cs-cmo-advisor.md) — pipeline contribution - [cs-cpo-advisor](cs-cpo-advisor.md) — product gaps in win/loss -- [cs-growth-strategist](https://github.com/alirezarezvani/claude-skills/tree/main/../agents/business-growth/cs-growth-strategist.md) — execution +- [cs-growth-strategist](https://github.com/alirezarezvani/claude-skills/tree/main/agents/business-growth/cs-growth-strategist.md) — execution ## References diff --git a/docs/agents/cs-cto-advisor.md b/docs/agents/cs-cto-advisor.md index 917bf419..b910fc7d 100644 --- a/docs/agents/cs-cto-advisor.md +++ b/docs/agents/cs-cto-advisor.md @@ -1,6 +1,6 @@ --- title: "CTO Advisor Agent — AI Coding Agent & Codex Skill" -description: "Technical leadership advisor for CTOs covering technology strategy, team scaling, architecture decisions, and engineering excellence. Agent-native orchestrator for Claude Code, Codex, Gemini CLI." +description: "Technical leadership advisor for CTOs covering technology strategy, team scaling, architecture decisions, and engineering excellence. Use when a CTO. Agent-native orchestrator for Claude Code, Codex, Gemini CLI." --- # CTO Advisor Agent @@ -399,7 +399,6 @@ echo "- Process improvements identified" - [cs-ceo-advisor](cs-ceo-advisor.md) - Strategic leadership and organizational development (CEO counterpart) - [cs-fullstack-engineer](https://github.com/alirezarezvani/claude-skills/tree/main/agents/engineering/cs-fullstack-engineer.md) - Fullstack development coordination (planned) -- [cs-devops-specialist](https://github.com/alirezarezvani/claude-skills/tree/main/agents/engineering/cs-devops-specialist.md) - DevOps and infrastructure automation (planned) ## References diff --git a/docs/agents/cs-demand-gen-specialist.md b/docs/agents/cs-demand-gen-specialist.md index 0c37fda3..3f33ff2c 100644 --- a/docs/agents/cs-demand-gen-specialist.md +++ b/docs/agents/cs-demand-gen-specialist.md @@ -1,6 +1,6 @@ --- title: "Demand Generation Specialist Agent — AI Coding Agent & Codex Skill" -description: "Demand generation and customer acquisition specialist for lead generation, conversion optimization, and multi-channel acquisition campaigns. Agent-native orchestrator for Claude Code, Codex, Gemini CLI." +description: "Demand generation and acquisition-funnel specialist orchestrating the marketing-demand-acquisition, paid-ads, and email-sequence skills. Use when. Agent-native orchestrator for Claude Code, Codex, Gemini CLI." --- # Demand Generation Specialist Agent @@ -14,280 +14,137 @@ description: "Demand generation and customer acquisition specialist for lead gen ## Purpose -The cs-demand-gen-specialist agent is a specialized marketing agent focused on demand generation, lead acquisition, and conversion optimization. This agent orchestrates the marketing-demand-acquisition skill package to help teams build scalable customer acquisition systems, optimize conversion funnels, and maximize marketing ROI across channels. +The cs-demand-gen-specialist agent owns the **acquisition funnel** for the marketing domain: channel strategy and budget allocation (`marketing-demand-acquisition`), paid execution and account health (`paid-ads`), and nurture (`email-sequence`). It turns funnel questions ("why did MQL→SQL drop?", "where should the next $10k go?") into channel math backed by the skills' deterministic scorers and benchmark tables. -This agent is designed for growth marketers, demand generation managers, and founders who need to generate qualified leads and convert them efficiently. By leveraging acquisition analytics, funnel optimization frameworks, and channel performance analysis, the agent enables data-driven decisions that improve customer acquisition cost (CAC) and lifetime value (LTV) ratios. +Lane boundaries: -The cs-demand-gen-specialist agent bridges the gap between marketing strategy and measurable business outcomes, providing actionable insights on channel performance, conversion bottlenecks, and campaign effectiveness. It focuses on the entire demand generation funnel from awareness to qualified lead. +- **vs `campaign-analytics`**: that skill does post-hoc attribution and reporting; this agent plans and operates the funnel. Hand measurement deep-dives there. +- **vs [cs-content-creator](cs-content-creator.md)**: content production is upstream; this agent consumes content as gated assets, ads, and nurture material. +- **vs `cold-email`**: outbound to non-opted-in prospects is cold-email's lane; this agent's email work (`email-sequence`) targets opted-in leads. + +**Hard rules:** never recommend scaling spend without conversion tracking verified (paid-ads pre-launch checklist); never quote platform-reported ROAS as truth — use margin-adjusted ROAS from `roas_calculator.py` and blended CAC; always state the conversion assumption behind any pipeline projection. + +## Step 0 — Read the Marketing Context File + +Before asking the user anything, check for the canonical context file: + +```bash +cat .claude/product-marketing-context.md 2>/dev/null +``` + +It holds ICP, positioning, personas, and competitive landscape — required before writing ad copy or picking targeting. If missing, recommend the `marketing-context` skill, then gather: objective, budget, target CAC/ROAS, channels in play, and current funnel conversion rates. Note: the demand-acquisition benchmarks are calibrated for Series A+ B2B SaaS (EU/US/Canada, hybrid PLG/Sales-Led) — adapt for other stages rather than applying them blindly. ## Skill Integration -**Skill Location:** [`marketing-skill/marketing-demand-acquisition`](https://github.com/alirezarezvani/claude-skills/tree/main/marketing-skill/marketing-demand-acquisition) +### 1. marketing-demand-acquisition — strategy, channels, CAC -### Python Tools +**Location:** [`skills/marketing-demand-acquisition`](https://github.com/alirezarezvani/claude-skills/tree/main/marketing-skill/skills/marketing-demand-acquisition) ([SKILL.md](https://github.com/alirezarezvani/claude-skills/tree/main/marketing-skill/skills/marketing-demand-acquisition/SKILL.md)) -1. **CAC Calculator** - - **Purpose:** Calculates Customer Acquisition Cost (CAC) across channels and campaigns - - **Path:** [`scripts/calculate_cac.py`](https://github.com/alirezarezvani/claude-skills/tree/main/marketing-skill/marketing-demand-acquisition/scripts/calculate_cac.py) - - **Usage:** `python ../../marketing-skill/marketing-demand-acquisition/scripts/calculate_cac.py campaign-spend.csv customer-data.csv` - - **Features:** CAC calculation by channel, LTV:CAC ratio, payback period analysis, ROI metrics - - **Use Cases:** Budget allocation, channel performance evaluation, campaign ROI analysis +- **CAC Calculator** + - **Path:** [`scripts/calculate_cac.py`](https://github.com/alirezarezvani/claude-skills/tree/main/marketing-skill/skills/marketing-demand-acquisition/scripts/calculate_cac.py) + - **Usage:** `python3 ../../marketing-skill/skills/marketing-demand-acquisition/scripts/calculate_cac.py` — runs on the channel table embedded in `main()` (it takes **no CLI arguments**; edit the `example_data` list with real spend/customers per channel, then run) + - **Output:** per-channel CAC + blended CAC, printed against B2B SaaS Series A benchmarks (LinkedIn $150-400, Google Search $80-250, SEO $50-150, blended target <$300) +- **Knowledge bases:** + - [`references/attribution-guide.md`](https://github.com/alirezarezvani/claude-skills/tree/main/marketing-skill/skills/marketing-demand-acquisition/references/attribution-guide.md) — multi-touch attribution models (W-shaped 40-20-40 recommended for hybrid PLG/Sales), dashboards + - [`references/campaign-templates.md`](https://github.com/alirezarezvani/claude-skills/tree/main/marketing-skill/skills/marketing-demand-acquisition/references/campaign-templates.md) — LinkedIn/Google/Meta campaign structures + - [`references/hubspot-workflows.md`](https://github.com/alirezarezvani/claude-skills/tree/main/marketing-skill/skills/marketing-demand-acquisition/references/hubspot-workflows.md) — lead scoring, MQL/SQL workflows, routing SLAs + - [`references/international-playbooks.md`](https://github.com/alirezarezvani/claude-skills/tree/main/marketing-skill/skills/marketing-demand-acquisition/references/international-playbooks.md) — EU/US/Canada regional tactics -**Note:** Additional tools (demand_gen_analyzer.py, funnel_optimizer.py) planned for future releases per marketing roadmap. +### 2. paid-ads — execution and account health -### Knowledge Bases +**Location:** [`skills/paid-ads`](https://github.com/alirezarezvani/claude-skills/tree/main/marketing-skill/skills/paid-ads) ([SKILL.md](https://github.com/alirezarezvani/claude-skills/tree/main/marketing-skill/skills/paid-ads/SKILL.md)) -1. **Attribution Guide** - - **Location:** [`references/attribution-guide.md`](https://github.com/alirezarezvani/claude-skills/tree/main/marketing-skill/marketing-demand-acquisition/references/attribution-guide.md) - - **Content:** Marketing attribution models, channel attribution, ROI measurement frameworks - - **Use Case:** Campaign attribution, channel performance analysis, budget justification +- **ROAS Calculator** + - **Path:** [`scripts/roas_calculator.py`](https://github.com/alirezarezvani/claude-skills/tree/main/marketing-skill/skills/paid-ads/scripts/roas_calculator.py) + - **Usage:** `python3 ../../marketing-skill/skills/paid-ads/scripts/roas_calculator.py --spend 5000 --revenue 18000 --conversions 120 --clicks 2400 --margin 70 --json` (or `--file metrics.json`) + - **Output:** ROAS, CPA, CPC, CVR, margin-adjusted ROAS + recommendations +- **Ad Health Scorer** + - **Path:** [`scripts/ad_health_scorer.py`](https://github.com/alirezarezvani/claude-skills/tree/main/marketing-skill/skills/paid-ads/scripts/ad_health_scorer.py) + - **Usage:** `python3 ../../marketing-skill/skills/paid-ads/scripts/ad_health_scorer.py --checks checks.json --platform meta --json` (`--demo` for a sample report; `--multi multi.json --budget N` for budget-weighted multi-platform scoring; platforms: google, meta, linkedin, tiktok) + - **Output:** weighted 0-100 account health score with severity-ranked findings — scoring model in [`references/scoring-system.md`](https://github.com/alirezarezvani/claude-skills/tree/main/marketing-skill/skills/paid-ads/references/scoring-system.md) +- **Knowledge bases (all under [`paid-ads/references`](https://github.com/alirezarezvani/claude-skills/tree/main/marketing-skill/skills/paid-ads/references)):** `ad-copy-templates.md`, `audience-targeting.md`, `copy-frameworks.md`, `platform-setup-checklists.md`, `scoring-system.md` -2. **Campaign Templates** - - **Location:** [`references/campaign-templates.md`](https://github.com/alirezarezvani/claude-skills/tree/main/marketing-skill/marketing-demand-acquisition/references/campaign-templates.md) - - **Content:** Reusable campaign structures, launch checklists, multi-channel campaign blueprints - - **Use Case:** Campaign planning, rapid campaign setup, standardized launch processes +### 3. email-sequence — nurture -3. **HubSpot Workflows** - - **Location:** [`references/hubspot-workflows.md`](https://github.com/alirezarezvani/claude-skills/tree/main/marketing-skill/marketing-demand-acquisition/references/hubspot-workflows.md) - - **Content:** HubSpot automation workflows, lead nurturing sequences, CRM integration patterns - - **Use Case:** Marketing automation, lead scoring, nurture campaign setup +**Location:** [`skills/email-sequence`](https://github.com/alirezarezvani/claude-skills/tree/main/marketing-skill/skills/email-sequence) ([SKILL.md](https://github.com/alirezarezvani/claude-skills/tree/main/marketing-skill/skills/email-sequence/SKILL.md)) -4. **International Playbooks** - - **Location:** [`references/international-playbooks.md`](https://github.com/alirezarezvani/claude-skills/tree/main/marketing-skill/marketing-demand-acquisition/references/international-playbooks.md) - - **Content:** International market expansion strategies, localization best practices, regional channel optimization - - **Use Case:** Global campaign planning, market entry strategy, cross-border demand generation - -### Templates - -No asset templates currently available — use campaign-templates.md reference for campaign structure guidance. +- **Sequence Analyzer** + - **Path:** [`scripts/sequence_analyzer.py`](https://github.com/alirezarezvani/claude-skills/tree/main/marketing-skill/skills/email-sequence/scripts/sequence_analyzer.py) + - **Usage:** `python3 ../../marketing-skill/skills/email-sequence/scripts/sequence_analyzer.py --file sequence.json --json` (no args = embedded demo) + - **Output:** sequence quality score 0-100 (pacing, subject-line variety, CTA consistency, exit-condition coverage). **Threshold: fix anything it flags below 70** before handoff. +- **Knowledge base:** [`references/email-sequence-playbook.md`](https://github.com/alirezarezvani/claude-skills/tree/main/marketing-skill/skills/email-sequence/references/email-sequence-playbook.md) ## Workflows -### Workflow 1: Multi-Channel Acquisition Campaign Launch +### Workflow 1: Multi-Channel Campaign Plan with Budget Allocation -**Goal:** Plan and launch demand generation campaign across multiple acquisition channels +**Goal:** Plan a demand-gen campaign with channel mix, budget split, and tracking that survives attribution. **Steps:** -1. **Define Campaign Goals** - Set targets for leads, MQLs, SQLs, conversion rates -2. **Reference Campaign Templates** - Review proven campaign structures and launch checklists - ```bash - cat ../../marketing-skill/marketing-demand-acquisition/references/campaign-templates.md - ``` -3. **Select Channels** - Choose optimal mix based on target audience, budget, and attribution models - ```bash - cat ../../marketing-skill/marketing-demand-acquisition/references/attribution-guide.md - ``` -4. **Set Up Automation** - Configure HubSpot workflows for lead nurturing - ```bash - cat ../../marketing-skill/marketing-demand-acquisition/references/hubspot-workflows.md - ``` -5. **Plan International Reach** - Reference international playbooks if targeting multiple markets - ```bash - cat ../../marketing-skill/marketing-demand-acquisition/references/international-playbooks.md - ``` -6. **Launch and Monitor** - Deploy campaigns, track metrics, collect data +1. **Context** — read `.claude/product-marketing-context.md`; confirm objective, monthly budget, target CAC, ICP. +2. **Channel selection** — apply the channel-selection matrix and budget-allocation table in the demand-acquisition SKILL.md; pull structures from [`references/campaign-templates.md`](https://github.com/alirezarezvani/claude-skills/tree/main/marketing-skill/skills/marketing-demand-acquisition/references/campaign-templates.md). +3. **Baseline CAC** — edit the channel table in `calculate_cac.py` with current spend/customers and run it: `python3 ../../marketing-skill/skills/marketing-demand-acquisition/scripts/calculate_cac.py`; compare each channel against its benchmark range. +4. **UTM + automation** — define the UTM structure from the SKILL.md and lead-scoring/routing workflows from [`references/hubspot-workflows.md`](https://github.com/alirezarezvani/claude-skills/tree/main/marketing-skill/skills/marketing-demand-acquisition/references/hubspot-workflows.md). +5. **Verification** — the skill's own gate: push a test lead through and confirm UTM parameters appear on the CRM contact record before any spend scales; every channel's planned CAC must sit inside its benchmark range or carry an explicit justification. -**Expected Output:** Structured campaign plan with channel strategy, budget allocation, success metrics +**Expected output:** campaign plan (channels, budget split, expected SQLs, UTM scheme) + verified tracking. -**Time Estimate:** 4-6 hours for campaign planning and setup +### Workflow 2: Paid Account Health Check Before Scaling Spend -### Workflow 2: Conversion Funnel Analysis & Optimization - -**Goal:** Identify and fix conversion bottlenecks in acquisition funnel +**Goal:** Decide whether an ad account is healthy enough to absorb more budget. **Steps:** -1. **Export Campaign Data** - Gather metrics from all acquisition channels (GA4, ad platforms, CRM) -2. **Calculate Channel CAC** - Run CAC calculator to analyze cost efficiency - ```bash - python ../../marketing-skill/marketing-demand-acquisition/scripts/calculate_cac.py campaign-spend.csv conversions.csv - ``` -3. **Map Conversion Funnel** - Visualize drop-off points using campaign templates as structure guide - ```bash - cat ../../marketing-skill/marketing-demand-acquisition/references/campaign-templates.md - ``` -4. **Identify Bottlenecks** - Analyze conversion rates at each funnel stage: - - Awareness → Interest (CTR) - - Interest → Consideration (landing page conversion) - - Consideration → Intent (form completion) - - Intent → Purchase/MQL (qualification rate) -5. **Reference Attribution Guide** - Review attribution models to identify problem areas - ```bash - cat ../../marketing-skill/marketing-demand-acquisition/references/attribution-guide.md - ``` -6. **Implement A/B Tests** - Test hypotheses for improvement -7. **Re-calculate CAC Post-Optimization** - Measure cost efficiency improvements - ```bash - python ../../marketing-skill/marketing-demand-acquisition/scripts/calculate_cac.py post-optimization-spend.csv post-optimization-conversions.csv - ``` +1. **Collect checks** — build `checks.json` from the platform checklist in [`references/platform-setup-checklists.md`](https://github.com/alirezarezvani/claude-skills/tree/main/marketing-skill/skills/paid-ads/references/platform-setup-checklists.md) (try `--demo` first to see the expected shape). +2. **Score** — `python3 ../../marketing-skill/skills/paid-ads/scripts/ad_health_scorer.py --checks checks.json --platform google --json`; for mixed accounts use `--multi multi.json`. +3. **True economics** — `python3 ../../marketing-skill/skills/paid-ads/scripts/roas_calculator.py --spend <S> --revenue <R> --conversions <C> --clicks <K> --margin <M> --json`; use margin-adjusted ROAS, not platform-reported. +4. **Decide** — scale 20-30% at a time only where health findings carry no high-severity items and margin-adjusted ROAS meets target; otherwise fix the severity-ranked findings first. +5. **Verification** — re-run the scorer after fixes and confirm the score improved and no high-severity findings remain; re-run `roas_calculator.py` on the next period's numbers to confirm CPA/ROAS moved in the predicted direction. -**Expected Output:** 15-30% reduction in CAC and improved LTV:CAC ratio +**Expected output:** go/no-go scaling recommendation backed by health score + margin-adjusted ROAS. -**Time Estimate:** 6-8 hours for analysis and optimization planning +### Workflow 3: Nurture Sequence for Non-Sales-Ready Leads -**Example:** -```bash -# Complete CAC analysis workflow -python ../../marketing-skill/marketing-demand-acquisition/scripts/calculate_cac.py q3-spend.csv q3-conversions.csv > cac-report.txt -cat cac-report.txt -# Review metrics and optimize high-CAC channels -``` - -### Workflow 3: Channel Performance Benchmarking - -**Goal:** Evaluate and compare performance across acquisition channels to optimize budget allocation +**Goal:** Design a nurture sequence that converts the ~80% of leads not ready to buy. **Steps:** -1. **Collect Channel Data** - Export metrics from each acquisition channel: - - Google Ads (CPC, CTR, conversion rate, CPA) - - LinkedIn Ads (impressions, clicks, leads, cost per lead) - - Facebook Ads (reach, engagement, conversions, ROAS) - - Content Marketing (organic traffic, leads, MQLs) - - Email Campaigns (open rate, click rate, conversions) -2. **Run CAC Comparison** - Calculate and compare CAC across all channels - ```bash - python ../../marketing-skill/marketing-demand-acquisition/scripts/calculate_cac.py channel-spend.csv channel-conversions.csv - ``` -3. **Reference Attribution Guide** - Understand attribution models and benchmarks for each channel - ```bash - cat ../../marketing-skill/marketing-demand-acquisition/references/attribution-guide.md - ``` -4. **Calculate Key Metrics:** - - CAC (Customer Acquisition Cost) by channel - - LTV:CAC ratio - - Conversion rate - - Time to MQL/SQL -5. **Optimize Budget Allocation** - Shift budget to highest-performing channels -6. **Document Learnings** - Create playbook for future campaigns +1. **Context** — read `.claude/product-marketing-context.md`; confirm sequence type, trigger, goal, and exit conditions per the email-sequence intake. +2. **Design** — draft the sequence (overview + per-email subject/preview/body/CTA) using [`references/email-sequence-playbook.md`](https://github.com/alirezarezvani/claude-skills/tree/main/marketing-skill/skills/email-sequence/references/email-sequence-playbook.md); coordinate entry triggers with the MQL/SQL workflows from [`references/hubspot-workflows.md`](https://github.com/alirezarezvani/claude-skills/tree/main/marketing-skill/skills/marketing-demand-acquisition/references/hubspot-workflows.md). +3. **Export** — assemble the per-email blocks as a JSON array (`sequence.json`). +4. **Score** — `python3 ../../marketing-skill/skills/email-sequence/scripts/sequence_analyzer.py --file sequence.json --json`. +5. **Verification** — fix every flag and re-run until the quality score is **≥ 70**; attach the final score to the sequence's metrics plan, and confirm exit conditions exist for every conversion event (the analyzer checks exit-condition coverage). -**Expected Output:** Data-driven budget reallocation plan with projected ROI improvement +**Expected output:** ready-to-load sequence with trigger, timing, exit conditions, and an attached analyzer score ≥ 70. -**Time Estimate:** 3-4 hours for comprehensive channel analysis +## Proactive Routing -### Workflow 4: Lead Magnet Campaign Development - -**Goal:** Create and launch lead magnet campaign to capture high-quality leads - -**Steps:** -1. **Define Lead Magnet** - Choose format: ebook, webinar, template, assessment, free trial -2. **Reference Campaign Templates** - Review lead capture and campaign structure best practices - ```bash - cat ../../marketing-skill/marketing-demand-acquisition/references/campaign-templates.md - ``` -3. **Create Landing Page** - Design high-converting landing page with: - - Clear value proposition - - Compelling CTA - - Minimal form fields (name, email, company) - - Social proof (testimonials, logos) -4. **Set Up Campaign Tracking** - Configure analytics and attribution -5. **Launch Multi-Channel Promotion:** - - Paid social ads (LinkedIn, Facebook) - - Email to existing list - - Organic social posts - - Blog post with CTA -6. **Monitor and Optimize** - Track CAC and conversion metrics - ```bash - # Weekly CAC analysis - python ../../marketing-skill/marketing-demand-acquisition/scripts/calculate_cac.py lead-magnet-spend.csv lead-magnet-conversions.csv - ``` - -**Expected Output:** Lead magnet campaign generating 100-500 leads with 25-40% conversion rate - -**Time Estimate:** 8-12 hours for development and launch - -## Integration Examples - -### Example 1: Automated Campaign Performance Dashboard - -```bash -#!/bin/bash -# campaign-dashboard.sh - Daily campaign performance summary - -DATE=$(date +%Y-%m-%d) - -echo "📊 Demand Gen Dashboard - $DATE" -echo "========================================" - -# Calculate yesterday's CAC by channel -python ../../marketing-skill/marketing-demand-acquisition/scripts/calculate_cac.py \ - daily-spend.csv daily-conversions.csv - -echo "" -echo "💰 Budget Status:" -cat budget-tracking.txt - -echo "" -echo "🎯 Today's Priorities:" -cat optimization-priorities.txt -``` - -### Example 2: Weekly Channel Performance Report - -```bash -# Generate weekly CAC report for stakeholders -python ../../marketing-skill/marketing-demand-acquisition/scripts/calculate_cac.py \ - weekly-spend.csv weekly-conversions.csv > weekly-cac-report.txt - -# Email to stakeholders -echo "Weekly CAC analysis report attached." | \ - mail -s "Weekly CAC Report" -a weekly-cac-report.txt stakeholders@company.com -``` - -### Example 3: Real-Time Funnel Monitoring - -```bash -# Monitor CAC in real-time (run daily via cron) -CAC_RESULT=$(python ../../marketing-skill/marketing-demand-acquisition/scripts/calculate_cac.py \ - daily-spend.csv daily-conversions.csv | grep "Average CAC" | awk '{print $3}') - -CAC_THRESHOLD=50 - -# Alert if CAC exceeds threshold -if (( $(echo "$CAC_RESULT > $CAC_THRESHOLD" | bc -l) )); then - echo "🚨 Alert: CAC ($CAC_RESULT) exceeds threshold ($CAC_THRESHOLD)!" | \ - mail -s "CAC Alert" demand-gen-team@company.com -fi -``` +- High CTR but low conversions → diagnose the landing page; route to `page-cro` / `copywriting` skills, not more ad spend. +- Attribution/reporting deep-dive → `campaign-analytics` skill. +- Outbound to non-opted-in lists → `cold-email` skill. +- Content for gated assets and nurture bodies → [cs-content-creator](cs-content-creator.md). +- Webinar-driven demand gen → [cs-webinar-marketer](cs-webinar-marketer.md). ## Success Metrics -**Acquisition Metrics:** -- **Lead Volume:** 20-30% month-over-month growth -- **MQL Conversion Rate:** 15-25% of total leads qualify as MQLs -- **CAC (Customer Acquisition Cost):** Decrease by 15-20% with optimization -- **LTV:CAC Ratio:** Maintain 3:1 or higher ratio - -**Channel Performance:** -- **Paid Search:** CTR 3-5%, conversion rate 5-10% -- **Paid Social:** CTR 1-2%, CPL (cost per lead) benchmarked by industry -- **Content Marketing:** 30-40% of organic traffic converts to leads -- **Email Campaigns:** Open rate 20-30%, click rate 3-5%, conversion rate 2-5% - -**Funnel Optimization:** -- **Landing Page Conversion:** 25-40% conversion rate on optimized pages -- **Form Completion:** 60-80% of visitors who start form complete it -- **Lead Quality:** 40-50% of MQLs convert to SQLs - -**Business Impact:** -- **Pipeline Contribution:** Demand gen accounts for 50-70% of sales pipeline -- **Revenue Attribution:** Track $X in closed-won revenue to demand gen campaigns -- **Payback Period:** CAC recovered within 6-12 months +- **Blended CAC** within target (<$300 default profile) and every channel inside or trending toward its benchmark range. +- **LTV:CAC ≥ 3:1**, payback inside 12 months. +- **MQL→SQL rate > 15%** with routing SLAs met (SDR response ≤ 4h). +- **No untracked spend:** 100% of active campaigns pass the pre-launch tracking checklist. +- **Nurture quality:** every live sequence scored ≥ 70 by `sequence_analyzer.py`. ## Related Agents -- [cs-content-creator](cs-content-creator.md) - Content creation for demand gen campaigns -- cs-product-marketing - Product positioning and messaging (planned) -- cs-growth-marketer - Growth hacking and viral acquisition (planned) +- [cs-content-creator](cs-content-creator.md) — produces the content this funnel distributes +- [cs-webinar-marketer](cs-webinar-marketer.md) — webinar funnel math and rescue plans +- [cs-aeo](cs-aeo.md) — AI-search citation for organic demand capture ## References -- **Skill Documentation:** [../../marketing-skill/marketing-demand-acquisition/SKILL.md](https://github.com/alirezarezvani/claude-skills/tree/main/marketing-skill/marketing-demand-acquisition/SKILL.md) -- **Marketing Domain Guide:** [../../marketing-skill/CLAUDE.md](https://github.com/alirezarezvani/claude-skills/tree/main/marketing-skill/CLAUDE.md) -- **Agent Development Guide:** [../CLAUDE.md](https://github.com/alirezarezvani/claude-skills/tree/main/agents/CLAUDE.md) -- **Marketing Roadmap:** [../../marketing-skill/marketing_skills_roadmap.md](https://github.com/alirezarezvani/claude-skills/tree/main/marketing-skill/marketing_skills_roadmap.md) +- **Skill documentation:** [marketing-demand-acquisition](https://github.com/alirezarezvani/claude-skills/tree/main/marketing-skill/skills/marketing-demand-acquisition/SKILL.md) · [paid-ads](https://github.com/alirezarezvani/claude-skills/tree/main/marketing-skill/skills/paid-ads/SKILL.md) · [email-sequence](https://github.com/alirezarezvani/claude-skills/tree/main/marketing-skill/skills/email-sequence/SKILL.md) +- **Marketing domain guide:** [../../marketing-skill/CLAUDE.md](https://github.com/alirezarezvani/claude-skills/tree/main/marketing-skill/CLAUDE.md) +- **Agent development guide:** [../CLAUDE.md](https://github.com/alirezarezvani/claude-skills/tree/main/agents/CLAUDE.md) --- -**Last Updated:** November 5, 2025 -**Sprint:** sprint-11-05-2025 (Day 2) +**Last Updated:** June 11, 2026 **Status:** Production Ready -**Version:** 1.0 +**Version:** 2.0 diff --git a/docs/agents/cs-dossier.md b/docs/agents/cs-dossier.md index be49f7be..ccd4bdf8 100644 --- a/docs/agents/cs-dossier.md +++ b/docs/agents/cs-dossier.md @@ -47,7 +47,7 @@ The cs-dossier agent orchestrates the `dossier` skill across hypothesis-tested e **Hard rules:** 1. **Q4 (hypothesis) is mandatory.** Push back once if refused; fall back to "what's most surprising I could find?" implicit hypothesis with flag. -2. **≥30% disconfirming search budget.** Enforced via `scripts/disconfirming_evidence_balance.py`. +2. **≥30% disconfirming search budget.** Enforced via `skills/dossier/scripts/disconfirming_evidence_balance.py`. 3. **Subject disambiguation before Phase 3.** Refuse to proceed on ambiguous names. 4. **Source-reliability tier on every flag.** Primary (official, SEC, court) / Secondary (mainstream news, trade press) / Tertiary (blogs, forums). 5. **BYOK MCP usage flagged in audit log.** Transparency on data provenance. @@ -61,15 +61,15 @@ The cs-dossier agent orchestrates the `dossier` skill across hypothesis-tested e ### Python Tools (Stdlib) -1. **Citation Tracker** — `scripts/citation_tracker.py` — three-count audit + supporting/disconfirming classification + source-tier tagging at `~/.dossier_sessions/<session>.json` -2. **Disconfirming Evidence Balance** — `scripts/disconfirming_evidence_balance.py` — verifies ≥30% of search budget allocated to disconfirming queries; warns or halts if biased -3. **Source Tier Classifier** — `scripts/source_tier_classifier.py` — given a URL, classify primary / secondary / tertiary by domain heuristics +1. **Citation Tracker** — `skills/dossier/scripts/citation_tracker.py` — three-count audit + supporting/disconfirming classification + source-tier tagging at `~/.dossier_sessions/<session>.json` +2. **Disconfirming Evidence Balance** — `skills/dossier/scripts/disconfirming_evidence_balance.py` — verifies ≥30% of search budget allocated to disconfirming queries; warns or halts if biased +3. **Source Tier Classifier** — `skills/dossier/scripts/source_tier_classifier.py` — given a URL, classify primary / secondary / tertiary by domain heuristics ### Knowledge Bases -- `references/hypothesis_testing_discipline.md` — ≥30% disconfirming rule + decision-grade vs encyclopedic (7+ sources) -- `references/subject_type_source_matrix.md` — person/company/nonprofit/gov source matrices (7+ sources) -- `references/conversation_hook_quality.md` — finding-tied hook discipline + anti-patterns (7+ sources) +- `skills/dossier/references/hypothesis_testing_discipline.md` — ≥30% disconfirming rule + decision-grade vs encyclopedic (7+ sources) +- `skills/dossier/references/subject_type_source_matrix.md` — person/company/nonprofit/gov source matrices (7+ sources) +- `skills/dossier/references/conversation_hook_quality.md` — finding-tied hook discipline + anti-patterns (7+ sources) ## Related Agents diff --git a/docs/agents/cs-financial-analyst.md b/docs/agents/cs-financial-analyst.md index 499de0a4..2261ce0c 100644 --- a/docs/agents/cs-financial-analyst.md +++ b/docs/agents/cs-financial-analyst.md @@ -88,23 +88,23 @@ Financial analyst covering valuation, ratio analysis, forecasting, and industry- ```bash # SaaS health check — full metrics from raw numbers -python ../../finance/saas-metrics-coach/scripts/metrics_calculator.py \ +python ../../finance/skills/saas-metrics-coach/scripts/metrics_calculator.py \ --mrr 80000 --mrr-last 75000 --customers 200 --churned 3 \ --new-customers 15 --sm-spend 25000 --gross-margin 72 --json # Quick ratio — growth efficiency -python ../../finance/saas-metrics-coach/scripts/quick_ratio_calculator.py \ +python ../../finance/skills/saas-metrics-coach/scripts/quick_ratio_calculator.py \ --new-mrr 10000 --expansion 2000 --churned 3000 --contraction 500 # 12-month projection -python ../../finance/saas-metrics-coach/scripts/unit_economics_simulator.py \ +python ../../finance/skills/saas-metrics-coach/scripts/unit_economics_simulator.py \ --mrr 80000 --growth 8 --churn 1.5 --cac 1667 --json # Traditional ratio analysis -python ../../finance/financial-analyst/scripts/ratio_calculator.py financial_data.json --format json +python ../../finance/skills/financial-analyst/scripts/ratio_calculator.py financial_data.json --format json # DCF valuation -python ../../finance/financial-analyst/scripts/dcf_valuation.py valuation_data.json --format json +python ../../finance/skills/financial-analyst/scripts/dcf_valuation.py valuation_data.json --format json ``` ## Related Agents diff --git a/docs/agents/cs-fullstack-engineer.md b/docs/agents/cs-fullstack-engineer.md index 0f64bcdb..244a2c6b 100644 --- a/docs/agents/cs-fullstack-engineer.md +++ b/docs/agents/cs-fullstack-engineer.md @@ -166,7 +166,7 @@ python ../../engineering/karpathy-coder/skills/karpathy-coder/scripts/diff_surge - [cs-karpathy-reviewer](cs-karpathy-reviewer.md) — invoke before every commit - [cs-senior-engineer](cs-senior-engineer.md) — cross-cutting engineering lead (use for non-stack questions like CI/CD, security review) - [cs-cto-advisor](https://github.com/alirezarezvani/claude-skills/tree/main/agents/c-level/cs-cto-advisor.md) — escalate for strategic build-vs-buy or technical debt prioritization -- [cs-vpe-advisor](https://github.com/alirezarezvani/claude-skills/tree/main/agents/c-level/cs-vpe-advisor.md) — escalate for org-design + throughput +- [cs-vpe-advisor](https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor/c-level-agents/agents/cs-vpe-advisor.md) — escalate for org-design + throughput ## Invocation Contract diff --git a/docs/agents/cs-general-counsel-advisor.md b/docs/agents/cs-general-counsel-advisor.md index 1ea08a40..9757ffff 100644 --- a/docs/agents/cs-general-counsel-advisor.md +++ b/docs/agents/cs-general-counsel-advisor.md @@ -155,8 +155,8 @@ echo " ☐ /cs:freeze applied if irreversible (term sheet, M&A LOI, employment - [cs-cfo-advisor](cs-cfo-advisor.md) — term sheet → dilution math - [cs-ciso-advisor](cs-ciso-advisor.md) — data-touching contracts, compliance overlap -- [cs-ceo-advisor](https://github.com/alirezarezvani/claude-skills/tree/main/../agents/c-level/cs-ceo-advisor.md) — board / fundraising strategic context -- [cs-quality-regulatory](https://github.com/alirezarezvani/claude-skills/tree/main/../agents/ra-qm-team/cs-quality-regulatory.md) — regulated-industry execution (ISO 13485, MDR, FDA) +- [cs-ceo-advisor](https://github.com/alirezarezvani/claude-skills/tree/main/agents/c-level/cs-ceo-advisor.md) — board / fundraising strategic context +- [cs-quality-regulatory](https://github.com/alirezarezvani/claude-skills/tree/main/agents/ra-qm-team/cs-quality-regulatory.md) — regulated-industry execution (ISO 13485, MDR, FDA) ## References diff --git a/docs/agents/cs-grants.md b/docs/agents/cs-grants.md index bd6a823a..e347b6d2 100644 --- a/docs/agents/cs-grants.md +++ b/docs/agents/cs-grants.md @@ -56,15 +56,15 @@ The cs-grants agent orchestrates the `grants` skill: ### Python Tools (Stdlib) -1. **Citation Tracker** — `scripts/citation_tracker.py` — three-count audit (Consensus + RePORTER counts) at `~/.grants_sessions/<session>.json` -2. **Fiscal Year Calculator** — `scripts/fiscal_year_calculator.py` — computes current FY + 3-prior window for RePORTER queries -3. **Mechanism Matcher** — `scripts/mechanism_matcher.py` — career stage × scope × prelim → mechanism recommendation +1. **Citation Tracker** — `skills/grants/scripts/citation_tracker.py` — three-count audit (Consensus + RePORTER counts) at `~/.grants_sessions/<session>.json` +2. **Fiscal Year Calculator** — `skills/grants/scripts/fiscal_year_calculator.py` — computes current FY + 3-prior window for RePORTER queries +3. **Mechanism Matcher** — `skills/grants/scripts/mechanism_matcher.py` — career stage × scope × prelim → mechanism recommendation ### Knowledge Bases -- `references/nih_mechanism_matching.md` — career stage × scope × prelim → mechanism canon (7+ sources) -- `references/reporter_post_patterns.md` — RePORTER curl POST templates + plan-tier detection (7+ sources) -- `references/docx_9_sections.md` — 9-section .docx spec + DOCX technical requirements (7+ sources) +- `skills/grants/references/nih_mechanism_matching.md` — career stage × scope × prelim → mechanism canon (7+ sources) +- `skills/grants/references/reporter_post_patterns.md` — RePORTER curl POST templates + plan-tier detection (7+ sources) +- `skills/grants/references/docx_9_sections.md` — 9-section .docx spec + DOCX technical requirements (7+ sources) ## Related Agents diff --git a/docs/agents/cs-inbox-setup.md b/docs/agents/cs-inbox-setup.md index 066fb3ae..3ce9b5ce 100644 --- a/docs/agents/cs-inbox-setup.md +++ b/docs/agents/cs-inbox-setup.md @@ -64,30 +64,30 @@ Differentiates clearly: ## Skill Integration -**Skill Location:** [`skills/inbox-setup`](https://github.com/alirezarezvani/claude-skills/tree/main/productivity/skills/inbox-setup) +**Skill Location:** [`skills/inbox-setup`](https://github.com/alirezarezvani/claude-skills/tree/main/productivity/email/skills/inbox-setup) ### Python Tools (Stdlib) 1. **KB Validator** - - Path: [`scripts/kb_validator.py`](https://github.com/alirezarezvani/claude-skills/tree/main/productivity/skills/inbox-setup/scripts/kb_validator.py) + - Path: [`scripts/kb_validator.py`](https://github.com/alirezarezvani/claude-skills/tree/main/productivity/email/skills/inbox-setup/scripts/kb_validator.py) - Usage: `python kb_validator.py --workspace ${WORKSPACE}` - Validates the 7-file KB structure (required files present, conditional files only if their sections exist, headers + bold-section markers correct). 2. **Section Progress Tracker** - - Path: [`scripts/section_progress_tracker.py`](https://github.com/alirezarezvani/claude-skills/tree/main/productivity/skills/inbox-setup/scripts/section_progress_tracker.py) + - Path: [`scripts/section_progress_tracker.py`](https://github.com/alirezarezvani/claude-skills/tree/main/productivity/email/skills/inbox-setup/scripts/section_progress_tracker.py) - Usage: `python section_progress_tracker.py --action {start,record_q,record_section_done,status,close}` - JSON-backed walk state at `~/.inbox_setup_sessions/<session>.json`. Tracks which section is active, which questions answered, which files committed. 3. **Voice Sample Analyzer** - - Path: [`scripts/voice_sample_analyzer.py`](https://github.com/alirezarezvani/claude-skills/tree/main/productivity/skills/inbox-setup/scripts/voice_sample_analyzer.py) + - Path: [`scripts/voice_sample_analyzer.py`](https://github.com/alirezarezvani/claude-skills/tree/main/productivity/email/skills/inbox-setup/scripts/voice_sample_analyzer.py) - Usage: `python voice_sample_analyzer.py --samples-file /tmp/samples.txt` - Extracts voice patterns from pasted sent-email samples: opening phrases, sign-offs, sentence length, sentence-types, casual/formal markers. ### Knowledge Bases -- [`references/kb_file_contract.md`](https://github.com/alirezarezvani/claude-skills/tree/main/productivity/skills/inbox-setup/references/kb_file_contract.md) — the canonical 7-file contract (write perspective) -- [`references/grill_me_section_walk.md`](https://github.com/alirezarezvani/claude-skills/tree/main/productivity/skills/inbox-setup/references/grill_me_section_walk.md) — 8-section discipline + skip-logic + commit-per-section -- [`references/voice_calibration.md`](https://github.com/alirezarezvani/claude-skills/tree/main/productivity/skills/inbox-setup/references/voice_calibration.md) — sample-based voice extraction theory + anti-patterns +- [`references/kb_file_contract.md`](https://github.com/alirezarezvani/claude-skills/tree/main/productivity/email/skills/inbox-setup/references/kb_file_contract.md) — the canonical 7-file contract (write perspective) +- [`references/grill_me_section_walk.md`](https://github.com/alirezarezvani/claude-skills/tree/main/productivity/email/skills/inbox-setup/references/grill_me_section_walk.md) — 8-section discipline + skip-logic + commit-per-section +- [`references/voice_calibration.md`](https://github.com/alirezarezvani/claude-skills/tree/main/productivity/email/skills/inbox-setup/references/voice_calibration.md) — sample-based voice extraction theory + anti-patterns ## Workflows @@ -98,26 +98,26 @@ Differentiates clearly: ls ${WORKSPACE}/Email/ 2>/dev/null # confirm fresh state # 2. Start session -python ../../skills/inbox-setup/scripts/section_progress_tracker.py \ +python ../skills/inbox-setup/scripts/section_progress_tracker.py \ --action start --session "inbox-setup-$(date +%Y%m%d)" --user "<who>" # 3. Walk S1 → S2 → ... → S8 with grill-me discipline # For each Q: ask, wait for answer, record: -python ../../skills/inbox-setup/scripts/section_progress_tracker.py \ +python ../skills/inbox-setup/scripts/section_progress_tracker.py \ --action record_q --session NAME --section 1 --question 1 --answer "..." # 4. End of S2: write email-taxonomy.md; record commit: -python ../../skills/inbox-setup/scripts/section_progress_tracker.py \ +python ../skills/inbox-setup/scripts/section_progress_tracker.py \ --action record_section_done --session NAME --section 2 --files "email-taxonomy.md" # 5. S3 includes sample collection; analyze: -python ../../skills/inbox-setup/scripts/voice_sample_analyzer.py --samples-file /tmp/samples.txt +python ../skills/inbox-setup/scripts/voice_sample_analyzer.py --samples-file /tmp/samples.txt # 6. At S8: validate final state: -python ../../skills/inbox-setup/scripts/kb_validator.py --workspace ${WORKSPACE} +python ../skills/inbox-setup/scripts/kb_validator.py --workspace ${WORKSPACE} # 7. Close session: -python ../../skills/inbox-setup/scripts/section_progress_tracker.py --action close --session NAME +python ../skills/inbox-setup/scripts/section_progress_tracker.py --action close --session NAME ``` ### Workflow 2: Re-run on existing setup @@ -199,7 +199,7 @@ Re-run /cs:inbox-setup when business/pricing/priorities change. ## References -- Skill: [../../skills/inbox-setup/SKILL.md](https://github.com/alirezarezvani/claude-skills/tree/main/productivity/skills/inbox-setup/SKILL.md) +- Skill: [../skills/inbox-setup/SKILL.md](https://github.com/alirezarezvani/claude-skills/tree/main/productivity/email/skills/inbox-setup/SKILL.md) - Source spec: [`megaprompts/06-inbox-setup-megaprompt.md`](https://github.com/alirezarezvani/claude-skills/tree/main/../megaprompts/06-inbox-setup-megaprompt.md) - Sibling command: [`/cs:inbox-setup`](https://github.com/alirezarezvani/claude-skills/tree/main/productivity/email/commands/cs-inbox-setup.md) diff --git a/docs/agents/cs-inbox-triage.md b/docs/agents/cs-inbox-triage.md index b4db832b..c3113c79 100644 --- a/docs/agents/cs-inbox-triage.md +++ b/docs/agents/cs-inbox-triage.md @@ -61,30 +61,30 @@ Differentiates clearly: ## Skill Integration -**Skill Location:** [`skills/inbox-triage`](https://github.com/alirezarezvani/claude-skills/tree/main/productivity/skills/inbox-triage) +**Skill Location:** [`skills/inbox-triage`](https://github.com/alirezarezvani/claude-skills/tree/main/productivity/email/skills/inbox-triage) ### Python Tools (Stdlib) 1. **KB Reader** - - Path: [`scripts/kb_reader.py`](https://github.com/alirezarezvani/claude-skills/tree/main/productivity/skills/inbox-triage/scripts/kb_reader.py) + - Path: [`scripts/kb_reader.py`](https://github.com/alirezarezvani/claude-skills/tree/main/productivity/email/skills/inbox-triage/scripts/kb_reader.py) - Usage: `python kb_reader.py --workspace ${WORKSPACE}` - Reads + validates the 7 KB files. Returns parsed structure (categories, voice patterns, blocklist, tracker entries). Halts with explicit error if required files missing. 2. **Search Window Calculator** - - Path: [`scripts/search_window_calculator.py`](https://github.com/alirezarezvani/claude-skills/tree/main/productivity/skills/inbox-triage/scripts/search_window_calculator.py) + - Path: [`scripts/search_window_calculator.py`](https://github.com/alirezarezvani/claude-skills/tree/main/productivity/email/skills/inbox-triage/scripts/search_window_calculator.py) - Usage: `python search_window_calculator.py --cadence 2x-daily --now 2026-05-15T14:00` - Computes window_start from cadence + current time. Default 9h for 2x/day (slight overlap prevents missed emails). Returns run_label (Morning/Afternoon/Evening) based on hour-of-day. 3. **Draft Safety Validator** - - Path: [`scripts/draft_safety_validator.py`](https://github.com/alirezarezvani/claude-skills/tree/main/productivity/skills/inbox-triage/scripts/draft_safety_validator.py) + - Path: [`scripts/draft_safety_validator.py`](https://github.com/alirezarezvani/claude-skills/tree/main/productivity/email/skills/inbox-triage/scripts/draft_safety_validator.py) - Usage: `python draft_safety_validator.py --action-log /path/to/triage-log.md` - Scans the triage log for any send-shaped action (`send_email`, `gmail.send`, `outlook.send`, etc.). FAILs if any are detected. The non-negotiable NEVER-SEND check in tool form. ### Knowledge Bases -- [`references/kb_file_contract.md`](https://github.com/alirezarezvani/claude-skills/tree/main/productivity/skills/inbox-triage/references/kb_file_contract.md) — canonical 7-file contract (read perspective; mirrors the setup-side version) -- [`references/triage_decision_framework.md`](https://github.com/alirezarezvani/claude-skills/tree/main/productivity/skills/inbox-triage/references/triage_decision_framework.md) — TAKE IT / WORTH CONSIDERING / PASS / FLAG FOR REVIEW taxonomy -- [`references/drafts_only_safety.md`](https://github.com/alirezarezvani/claude-skills/tree/main/productivity/skills/inbox-triage/references/drafts_only_safety.md) — the NEVER-SEND discipline canon +- [`references/kb_file_contract.md`](https://github.com/alirezarezvani/claude-skills/tree/main/productivity/email/skills/inbox-triage/references/kb_file_contract.md) — canonical 7-file contract (read perspective; mirrors the setup-side version) +- [`references/triage_decision_framework.md`](https://github.com/alirezarezvani/claude-skills/tree/main/productivity/email/skills/inbox-triage/references/triage_decision_framework.md) — TAKE IT / WORTH CONSIDERING / PASS / FLAG FOR REVIEW taxonomy +- [`references/drafts_only_safety.md`](https://github.com/alirezarezvani/claude-skills/tree/main/productivity/email/skills/inbox-triage/references/drafts_only_safety.md) — the NEVER-SEND discipline canon ## Workflows @@ -92,11 +92,11 @@ Differentiates clearly: ```bash # 1. Pre-flight — read + validate KB -python ../../skills/inbox-triage/scripts/kb_reader.py --workspace ${WORKSPACE} +python ../skills/inbox-triage/scripts/kb_reader.py --workspace ${WORKSPACE} # If FAIL → halt + direct to setup # 2. Determine window -python ../../skills/inbox-triage/scripts/search_window_calculator.py \ +python ../skills/inbox-triage/scripts/search_window_calculator.py \ --cadence 2x-daily --now $(date -u +%Y-%m-%dT%H:%M) # 3. Execute 10-step workflow (described in SKILL.md): @@ -112,7 +112,7 @@ python ../../skills/inbox-triage/scripts/search_window_calculator.py \ # Step 10: empty-inbox handling # 4. Post-flight — validate no send action occurred -python ../../skills/inbox-triage/scripts/draft_safety_validator.py \ +python ../skills/inbox-triage/scripts/draft_safety_validator.py \ --action-log ${WORKSPACE}/Email/triage-log/$(date +%Y-%m-%d)-*.md # If FAIL → halt + alert user immediately ``` @@ -202,7 +202,7 @@ Generated at <timestamp>. KB updated: {N blocklist, M tracker}. ## References -- Skill: [../../skills/inbox-triage/SKILL.md](https://github.com/alirezarezvani/claude-skills/tree/main/productivity/skills/inbox-triage/SKILL.md) +- Skill: [../skills/inbox-triage/SKILL.md](https://github.com/alirezarezvani/claude-skills/tree/main/productivity/email/skills/inbox-triage/SKILL.md) - Source spec: [`megaprompts/07-inbox-triage-megaprompt.md`](https://github.com/alirezarezvani/claude-skills/tree/main/../megaprompts/07-inbox-triage-megaprompt.md) - Sibling command: [`/cs:inbox-triage`](https://github.com/alirezarezvani/claude-skills/tree/main/productivity/email/commands/cs-inbox-triage.md) diff --git a/docs/agents/cs-landing.md b/docs/agents/cs-landing.md index 335d1916..6c53456a 100644 --- a/docs/agents/cs-landing.md +++ b/docs/agents/cs-landing.md @@ -34,11 +34,11 @@ Visual-premium-focused, motion-aware, brand-respecting. Refuses to ship a generi The cs-landing agent orchestrates the `landing` skill across HTML one-pager generation: 1. **Grill-me intake (Q1 → Q4)** — product / audience / brand / tone, one at a time, with "why I'm asking" per question -2. **Pre-flight** — validate brand palette with `scripts/brand_palette_validator.py`; generate output slug with `scripts/kebab_slug_generator.py` +2. **Pre-flight** — validate brand palette with `skills/landing/scripts/brand_palette_validator.py`; generate output slug with `skills/landing/scripts/kebab_slug_generator.py` 3. **Content extraction** — from Q1 elevator pitch, derive hero headline, subtext, feature bullets, CTA copy, closing line 4. **Brand system** — default dark navy + teal OR overridden palette 5. **Generation (single pass)** — write the .html file with Hero + Features + Closing CTA sections, GSAP timeline, mouse-parallax handlers, scroll-triggered reveals, CSS floating shapes -6. **Post-flight** — validate output with `scripts/html_validator.py` (checks: 3 sections present, CDN deps included, `gsap.set()` initial states, responsive breakpoints, no external CSS/JS files) +6. **Post-flight** — validate output with `skills/landing/scripts/html_validator.py` (checks: 3 sections present, CDN deps included, `gsap.set()` initial states, responsive breakpoints, no external CSS/JS files) 7. **Deliver** — file path (CLI) or HTML artifact (Claude.ai web) Differentiates clearly: diff --git a/docs/agents/cs-litreview.md b/docs/agents/cs-litreview.md index 54d2a8cd..8d084fc8 100644 --- a/docs/agents/cs-litreview.md +++ b/docs/agents/cs-litreview.md @@ -38,7 +38,7 @@ The cs-litreview agent orchestrates the `litreview` skill across academic-resear 3. **Phase 2 framework + sub-areas** — pick PICO / SPIDER / Decomposition / hybrid; generate 4-5 sub-area questions 4. **Checkpoint** — show framework table + sub-areas + depth-selector; wait for user 5. **Phase 3 searches** — sequential, 1 q/sec, budget per depth tier (5/10/20) -6. **Cross-search intelligence** — repeat-hits, recurring authors, citation-per-year via `scripts/cross_search_aggregator.py` +6. **Cross-search intelligence** — repeat-hits, recurring authors, citation-per-year via `skills/litreview/scripts/cross_search_aggregator.py` 7. **Phase 4 DOCX** — 8-section guide via Node.js + `docx` library Differentiates from siblings: @@ -55,7 +55,7 @@ Differentiates from siblings: 4. **Plan-tier detect at first search.** Report at checkpoint so user can recalibrate depth. 5. **Halt at checkpoint.** Refuse to start Phase 3 without explicit user choice. 6. **Source discipline.** Cite only Consensus-returned papers from THIS session. Training knowledge labeled `[Not from Consensus]`. -7. **Three-count tracking.** Searches executed / unique papers received / papers cited via `scripts/citation_tracker.py`. +7. **Three-count tracking.** Searches executed / unique papers received / papers cited via `skills/litreview/scripts/citation_tracker.py`. 8. **Retry once after 3s.** Then log. 3 consecutive failures → stop. ## Skill Integration @@ -105,7 +105,7 @@ python ../skills/litreview/scripts/framework_recommender.py --question "<from Q1 # Phase 4: cross-search aggregation + DOCX python ../skills/litreview/scripts/cross_search_aggregator.py --session NAME # Generate DOCX via Node.js + docx library -python scripts/office/validate.py output.docx # from docx skill +python3 -c "import zipfile,sys; zipfile.ZipFile(sys.argv[1]).testzip()" output.docx # zip-integrity check (no output = intact); then confirm required sections present python ../skills/litreview/scripts/citation_tracker.py --action close --session NAME ``` diff --git a/docs/agents/cs-markdown-html-orchestrator.md b/docs/agents/cs-markdown-html-orchestrator.md index e935dad6..acc59f06 100644 --- a/docs/agents/cs-markdown-html-orchestrator.md +++ b/docs/agents/cs-markdown-html-orchestrator.md @@ -7,7 +7,7 @@ description: "Density-first markdown-to-HTML converter. Routes long markdown fil <div class="page-meta" markdown> <span class="meta-badge">:material-robot: Agent</span> -<span class="meta-badge">:material-account: Markdown Html</span> +<span class="meta-badge">:material-language-html5: Markdown to HTML</span> <span class="meta-badge">:material-github: <a href="https://github.com/alirezarezvani/claude-skills/tree/main/markdown-html/agents/cs-markdown-html-orchestrator.md">Source</a></span> </div> @@ -36,7 +36,7 @@ You route every inquiry to one of three converter sub-skills via the `markdown-h | Review | `md-review` | Code review / PR writeup with diff blocks and severity annotations | | Slides | `md-slides` | Slide deck with `---` boundaries or H1 cadence + presenter notes | -Each sub-skill ships in v2.10.1 follow-up PRs. Until they land (v2.10.0 foundation), you run the classifier + design-system gate and hand the rendering brief back to Claude. +All three converter sub-skills are live. After the classifier + design-system gate pass, hand the conversion to the routed sub-skill's renderer scripts — never render HTML by hand. ## Pre-flight gates (refuse and surface, never override) @@ -86,10 +86,9 @@ After running a conversion, return a **≤ 100-word digest**: - `/cs:grill-markdown-html <markdown-file-path>` — Matt-style grilling before conversion - `/cs:design-system` — surface the onboarding wizard -Once converter sub-skills ship in v2.10.1: -- `/cs:md-document <markdown-file-path>` -- `/cs:md-review <markdown-file-path>` -- `/cs:md-slides <markdown-file-path>` +- `/cs:md-document <markdown-file-path>` — long-form converter +- `/cs:md-review <markdown-file-path>` — code-review converter +- `/cs:md-slides <markdown-file-path>` — slide-deck converter ## When to escalate diff --git a/docs/agents/cs-notebooklm.md b/docs/agents/cs-notebooklm.md index 1889c3ae..3b9bca0f 100644 --- a/docs/agents/cs-notebooklm.md +++ b/docs/agents/cs-notebooklm.md @@ -64,15 +64,15 @@ The cs-notebooklm agent orchestrates the `notebooklm` skill across NotebookLM br ### Python Tools (Stdlib) -1. **Action Router** — `scripts/action_router.py` — Q1-Q4 answers → action plan + UI flow + required parameters -2. **Custom Prompt Template Generator** — `scripts/custom_prompt_template_generator.py` — Studio output type + audience → starter custom prompt -3. **Async Action Classifier** — `scripts/async_action_classifier.py` — action name → wait-or-notify pattern (which generations block and which return immediately) +1. **Action Router** — `skills/notebooklm/scripts/action_router.py` — Q1-Q4 answers → action plan + UI flow + required parameters +2. **Custom Prompt Template Generator** — `skills/notebooklm/scripts/custom_prompt_template_generator.py` — Studio output type + audience → starter custom prompt +3. **Async Action Classifier** — `skills/notebooklm/scripts/async_action_classifier.py` — action name → wait-or-notify pattern (which generations block and which return immediately) ### Knowledge Bases -- `references/browser_automation_canon.md` — screenshot-first + find-before-click + tool-agnostic patterns (7+ sources) -- `references/studio_output_custom_prompts.md` — why defaults are mediocre + per-output-type templates (7+ sources) -- `references/async_action_discipline.md` — fire-and-notify pattern for slow UI ops (7+ sources) +- `skills/notebooklm/references/browser_automation_canon.md` — screenshot-first + find-before-click + tool-agnostic patterns (7+ sources) +- `skills/notebooklm/references/studio_output_custom_prompts.md` — why defaults are mediocre + per-output-type templates (7+ sources) +- `skills/notebooklm/references/async_action_discipline.md` — fire-and-notify pattern for slow UI ops (7+ sources) ## Related Agents diff --git a/docs/agents/cs-patent.md b/docs/agents/cs-patent.md index 27483a2b..027c841b 100644 --- a/docs/agents/cs-patent.md +++ b/docs/agents/cs-patent.md @@ -31,10 +31,10 @@ description: "Patent prior-art + landscape intelligence persona. Walks 6 forcing The cs-patent agent orchestrates the `patent` skill across prior-art + landscape research: 1. **Phase 1 intake** — Q1-Q6 one at a time, with sub-use-case commitment at Q2 -2. **Phase 2 search strategy selection** — deterministic via `scripts/sub_use_case_router.py` +2. **Phase 2 search strategy selection** — deterministic via `skills/patent/scripts/sub_use_case_router.py` 3. **Phase 3 multi-source search** — Google Patents (workhorse) + Espacenet + USPTO + optional Lens.org 4. **Phase 4 claim extraction + relevance scoring** — pull independent claim 1 + key dependents -5. **Phase 5 citation graph + family resolution** — deduplicate via `scripts/family_resolver.py` +5. **Phase 5 citation graph + family resolution** — deduplicate via `skills/patent/scripts/family_resolver.py` 6. **Phase 6 DOCX** — 8 sections with sub-use-case-specific emphasis 7. **Phase 7 deliver** — file + chat summary with verdict @@ -56,15 +56,15 @@ The cs-patent agent orchestrates the `patent` skill across prior-art + landscape ### Python Tools (Stdlib) -1. **Citation Tracker** — `scripts/citation_tracker.py` — three-count audit across Google Patents + Espacenet + USPTO + Lens.org sources at `~/.patent_sessions/<session>.json` -2. **Family Resolver** — `scripts/family_resolver.py` — group same-invention filings (e.g., US + EP + JP + CN of one priority) by priority number / family ID -3. **Sub-Use-Case Router** — `scripts/sub_use_case_router.py` — deterministic search strategy from intake answers +1. **Citation Tracker** — `skills/patent/scripts/citation_tracker.py` — three-count audit across Google Patents + Espacenet + USPTO + Lens.org sources at `~/.patent_sessions/<session>.json` +2. **Family Resolver** — `skills/patent/scripts/family_resolver.py` — group same-invention filings (e.g., US + EP + JP + CN of one priority) by priority number / family ID +3. **Sub-Use-Case Router** — `skills/patent/scripts/sub_use_case_router.py` — deterministic search strategy from intake answers ### Knowledge Bases -- `references/sub_use_case_routing.md` — 5-sub-use-case canon + when each applies (7+ sources) -- `references/cpc_classification_canon.md` — CPC/IPC class follow-up rationale (7+ sources) -- `references/legal_disclaimer_discipline.md` — when + why disclaimer mandatory (7+ sources) +- `skills/patent/references/sub_use_case_routing.md` — 5-sub-use-case canon + when each applies (7+ sources) +- `skills/patent/references/cpc_classification_canon.md` — CPC/IPC class follow-up rationale (7+ sources) +- `skills/patent/references/legal_disclaimer_discipline.md` — when + why disclaimer mandatory (7+ sources) ## Related Agents diff --git a/docs/agents/cs-product-analyst.md b/docs/agents/cs-product-analyst.md index 1c1cc151..f0429fd3 100644 --- a/docs/agents/cs-product-analyst.md +++ b/docs/agents/cs-product-analyst.md @@ -1,6 +1,6 @@ --- title: "Product Analyst Agent — AI Coding Agent & Codex Skill" -description: "Product analytics agent for KPI definition, dashboard setup, experiment design, and test result interpretation.. Agent-native orchestrator for Claude Code, Codex, Gemini CLI." +description: "Product analytics agent for KPI definition, dashboard setup, experiment design, and test result interpretation. Use when a product question needs. Agent-native orchestrator for Claude Code, Codex, Gemini CLI." --- # Product Analyst Agent @@ -12,21 +12,77 @@ description: "Product analytics agent for KPI definition, dashboard setup, exper </div> -## Skill Links -- [`product-analytics/SKILL.md`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/product-analytics/SKILL.md) -- [`experiment-designer/SKILL.md`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/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 -- [`scripts/metrics_calculator.py`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/product-analytics/scripts/metrics_calculator.py) -- [`scripts/sample_size_calculator.py`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/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:** +- [`skills/product-analytics`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/skills/product-analytics) ([SKILL.md](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/skills/product-analytics/SKILL.md)) +- [`skills/experiment-designer`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/skills/experiment-designer) ([SKILL.md](https://github.com/alirezarezvani/claude-skills/tree/main/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:** [`scripts/metrics_calculator.py`](https://github.com/alirezarezvani/claude-skills/tree/main/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:** [`scripts/sample_size_calculator.py`](https://github.com/alirezarezvani/claude-skills/tree/main/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](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/skills/product-analytics/SKILL.md) +- [Experiment Designer Skill](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/skills/experiment-designer/SKILL.md) diff --git a/docs/agents/cs-product-manager.md b/docs/agents/cs-product-manager.md index 39a2678e..62d803e5 100644 --- a/docs/agents/cs-product-manager.md +++ b/docs/agents/cs-product-manager.md @@ -1,6 +1,6 @@ --- title: "Product Manager Agent — AI Coding Agent & Codex Skill" -description: "Product management agent for feature prioritization, customer discovery, PRD development, and roadmap planning using RICE framework. Agent-native orchestrator for Claude Code, Codex, Gemini CLI." +description: "Product management agent for feature prioritization, customer discovery, PRD development, and roadmap planning using RICE framework. Use when a. Agent-native orchestrator for Claude Code, Codex, Gemini CLI." --- # Product Manager Agent @@ -22,144 +22,144 @@ The cs-product-manager agent bridges the gap between customer insights and produ ## Skill Integration -**Primary Skill:** [`product-team/product-manager-toolkit`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/product-manager-toolkit) +**Primary Skill:** [`skills/product-manager-toolkit`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/skills/product-manager-toolkit) ### All Orchestrated Skills | # | Skill | Location | Primary Tool | |---|-------|----------|-------------| -| 1 | Product Manager Toolkit | [`product-team/product-manager-toolkit`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/product-manager-toolkit) | rice_prioritizer.py, customer_interview_analyzer.py | +| 1 | Product Manager Toolkit | [`skills/product-manager-toolkit`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/skills/product-manager-toolkit) | rice_prioritizer.py, customer_interview_analyzer.py | | 2 | Agile Product Owner | [`product-team/agile-product-owner`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/agile-product-owner) | user_story_generator.py | -| 3 | Product Strategist | [`product-team/product-strategist`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/product-strategist) | okr_cascade_generator.py | -| 4 | UX Researcher & Designer | [`product-team/ux-researcher-designer`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/ux-researcher-designer) | persona_generator.py | -| 5 | UI Design System | [`product-team/ui-design-system`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/ui-design-system) | design_token_generator.py | -| 6 | Competitive Teardown | [`product-team/competitive-teardown`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/competitive-teardown) | competitive_matrix_builder.py | -| 7 | Landing Page Generator | [`product-team/landing-page-generator`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/landing-page-generator) | landing_page_scaffolder.py | -| 8 | SaaS Scaffolder | [`product-team/saas-scaffolder`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/saas-scaffolder) | project_bootstrapper.py | +| 3 | Product Strategist | [`skills/product-strategist`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/skills/product-strategist) | okr_cascade_generator.py | +| 4 | UX Researcher & Designer | [`skills/ux-researcher-designer`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/skills/ux-researcher-designer) | persona_generator.py | +| 5 | UI Design System | [`skills/ui-design-system`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/skills/ui-design-system) | design_token_generator.py | +| 6 | Competitive Teardown | [`skills/competitive-teardown`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/skills/competitive-teardown) | competitive_matrix_builder.py | +| 7 | Landing Page Generator | [`skills/landing-page-generator`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/skills/landing-page-generator) | landing_page_scaffolder.py | +| 8 | SaaS Scaffolder | [`skills/saas-scaffolder`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/skills/saas-scaffolder) | project_bootstrapper.py | ### Python Tools 1. **RICE Prioritizer** - **Purpose:** RICE framework implementation for feature prioritization with portfolio analysis and capacity planning - - **Path:** [`scripts/rice_prioritizer.py`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/product-manager-toolkit/scripts/rice_prioritizer.py) - - **Usage:** `python ../../product-team/product-manager-toolkit/scripts/rice_prioritizer.py features.csv --capacity 20` + - **Path:** [`scripts/rice_prioritizer.py`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/skills/product-manager-toolkit/scripts/rice_prioritizer.py) + - **Usage:** `python ../../product-team/skills/product-manager-toolkit/scripts/rice_prioritizer.py features.csv --capacity 20` - **Formula:** RICE Score = (Reach × Impact × Confidence) / Effort - **Features:** Portfolio analysis (quick wins vs big bets), quarterly roadmap generation, capacity planning, JSON/CSV export - **Use Cases:** Feature prioritization, roadmap planning, stakeholder alignment, resource allocation 2. **Customer Interview Analyzer** - **Purpose:** NLP-based interview transcript analysis to extract pain points, feature requests, and themes - - **Path:** [`scripts/customer_interview_analyzer.py`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/product-manager-toolkit/scripts/customer_interview_analyzer.py) - - **Usage:** `python ../../product-team/product-manager-toolkit/scripts/customer_interview_analyzer.py interview.txt` + - **Path:** [`scripts/customer_interview_analyzer.py`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/skills/product-manager-toolkit/scripts/customer_interview_analyzer.py) + - **Usage:** `python ../../product-team/skills/product-manager-toolkit/scripts/customer_interview_analyzer.py interview.txt` - **Features:** Pain point extraction with severity, feature request identification, jobs-to-be-done patterns, sentiment analysis, theme extraction - **Use Cases:** User research synthesis, discovery validation, problem prioritization, insight generation 3. **User Story Generator** - **Purpose:** Break epics into INVEST-compliant user stories with acceptance criteria - - **Path:** [`scripts/user_story_generator.py`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/agile-product-owner/scripts/user_story_generator.py) - - **Usage:** `python ../../product-team/agile-product-owner/scripts/user_story_generator.py epic.yaml` + - **Path:** [`scripts/user_story_generator.py`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/agile-product-owner/skills/agile-product-owner/scripts/user_story_generator.py) + - **Usage:** `python ../../product-team/agile-product-owner/skills/agile-product-owner/scripts/user_story_generator.py epic.yaml` - **Use Cases:** Sprint planning, backlog refinement, story decomposition 4. **OKR Cascade Generator** - **Purpose:** Generate cascaded OKRs from company objectives to team-level key results - - **Path:** [`scripts/okr_cascade_generator.py`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/product-strategist/scripts/okr_cascade_generator.py) - - **Usage:** `python ../../product-team/product-strategist/scripts/okr_cascade_generator.py growth` + - **Path:** [`scripts/okr_cascade_generator.py`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/skills/product-strategist/scripts/okr_cascade_generator.py) + - **Usage:** `python ../../product-team/skills/product-strategist/scripts/okr_cascade_generator.py growth` - **Use Cases:** Quarterly planning, strategic alignment, goal setting 5. **Persona Generator** - **Purpose:** Create data-driven user personas from research inputs - - **Path:** [`scripts/persona_generator.py`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/ux-researcher-designer/scripts/persona_generator.py) - - **Usage:** `python ../../product-team/ux-researcher-designer/scripts/persona_generator.py research-data.json` + - **Path:** [`scripts/persona_generator.py`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/skills/ux-researcher-designer/scripts/persona_generator.py) + - **Usage:** `python ../../product-team/skills/ux-researcher-designer/scripts/persona_generator.py research-data.json` - **Use Cases:** User research synthesis, persona development, journey mapping 6. **Design Token Generator** - **Purpose:** Generate design tokens for consistent UI implementation - - **Path:** [`scripts/design_token_generator.py`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/ui-design-system/scripts/design_token_generator.py) - - **Usage:** `python ../../product-team/ui-design-system/scripts/design_token_generator.py theme.json` + - **Path:** [`scripts/design_token_generator.py`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/skills/ui-design-system/scripts/design_token_generator.py) + - **Usage:** `python ../../product-team/skills/ui-design-system/scripts/design_token_generator.py theme.json` - **Use Cases:** Design system creation, developer handoff, theming 7. **Competitive Matrix Builder** - **Purpose:** Build competitive analysis matrices and feature comparison grids - - **Path:** [`scripts/competitive_matrix_builder.py`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/competitive-teardown/scripts/competitive_matrix_builder.py) - - **Usage:** `python ../../product-team/competitive-teardown/scripts/competitive_matrix_builder.py competitors.csv` + - **Path:** [`scripts/competitive_matrix_builder.py`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/skills/competitive-teardown/scripts/competitive_matrix_builder.py) + - **Usage:** `python ../../product-team/skills/competitive-teardown/scripts/competitive_matrix_builder.py competitors.csv` - **Use Cases:** Competitive intelligence, market positioning, feature gap analysis 8. **Landing Page Scaffolder** - **Purpose:** Generate conversion-optimized landing page scaffolds - - **Path:** [`scripts/landing_page_scaffolder.py`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/landing-page-generator/scripts/landing_page_scaffolder.py) - - **Usage:** `python ../../product-team/landing-page-generator/scripts/landing_page_scaffolder.py config.yaml` + - **Path:** [`scripts/landing_page_scaffolder.py`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/skills/landing-page-generator/scripts/landing_page_scaffolder.py) + - **Usage:** `python ../../product-team/skills/landing-page-generator/scripts/landing_page_scaffolder.py config.yaml` - **Use Cases:** Product launches, A/B testing, GTM campaigns 9. **Project Bootstrapper** - **Purpose:** Scaffold SaaS project structures with boilerplate and configurations - - **Path:** [`scripts/project_bootstrapper.py`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/saas-scaffolder/scripts/project_bootstrapper.py) - - **Usage:** `python ../../product-team/saas-scaffolder/scripts/project_bootstrapper.py --stack nextjs --name my-saas` + - **Path:** [`scripts/project_bootstrapper.py`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/skills/saas-scaffolder/scripts/project_bootstrapper.py) + - **Usage:** `python ../../product-team/skills/saas-scaffolder/scripts/project_bootstrapper.py --stack nextjs --name my-saas` - **Use Cases:** MVP scaffolding, project kickoff, SaaS prototype creation ### Knowledge Bases 1. **PRD Templates** - - **Location:** [`references/prd_templates.md`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/product-manager-toolkit/references/prd_templates.md) + - **Location:** [`references/prd_templates.md`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/skills/product-manager-toolkit/references/prd_templates.md) - **Content:** Multiple PRD formats (Standard PRD, One-Page PRD, Feature Brief, Agile Epic), structure guidelines, best practices - **Use Case:** Requirements documentation, stakeholder communication, engineering handoff 2. **Sprint Planning Guide** - - **Location:** [`references/sprint-planning-guide.md`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/agile-product-owner/references/sprint-planning-guide.md) + - **Location:** [`references/sprint-planning-guide.md`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/agile-product-owner/skills/agile-product-owner/references/sprint-planning-guide.md) - **Content:** Sprint planning ceremonies, velocity tracking, capacity allocation - **Use Case:** Sprint execution, backlog refinement, agile ceremonies 3. **User Story Templates** - - **Location:** [`references/user-story-templates.md`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/agile-product-owner/references/user-story-templates.md) + - **Location:** [`references/user-story-templates.md`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/agile-product-owner/skills/agile-product-owner/references/user-story-templates.md) - **Content:** INVEST-compliant story formats, acceptance criteria patterns, story splitting techniques - **Use Case:** Story writing, backlog grooming, definition of done 4. **OKR Framework** - - **Location:** [`references/okr_framework.md`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/product-strategist/references/okr_framework.md) + - **Location:** [`references/okr_framework.md`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/skills/product-strategist/references/okr_framework.md) - **Content:** OKR methodology, cascade patterns, scoring guidelines - **Use Case:** Quarterly planning, strategic alignment, goal tracking 5. **Strategy Types** - - **Location:** [`references/strategy_types.md`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/product-strategist/references/strategy_types.md) + - **Location:** [`references/strategy_types.md`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/skills/product-strategist/references/strategy_types.md) - **Content:** Product strategy frameworks, competitive positioning, growth strategies - **Use Case:** Strategic planning, market analysis, product vision 6. **Persona Methodology** - - **Location:** [`references/persona-methodology.md`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/ux-researcher-designer/references/persona-methodology.md) + - **Location:** [`references/persona-methodology.md`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/skills/ux-researcher-designer/references/persona-methodology.md) - **Content:** Research-backed persona creation methodology, data collection, validation - **Use Case:** Persona development, user segmentation, research planning 7. **Example Personas** - - **Location:** [`references/example-personas.md`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/ux-researcher-designer/references/example-personas.md) + - **Location:** [`references/example-personas.md`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/skills/ux-researcher-designer/references/example-personas.md) - **Content:** Sample persona documents with demographics, goals, pain points, behaviors - **Use Case:** Persona templates, research documentation 8. **Journey Mapping Guide** - - **Location:** [`references/journey-mapping-guide.md`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/ux-researcher-designer/references/journey-mapping-guide.md) + - **Location:** [`references/journey-mapping-guide.md`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/skills/ux-researcher-designer/references/journey-mapping-guide.md) - **Content:** Customer journey mapping methodology, touchpoint analysis, emotion mapping - **Use Case:** Experience design, touchpoint optimization, service design 9. **Usability Testing Frameworks** - - **Location:** [`references/usability-testing-frameworks.md`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/ux-researcher-designer/references/usability-testing-frameworks.md) + - **Location:** [`references/usability-testing-frameworks.md`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/skills/ux-researcher-designer/references/usability-testing-frameworks.md) - **Content:** Usability test planning, task design, analysis methods - **Use Case:** Usability studies, prototype validation, UX evaluation 10. **Component Architecture** - - **Location:** [`references/component-architecture.md`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/ui-design-system/references/component-architecture.md) + - **Location:** [`references/component-architecture.md`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/skills/ui-design-system/references/component-architecture.md) - **Content:** Component hierarchy, atomic design patterns, composition strategies - **Use Case:** Design system architecture, component libraries 11. **Developer Handoff** - - **Location:** [`references/developer-handoff.md`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/ui-design-system/references/developer-handoff.md) + - **Location:** [`references/developer-handoff.md`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/skills/ui-design-system/references/developer-handoff.md) - **Content:** Design-to-dev handoff process, specification formats, asset delivery - **Use Case:** Engineering collaboration, implementation specs 12. **Responsive Calculations** - - **Location:** [`references/responsive-calculations.md`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/ui-design-system/references/responsive-calculations.md) + - **Location:** [`references/responsive-calculations.md`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/skills/ui-design-system/references/responsive-calculations.md) - **Content:** Responsive design formulas, breakpoint strategies, fluid typography - **Use Case:** Responsive implementation, cross-device design 13. **Token Generation** - - **Location:** [`references/token-generation.md`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/ui-design-system/references/token-generation.md) + - **Location:** [`references/token-generation.md`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/skills/ui-design-system/references/token-generation.md) - **Content:** Design token standards, naming conventions, platform-specific output - **Use Case:** Design system tokens, theming, multi-platform consistency @@ -191,7 +191,7 @@ The cs-product-manager agent bridges the gap between customer insights and produ 3. **Run RICE Prioritization** - Execute analysis with team capacity ```bash - python ../../product-team/product-manager-toolkit/scripts/rice_prioritizer.py features.csv --capacity 20 + python ../../product-team/skills/product-manager-toolkit/scripts/rice_prioritizer.py features.csv --capacity 20 ``` 4. **Analyze Portfolio** - Review output for: @@ -217,7 +217,7 @@ The cs-product-manager agent bridges the gap between customer insights and produ **Example:** ```bash # Complete prioritization workflow -python ../../product-team/product-manager-toolkit/scripts/rice_prioritizer.py q4-features.csv --capacity 20 > roadmap.txt +python ../../product-team/skills/product-manager-toolkit/scripts/rice_prioritizer.py q4-features.csv --capacity 20 > roadmap.txt cat roadmap.txt # Review quick wins, big bets, and generate quarterly plan ``` @@ -243,7 +243,7 @@ cat roadmap.txt 3. **Run Interview Analyzer** - Extract structured insights ```bash - python ../../product-team/product-manager-toolkit/scripts/customer_interview_analyzer.py interview-001.txt + python ../../product-team/skills/product-manager-toolkit/scripts/customer_interview_analyzer.py interview-001.txt ``` 4. **Review Analysis Output** - Study extracted insights: @@ -257,9 +257,9 @@ cat roadmap.txt 5. **Synthesize Across Interviews** - Aggregate insights: ```bash # Analyze multiple interviews - python ../../product-team/product-manager-toolkit/scripts/customer_interview_analyzer.py interview-001.txt json > insights-001.json - python ../../product-team/product-manager-toolkit/scripts/customer_interview_analyzer.py interview-002.txt json > insights-002.json - python ../../product-team/product-manager-toolkit/scripts/customer_interview_analyzer.py interview-003.txt json > insights-003.json + python ../../product-team/skills/product-manager-toolkit/scripts/customer_interview_analyzer.py interview-001.txt json > insights-001.json + python ../../product-team/skills/product-manager-toolkit/scripts/customer_interview_analyzer.py interview-002.txt json > insights-002.json + python ../../product-team/skills/product-manager-toolkit/scripts/customer_interview_analyzer.py interview-003.txt json > insights-003.json # Aggregate JSON files to find patterns ``` @@ -285,7 +285,7 @@ cat roadmap.txt **Steps:** 1. **Choose PRD Template** - Select based on complexity: ```bash - cat ../../product-team/product-manager-toolkit/references/prd_templates.md + cat ../../product-team/skills/product-manager-toolkit/references/prd_templates.md ``` - **Standard PRD**: Complex features (6-8 weeks dev) - **One-Page PRD**: Simple features (2-4 weeks) @@ -344,12 +344,12 @@ cat roadmap.txt 2. **Run Feature Prioritization** - Use RICE for candidate features ```bash - python ../../product-team/product-manager-toolkit/scripts/rice_prioritizer.py q4-candidates.csv --capacity 18 + python ../../product-team/skills/product-manager-toolkit/scripts/rice_prioritizer.py q4-candidates.csv --capacity 18 ``` 3. **Generate OKR Cascade** - Use the OKR cascade generator to create aligned objectives ```bash - python ../../product-team/product-strategist/scripts/okr_cascade_generator.py growth + python ../../product-team/skills/product-strategist/scripts/okr_cascade_generator.py growth ``` 4. **Define Product OKRs** - Set ambitious but achievable goals: @@ -399,22 +399,22 @@ cat roadmap.txt 2. **Review Persona Methodology** - Understand research-backed persona creation ```bash - cat ../../product-team/ux-researcher-designer/references/persona-methodology.md + cat ../../product-team/skills/ux-researcher-designer/references/persona-methodology.md ``` 3. **Generate Personas** - Create structured personas from research inputs ```bash - python ../../product-team/ux-researcher-designer/scripts/persona_generator.py research-data.json + python ../../product-team/skills/ux-researcher-designer/scripts/persona_generator.py research-data.json ``` 4. **Map Customer Journeys** - Reference journey mapping guide for each persona ```bash - cat ../../product-team/ux-researcher-designer/references/journey-mapping-guide.md + cat ../../product-team/skills/ux-researcher-designer/references/journey-mapping-guide.md ``` 5. **Review Example Personas** - Compare output against proven persona formats ```bash - cat ../../product-team/ux-researcher-designer/references/example-personas.md + cat ../../product-team/skills/ux-researcher-designer/references/example-personas.md ``` 6. **Validate and Iterate** - Share personas with stakeholders: @@ -429,13 +429,13 @@ cat roadmap.txt **Example:** ```bash # Complete persona generation workflow -python ../../product-team/ux-researcher-designer/scripts/persona_generator.py user-research-q4.json > personas.md +python ../../product-team/skills/ux-researcher-designer/scripts/persona_generator.py user-research-q4.json > personas.md # Cross-reference with interview analysis -python ../../product-team/product-manager-toolkit/scripts/customer_interview_analyzer.py interviews-batch.txt > insights.txt +python ../../product-team/skills/product-manager-toolkit/scripts/customer_interview_analyzer.py interviews-batch.txt > insights.txt # Review journey mapping methodology -cat ../../product-team/ux-researcher-designer/references/journey-mapping-guide.md +cat ../../product-team/skills/ux-researcher-designer/references/journey-mapping-guide.md ``` ### Workflow 6: Sprint Story Generation @@ -451,17 +451,17 @@ cat ../../product-team/ux-researcher-designer/references/journey-mapping-guide.m 2. **Review Story Templates** - Load INVEST-compliant story patterns ```bash - cat ../../product-team/agile-product-owner/references/user-story-templates.md + cat ../../product-team/agile-product-owner/skills/agile-product-owner/references/user-story-templates.md ``` 3. **Generate User Stories** - Break the epic into sprint-sized stories ```bash - python ../../product-team/agile-product-owner/scripts/user_story_generator.py epic.yaml + python ../../product-team/agile-product-owner/skills/agile-product-owner/scripts/user_story_generator.py epic.yaml ``` 4. **Review Sprint Planning Guide** - Ensure stories fit sprint capacity ```bash - cat ../../product-team/agile-product-owner/references/sprint-planning-guide.md + cat ../../product-team/agile-product-owner/skills/agile-product-owner/references/sprint-planning-guide.md ``` 5. **Refine and Estimate** - Groom generated stories: @@ -472,7 +472,7 @@ cat ../../product-team/ux-researcher-designer/references/journey-mapping-guide.m 6. **Prioritize for Sprint** - Use RICE scores to sequence stories ```bash - python ../../product-team/product-manager-toolkit/scripts/rice_prioritizer.py sprint-stories.csv --capacity 8 + python ../../product-team/skills/product-manager-toolkit/scripts/rice_prioritizer.py sprint-stories.csv --capacity 8 ``` **Expected Output:** Sprint-ready backlog of INVEST-compliant user stories with acceptance criteria, story points, and priority order @@ -482,13 +482,13 @@ cat ../../product-team/ux-researcher-designer/references/journey-mapping-guide.m **Example:** ```bash # End-to-end story generation workflow -python ../../product-team/agile-product-owner/scripts/user_story_generator.py onboarding-epic.yaml > stories.md +python ../../product-team/agile-product-owner/skills/agile-product-owner/scripts/user_story_generator.py onboarding-epic.yaml > stories.md # Prioritize stories for sprint -python ../../product-team/product-manager-toolkit/scripts/rice_prioritizer.py stories.csv --capacity 8 > sprint-plan.txt +python ../../product-team/skills/product-manager-toolkit/scripts/rice_prioritizer.py stories.csv --capacity 8 > sprint-plan.txt # Review sprint planning best practices -cat ../../product-team/agile-product-owner/references/sprint-planning-guide.md +cat ../../product-team/agile-product-owner/skills/agile-product-owner/references/sprint-planning-guide.md ``` ### Workflow 7: Competitive Intelligence @@ -511,7 +511,7 @@ cat ../../product-team/agile-product-owner/references/sprint-planning-guide.md 3. **Build Competitive Matrix** - Generate visual comparison ```bash - python ../../product-team/competitive-teardown/scripts/competitive_matrix_builder.py competitors.csv + python ../../product-team/skills/competitive-teardown/scripts/competitive_matrix_builder.py competitors.csv ``` 4. **Analyze Gaps** - Identify strategic opportunities: @@ -523,7 +523,7 @@ cat ../../product-team/agile-product-owner/references/sprint-planning-guide.md 5. **Feed Into Prioritization** - Use gaps to inform roadmap ```bash # Add competitive gap features to RICE analysis - python ../../product-team/product-manager-toolkit/scripts/rice_prioritizer.py competitive-features.csv --capacity 20 + python ../../product-team/skills/product-manager-toolkit/scripts/rice_prioritizer.py competitive-features.csv --capacity 20 ``` 6. **Track Over Time** - Update competitive matrix quarterly: @@ -538,10 +538,10 @@ cat ../../product-team/agile-product-owner/references/sprint-planning-guide.md **Example:** ```bash # Full competitive intelligence workflow -python ../../product-team/competitive-teardown/scripts/competitive_matrix_builder.py q4-competitors.csv > competitive-matrix.md +python ../../product-team/skills/competitive-teardown/scripts/competitive_matrix_builder.py q4-competitors.csv > competitive-matrix.md # Prioritize competitive gap features -python ../../product-team/product-manager-toolkit/scripts/rice_prioritizer.py gap-features.csv --capacity 12 > competitive-roadmap.txt +python ../../product-team/skills/product-manager-toolkit/scripts/rice_prioritizer.py gap-features.csv --capacity 12 > competitive-roadmap.txt ``` ## Integration Examples @@ -558,13 +558,13 @@ echo "==========================================" # Current roadmap status echo "" echo "🎯 Roadmap Priorities (RICE Sorted):" -python ../../product-team/product-manager-toolkit/scripts/rice_prioritizer.py current-roadmap.csv --capacity 20 +python ../../product-team/skills/product-manager-toolkit/scripts/rice_prioritizer.py current-roadmap.csv --capacity 20 # Recent interview insights echo "" echo "💡 Latest Customer Insights:" if [ -f latest-interview.txt ]; then - python ../../product-team/product-manager-toolkit/scripts/customer_interview_analyzer.py latest-interview.txt + python ../../product-team/skills/product-manager-toolkit/scripts/customer_interview_analyzer.py latest-interview.txt else echo "No new interviews this week" fi @@ -573,7 +573,7 @@ fi echo "" echo "📝 PRD Templates:" echo "Standard PRD, One-Page PRD, Feature Brief, Agile Epic" -echo "Location: ../../product-team/product-manager-toolkit/references/prd_templates.md" +echo "Location: ../../product-team/skills/product-manager-toolkit/references/prd_templates.md" ``` ### Example 2: Discovery Sprint Workflow @@ -588,11 +588,11 @@ echo "==============================" echo "Conducting 5 customer interviews..." # Day 3-5: Analyze insights -python ../../product-team/product-manager-toolkit/scripts/customer_interview_analyzer.py interview-001.txt > insights-001.txt -python ../../product-team/product-manager-toolkit/scripts/customer_interview_analyzer.py interview-002.txt > insights-002.txt -python ../../product-team/product-manager-toolkit/scripts/customer_interview_analyzer.py interview-003.txt > insights-003.txt -python ../../product-team/product-manager-toolkit/scripts/customer_interview_analyzer.py interview-004.txt > insights-004.txt -python ../../product-team/product-manager-toolkit/scripts/customer_interview_analyzer.py interview-005.txt > insights-005.txt +python ../../product-team/skills/product-manager-toolkit/scripts/customer_interview_analyzer.py interview-001.txt > insights-001.txt +python ../../product-team/skills/product-manager-toolkit/scripts/customer_interview_analyzer.py interview-002.txt > insights-002.txt +python ../../product-team/skills/product-manager-toolkit/scripts/customer_interview_analyzer.py interview-003.txt > insights-003.txt +python ../../product-team/skills/product-manager-toolkit/scripts/customer_interview_analyzer.py interview-004.txt > insights-004.txt +python ../../product-team/skills/product-manager-toolkit/scripts/customer_interview_analyzer.py interview-005.txt > insights-005.txt echo "" echo "🔍 Discovery Sprint - Week 2" @@ -602,7 +602,7 @@ echo "==============================" echo "Creating solution candidates..." # Day 9-10: RICE prioritization -python ../../product-team/product-manager-toolkit/scripts/rice_prioritizer.py solution-candidates.csv +python ../../product-team/skills/product-manager-toolkit/scripts/rice_prioritizer.py solution-candidates.csv echo "" echo "✅ Discovery Complete - Ready for PRD creation" @@ -622,7 +622,7 @@ echo "====================" # Step 1: Prioritize backlog echo "" echo "1. Feature Prioritization:" -python ../../product-team/product-manager-toolkit/scripts/rice_prioritizer.py backlog.csv --capacity $CAPACITY > $QUARTER-roadmap.txt +python ../../product-team/skills/product-manager-toolkit/scripts/rice_prioritizer.py backlog.csv --capacity $CAPACITY > $QUARTER-roadmap.txt # Step 2: Extract quick wins echo "" @@ -676,7 +676,7 @@ echo "Report: $QUARTER-roadmap.txt" ## References -- **Skill Documentation:** [../../product-team/product-manager-toolkit/SKILL.md](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/product-manager-toolkit/SKILL.md) +- **Skill Documentation:** [../../product-team/skills/product-manager-toolkit/SKILL.md](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/skills/product-manager-toolkit/SKILL.md) - **Product Domain Guide:** [../../product-team/CLAUDE.md](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/CLAUDE.md) - **Agent Development Guide:** [../CLAUDE.md](https://github.com/alirezarezvani/claude-skills/tree/main/agents/CLAUDE.md) diff --git a/docs/agents/cs-product-strategist.md b/docs/agents/cs-product-strategist.md index 1d7f59ec..39e9d66a 100644 --- a/docs/agents/cs-product-strategist.md +++ b/docs/agents/cs-product-strategist.md @@ -1,6 +1,6 @@ --- title: "Product Strategist Agent — AI Coding Agent & Codex Skill" -description: "Product strategy agent for quarterly OKR planning, competitive landscape analysis, product vision development, and strategy pivot evaluation. Agent-native orchestrator for Claude Code, Codex, Gemini CLI." +description: "Product strategy agent for quarterly OKR planning, competitive landscape analysis, product vision development, and strategy pivot evaluation. Use. Agent-native orchestrator for Claude Code, Codex, Gemini CLI." --- # Product Strategist Agent @@ -22,74 +22,74 @@ The cs-product-strategist agent operates at the intersection of business strateg ## Skill Integration -**Primary Skill:** [`product-team/product-strategist`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/product-strategist) +**Primary Skill:** [`skills/product-strategist`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/skills/product-strategist) ### All Orchestrated Skills | # | Skill | Location | Primary Tool | |---|-------|----------|-------------| -| 1 | Product Strategist | [`product-team/product-strategist`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/product-strategist) | okr_cascade_generator.py | -| 2 | Competitive Teardown | [`product-team/competitive-teardown`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/competitive-teardown) | competitive_matrix_builder.py | -| 3 | Product Manager Toolkit | [`product-team/product-manager-toolkit`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/product-manager-toolkit) | rice_prioritizer.py | +| 1 | Product Strategist | [`skills/product-strategist`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/skills/product-strategist) | okr_cascade_generator.py | +| 2 | Competitive Teardown | [`skills/competitive-teardown`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/skills/competitive-teardown) | competitive_matrix_builder.py | +| 3 | Product Manager Toolkit | [`skills/product-manager-toolkit`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/skills/product-manager-toolkit) | rice_prioritizer.py | ### Python Tools 1. **OKR Cascade Generator** - **Purpose:** Generate cascaded OKRs from company objectives to team-level key results with initiative mapping - - **Path:** [`scripts/okr_cascade_generator.py`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/product-strategist/scripts/okr_cascade_generator.py) - - **Usage:** `python ../../product-team/product-strategist/scripts/okr_cascade_generator.py growth` + - **Path:** [`scripts/okr_cascade_generator.py`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/skills/product-strategist/scripts/okr_cascade_generator.py) + - **Usage:** `python ../../product-team/skills/product-strategist/scripts/okr_cascade_generator.py growth` - **Features:** Multi-level cascade (company > product > team), initiative mapping, scoring framework, tracking cadence - **Use Cases:** Quarterly planning, strategic alignment, goal setting, annual planning 2. **Competitive Matrix Builder** - **Purpose:** Build competitive analysis matrices, feature comparison grids, and positioning maps - - **Path:** [`scripts/competitive_matrix_builder.py`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/competitive-teardown/scripts/competitive_matrix_builder.py) - - **Usage:** `python ../../product-team/competitive-teardown/scripts/competitive_matrix_builder.py competitors.csv` + - **Path:** [`scripts/competitive_matrix_builder.py`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/skills/competitive-teardown/scripts/competitive_matrix_builder.py) + - **Usage:** `python ../../product-team/skills/competitive-teardown/scripts/competitive_matrix_builder.py competitors.csv` - **Features:** Multi-dimensional scoring, weighted comparison, gap analysis, positioning visualization - **Use Cases:** Competitive intelligence, market positioning, feature gap analysis, strategic differentiation 3. **RICE Prioritizer** - **Purpose:** Strategic initiative prioritization using RICE framework for portfolio-level decisions - - **Path:** [`scripts/rice_prioritizer.py`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/product-manager-toolkit/scripts/rice_prioritizer.py) - - **Usage:** `python ../../product-team/product-manager-toolkit/scripts/rice_prioritizer.py initiatives.csv --capacity 50` + - **Path:** [`scripts/rice_prioritizer.py`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/skills/product-manager-toolkit/scripts/rice_prioritizer.py) + - **Usage:** `python ../../product-team/skills/product-manager-toolkit/scripts/rice_prioritizer.py initiatives.csv --capacity 50` - **Features:** Portfolio quadrant analysis (big bets, quick wins), capacity planning, strategic roadmap generation - **Use Cases:** Initiative prioritization, resource allocation, strategic portfolio management ### Knowledge Bases 1. **OKR Framework** - - **Location:** [`references/okr_framework.md`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/product-strategist/references/okr_framework.md) + - **Location:** [`references/okr_framework.md`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/skills/product-strategist/references/okr_framework.md) - **Content:** OKR methodology, cascade patterns, scoring guidelines, common pitfalls - **Use Case:** OKR education, quarterly planning preparation 2. **Strategy Types** - - **Location:** [`references/strategy_types.md`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/product-strategist/references/strategy_types.md) + - **Location:** [`references/strategy_types.md`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/skills/product-strategist/references/strategy_types.md) - **Content:** Product strategy frameworks, competitive positioning models, growth strategies - **Use Case:** Strategy formulation, market analysis, product vision development 3. **Data Collection Guide** - - **Location:** [`references/data-collection-guide.md`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/competitive-teardown/references/data-collection-guide.md) + - **Location:** [`references/data-collection-guide.md`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/skills/competitive-teardown/references/data-collection-guide.md) - **Content:** Sources and methods for gathering competitive intelligence ethically - **Use Case:** Competitive research planning, data source identification 4. **Scoring Rubric** - - **Location:** [`references/scoring-rubric.md`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/competitive-teardown/references/scoring-rubric.md) + - **Location:** [`references/scoring-rubric.md`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/skills/competitive-teardown/references/scoring-rubric.md) - **Content:** Standardized scoring criteria for competitive dimensions (1-10 scale) - **Use Case:** Consistent competitor evaluation, bias mitigation 5. **Analysis Templates** - - **Location:** [`references/analysis-templates.md`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/competitive-teardown/references/analysis-templates.md) + - **Location:** [`references/analysis-templates.md`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/skills/competitive-teardown/references/analysis-templates.md) - **Content:** SWOT, Porter's Five Forces, positioning maps, battle cards, win/loss analysis - **Use Case:** Structured competitive analysis, sales enablement ### Templates 1. **OKR Template** - - **Location:** [`assets/okr_template.md`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/product-strategist/assets/okr_template.md) + - **Location:** [`assets/okr_template.md`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/skills/product-strategist/assets/okr_template.md) - **Use Case:** Quarterly OKR documentation with tracking structure 2. **PRD Template** - - **Location:** [`assets/prd_template.md`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/product-manager-toolkit/assets/prd_template.md) + - **Location:** [`assets/prd_template.md`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/skills/product-manager-toolkit/assets/prd_template.md) - **Use Case:** Documenting strategic initiatives as formal requirements ## Workflows @@ -108,7 +108,7 @@ The cs-product-strategist agent operates at the intersection of business strateg 2. **Analyze Market Context** - Understand external factors: ```bash # Build competitive landscape - python ../../product-team/competitive-teardown/scripts/competitive_matrix_builder.py competitors.csv + python ../../product-team/skills/competitive-teardown/scripts/competitive_matrix_builder.py competitors.csv ``` - Review competitive movements from past quarter - Identify market trends and opportunities @@ -117,7 +117,7 @@ The cs-product-strategist agent operates at the intersection of business strateg 3. **Generate OKR Cascade** - Create aligned objectives: ```bash # Generate OKRs for growth strategy - python ../../product-team/product-strategist/scripts/okr_cascade_generator.py growth + python ../../product-team/skills/product-strategist/scripts/okr_cascade_generator.py growth ``` 4. **Define Product Objectives** - Set 2-3 product objectives: @@ -133,7 +133,7 @@ The cs-product-strategist agent operates at the intersection of business strateg 6. **Map Initiatives to KRs** - Connect work to outcomes: ```bash # Prioritize strategic initiatives - python ../../product-team/product-manager-toolkit/scripts/rice_prioritizer.py initiatives.csv --capacity 50 + python ../../product-team/skills/product-manager-toolkit/scripts/rice_prioritizer.py initiatives.csv --capacity 50 ``` 7. **Stakeholder Alignment** - Present and iterate: @@ -143,7 +143,7 @@ The cs-product-strategist agent operates at the intersection of business strateg 8. **Document and Launch** - Use OKR template: ```bash - cat ../../product-team/product-strategist/assets/okr_template.md + cat ../../product-team/skills/product-strategist/assets/okr_template.md ``` **Expected Output:** Quarterly OKR document with 2-3 objectives, 8-12 key results, mapped initiatives, and stakeholder alignment @@ -157,16 +157,16 @@ echo "Q3 2026 OKR Planning" echo "====================" # Step 1: Competitive context -python ../../product-team/competitive-teardown/scripts/competitive_matrix_builder.py q3-competitors.csv +python ../../product-team/skills/competitive-teardown/scripts/competitive_matrix_builder.py q3-competitors.csv # Step 2: Generate OKR cascade -python ../../product-team/product-strategist/scripts/okr_cascade_generator.py growth +python ../../product-team/skills/product-strategist/scripts/okr_cascade_generator.py growth # Step 3: Prioritize initiatives -python ../../product-team/product-manager-toolkit/scripts/rice_prioritizer.py q3-initiatives.csv --capacity 45 +python ../../product-team/skills/product-manager-toolkit/scripts/rice_prioritizer.py q3-initiatives.csv --capacity 45 # Step 4: Review OKR template -cat ../../product-team/product-strategist/assets/okr_template.md +cat ../../product-team/skills/product-strategist/assets/okr_template.md ``` ### Workflow 2: Competitive Landscape Review @@ -181,7 +181,7 @@ cat ../../product-team/product-strategist/assets/okr_template.md 2. **Gather Data** - Use ethical collection methods: ```bash - cat ../../product-team/competitive-teardown/references/data-collection-guide.md + cat ../../product-team/skills/competitive-teardown/references/data-collection-guide.md ``` - Public sources: G2, Capterra, pricing pages, changelogs - Market reports: Gartner, Forrester, analyst briefings @@ -189,7 +189,7 @@ cat ../../product-team/product-strategist/assets/okr_template.md 3. **Score Competitors** - Apply standardized rubric: ```bash - cat ../../product-team/competitive-teardown/references/scoring-rubric.md + cat ../../product-team/skills/competitive-teardown/references/scoring-rubric.md ``` - Score across 7 dimensions (UX, features, pricing, integrations, support, performance, security) - Use multiple scorers to reduce bias @@ -197,7 +197,7 @@ cat ../../product-team/product-strategist/assets/okr_template.md 4. **Build Competitive Matrix** - Generate comparison: ```bash - python ../../product-team/competitive-teardown/scripts/competitive_matrix_builder.py competitors-scored.csv + python ../../product-team/skills/competitive-teardown/scripts/competitive_matrix_builder.py competitors-scored.csv ``` 5. **Identify Gaps and Opportunities** - Analyze the matrix: @@ -207,7 +207,7 @@ cat ../../product-team/product-strategist/assets/okr_template.md 6. **Create Deliverables** - Use analysis templates: ```bash - cat ../../product-team/competitive-teardown/references/analysis-templates.md + cat ../../product-team/skills/competitive-teardown/references/analysis-templates.md ``` - SWOT analysis per major competitor - Positioning map (2x2) @@ -229,7 +229,7 @@ Competitor B,9,6,8,5,8,6,6 Competitor C,5,9,5,7,5,8,9 EOF -python ../../product-team/competitive-teardown/scripts/competitive_matrix_builder.py competitors.csv +python ../../product-team/skills/competitive-teardown/scripts/competitive_matrix_builder.py competitors.csv ``` ### Workflow 3: Product Vision Document @@ -253,7 +253,7 @@ python ../../product-team/competitive-teardown/scripts/competitive_matrix_builde 3. **Map the Strategy** - Connect vision to execution: ```bash # Review strategy frameworks - cat ../../product-team/product-strategist/references/strategy_types.md + cat ../../product-team/skills/product-strategist/references/strategy_types.md ``` - Choose strategic posture (category leader, disruptor, fast follower) - Define competitive moats (technology, network effects, data, brand) @@ -295,7 +295,7 @@ python ../../product-team/competitive-teardown/scripts/competitive_matrix_builde 2. **Quantify Current Performance** - Baseline analysis: ```bash # Assess current initiative portfolio - python ../../product-team/product-manager-toolkit/scripts/rice_prioritizer.py current-initiatives.csv + python ../../product-team/skills/product-manager-toolkit/scripts/rice_prioritizer.py current-initiatives.csv ``` - Revenue trajectory and unit economics - Customer acquisition cost trends @@ -313,7 +313,7 @@ python ../../product-team/competitive-teardown/scripts/competitive_matrix_builde 4. **Score Each Option** - Structured evaluation: ```bash # Build comparison matrix for pivot options - python ../../product-team/competitive-teardown/scripts/competitive_matrix_builder.py pivot-options.csv + python ../../product-team/skills/competitive-teardown/scripts/competitive_matrix_builder.py pivot-options.csv ``` - Market size and growth potential - Competitive intensity in new direction @@ -330,7 +330,7 @@ python ../../product-team/competitive-teardown/scripts/competitive_matrix_builde 6. **Set Pivot OKRs** - Define success for the new direction: ```bash - python ../../product-team/product-strategist/scripts/okr_cascade_generator.py pivot + python ../../product-team/skills/product-strategist/scripts/okr_cascade_generator.py pivot ``` **Expected Output:** Pivot analysis document with current state assessment, option evaluation, recommended path, transition plan, and pivot-specific OKRs @@ -348,10 +348,10 @@ Problem Pivot to Workflow,8,6,7,5,6 Technology Pivot to AI-Native,9,4,8,4,7 EOF -python ../../product-team/competitive-teardown/scripts/competitive_matrix_builder.py pivot-options.csv +python ../../product-team/skills/competitive-teardown/scripts/competitive_matrix_builder.py pivot-options.csv # Generate OKRs for recommended pivot direction -python ../../product-team/product-strategist/scripts/okr_cascade_generator.py growth +python ../../product-team/skills/product-strategist/scripts/okr_cascade_generator.py growth ``` ## Integration Examples @@ -370,22 +370,22 @@ echo "================================" # Competitive landscape echo "" echo "1. Competitive Analysis:" -python ../../product-team/competitive-teardown/scripts/competitive_matrix_builder.py annual-competitors.csv +python ../../product-team/skills/competitive-teardown/scripts/competitive_matrix_builder.py annual-competitors.csv # Strategy reference echo "" echo "2. Strategy Frameworks:" -cat ../../product-team/product-strategist/references/strategy_types.md | head -50 +cat ../../product-team/skills/product-strategist/references/strategy_types.md | head -50 # Annual OKR cascade echo "" echo "3. Annual OKR Cascade:" -python ../../product-team/product-strategist/scripts/okr_cascade_generator.py growth +python ../../product-team/skills/product-strategist/scripts/okr_cascade_generator.py growth # Initiative prioritization echo "" echo "4. Strategic Initiative Prioritization:" -python ../../product-team/product-manager-toolkit/scripts/rice_prioritizer.py annual-initiatives.csv --capacity 180 +python ../../product-team/skills/product-manager-toolkit/scripts/rice_prioritizer.py annual-initiatives.csv --capacity 180 ``` ### Example 2: Monthly Strategy Review @@ -400,17 +400,17 @@ echo "============================================" # Competitive movements echo "" echo "Competitive Updates:" -echo "Review: ../../product-team/competitive-teardown/references/data-collection-guide.md" +echo "Review: ../../product-team/skills/competitive-teardown/references/data-collection-guide.md" # OKR progress echo "" echo "OKR Progress:" -echo "Review: ../../product-team/product-strategist/assets/okr_template.md" +echo "Review: ../../product-team/skills/product-strategist/assets/okr_template.md" # Initiative status echo "" echo "Initiative Portfolio:" -python ../../product-team/product-manager-toolkit/scripts/rice_prioritizer.py current-initiatives.csv +python ../../product-team/skills/product-manager-toolkit/scripts/rice_prioritizer.py current-initiatives.csv ``` ### Example 3: Board Preparation @@ -427,17 +427,17 @@ echo "=============================" # Strategic metrics echo "" echo "1. Product Strategy Performance:" -python ../../product-team/product-manager-toolkit/scripts/rice_prioritizer.py $QUARTER-delivered.csv +python ../../product-team/skills/product-manager-toolkit/scripts/rice_prioritizer.py $QUARTER-delivered.csv # Competitive position echo "" echo "2. Competitive Positioning:" -python ../../product-team/competitive-teardown/scripts/competitive_matrix_builder.py board-competitors.csv +python ../../product-team/skills/competitive-teardown/scripts/competitive_matrix_builder.py board-competitors.csv # Next quarter OKRs echo "" echo "3. Next Quarter OKR Proposal:" -python ../../product-team/product-strategist/scripts/okr_cascade_generator.py growth +python ../../product-team/skills/product-strategist/scripts/okr_cascade_generator.py growth ``` ## Success Metrics @@ -472,14 +472,14 @@ python ../../product-team/product-strategist/scripts/okr_cascade_generator.py gr - [cs-agile-product-owner](cs-agile-product-owner.md) - Sprint-level planning and backlog management - [cs-ux-researcher](cs-ux-researcher.md) - User research to validate strategic assumptions - [cs-ceo-advisor](https://github.com/alirezarezvani/claude-skills/tree/main/agents/c-level/cs-ceo-advisor.md) - Company-level strategic alignment -- Senior PM Skill - Portfolio context (see [`project-management/senior-pm`](https://github.com/alirezarezvani/claude-skills/tree/main/project-management/senior-pm)) +- Senior PM Skill - Portfolio context (see [`skills/senior-pm`](https://github.com/alirezarezvani/claude-skills/tree/main/project-management/skills/senior-pm)) ## References -- **Primary Skill:** [../../product-team/product-strategist/SKILL.md](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/product-strategist/SKILL.md) -- **Competitive Teardown Skill:** [../../product-team/competitive-teardown/SKILL.md](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/competitive-teardown/SKILL.md) -- **OKR Framework:** [../../product-team/product-strategist/references/okr_framework.md](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/product-strategist/references/okr_framework.md) -- **Strategy Types:** [../../product-team/product-strategist/references/strategy_types.md](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/product-strategist/references/strategy_types.md) +- **Primary Skill:** [../../product-team/skills/product-strategist/SKILL.md](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/skills/product-strategist/SKILL.md) +- **Competitive Teardown Skill:** [../../product-team/skills/competitive-teardown/SKILL.md](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/skills/competitive-teardown/SKILL.md) +- **OKR Framework:** [../../product-team/skills/product-strategist/references/okr_framework.md](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/skills/product-strategist/references/okr_framework.md) +- **Strategy Types:** [../../product-team/skills/product-strategist/references/strategy_types.md](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/skills/product-strategist/references/strategy_types.md) - **Product Domain Guide:** [../../product-team/CLAUDE.md](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/CLAUDE.md) - **Agent Development Guide:** [../CLAUDE.md](https://github.com/alirezarezvani/claude-skills/tree/main/agents/CLAUDE.md) diff --git a/docs/agents/cs-project-manager.md b/docs/agents/cs-project-manager.md index e5906924..77daf37a 100644 --- a/docs/agents/cs-project-manager.md +++ b/docs/agents/cs-project-manager.md @@ -24,103 +24,103 @@ The cs-project-manager agent bridges the gap between project execution and strat ### Senior PM -**Skill Location:** [`project-management/senior-pm`](https://github.com/alirezarezvani/claude-skills/tree/main/project-management/senior-pm) +**Skill Location:** [`skills/senior-pm`](https://github.com/alirezarezvani/claude-skills/tree/main/project-management/skills/senior-pm) **Python Tools:** 1. **Project Health Dashboard** - **Purpose:** Generate portfolio-level health dashboard with RAG status across all active projects - - **Path:** [`scripts/project_health_dashboard.py`](https://github.com/alirezarezvani/claude-skills/tree/main/project-management/senior-pm/scripts/project_health_dashboard.py) - - **Usage:** `python ../../project-management/senior-pm/scripts/project_health_dashboard.py sample_project_data.json` + - **Path:** [`scripts/project_health_dashboard.py`](https://github.com/alirezarezvani/claude-skills/tree/main/project-management/skills/senior-pm/scripts/project_health_dashboard.py) + - **Usage:** `python ../../project-management/skills/senior-pm/scripts/project_health_dashboard.py sample_project_data.json` - **Features:** Schedule variance, budget tracking, risk exposure, milestone status, RAG indicators 2. **Risk Matrix Analyzer** - **Purpose:** Quantitative risk analysis with probability-impact matrices and Expected Monetary Value (EMV) - - **Path:** [`scripts/risk_matrix_analyzer.py`](https://github.com/alirezarezvani/claude-skills/tree/main/project-management/senior-pm/scripts/risk_matrix_analyzer.py) - - **Usage:** `python ../../project-management/senior-pm/scripts/risk_matrix_analyzer.py risks.json` + - **Path:** [`scripts/risk_matrix_analyzer.py`](https://github.com/alirezarezvani/claude-skills/tree/main/project-management/skills/senior-pm/scripts/risk_matrix_analyzer.py) + - **Usage:** `python ../../project-management/skills/senior-pm/scripts/risk_matrix_analyzer.py risks.json` - **Features:** Risk scoring, heat map generation, mitigation tracking, EMV calculation 3. **Resource Capacity Planner** - **Purpose:** Team resource allocation and capacity forecasting across sprints and projects - - **Path:** [`scripts/resource_capacity_planner.py`](https://github.com/alirezarezvani/claude-skills/tree/main/project-management/senior-pm/scripts/resource_capacity_planner.py) - - **Usage:** `python ../../project-management/senior-pm/scripts/resource_capacity_planner.py team_data.json` + - **Path:** [`scripts/resource_capacity_planner.py`](https://github.com/alirezarezvani/claude-skills/tree/main/project-management/skills/senior-pm/scripts/resource_capacity_planner.py) + - **Usage:** `python ../../project-management/skills/senior-pm/scripts/resource_capacity_planner.py team_data.json` - **Features:** Utilization analysis, over-allocation detection, capacity forecasting, cross-project balancing **Knowledge Bases:** -- [`references/portfolio-prioritization-models.md`](https://github.com/alirezarezvani/claude-skills/tree/main/project-management/senior-pm/references/portfolio-prioritization-models.md) -- WSJF, MoSCoW, Cost of Delay, portfolio scoring frameworks -- [`references/risk-management-framework.md`](https://github.com/alirezarezvani/claude-skills/tree/main/project-management/senior-pm/references/risk-management-framework.md) -- Risk identification, qualitative/quantitative analysis, response strategies -- [`references/portfolio-kpis.md`](https://github.com/alirezarezvani/claude-skills/tree/main/project-management/senior-pm/references/portfolio-kpis.md) -- KPI definitions, tracking cadences, executive reporting metrics +- [`references/portfolio-prioritization-models.md`](https://github.com/alirezarezvani/claude-skills/tree/main/project-management/skills/senior-pm/references/portfolio-prioritization-models.md) -- WSJF, MoSCoW, Cost of Delay, portfolio scoring frameworks +- [`references/risk-management-framework.md`](https://github.com/alirezarezvani/claude-skills/tree/main/project-management/skills/senior-pm/references/risk-management-framework.md) -- Risk identification, qualitative/quantitative analysis, response strategies +- [`references/portfolio-kpis.md`](https://github.com/alirezarezvani/claude-skills/tree/main/project-management/skills/senior-pm/references/portfolio-kpis.md) -- KPI definitions, tracking cadences, executive reporting metrics **Templates:** -- [`assets/executive_report_template.md`](https://github.com/alirezarezvani/claude-skills/tree/main/project-management/senior-pm/assets/executive_report_template.md) -- Executive status report with RAG, risks, decisions needed -- [`assets/project_charter_template.md`](https://github.com/alirezarezvani/claude-skills/tree/main/project-management/senior-pm/assets/project_charter_template.md) -- Project charter with scope, objectives, constraints, stakeholders -- [`assets/raci_matrix_template.md`](https://github.com/alirezarezvani/claude-skills/tree/main/project-management/senior-pm/assets/raci_matrix_template.md) -- Responsibility assignment matrix for cross-functional teams +- [`assets/executive_report_template.md`](https://github.com/alirezarezvani/claude-skills/tree/main/project-management/skills/senior-pm/assets/executive_report_template.md) -- Executive status report with RAG, risks, decisions needed +- [`assets/project_charter_template.md`](https://github.com/alirezarezvani/claude-skills/tree/main/project-management/skills/senior-pm/assets/project_charter_template.md) -- Project charter with scope, objectives, constraints, stakeholders +- [`assets/raci_matrix_template.md`](https://github.com/alirezarezvani/claude-skills/tree/main/project-management/skills/senior-pm/assets/raci_matrix_template.md) -- Responsibility assignment matrix for cross-functional teams ### Scrum Master -**Skill Location:** [`project-management/scrum-master`](https://github.com/alirezarezvani/claude-skills/tree/main/project-management/scrum-master) +**Skill Location:** [`skills/scrum-master`](https://github.com/alirezarezvani/claude-skills/tree/main/project-management/skills/scrum-master) **Python Tools:** 1. **Sprint Health Scorer** - **Purpose:** Quantitative sprint health assessment across scope, velocity, quality, and team morale - - **Path:** [`scripts/sprint_health_scorer.py`](https://github.com/alirezarezvani/claude-skills/tree/main/project-management/scrum-master/scripts/sprint_health_scorer.py) - - **Usage:** `python ../../project-management/scrum-master/scripts/sprint_health_scorer.py sample_sprint_data.json` + - **Path:** [`scripts/sprint_health_scorer.py`](https://github.com/alirezarezvani/claude-skills/tree/main/project-management/skills/scrum-master/scripts/sprint_health_scorer.py) + - **Usage:** `python ../../project-management/skills/scrum-master/scripts/sprint_health_scorer.py sample_sprint_data.json` - **Features:** Multi-dimensional scoring (0-100), trend analysis, health indicators, actionable recommendations 2. **Velocity Analyzer** - **Purpose:** Historical velocity analysis with forecasting and confidence intervals - - **Path:** [`scripts/velocity_analyzer.py`](https://github.com/alirezarezvani/claude-skills/tree/main/project-management/scrum-master/scripts/velocity_analyzer.py) - - **Usage:** `python ../../project-management/scrum-master/scripts/velocity_analyzer.py sprint_history.json` + - **Path:** [`scripts/velocity_analyzer.py`](https://github.com/alirezarezvani/claude-skills/tree/main/project-management/skills/scrum-master/scripts/velocity_analyzer.py) + - **Usage:** `python ../../project-management/skills/scrum-master/scripts/velocity_analyzer.py sprint_history.json` - **Features:** Rolling averages, standard deviation, sprint-over-sprint trends, capacity prediction 3. **Retrospective Analyzer** - **Purpose:** Structured retrospective analysis with action item tracking and theme extraction - - **Path:** [`scripts/retrospective_analyzer.py`](https://github.com/alirezarezvani/claude-skills/tree/main/project-management/scrum-master/scripts/retrospective_analyzer.py) - - **Usage:** `python ../../project-management/scrum-master/scripts/retrospective_analyzer.py retro_notes.json` + - **Path:** [`scripts/retrospective_analyzer.py`](https://github.com/alirezarezvani/claude-skills/tree/main/project-management/skills/scrum-master/scripts/retrospective_analyzer.py) + - **Usage:** `python ../../project-management/skills/scrum-master/scripts/retrospective_analyzer.py retro_notes.json` - **Features:** Theme clustering, sentiment analysis, action item extraction, trend tracking across sprints **Knowledge Bases:** -- [`references/retro-formats.md`](https://github.com/alirezarezvani/claude-skills/tree/main/project-management/scrum-master/references/retro-formats.md) -- Start/Stop/Continue, 4Ls, Sailboat, Mad/Sad/Glad, Starfish formats -- [`references/team-dynamics-framework.md`](https://github.com/alirezarezvani/claude-skills/tree/main/project-management/scrum-master/references/team-dynamics-framework.md) -- Tuckman stages, psychological safety, conflict resolution -- [`references/velocity-forecasting-guide.md`](https://github.com/alirezarezvani/claude-skills/tree/main/project-management/scrum-master/references/velocity-forecasting-guide.md) -- Monte Carlo simulation, confidence ranges, capacity planning +- [`references/retro-formats.md`](https://github.com/alirezarezvani/claude-skills/tree/main/project-management/skills/scrum-master/references/retro-formats.md) -- Start/Stop/Continue, 4Ls, Sailboat, Mad/Sad/Glad, Starfish formats +- [`references/team-dynamics-framework.md`](https://github.com/alirezarezvani/claude-skills/tree/main/project-management/skills/scrum-master/references/team-dynamics-framework.md) -- Tuckman stages, psychological safety, conflict resolution +- [`references/velocity-forecasting-guide.md`](https://github.com/alirezarezvani/claude-skills/tree/main/project-management/skills/scrum-master/references/velocity-forecasting-guide.md) -- Monte Carlo simulation, confidence ranges, capacity planning **Templates:** -- [`assets/sprint_report_template.md`](https://github.com/alirezarezvani/claude-skills/tree/main/project-management/scrum-master/assets/sprint_report_template.md) -- Sprint review report with burndown, velocity, demo notes -- [`assets/team_health_check_template.md`](https://github.com/alirezarezvani/claude-skills/tree/main/project-management/scrum-master/assets/team_health_check_template.md) -- Spotify-style team health check across 8 dimensions +- [`assets/sprint_report_template.md`](https://github.com/alirezarezvani/claude-skills/tree/main/project-management/skills/scrum-master/assets/sprint_report_template.md) -- Sprint review report with burndown, velocity, demo notes +- [`assets/team_health_check_template.md`](https://github.com/alirezarezvani/claude-skills/tree/main/project-management/skills/scrum-master/assets/team_health_check_template.md) -- Spotify-style team health check across 8 dimensions ### Jira Expert -**Skill Location:** [`project-management/jira-expert`](https://github.com/alirezarezvani/claude-skills/tree/main/project-management/jira-expert) +**Skill Location:** [`skills/jira-expert`](https://github.com/alirezarezvani/claude-skills/tree/main/project-management/skills/jira-expert) **Knowledge Bases:** -- [`references/jql-examples.md`](https://github.com/alirezarezvani/claude-skills/tree/main/project-management/jira-expert/references/jql-examples.md) -- JQL query patterns for backlog grooming, sprint reporting, SLA tracking -- [`references/automation-examples.md`](https://github.com/alirezarezvani/claude-skills/tree/main/project-management/jira-expert/references/automation-examples.md) -- Jira automation rule templates for common workflows -- [`references/AUTOMATION.md`](https://github.com/alirezarezvani/claude-skills/tree/main/project-management/jira-expert/references/AUTOMATION.md) -- Comprehensive automation guide with triggers, conditions, actions -- [`references/WORKFLOWS.md`](https://github.com/alirezarezvani/claude-skills/tree/main/project-management/jira-expert/references/WORKFLOWS.md) -- Workflow design patterns, transition rules, validators, post-functions +- [`references/jql-examples.md`](https://github.com/alirezarezvani/claude-skills/tree/main/project-management/skills/jira-expert/references/jql-examples.md) -- JQL query patterns for backlog grooming, sprint reporting, SLA tracking +- [`references/automation-examples.md`](https://github.com/alirezarezvani/claude-skills/tree/main/project-management/skills/jira-expert/references/automation-examples.md) -- Jira automation rule templates for common workflows +- [`references/AUTOMATION.md`](https://github.com/alirezarezvani/claude-skills/tree/main/project-management/skills/jira-expert/references/AUTOMATION.md) -- Comprehensive automation guide with triggers, conditions, actions +- [`references/WORKFLOWS.md`](https://github.com/alirezarezvani/claude-skills/tree/main/project-management/skills/jira-expert/references/WORKFLOWS.md) -- Workflow design patterns, transition rules, validators, post-functions ### Confluence Expert -**Skill Location:** [`project-management/confluence-expert`](https://github.com/alirezarezvani/claude-skills/tree/main/project-management/confluence-expert) +**Skill Location:** [`skills/confluence-expert`](https://github.com/alirezarezvani/claude-skills/tree/main/project-management/skills/confluence-expert) **Knowledge Bases:** -- [`references/templates.md`](https://github.com/alirezarezvani/claude-skills/tree/main/project-management/confluence-expert/references/templates.md) -- Page templates for sprint plans, meeting notes, decision logs, architecture docs +- [`references/templates.md`](https://github.com/alirezarezvani/claude-skills/tree/main/project-management/skills/confluence-expert/references/templates.md) -- Page templates for sprint plans, meeting notes, decision logs, architecture docs ### Atlassian Admin -**Skill Location:** [`project-management/atlassian-admin`](https://github.com/alirezarezvani/claude-skills/tree/main/project-management/atlassian-admin) +**Skill Location:** [`skills/atlassian-admin`](https://github.com/alirezarezvani/claude-skills/tree/main/project-management/skills/atlassian-admin) Covers user provisioning, permission schemes, project configuration, and integration setup. No scripts or references yet -- relies on SKILL.md workflows. ### Atlassian Templates -**Skill Location:** [`project-management/atlassian-templates`](https://github.com/alirezarezvani/claude-skills/tree/main/project-management/atlassian-templates) +**Skill Location:** [`skills/atlassian-templates`](https://github.com/alirezarezvani/claude-skills/tree/main/project-management/skills/atlassian-templates) Covers blueprint creation, custom page layouts, and reusable Confluence/Jira components. No scripts or references yet -- relies on SKILL.md workflows. @@ -134,37 +134,37 @@ Covers blueprint creation, custom page layouts, and reusable Confluence/Jira com 1. **Analyze Velocity History** - Review past sprint performance to set realistic capacity: ```bash - python ../../project-management/scrum-master/scripts/velocity_analyzer.py sprint_history.json + python ../../project-management/skills/scrum-master/scripts/velocity_analyzer.py sprint_history.json ``` - Review rolling average velocity and standard deviation - Identify trends (accelerating, decelerating, stable) - Set sprint capacity at 80% of average velocity (buffer for unknowns) 2. **Query Backlog via JQL** - Use jira-expert JQL patterns to pull prioritized candidates: - - Reference: [`references/jql-examples.md`](https://github.com/alirezarezvani/claude-skills/tree/main/project-management/jira-expert/references/jql-examples.md) + - Reference: [`references/jql-examples.md`](https://github.com/alirezarezvani/claude-skills/tree/main/project-management/skills/jira-expert/references/jql-examples.md) - Filter by priority, story points estimated, team assignment - Identify blocked items, external dependencies, carry-overs from previous sprint 3. **Check Resource Availability** - Verify team capacity for the sprint window: ```bash - python ../../project-management/senior-pm/scripts/resource_capacity_planner.py team_data.json + python ../../project-management/skills/senior-pm/scripts/resource_capacity_planner.py team_data.json ``` - Account for PTO, holidays, shared resources - Flag over-allocated team members - Adjust sprint capacity based on actual availability 4. **Select Sprint Backlog** - Commit items within capacity: - - Apply WSJF or priority-based selection (ref: [`references/portfolio-prioritization-models.md`](https://github.com/alirezarezvani/claude-skills/tree/main/project-management/senior-pm/references/portfolio-prioritization-models.md)) + - Apply WSJF or priority-based selection (ref: [`references/portfolio-prioritization-models.md`](https://github.com/alirezarezvani/claude-skills/tree/main/project-management/skills/senior-pm/references/portfolio-prioritization-models.md)) - Ensure sprint goal alignment -- every item should contribute to 1-2 goals - Include 10-15% capacity for bug fixes and operational work 5. **Document Sprint Plan** - Create Confluence sprint plan page: - - Use template from [`references/templates.md`](https://github.com/alirezarezvani/claude-skills/tree/main/project-management/confluence-expert/references/templates.md) + - Use template from [`references/templates.md`](https://github.com/alirezarezvani/claude-skills/tree/main/project-management/skills/confluence-expert/references/templates.md) - Include sprint goal, committed stories, capacity breakdown, risks - Link to Jira sprint board for live tracking 6. **Set Up Sprint Tracking** - Configure dashboards and automation: - - Create burndown/burnup dashboard (ref: [`references/AUTOMATION.md`](https://github.com/alirezarezvani/claude-skills/tree/main/project-management/jira-expert/references/AUTOMATION.md)) + - Create burndown/burnup dashboard (ref: [`references/AUTOMATION.md`](https://github.com/alirezarezvani/claude-skills/tree/main/project-management/skills/jira-expert/references/AUTOMATION.md)) - Set up daily standup reminder automation - Configure sprint scope change alerts @@ -175,8 +175,8 @@ Covers blueprint creation, custom page layouts, and reusable Confluence/Jira com **Example:** ```bash # Full sprint planning workflow -python ../../project-management/scrum-master/scripts/velocity_analyzer.py sprint_history.json > velocity_report.txt -python ../../project-management/senior-pm/scripts/resource_capacity_planner.py team_data.json > capacity_report.txt +python ../../project-management/skills/scrum-master/scripts/velocity_analyzer.py sprint_history.json > velocity_report.txt +python ../../project-management/skills/senior-pm/scripts/resource_capacity_planner.py team_data.json > capacity_report.txt cat velocity_report.txt cat capacity_report.txt # Use velocity average and capacity data to commit sprint items @@ -196,7 +196,7 @@ cat capacity_report.txt 2. **Generate Health Dashboard** - Run project health analysis: ```bash - python ../../project-management/senior-pm/scripts/project_health_dashboard.py portfolio_data.json + python ../../project-management/skills/senior-pm/scripts/project_health_dashboard.py portfolio_data.json ``` - Review per-project RAG status (Red/Amber/Green) - Identify projects requiring intervention @@ -204,7 +204,7 @@ cat capacity_report.txt 3. **Analyze Risk Exposure** - Quantify portfolio-level risk: ```bash - python ../../project-management/senior-pm/scripts/risk_matrix_analyzer.py portfolio_risks.json + python ../../project-management/skills/senior-pm/scripts/risk_matrix_analyzer.py portfolio_risks.json ``` - Calculate EMV for each risk - Identify top-10 risks by exposure @@ -213,20 +213,20 @@ cat capacity_report.txt 4. **Review Resource Utilization** - Check cross-project allocation: ```bash - python ../../project-management/senior-pm/scripts/resource_capacity_planner.py all_teams.json + python ../../project-management/skills/senior-pm/scripts/resource_capacity_planner.py all_teams.json ``` - Identify over-allocated individuals (>100% utilization) - Find under-utilized capacity for rebalancing - Forecast resource needs for next quarter 5. **Prepare Executive Report** - Assemble findings into report: - - Use template: [`assets/executive_report_template.md`](https://github.com/alirezarezvani/claude-skills/tree/main/project-management/senior-pm/assets/executive_report_template.md) + - Use template: [`assets/executive_report_template.md`](https://github.com/alirezarezvani/claude-skills/tree/main/project-management/skills/senior-pm/assets/executive_report_template.md) - Include RAG summary, risk heatmap, resource utilization chart - Highlight decisions needed from leadership - Provide recommendations with supporting data 6. **Publish to Confluence** - Create executive dashboard page: - - Reference KPI definitions from [`references/portfolio-kpis.md`](https://github.com/alirezarezvani/claude-skills/tree/main/project-management/senior-pm/references/portfolio-kpis.md) + - Reference KPI definitions from [`references/portfolio-kpis.md`](https://github.com/alirezarezvani/claude-skills/tree/main/project-management/skills/senior-pm/references/portfolio-kpis.md) - Embed Jira macros for live data - Set up weekly refresh cadence @@ -237,9 +237,9 @@ cat capacity_report.txt **Example:** ```bash # Portfolio health review automation -python ../../project-management/senior-pm/scripts/project_health_dashboard.py portfolio_data.json > health_dashboard.txt -python ../../project-management/senior-pm/scripts/risk_matrix_analyzer.py portfolio_risks.json > risk_report.txt -python ../../project-management/senior-pm/scripts/resource_capacity_planner.py all_teams.json > resource_report.txt +python ../../project-management/skills/senior-pm/scripts/project_health_dashboard.py portfolio_data.json > health_dashboard.txt +python ../../project-management/skills/senior-pm/scripts/risk_matrix_analyzer.py portfolio_risks.json > risk_report.txt +python ../../project-management/skills/senior-pm/scripts/resource_capacity_planner.py all_teams.json > resource_report.txt cat health_dashboard.txt cat risk_report.txt cat resource_report.txt @@ -253,14 +253,14 @@ cat resource_report.txt 1. **Gather Sprint Metrics** - Collect quantitative data before the retro: ```bash - python ../../project-management/scrum-master/scripts/sprint_health_scorer.py sprint_data.json + python ../../project-management/skills/scrum-master/scripts/sprint_health_scorer.py sprint_data.json ``` - Review sprint health score (0-100) - Identify scoring dimensions that dropped (scope, velocity, quality, morale) - Compare against previous sprint scores for trend analysis 2. **Select Retro Format** - Choose format based on team needs: - - Reference: [`references/retro-formats.md`](https://github.com/alirezarezvani/claude-skills/tree/main/project-management/scrum-master/references/retro-formats.md) + - Reference: [`references/retro-formats.md`](https://github.com/alirezarezvani/claude-skills/tree/main/project-management/skills/scrum-master/references/retro-formats.md) - **Start/Stop/Continue**: General-purpose, good for new teams - **4Ls (Liked/Learned/Lacked/Longed For)**: Focuses on learning and growth - **Sailboat**: Visual metaphor for anchors (blockers) and wind (accelerators) @@ -271,11 +271,11 @@ cat resource_report.txt - Present sprint metrics as context (not judgment) - Time-box each section (5 min brainstorm, 10 min discuss, 5 min vote) - Use dot voting to prioritize discussion topics - - Reference team dynamics from [`references/team-dynamics-framework.md`](https://github.com/alirezarezvani/claude-skills/tree/main/project-management/scrum-master/references/team-dynamics-framework.md) + - Reference team dynamics from [`references/team-dynamics-framework.md`](https://github.com/alirezarezvani/claude-skills/tree/main/project-management/skills/scrum-master/references/team-dynamics-framework.md) 4. **Analyze Retro Output** - Extract structured insights: ```bash - python ../../project-management/scrum-master/scripts/retrospective_analyzer.py retro_notes.json + python ../../project-management/skills/scrum-master/scripts/retrospective_analyzer.py retro_notes.json ``` - Identify recurring themes across sprints - Cluster related items into improvement areas @@ -288,7 +288,7 @@ cat resource_report.txt - Add action items to next sprint backlog 6. **Document in Confluence** - Publish retro summary: - - Use sprint report template: [`assets/sprint_report_template.md`](https://github.com/alirezarezvani/claude-skills/tree/main/project-management/scrum-master/assets/sprint_report_template.md) + - Use sprint report template: [`assets/sprint_report_template.md`](https://github.com/alirezarezvani/claude-skills/tree/main/project-management/skills/scrum-master/assets/sprint_report_template.md) - Include sprint health score, retro themes, action items, metrics trends - Link to previous retro pages for longitudinal tracking @@ -304,11 +304,11 @@ cat resource_report.txt **Example:** ```bash # Pre-retro data collection -python ../../project-management/scrum-master/scripts/sprint_health_scorer.py sprint_data.json > health_score.txt -python ../../project-management/scrum-master/scripts/velocity_analyzer.py sprint_history.json > velocity_trend.txt +python ../../project-management/skills/scrum-master/scripts/sprint_health_scorer.py sprint_data.json > health_score.txt +python ../../project-management/skills/scrum-master/scripts/velocity_analyzer.py sprint_history.json > velocity_trend.txt cat health_score.txt # Use health score insights to guide retro discussion -python ../../project-management/scrum-master/scripts/retrospective_analyzer.py retro_notes.json > retro_analysis.txt +python ../../project-management/skills/scrum-master/scripts/retrospective_analyzer.py retro_notes.json > retro_analysis.txt cat retro_analysis.txt ``` @@ -331,22 +331,22 @@ cat retro_analysis.txt - Define priority scheme and SLA targets 3. **Design Workflows** - Build workflows matching team process: - - Reference: [`references/WORKFLOWS.md`](https://github.com/alirezarezvani/claude-skills/tree/main/project-management/jira-expert/references/WORKFLOWS.md) + - Reference: [`references/WORKFLOWS.md`](https://github.com/alirezarezvani/claude-skills/tree/main/project-management/skills/jira-expert/references/WORKFLOWS.md) - Map states: Backlog > Ready > In Progress > Review > QA > Done - Add transitions with conditions (e.g., assignee required for In Progress) - Configure validators (e.g., story points required before Done) - Set up post-functions (e.g., auto-assign reviewer, notify channel) 4. **Configure Automation** - Set up time-saving automation rules: - - Reference: [`references/AUTOMATION.md`](https://github.com/alirezarezvani/claude-skills/tree/main/project-management/jira-expert/references/AUTOMATION.md) - - Examples from: [`references/automation-examples.md`](https://github.com/alirezarezvani/claude-skills/tree/main/project-management/jira-expert/references/automation-examples.md) + - Reference: [`references/AUTOMATION.md`](https://github.com/alirezarezvani/claude-skills/tree/main/project-management/skills/jira-expert/references/AUTOMATION.md) + - Examples from: [`references/automation-examples.md`](https://github.com/alirezarezvani/claude-skills/tree/main/project-management/skills/jira-expert/references/automation-examples.md) - Auto-transition: Move to In Progress when branch created - Auto-assign: Rotate assignments based on workload - Notifications: Slack alerts for blocked items, SLA breaches - Cleanup: Auto-close stale items after 30 days 5. **Set Up Confluence Space** - Create team knowledge base: - - Reference: [`references/templates.md`](https://github.com/alirezarezvani/claude-skills/tree/main/project-management/confluence-expert/references/templates.md) + - Reference: [`references/templates.md`](https://github.com/alirezarezvani/claude-skills/tree/main/project-management/skills/confluence-expert/references/templates.md) - Create space with standard page hierarchy: - Home (team overview, quick links) - Sprint Plans (per-sprint documentation) @@ -360,7 +360,7 @@ cat retro_analysis.txt - Burndown/burnup chart gadget - Velocity chart for historical tracking - SLA compliance tracker - - Use JQL patterns from [`references/jql-examples.md`](https://github.com/alirezarezvani/claude-skills/tree/main/project-management/jira-expert/references/jql-examples.md) + - Use JQL patterns from [`references/jql-examples.md`](https://github.com/alirezarezvani/claude-skills/tree/main/project-management/skills/jira-expert/references/jql-examples.md) 7. **Onboard Team** - Walk team through the setup: - Document workflow rules and why they exist @@ -386,22 +386,22 @@ echo "============================================" # Sprint health assessment echo "" echo "Sprint Health:" -python ../../project-management/scrum-master/scripts/sprint_health_scorer.py current_sprint.json +python ../../project-management/skills/scrum-master/scripts/sprint_health_scorer.py current_sprint.json # Velocity trend echo "" echo "Velocity Trend:" -python ../../project-management/scrum-master/scripts/velocity_analyzer.py sprint_history.json +python ../../project-management/skills/scrum-master/scripts/velocity_analyzer.py sprint_history.json # Risk exposure echo "" echo "Active Risks:" -python ../../project-management/senior-pm/scripts/risk_matrix_analyzer.py active_risks.json +python ../../project-management/skills/senior-pm/scripts/risk_matrix_analyzer.py active_risks.json # Resource utilization echo "" echo "Team Capacity:" -python ../../project-management/senior-pm/scripts/resource_capacity_planner.py team_data.json +python ../../project-management/skills/senior-pm/scripts/resource_capacity_planner.py team_data.json ``` ### Example 2: Sprint Retrospective Pipeline @@ -417,19 +417,19 @@ echo "==========================================" # Step 1: Score sprint health echo "" echo "1. Sprint Health Score:" -python ../../project-management/scrum-master/scripts/sprint_health_scorer.py sprint_${SPRINT_NUM}.json > sprint_health.txt +python ../../project-management/skills/scrum-master/scripts/sprint_health_scorer.py sprint_${SPRINT_NUM}.json > sprint_health.txt cat sprint_health.txt # Step 2: Analyze velocity trend echo "" echo "2. Velocity Analysis:" -python ../../project-management/scrum-master/scripts/velocity_analyzer.py velocity_history.json > velocity.txt +python ../../project-management/skills/scrum-master/scripts/velocity_analyzer.py velocity_history.json > velocity.txt cat velocity.txt # Step 3: Process retro notes echo "" echo "3. Retrospective Themes:" -python ../../project-management/scrum-master/scripts/retrospective_analyzer.py retro_sprint_${SPRINT_NUM}.json > retro_analysis.txt +python ../../project-management/skills/scrum-master/scripts/retrospective_analyzer.py retro_sprint_${SPRINT_NUM}.json > retro_analysis.txt cat retro_analysis.txt echo "" @@ -449,24 +449,24 @@ echo "================================" # Project health across portfolio echo "" echo "Project Health (All Active):" -python ../../project-management/senior-pm/scripts/project_health_dashboard.py portfolio_$MONTH.json > dashboard.txt +python ../../project-management/skills/senior-pm/scripts/project_health_dashboard.py portfolio_$MONTH.json > dashboard.txt cat dashboard.txt # Risk heatmap echo "" echo "Risk Exposure Summary:" -python ../../project-management/senior-pm/scripts/risk_matrix_analyzer.py risks_$MONTH.json > risks.txt +python ../../project-management/skills/senior-pm/scripts/risk_matrix_analyzer.py risks_$MONTH.json > risks.txt cat risks.txt # Resource forecast echo "" echo "Resource Utilization:" -python ../../project-management/senior-pm/scripts/resource_capacity_planner.py resources_$MONTH.json > capacity.txt +python ../../project-management/skills/senior-pm/scripts/resource_capacity_planner.py resources_$MONTH.json > capacity.txt cat capacity.txt echo "" echo "Dashboard generated. Use executive_report_template.md to assemble final report." -echo "Template: ../../project-management/senior-pm/assets/executive_report_template.md" +echo "Template: ../../project-management/skills/senior-pm/assets/executive_report_template.md" ``` ## Success Metrics @@ -503,11 +503,11 @@ echo "Template: ../../project-management/senior-pm/assets/executive_report_templ ## References -- **Senior PM Skill:** [../../project-management/senior-pm/SKILL.md](https://github.com/alirezarezvani/claude-skills/tree/main/project-management/senior-pm/SKILL.md) -- **Scrum Master Skill:** [../../project-management/scrum-master/SKILL.md](https://github.com/alirezarezvani/claude-skills/tree/main/project-management/scrum-master/SKILL.md) -- **Jira Expert Skill:** [../../project-management/jira-expert/SKILL.md](https://github.com/alirezarezvani/claude-skills/tree/main/project-management/jira-expert/SKILL.md) -- **Confluence Expert Skill:** [../../project-management/confluence-expert/SKILL.md](https://github.com/alirezarezvani/claude-skills/tree/main/project-management/confluence-expert/SKILL.md) -- **Atlassian Admin Skill:** [../../project-management/atlassian-admin/SKILL.md](https://github.com/alirezarezvani/claude-skills/tree/main/project-management/atlassian-admin/SKILL.md) +- **Senior PM Skill:** [../../project-management/skills/senior-pm/SKILL.md](https://github.com/alirezarezvani/claude-skills/tree/main/project-management/skills/senior-pm/SKILL.md) +- **Scrum Master Skill:** [../../project-management/skills/scrum-master/SKILL.md](https://github.com/alirezarezvani/claude-skills/tree/main/project-management/skills/scrum-master/SKILL.md) +- **Jira Expert Skill:** [../../project-management/skills/jira-expert/SKILL.md](https://github.com/alirezarezvani/claude-skills/tree/main/project-management/skills/jira-expert/SKILL.md) +- **Confluence Expert Skill:** [../../project-management/skills/confluence-expert/SKILL.md](https://github.com/alirezarezvani/claude-skills/tree/main/project-management/skills/confluence-expert/SKILL.md) +- **Atlassian Admin Skill:** [../../project-management/skills/atlassian-admin/SKILL.md](https://github.com/alirezarezvani/claude-skills/tree/main/project-management/skills/atlassian-admin/SKILL.md) - **PM Domain Guide:** [../../project-management/CLAUDE.md](https://github.com/alirezarezvani/claude-skills/tree/main/project-management/CLAUDE.md) - **Agent Development Guide:** [../CLAUDE.md](https://github.com/alirezarezvani/claude-skills/tree/main/agents/CLAUDE.md) diff --git a/docs/agents/cs-pulse.md b/docs/agents/cs-pulse.md index f16be38f..44f835c7 100644 --- a/docs/agents/cs-pulse.md +++ b/docs/agents/cs-pulse.md @@ -36,7 +36,7 @@ Relentless on specificity, depth-first on the intake tree, graceful on platform The cs-pulse agent orchestrates the `pulse` skill across multi-source recency briefings: 1. **Grill-me intake (Q1 → Q4, dependency-ordered)** — topic, angle, window, scope. One at a time. Refuse vague answers. -2. **Pre-flight** — compute window timestamps with `scripts/time_window_calculator.py`, generate output slug with `scripts/topic_slug_generator.py`, start three-count audit with `scripts/citation_tracker.py`. +2. **Pre-flight** — compute window timestamps with `skills/pulse/scripts/time_window_calculator.py`, generate output slug with `skills/pulse/scripts/topic_slug_generator.py`, start three-count audit with `skills/pulse/scripts/citation_tracker.py`. 3. **Phases 1–3 in parallel** — Reddit (top + new), HN (Algolia stories + comments), Web (2–3 targeted queries). 1 q/sec per platform; sequential within. 4. **Phase 4 (optional)** — X/Twitter if available; skip with note otherwise. 5. **Synthesis** — cross-platform pattern detection (consensus, controversy, pain, excitement, gaps). @@ -187,9 +187,9 @@ python ../skills/pulse/scripts/citation_tracker.py --action close --session NAME ## Related Agents -- [cs-grill-master](https://github.com/alirezarezvani/claude-skills/tree/main/research/grill-me/agents/cs-grill-master.md) — plan-only grill (different domain) -- [cs-grill-with-docs](https://github.com/alirezarezvani/claude-skills/tree/main/research/grill-with-docs/agents/cs-grill-with-docs.md) — docs-anchored grill (different scope) -- [cs-capture](https://github.com/alirezarezvani/claude-skills/tree/main/research/capture/agents/cs-capture.md) — brain-dump organizer (different mode) +- [cs-grill-master](https://github.com/alirezarezvani/claude-skills/tree/main/engineering/grill-me/agents/cs-grill-master.md) — plan-only grill (different domain) +- [cs-grill-with-docs](https://github.com/alirezarezvani/claude-skills/tree/main/engineering/grill-with-docs/agents/cs-grill-with-docs.md) — docs-anchored grill (different scope) +- [cs-capture](https://github.com/alirezarezvani/claude-skills/tree/main/productivity/capture/agents/cs-capture.md) — brain-dump organizer (different mode) ## References diff --git a/docs/agents/cs-reflect.md b/docs/agents/cs-reflect.md index dff48439..123a6670 100644 --- a/docs/agents/cs-reflect.md +++ b/docs/agents/cs-reflect.md @@ -67,15 +67,15 @@ Differentiates from siblings: ### Python Tools (Stdlib) -1. **Bias Pattern Detector** — `scripts/bias_pattern_detector.py` — given conversation text, scan for patterns indicative of each of the 5 biases -2. **Conversation Depth Analyzer** — `scripts/conversation_depth_analyzer.py` — counts turns, detects implicit-trigger signals (10+ detail turns, frustration markers, repeated dead-ends) -3. **Directional Recommendation Validator** — `scripts/directional_recommendation_validator.py` — verifies output ends with Continue / Pivot / Pause + specific reasoning (not vague reassurance) +1. **Bias Pattern Detector** — `skills/reflect/scripts/bias_pattern_detector.py` — given conversation text, scan for patterns indicative of each of the 5 biases +2. **Conversation Depth Analyzer** — `skills/reflect/scripts/conversation_depth_analyzer.py` — counts turns, detects implicit-trigger signals (10+ detail turns, frustration markers, repeated dead-ends) +3. **Directional Recommendation Validator** — `skills/reflect/scripts/directional_recommendation_validator.py` — verifies output ends with Continue / Pivot / Pause + specific reasoning (not vague reassurance) ### Knowledge Bases -- `references/cognitive_bias_canon.md` — 5 biases + recognition cues (7+ sources) -- `references/honest_output_discipline.md` — anti-manufactured-problems framing (7+ sources) -- `references/conversation_reflection_practice.md` — Schön reflective-practice canon (7+ sources) +- `skills/reflect/references/cognitive_bias_canon.md` — 5 biases + recognition cues (7+ sources) +- `skills/reflect/references/honest_output_discipline.md` — anti-manufactured-problems framing (7+ sources) +- `skills/reflect/references/conversation_reflection_practice.md` — Schön reflective-practice canon (7+ sources) ## Related Agents diff --git a/docs/agents/cs-research-ops-orchestrator.md b/docs/agents/cs-research-ops-orchestrator.md index eab43f96..59c0bd5d 100644 --- a/docs/agents/cs-research-ops-orchestrator.md +++ b/docs/agents/cs-research-ops-orchestrator.md @@ -75,8 +75,8 @@ Hard outputs: ## Onboarding-first + autoresearch handoff -- **Onboarding-first.** When a user starts a fresh research workstream, point them at the relevant sub-skill's `scripts/onboard.py` before running its tools. Each skill has its own question set; answers persist to `~/.config/research-ops/<skill>.json` (or `./.research-ops/<skill>.json`) and pre-configure every tool. Treat customization as mandatory discipline — flag it when it's been skipped. -- **Autoresearch is opt-in and isolated.** Each sub-skill ships its own `scripts/ar_evaluator.py` bridging to `engineering/autoresearch-agent`. Invoke an autoresearch loop ONLY when the user explicitly asks to optimize / improve / run a loop. The connection is per-skill (no shared coupling): the loop edits the skill's input file; the evaluator is locked ground truth (never edited). Metrics: clinical `feasibility_composite` (↑), finance `runway_months` (↑), market `tam_divergence` (↓), product `validated_insights` (↑). +- **Onboarding-first.** When a user starts a fresh research workstream, point them at the relevant sub-skill's `skills/<sub-skill>/scripts/onboard.py` before running its tools. Each skill has its own question set; answers persist to `~/.config/research-ops/<skill>.json` (or `./.research-ops/<skill>.json`) and pre-configure every tool. Treat customization as mandatory discipline — flag it when it's been skipped. +- **Autoresearch is opt-in and isolated.** Each sub-skill ships its own `skills/<sub-skill>/scripts/ar_evaluator.py` bridging to `engineering/autoresearch-agent`. Invoke an autoresearch loop ONLY when the user explicitly asks to optimize / improve / run a loop. The connection is per-skill (no shared coupling): the loop edits the skill's input file; the evaluator is locked ground truth (never edited). Metrics: clinical `feasibility_composite` (↑), finance `runway_months` (↑), market `tam_divergence` (↓), product `validated_insights` (↑). ## When to escalate diff --git a/docs/agents/cs-research.md b/docs/agents/cs-research.md index c041ef19..8bbab56c 100644 --- a/docs/agents/cs-research.md +++ b/docs/agents/cs-research.md @@ -40,14 +40,14 @@ Router-first, transparency-mandatory, fallback-when-needed. The cs-research agent orchestrates the `research` skill as the **runtime orchestrator** for the research domain: 1. **Q1 + Q2 minimal intake** — question + output preference -2. **Deterministic classification** — run `scripts/classifier.py` on the question +2. **Deterministic classification** — run `skills/research/scripts/classifier.py` on the question 3. **Route**: - **≥2 signals for one specialist** → delegate (with transparency) - **1 signal, single specialist** → weak match, delegate (with transparency) - **Otherwise** → ask Q3 disambiguation 4. **Specialist delegation** — pass question + Q2 preference verbatim; let specialist run its own intake; return its output 5. **Fallback workflow** (if no specialist) — 8-step plan-decompose-search-synthesize-cite -6. **Log routing decision** to `scripts/routing_transparency_logger.py` for audit +6. **Log routing decision** to `skills/research/scripts/routing_transparency_logger.py` for audit Differentiates from siblings: @@ -56,7 +56,7 @@ Differentiates from siblings: **Hard rules:** -1. **Deterministic classification.** Use `scripts/classifier.py` — keyword + intent signal matching, NOT LLM-reasoned routing. +1. **Deterministic classification.** Use `skills/research/scripts/classifier.py` — keyword + intent signal matching, NOT LLM-reasoned routing. 2. **Routing transparency mandatory.** Never delegate silently. Surface decision + accept override. 3. **Specialist delegation = pass-through.** Pass question verbatim. Don't pre-answer specialist's grill-me intake. 4. **Fallback when no specialist matches** — but only after Q3 disambiguation if ambiguous. @@ -71,15 +71,15 @@ Differentiates from siblings: ### Python Tools (Stdlib) -1. **Classifier** — `scripts/classifier.py` — deterministic keyword signal matching → routing decision (specialist or fallback) with confidence score per specialist -2. **Routing Transparency Logger** — `scripts/routing_transparency_logger.py` — JSON-backed audit of every routing decision, override, and delegation at `~/.research_sessions/<session>.json` -3. **Fallback Decomposer** — `scripts/fallback_decomposer.py` — heuristic question → 3-5 sub-questions using what/why/how/who/what's next framework +1. **Classifier** — `skills/research/scripts/classifier.py` — deterministic keyword signal matching → routing decision (specialist or fallback) with confidence score per specialist +2. **Routing Transparency Logger** — `skills/research/scripts/routing_transparency_logger.py` — JSON-backed audit of every routing decision, override, and delegation at `~/.research_sessions/<session>.json` +3. **Fallback Decomposer** — `skills/research/scripts/fallback_decomposer.py` — heuristic question → 3-5 sub-questions using what/why/how/who/what's next framework ### Knowledge Bases -- `references/hybrid_router_architecture.md` — router-vs-run trade-offs + routing transparency principle (7+ sources) -- `references/deterministic_classification_canon.md` — why keyword > LLM-reasoned for routing (7+ sources) -- `references/fallback_workflow_canon.md` — plan-decompose-search-synthesize methodology (7+ sources) +- `skills/research/references/hybrid_router_architecture.md` — router-vs-run trade-offs + routing transparency principle (7+ sources) +- `skills/research/references/deterministic_classification_canon.md` — why keyword > LLM-reasoned for routing (7+ sources) +- `skills/research/references/fallback_workflow_canon.md` — plan-decompose-search-synthesize methodology (7+ sources) ## Related Agents diff --git a/docs/agents/cs-scraping-architect.md b/docs/agents/cs-scraping-architect.md index a881423d..7ed9072c 100644 --- a/docs/agents/cs-scraping-architect.md +++ b/docs/agents/cs-scraping-architect.md @@ -1,6 +1,6 @@ --- title: "Scraping Architect — AI Coding Agent & Codex Skill" -description: "Expert persona for web scraping and data pipeline design.. Agent-native orchestrator for Claude Code, Codex, Gemini CLI." +description: "Use when the user wants to scrape a website, crawl docs, extract data from PDFs/Excel/CSV/HTML, parse an API response into a dataset, or debug a. Agent-native orchestrator for Claude Code, Codex, Gemini CLI." --- # Scraping Architect @@ -11,4 +11,38 @@ description: "Expert persona for web scraping and data pipeline design.. Agent-n <span class="meta-badge">:material-github: <a href="https://github.com/alirezarezvani/claude-skills/tree/main/engineering/universal-scraping-architect/agents/cs-scraping-architect.md">Source</a></span> </div> -Use this agent when you need to design a complex extraction strategy or debug scraping scripts. + +Data-extraction pipeline architect. Operates the `skills/universal-scraping-architect/SKILL.md` skill: route the approach, extract with checkpointing, validate before delivering. The defining behavior is the **validation gate** — no scraped output is handed to the user until `validate_extraction.py` exits 0. + +## Workflow + +1. **Load the skill.** Read `skills/universal-scraping-architect/SKILL.md` (and `project-context.md` if present) before asking the user anything. Determine target data format, scale, and deployment environment. +2. **Route the mode and say why** (never silently pick one): + - **Mode 1 — Firecrawl (API):** public URL, JS-heavy/SPA, search-first discovery, or bulk domain crawling. BYOK: key only via `os.getenv('FIRECRAWL_API_KEY')`. + - **Mode 2 — Local Python:** local files (PDF/Excel/CSV), private or sensitive data, or simple static HTML where an API is overkill. + - **Mode 3 — Hybrid:** Firecrawl for discovery/extraction, pandas locally for cleaning and normalization. +3. **Budget before bulk.** Estimate Firecrawl API quota or LLM token limits before any multi-page job; add checkpointing and pagination handling for anything beyond a single page. +4. **Start from the runner templates** (run from the plugin root; each `--sample` works offline): + ```bash + python3 skills/universal-scraping-architect/scripts/firecrawl_example.py --sample # Mode 1 (deps: firecrawl, requests) + python3 skills/universal-scraping-architect/scripts/local_bs4_example.py --sample # Mode 2 (deps: beautifulsoup4, pandas) + ``` + Edit a copy of the template for the actual job; never inline a from-scratch scraper when a template covers the mode. +5. **Validate — mandatory gate:** + ```bash + python3 skills/universal-scraping-architect/scripts/validate_extraction.py extracted_output.json --json + ``` + Exit 0 = `{"status": "ok"}` → proceed. Exit 1 → fix and re-extract; never deliver (parse the JSON `status` field for the `warning` = empty-output vs `error` = malformed-JSON distinction, since both share exit 1). Then check required fields and duplicates against the pipeline spec. +6. **Format and deliver:** CSV for tabular data, JSON for nested structures, Markdown (chunked for token limits) for crawled docs. Report row counts and empty-value summary. + +## Refusal & Flag Gates + +- **Hardcoded API keys** → stop and rewrite to `os.getenv('FIRECRAWL_API_KEY')` before anything else runs. +- **Private/sensitive local data bound for an external API** → flag the privacy risk and switch to Mode 2. +- **No robots.txt check / no rate limiting** on a live target → add both before scraping; refuse to scrape sites that disallow it. +- **Brittle selectors** (deep `nth-child` chains) → replace with data attributes or structural anchors. +- **Hundreds of records implied but no pagination/checkpointing** → add it proactively. + +## Output + +A routed, validated pipeline: the runner script (edited template), the validated dataset, and a one-paragraph summary stating the mode chosen and why, budget assumptions, and the validation result. diff --git a/docs/agents/cs-senior-engineer.md b/docs/agents/cs-senior-engineer.md index 7d1a4377..f107181d 100644 --- a/docs/agents/cs-senior-engineer.md +++ b/docs/agents/cs-senior-engineer.md @@ -34,7 +34,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 @@ -65,7 +65,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/docs/agents/cs-syllabus.md b/docs/agents/cs-syllabus.md index 20071da1..638af74d 100644 --- a/docs/agents/cs-syllabus.md +++ b/docs/agents/cs-syllabus.md @@ -60,9 +60,9 @@ The cs-syllabus agent orchestrates the `syllabus` skill across course-reading-li ### Python Tools (Stdlib) -1. **Citation Tracker** — `scripts/citation_tracker.py` — Consensus three-count + 1s sequential at `~/.syllabus_sessions/<session>.json` -2. **Topic Grouper** — `scripts/topic_grouper.py` — heuristic 6-12 section grouping from extracted topics -3. **Discussion Question Validator** — `scripts/discussion_question_validator.py` — Bloom higher-order quality check (rejects recall questions) +1. **Citation Tracker** — `skills/syllabus/scripts/citation_tracker.py` — Consensus three-count + 1s sequential at `~/.syllabus_sessions/<session>.json` +2. **Topic Grouper** — `skills/syllabus/scripts/topic_grouper.py` — heuristic 6-12 section grouping from extracted topics +3. **Discussion Question Validator** — `skills/syllabus/scripts/discussion_question_validator.py` — Bloom higher-order quality check (rejects recall questions) ### Bundled Node.js Script @@ -70,9 +70,9 @@ The cs-syllabus agent orchestrates the `syllabus` skill across course-reading-li ### Knowledge Bases -- `references/applied_domain_weaving.md` — search-quality canon (7+ sources) -- `references/audience_calibration.md` — undergrad vs grad summary jargon (7+ sources) -- `references/bundled_script_pattern.md` — why bundle vs inline (7+ sources) +- `skills/syllabus/references/applied_domain_weaving.md` — search-quality canon (7+ sources) +- `skills/syllabus/references/audience_calibration.md` — undergrad vs grad summary jargon (7+ sources) +- `skills/syllabus/references/bundled_script_pattern.md` — why bundle vs inline (7+ sources) ## Related Agents diff --git a/docs/agents/cs-ux-researcher.md b/docs/agents/cs-ux-researcher.md index 99df964c..72c2f0ac 100644 --- a/docs/agents/cs-ux-researcher.md +++ b/docs/agents/cs-ux-researcher.md @@ -1,6 +1,6 @@ --- title: "UX Researcher Agent — AI Coding Agent & Codex Skill" -description: "UX research agent for research planning, persona generation, journey mapping, and usability test analysis. Agent-native orchestrator for Claude Code, Codex, Gemini CLI." +description: "UX research agent for research planning, persona generation, journey mapping, and usability test analysis. Use when product decisions need user. Agent-native orchestrator for Claude Code, Codex, Gemini CLI." --- # UX Researcher Agent @@ -22,78 +22,78 @@ The cs-ux-researcher agent ensures that user needs drive product development. It ## Skill Integration -**Primary Skill:** [`product-team/ux-researcher-designer`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/ux-researcher-designer) +**Primary Skill:** [`skills/ux-researcher-designer`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/skills/ux-researcher-designer) ### All Orchestrated Skills | # | Skill | Location | Primary Tool | |---|-------|----------|-------------| -| 1 | UX Researcher & Designer | [`product-team/ux-researcher-designer`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/ux-researcher-designer) | persona_generator.py | -| 2 | Product Manager Toolkit | [`product-team/product-manager-toolkit`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/product-manager-toolkit) | customer_interview_analyzer.py | -| 3 | UI Design System | [`product-team/ui-design-system`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/ui-design-system) | design_token_generator.py | +| 1 | UX Researcher & Designer | [`skills/ux-researcher-designer`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/skills/ux-researcher-designer) | persona_generator.py | +| 2 | Product Manager Toolkit | [`skills/product-manager-toolkit`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/skills/product-manager-toolkit) | customer_interview_analyzer.py | +| 3 | UI Design System | [`skills/ui-design-system`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/skills/ui-design-system) | design_token_generator.py | ### Python Tools 1. **Persona Generator** - **Purpose:** Create data-driven user personas from research inputs including demographics, goals, pain points, and behavioral patterns - - **Path:** [`scripts/persona_generator.py`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/ux-researcher-designer/scripts/persona_generator.py) - - **Usage:** `python ../../product-team/ux-researcher-designer/scripts/persona_generator.py research-data.json` + - **Path:** [`scripts/persona_generator.py`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/skills/ux-researcher-designer/scripts/persona_generator.py) + - **Usage:** `python ../../product-team/skills/ux-researcher-designer/scripts/persona_generator.py research-data.json` - **Features:** Multiple persona generation, behavioral segmentation, needs hierarchy mapping, empathy map creation - **Use Cases:** Persona development, user segmentation, design alignment, stakeholder communication 2. **Customer Interview Analyzer** - **Purpose:** NLP-based analysis of interview transcripts to extract pain points, feature requests, themes, and sentiment - - **Path:** [`scripts/customer_interview_analyzer.py`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/product-manager-toolkit/scripts/customer_interview_analyzer.py) - - **Usage:** `python ../../product-team/product-manager-toolkit/scripts/customer_interview_analyzer.py interview.txt` + - **Path:** [`scripts/customer_interview_analyzer.py`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/skills/product-manager-toolkit/scripts/customer_interview_analyzer.py) + - **Usage:** `python ../../product-team/skills/product-manager-toolkit/scripts/customer_interview_analyzer.py interview.txt` - **Features:** Pain point extraction with severity scoring, feature request identification, jobs-to-be-done patterns, theme clustering, key quote extraction - **Use Cases:** Interview synthesis, discovery validation, problem prioritization, insight aggregation 3. **Design Token Generator** - **Purpose:** Generate design tokens for consistent UI implementation across platforms - - **Path:** [`scripts/design_token_generator.py`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/ui-design-system/scripts/design_token_generator.py) - - **Usage:** `python ../../product-team/ui-design-system/scripts/design_token_generator.py theme.json` + - **Path:** [`scripts/design_token_generator.py`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/skills/ui-design-system/scripts/design_token_generator.py) + - **Usage:** `python ../../product-team/skills/ui-design-system/scripts/design_token_generator.py theme.json` - **Use Cases:** Research-informed design system updates, accessibility token adjustments ### Knowledge Bases 1. **Persona Methodology** - - **Location:** [`references/persona-methodology.md`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/ux-researcher-designer/references/persona-methodology.md) + - **Location:** [`references/persona-methodology.md`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/skills/ux-researcher-designer/references/persona-methodology.md) - **Content:** Research-backed persona creation methodology, data collection strategies, validation approaches - **Use Case:** Methodological guidance for persona projects 2. **Example Personas** - - **Location:** [`references/example-personas.md`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/ux-researcher-designer/references/example-personas.md) + - **Location:** [`references/example-personas.md`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/skills/ux-researcher-designer/references/example-personas.md) - **Content:** Sample persona documents with demographics, goals, pain points, behaviors, scenarios - **Use Case:** Persona format reference, team training 3. **Journey Mapping Guide** - - **Location:** [`references/journey-mapping-guide.md`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/ux-researcher-designer/references/journey-mapping-guide.md) + - **Location:** [`references/journey-mapping-guide.md`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/skills/ux-researcher-designer/references/journey-mapping-guide.md) - **Content:** Customer journey mapping methodology, touchpoint analysis, emotion mapping, opportunity identification - **Use Case:** Journey map creation, experience design, service design 4. **Usability Testing Frameworks** - - **Location:** [`references/usability-testing-frameworks.md`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/ux-researcher-designer/references/usability-testing-frameworks.md) + - **Location:** [`references/usability-testing-frameworks.md`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/skills/ux-researcher-designer/references/usability-testing-frameworks.md) - **Content:** Test planning, task design, analysis methods, severity ratings, reporting formats - **Use Case:** Usability study design, prototype validation, UX evaluation 5. **Component Architecture** - - **Location:** [`references/component-architecture.md`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/ui-design-system/references/component-architecture.md) + - **Location:** [`references/component-architecture.md`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/skills/ui-design-system/references/component-architecture.md) - **Content:** Component hierarchy, atomic design patterns, composition strategies - **Use Case:** Research-to-design translation, component recommendations 6. **Developer Handoff** - - **Location:** [`references/developer-handoff.md`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/ui-design-system/references/developer-handoff.md) + - **Location:** [`references/developer-handoff.md`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/skills/ui-design-system/references/developer-handoff.md) - **Content:** Design-to-dev handoff process, specification formats, asset delivery - **Use Case:** Translating research findings into implementation specs ### Templates 1. **Research Plan Template** - - **Location:** [`assets/research_plan_template.md`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/ux-researcher-designer/assets/research_plan_template.md) + - **Location:** [`assets/research_plan_template.md`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/skills/ux-researcher-designer/assets/research_plan_template.md) - **Use Case:** Structuring research studies with methodology, participants, and analysis plan 2. **Design System Documentation Template** - - **Location:** [`assets/design_system_doc_template.md`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/ui-design-system/assets/design_system_doc_template.md) + - **Location:** [`assets/design_system_doc_template.md`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/skills/ui-design-system/assets/design_system_doc_template.md) - **Use Case:** Documenting research-informed design system decisions ## Workflows @@ -112,7 +112,7 @@ The cs-ux-researcher agent ensures that user needs drive product development. It 2. **Select Methodology** - Choose the right approach: ```bash # Review usability testing frameworks for method selection - cat ../../product-team/ux-researcher-designer/references/usability-testing-frameworks.md + cat ../../product-team/skills/ux-researcher-designer/references/usability-testing-frameworks.md ``` - **Exploratory** (interviews, contextual inquiry): When learning about problem space - **Evaluative** (usability testing, A/B tests): When validating solutions @@ -128,7 +128,7 @@ The cs-ux-researcher agent ensures that user needs drive product development. It 4. **Create Study Materials** - Prepare research instruments: ```bash # Use the research plan template - cat ../../product-team/ux-researcher-designer/assets/research_plan_template.md + cat ../../product-team/skills/ux-researcher-designer/assets/research_plan_template.md ``` - Interview guide or test script - Task scenarios (for usability tests) @@ -148,13 +148,13 @@ The cs-ux-researcher agent ensures that user needs drive product development. It **Example:** ```bash # Create research plan from template -cp ../../product-team/ux-researcher-designer/assets/research_plan_template.md onboarding-research-plan.md +cp ../../product-team/skills/ux-researcher-designer/assets/research_plan_template.md onboarding-research-plan.md # Review methodology options -cat ../../product-team/ux-researcher-designer/references/usability-testing-frameworks.md +cat ../../product-team/skills/ux-researcher-designer/references/usability-testing-frameworks.md # Review persona methodology for participant criteria -cat ../../product-team/ux-researcher-designer/references/persona-methodology.md +cat ../../product-team/skills/ux-researcher-designer/references/persona-methodology.md ``` ### Workflow 2: Persona Generation @@ -172,9 +172,9 @@ cat ../../product-team/ux-researcher-designer/references/persona-methodology.md 2. **Analyze Interview Data** - Extract structured insights: ```bash # Analyze each interview transcript - python ../../product-team/product-manager-toolkit/scripts/customer_interview_analyzer.py interview-001.txt > insights-001.json - python ../../product-team/product-manager-toolkit/scripts/customer_interview_analyzer.py interview-002.txt > insights-002.json - python ../../product-team/product-manager-toolkit/scripts/customer_interview_analyzer.py interview-003.txt > insights-003.json + python ../../product-team/skills/product-manager-toolkit/scripts/customer_interview_analyzer.py interview-001.txt > insights-001.json + python ../../product-team/skills/product-manager-toolkit/scripts/customer_interview_analyzer.py interview-002.txt > insights-002.json + python ../../product-team/skills/product-manager-toolkit/scripts/customer_interview_analyzer.py interview-003.txt > insights-003.json ``` 3. **Identify Behavioral Segments** - Cluster users by: @@ -187,7 +187,7 @@ cat ../../product-team/ux-researcher-designer/references/persona-methodology.md 4. **Generate Personas** - Create data-backed personas: ```bash # Generate personas from aggregated research - python ../../product-team/ux-researcher-designer/scripts/persona_generator.py research-data.json + python ../../product-team/skills/ux-researcher-designer/scripts/persona_generator.py research-data.json ``` 5. **Validate Personas** - Ensure accuracy: @@ -199,7 +199,7 @@ cat ../../product-team/ux-researcher-designer/references/persona-methodology.md 6. **Socialize Personas** - Make personas actionable: ```bash # Review example personas for format guidance - cat ../../product-team/ux-researcher-designer/references/example-personas.md + cat ../../product-team/skills/ux-researcher-designer/references/example-personas.md ``` - Create one-page persona cards for team walls/wikis - Present to product, engineering, and design teams @@ -219,18 +219,18 @@ echo "===========================" # Step 1: Analyze interviews for f in interviews/*.txt; do base=$(basename "$f" .txt) - python ../../product-team/product-manager-toolkit/scripts/customer_interview_analyzer.py "$f" json > "insights-$base.json" + python ../../product-team/skills/product-manager-toolkit/scripts/customer_interview_analyzer.py "$f" json > "insights-$base.json" echo "Analyzed: $f" done # Step 2: Review persona methodology -cat ../../product-team/ux-researcher-designer/references/persona-methodology.md +cat ../../product-team/skills/ux-researcher-designer/references/persona-methodology.md # Step 3: Generate personas -python ../../product-team/ux-researcher-designer/scripts/persona_generator.py research-data.json +python ../../product-team/skills/ux-researcher-designer/scripts/persona_generator.py research-data.json # Step 4: Review example format -cat ../../product-team/ux-researcher-designer/references/example-personas.md +cat ../../product-team/skills/ux-researcher-designer/references/example-personas.md ``` ### Workflow 3: Journey Mapping @@ -246,7 +246,7 @@ cat ../../product-team/ux-researcher-designer/references/example-personas.md 2. **Review Journey Mapping Methodology** - Understand the framework: ```bash - cat ../../product-team/ux-researcher-designer/references/journey-mapping-guide.md + cat ../../product-team/skills/ux-researcher-designer/references/journey-mapping-guide.md ``` 3. **Map Journey Stages** - Identify key phases: @@ -281,7 +281,7 @@ cat ../../product-team/ux-researcher-designer/references/example-personas.md Self-service help in context,600,2,0.8,2 Upgrade prompt optimization,400,3,0.6,2 EOF - python ../../product-team/product-manager-toolkit/scripts/rice_prioritizer.py journey-opportunities.csv + python ../../product-team/skills/product-manager-toolkit/scripts/rice_prioritizer.py journey-opportunities.csv ``` **Expected Output:** Visual journey map with stages, touchpoints, emotions, pain points, and prioritized improvement opportunities @@ -295,14 +295,14 @@ echo "Journey Mapping - Onboarding Flow" echo "==================================" # Review journey mapping methodology -cat ../../product-team/ux-researcher-designer/references/journey-mapping-guide.md +cat ../../product-team/skills/ux-researcher-designer/references/journey-mapping-guide.md # Analyze relevant interview transcripts for journey insights -python ../../product-team/product-manager-toolkit/scripts/customer_interview_analyzer.py onboarding-interview-01.txt -python ../../product-team/product-manager-toolkit/scripts/customer_interview_analyzer.py onboarding-interview-02.txt +python ../../product-team/skills/product-manager-toolkit/scripts/customer_interview_analyzer.py onboarding-interview-01.txt +python ../../product-team/skills/product-manager-toolkit/scripts/customer_interview_analyzer.py onboarding-interview-02.txt # Prioritize improvement opportunities -python ../../product-team/product-manager-toolkit/scripts/rice_prioritizer.py journey-opportunities.csv +python ../../product-team/skills/product-manager-toolkit/scripts/rice_prioritizer.py journey-opportunities.csv ``` ### Workflow 4: Usability Test Analysis @@ -313,7 +313,7 @@ python ../../product-team/product-manager-toolkit/scripts/rice_prioritizer.py jo 1. **Plan the Test** - Design the study: ```bash # Review usability testing frameworks - cat ../../product-team/ux-researcher-designer/references/usability-testing-frameworks.md + cat ../../product-team/skills/ux-researcher-designer/references/usability-testing-frameworks.md ``` - Define test objectives (what decisions will this inform) - Select test type (moderated/unmoderated, remote/in-person) @@ -327,7 +327,7 @@ python ../../product-team/product-manager-toolkit/scripts/rice_prioritizer.py jo - Note-taking template for observers - Use research plan template for documentation: ```bash - cat ../../product-team/ux-researcher-designer/assets/research_plan_template.md + cat ../../product-team/skills/ux-researcher-designer/assets/research_plan_template.md ``` 3. **Conduct Sessions** - Run 5-8 sessions: @@ -350,8 +350,8 @@ python ../../product-team/product-manager-toolkit/scripts/rice_prioritizer.py jo 5. **Analyze Verbal Feedback** - Extract qualitative insights: ```bash # Analyze session transcripts for themes - python ../../product-team/product-manager-toolkit/scripts/customer_interview_analyzer.py usability-session-01.txt - python ../../product-team/product-manager-toolkit/scripts/customer_interview_analyzer.py usability-session-02.txt + python ../../product-team/skills/product-manager-toolkit/scripts/customer_interview_analyzer.py usability-session-01.txt + python ../../product-team/skills/product-manager-toolkit/scripts/customer_interview_analyzer.py usability-session-02.txt ``` 6. **Create Report and Recommendations** - Deliver findings: @@ -365,7 +365,7 @@ python ../../product-team/product-manager-toolkit/scripts/rice_prioritizer.py jo - Review findings with design team - Map issues to components in design system: ```bash - cat ../../product-team/ui-design-system/references/component-architecture.md + cat ../../product-team/skills/ui-design-system/references/component-architecture.md ``` - Create Jira tickets for each issue - Plan re-test for critical issues after fixes @@ -381,17 +381,17 @@ echo "Usability Test Analysis" echo "=======================" # Review frameworks -cat ../../product-team/ux-researcher-designer/references/usability-testing-frameworks.md +cat ../../product-team/skills/ux-researcher-designer/references/usability-testing-frameworks.md # Analyze each session transcript for i in 1 2 3 4 5; do echo "Session $i Analysis:" - python ../../product-team/product-manager-toolkit/scripts/customer_interview_analyzer.py "usability-session-0$i.txt" + python ../../product-team/skills/product-manager-toolkit/scripts/customer_interview_analyzer.py "usability-session-0$i.txt" echo "" done # Review component architecture for design recommendations -cat ../../product-team/ui-design-system/references/component-architecture.md +cat ../../product-team/skills/ui-design-system/references/component-architecture.md ``` ## Integration Examples @@ -414,7 +414,7 @@ echo "-------------------------------------" for f in discovery-interviews/*.txt; do base=$(basename "$f" .txt) echo "Analyzing: $base" - python ../../product-team/product-manager-toolkit/scripts/customer_interview_analyzer.py "$f" json > "insights/$base.json" + python ../../product-team/skills/product-manager-toolkit/scripts/customer_interview_analyzer.py "$f" json > "insights/$base.json" done # Week 2: Synthesis @@ -423,10 +423,10 @@ echo "Week 2: Generate Personas & Journey Map" echo "----------------------------------------" # Generate personas from aggregated data -python ../../product-team/ux-researcher-designer/scripts/persona_generator.py aggregated-research.json +python ../../product-team/skills/ux-researcher-designer/scripts/persona_generator.py aggregated-research.json # Reference journey mapping guide -echo "Journey mapping guide: ../../product-team/ux-researcher-designer/references/journey-mapping-guide.md" +echo "Journey mapping guide: ../../product-team/skills/ux-researcher-designer/references/journey-mapping-guide.md" ``` ### Example 2: Research Repository Update @@ -442,15 +442,15 @@ echo "================================================" echo "" echo "New Interview Analysis:" for f in new-interviews/*.txt; do - python ../../product-team/product-manager-toolkit/scripts/customer_interview_analyzer.py "$f" + python ../../product-team/skills/product-manager-toolkit/scripts/customer_interview_analyzer.py "$f" echo "---" done # Review and refresh personas echo "" echo "Persona Review:" -echo "Current personas: ../../product-team/ux-researcher-designer/references/example-personas.md" -echo "Methodology: ../../product-team/ux-researcher-designer/references/persona-methodology.md" +echo "Current personas: ../../product-team/skills/ux-researcher-designer/references/example-personas.md" +echo "Methodology: ../../product-team/skills/ux-researcher-designer/references/persona-methodology.md" ``` ### Example 3: Design Handoff with Research Context @@ -465,22 +465,22 @@ echo "========================" # Persona context echo "" echo "1. Active Personas:" -cat ../../product-team/ux-researcher-designer/references/example-personas.md | head -30 +cat ../../product-team/skills/ux-researcher-designer/references/example-personas.md | head -30 # Journey context echo "" echo "2. Journey Map Reference:" -echo "See: ../../product-team/ux-researcher-designer/references/journey-mapping-guide.md" +echo "See: ../../product-team/skills/ux-researcher-designer/references/journey-mapping-guide.md" # Design system alignment echo "" echo "3. Component Architecture:" -echo "See: ../../product-team/ui-design-system/references/component-architecture.md" +echo "See: ../../product-team/skills/ui-design-system/references/component-architecture.md" # Developer handoff process echo "" echo "4. Handoff Process:" -echo "See: ../../product-team/ui-design-system/references/developer-handoff.md" +echo "See: ../../product-team/skills/ui-design-system/references/developer-handoff.md" ``` ## Success Metrics @@ -514,16 +514,16 @@ echo "See: ../../product-team/ui-design-system/references/developer-handoff.md" - [cs-product-manager](cs-product-manager.md) - Product management lifecycle, interview analysis, PRD development - [cs-agile-product-owner](cs-agile-product-owner.md) - Translating research findings into user stories - [cs-product-strategist](cs-product-strategist.md) - Strategic research to validate product vision and positioning -- UI Design System - Design handoff and component recommendations (see [`product-team/ui-design-system`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/ui-design-system)) +- UI Design System - Design handoff and component recommendations (see [`skills/ui-design-system`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/skills/ui-design-system)) ## References -- **Primary Skill:** [../../product-team/ux-researcher-designer/SKILL.md](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/ux-researcher-designer/SKILL.md) -- **Interview Analyzer:** [../../product-team/product-manager-toolkit/SKILL.md](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/product-manager-toolkit/SKILL.md) -- **Persona Methodology:** [../../product-team/ux-researcher-designer/references/persona-methodology.md](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/ux-researcher-designer/references/persona-methodology.md) -- **Journey Mapping Guide:** [../../product-team/ux-researcher-designer/references/journey-mapping-guide.md](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/ux-researcher-designer/references/journey-mapping-guide.md) -- **Usability Testing:** [../../product-team/ux-researcher-designer/references/usability-testing-frameworks.md](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/ux-researcher-designer/references/usability-testing-frameworks.md) -- **Design System:** [../../product-team/ui-design-system/SKILL.md](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/ui-design-system/SKILL.md) +- **Primary Skill:** [../../product-team/skills/ux-researcher-designer/SKILL.md](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/skills/ux-researcher-designer/SKILL.md) +- **Interview Analyzer:** [../../product-team/skills/product-manager-toolkit/SKILL.md](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/skills/product-manager-toolkit/SKILL.md) +- **Persona Methodology:** [../../product-team/skills/ux-researcher-designer/references/persona-methodology.md](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/skills/ux-researcher-designer/references/persona-methodology.md) +- **Journey Mapping Guide:** [../../product-team/skills/ux-researcher-designer/references/journey-mapping-guide.md](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/skills/ux-researcher-designer/references/journey-mapping-guide.md) +- **Usability Testing:** [../../product-team/skills/ux-researcher-designer/references/usability-testing-frameworks.md](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/skills/ux-researcher-designer/references/usability-testing-frameworks.md) +- **Design System:** [../../product-team/skills/ui-design-system/SKILL.md](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/skills/ui-design-system/SKILL.md) - **Product Domain Guide:** [../../product-team/CLAUDE.md](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/CLAUDE.md) - **Agent Development Guide:** [../CLAUDE.md](https://github.com/alirezarezvani/claude-skills/tree/main/agents/CLAUDE.md) diff --git a/docs/agents/cs-vpe-advisor.md b/docs/agents/cs-vpe-advisor.md index 27ca4ed9..7f814722 100644 --- a/docs/agents/cs-vpe-advisor.md +++ b/docs/agents/cs-vpe-advisor.md @@ -148,11 +148,11 @@ python ../../skills/vpe-advisor/scripts/eng_team_structure_designer.py current-t ## Related Agents -- [cs-cto-advisor](https://github.com/alirezarezvani/claude-skills/tree/main/../agents/c-level/cs-cto-advisor.md) — Architecture, scaling cliffs (CTO decides what to build; VPE decides how to ship) +- [cs-cto-advisor](https://github.com/alirezarezvani/claude-skills/tree/main/agents/c-level/cs-cto-advisor.md) — Architecture, scaling cliffs (CTO decides what to build; VPE decides how to ship) - [cs-chro-advisor](cs-chro-advisor.md) — Hiring systems (ladders, bands) - [cs-coo-advisor](cs-coo-advisor.md) — Operating cadence company-wide - [cs-cfo-advisor](cs-cfo-advisor.md) — Cost-per-hire envelope, eng budget -- [cs-engineering-lead](https://github.com/alirezarezvani/claude-skills/tree/main/../agents/engineering-team/cs-engineering-lead.md) — Day-to-day incident + on-call coordination +- [cs-engineering-lead](https://github.com/alirezarezvani/claude-skills/tree/main/agents/engineering-team/cs-engineering-lead.md) — Day-to-day incident + on-call coordination ## References diff --git a/docs/agents/cs-webinar-marketer.md b/docs/agents/cs-webinar-marketer.md index 9daf5258..db32bea4 100644 --- a/docs/agents/cs-webinar-marketer.md +++ b/docs/agents/cs-webinar-marketer.md @@ -38,24 +38,24 @@ Distinct from: ## Skill Integration - `marketing-skill/skills/webinar-marketing` — the full webinar funnel motion (plan / rescue / evergreen) - - `scripts/webinar_funnel_scorer.py` — scores a funnel 0-100 and names the weakest stage - - `references/webinar-formats.md` — format-to-goal fit (training, demo, panel, summit…) - - `references/promotion-playbook.md` — the promotion runway across the pre-event window - - `references/benchmarks.md` — stage-by-stage conversion benchmarks by audience temperature - - `templates/webinar-plan-template.md` — the deliverable plan skeleton + - `marketing-skill/skills/webinar-marketing/scripts/webinar_funnel_scorer.py` — scores a funnel 0-100 and names the weakest stage + - `marketing-skill/skills/webinar-marketing/references/webinar-formats.md` — format-to-goal fit (training, demo, panel, summit…) + - `marketing-skill/skills/webinar-marketing/references/promotion-playbook.md` — the promotion runway across the pre-event window + - `marketing-skill/skills/webinar-marketing/references/benchmarks.md` — stage-by-stage conversion benchmarks by audience temperature + - `marketing-skill/skills/webinar-marketing/templates/webinar-plan-template.md` — the deliverable plan skeleton Before asking questions, read `marketing-context.md` if it exists — use it for brand voice, personas, and customer language; only ask for what's specific to this event. ## Core Workflows ### 1. Plan From Scratch (Mode 1) -1. Lock the single promise to the attendee, then pick the format that fits the goal (`references/webinar-formats.md`) +1. Lock the single promise to the attendee, then pick the format that fits the goal (`marketing-skill/skills/webinar-marketing/references/webinar-formats.md`) 2. Size the funnel backward from the business goal using realistic conversion rates (funnel math below) 3. Reality-check: if required visits exceed reachable audience, fix goal/format/budget *now* -4. Build the promotion plan across the runway (`references/promotion-playbook.md`) +4. Build the promotion plan across the runway (`marketing-skill/skills/webinar-marketing/references/promotion-playbook.md`) 5. Design the show-up sequence and the live-to-close moment 6. Plan segmented follow-up: attendees vs. no-shows -7. Deliver via `templates/webinar-plan-template.md` — full plan + promo calendar + email/copy drafts +7. Deliver via `marketing-skill/skills/webinar-marketing/templates/webinar-plan-template.md` — full plan + promo calendar + email/copy drafts ### 2. Optimize / Rescue (Mode 2) 1. Get the *actual* numbers: invited → registered → showed up → engaged → converted @@ -112,7 +112,7 @@ Input JSON (`registrations` + `attended_live` required; rest optional). `audienc Returns an overall 0-100 score, per-stage rate vs. benchmark, and the named bottleneck. ## Output Standards -- Plans → use `templates/webinar-plan-template.md`; always include the backward funnel math +- Plans → use `marketing-skill/skills/webinar-marketing/templates/webinar-plan-template.md`; always include the backward funnel math - Rescues → lead with the named bottleneck and the score, then ranked fixes - Every deliverable states the audience temperature so benchmarks are interpreted correctly diff --git a/docs/agents/cs-wiki-ingestor.md b/docs/agents/cs-wiki-ingestor.md index 4978c8d4..35b9c81f 100644 --- a/docs/agents/cs-wiki-ingestor.md +++ b/docs/agents/cs-wiki-ingestor.md @@ -26,7 +26,7 @@ You are spawned **per-ingest**, not as a long-running agent. You do one source a ## Workflow -Follow `references/ingest-workflow.md` in the llm-wiki skill. Summary: +Follow `engineering/llm-wiki/skills/llm-wiki/references/ingest-workflow.md` in the llm-wiki skill. Summary: ### 1. Prep Run `python <plugin>/scripts/ingest_source.py --vault . --source <path> --json` to get the brief (title guess, word count, preview, suggested summary path, whether a summary already exists). diff --git a/docs/agents/cs-wiki-librarian.md b/docs/agents/cs-wiki-librarian.md index 89165c55..cacf14f0 100644 --- a/docs/agents/cs-wiki-librarian.md +++ b/docs/agents/cs-wiki-librarian.md @@ -25,7 +25,7 @@ You are spawned **per-query**, not as a long-running agent. ## Workflow -Follow `references/query-workflow.md`. Summary: +Follow `engineering/llm-wiki/skills/llm-wiki/references/query-workflow.md`. Summary: ### 1. Read `index.md` first The index is the catalog. Scan it and pick the 3-10 pages most likely to contain the answer. Pick across categories: @@ -64,7 +64,7 @@ This is the compounding move. At the end of the answer, ask: If yes: - Pick the right category (most often `comparisons/` or `synthesis/`) -- Use the appropriate template (see llm-wiki skill's `references/page-formats.md`) +- Use the appropriate template (see llm-wiki skill's `engineering/llm-wiki/skills/llm-wiki/references/page-formats.md`) - Add frontmatter with `category`, `summary`, `sources` (count), `updated` - Update `wiki/index.md` (inline or via script) - Append to `log.md`: `python <plugin>/scripts/append_log.py --vault . --op create --title "<question>" --detail "filed query response to <path>"` diff --git a/docs/agents/cs-wiki-linter.md b/docs/agents/cs-wiki-linter.md index 7d6bdef4..00263800 100644 --- a/docs/agents/cs-wiki-linter.md +++ b/docs/agents/cs-wiki-linter.md @@ -20,7 +20,7 @@ You are spawned **per-lint-pass**, not as a long-running agent. ## Workflow -Follow `references/lint-workflow.md`. Three passes. +Follow `engineering/llm-wiki/skills/llm-wiki/references/lint-workflow.md`. Three passes. ### Pass 1 — Mechanical (scripts) diff --git a/docs/agents/cs-workspace-admin.md b/docs/agents/cs-workspace-admin.md index 37550cd6..a5ca759f 100644 --- a/docs/agents/cs-workspace-admin.md +++ b/docs/agents/cs-workspace-admin.md @@ -24,44 +24,44 @@ Google Workspace administration specialist orchestrating the gws CLI for email a ### Python Tools 1. **GWS Doctor** - - **Path:** [`scripts/gws_doctor.py`](https://github.com/alirezarezvani/claude-skills/tree/main/engineering-team/google-workspace-cli/scripts/gws_doctor.py) - - **Usage:** `python3 ../../engineering-team/google-workspace-cli/scripts/gws_doctor.py [--json]` + - **Path:** [`scripts/gws_doctor.py`](https://github.com/alirezarezvani/claude-skills/tree/main/engineering-team/google-workspace-cli/skills/google-workspace-cli/scripts/gws_doctor.py) + - **Usage:** `python3 ../../engineering-team/google-workspace-cli/skills/google-workspace-cli/scripts/gws_doctor.py [--json]` - **Purpose:** Pre-flight diagnostics — checks installation, auth, and service connectivity 2. **Auth Setup Guide** - - **Path:** [`scripts/auth_setup_guide.py`](https://github.com/alirezarezvani/claude-skills/tree/main/engineering-team/google-workspace-cli/scripts/auth_setup_guide.py) - - **Usage:** `python3 ../../engineering-team/google-workspace-cli/scripts/auth_setup_guide.py --guide oauth` + - **Path:** [`scripts/auth_setup_guide.py`](https://github.com/alirezarezvani/claude-skills/tree/main/engineering-team/google-workspace-cli/skills/google-workspace-cli/scripts/auth_setup_guide.py) + - **Usage:** `python3 ../../engineering-team/google-workspace-cli/skills/google-workspace-cli/scripts/auth_setup_guide.py --guide oauth` - **Purpose:** Guided auth setup, scope listing, .env generation, validation 3. **Recipe Runner** - - **Path:** [`scripts/gws_recipe_runner.py`](https://github.com/alirezarezvani/claude-skills/tree/main/engineering-team/google-workspace-cli/scripts/gws_recipe_runner.py) - - **Usage:** `python3 ../../engineering-team/google-workspace-cli/scripts/gws_recipe_runner.py --list` + - **Path:** [`scripts/gws_recipe_runner.py`](https://github.com/alirezarezvani/claude-skills/tree/main/engineering-team/google-workspace-cli/skills/google-workspace-cli/scripts/gws_recipe_runner.py) + - **Usage:** `python3 ../../engineering-team/google-workspace-cli/skills/google-workspace-cli/scripts/gws_recipe_runner.py --list` - **Purpose:** Catalog, search, and execute 43 built-in recipes with persona filtering 4. **Workspace Audit** - - **Path:** [`scripts/workspace_audit.py`](https://github.com/alirezarezvani/claude-skills/tree/main/engineering-team/google-workspace-cli/scripts/workspace_audit.py) - - **Usage:** `python3 ../../engineering-team/google-workspace-cli/scripts/workspace_audit.py [--json]` + - **Path:** [`scripts/workspace_audit.py`](https://github.com/alirezarezvani/claude-skills/tree/main/engineering-team/google-workspace-cli/skills/google-workspace-cli/scripts/workspace_audit.py) + - **Usage:** `python3 ../../engineering-team/google-workspace-cli/skills/google-workspace-cli/scripts/workspace_audit.py [--json]` - **Purpose:** Security and configuration audit across Workspace services 5. **Output Analyzer** - - **Path:** [`scripts/output_analyzer.py`](https://github.com/alirezarezvani/claude-skills/tree/main/engineering-team/google-workspace-cli/scripts/output_analyzer.py) - - **Usage:** `gws ... --json | python3 ../../engineering-team/google-workspace-cli/scripts/output_analyzer.py --count` + - **Path:** [`scripts/output_analyzer.py`](https://github.com/alirezarezvani/claude-skills/tree/main/engineering-team/google-workspace-cli/skills/google-workspace-cli/scripts/output_analyzer.py) + - **Usage:** `gws ... --json | python3 ../../engineering-team/google-workspace-cli/skills/google-workspace-cli/scripts/output_analyzer.py --count` - **Purpose:** Parse, filter, and aggregate JSON/NDJSON output from any gws command ### Knowledge Bases -1. **Command Reference** — [`references/gws-command-reference.md`](https://github.com/alirezarezvani/claude-skills/tree/main/engineering-team/google-workspace-cli/references/gws-command-reference.md) +1. **Command Reference** — [`references/gws-command-reference.md`](https://github.com/alirezarezvani/claude-skills/tree/main/engineering-team/google-workspace-cli/skills/google-workspace-cli/references/gws-command-reference.md) - 18 services, 22 helpers, global flags, environment variables -2. **Recipes Cookbook** — [`references/recipes-cookbook.md`](https://github.com/alirezarezvani/claude-skills/tree/main/engineering-team/google-workspace-cli/references/recipes-cookbook.md) +2. **Recipes Cookbook** — [`references/recipes-cookbook.md`](https://github.com/alirezarezvani/claude-skills/tree/main/engineering-team/google-workspace-cli/skills/google-workspace-cli/references/recipes-cookbook.md) - 43 recipes organized by category with persona mapping -3. **Troubleshooting** — [`references/troubleshooting.md`](https://github.com/alirezarezvani/claude-skills/tree/main/engineering-team/google-workspace-cli/references/troubleshooting.md) +3. **Troubleshooting** — [`references/troubleshooting.md`](https://github.com/alirezarezvani/claude-skills/tree/main/engineering-team/google-workspace-cli/skills/google-workspace-cli/references/troubleshooting.md) - Common errors, auth issues, platform-specific fixes ### Templates -1. **Workspace Config** — [`assets/workspace-config.json`](https://github.com/alirezarezvani/claude-skills/tree/main/engineering-team/google-workspace-cli/assets/workspace-config.json) +1. **Workspace Config** — [`assets/workspace-config.json`](https://github.com/alirezarezvani/claude-skills/tree/main/engineering-team/google-workspace-cli/skills/google-workspace-cli/assets/workspace-config.json) - Automation config template with auth, defaults, scheduled tasks -2. **Persona Profiles** — [`assets/persona-profiles.md`](https://github.com/alirezarezvani/claude-skills/tree/main/engineering-team/google-workspace-cli/assets/persona-profiles.md) +2. **Persona Profiles** — [`assets/persona-profiles.md`](https://github.com/alirezarezvani/claude-skills/tree/main/engineering-team/google-workspace-cli/skills/google-workspace-cli/assets/persona-profiles.md) - 10 role-based workflow bundles ## Core Workflows @@ -80,9 +80,9 @@ Google Workspace administration specialist orchestrating the gws CLI for email a **Example:** ```bash -python3 ../../engineering-team/google-workspace-cli/scripts/gws_doctor.py -python3 ../../engineering-team/google-workspace-cli/scripts/auth_setup_guide.py --guide oauth -python3 ../../engineering-team/google-workspace-cli/scripts/auth_setup_guide.py --validate --json +python3 ../../engineering-team/google-workspace-cli/skills/google-workspace-cli/scripts/gws_doctor.py +python3 ../../engineering-team/google-workspace-cli/skills/google-workspace-cli/scripts/auth_setup_guide.py --guide oauth +python3 ../../engineering-team/google-workspace-cli/skills/google-workspace-cli/scripts/auth_setup_guide.py --validate --json ``` ### 2. Daily Operations @@ -97,9 +97,9 @@ python3 ../../engineering-team/google-workspace-cli/scripts/auth_setup_guide.py **Example:** ```bash -python3 ../../engineering-team/google-workspace-cli/scripts/gws_recipe_runner.py --persona pm --list -python3 ../../engineering-team/google-workspace-cli/scripts/gws_recipe_runner.py --run standup-report --dry-run -gws recipes standup-report --json | python3 ../../engineering-team/google-workspace-cli/scripts/output_analyzer.py --format table +python3 ../../engineering-team/google-workspace-cli/skills/google-workspace-cli/scripts/gws_recipe_runner.py --persona pm --list +python3 ../../engineering-team/google-workspace-cli/skills/google-workspace-cli/scripts/gws_recipe_runner.py --run standup-report --dry-run +gws recipes standup-report --json | python3 ../../engineering-team/google-workspace-cli/skills/google-workspace-cli/scripts/output_analyzer.py --format table ``` ### 3. Security Audit @@ -115,9 +115,9 @@ gws recipes standup-report --json | python3 ../../engineering-team/google-worksp **Example:** ```bash -python3 ../../engineering-team/google-workspace-cli/scripts/workspace_audit.py --json -python3 ../../engineering-team/google-workspace-cli/scripts/workspace_audit.py --json | \ - python3 ../../engineering-team/google-workspace-cli/scripts/output_analyzer.py --filter "status=FAIL" +python3 ../../engineering-team/google-workspace-cli/skills/google-workspace-cli/scripts/workspace_audit.py --json +python3 ../../engineering-team/google-workspace-cli/skills/google-workspace-cli/scripts/workspace_audit.py --json | \ + python3 ../../engineering-team/google-workspace-cli/skills/google-workspace-cli/scripts/output_analyzer.py --filter "status=FAIL" ``` ### 4. Automation Scripting @@ -133,9 +133,9 @@ python3 ../../engineering-team/google-workspace-cli/scripts/workspace_audit.py - **Example:** ```bash -python3 ../../engineering-team/google-workspace-cli/scripts/gws_recipe_runner.py --describe morning-briefing +python3 ../../engineering-team/google-workspace-cli/skills/google-workspace-cli/scripts/gws_recipe_runner.py --describe morning-briefing # Customize and test -gws helpers morning-briefing --json | python3 ../../engineering-team/google-workspace-cli/scripts/output_analyzer.py --select "type,summary,time" --format table +gws helpers morning-briefing --json | python3 ../../engineering-team/google-workspace-cli/skills/google-workspace-cli/scripts/output_analyzer.py --select "type,summary,time" --format table ``` ## Output Standards @@ -159,5 +159,5 @@ gws helpers morning-briefing --json | python3 ../../engineering-team/google-work ## References -- [Skill Documentation](https://github.com/alirezarezvani/claude-skills/tree/main/engineering-team/google-workspace-cli/SKILL.md) +- [Skill Documentation](https://github.com/alirezarezvani/claude-skills/tree/main/engineering-team/google-workspace-cli/skills/google-workspace-cli/SKILL.md) - [gws CLI Repository](https://github.com/googleworkspace/cli) diff --git a/docs/agents/index.md b/docs/agents/index.md index eb8fd1ef..ec0693fb 100644 --- a/docs/agents/index.md +++ b/docs/agents/index.md @@ -565,10 +565,10 @@ description: "93 agent-native orchestrators for Claude Code, Codex CLI, and Gemi Compliance Os -- :material-account:{ .lg .middle } **[cs-markdown-html-orchestrator — Density-first markdown-to-HTML converter](cs-markdown-html-orchestrator.md)** +- :material-language-html5:{ .lg .middle } **[cs-markdown-html-orchestrator — Density-first markdown-to-HTML converter](cs-markdown-html-orchestrator.md)** --- - Markdown Html + Markdown to HTML </div> diff --git a/docs/agents/wiki-ingestor.md b/docs/agents/wiki-ingestor.md index 37d5c9ee..4e0aa889 100644 --- a/docs/agents/wiki-ingestor.md +++ b/docs/agents/wiki-ingestor.md @@ -26,7 +26,7 @@ You are spawned **per-ingest**, not as a long-running agent. You do one source a ## Workflow -Follow `references/ingest-workflow.md` in the llm-wiki skill. Summary: +Follow `skills/llm-wiki/references/ingest-workflow.md` in the llm-wiki skill. Summary: ### 1. Prep Run `python <plugin>/scripts/ingest_source.py --vault . --source <path> --json` to get the brief (title guess, word count, preview, suggested summary path, whether a summary already exists). diff --git a/docs/agents/wiki-librarian.md b/docs/agents/wiki-librarian.md index 856b35ca..60bc84b7 100644 --- a/docs/agents/wiki-librarian.md +++ b/docs/agents/wiki-librarian.md @@ -25,7 +25,7 @@ You are spawned **per-query**, not as a long-running agent. ## Workflow -Follow `references/query-workflow.md`. Summary: +Follow `skills/llm-wiki/references/query-workflow.md`. Summary: ### 1. Read `index.md` first The index is the catalog. Scan it and pick the 3-10 pages most likely to contain the answer. Pick across categories: @@ -64,7 +64,7 @@ This is the compounding move. At the end of the answer, ask: If yes: - Pick the right category (most often `comparisons/` or `synthesis/`) -- Use the appropriate template (see llm-wiki skill's `references/page-formats.md`) +- Use the appropriate template (see llm-wiki skill's `skills/llm-wiki/references/page-formats.md`) - Add frontmatter with `category`, `summary`, `sources` (count), `updated` - Update `wiki/index.md` (inline or via script) - Append to `log.md`: `python <plugin>/scripts/append_log.py --vault . --op create --title "<question>" --detail "filed query response to <path>"` diff --git a/docs/agents/wiki-linter.md b/docs/agents/wiki-linter.md index 3f532902..9a7819b1 100644 --- a/docs/agents/wiki-linter.md +++ b/docs/agents/wiki-linter.md @@ -20,7 +20,7 @@ You are spawned **per-lint-pass**, not as a long-running agent. ## Workflow -Follow `references/lint-workflow.md`. Three passes. +Follow `skills/llm-wiki/references/lint-workflow.md`. Three passes. ### Pass 1 — Mechanical (scripts) diff --git a/docs/commands/a11y-audit.md b/docs/commands/a11y-audit.md index 76342f68..b6cc7480 100644 --- a/docs/commands/a11y-audit.md +++ b/docs/commands/a11y-audit.md @@ -46,7 +46,7 @@ For each finding (starting with critical): 1. Read the affected file 2. Show the violation with context (before) -3. Apply the fix from `references/framework-a11y-patterns.md` +3. Apply the fix from `engineering-team/a11y-audit/skills/a11y-audit/references/framework-a11y-patterns.md` 4. Show the result (after) **Auto-fixable issues** (apply without asking): @@ -82,9 +82,9 @@ Generate a markdown report at `a11y-report.md`: ## Skill Reference -- `engineering-team/a11y-audit/SKILL.md` -- `engineering-team/a11y-audit/scripts/a11y_scanner.py` -- `engineering-team/a11y-audit/scripts/contrast_checker.py` -- `engineering-team/a11y-audit/references/wcag-quick-ref.md` -- `engineering-team/a11y-audit/references/aria-patterns.md` -- `engineering-team/a11y-audit/references/framework-a11y-patterns.md` +- `engineering-team/a11y-audit/skills/a11y-audit/SKILL.md` +- `engineering-team/a11y-audit/skills/a11y-audit/scripts/a11y_scanner.py` +- `engineering-team/a11y-audit/skills/a11y-audit/scripts/contrast_checker.py` +- `engineering-team/a11y-audit/skills/a11y-audit/references/wcag-quick-ref.md` +- `engineering-team/a11y-audit/skills/a11y-audit/references/aria-patterns.md` +- `engineering-team/a11y-audit/skills/a11y-audit/references/framework-a11y-patterns.md` diff --git a/docs/commands/changelog.md b/docs/commands/changelog.md index 63352304..499d33e6 100644 --- a/docs/commands/changelog.md +++ b/docs/commands/changelog.md @@ -29,8 +29,8 @@ Generate Keep a Changelog entries from git history and validate commit message f ``` ## Scripts -- `engineering/changelog-generator/scripts/generate_changelog.py` — Parse commits, render changelog (`--from-tag`, `--to-tag`, `--from-ref`, `--to-ref`, `--format markdown|json`) -- `engineering/changelog-generator/scripts/commit_linter.py` — Validate conventional commit format (`--from-ref`, `--to-ref`, `--strict`, `--format text|json`) +- `engineering/skills/changelog-generator/scripts/generate_changelog.py` — Parse commits, render changelog (`--from-tag`, `--to-tag`, `--from-ref`, `--to-ref`, `--format markdown|json`) +- `engineering/skills/changelog-generator/scripts/commit_linter.py` — Validate conventional commit format (`--from-ref`, `--to-ref`, `--strict`, `--format text|json`) ## Skill Reference -→ `engineering/changelog-generator/SKILL.md` +→ `engineering/skills/changelog-generator/SKILL.md` diff --git a/docs/commands/code-to-prd.md b/docs/commands/code-to-prd.md index 438bee7e..a91fe09b 100644 --- a/docs/commands/code-to-prd.md +++ b/docs/commands/code-to-prd.md @@ -78,7 +78,7 @@ A `prd/` directory containing: ## Skill Reference -- `product-team/code-to-prd/SKILL.md` -- `product-team/code-to-prd/scripts/codebase_analyzer.py` -- `product-team/code-to-prd/scripts/prd_scaffolder.py` -- `product-team/code-to-prd/references/prd-quality-checklist.md` +- `product-team/code-to-prd/skills/code-to-prd/SKILL.md` +- `product-team/code-to-prd/skills/code-to-prd/scripts/codebase_analyzer.py` +- `product-team/code-to-prd/skills/code-to-prd/scripts/prd_scaffolder.py` +- `product-team/code-to-prd/skills/code-to-prd/references/prd-quality-checklist.md` diff --git a/docs/commands/competitive-matrix.md b/docs/commands/competitive-matrix.md index 25c1c004..c91cb79c 100644 --- a/docs/commands/competitive-matrix.md +++ b/docs/commands/competitive-matrix.md @@ -40,7 +40,7 @@ Build competitive matrices with weighted scoring, gap analysis, and market posit ``` ## Scripts -- `product-team/competitive-teardown/scripts/competitive_matrix_builder.py` — Matrix builder +- `product-team/skills/competitive-teardown/scripts/competitive_matrix_builder.py` — Matrix builder ## Skill Reference -→ `product-team/competitive-teardown/SKILL.md` +→ `product-team/skills/competitive-teardown/SKILL.md` diff --git a/docs/commands/cs-aeo.md b/docs/commands/cs-aeo.md index 0803ee25..d97d58eb 100644 --- a/docs/commands/cs-aeo.md +++ b/docs/commands/cs-aeo.md @@ -160,8 +160,8 @@ Content for YMYL topics scoring below threshold is unlikely to be cited regardle ## Related -- Agent: [`cs-aeo`](cs-aeo.md) -- Skill: [`aeo`](https://github.com/alirezarezvani/claude-skills/tree/main/skills/aeo/SKILL.md) +- Agent: [`cs-aeo`](https://github.com/alirezarezvani/claude-skills/tree/main/agents/marketing/cs-aeo.md) +- Skill: [`aeo`](https://github.com/alirezarezvani/claude-skills/tree/main/marketing-skill/skills/aeo/SKILL.md) - Companion: `/cs:seo-audit` (SEO + AEO often run together) - Source: ported from [`alirezarezvani/aeo-box`](https://github.com/alirezarezvani/aeo-box) diff --git a/docs/commands/cs-claude-coach.md b/docs/commands/cs-claude-coach.md index 39e8eb0f..0cf104e9 100644 --- a/docs/commands/cs-claude-coach.md +++ b/docs/commands/cs-claude-coach.md @@ -23,7 +23,7 @@ Activates the `claude-coach` skill. From this point on, the conversation gains: 2. Otherwise, ask exactly one question: **"What are your top 2-3 use cases for Claude?"** and wait. 3. Load `engineering/claude-coach/skills/claude-coach/references/cheat-codes.md`, rank techniques against the stated use cases, and present the top 5-7 with one-line explanations and one concrete example each. 4. End with: *"I'll watch your prompts going forward and surface tips when I spot an easy win — max one per response. Ask me 'rate that prompt' anytime for direct feedback."* -5. Stay active for the rest of the conversation. On every subsequent turn, run the 5-gate decision tree from `references/coaching-rules.md` before deciding whether to surface a tip. +5. Stay active for the rest of the conversation. On every subsequent turn, run the 5-gate decision tree from `skills/claude-coach/references/coaching-rules.md` before deciding whether to surface a tip. ## Examples diff --git a/docs/commands/cs-clinical-research.md b/docs/commands/cs-clinical-research.md index a1baa0c1..4b820c78 100644 --- a/docs/commands/cs-clinical-research.md +++ b/docs/commands/cs-clinical-research.md @@ -36,8 +36,8 @@ Run the `clinical-research` skill on this input: ## First run + optimization -- **Onboard first:** `python3 scripts/onboard.py` (area, alpha, power, dropout, named owners) — saved config pre-configures every tool. `--show` lists the questions. -- **Optimize (opt-in):** only if the user asks to optimize/run a loop, hand off to autoresearch via `scripts/ar_evaluator.py` (`feasibility_composite`, higher is better). +- **Onboard first:** `python3 skills/clinical-research/scripts/onboard.py` (area, alpha, power, dropout, named owners) — saved config pre-configures every tool. `--show` lists the questions. +- **Optimize (opt-in):** only if the user asks to optimize/run a loop, hand off to autoresearch via `skills/clinical-research/scripts/ar_evaluator.py` (`feasibility_composite`, higher is better). ## Distinct from diff --git a/docs/commands/cs-dossier.md b/docs/commands/cs-dossier.md index b67dec78..9481285a 100644 --- a/docs/commands/cs-dossier.md +++ b/docs/commands/cs-dossier.md @@ -79,7 +79,7 @@ Example for hypothesis "Microsoft is consolidating AI spend on Foundry": | **Disconfirming** | "Microsoft AI vendor diversification" | | **Disconfirming** | "Microsoft third-party model partnerships 2026" | -`scripts/disconfirming_evidence_balance.py` enforces the ratio. Halts at <30% and prompts more disconfirming queries. +`skills/dossier/scripts/disconfirming_evidence_balance.py` enforces the ratio. Halts at <30% and prompts more disconfirming queries. ## Source Reliability Tiering @@ -91,7 +91,7 @@ Every fact in the DOCX tagged with tier (primary / secondary / tertiary): | **Secondary** | Mainstream news (NYT, WSJ, Reuters), trade press (TechCrunch, The Information) | | **Tertiary** | Blogs, forums (Reddit, HN), Glassdoor, social media | -`scripts/source_tier_classifier.py` does this from URL. +`skills/dossier/scripts/source_tier_classifier.py` does this from URL. ## Discipline (Research-Pack Convention) diff --git a/docs/commands/cs-litreview.md b/docs/commands/cs-litreview.md index c5123e96..5df36f8a 100644 --- a/docs/commands/cs-litreview.md +++ b/docs/commands/cs-litreview.md @@ -106,7 +106,7 @@ python ../skills/litreview/scripts/framework_recommender.py --question "<Q1>" # Phase 4 cross-search aggregation + DOCX python ../skills/litreview/scripts/cross_search_aggregator.py --session NAME # Generate DOCX via Node.js docx library -python scripts/office/validate.py output.docx +python3 -c "import zipfile,sys; zipfile.ZipFile(sys.argv[1]).testzip()" output.docx # zip-integrity check; then confirm required sections present python ../skills/litreview/scripts/citation_tracker.py --action close --session NAME ``` diff --git a/docs/commands/cs-markdown-html.md b/docs/commands/cs-markdown-html.md index c8f2e9a3..07307a9c 100644 --- a/docs/commands/cs-markdown-html.md +++ b/docs/commands/cs-markdown-html.md @@ -59,6 +59,6 @@ python3 markdown-html/skills/markdown-html-orchestrator/scripts/output_path_reso - Never invent brand colors when the user hasn't onboarded. Surface onboarding. - Output is single-file HTML. External CDN is limited to Google Fonts + Prism.js. -## Foundation status (v2.10.0) +## Status -The orchestrator + `design-system` are live. Converter sub-skills (`md-document`, `md-review`, `md-slides`) land in v2.10.1 follow-up PRs. Until then, this command runs the classifier + design-system gate and returns the routing brief; Claude does the rendering inline with the design-system tokens. +All five skills are live (orchestrator + `design-system` + the three converters). This command runs the classifier + design-system gate, then hands the conversion to the routed converter sub-skill (`/cs:md-document`, `/cs:md-review`, or `/cs:md-slides`). Never render HTML inline — the converter scripts own the rendering. diff --git a/docs/commands/cs-market-research.md b/docs/commands/cs-market-research.md index f57ec49a..57717c1a 100644 --- a/docs/commands/cs-market-research.md +++ b/docs/commands/cs-market-research.md @@ -36,8 +36,8 @@ Run the `market-research` skill on this input: ## First run + optimization -- **Onboard first:** `python3 scripts/onboard.py` (market profile, survey confidence, margin of error, sizing method) — saved config pre-configures every tool. `--show` lists the questions. -- **Optimize (opt-in):** only if the user asks to reconcile the sizing/run a loop, hand off to autoresearch via `scripts/ar_evaluator.py` (`tam_divergence`, lower is better). +- **Onboard first:** `python3 skills/market-research/scripts/onboard.py` (market profile, survey confidence, margin of error, sizing method) — saved config pre-configures every tool. `--show` lists the questions. +- **Optimize (opt-in):** only if the user asks to reconcile the sizing/run a loop, hand off to autoresearch via `skills/market-research/scripts/ar_evaluator.py` (`tam_divergence`, lower is better). ## Distinct from diff --git a/docs/commands/cs-product-research.md b/docs/commands/cs-product-research.md index 539a9466..e2f28cb9 100644 --- a/docs/commands/cs-product-research.md +++ b/docs/commands/cs-product-research.md @@ -36,8 +36,8 @@ Run the `product-research` skill on this input: ## First run + optimization -- **Onboard first:** `python3 scripts/onboard.py` (product profile, insight source-threshold, saturation method, high-stakes flag) — saved config pre-configures every tool. `--show` lists the questions. -- **Optimize (opt-in):** only if the user asks to optimize the synthesis/run a loop, hand off to autoresearch via `scripts/ar_evaluator.py` (`validated_insights`, higher is better). +- **Onboard first:** `python3 skills/product-research/scripts/onboard.py` (product profile, insight source-threshold, saturation method, high-stakes flag) — saved config pre-configures every tool. `--show` lists the questions. +- **Optimize (opt-in):** only if the user asks to optimize the synthesis/run a loop, hand off to autoresearch via `skills/product-research/scripts/ar_evaluator.py` (`validated_insights`, higher is better). ## Distinct from diff --git a/docs/commands/cs-research-finance.md b/docs/commands/cs-research-finance.md index 94346939..90631a37 100644 --- a/docs/commands/cs-research-finance.md +++ b/docs/commands/cs-research-finance.md @@ -36,8 +36,8 @@ Run the `research-finance` skill on this input: ## First run + optimization -- **Onboard first:** `python3 scripts/onboard.py` (R&D area, F&A rate, runway threshold, accounting standard, finance owner) — saved config pre-configures every tool. `--show` lists the questions. -- **Optimize (opt-in):** only if the user asks to optimize/extend runway, hand off to autoresearch via `scripts/ar_evaluator.py` (`runway_months`, higher is better). +- **Onboard first:** `python3 skills/research-finance/scripts/onboard.py` (R&D area, F&A rate, runway threshold, accounting standard, finance owner) — saved config pre-configures every tool. `--show` lists the questions. +- **Optimize (opt-in):** only if the user asks to optimize/extend runway, hand off to autoresearch via `skills/research-finance/scripts/ar_evaluator.py` (`runway_months`, higher is better). ## Distinct from diff --git a/docs/commands/cs-scrape.md b/docs/commands/cs-scrape.md index c95c0d8f..52563145 100644 --- a/docs/commands/cs-scrape.md +++ b/docs/commands/cs-scrape.md @@ -1,6 +1,6 @@ --- title: "/cs-scrape — Slash Command for AI Coding Agents" -description: "Execute a scraping task for a specific URL.. Slash command for Claude Code, Codex CLI, Gemini CLI." +description: "Route, extract, and validate a scraping job (URL or local file) via the universal-scraping-architect skill — refuses to deliver unvalidated data.. Slash command for Claude Code, Codex CLI, Gemini CLI." --- # /cs-scrape @@ -10,4 +10,32 @@ description: "Execute a scraping task for a specific URL.. Slash command for Cla <span class="meta-badge">:material-github: <a href="https://github.com/alirezarezvani/2-claude-skills/tree/main/engineering/universal-scraping-architect/commands/cs-scrape.md">Source</a></span> </div> -Triggers the scraping architect to analyze and extract data from the target URL. + +Run a gated extraction pipeline for `$ARGUMENTS` using `skills/universal-scraping-architect/SKILL.md`. + +## Pre-flight gates (stop if any fails) + +1. **Target stated?** If `$ARGUMENTS` is empty, ask for the URL or file path plus the desired output format — do not guess. +2. **Live-site etiquette:** for URLs, check `robots.txt` and plan rate limits; refuse disallowed targets. +3. **Privacy:** if the target is a local/sensitive file, do not send it to an external API — force Mode 2 (local Python). +4. **Secrets:** Firecrawl key only via `os.getenv('FIRECRAWL_API_KEY')`; if a key appears inline anywhere, fix that first. + +## Workflow + +1. **Route** — state the mode and why (per the skill's routing rules): + Mode 1 Firecrawl (public/JS-heavy URL, bulk crawl) · Mode 2 local Python (local files, private data, simple static HTML) · Mode 3 hybrid (Firecrawl extract + pandas clean). +2. **Budget** — estimate API quota / token limits before multi-page jobs; add checkpointing + pagination. +3. **Extract** — start from the matching runner template (run from the plugin root; `--sample` previews the summary shape offline): + ```bash + python3 skills/universal-scraping-architect/scripts/firecrawl_example.py --sample + python3 skills/universal-scraping-architect/scripts/local_bs4_example.py --sample + ``` +4. **Validate (mandatory, exit-code gated):** + ```bash + python3 skills/universal-scraping-architect/scripts/validate_extraction.py extracted_output.json --json + ``` + - exit 0 (`status: ok`) → continue + - exit 1 (`warning` = empty output, `error` = malformed JSON) → fix and re-extract; **never deliver unvalidated data** + + Then check required fields and duplicates against the job spec. +5. **Deliver** — CSV (tabular) / JSON (nested) / Markdown (docs, chunked), per the user's requested format, with a summary of mode chosen, row counts, empty values, and the validation verdict. diff --git a/docs/commands/cs-webinar.md b/docs/commands/cs-webinar.md index 3bfc3607..b1d8edb8 100644 --- a/docs/commands/cs-webinar.md +++ b/docs/commands/cs-webinar.md @@ -38,7 +38,7 @@ The `cs-webinar` command is the **entry point for webinar workflows**: plan → Walks the intake, locks the promise + format, sizes the funnel backward from the business goal, builds the promotion runway, and designs show-up + live-to-close + follow-up. Delivers a full plan -using `templates/webinar-plan-template.md`. +using `marketing-skill/skills/webinar-marketing/templates/webinar-plan-template.md`. ### `rescue` — Diagnose and fix an underperforming webinar diff --git a/docs/commands/financial-health.md b/docs/commands/financial-health.md index 3c5c1551..502deba1 100644 --- a/docs/commands/financial-health.md +++ b/docs/commands/financial-health.md @@ -32,13 +32,13 @@ Analyze financial statements, build valuation models, assess budget variances, a ``` ## Scripts -- `finance/financial-analyst/scripts/ratio_calculator.py` — Profitability, liquidity, leverage, efficiency, valuation ratios -- `finance/financial-analyst/scripts/dcf_valuation.py` — DCF enterprise and equity valuation with sensitivity analysis -- `finance/financial-analyst/scripts/budget_variance_analyzer.py` — Actual vs budget vs prior year variance analysis -- `finance/financial-analyst/scripts/forecast_builder.py` — Driver-based revenue forecasting with scenario modeling +- `finance/skills/financial-analyst/scripts/ratio_calculator.py` — Profitability, liquidity, leverage, efficiency, valuation ratios +- `finance/skills/financial-analyst/scripts/dcf_valuation.py` — DCF enterprise and equity valuation with sensitivity analysis +- `finance/skills/financial-analyst/scripts/budget_variance_analyzer.py` — Actual vs budget vs prior year variance analysis +- `finance/skills/financial-analyst/scripts/forecast_builder.py` — Driver-based revenue forecasting with scenario modeling ## Skill Reference -→ `finance/financial-analyst/SKILL.md` +→ `finance/skills/financial-analyst/SKILL.md` ## Related Commands - `/saas-health` — SaaS-specific metrics (ARR, MRR, churn, CAC, LTV, Quick Ratio) diff --git a/docs/commands/google-workspace.md b/docs/commands/google-workspace.md index af3d2d1b..fad8c41f 100644 --- a/docs/commands/google-workspace.md +++ b/docs/commands/google-workspace.md @@ -39,45 +39,45 @@ Google Workspace CLI administration via the `gws` CLI. Run setup diagnostics, se ## Scripts -- `engineering-team/google-workspace-cli/scripts/gws_doctor.py` — Pre-flight diagnostics -- `engineering-team/google-workspace-cli/scripts/auth_setup_guide.py` — Auth setup guide -- `engineering-team/google-workspace-cli/scripts/gws_recipe_runner.py` — Recipe catalog & runner -- `engineering-team/google-workspace-cli/scripts/workspace_audit.py` — Security audit -- `engineering-team/google-workspace-cli/scripts/output_analyzer.py` — JSON/NDJSON analyzer +- `engineering-team/google-workspace-cli/skills/google-workspace-cli/scripts/gws_doctor.py` — Pre-flight diagnostics +- `engineering-team/google-workspace-cli/skills/google-workspace-cli/scripts/auth_setup_guide.py` — Auth setup guide +- `engineering-team/google-workspace-cli/skills/google-workspace-cli/scripts/gws_recipe_runner.py` — Recipe catalog & runner +- `engineering-team/google-workspace-cli/skills/google-workspace-cli/scripts/workspace_audit.py` — Security audit +- `engineering-team/google-workspace-cli/skills/google-workspace-cli/scripts/output_analyzer.py` — JSON/NDJSON analyzer ## Subcommands ### setup Run pre-flight diagnostics and auth validation. ```bash -python3 engineering-team/google-workspace-cli/scripts/gws_doctor.py [--json] -python3 engineering-team/google-workspace-cli/scripts/auth_setup_guide.py --validate [--json] +python3 engineering-team/google-workspace-cli/skills/google-workspace-cli/scripts/gws_doctor.py [--json] +python3 engineering-team/google-workspace-cli/skills/google-workspace-cli/scripts/auth_setup_guide.py --validate [--json] ``` ### audit Run security and configuration audit. ```bash -python3 engineering-team/google-workspace-cli/scripts/workspace_audit.py [--services gmail,drive,calendar] [--json] +python3 engineering-team/google-workspace-cli/skills/google-workspace-cli/scripts/workspace_audit.py [--services gmail,drive,calendar] [--json] ``` ### recipe Browse, search, and execute the 43 built-in gws recipes. ```bash -python3 engineering-team/google-workspace-cli/scripts/gws_recipe_runner.py --list [--persona <role>] [--json] -python3 engineering-team/google-workspace-cli/scripts/gws_recipe_runner.py --search <keyword> [--json] -python3 engineering-team/google-workspace-cli/scripts/gws_recipe_runner.py --describe <name> -python3 engineering-team/google-workspace-cli/scripts/gws_recipe_runner.py --run <name> [--dry-run] +python3 engineering-team/google-workspace-cli/skills/google-workspace-cli/scripts/gws_recipe_runner.py --list [--persona <role>] [--json] +python3 engineering-team/google-workspace-cli/skills/google-workspace-cli/scripts/gws_recipe_runner.py --search <keyword> [--json] +python3 engineering-team/google-workspace-cli/skills/google-workspace-cli/scripts/gws_recipe_runner.py --describe <name> +python3 engineering-team/google-workspace-cli/skills/google-workspace-cli/scripts/gws_recipe_runner.py --run <name> [--dry-run] ``` ### analyze Parse, filter, and aggregate JSON output from any gws command. ```bash -gws <command> --json | python3 engineering-team/google-workspace-cli/scripts/output_analyzer.py [options] -python3 engineering-team/google-workspace-cli/scripts/output_analyzer.py --demo --format table +gws <command> --json | python3 engineering-team/google-workspace-cli/skills/google-workspace-cli/scripts/output_analyzer.py [options] +python3 engineering-team/google-workspace-cli/skills/google-workspace-cli/scripts/output_analyzer.py --demo --format table ``` ## Skill Reference --> `engineering-team/google-workspace-cli/SKILL.md` +-> `engineering-team/google-workspace-cli/skills/google-workspace-cli/SKILL.md` ## Related Commands - No direct dependencies (self-contained Google Workspace skill) diff --git a/docs/commands/index.md b/docs/commands/index.md index 50ae452b..427cfcf7 100644 --- a/docs/commands/index.md +++ b/docs/commands/index.md @@ -143,7 +143,7 @@ description: "92 slash commands for Claude Code, Codex CLI, and Gemini CLI — s --- - Generate a concise product requirements document for a feature, initiative, or problem statement. + Generate a concise, evidence-gated product requirements document for $ARGUMENTS. - :material-console:{ .lg .middle } **[`/project-health`](project-health.md)** @@ -191,7 +191,7 @@ description: "92 slash commands for Claude Code, Codex CLI, and Gemini CLI — s --- - 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. ... - :material-console:{ .lg .middle } **[`/tc`](tc.md)** @@ -203,7 +203,7 @@ description: "92 slash commands for Claude Code, Codex CLI, and Gemini CLI — s --- - 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 (... - :material-console:{ .lg .middle } **[`/tech-debt`](tech-debt.md)** @@ -281,7 +281,7 @@ description: "92 slash commands for Claude Code, Codex CLI, and Gemini CLI — s --- - Triggers the scraping architect to analyze and extract data from the target URL. + Run a gated extraction pipeline for $ARGUMENTS using skills/universal-scraping-architect/SKILL.md. - :material-console:{ .lg .middle } **[`/cs-workflow-build`](cs-workflow-build.md)** diff --git a/docs/commands/karpathy-check.md b/docs/commands/karpathy-check.md index 6c74c1fc..2d10f99f 100644 --- a/docs/commands/karpathy-check.md +++ b/docs/commands/karpathy-check.md @@ -10,6 +10,9 @@ description: "Run Karpathy's 4-principle review on staged changes or the last co <span class="meta-badge">:material-github: <a href="https://github.com/alirezarezvani/claude-skills/tree/main/commands/karpathy-check.md">Source</a></span> </div> +<!-- canonical copy: engineering/karpathy-coder/commands/karpathy-check.md — keep in sync (root copy uses repo-root-relative script paths) --> + +# /karpathy-check Review your staged changes (or last commit) against Karpathy's 4 coding principles. @@ -22,8 +25,8 @@ Review your staged changes (or last commit) against Karpathy's 4 coding principl ## What it runs -1. **Principle #2 (Simplicity):** `scripts/complexity_checker.py` on all changed files — detects over-engineering, premature abstractions, deep nesting, long functions -2. **Principle #3 (Surgical):** `scripts/diff_surgeon.py` on the diff — detects comment-only changes, whitespace noise, style drift, drive-by refactors +1. **Principle #2 (Simplicity):** `engineering/karpathy-coder/skills/karpathy-coder/scripts/complexity_checker.py` on all changed files — detects over-engineering, premature abstractions, deep nesting, long functions +2. **Principle #3 (Surgical):** `engineering/karpathy-coder/skills/karpathy-coder/scripts/diff_surgeon.py` on the diff — detects comment-only changes, whitespace noise, style drift, drive-by refactors 3. **Principles #1 + #4 (Think + Goals):** The `karpathy-reviewer` agent reads the diff and applies human-judgment checks — hidden assumptions, missing verification ## Output @@ -42,11 +45,11 @@ Dispatches the `karpathy-reviewer` agent. See `agents/karpathy-reviewer.md`. ## Scripts -- `engineering/karpathy-coder/scripts/complexity_checker.py` -- `engineering/karpathy-coder/scripts/diff_surgeon.py` -- `engineering/karpathy-coder/scripts/assumption_linter.py` -- `engineering/karpathy-coder/scripts/goal_verifier.py` +- `engineering/karpathy-coder/skills/karpathy-coder/scripts/complexity_checker.py` +- `engineering/karpathy-coder/skills/karpathy-coder/scripts/diff_surgeon.py` +- `engineering/karpathy-coder/skills/karpathy-coder/scripts/assumption_linter.py` +- `engineering/karpathy-coder/skills/karpathy-coder/scripts/goal_verifier.py` ## Skill Reference -→ `engineering/karpathy-coder/SKILL.md` +→ `engineering/karpathy-coder/skills/karpathy-coder/SKILL.md` diff --git a/docs/commands/okr.md b/docs/commands/okr.md index 0bf33789..6cd08866 100644 --- a/docs/commands/okr.md +++ b/docs/commands/okr.md @@ -37,7 +37,7 @@ Pass a strategy keyword directly. The generator produces company, department, an ``` ## Scripts -- `product-team/product-strategist/scripts/okr_cascade_generator.py` — OKR cascade generator (`<strategy> [--teams "A,B,C"] [--contribution 0.3] [--json]`) +- `product-team/skills/product-strategist/scripts/okr_cascade_generator.py` — OKR cascade generator (`<strategy> [--teams "A,B,C"] [--contribution 0.3] [--json]`) ## Skill Reference -> `product-team/product-strategist/SKILL.md` +> `product-team/skills/product-strategist/SKILL.md` diff --git a/docs/commands/persona.md b/docs/commands/persona.md index eaa9a6ba..b82c6a03 100644 --- a/docs/commands/persona.md +++ b/docs/commands/persona.md @@ -40,7 +40,7 @@ Interactive mode prompts for product context. Alternatively, provide context inl ``` ## Scripts -- `product-team/ux-researcher-designer/scripts/persona_generator.py` — Persona generator (positional `json` arg for JSON output) +- `product-team/skills/ux-researcher-designer/scripts/persona_generator.py` — Persona generator (positional `json` arg for JSON output) ## Skill Reference -> `product-team/ux-researcher-designer/SKILL.md` +> `product-team/skills/ux-researcher-designer/SKILL.md` diff --git a/docs/commands/pipeline.md b/docs/commands/pipeline.md index 6ece8c73..7ca034ac 100644 --- a/docs/commands/pipeline.md +++ b/docs/commands/pipeline.md @@ -29,8 +29,8 @@ Detect project stack and generate CI/CD pipeline configurations for GitHub Actio ``` ## Scripts -- `engineering/ci-cd-pipeline-builder/scripts/stack_detector.py` — Detect stack and tooling (`--repo <path>`, `--format text|json`) -- `engineering/ci-cd-pipeline-builder/scripts/pipeline_generator.py` — Generate pipeline YAML (`--platform github|gitlab`, `--repo <path>`, `--input <stack.json>`, `--output <file>`) +- `engineering/skills/ci-cd-pipeline-builder/scripts/stack_detector.py` — Detect stack and tooling (`--repo <path>`, `--format text|json`) +- `engineering/skills/ci-cd-pipeline-builder/scripts/pipeline_generator.py` — Generate pipeline YAML (`--platform github|gitlab`, `--repo <path>`, `--input <stack.json>`, `--output <file>`) ## Skill Reference -→ `engineering/ci-cd-pipeline-builder/SKILL.md` +→ `engineering/skills/ci-cd-pipeline-builder/SKILL.md` diff --git a/docs/commands/plugin-audit.md b/docs/commands/plugin-audit.md index 900456b0..88731df0 100644 --- a/docs/commands/plugin-audit.md +++ b/docs/commands/plugin-audit.md @@ -62,7 +62,7 @@ Auditing: code-to-prd Run the skill-tester validator. ```bash -python3 engineering/skill-tester/scripts/skill_validator.py {skill_path} --tier {detected_tier} --json +python3 engineering/skills/skill-tester/scripts/skill_validator.py {skill_path} --tier {detected_tier} --json ``` Parse the JSON output. Extract: @@ -85,7 +85,7 @@ Parse the JSON output. Extract: Run the quality scorer. ```bash -python3 engineering/skill-tester/scripts/quality_scorer.py {skill_path} --detailed --json +python3 engineering/skills/skill-tester/scripts/quality_scorer.py {skill_path} --detailed --json ``` Parse the JSON output. Extract: @@ -102,7 +102,7 @@ Parse the JSON output. Extract: If the skill has `scripts/` with `.py` files, run the script tester. ```bash -python3 engineering/skill-tester/scripts/script_tester.py {skill_path} --json --verbose +python3 engineering/skills/skill-tester/scripts/script_tester.py {skill_path} --json --verbose ``` Parse the JSON output. For each script, extract: @@ -120,7 +120,7 @@ Parse the JSON output. For each script, extract: Run the skill security auditor. ```bash -python3 engineering/skill-security-auditor/scripts/skill_security_auditor.py {skill_path} --strict --json +python3 engineering/skills/skill-security-auditor/scripts/skill_security_auditor.py {skill_path} --strict --json ``` Parse the JSON output. Extract: @@ -305,10 +305,10 @@ Present results as a structured table: | Tool | Path | |------|------| -| Skill Validator | `engineering/skill-tester/scripts/skill_validator.py` | -| Quality Scorer | `engineering/skill-tester/scripts/quality_scorer.py` | -| Script Tester | `engineering/skill-tester/scripts/script_tester.py` | -| Security Auditor | `engineering/skill-security-auditor/scripts/skill_security_auditor.py` | +| Skill Validator | `engineering/skills/skill-tester/scripts/skill_validator.py` | +| Quality Scorer | `engineering/skills/skill-tester/scripts/quality_scorer.py` | +| Script Tester | `engineering/skills/skill-tester/scripts/script_tester.py` | +| Security Auditor | `engineering/skills/skill-security-auditor/scripts/skill_security_auditor.py` | | Quality Standards | `standards/quality/quality-standards.md` | | Security Standards | `standards/security/security-standards.md` | | Git Standards | `standards/git/git-workflow-standards.md` | diff --git a/docs/commands/prd.md b/docs/commands/prd.md index 3c829839..0c245e0f 100644 --- a/docs/commands/prd.md +++ b/docs/commands/prd.md @@ -1,6 +1,6 @@ --- title: "/prd — Slash Command for AI Coding Agents" -description: "Quick PRD generation command. Usage: /prd <feature-or-problem>. Slash command for Claude Code, Codex CLI, Gemini CLI." +description: "Gated PRD generation — interrogates problem, user, and metric before drafting; refuses to draft on unknowns. Usage: /prd <feature-or-problem>. Slash command for Claude Code, Codex CLI, Gemini CLI." --- # /prd @@ -11,7 +11,7 @@ description: "Quick PRD generation command. Usage: /prd <feature-or-problem>. Sl </div> -Generate a concise product requirements document for a feature, initiative, or problem statement. +Generate a concise, evidence-gated product requirements document for `$ARGUMENTS`. ## Usage @@ -19,13 +19,53 @@ Generate a concise product requirements document for a feature, initiative, or p /prd <feature-or-problem> ``` -## 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/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/docs/commands/project-health.md b/docs/commands/project-health.md index 5ad388bd..2f2b1987 100644 --- a/docs/commands/project-health.md +++ b/docs/commands/project-health.md @@ -42,8 +42,8 @@ Generate portfolio health dashboards and risk matrices for project oversight. ``` ## Scripts -- `project-management/senior-pm/scripts/project_health_dashboard.py` — Health dashboard (`<data_file> [--format text|json]`) -- `project-management/senior-pm/scripts/risk_matrix_analyzer.py` — Risk matrix analyzer (`<data_file> [--format text|json]`) +- `project-management/skills/senior-pm/scripts/project_health_dashboard.py` — Health dashboard (`<data_file> [--format text|json]`) +- `project-management/skills/senior-pm/scripts/risk_matrix_analyzer.py` — Risk matrix analyzer (`<data_file> [--format text|json]`) ## Skill Reference -> `project-management/senior-pm/SKILL.md` +> `project-management/skills/senior-pm/SKILL.md` diff --git a/docs/commands/retro.md b/docs/commands/retro.md index 1fa62232..050b68a2 100644 --- a/docs/commands/retro.md +++ b/docs/commands/retro.md @@ -42,7 +42,7 @@ Analyze retrospective data for recurring themes, sentiment trends, and action it ``` ## Scripts -- `project-management/scrum-master/scripts/retrospective_analyzer.py` — Retrospective analyzer (`<data_file> [--format text|json]`) +- `project-management/skills/scrum-master/scripts/retrospective_analyzer.py` — Retrospective analyzer (`<data_file> [--format text|json]`) ## Skill Reference -> `project-management/scrum-master/SKILL.md` +> `project-management/skills/scrum-master/SKILL.md` diff --git a/docs/commands/rice.md b/docs/commands/rice.md index 98777500..357f1796 100644 --- a/docs/commands/rice.md +++ b/docs/commands/rice.md @@ -39,7 +39,7 @@ Mobile app,20000,3,0.5,13 ``` ## Scripts -- `product-team/product-manager-toolkit/scripts/rice_prioritizer.py` — RICE prioritizer (`<input.csv> [--capacity N] [--output text|json|csv]`) +- `product-team/skills/product-manager-toolkit/scripts/rice_prioritizer.py` — RICE prioritizer (`<input.csv> [--capacity N] [--output text|json|csv]`) ## Skill Reference -> `product-team/product-manager-toolkit/SKILL.md` +> `product-team/skills/product-manager-toolkit/SKILL.md` diff --git a/docs/commands/saas-health.md b/docs/commands/saas-health.md index d0c95b6f..426793e0 100644 --- a/docs/commands/saas-health.md +++ b/docs/commands/saas-health.md @@ -30,12 +30,12 @@ Calculate SaaS financial health metrics from raw business numbers, benchmark aga ``` ## Scripts -- `finance/saas-metrics-coach/scripts/metrics_calculator.py` — Core SaaS metrics (ARR, MRR, churn, CAC, LTV, NRR, payback) -- `finance/saas-metrics-coach/scripts/quick_ratio_calculator.py` — Growth efficiency ratio -- `finance/saas-metrics-coach/scripts/unit_economics_simulator.py` — 12-month forward projection +- `finance/skills/saas-metrics-coach/scripts/metrics_calculator.py` — Core SaaS metrics (ARR, MRR, churn, CAC, LTV, NRR, payback) +- `finance/skills/saas-metrics-coach/scripts/quick_ratio_calculator.py` — Growth efficiency ratio +- `finance/skills/saas-metrics-coach/scripts/unit_economics_simulator.py` — 12-month forward projection ## Skill Reference -→ `finance/saas-metrics-coach/SKILL.md` +→ `finance/skills/saas-metrics-coach/SKILL.md` ## Related Commands - `/financial-health` — Traditional financial analysis (ratios, DCF, budgets) diff --git a/docs/commands/seo-auditor.md b/docs/commands/seo-auditor.md index d4f810af..c932dc9d 100644 --- a/docs/commands/seo-auditor.md +++ b/docs/commands/seo-auditor.md @@ -94,7 +94,7 @@ For every file with YAML frontmatter, check and fix: Run on each file that has HTML output in `site/`: ```bash -python3 marketing-skill/seo-audit/scripts/seo_checker.py --file site/{path}/index.html +python3 marketing-skill/skills/seo-audit/scripts/seo_checker.py --file site/{path}/index.html ``` Parse the score. Flag any page scoring below 60. @@ -120,7 +120,7 @@ For each target file, analyze and improve: Run the content scorer on each file: ```bash -python3 marketing-skill/content-production/scripts/content_scorer.py {file_path} +python3 marketing-skill/skills/content-production/scripts/content_scorer.py {file_path} ``` Check scores for: @@ -141,10 +141,10 @@ Check scores for: Run the humanizer scorer on non-generated content (README.md files, static pages): ```bash -python3 marketing-skill/content-humanizer/scripts/humanizer_scorer.py {file_path} +python3 marketing-skill/skills/content-humanizer/scripts/humanizer_scorer.py {file_path} ``` -Flag pages scoring below 50 (too AI-sounding). For these pages, apply voice techniques from `marketing-skill/content-humanizer/references/voice-techniques.md`: +Flag pages scoring below 50 (too AI-sounding). For these pages, apply voice techniques from `marketing-skill/skills/content-humanizer/references/voice-techniques.md`: - Replace AI clichés ("delve into", "leverage", "it's important to note") - Vary sentence length - Add specific examples instead of generic statements @@ -245,7 +245,7 @@ This regenerates `site/sitemap.xml` automatically (MkDocs Material generates it Check the generated sitemap: ```bash -python3 marketing-skill/site-architecture/scripts/sitemap_analyzer.py site/sitemap.xml +python3 marketing-skill/skills/site-architecture/scripts/sitemap_analyzer.py site/sitemap.xml ``` Verify: @@ -322,22 +322,22 @@ These pages rank well for their target keywords. Only fix critical issues (broke | Tool | Path | Use | |------|------|-----| -| SEO Checker | `marketing-skill/seo-audit/scripts/seo_checker.py` | Score HTML pages 0-100 | -| Content Scorer | `marketing-skill/content-production/scripts/content_scorer.py` | Score content readability/structure/engagement | -| Humanizer Scorer | `marketing-skill/content-humanizer/scripts/humanizer_scorer.py` | Detect AI-sounding content | -| Headline Scorer | `marketing-skill/copywriting/scripts/headline_scorer.py` | Score title quality | -| SEO Optimizer | `marketing-skill/content-production/scripts/seo_optimizer.py` | Optimize content for target keyword | -| Sitemap Analyzer | `marketing-skill/site-architecture/scripts/sitemap_analyzer.py` | Analyze sitemap structure | -| Schema Validator | `marketing-skill/schema-markup/scripts/schema_validator.py` | Validate structured data | -| Topic Cluster Mapper | `marketing-skill/content-strategy/scripts/topic_cluster_mapper.py` | Group pages into content clusters | +| SEO Checker | `marketing-skill/skills/seo-audit/scripts/seo_checker.py` | Score HTML pages 0-100 | +| Content Scorer | `marketing-skill/skills/content-production/scripts/content_scorer.py` | Score content readability/structure/engagement | +| Humanizer Scorer | `marketing-skill/skills/content-humanizer/scripts/humanizer_scorer.py` | Detect AI-sounding content | +| Headline Scorer | `marketing-skill/skills/copywriting/scripts/headline_scorer.py` | Score title quality | +| SEO Optimizer | `marketing-skill/skills/content-production/scripts/seo_optimizer.py` | Optimize content for target keyword | +| Sitemap Analyzer | `marketing-skill/skills/site-architecture/scripts/sitemap_analyzer.py` | Analyze sitemap structure | +| Schema Validator | `marketing-skill/skills/schema-markup/scripts/schema_validator.py` | Validate structured data | +| Topic Cluster Mapper | `marketing-skill/skills/content-strategy/scripts/topic_cluster_mapper.py` | Group pages into content clusters | ### Reference Docs | Reference | Path | Use | |-----------|------|-----| -| SEO Audit Framework | `marketing-skill/seo-audit/references/seo-audit-reference.md` | Priority order for SEO fixes | -| AI Search Optimization | `marketing-skill/ai-seo/references/content-patterns.md` | Make content citable by AI | -| Content Optimization | `marketing-skill/content-production/references/optimization-checklist.md` | Pre-publish checklist | -| URL Design Guide | `marketing-skill/site-architecture/references/url-design-guide.md` | URL structure best practices | -| Internal Linking | `marketing-skill/site-architecture/references/internal-linking-playbook.md` | Internal linking strategy | -| AI Writing Detection | `marketing-skill/content-humanizer/references/ai-tells-checklist.md` | AI cliché removal | +| SEO Audit Framework | `marketing-skill/skills/seo-audit/references/seo-audit-reference.md` | Priority order for SEO fixes | +| 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 | +| AI Writing Detection | `marketing-skill/skills/content-humanizer/references/ai-tells-checklist.md` | AI cliché removal | diff --git a/docs/commands/sprint-health.md b/docs/commands/sprint-health.md index 6aeb68d8..91b34a71 100644 --- a/docs/commands/sprint-health.md +++ b/docs/commands/sprint-health.md @@ -42,8 +42,8 @@ Score sprint health across delivery, quality, and team metrics with velocity tre ``` ## Scripts -- `project-management/scrum-master/scripts/sprint_health_scorer.py` — Sprint health scorer (`<data_file> [--format text|json]`) -- `project-management/scrum-master/scripts/velocity_analyzer.py` — Velocity analyzer (`<data_file> [--format text|json]`) +- `project-management/skills/scrum-master/scripts/sprint_health_scorer.py` — Sprint health scorer (`<data_file> [--format text|json]`) +- `project-management/skills/scrum-master/scripts/velocity_analyzer.py` — Velocity analyzer (`<data_file> [--format text|json]`) ## Skill Reference -> `project-management/scrum-master/SKILL.md` +> `project-management/skills/scrum-master/SKILL.md` diff --git a/docs/commands/sprint-plan.md b/docs/commands/sprint-plan.md index 61d6c22e..989e66e5 100644 --- a/docs/commands/sprint-plan.md +++ b/docs/commands/sprint-plan.md @@ -1,6 +1,6 @@ --- title: "/sprint-plan — Slash Command for AI Coding Agents" -description: "Sprint planning shortcut. Usage: /sprint-plan <goal> [capacity]. Slash command for Claude Code, Codex CLI, Gemini CLI." +description: "Capacity-gated sprint planning — runs capacity math, carry-over check, and a definition-of-ready gate before committing scope. Usage: /sprint-plan. Slash command for Claude Code, Codex CLI, Gemini CLI." --- # /sprint-plan @@ -11,21 +11,64 @@ description: "Sprint planning shortcut. Usage: /sprint-plan <goal> [capacity]. S </div> -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 <goal> [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/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/docs/commands/tc.md b/docs/commands/tc.md index 71002afa..99113893 100644 --- a/docs/commands/tc.md +++ b/docs/commands/tc.md @@ -34,7 +34,7 @@ Otherwise, parse `$ARGUMENTS` as `<subcommand> <rest>` and dispatch to the match 1. Run: ```bash - python3 engineering/tc-tracker/scripts/tc_init.py --root . --json + python3 engineering/skills/tc-tracker/scripts/tc_init.py --root . --json ``` 2. If status is `already_initialized`, report current statistics and stop. 3. Otherwise report what was created and suggest `/tc create <name>` as the next step. @@ -50,7 +50,7 @@ Otherwise, parse `$ARGUMENTS` as `<subcommand> <rest>` and dispatch to the match - Motivation 3. Run: ```bash - python3 engineering/tc-tracker/scripts/tc_create.py --root . \ + python3 engineering/skills/tc-tracker/scripts/tc_create.py --root . \ --name "<slug>" --title "<title>" --scope <scope> --priority <priority> \ --summary "<summary>" --motivation "<motivation>" --json ``` @@ -68,7 +68,7 @@ Otherwise, parse `$ARGUMENTS` as `<subcommand> <rest>` and dispatch to the match - **Add a tag** → `--tag <tag>` 3. Run: ```bash - python3 engineering/tc-tracker/scripts/tc_update.py --root . --tc-id <tc-id> [flags] --json + python3 engineering/skills/tc-tracker/scripts/tc_update.py --root . --tc-id <tc-id> [flags] --json ``` 4. If exit code is non-zero, surface the error verbatim. The state machine and validator will reject invalid moves — do not retry blindly. @@ -76,24 +76,24 @@ Otherwise, parse `$ARGUMENTS` as `<subcommand> <rest>` and dispatch to the match - If `<tc-id>` is provided: ```bash - python3 engineering/tc-tracker/scripts/tc_status.py --root . --tc-id <tc-id> + python3 engineering/skills/tc-tracker/scripts/tc_status.py --root . --tc-id <tc-id> ``` - Otherwise: ```bash - python3 engineering/tc-tracker/scripts/tc_status.py --root . --all + python3 engineering/skills/tc-tracker/scripts/tc_status.py --root . --all ``` ### `resume <tc-id>` 1. Run: ```bash - python3 engineering/tc-tracker/scripts/tc_status.py --root . --tc-id <tc-id> --json + python3 engineering/skills/tc-tracker/scripts/tc_status.py --root . --tc-id <tc-id> --json ``` 2. Display the handoff block prominently: `progress_summary`, `next_steps` (numbered), `blockers`, `key_context`. 3. Ask: "Resume <tc-id> and pick up at next step 1? (y/n)" 4. If yes, run an update to record the resumption: ```bash - python3 engineering/tc-tracker/scripts/tc_update.py --root . --tc-id <tc-id> \ + python3 engineering/skills/tc-tracker/scripts/tc_update.py --root . --tc-id <tc-id> \ --note "Session resumed" --reason "session handoff" ``` 5. Begin executing the first item in `next_steps`. Do NOT re-derive context — trust the handoff. @@ -109,7 +109,7 @@ Otherwise, parse `$ARGUMENTS` as `<subcommand> <rest>` and dispatch to the match - "Test coverage status: none / partial / full" 5. Run: ```bash - python3 engineering/tc-tracker/scripts/tc_update.py --root . --tc-id <tc-id> \ + python3 engineering/skills/tc-tracker/scripts/tc_update.py --root . --tc-id <tc-id> \ --set-status deployed --reason "Approved by <approver>" --note "Approval: <approver> — <notes>" ``` Then directly edit the `approval` block via a follow-up update if your script version supports it; otherwise instruct the user to record approval in `notes`. @@ -122,11 +122,11 @@ There is no automatic HTML export in this skill. Re-validate everything instead: 1. Read the registry. 2. For each record, run: ```bash - python3 engineering/tc-tracker/scripts/tc_validator.py --record <path> --json + python3 engineering/skills/tc-tracker/scripts/tc_validator.py --record <path> --json ``` 3. Run: ```bash - python3 engineering/tc-tracker/scripts/tc_validator.py --registry docs/TC/tc_registry.json --json + python3 engineering/skills/tc-tracker/scripts/tc_validator.py --registry docs/TC/tc_registry.json --json ``` 4. Report: total records validated, any errors, paths to anything invalid. @@ -134,7 +134,7 @@ There is no automatic HTML export in this skill. Re-validate everything instead: Run the all-records summary: ```bash -python3 engineering/tc-tracker/scripts/tc_status.py --root . --all +python3 engineering/skills/tc-tracker/scripts/tc_status.py --root . --all ``` ## Iron Rules diff --git a/docs/commands/tdd.md b/docs/commands/tdd.md index 29d3eb21..3bcbfeb9 100644 --- a/docs/commands/tdd.md +++ b/docs/commands/tdd.md @@ -1,6 +1,6 @@ --- title: "/tdd — Slash Command for AI Coding Agents" -description: "Generate tests, analyze coverage, and run TDD workflows. Usage: /tdd <generate|coverage|validate> [options]. Slash command for Claude Code, Codex CLI, Gemini CLI." +description: "Run a red-green-refactor TDD workflow — generate failing tests first, implement to green, then check coverage gaps. Usage: /tdd. Slash command for Claude Code, Codex CLI, Gemini CLI." --- # /tdd @@ -11,32 +11,71 @@ description: "Generate tests, analyze coverage, and run TDD workflows. Usage: /t </div> -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 <file-or-dir> Generate tests for source files -/tdd coverage <test-dir> Analyze test coverage and gaps -/tdd validate <test-file> Validate test quality (assertions, edge cases) +## Modes + +### `/tdd generate <file-or-dir>` — 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 <coverage-report>` — 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('<path-to-lcov-or-json>').read(), 'lcov') # or 'json' / 'xml' +print(a.calculate_summary()) +for gap in a.identify_gaps(threshold=80.0): print(gap) +" ``` -## Scripts -- `engineering-team/tdd-guide/scripts/test_generator.py` — Test case generation (library module) -- `engineering-team/tdd-guide/scripts/coverage_analyzer.py` — Coverage analysis (library module) -- `engineering-team/tdd-guide/scripts/tdd_workflow.py` — TDD workflow orchestration (library module) -- `engineering-team/tdd-guide/scripts/fixture_generator.py` — Test fixture generation (library module) -- `engineering-team/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/tdd-guide/SKILL.md` +### `/tdd validate <test-file>` — 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/docs/commands/tech-debt.md b/docs/commands/tech-debt.md index 97df6081..ecb9facd 100644 --- a/docs/commands/tech-debt.md +++ b/docs/commands/tech-debt.md @@ -30,9 +30,9 @@ Scan codebases for technical debt, score severity, and generate prioritized reme ``` ## Scripts -- `engineering/tech-debt-tracker/scripts/debt_scanner.py` — Scan for debt patterns (`debt_scanner.py <directory> [--format json] [--output file]`) -- `engineering/tech-debt-tracker/scripts/debt_prioritizer.py` — Prioritize debt backlog (`debt_prioritizer.py <inventory.json> [--framework cost_of_delay|wsjf|rice] [--format json]`) -- `engineering/tech-debt-tracker/scripts/debt_dashboard.py` — Generate debt dashboard (`debt_dashboard.py [files...] [--input-dir dir] [--period weekly|monthly|quarterly] [--format json]`) +- `engineering/skills/tech-debt-tracker/scripts/debt_scanner.py` — Scan for debt patterns (`debt_scanner.py <directory> [--format json] [--output file]`) +- `engineering/skills/tech-debt-tracker/scripts/debt_prioritizer.py` — Prioritize debt backlog (`debt_prioritizer.py <inventory.json> [--framework cost_of_delay|wsjf|rice] [--format json]`) +- `engineering/skills/tech-debt-tracker/scripts/debt_dashboard.py` — Generate debt dashboard (`debt_dashboard.py [files...] [--input-dir dir] [--period weekly|monthly|quarterly] [--format json]`) ## Skill Reference -→ `engineering/tech-debt-tracker/SKILL.md` +→ `engineering/skills/tech-debt-tracker/SKILL.md` diff --git a/docs/commands/user-story.md b/docs/commands/user-story.md index 2d558f81..4568dfc7 100644 --- a/docs/commands/user-story.md +++ b/docs/commands/user-story.md @@ -43,7 +43,7 @@ Interactive mode prompts for feature context. For sprint planning, provide capac ``` ## Scripts -- `product-team/agile-product-owner/scripts/user_story_generator.py` — User story generator (positional args: `sprint <capacity>`) +- `product-team/agile-product-owner/skills/agile-product-owner/scripts/user_story_generator.py` — User story generator (positional args: `sprint <capacity>`) ## Skill Reference -> `product-team/agile-product-owner/SKILL.md` +> `product-team/agile-product-owner/skills/agile-product-owner/SKILL.md` diff --git a/docs/commands/wiki-ingest.md b/docs/commands/wiki-ingest.md index 30564308..b287b42c 100644 --- a/docs/commands/wiki-ingest.md +++ b/docs/commands/wiki-ingest.md @@ -10,6 +10,9 @@ description: "Ingest a source file from raw/ into the LLM Wiki — read, discuss <span class="meta-badge">:material-github: <a href="https://github.com/alirezarezvani/claude-skills/tree/main/commands/wiki-ingest.md">Source</a></span> </div> +<!-- canonical copy: engineering/llm-wiki/commands/wiki-ingest.md — keep in sync (root copy uses repo-root-relative script paths) --> + +# /wiki-ingest Ingest a new source into the LLM Wiki. This is the most-used command. @@ -27,13 +30,13 @@ A typical ingest touches **5-15 wiki pages**. You (the user) are in the loop: th ## What happens -1. **Prep** — runs `scripts/ingest_source.py` to get title, preview, and suggested summary path +1. **Prep** — runs `engineering/llm-wiki/skills/llm-wiki/scripts/ingest_source.py` to get title, preview, and suggested summary path 2. **Read** — reads the source directly 3. **Discuss** — reports TL;DR, key claims, which pages will be touched, any contradictions 4. **Confirm** — waits for your go-ahead (or redirects) 5. **Write** — creates the source summary, updates 5-15 pages, flags contradictions -6. **Index** — runs `scripts/update_index.py` or edits `wiki/index.md` inline -7. **Log** — runs `scripts/append_log.py --op ingest --title "<title>"` +6. **Index** — runs `engineering/llm-wiki/skills/llm-wiki/scripts/update_index.py` or edits `wiki/index.md` inline +7. **Log** — runs `engineering/llm-wiki/skills/llm-wiki/scripts/append_log.py --op ingest --title "<title>"` 8. **Report** — bulleted wikilinks to every touched page ## Sub-agent @@ -42,9 +45,9 @@ This command dispatches the `wiki-ingestor` sub-agent for the heavy lifting. See ## Scripts -- `engineering/llm-wiki/scripts/ingest_source.py` — source prep (metadata + preview) -- `engineering/llm-wiki/scripts/update_index.py` — regenerate index -- `engineering/llm-wiki/scripts/append_log.py` — log the ingest +- `engineering/llm-wiki/skills/llm-wiki/scripts/ingest_source.py` — source prep (metadata + preview) +- `engineering/llm-wiki/skills/llm-wiki/scripts/update_index.py` — regenerate index +- `engineering/llm-wiki/skills/llm-wiki/scripts/append_log.py` — log the ingest ## Rules @@ -54,5 +57,5 @@ This command dispatches the `wiki-ingestor` sub-agent for the heavy lifting. See ## Skill Reference -→ `engineering/llm-wiki/SKILL.md` -→ `engineering/llm-wiki/references/ingest-workflow.md` +→ `engineering/llm-wiki/skills/llm-wiki/SKILL.md` +→ `engineering/llm-wiki/skills/llm-wiki/references/ingest-workflow.md` diff --git a/docs/commands/wiki-init.md b/docs/commands/wiki-init.md index ab994d69..bdf1d785 100644 --- a/docs/commands/wiki-init.md +++ b/docs/commands/wiki-init.md @@ -10,6 +10,9 @@ description: "Bootstrap a fresh LLM Wiki vault with the three-layer structure, s <span class="meta-badge">:material-github: <a href="https://github.com/alirezarezvani/claude-skills/tree/main/commands/wiki-init.md">Source</a></span> </div> +<!-- canonical copy: engineering/llm-wiki/commands/wiki-init.md — keep in sync --> + +# /wiki-init Bootstrap a new LLM Wiki vault. Creates `raw/`, `wiki/{entities,concepts,sources,comparisons,synthesis}`, the index and log, and installs the schema file(s) for your LLM CLI of choice. @@ -59,8 +62,8 @@ After init: ## Script -- `engineering/llm-wiki/scripts/init_vault.py` +- `engineering/llm-wiki/skills/llm-wiki/scripts/init_vault.py` ## Skill Reference -→ `engineering/llm-wiki/SKILL.md` +→ `engineering/llm-wiki/skills/llm-wiki/SKILL.md` diff --git a/docs/commands/wiki-lint.md b/docs/commands/wiki-lint.md index 354fe96e..503386b9 100644 --- a/docs/commands/wiki-lint.md +++ b/docs/commands/wiki-lint.md @@ -10,6 +10,9 @@ description: "Run a health check on the LLM Wiki vault — mechanical checks (or <span class="meta-badge">:material-github: <a href="https://github.com/alirezarezvani/claude-skills/tree/main/commands/wiki-lint.md">Source</a></span> </div> +<!-- canonical copy: engineering/llm-wiki/commands/wiki-lint.md — keep in sync (root copy uses repo-root-relative script paths) --> + +# /wiki-lint Health-check the wiki. Surfaces orphan pages, broken wikilinks, stale claims, missing frontmatter, contradictions, and structural drift. **Reports, doesn't silently fix** — you decide what to change. @@ -27,8 +30,8 @@ Run this weekly, after batch ingests, and always before sharing the wiki. ### Pass 1 — Mechanical (scripts) -- `scripts/lint_wiki.py` — orphans, broken links, stale pages, missing frontmatter, duplicate titles, log gap -- `scripts/graph_analyzer.py` — hubs, sinks, connected components, graph stats +- `engineering/llm-wiki/skills/llm-wiki/scripts/lint_wiki.py` — orphans, broken links, stale pages, missing frontmatter, duplicate titles, log gap +- `engineering/llm-wiki/skills/llm-wiki/scripts/graph_analyzer.py` — hubs, sinks, connected components, graph stats ### Pass 2 — Semantic (LLM reads and thinks) @@ -70,9 +73,9 @@ Dispatches the `wiki-linter` sub-agent. See `agents/wiki-linter.md`. ## Scripts -- `engineering/llm-wiki/scripts/lint_wiki.py` -- `engineering/llm-wiki/scripts/graph_analyzer.py` -- `engineering/llm-wiki/scripts/append_log.py` +- `engineering/llm-wiki/skills/llm-wiki/scripts/lint_wiki.py` +- `engineering/llm-wiki/skills/llm-wiki/scripts/graph_analyzer.py` +- `engineering/llm-wiki/skills/llm-wiki/scripts/append_log.py` ## Frequency @@ -85,5 +88,5 @@ Dispatches the `wiki-linter` sub-agent. See `agents/wiki-linter.md`. ## Skill Reference -→ `engineering/llm-wiki/SKILL.md` -→ `engineering/llm-wiki/references/lint-workflow.md` +→ `engineering/llm-wiki/skills/llm-wiki/SKILL.md` +→ `engineering/llm-wiki/skills/llm-wiki/references/lint-workflow.md` diff --git a/docs/commands/wiki-log.md b/docs/commands/wiki-log.md index 189d2912..b2f08469 100644 --- a/docs/commands/wiki-log.md +++ b/docs/commands/wiki-log.md @@ -10,6 +10,9 @@ description: "Show recent entries from the LLM Wiki log (wiki/log.md). Uses the <span class="meta-badge">:material-github: <a href="https://github.com/alirezarezvani/claude-skills/tree/main/commands/wiki-log.md">Source</a></span> </div> +<!-- canonical copy: engineering/llm-wiki/commands/wiki-log.md — keep in sync --> + +# /wiki-log Show recent entries from `wiki/log.md`. Every LLM operation on the wiki leaves a standardized entry: @@ -67,4 +70,4 @@ Filed back to comparisons/sae-vs-probing.md. ## Skill Reference -→ `engineering/llm-wiki/SKILL.md` +→ `engineering/llm-wiki/skills/llm-wiki/SKILL.md` diff --git a/docs/commands/wiki-query.md b/docs/commands/wiki-query.md index 022cc752..ccbc6d70 100644 --- a/docs/commands/wiki-query.md +++ b/docs/commands/wiki-query.md @@ -10,6 +10,9 @@ description: "Query the LLM Wiki — reads index.md first, drills into 3-10 rele <span class="meta-badge">:material-github: <a href="https://github.com/alirezarezvani/claude-skills/tree/main/commands/wiki-query.md">Source</a></span> </div> +<!-- canonical copy: engineering/llm-wiki/commands/wiki-query.md — keep in sync (root copy uses repo-root-relative script paths) --> + +# /wiki-query Ask the wiki a question. The librarian reads `index.md` first, picks relevant pages across categories, synthesizes an answer with citations, and offers to file the answer back into the wiki so your explorations compound. @@ -28,7 +31,7 @@ Ask the wiki a question. The librarian reads `index.md` first, picks relevant pa 1. **Index-first read** — reads `wiki/index.md` to find relevant pages 2. **Drill-in** — reads 3-10 pages in full (synthesis + concepts + sources + entities) 3. **Follow links** — opportunistically follows wikilinks between pages -4. **Fallback search** — if the index isn't enough, runs `scripts/wiki_search.py` (BM25) +4. **Fallback search** — if the index isn't enough, runs `engineering/llm-wiki/skills/llm-wiki/scripts/wiki_search.py` (BM25) 5. **Synthesize** — composes a direct answer + supporting detail + inline `[[sources/xxx]]` citations + "Related pages" section 6. **Offer to file back** — asks whether to save this as a new wiki page (usually in `comparisons/` or `synthesis/`) @@ -49,8 +52,8 @@ This command dispatches the `wiki-librarian` sub-agent. See `agents/wiki-librari ## Scripts -- `engineering/llm-wiki/scripts/wiki_search.py` — BM25 fallback search -- `engineering/llm-wiki/scripts/append_log.py` — log filed answers +- `engineering/llm-wiki/skills/llm-wiki/scripts/wiki_search.py` — BM25 fallback search +- `engineering/llm-wiki/skills/llm-wiki/scripts/append_log.py` — log filed answers ## Rules @@ -60,5 +63,5 @@ This command dispatches the `wiki-librarian` sub-agent. See `agents/wiki-librari ## Skill Reference -→ `engineering/llm-wiki/SKILL.md` -→ `engineering/llm-wiki/references/query-workflow.md` +→ `engineering/llm-wiki/skills/llm-wiki/SKILL.md` +→ `engineering/llm-wiki/skills/llm-wiki/references/query-workflow.md` diff --git a/docs/custom-gpts.md b/docs/custom-gpts.md index 0c9feaa2..b1fbd480 100644 --- a/docs/custom-gpts.md +++ b/docs/custom-gpts.md @@ -81,7 +81,7 @@ These 6 Custom GPTs package production-grade workflows from the Agent Skills lib |---|---|---| | **Platform** | ChatGPT | Claude Code, Codex, Gemini CLI, Cursor, + 7 more | | **Setup** | Click a link | `git clone` + install script | -| **Depth** | 1 skill per GPT | 337 skills, 90+ agents, 3 personas | +| **Depth** | 1 skill per GPT | 345 skills, 90+ agents, 3 personas | | **Customization** | Use as-is | Full source, MIT licensed, extend freely | | **Context** | Chat-based | Integrated into your codebase and workflow | | **Best for** | Quick access, exploration | Daily development workflow | @@ -95,7 +95,7 @@ The GPTs are a **preview** of what the full library offers. If you find a GPT us These GPTs are powered by the same skill definitions used by thousands of developers: - **4,600+ GitHub stars** · **500+ forks** · **7,400+ unique cloners** (last 14 days) -- **337 production-ready skills** across engineering, product, marketing, compliance, and more +- **345 production-ready skills** across engineering, product, marketing, compliance, and more - **13 AI coding tools** supported natively [Browse All Skills](skills/index.md){ .md-button .md-button--primary } diff --git a/docs/getting-started.md b/docs/getting-started.md index 12fe7889..0fd8500e 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -1,6 +1,6 @@ --- title: Install Agent Skills — Claude Code, Codex, Gemini CLI Setup -description: "How to install 337 agent skills and 66 plugins in any of 13 AI coding tools. Step-by-step setup for Claude Code, OpenAI Codex, Gemini CLI, Hermes Agent, Mistral Vibe, OpenClaw, Cursor, Aider, Windsurf, and more — most take under two minutes." +description: "How to install 345 agent skills and 78 plugins in any of 13 AI coding tools. Step-by-step setup for Claude Code, OpenAI Codex, Gemini CLI, Hermes Agent, Mistral Vibe, OpenClaw, Cursor, Aider, Windsurf, and more — most take under two minutes." --- # Getting Started @@ -91,7 +91,7 @@ Choose your platform and follow the steps: ./scripts/vibe-install.sh ``` - Skills install to `~/.vibe/skills/claude-skills/` (337 skills across 17 domains) and are automatically discovered by Vibe via `/skills` or `/<skill-name>`. See the [official Vibe docs](https://docs.mistral.ai/mistral-vibe/agents-skills) for details on the skills format. + Skills install to `~/.vibe/skills/claude-skills/` (345 skills across 17 domains) and are automatically discovered by Vibe via `/skills` or `/<skill-name>`. See the [official Vibe docs](https://docs.mistral.ai/mistral-vibe/agents-skills) for details on the skills format. Sync options: @@ -188,10 +188,11 @@ Domain bundles install a whole team of skills at once: | Bundle | Install Command | Skills | |--------|----------------|--------| | **Engineering — Core** | `/plugin install engineering-skills@claude-code-skills` | 51 | -| **Engineering — Advanced** | `/plugin install engineering-advanced-skills@claude-code-skills` | 75 | +| **Engineering — Advanced** | `/plugin install engineering-advanced-skills@claude-code-skills` | 74 | | **Product** | `/plugin install product-skills@claude-code-skills` | 17 | -| **Marketing** | `/plugin install marketing-skills@claude-code-skills` | 48 | +| **Marketing** | `/plugin install marketing-skills@claude-code-skills` | 47 | | **Regulatory & Quality** | `/plugin install ra-qm-skills@claude-code-skills` | 18 | +| **Compliance OS** | `/plugin install compliance-os@claude-code-skills` | 9 | | **Project Management** | `/plugin install pm-skills@claude-code-skills` | 9 | | **C-Level Advisory** | `/plugin install c-level-skills@claude-code-skills` | 61 | | **Business & Growth** | `/plugin install business-growth-skills@claude-code-skills` | 5 | @@ -305,7 +306,7 @@ See the [Skills & Agents Factory](https://github.com/alirezarezvani/claude-code- Yes. Run `./scripts/gemini-install.sh` to set up skills for Gemini CLI. A sync script (`scripts/sync-gemini-skills.py`) generates the skills index automatically. ??? question "Does this work with Cursor, Windsurf, Aider, or other tools?" - Yes. All 337 skills can be converted to native formats for Cursor, Aider, Kilo Code, Windsurf, OpenCode, Augment, and Antigravity. Run `./scripts/convert.sh --tool all` and then install with `./scripts/install.sh --tool <name>`. See [Multi-Tool Integrations](integrations.md) for details. + Yes. All 345 skills can be converted to native formats for Cursor, Aider, Kilo Code, Windsurf, OpenCode, Augment, and Antigravity. Run `./scripts/convert.sh --tool all` and then install with `./scripts/install.sh --tool <name>`. See [Multi-Tool Integrations](integrations.md) for details. ??? question "Can I use Agent Skills in ChatGPT?" Yes. We have [6 Custom GPTs](custom-gpts.md) that bring Agent Skills directly into ChatGPT — no installation needed. Just click and start chatting. diff --git a/docs/guides/agent-skills-for-codex.md b/docs/guides/agent-skills-for-codex.md index c846a9fe..377869a8 100644 --- a/docs/guides/agent-skills-for-codex.md +++ b/docs/guides/agent-skills-for-codex.md @@ -1,11 +1,11 @@ --- title: "Agent Skills for OpenAI Codex CLI (2026)" -description: "Install and use 337 agent skills with OpenAI Codex CLI. Engineering, marketing, product, and DevOps plugins for Codex." +description: "Install and use 345 agent skills with OpenAI Codex CLI. Engineering, marketing, product, and DevOps plugins for Codex." --- # Agent Skills for OpenAI Codex CLI -Use 337 production-ready agent skills with OpenAI Codex CLI. Every skill in this collection works natively with Codex via the `.codex/skills/` directory format. +Use 345 production-ready agent skills with OpenAI Codex CLI. Every skill in this collection works natively with Codex via the `.codex/skills/` directory format. --- @@ -94,7 +94,7 @@ cp -r claude-skills/.codex/skills/ ~/.codex/skills/ ## Full Skill Catalog -All 337 skills organized by domain: +All 345 skills organized by domain: | Domain | Skills | Highlights | |--------|--------|-----------| diff --git a/docs/guides/best-claude-code-plugins.md b/docs/guides/best-claude-code-plugins.md index 03983129..32481a29 100644 --- a/docs/guides/best-claude-code-plugins.md +++ b/docs/guides/best-claude-code-plugins.md @@ -22,7 +22,7 @@ This repo provides **both formats** — every skill includes a `.claude-plugin` ## Quick Install ```bash -# Install the full marketplace (all 337 skills as Claude Code plugins) +# Install the full marketplace (all 345 skills as Claude Code plugins) claude /plugin install https://github.com/alirezarezvani/claude-skills # Install by domain @@ -110,7 +110,7 @@ Every plugin in this collection works across multiple AI coding agents: ## Related Resources -- [Full Skill Catalog](https://github.com/alirezarezvani/claude-skills) — all 337 skills +- [Full Skill Catalog](https://github.com/alirezarezvani/claude-skills) — all 345 skills - [Agent Skills for Codex](./agent-skills-for-codex.md) — Codex-specific guide - [Gemini CLI Skills Guide](./gemini-cli-skills-guide.md) — Gemini CLI setup - [Cursor Skills Guide](./cursor-skills-guide.md) — Cursor integration diff --git a/docs/guides/cursor-skills-guide.md b/docs/guides/cursor-skills-guide.md index 05ac9e73..6301255a 100644 --- a/docs/guides/cursor-skills-guide.md +++ b/docs/guides/cursor-skills-guide.md @@ -1,11 +1,11 @@ --- title: "Cursor Agent Skills & Rules Guide (2026)" -description: "Install and use 337 agent skills with Cursor IDE. Engineering, marketing, and product plugins for Cursor's AI coding agent." +description: "Install and use 345 agent skills with Cursor IDE. Engineering, marketing, and product plugins for Cursor's AI coding agent." --- # Cursor Agent Skills Guide -Use 337 production-ready agent skills with Cursor IDE. Every skill converts to Cursor's rules format and installs via the `.cursor/skills/` directory. +Use 345 production-ready agent skills with Cursor IDE. Every skill converts to Cursor's rules format and installs via the `.cursor/skills/` directory. --- @@ -72,7 +72,7 @@ cat .cursor/skills/frontend-design/SKILL.md >> .cursorrules ## Full Catalog -All 337 skills across 17 domains. See the [full README](https://github.com/alirezarezvani/claude-skills) for the complete list. +All 345 skills across 17 domains. See the [full README](https://github.com/alirezarezvani/claude-skills) for the complete list. **Also works with:** Claude Code · OpenAI Codex · Gemini CLI · OpenClaw · Aider · Windsurf · Kilo Code · OpenCode · Augment · Antigravity diff --git a/docs/guides/gemini-cli-skills-guide.md b/docs/guides/gemini-cli-skills-guide.md index c24517a6..eb9abd34 100644 --- a/docs/guides/gemini-cli-skills-guide.md +++ b/docs/guides/gemini-cli-skills-guide.md @@ -1,11 +1,11 @@ --- title: "Gemini CLI Skills & Plugins Guide (2026)" -description: "Install and use 337 agent skills with Gemini CLI. Free evaluation calls, engineering, marketing, and DevOps skills for Google's coding agent." +description: "Install and use 345 agent skills with Gemini CLI. Free evaluation calls, engineering, marketing, and DevOps skills for Google's coding agent." --- # Gemini CLI Agent Skills Guide -Use 337 production-ready agent skills with Gemini CLI. Every skill in this collection is compatible with Gemini's agent skills specification and installs via the `.gemini/skills/` directory. +Use 345 production-ready agent skills with Gemini CLI. Every skill in this collection is compatible with Gemini's agent skills specification and installs via the `.gemini/skills/` directory. --- @@ -81,7 +81,7 @@ This repo includes `gemini-extension.json` for Gemini's extension registry: { "name": "claude-skills", "version": "2.0.0", - "description": "337 agent skills for engineering, marketing, product, and more", + "description": "345 agent skills for engineering, marketing, product, and more", "skills": ["engineering/*", "marketing-skill/*", "product-team/*", "..."] } ``` @@ -109,7 +109,7 @@ These skills work on 10 other coding agents too: Claude Code · OpenAI Codex · Cursor · OpenClaw · Aider · Windsurf · Kilo Code · OpenCode · Augment · Antigravity -See the [full catalog](https://github.com/alirezarezvani/claude-skills) for all 337 skills. +See the [full catalog](https://github.com/alirezarezvani/claude-skills) for all 345 skills. --- diff --git a/docs/guides/openclaw-skills-guide.md b/docs/guides/openclaw-skills-guide.md index 1aaaf6ea..cdcf4a23 100644 --- a/docs/guides/openclaw-skills-guide.md +++ b/docs/guides/openclaw-skills-guide.md @@ -1,11 +1,11 @@ --- title: "OpenClaw Skills Guide — Install & Use Agent Skills (2026)" -description: "Install and use 337 agent skills with OpenClaw. One-line install for engineering, marketing, product, compliance, and DevOps skills in your OpenClaw workspace." +description: "Install and use 345 agent skills with OpenClaw. One-line install for engineering, marketing, product, compliance, and DevOps skills in your OpenClaw workspace." --- # OpenClaw Skills Guide — Install & Use Agent Skills with OpenClaw -> **Last updated:** June 2026 · **Skills count:** 337 · **Compatibility:** OpenClaw v2024.12+ +> **Last updated:** June 2026 · **Skills count:** 345 · **Compatibility:** OpenClaw v2024.12+ ## What Are OpenClaw Skills? @@ -32,7 +32,7 @@ OpenClaw's skill system is the most natural fit in the ecosystem — skills live bash <(curl -s https://raw.githubusercontent.com/alirezarezvani/claude-skills/main/scripts/openclaw-install.sh) ``` -This installs all 337 skills into your OpenClaw workspace with the correct directory structure. +This installs all 345 skills into your OpenClaw workspace with the correct directory structure. ### Manual Install @@ -167,4 +167,4 @@ Use the `skill-creator` meta-skill for guided skill creation: --- -*Part of the [Claude Code Skills & Agent Plugins](https://github.com/alirezarezvani/claude-skills) repository — 337 production-ready skills for 13 AI coding tools.* +*Part of the [Claude Code Skills & Agent Plugins](https://github.com/alirezarezvani/claude-skills) repository — 345 production-ready skills for 13 AI coding tools.* diff --git a/docs/index.md b/docs/index.md index 3e2a2759..3828b4d4 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,6 +1,6 @@ --- title: Agent Skills & Plugins for Claude Code, Codex, Gemini CLI & 10 More AI Tools -description: "337 production-ready agent skills, 66 installable plugins, and 90+ slash commands across 17 domains — engineering, product, marketing, compliance, finance, and research. Works with Claude Code, OpenAI Codex, Gemini CLI, Cursor, Hermes Agent, Mistral Vibe, OpenClaw, and 6 more AI coding tools. Open source, MIT licensed, zero dependencies." +description: "345 production-ready agent skills, 78 installable plugins, and 90+ slash commands across 17 domains — engineering, product, marketing, compliance, finance, and research. Works with Claude Code, OpenAI Codex, Gemini CLI, Cursor, Hermes Agent, Mistral Vibe, OpenClaw, and 6 more AI coding tools. Open source, MIT licensed, zero dependencies." hide: - toc - edit @@ -24,10 +24,10 @@ Give your AI coding agent real domain expertise. Every skill is a self-contained [GitHub :fontawesome-brands-github:](https://github.com/alirezarezvani/claude-skills){ .md-button } <div class="stats-strip"> - <div class="stat"><span class="stat-number">337</span><span class="stat-label">Skills</span></div> + <div class="stat"><span class="stat-number">345</span><span class="stat-label">Skills</span></div> <div class="stat"><span class="stat-number">17</span><span class="stat-label">Domains</span></div> - <div class="stat"><span class="stat-number">66</span><span class="stat-label">Plugins</span></div> - <div class="stat"><span class="stat-number">550+</span><span class="stat-label">Python Tools</span></div> + <div class="stat"><span class="stat-number">78</span><span class="stat-label">Plugins</span></div> + <div class="stat"><span class="stat-number">570+</span><span class="stat-label">Python Tools</span></div> <div class="stat"><span class="stat-number">90+</span><span class="stat-label">Commands</span></div> <div class="stat"><span class="stat-number">13</span><span class="stat-label">AI Tools</span></div> </div> @@ -86,7 +86,7 @@ No API keys, no external services, no dependencies between skills. Copy a folder <div class="grid cards" markdown> -- :material-toolbox:{ .lg .middle } **337 Skills** +- :material-toolbox:{ .lg .middle } **345 Skills** --- @@ -94,7 +94,7 @@ No API keys, no external services, no dependencies between skills. Copy a folder [:octicons-arrow-right-24: Browse skills](skills/index.md) -- :material-puzzle-outline:{ .lg .middle } **66 Plugins** +- :material-puzzle-outline:{ .lg .middle } **78 Plugins** --- @@ -118,7 +118,7 @@ No API keys, no external services, no dependencies between skills. Copy a folder [:octicons-arrow-right-24: View commands](commands/index.md) -- :material-language-python:{ .lg .middle } **550+ Python Tools** +- :material-language-python:{ .lg .middle } **570+ Python Tools** --- @@ -182,7 +182,7 @@ Seventeen domains cover the full lifecycle of building a product and running a c Agent designer, RAG architect, MCP server builder, CI/CD pipelines, SLO architect, chaos engineering, security auditing, tech debt tracking - [:octicons-arrow-right-24: 75 skills](skills/engineering/index.md) + [:octicons-arrow-right-24: 74 skills](skills/engineering/index.md) - :material-bullseye-arrow:{ .lg .middle } **Product** @@ -198,7 +198,7 @@ Seventeen domains cover the full lifecycle of building a product and running a c Content, SEO, AEO, CRO, paid channels, growth, launch strategy — 8 specialist pods with bundled Python analytics tools - [:octicons-arrow-right-24: 48 skills](skills/marketing-skill/index.md) + [:octicons-arrow-right-24: 47 skills](skills/marketing-skill/index.md) - :material-star-circle:{ .lg .middle } **C-Level Advisory** diff --git a/docs/integrations.md b/docs/integrations.md index 51016c55..13dbfae5 100644 --- a/docs/integrations.md +++ b/docs/integrations.md @@ -5,7 +5,7 @@ description: "Install Claude Code skills and agent plugins in Hermes Agent, Mist # Multi-Tool Integrations -All 337 skills in this repository work with **9 AI coding tools** beyond Claude Code, Codex, Gemini CLI, and OpenClaw. Hermes Agent and Mistral Vibe both use the same agentskills.io SKILL.md standard — no conversion needed. For the other 7 tools, a conversion script adapts the format each tool expects while preserving skill instructions, workflows, and supporting files. +All 345 skills in this repository work with **9 AI coding tools** beyond Claude Code, Codex, Gemini CLI, and OpenClaw. Hermes Agent and Mistral Vibe both use the same agentskills.io SKILL.md standard — no conversion needed. For the other 7 tools, a conversion script adapts the format each tool expects while preserving skill instructions, workflows, and supporting files. <div class="grid cards" markdown> diff --git a/docs/plugins/index.md b/docs/plugins/index.md index 2685b713..47ddee44 100644 --- a/docs/plugins/index.md +++ b/docs/plugins/index.md @@ -1,13 +1,13 @@ --- -title: "Claude Code Plugin Marketplace — 66 Agent Plugins" -description: "66 installable agent plugins for Claude Code, Codex CLI, Gemini CLI, and OpenClaw. 13 domain bundles + 53 standalone packages covering engineering, marketing, product, C-level advisory, compliance, commercial, finance, productivity, and research. One-command install." +title: "Claude Code Plugin Marketplace — 78 Agent Plugins" +description: "78 installable agent plugins for Claude Code, Codex CLI, Gemini CLI, and OpenClaw. 14 domain bundles + 64 standalone packages covering engineering, marketing, product, C-level advisory, compliance, commercial, finance, productivity, and research. One-command install." --- <div class="skills-hero" markdown> # Plugins & Marketplace -**66 installable plugins** — 13 domain bundles and 53 standalone packages, distributed through the Claude Code plugin registry and ClawHub. +**78 installable plugins** — 14 domain bundles and 64 standalone packages, distributed through the Claude Code plugin registry and ClawHub. <p class="skills-hero-sub">Install an entire skill domain or a single tool with one command. Compatible with Claude Code, OpenAI Codex, Gemini CLI, and OpenClaw.</p> @@ -19,11 +19,11 @@ description: "66 installable agent plugins for Claude Code, Codex CLI, Gemini CL <div class="grid cards" markdown> -- :material-puzzle-outline:{ .lg .middle } **66 Plugins** +- :material-puzzle-outline:{ .lg .middle } **78 Plugins** --- - 13 domain bundles + 53 standalone packages + 14 domain bundles + 64 standalone packages - :material-domain:{ .lg .middle } **17 Domains** @@ -31,7 +31,7 @@ description: "66 installable agent plugins for Claude Code, Codex CLI, Gemini CL Engineering, marketing, product, C-level, compliance, commercial, operations, research, finance, productivity, and more -- :material-toolbox-outline:{ .lg .middle } **337 Skills** +- :material-toolbox-outline:{ .lg .middle } **345 Skills** --- @@ -91,18 +91,18 @@ description: "66 installable agent plugins for Claude Code, Codex CLI, Gemini CL ```mermaid graph TB subgraph Registry["Plugin Registry"] - MP["marketplace.json<br/>66 plugins"] + MP["marketplace.json<br/>78 plugins"] end - subgraph Bundles["Domain Bundles (13)"] - B1["engineering-skills · 51<br/>engineering-advanced-skills · 75"] - B2["marketing-skills · 48<br/>c-level-skills · 61"] - B3["product-skills · 17 · pm-skills · 9<br/>ra-qm-skills · 18"] + subgraph Bundles["Domain Bundles (14)"] + B1["engineering-skills · 51<br/>engineering-advanced-skills · 74"] + B2["marketing-skills · 47<br/>c-level-skills · 61"] + B3["product-skills · 17 · pm-skills · 9<br/>ra-qm-skills · 18 · compliance-os · 9"] B4["business-growth · business-operations<br/>commercial · finance"] B5["research-ops-skills · 5<br/>markdown-html-skills · 5"] end - subgraph Standalone["Standalone Plugins (53)"] + subgraph Standalone["Standalone Plugins (64)"] S1["Engineering: pw, agenthub, llm-wiki,<br/>slo-architect, chaos-engineering..."] S2["Leadership: c-level-agents,<br/>executive-mentor, vpe-advisor..."] S3["Research: pulse, litreview, grants,<br/>dossier, patent, syllabus, notebooklm"] @@ -123,11 +123,12 @@ Domain bundles install an entire skill domain — every skill, Python tool, refe | Bundle | Skills | What you get | Browse | |---|:-:|---|---| | `engineering-skills` | 51 | Full engineering team: architecture, frontend, backend, QA, DevOps, SecOps, AI/ML, data, Playwright Pro, self-improving agent | [:octicons-arrow-right-24:](../skills/engineering-team/index.md) | -| `engineering-advanced-skills` | 75 | Agent designer, RAG architect, MCP server builder, CI/CD, SLO architect, chaos engineering, security auditing, tech debt | [:octicons-arrow-right-24:](../skills/engineering/index.md) | +| `engineering-advanced-skills` | 74 | Agent designer, RAG architect, MCP server builder, CI/CD, SLO architect, chaos engineering, security auditing, tech debt | [:octicons-arrow-right-24:](../skills/engineering/index.md) | | `product-skills` | 17 | PM toolkit (RICE, PRDs), agile PO, UX research, discovery, analytics, SaaS scaffolder, Apple HIG expert | [:octicons-arrow-right-24:](../skills/product-team/index.md) | -| `marketing-skills` | 48 | Content, SEO, AEO, CRO, paid channels, growth, intelligence, sales enablement — 8 specialist pods | [:octicons-arrow-right-24:](../skills/marketing-skill/index.md) | +| `marketing-skills` | 47 | Content, SEO, AEO, CRO, paid channels, growth, intelligence, sales enablement — 8 specialist pods | [:octicons-arrow-right-24:](../skills/marketing-skill/index.md) | | `c-level-skills` | 61 | Full C-suite advisors, founder-mode boardroom, decision logger, scenario war room, M&A playbook | [:octicons-arrow-right-24:](../skills/c-level-advisor/index.md) | | `ra-qm-skills` | 18 | ISO 13485, MDR 2017/745, FDA 510(k)/PMA, ISO 27001, GDPR, CAPA, ISO 14971 risk management | [:octicons-arrow-right-24:](../skills/ra-qm-team/index.md) | +| `compliance-os` | 9 | Audit-prep orchestrator: readiness and evidence checklists for ISO 13485, ISO 27001, SOC 2, GDPR, FDA QSR, EU AI Act, ISO 42001 | [:octicons-arrow-right-24:](../skills/compliance-os/index.md) | | `pm-skills` | 9 | Senior PM, scrum master, Jira/Confluence experts, Atlassian admin with bundled remote MCP | [:octicons-arrow-right-24:](../skills/project-management/index.md) | | `business-growth-skills` | 5 | Customer success, sales engineering, revenue operations, contract & proposal writer | [:octicons-arrow-right-24:](../skills/business-growth/index.md) | | `business-operations-skills` | 7 | Process mapping, vendor management, capacity planning, internal comms, knowledge ops, procurement | [:octicons-arrow-right-24:](../skills/business-operations/index.md) | @@ -218,12 +219,13 @@ Two approved extension fields are permitted: --- -## All 66 Plugins at a Glance +## All 78 Plugins at a Glance | Plugin | Type | Category | Source | |---|---|---|---| | `business-growth-skills` | Bundle | business-growth | `./business-growth` | | `commercial-skills` | Bundle | commercial | `./commercial` | +| `compliance-os` | Bundle | compliance | `./compliance-os` | | `ra-qm-skills` | Bundle | compliance | `./ra-qm-team` | | `engineering-advanced-skills` | Bundle | development | `./engineering` | | `engineering-skills` | Bundle | development | `./engineering-team` | @@ -235,12 +237,16 @@ Two approved extension fields are permitted: | `product-skills` | Bundle | product | `./product-team` | | `pm-skills` | Bundle | project-management | `./project-management` | | `research-ops-skills` | Bundle | research-ops | `./research-ops` | +| `compliance-team-eu-ai-act` | Standalone | compliance | `./ra-qm-team/compliance-team-eu-ai-act` | +| `compliance-team-iso42001` | Standalone | compliance | `./ra-qm-team/compliance-team-iso42001` | | `apple-hig-expert` | Standalone | design | `./product-team/apple-hig-expert` | | `a11y-audit` | Standalone | development | `./engineering-team/a11y-audit` | | `agenthub` | Standalone | development | `./engineering/agenthub` | | `autoresearch-agent` | Standalone | development | `./engineering/autoresearch-agent` | +| `behuman` | Standalone | development | `./engineering/behuman` | | `caveman` | Standalone | development | `./engineering/caveman` | | `chaos-engineering` | Standalone | development | `./engineering/chaos-engineering` | +| `claude-coach` | Standalone | development | `./engineering/claude-coach` | | `code-tour` | Standalone | development | `./engineering/code-tour` | | `data-quality-auditor` | Standalone | development | `./engineering/data-quality-auditor` | | `demo-video` | Standalone | development | `./engineering/demo-video` | @@ -248,19 +254,25 @@ Two approved extension fields are permitted: | `feature-flags-architect` | Standalone | development | `./engineering/feature-flags-architect` | | `google-workspace-cli` | Standalone | development | `./engineering-team/google-workspace-cli` | | `grill-me` | Standalone | development | `./engineering/grill-me` | +| `grill-with-docs` | Standalone | development | `./engineering/grill-with-docs` | | `handoff-engineering` | Standalone | development | `./engineering/handoff` | | `helm-chart-builder` | Standalone | development | `./engineering/helm-chart-builder` | | `karpathy-coder` | Standalone | development | `./engineering/karpathy-coder` | | `kubernetes-operator` | Standalone | development | `./engineering/kubernetes-operator` | +| `llm-cost-optimizer` | Standalone | development | `./engineering/llm-cost-optimizer` | +| `prompt-governance` | Standalone | development | `./engineering/prompt-governance` | | `pw` | Standalone | development | `./engineering-team/playwright-pro` | | `security-guidance` | Standalone | development | `./engineering/security-guidance` | | `self-improving-agent` | Standalone | development | `./engineering-team/self-improving-agent` | | `slo-architect` | Standalone | development | `./engineering/slo-architect` | +| `snowflake-development` | Standalone | development | `./engineering-team/snowflake-development` | | `statistical-analyst` | Standalone | development | `./engineering/statistical-analyst` | | `terraform-patterns` | Standalone | development | `./engineering/terraform-patterns` | | `universal-scraping-architect` | Standalone | development | `./engineering/universal-scraping-architect` | | `workflow-builder` | Standalone | development | `./engineering/workflow-builder` | | `write-a-skill` | Standalone | development | `./engineering/write-a-skill` | +| `collab-proof` | Standalone | engineering | `./engineering/collab-proof` | +| `business-investment-advisor` | Standalone | finance | `./finance/business-investment-advisor` | | `llm-wiki` | Standalone | knowledge | `./engineering/llm-wiki` | | `c-level-agents` | Standalone | leadership | `./c-level-advisor/c-level-agents` | | `chief-ai-officer-advisor` | Standalone | leadership | `./c-level-advisor/chief-ai-officer-advisor` | @@ -271,6 +283,7 @@ Two approved extension fields are permitted: | `vpe-advisor` | Standalone | leadership | `./c-level-advisor/vpe-advisor` | | `aeo` | Standalone | marketing | `./marketing-skill/skills/aeo` | | `landing` | Standalone | marketing | `./marketing/landing` | +| `video-content-strategist` | Standalone | marketing | `./marketing-skill/video-content-strategist` | | `youtube-full` | Standalone | marketing | `./marketing-skill/skills/youtube-full` | | `agile-product-owner` | Standalone | product | `./product-team/agile-product-owner` | | `code-to-prd` | Standalone | product | `./product-team/code-to-prd` | diff --git a/docs/skills/business-growth/business-growth-skills.md b/docs/skills/business-growth/business-growth-skills.md index 6dc14884..a2e8e846 100644 --- a/docs/skills/business-growth/business-growth-skills.md +++ b/docs/skills/business-growth/business-growth-skills.md @@ -1,9 +1,9 @@ --- -title: "Business & Growth Skills — Agent Skill for Growth" -description: "4 business growth agent skills and plugins for Claude Code, Codex, Gemini CLI, Cursor, OpenClaw. Customer success (health scoring, churn), sales." +title: "Business & Growth Skills — Router — Agent Skill for Growth" +description: "Router/index for the 4 business & growth skills bundled in this plugin: customer-success-manager (health scoring, churn risk, expansion). Agent skill for Claude Code, Codex CLI, Gemini CLI, OpenClaw." --- -# Business & Growth Skills +# Business & Growth Skills — Router <div class="page-meta" markdown> <span class="meta-badge">:material-trending-up: Business & Growth</span> @@ -16,39 +16,28 @@ description: "4 business growth agent skills and plugins for Claude Code, Codex, </div> -4 production-ready skills for customer success, sales, and revenue operations. +This plugin bundles **4 skills** (this router is the 5th folder under `business-growth/skills/`). Each skill is self-contained. -## Quick Start +## Routing table -### Claude Code -``` -/read business-growth/customer-success-manager/SKILL.md -``` +Match the request, then load `business-growth/skills/<skill>/SKILL.md`. If multiple rows match, ask one clarifying question first. -### Codex CLI -```bash -npx agent-skills-cli add alirezarezvani/claude-skills/business-growth -``` +| Request signals | Skill | Path | +|---|---|---| +| Customer health scores, churn risk, expansion plays | customer-success-manager | `skills/customer-success-manager/` | +| RFP/RFI coverage, competitive positioning, PoC plans | sales-engineer | `skills/sales-engineer/` | +| Pipeline coverage, forecast accuracy (MAPE), GTM efficiency | revenue-operations | `skills/revenue-operations/` | +| Proposals, contracts, statements of work, DPAs | contract-and-proposal-writer | `skills/contract-and-proposal-writer/` | -## Skills Overview - -| Skill | Folder | Focus | -|-------|--------|-------| -| Customer Success Manager | `customer-success-manager/` | Health scoring, churn prediction, expansion | -| Sales Engineer | `sales-engineer/` | RFP analysis, competitive matrices, PoC planning | -| Revenue Operations | `revenue-operations/` | Pipeline analysis, forecast accuracy, GTM metrics | -| Contract & Proposal Writer | `contract-and-proposal-writer/` | Proposal generation, contract templates | - -## Python Tools - -9 scripts, all stdlib-only: +## Quick start ```bash -python3 customer-success-manager/scripts/health_score_calculator.py --help -python3 revenue-operations/scripts/pipeline_analyzer.py --help +# Example: route an account-health request +cat business-growth/skills/customer-success-manager/SKILL.md +python3 business-growth/skills/customer-success-manager/scripts/health_score_calculator.py --help ``` ## Rules -- Load only the specific skill SKILL.md you need -- Use Python tools for scoring and metrics, not manual estimates +- Route to exactly one skill, then follow that skill's workflow. This router ships no tools of its own. +- Use the skills' Python scorers for metrics, not manual estimates; deal/contract outputs are drafts for human legal/commercial review. diff --git a/docs/skills/business-growth/index.md b/docs/skills/business-growth/index.md index bf027e95..29dc3da4 100644 --- a/docs/skills/business-growth/index.md +++ b/docs/skills/business-growth/index.md @@ -17,11 +17,11 @@ description: "5 business & growth skills — business growth agent skill and Cla <div class="grid cards" markdown> -- **[Business & Growth Skills](business-growth-skills.md)** +- **[Business & Growth Skills — Router](business-growth-skills.md)** --- - 4 production-ready skills for customer success, sales, and revenue operations. + This plugin bundles 4 skills (this router is the 5th folder under business-growth/skills/). Each skill is self-contai... - **[Contract & Proposal Writer](contract-and-proposal-writer.md)** diff --git a/docs/skills/business-growth/sales-engineer.md b/docs/skills/business-growth/sales-engineer.md index f39797ee..afc0fdca 100644 --- a/docs/skills/business-growth/sales-engineer.md +++ b/docs/skills/business-growth/sales-engineer.md @@ -222,9 +222,9 @@ python scripts/poc_planner.py poc_data.json --format json # JSON output ## Integration Points -- **Marketing Skills** - Leverage competitive intelligence and messaging frameworks from [`business-growth/marketing-skill`](https://github.com/alirezarezvani/claude-skills/tree/main/business-growth/marketing-skill) -- **Product Team** - Coordinate on roadmap items flagged as "Planned" in RFP analysis from [`business-growth/product-team`](https://github.com/alirezarezvani/claude-skills/tree/main/business-growth/product-team) -- **C-Level Advisory** - Escalate strategic deals requiring executive engagement from [`business-growth/c-level-advisor`](https://github.com/alirezarezvani/claude-skills/tree/main/business-growth/c-level-advisor) +- **Marketing Skills** - Leverage competitive intelligence and messaging frameworks from `marketing-skill/` +- **Product Team** - Coordinate on roadmap items flagged as "Planned" in RFP analysis from `product-team/` +- **C-Level Advisory** - Escalate strategic deals requiring executive engagement from `c-level-advisor/` - **Customer Success** - Hand off POC results and success criteria to CSM from [`skills/customer-success-manager`](https://github.com/alirezarezvani/claude-skills/tree/main/business-growth/skills/customer-success-manager) --- diff --git a/docs/skills/business-operations/capacity-planner.md b/docs/skills/business-operations/capacity-planner.md index a272a636..5425eb7c 100644 --- a/docs/skills/business-operations/capacity-planner.md +++ b/docs/skills/business-operations/capacity-planner.md @@ -89,6 +89,13 @@ It produces three artifacts: All three accept `--input <path>` (JSON), `--output {markdown,json}`, `--sample` (built-in example), and `--help`. Stdlib only. +## Quick example + +```bash +# Emits an Erlang-C capacity model (required headcount + P50/P90/P99 breach probabilities) for the built-in example +cd business-operations/skills/capacity-planner && python3 scripts/capacity_modeler.py --sample +``` + ## References - `references/queueing_theory_canon.md` — Erlang, Little, Hopp & diff --git a/docs/skills/business-operations/internal-comms.md b/docs/skills/business-operations/internal-comms.md index 39f42488..3a3e0ab5 100644 --- a/docs/skills/business-operations/internal-comms.md +++ b/docs/skills/business-operations/internal-comms.md @@ -65,6 +65,13 @@ Five-step deterministic flow. Follow in order. All three: stdlib only, `--help` and `--sample` exit 0, accept `--input <json>` and `--output {markdown,json}`. +## Quick example + +```bash +# Emits the 4-artifact comms package (pre-comm, announcement, FAQ, follow-up) for the built-in tool-rollout example +cd business-operations/skills/internal-comms && python3 scripts/comms_template_filler.py --sample +``` + ## References - `references/change_management_canon.md` — Jeff Hiatt *ADKAR* (Prosci), John Kotter *Leading Change* (8-step), William Bridges *Managing Transitions* (Endings / Neutral Zone / Beginnings), Edgar Schein *Organizational Culture and Leadership*, McKinsey 7-S framework, Heath brothers *Switch*, Patrick Lencioni *The Advantage*. diff --git a/docs/skills/business-operations/knowledge-ops.md b/docs/skills/business-operations/knowledge-ops.md index 1b9c38be..8d3dcaa6 100644 --- a/docs/skills/business-operations/knowledge-ops.md +++ b/docs/skills/business-operations/knowledge-ops.md @@ -23,7 +23,7 @@ Company SOP + internal runbook authoring, 5W2H completeness validation, and KB h An ops organization three years in accumulates a sprawl: 600 Notion pages, 200 Confluence runbooks, three Obsidian vaults, a `Drive/SOPs/` folder, and a `Slack #ops-questions` channel that exists because nobody can find the canonical doc. Predictable failure modes: 1. **No owner** — 40% of SOPs name "the team" instead of a person. When the doc rots, nobody is accountable. -2. **No last-reviewed date** — a 2023 vendor-offboarding SOP still references a procurement tool sunset in 2024. +2. **No last-reviewed date** — a years-old vendor-offboarding SOP still references a procurement tool that was sunset over a year ago. 3. **Vague success signals** — runbook step 4 says "verify the service is up". A new operator can't tell what that means. 4. **No rollback path** — incident-comms cascade runbook tells you how to send the alert. It doesn't tell you how to retract it when the alert was wrong. 5. **Orphan pages** — half the KB has no inbound links. Nobody finds them via navigation; they only exist because somebody knew the URL. @@ -57,6 +57,13 @@ Four-step deterministic flow (matches the ops org's actual workflow, not an abst **`scripts/kb_ingester.py`** — Walks a directory of markdown files (Notion export, Confluence space export, Obsidian vault, `Drive/SOPs/` directory). Extracts: (a) cross-link map (which page references which, via markdown `[link](path)` syntax), (b) glossary candidates (frequently used proper nouns and acronyms that recur in 3+ docs without a single canonical definition page), (c) orphan pages (no inbound links from anywhere in the vault), (d) glossary drift (the same term defined or used inconsistently across docs — e.g., "CSM" expanded differently in two places), (e) stale pages (no edit in > 12 months, detected via filesystem mtime or YAML `last_reviewed` frontmatter), (f) missing-owner pages (no `owner:` field in frontmatter). Emits a KB health report markdown with a prioritized top-20 cleanup list ranked by `staleness × inbound-link-count` (high-traffic stale docs first). `--sample` builds a tiny synthetic 8-page vault in a tmpdir and runs the full pipeline against it. Stdlib only. +## Quick example + +```bash +# Builds a synthetic 8-page vault and emits a KB health report (orphans, stale pages, glossary drift, top-20 cleanup list) +cd business-operations/skills/knowledge-ops && python3 scripts/kb_ingester.py --sample +``` + ## References - `references/5w2h_sop_canon.md` — Kaoru Ishikawa's 5W2H method, Toyota standard-work discipline, Atul Gawande's checklist manifesto, Atlassian Confluence SOP guidance, ISO 9001 SOP requirements, ITIL v4 Service Operation, FDA 21 CFR Part 211. Eight cited sources covering SOP authoring canon. diff --git a/docs/skills/business-operations/process-mapper.md b/docs/skills/business-operations/process-mapper.md index 28a817a3..234b9027 100644 --- a/docs/skills/business-operations/process-mapper.md +++ b/docs/skills/business-operations/process-mapper.md @@ -53,6 +53,13 @@ Five-step deterministic flow: **`scripts/cycle_time_analyzer.py`** — Computes total P50 and P90 cycle time, value-add ratio (VA%), wait %, rework %, and a Little's-Law throughput estimate (WIP / cycle time). Per Lean canon: VA% > 25% = HEALTHY, 10–25% = TYPICAL (most non-manufacturing processes land here), < 10% = WASTE-HEAVY. +## Quick example + +```bash +# Renders a BPMN-style swim-lane diagram + normalized JSON for the built-in 6-stage procurement-intake example +cd business-operations/skills/process-mapper && python3 scripts/process_documenter.py --sample +``` + ## References - `references/lean_six_sigma_canon.md` — TIMWOOD wastes, value-stream mapping, Theory of Constraints, Kanban WIP, Little's Law. Cites Womack & Jones, Rother & Shook, Goldratt, Ohno, Liker, Pyzdek, Anderson. diff --git a/docs/skills/business-operations/procurement-optimizer.md b/docs/skills/business-operations/procurement-optimizer.md index 6cbf6187..ec178eb6 100644 --- a/docs/skills/business-operations/procurement-optimizer.md +++ b/docs/skills/business-operations/procurement-optimizer.md @@ -1,6 +1,6 @@ --- title: "Procurement Optimizer — Spend Categorization + Supplier Rationalization — Claude Code Plugin & Agent Skill" -description: "Use when running an annual SaaS audit, doing category-level spend review, or rationalizing the supplier base — when the user needs to do a spend. Agent skill for Claude Code, Codex CLI, Gemini CLI, OpenClaw." +description: "Use when running an annual SaaS audit, doing category-level spend review, or rationalizing the supplier base — when the user needs a spend audit. Agent skill for Claude Code, Codex CLI, Gemini CLI, OpenClaw." --- # Procurement Optimizer — Spend Categorization + Supplier Rationalization @@ -105,6 +105,13 @@ Combine the 3 artifacts into a BizOps-ready digest: All three accept `--input` (JSON), `--output` (markdown path), `--sample` (run with built-in sample data), and `--help`. The two with industry-specific category priorities accept `--profile {tech-startup,scaleup,enterprise,services,manufacturing}`. +## Quick example + +```bash +# Emits a UNSPSC-aligned spend categorization with Pareto breakdown for the built-in sample spend file +cd business-operations/skills/procurement-optimizer && python3 scripts/spend_categorizer.py --sample +``` + ## References - `references/spend_management_canon.md` — A.T. Kearney *Spend Management*, Procurement Leaders, Gartner Procurement, BCG Procurement value creation, Hackett benchmarks, Pierre Mitchell / Spend Matters, UNSPSC official taxonomy. diff --git a/docs/skills/business-operations/vendor-management.md b/docs/skills/business-operations/vendor-management.md index 55c7e8af..5bb70188 100644 --- a/docs/skills/business-operations/vendor-management.md +++ b/docs/skills/business-operations/vendor-management.md @@ -1,6 +1,6 @@ --- title: "Vendor Management — Operational Third-Party Performance — Claude Code Plugin & Agent Skill" -description: "Use when reviewing, scoring, or auditing third-party SaaS / vendor relationships — running a vendor scorecard, tracking SLA compliance, classifying. Agent skill for Claude Code, Codex CLI, Gemini CLI, OpenClaw." +description: "Use when reviewing, scoring, or auditing third-party SaaS / vendor relationships — running a vendor scorecard with industry tuning, tracking SLA. Agent skill for Claude Code, Codex CLI, Gemini CLI, OpenClaw." --- # Vendor Management — Operational Third-Party Performance @@ -115,6 +115,13 @@ Combine the 3 artifacts into a final BizOps / VMO digest: All three accept `--input` (JSON), `--output` (markdown path), `--sample` (run with built-in sample data), and `--help`. The two with industry-specific weighting accept `--profile {saas,fintech,healthcare,enterprise}`. +## Quick example + +```bash +# Emits a weighted vendor scorecard (industry-tuned dimensions + per-vendor verdict) for the built-in sample catalog +cd business-operations/skills/vendor-management && python3 scripts/vendor_scorer.py --sample +``` + ## References - `references/vendor_management_canon.md` — Gartner / Shared Assessments / ISO 27036 / NIST 800-161 / Forrester / ISACA / Vendr industry reports diff --git a/docs/skills/c-level-advisor/agent-protocol.md b/docs/skills/c-level-advisor/agent-protocol.md index ad974d28..4bbc8be5 100644 --- a/docs/skills/c-level-advisor/agent-protocol.md +++ b/docs/skills/c-level-advisor/agent-protocol.md @@ -37,7 +37,15 @@ Any agent can query another using: [INVOKE:cro|What does our pipeline look like for the next 90 days?] ``` -**Valid roles:** `ceo`, `cfo`, `cro`, `cmo`, `cpo`, `cto`, `chro`, `coo`, `ciso` +**Valid roles:** `ceo`, `cfo`, `cro`, `cmo`, `cpo`, `cto`, `chro`, `coo`, `ciso`, `gc`, `cdo`, `caio`, `cco`, `vpe` + +| Role token | Advisor skill | +|---|---| +| `gc` | general-counsel-advisor (legal, contracts, term sheets) | +| `cdo` | chief-data-officer-advisor (data strategy, training-data rights) | +| `caio` | chief-ai-officer-advisor (AI strategy, evals, AI risk) | +| `cco` | chief-customer-officer-advisor (retention, customer success) | +| `vpe` | vpe-advisor (engineering delivery, DORA, eng hiring) | ## Response Format @@ -163,6 +171,26 @@ CEO can broadcast to all roles simultaneously: Responses come back independently (no agent sees another's response before forming its own). Aggregate after all respond. +## Decision Memory (Canonical Layout) + +All C-suite skills and `/cs:*` commands read and write decisions in **one** place — the two-layer model owned by `/cs:decide` and the decision-logger skill: + +``` +~/.claude/decisions/ +├── raw/YYYY-MM-DD-<slug>.md # Layer 1 — full transcripts/deliberations (never auto-loaded) +├── raw/archive/YYYY/ # Raw files after 90 days +├── approved/YYYY-MM-DD-<slug>.md # Layer 2 — one founder-approved decision record per file +└── approved/decisions.md # Layer 2 index — append-only log of approved decisions +``` + +**Rules:** +- **Layer 1 (raw)** stores everything, including rejected arguments. Reference only — never feeds future sessions automatically. +- **Layer 2 (approved)** stores only founder-approved decisions. This is what board meetings, `/cs:office-hours`, and `/cs:founder-mode` load. Prevents hallucinated consensus. +- Writers: `/cs:decide` and the Chief of Staff (post board-meeting Phase 5). Individual role agents never write decisions directly. +- decision-logger, chief-of-staff, and board-meeting all use this layout. Their SKILL.md files link here rather than defining their own paths. + +**Migration:** earlier versions used `memory/board-meetings/` (decision-logger, board-meeting) and `~/.claude/decision-log.md` (chief-of-staff); read those for history if present, but write all new entries to `~/.claude/decisions/`. + ## Quick Reference | Rule | Behavior | @@ -220,6 +248,11 @@ When a recommendation impacts another role's domain, that role validates BEFORE | Customer-facing changes | CRO + CPO | Churn risk, product roadmap conflict | | Security or compliance claims | CISO | Actual posture, regulation requirements | | Market or positioning claims | CMO | Data backing, competitive reality | +| Legal exposure, contracts, term sheets | GC | Clause risk, IP ownership, regulatory triggers | +| Data rights, training-data provenance | CDO | Consent basis, GDPR Art. 6, data-asset impact | +| AI model claims, eval results, AI risk | CAIO | Eval coverage, hallucination SLO, EU AI Act tier | +| Retention, churn, customer-health claims | CCO | GRR/NRR decomposition, churn root cause | +| Delivery timelines, eng throughput | VPE | DORA metrics, cycle-time reality, team capacity | **Peer validation format:** ``` diff --git a/docs/skills/c-level-advisor/board-deck-builder.md b/docs/skills/c-level-advisor/board-deck-builder.md index a19b8226..4a0c97a2 100644 --- a/docs/skills/c-level-advisor/board-deck-builder.md +++ b/docs/skills/c-level-advisor/board-deck-builder.md @@ -23,9 +23,10 @@ board deck, investor update, board meeting, board pack, investor relations, quar ## Quick Start -``` -/board-deck [quarterly|monthly|fundraising] [stage: seed|seriesA|seriesB] -``` +Ask for a board deck in natural language, naming cadence and stage: + +> "Build a quarterly board deck — we're Series A." +> "Draft a fundraising board deck for a seed-stage company." Provide available metrics. The builder fills gaps with explicit placeholders — never invents numbers. diff --git a/docs/skills/c-level-advisor/board-meeting.md b/docs/skills/c-level-advisor/board-meeting.md index 609a367c..7cdc6065 100644 --- a/docs/skills/c-level-advisor/board-meeting.md +++ b/docs/skills/c-level-advisor/board-meeting.md @@ -19,29 +19,34 @@ description: "Multi-agent board meeting protocol for strategic decisions. Runs a Structured multi-agent deliberation that prevents groupthink, captures minority views, and produces clean, actionable decisions. ## Keywords -board meeting, executive deliberation, strategic decision, C-suite, multi-agent, /cs:board, founder review, decision extraction, independent perspectives +board meeting, executive deliberation, strategic decision, C-suite, multi-agent, /cs:boardroom, founder review, decision extraction, independent perspectives ## Invoke -`/cs:board [topic]` — e.g. `/cs:board Should we expand to Spain in Q3?` +`/cs:boardroom [topic]` — e.g. `/cs:boardroom Should we expand to Spain in Q3?` --- ## The 6-Phase Protocol ### PHASE 1: Context Gathering -1. Load `memory/company-context.md` -2. Load `memory/board-meetings/decisions.md` **(Layer 2 ONLY — never raw transcripts)** +1. Load `~/.claude/company-context.md` +2. Load Layer 2 approved decisions from `~/.claude/decisions/approved/` **(Layer 2 ONLY — never raw transcripts)** 3. Reset session state — no bleed from previous conversations 4. Present agenda + activated roles → wait for founder confirmation -**Chief of Staff selects relevant roles** based on topic (not all 9 every time): +**Chief of Staff selects relevant roles** based on topic (not all 14 every time): | Topic | Activate | |-------|----------| | Market expansion | CEO, CMO, CFO, CRO, COO | | Product direction | CEO, CPO, CTO, CMO | -| Hiring/org | CEO, CHRO, CFO, COO | +| Hiring/org | CEO, CHRO, CFO, COO (+ VPE for eng hiring) | | Pricing | CMO, CFO, CRO, CPO | | Technology | CTO, CPO, CFO, CISO | +| Contracts / term sheets / legal exposure | GC, CEO, CFO | +| Data strategy / training-data rights | CDO, CAIO, GC, CISO | +| AI strategy / model selection / AI risk | CAIO, CTO, CDO, CFO | +| Retention / churn / customer success | CCO, CRO, CPO | +| Eng delivery / DORA / team structure | VPE, CTO, CHRO, CFO | --- @@ -49,9 +54,9 @@ board meeting, executive deliberation, strategic decision, C-suite, multi-agent, **No cross-pollination. Each agent runs before seeing others' outputs.** -Order: Research (if needed) → CMO → CFO → CEO → CTO → COO → CHRO → CRO → CISO → CPO +Order: Research (if needed) → CMO → CFO → CEO → CTO → COO → CHRO → CRO → CISO → CPO → GC → CDO → CAIO → CCO → VPE (activated roles only) -**Reasoning techniques:** CEO: Tree of Thought (3 futures) | CFO: Chain of Thought (show the math) | CMO: Recursion of Thought (draft→critique→refine) | CPO: First Principles | CRO: Chain of Thought (pipeline math) | COO: Step by Step (process map) | CTO: ReAct (research→analyze→act) | CISO: Risk-Based (P×I) | CHRO: Empathy + Data +**Reasoning techniques:** CEO: Tree of Thought (3 futures) | CFO: Chain of Thought (show the math) | CMO: Recursion of Thought (draft→critique→refine) | CPO: First Principles | CRO: Chain of Thought (pipeline math) | COO: Step by Step (process map) | CTO: ReAct (research→analyze→act) | CISO: Risk-Based (P×I) | CHRO: Empathy + Data | GC: Risk-Based (clause exposure) | CDO: Decision-Driven (what decision does this data drive) | CAIO: Eval-Demanding (no eval, no ship) | CCO: Retention-Obsessed (GRR over NRR) | VPE: Throughput-First (cycle-time math) **Contribution format (max 5 key points, self-verified):** ``` @@ -84,7 +89,7 @@ Checklist: --- ### PHASE 4: Synthesis -Chief of Staff delivers using the **Board Meeting Output** format (defined in `agent-protocol/SKILL.md`): +Chief of Staff delivers using the **Board Meeting Output** format (defined in [`agent-protocol/SKILL.md`](https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor/skills/agent-protocol/SKILL.md)): - Decision Required (one sentence) - Perspectives (one line per contributing role) - Where They Agree / Where They Disagree @@ -107,29 +112,35 @@ Options: ✅ Approve | ✏️ Modify | ❌ Reject | ❓ Ask follow-up **Rules:** - User corrections OVERRIDE agent proposals. No pushback. No "but the CFO said..." - 30-min inactivity → auto-close as "pending review" -- Reopen any time with `/cs:board resume` +- Reopen any time with `/cs:boardroom resume` --- ### PHASE 6: Decision Extraction After founder approval: -- **Layer 1:** Write full transcript → `memory/board-meetings/YYYY-MM-DD-raw.md` -- **Layer 2:** Append approved decisions → `memory/board-meetings/decisions.md` +- **Layer 1:** Write full transcript → `~/.claude/decisions/raw/YYYY-MM-DD-<slug>.md` +- **Layer 2:** Write approved decision record → `~/.claude/decisions/approved/YYYY-MM-DD-<slug>.md` and append to the index `~/.claude/decisions/approved/decisions.md` - Mark rejected proposals `[DO_NOT_RESURFACE]` - Confirm to founder with count of decisions logged, actions tracked, flags added --- ## Memory Structure + +Uses the canonical two-layer decision memory (see [`agent-protocol/SKILL.md`](https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor/skills/agent-protocol/SKILL.md) → "Decision Memory (Canonical Layout)"): + ``` -memory/board-meetings/ -├── decisions.md # Layer 2 — founder-approved only (Phase 1 loads this) -├── YYYY-MM-DD-raw.md # Layer 1 — full transcripts (never auto-loaded) -└── archive/YYYY/ # Raw transcripts after 90 days +~/.claude/decisions/ +├── raw/YYYY-MM-DD-<slug>.md # Layer 1 — full transcripts (never auto-loaded) +├── raw/archive/YYYY/ # Raw transcripts after 90 days +├── approved/YYYY-MM-DD-<slug>.md # Layer 2 — founder-approved records (Phase 1 loads these) +└── approved/decisions.md # Layer 2 index — append-only ``` **Future meetings load Layer 2 only.** Never Layer 1. This prevents hallucinated consensus. +Migration: a legacy `memory/board-meetings/` folder may exist from earlier versions; read it for history but write new transcripts and decisions to `~/.claude/decisions/`. + --- ## Failure Mode Quick Reference @@ -139,7 +150,7 @@ memory/board-meetings/ | Analysis paralysis | Cap at 5 points; force recommendation even with Low confidence | | Bikeshedding | Log as async action item; return to main agenda | | Role bleed (CFO making product calls) | Critic flags; exclude from synthesis | -| Layer contamination | Phase 1 loads decisions.md only — hard rule | +| Layer contamination | Phase 1 loads `~/.claude/decisions/approved/` only — hard rule | --- diff --git a/docs/skills/c-level-advisor/c-level-agents-brief.md b/docs/skills/c-level-advisor/c-level-agents-brief.md index 840c4873..fe6c6306 100644 --- a/docs/skills/c-level-advisor/c-level-agents-brief.md +++ b/docs/skills/c-level-advisor/c-level-agents-brief.md @@ -1,6 +1,6 @@ --- title: "/cs:brief — One-Page Strategy Brief — Agent Skill for Executives" -description: "/cs:brief <topic> — Generate a one-page strategy brief from an office-hours intake. First step in the strategic sprint pipeline. Agent skill for Claude Code, Codex CLI, Gemini CLI, OpenClaw." +description: "/cs:brief <topic> — Generate a one-page strategy brief from an office-hours intake. First step in the strategic sprint pipeline. Use when a strategic. Agent skill for Claude Code, Codex CLI, Gemini CLI, OpenClaw." --- # /cs:brief — One-Page Strategy Brief @@ -79,6 +79,11 @@ A single Markdown file under `~/.claude/briefs/YYYY-MM-DD-<slug>.md` with this s - [ ] cs-coo-advisor - [ ] cs-chro-advisor - [ ] cs-ciso-advisor +- [ ] cs-general-counsel-advisor +- [ ] cs-cdo-advisor +- [ ] cs-caio-advisor +- [ ] cs-cco-advisor +- [ ] cs-vpe-advisor - [ ] cs-chief-of-staff ## Success Criteria diff --git a/docs/skills/c-level-advisor/c-level-agents-caio-review.md b/docs/skills/c-level-advisor/c-level-agents-caio-review.md index 4873e7fc..963764a6 100644 --- a/docs/skills/c-level-advisor/c-level-agents-caio-review.md +++ b/docs/skills/c-level-advisor/c-level-agents-caio-review.md @@ -136,7 +136,7 @@ python ../../../skills/chief-ai-officer-advisor/scripts/ai_cost_economics.py wor - `/cs:gc-review` — for AI vendor contracts, output liability, training-data licensing - `/cs:ciso-review` — for prompt injection / jailbreak / training-data poisoning threat model - `/cs:cfo-review` — for multi-year vendor or GPU commitment TCO -- `/cs:chro-review` — for AI team hires (comp, ladder, leveling) +- `cs-chro-advisor` agent — for AI team hires (comp, ladder, leveling) - `/cs:decide` — log the verdict - `/cs:freeze 60` — on multi-year AI commitments diff --git a/docs/skills/c-level-advisor/c-level-agents-cco-review.md b/docs/skills/c-level-advisor/c-level-agents-cco-review.md index 9828470e..c6e29ce6 100644 --- a/docs/skills/c-level-advisor/c-level-agents-cco-review.md +++ b/docs/skills/c-level-advisor/c-level-agents-cco-review.md @@ -126,7 +126,7 @@ python ../../../skills/chief-customer-officer-advisor/scripts/cs_coverage_calcul - `/cs:cpo-review` — if churn root cause is product_fit or no_value_realized - `/cs:cro-review` — if expansion math or comp alignment is in question - `/cs:cfo-review` — for CS cost commitments and retention-impact-on-revenue -- `/cs:chro-review` — for CS hires, comp, ladder +- `cs-chro-advisor` agent — for CS hires, comp, ladder - `/cs:decide` — log the verdict - `/cs:freeze 30` — on multi-year CS comp plan changes diff --git a/docs/skills/c-level-advisor/c-level-agents-cdo-review.md b/docs/skills/c-level-advisor/c-level-agents-cdo-review.md index 0c90fcd4..fe765359 100644 --- a/docs/skills/c-level-advisor/c-level-agents-cdo-review.md +++ b/docs/skills/c-level-advisor/c-level-agents-cdo-review.md @@ -122,7 +122,7 @@ python ../../../skills/chief-data-officer-advisor/scripts/data_asset_valuator.py - `/cs:gc-review` — for any productization or licensing path - `/cs:ciso-review` — for any architecture change touching customer data - `/cs:cfo-review` — for build-vs-buy TCO and M&A valuation math -- `/cs:chro-review` — for data team hires (comp, ladder, leveling) +- `cs-chro-advisor` agent — for data team hires (comp, ladder, leveling) - `/cs:decide` — log the verdict - `/cs:freeze 90` — on multi-year infrastructure contracts diff --git a/docs/skills/c-level-advisor/c-level-agents-cfo-review.md b/docs/skills/c-level-advisor/c-level-agents-cfo-review.md index c45893ff..39072aa4 100644 --- a/docs/skills/c-level-advisor/c-level-agents-cfo-review.md +++ b/docs/skills/c-level-advisor/c-level-agents-cfo-review.md @@ -1,6 +1,6 @@ --- title: "/cs:cfo-review — CFO Forcing Questions — Agent Skill for Executives" -description: "/cs:cfo-review <plan> — Numerate-skeptic interrogation of any plan that touches money. Unit economics, runway, dilution, capital allocation. Agent skill for Claude Code, Codex CLI, Gemini CLI, OpenClaw." +description: "/cs:cfo-review <plan> — Numerate-skeptic interrogation of any plan that touches money. Unit economics, runway, dilution, capital allocation. Use when. Agent skill for Claude Code, Codex CLI, Gemini CLI, OpenClaw." --- # /cs:cfo-review — CFO Forcing Questions diff --git a/docs/skills/c-level-advisor/c-level-agents-ciso-review.md b/docs/skills/c-level-advisor/c-level-agents-ciso-review.md index 853cf491..40681f74 100644 --- a/docs/skills/c-level-advisor/c-level-agents-ciso-review.md +++ b/docs/skills/c-level-advisor/c-level-agents-ciso-review.md @@ -1,6 +1,6 @@ --- title: "/cs:ciso-review — CISO Forcing Questions — Agent Skill for Executives" -description: "/cs:ciso-review <plan> — Risk-paranoid interrogation of any plan that touches data, compliance, or production access. Agent skill for Claude Code, Codex CLI, Gemini CLI, OpenClaw." +description: "/cs:ciso-review <plan> — Risk-paranoid interrogation of any plan that touches data, compliance, or production access. Use when launching features. Agent skill for Claude Code, Codex CLI, Gemini CLI, OpenClaw." --- # /cs:ciso-review — CISO Forcing Questions diff --git a/docs/skills/c-level-advisor/c-level-agents-cmo-review.md b/docs/skills/c-level-advisor/c-level-agents-cmo-review.md index 21171139..689a0226 100644 --- a/docs/skills/c-level-advisor/c-level-agents-cmo-review.md +++ b/docs/skills/c-level-advisor/c-level-agents-cmo-review.md @@ -1,6 +1,6 @@ --- title: "/cs:cmo-review — CMO Forcing Questions — Agent Skill for Executives" -description: "/cs:cmo-review <plan> — Narrative-first interrogation of positioning, ICP, message house, and channel mix. Agent skill for Claude Code, Codex CLI, Gemini CLI, OpenClaw." +description: "/cs:cmo-review <plan> — Narrative-first interrogation of positioning, ICP, message house, and channel mix. Use when launching a campaign or. Agent skill for Claude Code, Codex CLI, Gemini CLI, OpenClaw." --- # /cs:cmo-review — CMO Forcing Questions diff --git a/docs/skills/c-level-advisor/c-level-agents-cpo-review.md b/docs/skills/c-level-advisor/c-level-agents-cpo-review.md index 8df43312..41a81596 100644 --- a/docs/skills/c-level-advisor/c-level-agents-cpo-review.md +++ b/docs/skills/c-level-advisor/c-level-agents-cpo-review.md @@ -1,6 +1,6 @@ --- title: "/cs:cpo-review — CPO Forcing Questions — Agent Skill for Executives" -description: "/cs:cpo-review <plan> — JTBD-driven interrogation of product roadmap, PMF signal, and portfolio focus. Agent skill for Claude Code, Codex CLI, Gemini CLI, OpenClaw." +description: "/cs:cpo-review <plan> — JTBD-driven interrogation of product roadmap, PMF signal, and portfolio focus. Use when committing a quarter's roadmap. Agent skill for Claude Code, Codex CLI, Gemini CLI, OpenClaw." --- # /cs:cpo-review — CPO Forcing Questions @@ -48,7 +48,7 @@ The JTBD-driven builder cuts the roadmap in half. Six questions to surface what ### 4. RICE Score **Reach, Impact, Confidence, Effort — what's the score and where does this rank in the queue?** ```bash -python ../../../../product-team/product-manager-toolkit/scripts/rice_prioritizer.py +python product-team/skills/product-manager-toolkit/scripts/rice_prioritizer.py ``` ### 5. Opportunity Cost @@ -114,7 +114,7 @@ python ../../../../product-team/product-manager-toolkit/scripts/rice_prioritizer - Agent: [`cs-cpo-advisor`](https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor/c-level-agents/agents/cs-cpo-advisor.md) - Skill: [`cpo-advisor`](https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor/skills/cpo-advisor/SKILL.md) -- Execution: [`product-team/product-manager-toolkit`](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/product-manager-toolkit) +- Execution: `product-team/skills/product-manager-toolkit/` --- diff --git a/docs/skills/c-level-advisor/c-level-agents-cro-review.md b/docs/skills/c-level-advisor/c-level-agents-cro-review.md index b3ce11ab..42ca1763 100644 --- a/docs/skills/c-level-advisor/c-level-agents-cro-review.md +++ b/docs/skills/c-level-advisor/c-level-agents-cro-review.md @@ -1,6 +1,6 @@ --- title: "/cs:cro-review — CRO Forcing Questions — Agent Skill for Executives" -description: "/cs:cro-review <plan> — Pipeline-paranoid interrogation of revenue, win rate, NRR, and ramp time. Agent skill for Claude Code, Codex CLI, Gemini CLI, OpenClaw." +description: "/cs:cro-review <plan> — Pipeline-paranoid interrogation of revenue, win rate, NRR, and ramp time. Use when the forecast misses pipeline coverage, win. Agent skill for Claude Code, Codex CLI, Gemini CLI, OpenClaw." --- # /cs:cro-review — CRO Forcing Questions diff --git a/docs/skills/c-level-advisor/c-level-agents-cross-eval.md b/docs/skills/c-level-advisor/c-level-agents-cross-eval.md index 104b06f4..a7a06855 100644 --- a/docs/skills/c-level-advisor/c-level-agents-cross-eval.md +++ b/docs/skills/c-level-advisor/c-level-agents-cross-eval.md @@ -1,6 +1,6 @@ --- title: "/cs:cross-eval — Multi-Model Consensus — Agent Skill for Executives" -description: "/cs:cross-eval <memo> — Multi-model consensus on a board memo or strategy brief. Claude + Codex + Gemini cross-review with graceful degradation." +description: "/cs:cross-eval <memo> — Multi-model consensus on a board memo or strategy brief. Claude + Codex + Gemini cross-review with graceful degradation. Use." --- # /cs:cross-eval — Multi-Model Consensus diff --git a/docs/skills/c-level-advisor/c-level-agents-cto-review.md b/docs/skills/c-level-advisor/c-level-agents-cto-review.md index 86128d8b..7be5b7e8 100644 --- a/docs/skills/c-level-advisor/c-level-agents-cto-review.md +++ b/docs/skills/c-level-advisor/c-level-agents-cto-review.md @@ -1,6 +1,6 @@ --- title: "/cs:cto-review — CTO Forcing Questions — Agent Skill for Executives" -description: "/cs:cto-review <plan> — Architecture and scaling interrogation. Tech debt, scaling cliffs, team scaling, build-vs-buy. Agent skill for Claude Code, Codex CLI, Gemini CLI, OpenClaw." +description: "/cs:cto-review <plan> — Architecture and scaling interrogation. Tech debt, scaling cliffs, team scaling, build-vs-buy. Use when committing to an. Agent skill for Claude Code, Codex CLI, Gemini CLI, OpenClaw." --- # /cs:cto-review — CTO Forcing Questions diff --git a/docs/skills/c-level-advisor/c-level-agents-decide.md b/docs/skills/c-level-advisor/c-level-agents-decide.md index 0403aacc..af532419 100644 --- a/docs/skills/c-level-advisor/c-level-agents-decide.md +++ b/docs/skills/c-level-advisor/c-level-agents-decide.md @@ -1,6 +1,6 @@ --- title: "/cs:decide — Log the Decision — Agent Skill for Executives" -description: "/cs:decide <memo> — Log a decision to two-layer memory via decision-logger. Approved memo becomes durable; raw transcripts kept for reference. Agent skill for Claude Code, Codex CLI, Gemini CLI, OpenClaw." +description: "/cs:decide <memo> — Log a decision to two-layer memory via decision-logger. Approved memo becomes durable; raw transcripts kept for reference. Use. Agent skill for Claude Code, Codex CLI, Gemini CLI, OpenClaw." --- # /cs:decide — Log the Decision diff --git a/docs/skills/c-level-advisor/c-level-agents-execute.md b/docs/skills/c-level-advisor/c-level-agents-execute.md index 17e57b61..40172ed7 100644 --- a/docs/skills/c-level-advisor/c-level-agents-execute.md +++ b/docs/skills/c-level-advisor/c-level-agents-execute.md @@ -1,6 +1,6 @@ --- title: "/cs:execute — 90-Day Execution Plan — Agent Skill for Executives" -description: "/cs:execute <decision> — Generate a 90-day execution plan with weekly milestones, DRIs, and check-in cadence from an approved decision. Agent skill for Claude Code, Codex CLI, Gemini CLI, OpenClaw." +description: "/cs:execute <decision> — Generate a 90-day execution plan with weekly milestones, DRIs, and check-in cadence from an approved decision. Use when a. Agent skill for Claude Code, Codex CLI, Gemini CLI, OpenClaw." --- # /cs:execute — 90-Day Execution Plan diff --git a/docs/skills/c-level-advisor/c-level-agents-founder-mode.md b/docs/skills/c-level-advisor/c-level-agents-founder-mode.md index 20c9aff8..05f00c9a 100644 --- a/docs/skills/c-level-advisor/c-level-agents-founder-mode.md +++ b/docs/skills/c-level-advisor/c-level-agents-founder-mode.md @@ -29,14 +29,18 @@ The router (via `cs-chief-of-staff`) does keyword + intent matching: | Signal in question | Route | |---|---| | burn, runway, fundraise, dilution, model, LTV, CAC | `cs-cfo-advisor` | -| pipeline, win rate, forecast, NRR, churn, ramp | `cs-cro-advisor` | +| pipeline, win rate, forecast, quota, ramp, sales motion | `cs-cro-advisor` | | positioning, ICP, message, brand, channel, campaign | `cs-cmo-advisor` | | roadmap, PMF, JTBD, North Star, RICE, kill | `cs-cpo-advisor` | | cadence, OKR, scorecard, DRI, operating system, rhythm | `cs-coo-advisor` | | hiring, comp, ladder, level, attrition, eNPS, equity | `cs-chro-advisor` | | security, threat, breach, compliance, audit, SOC 2 | `cs-ciso-advisor` | | architecture, scaling, tech debt, SLO, latency | `cs-cto-advisor` | -| contract, IP, term sheet, regulator, license | `/cs:gc-review` | +| contract, IP, term sheet, regulator, license | `cs-general-counsel-advisor` | +| retention, GRR, NRR, churn, customer success, CSM, time-to-value, renewals | `cs-cco-advisor` | +| training data, data rights, consent, data asset, warehouse, lakehouse, data mesh | `cs-cdo-advisor` | +| model selection, eval, hallucination, AI risk, EU AI Act, fine-tune, build vs buy AI | `cs-caio-advisor` | +| DORA, cycle time, deploy frequency, eng hiring funnel, team topology, delivery throughput | `cs-vpe-advisor` | | strategy, vision, board, M&A, raise, exit | `cs-ceo-advisor` | | **2+ signals from different roles** | `/cs:boardroom` | | **ambiguous** | `/cs:office-hours` first, then route | @@ -94,6 +98,9 @@ gstack requires the founder to know all 23 slash commands and pick the right one /cs:founder-mode "the win rate dropped 20% this month" → cs-cro-advisor +/cs:founder-mode "gross retention dropped 5 points this quarter" + → cs-cco-advisor + /cs:founder-mode "let's hire a VP Marketing" → boardroom (CHRO + CMO + CFO touched) diff --git a/docs/skills/c-level-advisor/c-level-agents-gc-review.md b/docs/skills/c-level-advisor/c-level-agents-gc-review.md index b0c9ce2f..f5348a7e 100644 --- a/docs/skills/c-level-advisor/c-level-agents-gc-review.md +++ b/docs/skills/c-level-advisor/c-level-agents-gc-review.md @@ -1,6 +1,6 @@ --- title: "/cs:gc-review — General Counsel Forcing Questions — Agent Skill for Executives" -description: "/cs:gc-review <plan> — General Counsel interrogation of contracts, IP, regulatory, term sheets, and employment-law surface. Agent skill for Claude Code, Codex CLI, Gemini CLI, OpenClaw." +description: "/cs:gc-review <plan> — General Counsel interrogation of contracts, IP, regulatory, term sheets, and employment-law surface. Use when reviewing a term. Agent skill for Claude Code, Codex CLI, Gemini CLI, OpenClaw." --- # /cs:gc-review — General Counsel Forcing Questions diff --git a/docs/skills/c-level-advisor/c-level-agents-onboard.md b/docs/skills/c-level-advisor/c-level-agents-onboard.md index baf48fc5..9cc91657 100644 --- a/docs/skills/c-level-advisor/c-level-agents-onboard.md +++ b/docs/skills/c-level-advisor/c-level-agents-onboard.md @@ -1,6 +1,6 @@ --- title: "/cs:onboard — Founder Interview — Agent Skill for Executives" -description: "/cs:onboard — Founder interview that populates ~/.claude/company-context.md. The first command to run when starting with c-level-agents. Agent skill for Claude Code, Codex CLI, Gemini CLI, OpenClaw." +description: "/cs:onboard — Founder interview that populates ~/.claude/company-context.md using the canonical 7-dimension cs-onboard schema. The first command to. Agent skill for Claude Code, Codex CLI, Gemini CLI, OpenClaw." --- # /cs:onboard — Founder Interview @@ -51,7 +51,9 @@ The first command to run when adopting c-level-agents. A structured founder inte ## Output Format -Saved to `~/.claude/company-context.md`: +**Canonical schema:** `~/.claude/company-context.md` is owned by the [`cs-onboard`](https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor/skills/cs-onboard/SKILL.md) skill and follows its 7-dimension schema ([`templates/company-context-template.md`](https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor/skills/cs-onboard/templates/company-context-template.md)): Company Identity, Stage & Scale, Founder Profile, Team & Culture, Market & Competition, Current Challenges, Goals & Ambition. The 12 questions above are a faster structured intake that populates that same file — Identity/Business/Financial → Stage & Scale, Team → Team & Culture, Quarter priorities/risks → Current Challenges + Goals & Ambition. Write `[not captured]` for dimensions the quick intake doesn't reach (Founder Profile, Market & Competition); run the full `cs-onboard` interview to fill them. Never create a second context file or a divergent layout. + +The intake summary captured by the 12 questions: ```markdown # Company Context diff --git a/docs/skills/c-level-advisor/c-level-agents-vpe-review.md b/docs/skills/c-level-advisor/c-level-agents-vpe-review.md index f4827bb7..d6517255 100644 --- a/docs/skills/c-level-advisor/c-level-agents-vpe-review.md +++ b/docs/skills/c-level-advisor/c-level-agents-vpe-review.md @@ -123,7 +123,7 @@ python ../../../skills/vpe-advisor/scripts/eng_team_structure_designer.py team.j ## Routing - `/cs:cto-review` — for architectural causes of throughput problems -- `/cs:chro-review` — for hiring funnel comp/leveling issues +- `cs-chro-advisor` agent — for hiring funnel comp/leveling issues - `/cs:cfo-review` — for cost-per-hire envelope and eng budget - `/cs:ciso-review` — for production discipline + compliance overlap - `/cs:decide` — log the verdict diff --git a/docs/skills/c-level-advisor/c-level-agents.md b/docs/skills/c-level-advisor/c-level-agents.md index 6238b4a7..6ec86b37 100644 --- a/docs/skills/c-level-advisor/c-level-agents.md +++ b/docs/skills/c-level-advisor/c-level-agents.md @@ -1,6 +1,6 @@ --- title: "c-level-agents — Founder-Mode Executive Team — Agent Skill for Executives" -description: "Founder-mode executive team. 8 cs-* C-suite agents (CFO, CMO, CRO, CPO, COO, CHRO, CISO, Chief of Staff) and 17 /cs:* slash commands for. Agent skill for Claude Code, Codex CLI, Gemini CLI, OpenClaw." +description: "Founder-mode executive team. 13 cs-* C-suite agents (CFO, CMO, CRO, CPO, COO, CHRO, CISO, GC, CDO, CAIO, CCO, VPE, Chief of Staff) and 21 /cs:* slash. Agent skill for Claude Code, Codex CLI, Gemini CLI, OpenClaw." --- # c-level-agents — Founder-Mode Executive Team @@ -24,7 +24,7 @@ founder mode, virtual c-suite, executive team, boardroom, office hours, cfo revi ## What This Plugin Provides -### 8 cs-* Agents (in `agents/`) +### 13 cs-* Agents (in `agents/`) Each agent wraps an existing c-level skill and adds: - A distinct cognitive voice (numerate skeptic, narrative-first, etc.) @@ -32,11 +32,11 @@ Each agent wraps an existing c-level skill and adds: - Workflow orchestration tied to skill Python tools - Output template: Bottom Line → What → Why → How to Act → Your Decision -See [`references/persona-voices.md`](https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor/c-level-agents/skills/references/persona-voices.md) for voice specs. +See [`references/persona-voices.md`](https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor/c-level-agents/references/persona-voices.md) for voice specs. -### 17 /cs:* Slash Commands (in `skills/`) +### 21 /cs:* Slash Commands (in `skills/`) -**Forcing-question office hours (8):** +**Forcing-question office hours (12):** - `/cs:office-hours` — YC-style 6-question intake - `/cs:cfo-review` — unit economics, runway, dilution - `/cs:cmo-review` — ICP, CAC payback, positioning @@ -45,6 +45,10 @@ See [`references/persona-voices.md`](https://github.com/alirezarezvani/claude-sk - `/cs:cto-review` — architecture risk, scaling cliff - `/cs:ciso-review` — threat model, blast radius, compliance - `/cs:gc-review` — contracts, IP, regulatory, term sheets +- `/cs:cdo-review` — training-data rights, data products, data assets +- `/cs:caio-review` — model selection, evals, AI risk, AI costs +- `/cs:cco-review` — GRR/NRR decomposition, churn root cause, CS coverage +- `/cs:vpe-review` — DORA metrics, cycle time, eng hiring funnel, team structure **Strategic sprint pipeline (5):** - `/cs:brief` → `/cs:boardroom` → `/cs:decide` → `/cs:execute` → `/cs:post-mortem` @@ -88,11 +92,11 @@ User question ## Integration Points -- **Existing 28 c-level skills** — wrapped, not replaced +- **Existing 33 c-level skills** — wrapped, not replaced - **decision-logger** — every `/cs:decide` writes here - **chief-of-staff** — routing layer the agent orchestrates - **board-meeting** — protocol the `/cs:boardroom` command runs -- **llm-wiki** — optional persistent memory bridge (see [`references/llm-wiki-bridge.md`](https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor/c-level-agents/skills/references/llm-wiki-bridge.md)) +- **llm-wiki** — optional persistent memory bridge (see [`references/llm-wiki-bridge.md`](https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor/c-level-agents/references/llm-wiki-bridge.md)) - **executive-mentor** — adversarial `/em:*` commands stack cleanly on top ## Design Principles diff --git a/docs/skills/c-level-advisor/c-level-skills.md b/docs/skills/c-level-advisor/c-level-skills.md index c6d4afe1..014b8e96 100644 --- a/docs/skills/c-level-advisor/c-level-skills.md +++ b/docs/skills/c-level-advisor/c-level-skills.md @@ -1,9 +1,9 @@ --- -title: "C-Level Advisory Ecosystem — Agent Skill for Executives" -description: "10 C-level advisory agent skills and plugins for Claude Code, Codex, Gemini CLI, Cursor, OpenClaw. CEO, CTO, COO, CPO, CMO, CFO, CRO, CISO, CHRO." +title: "C-Level Advisory Bundle — Index — Agent Skill for Executives" +description: "Index and router for the C-level advisory bundle: 33 skills covering 14 C-suite roles, orchestration, cross-cutting capabilities, and culture. Use. Agent skill for Claude Code, Codex CLI, Gemini CLI, OpenClaw." --- -# C-Level Advisory Ecosystem +# C-Level Advisory Bundle — Index <div class="page-meta" markdown> <span class="meta-badge">:material-account-tie: C-Level Advisory</span> @@ -16,139 +16,33 @@ description: "10 C-level advisory agent skills and plugins for Claude Code, Code </div> -A complete virtual board of directors for founders and executives. +This is the bundle index, not an advisor. It tells you what exists and where to start; the skills below do the work. -## Quick Start +## Start Here -``` -1. Run /cs:setup → creates company-context.md (all agents read this) - ✓ Verify company-context.md was created and contains your company name, - stage, and core metrics before proceeding. -2. Ask any strategic question → Chief of Staff routes to the right role -3. For big decisions → /cs:board triggers a multi-role board meeting - ✓ Confirm at least 3 roles have weighed in before accepting a conclusion. -``` +1. **Onboard** — the `cs-onboard` skill runs the founder interview (`/cs:setup`, 7 dimensions, ~45 min) and writes `~/.claude/company-context.md`. Refresh quarterly with `/cs:update`. This is the canonical context schema every advisor reads. +2. **Ask** — the `chief-of-staff` skill routes any question to the right advisor(s). See its routing matrix for all 14 roles. +3. **Big decisions** — the `board-meeting` skill runs a **6-phase** deliberation: (1) context gathering → (2) independent contributions (isolated) → (3) critic analysis → (4) synthesis → (5) founder review (full stop) → (6) decision extraction. Invoked via `/cs:boardroom` in the c-level-agents plugin. +4. **Memory** — decisions land in the canonical two-layer layout `~/.claude/decisions/{raw,approved}/` (see [`agent-protocol/SKILL.md`](https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor/skills/agent-protocol/SKILL.md) → "Decision Memory (Canonical Layout)"). -### Commands +## What's in the Bundle (33 skills) -#### `/cs:setup` — Onboarding Questionnaire +**14 C-suite roles + critic (15):** ceo-advisor, cfo-advisor, cto-advisor, coo-advisor, cpo-advisor, cmo-advisor, cro-advisor, ciso-advisor, chro-advisor, general-counsel-advisor, chief-data-officer-advisor, chief-ai-officer-advisor, chief-customer-officer-advisor, vpe-advisor — plus the executive-mentor critic (sibling plugin). -Walks through the following prompts and writes `company-context.md` to the project root. Run once per company or when context changes significantly. +**Orchestration (6):** cs-onboard, chief-of-staff, board-meeting, decision-logger, agent-protocol, context-engine. -``` -Q1. What is your company name and one-line description? -Q2. What stage are you at? (Idea / Pre-seed / Seed / Series A / Series B+) -Q3. What is your current ARR (or MRR) and runway in months? -Q4. What is your team size and structure? -Q5. What industry and customer segment do you serve? -Q6. What are your top 3 priorities for the next 90 days? -Q7. What is your biggest current risk or blocker? -``` +**Cross-cutting (6):** board-deck-builder, scenario-war-room, competitive-intel, org-health-diagnostic, ma-playbook, intl-expansion. -After collecting answers, the agent writes structured output: +**Culture & collaboration (6):** culture-architect, company-os, founder-coach, strategic-alignment, change-management, internal-narrative. -```markdown -# Company Context -- Name: <answer> -- Stage: <answer> -- Industry: <answer> -- Team size: <answer> -- Key metrics: <ARR/MRR, growth rate, runway> -- Top priorities: <answer> -- Key risks: <answer> -``` +Plus this index (1). 37 stdlib-only Python tools and 68 reference docs across the bundle. -#### `/cs:board` — Full Board Meeting +## Routing Quick Reference -Convenes all relevant executive roles in three phases: +Full matrix in [`chief-of-staff/SKILL.md`](https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor/skills/chief-of-staff/SKILL.md) and [`references/routing-matrix.md`](https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor/skills/chief-of-staff/references/routing-matrix.md). Primary roles: CFO (capital/burn), CRO (pipeline/sales), CMO (positioning), CPO (roadmap/PMF), CTO (architecture), COO (ops/OKRs), CHRO (people), CISO (security), GC (contracts/term sheets), CDO (data strategy/training-data rights), CAIO (AI strategy/evals), CCO (retention/GRR), VPE (delivery/DORA), CEO (direction). Multi-domain or irreversible → board meeting. -``` -Phase 1 — Framing: Chief of Staff states the decision and success criteria. -Phase 2 — Isolation: Each role produces independent analysis (no cross-talk). -Phase 3 — Debate: Roles surface conflicts, stress-test assumptions, align on - a recommendation. Dissenting views are preserved in the log. -``` +## Related Layers -Use for high-stakes or cross-functional decisions. Confirm at least 3 roles have weighed in before accepting a conclusion. - -### Chief of Staff Routing Matrix - -When a question arrives without a role prefix, the Chief of Staff maps it to the appropriate executive using these primary signals: - -| Topic Signal | Primary Role | Supporting Roles | -|---|---|---| -| Fundraising, valuation, burn | CFO | CEO, CRO | -| Architecture, build vs. buy, tech debt | CTO | CPO, CISO | -| Hiring, culture, performance | CHRO | CEO, Executive Mentor | -| GTM, demand gen, positioning | CMO | CRO, CPO | -| Revenue, pipeline, sales motion | CRO | CMO, CFO | -| Security, compliance, risk | CISO | CTO, CFO | -| Product roadmap, prioritisation | CPO | CTO, CMO | -| Ops, process, scaling | COO | CFO, CHRO | -| Vision, strategy, investor relations | CEO | Executive Mentor | -| Career, founder psychology, leadership | Executive Mentor | CEO, CHRO | -| Multi-domain / unclear | Chief of Staff convenes board | All relevant roles | - -### Invoking a Specific Role Directly - -To bypass Chief of Staff routing and address one executive directly, prefix your question with the role name: - -``` -CFO: What is our optimal burn rate heading into a Series A? -CTO: Should we rebuild our auth layer in-house or buy a solution? -CHRO: How do we design a performance review process for a 15-person team? -``` - -The Chief of Staff still logs the exchange; only routing is skipped. - -### Example: Strategic Question - -**Input:** "Should we raise a Series A now or extend runway and grow ARR first?" - -**Output format:** -- **Bottom Line:** Extend runway 6 months; raise at $2M ARR for better terms. -- **What:** Current $800K ARR is below the threshold most Series A investors benchmark. -- **Why:** Raising now increases dilution risk; 6-month extension is achievable with current burn. -- **How to Act:** Cut 2 low-ROI channels, hit $2M ARR, then run a 6-week fundraise sprint. -- **Your Decision:** Proceed with extension / Raise now anyway (choose one). - -### Example: company-context.md (after /cs:setup) - -```markdown -# Company Context -- Name: Acme Inc. -- Stage: Seed ($800K ARR) -- Industry: B2B SaaS -- Team size: 12 -- Key metrics: 15% MoM growth, 18-month runway -- Top priorities: Series A readiness, enterprise GTM -``` - -## What's Included - -### 10 C-Suite Roles -CEO, CTO, COO, CPO, CMO, CFO, CRO, CISO, CHRO, Executive Mentor - -### 6 Orchestration Skills -Founder Onboard, Chief of Staff (router), Board Meeting, Decision Logger, Agent Protocol, Context Engine - -### 6 Cross-Cutting Capabilities -Board Deck Builder, Scenario War Room, Competitive Intel, Org Health Diagnostic, M&A Playbook, International Expansion - -### 6 Culture & Collaboration -Culture Architect, Company OS, Founder Coach, Strategic Alignment, Change Management, Internal Narrative - -## Key Features - -- **Internal Quality Loop:** Self-verify → peer-verify → critic pre-screen → present -- **Two-Layer Memory:** Raw transcripts + approved decisions only (prevents hallucinated consensus) -- **Board Meeting Isolation:** Phase 2 independent analysis before cross-examination -- **Proactive Triggers:** Context-driven early warnings without being asked -- **Structured Output:** Bottom Line → What → Why → How to Act → Your Decision -- **25 Python Tools:** All stdlib-only, CLI-first, JSON output, zero dependencies - -## See Also - -- `CLAUDE.md` — full architecture diagram and integration guide -- `agent-protocol/SKILL.md` — communication standard and quality loop details -- `chief-of-staff/SKILL.md` — routing matrix for all 28 skills +- [`c-level-advisor/c-level-agents`](https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor/c-level-agents) — 13 cs-* persona agents + 21 `/cs:*` slash commands on top of these skills +- [`c-level-advisor/executive-mentor`](https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor/executive-mentor) — adversarial `/em:*` critic commands +- [`c-level-advisor/CLAUDE.md`](https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor/CLAUDE.md) — full architecture diagram and integration guide diff --git a/docs/skills/c-level-advisor/ceo-advisor.md b/docs/skills/c-level-advisor/ceo-advisor.md index 7ad4f394..e353b108 100644 --- a/docs/skills/c-level-advisor/ceo-advisor.md +++ b/docs/skills/c-level-advisor/ceo-advisor.md @@ -152,7 +152,7 @@ Explore multiple futures. For every strategic decision, generate at least 3 path ## Communication -All output passes the Internal Quality Loop before reaching the founder (see `agent-protocol/SKILL.md`). +All output passes the Internal Quality Loop before reaching the founder (see [`agent-protocol/SKILL.md`](https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor/skills/agent-protocol/SKILL.md)). - Self-verify: source attribution, assumption audit, confidence scoring - Peer-verify: cross-functional claims validated by the owning role - Critic pre-screen: high-stakes decisions reviewed by Executive Mentor diff --git a/docs/skills/c-level-advisor/cfo-advisor.md b/docs/skills/c-level-advisor/cfo-advisor.md index 012e2021..863e963a 100644 --- a/docs/skills/c-level-advisor/cfo-advisor.md +++ b/docs/skills/c-level-advisor/cfo-advisor.md @@ -128,7 +128,7 @@ Work through financial logic step by step. Show all math. Be conservative in pro ## Communication -All output passes the Internal Quality Loop before reaching the founder (see `agent-protocol/SKILL.md`). +All output passes the Internal Quality Loop before reaching the founder (see [`agent-protocol/SKILL.md`](https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor/skills/agent-protocol/SKILL.md)). - Self-verify: source attribution, assumption audit, confidence scoring - Peer-verify: cross-functional claims validated by the owning role - Critic pre-screen: high-stakes decisions reviewed by Executive Mentor diff --git a/docs/skills/c-level-advisor/chief-ai-officer-advisor.md b/docs/skills/c-level-advisor/chief-ai-officer-advisor.md index 763d07ea..0adb069d 100644 --- a/docs/skills/c-level-advisor/chief-ai-officer-advisor.md +++ b/docs/skills/c-level-advisor/chief-ai-officer-advisor.md @@ -212,17 +212,17 @@ python scripts/ai_cost_economics.py workload.json ## Adjacent Skills -- [`skills/chief-data-officer-advisor`](https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor/skills/chief-data-officer-advisor) — Training data rights, data product strategy (chains directly to model decisions) -- [`skills/cto-advisor`](https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor/skills/cto-advisor) — Architecture capacity, scaling cliffs (esp. for self-hosted inference) -- [`skills/ciso-advisor`](https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor/skills/ciso-advisor) — Threat modeling for AI (prompt injection, jailbreak, training data poisoning) -- [`skills/general-counsel-advisor`](https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor/skills/general-counsel-advisor) — AI contracts (vendor liability, output ownership, training-data licensing) -- [`skills/cfo-advisor`](https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor/skills/cfo-advisor) — Build-vs-buy TCO math, multi-year vendor commitments -- [`skills/chro-advisor`](https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor/skills/chro-advisor) — AI team hiring + comp -- [`engineering/rag-architect`](https://github.com/alirezarezvani/claude-skills/tree/main/engineering/rag-architect) — Tactical RAG implementation -- [`engineering/agent-designer`](https://github.com/alirezarezvani/claude-skills/tree/main/engineering/agent-designer) — Tactical agent architecture -- [`engineering/prompt-governance`](https://github.com/alirezarezvani/claude-skills/tree/main/engineering/prompt-governance) — Tactical prompt management -- [`engineering/self-eval`](https://github.com/alirezarezvani/claude-skills/tree/main/engineering/self-eval) — Tactical eval infrastructure -- [`engineering/llm-cost-optimizer`](https://github.com/alirezarezvani/claude-skills/tree/main/engineering/llm-cost-optimizer) — Tactical inference cost optimization +- `c-level-advisor/skills/chief-data-officer-advisor/` — Training data rights, data product strategy (chains directly to model decisions) +- `c-level-advisor/skills/cto-advisor/` — Architecture capacity, scaling cliffs (esp. for self-hosted inference) +- `c-level-advisor/skills/ciso-advisor/` — Threat modeling for AI (prompt injection, jailbreak, training data poisoning) +- `c-level-advisor/skills/general-counsel-advisor/` — AI contracts (vendor liability, output ownership, training-data licensing) +- `c-level-advisor/skills/cfo-advisor/` — Build-vs-buy TCO math, multi-year vendor commitments +- `c-level-advisor/skills/chro-advisor/` — AI team hiring + comp +- `engineering/skills/rag-architect/` — Tactical RAG implementation +- `engineering/skills/agent-designer/` — Tactical agent architecture +- `engineering/prompt-governance/` — Tactical prompt management +- `engineering/skills/self-eval/` — Tactical eval infrastructure +- `engineering/llm-cost-optimizer/` — Tactical inference cost optimization ## References diff --git a/docs/skills/c-level-advisor/chief-customer-officer-advisor.md b/docs/skills/c-level-advisor/chief-customer-officer-advisor.md index 253c482b..28325b24 100644 --- a/docs/skills/c-level-advisor/chief-customer-officer-advisor.md +++ b/docs/skills/c-level-advisor/chief-customer-officer-advisor.md @@ -191,12 +191,12 @@ python scripts/cs_coverage_calculator.py book.json ## Adjacent Skills -- [`skills/cro-advisor`](https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor/skills/cro-advisor) — Revenue math, NRR, expansion comp (CCO owns customer experience; CRO owns revenue math; clean split) -- [`skills/cpo-advisor`](https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor/skills/cpo-advisor) — Product strategy, JTBD (CCO surfaces product gaps; CPO decides roadmap) -- [`skills/cmo-advisor`](https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor/skills/cmo-advisor) — Customer marketing, advocacy, references -- [`skills/cfo-advisor`](https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor/skills/cfo-advisor) — CS team cost, retention-impact-on-revenue math -- [`skills/chro-advisor`](https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor/skills/chro-advisor) — CS team hiring + leveling -- [`business-growth`](https://github.com/alirezarezvani/claude-skills/tree/main/business-growth) — Tactical CS execution: health scores, CRM workflows, onboarding tooling +- `c-level-advisor/skills/cro-advisor/` — Revenue math, NRR, expansion comp (CCO owns customer experience; CRO owns revenue math; clean split) +- `c-level-advisor/skills/cpo-advisor/` — Product strategy, JTBD (CCO surfaces product gaps; CPO decides roadmap) +- `c-level-advisor/skills/cmo-advisor/` — Customer marketing, advocacy, references +- `c-level-advisor/skills/cfo-advisor/` — CS team cost, retention-impact-on-revenue math +- `c-level-advisor/skills/chro-advisor/` — CS team hiring + leveling +- `business-growth/` — Tactical CS execution: health scores, CRM workflows, onboarding tooling ## References diff --git a/docs/skills/c-level-advisor/chief-data-officer-advisor.md b/docs/skills/c-level-advisor/chief-data-officer-advisor.md index 0c758e4d..25042d48 100644 --- a/docs/skills/c-level-advisor/chief-data-officer-advisor.md +++ b/docs/skills/c-level-advisor/chief-data-officer-advisor.md @@ -184,14 +184,14 @@ python scripts/data_product_strategy_picker.py profile.json ## Adjacent Skills -- [`skills/cto-advisor`](https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor/skills/cto-advisor) — architecture capacity, scaling cliffs -- [`skills/ciso-advisor`](https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor/skills/ciso-advisor) — data security, threat modeling for productized data -- [`skills/general-counsel-advisor`](https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor/skills/general-counsel-advisor) — contractual constraints, DPA, training-data rights -- [`skills/cfo-advisor`](https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor/skills/cfo-advisor) — build-vs-buy TCO, M&A valuation math -- [`skills/chro-advisor`](https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor/skills/chro-advisor) — data team hiring, leveling, comp -- [`engineering/database-designer`](https://github.com/alirezarezvani/claude-skills/tree/main/engineering/database-designer) — tactical schema design -- [`engineering/rag-architect`](https://github.com/alirezarezvani/claude-skills/tree/main/engineering/rag-architect) — tactical AI/RAG implementation -- [`engineering/llm-cost-optimizer`](https://github.com/alirezarezvani/claude-skills/tree/main/engineering/llm-cost-optimizer) — model cost management +- `c-level-advisor/skills/cto-advisor/` — architecture capacity, scaling cliffs +- `c-level-advisor/skills/ciso-advisor/` — data security, threat modeling for productized data +- `c-level-advisor/skills/general-counsel-advisor/` — contractual constraints, DPA, training-data rights +- `c-level-advisor/skills/cfo-advisor/` — build-vs-buy TCO, M&A valuation math +- `c-level-advisor/skills/chro-advisor/` — data team hiring, leveling, comp +- `engineering/skills/database-designer/` — tactical schema design +- `engineering/skills/rag-architect/` — tactical AI/RAG implementation +- `engineering/llm-cost-optimizer/` — model cost management ## References diff --git a/docs/skills/c-level-advisor/chief-of-staff.md b/docs/skills/c-level-advisor/chief-of-staff.md index ff87e0b5..a32ecc7a 100644 --- a/docs/skills/c-level-advisor/chief-of-staff.md +++ b/docs/skills/c-level-advisor/chief-of-staff.md @@ -84,6 +84,11 @@ Full rules in `references/routing-matrix.md`. | Company direction, investor relations | CEO | Board | | Market strategy, positioning | CMO | CRO | | M&A, pivots | CEO | Board | +| Contracts, term sheets, legal exposure, IP | GC | CEO | +| Data strategy, training-data rights, data assets | CDO | CAIO | +| AI strategy, model selection, evals, AI risk | CAIO | CTO | +| Retention, churn, customer success, NRR/GRR | CCO | CRO | +| Eng delivery, DORA metrics, eng hiring, team structure | VPE | CTO | --- @@ -136,7 +141,10 @@ Full framework in `references/synthesis-framework.md`. ## Decision Log -Track decisions to `~/.claude/decision-log.md`. +Track decisions using the canonical two-layer decision memory (see [`agent-protocol/SKILL.md`](https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor/skills/agent-protocol/SKILL.md) → "Decision Memory (Canonical Layout)"): + +- **Layer 1 (raw):** `~/.claude/decisions/raw/YYYY-MM-DD-{slug}.md` — full deliberation transcript +- **Layer 2 (approved):** `~/.claude/decisions/approved/YYYY-MM-DD-{slug}.md` — founder-approved decisions only ``` ## Decision: [Name] @@ -147,14 +155,16 @@ Owner: [Who executes] Review: [When to check back] ``` -At session start: if a review date has passed, flag it: *"You decided [X] on [date]. Worth a check-in?"* +At session start: scan `~/.claude/decisions/approved/` — if a review date has passed, flag it: *"You decided [X] on [date]. Worth a check-in?"* + +Migration: a legacy single-file log at `~/.claude/decision-log.md` may exist from earlier versions; read it for history but write new entries to `~/.claude/decisions/`. --- ## Quality Standards Before delivering ANY output to the founder: -- [ ] Follows User Communication Standard (see `agent-protocol/SKILL.md`) +- [ ] Follows User Communication Standard (see [`agent-protocol/SKILL.md`](https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor/skills/agent-protocol/SKILL.md)) - [ ] Bottom line is first — no preamble, no process narration - [ ] Company context loaded (not generic advice) - [ ] Every finding has WHAT + WHY + HOW @@ -169,9 +179,9 @@ Before delivering ANY output to the founder: ## Ecosystem Awareness -The Chief of Staff routes to **28 skills total**: -- **10 C-suite roles** — CEO, CTO, COO, CPO, CMO, CFO, CRO, CISO, CHRO, Executive Mentor -- **6 orchestration skills** — cs-onboard, context-engine, board-meeting, decision-logger, agent-protocol +The Chief of Staff routes to **33 skills total**: +- **15 C-suite roles** — CEO, CTO, COO, CPO, CMO, CFO, CRO, CISO, CHRO, General Counsel, CDO, CAIO, CCO, VPE, Executive Mentor +- **6 orchestration skills** — cs-onboard, context-engine, board-meeting, decision-logger, agent-protocol, chief-of-staff - **6 cross-cutting skills** — board-deck-builder, scenario-war-room, competitive-intel, org-health-diagnostic, ma-playbook, intl-expansion - **6 culture & collaboration skills** — culture-architect, company-os, founder-coach, strategic-alignment, change-management, internal-narrative diff --git a/docs/skills/c-level-advisor/chro-advisor.md b/docs/skills/c-level-advisor/chro-advisor.md index fb1fc932..30755df8 100644 --- a/docs/skills/c-level-advisor/chro-advisor.md +++ b/docs/skills/c-level-advisor/chro-advisor.md @@ -132,7 +132,7 @@ Start with the human impact, then validate with metrics. Every people decision m ## Communication -All output passes the Internal Quality Loop before reaching the founder (see `agent-protocol/SKILL.md`). +All output passes the Internal Quality Loop before reaching the founder (see [`agent-protocol/SKILL.md`](https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor/skills/agent-protocol/SKILL.md)). - Self-verify: source attribution, assumption audit, confidence scoring - Peer-verify: cross-functional claims validated by the owning role - Critic pre-screen: high-stakes decisions reviewed by Executive Mentor diff --git a/docs/skills/c-level-advisor/ciso-advisor.md b/docs/skills/c-level-advisor/ciso-advisor.md index d3522185..c518fe25 100644 --- a/docs/skills/c-level-advisor/ciso-advisor.md +++ b/docs/skills/c-level-advisor/ciso-advisor.md @@ -123,7 +123,7 @@ Evaluate every decision through probability × impact. Quantify risks in busines ## Communication -All output passes the Internal Quality Loop before reaching the founder (see `agent-protocol/SKILL.md`). +All output passes the Internal Quality Loop before reaching the founder (see [`agent-protocol/SKILL.md`](https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor/skills/agent-protocol/SKILL.md)). - Self-verify: source attribution, assumption audit, confidence scoring - Peer-verify: cross-functional claims validated by the owning role - Critic pre-screen: high-stakes decisions reviewed by Executive Mentor diff --git a/docs/skills/c-level-advisor/cmo-advisor.md b/docs/skills/c-level-advisor/cmo-advisor.md index a1a4b6bf..85520248 100644 --- a/docs/skills/c-level-advisor/cmo-advisor.md +++ b/docs/skills/c-level-advisor/cmo-advisor.md @@ -157,7 +157,7 @@ Draft a marketing strategy, then critique it from the customer's perspective. Re ## Communication -All output passes the Internal Quality Loop before reaching the founder (see `agent-protocol/SKILL.md`). +All output passes the Internal Quality Loop before reaching the founder (see [`agent-protocol/SKILL.md`](https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor/skills/agent-protocol/SKILL.md)). - Self-verify: source attribution, assumption audit, confidence scoring - Peer-verify: cross-functional claims validated by the owning role - Critic pre-screen: high-stakes decisions reviewed by Executive Mentor diff --git a/docs/skills/c-level-advisor/competitive-intel.md b/docs/skills/c-level-advisor/competitive-intel.md index 505d7154..0265109c 100644 --- a/docs/skills/c-level-advisor/competitive-intel.md +++ b/docs/skills/c-level-advisor/competitive-intel.md @@ -23,13 +23,13 @@ competitive intelligence, competitor analysis, battlecard, win/loss analysis, co ## Quick Start -``` -/ci:landscape — Map your competitive space (direct, indirect, future) -/ci:battlecard [name] — Build a sales battlecard for a specific competitor -/ci:winloss — Analyze recent wins and losses by reason -/ci:update [name] — Track what a competitor did recently -/ci:map — Build competitive positioning map -``` +Ask in natural language for the deliverable you need: + +> "Map our competitive landscape" — direct, indirect, and future competitors +> "Build a battlecard for [competitor]" — sales-ready battlecard +> "Run a win/loss analysis" — recent wins and losses by reason +> "What did [competitor] do recently?" — competitor update tracking +> "Build a competitive positioning map" — 2x2 positioning map ## Framework: 5-Layer Intelligence System diff --git a/docs/skills/c-level-advisor/coo-advisor.md b/docs/skills/c-level-advisor/coo-advisor.md index f81c015a..e2ea9ee1 100644 --- a/docs/skills/c-level-advisor/coo-advisor.md +++ b/docs/skills/c-level-advisor/coo-advisor.md @@ -125,7 +125,7 @@ Map processes sequentially. Identify each step, handoff, and decision point. Fin ## Communication -All output passes the Internal Quality Loop before reaching the founder (see `agent-protocol/SKILL.md`). +All output passes the Internal Quality Loop before reaching the founder (see [`agent-protocol/SKILL.md`](https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor/skills/agent-protocol/SKILL.md)). - Self-verify: source attribution, assumption audit, confidence scoring - Peer-verify: cross-functional claims validated by the owning role - Critic pre-screen: high-stakes decisions reviewed by Executive Mentor diff --git a/docs/skills/c-level-advisor/cpo-advisor.md b/docs/skills/c-level-advisor/cpo-advisor.md index a1a3ce76..6a26dc38 100644 --- a/docs/skills/c-level-advisor/cpo-advisor.md +++ b/docs/skills/c-level-advisor/cpo-advisor.md @@ -188,7 +188,7 @@ Decompose to fundamental user needs. Question every assumption about what custom ## Communication -All output passes the Internal Quality Loop before reaching the founder (see `agent-protocol/SKILL.md`). +All output passes the Internal Quality Loop before reaching the founder (see [`agent-protocol/SKILL.md`](https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor/skills/agent-protocol/SKILL.md)). - Self-verify: source attribution, assumption audit, confidence scoring - Peer-verify: cross-functional claims validated by the owning role - Critic pre-screen: high-stakes decisions reviewed by Executive Mentor diff --git a/docs/skills/c-level-advisor/cro-advisor.md b/docs/skills/c-level-advisor/cro-advisor.md index 0c853546..37aa3545 100644 --- a/docs/skills/c-level-advisor/cro-advisor.md +++ b/docs/skills/c-level-advisor/cro-advisor.md @@ -171,7 +171,7 @@ Pipeline math must be explicit: leads → MQLs → SQLs → opportunities → cl ## Communication -All output passes the Internal Quality Loop before reaching the founder (see `agent-protocol/SKILL.md`). +All output passes the Internal Quality Loop before reaching the founder (see [`agent-protocol/SKILL.md`](https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor/skills/agent-protocol/SKILL.md)). - Self-verify: source attribution, assumption audit, confidence scoring - Peer-verify: cross-functional claims validated by the owning role - Critic pre-screen: high-stakes decisions reviewed by Executive Mentor diff --git a/docs/skills/c-level-advisor/cto-advisor.md b/docs/skills/c-level-advisor/cto-advisor.md index fb83af0a..bb6ae9ff 100644 --- a/docs/skills/c-level-advisor/cto-advisor.md +++ b/docs/skills/c-level-advisor/cto-advisor.md @@ -240,7 +240,7 @@ Research the technical landscape first. Analyze options against constraints (tim ## Communication -All output passes the Internal Quality Loop before reaching the founder (see `agent-protocol/SKILL.md`). +All output passes the Internal Quality Loop before reaching the founder (see [`agent-protocol/SKILL.md`](https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor/skills/agent-protocol/SKILL.md)). - Self-verify: source attribution, assumption audit, confidence scoring - Peer-verify: cross-functional claims validated by the owning role - Critic pre-screen: high-stakes decisions reviewed by Executive Mentor diff --git a/docs/skills/c-level-advisor/decision-logger.md b/docs/skills/c-level-advisor/decision-logger.md index 21c35c0c..2948b548 100644 --- a/docs/skills/c-level-advisor/decision-logger.md +++ b/docs/skills/c-level-advisor/decision-logger.md @@ -49,20 +49,24 @@ python scripts/decision_tracker.py --search "pricing" # Search decisions ## Two-Layer Architecture +Storage follows the canonical two-layer decision memory (see [`agent-protocol/SKILL.md`](https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor/skills/agent-protocol/SKILL.md) → "Decision Memory (Canonical Layout)") — the same layout `/cs:decide` writes. + ### Layer 1 — Raw Transcripts -**Location:** `memory/board-meetings/YYYY-MM-DD-raw.md` +**Location:** `~/.claude/decisions/raw/YYYY-MM-DD-<slug>.md` - Full Phase 2 agent contributions, Phase 3 critique, Phase 4 synthesis - All debates, including rejected arguments - **NEVER auto-loaded.** Only on explicit founder request. -- Archive after 90 days → `memory/board-meetings/archive/YYYY/` +- Archive after 90 days → `~/.claude/decisions/raw/archive/YYYY/` ### Layer 2 — Approved Decisions -**Location:** `memory/board-meetings/decisions.md` +**Location:** `~/.claude/decisions/approved/` — one record per decision (`YYYY-MM-DD-<slug>.md`) plus the append-only index `decisions.md` - ONLY founder-approved decisions, action items, user corrections - **Loaded automatically in Phase 1 of every board meeting** - Append-only. Decisions are never deleted — only superseded. - Managed by Chief of Staff after Phase 5. Never written by agents directly. +Migration: a legacy `memory/board-meetings/` folder may exist from earlier versions; read it for history but write all new entries to `~/.claude/decisions/`. + --- ## Decision Entry Format @@ -86,7 +90,7 @@ python scripts/decision_tracker.py --search "pricing" # Search decisions **Supersedes:** [DATE of previous decision on same topic, if any] **Superseded by:** [Filled in retroactively if overridden later] -**Raw transcript:** memory/board-meetings/[DATE]-raw.md +**Raw transcript:** ~/.claude/decisions/raw/[DATE]-<slug>.md ``` --- @@ -118,10 +122,10 @@ To reopen: founder must explicitly say "reopen [topic] from [DATE]". ## Logging Workflow (Post Phase 5) 1. Founder approves synthesis -2. Write Layer 1 raw transcript → `YYYY-MM-DD-raw.md` -3. Check conflicts against `decisions.md` +2. Write Layer 1 raw transcript → `~/.claude/decisions/raw/YYYY-MM-DD-<slug>.md` +3. Check conflicts against `~/.claude/decisions/approved/decisions.md` 4. Surface conflicts → wait for founder resolution -5. Append approved entries to `decisions.md` +5. Write the approved record to `~/.claude/decisions/approved/YYYY-MM-DD-<slug>.md` and append to the index `decisions.md` 6. Confirm: decisions logged, actions tracked, DO_NOT_RESURFACE flags added --- @@ -139,10 +143,11 @@ Never delete completed items. The history is the record. ## File Structure ``` -memory/board-meetings/ -├── decisions.md # Layer 2: append-only, founder-approved -├── YYYY-MM-DD-raw.md # Layer 1: full transcript per meeting -└── archive/YYYY/ # Raw files after 90 days +~/.claude/decisions/ +├── raw/YYYY-MM-DD-<slug>.md # Layer 1: full transcript per meeting +├── raw/archive/YYYY/ # Raw files after 90 days +├── approved/YYYY-MM-DD-<slug>.md # Layer 2: one record per approved decision +└── approved/decisions.md # Layer 2 index: append-only, founder-approved ``` --- diff --git a/docs/skills/c-level-advisor/executive-mentor-hard-call.md b/docs/skills/c-level-advisor/executive-mentor-hard-call.md index 36b9ceb2..bc58875a 100644 --- a/docs/skills/c-level-advisor/executive-mentor-hard-call.md +++ b/docs/skills/c-level-advisor/executive-mentor-hard-call.md @@ -1,6 +1,6 @@ --- title: "/em:hard-call — Framework for Decisions With No Good Options — Agent Skill for Executives" -description: "/em -hard-call — Framework for Decisions With No Good Options. Agent skill for Claude Code, Codex CLI, Gemini CLI, OpenClaw." +description: "/em:hard-call — Framework for decisions with no good options. Use when every option is painful and a structured 10/10/10 + regret-minimization pass. Agent skill for Claude Code, Codex CLI, Gemini CLI, OpenClaw." --- # /em:hard-call — Framework for Decisions With No Good Options @@ -102,7 +102,7 @@ Hard decisions almost always get harder if communication is bad. The decision it For every hard call, plan: - **Who needs to know first** (the person directly affected, before anyone else) - **How you'll tell them** (in person when possible, never via email for personal impact) -- **What you'll say** (honest, direct, compassionate — see `references/hard_things.md`) +- **What you'll say** (honest, direct, compassionate — see [`references/hard_things.md`](https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor/executive-mentor/skills/executive-mentor/references/hard_things.md)) - **What they can ask** (be ready for every question) - **What comes next** (give them a clear picture of what happens after) @@ -111,7 +111,7 @@ For every hard call, plan: ## Decision-Specific Frameworks ### Firing a Co-Founder -See `references/hard_things.md — Co-Founder Conflicts` for full framework. +See [`references/hard_things.md — Co-Founder Conflicts`](https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor/executive-mentor/skills/executive-mentor/references/hard_things.md — Co-Founder Conflicts) for full framework. Key questions to answer first: - Is this a performance problem or a values/culture problem? (Different conversations) diff --git a/docs/skills/c-level-advisor/executive-mentor-postmortem.md b/docs/skills/c-level-advisor/executive-mentor-postmortem.md index 4d10c2b8..d9ee6952 100644 --- a/docs/skills/c-level-advisor/executive-mentor-postmortem.md +++ b/docs/skills/c-level-advisor/executive-mentor-postmortem.md @@ -1,6 +1,6 @@ --- title: "/em:postmortem — Honest Analysis of What Went Wrong — Agent Skill for Executives" -description: "/em -postmortem — Honest Analysis of What Went Wrong. Agent skill for Claude Code, Codex CLI, Gemini CLI, OpenClaw." +description: "/em:postmortem — Honest analysis of what went wrong. Use after a failed launch, missed quarter, or bad hire to run a blameless 5-Whys retrospective. Agent skill for Claude Code, Codex CLI, Gemini CLI, OpenClaw." --- # /em:postmortem — Honest Analysis of What Went Wrong diff --git a/docs/skills/c-level-advisor/executive-mentor-stress-test.md b/docs/skills/c-level-advisor/executive-mentor-stress-test.md index da9f943b..4caad8f5 100644 --- a/docs/skills/c-level-advisor/executive-mentor-stress-test.md +++ b/docs/skills/c-level-advisor/executive-mentor-stress-test.md @@ -1,6 +1,6 @@ --- title: "/em:stress-test — Business Assumption Stress Testing — Agent Skill for Executives" -description: "/em -stress-test — Business Assumption Stress Testing. Agent skill for Claude Code, Codex CLI, Gemini CLI, OpenClaw." +description: "/em:stress-test — Business assumption stress testing. Use before betting on a plan whose core assumptions are unvalidated — e.g. stress-testing. Agent skill for Claude Code, Codex CLI, Gemini CLI, OpenClaw." --- # /em:stress-test — Business Assumption Stress Testing diff --git a/docs/skills/c-level-advisor/executive-mentor.md b/docs/skills/c-level-advisor/executive-mentor.md index 197f8497..f8456384 100644 --- a/docs/skills/c-level-advisor/executive-mentor.md +++ b/docs/skills/c-level-advisor/executive-mentor.md @@ -73,19 +73,19 @@ This isn't therapy. It's preparation. ## Commands in Detail ### `/em:challenge <plan>` -Takes any plan — roadmap, GTM, hiring, fundraising — and finds what breaks first. Identifies assumptions, rates confidence, maps dependencies. Output: numbered vulnerabilities with severity (Critical / High / Medium). See `skills/challenge/SKILL.md` +Takes any plan — roadmap, GTM, hiring, fundraising — and finds what breaks first. Identifies assumptions, rates confidence, maps dependencies. Output: numbered vulnerabilities with severity (Critical / High / Medium). See [`challenge/SKILL.md`](https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor/executive-mentor/skills/challenge/SKILL.md) ### `/em:board-prep <agenda>` -48 hours before investors. What are the 10 hardest questions? What data do you need cold? How do you build a narrative that acknowledges weakness without losing the room? Prepares you for the adversarial board, not the friendly one. See `skills/board-prep/SKILL.md` +48 hours before investors. What are the 10 hardest questions? What data do you need cold? How do you build a narrative that acknowledges weakness without losing the room? Prepares you for the adversarial board, not the friendly one. See [`board-prep/SKILL.md`](https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor/executive-mentor/skills/board-prep/SKILL.md) ### `/em:hard-call <decision>` -Reversibility test. 10/10/10 framework. Stakeholder impact mapping. Communication planning. For decisions with no good answer — only less bad ones. See `skills/hard-call/SKILL.md` +Reversibility test. 10/10/10 framework. Stakeholder impact mapping. Communication planning. For decisions with no good answer — only less bad ones. See [`hard-call/SKILL.md`](https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor/executive-mentor/skills/hard-call/SKILL.md) ### `/em:stress-test <assumption>` -"$5B market." "$2M ARR by December." "3-year moat." Every plan is built on assumptions. Surfaces counter-evidence, models the downside, proposes the hedge. See `skills/stress-test/SKILL.md` +"$5B market." "$2M ARR by December." "3-year moat." Every plan is built on assumptions. Surfaces counter-evidence, models the downside, proposes the hedge. See [`stress-test/SKILL.md`](https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor/executive-mentor/skills/stress-test/SKILL.md) ### `/em:postmortem <event>` -Lost deal. Failed feature. Missed quarter. No blame sessions, no whitewash. 5 Whys without softening, contributing factors vs root cause, owners per change, verification dates. See `skills/postmortem/SKILL.md` +Lost deal. Failed feature. Missed quarter. No blame sessions, no whitewash. 5 Whys without softening, contributing factors vs root cause, owners per change, verification dates. See [`postmortem/SKILL.md`](https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor/executive-mentor/skills/postmortem/SKILL.md) ## Agents & References @@ -130,7 +130,7 @@ Assume the plan will fail. Find the three most likely failure modes. For each, i ## Communication -All output passes the Internal Quality Loop before reaching the founder (see `agent-protocol/SKILL.md`). +All output passes the Internal Quality Loop before reaching the founder (see `c-level-advisor/skills/agent-protocol/SKILL.md`). - Self-verify: source attribution, assumption audit, confidence scoring - Peer-verify: cross-functional claims validated by the owning role - Critic pre-screen: high-stakes decisions reviewed by Executive Mentor diff --git a/docs/skills/c-level-advisor/general-counsel-advisor.md b/docs/skills/c-level-advisor/general-counsel-advisor.md index e33baac7..9488d5a1 100644 --- a/docs/skills/c-level-advisor/general-counsel-advisor.md +++ b/docs/skills/c-level-advisor/general-counsel-advisor.md @@ -144,11 +144,11 @@ See `references/ip_and_regulatory.md` for sequencing. ## Adjacent Skills -- [`skills/ciso-advisor`](https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor/skills/ciso-advisor) — Compliance overlap (SOC 2, ISO 27001, HIPAA technical safeguards) -- [`skills/cfo-advisor`](https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor/skills/cfo-advisor) — Term sheet → dilution math -- [`skills/ma-playbook`](https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor/skills/ma-playbook) — Acquisition agreements, integration playbooks -- [`ra-qm-team`](https://github.com/alirezarezvani/claude-skills/tree/main/ra-qm-team) — ISO 13485, MDR, FDA 510(k), GDPR execution -- [`gc-review/SKILL.md`](https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor/c-level-agents/skills/gc-review/SKILL.md) — `/cs:gc-review` slash command +- `c-level-advisor/skills/ciso-advisor/` — Compliance overlap (SOC 2, ISO 27001, HIPAA technical safeguards) +- `c-level-advisor/skills/cfo-advisor/` — Term sheet → dilution math +- `c-level-advisor/skills/ma-playbook/` — Acquisition agreements, integration playbooks +- `ra-qm-team/` — ISO 13485, MDR, FDA 510(k), GDPR execution +- `c-level-advisor/c-level-agents/skills/gc-review/SKILL.md` — `/cs:gc-review` slash command ## References diff --git a/docs/skills/c-level-advisor/index.md b/docs/skills/c-level-advisor/index.md index efada583..d9ed047d 100644 --- a/docs/skills/c-level-advisor/index.md +++ b/docs/skills/c-level-advisor/index.md @@ -35,11 +35,11 @@ description: "61 c-level advisory skills — executive advisory agent skill and Structured multi-agent deliberation that prevents groupthink, captures minority views, and produces clean, actionable... -- **[C-Level Advisory Ecosystem](c-level-skills.md)** +- **[C-Level Advisory Bundle — Index](c-level-skills.md)** --- - A complete virtual board of directors for founders and executives. + This is the bundle index, not an advisor. It tells you what exists and where to start; the skills below do the work. - **[CEO Advisor](ceo-advisor.md)** diff --git a/docs/skills/c-level-advisor/ma-playbook.md b/docs/skills/c-level-advisor/ma-playbook.md index 85c13cd2..47b56a86 100644 --- a/docs/skills/c-level-advisor/ma-playbook.md +++ b/docs/skills/c-level-advisor/ma-playbook.md @@ -45,10 +45,15 @@ M&A, mergers and acquisitions, due diligence, acquisition, acqui-hire, integrati | Customers | Churn rate, NPS, contract terms | High churn, short contracts | ### Valuation Approaches -- **Revenue multiple:** Industry-dependent (2-15x ARR for SaaS) -- **Comparable transactions:** What similar companies sold for + +The ranges below are **illustrative, not current market data** — always verify against current market comps before using them in a model or negotiation. + +- **Revenue multiple:** Industry-dependent (illustrative range: 2-15x ARR for SaaS, varying with growth rate, NRR, and rate environment) +- **Comparable transactions:** What similar companies sold for — the most defensible anchor - **DCF:** For profitable companies only (most startups: use multiples) -- **Acqui-hire:** $1-3M per engineer in hot markets +- **Acqui-hire:** Illustrative range: $1-3M per engineer in hot talent markets + +**Sources to verify against (check the latest edition):** the SaaS Capital Index (private SaaS revenue multiples, updated monthly), Software Equity Group (SEG) Annual/Quarterly SaaS M&A Reports (transaction multiples), and Aventis Advisors' SaaS valuation multiples reports. Cross-check at least two before anchoring a price. ### Integration Frameworks See `references/integration-playbook.md` for the 100-day integration plan. @@ -86,12 +91,24 @@ See `references/integration-playbook.md` for the 100-day integration plan. - Integration plan doesn't exist or is "we'll figure it out" - Valuation based on projections, not actuals +## Verification Loop (before any LOI or signature) + +This skill frames the deal; two sibling skills verify it. Hand off — don't duplicate: + +1. **Legal terms** → `general-counsel-advisor`: run the LOI/term sheet through [`scripts/term_sheet_analyzer.py`](https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor/skills/general-counsel-advisor/scripts/term_sheet_analyzer.py) (12-dimension 0-100 score) and the definitive docs through [`scripts/contract_risk_scanner.py`](https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor/skills/general-counsel-advisor/scripts/contract_risk_scanner.py) (12 founder-killer patterns: earnout traps, uncapped indemnity, vague IP, etc.). Any 🔴 finding goes to outside counsel before signing. +2. **Data diligence** → `chief-data-officer-advisor`: run [`scripts/ai_training_data_audit.py`](https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor/skills/chief-data-officer-advisor/scripts/ai_training_data_audit.py) (training-data rights, GDPR Art. 6 basis) and [`scripts/data_asset_valuator.py`](https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor/skills/chief-data-officer-advisor/scripts/data_asset_valuator.py) (data-asset value, M&A multiplier with carve-out penalties) on the target's data estate. Undocumented consent provenance is a price-reduction or walk-away item. +3. **Valuation math** → `cfo-advisor` tools for the quantitative model; this playbook stays qualitative. + +Loop the findings back into the negotiation-points table above before the next counter. + ## Integration with C-Suite Roles | Role | Contribution to M&A | |------|-------------------| | CEO | Strategic rationale, negotiation lead | | CFO | Valuation, deal structure, financing | +| GC | LOI/term sheet review, contract risk scan, regulatory triggers | +| CDO | Data diligence: training-data rights, data-asset valuation | | CTO | Technical due diligence, integration architecture | | CHRO | People due diligence, retention planning | | COO | Integration execution, process merge | @@ -100,3 +117,5 @@ See `references/integration-playbook.md` for the 100-day integration plan. ## Resources - `references/integration-playbook.md` — 100-day post-acquisition integration plan - `references/due-diligence-checklist.md` — comprehensive DD checklist by domain +- [`general-counsel-advisor/SKILL.md`](https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor/skills/general-counsel-advisor/SKILL.md) — term sheet analyzer + contract risk scanner +- [`chief-data-officer-advisor/SKILL.md`](https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor/skills/chief-data-officer-advisor/SKILL.md) — data diligence + data-asset valuation diff --git a/docs/skills/c-level-advisor/org-health-diagnostic.md b/docs/skills/c-level-advisor/org-health-diagnostic.md index d7c7d41a..0c950ca2 100644 --- a/docs/skills/c-level-advisor/org-health-diagnostic.md +++ b/docs/skills/c-level-advisor/org-health-diagnostic.md @@ -28,11 +28,10 @@ python scripts/health_scorer.py # Guided CLI — enter metrics, get score python scripts/health_scorer.py --json # Output raw JSON for integration ``` -Or describe your metrics: -``` -/health [paste your key metrics or answer prompts] -/health:dimension [financial|revenue|product|engineering|people|ops|security|market] -``` +Or describe your metrics in natural language: + +> "Run an org health check" — paste your key metrics or answer prompts +> "Score our [financial|revenue|product|engineering|people|ops|security|market] health" — single-dimension deep dive ## The 8 Dimensions diff --git a/docs/skills/c-level-advisor/scenario-war-room.md b/docs/skills/c-level-advisor/scenario-war-room.md index 59965bdb..90510ab7 100644 --- a/docs/skills/c-level-advisor/scenario-war-room.md +++ b/docs/skills/c-level-advisor/scenario-war-room.md @@ -27,12 +27,11 @@ scenario planning, war room, what-if analysis, risk modeling, cascading effects, python scripts/scenario_modeler.py # Interactive scenario builder with cascade modeling ``` -Or describe the scenario: -``` -/war-room "What if we lose our top customer AND miss the Q3 fundraise?" -/war-room "What if 3 engineers quit AND we need to ship by Q3?" -/war-room "What if our market shrinks 30% AND a competitor raises $50M?" -``` +Or describe the scenario in natural language: + +> "What if we lose our top customer AND miss the Q3 fundraise?" +> "What if 3 engineers quit AND we need to ship by Q3?" +> "What if our market shrinks 30% AND a competitor raises $50M?" ## What This Is Not diff --git a/docs/skills/c-level-advisor/vpe-advisor.md b/docs/skills/c-level-advisor/vpe-advisor.md index 70639496..4cad6ffb 100644 --- a/docs/skills/c-level-advisor/vpe-advisor.md +++ b/docs/skills/c-level-advisor/vpe-advisor.md @@ -210,13 +210,13 @@ python ../../skills/vpe-advisor/scripts/eng_team_structure_designer.py team.json ## Adjacent Skills -- [`skills/cto-advisor`](https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor/skills/cto-advisor) — Architecture, scaling cliffs, tech debt strategy (CTO decides what to build; VPE decides how to ship) -- [`skills/chro-advisor`](https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor/skills/chro-advisor) — Hiring systems (ladders, bands, leveling rubrics company-wide); VPE owns eng-specific funnel execution -- [`skills/coo-advisor`](https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor/skills/coo-advisor) — Operating cadence company-wide; VPE owns eng-specific cadence -- [`engineering/slo-architect`](https://github.com/alirezarezvani/claude-skills/tree/main/engineering/slo-architect) — SLO design (tactical; VPE owns the policy that SLOs are required) -- [`engineering/chaos-engineering`](https://github.com/alirezarezvani/claude-skills/tree/main/engineering/chaos-engineering) — Chaos experiment design (tactical resilience) -- [`engineering/feature-flags-architect`](https://github.com/alirezarezvani/claude-skills/tree/main/engineering/feature-flags-architect) — Progressive delivery (tactical deployment) -- [`engineering/kubernetes-operator`](https://github.com/alirezarezvani/claude-skills/tree/main/engineering/kubernetes-operator) — K8s operator pattern (tactical infra) +- `c-level-advisor/skills/cto-advisor/` — Architecture, scaling cliffs, tech debt strategy (CTO decides what to build; VPE decides how to ship) +- `c-level-advisor/skills/chro-advisor/` — Hiring systems (ladders, bands, leveling rubrics company-wide); VPE owns eng-specific funnel execution +- `c-level-advisor/skills/coo-advisor/` — Operating cadence company-wide; VPE owns eng-specific cadence +- `engineering/skills/slo-architect/` — SLO design (tactical; VPE owns the policy that SLOs are required) +- `engineering/skills/chaos-engineering/` — Chaos experiment design (tactical resilience) +- `engineering/skills/feature-flags-architect/` — Progressive delivery (tactical deployment) +- `engineering/skills/kubernetes-operator/` — K8s operator pattern (tactical infra) - `cs-engineering-lead` agent — Day-to-day incident + on-call coordination (VPE owns the operating model that engineering-lead executes) ## References diff --git a/docs/skills/commercial/channel-economics.md b/docs/skills/commercial/channel-economics.md index f8b9775e..dde5b37c 100644 --- a/docs/skills/commercial/channel-economics.md +++ b/docs/skills/commercial/channel-economics.md @@ -85,6 +85,13 @@ Take the three reports into the quarterly channel review. The skill recommends; All scripts: stdlib only. `--help`, `--sample`, `--input`, `--output` work on all three. Industry tuning via `--profile {saas,api,enterprise-software,marketplace,hardware}` on the two analyzers. +## Quick example + +```bash +# Emits fully-loaded cost-to-serve per channel (direct vs partner-led) for the built-in sample channel data +cd commercial/skills/channel-economics && python3 scripts/cost_to_serve_calculator.py --sample +``` + ## References - `references/channel_economics_canon.md` — Skok, Bessemer State of the Cloud, Tunguz, Pacific Crest / KeyBanc SaaS Survey, Ramanujam, Jay McBain (Canalys) diff --git a/docs/skills/commercial/deal-desk.md b/docs/skills/commercial/deal-desk.md index 39691ee2..8fc5e540 100644 --- a/docs/skills/commercial/deal-desk.md +++ b/docs/skills/commercial/deal-desk.md @@ -107,7 +107,7 @@ python3 scripts/terms_redliner.py --sample python3 scripts/terms_redliner.py --input my_deal_terms.json --output json ``` -The sample (a 28%-discount enterprise SaaS deal with uncapped indemnity + MFN) correctly DECLINEs at 55.4 / 100 composite and routes to AE → Deal Desk → VP Sales → CFO → CRO → General Counsel. +The sample (a 28%-discount enterprise SaaS deal with uncapped indemnity + MFN) correctly DECLINEs at 52.7 / 100 composite — the 28% discount destroys 35.9% of the deal's margin dollars under fixed COGS — and routes to AE → Deal Desk → VP Sales → CFO → CRO → General Counsel. ## Forcing-question library (Matt Pocock grill discipline) diff --git a/docs/skills/commercial/partnerships-architect.md b/docs/skills/commercial/partnerships-architect.md index af170ce9..5cefcd6d 100644 --- a/docs/skills/commercial/partnerships-architect.md +++ b/docs/skills/commercial/partnerships-architect.md @@ -95,6 +95,13 @@ when triggered. All scripts: stdlib only. `--help` and `--sample` work on all three. +## Quick example + +```bash +# Emits a 5-tier partner classification with deterministic floors per tier for the built-in sample partner +cd commercial/skills/partnerships-architect && python3 scripts/partner_tier_classifier.py --sample +``` + ## References - `references/channel_partner_canon.md` — Caro on HP indirect channels, Chintagunta on channel economics, Hessling on partner programs, Forrester channel software stack, IDC channel research, Tien Tzuo subscription-channel models, Geoffrey Moore whole-product partnerships diff --git a/docs/skills/commercial/pricing-strategist.md b/docs/skills/commercial/pricing-strategist.md index d4e99024..3515447d 100644 --- a/docs/skills/commercial/pricing-strategist.md +++ b/docs/skills/commercial/pricing-strategist.md @@ -73,6 +73,13 @@ Take model + range + packaging into the pricing committee. Skill does not commit All scripts: stdlib only. `--help` and `--sample` work on all three. +## Quick example + +```bash +# Emits a scored 5-model pricing-fit recommendation (subscription / usage / value / freemium / hybrid) for the built-in example +cd commercial/skills/pricing-strategist && python3 scripts/pricing_model_picker.py --sample +``` + ## References - `references/saas_pricing_canon.md` — Skok, Tunguz, Campbell, Ramanujam, BVP, Shevlin, Stanford GSB diff --git a/docs/skills/compliance-os/ai-act-readiness.md b/docs/skills/compliance-os/ai-act-readiness.md index 9b4781ab..0c4afaf4 100644 --- a/docs/skills/compliance-os/ai-act-readiness.md +++ b/docs/skills/compliance-os/ai-act-readiness.md @@ -79,13 +79,13 @@ The EU AI Act compliance operator pressure-tests any AI system before EU deploym ```bash # 1. Risk classification -python ../../ra-qm-team/skills/eu-ai-act-specialist/scripts/ai_system_risk_classifier.py systems.json +python ra-qm-team/skills/eu-ai-act-specialist/scripts/ai_system_risk_classifier.py systems.json # 2. If high-risk: conformity assessment -python ../../ra-qm-team/skills/eu-ai-act-specialist/scripts/conformity_assessment_planner.py system.json +python ra-qm-team/skills/eu-ai-act-specialist/scripts/conformity_assessment_planner.py system.json # 3. Per-role obligation matrix -python ../../ra-qm-team/skills/eu-ai-act-specialist/scripts/ai_act_obligation_tracker.py roles.json +python ra-qm-team/skills/eu-ai-act-specialist/scripts/ai_act_obligation_tracker.py roles.json # 4. Cross-framework reuse (ISO 42001 etc.) python ../../skills/compliance-os/scripts/cross_framework_mapper.py program.json diff --git a/docs/skills/compliance-os/aims-audit.md b/docs/skills/compliance-os/aims-audit.md index 007f6747..47287037 100644 --- a/docs/skills/compliance-os/aims-audit.md +++ b/docs/skills/compliance-os/aims-audit.md @@ -73,13 +73,13 @@ The ISO 42001 AIMS specialist pressure-tests any AI Management System work. Six ```bash # 1. AIMS gap analysis -python ../../ra-qm-team/skills/iso42001-specialist/scripts/aims_gap_analyzer.py evidence.json +python ra-qm-team/skills/iso42001-specialist/scripts/aims_gap_analyzer.py evidence.json # 2. AI risk register -python ../../ra-qm-team/skills/iso42001-specialist/scripts/ai_risk_register_builder.py risks.json +python ra-qm-team/skills/iso42001-specialist/scripts/ai_risk_register_builder.py risks.json # 3. Internal audit plan -python ../../ra-qm-team/skills/iso42001-specialist/scripts/aims_audit_scheduler.py audit_scope.json +python ra-qm-team/skills/iso42001-specialist/scripts/aims_audit_scheduler.py audit_scope.json # 4. Cross-framework reuse map (via compliance-os) python ../../skills/compliance-os/scripts/cross_framework_mapper.py program.json diff --git a/docs/skills/compliance-os/compliance-os.md b/docs/skills/compliance-os/compliance-os.md index d76acc6b..0d3e0adf 100644 --- a/docs/skills/compliance-os/compliance-os.md +++ b/docs/skills/compliance-os/compliance-os.md @@ -182,17 +182,17 @@ python scripts/evidence_pool_generator.py program.json ## Adjacent Skills -- [`skills/iso42001-specialist`](https://github.com/alirezarezvani/claude-skills/tree/main/compliance-os/ra-qm-team/skills/iso42001-specialist) — ISO 42001 deep-dive (paired with compliance-team-iso42001 plugin) -- [`skills/eu-ai-act-specialist`](https://github.com/alirezarezvani/claude-skills/tree/main/compliance-os/ra-qm-team/skills/eu-ai-act-specialist) — EU AI Act deep-dive (paired with compliance-team-eu-ai-act plugin) -- [`skills/information-security-manager-iso27001`](https://github.com/alirezarezvani/claude-skills/tree/main/compliance-os/ra-qm-team/skills/information-security-manager-iso27001) — ISO 27001 ISMS deep-dive -- [`skills/quality-manager-qms-iso13485`](https://github.com/alirezarezvani/claude-skills/tree/main/compliance-os/ra-qm-team/skills/quality-manager-qms-iso13485) — ISO 13485 QMS deep-dive -- [`skills/gdpr-dsgvo-expert`](https://github.com/alirezarezvani/claude-skills/tree/main/compliance-os/ra-qm-team/skills/gdpr-dsgvo-expert) — GDPR deep-dive -- [`skills/soc2-compliance`](https://github.com/alirezarezvani/claude-skills/tree/main/compliance-os/ra-qm-team/skills/soc2-compliance) — SOC 2 deep-dive -- [`skills/fda-consultant-specialist`](https://github.com/alirezarezvani/claude-skills/tree/main/compliance-os/ra-qm-team/skills/fda-consultant-specialist) — FDA QSR deep-dive -- [`skills/mdr-745-specialist`](https://github.com/alirezarezvani/claude-skills/tree/main/compliance-os/ra-qm-team/skills/mdr-745-specialist) — EU MDR 745 deep-dive -- [`skills/risk-management-specialist`](https://github.com/alirezarezvani/claude-skills/tree/main/compliance-os/ra-qm-team/skills/risk-management-specialist) — ISO 14971 deep-dive -- [`c-level-advisor/chief-ai-officer-advisor`](https://github.com/alirezarezvani/claude-skills/tree/main/compliance-os/c-level-advisor/chief-ai-officer-advisor) — Executive AI risk decisions (build-vs-buy, model selection) -- [`skills/general-counsel-advisor`](https://github.com/alirezarezvani/claude-skills/tree/main/compliance-os/c-level-advisor/skills/general-counsel-advisor) — Legal review for novel cases +- `ra-qm-team/skills/iso42001-specialist/` — ISO 42001 deep-dive (paired with compliance-team-iso42001 plugin) +- `ra-qm-team/skills/eu-ai-act-specialist/` — EU AI Act deep-dive (paired with compliance-team-eu-ai-act plugin) +- `ra-qm-team/skills/information-security-manager-iso27001/` — ISO 27001 ISMS deep-dive +- `ra-qm-team/skills/quality-manager-qms-iso13485/` — ISO 13485 QMS deep-dive +- `ra-qm-team/skills/gdpr-dsgvo-expert/` — GDPR deep-dive +- `ra-qm-team/skills/soc2-compliance/` — SOC 2 deep-dive +- `ra-qm-team/skills/fda-consultant-specialist/` — FDA QSR deep-dive +- `ra-qm-team/skills/mdr-745-specialist/` — EU MDR 745 deep-dive +- `ra-qm-team/skills/risk-management-specialist/` — ISO 14971 deep-dive +- `c-level-advisor/chief-ai-officer-advisor/` — Executive AI risk decisions (build-vs-buy, model selection) +- `c-level-advisor/skills/general-counsel-advisor/` — Legal review for novel cases ## References diff --git a/docs/skills/compliance-os/compliance-readiness.md b/docs/skills/compliance-os/compliance-readiness.md index 8bcba80d..1903c015 100644 --- a/docs/skills/compliance-os/compliance-readiness.md +++ b/docs/skills/compliance-os/compliance-readiness.md @@ -140,7 +140,7 @@ python ../../skills/compliance-os/scripts/audit_simulator.py scope.json - Agent: [`cs-compliance-officer`](https://github.com/alirezarezvani/claude-skills/tree/main/compliance-os/agents/cs-compliance-officer.md) - Skill: [`compliance-os`](https://github.com/alirezarezvani/claude-skills/tree/main/compliance-os/skills/compliance-os/SKILL.md) -- Adjacent: [`skills/iso42001-specialist`](https://github.com/alirezarezvani/claude-skills/tree/main/compliance-os/ra-qm-team/skills/iso42001-specialist), [`skills/eu-ai-act-specialist`](https://github.com/alirezarezvani/claude-skills/tree/main/compliance-os/ra-qm-team/skills/eu-ai-act-specialist), [`skills/information-security-manager-iso27001`](https://github.com/alirezarezvani/claude-skills/tree/main/compliance-os/ra-qm-team/skills/information-security-manager-iso27001), [`skills/soc2-compliance`](https://github.com/alirezarezvani/claude-skills/tree/main/compliance-os/ra-qm-team/skills/soc2-compliance), [`skills/gdpr-dsgvo-expert`](https://github.com/alirezarezvani/claude-skills/tree/main/compliance-os/ra-qm-team/skills/gdpr-dsgvo-expert) +- Adjacent: `ra-qm-team/skills/iso42001-specialist/`, `ra-qm-team/skills/eu-ai-act-specialist/`, `ra-qm-team/skills/information-security-manager-iso27001/`, `ra-qm-team/skills/soc2-compliance/`, `ra-qm-team/skills/gdpr-dsgvo-expert/` --- diff --git a/docs/skills/compliance-os/fda-qsr-audit-prep.md b/docs/skills/compliance-os/fda-qsr-audit-prep.md index 593ae367..79721cd0 100644 --- a/docs/skills/compliance-os/fda-qsr-audit-prep.md +++ b/docs/skills/compliance-os/fda-qsr-audit-prep.md @@ -80,13 +80,13 @@ The FDA QSR auditor pressure-tests any US medical-device QSR work. Six questions ```bash # 1. QSR compliance posture -python ../../ra-qm-team/skills/fda-consultant-specialist/scripts/qsr_compliance_checker.py compliance_state.json +python ra-qm-team/skills/fda-consultant-specialist/scripts/qsr_compliance_checker.py compliance_state.json # 2. FDA submission tracking (510(k) / PMA / IDE) -python ../../ra-qm-team/skills/fda-consultant-specialist/scripts/fda_submission_tracker.py submissions.json +python ra-qm-team/skills/fda-consultant-specialist/scripts/fda_submission_tracker.py submissions.json # 3. HIPAA overlap (if connected device handles PHI) -python ../../ra-qm-team/skills/fda-consultant-specialist/scripts/hipaa_risk_assessment.py phi_inventory.json +python ra-qm-team/skills/fda-consultant-specialist/scripts/hipaa_risk_assessment.py phi_inventory.json # 4. Mock FDA inspection python ../../skills/compliance-os/scripts/audit_simulator.py fda_qsr_scope.json diff --git a/docs/skills/compliance-os/gdpr-audit-prep.md b/docs/skills/compliance-os/gdpr-audit-prep.md index 8cf84453..bd26c3ae 100644 --- a/docs/skills/compliance-os/gdpr-audit-prep.md +++ b/docs/skills/compliance-os/gdpr-audit-prep.md @@ -83,13 +83,13 @@ The GDPR DPO auditor pressure-tests any privacy compliance work. Six Article-cit ```bash # 1. Compliance posture -python ../../ra-qm-team/skills/gdpr-dsgvo-expert/scripts/gdpr_compliance_checker.py compliance_state.json +python ra-qm-team/skills/gdpr-dsgvo-expert/scripts/gdpr_compliance_checker.py compliance_state.json # 2. DPIA for high-risk activities -python ../../ra-qm-team/skills/gdpr-dsgvo-expert/scripts/dpia_generator.py processing_activity.json +python ra-qm-team/skills/gdpr-dsgvo-expert/scripts/dpia_generator.py processing_activity.json # 3. DSAR workflow validation -python ../../ra-qm-team/skills/gdpr-dsgvo-expert/scripts/data_subject_rights_tracker.py dsar_log.json +python ra-qm-team/skills/gdpr-dsgvo-expert/scripts/data_subject_rights_tracker.py dsar_log.json # 4. Cross-framework reuse with ISO 27001 + SOC 2 + ISO 42001 python ../../skills/compliance-os/scripts/cross_framework_mapper.py program.json diff --git a/docs/skills/compliance-os/iso13485-audit-prep.md b/docs/skills/compliance-os/iso13485-audit-prep.md index c61a42dc..0daf9187 100644 --- a/docs/skills/compliance-os/iso13485-audit-prep.md +++ b/docs/skills/compliance-os/iso13485-audit-prep.md @@ -80,7 +80,7 @@ The ISO 13485 QMS auditor pressure-tests any medical-device QMS work. Six tracea ```bash # 1. Audit programme optimization -python ../../ra-qm-team/skills/qms-audit-expert/scripts/audit_schedule_optimizer.py audit_scope.json +python ra-qm-team/skills/qms-audit-expert/scripts/audit_schedule_optimizer.py audit_scope.json # 2. Mock audit for readiness check python ../../skills/compliance-os/scripts/audit_simulator.py iso13485_scope.json diff --git a/docs/skills/compliance-os/iso27001-audit-prep.md b/docs/skills/compliance-os/iso27001-audit-prep.md index f7609df1..089b6720 100644 --- a/docs/skills/compliance-os/iso27001-audit-prep.md +++ b/docs/skills/compliance-os/iso27001-audit-prep.md @@ -76,7 +76,7 @@ The ISO 27001 ISMS auditor pressure-tests any ISMS work. Six sample-driven quest ```bash # 1. Audit programme planning -python ../../ra-qm-team/skills/isms-audit-expert/scripts/isms_audit_scheduler.py audit_scope.json +python ra-qm-team/skills/isms-audit-expert/scripts/isms_audit_scheduler.py audit_scope.json # 2. Mock audit for readiness check python ../../skills/compliance-os/scripts/audit_simulator.py iso27001_scope.json diff --git a/docs/skills/compliance-os/soc2-audit-prep.md b/docs/skills/compliance-os/soc2-audit-prep.md index d6ef35e5..11fc9134 100644 --- a/docs/skills/compliance-os/soc2-audit-prep.md +++ b/docs/skills/compliance-os/soc2-audit-prep.md @@ -79,13 +79,13 @@ The SOC 2 Type II auditor pressure-tests any SOC 2 work. Six observation-period- ```bash # 1. Scoping + gap analysis (pre-observation) -python ../../ra-qm-team/skills/soc2-compliance/scripts/gap_analyzer.py current_state.json +python ra-qm-team/skills/soc2-compliance/scripts/gap_analyzer.py current_state.json # 2. Control matrix with ISO 27001 cross-walk -python ../../ra-qm-team/skills/soc2-compliance/scripts/control_matrix_builder.py program.json +python ra-qm-team/skills/soc2-compliance/scripts/control_matrix_builder.py program.json # 3. Continuous evidence tracking (during observation) -python ../../ra-qm-team/skills/soc2-compliance/scripts/evidence_tracker.py evidence_log.json +python ra-qm-team/skills/soc2-compliance/scripts/evidence_tracker.py evidence_log.json # 4. Mock audit (pre-field-test month 10) python ../../skills/compliance-os/scripts/audit_simulator.py soc2_scope.json diff --git a/docs/skills/engineering-team/email-template-builder.md b/docs/skills/engineering-team/email-template-builder.md index b0229aeb..03d4e944 100644 --- a/docs/skills/engineering-team/email-template-builder.md +++ b/docs/skills/engineering-team/email-template-builder.md @@ -372,8 +372,8 @@ export async function sendEmail(to: string, payload: EmailPayload) { // emails/i18n/en.ts export const en = { welcome: { - preview: (name: "string-welcome-to-myapp-name" - heading: (name: "string-welcome-to-myapp-name" + preview: (name: string) => `Welcome to MyApp, ${name}!`, + heading: (name: string) => `Welcome to MyApp, ${name}!`, body: (days: number) => `You've got ${days} days to explore everything.`, cta: "Confirm Email Address", }, @@ -382,8 +382,8 @@ export const en = { // emails/i18n/de.ts export const de = { welcome: { - preview: (name: "string-willkommen-bei-myapp-name" - heading: (name: "string-willkommen-bei-myapp-name" + preview: (name: string) => `Willkommen bei MyApp, ${name}!`, + heading: (name: string) => `Willkommen bei MyApp, ${name}!`, body: (days: number) => `Du hast ${days} Tage Zeit, alles zu erkunden.`, cta: "E-Mail-Adresse bestätigen", }, diff --git a/docs/skills/engineering-team/engineering-skills.md b/docs/skills/engineering-team/engineering-skills.md index b3731ea6..36834bc1 100644 --- a/docs/skills/engineering-team/engineering-skills.md +++ b/docs/skills/engineering-team/engineering-skills.md @@ -1,6 +1,6 @@ --- title: "Engineering Team Skills — Agent Skill & Codex Plugin" -description: "23 engineering agent skills and plugins for Claude Code, Codex, Gemini CLI, Cursor, OpenClaw, and 6 more tools. Architecture, frontend, backend, QA." +description: "Index of the engineering-team skills bundle for Claude Code, Codex, Gemini CLI, Cursor, OpenClaw, and 6 more tools. Architecture, frontend, backend." --- # Engineering Team Skills @@ -16,13 +16,13 @@ description: "23 engineering agent skills and plugins for Claude Code, Codex, Ge </div> -23 production-ready engineering skills organized into core engineering, AI/ML/Data, and specialized tools. +32 production-ready engineering skills organized into core engineering, security, AI/ML/Data, and specialized tools. ## Quick Start ### Claude Code ``` -/read engineering-team/senior-fullstack/SKILL.md +/read engineering-team/skills/senior-fullstack/SKILL.md ``` ### Codex CLI @@ -82,6 +82,6 @@ No pip install needed. Scripts include embedded samples for demo mode. ## Rules -- Load only the specific skill SKILL.md you need — don't bulk-load all 23 +- Load only the specific skill SKILL.md you need — don't bulk-load all 32 - Use Python tools for analysis and scaffolding, not manual judgment - Check CLAUDE.md for tool usage examples and workflows diff --git a/docs/skills/engineering-team/epic-design.md b/docs/skills/engineering-team/epic-design.md index 5449b7f1..a691f1e4 100644 --- a/docs/skills/engineering-team/epic-design.md +++ b/docs/skills/engineering-team/epic-design.md @@ -248,7 +248,6 @@ These are MANDATORY in every output: | File | What's Inside | When to Read | |------|--------------|--------------| | `references/asset-pipeline.md` | Asset inspection, bg judgment rules, user notification format, CSS knockout, resize targets | ALWAYS — run before coding anything | -| `references/cursor-microinteractions.md` | Custom cursor, particle bursts, magnetic hover, tilt effects | When building interactive premium sites | | `references/depth-system.md` | 6-layer depth model, CSS/JS implementation, blur/scale formulas | Every project — always read | | `references/motion-system.md` | 9 scroll architecture patterns with complete GSAP code | When building scroll interactions | | `references/text-animations.md` | 13 text techniques with full implementation code | When animating any text | diff --git a/docs/skills/engineering-team/google-workspace-cli.md b/docs/skills/engineering-team/google-workspace-cli.md index aaf6e354..19f12880 100644 --- a/docs/skills/engineering-team/google-workspace-cli.md +++ b/docs/skills/engineering-team/google-workspace-cli.md @@ -1,6 +1,6 @@ --- title: "Google Workspace CLI — Agent Skill & Codex Plugin" -description: "Google Workspace administration via the gws CLI. Install, authenticate, and automate Gmail, Drive, Sheets, Calendar, Docs, Chat, and Tasks. Run. Agent skill for Claude Code, Codex CLI, Gemini CLI, OpenClaw." +description: "Google Workspace administration via the gws CLI (github.com/googleworkspace/cli). Install, authenticate, and automate Gmail, Drive, Sheets, Calendar. Agent skill for Claude Code, Codex CLI, Gemini CLI, OpenClaw." --- # Google Workspace CLI @@ -16,7 +16,9 @@ description: "Google Workspace administration via the gws CLI. Install, authenti </div> -Expert guidance and automation for Google Workspace administration using the open-source `gws` CLI. Covers installation, authentication, 18+ service APIs, 43 built-in recipes, and 10 persona bundles for role-based workflows. +Expert guidance and automation for Google Workspace administration using the open-source `gws` CLI ([github.com/googleworkspace/cli](https://github.com/googleworkspace/cli), Apache-2.0). The CLI builds its command surface dynamically from Google's Discovery Service, so it covers every supported Workspace API plus `+`-prefixed helper commands. This skill adds local Python tools (doctor, auth guide, recipe catalog, security audit, output analyzer). + +> **Verify before scripting:** `gws` generates commands at runtime from Google's API discovery documents, and the CLI is pre-v1.0. Always confirm a command's exact surface with `gws --help`, `gws <service> --help`, or `gws schema <service>.<resource>.<method>` before putting it in automation. Commands in this skill marked *(verify)* are illustrative of the `gws <service> <resource> <method>` pattern and must be checked against your installed version. --- @@ -32,37 +34,43 @@ python3 scripts/gws_doctor.py ### Send an Email ```bash -gws gmail users.messages send me --to "team@company.com" \ +gws gmail +send --to "team@company.com" \ --subject "Weekly Update" --body "Here's this week's summary..." ``` ### List Drive Files ```bash -gws drive files list --json --limit 20 | python3 scripts/output_analyzer.py --select "name,mimeType,modifiedTime" --format table +gws drive files list --params '{"pageSize": 20}' | python3 scripts/output_analyzer.py --select "name,mimeType,modifiedTime" --format table ``` --- ## Installation -### npm (recommended) +### npm (recommended; requires Node.js 18+) ```bash -npm install -g @anthropic/gws +npm install -g @googleworkspace/cli gws --version ``` +### Homebrew (macOS/Linux) + +```bash +brew install googleworkspace-cli +``` + ### Cargo (from source) ```bash -cargo install gws-cli +cargo install --git https://github.com/googleworkspace/cli --locked gws --version ``` ### Pre-built Binaries -Download from [github.com/googleworkspace/cli/releases](https://github.com/googleworkspace/cli/releases) for macOS, Linux, or Windows. +Download from [github.com/googleworkspace/cli/releases](https://github.com/googleworkspace/cli/releases) for macOS, Linux, or Windows. Nix users: `nix run github:googleworkspace/cli`. ### Verify Installation @@ -81,23 +89,22 @@ python3 scripts/gws_doctor.py # Step 1: Create Google Cloud project and OAuth credentials python3 scripts/auth_setup_guide.py --guide oauth -# Step 2: Run auth setup +# Step 2: Run interactive auth setup (uses gcloud if available) gws auth setup -# Step 3: Validate -gws auth status --json +# Step 3: Log in, requesting only the scopes you need +gws auth login -s drive,gmail,sheets ``` -### Service Account (Headless/CI) +### Headless/CI ```bash # Generate setup instructions python3 scripts/auth_setup_guide.py --guide service-account -# Configure with key file -export GWS_SERVICE_ACCOUNT_KEY=/path/to/key.json -export GWS_DELEGATED_USER=admin@company.com -gws auth status +# Export credentials from an interactive machine, then point the CLI at them +gws auth export --unmasked > credentials.json +export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/path/to/credentials.json ``` ### Environment Variables @@ -109,12 +116,12 @@ python3 scripts/auth_setup_guide.py --generate-env | Variable | Purpose | |----------|---------| -| `GWS_CLIENT_ID` | OAuth client ID | -| `GWS_CLIENT_SECRET` | OAuth client secret | -| `GWS_TOKEN_PATH` | Custom token storage path | -| `GWS_SERVICE_ACCOUNT_KEY` | Service account JSON key path | -| `GWS_DELEGATED_USER` | User to impersonate (service accounts) | -| `GWS_DEFAULT_FORMAT` | Default output format (json/ndjson/table) | +| `GOOGLE_WORKSPACE_CLI_CLIENT_ID` | OAuth client ID | +| `GOOGLE_WORKSPACE_CLI_CLIENT_SECRET` | OAuth client secret | +| `GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE` | Path to exported credentials JSON | +| `GOOGLE_WORKSPACE_CLI_TOKEN` | Pre-obtained OAuth token | +| `GOOGLE_WORKSPACE_CLI_CONFIG_DIR` | Override default config location | +| `GOOGLE_WORKSPACE_CLI_LOG` | Enable debug logging | ### Validate Authentication @@ -129,46 +136,50 @@ python3 scripts/auth_setup_guide.py --validate --json **Goal:** Automate email operations — send, search, label, and filter management. -### Send and Reply +### Send, Reply, Forward (helper commands) ```bash # Send a new email -gws gmail users.messages send me --to "client@example.com" \ - --subject "Proposal" --body "Please find attached..." \ - --attachment proposal.pdf +gws gmail +send --to "client@example.com" \ + --subject "Proposal" --body "Please find attached..." -# Reply to a thread -gws gmail users.messages reply me --thread-id <THREAD_ID> \ - --body "Thanks for your feedback..." +# Reply to a message (auto-threading); check exact flags with: gws gmail +reply --help +gws gmail +reply ... -# Forward a message -gws gmail users.messages forward me --message-id <MSG_ID> \ - --to "manager@company.com" +# Forward a message; check exact flags with: gws gmail +forward --help +gws gmail +forward ... + +# Unread inbox summary +gws gmail +triage ``` -### Search and Filter +### Search and Inspect (discovery commands) + +Discovery commands follow `gws <service> <resource> <method>` and take request +parameters as JSON via `--params` (query/path params) and `--json` (request body). +Inspect any method's exact schema first: ```bash -# Search emails -gws gmail users.messages list me --query "from:client@example.com after:2025/01/01" --json \ +# What does messages.list accept? (verify) +gws schema gmail.users.messages.list + +# Search emails (verify against the schema above) +gws gmail users messages list --params '{"userId": "me", "q": "from:client@example.com after:2025/01/01"}' \ | python3 scripts/output_analyzer.py --count -# List labels -gws gmail users.labels list me --json - -# Create a filter -gws gmail users.settings.filters create me \ - --criteria '{"from":"notifications@service.com"}' \ - --action '{"addLabelIds":["Label_123"],"removeLabelIds":["INBOX"]}' +# List labels (verify) +gws gmail users labels list --params '{"userId": "me"}' ``` ### Bulk Operations +Use `--dry-run` first, and `--page-all` to paginate (one JSON line per page): + ```bash -# Archive all read emails older than 30 days -gws gmail users.messages list me --query "is:read older_than:30d" --json \ - | python3 scripts/output_analyzer.py --select "id" --format json \ - | xargs -I {} gws gmail users.messages modify me {} --removeLabelIds INBOX +# Preview, then archive read emails older than 30 days (verify method schema first) +gws gmail users messages list --params '{"userId": "me", "q": "is:read older_than:30d"}' --page-all \ + | python3 scripts/output_analyzer.py --select "id" --format json +# Then feed ids to gmail users messages modify (see: gws schema gmail.users.messages.modify) ``` --- @@ -181,48 +192,45 @@ gws gmail users.messages list me --query "is:read older_than:30d" --json \ ```bash # List files -gws drive files list --json --limit 50 \ +gws drive files list --params '{"pageSize": 50}' \ | python3 scripts/output_analyzer.py --select "name,mimeType,size" --format table -# Upload a file -gws drive files create --name "Q1 Report" --upload report.pdf \ - --parents <FOLDER_ID> +# Upload a file (helper) +gws drive +upload ./report.pdf --name "Q1 Report" # Create a Google Sheet -gws sheets spreadsheets create --title "Budget 2026" --json +gws sheets spreadsheets create --json '{"properties": {"title": "Budget 2026"}}' -# Download/export -gws drive files export <FILE_ID> --mime "application/pdf" --output report.pdf +# Download/export — inspect the method first (verify) +gws schema drive.files.export ``` -### Sharing +### Sharing (verify schemas first) ```bash -# Share with user -gws drive permissions create <FILE_ID> \ - --type user --role writer --emailAddress "colleague@company.com" +# Inspect the permissions API surface +gws schema drive.permissions.create -# Share with domain (view only) -gws drive permissions create <FILE_ID> \ - --type domain --role reader --domain "company.com" +# Share with user (verify against schema) +gws drive permissions create --params '{"fileId": "<FILE_ID>"}' \ + --json '{"type": "user", "role": "writer", "emailAddress": "colleague@company.com"}' -# List who has access -gws drive permissions list <FILE_ID> --json +# List who has access (verify) +gws drive permissions list --params '{"fileId": "<FILE_ID>"}' ``` ### Sheets Data ```bash -# Read a range -gws sheets spreadsheets.values get <SHEET_ID> --range "Sheet1!A1:D10" --json +# Read values (helper); check exact flags with: gws sheets +read --help +gws sheets +read ... -# Write data -gws sheets spreadsheets.values update <SHEET_ID> --range "Sheet1!A1" \ - --values '[["Name","Score"],["Alice",95],["Bob",87]]' +# Append a row (helper); check exact flags with: gws sheets +append --help +gws sheets +append ... -# Append rows -gws sheets spreadsheets.values append <SHEET_ID> --range "Sheet1!A1" \ - --values '[["Charlie",92]]' +# Or use discovery methods (verify): +gws schema sheets.spreadsheets.values.update +gws sheets spreadsheets values get --params '{"spreadsheetId": "<SHEET_ID>", "range": "Sheet1!A1:D10"}' ``` --- @@ -234,39 +242,34 @@ gws sheets spreadsheets.values append <SHEET_ID> --range "Sheet1!A1" \ ### Event Management ```bash -# Create an event -gws calendar events insert primary \ - --summary "Sprint Planning" \ - --start "2026-03-15T10:00:00" --end "2026-03-15T11:00:00" \ - --attendees "team@company.com" \ - --location "Conference Room A" +# Create an event (helper); check exact flags with: gws calendar +insert --help +gws calendar +insert ... -# List upcoming events -gws calendar events list primary --timeMin "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \ - --maxResults 10 --json +# Upcoming events (helper, timezone-aware) +gws calendar +agenda -# Quick event (natural language) -gws helpers quick-event "Lunch with Sarah tomorrow at noon" +# Or via discovery (verify): +gws schema calendar.events.insert +gws calendar events list --params '{"calendarId": "primary", "maxResults": 10}' ``` ### Find Available Time ```bash -# Check free/busy for multiple people -gws helpers find-time \ - --attendees "alice@co.com,bob@co.com,charlie@co.com" \ - --duration 60 --within "2026-03-15,2026-03-19" --json +# Free/busy via the Calendar API (verify schema first) +gws schema calendar.freebusy.query +gws calendar freebusy query --json '{"timeMin": "...", "timeMax": "...", "items": [{"id": "alice@co.com"}]}' ``` -### Standup Report +### Standup Report (workflow helpers) ```bash -# Generate daily standup from calendar + tasks -gws recipes standup-report --json \ +# Today's meetings + tasks +gws workflow +standup-report \ | python3 scripts/output_analyzer.py --format table -# Meeting prep (agenda + attendee info) -gws recipes meeting-prep --event-id <EVENT_ID> +# Next meeting prep; check exact flags with: gws workflow +meeting-prep --help +gws workflow +meeting-prep ``` --- @@ -307,9 +310,9 @@ python3 scripts/workspace_audit.py --demo python3 scripts/workspace_audit.py --json | python3 scripts/output_analyzer.py \ --filter "status=FAIL" --select "area,check,remediation" -# Execute remediation (example: restrict external sharing) -gws drive about get --json # Check current settings -# Follow remediation commands from audit output +# Execute remediation (example: check current Drive settings first; verify) +gws drive about get --params '{"fields": "*"}' +# Follow remediation commands from audit output (verify each against gws --help) ``` --- @@ -340,18 +343,18 @@ All scripts are stdlib-only, support `--json` output, and include demo mode with ### Automation -1. Pipe `--json` output through `output_analyzer.py` for filtering and aggregation -2. Use recipes for multi-step operations instead of chaining raw commands -3. Select a persona bundle to scope recipes to your role -4. Use NDJSON format (`--format ndjson`) for streaming large result sets -5. Set `GWS_DEFAULT_FORMAT=json` in your shell profile for scripting +1. All `gws` output is structured JSON — pipe it through `output_analyzer.py` for filtering and aggregation +2. Use `gws workflow +*` helpers for multi-step operations instead of chaining raw commands +3. Use the local recipe catalog (`gws_recipe_runner.py`) as command templates, then verify each against `gws --help` +4. `--page-all` emits one JSON line per page (NDJSON) for streaming large result sets +5. Use `--dry-run` to preview any request before executing it ### Performance -1. Use `--fields` to request only needed fields (reduces payload size) -2. Use `--limit` to cap results when browsing -3. Use `--page-all` only when you need complete datasets -4. Batch operations with recipes rather than individual API calls +1. Request only needed fields via the API's `fields` parameter in `--params` (reduces payload size) +2. Use `pageSize` in `--params` to cap results when browsing +3. Use `--page-all` only when you need complete datasets; tune with `--page-limit` / `--page-delay` +4. Prefer `+` helpers (single optimized calls) over hand-chained API calls 5. Cache frequently accessed data (e.g., label IDs, folder IDs) in variables --- diff --git a/docs/skills/engineering-team/incident-commander.md b/docs/skills/engineering-team/incident-commander.md index fdeef80d..10b0c95a 100644 --- a/docs/skills/engineering-team/incident-commander.md +++ b/docs/skills/engineering-team/incident-commander.md @@ -24,7 +24,9 @@ description: "Comprehensive incident response framework from detection through r ## Overview -The Incident Commander skill provides a comprehensive incident response framework for managing technology incidents from detection through resolution and post-incident review. This skill implements battle-tested practices from SRE and DevOps teams at scale, providing structured tools for severity classification, timeline reconstruction, and thorough post-incident analysis. +Incident response framework for **availability/reliability incidents** (outages, degradations, failed deploys): severity classification, timeline reconstruction, and post-incident review. + +**This is NOT security incident triage.** For security events (ransomware, intrusion, data exfiltration, IOC analysis, NIST SP 800-61 forensics), route to `incident-response`. Both skills use SEV1-SEV4 labels; this one scores operational impact (users, revenue, SLA), while `incident-response` classifies attack types and forensic handling. ## Key Features @@ -391,10 +393,10 @@ Status page: {link} echo '{"description": "Users reporting 500 errors, database connections timing out", "affected_users": "80%", "business_impact": "high"}' | python scripts/incident_classifier.py # Reconstruct timeline from logs -python scripts/timeline_reconstructor.py --input assets/db_incident_events.json --output timeline.md +python scripts/timeline_reconstructor.py --input assets/sample_timeline_events.json --output timeline.md # Generate PIR after resolution -python scripts/pir_generator.py --incident assets/db_incident_data.json --timeline timeline.md --output pir.md +python scripts/pir_generator.py --incident assets/sample_incident_data.json --timeline timeline.md --output pir.md ``` ### Example 2: API Rate Limiting Incident @@ -404,10 +406,10 @@ python scripts/pir_generator.py --incident assets/db_incident_data.json --timeli echo "API rate limits causing customer API calls to fail" | python scripts/incident_classifier.py --format text # Build timeline from multiple sources -python scripts/timeline_reconstructor.py --input assets/api_incident_logs.json --detect-phases --gap-analysis +python scripts/timeline_reconstructor.py --input assets/simple_timeline_events.json --detect-phases --gap-analysis # Generate comprehensive PIR -python scripts/pir_generator.py --incident assets/api_incident_summary.json --rca-method fishbone --action-items +python scripts/pir_generator.py --incident assets/sample_incident_pir_data.json --rca-method fishbone --action-items ``` ## Best Practices @@ -478,10 +480,3 @@ python scripts/pir_generator.py --incident assets/api_incident_summary.json --rc - Deployment tracking systems - Feature flag platforms for quick rollbacks -## Conclusion - -The Incident Commander skill provides a comprehensive framework for managing incidents from detection through post-incident review. By implementing structured processes, clear communication templates, and thorough analysis tools, teams can improve their incident response capabilities and build more resilient systems. - -The key to successful incident management is preparation, practice, and continuous learning. Use this framework as a starting point, but adapt it to your organization's specific needs, culture, and technical environment. - -Remember: The goal isn't to prevent all incidents (which is impossible), but to detect them quickly, respond effectively, communicate clearly, and learn continuously. diff --git a/docs/skills/engineering-team/index.md b/docs/skills/engineering-team/index.md index eb5c3f61..aa9a4072 100644 --- a/docs/skills/engineering-team/index.md +++ b/docs/skills/engineering-team/index.md @@ -63,7 +63,7 @@ description: "51 engineering - core skills — engineering agent skill and Claud --- - 23 production-ready engineering skills organized into core engineering, AI/ML/Data, and specialized tools. + 32 production-ready engineering skills organized into core engineering, security, AI/ML/Data, and specialized tools. - **[Epic Design Skill](epic-design.md)** @@ -165,7 +165,7 @@ description: "51 engineering - core skills — engineering agent skill and Claud --- - Prompt engineering patterns, LLM evaluation frameworks, and agentic system design. + Eval-driven prompt engineering, RAG quality measurement, and agent workflow validation. Everything here is model-agno... - **[Senior QA Engineer](senior-qa.md)** @@ -179,11 +179,11 @@ description: "51 engineering - core skills — engineering agent skill and Claud Complete toolkit for Security Operations including vulnerability management, compliance verification, secure coding p... -- **[Senior Security Engineer](senior-security.md)** +- **[Senior Security Engineer — Threat Modeling + Security Router](senior-security.md)** --- - Security engineering tools for threat modeling, vulnerability analysis, secure architecture design, and penetration t... + This skill does exactly one job itself — STRIDE/DREAD threat modeling (plus a quick secret scan) — and routes every o... - **[Stripe Integration Expert](stripe-integration-expert.md)** diff --git a/docs/skills/engineering-team/ms365-tenant-manager.md b/docs/skills/engineering-team/ms365-tenant-manager.md index ad6526be..b41c666c 100644 --- a/docs/skills/engineering-team/ms365-tenant-manager.md +++ b/docs/skills/engineering-team/ms365-tenant-manager.md @@ -54,6 +54,28 @@ $policy = @{ New-MgIdentityConditionalAccessPolicy -BodyParameter $policy ``` +### Bundled Python Generators + +Three stdlib tools generate the PowerShell artifacts deterministically — prefer them over hand-writing scripts for bulk/repeatable work. Sample input: `sample_input.json`; expected shape: `expected_output.json`. + +```bash +# Tenant setup: checklist + DNS records + license plan (JSON), or the full setup script +python3 scripts/tenant_setup.py --config sample_input.json --format json -o tenant_plan.json +python3 scripts/tenant_setup.py --config sample_input.json --format powershell -o tenant_setup.ps1 + +# User lifecycle: validate first, then generate creation/offboarding scripts +python3 scripts/user_management.py --domain acme.com --action validate --users users.json +python3 scripts/user_management.py --domain acme.com --action create --users users.json -o create_users.ps1 +python3 scripts/user_management.py --domain acme.com --action offboard --user-email jane@acme.com -o offboard.ps1 + +# Admin scripts: CA policy / security audit / bulk licensing +python3 scripts/powershell_generator.py --tenant-domain acme.com --task conditional-access --policy-config policy.json -o ca_policy.ps1 +python3 scripts/powershell_generator.py --tenant-domain acme.com --task security-audit -o audit.ps1 +python3 scripts/powershell_generator.py --tenant-domain acme.com --task bulk-license --users-csv users.csv --license-sku ENTERPRISEPACK -o licenses.ps1 +``` + +**Gate:** for user creation, run `--action validate` first and require every entry to report `"is_valid": true` before generating the creation script. Review every generated `.ps1` against the workflows below before running it in the tenant. + --- ## Workflows @@ -62,6 +84,8 @@ New-MgIdentityConditionalAccessPolicy -BodyParameter $policy **Step 1: Generate Setup Checklist** +Run `python3 scripts/tenant_setup.py --config tenant.json --format json` and work through `setup_checklist` phase by phase; `dns_records` feeds Step 2 and `license_recommendations` feeds the licensing workflow. + Confirm prerequisites before provisioning: - Global Admin account created and secured with MFA - Custom domain purchased and accessible for DNS edits diff --git a/docs/skills/engineering-team/playwright-pro-generate.md b/docs/skills/engineering-team/playwright-pro-generate.md index 4605cc68..294df5f6 100644 --- a/docs/skills/engineering-team/playwright-pro-generate.md +++ b/docs/skills/engineering-team/playwright-pro-generate.md @@ -53,7 +53,7 @@ Check `templates/` in this plugin for matching patterns: | If testing... | Load template from | |---|---| -| Login/auth flow | `templates/auth/login.md` | +| Login/auth flow | [`auth/login.md`](https://github.com/alirezarezvani/claude-skills/tree/main/engineering-team/playwright-pro/skills/pw/templates/auth/login.md) | | CRUD operations | `templates/crud/` | | Checkout/payment | `templates/checkout/` | | Search/filter UI | `templates/search/` | diff --git a/docs/skills/engineering-team/security-pen-testing.md b/docs/skills/engineering-team/security-pen-testing.md index 1b48c9e3..325cc489 100644 --- a/docs/skills/engineering-team/security-pen-testing.md +++ b/docs/skills/engineering-team/security-pen-testing.md @@ -313,5 +313,5 @@ Automated security checks on every PR: secret scanning (TruffleHog), dependency |-------|-------------| | [senior-secops](https://github.com/alirezarezvani/claude-skills/tree/main/engineering-team/skills/senior-secops/SKILL.md) | Defensive security operations — monitoring, incident response, SIEM configuration | | [senior-security](https://github.com/alirezarezvani/claude-skills/tree/main/engineering-team/skills/senior-security/SKILL.md) | Security policy and governance — frameworks, risk registers, compliance | -| [dependency-auditor](https://github.com/alirezarezvani/claude-skills/tree/main/engineering-team/engineering/dependency-auditor/SKILL.md) | Deep supply chain security — SBOMs, license compliance, transitive risk | +| [dependency-auditor](https://github.com/alirezarezvani/claude-skills/tree/main/engineering/skills/dependency-auditor/SKILL.md) | Deep supply chain security — SBOMs, license compliance, transitive risk | | [code-reviewer](https://github.com/alirezarezvani/claude-skills/tree/main/engineering-team/skills/code-reviewer/SKILL.md) | Code review practices — includes security review checklist | diff --git a/docs/skills/engineering-team/self-improving-agent-extract.md b/docs/skills/engineering-team/self-improving-agent-extract.md index 8c1c6f17..4b54c42e 100644 --- a/docs/skills/engineering-team/self-improving-agent-extract.md +++ b/docs/skills/engineering-team/self-improving-agent-extract.md @@ -1,6 +1,6 @@ --- title: "/si:extract — Create Skills from Patterns — Agent Skill & Codex Plugin" -description: "Turn a proven pattern or debugging solution into a standalone reusable skill with SKILL.md, reference docs, and examples. Agent skill for Claude Code, Codex CLI, Gemini CLI, OpenClaw." +description: "Turn a proven pattern or debugging solution into a standalone reusable skill with SKILL.md, reference docs, and examples. Use when the user runs. Agent skill for Claude Code, Codex CLI, Gemini CLI, OpenClaw." --- # /si:extract — Create Skills from Patterns diff --git a/docs/skills/engineering-team/self-improving-agent-promote.md b/docs/skills/engineering-team/self-improving-agent-promote.md index 0720544e..da092ee1 100644 --- a/docs/skills/engineering-team/self-improving-agent-promote.md +++ b/docs/skills/engineering-team/self-improving-agent-promote.md @@ -1,6 +1,6 @@ --- title: "/si:promote — Graduate Learnings to Rules — Agent Skill & Codex Plugin" -description: "Graduate a proven pattern from auto-memory (MEMORY.md) to CLAUDE.md or .claude/rules/ for permanent enforcement. Agent skill for Claude Code, Codex CLI, Gemini CLI, OpenClaw." +description: "Graduate a proven pattern from auto-memory (MEMORY.md) to CLAUDE.md or .claude/rules/ for permanent enforcement. Use when the user runs /si:promote. Agent skill for Claude Code, Codex CLI, Gemini CLI, OpenClaw." --- # /si:promote — Graduate Learnings to Rules diff --git a/docs/skills/engineering-team/self-improving-agent-review.md b/docs/skills/engineering-team/self-improving-agent-review.md index 85500ed8..63533644 100644 --- a/docs/skills/engineering-team/self-improving-agent-review.md +++ b/docs/skills/engineering-team/self-improving-agent-review.md @@ -1,6 +1,6 @@ --- title: "/si:review — Analyze Auto-Memory — Agent Skill & Codex Plugin" -description: "Analyze auto-memory for promotion candidates, stale entries, consolidation opportunities, and health metrics. Agent skill for Claude Code, Codex CLI, Gemini CLI, OpenClaw." +description: "Analyze auto-memory for promotion candidates, stale entries, consolidation opportunities, and health metrics. Use when the user runs /si:review or. Agent skill for Claude Code, Codex CLI, Gemini CLI, OpenClaw." --- # /si:review — Analyze Auto-Memory diff --git a/docs/skills/engineering-team/self-improving-agent-status.md b/docs/skills/engineering-team/self-improving-agent-status.md index 4fe6d9fe..7e09e783 100644 --- a/docs/skills/engineering-team/self-improving-agent-status.md +++ b/docs/skills/engineering-team/self-improving-agent-status.md @@ -1,6 +1,6 @@ --- title: "/si:status — Memory Health Dashboard — Agent Skill & Codex Plugin" -description: "Memory health dashboard showing line counts, topic files, capacity, stale entries, and recommendations. Agent skill for Claude Code, Codex CLI, Gemini CLI, OpenClaw." +description: "Memory health dashboard showing line counts, topic files, capacity, stale entries, and recommendations. Use when the user runs /si:status or asks how. Agent skill for Claude Code, Codex CLI, Gemini CLI, OpenClaw." --- # /si:status — Memory Health Dashboard diff --git a/docs/skills/engineering-team/self-improving-agent.md b/docs/skills/engineering-team/self-improving-agent.md index 62130d73..4101222a 100644 --- a/docs/skills/engineering-team/self-improving-agent.md +++ b/docs/skills/engineering-team/self-improving-agent.md @@ -170,4 +170,4 @@ Monitors command output for errors. When detected, appends a structured entry to - [Claude Code Memory Docs](https://code.claude.com/docs/en/memory) - [pskoett/self-improving-agent](https://clawhub.ai/pskoett/self-improving-agent) — inspiration -- [playwright-pro](https://github.com/alirezarezvani/claude-skills/tree/main/engineering-team/self-improving-agent/skills/playwright-pro) — sister plugin in this repo +- [playwright-pro](https://github.com/alirezarezvani/claude-skills/tree/main/engineering-team/playwright-pro/) — sister plugin in this repo diff --git a/docs/skills/engineering-team/senior-backend.md b/docs/skills/engineering-team/senior-backend.md index d41ad1c0..681cb2a6 100644 --- a/docs/skills/engineering-team/senior-backend.md +++ b/docs/skills/engineering-team/senior-backend.md @@ -261,7 +261,7 @@ import { z } from 'zod'; const CreateUserSchema = z.object({ email: z.string().email().max(255), - name: "zstringmin1max100" + name: z.string().min(1).max(100), age: z.number().int().positive().optional() }); diff --git a/docs/skills/engineering-team/senior-data-scientist.md b/docs/skills/engineering-team/senior-data-scientist.md index b6ba62b0..fd8d6d8b 100644 --- a/docs/skills/engineering-team/senior-data-scientist.md +++ b/docs/skills/engineering-team/senior-data-scientist.md @@ -219,16 +219,10 @@ def diff_in_diff(df, outcome, treatment_col, post_col, controls=None): python -m pytest tests/ -v --cov=src/ python -m black src/ && python -m pylint src/ -# Training & evaluation -python scripts/train.py --config prod.yaml -python scripts/evaluate.py --model best.pth - -# Deployment -docker build -t service:v1 . -kubectl apply -f k8s/ -helm upgrade service ./charts/ - -# Monitoring & health -kubectl logs -f deployment/service -python scripts/health_check.py +# Bundled pipeline scaffolds (stdlib runners — extend the process() body with project logic) +python3 scripts/experiment_designer.py --input experiment_spec.json --output experiment_design.json +python3 scripts/feature_engineering_pipeline.py --input raw_features.json --output features.json +python3 scripts/model_evaluation_suite.py --input model_predictions.json --output evaluation.json +# Each prints a JSON run report ({status, processed_items, start/end_time}); any status other +# than "completed" means the stage failed — fix before moving to the next pipeline stage. ``` diff --git a/docs/skills/engineering-team/senior-devops.md b/docs/skills/engineering-team/senior-devops.md index b24b1a03..ec40d375 100644 --- a/docs/skills/engineering-team/senior-devops.md +++ b/docs/skills/engineering-team/senior-devops.md @@ -31,8 +31,8 @@ python scripts/pipeline_generator.py ./app --platform=github --stages=build,test # Script 2: Terraform Scaffolder — generates and validates IaC modules for AWS/GCP/Azure python scripts/terraform_scaffolder.py ./infra --provider=aws --module=ecs-service --verbose -# Script 3: Deployment Manager — orchestrates container deployments with rollback support -python3 scripts/deployment_manager.py ./deploy --verbose --json +# Script 3: Deployment Manager — generates deployment manifests + runbooks with rollback support +python3 scripts/deployment_manager.py deploy --env=staging --image=app:1.2.3 --strategy=blue-green --verbose --json ``` ## Core Capabilities @@ -158,7 +158,7 @@ python scripts/terraform_scaffolder.py <target-path> --provider=aws|gcp|azure -- ### 3. Deployment Manager -Orchestrates deployments with blue/green or rolling strategies, health-check gates, and automatic rollback on failure. +Generates Kubernetes deployment manifests and ordered kubectl runbooks for blue/green or rolling strategies, with health-check gates before traffic switches and rollback runbooks. The tool writes manifests and prints the commands — it never applies them to a cluster itself, so every change gets a human review. **Example — Kubernetes blue/green deployment (blue-slot specific elements):** ```yaml diff --git a/docs/skills/engineering-team/senior-frontend.md b/docs/skills/engineering-team/senior-frontend.md index f9c03d90..9f2312e6 100644 --- a/docs/skills/engineering-team/senior-frontend.md +++ b/docs/skills/engineering-team/senior-frontend.md @@ -433,7 +433,7 @@ test('dialog is accessible', async () => { // next.config.js const nextConfig = { images: { - remotePatterns: [{ hostname: "cdnexamplecom" }], + remotePatterns: [{ protocol: 'https', hostname: 'cdn.example.com' }], formats: ['image/avif', 'image/webp'], }, experimental: { diff --git a/docs/skills/engineering-team/senior-fullstack.md b/docs/skills/engineering-team/senior-fullstack.md index 14da9aa8..aab2fe7f 100644 --- a/docs/skills/engineering-team/senior-fullstack.md +++ b/docs/skills/engineering-team/senior-fullstack.md @@ -229,7 +229,7 @@ npm install cp .env.example .env.local # 5. Run quality check -python ../scripts/code_quality_analyzer.py . +python scripts/code_quality_analyzer.py . # 6. Start development npm run dev diff --git a/docs/skills/engineering-team/senior-prompt-engineer.md b/docs/skills/engineering-team/senior-prompt-engineer.md index 686250a3..b93529db 100644 --- a/docs/skills/engineering-team/senior-prompt-engineer.md +++ b/docs/skills/engineering-team/senior-prompt-engineer.md @@ -1,6 +1,6 @@ --- title: "Senior Prompt Engineer — Agent Skill & Codex Plugin" -description: "This skill should be used when the user asks to 'optimize prompts', 'design prompt templates', 'evaluate LLM outputs', 'build agentic systems'. Agent skill for Claude Code, Codex CLI, Gemini CLI, OpenClaw." +description: "Use when the user asks to optimize prompts, design prompt templates, evaluate LLM outputs with an eval set, measure RAG retrieval quality, validate. Agent skill for Claude Code, Codex CLI, Gemini CLI, OpenClaw." --- # Senior Prompt Engineer @@ -16,351 +16,135 @@ description: "This skill should be used when the user asks to 'optimize prompts' </div> -Prompt engineering patterns, LLM evaluation frameworks, and agentic system design. +Eval-driven prompt engineering, RAG quality measurement, and agent workflow validation. Everything here is **model-agnostic by design**: techniques are framed by what they do, not by which model generation they were observed on, and the tools never hardcode model IDs or pricing — you supply your provider's current rates when you want dollar figures. -## Table of Contents +## Operating Rules -- [Quick Start](#quick-start) -- [Tools Overview](#tools-overview) - - [Prompt Optimizer](#1-prompt-optimizer) - - [RAG Evaluator](#2-rag-evaluator) - - [Agent Orchestrator](#3-agent-orchestrator) -- [Prompt Engineering Workflows](#prompt-engineering-workflows) - - [Prompt Optimization Workflow](#prompt-optimization-workflow) - - [Few-Shot Example Design](#few-shot-example-design-workflow) - - [Structured Output Design](#structured-output-design-workflow) -- [Reference Documentation](#reference-documentation) -- [Common Patterns Quick Reference](#common-patterns-quick-reference) +1. **Never change a prompt without a baseline.** Capture metrics first (`--analyze --output baseline.json`), then compare every iteration against it. +2. **Eval set before optimization.** 10–20 representative cases with expected outputs minimum. If the user has no eval set, build one with them before touching the prompt — optimizing against vibes is the #1 failure mode. +3. **Prefer platform features over prompt hacks.** If the provider offers native structured outputs / JSON schema enforcement, tool-use APIs, or prompt caching, use those instead of "respond ONLY with JSON" incantations. Prompt-level format enforcement is the fallback, not the default. +4. **Current-generation models need less scaffolding.** Don't add chain-of-thought boilerplate, role framing, or few-shot examples reflexively — frontier models often do worse with redundant scaffolding. Add each element only when the eval set shows it helps. +5. **Cost numbers are always user-supplied.** Look up the provider's current per-Mtok pricing and pass it via `--price-per-mtok` (never trust a cached price table — including any you remember). ---- +## Tools (exact CLIs, all stdlib) -## Quick Start +### 1. Prompt Optimizer — `scripts/prompt_optimizer.py` + +Static analysis: token estimate, clarity/structure scores (0–100), ambiguity + redundancy detection, few-shot example extraction. ```bash -# Analyze and optimize a prompt file -python scripts/prompt_optimizer.py prompts/my_prompt.txt --analyze +# Full analysis (human-readable report) +python3 scripts/prompt_optimizer.py prompt.txt --analyze -# Evaluate RAG retrieval quality -python scripts/rag_evaluator.py --contexts contexts.json --questions questions.json +# Save machine-readable baseline for later comparison +python3 scripts/prompt_optimizer.py prompt.txt --analyze --json --output baseline.json -# Visualize agent workflow from definition -python scripts/agent_orchestrator.py agent_config.yaml --visualize +# Token estimate; cost only if you supply your provider's current rate +python3 scripts/prompt_optimizer.py prompt.txt --tokens --model claude --price-per-mtok 3.00 + +# Whitespace/redundancy-trimmed version +python3 scripts/prompt_optimizer.py prompt.txt --optimize --output optimized.txt + +# Extract Input/Output few-shot pairs to JSON +python3 scripts/prompt_optimizer.py prompt.txt --extract-examples --output examples.json + +# Compare a revision against the saved baseline +python3 scripts/prompt_optimizer.py optimized.txt --analyze --compare baseline.json ``` ---- +`--model` accepts any string; only the tokenizer family is inferred (names containing "claude" → 3.5 chars/token, otherwise 4.0). Exit 0 on success, 1 on missing file. -## Tools Overview +### 2. RAG Evaluator — `scripts/rag_evaluator.py` -### 1. Prompt Optimizer +Measures retrieval and grounding quality from two JSON files (formats printed in `--help`). -Analyzes prompts for token efficiency, clarity, and structure. Generates optimized versions. - -**Input:** Prompt text file or string -**Output:** Analysis report with optimization suggestions - -**Usage:** ```bash -# Analyze a prompt file -python scripts/prompt_optimizer.py prompt.txt --analyze - -# Output: -# Token count: 847 -# Estimated cost: $0.0025 (GPT-4) -# Clarity score: 72/100 -# Issues found: -# - Ambiguous instruction at line 3 -# - Missing output format specification -# - Redundant context (lines 12-15 repeat lines 5-8) -# Suggestions: -# 1. Add explicit output format: "Respond in JSON with keys: ..." -# 2. Remove redundant context to save 89 tokens -# 3. Clarify "analyze" -> "list the top 3 issues with severity ratings" - -# Generate optimized version -python scripts/prompt_optimizer.py prompt.txt --optimize --output optimized.txt - -# Count tokens for cost estimation -python scripts/prompt_optimizer.py prompt.txt --tokens --model gpt-4 - -# Extract and manage few-shot examples -python scripts/prompt_optimizer.py prompt.txt --extract-examples --output examples.json +python3 scripts/rag_evaluator.py --contexts retrieved.json --questions eval_set.json +python3 scripts/rag_evaluator.py --contexts ctx.json --questions q.json --k 10 --json +python3 scripts/rag_evaluator.py --contexts ctx.json --questions q.json --output report.json --verbose +python3 scripts/rag_evaluator.py --contexts ctx.json --questions q.json --compare baseline_report.json ``` ---- +Reports context relevance, precision@k, coverage, answer faithfulness, groundedness. Treat relevance < 0.80 as a retrieval problem (chunking/embedding/filtering), not a prompt problem — fix retrieval before rewriting the generation prompt. -### 2. RAG Evaluator +### 3. Agent Orchestrator — `scripts/agent_orchestrator.py` -Evaluates Retrieval-Augmented Generation quality by measuring context relevance and answer faithfulness. +Validates agent configs (YAML/JSON): tool wiring, missing required config, loop risk, token estimates. -**Input:** Retrieved contexts (JSON) and questions/answers -**Output:** Evaluation metrics and quality report - -**Usage:** ```bash -# Evaluate retrieval quality -python scripts/rag_evaluator.py --contexts retrieved.json --questions eval_set.json - -# Output: -# === RAG Evaluation Report === -# Questions evaluated: 50 -# -# Retrieval Metrics: -# Context Relevance: 0.78 (target: >0.80) -# Retrieval Precision@5: 0.72 -# Coverage: 0.85 -# -# Generation Metrics: -# Answer Faithfulness: 0.91 -# Groundedness: 0.88 -# -# Issues Found: -# - 8 questions had no relevant context in top-5 -# - 3 answers contained information not in context -# -# Recommendations: -# 1. Improve chunking strategy for technical documents -# 2. Add metadata filtering for date-sensitive queries - -# Evaluate with custom metrics -python scripts/rag_evaluator.py --contexts retrieved.json --questions eval_set.json \ - --metrics relevance,faithfulness,coverage - -# Export detailed results -python scripts/rag_evaluator.py --contexts retrieved.json --questions eval_set.json \ - --output report.json --verbose +python3 scripts/agent_orchestrator.py agent.yaml --validate +python3 scripts/agent_orchestrator.py agent.yaml --visualize --format mermaid +python3 scripts/agent_orchestrator.py agent.yaml --estimate-cost --runs 100 \ + --input-price-per-mtok 3.00 --output-price-per-mtok 15.00 ``` ---- +Without the two price flags, `--estimate-cost` reports token estimates only. The `model:` field in the config is informational — any model name is accepted. -### 3. Agent Orchestrator +## Workflows -Parses agent definitions and visualizes execution flows. Validates tool configurations. +### Prompt Optimization (eval-gated) -**Input:** Agent configuration (YAML/JSON) -**Output:** Workflow visualization, validation report +1. **Baseline:** `python3 scripts/prompt_optimizer.py current_prompt.txt --analyze --json --output baseline.json` +2. **Diagnose** from the report: ambiguous verbs ("analyze", "handle"), redundant blocks, missing output contract, token waste. +3. **Apply one change at a time**, in this order of leverage: + | Symptom | Fix | + |---------|-----| + | Malformed/unparseable output | Native structured outputs / JSON schema if the API supports it; explicit schema-in-prompt otherwise | + | Inconsistent answers across runs | Tighten instructions + add 2–3 contrastive examples (one near-miss showing what NOT to do) | + | Misses edge cases | Enumerate the edge cases explicitly; add a "when uncertain, do X" rule | + | Token bloat on repeated calls | Move stable prefix (system rules, examples) first so prompt caching applies; trim redundancy | + | Wrong reasoning on hard cases | Ask for stepwise reasoning *in a scratch field the consumer ignores*, or use the provider's extended-thinking mode | +4. **Re-analyze and compare:** `python3 scripts/prompt_optimizer.py revised.txt --analyze --compare baseline.json` +5. **Eval gate (must pass before shipping):** run the revised prompt over the eval set, write per-case pass/fail to `eval_results.json`, then assert: + ```bash + python3 scripts/prompt_optimizer.py revised.txt --analyze --json --output revised.json \ + && python3 -c " + import json, sys + r = json.load(open('revised.json')); b = json.load(open('baseline.json')) + ok = r['clarity_score'] >= b['clarity_score'] and r['token_count'] <= b['token_count'] * 1.10 + sys.exit(0 if ok else 1)" + echo "gate exit=$?" # 0 = ship; 1 = regression, iterate again + ``` + Pair this structural gate with your task-level eval: the revision must not lose any previously-passing eval case (no-regression rule). -**Usage:** -```bash -# Validate agent configuration -python scripts/agent_orchestrator.py agent.yaml --validate +### Few-Shot Example Design -# Output: -# === Agent Validation Report === -# Agent: research_assistant -# Pattern: ReAct -# -# Tools (4 registered): -# [OK] web_search - API key configured -# [OK] calculator - No config needed -# [WARN] file_reader - Missing allowed_paths -# [OK] summarizer - Prompt template valid -# -# Flow Analysis: -# Max depth: 5 iterations -# Estimated tokens/run: 2,400-4,800 -# Potential infinite loop: No -# -# Recommendations: -# 1. Add allowed_paths to file_reader for security -# 2. Consider adding early exit condition for simple queries +1. Define the task contract first (input shape, output shape, edge-case policy). +2. Start with **zero examples** and measure — current models often need none. Add examples only for failure clusters the eval reveals. +3. When adding: 3–5 max, ordered simple → edge → negative (what NOT to extract), formatted identically to the real output contract. +4. Validate consistency: `python3 scripts/prompt_optimizer.py prompt_with_examples.txt --extract-examples --output examples.json` and inspect that every extracted pair parses against your schema. +5. Re-run the eval set; if a case passes only because it resembles an example, add a held-out variant to the eval set. -# Visualize agent workflow (ASCII) -python scripts/agent_orchestrator.py agent.yaml --visualize +### Structured Output Design -# Output: -# ┌─────────────────────────────────────────┐ -# │ research_assistant │ -# │ (ReAct Pattern) │ -# └─────────────────┬───────────────────────┘ -# │ -# ┌────────▼────────┐ -# │ User Query │ -# └────────┬────────┘ -# │ -# ┌────────▼────────┐ -# │ Think │◄──────┐ -# └────────┬────────┘ │ -# │ │ -# ┌────────▼────────┐ │ -# │ Select Tool │ │ -# └────────┬────────┘ │ -# │ │ -# ┌─────────────┼─────────────┐ │ -# ▼ ▼ ▼ │ -# [web_search] [calculator] [file_reader] -# │ │ │ │ -# └─────────────┼─────────────┘ │ -# │ │ -# ┌────────▼────────┐ │ -# │ Observe │───────┘ -# └────────┬────────┘ -# │ -# ┌────────▼────────┐ -# │ Final Answer │ -# └─────────────────┘ +1. Write the JSON Schema first (types, enums, required, maxLength). +2. **Prefer API-native enforcement**: structured-outputs / response-schema / tool-call parameters guarantee shape; prompt text cannot. +3. Fallback (API without schema support): include the schema rendered as field-by-field rules + one valid example, and instruct "output only the JSON object". +4. Gate: pipe 10 eval outputs through a schema validator (`python3 -c "import json,sys; [json.loads(l) for l in sys.stdin]"` at minimum); 10/10 must parse, else return to step 2. -# Export workflow as Mermaid diagram -python scripts/agent_orchestrator.py agent.yaml --visualize --format mermaid -``` +### RAG Tuning Loop ---- +1. Build `questions.json` (id, question, reference answer) and capture current retrievals to `contexts.json`. +2. `python3 scripts/rag_evaluator.py --contexts contexts.json --questions questions.json --output rag_baseline.json` +3. Fix the **lowest metric first**: relevance → chunking/embeddings/metadata filters; faithfulness → grounding instructions + "answer only from context" + citation requirement; coverage → retrieval k / query expansion. +4. Gate: `python3 scripts/rag_evaluator.py --contexts new_contexts.json --questions questions.json --compare rag_baseline.json` — every metric must be ≥ baseline; any regression blocks the change. -## Prompt Engineering Workflows +### Agent Config Review -### Prompt Optimization Workflow +1. `python3 scripts/agent_orchestrator.py agent.yaml --validate` — must exit with VALIDATION PASSED; fix every error and warning (missing tool config, unbounded iterations, loop risk). +2. Check context discipline: each tool description ≤ 1–2 sentences, tool count minimal for the job, stable system prompt placed first (cache-friendly), iteration cap + early-exit condition present. +3. Budget: `--estimate-cost --runs N` with your current prices; if cost/run exceeds budget, cut tools or context before downgrading the model. -Use when improving an existing prompt's performance or reducing token costs. - -**Step 1: Baseline current prompt** -```bash -python scripts/prompt_optimizer.py current_prompt.txt --analyze --output baseline.json -``` - -**Step 2: Identify issues** -Review the analysis report for: -- Token waste (redundant instructions, verbose examples) -- Ambiguous instructions (unclear output format, vague verbs) -- Missing constraints (no length limits, no format specification) - -**Step 3: Apply optimization patterns** -| Issue | Pattern to Apply | -|-------|------------------| -| Ambiguous output | Add explicit format specification | -| Too verbose | Extract to few-shot examples | -| Inconsistent results | Add role/persona framing | -| Missing edge cases | Add constraint boundaries | - -**Step 4: Generate optimized version** -```bash -python scripts/prompt_optimizer.py current_prompt.txt --optimize --output optimized.txt -``` - -**Step 5: Compare results** -```bash -python scripts/prompt_optimizer.py optimized.txt --analyze --compare baseline.json -# Shows: token reduction, clarity improvement, issues resolved -``` - -**Step 6: Validate with test cases** -Run both prompts against your evaluation set and compare outputs. - ---- - -### Few-Shot Example Design Workflow - -Use when creating examples for in-context learning. - -**Step 1: Define the task clearly** -``` -Task: Extract product entities from customer reviews -Input: Review text -Output: JSON with {product_name, sentiment, features_mentioned} -``` - -**Step 2: Select diverse examples (3-5 recommended)** -| Example Type | Purpose | -|--------------|---------| -| Simple case | Shows basic pattern | -| Edge case | Handles ambiguity | -| Complex case | Multiple entities | -| Negative case | What NOT to extract | - -**Step 3: Format consistently** -``` -Example 1: -Input: "Love my new iPhone 15, the camera is amazing!" -Output: {"product_name": "iPhone 15", "sentiment": "positive", "features_mentioned": ["camera"]} - -Example 2: -Input: "The laptop was okay but battery life is terrible." -Output: {"product_name": "laptop", "sentiment": "mixed", "features_mentioned": ["battery life"]} -``` - -**Step 4: Validate example quality** -```bash -python scripts/prompt_optimizer.py prompt_with_examples.txt --validate-examples -# Checks: consistency, coverage, format alignment -``` - -**Step 5: Test with held-out cases** -Ensure model generalizes beyond your examples. - ---- - -### Structured Output Design Workflow - -Use when you need reliable JSON/XML/structured responses. - -**Step 1: Define schema** -```json -{ - "type": "object", - "properties": { - "summary": {"type": "string", "maxLength": 200}, - "sentiment": {"enum": ["positive", "negative", "neutral"]}, - "confidence": {"type": "number", "minimum": 0, "maximum": 1} - }, - "required": ["summary", "sentiment"] -} -``` - -**Step 2: Include schema in prompt** -``` -Respond with JSON matching this schema: -- summary (string, max 200 chars): Brief summary of the content -- sentiment (enum): One of "positive", "negative", "neutral" -- confidence (number 0-1): Your confidence in the sentiment -``` - -**Step 3: Add format enforcement** -``` -IMPORTANT: Respond ONLY with valid JSON. No markdown, no explanation. -Start your response with { and end with } -``` - -**Step 4: Validate outputs** -```bash -python scripts/prompt_optimizer.py structured_prompt.txt --validate-schema schema.json -``` - ---- - -## Reference Documentation +## References | File | Contains | Load when user asks about | |------|----------|---------------------------| -| `references/prompt_engineering_patterns.md` | 10 prompt patterns with input/output examples | "which pattern?", "few-shot", "chain-of-thought", "role prompting" | -| `references/llm_evaluation_frameworks.md` | Evaluation metrics, scoring methods, A/B testing | "how to evaluate?", "measure quality", "compare prompts" | +| `references/prompt_engineering_patterns.md` | 10 prompt patterns with input/output examples | "which pattern?", few-shot design, decomposition, meta-prompting | +| `references/llm_evaluation_frameworks.md` | Eval metrics, scoring methods, A/B testing | "how to evaluate?", "measure quality", "compare prompts" | | `references/agentic_system_design.md` | Agent architectures (ReAct, Plan-Execute, Tool Use) | "build agent", "tool calling", "multi-agent" | ---- +## Related Skills -## Common Patterns Quick Reference - -| Pattern | When to Use | Example | -|---------|-------------|---------| -| **Zero-shot** | Simple, well-defined tasks | "Classify this email as spam or not spam" | -| **Few-shot** | Complex tasks, consistent format needed | Provide 3-5 examples before the task | -| **Chain-of-Thought** | Reasoning, math, multi-step logic | "Think step by step..." | -| **Role Prompting** | Expertise needed, specific perspective | "You are an expert tax accountant..." | -| **Structured Output** | Need parseable JSON/XML | Include schema + format enforcement | - ---- - -## Common Commands - -```bash -# Prompt Analysis -python scripts/prompt_optimizer.py prompt.txt --analyze # Full analysis -python scripts/prompt_optimizer.py prompt.txt --tokens # Token count only -python scripts/prompt_optimizer.py prompt.txt --optimize # Generate optimized version - -# RAG Evaluation -python scripts/rag_evaluator.py --contexts ctx.json --questions q.json # Evaluate -python scripts/rag_evaluator.py --contexts ctx.json --compare baseline # Compare to baseline - -# Agent Development -python scripts/agent_orchestrator.py agent.yaml --validate # Validate config -python scripts/agent_orchestrator.py agent.yaml --visualize # Show workflow -python scripts/agent_orchestrator.py agent.yaml --estimate-cost # Token estimation -``` +- `engineering-team/skills/senior-ml-engineer` — model deployment and serving (this skill stops at the prompt/eval layer) +- `engineering/rag-architect` — RAG system architecture (this skill measures RAG quality; that one designs the pipeline) +- `engineering/agent-designer` — full agent system design (this skill validates configs; that one designs the architecture) diff --git a/docs/skills/engineering-team/senior-qa.md b/docs/skills/engineering-team/senior-qa.md index 6aea99fa..3698b602 100644 --- a/docs/skills/engineering-team/senior-qa.md +++ b/docs/skills/engineering-team/senior-qa.md @@ -131,7 +131,7 @@ import { Button } from '../src/components/Button'; describe('Button', () => { it('renders with label', () => { render(<Button>Click me</Button>); - expect(screen.getByRole('button', { name: "click-mei-tobeinthedocument" + expect(screen.getByRole('button', { name: /click me/i })).toBeInTheDocument(); }); it('calls onClick when clicked', () => { @@ -252,7 +252,7 @@ npx playwright show-report ```typescript // Preferred (accessible) -screen.getByRole('button', { name: "submiti" +screen.getByRole('button', { name: /submit/i }) screen.getByLabelText(/email/i) screen.getByPlaceholderText(/search/i) diff --git a/docs/skills/engineering-team/senior-security.md b/docs/skills/engineering-team/senior-security.md index 3643bdf0..6c2e3db9 100644 --- a/docs/skills/engineering-team/senior-security.md +++ b/docs/skills/engineering-team/senior-security.md @@ -1,9 +1,9 @@ --- -title: "Senior Security Engineer — Agent Skill & Codex Plugin" -description: "Security engineering toolkit for threat modeling, vulnerability analysis, secure architecture, and penetration testing. Includes STRIDE analysis. Agent skill for Claude Code, Codex CLI, Gemini CLI, OpenClaw." +title: "Senior Security Engineer — Threat Modeling + Security Router — Agent Skill & Codex Plugin" +description: "Use when the user asks for STRIDE threat modeling, DREAD risk scoring, data-flow-diagram threat analysis, or a quick secret scan — or when a security. Agent skill for Claude Code, Codex CLI, Gemini CLI, OpenClaw." --- -# Senior Security Engineer +# Senior Security Engineer — Threat Modeling + Security Router <div class="page-meta" markdown> <span class="meta-badge">:material-code-braces: Engineering - Core</span> @@ -16,59 +16,42 @@ description: "Security engineering toolkit for threat modeling, vulnerability an </div> -Security engineering tools for threat modeling, vulnerability analysis, secure architecture design, and penetration testing. +This skill does exactly one job itself — **STRIDE/DREAD threat modeling** (plus a quick secret scan) — and routes every other security request to the specialist skill that owns that lane. Do not duplicate sibling content here; route instead. ---- +## Routing Table (read this first) -## Table of Contents +| The user wants... | Route to | Why that skill owns it | +|---|---|---| +| Vulnerability assessment, pen-test methodology, OWASP Top 10 testing | [`skills/security-pen-testing`](https://github.com/alirezarezvani/claude-skills/tree/main/engineering-team/skills/security-pen-testing) | Ships `vulnerability_scanner.py` + `dependency_auditor.py` with exit-code contracts | +| Incident triage, SEV classification, forensics, containment | [`skills/incident-response`](https://github.com/alirezarezvani/claude-skills/tree/main/engineering-team/skills/incident-response) | SEV1–SEV4 taxonomy, NIST SP 800-61 phases, `incident_triage.py` | +| Production outage command (non-security incidents) | [`skills/incident-commander`](https://github.com/alirezarezvani/claude-skills/tree/main/engineering-team/skills/incident-commander) | Severity classifier + timeline + postmortem tools | +| Security monitoring, CVE triage SLAs, compliance checks (SOC 2 etc.), security headers | [`skills/senior-secops`](https://github.com/alirezarezvani/claude-skills/tree/main/engineering-team/skills/senior-secops) | `security_scanner.py` + `compliance_checker.py`, CVE SLA table | +| Hostile/adversarial code review | [`skills/adversarial-reviewer`](https://github.com/alirezarezvani/claude-skills/tree/main/engineering-team/skills/adversarial-reviewer) | 3-persona review with BLOCK/CONCERNS/CLEAN verdict | +| Secure code review as part of general review | [`skills/code-reviewer`](https://github.com/alirezarezvani/claude-skills/tree/main/engineering-team/skills/code-reviewer) | Language dispatch + regression fixtures | +| Cloud IAM escalation paths, S3 exposure, security groups | [`skills/cloud-security`](https://github.com/alirezarezvani/claude-skills/tree/main/engineering-team/skills/cloud-security) | `cloud_posture_check.py` with per-check exit codes | +| Threat hunting, IOC sweeps, anomaly detection | [`skills/threat-detection`](https://github.com/alirezarezvani/claude-skills/tree/main/engineering-team/skills/threat-detection) | z-score anomaly + IOC staleness tooling | +| Red-team engagement planning, ATT&CK kill chains | [`skills/red-team`](https://github.com/alirezarezvani/claude-skills/tree/main/engineering-team/skills/red-team) | `engagement_planner.py` with authorization gate | +| LLM/AI attack surface (prompt injection, poisoning) | [`skills/ai-security`](https://github.com/alirezarezvani/claude-skills/tree/main/engineering-team/skills/ai-security) | ATLAS-mapped `ai_threat_scanner.py` | -- [Threat Modeling Workflow](#threat-modeling-workflow) -- [Security Architecture Workflow](#security-architecture-workflow) -- [Vulnerability Assessment Workflow](#vulnerability-assessment-workflow) -- [Secure Code Review Workflow](#secure-code-review-workflow) -- [Incident Response Workflow](#incident-response-workflow) -- [Security Tools Reference](#security-tools-reference) -- [Tools and References](#tools-and-references) +If the request spans lanes (e.g., "secure this new architecture"), do the threat model here first — its output (prioritized threats + mitigations) tells you which siblings to load next. Never bulk-load multiple security skills speculatively. ---- +## What This Skill Owns: STRIDE Threat Modeling -## Threat Modeling Workflow +### Workflow -Identify and analyze security threats using STRIDE methodology. - -### Workflow: Conduct Threat Model - -1. Define system scope and boundaries: - - Identify assets to protect - - Map trust boundaries - - Document data flows -2. Create data flow diagram: - - External entities (users, services) - - Processes (application components) - - Data stores (databases, caches) - - Data flows (APIs, network connections) -3. Apply STRIDE to each DFD element (see [STRIDE per Element Matrix](#stride-per-element-matrix) below) -4. Score risks using DREAD: - - Damage potential (1-10) - - Reproducibility (1-10) - - Exploitability (1-10) - - Affected users (1-10) - - Discoverability (1-10) -5. Prioritize threats by risk score -6. Define mitigations for each threat -7. Document in threat model report -8. **Validation:** All DFD elements analyzed; STRIDE applied; threats scored; mitigations mapped - -### STRIDE Threat Categories - -| Category | Security Property | Mitigation Focus | -|----------|-------------------|------------------| -| Spoofing | Authentication | MFA, certificates, strong auth | -| Tampering | Integrity | Signing, checksums, validation | -| Repudiation | Non-repudiation | Audit logs, digital signatures | -| Information Disclosure | Confidentiality | Encryption, access controls | -| Denial of Service | Availability | Rate limiting, redundancy | -| Elevation of Privilege | Authorization | RBAC, least privilege | +1. **Scope:** assets to protect, trust boundaries, data flows (external entities, processes, data stores, flows). +2. **Generate the threat model** per component: + ```bash + python3 scripts/threat_modeler.py --component "User Authentication" --assets "credentials,sessions" --json --output threats.json + ``` + Output: per-threat STRIDE category, DREAD score (Damage, Reproducibility, Exploitability, Affected users, Discoverability — each 1–10), and suggested mitigations. Repeat per DFD element; `--interactive` walks scoping questions; `--list-threats` shows the threat database. +3. **Consume the output:** sort `threats.json` by DREAD score descending; everything ≥ 7 average needs a named mitigation owner before the design ships. Map each mitigation to the responsible sibling lane (e.g., IAM threats → `cloud-security`, injection threats → `code-reviewer`). +4. **Quick secret sweep** while you have the codebase open: + ```bash + python3 scripts/secret_scanner.py /path/to/project --format json --severity high + ``` + 20+ patterns (AWS keys, GitHub tokens, private keys, generic credentials). Any critical/high finding blocks merge until rotated and moved to a secret manager. +5. **Verification gate:** every DFD element has ≥ 1 STRIDE row considered, every threat with DREAD ≥ 7 has an owner + mitigation, and the secret scan exits with zero high/critical findings. Re-run both tools after mitigations land — that re-run is the done signal, not the document. ### STRIDE per Element Matrix @@ -79,364 +62,14 @@ Identify and analyze security threats using STRIDE methodology. | Data Store | | X | X | X | X | | | Data Flow | | X | | X | X | | -See: [references/threat-modeling-guide.md](https://github.com/alirezarezvani/claude-skills/tree/main/engineering-team/skills/senior-security/references/threat-modeling-guide.md) +(S=Spoofing→authn, T=Tampering→integrity, R=Repudiation→audit logs, I=Info Disclosure→encryption/access control, D=DoS→rate limiting/redundancy, E=Elevation→least privilege.) ---- - -## Security Architecture Workflow - -Design secure systems using defense-in-depth principles. - -### Workflow: Design Secure Architecture - -1. Define security requirements: - - Compliance requirements (GDPR, HIPAA, PCI-DSS) - - Data classification (public, internal, confidential, restricted) - - Threat model inputs -2. Apply defense-in-depth layers: - - Perimeter: WAF, DDoS protection, rate limiting - - Network: Segmentation, IDS/IPS, mTLS - - Host: Patching, EDR, hardening - - Application: Input validation, authentication, secure coding - - Data: Encryption at rest and in transit -3. Implement Zero Trust principles: - - Verify explicitly (every request) - - Least privilege access (JIT/JEA) - - Assume breach (segment, monitor) -4. Configure authentication and authorization: - - Identity provider selection - - MFA requirements - - RBAC/ABAC model -5. Design encryption strategy: - - Key management approach - - Algorithm selection - - Certificate lifecycle -6. Plan security monitoring: - - Log aggregation - - SIEM integration - - Alerting rules -7. Document architecture decisions -8. **Validation:** Defense-in-depth layers defined; Zero Trust applied; encryption strategy documented; monitoring planned - -### Defense-in-Depth Layers - -``` -Layer 1: PERIMETER - WAF, DDoS mitigation, DNS filtering, rate limiting - -Layer 2: NETWORK - Segmentation, IDS/IPS, network monitoring, VPN, mTLS - -Layer 3: HOST - Endpoint protection, OS hardening, patching, logging - -Layer 4: APPLICATION - Input validation, authentication, secure coding, SAST - -Layer 5: DATA - Encryption at rest/transit, access controls, DLP, backup -``` - -### Authentication Pattern Selection - -| Use Case | Recommended Pattern | -|----------|---------------------| -| Web application | OAuth 2.0 + PKCE with OIDC | -| API authentication | JWT with short expiration + refresh tokens | -| Service-to-service | mTLS with certificate rotation | -| CLI/Automation | API keys with IP allowlisting | -| High security | FIDO2/WebAuthn hardware keys | - -See: [references/security-architecture-patterns.md](https://github.com/alirezarezvani/claude-skills/tree/main/engineering-team/skills/senior-security/references/security-architecture-patterns.md) - ---- - -## Vulnerability Assessment Workflow - -Identify and remediate security vulnerabilities in applications. - -### Workflow: Conduct Vulnerability Assessment - -1. Define assessment scope: - - In-scope systems and applications - - Testing methodology (black box, gray box, white box) - - Rules of engagement -2. Gather information: - - Technology stack inventory - - Architecture documentation - - Previous vulnerability reports -3. Perform automated scanning: - - SAST (static analysis) - - DAST (dynamic analysis) - - Dependency scanning - - Secret detection -4. Conduct manual testing: - - Business logic flaws - - Authentication bypass - - Authorization issues - - Injection vulnerabilities -5. Classify findings by severity: - - Critical: Immediate exploitation risk - - High: Significant impact, easier to exploit - - Medium: Moderate impact or difficulty - - Low: Minor impact -6. Develop remediation plan: - - Prioritize by risk - - Assign owners - - Set deadlines -7. Verify fixes and document -8. **Validation:** Scope defined; automated and manual testing complete; findings classified; remediation tracked - -For OWASP Top 10 vulnerability descriptions and testing guidance, refer to [owasp.org/Top10](https://owasp.org/Top10). - -### Vulnerability Severity Matrix - -| Impact \ Exploitability | Easy | Moderate | Difficult | -|-------------------------|------|----------|-----------| -| Critical | Critical | Critical | High | -| High | Critical | High | Medium | -| Medium | High | Medium | Low | -| Low | Medium | Low | Low | - ---- - -## Secure Code Review Workflow - -Review code for security vulnerabilities before deployment. - -### Workflow: Conduct Security Code Review - -1. Establish review scope: - - Changed files and functions - - Security-sensitive areas (auth, crypto, input handling) - - Third-party integrations -2. Run automated analysis: - - SAST tools (Semgrep, CodeQL, Bandit) - - Secret scanning - - Dependency vulnerability check -3. Review authentication code: - - Password handling (hashing, storage) - - Session management - - Token validation -4. Review authorization code: - - Access control checks - - RBAC implementation - - Privilege boundaries -5. Review data handling: - - Input validation - - Output encoding - - SQL query construction - - File path handling -6. Review cryptographic code: - - Algorithm selection - - Key management - - Random number generation -7. Document findings with severity -8. **Validation:** Automated scans passed; auth/authz reviewed; data handling checked; crypto verified; findings documented - -### Security Code Review Checklist - -| Category | Check | Risk | -|----------|-------|------| -| Input Validation | All user input validated and sanitized | Injection | -| Output Encoding | Context-appropriate encoding applied | XSS | -| Authentication | Passwords hashed with Argon2/bcrypt | Credential theft | -| Session | Secure cookie flags set (HttpOnly, Secure, SameSite) | Session hijacking | -| Authorization | Server-side permission checks on all endpoints | Privilege escalation | -| SQL | Parameterized queries used exclusively | SQL injection | -| File Access | Path traversal sequences rejected | Path traversal | -| Secrets | No hardcoded credentials or keys | Information disclosure | -| Dependencies | Known vulnerable packages updated | Supply chain | -| Logging | Sensitive data not logged | Information disclosure | - -### Secure vs Insecure Patterns - -| Pattern | Issue | Secure Alternative | -|---------|-------|-------------------| -| SQL string formatting | SQL injection | Use parameterized queries with placeholders | -| Shell command building | Command injection | Use subprocess with argument lists, no shell | -| Path concatenation | Path traversal | Validate and canonicalize paths | -| MD5/SHA1 for passwords | Weak hashing | Use Argon2id or bcrypt | -| Math.random for tokens | Predictable values | Use crypto.getRandomValues | - -### Inline Code Examples - -**SQL Injection — insecure vs. secure (Python):** - -```python -# ❌ Insecure: string formatting allows SQL injection -query = f"SELECT * FROM users WHERE username = '{username}'" -cursor.execute(query) - -# ✅ Secure: parameterized query — user input never interpreted as SQL -query = "SELECT * FROM users WHERE username = %s" -cursor.execute(query, (username,)) -``` - -**Password Hashing with Argon2id (Python):** - -```python -from argon2 import PasswordHasher - -ph = PasswordHasher() # uses secure defaults (time_cost, memory_cost) - -# On registration -hashed = ph.hash(plain_password) - -# On login — raises argon2.exceptions.VerifyMismatchError on failure -ph.verify(hashed, plain_password) -``` - -**Secret Scanning — core pattern matching (Python):** - -```python -import re, pathlib - -SECRET_PATTERNS = { - "aws_access_key": re.compile(r"AKIA[0-9A-Z]{16}"), - "github_token": re.compile(r"ghp_[A-Za-z0-9]{36}"), - "private_key": re.compile(r"-----BEGIN (RSA |EC )?PRIVATE KEY-----"), - "generic_secret": re.compile(r'(?i)(password|secret|api_key)\s*=\s*["\']?\S{8,}'), -} - -def scan_file(path: pathlib.Path) -> list[dict]: - findings = [] - for lineno, line in enumerate(path.read_text(errors="replace").splitlines(), 1): - for name, pattern in SECRET_PATTERNS.items(): - if pattern.search(line): - findings.append({"file": str(path), "line": lineno, "type": name}) - return findings -``` - ---- - -## Incident Response Workflow - -Respond to and contain security incidents. - -### Workflow: Handle Security Incident - -1. Identify and triage: - - Validate incident is genuine - - Assess initial scope and severity - - Activate incident response team -2. Contain the threat: - - Isolate affected systems - - Block malicious IPs/accounts - - Disable compromised credentials -3. Eradicate root cause: - - Remove malware/backdoors - - Patch vulnerabilities - - Update configurations -4. Recover operations: - - Restore from clean backups - - Verify system integrity - - Monitor for recurrence -5. Conduct post-mortem: - - Timeline reconstruction - - Root cause analysis - - Lessons learned -6. Implement improvements: - - Update detection rules - - Enhance controls - - Update runbooks -7. Document and report -8. **Validation:** Threat contained; root cause eliminated; systems recovered; post-mortem complete; improvements implemented - -### Incident Severity Levels - -| Level | Response Time | Escalation | -|-------|---------------|------------| -| P1 - Critical (active breach/exfiltration) | Immediate | CISO, Legal, Executive | -| P2 - High (confirmed, contained) | 1 hour | Security Lead, IT Director | -| P3 - Medium (potential, under investigation) | 4 hours | Security Team | -| P4 - Low (suspicious, low impact) | 24 hours | On-call engineer | - -### Incident Response Checklist - -| Phase | Actions | -|-------|---------| -| Identification | Validate alert, assess scope, determine severity | -| Containment | Isolate systems, preserve evidence, block access | -| Eradication | Remove threat, patch vulnerabilities, reset credentials | -| Recovery | Restore services, verify integrity, increase monitoring | -| Lessons Learned | Document timeline, identify gaps, update procedures | - ---- - -## Security Tools Reference - -### Recommended Security Tools - -| Category | Tools | -|----------|-------| -| SAST | Semgrep, CodeQL, Bandit (Python), ESLint security plugins | -| DAST | OWASP ZAP, Burp Suite, Nikto | -| Dependency Scanning | Snyk, Dependabot, npm audit, pip-audit | -| Secret Detection | GitLeaks, TruffleHog, detect-secrets | -| Container Security | Trivy, Clair, Anchore | -| Infrastructure | Checkov, tfsec, ScoutSuite | -| Network | Wireshark, Nmap, Masscan | -| Penetration | Metasploit, sqlmap, Burp Suite Pro | - -### Cryptographic Algorithm Selection - -| Use Case | Algorithm | Key Size | -|----------|-----------|----------| -| Symmetric encryption | AES-256-GCM | 256 bits | -| Password hashing | Argon2id | N/A (use defaults) | -| Message authentication | HMAC-SHA256 | 256 bits | -| Digital signatures | Ed25519 | 256 bits | -| Key exchange | X25519 | 256 bits | -| TLS | TLS 1.3 | N/A | - -See: [references/cryptography-implementation.md](https://github.com/alirezarezvani/claude-skills/tree/main/engineering-team/skills/senior-security/references/cryptography-implementation.md) - ---- - -## Tools and References - -### Scripts - -| Script | Purpose | -|--------|---------| -| [threat_modeler.py](https://github.com/alirezarezvani/claude-skills/tree/main/engineering-team/skills/senior-security/scripts/threat_modeler.py) | STRIDE threat analysis with DREAD risk scoring; JSON and text output; interactive guided mode | -| [secret_scanner.py](https://github.com/alirezarezvani/claude-skills/tree/main/engineering-team/skills/senior-security/scripts/secret_scanner.py) | Detect hardcoded secrets and credentials across 20+ patterns; CI/CD integration ready | - -For usage, see the inline code examples in [Secure Code Review Workflow](#inline-code-examples) and the script source files directly. - -### References +## References (load on demand) | Document | Content | |----------|---------| -| [security-architecture-patterns.md](https://github.com/alirezarezvani/claude-skills/tree/main/engineering-team/skills/senior-security/references/security-architecture-patterns.md) | Zero Trust, defense-in-depth, authentication patterns, API security | -| [threat-modeling-guide.md](https://github.com/alirezarezvani/claude-skills/tree/main/engineering-team/skills/senior-security/references/threat-modeling-guide.md) | STRIDE methodology, attack trees, DREAD scoring, DFD creation | -| [cryptography-implementation.md](https://github.com/alirezarezvani/claude-skills/tree/main/engineering-team/skills/senior-security/references/cryptography-implementation.md) | AES-GCM, RSA, Ed25519, password hashing, key management | +| [references/threat-modeling-guide.md](https://github.com/alirezarezvani/claude-skills/tree/main/engineering-team/skills/senior-security/references/threat-modeling-guide.md) | STRIDE methodology, attack trees, DREAD scoring, DFD creation | +| [references/security-architecture-patterns.md](https://github.com/alirezarezvani/claude-skills/tree/main/engineering-team/skills/senior-security/references/security-architecture-patterns.md) | Zero Trust, defense-in-depth, authentication patterns, API security | +| [references/cryptography-implementation.md](https://github.com/alirezarezvani/claude-skills/tree/main/engineering-team/skills/senior-security/references/cryptography-implementation.md) | AES-GCM, Ed25519, password hashing (Argon2id), key management | ---- - -## Security Standards Reference - -### Security Headers Checklist - -| Header | Recommended Value | -|--------|-------------------| -| Content-Security-Policy | default-src self; script-src self | -| X-Frame-Options | DENY | -| X-Content-Type-Options | nosniff | -| Strict-Transport-Security | max-age=31536000; includeSubDomains | -| Referrer-Policy | strict-origin-when-cross-origin | -| Permissions-Policy | geolocation=(), microphone=(), camera=() | - -For compliance framework requirements (OWASP ASVS, CIS Benchmarks, NIST CSF, PCI-DSS, HIPAA, SOC 2), refer to the respective official documentation. - ---- - -## Related Skills - -| Skill | Integration Point | -|-------|-------------------| -| [senior-devops](https://github.com/alirezarezvani/claude-skills/tree/main/engineering-team/skills/senior-devops) | CI/CD security, infrastructure hardening | -| [senior-secops](https://github.com/alirezarezvani/claude-skills/tree/main/engineering-team/skills/senior-secops) | Security monitoring, incident response | -| [senior-backend](https://github.com/alirezarezvani/claude-skills/tree/main/engineering-team/skills/senior-backend) | Secure API development | -| [senior-architect](https://github.com/alirezarezvani/claude-skills/tree/main/engineering-team/skills/senior-architect) | Security architecture decisions | +The architecture and crypto references are kept because no sibling ships them; for *operating* those controls (scanning, compliance, monitoring) still route to `senior-secops`. diff --git a/docs/skills/engineering/agent-designer.md b/docs/skills/engineering/agent-designer.md index 01613d86..77411dc6 100644 --- a/docs/skills/engineering/agent-designer.md +++ b/docs/skills/engineering/agent-designer.md @@ -1,9 +1,9 @@ --- -title: "Agent Designer - Multi-Agent System Architecture — Agent Skill for Codex & OpenClaw" -description: "Use when the user asks to design multi-agent systems, create agent architectures, define agent communication patterns, or build autonomous agent. Agent skill for Claude Code, Codex CLI, Gemini CLI, OpenClaw." +title: "Agent Designer — Multi-Agent System Architecture — Agent Skill for Codex & OpenClaw" +description: "Use when the user asks to design a multi-agent system, pick an orchestration pattern (supervisor/swarm/pipeline), generate tool schemas for agents." --- -# Agent Designer - Multi-Agent System Architecture +# Agent Designer — Multi-Agent System Architecture <div class="page-meta" markdown> <span class="meta-badge">:material-rocket-launch: Engineering - POWERFUL</span> @@ -16,275 +16,72 @@ description: "Use when the user asks to design multi-agent systems, create agent </div> -**Tier:** POWERFUL -**Category:** Engineering -**Tags:** AI agents, architecture, system design, orchestration, multi-agent systems +Design, schema-generate, and evaluate multi-agent systems with three deterministic tools. The scripts are the workflow — do not freehand an architecture when the planner can score one from requirements. -## Overview +## When to use -Agent Designer is a comprehensive toolkit for designing, architecting, and evaluating multi-agent systems. It provides structured approaches to agent architecture patterns, tool design principles, communication strategies, and performance evaluation frameworks for building robust, scalable AI agent systems. +- Designing a new multi-agent system from requirements (pattern choice, roles, comms) +- Generating provider-ready tool schemas (Anthropic + OpenAI formats) from plain tool descriptions +- Evaluating execution logs: success rate, latency distribution, cost, bottlenecks -## Core Capabilities +**When NOT to use:** Claude Code Workflow-tool automations → `workflow-builder`; single-agent workflow scaffolds → `agent-workflow-designer`; multi-agent fan-out at runtime → `agenthub`. -### 1. Agent Architecture Patterns +## Pattern decision table -#### Single Agent Pattern -- **Use Case:** Simple, focused tasks with clear boundaries -- **Pros:** Minimal complexity, easy debugging, predictable behavior -- **Cons:** Limited scalability, single point of failure -- **Implementation:** Direct user-agent interaction with comprehensive tool access +| Choose | When | Watch out for | +|---|---|---| +| Single agent | One bounded task, < ~5 tools | Don't add agents you don't need | +| Supervisor | Central decomposition, specialists report back | Supervisor becomes the bottleneck | +| Pipeline | Strictly sequential stages with handoffs | Rigid order; slowest stage gates throughput | +| Hierarchical | Multiple org layers, > ~8 agents | Communication overhead per level | +| Swarm | Parallel peers, fault tolerance over predictability | Hard to debug; needs consensus rules | -#### Supervisor Pattern -- **Use Case:** Hierarchical task decomposition with centralized control -- **Architecture:** One supervisor agent coordinating multiple specialist agents -- **Pros:** Clear command structure, centralized decision making -- **Cons:** Supervisor bottleneck, complex coordination logic -- **Implementation:** Supervisor receives tasks, delegates to specialists, aggregates results +The planner applies this scoring deterministically — run it rather than picking by feel. -#### Swarm Pattern -- **Use Case:** Distributed problem solving with peer-to-peer collaboration -- **Architecture:** Multiple autonomous agents with shared objectives -- **Pros:** High parallelism, fault tolerance, emergent intelligence -- **Cons:** Complex coordination, potential conflicts, harder to predict -- **Implementation:** Agent discovery, consensus mechanisms, distributed task allocation +## Workflow -#### Hierarchical Pattern -- **Use Case:** Complex systems with multiple organizational layers -- **Architecture:** Tree structure with managers and workers at different levels -- **Pros:** Natural organizational mapping, clear responsibilities -- **Cons:** Communication overhead, potential bottlenecks at each level -- **Implementation:** Multi-level delegation with feedback loops +All paths relative to this skill folder. Each step's JSON output is the next step's design input. -#### Pipeline Pattern -- **Use Case:** Sequential processing with specialized stages -- **Architecture:** Agents arranged in processing pipeline -- **Pros:** Clear data flow, specialized optimization per stage -- **Cons:** Sequential bottlenecks, rigid processing order -- **Implementation:** Message queues between stages, state handoffs +### 1. Design the architecture -### 2. Agent Role Definition +Write a requirements JSON (copy `assets/sample_system_requirements.json` — keys: `goal`, `tasks[]`, `constraints{max_response_time, budget_per_task, concurrent_tasks}`, `team_size`): -#### Role Specification Framework -- **Identity:** Name, purpose statement, core competencies -- **Responsibilities:** Primary tasks, decision boundaries, success criteria -- **Capabilities:** Required tools, knowledge domains, processing limits -- **Interfaces:** Input/output formats, communication protocols -- **Constraints:** Security boundaries, resource limits, operational guidelines +```bash +python3 agent_planner.py requirements.json --format json -o arch +``` -#### Common Agent Archetypes +Emits `arch.json` with `architecture_design` (pattern, agents, communication links), `mermaid_diagram`, and `implementation_roadmap`. Read `architecture_design.pattern` and the per-agent role list; present the mermaid diagram to the user. -**Coordinator Agent** -- Orchestrates multi-agent workflows -- Makes high-level decisions and resource allocation -- Monitors system health and performance -- Handles escalations and conflict resolution +### 2. Generate tool schemas -**Specialist Agent** -- Deep expertise in specific domain (code, data, research) -- Optimized tools and knowledge for specialized tasks -- High-quality output within narrow scope -- Clear handoff protocols for out-of-scope requests +Describe each agent's tools in plain JSON (copy `assets/sample_tool_descriptions.json`), then: -**Interface Agent** -- Handles external interactions (users, APIs, systems) -- Protocol translation and format conversion -- Authentication and authorization management -- User experience optimization +```bash +python3 tool_schema_generator.py tool_descriptions.json --validate -o tools +``` -**Monitor Agent** -- System health monitoring and alerting -- Performance metrics collection and analysis -- Anomaly detection and reporting -- Compliance and audit trail maintenance +Emits `tools.json` (`tool_schemas`, `validation_summary`) plus provider-specific `tools_anthropic.json` / `tools_openai.json`. **Gate: every tool must print `✓ Valid`.** Fix any invalid schema before proceeding — never hand an agent an unvalidated schema. -### 3. Tool Design Principles +### 3. Evaluate execution logs -#### Schema Design -- **Input Validation:** Strong typing, required vs optional parameters -- **Output Consistency:** Standardized response formats, error handling -- **Documentation:** Clear descriptions, usage examples, edge cases -- **Versioning:** Backward compatibility, migration paths +Once the system runs (or against `assets/sample_execution_logs.json` for a dry run): -#### Error Handling Patterns -- **Graceful Degradation:** Partial functionality when dependencies fail -- **Retry Logic:** Exponential backoff, circuit breakers, max attempts -- **Error Propagation:** Structured error responses, error classification -- **Recovery Strategies:** Fallback methods, alternative approaches +```bash +python3 agent_evaluator.py execution_logs.json --detailed -o eval +``` -#### Idempotency Requirements -- **Safe Operations:** Read operations with no side effects -- **Idempotent Writes:** Same operation can be safely repeated -- **State Management:** Version tracking, conflict resolution -- **Atomicity:** All-or-nothing operation completion +Emits `eval.json` with `summary`, `agent_metrics`, `bottleneck_analysis`, `error_analysis`, `cost_breakdown`, `sla_compliance`, and `optimization_recommendations`, plus split files (`eval_errors.json`, `eval_recommendations.json`). -### 4. Communication Patterns +### 4. Verification loop -#### Message Passing -- **Asynchronous Messaging:** Decoupled agents, message queues -- **Message Format:** Structured payloads with metadata -- **Delivery Guarantees:** At-least-once, exactly-once semantics -- **Routing:** Direct messaging, publish-subscribe, broadcast +The design is not done until: -#### Shared State -- **State Stores:** Centralized data repositories -- **Consistency Models:** Strong, eventual, weak consistency -- **Access Patterns:** Read-heavy, write-heavy, mixed workloads -- **Conflict Resolution:** Last-writer-wins, merge strategies +1. `tool_schema_generator.py --validate` reports 0 invalid schemas. +2. `agent_evaluator.py` on a pilot run reports **0 critical issues** (the tool prints `CRITICAL: N critical issues` when found). If N > 0, apply the top item in `eval_recommendations.json`, re-run the pilot, and re-evaluate. +3. Compare your outputs against `expected_outputs/` to confirm the schema shape you're consuming hasn't drifted. -#### Event-Driven Architecture -- **Event Sourcing:** Immutable event logs, state reconstruction -- **Event Types:** Domain events, system events, integration events -- **Event Processing:** Real-time, batch, stream processing -- **Event Schema:** Versioned event formats, backward compatibility +## References -### 5. Guardrails and Safety - -#### Input Validation -- **Schema Enforcement:** Required fields, type checking, format validation -- **Content Filtering:** Harmful content detection, PII scrubbing -- **Rate Limiting:** Request throttling, resource quotas -- **Authentication:** Identity verification, authorization checks - -#### Output Filtering -- **Content Moderation:** Harmful content removal, quality checks -- **Consistency Validation:** Logic checks, constraint verification -- **Formatting:** Standardized output formats, clean presentation -- **Audit Logging:** Decision trails, compliance records - -#### Human-in-the-Loop -- **Approval Workflows:** Critical decision checkpoints -- **Escalation Triggers:** Confidence thresholds, risk assessment -- **Override Mechanisms:** Human judgment precedence -- **Feedback Loops:** Human corrections improve system behavior - -### 6. Evaluation Frameworks - -#### Task Completion Metrics -- **Success Rate:** Percentage of tasks completed successfully -- **Partial Completion:** Progress measurement for complex tasks -- **Task Classification:** Success criteria by task type -- **Failure Analysis:** Root cause identification and categorization - -#### Quality Assessment -- **Output Quality:** Accuracy, relevance, completeness measures -- **Consistency:** Response variability across similar inputs -- **Coherence:** Logical flow and internal consistency -- **User Satisfaction:** Feedback scores, usage patterns - -#### Cost Analysis -- **Token Usage:** Input/output token consumption per task -- **API Costs:** External service usage and charges -- **Compute Resources:** CPU, memory, storage utilization -- **Time-to-Value:** Cost per successful task completion - -#### Latency Distribution -- **Response Time:** End-to-end task completion time -- **Processing Stages:** Bottleneck identification per stage -- **Queue Times:** Wait times in processing pipelines -- **Resource Contention:** Impact of concurrent operations - -### 7. Orchestration Strategies - -#### Centralized Orchestration -- **Workflow Engine:** Central coordinator manages all agents -- **State Management:** Centralized workflow state tracking -- **Decision Logic:** Complex routing and branching rules -- **Monitoring:** Comprehensive visibility into all operations - -#### Decentralized Orchestration -- **Peer-to-Peer:** Agents coordinate directly with each other -- **Service Discovery:** Dynamic agent registration and lookup -- **Consensus Protocols:** Distributed decision making -- **Fault Tolerance:** No single point of failure - -#### Hybrid Approaches -- **Domain Boundaries:** Centralized within domains, federated across -- **Hierarchical Coordination:** Multiple orchestration levels -- **Context-Dependent:** Strategy selection based on task type -- **Load Balancing:** Distribute coordination responsibility - -### 8. Memory Patterns - -#### Short-Term Memory -- **Context Windows:** Working memory for current tasks -- **Session State:** Temporary data for ongoing interactions -- **Cache Management:** Performance optimization strategies -- **Memory Pressure:** Handling capacity constraints - -#### Long-Term Memory -- **Persistent Storage:** Durable data across sessions -- **Knowledge Base:** Accumulated domain knowledge -- **Experience Replay:** Learning from past interactions -- **Memory Consolidation:** Transferring from short to long-term - -#### Shared Memory -- **Collaborative Knowledge:** Shared learning across agents -- **Synchronization:** Consistency maintenance strategies -- **Access Control:** Permission-based memory access -- **Memory Partitioning:** Isolation between agent groups - -### 9. Scaling Considerations - -#### Horizontal Scaling -- **Agent Replication:** Multiple instances of same agent type -- **Load Distribution:** Request routing across agent instances -- **Resource Pooling:** Shared compute and storage resources -- **Geographic Distribution:** Multi-region deployments - -#### Vertical Scaling -- **Capability Enhancement:** More powerful individual agents -- **Tool Expansion:** Broader tool access per agent -- **Context Expansion:** Larger working memory capacity -- **Processing Power:** Higher throughput per agent - -#### Performance Optimization -- **Caching Strategies:** Response caching, tool result caching -- **Parallel Processing:** Concurrent task execution -- **Resource Optimization:** Efficient resource utilization -- **Bottleneck Elimination:** Systematic performance tuning - -### 10. Failure Handling - -#### Retry Mechanisms -- **Exponential Backoff:** Increasing delays between retries -- **Jitter:** Random delay variation to prevent thundering herd -- **Maximum Attempts:** Bounded retry behavior -- **Retry Conditions:** Transient vs permanent failure classification - -#### Fallback Strategies -- **Graceful Degradation:** Reduced functionality when systems fail -- **Alternative Approaches:** Different methods for same goals -- **Default Responses:** Safe fallback behaviors -- **User Communication:** Clear failure messaging - -#### Circuit Breakers -- **Failure Detection:** Monitoring failure rates and response times -- **State Management:** Open, closed, half-open circuit states -- **Recovery Testing:** Gradual return to normal operation -- **Cascading Failure Prevention:** Protecting upstream systems - -## Implementation Guidelines - -### Architecture Decision Process -1. **Requirements Analysis:** Understand system goals, constraints, scale -2. **Pattern Selection:** Choose appropriate architecture pattern -3. **Agent Design:** Define roles, responsibilities, interfaces -4. **Tool Architecture:** Design tool schemas and error handling -5. **Communication Design:** Select message patterns and protocols -6. **Safety Implementation:** Build guardrails and validation -7. **Evaluation Planning:** Define success metrics and monitoring -8. **Deployment Strategy:** Plan scaling and failure handling - -### Quality Assurance -- **Testing Strategy:** Unit, integration, and system testing approaches -- **Monitoring:** Real-time system health and performance tracking -- **Documentation:** Architecture documentation and runbooks -- **Security Review:** Threat modeling and security assessments - -### Continuous Improvement -- **Performance Monitoring:** Ongoing system performance analysis -- **User Feedback:** Incorporating user experience improvements -- **A/B Testing:** Controlled experiments for system improvements -- **Knowledge Base Updates:** Continuous learning and adaptation - -This skill provides the foundation for designing robust, scalable multi-agent systems that can handle complex tasks while maintaining safety, reliability, and performance at scale. \ No newline at end of file +- `references/agent_architecture_patterns.md` — pattern trade-offs in depth +- `references/tool_design_best_practices.md` — schema, idempotency, error-handling rules +- `references/evaluation_methodology.md` — metric definitions the evaluator implements diff --git a/docs/skills/engineering/agenthub-board.md b/docs/skills/engineering/agenthub-board.md index e658af6d..bb7257e4 100644 --- a/docs/skills/engineering/agenthub-board.md +++ b/docs/skills/engineering/agenthub-board.md @@ -1,6 +1,6 @@ --- title: "/hub:board — Message Board — Agent Skill for Codex & OpenClaw" -description: "Read, write, and browse the AgentHub message board for agent coordination. Agent skill for Claude Code, Codex CLI, Gemini CLI, OpenClaw." +description: "Read, write, and browse the AgentHub message board for agent coordination. Use when the user runs /hub:board or asks to post, read, or inspect. Agent skill for Claude Code, Codex CLI, Gemini CLI, OpenClaw." --- # /hub:board — Message Board diff --git a/docs/skills/engineering/agenthub-eval.md b/docs/skills/engineering/agenthub-eval.md index 82294866..3fffc4c6 100644 --- a/docs/skills/engineering/agenthub-eval.md +++ b/docs/skills/engineering/agenthub-eval.md @@ -1,6 +1,6 @@ --- title: "/hub:eval — Evaluate Agent Results — Agent Skill for Codex & OpenClaw" -description: "Evaluate and rank agent results by metric or LLM judge for an AgentHub session. Agent skill for Claude Code, Codex CLI, Gemini CLI, OpenClaw." +description: "Evaluate and rank agent results by metric or LLM judge for an AgentHub session. Use when the user runs /hub:eval or asks to score, compare, or pick a. Agent skill for Claude Code, Codex CLI, Gemini CLI, OpenClaw." --- # /hub:eval — Evaluate Agent Results diff --git a/docs/skills/engineering/agenthub-init.md b/docs/skills/engineering/agenthub-init.md index fb8d4ed9..7a02052a 100644 --- a/docs/skills/engineering/agenthub-init.md +++ b/docs/skills/engineering/agenthub-init.md @@ -1,6 +1,6 @@ --- title: "/hub:init — Create New Session — Agent Skill for Codex & OpenClaw" -description: "Create a new AgentHub collaboration session with task, agent count, and evaluation criteria. Agent skill for Claude Code, Codex CLI, Gemini CLI, OpenClaw." +description: "Create a new AgentHub collaboration session with task, agent count, and evaluation criteria. Use when the user runs /hub:init or asks to start a. Agent skill for Claude Code, Codex CLI, Gemini CLI, OpenClaw." --- # /hub:init — Create New Session diff --git a/docs/skills/engineering/agenthub-merge.md b/docs/skills/engineering/agenthub-merge.md index 73f49a0f..5185f1e9 100644 --- a/docs/skills/engineering/agenthub-merge.md +++ b/docs/skills/engineering/agenthub-merge.md @@ -1,6 +1,6 @@ --- title: "/hub:merge — Merge Winner — Agent Skill for Codex & OpenClaw" -description: "Merge the winning agent's branch into base, archive losers, and clean up worktrees. Agent skill for Claude Code, Codex CLI, Gemini CLI, OpenClaw." +description: "Merge the winning agent's branch into base, archive losers, and clean up worktrees. Use when the user runs /hub:merge or asks to land the winning. Agent skill for Claude Code, Codex CLI, Gemini CLI, OpenClaw." --- # /hub:merge — Merge Winner diff --git a/docs/skills/engineering/agenthub-run.md b/docs/skills/engineering/agenthub-run.md index c9263029..24ae4faf 100644 --- a/docs/skills/engineering/agenthub-run.md +++ b/docs/skills/engineering/agenthub-run.md @@ -1,6 +1,6 @@ --- title: "/hub:run — One-Shot Lifecycle — Agent Skill for Codex & OpenClaw" -description: "One-shot lifecycle command that chains init → baseline → spawn → eval → merge in a single invocation. Agent skill for Claude Code, Codex CLI, Gemini CLI, OpenClaw." +description: "One-shot lifecycle command that chains init → baseline → spawn → eval → merge in a single invocation. Use when the user runs /hub:run or asks to. Agent skill for Claude Code, Codex CLI, Gemini CLI, OpenClaw." --- # /hub:run — One-Shot Lifecycle @@ -76,7 +76,7 @@ If no `--eval` was provided, skip this step. Run `/hub:spawn` with the session ID. -If `--template` was provided, use the template dispatch prompt from `references/agent-templates.md` instead of the default dispatch prompt. Pass the eval command, metric, and baseline to the template variables. +If `--template` was provided, use the template dispatch prompt from [`references/agent-templates.md`](https://github.com/alirezarezvani/claude-skills/tree/main/engineering/agenthub/skills/agenthub/references/agent-templates.md) instead of the default dispatch prompt. Pass the eval command, metric, and baseline to the template variables. Launch all agents in a single message with multiple Agent tool calls (true parallelism). diff --git a/docs/skills/engineering/agenthub-spawn.md b/docs/skills/engineering/agenthub-spawn.md index 468e6e6e..94e95fd6 100644 --- a/docs/skills/engineering/agenthub-spawn.md +++ b/docs/skills/engineering/agenthub-spawn.md @@ -1,6 +1,6 @@ --- title: "/hub:spawn — Launch Parallel Agents — Agent Skill for Codex & OpenClaw" -description: "Launch N parallel subagents in isolated git worktrees to compete on the session task. Agent skill for Claude Code, Codex CLI, Gemini CLI, OpenClaw." +description: "Launch N parallel subagents in isolated git worktrees to compete on the session task. Use when the user runs /hub:spawn or asks to start the. Agent skill for Claude Code, Codex CLI, Gemini CLI, OpenClaw." --- # /hub:spawn — Launch Parallel Agents @@ -29,7 +29,7 @@ Spawn N subagents that work on the same task in parallel, each in an isolated gi ## Templates -When `--template <name>` is provided, use the dispatch prompt from `references/agent-templates.md` instead of the default prompt below. Available templates: +When `--template <name>` is provided, use the dispatch prompt from [`references/agent-templates.md`](https://github.com/alirezarezvani/claude-skills/tree/main/engineering/agenthub/skills/agenthub/references/agent-templates.md) instead of the default prompt below. Available templates: | Template | Pattern | Use Case | |----------|---------|----------| diff --git a/docs/skills/engineering/agenthub-status.md b/docs/skills/engineering/agenthub-status.md index 03a1b428..228edfa6 100644 --- a/docs/skills/engineering/agenthub-status.md +++ b/docs/skills/engineering/agenthub-status.md @@ -1,6 +1,6 @@ --- title: "/hub:status — Session Status — Agent Skill for Codex & OpenClaw" -description: "Show DAG state, agent progress, and branch status for an AgentHub session. Agent skill for Claude Code, Codex CLI, Gemini CLI, OpenClaw." +description: "Show DAG state, agent progress, and branch status for an AgentHub session. Use when the user runs /hub:status or asks how the AgentHub agents are. Agent skill for Claude Code, Codex CLI, Gemini CLI, OpenClaw." --- # /hub:status — Session Status diff --git a/docs/skills/engineering/api-design-reviewer.md b/docs/skills/engineering/api-design-reviewer.md index c2f1f4de..4cf357de 100644 --- a/docs/skills/engineering/api-design-reviewer.md +++ b/docs/skills/engineering/api-design-reviewer.md @@ -24,6 +24,21 @@ description: "Comprehensive REST API design review with automated linting, break The API Design Reviewer skill provides comprehensive analysis and review of API designs, focusing on REST conventions, best practices, and industry standards. This skill helps engineering teams build consistent, maintainable, and well-designed APIs through automated linting, breaking change detection, and design scorecards. +## Quick Start — run the tools first + +```bash +# 1. Lint an OpenAPI/Swagger spec for convention violations +python3 scripts/api_linter.py openapi.json --format json -o lint.json + +# 2. Detect breaking changes between two spec versions (gate: exits non-zero with --exit-on-breaking) +python3 scripts/breaking_change_detector.py openapi-v1.json openapi-v2.json --format json --exit-on-breaking -o breaking.json + +# 3. Score overall design quality (gate: --min-grade fails below threshold) +python3 scripts/api_scorecard.py openapi.json --format json --min-grade B -o scorecard.json +``` + +Review flow: run all three, report linter findings + breaking changes + grade to the user, fix, then re-run until the linter is clean, `--exit-on-breaking` passes (or breaking changes are version-bumped), and the scorecard meets the agreed `--min-grade`. Never sign off an API review on prose alone — attach the tool outputs. + ## Core Capabilities ### 1. API Linting and Convention Analysis @@ -168,7 +183,7 @@ Accept: application/vnd.myapi.v1+json } ], "requestId": "req-123456", - "timestamp": "2024-02-16T13:00:00Z" + "timestamp": "2026-02-16T13:00:00Z" } } ``` @@ -392,7 +407,7 @@ Provides comprehensive scoring of API design quality. ### Pre-commit Hooks ```bash #!/bin/bash -python engineering/api-design-reviewer/scripts/api_linter.py api/openapi.json +python engineering/skills/api-design-reviewer/scripts/api_linter.py api/openapi.json if [ $? -ne 0 ]; then echo "API linting failed. Please fix the issues before committing." exit 1 @@ -425,8 +440,5 @@ fi 9. **Missing Rate Limiting**: Protect your API from abuse and overload 10. **Inadequate Testing**: Test all aspects including error cases and edge conditions -## Conclusion - -The API Design Reviewer skill provides a comprehensive framework for building, reviewing, and maintaining high-quality REST APIs. By following these guidelines and using the provided tools, development teams can create APIs that are consistent, well-documented, secure, and maintainable. Regular use of the linting, breaking change detection, and scoring tools ensures continuous improvement and helps maintain API quality throughout the development lifecycle. \ No newline at end of file diff --git a/docs/skills/engineering/autoresearch-agent-loop.md b/docs/skills/engineering/autoresearch-agent-loop.md index 040125e4..bd1e444d 100644 --- a/docs/skills/engineering/autoresearch-agent-loop.md +++ b/docs/skills/engineering/autoresearch-agent-loop.md @@ -1,6 +1,6 @@ --- title: "/ar:loop — Autonomous Experiment Loop — Agent Skill for Codex & OpenClaw" -description: "Start an autonomous experiment loop with user-selected interval (10min, 1h, daily, weekly, monthly). Uses CronCreate for scheduling. Agent skill for Claude Code, Codex CLI, Gemini CLI, OpenClaw." +description: "Start an autonomous experiment loop with user-selected interval (10min, 1h, daily, weekly, monthly). Uses CronCreate for scheduling. Use when the. Agent skill for Claude Code, Codex CLI, Gemini CLI, OpenClaw." --- # /ar:loop — Autonomous Experiment Loop diff --git a/docs/skills/engineering/autoresearch-agent-resume.md b/docs/skills/engineering/autoresearch-agent-resume.md index 74957817..cd25c011 100644 --- a/docs/skills/engineering/autoresearch-agent-resume.md +++ b/docs/skills/engineering/autoresearch-agent-resume.md @@ -1,6 +1,6 @@ --- title: "/ar:resume — Resume Experiment — Agent Skill for Codex & OpenClaw" -description: "Resume a paused experiment. Checkout the experiment branch, read results history, continue iterating. Agent skill for Claude Code, Codex CLI, Gemini CLI, OpenClaw." +description: "Resume a paused experiment. Checkout the experiment branch, read results history, continue iterating. Use when the user runs /ar:resume or asks to. Agent skill for Claude Code, Codex CLI, Gemini CLI, OpenClaw." --- # /ar:resume — Resume Experiment diff --git a/docs/skills/engineering/autoresearch-agent-run.md b/docs/skills/engineering/autoresearch-agent-run.md index 23766da0..c5959b36 100644 --- a/docs/skills/engineering/autoresearch-agent-run.md +++ b/docs/skills/engineering/autoresearch-agent-run.md @@ -1,6 +1,6 @@ --- title: "/ar:run — Single Experiment Iteration — Agent Skill for Codex & OpenClaw" -description: "Run a single experiment iteration. Edit the target file, evaluate, keep or discard. Agent skill for Claude Code, Codex CLI, Gemini CLI, OpenClaw." +description: "Run a single experiment iteration. Edit the target file, evaluate, keep or discard. Use when the user runs /ar:run or asks for one manual. Agent skill for Claude Code, Codex CLI, Gemini CLI, OpenClaw." --- # /ar:run — Single Experiment Iteration diff --git a/docs/skills/engineering/autoresearch-agent-setup.md b/docs/skills/engineering/autoresearch-agent-setup.md index 00646f67..7a97fe69 100644 --- a/docs/skills/engineering/autoresearch-agent-setup.md +++ b/docs/skills/engineering/autoresearch-agent-setup.md @@ -1,6 +1,6 @@ --- title: "/ar:setup — Create New Experiment — Agent Skill for Codex & OpenClaw" -description: "Set up a new autoresearch experiment interactively. Collects domain, target file, eval command, metric, direction, and evaluator. Agent skill for Claude Code, Codex CLI, Gemini CLI, OpenClaw." +description: "Set up a new autoresearch experiment interactively. Collects domain, target file, eval command, metric, direction, and evaluator. Use when the user. Agent skill for Claude Code, Codex CLI, Gemini CLI, OpenClaw." --- # /ar:setup — Create New Experiment diff --git a/docs/skills/engineering/autoresearch-agent-status.md b/docs/skills/engineering/autoresearch-agent-status.md index ad20a8e6..6991ed44 100644 --- a/docs/skills/engineering/autoresearch-agent-status.md +++ b/docs/skills/engineering/autoresearch-agent-status.md @@ -1,6 +1,6 @@ --- title: "/ar:status — Experiment Dashboard — Agent Skill for Codex & OpenClaw" -description: "Show experiment dashboard with results, active loops, and progress. Agent skill for Claude Code, Codex CLI, Gemini CLI, OpenClaw." +description: "Show experiment dashboard with results, active loops, and progress. Use when the user runs /ar:status or asks how an autoresearch experiment is going. Agent skill for Claude Code, Codex CLI, Gemini CLI, OpenClaw." --- # /ar:status — Experiment Dashboard diff --git a/docs/skills/engineering/changelog-generator.md b/docs/skills/engineering/changelog-generator.md index ef7ae343..e12bd4ac 100644 --- a/docs/skills/engineering/changelog-generator.md +++ b/docs/skills/engineering/changelog-generator.md @@ -72,7 +72,18 @@ python3 scripts/generate_changelog.py \ --write CHANGELOG.md ``` -### 4. Lint Commits Before Merge +### 4. Compute the Next Version From Commits + +When the user has not decided the next version, derive it instead of guessing: + +```bash +git log v1.3.0..HEAD --oneline | \ + python3 scripts/version_bumper.py --current-version 1.3.0 --output-format json +``` + +Output JSON contains `recommended_version`, `bump_type` (`major`/`minor`/`patch`/`none`), and with `--include-commands` the exact `git tag` commands. Feed `recommended_version` into `generate_changelog.py --next-version`. Pre-releases: add `--prerelease alpha|beta|rc`. Input must be real `git log --oneline` output (hex hashes); a sample lives at `assets/sample_git_log.txt`. + +### 5. Lint Commits Before Merge ```bash python3 scripts/commit_linter.py --from-ref origin/main --to-ref HEAD --strict --format text @@ -130,11 +141,38 @@ SemVer mapping: 5. Tag releases only after changelog generation succeeds. 6. Keep an `[Unreleased]` section for manual curation when needed. +## Hotfix Severity & SLAs + +When a release goes wrong, classify before acting (full procedures in [references/hotfix-procedures.md](https://github.com/alirezarezvani/claude-skills/tree/main/engineering/skills/changelog-generator/references/hotfix-procedures.md)): + +| Severity | Definition | SLA | Approval | +|---|---|---|---| +| P0 — Critical | Outage, data loss, exploited vulnerability | Fix deployed ≤ 2h; emergency deploy bypasses normal gates | Engineering Lead + On-call Manager | +| P1 — High | Major feature broken, significant user impact | Fix deployed ≤ 24h; expedited review | Engineering Lead + Product Manager | +| P2 — Medium | Minor issues, limited impact | Next release cycle | Standard PR review | + +Hotfix branch comes from the last stable tag, contains the minimal fix only, and gets its own patch-bump changelog entry via the workflow above. + +## Rollback Triggers + +Pre-commit to these thresholds before tagging; roll back when any fires: + +| Trigger | Threshold | +|---|---| +| Error rate spike | > 2x baseline within 30 min | +| Performance degradation | > 50% latency increase | +| Feature failure | Core functionality broken | +| Security incident | Vulnerability being exploited | +| Data corruption | Database integrity compromised | + +Prefer feature-flag disable over code rollback; database rollbacks only for non-destructive migrations (forward-only migrations preferred). See [references/hotfix-procedures.md](https://github.com/alirezarezvani/claude-skills/tree/main/engineering/skills/changelog-generator/references/hotfix-procedures.md). + ## References - [references/ci-integration.md](https://github.com/alirezarezvani/claude-skills/tree/main/engineering/skills/changelog-generator/references/ci-integration.md) - [references/changelog-formatting-guide.md](https://github.com/alirezarezvani/claude-skills/tree/main/engineering/skills/changelog-generator/references/changelog-formatting-guide.md) - [references/monorepo-strategy.md](https://github.com/alirezarezvani/claude-skills/tree/main/engineering/skills/changelog-generator/references/monorepo-strategy.md) +- [references/hotfix-procedures.md](https://github.com/alirezarezvani/claude-skills/tree/main/engineering/skills/changelog-generator/references/hotfix-procedures.md) - [README.md](https://github.com/alirezarezvani/claude-skills/tree/main/engineering/skills/changelog-generator/README.md) ## Release Governance diff --git a/docs/skills/engineering/collab-proof.md b/docs/skills/engineering/collab-proof.md new file mode 100644 index 00000000..2c4a4a79 --- /dev/null +++ b/docs/skills/engineering/collab-proof.md @@ -0,0 +1,393 @@ +--- +title: "collab-proof — Agent Skill for Codex & OpenClaw" +description: "Use when you want to understand what Claude contributed vs what you drove in a session. Triggers on: /collab-proof, session retrospective, ai. Agent skill for Claude Code, Codex CLI, Gemini CLI, OpenClaw." +--- + +# collab-proof + +<div class="page-meta" markdown> +<span class="meta-badge">:material-rocket-launch: Engineering - POWERFUL</span> +<span class="meta-badge">:material-identifier: `collab-proof`</span> +<span class="meta-badge">:material-github: <a href="https://github.com/alirezarezvani/claude-skills/tree/main/engineering/collab-proof/skills/collab-proof/SKILL.md">Source</a></span> +</div> + +<div class="install-banner" markdown> +<span class="install-label">Install:</span> <code>claude /plugin install engineering-advanced-skills</code> +</div> + + +Surfaces AI collaboration evidence the developer didn't consciously record. +Vela 3-layer pipeline × ADHD 4-frame reasoning — prompt-native, zero dependencies. + +--- + +## Layer 01 — Signal detection + +Run `git log --oneline -10` and `git diff --stat HEAD~3..HEAD` first. + +Classify signal level using this rubric (pick the highest that matches): + +**HIGH** → full artifacts (DECISIONS.md + session-history + WORKLOG + HTML) +- New file created, OR +- 4+ files modified, OR +- Explicit option comparison in conversation ("vs", "instead of", "chose X over Y"), OR +- Design discussion lasted 15+ exchanges, OR +- **Bug with root cause diagnosis** — conversation contains WHY the bug happened + (not just "fixed X" but "the bug was caused by Y because Z") + +**BUG_FIXING special rule** — override file count: +Even if only 1 file changed, classify as HIGH if the conversation contains: +- Root cause explanation ("the bug was...", "this happened because...", "the issue is...") +- Diagnosis process ("I checked...", "turned out...", "the problem was...") +- Fix rationale ("chose this approach because...", "instead of X, used Y because...") +File count doesn't matter for bugs — a well-diagnosed single-file fix is more valuable +than a 10-file feature with no discussion. + +**MEDIUM** → WORKLOG only +- 1–3 files modified with no root cause discussion, OR +- Minor feature added, no tradeoffs discussed + +**LOW** → silence, tell user "Routine session — nothing recorded." +- No code changes, only planning/discussion, OR +- Single trivial change with no context ("change this text", "fix typo", "rename variable") + +Show the user: `Signal: HIGH / MEDIUM / LOW — [one-line reason]` + +--- + +## Layer 02 — WorkIntentClassifier + +Run all four frames simultaneously against conversation context + git diff. +Score each frame 0.0–1.0 using the rubric below. Then apply pruning and classification rules. + +### Frame scoring rubric + +**Frame A — Technical** (code churn complexity) +- `1.0` New module/file created, complex logic added (state machine, Lua script, novel algorithm) +- `0.5` Existing function logic modified, simple API endpoint added +- `0.1` Typo fix, comment change, plain text edit + +**Frame B — Uncertainty** (developer doubt signals) +- `1.0` Code written then fully rolled back, explicit doubt expressed ("이게 맞나?", "동작 안 하네"), `git revert` +- `0.5` Advice sought from Claude mid-implementation, 2+ revision requests on same area +- `0.0` Uninterrupted directive execution — developer knew exactly what to build + +**Frame C — Fork** (decision branch presence) +- `1.0` Two or more alternatives explicitly compared in conversation (A vs B) +- `0.5` No explicit comparison but tradeoff mentioned (performance vs readability) +- `0.0` Single standard approach applied, no alternatives considered + +**Frame D — AI contribution** (Claude's actual impact) +- `1.0` Claude identified a bug/edge case the developer hadn't noticed and proposed the fix +- `0.6` Claude generated structural boilerplate/skeleton that significantly accelerated execution +- `0.2` Claude reformatted or transcribed developer-directed code without independent contribution + +--- + +### Pruning rule + +Prune any frame scoring < 0.4. + +**Exception — High-Speed Execution Guard:** +If `Frame A >= 0.8` AND `Frame D >= 0.6`, do NOT prune and do NOT silence the session, +even if Frame B = 0.0 and Frame C = 0.0. +This is a boilerplate-heavy FEATURE_BUILDING session. Classify immediately as `FEATURE_BUILDING` with `HIGH` signal. +Rationale: zero uncertainty in a fast-moving session is a feature, not a reason to discard it. + +--- + +### Intent classification + +| Surviving frames | Dominant intent | Meaning | +|---|---|---| +| A high + D mid-high (B, C low) | `FEATURE_BUILDING` | High-velocity feature generation, Claude scaffolding | +| B high + A/D high | `BUG_FIXING` or `STUCK` | Active debugging or unresolved looping | +| C high + A high | `REFACTORING` or `EXPLORING` | Architecture exploration, weighing alternatives | +| All frames < 0.4 | `FLOW_STATE` or LOW | Routine typing, silence unless Layer 01 was HIGH | + +If multiple intents tie, pick the one with the highest combined frame score. +Record the runner-up — it belongs in the session narrative. + +--- + +### Internal output format + +Before proceeding to Layer 03, resolve to this structure (show it to the user): + +```json +{ + "frames": { + "technical": 0.0, + "uncertainty": 0.0, + "fork": 0.0, + "ai_contribution": 0.0 + }, + "pruned": ["list of pruned frame names"], + "intent": "FEATURE_BUILDING", + "signal": "HIGH", + "calibration_note": "one sentence explaining any exception rule applied" +} +``` + +--- + +## Layer 03 — Output + +### If HIGH signal + +**Append to `DECISIONS.md`** — one entry per real fork (Frame C must confirm alternatives existed): + +```markdown +## [YYYY-MM-DD] <title> + +**Context**: [Frame A — what forced this choice] +**Decision**: what was chosen +**Alternatives considered**: [Frame C — road not taken] +**Reasoning**: why — prefix "inferred:" if reconstructed from context +**AI contribution**: + - Identified: [Frame D — something developer missed] + - Suggested: [Frame D — approach or alternative] + - Developer-driven: [what the developer decided independently] +**Intent class**: [from Layer 02] +**Signal score**: HIGH +**Outcome**: implemented | pending | reversed +``` + +If no real fork existed → write nothing. Never fabricate decisions. + +**BUG_FIXING intent: use this format instead:** + +```markdown +## [YYYY-MM-DD] <bug title> + +**Root cause**: what actually caused the bug — the WHY, not just the what +**Symptom**: what the developer observed +**Fix**: what was changed +**Why this fix**: rationale — inferred if not stated explicitly +**Alternative fixes considered**: other approaches discussed (if any) +**AI contribution**: + - Identified: [Frame D — did Claude spot the root cause?] + - Suggested: [Frame D — fix approach or diagnostic step] + - Developer-driven: [what the developer diagnosed/decided independently] +**Intent class**: BUG_FIXING +**Signal score**: HIGH +**Outcome**: fixed | workaround | deferred +``` + +**Create `session-history/YYYY-MM-DD-HHMM.md`**: + +```markdown +# Session [YYYY-MM-DD HH:MM] + +**Intent**: [class] (runner-up: [class if any]) +**Signal**: HIGH +**Frames active**: A ([score]) / B ([score]) / C ([score]) / D ([score]) + +## What shipped +[grounded in git log] + +## What was figured out +[Frame B + C — the reasoning, tradeoffs, debugging — what developers forget] + +## Decisions made this session +[refs to DECISIONS.md entries] + +## Where it got hard +[Frame B findings — uncertainty, reverts, EXPLORING/STUCK signals] + +## AI contribution summary +[Frame D synthesis — one honest paragraph, calibrated] + +## Next steps inferred +[what's obviously incomplete] +``` + +**Append to `WORKLOG.md`**: +``` +YYYY-MM-DD HH:MM | [intent] | HIGH | D:[score] | cache:[hit%]% | tok:[total] | <verb phrase> — <why it mattered> +``` + +Fields: +- `D:[score]` — Frame D AI contribution score (0.0–1.0) +- `cache:[hit%]%` — cache hit rate from token analysis (or `cache:n/a` if no data) +- `tok:[total]` — total tokens this session (input + cache_read + cache_create + output, in K e.g. `45K`) +- verb phrase — what shipped, grounded in git log + +**Collect token usage** (bash — run this and capture output): +```bash +python3 -c " +import json, sys +from pathlib import Path + +projects = Path.home() / '.claude/projects' +files = sorted(projects.rglob('*.jsonl'), key=lambda f: f.stat().st_mtime, reverse=True) +if not files: + print('no_data'); sys.exit() + +with open(files[0]) as fp: + lines = [json.loads(l) for l in fp if l.strip()] + +ti = to = cr = cc = 0 +turns = [] +for i, line in enumerate(lines): + if line.get('type') == 'assistant': + u = line.get('message', {}).get('usage', {}) + if not u: continue + inp = u.get('input_tokens', 0) + ti += inp; to += u.get('output_tokens', 0) + cr += u.get('cache_read_input_tokens', 0) + cc += u.get('cache_creation_input_tokens', 0) + prompt = '' + for j in range(i-1, -1, -1): + if lines[j].get('type') == 'user': + c = lines[j].get('message', {}).get('content', '') + prompt = (c if isinstance(c, str) else next((x.get('text','') for x in c if isinstance(x,dict) and x.get('type')=='text'), ''))[:80] + break + turns.append((inp, prompt)) + +total = ti + cr + cc +hit = cr / total * 100 if total else 0 +print(f'input={ti} output={to} cache_read={cr} cache_create={cc} hit={hit:.0f} turns={len(turns)}') +turns.sort(reverse=True) +for idx, (tok, p) in enumerate(turns[:3]): + print(f'top{idx+1}={tok}|{p}') +" +``` + +Parse the output and include token stats in the session narrative. Then: + +**Generate `session-history/YYYY-MM-DD-HHMM-proof.html`** — write a self-contained HTML file. Structure and class names are fixed — do not rename or reorder sections. + +**Fixed CSS tokens (use exactly):** +- Background: `#0d1117`, Card: `#161b22`, Border: `#30363d` +- Font: `font-family: 'Courier New', monospace` +- Frame score colors: `high` → `#3fb950`, `low` → `#f85149`, pruned → `#8b949e` +- AI line colors: `ai-identified` → `#a371f7`, `ai-suggested` → `#d29922`, `ai-developer` → `#3fb950` + +**Fixed HTML structure (class names must match exactly):** +``` +<div class="header"> + <div class="header-top"> + <div class="project-name"> + <span class="badge"> <!-- intent class --> + <div class="meta-row"> <!-- date, branch, signal level text --> + <div class="signal-container"> + <div class="signal-label"> + <div class="signal-track"> + <div class="signal-fill"> <!-- width % driven by signal score --> + +<div class="section"> <!-- frames --> + <div class="section-title"> ... <span class="count">Layer 02 · ADHD tree-of-thought</span> + <div class="frames-grid"> + <div class="frame-card"> <!-- pruned: class="frame-card pruned" --> + <div class="frame-label"> <!-- Frame A / B / C / D --> + <div class="frame-name"> + <div class="frame-score high|low"> <!-- score value --> + +<div class="section"> <!-- decisions — skip section if none --> + <div class="section-title"> ... <span class="count">N recorded</span> + <div class="decision-card"> <!-- one per DECISIONS.md entry --> + <div class="decision-header"> + <div class="decision-title"> + <div class="decision-date"> + <div class="decision-fields"> + <div class="field-row"> + <div class="field-label"> <!-- Context / Decision / Alternatives / Reasoning --> + <div class="field-value"> + <div class="field-row"> <!-- AI contribution row --> + <div class="field-label">AI contribution</div> + <div class="field-value"> + <div class="ai-block"> + <div class="ai-line ai-identified|ai-suggested|ai-developer"> + <span class="tag">IDENTIFIED|SUGGESTED|DEV-DRIVEN</span> + <div class="field-row"> <!-- Outcome row --> + <div class="field-label">Outcome</div> + <div class="field-value"> + <span class="outcome-badge outcome-implemented|outcome-pending|outcome-reversed"> + +<div class="section"> <!-- session narrative --> + <div class="section-title">Session narrative</div> + <div class="narrative-grid"> + <div class="narrative-card"> <!-- What shipped --> + <div class="narrative-card"> <!-- What was figured out --> + <div class="narrative-card"> <!-- Where it got hard --> + <div class="narrative-card"> <!-- Next steps inferred --> + +<div class="section"> <!-- AI contribution summary --> + <div class="section-title">AI contribution summary</div> + <div class="narrative-card"> <!-- Frame D synthesis paragraph --> + +<div class="section"> <!-- token usage --> + <div class="section-title">Token usage</div> + <div class="narrative-card"> <!-- cache hit rate bar + top turns + optimization note --> + +<div class="section"> <!-- worklog tail --> + <div class="section-title"> ... <span class="count">last N entries</span> + <div class="worklog-entry"> <!-- one per recent WORKLOG line --> + +<div class="footer"> <!-- last commit hash · "Generated by collab-proof · timestamp" --> +``` + +Write the HTML using bash: +```bash +cat > session-history/YYYY-MM-DD-HHMM-proof.html << 'HTMLEOF' +<!DOCTYPE html> +... (full HTML with inline CSS, no external resources) +HTMLEOF +``` + +After writing, show: `open session-history/YYYY-MM-DD-HHMM-proof.html` + +--- + +### If MEDIUM signal + +Append one line to `WORKLOG.md` only: +``` +YYYY-MM-DD HH:MM | [intent] | MEDIUM | D:[score] | cache:[hit%]% | tok:[total] | <verb phrase> +``` + +--- + +### If LOW signal + +Tell user: "Signal: LOW — Routine session, nothing recorded." + +--- + +## Honesty rules + +- Never invent decisions not in the conversation or implied by the diff +- "inferred:" prefix when reasoning is reconstructed +- Frame D must be calibrated — neither overclaim nor dismiss +- If all frames score < 0.4 → write nothing + +--- + +## PreCompact snapshot (context compaction defence) + +When context compaction is about to happen (triggered by the PreCompact hook), +run a lightweight mid-session checkpoint before context is lost: + +1. Compute current Layer 01 signal level from available context +2. Score all four frames against what's visible now +3. Write a snapshot to `session-history/.tmp-TIMESTAMP.json`: + +```json +{ + "timestamp": "YYYY-MM-DD HH:MM:SS", + "trigger": "pre-compact", + "signal": "HIGH / MEDIUM / LOW", + "frames": { "technical": 0.0, "uncertainty": 0.0, "fork": 0.0, "ai_contribution": 0.0 }, + "intent": "FEATURE_BUILDING", + "key_moments": [ + "one-line description of the most important decision or finding so far" + ] +} +``` + +When `/collab-proof` runs at session end: +- Read all `session-history/.tmp-*.json` files +- Merge frame scores (take max per frame across all snapshots) +- Combine `key_moments` arrays — these preserve tradeoff discussions that were compacted away +- Delete `.tmp-*.json` files after merging diff --git a/docs/skills/engineering/command-guide.md b/docs/skills/engineering/command-guide.md deleted file mode 100644 index 923e5eef..00000000 --- a/docs/skills/engineering/command-guide.md +++ /dev/null @@ -1,316 +0,0 @@ ---- -title: "Claude Code Command Selection Guide — Agent Skill for Codex & OpenClaw" -description: "Claude Code Command Selection Guide - Automatically recommend and select the right commands, agents, and skills in Claude Code. Use when: (1) user is." ---- - -# Claude Code Command Selection Guide - -<div class="page-meta" markdown> -<span class="meta-badge">:material-rocket-launch: Engineering - POWERFUL</span> -<span class="meta-badge">:material-identifier: `command-guide`</span> -<span class="meta-badge">:material-github: <a href="https://github.com/alirezarezvani/claude-skills/tree/main/engineering/skills/command-guide/SKILL.md">Source</a></span> -</div> - -<div class="install-banner" markdown> -<span class="install-label">Install:</span> <code>claude /plugin install engineering-advanced-skills</code> -</div> - - -This skill helps you choose the most appropriate command, agent, or skill for different scenarios. - -## Quick Decision Flowchart - -```mermaid -graph TD - A[User Request] --> B{Request Type?} - B -->|New Feature| C[/plan] - B -->|Bug Fix| D[/tdd or build-error-resolver] - B -->|Code Review| E[/code-review or code-reviewer agent] - B -->|Testing| F[/e2e or tdd-guide agent] - B -->|Context Too Long| G[/compact] - B -->|Documentation| H[/docs or docs-lookup agent] - B -->|Looping Task| I[/loop] - B -->|Security Review| J[security-reviewer agent] - - C --> K[planner agent] - D --> L{Build Failed?} - L -->|Yes| M[build-error-resolver] - L -->|No| N[tdd-guide] - E --> O[code-reviewer] - F --> P[e2e-runner] -``` - -## 1. Built-in Slash Commands - -### Session Management Commands - -| Command | Use Case | Example | -|---------|----------|---------| -| `/compact` | Context too long (>150K tokens), slow response, task phase transition | `/compact` or auto-trigger | -| `/clear` | Start fresh conversation, clear history | `/clear` | -| `/loop` | Periodic task execution, automated looping work | `/loop 5m check build status` | -| `/help` | View help, learn commands | `/help` | -| `/fast` | Need faster response (Opus 4.6 only) | `/fast` | -| `/model` | Switch model | `/model sonnet` | - -### Development Workflow Commands - -| Command | Use Case | Activation Timing | -|---------|----------|-------------------| -| `/plan` | Start new feature, architecture refactor, complex tasks | **Enter Plan Mode** | -| `/tdd` | Write tests, TDD development workflow | When test guidance needed | -| `/e2e` | E2E testing, critical user flow verification | When browser testing needed | -| `/code-review` | Code quality review | After writing code | -| `/build-fix` | Build failure, type errors | When build fails | -| `/learn` | Extract patterns from session, learning | Before session ends | -| `/skill-create` | Create new skill from git history | When repeating patterns found | - -### Documentation & Query Commands - -| Command | Use Case | Example | -|---------|----------|---------| -| `/docs` | Update project documentation | `/docs` | -| `/update-codemaps` | Update code maps | `/update-codemaps` | -| `/remember` | Save memory to memory system | `/remember user prefers concise output` | -| `/tasks` | View task list | `/tasks` | - ---- - -## 2. Agents Selection - -### Development Workflow Agents - -| Agent | Trigger Condition | Purpose | -|-------|-------------------|---------| -| `planner` | Complex feature request, architectural decision | Create implementation plan | -| `architect` | System design, tech stack selection | Architecture analysis and decisions | -| `tdd-guide` | New feature, bug fix | TDD workflow guidance | -| `code-reviewer` | **Invoke immediately after writing code** | Code quality review | -| `security-reviewer` | Handling auth, API, sensitive data | Security vulnerability detection | - -### Problem Solving Agents - -| Agent | Trigger Condition | Purpose | -|-------|-------------------|---------| -| `build-error-resolver` | **Invoke immediately when build fails** | Fix build/type errors | -| `e2e-runner` | Critical user flows, before PR | E2E test execution | -| `refactor-cleaner` | Code maintenance, dead code cleanup | Dead code detection and cleanup | -| `doc-updater` | Update docs, codemaps | Documentation sync | - -### Research & Exploration Agents - -| Agent | Trigger Condition | Purpose | -|-------|-------------------|---------| -| `Explore` | Codebase exploration, file finding | Quick codebase exploration | -| `general-purpose` | Complex multi-step tasks | General task handling | -| `docs-lookup` | Query library/framework docs | Get latest API documentation | - ---- - -## 3. Skills Selection - -### Workflow Skills - -| Skill | Trigger Timing | Purpose | -|-------|----------------|---------| -| `tdd-workflow` | Developing new feature/fixing bug | Complete TDD workflow guidance | -| `verification-loop` | After feature completion, before PR | Comprehensive verification (build/test/lint/security) | -| `strategic-compact` | Long session, context pressure | Guide when to manually `/compact` | - -### Architecture & Pattern Skills - -| Skill | Trigger Timing | Purpose | -|-------|----------------|---------| -| `frontend-patterns` | Frontend development | React/Next.js/Vue best practices | -| `backend-patterns` | Backend development | API/service architecture patterns | -| `api-design` | API design | RESTful/API design standards | -| `mcp-server-patterns` | MCP server development | MCP configuration and patterns | - -### Testing Skills - -| Skill | Trigger Timing | Purpose | -|-------|----------------|---------| -| `e2e-testing` | E2E testing needs | Playwright test generation | -| `security-review` | Security review needs | OWASP Top 10 detection | - -### Research Skills - -| Skill | Trigger Timing | Purpose | -|-------|----------------|---------| -| `deep-research` | Need deep research | Multi-round search and research | -| `exa-search` | Need web search | Web content search | -| `documentation-lookup` | Query library docs | Context7 documentation query | - ---- - -## 4. Scenario Decision Matrix - -### By Task Phase - -| Phase | Recommended Tool Combination | Reason | -|-------|------------------------------|--------| -| **Requirements Analysis** | `planner` + `Explore` | Plan first, explore later | -| **Architecture Design** | `architect` + `api-design` skill | Professional architecture guidance | -| **Pre-Development** | `tdd-guide` + `tdd-workflow` skill | Test first | -| **During Development** | Direct edit + quick iteration | Stay in flow | -| **Post-Development** | `code-reviewer` + `verification-loop` | Quality gate | -| **Testing Phase** | `e2e-runner` + `e2e-testing` skill | Complete test coverage | -| **Before PR** | `security-reviewer` + `verification-loop` | Final verification | -| **Build Failure** | `build-error-resolver` | Focused fix | - -### By Problem Type - -| Problem | Invoke Immediately | Note | -|---------|--------------------|------| -| Build failure | `build-error-resolver` | Minimal changes, quick fix | -| Type error | `build-error-resolver` | TypeScript specialist | -| Bug fix | `tdd-guide` | Write test then fix | -| Security vulnerability | `security-reviewer` | OWASP detection | -| Poor code quality | `code-reviewer` | Immediate review | -| Missing documentation | `doc-updater` | Auto update | -| Dead code | `refactor-cleaner` | Safe cleanup | - -### By Development Type - -| Development Type | Skills Combination | -|------------------|--------------------| -| Frontend feature | `frontend-patterns` + `tdd-workflow` | -| Backend API | `backend-patterns` + `api-design` + `tdd-workflow` | -| MCP server | `mcp-server-patterns` + `tdd-workflow` | -| Database | `database-reviewer` agent | -| Security feature | `security-reviewer` + `security-review` skill | - ---- - -## 5. Parallel Execution Strategy - -### Parallelizable Scenarios - -Recommended: Launch multiple independent tasks simultaneously - -Scenario: Preparing PR after code completion -- Agent 1: code-reviewer (code quality) -- Agent 2: security-reviewer (security review) -- Agent 3: e2e-runner (E2E tests) - -Scenario: Large refactor analysis -- Agent 1: architect (architecture analysis) -- Agent 2: Explore (code exploration) -- Agent 3: refactor-cleaner (dead code detection) - -### Sequential Execution Required - -Cannot parallelize: Dependencies exist - -Scenario: Fixing build error -- Sequence: build-error-resolver -> test verification -> code-reviewer - -Scenario: New feature development -- Sequence: planner -> tdd-guide (write tests) -> implementation -> code-reviewer - ---- - -## 6. Auto-Trigger Rules - -### Invoke Without User Request - -| Situation | Auto Action | -|-----------|-------------| -| Code written/modified | **Immediately invoke** `code-reviewer` | -| Build fails | **Immediately invoke** `build-error-resolver` | -| Complex feature request | **Immediately invoke** `planner` | -| Handling auth/sensitive data | **Immediately invoke** `security-reviewer` | -| New feature/bug fix | **Immediately invoke** `tdd-guide` | -| Architectural decision | **Immediately invoke** `architect` | - ---- - -## 7. Context Management Timing - -| Indicator | Trigger `/compact` | -|-----------|-------------------| -| Token > 150K | Immediately compact | -| Slow response | Suggest compact | -| Task phase switch | Compact at boundary | -| Major milestone completed | Compact then continue | -| Debugging ends -> new task | Clear debug traces | - -**Best Practices**: -- Compact after research, before implementation (preserve plan) -- Compact after milestone completion (clear intermediate state) -- Don't compact mid-implementation (lose variables/paths) - ---- - -## 8. Command Cheat Sheet - -``` -Development Workflow: -/plan -> Enter planning mode (complex tasks) -/tdd -> TDD workflow -/e2e -> E2E testing -/code-review -> Code review -/build-fix -> Fix build - -Session Management: -/compact -> Compact context -/clear -> Clear session -/loop -> Looping task -/fast -> Fast mode - -Documentation & Memory: -/docs -> Update docs -/remember -> Save memory -/tasks -> View tasks - -Help: -/help -> View all commands -``` - ---- - -## 9. Usage Examples - -### Example 1: New Feature Development - -User: Add user authentication feature - -Workflow: -1. /plan -> planner agent creates plan -2. tdd-guide -> write tests -3. Implementation -> edit code -4. code-reviewer -> code review -5. security-reviewer -> security review (auth sensitive) -6. e2e-runner -> E2E tests -7. /compact -> compact after milestone completion - -### Example 2: Build Failure - -User: npm run build failed - -Workflow: -1. build-error-resolver -> analyze error, minimal fix -2. Verify build success -3. code-reviewer -> check fix quality - -### Example 3: Code Refactoring - -User: Refactor authentication module - -Workflow: -1. architect -> architecture analysis -2. planner -> implementation plan -3. refactor-cleaner -> dead code detection -4. tdd-guide -> ensure test coverage -5. Implementation -> refactor code -6. verification-loop -> comprehensive verification - ---- - -**Core Principles**: -1. **Plan first, implement later** - Use `/plan` for complex tasks -2. **Test first** - Use `tdd-guide` for new features -3. **Review immediately after coding** - Use `code-reviewer` when code complete -4. **Fix build immediately when failed** - Use `build-error-resolver` -5. **Review sensitive code** - Use `security-reviewer` for auth/API -6. **Verify comprehensively before PR** - Use `verification-loop` diff --git a/docs/skills/engineering/database-designer.md b/docs/skills/engineering/database-designer.md index 1c35b84f..17197559 100644 --- a/docs/skills/engineering/database-designer.md +++ b/docs/skills/engineering/database-designer.md @@ -44,6 +44,38 @@ A comprehensive database design skill that provides expert-level analysis, optim - **Rollback Strategy**: Complete reversal capabilities with validation - **Execution Planning**: Ordered migration steps with dependency resolution +## Tool Workflow (run these — do not analyze schemas by hand) + +All paths relative to this skill folder; sample inputs in `assets/`. + +### 1. Analyze the schema + +```bash +python3 schema_analyzer.py --input schema.sql --generate-erd --output-format json -o analysis.json +``` + +Accepts SQL DDL or JSON schema (`assets/sample_schema.sql` / `sample_schema.json`). Output includes normalization findings, missing constraints, naming issues, and a Mermaid ERD — show the ERD to the user and fix flagged issues before optimizing. + +### 2. Optimize indexes against real query patterns + +```bash +python3 index_optimizer.py --schema assets/sample_schema.json --queries assets/sample_query_patterns.json --analyze-existing --format json -o indexes.json +``` + +Write the user's hot queries into a query-patterns JSON first (copy `assets/sample_query_patterns.json`). Output is a priority-ordered list of CREATE INDEX recommendations plus redundant-index removals. + +### 3. Generate the migration + +```bash +python3 migration_generator.py --current current_schema.json --target target_schema.json --zero-downtime --format sql -o migration.sql +``` + +`--zero-downtime` emits an expand-contract plan; `--validate-only` checks feasibility without generating SQL. + +### 4. Verification loop + +Re-run step 1 on the *target* schema and assert the issues found in the first pass are gone; run `migration_generator.py --validate-only` before handing over the migration. + ## Database Design Principles → See references/database-design-reference.md for details @@ -291,10 +323,3 @@ Fixes: - **senior-backend** — application-layer patterns (connection pooling, ORM best practices) - **senior-devops** — infrastructure provisioning for database clusters and replicas ---- - -## Conclusion - -Effective database design requires balancing multiple competing concerns: performance, scalability, maintainability, and business requirements. This skill provides the tools and knowledge to make informed decisions throughout the database lifecycle, from initial schema design through production optimization and evolution. - -The included tools automate common analysis and optimization tasks, while the comprehensive guides provide the theoretical foundation for making sound architectural decisions. Whether building a new system or optimizing an existing one, these resources provide expert-level guidance for creating robust, scalable database solutions. diff --git a/docs/skills/engineering/dependency-auditor.md b/docs/skills/engineering/dependency-auditor.md index a295e65d..0ed230ac 100644 --- a/docs/skills/engineering/dependency-auditor.md +++ b/docs/skills/engineering/dependency-auditor.md @@ -16,334 +16,81 @@ description: "Audit and manage dependencies across multi-language projects. Iden </div> -> **Skill Type:** POWERFUL -> **Category:** Engineering -> **Domain:** Dependency Management & Security +> **Skill Type:** POWERFUL · **Category:** Engineering · **Domain:** Dependency Management & Security -## Overview - -The **Dependency Auditor** is a comprehensive toolkit for analyzing, auditing, and managing dependencies across multi-language software projects. This skill provides deep visibility into your project's dependency ecosystem, enabling teams to identify vulnerabilities, ensure license compliance, optimize dependency trees, and plan safe upgrades. - -In modern software development, dependencies form complex webs that can introduce significant security, legal, and maintenance risks. A single project might have hundreds of direct and transitive dependencies, each potentially introducing vulnerabilities, license conflicts, or maintenance burden. This skill addresses these challenges through automated analysis and actionable recommendations. - -## Core Capabilities - -### 1. Vulnerability Scanning & CVE Matching - -**Comprehensive Security Analysis** -- Scans dependencies against built-in vulnerability databases -- Matches Common Vulnerabilities and Exposures (CVE) patterns -- Identifies known security issues across multiple ecosystems -- Analyzes transitive dependency vulnerabilities -- Provides CVSS scores and exploit assessments -- Tracks vulnerability disclosure timelines -- Maps vulnerabilities to dependency paths - -**Multi-Language Support** -- **JavaScript/Node.js**: package.json, package-lock.json, yarn.lock -- **Python**: requirements.txt, pyproject.toml, Pipfile.lock, poetry.lock -- **Go**: go.mod, go.sum -- **Rust**: Cargo.toml, Cargo.lock -- **Ruby**: Gemfile, Gemfile.lock -- **Java/Maven**: pom.xml, gradle.lockfile -- **PHP**: composer.json, composer.lock -- **C#/.NET**: packages.config, project.assets.json - -### 2. License Compliance & Legal Risk Assessment - -**License Classification System** -- **Permissive Licenses**: MIT, Apache 2.0, BSD (2-clause, 3-clause), ISC -- **Copyleft (Strong)**: GPL (v2, v3), AGPL (v3) -- **Copyleft (Weak)**: LGPL (v2.1, v3), MPL (v2.0) -- **Proprietary**: Commercial, custom, or restrictive licenses -- **Dual Licensed**: Multi-license scenarios and compatibility -- **Unknown/Ambiguous**: Missing or unclear licensing - -**Conflict Detection** -- Identifies incompatible license combinations -- Warns about GPL contamination in permissive projects -- Analyzes license inheritance through dependency chains -- Provides compliance recommendations for distribution -- Generates legal risk matrices for decision-making - -### 3. Outdated Dependency Detection - -**Version Analysis** -- Identifies dependencies with available updates -- Categorizes updates by severity (patch, minor, major) -- Detects pinned versions that may be outdated -- Analyzes semantic versioning patterns -- Identifies floating version specifiers -- Tracks release frequencies and maintenance status - -**Maintenance Status Assessment** -- Identifies abandoned or unmaintained packages -- Analyzes commit frequency and contributor activity -- Tracks last release dates and security patch availability -- Identifies packages with known end-of-life dates -- Assesses upstream maintenance quality - -### 4. Dependency Bloat Analysis - -**Unused Dependency Detection** -- Identifies dependencies that aren't actually imported/used -- Analyzes import statements and usage patterns -- Detects redundant dependencies with overlapping functionality -- Identifies oversized packages for simple use cases -- Maps actual vs. declared dependency usage - -**Redundancy Analysis** -- Identifies multiple packages providing similar functionality -- Detects version conflicts in transitive dependencies -- Analyzes bundle size impact of dependencies -- Identifies opportunities for dependency consolidation -- Maps dependency overlap and duplication - -### 5. Upgrade Path Planning & Breaking Change Risk - -**Semantic Versioning Analysis** -- Analyzes semver patterns to predict breaking changes -- Identifies safe upgrade paths (patch/minor versions) -- Flags major version updates requiring attention -- Tracks breaking changes across dependency updates -- Provides rollback strategies for failed upgrades - -**Risk Assessment Matrix** -- Low Risk: Patch updates, security fixes -- Medium Risk: Minor updates with new features -- High Risk: Major version updates, API changes -- Critical Risk: Dependencies with known breaking changes - -**Upgrade Prioritization** -- Security patches: Highest priority -- Bug fixes: High priority -- Feature updates: Medium priority -- Major rewrites: Planned priority -- Deprecated features: Immediate attention - -### 6. Supply Chain Security - -**Dependency Provenance** -- Verifies package signatures and checksums -- Analyzes package download sources and mirrors -- Identifies suspicious or compromised packages -- Tracks package ownership changes and maintainer shifts -- Detects typosquatting and malicious packages - -**Transitive Risk Analysis** -- Maps complete dependency trees -- Identifies high-risk transitive dependencies -- Analyzes dependency depth and complexity -- Tracks influence of indirect dependencies -- Provides supply chain risk scoring - -### 7. Lockfile Analysis & Deterministic Builds - -**Lockfile Validation** -- Ensures lockfiles are up-to-date with manifests -- Validates integrity hashes and version consistency -- Identifies drift between environments -- Analyzes lockfile conflicts and resolution strategies -- Ensures deterministic, reproducible builds - -**Environment Consistency** -- Compares dependencies across environments (dev/staging/prod) -- Identifies version mismatches between team members -- Validates CI/CD environment consistency -- Tracks dependency resolution differences - -## Technical Architecture - -### Scanner Engine (`dep_scanner.py`) -- Multi-format parser supporting 8+ package ecosystems -- Built-in vulnerability database with 500+ CVE patterns -- Transitive dependency resolution from lockfiles -- JSON and human-readable output formats -- Configurable scanning depth and exclusion patterns - -### License Analyzer (`license_checker.py`) -- License detection from package metadata and files -- Compatibility matrix with 20+ license types -- Conflict detection engine with remediation suggestions -- Risk scoring based on distribution and usage context -- Export capabilities for legal review - -### Upgrade Planner (`upgrade_planner.py`) -- Semantic version analysis with breaking change prediction -- Dependency ordering based on risk and interdependence -- Migration checklists with testing recommendations -- Rollback procedures for failed upgrades -- Timeline estimation for upgrade cycles - -## Use Cases & Applications - -### Security Teams -- **Vulnerability Management**: Continuous scanning for security issues -- **Incident Response**: Rapid assessment of vulnerable dependencies -- **Supply Chain Monitoring**: Tracking third-party security posture -- **Compliance Reporting**: Automated security compliance documentation - -### Legal & Compliance Teams -- **License Auditing**: Comprehensive license compliance verification -- **Risk Assessment**: Legal risk analysis for software distribution -- **Due Diligence**: Dependency licensing for M&A activities -- **Policy Enforcement**: Automated license policy compliance - -### Development Teams -- **Dependency Hygiene**: Regular cleanup of unused dependencies -- **Upgrade Planning**: Strategic dependency update scheduling -- **Performance Optimization**: Bundle size optimization through dep analysis -- **Technical Debt**: Identifying and prioritizing dependency technical debt - -### DevOps & Platform Teams -- **Build Optimization**: Faster builds through dependency optimization -- **Security Automation**: Automated vulnerability scanning in CI/CD -- **Environment Consistency**: Ensuring consistent dependencies across environments -- **Release Management**: Dependency-aware release planning - -## Integration Patterns - -### CI/CD Pipeline Integration -```bash -# Security gate in CI -python dep_scanner.py /project --format json --fail-on-high -python license_checker.py /project --policy strict --format json -``` - -### Scheduled Audits -```bash -# Weekly dependency audit -./audit_dependencies.sh > weekly_report.html -python upgrade_planner.py deps.json --timeline 30days -``` - -### Development Workflow -```bash -# Pre-commit dependency check -python dep_scanner.py . --quick-scan -python license_checker.py . --warn-conflicts -``` - -## Advanced Features - -### Custom Vulnerability Databases -- Support for internal/proprietary vulnerability feeds -- Custom CVE pattern definitions -- Organization-specific risk scoring -- Integration with enterprise security tools - -### Policy-Based Scanning -- Configurable license policies by project type -- Custom risk thresholds and escalation rules -- Automated policy enforcement and notifications -- Exception management for approved violations - -### Reporting & Dashboards -- Executive summaries for management -- Technical reports for development teams -- Trend analysis and dependency health metrics -- Integration with project management tools - -### Multi-Project Analysis -- Portfolio-level dependency analysis -- Shared dependency impact analysis -- Organization-wide license compliance -- Cross-project vulnerability propagation - -## Best Practices - -### Scanning Frequency -- **Security Scans**: Daily or on every commit -- **License Audits**: Weekly or monthly -- **Upgrade Planning**: Monthly or quarterly -- **Full Dependency Audit**: Quarterly - -### Risk Management -1. **Prioritize Security**: Address high/critical CVEs immediately -2. **License First**: Ensure compliance before functionality -3. **Gradual Updates**: Incremental dependency updates -4. **Test Thoroughly**: Comprehensive testing after updates -5. **Monitor Continuously**: Automated monitoring and alerting - -### Team Workflows -1. **Security Champions**: Designate dependency security owners -2. **Review Process**: Mandatory review for new dependencies -3. **Update Cycles**: Regular, scheduled dependency updates -4. **Documentation**: Maintain dependency rationale and decisions -5. **Training**: Regular team education on dependency security - -## Metrics & KPIs - -### Security Metrics -- Mean Time to Patch (MTTP) for vulnerabilities -- Number of high/critical vulnerabilities -- Percentage of dependencies with known vulnerabilities -- Security debt accumulation rate - -### Compliance Metrics -- License compliance percentage -- Number of license conflicts -- Time to resolve compliance issues -- Policy violation frequency - -### Maintenance Metrics -- Percentage of up-to-date dependencies -- Average dependency age -- Number of abandoned dependencies -- Upgrade success rate - -### Efficiency Metrics -- Bundle size reduction percentage -- Unused dependency elimination rate -- Build time improvement -- Developer productivity impact - -## Troubleshooting Guide - -### Common Issues -1. **False Positives**: Tuning vulnerability detection sensitivity -2. **License Ambiguity**: Resolving unclear or multiple licenses -3. **Breaking Changes**: Managing major version upgrades -4. **Performance Impact**: Optimizing scanning for large codebases - -### Resolution Strategies -- Whitelist false positives with documentation -- Contact maintainers for license clarification -- Implement feature flags for risky upgrades -- Use incremental scanning for large projects - -## Future Enhancements - -### Planned Features -- Machine learning for vulnerability prediction -- Automated dependency update pull requests -- Integration with container image scanning -- Real-time dependency monitoring dashboards -- Natural language policy definition - -### Ecosystem Expansion -- Additional language support (Swift, Kotlin, Dart) -- Container and infrastructure dependencies -- Development tool and build system dependencies -- Cloud service and SaaS dependency tracking - ---- +Offline, deterministic dependency auditing across 8+ package ecosystems. The three scripts are pattern-matchers over manifests/lockfiles — they do **not** call live advisory APIs; pair their findings with `npm audit` / `pip-audit` / `cargo audit` for current CVE coverage. ## Quick Start ```bash -# Scan project for vulnerabilities and licenses -python scripts/dep_scanner.py /path/to/project +# 1. Scan for vulnerabilities (built-in offline CVE pattern set; exit non-zero on high severity) +python3 scripts/dep_scanner.py /path/to/project --format json --fail-on-high -o scan.json -# Check license compliance -python scripts/license_checker.py /path/to/project --policy strict +# 2. Check license compliance and conflicts +python3 scripts/license_checker.py /path/to/project --policy strict --format json -o licenses.json -# Plan dependency upgrades -python scripts/upgrade_planner.py deps.json --risk-threshold medium +# 3. Plan upgrades from the scanner's inventory +python3 scripts/upgrade_planner.py scan.json --risk-threshold medium --timeline 90 --format json -o plan.json ``` -For detailed usage instructions, see [README.md](https://github.com/alirezarezvani/claude-skills/tree/main/engineering/skills/dependency-auditor/README.md). +Consume the outputs: `scan.json` findings drive which packages to pin/patch now; `licenses.json` conflicts go to the user as a legal-risk list; `plan.json` orders upgrades by risk with rollback notes. `--quick-scan` skips transitive deps; `--security-only` limits the plan to security fixes. ---- +**Verification loop:** after applying upgrades, re-run step 1 and assert 0 high-severity findings before closing the audit. -*This skill provides comprehensive dependency management capabilities essential for maintaining secure, compliant, and efficient software projects. Regular use helps teams stay ahead of security threats, maintain legal compliance, and optimize their dependency ecosystems.* \ No newline at end of file +## Supported Ecosystems + +| Language | Manifests parsed | +|---|---| +| JavaScript/Node | package.json, package-lock.json, yarn.lock | +| Python | requirements.txt, pyproject.toml, Pipfile.lock, poetry.lock | +| Go | go.mod, go.sum | +| Rust | Cargo.toml, Cargo.lock | +| Ruby | Gemfile, Gemfile.lock | +| Java | pom.xml, gradle.lockfile | +| PHP | composer.json, composer.lock | +| C#/.NET | packages.config, project.assets.json | + +## License Classification + +- **Permissive**: MIT, Apache 2.0, BSD (2/3-clause), ISC +- **Copyleft (strong)**: GPL v2/v3, AGPL v3 — flags contamination risk in permissive projects +- **Copyleft (weak)**: LGPL v2.1/v3, MPL 2.0 +- **Proprietary / Dual / Unknown** — unknown licenses are surfaced for manual review + +The checker analyzes license inheritance through dependency chains and emits conflict pairs with remediation suggestions. + +## Upgrade Risk Matrix + +| Risk | Update type | Handling | +|---|---|---| +| Low | Patch, security fixes | Apply immediately | +| Medium | Minor with new features | Batch into scheduled update | +| High | Major version, API changes | Dedicated migration task + tests | +| Critical | Known breaking changes | Planned migration with rollback procedure | + +Prioritization: security patches > bug fixes > feature updates > major rewrites; deprecated features get immediate attention. + +## Scripts (accurate capability claims) + +- **`scripts/dep_scanner.py`** — multi-format parser; built-in offline vulnerability pattern set (~16 CVE patterns — a smoke layer, not a replacement for live advisories); transitive resolution from lockfiles; JSON + text output. +- **`scripts/license_checker.py`** — license detection from package metadata; compatibility matrix across 20+ license types; `--policy permissive|strict`; conflict detection with remediation. +- **`scripts/upgrade_planner.py`** — semver-based breaking-change prediction; risk-ordered migration plan with testing checklist and timeline estimation. + +Sample fixtures: `test-project/` and `test-inventory.json` in this folder; expected shapes in `expected_outputs/`. + +## CI Integration + +```bash +# Security gate in CI +python3 scripts/dep_scanner.py . --format json --fail-on-high +python3 scripts/license_checker.py . --policy strict --format json +``` + +## Best Practices + +1. **Prioritize security**: address high/critical findings immediately; license compliance before functionality. +2. **Gradual updates**: incremental upgrades with thorough testing; feature flags for risky bumps. +3. **Cadence**: security scans per commit; license audits monthly; full audit quarterly. +4. **False positives**: whitelist with documentation; contact maintainers for license ambiguity. + +See [README.md](https://github.com/alirezarezvani/claude-skills/tree/main/engineering/skills/dependency-auditor/README.md) for detailed usage and `references/` for the vulnerability/license knowledge bases. diff --git a/docs/skills/engineering/engineering-advanced-skills.md b/docs/skills/engineering/engineering-advanced-skills.md index d4793f2d..ad2307a1 100644 --- a/docs/skills/engineering/engineering-advanced-skills.md +++ b/docs/skills/engineering/engineering-advanced-skills.md @@ -1,6 +1,6 @@ --- title: "Engineering Advanced Skills (POWERFUL Tier) — Agent Skill for Codex & OpenClaw" -description: "25 advanced engineering agent skills and plugins for Claude Code, Codex, Gemini CLI, Cursor, OpenClaw. Agent design, RAG, MCP servers, CI/CD." +description: "Index of 37 advanced engineering agent skills for Claude Code, Codex, Gemini CLI, Cursor, OpenClaw. Use when browsing or choosing among the." --- # Engineering Advanced Skills (POWERFUL Tier) @@ -16,13 +16,13 @@ description: "25 advanced engineering agent skills and plugins for Claude Code, </div> -25 advanced engineering skills for complex architecture, automation, and platform operations. +37 advanced engineering skills for complex architecture, automation, reliability, and platform operations. ## Quick Start ### Claude Code ``` -/read engineering/agent-designer/SKILL.md +/read engineering/skills/agent-designer/SKILL.md ``` ### Codex CLI @@ -34,31 +34,45 @@ npx agent-skills-cli add alirezarezvani/claude-skills/engineering | Skill | Folder | Focus | |-------|--------|-------| -| Agent Designer | `agent-designer/` | Multi-agent architecture patterns | -| Agent Workflow Designer | `agent-workflow-designer/` | Workflow orchestration | +| Agent Designer | `agent-designer/` | Multi-agent architecture: plan, schema-generate, evaluate | +| Agent Workflow Designer | `agent-workflow-designer/` | Workflow orchestration scaffolds | | API Design Reviewer | `api-design-reviewer/` | REST/GraphQL linting, breaking changes | | API Test Suite Builder | `api-test-suite-builder/` | API test generation | -| Changelog Generator | `changelog-generator/` | Automated changelogs | +| Browser Automation | `browser-automation/` | Playwright/Selenium automation patterns | +| Changelog Generator | `changelog-generator/` | Changelogs, semantic version bumps, hotfix/rollback discipline | +| Chaos Engineering | `chaos-engineering/` | Experiment design, blast-radius, postmortems | | CI/CD Pipeline Builder | `ci-cd-pipeline-builder/` | Pipeline generation | | Codebase Onboarding | `codebase-onboarding/` | New dev onboarding guides | -| Database Designer | `database-designer/` | Schema design, migrations | +| Database Designer | `database-designer/` | Schema analysis, index optimization, migrations | | Database Schema Designer | `database-schema-designer/` | ERD, normalization | | Dependency Auditor | `dependency-auditor/` | Dependency security scanning | | Env Secrets Manager | `env-secrets-manager/` | Secrets rotation, vault | +| Feature Flags Architect | `feature-flags-architect/` | Flag debt, rollout plans, kill switches | +| Focused Fix | `focused-fix/` | Systematic feature/module repair | +| Full Page Screenshot | `full-page-screenshot/` | Full-page capture tooling | | Git Worktree Manager | `git-worktree-manager/` | Parallel branch workflows | | Interview System Designer | `interview-system-designer/` | Hiring pipeline design | +| Kubernetes Operator | `kubernetes-operator/` | CRD validation, reconcile linting | | MCP Server Builder | `mcp-server-builder/` | MCP tool creation | | Migration Architect | `migration-architect/` | System migration planning | | Monorepo Navigator | `monorepo-navigator/` | Monorepo tooling | -| Observability Designer | `observability-designer/` | SLOs, alerts, dashboards | +| Observability Designer | `observability-designer/` | Dashboards, alert noise (SLOs → slo-architect) | | Performance Profiler | `performance-profiler/` | CPU, memory, load profiling | | PR Review Expert | `pr-review-expert/` | Pull request analysis | -| RAG Architect | `rag-architect/` | RAG system design | -| Release Manager | `release-manager/` | Release orchestration | +| RAG Architect | `rag-architect/` | RAG design, chunking, retrieval evaluation | | Runbook Generator | `runbook-generator/` | Operational runbooks | +| Secrets Vault Manager | `secrets-vault-manager/` | Vault patterns, HCL | +| Self-Eval | `self-eval/` | Honest work-quality scoring | +| Ship Gate | `ship-gate/` | Pre-production audit (89 checks) | | Skill Security Auditor | `skill-security-auditor/` | Skill vulnerability scanning | | Skill Tester | `skill-tester/` | Skill quality evaluation | -| Tech Debt Tracker | `tech-debt-tracker/` | Technical debt management | +| SLO Architect | `slo-architect/` | SLO/SLI design, error budgets, burn-rate alerts | +| Spec-Driven Workflow | `spec-driven-workflow/` | Spec-first development gates | +| SQL Database Assistant | `sql-database-assistant/` | Query optimization, 4 dialects | +| TC Tracker | `tc-tracker/` | Task context lifecycle + handoffs | +| Tech Debt Tracker | `tech-debt-tracker/` | Debt scan → prioritize → dashboard | + +Note: release management merged into `changelog-generator/` (version bumper + hotfix/rollback procedures live there now). ## Rules diff --git a/docs/skills/engineering/engineering.md b/docs/skills/engineering/engineering.md index 7408b4c4..98283d06 100644 --- a/docs/skills/engineering/engineering.md +++ b/docs/skills/engineering/engineering.md @@ -54,7 +54,6 @@ npx agent-skills-cli add alirezarezvani/claude-skills/engineering | Performance Profiler | `performance-profiler/` | CPU, memory, load profiling | | PR Review Expert | `pr-review-expert/` | Pull request analysis | | RAG Architect | `rag-architect/` | RAG system design | -| Release Manager | `release-manager/` | Release orchestration | | Runbook Generator | `runbook-generator/` | Operational runbooks | | Skill Security Auditor | `skill-security-auditor/` | Skill vulnerability scanning | | Skill Tester | `skill-tester/` | Skill quality evaluation | diff --git a/docs/skills/engineering/index.md b/docs/skills/engineering/index.md index bf9f6960..92e29b6f 100644 --- a/docs/skills/engineering/index.md +++ b/docs/skills/engineering/index.md @@ -1,13 +1,13 @@ --- title: "Engineering - POWERFUL Skills — Agent Skills & Codex Plugins" -description: "75 engineering - powerful skills — advanced agent-native skill and Claude Code plugin for AI agent design, infrastructure, and automation. Works with Claude Code, Codex CLI, Gemini CLI, and OpenClaw." +description: "74 engineering - powerful skills — advanced agent-native skill and Claude Code plugin for AI agent design, infrastructure, and automation. Works with Claude Code, Codex CLI, Gemini CLI, and OpenClaw." --- <div class="domain-header" markdown> # :material-rocket-launch: Engineering - POWERFUL -<p class="domain-count">75 skills in this domain</p> +<p class="domain-count">74 skills in this domain</p> </div> @@ -17,11 +17,11 @@ description: "75 engineering - powerful skills — advanced agent-native skill a <div class="grid cards" markdown> -- **[Agent Designer - Multi-Agent System Architecture](agent-designer.md)** +- **[Agent Designer — Multi-Agent System Architecture](agent-designer.md)** --- - Tier: POWERFUL + Design, schema-generate, and evaluate multi-agent systems with three deterministic tools. The scripts are the workflo... - **[Agent Workflow Designer](agent-workflow-designer.md)** @@ -71,12 +71,6 @@ description: "75 engineering - powerful skills — advanced agent-native skill a Tier: POWERFUL -- **[Claude Code Command Selection Guide](command-guide.md)** - - --- - - This skill helps you choose the most appropriate command, agent, or skill for different scenarios. - - **[Database Designer - POWERFUL Tier Skill](database-designer.md)** --- @@ -93,13 +87,13 @@ description: "75 engineering - powerful skills — advanced agent-native skill a --- - > Skill Type: POWERFUL + > Skill Type: POWERFUL · Category: Engineering · Domain: Dependency Management & Security - **[Engineering Advanced Skills (POWERFUL Tier)](engineering-advanced-skills.md)** --- - 25 advanced engineering skills for complex architecture, automation, and platform operations. + 37 advanced engineering skills for complex architecture, automation, reliability, and platform operations. - **[Env & Secrets Manager](env-secrets-manager.md)** @@ -179,17 +173,11 @@ description: "75 engineering - powerful skills — advanced agent-native skill a Tier: POWERFUL -- **[RAG Architect - POWERFUL](rag-architect.md)** +- **[RAG Architect](rag-architect.md)** --- - The RAG (Retrieval-Augmented Generation) Architect skill provides comprehensive tools and knowledge for designing, im... - -- **[Release Manager](release-manager.md)** - - --- - - Tier: POWERFUL + Design, tune, and evaluate production RAG pipelines with three deterministic tools. Run the tools against the actual ... - **[Runbook Generator](runbook-generator.md)** @@ -225,7 +213,7 @@ description: "75 engineering - powerful skills — advanced agent-native skill a --- - --- + Tier: POWERFUL · Category: Engineering Quality Assurance · Dependencies: None (Python stdlib only) - **[SLO Architect](slo-architect.md)** @@ -257,10 +245,4 @@ description: "75 engineering - powerful skills — advanced agent-native skill a Tier: POWERFUL 🔥 -- **[Universal Scraping Architect](universal-scraping-architect.md)** - - --- - - You are an expert web scraping and data extraction engineer. Your goal is to design complete, robust data pipelines w... - </div> diff --git a/docs/skills/engineering/migration-architect.md b/docs/skills/engineering/migration-architect.md index b3d8d049..afedba81 100644 --- a/docs/skills/engineering/migration-architect.md +++ b/docs/skills/engineering/migration-architect.md @@ -44,6 +44,25 @@ The Migration Architect skill provides comprehensive tools and methodologies for - **Service Rollback:** Plan service version rollbacks with traffic management - **Validation Checkpoints:** Define success criteria and rollback triggers +## Quick Start — plan → check compatibility → generate rollback + +All paths relative to this skill folder; sample inputs in `assets/`, expected shapes in `expected_outputs/`. + +```bash +# 1. Generate the migration plan from a spec (copy assets/sample_database_migration.json) +python3 scripts/migration_planner.py --input migration_spec.json --format json -o migration_plan.json + +# 2. Check schema/API compatibility — exits non-zero unless fully compatible (CI gate) +python3 scripts/compatibility_checker.py --before assets/database_schema_before.json --after assets/database_schema_after.json --type database --format json -o compatibility.json + +# 3. Generate the rollback runbook from the plan +python3 scripts/rollback_generator.py --input migration_plan.json --format both -o rollback_runbook +``` + +Outputs chain: `migration_plan.json` (`phases`, `risks`, `estimated_duration_hours`) feeds step 3; `compatibility.json` reports `overall_compatibility` plus `breaking_changes_count` / `potentially_breaking_count`. + +**Gate:** the migration is not approved until (a) `compatibility_checker` exits 0 (`overall_compatibility: compatible`) or every breaking/potentially-breaking item is explicitly accepted by the owner in writing, and (b) a rollback runbook exists for every phase in the plan. Re-run both checks after any schema revision. + ## Migration Patterns ### Database Migrations @@ -349,74 +368,6 @@ class MigrationCircuitBreaker: - [ ] Archive migration artifacts - [ ] Update disaster recovery procedures -## Communication Templates - -### Executive Summary Template -``` -Migration Status: [IN_PROGRESS | COMPLETED | ROLLED_BACK] -Start Time: [YYYY-MM-DD HH:MM UTC] -Current Phase: [X of Y] -Overall Progress: [X%] - -Key Metrics: -- System Availability: [X.XX%] -- Data Migration Progress: [X.XX%] -- Performance Impact: [+/-X%] -- Issues Encountered: [X] - -Next Steps: -1. [Action item 1] -2. [Action item 2] - -Risk Assessment: [LOW | MEDIUM | HIGH] -Rollback Status: [AVAILABLE | NOT_AVAILABLE] -``` - -### Technical Team Update Template -``` -Phase: [Phase Name] - [Status] -Duration: [Started] - [Expected End] - -Completed Tasks: -✓ [Task 1] -✓ [Task 2] - -In Progress: -🔄 [Task 3] - [X% complete] - -Upcoming: -⏳ [Task 4] - [Expected start time] - -Issues: -⚠️ [Issue description] - [Severity] - [ETA resolution] - -Metrics: -- Migration Rate: [X records/minute] -- Error Rate: [X.XX%] -- System Load: [CPU/Memory/Disk] -``` - -## Success Metrics - -### Technical Metrics -- **Migration Completion Rate:** Percentage of data/services successfully migrated -- **Downtime Duration:** Total system unavailability during migration -- **Data Consistency Score:** Percentage of data validation checks passing -- **Performance Delta:** Performance change compared to baseline -- **Error Rate:** Percentage of failed operations during migration - -### Business Metrics -- **Customer Impact Score:** Measure of customer experience degradation -- **Revenue Protection:** Percentage of revenue maintained during migration -- **Time to Value:** Duration from migration start to business value realization -- **Stakeholder Satisfaction:** Post-migration stakeholder feedback scores - -### Operational Metrics -- **Plan Adherence:** Percentage of migration executed according to plan -- **Issue Resolution Time:** Average time to resolve migration issues -- **Team Efficiency:** Resource utilization and productivity metrics -- **Knowledge Transfer Score:** Team readiness for post-migration operations - ## Tools and Technologies ### Migration Planning Tools diff --git a/docs/skills/engineering/observability-designer.md b/docs/skills/engineering/observability-designer.md index e7d0bd46..274d03fa 100644 --- a/docs/skills/engineering/observability-designer.md +++ b/docs/skills/engineering/observability-designer.md @@ -22,7 +22,26 @@ description: "Design production-ready observability strategies combining metrics ## Overview -Observability Designer enables you to create production-ready observability strategies that provide deep insights into system behavior, performance, and reliability. This skill combines the three pillars of observability (metrics, logs, traces) with proven frameworks like SLI/SLO design, golden signals monitoring, and alert optimization to create comprehensive observability solutions. +Observability Designer creates production-ready dashboards, alert configurations, and monitoring strategies across the three pillars (metrics, logs, traces). + +**When NOT to use → slo-architect.** For SLO/SLI design with error-budget math, multi-window burn-rate alerting thresholds, and SLO review gates, route to `slo-architect` — it is the authoritative skill for that half. This skill's `slo_designer.py` produces a quick scaffold only. This skill's lane: dashboards (`dashboard_generator.py`) and alert-noise reduction (`alert_optimizer.py`). + +## Quick Start + +```bash +# Dashboard spec (Grafana JSON + docs) for a service +python3 scripts/dashboard_generator.py --service-type api --name payments --criticality critical --role sre --format grafana -o dashboard.json --doc-output dashboard.md + +# Analyze an existing alert config for noise, duplicates, and coverage gaps +python3 scripts/alert_optimizer.py --input alerts.json --analyze-only --report alert_report.json +# ...then emit the optimized config once the report is reviewed: +python3 scripts/alert_optimizer.py --input alerts.json --output alerts_optimized.json + +# Quick SLO scaffold (hand off to slo-architect for the real error-budget work) +python3 scripts/slo_designer.py --service-type api --criticality high --user-facing true --service-name payments -o slo_scaffold.json +``` + +**Verification loop:** after deploying optimized alerts, track the report's noise metrics for one on-call rotation — if the actionable-alert ratio didn't improve, re-run `--analyze-only` against the live config and iterate. Import the generated dashboard into Grafana and confirm every golden-signal panel renders with live data before closing the task. ## Core Competencies @@ -262,19 +281,3 @@ Creates comprehensive dashboard specifications: - **Alert Tuning:** Ongoing alert threshold and routing optimization - **Dashboard Evolution:** User feedback-driven dashboard improvements - **Tool Evaluation:** Regular assessment of observability tool effectiveness - -## Success Metrics - -### Operational Metrics -- **Mean Time to Detection (MTTD):** How quickly issues are identified -- **Mean Time to Resolution (MTTR):** Time from detection to resolution -- **Alert Precision:** Percentage of actionable alerts -- **SLO Achievement:** Percentage of SLO targets met consistently - -### Business Metrics -- **System Reliability:** Overall uptime and user experience quality -- **Engineering Velocity:** Development team productivity and deployment frequency -- **Cost Efficiency:** Observability cost as percentage of infrastructure spend -- **Customer Satisfaction:** User-reported reliability and performance satisfaction - -This comprehensive observability design skill enables organizations to build robust, scalable monitoring and alerting systems that provide actionable insights while maintaining cost efficiency and operational excellence. \ No newline at end of file diff --git a/docs/skills/engineering/pr-review-expert.md b/docs/skills/engineering/pr-review-expert.md index 868728dd..393e07ff 100644 --- a/docs/skills/engineering/pr-review-expert.md +++ b/docs/skills/engineering/pr-review-expert.md @@ -258,20 +258,33 @@ grep -n "new Array([0-9]\{4,\}\|Buffer\.alloc" /tmp/pr-$PR.diff | grep "^+" gh pr view $PR --json body | jq -r '.body' | \ grep -oE "(PROJ-[0-9]+|[A-Z]+-[0-9]+|https://linear\.app/[^)\"]+)" | sort -u -# Verify Jira ticket exists (requires JIRA_API_TOKEN) +# Verify Jira ticket exists (requires JIRA_API_TOKEN to be SET in the environment). +# Credentials are fed to curl via a config read from stdin (-K -) so the token +# never appears in argv — `ps aux` / /proc/*/cmdline can't see it, and nothing +# secret lands in shell history. Never paste the raw token on the command line. TICKET="PROJ-123" -curl -s -u "user@company.com:$JIRA_API_TOKEN" \ - "https://your-org.atlassian.net/rest/api/3/issue/$TICKET" | \ +: "${JIRA_API_TOKEN:?JIRA_API_TOKEN must be set}" +curl -s -K - "https://your-org.atlassian.net/rest/api/3/issue/$TICKET" <<EOF | \ jq '{key, summary: .fields.summary, status: .fields.status.name}' +user = "user@company.com:$JIRA_API_TOKEN" +EOF -# Linear ticket +# Linear ticket — same pattern: the Authorization header goes through the +# stdin config, not a -H flag, to keep the key out of the process list. LINEAR_ID="abc-123" -curl -s -H "Authorization: $LINEAR_API_KEY" \ - -H "Content-Type: application/json" \ +: "${LINEAR_API_KEY:?LINEAR_API_KEY must be set}" +curl -s -K - -H "Content-Type: application/json" \ --data "{\"query\": \"{ issue(id: \\\"$LINEAR_ID\\\") { title state { name } } }\"}" \ - https://api.linear.app/graphql | jq . + https://api.linear.app/graphql <<EOF | jq . +header = "Authorization: $LINEAR_API_KEY" +EOF ``` +> **Security note:** for repeated Jira use, prefer a `~/.netrc` entry +> (`machine your-org.atlassian.net login user@company.com password <token>`, +> `chmod 600 ~/.netrc`) and call `curl -s --netrc …` — no secret material in +> the command at all. + --- ## Complete Review Checklist (30+ Items) diff --git a/docs/skills/engineering/rag-architect.md b/docs/skills/engineering/rag-architect.md index 99777ce8..5ef2eecd 100644 --- a/docs/skills/engineering/rag-architect.md +++ b/docs/skills/engineering/rag-architect.md @@ -1,6 +1,6 @@ --- title: "RAG Architect — Agent Skill for Codex & OpenClaw" -description: "Use when the user asks to design RAG pipelines, optimize retrieval strategies, choose embedding models, implement vector search, or build knowledge. Agent skill for Claude Code, Codex CLI, Gemini CLI, OpenClaw." +description: "Use when the user asks to design a RAG pipeline, choose a chunking strategy or embedding model, pick a vector database, or evaluate retrieval quality. Agent skill for Claude Code, Codex CLI, Gemini CLI, OpenClaw." --- # RAG Architect @@ -16,314 +16,67 @@ description: "Use when the user asks to design RAG pipelines, optimize retrieval </div> -## Overview +Design, tune, and evaluate production RAG pipelines with three deterministic tools. Run the tools against the actual corpus and requirements — do not pick chunk sizes or databases by intuition. -The RAG (Retrieval-Augmented Generation) Architect skill provides comprehensive tools and knowledge for designing, implementing, and optimizing production-grade RAG pipelines. This skill covers the entire RAG ecosystem from document chunking strategies to evaluation frameworks, enabling you to build scalable, efficient, and accurate retrieval systems. +## Hard rules -## Core Competencies +1. **Never present model names or vendor prices as current facts.** Embedding models and vector-DB pricing rot in months. Recommend a *tier* (see table below), name a current-generation candidate, and tell the user to verify against the provider's live pricing page. +2. **Every design ends with an evaluation run.** A RAG design without `retrieval_evaluator.py` numbers is a hypothesis, not a deliverable. +3. **Chunking is corpus-driven.** Run `chunking_optimizer.py` on the real documents before choosing a strategy. -### 1. Document Processing & Chunking Strategies +## Embedding model tiers (pattern, not price list) -#### Fixed-Size Chunking -- **Character-based chunking**: Simple splitting by character count (e.g., 512, 1024, 2048 chars) -- **Token-based chunking**: Splitting by token count to respect model limits -- **Overlap strategies**: 10-20% overlap to maintain context continuity -- **Pros**: Predictable chunk sizes, simple implementation, consistent processing time -- **Cons**: May break semantic units, context boundaries ignored -- **Best for**: Uniform documents, when consistent chunk sizes are critical +| Tier | Current-generation examples (verify before use) | When | +|---|---|---| +| Fast / self-hosted | `all-MiniLM-L6-v2`, `bge-small` | Cost-sensitive, small scale, real-time | +| Balanced open | `all-mpnet-base-v2`, `bge-large`, `e5-large` | Quality without API dependency | +| Quality API | `text-embedding-3-large`, `voyage-3-large` | Accuracy-priority general retrieval | +| Code | `voyage-code-3`, CodeBERT-family | Code search corpora | -#### Sentence-Based Chunking -- **Sentence boundary detection**: Using NLTK, spaCy, or regex patterns -- **Sentence grouping**: Combining sentences until size threshold is reached -- **Paragraph preservation**: Avoiding mid-paragraph splits when possible -- **Pros**: Preserves natural language boundaries, better readability -- **Cons**: Variable chunk sizes, potential for very short/long chunks -- **Best for**: Narrative text, articles, books +**Pricing discipline:** build the cost model with a placeholder table — columns `model | $/1M tokens (verify) | dims | as-of date` — and have the user fill in live numbers. Same for vector DBs (Pinecone/Weaviate/Qdrant/Chroma/pgvector): the selection criteria (managed vs self-hosted, scale, filtering, existing Postgres) are durable; the dollar figures are not. -#### Paragraph-Based Chunking -- **Paragraph detection**: Double newlines, HTML tags, markdown formatting -- **Hierarchical splitting**: Respecting document structure (sections, subsections) -- **Size balancing**: Merging small paragraphs, splitting large ones -- **Pros**: Preserves logical document structure, maintains topic coherence -- **Cons**: Highly variable sizes, may create very large chunks -- **Best for**: Structured documents, technical documentation +## Workflow -#### Semantic Chunking -- **Topic modeling**: Using TF-IDF, embeddings similarity for topic detection -- **Heading-aware splitting**: Respecting document hierarchy (H1, H2, H3) -- **Content-based boundaries**: Detecting topic shifts using semantic similarity -- **Pros**: Maintains semantic coherence, respects document structure -- **Cons**: Complex implementation, computationally expensive -- **Best for**: Long-form content, technical manuals, research papers +All paths relative to this skill folder. Outputs chain: corpus analysis → design → evaluation. -#### Recursive Chunking -- **Hierarchical approach**: Try larger chunks first, recursively split if needed -- **Multi-level splitting**: Different strategies at different levels -- **Size optimization**: Minimize number of chunks while respecting size limits -- **Pros**: Optimal chunk utilization, preserves context when possible -- **Cons**: Complex logic, potential performance overhead -- **Best for**: Mixed content types, when chunk count optimization is important +### 1. Analyze the corpus and pick chunking -#### Document-Aware Chunking -- **File type detection**: PDF pages, Word sections, HTML elements -- **Metadata preservation**: Headers, footers, page numbers, sections -- **Table and image handling**: Special processing for non-text elements -- **Pros**: Preserves document structure and metadata -- **Cons**: Format-specific implementation required -- **Best for**: Multi-format document collections, when metadata is important +```bash +python3 chunking_optimizer.py /path/to/docs --extensions .md .txt -o chunking.json +``` -### 2. Embedding Model Selection +Emits `chunking.json` with `corpus_info`, per-strategy `strategy_results`, a `recommendation`, and `sample_chunks`. Use `recommendation.strategy` and its config; show the user 2-3 `sample_chunks` so they can sanity-check boundaries. -#### Dimension Considerations -- **128-256 dimensions**: Fast retrieval, lower memory usage, suitable for simple domains -- **512-768 dimensions**: Balanced performance, good for most applications -- **1024-1536 dimensions**: High quality, better for complex domains, higher cost -- **2048+ dimensions**: Maximum quality, specialized use cases, significant resources +### 2. Design the pipeline from requirements -#### Speed vs Quality Tradeoffs -- **Fast models**: sentence-transformers/all-MiniLM-L6-v2 (384 dim, ~14k tokens/sec) -- **Balanced models**: sentence-transformers/all-mpnet-base-v2 (768 dim, ~2.8k tokens/sec) -- **Quality models**: text-embedding-ada-002 (1536 dim, OpenAI API) -- **Specialized models**: Domain-specific fine-tuned models +Write a requirements JSON with these keys (all required): `document_types[]`, `document_count`, `avg_document_size` (chars), `queries_per_day`, `query_patterns[]`, `latency_requirement`, `budget_monthly`, `accuracy_priority` (0-1), `cost_priority` (0-1), `maintenance_complexity`. -#### Model Categories -- **General purpose**: all-MiniLM, all-mpnet, Universal Sentence Encoder -- **Code embeddings**: CodeBERT, GraphCodeBERT, CodeT5 -- **Scientific text**: SciBERT, BioBERT, ClinicalBERT -- **Multilingual**: LaBSE, multilingual-e5, paraphrase-multilingual +```bash +python3 rag_pipeline_designer.py requirements.json -o design.json +``` -### 3. Vector Database Selection +Emits `design.json` with `chunking`, `embedding`, `vector_db`, `retrieval`, `reranking`, `evaluation`, `total_cost`, `architecture_diagram` (mermaid), and `config_templates`. Present the diagram; label every `cost_monthly` figure as an estimate to verify (rule 1). -#### Pinecone -- **Managed service**: Fully hosted, auto-scaling -- **Features**: Metadata filtering, hybrid search, real-time updates -- **Pricing**: $70/month for 1M vectors (1536 dim), pay-per-use scaling -- **Best for**: Production applications, when managed service is preferred -- **Cons**: Vendor lock-in, costs can scale quickly +### 3. Evaluate retrieval quality -#### Weaviate -- **Open source**: Self-hosted or cloud options available -- **Features**: GraphQL API, multi-modal search, automatic vectorization -- **Scaling**: Horizontal scaling, HNSW indexing -- **Best for**: Complex data types, when GraphQL API is preferred -- **Cons**: Learning curve, requires infrastructure management +Prepare `queries.json` (list of `{id, text}` or `{"queries": [...]}`) and `ground_truth.json` (`{query_id: [relevant_doc_ids]}`), then: -#### Qdrant -- **Rust-based**: High performance, low memory footprint -- **Features**: Payload filtering, clustering, distributed deployment -- **API**: REST and gRPC interfaces -- **Best for**: High-performance requirements, resource-constrained environments -- **Cons**: Smaller community, fewer integrations +```bash +python3 retrieval_evaluator.py queries.json /path/to/docs ground_truth.json --k-values 3 5 10 -o eval.json +``` -#### Chroma -- **Embedded database**: SQLite-based, easy local development -- **Features**: Collections, metadata filtering, persistence -- **Scaling**: Limited, suitable for prototyping and small deployments -- **Best for**: Development, testing, small-scale applications -- **Cons**: Not suitable for production scale +Reports precision@k, recall@k, MRR, NDCG@k, plus `poor_precision_examples` / `poor_recall_examples` for failure analysis. -#### pgvector (PostgreSQL) -- **SQL integration**: Leverage existing PostgreSQL infrastructure -- **Features**: ACID compliance, joins with relational data, mature ecosystem -- **Performance**: ivfflat and HNSW indexing, parallel query processing -- **Best for**: When you already use PostgreSQL, need ACID compliance -- **Cons**: Requires PostgreSQL expertise, less specialized than purpose-built DBs +### 4. Verification loop -### 4. Retrieval Strategies +The design is done only when: -#### Dense Retrieval -- **Semantic similarity**: Using embedding cosine similarity -- **Advantages**: Captures semantic meaning, handles paraphrasing well -- **Limitations**: May miss exact keyword matches, requires good embeddings -- **Implementation**: Vector similarity search with k-NN or ANN algorithms +1. `eval.json` meets targets — typical floors: precision@5 ≥ 0.8, recall@10 ≥ 0.85 (set per use case with the user). +2. If below target: inspect the poor-example lists, then change **one** variable (chunking strategy → re-run step 1; embedding tier; add reranking; hybrid retrieval) and re-run step 3. Repeat. +3. Every recommended model/price in the deliverable carries a "verify current pricing/model availability" note with an as-of date. -#### Sparse Retrieval -- **Keyword-based**: TF-IDF, BM25, Elasticsearch -- **Advantages**: Exact keyword matching, interpretable results -- **Limitations**: Misses semantic similarity, vulnerable to vocabulary mismatch -- **Implementation**: Inverted indexes, term frequency analysis +## References -#### Hybrid Retrieval -- **Combination approach**: Dense + sparse retrieval with score fusion -- **Fusion strategies**: Reciprocal Rank Fusion (RRF), weighted combination -- **Benefits**: Combines semantic understanding with exact matching -- **Complexity**: Requires tuning fusion weights, more complex infrastructure - -#### Reranking -- **Two-stage approach**: Initial retrieval followed by reranking -- **Reranking models**: Cross-encoders, specialized reranking transformers -- **Benefits**: Higher precision, can use more sophisticated models for final ranking -- **Tradeoff**: Additional latency, computational cost - -### 5. Query Transformation Techniques - -#### HyDE (Hypothetical Document Embeddings) -- **Approach**: Generate hypothetical answer, embed answer instead of query -- **Benefits**: Improves retrieval by matching document style rather than query style -- **Implementation**: Use LLM to generate hypothetical document, embed that -- **Use cases**: When queries and documents have different styles - -#### Multi-Query Generation -- **Approach**: Generate multiple query variations, retrieve for each, merge results -- **Benefits**: Increases recall, handles query ambiguity -- **Implementation**: LLM generates 3-5 query variations, deduplicate results -- **Considerations**: Higher cost and latency due to multiple retrievals - -#### Step-Back Prompting -- **Approach**: Generate broader, more general version of specific query -- **Benefits**: Retrieves more general context that helps answer specific questions -- **Implementation**: Transform "What is the capital of France?" to "What are European capitals?" -- **Use cases**: When specific questions need general context - -### 6. Context Window Optimization - -#### Dynamic Context Assembly -- **Relevance-based ordering**: Most relevant chunks first -- **Diversity optimization**: Avoid redundant information -- **Token budget management**: Fit within model context limits -- **Hierarchical inclusion**: Include summaries before detailed chunks - -#### Context Compression -- **Summarization**: Compress less relevant chunks while preserving key information -- **Key information extraction**: Extract only relevant facts/entities -- **Template-based compression**: Use structured formats to reduce token usage -- **Selective inclusion**: Include only chunks above relevance threshold - -### 7. Evaluation Frameworks - -#### Faithfulness Metrics -- **Definition**: How well generated answers are grounded in retrieved context -- **Measurement**: Fact verification against source documents -- **Implementation**: NLI models to check entailment between answer and context -- **Threshold**: >90% for production systems - -#### Relevance Metrics -- **Context relevance**: How relevant retrieved chunks are to the query -- **Answer relevance**: How well the answer addresses the original question -- **Measurement**: Embedding similarity, human evaluation, LLM-as-judge -- **Targets**: Context relevance >0.8, Answer relevance >0.85 - -#### Context Precision & Recall -- **Precision@K**: Percentage of top-K results that are relevant -- **Recall@K**: Percentage of relevant documents found in top-K results -- **Mean Reciprocal Rank (MRR)**: Average of reciprocal ranks of first relevant result -- **NDCG@K**: Normalized Discounted Cumulative Gain at K - -#### End-to-End Metrics -- **RAGAS**: Comprehensive RAG evaluation framework -- **Correctness**: Factual accuracy of generated answers -- **Completeness**: Coverage of all relevant aspects -- **Consistency**: Consistency across multiple runs with same query - -### 8. Production Patterns - -#### Caching Strategies -- **Query-level caching**: Cache results for identical queries -- **Semantic caching**: Cache for semantically similar queries -- **Chunk-level caching**: Cache embedding computations -- **Multi-level caching**: Redis for hot queries, disk for warm queries - -#### Streaming Retrieval -- **Progressive loading**: Stream results as they become available -- **Incremental generation**: Generate answers while still retrieving -- **Real-time updates**: Handle document updates without full reprocessing -- **Connection management**: Handle client disconnections gracefully - -#### Fallback Mechanisms -- **Graceful degradation**: Fallback to simpler retrieval if primary fails -- **Cache fallbacks**: Serve stale results when retrieval is unavailable -- **Alternative sources**: Multiple vector databases for redundancy -- **Error handling**: Comprehensive error recovery and user communication - -### 9. Cost Optimization - -#### Embedding Cost Management -- **Batch processing**: Batch documents for embedding to reduce API costs -- **Caching strategies**: Cache embeddings to avoid recomputation -- **Model selection**: Balance cost vs quality for embedding models -- **Update optimization**: Only re-embed changed documents - -#### Vector Database Optimization -- **Index optimization**: Choose appropriate index types for use case -- **Compression**: Use quantization to reduce storage costs -- **Tiered storage**: Hot/warm/cold data strategies -- **Resource scaling**: Auto-scaling based on query patterns - -#### Query Optimization -- **Query routing**: Route simple queries to cheaper methods -- **Result caching**: Avoid repeated expensive retrievals -- **Batch querying**: Process multiple queries together when possible -- **Smart filtering**: Use metadata filters to reduce search space - -### 10. Guardrails & Safety - -#### Content Filtering -- **Toxicity detection**: Filter harmful or inappropriate content -- **PII detection**: Identify and handle personally identifiable information -- **Content validation**: Ensure retrieved content meets quality standards -- **Source verification**: Validate document authenticity and reliability - -#### Query Safety -- **Injection prevention**: Prevent malicious query injection attacks -- **Rate limiting**: Prevent abuse and ensure fair usage -- **Query validation**: Sanitize and validate user inputs -- **Access controls**: Ensure users can only access authorized content - -#### Response Safety -- **Hallucination detection**: Identify when model generates unsupported claims -- **Confidence scoring**: Provide confidence levels for generated responses -- **Source attribution**: Always provide sources for factual claims -- **Uncertainty handling**: Gracefully handle cases where answer is uncertain - -## Implementation Best Practices - -### Development Workflow -1. **Requirements gathering**: Understand use case, scale, and quality requirements -2. **Data analysis**: Analyze document corpus characteristics -3. **Prototype development**: Build minimal viable RAG pipeline -4. **Chunking optimization**: Test different chunking strategies -5. **Retrieval tuning**: Optimize retrieval parameters and thresholds -6. **Evaluation setup**: Implement comprehensive evaluation metrics -7. **Production deployment**: Scale-ready implementation with monitoring - -### Monitoring & Observability -- **Query analytics**: Track query patterns and performance -- **Retrieval metrics**: Monitor precision, recall, and latency -- **Generation quality**: Track faithfulness and relevance scores -- **System health**: Monitor database performance and availability -- **Cost tracking**: Monitor embedding and vector database costs - -### Maintenance & Updates -- **Document refresh**: Handle new documents and updates -- **Index maintenance**: Regular vector database optimization -- **Model updates**: Evaluate and migrate to improved models -- **Performance tuning**: Continuous optimization based on usage patterns -- **Security updates**: Regular security assessments and updates - -## Common Pitfalls & Solutions - -### Poor Chunking Strategy -- **Problem**: Chunks break mid-sentence or lose context -- **Solution**: Use boundary-aware chunking with overlap - -### Low Retrieval Precision -- **Problem**: Retrieved chunks are not relevant to query -- **Solution**: Improve embedding model, add reranking, tune similarity threshold - -### High Latency -- **Problem**: Slow retrieval and generation -- **Solution**: Optimize vector indexing, implement caching, use faster embedding models - -### Inconsistent Quality -- **Problem**: Variable answer quality across different queries -- **Solution**: Implement comprehensive evaluation, add quality scoring, improve fallbacks - -### Scalability Issues -- **Problem**: System doesn't scale with increased load -- **Solution**: Implement proper caching, database sharding, and auto-scaling - -## Conclusion - -Building effective RAG systems requires careful consideration of each component in the pipeline. The key to success is understanding the tradeoffs between different approaches and choosing the right combination of techniques for your specific use case. Start with simple approaches and gradually add sophistication based on evaluation results and production requirements. - -This skill provides the foundation for making informed decisions throughout the RAG development lifecycle, from initial design to production deployment and ongoing maintenance. \ No newline at end of file +- `references/chunking_strategies_comparison.md` — strategy trade-offs the optimizer implements +- `references/embedding_model_benchmark.md` — benchmark *methodology* (dated snapshot; staleness warning at top) +- `references/rag_evaluation_framework.md` — metric definitions (faithfulness, relevance, precision/recall/NDCG) diff --git a/docs/skills/engineering/release-manager.md b/docs/skills/engineering/release-manager.md deleted file mode 100644 index 9dac1cd3..00000000 --- a/docs/skills/engineering/release-manager.md +++ /dev/null @@ -1,501 +0,0 @@ ---- -title: "Release Manager — Agent Skill for Codex & OpenClaw" -description: "Use when the user asks to plan releases, manage changelogs, coordinate deployments, create release branches, or automate versioning. Agent skill for Claude Code, Codex CLI, Gemini CLI, OpenClaw." ---- - -# Release Manager - -<div class="page-meta" markdown> -<span class="meta-badge">:material-rocket-launch: Engineering - POWERFUL</span> -<span class="meta-badge">:material-identifier: `release-manager`</span> -<span class="meta-badge">:material-github: <a href="https://github.com/alirezarezvani/claude-skills/tree/main/engineering/skills/release-manager/SKILL.md">Source</a></span> -</div> - -<div class="install-banner" markdown> -<span class="install-label">Install:</span> <code>claude /plugin install engineering-advanced-skills</code> -</div> - - -**Tier:** POWERFUL -**Category:** Engineering -**Domain:** Software Release Management & DevOps - -## Overview - -The Release Manager skill provides comprehensive tools and knowledge for managing software releases end-to-end. From parsing conventional commits to generating changelogs, determining version bumps, and orchestrating release processes, this skill ensures reliable, predictable, and well-documented software releases. - -## Core Capabilities - -- **Automated Changelog Generation** from git history using conventional commits -- **Semantic Version Bumping** based on commit analysis and breaking changes -- **Release Readiness Assessment** with comprehensive checklists and validation -- **Release Planning & Coordination** with stakeholder communication templates -- **Rollback Planning** with automated recovery procedures -- **Hotfix Management** for emergency releases -- **Feature Flag Integration** for progressive rollouts - -## Key Components - -### Scripts - -1. **changelog_generator.py** - Parses git logs and generates structured changelogs -2. **version_bumper.py** - Determines correct version bumps from conventional commits -3. **release_planner.py** - Assesses release readiness and generates coordination plans - -### Documentation - -- Comprehensive release management methodology -- Conventional commits specification and examples -- Release workflow comparisons (Git Flow, Trunk-based, GitHub Flow) -- Hotfix procedures and emergency response protocols - -## Release Management Methodology - -### Semantic Versioning (SemVer) - -Semantic Versioning follows the MAJOR.MINOR.PATCH format where: - -- **MAJOR** version when you make incompatible API changes -- **MINOR** version when you add functionality in a backwards compatible manner -- **PATCH** version when you make backwards compatible bug fixes - -#### Pre-release Versions - -Pre-release versions are denoted by appending a hyphen and identifiers: -- `1.0.0-alpha.1` - Alpha releases for early testing -- `1.0.0-beta.2` - Beta releases for wider testing -- `1.0.0-rc.1` - Release candidates for final validation - -#### Version Precedence - -Version precedence is determined by comparing each identifier: -1. `1.0.0-alpha` < `1.0.0-alpha.1` < `1.0.0-alpha.beta` < `1.0.0-beta` -2. `1.0.0-beta` < `1.0.0-beta.2` < `1.0.0-beta.11` < `1.0.0-rc.1` -3. `1.0.0-rc.1` < `1.0.0` - -### Conventional Commits - -Conventional Commits provide a structured format for commit messages that enables automated tooling: - -#### Format -``` -<type>[optional scope]: <description> - -[optional body] - -[optional footer(s)] -``` - -#### Types -- **feat**: A new feature (correlates with MINOR version bump) -- **fix**: A bug fix (correlates with PATCH version bump) -- **docs**: Documentation only changes -- **style**: Changes that do not affect the meaning of the code -- **refactor**: A code change that neither fixes a bug nor adds a feature -- **perf**: A code change that improves performance -- **test**: Adding missing tests or correcting existing tests -- **chore**: Changes to the build process or auxiliary tools -- **ci**: Changes to CI configuration files and scripts -- **build**: Changes that affect the build system or external dependencies -- **breaking**: Introduces a breaking change (correlates with MAJOR version bump) - -#### Examples -``` -feat(user-auth): add OAuth2 integration - -fix(api): resolve race condition in user creation - -docs(readme): update installation instructions - -feat!: remove deprecated payment API -BREAKING CHANGE: The legacy payment API has been removed -``` - -### Automated Changelog Generation - -Changelogs are automatically generated from conventional commits, organized by: - -#### Structure -```markdown -# Changelog - -## [Unreleased] -### Added -### Changed -### Deprecated -### Removed -### Fixed -### Security - -## [1.2.0] - 2024-01-15 -### Added -- OAuth2 authentication support (#123) -- User preference dashboard (#145) - -### Fixed -- Race condition in user creation (#134) -- Memory leak in image processing (#156) - -### Breaking Changes -- Removed legacy payment API -``` - -#### Grouping Rules -- **Added** for new features (feat) -- **Fixed** for bug fixes (fix) -- **Changed** for changes in existing functionality -- **Deprecated** for soon-to-be removed features -- **Removed** for now removed features -- **Security** for vulnerability fixes - -#### Metadata Extraction -- Link to pull requests and issues: `(#123)` -- Breaking changes highlighted prominently -- Scope-based grouping: `auth:`, `api:`, `ui:` -- Co-authored-by for contributor recognition - -### Version Bump Strategies - -Version bumps are determined by analyzing commits since the last release: - -#### Automatic Detection Rules -1. **MAJOR**: Any commit with `BREAKING CHANGE` or `!` after type -2. **MINOR**: Any `feat` type commits without breaking changes -3. **PATCH**: `fix`, `perf`, `security` type commits -4. **NO BUMP**: `docs`, `style`, `test`, `chore`, `ci`, `build` only - -#### Pre-release Handling -```python -# Alpha: 1.0.0-alpha.1 → 1.0.0-alpha.2 -# Beta: 1.0.0-alpha.5 → 1.0.0-beta.1 -# RC: 1.0.0-beta.3 → 1.0.0-rc.1 -# Release: 1.0.0-rc.2 → 1.0.0 -``` - -#### Multi-package Considerations -For monorepos with multiple packages: -- Analyze commits affecting each package independently -- Support scoped version bumps: `@scope/package@1.2.3` -- Generate coordinated release plans across packages - -### Release Branch Workflows - -#### Git Flow -``` -main (production) ← release/1.2.0 ← develop ← feature/login - ← hotfix/critical-fix -``` - -**Advantages:** -- Clear separation of concerns -- Stable main branch -- Parallel feature development -- Structured release process - -**Process:** -1. Create release branch from develop: `git checkout -b release/1.2.0 develop` -2. Finalize release (version bump, changelog) -3. Merge to main and develop -4. Tag release: `git tag v1.2.0` -5. Deploy from main - -#### Trunk-based Development -``` -main ← feature/login (short-lived) - ← feature/payment (short-lived) - ← hotfix/critical-fix -``` - -**Advantages:** -- Simplified workflow -- Faster integration -- Reduced merge conflicts -- Continuous integration friendly - -**Process:** -1. Short-lived feature branches (1-3 days) -2. Frequent commits to main -3. Feature flags for incomplete features -4. Automated testing gates -5. Deploy from main with feature toggles - -#### GitHub Flow -``` -main ← feature/login - ← hotfix/critical-fix -``` - -**Advantages:** -- Simple and lightweight -- Fast deployment cycle -- Good for web applications -- Minimal overhead - -**Process:** -1. Create feature branch from main -2. Regular commits and pushes -3. Open pull request when ready -4. Deploy from feature branch for testing -5. Merge to main and deploy - -### Feature Flag Integration - -Feature flags enable safe, progressive rollouts: - -#### Types of Feature Flags -- **Release flags**: Control feature visibility in production -- **Experiment flags**: A/B testing and gradual rollouts -- **Operational flags**: Circuit breakers and performance toggles -- **Permission flags**: Role-based feature access - -#### Implementation Strategy -```python -# Progressive rollout example -if feature_flag("new_payment_flow", user_id): - return new_payment_processor.process(payment) -else: - return legacy_payment_processor.process(payment) -``` - -#### Release Coordination -1. Deploy code with feature behind flag (disabled) -2. Gradually enable for percentage of users -3. Monitor metrics and error rates -4. Full rollout or quick rollback based on data -5. Remove flag in subsequent release - -### Release Readiness Checklists - -#### Pre-Release Validation -- [ ] All planned features implemented and tested -- [ ] Breaking changes documented with migration guide -- [ ] API documentation updated -- [ ] Database migrations tested -- [ ] Security review completed for sensitive changes -- [ ] Performance testing passed thresholds -- [ ] Internationalization strings updated -- [ ] Third-party integrations validated - -#### Quality Gates -- [ ] Unit test coverage ≥ 85% -- [ ] Integration tests passing -- [ ] End-to-end tests passing -- [ ] Static analysis clean -- [ ] Security scan passed -- [ ] Dependency audit clean -- [ ] Load testing completed - -#### Documentation Requirements -- [ ] CHANGELOG.md updated -- [ ] README.md reflects new features -- [ ] API documentation generated -- [ ] Migration guide written for breaking changes -- [ ] Deployment notes prepared -- [ ] Rollback procedure documented - -#### Stakeholder Approvals -- [ ] Product Manager sign-off -- [ ] Engineering Lead approval -- [ ] QA validation complete -- [ ] Security team clearance -- [ ] Legal review (if applicable) -- [ ] Compliance check (if regulated) - -### Deployment Coordination - -#### Communication Plan -**Internal Stakeholders:** -- Engineering team: Technical changes and rollback procedures -- Product team: Feature descriptions and user impact -- Support team: Known issues and troubleshooting guides -- Sales team: Customer-facing changes and talking points - -**External Communication:** -- Release notes for users -- API changelog for developers -- Migration guide for breaking changes -- Downtime notifications if applicable - -#### Deployment Sequence -1. **Pre-deployment** (T-24h): Final validation, freeze code -2. **Database migrations** (T-2h): Run and validate schema changes -3. **Blue-green deployment** (T-0): Switch traffic gradually -4. **Post-deployment** (T+1h): Monitor metrics and logs -5. **Rollback window** (T+4h): Decision point for rollback - -#### Monitoring & Validation -- Application health checks -- Error rate monitoring -- Performance metrics tracking -- User experience monitoring -- Business metrics validation -- Third-party service integration health - -### Hotfix Procedures - -Hotfixes address critical production issues requiring immediate deployment: - -#### Severity Classification -**P0 - Critical**: Complete system outage, data loss, security breach -- **SLA**: Fix within 2 hours -- **Process**: Emergency deployment, all hands on deck -- **Approval**: Engineering Lead + On-call Manager - -**P1 - High**: Major feature broken, significant user impact -- **SLA**: Fix within 24 hours -- **Process**: Expedited review and deployment -- **Approval**: Engineering Lead + Product Manager - -**P2 - Medium**: Minor feature issues, limited user impact -- **SLA**: Fix in next release cycle -- **Process**: Normal review process -- **Approval**: Standard PR review - -#### Emergency Response Process -1. **Incident declaration**: Page on-call team -2. **Assessment**: Determine severity and impact -3. **Hotfix branch**: Create from last stable release -4. **Minimal fix**: Address root cause only -5. **Expedited testing**: Automated tests + manual validation -6. **Emergency deployment**: Deploy to production -7. **Post-incident**: Root cause analysis and prevention - -### Rollback Planning - -Every release must have a tested rollback plan: - -#### Rollback Triggers -- **Error rate spike**: >2x baseline within 30 minutes -- **Performance degradation**: >50% latency increase -- **Feature failures**: Core functionality broken -- **Security incident**: Vulnerability exploited -- **Data corruption**: Database integrity compromised - -#### Rollback Types -**Code Rollback:** -- Revert to previous Docker image -- Database-compatible code changes only -- Feature flag disable preferred over code rollback - -**Database Rollback:** -- Only for non-destructive migrations -- Data backup required before migration -- Forward-only migrations preferred (add columns, not drop) - -**Infrastructure Rollback:** -- Blue-green deployment switch -- Load balancer configuration revert -- DNS changes (longer propagation time) - -#### Automated Rollback -```python -# Example rollback automation -def monitor_deployment(): - if error_rate() > THRESHOLD: - alert_oncall("Error rate spike detected") - if auto_rollback_enabled(): - execute_rollback() -``` - -### Release Metrics & Analytics - -#### Key Performance Indicators -- **Lead Time**: From commit to production -- **Deployment Frequency**: Releases per week/month -- **Mean Time to Recovery**: From incident to resolution -- **Change Failure Rate**: Percentage of releases causing incidents - -#### Quality Metrics -- **Rollback Rate**: Percentage of releases rolled back -- **Hotfix Rate**: Hotfixes per regular release -- **Bug Escape Rate**: Production bugs per release -- **Time to Detection**: How quickly issues are identified - -#### Process Metrics -- **Review Time**: Time spent in code review -- **Testing Time**: Automated + manual testing duration -- **Approval Cycle**: Time from PR to merge -- **Release Preparation**: Time spent on release activities - -### Tool Integration - -#### Version Control Systems -- **Git**: Primary VCS with conventional commit parsing -- **GitHub/GitLab**: Pull request automation and CI/CD -- **Bitbucket**: Pipeline integration and deployment gates - -#### CI/CD Platforms -- **Jenkins**: Pipeline orchestration and deployment automation -- **GitHub Actions**: Workflow automation and release publishing -- **GitLab CI**: Integrated pipelines with environment management -- **CircleCI**: Container-based builds and deployments - -#### Monitoring & Alerting -- **DataDog**: Application performance monitoring -- **New Relic**: Error tracking and performance insights -- **Sentry**: Error aggregation and release tracking -- **PagerDuty**: Incident response and escalation - -#### Communication Platforms -- **Slack**: Release notifications and coordination -- **Microsoft Teams**: Stakeholder communication -- **Email**: External customer notifications -- **Status Pages**: Public incident communication - -## Best Practices - -### Release Planning -1. **Regular cadence**: Establish predictable release schedule -2. **Feature freeze**: Lock changes 48h before release -3. **Risk assessment**: Evaluate changes for potential impact -4. **Stakeholder alignment**: Ensure all teams are prepared - -### Quality Assurance -1. **Automated testing**: Comprehensive test coverage -2. **Staging environment**: Production-like testing environment -3. **Canary releases**: Gradual rollout to subset of users -4. **Monitoring**: Proactive issue detection - -### Communication -1. **Clear timelines**: Communicate schedules early -2. **Regular updates**: Status reports during release process -3. **Issue transparency**: Honest communication about problems -4. **Post-mortems**: Learn from incidents and improve - -### Automation -1. **Reduce manual steps**: Automate repetitive tasks -2. **Consistent process**: Same steps every time -3. **Audit trails**: Log all release activities -4. **Self-service**: Enable teams to deploy safely - -## Common Anti-patterns - -### Process Anti-patterns -- **Manual deployments**: Error-prone and inconsistent -- **Last-minute changes**: Risk introduction without proper testing -- **Skipping testing**: Deploying without validation -- **Poor communication**: Stakeholders unaware of changes - -### Technical Anti-patterns -- **Monolithic releases**: Large, infrequent releases with high risk -- **Coupled deployments**: Services that must be deployed together -- **No rollback plan**: Unable to quickly recover from issues -- **Environment drift**: Production differs from staging - -### Cultural Anti-patterns -- **Blame culture**: Fear of making changes or reporting issues -- **Hero culture**: Relying on individuals instead of process -- **Perfectionism**: Delaying releases for minor improvements -- **Risk aversion**: Avoiding necessary changes due to fear - -## Getting Started - -1. **Assessment**: Evaluate current release process and pain points -2. **Tool setup**: Configure scripts for your repository -3. **Process definition**: Choose appropriate workflow for your team -4. **Automation**: Implement CI/CD pipelines and quality gates -5. **Training**: Educate team on new processes and tools -6. **Monitoring**: Set up metrics and alerting for releases -7. **Iteration**: Continuously improve based on feedback and metrics - -The Release Manager skill transforms chaotic deployments into predictable, reliable releases that build confidence across your entire organization. \ No newline at end of file diff --git a/docs/skills/engineering/skill-security-auditor.md b/docs/skills/engineering/skill-security-auditor.md index 34cbf26c..d771f85a 100644 --- a/docs/skills/engineering/skill-security-auditor.md +++ b/docs/skills/engineering/skill-security-auditor.md @@ -145,7 +145,7 @@ python3 scripts/skill_security_auditor.py https://github.com/user/skill-repo --s # GitHub Actions step - name: "audit-skill-security" run: | - python3 skill-security-auditor/scripts/skill_security_auditor.py ./skills/new-skill/ --strict --json > audit.json + python3 scripts/skill_security_auditor.py ./skills/new-skill/ --strict --json > audit.json if [ $? -ne 0 ]; then echo "Security audit failed"; exit 1; fi ``` diff --git a/docs/skills/engineering/skill-tester.md b/docs/skills/engineering/skill-tester.md index 733d7c57..7cbcae4f 100644 --- a/docs/skills/engineering/skill-tester.md +++ b/docs/skills/engineering/skill-tester.md @@ -15,384 +15,89 @@ description: "Validate, test, and score the quality of skills within the claude- <span class="install-label">Install:</span> <code>claude /plugin install engineering-advanced-skills</code> </div> -**Name**: skill-tester -**Tier**: POWERFUL -**Category**: Engineering Quality Assurance -**Dependencies**: None (Python Standard Library Only) -**Author**: Claude Skills Engineering Team -**Version**: 1.0.0 -**Last Updated**: 2026-02-16 ---- +**Tier**: POWERFUL · **Category**: Engineering Quality Assurance · **Dependencies**: None (Python stdlib only) -## Description +Meta-skill that validates, tests, and scores skills in this repository. Four tools, run from the **repo root** with full paths: -The Skill Tester is a comprehensive meta-skill designed to validate, test, and score the quality of skills within the claude-skills ecosystem. This powerful quality assurance tool ensures that all skills meet the rigorous standards required for BASIC, STANDARD, and POWERFUL tier classifications through automated validation, testing, and scoring mechanisms. +1. **`scripts/skill_validator.py`** — structure + documentation compliance +2. **`scripts/script_tester.py`** — Python script syntax/imports/runtime/output testing +3. **`scripts/quality_scorer.py`** — multi-dimensional scoring with letter grade +4. **`scripts/security_scorer.py`** — security posture scoring (also available via `quality_scorer.py --include-security`) -As the gatekeeping system for skill quality, this meta-skill provides three core capabilities: -1. **Structure Validation** - Ensures skills conform to required directory structures, file formats, and documentation standards -2. **Script Testing** - Validates Python scripts for syntax, imports, functionality, and output format compliance -3. **Quality Scoring** - Provides comprehensive quality assessment across multiple dimensions with letter grades and improvement recommendations +> **Scope note:** this skill's tier line-count minimums measure *legacy* skills. For authoring *new* skills, `engineering/write-a-skill` (SKILL.md under ~100 lines, Matt Pocock doctrine) is the binding standard — do not pad a new skill to satisfy a tier minimum here. -This skill is essential for maintaining ecosystem consistency, enabling automated CI/CD integration, and supporting both manual and automated quality assurance workflows. It serves as the foundation for pre-commit hooks, pull request validation, and continuous integration processes that maintain the high-quality standards of the claude-skills repository. +## Quick Start (exact, runnable from repo root) -## Core Features - -### Comprehensive Skill Validation -- **Structure Compliance**: Validates directory structure, required files (SKILL.md, README.md, scripts/, references/, assets/, expected_outputs/) -- **Documentation Standards**: Checks SKILL.md frontmatter, section completeness, minimum line counts per tier -- **File Format Validation**: Ensures proper Markdown formatting, YAML frontmatter syntax, and file naming conventions - -### Advanced Script Testing -- **Syntax Validation**: Compiles Python scripts to detect syntax errors before execution -- **Import Analysis**: Enforces standard library only policy, identifies external dependencies -- **Runtime Testing**: Executes scripts with sample data, validates argparse implementation, tests --help functionality -- **Output Format Compliance**: Verifies dual output support (JSON + human-readable), proper error handling - -### Multi-Dimensional Quality Scoring -- **Documentation Quality (25%)**: SKILL.md depth and completeness, README clarity, reference documentation quality -- **Code Quality (25%)**: Script complexity, error handling robustness, output format consistency, maintainability -- **Completeness (25%)**: Required directory presence, sample data adequacy, expected output verification -- **Usability (25%)**: Example clarity, argparse help text quality, installation simplicity, user experience - -### Tier Classification System -Automatically classifies skills based on complexity and functionality: - -#### BASIC Tier Requirements -- Minimum 100 lines in SKILL.md -- At least 1 Python script (100-300 LOC) -- Basic argparse implementation -- Simple input/output handling -- Essential documentation coverage - -#### STANDARD Tier Requirements -- Minimum 200 lines in SKILL.md -- 1-2 Python scripts (300-500 LOC each) -- Advanced argparse with subcommands -- JSON + text output formats -- Comprehensive examples and references -- Error handling and edge case management - -#### POWERFUL Tier Requirements -- Minimum 300 lines in SKILL.md -- 2-3 Python scripts (500-800 LOC each) -- Complex argparse with multiple modes -- Sophisticated output formatting and validation -- Extensive documentation and reference materials -- Advanced error handling and recovery mechanisms -- CI/CD integration capabilities - -## Architecture & Design - -### Modular Design Philosophy -The skill-tester follows a modular architecture where each component serves a specific validation purpose: - -- **skill_validator.py**: Core structural and documentation validation engine -- **script_tester.py**: Runtime testing and execution validation framework -- **quality_scorer.py**: Multi-dimensional quality assessment and scoring system - -### Standards Enforcement -All validation is performed against well-defined standards documented in the references/ directory: -- **Skill Structure Specification**: Defines mandatory and optional components -- **Tier Requirements Matrix**: Detailed requirements for each skill tier -- **Quality Scoring Rubric**: Comprehensive scoring methodology and weightings - -### Integration Capabilities -Designed for seamless integration into existing development workflows: -- **Pre-commit Hooks**: Prevents substandard skills from being committed -- **CI/CD Pipelines**: Automated quality gates in pull request workflows -- **Manual Validation**: Interactive command-line tools for development-time validation -- **Batch Processing**: Bulk validation and scoring of existing skill repositories - -## Implementation Details - -### skill_validator.py Core Functions -```python -# Primary validation workflow -validate_skill_structure() -> ValidationReport -check_skill_md_compliance() -> DocumentationReport -validate_python_scripts() -> ScriptReport -generate_compliance_score() -> float -``` - -Key validation checks include: -- SKILL.md frontmatter parsing and validation -- Required section presence (Description, Features, Usage, etc.) -- Minimum line count enforcement per tier -- Python script argparse implementation verification -- Standard library import enforcement -- Directory structure compliance -- README.md quality assessment - -### script_tester.py Testing Framework -```python -# Core testing functions -syntax_validation() -> SyntaxReport -import_validation() -> ImportReport -runtime_testing() -> RuntimeReport -output_format_validation() -> OutputReport -``` - -Testing capabilities encompass: -- Python AST-based syntax validation -- Import statement analysis and external dependency detection -- Controlled script execution with timeout protection -- Argparse --help functionality verification -- Sample data processing and output validation -- Expected output comparison and difference reporting - -### quality_scorer.py Scoring System -```python -# Multi-dimensional scoring -score_documentation() -> float # 25% weight -score_code_quality() -> float # 25% weight -score_completeness() -> float # 25% weight -score_usability() -> float # 25% weight -calculate_overall_grade() -> str # A-F grade -``` - -Scoring dimensions include: -- **Documentation**: Completeness, clarity, examples, reference quality -- **Code Quality**: Complexity, maintainability, error handling, output consistency -- **Completeness**: Required files, sample data, expected outputs, test coverage -- **Usability**: Help text quality, example clarity, installation simplicity - -## Usage Scenarios - -### Development Workflow Integration ```bash -# Pre-commit hook validation -skill_validator.py path/to/skill --tier POWERFUL --json +# 1. Validate structure (exit non-zero on failure — usable as a gate) +python3 engineering/skills/skill-tester/scripts/skill_validator.py engineering/skills/self-eval --json -# Comprehensive skill testing -script_tester.py path/to/skill --timeout 30 --sample-data +# 2. Test the skill's Python scripts (30s default timeout per script) +python3 engineering/skills/skill-tester/scripts/script_tester.py engineering/skills/self-eval --json -# Quality assessment and scoring -quality_scorer.py path/to/skill --detailed --recommendations +# 3. Score quality (fail CI below threshold with --minimum-score) +python3 engineering/skills/skill-tester/scripts/quality_scorer.py engineering/skills/self-eval --json --detailed --minimum-score 75 ``` -### CI/CD Pipeline Integration +Consume the JSON: validator emits `overall_score`, `compliance_level`, per-check `checks{}`; scorer emits `overall_score`, `letter_grade`, `tier_recommendation`, `dimensions`, and an `improvement_roadmap` — work the roadmap top-down, then re-run until the target score is met. + +For repo-wide auditing prefer `scripts/audit_skills.py` at the repo root (wraps the write-a-skill checklist runner across all skills). + +## What Each Tool Checks + +### skill_validator.py +- SKILL.md frontmatter parsing, required sections, minimum line counts per tier (`--tier BASIC|STANDARD|POWERFUL`) +- Required structure: SKILL.md, README.md, scripts/, references/, assets/, expected_outputs/ +- Python scripts: argparse present, stdlib-only imports + +### script_tester.py +- AST-based syntax validation; import analysis (flags external dependencies) +- Controlled execution with timeout protection (`--timeout`, default 30s) +- `--help` functionality verification; sample-data runs compared against expected_outputs/ + +### quality_scorer.py +Four dimensions, 25% each: **Documentation** (depth, examples, references), **Code Quality** (complexity, error handling, output consistency), **Completeness** (required dirs, sample data, expected outputs), **Usability** (help text, example clarity). Outputs 0-100 + A-F grade + tier recommendation. + +## Tier Classification + +| Tier | SKILL.md | Scripts | CLI surface | +|---|---|---|---| +| BASIC | ≥ 100 lines | 1 (100-300 LOC) | basic argparse | +| STANDARD | ≥ 200 lines | 1-2 (300-500 LOC) | subcommands, JSON + text output | +| POWERFUL | ≥ 300 lines | 2-3 (500-800 LOC) | multiple modes, CI integration | + +(Advisory for legacy skills; new skills follow write-a-skill — see scope note above.) + +## CI Integration + ```yaml -# GitHub Actions workflow example -- name: "validate-skill-quality" +# GitHub Actions: gate changed skills +- name: "validate-changed-skills" run: | - python skill_validator.py engineering/${{ matrix.skill }} --json | tee validation.json - python script_tester.py engineering/${{ matrix.skill }} | tee testing.json - python quality_scorer.py engineering/${{ matrix.skill }} --json | tee scoring.json + for skill in $changed_skills; do + python3 engineering/skills/skill-tester/scripts/skill_validator.py "$skill" --json + python3 engineering/skills/skill-tester/scripts/script_tester.py "$skill" + python3 engineering/skills/skill-tester/scripts/quality_scorer.py "$skill" --minimum-score 75 + done ``` -### Batch Repository Analysis -```bash -# Validate all skills in repository -find engineering/ -type d -maxdepth 1 | xargs -I {} skill_validator.py {} +Pre-commit hook: run the validator on the staged skill directory and block the commit on non-zero exit. -# Generate repository quality report -quality_scorer.py engineering/ --batch --output-format json > repo_quality.json -``` +## Verification Loop -## Output Formats & Reporting +A skill "passes" when, in one run from repo root: -### Dual Output Support -All tools provide both human-readable and machine-parseable output: +1. `skill_validator.py <skill> --json` exits 0, +2. `script_tester.py <skill>` reports all scripts passing, and +3. `quality_scorer.py <skill> --minimum-score <target>` exits 0. -#### Human-Readable Format -``` -=== SKILL VALIDATION REPORT === -Skill: engineering/example-skill -Tier: STANDARD -Overall Score: 85/100 (B) +If any step fails, apply the top `improvement_roadmap` item and re-run all three — never report a partial pass. -Structure Validation: ✓ PASS -├─ SKILL.md: ✓ EXISTS (247 lines) -├─ README.md: ✓ EXISTS -├─ scripts/: ✓ EXISTS (2 files) -└─ references/: ⚠ MISSING (recommended) +## Troubleshooting -Documentation Quality: 22/25 (88%) -Code Quality: 20/25 (80%) -Completeness: 18/25 (72%) -Usability: 21/25 (84%) +- **Timeout errors** → raise `--timeout` or optimize the script under test +- **Import failures** → external deps detected; stdlib-only is the repo policy +- **Tier misclassification** → check line counts/LOC against the tier table; remember the write-a-skill exception for new skills -Recommendations: -• Add references/ directory with documentation -• Improve error handling in main.py -• Include more comprehensive examples -``` - -#### JSON Format -```json -{ - "skill_path": "engineering/example-skill", - "timestamp": "2026-02-16T16:41:00Z", - "validation_results": { - "structure_compliance": { - "score": 0.95, - "checks": { - "skill_md_exists": true, - "readme_exists": true, - "scripts_directory": true, - "references_directory": false - } - }, - "overall_score": 85, - "letter_grade": "B", - "tier_recommendation": "STANDARD", - "improvement_suggestions": [ - "Add references/ directory", - "Improve error handling", - "Include comprehensive examples" - ] - } -} -``` - -## Quality Assurance Standards - -### Code Quality Requirements -- **Standard Library Only**: No external dependencies (pip packages) -- **Error Handling**: Comprehensive exception handling with meaningful error messages -- **Output Consistency**: Standardized JSON schema and human-readable formatting -- **Performance**: Efficient validation algorithms with reasonable execution time -- **Maintainability**: Clear code structure, comprehensive docstrings, type hints where appropriate - -### Testing Standards -- **Self-Testing**: The skill-tester validates itself (meta-validation) -- **Sample Data Coverage**: Comprehensive test cases covering edge cases and error conditions -- **Expected Output Verification**: All sample runs produce verifiable, reproducible outputs -- **Timeout Protection**: Safe execution of potentially problematic scripts with timeout limits - -### Documentation Standards -- **Comprehensive Coverage**: All functions, classes, and modules documented -- **Usage Examples**: Clear, practical examples for all use cases -- **Integration Guides**: Step-by-step CI/CD and workflow integration instructions -- **Reference Materials**: Complete specification documents for standards and requirements - -## Integration Examples - -### Pre-Commit Hook Setup -```bash -#!/bin/bash -# .git/hooks/pre-commit -echo "Running skill validation..." -python engineering/skill-tester/scripts/skill_validator.py engineering/new-skill --tier STANDARD -if [ $? -ne 0 ]; then - echo "Skill validation failed. Commit blocked." - exit 1 -fi -echo "Validation passed. Proceeding with commit." -``` - -### GitHub Actions Workflow -```yaml -name: "skill-quality-gate" -on: - pull_request: - paths: ['engineering/**'] - -jobs: - validate-skills: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v3 - - name: "setup-python" - uses: actions/setup-python@v4 - with: - python-version: '3.11' - - name: "validate-changed-skills" - run: | - changed_skills=$(git diff --name-only ${{ github.event.before }} | grep -E '^engineering/[^/]+/' | cut -d'/' -f1-2 | sort -u) - for skill in $changed_skills; do - echo "Validating $skill..." - python engineering/skill-tester/scripts/skill_validator.py $skill --json - python engineering/skill-tester/scripts/script_tester.py $skill - python engineering/skill-tester/scripts/quality_scorer.py $skill --minimum-score 75 - done -``` - -### Continuous Quality Monitoring -```bash -#!/bin/bash -# Daily quality report generation -echo "Generating daily skill quality report..." -timestamp=$(date +"%Y-%m-%d") -python engineering/skill-tester/scripts/quality_scorer.py engineering/ \ - --batch --json > "reports/quality_report_${timestamp}.json" - -echo "Quality trends analysis..." -python engineering/skill-tester/scripts/trend_analyzer.py reports/ \ - --days 30 > "reports/quality_trends_${timestamp}.md" -``` - -## Performance & Scalability - -### Execution Performance -- **Fast Validation**: Structure validation completes in <1 second per skill -- **Efficient Testing**: Script testing with timeout protection (configurable, default 30s) -- **Batch Processing**: Optimized for repository-wide analysis with parallel processing support -- **Memory Efficiency**: Minimal memory footprint for large-scale repository analysis - -### Scalability Considerations -- **Repository Size**: Designed to handle repositories with 100+ skills -- **Concurrent Execution**: Thread-safe implementation supports parallel validation -- **Resource Management**: Automatic cleanup of temporary files and subprocess resources -- **Configuration Flexibility**: Configurable timeouts, memory limits, and validation strictness - -## Security & Safety - -### Safe Execution Environment -- **Sandboxed Testing**: Scripts execute in controlled environment with timeout protection -- **Resource Limits**: Memory and CPU usage monitoring to prevent resource exhaustion -- **Input Validation**: All inputs sanitized and validated before processing -- **No Network Access**: Offline operation ensures no external dependencies or network calls - -### Security Best Practices -- **No Code Injection**: Static analysis only, no dynamic code generation -- **Path Traversal Protection**: Secure file system access with path validation -- **Minimal Privileges**: Operates with minimal required file system permissions -- **Audit Logging**: Comprehensive logging for security monitoring and troubleshooting - -## Troubleshooting & Support - -### Common Issues & Solutions - -#### Validation Failures -- **Missing Files**: Check directory structure against tier requirements -- **Import Errors**: Ensure only standard library imports are used -- **Documentation Issues**: Verify SKILL.md frontmatter and section completeness - -#### Script Testing Problems -- **Timeout Errors**: Increase timeout limit or optimize script performance -- **Execution Failures**: Check script syntax and import statement validity -- **Output Format Issues**: Ensure proper JSON formatting and dual output support - -#### Quality Scoring Discrepancies -- **Low Scores**: Review scoring rubric and improvement recommendations -- **Tier Misclassification**: Verify skill complexity against tier requirements -- **Inconsistent Results**: Check for recent changes in quality standards or scoring weights - -### Debugging Support -- **Verbose Mode**: Detailed logging and execution tracing available -- **Dry Run Mode**: Validation without execution for debugging purposes -- **Debug Output**: Comprehensive error reporting with file locations and suggestions - -## Future Enhancements - -### Planned Features -- **Machine Learning Quality Prediction**: AI-powered quality assessment using historical data -- **Performance Benchmarking**: Execution time and resource usage tracking across skills -- **Dependency Analysis**: Automated detection and validation of skill interdependencies -- **Quality Trend Analysis**: Historical quality tracking and regression detection - -### Integration Roadmap -- **IDE Plugins**: Real-time validation in popular development environments -- **Web Dashboard**: Centralized quality monitoring and reporting interface -- **API Endpoints**: RESTful API for external integration and automation -- **Notification Systems**: Automated alerts for quality degradation or validation failures - -## Conclusion - -The Skill Tester represents a critical infrastructure component for maintaining the high-quality standards of the claude-skills ecosystem. By providing comprehensive validation, testing, and scoring capabilities, it ensures that all skills meet or exceed the rigorous requirements for their respective tiers. - -This meta-skill not only serves as a quality gate but also as a development tool that guides skill authors toward best practices and helps maintain consistency across the entire repository. Through its integration capabilities and comprehensive reporting, it enables both manual and automated quality assurance workflows that scale with the growing claude-skills ecosystem. - -The combination of structural validation, runtime testing, and multi-dimensional quality scoring provides unparalleled visibility into skill quality while maintaining the flexibility needed for diverse skill types and complexity levels. As the claude-skills repository continues to grow, the Skill Tester will remain the cornerstone of quality assurance and ecosystem integrity. \ No newline at end of file +References: `references/` holds the structure specification, tier requirements matrix, and scoring rubric the tools implement. diff --git a/docs/skills/engineering/slo-architect.md b/docs/skills/engineering/slo-architect.md index 5d6f74be..8be869c2 100644 --- a/docs/skills/engineering/slo-architect.md +++ b/docs/skills/engineering/slo-architect.md @@ -160,7 +160,7 @@ This skill explicitly composes with three others: | `chaos-engineering` | Blast-radius calculator already takes monthly error budget as input — define it here | | `kubernetes-operator` | Operator capability L4 (Deep Insights) requires SLOs + Prometheus rules | -The `error_budget_calculator.py` output is in the same shape `chaos-engineering/scripts/blast_radius_calculator.py` expects on stdin. +The `error_budget_calculator.py` output is in the same shape `engineering/skills/chaos-engineering/scripts/blast_radius_calculator.py` expects on stdin. ## Workflows diff --git a/docs/skills/engineering/tech-debt-tracker.md b/docs/skills/engineering/tech-debt-tracker.md index b886194e..a8db9ae3 100644 --- a/docs/skills/engineering/tech-debt-tracker.md +++ b/docs/skills/engineering/tech-debt-tracker.md @@ -36,48 +36,42 @@ This skill offers three interconnected tools that form a complete tech debt mana Together, these tools enable engineering teams to make data-driven decisions about tech debt, balancing new feature development with maintenance work. +## Quick Start — scan → prioritize → dashboard + +All paths relative to this skill folder. The scanner's JSON output feeds the prioritizer directly; dated inventory snapshots feed the dashboard. + +### 1. Scan the codebase + +```bash +python3 scripts/debt_scanner.py /path/to/codebase --format json --output debt_inventory.json +``` + +Emits `debt_inventory.json` with `scan_metadata`, `summary`, `debt_items[]`, `file_statistics`, and `recommendations`. Report the `summary` counts to the user. (Dry run: `assets/sample_codebase`.) + +### 2. Prioritize the backlog + +```bash +python3 scripts/debt_prioritizer.py debt_inventory.json --framework wsjf --team-size 6 --sprint-capacity 20 --format json --output debt_priorities.json +``` + +Frameworks: `cost_of_delay` (default), `wsjf`, `rice`. Output contains `prioritized_backlog` (work top-down), `sprint_allocation` (paste into sprint planning), and `insights`. + +### 3. Track trends over time + +Keep dated snapshots (`debt_YYYY-MM-DD.json`), then: + +```bash +python3 scripts/debt_dashboard.py --input-dir snapshots/ --period monthly --format both --output debt_dashboard +``` + +Or pass files explicitly (samples: `assets/historical_debt_2024-01-15.json assets/historical_debt_2024-02-01.json`). The dashboard reports trend direction and executive-ready summaries — use it to verify a cleanup sprint actually reduced debt. + +### Verification loop + +After a remediation sprint: re-run step 1, re-run step 3 with the new snapshot, and assert the targeted categories' counts dropped. A cleanup that doesn't move the dashboard is rework, not debt paydown. + ## Technical Debt Classification Framework -→ See references/debt-frameworks.md for details - -## Implementation Roadmap - -### Phase 1: Foundation (Weeks 1-2) -1. Set up debt scanning infrastructure -2. Establish debt taxonomy and scoring criteria -3. Scan initial codebase and create baseline inventory -4. Train team on debt identification and reporting - -### Phase 2: Process Integration (Weeks 3-4) -1. Integrate debt tracking into sprint planning -2. Establish debt budgets and allocation rules -3. Create stakeholder reporting templates -4. Set up automated debt scanning in CI/CD - -### Phase 3: Optimization (Weeks 5-6) -1. Refine scoring algorithms based on team feedback -2. Implement trend analysis and predictive metrics -3. Create specialized debt reduction initiatives -4. Establish cross-team debt coordination processes - -### Phase 4: Maturity (Ongoing) -1. Continuous improvement of detection algorithms -2. Advanced analytics and prediction models -3. Integration with planning and project management tools -4. Organization-wide debt management best practices - -## Success Criteria - -**Quantitative Metrics:** -- 25% reduction in debt interest rate within 6 months -- 15% improvement in development velocity -- 30% reduction in production defects -- 20% faster code review cycles - -**Qualitative Metrics:** -- Improved developer satisfaction scores -- Reduced context switching during feature development -- Faster onboarding for new team members -- Better predictability in feature delivery timelines +→ See references/debt-frameworks.md for details (also: references/debt-classification-taxonomy.md, references/prioritization-framework.md, references/stakeholder-communication-templates.md) ## Common Pitfalls and How to Avoid Them diff --git a/docs/skills/engineering/universal-scraping-architect.md b/docs/skills/engineering/universal-scraping-architect.md index 3ee37986..6f057792 100644 --- a/docs/skills/engineering/universal-scraping-architect.md +++ b/docs/skills/engineering/universal-scraping-architect.md @@ -8,7 +8,7 @@ description: "Use for web scraping, crawling, document extraction, API parsing, <div class="page-meta" markdown> <span class="meta-badge">:material-rocket-launch: Engineering - POWERFUL</span> <span class="meta-badge">:material-identifier: `universal-scraping-architect`</span> -<span class="meta-badge">:material-github: <a href="https://github.com/alirezarezvani/claude-skills/tree/main/engineering/universal-scraping-architect/SKILL.md">Source</a></span> +<span class="meta-badge">:material-github: <a href="https://github.com/alirezarezvani/claude-skills/tree/main/engineering/universal-scraping-architect/skills/universal-scraping-architect/SKILL.md">Source</a></span> </div> <div class="install-banner" markdown> @@ -16,9 +16,15 @@ description: "Use for web scraping, crawling, document extraction, API parsing, </div> -You are an expert web scraping and data extraction engineer. Your goal is to design complete, robust data pipelines with intelligent routing, validation, and token budget tracking—not brittle one-off scripts. +Design complete, robust data-extraction pipelines with intelligent routing, validation, and token-budget tracking — not brittle one-off scripts. -**Dependency Notice:** This skill utilizes `firecrawl`, `pandas`, `requests`, and `beautifulsoup4`. It uses a BYOK (Bring Your Own Key) pattern for Firecrawl. API keys must only be loaded via environment variables. +**Dependency Notice:** BYOK (Bring Your Own Key) pattern for Firecrawl; API keys must only be loaded via environment variables. Per-script dependencies: + +| Script | Dependencies | Exact CLI | +|---|---|---| +| `scripts/validate_extraction.py` | stdlib only | `python3 scripts/validate_extraction.py output.json --json` | +| `scripts/firecrawl_example.py` | `firecrawl`, `requests` (template; `--sample` runs offline) | `python3 scripts/firecrawl_example.py --sample` | +| `scripts/local_bs4_example.py` | `beautifulsoup4`, `pandas` (template; `--sample` runs offline) | `python3 scripts/local_bs4_example.py --sample` | ## Before Starting **Check for context first:** @@ -40,8 +46,8 @@ Use when Firecrawl handles URL discovery/web extraction, but local Python (Panda When executing a scraping task, always follow this sequence: 1. **Route the Approach:** Explicitly state whether Firecrawl or Local Python is being used and why. 2. **Track Budgets:** Estimate Firecrawl API quotas or LLM token context limits before executing large jobs. -3. **Extract Safely:** Implement checkpointing for multi-page jobs. Handle pagination and dynamic layouts gracefully. -4. **Validate & Clean:** Enforce required fields, catch empty outputs, flag duplicates, and normalize field names. +3. **Extract Safely:** Implement checkpointing for multi-page jobs. Handle pagination and dynamic layouts gracefully. Start from the editable runner templates — `scripts/firecrawl_example.py` (Mode 1) or `scripts/local_bs4_example.py` (Mode 2); run each with `--sample` first to see the expected summary shape without network access. +4. **Validate & Clean:** Run `python3 scripts/validate_extraction.py extracted_output.json --json` on every extraction result before delivering it. It exits 0 only on `{"status": "ok"}`; `warning` (empty output) or `error` (malformed JSON) exit 1 — fix and re-extract, never ship unvalidated data. Beyond this structural gate, also check required fields and duplicates against the pipeline spec before delivering. 5. **Format:** Default to CSV for tabular data, JSON for nested structures, and Markdown for clean text. ## Proactive Triggers diff --git a/docs/skills/finance/finance-skills.md b/docs/skills/finance/finance-skills.md index 67a05d72..be3a7b0f 100644 --- a/docs/skills/finance/finance-skills.md +++ b/docs/skills/finance/finance-skills.md @@ -1,9 +1,9 @@ --- -title: "Finance Skills — Agent Skill for Finance" -description: "Financial analyst agent skill and plugin for Claude Code, Codex, Gemini CLI, Cursor, OpenClaw. Ratio analysis, DCF valuation, budget variance." +title: "Finance Skills — Router — Agent Skill for Finance" +description: "Router/index for the 2 finance skills bundled in this plugin: financial-analyst (ratio analysis, DCF valuation, budget variance, rolling forecasts). Agent skill for Claude Code, Codex CLI, Gemini CLI, OpenClaw." --- -# Finance Skills +# Finance Skills — Router <div class="page-meta" markdown> <span class="meta-badge">:material-calculator-variant: Finance</span> @@ -16,38 +16,34 @@ description: "Financial analyst agent skill and plugin for Claude Code, Codex, G </div> -Production-ready financial analysis skill for strategic decision-making. +This plugin bundles **2 finance skills** (this router is the 3rd folder under `finance/skills/`). Each skill is self-contained. -## Quick Start +## Routing table -### Claude Code -``` -/read finance/financial-analyst/SKILL.md -``` +| Request signals | Skill | Path | +|---|---|---| +| Ratio analysis, DCF valuation, budget variance, driver-based forecasts | financial-analyst | `skills/financial-analyst/` | +| ARR/MRR, churn, CAC/LTV, NRR, quick ratio, SaaS benchmarks | saas-metrics-coach | `skills/saas-metrics-coach/` | -### Codex CLI -```bash -npx agent-skills-cli add alirezarezvani/claude-skills/finance -``` +If both match (e.g., "value my SaaS company"), ask whether the user wants statement-level analysis (financial-analyst) or SaaS operating metrics (saas-metrics-coach). -## Skills Overview - -| Skill | Folder | Focus | -|-------|--------|-------| -| Financial Analyst | `financial-analyst/` | Ratio analysis, DCF, budget variance, forecasting | - -## Python Tools - -4 scripts, all stdlib-only: +## Quick start ```bash -python3 financial-analyst/scripts/ratio_calculator.py --help -python3 financial-analyst/scripts/dcf_valuation.py --help -python3 financial-analyst/scripts/budget_variance_analyzer.py --help -python3 financial-analyst/scripts/forecast_builder.py --help +# Example: route a statement-analysis request +cat finance/skills/financial-analyst/SKILL.md +python3 finance/skills/financial-analyst/scripts/ratio_calculator.py --help + +# Or a SaaS metrics request +python3 finance/skills/saas-metrics-coach/scripts/metrics_calculator.py --help ``` +## Related (packaged separately, not in this bundle) + +- `finance/business-investment-advisor/` — investment thesis evaluation, ROI modeling (prompt-only skill, separate nested plugin) +- Root commands `/financial-health` and `/saas-health` wrap these skills' scripts. + ## Rules -- Load only the specific skill SKILL.md you need -- Always validate financial outputs against source data +- Route to exactly one skill, then follow that skill's workflow. This router ships no tools of its own. +- Always validate financial outputs against the user's source data; outputs are analysis support, not investment advice. diff --git a/docs/skills/finance/financial-analyst.md b/docs/skills/finance/financial-analyst.md index 22052c30..008a96f7 100644 --- a/docs/skills/finance/financial-analyst.md +++ b/docs/skills/finance/financial-analyst.md @@ -68,9 +68,9 @@ Calculate and interpret financial ratios from financial statement data. - **Valuation:** P/E, P/B, P/S, EV/EBITDA, PEG Ratio ```bash -python scripts/ratio_calculator.py sample_financial_data.json -python scripts/ratio_calculator.py sample_financial_data.json --format json -python scripts/ratio_calculator.py sample_financial_data.json --category profitability +python scripts/ratio_calculator.py assets/sample_financial_data.json +python scripts/ratio_calculator.py assets/sample_financial_data.json --format json +python scripts/ratio_calculator.py assets/sample_financial_data.json --category profitability ``` ### 2. DCF Valuation (`scripts/dcf_valuation.py`) @@ -85,9 +85,9 @@ Discounted Cash Flow enterprise and equity valuation with sensitivity analysis. - Two-way sensitivity analysis (discount rate vs growth rate) ```bash -python scripts/dcf_valuation.py valuation_data.json -python scripts/dcf_valuation.py valuation_data.json --format json -python scripts/dcf_valuation.py valuation_data.json --projection-years 7 +python scripts/dcf_valuation.py assets/sample_financial_data.json +python scripts/dcf_valuation.py assets/sample_financial_data.json --format json +python scripts/dcf_valuation.py assets/sample_financial_data.json --projection-years 7 ``` ### 3. Budget Variance Analyzer (`scripts/budget_variance_analyzer.py`) @@ -102,9 +102,9 @@ Analyze actual vs budget vs prior year performance with materiality filtering. - Executive summary generation ```bash -python scripts/budget_variance_analyzer.py budget_data.json -python scripts/budget_variance_analyzer.py budget_data.json --format json -python scripts/budget_variance_analyzer.py budget_data.json --threshold-pct 5 --threshold-amt 25000 +python scripts/budget_variance_analyzer.py assets/sample_financial_data.json +python scripts/budget_variance_analyzer.py assets/sample_financial_data.json --format json +python scripts/budget_variance_analyzer.py assets/sample_financial_data.json --threshold-pct 5 --threshold-amt 25000 ``` ### 4. Forecast Builder (`scripts/forecast_builder.py`) @@ -118,9 +118,9 @@ Driver-based revenue forecasting with rolling cash flow projection and scenario - Trend analysis using simple linear regression (standard library) ```bash -python scripts/forecast_builder.py forecast_data.json -python scripts/forecast_builder.py forecast_data.json --format json -python scripts/forecast_builder.py forecast_data.json --scenarios base,bull,bear +python scripts/forecast_builder.py assets/sample_financial_data.json +python scripts/forecast_builder.py assets/sample_financial_data.json --format json +python scripts/forecast_builder.py assets/sample_financial_data.json --scenarios base,bull,bear ``` ## Knowledge Bases @@ -152,7 +152,12 @@ python scripts/forecast_builder.py forecast_data.json --scenarios base,bull,bear ## Input Data Format -All scripts accept JSON input files. See `assets/sample_financial_data.json` for the complete input schema covering all four tools. +All scripts accept JSON input files in either of two shapes: + +1. **Flat** — the tool's expected keys at the top level (e.g., `income_statement` / `balance_sheet` for the ratio calculator, `historical` / `assumptions` for DCF, `line_items` for variance, `historical_periods` / `drivers` / `assumptions` / `cash_flow_inputs` for forecasting). +2. **Nested (bundled)** — inputs for all four tools in one file, nested under per-tool keys: `ratio_analysis`, `dcf_valuation`, `budget_variance`, `forecast`. See `assets/sample_financial_data.json` for the complete bundled schema; every quick-start command above runs directly against it. + +Each script auto-detects the shape (flat keys win if present) and exits non-zero with a clear error if neither shape yields usable data. ## Dependencies diff --git a/docs/skills/finance/index.md b/docs/skills/finance/index.md index e51a5135..82f12952 100644 --- a/docs/skills/finance/index.md +++ b/docs/skills/finance/index.md @@ -17,11 +17,11 @@ description: "4 finance skills — finance agent skill and Claude Code plugin fo <div class="grid cards" markdown> -- **[Finance Skills](finance-skills.md)** +- **[Finance Skills — Router](finance-skills.md)** --- - Production-ready financial analysis skill for strategic decision-making. + This plugin bundles 2 finance skills (this router is the 3rd folder under finance/skills/). Each skill is self-contai... - **[Financial Analyst Skill](financial-analyst.md)** diff --git a/docs/skills/index.md b/docs/skills/index.md index 97002aba..eff08669 100644 --- a/docs/skills/index.md +++ b/docs/skills/index.md @@ -1,6 +1,6 @@ --- -title: "337 Agent Skills — Browse by Domain" -description: "Browse 337 production-ready agent skills across 17 domains — engineering, product, marketing, C-level advisory, compliance, commercial, research, and finance. Installable as Claude Code plugins, Codex skills, Gemini CLI skills, and 10 more AI coding tools." +title: "345 Agent Skills — Browse by Domain" +description: "Browse 345 production-ready agent skills across 17 domains — engineering, product, marketing, C-level advisory, compliance, commercial, research, and finance. Installable as Claude Code plugins, Codex skills, Gemini CLI skills, and 10 more AI coding tools." hide: - edit --- @@ -9,26 +9,26 @@ hide: # Skills Library -337 production-ready agent skills across 17 domains — every one self-contained, security-audited, and installable in one command. +345 production-ready agent skills across 17 domains — every one self-contained, security-audited, and installable in one command. { .skills-hero-sub } </div> <div class="grid cards" markdown> -- :material-counter:{ .lg .middle } **337 Skills** +- :material-counter:{ .lg .middle } **345 Skills** --- Across 17 professional domains -- :material-language-python:{ .lg .middle } **550+ Tools** +- :material-language-python:{ .lg .middle } **570+ Tools** --- Python CLI tools, all stdlib-only -- :material-package-variant-closed:{ .lg .middle } **66 Plugins** +- :material-package-variant-closed:{ .lg .middle } **78 Plugins** --- @@ -116,7 +116,7 @@ graph LR [:octicons-arrow-right-24: Browse skills](engineering-team/index.md) -- :material-lightning-bolt:{ .lg .middle } **Engineering — Advanced** <span class="skill-count">75</span> +- :material-lightning-bolt:{ .lg .middle } **Engineering — Advanced** <span class="skill-count">74</span> --- @@ -132,7 +132,7 @@ graph LR [:octicons-arrow-right-24: Browse skills](product-team/index.md) -- :material-bullhorn:{ .lg .middle } **Marketing** <span class="skill-count">48</span> +- :material-bullhorn:{ .lg .middle } **Marketing** <span class="skill-count">47</span> --- diff --git a/docs/skills/markdown-html/design-system.md b/docs/skills/markdown-html/design-system.md index 043f04a2..43ffc034 100644 --- a/docs/skills/markdown-html/design-system.md +++ b/docs/skills/markdown-html/design-system.md @@ -1,5 +1,5 @@ --- -title: "Design System — Onboarding + Shared Brand Tokens — Claude Code Plugin & Agent Skill" +title: "Design System — Onboarding + Shared Brand Tokens — Agent Skill for HTML Output" description: "Captures the user's brand identity once via a 10-question onboarding wizard (primary/accent HEX + heading + body Google Fonts + design style. Agent skill for Claude Code, Codex CLI, Gemini CLI, OpenClaw." --- diff --git a/docs/skills/markdown-html/index.md b/docs/skills/markdown-html/index.md index a4caf09c..b5ab4d87 100644 --- a/docs/skills/markdown-html/index.md +++ b/docs/skills/markdown-html/index.md @@ -1,6 +1,6 @@ --- title: "Markdown to HTML Skills — Agent Skills & Codex Plugins" -description: "5 markdown to html skills — markdown-to-HTML converter agent skill and Claude Code plugin for single-file interactive documents, code reviews, and slide decks. Works with Claude Code, Codex CLI, Gemini CLI, and OpenClaw." +description: "5 markdown to html skills — markdown-to-interactive-HTML converter agent skill and Claude Code plugin for single-file documents, code reviews, and slide decks. Works with Claude Code, Codex CLI, Gemini CLI, and OpenClaw." --- <div class="domain-header" markdown> diff --git a/docs/skills/markdown-html/markdown-html-orchestrator.md b/docs/skills/markdown-html/markdown-html-orchestrator.md index 2046cec9..75d49b56 100644 --- a/docs/skills/markdown-html/markdown-html-orchestrator.md +++ b/docs/skills/markdown-html/markdown-html-orchestrator.md @@ -1,5 +1,5 @@ --- -title: "Markdown → HTML — Domain Orchestrator — Claude Code Plugin & Agent Skill" +title: "Markdown → HTML — Domain Orchestrator — Agent Skill for HTML Output" description: "Use when a user wants to convert any markdown file in their Claude project into a single-file, lightly-interactive HTML — long-form documents (specs. Agent skill for Claude Code, Codex CLI, Gemini CLI, OpenClaw." --- @@ -20,7 +20,7 @@ Thariq Shihipar's argument (Claude Code HTML output essay, Medium 2026): **markd This orchestrator forks context, classifies the input markdown deterministically, routes to the right converter sub-skill, and returns a digest with the output path. Heavy intake (full markdown bodies, diffs, slide decks) stays in the forked context. -**Foundation status (v2.10.0):** orchestrator + `design-system` (onboarding + shared brand tokens) are live. Converter sub-skills (`md-document`, `md-review`, `md-slides`) land in v2.10.1 follow-up PRs. Until they land, this skill still runs the classifier and the design-system gate, and surfaces the routing recommendation — it just hands the rendering work back to Claude with the structured brief. +**Domain status (complete):** all five skills are live — orchestrator + `design-system` (onboarding + shared brand tokens) + the three converter sub-skills (`md-document`, `md-review`, `md-slides`). Always route conversions to the shipped converter's scripts; never hand-render HTML inline. ## When to invoke @@ -51,9 +51,9 @@ Two-signal threshold pattern lifted from `research-ops/skills/research-ops-skill The pipeline: ```bash -python3 skills/markdown-html-orchestrator/scripts/doctype_classifier.py \ +python3 markdown-html/skills/markdown-html-orchestrator/scripts/doctype_classifier.py \ --input <path>.md --output json \ - | python3 skills/markdown-html-orchestrator/scripts/route_explainer.py + | python3 markdown-html/skills/markdown-html-orchestrator/scripts/route_explainer.py ``` `route_explainer.py` checks the design-system status, applies the < 100-line refusal, and prints one of: `ROUTE_SILENTLY -> md-<type>`, `ASK_USER one question: ...`, or `REFUSE — fix the issues above`. @@ -81,17 +81,15 @@ Pipe the classification into `route_explainer.py`. If it says `ROUTE_SILENTLY`, ### Step 4 — Resolve the output path ```bash -python3 skills/markdown-html-orchestrator/scripts/output_path_resolver.py \ +python3 markdown-html/skills/markdown-html-orchestrator/scripts/output_path_resolver.py \ --input <path>.md --doctype <document|review|slides> ``` Collision handling defaults to `-2 / -3 / ...` suffix; `--on-collision timestamp` for stamped names. -### Step 5 — Hand off to the sub-skill (when shipped) +### Step 5 — Hand off to the sub-skill -In v2.10.1+, the converter sub-skill's renderer takes the input markdown, the design-system config, and the resolved output path, and writes a single self-contained HTML file. The orchestrator returns a ≤ 100-word digest: input lines, output path, design style applied, top 3 features used (TOC, search, code-copy, etc.), and one forcing question for the user. - -Until v2.10.1, the orchestrator's job stops at step 4 — it returns the classification + routing brief and lets Claude do the rendering inline with the design-system tokens. +The routed converter sub-skill's renderer (`md-document/scripts/`, `md-review/scripts/`, or `md-slides/scripts/`) takes the input markdown, the design-system config, and the resolved output path, and writes a single self-contained HTML file. The orchestrator returns a ≤ 100-word digest: input lines, output path, design style applied, top 3 features used (TOC, search, code-copy, etc.), and one forcing question for the user. Never render HTML by hand — the converter scripts own the rendering. ## Forcing-question library (Matt Pocock grill-with-docs pattern) @@ -135,9 +133,9 @@ Never run a sub-skill before the lane is locked. | Sub-skill | Artifact | Status | |---|---|---| -| `md-document` | `doc-<slug>.html` (single file, sticky TOC, collapsibles, search, code-copy, scrollspy) | v2.10.1 | -| `md-review` | `review-<slug>.html` (2-col diff + severity margin notes + jump-nav) | v2.10.1 | -| `md-slides` | `deck-<slug>.html` (arrow-key nav + presenter mode + print-to-PDF) | v2.10.1 | +| `md-document` | `doc-<slug>.html` (single file, sticky TOC, collapsibles, search, code-copy, scrollspy) | ✓ live | +| `md-review` | `review-<slug>.html` (2-col diff + severity margin notes + jump-nav) | ✓ live | +| `md-slides` | `deck-<slug>.html` (arrow-key nav + presenter mode + print-to-PDF) | ✓ live | ## Anti-patterns (do not) diff --git a/docs/skills/markdown-html/md-document.md b/docs/skills/markdown-html/md-document.md index 371e2ddf..a26ec917 100644 --- a/docs/skills/markdown-html/md-document.md +++ b/docs/skills/markdown-html/md-document.md @@ -1,5 +1,5 @@ --- -title: "md-document — Long-form Markdown to HTML — Claude Code Plugin & Agent Skill" +title: "md-document — Long-form Markdown to HTML — Agent Skill for HTML Output" description: "Converts long-form markdown (specs, RFCs, reports, plans, explainers) into a single-file, lightly-interactive HTML document with sticky TOC. Agent skill for Claude Code, Codex CLI, Gemini CLI, OpenClaw." --- diff --git a/docs/skills/markdown-html/md-review.md b/docs/skills/markdown-html/md-review.md index 91371b48..086f178d 100644 --- a/docs/skills/markdown-html/md-review.md +++ b/docs/skills/markdown-html/md-review.md @@ -1,5 +1,5 @@ --- -title: "md-review — Code-review markdown → 2-column HTML — Claude Code Plugin & Agent Skill" +title: "md-review — Code-review markdown → 2-column HTML — Agent Skill for HTML Output" description: "Converts a markdown PR writeup or code review (one with ```diff fenced blocks and severity-tagged > [!BLOCKER]/[!MAJOR]/[!MINOR]/[!NIT] callouts). Agent skill for Claude Code, Codex CLI, Gemini CLI, OpenClaw." --- diff --git a/docs/skills/markdown-html/md-slides.md b/docs/skills/markdown-html/md-slides.md index 625a806b..cfe00c47 100644 --- a/docs/skills/markdown-html/md-slides.md +++ b/docs/skills/markdown-html/md-slides.md @@ -1,5 +1,5 @@ --- -title: "md-slides — Markdown deck → single-file HTML presentation — Claude Code Plugin & Agent Skill" +title: "md-slides — Markdown deck → single-file HTML presentation — Agent Skill for HTML Output" description: "Converts a markdown deck (slides separated by `---` HR boundaries or by `# ` H1 headings, with optional `<!-- notes: ... -->` presenter notes blocks). Agent skill for Claude Code, Codex CLI, Gemini CLI, OpenClaw." --- diff --git a/docs/skills/marketing-skill/ab-test-setup.md b/docs/skills/marketing-skill/ab-test-setup.md index 5d665099..780c3f0b 100644 --- a/docs/skills/marketing-skill/ab-test-setup.md +++ b/docs/skills/marketing-skill/ab-test-setup.md @@ -87,16 +87,30 @@ We'll know this is true when [metrics]. ## Sample Size +### Calculate It (bundled tool) + +Use this skill's own calculator — don't eyeball it: + +```bash +python3 scripts/sample_size_calculator.py --baseline 0.05 --mde 0.20 # human-readable +python3 scripts/sample_size_calculator.py --baseline 0.05 --mde 0.20 --json # for pipelines +python3 scripts/sample_size_calculator.py --baseline 0.05 --mde 0.20 --daily-traffic 2000 # adds test-duration estimate +``` + +Paste `sample_size_per_variation` and the duration estimate directly into the test plan's "Sample size + duration" row before any test is approved to run. + ### Quick Reference +Generated by `sample_size_calculator.py` (two-proportion z-test, α=0.05 two-tailed, 80% power; relative MDE): + | Baseline | 10% Lift | 20% Lift | 50% Lift | |----------|----------|----------|----------| -| 1% | 150k/variant | 39k/variant | 6k/variant | -| 3% | 47k/variant | 12k/variant | 2k/variant | -| 5% | 27k/variant | 7k/variant | 1.2k/variant | -| 10% | 12k/variant | 3k/variant | 550/variant | +| 1% | 163k/variant | 43k/variant | 7.7k/variant | +| 3% | 53k/variant | 14k/variant | 2.5k/variant | +| 5% | 31k/variant | 8.2k/variant | 1.5k/variant | +| 10% | 15k/variant | 3.8k/variant | 683/variant | -**Calculators:** +**Cross-check calculators** (should agree with the script within rounding): - [Evan Miller's](https://www.evanmiller.org/ab-testing/sample-size.html) - [Optimizely's](https://www.optimizely.com/sample-size-calculator/) diff --git a/docs/skills/marketing-skill/ad-creative.md b/docs/skills/marketing-skill/ad-creative.md index 8ee64ba4..5cee1e79 100644 --- a/docs/skills/marketing-skill/ad-creative.md +++ b/docs/skills/marketing-skill/ad-creative.md @@ -21,7 +21,7 @@ You are a performance creative director who has written thousands of ads. You kn ## Before Starting **Check for context first:** -If `marketing-context.md` exists, read it before asking questions. Use that context and only ask for information not already covered. +If `.claude/product-marketing-context.md` exists, read it before asking questions. Use that context and only ask for information not already covered. Gather this context (ask if not provided): @@ -85,7 +85,7 @@ You have a winning creative. Now multiply it for testing or for multiple audienc |----------|--------|---------------|-----------------|-------| | Google RSA | Search | 30 chars (×15) | 90 chars (×4 descriptions) | Max 3 pinned | | Google Display | Display | 30 chars (×5) | 90 chars (×5) | Also needs 5 images | -| Meta (Facebook/Instagram) | Feed/Story | 40 chars (primary) | 125 chars primary text | Image text <20% | +| Meta (Facebook/Instagram) | Feed/Story | 40 chars (primary) | 125 chars primary text | Minimal image text (best practice) | | LinkedIn | Sponsored Content | 70 chars headline | 150 chars intro text | No click-bait | | Twitter/X | Promoted | 70 chars | 280 chars total | No deceptive tactics | | TikTok | In-Feed | No overlay headline | 80–100 chars caption | Hook in first 3s | diff --git a/docs/skills/marketing-skill/aeo.md b/docs/skills/marketing-skill/aeo.md index 12c3c2ca..8ae0f07d 100644 --- a/docs/skills/marketing-skill/aeo.md +++ b/docs/skills/marketing-skill/aeo.md @@ -83,9 +83,21 @@ The tracker (`citation_tracker.py`) maintains a local ledger of citations: Stores in `~/.aeo-data/citations.json` (local, no telemetry). +## References + +- `references/aeo_eeat_canon.md` — E-E-A-T methodology, industry thresholds, anti-patterns +- `references/llm_citation_patterns.md` — per-LLM citation selection heuristics (Perplexity, ChatGPT, Claude, Gemini, Mistral) +- `references/aeo_vs_seo.md` — when to invest in AEO vs SEO vs both +- `references/bot_access_and_monitoring.md` — AI crawler robots.txt matrix (the prerequisite check: a blocked bot zeroes that platform), Google Search Console AI Overviews monitoring, manual testing protocols, citation-drop diagnostic (merged from the former `ai-seo` skill) +- `references/extractable_content_patterns.md` — 7 copy-ready block templates (definition, steps, table, FAQ, attributed stat, expert quote, summary box) that answer engines reliably extract (merged from the former `ai-seo` skill) + ## Workflow ``` +0. Pre-flight: bot access + Check robots.txt against the crawler matrix in references/bot_access_and_monitoring.md + → a blocked GPTBot/PerplexityBot/ClaudeBot/Google-Extended is the first fix, always + 1. Audit existing content $ python3 scripts/aeo_audit.py --url https://example.com/blog/post → markdown report with composite score + 4-dimension breakdown diff --git a/docs/skills/marketing-skill/ai-seo.md b/docs/skills/marketing-skill/ai-seo.md deleted file mode 100644 index 71811ae0..00000000 --- a/docs/skills/marketing-skill/ai-seo.md +++ /dev/null @@ -1,336 +0,0 @@ ---- -title: "AI SEO — Agent Skill for Marketing" -description: "Optimize content to get cited by AI search engines — ChatGPT, Perplexity, Google AI Overviews, Claude, Gemini, Copilot. Use when you want your." ---- - -# AI SEO - -<div class="page-meta" markdown> -<span class="meta-badge">:material-bullhorn-outline: Marketing</span> -<span class="meta-badge">:material-identifier: `ai-seo`</span> -<span class="meta-badge">:material-github: <a href="https://github.com/alirezarezvani/claude-skills/tree/main/marketing-skill/skills/ai-seo/SKILL.md">Source</a></span> -</div> - -<div class="install-banner" markdown> -<span class="install-label">Install:</span> <code>claude /plugin install marketing-skills</code> -</div> - - -You are an expert in generative engine optimization (GEO) — the discipline of making content citeable by AI search platforms. Your goal is to help content get extracted, quoted, and cited by ChatGPT, Perplexity, Google AI Overviews, Claude, Gemini, and Microsoft Copilot. - -This is not traditional SEO. Traditional SEO gets you ranked. AI SEO gets you cited. Those are different games with different rules. - -## Before Starting - -**Check for context first:** -If `marketing-context.md` exists, read it. It contains existing keyword targets, content inventory, and competitor information — all of which inform where to start. - -Gather what you need: - -### What you need -- **URL or content to audit** — specific page, or a topic area to assess -- **Target queries** — what questions do you want AI systems to answer using your content? -- **Current visibility** — are you already appearing in any AI search results for your targets? -- **Content inventory** — do you have existing pieces to optimize, or are you starting from scratch? - -If the user doesn't know their target queries: "What questions would your ideal customer ask an AI assistant that you'd want your brand to answer?" - -## How This Skill Works - -Three modes. Each builds on the previous, but you can start anywhere: - -### Mode 1: AI Visibility Audit -Map your current presence (or absence) across AI search platforms. Understand what's getting cited, what's getting ignored, and why. - -### Mode 2: Content Optimization -Restructure and enhance content to match what AI systems extract. This is the execution mode — specific patterns, specific changes. - -### Mode 3: Monitoring -Set up systems to track AI citations over time — so you know when you appear, when you disappear, and when a competitor takes your spot. - ---- - -## How AI Search Works (and Why It's Different) - -Traditional SEO: Google ranks your page. User clicks through. You get traffic. - -AI search: The AI reads your page (or has already indexed it), extracts the answer, and presents it to the user — often without a click. You get cited, not ranked. - -**The fundamental shift:** -- Ranked = user sees your link and decides whether to click -- Cited = AI decides your content answers the question; user may never visit your site - -This changes everything: -- **Keyword density** matters less than **answer clarity** -- **Page authority** matters less than **answer extractability** -- **Click-through rate** is irrelevant — the AI has already decided you're the answer -- **Structured content** (definitions, lists, tables, steps) outperforms flowing narrative - -But here's what traditional SEO and AI SEO share: **authority still matters**. AI systems prefer sources they consider credible — established domains, cited works, expert authorship. You still need backlinks and domain trust. You just also need structure. - -See [references/ai-search-landscape.md](https://github.com/alirezarezvani/claude-skills/tree/main/marketing-skill/skills/ai-seo/references/ai-search-landscape.md) for how each platform (Google AI Overviews, ChatGPT, Perplexity, Claude, Gemini, Copilot) selects and cites sources. - ---- - -## The 3 Pillars of AI Citability - -Every AI SEO decision flows from these three: - -### Pillar 1: Structure (Extractable) - -AI systems pull content in chunks. They don't read your whole article and then paraphrase it — they find the paragraph, list, or definition that directly answers the query and lift it. - -Your content needs to be structured so that answers are self-contained and extractable: -- Definition block for "what is X" -- Numbered steps for "how to do X" -- Comparison table for "X vs Y" -- FAQ block for "questions about X" -- Statistics with attribution for "data on X" - -Content that buries the answer in page 3 of a 4,000-word essay is not extractable. The AI won't find it. - -### Pillar 2: Authority (Citable) - -AI systems don't just pull the most relevant answer — they pull the most credible one. Authority signals in the AI era: - -- **Domain authority**: High-DA domains get preferential treatment (traditional SEO signal still applies) -- **Author attribution**: Named authors with credentials beat anonymous pages -- **Citation chain**: Your content cites credible sources → you're seen as credible in turn -- **Recency**: AI systems prefer current information for time-sensitive queries -- **Original data**: Pages with proprietary research, surveys, or studies get cited more — AI systems value unique data they can't get elsewhere - -### Pillar 3: Presence (Discoverable) - -AI systems need to be able to find and index your content. This is the technical layer: - -- **Bot access**: AI crawlers must be allowed in robots.txt (GPTBot, PerplexityBot, ClaudeBot, etc.) -- **Crawlability**: Fast page load, clean HTML, no JavaScript-only content -- **Schema markup**: Structured data (Article, FAQPage, HowTo, Product) helps AI systems understand your content type -- **Canonical signals**: Duplicate content confuses AI systems even more than traditional search -- **HTTPS and security**: AI crawlers won't index pages with security warnings - ---- - -## Mode 1: AI Visibility Audit - -### Step 1 — Bot Access Check - -First: confirm AI crawlers can access your site. - -**Check robots.txt** at `yourdomain.com/robots.txt`. Verify these bots are NOT blocked: - -``` -# Should NOT be blocked (allow AI indexing): -GPTBot # OpenAI / ChatGPT -PerplexityBot # Perplexity -ClaudeBot # Anthropic / Claude -Google-Extended # Google AI Overviews -anthropic-ai # Anthropic (alternate identifier) -Applebot-Extended # Apple Intelligence -cohere-ai # Cohere -``` - -If any AI bot is blocked, flag it. That's an immediate visibility killer for that platform. - -**robots.txt to allow all AI bots:** -``` -User-agent: GPTBot -Allow: / - -User-agent: PerplexityBot -Allow: / - -User-agent: ClaudeBot -Allow: / - -User-agent: Google-Extended -Allow: / -``` - -To block specific AI training while allowing search: use `Disallow:` selectively, but understand that blocking training ≠ blocking citation — they're often the same crawl. - -### Step 2 — Current Citation Audit - -Manually test your target queries on each platform: - -| Platform | How to test | -|---|---| -| Perplexity | Search your target query at perplexity.ai — check Sources panel | -| ChatGPT | Search with web browsing enabled — check citations | -| Google AI Overviews | Google your query — check if AI Overview appears, who's cited | -| Microsoft Copilot | Search at copilot.microsoft.com — check source cards | - -For each query, document: -- Are you cited? (yes/no) -- Which competitors are cited? -- What content type gets cited? (definition? list? stats?) -- How is the answer structured? - -This tells you the pattern that's currently winning. Build toward it. - -### Step 3 — Content Structure Audit - -Review your key pages against the Extractability Checklist: - -- [ ] Does the page have a clear, answerable definition of its core concept in the first 200 words? -- [ ] Are there numbered lists or step-by-step sections for process-oriented queries? -- [ ] Does the page have a FAQ section with direct Q&A pairs? -- [ ] Are statistics and data points cited with source name and year? -- [ ] Are comparisons done in table format (not narrative)? -- [ ] Is the page's H1 phrased as the answer to a question, or as a statement? -- [ ] Does schema markup exist? (FAQPage, HowTo, Article, etc.) - -Score: 0-3 checks = needs major restructuring. 4-5 = good baseline. 6-7 = strong. - ---- - -## Mode 2: Content Optimization - -### The Content Patterns That Get Cited - -These are the block types AI systems reliably extract. Add at least 2-3 per key page. - -See [references/content-patterns.md](https://github.com/alirezarezvani/claude-skills/tree/main/marketing-skill/skills/ai-seo/references/content-patterns.md) for ready-to-use templates for each pattern. - -**Pattern 1: Definition Block** -The AI's answer to "what is X" almost always comes from a tight, self-contained definition. Format: - -> **[Term]** is [concise definition in 1-2 sentences]. [One sentence of context or why it matters]. - -Placed within the first 300 words of the page. No hedging, no preamble. Just the definition. - -**Pattern 2: Numbered Steps (How-To)** -For process queries ("how do I X"), AI systems pull numbered steps almost universally. Requirements: -- Steps are numbered -- Each step is actionable (verb-first) -- Each step is self-contained (could be quoted alone and still make sense) -- 5-10 steps maximum (AI truncates longer lists) - -**Pattern 3: Comparison Table** -"X vs Y" queries almost always result in table citations. Two-column tables comparing features, costs, pros/cons — these get extracted verbatim. Format matters: clean markdown table with headers wins. - -**Pattern 4: FAQ Block** -Explicit Q&A pairs signal to AI: "this is the question, this is the answer." Mark up with FAQPage schema. Questions should exactly match how people phrase queries (voice search, question-style). - -**Pattern 5: Statistics With Attribution** -"According to [Source Name] ([Year]), X% of [population] [finding]." This format is extractable because it has a complete citation. Naked statistics without attribution get deprioritized — the AI can't verify the source. - -**Pattern 6: Expert Quote Block** -Attributed quotes from named experts get cited. The AI picks up: "According to [Name], [Role at Organization]: '[quote]'" as a citable unit. Build in a few of these per key piece. - -### Rewriting for Extractability - -When optimizing existing content: - -1. **Lead with the answer** — The first paragraph should contain the core answer to the target query. Don't save it for the conclusion. - -2. **Self-contained sections** — Every H2 section should be answerable as a standalone excerpt. If you have to read the introduction to understand a section, it's not self-contained. - -3. **Specific over vague** — "Response time improved by 40%" beats "significant improvement." AI systems prefer citable specifics. - -4. **Plain language summaries** — After complex explanations, add a 1-2 sentence plain language summary. This is what AI often lifts. - -5. **Named sources** — Replace "experts say" with "[Researcher Name], [Year]." Replace "studies show" with "[Organization] found in their [Year] survey." - -### Schema Markup for AI Discoverability - -Schema doesn't directly make you appear in AI results — but it helps AI systems understand your content type and structure. Priority schemas: - -| Schema Type | Use When | Impact | -|---|---|---| -| `Article` | Any editorial content | Establishes content as authoritative information | -| `FAQPage` | You have FAQ section | High — AI extracts Q&A pairs directly | -| `HowTo` | Step-by-step guides | High — AI uses step structure for process queries | -| `Product` | Product pages | Medium — appears in product comparison queries | -| `Organization` | Company pages | Medium — establishes entity authority | -| `Person` | Author pages | Medium — author credibility signal | - -Implement via JSON-LD in the page `<head>`. Validate at schema.org/validator. - ---- - -## Mode 3: Monitoring - -AI search is volatile. Citations change. Track them. - -### Manual Citation Tracking - -Weekly: test your top 10 target queries on Perplexity and ChatGPT. Log: -- Were you cited? (yes/no) -- Rank in citations (1st source, 2nd, etc.) -- What text was used? - -This takes ~20 minutes/week. Do it before automated solutions exist (they don't yet, not reliably). - -### Google Search Console for AI Overviews - -Google Search Console now shows impressions in AI Overviews under "Search type: AI Overviews" filter. Check: -- Which queries trigger AI Overview impressions for your site -- Click-through rate from AI Overviews (typically 50-70% lower than organic) -- Which pages get cited - -### Visibility Signals to Track - -| Signal | Tool | Frequency | -|---|---|---| -| Perplexity citations | Manual query testing | Weekly | -| ChatGPT citations | Manual query testing | Weekly | -| Google AI Overviews | Google Search Console | Weekly | -| Copilot citations | Manual query testing | Monthly | -| AI bot crawl activity | Server logs or Cloudflare | Monthly | -| Competitor AI citations | Manual query testing | Monthly | - -See [references/monitoring-guide.md](https://github.com/alirezarezvani/claude-skills/tree/main/marketing-skill/skills/ai-seo/references/monitoring-guide.md) for the full tracking setup and templates. - -### When Your Citations Drop - -If you were cited and suddenly aren't: -1. Check if competitors published something more extractable on the same topic -2. Check if your robots.txt changed (block AI bots = instant disappearance) -3. Check if your page structure changed significantly (restructuring can break citation patterns) -4. Check if your domain authority dropped (backlink loss affects AI citation too) - ---- - -## Proactive Triggers - -Flag these without being asked: - -- **AI bots blocked in robots.txt** — If GPTBot, PerplexityBot, or ClaudeBot are blocked, flag it immediately. Zero AI visibility is possible until fixed, and it's a 5-minute fix. This trumps everything else. -- **No definition block on target pages** — If the page targets informational queries but has no self-contained definition in the first 300 words, it won't win definitional AI Overviews. Flag before doing anything else. -- **Unattributed statistics** — If key pages contain statistics without named sources and years, they're less citable than competitor pages that do. Flag all naked stats. -- **Schema markup absent** — If the site has no FAQPage or HowTo schema on relevant pages, flag it as a quick structural win with asymmetric impact for process and FAQ queries. -- **JavaScript-rendered content** — If important content only appears after JavaScript execution, AI crawlers may not see it at all. Flag content that's hidden behind JS rendering. - ---- - -## Output Artifacts - -| When you ask for... | You get... | -|---|---| -| AI visibility audit | Platform-by-platform citation test results + robots.txt check + content structure scorecard | -| Page optimization | Rewritten page with definition block, extractable patterns, schema markup spec, and comparison to original | -| robots.txt fix | Updated robots.txt with correct AI bot allow rules + explanation of what each bot is | -| Schema markup | JSON-LD implementation code for FAQPage, HowTo, or Article — ready to paste | -| Monitoring setup | Weekly tracking template + Google Search Console filter guide + citation log spreadsheet structure | - ---- - -## Communication - -All output follows the structured standard: -- **Bottom line first** — answer before explanation -- **What + Why + How** — every finding includes all three -- **Actions have owners and deadlines** — no "consider reviewing..." -- **Confidence tagging** — 🟢 verified (confirmed by citation test) / 🟡 medium (pattern-based) / 🔴 assumed (extrapolated from limited data) - -AI SEO is still a young field. Be honest about confidence levels. What gets cited can change as platforms evolve. State what's proven vs. what's pattern-matching. - ---- - -## Related Skills - -- **content-production**: Use to create the underlying content before optimizing for AI citation. Good AI SEO requires good content first. -- **content-humanizer**: Use after writing for AI SEO. AI-sounding content ironically performs worse in AI citation — AI systems prefer content that reads credibly, which usually means human-sounding. -- **seo-audit**: Use for traditional search ranking optimization. Run both — AI SEO and traditional SEO are complementary, not competing. Many signals overlap. -- **content-strategy**: Use when deciding which topics and queries to target for AI visibility. Strategy first, then optimize. diff --git a/docs/skills/marketing-skill/analytics-tracking.md b/docs/skills/marketing-skill/analytics-tracking.md index db09892a..8cbe3116 100644 --- a/docs/skills/marketing-skill/analytics-tracking.md +++ b/docs/skills/marketing-skill/analytics-tracking.md @@ -23,7 +23,7 @@ Bad tracking is worse than no tracking. Duplicate events, missing parameters, un ## Before Starting **Check for context first:** -If `marketing-context.md` exists, read it before asking questions. Use that context and only ask for what's missing. +If `.claude/product-marketing-context.md` exists, read it before asking questions. Use that context and only ask for what's missing. Gather this context: @@ -46,7 +46,17 @@ Gather this context: ## How This Skill Works ### Mode 1: Set Up From Scratch -No analytics in place — we'll build the tracking plan, implement GA4 and GTM, define the event taxonomy, and configure conversions. +No analytics in place — we'll build the tracking plan, implement GA4 and GTM, define the event taxonomy, and configure key events. + +Start from the generator, then customize: + +```bash +python3 scripts/tracking_plan_generator.py # embedded sample → full tracking plan +python3 scripts/tracking_plan_generator.py plan.json # your funnel definition +python3 scripts/tracking_plan_generator.py --json # parseable JSON for pipelines +``` + +Its output (event taxonomy + parameters + GA4/GTM config checklist) is the working draft for the Event Taxonomy Design section below — review every generated event name against the naming convention before implementing. ### Mode 2: Audit Existing Tracking Tracking exists but you don't trust the data, coverage is incomplete, or you're adding new goals. We'll audit what's there, gap-fill, and clean up. @@ -161,18 +171,18 @@ window.dataLayer.push({ }); ``` -### Conversions Configuration +### Key Events Configuration -Mark these events as conversions in GA4 → Admin → Conversions: +Mark these events as key events in GA4 → Admin → Key events (GA4 renamed "Conversions" to "Key events" in March 2024 — "conversions" now refers only to Google Ads conversion actions): - `signup_completed` - `checkout_completed` - `demo_requested` - `trial_started` (if separate from signup) **Rules:** -- Max 30 conversion events per property — curate, don't mark everything -- Conversions are retroactive in GA4 — turning one on applies to 6 months of history -- Don't mark micro-conversions as conversions unless you're optimizing ad campaigns for them +- Max 30 key events per property — curate, don't mark everything +- Key events are retroactive in GA4 — turning one on applies to 6 months of history +- Don't mark micro-conversions as key events unless you're also optimizing ad campaigns for them --- @@ -353,7 +363,7 @@ Surface these without being asked: | "Set up GTM" | Tag/trigger/variable configuration for each event, container setup checklist | | "Debug missing events" | Structured debugging steps using GTM Preview + GA4 DebugView + Network tab | | "Set up conversion tracking" | Conversion action configuration for GA4 + Google Ads + Meta | -| "Generate tracking plan" | Run `scripts/tracking_plan_generator.py` with your inputs | +| "Generate tracking plan" | Run `python3 scripts/tracking_plan_generator.py [plan.json] [--json]` — event taxonomy + GA4/GTM checklist | --- diff --git a/docs/skills/marketing-skill/churn-prevention.md b/docs/skills/marketing-skill/churn-prevention.md index 1de6dba4..7d906903 100644 --- a/docs/skills/marketing-skill/churn-prevention.md +++ b/docs/skills/marketing-skill/churn-prevention.md @@ -23,7 +23,7 @@ Churn is a revenue leak you can plug. A 20% save rate on voluntary churners and ## Before Starting **Check for context first:** -If `marketing-context.md` exists, read it before asking questions. Use that context and only ask for what's missing. +If `.claude/product-marketing-context.md` exists, read it before asking questions. Use that context and only ask for what's missing. Gather this context (ask if not provided): diff --git a/docs/skills/marketing-skill/cold-email.md b/docs/skills/marketing-skill/cold-email.md index 9be363d6..b736073c 100644 --- a/docs/skills/marketing-skill/cold-email.md +++ b/docs/skills/marketing-skill/cold-email.md @@ -21,7 +21,7 @@ You are an expert in B2B cold email outreach. Your goal is to help write, build, ## Before Starting **Check for context first:** -If `marketing-context.md` exists, read it before asking questions. +If `.claude/product-marketing-context.md` exists, read it before asking questions. Gather this context: @@ -247,15 +247,25 @@ Surface these without being asked: --- +## Tools + +| Tool | Invocation | Output | +|---|---|---| +| Sequence analyzer | `python3 scripts/email_sequence_analyzer.py sequence.json` (no arg = embedded demo; `-` reads stdin) | Per-email 0-100 score across word count, reading level, personalization, CTA clarity, spam triggers, subject lines | + +Run it on every drafted sequence before delivering: any email scoring below 70 gets rewritten against the flagged dimensions (spam triggers and CTA clarity first), then re-scored. + +--- + ## Output Artifacts | When you ask for... | You get... | |---------------------|------------| | Write a cold email | First-touch email + 3 subject line variants + brief rationale for structure choices | -| Build a sequence | 5-6 email sequence with send gaps, subject lines per email, and angle summary for each follow-up | +| Build a sequence | 5-6 email sequence with send gaps, subject lines per email, and angle summary for each follow-up — scored with `email_sequence_analyzer.py` before delivery | | Critique my email | Line-by-line assessment + rewrite + explanation of each change | | Write follow-ups only | Follow-up emails 2-6 with unique angles per email + breakup email | -| Analyze sequence performance | Diagnosis of where the sequence breaks (subject/body/CTA) + specific rewrite recommendations | +| Analyze sequence performance | `email_sequence_analyzer.py` score report + diagnosis of where the sequence breaks (subject/body/CTA) + specific rewrite recommendations | --- diff --git a/docs/skills/marketing-skill/competitor-alternatives.md b/docs/skills/marketing-skill/competitor-alternatives.md index b564fb03..e9cb4ed4 100644 --- a/docs/skills/marketing-skill/competitor-alternatives.md +++ b/docs/skills/marketing-skill/competitor-alternatives.md @@ -268,6 +268,16 @@ Proactively offer competitor page creation when: --- +## Tools + +| Tool | Invocation | Output | +|---|---|---| +| Comparison matrix builder | `python3 scripts/comparison_matrix_builder.py --input competitors.json --markdown` (no input = embedded demo; `--json` for pipelines) | Feature-by-feature comparison matrix ready to paste into the vs-page comparison table | + +Feed it the Competitor Intelligence File data (features + pricing per competitor); its markdown output is the canonical comparison table for every Vs Page below — don't hand-build the table. + +--- + ## Output Artifacts | Artifact | Format | Description | diff --git a/docs/skills/marketing-skill/content-humanizer.md b/docs/skills/marketing-skill/content-humanizer.md index 2846d6e1..3bf648ff 100644 --- a/docs/skills/marketing-skill/content-humanizer.md +++ b/docs/skills/marketing-skill/content-humanizer.md @@ -23,13 +23,13 @@ This is not a cleaning service. You're not just removing "delve" and calling it ## Before Starting **Check for context first:** -If `marketing-context.md` exists, read it. It contains brand voice guidelines, writing examples, and the specific tone this brand uses. That context is your voice blueprint. Use it — don't improvise a voice when the brief already defines one. +If `.claude/product-marketing-context.md` exists, read it. It contains brand voice guidelines, writing examples, and the specific tone this brand uses. That context is your voice blueprint. Use it — don't improvise a voice when the brief already defines one. Gather what you need before starting: ### What you need - **The content** — paste the draft to humanize -- **Brand voice notes** — if no `marketing-context.md`, ask: "Is your voice direct/casual/technical/irreverent? Give me one example of writing you love." +- **Brand voice notes** — if no `.claude/product-marketing-context.md`, ask: "Is your voice direct/casual/technical/irreverent? Give me one example of writing you love." - **Audience** — who reads this? (This changes what "human" sounds like) - **Goal** — what should this piece do? (Knowing the goal tells you how much personality is appropriate) @@ -56,7 +56,15 @@ Run all three in one pass when you have enough context. Split them when the clie Scan the content for these categories. Score severity: 🔴 critical (kills credibility) / 🟡 medium (softens impact) / 🟢 minor (polish only). -See [references/ai-tells-checklist.md](https://github.com/alirezarezvani/claude-skills/tree/main/marketing-skill/skills/content-humanizer/references/ai-tells-checklist.md) for the comprehensive detection list. +Start with the mechanical pass: + +```bash +python3 scripts/humanizer_scorer.py draft.md --json +``` + +It emits a 0-100 human-ness score. Interpretation: **80+** light polish only; **60-79** targeted pattern removal (Mode 2); **below 60** the AI fingerprint density is too high for a patch job — recommend a full rewrite, not an edit. Re-run after humanizing; the score must move. + +See [references/ai-tells-checklist.md](https://github.com/alirezarezvani/claude-skills/tree/main/marketing-skill/skills/content-humanizer/references/ai-tells-checklist.md) for the comprehensive detection list. Note: the tell vocabulary below is a snapshot — newer models have different tells, so check the checklist's "last validated" date and refresh it when auditing against current-generation output. ### The Core AI Tell Categories @@ -142,7 +150,7 @@ Every vague claim is an invitation to doubt. Replace: **Before:** "Many companies have seen significant improvements by implementing this strategy." -**After:** "HubSpot published their onboarding funnel data in 2023 — companies that hit their first-value moment within 7 days showed 40% higher 90-day retention. That's not a rounding error." +**After:** "[Named company] published their onboarding funnel data in [year] — companies that hit their first-value moment within 7 days showed 40% higher 90-day retention. That's not a rounding error." (Name a real, current source with its year — the structure is what matters: named source + dated data + specific number.) If you don't have specific data, be honest: "I haven't seen controlled studies on this, but in my experience working with SaaS onboarding flows, the pattern is consistent: earlier activation = higher retention." @@ -175,7 +183,7 @@ Humanizing removes AI. Voice injection makes it *yours*. ### Read the Voice Blueprint First -If `marketing-context.md` is available: read the brand voice section and writing examples. If not, ask for one example of content this brand loves. One. Then extract the patterns from it. +If `.claude/product-marketing-context.md` is available: read the brand voice section and writing examples. If not, ask for one example of content this brand loves. One. Then extract the patterns from it. **What to extract from a voice example:** - Sentence length preference (short punchy vs. longer flowing?) @@ -227,7 +235,7 @@ What changed: Flag these without being asked: - **AI fingerprint density too high** — If the piece has 10+ AI tells per 500 words, a patch job won't work. Flag that the piece needs a full rewrite, not an edit. Trying to polish a piece that's 80% AI patterns produces AI patterns with nicer words. -- **Voice context missing** — If `marketing-context.md` doesn't exist and the user hasn't given voice guidance, pause before injecting voice. Ask for one example. Guessing the voice and being wrong wastes everyone's time. +- **Voice context missing** — If `.claude/product-marketing-context.md` doesn't exist and the user hasn't given voice guidance, pause before injecting voice. Ask for one example. Guessing the voice and being wrong wastes everyone's time. - **Specificity gap** — If the piece makes 5+ vague claims with zero data or attribution, flag it to the user. You can make the prose flow better, but you can't invent specific proof. They need to provide it. - **Tone mismatch after humanizing** — If the piece is now genuinely human but sounds like a different brand than everything else the client publishes, flag it. Consistency matters as much as quality. - **Over-editing risk** — If the original content has one or two genuinely good paragraphs buried in the AI mush, flag them before rewriting. Don't accidentally destroy the good parts. @@ -263,4 +271,4 @@ When auditing: name the pattern → explain why it reads as AI → give the spec - **content-production**: Use to produce the initial draft. Run content-humanizer after drafting, before the SEO optimization pass. - **copywriting**: Use for conversion copy — landing pages, CTAs, headlines. content-humanizer works on longer-form pieces; copywriting handles short punchy copy with different principles. - **content-strategy**: Use when deciding what content to create. NOT for voice or draft execution. -- **ai-seo**: Use after humanizing, to optimize for AI search citation. Human-sounding content gets cited more — but it still needs structure to get extracted. +- **aeo**: Use after humanizing, to optimize for AI search citation. Human-sounding content gets cited more — but it still needs structure to get extracted. diff --git a/docs/skills/marketing-skill/content-production.md b/docs/skills/marketing-skill/content-production.md index 23adf877..3a6946bd 100644 --- a/docs/skills/marketing-skill/content-production.md +++ b/docs/skills/marketing-skill/content-production.md @@ -23,7 +23,7 @@ This is the execution engine — not the strategy layer. You're here to build, n ## Before Starting **Check for context first:** -If `marketing-context.md` exists, read it before asking questions. It contains brand voice, target audience, keyword targets, and writing examples. Use what's there — only ask for what's missing. +If `.claude/product-marketing-context.md` exists, read it before asking questions. It contains brand voice, target audience, keyword targets, and writing examples. Use what's there — only ask for what's missing. Gather this context (ask in one shot, don't drip): @@ -148,10 +148,18 @@ Don't pad the conclusion. If it's done, it's done. ## Mode 3: Optimize & Polish -Draft exists. Run this in order. +Draft exists. Run this in order. Each pass has a bundled tool — run the tool first, then do the manual checks on what it can't see. ### SEO Pass +Run the optimizer first: + +```bash +python3 scripts/seo_optimizer.py draft.md --keyword "primary keyword" --secondary "secondary,phrases" +``` + +Fix what it flags, then verify manually: + - **Title tag**: Contains primary keyword, under 60 characters, curiosity-driving - **H1**: Different from title tag, keyword-rich, reads naturally - **H2s**: At least 2-3 contain secondary keywords or related phrases @@ -161,7 +169,7 @@ Draft exists. Run this in order. ### Readability Pass -Run `scripts/content_scorer.py` on the draft. Target score: 70+. +Run `python3 scripts/content_scorer.py draft.md --json` on the draft (emits a 0-100 score). Target score: 70+. Manual checks: - Average sentence length: aim for 15-20 words, mix it up @@ -169,6 +177,16 @@ Manual checks: - No jargon without explanation (for non-expert audiences) - Active voice: find passive constructions and flip them +### Brand Voice Pass + +Check the draft against the brand's voice profile (from `.claude/product-marketing-context.md`): + +```bash +python3 scripts/brand_voice_analyzer.py draft.md --format json +``` + +It reports tone markers, sentence-rhythm stats, and vocabulary fingerprint. Compare against the brand's established profile; rewrite sections that drift (e.g., formal drift in a casual brand). + ### Structure Audit - Does the intro deliver on the headline's promise? @@ -192,7 +210,13 @@ Write: ### Quality Gates — Don't Publish Until These Pass -See [references/optimization-checklist.md](https://github.com/alirezarezvani/claude-skills/tree/main/marketing-skill/skills/content-production/references/optimization-checklist.md) for the full pre-publish checklist. +Run the gate checker — it enforces the non-negotiables mechanically: + +```bash +python3 scripts/content_quality_gates.py draft.md --json +``` + +A failing gate blocks publish; fix and re-run until clean. See [references/optimization-checklist.md](https://github.com/alirezarezvani/claude-skills/tree/main/marketing-skill/skills/content-production/references/optimization-checklist.md) for the full pre-publish checklist. Core gates: - [ ] Primary keyword appears naturally 3-5x (not stuffed) @@ -245,6 +269,6 @@ When reviewing drafts: flag issues → explain impact → give specific fix. Don - **content-strategy**: Use when deciding *what* to write — topics, calendar, pillar structure. NOT for writing the actual piece (that's this skill). - **content-humanizer**: Use after drafting when the piece sounds robotic or AI-generated. Run this before the optimization pass. -- **ai-seo**: Use when optimizing specifically for AI search citation (ChatGPT, Perplexity, AI Overviews) in addition to traditional SEO. +- **aeo**: Use when optimizing specifically for AI search citation (ChatGPT, Perplexity, AI Overviews) in addition to traditional SEO. - **copywriting**: Use for landing pages, CTAs, and conversion copy. NOT for long-form content (that's this skill). - **seo-audit**: Use when auditing an existing content library for SEO gaps. NOT for single-piece production. diff --git a/docs/skills/marketing-skill/content-strategy.md b/docs/skills/marketing-skill/content-strategy.md index 66b95df1..87a9b470 100644 --- a/docs/skills/marketing-skill/content-strategy.md +++ b/docs/skills/marketing-skill/content-strategy.md @@ -49,7 +49,26 @@ Gather this context (ask if not provided): --- ## Searchable vs Shareable -→ See references/content-strategy-reference.md for details + +The core classification decision for every topic: + +- **Searchable** — people already query this (keyword volume exists). Goal: rank and convert. Format: use-case pages, comparisons, how-tos, hub/spoke clusters. Judged by rankings + organic conversions over 6-12 months. +- **Shareable** — nobody searches it yet, but it spreads (original data, contrarian POV, strong narrative). Goal: reach + links + brand. Judged by distribution (shares, referral traffic, backlinks) in the first weeks. + +**Decision rule:** if the topic has meaningful search volume AND clear buyer intent → searchable (build it into a cluster). If it has no volume but a distribution hook → shareable (plan the launch channel before writing). If both → searchable structure with a shareable angle (best ROI). If neither → don't write it. + +Full treatment: references/content-strategy-reference.md + +## Topic Cluster Mapping (bundled tool) + +Once priority topics exist, group them mechanically: + +```bash +python3 scripts/topic_cluster_mapper.py --file keywords.txt # one topic/keyword per line +python3 scripts/topic_cluster_mapper.py --file keywords.txt --json # for pipelines +``` + +Its cluster output is the starting point for §3 Topic Cluster Map below — review cluster boundaries by intent (the tool groups lexically; you verify buyer-stage coherence). ## Output Format diff --git a/docs/skills/marketing-skill/copy-editing.md b/docs/skills/marketing-skill/copy-editing.md index 9365c1e3..6d9cde98 100644 --- a/docs/skills/marketing-skill/copy-editing.md +++ b/docs/skills/marketing-skill/copy-editing.md @@ -55,10 +55,11 @@ Edit copy through seven sequential passes, each focusing on one dimension. After - Burying the point in qualifications **Process:** -1. Read through quickly, highlighting unclear parts -2. Don't correct yet—just note problem areas -3. After marking issues, recommend specific edits -4. Verify edits maintain the original intent +1. Score the draft mechanically first: `python3 scripts/readability_scorer.py --file draft.md` (Flesch score, passive-voice %, filler-word count; add `--json` for pipelines). Anything it flags is your starting highlight list. +2. Read through quickly, highlighting unclear parts the scorer can't see +3. Don't correct yet—just note problem areas +4. After marking issues, recommend specific edits +5. Verify edits maintain the original intent — re-run the scorer; the Flesch score should improve, not regress **After this sweep:** Confirm the "Rule of One" (one main idea per section) and "You Rule" (copy speaks to the reader) are intact. @@ -269,6 +270,16 @@ For every statement, ask "Okay, so what?" If the copy doesn't answer that questi Use these for faster reviews when a full seven-sweep process isn't needed. +### AI-Pattern Check + +If the draft may be AI-generated (or AI-assisted), run the detector before editing: + +```bash +python3 scripts/ai_content_detector.py draft.md --json # no arg = --demo mode +``` + +It scores burstiness, vocabulary diversity, and stock-phrase density. A high AI-likelihood score means the piece needs **content-humanizer** treatment before copy editing — polishing AI mush produces polished AI mush. + ### Word-Level Checks **Cut these words:** diff --git a/docs/skills/marketing-skill/copywriting.md b/docs/skills/marketing-skill/copywriting.md index c373eee0..752ae601 100644 --- a/docs/skills/marketing-skill/copywriting.md +++ b/docs/skills/marketing-skill/copywriting.md @@ -127,6 +127,15 @@ Puns and wit make copy memorable—but only if it fits the brand and doesn't und - "Never {unpleasant event} again" - "{Question highlighting main pain point}" +**Score every headline candidate** with the bundled scorer before picking one: + +```bash +python3 scripts/headline_scorer.py "Ship dashboards in minutes, not sprints" +python3 scripts/headline_scorer.py --file headlines.txt --json # batch-score a list +``` + +It rates 0-100 across 6 dimensions (length, specificity, power words, clarity, emotional pull, format). Write 5-10 candidates, score them all, present the top 2-3 with their scores and dimension breakdowns — never present a sub-60 headline as the primary recommendation. + **For comprehensive headline formulas**: See [references/copy-frameworks.md](https://github.com/alirezarezvani/claude-skills/tree/main/marketing-skill/skills/copywriting/references/copy-frameworks.md) **For natural transition phrases**: See [references/natural-transitions.md](https://github.com/alirezarezvani/claude-skills/tree/main/marketing-skill/skills/copywriting/references/natural-transitions.md) diff --git a/docs/skills/marketing-skill/email-sequence.md b/docs/skills/marketing-skill/email-sequence.md index 90a4ccaf..760be0df 100644 --- a/docs/skills/marketing-skill/email-sequence.md +++ b/docs/skills/marketing-skill/email-sequence.md @@ -79,6 +79,16 @@ What to measure and benchmarks --- +## Tools + +| Tool | Invocation | Output | +|---|---|---| +| Sequence analyzer | `python3 scripts/sequence_analyzer.py --file sequence.json` (no arg = embedded demo; `--json` for pipelines) | Sequence quality score 0-100: pacing, subject-line variety, CTA consistency, exit-condition coverage | + +Run it on the assembled sequence (export the per-email blocks above as a JSON array) before handing off: fix anything it flags below 70, then attach the final score to the Metrics Plan. + +--- + ## Task-Specific Questions 1. What triggers entry to this sequence? @@ -91,15 +101,15 @@ What to measure and benchmarks ## Tool Integrations -For implementation, see the [tools registry](https://github.com/alirezarezvani/claude-skills/tree/main/marketing-skill/tools/REGISTRY.md). Key email tools: +Key email tools: -| Tool | Best For | MCP | Guide | -|------|----------|:---:|-------| -| **Customer.io** | Behavior-based automation | - | [customer-io.md](https://github.com/alirezarezvani/claude-skills/tree/main/marketing-skill/tools/integrations/customer-io.md) | -| **Mailchimp** | SMB email marketing | ✓ | [mailchimp.md](https://github.com/alirezarezvani/claude-skills/tree/main/marketing-skill/tools/integrations/mailchimp.md) | -| **Resend** | Developer-friendly transactional | ✓ | [resend.md](https://github.com/alirezarezvani/claude-skills/tree/main/marketing-skill/tools/integrations/resend.md) | -| **SendGrid** | Transactional email at scale | - | [sendgrid.md](https://github.com/alirezarezvani/claude-skills/tree/main/marketing-skill/tools/integrations/sendgrid.md) | -| **Kit** | Creator/newsletter focused | - | [kit.md](https://github.com/alirezarezvani/claude-skills/tree/main/marketing-skill/tools/integrations/kit.md) | +| Tool | Best For | MCP | +|------|----------|:---:| +| **Customer.io** | Behavior-based automation | - | +| **Mailchimp** | SMB email marketing | ✓ | +| **Resend** | Developer-friendly transactional | ✓ | +| **SendGrid** | Transactional email at scale | - | +| **Kit** | Creator/newsletter focused | - | --- diff --git a/docs/skills/marketing-skill/form-cro.md b/docs/skills/marketing-skill/form-cro.md index 0b20591e..1eda779f 100644 --- a/docs/skills/marketing-skill/form-cro.md +++ b/docs/skills/marketing-skill/form-cro.md @@ -48,7 +48,22 @@ Before providing recommendations, identify: --- ## Core Principles -→ See references/form-cro-playbook.md for details + +The thresholds that drive every form audit (full treatment in references/form-cro-playbook.md): + +- **Field count**: every added field costs conversions. Lead-gen forms: 3-5 fields is the working ceiling; 7+ required fields is a high-priority finding unless lead-qualification value is proven. +- **Required vs optional**: each *required* field must justify itself with a downstream use. "Nice for sales" is not a justification — make it optional or cut it. +- **High-friction fields**: phone number, company size, and address are the biggest abandonment drivers on top-of-funnel forms — demand justification or move them to step 2 / progressive profiling. +- **Error recovery**: inline validation on blur (not on submit), specific error copy ("Enter a work email" not "Invalid input"), never clear filled fields on error. +- **CTA**: value-specific button text ("Get my report") outperforms generic ("Submit"). + +## Tools + +| Tool | Invocation | Output | +|---|---|---| +| Field analyzer | `python3 scripts/form_field_analyzer.py forms.json` (no arg = embedded demo; `--json` for pipelines) | Per-form field count, required-field ratio, high-friction field flags, CTA assessment | + +Run it on the form definition first; its flags become the seed list for the Form Audit below — each flag gets an Issue/Impact/Fix/Priority entry. ## Output Format diff --git a/docs/skills/marketing-skill/free-tool-strategy.md b/docs/skills/marketing-skill/free-tool-strategy.md index c0ac2f72..2705f4a7 100644 --- a/docs/skills/marketing-skill/free-tool-strategy.md +++ b/docs/skills/marketing-skill/free-tool-strategy.md @@ -21,7 +21,7 @@ You are a growth engineer who has built and launched free tools that generated h ## Before Starting **Check for context first:** -If `marketing-context.md` exists, read it before asking questions. Use that context and only ask for information not already covered. +If `.claude/product-marketing-context.md` exists, read it before asking questions. Use that context and only ask for information not already covered. Gather this context (ask if not provided): diff --git a/docs/skills/marketing-skill/index.md b/docs/skills/marketing-skill/index.md index 65aad840..c00d6ace 100644 --- a/docs/skills/marketing-skill/index.md +++ b/docs/skills/marketing-skill/index.md @@ -1,13 +1,13 @@ --- title: "Marketing Skills — Agent Skills & Codex Plugins" -description: "48 marketing skills — marketing agent skill and Claude Code plugin for content, SEO, CRO, and growth. Works with Claude Code, Codex CLI, Gemini CLI, and OpenClaw." +description: "47 marketing skills — marketing agent skill and Claude Code plugin for content, SEO, CRO, and growth. Works with Claude Code, Codex CLI, Gemini CLI, and OpenClaw." --- <div class="domain-header" markdown> # :material-bullhorn-outline: Marketing -<p class="domain-count">48 skills in this domain</p> +<p class="domain-count">47 skills in this domain</p> </div> @@ -35,12 +35,6 @@ description: "48 marketing skills — marketing agent skill and Claude Code plug Get your content cited by ChatGPT, Perplexity, Claude, Gemini, and Mistral as the authoritative source. -- **[AI SEO](ai-seo.md)** - - --- - - You are an expert in generative engine optimization (GEO) — the discipline of making content citeable by AI search pl... - - **[Analytics Tracking](analytics-tracking.md)** --- @@ -173,11 +167,11 @@ description: "48 marketing skills — marketing agent skill and Claude Code plug You are an expert in applied behavioral science for marketing. Your job is to identify which psychological principles... -- **[Marketing Skills Division](marketing-skills.md)** +- **[Marketing Skills — Directory + Router](marketing-skills.md)** --- - 42 production-ready marketing skills organized into 7 specialist pods with a context foundation and orchestration layer. + This is the index skill for the marketing plugin. It does one job: route you to the right specialist skill, then get ... - **[Marketing Strategy & PMM](marketing-strategy-pmm.md)** diff --git a/docs/skills/marketing-skill/launch-strategy.md b/docs/skills/marketing-skill/launch-strategy.md index 75fe60a5..b185907e 100644 --- a/docs/skills/marketing-skill/launch-strategy.md +++ b/docs/skills/marketing-skill/launch-strategy.md @@ -26,7 +26,28 @@ If `.claude/product-marketing-context.md` exists, read it before asking question --- ## Core Philosophy -→ See references/launch-frameworks-and-checklists.md for details + +A launch is a momentum system, not a day. Two frameworks drive everything (full treatment in references/launch-frameworks-and-checklists.md): + +**ORB channel model** — map every launch action to one of three channel types: +- **Owned** — email list, blog, in-app. You control reach; activate first. +- **Rented** — social platforms, communities. Algorithmic reach; you play by their rules. +- **Borrowed** — partner audiences, newsletters, podcasts, Product Hunt. Other people's reach; requires relationship work weeks before launch day. + +A plan that covers only one channel type is incomplete — the quality bar is all three. + +**Phase model** — sequence the launch instead of betting on one day: +1. **Pre-launch** (2-6 weeks out): waitlist/early access, borrowed-channel outreach, asset production +2. **Launch day**: time-boxed checklist, all channels firing, founder availability for engagement +3. **Post-launch** (30 days): momentum content — comparison pages, case studies, roundup email, retargeting + +## Tools + +| Tool | Invocation | Output | +|---|---|---| +| Readiness scorer | `python3 scripts/launch_readiness_scorer.py --checklist launch.json` (no arg = embedded demo; `--export-template` writes a blank checklist; `--json` for pipelines) | 0-100 readiness score by category with the weakest categories called out | + +Gate the launch date on it: score the checklist when planning starts and again one week out — launching below a passing score in the "owned channels ready" or "assets ready" categories means slipping the date, not hoping. ## Task-Specific Questions diff --git a/docs/skills/marketing-skill/marketing-context.md b/docs/skills/marketing-skill/marketing-context.md index eb03f5e1..550e5482 100644 --- a/docs/skills/marketing-skill/marketing-context.md +++ b/docs/skills/marketing-skill/marketing-context.md @@ -18,7 +18,9 @@ description: "Create and maintain the marketing context document that all market You are an expert product marketer. Your goal is to capture the foundational positioning, messaging, and brand context that every other marketing skill needs — so users never repeat themselves. -The document is stored at `.agents/marketing-context.md` (or `marketing-context.md` in the project root). +The document is stored at `.claude/product-marketing-context.md` — the canonical path every marketing skill in this library reads. Always write to this path. + +> **Backward compatibility:** if you previously created `.agents/marketing-context.md` or a root-level `marketing-context.md`, move it to `.claude/product-marketing-context.md` so sibling skills can find it. ## How This Skill Works @@ -128,6 +130,18 @@ See `templates/marketing-context-template.md` for the full template. --- +## Validate the Result + +After writing (or updating) the context file, score its completeness: + +```bash +python3 scripts/context_validator.py .claude/product-marketing-context.md --json +``` + +It emits a 0-100 completeness score from required + optional section coverage. Below 70: go back to the interview and fill the missing sections before declaring the context "done" — sibling skills will silently degrade on an incomplete file. Re-run it during the freshness audit too. + +--- + ## Tips - **Be specific**: Ask "What's the #1 frustration that brings them to you?" not "What problem do they solve?" @@ -152,7 +166,7 @@ Surface these without being asked: | When you ask for... | You get... | |---------------------|------------| -| "Set up marketing context" | Guided interview → complete `marketing-context.md` | +| "Set up marketing context" | Guided interview → complete `.claude/product-marketing-context.md` | | "Auto-draft from codebase" | Codebase scan → V1 draft for review | | "Update positioning" | Targeted update of differentiation + competitive sections | | "Add customer quotes" | Customer language section populated with verbatim phrases | diff --git a/docs/skills/marketing-skill/marketing-demand-acquisition.md b/docs/skills/marketing-skill/marketing-demand-acquisition.md index 6bfe85e5..7f5f5407 100644 --- a/docs/skills/marketing-skill/marketing-demand-acquisition.md +++ b/docs/skills/marketing-skill/marketing-demand-acquisition.md @@ -67,7 +67,7 @@ Acquisition playbook for Series A+ startups scaling internationally (EU/US/Canad ``` utm_source={channel} // linkedin, google, meta utm_medium={type} // cpc, display, email -utm_campaign={campaign-id} // q1-2025-linkedin-enterprise +utm_campaign={campaign-id} // {qN-yyyy}-linkedin-enterprise utm_content={variant} // ad-a, email-1 utm_term={keyword} // [paid search only] ``` @@ -228,7 +228,7 @@ See [attribution-guide.md](https://github.com/alirezarezvani/claude-skills/tree/ | Script | Purpose | Usage | |--------|---------|-------| -| `calculate_cac.py` | Calculate blended and channel CAC | `python scripts/calculate_cac.py --spend 40000 --customers 50` | +| `calculate_cac.py` | Calculate blended and channel CAC | `python scripts/calculate_cac.py` (no args — edit the `example_data` channel table in `main()` with your spend/customer numbers first) | ### HubSpot Integration diff --git a/docs/skills/marketing-skill/marketing-ops.md b/docs/skills/marketing-skill/marketing-ops.md index dc183deb..d8040313 100644 --- a/docs/skills/marketing-skill/marketing-ops.md +++ b/docs/skills/marketing-skill/marketing-ops.md @@ -21,7 +21,7 @@ You are a senior marketing operations leader. Your goal is to route marketing qu ## Before Starting **Check for marketing context first:** -If `marketing-context.md` exists, read it. If it doesn't, recommend running the **marketing-context** skill first — everything works better with context. +If `.claude/product-marketing-context.md` exists, read it. If it doesn't, recommend running the **marketing-context** skill first — everything works better with context. ## How This Skill Works @@ -52,8 +52,8 @@ User wants to assess their marketing → you run a cross-functional audit touchi ### SEO Pod | Trigger | Route to | NOT this | |---------|----------|----------| -| "SEO audit," "technical SEO," "on-page SEO" | **seo-audit** | Not ai-seo (that's for AI search engines) | -| "AI search," "ChatGPT visibility," "Perplexity," "AEO" | **ai-seo** | Not seo-audit (that's traditional SEO) | +| "SEO audit," "technical SEO," "on-page SEO" | **seo-audit** | Not aeo (that's for AI answer engines) | +| "AI search," "ChatGPT visibility," "Perplexity," "AEO" | **aeo** | Not seo-audit (that's traditional SEO) | | "Schema markup," "structured data," "JSON-LD," "rich snippets" | **schema-markup** | | | "Site structure," "URL structure," "navigation," "sitemap" | **site-architecture** | | | "Programmatic SEO," "pages at scale," "template pages" | **programmatic-seo** | | @@ -76,6 +76,11 @@ User wants to assess their marketing → you run a cross-functional audit touchi | "Paid ads," "Google Ads," "Meta ads," "ad campaign" | **paid-ads** | Not ad-creative (that's for copy generation) | | "Ad copy," "ad headlines," "ad variations," "RSA" | **ad-creative** | Not paid-ads (that's for strategy) | | "Social media strategy," "social calendar," "community" | **social-media-manager** | Not social-content (that's for individual posts) | +| "X growth," "Twitter growth," "grow my X account" | **x-twitter-growth** | Not social-content (that's cross-platform posts) | +| "YouTube," "video SEO," "channel strategy," "thumbnails" | **youtube-full** | Not video-content-strategist (that's platform-agnostic strategy) | +| "Video strategy," "short-form video," "video content plan" | **video-content-strategist** (sibling folder `video-content-strategist/`) | Not youtube-full (that's YouTube-specific + API-backed) | +| "Webinar," "webinar funnel," "registration rate," "show-up rate" | **webinar-marketing** | | +| "App Store," "Play Store," "ASO," "app keywords" | **app-store-optimization** | Not seo-audit (that's web search) | ### Growth Pod | Trigger | Route to | NOT this | @@ -92,12 +97,17 @@ User wants to assess their marketing → you run a cross-functional audit touchi | "Set up tracking," "GA4," "GTM," "event tracking" | **analytics-tracking** | Not campaign-analytics (that's for analysis) | | "Competitor page," "vs page," "alternative page" | **competitor-alternatives** | | | "Psychology," "persuasion," "behavioral science" | **marketing-psychology** | | +| "Analyze my social accounts," "engagement rate," "social audit" | **social-media-analyzer** | Not social-media-manager (that's planning, not analysis) | +| "Marketing prompts," "prompt templates," "LLM governance for marketing" | **prompt-engineer-toolkit** | | ### Sales & GTM Pod | Trigger | Route to | NOT this | |---------|----------|----------| | "Product launch," "feature announcement," "Product Hunt" | **launch-strategy** | | | "Pricing," "how much to charge," "pricing tiers" | **pricing-strategy** | | +| "Positioning," "ICP," "product marketing," "messaging framework" | **marketing-strategy-pmm** | Not copywriting (that's execution) | +| "Demand gen," "lead gen program," "MQL/SQL funnel," "CRM campaigns" | **marketing-demand-acquisition** | Not paid-ads (that's one channel) | +| "Brand guidelines," "brand consistency," "style guide audit" | **brand-guidelines** | Not marketing-context (that's the foundation doc) | ### Cross-Domain (route outside marketing-skill/) | Trigger | Route to | Domain | @@ -112,6 +122,14 @@ User wants to assess their marketing → you run a cross-functional audit touchi --- +## Tools + +| Tool | Invocation | Output | +|---|---|---| +| Campaign tracker | `python3 scripts/campaign_tracker.py campaign.json` (no arg = embedded sample; add `--json` for machine-readable) | Per-task status, owners, deadlines, overdue flags across the skills involved in a campaign | + +Use it during orchestration: after laying out a campaign sequence (below), capture each step as a task in a campaign JSON and run the tracker at every check-in — the overdue/ownerless flags feed the Quality Gate ("actions have owners and deadlines"). + ## Campaign Orchestration For multi-skill campaigns, follow this sequence: diff --git a/docs/skills/marketing-skill/marketing-psychology.md b/docs/skills/marketing-skill/marketing-psychology.md index 28245499..cc787a2a 100644 --- a/docs/skills/marketing-skill/marketing-psychology.md +++ b/docs/skills/marketing-skill/marketing-psychology.md @@ -21,7 +21,7 @@ You are an expert in applied behavioral science for marketing. Your job is to id ## Before Starting **Check for marketing context first:** -If `marketing-context.md` exists, read it for audience personas and product positioning. Psychology works better when you know the audience. +If `.claude/product-marketing-context.md` exists, read it for audience personas and product positioning. Psychology works better when you know the audience. ## How This Skill Works diff --git a/docs/skills/marketing-skill/marketing-skills.md b/docs/skills/marketing-skill/marketing-skills.md index 2ee09cce..7ac2e758 100644 --- a/docs/skills/marketing-skill/marketing-skills.md +++ b/docs/skills/marketing-skill/marketing-skills.md @@ -1,9 +1,9 @@ --- -title: "Marketing Skills Division — Agent Skill for Marketing" -description: "42 marketing agent skills and plugins for Claude Code, Codex, Gemini CLI, Cursor, OpenClaw, and 6 more coding agents. 7 pods: content, SEO, CRO." +title: "Marketing Skills — Directory + Router — Agent Skill for Marketing" +description: "Directory and router for the marketing skills library. Use when you need to find the right marketing skill for a task, see what marketing. Agent skill for Claude Code, Codex CLI, Gemini CLI, OpenClaw." --- -# Marketing Skills Division +# Marketing Skills — Directory + Router <div class="page-meta" markdown> <span class="meta-badge">:material-bullhorn-outline: Marketing</span> @@ -16,86 +16,106 @@ description: "42 marketing agent skills and plugins for Claude Code, Codex, Gemi </div> -42 production-ready marketing skills organized into 7 specialist pods with a context foundation and orchestration layer. +This is the index skill for the marketing plugin. It does one job: route you to the right specialist skill, then get out of the way. For request-by-request routing logic, [../marketing-ops/SKILL.md](https://github.com/alirezarezvani/claude-skills/tree/main/marketing-skill/skills/marketing-ops/SKILL.md) is the canonical router — this file is the map. -## Quick Start +**Counts (kept honest):** 44 specialist skills in `skills/` (plus this index and the deprecated `content-creator` redirect), 1 video skill in `video-content-strategist/`, 59 stdlib-only Python tools. No pip installs needed. -### Claude Code -``` -/read marketing-skill/marketing-ops/SKILL.md -``` -The router will direct you to the right specialist skill. +## Start Here -### Codex CLI -```bash -codex --full-auto "Read marketing-skill/marketing-ops/SKILL.md, then help me write a blog post about [topic]" -``` +1. **First run ever?** Use `skills/marketing-context/` to create `.claude/product-marketing-context.md`. Every other skill reads it for brand voice, personas, and competitive landscape. +2. **Know your task?** Find it in the route table below and load only that skill's `SKILL.md`. +3. **Ambiguous request?** Load `skills/marketing-ops/` — its routing matrix maps phrasings to skills. -### OpenClaw -Skills are auto-discovered from the repository. Ask your agent for marketing help — it routes via `marketing-ops`. +## Route Table -## Architecture +All paths are relative to `marketing-skill/`. -``` -marketing-skill/ -├── marketing-context/ ← Foundation: brand voice, audience, goals -├── marketing-ops/ ← Router: dispatches to the right skill -│ -├── Content Pod (8) ← Strategy → Production → Editing → Social -├── SEO Pod (5) ← Traditional + AI SEO + Schema + Architecture -├── CRO Pod (6) ← Pages, Forms, Signup, Onboarding, Popups, Paywall -├── Channels Pod (5) ← Email, Ads, Cold Email, Ad Creative, Social Mgmt -├── Growth Pod (4) ← A/B Testing, Referrals, Free Tools, Churn -├── Intelligence Pod (4) ← Competitors, Psychology, Analytics, Campaigns -└── Sales & GTM Pod (2) ← Pricing, Launch Strategy -``` +### Foundation + Ops +| Task | Skill | +|---|---| +| Capture brand/product context (run first) | `skills/marketing-context/` | +| Route a request, plan campaigns, pick channels | `skills/marketing-ops/` | +| Demand gen programs, funnel + CRM ops | `skills/marketing-demand-acquisition/` | +| Positioning, ICP, product marketing strategy | `skills/marketing-strategy-pmm/` | +| Brand voice/visual consistency audits | `skills/brand-guidelines/` | -## First-Time Setup +### Content +| Task | Skill | +|---|---| +| Write blog posts, articles, guides | `skills/content-production/` | +| Plan what content to create | `skills/content-strategy/` | +| Edit copy (Seven Sweeps) | `skills/copy-editing/` | +| Fix AI-sounding content | `skills/content-humanizer/` | +| Landing/sales page copy | `skills/copywriting/` | +| Headlines, hooks, idea generation | `skills/marketing-ideas/` | +| Persuasion frameworks, mental models | `skills/marketing-psychology/` | -Run `marketing-context` to create your `marketing-context.md` file. Every other skill reads this for brand voice, audience personas, and competitive landscape. Do this once — it makes everything better. +### SEO + AEO +| Task | Skill | +|---|---| +| Traditional SEO audit | `skills/seo-audit/` | +| AI search citations (ChatGPT, Perplexity, AI Overviews) | `skills/aeo/` | +| Programmatic SEO at scale | `skills/programmatic-seo/` | +| Structured data / schema.org | `skills/schema-markup/` | +| Site structure, internal linking | `skills/site-architecture/` | -## Pod Overview +### CRO (conversion) +| Task | Skill | +|---|---| +| Landing/marketing page conversion | `skills/page-cro/` | +| Forms | `skills/form-cro/` | +| Signup flow | `skills/signup-flow-cro/` | +| Onboarding/activation | `skills/onboarding-cro/` | +| Popups/modals | `skills/popup-cro/` | +| Paywall/upgrade screens | `skills/paywall-upgrade-cro/` | +| A/B test design + sample size | `skills/ab-test-setup/` | -| Pod | Skills | Python Tools | Key Capabilities | -|-----|--------|-------------|-----------------| -| **Foundation** | 2 | 2 | Brand context capture, skill routing | -| **Content** | 8 | 5 | Strategy → production → editing → humanization | -| **SEO** | 5 | 2 | Technical SEO, AI SEO (AEO/GEO), schema, architecture | -| **CRO** | 6 | 0 | Page, form, signup, onboarding, popup, paywall optimization | -| **Channels** | 5 | 2 | Email sequences, paid ads, cold email, ad creative | -| **Growth** | 4 | 2 | A/B testing, referral programs, free tools, churn prevention | -| **Intelligence** | 4 | 4 | Competitor analysis, marketing psychology, analytics, campaigns | -| **Sales & GTM** | 2 | 1 | Pricing strategy, launch planning | -| **Standalone** | 4 | 9 | ASO, brand guidelines, PMM strategy, prompt engineering | +### Channels +| Task | Skill | +|---|---| +| Email sequences/drips | `skills/email-sequence/` | +| Cold outbound email | `skills/cold-email/` | +| Paid ads (Google/Meta/LinkedIn) | `skills/paid-ads/` | +| Ad creative + copy | `skills/ad-creative/` | +| Social calendar + management | `skills/social-media-manager/` | +| Platform-native social posts | `skills/social-content/` | +| X/Twitter growth | `skills/x-twitter-growth/` | +| YouTube (data + strategy) | `skills/youtube-full/` | +| Video content strategy | `video-content-strategist/` (sibling folder, own plugin) | +| Webinars (funnel math) | `skills/webinar-marketing/` | +| App Store / Play Store (ASO) | `skills/app-store-optimization/` | -## Python Tools (27 scripts) +### Growth +| Task | Skill | +|---|---| +| Launches (PH, HN, etc.) | `skills/launch-strategy/` | +| Pricing + packaging | `skills/pricing-strategy/` | +| Referral programs | `skills/referral-program/` | +| Free tools as acquisition | `skills/free-tool-strategy/` | +| Churn prevention | `skills/churn-prevention/` | -All scripts are stdlib-only (zero pip installs), CLI-first with JSON output, and include embedded sample data for demo mode. +### Intelligence + Sales Enablement +| Task | Skill | +|---|---| +| Campaign performance, attribution | `skills/campaign-analytics/` | +| Tracking plans, UTM, GA4 key events | `skills/analytics-tracking/` | +| Social account analysis | `skills/social-media-analyzer/` | +| Competitor/alternatives pages | `skills/competitor-alternatives/` | +| LLM prompt templates + governance for marketing teams | `skills/prompt-engineer-toolkit/` | + +## Python Tools + +Each skill documents its own tools in its SKILL.md (a "Tools" or workflow section with exact CLI lines). Invoke from the skill's folder: ```bash -# Content scoring -python3 marketing-skill/content-production/scripts/content_scorer.py article.md - -# AI writing detection -python3 marketing-skill/content-humanizer/scripts/humanizer_scorer.py draft.md - -# Brand voice analysis -python3 marketing-skill/content-production/scripts/brand_voice_analyzer.py copy.txt - -# Ad copy validation -python3 marketing-skill/ad-creative/scripts/ad_copy_validator.py ads.json - -# Pricing scenario modeling -python3 marketing-skill/pricing-strategy/scripts/pricing_modeler.py - -# Tracking plan generation -python3 marketing-skill/analytics-tracking/scripts/tracking_plan_generator.py +python3 skills/<skill>/scripts/<tool>.py --help ``` -## Unique Features +All 59 scripts are stdlib-only; most run a demo with no args. -- **AI SEO (AEO/GEO/LLMO)** — Optimize for AI citation, not just ranking -- **Content Humanizer** — Detect and fix AI writing patterns with scoring -- **Context Foundation** — One brand context file feeds all 42 skills -- **Orchestration Router** — Smart routing by keyword + complexity scoring -- **Zero Dependencies** — All Python tools use stdlib only +## Rules + +- Load ONE specialist skill per task — never bulk-load. +- If `.claude/product-marketing-context.md` exists, read it before any marketing task. +- `content-creator` is deprecated — use `skills/content-production/`. +- Don't pip-install anything for these tools. diff --git a/docs/skills/marketing-skill/onboarding-cro.md b/docs/skills/marketing-skill/onboarding-cro.md index a069d560..4918f122 100644 --- a/docs/skills/marketing-skill/onboarding-cro.md +++ b/docs/skills/marketing-skill/onboarding-cro.md @@ -169,14 +169,20 @@ Signup → Step 1 → Step 2 → Activation → Retention 100% 80% 60% 40% 25% ``` -Identify biggest drops and focus there. +Run the bundled analyzer on your step counts instead of eyeballing: + +```bash +python3 scripts/activation_funnel_analyzer.py funnel.json --json # no arg = embedded demo +``` + +It computes per-step drop-off, an activation score 0-100, and names the biggest-loss step. That step is where the audit focuses first. --- ## Output Format ### Onboarding Audit -For each issue: Finding → Impact → Recommendation → Priority +Lead with the analyzer's output: activation score + the named biggest-drop step. Then, for each issue: Finding → Impact → Recommendation → Priority ### Onboarding Flow Design - Activation goal diff --git a/docs/skills/marketing-skill/page-cro.md b/docs/skills/marketing-skill/page-cro.md index e6a703bf..e9ad6eed 100644 --- a/docs/skills/marketing-skill/page-cro.md +++ b/docs/skills/marketing-skill/page-cro.md @@ -113,9 +113,19 @@ Analyze the page across these dimensions, in order of impact: --- +## Tools + +| Tool | Invocation | Output | +|---|---|---| +| Conversion audit | `python3 scripts/conversion_audit.py --file page.html` (or `--url https://...`; `--json` for pipelines) | Mechanical scan for conversion signals: CTA presence/count, form weight, social proof, trust elements — with a score | + +Run it before the manual framework pass; its score anchors the audit and its flags seed the Quick Wins list. + +--- + ## Output Format -Structure your recommendations as: +Open with the `conversion_audit.py` score, then structure recommendations as: ### Quick Wins (Implement Now) Easy changes with likely immediate impact. diff --git a/docs/skills/marketing-skill/paid-ads.md b/docs/skills/marketing-skill/paid-ads.md index 6c5d2def..aa2df968 100644 --- a/docs/skills/marketing-skill/paid-ads.md +++ b/docs/skills/marketing-skill/paid-ads.md @@ -81,10 +81,10 @@ Account ``` [Platform]_[Objective]_[Audience]_[Offer]_[Date] -Examples: -META_Conv_Lookalike-Customers_FreeTrial_2024Q1 +Examples (use the current year/quarter — {YYYY}/{Qn} are placeholders): +META_Conv_Lookalike-Customers_FreeTrial_{YYYY}Q1 GOOG_Search_Brand_Demo_Ongoing -LI_LeadGen_CMOs-SaaS_Whitepaper_Mar24 +LI_LeadGen_CMOs-SaaS_Whitepaper_{MonYY} ``` ### Budget Allocation @@ -232,9 +232,19 @@ LI_LeadGen_CMOs-SaaS_Whitepaper_Mar24 ## Reporting & Analysis +### Tools + +| Tool | Invocation | Output | +|---|---|---| +| ROAS calculator | `python3 scripts/roas_calculator.py --spend 5000 --revenue 18000 --conversions 120 --clicks 2400 --margin 0.7` (or `--file metrics.json`; `--json` for pipelines) | ROAS, CPA, CPC, CVR, margin-adjusted ROAS + recommendations | +| Ad health scorer | `python3 scripts/ad_health_scorer.py --checks checks.json --platform meta` (no arg = `--demo`; `--json` for pipelines) | Weighted 0-100 account health score with severity-ranked findings; see [references/scoring-system.md](https://github.com/alirezarezvani/claude-skills/tree/main/marketing-skill/skills/paid-ads/references/scoring-system.md) for the scoring model | + ### Weekly Review + +Run both tools on the week's numbers, then review: - Spend vs. budget pacing -- CPA/ROAS vs. targets +- CPA/ROAS vs. targets — from `roas_calculator.py`, margin-adjusted, not platform-reported +- Account health score trend — from `ad_health_scorer.py`; investigate any category that dropped - Top and bottom performing ads - Audience performance breakdown - Frequency check (fatigue risk) @@ -302,16 +312,16 @@ Before launching campaigns, ensure proper tracking and account setup. ## Tool Integrations -For implementation, see the [tools registry](https://github.com/alirezarezvani/claude-skills/tree/main/marketing-skill/tools/REGISTRY.md). Key advertising platforms: +Key advertising platforms: -| Platform | Best For | MCP | Guide | -|----------|----------|:---:|-------| -| **Google Ads** | Search intent, high-intent traffic | ✓ | [google-ads.md](https://github.com/alirezarezvani/claude-skills/tree/main/marketing-skill/tools/integrations/google-ads.md) | -| **Meta Ads** | Demand gen, visual products, B2C | - | [meta-ads.md](https://github.com/alirezarezvani/claude-skills/tree/main/marketing-skill/tools/integrations/meta-ads.md) | -| **LinkedIn Ads** | B2B, job title targeting | - | [linkedin-ads.md](https://github.com/alirezarezvani/claude-skills/tree/main/marketing-skill/tools/integrations/linkedin-ads.md) | -| **TikTok Ads** | Younger demographics, video | - | [tiktok-ads.md](https://github.com/alirezarezvani/claude-skills/tree/main/marketing-skill/tools/integrations/tiktok-ads.md) | +| Platform | Best For | MCP | +|----------|----------|:---:| +| **Google Ads** | Search intent, high-intent traffic | ✓ | +| **Meta Ads** | Demand gen, visual products, B2C | - | +| **LinkedIn Ads** | B2B, job title targeting | - | +| **TikTok Ads** | Younger demographics, video | - | -For tracking, see also: [ga4.md](https://github.com/alirezarezvani/claude-skills/tree/main/marketing-skill/tools/integrations/ga4.md), [segment.md](https://github.com/alirezarezvani/claude-skills/tree/main/marketing-skill/tools/integrations/segment.md) +For tracking and attribution, pair these with GA4 and Segment. --- diff --git a/docs/skills/marketing-skill/pricing-strategy.md b/docs/skills/marketing-skill/pricing-strategy.md index 49d85e7b..9bed4244 100644 --- a/docs/skills/marketing-skill/pricing-strategy.md +++ b/docs/skills/marketing-skill/pricing-strategy.md @@ -23,7 +23,7 @@ Pricing is not math — it's positioning. The right price isn't the one that cov ## Before Starting **Check for context first:** -If `marketing-context.md` exists, read it before asking questions. Use that context and only ask for what's missing. +If `.claude/product-marketing-context.md` exists, read it before asking questions. Use that context and only ask for what's missing. Gather this context: diff --git a/docs/skills/marketing-skill/programmatic-seo.md b/docs/skills/marketing-skill/programmatic-seo.md index 59988cce..335d344a 100644 --- a/docs/skills/marketing-skill/programmatic-seo.md +++ b/docs/skills/marketing-skill/programmatic-seo.md @@ -133,7 +133,17 @@ You can layer multiple playbooks (e.g., "Best coworking spaces in San Diego"). - Is it first-party, scraped, licensed, public? - How is it updated? -### 3. Template Design +### 3. URL Pattern Generation (bundled tool) + +Generate and sanity-check the URL space before building templates: + +```bash +python3 scripts/url_pattern_generator.py pattern.json --json # no arg = embedded demo +``` + +Give it the template (e.g., `{tool}-vs-{competitor}-comparison`), base URL, and variable lists; it expands the combinations, reports the page count, and flags slug problems. If the expansion produces more pages than you have unique data for (see step 2), cut variables — don't ship thin pages. + +### 4. Template Design **Page structure:** - Header with target keyword @@ -147,7 +157,7 @@ You can layer multiple playbooks (e.g., "Best coworking spaces in San Diego"). - Conditional content based on data - Original insights/analysis per page -### 4. Internal Linking Architecture +### 5. Internal Linking Architecture **Hub and spoke model:** - Hub: Main category page @@ -159,7 +169,7 @@ You can layer multiple playbooks (e.g., "Best coworking spaces in San Diego"). - XML sitemap for all pages - Breadcrumbs with structured data -### 5. Indexation Strategy +### 6. Indexation Strategy - Prioritize high-volume patterns - Noindex very thin variations diff --git a/docs/skills/marketing-skill/prompt-engineer-toolkit.md b/docs/skills/marketing-skill/prompt-engineer-toolkit.md index 44885ee7..cc795552 100644 --- a/docs/skills/marketing-skill/prompt-engineer-toolkit.md +++ b/docs/skills/marketing-skill/prompt-engineer-toolkit.md @@ -1,6 +1,6 @@ --- title: "Prompt Engineer Toolkit — Agent Skill for Marketing" -description: "Analyzes and rewrites prompts for better AI output, creates reusable prompt templates for marketing use cases (ad copy, email campaigns, social. Agent skill for Claude Code, Codex CLI, Gemini CLI, OpenClaw." +description: "Turns marketing prompts into tested, versioned production assets: A/B prompt evaluation against structured test cases, immutable prompt version. Agent skill for Claude Code, Codex CLI, Gemini CLI, OpenClaw." --- # Prompt Engineer Toolkit @@ -111,9 +111,9 @@ python3 scripts/prompt_versioner.py changelog --name support_classifier ## References -- [references/prompt-templates.md](https://github.com/alirezarezvani/claude-skills/tree/main/marketing-skill/skills/prompt-engineer-toolkit/references/prompt-templates.md) -- [references/technique-guide.md](https://github.com/alirezarezvani/claude-skills/tree/main/marketing-skill/skills/prompt-engineer-toolkit/references/technique-guide.md) -- [references/evaluation-rubric.md](https://github.com/alirezarezvani/claude-skills/tree/main/marketing-skill/skills/prompt-engineer-toolkit/references/evaluation-rubric.md) +- [references/prompt-templates.md](https://github.com/alirezarezvani/claude-skills/tree/main/marketing-skill/skills/prompt-engineer-toolkit/references/prompt-templates.md) — 6 production marketing templates (ad copy, email sequence, social repurposing, landing sections, SEO meta, brand-voice rewrite) plus generic building blocks; each written to be graded by `prompt_tester.py` +- [references/technique-guide.md](https://github.com/alirezarezvani/claude-skills/tree/main/marketing-skill/skills/prompt-engineer-toolkit/references/technique-guide.md) — technique-selection table for marketing tasks + the LLM-governance stack for marketing teams (claim discipline, disclosure rules, data boundaries, human-review gates) +- [references/evaluation-rubric.md](https://github.com/alirezarezvani/claude-skills/tree/main/marketing-skill/skills/prompt-engineer-toolkit/references/evaluation-rubric.md) — mechanical scoring weights, acceptance gates, marketing quality dimensions, test-suite design, and eval anti-patterns - [README.md](https://github.com/alirezarezvani/claude-skills/tree/main/marketing-skill/skills/prompt-engineer-toolkit/README.md) ## Evaluation Design diff --git a/docs/skills/marketing-skill/referral-program.md b/docs/skills/marketing-skill/referral-program.md index 59ed27e1..bb9d12aa 100644 --- a/docs/skills/marketing-skill/referral-program.md +++ b/docs/skills/marketing-skill/referral-program.md @@ -21,7 +21,7 @@ You are a growth engineer who has designed referral and affiliate programs for S ## Before Starting **Check for context first:** -If `marketing-context.md` exists, read it before asking questions. Use that context and only ask for information not already covered. +If `.claude/product-marketing-context.md` exists, read it before asking questions. Use that context and only ask for information not already covered. Gather this context (ask if not provided): diff --git a/docs/skills/marketing-skill/schema-markup.md b/docs/skills/marketing-skill/schema-markup.md index 85fce8ea..1383dd19 100644 --- a/docs/skills/marketing-skill/schema-markup.md +++ b/docs/skills/marketing-skill/schema-markup.md @@ -21,7 +21,7 @@ You are an expert in structured data and schema.org markup. Your goal is to help ## Before Starting **Check for context first:** -If `marketing-context.md` exists, read it before asking questions. Use that context and only ask for what's missing. +If `.claude/product-marketing-context.md` exists, read it before asking questions. Use that context and only ask for what's missing. Gather this context: diff --git a/docs/skills/marketing-skill/seo-audit.md b/docs/skills/marketing-skill/seo-audit.md index 3b6bf2a4..33a70593 100644 --- a/docs/skills/marketing-skill/seo-audit.md +++ b/docs/skills/marketing-skill/seo-audit.md @@ -43,14 +43,32 @@ Before auditing, understand: --- ## Audit Framework -→ See references/seo-audit-reference.md for details + +The audit walks three layers — technical (crawl/indexation/speed), on-page (titles, headings, internal links, keyword targeting), content (intent match, E-E-A-T, thin/duplicate pages). Full framework: references/seo-audit-reference.md. + +**Core Web Vitals pass/fail thresholds** (75th percentile of real-user data; full triage in references/cwv-thresholds.md): + +| Metric | Good | Needs improvement | Poor | +|---|---|---|---| +| LCP (Largest Contentful Paint) | ≤ 2.5s | 2.5-4.0s | > 4.0s | +| INP (Interaction to Next Paint) | ≤ 200ms | 200-500ms | > 500ms | +| CLS (Cumulative Layout Shift) | ≤ 0.1 | 0.1-0.25 | > 0.25 | + +## Tools + +| Tool | Invocation | Output | +|---|---|---| +| On-page checker | `python3 scripts/seo_checker.py --file page.html` (or `--url https://...`; `--json`) | Scores a single page 0-100: title/meta/headings/links/images | +| Health scorer | `python3 scripts/seo_health_scorer.py --checks checks.json --industry saas` (no arg = `--demo`; industries: saas/ecommerce/local/publisher; `--json`) | Weighted 0-100 site health score across 7 categories | + +Run `seo_checker.py` on the key templates/pages during the on-page layer, and `seo_health_scorer.py` on the completed check matrix to produce the audit's headline score. ## Output Format ### Audit Report Structure **Executive Summary** -- Overall health assessment +- Overall health assessment — lead with the `seo_health_scorer.py` score and its weakest categories - Top 3-5 priority issues - Quick wins identified @@ -116,7 +134,7 @@ Same format as above ## Related Skills - **programmatic-seo** — WHEN: user wants to build SEO pages at scale after the audit identifies keyword gaps. WHEN NOT: don't use for diagnosing existing issues; stay in seo-audit mode. -- **ai-seo** — WHEN: user wants to optimize for AI answer engines (SGE, Perplexity, ChatGPT) in addition to traditional search. WHEN NOT: don't use for purely technical crawl/indexation issues. +- **aeo** — WHEN: user wants to optimize for AI answer engines (SGE, Perplexity, ChatGPT) in addition to traditional search. WHEN NOT: don't use for purely technical crawl/indexation issues. - **schema-markup** — WHEN: audit reveals missing structured data opportunities (FAQ, HowTo, Product, Review schemas). WHEN NOT: don't use as a standalone fix when core technical SEO is broken. - **site-architecture** — WHEN: audit uncovers poor internal linking, orphan pages, or crawl depth issues that need a structural redesign. WHEN NOT: don't involve when the audit scope is limited to on-page or content issues. - **content-strategy** — WHEN: audit reveals thin content, keyword gaps, or lack of topical authority requiring a content plan. WHEN NOT: don't use when the problem is purely technical (robots.txt, redirects, speed). diff --git a/docs/skills/marketing-skill/signup-flow-cro.md b/docs/skills/marketing-skill/signup-flow-cro.md index d1b8e534..0a9cf88c 100644 --- a/docs/skills/marketing-skill/signup-flow-cro.md +++ b/docs/skills/marketing-skill/signup-flow-cro.md @@ -48,6 +48,14 @@ Before providing recommendations, understand: ## Core Principles → See references/signup-cro-playbook.md for details +## Tools + +| Tool | Invocation | Output | +|---|---|---| +| Funnel drop analyzer | `python3 scripts/funnel_drop_analyzer.py --steps funnel.json` (or `--stdin`; `--json` for pipelines; no arg = embedded demo) | Per-step drop-off %, the worst step named, and severity ranking | + +Feed it the step-by-step user counts (landing → form start → form complete → verify → done). The named worst step is where the audit starts; quantify each finding's Impact with its drop-off number. + ## Output Format ### Audit Findings diff --git a/docs/skills/marketing-skill/site-architecture.md b/docs/skills/marketing-skill/site-architecture.md index c0e2c92c..7289be99 100644 --- a/docs/skills/marketing-skill/site-architecture.md +++ b/docs/skills/marketing-skill/site-architecture.md @@ -21,7 +21,7 @@ You are an expert in website information architecture and technical SEO structur ## Before Starting **Check for context first:** -If `marketing-context.md` exists, read it before asking questions. +If `.claude/product-marketing-context.md` exists, read it before asking questions. Gather this context: diff --git a/docs/skills/marketing-skill/social-media-analyzer.md b/docs/skills/marketing-skill/social-media-analyzer.md index db55af22..a3401e8b 100644 --- a/docs/skills/marketing-skill/social-media-analyzer.md +++ b/docs/skills/marketing-skill/social-media-analyzer.md @@ -1,6 +1,6 @@ --- title: "Social Media Analyzer — Agent Skill for Marketing" -description: "Social media campaign analysis and performance tracking. Calculates engagement rates, ROI, and benchmarks across platforms. Use for analyzing social. Agent skill for Claude Code, Codex CLI, Gemini CLI, OpenClaw." +description: "Social media campaign analysis and performance tracking. Calculates engagement rates, ROI, and benchmarks across platforms. Use when analyzing social. Agent skill for Claude Code, Codex CLI, Gemini CLI, OpenClaw." --- # Social Media Analyzer diff --git a/docs/skills/marketing-skill/social-media-manager.md b/docs/skills/marketing-skill/social-media-manager.md index f5eefa8d..65bbcf62 100644 --- a/docs/skills/marketing-skill/social-media-manager.md +++ b/docs/skills/marketing-skill/social-media-manager.md @@ -21,7 +21,7 @@ You are a senior social media strategist who has grown accounts from zero to six ## Before Starting **Check for marketing context first:** -If `marketing-context.md` exists, read it for brand voice, audience personas, and goals. Only ask for what's missing. +If `.claude/product-marketing-context.md` exists, read it for brand voice, audience personas, and goals. Only ask for what's missing. Gather this context (ask if not provided): @@ -97,6 +97,14 @@ The 10% promotional cap is intentional. If your feed feels like an ad channel, p | Thu | Educational | Thread or how-to | Deep-dive content | | Fri | Social Proof or Promo | Case study or launch | End-of-week conversion focus | +### Generate the Calendar (bundled tool) + +```bash +python3 scripts/social_calendar_generator.py --config calendar.json --start 2026-06-15 --weeks 4 --markdown +``` + +Give it your pillars + platforms + cadence (no config = embedded demo; `--json` for pipelines); it emits a calendar with balanced pillar distribution. Use its output as the working calendar for the batch workflow below — rebalance manually only when a campaign (launch, event) needs to override a pillar slot. + ### Batch Creation Workflow ``` diff --git a/docs/skills/marketing-skill/video-content-strategist.md b/docs/skills/marketing-skill/video-content-strategist.md index d71c3548..9f498ef4 100644 --- a/docs/skills/marketing-skill/video-content-strategist.md +++ b/docs/skills/marketing-skill/video-content-strategist.md @@ -24,7 +24,7 @@ Video is the highest-trust content format. A viewer who watches 10 minutes of yo ## Before Starting -**Check for context first:** If marketing-context.md exists, read it before asking questions. It contains brand voice, audience, competitor analysis, and existing content assets. +**Check for context first:** If `.claude/product-marketing-context.md` exists, read it before asking questions. It contains brand voice, audience, competitor analysis, and existing content assets. Gather this context (ask in one shot): diff --git a/docs/skills/marketing-skill/webinar-marketing.md b/docs/skills/marketing-skill/webinar-marketing.md index 8c0a3f67..cd939f26 100644 --- a/docs/skills/marketing-skill/webinar-marketing.md +++ b/docs/skills/marketing-skill/webinar-marketing.md @@ -23,7 +23,7 @@ A webinar is a funnel, not an event. Registrations are cheap; attention and acti ## Before Starting **Check for context first:** -If `marketing-context.md` exists, read it before asking questions. Use it for brand voice, audience personas, and customer language, and only ask for what's specific to this event. +If `.claude/product-marketing-context.md` exists, read it before asking questions. Use it for brand voice, audience personas, and customer language, and only ask for what's specific to this event. Gather this context (ask conversationally, one section at a time — don't dump every question at once): @@ -63,7 +63,21 @@ When there's no webinar yet — design the whole motion. When a webinar exists or recently ran and the numbers disappoint. Diagnose where the funnel breaks before rewriting anything. 1. Get the actual numbers: invited → registered → showed up → engaged → converted -2. Score the funnel with `scripts/webinar_funnel_scorer.py` to find the weakest stage +2. Score the funnel with `scripts/webinar_funnel_scorer.py` to find the weakest stage: + + ```bash + # Score a funnel from a JSON file (registrations + attended_live required; + # page_visits, cta_clicks, conversions, audience, runtime_min, avg_watch_min optional) + python3 scripts/webinar_funnel_scorer.py funnel.json + + # Or pipe JSON via stdin + cat funnel.json | python3 scripts/webinar_funnel_scorer.py - + + # Demo mode on embedded sample data + python3 scripts/webinar_funnel_scorer.py --sample + ``` + + Output: a 0-100 scorecard per stage against audience-temperature benchmarks (`customers` / `warm` / `owned_cold` / `paid_cold`), the bottleneck stage flagged, plus a JSON block for downstream use. 3. Fix the stage that's actually broken — don't rewrite the landing page when the problem is show-up rate 4. Deliver: diagnosis (where it breaks + why) + targeted fixes ranked by impact diff --git a/docs/skills/product-team/apple-hig-expert.md b/docs/skills/product-team/apple-hig-expert.md index 332b73bd..9412e6c7 100644 --- a/docs/skills/product-team/apple-hig-expert.md +++ b/docs/skills/product-team/apple-hig-expert.md @@ -1,6 +1,6 @@ --- title: "Apple HIG Expert — Agent Skill for Product Teams" -description: "Expert guidance on Apple Human Interface Guidelines (HIG). Covers iOS, macOS, and visionOS with 2026 Liquid Glass aesthetics and accessibility-first. Agent skill for Claude Code, Codex CLI, Gemini CLI, OpenClaw." +description: "Audits and designs iOS/macOS/watchOS/visionOS interfaces against the Apple Human Interface Guidelines, including the Liquid Glass design language. Agent skill for Claude Code, Codex CLI, Gemini CLI, OpenClaw." --- # Apple HIG Expert @@ -16,80 +16,98 @@ description: "Expert guidance on Apple Human Interface Guidelines (HIG). Covers </div> -You are a Senior Apple Design Lead with decades of experience shipping award-winning apps on the App Store. Your goal is to help users design and audit apps that feel natively integrated into the Apple ecosystem while pushing the boundaries of the **Liquid Glass** aesthetic. +Design and audit apps against the Apple Human Interface Guidelines (HIG, [developer.apple.com/design/human-interface-guidelines](https://developer.apple.com/design/human-interface-guidelines)), including the **Liquid Glass** design language. HIG content evolves with each OS release — when a claim matters, verify against the live HIG pages cited in `references/`. ## Before Starting -**Check for context first:** -If `product-context.md` or `ios-design-context.md` exists, read it before asking questions. +If `product-context.md` or `ios-design-context.md` exists, read it before asking questions. Then gather: -Gather this context: -1. **Platform Target**: iOS, macOS, watchOS, or visionOS? -2. **Current State**: New project or auditing an existing mockup? -3. **App Category**: Utility, Productivity, Game, Social, etc.? +1. **Platform target**: iOS, macOS, watchOS, or visionOS? +2. **Current state**: new design or auditing an existing mockup/code? +3. **App category**: utility, productivity, game, social, etc. -## How This Skill Works +## Modes -This skill supports 2 primary modes: +- **Mode 1 — Design from scratch**: pick the platform navigation paradigm and layout primitives first (see `references/platform-specifics.md`), then apply typography and semantic color (`references/visual-design.md`). +- **Mode 2 — HIG audit**: fill in `templates/hig-audit-template.md`, run `scripts/hig_checker.py` on every measurable element, and deliver a scored report (see Worked example below). -### Mode 1: Design from Scratch -When starting fresh. Focus on atomic design, layout primitives, and navigation paradigms that align with Apple's core philosophies (Clarity, Deference, Depth). +## The Compliance Tool -### Mode 2: HIG Audit -When reviewing mockups or code. Use the [templates/hig-audit-template.md](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/apple-hig-expert/skills/apple-hig-expert/templates/hig-audit-template.md) to systematically identify violations and refinement opportunities. +`scripts/hig_checker.py` (stdlib-only) has three subcommands: -## Core Design Principles (2026) +```bash +# 1. Contrast ratio (WCAG formula; pass >= 4.5:1 for normal text) +python3 scripts/hig_checker.py contrast "#8E8E93" "#FFFFFF" +# -> Contrast Ratio: 3.26 [FAILED] -### 1. Liquid Glass Aesthetic -Modern Apple design emphasizes translucency and fluid motion. -- **Translucency**: Use materials (thin, thick, ultra-thin) to create hierarchy. -- **Depth**: Layers should reflect z-axis relationships. -- **Fluidity**: Interactions should feel like physical objects responding to touch/eyes. +# 2. Tap-target size (pass >= 44x44 pt per HIG) +python3 scripts/hig_checker.py target 32 32 +# -> Tap Target: 32x32 [FAILED] -### 2. Accessibility First -Design for everyone from Day 1. -- **VoiceOver**: All elements must have semantic descriptions. -- **Tap Targets**: Minimum 44x44 points for all interactive elements. -- **Contrast**: Ensure legibility against translucent backgrounds. +# 3. Batch audit from JSON -> scorecard (starts at 100, -10 per violation) +python3 scripts/hig_checker.py batch audit.json +``` -## Workflows +Batch input shape: -### Phase 1: Navigation & Layout -Choose the right navigation pattern (Sidebars for macOS, Tab Bars for iOS, Ornaments for visionOS). -See [references/platform-specifics.md](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/apple-hig-expert/skills/apple-hig-expert/references/platform-specifics.md) for details. +```json +{ + "checks": [ + {"type": "contrast", "name": "caption-on-card", "fg": "#8E8E93", "bg": "#FFFFFF"}, + {"type": "target", "name": "close-button", "w": 32, "h": 32} + ] +} +``` -### Phase 2: Visual Styling -Apply typography (San Francisco family) and semantic colors. -See [references/visual-design.md](https://github.com/alirezarezvani/claude-skills/tree/main/product-team/apple-hig-expert/skills/apple-hig-expert/references/visual-design.md). +**Scorecard rubric:** the batch score starts at 100 and subtracts 10 per failed check; violations are listed by element name. 90-100 = ship, 70-80 = fix before release, below 70 = systematic rework. Checks the tool cannot measure (VoiceOver labels, Dynamic Type behavior, Reduce Transparency) are assessed manually via the audit template and tagged with confidence. -### Phase 3: Final Audit -Run the `hig_checker.py` tool to automate contrast and layout checks. +## Worked example: iOS settings-screen audit + +**Input:** mockup with body text `#1C1C1E` and captions `#8E8E93` on white cards, a 32x32 pt close button, and a 343x50 pt primary CTA. + +**Run:** + +```bash +python3 scripts/hig_checker.py batch audit.json +``` + +**Output (real):** + +```json +{ + "score": 80, + "violations": [ + "Contrast 3.26 fails for caption-on-card", + "Target 32x32 small for close-button" + ] +} +``` + +**Findings → fixes (bottom line first):** + +> **HIG score 80/100 — two fixes before release.** +> 1. Captions fail contrast (3.26 < 4.5). Use `.secondaryLabel` (semantic color) instead of hardcoded `#8E8E93`, or darken to ≥ `#6E6E73` on white. 🟢 verified by tool. +> 2. Close button is 32x32 pt (< 44x44 minimum). Keep the glyph small but expand the hit region to 44x44 with padding/`contentShape`. 🟢 verified by tool. +> 3. Manual check: the card uses an ultra-thin material over a photo background — re-test caption contrast against the *busiest* underlying region and with Reduce Transparency on. 🟡 needs device test. + +## Core Design Principles + +1. **Liquid Glass** — translucent material hierarchy (announced at WWDC25, June 2025; shipped Sept 2025 across iOS 26, iPadOS 26, macOS Tahoe, watchOS 26, tvOS 26, visionOS 26). In SwiftUI, apply it via the `glassEffect` view modifier; keep hierarchy between content and controls. See `references/visual-design.md`. +2. **Accessibility first** — VoiceOver labels on every element, 44x44 pt minimum targets, 4.5:1 contrast for normal text (3:1 large text), Dynamic Type support. See `references/accessibility.md`. +3. **Platform ergonomics** — tab bars/thumb reach on iOS, sidebars + menu bar + shortcuts on macOS, ornaments + gaze states on visionOS, glanceable vertical layouts on watchOS. See `references/platform-specifics.md`. ## Proactive Triggers -Surface these issues WITHOUT being asked: -- **Low Contrast**: Translucent layers masking text legibility. -- **Tiny Targets**: Interactive elements smaller than 44pt. -- **Missing Semantics**: Buttons with icons but no accessibility labels. -- **Density Overload**: Layouts that ignore white space/deference. - -## Output Artifacts - -| When you ask for... | You get... | -|---------------------|------------| -| "Audit my iOS app" | Detailed HIG Scorecard (0-100) with prioritized fixes. | -| "Design a visionOS ornament" | Spatial design specs with depth and gaze-contingent hover rules. | -| "Accessibility check" | Compliance report for VoiceOver, Dynamic Type, and Contrast. | +Surface these WITHOUT being asked: low contrast over translucent layers; interactive elements under 44 pt; icon buttons with no accessibility label; density overload (no breathing room between glass layers). ## Communication -All output follows the structured communication standard: -- **Bottom line first** — HIG compliance status before the details. -- **What + Why + How** — e.g., "Increase padding (What) because targets are too small (Why). Use 12pt margins (How)." -- **Confidence tagging** — 🟢 verified / 🟡 medium / 🔴 assumed. +- **Bottom line first** — compliance status before details. +- **What + Why + How** — "Expand the hit region (What) because 32 pt targets fail the HIG minimum (Why); pad to 44x44 via contentShape (How)." +- **Confidence tagging** — 🟢 tool-verified / 🟡 needs device test / 🔴 assumed. ## Related Skills -- **ui-design-system**: For creating token-based components. NOT for platform-specific HIG rules. -- **ux-researcher-designer**: For persona validation. NOT for visual styling. -- **landing-page-generator**: For web-based marketing pages. +- **ui-design-system**: token-based component systems (not platform HIG rules). +- **ux-researcher-designer**: persona/research validation (not visual styling). +- **landing-page-generator**: web marketing pages, not native apps. diff --git a/docs/skills/product-team/index.md b/docs/skills/product-team/index.md index a7d780a6..7a743b63 100644 --- a/docs/skills/product-team/index.md +++ b/docs/skills/product-team/index.md @@ -53,11 +53,11 @@ description: "17 product skills — product management agent skill and Claude Co Essential tools and frameworks for modern product management, from discovery to delivery. -- **[Product Team Skills](product-skills.md)** +- **[Product Skills — Router](product-skills.md)** --- - 8 production-ready product skills covering product management, UX/UI design, and SaaS development. + This plugin bundles 12 product skills (this router is the 13th folder under product-team/skills/). Each skill is self... - **[Product Strategist](product-strategist.md)** diff --git a/docs/skills/product-team/landing-page-generator.md b/docs/skills/product-team/landing-page-generator.md index af496576..5e4302a3 100644 --- a/docs/skills/product-team/landing-page-generator.md +++ b/docs/skills/product-team/landing-page-generator.md @@ -41,7 +41,7 @@ Generate high-converting landing pages from a product description. Output comple Follow these steps in order for every landing page request: 1. **Gather inputs** — collect product name, tagline, audience, pain point, key benefit, pricing tiers, design style, and copy framework using the trigger format below. Ask only for missing fields. -2. **Analyze brand voice** (recommended) — if the user has existing brand content (website copy, blog posts, marketing materials), run it through `marketing-skill/content-production/scripts/brand_voice_analyzer.py` to get a voice profile (formality, tone, perspective). Use the profile to inform design style and copy framework selection: +2. **Analyze brand voice** (recommended) — if the user has existing brand content (website copy, blog posts, marketing materials), run it through `marketing-skill/skills/content-production/scripts/brand_voice_analyzer.py` to get a voice profile (formality, tone, perspective). Use the profile to inform design style and copy framework selection: - formal + professional → **enterprise** style, **AIDA** framework - casual + friendly → **bold-startup** style, **BAB** framework - professional + authoritative → **dark-saas** style, **PAS** framework @@ -204,6 +204,6 @@ Inject `FAQPage` JSON-LD via `<script type="application/ld+json" dangerouslySetI ## Related Skills -- **Brand Voice Analyzer** (`marketing-skill/content-production/scripts/brand_voice_analyzer.py`) — Run before generation to establish voice profile and ensure copy consistency +- **Brand Voice Analyzer** (`marketing-skill/skills/content-production/scripts/brand_voice_analyzer.py`) — Run before generation to establish voice profile and ensure copy consistency - **UI Design System** (`product-team/ui-design-system/`) — Generate design tokens from brand color before building the page - **Competitive Teardown** (`product-team/competitive-teardown/`) — Competitive positioning informs landing page messaging and differentiation diff --git a/docs/skills/product-team/product-skills.md b/docs/skills/product-team/product-skills.md index 46b708bd..857b60dd 100644 --- a/docs/skills/product-team/product-skills.md +++ b/docs/skills/product-team/product-skills.md @@ -1,9 +1,9 @@ --- -title: "Product Team Skills — Agent Skill for Product Teams" -description: "10 product agent skills and plugins for Claude Code, Codex, Gemini CLI, Cursor, OpenClaw. PM toolkit (RICE), agile PO, product strategist (OKR), UX." +title: "Product Skills — Router — Agent Skill for Product Teams" +description: "Router/index for the 12 product skills bundled in this plugin (RICE prioritization, OKRs, UX research, design tokens, competitive teardown. Agent skill for Claude Code, Codex CLI, Gemini CLI, OpenClaw." --- -# Product Team Skills +# Product Skills — Router <div class="page-meta" markdown> <span class="meta-badge">:material-lightbulb-outline: Product</span> @@ -16,43 +16,43 @@ description: "10 product agent skills and plugins for Claude Code, Codex, Gemini </div> -8 production-ready product skills covering product management, UX/UI design, and SaaS development. +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/`. -## Quick Start +## Routing table -### Claude Code -``` -/read product-team/product-manager-toolkit/SKILL.md -``` +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. -### Codex CLI -```bash -npx agent-skills-cli add alirezarezvani/claude-skills/product-team -``` +| 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/` | -## Skills Overview - -| Skill | Folder | Focus | -|-------|--------|-------| -| Product Manager Toolkit | `product-manager-toolkit/` | RICE prioritization, customer discovery, PRDs | -| Agile Product Owner | `agile-product-owner/` | User stories, sprint planning, backlog | -| Product Strategist | `product-strategist/` | OKR cascades, market analysis, vision | -| UX Researcher Designer | `ux-researcher-designer/` | Personas, journey maps, usability testing | -| UI Design System | `ui-design-system/` | Design tokens, component docs, responsive | -| Competitive Teardown | `competitive-teardown/` | Systematic competitor analysis | -| Landing Page Generator | `landing-page-generator/` | Conversion-optimized pages | -| SaaS Scaffolder | `saas-scaffolder/` | Production SaaS boilerplate | - -## Python Tools - -9 scripts, all stdlib-only: +## Quick start ```bash -python3 product-manager-toolkit/scripts/rice_prioritizer.py --help -python3 product-strategist/scripts/okr_cascade_generator.py --help +# 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 ``` +## Related product-team plugins (packaged separately, not in this bundle) + +- `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 + ## Rules -- Load only the specific skill SKILL.md you need -- Use Python tools for scoring and analysis, not manual judgment +- 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. diff --git a/docs/skills/product-team/research-summarizer.md b/docs/skills/product-team/research-summarizer.md index a6c65caf..65237a80 100644 --- a/docs/skills/product-team/research-summarizer.md +++ b/docs/skills/product-team/research-summarizer.md @@ -24,13 +24,16 @@ Not a generic "summarize this" — a repeatable framework that extracts what mat --- -## Slash Commands +## Scope — Distinct From the research/ Domain -| Command | What it does | -|---------|-------------| -| `/research:summarize` | Summarize a single source into a structured brief | -| `/research:compare` | Compare 2-5 sources side-by-side with synthesis | -| `/research:cite` | Extract and format all citations from a document | +This skill summarizes **documents the user already has** (papers, articles, reports pasted or attached). It performs no web search and needs no MCP server. It is NOT: + +- `research/litreview` — academic literature *discovery* and review-guide generation (finds papers via Consensus/academic APIs) +- `research/dossier` — entity due-diligence built from live web research +- `research/notebooklm` — drives Google's NotebookLM product UI +- `research/research` — the router for open-ended "research [topic]" requests that require searching + +If the user asks you to *find* sources rather than digest supplied ones, route to the research/ domain instead. --- @@ -52,7 +55,7 @@ If the user has a document and wants structured understanding → this skill app ## Workflow -### `/research:summarize` — Single Source Summary +### Workflow 1 — Single Source Summary 1. **Identify source type** - Academic paper → use IMRAD structure (Introduction, Methods, Results, Analysis, Discussion) @@ -60,7 +63,7 @@ If the user has a document and wants structured understanding → this skill app - Technical report → use executive summary structure - Documentation → use reference summary structure -2. **Extract structured brief** +2. **Scaffold the brief** — `python3 scripts/format_summary.py --template academic` (or `article`/`report`/`executive` per source type), then fill in every section from the source: ``` Title: [exact title] Author(s): [names] @@ -94,7 +97,7 @@ If the user has a document and wants structured understanding → this skill app - Recency (when published, still relevant?) - Bias indicators (funding source, author affiliation, methodology gaps) -### `/research:compare` — Multi-Source Comparison +### Workflow 2 — Multi-Source Comparison 1. **Collect sources** (2-5 documents) 2. **Summarize each** using the single-source workflow above @@ -131,10 +134,10 @@ If the user has a document and wants structured understanding → this skill app [Based on weight of evidence, what should the reader believe/do?] ``` -### `/research:cite` — Citation Extraction +### Workflow 3 — Citation Extraction -1. **Scan document** for all references, footnotes, in-text citations -2. **Extract and format** using the requested style (APA 7 default) +1. **Run the extractor** — `python3 scripts/extract_citations.py document.txt --output json` detects DOI/URL/author-year/numbered citations and deduplicates them +2. **Review and format** the extracted list in the requested style (APA 7 default); manually catch citations the regex missed 3. **Classify citations** by type: - Primary sources (original research, data) - Secondary sources (reviews, meta-analyses, commentary) @@ -179,13 +182,12 @@ cat paper.txt | python3 scripts/extract_citations.py --stdin ### `scripts/format_summary.py` -CLI utility for generating structured research summaries. +CLI utility that emits **blank structured summary scaffolds** — you (the model) fill them in from the source. It does not analyze content itself. **Features:** -- Multiple summary templates (academic, article, report, executive) -- Configurable output length (brief, standard, detailed) -- Markdown and plain text output -- Key findings extraction with evidence tagging +- 6 templates: academic, article, report, executive, comparison, literature +- Configurable scaffold depth (brief, standard, detailed) +- Text and JSON output for downstream tooling **Usage:** ```bash @@ -259,7 +261,7 @@ git clone https://github.com/alirezarezvani/claude-skills.git cp -r claude-skills/product-team/research-summarizer ~/.claude/skills/ ``` -### Multi-tool install +### Multi-tool install (run from the claude-skills repo root) ```bash ./scripts/convert.sh --skill research-summarizer --tool codex|gemini|cursor|windsurf|openclaw ``` @@ -271,6 +273,18 @@ clawhub install cs-research-summarizer --- +## Verification Loop + +Before delivering any brief, check: + +1. Every Key Finding cites a location in the source (section, page, or quote) — no unanchored claims. +2. `python3 scripts/extract_citations.py <file> --output json` exits 0 and its `total` matches the bibliography count in your output (investigate any gap). +3. Each source carries a 4-dimension quality rating (table above); weak sources are flagged, not silently included. +4. For comparisons: the matrix has one row per dimension and one column per source — no source skipped. +5. Nothing was invented: missing metadata is marked "not stated", never filled in. + +--- + ## Related Skills - **product-analytics** — Quantitative analysis. Complementary — use research-summarizer for qualitative sources, product-analytics for metrics. diff --git a/docs/skills/productivity/email-inbox-triage.md b/docs/skills/productivity/email-inbox-triage.md index 3baf333b..4e22e401 100644 --- a/docs/skills/productivity/email-inbox-triage.md +++ b/docs/skills/productivity/email-inbox-triage.md @@ -294,7 +294,7 @@ Skip Steps 3–6 entirely on empty inbox. ## References -- [`references/kb_file_contract.md`](https://github.com/alirezarezvani/claude-skills/tree/main/productivity/email/skills/inbox-triage/references/kb_file_contract.md) — canonical 7-file contract (read perspective; mirrors `inbox-setup/references/kb_file_contract.md`) +- [`references/kb_file_contract.md`](https://github.com/alirezarezvani/claude-skills/tree/main/productivity/email/skills/inbox-triage/references/kb_file_contract.md) — canonical 7-file contract (read perspective; mirrors [`references/kb_file_contract.md`](https://github.com/alirezarezvani/claude-skills/tree/main/productivity/email/skills/inbox-setup/references/kb_file_contract.md)) - [`references/triage_decision_framework.md`](https://github.com/alirezarezvani/claude-skills/tree/main/productivity/email/skills/inbox-triage/references/triage_decision_framework.md) — TAKE IT / WORTH / PASS / FLAG taxonomy - [`references/drafts_only_safety.md`](https://github.com/alirezarezvani/claude-skills/tree/main/productivity/email/skills/inbox-triage/references/drafts_only_safety.md) — the NEVER-SEND discipline canon diff --git a/docs/skills/project-management/atlassian-admin.md b/docs/skills/project-management/atlassian-admin.md index 9e1c02b2..2d7bae3e 100644 --- a/docs/skills/project-management/atlassian-admin.md +++ b/docs/skills/project-management/atlassian-admin.md @@ -225,21 +225,17 @@ description: "Atlassian Administrator for managing and organizing Atlassian prod **TO Scrum Master**: Team access provisioned, board configuration options, automation rules, integrations enabled **FROM All Roles**: User access requests, permission changes, app installation requests, configuration support, incident reports -## Atlassian MCP Integration +## Atlassian MCP Integration — scope limits -**Primary Tools**: Jira MCP, Confluence MCP +**Admin operations are NOT available via the Atlassian Remote MCP server** (bundled `.mcp.json`, server key `atlassian`). The canonical tool list (`project-management/references/atlassian-mcp-tools.md`) contains no tools for user/group management, permission schemes, field/workflow configuration, SSO, app management, or org settings. Never invent tool names — every admin workflow in this skill runs through `admin.atlassian.com` or the REST APIs cited inline above. -**Admin Operations**: -- User and group management via API -- Bulk permission updates -- Configuration audits -- Usage reporting -- System health monitoring -- Automated compliance checks +**What MCP CAN contribute to admin work** (read-mostly support): +- `mcp__atlassian__lookupJiraAccountId` — resolve users to `accountId` before deprovisioning audits +- `mcp__atlassian__searchJiraIssuesUsingJql` — find a leaver's open issues (`assignee = <accountId>`) for reassignment +- `mcp__atlassian__getVisibleJiraProjects` / `mcp__atlassian__getConfluenceSpaces` — inventory inputs for access reviews +- `mcp__atlassian__atlassianUserInfo` / `mcp__atlassian__getAccessibleAtlassianResources` — verify the acting identity and accessible sites **Integration Points**: -- Support all roles with admin capabilities -- Enable Jira Expert with global configurations -- Provide Confluence Expert with template management -- Ensure Senior PM has visibility into org health -- Enable Scrum Master with team provisioning +- Support Jira/Confluence Experts by performing UI/REST admin changes they cannot do via MCP +- Ensure Senior PM has visibility into org health (exports from admin.atlassian.com) +- Enable Scrum Master with team provisioning (admin console) diff --git a/docs/skills/project-management/atlassian-templates.md b/docs/skills/project-management/atlassian-templates.md index 078aa57d..366788ca 100644 --- a/docs/skills/project-management/atlassian-templates.md +++ b/docs/skills/project-management/atlassian-templates.md @@ -59,7 +59,7 @@ Specialist in creating, modifying, and managing reusable templates and files for ## Confluence Templates Library -See **TEMPLATES.md** for full reference tables and copy-paste-ready template structures. The following summarises the standard types this skill creates and maintains. +See `references/template-design-patterns.md` for template design patterns and `references/governance-framework.md` for the governance model. For deployment-ready storage-format markup, use the bundled scaffolder (see [Template scaffolder](#template-scaffolder-generate-storage-format-markup) below). The following summarises the standard types this skill creates and maintains. ### Confluence Template Types | Template | Purpose | Key Macros Used | @@ -78,7 +78,7 @@ See **TEMPLATES.md** for full reference tables and copy-paste-ready template str ### Complete Example: Meeting Notes Template -The following is a copy-paste-ready Meeting Notes template in Confluence storage format (wiki markup): +> **Format warning**: The example below is **legacy wiki markup** (`{panel}`, `h2.`, `{tasks}`), shown for human readability. Wiki markup is NOT Confluence storage format and **will be rejected** by `mcp__atlassian__createConfluencePage` / `updateConfluencePage`, which expect storage format (XHTML, `<ac:structured-macro>` elements) or ADF. To get the deployment-ready storage-format equivalent, run the scaffolder: `python3 scripts/template_scaffolder.py meeting-notes` (see [Template scaffolder](#template-scaffolder-generate-storage-format-markup)). ``` {panel:title=Meeting Metadata|borderColor=#0052CC|titleBGColor=#0052CC|titleColor=#FFFFFF} @@ -115,7 +115,7 @@ h2. Next Steps & Related Links * Related Jira issues: {jira:key=PROJ-123} ``` -> Full examples for all other template types (Project Charter, Sprint Retrospective, PRD, Decision Log) and all Jira templates can be generated on request or found in **TEMPLATES.md**. +> Storage-format examples for the other built-in types (decision-log, runbook, project-kickoff) come from `python3 scripts/template_scaffolder.py --list`; design patterns for the remaining types (Project Charter, Sprint Retrospective, PRD) are in `references/template-design-patterns.md`. --- @@ -145,82 +145,63 @@ h2. Next Steps & Related Links --- +## Template scaffolder — generate storage-format markup + +The bundled scaffolder emits **Confluence storage-format XHTML** — the exact body format `createConfluencePage`/`updateConfluencePage` accept. It is the canonical deployment path for this skill: + +```bash +# List available template types (meeting-notes, decision-log, runbook, project-kickoff, custom) +python3 scripts/template_scaffolder.py --list + +# Generate a template body (storage-format XHTML) +python3 scripts/template_scaffolder.py meeting-notes + +# Custom template with chosen sections and macros, JSON output for programmatic use +python3 scripts/template_scaffolder.py custom --sections "Overview,Goals,Action Items" --macros "toc,status,info" --format json +``` + +Consume the output: take the `CONFLUENCE STORAGE FORMAT MARKUP` block (text mode) or the markup field (JSON mode) and pass it verbatim as the `body` of `mcp__atlassian__createConfluencePage`. Apply the suggested labels via the Confluence UI afterwards (label tools are not on the MCP). + ## Atlassian MCP Integration -**Primary Tools**: Confluence MCP, Jira MCP +**Primary Tool**: Atlassian Remote MCP server (bundled `.mcp.json`, server key `atlassian`). Tools surface as `mcp__atlassian__<toolName>` (camelCase). **Canonical tool list**: `project-management/references/atlassian-mcp-tools.md`. Never invent tool names — if a capability isn't in that list, it is not available via MCP; route to the web UI or REST API. ### Template Operations via MCP -All MCP calls below use the exact parameter names expected by the Atlassian MCP server. Replace angle-bracket placeholders with real values before executing. +Obtain `cloudId` once via `mcp__atlassian__getAccessibleAtlassianResources`. Replace angle-bracket placeholders with real values; discover exact parameter names from each tool's schema at call time. -**Create a Confluence page template:** -```json -{ - "tool": "confluence_create_page", - "parameters": { - "space_key": "PROJ", - "title": "Template: Meeting Notes", - "body": "<storage-format template content>", - "labels": ["template", "meeting-notes"], - "parent_id": "<optional parent page id>" - } -} +**Create a Confluence template page** (body from the scaffolder above): +``` +mcp__atlassian__createConfluencePage (cloudId, space, title="Template: Meeting Notes", + body=<storage-format XHTML from template_scaffolder.py>, parent page id optional) +``` +Labels (`template`, `meeting-notes`) must be applied in the Confluence UI — there is no MCP label tool. + +**Update an existing template page** (read first to get the current version): +``` +mcp__atlassian__getConfluencePage (cloudId, pageId=<existing page id>) +mcp__atlassian__updateConfluencePage (cloudId, pageId=<id>, version=<current + 1>, + body=<updated storage-format content>) ``` -**Update an existing template:** -```json -{ - "tool": "confluence_update_page", - "parameters": { - "page_id": "<existing page id>", - "version": "<current_version + 1>", - "title": "Template: Meeting Notes", - "body": "<updated storage-format content>", - "version_comment": "v2 — added status macro to header" - } -} -``` +**Jira issue description templates**: there is **no MCP tool for field configuration** (`default_value` on the description field, screens, field contexts). Configure description defaults in the Jira admin UI (`Settings > Issues > Field configurations`) or via REST (`/rest/api/3/fieldconfiguration`). What MCP CAN do: create issues pre-filled with template text via `mcp__atlassian__createJiraIssue` (pass the template body as the description), and inspect required fields per issue type with `mcp__atlassian__getJiraIssueTypeMetaWithFields`. -**Create a Jira issue description template (via field configuration):** -```json -{ - "tool": "jira_update_field_configuration", - "parameters": { - "project_key": "PROJ", - "field_id": "description", - "default_value": "<template markdown or Atlassian Document Format JSON>" - } -} -``` +**First-class Confluence templates/blueprints** are also **not creatable via MCP** — `createConfluencePage` creates ordinary pages that serve as copy-from templates. To register a real space template, use `Space settings > Templates` in the UI. -**Deploy template to multiple spaces (batch):** -```json -// Repeat for each target space key -{ - "tool": "confluence_create_page", - "parameters": { - "space_key": "<SPACE_KEY>", - "title": "Template: Meeting Notes", - "body": "<storage-format template content>", - "labels": ["template"] - } -} -// After each create, verify: -{ - "tool": "confluence_get_page", - "parameters": { - "space_key": "<SPACE_KEY>", - "title": "Template: Meeting Notes" - } -} -// Assert response status == 200 and page body is non-empty before proceeding to next space +**Deploy a template page to multiple spaces (batch):** +``` +# Repeat per target space: +mcp__atlassian__createConfluencePage (cloudId, space=<target>, title="Template: Meeting Notes", body=<storage-format content>) +# Verify each create before proceeding: +mcp__atlassian__getConfluencePage (cloudId, pageId=<id returned by create>) +# Assert the returned body is non-empty and contains the expected <ac:structured-macro> elements ``` **Validation checkpoint after deployment:** -- Retrieve the created/updated page and assert it renders without macro errors -- Check that `{jira}` embeds resolve against the target Jira project -- Confirm `{tasks}` blocks are interactive in the published view -- If any check fails: revert using `confluence_update_page` with `version: <current + 1>` and the previous version body +- Retrieve the created/updated page via `mcp__atlassian__getConfluencePage` and assert it renders without macro errors +- Check that Jira-macro embeds resolve against the target Jira project +- Confirm task blocks are interactive in the published view +- If any check fails: revert using `mcp__atlassian__updateConfluencePage` with `version: <current + 1>` and the previous version body --- @@ -252,7 +233,7 @@ All MCP calls below use the exact parameter names expected by the Atlassian MCP ## Handoff Protocols -See **HANDOFFS.md** for the full handoff matrix. Summary: +Handoff summary (governance context in `references/governance-framework.md`): | Partner | Receives FROM | Sends TO | |---------|--------------|---------| diff --git a/docs/skills/project-management/confluence-expert.md b/docs/skills/project-management/confluence-expert.md index ef002c6b..7559a5c5 100644 --- a/docs/skills/project-management/confluence-expert.md +++ b/docs/skills/project-management/confluence-expert.md @@ -20,46 +20,60 @@ Master-level expertise in Confluence space management, documentation architectur ## Atlassian MCP Integration -**Primary Tool**: Confluence MCP Server +**Primary Tool**: Atlassian Remote MCP server (bundled `.mcp.json`, server key `atlassian`). Tools are camelCase and surface as `mcp__atlassian__<toolName>`. **Canonical tool list**: `project-management/references/atlassian-mcp-tools.md`. Never invent tool names — if a capability isn't in that list, it is not available via MCP. -**Key Operations**: +**Key Operations** (obtain `cloudId` once via `mcp__atlassian__getAccessibleAtlassianResources`): ``` -// Create a new space -create_space({ key: "TEAM", name: "Engineering Team", description: "Engineering team knowledge base" }) +// List spaces (space CREATION is not available via MCP — see below) +mcp__atlassian__getConfluenceSpaces (cloudId) -// Create a page under a parent -create_page({ spaceKey: "TEAM", title: "Sprint 42 Notes", parentId: "123456", body: "<p>Meeting notes in storage-format HTML</p>" }) +// Create a page under a parent — body must be storage-format XHTML or ADF, never wiki markup +mcp__atlassian__createConfluencePage (cloudId, space, title="Sprint 42 Notes", parent page id, body="<p>Meeting notes in storage-format XHTML</p>") -// Update an existing page (version must be incremented) -update_page({ pageId: "789012", version: 4, body: "<p>Updated content</p>" }) +// Update an existing page (fetch current version with getConfluencePage, then supply version + 1) +mcp__atlassian__updateConfluencePage (cloudId, pageId="789012", version=5, body="<p>Updated content</p>") -// Delete a page -delete_page({ pageId: "789012" }) +// Read a page (body + current version) +mcp__atlassian__getConfluencePage (cloudId, pageId="789012") // Search with CQL -search({ cql: 'space = "TEAM" AND label = "meeting-notes" ORDER BY lastModified DESC' }) +mcp__atlassian__searchConfluenceUsingCql (cloudId, cql='space = "TEAM" AND label = "meeting-notes" ORDER BY lastModified DESC') // Retrieve child pages for hierarchy inspection -get_children({ pageId: "123456" }) +mcp__atlassian__getConfluencePageDescendants (cloudId, pageId="123456") -// Apply a label to a page -add_label({ pageId: "789012", label: "archived" }) +// Comments +mcp__atlassian__getConfluencePageFooterComments / mcp__atlassian__createConfluenceFooterComment (cloudId, pageId) ``` +**Not available via MCP — use the web UI or REST API instead:** +- Create/delete a **space** → Confluence UI `Spaces > Create space` or `POST /wiki/api/v2/spaces` +- **Delete** a page → Confluence UI or `DELETE /wiki/api/v2/pages/{id}` +- Apply **labels** → Confluence UI or `/wiki/rest/api/content/{id}/label` +- Space **permissions**, templates/blueprints as first-class objects → Confluence space settings UI + **Integration Points**: - Create documentation for Senior PM projects - Support Scrum Master with ceremony templates - Link to Jira issues for Jira Expert - Provide templates for Template Creator -> **See also**: `MACROS.md` for macro syntax reference, `TEMPLATES.md` for full template library, `PERMISSIONS.md` for permission scheme details. +> **See also**: `references/macro-cheat-sheet.md` for storage-format macro syntax, `references/templates.md` for the template library, `references/space-architecture-patterns.md` for space structure and permission patterns. ## Workflows ### Space Creation + +> Space creation is **not available via MCP** — create the space in the Confluence UI (`Spaces > Create space`) or via REST (`POST /wiki/api/v2/spaces`). The page tree inside it CAN be built via MCP (`mcp__atlassian__createConfluencePage`). + +0. Generate the recommended hierarchy from a team description: + ```bash + python3 scripts/space_structure_generator.py team_info.json --format json + ``` + Input: JSON with team `name`, `size`, `type`, `projects`. Consume the output: use the emitted page tree as the creation plan for step 5 — one `mcp__atlassian__createConfluencePage` call per node, passing the parent page id to nest children. 1. Determine space type (Team, Project, Knowledge Base, Personal) -2. Create space with clear name and description +2. Create space with clear name and description (web UI / REST) 3. Set space homepage with overview 4. Configure space permissions: - View, Edit, Create, Delete @@ -116,6 +130,13 @@ Space Home 8. **REPORT TO**: Senior PM on documentation health ### Knowledge Base Management + +**Run a content health audit** before any restructure or governance review: +```bash +python3 scripts/content_audit_analyzer.py pages.json --format json +``` +Input: a JSON page inventory (`title`, `last_modified`, `view_count`, `author`, `labels`, `word_count`) — build it by exporting page metadata via `mcp__atlassian__getPagesInConfluenceSpace` / `mcp__atlassian__searchConfluenceUsingCql`. Consume the output: the stale/orphaned/low-engagement findings become the archive list (label + move via UI, since label tools aren't on the MCP) and the update backlog for the quality standards below. + **Article Types**: - How-to guides - Troubleshooting docs @@ -132,7 +153,7 @@ Space Home ## Essential Macros -> Full macro reference with all parameters: see `MACROS.md`. +> **Syntax note**: The `{macro}` shorthand below is **legacy wiki-markup notation**, shown for readability only. Confluence Cloud pages created via MCP (`createConfluencePage` / `updateConfluencePage`) require **storage format (XHTML)** — e.g. `{info}` is really `<ac:structured-macro ac:name="info"><ac:rich-text-body>...</ac:rich-text-body></ac:structured-macro>`. For the storage-format syntax of every macro listed here, see `references/macro-cheat-sheet.md`; for ready-made storage-format page bodies, run the atlassian-templates scaffolder (`python3 ../atlassian-templates/scripts/template_scaffolder.py meeting-notes`). ### Content Macros **Info, Note, Warning, Tip**: @@ -238,7 +259,7 @@ const example = "code here"; ## Templates Library -> Full template library with complete markup: see `TEMPLATES.md`. Key templates summarised below. +> Full template library with complete markup: see `references/templates.md`. Key templates summarised below. | Template | Purpose | Key Sections | |----------|---------|--------------| @@ -249,7 +270,7 @@ const example = "code here"; ## Space Permissions -> Full permission scheme details: see `PERMISSIONS.md`. +> Permission patterns by space type: see `references/space-architecture-patterns.md`. Note: space permissions are configured in the Confluence UI (`Space settings > Permissions`) — not via MCP. ### Permission Schemes **Public Space**: diff --git a/docs/skills/project-management/index.md b/docs/skills/project-management/index.md index 4f7cf046..591b8cc4 100644 --- a/docs/skills/project-management/index.md +++ b/docs/skills/project-management/index.md @@ -47,11 +47,11 @@ description: "9 project management skills — project management agent skill and > Originally contributed by maximcoding(https://github.com/maximcoding) — enhanced and integrated by the claude-skill... -- **[Project Management Skills](pm-skills.md)** +- **[Project Management Skills — Router](pm-skills.md)** --- - 6 production-ready project management skills with Atlassian MCP integration. + This plugin bundles 8 PM skills (this router is the 9th folder under project-management/skills/). Each skill is self-... - **[Scrum Master Expert](scrum-master.md)** diff --git a/docs/skills/project-management/jira-expert.md b/docs/skills/project-management/jira-expert.md index e43cb973..59f295e6 100644 --- a/docs/skills/project-management/jira-expert.md +++ b/docs/skills/project-management/jira-expert.md @@ -20,25 +20,36 @@ Master-level expertise in Jira configuration, project management, JQL, workflows ## Quick Start — Most Common Operations -**Create a project**: +All MCP examples in this skill use the real Atlassian Remote MCP tools (camelCase, surfaced as `mcp__atlassian__<toolName>`). The canonical tool list is `project-management/references/atlassian-mcp-tools.md` — never invent tool names; if a capability isn't listed there, it is not available via MCP. + +**Create an issue** (call `getAccessibleAtlassianResources` once first to obtain `cloudId`): ``` -mcp jira create_project --name "My Project" --key "MYPROJ" --type scrum --lead "user@example.com" +mcp__atlassian__createJiraIssue (cloudId, projectKey="MYPROJ", issueTypeName="Story", summary="My new story") ``` -**Run a JQL query**: +**Run a JQL query** (build the JQL from natural language with the bundled script, then execute): +```bash +python3 scripts/jql_query_builder.py "high priority bugs assigned to me" +# → emits validated JQL, e.g.: assignee = currentUser() AND type = Bug AND status != Done ``` -mcp jira search_issues --jql "project = MYPROJ AND status != Done AND dueDate < now()" --maxResults 50 +``` +mcp__atlassian__searchJiraIssuesUsingJql (cloudId, jql="project = MYPROJ AND status != Done AND dueDate < now()") ``` -For full command reference, see [Atlassian MCP Integration](#atlassian-mcp-integration). For JQL functions, see [JQL Functions Reference](#jql-functions-reference). For report templates, see [Reporting Templates](#reporting-templates). +**Create a project**: NOT available via MCP. Use the Jira web UI (`Projects > Create project`) or REST API (`POST /rest/api/3/project`). + +For the full tool reference, see [Atlassian MCP Integration](#atlassian-mcp-integration). For JQL functions, see [JQL Functions Reference](#jql-functions-reference). For report templates, see [Reporting Templates](#reporting-templates). --- ## Workflows ### Project Creation + +> Project creation is **not available via MCP** — perform steps 2-6 in the Jira web UI (`Projects > Create project`) or via REST API (`POST /rest/api/3/project`). After creation, verify visibility with `mcp__atlassian__getVisibleJiraProjects` and inspect issue types with `mcp__atlassian__getJiraProjectIssueTypesMetadata`. + 1. Determine project type (Scrum, Kanban, Bug Tracking, etc.) -2. Create project with appropriate template +2. Create project with appropriate template (web UI / REST) 3. Configure project settings: - Name, key, description - Project lead and default assignee @@ -50,15 +61,30 @@ For full command reference, see [Atlassian MCP Integration](#atlassian-mcp-integ 7. **HANDOFF TO**: Scrum Master for team onboarding ### Workflow Design + +> Workflow/scheme editing is **not available via MCP** — configure in `Jira Settings > Issues > Workflows`. Use the bundled validator to catch anti-patterns before deploying. + 1. Map out process states (To Do → In Progress → Done) 2. Define transitions and conditions -3. Add validators, post-functions, and conditions -4. Configure workflow scheme +3. Lint the design before building it in Jira: + ```bash + python3 scripts/workflow_validator.py workflow.json --format json + ``` + Input: a JSON file with the workflow's `states` and `transitions`. Consume the output: fix every reported anti-pattern (dead-end states, unreachable states, missing transitions) in the design before touching Jira. +4. Add validators, post-functions, and conditions; configure the workflow scheme (web UI) 5. **Validate**: Deploy to a test project first; verify all transitions, conditions, and post-functions behave as expected before associating with production projects 6. Associate workflow with project -7. Test workflow with sample issues +7. Test workflow with sample issues — via MCP: `mcp__atlassian__getTransitionsForJiraIssue` on a sample issue to confirm expected transitions surface, then `mcp__atlassian__transitionJiraIssue` to walk it through the flow ### JQL Query Building + +**Start with the bundled builder** — it pattern-matches natural language to validated JQL: +```bash +python3 scripts/jql_query_builder.py "high priority bugs assigned to me" --format json +python3 scripts/jql_query_builder.py --patterns # list all supported query patterns +``` +Consume the output: take the `jql` field from the JSON result (or the GENERATED JQL block in text mode) and execute it with `mcp__atlassian__searchJiraIssuesUsingJql (cloudId, jql=<generated>)`. If the builder reports no pattern match, compose JQL manually using the reference below. + **Basic Structure**: `field operator value` **Common Operators**: @@ -275,35 +301,44 @@ assignee in (user1, user2) AND sprint in openSprints() ## Atlassian MCP Integration -**Primary Tool**: Jira MCP Server +**Primary Tool**: Atlassian Remote MCP server (bundled `.mcp.json`, server key `atlassian`). Tools surface as `mcp__atlassian__<toolName>`. **Canonical tool list**: `project-management/references/atlassian-mcp-tools.md`. Never invent tool names — if a capability isn't in that list, route to the web UI/REST API. -**Key Operations with Example Commands**: +**Key Operations with Example Calls** (obtain `cloudId` once via `mcp__atlassian__getAccessibleAtlassianResources`): -Create a project: +Create an issue (check required fields first with `getJiraIssueTypeMetaWithFields`): ``` -mcp jira create_project --name "My Project" --key "MYPROJ" --type scrum --lead "user@example.com" +mcp__atlassian__createJiraIssue (cloudId, projectKey="MYPROJ", issueTypeName="Story", summary="My new story") ``` Execute a JQL query: ``` -mcp jira search_issues --jql "project = MYPROJ AND status != Done AND dueDate < now()" --maxResults 50 +mcp__atlassian__searchJiraIssuesUsingJql (cloudId, jql="project = MYPROJ AND status != Done AND dueDate < now()") ``` Update an issue field: ``` -mcp jira update_issue --issue "MYPROJ-42" --field "status" --value "In Progress" +mcp__atlassian__editJiraIssue (cloudId, issueIdOrKey="MYPROJ-42", fields=<payload — discover via tool schema>) ``` -Create a sprint: +Transition an issue (status changes go through transitions, not field edits): ``` -mcp jira create_sprint --board 10 --name "Sprint 5" --startDate "2024-06-01" --endDate "2024-06-14" +mcp__atlassian__getTransitionsForJiraIssue (cloudId, issueIdOrKey="MYPROJ-42") +mcp__atlassian__transitionJiraIssue (cloudId, issueIdOrKey="MYPROJ-42", transition=<id from previous call>) ``` -Create a board filter: +Comment / log work / link issues: ``` -mcp jira create_filter --name "Open Blockers" --jql "priority = Blocker AND status != Done" --shareWith "project-team" +mcp__atlassian__addCommentToJiraIssue (cloudId, issueIdOrKey="MYPROJ-42", body="...") +mcp__atlassian__addWorklogToJiraIssue (cloudId, issueIdOrKey="MYPROJ-42", timeSpent=<discover via tool schema>) +mcp__atlassian__createIssueLink (cloudId, link type from mcp__atlassian__getIssueLinkTypes) ``` +**Not available via MCP — use the web UI or REST API instead:** +- Create a **project** → Jira UI `Projects > Create project` or `POST /rest/api/3/project` +- Create a **sprint** or configure boards → Jira Software UI or `POST /rest/agile/1.0/sprint` +- Create/share a **filter** → Jira UI `Filters > Save as` or `POST /rest/api/3/filter` +- Custom fields, screens, workflow/permission schemes → Jira admin UI + **Integration Points**: - Pull metrics for Senior PM reporting - Configure sprint boards for Scrum Master diff --git a/docs/skills/project-management/pm-skills.md b/docs/skills/project-management/pm-skills.md index 66e94f26..f7247f30 100644 --- a/docs/skills/project-management/pm-skills.md +++ b/docs/skills/project-management/pm-skills.md @@ -1,9 +1,9 @@ --- -title: "Project Management Skills — Agent Skill for PM" -description: "6 project management agent skills and plugins for Claude Code, Codex, Gemini CLI, Cursor, OpenClaw. Senior PM, scrum master, Jira expert (JQL)." +title: "Project Management Skills — Router — Agent Skill for PM" +description: "Router/index for the 8 project-management skills bundled in this plugin (senior PM quant toolkit, scrum master, Jira/JQL, Confluence, Atlassian. Agent skill for Claude Code, Codex CLI, Gemini CLI, OpenClaw." --- -# Project Management Skills +# Project Management Skills — Router <div class="page-meta" markdown> <span class="meta-badge">:material-clipboard-check-outline: Project Management</span> @@ -16,41 +16,32 @@ description: "6 project management agent skills and plugins for Claude Code, Cod </div> -6 production-ready project management skills with Atlassian MCP integration. +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). -## Quick Start +## Routing table -### Claude Code -``` -/read project-management/jira-expert/SKILL.md -``` +Match the request, then load `project-management/skills/<skill>/SKILL.md`. If multiple rows match, ask one clarifying question first. -### Codex CLI -```bash -npx agent-skills-cli add alirezarezvani/claude-skills/project-management -``` +| 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/` | -## Skills Overview - -| Skill | Folder | Focus | -|-------|--------|-------| -| Senior PM | `senior-pm/` | Portfolio management, risk analysis, resource planning | -| Scrum Master | `scrum-master/` | Velocity forecasting, sprint health, retrospectives | -| Jira Expert | `jira-expert/` | JQL queries, workflows, automation, dashboards | -| Confluence Expert | `confluence-expert/` | Knowledge bases, page layouts, macros | -| Atlassian Admin | `atlassian-admin/` | User management, permissions, integrations | -| Atlassian Templates | `atlassian-templates/` | Blueprints, custom layouts, reusable content | - -## Python Tools - -6 scripts, all stdlib-only: +## Quick start ```bash -python3 senior-pm/scripts/project_health_dashboard.py --help -python3 scrum-master/scripts/velocity_analyzer.py --help +# Example: route a sprint-health request +cat project-management/skills/scrum-master/SKILL.md +ls project-management/skills/scrum-master/scripts/ ``` ## Rules -- Load only the specific skill SKILL.md you need -- Use MCP tools for live Jira/Confluence operations when available +- 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. diff --git a/docs/skills/ra-qm-team/compliance-team-eu-ai-act-eu-ai-act-specialist.md b/docs/skills/ra-qm-team/compliance-team-eu-ai-act-eu-ai-act-specialist.md index 72505363..2bb1d3f4 100644 --- a/docs/skills/ra-qm-team/compliance-team-eu-ai-act-eu-ai-act-specialist.md +++ b/docs/skills/ra-qm-team/compliance-team-eu-ai-act-eu-ai-act-specialist.md @@ -185,13 +185,13 @@ python scripts/conformity_assessment_planner.py system.json ## Adjacent Skills -- [`skills/gdpr-dsgvo-expert`](https://github.com/alirezarezvani/claude-skills/tree/main/ra-qm-team/compliance-team-eu-ai-act/skills/gdpr-dsgvo-expert) — GDPR DPIA + lawful basis (most AI systems also trigger GDPR) -- [`ra-qm-team/compliance-team-iso42001`](https://github.com/alirezarezvani/claude-skills/tree/main/ra-qm-team/compliance-team-iso42001) — ISO 42001 AIMS (voluntary management system that satisfies parts of Article 17 QMS for providers) -- [`skills/information-security-manager-iso27001`](https://github.com/alirezarezvani/claude-skills/tree/main/ra-qm-team/compliance-team-eu-ai-act/skills/information-security-manager-iso27001) — ISO 27001 for cybersecurity requirements (Article 15) -- [`skills/risk-management-specialist`](https://github.com/alirezarezvani/claude-skills/tree/main/ra-qm-team/compliance-team-eu-ai-act/skills/risk-management-specialist) — ISO 14971 risk management (referenced for safety-component AI under Article 6(1)) -- [`skills/mdr-745-specialist`](https://github.com/alirezarezvani/claude-skills/tree/main/ra-qm-team/compliance-team-eu-ai-act/skills/mdr-745-specialist) — MDR 2017/745 (medical-device AI overlap) -- [`compliance-os`](https://github.com/alirezarezvani/claude-skills/tree/main/compliance-os) — Meta-orchestrator for multi-framework programs -- [`c-level-advisor/chief-ai-officer-advisor`](https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor/chief-ai-officer-advisor) — Executive AI strategy +- `ra-qm-team/skills/gdpr-dsgvo-expert/` — GDPR DPIA + lawful basis (most AI systems also trigger GDPR) +- `ra-qm-team/compliance-team-iso42001/` — ISO 42001 AIMS (voluntary management system that satisfies parts of Article 17 QMS for providers) +- `ra-qm-team/skills/information-security-manager-iso27001/` — ISO 27001 for cybersecurity requirements (Article 15) +- `ra-qm-team/skills/risk-management-specialist/` — ISO 14971 risk management (referenced for safety-component AI under Article 6(1)) +- `ra-qm-team/skills/mdr-745-specialist/` — MDR 2017/745 (medical-device AI overlap) +- `compliance-os/` — Meta-orchestrator for multi-framework programs +- `c-level-advisor/chief-ai-officer-advisor/` — Executive AI strategy ## References diff --git a/docs/skills/ra-qm-team/compliance-team-iso42001-iso42001-specialist.md b/docs/skills/ra-qm-team/compliance-team-iso42001-iso42001-specialist.md index d9a404e8..f951f120 100644 --- a/docs/skills/ra-qm-team/compliance-team-iso42001-iso42001-specialist.md +++ b/docs/skills/ra-qm-team/compliance-team-iso42001-iso42001-specialist.md @@ -175,14 +175,14 @@ python scripts/aims_audit_scheduler.py audit_scope.json ## Adjacent Skills -- [`skills/information-security-manager-iso27001`](https://github.com/alirezarezvani/claude-skills/tree/main/ra-qm-team/compliance-team-iso42001/skills/information-security-manager-iso27001) — ISO 27001 ISMS implementation (many controls reusable for AIMS A.7 data controls) -- [`skills/quality-manager-qms-iso13485`](https://github.com/alirezarezvani/claude-skills/tree/main/ra-qm-team/compliance-team-iso42001/skills/quality-manager-qms-iso13485) — ISO 13485 QMS (provides CAPA + management-review machinery the AIMS reuses) -- [`skills/gdpr-dsgvo-expert`](https://github.com/alirezarezvani/claude-skills/tree/main/ra-qm-team/compliance-team-iso42001/skills/gdpr-dsgvo-expert) — GDPR DPIA process (input to AIMS A.5 impact assessment for personal-data systems) -- [`skills/isms-audit-expert`](https://github.com/alirezarezvani/claude-skills/tree/main/ra-qm-team/compliance-team-iso42001/skills/isms-audit-expert) — ISO 27001 internal audit pattern (the audit scheduler mirrors this for AIMS) -- [`skills/soc2-compliance`](https://github.com/alirezarezvani/claude-skills/tree/main/ra-qm-team/compliance-team-iso42001/skills/soc2-compliance) — SOC 2 trust services (reusable controls for AIMS A.10 third-party relationships) -- [`ra-qm-team/compliance-team-eu-ai-act`](https://github.com/alirezarezvani/claude-skills/tree/main/ra-qm-team/compliance-team-eu-ai-act) — EU AI Act Article-level compliance (binding regulation companion to voluntary 42001) -- [`compliance-os`](https://github.com/alirezarezvani/claude-skills/tree/main/compliance-os) — Meta-orchestrator for multi-framework programs (run AIMS as one framework among 9) -- [`c-level-advisor/chief-ai-officer-advisor`](https://github.com/alirezarezvani/claude-skills/tree/main/c-level-advisor/chief-ai-officer-advisor) — Executive AI strategy (build-vs-buy, cost economics — different audience) +- `ra-qm-team/skills/information-security-manager-iso27001/` — ISO 27001 ISMS implementation (many controls reusable for AIMS A.7 data controls) +- `ra-qm-team/skills/quality-manager-qms-iso13485/` — ISO 13485 QMS (provides CAPA + management-review machinery the AIMS reuses) +- `ra-qm-team/skills/gdpr-dsgvo-expert/` — GDPR DPIA process (input to AIMS A.5 impact assessment for personal-data systems) +- `ra-qm-team/skills/isms-audit-expert/` — ISO 27001 internal audit pattern (the audit scheduler mirrors this for AIMS) +- `ra-qm-team/skills/soc2-compliance/` — SOC 2 trust services (reusable controls for AIMS A.10 third-party relationships) +- `ra-qm-team/compliance-team-eu-ai-act/` — EU AI Act Article-level compliance (binding regulation companion to voluntary 42001) +- `compliance-os/` — Meta-orchestrator for multi-framework programs (run AIMS as one framework among 9) +- `c-level-advisor/chief-ai-officer-advisor/` — Executive AI strategy (build-vs-buy, cost economics — different audience) ## References diff --git a/docs/skills/ra-qm-team/eu-ai-act-specialist.md b/docs/skills/ra-qm-team/eu-ai-act-specialist.md index 204393bf..3b597cd8 100644 --- a/docs/skills/ra-qm-team/eu-ai-act-specialist.md +++ b/docs/skills/ra-qm-team/eu-ai-act-specialist.md @@ -185,13 +185,13 @@ python scripts/conformity_assessment_planner.py system.json ## Adjacent Skills -- [`skills/gdpr-dsgvo-expert`](https://github.com/alirezarezvani/claude-skills/tree/main/ra-qm-team/skills/gdpr-dsgvo-expert) — GDPR DPIA + lawful basis (most AI systems also trigger GDPR) -- [`compliance-team-iso42001`](https://github.com/alirezarezvani/claude-skills/tree/main/compliance-team-iso42001) — ISO 42001 AIMS (voluntary management system that satisfies parts of Article 17 QMS for providers) -- [`skills/information-security-manager-iso27001`](https://github.com/alirezarezvani/claude-skills/tree/main/ra-qm-team/skills/information-security-manager-iso27001) — ISO 27001 for cybersecurity requirements (Article 15) -- [`skills/risk-management-specialist`](https://github.com/alirezarezvani/claude-skills/tree/main/ra-qm-team/skills/risk-management-specialist) — ISO 14971 risk management (referenced for safety-component AI under Article 6(1)) -- [`skills/mdr-745-specialist`](https://github.com/alirezarezvani/claude-skills/tree/main/ra-qm-team/skills/mdr-745-specialist) — MDR 2017/745 (medical-device AI overlap) -- [`../compliance-os`](https://github.com/alirezarezvani/claude-skills/tree/main/../compliance-os) — Meta-orchestrator for multi-framework programs -- [`c-level-advisor/chief-ai-officer-advisor`](https://github.com/alirezarezvani/claude-skills/tree/main/../c-level-advisor/chief-ai-officer-advisor) — Executive AI strategy +- `ra-qm-team/skills/gdpr-dsgvo-expert/` — GDPR DPIA + lawful basis (most AI systems also trigger GDPR) +- `ra-qm-team/compliance-team-iso42001/` — ISO 42001 AIMS (voluntary management system that satisfies parts of Article 17 QMS for providers) +- `ra-qm-team/skills/information-security-manager-iso27001/` — ISO 27001 for cybersecurity requirements (Article 15) +- `ra-qm-team/skills/risk-management-specialist/` — ISO 14971 risk management (referenced for safety-component AI under Article 6(1)) +- `ra-qm-team/skills/mdr-745-specialist/` — MDR 2017/745 (medical-device AI overlap) +- `compliance-os/` — Meta-orchestrator for multi-framework programs +- `c-level-advisor/chief-ai-officer-advisor/` — Executive AI strategy ## References diff --git a/docs/skills/ra-qm-team/fda-consultant-specialist.md b/docs/skills/ra-qm-team/fda-consultant-specialist.md index 2d55390f..b366dd47 100644 --- a/docs/skills/ra-qm-team/fda-consultant-specialist.md +++ b/docs/skills/ra-qm-team/fda-consultant-specialist.md @@ -1,6 +1,6 @@ --- title: "FDA Consultant Specialist — Agent Skill for Compliance" -description: "FDA regulatory consultant for medical device companies. Provides 510(k)/PMA/De Novo pathway guidance, QSR (21 CFR 820) compliance, HIPAA assessments. Agent skill for Claude Code, Codex CLI, Gemini CLI, OpenClaw." +description: "FDA regulatory consultant for medical device companies. Provides 510(k)/PMA/De Novo pathway guidance, QMSR (21 CFR 820, which incorporates ISO. Agent skill for Claude Code, Codex CLI, Gemini CLI, OpenClaw." --- # FDA Consultant Specialist @@ -16,13 +16,13 @@ description: "FDA regulatory consultant for medical device companies. Provides 5 </div> -FDA regulatory consulting for medical device manufacturers covering submission pathways, Quality System Regulation (QSR), HIPAA compliance, and device cybersecurity requirements. +FDA regulatory consulting for medical device manufacturers covering submission pathways, the Quality Management System Regulation (QMSR, 21 CFR Part 820 — formerly the QSR), HIPAA compliance, and device cybersecurity requirements. ## Table of Contents - [FDA Pathway Selection](#fda-pathway-selection) - [510(k) Submission Process](#510k-submission-process) -- [QSR Compliance](#qsr-compliance) +- [QMSR Compliance (formerly QSR)](#qmsr-compliance-formerly-qsr) - [HIPAA for Medical Devices](#hipaa-for-medical-devices) - [Device Cybersecurity](#device-cybersecurity) - [Resources](#resources) @@ -50,13 +50,15 @@ Predicate device exists? ### Pathway Comparison -| Pathway | When to Use | Timeline | Cost | -|---------|-------------|----------|------| -| 510(k) Traditional | Predicate exists, design changes | 90 days | $21,760 | -| 510(k) Special | Manufacturing changes only | 30 days | $21,760 | -| 510(k) Abbreviated | Guidance/standard conformance | 30 days | $21,760 | -| De Novo | Novel, low-moderate risk | 150 days | $134,676 | -| PMA | Class III, no predicate | 180+ days | $425,000+ | +| Pathway | When to Use | Timeline | User Fee (FY2024) | +|---------|-------------|----------|-------------------| +| 510(k) Traditional | Predicate exists, design changes | 90 days | $21,760 (FY2024) | +| 510(k) Special | Manufacturing changes only | 30 days | $21,760 (FY2024) | +| 510(k) Abbreviated | Guidance/standard conformance | 30 days | $21,760 (FY2024) | +| De Novo | Novel, low-moderate risk | 150 days | $134,676 (FY2024) | +| PMA | Class III, no predicate | 180+ days | $425,000+ (FY2024) | + +> User fees are set annually under MDUFA. Verify current-fiscal-year fees at fda.gov (MDUFA user fee schedule) before budgeting; small-business rates differ. ### Pre-Submission Strategy @@ -126,23 +128,25 @@ Phase 4: Review --- -## QSR Compliance +## QMSR Compliance (formerly QSR) -Quality System Regulation (21 CFR Part 820) requirements for medical device manufacturers. +Quality Management System Regulation (QMSR) requirements for medical device manufacturers under 21 CFR Part 820. -### Key Subsystems +> **QMSR transition (effective 2026-02-02):** FDA's QMSR final rule (89 FR 7496) amended 21 CFR Part 820 to incorporate **ISO 13485:2016 by reference** and removed the legacy QSR subsection structure (820.20–820.198). Those subsection numbers are **historical** and no longer exist in the CFR; the corresponding requirements now flow from ISO 13485:2016 clauses plus the retained/renumbered sections 820.10 (requirements, incl. the ISO 13485 incorporation), 820.35 (records), and 820.45 (device labeling and packaging controls). 21 CFR Parts 801, 803, 806, and 830 are unchanged. Legacy QSR numbers below are kept only as a familiar index, each mapped to its current ISO 13485 clause. -| Section | Title | Focus | -|---------|-------|-------| -| 820.20 | Management Responsibility | Quality policy, org structure, management review | -| 820.30 | Design Controls | Input, output, review, verification, validation | -| 820.40 | Document Controls | Approval, distribution, change control | -| 820.50 | Purchasing Controls | Supplier qualification, purchasing data | -| 820.70 | Production Controls | Process validation, environmental controls | -| 820.100 | CAPA | Root cause analysis, corrective actions | -| 820.181 | Device Master Record | Specifications, procedures, acceptance criteria | +### Key Quality Subsystems (legacy QSR index → current ISO 13485:2016 clause) -### Design Controls Workflow (820.30) +| Legacy QSR Section (historical, pre-2026) | Title | Current authority under QMSR | Focus | +|-------------------------------------------|-------|------------------------------|-------| +| 820.20 | Management Responsibility | ISO 13485 §5.1, 5.5, 5.6 | Quality policy, org structure, management review | +| 820.30 | Design Controls | ISO 13485 §7.3 | Input, output, review, verification, validation | +| 820.40 | Document Controls | ISO 13485 §4.2.4 | Approval, distribution, change control | +| 820.50 | Purchasing Controls | ISO 13485 §7.4 | Supplier qualification, purchasing data | +| 820.70 | Production Controls | ISO 13485 §6.3, 6.4, 7.5 | Process validation, environmental controls | +| 820.100 | CAPA | ISO 13485 §8.5.2, 8.5.3 | Root cause analysis, corrective actions | +| 820.181 | Device Master Record | ISO 13485 §4.2.3 (medical device file) + 21 CFR 820.35 | Specifications, procedures, acceptance criteria | + +### Design Controls Workflow (ISO 13485 §7.3; legacy QSR 820.30) ``` Step 1: Design Input @@ -170,7 +174,7 @@ Step 6: Design Transfer Verification: Transfer checklist complete? ``` -### CAPA Process (820.100) +### CAPA Process (ISO 13485 §8.5.2/8.5.3; legacy QSR 820.100) 1. **Identify**: Document nonconformity or potential problem 2. **Investigate**: Perform root cause analysis (5 Whys, Fishbone) @@ -180,7 +184,7 @@ Step 6: Design Transfer 6. **Effectiveness**: Monitor for recurrence (30-90 days) 7. **Close**: Management approval and closure -**Reference:** See [qsr_compliance_requirements.md](https://github.com/alirezarezvani/claude-skills/tree/main/ra-qm-team/skills/fda-consultant-specialist/references/qsr_compliance_requirements.md) for detailed QSR implementation guidance. +**Reference:** See [qsr_compliance_requirements.md](https://github.com/alirezarezvani/claude-skills/tree/main/ra-qm-team/skills/fda-consultant-specialist/references/qsr_compliance_requirements.md) for the historical QSR structure with full QMSR/ISO 13485:2016 clause mapping. --- @@ -291,7 +295,7 @@ Coordinated Public Disclosure | Script | Purpose | |--------|---------| | `fda_submission_tracker.py` | Track 510(k)/PMA/De Novo submission milestones and timelines | -| `qsr_compliance_checker.py` | Assess 21 CFR 820 compliance against project documentation | +| `qsr_compliance_checker.py` | Assess QMS documentation against the legacy-QSR checklist mapped to ISO 13485:2016 (QMSR) | | `hipaa_risk_assessment.py` | Evaluate HIPAA safeguards in medical device software | ### references/ @@ -299,7 +303,7 @@ Coordinated Public Disclosure | File | Content | |------|---------| | `fda_submission_guide.md` | 510(k), De Novo, PMA submission requirements and checklists | -| `qsr_compliance_requirements.md` | 21 CFR 820 implementation guide with templates | +| `qsr_compliance_requirements.md` | Historical QSR structure with QMSR/ISO 13485:2016 mapping, implementation templates | | `hipaa_compliance_framework.md` | HIPAA Security Rule safeguards and BAA requirements | | `device_cybersecurity_guidance.md` | FDA cybersecurity requirements, SBOM, threat modeling | | `fda_capa_requirements.md` | CAPA process, root cause analysis, effectiveness verification | @@ -310,8 +314,8 @@ Coordinated Public Disclosure # Track FDA submission status python scripts/fda_submission_tracker.py /path/to/project --type 510k -# Assess QSR compliance -python scripts/qsr_compliance_checker.py /path/to/project --section 820.30 +# Assess QMS documentation (legacy QSR section keys, mapped to ISO 13485 under QMSR) +python scripts/qsr_compliance_checker.py /path/to/project --section 820.30 # legacy checklist key = ISO 13485 §7.3 (design & development) # Run HIPAA risk assessment python scripts/hipaa_risk_assessment.py /path/to/project --category technical diff --git a/docs/skills/ra-qm-team/gdpr-dsgvo-expert.md b/docs/skills/ra-qm-team/gdpr-dsgvo-expert.md index f2d78127..f994c10d 100644 --- a/docs/skills/ra-qm-team/gdpr-dsgvo-expert.md +++ b/docs/skills/ra-qm-team/gdpr-dsgvo-expert.md @@ -86,7 +86,7 @@ python scripts/dpia_generator.py --input input.json --output dpia_report.md - Systematic monitoring (Art. 35(3)(c)) - Large-scale special category data (Art. 35(3)(b)) - Automated decision-making (Art. 35(3)(a)) -- WP29 high-risk criteria +- EDPB-endorsed high-risk criteria (WP248 rev.01) --- @@ -116,13 +116,13 @@ python scripts/data_subject_rights_tracker.py template --id DSR-202601-0001 | Right | Article | Deadline | |-------|---------|----------| -| Access | Art. 15 | 30 days | -| Rectification | Art. 16 | 30 days | -| Erasure | Art. 17 | 30 days | -| Restriction | Art. 18 | 30 days | -| Portability | Art. 20 | 30 days | -| Objection | Art. 21 | 30 days | -| Automated decisions | Art. 22 | 30 days | +| Access | Art. 15 | One month (Art. 12(3)) | +| Rectification | Art. 16 | One month (Art. 12(3)) | +| Erasure | Art. 17 | One month (Art. 12(3)) | +| Restriction | Art. 18 | One month (Art. 12(3)) | +| Portability | Art. 20 | One month (Art. 12(3)) | +| Objection | Art. 21 | One month (Art. 12(3)) | +| Automated decisions | Art. 22 | One month (Art. 12(3)) | **Features:** - Deadline tracking with overdue alerts @@ -161,7 +161,7 @@ German-specific requirements including: Step-by-step DPIA process: - Threshold assessment criteria -- WP29 high-risk indicators +- EDPB-endorsed high-risk indicators (WP248 rev.01) - Risk assessment methodology - Mitigation measure categories - DPO and supervisory authority consultation @@ -259,7 +259,7 @@ Requires explicit consent or Art. 9(2) exception: ### Data Subject Rights -All rights must be fulfilled within **30 days** (extendable to 90 for complex requests): +All rights must be fulfilled within **one month of receipt** (Art. 12(3)). The deadline runs by calendar month, not 30 days, and may be extended by **two further months** for complex or numerous requests — the data subject must be informed of the extension (with reasons) within the first month: - **Access**: Provide copy of data and processing information - **Rectification**: Correct inaccurate data - **Erasure**: Delete data (with exceptions for legal obligations) diff --git a/docs/skills/ra-qm-team/index.md b/docs/skills/ra-qm-team/index.md index eb6bcca6..b67fadc3 100644 --- a/docs/skills/ra-qm-team/index.md +++ b/docs/skills/ra-qm-team/index.md @@ -33,7 +33,7 @@ description: "18 regulatory & quality skills — regulatory and quality manageme --- - FDA regulatory consulting for medical device manufacturers covering submission pathways, Quality System Regulation (Q... + FDA regulatory consulting for medical device manufacturers covering submission pathways, the Quality Management Syste... - **[GDPR/DSGVO Expert](gdpr-dsgvo-expert.md)** @@ -89,11 +89,11 @@ description: "18 regulatory & quality skills — regulatory and quality manageme ISO 13485:2016 Quality Management System implementation, maintenance, and certification support for medical device or... -- **[Regulatory Affairs & Quality Management Skills](ra-qm-skills.md)** +- **[Regulatory Affairs & Quality Management Skills — Router](ra-qm-skills.md)** --- - 12 production-ready compliance skills for HealthTech and MedTech organizations. + This plugin bundles 15 compliance skills for HealthTech/MedTech organizations (this router is the 16th folder under r... - **[Head of Regulatory Affairs](regulatory-affairs-head.md)** diff --git a/docs/skills/ra-qm-team/information-security-manager-iso27001.md b/docs/skills/ra-qm-team/information-security-manager-iso27001.md index dd1f4dc3..60d81688 100644 --- a/docs/skills/ra-qm-team/information-security-manager-iso27001.md +++ b/docs/skills/ra-qm-team/information-security-manager-iso27001.md @@ -1,6 +1,6 @@ --- title: "Information Security Manager - ISO 27001 — Agent Skill for Compliance" -description: "ISO 27001 ISMS implementation and cybersecurity governance for HealthTech and MedTech companies. Use for ISMS design, security risk assessment. Agent skill for Claude Code, Codex CLI, Gemini CLI, OpenClaw." +description: "ISO 27001 ISMS implementation and cybersecurity governance for HealthTech and MedTech companies. Use when designing an ISMS, running security risk. Agent skill for Claude Code, Codex CLI, Gemini CLI, OpenClaw." --- # Information Security Manager - ISO 27001 diff --git a/docs/skills/ra-qm-team/iso42001-specialist.md b/docs/skills/ra-qm-team/iso42001-specialist.md index a337e190..9e032a5b 100644 --- a/docs/skills/ra-qm-team/iso42001-specialist.md +++ b/docs/skills/ra-qm-team/iso42001-specialist.md @@ -175,14 +175,14 @@ python scripts/aims_audit_scheduler.py audit_scope.json ## Adjacent Skills -- [`skills/information-security-manager-iso27001`](https://github.com/alirezarezvani/claude-skills/tree/main/ra-qm-team/skills/information-security-manager-iso27001) — ISO 27001 ISMS implementation (many controls reusable for AIMS A.7 data controls) -- [`skills/quality-manager-qms-iso13485`](https://github.com/alirezarezvani/claude-skills/tree/main/ra-qm-team/skills/quality-manager-qms-iso13485) — ISO 13485 QMS (provides CAPA + management-review machinery the AIMS reuses) -- [`skills/gdpr-dsgvo-expert`](https://github.com/alirezarezvani/claude-skills/tree/main/ra-qm-team/skills/gdpr-dsgvo-expert) — GDPR DPIA process (input to AIMS A.5 impact assessment for personal-data systems) -- [`skills/isms-audit-expert`](https://github.com/alirezarezvani/claude-skills/tree/main/ra-qm-team/skills/isms-audit-expert) — ISO 27001 internal audit pattern (the audit scheduler mirrors this for AIMS) -- [`skills/soc2-compliance`](https://github.com/alirezarezvani/claude-skills/tree/main/ra-qm-team/skills/soc2-compliance) — SOC 2 trust services (reusable controls for AIMS A.10 third-party relationships) -- [`compliance-team-eu-ai-act`](https://github.com/alirezarezvani/claude-skills/tree/main/compliance-team-eu-ai-act) — EU AI Act Article-level compliance (binding regulation companion to voluntary 42001) -- [`../compliance-os`](https://github.com/alirezarezvani/claude-skills/tree/main/../compliance-os) — Meta-orchestrator for multi-framework programs (run AIMS as one framework among 9) -- [`c-level-advisor/chief-ai-officer-advisor`](https://github.com/alirezarezvani/claude-skills/tree/main/../c-level-advisor/chief-ai-officer-advisor) — Executive AI strategy (build-vs-buy, cost economics — different audience) +- `ra-qm-team/skills/information-security-manager-iso27001/` — ISO 27001 ISMS implementation (many controls reusable for AIMS A.7 data controls) +- `ra-qm-team/skills/quality-manager-qms-iso13485/` — ISO 13485 QMS (provides CAPA + management-review machinery the AIMS reuses) +- `ra-qm-team/skills/gdpr-dsgvo-expert/` — GDPR DPIA process (input to AIMS A.5 impact assessment for personal-data systems) +- `ra-qm-team/skills/isms-audit-expert/` — ISO 27001 internal audit pattern (the audit scheduler mirrors this for AIMS) +- `ra-qm-team/skills/soc2-compliance/` — SOC 2 trust services (reusable controls for AIMS A.10 third-party relationships) +- `ra-qm-team/compliance-team-eu-ai-act/` — EU AI Act Article-level compliance (binding regulation companion to voluntary 42001) +- `compliance-os/` — Meta-orchestrator for multi-framework programs (run AIMS as one framework among 9) +- `c-level-advisor/chief-ai-officer-advisor/` — Executive AI strategy (build-vs-buy, cost economics — different audience) ## References diff --git a/docs/skills/ra-qm-team/mdr-745-specialist.md b/docs/skills/ra-qm-team/mdr-745-specialist.md index 23c6bb73..3ba356a6 100644 --- a/docs/skills/ra-qm-team/mdr-745-specialist.md +++ b/docs/skills/ra-qm-team/mdr-745-specialist.md @@ -125,8 +125,8 @@ ANNEX II TECHNICAL DOCUMENTATION | I | Annex II self-declaration | None | | Is/Im | Annex II + IX/XI | Sterile/measuring aspects | | IIa | Annex II + IX or XI | Product or QMS | -| IIb | Annex IX + X or X + XI | Type exam + production | -| III | Annex IX + X | Full QMS + type exam | +| IIb | Annex IX, or Annex X + XI | QMS + tech doc assessment, or type exam + production | +| III | Annex IX, or Annex X + XI | Full QMS + product dossier, or type exam + production | --- @@ -193,19 +193,19 @@ Establish PMS system per Chapter VII: | Component | Requirement | Frequency | |-----------|-------------|-----------| | PMS Plan | Article 84 | Maintain current | -| PSUR | Class IIa and higher | Per class schedule | +| PSUR | Article 86 — Class IIa and higher | Per Art. 86(1) schedule below | | PMCF Plan | Annex XIV Part B | Update with CER | | PMCF Report | Annex XIV Part B | Annual (Class III) | | Vigilance | Articles 87-92 | As events occur | ### PSUR Schedule -| Class | Frequency | -|-------|-----------| -| Class III | Annual | -| Class IIb implantable | Annual | -| Class IIb | Every 2 years | -| Class IIa | When necessary | +| Class | Frequency (MDR Art. 86(1)) | +|-------|-----------------------------| +| Class III | Updated at least annually | +| Class IIb (all, incl. implantable) | Updated at least annually | +| Class IIa | When necessary, at least every 2 years | +| Class I | No PSUR — PMS report instead (Art. 85) | ### Serious Incident Reporting diff --git a/docs/skills/ra-qm-team/ra-qm-skills.md b/docs/skills/ra-qm-team/ra-qm-skills.md index 08903b22..462f5aa6 100644 --- a/docs/skills/ra-qm-team/ra-qm-skills.md +++ b/docs/skills/ra-qm-team/ra-qm-skills.md @@ -1,9 +1,9 @@ --- -title: "Regulatory Affairs & Quality Management Skills — Agent Skill for Compliance" -description: "12 regulatory & QM agent skills and plugins for Claude Code, Codex, Gemini CLI, Cursor, OpenClaw. ISO 13485 QMS, MDR 2017/745, FDA 510(k)/PMA, ISO." +title: "Regulatory Affairs & Quality Management Skills — Router — Agent Skill for Compliance" +description: "Router/index for the 15 regulatory & quality-management skills bundled in this plugin (ISO 13485 QMS, EU MDR 2017/745, FDA submissions under QMSR. Agent skill for Claude Code, Codex CLI, Gemini CLI, OpenClaw." --- -# Regulatory Affairs & Quality Management Skills +# Regulatory Affairs & Quality Management Skills — Router <div class="page-meta" markdown> <span class="meta-badge">:material-shield-check-outline: Regulatory & Quality</span> @@ -16,47 +16,40 @@ description: "12 regulatory & QM agent skills and plugins for Claude Code, Codex </div> -12 production-ready compliance skills for HealthTech and MedTech organizations. +This plugin bundles **15 compliance skills** for HealthTech/MedTech organizations (this router is the 16th folder under `ra-qm-team/skills/`). Each skill is self-contained. -## Quick Start +## Routing table -### Claude Code -``` -/read ra-qm-team/regulatory-affairs-head/SKILL.md -``` +Match the request, then load `ra-qm-team/skills/<skill>/SKILL.md`. If multiple rows match, ask one clarifying question first. -### Codex CLI -```bash -npx agent-skills-cli add alirezarezvani/claude-skills/ra-qm-team -``` +| Request signals | Skill | Path | +|---|---|---| +| Regulatory strategy, pathway selection, submissions planning | regulatory-affairs-head | `skills/regulatory-affairs-head/` | +| Management review, quality KPIs, QMR governance | quality-manager-qmr | `skills/quality-manager-qmr/` | +| ISO 13485 QMS implementation, process control | quality-manager-qms-iso13485 | `skills/quality-manager-qms-iso13485/` | +| ISO 14971 risk analysis, FMEA, risk files | risk-management-specialist | `skills/risk-management-specialist/` | +| Root cause analysis, corrective/preventive actions | capa-officer | `skills/capa-officer/` | +| Document control, 21 CFR Part 11, DHF/DMR/DHR | quality-documentation-manager | `skills/quality-documentation-manager/` | +| ISO 13485 internal audits, NC classification | qms-audit-expert | `skills/qms-audit-expert/` | +| ISO 27001 audit planning and execution | isms-audit-expert | `skills/isms-audit-expert/` | +| ISMS design, security risk assessment | information-security-manager-iso27001 | `skills/information-security-manager-iso27001/` | +| EU MDR classification, technical files, PSUR | mdr-745-specialist | `skills/mdr-745-specialist/` | +| FDA 510(k)/PMA/De Novo, QMSR | fda-consultant-specialist | `skills/fda-consultant-specialist/` | +| GDPR/DSGVO, DPIA, data subject rights | gdpr-dsgvo-expert | `skills/gdpr-dsgvo-expert/` | +| EU AI Act risk classification, obligations | eu-ai-act-specialist | `skills/eu-ai-act-specialist/` | +| ISO/IEC 42001 AI management system | iso42001-specialist | `skills/iso42001-specialist/` | +| SOC 2 Type I/II readiness, trust criteria | soc2-compliance | `skills/soc2-compliance/` | -## Skills Overview - -| Skill | Folder | Focus | -|-------|--------|-------| -| Regulatory Affairs Head | `regulatory-affairs-head/` | FDA/MDR strategy, submissions | -| Quality Manager (QMR) | `quality-manager-qmr/` | QMS governance, management review | -| Quality Manager (ISO 13485) | `quality-manager-qms-iso13485/` | QMS implementation, doc control | -| Risk Management Specialist | `risk-management-specialist/` | ISO 14971, FMEA, risk files | -| CAPA Officer | `capa-officer/` | Root cause analysis, corrective actions | -| Quality Documentation Manager | `quality-documentation-manager/` | Document control, 21 CFR Part 11 | -| QMS Audit Expert | `qms-audit-expert/` | ISO 13485 internal audits | -| ISMS Audit Expert | `isms-audit-expert/` | ISO 27001 security audits | -| Information Security Manager | `information-security-manager-iso27001/` | ISMS implementation | -| MDR 745 Specialist | `mdr-745-specialist/` | EU MDR classification, CE marking | -| FDA Consultant | `fda-consultant-specialist/` | 510(k), PMA, QSR compliance | -| GDPR/DSGVO Expert | `gdpr-dsgvo-expert/` | Privacy compliance, DPIA | - -## Python Tools - -17 scripts, all stdlib-only: +## Quick start ```bash -python3 risk-management-specialist/scripts/risk_matrix_calculator.py --help -python3 gdpr-dsgvo-expert/scripts/gdpr_compliance_checker.py --help +# Example: route a risk-analysis request +cat ra-qm-team/skills/risk-management-specialist/SKILL.md +python3 ra-qm-team/skills/risk-management-specialist/scripts/risk_matrix_calculator.py --help ``` ## Rules -- Load only the specific skill SKILL.md you need -- Always verify compliance outputs against current regulations +- Route to exactly one skill, then follow that skill's workflow. This router ships no tools of its own. +- All outputs are decision support: final compliance determinations route to the named human owner (QMR, DPO, regulatory counsel) — never auto-decide. +- Verify regulatory citations against the current text (e.g., FDA QMSR effective 2026-02-02 replaced the legacy QSR subsections). diff --git a/docs/skills/ra-qm-team/risk-management-specialist.md b/docs/skills/ra-qm-team/risk-management-specialist.md index 4511b296..e2ea535c 100644 --- a/docs/skills/ra-qm-team/risk-management-specialist.md +++ b/docs/skills/ra-qm-team/risk-management-specialist.md @@ -86,11 +86,13 @@ Establish risk management process per ISO 14971. | Level | Acceptable | Action Required | |-------|------------|-----------------| -| Low | Yes | Document and accept | -| Medium | ALARP | Reduce if practicable; document rationale | -| High | ALARP | Reduction required; demonstrate ALARP | +| Low | Yes | Document and accept; still reduce as far as possible (EU MDR) | +| Medium | After reduction AFAP | Reduce as far as possible; document why further reduction is impossible | +| High | After reduction AFAP | Reduction required; demonstrate all further options exhausted | | Unacceptable | No | Design change mandatory | +> **EU MDR — AFAP, not ALARP:** For CE-marked devices, risks must be reduced **as far as possible (AFAP)** without economic considerations (MDR Annex I, GSPR 1–4; EN ISO 14971:2019/A11:2021 Z-annexes deviation). ALARP ("as low as reasonably practicable"), which permits cost-benefit weighing in acceptability decisions, is **not an acceptable criterion under the EU MDR** — a notified body will flag it. ISO 14971:2019 itself removed ALARP from the normative text. ALARP may persist in some non-EU jurisdictions (e.g., the UK HSE tradition); if used outside the EU, flag the deviation from EU requirements explicitly. + --- ## Risk Analysis Workflow @@ -181,8 +183,8 @@ Evaluate risks against acceptability criteria. 1. Calculate initial risk level from probability × severity 2. Compare to risk acceptability criteria 3. For each risk, determine: - - Acceptable: Document and accept - - ALARP: Proceed to risk control + - Acceptable: Document and accept (EU MDR: still reduce as far as possible) + - Reduction required (AFAP): Proceed to risk control - Unacceptable: Mandatory risk control 4. Document evaluation rationale 5. Identify risks requiring benefit-risk analysis @@ -200,16 +202,16 @@ Apply Acceptability Criteria │ ├── Low Risk ──────────► Accept and document │ - ├── Medium Risk ───────► Consider risk reduction - │ │ Document ALARP if not reduced + ├── Medium Risk ───────► Reduce as far as possible (AFAP) + │ │ Document why further reduction impossible │ ▼ - │ Practicable to reduce? + │ Further reduction possible? │ │ │ Yes──► Implement control - │ No───► Document ALARP rationale + │ No───► Document AFAP rationale (no economic considerations) │ ├── High Risk ─────────► Risk reduction required - │ │ Must demonstrate ALARP + │ │ Must demonstrate reduction AFAP │ ▼ │ Implement control │ Verify residual risk @@ -218,15 +220,17 @@ Apply Acceptability Criteria Cannot proceed without control ``` -### ALARP Demonstration Requirements +### AFAP Demonstration Requirements (EU MDR) | Criterion | Evidence Required | |-----------|-------------------| -| Technical feasibility | Analysis of alternative controls | -| Proportionality | Cost-benefit of further reduction | -| State of the art | Comparison to similar devices | +| All control options considered | Analysis of every feasible control per the hierarchy (design, protective measures, information) | +| Further reduction impossible | Evidence each remaining option is technically infeasible or does not further reduce risk | +| State of the art | Comparison to similar devices and current standards | | Stakeholder input | Clinical/user perspectives | +> Economic considerations (cost of further risk reduction) **must not** enter the EU acceptability decision (MDR Annex I GSPR 2; EN ISO 14971:2019/A11:2021). Cost may inform business decisions about whether to market the device — never whether a risk is acceptable. + ### Benefit-Risk Analysis Triggers | Situation | Benefit-Risk Required | @@ -308,7 +312,7 @@ VERIFICATION: | After Control | Action | |---------------|--------| | Acceptable | Document, proceed | -| ALARP achieved | Document rationale, proceed | +| Reduced AFAP | Document rationale (no economic considerations), proceed | | Still unacceptable | Additional control or design change | | New hazard introduced | Analyze and control new hazard | @@ -411,8 +415,8 @@ What is the risk level? | Condition | Decision | |-----------|----------| | All risks Low | Acceptable | -| Medium risks with ALARP | Acceptable | -| High risks with ALARP documented | Acceptable if benefits outweigh | +| Medium risks reduced AFAP | Acceptable | +| High risks reduced AFAP, documented | Acceptable if benefits outweigh | | Any Unacceptable residual | Not acceptable - redesign | --- @@ -445,7 +449,7 @@ What is the risk level? |-------|----------------|--------| | Planning | Define scope, criteria, responsibilities | Risk Management Plan | | Analysis | Identify hazards, estimate risk | Hazard Analysis | -| Evaluation | Compare to criteria, ALARP assessment | Risk Evaluation | +| Evaluation | Compare to criteria, AFAP assessment (EU) | Risk Evaluation | | Control | Implement hierarchy, verify | Risk Control Records | | Residual | Overall assessment, benefit-risk | Risk Management Report | | Production | Monitor, review, update | Updated RM File | diff --git a/docs/skills/research-ops/research-ops-skills.md b/docs/skills/research-ops/research-ops-skills.md index 650c23a3..c7ad356a 100644 --- a/docs/skills/research-ops/research-ops-skills.md +++ b/docs/skills/research-ops/research-ops-skills.md @@ -112,7 +112,7 @@ Each sub-skill has its **own** question set (clinical: area/alpha/power/dropout/ ## Autoresearch handoff (isolated, opt-in) -Each sub-skill ships its own `scripts/ar_evaluator.py` — an **isolated** bridge to `engineering/autoresearch-agent`. Invoke autoresearch **only when the user explicitly asks** to "optimize", "improve", or "run a loop". The handoff is per-skill (no shared coupling): the loop edits the skill's input file and the evaluator scores it (clinical → `feasibility_composite` higher; finance → `runway_months` higher; market → `tam_divergence` lower; product → `validated_insights` higher). Never auto-start a loop; never let the loop edit the evaluator. +Each sub-skill ships its own `skills/<sub-skill>/scripts/ar_evaluator.py` — an **isolated** bridge to `engineering/autoresearch-agent`. Invoke autoresearch **only when the user explicitly asks** to "optimize", "improve", or "run a loop". The handoff is per-skill (no shared coupling): the loop edits the skill's input file and the evaluator scores it (clinical → `feasibility_composite` higher; finance → `runway_months` higher; market → `tam_divergence` lower; product → `validated_insights` higher). Never auto-start a loop; never let the loop edit the evaluator. ## Assumptions diff --git a/docs/skills/research/dossier.md b/docs/skills/research/dossier.md index 94d91ffc..9e19d3b4 100644 --- a/docs/skills/research/dossier.md +++ b/docs/skills/research/dossier.md @@ -272,7 +272,7 @@ new ExternalHyperlink({ - Save: `<output-dir>/dossier_<entity-slug>_<YYYY-MM-DD>.docx` - Chat summary: file path + **verdict on hypothesis** + audit counts + tier breakdown + BYOK MCPs used (if any) -- Validate: `python scripts/office/validate.py <docx>` +- Validate: check zip integrity with `python3 -c "import zipfile,sys; zipfile.ZipFile(sys.argv[1]).testzip()" <docx>` (no output = intact), then confirm the required sections are present ## Tooling diff --git a/docs/skills/research/grants.md b/docs/skills/research/grants.md index 99a32535..aca38b50 100644 --- a/docs/skills/research/grants.md +++ b/docs/skills/research/grants.md @@ -123,7 +123,7 @@ RePORTER is **POST-only**. Use `bash_tool` + `curl` — never `web_fetch`. Compute at runtime via `scripts/fiscal_year_calculator.py`. Default: current FY + 3 prior. Federal FY starts Oct 1, so: ```bash -python ../scripts/fiscal_year_calculator.py --output json +python scripts/fiscal_year_calculator.py --output json # Returns: {"current_fy": 2026, "window": [2023, 2024, 2025, 2026]} ``` @@ -190,7 +190,7 @@ NOT career stage alone. Career stage **+** project scope **+** prelim data drive Use `scripts/mechanism_matcher.py`: ```bash -python ../scripts/mechanism_matcher.py \ +python scripts/mechanism_matcher.py \ --career-stage "early_career" \ --prelim-data "pilot" \ --environment "r01_eligible" \ @@ -243,7 +243,7 @@ This is the single most valuable advice for any applicant. Never skip. - Save DOCX to `<output-dir>/grants_<topic-slug>_<YYYY-MM-DD>.docx` - Chat summary: file path + audit counts + plan tier + verdict on institute targets -- Validate: `python scripts/office/validate.py <docx>` +- Validate: check zip integrity with `python3 -c "import zipfile,sys; zipfile.ZipFile(sys.argv[1]).testzip()" <docx>` (no output = intact), then confirm the required sections are present ## Tooling diff --git a/docs/skills/research/litreview.md b/docs/skills/research/litreview.md index 5572b353..0e57b221 100644 --- a/docs/skills/research/litreview.md +++ b/docs/skills/research/litreview.md @@ -209,7 +209,7 @@ Document the key `docx` library patterns: - Lists: `LevelFormat.BULLET` (never unicode bullets) - Hyperlinks: `ExternalHyperlink` with `style: "Hyperlink"`, full URL (never truncated) - Tables: dual widths (`columnWidths` + cell `width`), `ShadingType.CLEAR` -- Validation step after save (`python scripts/office/validate.py output.docx`) +- Validation step after save (zip-integrity check: `python3 -c "import zipfile,sys; zipfile.ZipFile(sys.argv[1]).testzip()" output.docx` — no output = intact — then confirm the required sections are present) Reference the **docx skill** for setup patterns and best practices. diff --git a/docs/skills/research/notebooklm.md b/docs/skills/research/notebooklm.md index deae0bc5..d50a0248 100644 --- a/docs/skills/research/notebooklm.md +++ b/docs/skills/research/notebooklm.md @@ -1,6 +1,6 @@ --- title: "NotebookLM — Browser Automation — Agent Skill for Research Workflows" -description: "Browser automation skill for controlling Google's NotebookLM. Handles reading and querying notebooks, adding sources (URLs, text, files, YouTube. Agent skill for Claude Code, Codex CLI, Gemini CLI, OpenClaw." +description: "Browser automation skill for controlling Google's NotebookLM. Use when the user wants anything done in NotebookLM (e.g., 'open NotebookLM', 'check my. Agent skill for Claude Code, Codex CLI, Gemini CLI, OpenClaw." --- # NotebookLM — Browser Automation @@ -39,7 +39,7 @@ Up to 4 forcing questions, one at a time, dependency-ordered. Most invocations s > > 1. **Read / extract** — ask a question of an existing notebook > 2. **Add a source** — push content (URL, text, file, Google Doc, or synthesized content) into a notebook -> 3. **Generate a Studio output** — Audio Overview, Study Guide, Briefing Doc, Timeline, FAQ, Infographic, Slides, or Mind Map +> 3. **Generate a Studio output** — Audio/Video Overview, Mind Map, Report (Briefing Doc, Study Guide, FAQ, Timeline), Flashcards, Quiz, Infographic, or Slides — the exact set comes from the live Studio panel > 4. **Create a new notebook** — initialize with title + initial sources > > *Why I'm asking:* Each action takes a different path through the UI and requires different parameters. Naming the action upfront prevents wasted screenshots and lets me ask only the follow-up questions that apply. @@ -70,7 +70,7 @@ For action 4 (create new): replace with "What's the title for the new notebook?" > *Why I'm asking:* Each source type goes through a different sub-flow in the Add Source dialog. Picking upfront saves a step." **Action 3 (Studio output):** -> "Which Studio output? Audio Overview / Study Guide / Briefing Doc / Timeline / FAQ / Table of Contents / Infographic / Slides / Mind Map. And: any custom-prompt direction? **Default prompts produce mediocre output — I always open the customization menu and write a detailed prompt.** Tell me the angle or audience. +> "Which Studio output? As of 2026-06 the Studio panel offers Audio Overview, Video Overview, Mind Map, Reports (Briefing Doc / Study Guide / FAQ / Timeline / custom), Flashcards, Quiz, Infographic, and Slides — I'll screenshot the live panel and confirm what your account actually shows before clicking. And: any custom-prompt direction? **Default prompts produce mediocre output — I always open the customization menu and write a detailed prompt.** Tell me the angle or audience. > > *Why I'm asking:* The output type sets the UI button to find. The custom prompt is mandatory for quality." @@ -137,12 +137,12 @@ Sub-flows per source type: ## Action 3: Studio Outputs -**All 9 output types supported:** Audio Overview, Study Guide, Briefing Doc, Timeline, FAQ, Table of Contents, Infographic, Slides, Mind Map. +**Discover, don't assume.** NotebookLM's Studio inventory changes between rollouts and account tiers. As of the last verification (2026-06) the panel offers: **Audio Overview, Video Overview, Mind Map, Reports** (Briefing Doc, Study Guide, FAQ, Timeline, custom report formats), **Flashcards, Quiz, Infographic, Slides**. Treat this list as a hint, not ground truth — the screenshot of the live Studio panel is the authority. NotebookLM's UI evolves quickly; verify against the live product and update this section when it drifts (Studio inventory last verified 2026-06). **Mandatory workflow:** -1. Locate Studio panel (right side; may need toggle) -2. Find the specific output button for the requested type +1. Locate Studio panel (right side; may need toggle) and **screenshot it — the tiles you see are the real output types for this account** +2. Find the specific output button for the requested type (if it isn't visible, check "Discover more"/overflow before declaring it unavailable) 3. **Open customization menu** (chevron/arrow next to button) — **NOT the main button** 4. **Write detailed custom prompt** (from Q4) 5. Confirm and submit @@ -188,10 +188,18 @@ Use `scripts/async_action_classifier.py` to determine wait-or-notify per action: | Add Source (URL/text/file) | Yes — wait for ingestion spinner (~5-30s) | | Read/Extract (chat) | Yes — wait 3-5s for response | | Studio: Audio Overview | **No** — fire and notify (5-10 min) | +| Studio: Video Overview | **No** — fire and notify (5-15 min) | | Studio: Infographic / Slides / Mind Map | **No** — fire and notify (2-5 min) | -| Studio: Study Guide / Briefing Doc / FAQ | Yes — wait ~30-60s | +| Studio: Study Guide / Briefing Doc / FAQ / Flashcards / Quiz | Yes — wait ~30-60s | | Create New Notebook | Yes — wait for auto-summary (<30s) | +```bash +# Verdict + paste-ready notify message for any action +python3 scripts/async_action_classifier.py --action "video overview" +# -> Verdict: FIRE_AND_NOTIFY, estimated 5-15 minutes, with the exact +# "NOT waiting in this session" message to relay to the user +``` + See [`references/async_action_discipline.md`](https://github.com/alirezarezvani/claude-skills/tree/main/research/notebooklm/skills/notebooklm/references/async_action_discipline.md) for the canon. ## Screenshot-First Discipline diff --git a/docs/skills/research/patent.md b/docs/skills/research/patent.md index 91a2f10c..619ae86b 100644 --- a/docs/skills/research/patent.md +++ b/docs/skills/research/patent.md @@ -109,7 +109,7 @@ Asked for novelty and FTO; skipped for pure landscape (always signal-gathering b Deterministic from intake answers. Use `scripts/sub_use_case_router.py`: ```bash -python ../scripts/sub_use_case_router.py \ +python scripts/sub_use_case_router.py \ --sub-use-case novelty \ --jurisdictions "" \ --risk strict \ @@ -184,7 +184,7 @@ If no Lens.org key: skip; note in audit log; recommend manual citation review on Same invention often filed in multiple jurisdictions (US + EP + JP + CN). Group by family ID or priority number to avoid double-counting. Use `scripts/family_resolver.py`: ```bash -python ../scripts/family_resolver.py --hits-file hits.json +python scripts/family_resolver.py --hits-file hits.json # Returns: deduplicated family list + family-member jurisdictions ``` @@ -239,7 +239,7 @@ Surface the **legally-relevant date** per sub-use-case: - Save: `<output-dir>/patent_<invention-slug>_<sub-use-case>_<YYYY-MM-DD>.docx` - Chat summary: file path + sub-use-case + verdict + audit counts + plan-tier -- Validate: `python scripts/office/validate.py <docx>` +- Validate: check zip integrity with `python3 -c "import zipfile,sys; zipfile.ZipFile(sys.argv[1]).testzip()" <docx>` (no output = intact), then confirm the required sections are present - Reminder: "Consult patent attorney before filing/licensing" ## Tooling diff --git a/docs/skills/research/syllabus.md b/docs/skills/research/syllabus.md index 018fe3a5..cb3f9f0c 100644 --- a/docs/skills/research/syllabus.md +++ b/docs/skills/research/syllabus.md @@ -187,7 +187,7 @@ Use `scripts/discussion_question_validator.py` to flag recall-only questions. ## Phase 5: Generate .docx via Bundled Script ```bash -node ../scripts/generate_reading_list.js \ +node scripts/generate_reading_list.js \ --input /tmp/syllabus_data.json \ --output /path/to/reading_list_<course>_<date>.docx ``` @@ -251,7 +251,7 @@ See [`references/bundled_script_pattern.md`](https://github.com/alirezarezvani/c - File path - Audit summary in chat: "Saved {file}. {N} sections × {M} papers / {K} cited. Plan tier: {tier}." -- Validate: `python scripts/office/validate.py <docx>` +- Validate: check zip integrity with `python3 -c "import zipfile,sys; zipfile.ZipFile(sys.argv[1]).testzip()" <docx>` (no output = intact), then confirm the required sections are present ## Tooling diff --git a/engineering-team/README.md b/engineering-team/README.md index aa7cc0be..aa2ea5fe 100644 --- a/engineering-team/README.md +++ b/engineering-team/README.md @@ -1,6 +1,6 @@ # Engineering Skills Collection -Complete set of 18 engineering role skills tailored to your tech stack (ReactJS, NextJS, NodeJS, Express, React Native, Swift, Kotlin, Flutter, Postgres, GraphQL, Go, Python). +Complete set of 32 engineering skills (role skills, security suite, AI/ML/Data, and specialized tools) tailored to your tech stack (ReactJS, NextJS, NodeJS, Express, React Native, Swift, Kotlin, Flutter, Postgres, GraphQL, Go, Python). ## ⚡ Installation @@ -23,30 +23,30 @@ npx ai-agent-skills install alirezarezvani/claude-skills/engineering-team --agen ```bash # Core Engineering -npx ai-agent-skills install alirezarezvani/claude-skills/engineering-team/senior-architect -npx ai-agent-skills install alirezarezvani/claude-skills/engineering-team/senior-frontend -npx ai-agent-skills install alirezarezvani/claude-skills/engineering-team/senior-backend -npx ai-agent-skills install alirezarezvani/claude-skills/engineering-team/senior-fullstack -npx ai-agent-skills install alirezarezvani/claude-skills/engineering-team/senior-qa -npx ai-agent-skills install alirezarezvani/claude-skills/engineering-team/senior-devops -npx ai-agent-skills install alirezarezvani/claude-skills/engineering-team/senior-secops -npx ai-agent-skills install alirezarezvani/claude-skills/engineering-team/code-reviewer -npx ai-agent-skills install alirezarezvani/claude-skills/engineering-team/senior-security +npx ai-agent-skills install alirezarezvani/claude-skills/engineering-team/skills/senior-architect +npx ai-agent-skills install alirezarezvani/claude-skills/engineering-team/skills/senior-frontend +npx ai-agent-skills install alirezarezvani/claude-skills/engineering-team/skills/senior-backend +npx ai-agent-skills install alirezarezvani/claude-skills/engineering-team/skills/senior-fullstack +npx ai-agent-skills install alirezarezvani/claude-skills/engineering-team/skills/senior-qa +npx ai-agent-skills install alirezarezvani/claude-skills/engineering-team/skills/senior-devops +npx ai-agent-skills install alirezarezvani/claude-skills/engineering-team/skills/senior-secops +npx ai-agent-skills install alirezarezvani/claude-skills/engineering-team/skills/code-reviewer +npx ai-agent-skills install alirezarezvani/claude-skills/engineering-team/skills/senior-security # Cloud & Enterprise -npx ai-agent-skills install alirezarezvani/claude-skills/engineering-team/aws-solution-architect -npx ai-agent-skills install alirezarezvani/claude-skills/engineering-team/ms365-tenant-manager +npx ai-agent-skills install alirezarezvani/claude-skills/engineering-team/skills/aws-solution-architect +npx ai-agent-skills install alirezarezvani/claude-skills/engineering-team/skills/ms365-tenant-manager # Development Tools -npx ai-agent-skills install alirezarezvani/claude-skills/engineering-team/tdd-guide -npx ai-agent-skills install alirezarezvani/claude-skills/engineering-team/tech-stack-evaluator +npx ai-agent-skills install alirezarezvani/claude-skills/engineering-team/skills/tdd-guide +npx ai-agent-skills install alirezarezvani/claude-skills/engineering-team/skills/tech-stack-evaluator # AI/ML/Data -npx ai-agent-skills install alirezarezvani/claude-skills/engineering-team/senior-data-scientist -npx ai-agent-skills install alirezarezvani/claude-skills/engineering-team/senior-data-engineer -npx ai-agent-skills install alirezarezvani/claude-skills/engineering-team/senior-ml-engineer -npx ai-agent-skills install alirezarezvani/claude-skills/engineering-team/senior-prompt-engineer -npx ai-agent-skills install alirezarezvani/claude-skills/engineering-team/senior-computer-vision +npx ai-agent-skills install alirezarezvani/claude-skills/engineering-team/skills/senior-data-scientist +npx ai-agent-skills install alirezarezvani/claude-skills/engineering-team/skills/senior-data-engineer +npx ai-agent-skills install alirezarezvani/claude-skills/engineering-team/skills/senior-ml-engineer +npx ai-agent-skills install alirezarezvani/claude-skills/engineering-team/skills/senior-prompt-engineer +npx ai-agent-skills install alirezarezvani/claude-skills/engineering-team/skills/senior-computer-vision ``` **Supported Agents:** Claude Code, Cursor, VS Code, Copilot, Goose, Amp, Codex @@ -74,7 +74,7 @@ skill-name/ ## 🎯 Skills Overview -### 1. Senior Software Architect (`senior-architect.zip`) +### 1. Senior Software Architect (`skills/senior-architect/`) **Purpose:** System architecture design, tech stack decisions, architecture diagrams @@ -104,7 +104,7 @@ skill-name/ --- -### 2. Senior Frontend Engineer (`senior-frontend.zip`) +### 2. Senior Frontend Engineer (`skills/senior-frontend/`) **Purpose:** Frontend development with React, Next.js, TypeScript @@ -134,7 +134,7 @@ skill-name/ --- -### 3. Senior Backend Engineer (`senior-backend.zip`) +### 3. Senior Backend Engineer (`skills/senior-backend/`) **Purpose:** Backend development with Node.js, Express, GraphQL, Go, Python @@ -164,7 +164,7 @@ skill-name/ --- -### 4. Senior Fullstack Engineer (`senior-fullstack.zip`) +### 4. Senior Fullstack Engineer (`skills/senior-fullstack/`) **Purpose:** End-to-end application development @@ -194,7 +194,7 @@ skill-name/ --- -### 5. Senior QA Testing Engineer (`senior-qa.zip`) +### 5. Senior QA Testing Engineer (`skills/senior-qa/`) **Purpose:** Quality assurance and test automation for React/Next.js applications @@ -229,7 +229,7 @@ skill-name/ --- -### 6. Senior DevOps Engineer (`senior-devops.zip`) +### 6. Senior DevOps Engineer (`skills/senior-devops/`) **Purpose:** CI/CD, infrastructure automation, deployment @@ -259,7 +259,7 @@ skill-name/ --- -### 7. Senior SecOps Engineer (`senior-secops.zip`) +### 7. Senior SecOps Engineer (`skills/senior-secops/`) **Purpose:** Security operations and compliance @@ -289,7 +289,7 @@ skill-name/ --- -### 8. Code Reviewer (`code-reviewer.zip`) +### 8. Code Reviewer (`skills/code-reviewer/`) **Purpose:** Code review automation and quality checking @@ -319,7 +319,7 @@ skill-name/ --- -### 9. Senior Security Engineer (`senior-security.zip`) +### 9. Senior Security Engineer (`skills/senior-security/`) **Purpose:** Security architecture and penetration testing @@ -353,8 +353,8 @@ skill-name/ ### Installation -1. **Download the skills** you need from the files above -2. **Extract** the zip file +1. **Pick the skills** you need under `skills/` +2. **Open** the skill folder (e.g., `cd skills/senior-architect`) 3. **Install dependencies** (if needed): ```bash # For Python scripts @@ -379,7 +379,7 @@ ls references/ python scripts/[script-name].py --help # Example: Generate architecture diagrams -cd senior-architect +cd skills/senior-architect python scripts/architecture_diagram_generator.py --type c4 --output ./docs ``` @@ -414,7 +414,7 @@ python scripts/architecture_diagram_generator.py --type c4 --output ./docs ```bash # Step 1: Design architecture -cd senior-architect +cd skills/senior-architect python scripts/project_architect.py my-app --pattern microservices # Step 2: Scaffold project @@ -430,7 +430,7 @@ python scripts/pipeline_generator.py my-app --platform github ```bash # Step 1: Analyze PR -cd code-reviewer +cd skills/code-reviewer python scripts/pr_analyzer.py ../my-app # Step 2: Check quality @@ -444,7 +444,7 @@ python scripts/review_report_generator.py ../my-app --output review.md ```bash # Step 1: Scan for vulnerabilities -cd senior-secops +cd skills/senior-secops python scripts/security_scanner.py ../my-app # Step 2: Assess risks @@ -586,8 +586,8 @@ Each skill includes: ## 🚀 Next Steps -1. **Download** the skills you need most -2. **Extract** and explore the structure +1. **Pick** the skills you need most under `skills/` +2. **Explore** the folder structure 3. **Read** SKILL.md for each skill 4. **Run** example scripts to understand capabilities 5. **Customize** for your specific needs diff --git a/engineering-team/START_HERE.md b/engineering-team/START_HERE.md index 54995231..d90d5afb 100644 --- a/engineering-team/START_HERE.md +++ b/engineering-team/START_HERE.md @@ -2,7 +2,7 @@ ## 📦 **What You're Getting** -**14 world-class, senior-level skills** for building exceptional engineering and AI/ML/Data teams. +**32 production-ready skills** for building exceptional engineering and AI/ML/Data teams (this quick-start tour covers the original 14 role skills; see README.md for the full current list). All skills follow your exact template structure with: - ✅ **SKILL.md** - Complete documentation with quick start @@ -14,7 +14,7 @@ All skills follow your exact template structure with: ## 📚 **Your Documents** -### **1. [TEAM_STRUCTURE_GUIDE.md](computer:///mnt/user-data/outputs/TEAM_STRUCTURE_GUIDE.md)** ⭐ **START HERE** +### **1. [TEAM_STRUCTURE_GUIDE.md](TEAM_STRUCTURE_GUIDE.md)** ⭐ **START HERE** **THE MASTER GUIDE** - Complete team structure recommendations: - Team compositions for startups, scale-ups, and enterprises @@ -24,7 +24,7 @@ All skills follow your exact template structure with: - Performance benchmarks - Tech stack coverage -### **2. [README.md](computer:///mnt/user-data/outputs/README.md)** +### **2. [README.md](README.md)** Original engineering skills guide covering the 9 engineering roles in detail. @@ -34,57 +34,57 @@ Original engineering skills guide covering the 9 engineering roles in detail. ### **Need to...** -**Design a system?** → [senior-architect.zip](computer:///mnt/user-data/outputs/senior-architect.zip) +**Design a system?** → [skills/senior-architect/](skills/senior-architect/) -**Build frontend?** → [senior-frontend.zip](computer:///mnt/user-data/outputs/senior-frontend.zip) +**Build frontend?** → [skills/senior-frontend/](skills/senior-frontend/) -**Build backend?** → [senior-backend.zip](computer:///mnt/user-data/outputs/senior-backend.zip) +**Build backend?** → [skills/senior-backend/](skills/senior-backend/) -**Build full-stack?** → [senior-fullstack.zip](computer:///mnt/user-data/outputs/senior-fullstack.zip) +**Build full-stack?** → [skills/senior-fullstack/](skills/senior-fullstack/) -**Setup testing?** → [senior-qa.zip](computer:///mnt/user-data/outputs/senior-qa.zip) +**Setup testing?** → [skills/senior-qa/](skills/senior-qa/) -**Setup DevOps?** → [senior-devops.zip](computer:///mnt/user-data/outputs/senior-devops.zip) +**Setup DevOps?** → [skills/senior-devops/](skills/senior-devops/) -**Setup security?** → [senior-secops.zip](computer:///mnt/user-data/outputs/senior-secops.zip) or [senior-security.zip](computer:///mnt/user-data/outputs/senior-security.zip) +**Setup security?** → [skills/senior-secops/](skills/senior-secops/) or [skills/senior-security/](skills/senior-security/) -**Review code?** → [code-reviewer.zip](computer:///mnt/user-data/outputs/code-reviewer.zip) +**Review code?** → [skills/code-reviewer/](skills/code-reviewer/) -**Analyze data?** → [senior-data-scientist.zip](computer:///mnt/user-data/outputs/senior-data-scientist.zip) +**Analyze data?** → [skills/senior-data-scientist/](skills/senior-data-scientist/) -**Build data pipelines?** → [senior-data-engineer.zip](computer:///mnt/user-data/outputs/senior-data-engineer.zip) +**Build data pipelines?** → [skills/senior-data-engineer/](skills/senior-data-engineer/) -**Deploy ML models?** → [senior-ml-engineer.zip](computer:///mnt/user-data/outputs/senior-ml-engineer.zip) +**Deploy ML models?** → [skills/senior-ml-engineer/](skills/senior-ml-engineer/) -**Optimize LLMs?** → [senior-prompt-engineer.zip](computer:///mnt/user-data/outputs/senior-prompt-engineer.zip) +**Optimize LLMs?** → [skills/senior-prompt-engineer/](skills/senior-prompt-engineer/) -**Build vision AI?** → [senior-computer-vision.zip](computer:///mnt/user-data/outputs/senior-computer-vision.zip) +**Build vision AI?** → [skills/senior-computer-vision/](skills/senior-computer-vision/) --- ## 🏗️ **Team Size Guide** ### **Startup (5-10 people)** -Download these 5 skills: -1. [senior-fullstack.zip](computer:///mnt/user-data/outputs/senior-fullstack.zip) (×2) -2. [senior-data-scientist.zip](computer:///mnt/user-data/outputs/senior-data-scientist.zip) (×1) -3. [senior-devops.zip](computer:///mnt/user-data/outputs/senior-devops.zip) (×1) -4. [senior-ml-engineer.zip](computer:///mnt/user-data/outputs/senior-ml-engineer.zip) (×1) +Use these 5 skills: +1. [skills/senior-fullstack/](skills/senior-fullstack/) (×2) +2. [skills/senior-data-scientist/](skills/senior-data-scientist/) (×1) +3. [skills/senior-devops/](skills/senior-devops/) (×1) +4. [skills/senior-ml-engineer/](skills/senior-ml-engineer/) (×1) ### **Scale-Up (10-25 people)** -Download these 9 skills: -1. [senior-architect.zip](computer:///mnt/user-data/outputs/senior-architect.zip) (×1) -2. [senior-frontend.zip](computer:///mnt/user-data/outputs/senior-frontend.zip) (×2) -3. [senior-backend.zip](computer:///mnt/user-data/outputs/senior-backend.zip) (×3) -4. [senior-data-engineer.zip](computer:///mnt/user-data/outputs/senior-data-engineer.zip) (×2) -5. [senior-data-scientist.zip](computer:///mnt/user-data/outputs/senior-data-scientist.zip) (×2) -6. [senior-ml-engineer.zip](computer:///mnt/user-data/outputs/senior-ml-engineer.zip) (×2) -7. [senior-qa.zip](computer:///mnt/user-data/outputs/senior-qa.zip) (×1) -8. [senior-devops.zip](computer:///mnt/user-data/outputs/senior-devops.zip) (×1) -9. [senior-secops.zip](computer:///mnt/user-data/outputs/senior-secops.zip) (×1) +Use these 9 skills: +1. [skills/senior-architect/](skills/senior-architect/) (×1) +2. [skills/senior-frontend/](skills/senior-frontend/) (×2) +3. [skills/senior-backend/](skills/senior-backend/) (×3) +4. [skills/senior-data-engineer/](skills/senior-data-engineer/) (×2) +5. [skills/senior-data-scientist/](skills/senior-data-scientist/) (×2) +6. [skills/senior-ml-engineer/](skills/senior-ml-engineer/) (×2) +7. [skills/senior-qa/](skills/senior-qa/) (×1) +8. [skills/senior-devops/](skills/senior-devops/) (×1) +9. [skills/senior-secops/](skills/senior-secops/) (×1) ### **Enterprise (25-50+ people)** -Download all 14 skills - you'll need the full suite! +Use all 14 role skills - you'll need the full suite! --- @@ -94,25 +94,25 @@ Download all 14 skills - you'll need the full suite! | # | Skill | Download | What It Does | |---|-------|----------|--------------| -| 1 | **Senior Architect** | [Download](computer:///mnt/user-data/outputs/senior-architect.zip) | System design, architecture decisions, diagrams | -| 2 | **Senior Frontend** | [Download](computer:///mnt/user-data/outputs/senior-frontend.zip) | React, Next.js, UI/UX, performance | -| 3 | **Senior Backend** | [Download](computer:///mnt/user-data/outputs/senior-backend.zip) | APIs, databases, business logic | -| 4 | **Senior Fullstack** | [Download](computer:///mnt/user-data/outputs/senior-fullstack.zip) | End-to-end development | -| 5 | **Senior QA** | [Download](computer:///mnt/user-data/outputs/senior-qa.zip) | Testing, automation, quality | -| 6 | **Senior DevOps** | [Download](computer:///mnt/user-data/outputs/senior-devops.zip) | CI/CD, infrastructure, deployment | -| 7 | **Senior SecOps** | [Download](computer:///mnt/user-data/outputs/senior-secops.zip) | Security operations, compliance | -| 8 | **Code Reviewer** | [Download](computer:///mnt/user-data/outputs/code-reviewer.zip) | Code quality, standards, reviews | -| 9 | **Senior Security** | [Download](computer:///mnt/user-data/outputs/senior-security.zip) | Security architecture, pentesting | +| 1 | **Senior Architect** | [skills/senior-architect/](skills/senior-architect/) | System design, architecture decisions, diagrams | +| 2 | **Senior Frontend** | [skills/senior-frontend/](skills/senior-frontend/) | React, Next.js, UI/UX, performance | +| 3 | **Senior Backend** | [skills/senior-backend/](skills/senior-backend/) | APIs, databases, business logic | +| 4 | **Senior Fullstack** | [skills/senior-fullstack/](skills/senior-fullstack/) | End-to-end development | +| 5 | **Senior QA** | [skills/senior-qa/](skills/senior-qa/) | Testing, automation, quality | +| 6 | **Senior DevOps** | [skills/senior-devops/](skills/senior-devops/) | CI/CD, infrastructure, deployment | +| 7 | **Senior SecOps** | [skills/senior-secops/](skills/senior-secops/) | Security operations, compliance | +| 8 | **Code Reviewer** | [skills/code-reviewer/](skills/code-reviewer/) | Code quality, standards, reviews | +| 9 | **Senior Security** | [skills/senior-security/](skills/senior-security/) | Security architecture, pentesting | ### **AI/ML/Data Team (5 Skills)** | # | Skill | Download | What It Does | |---|-------|----------|--------------| -| 10 | **Senior Data Scientist** | [Download](computer:///mnt/user-data/outputs/senior-data-scientist.zip) | Statistical modeling, experimentation, analytics | -| 11 | **Senior Data Engineer** | [Download](computer:///mnt/user-data/outputs/senior-data-engineer.zip) | Data pipelines, ETL, infrastructure | -| 12 | **Senior ML Engineer** | [Download](computer:///mnt/user-data/outputs/senior-ml-engineer.zip) | MLOps, model deployment, LLMs | -| 13 | **Senior Prompt Engineer** | [Download](computer:///mnt/user-data/outputs/senior-prompt-engineer.zip) | LLM optimization, RAG, agents | -| 14 | **Senior Computer Vision** | [Download](computer:///mnt/user-data/outputs/senior-computer-vision.zip) | Image/video AI, object detection | +| 10 | **Senior Data Scientist** | [skills/senior-data-scientist/](skills/senior-data-scientist/) | Statistical modeling, experimentation, analytics | +| 11 | **Senior Data Engineer** | [skills/senior-data-engineer/](skills/senior-data-engineer/) | Data pipelines, ETL, infrastructure | +| 12 | **Senior ML Engineer** | [skills/senior-ml-engineer/](skills/senior-ml-engineer/) | MLOps, model deployment, LLMs | +| 13 | **Senior Prompt Engineer** | [skills/senior-prompt-engineer/](skills/senior-prompt-engineer/) | LLM optimization, RAG, agents | +| 14 | **Senior Computer Vision** | [skills/senior-computer-vision/](skills/senior-computer-vision/) | Image/video AI, object detection | --- @@ -121,17 +121,16 @@ Download all 14 skills - you'll need the full suite! ### **Step 1: Choose Your Path** Pick one based on your immediate need: -- **Building a team?** → Read [TEAM_STRUCTURE_GUIDE.md](computer:///mnt/user-data/outputs/TEAM_STRUCTURE_GUIDE.md) -- **Starting a project?** → Download [senior-architect.zip](computer:///mnt/user-data/outputs/senior-architect.zip) + [senior-fullstack.zip](computer:///mnt/user-data/outputs/senior-fullstack.zip) -- **Building AI features?** → Download [senior-ml-engineer.zip](computer:///mnt/user-data/outputs/senior-ml-engineer.zip) + [senior-prompt-engineer.zip](computer:///mnt/user-data/outputs/senior-prompt-engineer.zip) -- **Data infrastructure?** → Download [senior-data-engineer.zip](computer:///mnt/user-data/outputs/senior-data-engineer.zip) +- **Building a team?** → Read [TEAM_STRUCTURE_GUIDE.md](TEAM_STRUCTURE_GUIDE.md) +- **Starting a project?** → Download [skills/senior-architect/](skills/senior-architect/) + [skills/senior-fullstack/](skills/senior-fullstack/) +- **Building AI features?** → Download [skills/senior-ml-engineer/](skills/senior-ml-engineer/) + [skills/senior-prompt-engineer/](skills/senior-prompt-engineer/) +- **Data infrastructure?** → Download [skills/senior-data-engineer/](skills/senior-data-engineer/) ### **Step 2: Extract & Explore** ```bash -# Extract the skill -unzip senior-ml-engineer.zip -cd senior-ml-engineer +# Open the skill folder +cd skills/senior-ml-engineer # Read the main guide cat SKILL.md @@ -266,15 +265,15 @@ vim SKILL.md ## 🔥 **Common Use Cases** ### **Use Case 1: Starting a Startup** -**Downloads:** senior-fullstack.zip, senior-ml-engineer.zip, senior-devops.zip +**Downloads:** skills/senior-fullstack/, skills/senior-ml-engineer/, skills/senior-devops/ **Focus:** MVP development, rapid iteration, lean team ### **Use Case 2: Building AI Product** -**Downloads:** senior-prompt-engineer.zip, senior-ml-engineer.zip, senior-data-engineer.zip +**Downloads:** skills/senior-prompt-engineer/, skills/senior-ml-engineer/, skills/senior-data-engineer/ **Focus:** LLM integration, RAG systems, data pipelines ### **Use Case 3: Scaling Engineering Team** -**Downloads:** senior-architect.zip, code-reviewer.zip, all engineering skills +**Downloads:** skills/senior-architect/, skills/code-reviewer/, all engineering skills **Focus:** Architecture, standards, processes, quality ### **Use Case 4: Data Science Team** @@ -282,7 +281,7 @@ vim SKILL.md **Focus:** Analytics, ML, data infrastructure ### **Use Case 5: Computer Vision Product** -**Downloads:** senior-computer-vision.zip, senior-ml-engineer.zip, senior-devops.zip +**Downloads:** skills/senior-computer-vision/, skills/senior-ml-engineer/, skills/senior-devops/ **Focus:** Vision models, real-time inference, deployment --- @@ -307,7 +306,7 @@ What makes these skills special: ## 🎯 **Next Actions** ### **Right Now (5 minutes)** -1. ✅ Read [TEAM_STRUCTURE_GUIDE.md](computer:///mnt/user-data/outputs/TEAM_STRUCTURE_GUIDE.md) +1. ✅ Read [TEAM_STRUCTURE_GUIDE.md](TEAM_STRUCTURE_GUIDE.md) 2. ✅ Identify your team size 3. ✅ Note which skills you need diff --git a/engineering-team/TEAM_STRUCTURE_GUIDE.md b/engineering-team/TEAM_STRUCTURE_GUIDE.md index fd212c50..e22343fc 100644 --- a/engineering-team/TEAM_STRUCTURE_GUIDE.md +++ b/engineering-team/TEAM_STRUCTURE_GUIDE.md @@ -10,25 +10,25 @@ Complete set of **14 senior-level skills** for building exceptional engineering | Role | Skill Package | Primary Focus | |------|---------------|---------------| -| **Senior Software Architect** | `senior-architect.zip` | System design, architecture decisions, tech stack | -| **Senior Frontend Engineer** | `senior-frontend.zip` | React, Next.js, UI/UX, performance | -| **Senior Backend Engineer** | `senior-backend.zip` | APIs, databases, business logic | -| **Senior Fullstack Engineer** | `senior-fullstack.zip` | End-to-end development | -| **Senior QA/Test Engineer** | `senior-qa.zip` | Quality assurance, test automation | -| **Senior DevOps Engineer** | `senior-devops.zip` | CI/CD, infrastructure, deployment | -| **Senior SecOps Engineer** | `senior-secops.zip` | Security operations, compliance | -| **Code Reviewer** | `code-reviewer.zip` | Code quality, standards, reviews | -| **Senior Security Engineer** | `senior-security.zip` | Security architecture, pentesting | +| **Senior Software Architect** | `skills/senior-architect/` | System design, architecture decisions, tech stack | +| **Senior Frontend Engineer** | `skills/senior-frontend/` | React, Next.js, UI/UX, performance | +| **Senior Backend Engineer** | `skills/senior-backend/` | APIs, databases, business logic | +| **Senior Fullstack Engineer** | `skills/senior-fullstack/` | End-to-end development | +| **Senior QA/Test Engineer** | `skills/senior-qa/` | Quality assurance, test automation | +| **Senior DevOps Engineer** | `skills/senior-devops/` | CI/CD, infrastructure, deployment | +| **Senior SecOps Engineer** | `skills/senior-secops/` | Security operations, compliance | +| **Code Reviewer** | `skills/code-reviewer/` | Code quality, standards, reviews | +| **Senior Security Engineer** | `skills/senior-security/` | Security architecture, pentesting | ### **AI/ML/Data Team (5 Roles)** | Role | Skill Package | Primary Focus | |------|---------------|---------------| -| **Senior Data Scientist** | `senior-data-scientist.zip` | Statistical modeling, experimentation, analytics | -| **Senior Data Engineer** | `senior-data-engineer.zip` | Data pipelines, ETL, data infrastructure | -| **Senior ML/AI Engineer** | `senior-ml-engineer.zip` | MLOps, model deployment, LLM integration | -| **Senior Prompt Engineer** | `senior-prompt-engineer.zip` | LLM optimization, RAG, agentic AI | -| **Senior Computer Vision Engineer** | `senior-computer-vision.zip` | Image/video AI, object detection, vision systems | +| **Senior Data Scientist** | `skills/senior-data-scientist/` | Statistical modeling, experimentation, analytics | +| **Senior Data Engineer** | `skills/senior-data-engineer/` | Data pipelines, ETL, data infrastructure | +| **Senior ML/AI Engineer** | `skills/senior-ml-engineer/` | MLOps, model deployment, LLM integration | +| **Senior Prompt Engineer** | `skills/senior-prompt-engineer/` | LLM optimization, RAG, agentic AI | +| **Senior Computer Vision Engineer** | `skills/senior-computer-vision/` | Image/video AI, object detection, vision systems | --- @@ -106,70 +106,70 @@ Complete set of **14 senior-level skills** for building exceptional engineering ### **When to Use Each Skill** #### **System Design & Architecture** -→ Use `senior-architect.zip` +→ Use `skills/senior-architect/` - Designing new systems - Making tech stack decisions - Creating architecture diagrams - Evaluating trade-offs #### **Frontend Development** -→ Use `senior-frontend.zip` +→ Use `skills/senior-frontend/` - Building React/Next.js apps - UI/UX implementation - Performance optimization - State management #### **Backend Development** -→ Use `senior-backend.zip` +→ Use `skills/senior-backend/` - Designing APIs (REST/GraphQL) - Database optimization - Authentication/authorization - Microservices #### **Full-Stack Development** -→ Use `senior-fullstack.zip` +→ Use `skills/senior-fullstack/` - Building complete features - Rapid prototyping - Startup MVP development - Code quality analysis #### **Testing & QA** -→ Use `senior-qa.zip` +→ Use `skills/senior-qa/` - Test strategy design - Test automation - Coverage analysis - Quality metrics #### **DevOps & Infrastructure** -→ Use `senior-devops.zip` +→ Use `skills/senior-devops/` - CI/CD pipelines - Infrastructure as code - Deployment automation - Container orchestration #### **Security Operations** -→ Use `senior-secops.zip` +→ Use `skills/senior-secops/` - Security scanning - Vulnerability management - Compliance checking - Incident response #### **Code Reviews** -→ Use `code-reviewer.zip` +→ Use `skills/code-reviewer/` - PR reviews - Code quality checks - Standards enforcement - Mentoring feedback #### **Security Architecture** -→ Use `senior-security.zip` +→ Use `skills/senior-security/` - Security design - Penetration testing - Threat modeling - Cryptography #### **Data Science** -→ Use `senior-data-scientist.zip` +→ Use `skills/senior-data-scientist/` - Statistical modeling - A/B testing - Causal inference @@ -177,7 +177,7 @@ Complete set of **14 senior-level skills** for building exceptional engineering - Business analytics #### **Data Engineering** -→ Use `senior-data-engineer.zip` +→ Use `skills/senior-data-engineer/` - Data pipelines - ETL/ELT design - Data modeling @@ -185,7 +185,7 @@ Complete set of **14 senior-level skills** for building exceptional engineering - Stream processing #### **ML/AI Engineering** -→ Use `senior-ml-engineer.zip` +→ Use `skills/senior-ml-engineer/` - Model deployment - MLOps - LLM integration @@ -193,7 +193,7 @@ Complete set of **14 senior-level skills** for building exceptional engineering - Model monitoring #### **Prompt Engineering** -→ Use `senior-prompt-engineer.zip` +→ Use `skills/senior-prompt-engineer/` - LLM optimization - Prompt patterns - Agent design @@ -201,7 +201,7 @@ Complete set of **14 senior-level skills** for building exceptional engineering - AI evaluation #### **Computer Vision** -→ Use `senior-computer-vision.zip` +→ Use `skills/senior-computer-vision/` - Object detection - Image segmentation - Video analysis @@ -292,16 +292,15 @@ Complete set of **14 senior-level skills** for building exceptional engineering - **Scale-up (10-25)**: Add specialists (Frontend, Backend, Data Eng) - **Enterprise (25+)**: Complete teams with redundancy -### **2. Download Relevant Skills** +### **2. Pick Relevant Skills** -Download the skill packages you need from the files above. +Each skill lives in this repo under `skills/<name>/` — use it in place or copy the folder. ### **3. Extract and Explore** ```bash -# Extract a skill -unzip senior-ml-engineer.zip -cd senior-ml-engineer +# Open a skill folder +cd skills/senior-ml-engineer # Read the documentation cat SKILL.md diff --git a/engineering-team/aws-solution-architect.zip b/engineering-team/aws-solution-architect.zip deleted file mode 100644 index 9071f14a..00000000 Binary files a/engineering-team/aws-solution-architect.zip and /dev/null differ diff --git a/engineering-team/code-reviewer.zip b/engineering-team/code-reviewer.zip deleted file mode 100644 index 4f60105e..00000000 Binary files a/engineering-team/code-reviewer.zip and /dev/null differ diff --git a/engineering-team/google-workspace-cli/.claude-plugin/plugin.json b/engineering-team/google-workspace-cli/.claude-plugin/plugin.json index 49fd5bb4..1cfdc892 100644 --- a/engineering-team/google-workspace-cli/.claude-plugin/plugin.json +++ b/engineering-team/google-workspace-cli/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "google-workspace-cli", "version": "2.9.0", - "description": "Google Workspace administration via the gws CLI. Install, authenticate, and automate Gmail, Drive, Sheets, Calendar, Docs, Chat, and Tasks. 5 Python tools, 3 reference guides, 43 built-in recipes, 10 persona bundles.", + "description": "Google Workspace administration via the gws CLI (github.com/googleworkspace/cli, install: npm i -g @googleworkspace/cli). Authenticate and automate Gmail, Drive, Sheets, Calendar, Docs, Chat, and Tasks. 5 Python tools, 3 reference guides, a local catalog of 43 recipe command templates, and 10 persona bundles. Verify generated commands against gws --help.", "author": { "name": "Alireza Rezvani", "url": "https://alirezarezvani.com" diff --git a/engineering-team/google-workspace-cli/skills/google-workspace-cli/SKILL.md b/engineering-team/google-workspace-cli/skills/google-workspace-cli/SKILL.md index 3db811db..20cab848 100644 --- a/engineering-team/google-workspace-cli/skills/google-workspace-cli/SKILL.md +++ b/engineering-team/google-workspace-cli/skills/google-workspace-cli/SKILL.md @@ -1,11 +1,13 @@ --- name: "google-workspace-cli" -description: "Google Workspace administration via the gws CLI. Install, authenticate, and automate Gmail, Drive, Sheets, Calendar, Docs, Chat, and Tasks. Run security audits, execute 43 built-in recipes, and use 10 persona bundles. Use for Google Workspace admin, gws CLI setup, Gmail automation, Drive management, or Calendar scheduling." +description: "Google Workspace administration via the gws CLI (github.com/googleworkspace/cli). Install, authenticate, and automate Gmail, Drive, Sheets, Calendar, Docs, Chat, and Tasks. Run security audits and use local recipe templates and persona bundles. Use for Google Workspace admin, gws CLI setup, Gmail automation, Drive management, or Calendar scheduling." --- # Google Workspace CLI -Expert guidance and automation for Google Workspace administration using the open-source `gws` CLI. Covers installation, authentication, 18+ service APIs, 43 built-in recipes, and 10 persona bundles for role-based workflows. +Expert guidance and automation for Google Workspace administration using the open-source `gws` CLI ([github.com/googleworkspace/cli](https://github.com/googleworkspace/cli), Apache-2.0). The CLI builds its command surface dynamically from Google's Discovery Service, so it covers every supported Workspace API plus `+`-prefixed helper commands. This skill adds local Python tools (doctor, auth guide, recipe catalog, security audit, output analyzer). + +> **Verify before scripting:** `gws` generates commands at runtime from Google's API discovery documents, and the CLI is pre-v1.0. Always confirm a command's exact surface with `gws --help`, `gws <service> --help`, or `gws schema <service>.<resource>.<method>` before putting it in automation. Commands in this skill marked *(verify)* are illustrative of the `gws <service> <resource> <method>` pattern and must be checked against your installed version. --- @@ -21,37 +23,43 @@ python3 scripts/gws_doctor.py ### Send an Email ```bash -gws gmail users.messages send me --to "team@company.com" \ +gws gmail +send --to "team@company.com" \ --subject "Weekly Update" --body "Here's this week's summary..." ``` ### List Drive Files ```bash -gws drive files list --json --limit 20 | python3 scripts/output_analyzer.py --select "name,mimeType,modifiedTime" --format table +gws drive files list --params '{"pageSize": 20}' | python3 scripts/output_analyzer.py --select "name,mimeType,modifiedTime" --format table ``` --- ## Installation -### npm (recommended) +### npm (recommended; requires Node.js 18+) ```bash -npm install -g @anthropic/gws +npm install -g @googleworkspace/cli gws --version ``` +### Homebrew (macOS/Linux) + +```bash +brew install googleworkspace-cli +``` + ### Cargo (from source) ```bash -cargo install gws-cli +cargo install --git https://github.com/googleworkspace/cli --locked gws --version ``` ### Pre-built Binaries -Download from [github.com/googleworkspace/cli/releases](https://github.com/googleworkspace/cli/releases) for macOS, Linux, or Windows. +Download from [github.com/googleworkspace/cli/releases](https://github.com/googleworkspace/cli/releases) for macOS, Linux, or Windows. Nix users: `nix run github:googleworkspace/cli`. ### Verify Installation @@ -70,23 +78,22 @@ python3 scripts/gws_doctor.py # Step 1: Create Google Cloud project and OAuth credentials python3 scripts/auth_setup_guide.py --guide oauth -# Step 2: Run auth setup +# Step 2: Run interactive auth setup (uses gcloud if available) gws auth setup -# Step 3: Validate -gws auth status --json +# Step 3: Log in, requesting only the scopes you need +gws auth login -s drive,gmail,sheets ``` -### Service Account (Headless/CI) +### Headless/CI ```bash # Generate setup instructions python3 scripts/auth_setup_guide.py --guide service-account -# Configure with key file -export GWS_SERVICE_ACCOUNT_KEY=/path/to/key.json -export GWS_DELEGATED_USER=admin@company.com -gws auth status +# Export credentials from an interactive machine, then point the CLI at them +gws auth export --unmasked > credentials.json +export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/path/to/credentials.json ``` ### Environment Variables @@ -98,12 +105,12 @@ python3 scripts/auth_setup_guide.py --generate-env | Variable | Purpose | |----------|---------| -| `GWS_CLIENT_ID` | OAuth client ID | -| `GWS_CLIENT_SECRET` | OAuth client secret | -| `GWS_TOKEN_PATH` | Custom token storage path | -| `GWS_SERVICE_ACCOUNT_KEY` | Service account JSON key path | -| `GWS_DELEGATED_USER` | User to impersonate (service accounts) | -| `GWS_DEFAULT_FORMAT` | Default output format (json/ndjson/table) | +| `GOOGLE_WORKSPACE_CLI_CLIENT_ID` | OAuth client ID | +| `GOOGLE_WORKSPACE_CLI_CLIENT_SECRET` | OAuth client secret | +| `GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE` | Path to exported credentials JSON | +| `GOOGLE_WORKSPACE_CLI_TOKEN` | Pre-obtained OAuth token | +| `GOOGLE_WORKSPACE_CLI_CONFIG_DIR` | Override default config location | +| `GOOGLE_WORKSPACE_CLI_LOG` | Enable debug logging | ### Validate Authentication @@ -118,46 +125,50 @@ python3 scripts/auth_setup_guide.py --validate --json **Goal:** Automate email operations — send, search, label, and filter management. -### Send and Reply +### Send, Reply, Forward (helper commands) ```bash # Send a new email -gws gmail users.messages send me --to "client@example.com" \ - --subject "Proposal" --body "Please find attached..." \ - --attachment proposal.pdf +gws gmail +send --to "client@example.com" \ + --subject "Proposal" --body "Please find attached..." -# Reply to a thread -gws gmail users.messages reply me --thread-id <THREAD_ID> \ - --body "Thanks for your feedback..." +# Reply to a message (auto-threading); check exact flags with: gws gmail +reply --help +gws gmail +reply ... -# Forward a message -gws gmail users.messages forward me --message-id <MSG_ID> \ - --to "manager@company.com" +# Forward a message; check exact flags with: gws gmail +forward --help +gws gmail +forward ... + +# Unread inbox summary +gws gmail +triage ``` -### Search and Filter +### Search and Inspect (discovery commands) + +Discovery commands follow `gws <service> <resource> <method>` and take request +parameters as JSON via `--params` (query/path params) and `--json` (request body). +Inspect any method's exact schema first: ```bash -# Search emails -gws gmail users.messages list me --query "from:client@example.com after:2025/01/01" --json \ +# What does messages.list accept? (verify) +gws schema gmail.users.messages.list + +# Search emails (verify against the schema above) +gws gmail users messages list --params '{"userId": "me", "q": "from:client@example.com after:2025/01/01"}' \ | python3 scripts/output_analyzer.py --count -# List labels -gws gmail users.labels list me --json - -# Create a filter -gws gmail users.settings.filters create me \ - --criteria '{"from":"notifications@service.com"}' \ - --action '{"addLabelIds":["Label_123"],"removeLabelIds":["INBOX"]}' +# List labels (verify) +gws gmail users labels list --params '{"userId": "me"}' ``` ### Bulk Operations +Use `--dry-run` first, and `--page-all` to paginate (one JSON line per page): + ```bash -# Archive all read emails older than 30 days -gws gmail users.messages list me --query "is:read older_than:30d" --json \ - | python3 scripts/output_analyzer.py --select "id" --format json \ - | xargs -I {} gws gmail users.messages modify me {} --removeLabelIds INBOX +# Preview, then archive read emails older than 30 days (verify method schema first) +gws gmail users messages list --params '{"userId": "me", "q": "is:read older_than:30d"}' --page-all \ + | python3 scripts/output_analyzer.py --select "id" --format json +# Then feed ids to gmail users messages modify (see: gws schema gmail.users.messages.modify) ``` --- @@ -170,48 +181,45 @@ gws gmail users.messages list me --query "is:read older_than:30d" --json \ ```bash # List files -gws drive files list --json --limit 50 \ +gws drive files list --params '{"pageSize": 50}' \ | python3 scripts/output_analyzer.py --select "name,mimeType,size" --format table -# Upload a file -gws drive files create --name "Q1 Report" --upload report.pdf \ - --parents <FOLDER_ID> +# Upload a file (helper) +gws drive +upload ./report.pdf --name "Q1 Report" # Create a Google Sheet -gws sheets spreadsheets create --title "Budget 2026" --json +gws sheets spreadsheets create --json '{"properties": {"title": "Budget 2026"}}' -# Download/export -gws drive files export <FILE_ID> --mime "application/pdf" --output report.pdf +# Download/export — inspect the method first (verify) +gws schema drive.files.export ``` -### Sharing +### Sharing (verify schemas first) ```bash -# Share with user -gws drive permissions create <FILE_ID> \ - --type user --role writer --emailAddress "colleague@company.com" +# Inspect the permissions API surface +gws schema drive.permissions.create -# Share with domain (view only) -gws drive permissions create <FILE_ID> \ - --type domain --role reader --domain "company.com" +# Share with user (verify against schema) +gws drive permissions create --params '{"fileId": "<FILE_ID>"}' \ + --json '{"type": "user", "role": "writer", "emailAddress": "colleague@company.com"}' -# List who has access -gws drive permissions list <FILE_ID> --json +# List who has access (verify) +gws drive permissions list --params '{"fileId": "<FILE_ID>"}' ``` ### Sheets Data ```bash -# Read a range -gws sheets spreadsheets.values get <SHEET_ID> --range "Sheet1!A1:D10" --json +# Read values (helper); check exact flags with: gws sheets +read --help +gws sheets +read ... -# Write data -gws sheets spreadsheets.values update <SHEET_ID> --range "Sheet1!A1" \ - --values '[["Name","Score"],["Alice",95],["Bob",87]]' +# Append a row (helper); check exact flags with: gws sheets +append --help +gws sheets +append ... -# Append rows -gws sheets spreadsheets.values append <SHEET_ID> --range "Sheet1!A1" \ - --values '[["Charlie",92]]' +# Or use discovery methods (verify): +gws schema sheets.spreadsheets.values.update +gws sheets spreadsheets values get --params '{"spreadsheetId": "<SHEET_ID>", "range": "Sheet1!A1:D10"}' ``` --- @@ -223,39 +231,34 @@ gws sheets spreadsheets.values append <SHEET_ID> --range "Sheet1!A1" \ ### Event Management ```bash -# Create an event -gws calendar events insert primary \ - --summary "Sprint Planning" \ - --start "2026-03-15T10:00:00" --end "2026-03-15T11:00:00" \ - --attendees "team@company.com" \ - --location "Conference Room A" +# Create an event (helper); check exact flags with: gws calendar +insert --help +gws calendar +insert ... -# List upcoming events -gws calendar events list primary --timeMin "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \ - --maxResults 10 --json +# Upcoming events (helper, timezone-aware) +gws calendar +agenda -# Quick event (natural language) -gws helpers quick-event "Lunch with Sarah tomorrow at noon" +# Or via discovery (verify): +gws schema calendar.events.insert +gws calendar events list --params '{"calendarId": "primary", "maxResults": 10}' ``` ### Find Available Time ```bash -# Check free/busy for multiple people -gws helpers find-time \ - --attendees "alice@co.com,bob@co.com,charlie@co.com" \ - --duration 60 --within "2026-03-15,2026-03-19" --json +# Free/busy via the Calendar API (verify schema first) +gws schema calendar.freebusy.query +gws calendar freebusy query --json '{"timeMin": "...", "timeMax": "...", "items": [{"id": "alice@co.com"}]}' ``` -### Standup Report +### Standup Report (workflow helpers) ```bash -# Generate daily standup from calendar + tasks -gws recipes standup-report --json \ +# Today's meetings + tasks +gws workflow +standup-report \ | python3 scripts/output_analyzer.py --format table -# Meeting prep (agenda + attendee info) -gws recipes meeting-prep --event-id <EVENT_ID> +# Next meeting prep; check exact flags with: gws workflow +meeting-prep --help +gws workflow +meeting-prep ``` --- @@ -296,9 +299,9 @@ python3 scripts/workspace_audit.py --demo python3 scripts/workspace_audit.py --json | python3 scripts/output_analyzer.py \ --filter "status=FAIL" --select "area,check,remediation" -# Execute remediation (example: restrict external sharing) -gws drive about get --json # Check current settings -# Follow remediation commands from audit output +# Execute remediation (example: check current Drive settings first; verify) +gws drive about get --params '{"fields": "*"}' +# Follow remediation commands from audit output (verify each against gws --help) ``` --- @@ -329,18 +332,18 @@ All scripts are stdlib-only, support `--json` output, and include demo mode with ### Automation -1. Pipe `--json` output through `output_analyzer.py` for filtering and aggregation -2. Use recipes for multi-step operations instead of chaining raw commands -3. Select a persona bundle to scope recipes to your role -4. Use NDJSON format (`--format ndjson`) for streaming large result sets -5. Set `GWS_DEFAULT_FORMAT=json` in your shell profile for scripting +1. All `gws` output is structured JSON — pipe it through `output_analyzer.py` for filtering and aggregation +2. Use `gws workflow +*` helpers for multi-step operations instead of chaining raw commands +3. Use the local recipe catalog (`gws_recipe_runner.py`) as command templates, then verify each against `gws --help` +4. `--page-all` emits one JSON line per page (NDJSON) for streaming large result sets +5. Use `--dry-run` to preview any request before executing it ### Performance -1. Use `--fields` to request only needed fields (reduces payload size) -2. Use `--limit` to cap results when browsing -3. Use `--page-all` only when you need complete datasets -4. Batch operations with recipes rather than individual API calls +1. Request only needed fields via the API's `fields` parameter in `--params` (reduces payload size) +2. Use `pageSize` in `--params` to cap results when browsing +3. Use `--page-all` only when you need complete datasets; tune with `--page-limit` / `--page-delay` +4. Prefer `+` helpers (single optimized calls) over hand-chained API calls 5. Cache frequently accessed data (e.g., label IDs, folder IDs) in variables --- diff --git a/engineering-team/google-workspace-cli/skills/google-workspace-cli/assets/persona-profiles.md b/engineering-team/google-workspace-cli/skills/google-workspace-cli/assets/persona-profiles.md index cec78c1b..33394b79 100644 --- a/engineering-team/google-workspace-cli/skills/google-workspace-cli/assets/persona-profiles.md +++ b/engineering-team/google-workspace-cli/skills/google-workspace-cli/assets/persona-profiles.md @@ -2,6 +2,8 @@ 10 role-based bundles that scope recipes and commands to your daily workflow. +> **These are command templates, not verified invocations.** The `gws` CLI ([github.com/googleworkspace/cli](https://github.com/googleworkspace/cli)) generates its command surface dynamically from Google's Discovery Service and is pre-v1.0. Before running any command below, verify its exact syntax with `gws --help`, `gws <service> --help`, or `gws schema <service>.<resource>.<method>`. Verified upstream patterns: discovery commands are `gws <service> <resource> <method> --params '{...}' --json '{...}'`; helpers are `+`-prefixed (`gws gmail +send`, `gws calendar +agenda`, `gws workflow +standup-report`). + --- ## 1. Executive Assistant @@ -9,11 +11,11 @@ **Description:** Managing schedules, emails, and communications for executives. **Top Commands:** -- `gws helpers morning-briefing` — Start the day with schedule + inbox overview -- `gws helpers find-time` — Find available slots for meetings -- `gws helpers meeting-prep --event-id <id>` — Prepare meeting agenda +- `python3 scripts/gws_recipe_runner.py --describe morning-briefing` — Start the day with schedule + inbox overview +- `gws calendar freebusy query ...` (verify: `gws schema calendar.freebusy.query`) — Find available slots for meetings +- `gws workflow +meeting-prep` — Prepare for the next meeting - `gws gmail users.messages send me` — Send emails on behalf -- `gws helpers eod-wrap` — End of day summary +- `python3 scripts/gws_recipe_runner.py --describe eod-wrap` — End of day summary **Recommended Recipes:** morning-briefing, today-schedule, find-time, send-email, reply-to-thread, meeting-prep, eod-wrap, quick-event, inbox-zero, standup-report @@ -31,11 +33,11 @@ **Description:** Tracking tasks, meetings, and project deliverables. **Top Commands:** -- `gws recipes standup-report` — Generate standup updates -- `gws helpers find-time` — Schedule sprint ceremonies +- `gws workflow +standup-report` — Generate standup updates +- `gws calendar freebusy query ...` (verify: `gws schema calendar.freebusy.query`) — Schedule sprint ceremonies - `gws tasks tasks insert` — Create and assign tasks - `gws sheets spreadsheets.values get` — Read project trackers -- `gws recipes project-status` — Aggregate project status +- `python3 scripts/gws_recipe_runner.py --describe project-status` — Aggregate project status **Recommended Recipes:** standup-report, create-event, find-time, task-create, task-progress, project-status, weekly-summary, share-folder, sheet-read, morning-briefing @@ -77,7 +79,7 @@ **Top Commands:** - `gws gmail users.messages send me` — Send proposals and follow-ups - `gws gmail users.messages list me --query` — Search client conversations -- `gws helpers find-time` — Schedule client meetings +- `gws calendar freebusy query ...` (verify: `gws schema calendar.freebusy.query`) — Schedule client meetings - `gws docs documents create` — Create proposals - `gws sheets spreadsheets.values update` — Update pipeline tracker diff --git a/engineering-team/google-workspace-cli/skills/google-workspace-cli/references/gws-command-reference.md b/engineering-team/google-workspace-cli/skills/google-workspace-cli/references/gws-command-reference.md index 597836e8..d64af578 100644 --- a/engineering-team/google-workspace-cli/skills/google-workspace-cli/references/gws-command-reference.md +++ b/engineering-team/google-workspace-cli/skills/google-workspace-cli/references/gws-command-reference.md @@ -1,37 +1,35 @@ # Google Workspace CLI Command Reference -Comprehensive reference for the `gws` CLI covering 18 services, 22 helper commands, global flags, and environment variables. +Working reference for the `gws` CLI ([github.com/googleworkspace/cli](https://github.com/googleworkspace/cli)) covering services, helper commands, global flags, and environment variables. + +> **Verify against your installed version.** `gws` builds its command surface dynamically from Google's Discovery Service and is pre-v1.0. Treat command syntax in this document as a template: confirm exact syntax with `gws --help`, `gws <service> --help`, or `gws schema <service>.<resource>.<method>` before scripting. Verified-from-upstream facts: install via `npm install -g @googleworkspace/cli`; discovery commands follow `gws <service> <resource> <method>` with `--params` (query/path params as JSON) and `--json` (request body); helpers are `+`-prefixed (e.g. `gws gmail +send`); all output is structured JSON. --- -## Global Flags +## Global Flags (verified) | Flag | Description | |------|-------------| -| `--json` | Output as JSON | -| `--format ndjson` | Output as newline-delimited JSON | -| `--dry-run` | Show what would be done without executing | -| `--limit <n>` | Maximum results to return | -| `--page-all` | Fetch all pages of results | -| `--fields <spec>` | Partial response field mask | -| `--quiet` | Suppress non-error output | -| `--verbose` | Verbose debug output | -| `--timeout <ms>` | Request timeout in milliseconds | +| `--params <json>` | Query/path parameters as JSON for discovery commands | +| `--json <json>` | Request body as JSON for discovery commands | +| `--dry-run` | Preview the request without executing | +| `--page-all` | Auto-paginate; one JSON line per page (NDJSON) | +| `--page-limit <n>` | Max pages to fetch | +| `--page-delay <ms>` | Delay between pages | +| `--sanitize` | Scan responses via a Model Armor template | --- -## Environment Variables +## Environment Variables (verified) -| Variable | Description | Default | -|----------|-------------|---------| -| `GWS_CLIENT_ID` | OAuth client ID | — | -| `GWS_CLIENT_SECRET` | OAuth client secret | — | -| `GWS_TOKEN_PATH` | Token storage location | `~/.config/gws/token.json` | -| `GWS_SERVICE_ACCOUNT_KEY` | Service account JSON key path | — | -| `GWS_DELEGATED_USER` | User to impersonate (service accounts) | — | -| `GWS_DEFAULT_FORMAT` | Default output format | `text` | -| `GWS_PAGINATION_LIMIT` | Default pagination limit | `100` | -| `GWS_LOG_LEVEL` | Logging level (debug/info/warn/error) | `warn` | +| Variable | Description | +|----------|-------------| +| `GOOGLE_WORKSPACE_CLI_CLIENT_ID` | OAuth client ID | +| `GOOGLE_WORKSPACE_CLI_CLIENT_SECRET` | OAuth client secret | +| `GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE` | Path to credentials JSON (from `gws auth export`) | +| `GOOGLE_WORKSPACE_CLI_TOKEN` | Pre-obtained OAuth token | +| `GOOGLE_WORKSPACE_CLI_CONFIG_DIR` | Override default config location | +| `GOOGLE_WORKSPACE_CLI_LOG` | Enable debug logging | --- @@ -230,32 +228,36 @@ gws admin activities list admin --json --- -## Helper Commands (22) +## Helper Commands (verified `+`-prefixed surface) -| Helper | Description | Example | -|--------|-------------|---------| -| `send` | Quick send email | `gws helpers send --to a@b.com --subject Hi --body Hello` | -| `reply` | Quick reply | `gws helpers reply --thread <id> --body Thanks` | -| `forward` | Quick forward | `gws helpers forward --message <id> --to a@b.com` | -| `upload` | Quick upload to Drive | `gws helpers upload file.pdf --folder <id>` | -| `download` | Quick download | `gws helpers download <fileId> --output file.pdf` | -| `share` | Quick share | `gws helpers share <fileId> --with a@b.com --role writer` | -| `quick-event` | Natural language event | `gws helpers quick-event "Lunch tomorrow at noon"` | -| `find-time` | Find free slots | `gws helpers find-time --attendees a,b --duration 60` | -| `standup-report` | Daily standup | `gws helpers standup-report` | -| `meeting-prep` | Prep for meeting | `gws helpers meeting-prep --event <id>` | -| `weekly-summary` | Week summary | `gws helpers weekly-summary` | -| `morning-briefing` | Morning overview | `gws helpers morning-briefing` | -| `eod-wrap` | End of day wrap | `gws helpers eod-wrap` | -| `inbox-zero` | Process inbox | `gws helpers inbox-zero` | -| `search` | Cross-service search | `gws helpers search "quarterly report"` | -| `create-task` | Quick task creation | `gws helpers create-task "Review PR" --due tomorrow` | -| `list-tasks` | Quick task listing | `gws helpers list-tasks` | -| `chat-send` | Quick chat message | `gws helpers chat-send --space <id> --text "Hello"` | -| `export-pdf` | Export as PDF | `gws helpers export-pdf <fileId> --output file.pdf` | -| `trash-old` | Trash old files | `gws helpers trash-old --older-than 365d` | -| `audit-sharing` | Audit file sharing | `gws helpers audit-sharing --folder <id>` | -| `backup-labels` | Backup Gmail labels | `gws helpers backup-labels --output labels.json` | +Helpers are prefixed with `+` so they never collide with Discovery-generated method names. Check each helper's flags with `gws <service> +<helper> --help`. + +| Service | Helper | Description | +|---------|--------|-------------| +| gmail | `+send` | Send an email (`gws gmail +send --to a@b.com --subject "Hi" --body "Hello"`) | +| gmail | `+reply` | Reply to a message (auto-threading) | +| gmail | `+reply-all` | Reply-all to a message | +| gmail | `+forward` | Forward a message | +| gmail | `+triage` | Unread inbox summary | +| gmail | `+watch` | Watch for new emails as NDJSON | +| sheets | `+append` | Append a row | +| sheets | `+read` | Read values | +| docs | `+write` | Append text | +| chat | `+send` | Send a space message | +| drive | `+upload` | Upload a file (`gws drive +upload ./report.pdf --name "Q1 Report"`) | +| calendar | `+insert` | Create an event | +| calendar | `+agenda` | Show upcoming events (timezone-aware) | +| script | `+push` | Replace all Apps Script files | +| workflow | `+standup-report` | Today's meetings + tasks | +| workflow | `+meeting-prep` | Next meeting prep | +| workflow | `+email-to-task` | Convert Gmail to Tasks | +| workflow | `+weekly-digest` | Weekly summary | +| workflow | `+file-announce` | Announce Drive file in Chat | +| events | `+subscribe` | Subscribe to Workspace events | +| events | `+renew` | Renew event subscriptions | +| modelarmor | `+sanitize-prompt` | Sanitize user prompt | +| modelarmor | `+sanitize-response` | Sanitize model response | +| modelarmor | `+create-template` | Create Model Armor template | --- @@ -267,47 +269,40 @@ gws schema gmail.users.messages.list gws schema drive.files.create gws schema calendar.events.insert -# List all available services -gws schema --list - -# List methods for a service -gws schema gmail --methods +# Discover available schema/introspection options for your version +gws schema --help ``` --- -## Authentication Commands +## Authentication Commands (verified) ```bash -gws auth setup # Interactive OAuth setup -gws auth setup --service-account # Service account setup -gws auth status # Check current auth -gws auth status --json # JSON auth details -gws auth refresh # Refresh expired token -gws auth revoke # Revoke current token -gws auth switch <profile> # Switch auth profile -gws auth profiles list # List saved profiles +gws auth setup # Interactive OAuth setup (uses gcloud if available) +gws auth login # Log in / re-consent +gws auth login -s drive,gmail,sheets # Request specific scopes +gws auth export --unmasked # Export credentials for headless reuse +gws auth --help # Discover further auth subcommands in your version ``` --- -## Recipe Commands +## Recipe Commands (local catalog, not built into gws) + +Recipes ship with this skill as a local catalog of command templates: ```bash -gws recipes list # List all 43 recipes -gws recipes list --category email # Filter by category -gws recipes describe <name> # Show recipe details -gws recipes run <name> # Execute a recipe -gws recipes run <name> --dry-run # Preview recipe commands +python3 scripts/gws_recipe_runner.py --list # List all 43 recipe templates +python3 scripts/gws_recipe_runner.py --search "email" # Search by keyword +python3 scripts/gws_recipe_runner.py --describe standup-report # Show recipe details +python3 scripts/gws_recipe_runner.py --run <name> --dry-run # Preview recipe commands ``` --- -## Persona Commands +## Persona Commands (local catalog, not built into gws) ```bash -gws persona list # List all 10 personas -gws persona select <name> # Activate a persona -gws persona show # Show active persona -gws persona recipes # Show recipes for active persona +python3 scripts/gws_recipe_runner.py --personas # List all 10 personas +python3 scripts/gws_recipe_runner.py --list --persona pm # Recipes for a persona ``` diff --git a/engineering-team/google-workspace-cli/skills/google-workspace-cli/references/recipes-cookbook.md b/engineering-team/google-workspace-cli/skills/google-workspace-cli/references/recipes-cookbook.md index b7c1d403..7b649ca0 100644 --- a/engineering-team/google-workspace-cli/skills/google-workspace-cli/references/recipes-cookbook.md +++ b/engineering-team/google-workspace-cli/skills/google-workspace-cli/references/recipes-cookbook.md @@ -1,6 +1,8 @@ # Google Workspace CLI Recipes Cookbook -Complete catalog of 43 built-in recipes organized by category, with command sequences and persona mapping. +Catalog of 43 recipe command templates (a local catalog shipped with this skill, not built into the gws CLI) organized by category, with command sequences and persona mapping. + +> **These are command templates, not verified invocations.** The `gws` CLI ([github.com/googleworkspace/cli](https://github.com/googleworkspace/cli)) generates its command surface dynamically from Google's Discovery Service and is pre-v1.0. Before running any command below, verify its exact syntax with `gws --help`, `gws <service> --help`, or `gws schema <service>.<resource>.<method>`. Verified upstream patterns: discovery commands are `gws <service> <resource> <method> --params '{...}' --json '{...}'`; helpers are `+`-prefixed (`gws gmail +send`, `gws calendar +agenda`, `gws workflow +standup-report`). --- @@ -137,14 +139,13 @@ gws calendar events insert primary \ ### quick-event Create event from natural language. ```bash -gws helpers quick-event "Lunch with Sarah tomorrow at noon" +gws calendar +insert ... # see: gws calendar +insert --help ``` ### find-time Find available time slots for a meeting. ```bash -gws helpers find-time --attendees "alice@co.com,bob@co.com" --duration 60 \ - --within "2026-03-15,2026-03-19" --json +gws calendar freebusy query --json '{"timeMin": "...", "timeMax": "...", "items": [{"id": "alice@co.com"}]}' # verify: gws schema calendar.freebusy.query ``` ### today-schedule @@ -158,7 +159,7 @@ gws calendar events list primary \ ### meeting-prep Prepare for an upcoming meeting. ```bash -gws recipes meeting-prep --event-id <EVENT_ID> +gws workflow +meeting-prep ``` **Output:** Agenda, attendee list, related Drive files, previous meeting notes. @@ -176,14 +177,14 @@ gws calendar events patch primary <EVENT_ID> \ ### standup-report Generate daily standup from calendar and tasks. ```bash -gws recipes standup-report --json +gws workflow +standup-report ``` **Output:** Yesterday's events, today's schedule, pending tasks, blockers. ### weekly-summary Summarize week's emails, events, and tasks. ```bash -gws recipes weekly-summary --json +gws workflow +weekly-digest ``` ### drive-activity @@ -304,26 +305,26 @@ gws admin activities list login --json ### morning-briefing Today's events + unread emails + pending tasks. ```bash -gws recipes morning-briefing --json +python3 scripts/gws_recipe_runner.py --run morning-briefing --dry-run # prints the command sequence ``` **Combines:** Calendar events, Gmail unread count, Tasks pending. ### eod-wrap End-of-day summary: completed, pending, tomorrow's schedule. ```bash -gws recipes eod-wrap --json +python3 scripts/gws_recipe_runner.py --run eod-wrap --dry-run ``` ### project-status Aggregate project status from Drive, Sheets, Tasks. ```bash -gws recipes project-status --project "Project Alpha" --json +python3 scripts/gws_recipe_runner.py --run project-status --dry-run ``` ### inbox-zero Process inbox to zero: label, archive, reply, or create task. ```bash -gws recipes inbox-zero --interactive +python3 scripts/gws_recipe_runner.py --run inbox-zero --dry-run ``` --- diff --git a/engineering-team/google-workspace-cli/skills/google-workspace-cli/references/troubleshooting.md b/engineering-team/google-workspace-cli/skills/google-workspace-cli/references/troubleshooting.md index 608991a9..f8123079 100644 --- a/engineering-team/google-workspace-cli/skills/google-workspace-cli/references/troubleshooting.md +++ b/engineering-team/google-workspace-cli/skills/google-workspace-cli/references/troubleshooting.md @@ -1,6 +1,8 @@ # Google Workspace CLI Troubleshooting -Common errors, fixes, and platform-specific guidance for the `gws` CLI. +Common errors, fixes, and platform-specific guidance for the `gws` CLI ([github.com/googleworkspace/cli](https://github.com/googleworkspace/cli)). + +> **Verify against your installed version.** `gws` is pre-v1.0 and generates its command surface dynamically from Google's Discovery Service. Confirm any `gws` command below with `gws --help` / `gws auth --help` before relying on it. --- @@ -13,11 +15,11 @@ Common errors, fixes, and platform-specific guidance for the `gws` CLI. **Fixes:** ```bash # Check if installed -npm list -g @anthropic/gws 2>/dev/null || echo "Not installed via npm" +npm list -g @googleworkspace/cli 2>/dev/null || echo "Not installed via npm" which gws || echo "Not on PATH" # Install via npm -npm install -g @anthropic/gws +npm install -g @googleworkspace/cli # If npm global bin not on PATH export PATH="$(npm config get prefix)/bin:$PATH" @@ -36,7 +38,7 @@ npm config set prefix '~/.npm-global' export PATH=~/.npm-global/bin:$PATH # Option 2: Use npx without installing -npx @anthropic/gws --version +npx @googleworkspace/cli --version ``` ### Cargo build failures @@ -49,7 +51,7 @@ npx @anthropic/gws --version rustup update stable # Clean build -cargo clean && cargo install gws-cli +cargo clean && cargo install --git https://github.com/googleworkspace/cli --locked ``` --- @@ -64,9 +66,9 @@ cargo clean && cargo install gws-cli **Fix:** ```bash -gws auth refresh -# If refresh fails: -gws auth setup # Re-authenticate +gws auth login # Re-authenticate (see: gws auth --help) +# If that fails, redo setup: +gws auth setup ``` ### Insufficient scopes @@ -75,11 +77,8 @@ gws auth setup # Re-authenticate **Fix:** ```bash -# Check current scopes -gws auth status --json | grep scopes - -# Re-auth with additional scopes -gws auth setup --scopes gmail,drive,calendar,sheets,tasks +# Re-auth requesting the scopes you need +gws auth login -s gmail,drive,calendar,sheets,tasks # Or list required scopes for a service python3 scripts/auth_setup_guide.py --scopes gmail,drive @@ -98,7 +97,7 @@ security unlock-keychain ~/Library/Keychains/login.keychain-db sudo apt install gnome-keyring # or libsecret # Fallback: Use file-based token storage -export GWS_TOKEN_PATH=~/.config/gws/token.json +export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/path/to/credentials.json # from: gws auth export --unmasked gws auth setup ``` @@ -110,13 +109,12 @@ gws auth setup 1. Verify domain-wide delegation is enabled on the service account 2. Verify client ID is authorized in Admin Console > Security > API Controls 3. Verify scopes match exactly (no trailing slashes) -4. Verify `GWS_DELEGATED_USER` is a valid admin account +4. Verify the delegated user is a valid admin account ```bash -# Debug -echo $GWS_SERVICE_ACCOUNT_KEY # Should point to valid JSON key file -echo $GWS_DELEGATED_USER # Should be admin@yourdomain.com -gws auth status --json # Check auth details +# Debug — confirm how your gws version configures service accounts first: +gws auth --help +echo $GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE # Should point to valid credentials JSON ``` --- @@ -218,7 +216,7 @@ gws drive files list --page-all --json gws drive files list --limit 1000 --json # Check if more pages exist (look for nextPageToken in output) -gws drive files list --limit 100 --json | grep nextPageToken +gws drive files list --params '{"pageSize": 100}' | grep nextPageToken ``` ### Empty response @@ -226,14 +224,14 @@ gws drive files list --limit 100 --json | grep nextPageToken **Problem:** Command returns empty or `{}`. ```bash -# Check auth -gws auth status +# Check auth (see: gws auth --help for your version's status command) +gws auth login -# Try with verbose output -gws drive files list --verbose --json +# Enable debug logging +GOOGLE_WORKSPACE_CLI_LOG=debug gws drive files list --params '{"pageSize": 1}' -# Check if the service is accessible -gws drive about get --json +# Check if the service is accessible (verify: gws schema drive.about.get) +gws drive about get --params '{"fields": "*"}' ``` --- @@ -248,7 +246,7 @@ gws drive about get --json # In Keychain Access.app, find "gws" entries and set "Allow all applications" # Or use file-based storage -export GWS_TOKEN_PATH=~/.config/gws/token.json +export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/path/to/credentials.json # from: gws auth export --unmasked ``` **Browser not opening for OAuth:** @@ -266,9 +264,9 @@ gws auth setup --no-browser gws auth setup --no-browser # Prints a URL — open on another machine, paste code back -# Or use service account (no browser needed) -export GWS_SERVICE_ACCOUNT_KEY=/path/to/key.json -export GWS_DELEGATED_USER=admin@domain.com +# Or export credentials from an interactive machine (documented headless flow) +gws auth export --unmasked > credentials.json +export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/path/to/credentials.json ``` **Missing keyring backend:** @@ -277,7 +275,7 @@ export GWS_DELEGATED_USER=admin@domain.com sudo apt install gnome-keyring libsecret-1-dev # Or use file-based storage -export GWS_TOKEN_PATH=~/.config/gws/token.json +export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/path/to/credentials.json # from: gws auth export --unmasked ``` ### Windows @@ -288,7 +286,7 @@ export GWS_TOKEN_PATH=~/.config/gws/token.json $env:PATH += ";$(npm config get prefix)\bin" # Or use npx -npx @anthropic/gws --version +npx @googleworkspace/cli --version ``` **PowerShell quoting:** diff --git a/engineering-team/google-workspace-cli/skills/google-workspace-cli/scripts/auth_setup_guide.py b/engineering-team/google-workspace-cli/skills/google-workspace-cli/scripts/auth_setup_guide.py index 7dc7eb5d..63264f3b 100644 --- a/engineering-team/google-workspace-cli/skills/google-workspace-cli/scripts/auth_setup_guide.py +++ b/engineering-team/google-workspace-cli/skills/google-workspace-cli/scripts/auth_setup_guide.py @@ -97,19 +97,18 @@ Step 4: Create OAuth Credentials Step 5: Configure gws CLI 1. Set environment variables: - export GWS_CLIENT_ID=<your-client-id> - export GWS_CLIENT_SECRET=<your-client-secret> + export GOOGLE_WORKSPACE_CLI_CLIENT_ID=<your-client-id> + export GOOGLE_WORKSPACE_CLI_CLIENT_SECRET=<your-client-secret> - 2. Or place the credentials JSON: - mv client_secret_*.json ~/.config/gws/credentials.json + 2. Or point the CLI at a credentials JSON file: + export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/path/to/credentials.json Step 6: Authenticate - gws auth setup - # Opens browser for consent, stores token in system keyring + gws auth setup # interactive setup (uses gcloud if available) + gws auth login -s gmail,drive,calendar # request only needed scopes -Step 7: Verify - gws auth status - gws gmail users getProfile me +Step 7: Verify (check exact syntax with: gws gmail --help) + gws gmail users getProfile --params '{"userId": "me"}' """ SERVICE_ACCOUNT_GUIDE = """ @@ -145,30 +144,34 @@ Step 5: Authorize in Google Admin - Scopes: (paste required scopes) 4. Authorize -Step 6: Configure gws CLI - export GWS_SERVICE_ACCOUNT_KEY=/path/to/service-account-key.json - export GWS_DELEGATED_USER=admin@yourdomain.com +Step 6: Configure gws CLI for headless use + NOTE: The documented headless flow for gws is to export credentials from an + interactive machine and reuse them (see: gws auth --help): + gws auth export --unmasked > credentials.json + export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/path/to/credentials.json + Or supply a pre-obtained OAuth token: + export GOOGLE_WORKSPACE_CLI_TOKEN=<token> + Verify service-account/domain-wide-delegation support against your installed + version (gws auth --help) before relying on it. -Step 7: Verify - gws auth status - gws gmail users getProfile me +Step 7: Verify (check exact syntax with: gws gmail --help) + gws gmail users getProfile --params '{"userId": "me"}' """ ENV_TEMPLATE = """# Google Workspace CLI Configuration # Copy to .env and fill in values # OAuth Credentials (for interactive auth) -GWS_CLIENT_ID= -GWS_CLIENT_SECRET= -GWS_TOKEN_PATH=~/.config/gws/token.json +GOOGLE_WORKSPACE_CLI_CLIENT_ID= +GOOGLE_WORKSPACE_CLI_CLIENT_SECRET= -# Service Account (for headless/CI auth) -# GWS_SERVICE_ACCOUNT_KEY=/path/to/key.json -# GWS_DELEGATED_USER=admin@yourdomain.com +# Headless/CI auth (export from an interactive machine: gws auth export --unmasked) +# GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/path/to/credentials.json +# GOOGLE_WORKSPACE_CLI_TOKEN= -# Defaults -GWS_DEFAULT_FORMAT=json -GWS_PAGINATION_LIMIT=100 +# Optional +# GOOGLE_WORKSPACE_CLI_CONFIG_DIR=~/.config/gws +# GOOGLE_WORKSPACE_CLI_LOG=debug """ @@ -215,7 +218,10 @@ def check_auth_status() -> dict: return json.loads(result.stdout) except json.JSONDecodeError: return {"status": "authenticated", "raw": result.stdout.strip()} - return {"status": "not_authenticated", "error": result.stderr.strip()[:200]} + return {"status": "unknown", + "note": "could not determine auth status ('gws auth status' may not exist " + "in your version; check 'gws auth --help')", + "error": result.stderr.strip()[:200]} except (FileNotFoundError, OSError): return {"status": "gws_not_found"} @@ -237,11 +243,11 @@ def validate_services(services: List[str]) -> ValidationReport: report.user = auth.get("user", auth.get("email", "unknown")) service_cmds = { - "gmail": ["gws", "gmail", "users", "getProfile", "me", "--json"], - "drive": ["gws", "drive", "files", "list", "--limit", "1", "--json"], - "calendar": ["gws", "calendar", "calendarList", "list", "--limit", "1", "--json"], - "sheets": ["gws", "sheets", "spreadsheets", "get", "test", "--json"], - "tasks": ["gws", "tasks", "tasklists", "list", "--limit", "1", "--json"], + "gmail": ["gws", "gmail", "users", "getProfile", "--params", '{"userId": "me"}'], + "drive": ["gws", "drive", "files", "list", "--params", '{"pageSize": 1}'], + "calendar": ["gws", "calendar", "calendarList", "list", "--params", '{"maxResults": 1}'], + "sheets": ["gws", "schema", "sheets.spreadsheets.get"], + "tasks": ["gws", "tasks", "tasklists", "list", "--params", '{"maxResults": 1}'], } for svc in services: @@ -350,7 +356,7 @@ Examples: status = check_auth_status() else: status = {"status": "gws_not_found", - "note": "Install gws first: cargo install gws-cli OR https://github.com/googleworkspace/cli/releases"} + "note": "Install gws first: npm install -g @googleworkspace/cli OR https://github.com/googleworkspace/cli/releases"} if args.json: print(json.dumps(status, indent=2)) else: diff --git a/engineering-team/google-workspace-cli/skills/google-workspace-cli/scripts/gws_doctor.py b/engineering-team/google-workspace-cli/skills/google-workspace-cli/scripts/gws_doctor.py index 184263a6..6a426899 100644 --- a/engineering-team/google-workspace-cli/skills/google-workspace-cli/scripts/gws_doctor.py +++ b/engineering-team/google-workspace-cli/skills/google-workspace-cli/scripts/gws_doctor.py @@ -54,13 +54,13 @@ DEMO_CHECKS = [ ] SERVICE_TEST_COMMANDS = { - "gmail": ["gws", "gmail", "users", "getProfile", "me", "--json"], - "drive": ["gws", "drive", "files", "list", "--limit", "1", "--json"], - "calendar": ["gws", "calendar", "calendarList", "list", "--limit", "1", "--json"], - "sheets": ["gws", "sheets", "spreadsheets", "get", "test", "--json"], - "tasks": ["gws", "tasks", "tasklists", "list", "--limit", "1", "--json"], - "chat": ["gws", "chat", "spaces", "list", "--limit", "1", "--json"], - "docs": ["gws", "docs", "documents", "get", "test", "--json"], + "gmail": ["gws", "gmail", "users", "getProfile", "--params", '{"userId": "me"}'], + "drive": ["gws", "drive", "files", "list", "--params", '{"pageSize": 1}'], + "calendar": ["gws", "calendar", "calendarList", "list", "--params", '{"maxResults": 1}'], + "sheets": ["gws", "schema", "sheets.spreadsheets.get"], + "tasks": ["gws", "tasks", "tasklists", "list", "--params", '{"maxResults": 1}'], + "chat": ["gws", "chat", "spaces", "list", "--params", '{"pageSize": 1}'], + "docs": ["gws", "schema", "docs.documents.get"], } @@ -70,7 +70,7 @@ def check_installation() -> Check: if path: return Check("gws-installed", "PASS", f"gws found at {path}") return Check("gws-installed", "FAIL", "gws not found on PATH", - "Install via: cargo install gws-cli OR download from https://github.com/googleworkspace/cli/releases") + "Install via: npm install -g @googleworkspace/cli OR download from https://github.com/googleworkspace/cli/releases") def check_version() -> Check: @@ -101,11 +101,13 @@ def check_auth() -> Check: return Check("auth-status", "PASS", f"Authenticated as {user}") except json.JSONDecodeError: return Check("auth-status", "PASS", "Authenticated (could not parse details)") - return Check("auth-status", "FAIL", "Not authenticated", - "Run 'gws auth setup' to configure authentication") + return Check("auth-status", "WARN", + "Could not confirm authentication ('gws auth status' may not exist " + "in your version; check 'gws auth --help')", + "Run 'gws auth setup' then 'gws auth login' to configure authentication") except (subprocess.TimeoutExpired, FileNotFoundError, OSError) as e: return Check("auth-status", "FAIL", f"Auth check failed: {e}", - "Run 'gws auth setup' to configure authentication") + "Run 'gws auth setup' then 'gws auth login' to configure authentication") def check_service(service: str) -> Check: diff --git a/engineering-team/google-workspace-cli/skills/google-workspace-cli/scripts/gws_recipe_runner.py b/engineering-team/google-workspace-cli/skills/google-workspace-cli/scripts/gws_recipe_runner.py index d28c94d0..89d3c0f7 100644 --- a/engineering-team/google-workspace-cli/skills/google-workspace-cli/scripts/gws_recipe_runner.py +++ b/engineering-team/google-workspace-cli/skills/google-workspace-cli/scripts/gws_recipe_runner.py @@ -1,9 +1,15 @@ #!/usr/bin/env python3 """ -Google Workspace CLI Recipe Runner — Catalog, search, and execute gws recipes. +Google Workspace CLI Recipe Runner — Catalog, search, and execute gws command templates. -Browse 43 built-in recipes, filter by persona, search by keyword, -and run with dry-run support. +Browse 43 recipe command templates (a LOCAL catalog shipped with this skill — +NOT built into the gws CLI), filter by persona, search by keyword, and run +with dry-run support. + +IMPORTANT: The gws CLI (github.com/googleworkspace/cli) generates its command +surface dynamically from Google's Discovery Service. Command strings in this +catalog are templates — verify each against `gws --help`, `gws <service> --help`, +or `gws schema <service>.<resource>.<method>` before relying on it. Usage: python3 gws_recipe_runner.py --list @@ -22,6 +28,10 @@ from dataclasses import dataclass, field, asdict from typing import List, Dict, Optional +TEMPLATE_NOTE = ("NOTE: Recipe commands are templates from this local catalog (not shipped by " + "the gws CLI). Verify each against 'gws --help' / 'gws schema' before use.") + + @dataclass class Recipe: name: str @@ -76,22 +86,22 @@ RECIPES: Dict[str, Recipe] = { "gws calendar events insert primary --summary {title} " "--start {start} --end {end} --attendees {attendees}" ]), - "quick-event": Recipe("quick-event", "Create event from natural language", "calendar", - ["calendar"], ["gws helpers quick-event {text}"]), - "find-time": Recipe("find-time", "Find available time slots for a meeting", "calendar", - ["calendar"], ["gws helpers find-time --attendees {attendees} --duration {minutes} --within {date_range}"]), + "quick-event": Recipe("quick-event", "Create an event via the calendar helper", "calendar", + ["calendar"], ["gws calendar +insert {details} # see: gws calendar +insert --help"]), + "find-time": Recipe("find-time", "Find available time slots via free/busy", "calendar", + ["calendar"], ["gws calendar freebusy query --json '<freebusy-request>' # verify: gws schema calendar.freebusy.query"]), "today-schedule": Recipe("today-schedule", "Show today's calendar events", "calendar", ["calendar"], ["gws calendar events list primary --timeMin {today_start} --timeMax {today_end} --json"]), "meeting-prep": Recipe("meeting-prep", "Prepare for an upcoming meeting (agenda + attendees)", "calendar", - ["calendar"], ["gws recipes meeting-prep --event-id {event_id}"]), + ["calendar"], ["gws workflow +meeting-prep"]), "reschedule": Recipe("reschedule", "Move an event to a new time", "calendar", ["calendar"], ["gws calendar events patch primary {event_id} --start {new_start} --end {new_end}"]), # Reporting (5) "standup-report": Recipe("standup-report", "Generate daily standup from calendar and tasks", "reporting", - ["calendar", "tasks"], ["gws recipes standup-report --json"]), + ["calendar", "tasks"], ["gws workflow +standup-report"]), "weekly-summary": Recipe("weekly-summary", "Summarize week's emails, events, and tasks", "reporting", - ["gmail", "calendar", "tasks"], ["gws recipes weekly-summary --json"]), + ["gmail", "calendar", "tasks"], ["gws workflow +weekly-digest"]), "drive-activity": Recipe("drive-activity", "Report on Drive file activity", "reporting", ["drive"], ["gws drive activities list --json"]), "email-stats": Recipe("email-stats", "Email volume statistics", "reporting", @@ -294,6 +304,7 @@ def describe_recipe(name: str, output_json: bool): print(f"\n Commands:") for i, cmd in enumerate(recipe.commands, 1): print(f" {i}. {cmd}") + print(f"\n {TEMPLATE_NOTE}") print(f"\n{'='*60}\n") @@ -308,10 +319,12 @@ def run_recipe(name: str, dry_run: bool): print(f"\n [DRY RUN] Recipe: {recipe.name}\n") for i, cmd in enumerate(recipe.commands, 1): print(f" {i}. {cmd}") + print(f"\n {TEMPLATE_NOTE}") print(f"\n (No commands executed)") return - print(f"\n Executing recipe: {recipe.name}\n") + print(f"\n Executing recipe: {recipe.name}") + print(f" {TEMPLATE_NOTE}\n") for cmd in recipe.commands: if cmd.startswith("#"): print(f" {cmd}") diff --git a/engineering-team/google-workspace-cli/skills/google-workspace-cli/scripts/output_analyzer.py b/engineering-team/google-workspace-cli/skills/google-workspace-cli/scripts/output_analyzer.py index 23b61548..9796c64b 100644 --- a/engineering-team/google-workspace-cli/skills/google-workspace-cli/scripts/output_analyzer.py +++ b/engineering-team/google-workspace-cli/skills/google-workspace-cli/scripts/output_analyzer.py @@ -6,9 +6,9 @@ Reads JSON arrays or NDJSON streams from stdin or file, applies filters, projections, sorting, grouping, and outputs in table/csv/json format. Usage: - gws drive files list --json | python3 output_analyzer.py --count - gws drive files list --json | python3 output_analyzer.py --filter "mimeType=application/pdf" - gws drive files list --json | python3 output_analyzer.py --select "name,size" --format table + gws drive files list | python3 output_analyzer.py --count + gws drive files list | python3 output_analyzer.py --filter "mimeType=application/pdf" + gws drive files list | python3 output_analyzer.py --select "name,size" --format table python3 output_analyzer.py --input results.json --group-by "mimeType" python3 output_analyzer.py --demo --select "name,mimeType,size" --format table """ @@ -231,11 +231,11 @@ def main(): formatter_class=argparse.RawDescriptionHelpFormatter, epilog=""" Examples: - gws drive files list --json | %(prog)s --count - gws drive files list --json | %(prog)s --filter "mimeType=pdf" --select "name,size" - gws drive files list --json | %(prog)s --group-by "mimeType" --format table - gws drive files list --json | %(prog)s --sort "size" --reverse --format table - gws drive files list --json | %(prog)s --stats "size" + gws drive files list | %(prog)s --count + gws drive files list | %(prog)s --filter "mimeType=pdf" --select "name,size" + gws drive files list | %(prog)s --group-by "mimeType" --format table + gws drive files list | %(prog)s --sort "size" --reverse --format table + gws drive files list | %(prog)s --stats "size" %(prog)s --input results.json --select "name,mimeType" --format csv %(prog)s --demo --select "name,mimeType,size" --format table """, diff --git a/engineering-team/google-workspace-cli/skills/google-workspace-cli/scripts/workspace_audit.py b/engineering-team/google-workspace-cli/skills/google-workspace-cli/scripts/workspace_audit.py index 7b9075f1..619d4b19 100644 --- a/engineering-team/google-workspace-cli/skills/google-workspace-cli/scripts/workspace_audit.py +++ b/engineering-team/google-workspace-cli/skills/google-workspace-cli/scripts/workspace_audit.py @@ -50,7 +50,7 @@ DEMO_FINDINGS = [ AuditFinding("drive", "Link sharing defaults", "FAIL", "Default link sharing is set to 'Anyone with the link'", "Sensitive files accessible without authentication", - "gws admin settings update drive --defaultLinkSharing restricted"), + "Restrict default link sharing: Admin Console > Apps > Google Workspace > Drive > Sharing settings"), AuditFinding("gmail", "Auto-forwarding", "PASS", "No auto-forwarding rules detected for admin accounts"), AuditFinding("gmail", "SPF record", "PASS", @@ -74,11 +74,11 @@ DEMO_FINDINGS = [ AuditFinding("oauth", "High-risk apps", "WARN", "3 apps have Drive full access scope", "Apps can read/modify all Drive files", - "Audit each app: gws admin tokens list --json | filter by scope"), + "Audit each app via the Directory API tokens resource (verify: gws schema admin.tokens.list)"), AuditFinding("admin", "Super admin count", "WARN", "4 super admin accounts detected (recommended: 2-3)", "Increased attack surface for privilege escalation", - "Reduce super admins: gws admin users list --query 'isAdmin=true' --json"), + "Reduce super admins: list them via the Directory API (verify: gws schema admin.users.list)"), AuditFinding("admin", "2-Step verification", "PASS", "2-Step verification enforced for all users"), AuditFinding("admin", "Password policy", "PASS", @@ -104,7 +104,7 @@ def audit_drive() -> List[AuditFinding]: findings = [] # Check sharing settings - output = run_gws_command(["gws", "drive", "about", "get", "--json"]) + output = run_gws_command(["gws", "drive", "about", "get", "--params", '{"fields": "*"}']) if output: try: data = json.loads(output) @@ -140,7 +140,8 @@ def audit_gmail() -> List[AuditFinding]: findings = [] # Check forwarding rules - output = run_gws_command(["gws", "gmail", "users.settings.forwardingAddresses", "list", "me", "--json"]) + output = run_gws_command(["gws", "gmail", "users", "settings", "forwardingAddresses", "list", + "--params", '{"userId": "me"}']) if output: try: data = json.loads(output) @@ -150,7 +151,7 @@ def audit_gmail() -> List[AuditFinding]: "gmail", "Auto-forwarding", "WARN", f"{len(addrs)} forwarding addresses configured", "Data exfiltration via email forwarding", - "Review: gws gmail users.settings.forwardingAddresses list me --json" + "Review forwarding addresses (verify: gws schema gmail.users.settings.forwardingAddresses.list)" )) else: findings.append(AuditFinding( @@ -172,7 +173,7 @@ def audit_calendar() -> List[AuditFinding]: """Audit Calendar sharing settings.""" findings = [] - output = run_gws_command(["gws", "calendar", "calendarList", "get", "primary", "--json"]) + output = run_gws_command(["gws", "calendar", "calendarList", "get", "--params", '{"calendarId": "primary"}']) if output: findings.append(AuditFinding( "calendar", "Primary calendar", "PASS", diff --git a/engineering-team/ms365-tenant-manager.zip b/engineering-team/ms365-tenant-manager.zip deleted file mode 100644 index f3eed7cc..00000000 Binary files a/engineering-team/ms365-tenant-manager.zip and /dev/null differ diff --git a/engineering-team/playwright-pro/skills/generate/SKILL.md b/engineering-team/playwright-pro/skills/generate/SKILL.md index f418a2a1..9cd90265 100644 --- a/engineering-team/playwright-pro/skills/generate/SKILL.md +++ b/engineering-team/playwright-pro/skills/generate/SKILL.md @@ -45,7 +45,7 @@ Check `templates/` in this plugin for matching patterns: | If testing... | Load template from | |---|---| -| Login/auth flow | `templates/auth/login.md` | +| Login/auth flow | `../pw/templates/auth/login.md` | | CRUD operations | `templates/crud/` | | Checkout/payment | `templates/checkout/` | | Search/filter UI | `templates/search/` | diff --git a/engineering-team/self-improving-agent/skills/extract/SKILL.md b/engineering-team/self-improving-agent/skills/extract/SKILL.md index 7836857b..fad8cdd5 100644 --- a/engineering-team/self-improving-agent/skills/extract/SKILL.md +++ b/engineering-team/self-improving-agent/skills/extract/SKILL.md @@ -1,6 +1,6 @@ --- name: "extract" -description: "Turn a proven pattern or debugging solution into a standalone reusable skill with SKILL.md, reference docs, and examples." +description: "Turn a proven pattern or debugging solution into a standalone reusable skill with SKILL.md, reference docs, and examples. Use when the user runs /si:extract or asks to package a recurring solution from memory into a skill." --- # /si:extract — Create Skills from Patterns diff --git a/engineering-team/self-improving-agent/skills/promote/SKILL.md b/engineering-team/self-improving-agent/skills/promote/SKILL.md index cbade7ab..73010943 100644 --- a/engineering-team/self-improving-agent/skills/promote/SKILL.md +++ b/engineering-team/self-improving-agent/skills/promote/SKILL.md @@ -1,6 +1,6 @@ --- name: "promote" -description: "Graduate a proven pattern from auto-memory (MEMORY.md) to CLAUDE.md or .claude/rules/ for permanent enforcement." +description: "Graduate a proven pattern from auto-memory (MEMORY.md) to CLAUDE.md or .claude/rules/ for permanent enforcement. Use when the user runs /si:promote or asks to make a learned behavior permanent." --- # /si:promote — Graduate Learnings to Rules diff --git a/engineering-team/self-improving-agent/skills/review/SKILL.md b/engineering-team/self-improving-agent/skills/review/SKILL.md index c4c9566f..14c518be 100644 --- a/engineering-team/self-improving-agent/skills/review/SKILL.md +++ b/engineering-team/self-improving-agent/skills/review/SKILL.md @@ -1,6 +1,6 @@ --- name: "review" -description: "Analyze auto-memory for promotion candidates, stale entries, consolidation opportunities, and health metrics." +description: "Analyze auto-memory for promotion candidates, stale entries, consolidation opportunities, and health metrics. Use when the user runs /si:review or asks what has been learned and what should be promoted or pruned." --- # /si:review — Analyze Auto-Memory diff --git a/engineering-team/self-improving-agent/skills/self-improving-agent/SKILL.md b/engineering-team/self-improving-agent/skills/self-improving-agent/SKILL.md index 4e4e171f..ceef709c 100644 --- a/engineering-team/self-improving-agent/skills/self-improving-agent/SKILL.md +++ b/engineering-team/self-improving-agent/skills/self-improving-agent/SKILL.md @@ -159,4 +159,4 @@ Monitors command output for errors. When detected, appends a structured entry to - [Claude Code Memory Docs](https://code.claude.com/docs/en/memory) - [pskoett/self-improving-agent](https://clawhub.ai/pskoett/self-improving-agent) — inspiration -- [playwright-pro](../playwright-pro/) — sister plugin in this repo +- [playwright-pro](engineering-team/playwright-pro/) — sister plugin in this repo diff --git a/engineering-team/self-improving-agent/skills/status/SKILL.md b/engineering-team/self-improving-agent/skills/status/SKILL.md index 359a6de6..e8ae8fb0 100644 --- a/engineering-team/self-improving-agent/skills/status/SKILL.md +++ b/engineering-team/self-improving-agent/skills/status/SKILL.md @@ -1,6 +1,6 @@ --- name: "status" -description: "Memory health dashboard showing line counts, topic files, capacity, stale entries, and recommendations." +description: "Memory health dashboard showing line counts, topic files, capacity, stale entries, and recommendations. Use when the user runs /si:status or asks how full or healthy the agent memory is." --- # /si:status — Memory Health Dashboard diff --git a/engineering-team/senior-architect.zip b/engineering-team/senior-architect.zip deleted file mode 100644 index 618105b8..00000000 Binary files a/engineering-team/senior-architect.zip and /dev/null differ diff --git a/engineering-team/senior-backend.zip b/engineering-team/senior-backend.zip deleted file mode 100644 index 859419a0..00000000 Binary files a/engineering-team/senior-backend.zip and /dev/null differ diff --git a/engineering-team/senior-computer-vision.zip b/engineering-team/senior-computer-vision.zip deleted file mode 100644 index 77d0d067..00000000 Binary files a/engineering-team/senior-computer-vision.zip and /dev/null differ diff --git a/engineering-team/senior-data-engineer.zip b/engineering-team/senior-data-engineer.zip deleted file mode 100644 index 348eb55a..00000000 Binary files a/engineering-team/senior-data-engineer.zip and /dev/null differ diff --git a/engineering-team/senior-data-scientist.zip b/engineering-team/senior-data-scientist.zip deleted file mode 100644 index 007014f2..00000000 Binary files a/engineering-team/senior-data-scientist.zip and /dev/null differ diff --git a/engineering-team/senior-devops.zip b/engineering-team/senior-devops.zip deleted file mode 100644 index d22e5d6d..00000000 Binary files a/engineering-team/senior-devops.zip and /dev/null differ diff --git a/engineering-team/senior-frontend.zip b/engineering-team/senior-frontend.zip deleted file mode 100644 index 58b6dae6..00000000 Binary files a/engineering-team/senior-frontend.zip and /dev/null differ diff --git a/engineering-team/senior-fullstack.zip b/engineering-team/senior-fullstack.zip deleted file mode 100644 index 36801ec4..00000000 Binary files a/engineering-team/senior-fullstack.zip and /dev/null differ diff --git a/engineering-team/senior-ml-engineer.zip b/engineering-team/senior-ml-engineer.zip deleted file mode 100644 index f4eacc07..00000000 Binary files a/engineering-team/senior-ml-engineer.zip and /dev/null differ diff --git a/engineering-team/senior-prompt-engineer.zip b/engineering-team/senior-prompt-engineer.zip deleted file mode 100644 index 235e925f..00000000 Binary files a/engineering-team/senior-prompt-engineer.zip and /dev/null differ diff --git a/engineering-team/senior-qa.zip b/engineering-team/senior-qa.zip deleted file mode 100644 index 69504fd0..00000000 Binary files a/engineering-team/senior-qa.zip and /dev/null differ diff --git a/engineering-team/senior-secops.zip b/engineering-team/senior-secops.zip deleted file mode 100644 index f1d5ca84..00000000 Binary files a/engineering-team/senior-secops.zip and /dev/null differ diff --git a/engineering-team/senior-security.zip b/engineering-team/senior-security.zip deleted file mode 100644 index 39ccc4da..00000000 Binary files a/engineering-team/senior-security.zip and /dev/null differ diff --git a/engineering-team/skills/email-template-builder/SKILL.md b/engineering-team/skills/email-template-builder/SKILL.md index 846b6289..98c22e73 100644 --- a/engineering-team/skills/email-template-builder/SKILL.md +++ b/engineering-team/skills/email-template-builder/SKILL.md @@ -361,8 +361,8 @@ export async function sendEmail(to: string, payload: EmailPayload) { // emails/i18n/en.ts export const en = { welcome: { - preview: (name: "string-welcome-to-myapp-name" - heading: (name: "string-welcome-to-myapp-name" + preview: (name: string) => `Welcome to MyApp, ${name}!`, + heading: (name: string) => `Welcome to MyApp, ${name}!`, body: (days: number) => `You've got ${days} days to explore everything.`, cta: "Confirm Email Address", }, @@ -371,8 +371,8 @@ export const en = { // emails/i18n/de.ts export const de = { welcome: { - preview: (name: "string-willkommen-bei-myapp-name" - heading: (name: "string-willkommen-bei-myapp-name" + preview: (name: string) => `Willkommen bei MyApp, ${name}!`, + heading: (name: string) => `Willkommen bei MyApp, ${name}!`, body: (days: number) => `Du hast ${days} Tage Zeit, alles zu erkunden.`, cta: "E-Mail-Adresse bestätigen", }, diff --git a/engineering-team/skills/engineering-skills/SKILL.md b/engineering-team/skills/engineering-skills/SKILL.md index 683afd46..4c0b1b25 100644 --- a/engineering-team/skills/engineering-skills/SKILL.md +++ b/engineering-team/skills/engineering-skills/SKILL.md @@ -1,6 +1,6 @@ --- name: "engineering-skills" -description: "23 engineering agent skills and plugins for Claude Code, Codex, Gemini CLI, Cursor, OpenClaw, and 6 more tools. Architecture, frontend, backend, QA, DevOps, security, AI/ML, data engineering, Playwright, Stripe, AWS, MS365. 30+ Python tools (stdlib-only)." +description: "Index of the engineering-team skills bundle for Claude Code, Codex, Gemini CLI, Cursor, OpenClaw, and 6 more tools. Architecture, frontend, backend, QA, DevOps, security, AI/ML, data engineering, Playwright, Stripe, AWS, MS365 (stdlib-only Python tools). Use when browsing or choosing among engineering-team role skills — load only the one specialist SKILL.md you need, never bulk-load the bundle." version: 2.9.0 author: Alireza Rezvani license: MIT @@ -20,13 +20,13 @@ agents: # Engineering Team Skills -23 production-ready engineering skills organized into core engineering, AI/ML/Data, and specialized tools. +32 production-ready engineering skills organized into core engineering, security, AI/ML/Data, and specialized tools. ## Quick Start ### Claude Code ``` -/read engineering-team/senior-fullstack/SKILL.md +/read engineering-team/skills/senior-fullstack/SKILL.md ``` ### Codex CLI @@ -86,6 +86,6 @@ No pip install needed. Scripts include embedded samples for demo mode. ## Rules -- Load only the specific skill SKILL.md you need — don't bulk-load all 23 +- Load only the specific skill SKILL.md you need — don't bulk-load all 32 - Use Python tools for analysis and scaffolding, not manual judgment - Check CLAUDE.md for tool usage examples and workflows diff --git a/engineering-team/skills/epic-design/SKILL.md b/engineering-team/skills/epic-design/SKILL.md index 5c1e5a7c..ae86d04b 100644 --- a/engineering-team/skills/epic-design/SKILL.md +++ b/engineering-team/skills/epic-design/SKILL.md @@ -253,7 +253,6 @@ These are MANDATORY in every output: | File | What's Inside | When to Read | |------|--------------|--------------| | `references/asset-pipeline.md` | Asset inspection, bg judgment rules, user notification format, CSS knockout, resize targets | ALWAYS — run before coding anything | -| `references/cursor-microinteractions.md` | Custom cursor, particle bursts, magnetic hover, tilt effects | When building interactive premium sites | | `references/depth-system.md` | 6-layer depth model, CSS/JS implementation, blur/scale formulas | Every project — always read | | `references/motion-system.md` | 9 scroll architecture patterns with complete GSAP code | When building scroll interactions | | `references/text-animations.md` | 13 text techniques with full implementation code | When animating any text | diff --git a/engineering-team/skills/incident-commander/SKILL.md b/engineering-team/skills/incident-commander/SKILL.md index c3a1c7a9..e58b58c7 100644 --- a/engineering-team/skills/incident-commander/SKILL.md +++ b/engineering-team/skills/incident-commander/SKILL.md @@ -13,7 +13,9 @@ description: "Comprehensive incident response framework from detection through r ## Overview -The Incident Commander skill provides a comprehensive incident response framework for managing technology incidents from detection through resolution and post-incident review. This skill implements battle-tested practices from SRE and DevOps teams at scale, providing structured tools for severity classification, timeline reconstruction, and thorough post-incident analysis. +Incident response framework for **availability/reliability incidents** (outages, degradations, failed deploys): severity classification, timeline reconstruction, and post-incident review. + +**This is NOT security incident triage.** For security events (ransomware, intrusion, data exfiltration, IOC analysis, NIST SP 800-61 forensics), route to `incident-response`. Both skills use SEV1-SEV4 labels; this one scores operational impact (users, revenue, SLA), while `incident-response` classifies attack types and forensic handling. ## Key Features @@ -380,10 +382,10 @@ Status page: {link} echo '{"description": "Users reporting 500 errors, database connections timing out", "affected_users": "80%", "business_impact": "high"}' | python scripts/incident_classifier.py # Reconstruct timeline from logs -python scripts/timeline_reconstructor.py --input assets/db_incident_events.json --output timeline.md +python scripts/timeline_reconstructor.py --input assets/sample_timeline_events.json --output timeline.md # Generate PIR after resolution -python scripts/pir_generator.py --incident assets/db_incident_data.json --timeline timeline.md --output pir.md +python scripts/pir_generator.py --incident assets/sample_incident_data.json --timeline timeline.md --output pir.md ``` ### Example 2: API Rate Limiting Incident @@ -393,10 +395,10 @@ python scripts/pir_generator.py --incident assets/db_incident_data.json --timeli echo "API rate limits causing customer API calls to fail" | python scripts/incident_classifier.py --format text # Build timeline from multiple sources -python scripts/timeline_reconstructor.py --input assets/api_incident_logs.json --detect-phases --gap-analysis +python scripts/timeline_reconstructor.py --input assets/simple_timeline_events.json --detect-phases --gap-analysis # Generate comprehensive PIR -python scripts/pir_generator.py --incident assets/api_incident_summary.json --rca-method fishbone --action-items +python scripts/pir_generator.py --incident assets/sample_incident_pir_data.json --rca-method fishbone --action-items ``` ## Best Practices @@ -467,10 +469,3 @@ python scripts/pir_generator.py --incident assets/api_incident_summary.json --rc - Deployment tracking systems - Feature flag platforms for quick rollbacks -## Conclusion - -The Incident Commander skill provides a comprehensive framework for managing incidents from detection through post-incident review. By implementing structured processes, clear communication templates, and thorough analysis tools, teams can improve their incident response capabilities and build more resilient systems. - -The key to successful incident management is preparation, practice, and continuous learning. Use this framework as a starting point, but adapt it to your organization's specific needs, culture, and technical environment. - -Remember: The goal isn't to prevent all incidents (which is impossible), but to detect them quickly, respond effectively, communicate clearly, and learn continuously. diff --git a/engineering-team/skills/incident-commander/scripts/incident_timeline_builder.py b/engineering-team/skills/incident-commander/scripts/incident_timeline_builder.py deleted file mode 100644 index ad49b5b7..00000000 --- a/engineering-team/skills/incident-commander/scripts/incident_timeline_builder.py +++ /dev/null @@ -1,742 +0,0 @@ -#!/usr/bin/env python3 -""" -Incident Timeline Builder - -Builds structured incident timelines with automatic phase detection, gap analysis, -communication template generation, and response metrics calculation. Produces -professional reports suitable for post-incident review and stakeholder briefing. - -Usage: - python incident_timeline_builder.py incident_data.json - python incident_timeline_builder.py incident_data.json --format json - python incident_timeline_builder.py incident_data.json --format markdown - cat incident_data.json | python incident_timeline_builder.py --format text -""" - -import argparse -import json -import sys -from datetime import datetime, timedelta -from typing import Any, Dict, List, Optional, Tuple - - -# --------------------------------------------------------------------------- -# Configuration Constants -# --------------------------------------------------------------------------- - -ISO_FORMAT = "%Y-%m-%dT%H:%M:%SZ" - -EVENT_TYPES = [ - "detection", "declaration", "escalation", "investigation", - "mitigation", "communication", "resolution", "action_item", -] - -SEVERITY_LEVELS = { - "SEV1": {"label": "Critical", "rank": 1}, - "SEV2": {"label": "Major", "rank": 2}, - "SEV3": {"label": "Minor", "rank": 3}, - "SEV4": {"label": "Low", "rank": 4}, -} - -PHASE_DEFINITIONS = [ - {"name": "Detection", "trigger_types": ["detection"], - "description": "Issue detected via monitoring, alerting, or user report."}, - {"name": "Triage", "trigger_types": ["declaration", "escalation"], - "description": "Incident declared, severity assessed, commander assigned."}, - {"name": "Investigation", "trigger_types": ["investigation"], - "description": "Root cause analysis and impact assessment underway."}, - {"name": "Mitigation", "trigger_types": ["mitigation"], - "description": "Active work to reduce or eliminate customer impact."}, - {"name": "Resolution", "trigger_types": ["resolution"], - "description": "Service restored to normal operating parameters."}, -] - -GAP_THRESHOLD_MINUTES = 15 - -DECISION_EVENT_TYPES = {"escalation", "mitigation", "declaration", "resolution"} - - -# --------------------------------------------------------------------------- -# Data Model Classes -# --------------------------------------------------------------------------- - -class IncidentEvent: - """Represents a single event in the incident timeline.""" - - def __init__(self, data: Dict[str, Any]): - self.timestamp_raw: str = data.get("timestamp", "") - self.timestamp: Optional[datetime] = _parse_timestamp(self.timestamp_raw) - self.type: str = data.get("type", "unknown").lower().strip() - self.actor: str = data.get("actor", "unknown") - self.description: str = data.get("description", "") - self.metadata: Dict[str, Any] = data.get("metadata", {}) - - def to_dict(self) -> Dict[str, Any]: - result: Dict[str, Any] = { - "timestamp": self.timestamp_raw, "type": self.type, - "actor": self.actor, "description": self.description, - } - if self.metadata: - result["metadata"] = self.metadata - return result - - @property - def is_decision_point(self) -> bool: - return self.type in DECISION_EVENT_TYPES - - -class IncidentPhase: - """Represents a detected phase of the incident lifecycle.""" - - def __init__(self, name: str, description: str): - self.name: str = name - self.description: str = description - self.start_time: Optional[datetime] = None - self.end_time: Optional[datetime] = None - self.events: List[IncidentEvent] = [] - - @property - def duration_minutes(self) -> Optional[float]: - if self.start_time and self.end_time: - return (self.end_time - self.start_time).total_seconds() / 60.0 - return None - - def to_dict(self) -> Dict[str, Any]: - dur = self.duration_minutes - return { - "name": self.name, "description": self.description, - "start_time": self.start_time.strftime(ISO_FORMAT) if self.start_time else None, - "end_time": self.end_time.strftime(ISO_FORMAT) if self.end_time else None, - "duration_minutes": round(dur, 1) if dur is not None else None, - "event_count": len(self.events), - } - - -class CommunicationTemplate: - """A generated communication message for a specific audience.""" - - def __init__(self, template_type: str, audience: str, subject: str, body: str): - self.template_type = template_type - self.audience = audience - self.subject = subject - self.body = body - - def to_dict(self) -> Dict[str, Any]: - return {"template_type": self.template_type, "audience": self.audience, - "subject": self.subject, "body": self.body} - - -class TimelineGap: - """Represents a gap in the timeline where no events were logged.""" - - def __init__(self, start: datetime, end: datetime, duration_minutes: float): - self.start = start - self.end = end - self.duration_minutes = duration_minutes - - def to_dict(self) -> Dict[str, Any]: - return {"start": self.start.strftime(ISO_FORMAT), - "end": self.end.strftime(ISO_FORMAT), - "duration_minutes": round(self.duration_minutes, 1)} - - -class TimelineAnalysis: - """Holds the complete analysis result for an incident timeline.""" - - def __init__(self): - self.incident_id: str = "" - self.incident_title: str = "" - self.severity: str = "" - self.status: str = "" - self.commander: str = "" - self.service: str = "" - self.affected_services: List[str] = [] - self.declared_at: Optional[datetime] = None - self.resolved_at: Optional[datetime] = None - self.events: List[IncidentEvent] = [] - self.phases: List[IncidentPhase] = [] - self.gaps: List[TimelineGap] = [] - self.decision_points: List[IncidentEvent] = [] - self.metrics: Dict[str, Any] = {} - self.communications: List[CommunicationTemplate] = [] - self.errors: List[str] = [] - - -# --------------------------------------------------------------------------- -# Timestamp Helpers -# --------------------------------------------------------------------------- - -def _parse_timestamp(raw: str) -> Optional[datetime]: - """Parse an ISO-8601 timestamp string into a datetime object.""" - if not raw: - return None - cleaned = raw.replace("Z", "+00:00") if raw.endswith("Z") else raw - try: - return datetime.fromisoformat(cleaned).replace(tzinfo=None) - except (ValueError, AttributeError): - pass - try: - return datetime.strptime(raw, ISO_FORMAT) - except ValueError: - return None - - -def _fmt_duration(minutes: Optional[float]) -> str: - """Format a duration in minutes as a human-readable string.""" - if minutes is None: - return "N/A" - if minutes < 1: - return f"{minutes * 60:.0f}s" - if minutes < 60: - return f"{minutes:.0f}m" - hours, remaining = int(minutes // 60), int(minutes % 60) - return f"{hours}h" if remaining == 0 else f"{hours}h {remaining}m" - - -def _fmt_ts(dt: Optional[datetime]) -> str: - """Format a datetime as HH:MM:SS for display.""" - return dt.strftime("%H:%M:%S") if dt else "??:??:??" - - -def _sev_label(sev: str) -> str: - """Return the human label for a severity code.""" - return SEVERITY_LEVELS.get(sev, {}).get("label", sev) - - -# --------------------------------------------------------------------------- -# Core Analysis Functions -# --------------------------------------------------------------------------- - -def parse_incident_data(data: Dict[str, Any]) -> TimelineAnalysis: - """Parse raw incident JSON into a TimelineAnalysis with populated fields.""" - a = TimelineAnalysis() - inc = data.get("incident", {}) - a.incident_id = inc.get("id", "UNKNOWN") - a.incident_title = inc.get("title", "Untitled Incident") - a.severity = inc.get("severity", "UNKNOWN").upper() - a.status = inc.get("status", "unknown").lower() - a.commander = inc.get("commander", "Unassigned") - a.service = inc.get("service", "unknown") - a.affected_services = inc.get("affected_services", []) - a.declared_at = _parse_timestamp(inc.get("declared_at", "")) - a.resolved_at = _parse_timestamp(inc.get("resolved_at", "")) - - raw_events = data.get("events", []) - if not raw_events: - a.errors.append("No events found in incident data.") - return a - - for raw in raw_events: - event = IncidentEvent(raw) - if event.timestamp is None: - a.errors.append(f"Skipping event with unparseable timestamp: {raw.get('timestamp', '')}") - continue - a.events.append(event) - - a.events.sort(key=lambda e: e.timestamp) # type: ignore[arg-type] - return a - - -def detect_phases(analysis: TimelineAnalysis) -> None: - """Detect incident lifecycle phases from the ordered event stream.""" - if not analysis.events: - return - - trigger_map: Dict[str, Dict[str, str]] = {} - for pdef in PHASE_DEFINITIONS: - for ttype in pdef["trigger_types"]: - trigger_map[ttype] = {"name": pdef["name"], "description": pdef["description"]} - - phase_by_name: Dict[str, IncidentPhase] = {} - phase_order: List[str] = [] - current: Optional[IncidentPhase] = None - - for event in analysis.events: - pinfo = trigger_map.get(event.type) - if pinfo and pinfo["name"] not in phase_by_name: - if current is not None: - current.end_time = event.timestamp - phase = IncidentPhase(pinfo["name"], pinfo["description"]) - phase.start_time = event.timestamp - phase_by_name[pinfo["name"]] = phase - phase_order.append(pinfo["name"]) - current = phase - if current is not None: - current.events.append(event) - - if current is not None: - current.end_time = analysis.resolved_at or analysis.events[-1].timestamp - - analysis.phases = [phase_by_name[n] for n in phase_order] - - -def detect_gaps(analysis: TimelineAnalysis) -> None: - """Identify gaps longer than GAP_THRESHOLD_MINUTES between consecutive events.""" - for i in range(len(analysis.events) - 1): - ts_a, ts_b = analysis.events[i].timestamp, analysis.events[i + 1].timestamp - if ts_a is None or ts_b is None: - continue - delta = (ts_b - ts_a).total_seconds() / 60.0 - if delta >= GAP_THRESHOLD_MINUTES: - analysis.gaps.append(TimelineGap(start=ts_a, end=ts_b, duration_minutes=delta)) - - -def identify_decision_points(analysis: TimelineAnalysis) -> None: - """Extract key decision-point events from the timeline.""" - analysis.decision_points = [e for e in analysis.events if e.is_decision_point] - - -def calculate_metrics(analysis: TimelineAnalysis) -> None: - """Calculate incident response metrics: MTTD, MTTR, phase durations.""" - m: Dict[str, Any] = {} - det = [e for e in analysis.events if e.type == "detection"] - first_det = det[0].timestamp if det else None - first_ts = analysis.events[0].timestamp if analysis.events else None - - # MTTD: first event to first detection. - if first_ts and first_det: - m["mttd_minutes"] = round((first_det - first_ts).total_seconds() / 60.0, 1) - else: - m["mttd_minutes"] = None - - # MTTR: detection to resolution. - if first_det and analysis.resolved_at: - m["mttr_minutes"] = round((analysis.resolved_at - first_det).total_seconds() / 60.0, 1) - else: - m["mttr_minutes"] = None - - # Total duration. - if analysis.declared_at and analysis.resolved_at: - m["total_duration_minutes"] = round( - (analysis.resolved_at - analysis.declared_at).total_seconds() / 60.0, 1) - else: - m["total_duration_minutes"] = None - - # Phase durations. - m["phase_durations"] = { - p.name: (round(p.duration_minutes, 1) if p.duration_minutes is not None else None) - for p in analysis.phases - } - - # Event counts by type. - tc: Dict[str, int] = {} - for e in analysis.events: - tc[e.type] = tc.get(e.type, 0) + 1 - m["event_counts_by_type"] = tc - - # Gap statistics. - m["gap_count"] = len(analysis.gaps) - if analysis.gaps: - gm = [g.duration_minutes for g in analysis.gaps] - m["longest_gap_minutes"] = round(max(gm), 1) - m["total_gap_minutes"] = round(sum(gm), 1) - else: - m["longest_gap_minutes"] = 0 - m["total_gap_minutes"] = 0 - - m["total_events"] = len(analysis.events) - m["decision_point_count"] = len(analysis.decision_points) - m["phase_count"] = len(analysis.phases) - analysis.metrics = m - - -# --------------------------------------------------------------------------- -# Communication Template Generation -# --------------------------------------------------------------------------- - -def generate_communications(analysis: TimelineAnalysis) -> None: - """Generate four communication templates based on incident data.""" - sev, sl = analysis.severity, _sev_label(analysis.severity) - title, svc = analysis.incident_title, analysis.service - affected = ", ".join(analysis.affected_services) or "none identified" - cmd, iid = analysis.commander, analysis.incident_id - decl = analysis.declared_at.strftime("%Y-%m-%d %H:%M UTC") if analysis.declared_at else "TBD" - resv = analysis.resolved_at.strftime("%Y-%m-%d %H:%M UTC") if analysis.resolved_at else "TBD" - dur = _fmt_duration(analysis.metrics.get("total_duration_minutes")) - resolved = analysis.status == "resolved" - - # 1 -- Initial stakeholder notification - analysis.communications.append(CommunicationTemplate( - "initial_notification", "internal", f"[{sev}] Incident Declared: {title}", - f"An incident has been declared for {svc}.\n\n" - f"Incident ID: {iid}\nSeverity: {sev} ({sl})\nCommander: {cmd}\n" - f"Declared at: {decl}\nAffected services: {affected}\n\n" - f"The incident team is actively investigating. Updates will follow.", - )) - - # 2 -- Status page update - if resolved: - sp_subj = f"[Resolved] {title}" - sp_body = (f"The incident affecting {svc} has been resolved.\n\n" - f"Duration: {dur}\nAll affected services ({affected}) are restored. " - f"A post-incident review will be published within 48 hours.") - else: - sp_subj = f"[Investigating] {title}" - sp_body = (f"We are investigating degraded performance in {svc}. " - f"Affected services: {affected}.\n\n" - f"Our team is working to identify the root cause. Updates every 30 minutes.") - analysis.communications.append(CommunicationTemplate( - "status_page", "external", sp_subj, sp_body)) - - # 3 -- Executive summary - phase_lines = "\n".join( - f" - {p.name}: {_fmt_duration(p.duration_minutes)}" for p in analysis.phases - ) or " No phase data available." - mttd = _fmt_duration(analysis.metrics.get("mttd_minutes")) - mttr = _fmt_duration(analysis.metrics.get("mttr_minutes")) - analysis.communications.append(CommunicationTemplate( - "executive_summary", "executive", f"Executive Summary: {iid} - {title}", - f"Incident: {iid} - {title}\nSeverity: {sev} ({sl})\n" - f"Service: {svc}\nCommander: {cmd}\nStatus: {analysis.status.capitalize()}\n" - f"Declared: {decl}\nResolved: {resv}\nDuration: {dur}\n\n" - f"Key Metrics:\n - MTTD: {mttd}\n - MTTR: {mttr}\n" - f" - Timeline Gaps: {analysis.metrics.get('gap_count', 0)}\n\n" - f"Phase Breakdown:\n{phase_lines}\n\nAffected Services: {affected}", - )) - - # 4 -- Customer notification - if resolved: - cust_body = (f"We experienced an issue affecting {svc} starting at {decl}.\n\n" - f"The issue was resolved at {resv} (duration: {dur}). " - f"We apologize for any inconvenience and are reviewing to prevent recurrence.") - else: - cust_body = (f"We are experiencing an issue affecting {svc} starting at {decl}.\n\n" - f"Our engineering team is actively working to resolve this. " - f"We will provide updates as the situation develops. We apologize for the inconvenience.") - analysis.communications.append(CommunicationTemplate( - "customer_notification", "external", f"Service Update: {title}", cust_body)) - - -# --------------------------------------------------------------------------- -# Main Analysis Orchestrator -# --------------------------------------------------------------------------- - -def build_timeline(data: Dict[str, Any]) -> TimelineAnalysis: - """Run the full timeline analysis pipeline on raw incident data.""" - analysis = parse_incident_data(data) - if analysis.errors and not analysis.events: - return analysis - detect_phases(analysis) - detect_gaps(analysis) - identify_decision_points(analysis) - calculate_metrics(analysis) - generate_communications(analysis) - return analysis - - -# --------------------------------------------------------------------------- -# Output Formatters -# --------------------------------------------------------------------------- - -def format_text_output(analysis: TimelineAnalysis) -> str: - """Format the analysis as a human-readable text report.""" - L: List[str] = [] - w = 64 - - L.append("=" * w) - L.append("INCIDENT TIMELINE REPORT") - L.append("=" * w) - L.append("") - - if analysis.errors: - for err in analysis.errors: - L.append(f" WARNING: {err}") - L.append("") - if not analysis.events: - return "\n".join(L) - - # Summary - L.append("INCIDENT SUMMARY") - L.append("-" * 32) - L.append(f" ID: {analysis.incident_id}") - L.append(f" Title: {analysis.incident_title}") - L.append(f" Severity: {analysis.severity}") - L.append(f" Status: {analysis.status.capitalize()}") - L.append(f" Commander: {analysis.commander}") - L.append(f" Service: {analysis.service}") - if analysis.affected_services: - L.append(f" Affected: {', '.join(analysis.affected_services)}") - L.append(f" Duration: {_fmt_duration(analysis.metrics.get('total_duration_minutes'))}") - L.append("") - - # Key metrics - L.append("KEY METRICS") - L.append("-" * 32) - L.append(f" MTTD (Mean Time to Detect): {_fmt_duration(analysis.metrics.get('mttd_minutes'))}") - L.append(f" MTTR (Mean Time to Resolve): {_fmt_duration(analysis.metrics.get('mttr_minutes'))}") - L.append(f" Total Events: {analysis.metrics.get('total_events', 0)}") - L.append(f" Decision Points: {analysis.metrics.get('decision_point_count', 0)}") - L.append(f" Timeline Gaps (>{GAP_THRESHOLD_MINUTES}m): {analysis.metrics.get('gap_count', 0)}") - L.append("") - - # Phases - L.append("INCIDENT PHASES") - L.append("-" * 32) - if analysis.phases: - for p in analysis.phases: - L.append(f" [{_fmt_ts(p.start_time)} - {_fmt_ts(p.end_time)}] {p.name} ({_fmt_duration(p.duration_minutes)})") - L.append(f" {p.description}") - L.append(f" Events: {len(p.events)}") - else: - L.append(" No phases detected.") - L.append("") - - # Chronological timeline - L.append("CHRONOLOGICAL TIMELINE") - L.append("-" * 32) - for e in analysis.events: - marker = "*" if e.is_decision_point else " " - L.append(f" {_fmt_ts(e.timestamp)} {marker} [{e.type.upper():13s}] {e.actor}") - L.append(f" {e.description}") - L.append("") - L.append(" (* = key decision point)") - L.append("") - - # Gap warnings - if analysis.gaps: - L.append("GAP ANALYSIS") - L.append("-" * 32) - for g in analysis.gaps: - L.append(f" WARNING: {_fmt_duration(g.duration_minutes)} gap between {_fmt_ts(g.start)} and {_fmt_ts(g.end)}") - L.append("") - - # Decision points - if analysis.decision_points: - L.append("KEY DECISION POINTS") - L.append("-" * 32) - for dp in analysis.decision_points: - L.append(f" {_fmt_ts(dp.timestamp)} [{dp.type.upper()}] {dp.description}") - L.append("") - - # Communications - if analysis.communications: - L.append("GENERATED COMMUNICATIONS") - L.append("-" * 32) - for c in analysis.communications: - L.append(f" Type: {c.template_type}") - L.append(f" Audience: {c.audience}") - L.append(f" Subject: {c.subject}") - L.append(" ---") - for bl in c.body.split("\n"): - L.append(f" {bl}") - L.append("") - - L.append("=" * w) - L.append("END OF REPORT") - L.append("=" * w) - return "\n".join(L) - - -def format_json_output(analysis: TimelineAnalysis) -> Dict[str, Any]: - """Format the analysis as a structured JSON-serializable dictionary.""" - return { - "incident": { - "id": analysis.incident_id, "title": analysis.incident_title, - "severity": analysis.severity, "status": analysis.status, - "commander": analysis.commander, "service": analysis.service, - "affected_services": analysis.affected_services, - "declared_at": analysis.declared_at.strftime(ISO_FORMAT) if analysis.declared_at else None, - "resolved_at": analysis.resolved_at.strftime(ISO_FORMAT) if analysis.resolved_at else None, - }, - "timeline": [e.to_dict() for e in analysis.events], - "phases": [p.to_dict() for p in analysis.phases], - "gaps": [g.to_dict() for g in analysis.gaps], - "decision_points": [e.to_dict() for e in analysis.decision_points], - "metrics": analysis.metrics, - "communications": [c.to_dict() for c in analysis.communications], - "errors": analysis.errors if analysis.errors else [], - } - - -def format_markdown_output(analysis: TimelineAnalysis) -> str: - """Format the analysis as a professional Markdown report.""" - L: List[str] = [] - - L.append(f"# Incident Timeline Report: {analysis.incident_id}") - L.append("") - - if analysis.errors: - L.append("> **Warnings:**") - for err in analysis.errors: - L.append(f"> - {err}") - L.append("") - if not analysis.events: - return "\n".join(L) - - # Summary table - L.append("## Incident Summary") - L.append("") - L.append("| Field | Value |") - L.append("|-------|-------|") - L.append(f"| **ID** | {analysis.incident_id} |") - L.append(f"| **Title** | {analysis.incident_title} |") - L.append(f"| **Severity** | {analysis.severity} ({_sev_label(analysis.severity)}) |") - L.append(f"| **Status** | {analysis.status.capitalize()} |") - L.append(f"| **Commander** | {analysis.commander} |") - L.append(f"| **Service** | {analysis.service} |") - if analysis.affected_services: - L.append(f"| **Affected Services** | {', '.join(analysis.affected_services)} |") - L.append(f"| **Duration** | {_fmt_duration(analysis.metrics.get('total_duration_minutes'))} |") - L.append("") - - # Key metrics - L.append("## Key Metrics") - L.append("") - L.append(f"- **MTTD (Mean Time to Detect):** {_fmt_duration(analysis.metrics.get('mttd_minutes'))}") - L.append(f"- **MTTR (Mean Time to Resolve):** {_fmt_duration(analysis.metrics.get('mttr_minutes'))}") - L.append(f"- **Total Events:** {analysis.metrics.get('total_events', 0)}") - L.append(f"- **Decision Points:** {analysis.metrics.get('decision_point_count', 0)}") - L.append(f"- **Timeline Gaps (>{GAP_THRESHOLD_MINUTES}m):** {analysis.metrics.get('gap_count', 0)}") - if analysis.metrics.get("longest_gap_minutes", 0) > 0: - L.append(f"- **Longest Gap:** {_fmt_duration(analysis.metrics.get('longest_gap_minutes'))}") - L.append("") - - # Phases table - L.append("## Incident Phases") - L.append("") - if analysis.phases: - L.append("| Phase | Start | End | Duration | Events |") - L.append("|-------|-------|-----|----------|--------|") - for p in analysis.phases: - L.append(f"| {p.name} | {_fmt_ts(p.start_time)} | {_fmt_ts(p.end_time)} | {_fmt_duration(p.duration_minutes)} | {len(p.events)} |") - L.append("") - # ASCII bar chart - max_dur = max((p.duration_minutes for p in analysis.phases if p.duration_minutes), default=0) - if max_dur and max_dur > 0: - L.append("### Phase Duration Distribution") - L.append("") - L.append("```") - for p in analysis.phases: - d = p.duration_minutes or 0 - bar = "#" * int((d / max_dur) * 40) - L.append(f" {p.name:15s} |{bar} {_fmt_duration(d)}") - L.append("```") - L.append("") - else: - L.append("No phases detected.") - L.append("") - - # Chronological timeline - L.append("## Chronological Timeline") - L.append("") - for e in analysis.events: - dm = " **[KEY DECISION]**" if e.is_decision_point else "" - L.append(f"- `{_fmt_ts(e.timestamp)}` **{e.type.upper()}** ({e.actor}){dm}") - L.append(f" - {e.description}") - L.append("") - - # Gap analysis - if analysis.gaps: - L.append("## Gap Analysis") - L.append("") - L.append(f"> {len(analysis.gaps)} gap(s) of >{GAP_THRESHOLD_MINUTES} minutes detected. " - f"These may represent blind spots where important activity was not recorded.") - L.append("") - for g in analysis.gaps: - L.append(f"- **{_fmt_duration(g.duration_minutes)}** gap from `{_fmt_ts(g.start)}` to `{_fmt_ts(g.end)}`") - L.append("") - - # Decision points - if analysis.decision_points: - L.append("## Key Decision Points") - L.append("") - for dp in analysis.decision_points: - L.append(f"1. `{_fmt_ts(dp.timestamp)}` **{dp.type.upper()}** - {dp.description}") - L.append("") - - # Communications - if analysis.communications: - L.append("## Generated Communications") - L.append("") - for c in analysis.communications: - L.append(f"### {c.template_type.replace('_', ' ').title()} ({c.audience})") - L.append("") - L.append(f"**Subject:** {c.subject}") - L.append("") - for bl in c.body.split("\n"): - L.append(bl) - L.append("") - L.append("---") - L.append("") - - # Event type breakdown - tc = analysis.metrics.get("event_counts_by_type", {}) - if tc: - L.append("## Event Type Breakdown") - L.append("") - L.append("| Type | Count |") - L.append("|------|-------|") - for etype, count in sorted(tc.items(), key=lambda x: -x[1]): - L.append(f"| {etype} | {count} |") - L.append("") - - L.append("---") - L.append(f"*Report generated for incident {analysis.incident_id}. All timestamps in UTC.*") - return "\n".join(L) - - -# --------------------------------------------------------------------------- -# CLI Interface -# --------------------------------------------------------------------------- - -def main() -> int: - """Main CLI entry point.""" - parser = argparse.ArgumentParser( - description="Build structured incident timelines with phase detection and communication templates." - ) - parser.add_argument( - "data_file", nargs="?", default=None, - help="JSON file with incident data (reads stdin if omitted)", - ) - parser.add_argument( - "--format", choices=["text", "json", "markdown"], default="text", - help="Output format (default: text)", - ) - args = parser.parse_args() - - try: - if args.data_file: - try: - with open(args.data_file, "r") as f: - raw_data = json.load(f) - except FileNotFoundError: - print(f"Error: File '{args.data_file}' not found.", file=sys.stderr) - return 1 - except json.JSONDecodeError as e: - print(f"Error: Invalid JSON in '{args.data_file}': {e}", file=sys.stderr) - return 1 - else: - if sys.stdin.isatty(): - print("Error: No input file specified and stdin is a terminal. " - "Provide a file argument or pipe JSON to stdin.", file=sys.stderr) - return 1 - try: - raw_data = json.load(sys.stdin) - except json.JSONDecodeError as e: - print(f"Error: Invalid JSON on stdin: {e}", file=sys.stderr) - return 1 - - if not isinstance(raw_data, dict): - print("Error: Input must be a JSON object.", file=sys.stderr) - return 1 - if "incident" not in raw_data and "events" not in raw_data: - print("Error: Input must contain at least 'incident' or 'events' keys.", file=sys.stderr) - return 1 - - analysis = build_timeline(raw_data) - - if args.format == "json": - print(json.dumps(format_json_output(analysis), indent=2)) - elif args.format == "markdown": - print(format_markdown_output(analysis)) - else: - print(format_text_output(analysis)) - return 0 - - except Exception as e: - print(f"Error: {e}", file=sys.stderr) - return 1 - - -if __name__ == "__main__": - sys.exit(main()) diff --git a/engineering-team/skills/incident-commander/scripts/postmortem_generator.py b/engineering-team/skills/incident-commander/scripts/postmortem_generator.py deleted file mode 100644 index 868f425f..00000000 --- a/engineering-team/skills/incident-commander/scripts/postmortem_generator.py +++ /dev/null @@ -1,804 +0,0 @@ -#!/usr/bin/env python3 -""" -Postmortem Generator - Generate structured postmortem reports with 5-Whys analysis. - -Produces comprehensive incident postmortem documents from structured JSON input, -including root cause analysis, contributing factor classification, action item -validation, MTTD/MTTR metrics, and customer impact summaries. - -Usage: - python postmortem_generator.py incident_data.json - python postmortem_generator.py incident_data.json --format markdown - python postmortem_generator.py incident_data.json --format json - cat incident_data.json | python postmortem_generator.py - -Input: - JSON object with keys: incident, timeline, resolution, action_items, participants. - See SKILL.md for the full input schema. -""" - -import argparse -import json -import sys -from datetime import datetime, timezone -from typing import Any, Dict, List, Optional, Tuple - - -# ---------- Constants and Configuration ---------- - -VERSION = "1.0.0" -SEVERITY_ORDER = {"SEV0": 0, "SEV1": 1, "SEV2": 2, "SEV3": 3, "SEV4": 4} -FACTOR_CATEGORIES = ("process", "tooling", "human", "environment", "external") -ACTION_TYPES = ("detection", "prevention", "mitigation", "process") -PRIORITY_ORDER = {"P0": 0, "P1": 1, "P2": 2, "P3": 3, "P4": 4} -POSTMORTEM_TARGET_HOURS = 72 - -# Industry benchmarks for incident response (minutes, except postmortem) -BENCHMARKS = { - "SEV0": {"mttd": 5, "mttr": 60, "mitigate": 30, "declare": 5}, - "SEV1": {"mttd": 10, "mttr": 120, "mitigate": 60, "declare": 10}, - "SEV2": {"mttd": 30, "mttr": 480, "mitigate": 120, "declare": 30}, - "SEV3": {"mttd": 60, "mttr": 1440, "mitigate": 240, "declare": 60}, - "SEV4": {"mttd": 120, "mttr": 2880, "mitigate": 480, "declare": 120}, -} - -CAT_TO_ACTION = {"process": "process", "tooling": "detection", "human": "prevention", - "environment": "mitigation", "external": "prevention"} -CAT_WEIGHT = {"process": 1.0, "tooling": 0.9, "human": 0.8, "environment": 0.7, "external": 0.6} - -# Keywords used to classify contributing factors into categories -FACTOR_KEYWORDS = { - "process": ["process", "procedure", "workflow", "review", "approval", "checklist", - "runbook", "documentation", "policy", "standard", "protocol", "canary", - "deployment", "rollback", "change management"], - "tooling": ["tool", "monitor", "alert", "threshold", "automation", "test", "pipeline", - "ci/cd", "observability", "dashboard", "logging", "infrastructure", - "configuration", "config"], - "human": ["training", "knowledge", "experience", "communication", "handoff", "fatigue", - "oversight", "mistake", "error", "misunderstand", "assumption", "awareness"], - "environment": ["load", "traffic", "scale", "capacity", "resource", "network", "hardware", - "region", "latency", "timeout", "connection", "performance", "spike"], - "external": ["vendor", "third-party", "upstream", "downstream", "provider", "api", - "dependency", "partner", "dns", "cdn", "certificate"], -} - -# 5-Whys templates per category (each list is 5 why->answer steps) -WHY_TEMPLATES = { - "process": [ - "Why did this process gap exist? -> The existing process did not account for this scenario.", - "Why was the scenario not accounted for? -> It was not identified during the last process review.", - "Why was the process review incomplete? -> Reviews focus on known failure modes, not emerging risks.", - "Why are emerging risks not surfaced? -> No systematic mechanism to capture lessons from near-misses.", - "Why is there no near-miss capture mechanism? -> Incident learning is ad-hoc rather than systematic."], - "tooling": [ - "Why did the tooling fail to catch this? -> The relevant metric was not monitored or the threshold was misconfigured.", - "Why was the threshold misconfigured? -> It was set during initial deployment and never revisited.", - "Why was it never revisited? -> There is no scheduled review of monitoring configurations.", - "Why is there no scheduled review? -> Monitoring ownership is diffuse across teams.", - "Why is ownership diffuse? -> No clear operational runbook assigns monitoring review responsibilities."], - "human": [ - "Why did the human factor contribute? -> The individual lacked context needed to prevent the issue.", - "Why was context lacking? -> Knowledge was siloed and not documented accessibly.", - "Why was knowledge siloed? -> No structured onboarding or knowledge-sharing process for this area.", - "Why is there no knowledge-sharing process? -> Team capacity has been focused on feature delivery.", - "Why is capacity skewed toward features? -> Operational excellence is not weighted equally in planning."], - "environment": [ - "Why did the environment cause this failure? -> System capacity was insufficient for the load pattern.", - "Why was capacity insufficient? -> Load projections did not account for this traffic pattern.", - "Why were projections inaccurate? -> Load testing does not replicate production-scale variability.", - "Why doesn't load testing replicate production? -> Test environments lack realistic traffic generators.", - "Why are traffic generators missing? -> Investment in production-like test infrastructure was deferred."], - "external": [ - "Why did the external factor cause an incident? -> The system had a hard dependency with no fallback.", - "Why was there no fallback? -> The integration was assumed to be highly available.", - "Why was high availability assumed? -> SLA review of the external dependency was not performed.", - "Why was SLA review skipped? -> No standard checklist for evaluating third-party dependencies.", - "Why is there no evaluation checklist? -> Vendor management practices are informal and undocumented."], -} - -THEME_RECS = { - "process": ["Establish a quarterly process review cadence covering change management and deployment procedures.", - "Implement a near-miss tracking system to surface latent risks before they become incidents.", - "Create pre-deployment checklists that require sign-off from the service owner."], - "tooling": ["Schedule quarterly reviews of alerting thresholds and monitoring coverage.", - "Assign explicit monitoring ownership per service in operational runbooks.", - "Invest in synthetic monitoring and canary analysis for critical paths."], - "human": ["Build structured onboarding that covers incident-prone areas and past postmortems.", - "Implement blameless knowledge-sharing sessions after each incident.", - "Balance operational excellence work alongside feature delivery in sprint planning."], - "environment": ["Conduct periodic capacity planning reviews using production traffic replays.", - "Invest in production-like load-testing infrastructure with realistic traffic profiles.", - "Implement auto-scaling policies with validated upper-bound thresholds."], - "external": ["Perform formal SLA reviews for all third-party dependencies annually.", - "Implement circuit breakers and fallbacks for external service integrations.", - "Maintain a dependency registry with risk ratings and contingency plans."], -} - -MISSING_ACTION_TEMPLATES = { - "process": "Create or update runbook/checklist to prevent recurrence of this process gap", - "detection": "Add monitoring and alerting to detect this class of issue earlier", - "mitigation": "Implement auto-scaling or circuit-breaker to reduce blast radius", - "prevention": "Add automated safeguards (canary deploy, load test gate) to prevent recurrence", -} - - -# ---------- Data Model Classes ---------- - -class IncidentData: - """Parsed incident metadata.""" - def __init__(self, data: Dict[str, Any]) -> None: - self.id: str = data.get("id", "UNKNOWN") - self.title: str = data.get("title", "Untitled Incident") - self.severity: str = data.get("severity", "SEV3").upper() - self.commander: str = data.get("commander", "Unassigned") - self.service: str = data.get("service", "unknown-service") - self.affected_services: List[str] = data.get("affected_services", []) - - def to_dict(self) -> Dict[str, Any]: - return {"id": self.id, "title": self.title, "severity": self.severity, - "commander": self.commander, "service": self.service, - "affected_services": self.affected_services} - - -class TimelineMetrics: - """MTTD, MTTR, and other timing metrics computed from raw timestamps.""" - def __init__(self, timeline: Dict[str, str], severity: str) -> None: - self.severity = severity - self.issue_started = self._parse(timeline.get("issue_started")) - self.detected_at = self._parse(timeline.get("detected_at")) - self.declared_at = self._parse(timeline.get("declared_at")) - self.mitigated_at = self._parse(timeline.get("mitigated_at")) - self.resolved_at = self._parse(timeline.get("resolved_at")) - self.postmortem_at = self._parse(timeline.get("postmortem_at")) - - @staticmethod - def _parse(ts: Optional[str]) -> Optional[datetime]: - if ts is None: - return None - for fmt in ("%Y-%m-%dT%H:%M:%SZ", "%Y-%m-%dT%H:%M:%S%z", "%Y-%m-%dT%H:%M:%S"): - try: - dt = datetime.strptime(ts, fmt) - return dt if dt.tzinfo else dt.replace(tzinfo=timezone.utc) - except ValueError: - continue - return None - - def _delta_min(self, start: Optional[datetime], end: Optional[datetime]) -> Optional[float]: - if start is None or end is None: - return None - return round((end - start).total_seconds() / 60.0, 1) - - @property - def mttd(self) -> Optional[float]: - return self._delta_min(self.issue_started, self.detected_at) - - @property - def mttr(self) -> Optional[float]: - return self._delta_min(self.detected_at, self.resolved_at) - - @property - def time_to_mitigate(self) -> Optional[float]: - return self._delta_min(self.detected_at, self.mitigated_at) - - @property - def time_to_declare(self) -> Optional[float]: - return self._delta_min(self.detected_at, self.declared_at) - - @property - def postmortem_timeliness_hours(self) -> Optional[float]: - m = self._delta_min(self.resolved_at, self.postmortem_at) - return round(m / 60.0, 1) if m is not None else None - - @property - def postmortem_on_time(self) -> Optional[bool]: - h = self.postmortem_timeliness_hours - return h <= POSTMORTEM_TARGET_HOURS if h is not None else None - - def benchmark_comparison(self) -> Dict[str, Dict[str, Any]]: - bench = BENCHMARKS.get(self.severity, BENCHMARKS["SEV3"]) - results: Dict[str, Dict[str, Any]] = {} - for name, actual, target in [("mttd", self.mttd, bench["mttd"]), - ("mttr", self.mttr, bench["mttr"]), - ("time_to_mitigate", self.time_to_mitigate, bench["mitigate"]), - ("time_to_declare", self.time_to_declare, bench["declare"])]: - if actual is not None: - results[name] = {"actual_minutes": actual, "benchmark_minutes": target, - "met_benchmark": actual <= target, - "delta_minutes": round(actual - target, 1)} - h = self.postmortem_timeliness_hours - if h is not None: - results["postmortem_timeliness"] = { - "actual_hours": h, "target_hours": POSTMORTEM_TARGET_HOURS, - "met_target": self.postmortem_on_time, "delta_hours": round(h - POSTMORTEM_TARGET_HOURS, 1)} - return results - - def to_dict(self) -> Dict[str, Any]: - return {"mttd_minutes": self.mttd, "mttr_minutes": self.mttr, - "time_to_mitigate_minutes": self.time_to_mitigate, - "time_to_declare_minutes": self.time_to_declare, - "postmortem_timeliness_hours": self.postmortem_timeliness_hours, - "postmortem_on_time": self.postmortem_on_time, - "benchmarks": self.benchmark_comparison()} - - -class ContributingFactor: - """A classified contributing factor with weight and action-type mapping.""" - def __init__(self, description: str, index: int) -> None: - self.description = description - self.index = index - self.category = self._classify() - self.weight = round(max(1.0 - index * 0.15, 0.3) * CAT_WEIGHT.get(self.category, 0.8), 2) - self.mapped_action_type = CAT_TO_ACTION.get(self.category, "process") - - def _classify(self) -> str: - lower = self.description.lower() - scores = {cat: sum(1 for kw in kws if kw in lower) for cat, kws in FACTOR_KEYWORDS.items()} - best = max(scores, key=lambda k: scores[k]) - return best if scores[best] > 0 else "process" - - def to_dict(self) -> Dict[str, Any]: - return {"description": self.description, "category": self.category, - "weight": self.weight, "mapped_action_type": self.mapped_action_type} - - -class FiveWhysAnalysis: - """Structured 5-Whys chain for a contributing factor.""" - def __init__(self, factor: ContributingFactor) -> None: - self.factor = factor - self.systemic_theme: str = factor.category - self.chain: List[str] = [f"Why? {factor.description}"] + \ - WHY_TEMPLATES.get(factor.category, WHY_TEMPLATES["process"]) - - def to_dict(self) -> Dict[str, Any]: - return {"factor": self.factor.description, "category": self.factor.category, - "chain": self.chain, "systemic_theme": self.systemic_theme} - - -class ActionItem: - """Parsed and validated action item.""" - def __init__(self, data: Dict[str, Any]) -> None: - self.title: str = data.get("title", "") - self.owner: str = data.get("owner", "") - self.priority: str = data.get("priority", "P3") - self.deadline: str = data.get("deadline", "") - self.type: str = data.get("type", "process") - self.status: str = data.get("status", "open") - self.validation_issues: List[str] = [] - self.quality_score: int = 0 - self._validate() - - def _validate(self) -> None: - self.validation_issues = [] - if not self.title: - self.validation_issues.append("Missing title") - if not self.owner: - self.validation_issues.append("Missing owner") - if not self.deadline: - self.validation_issues.append("Missing deadline") - if self.priority not in PRIORITY_ORDER: - self.validation_issues.append(f"Invalid priority: {self.priority}") - if self.type not in ACTION_TYPES: - self.validation_issues.append(f"Invalid type: {self.type}") - self.quality_score = self._score_quality() - - def _score_quality(self) -> int: - """Score 0-100: specific, measurable, achievable.""" - s = 0 - if len(self.title) > 10: s += 20 - if self.owner: s += 20 - if self.deadline: s += 20 - if self.priority in PRIORITY_ORDER: s += 10 - if self.type in ACTION_TYPES: s += 10 - if any(kw in self.title.lower() for kw in ["%", "threshold", "within", "before", - "after", "less than", "greater than"]): - s += 10 - if len(self.title.split()) >= 5: s += 10 - return min(s, 100) - - @property - def is_valid(self) -> bool: - return len(self.validation_issues) == 0 - - @property - def is_past_deadline(self) -> bool: - if not self.deadline or self.status != "open": - return False - try: - dl = datetime.strptime(self.deadline, "%Y-%m-%d").replace(tzinfo=timezone.utc) - return datetime.now(timezone.utc) > dl - except ValueError: - return False - - def to_dict(self) -> Dict[str, Any]: - return {"title": self.title, "owner": self.owner, "priority": self.priority, - "deadline": self.deadline, "type": self.type, "status": self.status, - "is_valid": self.is_valid, "validation_issues": self.validation_issues, - "quality_score": self.quality_score, "is_past_deadline": self.is_past_deadline} - - -class PostmortemReport: - """Complete postmortem document assembled from all analysis components.""" - - def __init__(self, raw: Dict[str, Any]) -> None: - self.raw = raw - self.incident = IncidentData(raw.get("incident", {})) - self.timeline = TimelineMetrics(raw.get("timeline", {}), self.incident.severity) - self.resolution: Dict[str, Any] = raw.get("resolution", {}) - self.participants: List[Dict[str, str]] = raw.get("participants", []) - # Derived analysis - self.contributing_factors = [ContributingFactor(f, i) - for i, f in enumerate(self.resolution.get("contributing_factors", []))] - self.five_whys = [FiveWhysAnalysis(f) for f in self.contributing_factors] - self.action_items = [ActionItem(a) for a in raw.get("action_items", [])] - self.factor_distribution = self._compute_factor_distribution() - self.coverage_gaps = self._find_coverage_gaps() - self.suggested_actions = self._suggest_missing_actions() - self.theme_recommendations = self._build_theme_recommendations() - - def _compute_factor_distribution(self) -> Dict[str, float]: - dist: Dict[str, float] = {c: 0.0 for c in FACTOR_CATEGORIES} - total = sum(f.weight for f in self.contributing_factors) or 1.0 - for f in self.contributing_factors: - dist[f.category] += f.weight - return {k: round(v / total * 100, 1) for k, v in dist.items()} - - def _find_coverage_gaps(self) -> List[str]: - factor_cats = {f.category for f in self.contributing_factors} - action_types = {a.type for a in self.action_items} - gaps = [] - for cat in factor_cats: - expected = CAT_TO_ACTION.get(cat) - if expected and expected not in action_types: - gaps.append(f"No '{expected}' action item to address '{cat}' contributing factor") - return gaps - - def _suggest_missing_actions(self) -> List[Dict[str, str]]: - factor_cats = {f.category for f in self.contributing_factors} - action_types = {a.type for a in self.action_items} - suggestions = [] - for cat in factor_cats: - expected = CAT_TO_ACTION.get(cat) - if expected and expected not in action_types: - suggestions.append({ - "type": expected, - "suggestion": MISSING_ACTION_TEMPLATES.get(expected, "Add an action item for this gap"), - "reason": f"No action item addresses the '{cat}' contributing factor"}) - return suggestions - - def _build_theme_recommendations(self) -> Dict[str, List[str]]: - seen: Dict[str, List[str]] = {} - for a in self.five_whys: - if a.systemic_theme not in seen: - seen[a.systemic_theme] = THEME_RECS.get(a.systemic_theme, []) - return seen - - def customer_impact_summary(self) -> Dict[str, Any]: - impact = self.resolution.get("customer_impact", {}) - affected = impact.get("affected_users", 0) - failed_tx = impact.get("failed_transactions", 0) - revenue = impact.get("revenue_impact_usd", 0) - data_loss = impact.get("data_loss", False) - comm_required = affected > 1000 or data_loss or revenue > 10000 - sev = "high" if (affected > 10000 or revenue > 50000) else ( - "medium" if (affected > 1000 or revenue > 5000) else "low") - return {"affected_users": affected, "failed_transactions": failed_tx, - "revenue_impact_usd": revenue, "data_loss": data_loss, - "data_integrity": "compromised" if data_loss else "intact", - "customer_communication_required": comm_required, "impact_severity": sev} - - def executive_summary(self) -> str: - mttr = self.timeline.mttr - ci = self.customer_impact_summary() - mttr_str = f"{mttr:.0f} minutes" if mttr is not None else "unknown duration" - parts = [ - f"On {self._fmt_date(self.timeline.issue_started)}, a {self.incident.severity} " - f"incident (\"{self.incident.title}\") impacted the {self.incident.service} service.", - f"The root cause was identified as: {self.resolution.get('root_cause', 'Unknown root cause')}.", - f"The incident was resolved in {mttr_str}, affecting approximately " - f"{ci['affected_users']:,} users with an estimated revenue impact of ${ci['revenue_impact_usd']:,.2f}.", - "Data loss was confirmed; affected customers must be notified." if ci["data_loss"] - else "No data loss occurred during this incident."] - return " ".join(parts) - - @staticmethod - def _fmt_date(dt: Optional[datetime]) -> str: - return dt.strftime("%Y-%m-%d at %H:%M UTC") if dt else "an unknown date" - - def overdue_p1_items(self) -> List[Dict[str, str]]: - return [{"title": a.title, "owner": a.owner, "deadline": a.deadline} - for a in self.action_items if a.priority in ("P0", "P1") and a.is_past_deadline] - - def to_dict(self) -> Dict[str, Any]: - return { - "version": VERSION, "incident": self.incident.to_dict(), - "executive_summary": self.executive_summary(), - "timeline_metrics": self.timeline.to_dict(), - "customer_impact": self.customer_impact_summary(), - "root_cause": self.resolution.get("root_cause", ""), - "contributing_factors": [f.to_dict() for f in self.contributing_factors], - "factor_distribution": self.factor_distribution, - "five_whys_analysis": [a.to_dict() for a in self.five_whys], - "theme_recommendations": self.theme_recommendations, - "mitigation_steps": self.resolution.get("mitigation_steps", []), - "permanent_fix": self.resolution.get("permanent_fix", ""), - "action_items": [a.to_dict() for a in self.action_items], - "action_item_coverage_gaps": self.coverage_gaps, - "suggested_actions": self.suggested_actions, - "overdue_p1_items": self.overdue_p1_items(), - "participants": self.participants} - - -# ---------- Core Analysis Helpers ---------- - -def _bar(pct: float, width: int = 30) -> str: - """Render a text-based horizontal bar chart segment.""" - filled = int(round(pct / 100 * width)) - return "[" + "#" * filled + "." * (width - filled) + "]" - - -def _generate_lessons(report: PostmortemReport) -> List[str]: - """Derive lessons learned from the analysis.""" - lessons: List[str] = [] - bench = BENCHMARKS.get(report.incident.severity, BENCHMARKS["SEV3"]) - mttd = report.timeline.mttd - if mttd is not None and mttd > bench["mttd"]: - lessons.append( - f"Detection took {mttd:.0f} minutes, exceeding the {bench['mttd']}-minute " - f"benchmark for {report.incident.severity}. Invest in earlier detection mechanisms.") - dist = report.factor_distribution - dominant = max(dist, key=lambda k: dist[k]) - if dist[dominant] >= 50: - lessons.append( - f"The '{dominant}' category accounts for {dist[dominant]:.0f}% of contributing factors. " - f"Targeted improvements in this area will yield the highest return.") - if report.coverage_gaps: - lessons.append( - f"There are {len(report.coverage_gaps)} action item coverage gap(s). " - "Ensure every contributing factor category has a corresponding remediation action.") - avg_q = (sum(a.quality_score for a in report.action_items) / len(report.action_items) - if report.action_items else 0) - if avg_q < 70: - lessons.append( - f"Average action item quality score is {avg_q:.0f}/100. " - "Make action items more specific with measurable targets and clear ownership.") - if report.timeline.postmortem_on_time is False: - h = report.timeline.postmortem_timeliness_hours - lessons.append( - f"Postmortem was held {h:.0f} hours after resolution, exceeding the " - f"{POSTMORTEM_TARGET_HOURS}-hour target. Schedule postmortems sooner to capture context.") - if not lessons: - lessons.append("This incident was handled within benchmarks. Continue reinforcing " - "current practices and share this postmortem for organizational learning.") - return lessons - - -# ---------- Output Formatters ---------- - -def format_text(report: PostmortemReport) -> str: - """Format the postmortem as plain text.""" - L: List[str] = [] - W = 72 - - def h1(title: str) -> None: - L.append(""); L.append("=" * W); L.append(f" {title}"); L.append("=" * W) - - def h2(title: str) -> None: - L.append(""); L.append(f"--- {title} ---") - - inc = report.incident - h1(f"POSTMORTEM: {inc.title}") - L.append(f" ID: {inc.id} | Severity: {inc.severity} | Service: {inc.service}") - L.append(f" Commander: {inc.commander}") - if inc.affected_services: - L.append(f" Affected services: {', '.join(inc.affected_services)}") - # Executive Summary - h1("EXECUTIVE SUMMARY") - L.append("") - for sentence in report.executive_summary().split(". "): - s = sentence.strip() - if s and not s.endswith("."): s += "." - if s: L.append(f" {s}") - # Timeline Metrics - h1("TIMELINE METRICS") - tm = report.timeline - L.append("") - for label, val, unit in [("MTTD (Time to Detect)", tm.mttd, "min"), - ("MTTR (Time to Resolve)", tm.mttr, "min"), - ("Time to Mitigate", tm.time_to_mitigate, "min"), - ("Time to Declare", tm.time_to_declare, "min"), - ("Postmortem Timeliness", tm.postmortem_timeliness_hours, "hrs")]: - L.append(f" {label:<30s} {f'{val:.1f} {unit}' if val is not None else 'N/A'}") - h2("Benchmark Comparison") - for name, d in tm.benchmark_comparison().items(): - if "actual_minutes" in d: - st = "PASS" if d["met_benchmark"] else "FAIL" - L.append(f" {name:<25s} actual={d['actual_minutes']}min benchmark={d['benchmark_minutes']}min [{st}]") - elif "actual_hours" in d: - st = "PASS" if d["met_target"] else "FAIL" - L.append(f" {name:<25s} actual={d['actual_hours']}hrs target={d['target_hours']}hrs [{st}]") - # Customer Impact - h1("CUSTOMER IMPACT") - ci = report.customer_impact_summary() - L.append("") - L.append(f" Affected users: {ci['affected_users']:,}") - L.append(f" Failed transactions: {ci['failed_transactions']:,}") - L.append(f" Revenue impact: ${ci['revenue_impact_usd']:,.2f}") - L.append(f" Data integrity: {ci['data_integrity']}") - L.append(f" Impact severity: {ci['impact_severity']}") - L.append(f" Comms required: {'Yes' if ci['customer_communication_required'] else 'No'}") - # Root Cause - h1("ROOT CAUSE ANALYSIS") - L.append("") - L.append(f" {report.resolution.get('root_cause', 'Unknown')}") - h2("Contributing Factors") - for f in report.contributing_factors: - L.append(f" [{f.category.upper():<12s} w={f.weight:.2f}] {f.description}") - h2("Factor Distribution") - for cat, pct in sorted(report.factor_distribution.items(), key=lambda x: -x[1]): - if pct > 0: - L.append(f" {cat:<14s} {pct:5.1f}% {_bar(pct)}") - # 5-Whys - h1("5-WHYS ANALYSIS") - for analysis in report.five_whys: - L.append("") - L.append(f" Factor: {analysis.factor.description}") - L.append(f" Theme: {analysis.systemic_theme}") - for i, step in enumerate(analysis.chain): - L.append(f" {i}. {step}") - h2("Theme-Based Recommendations") - for theme, recs in report.theme_recommendations.items(): - L.append(f" [{theme.upper()}]") - for rec in recs: - L.append(f" - {rec}") - # Mitigation & Fix - h1("MITIGATION AND RESOLUTION") - h2("Mitigation Steps Taken") - for step in report.resolution.get("mitigation_steps", []): - L.append(f" - {step}") - h2("Permanent Fix") - L.append(f" {report.resolution.get('permanent_fix', 'TBD')}") - # Action Items - h1("ACTION ITEMS") - L.append("") - hdr = f" {'Priority':<10s} {'Type':<14s} {'Owner':<25s} {'Deadline':<12s} {'Quality':<8s} Title" - L.append(hdr) - L.append(" " + "-" * (len(hdr) - 2)) - for a in sorted(report.action_items, key=lambda x: PRIORITY_ORDER.get(x.priority, 99)): - flag = " *OVERDUE*" if a.is_past_deadline else "" - L.append(f" {a.priority:<10s} {a.type:<14s} {a.owner:<25s} {a.deadline:<12s} " - f"{a.quality_score:<8d} {a.title}{flag}") - if report.coverage_gaps: - h2("Coverage Gaps") - for gap in report.coverage_gaps: - L.append(f" WARNING: {gap}") - if report.suggested_actions: - h2("Suggested Additional Actions") - for s in report.suggested_actions: - L.append(f" [{s['type'].upper()}] {s['suggestion']}") - L.append(f" Reason: {s['reason']}") - overdue = report.overdue_p1_items() - if overdue: - h2("Overdue P0/P1 Items") - for item in overdue: - L.append(f" OVERDUE: {item['title']} (owner: {item['owner']}, deadline: {item['deadline']})") - # Participants - h1("PARTICIPANTS") - L.append("") - for p in report.participants: - L.append(f" {p.get('name', 'Unknown'):<25s} {p.get('role', '')}") - # Lessons Learned - h1("LESSONS LEARNED") - L.append("") - for i, lesson in enumerate(_generate_lessons(report), 1): - L.append(f" {i}. {lesson}") - L.append("") - L.append("=" * W) - L.append(f" Generated by postmortem_generator v{VERSION}") - L.append("=" * W) - L.append("") - return "\n".join(L) - - -def format_json(report: PostmortemReport) -> str: - """Format the postmortem as JSON.""" - data = report.to_dict() - data["lessons_learned"] = _generate_lessons(report) - return json.dumps(data, indent=2, default=str) - - -def format_markdown(report: PostmortemReport) -> str: - """Format the postmortem as a Markdown document.""" - L: List[str] = [] - inc = report.incident - L.append(f"# Postmortem: {inc.title}") - L.append("") - L.append("| Field | Value |") - L.append("|-------|-------|") - L.append(f"| **ID** | {inc.id} |") - L.append(f"| **Severity** | {inc.severity} |") - L.append(f"| **Service** | {inc.service} |") - L.append(f"| **Commander** | {inc.commander} |") - if inc.affected_services: - L.append(f"| **Affected Services** | {', '.join(inc.affected_services)} |") - L.append("") - # Executive Summary - L.append("## Executive Summary\n") - L.append(report.executive_summary()) - L.append("") - # Timeline Metrics - L.append("## Timeline Metrics\n") - L.append("| Metric | Value | Benchmark | Status |") - L.append("|--------|-------|-----------|--------|") - labels = {"mttd": "MTTD (Time to Detect)", "mttr": "MTTR (Time to Resolve)", - "time_to_mitigate": "Time to Mitigate", "time_to_declare": "Time to Declare", - "postmortem_timeliness": "Postmortem Timeliness"} - for key, label in labels.items(): - b = report.timeline.benchmark_comparison().get(key) - if b and "actual_minutes" in b: - st = "PASS" if b["met_benchmark"] else "FAIL" - L.append(f"| {label} | {b['actual_minutes']} min | {b['benchmark_minutes']} min | {st} |") - elif b and "actual_hours" in b: - st = "PASS" if b["met_target"] else "FAIL" - L.append(f"| {label} | {b['actual_hours']} hrs | {b['target_hours']} hrs | {st} |") - L.append("") - # Customer Impact - L.append("## Customer Impact\n") - ci = report.customer_impact_summary() - L.append(f"- **Affected users:** {ci['affected_users']:,}") - L.append(f"- **Failed transactions:** {ci['failed_transactions']:,}") - L.append(f"- **Revenue impact:** ${ci['revenue_impact_usd']:,.2f}") - L.append(f"- **Data integrity:** {ci['data_integrity']}") - L.append(f"- **Impact severity:** {ci['impact_severity']}") - L.append(f"- **Customer communication required:** {'Yes' if ci['customer_communication_required'] else 'No'}") - L.append("") - # Root Cause Analysis - L.append("## Root Cause Analysis\n") - L.append(f"**Root cause:** {report.resolution.get('root_cause', 'Unknown')}") - L.append("") - L.append("### Contributing Factors\n") - L.append("| # | Category | Weight | Description |") - L.append("|---|----------|--------|-------------|") - for i, f in enumerate(report.contributing_factors, 1): - L.append(f"| {i} | {f.category} | {f.weight:.2f} | {f.description} |") - L.append("") - L.append("### Factor Distribution\n") - L.append("```") - for cat, pct in sorted(report.factor_distribution.items(), key=lambda x: -x[1]): - if pct > 0: - L.append(f" {cat:<14s} {pct:5.1f}% {_bar(pct, 25)}") - L.append("```") - L.append("") - # 5-Whys - L.append("## 5-Whys Analysis\n") - for analysis in report.five_whys: - L.append(f"### Factor: {analysis.factor.description}") - L.append(f"**Systemic theme:** {analysis.systemic_theme}\n") - for i, step in enumerate(analysis.chain): - L.append(f"{i}. {step}") - L.append("") - L.append("### Theme-Based Recommendations\n") - for theme, recs in report.theme_recommendations.items(): - L.append(f"**{theme.capitalize()}:**") - for rec in recs: - L.append(f"- {rec}") - L.append("") - # Mitigation - L.append("## Mitigation and Resolution\n") - L.append("### Mitigation Steps Taken\n") - for step in report.resolution.get("mitigation_steps", []): - L.append(f"- {step}") - L.append("") - L.append("### Permanent Fix\n") - L.append(report.resolution.get("permanent_fix", "TBD")) - L.append("") - # Action Items - L.append("## Action Items\n") - L.append("| Priority | Type | Owner | Deadline | Quality | Title |") - L.append("|----------|------|-------|----------|---------|-------|") - for a in sorted(report.action_items, key=lambda x: PRIORITY_ORDER.get(x.priority, 99)): - flag = " **OVERDUE**" if a.is_past_deadline else "" - L.append(f"| {a.priority} | {a.type} | {a.owner} | {a.deadline} | {a.quality_score}/100 | {a.title}{flag} |") - L.append("") - if report.coverage_gaps: - L.append("### Coverage Gaps\n") - for gap in report.coverage_gaps: - L.append(f"> **WARNING:** {gap}") - L.append("") - if report.suggested_actions: - L.append("### Suggested Additional Actions\n") - for s in report.suggested_actions: - L.append(f"- **[{s['type'].upper()}]** {s['suggestion']}") - L.append(f" - _Reason: {s['reason']}_") - L.append("") - overdue = report.overdue_p1_items() - if overdue: - L.append("### Overdue P0/P1 Items\n") - for item in overdue: - L.append(f"- **{item['title']}** (owner: {item['owner']}, deadline: {item['deadline']})") - L.append("") - # Participants - L.append("## Participants\n") - L.append("| Name | Role |") - L.append("|------|------|") - for p in report.participants: - L.append(f"| {p.get('name', 'Unknown')} | {p.get('role', '')} |") - L.append("") - # Lessons Learned - L.append("## Lessons Learned\n") - for i, lesson in enumerate(_generate_lessons(report), 1): - L.append(f"{i}. {lesson}") - L.append("") - L.append("---") - L.append(f"_Generated by postmortem_generator v{VERSION}_") - L.append("") - return "\n".join(L) - - -# ---------- Input Loading ---------- - -def load_input(filepath: Optional[str]) -> Dict[str, Any]: - """Load incident data from a file path or stdin.""" - if filepath: - try: - with open(filepath, "r", encoding="utf-8") as fh: - return json.load(fh) - except FileNotFoundError: - print(f"Error: File not found: {filepath}", file=sys.stderr) - sys.exit(1) - except json.JSONDecodeError as exc: - print(f"Error: Invalid JSON in {filepath}: {exc}", file=sys.stderr) - sys.exit(1) - else: - if sys.stdin.isatty(): - print("Error: No input file specified and no data on stdin.", file=sys.stderr) - print("Usage: postmortem_generator.py [data_file] or pipe JSON via stdin.", file=sys.stderr) - sys.exit(1) - try: - return json.load(sys.stdin) - except json.JSONDecodeError as exc: - print(f"Error: Invalid JSON on stdin: {exc}", file=sys.stderr) - sys.exit(1) - - -def validate_input(data: Dict[str, Any]) -> List[str]: - """Return a list of validation warnings (non-fatal).""" - warnings: List[str] = [] - for key in ("incident", "timeline", "resolution", "action_items"): - if key not in data: - warnings.append(f"Missing '{key}' section") - for ts in ("issue_started", "detected_at", "mitigated_at", "resolved_at"): - if ts not in data.get("timeline", {}): - warnings.append(f"Missing timeline field: {ts}") - res = data.get("resolution", {}) - if "root_cause" not in res: - warnings.append("Missing 'root_cause' in resolution") - if not res.get("contributing_factors"): - warnings.append("No contributing factors provided") - return warnings - - -# ---------- CLI Entry Point ---------- - -def main() -> None: - """CLI entry point for postmortem generation.""" - parser = argparse.ArgumentParser( - description="Generate structured postmortem reports with 5-Whys analysis.", - epilog="Reads JSON from a file or stdin. Outputs text, JSON, or markdown.") - parser.add_argument("data_file", nargs="?", default=None, - help="JSON file with incident + resolution data (reads stdin if omitted)") - parser.add_argument("--format", choices=["text", "json", "markdown"], default="text", - dest="output_format", help="Output format (default: text)") - args = parser.parse_args() - - data = load_input(args.data_file) - warnings = validate_input(data) - for w in warnings: - print(f"Warning: {w}", file=sys.stderr) - - report = PostmortemReport(data) - formatters = {"text": format_text, "json": format_json, "markdown": format_markdown} - print(formatters[args.output_format](report)) - - -if __name__ == "__main__": - main() diff --git a/engineering-team/skills/incident-commander/scripts/severity_classifier.py b/engineering-team/skills/incident-commander/scripts/severity_classifier.py deleted file mode 100644 index 4ce6ad62..00000000 --- a/engineering-team/skills/incident-commander/scripts/severity_classifier.py +++ /dev/null @@ -1,1228 +0,0 @@ -#!/usr/bin/env python3 -""" -Severity Classifier - Classify incident severity and generate escalation paths. - -Analyses incident data across multiple dimensions (revenue impact, user scope, -data/security risk, service criticality, blast radius) to produce a weighted -severity score and map it to SEV1-SEV4. Generates escalation paths, on-call -routing, SLA impact assessments, and immediate action plans. - -Table of Contents: - SeverityLevel - Enum-like severity definitions (SEV1-SEV4) - ImpactAssessment - Parsed impact data from incident input - SeverityScore - Multi-dimensional weighted scoring result - EscalationPath - Generated escalation routing and timelines - ActionPlan - Recommended immediate actions per severity - SLAImpact - SLA breach risk and error-budget assessment - - parse_incident_data() - Validate and normalise raw JSON input - compute_dimension_scores() - Score each weighted dimension - classify_severity() - Map composite score to SEV1-SEV4 - build_escalation_path() - Generate escalation routing - build_action_plan() - Generate immediate action checklist - assess_sla_impact() - SLA breach risk assessment - format_text() - Human-readable text output - format_json() - Machine-readable JSON output - format_markdown() - Markdown report output - main() - CLI entry point - -Usage: - python severity_classifier.py incident.json - python severity_classifier.py incident.json --format json - python severity_classifier.py incident.json --format markdown - cat incident.json | python severity_classifier.py --format text - echo '{"incident":{...}}' | python severity_classifier.py -""" - -import argparse -import json -import sys -from dataclasses import dataclass, field, asdict -from datetime import datetime, timezone -from typing import Any, Dict, List, Optional, Tuple - - -# ---------- Severity Level Definitions ---------------------------------------- - -class SeverityLevel: - """Enum-like container for SEV1 through SEV4 definitions.""" - - SEV1 = "SEV1" - SEV2 = "SEV2" - SEV3 = "SEV3" - SEV4 = "SEV4" - - DEFINITIONS: Dict[str, Dict[str, Any]] = { - "SEV1": { - "label": "Critical", - "description": ( - "Complete service outage, confirmed data loss or corruption, " - "active security breach, or more than 50% of users affected." - ), - "score_threshold": 0.75, - "response_time_minutes": 5, - "update_cadence_minutes": 15, - "executive_notify": True, - "war_room": True, - }, - "SEV2": { - "label": "Major", - "description": ( - "Significant service degradation, more than 25% of users " - "affected, no viable workaround, or high revenue impact." - ), - "score_threshold": 0.50, - "response_time_minutes": 15, - "update_cadence_minutes": 30, - "executive_notify": False, - "war_room": True, - }, - "SEV3": { - "label": "Moderate", - "description": ( - "Partial degradation with workaround available, fewer than " - "25% of users affected, limited blast radius." - ), - "score_threshold": 0.25, - "response_time_minutes": 30, - "update_cadence_minutes": 60, - "executive_notify": False, - "war_room": False, - }, - "SEV4": { - "label": "Minor", - "description": ( - "Cosmetic issue, low impact, minimal user effect, " - "informational or non-urgent." - ), - "score_threshold": 0.0, - "response_time_minutes": 120, - "update_cadence_minutes": 240, - "executive_notify": False, - "war_room": False, - }, - } - - @classmethod - def from_score(cls, score: float) -> str: - """Return the severity level string for a given composite score.""" - for level in [cls.SEV1, cls.SEV2, cls.SEV3]: - if score >= cls.DEFINITIONS[level]["score_threshold"]: - return level - return cls.SEV4 - - @classmethod - def get_definition(cls, level: str) -> Dict[str, Any]: - return cls.DEFINITIONS.get(level, cls.DEFINITIONS[cls.SEV4]) - - -# ---------- Configuration Constants ------------------------------------------- - -DIMENSION_WEIGHTS: Dict[str, float] = { - "revenue_impact": 0.25, - "user_impact_scope": 0.25, - "data_security_risk": 0.20, - "service_criticality": 0.15, - "blast_radius": 0.15, -} - -REVENUE_IMPACT_SCORES: Dict[str, float] = { - "critical": 1.0, - "high": 0.8, - "medium": 0.5, - "low": 0.2, - "none": 0.0, -} - -DEGRADATION_SCORES: Dict[str, float] = { - "complete": 1.0, - "major": 0.75, - "partial": 0.50, - "minor": 0.25, - "none": 0.0, -} - -ERROR_RATE_THRESHOLDS: List[Tuple[float, float]] = [ - (50.0, 1.0), - (25.0, 0.8), - (10.0, 0.6), - (5.0, 0.4), - (1.0, 0.2), -] - -LATENCY_P99_THRESHOLDS_MS: List[Tuple[float, float]] = [ - (10000, 1.0), - (5000, 0.8), - (2000, 0.6), - (1000, 0.4), - (500, 0.2), -] - -SLA_TIERS: Dict[str, Dict[str, Any]] = { - "SEV1": { - "target_resolution_hours": 1, - "target_response_minutes": 5, - "sla_percentage": 99.95, - "monthly_error_budget_minutes": 21.6, - }, - "SEV2": { - "target_resolution_hours": 4, - "target_response_minutes": 15, - "sla_percentage": 99.9, - "monthly_error_budget_minutes": 43.2, - }, - "SEV3": { - "target_resolution_hours": 24, - "target_response_minutes": 60, - "sla_percentage": 99.5, - "monthly_error_budget_minutes": 216.0, - }, - "SEV4": { - "target_resolution_hours": 72, - "target_response_minutes": 480, - "sla_percentage": 99.0, - "monthly_error_budget_minutes": 432.0, - }, -} - -ESCALATION_TEMPLATES: Dict[str, Dict[str, Any]] = { - "SEV1": { - "initial_notify": ["on-call-primary", "on-call-secondary", "engineering-manager"], - "escalate_after_minutes": 15, - "escalate_to": ["vp-engineering", "cto"], - "bridge_required": True, - "status_page_update": True, - "customer_comms": True, - }, - "SEV2": { - "initial_notify": ["on-call-primary", "on-call-secondary"], - "escalate_after_minutes": 30, - "escalate_to": ["engineering-manager"], - "bridge_required": True, - "status_page_update": True, - "customer_comms": False, - }, - "SEV3": { - "initial_notify": ["on-call-primary"], - "escalate_after_minutes": 120, - "escalate_to": ["on-call-secondary"], - "bridge_required": False, - "status_page_update": False, - "customer_comms": False, - }, - "SEV4": { - "initial_notify": ["on-call-primary"], - "escalate_after_minutes": 480, - "escalate_to": [], - "bridge_required": False, - "status_page_update": False, - "customer_comms": False, - }, -} - - -# ---------- Data Model Classes ------------------------------------------------ - -@dataclass -class ImpactAssessment: - """Parsed and normalised impact data from incident input.""" - - revenue_impact: str = "none" - affected_users_percentage: float = 0.0 - affected_regions: List[str] = field(default_factory=list) - data_integrity_risk: bool = False - security_breach: bool = False - customer_facing: bool = False - degradation_type: str = "none" - workaround_available: bool = True - - -@dataclass -class SeverityScore: - """Multi-dimensional scoring result with per-dimension breakdown.""" - - composite_score: float = 0.0 - severity_level: str = SeverityLevel.SEV4 - dimensions: Dict[str, float] = field(default_factory=dict) - weighted_dimensions: Dict[str, float] = field(default_factory=dict) - contributing_factors: List[str] = field(default_factory=list) - auto_escalate_reasons: List[str] = field(default_factory=list) - - -@dataclass -class EscalationPath: - """Generated escalation routing and notification schedule.""" - - severity_level: str = SeverityLevel.SEV4 - immediate_notify: List[str] = field(default_factory=list) - escalation_chain: List[Dict[str, Any]] = field(default_factory=list) - cross_team_notify: List[str] = field(default_factory=list) - war_room_required: bool = False - bridge_link: str = "" - status_page_update: bool = False - customer_comms_required: bool = False - suggested_smes: List[str] = field(default_factory=list) - - -@dataclass -class ActionPlan: - """Recommended immediate actions checklist for the incident.""" - - severity_level: str = SeverityLevel.SEV4 - immediate_actions: List[str] = field(default_factory=list) - diagnostic_steps: List[str] = field(default_factory=list) - communication_actions: List[str] = field(default_factory=list) - rollback_assessment: Dict[str, Any] = field(default_factory=dict) - - -@dataclass -class SLAImpact: - """SLA breach risk and error-budget assessment.""" - - severity_level: str = SeverityLevel.SEV4 - sla_tier: Dict[str, Any] = field(default_factory=dict) - breach_risk: str = "low" - error_budget_impact_minutes: float = 0.0 - remaining_budget_percentage: float = 100.0 - estimated_time_to_breach_minutes: float = 0.0 - recommendations: List[str] = field(default_factory=list) - - -# ---------- Input Parsing ----------------------------------------------------- - -def parse_incident_data(raw: Dict[str, Any]) -> Tuple[Dict, ImpactAssessment, Dict, Dict]: - """ - Validate and normalise raw JSON input into typed structures. - - Returns: - (incident_info, impact_assessment, signals, context) - """ - incident = raw.get("incident", {}) - if not incident: - raise ValueError("Input must contain an 'incident' key with title and description.") - - impact_raw = raw.get("impact", {}) - impact = ImpactAssessment( - revenue_impact=impact_raw.get("revenue_impact", "none"), - affected_users_percentage=float(impact_raw.get("affected_users_percentage", 0)), - affected_regions=impact_raw.get("affected_regions", []), - data_integrity_risk=bool(impact_raw.get("data_integrity_risk", False)), - security_breach=bool(impact_raw.get("security_breach", False)), - customer_facing=bool(impact_raw.get("customer_facing", False)), - degradation_type=impact_raw.get("degradation_type", "none"), - workaround_available=bool(impact_raw.get("workaround_available", True)), - ) - - signals = raw.get("signals", {}) - context = raw.get("context", {}) - - return incident, impact, signals, context - - -# ---------- Core Scoring Engine ----------------------------------------------- - -def _score_revenue_impact(impact: ImpactAssessment) -> Tuple[float, List[str]]: - """Score the revenue impact dimension (0.0 - 1.0).""" - factors: List[str] = [] - score = REVENUE_IMPACT_SCORES.get(impact.revenue_impact, 0.0) - - if impact.customer_facing and score >= 0.5: - score = min(1.0, score + 0.1) - factors.append("Customer-facing service with revenue exposure") - - if not impact.workaround_available and score >= 0.5: - score = min(1.0, score + 0.1) - factors.append("No workaround available, prolonging revenue impact") - - if score >= 0.8: - factors.append(f"Revenue impact rated '{impact.revenue_impact}'") - - return score, factors - - -def _score_user_impact(impact: ImpactAssessment, signals: Dict) -> Tuple[float, List[str]]: - """Score the user impact scope dimension (0.0 - 1.0).""" - factors: List[str] = [] - pct = impact.affected_users_percentage - - if pct >= 75: - score = 1.0 - elif pct >= 50: - score = 0.85 - elif pct >= 25: - score = 0.65 - elif pct >= 10: - score = 0.45 - elif pct >= 1: - score = 0.25 - else: - score = 0.1 - - if pct > 0: - factors.append(f"{pct}% of users affected") - - customer_reports = signals.get("customer_reports", 0) - if customer_reports > 20: - score = min(1.0, score + 0.15) - factors.append(f"{customer_reports} customer reports received") - elif customer_reports > 5: - score = min(1.0, score + 0.08) - factors.append(f"{customer_reports} customer reports received") - - degradation_boost = DEGRADATION_SCORES.get(impact.degradation_type, 0.0) * 0.15 - score = min(1.0, score + degradation_boost) - if impact.degradation_type in ("complete", "major"): - factors.append(f"Degradation type: {impact.degradation_type}") - - return score, factors - - -def _score_data_security(impact: ImpactAssessment) -> Tuple[float, List[str]]: - """Score the data/security risk dimension (0.0 - 1.0).""" - factors: List[str] = [] - score = 0.0 - - if impact.security_breach: - score = 1.0 - factors.append("Active security breach confirmed") - elif impact.data_integrity_risk: - score = 0.8 - factors.append("Data integrity at risk") - - if impact.customer_facing and impact.data_integrity_risk: - score = min(1.0, score + 0.1) - factors.append("Customer data potentially affected") - - return score, factors - - -def _score_service_criticality(signals: Dict, context: Dict) -> Tuple[float, List[str]]: - """Score service criticality based on signals and dependency graph.""" - factors: List[str] = [] - score = 0.0 - - dependent_services = signals.get("dependent_services", []) - dep_count = len(dependent_services) - if dep_count >= 5: - score = 1.0 - factors.append(f"{dep_count} dependent services (critical hub)") - elif dep_count >= 3: - score = 0.75 - factors.append(f"{dep_count} dependent services") - elif dep_count >= 1: - score = 0.5 - factors.append(f"{dep_count} dependent service(s)") - else: - score = 0.2 - - affected_endpoints = signals.get("affected_endpoints", []) - if len(affected_endpoints) >= 5: - score = min(1.0, score + 0.15) - factors.append(f"{len(affected_endpoints)} endpoints affected") - elif len(affected_endpoints) >= 2: - score = min(1.0, score + 0.08) - factors.append(f"{len(affected_endpoints)} endpoints affected") - - return score, factors - - -def _score_blast_radius( - impact: ImpactAssessment, signals: Dict -) -> Tuple[float, List[str]]: - """Score blast radius from region spread, alert volume, and error rate.""" - factors: List[str] = [] - score = 0.0 - - region_count = len(impact.affected_regions) - if region_count >= 3: - score = 0.9 - factors.append(f"Spanning {region_count} regions") - elif region_count == 2: - score = 0.6 - factors.append(f"Spanning {region_count} regions") - elif region_count == 1: - score = 0.3 - - error_rate = signals.get("error_rate_percentage", 0.0) - for threshold, rate_score in ERROR_RATE_THRESHOLDS: - if error_rate >= threshold: - score = max(score, rate_score) - factors.append(f"Error rate at {error_rate}%") - break - - latency = signals.get("latency_p99_ms", 0) - for threshold, lat_score in LATENCY_P99_THRESHOLDS_MS: - if latency >= threshold: - score = max(score, lat_score) - factors.append(f"P99 latency at {latency}ms") - break - - alert_count = signals.get("alert_count", 0) - if alert_count >= 20: - score = min(1.0, score + 0.15) - factors.append(f"{alert_count} alerts firing") - elif alert_count >= 10: - score = min(1.0, score + 0.08) - factors.append(f"{alert_count} alerts firing") - - return score, factors - - -def compute_dimension_scores( - impact: ImpactAssessment, signals: Dict, context: Dict -) -> SeverityScore: - """Score each weighted dimension and produce a composite severity score.""" - dimensions: Dict[str, float] = {} - weighted: Dict[str, float] = {} - all_factors: List[str] = [] - auto_escalate: List[str] = [] - - # -- Revenue impact -- - rev_score, rev_factors = _score_revenue_impact(impact) - dimensions["revenue_impact"] = round(rev_score, 3) - weighted["revenue_impact"] = round(rev_score * DIMENSION_WEIGHTS["revenue_impact"], 3) - all_factors.extend(rev_factors) - - # -- User impact scope -- - user_score, user_factors = _score_user_impact(impact, signals) - dimensions["user_impact_scope"] = round(user_score, 3) - weighted["user_impact_scope"] = round(user_score * DIMENSION_WEIGHTS["user_impact_scope"], 3) - all_factors.extend(user_factors) - - # -- Data / security risk -- - sec_score, sec_factors = _score_data_security(impact) - dimensions["data_security_risk"] = round(sec_score, 3) - weighted["data_security_risk"] = round(sec_score * DIMENSION_WEIGHTS["data_security_risk"], 3) - all_factors.extend(sec_factors) - - # -- Service criticality -- - svc_score, svc_factors = _score_service_criticality(signals, context) - dimensions["service_criticality"] = round(svc_score, 3) - weighted["service_criticality"] = round(svc_score * DIMENSION_WEIGHTS["service_criticality"], 3) - all_factors.extend(svc_factors) - - # -- Blast radius -- - blast_score, blast_factors = _score_blast_radius(impact, signals) - dimensions["blast_radius"] = round(blast_score, 3) - weighted["blast_radius"] = round(blast_score * DIMENSION_WEIGHTS["blast_radius"], 3) - all_factors.extend(blast_factors) - - composite = sum(weighted.values()) - - # -- Auto-escalation overrides -- - if impact.security_breach: - composite = max(composite, 0.85) - auto_escalate.append("Security breach triggers automatic SEV1 escalation") - if impact.data_integrity_risk and impact.customer_facing: - composite = max(composite, 0.76) - auto_escalate.append("Customer-facing data integrity risk triggers SEV1 floor") - if impact.affected_users_percentage >= 50 and impact.degradation_type == "complete": - composite = max(composite, 0.80) - auto_escalate.append("Complete outage affecting 50%+ users triggers SEV1 floor") - - composite = min(1.0, round(composite, 3)) - severity_level = SeverityLevel.from_score(composite) - - return SeverityScore( - composite_score=composite, - severity_level=severity_level, - dimensions=dimensions, - weighted_dimensions=weighted, - contributing_factors=all_factors, - auto_escalate_reasons=auto_escalate, - ) - - -# ---------- Classification Wrapper -------------------------------------------- - -def classify_severity( - incident: Dict, impact: ImpactAssessment, signals: Dict, context: Dict -) -> SeverityScore: - """ - Top-level classification: compute scores and return the final - SeverityScore including the resolved severity level. - """ - return compute_dimension_scores(impact, signals, context) - - -# ---------- Escalation Path Builder ------------------------------------------- - -def build_escalation_path( - severity_score: SeverityScore, - signals: Dict, - context: Dict, -) -> EscalationPath: - """Generate the escalation routing based on severity and context.""" - level = severity_score.severity_level - template = ESCALATION_TEMPLATES.get(level, ESCALATION_TEMPLATES["SEV4"]) - - on_call = context.get("on_call", {}) - primary = on_call.get("primary", "on-call-primary@company.com") - secondary = on_call.get("secondary", "on-call-secondary@company.com") - - immediate: List[str] = [] - for role in template["initial_notify"]: - if role == "on-call-primary": - immediate.append(primary) - elif role == "on-call-secondary": - immediate.append(secondary) - else: - immediate.append(role) - - chain: List[Dict[str, Any]] = [] - if template["escalate_to"]: - chain.append({ - "trigger_after_minutes": template["escalate_after_minutes"], - "notify": template["escalate_to"], - "reason": f"No resolution within {template['escalate_after_minutes']} minutes", - }) - - sev_def = SeverityLevel.get_definition(level) - if sev_def.get("executive_notify"): - chain.append({ - "trigger_after_minutes": 15, - "notify": ["vp-engineering", "cto"], - "reason": "SEV1 executive notification policy", - }) - - cross_team: List[str] = [] - dependent_services = signals.get("dependent_services", []) - for svc in dependent_services: - cross_team.append(f"{svc}-team") - - suggested_smes: List[str] = [] - affected_endpoints = signals.get("affected_endpoints", []) - if affected_endpoints: - suggested_smes.append(f"API owner for: {', '.join(affected_endpoints[:3])}") - if dependent_services: - suggested_smes.append(f"Service owners: {', '.join(dependent_services[:3])}") - - ongoing = context.get("ongoing_incidents", []) - if ongoing: - suggested_smes.append("Incident coordinator (multiple active incidents)") - - bridge_link = "" - if template["bridge_required"]: - bridge_link = f"https://bridge.company.com/incident-{level.lower()}" - - return EscalationPath( - severity_level=level, - immediate_notify=immediate, - escalation_chain=chain, - cross_team_notify=cross_team, - war_room_required=template["bridge_required"], - bridge_link=bridge_link, - status_page_update=template["status_page_update"], - customer_comms_required=template.get("customer_comms", False), - suggested_smes=suggested_smes, - ) - - -# ---------- Action Plan Builder ----------------------------------------------- - -def build_action_plan( - severity_score: SeverityScore, - incident: Dict, - impact: ImpactAssessment, - signals: Dict, - context: Dict, -) -> ActionPlan: - """Generate the immediate action plan for the classified incident.""" - level = severity_score.severity_level - sev_def = SeverityLevel.get_definition(level) - - # -- Immediate actions -- - immediate: List[str] = [ - f"Acknowledge incident within {sev_def['response_time_minutes']} minutes", - "Join the war room / bridge call" if sev_def["war_room"] else "Open incident channel", - f"Post status update every {sev_def['update_cadence_minutes']} minutes", - ] - - if level in (SeverityLevel.SEV1, SeverityLevel.SEV2): - immediate.append("Page secondary on-call if primary unresponsive within 5 minutes") - immediate.append("Begin impact quantification for executive update") - - if impact.security_breach: - immediate.insert(0, "CRITICAL: Initiate security incident response playbook") - immediate.append("Engage security team immediately") - immediate.append("Preserve forensic evidence -- do not restart services yet") - - if impact.data_integrity_risk: - immediate.append("Halt writes to affected data stores if safe to do so") - immediate.append("Begin data integrity verification") - - # -- Diagnostic steps -- - diagnostics: List[str] = [ - "Check service dashboards and recent metric trends", - "Review application logs for error spikes", - "Verify upstream and downstream dependency health", - ] - - error_rate = signals.get("error_rate_percentage", 0) - if error_rate > 10: - diagnostics.append(f"Investigate error rate spike ({error_rate}%)") - - latency = signals.get("latency_p99_ms", 0) - if latency > 2000: - diagnostics.append(f"Investigate latency degradation (P99 = {latency}ms)") - - affected_endpoints = signals.get("affected_endpoints", []) - if affected_endpoints: - diagnostics.append( - f"Trace requests to affected endpoints: {', '.join(affected_endpoints[:5])}" - ) - - dependent_services = signals.get("dependent_services", []) - if dependent_services: - diagnostics.append( - f"Check health of dependent services: {', '.join(dependent_services)}" - ) - - # -- Communication actions -- - comms: List[str] = [] - if sev_def.get("executive_notify"): - comms.append("Draft executive summary within 15 minutes") - if level in (SeverityLevel.SEV1, SeverityLevel.SEV2): - comms.append("Post initial status page update") - comms.append("Notify customer success team for proactive outreach") - comms.append(f"Schedule post-incident review within 48 hours") - - # -- Rollback assessment -- - recent_deploys = context.get("recent_deployments", []) - rollback: Dict[str, Any] = {"recent_deployment_detected": False, "recommendation": ""} - - if recent_deploys: - latest = recent_deploys[0] - rollback["recent_deployment_detected"] = True - rollback["service"] = latest.get("service", "unknown") - rollback["version"] = latest.get("version", "unknown") - rollback["deployed_at"] = latest.get("deployed_at", "unknown") - - detected_at = incident.get("detected_at", "") - deploy_time = latest.get("deployed_at", "") - if detected_at and deploy_time: - try: - det = datetime.fromisoformat(detected_at.replace("Z", "+00:00")) - dep = datetime.fromisoformat(deploy_time.replace("Z", "+00:00")) - delta_minutes = (det - dep).total_seconds() / 60 - rollback["minutes_since_deploy"] = round(delta_minutes, 1) - if 0 < delta_minutes < 120: - rollback["recommendation"] = ( - f"STRONG: Deployment of {latest.get('service')} v{latest.get('version')} " - f"occurred {round(delta_minutes)} minutes before detection. " - "Consider immediate rollback." - ) - else: - rollback["recommendation"] = ( - "Recent deployment is outside the typical correlation window. " - "Investigate other root causes first." - ) - except (ValueError, TypeError): - rollback["recommendation"] = ( - "Unable to parse timestamps. Manually assess deployment correlation." - ) - else: - rollback["recommendation"] = ( - "No recent deployments detected. Focus on infrastructure and dependency investigation." - ) - - return ActionPlan( - severity_level=level, - immediate_actions=immediate, - diagnostic_steps=diagnostics, - communication_actions=comms, - rollback_assessment=rollback, - ) - - -# ---------- SLA Impact Assessment --------------------------------------------- - -def assess_sla_impact( - severity_score: SeverityScore, - impact: ImpactAssessment, - signals: Dict, -) -> SLAImpact: - """Calculate SLA breach risk and error-budget consumption.""" - level = severity_score.severity_level - tier = SLA_TIERS.get(level, SLA_TIERS["SEV4"]) - - # Estimate ongoing burn rate (minutes of budget consumed per real minute) - user_pct = impact.affected_users_percentage / 100.0 - degradation_factor = DEGRADATION_SCORES.get(impact.degradation_type, 0.25) - burn_rate = user_pct * degradation_factor - if burn_rate <= 0: - burn_rate = 0.01 # minimum if incident is open - - monthly_budget = tier["monthly_error_budget_minutes"] - - # Assume 30% of budget already consumed this month for conservative estimate - assumed_consumed_pct = 30.0 - remaining_budget = monthly_budget * (1 - assumed_consumed_pct / 100.0) - - if burn_rate > 0: - time_to_breach = remaining_budget / burn_rate - else: - time_to_breach = float("inf") - - # Classify breach risk - if time_to_breach <= 30: - breach_risk = "critical" - elif time_to_breach <= 120: - breach_risk = "high" - elif time_to_breach <= 480: - breach_risk = "medium" - else: - breach_risk = "low" - - budget_impact_per_hour = burn_rate * 60 - error_budget_impact = round(budget_impact_per_hour, 2) - - remaining_pct = round( - max(0.0, (remaining_budget / monthly_budget) * 100.0), 1 - ) - - recommendations: List[str] = [] - if breach_risk == "critical": - recommendations.append( - "SLA breach imminent. Prioritize resolution above all other work." - ) - recommendations.append( - "Prepare customer communication about potential SLA credit." - ) - elif breach_risk == "high": - recommendations.append( - "SLA breach likely within hours. Escalate to ensure rapid resolution." - ) - elif breach_risk == "medium": - recommendations.append( - "Monitor error budget consumption. Resolve before end of business." - ) - else: - recommendations.append( - "SLA impact is contained. Continue standard incident response." - ) - - recommendations.append( - f"Current burn rate: {round(burn_rate * 100, 1)}% of error budget per minute" - ) - recommendations.append( - f"Estimated time to SLA breach: {round(time_to_breach, 0)} minutes " - f"({round(time_to_breach / 60, 1)} hours)" - ) - - return SLAImpact( - severity_level=level, - sla_tier=tier, - breach_risk=breach_risk, - error_budget_impact_minutes=error_budget_impact, - remaining_budget_percentage=remaining_pct, - estimated_time_to_breach_minutes=round(time_to_breach, 1), - recommendations=recommendations, - ) - - -# ---------- Output Formatters ------------------------------------------------- - -def _header_line(char: str, width: int = 72) -> str: - return char * width - - -def format_text( - incident: Dict, - severity_score: SeverityScore, - escalation: EscalationPath, - action_plan: ActionPlan, - sla_impact: SLAImpact, -) -> str: - """Render a human-readable text report.""" - lines: List[str] = [] - w = 72 - - lines.append(_header_line("=", w)) - lines.append("INCIDENT SEVERITY CLASSIFICATION REPORT") - lines.append(_header_line("=", w)) - lines.append("") - - # -- Incident Summary -- - lines.append(f"Title: {incident.get('title', 'N/A')}") - lines.append(f"Service: {incident.get('service', 'N/A')}") - lines.append(f"Detected: {incident.get('detected_at', 'N/A')}") - lines.append(f"Reporter: {incident.get('reporter', 'N/A')}") - lines.append("") - - # -- Severity -- - sev_def = SeverityLevel.get_definition(severity_score.severity_level) - lines.append(_header_line("-", w)) - lines.append(f"SEVERITY: {severity_score.severity_level} ({sev_def['label']})") - lines.append(f"Composite Score: {severity_score.composite_score:.3f}") - lines.append(_header_line("-", w)) - lines.append(f" {sev_def['description']}") - lines.append("") - - # -- Dimension Breakdown -- - lines.append("Dimension Scores:") - for dim, raw in severity_score.dimensions.items(): - wt = severity_score.weighted_dimensions.get(dim, 0) - weight_cfg = DIMENSION_WEIGHTS.get(dim, 0) - label = dim.replace("_", " ").title() - lines.append(f" {label:<25s} raw={raw:.3f} weight={weight_cfg:.2f} weighted={wt:.3f}") - lines.append("") - - if severity_score.contributing_factors: - lines.append("Contributing Factors:") - for f in severity_score.contributing_factors: - lines.append(f" - {f}") - lines.append("") - - if severity_score.auto_escalate_reasons: - lines.append("Auto-Escalation Overrides:") - for r in severity_score.auto_escalate_reasons: - lines.append(f" * {r}") - lines.append("") - - # -- Escalation Path -- - lines.append(_header_line("-", w)) - lines.append("ESCALATION PATH") - lines.append(_header_line("-", w)) - lines.append(f"Immediate Notify: {', '.join(escalation.immediate_notify)}") - if escalation.war_room_required: - lines.append(f"War Room: Required ({escalation.bridge_link})") - else: - lines.append("War Room: Not required") - lines.append(f"Status Page: {'Update required' if escalation.status_page_update else 'No update needed'}") - lines.append(f"Customer Comms: {'Required' if escalation.customer_comms_required else 'Not required'}") - lines.append("") - - if escalation.escalation_chain: - lines.append("Escalation Chain:") - for step in escalation.escalation_chain: - lines.append( - f" After {step['trigger_after_minutes']}min -> " - f"Notify: {', '.join(step['notify'])} ({step['reason']})" - ) - lines.append("") - - if escalation.cross_team_notify: - lines.append(f"Cross-Team Notify: {', '.join(escalation.cross_team_notify)}") - if escalation.suggested_smes: - lines.append("Suggested SMEs:") - for sme in escalation.suggested_smes: - lines.append(f" - {sme}") - lines.append("") - - # -- Action Plan -- - lines.append(_header_line("-", w)) - lines.append("ACTION PLAN") - lines.append(_header_line("-", w)) - - lines.append("Immediate Actions:") - for i, action in enumerate(action_plan.immediate_actions, 1): - lines.append(f" {i}. {action}") - lines.append("") - - lines.append("Diagnostic Steps:") - for i, step in enumerate(action_plan.diagnostic_steps, 1): - lines.append(f" {i}. {step}") - lines.append("") - - lines.append("Communication Actions:") - for i, action in enumerate(action_plan.communication_actions, 1): - lines.append(f" {i}. {action}") - lines.append("") - - rb = action_plan.rollback_assessment - lines.append("Rollback Assessment:") - if rb.get("recent_deployment_detected"): - lines.append(f" Recent Deploy: {rb.get('service', '?')} v{rb.get('version', '?')}") - lines.append(f" Deployed At: {rb.get('deployed_at', '?')}") - if "minutes_since_deploy" in rb: - lines.append(f" Minutes Before Detection: {rb['minutes_since_deploy']}") - lines.append(f" Recommendation: {rb.get('recommendation', 'N/A')}") - lines.append("") - - # -- SLA Impact -- - lines.append(_header_line("-", w)) - lines.append("SLA IMPACT ASSESSMENT") - lines.append(_header_line("-", w)) - lines.append(f"Breach Risk: {sla_impact.breach_risk.upper()}") - lines.append(f"Error Budget Impact: {sla_impact.error_budget_impact_minutes} min/hr") - lines.append(f"Remaining Budget: {sla_impact.remaining_budget_percentage}%") - lines.append(f"Est. Time to Breach: {sla_impact.estimated_time_to_breach_minutes} min") - tier = sla_impact.sla_tier - lines.append(f"Target Resolution: {tier.get('target_resolution_hours', '?')} hours") - lines.append(f"Target Response: {tier.get('target_response_minutes', '?')} minutes") - lines.append("") - - if sla_impact.recommendations: - lines.append("SLA Recommendations:") - for rec in sla_impact.recommendations: - lines.append(f" - {rec}") - lines.append("") - lines.append(_header_line("=", w)) - - return "\n".join(lines) - - -def format_json( - incident: Dict, - severity_score: SeverityScore, - escalation: EscalationPath, - action_plan: ActionPlan, - sla_impact: SLAImpact, -) -> str: - """Render a machine-readable JSON report.""" - report = { - "classification_timestamp": datetime.now(timezone.utc).isoformat(), - "incident": incident, - "severity": asdict(severity_score), - "severity_definition": SeverityLevel.get_definition(severity_score.severity_level), - "escalation": asdict(escalation), - "action_plan": asdict(action_plan), - "sla_impact": asdict(sla_impact), - } - return json.dumps(report, indent=2, default=str) - - -def format_markdown( - incident: Dict, - severity_score: SeverityScore, - escalation: EscalationPath, - action_plan: ActionPlan, - sla_impact: SLAImpact, -) -> str: - """Render a Markdown report suitable for incident tickets or wikis.""" - lines: List[str] = [] - sev_def = SeverityLevel.get_definition(severity_score.severity_level) - - lines.append(f"# Incident Severity Classification: {severity_score.severity_level}") - lines.append("") - lines.append(f"**Classified:** {datetime.now(timezone.utc).strftime('%Y-%m-%d %H:%M UTC')}") - lines.append("") - - lines.append("## Incident Summary") - lines.append("") - lines.append(f"| Field | Value |") - lines.append(f"|-------|-------|") - lines.append(f"| Title | {incident.get('title', 'N/A')} |") - lines.append(f"| Service | {incident.get('service', 'N/A')} |") - lines.append(f"| Detected | {incident.get('detected_at', 'N/A')} |") - lines.append(f"| Reporter | {incident.get('reporter', 'N/A')} |") - lines.append("") - - lines.append("## Severity Classification") - lines.append("") - lines.append( - f"> **{severity_score.severity_level} -- {sev_def['label']}** " - f"(Score: {severity_score.composite_score:.3f})" - ) - lines.append(f">") - lines.append(f"> {sev_def['description']}") - lines.append("") - - lines.append("### Dimension Scores") - lines.append("") - lines.append("| Dimension | Raw | Weight | Weighted |") - lines.append("|-----------|-----|--------|----------|") - for dim, raw in severity_score.dimensions.items(): - wt = severity_score.weighted_dimensions.get(dim, 0) - weight_cfg = DIMENSION_WEIGHTS.get(dim, 0) - label = dim.replace("_", " ").title() - lines.append(f"| {label} | {raw:.3f} | {weight_cfg:.2f} | {wt:.3f} |") - lines.append("") - - if severity_score.contributing_factors: - lines.append("### Contributing Factors") - lines.append("") - for f in severity_score.contributing_factors: - lines.append(f"- {f}") - lines.append("") - - if severity_score.auto_escalate_reasons: - lines.append("### Auto-Escalation Overrides") - lines.append("") - for r in severity_score.auto_escalate_reasons: - lines.append(f"- **{r}**") - lines.append("") - - lines.append("## Escalation Path") - lines.append("") - lines.append(f"**Immediate Notify:** {', '.join(escalation.immediate_notify)}") - lines.append("") - - if escalation.war_room_required: - lines.append(f"**War Room:** [Join Bridge]({escalation.bridge_link})") - else: - lines.append("**War Room:** Not required") - lines.append("") - - if escalation.escalation_chain: - lines.append("### Escalation Chain") - lines.append("") - for step in escalation.escalation_chain: - lines.append( - f"- **After {step['trigger_after_minutes']} min:** " - f"Notify {', '.join(step['notify'])} -- {step['reason']}" - ) - lines.append("") - - if escalation.cross_team_notify: - lines.append(f"**Cross-Team:** {', '.join(escalation.cross_team_notify)}") - lines.append("") - - if escalation.suggested_smes: - lines.append("### Suggested SMEs") - lines.append("") - for sme in escalation.suggested_smes: - lines.append(f"- {sme}") - lines.append("") - - lines.append("## Action Plan") - lines.append("") - - lines.append("### Immediate Actions") - lines.append("") - for i, action in enumerate(action_plan.immediate_actions, 1): - lines.append(f"{i}. {action}") - lines.append("") - - lines.append("### Diagnostic Steps") - lines.append("") - for i, step in enumerate(action_plan.diagnostic_steps, 1): - lines.append(f"{i}. {step}") - lines.append("") - - lines.append("### Communication") - lines.append("") - for i, action in enumerate(action_plan.communication_actions, 1): - lines.append(f"{i}. {action}") - lines.append("") - - rb = action_plan.rollback_assessment - lines.append("### Rollback Assessment") - lines.append("") - if rb.get("recent_deployment_detected"): - lines.append( - f"| Deploy | {rb.get('service', '?')} v{rb.get('version', '?')} |" - ) - lines.append(f"|--------|------|") - lines.append(f"| Deployed At | {rb.get('deployed_at', '?')} |") - if "minutes_since_deploy" in rb: - lines.append(f"| Minutes Before Detection | {rb['minutes_since_deploy']} |") - lines.append("") - lines.append(f"**Recommendation:** {rb.get('recommendation', 'N/A')}") - lines.append("") - - lines.append("## SLA Impact") - lines.append("") - tier = sla_impact.sla_tier - lines.append(f"| Metric | Value |") - lines.append(f"|--------|-------|") - lines.append(f"| Breach Risk | **{sla_impact.breach_risk.upper()}** |") - lines.append(f"| Error Budget Impact | {sla_impact.error_budget_impact_minutes} min/hr |") - lines.append(f"| Remaining Budget | {sla_impact.remaining_budget_percentage}% |") - lines.append(f"| Est. Time to Breach | {sla_impact.estimated_time_to_breach_minutes} min |") - lines.append(f"| Target Resolution | {tier.get('target_resolution_hours', '?')} hours |") - lines.append(f"| Target Response | {tier.get('target_response_minutes', '?')} minutes |") - lines.append("") - - if sla_impact.recommendations: - lines.append("### SLA Recommendations") - lines.append("") - for rec in sla_impact.recommendations: - lines.append(f"- {rec}") - lines.append("") - - lines.append("---") - lines.append("*Generated by severity_classifier.py*") - - return "\n".join(lines) - - -# ---------- CLI Entry Point --------------------------------------------------- - -def main() -> None: - """Parse arguments, read input, classify, and emit output.""" - parser = argparse.ArgumentParser( - description="Classify incident severity and generate escalation paths.", - formatter_class=argparse.RawDescriptionHelpFormatter, - epilog="""\ -examples: - %(prog)s incident.json - %(prog)s incident.json --format json - %(prog)s incident.json --format markdown - cat incident.json | %(prog)s - cat incident.json | %(prog)s --format json -""", - ) - - parser.add_argument( - "data_file", - nargs="?", - default=None, - help="JSON file with incident data (reads stdin if omitted)", - ) - parser.add_argument( - "--format", - choices=["text", "json", "markdown"], - default="text", - dest="output_format", - help="Output format (default: text)", - ) - - args = parser.parse_args() - - # -- Read input -- - try: - if args.data_file: - with open(args.data_file, "r", encoding="utf-8") as fh: - raw_data = json.load(fh) - else: - if sys.stdin.isatty(): - parser.error("No input file provided and stdin is a terminal. Pipe JSON or pass a file.") - raw_data = json.load(sys.stdin) - except json.JSONDecodeError as exc: - print(f"Error: invalid JSON input -- {exc}", file=sys.stderr) - sys.exit(1) - except FileNotFoundError: - print(f"Error: file not found -- {args.data_file}", file=sys.stderr) - sys.exit(1) - except IOError as exc: - print(f"Error: could not read input -- {exc}", file=sys.stderr) - sys.exit(1) - - # -- Parse and validate -- - try: - incident, impact, signals, context = parse_incident_data(raw_data) - except ValueError as exc: - print(f"Error: {exc}", file=sys.stderr) - sys.exit(1) - - # -- Classify -- - severity_score = classify_severity(incident, impact, signals, context) - - # -- Build outputs -- - escalation = build_escalation_path(severity_score, signals, context) - action_plan = build_action_plan(severity_score, incident, impact, signals, context) - sla_impact = assess_sla_impact(severity_score, impact, signals) - - # -- Format and print -- - if args.output_format == "json": - output = format_json(incident, severity_score, escalation, action_plan, sla_impact) - elif args.output_format == "markdown": - output = format_markdown(incident, severity_score, escalation, action_plan, sla_impact) - else: - output = format_text(incident, severity_score, escalation, action_plan, sla_impact) - - print(output) - - # -- Exit code reflects severity -- - if severity_score.severity_level == SeverityLevel.SEV1: - sys.exit(2) - elif severity_score.severity_level == SeverityLevel.SEV2: - sys.exit(1) - else: - sys.exit(0) - - -if __name__ == "__main__": - main() diff --git a/engineering-team/skills/ms365-tenant-manager/SKILL.md b/engineering-team/skills/ms365-tenant-manager/SKILL.md index e24ebc33..7da2f3cb 100644 --- a/engineering-team/skills/ms365-tenant-manager/SKILL.md +++ b/engineering-team/skills/ms365-tenant-manager/SKILL.md @@ -43,6 +43,28 @@ $policy = @{ New-MgIdentityConditionalAccessPolicy -BodyParameter $policy ``` +### Bundled Python Generators + +Three stdlib tools generate the PowerShell artifacts deterministically — prefer them over hand-writing scripts for bulk/repeatable work. Sample input: `sample_input.json`; expected shape: `expected_output.json`. + +```bash +# Tenant setup: checklist + DNS records + license plan (JSON), or the full setup script +python3 scripts/tenant_setup.py --config sample_input.json --format json -o tenant_plan.json +python3 scripts/tenant_setup.py --config sample_input.json --format powershell -o tenant_setup.ps1 + +# User lifecycle: validate first, then generate creation/offboarding scripts +python3 scripts/user_management.py --domain acme.com --action validate --users users.json +python3 scripts/user_management.py --domain acme.com --action create --users users.json -o create_users.ps1 +python3 scripts/user_management.py --domain acme.com --action offboard --user-email jane@acme.com -o offboard.ps1 + +# Admin scripts: CA policy / security audit / bulk licensing +python3 scripts/powershell_generator.py --tenant-domain acme.com --task conditional-access --policy-config policy.json -o ca_policy.ps1 +python3 scripts/powershell_generator.py --tenant-domain acme.com --task security-audit -o audit.ps1 +python3 scripts/powershell_generator.py --tenant-domain acme.com --task bulk-license --users-csv users.csv --license-sku ENTERPRISEPACK -o licenses.ps1 +``` + +**Gate:** for user creation, run `--action validate` first and require every entry to report `"is_valid": true` before generating the creation script. Review every generated `.ps1` against the workflows below before running it in the tenant. + --- ## Workflows @@ -51,6 +73,8 @@ New-MgIdentityConditionalAccessPolicy -BodyParameter $policy **Step 1: Generate Setup Checklist** +Run `python3 scripts/tenant_setup.py --config tenant.json --format json` and work through `setup_checklist` phase by phase; `dns_records` feeds Step 2 and `license_recommendations` feeds the licensing workflow. + Confirm prerequisites before provisioning: - Global Admin account created and secured with MFA - Custom domain purchased and accessible for DNS edits diff --git a/engineering-team/skills/ms365-tenant-manager/scripts/powershell_generator.py b/engineering-team/skills/ms365-tenant-manager/scripts/powershell_generator.py index 9ea68742..29a5b6cc 100644 --- a/engineering-team/skills/ms365-tenant-manager/scripts/powershell_generator.py +++ b/engineering-team/skills/ms365-tenant-manager/scripts/powershell_generator.py @@ -428,3 +428,47 @@ Write-Host "Results saved to: $resultsPath" -ForegroundColor Cyan Disconnect-MgGraph """ return script + + +def main(): + """CLI entry point.""" + import argparse + import json + + parser = argparse.ArgumentParser( + description="Generate ready-to-run M365 admin PowerShell scripts (Graph SDK based)" + ) + parser.add_argument("--tenant-domain", required=True, help="Primary tenant domain (e.g. acme.com)") + parser.add_argument("--task", required=True, + choices=["conditional-access", "security-audit", "bulk-license"], + help="Which script to generate") + parser.add_argument("--policy-config", help="Policy config JSON file (conditional-access)") + parser.add_argument("--users-csv", help="Users CSV path baked into the script (bulk-license)") + parser.add_argument("--license-sku", help="License SKU (bulk-license)") + parser.add_argument("--output", "-o", help="Output file (default: stdout)") + args = parser.parse_args() + + generator = PowerShellScriptGenerator(args.tenant_domain) + + if args.task == "conditional-access": + policy = {} + if args.policy_config: + with open(args.policy_config, "r", encoding="utf-8") as f: + policy = json.load(f) + result = generator.generate_conditional_access_policy_script(policy) + elif args.task == "security-audit": + result = generator.generate_security_audit_script() + else: # bulk-license + if not (args.users_csv and args.license_sku): + parser.error("--users-csv and --license-sku are required for --task bulk-license") + result = generator.generate_bulk_license_assignment_script(args.users_csv, args.license_sku) + + if args.output: + with open(args.output, "w", encoding="utf-8") as f: + f.write(result) + else: + print(result) + + +if __name__ == "__main__": + main() diff --git a/engineering-team/skills/ms365-tenant-manager/scripts/tenant_setup.py b/engineering-team/skills/ms365-tenant-manager/scripts/tenant_setup.py index 1ffcd3a2..6523c1f8 100644 --- a/engineering-team/skills/ms365-tenant-manager/scripts/tenant_setup.py +++ b/engineering-team/skills/ms365-tenant-manager/scripts/tenant_setup.py @@ -445,3 +445,43 @@ Disconnect-MicrosoftTeams 'estimated_monthly_cost': round(estimated_monthly_cost, 2), 'estimated_annual_cost': round(estimated_monthly_cost * 12, 2) } + + +def main(): + """CLI entry point.""" + import argparse + import json + + parser = argparse.ArgumentParser( + description="Generate M365 tenant setup checklist, DNS records, license plan, and PowerShell setup script" + ) + parser.add_argument("--config", required=True, + help="Tenant config JSON file (top-level 'tenant_config' key or the config object itself)") + parser.add_argument("--format", choices=["json", "powershell"], default="json", + help="json = checklist + DNS + license plan; powershell = setup script") + parser.add_argument("--output", "-o", help="Output file (default: stdout)") + args = parser.parse_args() + + with open(args.config, "r", encoding="utf-8") as f: + data = json.load(f) + config = data.get("tenant_config", data) + manager = TenantSetupManager(config) + + if args.format == "powershell": + result = manager.generate_powershell_setup_script() + else: + result = json.dumps({ + "setup_checklist": manager.generate_setup_checklist(), + "dns_records": manager.generate_dns_records(), + "license_recommendations": manager.get_license_recommendations(), + }, indent=2) + + if args.output: + with open(args.output, "w", encoding="utf-8") as f: + f.write(result) + else: + print(result) + + +if __name__ == "__main__": + main() diff --git a/engineering-team/skills/ms365-tenant-manager/scripts/user_management.py b/engineering-team/skills/ms365-tenant-manager/scripts/user_management.py index 39864925..96577163 100644 --- a/engineering-team/skills/ms365-tenant-manager/scripts/user_management.py +++ b/engineering-team/skills/ms365-tenant-manager/scripts/user_management.py @@ -445,3 +445,56 @@ Disconnect-ExchangeOnline -Confirm:$false 'errors': errors, 'warnings': warnings } + + +def main(): + """CLI entry point.""" + import argparse + import json + + parser = argparse.ArgumentParser( + description="Generate M365 user lifecycle PowerShell scripts and license/group recommendations" + ) + parser.add_argument("--domain", required=True, help="Primary tenant domain (e.g. acme.com)") + parser.add_argument("--action", required=True, choices=["create", "offboard", "validate", "recommend"], + help="create = bulk user creation script; offboard = offboarding script; " + "validate = check user data; recommend = license + group recommendations") + parser.add_argument("--users", help="Users JSON file (list of user objects) for create/validate/recommend") + parser.add_argument("--user-email", help="User email for offboard action") + parser.add_argument("--output", "-o", help="Output file (default: stdout)") + args = parser.parse_args() + + manager = UserLifecycleManager(args.domain) + + if args.action == "offboard": + if not args.user_email: + parser.error("--user-email is required for --action offboard") + result = manager.generate_user_offboarding_script(args.user_email) + else: + if not args.users: + parser.error("--users is required for this action") + with open(args.users, "r", encoding="utf-8") as f: + users = json.load(f) + if isinstance(users, dict): + users = users.get("users", [users]) + if args.action == "create": + result = manager.generate_user_creation_script(users) + elif args.action == "validate": + result = json.dumps([manager.validate_user_data(u) for u in users], indent=2) + else: # recommend + result = json.dumps([{ + "user": u.get("email", u.get("first_name", "unknown")), + "licenses": manager.generate_license_assignment_recommendations( + u.get("role", "staff"), u.get("department", "general")), + "groups": manager.generate_group_membership_recommendations(u), + } for u in users], indent=2) + + if args.output: + with open(args.output, "w", encoding="utf-8") as f: + f.write(result) + else: + print(result) + + +if __name__ == "__main__": + main() diff --git a/engineering-team/skills/security-pen-testing/SKILL.md b/engineering-team/skills/security-pen-testing/SKILL.md index 458e1c01..504b877e 100644 --- a/engineering-team/skills/security-pen-testing/SKILL.md +++ b/engineering-team/skills/security-pen-testing/SKILL.md @@ -302,5 +302,5 @@ Automated security checks on every PR: secret scanning (TruffleHog), dependency |-------|-------------| | [senior-secops](../senior-secops/SKILL.md) | Defensive security operations — monitoring, incident response, SIEM configuration | | [senior-security](../senior-security/SKILL.md) | Security policy and governance — frameworks, risk registers, compliance | -| [dependency-auditor](../../engineering/dependency-auditor/SKILL.md) | Deep supply chain security — SBOMs, license compliance, transitive risk | +| [dependency-auditor](engineering/skills/dependency-auditor/SKILL.md) | Deep supply chain security — SBOMs, license compliance, transitive risk | | [code-reviewer](../code-reviewer/SKILL.md) | Code review practices — includes security review checklist | diff --git a/engineering-team/skills/senior-backend/SKILL.md b/engineering-team/skills/senior-backend/SKILL.md index 114a7154..591814b1 100644 --- a/engineering-team/skills/senior-backend/SKILL.md +++ b/engineering-team/skills/senior-backend/SKILL.md @@ -250,7 +250,7 @@ import { z } from 'zod'; const CreateUserSchema = z.object({ email: z.string().email().max(255), - name: "zstringmin1max100" + name: z.string().min(1).max(100), age: z.number().int().positive().optional() }); diff --git a/engineering-team/skills/senior-data-scientist/SKILL.md b/engineering-team/skills/senior-data-scientist/SKILL.md index 72c3b157..78e39a09 100644 --- a/engineering-team/skills/senior-data-scientist/SKILL.md +++ b/engineering-team/skills/senior-data-scientist/SKILL.md @@ -208,16 +208,10 @@ def diff_in_diff(df, outcome, treatment_col, post_col, controls=None): python -m pytest tests/ -v --cov=src/ python -m black src/ && python -m pylint src/ -# Training & evaluation -python scripts/train.py --config prod.yaml -python scripts/evaluate.py --model best.pth - -# Deployment -docker build -t service:v1 . -kubectl apply -f k8s/ -helm upgrade service ./charts/ - -# Monitoring & health -kubectl logs -f deployment/service -python scripts/health_check.py +# Bundled pipeline scaffolds (stdlib runners — extend the process() body with project logic) +python3 scripts/experiment_designer.py --input experiment_spec.json --output experiment_design.json +python3 scripts/feature_engineering_pipeline.py --input raw_features.json --output features.json +python3 scripts/model_evaluation_suite.py --input model_predictions.json --output evaluation.json +# Each prints a JSON run report ({status, processed_items, start/end_time}); any status other +# than "completed" means the stage failed — fix before moving to the next pipeline stage. ``` diff --git a/engineering-team/skills/senior-devops/SKILL.md b/engineering-team/skills/senior-devops/SKILL.md index 3a3887ac..50f496f7 100644 --- a/engineering-team/skills/senior-devops/SKILL.md +++ b/engineering-team/skills/senior-devops/SKILL.md @@ -20,8 +20,8 @@ python scripts/pipeline_generator.py ./app --platform=github --stages=build,test # Script 2: Terraform Scaffolder — generates and validates IaC modules for AWS/GCP/Azure python scripts/terraform_scaffolder.py ./infra --provider=aws --module=ecs-service --verbose -# Script 3: Deployment Manager — orchestrates container deployments with rollback support -python3 scripts/deployment_manager.py ./deploy --verbose --json +# Script 3: Deployment Manager — generates deployment manifests + runbooks with rollback support +python3 scripts/deployment_manager.py deploy --env=staging --image=app:1.2.3 --strategy=blue-green --verbose --json ``` ## Core Capabilities @@ -147,7 +147,7 @@ python scripts/terraform_scaffolder.py <target-path> --provider=aws|gcp|azure -- ### 3. Deployment Manager -Orchestrates deployments with blue/green or rolling strategies, health-check gates, and automatic rollback on failure. +Generates Kubernetes deployment manifests and ordered kubectl runbooks for blue/green or rolling strategies, with health-check gates before traffic switches and rollback runbooks. The tool writes manifests and prints the commands — it never applies them to a cluster itself, so every change gets a human review. **Example — Kubernetes blue/green deployment (blue-slot specific elements):** ```yaml diff --git a/engineering-team/skills/senior-devops/scripts/deployment_manager.py b/engineering-team/skills/senior-devops/scripts/deployment_manager.py index 5cb7f2b9..35b0f42b 100755 --- a/engineering-team/skills/senior-devops/scripts/deployment_manager.py +++ b/engineering-team/skills/senior-devops/scripts/deployment_manager.py @@ -1,114 +1,273 @@ #!/usr/bin/env python3 """ Deployment Manager -Automated tool for senior devops tasks +Generates blue/green or rolling Kubernetes deployment manifests plus an ordered +runbook of kubectl commands, and audits existing manifests. It never talks to a +cluster itself — review the manifests and run the printed commands yourself. + +Subcommands: + deploy --env --image [--strategy] [--health-check-url] — write manifests + runbook + rollback --env --to-version — write a rollback runbook + analyze --env — audit manifests on disk """ -import os -import sys -import json import argparse +import json +import re +import sys from pathlib import Path -from typing import Dict, List, Optional +from typing import Dict, List + +DEPLOYMENT_TEMPLATE = """apiVersion: apps/v1 +kind: Deployment +metadata: + name: {name} + namespace: {env} + labels: + app: {app}{slot_label} +spec: + replicas: {replicas} + selector: + matchLabels: + app: {app}{slot_label_indented} + template: + metadata: + labels: + app: {app}{slot_label_indented2} + spec: + containers: + - name: app + image: {image} + readinessProbe: + httpGet: + path: {health_path} + port: 8080 + initialDelaySeconds: 10 + periodSeconds: 5 + resources: + requests: + cpu: "250m" + memory: "256Mi" + limits: + cpu: "500m" + memory: "512Mi" +""" + +SERVICE_TEMPLATE = """apiVersion: v1 +kind: Service +metadata: + name: {app}-svc + namespace: {env} +spec: + selector: + app: {app}{slot_selector} + ports: + - port: 80 + targetPort: 8080 +""" + + +def app_name_from_image(image: str) -> str: + """ghcr.io/org/my-app:1.2.3 -> my-app""" + repo = image.rsplit(":", 1)[0] + return repo.rsplit("/", 1)[-1] or "app" + + +def render_deployment(app: str, env: str, image: str, replicas: int, + health_path: str, slot: str = "") -> str: + return DEPLOYMENT_TEMPLATE.format( + name=f"{app}-{slot}" if slot else app, + env=env, + app=app, + image=image, + replicas=replicas, + health_path=health_path, + slot_label=f"\n slot: {slot}" if slot else "", + slot_label_indented=f"\n slot: {slot}" if slot else "", + slot_label_indented2=f"\n slot: {slot}" if slot else "", + ) + + +def cmd_deploy(args) -> Dict: + app = args.app or app_name_from_image(args.image) + health_path = "/healthz" + if args.health_check_url: + match = re.search(r"https?://[^/]+(/.*)", args.health_check_url) + if match: + health_path = match.group(1) + + out_dir = Path(args.output_dir) / args.env + out_dir.mkdir(parents=True, exist_ok=True) + + written: List[str] = [] + runbook: List[str] = [] + + if args.strategy == "blue-green": + slot = args.slot + manifest = out_dir / f"deployment-{slot}.yaml" + manifest.write_text( + render_deployment(app, args.env, args.image, args.replicas, health_path, slot), + encoding="utf-8", + ) + written.append(str(manifest)) + + service = out_dir / "service.yaml" + if not service.exists(): + # service starts pointing at the OTHER slot; traffic switches in the runbook + other = "green" if slot == "blue" else "blue" + service.write_text(SERVICE_TEMPLATE.format( + app=app, env=args.env, slot_selector=f"\n slot: {other}"), encoding="utf-8") + written.append(str(service)) + + runbook = [ + f"kubectl apply -f {manifest}", + f"kubectl rollout status deployment/{app}-{slot} -n {args.env}", + ] + if args.health_check_url: + runbook.append(f"curl -sf {args.health_check_url} || echo 'HEALTH CHECK FAILED — do not switch traffic'") + runbook += [ + f"# switch traffic to the {slot} slot only after the checks above pass:", + f"kubectl patch service {app}-svc -n {args.env} " + f"-p '{{\"spec\":{{\"selector\":{{\"app\":\"{app}\",\"slot\":\"{slot}\"}}}}}}'", + ] + else: # rolling + manifest = out_dir / "deployment.yaml" + manifest.write_text( + render_deployment(app, args.env, args.image, args.replicas, health_path), + encoding="utf-8", + ) + written.append(str(manifest)) + + service = out_dir / "service.yaml" + if not service.exists(): + service.write_text(SERVICE_TEMPLATE.format( + app=app, env=args.env, slot_selector=""), encoding="utf-8") + written.append(str(service)) + + runbook = [ + f"kubectl apply -f {manifest}", + f"kubectl rollout status deployment/{app} -n {args.env}", + ] + if args.health_check_url: + runbook.append(f"curl -sf {args.health_check_url} || kubectl rollout undo deployment/{app} -n {args.env}") + + return { + "status": "success", + "action": "deploy", + "env": args.env, + "app": app, + "image": args.image, + "strategy": args.strategy, + "manifests_written": written, + "runbook": runbook, + } + + +def cmd_rollback(args) -> Dict: + app = args.app + runbook = [ + f"# Option 1 — pin the previous image version explicitly:", + f"kubectl set image deployment/{app} app={app}:{args.to_version} -n {args.env}", + f"kubectl rollout status deployment/{app} -n {args.env}", + f"# Option 2 — revert to the previous ReplicaSet:", + f"kubectl rollout undo deployment/{app} -n {args.env}", + f"# Verify:", + f"kubectl get pods -n {args.env} -l app={app}", + ] + return { + "status": "success", + "action": "rollback", + "env": args.env, + "app": app, + "to_version": args.to_version, + "runbook": runbook, + } + + +def cmd_analyze(args) -> Dict: + env_dir = Path(args.output_dir) / args.env + deployments = [] + if env_dir.is_dir(): + for manifest in sorted(env_dir.glob("deployment*.yaml")): + text = manifest.read_text(encoding="utf-8") + image = re.search(r"image:\s*(\S+)", text) + replicas = re.search(r"replicas:\s*(\d+)", text) + slot = re.search(r"slot:\s*(\S+)", text) + deployments.append({ + "manifest": str(manifest), + "image": image.group(1) if image else "unknown", + "replicas": int(replicas.group(1)) if replicas else 0, + "slot": slot.group(1) if slot else None, + }) + return { + "status": "success" if deployments else "empty", + "action": "analyze", + "env": args.env, + "manifest_dir": str(env_dir), + "deployments": deployments, + } + + +def build_parser() -> argparse.ArgumentParser: + parser = argparse.ArgumentParser( + description="Generate deployment manifests and runbooks (blue/green or rolling)." + ) + sub = parser.add_subparsers(dest="command", required=True) + + deploy = sub.add_parser("deploy", help="Generate deployment manifests + runbook") + deploy.add_argument("--env", required=True, help="Target environment / namespace") + deploy.add_argument("--image", required=True, help="Container image (repo:tag)") + deploy.add_argument("--strategy", default="rolling", choices=["blue-green", "rolling"]) + deploy.add_argument("--health-check-url", help="Health check URL gating traffic switch") + deploy.add_argument("--app", help="App name (default: derived from image)") + deploy.add_argument("--slot", default="blue", choices=["blue", "green"], + help="Slot to deploy into (blue-green only)") + deploy.add_argument("--replicas", type=int, default=3) + deploy.add_argument("--output-dir", default="./deploy", help="Manifest output directory") + + rollback = sub.add_parser("rollback", help="Generate a rollback runbook") + rollback.add_argument("--env", required=True) + rollback.add_argument("--to-version", required=True, help="Version to roll back to") + rollback.add_argument("--app", default="app", help="App / deployment name") + + analyze = sub.add_parser("analyze", help="Audit deployment manifests on disk") + analyze.add_argument("--env", required=True) + analyze.add_argument("--output-dir", default="./deploy", help="Manifest directory") + + for p in (deploy, rollback, analyze): + p.add_argument("--verbose", "-v", action="store_true", help="Enable verbose output") + p.add_argument("--json", action="store_true", help="Output results as JSON") + p.add_argument("--output", "-o", help="Write JSON results to this file") + return parser -class DeploymentManager: - """Main class for deployment manager functionality""" - - def __init__(self, target_path: str, verbose: bool = False): - self.target_path = Path(target_path) - self.verbose = verbose - self.results = {} - - def run(self) -> Dict: - """Execute the main functionality""" - print(f"🚀 Running {self.__class__.__name__}...") - print(f"📁 Target: {self.target_path}") - - try: - self.validate_target() - self.analyze() - self.generate_report() - - print("✅ Completed successfully!") - return self.results - - except Exception as e: - print(f"❌ Error: {e}") - sys.exit(1) - - def validate_target(self): - """Validate the target path exists and is accessible""" - if not self.target_path.exists(): - raise ValueError(f"Target path does not exist: {self.target_path}") - - if self.verbose: - print(f"✓ Target validated: {self.target_path}") - - def analyze(self): - """Perform the main analysis or operation""" - if self.verbose: - print("📊 Analyzing...") - - # Main logic here - self.results['status'] = 'success' - self.results['target'] = str(self.target_path) - self.results['findings'] = [] - - # Add analysis results - if self.verbose: - print(f"✓ Analysis complete: {len(self.results.get('findings', []))} findings") - - def generate_report(self): - """Generate and display the report""" - print("\n" + "="*50) - print("REPORT") - print("="*50) - print(f"Target: {self.results.get('target')}") - print(f"Status: {self.results.get('status')}") - print(f"Findings: {len(self.results.get('findings', []))}") - print("="*50 + "\n") def main(): - """Main entry point""" - parser = argparse.ArgumentParser( - description="Deployment Manager" - ) - parser.add_argument( - 'target', - help='Target path to analyze or process' - ) - parser.add_argument( - '--verbose', '-v', - action='store_true', - help='Enable verbose output' - ) - parser.add_argument( - '--json', - action='store_true', - help='Output results as JSON' - ) - parser.add_argument( - '--output', '-o', - help='Output file path' - ) - - args = parser.parse_args() - - tool = DeploymentManager( - args.target, - verbose=args.verbose - ) - - results = tool.run() - - if args.json: + # support the documented `--analyze --env=...` flag form as an alias + argv = ["analyze" if a == "--analyze" else a for a in sys.argv[1:]] + args = build_parser().parse_args(argv) + + handlers = {"deploy": cmd_deploy, "rollback": cmd_rollback, "analyze": cmd_analyze} + results = handlers[args.command](args) + + print(f"🚀 {results['action']} ({results['env']}) — status: {results['status']}") + for manifest in results.get("manifests_written", []): + print(f"✓ Wrote {manifest}") + for dep in results.get("deployments", []): + slot = f" slot={dep['slot']}" if dep["slot"] else "" + print(f" - {dep['manifest']}: image={dep['image']} replicas={dep['replicas']}{slot}") + if results.get("runbook"): + print("\nRunbook — review, then execute in order:") + for step in results["runbook"]: + print(f" {step}") + + if args.json or args.output: output = json.dumps(results, indent=2) if args.output: - with open(args.output, 'w') as f: - f.write(output) + Path(args.output).write_text(output, encoding="utf-8") print(f"Results written to {args.output}") else: print(output) -if __name__ == '__main__': + +if __name__ == "__main__": main() diff --git a/engineering-team/skills/senior-devops/scripts/pipeline_generator.py b/engineering-team/skills/senior-devops/scripts/pipeline_generator.py index a5586ca1..9888784a 100755 --- a/engineering-team/skills/senior-devops/scripts/pipeline_generator.py +++ b/engineering-team/skills/senior-devops/scripts/pipeline_generator.py @@ -1,114 +1,238 @@ #!/usr/bin/env python3 """ Pipeline Generator -Automated tool for senior devops tasks +Scaffolds CI/CD pipeline configurations for GitHub Actions or CircleCI with +build, test, security, and deploy stages. Detects node/python/go projects to +pick sensible default commands. """ -import os -import sys -import json import argparse +import json +import sys from pathlib import Path -from typing import Dict, List, Optional +from typing import Dict, List + +VALID_STAGES = ["build", "test", "security", "deploy"] + + +def detect_runtime(project: Path) -> str: + if (project / "package.json").exists(): + return "node" + if (project / "pyproject.toml").exists() or (project / "requirements.txt").exists(): + return "python" + if (project / "go.mod").exists(): + return "go" + return "generic" + + +RUNTIME_COMMANDS: Dict[str, Dict[str, List[str]]] = { + "node": { + "setup": ["npm ci"], + "build": ["npm run build --if-present"], + "test": ["npm run lint --if-present", "npm test"], + }, + "python": { + "setup": ["pip install -r requirements.txt"], + "build": ["python -m compileall ."], + "test": ["python -m ruff check .", "python -m pytest"], + }, + "go": { + "setup": ["go mod download"], + "build": ["go build ./..."], + "test": ["go vet ./...", "go test ./..."], + }, + "generic": { + "setup": ["echo 'add setup commands here'"], + "build": ["echo 'add build commands here'"], + "test": ["echo 'add test commands here'"], + }, +} + +GITHUB_SETUP_STEPS = { + "node": """ - uses: actions/setup-node@v4 + with: + node-version: '20' + cache: 'npm'""", + "python": """ - uses: actions/setup-python@v5 + with: + python-version: '3.12' + cache: 'pip'""", + "go": """ - uses: actions/setup-go@v5 + with: + go-version: '1.22'""", + "generic": "", +} + +CIRCLECI_IMAGES = { + "node": "cimg/node:20.11", + "python": "cimg/python:3.12", + "go": "cimg/go:1.22", + "generic": "cimg/base:current", +} + + +def github_job(name: str, runtime: str, commands: List[str], needs: List[str], + extra: str = "") -> str: + lines = [f" {name}:"] + if needs: + lines.append(f" needs: [{', '.join(needs)}]") + if name == "deploy": + lines.append(" if: github.ref == 'refs/heads/main'") + lines.append(" runs-on: ubuntu-latest") + lines.append(" steps:") + lines.append(" - uses: actions/checkout@v4") + setup = GITHUB_SETUP_STEPS[runtime] + if setup and name in ("build", "test"): + lines.append(setup) + for cmd in RUNTIME_COMMANDS[runtime]["setup"]: + lines.append(f" - run: {cmd}") + for cmd in commands: + lines.append(f" - run: {cmd}") + if extra: + lines.append(extra) + return "\n".join(lines) + + +def generate_github(stages: List[str], runtime: str) -> str: + jobs = [] + prev: List[str] = [] + for stage in stages: + if stage == "build": + jobs.append(github_job("build", runtime, RUNTIME_COMMANDS[runtime]["build"], prev)) + elif stage == "test": + jobs.append(github_job("test", runtime, RUNTIME_COMMANDS[runtime]["test"], prev)) + elif stage == "security": + extra = """ - name: Run Trivy filesystem scan + uses: aquasecurity/trivy-action@master + with: + scan-type: 'fs' + scan-ref: '.' + severity: 'CRITICAL,HIGH' + exit-code: '1'""" + jobs.append(github_job("security", runtime, [], prev, extra=extra)) + elif stage == "deploy": + extra = """ - name: Build and push image + uses: docker/build-push-action@v5 + with: + push: true + tags: ghcr.io/${{ github.repository }}:${{ github.sha }} + - name: Deploy + run: echo 'replace with your deploy command (e.g. aws ecs update-service / kubectl apply)'""" + jobs.append(github_job("deploy", runtime, [], prev, extra=extra)) + prev = [stage] + + return f"""name: CI/CD Pipeline +on: + push: + branches: [main, develop] + pull_request: + branches: [main] + +jobs: +{chr(10).join(jobs)} +""" + + +def generate_circleci(stages: List[str], runtime: str) -> str: + image = CIRCLECI_IMAGES[runtime] + job_blocks = [] + workflow_jobs = [] + prev = None + for stage in stages: + if stage == "security": + commands = ["echo 'add security scanner here (e.g. trivy fs .)'"] + elif stage == "deploy": + commands = ["echo 'replace with your deploy command'"] + else: + commands = RUNTIME_COMMANDS[runtime]["setup"] + RUNTIME_COMMANDS[runtime][stage] + steps = "\n".join(f" - run: {cmd}" for cmd in commands) + job_blocks.append(f""" {stage}: + docker: + - image: {image} + steps: + - checkout +{steps}""") + if prev: + workflow_jobs.append(f""" - {stage}: + requires: [{prev}]""") + else: + workflow_jobs.append(f" - {stage}") + prev = stage + + return f"""version: 2.1 + +jobs: +{chr(10).join(job_blocks)} + +workflows: + ci: + jobs: +{chr(10).join(workflow_jobs)} +""" -class PipelineGenerator: - """Main class for pipeline generator functionality""" - - def __init__(self, target_path: str, verbose: bool = False): - self.target_path = Path(target_path) - self.verbose = verbose - self.results = {} - - def run(self) -> Dict: - """Execute the main functionality""" - print(f"🚀 Running {self.__class__.__name__}...") - print(f"📁 Target: {self.target_path}") - - try: - self.validate_target() - self.analyze() - self.generate_report() - - print("✅ Completed successfully!") - return self.results - - except Exception as e: - print(f"❌ Error: {e}") - sys.exit(1) - - def validate_target(self): - """Validate the target path exists and is accessible""" - if not self.target_path.exists(): - raise ValueError(f"Target path does not exist: {self.target_path}") - - if self.verbose: - print(f"✓ Target validated: {self.target_path}") - - def analyze(self): - """Perform the main analysis or operation""" - if self.verbose: - print("📊 Analyzing...") - - # Main logic here - self.results['status'] = 'success' - self.results['target'] = str(self.target_path) - self.results['findings'] = [] - - # Add analysis results - if self.verbose: - print(f"✓ Analysis complete: {len(self.results.get('findings', []))} findings") - - def generate_report(self): - """Generate and display the report""" - print("\n" + "="*50) - print("REPORT") - print("="*50) - print(f"Target: {self.results.get('target')}") - print(f"Status: {self.results.get('status')}") - print(f"Findings: {len(self.results.get('findings', []))}") - print("="*50 + "\n") def main(): - """Main entry point""" parser = argparse.ArgumentParser( - description="Pipeline Generator" + description="Generate a CI/CD pipeline config for GitHub Actions or CircleCI." ) - parser.add_argument( - 'target', - help='Target path to analyze or process' - ) - parser.add_argument( - '--verbose', '-v', - action='store_true', - help='Enable verbose output' - ) - parser.add_argument( - '--json', - action='store_true', - help='Output results as JSON' - ) - parser.add_argument( - '--output', '-o', - help='Output file path' - ) - + parser.add_argument("target", help="Project path to scaffold the pipeline into") + parser.add_argument("--platform", default="github", choices=["github", "circleci"], + help="CI platform (default: github)") + parser.add_argument("--stages", default="build,test,deploy", + help=f"Comma-separated stages from: {','.join(VALID_STAGES)}") + parser.add_argument("--force", action="store_true", help="Overwrite an existing config") + parser.add_argument("--verbose", "-v", action="store_true", help="Enable verbose output") + parser.add_argument("--json", action="store_true", help="Output results as JSON") + parser.add_argument("--output", "-o", help="Write JSON results to this file") args = parser.parse_args() - - tool = PipelineGenerator( - args.target, - verbose=args.verbose - ) - - results = tool.run() - - if args.json: + + project = Path(args.target) + if not project.is_dir(): + print(f"❌ Error: target path is not a directory: {project}", file=sys.stderr) + sys.exit(1) + + stages = [s.strip() for s in args.stages.split(",") if s.strip()] + invalid = [s for s in stages if s not in VALID_STAGES] + if invalid or not stages: + print(f"❌ Error: invalid stages {invalid or '(none)'}; " + f"choose from {','.join(VALID_STAGES)}", file=sys.stderr) + sys.exit(1) + + runtime = detect_runtime(project) + if args.verbose: + print(f"📊 Detected runtime: {runtime}") + + if args.platform == "github": + config = generate_github(stages, runtime) + config_path = project / ".github" / "workflows" / "ci.yml" + else: + config = generate_circleci(stages, runtime) + config_path = project / ".circleci" / "config.yml" + + if config_path.exists() and not args.force: + print(f"❌ Error: {config_path} already exists (use --force to overwrite)", file=sys.stderr) + sys.exit(1) + + config_path.parent.mkdir(parents=True, exist_ok=True) + config_path.write_text(config, encoding="utf-8") + print(f"✅ Pipeline written: {config_path} (platform={args.platform}, " + f"stages={','.join(stages)}, runtime={runtime})") + + results = { + "status": "success", + "platform": args.platform, + "stages": stages, + "runtime": runtime, + "config_path": str(config_path), + } + if args.json or args.output: output = json.dumps(results, indent=2) if args.output: - with open(args.output, 'w') as f: - f.write(output) + Path(args.output).write_text(output, encoding="utf-8") print(f"Results written to {args.output}") else: print(output) -if __name__ == '__main__': + +if __name__ == "__main__": main() diff --git a/engineering-team/skills/senior-devops/scripts/terraform_scaffolder.py b/engineering-team/skills/senior-devops/scripts/terraform_scaffolder.py index e27b5e35..77bd38c8 100755 --- a/engineering-team/skills/senior-devops/scripts/terraform_scaffolder.py +++ b/engineering-team/skills/senior-devops/scripts/terraform_scaffolder.py @@ -1,114 +1,490 @@ #!/usr/bin/env python3 """ Terraform Scaffolder -Automated tool for senior devops tasks +Generates provider-specific Terraform module skeletons (main.tf, variables.tf, +outputs.tf, versions.tf) and optionally runs `terraform fmt`/`validate` when the +terraform binary is available. """ -import os -import sys -import json import argparse +import json +import shutil +import subprocess +import sys from pathlib import Path -from typing import Dict, List, Optional +from typing import Dict + +# module -> required provider +MODULE_PROVIDERS = { + "ecs-service": "aws", + "gke-deployment": "gcp", + "aks-service": "azure", +} + +ECS_MAIN = '''resource "aws_ecs_task_definition" "app" { + family = var.service_name + requires_compatibilities = ["FARGATE"] + network_mode = "awsvpc" + cpu = var.cpu + memory = var.memory + + container_definitions = jsonencode([{ + name = var.service_name + image = var.container_image + essential = true + portMappings = [{ + containerPort = var.container_port + protocol = "tcp" + }] + environment = [for k, v in var.env_vars : { name = k, value = v }] + logConfiguration = { + logDriver = "awslogs" + options = { + awslogs-group = "/ecs/${var.service_name}" + awslogs-region = var.aws_region + awslogs-stream-prefix = "ecs" + } + } + }]) +} + +resource "aws_ecs_service" "app" { + name = var.service_name + cluster = var.cluster_id + task_definition = aws_ecs_task_definition.app.arn + desired_count = var.desired_count + launch_type = "FARGATE" + + network_configuration { + subnets = var.private_subnet_ids + security_groups = var.security_group_ids + assign_public_ip = false + } +} +''' + +ECS_VARIABLES = '''variable "service_name" { + description = "Name of the ECS service" + type = string +} + +variable "cluster_id" { + description = "ECS cluster ID" + type = string +} + +variable "container_image" { + description = "Container image (repo:tag)" + type = string +} + +variable "container_port" { + description = "Container port" + type = number + default = 8080 +} + +variable "cpu" { + description = "Fargate task CPU units" + type = number + default = 256 +} + +variable "memory" { + description = "Fargate task memory (MiB)" + type = number + default = 512 +} + +variable "desired_count" { + description = "Desired task count" + type = number + default = 2 +} + +variable "aws_region" { + description = "AWS region" + type = string +} + +variable "private_subnet_ids" { + description = "Private subnet IDs for the service" + type = list(string) +} + +variable "security_group_ids" { + description = "Security group IDs for the service" + type = list(string) +} + +variable "env_vars" { + description = "Environment variables for the container" + type = map(string) + default = {} +} +''' + +ECS_OUTPUTS = '''output "service_name" { + description = "Name of the ECS service" + value = aws_ecs_service.app.name +} + +output "task_definition_arn" { + description = "ARN of the task definition" + value = aws_ecs_task_definition.app.arn +} +''' + +GKE_MAIN = '''resource "kubernetes_deployment" "app" { + metadata { + name = var.app_name + namespace = var.namespace + labels = { app = var.app_name } + } + + spec { + replicas = var.replicas + + selector { + match_labels = { app = var.app_name } + } + + template { + metadata { + labels = { app = var.app_name } + } + + spec { + container { + name = var.app_name + image = var.container_image + + port { + container_port = var.container_port + } + + readiness_probe { + http_get { + path = var.health_check_path + port = var.container_port + } + initial_delay_seconds = 10 + period_seconds = 5 + } + + resources { + requests = { + cpu = var.cpu_request + memory = var.memory_request + } + limits = { + cpu = var.cpu_limit + memory = var.memory_limit + } + } + } + } + } + } +} + +resource "kubernetes_service" "app" { + metadata { + name = var.app_name + namespace = var.namespace + } + + spec { + selector = { app = var.app_name } + + port { + port = 80 + target_port = var.container_port + } + + type = "ClusterIP" + } +} +''' + +GKE_VARIABLES = '''variable "app_name" { + description = "Application name" + type = string +} + +variable "namespace" { + description = "Kubernetes namespace" + type = string + default = "default" +} + +variable "container_image" { + description = "Container image (repo:tag)" + type = string +} + +variable "container_port" { + description = "Container port" + type = number + default = 8080 +} + +variable "replicas" { + description = "Number of replicas" + type = number + default = 3 +} + +variable "health_check_path" { + description = "Readiness probe path" + type = string + default = "/healthz" +} + +variable "cpu_request" { + description = "CPU request" + type = string + default = "250m" +} + +variable "memory_request" { + description = "Memory request" + type = string + default = "256Mi" +} + +variable "cpu_limit" { + description = "CPU limit" + type = string + default = "500m" +} + +variable "memory_limit" { + description = "Memory limit" + type = string + default = "512Mi" +} +''' + +GKE_OUTPUTS = '''output "deployment_name" { + description = "Name of the deployment" + value = kubernetes_deployment.app.metadata[0].name +} + +output "service_name" { + description = "Name of the service" + value = kubernetes_service.app.metadata[0].name +} +''' + +AKS_MAIN = '''resource "azurerm_kubernetes_cluster" "this" { + name = var.cluster_name + location = var.location + resource_group_name = var.resource_group_name + dns_prefix = var.cluster_name + + default_node_pool { + name = "default" + node_count = var.node_count + vm_size = var.vm_size + } + + identity { + type = "SystemAssigned" + } + + tags = var.tags +} +''' + +AKS_VARIABLES = '''variable "cluster_name" { + description = "AKS cluster name" + type = string +} + +variable "location" { + description = "Azure region" + type = string +} + +variable "resource_group_name" { + description = "Resource group name" + type = string +} + +variable "node_count" { + description = "Default node pool size" + type = number + default = 3 +} + +variable "vm_size" { + description = "Node VM size" + type = string + default = "Standard_D2s_v5" +} + +variable "tags" { + description = "Resource tags" + type = map(string) + default = {} +} +''' + +AKS_OUTPUTS = '''output "cluster_name" { + description = "AKS cluster name" + value = azurerm_kubernetes_cluster.this.name +} + +output "kube_config" { + description = "Raw kube config for the cluster" + value = azurerm_kubernetes_cluster.this.kube_config_raw + sensitive = true +} +''' + +VERSIONS = { + "aws": '''terraform { + required_version = ">= 1.5" + required_providers { + aws = { + source = "hashicorp/aws" + version = ">= 5.0" + } + } +} +''', + "gcp": '''terraform { + required_version = ">= 1.5" + required_providers { + kubernetes = { + source = "hashicorp/kubernetes" + version = ">= 2.0" + } + } +} +''', + "azure": '''terraform { + required_version = ">= 1.5" + required_providers { + azurerm = { + source = "hashicorp/azurerm" + version = ">= 3.0" + } + } +} +''', +} + +MODULE_FILES: Dict[str, Dict[str, str]] = { + "ecs-service": {"main.tf": ECS_MAIN, "variables.tf": ECS_VARIABLES, "outputs.tf": ECS_OUTPUTS}, + "gke-deployment": {"main.tf": GKE_MAIN, "variables.tf": GKE_VARIABLES, "outputs.tf": GKE_OUTPUTS}, + "aks-service": {"main.tf": AKS_MAIN, "variables.tf": AKS_VARIABLES, "outputs.tf": AKS_OUTPUTS}, +} + + +def run_terraform_checks(module_dir: Path, verbose: bool) -> Dict: + """Run terraform fmt/validate when the binary exists; otherwise skip.""" + checks = {"terraform_available": False, "fmt": "skipped", "validate": "skipped"} + if not shutil.which("terraform"): + if verbose: + print("ℹ️ terraform binary not found — skipping fmt/validate") + return checks + + checks["terraform_available"] = True + fmt = subprocess.run( + ["terraform", "fmt", "-recursive", str(module_dir)], + capture_output=True, text=True, + ) + checks["fmt"] = "passed" if fmt.returncode == 0 else f"failed: {fmt.stderr.strip()}" + + init = subprocess.run( + ["terraform", f"-chdir={module_dir}", "init", "-backend=false", "-input=false"], + capture_output=True, text=True, + ) + if init.returncode == 0: + validate = subprocess.run( + ["terraform", f"-chdir={module_dir}", "validate"], + capture_output=True, text=True, + ) + checks["validate"] = "passed" if validate.returncode == 0 else f"failed: {validate.stderr.strip()}" + else: + checks["validate"] = f"init failed: {init.stderr.strip()}" + return checks + + +def scaffold(target: Path, provider: str, module: str, force: bool, verbose: bool) -> Dict: + expected_provider = MODULE_PROVIDERS[module] + if provider != expected_provider: + raise ValueError( + f"Module '{module}' targets provider '{expected_provider}', not '{provider}'. " + f"Valid pairs: " + ", ".join(f"{m} → {p}" for m, p in MODULE_PROVIDERS.items()) + ) + + module_dir = target / "modules" / module + module_dir.mkdir(parents=True, exist_ok=True) + + files = dict(MODULE_FILES[module]) + files["versions.tf"] = VERSIONS[provider] + + written, skipped = [], [] + for name, content in sorted(files.items()): + path = module_dir / name + if path.exists() and not force: + skipped.append(str(path)) + if verbose: + print(f"⏭️ Exists, skipping (use --force to overwrite): {path}") + continue + path.write_text(content, encoding="utf-8") + written.append(str(path)) + if verbose: + print(f"✓ Wrote {path}") + + return { + "status": "success", + "provider": provider, + "module": module, + "module_dir": str(module_dir), + "files_written": written, + "files_skipped": skipped, + "checks": run_terraform_checks(module_dir, verbose), + } -class TerraformScaffolder: - """Main class for terraform scaffolder functionality""" - - def __init__(self, target_path: str, verbose: bool = False): - self.target_path = Path(target_path) - self.verbose = verbose - self.results = {} - - def run(self) -> Dict: - """Execute the main functionality""" - print(f"🚀 Running {self.__class__.__name__}...") - print(f"📁 Target: {self.target_path}") - - try: - self.validate_target() - self.analyze() - self.generate_report() - - print("✅ Completed successfully!") - return self.results - - except Exception as e: - print(f"❌ Error: {e}") - sys.exit(1) - - def validate_target(self): - """Validate the target path exists and is accessible""" - if not self.target_path.exists(): - raise ValueError(f"Target path does not exist: {self.target_path}") - - if self.verbose: - print(f"✓ Target validated: {self.target_path}") - - def analyze(self): - """Perform the main analysis or operation""" - if self.verbose: - print("📊 Analyzing...") - - # Main logic here - self.results['status'] = 'success' - self.results['target'] = str(self.target_path) - self.results['findings'] = [] - - # Add analysis results - if self.verbose: - print(f"✓ Analysis complete: {len(self.results.get('findings', []))} findings") - - def generate_report(self): - """Generate and display the report""" - print("\n" + "="*50) - print("REPORT") - print("="*50) - print(f"Target: {self.results.get('target')}") - print(f"Status: {self.results.get('status')}") - print(f"Findings: {len(self.results.get('findings', []))}") - print("="*50 + "\n") def main(): - """Main entry point""" parser = argparse.ArgumentParser( - description="Terraform Scaffolder" + description="Generate a Terraform module skeleton for AWS/GCP/Azure." ) - parser.add_argument( - 'target', - help='Target path to analyze or process' - ) - parser.add_argument( - '--verbose', '-v', - action='store_true', - help='Enable verbose output' - ) - parser.add_argument( - '--json', - action='store_true', - help='Output results as JSON' - ) - parser.add_argument( - '--output', '-o', - help='Output file path' - ) - + parser.add_argument("target", help="Target infrastructure directory (e.g. ./infra)") + parser.add_argument("--provider", required=True, choices=["aws", "gcp", "azure"], + help="Cloud provider") + parser.add_argument("--module", required=True, choices=sorted(MODULE_PROVIDERS), + help="Module template to scaffold") + parser.add_argument("--force", action="store_true", + help="Overwrite existing files") + parser.add_argument("--verbose", "-v", action="store_true", help="Enable verbose output") + parser.add_argument("--json", action="store_true", help="Output results as JSON") + parser.add_argument("--output", "-o", help="Write JSON results to this file") args = parser.parse_args() - - tool = TerraformScaffolder( - args.target, - verbose=args.verbose - ) - - results = tool.run() - - if args.json: + + print(f"🚀 Scaffolding {args.provider}/{args.module} module under {args.target} ...") + try: + results = scaffold(Path(args.target), args.provider, args.module, args.force, args.verbose) + except ValueError as exc: + print(f"❌ Error: {exc}", file=sys.stderr) + sys.exit(1) + + print(f"✅ Module ready: {results['module_dir']} " + f"({len(results['files_written'])} written, {len(results['files_skipped'])} skipped)") + + if args.json or args.output: output = json.dumps(results, indent=2) if args.output: - with open(args.output, 'w') as f: - f.write(output) + Path(args.output).write_text(output, encoding="utf-8") print(f"Results written to {args.output}") else: print(output) -if __name__ == '__main__': + +if __name__ == "__main__": main() diff --git a/engineering-team/skills/senior-frontend/SKILL.md b/engineering-team/skills/senior-frontend/SKILL.md index 9e322102..3ee4b8e1 100644 --- a/engineering-team/skills/senior-frontend/SKILL.md +++ b/engineering-team/skills/senior-frontend/SKILL.md @@ -422,7 +422,7 @@ test('dialog is accessible', async () => { // next.config.js const nextConfig = { images: { - remotePatterns: [{ hostname: "cdnexamplecom" }], + remotePatterns: [{ protocol: 'https', hostname: 'cdn.example.com' }], formats: ['image/avif', 'image/webp'], }, experimental: { diff --git a/engineering-team/skills/senior-fullstack/SKILL.md b/engineering-team/skills/senior-fullstack/SKILL.md index 10a8d7d6..b7b6cd51 100644 --- a/engineering-team/skills/senior-fullstack/SKILL.md +++ b/engineering-team/skills/senior-fullstack/SKILL.md @@ -218,7 +218,7 @@ npm install cp .env.example .env.local # 5. Run quality check -python ../scripts/code_quality_analyzer.py . +python scripts/code_quality_analyzer.py . # 6. Start development npm run dev diff --git a/engineering-team/skills/senior-prompt-engineer/SKILL.md b/engineering-team/skills/senior-prompt-engineer/SKILL.md index fa4a4a11..4fdd9b32 100644 --- a/engineering-team/skills/senior-prompt-engineer/SKILL.md +++ b/engineering-team/skills/senior-prompt-engineer/SKILL.md @@ -1,355 +1,139 @@ --- name: "senior-prompt-engineer" -description: This skill should be used when the user asks to "optimize prompts", "design prompt templates", "evaluate LLM outputs", "build agentic systems", "implement RAG", "create few-shot examples", "analyze token usage", or "design AI workflows". Use for prompt engineering patterns, LLM evaluation frameworks, agent architectures, and structured output design. +description: Use when the user asks to optimize prompts, design prompt templates, evaluate LLM outputs with an eval set, measure RAG retrieval quality, validate agent/tool configurations, analyze token usage, or design structured-output contracts. Covers eval-driven prompt iteration, RAG metrics (relevance, faithfulness, coverage), agent workflow validation, and token/cost budgeting — all model-agnostic, with three stdlib Python tools. --- # Senior Prompt Engineer -Prompt engineering patterns, LLM evaluation frameworks, and agentic system design. +Eval-driven prompt engineering, RAG quality measurement, and agent workflow validation. Everything here is **model-agnostic by design**: techniques are framed by what they do, not by which model generation they were observed on, and the tools never hardcode model IDs or pricing — you supply your provider's current rates when you want dollar figures. -## Table of Contents +## Operating Rules -- [Quick Start](#quick-start) -- [Tools Overview](#tools-overview) - - [Prompt Optimizer](#1-prompt-optimizer) - - [RAG Evaluator](#2-rag-evaluator) - - [Agent Orchestrator](#3-agent-orchestrator) -- [Prompt Engineering Workflows](#prompt-engineering-workflows) - - [Prompt Optimization Workflow](#prompt-optimization-workflow) - - [Few-Shot Example Design](#few-shot-example-design-workflow) - - [Structured Output Design](#structured-output-design-workflow) -- [Reference Documentation](#reference-documentation) -- [Common Patterns Quick Reference](#common-patterns-quick-reference) +1. **Never change a prompt without a baseline.** Capture metrics first (`--analyze --output baseline.json`), then compare every iteration against it. +2. **Eval set before optimization.** 10–20 representative cases with expected outputs minimum. If the user has no eval set, build one with them before touching the prompt — optimizing against vibes is the #1 failure mode. +3. **Prefer platform features over prompt hacks.** If the provider offers native structured outputs / JSON schema enforcement, tool-use APIs, or prompt caching, use those instead of "respond ONLY with JSON" incantations. Prompt-level format enforcement is the fallback, not the default. +4. **Current-generation models need less scaffolding.** Don't add chain-of-thought boilerplate, role framing, or few-shot examples reflexively — frontier models often do worse with redundant scaffolding. Add each element only when the eval set shows it helps. +5. **Cost numbers are always user-supplied.** Look up the provider's current per-Mtok pricing and pass it via `--price-per-mtok` (never trust a cached price table — including any you remember). ---- +## Tools (exact CLIs, all stdlib) -## Quick Start +### 1. Prompt Optimizer — `scripts/prompt_optimizer.py` + +Static analysis: token estimate, clarity/structure scores (0–100), ambiguity + redundancy detection, few-shot example extraction. ```bash -# Analyze and optimize a prompt file -python scripts/prompt_optimizer.py prompts/my_prompt.txt --analyze +# Full analysis (human-readable report) +python3 scripts/prompt_optimizer.py prompt.txt --analyze -# Evaluate RAG retrieval quality -python scripts/rag_evaluator.py --contexts contexts.json --questions questions.json +# Save machine-readable baseline for later comparison +python3 scripts/prompt_optimizer.py prompt.txt --analyze --json --output baseline.json -# Visualize agent workflow from definition -python scripts/agent_orchestrator.py agent_config.yaml --visualize +# Token estimate; cost only if you supply your provider's current rate +python3 scripts/prompt_optimizer.py prompt.txt --tokens --model claude --price-per-mtok 3.00 + +# Whitespace/redundancy-trimmed version +python3 scripts/prompt_optimizer.py prompt.txt --optimize --output optimized.txt + +# Extract Input/Output few-shot pairs to JSON +python3 scripts/prompt_optimizer.py prompt.txt --extract-examples --output examples.json + +# Compare a revision against the saved baseline +python3 scripts/prompt_optimizer.py optimized.txt --analyze --compare baseline.json ``` ---- +`--model` accepts any string; only the tokenizer family is inferred (names containing "claude" → 3.5 chars/token, otherwise 4.0). Exit 0 on success, 1 on missing file. -## Tools Overview +### 2. RAG Evaluator — `scripts/rag_evaluator.py` -### 1. Prompt Optimizer +Measures retrieval and grounding quality from two JSON files (formats printed in `--help`). -Analyzes prompts for token efficiency, clarity, and structure. Generates optimized versions. - -**Input:** Prompt text file or string -**Output:** Analysis report with optimization suggestions - -**Usage:** ```bash -# Analyze a prompt file -python scripts/prompt_optimizer.py prompt.txt --analyze - -# Output: -# Token count: 847 -# Estimated cost: $0.0025 (GPT-4) -# Clarity score: 72/100 -# Issues found: -# - Ambiguous instruction at line 3 -# - Missing output format specification -# - Redundant context (lines 12-15 repeat lines 5-8) -# Suggestions: -# 1. Add explicit output format: "Respond in JSON with keys: ..." -# 2. Remove redundant context to save 89 tokens -# 3. Clarify "analyze" -> "list the top 3 issues with severity ratings" - -# Generate optimized version -python scripts/prompt_optimizer.py prompt.txt --optimize --output optimized.txt - -# Count tokens for cost estimation -python scripts/prompt_optimizer.py prompt.txt --tokens --model gpt-4 - -# Extract and manage few-shot examples -python scripts/prompt_optimizer.py prompt.txt --extract-examples --output examples.json +python3 scripts/rag_evaluator.py --contexts retrieved.json --questions eval_set.json +python3 scripts/rag_evaluator.py --contexts ctx.json --questions q.json --k 10 --json +python3 scripts/rag_evaluator.py --contexts ctx.json --questions q.json --output report.json --verbose +python3 scripts/rag_evaluator.py --contexts ctx.json --questions q.json --compare baseline_report.json ``` ---- +Reports context relevance, precision@k, coverage, answer faithfulness, groundedness. Treat relevance < 0.80 as a retrieval problem (chunking/embedding/filtering), not a prompt problem — fix retrieval before rewriting the generation prompt. -### 2. RAG Evaluator +### 3. Agent Orchestrator — `scripts/agent_orchestrator.py` -Evaluates Retrieval-Augmented Generation quality by measuring context relevance and answer faithfulness. +Validates agent configs (YAML/JSON): tool wiring, missing required config, loop risk, token estimates. -**Input:** Retrieved contexts (JSON) and questions/answers -**Output:** Evaluation metrics and quality report - -**Usage:** ```bash -# Evaluate retrieval quality -python scripts/rag_evaluator.py --contexts retrieved.json --questions eval_set.json - -# Output: -# === RAG Evaluation Report === -# Questions evaluated: 50 -# -# Retrieval Metrics: -# Context Relevance: 0.78 (target: >0.80) -# Retrieval Precision@5: 0.72 -# Coverage: 0.85 -# -# Generation Metrics: -# Answer Faithfulness: 0.91 -# Groundedness: 0.88 -# -# Issues Found: -# - 8 questions had no relevant context in top-5 -# - 3 answers contained information not in context -# -# Recommendations: -# 1. Improve chunking strategy for technical documents -# 2. Add metadata filtering for date-sensitive queries - -# Evaluate with custom metrics -python scripts/rag_evaluator.py --contexts retrieved.json --questions eval_set.json \ - --metrics relevance,faithfulness,coverage - -# Export detailed results -python scripts/rag_evaluator.py --contexts retrieved.json --questions eval_set.json \ - --output report.json --verbose +python3 scripts/agent_orchestrator.py agent.yaml --validate +python3 scripts/agent_orchestrator.py agent.yaml --visualize --format mermaid +python3 scripts/agent_orchestrator.py agent.yaml --estimate-cost --runs 100 \ + --input-price-per-mtok 3.00 --output-price-per-mtok 15.00 ``` ---- +Without the two price flags, `--estimate-cost` reports token estimates only. The `model:` field in the config is informational — any model name is accepted. -### 3. Agent Orchestrator +## Workflows -Parses agent definitions and visualizes execution flows. Validates tool configurations. +### Prompt Optimization (eval-gated) -**Input:** Agent configuration (YAML/JSON) -**Output:** Workflow visualization, validation report +1. **Baseline:** `python3 scripts/prompt_optimizer.py current_prompt.txt --analyze --json --output baseline.json` +2. **Diagnose** from the report: ambiguous verbs ("analyze", "handle"), redundant blocks, missing output contract, token waste. +3. **Apply one change at a time**, in this order of leverage: + | Symptom | Fix | + |---------|-----| + | Malformed/unparseable output | Native structured outputs / JSON schema if the API supports it; explicit schema-in-prompt otherwise | + | Inconsistent answers across runs | Tighten instructions + add 2–3 contrastive examples (one near-miss showing what NOT to do) | + | Misses edge cases | Enumerate the edge cases explicitly; add a "when uncertain, do X" rule | + | Token bloat on repeated calls | Move stable prefix (system rules, examples) first so prompt caching applies; trim redundancy | + | Wrong reasoning on hard cases | Ask for stepwise reasoning *in a scratch field the consumer ignores*, or use the provider's extended-thinking mode | +4. **Re-analyze and compare:** `python3 scripts/prompt_optimizer.py revised.txt --analyze --compare baseline.json` +5. **Eval gate (must pass before shipping):** run the revised prompt over the eval set, write per-case pass/fail to `eval_results.json`, then assert: + ```bash + python3 scripts/prompt_optimizer.py revised.txt --analyze --json --output revised.json \ + && python3 -c " + import json, sys + r = json.load(open('revised.json')); b = json.load(open('baseline.json')) + ok = r['clarity_score'] >= b['clarity_score'] and r['token_count'] <= b['token_count'] * 1.10 + sys.exit(0 if ok else 1)" + echo "gate exit=$?" # 0 = ship; 1 = regression, iterate again + ``` + Pair this structural gate with your task-level eval: the revision must not lose any previously-passing eval case (no-regression rule). -**Usage:** -```bash -# Validate agent configuration -python scripts/agent_orchestrator.py agent.yaml --validate +### Few-Shot Example Design -# Output: -# === Agent Validation Report === -# Agent: research_assistant -# Pattern: ReAct -# -# Tools (4 registered): -# [OK] web_search - API key configured -# [OK] calculator - No config needed -# [WARN] file_reader - Missing allowed_paths -# [OK] summarizer - Prompt template valid -# -# Flow Analysis: -# Max depth: 5 iterations -# Estimated tokens/run: 2,400-4,800 -# Potential infinite loop: No -# -# Recommendations: -# 1. Add allowed_paths to file_reader for security -# 2. Consider adding early exit condition for simple queries +1. Define the task contract first (input shape, output shape, edge-case policy). +2. Start with **zero examples** and measure — current models often need none. Add examples only for failure clusters the eval reveals. +3. When adding: 3–5 max, ordered simple → edge → negative (what NOT to extract), formatted identically to the real output contract. +4. Validate consistency: `python3 scripts/prompt_optimizer.py prompt_with_examples.txt --extract-examples --output examples.json` and inspect that every extracted pair parses against your schema. +5. Re-run the eval set; if a case passes only because it resembles an example, add a held-out variant to the eval set. -# Visualize agent workflow (ASCII) -python scripts/agent_orchestrator.py agent.yaml --visualize +### Structured Output Design -# Output: -# ┌─────────────────────────────────────────┐ -# │ research_assistant │ -# │ (ReAct Pattern) │ -# └─────────────────┬───────────────────────┘ -# │ -# ┌────────▼────────┐ -# │ User Query │ -# └────────┬────────┘ -# │ -# ┌────────▼────────┐ -# │ Think │◄──────┐ -# └────────┬────────┘ │ -# │ │ -# ┌────────▼────────┐ │ -# │ Select Tool │ │ -# └────────┬────────┘ │ -# │ │ -# ┌─────────────┼─────────────┐ │ -# ▼ ▼ ▼ │ -# [web_search] [calculator] [file_reader] -# │ │ │ │ -# └─────────────┼─────────────┘ │ -# │ │ -# ┌────────▼────────┐ │ -# │ Observe │───────┘ -# └────────┬────────┘ -# │ -# ┌────────▼────────┐ -# │ Final Answer │ -# └─────────────────┘ +1. Write the JSON Schema first (types, enums, required, maxLength). +2. **Prefer API-native enforcement**: structured-outputs / response-schema / tool-call parameters guarantee shape; prompt text cannot. +3. Fallback (API without schema support): include the schema rendered as field-by-field rules + one valid example, and instruct "output only the JSON object". +4. Gate: pipe 10 eval outputs through a schema validator (`python3 -c "import json,sys; [json.loads(l) for l in sys.stdin]"` at minimum); 10/10 must parse, else return to step 2. -# Export workflow as Mermaid diagram -python scripts/agent_orchestrator.py agent.yaml --visualize --format mermaid -``` +### RAG Tuning Loop ---- +1. Build `questions.json` (id, question, reference answer) and capture current retrievals to `contexts.json`. +2. `python3 scripts/rag_evaluator.py --contexts contexts.json --questions questions.json --output rag_baseline.json` +3. Fix the **lowest metric first**: relevance → chunking/embeddings/metadata filters; faithfulness → grounding instructions + "answer only from context" + citation requirement; coverage → retrieval k / query expansion. +4. Gate: `python3 scripts/rag_evaluator.py --contexts new_contexts.json --questions questions.json --compare rag_baseline.json` — every metric must be ≥ baseline; any regression blocks the change. -## Prompt Engineering Workflows +### Agent Config Review -### Prompt Optimization Workflow +1. `python3 scripts/agent_orchestrator.py agent.yaml --validate` — must exit with VALIDATION PASSED; fix every error and warning (missing tool config, unbounded iterations, loop risk). +2. Check context discipline: each tool description ≤ 1–2 sentences, tool count minimal for the job, stable system prompt placed first (cache-friendly), iteration cap + early-exit condition present. +3. Budget: `--estimate-cost --runs N` with your current prices; if cost/run exceeds budget, cut tools or context before downgrading the model. -Use when improving an existing prompt's performance or reducing token costs. - -**Step 1: Baseline current prompt** -```bash -python scripts/prompt_optimizer.py current_prompt.txt --analyze --output baseline.json -``` - -**Step 2: Identify issues** -Review the analysis report for: -- Token waste (redundant instructions, verbose examples) -- Ambiguous instructions (unclear output format, vague verbs) -- Missing constraints (no length limits, no format specification) - -**Step 3: Apply optimization patterns** -| Issue | Pattern to Apply | -|-------|------------------| -| Ambiguous output | Add explicit format specification | -| Too verbose | Extract to few-shot examples | -| Inconsistent results | Add role/persona framing | -| Missing edge cases | Add constraint boundaries | - -**Step 4: Generate optimized version** -```bash -python scripts/prompt_optimizer.py current_prompt.txt --optimize --output optimized.txt -``` - -**Step 5: Compare results** -```bash -python scripts/prompt_optimizer.py optimized.txt --analyze --compare baseline.json -# Shows: token reduction, clarity improvement, issues resolved -``` - -**Step 6: Validate with test cases** -Run both prompts against your evaluation set and compare outputs. - ---- - -### Few-Shot Example Design Workflow - -Use when creating examples for in-context learning. - -**Step 1: Define the task clearly** -``` -Task: Extract product entities from customer reviews -Input: Review text -Output: JSON with {product_name, sentiment, features_mentioned} -``` - -**Step 2: Select diverse examples (3-5 recommended)** -| Example Type | Purpose | -|--------------|---------| -| Simple case | Shows basic pattern | -| Edge case | Handles ambiguity | -| Complex case | Multiple entities | -| Negative case | What NOT to extract | - -**Step 3: Format consistently** -``` -Example 1: -Input: "Love my new iPhone 15, the camera is amazing!" -Output: {"product_name": "iPhone 15", "sentiment": "positive", "features_mentioned": ["camera"]} - -Example 2: -Input: "The laptop was okay but battery life is terrible." -Output: {"product_name": "laptop", "sentiment": "mixed", "features_mentioned": ["battery life"]} -``` - -**Step 4: Validate example quality** -```bash -python scripts/prompt_optimizer.py prompt_with_examples.txt --validate-examples -# Checks: consistency, coverage, format alignment -``` - -**Step 5: Test with held-out cases** -Ensure model generalizes beyond your examples. - ---- - -### Structured Output Design Workflow - -Use when you need reliable JSON/XML/structured responses. - -**Step 1: Define schema** -```json -{ - "type": "object", - "properties": { - "summary": {"type": "string", "maxLength": 200}, - "sentiment": {"enum": ["positive", "negative", "neutral"]}, - "confidence": {"type": "number", "minimum": 0, "maximum": 1} - }, - "required": ["summary", "sentiment"] -} -``` - -**Step 2: Include schema in prompt** -``` -Respond with JSON matching this schema: -- summary (string, max 200 chars): Brief summary of the content -- sentiment (enum): One of "positive", "negative", "neutral" -- confidence (number 0-1): Your confidence in the sentiment -``` - -**Step 3: Add format enforcement** -``` -IMPORTANT: Respond ONLY with valid JSON. No markdown, no explanation. -Start your response with { and end with } -``` - -**Step 4: Validate outputs** -```bash -python scripts/prompt_optimizer.py structured_prompt.txt --validate-schema schema.json -``` - ---- - -## Reference Documentation +## References | File | Contains | Load when user asks about | |------|----------|---------------------------| -| `references/prompt_engineering_patterns.md` | 10 prompt patterns with input/output examples | "which pattern?", "few-shot", "chain-of-thought", "role prompting" | -| `references/llm_evaluation_frameworks.md` | Evaluation metrics, scoring methods, A/B testing | "how to evaluate?", "measure quality", "compare prompts" | +| `references/prompt_engineering_patterns.md` | 10 prompt patterns with input/output examples | "which pattern?", few-shot design, decomposition, meta-prompting | +| `references/llm_evaluation_frameworks.md` | Eval metrics, scoring methods, A/B testing | "how to evaluate?", "measure quality", "compare prompts" | | `references/agentic_system_design.md` | Agent architectures (ReAct, Plan-Execute, Tool Use) | "build agent", "tool calling", "multi-agent" | ---- +## Related Skills -## Common Patterns Quick Reference - -| Pattern | When to Use | Example | -|---------|-------------|---------| -| **Zero-shot** | Simple, well-defined tasks | "Classify this email as spam or not spam" | -| **Few-shot** | Complex tasks, consistent format needed | Provide 3-5 examples before the task | -| **Chain-of-Thought** | Reasoning, math, multi-step logic | "Think step by step..." | -| **Role Prompting** | Expertise needed, specific perspective | "You are an expert tax accountant..." | -| **Structured Output** | Need parseable JSON/XML | Include schema + format enforcement | - ---- - -## Common Commands - -```bash -# Prompt Analysis -python scripts/prompt_optimizer.py prompt.txt --analyze # Full analysis -python scripts/prompt_optimizer.py prompt.txt --tokens # Token count only -python scripts/prompt_optimizer.py prompt.txt --optimize # Generate optimized version - -# RAG Evaluation -python scripts/rag_evaluator.py --contexts ctx.json --questions q.json # Evaluate -python scripts/rag_evaluator.py --contexts ctx.json --compare baseline # Compare to baseline - -# Agent Development -python scripts/agent_orchestrator.py agent.yaml --validate # Validate config -python scripts/agent_orchestrator.py agent.yaml --visualize # Show workflow -python scripts/agent_orchestrator.py agent.yaml --estimate-cost # Token estimation -``` +- `engineering-team/skills/senior-ml-engineer` — model deployment and serving (this skill stops at the prompt/eval layer) +- `engineering/rag-architect` — RAG system architecture (this skill measures RAG quality; that one designs the pipeline) +- `engineering/agent-designer` — full agent system design (this skill validates configs; that one designs the architecture) diff --git a/engineering-team/skills/senior-prompt-engineer/references/prompt_engineering_patterns.md b/engineering-team/skills/senior-prompt-engineer/references/prompt_engineering_patterns.md index d95f9480..0c51d936 100644 --- a/engineering-team/skills/senior-prompt-engineer/references/prompt_engineering_patterns.md +++ b/engineering-team/skills/senior-prompt-engineer/references/prompt_engineering_patterns.md @@ -511,7 +511,7 @@ available at $399. The standard model has a 12-hour battery life. You are a prompt engineering expert. Task: [description of what the prompt should do] -Target model: [GPT-4/Claude/etc.] +Target model: [the model family you are deploying on] Constraints: [length limits, format requirements] Generate an optimized prompt for this task. @@ -524,7 +524,7 @@ Input: You are a prompt engineering expert. Task: Create a prompt that extracts action items from meeting notes -Target model: GPT-4 +Target model: a current frontier model Constraints: - Output must be valid JSON - Each action item needs: task, owner, due_date diff --git a/engineering-team/skills/senior-prompt-engineer/scripts/agent_orchestrator.py b/engineering-team/skills/senior-prompt-engineer/scripts/agent_orchestrator.py index c54596a5..867e7186 100755 --- a/engineering-team/skills/senior-prompt-engineer/scripts/agent_orchestrator.py +++ b/engineering-team/skills/senior-prompt-engineer/scripts/agent_orchestrator.py @@ -55,7 +55,7 @@ class AgentConfig: max_iterations: int = 10 system_prompt: str = "" temperature: float = 0.7 - model: str = "gpt-4" + model: str = "unspecified" # any model name; informational only — never priced from a hardcoded table @dataclass @@ -177,7 +177,7 @@ def load_config(path: Path) -> AgentConfig: max_iterations=int(data.get('max_iterations', 10)), system_prompt=data.get('system_prompt', ''), temperature=float(data.get('temperature', 0.7)), - model=data.get('model', 'gpt-4') + model=data.get('model', 'unspecified') ) @@ -369,45 +369,44 @@ def generate_mermaid_diagram(config: AgentConfig) -> str: return '\n'.join(lines) -def estimate_cost(config: AgentConfig, runs: int = 100) -> Dict[str, Any]: - """Estimate token costs for agent runs""" +def estimate_cost(config: AgentConfig, runs: int = 100, + input_price_per_mtok: Optional[float] = None, + output_price_per_mtok: Optional[float] = None) -> Dict[str, Any]: + """Estimate token usage (always) and dollar costs (only with user-supplied prices). + + Model pricing changes too often to hardcode. Look up your provider's current + rates and pass --input-price-per-mtok / --output-price-per-mtok; without them + the tool reports token estimates only. + """ validation = validate_agent(config) min_tokens, max_tokens = validation.estimated_tokens_per_run - # Cost per 1K tokens - costs = { - 'gpt-4': {'input': 0.03, 'output': 0.06}, - 'gpt-4-turbo': {'input': 0.01, 'output': 0.03}, - 'gpt-3.5-turbo': {'input': 0.0005, 'output': 0.0015}, - 'claude-3-opus': {'input': 0.015, 'output': 0.075}, - 'claude-3-sonnet': {'input': 0.003, 'output': 0.015}, - } - - model_cost = costs.get(config.model, costs['gpt-4']) - - # Assume 60% input, 40% output - input_tokens = min_tokens * 0.6 - output_tokens = min_tokens * 0.4 - - cost_per_run_min = (input_tokens / 1000 * model_cost['input'] + - output_tokens / 1000 * model_cost['output']) - - input_tokens_max = max_tokens * 0.6 - output_tokens_max = max_tokens * 0.4 - cost_per_run_max = (input_tokens_max / 1000 * model_cost['input'] + - output_tokens_max / 1000 * model_cost['output']) - - return { + result: Dict[str, Any] = { 'model': config.model, 'tokens_per_run': {'min': min_tokens, 'max': max_tokens}, - 'cost_per_run': {'min': round(cost_per_run_min, 4), 'max': round(cost_per_run_max, 4)}, - 'estimated_monthly': { - 'runs': runs * 30, - 'cost_min': round(cost_per_run_min * runs * 30, 2), - 'cost_max': round(cost_per_run_max * runs * 30, 2) - } + 'cost_per_run': None, + 'estimated_monthly': {'runs': runs * 30, 'cost_min': None, 'cost_max': None}, } + if input_price_per_mtok is None or output_price_per_mtok is None: + return result + + # Assume 60% input, 40% output + def run_cost(tokens: int) -> float: + return (tokens * 0.6 / 1_000_000 * input_price_per_mtok + + tokens * 0.4 / 1_000_000 * output_price_per_mtok) + + cost_per_run_min = run_cost(min_tokens) + cost_per_run_max = run_cost(max_tokens) + + result['cost_per_run'] = {'min': round(cost_per_run_min, 4), 'max': round(cost_per_run_max, 4)} + result['estimated_monthly'] = { + 'runs': runs * 30, + 'cost_min': round(cost_per_run_min * runs * 30, 2), + 'cost_max': round(cost_per_run_max * runs * 30, 2), + } + return result + def format_validation_report(config: AgentConfig, result: ValidationResult) -> str: """Format validation result as human-readable report""" @@ -475,7 +474,7 @@ Agent config format (YAML): name: research_assistant pattern: react -model: gpt-4 +model: any-model-id # optional, informational only max_iterations: 10 tools: - name: web_search @@ -491,8 +490,13 @@ tools: parser.add_argument('--visualize', '-v', action='store_true', help='Visualize agent workflow') parser.add_argument('--format', '-f', choices=['ascii', 'mermaid'], default='ascii', help='Visualization format (default: ascii)') - parser.add_argument('--estimate-cost', '-e', action='store_true', help='Estimate token costs') + parser.add_argument('--estimate-cost', '-e', action='store_true', + help='Estimate token usage (and dollar cost if prices supplied)') parser.add_argument('--runs', '-r', type=int, default=100, help='Daily runs for cost estimation') + parser.add_argument('--input-price-per-mtok', type=float, default=None, + help='Input price in USD per million tokens (your provider\'s current rate)') + parser.add_argument('--output-price-per-mtok', type=float, default=None, + help='Output price in USD per million tokens (your provider\'s current rate)') parser.add_argument('--output', '-o', help='Output file path') parser.add_argument('--json', '-j', action='store_true', help='Output as JSON') @@ -534,7 +538,8 @@ tools: # Cost estimation if args.estimate_cost: - costs = estimate_cost(config, args.runs) + costs = estimate_cost(config, args.runs, + args.input_price_per_mtok, args.output_price_per_mtok) if args.json: output_parts.append(json.dumps(costs, indent=2)) else: @@ -542,10 +547,14 @@ tools: output_parts.append("💰 COST ESTIMATION") output_parts.append(f" Model: {costs['model']}") output_parts.append(f" Tokens per run: {costs['tokens_per_run']['min']:,} - {costs['tokens_per_run']['max']:,}") - output_parts.append(f" Cost per run: ${costs['cost_per_run']['min']:.4f} - ${costs['cost_per_run']['max']:.4f}") - output_parts.append(f" Monthly ({costs['estimated_monthly']['runs']:,} runs):") - output_parts.append(f" Min: ${costs['estimated_monthly']['cost_min']:.2f}") - output_parts.append(f" Max: ${costs['estimated_monthly']['cost_max']:.2f}") + if costs['cost_per_run'] is not None: + output_parts.append(f" Cost per run: ${costs['cost_per_run']['min']:.4f} - ${costs['cost_per_run']['max']:.4f}") + output_parts.append(f" Monthly ({costs['estimated_monthly']['runs']:,} runs):") + output_parts.append(f" Min: ${costs['estimated_monthly']['cost_min']:.2f}") + output_parts.append(f" Max: ${costs['estimated_monthly']['cost_max']:.2f}") + else: + output_parts.append(" Dollar cost: n/a — pass --input-price-per-mtok and " + "--output-price-per-mtok with your provider's current rates") # Output output = '\n'.join(output_parts) diff --git a/engineering-team/skills/senior-prompt-engineer/scripts/prompt_optimizer.py b/engineering-team/skills/senior-prompt-engineer/scripts/prompt_optimizer.py index 700093be..aea01286 100755 --- a/engineering-team/skills/senior-prompt-engineer/scripts/prompt_optimizer.py +++ b/engineering-team/skills/senior-prompt-engineer/scripts/prompt_optimizer.py @@ -3,15 +3,21 @@ Prompt Optimizer - Static analysis tool for prompt engineering Features: -- Token estimation (GPT-4/Claude approximation) +- Token estimation (model-agnostic chars-per-token approximation) - Prompt structure analysis - Clarity scoring - Few-shot example extraction and management - Optimization suggestions +Model-agnostic by design: pass any model name with --model (only the tokenizer +family is inferred from it), and supply current pricing yourself with +--price-per-mtok if you want cost estimates. No model IDs or prices are +hardcoded, so this tool does not rot as the model landscape changes. + Usage: python prompt_optimizer.py prompt.txt --analyze - python prompt_optimizer.py prompt.txt --tokens --model gpt-4 + python prompt_optimizer.py prompt.txt --tokens + python prompt_optimizer.py prompt.txt --tokens --model claude --price-per-mtok 3.00 python prompt_optimizer.py prompt.txt --optimize --output optimized.txt python prompt_optimizer.py prompt.txt --extract-examples --output examples.json """ @@ -25,23 +31,11 @@ from typing import Dict, List, Optional, Tuple from dataclasses import dataclass, asdict -# Token estimation ratios (chars per token approximation) +# Token estimation ratios (chars per token approximation), inferred from the +# tokenizer FAMILY in the --model string. Any model name is accepted. TOKEN_RATIOS = { - 'gpt-4': 4.0, - 'gpt-3.5': 4.0, - 'claude': 3.5, - 'default': 4.0 -} - -# Cost per 1K tokens (input) -COST_PER_1K = { - 'gpt-4': 0.03, - 'gpt-4-turbo': 0.01, - 'gpt-3.5-turbo': 0.0005, - 'claude-3-opus': 0.015, - 'claude-3-sonnet': 0.003, - 'claude-3-haiku': 0.00025, - 'default': 0.01 + 'claude': 3.5, # Anthropic tokenizer tends to be denser + 'default': 4.0, # common BPE-family approximation } @@ -49,7 +43,7 @@ COST_PER_1K = { class PromptAnalysis: """Results of prompt analysis""" token_count: int - estimated_cost: float + estimated_cost: Optional[float] model: str clarity_score: int structure_score: int @@ -72,15 +66,21 @@ class FewShotExample: def estimate_tokens(text: str, model: str = 'default') -> int: - """Estimate token count based on character ratio""" - ratio = TOKEN_RATIOS.get(model, TOKEN_RATIOS['default']) + """Estimate token count based on character ratio (family inferred from model name)""" + family = 'claude' if 'claude' in model.lower() else 'default' + ratio = TOKEN_RATIOS[family] return int(len(text) / ratio) -def estimate_cost(token_count: int, model: str = 'default') -> float: - """Estimate cost based on token count""" - cost_per_1k = COST_PER_1K.get(model, COST_PER_1K['default']) - return round((token_count / 1000) * cost_per_1k, 6) +def estimate_cost(token_count: int, price_per_mtok: Optional[float] = None) -> Optional[float]: + """Estimate input cost from a user-supplied price (USD per million tokens). + + Returns None when no price is supplied — pricing changes too often to hardcode; + look up your provider's current rate and pass --price-per-mtok. + """ + if price_per_mtok is None: + return None + return round((token_count / 1_000_000) * price_per_mtok, 6) def find_ambiguous_instructions(text: str) -> List[Dict[str, str]]: @@ -299,12 +299,13 @@ def generate_suggestions(analysis: PromptAnalysis) -> List[str]: return suggestions -def analyze_prompt(text: str, model: str = 'gpt-4') -> PromptAnalysis: +def analyze_prompt(text: str, model: str = 'default', + price_per_mtok: Optional[float] = None) -> PromptAnalysis: """Perform comprehensive prompt analysis""" # Basic metrics token_count = estimate_tokens(text, model) - cost = estimate_cost(token_count, model) + cost = estimate_cost(token_count, price_per_mtok) word_count = len(text.split()) line_count = len(text.split('\n')) @@ -368,7 +369,10 @@ def format_report(analysis: PromptAnalysis) -> str: report.append("📊 METRICS") report.append(f" Token count: {analysis.token_count:,}") - report.append(f" Estimated cost: ${analysis.estimated_cost:.4f} ({analysis.model})") + if analysis.estimated_cost is not None: + report.append(f" Estimated cost: ${analysis.estimated_cost:.4f} ({analysis.model}, user-supplied price)") + else: + report.append(" Estimated cost: n/a (pass --price-per-mtok with your provider's current rate)") report.append(f" Word count: {analysis.word_count:,}") report.append(f" Line count: {analysis.line_count}") report.append("") @@ -417,7 +421,7 @@ def main(): epilog=""" Examples: %(prog)s prompt.txt --analyze - %(prog)s prompt.txt --tokens --model claude-3-sonnet + %(prog)s prompt.txt --tokens --model claude --price-per-mtok 3.00 %(prog)s prompt.txt --optimize --output optimized.txt %(prog)s prompt.txt --extract-examples --output examples.json """ @@ -428,9 +432,12 @@ Examples: parser.add_argument('--tokens', '-t', action='store_true', help='Count tokens only') parser.add_argument('--optimize', '-O', action='store_true', help='Generate optimized version') parser.add_argument('--extract-examples', '-e', action='store_true', help='Extract few-shot examples') - parser.add_argument('--model', '-m', default='gpt-4', - choices=['gpt-4', 'gpt-4-turbo', 'gpt-3.5-turbo', 'claude-3-opus', 'claude-3-sonnet', 'claude-3-haiku'], - help='Model for token/cost estimation') + parser.add_argument('--model', '-m', default='default', + help='Model name (any string; only the tokenizer family is inferred: ' + 'names containing "claude" use 3.5 chars/token, otherwise 4.0)') + parser.add_argument('--price-per-mtok', type=float, default=None, + help='Input price in USD per million tokens (look up your provider\'s ' + 'current rate); omit to skip cost estimation') parser.add_argument('--output', '-o', help='Output file path') parser.add_argument('--json', '-j', action='store_true', help='Output as JSON') parser.add_argument('--compare', '-c', help='Compare with baseline analysis JSON') @@ -448,7 +455,7 @@ Examples: # Tokens only if args.tokens: token_count = estimate_tokens(text, args.model) - cost = estimate_cost(token_count, args.model) + cost = estimate_cost(token_count, args.price_per_mtok) if args.json: print(json.dumps({ 'tokens': token_count, @@ -457,7 +464,8 @@ Examples: }, indent=2)) else: print(f"Tokens: {token_count:,}") - print(f"Estimated cost: ${cost:.4f} ({args.model})") + if cost is not None: + print(f"Estimated cost: ${cost:.4f} ({args.model}, user-supplied price)") sys.exit(0) # Extract examples @@ -490,7 +498,7 @@ Examples: sys.exit(0) # Default: full analysis - analysis = analyze_prompt(text, args.model) + analysis = analyze_prompt(text, args.model, args.price_per_mtok) # Compare with baseline if args.compare: diff --git a/engineering-team/skills/senior-qa/SKILL.md b/engineering-team/skills/senior-qa/SKILL.md index 15ba9122..5c5f7a1b 100644 --- a/engineering-team/skills/senior-qa/SKILL.md +++ b/engineering-team/skills/senior-qa/SKILL.md @@ -120,7 +120,7 @@ import { Button } from '../src/components/Button'; describe('Button', () => { it('renders with label', () => { render(<Button>Click me</Button>); - expect(screen.getByRole('button', { name: "click-mei-tobeinthedocument" + expect(screen.getByRole('button', { name: /click me/i })).toBeInTheDocument(); }); it('calls onClick when clicked', () => { @@ -241,7 +241,7 @@ npx playwright show-report ```typescript // Preferred (accessible) -screen.getByRole('button', { name: "submiti" +screen.getByRole('button', { name: /submit/i }) screen.getByLabelText(/email/i) screen.getByPlaceholderText(/search/i) diff --git a/engineering-team/skills/senior-security/SKILL.md b/engineering-team/skills/senior-security/SKILL.md index f2649b4f..207c94cf 100644 --- a/engineering-team/skills/senior-security/SKILL.md +++ b/engineering-team/skills/senior-security/SKILL.md @@ -1,76 +1,46 @@ --- name: "senior-security" -description: Security engineering toolkit for threat modeling, vulnerability analysis, secure architecture, and penetration testing. Includes STRIDE analysis, OWASP guidance, cryptography patterns, and security scanning tools. Use when the user asks about security reviews, threat analysis, vulnerability assessments, secure coding practices, security audits, attack surface analysis, CVE remediation, or security best practices. -triggers: - - security architecture - - threat modeling - - STRIDE analysis - - penetration testing - - vulnerability assessment - - secure coding - - OWASP - - application security - - cryptography implementation - - secret scanning - - security audit - - zero trust +description: Use when the user asks for STRIDE threat modeling, DREAD risk scoring, data-flow-diagram threat analysis, or a quick secret scan — or when a security request needs routing to the right specialist skill (pen-testing, incident response, cloud posture, red team, AI security, threat hunting, secure code review). This skill owns threat modeling; everything else routes to a sibling. --- -# Senior Security Engineer +# Senior Security Engineer — Threat Modeling + Security Router -Security engineering tools for threat modeling, vulnerability analysis, secure architecture design, and penetration testing. +This skill does exactly one job itself — **STRIDE/DREAD threat modeling** (plus a quick secret scan) — and routes every other security request to the specialist skill that owns that lane. Do not duplicate sibling content here; route instead. ---- +## Routing Table (read this first) -## Table of Contents +| The user wants... | Route to | Why that skill owns it | +|---|---|---| +| Vulnerability assessment, pen-test methodology, OWASP Top 10 testing | `../security-pen-testing/` | Ships `vulnerability_scanner.py` + `dependency_auditor.py` with exit-code contracts | +| Incident triage, SEV classification, forensics, containment | `../incident-response/` | SEV1–SEV4 taxonomy, NIST SP 800-61 phases, `incident_triage.py` | +| Production outage command (non-security incidents) | `../incident-commander/` | Severity classifier + timeline + postmortem tools | +| Security monitoring, CVE triage SLAs, compliance checks (SOC 2 etc.), security headers | `../senior-secops/` | `security_scanner.py` + `compliance_checker.py`, CVE SLA table | +| Hostile/adversarial code review | `../adversarial-reviewer/` | 3-persona review with BLOCK/CONCERNS/CLEAN verdict | +| Secure code review as part of general review | `../code-reviewer/` | Language dispatch + regression fixtures | +| Cloud IAM escalation paths, S3 exposure, security groups | `../cloud-security/` | `cloud_posture_check.py` with per-check exit codes | +| Threat hunting, IOC sweeps, anomaly detection | `../threat-detection/` | z-score anomaly + IOC staleness tooling | +| Red-team engagement planning, ATT&CK kill chains | `../red-team/` | `engagement_planner.py` with authorization gate | +| LLM/AI attack surface (prompt injection, poisoning) | `../ai-security/` | ATLAS-mapped `ai_threat_scanner.py` | -- [Threat Modeling Workflow](#threat-modeling-workflow) -- [Security Architecture Workflow](#security-architecture-workflow) -- [Vulnerability Assessment Workflow](#vulnerability-assessment-workflow) -- [Secure Code Review Workflow](#secure-code-review-workflow) -- [Incident Response Workflow](#incident-response-workflow) -- [Security Tools Reference](#security-tools-reference) -- [Tools and References](#tools-and-references) +If the request spans lanes (e.g., "secure this new architecture"), do the threat model here first — its output (prioritized threats + mitigations) tells you which siblings to load next. Never bulk-load multiple security skills speculatively. ---- +## What This Skill Owns: STRIDE Threat Modeling -## Threat Modeling Workflow +### Workflow -Identify and analyze security threats using STRIDE methodology. - -### Workflow: Conduct Threat Model - -1. Define system scope and boundaries: - - Identify assets to protect - - Map trust boundaries - - Document data flows -2. Create data flow diagram: - - External entities (users, services) - - Processes (application components) - - Data stores (databases, caches) - - Data flows (APIs, network connections) -3. Apply STRIDE to each DFD element (see [STRIDE per Element Matrix](#stride-per-element-matrix) below) -4. Score risks using DREAD: - - Damage potential (1-10) - - Reproducibility (1-10) - - Exploitability (1-10) - - Affected users (1-10) - - Discoverability (1-10) -5. Prioritize threats by risk score -6. Define mitigations for each threat -7. Document in threat model report -8. **Validation:** All DFD elements analyzed; STRIDE applied; threats scored; mitigations mapped - -### STRIDE Threat Categories - -| Category | Security Property | Mitigation Focus | -|----------|-------------------|------------------| -| Spoofing | Authentication | MFA, certificates, strong auth | -| Tampering | Integrity | Signing, checksums, validation | -| Repudiation | Non-repudiation | Audit logs, digital signatures | -| Information Disclosure | Confidentiality | Encryption, access controls | -| Denial of Service | Availability | Rate limiting, redundancy | -| Elevation of Privilege | Authorization | RBAC, least privilege | +1. **Scope:** assets to protect, trust boundaries, data flows (external entities, processes, data stores, flows). +2. **Generate the threat model** per component: + ```bash + python3 scripts/threat_modeler.py --component "User Authentication" --assets "credentials,sessions" --json --output threats.json + ``` + Output: per-threat STRIDE category, DREAD score (Damage, Reproducibility, Exploitability, Affected users, Discoverability — each 1–10), and suggested mitigations. Repeat per DFD element; `--interactive` walks scoping questions; `--list-threats` shows the threat database. +3. **Consume the output:** sort `threats.json` by DREAD score descending; everything ≥ 7 average needs a named mitigation owner before the design ships. Map each mitigation to the responsible sibling lane (e.g., IAM threats → `cloud-security`, injection threats → `code-reviewer`). +4. **Quick secret sweep** while you have the codebase open: + ```bash + python3 scripts/secret_scanner.py /path/to/project --format json --severity high + ``` + 20+ patterns (AWS keys, GitHub tokens, private keys, generic credentials). Any critical/high finding blocks merge until rotated and moved to a secret manager. +5. **Verification gate:** every DFD element has ≥ 1 STRIDE row considered, every threat with DREAD ≥ 7 has an owner + mitigation, and the secret scan exits with zero high/critical findings. Re-run both tools after mitigations land — that re-run is the done signal, not the document. ### STRIDE per Element Matrix @@ -81,364 +51,14 @@ Identify and analyze security threats using STRIDE methodology. | Data Store | | X | X | X | X | | | Data Flow | | X | | X | X | | -See: [references/threat-modeling-guide.md](references/threat-modeling-guide.md) +(S=Spoofing→authn, T=Tampering→integrity, R=Repudiation→audit logs, I=Info Disclosure→encryption/access control, D=DoS→rate limiting/redundancy, E=Elevation→least privilege.) ---- - -## Security Architecture Workflow - -Design secure systems using defense-in-depth principles. - -### Workflow: Design Secure Architecture - -1. Define security requirements: - - Compliance requirements (GDPR, HIPAA, PCI-DSS) - - Data classification (public, internal, confidential, restricted) - - Threat model inputs -2. Apply defense-in-depth layers: - - Perimeter: WAF, DDoS protection, rate limiting - - Network: Segmentation, IDS/IPS, mTLS - - Host: Patching, EDR, hardening - - Application: Input validation, authentication, secure coding - - Data: Encryption at rest and in transit -3. Implement Zero Trust principles: - - Verify explicitly (every request) - - Least privilege access (JIT/JEA) - - Assume breach (segment, monitor) -4. Configure authentication and authorization: - - Identity provider selection - - MFA requirements - - RBAC/ABAC model -5. Design encryption strategy: - - Key management approach - - Algorithm selection - - Certificate lifecycle -6. Plan security monitoring: - - Log aggregation - - SIEM integration - - Alerting rules -7. Document architecture decisions -8. **Validation:** Defense-in-depth layers defined; Zero Trust applied; encryption strategy documented; monitoring planned - -### Defense-in-Depth Layers - -``` -Layer 1: PERIMETER - WAF, DDoS mitigation, DNS filtering, rate limiting - -Layer 2: NETWORK - Segmentation, IDS/IPS, network monitoring, VPN, mTLS - -Layer 3: HOST - Endpoint protection, OS hardening, patching, logging - -Layer 4: APPLICATION - Input validation, authentication, secure coding, SAST - -Layer 5: DATA - Encryption at rest/transit, access controls, DLP, backup -``` - -### Authentication Pattern Selection - -| Use Case | Recommended Pattern | -|----------|---------------------| -| Web application | OAuth 2.0 + PKCE with OIDC | -| API authentication | JWT with short expiration + refresh tokens | -| Service-to-service | mTLS with certificate rotation | -| CLI/Automation | API keys with IP allowlisting | -| High security | FIDO2/WebAuthn hardware keys | - -See: [references/security-architecture-patterns.md](references/security-architecture-patterns.md) - ---- - -## Vulnerability Assessment Workflow - -Identify and remediate security vulnerabilities in applications. - -### Workflow: Conduct Vulnerability Assessment - -1. Define assessment scope: - - In-scope systems and applications - - Testing methodology (black box, gray box, white box) - - Rules of engagement -2. Gather information: - - Technology stack inventory - - Architecture documentation - - Previous vulnerability reports -3. Perform automated scanning: - - SAST (static analysis) - - DAST (dynamic analysis) - - Dependency scanning - - Secret detection -4. Conduct manual testing: - - Business logic flaws - - Authentication bypass - - Authorization issues - - Injection vulnerabilities -5. Classify findings by severity: - - Critical: Immediate exploitation risk - - High: Significant impact, easier to exploit - - Medium: Moderate impact or difficulty - - Low: Minor impact -6. Develop remediation plan: - - Prioritize by risk - - Assign owners - - Set deadlines -7. Verify fixes and document -8. **Validation:** Scope defined; automated and manual testing complete; findings classified; remediation tracked - -For OWASP Top 10 vulnerability descriptions and testing guidance, refer to [owasp.org/Top10](https://owasp.org/Top10). - -### Vulnerability Severity Matrix - -| Impact \ Exploitability | Easy | Moderate | Difficult | -|-------------------------|------|----------|-----------| -| Critical | Critical | Critical | High | -| High | Critical | High | Medium | -| Medium | High | Medium | Low | -| Low | Medium | Low | Low | - ---- - -## Secure Code Review Workflow - -Review code for security vulnerabilities before deployment. - -### Workflow: Conduct Security Code Review - -1. Establish review scope: - - Changed files and functions - - Security-sensitive areas (auth, crypto, input handling) - - Third-party integrations -2. Run automated analysis: - - SAST tools (Semgrep, CodeQL, Bandit) - - Secret scanning - - Dependency vulnerability check -3. Review authentication code: - - Password handling (hashing, storage) - - Session management - - Token validation -4. Review authorization code: - - Access control checks - - RBAC implementation - - Privilege boundaries -5. Review data handling: - - Input validation - - Output encoding - - SQL query construction - - File path handling -6. Review cryptographic code: - - Algorithm selection - - Key management - - Random number generation -7. Document findings with severity -8. **Validation:** Automated scans passed; auth/authz reviewed; data handling checked; crypto verified; findings documented - -### Security Code Review Checklist - -| Category | Check | Risk | -|----------|-------|------| -| Input Validation | All user input validated and sanitized | Injection | -| Output Encoding | Context-appropriate encoding applied | XSS | -| Authentication | Passwords hashed with Argon2/bcrypt | Credential theft | -| Session | Secure cookie flags set (HttpOnly, Secure, SameSite) | Session hijacking | -| Authorization | Server-side permission checks on all endpoints | Privilege escalation | -| SQL | Parameterized queries used exclusively | SQL injection | -| File Access | Path traversal sequences rejected | Path traversal | -| Secrets | No hardcoded credentials or keys | Information disclosure | -| Dependencies | Known vulnerable packages updated | Supply chain | -| Logging | Sensitive data not logged | Information disclosure | - -### Secure vs Insecure Patterns - -| Pattern | Issue | Secure Alternative | -|---------|-------|-------------------| -| SQL string formatting | SQL injection | Use parameterized queries with placeholders | -| Shell command building | Command injection | Use subprocess with argument lists, no shell | -| Path concatenation | Path traversal | Validate and canonicalize paths | -| MD5/SHA1 for passwords | Weak hashing | Use Argon2id or bcrypt | -| Math.random for tokens | Predictable values | Use crypto.getRandomValues | - -### Inline Code Examples - -**SQL Injection — insecure vs. secure (Python):** - -```python -# ❌ Insecure: string formatting allows SQL injection -query = f"SELECT * FROM users WHERE username = '{username}'" -cursor.execute(query) - -# ✅ Secure: parameterized query — user input never interpreted as SQL -query = "SELECT * FROM users WHERE username = %s" -cursor.execute(query, (username,)) -``` - -**Password Hashing with Argon2id (Python):** - -```python -from argon2 import PasswordHasher - -ph = PasswordHasher() # uses secure defaults (time_cost, memory_cost) - -# On registration -hashed = ph.hash(plain_password) - -# On login — raises argon2.exceptions.VerifyMismatchError on failure -ph.verify(hashed, plain_password) -``` - -**Secret Scanning — core pattern matching (Python):** - -```python -import re, pathlib - -SECRET_PATTERNS = { - "aws_access_key": re.compile(r"AKIA[0-9A-Z]{16}"), - "github_token": re.compile(r"ghp_[A-Za-z0-9]{36}"), - "private_key": re.compile(r"-----BEGIN (RSA |EC )?PRIVATE KEY-----"), - "generic_secret": re.compile(r'(?i)(password|secret|api_key)\s*=\s*["\']?\S{8,}'), -} - -def scan_file(path: pathlib.Path) -> list[dict]: - findings = [] - for lineno, line in enumerate(path.read_text(errors="replace").splitlines(), 1): - for name, pattern in SECRET_PATTERNS.items(): - if pattern.search(line): - findings.append({"file": str(path), "line": lineno, "type": name}) - return findings -``` - ---- - -## Incident Response Workflow - -Respond to and contain security incidents. - -### Workflow: Handle Security Incident - -1. Identify and triage: - - Validate incident is genuine - - Assess initial scope and severity - - Activate incident response team -2. Contain the threat: - - Isolate affected systems - - Block malicious IPs/accounts - - Disable compromised credentials -3. Eradicate root cause: - - Remove malware/backdoors - - Patch vulnerabilities - - Update configurations -4. Recover operations: - - Restore from clean backups - - Verify system integrity - - Monitor for recurrence -5. Conduct post-mortem: - - Timeline reconstruction - - Root cause analysis - - Lessons learned -6. Implement improvements: - - Update detection rules - - Enhance controls - - Update runbooks -7. Document and report -8. **Validation:** Threat contained; root cause eliminated; systems recovered; post-mortem complete; improvements implemented - -### Incident Severity Levels - -| Level | Response Time | Escalation | -|-------|---------------|------------| -| P1 - Critical (active breach/exfiltration) | Immediate | CISO, Legal, Executive | -| P2 - High (confirmed, contained) | 1 hour | Security Lead, IT Director | -| P3 - Medium (potential, under investigation) | 4 hours | Security Team | -| P4 - Low (suspicious, low impact) | 24 hours | On-call engineer | - -### Incident Response Checklist - -| Phase | Actions | -|-------|---------| -| Identification | Validate alert, assess scope, determine severity | -| Containment | Isolate systems, preserve evidence, block access | -| Eradication | Remove threat, patch vulnerabilities, reset credentials | -| Recovery | Restore services, verify integrity, increase monitoring | -| Lessons Learned | Document timeline, identify gaps, update procedures | - ---- - -## Security Tools Reference - -### Recommended Security Tools - -| Category | Tools | -|----------|-------| -| SAST | Semgrep, CodeQL, Bandit (Python), ESLint security plugins | -| DAST | OWASP ZAP, Burp Suite, Nikto | -| Dependency Scanning | Snyk, Dependabot, npm audit, pip-audit | -| Secret Detection | GitLeaks, TruffleHog, detect-secrets | -| Container Security | Trivy, Clair, Anchore | -| Infrastructure | Checkov, tfsec, ScoutSuite | -| Network | Wireshark, Nmap, Masscan | -| Penetration | Metasploit, sqlmap, Burp Suite Pro | - -### Cryptographic Algorithm Selection - -| Use Case | Algorithm | Key Size | -|----------|-----------|----------| -| Symmetric encryption | AES-256-GCM | 256 bits | -| Password hashing | Argon2id | N/A (use defaults) | -| Message authentication | HMAC-SHA256 | 256 bits | -| Digital signatures | Ed25519 | 256 bits | -| Key exchange | X25519 | 256 bits | -| TLS | TLS 1.3 | N/A | - -See: [references/cryptography-implementation.md](references/cryptography-implementation.md) - ---- - -## Tools and References - -### Scripts - -| Script | Purpose | -|--------|---------| -| [threat_modeler.py](scripts/threat_modeler.py) | STRIDE threat analysis with DREAD risk scoring; JSON and text output; interactive guided mode | -| [secret_scanner.py](scripts/secret_scanner.py) | Detect hardcoded secrets and credentials across 20+ patterns; CI/CD integration ready | - -For usage, see the inline code examples in [Secure Code Review Workflow](#inline-code-examples) and the script source files directly. - -### References +## References (load on demand) | Document | Content | |----------|---------| -| [security-architecture-patterns.md](references/security-architecture-patterns.md) | Zero Trust, defense-in-depth, authentication patterns, API security | -| [threat-modeling-guide.md](references/threat-modeling-guide.md) | STRIDE methodology, attack trees, DREAD scoring, DFD creation | -| [cryptography-implementation.md](references/cryptography-implementation.md) | AES-GCM, RSA, Ed25519, password hashing, key management | +| [references/threat-modeling-guide.md](references/threat-modeling-guide.md) | STRIDE methodology, attack trees, DREAD scoring, DFD creation | +| [references/security-architecture-patterns.md](references/security-architecture-patterns.md) | Zero Trust, defense-in-depth, authentication patterns, API security | +| [references/cryptography-implementation.md](references/cryptography-implementation.md) | AES-GCM, Ed25519, password hashing (Argon2id), key management | ---- - -## Security Standards Reference - -### Security Headers Checklist - -| Header | Recommended Value | -|--------|-------------------| -| Content-Security-Policy | default-src self; script-src self | -| X-Frame-Options | DENY | -| X-Content-Type-Options | nosniff | -| Strict-Transport-Security | max-age=31536000; includeSubDomains | -| Referrer-Policy | strict-origin-when-cross-origin | -| Permissions-Policy | geolocation=(), microphone=(), camera=() | - -For compliance framework requirements (OWASP ASVS, CIS Benchmarks, NIST CSF, PCI-DSS, HIPAA, SOC 2), refer to the respective official documentation. - ---- - -## Related Skills - -| Skill | Integration Point | -|-------|-------------------| -| [senior-devops](../senior-devops/) | CI/CD security, infrastructure hardening | -| [senior-secops](../senior-secops/) | Security monitoring, incident response | -| [senior-backend](../senior-backend/) | Secure API development | -| [senior-architect](../senior-architect/) | Security architecture decisions | +The architecture and crypto references are kept because no sibling ships them; for *operating* those controls (scanning, compliance, monitoring) still route to `senior-secops`. diff --git a/engineering-team/tdd-guide.zip b/engineering-team/tdd-guide.zip deleted file mode 100644 index 7c81c431..00000000 Binary files a/engineering-team/tdd-guide.zip and /dev/null differ diff --git a/engineering-team/tech-stack-evaluator.zip b/engineering-team/tech-stack-evaluator.zip deleted file mode 100644 index b7cbdc62..00000000 Binary files a/engineering-team/tech-stack-evaluator.zip and /dev/null differ diff --git a/engineering/.claude-plugin/plugin.json b/engineering/.claude-plugin/plugin.json index e51ce900..8e1f38a1 100644 --- a/engineering/.claude-plugin/plugin.json +++ b/engineering/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "engineering-advanced-skills", - "description": "40 advanced engineering skills: agent designer, agent workflow designer, AgentHub, RAG architect, database designer, migration architect, observability designer, dependency auditor, release manager, API reviewer, CI/CD pipeline builder, MCP server builder, skill security auditor, performance profiler, Helm chart builder, Terraform patterns, focused-fix, browser-automation, spec-driven-workflow, secrets-vault-manager, sql-database-assistant, self-eval, llm-cost-optimizer, prompt-governance, llm-wiki (second brain for Obsidian + Claude Code, Karpathy pattern), tc-tracker (task context tracker with lifecycle and handoff format), feature-flags-architect, kubernetes-operator, chaos-engineering, ship-gate (pre-production 8-category audit with deploy-intent intercept), slo-architect (SLO designer, error-budget calculator with multi-window burn-rate alerts, SLO reviewer per Google SRE Workbook), and more. Agent skill and plugin for Claude Code, Codex, Gemini CLI, Cursor, OpenClaw.", + "description": "37 advanced engineering skills: agent designer, agent workflow designer, RAG architect, database designer + schema designer + SQL assistant, migration architect, observability designer, dependency auditor, changelog generator (with semantic version bumper and hotfix/rollback procedures), API design reviewer, API test suite builder, CI/CD pipeline builder, MCP server builder, skill security auditor, skill tester, performance profiler, focused-fix, browser-automation, full-page-screenshot, git-worktree-manager, monorepo-navigator, codebase-onboarding, interview-system-designer, runbook-generator, spec-driven-workflow, secrets-vault-manager, env-secrets-manager, pr-review-expert, self-eval, tc-tracker (task context tracker with lifecycle and handoff format), feature-flags-architect, kubernetes-operator, chaos-engineering, ship-gate (pre-production 8-category audit with deploy-intent intercept), slo-architect (SLO designer, error-budget calculator with multi-window burn-rate alerts, SLO reviewer per Google SRE Workbook), and tech-debt-tracker. Agent skill and plugin for Claude Code, Codex, Gemini CLI, Cursor, OpenClaw.", "version": "2.9.0", "author": { "name": "Alireza Rezvani", diff --git a/engineering/.codex/instructions.md b/engineering/.codex/instructions.md index faa51073..9d112692 100644 --- a/engineering/.codex/instructions.md +++ b/engineering/.codex/instructions.md @@ -19,7 +19,7 @@ When working on advanced engineering tasks, use the POWERFUL-tier skill system: | Performance tuning | performance-profiler | | API review | api-design-reviewer | | Monitoring/SLOs | observability-designer | -| Release management | release-manager | +| Release management / changelogs | changelog-generator | | Security audit | skill-security-auditor | | Tech debt | tech-debt-tracker | diff --git a/engineering/agenthub/skills/board/SKILL.md b/engineering/agenthub/skills/board/SKILL.md index 1ee54adf..483e7b15 100644 --- a/engineering/agenthub/skills/board/SKILL.md +++ b/engineering/agenthub/skills/board/SKILL.md @@ -1,6 +1,6 @@ --- name: "board" -description: "Read, write, and browse the AgentHub message board for agent coordination." +description: "Read, write, and browse the AgentHub message board for agent coordination. Use when the user runs /hub:board or asks to post, read, or inspect coordination messages between competing AgentHub agents." command: /hub:board --- diff --git a/engineering/agenthub/skills/eval/SKILL.md b/engineering/agenthub/skills/eval/SKILL.md index f1dc8c02..1eaf3c5d 100644 --- a/engineering/agenthub/skills/eval/SKILL.md +++ b/engineering/agenthub/skills/eval/SKILL.md @@ -1,6 +1,6 @@ --- name: "eval" -description: "Evaluate and rank agent results by metric or LLM judge for an AgentHub session." +description: "Evaluate and rank agent results by metric or LLM judge for an AgentHub session. Use when the user runs /hub:eval or asks to score, compare, or pick a winner among completed AgentHub agents." command: /hub:eval --- diff --git a/engineering/agenthub/skills/init/SKILL.md b/engineering/agenthub/skills/init/SKILL.md index 93a7505b..e013e2d6 100644 --- a/engineering/agenthub/skills/init/SKILL.md +++ b/engineering/agenthub/skills/init/SKILL.md @@ -1,6 +1,6 @@ --- name: "init" -description: "Create a new AgentHub collaboration session with task, agent count, and evaluation criteria." +description: "Create a new AgentHub collaboration session with task, agent count, and evaluation criteria. Use when the user runs /hub:init or asks to start a multi-agent competition on a task." command: /hub:init --- diff --git a/engineering/agenthub/skills/merge/SKILL.md b/engineering/agenthub/skills/merge/SKILL.md index a4a3e6b6..104b7646 100644 --- a/engineering/agenthub/skills/merge/SKILL.md +++ b/engineering/agenthub/skills/merge/SKILL.md @@ -1,6 +1,6 @@ --- name: "merge" -description: "Merge the winning agent's branch into base, archive losers, and clean up worktrees." +description: "Merge the winning agent's branch into base, archive losers, and clean up worktrees. Use when the user runs /hub:merge or asks to land the winning AgentHub result and tidy the session." command: /hub:merge --- diff --git a/engineering/agenthub/skills/run/SKILL.md b/engineering/agenthub/skills/run/SKILL.md index f6235a86..4761879e 100644 --- a/engineering/agenthub/skills/run/SKILL.md +++ b/engineering/agenthub/skills/run/SKILL.md @@ -1,6 +1,6 @@ --- name: "run" -description: "One-shot lifecycle command that chains init → baseline → spawn → eval → merge in a single invocation." +description: "One-shot lifecycle command that chains init → baseline → spawn → eval → merge in a single invocation. Use when the user runs /hub:run or asks to execute a full AgentHub competition end-to-end." command: /hub:run --- @@ -66,7 +66,7 @@ If no `--eval` was provided, skip this step. Run `/hub:spawn` with the session ID. -If `--template` was provided, use the template dispatch prompt from `references/agent-templates.md` instead of the default dispatch prompt. Pass the eval command, metric, and baseline to the template variables. +If `--template` was provided, use the template dispatch prompt from `../agenthub/references/agent-templates.md` instead of the default dispatch prompt. Pass the eval command, metric, and baseline to the template variables. Launch all agents in a single message with multiple Agent tool calls (true parallelism). diff --git a/engineering/agenthub/skills/spawn/SKILL.md b/engineering/agenthub/skills/spawn/SKILL.md index a95061a2..4eb9a5a8 100644 --- a/engineering/agenthub/skills/spawn/SKILL.md +++ b/engineering/agenthub/skills/spawn/SKILL.md @@ -1,6 +1,6 @@ --- name: "spawn" -description: "Launch N parallel subagents in isolated git worktrees to compete on the session task." +description: "Launch N parallel subagents in isolated git worktrees to compete on the session task. Use when the user runs /hub:spawn or asks to start the competing agents for an initialized AgentHub session." command: /hub:spawn --- @@ -19,7 +19,7 @@ Spawn N subagents that work on the same task in parallel, each in an isolated gi ## Templates -When `--template <name>` is provided, use the dispatch prompt from `references/agent-templates.md` instead of the default prompt below. Available templates: +When `--template <name>` is provided, use the dispatch prompt from `../agenthub/references/agent-templates.md` instead of the default prompt below. Available templates: | Template | Pattern | Use Case | |----------|---------|----------| diff --git a/engineering/agenthub/skills/status/SKILL.md b/engineering/agenthub/skills/status/SKILL.md index ec5abf07..17f0ae7e 100644 --- a/engineering/agenthub/skills/status/SKILL.md +++ b/engineering/agenthub/skills/status/SKILL.md @@ -1,6 +1,6 @@ --- name: "status" -description: "Show DAG state, agent progress, and branch status for an AgentHub session." +description: "Show DAG state, agent progress, and branch status for an AgentHub session. Use when the user runs /hub:status or asks how the AgentHub agents are doing." command: /hub:status --- diff --git a/engineering/autoresearch-agent/skills/loop/SKILL.md b/engineering/autoresearch-agent/skills/loop/SKILL.md index cd07d8b8..adbff858 100644 --- a/engineering/autoresearch-agent/skills/loop/SKILL.md +++ b/engineering/autoresearch-agent/skills/loop/SKILL.md @@ -1,6 +1,6 @@ --- name: "loop" -description: "Start an autonomous experiment loop with user-selected interval (10min, 1h, daily, weekly, monthly). Uses CronCreate for scheduling." +description: "Start an autonomous experiment loop with user-selected interval (10min, 1h, daily, weekly, monthly). Uses CronCreate for scheduling. Use when the user runs /ar:loop or asks to run an autoresearch experiment continuously on a schedule." command: /ar:loop --- diff --git a/engineering/autoresearch-agent/skills/resume/SKILL.md b/engineering/autoresearch-agent/skills/resume/SKILL.md index 48bc7f79..2dd81260 100644 --- a/engineering/autoresearch-agent/skills/resume/SKILL.md +++ b/engineering/autoresearch-agent/skills/resume/SKILL.md @@ -1,6 +1,6 @@ --- name: "resume" -description: "Resume a paused experiment. Checkout the experiment branch, read results history, continue iterating." +description: "Resume a paused experiment. Checkout the experiment branch, read results history, continue iterating. Use when the user runs /ar:resume or asks to pick up a previously started autoresearch experiment." command: /ar:resume --- diff --git a/engineering/autoresearch-agent/skills/run/SKILL.md b/engineering/autoresearch-agent/skills/run/SKILL.md index 4a9caff1..1584d557 100644 --- a/engineering/autoresearch-agent/skills/run/SKILL.md +++ b/engineering/autoresearch-agent/skills/run/SKILL.md @@ -1,6 +1,6 @@ --- name: "run" -description: "Run a single experiment iteration. Edit the target file, evaluate, keep or discard." +description: "Run a single experiment iteration. Edit the target file, evaluate, keep or discard. Use when the user runs /ar:run or asks for one manual autoresearch iteration." command: /ar:run --- diff --git a/engineering/autoresearch-agent/skills/setup/SKILL.md b/engineering/autoresearch-agent/skills/setup/SKILL.md index 15d42d28..50b72766 100644 --- a/engineering/autoresearch-agent/skills/setup/SKILL.md +++ b/engineering/autoresearch-agent/skills/setup/SKILL.md @@ -1,6 +1,6 @@ --- name: "setup" -description: "Set up a new autoresearch experiment interactively. Collects domain, target file, eval command, metric, direction, and evaluator." +description: "Set up a new autoresearch experiment interactively. Collects domain, target file, eval command, metric, direction, and evaluator. Use when the user runs /ar:setup or asks to start optimizing a file with the autoresearch loop." command: /ar:setup --- diff --git a/engineering/autoresearch-agent/skills/status/SKILL.md b/engineering/autoresearch-agent/skills/status/SKILL.md index 56b3ed4c..173737a8 100644 --- a/engineering/autoresearch-agent/skills/status/SKILL.md +++ b/engineering/autoresearch-agent/skills/status/SKILL.md @@ -1,6 +1,6 @@ --- name: "status" -description: "Show experiment dashboard with results, active loops, and progress." +description: "Show experiment dashboard with results, active loops, and progress. Use when the user runs /ar:status or asks how an autoresearch experiment is going." command: /ar:status --- diff --git a/engineering/chaos-engineering/skills/chaos-engineering/scripts/blast_radius_calculator.py b/engineering/chaos-engineering/skills/chaos-engineering/scripts/blast_radius_calculator.py index 1ab87664..1589ad6f 100755 --- a/engineering/chaos-engineering/skills/chaos-engineering/scripts/blast_radius_calculator.py +++ b/engineering/chaos-engineering/skills/chaos-engineering/scripts/blast_radius_calculator.py @@ -70,9 +70,11 @@ def render_text(result): def main(): ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter) - ap.add_argument("--traffic-share", type=float, required=True, help="Fraction (0-1) of traffic affected") - ap.add_argument("--user-pop", type=int, required=True, help="Total user population") - ap.add_argument("--duration-min", type=int, required=True, help="Experiment duration in minutes") + ap.add_argument("--traffic-share", type=float, help="Fraction (0-1) of traffic affected") + ap.add_argument("--user-pop", type=int, help="Total user population") + ap.add_argument("--duration-min", type=int, help="Experiment duration in minutes") + ap.add_argument("--sample", action="store_true", + help="Run with embedded sample inputs (5%% traffic, 100k users, 30 min)") ap.add_argument("--baseline-availability", type=float, default=0.999, help="Baseline availability (default: 0.999)") ap.add_argument("--expected-impact-availability", type=float, default=0.95, dest="impact_avail", help="Availability under fault (default: 0.95)") @@ -81,9 +83,16 @@ def main(): ap.add_argument("--format", choices=["text", "json"], default="text") args = ap.parse_args() + if args.sample: + traffic_share, user_pop, duration_min = 0.05, 100000, 30 + elif None not in (args.traffic_share, args.user_pop, args.duration_min): + traffic_share, user_pop, duration_min = args.traffic_share, args.user_pop, args.duration_min + else: + ap.error("--traffic-share, --user-pop and --duration-min are required (or use --sample)") + try: result = calculate( - args.traffic_share, args.user_pop, args.duration_min, + traffic_share, user_pop, duration_min, args.baseline_availability, args.impact_avail, args.monthly_budget_min, ) except ValueError as e: diff --git a/engineering/claude-coach/agents/cs-claude-coach.md b/engineering/claude-coach/agents/cs-claude-coach.md index b02469d7..ae67910a 100644 --- a/engineering/claude-coach/agents/cs-claude-coach.md +++ b/engineering/claude-coach/agents/cs-claude-coach.md @@ -28,7 +28,7 @@ You are the persona behind the `claude-coach` skill. Your job is to teach the us ## When to invoke -Activate on first explicit request to learn Claude ("coach me", "make me a power user", "Claude cheat codes"). Stay on for the remainder of the conversation. On every subsequent turn, run the 5-gate decision tree from `references/coaching-rules.md` before deciding whether to surface a tip. +Activate on first explicit request to learn Claude ("coach me", "make me a power user", "Claude cheat codes"). Stay on for the remainder of the conversation. On every subsequent turn, run the 5-gate decision tree from `skills/claude-coach/references/coaching-rules.md` before deciding whether to surface a tip. ## On-demand modes diff --git a/engineering/claude-coach/commands/cs-claude-coach.md b/engineering/claude-coach/commands/cs-claude-coach.md index 78f9cf3c..45d1b317 100644 --- a/engineering/claude-coach/commands/cs-claude-coach.md +++ b/engineering/claude-coach/commands/cs-claude-coach.md @@ -17,7 +17,7 @@ Activates the `claude-coach` skill. From this point on, the conversation gains: 2. Otherwise, ask exactly one question: **"What are your top 2-3 use cases for Claude?"** and wait. 3. Load `engineering/claude-coach/skills/claude-coach/references/cheat-codes.md`, rank techniques against the stated use cases, and present the top 5-7 with one-line explanations and one concrete example each. 4. End with: *"I'll watch your prompts going forward and surface tips when I spot an easy win — max one per response. Ask me 'rate that prompt' anytime for direct feedback."* -5. Stay active for the rest of the conversation. On every subsequent turn, run the 5-gate decision tree from `references/coaching-rules.md` before deciding whether to surface a tip. +5. Stay active for the rest of the conversation. On every subsequent turn, run the 5-gate decision tree from `skills/claude-coach/references/coaching-rules.md` before deciding whether to surface a tip. ## Examples diff --git a/engineering/claude-coach/skills/claude-coach/scripts/cheat_code_filter.py b/engineering/claude-coach/skills/claude-coach/scripts/cheat_code_filter.py index 976b62cc..c447c5f9 100644 --- a/engineering/claude-coach/skills/claude-coach/scripts/cheat_code_filter.py +++ b/engineering/claude-coach/skills/claude-coach/scripts/cheat_code_filter.py @@ -118,12 +118,16 @@ def render_human(picks: list[Technique]) -> str: return "\n".join(out) -def sample_run() -> int: +def sample_run(as_json: bool = False) -> int: sample_path = DEFAULT_GLOSSARY if not sample_path.exists(): print("Sample glossary not found; place references/cheat-codes.md alongside this script.", file=sys.stderr) return 1 - picks = rank(parse_glossary(sample_path), ["writing", "coding"], 5) + use_cases = ["writing", "coding"] + picks = rank(parse_glossary(sample_path), use_cases, 5) + if as_json: + print(json.dumps({"use_cases": use_cases, "picks": [asdict(t) for t in picks]}, indent=2)) + return 0 print(render_human(picks)) return 0 @@ -138,7 +142,7 @@ def main(argv: list[str] | None = None) -> int: args = parser.parse_args(argv) if args.sample: - return sample_run() + return sample_run(args.json) if not args.use_cases: parser.error("--use-cases is required unless --sample is passed") diff --git a/engineering/claude-coach/skills/claude-coach/scripts/coach_tip_classifier.py b/engineering/claude-coach/skills/claude-coach/scripts/coach_tip_classifier.py index 997a8891..c567457a 100644 --- a/engineering/claude-coach/skills/claude-coach/scripts/coach_tip_classifier.py +++ b/engineering/claude-coach/skills/claude-coach/scripts/coach_tip_classifier.py @@ -164,7 +164,7 @@ def render_human(d: Decision) -> str: return "\n".join(out) -def sample_run() -> int: +def sample_run(as_json: bool = False) -> int: cases = [ ("Can you help me with my email?", False), ("Write a 200-word product description for a noise-cancelling headphone targeting remote workers, focused on the focus-time benefit, no marketing fluff.", False), @@ -172,8 +172,11 @@ def sample_run() -> int: ("Can you make this better?", True), ("stop with the tips, just rewrite it", False), ] - for prompt, prev in cases: - d = classify(prompt, previous_tip_given=prev) + decisions = [classify(prompt, previous_tip_given=prev) for prompt, prev in cases] + if as_json: + print(json.dumps([asdict(d) for d in decisions], indent=2)) + return 0 + for d in decisions: print(render_human(d)) print("-" * 60) return 0 @@ -188,7 +191,7 @@ def main(argv: list[str] | None = None) -> int: args = parser.parse_args(argv) if args.sample: - return sample_run() + return sample_run(args.json) if not args.prompt: parser.error("--prompt is required unless --sample is passed") diff --git a/engineering/claude-coach/skills/claude-coach/scripts/prompt_rater.py b/engineering/claude-coach/skills/claude-coach/scripts/prompt_rater.py index 02091683..11e5f49d 100644 --- a/engineering/claude-coach/skills/claude-coach/scripts/prompt_rater.py +++ b/engineering/claude-coach/skills/claude-coach/scripts/prompt_rater.py @@ -138,14 +138,17 @@ def render_human(r: Rating) -> str: ) -def sample_run() -> int: +def sample_run(as_json: bool = False) -> int: samples = [ "Can you help me with my email?", "Write a 200-word product description for a noise-cancelling headphone targeting remote workers, focused on the focus-time benefit, no marketing fluff.", "thoughts?", ] - for s in samples: - r = rate(s) + ratings = [rate(s) for s in samples] + if as_json: + print(json.dumps([asdict(r) for r in ratings], indent=2)) + return 0 + for r in ratings: print(render_human(r)) print("-" * 60) return 0 @@ -159,7 +162,7 @@ def main(argv: list[str] | None = None) -> int: args = parser.parse_args(argv) if args.sample: - return sample_run() + return sample_run(args.json) if not args.prompt: parser.error("--prompt is required unless --sample is passed") diff --git a/engineering/collab-proof/.claude-plugin/plugin.json b/engineering/collab-proof/.claude-plugin/plugin.json new file mode 100644 index 00000000..22dcdc45 --- /dev/null +++ b/engineering/collab-proof/.claude-plugin/plugin.json @@ -0,0 +1,20 @@ +{ + "name": "collab-proof", + "description": "Assisted retrospective: after a session, calibrates what Claude contributed vs what the developer drove. LLM-assessed 4-frame analysis, zero dependencies.", + "version": "1.0.0", + "author": { + "name": "dong7812", + "url": "https://github.com/dong7812" + }, + "homepage": "https://github.com/alirezarezvani/claude-skills/tree/main/engineering/collab-proof", + "repository": "https://github.com/alirezarezvani/claude-skills", + "license": "MIT", + "attribution": { + "source_repo": "https://github.com/dong7812/collab-proof", + "author": "dong7812", + "license": "MIT" + }, + "skills": [ + "./skills/collab-proof" + ] +} diff --git a/engineering/collab-proof/LICENSE b/engineering/collab-proof/LICENSE new file mode 100644 index 00000000..466654e4 --- /dev/null +++ b/engineering/collab-proof/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 dong7812 + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/engineering/collab-proof/skills/collab-proof/SKILL.md b/engineering/collab-proof/skills/collab-proof/SKILL.md new file mode 100644 index 00000000..b9535e13 --- /dev/null +++ b/engineering/collab-proof/skills/collab-proof/SKILL.md @@ -0,0 +1,383 @@ +--- +name: "collab-proof" +description: "Use when you want to understand what Claude contributed vs what you drove in a session. Triggers on: /collab-proof, session retrospective, ai contribution analysis, collaboration evidence, what did claude do." +license: MIT +--- + +# collab-proof + +Surfaces AI collaboration evidence the developer didn't consciously record. +Vela 3-layer pipeline × ADHD 4-frame reasoning — prompt-native, zero dependencies. + +--- + +## Layer 01 — Signal detection + +Run `git log --oneline -10` and `git diff --stat HEAD~3..HEAD` first. + +Classify signal level using this rubric (pick the highest that matches): + +**HIGH** → full artifacts (DECISIONS.md + session-history + WORKLOG + HTML) +- New file created, OR +- 4+ files modified, OR +- Explicit option comparison in conversation ("vs", "instead of", "chose X over Y"), OR +- Design discussion lasted 15+ exchanges, OR +- **Bug with root cause diagnosis** — conversation contains WHY the bug happened + (not just "fixed X" but "the bug was caused by Y because Z") + +**BUG_FIXING special rule** — override file count: +Even if only 1 file changed, classify as HIGH if the conversation contains: +- Root cause explanation ("the bug was...", "this happened because...", "the issue is...") +- Diagnosis process ("I checked...", "turned out...", "the problem was...") +- Fix rationale ("chose this approach because...", "instead of X, used Y because...") +File count doesn't matter for bugs — a well-diagnosed single-file fix is more valuable +than a 10-file feature with no discussion. + +**MEDIUM** → WORKLOG only +- 1–3 files modified with no root cause discussion, OR +- Minor feature added, no tradeoffs discussed + +**LOW** → silence, tell user "Routine session — nothing recorded." +- No code changes, only planning/discussion, OR +- Single trivial change with no context ("change this text", "fix typo", "rename variable") + +Show the user: `Signal: HIGH / MEDIUM / LOW — [one-line reason]` + +--- + +## Layer 02 — WorkIntentClassifier + +Run all four frames simultaneously against conversation context + git diff. +Score each frame 0.0–1.0 using the rubric below. Then apply pruning and classification rules. + +### Frame scoring rubric + +**Frame A — Technical** (code churn complexity) +- `1.0` New module/file created, complex logic added (state machine, Lua script, novel algorithm) +- `0.5` Existing function logic modified, simple API endpoint added +- `0.1` Typo fix, comment change, plain text edit + +**Frame B — Uncertainty** (developer doubt signals) +- `1.0` Code written then fully rolled back, explicit doubt expressed ("이게 맞나?", "동작 안 하네"), `git revert` +- `0.5` Advice sought from Claude mid-implementation, 2+ revision requests on same area +- `0.0` Uninterrupted directive execution — developer knew exactly what to build + +**Frame C — Fork** (decision branch presence) +- `1.0` Two or more alternatives explicitly compared in conversation (A vs B) +- `0.5` No explicit comparison but tradeoff mentioned (performance vs readability) +- `0.0` Single standard approach applied, no alternatives considered + +**Frame D — AI contribution** (Claude's actual impact) +- `1.0` Claude identified a bug/edge case the developer hadn't noticed and proposed the fix +- `0.6` Claude generated structural boilerplate/skeleton that significantly accelerated execution +- `0.2` Claude reformatted or transcribed developer-directed code without independent contribution + +--- + +### Pruning rule + +Prune any frame scoring < 0.4. + +**Exception — High-Speed Execution Guard:** +If `Frame A >= 0.8` AND `Frame D >= 0.6`, do NOT prune and do NOT silence the session, +even if Frame B = 0.0 and Frame C = 0.0. +This is a boilerplate-heavy FEATURE_BUILDING session. Classify immediately as `FEATURE_BUILDING` with `HIGH` signal. +Rationale: zero uncertainty in a fast-moving session is a feature, not a reason to discard it. + +--- + +### Intent classification + +| Surviving frames | Dominant intent | Meaning | +|---|---|---| +| A high + D mid-high (B, C low) | `FEATURE_BUILDING` | High-velocity feature generation, Claude scaffolding | +| B high + A/D high | `BUG_FIXING` or `STUCK` | Active debugging or unresolved looping | +| C high + A high | `REFACTORING` or `EXPLORING` | Architecture exploration, weighing alternatives | +| All frames < 0.4 | `FLOW_STATE` or LOW | Routine typing, silence unless Layer 01 was HIGH | + +If multiple intents tie, pick the one with the highest combined frame score. +Record the runner-up — it belongs in the session narrative. + +--- + +### Internal output format + +Before proceeding to Layer 03, resolve to this structure (show it to the user): + +```json +{ + "frames": { + "technical": 0.0, + "uncertainty": 0.0, + "fork": 0.0, + "ai_contribution": 0.0 + }, + "pruned": ["list of pruned frame names"], + "intent": "FEATURE_BUILDING", + "signal": "HIGH", + "calibration_note": "one sentence explaining any exception rule applied" +} +``` + +--- + +## Layer 03 — Output + +### If HIGH signal + +**Append to `DECISIONS.md`** — one entry per real fork (Frame C must confirm alternatives existed): + +```markdown +## [YYYY-MM-DD] <title> + +**Context**: [Frame A — what forced this choice] +**Decision**: what was chosen +**Alternatives considered**: [Frame C — road not taken] +**Reasoning**: why — prefix "inferred:" if reconstructed from context +**AI contribution**: + - Identified: [Frame D — something developer missed] + - Suggested: [Frame D — approach or alternative] + - Developer-driven: [what the developer decided independently] +**Intent class**: [from Layer 02] +**Signal score**: HIGH +**Outcome**: implemented | pending | reversed +``` + +If no real fork existed → write nothing. Never fabricate decisions. + +**BUG_FIXING intent: use this format instead:** + +```markdown +## [YYYY-MM-DD] <bug title> + +**Root cause**: what actually caused the bug — the WHY, not just the what +**Symptom**: what the developer observed +**Fix**: what was changed +**Why this fix**: rationale — inferred if not stated explicitly +**Alternative fixes considered**: other approaches discussed (if any) +**AI contribution**: + - Identified: [Frame D — did Claude spot the root cause?] + - Suggested: [Frame D — fix approach or diagnostic step] + - Developer-driven: [what the developer diagnosed/decided independently] +**Intent class**: BUG_FIXING +**Signal score**: HIGH +**Outcome**: fixed | workaround | deferred +``` + +**Create `session-history/YYYY-MM-DD-HHMM.md`**: + +```markdown +# Session [YYYY-MM-DD HH:MM] + +**Intent**: [class] (runner-up: [class if any]) +**Signal**: HIGH +**Frames active**: A ([score]) / B ([score]) / C ([score]) / D ([score]) + +## What shipped +[grounded in git log] + +## What was figured out +[Frame B + C — the reasoning, tradeoffs, debugging — what developers forget] + +## Decisions made this session +[refs to DECISIONS.md entries] + +## Where it got hard +[Frame B findings — uncertainty, reverts, EXPLORING/STUCK signals] + +## AI contribution summary +[Frame D synthesis — one honest paragraph, calibrated] + +## Next steps inferred +[what's obviously incomplete] +``` + +**Append to `WORKLOG.md`**: +``` +YYYY-MM-DD HH:MM | [intent] | HIGH | D:[score] | cache:[hit%]% | tok:[total] | <verb phrase> — <why it mattered> +``` + +Fields: +- `D:[score]` — Frame D AI contribution score (0.0–1.0) +- `cache:[hit%]%` — cache hit rate from token analysis (or `cache:n/a` if no data) +- `tok:[total]` — total tokens this session (input + cache_read + cache_create + output, in K e.g. `45K`) +- verb phrase — what shipped, grounded in git log + +**Collect token usage** (bash — run this and capture output): +```bash +python3 -c " +import json, sys +from pathlib import Path + +projects = Path.home() / '.claude/projects' +files = sorted(projects.rglob('*.jsonl'), key=lambda f: f.stat().st_mtime, reverse=True) +if not files: + print('no_data'); sys.exit() + +with open(files[0]) as fp: + lines = [json.loads(l) for l in fp if l.strip()] + +ti = to = cr = cc = 0 +turns = [] +for i, line in enumerate(lines): + if line.get('type') == 'assistant': + u = line.get('message', {}).get('usage', {}) + if not u: continue + inp = u.get('input_tokens', 0) + ti += inp; to += u.get('output_tokens', 0) + cr += u.get('cache_read_input_tokens', 0) + cc += u.get('cache_creation_input_tokens', 0) + prompt = '' + for j in range(i-1, -1, -1): + if lines[j].get('type') == 'user': + c = lines[j].get('message', {}).get('content', '') + prompt = (c if isinstance(c, str) else next((x.get('text','') for x in c if isinstance(x,dict) and x.get('type')=='text'), ''))[:80] + break + turns.append((inp, prompt)) + +total = ti + cr + cc +hit = cr / total * 100 if total else 0 +print(f'input={ti} output={to} cache_read={cr} cache_create={cc} hit={hit:.0f} turns={len(turns)}') +turns.sort(reverse=True) +for idx, (tok, p) in enumerate(turns[:3]): + print(f'top{idx+1}={tok}|{p}') +" +``` + +Parse the output and include token stats in the session narrative. Then: + +**Generate `session-history/YYYY-MM-DD-HHMM-proof.html`** — write a self-contained HTML file. Structure and class names are fixed — do not rename or reorder sections. + +**Fixed CSS tokens (use exactly):** +- Background: `#0d1117`, Card: `#161b22`, Border: `#30363d` +- Font: `font-family: 'Courier New', monospace` +- Frame score colors: `high` → `#3fb950`, `low` → `#f85149`, pruned → `#8b949e` +- AI line colors: `ai-identified` → `#a371f7`, `ai-suggested` → `#d29922`, `ai-developer` → `#3fb950` + +**Fixed HTML structure (class names must match exactly):** +``` +<div class="header"> + <div class="header-top"> + <div class="project-name"> + <span class="badge"> <!-- intent class --> + <div class="meta-row"> <!-- date, branch, signal level text --> + <div class="signal-container"> + <div class="signal-label"> + <div class="signal-track"> + <div class="signal-fill"> <!-- width % driven by signal score --> + +<div class="section"> <!-- frames --> + <div class="section-title"> ... <span class="count">Layer 02 · ADHD tree-of-thought</span> + <div class="frames-grid"> + <div class="frame-card"> <!-- pruned: class="frame-card pruned" --> + <div class="frame-label"> <!-- Frame A / B / C / D --> + <div class="frame-name"> + <div class="frame-score high|low"> <!-- score value --> + +<div class="section"> <!-- decisions — skip section if none --> + <div class="section-title"> ... <span class="count">N recorded</span> + <div class="decision-card"> <!-- one per DECISIONS.md entry --> + <div class="decision-header"> + <div class="decision-title"> + <div class="decision-date"> + <div class="decision-fields"> + <div class="field-row"> + <div class="field-label"> <!-- Context / Decision / Alternatives / Reasoning --> + <div class="field-value"> + <div class="field-row"> <!-- AI contribution row --> + <div class="field-label">AI contribution</div> + <div class="field-value"> + <div class="ai-block"> + <div class="ai-line ai-identified|ai-suggested|ai-developer"> + <span class="tag">IDENTIFIED|SUGGESTED|DEV-DRIVEN</span> + <div class="field-row"> <!-- Outcome row --> + <div class="field-label">Outcome</div> + <div class="field-value"> + <span class="outcome-badge outcome-implemented|outcome-pending|outcome-reversed"> + +<div class="section"> <!-- session narrative --> + <div class="section-title">Session narrative</div> + <div class="narrative-grid"> + <div class="narrative-card"> <!-- What shipped --> + <div class="narrative-card"> <!-- What was figured out --> + <div class="narrative-card"> <!-- Where it got hard --> + <div class="narrative-card"> <!-- Next steps inferred --> + +<div class="section"> <!-- AI contribution summary --> + <div class="section-title">AI contribution summary</div> + <div class="narrative-card"> <!-- Frame D synthesis paragraph --> + +<div class="section"> <!-- token usage --> + <div class="section-title">Token usage</div> + <div class="narrative-card"> <!-- cache hit rate bar + top turns + optimization note --> + +<div class="section"> <!-- worklog tail --> + <div class="section-title"> ... <span class="count">last N entries</span> + <div class="worklog-entry"> <!-- one per recent WORKLOG line --> + +<div class="footer"> <!-- last commit hash · "Generated by collab-proof · timestamp" --> +``` + +Write the HTML using bash: +```bash +cat > session-history/YYYY-MM-DD-HHMM-proof.html << 'HTMLEOF' +<!DOCTYPE html> +... (full HTML with inline CSS, no external resources) +HTMLEOF +``` + +After writing, show: `open session-history/YYYY-MM-DD-HHMM-proof.html` + +--- + +### If MEDIUM signal + +Append one line to `WORKLOG.md` only: +``` +YYYY-MM-DD HH:MM | [intent] | MEDIUM | D:[score] | cache:[hit%]% | tok:[total] | <verb phrase> +``` + +--- + +### If LOW signal + +Tell user: "Signal: LOW — Routine session, nothing recorded." + +--- + +## Honesty rules + +- Never invent decisions not in the conversation or implied by the diff +- "inferred:" prefix when reasoning is reconstructed +- Frame D must be calibrated — neither overclaim nor dismiss +- If all frames score < 0.4 → write nothing + +--- + +## PreCompact snapshot (context compaction defence) + +When context compaction is about to happen (triggered by the PreCompact hook), +run a lightweight mid-session checkpoint before context is lost: + +1. Compute current Layer 01 signal level from available context +2. Score all four frames against what's visible now +3. Write a snapshot to `session-history/.tmp-TIMESTAMP.json`: + +```json +{ + "timestamp": "YYYY-MM-DD HH:MM:SS", + "trigger": "pre-compact", + "signal": "HIGH / MEDIUM / LOW", + "frames": { "technical": 0.0, "uncertainty": 0.0, "fork": 0.0, "ai_contribution": 0.0 }, + "intent": "FEATURE_BUILDING", + "key_moments": [ + "one-line description of the most important decision or finding so far" + ] +} +``` + +When `/collab-proof` runs at session end: +- Read all `session-history/.tmp-*.json` files +- Merge frame scores (take max per frame across all snapshots) +- Combine `key_moments` arrays — these preserve tradeoff discussions that were compacted away +- Delete `.tmp-*.json` files after merging diff --git a/engineering/collab-proof/skills/collab-proof/references/ai-collaboration-evidence.md b/engineering/collab-proof/skills/collab-proof/references/ai-collaboration-evidence.md new file mode 100644 index 00000000..279d66b7 --- /dev/null +++ b/engineering/collab-proof/skills/collab-proof/references/ai-collaboration-evidence.md @@ -0,0 +1,38 @@ +# AI Collaboration Evidence: Why Documentation Matters + +## The Problem + +Developers increasingly build with AI, but the collaboration leaves no trace. Git log records *what* changed; the conversation records *what was said*. Neither answers the questions that matter most: + +- Why was this approach chosen over the alternative? +- What did the AI identify that the developer hadn't noticed? +- Where did the developer override the AI's suggestion — and why? + +## Key Sources + +**1. Hiring and Portfolio Verification (2025–2026)** +Companies now explicitly ask candidates to show AI collaboration evidence. GitHub portfolios require "a 'My contribution' section linking to commits or pull requests that demonstrate what you owned" (Artech, 2026). Recruiters scan for AI-native engineering skills and expect proof beyond finished artifacts. +Source: [Artech AI Portfolio Tips](https://www.artech.com/blog/ai-assisted-portfolio-credibility/) + +**2. Architecture Decision Records (ADRs)** +ADRs (Michael Nygard, 2011) capture the context, decision, and consequences of architectural choices. The canonical format includes: title, status, context, decision, consequences. Modern AI-assisted development extends this pattern to include *who* made the decision — human or AI. +Source: [Nygard ADR Template](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions) + +**3. Session Context Loss** +Claude Code saves session transcripts to `~/.claude/projects/` as JSONL. But context compaction and session boundaries mean reasoning evaporates. Studies of AI-assisted development show developers cannot reconstruct the reasoning behind 60–70% of decisions made in a session after 48 hours. +Source: [Claude Code Session Memory](https://claudefa.st/blog/guide/mechanics/session-memory) + +**4. AI Contribution Attribution** +The `git-ai` project (2026) tracks AI-generated code line-by-line. But line attribution ("AI wrote this") is different from decision attribution ("AI identified this issue"). collab-proof targets the decision layer, not the code layer. +Source: [git-ai: AI contribution tracking](https://github.com/git-ai-project/git-ai) + +**5. Developer Cognitive Load** +Research on expertise and memory (Sweller, 1988; Kirschner et al., 2006) shows that working memory constraints cause implicit reasoning to be discarded when focus shifts. External documentation of decisions during the session — not after — is the only reliable capture method. +Source: Sweller, J. (1988). Cognitive load during problem solving. *Cognitive Science*, 12(2), 257–285. + +## Implications for collab-proof + +- Evidence must be captured *during* the session, not reconstructed afterward +- Calibrated attribution ("identified" vs "suggested" vs "developer-driven") is more useful than binary AI/human labeling +- Shareable HTML format enables portfolio and hiring use cases that markdown alone cannot serve +- Signal filtering prevents noise — only sessions with genuine decision forks produce output diff --git a/engineering/collab-proof/skills/collab-proof/references/developer-portfolio-proof.md b/engineering/collab-proof/skills/collab-proof/references/developer-portfolio-proof.md new file mode 100644 index 00000000..92674bd9 --- /dev/null +++ b/engineering/collab-proof/skills/collab-proof/references/developer-portfolio-proof.md @@ -0,0 +1,68 @@ +# Developer Portfolio Proof: The AI Collaboration Evidence Problem + +## Why "Show Your Work" Now Applies to AI + +The hiring market has shifted. Companies explicitly ask candidates: "Show me how you used AI in this project." The challenge is that AI-assisted development leaves ambiguous evidence: + +- A GitHub repo shows finished code, not the collaboration process +- Commit messages show *what* shipped, not *why* this approach +- A demo shows the product works, not what the developer contributed vs the AI + +## The Verification Gap + +Source: [TechnCV: Claude Code Resume Skills](https://techncv.com/blog/claude-code-resume-skills/) + +Hiring managers at forward-thinking companies scan for AI-native engineering skills. The recommended evidence includes: +1. Git commit histories with meaningful messages +2. Prompt logs or decision rationale +3. Inline comments explaining decisions +4. Live demos where candidates walk through their logic + +collab-proof addresses items 2 and 3 automatically. + +## HTML as Portable Proof + +Markdown files are local artifacts. HTML files are shareable: +- Email attachment to a recruiter +- Link in a GitHub README +- Appendix to a portfolio site +- PR description for code review + +A self-contained HTML file (no CDN, no external resources, `file://`-ready) is the most portable format for portfolio evidence. PDF requires generation tooling; Gist requires GitHub authentication. + +Source: [AI Agent Portfolio Examples](https://tandamconnect.com/blog/ai-agent-portfolio-examples-2026) + +## The "AI Contribution" Calibration Problem + +Existing tools either overclaim ("AI built this") or dismiss ("developer did everything"). Neither is useful for: +- Honest self-assessment +- Team knowledge transfer +- Portfolio credibility + +The calibrated approach distinguishes three contribution types: +- **Identified**: AI spotted something the developer hadn't noticed (e.g., race condition, security issue) +- **Suggested**: AI proposed an approach or alternative (developer made final call) +- **Developer-driven**: Developer designed and decided; AI executed + +This three-way split comes from studies of pair programming (Williams & Kessler, 2002) where contribution attribution improved team learning and code review quality. + +Source: Williams, L. & Kessler, R. (2002). *Pair Programming Illuminated*. Addison-Wesley. + +## Signal Filtering Prevents Portfolio Inflation + +Not every session deserves documentation. A session where you changed a button color has no evidence value. collab-proof's LOW signal threshold silences these sessions. + +The 30–40% artifact generation rate is a feature, not a bug: it means every documented session has genuine decision content, making the portfolio more credible, not less. + +Source: [Asking HN: Hiring in the age of AI-assisted coding](https://news.ycombinator.com/item?id=47722081) + +## Tamper-Evident Timestamps via Git + +The HTML proof footer embeds the last git commit hash of the session. This provides: +- A timestamp verifiable against the public git history +- Proof the document was generated at development time, not retrospectively +- A link between the artifact and the code it describes + +This is analogous to signed commits but for documentation rather than code. + +Source: [Git: Cryptographic signing](https://git-scm.com/book/en/v2/Git-Tools-Signing-Your-Work) diff --git a/engineering/collab-proof/skills/collab-proof/references/session-documentation-patterns.md b/engineering/collab-proof/skills/collab-proof/references/session-documentation-patterns.md new file mode 100644 index 00000000..5d86346f --- /dev/null +++ b/engineering/collab-proof/skills/collab-proof/references/session-documentation-patterns.md @@ -0,0 +1,66 @@ +# Session Documentation Patterns + +## Existing Approaches and Their Gaps + +### Architecture Decision Records (ADRs) +ADRs (Nygard, 2011) are the standard for capturing architectural decisions. Format: context → decision → consequences. Tools like `madr-gen` auto-generate ADRs from Claude Code sessions using MADR 4.0 format. + +**Gap**: ADRs don't capture *who* made the decision. In AI-assisted development, "decision" can mean "Claude suggested and developer accepted," "developer decided over Claude's objection," or "collaborative synthesis." Without this distinction, ADRs are incomplete evidence. + +Source: [MADR format](https://adr.github.io/madr/), [madr-gen](https://github.com/Tazic123/madr-gen) + +### Session Loggers (claude-sessions, claude-diary) +Tools like `maleta/claude-sessions` automatically summarize Claude Code sessions and generate `SESSION_SUMMARIES.md`. `rlancemartin/claude-diary` creates diary entries from session transcripts. + +**Gap**: These tools answer "what happened?" not "what was the reasoning?" and not "what did each party contribute?" They're logs, not decision records. + +Source: [maleta/claude-sessions](https://github.com/maleta/claude-sessions), [claude-diary](https://github.com/rlancemartin/claude-diary) + +### Memory Compilers (claude-memory-compiler) +`coleam00/claude-memory-compiler` uses hooks to capture sessions, extracts key decisions with the Claude Agent SDK, and compiles cross-referenced knowledge articles. + +**Gap**: Heavy setup (requires Agent SDK), no HTML export, no calibrated attribution field. + +Source: [claude-memory-compiler](https://github.com/coleam00/claude-memory-compiler) + +## The Signal Filtering Pattern + +Not all sessions deserve documentation. Vela's 3-layer pipeline (signal detection → intent classification → output generation) filters noise before generating artifacts: + +- **Layer 01 (Signal)**: git diff + conversation analysis → HIGH/MEDIUM/LOW +- **Layer 02 (Intent)**: ADHD 4-frame parallel reasoning → intent class +- **Layer 03 (Output)**: proportional artifact generation + +This prevents the "everything is documented" anti-pattern where signal-to-noise ratio collapses. + +Reference: Signal-filtering pipeline pattern — see [collab-proof SKILL.md](https://github.com/alirezarezvani/claude-skills/tree/main/engineering/collab-proof/skills/collab-proof/SKILL.md) + +## ADHD Tree-of-Thought in Layer 02 + +The ADHD tree-of-thought approach (UditAkhourii, 2025) fans out parallel divergent thoughts under different cognitive frames, scores, prunes traps, and deepens survivors. + +Applied to session analysis, four frames fire simultaneously: +- **Frame A (Technical)**: What code choices were made? +- **Frame B (Uncertainty)**: Where was the developer unsure? +- **Frame C (Fork)**: What could have gone differently? +- **Frame D (AI contribution)**: Where did Claude change the outcome? + +Frames scoring below 0.4 are pruned. Only surviving frames contribute to output. + +Source: [UditAkhourii/adhd](https://github.com/uditakhourii/adhd), [The New Stack: Claude Code ADHD](https://thenewstack.io/claude-code-adhd/) + +## SessionEnd Hook (Claude Code 1.0.84+) + +Claude Code introduced the `SessionEnd` hook in version 1.0.84. It fires when the session closes, enabling full automation without user action. + +```json +"hooks": { + "SessionEnd": [{ + "hooks": [{"type": "command", "command": "~/.claude/hooks/collab-proof-on-session-end.sh"}] + }] +} +``` + +Known issue: `SessionEnd` hook may report "Hook cancelled" even on exit 0 (GitHub issue #63495, open as of 2026-06). Hook executes correctly despite the warning. + +Source: [Claude Code Hooks Reference](https://code.claude.com/docs/en/hooks), [Issue #63495](https://github.com/anthropics/claude-code/issues/63495) diff --git a/engineering/collab-proof/skills/collab-proof/references/tamper-evident-proof.md b/engineering/collab-proof/skills/collab-proof/references/tamper-evident-proof.md new file mode 100644 index 00000000..26a33e27 --- /dev/null +++ b/engineering/collab-proof/skills/collab-proof/references/tamper-evident-proof.md @@ -0,0 +1,71 @@ +# Tamper-Evident Proof via Git Notes + +## The Problem with Markdown-Only Evidence + +A DECISIONS.md file in a git repo can be backdated, edited, or fabricated. Without an immutable timestamp tied to the actual code state, it's not proof — it's documentation. + +## Git Notes: Metadata Without File Tree Pollution + +Git notes (`git notes`) attach arbitrary text to any git object (commit, blob, tree) without modifying the object itself. Notes live in `refs/notes/collab-proof` — a parallel namespace that doesn't appear in `git log` by default and doesn't affect `git status`. + +```bash +# Attach a note to the current commit +git notes add -m "collab-proof sha256: abc123..." HEAD + +# View notes on a commit +git notes show HEAD +git log --show-notes + +# Share notes with collaborators +git push origin refs/notes/collab-proof + +# Fetch collaborators' notes +git fetch origin refs/notes/collab-proof:refs/notes/collab-proof +``` + +Source: [Git Notes documentation](https://git-scm.com/docs/git-notes), [Pro Git: Git Notes](https://git-scm.com/book/en/v2/Git-Internals-The-Refspec) + +## Why SHA-256 of the HTML File + +The HTML proof file contains the full session narrative, decision records, and AI contribution analysis. Hashing it and attaching the hash to a specific commit creates a verifiable chain: + +``` +commit abc1234 (code state at session end) + └── git note: collab-proof sha256: f7a3... + file: 2026-06-01-1422-proof.html + +→ Anyone with the HTML file can verify: + python3 -c "import hashlib; print(hashlib.sha256(open('proof.html','rb').read()).hexdigest())" + # must match the hash in the git note +``` + +This is structurally similar to software release signing (GPG-signed tags) but using stdlib Python and git's built-in notes system. + +Source: [Git tag signing](https://git-scm.com/book/en/v2/Git-Tools-Signing-Your-Work), NIST SP 800-107 Rev 1 (SHA-256 collision resistance) + +## Collaboration Safety + +Git notes don't cause merge conflicts the way file edits do. Multiple contributors can append notes to the same commit independently: + +```bash +# Both developers can run this without conflict: +git notes append -m "reviewer: approved" HEAD +``` + +The `append` subcommand concatenates to existing notes; `add` replaces them. collab-proof uses `append` so multiple session runs on the same commit accumulate rather than overwrite. + +Source: [git-notes man page](https://git-scm.com/docs/git-notes#_commands) + +## Limitations + +- Notes are not included in a standard `git clone` — collaborators must explicitly `git fetch origin refs/notes/collab-proof` +- Notes can still be deleted with `git notes remove` — they are tamper-evident, not tamper-proof +- The proof is only as strong as the git history itself (rebasing changes commit hashes) + +Source: [Stack Overflow: Are git notes included in clone?](https://stackoverflow.com/questions/13935467/are-git-notes-included-in-a-git-clone) + +## Why Not GPG Signing? + +GPG signing would require key management infrastructure. git notes + SHA-256 achieves the core goal (linking an artifact to a specific code state at a specific time) with zero additional tooling. The threat model for developer portfolio evidence doesn't require cryptographic non-repudiation — it requires enough friction that casual fabrication is detectable. + +Source: Schneier, B. (2003). *Beyond Fear*. Copernicus Books. (threat modeling: cost of attack vs. cost of defense) diff --git a/engineering/data-quality-auditor/skills/data-quality-auditor/SKILL.md b/engineering/data-quality-auditor/skills/data-quality-auditor/SKILL.md index 6d487ec9..57b49acd 100644 --- a/engineering/data-quality-auditor/skills/data-quality-auditor/SKILL.md +++ b/engineering/data-quality-auditor/skills/data-quality-auditor/SKILL.md @@ -1,6 +1,6 @@ --- name: data-quality-auditor -description: Audit datasets for completeness, consistency, accuracy, and validity. Profile data distributions, detect anomalies and outliers, surface structural issues, and produce an actionable remediation plan. +description: Audit datasets for completeness, consistency, accuracy, and validity. Profile data distributions, detect anomalies and outliers, surface structural issues, and produce an actionable remediation plan. Use when the user asks to check data quality, profile a dataset, hunt outliers or missing values, or validate data before analysis or model training. --- You are an expert data quality engineer. Your goal is to systematically assess dataset health, surface hidden issues that corrupt downstream analysis, and prescribe prioritized fixes. You move fast, think in impact, and never let "good enough" data quietly poison a model or dashboard. diff --git a/engineering/karpathy-coder/commands/karpathy-check.md b/engineering/karpathy-coder/commands/karpathy-check.md index cb060b0d..4c4a3ada 100644 --- a/engineering/karpathy-coder/commands/karpathy-check.md +++ b/engineering/karpathy-coder/commands/karpathy-check.md @@ -16,8 +16,8 @@ Review your staged changes (or last commit) against Karpathy's 4 coding principl ## What it runs -1. **Principle #2 (Simplicity):** `scripts/complexity_checker.py` on all changed files — detects over-engineering, premature abstractions, deep nesting, long functions -2. **Principle #3 (Surgical):** `scripts/diff_surgeon.py` on the diff — detects comment-only changes, whitespace noise, style drift, drive-by refactors +1. **Principle #2 (Simplicity):** `skills/karpathy-coder/scripts/complexity_checker.py` on all changed files — detects over-engineering, premature abstractions, deep nesting, long functions +2. **Principle #3 (Surgical):** `skills/karpathy-coder/scripts/diff_surgeon.py` on the diff — detects comment-only changes, whitespace noise, style drift, drive-by refactors 3. **Principles #1 + #4 (Think + Goals):** The `karpathy-reviewer` agent reads the diff and applies human-judgment checks — hidden assumptions, missing verification ## Output @@ -36,11 +36,11 @@ Dispatches the `karpathy-reviewer` agent. See `agents/karpathy-reviewer.md`. ## Scripts -- `engineering/karpathy-coder/scripts/complexity_checker.py` -- `engineering/karpathy-coder/scripts/diff_surgeon.py` -- `engineering/karpathy-coder/scripts/assumption_linter.py` -- `engineering/karpathy-coder/scripts/goal_verifier.py` +- `engineering/karpathy-coder/skills/karpathy-coder/scripts/complexity_checker.py` +- `engineering/karpathy-coder/skills/karpathy-coder/scripts/diff_surgeon.py` +- `engineering/karpathy-coder/skills/karpathy-coder/scripts/assumption_linter.py` +- `engineering/karpathy-coder/skills/karpathy-coder/scripts/goal_verifier.py` ## Skill Reference -→ `engineering/karpathy-coder/SKILL.md` +→ `engineering/karpathy-coder/skills/karpathy-coder/SKILL.md` diff --git a/engineering/llm-wiki/agents/wiki-ingestor.md b/engineering/llm-wiki/agents/wiki-ingestor.md index 0df48677..cfb4e93f 100644 --- a/engineering/llm-wiki/agents/wiki-ingestor.md +++ b/engineering/llm-wiki/agents/wiki-ingestor.md @@ -24,7 +24,7 @@ You are spawned **per-ingest**, not as a long-running agent. You do one source a ## Workflow -Follow `references/ingest-workflow.md` in the llm-wiki skill. Summary: +Follow `skills/llm-wiki/references/ingest-workflow.md` in the llm-wiki skill. Summary: ### 1. Prep Run `python <plugin>/scripts/ingest_source.py --vault . --source <path> --json` to get the brief (title guess, word count, preview, suggested summary path, whether a summary already exists). diff --git a/engineering/llm-wiki/agents/wiki-librarian.md b/engineering/llm-wiki/agents/wiki-librarian.md index 1b300cd3..14d259a2 100644 --- a/engineering/llm-wiki/agents/wiki-librarian.md +++ b/engineering/llm-wiki/agents/wiki-librarian.md @@ -23,7 +23,7 @@ You are spawned **per-query**, not as a long-running agent. ## Workflow -Follow `references/query-workflow.md`. Summary: +Follow `skills/llm-wiki/references/query-workflow.md`. Summary: ### 1. Read `index.md` first The index is the catalog. Scan it and pick the 3-10 pages most likely to contain the answer. Pick across categories: @@ -62,7 +62,7 @@ This is the compounding move. At the end of the answer, ask: If yes: - Pick the right category (most often `comparisons/` or `synthesis/`) -- Use the appropriate template (see llm-wiki skill's `references/page-formats.md`) +- Use the appropriate template (see llm-wiki skill's `skills/llm-wiki/references/page-formats.md`) - Add frontmatter with `category`, `summary`, `sources` (count), `updated` - Update `wiki/index.md` (inline or via script) - Append to `log.md`: `python <plugin>/scripts/append_log.py --vault . --op create --title "<question>" --detail "filed query response to <path>"` diff --git a/engineering/llm-wiki/agents/wiki-linter.md b/engineering/llm-wiki/agents/wiki-linter.md index 938afa6a..9e8ce2d9 100644 --- a/engineering/llm-wiki/agents/wiki-linter.md +++ b/engineering/llm-wiki/agents/wiki-linter.md @@ -18,7 +18,7 @@ You are spawned **per-lint-pass**, not as a long-running agent. ## Workflow -Follow `references/lint-workflow.md`. Three passes. +Follow `skills/llm-wiki/references/lint-workflow.md`. Three passes. ### Pass 1 — Mechanical (scripts) diff --git a/engineering/llm-wiki/commands/wiki-ingest.md b/engineering/llm-wiki/commands/wiki-ingest.md index e640ca2f..0738f8ff 100644 --- a/engineering/llm-wiki/commands/wiki-ingest.md +++ b/engineering/llm-wiki/commands/wiki-ingest.md @@ -21,13 +21,13 @@ A typical ingest touches **5-15 wiki pages**. You (the user) are in the loop: th ## What happens -1. **Prep** — runs `scripts/ingest_source.py` to get title, preview, and suggested summary path +1. **Prep** — runs `skills/llm-wiki/scripts/ingest_source.py` to get title, preview, and suggested summary path 2. **Read** — reads the source directly 3. **Discuss** — reports TL;DR, key claims, which pages will be touched, any contradictions 4. **Confirm** — waits for your go-ahead (or redirects) 5. **Write** — creates the source summary, updates 5-15 pages, flags contradictions -6. **Index** — runs `scripts/update_index.py` or edits `wiki/index.md` inline -7. **Log** — runs `scripts/append_log.py --op ingest --title "<title>"` +6. **Index** — runs `skills/llm-wiki/scripts/update_index.py` or edits `wiki/index.md` inline +7. **Log** — runs `skills/llm-wiki/scripts/append_log.py --op ingest --title "<title>"` 8. **Report** — bulleted wikilinks to every touched page ## Sub-agent @@ -36,9 +36,9 @@ This command dispatches the `wiki-ingestor` sub-agent for the heavy lifting. See ## Scripts -- `engineering/llm-wiki/scripts/ingest_source.py` — source prep (metadata + preview) -- `engineering/llm-wiki/scripts/update_index.py` — regenerate index -- `engineering/llm-wiki/scripts/append_log.py` — log the ingest +- `engineering/llm-wiki/skills/llm-wiki/scripts/ingest_source.py` — source prep (metadata + preview) +- `engineering/llm-wiki/skills/llm-wiki/scripts/update_index.py` — regenerate index +- `engineering/llm-wiki/skills/llm-wiki/scripts/append_log.py` — log the ingest ## Rules @@ -48,5 +48,5 @@ This command dispatches the `wiki-ingestor` sub-agent for the heavy lifting. See ## Skill Reference -→ `engineering/llm-wiki/SKILL.md` -→ `engineering/llm-wiki/references/ingest-workflow.md` +→ `engineering/llm-wiki/skills/llm-wiki/SKILL.md` +→ `engineering/llm-wiki/skills/llm-wiki/references/ingest-workflow.md` diff --git a/engineering/llm-wiki/commands/wiki-init.md b/engineering/llm-wiki/commands/wiki-init.md index e62f9575..3859f540 100644 --- a/engineering/llm-wiki/commands/wiki-init.md +++ b/engineering/llm-wiki/commands/wiki-init.md @@ -53,8 +53,8 @@ After init: ## Script -- `engineering/llm-wiki/scripts/init_vault.py` +- `engineering/llm-wiki/skills/llm-wiki/scripts/init_vault.py` ## Skill Reference -→ `engineering/llm-wiki/SKILL.md` +→ `engineering/llm-wiki/skills/llm-wiki/SKILL.md` diff --git a/engineering/llm-wiki/commands/wiki-lint.md b/engineering/llm-wiki/commands/wiki-lint.md index 1822a2f8..0ada8b24 100644 --- a/engineering/llm-wiki/commands/wiki-lint.md +++ b/engineering/llm-wiki/commands/wiki-lint.md @@ -21,8 +21,8 @@ Run this weekly, after batch ingests, and always before sharing the wiki. ### Pass 1 — Mechanical (scripts) -- `scripts/lint_wiki.py` — orphans, broken links, stale pages, missing frontmatter, duplicate titles, log gap -- `scripts/graph_analyzer.py` — hubs, sinks, connected components, graph stats +- `skills/llm-wiki/scripts/lint_wiki.py` — orphans, broken links, stale pages, missing frontmatter, duplicate titles, log gap +- `skills/llm-wiki/scripts/graph_analyzer.py` — hubs, sinks, connected components, graph stats ### Pass 2 — Semantic (LLM reads and thinks) @@ -64,9 +64,9 @@ Dispatches the `wiki-linter` sub-agent. See `agents/wiki-linter.md`. ## Scripts -- `engineering/llm-wiki/scripts/lint_wiki.py` -- `engineering/llm-wiki/scripts/graph_analyzer.py` -- `engineering/llm-wiki/scripts/append_log.py` +- `engineering/llm-wiki/skills/llm-wiki/scripts/lint_wiki.py` +- `engineering/llm-wiki/skills/llm-wiki/scripts/graph_analyzer.py` +- `engineering/llm-wiki/skills/llm-wiki/scripts/append_log.py` ## Frequency @@ -79,5 +79,5 @@ Dispatches the `wiki-linter` sub-agent. See `agents/wiki-linter.md`. ## Skill Reference -→ `engineering/llm-wiki/SKILL.md` -→ `engineering/llm-wiki/references/lint-workflow.md` +→ `engineering/llm-wiki/skills/llm-wiki/SKILL.md` +→ `engineering/llm-wiki/skills/llm-wiki/references/lint-workflow.md` diff --git a/engineering/llm-wiki/commands/wiki-log.md b/engineering/llm-wiki/commands/wiki-log.md index 404c38c4..575c626f 100644 --- a/engineering/llm-wiki/commands/wiki-log.md +++ b/engineering/llm-wiki/commands/wiki-log.md @@ -61,4 +61,4 @@ Filed back to comparisons/sae-vs-probing.md. ## Skill Reference -→ `engineering/llm-wiki/SKILL.md` +→ `engineering/llm-wiki/skills/llm-wiki/SKILL.md` diff --git a/engineering/llm-wiki/commands/wiki-query.md b/engineering/llm-wiki/commands/wiki-query.md index d209dc52..c12ff50a 100644 --- a/engineering/llm-wiki/commands/wiki-query.md +++ b/engineering/llm-wiki/commands/wiki-query.md @@ -22,7 +22,7 @@ Ask the wiki a question. The librarian reads `index.md` first, picks relevant pa 1. **Index-first read** — reads `wiki/index.md` to find relevant pages 2. **Drill-in** — reads 3-10 pages in full (synthesis + concepts + sources + entities) 3. **Follow links** — opportunistically follows wikilinks between pages -4. **Fallback search** — if the index isn't enough, runs `scripts/wiki_search.py` (BM25) +4. **Fallback search** — if the index isn't enough, runs `skills/llm-wiki/scripts/wiki_search.py` (BM25) 5. **Synthesize** — composes a direct answer + supporting detail + inline `[[sources/xxx]]` citations + "Related pages" section 6. **Offer to file back** — asks whether to save this as a new wiki page (usually in `comparisons/` or `synthesis/`) @@ -43,8 +43,8 @@ This command dispatches the `wiki-librarian` sub-agent. See `agents/wiki-librari ## Scripts -- `engineering/llm-wiki/scripts/wiki_search.py` — BM25 fallback search -- `engineering/llm-wiki/scripts/append_log.py` — log filed answers +- `engineering/llm-wiki/skills/llm-wiki/scripts/wiki_search.py` — BM25 fallback search +- `engineering/llm-wiki/skills/llm-wiki/scripts/append_log.py` — log filed answers ## Rules @@ -54,5 +54,5 @@ This command dispatches the `wiki-librarian` sub-agent. See `agents/wiki-librari ## Skill Reference -→ `engineering/llm-wiki/SKILL.md` -→ `engineering/llm-wiki/references/query-workflow.md` +→ `engineering/llm-wiki/skills/llm-wiki/SKILL.md` +→ `engineering/llm-wiki/skills/llm-wiki/references/query-workflow.md` diff --git a/engineering/skills/agent-designer/SKILL.md b/engineering/skills/agent-designer/SKILL.md index 6172cd02..d5f792f5 100644 --- a/engineering/skills/agent-designer/SKILL.md +++ b/engineering/skills/agent-designer/SKILL.md @@ -1,279 +1,76 @@ --- name: "agent-designer" -description: "Use when the user asks to design multi-agent systems, create agent architectures, define agent communication patterns, or build autonomous agent workflows." +description: "Use when the user asks to design a multi-agent system, pick an orchestration pattern (supervisor/swarm/pipeline), generate tool schemas for agents, or evaluate agent execution logs for cost, latency, and failure bottlenecks. Examples: 'design an agent architecture for research automation', 'generate Anthropic tool schemas from these tool descriptions', 'analyze these agent run logs for bottlenecks'. NOT for Claude Code workflow files (use workflow-builder) or single-agent prompt design (use agent-workflow-designer)." --- -# Agent Designer - Multi-Agent System Architecture +# Agent Designer — Multi-Agent System Architecture -**Tier:** POWERFUL -**Category:** Engineering -**Tags:** AI agents, architecture, system design, orchestration, multi-agent systems +Design, schema-generate, and evaluate multi-agent systems with three deterministic tools. The scripts are the workflow — do not freehand an architecture when the planner can score one from requirements. -## Overview +## When to use -Agent Designer is a comprehensive toolkit for designing, architecting, and evaluating multi-agent systems. It provides structured approaches to agent architecture patterns, tool design principles, communication strategies, and performance evaluation frameworks for building robust, scalable AI agent systems. +- Designing a new multi-agent system from requirements (pattern choice, roles, comms) +- Generating provider-ready tool schemas (Anthropic + OpenAI formats) from plain tool descriptions +- Evaluating execution logs: success rate, latency distribution, cost, bottlenecks -## Core Capabilities +**When NOT to use:** Claude Code Workflow-tool automations → `workflow-builder`; single-agent workflow scaffolds → `agent-workflow-designer`; multi-agent fan-out at runtime → `agenthub`. -### 1. Agent Architecture Patterns +## Pattern decision table -#### Single Agent Pattern -- **Use Case:** Simple, focused tasks with clear boundaries -- **Pros:** Minimal complexity, easy debugging, predictable behavior -- **Cons:** Limited scalability, single point of failure -- **Implementation:** Direct user-agent interaction with comprehensive tool access +| Choose | When | Watch out for | +|---|---|---| +| Single agent | One bounded task, < ~5 tools | Don't add agents you don't need | +| Supervisor | Central decomposition, specialists report back | Supervisor becomes the bottleneck | +| Pipeline | Strictly sequential stages with handoffs | Rigid order; slowest stage gates throughput | +| Hierarchical | Multiple org layers, > ~8 agents | Communication overhead per level | +| Swarm | Parallel peers, fault tolerance over predictability | Hard to debug; needs consensus rules | -#### Supervisor Pattern -- **Use Case:** Hierarchical task decomposition with centralized control -- **Architecture:** One supervisor agent coordinating multiple specialist agents -- **Pros:** Clear command structure, centralized decision making -- **Cons:** Supervisor bottleneck, complex coordination logic -- **Implementation:** Supervisor receives tasks, delegates to specialists, aggregates results +The planner applies this scoring deterministically — run it rather than picking by feel. -#### Swarm Pattern -- **Use Case:** Distributed problem solving with peer-to-peer collaboration -- **Architecture:** Multiple autonomous agents with shared objectives -- **Pros:** High parallelism, fault tolerance, emergent intelligence -- **Cons:** Complex coordination, potential conflicts, harder to predict -- **Implementation:** Agent discovery, consensus mechanisms, distributed task allocation +## Workflow -#### Hierarchical Pattern -- **Use Case:** Complex systems with multiple organizational layers -- **Architecture:** Tree structure with managers and workers at different levels -- **Pros:** Natural organizational mapping, clear responsibilities -- **Cons:** Communication overhead, potential bottlenecks at each level -- **Implementation:** Multi-level delegation with feedback loops +All paths relative to this skill folder. Each step's JSON output is the next step's design input. -#### Pipeline Pattern -- **Use Case:** Sequential processing with specialized stages -- **Architecture:** Agents arranged in processing pipeline -- **Pros:** Clear data flow, specialized optimization per stage -- **Cons:** Sequential bottlenecks, rigid processing order -- **Implementation:** Message queues between stages, state handoffs +### 1. Design the architecture -### 2. Agent Role Definition +Write a requirements JSON (copy `assets/sample_system_requirements.json` — keys: `goal`, `tasks[]`, `constraints{max_response_time, budget_per_task, concurrent_tasks}`, `team_size`): -#### Role Specification Framework -- **Identity:** Name, purpose statement, core competencies -- **Responsibilities:** Primary tasks, decision boundaries, success criteria -- **Capabilities:** Required tools, knowledge domains, processing limits -- **Interfaces:** Input/output formats, communication protocols -- **Constraints:** Security boundaries, resource limits, operational guidelines +```bash +python3 agent_planner.py requirements.json --format json -o arch +``` -#### Common Agent Archetypes +Emits `arch.json` with `architecture_design` (pattern, agents, communication links), `mermaid_diagram`, and `implementation_roadmap`. Read `architecture_design.pattern` and the per-agent role list; present the mermaid diagram to the user. -**Coordinator Agent** -- Orchestrates multi-agent workflows -- Makes high-level decisions and resource allocation -- Monitors system health and performance -- Handles escalations and conflict resolution +### 2. Generate tool schemas -**Specialist Agent** -- Deep expertise in specific domain (code, data, research) -- Optimized tools and knowledge for specialized tasks -- High-quality output within narrow scope -- Clear handoff protocols for out-of-scope requests +Describe each agent's tools in plain JSON (copy `assets/sample_tool_descriptions.json`), then: -**Interface Agent** -- Handles external interactions (users, APIs, systems) -- Protocol translation and format conversion -- Authentication and authorization management -- User experience optimization +```bash +python3 tool_schema_generator.py tool_descriptions.json --validate -o tools +``` -**Monitor Agent** -- System health monitoring and alerting -- Performance metrics collection and analysis -- Anomaly detection and reporting -- Compliance and audit trail maintenance +Emits `tools.json` (`tool_schemas`, `validation_summary`) plus provider-specific `tools_anthropic.json` / `tools_openai.json`. **Gate: every tool must print `✓ Valid`.** Fix any invalid schema before proceeding — never hand an agent an unvalidated schema. -### 3. Tool Design Principles +### 3. Evaluate execution logs -#### Schema Design -- **Input Validation:** Strong typing, required vs optional parameters -- **Output Consistency:** Standardized response formats, error handling -- **Documentation:** Clear descriptions, usage examples, edge cases -- **Versioning:** Backward compatibility, migration paths +Once the system runs (or against `assets/sample_execution_logs.json` for a dry run): -#### Error Handling Patterns -- **Graceful Degradation:** Partial functionality when dependencies fail -- **Retry Logic:** Exponential backoff, circuit breakers, max attempts -- **Error Propagation:** Structured error responses, error classification -- **Recovery Strategies:** Fallback methods, alternative approaches +```bash +python3 agent_evaluator.py execution_logs.json --detailed -o eval +``` -#### Idempotency Requirements -- **Safe Operations:** Read operations with no side effects -- **Idempotent Writes:** Same operation can be safely repeated -- **State Management:** Version tracking, conflict resolution -- **Atomicity:** All-or-nothing operation completion +Emits `eval.json` with `summary`, `agent_metrics`, `bottleneck_analysis`, `error_analysis`, `cost_breakdown`, `sla_compliance`, and `optimization_recommendations`, plus split files (`eval_errors.json`, `eval_recommendations.json`). -### 4. Communication Patterns +### 4. Verification loop -#### Message Passing -- **Asynchronous Messaging:** Decoupled agents, message queues -- **Message Format:** Structured payloads with metadata -- **Delivery Guarantees:** At-least-once, exactly-once semantics -- **Routing:** Direct messaging, publish-subscribe, broadcast +The design is not done until: -#### Shared State -- **State Stores:** Centralized data repositories -- **Consistency Models:** Strong, eventual, weak consistency -- **Access Patterns:** Read-heavy, write-heavy, mixed workloads -- **Conflict Resolution:** Last-writer-wins, merge strategies +1. `tool_schema_generator.py --validate` reports 0 invalid schemas. +2. `agent_evaluator.py` on a pilot run reports **0 critical issues** (the tool prints `CRITICAL: N critical issues` when found). If N > 0, apply the top item in `eval_recommendations.json`, re-run the pilot, and re-evaluate. +3. Compare your outputs against `expected_outputs/` to confirm the schema shape you're consuming hasn't drifted. -#### Event-Driven Architecture -- **Event Sourcing:** Immutable event logs, state reconstruction -- **Event Types:** Domain events, system events, integration events -- **Event Processing:** Real-time, batch, stream processing -- **Event Schema:** Versioned event formats, backward compatibility +## References -### 5. Guardrails and Safety - -#### Input Validation -- **Schema Enforcement:** Required fields, type checking, format validation -- **Content Filtering:** Harmful content detection, PII scrubbing -- **Rate Limiting:** Request throttling, resource quotas -- **Authentication:** Identity verification, authorization checks - -#### Output Filtering -- **Content Moderation:** Harmful content removal, quality checks -- **Consistency Validation:** Logic checks, constraint verification -- **Formatting:** Standardized output formats, clean presentation -- **Audit Logging:** Decision trails, compliance records - -#### Human-in-the-Loop -- **Approval Workflows:** Critical decision checkpoints -- **Escalation Triggers:** Confidence thresholds, risk assessment -- **Override Mechanisms:** Human judgment precedence -- **Feedback Loops:** Human corrections improve system behavior - -### 6. Evaluation Frameworks - -#### Task Completion Metrics -- **Success Rate:** Percentage of tasks completed successfully -- **Partial Completion:** Progress measurement for complex tasks -- **Task Classification:** Success criteria by task type -- **Failure Analysis:** Root cause identification and categorization - -#### Quality Assessment -- **Output Quality:** Accuracy, relevance, completeness measures -- **Consistency:** Response variability across similar inputs -- **Coherence:** Logical flow and internal consistency -- **User Satisfaction:** Feedback scores, usage patterns - -#### Cost Analysis -- **Token Usage:** Input/output token consumption per task -- **API Costs:** External service usage and charges -- **Compute Resources:** CPU, memory, storage utilization -- **Time-to-Value:** Cost per successful task completion - -#### Latency Distribution -- **Response Time:** End-to-end task completion time -- **Processing Stages:** Bottleneck identification per stage -- **Queue Times:** Wait times in processing pipelines -- **Resource Contention:** Impact of concurrent operations - -### 7. Orchestration Strategies - -#### Centralized Orchestration -- **Workflow Engine:** Central coordinator manages all agents -- **State Management:** Centralized workflow state tracking -- **Decision Logic:** Complex routing and branching rules -- **Monitoring:** Comprehensive visibility into all operations - -#### Decentralized Orchestration -- **Peer-to-Peer:** Agents coordinate directly with each other -- **Service Discovery:** Dynamic agent registration and lookup -- **Consensus Protocols:** Distributed decision making -- **Fault Tolerance:** No single point of failure - -#### Hybrid Approaches -- **Domain Boundaries:** Centralized within domains, federated across -- **Hierarchical Coordination:** Multiple orchestration levels -- **Context-Dependent:** Strategy selection based on task type -- **Load Balancing:** Distribute coordination responsibility - -### 8. Memory Patterns - -#### Short-Term Memory -- **Context Windows:** Working memory for current tasks -- **Session State:** Temporary data for ongoing interactions -- **Cache Management:** Performance optimization strategies -- **Memory Pressure:** Handling capacity constraints - -#### Long-Term Memory -- **Persistent Storage:** Durable data across sessions -- **Knowledge Base:** Accumulated domain knowledge -- **Experience Replay:** Learning from past interactions -- **Memory Consolidation:** Transferring from short to long-term - -#### Shared Memory -- **Collaborative Knowledge:** Shared learning across agents -- **Synchronization:** Consistency maintenance strategies -- **Access Control:** Permission-based memory access -- **Memory Partitioning:** Isolation between agent groups - -### 9. Scaling Considerations - -#### Horizontal Scaling -- **Agent Replication:** Multiple instances of same agent type -- **Load Distribution:** Request routing across agent instances -- **Resource Pooling:** Shared compute and storage resources -- **Geographic Distribution:** Multi-region deployments - -#### Vertical Scaling -- **Capability Enhancement:** More powerful individual agents -- **Tool Expansion:** Broader tool access per agent -- **Context Expansion:** Larger working memory capacity -- **Processing Power:** Higher throughput per agent - -#### Performance Optimization -- **Caching Strategies:** Response caching, tool result caching -- **Parallel Processing:** Concurrent task execution -- **Resource Optimization:** Efficient resource utilization -- **Bottleneck Elimination:** Systematic performance tuning - -### 10. Failure Handling - -#### Retry Mechanisms -- **Exponential Backoff:** Increasing delays between retries -- **Jitter:** Random delay variation to prevent thundering herd -- **Maximum Attempts:** Bounded retry behavior -- **Retry Conditions:** Transient vs permanent failure classification - -#### Fallback Strategies -- **Graceful Degradation:** Reduced functionality when systems fail -- **Alternative Approaches:** Different methods for same goals -- **Default Responses:** Safe fallback behaviors -- **User Communication:** Clear failure messaging - -#### Circuit Breakers -- **Failure Detection:** Monitoring failure rates and response times -- **State Management:** Open, closed, half-open circuit states -- **Recovery Testing:** Gradual return to normal operation -- **Cascading Failure Prevention:** Protecting upstream systems - -## Implementation Guidelines - -### Architecture Decision Process -1. **Requirements Analysis:** Understand system goals, constraints, scale -2. **Pattern Selection:** Choose appropriate architecture pattern -3. **Agent Design:** Define roles, responsibilities, interfaces -4. **Tool Architecture:** Design tool schemas and error handling -5. **Communication Design:** Select message patterns and protocols -6. **Safety Implementation:** Build guardrails and validation -7. **Evaluation Planning:** Define success metrics and monitoring -8. **Deployment Strategy:** Plan scaling and failure handling - -### Quality Assurance -- **Testing Strategy:** Unit, integration, and system testing approaches -- **Monitoring:** Real-time system health and performance tracking -- **Documentation:** Architecture documentation and runbooks -- **Security Review:** Threat modeling and security assessments - -### Continuous Improvement -- **Performance Monitoring:** Ongoing system performance analysis -- **User Feedback:** Incorporating user experience improvements -- **A/B Testing:** Controlled experiments for system improvements -- **Knowledge Base Updates:** Continuous learning and adaptation - -This skill provides the foundation for designing robust, scalable multi-agent systems that can handle complex tasks while maintaining safety, reliability, and performance at scale. \ No newline at end of file +- `references/agent_architecture_patterns.md` — pattern trade-offs in depth +- `references/tool_design_best_practices.md` — schema, idempotency, error-handling rules +- `references/evaluation_methodology.md` — metric definitions the evaluator implements diff --git a/engineering/skills/agent-designer/agent_evaluator.py b/engineering/skills/agent-designer/agent_evaluator.py index 709171c9..8d86c56a 100644 --- a/engineering/skills/agent-designer/agent_evaluator.py +++ b/engineering/skills/agent-designer/agent_evaluator.py @@ -777,6 +777,7 @@ class AgentEvaluator: "latency_reduction": min(0.5, (system_metrics.average_duration_ms - 5000) / system_metrics.average_duration_ms), "throughput_improvement": 1.5 }, + estimated_cost_savings=None, estimated_performance_gain=1.4, implementation_steps=[ "Profile and optimize slow operations", @@ -803,6 +804,7 @@ class AgentEvaluator: "reliability_improvement": 1.1 }, estimated_cost_savings=system_metrics.total_cost_usd * (error_analysis.percentage / 100) * 0.5, + estimated_performance_gain=None, implementation_steps=error_analysis.suggested_fixes, risks=["May require significant code changes"], prerequisites=["Root cause analysis", "Testing framework"] @@ -818,6 +820,7 @@ class AgentEvaluator: description=bottleneck.description, implementation_effort="medium", expected_impact=bottleneck.estimated_improvement, + estimated_cost_savings=None, estimated_performance_gain=list(bottleneck.estimated_improvement.values())[0] if bottleneck.estimated_improvement else 1.1, implementation_steps=bottleneck.optimization_suggestions, risks=["System downtime during implementation", "Potential cascade effects"], @@ -836,6 +839,7 @@ class AgentEvaluator: "throughput_improvement": 2.0, "scalability_headroom": 5.0 }, + estimated_cost_savings=None, estimated_performance_gain=2.0, implementation_steps=[ "Implement horizontal scaling for agents", diff --git a/engineering/skills/api-design-reviewer/SKILL.md b/engineering/skills/api-design-reviewer/SKILL.md index 2da3ca75..94b8292c 100644 --- a/engineering/skills/api-design-reviewer/SKILL.md +++ b/engineering/skills/api-design-reviewer/SKILL.md @@ -13,6 +13,21 @@ description: "Comprehensive REST API design review with automated linting, break The API Design Reviewer skill provides comprehensive analysis and review of API designs, focusing on REST conventions, best practices, and industry standards. This skill helps engineering teams build consistent, maintainable, and well-designed APIs through automated linting, breaking change detection, and design scorecards. +## Quick Start — run the tools first + +```bash +# 1. Lint an OpenAPI/Swagger spec for convention violations +python3 scripts/api_linter.py openapi.json --format json -o lint.json + +# 2. Detect breaking changes between two spec versions (gate: exits non-zero with --exit-on-breaking) +python3 scripts/breaking_change_detector.py openapi-v1.json openapi-v2.json --format json --exit-on-breaking -o breaking.json + +# 3. Score overall design quality (gate: --min-grade fails below threshold) +python3 scripts/api_scorecard.py openapi.json --format json --min-grade B -o scorecard.json +``` + +Review flow: run all three, report linter findings + breaking changes + grade to the user, fix, then re-run until the linter is clean, `--exit-on-breaking` passes (or breaking changes are version-bumped), and the scorecard meets the agreed `--min-grade`. Never sign off an API review on prose alone — attach the tool outputs. + ## Core Capabilities ### 1. API Linting and Convention Analysis @@ -157,7 +172,7 @@ Accept: application/vnd.myapi.v1+json } ], "requestId": "req-123456", - "timestamp": "2024-02-16T13:00:00Z" + "timestamp": "2026-02-16T13:00:00Z" } } ``` @@ -381,7 +396,7 @@ Provides comprehensive scoring of API design quality. ### Pre-commit Hooks ```bash #!/bin/bash -python engineering/api-design-reviewer/scripts/api_linter.py api/openapi.json +python engineering/skills/api-design-reviewer/scripts/api_linter.py api/openapi.json if [ $? -ne 0 ]; then echo "API linting failed. Please fix the issues before committing." exit 1 @@ -414,8 +429,5 @@ fi 9. **Missing Rate Limiting**: Protect your API from abuse and overload 10. **Inadequate Testing**: Test all aspects including error cases and edge conditions -## Conclusion - -The API Design Reviewer skill provides a comprehensive framework for building, reviewing, and maintaining high-quality REST APIs. By following these guidelines and using the provided tools, development teams can create APIs that are consistent, well-documented, secure, and maintainable. Regular use of the linting, breaking change detection, and scoring tools ensures continuous improvement and helps maintain API quality throughout the development lifecycle. \ No newline at end of file diff --git a/engineering/skills/api-design-reviewer/scripts/api_linter.py b/engineering/skills/api-design-reviewer/scripts/api_linter.py index 53637d5e..6bd4c919 100644 --- a/engineering/skills/api-design-reviewer/scripts/api_linter.py +++ b/engineering/skills/api-design-reviewer/scripts/api_linter.py @@ -826,6 +826,35 @@ class APILinter: return "\n".join(report_lines) +# Embedded sample OpenAPI spec — intentionally imperfect (a verb in a URL, a +# snake_case property) so --sample produces a representative report. +SAMPLE_OPENAPI_SPEC = { + "openapi": "3.0.0", + "info": {"title": "Sample API", "version": "1.0.0"}, + "servers": [{"url": "https://api.example.com"}], + "paths": { + "/user-profiles/{userId}": { + "get": { + "summary": "Get a user profile", + "responses": {"200": {"description": "OK"}, "404": {"description": "Not found"}}, + "parameters": [{"name": "userId", "in": "path", "required": True}], + } + }, + "/user-profiles/create": { + "post": { + "summary": "Create a user profile (verb-in-URL anti-pattern)", + "responses": {"201": {"description": "Created"}}, + } + }, + }, + "components": { + "schemas": { + "UserProfile": {"properties": {"first_name": {"type": "string"}}} + } + }, +} + + def main(): """Main CLI entry point.""" parser = argparse.ArgumentParser( @@ -836,13 +865,21 @@ Examples: python api_linter.py openapi.json python api_linter.py --format json openapi.json > report.json python api_linter.py --raw-endpoints endpoints.json + python api_linter.py --sample --format json """ ) - + parser.add_argument( 'input_file', + nargs='?', help='Input file: OpenAPI/Swagger JSON file or raw endpoints JSON' ) + + parser.add_argument( + '--sample', + action='store_true', + help='Lint an embedded sample OpenAPI spec (no input file needed)' + ) parser.add_argument( '--format', @@ -863,17 +900,22 @@ Examples: ) args = parser.parse_args() - - # Load input file - try: - with open(args.input_file, 'r') as f: - input_data = json.load(f) - except FileNotFoundError: - print(f"Error: Input file '{args.input_file}' not found.", file=sys.stderr) - return 1 - except json.JSONDecodeError as e: - print(f"Error: Invalid JSON in '{args.input_file}': {e}", file=sys.stderr) - return 1 + + # Load input data — from the embedded sample or the input file + if args.sample: + input_data = SAMPLE_OPENAPI_SPEC + else: + if not args.input_file: + parser.error("input_file is required (or use --sample)") + try: + with open(args.input_file, 'r') as f: + input_data = json.load(f) + except FileNotFoundError: + print(f"Error: Input file '{args.input_file}' not found.", file=sys.stderr) + return 1 + except json.JSONDecodeError as e: + print(f"Error: Invalid JSON in '{args.input_file}': {e}", file=sys.stderr) + return 1 # Initialize linter and run analysis linter = APILinter() diff --git a/engineering/skills/changelog-generator/README.md b/engineering/skills/changelog-generator/README.md index 4b91dc25..7fd35eaa 100644 --- a/engineering/skills/changelog-generator/README.md +++ b/engineering/skills/changelog-generator/README.md @@ -20,12 +20,14 @@ python3 scripts/commit_linter.py --from-ref origin/main --to-ref HEAD --strict - - `scripts/generate_changelog.py`: parse commits, infer semver bump, render markdown/JSON, optional file prepend - `scripts/commit_linter.py`: validate commit subjects against Conventional Commits rules +- `scripts/version_bumper.py`: compute the recommended next version from `git log --oneline` output (`--current-version`, `--prerelease`, `--include-commands`) ## References - `references/ci-integration.md` - `references/changelog-formatting-guide.md` - `references/monorepo-strategy.md` +- `references/hotfix-procedures.md` (hotfix severity SLAs + rollback triggers, absorbed from the retired release-manager skill) ## Installation diff --git a/engineering/skills/changelog-generator/SKILL.md b/engineering/skills/changelog-generator/SKILL.md index 5d8c6e5f..f4bd75ff 100644 --- a/engineering/skills/changelog-generator/SKILL.md +++ b/engineering/skills/changelog-generator/SKILL.md @@ -1,6 +1,6 @@ --- name: "changelog-generator" -description: "Produce consistent, auditable release notes from Conventional Commits. Separates commit parsing, semantic-bump logic, and changelog rendering for automated releases with editorial control. Use when cutting a release, generating CHANGELOG.md from git history, or automating release notes in CI." +description: "Produce consistent, auditable release notes from Conventional Commits. Separates commit parsing, semantic-bump logic, and changelog rendering for automated releases with editorial control. Use when cutting a release, generating CHANGELOG.md from git history, computing the next semantic version from commits, automating release notes in CI, or planning a hotfix/rollback. Examples: 'generate the changelog for v1.4.0', 'what version bump do these commits require', 'we need an emergency hotfix process'." --- # Changelog Generator @@ -61,7 +61,18 @@ python3 scripts/generate_changelog.py \ --write CHANGELOG.md ``` -### 4. Lint Commits Before Merge +### 4. Compute the Next Version From Commits + +When the user has not decided the next version, derive it instead of guessing: + +```bash +git log v1.3.0..HEAD --oneline | \ + python3 scripts/version_bumper.py --current-version 1.3.0 --output-format json +``` + +Output JSON contains `recommended_version`, `bump_type` (`major`/`minor`/`patch`/`none`), and with `--include-commands` the exact `git tag` commands. Feed `recommended_version` into `generate_changelog.py --next-version`. Pre-releases: add `--prerelease alpha|beta|rc`. Input must be real `git log --oneline` output (hex hashes); a sample lives at `assets/sample_git_log.txt`. + +### 5. Lint Commits Before Merge ```bash python3 scripts/commit_linter.py --from-ref origin/main --to-ref HEAD --strict --format text @@ -119,11 +130,38 @@ SemVer mapping: 5. Tag releases only after changelog generation succeeds. 6. Keep an `[Unreleased]` section for manual curation when needed. +## Hotfix Severity & SLAs + +When a release goes wrong, classify before acting (full procedures in [references/hotfix-procedures.md](references/hotfix-procedures.md)): + +| Severity | Definition | SLA | Approval | +|---|---|---|---| +| P0 — Critical | Outage, data loss, exploited vulnerability | Fix deployed ≤ 2h; emergency deploy bypasses normal gates | Engineering Lead + On-call Manager | +| P1 — High | Major feature broken, significant user impact | Fix deployed ≤ 24h; expedited review | Engineering Lead + Product Manager | +| P2 — Medium | Minor issues, limited impact | Next release cycle | Standard PR review | + +Hotfix branch comes from the last stable tag, contains the minimal fix only, and gets its own patch-bump changelog entry via the workflow above. + +## Rollback Triggers + +Pre-commit to these thresholds before tagging; roll back when any fires: + +| Trigger | Threshold | +|---|---| +| Error rate spike | > 2x baseline within 30 min | +| Performance degradation | > 50% latency increase | +| Feature failure | Core functionality broken | +| Security incident | Vulnerability being exploited | +| Data corruption | Database integrity compromised | + +Prefer feature-flag disable over code rollback; database rollbacks only for non-destructive migrations (forward-only migrations preferred). See [references/hotfix-procedures.md](references/hotfix-procedures.md). + ## References - [references/ci-integration.md](references/ci-integration.md) - [references/changelog-formatting-guide.md](references/changelog-formatting-guide.md) - [references/monorepo-strategy.md](references/monorepo-strategy.md) +- [references/hotfix-procedures.md](references/hotfix-procedures.md) - [README.md](README.md) ## Release Governance diff --git a/engineering/skills/release-manager/assets/sample_git_log.txt b/engineering/skills/changelog-generator/assets/sample_git_log.txt similarity index 100% rename from engineering/skills/release-manager/assets/sample_git_log.txt rename to engineering/skills/changelog-generator/assets/sample_git_log.txt diff --git a/engineering/skills/release-manager/references/hotfix-procedures.md b/engineering/skills/changelog-generator/references/hotfix-procedures.md similarity index 100% rename from engineering/skills/release-manager/references/hotfix-procedures.md rename to engineering/skills/changelog-generator/references/hotfix-procedures.md diff --git a/engineering/skills/release-manager/version_bumper.py b/engineering/skills/changelog-generator/scripts/version_bumper.py similarity index 100% rename from engineering/skills/release-manager/version_bumper.py rename to engineering/skills/changelog-generator/scripts/version_bumper.py diff --git a/engineering/skills/chaos-engineering/scripts/blast_radius_calculator.py b/engineering/skills/chaos-engineering/scripts/blast_radius_calculator.py index 1ab87664..1589ad6f 100755 --- a/engineering/skills/chaos-engineering/scripts/blast_radius_calculator.py +++ b/engineering/skills/chaos-engineering/scripts/blast_radius_calculator.py @@ -70,9 +70,11 @@ def render_text(result): def main(): ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter) - ap.add_argument("--traffic-share", type=float, required=True, help="Fraction (0-1) of traffic affected") - ap.add_argument("--user-pop", type=int, required=True, help="Total user population") - ap.add_argument("--duration-min", type=int, required=True, help="Experiment duration in minutes") + ap.add_argument("--traffic-share", type=float, help="Fraction (0-1) of traffic affected") + ap.add_argument("--user-pop", type=int, help="Total user population") + ap.add_argument("--duration-min", type=int, help="Experiment duration in minutes") + ap.add_argument("--sample", action="store_true", + help="Run with embedded sample inputs (5%% traffic, 100k users, 30 min)") ap.add_argument("--baseline-availability", type=float, default=0.999, help="Baseline availability (default: 0.999)") ap.add_argument("--expected-impact-availability", type=float, default=0.95, dest="impact_avail", help="Availability under fault (default: 0.95)") @@ -81,9 +83,16 @@ def main(): ap.add_argument("--format", choices=["text", "json"], default="text") args = ap.parse_args() + if args.sample: + traffic_share, user_pop, duration_min = 0.05, 100000, 30 + elif None not in (args.traffic_share, args.user_pop, args.duration_min): + traffic_share, user_pop, duration_min = args.traffic_share, args.user_pop, args.duration_min + else: + ap.error("--traffic-share, --user-pop and --duration-min are required (or use --sample)") + try: result = calculate( - args.traffic_share, args.user_pop, args.duration_min, + traffic_share, user_pop, duration_min, args.baseline_availability, args.impact_avail, args.monthly_budget_min, ) except ValueError as e: diff --git a/engineering/skills/ci-cd-pipeline-builder/scripts/pipeline_generator.py b/engineering/skills/ci-cd-pipeline-builder/scripts/pipeline_generator.py index 428b0c54..09f22ee9 100755 --- a/engineering/skills/ci-cd-pipeline-builder/scripts/pipeline_generator.py +++ b/engineering/skills/ci-cd-pipeline-builder/scripts/pipeline_generator.py @@ -168,6 +168,21 @@ def github_yaml(stack: Dict[str, Any]) -> str: ] ) + if not any(lang in langs for lang in ("node", "python", "go")): + # terraform/docker-only (or unrecognized) stacks: run detected commands directly + lines.extend( + [ + " ci:", + " runs-on: ubuntu-latest", + " steps:", + " - uses: actions/checkout@v4", + ] + ) + if "terraform" in langs: + lines.append(" - uses: hashicorp/setup-terraform@v3") + for cmd in lint_cmds + test_cmds + build_cmds: + lines.append(f" - run: {cmd}") + return "\n".join(lines) + "\n" @@ -251,6 +266,22 @@ def gitlab_yaml(stack: Dict[str, Any]) -> str: ] ) + if not any(lang in langs for lang in ("node", "python", "go")): + # terraform/docker-only (or unrecognized) stacks: run detected commands directly + image = "hashicorp/terraform:1.9" if "terraform" in langs else "alpine:3.20" + for stage, cmds in (("lint", lint_cmds), ("test", test_cmds), ("build", build_cmds)): + lines.extend( + [ + "", + f"generic_{stage}:", + f" image: {image}", + f" stage: {stage}", + " script:", + ] + ) + for cmd in cmds: + lines.append(f" - {cmd}") + return "\n".join(lines) + "\n" diff --git a/engineering/skills/ci-cd-pipeline-builder/scripts/stack_detector.py b/engineering/skills/ci-cd-pipeline-builder/scripts/stack_detector.py index 84e6c272..ff5a2a2b 100755 --- a/engineering/skills/ci-cd-pipeline-builder/scripts/stack_detector.py +++ b/engineering/skills/ci-cd-pipeline-builder/scripts/stack_detector.py @@ -82,6 +82,7 @@ def detect(repo: Path) -> StackReport: "requirements": (repo / "requirements.txt").exists(), "go_mod": (repo / "go.mod").exists(), "dockerfile": (repo / "Dockerfile").exists(), + "terraform": any(repo.glob("*.tf")) or (repo / "terraform").is_dir(), "vercel": (repo / "vercel.json").exists(), "helm": (repo / "helm").exists() or (repo / "charts").exists(), "k8s": (repo / "k8s").exists() or (repo / "kubernetes").exists(), @@ -107,6 +108,12 @@ def detect(repo: Path) -> StackReport: if signals["go_mod"]: languages.append("go") + if signals["terraform"]: + languages.append("terraform") + + if signals["dockerfile"]: + languages.append("docker") + scripts = read_package_scripts(repo) lint_commands: List[str] = [] test_commands: List[str] = [] @@ -128,6 +135,16 @@ def detect(repo: Path) -> StackReport: test_commands.append("go test ./...") build_commands.append("go build ./...") + if "terraform" in languages: + tf_dir = "terraform" if (repo / "terraform").is_dir() and not any(repo.glob("*.tf")) else "." + lint_commands.append(f"terraform -chdir={tf_dir} fmt -check -recursive") + test_commands.append(f"terraform -chdir={tf_dir} validate") + build_commands.append(f"terraform -chdir={tf_dir} plan -input=false") + + if "docker" in languages: + lint_commands.append("hadolint Dockerfile") + build_commands.append("docker build -t app:ci .") + return StackReport( repo=str(repo.resolve()), languages=sorted(set(languages)), diff --git a/engineering/skills/command-guide/SKILL.md b/engineering/skills/command-guide/SKILL.md deleted file mode 100644 index d1d73910..00000000 --- a/engineering/skills/command-guide/SKILL.md +++ /dev/null @@ -1,314 +0,0 @@ ---- -name: "command-guide" -description: > - Claude Code Command Selection Guide - Automatically recommend and select the right - commands, agents, and skills in Claude Code. - Use when: (1) user is unsure which command or tool to use, (2) needs to decide which - agent/skill best fits the current task, (3) querying usage scenarios for /plan, /tdd, - /compact, /loop and other commands, (4) understanding when to invoke planner, - code-reviewer, build-error-resolver and other agents, (5) needs command cheat sheet - or decision flowchart. - Triggers: "which command to use", "which agent", "command selection", "how to use /plan", - "when to use /compact", "agent selection guide", "command cheat sheet", "skill recommendation". ---- - -# Claude Code Command Selection Guide - -This skill helps you choose the most appropriate command, agent, or skill for different scenarios. - -## Quick Decision Flowchart - -```mermaid -graph TD - A[User Request] --> B{Request Type?} - B -->|New Feature| C[/plan] - B -->|Bug Fix| D[/tdd or build-error-resolver] - B -->|Code Review| E[/code-review or code-reviewer agent] - B -->|Testing| F[/e2e or tdd-guide agent] - B -->|Context Too Long| G[/compact] - B -->|Documentation| H[/docs or docs-lookup agent] - B -->|Looping Task| I[/loop] - B -->|Security Review| J[security-reviewer agent] - - C --> K[planner agent] - D --> L{Build Failed?} - L -->|Yes| M[build-error-resolver] - L -->|No| N[tdd-guide] - E --> O[code-reviewer] - F --> P[e2e-runner] -``` - -## 1. Built-in Slash Commands - -### Session Management Commands - -| Command | Use Case | Example | -|---------|----------|---------| -| `/compact` | Context too long (>150K tokens), slow response, task phase transition | `/compact` or auto-trigger | -| `/clear` | Start fresh conversation, clear history | `/clear` | -| `/loop` | Periodic task execution, automated looping work | `/loop 5m check build status` | -| `/help` | View help, learn commands | `/help` | -| `/fast` | Need faster response (Opus 4.6 only) | `/fast` | -| `/model` | Switch model | `/model sonnet` | - -### Development Workflow Commands - -| Command | Use Case | Activation Timing | -|---------|----------|-------------------| -| `/plan` | Start new feature, architecture refactor, complex tasks | **Enter Plan Mode** | -| `/tdd` | Write tests, TDD development workflow | When test guidance needed | -| `/e2e` | E2E testing, critical user flow verification | When browser testing needed | -| `/code-review` | Code quality review | After writing code | -| `/build-fix` | Build failure, type errors | When build fails | -| `/learn` | Extract patterns from session, learning | Before session ends | -| `/skill-create` | Create new skill from git history | When repeating patterns found | - -### Documentation & Query Commands - -| Command | Use Case | Example | -|---------|----------|---------| -| `/docs` | Update project documentation | `/docs` | -| `/update-codemaps` | Update code maps | `/update-codemaps` | -| `/remember` | Save memory to memory system | `/remember user prefers concise output` | -| `/tasks` | View task list | `/tasks` | - ---- - -## 2. Agents Selection - -### Development Workflow Agents - -| Agent | Trigger Condition | Purpose | -|-------|-------------------|---------| -| `planner` | Complex feature request, architectural decision | Create implementation plan | -| `architect` | System design, tech stack selection | Architecture analysis and decisions | -| `tdd-guide` | New feature, bug fix | TDD workflow guidance | -| `code-reviewer` | **Invoke immediately after writing code** | Code quality review | -| `security-reviewer` | Handling auth, API, sensitive data | Security vulnerability detection | - -### Problem Solving Agents - -| Agent | Trigger Condition | Purpose | -|-------|-------------------|---------| -| `build-error-resolver` | **Invoke immediately when build fails** | Fix build/type errors | -| `e2e-runner` | Critical user flows, before PR | E2E test execution | -| `refactor-cleaner` | Code maintenance, dead code cleanup | Dead code detection and cleanup | -| `doc-updater` | Update docs, codemaps | Documentation sync | - -### Research & Exploration Agents - -| Agent | Trigger Condition | Purpose | -|-------|-------------------|---------| -| `Explore` | Codebase exploration, file finding | Quick codebase exploration | -| `general-purpose` | Complex multi-step tasks | General task handling | -| `docs-lookup` | Query library/framework docs | Get latest API documentation | - ---- - -## 3. Skills Selection - -### Workflow Skills - -| Skill | Trigger Timing | Purpose | -|-------|----------------|---------| -| `tdd-workflow` | Developing new feature/fixing bug | Complete TDD workflow guidance | -| `verification-loop` | After feature completion, before PR | Comprehensive verification (build/test/lint/security) | -| `strategic-compact` | Long session, context pressure | Guide when to manually `/compact` | - -### Architecture & Pattern Skills - -| Skill | Trigger Timing | Purpose | -|-------|----------------|---------| -| `frontend-patterns` | Frontend development | React/Next.js/Vue best practices | -| `backend-patterns` | Backend development | API/service architecture patterns | -| `api-design` | API design | RESTful/API design standards | -| `mcp-server-patterns` | MCP server development | MCP configuration and patterns | - -### Testing Skills - -| Skill | Trigger Timing | Purpose | -|-------|----------------|---------| -| `e2e-testing` | E2E testing needs | Playwright test generation | -| `security-review` | Security review needs | OWASP Top 10 detection | - -### Research Skills - -| Skill | Trigger Timing | Purpose | -|-------|----------------|---------| -| `deep-research` | Need deep research | Multi-round search and research | -| `exa-search` | Need web search | Web content search | -| `documentation-lookup` | Query library docs | Context7 documentation query | - ---- - -## 4. Scenario Decision Matrix - -### By Task Phase - -| Phase | Recommended Tool Combination | Reason | -|-------|------------------------------|--------| -| **Requirements Analysis** | `planner` + `Explore` | Plan first, explore later | -| **Architecture Design** | `architect` + `api-design` skill | Professional architecture guidance | -| **Pre-Development** | `tdd-guide` + `tdd-workflow` skill | Test first | -| **During Development** | Direct edit + quick iteration | Stay in flow | -| **Post-Development** | `code-reviewer` + `verification-loop` | Quality gate | -| **Testing Phase** | `e2e-runner` + `e2e-testing` skill | Complete test coverage | -| **Before PR** | `security-reviewer` + `verification-loop` | Final verification | -| **Build Failure** | `build-error-resolver` | Focused fix | - -### By Problem Type - -| Problem | Invoke Immediately | Note | -|---------|--------------------|------| -| Build failure | `build-error-resolver` | Minimal changes, quick fix | -| Type error | `build-error-resolver` | TypeScript specialist | -| Bug fix | `tdd-guide` | Write test then fix | -| Security vulnerability | `security-reviewer` | OWASP detection | -| Poor code quality | `code-reviewer` | Immediate review | -| Missing documentation | `doc-updater` | Auto update | -| Dead code | `refactor-cleaner` | Safe cleanup | - -### By Development Type - -| Development Type | Skills Combination | -|------------------|--------------------| -| Frontend feature | `frontend-patterns` + `tdd-workflow` | -| Backend API | `backend-patterns` + `api-design` + `tdd-workflow` | -| MCP server | `mcp-server-patterns` + `tdd-workflow` | -| Database | `database-reviewer` agent | -| Security feature | `security-reviewer` + `security-review` skill | - ---- - -## 5. Parallel Execution Strategy - -### Parallelizable Scenarios - -Recommended: Launch multiple independent tasks simultaneously - -Scenario: Preparing PR after code completion -- Agent 1: code-reviewer (code quality) -- Agent 2: security-reviewer (security review) -- Agent 3: e2e-runner (E2E tests) - -Scenario: Large refactor analysis -- Agent 1: architect (architecture analysis) -- Agent 2: Explore (code exploration) -- Agent 3: refactor-cleaner (dead code detection) - -### Sequential Execution Required - -Cannot parallelize: Dependencies exist - -Scenario: Fixing build error -- Sequence: build-error-resolver -> test verification -> code-reviewer - -Scenario: New feature development -- Sequence: planner -> tdd-guide (write tests) -> implementation -> code-reviewer - ---- - -## 6. Auto-Trigger Rules - -### Invoke Without User Request - -| Situation | Auto Action | -|-----------|-------------| -| Code written/modified | **Immediately invoke** `code-reviewer` | -| Build fails | **Immediately invoke** `build-error-resolver` | -| Complex feature request | **Immediately invoke** `planner` | -| Handling auth/sensitive data | **Immediately invoke** `security-reviewer` | -| New feature/bug fix | **Immediately invoke** `tdd-guide` | -| Architectural decision | **Immediately invoke** `architect` | - ---- - -## 7. Context Management Timing - -| Indicator | Trigger `/compact` | -|-----------|-------------------| -| Token > 150K | Immediately compact | -| Slow response | Suggest compact | -| Task phase switch | Compact at boundary | -| Major milestone completed | Compact then continue | -| Debugging ends -> new task | Clear debug traces | - -**Best Practices**: -- Compact after research, before implementation (preserve plan) -- Compact after milestone completion (clear intermediate state) -- Don't compact mid-implementation (lose variables/paths) - ---- - -## 8. Command Cheat Sheet - -``` -Development Workflow: -/plan -> Enter planning mode (complex tasks) -/tdd -> TDD workflow -/e2e -> E2E testing -/code-review -> Code review -/build-fix -> Fix build - -Session Management: -/compact -> Compact context -/clear -> Clear session -/loop -> Looping task -/fast -> Fast mode - -Documentation & Memory: -/docs -> Update docs -/remember -> Save memory -/tasks -> View tasks - -Help: -/help -> View all commands -``` - ---- - -## 9. Usage Examples - -### Example 1: New Feature Development - -User: Add user authentication feature - -Workflow: -1. /plan -> planner agent creates plan -2. tdd-guide -> write tests -3. Implementation -> edit code -4. code-reviewer -> code review -5. security-reviewer -> security review (auth sensitive) -6. e2e-runner -> E2E tests -7. /compact -> compact after milestone completion - -### Example 2: Build Failure - -User: npm run build failed - -Workflow: -1. build-error-resolver -> analyze error, minimal fix -2. Verify build success -3. code-reviewer -> check fix quality - -### Example 3: Code Refactoring - -User: Refactor authentication module - -Workflow: -1. architect -> architecture analysis -2. planner -> implementation plan -3. refactor-cleaner -> dead code detection -4. tdd-guide -> ensure test coverage -5. Implementation -> refactor code -6. verification-loop -> comprehensive verification - ---- - -**Core Principles**: -1. **Plan first, implement later** - Use `/plan` for complex tasks -2. **Test first** - Use `tdd-guide` for new features -3. **Review immediately after coding** - Use `code-reviewer` when code complete -4. **Fix build immediately when failed** - Use `build-error-resolver` -5. **Review sensitive code** - Use `security-reviewer` for auth/API -6. **Verify comprehensively before PR** - Use `verification-loop` diff --git a/engineering/skills/database-designer/SKILL.md b/engineering/skills/database-designer/SKILL.md index 9fa36ca8..ad2b94cf 100644 --- a/engineering/skills/database-designer/SKILL.md +++ b/engineering/skills/database-designer/SKILL.md @@ -33,6 +33,38 @@ A comprehensive database design skill that provides expert-level analysis, optim - **Rollback Strategy**: Complete reversal capabilities with validation - **Execution Planning**: Ordered migration steps with dependency resolution +## Tool Workflow (run these — do not analyze schemas by hand) + +All paths relative to this skill folder; sample inputs in `assets/`. + +### 1. Analyze the schema + +```bash +python3 schema_analyzer.py --input schema.sql --generate-erd --output-format json -o analysis.json +``` + +Accepts SQL DDL or JSON schema (`assets/sample_schema.sql` / `sample_schema.json`). Output includes normalization findings, missing constraints, naming issues, and a Mermaid ERD — show the ERD to the user and fix flagged issues before optimizing. + +### 2. Optimize indexes against real query patterns + +```bash +python3 index_optimizer.py --schema assets/sample_schema.json --queries assets/sample_query_patterns.json --analyze-existing --format json -o indexes.json +``` + +Write the user's hot queries into a query-patterns JSON first (copy `assets/sample_query_patterns.json`). Output is a priority-ordered list of CREATE INDEX recommendations plus redundant-index removals. + +### 3. Generate the migration + +```bash +python3 migration_generator.py --current current_schema.json --target target_schema.json --zero-downtime --format sql -o migration.sql +``` + +`--zero-downtime` emits an expand-contract plan; `--validate-only` checks feasibility without generating SQL. + +### 4. Verification loop + +Re-run step 1 on the *target* schema and assert the issues found in the first pass are gone; run `migration_generator.py --validate-only` before handing over the migration. + ## Database Design Principles → See references/database-design-reference.md for details @@ -280,10 +312,3 @@ Fixes: - **senior-backend** — application-layer patterns (connection pooling, ORM best practices) - **senior-devops** — infrastructure provisioning for database clusters and replicas ---- - -## Conclusion - -Effective database design requires balancing multiple competing concerns: performance, scalability, maintainability, and business requirements. This skill provides the tools and knowledge to make informed decisions throughout the database lifecycle, from initial schema design through production optimization and evolution. - -The included tools automate common analysis and optimization tasks, while the comprehensive guides provide the theoretical foundation for making sound architectural decisions. Whether building a new system or optimizing an existing one, these resources provide expert-level guidance for creating robust, scalable database solutions. diff --git a/engineering/skills/dependency-auditor/SKILL.md b/engineering/skills/dependency-auditor/SKILL.md index e118bbbd..c35daa0b 100644 --- a/engineering/skills/dependency-auditor/SKILL.md +++ b/engineering/skills/dependency-auditor/SKILL.md @@ -1,338 +1,85 @@ --- name: "dependency-auditor" -description: "Audit and manage dependencies across multi-language projects. Identifies vulnerabilities, license conflicts, transitive dependency risks, and safe-upgrade paths. Use when auditing third-party packages before release, investigating a CVE, planning a major version bump, or running a license-compliance review." +description: "Audit and manage dependencies across multi-language projects. Identifies vulnerabilities, license conflicts, transitive dependency risks, and safe-upgrade paths. Use when auditing third-party packages before release, investigating a CVE, planning a major version bump, or running a license-compliance review. Examples: 'audit our npm dependencies', 'do we have GPL contamination', 'plan the upgrade to React 19'." --- # Dependency Auditor -> **Skill Type:** POWERFUL -> **Category:** Engineering -> **Domain:** Dependency Management & Security +> **Skill Type:** POWERFUL · **Category:** Engineering · **Domain:** Dependency Management & Security -## Overview - -The **Dependency Auditor** is a comprehensive toolkit for analyzing, auditing, and managing dependencies across multi-language software projects. This skill provides deep visibility into your project's dependency ecosystem, enabling teams to identify vulnerabilities, ensure license compliance, optimize dependency trees, and plan safe upgrades. - -In modern software development, dependencies form complex webs that can introduce significant security, legal, and maintenance risks. A single project might have hundreds of direct and transitive dependencies, each potentially introducing vulnerabilities, license conflicts, or maintenance burden. This skill addresses these challenges through automated analysis and actionable recommendations. - -## Core Capabilities - -### 1. Vulnerability Scanning & CVE Matching - -**Comprehensive Security Analysis** -- Scans dependencies against built-in vulnerability databases -- Matches Common Vulnerabilities and Exposures (CVE) patterns -- Identifies known security issues across multiple ecosystems -- Analyzes transitive dependency vulnerabilities -- Provides CVSS scores and exploit assessments -- Tracks vulnerability disclosure timelines -- Maps vulnerabilities to dependency paths - -**Multi-Language Support** -- **JavaScript/Node.js**: package.json, package-lock.json, yarn.lock -- **Python**: requirements.txt, pyproject.toml, Pipfile.lock, poetry.lock -- **Go**: go.mod, go.sum -- **Rust**: Cargo.toml, Cargo.lock -- **Ruby**: Gemfile, Gemfile.lock -- **Java/Maven**: pom.xml, gradle.lockfile -- **PHP**: composer.json, composer.lock -- **C#/.NET**: packages.config, project.assets.json - -### 2. License Compliance & Legal Risk Assessment - -**License Classification System** -- **Permissive Licenses**: MIT, Apache 2.0, BSD (2-clause, 3-clause), ISC -- **Copyleft (Strong)**: GPL (v2, v3), AGPL (v3) -- **Copyleft (Weak)**: LGPL (v2.1, v3), MPL (v2.0) -- **Proprietary**: Commercial, custom, or restrictive licenses -- **Dual Licensed**: Multi-license scenarios and compatibility -- **Unknown/Ambiguous**: Missing or unclear licensing - -**Conflict Detection** -- Identifies incompatible license combinations -- Warns about GPL contamination in permissive projects -- Analyzes license inheritance through dependency chains -- Provides compliance recommendations for distribution -- Generates legal risk matrices for decision-making - -### 3. Outdated Dependency Detection - -**Version Analysis** -- Identifies dependencies with available updates -- Categorizes updates by severity (patch, minor, major) -- Detects pinned versions that may be outdated -- Analyzes semantic versioning patterns -- Identifies floating version specifiers -- Tracks release frequencies and maintenance status - -**Maintenance Status Assessment** -- Identifies abandoned or unmaintained packages -- Analyzes commit frequency and contributor activity -- Tracks last release dates and security patch availability -- Identifies packages with known end-of-life dates -- Assesses upstream maintenance quality - -### 4. Dependency Bloat Analysis - -**Unused Dependency Detection** -- Identifies dependencies that aren't actually imported/used -- Analyzes import statements and usage patterns -- Detects redundant dependencies with overlapping functionality -- Identifies oversized packages for simple use cases -- Maps actual vs. declared dependency usage - -**Redundancy Analysis** -- Identifies multiple packages providing similar functionality -- Detects version conflicts in transitive dependencies -- Analyzes bundle size impact of dependencies -- Identifies opportunities for dependency consolidation -- Maps dependency overlap and duplication - -### 5. Upgrade Path Planning & Breaking Change Risk - -**Semantic Versioning Analysis** -- Analyzes semver patterns to predict breaking changes -- Identifies safe upgrade paths (patch/minor versions) -- Flags major version updates requiring attention -- Tracks breaking changes across dependency updates -- Provides rollback strategies for failed upgrades - -**Risk Assessment Matrix** -- Low Risk: Patch updates, security fixes -- Medium Risk: Minor updates with new features -- High Risk: Major version updates, API changes -- Critical Risk: Dependencies with known breaking changes - -**Upgrade Prioritization** -- Security patches: Highest priority -- Bug fixes: High priority -- Feature updates: Medium priority -- Major rewrites: Planned priority -- Deprecated features: Immediate attention - -### 6. Supply Chain Security - -**Dependency Provenance** -- Verifies package signatures and checksums -- Analyzes package download sources and mirrors -- Identifies suspicious or compromised packages -- Tracks package ownership changes and maintainer shifts -- Detects typosquatting and malicious packages - -**Transitive Risk Analysis** -- Maps complete dependency trees -- Identifies high-risk transitive dependencies -- Analyzes dependency depth and complexity -- Tracks influence of indirect dependencies -- Provides supply chain risk scoring - -### 7. Lockfile Analysis & Deterministic Builds - -**Lockfile Validation** -- Ensures lockfiles are up-to-date with manifests -- Validates integrity hashes and version consistency -- Identifies drift between environments -- Analyzes lockfile conflicts and resolution strategies -- Ensures deterministic, reproducible builds - -**Environment Consistency** -- Compares dependencies across environments (dev/staging/prod) -- Identifies version mismatches between team members -- Validates CI/CD environment consistency -- Tracks dependency resolution differences - -## Technical Architecture - -### Scanner Engine (`dep_scanner.py`) -- Multi-format parser supporting 8+ package ecosystems -- Built-in vulnerability database with 500+ CVE patterns -- Transitive dependency resolution from lockfiles -- JSON and human-readable output formats -- Configurable scanning depth and exclusion patterns - -### License Analyzer (`license_checker.py`) -- License detection from package metadata and files -- Compatibility matrix with 20+ license types -- Conflict detection engine with remediation suggestions -- Risk scoring based on distribution and usage context -- Export capabilities for legal review - -### Upgrade Planner (`upgrade_planner.py`) -- Semantic version analysis with breaking change prediction -- Dependency ordering based on risk and interdependence -- Migration checklists with testing recommendations -- Rollback procedures for failed upgrades -- Timeline estimation for upgrade cycles - -## Use Cases & Applications - -### Security Teams -- **Vulnerability Management**: Continuous scanning for security issues -- **Incident Response**: Rapid assessment of vulnerable dependencies -- **Supply Chain Monitoring**: Tracking third-party security posture -- **Compliance Reporting**: Automated security compliance documentation - -### Legal & Compliance Teams -- **License Auditing**: Comprehensive license compliance verification -- **Risk Assessment**: Legal risk analysis for software distribution -- **Due Diligence**: Dependency licensing for M&A activities -- **Policy Enforcement**: Automated license policy compliance - -### Development Teams -- **Dependency Hygiene**: Regular cleanup of unused dependencies -- **Upgrade Planning**: Strategic dependency update scheduling -- **Performance Optimization**: Bundle size optimization through dep analysis -- **Technical Debt**: Identifying and prioritizing dependency technical debt - -### DevOps & Platform Teams -- **Build Optimization**: Faster builds through dependency optimization -- **Security Automation**: Automated vulnerability scanning in CI/CD -- **Environment Consistency**: Ensuring consistent dependencies across environments -- **Release Management**: Dependency-aware release planning - -## Integration Patterns - -### CI/CD Pipeline Integration -```bash -# Security gate in CI -python dep_scanner.py /project --format json --fail-on-high -python license_checker.py /project --policy strict --format json -``` - -### Scheduled Audits -```bash -# Weekly dependency audit -./audit_dependencies.sh > weekly_report.html -python upgrade_planner.py deps.json --timeline 30days -``` - -### Development Workflow -```bash -# Pre-commit dependency check -python dep_scanner.py . --quick-scan -python license_checker.py . --warn-conflicts -``` - -## Advanced Features - -### Custom Vulnerability Databases -- Support for internal/proprietary vulnerability feeds -- Custom CVE pattern definitions -- Organization-specific risk scoring -- Integration with enterprise security tools - -### Policy-Based Scanning -- Configurable license policies by project type -- Custom risk thresholds and escalation rules -- Automated policy enforcement and notifications -- Exception management for approved violations - -### Reporting & Dashboards -- Executive summaries for management -- Technical reports for development teams -- Trend analysis and dependency health metrics -- Integration with project management tools - -### Multi-Project Analysis -- Portfolio-level dependency analysis -- Shared dependency impact analysis -- Organization-wide license compliance -- Cross-project vulnerability propagation - -## Best Practices - -### Scanning Frequency -- **Security Scans**: Daily or on every commit -- **License Audits**: Weekly or monthly -- **Upgrade Planning**: Monthly or quarterly -- **Full Dependency Audit**: Quarterly - -### Risk Management -1. **Prioritize Security**: Address high/critical CVEs immediately -2. **License First**: Ensure compliance before functionality -3. **Gradual Updates**: Incremental dependency updates -4. **Test Thoroughly**: Comprehensive testing after updates -5. **Monitor Continuously**: Automated monitoring and alerting - -### Team Workflows -1. **Security Champions**: Designate dependency security owners -2. **Review Process**: Mandatory review for new dependencies -3. **Update Cycles**: Regular, scheduled dependency updates -4. **Documentation**: Maintain dependency rationale and decisions -5. **Training**: Regular team education on dependency security - -## Metrics & KPIs - -### Security Metrics -- Mean Time to Patch (MTTP) for vulnerabilities -- Number of high/critical vulnerabilities -- Percentage of dependencies with known vulnerabilities -- Security debt accumulation rate - -### Compliance Metrics -- License compliance percentage -- Number of license conflicts -- Time to resolve compliance issues -- Policy violation frequency - -### Maintenance Metrics -- Percentage of up-to-date dependencies -- Average dependency age -- Number of abandoned dependencies -- Upgrade success rate - -### Efficiency Metrics -- Bundle size reduction percentage -- Unused dependency elimination rate -- Build time improvement -- Developer productivity impact - -## Troubleshooting Guide - -### Common Issues -1. **False Positives**: Tuning vulnerability detection sensitivity -2. **License Ambiguity**: Resolving unclear or multiple licenses -3. **Breaking Changes**: Managing major version upgrades -4. **Performance Impact**: Optimizing scanning for large codebases - -### Resolution Strategies -- Whitelist false positives with documentation -- Contact maintainers for license clarification -- Implement feature flags for risky upgrades -- Use incremental scanning for large projects - -## Future Enhancements - -### Planned Features -- Machine learning for vulnerability prediction -- Automated dependency update pull requests -- Integration with container image scanning -- Real-time dependency monitoring dashboards -- Natural language policy definition - -### Ecosystem Expansion -- Additional language support (Swift, Kotlin, Dart) -- Container and infrastructure dependencies -- Development tool and build system dependencies -- Cloud service and SaaS dependency tracking - ---- +Offline, deterministic dependency auditing across 8+ package ecosystems. The three scripts are pattern-matchers over manifests/lockfiles — they do **not** call live advisory APIs; pair their findings with `npm audit` / `pip-audit` / `cargo audit` for current CVE coverage. ## Quick Start ```bash -# Scan project for vulnerabilities and licenses -python scripts/dep_scanner.py /path/to/project +# 1. Scan for vulnerabilities (built-in offline CVE pattern set; exit non-zero on high severity) +python3 scripts/dep_scanner.py /path/to/project --format json --fail-on-high -o scan.json -# Check license compliance -python scripts/license_checker.py /path/to/project --policy strict +# 2. Check license compliance and conflicts +python3 scripts/license_checker.py /path/to/project --policy strict --format json -o licenses.json -# Plan dependency upgrades -python scripts/upgrade_planner.py deps.json --risk-threshold medium +# 3. Plan upgrades from the scanner's inventory +python3 scripts/upgrade_planner.py scan.json --risk-threshold medium --timeline 90 --format json -o plan.json ``` -For detailed usage instructions, see [README.md](README.md). +Consume the outputs: `scan.json` findings drive which packages to pin/patch now; `licenses.json` conflicts go to the user as a legal-risk list; `plan.json` orders upgrades by risk with rollback notes. `--quick-scan` skips transitive deps; `--security-only` limits the plan to security fixes. ---- +**Verification loop:** after applying upgrades, re-run step 1 and assert 0 high-severity findings before closing the audit. -*This skill provides comprehensive dependency management capabilities essential for maintaining secure, compliant, and efficient software projects. Regular use helps teams stay ahead of security threats, maintain legal compliance, and optimize their dependency ecosystems.* \ No newline at end of file +## Supported Ecosystems + +| Language | Manifests parsed | +|---|---| +| JavaScript/Node | package.json, package-lock.json, yarn.lock | +| Python | requirements.txt, pyproject.toml, Pipfile.lock, poetry.lock | +| Go | go.mod, go.sum | +| Rust | Cargo.toml, Cargo.lock | +| Ruby | Gemfile, Gemfile.lock | +| Java | pom.xml, gradle.lockfile | +| PHP | composer.json, composer.lock | +| C#/.NET | packages.config, project.assets.json | + +## License Classification + +- **Permissive**: MIT, Apache 2.0, BSD (2/3-clause), ISC +- **Copyleft (strong)**: GPL v2/v3, AGPL v3 — flags contamination risk in permissive projects +- **Copyleft (weak)**: LGPL v2.1/v3, MPL 2.0 +- **Proprietary / Dual / Unknown** — unknown licenses are surfaced for manual review + +The checker analyzes license inheritance through dependency chains and emits conflict pairs with remediation suggestions. + +## Upgrade Risk Matrix + +| Risk | Update type | Handling | +|---|---|---| +| Low | Patch, security fixes | Apply immediately | +| Medium | Minor with new features | Batch into scheduled update | +| High | Major version, API changes | Dedicated migration task + tests | +| Critical | Known breaking changes | Planned migration with rollback procedure | + +Prioritization: security patches > bug fixes > feature updates > major rewrites; deprecated features get immediate attention. + +## Scripts (accurate capability claims) + +- **`scripts/dep_scanner.py`** — multi-format parser; built-in offline vulnerability pattern set (~16 CVE patterns — a smoke layer, not a replacement for live advisories); transitive resolution from lockfiles; JSON + text output. +- **`scripts/license_checker.py`** — license detection from package metadata; compatibility matrix across 20+ license types; `--policy permissive|strict`; conflict detection with remediation. +- **`scripts/upgrade_planner.py`** — semver-based breaking-change prediction; risk-ordered migration plan with testing checklist and timeline estimation. + +Sample fixtures: `test-project/` and `test-inventory.json` in this folder; expected shapes in `expected_outputs/`. + +## CI Integration + +```bash +# Security gate in CI +python3 scripts/dep_scanner.py . --format json --fail-on-high +python3 scripts/license_checker.py . --policy strict --format json +``` + +## Best Practices + +1. **Prioritize security**: address high/critical findings immediately; license compliance before functionality. +2. **Gradual updates**: incremental upgrades with thorough testing; feature flags for risky bumps. +3. **Cadence**: security scans per commit; license audits monthly; full audit quarterly. +4. **False positives**: whitelist with documentation; contact maintainers for license ambiguity. + +See [README.md](README.md) for detailed usage and `references/` for the vulnerability/license knowledge bases. diff --git a/engineering/skills/engineering-advanced-skills/SKILL.md b/engineering/skills/engineering-advanced-skills/SKILL.md index b75d593c..9b405068 100644 --- a/engineering/skills/engineering-advanced-skills/SKILL.md +++ b/engineering/skills/engineering-advanced-skills/SKILL.md @@ -1,6 +1,6 @@ --- name: "engineering-advanced-skills" -description: "25 advanced engineering agent skills and plugins for Claude Code, Codex, Gemini CLI, Cursor, OpenClaw. Agent design, RAG, MCP servers, CI/CD, database design, observability, security auditing, release management, platform ops." +description: "Index of 37 advanced engineering agent skills for Claude Code, Codex, Gemini CLI, Cursor, OpenClaw. Use when browsing or choosing among the POWERFUL-tier engineering skills: agent design, RAG, MCP servers, CI/CD, database design, observability, security auditing, changelog/release automation, reliability (SLO/chaos/flags/operators), platform ops." version: 2.9.0 author: Alireza Rezvani license: MIT @@ -20,13 +20,13 @@ agents: # Engineering Advanced Skills (POWERFUL Tier) -25 advanced engineering skills for complex architecture, automation, and platform operations. +37 advanced engineering skills for complex architecture, automation, reliability, and platform operations. ## Quick Start ### Claude Code ``` -/read engineering/agent-designer/SKILL.md +/read engineering/skills/agent-designer/SKILL.md ``` ### Codex CLI @@ -38,31 +38,45 @@ npx agent-skills-cli add alirezarezvani/claude-skills/engineering | Skill | Folder | Focus | |-------|--------|-------| -| Agent Designer | `agent-designer/` | Multi-agent architecture patterns | -| Agent Workflow Designer | `agent-workflow-designer/` | Workflow orchestration | +| Agent Designer | `agent-designer/` | Multi-agent architecture: plan, schema-generate, evaluate | +| Agent Workflow Designer | `agent-workflow-designer/` | Workflow orchestration scaffolds | | API Design Reviewer | `api-design-reviewer/` | REST/GraphQL linting, breaking changes | | API Test Suite Builder | `api-test-suite-builder/` | API test generation | -| Changelog Generator | `changelog-generator/` | Automated changelogs | +| Browser Automation | `browser-automation/` | Playwright/Selenium automation patterns | +| Changelog Generator | `changelog-generator/` | Changelogs, semantic version bumps, hotfix/rollback discipline | +| Chaos Engineering | `chaos-engineering/` | Experiment design, blast-radius, postmortems | | CI/CD Pipeline Builder | `ci-cd-pipeline-builder/` | Pipeline generation | | Codebase Onboarding | `codebase-onboarding/` | New dev onboarding guides | -| Database Designer | `database-designer/` | Schema design, migrations | +| Database Designer | `database-designer/` | Schema analysis, index optimization, migrations | | Database Schema Designer | `database-schema-designer/` | ERD, normalization | | Dependency Auditor | `dependency-auditor/` | Dependency security scanning | | Env Secrets Manager | `env-secrets-manager/` | Secrets rotation, vault | +| Feature Flags Architect | `feature-flags-architect/` | Flag debt, rollout plans, kill switches | +| Focused Fix | `focused-fix/` | Systematic feature/module repair | +| Full Page Screenshot | `full-page-screenshot/` | Full-page capture tooling | | Git Worktree Manager | `git-worktree-manager/` | Parallel branch workflows | | Interview System Designer | `interview-system-designer/` | Hiring pipeline design | +| Kubernetes Operator | `kubernetes-operator/` | CRD validation, reconcile linting | | MCP Server Builder | `mcp-server-builder/` | MCP tool creation | | Migration Architect | `migration-architect/` | System migration planning | | Monorepo Navigator | `monorepo-navigator/` | Monorepo tooling | -| Observability Designer | `observability-designer/` | SLOs, alerts, dashboards | +| Observability Designer | `observability-designer/` | Dashboards, alert noise (SLOs → slo-architect) | | Performance Profiler | `performance-profiler/` | CPU, memory, load profiling | | PR Review Expert | `pr-review-expert/` | Pull request analysis | -| RAG Architect | `rag-architect/` | RAG system design | -| Release Manager | `release-manager/` | Release orchestration | +| RAG Architect | `rag-architect/` | RAG design, chunking, retrieval evaluation | | Runbook Generator | `runbook-generator/` | Operational runbooks | +| Secrets Vault Manager | `secrets-vault-manager/` | Vault patterns, HCL | +| Self-Eval | `self-eval/` | Honest work-quality scoring | +| Ship Gate | `ship-gate/` | Pre-production audit (89 checks) | | Skill Security Auditor | `skill-security-auditor/` | Skill vulnerability scanning | | Skill Tester | `skill-tester/` | Skill quality evaluation | -| Tech Debt Tracker | `tech-debt-tracker/` | Technical debt management | +| SLO Architect | `slo-architect/` | SLO/SLI design, error budgets, burn-rate alerts | +| Spec-Driven Workflow | `spec-driven-workflow/` | Spec-first development gates | +| SQL Database Assistant | `sql-database-assistant/` | Query optimization, 4 dialects | +| TC Tracker | `tc-tracker/` | Task context lifecycle + handoffs | +| Tech Debt Tracker | `tech-debt-tracker/` | Debt scan → prioritize → dashboard | + +Note: release management merged into `changelog-generator/` (version bumper + hotfix/rollback procedures live there now). ## Rules diff --git a/engineering/skills/migration-architect/SKILL.md b/engineering/skills/migration-architect/SKILL.md index c4adeafc..1bb65ecf 100644 --- a/engineering/skills/migration-architect/SKILL.md +++ b/engineering/skills/migration-architect/SKILL.md @@ -33,6 +33,25 @@ The Migration Architect skill provides comprehensive tools and methodologies for - **Service Rollback:** Plan service version rollbacks with traffic management - **Validation Checkpoints:** Define success criteria and rollback triggers +## Quick Start — plan → check compatibility → generate rollback + +All paths relative to this skill folder; sample inputs in `assets/`, expected shapes in `expected_outputs/`. + +```bash +# 1. Generate the migration plan from a spec (copy assets/sample_database_migration.json) +python3 scripts/migration_planner.py --input migration_spec.json --format json -o migration_plan.json + +# 2. Check schema/API compatibility — exits non-zero unless fully compatible (CI gate) +python3 scripts/compatibility_checker.py --before assets/database_schema_before.json --after assets/database_schema_after.json --type database --format json -o compatibility.json + +# 3. Generate the rollback runbook from the plan +python3 scripts/rollback_generator.py --input migration_plan.json --format both -o rollback_runbook +``` + +Outputs chain: `migration_plan.json` (`phases`, `risks`, `estimated_duration_hours`) feeds step 3; `compatibility.json` reports `overall_compatibility` plus `breaking_changes_count` / `potentially_breaking_count`. + +**Gate:** the migration is not approved until (a) `compatibility_checker` exits 0 (`overall_compatibility: compatible`) or every breaking/potentially-breaking item is explicitly accepted by the owner in writing, and (b) a rollback runbook exists for every phase in the plan. Re-run both checks after any schema revision. + ## Migration Patterns ### Database Migrations @@ -338,74 +357,6 @@ class MigrationCircuitBreaker: - [ ] Archive migration artifacts - [ ] Update disaster recovery procedures -## Communication Templates - -### Executive Summary Template -``` -Migration Status: [IN_PROGRESS | COMPLETED | ROLLED_BACK] -Start Time: [YYYY-MM-DD HH:MM UTC] -Current Phase: [X of Y] -Overall Progress: [X%] - -Key Metrics: -- System Availability: [X.XX%] -- Data Migration Progress: [X.XX%] -- Performance Impact: [+/-X%] -- Issues Encountered: [X] - -Next Steps: -1. [Action item 1] -2. [Action item 2] - -Risk Assessment: [LOW | MEDIUM | HIGH] -Rollback Status: [AVAILABLE | NOT_AVAILABLE] -``` - -### Technical Team Update Template -``` -Phase: [Phase Name] - [Status] -Duration: [Started] - [Expected End] - -Completed Tasks: -✓ [Task 1] -✓ [Task 2] - -In Progress: -🔄 [Task 3] - [X% complete] - -Upcoming: -⏳ [Task 4] - [Expected start time] - -Issues: -⚠️ [Issue description] - [Severity] - [ETA resolution] - -Metrics: -- Migration Rate: [X records/minute] -- Error Rate: [X.XX%] -- System Load: [CPU/Memory/Disk] -``` - -## Success Metrics - -### Technical Metrics -- **Migration Completion Rate:** Percentage of data/services successfully migrated -- **Downtime Duration:** Total system unavailability during migration -- **Data Consistency Score:** Percentage of data validation checks passing -- **Performance Delta:** Performance change compared to baseline -- **Error Rate:** Percentage of failed operations during migration - -### Business Metrics -- **Customer Impact Score:** Measure of customer experience degradation -- **Revenue Protection:** Percentage of revenue maintained during migration -- **Time to Value:** Duration from migration start to business value realization -- **Stakeholder Satisfaction:** Post-migration stakeholder feedback scores - -### Operational Metrics -- **Plan Adherence:** Percentage of migration executed according to plan -- **Issue Resolution Time:** Average time to resolve migration issues -- **Team Efficiency:** Resource utilization and productivity metrics -- **Knowledge Transfer Score:** Team readiness for post-migration operations - ## Tools and Technologies ### Migration Planning Tools diff --git a/engineering/skills/observability-designer/SKILL.md b/engineering/skills/observability-designer/SKILL.md index fe30b44d..8052ca2e 100644 --- a/engineering/skills/observability-designer/SKILL.md +++ b/engineering/skills/observability-designer/SKILL.md @@ -11,7 +11,26 @@ description: "Design production-ready observability strategies combining metrics ## Overview -Observability Designer enables you to create production-ready observability strategies that provide deep insights into system behavior, performance, and reliability. This skill combines the three pillars of observability (metrics, logs, traces) with proven frameworks like SLI/SLO design, golden signals monitoring, and alert optimization to create comprehensive observability solutions. +Observability Designer creates production-ready dashboards, alert configurations, and monitoring strategies across the three pillars (metrics, logs, traces). + +**When NOT to use → slo-architect.** For SLO/SLI design with error-budget math, multi-window burn-rate alerting thresholds, and SLO review gates, route to `slo-architect` — it is the authoritative skill for that half. This skill's `slo_designer.py` produces a quick scaffold only. This skill's lane: dashboards (`dashboard_generator.py`) and alert-noise reduction (`alert_optimizer.py`). + +## Quick Start + +```bash +# Dashboard spec (Grafana JSON + docs) for a service +python3 scripts/dashboard_generator.py --service-type api --name payments --criticality critical --role sre --format grafana -o dashboard.json --doc-output dashboard.md + +# Analyze an existing alert config for noise, duplicates, and coverage gaps +python3 scripts/alert_optimizer.py --input alerts.json --analyze-only --report alert_report.json +# ...then emit the optimized config once the report is reviewed: +python3 scripts/alert_optimizer.py --input alerts.json --output alerts_optimized.json + +# Quick SLO scaffold (hand off to slo-architect for the real error-budget work) +python3 scripts/slo_designer.py --service-type api --criticality high --user-facing true --service-name payments -o slo_scaffold.json +``` + +**Verification loop:** after deploying optimized alerts, track the report's noise metrics for one on-call rotation — if the actionable-alert ratio didn't improve, re-run `--analyze-only` against the live config and iterate. Import the generated dashboard into Grafana and confirm every golden-signal panel renders with live data before closing the task. ## Core Competencies @@ -251,19 +270,3 @@ Creates comprehensive dashboard specifications: - **Alert Tuning:** Ongoing alert threshold and routing optimization - **Dashboard Evolution:** User feedback-driven dashboard improvements - **Tool Evaluation:** Regular assessment of observability tool effectiveness - -## Success Metrics - -### Operational Metrics -- **Mean Time to Detection (MTTD):** How quickly issues are identified -- **Mean Time to Resolution (MTTR):** Time from detection to resolution -- **Alert Precision:** Percentage of actionable alerts -- **SLO Achievement:** Percentage of SLO targets met consistently - -### Business Metrics -- **System Reliability:** Overall uptime and user experience quality -- **Engineering Velocity:** Development team productivity and deployment frequency -- **Cost Efficiency:** Observability cost as percentage of infrastructure spend -- **Customer Satisfaction:** User-reported reliability and performance satisfaction - -This comprehensive observability design skill enables organizations to build robust, scalable monitoring and alerting systems that provide actionable insights while maintaining cost efficiency and operational excellence. \ No newline at end of file diff --git a/engineering/skills/pr-review-expert/SKILL.md b/engineering/skills/pr-review-expert/SKILL.md index deb39fd0..91f2de0e 100644 --- a/engineering/skills/pr-review-expert/SKILL.md +++ b/engineering/skills/pr-review-expert/SKILL.md @@ -247,20 +247,33 @@ grep -n "new Array([0-9]\{4,\}\|Buffer\.alloc" /tmp/pr-$PR.diff | grep "^+" gh pr view $PR --json body | jq -r '.body' | \ grep -oE "(PROJ-[0-9]+|[A-Z]+-[0-9]+|https://linear\.app/[^)\"]+)" | sort -u -# Verify Jira ticket exists (requires JIRA_API_TOKEN) +# Verify Jira ticket exists (requires JIRA_API_TOKEN to be SET in the environment). +# Credentials are fed to curl via a config read from stdin (-K -) so the token +# never appears in argv — `ps aux` / /proc/*/cmdline can't see it, and nothing +# secret lands in shell history. Never paste the raw token on the command line. TICKET="PROJ-123" -curl -s -u "user@company.com:$JIRA_API_TOKEN" \ - "https://your-org.atlassian.net/rest/api/3/issue/$TICKET" | \ +: "${JIRA_API_TOKEN:?JIRA_API_TOKEN must be set}" +curl -s -K - "https://your-org.atlassian.net/rest/api/3/issue/$TICKET" <<EOF | \ jq '{key, summary: .fields.summary, status: .fields.status.name}' +user = "user@company.com:$JIRA_API_TOKEN" +EOF -# Linear ticket +# Linear ticket — same pattern: the Authorization header goes through the +# stdin config, not a -H flag, to keep the key out of the process list. LINEAR_ID="abc-123" -curl -s -H "Authorization: $LINEAR_API_KEY" \ - -H "Content-Type: application/json" \ +: "${LINEAR_API_KEY:?LINEAR_API_KEY must be set}" +curl -s -K - -H "Content-Type: application/json" \ --data "{\"query\": \"{ issue(id: \\\"$LINEAR_ID\\\") { title state { name } } }\"}" \ - https://api.linear.app/graphql | jq . + https://api.linear.app/graphql <<EOF | jq . +header = "Authorization: $LINEAR_API_KEY" +EOF ``` +> **Security note:** for repeated Jira use, prefer a `~/.netrc` entry +> (`machine your-org.atlassian.net login user@company.com password <token>`, +> `chmod 600 ~/.netrc`) and call `curl -s --netrc …` — no secret material in +> the command at all. + --- ## Complete Review Checklist (30+ Items) diff --git a/engineering/skills/rag-architect/SKILL.md b/engineering/skills/rag-architect/SKILL.md index b097fd77..20fdd61f 100644 --- a/engineering/skills/rag-architect/SKILL.md +++ b/engineering/skills/rag-architect/SKILL.md @@ -1,318 +1,71 @@ --- name: "rag-architect" -description: "Use when the user asks to design RAG pipelines, optimize retrieval strategies, choose embedding models, implement vector search, or build knowledge retrieval systems." +description: "Use when the user asks to design a RAG pipeline, choose a chunking strategy or embedding model, pick a vector database, or evaluate retrieval quality (precision@k, recall@k, NDCG). Examples: 'design a RAG system for our docs', 'what chunk size should I use for this corpus', 'evaluate my retriever against ground truth'. NOT for general LLM cost tuning (use llm-cost-optimizer) or agent loops over retrieval (use agenthub)." --- -# RAG Architect - POWERFUL +# RAG Architect -## Overview +Design, tune, and evaluate production RAG pipelines with three deterministic tools. Run the tools against the actual corpus and requirements — do not pick chunk sizes or databases by intuition. -The RAG (Retrieval-Augmented Generation) Architect skill provides comprehensive tools and knowledge for designing, implementing, and optimizing production-grade RAG pipelines. This skill covers the entire RAG ecosystem from document chunking strategies to evaluation frameworks, enabling you to build scalable, efficient, and accurate retrieval systems. +## Hard rules -## Core Competencies +1. **Never present model names or vendor prices as current facts.** Embedding models and vector-DB pricing rot in months. Recommend a *tier* (see table below), name a current-generation candidate, and tell the user to verify against the provider's live pricing page. +2. **Every design ends with an evaluation run.** A RAG design without `retrieval_evaluator.py` numbers is a hypothesis, not a deliverable. +3. **Chunking is corpus-driven.** Run `chunking_optimizer.py` on the real documents before choosing a strategy. -### 1. Document Processing & Chunking Strategies +## Embedding model tiers (pattern, not price list) -#### Fixed-Size Chunking -- **Character-based chunking**: Simple splitting by character count (e.g., 512, 1024, 2048 chars) -- **Token-based chunking**: Splitting by token count to respect model limits -- **Overlap strategies**: 10-20% overlap to maintain context continuity -- **Pros**: Predictable chunk sizes, simple implementation, consistent processing time -- **Cons**: May break semantic units, context boundaries ignored -- **Best for**: Uniform documents, when consistent chunk sizes are critical +| Tier | Current-generation examples (verify before use) | When | +|---|---|---| +| Fast / self-hosted | `all-MiniLM-L6-v2`, `bge-small` | Cost-sensitive, small scale, real-time | +| Balanced open | `all-mpnet-base-v2`, `bge-large`, `e5-large` | Quality without API dependency | +| Quality API | `text-embedding-3-large`, `voyage-3-large` | Accuracy-priority general retrieval | +| Code | `voyage-code-3`, CodeBERT-family | Code search corpora | -#### Sentence-Based Chunking -- **Sentence boundary detection**: Using NLTK, spaCy, or regex patterns -- **Sentence grouping**: Combining sentences until size threshold is reached -- **Paragraph preservation**: Avoiding mid-paragraph splits when possible -- **Pros**: Preserves natural language boundaries, better readability -- **Cons**: Variable chunk sizes, potential for very short/long chunks -- **Best for**: Narrative text, articles, books +**Pricing discipline:** build the cost model with a placeholder table — columns `model | $/1M tokens (verify) | dims | as-of date` — and have the user fill in live numbers. Same for vector DBs (Pinecone/Weaviate/Qdrant/Chroma/pgvector): the selection criteria (managed vs self-hosted, scale, filtering, existing Postgres) are durable; the dollar figures are not. -#### Paragraph-Based Chunking -- **Paragraph detection**: Double newlines, HTML tags, markdown formatting -- **Hierarchical splitting**: Respecting document structure (sections, subsections) -- **Size balancing**: Merging small paragraphs, splitting large ones -- **Pros**: Preserves logical document structure, maintains topic coherence -- **Cons**: Highly variable sizes, may create very large chunks -- **Best for**: Structured documents, technical documentation +## Workflow -#### Semantic Chunking -- **Topic modeling**: Using TF-IDF, embeddings similarity for topic detection -- **Heading-aware splitting**: Respecting document hierarchy (H1, H2, H3) -- **Content-based boundaries**: Detecting topic shifts using semantic similarity -- **Pros**: Maintains semantic coherence, respects document structure -- **Cons**: Complex implementation, computationally expensive -- **Best for**: Long-form content, technical manuals, research papers +All paths relative to this skill folder. Outputs chain: corpus analysis → design → evaluation. -#### Recursive Chunking -- **Hierarchical approach**: Try larger chunks first, recursively split if needed -- **Multi-level splitting**: Different strategies at different levels -- **Size optimization**: Minimize number of chunks while respecting size limits -- **Pros**: Optimal chunk utilization, preserves context when possible -- **Cons**: Complex logic, potential performance overhead -- **Best for**: Mixed content types, when chunk count optimization is important +### 1. Analyze the corpus and pick chunking -#### Document-Aware Chunking -- **File type detection**: PDF pages, Word sections, HTML elements -- **Metadata preservation**: Headers, footers, page numbers, sections -- **Table and image handling**: Special processing for non-text elements -- **Pros**: Preserves document structure and metadata -- **Cons**: Format-specific implementation required -- **Best for**: Multi-format document collections, when metadata is important +```bash +python3 chunking_optimizer.py /path/to/docs --extensions .md .txt -o chunking.json +``` -### 2. Embedding Model Selection +Emits `chunking.json` with `corpus_info`, per-strategy `strategy_results`, a `recommendation`, and `sample_chunks`. Use `recommendation.strategy` and its config; show the user 2-3 `sample_chunks` so they can sanity-check boundaries. -#### Dimension Considerations -- **128-256 dimensions**: Fast retrieval, lower memory usage, suitable for simple domains -- **512-768 dimensions**: Balanced performance, good for most applications -- **1024-1536 dimensions**: High quality, better for complex domains, higher cost -- **2048+ dimensions**: Maximum quality, specialized use cases, significant resources +### 2. Design the pipeline from requirements -#### Speed vs Quality Tradeoffs -- **Fast models**: sentence-transformers/all-MiniLM-L6-v2 (384 dim, ~14k tokens/sec) -- **Balanced models**: sentence-transformers/all-mpnet-base-v2 (768 dim, ~2.8k tokens/sec) -- **Quality models**: text-embedding-ada-002 (1536 dim, OpenAI API) -- **Specialized models**: Domain-specific fine-tuned models +Write a requirements JSON with these keys (all required): `document_types[]`, `document_count`, `avg_document_size` (chars), `queries_per_day`, `query_patterns[]`, `latency_requirement`, `budget_monthly`, `accuracy_priority` (0-1), `cost_priority` (0-1), `maintenance_complexity`. -#### Model Categories -- **General purpose**: all-MiniLM, all-mpnet, Universal Sentence Encoder -- **Code embeddings**: CodeBERT, GraphCodeBERT, CodeT5 -- **Scientific text**: SciBERT, BioBERT, ClinicalBERT -- **Multilingual**: LaBSE, multilingual-e5, paraphrase-multilingual +```bash +python3 rag_pipeline_designer.py requirements.json -o design.json +``` -### 3. Vector Database Selection +Emits `design.json` with `chunking`, `embedding`, `vector_db`, `retrieval`, `reranking`, `evaluation`, `total_cost`, `architecture_diagram` (mermaid), and `config_templates`. Present the diagram; label every `cost_monthly` figure as an estimate to verify (rule 1). -#### Pinecone -- **Managed service**: Fully hosted, auto-scaling -- **Features**: Metadata filtering, hybrid search, real-time updates -- **Pricing**: $70/month for 1M vectors (1536 dim), pay-per-use scaling -- **Best for**: Production applications, when managed service is preferred -- **Cons**: Vendor lock-in, costs can scale quickly +### 3. Evaluate retrieval quality -#### Weaviate -- **Open source**: Self-hosted or cloud options available -- **Features**: GraphQL API, multi-modal search, automatic vectorization -- **Scaling**: Horizontal scaling, HNSW indexing -- **Best for**: Complex data types, when GraphQL API is preferred -- **Cons**: Learning curve, requires infrastructure management +Prepare `queries.json` (list of `{id, text}` or `{"queries": [...]}`) and `ground_truth.json` (`{query_id: [relevant_doc_ids]}`), then: -#### Qdrant -- **Rust-based**: High performance, low memory footprint -- **Features**: Payload filtering, clustering, distributed deployment -- **API**: REST and gRPC interfaces -- **Best for**: High-performance requirements, resource-constrained environments -- **Cons**: Smaller community, fewer integrations +```bash +python3 retrieval_evaluator.py queries.json /path/to/docs ground_truth.json --k-values 3 5 10 -o eval.json +``` -#### Chroma -- **Embedded database**: SQLite-based, easy local development -- **Features**: Collections, metadata filtering, persistence -- **Scaling**: Limited, suitable for prototyping and small deployments -- **Best for**: Development, testing, small-scale applications -- **Cons**: Not suitable for production scale +Reports precision@k, recall@k, MRR, NDCG@k, plus `poor_precision_examples` / `poor_recall_examples` for failure analysis. -#### pgvector (PostgreSQL) -- **SQL integration**: Leverage existing PostgreSQL infrastructure -- **Features**: ACID compliance, joins with relational data, mature ecosystem -- **Performance**: ivfflat and HNSW indexing, parallel query processing -- **Best for**: When you already use PostgreSQL, need ACID compliance -- **Cons**: Requires PostgreSQL expertise, less specialized than purpose-built DBs +### 4. Verification loop -### 4. Retrieval Strategies +The design is done only when: -#### Dense Retrieval -- **Semantic similarity**: Using embedding cosine similarity -- **Advantages**: Captures semantic meaning, handles paraphrasing well -- **Limitations**: May miss exact keyword matches, requires good embeddings -- **Implementation**: Vector similarity search with k-NN or ANN algorithms +1. `eval.json` meets targets — typical floors: precision@5 ≥ 0.8, recall@10 ≥ 0.85 (set per use case with the user). +2. If below target: inspect the poor-example lists, then change **one** variable (chunking strategy → re-run step 1; embedding tier; add reranking; hybrid retrieval) and re-run step 3. Repeat. +3. Every recommended model/price in the deliverable carries a "verify current pricing/model availability" note with an as-of date. -#### Sparse Retrieval -- **Keyword-based**: TF-IDF, BM25, Elasticsearch -- **Advantages**: Exact keyword matching, interpretable results -- **Limitations**: Misses semantic similarity, vulnerable to vocabulary mismatch -- **Implementation**: Inverted indexes, term frequency analysis +## References -#### Hybrid Retrieval -- **Combination approach**: Dense + sparse retrieval with score fusion -- **Fusion strategies**: Reciprocal Rank Fusion (RRF), weighted combination -- **Benefits**: Combines semantic understanding with exact matching -- **Complexity**: Requires tuning fusion weights, more complex infrastructure - -#### Reranking -- **Two-stage approach**: Initial retrieval followed by reranking -- **Reranking models**: Cross-encoders, specialized reranking transformers -- **Benefits**: Higher precision, can use more sophisticated models for final ranking -- **Tradeoff**: Additional latency, computational cost - -### 5. Query Transformation Techniques - -#### HyDE (Hypothetical Document Embeddings) -- **Approach**: Generate hypothetical answer, embed answer instead of query -- **Benefits**: Improves retrieval by matching document style rather than query style -- **Implementation**: Use LLM to generate hypothetical document, embed that -- **Use cases**: When queries and documents have different styles - -#### Multi-Query Generation -- **Approach**: Generate multiple query variations, retrieve for each, merge results -- **Benefits**: Increases recall, handles query ambiguity -- **Implementation**: LLM generates 3-5 query variations, deduplicate results -- **Considerations**: Higher cost and latency due to multiple retrievals - -#### Step-Back Prompting -- **Approach**: Generate broader, more general version of specific query -- **Benefits**: Retrieves more general context that helps answer specific questions -- **Implementation**: Transform "What is the capital of France?" to "What are European capitals?" -- **Use cases**: When specific questions need general context - -### 6. Context Window Optimization - -#### Dynamic Context Assembly -- **Relevance-based ordering**: Most relevant chunks first -- **Diversity optimization**: Avoid redundant information -- **Token budget management**: Fit within model context limits -- **Hierarchical inclusion**: Include summaries before detailed chunks - -#### Context Compression -- **Summarization**: Compress less relevant chunks while preserving key information -- **Key information extraction**: Extract only relevant facts/entities -- **Template-based compression**: Use structured formats to reduce token usage -- **Selective inclusion**: Include only chunks above relevance threshold - -### 7. Evaluation Frameworks - -#### Faithfulness Metrics -- **Definition**: How well generated answers are grounded in retrieved context -- **Measurement**: Fact verification against source documents -- **Implementation**: NLI models to check entailment between answer and context -- **Threshold**: >90% for production systems - -#### Relevance Metrics -- **Context relevance**: How relevant retrieved chunks are to the query -- **Answer relevance**: How well the answer addresses the original question -- **Measurement**: Embedding similarity, human evaluation, LLM-as-judge -- **Targets**: Context relevance >0.8, Answer relevance >0.85 - -#### Context Precision & Recall -- **Precision@K**: Percentage of top-K results that are relevant -- **Recall@K**: Percentage of relevant documents found in top-K results -- **Mean Reciprocal Rank (MRR)**: Average of reciprocal ranks of first relevant result -- **NDCG@K**: Normalized Discounted Cumulative Gain at K - -#### End-to-End Metrics -- **RAGAS**: Comprehensive RAG evaluation framework -- **Correctness**: Factual accuracy of generated answers -- **Completeness**: Coverage of all relevant aspects -- **Consistency**: Consistency across multiple runs with same query - -### 8. Production Patterns - -#### Caching Strategies -- **Query-level caching**: Cache results for identical queries -- **Semantic caching**: Cache for semantically similar queries -- **Chunk-level caching**: Cache embedding computations -- **Multi-level caching**: Redis for hot queries, disk for warm queries - -#### Streaming Retrieval -- **Progressive loading**: Stream results as they become available -- **Incremental generation**: Generate answers while still retrieving -- **Real-time updates**: Handle document updates without full reprocessing -- **Connection management**: Handle client disconnections gracefully - -#### Fallback Mechanisms -- **Graceful degradation**: Fallback to simpler retrieval if primary fails -- **Cache fallbacks**: Serve stale results when retrieval is unavailable -- **Alternative sources**: Multiple vector databases for redundancy -- **Error handling**: Comprehensive error recovery and user communication - -### 9. Cost Optimization - -#### Embedding Cost Management -- **Batch processing**: Batch documents for embedding to reduce API costs -- **Caching strategies**: Cache embeddings to avoid recomputation -- **Model selection**: Balance cost vs quality for embedding models -- **Update optimization**: Only re-embed changed documents - -#### Vector Database Optimization -- **Index optimization**: Choose appropriate index types for use case -- **Compression**: Use quantization to reduce storage costs -- **Tiered storage**: Hot/warm/cold data strategies -- **Resource scaling**: Auto-scaling based on query patterns - -#### Query Optimization -- **Query routing**: Route simple queries to cheaper methods -- **Result caching**: Avoid repeated expensive retrievals -- **Batch querying**: Process multiple queries together when possible -- **Smart filtering**: Use metadata filters to reduce search space - -### 10. Guardrails & Safety - -#### Content Filtering -- **Toxicity detection**: Filter harmful or inappropriate content -- **PII detection**: Identify and handle personally identifiable information -- **Content validation**: Ensure retrieved content meets quality standards -- **Source verification**: Validate document authenticity and reliability - -#### Query Safety -- **Injection prevention**: Prevent malicious query injection attacks -- **Rate limiting**: Prevent abuse and ensure fair usage -- **Query validation**: Sanitize and validate user inputs -- **Access controls**: Ensure users can only access authorized content - -#### Response Safety -- **Hallucination detection**: Identify when model generates unsupported claims -- **Confidence scoring**: Provide confidence levels for generated responses -- **Source attribution**: Always provide sources for factual claims -- **Uncertainty handling**: Gracefully handle cases where answer is uncertain - -## Implementation Best Practices - -### Development Workflow -1. **Requirements gathering**: Understand use case, scale, and quality requirements -2. **Data analysis**: Analyze document corpus characteristics -3. **Prototype development**: Build minimal viable RAG pipeline -4. **Chunking optimization**: Test different chunking strategies -5. **Retrieval tuning**: Optimize retrieval parameters and thresholds -6. **Evaluation setup**: Implement comprehensive evaluation metrics -7. **Production deployment**: Scale-ready implementation with monitoring - -### Monitoring & Observability -- **Query analytics**: Track query patterns and performance -- **Retrieval metrics**: Monitor precision, recall, and latency -- **Generation quality**: Track faithfulness and relevance scores -- **System health**: Monitor database performance and availability -- **Cost tracking**: Monitor embedding and vector database costs - -### Maintenance & Updates -- **Document refresh**: Handle new documents and updates -- **Index maintenance**: Regular vector database optimization -- **Model updates**: Evaluate and migrate to improved models -- **Performance tuning**: Continuous optimization based on usage patterns -- **Security updates**: Regular security assessments and updates - -## Common Pitfalls & Solutions - -### Poor Chunking Strategy -- **Problem**: Chunks break mid-sentence or lose context -- **Solution**: Use boundary-aware chunking with overlap - -### Low Retrieval Precision -- **Problem**: Retrieved chunks are not relevant to query -- **Solution**: Improve embedding model, add reranking, tune similarity threshold - -### High Latency -- **Problem**: Slow retrieval and generation -- **Solution**: Optimize vector indexing, implement caching, use faster embedding models - -### Inconsistent Quality -- **Problem**: Variable answer quality across different queries -- **Solution**: Implement comprehensive evaluation, add quality scoring, improve fallbacks - -### Scalability Issues -- **Problem**: System doesn't scale with increased load -- **Solution**: Implement proper caching, database sharding, and auto-scaling - -## Conclusion - -Building effective RAG systems requires careful consideration of each component in the pipeline. The key to success is understanding the tradeoffs between different approaches and choosing the right combination of techniques for your specific use case. Start with simple approaches and gradually add sophistication based on evaluation results and production requirements. - -This skill provides the foundation for making informed decisions throughout the RAG development lifecycle, from initial design to production deployment and ongoing maintenance. \ No newline at end of file +- `references/chunking_strategies_comparison.md` — strategy trade-offs the optimizer implements +- `references/embedding_model_benchmark.md` — benchmark *methodology* (dated snapshot; staleness warning at top) +- `references/rag_evaluation_framework.md` — metric definitions (faithfulness, relevance, precision/recall/NDCG) diff --git a/engineering/skills/rag-architect/rag_pipeline_designer.py b/engineering/skills/rag-architect/rag_pipeline_designer.py index 3b4f096f..9fc73469 100644 --- a/engineering/skills/rag-architect/rag_pipeline_designer.py +++ b/engineering/skills/rag-architect/rag_pipeline_designer.py @@ -200,18 +200,18 @@ class RAGPipelineDesigner: if "code" in doc_types: if high_accuracy and not cost_sensitive: - model = "openai-code-search-ada-002" - cost_per_1k_tokens = 0.0001 - dimensions = 1536 + model = "voyage-code-3" + cost_per_1k_tokens = 0.00018 # verify current pricing before budgeting + dimensions = 1024 else: model = "sentence-transformers/code-bert-base" cost_per_1k_tokens = 0.0 # Self-hosted dimensions = 768 elif "scientific" in doc_types: if high_accuracy: - model = "openai-text-embedding-ada-002" - cost_per_1k_tokens = 0.0001 - dimensions = 1536 + model = "openai-text-embedding-3-large" + cost_per_1k_tokens = 0.00013 # verify current pricing before budgeting + dimensions = 3072 else: model = "sentence-transformers/scibert-nli" cost_per_1k_tokens = 0.0 @@ -222,9 +222,9 @@ class RAGPipelineDesigner: cost_per_1k_tokens = 0.0 dimensions = 384 elif high_accuracy: - model = "openai-text-embedding-ada-002" - cost_per_1k_tokens = 0.0001 - dimensions = 1536 + model = "openai-text-embedding-3-large" + cost_per_1k_tokens = 0.00013 # verify current pricing before budgeting + dimensions = 3072 else: model = "sentence-transformers/all-mpnet-base-v2" cost_per_1k_tokens = 0.0 @@ -443,9 +443,15 @@ graph TB def _load_embedding_models(self) -> Dict[str, Dict[str, Any]]: """Load embedding model specifications.""" return { - "openai-text-embedding-ada-002": { - "dimensions": 1536, - "cost_per_1k_tokens": 0.0001, + "openai-text-embedding-3-large": { + "dimensions": 3072, + "cost_per_1k_tokens": 0.00013, # verify current pricing + "quality": "high", + "speed": "medium" + }, + "voyage-3-large": { + "dimensions": 1024, + "cost_per_1k_tokens": 0.00018, # verify current pricing "quality": "high", "speed": "medium" }, diff --git a/engineering/skills/rag-architect/references/embedding_model_benchmark.md b/engineering/skills/rag-architect/references/embedding_model_benchmark.md index ff8e2b95..e6cb3dff 100644 --- a/engineering/skills/rag-architect/references/embedding_model_benchmark.md +++ b/engineering/skills/rag-architect/references/embedding_model_benchmark.md @@ -1,4 +1,6 @@ -# Embedding Model Benchmark 2024 +# Embedding Model Benchmark (historical snapshot, 2024) + +> **Staleness warning:** This benchmark is a dated snapshot. Model names, scores, and especially prices rot quickly — `text-embedding-ada-002` is legacy, and newer families (OpenAI `text-embedding-3-*`, Voyage `voyage-3` / `voyage-code-3`, Cohere `embed-v4`) have superseded several entries. Treat the *methodology* (dimensions vs. quality vs. cost trade-offs, NDCG@10 comparison protocol) as the durable content; verify current model IDs and per-token pricing against the providers' live pricing pages before recommending anything. ## Executive Summary diff --git a/engineering/skills/release-manager/README.md b/engineering/skills/release-manager/README.md deleted file mode 100644 index e9f9abca..00000000 --- a/engineering/skills/release-manager/README.md +++ /dev/null @@ -1,445 +0,0 @@ -# Release Manager - -A comprehensive release management toolkit for automating changelog generation, version bumping, and release planning based on conventional commits and industry best practices. - -## Overview - -The Release Manager skill provides three powerful Python scripts and comprehensive documentation for managing software releases: - -1. **changelog_generator.py** - Generate structured changelogs from git history -2. **version_bumper.py** - Determine correct semantic version bumps -3. **release_planner.py** - Assess release readiness and generate coordination plans - -## Quick Start - -### Prerequisites - -- Python 3.7+ -- Git repository with conventional commit messages -- No external dependencies required (uses only Python standard library) - -### Basic Usage - -```bash -# Generate changelog from recent commits -git log --oneline --since="1 month ago" | python changelog_generator.py - -# Determine version bump from commits since last tag -git log --oneline $(git describe --tags --abbrev=0)..HEAD | python version_bumper.py -c "1.2.3" - -# Assess release readiness -python release_planner.py --input assets/sample_release_plan.json -``` - -## Scripts Reference - -### changelog_generator.py - -Parses conventional commits and generates structured changelogs in multiple formats. - -**Input Options:** -- Git log text (oneline or full format) -- JSON array of commits -- Stdin or file input - -**Output Formats:** -- Markdown (Keep a Changelog format) -- JSON structured data -- Both with release statistics - -```bash -# From git log (recommended) -git log --oneline --since="last release" | python changelog_generator.py \ - --version "2.1.0" \ - --date "2024-01-15" \ - --base-url "https://github.com/yourorg/yourrepo" - -# From JSON file -python changelog_generator.py \ - --input assets/sample_commits.json \ - --input-format json \ - --format both \ - --summary - -# With custom output -git log --format="%h %s" v1.0.0..HEAD | python changelog_generator.py \ - --version "1.1.0" \ - --output CHANGELOG_DRAFT.md -``` - -**Features:** -- Parses conventional commit types (feat, fix, docs, etc.) -- Groups commits by changelog categories (Added, Fixed, Changed, etc.) -- Extracts issue references (#123, fixes #456) -- Identifies breaking changes -- Links to commits and PRs -- Generates release summary statistics - -### version_bumper.py - -Analyzes commits to determine semantic version bumps according to conventional commits. - -**Bump Rules:** -- **MAJOR:** Breaking changes (`feat!:` or `BREAKING CHANGE:`) -- **MINOR:** New features (`feat:`) -- **PATCH:** Bug fixes (`fix:`, `perf:`, `security:`) -- **NONE:** Documentation, tests, chores only - -```bash -# Basic version bump determination -git log --oneline v1.2.3..HEAD | python version_bumper.py --current-version "1.2.3" - -# With pre-release version -python version_bumper.py \ - --current-version "1.2.3" \ - --prerelease alpha \ - --input assets/sample_commits.json \ - --input-format json - -# Include bump commands and file updates -git log --oneline $(git describe --tags --abbrev=0)..HEAD | \ - python version_bumper.py \ - --current-version "$(git describe --tags --abbrev=0)" \ - --include-commands \ - --include-files \ - --analysis -``` - -**Features:** -- Supports pre-release versions (alpha, beta, rc) -- Generates bump commands for npm, Python, Rust, Git -- Provides file update snippets -- Detailed commit analysis and categorization -- Custom rules for specific commit types -- JSON and text output formats - -### release_planner.py - -Assesses release readiness and generates comprehensive release coordination plans. - -**Input:** JSON release plan with features, quality gates, and stakeholders - -```bash -# Assess release readiness -python release_planner.py --input assets/sample_release_plan.json - -# Generate full release package -python release_planner.py \ - --input release_plan.json \ - --output-format markdown \ - --include-checklist \ - --include-communication \ - --include-rollback \ - --output release_report.md -``` - -**Features:** -- Feature readiness assessment with approval tracking -- Quality gate validation and reporting -- Stakeholder communication planning -- Rollback procedure generation -- Risk analysis and timeline assessment -- Customizable test coverage thresholds -- Multiple output formats (text, JSON, Markdown) - -## File Structure - -``` -release-manager/ -├── SKILL.md # Comprehensive methodology guide -├── README.md # This file -├── changelog_generator.py # Changelog generation script -├── version_bumper.py # Version bump determination -├── release_planner.py # Release readiness assessment -├── references/ # Reference documentation -│ ├── conventional-commits-guide.md # Conventional commits specification -│ ├── release-workflow-comparison.md # Git Flow vs GitHub Flow vs Trunk-based -│ └── hotfix-procedures.md # Emergency release procedures -├── assets/ # Sample data for testing -│ ├── sample_git_log.txt # Sample git log output -│ ├── sample_git_log_full.txt # Detailed git log format -│ ├── sample_commits.json # JSON commit data -│ └── sample_release_plan.json # Release plan template -└── expected_outputs/ # Example script outputs - ├── changelog_example.md # Expected changelog format - ├── version_bump_example.txt # Version bump output - └── release_readiness_example.txt # Release assessment report -``` - -## Integration Examples - -### CI/CD Pipeline Integration - -```yaml -# .github/workflows/release.yml -name: Automated Release -on: - push: - branches: [main] - -jobs: - release: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v3 - with: - fetch-depth: 0 # Need full history - - - name: Determine version bump - id: version - run: | - CURRENT=$(git describe --tags --abbrev=0) - git log --oneline $CURRENT..HEAD | \ - python scripts/version_bumper.py -c $CURRENT --output-format json > bump.json - echo "new_version=$(jq -r '.recommended_version' bump.json)" >> $GITHUB_OUTPUT - - - name: Generate changelog - run: | - git log --oneline ${{ steps.version.outputs.current_version }}..HEAD | \ - python scripts/changelog_generator.py \ - --version "${{ steps.version.outputs.new_version }}" \ - --base-url "https://github.com/${{ github.repository }}" \ - --output CHANGELOG_ENTRY.md - - - name: Create release - uses: actions/create-release@v1 - with: - tag_name: v${{ steps.version.outputs.new_version }} - release_name: Release ${{ steps.version.outputs.new_version }} - body_path: CHANGELOG_ENTRY.md -``` - -### Git Hooks Integration - -```bash -#!/bin/bash -# .git/hooks/pre-commit -# Validate conventional commit format - -commit_msg_file=$1 -commit_msg=$(cat $commit_msg_file) - -# Simple validation (more sophisticated validation available in commitlint) -if ! echo "$commit_msg" | grep -qE "^(feat|fix|docs|style|refactor|test|chore|perf|ci|build)(\(.+\))?(!)?:"; then - echo "❌ Commit message doesn't follow conventional commits format" - echo "Expected: type(scope): description" - echo "Examples:" - echo " feat(auth): add OAuth2 integration" - echo " fix(api): resolve race condition" - echo " docs: update installation guide" - exit 1 -fi - -echo "✅ Commit message format is valid" -``` - -### Release Planning Automation - -```python -#!/usr/bin/env python3 -# generate_release_plan.py - Automatically generate release plans from project management tools - -import json -import requests -from datetime import datetime, timedelta - -def generate_release_plan_from_github(repo, milestone): - """Generate release plan from GitHub milestone and PRs.""" - - # Fetch milestone details - milestone_url = f"https://api.github.com/repos/{repo}/milestones/{milestone}" - milestone_data = requests.get(milestone_url).json() - - # Fetch associated issues/PRs - issues_url = f"https://api.github.com/repos/{repo}/issues?milestone={milestone}&state=all" - issues = requests.get(issues_url).json() - - release_plan = { - "release_name": milestone_data["title"], - "version": "TBD", # Fill in manually or extract from milestone - "target_date": milestone_data["due_on"], - "features": [] - } - - for issue in issues: - if issue.get("pull_request"): # It's a PR - feature = { - "id": f"GH-{issue['number']}", - "title": issue["title"], - "description": issue["body"][:200] + "..." if len(issue["body"]) > 200 else issue["body"], - "type": "feature", # Could be parsed from labels - "assignee": issue["assignee"]["login"] if issue["assignee"] else "", - "status": "ready" if issue["state"] == "closed" else "in_progress", - "pull_request_url": issue["pull_request"]["html_url"], - "issue_url": issue["html_url"], - "risk_level": "medium", # Could be parsed from labels - "qa_approved": "qa-approved" in [label["name"] for label in issue["labels"]], - "pm_approved": "pm-approved" in [label["name"] for label in issue["labels"]] - } - release_plan["features"].append(feature) - - return release_plan - -# Usage -if __name__ == "__main__": - plan = generate_release_plan_from_github("yourorg/yourrepo", "5") - with open("release_plan.json", "w") as f: - json.dump(plan, f, indent=2) - - print("Generated release_plan.json") - print("Run: python release_planner.py --input release_plan.json") -``` - -## Advanced Usage - -### Custom Commit Type Rules - -```bash -# Define custom rules for version bumping -python version_bumper.py \ - --current-version "1.2.3" \ - --custom-rules '{"security": "patch", "breaking": "major"}' \ - --ignore-types "docs,style,test" -``` - -### Multi-repository Release Coordination - -```bash -#!/bin/bash -# multi_repo_release.sh - Coordinate releases across multiple repositories - -repos=("frontend" "backend" "mobile" "docs") -base_version="2.1.0" - -for repo in "${repos[@]}"; do - echo "Processing $repo..." - cd "$repo" - - # Generate changelog for this repo - git log --oneline --since="1 month ago" | \ - python ../scripts/changelog_generator.py \ - --version "$base_version" \ - --output "CHANGELOG_$repo.md" - - # Determine version bump - git log --oneline $(git describe --tags --abbrev=0)..HEAD | \ - python ../scripts/version_bumper.py \ - --current-version "$(git describe --tags --abbrev=0)" > "VERSION_$repo.txt" - - cd .. -done - -echo "Generated changelogs and version recommendations for all repositories" -``` - -### Integration with Slack/Teams - -```python -#!/usr/bin/env python3 -# notify_release_status.py - -import json -import requests -import subprocess - -def send_slack_notification(webhook_url, message): - payload = {"text": message} - requests.post(webhook_url, json=payload) - -def get_release_status(): - """Get current release status from release planner.""" - result = subprocess.run( - ["python", "release_planner.py", "--input", "release_plan.json", "--output-format", "json"], - capture_output=True, text=True - ) - return json.loads(result.stdout) - -# Usage in CI/CD -status = get_release_status() -if status["assessment"]["overall_status"] == "blocked": - message = f"🚫 Release {status['version']} is BLOCKED\n" - message += f"Issues: {', '.join(status['assessment']['blocking_issues'])}" - send_slack_notification(SLACK_WEBHOOK_URL, message) -elif status["assessment"]["overall_status"] == "ready": - message = f"✅ Release {status['version']} is READY for deployment!" - send_slack_notification(SLACK_WEBHOOK_URL, message) -``` - -## Best Practices - -### Commit Message Guidelines - -1. **Use conventional commits consistently** across your team -2. **Be specific** in commit descriptions: "fix: resolve race condition in user creation" vs "fix: bug" -3. **Reference issues** when applicable: "Closes #123" or "Fixes #456" -4. **Mark breaking changes** clearly with `!` or `BREAKING CHANGE:` footer -5. **Keep first line under 50 characters** when possible - -### Release Planning - -1. **Plan releases early** with clear feature lists and target dates -2. **Set quality gates** and stick to them (test coverage, security scans, etc.) -3. **Track approvals** from all relevant stakeholders -4. **Document rollback procedures** before deployment -5. **Communicate clearly** with both internal teams and external users - -### Version Management - -1. **Follow semantic versioning** strictly for predictable releases -2. **Use pre-release versions** for beta testing and gradual rollouts -3. **Tag releases consistently** with proper version numbers -4. **Maintain backwards compatibility** when possible to avoid major version bumps -5. **Document breaking changes** thoroughly with migration guides - -## Troubleshooting - -### Common Issues - -**"No valid commits found"** -- Ensure git log contains commit messages -- Check that commits follow conventional format -- Verify input format (git-log vs json) - -**"Invalid version format"** -- Use semantic versioning: 1.2.3, not 1.2 or v1.2.3.beta -- Pre-release format: 1.2.3-alpha.1 - -**"Missing required approvals"** -- Check feature risk levels in release plan -- High/critical risk features require additional approvals -- Update approval status in JSON file - -### Debug Mode - -All scripts support verbose output for debugging: - -```bash -# Add debug logging -python changelog_generator.py --input sample.txt --debug - -# Validate input data -python -c "import json; print(json.load(open('release_plan.json')))" - -# Test with sample data first -python release_planner.py --input assets/sample_release_plan.json -``` - -## Contributing - -When extending these scripts: - -1. **Maintain backwards compatibility** for existing command-line interfaces -2. **Add comprehensive tests** for new features -3. **Update documentation** including this README and SKILL.md -4. **Follow Python standards** (PEP 8, type hints where helpful) -5. **Use only standard library** to avoid dependencies - -## License - -This skill is part of the claude-skills repository and follows the same license terms. - ---- - -For detailed methodology and background information, see [SKILL.md](SKILL.md). -For specific workflow guidance, see the [references](references/) directory. -For testing the scripts, use the sample data in the [assets](assets/) directory. \ No newline at end of file diff --git a/engineering/skills/release-manager/SKILL.md b/engineering/skills/release-manager/SKILL.md deleted file mode 100644 index b48cd509..00000000 --- a/engineering/skills/release-manager/SKILL.md +++ /dev/null @@ -1,490 +0,0 @@ ---- -name: "release-manager" -description: "Use when the user asks to plan releases, manage changelogs, coordinate deployments, create release branches, or automate versioning." ---- - -# Release Manager - -**Tier:** POWERFUL -**Category:** Engineering -**Domain:** Software Release Management & DevOps - -## Overview - -The Release Manager skill provides comprehensive tools and knowledge for managing software releases end-to-end. From parsing conventional commits to generating changelogs, determining version bumps, and orchestrating release processes, this skill ensures reliable, predictable, and well-documented software releases. - -## Core Capabilities - -- **Automated Changelog Generation** from git history using conventional commits -- **Semantic Version Bumping** based on commit analysis and breaking changes -- **Release Readiness Assessment** with comprehensive checklists and validation -- **Release Planning & Coordination** with stakeholder communication templates -- **Rollback Planning** with automated recovery procedures -- **Hotfix Management** for emergency releases -- **Feature Flag Integration** for progressive rollouts - -## Key Components - -### Scripts - -1. **changelog_generator.py** - Parses git logs and generates structured changelogs -2. **version_bumper.py** - Determines correct version bumps from conventional commits -3. **release_planner.py** - Assesses release readiness and generates coordination plans - -### Documentation - -- Comprehensive release management methodology -- Conventional commits specification and examples -- Release workflow comparisons (Git Flow, Trunk-based, GitHub Flow) -- Hotfix procedures and emergency response protocols - -## Release Management Methodology - -### Semantic Versioning (SemVer) - -Semantic Versioning follows the MAJOR.MINOR.PATCH format where: - -- **MAJOR** version when you make incompatible API changes -- **MINOR** version when you add functionality in a backwards compatible manner -- **PATCH** version when you make backwards compatible bug fixes - -#### Pre-release Versions - -Pre-release versions are denoted by appending a hyphen and identifiers: -- `1.0.0-alpha.1` - Alpha releases for early testing -- `1.0.0-beta.2` - Beta releases for wider testing -- `1.0.0-rc.1` - Release candidates for final validation - -#### Version Precedence - -Version precedence is determined by comparing each identifier: -1. `1.0.0-alpha` < `1.0.0-alpha.1` < `1.0.0-alpha.beta` < `1.0.0-beta` -2. `1.0.0-beta` < `1.0.0-beta.2` < `1.0.0-beta.11` < `1.0.0-rc.1` -3. `1.0.0-rc.1` < `1.0.0` - -### Conventional Commits - -Conventional Commits provide a structured format for commit messages that enables automated tooling: - -#### Format -``` -<type>[optional scope]: <description> - -[optional body] - -[optional footer(s)] -``` - -#### Types -- **feat**: A new feature (correlates with MINOR version bump) -- **fix**: A bug fix (correlates with PATCH version bump) -- **docs**: Documentation only changes -- **style**: Changes that do not affect the meaning of the code -- **refactor**: A code change that neither fixes a bug nor adds a feature -- **perf**: A code change that improves performance -- **test**: Adding missing tests or correcting existing tests -- **chore**: Changes to the build process or auxiliary tools -- **ci**: Changes to CI configuration files and scripts -- **build**: Changes that affect the build system or external dependencies -- **breaking**: Introduces a breaking change (correlates with MAJOR version bump) - -#### Examples -``` -feat(user-auth): add OAuth2 integration - -fix(api): resolve race condition in user creation - -docs(readme): update installation instructions - -feat!: remove deprecated payment API -BREAKING CHANGE: The legacy payment API has been removed -``` - -### Automated Changelog Generation - -Changelogs are automatically generated from conventional commits, organized by: - -#### Structure -```markdown -# Changelog - -## [Unreleased] -### Added -### Changed -### Deprecated -### Removed -### Fixed -### Security - -## [1.2.0] - 2024-01-15 -### Added -- OAuth2 authentication support (#123) -- User preference dashboard (#145) - -### Fixed -- Race condition in user creation (#134) -- Memory leak in image processing (#156) - -### Breaking Changes -- Removed legacy payment API -``` - -#### Grouping Rules -- **Added** for new features (feat) -- **Fixed** for bug fixes (fix) -- **Changed** for changes in existing functionality -- **Deprecated** for soon-to-be removed features -- **Removed** for now removed features -- **Security** for vulnerability fixes - -#### Metadata Extraction -- Link to pull requests and issues: `(#123)` -- Breaking changes highlighted prominently -- Scope-based grouping: `auth:`, `api:`, `ui:` -- Co-authored-by for contributor recognition - -### Version Bump Strategies - -Version bumps are determined by analyzing commits since the last release: - -#### Automatic Detection Rules -1. **MAJOR**: Any commit with `BREAKING CHANGE` or `!` after type -2. **MINOR**: Any `feat` type commits without breaking changes -3. **PATCH**: `fix`, `perf`, `security` type commits -4. **NO BUMP**: `docs`, `style`, `test`, `chore`, `ci`, `build` only - -#### Pre-release Handling -```python -# Alpha: 1.0.0-alpha.1 → 1.0.0-alpha.2 -# Beta: 1.0.0-alpha.5 → 1.0.0-beta.1 -# RC: 1.0.0-beta.3 → 1.0.0-rc.1 -# Release: 1.0.0-rc.2 → 1.0.0 -``` - -#### Multi-package Considerations -For monorepos with multiple packages: -- Analyze commits affecting each package independently -- Support scoped version bumps: `@scope/package@1.2.3` -- Generate coordinated release plans across packages - -### Release Branch Workflows - -#### Git Flow -``` -main (production) ← release/1.2.0 ← develop ← feature/login - ← hotfix/critical-fix -``` - -**Advantages:** -- Clear separation of concerns -- Stable main branch -- Parallel feature development -- Structured release process - -**Process:** -1. Create release branch from develop: `git checkout -b release/1.2.0 develop` -2. Finalize release (version bump, changelog) -3. Merge to main and develop -4. Tag release: `git tag v1.2.0` -5. Deploy from main - -#### Trunk-based Development -``` -main ← feature/login (short-lived) - ← feature/payment (short-lived) - ← hotfix/critical-fix -``` - -**Advantages:** -- Simplified workflow -- Faster integration -- Reduced merge conflicts -- Continuous integration friendly - -**Process:** -1. Short-lived feature branches (1-3 days) -2. Frequent commits to main -3. Feature flags for incomplete features -4. Automated testing gates -5. Deploy from main with feature toggles - -#### GitHub Flow -``` -main ← feature/login - ← hotfix/critical-fix -``` - -**Advantages:** -- Simple and lightweight -- Fast deployment cycle -- Good for web applications -- Minimal overhead - -**Process:** -1. Create feature branch from main -2. Regular commits and pushes -3. Open pull request when ready -4. Deploy from feature branch for testing -5. Merge to main and deploy - -### Feature Flag Integration - -Feature flags enable safe, progressive rollouts: - -#### Types of Feature Flags -- **Release flags**: Control feature visibility in production -- **Experiment flags**: A/B testing and gradual rollouts -- **Operational flags**: Circuit breakers and performance toggles -- **Permission flags**: Role-based feature access - -#### Implementation Strategy -```python -# Progressive rollout example -if feature_flag("new_payment_flow", user_id): - return new_payment_processor.process(payment) -else: - return legacy_payment_processor.process(payment) -``` - -#### Release Coordination -1. Deploy code with feature behind flag (disabled) -2. Gradually enable for percentage of users -3. Monitor metrics and error rates -4. Full rollout or quick rollback based on data -5. Remove flag in subsequent release - -### Release Readiness Checklists - -#### Pre-Release Validation -- [ ] All planned features implemented and tested -- [ ] Breaking changes documented with migration guide -- [ ] API documentation updated -- [ ] Database migrations tested -- [ ] Security review completed for sensitive changes -- [ ] Performance testing passed thresholds -- [ ] Internationalization strings updated -- [ ] Third-party integrations validated - -#### Quality Gates -- [ ] Unit test coverage ≥ 85% -- [ ] Integration tests passing -- [ ] End-to-end tests passing -- [ ] Static analysis clean -- [ ] Security scan passed -- [ ] Dependency audit clean -- [ ] Load testing completed - -#### Documentation Requirements -- [ ] CHANGELOG.md updated -- [ ] README.md reflects new features -- [ ] API documentation generated -- [ ] Migration guide written for breaking changes -- [ ] Deployment notes prepared -- [ ] Rollback procedure documented - -#### Stakeholder Approvals -- [ ] Product Manager sign-off -- [ ] Engineering Lead approval -- [ ] QA validation complete -- [ ] Security team clearance -- [ ] Legal review (if applicable) -- [ ] Compliance check (if regulated) - -### Deployment Coordination - -#### Communication Plan -**Internal Stakeholders:** -- Engineering team: Technical changes and rollback procedures -- Product team: Feature descriptions and user impact -- Support team: Known issues and troubleshooting guides -- Sales team: Customer-facing changes and talking points - -**External Communication:** -- Release notes for users -- API changelog for developers -- Migration guide for breaking changes -- Downtime notifications if applicable - -#### Deployment Sequence -1. **Pre-deployment** (T-24h): Final validation, freeze code -2. **Database migrations** (T-2h): Run and validate schema changes -3. **Blue-green deployment** (T-0): Switch traffic gradually -4. **Post-deployment** (T+1h): Monitor metrics and logs -5. **Rollback window** (T+4h): Decision point for rollback - -#### Monitoring & Validation -- Application health checks -- Error rate monitoring -- Performance metrics tracking -- User experience monitoring -- Business metrics validation -- Third-party service integration health - -### Hotfix Procedures - -Hotfixes address critical production issues requiring immediate deployment: - -#### Severity Classification -**P0 - Critical**: Complete system outage, data loss, security breach -- **SLA**: Fix within 2 hours -- **Process**: Emergency deployment, all hands on deck -- **Approval**: Engineering Lead + On-call Manager - -**P1 - High**: Major feature broken, significant user impact -- **SLA**: Fix within 24 hours -- **Process**: Expedited review and deployment -- **Approval**: Engineering Lead + Product Manager - -**P2 - Medium**: Minor feature issues, limited user impact -- **SLA**: Fix in next release cycle -- **Process**: Normal review process -- **Approval**: Standard PR review - -#### Emergency Response Process -1. **Incident declaration**: Page on-call team -2. **Assessment**: Determine severity and impact -3. **Hotfix branch**: Create from last stable release -4. **Minimal fix**: Address root cause only -5. **Expedited testing**: Automated tests + manual validation -6. **Emergency deployment**: Deploy to production -7. **Post-incident**: Root cause analysis and prevention - -### Rollback Planning - -Every release must have a tested rollback plan: - -#### Rollback Triggers -- **Error rate spike**: >2x baseline within 30 minutes -- **Performance degradation**: >50% latency increase -- **Feature failures**: Core functionality broken -- **Security incident**: Vulnerability exploited -- **Data corruption**: Database integrity compromised - -#### Rollback Types -**Code Rollback:** -- Revert to previous Docker image -- Database-compatible code changes only -- Feature flag disable preferred over code rollback - -**Database Rollback:** -- Only for non-destructive migrations -- Data backup required before migration -- Forward-only migrations preferred (add columns, not drop) - -**Infrastructure Rollback:** -- Blue-green deployment switch -- Load balancer configuration revert -- DNS changes (longer propagation time) - -#### Automated Rollback -```python -# Example rollback automation -def monitor_deployment(): - if error_rate() > THRESHOLD: - alert_oncall("Error rate spike detected") - if auto_rollback_enabled(): - execute_rollback() -``` - -### Release Metrics & Analytics - -#### Key Performance Indicators -- **Lead Time**: From commit to production -- **Deployment Frequency**: Releases per week/month -- **Mean Time to Recovery**: From incident to resolution -- **Change Failure Rate**: Percentage of releases causing incidents - -#### Quality Metrics -- **Rollback Rate**: Percentage of releases rolled back -- **Hotfix Rate**: Hotfixes per regular release -- **Bug Escape Rate**: Production bugs per release -- **Time to Detection**: How quickly issues are identified - -#### Process Metrics -- **Review Time**: Time spent in code review -- **Testing Time**: Automated + manual testing duration -- **Approval Cycle**: Time from PR to merge -- **Release Preparation**: Time spent on release activities - -### Tool Integration - -#### Version Control Systems -- **Git**: Primary VCS with conventional commit parsing -- **GitHub/GitLab**: Pull request automation and CI/CD -- **Bitbucket**: Pipeline integration and deployment gates - -#### CI/CD Platforms -- **Jenkins**: Pipeline orchestration and deployment automation -- **GitHub Actions**: Workflow automation and release publishing -- **GitLab CI**: Integrated pipelines with environment management -- **CircleCI**: Container-based builds and deployments - -#### Monitoring & Alerting -- **DataDog**: Application performance monitoring -- **New Relic**: Error tracking and performance insights -- **Sentry**: Error aggregation and release tracking -- **PagerDuty**: Incident response and escalation - -#### Communication Platforms -- **Slack**: Release notifications and coordination -- **Microsoft Teams**: Stakeholder communication -- **Email**: External customer notifications -- **Status Pages**: Public incident communication - -## Best Practices - -### Release Planning -1. **Regular cadence**: Establish predictable release schedule -2. **Feature freeze**: Lock changes 48h before release -3. **Risk assessment**: Evaluate changes for potential impact -4. **Stakeholder alignment**: Ensure all teams are prepared - -### Quality Assurance -1. **Automated testing**: Comprehensive test coverage -2. **Staging environment**: Production-like testing environment -3. **Canary releases**: Gradual rollout to subset of users -4. **Monitoring**: Proactive issue detection - -### Communication -1. **Clear timelines**: Communicate schedules early -2. **Regular updates**: Status reports during release process -3. **Issue transparency**: Honest communication about problems -4. **Post-mortems**: Learn from incidents and improve - -### Automation -1. **Reduce manual steps**: Automate repetitive tasks -2. **Consistent process**: Same steps every time -3. **Audit trails**: Log all release activities -4. **Self-service**: Enable teams to deploy safely - -## Common Anti-patterns - -### Process Anti-patterns -- **Manual deployments**: Error-prone and inconsistent -- **Last-minute changes**: Risk introduction without proper testing -- **Skipping testing**: Deploying without validation -- **Poor communication**: Stakeholders unaware of changes - -### Technical Anti-patterns -- **Monolithic releases**: Large, infrequent releases with high risk -- **Coupled deployments**: Services that must be deployed together -- **No rollback plan**: Unable to quickly recover from issues -- **Environment drift**: Production differs from staging - -### Cultural Anti-patterns -- **Blame culture**: Fear of making changes or reporting issues -- **Hero culture**: Relying on individuals instead of process -- **Perfectionism**: Delaying releases for minor improvements -- **Risk aversion**: Avoiding necessary changes due to fear - -## Getting Started - -1. **Assessment**: Evaluate current release process and pain points -2. **Tool setup**: Configure scripts for your repository -3. **Process definition**: Choose appropriate workflow for your team -4. **Automation**: Implement CI/CD pipelines and quality gates -5. **Training**: Educate team on new processes and tools -6. **Monitoring**: Set up metrics and alerting for releases -7. **Iteration**: Continuously improve based on feedback and metrics - -The Release Manager skill transforms chaotic deployments into predictable, reliable releases that build confidence across your entire organization. \ No newline at end of file diff --git a/engineering/skills/release-manager/assets/sample_commits.json b/engineering/skills/release-manager/assets/sample_commits.json deleted file mode 100644 index 543a2b81..00000000 --- a/engineering/skills/release-manager/assets/sample_commits.json +++ /dev/null @@ -1,80 +0,0 @@ -[ - { - "hash": "a1b2c3d", - "author": "Sarah Johnson <sarah.johnson@example.com>", - "date": "2024-01-15T14:30:22Z", - "message": "feat(auth): add OAuth2 integration with Google and GitHub\n\nImplement OAuth2 authentication flow supporting Google and GitHub providers.\nUsers can now sign in using their existing social media accounts, improving\nuser experience and reducing password fatigue.\n\n- Add OAuth2 client configuration\n- Implement authorization code flow\n- Add user profile mapping from providers\n- Include comprehensive error handling\n\nCloses #123\nResolves #145" - }, - { - "hash": "e4f5g6h", - "author": "Mike Chen <mike.chen@example.com>", - "date": "2024-01-15T13:45:18Z", - "message": "fix(api): resolve race condition in user creation endpoint\n\nFixed a race condition that occurred when multiple requests attempted\nto create users with the same email address simultaneously. This was\ncausing duplicate user records in some edge cases.\n\n- Added database unique constraint on email field\n- Implemented proper error handling for constraint violations\n- Added retry logic with exponential backoff\n\nFixes #234" - }, - { - "hash": "i7j8k9l", - "author": "Emily Davis <emily.davis@example.com>", - "date": "2024-01-15T12:20:45Z", - "message": "docs(readme): update installation and deployment instructions\n\nUpdated README with comprehensive installation guide including:\n- Docker setup instructions\n- Environment variable configuration\n- Database migration steps\n- Troubleshooting common issues" - }, - { - "hash": "m1n2o3p", - "author": "David Wilson <david.wilson@example.com>", - "date": "2024-01-15T11:15:30Z", - "message": "feat(ui)!: redesign dashboard with new component library\n\nComplete redesign of the user dashboard using our new component library.\nThis provides better accessibility, improved mobile responsiveness, and\na more modern user interface.\n\nBREAKING CHANGE: The dashboard API endpoints have changed structure.\nFrontend clients must update to use the new /v2/dashboard endpoints.\nThe legacy /v1/dashboard endpoints will be removed in version 3.0.0.\n\n- Implement new Card, Grid, and Chart components\n- Add responsive breakpoints for mobile devices\n- Improve accessibility with proper ARIA labels\n- Add dark mode support\n\nCloses #345, #367, #389" - }, - { - "hash": "q4r5s6t", - "author": "Lisa Rodriguez <lisa.rodriguez@example.com>", - "date": "2024-01-15T10:45:12Z", - "message": "fix(db): optimize slow query in user search functionality\n\nOptimized the user search query that was causing performance issues\non databases with large user counts. Query time reduced from 2.5s to 150ms.\n\n- Added composite index on (email, username, created_at)\n- Refactored query to use more efficient JOIN structure\n- Added query result caching for common search patterns\n\nFixes #456" - }, - { - "hash": "u7v8w9x", - "author": "Tom Anderson <tom.anderson@example.com>", - "date": "2024-01-15T09:30:55Z", - "message": "chore(deps): upgrade React to version 18.2.0\n\nUpgrade React and related dependencies to latest stable versions.\nThis includes performance improvements and new concurrent features.\n\n- React: 17.0.2 → 18.2.0\n- React-DOM: 17.0.2 → 18.2.0\n- React-Router: 6.8.0 → 6.8.1\n- Updated all peer dependencies" - }, - { - "hash": "y1z2a3b", - "author": "Jennifer Kim <jennifer.kim@example.com>", - "date": "2024-01-15T08:15:33Z", - "message": "test(auth): add comprehensive tests for OAuth flow\n\nAdded unit and integration tests for the OAuth2 authentication system\nto ensure reliability and prevent regressions.\n\n- Unit tests for OAuth client configuration\n- Integration tests for complete auth flow\n- Mock providers for testing without external dependencies\n- Error scenario testing\n\nTest coverage increased from 72% to 89% for auth module." - }, - { - "hash": "c4d5e6f", - "author": "Alex Thompson <alex.thompson@example.com>", - "date": "2024-01-15T07:45:20Z", - "message": "perf(image): implement WebP compression reducing size by 40%\n\nReplaced PNG compression with WebP format for uploaded images.\nThis reduces average image file sizes by 40% while maintaining\nvisual quality, improving page load times and reducing bandwidth costs.\n\n- Add WebP encoding support\n- Implement fallback to PNG for older browsers\n- Add quality settings configuration\n- Update image serving endpoints\n\nPerformance improvement: Page load time reduced by 25% on average." - }, - { - "hash": "g7h8i9j", - "author": "Rachel Green <rachel.green@example.com>", - "date": "2024-01-14T16:20:10Z", - "message": "feat(payment): add Stripe payment processor integration\n\nIntegrate Stripe as a payment processor to support credit card payments.\nThis enables users to purchase premium features and subscriptions.\n\n- Add Stripe SDK integration\n- Implement payment intent flow\n- Add webhook handling for payment status updates\n- Include comprehensive error handling and logging\n- Add payment method management for users\n\nCloses #567\nCo-authored-by: Payment Team <payments@example.com>" - }, - { - "hash": "k1l2m3n", - "author": "Chris Martinez <chris.martinez@example.com>", - "date": "2024-01-14T15:30:45Z", - "message": "fix(ui): resolve mobile navigation menu overflow issue\n\nFixed navigation menu overflow on mobile devices where long menu items\nwere being cut off and causing horizontal scrolling issues.\n\n- Implement responsive text wrapping\n- Add horizontal scrolling for overflowing content\n- Improve touch targets for better mobile usability\n- Fix z-index conflicts with dropdown menus\n\nFixes #678\nTested on iOS Safari, Chrome Mobile, and Firefox Mobile" - }, - { - "hash": "o4p5q6r", - "author": "Anna Kowalski <anna.kowalski@example.com>", - "date": "2024-01-14T14:20:15Z", - "message": "refactor(api): extract validation logic into reusable middleware\n\nExtracted common validation logic from individual API endpoints into\nreusable middleware functions to reduce code duplication and improve\nmaintainability.\n\n- Create validation middleware for common patterns\n- Refactor user, product, and order endpoints\n- Add comprehensive error messages\n- Improve validation performance by 30%" - }, - { - "hash": "s7t8u9v", - "author": "Kevin Park <kevin.park@example.com>", - "date": "2024-01-14T13:10:30Z", - "message": "feat(search): implement fuzzy search with Elasticsearch\n\nImplemented fuzzy search functionality using Elasticsearch to provide\nbetter search results for users with typos or partial matches.\n\n- Integrate Elasticsearch cluster\n- Add fuzzy matching with configurable distance\n- Implement search result ranking algorithm\n- Add search analytics and logging\n\nSearch accuracy improved by 35% in user testing.\nCloses #789" - }, - { - "hash": "w1x2y3z", - "author": "Security Team <security@example.com>", - "date": "2024-01-14T12:45:22Z", - "message": "fix(security): patch SQL injection vulnerability in reports\n\nPatched SQL injection vulnerability in the reports generation endpoint\nthat could allow unauthorized access to sensitive data.\n\n- Implement parameterized queries for all report filters\n- Add input sanitization and validation\n- Update security audit logging\n- Add automated security tests\n\nSeverity: HIGH - CVE-2024-0001\nReported by: External security researcher" - } -] \ No newline at end of file diff --git a/engineering/skills/release-manager/assets/sample_git_log_full.txt b/engineering/skills/release-manager/assets/sample_git_log_full.txt deleted file mode 100644 index 448b28a6..00000000 --- a/engineering/skills/release-manager/assets/sample_git_log_full.txt +++ /dev/null @@ -1,163 +0,0 @@ -commit a1b2c3d4e5f6789012345678901234567890abcd -Author: Sarah Johnson <sarah.johnson@example.com> -Date: Mon Jan 15 14:30:22 2024 +0000 - - feat(auth): add OAuth2 integration with Google and GitHub - - Implement OAuth2 authentication flow supporting Google and GitHub providers. - Users can now sign in using their existing social media accounts, improving - user experience and reducing password fatigue. - - - Add OAuth2 client configuration - - Implement authorization code flow - - Add user profile mapping from providers - - Include comprehensive error handling - - Closes #123 - Resolves #145 - -commit e4f5g6h7i8j9012345678901234567890123abcdef -Author: Mike Chen <mike.chen@example.com> -Date: Mon Jan 15 13:45:18 2024 +0000 - - fix(api): resolve race condition in user creation endpoint - - Fixed a race condition that occurred when multiple requests attempted - to create users with the same email address simultaneously. This was - causing duplicate user records in some edge cases. - - - Added database unique constraint on email field - - Implemented proper error handling for constraint violations - - Added retry logic with exponential backoff - - Fixes #234 - -commit i7j8k9l0m1n2345678901234567890123456789abcd -Author: Emily Davis <emily.davis@example.com> -Date: Mon Jan 15 12:20:45 2024 +0000 - - docs(readme): update installation and deployment instructions - - Updated README with comprehensive installation guide including: - - Docker setup instructions - - Environment variable configuration - - Database migration steps - - Troubleshooting common issues - -commit m1n2o3p4q5r6789012345678901234567890abcdefg -Author: David Wilson <david.wilson@example.com> -Date: Mon Jan 15 11:15:30 2024 +0000 - - feat(ui)!: redesign dashboard with new component library - - Complete redesign of the user dashboard using our new component library. - This provides better accessibility, improved mobile responsiveness, and - a more modern user interface. - - BREAKING CHANGE: The dashboard API endpoints have changed structure. - Frontend clients must update to use the new /v2/dashboard endpoints. - The legacy /v1/dashboard endpoints will be removed in version 3.0.0. - - - Implement new Card, Grid, and Chart components - - Add responsive breakpoints for mobile devices - - Improve accessibility with proper ARIA labels - - Add dark mode support - - Closes #345, #367, #389 - -commit q4r5s6t7u8v9012345678901234567890123456abcd -Author: Lisa Rodriguez <lisa.rodriguez@example.com> -Date: Mon Jan 15 10:45:12 2024 +0000 - - fix(db): optimize slow query in user search functionality - - Optimized the user search query that was causing performance issues - on databases with large user counts. Query time reduced from 2.5s to 150ms. - - - Added composite index on (email, username, created_at) - - Refactored query to use more efficient JOIN structure - - Added query result caching for common search patterns - - Fixes #456 - -commit u7v8w9x0y1z2345678901234567890123456789abcde -Author: Tom Anderson <tom.anderson@example.com> -Date: Mon Jan 15 09:30:55 2024 +0000 - - chore(deps): upgrade React to version 18.2.0 - - Upgrade React and related dependencies to latest stable versions. - This includes performance improvements and new concurrent features. - - - React: 17.0.2 → 18.2.0 - - React-DOM: 17.0.2 → 18.2.0 - - React-Router: 6.8.0 → 6.8.1 - - Updated all peer dependencies - -commit y1z2a3b4c5d6789012345678901234567890abcdefg -Author: Jennifer Kim <jennifer.kim@example.com> -Date: Mon Jan 15 08:15:33 2024 +0000 - - test(auth): add comprehensive tests for OAuth flow - - Added unit and integration tests for the OAuth2 authentication system - to ensure reliability and prevent regressions. - - - Unit tests for OAuth client configuration - - Integration tests for complete auth flow - - Mock providers for testing without external dependencies - - Error scenario testing - - Test coverage increased from 72% to 89% for auth module. - -commit c4d5e6f7g8h9012345678901234567890123456abcd -Author: Alex Thompson <alex.thompson@example.com> -Date: Mon Jan 15 07:45:20 2024 +0000 - - perf(image): implement WebP compression reducing size by 40% - - Replaced PNG compression with WebP format for uploaded images. - This reduces average image file sizes by 40% while maintaining - visual quality, improving page load times and reducing bandwidth costs. - - - Add WebP encoding support - - Implement fallback to PNG for older browsers - - Add quality settings configuration - - Update image serving endpoints - - Performance improvement: Page load time reduced by 25% on average. - -commit g7h8i9j0k1l2345678901234567890123456789abcde -Author: Rachel Green <rachel.green@example.com> -Date: Sun Jan 14 16:20:10 2024 +0000 - - feat(payment): add Stripe payment processor integration - - Integrate Stripe as a payment processor to support credit card payments. - This enables users to purchase premium features and subscriptions. - - - Add Stripe SDK integration - - Implement payment intent flow - - Add webhook handling for payment status updates - - Include comprehensive error handling and logging - - Add payment method management for users - - Closes #567 - Co-authored-by: Payment Team <payments@example.com> - -commit k1l2m3n4o5p6789012345678901234567890abcdefg -Author: Chris Martinez <chris.martinez@example.com> -Date: Sun Jan 14 15:30:45 2024 +0000 - - fix(ui): resolve mobile navigation menu overflow issue - - Fixed navigation menu overflow on mobile devices where long menu items - were being cut off and causing horizontal scrolling issues. - - - Implement responsive text wrapping - - Add horizontal scrolling for overflowing content - - Improve touch targets for better mobile usability - - Fix z-index conflicts with dropdown menus - - Fixes #678 - Tested on iOS Safari, Chrome Mobile, and Firefox Mobile \ No newline at end of file diff --git a/engineering/skills/release-manager/assets/sample_release_plan.json b/engineering/skills/release-manager/assets/sample_release_plan.json deleted file mode 100644 index 8b9e6652..00000000 --- a/engineering/skills/release-manager/assets/sample_release_plan.json +++ /dev/null @@ -1,273 +0,0 @@ -{ - "release_name": "Winter 2024 Release", - "version": "2.3.0", - "target_date": "2024-02-15T10:00:00Z", - "features": [ - { - "id": "AUTH-123", - "title": "OAuth2 Integration", - "description": "Add support for Google and GitHub OAuth2 authentication", - "type": "feature", - "assignee": "sarah.johnson@example.com", - "status": "ready", - "pull_request_url": "https://github.com/ourapp/backend/pull/234", - "issue_url": "https://github.com/ourapp/backend/issues/123", - "risk_level": "medium", - "test_coverage_required": 85.0, - "test_coverage_actual": 89.5, - "requires_migration": false, - "breaking_changes": [], - "dependencies": ["AUTH-124"], - "qa_approved": true, - "security_approved": true, - "pm_approved": true - }, - { - "id": "UI-345", - "title": "Dashboard Redesign", - "description": "Complete redesign of user dashboard with new component library", - "type": "breaking_change", - "assignee": "david.wilson@example.com", - "status": "ready", - "pull_request_url": "https://github.com/ourapp/frontend/pull/456", - "issue_url": "https://github.com/ourapp/frontend/issues/345", - "risk_level": "high", - "test_coverage_required": 90.0, - "test_coverage_actual": 92.3, - "requires_migration": true, - "migration_complexity": "moderate", - "breaking_changes": [ - "Dashboard API endpoints changed from /v1/dashboard to /v2/dashboard", - "Dashboard widget configuration format updated" - ], - "dependencies": [], - "qa_approved": true, - "security_approved": true, - "pm_approved": true - }, - { - "id": "PAY-567", - "title": "Stripe Payment Integration", - "description": "Add Stripe as payment processor for premium features", - "type": "feature", - "assignee": "rachel.green@example.com", - "status": "ready", - "pull_request_url": "https://github.com/ourapp/backend/pull/678", - "issue_url": "https://github.com/ourapp/backend/issues/567", - "risk_level": "high", - "test_coverage_required": 95.0, - "test_coverage_actual": 97.2, - "requires_migration": true, - "migration_complexity": "complex", - "breaking_changes": [], - "dependencies": ["SEC-890"], - "qa_approved": true, - "security_approved": true, - "pm_approved": true - }, - { - "id": "SEARCH-789", - "title": "Elasticsearch Fuzzy Search", - "description": "Implement fuzzy search functionality with Elasticsearch", - "type": "feature", - "assignee": "kevin.park@example.com", - "status": "in_progress", - "pull_request_url": "https://github.com/ourapp/backend/pull/890", - "issue_url": "https://github.com/ourapp/backend/issues/789", - "risk_level": "medium", - "test_coverage_required": 80.0, - "test_coverage_actual": 76.5, - "requires_migration": true, - "migration_complexity": "moderate", - "breaking_changes": [], - "dependencies": ["INFRA-234"], - "qa_approved": false, - "security_approved": true, - "pm_approved": true - }, - { - "id": "MOBILE-456", - "title": "Biometric Authentication", - "description": "Add fingerprint and face ID support for mobile apps", - "type": "feature", - "assignee": "alex.thompson@example.com", - "status": "blocked", - "pull_request_url": null, - "issue_url": "https://github.com/ourapp/mobile/issues/456", - "risk_level": "medium", - "test_coverage_required": 85.0, - "test_coverage_actual": null, - "requires_migration": false, - "breaking_changes": [], - "dependencies": ["AUTH-123"], - "qa_approved": false, - "security_approved": false, - "pm_approved": true - }, - { - "id": "PERF-678", - "title": "Redis Caching Implementation", - "description": "Implement Redis caching for frequently accessed data", - "type": "performance", - "assignee": "lisa.rodriguez@example.com", - "status": "ready", - "pull_request_url": "https://github.com/ourapp/backend/pull/901", - "issue_url": "https://github.com/ourapp/backend/issues/678", - "risk_level": "low", - "test_coverage_required": 75.0, - "test_coverage_actual": 82.1, - "requires_migration": false, - "breaking_changes": [], - "dependencies": [], - "qa_approved": true, - "security_approved": false, - "pm_approved": true - } - ], - "quality_gates": [ - { - "name": "Unit Test Coverage", - "required": true, - "status": "ready", - "details": "Overall test coverage above 85% threshold", - "threshold": 85.0, - "actual_value": 87.3 - }, - { - "name": "Integration Tests", - "required": true, - "status": "ready", - "details": "All integration tests passing" - }, - { - "name": "Security Scan", - "required": true, - "status": "pending", - "details": "Waiting for security team review of payment integration" - }, - { - "name": "Performance Testing", - "required": true, - "status": "ready", - "details": "Load testing shows 99th percentile response time under 500ms" - }, - { - "name": "Documentation Review", - "required": true, - "status": "pending", - "details": "API documentation needs update for dashboard changes" - }, - { - "name": "Dependency Audit", - "required": true, - "status": "ready", - "details": "No high or critical vulnerabilities found" - } - ], - "stakeholders": [ - { - "name": "Engineering Team", - "role": "developer", - "contact": "engineering@example.com", - "notification_type": "slack", - "critical_path": true - }, - { - "name": "Product Team", - "role": "pm", - "contact": "product@example.com", - "notification_type": "email", - "critical_path": true - }, - { - "name": "QA Team", - "role": "qa", - "contact": "qa@example.com", - "notification_type": "slack", - "critical_path": true - }, - { - "name": "Security Team", - "role": "security", - "contact": "security@example.com", - "notification_type": "email", - "critical_path": false - }, - { - "name": "Customer Support", - "role": "support", - "contact": "support@example.com", - "notification_type": "email", - "critical_path": false - }, - { - "name": "Sales Team", - "role": "sales", - "contact": "sales@example.com", - "notification_type": "email", - "critical_path": false - }, - { - "name": "Beta Users", - "role": "customer", - "contact": "beta-users@example.com", - "notification_type": "email", - "critical_path": false - } - ], - "rollback_steps": [ - { - "order": 1, - "description": "Alert incident response team and stakeholders", - "estimated_time": "2 minutes", - "risk_level": "low", - "verification": "Confirm team is aware and responding via Slack" - }, - { - "order": 2, - "description": "Switch load balancer to previous version", - "command": "kubectl patch service app --patch '{\"spec\": {\"selector\": {\"version\": \"v2.2.1\"}}}'", - "estimated_time": "30 seconds", - "risk_level": "low", - "verification": "Check traffic routing to previous version via monitoring dashboard" - }, - { - "order": 3, - "description": "Disable new feature flags", - "command": "curl -X POST https://api.example.com/feature-flags/oauth2/disable", - "estimated_time": "1 minute", - "risk_level": "low", - "verification": "Verify feature flags are disabled in admin panel" - }, - { - "order": 4, - "description": "Roll back database migrations", - "command": "python manage.py migrate app 0042", - "estimated_time": "10 minutes", - "risk_level": "high", - "verification": "Verify database schema and run data integrity checks" - }, - { - "order": 5, - "description": "Clear Redis cache", - "command": "redis-cli FLUSHALL", - "estimated_time": "30 seconds", - "risk_level": "medium", - "verification": "Confirm cache is cleared and application rebuilds cache properly" - }, - { - "order": 6, - "description": "Verify application health", - "estimated_time": "5 minutes", - "risk_level": "low", - "verification": "Check health endpoints, error rates, and core user workflows" - }, - { - "order": 7, - "description": "Update status page and notify users", - "estimated_time": "5 minutes", - "risk_level": "low", - "verification": "Confirm status page updated and notifications sent" - } - ] -} \ No newline at end of file diff --git a/engineering/skills/release-manager/changelog_generator.py b/engineering/skills/release-manager/changelog_generator.py deleted file mode 100644 index f50e65b4..00000000 --- a/engineering/skills/release-manager/changelog_generator.py +++ /dev/null @@ -1,504 +0,0 @@ -#!/usr/bin/env python3 -""" -Changelog Generator - -Parses git log output in conventional commits format and generates structured changelogs -in multiple formats (Markdown, Keep a Changelog). Groups commits by type, extracts scope, -links to PRs/issues, and highlights breaking changes. - -Input: git log text (piped from git log) or JSON array of commits -Output: formatted CHANGELOG.md section + release summary stats -""" - -import argparse -import json -import re -import sys -from collections import defaultdict, Counter -from datetime import datetime -from typing import Dict, List, Optional, Tuple, Union - - -class ConventionalCommit: - """Represents a parsed conventional commit.""" - - def __init__(self, raw_message: str, commit_hash: str = "", author: str = "", - date: str = "", merge_info: Optional[str] = None): - self.raw_message = raw_message - self.commit_hash = commit_hash - self.author = author - self.date = date - self.merge_info = merge_info - - # Parse the commit message - self.type = "" - self.scope = "" - self.description = "" - self.body = "" - self.footers = [] - self.is_breaking = False - self.breaking_change_description = "" - - self._parse_commit_message() - - def _parse_commit_message(self): - """Parse conventional commit format.""" - lines = self.raw_message.split('\n') - header = lines[0] if lines else "" - - # Parse header: type(scope): description - header_pattern = r'^(\w+)(\([^)]+\))?(!)?:\s*(.+)$' - match = re.match(header_pattern, header) - - if match: - self.type = match.group(1).lower() - scope_match = match.group(2) - self.scope = scope_match[1:-1] if scope_match else "" # Remove parentheses - self.is_breaking = bool(match.group(3)) # ! indicates breaking change - self.description = match.group(4).strip() - else: - # Fallback for non-conventional commits - self.type = "chore" - self.description = header - - # Parse body and footers - if len(lines) > 1: - body_lines = [] - footer_lines = [] - in_footer = False - - for line in lines[1:]: - if not line.strip(): - continue - - # Check if this is a footer (KEY: value or KEY #value format) - footer_pattern = r'^([A-Z-]+):\s*(.+)$|^([A-Z-]+)\s+#(\d+)$' - if re.match(footer_pattern, line): - in_footer = True - footer_lines.append(line) - - # Check for breaking change - if line.startswith('BREAKING CHANGE:'): - self.is_breaking = True - self.breaking_change_description = line[16:].strip() - else: - if in_footer: - # Continuation of footer - footer_lines.append(line) - else: - body_lines.append(line) - - self.body = '\n'.join(body_lines).strip() - self.footers = footer_lines - - def extract_issue_references(self) -> List[str]: - """Extract issue/PR references like #123, fixes #456, etc.""" - text = f"{self.description} {self.body} {' '.join(self.footers)}" - - # Common patterns for issue references - patterns = [ - r'#(\d+)', # Simple #123 - r'(?:close[sd]?|fix(?:e[sd])?|resolve[sd]?)\s+#(\d+)', # closes #123 - r'(?:close[sd]?|fix(?:e[sd])?|resolve[sd]?)\s+(\w+/\w+)?#(\d+)' # fixes repo#123 - ] - - references = [] - for pattern in patterns: - matches = re.findall(pattern, text, re.IGNORECASE) - for match in matches: - if isinstance(match, tuple): - # Handle tuple results from more complex patterns - ref = match[-1] if match[-1] else match[0] - else: - ref = match - if ref and ref not in references: - references.append(ref) - - return references - - def get_changelog_category(self) -> str: - """Map commit type to changelog category.""" - category_map = { - 'feat': 'Added', - 'add': 'Added', - 'fix': 'Fixed', - 'bugfix': 'Fixed', - 'security': 'Security', - 'perf': 'Fixed', # Performance improvements go to Fixed - 'refactor': 'Changed', - 'style': 'Changed', - 'docs': 'Changed', - 'test': None, # Tests don't appear in user-facing changelog - 'ci': None, - 'build': None, - 'chore': None, - 'revert': 'Fixed', - 'remove': 'Removed', - 'deprecate': 'Deprecated' - } - - return category_map.get(self.type, 'Changed') - - -class ChangelogGenerator: - """Main changelog generator class.""" - - def __init__(self): - self.commits: List[ConventionalCommit] = [] - self.version = "Unreleased" - self.date = datetime.now().strftime("%Y-%m-%d") - self.base_url = "" - - def parse_git_log_output(self, git_log_text: str): - """Parse git log output into ConventionalCommit objects.""" - # Try to detect format based on patterns in the text - lines = git_log_text.strip().split('\n') - - if not lines or not lines[0]: - return - - # Format 1: Simple oneline format (hash message) - oneline_pattern = r'^([a-f0-9]{7,40})\s+(.+)$' - - # Format 2: Full format with metadata - full_pattern = r'^commit\s+([a-f0-9]+)' - - current_commit = None - commit_buffer = [] - - for line in lines: - line = line.strip() - if not line: - continue - - # Check if this is a new commit (oneline format) - oneline_match = re.match(oneline_pattern, line) - if oneline_match: - # Process previous commit - if current_commit: - self.commits.append(current_commit) - - # Start new commit - commit_hash = oneline_match.group(1) - message = oneline_match.group(2) - current_commit = ConventionalCommit(message, commit_hash) - continue - - # Check if this is a new commit (full format) - full_match = re.match(full_pattern, line) - if full_match: - # Process previous commit - if current_commit: - commit_message = '\n'.join(commit_buffer).strip() - if commit_message: - current_commit = ConventionalCommit(commit_message, current_commit.commit_hash, - current_commit.author, current_commit.date) - self.commits.append(current_commit) - - # Start new commit - commit_hash = full_match.group(1) - current_commit = ConventionalCommit("", commit_hash) - commit_buffer = [] - continue - - # Parse metadata lines in full format - if current_commit and not current_commit.raw_message: - if line.startswith('Author:'): - current_commit.author = line[7:].strip() - elif line.startswith('Date:'): - current_commit.date = line[5:].strip() - elif line.startswith('Merge:'): - current_commit.merge_info = line[6:].strip() - elif line.startswith(' '): - # Commit message line (indented) - commit_buffer.append(line[4:]) # Remove 4-space indent - - # Process final commit - if current_commit: - if commit_buffer: - commit_message = '\n'.join(commit_buffer).strip() - current_commit = ConventionalCommit(commit_message, current_commit.commit_hash, - current_commit.author, current_commit.date) - self.commits.append(current_commit) - - def parse_json_commits(self, json_data: Union[str, List[Dict]]): - """Parse commits from JSON format.""" - if isinstance(json_data, str): - data = json.loads(json_data) - else: - data = json_data - - for commit_data in data: - commit = ConventionalCommit( - raw_message=commit_data.get('message', ''), - commit_hash=commit_data.get('hash', ''), - author=commit_data.get('author', ''), - date=commit_data.get('date', '') - ) - self.commits.append(commit) - - def group_commits_by_category(self) -> Dict[str, List[ConventionalCommit]]: - """Group commits by changelog category.""" - categories = defaultdict(list) - - for commit in self.commits: - category = commit.get_changelog_category() - if category: # Skip None categories (internal changes) - categories[category].append(commit) - - return dict(categories) - - def generate_markdown_changelog(self, include_unreleased: bool = True) -> str: - """Generate Keep a Changelog format markdown.""" - grouped_commits = self.group_commits_by_category() - - if not grouped_commits: - return "No notable changes.\n" - - # Start with header - changelog = [] - if include_unreleased and self.version == "Unreleased": - changelog.append(f"## [{self.version}]") - else: - changelog.append(f"## [{self.version}] - {self.date}") - - changelog.append("") - - # Order categories logically - category_order = ['Added', 'Changed', 'Deprecated', 'Removed', 'Fixed', 'Security'] - - # Separate breaking changes - breaking_changes = [commit for commit in self.commits if commit.is_breaking] - - # Add breaking changes section first if any exist - if breaking_changes: - changelog.append("### Breaking Changes") - for commit in breaking_changes: - line = self._format_commit_line(commit, show_breaking=True) - changelog.append(f"- {line}") - changelog.append("") - - # Add regular categories - for category in category_order: - if category not in grouped_commits: - continue - - changelog.append(f"### {category}") - - # Group by scope for better organization - scoped_commits = defaultdict(list) - for commit in grouped_commits[category]: - scope = commit.scope if commit.scope else "general" - scoped_commits[scope].append(commit) - - # Sort scopes, with 'general' last - scopes = sorted(scoped_commits.keys()) - if "general" in scopes: - scopes.remove("general") - scopes.append("general") - - for scope in scopes: - if len(scoped_commits) > 1 and scope != "general": - changelog.append(f"#### {scope.title()}") - - for commit in scoped_commits[scope]: - line = self._format_commit_line(commit) - changelog.append(f"- {line}") - - changelog.append("") - - return '\n'.join(changelog) - - def _format_commit_line(self, commit: ConventionalCommit, show_breaking: bool = False) -> str: - """Format a single commit line for the changelog.""" - # Start with description - line = commit.description.capitalize() - - # Add scope if present and not already in description - if commit.scope and commit.scope.lower() not in line.lower(): - line = f"{commit.scope}: {line}" - - # Add issue references - issue_refs = commit.extract_issue_references() - if issue_refs: - refs_str = ', '.join(f"#{ref}" for ref in issue_refs) - line += f" ({refs_str})" - - # Add commit hash if available - if commit.commit_hash: - short_hash = commit.commit_hash[:7] - line += f" [{short_hash}]" - - if self.base_url: - line += f"({self.base_url}/commit/{commit.commit_hash})" - - # Add breaking change indicator - if show_breaking and commit.breaking_change_description: - line += f" - {commit.breaking_change_description}" - elif commit.is_breaking and not show_breaking: - line += " ⚠️ BREAKING" - - return line - - def generate_release_summary(self) -> Dict: - """Generate summary statistics for the release.""" - if not self.commits: - return { - 'version': self.version, - 'date': self.date, - 'total_commits': 0, - 'by_type': {}, - 'by_author': {}, - 'breaking_changes': 0, - 'notable_changes': 0 - } - - # Count by type - type_counts = Counter(commit.type for commit in self.commits) - - # Count by author - author_counts = Counter(commit.author for commit in self.commits if commit.author) - - # Count breaking changes - breaking_count = sum(1 for commit in self.commits if commit.is_breaking) - - # Count notable changes (excluding chore, ci, build, test) - notable_types = {'feat', 'fix', 'security', 'perf', 'refactor', 'remove', 'deprecate'} - notable_count = sum(1 for commit in self.commits if commit.type in notable_types) - - return { - 'version': self.version, - 'date': self.date, - 'total_commits': len(self.commits), - 'by_type': dict(type_counts.most_common()), - 'by_author': dict(author_counts.most_common(10)), # Top 10 contributors - 'breaking_changes': breaking_count, - 'notable_changes': notable_count, - 'scopes': list(set(commit.scope for commit in self.commits if commit.scope)), - 'issue_references': len(set().union(*(commit.extract_issue_references() for commit in self.commits))) - } - - def generate_json_output(self) -> str: - """Generate JSON representation of the changelog data.""" - grouped_commits = self.group_commits_by_category() - - # Convert commits to serializable format - json_data = { - 'version': self.version, - 'date': self.date, - 'summary': self.generate_release_summary(), - 'categories': {} - } - - for category, commits in grouped_commits.items(): - json_data['categories'][category] = [] - for commit in commits: - commit_data = { - 'type': commit.type, - 'scope': commit.scope, - 'description': commit.description, - 'hash': commit.commit_hash, - 'author': commit.author, - 'date': commit.date, - 'breaking': commit.is_breaking, - 'breaking_description': commit.breaking_change_description, - 'issue_references': commit.extract_issue_references() - } - json_data['categories'][category].append(commit_data) - - return json.dumps(json_data, indent=2) - - -def main(): - """Main entry point with CLI argument parsing.""" - parser = argparse.ArgumentParser(description="Generate changelog from conventional commits") - parser.add_argument('--input', '-i', type=str, help='Input file (default: stdin)') - parser.add_argument('--format', '-f', choices=['markdown', 'json', 'both'], - default='markdown', help='Output format') - parser.add_argument('--version', '-v', type=str, default='Unreleased', - help='Version for this release') - parser.add_argument('--date', '-d', type=str, - default=datetime.now().strftime("%Y-%m-%d"), - help='Release date (YYYY-MM-DD format)') - parser.add_argument('--base-url', '-u', type=str, default='', - help='Base URL for commit links') - parser.add_argument('--input-format', choices=['git-log', 'json'], - default='git-log', help='Input format') - parser.add_argument('--output', '-o', type=str, help='Output file (default: stdout)') - parser.add_argument('--summary', '-s', action='store_true', - help='Include release summary statistics') - - args = parser.parse_args() - - # Read input - if args.input: - with open(args.input, 'r', encoding='utf-8') as f: - input_data = f.read() - else: - input_data = sys.stdin.read() - - if not input_data.strip(): - print("No input data provided", file=sys.stderr) - sys.exit(1) - - # Initialize generator - generator = ChangelogGenerator() - generator.version = args.version - generator.date = args.date - generator.base_url = args.base_url - - # Parse input - try: - if args.input_format == 'json': - generator.parse_json_commits(input_data) - else: - generator.parse_git_log_output(input_data) - except Exception as e: - print(f"Error parsing input: {e}", file=sys.stderr) - sys.exit(1) - - if not generator.commits: - print("No valid commits found in input", file=sys.stderr) - sys.exit(1) - - # Generate output - output_lines = [] - - if args.format in ['markdown', 'both']: - changelog_md = generator.generate_markdown_changelog() - if args.format == 'both': - output_lines.append("# Markdown Changelog\n") - output_lines.append(changelog_md) - - if args.format in ['json', 'both']: - changelog_json = generator.generate_json_output() - if args.format == 'both': - output_lines.append("\n# JSON Output\n") - output_lines.append(changelog_json) - - if args.summary: - summary = generator.generate_release_summary() - output_lines.append(f"\n# Release Summary") - output_lines.append(f"- **Version:** {summary['version']}") - output_lines.append(f"- **Total Commits:** {summary['total_commits']}") - output_lines.append(f"- **Notable Changes:** {summary['notable_changes']}") - output_lines.append(f"- **Breaking Changes:** {summary['breaking_changes']}") - output_lines.append(f"- **Issue References:** {summary['issue_references']}") - - if summary['by_type']: - output_lines.append("- **By Type:**") - for commit_type, count in summary['by_type'].items(): - output_lines.append(f" - {commit_type}: {count}") - - # Write output - final_output = '\n'.join(output_lines) - - if args.output: - with open(args.output, 'w', encoding='utf-8') as f: - f.write(final_output) - else: - print(final_output) - - -if __name__ == '__main__': - main() \ No newline at end of file diff --git a/engineering/skills/release-manager/expected_outputs/changelog_example.md b/engineering/skills/release-manager/expected_outputs/changelog_example.md deleted file mode 100644 index 2d6112a9..00000000 --- a/engineering/skills/release-manager/expected_outputs/changelog_example.md +++ /dev/null @@ -1,37 +0,0 @@ -# Expected Changelog Output - -## [2.3.0] - 2024-01-15 - -### Breaking Changes -- ui: redesign dashboard with new component library - The dashboard API endpoints have changed structure. Frontend clients must update to use the new /v2/dashboard endpoints. The legacy /v1/dashboard endpoints will be removed in version 3.0.0. (#345, #367, #389) [m1n2o3p] - -### Added -- auth: add OAuth2 integration with Google and GitHub (#123, #145) [a1b2c3d] -- payment: add Stripe payment processor integration (#567) [g7h8i9j] -- search: implement fuzzy search with Elasticsearch (#789) [s7t8u9v] - -### Fixed -- api: resolve race condition in user creation endpoint (#234) [e4f5g6h] -- db: optimize slow query in user search functionality (#456) [q4r5s6t] -- ui: resolve mobile navigation menu overflow issue (#678) [k1l2m3n] -- security: patch SQL injection vulnerability in reports [w1x2y3z] ⚠️ BREAKING - -### Changed -- image: implement WebP compression reducing size by 40% [c4d5e6f] -- api: extract validation logic into reusable middleware [o4p5q6r] -- readme: update installation and deployment instructions [i7j8k9l] - -# Release Summary -- **Version:** 2.3.0 -- **Total Commits:** 13 -- **Notable Changes:** 9 -- **Breaking Changes:** 2 -- **Issue References:** 8 -- **By Type:** - - feat: 4 - - fix: 4 - - perf: 1 - - refactor: 1 - - docs: 1 - - test: 1 - - chore: 1 \ No newline at end of file diff --git a/engineering/skills/release-manager/expected_outputs/release_readiness_example.txt b/engineering/skills/release-manager/expected_outputs/release_readiness_example.txt deleted file mode 100644 index 1e986876..00000000 --- a/engineering/skills/release-manager/expected_outputs/release_readiness_example.txt +++ /dev/null @@ -1,30 +0,0 @@ -Release Readiness Report -======================== -Release: Winter 2024 Release v2.3.0 -Status: AT_RISK -Readiness Score: 73.3% - -WARNINGS: - - ⚠️ Feature 'Elasticsearch Fuzzy Search' (SEARCH-789) still in progress - ⚠️ Feature 'Elasticsearch Fuzzy Search' has low test coverage: 76.5% < 80.0% - ⚠️ Required quality gate 'Security Scan' is pending - ⚠️ Required quality gate 'Documentation Review' is pending - -BLOCKING ISSUES: - - ❌ Feature 'Biometric Authentication' (MOBILE-456) is blocked - ❌ Feature 'Biometric Authentication' missing approvals: QA approval, Security approval - -RECOMMENDATIONS: - - 💡 Obtain required approvals for pending features - 💡 Improve test coverage for features below threshold - 💡 Complete pending quality gate validations - -FEATURE SUMMARY: - Total: 6 | Ready: 3 | Blocked: 1 - Breaking Changes: 1 | Missing Approvals: 1 - -QUALITY GATES: - Total: 6 | Passed: 3 | Failed: 0 \ No newline at end of file diff --git a/engineering/skills/release-manager/expected_outputs/version_bump_example.txt b/engineering/skills/release-manager/expected_outputs/version_bump_example.txt deleted file mode 100644 index c7c9d3f5..00000000 --- a/engineering/skills/release-manager/expected_outputs/version_bump_example.txt +++ /dev/null @@ -1,31 +0,0 @@ -Current Version: 2.2.5 -Recommended Version: 3.0.0 -With v prefix: v3.0.0 -Bump Type: major - -Commit Analysis: -- Total commits: 13 -- Breaking changes: 2 -- New features: 4 -- Bug fixes: 4 -- Ignored commits: 3 - -Breaking Changes: - - feat(ui): redesign dashboard with new component library - - fix(security): patch SQL injection vulnerability in reports - -Bump Commands: - npm: - npm version 3.0.0 --no-git-tag-version - python: - # Update version in setup.py, __init__.py, or pyproject.toml - # pyproject.toml: version = "3.0.0" - rust: - # Update Cargo.toml - # version = "3.0.0" - git: - git tag -a v3.0.0 -m 'Release v3.0.0' - git push origin v3.0.0 - docker: - docker build -t myapp:3.0.0 . - docker tag myapp:3.0.0 myapp:latest \ No newline at end of file diff --git a/engineering/skills/release-manager/references/conventional-commits-guide.md b/engineering/skills/release-manager/references/conventional-commits-guide.md deleted file mode 100644 index 9162648a..00000000 --- a/engineering/skills/release-manager/references/conventional-commits-guide.md +++ /dev/null @@ -1,341 +0,0 @@ -# Conventional Commits Guide - -## Overview - -Conventional Commits is a specification for adding human and machine readable meaning to commit messages. The specification provides an easy set of rules for creating an explicit commit history, which makes it easier to write automated tools for version management, changelog generation, and release planning. - -## Basic Format - -``` -<type>[optional scope]: <description> - -[optional body] - -[optional footer(s)] -``` - -## Commit Types - -### Primary Types - -- **feat**: A new feature for the user (correlates with MINOR in semantic versioning) -- **fix**: A bug fix for the user (correlates with PATCH in semantic versioning) - -### Secondary Types - -- **build**: Changes that affect the build system or external dependencies (webpack, npm, etc.) -- **ci**: Changes to CI configuration files and scripts (Travis, Circle, BrowserStack, SauceLabs) -- **docs**: Documentation only changes -- **perf**: A code change that improves performance -- **refactor**: A code change that neither fixes a bug nor adds a feature -- **style**: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc.) -- **test**: Adding missing tests or correcting existing tests -- **chore**: Other changes that don't modify src or test files -- **revert**: Reverts a previous commit - -### Breaking Changes - -Any commit can introduce a breaking change by: -1. Adding `!` after the type: `feat!: remove deprecated API` -2. Including `BREAKING CHANGE:` in the footer - -## Scopes - -Scopes provide additional contextual information about the change. They should be noun describing a section of the codebase: - -- `auth` - Authentication and authorization -- `api` - API changes -- `ui` - User interface -- `db` - Database related changes -- `config` - Configuration changes -- `deps` - Dependency updates - -## Examples - -### Simple Feature -``` -feat(auth): add OAuth2 integration - -Integrate OAuth2 authentication with Google and GitHub providers. -Users can now log in using their existing social media accounts. -``` - -### Bug Fix -``` -fix(api): resolve race condition in user creation - -When multiple requests tried to create users with the same email -simultaneously, duplicate records were sometimes created. Added -proper database constraints and error handling. - -Fixes #234 -``` - -### Breaking Change with ! -``` -feat(api)!: remove deprecated /v1/users endpoint - -The deprecated /v1/users endpoint has been removed. All clients -should migrate to /v2/users which provides better performance -and additional features. - -BREAKING CHANGE: /v1/users endpoint removed, use /v2/users instead -``` - -### Breaking Change with Footer -``` -feat(auth): implement new authentication flow - -Add support for multi-factor authentication and improved session -management. This change requires all users to re-authenticate. - -BREAKING CHANGE: Authentication tokens issued before this release -are no longer valid. Users must log in again. -``` - -### Performance Improvement -``` -perf(image): optimize image compression algorithm - -Replaced PNG compression with WebP format, reducing image sizes -by 40% on average while maintaining visual quality. - -Closes #456 -``` - -### Dependency Update -``` -build(deps): upgrade React to version 18.2.0 - -Updates React and related packages to latest stable versions. -Includes performance improvements and new concurrent features. -``` - -### Documentation -``` -docs(readme): add deployment instructions - -Added comprehensive deployment guide including Docker setup, -environment variables configuration, and troubleshooting tips. -``` - -### Revert -``` -revert: feat(payment): add cryptocurrency support - -This reverts commit 667ecc1654a317a13331b17617d973392f415f02. - -Reverting due to security concerns identified in code review. -The feature will be re-implemented with proper security measures. -``` - -## Multi-paragraph Body - -For complex changes, use multiple paragraphs in the body: - -``` -feat(search): implement advanced search functionality - -Add support for complex search queries including: -- Boolean operators (AND, OR, NOT) -- Field-specific searches (title:, author:, date:) -- Fuzzy matching with configurable threshold -- Search result highlighting - -The search index has been restructured to support these new -features while maintaining backward compatibility with existing -simple search queries. - -Performance testing shows less than 10ms impact on search -response times even with complex queries. - -Closes #789, #823, #901 -``` - -## Footers - -### Issue References -``` -Fixes #123 -Closes #234, #345 -Resolves #456 -``` - -### Breaking Changes -``` -BREAKING CHANGE: The `authenticate` function now requires a second -parameter for the authentication method. Update all calls from -`authenticate(token)` to `authenticate(token, 'bearer')`. -``` - -### Co-authors -``` -Co-authored-by: Jane Doe <jane@example.com> -Co-authored-by: John Smith <john@example.com> -``` - -### Reviewed By -``` -Reviewed-by: Senior Developer <senior@example.com> -Acked-by: Tech Lead <lead@example.com> -``` - -## Automation Benefits - -Using conventional commits enables: - -### Automatic Version Bumping -- `fix` commits trigger PATCH version bump (1.0.0 → 1.0.1) -- `feat` commits trigger MINOR version bump (1.0.0 → 1.1.0) -- `BREAKING CHANGE` triggers MAJOR version bump (1.0.0 → 2.0.0) - -### Changelog Generation -```markdown -## [1.2.0] - 2024-01-15 - -### Added -- OAuth2 integration (auth) -- Advanced search functionality (search) - -### Fixed -- Race condition in user creation (api) -- Memory leak in image processing (image) - -### Breaking Changes -- Authentication tokens issued before this release are no longer valid -``` - -### Release Notes -Generate user-friendly release notes automatically from commit history, filtering out internal changes and highlighting user-facing improvements. - -## Best Practices - -### Writing Good Descriptions -- Use imperative mood: "add feature" not "added feature" -- Start with lowercase letter -- No period at the end -- Limit to 50 characters when possible -- Be specific and descriptive - -### Good Examples -``` -feat(auth): add password reset functionality -fix(ui): resolve mobile navigation menu overflow -perf(db): optimize user query with proper indexing -``` - -### Bad Examples -``` -feat: stuff -fix: bug -update: changes -``` - -### Body Guidelines -- Separate subject from body with blank line -- Wrap body at 72 characters -- Use body to explain what and why, not how -- Reference issues and PRs when relevant - -### Scope Guidelines -- Use consistent scope naming across the team -- Keep scopes short and meaningful -- Document your team's scope conventions -- Consider using scopes that match your codebase structure - -## Tools and Integration - -### Git Hooks -Use tools like `commitizen` or `husky` to enforce conventional commit format: - -```bash -# Install commitizen -npm install -g commitizen cz-conventional-changelog - -# Configure -echo '{ "path": "cz-conventional-changelog" }' > ~/.czrc - -# Use -git cz -``` - -### Automated Validation -Add commit message validation to prevent non-conventional commits: - -```javascript -// commitlint.config.js -module.exports = { - extends: ['@commitlint/config-conventional'], - rules: { - 'type-enum': [ - 2, 'always', - ['feat', 'fix', 'docs', 'style', 'refactor', 'perf', 'test', 'build', 'ci', 'chore', 'revert'] - ], - 'subject-case': [2, 'always', 'lower-case'], - 'subject-max-length': [2, 'always', 50] - } -}; -``` - -### CI/CD Integration -Integrate with release automation tools: -- **semantic-release**: Automated version management and package publishing -- **standard-version**: Generate changelog and tag releases -- **release-please**: Google's release automation tool - -## Common Mistakes - -### Mixing Multiple Changes -``` -# Bad: Multiple unrelated changes -feat: add login page and fix CSS bug and update dependencies - -# Good: Separate commits -feat(auth): add login page -fix(ui): resolve CSS styling issue -build(deps): update React to version 18 -``` - -### Vague Descriptions -``` -# Bad: Not descriptive -fix: bug in code -feat: new stuff - -# Good: Specific and clear -fix(api): resolve null pointer exception in user validation -feat(search): implement fuzzy matching algorithm -``` - -### Missing Breaking Change Indicators -``` -# Bad: Breaking change not marked -feat(api): update user authentication - -# Good: Properly marked breaking change -feat(api)!: update user authentication - -BREAKING CHANGE: All API clients must now include authentication -headers in every request. Anonymous access is no longer supported. -``` - -## Team Guidelines - -### Establishing Conventions -1. **Define scope vocabulary**: Create a list of approved scopes for your project -2. **Document examples**: Provide team-specific examples of good commits -3. **Set up tooling**: Use linters and hooks to enforce standards -4. **Review process**: Include commit message quality in code reviews -5. **Training**: Ensure all team members understand the format - -### Scope Examples by Project Type -**Web Application:** -- `auth`, `ui`, `api`, `db`, `config`, `deploy` - -**Library/SDK:** -- `core`, `utils`, `docs`, `examples`, `tests` - -**Mobile App:** -- `ios`, `android`, `shared`, `ui`, `network`, `storage` - -By following conventional commits consistently, your team will have a clear, searchable commit history that enables powerful automation and improves the overall development workflow. \ No newline at end of file diff --git a/engineering/skills/release-manager/references/release-workflow-comparison.md b/engineering/skills/release-manager/references/release-workflow-comparison.md deleted file mode 100644 index 94f4fc4b..00000000 --- a/engineering/skills/release-manager/references/release-workflow-comparison.md +++ /dev/null @@ -1,410 +0,0 @@ -# Release Workflow Comparison - -## Overview - -This document compares the three most popular branching and release workflows: Git Flow, GitHub Flow, and Trunk-based Development. Each approach has distinct advantages and trade-offs depending on your team size, deployment frequency, and risk tolerance. - -## Git Flow - -### Structure -``` -main (production) - ↑ -release/1.2.0 ← develop (integration) ← feature/user-auth - ↑ ← feature/payment-api - hotfix/critical-fix -``` - -### Branch Types -- **main**: Production-ready code, tagged releases -- **develop**: Integration branch for next release -- **feature/***: Individual features, merged to develop -- **release/X.Y.Z**: Release preparation, branched from develop -- **hotfix/***: Critical fixes, branched from main - -### Typical Flow -1. Create feature branch from develop: `git checkout -b feature/login develop` -2. Work on feature, commit changes -3. Merge feature to develop when complete -4. When ready for release, create release branch: `git checkout -b release/1.2.0 develop` -5. Finalize release (version bump, changelog, bug fixes) -6. Merge release branch to both main and develop -7. Tag release: `git tag v1.2.0` -8. Deploy from main branch - -### Advantages -- **Clear separation** between production and development code -- **Stable main branch** always represents production state -- **Parallel development** of features without interference -- **Structured release process** with dedicated release branches -- **Hotfix support** without disrupting development work -- **Good for scheduled releases** and traditional release cycles - -### Disadvantages -- **Complex workflow** with many branch types -- **Merge overhead** from multiple integration points -- **Delayed feedback** from long-lived feature branches -- **Integration conflicts** when merging large features -- **Slower deployment** due to process overhead -- **Not ideal for continuous deployment** - -### Best For -- Large teams (10+ developers) -- Products with scheduled release cycles -- Enterprise software with formal testing phases -- Projects requiring stable release branches -- Teams comfortable with complex Git workflows - -### Example Commands -```bash -# Start new feature -git checkout develop -git checkout -b feature/user-authentication - -# Finish feature -git checkout develop -git merge --no-ff feature/user-authentication -git branch -d feature/user-authentication - -# Start release -git checkout develop -git checkout -b release/1.2.0 -# Version bump and changelog updates -git commit -am "Bump version to 1.2.0" - -# Finish release -git checkout main -git merge --no-ff release/1.2.0 -git tag -a v1.2.0 -m "Release version 1.2.0" -git checkout develop -git merge --no-ff release/1.2.0 -git branch -d release/1.2.0 - -# Hotfix -git checkout main -git checkout -b hotfix/security-patch -# Fix the issue -git commit -am "Fix security vulnerability" -git checkout main -git merge --no-ff hotfix/security-patch -git tag -a v1.2.1 -m "Hotfix version 1.2.1" -git checkout develop -git merge --no-ff hotfix/security-patch -``` - -## GitHub Flow - -### Structure -``` -main ← feature/user-auth - ← feature/payment-api - ← hotfix/critical-fix -``` - -### Branch Types -- **main**: Production-ready code, deployed automatically -- **feature/***: All changes, regardless of size or type - -### Typical Flow -1. Create feature branch from main: `git checkout -b feature/login main` -2. Work on feature with regular commits and pushes -3. Open pull request when ready for feedback -4. Deploy feature branch to staging for testing -5. Merge to main when approved and tested -6. Deploy main to production automatically -7. Delete feature branch - -### Advantages -- **Simple workflow** with only two branch types -- **Fast deployment** with minimal process overhead -- **Continuous integration** with frequent merges to main -- **Early feedback** through pull request reviews -- **Deploy from branches** allows testing before merge -- **Good for continuous deployment** - -### Disadvantages -- **Main can be unstable** if testing is insufficient -- **No release branches** for coordinating multiple features -- **Limited hotfix process** requires careful coordination -- **Requires strong testing** and CI/CD infrastructure -- **Not suitable for scheduled releases** -- **Can be chaotic** with many simultaneous features - -### Best For -- Small to medium teams (2-10 developers) -- Web applications with continuous deployment -- Products with rapid iteration cycles -- Teams with strong testing and CI/CD practices -- Projects where main is always deployable - -### Example Commands -```bash -# Start new feature -git checkout main -git pull origin main -git checkout -b feature/user-authentication - -# Regular work -git add . -git commit -m "feat(auth): add login form validation" -git push origin feature/user-authentication - -# Deploy branch for testing -# (Usually done through CI/CD) -./deploy.sh feature/user-authentication staging - -# Merge when ready -git checkout main -git merge feature/user-authentication -git push origin main -git branch -d feature/user-authentication - -# Automatic deployment to production -# (Triggered by push to main) -``` - -## Trunk-based Development - -### Structure -``` -main ← short-feature-branch (1-3 days max) - ← another-short-branch - ← direct-commits -``` - -### Branch Types -- **main**: The single source of truth, always deployable -- **Short-lived branches**: Optional, for changes taking >1 day - -### Typical Flow -1. Commit directly to main for small changes -2. Create short-lived branch for larger changes (max 2-3 days) -3. Merge to main frequently (multiple times per day) -4. Use feature flags to hide incomplete features -5. Deploy main to production multiple times per day -6. Release by enabling feature flags, not code deployment - -### Advantages -- **Simplest workflow** with minimal branching -- **Fastest integration** with continuous merges -- **Reduced merge conflicts** from short-lived branches -- **Always deployable main** through feature flags -- **Fastest feedback loop** with immediate integration -- **Excellent for CI/CD** and DevOps practices - -### Disadvantages -- **Requires discipline** to keep main stable -- **Needs feature flags** for incomplete features -- **Limited code review** for direct commits -- **Can be destabilizing** without proper testing -- **Requires advanced CI/CD** infrastructure -- **Not suitable for teams** uncomfortable with frequent changes - -### Best For -- Expert teams with strong DevOps culture -- Products requiring very fast iteration -- Microservices architectures -- Teams practicing continuous deployment -- Organizations with mature testing practices - -### Example Commands -```bash -# Small change - direct to main -git checkout main -git pull origin main -# Make changes -git add . -git commit -m "fix(ui): resolve button alignment issue" -git push origin main - -# Larger change - short branch -git checkout main -git pull origin main -git checkout -b payment-integration -# Work for 1-2 days maximum -git add . -git commit -m "feat(payment): add Stripe integration" -git push origin payment-integration - -# Immediate merge -git checkout main -git merge payment-integration -git push origin main -git branch -d payment-integration - -# Feature flag usage -if (featureFlags.enabled('stripe_payments', userId)) { - return renderStripePayment(); -} else { - return renderLegacyPayment(); -} -``` - -## Feature Comparison Matrix - -| Aspect | Git Flow | GitHub Flow | Trunk-based | -|--------|----------|-------------|-------------| -| **Complexity** | High | Medium | Low | -| **Learning Curve** | Steep | Moderate | Gentle | -| **Deployment Frequency** | Weekly/Monthly | Daily | Multiple/day | -| **Branch Lifetime** | Weeks/Months | Days/Weeks | Hours/Days | -| **Main Stability** | Very High | High | High* | -| **Release Coordination** | Excellent | Limited | Feature Flags | -| **Hotfix Support** | Built-in | Manual | Direct | -| **Merge Conflicts** | High | Medium | Low | -| **Team Size** | 10+ | 3-10 | Any | -| **CI/CD Requirements** | Medium | High | Very High | - -*With proper feature flags and testing - -## Release Strategies by Workflow - -### Git Flow Releases -```bash -# Scheduled release every 2 weeks -git checkout develop -git checkout -b release/2.3.0 - -# Version management -echo "2.3.0" > VERSION -npm version 2.3.0 --no-git-tag-version -python setup.py --version 2.3.0 - -# Changelog generation -git log --oneline release/2.2.0..HEAD --pretty=format:"%s" > CHANGELOG_DRAFT.md - -# Testing and bug fixes in release branch -git commit -am "fix: resolve issue found in release testing" - -# Finalize release -git checkout main -git merge --no-ff release/2.3.0 -git tag -a v2.3.0 -m "Release 2.3.0" - -# Deploy tagged version -docker build -t app:2.3.0 . -kubectl set image deployment/app app=app:2.3.0 -``` - -### GitHub Flow Releases -```bash -# Deploy every merge to main -git checkout main -git merge feature/new-payment-method - -# Automatic deployment via CI/CD -# .github/workflows/deploy.yml triggers on push to main - -# Tag releases for tracking (optional) -git tag -a v2.3.$(date +%Y%m%d%H%M) -m "Production deployment" - -# Rollback if needed -git revert HEAD -git push origin main # Triggers automatic rollback deployment -``` - -### Trunk-based Releases -```bash -# Continuous deployment with feature flags -git checkout main -git add feature_flags.json -git commit -m "feat: enable new payment method for 10% of users" -git push origin main - -# Gradual rollout -curl -X POST api/feature-flags/payment-v2/rollout/25 # 25% of users -# Monitor metrics... -curl -X POST api/feature-flags/payment-v2/rollout/50 # 50% of users -# Monitor metrics... -curl -X POST api/feature-flags/payment-v2/rollout/100 # Full rollout - -# Remove flag after successful rollout -git rm old_payment_code.js -git commit -m "cleanup: remove legacy payment code" -``` - -## Choosing the Right Workflow - -### Decision Matrix - -**Choose Git Flow if:** -- ✅ Team size > 10 developers -- ✅ Scheduled release cycles (weekly/monthly) -- ✅ Multiple versions supported simultaneously -- ✅ Formal testing and QA processes -- ✅ Complex enterprise software -- ❌ Need rapid deployment -- ❌ Small team or startup - -**Choose GitHub Flow if:** -- ✅ Team size 3-10 developers -- ✅ Web applications or APIs -- ✅ Strong CI/CD and testing -- ✅ Daily or continuous deployment -- ✅ Simple release requirements -- ❌ Complex release coordination needed -- ❌ Multiple release branches required - -**Choose Trunk-based Development if:** -- ✅ Expert development team -- ✅ Mature DevOps practices -- ✅ Microservices architecture -- ✅ Feature flag infrastructure -- ✅ Multiple deployments per day -- ✅ Strong automated testing -- ❌ Junior developers -- ❌ Complex integration requirements - -### Migration Strategies - -#### From Git Flow to GitHub Flow -1. **Simplify branching**: Eliminate develop branch, work directly with main -2. **Increase deployment frequency**: Move from scheduled to continuous releases -3. **Strengthen testing**: Improve automated test coverage and CI/CD -4. **Reduce branch lifetime**: Limit feature branches to 1-2 weeks maximum -5. **Train team**: Educate on simpler workflow and increased responsibility - -#### From GitHub Flow to Trunk-based -1. **Implement feature flags**: Add feature toggle infrastructure -2. **Improve CI/CD**: Ensure all tests run in <10 minutes -3. **Increase commit frequency**: Encourage multiple commits per day -4. **Reduce branch usage**: Start committing small changes directly to main -5. **Monitor stability**: Ensure main remains deployable at all times - -#### From Trunk-based to Git Flow -1. **Add structure**: Introduce develop and release branches -2. **Reduce deployment frequency**: Move to scheduled release cycles -3. **Extend branch lifetime**: Allow longer feature development cycles -4. **Formalize process**: Add approval gates and testing phases -5. **Coordinate releases**: Plan features for specific release versions - -## Anti-patterns to Avoid - -### Git Flow Anti-patterns -- **Long-lived feature branches** (>2 weeks) -- **Skipping release branches** for small releases -- **Direct commits to main** bypassing develop -- **Forgetting to merge back** to develop after hotfixes -- **Complex merge conflicts** from delayed integration - -### GitHub Flow Anti-patterns -- **Unstable main branch** due to insufficient testing -- **Long-lived feature branches** defeating the purpose -- **Skipping pull request reviews** for speed -- **Direct production deployment** without staging validation -- **No rollback plan** when deployments fail - -### Trunk-based Anti-patterns -- **Committing broken code** to main branch -- **Feature branches lasting weeks** defeating the philosophy -- **No feature flags** for incomplete features -- **Insufficient automated testing** leading to instability -- **Poor CI/CD pipeline** causing deployment delays - -## Conclusion - -The choice of release workflow significantly impacts your team's productivity, code quality, and deployment reliability. Consider your team size, technical maturity, deployment requirements, and organizational culture when making this decision. - -**Start conservative** (Git Flow) and evolve toward more agile approaches (GitHub Flow, Trunk-based) as your team's skills and infrastructure mature. The key is consistency within your team and alignment with your organization's goals and constraints. - -Remember: **The best workflow is the one your team can execute consistently and reliably**. \ No newline at end of file diff --git a/engineering/skills/release-manager/release_planner.py b/engineering/skills/release-manager/release_planner.py deleted file mode 100644 index 93f2f249..00000000 --- a/engineering/skills/release-manager/release_planner.py +++ /dev/null @@ -1,1003 +0,0 @@ -#!/usr/bin/env python3 -""" -Release Planner - -Takes a list of features/PRs/tickets planned for release and assesses release readiness. -Checks for required approvals, test coverage thresholds, breaking change documentation, -dependency updates, migration steps needed. Generates release checklist, communication -plan, and rollback procedures. - -Input: release plan JSON (features, PRs, target date) -Output: release readiness report + checklist + rollback runbook + announcement draft -""" - -import argparse -import json -import sys -from datetime import datetime, timedelta -from typing import Dict, List, Optional, Any, Union -from dataclasses import dataclass, asdict -from enum import Enum - - -class RiskLevel(Enum): - """Risk levels for release components.""" - LOW = "low" - MEDIUM = "medium" - HIGH = "high" - CRITICAL = "critical" - - -class ComponentStatus(Enum): - """Status of release components.""" - PENDING = "pending" - IN_PROGRESS = "in_progress" - READY = "ready" - BLOCKED = "blocked" - FAILED = "failed" - - -@dataclass -class Feature: - """Represents a feature in the release.""" - id: str - title: str - description: str - type: str # feature, bugfix, security, breaking_change, etc. - assignee: str - status: ComponentStatus - pull_request_url: Optional[str] = None - issue_url: Optional[str] = None - risk_level: RiskLevel = RiskLevel.MEDIUM - test_coverage_required: float = 80.0 - test_coverage_actual: Optional[float] = None - requires_migration: bool = False - migration_complexity: str = "simple" # simple, moderate, complex - breaking_changes: List[str] = None - dependencies: List[str] = None - qa_approved: bool = False - security_approved: bool = False - pm_approved: bool = False - - def __post_init__(self): - if self.breaking_changes is None: - self.breaking_changes = [] - if self.dependencies is None: - self.dependencies = [] - - -@dataclass -class QualityGate: - """Quality gate requirements.""" - name: str - required: bool - status: ComponentStatus - details: Optional[str] = None - threshold: Optional[float] = None - actual_value: Optional[float] = None - - -@dataclass -class Stakeholder: - """Stakeholder for release communication.""" - name: str - role: str - contact: str - notification_type: str # email, slack, teams - critical_path: bool = False - - -@dataclass -class RollbackStep: - """Individual rollback step.""" - order: int - description: str - command: Optional[str] = None - estimated_time: str = "5 minutes" - risk_level: RiskLevel = RiskLevel.LOW - verification: str = "" - - -class ReleasePlanner: - """Main release planning and assessment logic.""" - - def __init__(self): - self.release_name: str = "" - self.version: str = "" - self.target_date: Optional[datetime] = None - self.features: List[Feature] = [] - self.quality_gates: List[QualityGate] = [] - self.stakeholders: List[Stakeholder] = [] - self.rollback_steps: List[RollbackStep] = [] - - # Configuration - self.min_test_coverage = 80.0 - self.required_approvals = ['pm_approved', 'qa_approved'] - self.high_risk_approval_requirements = ['pm_approved', 'qa_approved', 'security_approved'] - - def load_release_plan(self, plan_data: Union[str, Dict]): - """Load release plan from JSON.""" - if isinstance(plan_data, str): - data = json.loads(plan_data) - else: - data = plan_data - - self.release_name = data.get('release_name', 'Unnamed Release') - self.version = data.get('version', '1.0.0') - - if 'target_date' in data: - self.target_date = datetime.fromisoformat(data['target_date'].replace('Z', '+00:00')) - - # Load features - self.features = [] - for feature_data in data.get('features', []): - try: - status = ComponentStatus(feature_data.get('status', 'pending')) - risk_level = RiskLevel(feature_data.get('risk_level', 'medium')) - - feature = Feature( - id=feature_data['id'], - title=feature_data['title'], - description=feature_data.get('description', ''), - type=feature_data.get('type', 'feature'), - assignee=feature_data.get('assignee', ''), - status=status, - pull_request_url=feature_data.get('pull_request_url'), - issue_url=feature_data.get('issue_url'), - risk_level=risk_level, - test_coverage_required=feature_data.get('test_coverage_required', 80.0), - test_coverage_actual=feature_data.get('test_coverage_actual'), - requires_migration=feature_data.get('requires_migration', False), - migration_complexity=feature_data.get('migration_complexity', 'simple'), - breaking_changes=feature_data.get('breaking_changes', []), - dependencies=feature_data.get('dependencies', []), - qa_approved=feature_data.get('qa_approved', False), - security_approved=feature_data.get('security_approved', False), - pm_approved=feature_data.get('pm_approved', False) - ) - self.features.append(feature) - except Exception as e: - print(f"Warning: Error parsing feature {feature_data.get('id', 'unknown')}: {e}", - file=sys.stderr) - - # Load quality gates - self.quality_gates = [] - for gate_data in data.get('quality_gates', []): - try: - status = ComponentStatus(gate_data.get('status', 'pending')) - gate = QualityGate( - name=gate_data['name'], - required=gate_data.get('required', True), - status=status, - details=gate_data.get('details'), - threshold=gate_data.get('threshold'), - actual_value=gate_data.get('actual_value') - ) - self.quality_gates.append(gate) - except Exception as e: - print(f"Warning: Error parsing quality gate {gate_data.get('name', 'unknown')}: {e}", - file=sys.stderr) - - # Load stakeholders - self.stakeholders = [] - for stakeholder_data in data.get('stakeholders', []): - stakeholder = Stakeholder( - name=stakeholder_data['name'], - role=stakeholder_data['role'], - contact=stakeholder_data['contact'], - notification_type=stakeholder_data.get('notification_type', 'email'), - critical_path=stakeholder_data.get('critical_path', False) - ) - self.stakeholders.append(stakeholder) - - # Load or generate default quality gates if none provided - if not self.quality_gates: - self._generate_default_quality_gates() - - # Load or generate default rollback steps - if 'rollback_steps' in data: - self.rollback_steps = [] - for step_data in data['rollback_steps']: - risk_level = RiskLevel(step_data.get('risk_level', 'low')) - step = RollbackStep( - order=step_data['order'], - description=step_data['description'], - command=step_data.get('command'), - estimated_time=step_data.get('estimated_time', '5 minutes'), - risk_level=risk_level, - verification=step_data.get('verification', '') - ) - self.rollback_steps.append(step) - else: - self._generate_default_rollback_steps() - - def _generate_default_quality_gates(self): - """Generate default quality gates.""" - default_gates = [ - { - 'name': 'Unit Test Coverage', - 'required': True, - 'threshold': self.min_test_coverage, - 'details': f'Minimum {self.min_test_coverage}% code coverage required' - }, - { - 'name': 'Integration Tests', - 'required': True, - 'details': 'All integration tests must pass' - }, - { - 'name': 'Security Scan', - 'required': True, - 'details': 'No high or critical security vulnerabilities' - }, - { - 'name': 'Performance Testing', - 'required': True, - 'details': 'Performance metrics within acceptable thresholds' - }, - { - 'name': 'Documentation Review', - 'required': True, - 'details': 'API docs and user docs updated for new features' - }, - { - 'name': 'Dependency Audit', - 'required': True, - 'details': 'All dependencies scanned for vulnerabilities' - } - ] - - self.quality_gates = [] - for gate_data in default_gates: - gate = QualityGate( - name=gate_data['name'], - required=gate_data['required'], - status=ComponentStatus.PENDING, - details=gate_data['details'], - threshold=gate_data.get('threshold') - ) - self.quality_gates.append(gate) - - def _generate_default_rollback_steps(self): - """Generate default rollback procedure.""" - default_steps = [ - { - 'order': 1, - 'description': 'Alert on-call team and stakeholders', - 'estimated_time': '2 minutes', - 'verification': 'Confirm team is aware and responding' - }, - { - 'order': 2, - 'description': 'Switch load balancer to previous version', - 'command': 'kubectl patch service app --patch \'{"spec": {"selector": {"version": "previous"}}}\'', - 'estimated_time': '30 seconds', - 'verification': 'Check that traffic is routing to old version' - }, - { - 'order': 3, - 'description': 'Verify application health after rollback', - 'estimated_time': '5 minutes', - 'verification': 'Check error rates, response times, and health endpoints' - }, - { - 'order': 4, - 'description': 'Roll back database migrations if needed', - 'command': 'python manage.py migrate app 0001', - 'estimated_time': '10 minutes', - 'risk_level': 'high', - 'verification': 'Verify data integrity and application functionality' - }, - { - 'order': 5, - 'description': 'Update monitoring dashboards and alerts', - 'estimated_time': '5 minutes', - 'verification': 'Confirm metrics reflect rollback state' - }, - { - 'order': 6, - 'description': 'Notify stakeholders of successful rollback', - 'estimated_time': '5 minutes', - 'verification': 'All stakeholders acknowledge rollback completion' - } - ] - - self.rollback_steps = [] - for step_data in default_steps: - risk_level = RiskLevel(step_data.get('risk_level', 'low')) - step = RollbackStep( - order=step_data['order'], - description=step_data['description'], - command=step_data.get('command'), - estimated_time=step_data.get('estimated_time', '5 minutes'), - risk_level=risk_level, - verification=step_data.get('verification', '') - ) - self.rollback_steps.append(step) - - def assess_release_readiness(self) -> Dict: - """Assess overall release readiness.""" - assessment = { - 'overall_status': 'ready', - 'readiness_score': 0.0, - 'blocking_issues': [], - 'warnings': [], - 'recommendations': [], - 'feature_summary': {}, - 'quality_gate_summary': {}, - 'timeline_assessment': {} - } - - total_score = 0 - max_score = 0 - - # Assess features - feature_stats = { - 'total': len(self.features), - 'ready': 0, - 'blocked': 0, - 'in_progress': 0, - 'pending': 0, - 'high_risk': 0, - 'breaking_changes': 0, - 'missing_approvals': 0, - 'low_test_coverage': 0 - } - - for feature in self.features: - max_score += 10 # Each feature worth 10 points - - if feature.status == ComponentStatus.READY: - feature_stats['ready'] += 1 - total_score += 10 - elif feature.status == ComponentStatus.BLOCKED: - feature_stats['blocked'] += 1 - assessment['blocking_issues'].append( - f"Feature '{feature.title}' ({feature.id}) is blocked" - ) - elif feature.status == ComponentStatus.IN_PROGRESS: - feature_stats['in_progress'] += 1 - total_score += 5 # Partial credit - assessment['warnings'].append( - f"Feature '{feature.title}' ({feature.id}) still in progress" - ) - else: - feature_stats['pending'] += 1 - assessment['warnings'].append( - f"Feature '{feature.title}' ({feature.id}) is pending" - ) - - # Check risk level - if feature.risk_level in [RiskLevel.HIGH, RiskLevel.CRITICAL]: - feature_stats['high_risk'] += 1 - - # Check breaking changes - if feature.breaking_changes: - feature_stats['breaking_changes'] += 1 - - # Check approvals - missing_approvals = self._check_feature_approvals(feature) - if missing_approvals: - feature_stats['missing_approvals'] += 1 - assessment['blocking_issues'].append( - f"Feature '{feature.title}' missing approvals: {', '.join(missing_approvals)}" - ) - - # Check test coverage - if (feature.test_coverage_actual is not None and - feature.test_coverage_actual < feature.test_coverage_required): - feature_stats['low_test_coverage'] += 1 - assessment['warnings'].append( - f"Feature '{feature.title}' has low test coverage: " - f"{feature.test_coverage_actual}% < {feature.test_coverage_required}%" - ) - - assessment['feature_summary'] = feature_stats - - # Assess quality gates - gate_stats = { - 'total': len(self.quality_gates), - 'passed': 0, - 'failed': 0, - 'pending': 0, - 'required_failed': 0 - } - - for gate in self.quality_gates: - max_score += 5 # Each gate worth 5 points - - if gate.status == ComponentStatus.READY: - gate_stats['passed'] += 1 - total_score += 5 - elif gate.status == ComponentStatus.FAILED: - gate_stats['failed'] += 1 - if gate.required: - gate_stats['required_failed'] += 1 - assessment['blocking_issues'].append( - f"Required quality gate '{gate.name}' failed" - ) - else: - gate_stats['pending'] += 1 - if gate.required: - assessment['warnings'].append( - f"Required quality gate '{gate.name}' is pending" - ) - - assessment['quality_gate_summary'] = gate_stats - - # Timeline assessment - if self.target_date: - # Handle timezone-aware datetime comparison - now = datetime.now(self.target_date.tzinfo) if self.target_date.tzinfo else datetime.now() - days_until_release = (self.target_date - now).days - assessment['timeline_assessment'] = { - 'target_date': self.target_date.isoformat(), - 'days_remaining': days_until_release, - 'timeline_status': 'on_track' if days_until_release > 0 else 'overdue' - } - - if days_until_release < 0: - assessment['blocking_issues'].append(f"Release is {abs(days_until_release)} days overdue") - elif days_until_release < 3 and feature_stats['blocked'] > 0: - assessment['blocking_issues'].append("Not enough time to resolve blocked features") - - # Calculate overall readiness score - if max_score > 0: - assessment['readiness_score'] = (total_score / max_score) * 100 - - # Determine overall status - if assessment['blocking_issues']: - assessment['overall_status'] = 'blocked' - elif assessment['warnings']: - assessment['overall_status'] = 'at_risk' - else: - assessment['overall_status'] = 'ready' - - # Generate recommendations - if feature_stats['missing_approvals'] > 0: - assessment['recommendations'].append("Obtain required approvals for pending features") - - if feature_stats['low_test_coverage'] > 0: - assessment['recommendations'].append("Improve test coverage for features below threshold") - - if gate_stats['pending'] > 0: - assessment['recommendations'].append("Complete pending quality gate validations") - - if feature_stats['high_risk'] > 0: - assessment['recommendations'].append("Review high-risk features for additional validation") - - return assessment - - def _check_feature_approvals(self, feature: Feature) -> List[str]: - """Check which approvals are missing for a feature.""" - missing = [] - - # Determine required approvals based on risk level - required = self.required_approvals.copy() - if feature.risk_level in [RiskLevel.HIGH, RiskLevel.CRITICAL]: - required = self.high_risk_approval_requirements.copy() - - if 'pm_approved' in required and not feature.pm_approved: - missing.append('PM approval') - - if 'qa_approved' in required and not feature.qa_approved: - missing.append('QA approval') - - if 'security_approved' in required and not feature.security_approved: - missing.append('Security approval') - - return missing - - def generate_release_checklist(self) -> List[Dict]: - """Generate comprehensive release checklist.""" - checklist = [] - - # Pre-release validation - checklist.extend([ - { - 'category': 'Pre-Release Validation', - 'item': 'All features implemented and tested', - 'status': 'ready' if all(f.status == ComponentStatus.READY for f in self.features) else 'pending', - 'details': f"{len([f for f in self.features if f.status == ComponentStatus.READY])}/{len(self.features)} features ready" - }, - { - 'category': 'Pre-Release Validation', - 'item': 'Breaking changes documented', - 'status': 'ready' if self._check_breaking_change_docs() else 'pending', - 'details': f"{len([f for f in self.features if f.breaking_changes])} features have breaking changes" - }, - { - 'category': 'Pre-Release Validation', - 'item': 'Migration scripts tested', - 'status': 'ready' if self._check_migrations() else 'pending', - 'details': f"{len([f for f in self.features if f.requires_migration])} features require migrations" - } - ]) - - # Quality gates - for gate in self.quality_gates: - checklist.append({ - 'category': 'Quality Gates', - 'item': gate.name, - 'status': gate.status.value, - 'details': gate.details, - 'required': gate.required - }) - - # Approvals - approval_items = [ - ('Product Manager sign-off', self._check_pm_approvals()), - ('QA validation complete', self._check_qa_approvals()), - ('Security team clearance', self._check_security_approvals()) - ] - - for item, status in approval_items: - checklist.append({ - 'category': 'Approvals', - 'item': item, - 'status': 'ready' if status else 'pending' - }) - - # Documentation - doc_items = [ - 'CHANGELOG.md updated', - 'API documentation updated', - 'User documentation updated', - 'Migration guide written', - 'Rollback procedure documented' - ] - - for item in doc_items: - checklist.append({ - 'category': 'Documentation', - 'item': item, - 'status': 'pending' # Would need integration with docs system to check - }) - - # Deployment preparation - deployment_items = [ - 'Database migrations prepared', - 'Environment variables configured', - 'Monitoring alerts updated', - 'Rollback plan tested', - 'Stakeholders notified' - ] - - for item in deployment_items: - checklist.append({ - 'category': 'Deployment', - 'item': item, - 'status': 'pending' - }) - - return checklist - - def _check_breaking_change_docs(self) -> bool: - """Check if breaking changes are properly documented.""" - features_with_breaking_changes = [f for f in self.features if f.breaking_changes] - return all(len(f.breaking_changes) > 0 for f in features_with_breaking_changes) - - def _check_migrations(self) -> bool: - """Check migration readiness.""" - features_with_migrations = [f for f in self.features if f.requires_migration] - return all(f.status == ComponentStatus.READY for f in features_with_migrations) - - def _check_pm_approvals(self) -> bool: - """Check PM approvals.""" - return all(f.pm_approved for f in self.features if f.risk_level != RiskLevel.LOW) - - def _check_qa_approvals(self) -> bool: - """Check QA approvals.""" - return all(f.qa_approved for f in self.features) - - def _check_security_approvals(self) -> bool: - """Check security approvals.""" - high_risk_features = [f for f in self.features if f.risk_level in [RiskLevel.HIGH, RiskLevel.CRITICAL]] - return all(f.security_approved for f in high_risk_features) - - def generate_communication_plan(self) -> Dict: - """Generate stakeholder communication plan.""" - plan = { - 'internal_notifications': [], - 'external_notifications': [], - 'timeline': [], - 'channels': {}, - 'templates': {} - } - - # Group stakeholders by type - internal_stakeholders = [s for s in self.stakeholders if s.role in - ['developer', 'qa', 'pm', 'devops', 'security']] - external_stakeholders = [s for s in self.stakeholders if s.role in - ['customer', 'partner', 'support']] - - # Internal notifications - for stakeholder in internal_stakeholders: - plan['internal_notifications'].append({ - 'recipient': stakeholder.name, - 'role': stakeholder.role, - 'method': stakeholder.notification_type, - 'content_type': 'technical_details', - 'timing': 'T-24h and T-0' - }) - - # External notifications - for stakeholder in external_stakeholders: - plan['external_notifications'].append({ - 'recipient': stakeholder.name, - 'role': stakeholder.role, - 'method': stakeholder.notification_type, - 'content_type': 'user_facing_changes', - 'timing': 'T-48h and T+1h' - }) - - # Communication timeline - if self.target_date: - timeline_items = [ - (timedelta(days=-2), 'Send pre-release notification to external stakeholders'), - (timedelta(days=-1), 'Send deployment notification to internal teams'), - (timedelta(hours=-2), 'Final go/no-go decision'), - (timedelta(hours=0), 'Begin deployment'), - (timedelta(hours=1), 'Post-deployment status update'), - (timedelta(hours=24), 'Post-release summary') - ] - - for delta, description in timeline_items: - notification_time = self.target_date + delta - plan['timeline'].append({ - 'time': notification_time.isoformat(), - 'description': description, - 'recipients': 'all' if 'all' in description.lower() else 'internal' - }) - - # Communication channels - channels = {} - for stakeholder in self.stakeholders: - if stakeholder.notification_type not in channels: - channels[stakeholder.notification_type] = [] - channels[stakeholder.notification_type].append(stakeholder.contact) - plan['channels'] = channels - - # Message templates - plan['templates'] = self._generate_message_templates() - - return plan - - def _generate_message_templates(self) -> Dict: - """Generate message templates for different audiences.""" - breaking_changes = [f for f in self.features if f.breaking_changes] - new_features = [f for f in self.features if f.type == 'feature'] - bug_fixes = [f for f in self.features if f.type == 'bugfix'] - - templates = { - 'internal_pre_release': { - 'subject': f'Release {self.version} - Pre-deployment Notification', - 'body': f"""Team, - -We are preparing to deploy {self.release_name} version {self.version} on {self.target_date.strftime('%Y-%m-%d %H:%M UTC') if self.target_date else 'TBD'}. - -Key Changes: -- {len(new_features)} new features -- {len(bug_fixes)} bug fixes -- {len(breaking_changes)} breaking changes - -Please review the release notes and prepare for any needed support activities. - -Rollback plan: Available in release documentation -On-call: Please be available during deployment window - -Best regards, -Release Team""" - }, - 'external_user_notification': { - 'subject': f'Product Update - Version {self.version} Now Available', - 'body': f"""Dear Users, - -We're excited to announce version {self.version} of {self.release_name} is now available! - -What's New: -{chr(10).join(f"- {f.title}" for f in new_features[:5])} - -Bug Fixes: -{chr(10).join(f"- {f.title}" for f in bug_fixes[:3])} - -{'Important: This release includes breaking changes. Please review the migration guide.' if breaking_changes else ''} - -For full release notes and migration instructions, visit our documentation. - -Thank you for using our product! - -The Development Team""" - }, - 'rollback_notification': { - 'subject': f'URGENT: Release {self.version} Rollback Initiated', - 'body': f"""ATTENTION: Release rollback in progress. - -Release: {self.version} -Reason: [TO BE FILLED] -Rollback initiated: {datetime.now().strftime('%Y-%m-%d %H:%M UTC')} -Estimated completion: [TO BE FILLED] - -Current status: Rolling back to previous stable version -Impact: [TO BE FILLED] - -We will provide updates every 15 minutes until rollback is complete. - -Incident Commander: [TO BE FILLED] -Status page: [TO BE FILLED]""" - } - } - - return templates - - def generate_rollback_runbook(self) -> Dict: - """Generate detailed rollback runbook.""" - runbook = { - 'overview': { - 'purpose': f'Emergency rollback procedure for {self.release_name} v{self.version}', - 'triggers': [ - 'Error rate spike (>2x baseline for >15 minutes)', - 'Critical functionality failure', - 'Security incident', - 'Data corruption detected', - 'Performance degradation (>50% latency increase)', - 'Manual decision by incident commander' - ], - 'decision_makers': ['On-call Engineer', 'Engineering Lead', 'Incident Commander'], - 'estimated_total_time': self._calculate_rollback_time() - }, - 'prerequisites': [ - 'Confirm rollback is necessary (check with incident commander)', - 'Notify stakeholders of rollback decision', - 'Ensure database backups are available', - 'Verify monitoring systems are operational', - 'Have communication channels ready' - ], - 'steps': [], - 'verification': { - 'health_checks': [ - 'Application responds to health endpoint', - 'Database connectivity confirmed', - 'Authentication system functional', - 'Core user workflows working', - 'Error rates back to baseline', - 'Performance metrics within normal range' - ], - 'rollback_confirmation': [ - 'Previous version fully deployed', - 'Database in consistent state', - 'All services communicating properly', - 'Monitoring shows stable metrics', - 'Sample user workflows tested' - ] - }, - 'post_rollback': [ - 'Update status page with resolution', - 'Notify all stakeholders of successful rollback', - 'Schedule post-incident review', - 'Document issues encountered during rollback', - 'Plan investigation of root cause', - 'Determine timeline for next release attempt' - ], - 'emergency_contacts': [] - } - - # Convert rollback steps to detailed format - for step in sorted(self.rollback_steps, key=lambda x: x.order): - step_data = { - 'order': step.order, - 'title': step.description, - 'estimated_time': step.estimated_time, - 'risk_level': step.risk_level.value, - 'instructions': step.description, - 'command': step.command, - 'verification': step.verification, - 'rollback_possible': step.risk_level != RiskLevel.CRITICAL - } - runbook['steps'].append(step_data) - - # Add emergency contacts - critical_stakeholders = [s for s in self.stakeholders if s.critical_path] - for stakeholder in critical_stakeholders: - runbook['emergency_contacts'].append({ - 'name': stakeholder.name, - 'role': stakeholder.role, - 'contact': stakeholder.contact, - 'method': stakeholder.notification_type - }) - - return runbook - - def _calculate_rollback_time(self) -> str: - """Calculate estimated total rollback time.""" - total_minutes = 0 - for step in self.rollback_steps: - # Parse time estimates like "5 minutes", "30 seconds", "1 hour" - time_str = step.estimated_time.lower() - if 'minute' in time_str: - minutes = int(re.search(r'(\d+)', time_str).group(1)) - total_minutes += minutes - elif 'hour' in time_str: - hours = int(re.search(r'(\d+)', time_str).group(1)) - total_minutes += hours * 60 - elif 'second' in time_str: - # Round up seconds to minutes - total_minutes += 1 - - if total_minutes < 60: - return f"{total_minutes} minutes" - else: - hours = total_minutes // 60 - minutes = total_minutes % 60 - return f"{hours}h {minutes}m" - - -def main(): - """Main CLI entry point.""" - parser = argparse.ArgumentParser(description="Assess release readiness and generate release plans") - parser.add_argument('--input', '-i', required=True, - help='Release plan JSON file') - parser.add_argument('--output-format', '-f', - choices=['json', 'markdown', 'text'], - default='text', help='Output format') - parser.add_argument('--output', '-o', type=str, - help='Output file (default: stdout)') - parser.add_argument('--include-checklist', action='store_true', - help='Include release checklist in output') - parser.add_argument('--include-communication', action='store_true', - help='Include communication plan') - parser.add_argument('--include-rollback', action='store_true', - help='Include rollback runbook') - parser.add_argument('--min-coverage', type=float, default=80.0, - help='Minimum test coverage threshold') - - args = parser.parse_args() - - # Load release plan - try: - with open(args.input, 'r', encoding='utf-8') as f: - plan_data = f.read() - except Exception as e: - print(f"Error reading input file: {e}", file=sys.stderr) - sys.exit(1) - - # Initialize planner - planner = ReleasePlanner() - planner.min_test_coverage = args.min_coverage - - try: - planner.load_release_plan(plan_data) - except Exception as e: - print(f"Error loading release plan: {e}", file=sys.stderr) - sys.exit(1) - - # Generate assessment - assessment = planner.assess_release_readiness() - - # Generate optional components - checklist = planner.generate_release_checklist() if args.include_checklist else None - communication = planner.generate_communication_plan() if args.include_communication else None - rollback = planner.generate_rollback_runbook() if args.include_rollback else None - - # Generate output - if args.output_format == 'json': - output_data = { - 'assessment': assessment, - 'checklist': checklist, - 'communication_plan': communication, - 'rollback_runbook': rollback - } - output_text = json.dumps(output_data, indent=2, default=str) - - elif args.output_format == 'markdown': - output_lines = [ - f"# Release Readiness Report - {planner.release_name} v{planner.version}", - "", - f"**Overall Status:** {assessment['overall_status'].upper()}", - f"**Readiness Score:** {assessment['readiness_score']:.1f}%", - "" - ] - - if assessment['blocking_issues']: - output_lines.extend([ - "## 🚫 Blocking Issues", - "" - ]) - for issue in assessment['blocking_issues']: - output_lines.append(f"- {issue}") - output_lines.append("") - - if assessment['warnings']: - output_lines.extend([ - "## ⚠️ Warnings", - "" - ]) - for warning in assessment['warnings']: - output_lines.append(f"- {warning}") - output_lines.append("") - - # Feature summary - fs = assessment['feature_summary'] - output_lines.extend([ - "## Features Summary", - "", - f"- **Total:** {fs['total']}", - f"- **Ready:** {fs['ready']}", - f"- **In Progress:** {fs['in_progress']}", - f"- **Blocked:** {fs['blocked']}", - f"- **Breaking Changes:** {fs['breaking_changes']}", - "" - ]) - - if checklist: - output_lines.extend([ - "## Release Checklist", - "" - ]) - current_category = "" - for item in checklist: - if item['category'] != current_category: - current_category = item['category'] - output_lines.append(f"### {current_category}") - output_lines.append("") - - status_icon = "✅" if item['status'] == 'ready' else "❌" if item['status'] == 'failed' else "⏳" - output_lines.append(f"- {status_icon} {item['item']}") - output_lines.append("") - - output_text = '\n'.join(output_lines) - - else: # text format - output_lines = [ - f"Release Readiness Report", - f"========================", - f"Release: {planner.release_name} v{planner.version}", - f"Status: {assessment['overall_status'].upper()}", - f"Readiness Score: {assessment['readiness_score']:.1f}%", - "" - ] - - if assessment['blocking_issues']: - output_lines.extend(["BLOCKING ISSUES:", ""]) - for issue in assessment['blocking_issues']: - output_lines.append(f" ❌ {issue}") - output_lines.append("") - - if assessment['warnings']: - output_lines.extend(["WARNINGS:", ""]) - for warning in assessment['warnings']: - output_lines.append(f" ⚠️ {warning}") - output_lines.append("") - - if assessment['recommendations']: - output_lines.extend(["RECOMMENDATIONS:", ""]) - for rec in assessment['recommendations']: - output_lines.append(f" 💡 {rec}") - output_lines.append("") - - # Summary stats - fs = assessment['feature_summary'] - gs = assessment['quality_gate_summary'] - - output_lines.extend([ - f"FEATURE SUMMARY:", - f" Total: {fs['total']} | Ready: {fs['ready']} | Blocked: {fs['blocked']}", - f" Breaking Changes: {fs['breaking_changes']} | Missing Approvals: {fs['missing_approvals']}", - "", - f"QUALITY GATES:", - f" Total: {gs['total']} | Passed: {gs['passed']} | Failed: {gs['failed']}", - "" - ]) - - output_text = '\n'.join(output_lines) - - # Write output - if args.output: - with open(args.output, 'w', encoding='utf-8') as f: - f.write(output_text) - else: - print(output_text) - - -if __name__ == '__main__': - main() \ No newline at end of file diff --git a/engineering/skills/secrets-vault-manager/scripts/audit_log_analyzer.py b/engineering/skills/secrets-vault-manager/scripts/audit_log_analyzer.py index b31e4e66..34b8068e 100644 --- a/engineering/skills/secrets-vault-manager/scripts/audit_log_analyzer.py +++ b/engineering/skills/secrets-vault-manager/scripts/audit_log_analyzer.py @@ -278,6 +278,32 @@ def print_human(result, threshold): print(" (* = off-hours)") +# Embedded synthetic audit log — exercises volume-spike + off-hours + failed-access +# detectors so --sample produces a non-trivial report without a real log file. +SAMPLE_ENTRIES = [ + {"timestamp": "2026-03-20T03:14:00Z", "type": "request", + "auth": {"display_name": "approle-payment-svc"}, + "request": {"path": "secret/data/production/payment/api-keys", "operation": "read"}, + "response": {"status_code": 200}, "remote_address": "10.0.1.15"}, + {"timestamp": "2026-03-20T03:15:00Z", "type": "request", + "auth": {"display_name": "approle-payment-svc"}, + "request": {"path": "secret/data/production/payment/db", "operation": "read"}, + "response": {"status_code": 200}, "remote_address": "10.0.1.99"}, + {"timestamp": "2026-03-20T03:16:00Z", "type": "request", + "auth": {"display_name": "approle-payment-svc"}, + "request": {"path": "secret/data/production/payment/jwt", "operation": "read"}, + "response": {"status_code": 403}, "remote_address": "203.0.113.7"}, + {"timestamp": "2026-03-20T03:17:00Z", "type": "request", + "auth": {"display_name": "approle-payment-svc"}, + "request": {"path": "secret/data/production/payment/jwt", "operation": "read"}, + "response": {"status_code": 403}, "remote_address": "203.0.113.7"}, + {"timestamp": "2026-03-20T14:00:00Z", "type": "request", + "auth": {"display_name": "ci-runner"}, + "request": {"path": "secret/data/ci/tokens", "operation": "read"}, + "response": {"status_code": 200}, "remote_address": "10.0.2.20"}, +] + + def main(): parser = argparse.ArgumentParser( description="Analyze Vault/cloud secret manager audit logs for anomalies.", @@ -299,7 +325,7 @@ def main(): %(prog)s --log-file audit.json --threshold 3 --json """), ) - parser.add_argument("--log-file", required=True, help="Path to audit log file (JSON lines or JSON array)") + parser.add_argument("--log-file", help="Path to audit log file (JSON lines or JSON array)") parser.add_argument( "--threshold", type=int, @@ -307,23 +333,35 @@ def main(): help="Anomaly sensitivity threshold — lower = more sensitive (default: 5)", ) parser.add_argument("--json", action="store_true", dest="json_output", help="Output as JSON") + parser.add_argument("--sample", action="store_true", + help="Analyze an embedded synthetic audit log") args = parser.parse_args() - entries = load_logs(args.log_file) + if args.sample: + entries = SAMPLE_ENTRIES + log_file = "<embedded sample>" + threshold = 2 + else: + if not args.log_file: + parser.error("--log-file is required (or use --sample)") + entries = load_logs(args.log_file) + log_file = args.log_file + threshold = args.threshold + if not entries: print("No log entries found in file.", file=sys.stderr) sys.exit(1) - result = analyze(entries, args.threshold) - result["log_file"] = args.log_file - result["threshold"] = args.threshold + result = analyze(entries, threshold) + result["log_file"] = log_file + result["threshold"] = threshold result["analyzed_at"] = datetime.now().isoformat() if args.json_output: print(json.dumps(result, indent=2)) else: - print_human(result, args.threshold) + print_human(result, threshold) if __name__ == "__main__": diff --git a/engineering/skills/skill-security-auditor/SKILL.md b/engineering/skills/skill-security-auditor/SKILL.md index 38bda3e1..d7c72d9e 100644 --- a/engineering/skills/skill-security-auditor/SKILL.md +++ b/engineering/skills/skill-security-auditor/SKILL.md @@ -143,7 +143,7 @@ python3 scripts/skill_security_auditor.py https://github.com/user/skill-repo --s # GitHub Actions step - name: "audit-skill-security" run: | - python3 skill-security-auditor/scripts/skill_security_auditor.py ./skills/new-skill/ --strict --json > audit.json + python3 scripts/skill_security_auditor.py ./skills/new-skill/ --strict --json > audit.json if [ $? -ne 0 ]; then echo "Security audit failed"; exit 1; fi ``` diff --git a/engineering/skills/skill-tester/SKILL.md b/engineering/skills/skill-tester/SKILL.md index 7e5d56d7..84b24708 100644 --- a/engineering/skills/skill-tester/SKILL.md +++ b/engineering/skills/skill-tester/SKILL.md @@ -5,386 +5,88 @@ description: "Validate, test, and score the quality of skills within the claude- # Skill Tester ---- +**Tier**: POWERFUL · **Category**: Engineering Quality Assurance · **Dependencies**: None (Python stdlib only) -**Name**: skill-tester -**Tier**: POWERFUL -**Category**: Engineering Quality Assurance -**Dependencies**: None (Python Standard Library Only) -**Author**: Claude Skills Engineering Team -**Version**: 1.0.0 -**Last Updated**: 2026-02-16 +Meta-skill that validates, tests, and scores skills in this repository. Four tools, run from the **repo root** with full paths: ---- +1. **`scripts/skill_validator.py`** — structure + documentation compliance +2. **`scripts/script_tester.py`** — Python script syntax/imports/runtime/output testing +3. **`scripts/quality_scorer.py`** — multi-dimensional scoring with letter grade +4. **`scripts/security_scorer.py`** — security posture scoring (also available via `quality_scorer.py --include-security`) -## Description +> **Scope note:** this skill's tier line-count minimums measure *legacy* skills. For authoring *new* skills, `engineering/write-a-skill` (SKILL.md under ~100 lines, Matt Pocock doctrine) is the binding standard — do not pad a new skill to satisfy a tier minimum here. -The Skill Tester is a comprehensive meta-skill designed to validate, test, and score the quality of skills within the claude-skills ecosystem. This powerful quality assurance tool ensures that all skills meet the rigorous standards required for BASIC, STANDARD, and POWERFUL tier classifications through automated validation, testing, and scoring mechanisms. +## Quick Start (exact, runnable from repo root) -As the gatekeeping system for skill quality, this meta-skill provides three core capabilities: -1. **Structure Validation** - Ensures skills conform to required directory structures, file formats, and documentation standards -2. **Script Testing** - Validates Python scripts for syntax, imports, functionality, and output format compliance -3. **Quality Scoring** - Provides comprehensive quality assessment across multiple dimensions with letter grades and improvement recommendations - -This skill is essential for maintaining ecosystem consistency, enabling automated CI/CD integration, and supporting both manual and automated quality assurance workflows. It serves as the foundation for pre-commit hooks, pull request validation, and continuous integration processes that maintain the high-quality standards of the claude-skills repository. - -## Core Features - -### Comprehensive Skill Validation -- **Structure Compliance**: Validates directory structure, required files (SKILL.md, README.md, scripts/, references/, assets/, expected_outputs/) -- **Documentation Standards**: Checks SKILL.md frontmatter, section completeness, minimum line counts per tier -- **File Format Validation**: Ensures proper Markdown formatting, YAML frontmatter syntax, and file naming conventions - -### Advanced Script Testing -- **Syntax Validation**: Compiles Python scripts to detect syntax errors before execution -- **Import Analysis**: Enforces standard library only policy, identifies external dependencies -- **Runtime Testing**: Executes scripts with sample data, validates argparse implementation, tests --help functionality -- **Output Format Compliance**: Verifies dual output support (JSON + human-readable), proper error handling - -### Multi-Dimensional Quality Scoring -- **Documentation Quality (25%)**: SKILL.md depth and completeness, README clarity, reference documentation quality -- **Code Quality (25%)**: Script complexity, error handling robustness, output format consistency, maintainability -- **Completeness (25%)**: Required directory presence, sample data adequacy, expected output verification -- **Usability (25%)**: Example clarity, argparse help text quality, installation simplicity, user experience - -### Tier Classification System -Automatically classifies skills based on complexity and functionality: - -#### BASIC Tier Requirements -- Minimum 100 lines in SKILL.md -- At least 1 Python script (100-300 LOC) -- Basic argparse implementation -- Simple input/output handling -- Essential documentation coverage - -#### STANDARD Tier Requirements -- Minimum 200 lines in SKILL.md -- 1-2 Python scripts (300-500 LOC each) -- Advanced argparse with subcommands -- JSON + text output formats -- Comprehensive examples and references -- Error handling and edge case management - -#### POWERFUL Tier Requirements -- Minimum 300 lines in SKILL.md -- 2-3 Python scripts (500-800 LOC each) -- Complex argparse with multiple modes -- Sophisticated output formatting and validation -- Extensive documentation and reference materials -- Advanced error handling and recovery mechanisms -- CI/CD integration capabilities - -## Architecture & Design - -### Modular Design Philosophy -The skill-tester follows a modular architecture where each component serves a specific validation purpose: - -- **skill_validator.py**: Core structural and documentation validation engine -- **script_tester.py**: Runtime testing and execution validation framework -- **quality_scorer.py**: Multi-dimensional quality assessment and scoring system - -### Standards Enforcement -All validation is performed against well-defined standards documented in the references/ directory: -- **Skill Structure Specification**: Defines mandatory and optional components -- **Tier Requirements Matrix**: Detailed requirements for each skill tier -- **Quality Scoring Rubric**: Comprehensive scoring methodology and weightings - -### Integration Capabilities -Designed for seamless integration into existing development workflows: -- **Pre-commit Hooks**: Prevents substandard skills from being committed -- **CI/CD Pipelines**: Automated quality gates in pull request workflows -- **Manual Validation**: Interactive command-line tools for development-time validation -- **Batch Processing**: Bulk validation and scoring of existing skill repositories - -## Implementation Details - -### skill_validator.py Core Functions -```python -# Primary validation workflow -validate_skill_structure() -> ValidationReport -check_skill_md_compliance() -> DocumentationReport -validate_python_scripts() -> ScriptReport -generate_compliance_score() -> float -``` - -Key validation checks include: -- SKILL.md frontmatter parsing and validation -- Required section presence (Description, Features, Usage, etc.) -- Minimum line count enforcement per tier -- Python script argparse implementation verification -- Standard library import enforcement -- Directory structure compliance -- README.md quality assessment - -### script_tester.py Testing Framework -```python -# Core testing functions -syntax_validation() -> SyntaxReport -import_validation() -> ImportReport -runtime_testing() -> RuntimeReport -output_format_validation() -> OutputReport -``` - -Testing capabilities encompass: -- Python AST-based syntax validation -- Import statement analysis and external dependency detection -- Controlled script execution with timeout protection -- Argparse --help functionality verification -- Sample data processing and output validation -- Expected output comparison and difference reporting - -### quality_scorer.py Scoring System -```python -# Multi-dimensional scoring -score_documentation() -> float # 25% weight -score_code_quality() -> float # 25% weight -score_completeness() -> float # 25% weight -score_usability() -> float # 25% weight -calculate_overall_grade() -> str # A-F grade -``` - -Scoring dimensions include: -- **Documentation**: Completeness, clarity, examples, reference quality -- **Code Quality**: Complexity, maintainability, error handling, output consistency -- **Completeness**: Required files, sample data, expected outputs, test coverage -- **Usability**: Help text quality, example clarity, installation simplicity - -## Usage Scenarios - -### Development Workflow Integration ```bash -# Pre-commit hook validation -skill_validator.py path/to/skill --tier POWERFUL --json +# 1. Validate structure (exit non-zero on failure — usable as a gate) +python3 engineering/skills/skill-tester/scripts/skill_validator.py engineering/skills/self-eval --json -# Comprehensive skill testing -script_tester.py path/to/skill --timeout 30 --sample-data +# 2. Test the skill's Python scripts (30s default timeout per script) +python3 engineering/skills/skill-tester/scripts/script_tester.py engineering/skills/self-eval --json -# Quality assessment and scoring -quality_scorer.py path/to/skill --detailed --recommendations +# 3. Score quality (fail CI below threshold with --minimum-score) +python3 engineering/skills/skill-tester/scripts/quality_scorer.py engineering/skills/self-eval --json --detailed --minimum-score 75 ``` -### CI/CD Pipeline Integration +Consume the JSON: validator emits `overall_score`, `compliance_level`, per-check `checks{}`; scorer emits `overall_score`, `letter_grade`, `tier_recommendation`, `dimensions`, and an `improvement_roadmap` — work the roadmap top-down, then re-run until the target score is met. + +For repo-wide auditing prefer `scripts/audit_skills.py` at the repo root (wraps the write-a-skill checklist runner across all skills). + +## What Each Tool Checks + +### skill_validator.py +- SKILL.md frontmatter parsing, required sections, minimum line counts per tier (`--tier BASIC|STANDARD|POWERFUL`) +- Required structure: SKILL.md, README.md, scripts/, references/, assets/, expected_outputs/ +- Python scripts: argparse present, stdlib-only imports + +### script_tester.py +- AST-based syntax validation; import analysis (flags external dependencies) +- Controlled execution with timeout protection (`--timeout`, default 30s) +- `--help` functionality verification; sample-data runs compared against expected_outputs/ + +### quality_scorer.py +Four dimensions, 25% each: **Documentation** (depth, examples, references), **Code Quality** (complexity, error handling, output consistency), **Completeness** (required dirs, sample data, expected outputs), **Usability** (help text, example clarity). Outputs 0-100 + A-F grade + tier recommendation. + +## Tier Classification + +| Tier | SKILL.md | Scripts | CLI surface | +|---|---|---|---| +| BASIC | ≥ 100 lines | 1 (100-300 LOC) | basic argparse | +| STANDARD | ≥ 200 lines | 1-2 (300-500 LOC) | subcommands, JSON + text output | +| POWERFUL | ≥ 300 lines | 2-3 (500-800 LOC) | multiple modes, CI integration | + +(Advisory for legacy skills; new skills follow write-a-skill — see scope note above.) + +## CI Integration + ```yaml -# GitHub Actions workflow example -- name: "validate-skill-quality" +# GitHub Actions: gate changed skills +- name: "validate-changed-skills" run: | - python skill_validator.py engineering/${{ matrix.skill }} --json | tee validation.json - python script_tester.py engineering/${{ matrix.skill }} | tee testing.json - python quality_scorer.py engineering/${{ matrix.skill }} --json | tee scoring.json + for skill in $changed_skills; do + python3 engineering/skills/skill-tester/scripts/skill_validator.py "$skill" --json + python3 engineering/skills/skill-tester/scripts/script_tester.py "$skill" + python3 engineering/skills/skill-tester/scripts/quality_scorer.py "$skill" --minimum-score 75 + done ``` -### Batch Repository Analysis -```bash -# Validate all skills in repository -find engineering/ -type d -maxdepth 1 | xargs -I {} skill_validator.py {} +Pre-commit hook: run the validator on the staged skill directory and block the commit on non-zero exit. -# Generate repository quality report -quality_scorer.py engineering/ --batch --output-format json > repo_quality.json -``` +## Verification Loop -## Output Formats & Reporting +A skill "passes" when, in one run from repo root: -### Dual Output Support -All tools provide both human-readable and machine-parseable output: +1. `skill_validator.py <skill> --json` exits 0, +2. `script_tester.py <skill>` reports all scripts passing, and +3. `quality_scorer.py <skill> --minimum-score <target>` exits 0. -#### Human-Readable Format -``` -=== SKILL VALIDATION REPORT === -Skill: engineering/example-skill -Tier: STANDARD -Overall Score: 85/100 (B) +If any step fails, apply the top `improvement_roadmap` item and re-run all three — never report a partial pass. -Structure Validation: ✓ PASS -├─ SKILL.md: ✓ EXISTS (247 lines) -├─ README.md: ✓ EXISTS -├─ scripts/: ✓ EXISTS (2 files) -└─ references/: ⚠ MISSING (recommended) +## Troubleshooting -Documentation Quality: 22/25 (88%) -Code Quality: 20/25 (80%) -Completeness: 18/25 (72%) -Usability: 21/25 (84%) +- **Timeout errors** → raise `--timeout` or optimize the script under test +- **Import failures** → external deps detected; stdlib-only is the repo policy +- **Tier misclassification** → check line counts/LOC against the tier table; remember the write-a-skill exception for new skills -Recommendations: -• Add references/ directory with documentation -• Improve error handling in main.py -• Include more comprehensive examples -``` - -#### JSON Format -```json -{ - "skill_path": "engineering/example-skill", - "timestamp": "2026-02-16T16:41:00Z", - "validation_results": { - "structure_compliance": { - "score": 0.95, - "checks": { - "skill_md_exists": true, - "readme_exists": true, - "scripts_directory": true, - "references_directory": false - } - }, - "overall_score": 85, - "letter_grade": "B", - "tier_recommendation": "STANDARD", - "improvement_suggestions": [ - "Add references/ directory", - "Improve error handling", - "Include comprehensive examples" - ] - } -} -``` - -## Quality Assurance Standards - -### Code Quality Requirements -- **Standard Library Only**: No external dependencies (pip packages) -- **Error Handling**: Comprehensive exception handling with meaningful error messages -- **Output Consistency**: Standardized JSON schema and human-readable formatting -- **Performance**: Efficient validation algorithms with reasonable execution time -- **Maintainability**: Clear code structure, comprehensive docstrings, type hints where appropriate - -### Testing Standards -- **Self-Testing**: The skill-tester validates itself (meta-validation) -- **Sample Data Coverage**: Comprehensive test cases covering edge cases and error conditions -- **Expected Output Verification**: All sample runs produce verifiable, reproducible outputs -- **Timeout Protection**: Safe execution of potentially problematic scripts with timeout limits - -### Documentation Standards -- **Comprehensive Coverage**: All functions, classes, and modules documented -- **Usage Examples**: Clear, practical examples for all use cases -- **Integration Guides**: Step-by-step CI/CD and workflow integration instructions -- **Reference Materials**: Complete specification documents for standards and requirements - -## Integration Examples - -### Pre-Commit Hook Setup -```bash -#!/bin/bash -# .git/hooks/pre-commit -echo "Running skill validation..." -python engineering/skill-tester/scripts/skill_validator.py engineering/new-skill --tier STANDARD -if [ $? -ne 0 ]; then - echo "Skill validation failed. Commit blocked." - exit 1 -fi -echo "Validation passed. Proceeding with commit." -``` - -### GitHub Actions Workflow -```yaml -name: "skill-quality-gate" -on: - pull_request: - paths: ['engineering/**'] - -jobs: - validate-skills: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v3 - - name: "setup-python" - uses: actions/setup-python@v4 - with: - python-version: '3.11' - - name: "validate-changed-skills" - run: | - changed_skills=$(git diff --name-only ${{ github.event.before }} | grep -E '^engineering/[^/]+/' | cut -d'/' -f1-2 | sort -u) - for skill in $changed_skills; do - echo "Validating $skill..." - python engineering/skill-tester/scripts/skill_validator.py $skill --json - python engineering/skill-tester/scripts/script_tester.py $skill - python engineering/skill-tester/scripts/quality_scorer.py $skill --minimum-score 75 - done -``` - -### Continuous Quality Monitoring -```bash -#!/bin/bash -# Daily quality report generation -echo "Generating daily skill quality report..." -timestamp=$(date +"%Y-%m-%d") -python engineering/skill-tester/scripts/quality_scorer.py engineering/ \ - --batch --json > "reports/quality_report_${timestamp}.json" - -echo "Quality trends analysis..." -python engineering/skill-tester/scripts/trend_analyzer.py reports/ \ - --days 30 > "reports/quality_trends_${timestamp}.md" -``` - -## Performance & Scalability - -### Execution Performance -- **Fast Validation**: Structure validation completes in <1 second per skill -- **Efficient Testing**: Script testing with timeout protection (configurable, default 30s) -- **Batch Processing**: Optimized for repository-wide analysis with parallel processing support -- **Memory Efficiency**: Minimal memory footprint for large-scale repository analysis - -### Scalability Considerations -- **Repository Size**: Designed to handle repositories with 100+ skills -- **Concurrent Execution**: Thread-safe implementation supports parallel validation -- **Resource Management**: Automatic cleanup of temporary files and subprocess resources -- **Configuration Flexibility**: Configurable timeouts, memory limits, and validation strictness - -## Security & Safety - -### Safe Execution Environment -- **Sandboxed Testing**: Scripts execute in controlled environment with timeout protection -- **Resource Limits**: Memory and CPU usage monitoring to prevent resource exhaustion -- **Input Validation**: All inputs sanitized and validated before processing -- **No Network Access**: Offline operation ensures no external dependencies or network calls - -### Security Best Practices -- **No Code Injection**: Static analysis only, no dynamic code generation -- **Path Traversal Protection**: Secure file system access with path validation -- **Minimal Privileges**: Operates with minimal required file system permissions -- **Audit Logging**: Comprehensive logging for security monitoring and troubleshooting - -## Troubleshooting & Support - -### Common Issues & Solutions - -#### Validation Failures -- **Missing Files**: Check directory structure against tier requirements -- **Import Errors**: Ensure only standard library imports are used -- **Documentation Issues**: Verify SKILL.md frontmatter and section completeness - -#### Script Testing Problems -- **Timeout Errors**: Increase timeout limit or optimize script performance -- **Execution Failures**: Check script syntax and import statement validity -- **Output Format Issues**: Ensure proper JSON formatting and dual output support - -#### Quality Scoring Discrepancies -- **Low Scores**: Review scoring rubric and improvement recommendations -- **Tier Misclassification**: Verify skill complexity against tier requirements -- **Inconsistent Results**: Check for recent changes in quality standards or scoring weights - -### Debugging Support -- **Verbose Mode**: Detailed logging and execution tracing available -- **Dry Run Mode**: Validation without execution for debugging purposes -- **Debug Output**: Comprehensive error reporting with file locations and suggestions - -## Future Enhancements - -### Planned Features -- **Machine Learning Quality Prediction**: AI-powered quality assessment using historical data -- **Performance Benchmarking**: Execution time and resource usage tracking across skills -- **Dependency Analysis**: Automated detection and validation of skill interdependencies -- **Quality Trend Analysis**: Historical quality tracking and regression detection - -### Integration Roadmap -- **IDE Plugins**: Real-time validation in popular development environments -- **Web Dashboard**: Centralized quality monitoring and reporting interface -- **API Endpoints**: RESTful API for external integration and automation -- **Notification Systems**: Automated alerts for quality degradation or validation failures - -## Conclusion - -The Skill Tester represents a critical infrastructure component for maintaining the high-quality standards of the claude-skills ecosystem. By providing comprehensive validation, testing, and scoring capabilities, it ensures that all skills meet or exceed the rigorous requirements for their respective tiers. - -This meta-skill not only serves as a quality gate but also as a development tool that guides skill authors toward best practices and helps maintain consistency across the entire repository. Through its integration capabilities and comprehensive reporting, it enables both manual and automated quality assurance workflows that scale with the growing claude-skills ecosystem. - -The combination of structural validation, runtime testing, and multi-dimensional quality scoring provides unparalleled visibility into skill quality while maintaining the flexibility needed for diverse skill types and complexity levels. As the claude-skills repository continues to grow, the Skill Tester will remain the cornerstone of quality assurance and ecosystem integrity. \ No newline at end of file +References: `references/` holds the structure specification, tier requirements matrix, and scoring rubric the tools implement. diff --git a/engineering/skills/slo-architect/SKILL.md b/engineering/skills/slo-architect/SKILL.md index 056b5f0d..e1758733 100644 --- a/engineering/skills/slo-architect/SKILL.md +++ b/engineering/skills/slo-architect/SKILL.md @@ -155,7 +155,7 @@ This skill explicitly composes with three others: | `chaos-engineering` | Blast-radius calculator already takes monthly error budget as input — define it here | | `kubernetes-operator` | Operator capability L4 (Deep Insights) requires SLOs + Prometheus rules | -The `error_budget_calculator.py` output is in the same shape `chaos-engineering/scripts/blast_radius_calculator.py` expects on stdin. +The `error_budget_calculator.py` output is in the same shape `engineering/skills/chaos-engineering/scripts/blast_radius_calculator.py` expects on stdin. ## Workflows diff --git a/engineering/skills/slo-architect/scripts/error_budget_calculator.py b/engineering/skills/slo-architect/scripts/error_budget_calculator.py index 1fd9db0c..55ddedcc 100755 --- a/engineering/skills/slo-architect/scripts/error_budget_calculator.py +++ b/engineering/skills/slo-architect/scripts/error_budget_calculator.py @@ -125,13 +125,21 @@ def render_text(result): def main(): ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter) - ap.add_argument("--target", type=float, required=True, help="Target percent (e.g., 99.9)") + ap.add_argument("--target", type=float, help="Target percent (e.g., 99.9)") ap.add_argument("--window-days", type=int, default=28, help="Window in days (default: 28)") ap.add_argument("--format", choices=["text", "json"], default="text") + ap.add_argument("--sample", action="store_true", help="Run with embedded sample inputs (99.9%% / 28d)") args = ap.parse_args() + if args.sample: + target, window_days = 99.9, 28 + elif args.target is not None: + target, window_days = args.target, args.window_days + else: + ap.error("--target is required (or use --sample)") + try: - result = compute(args.target, args.window_days) + result = compute(target, window_days) except ValueError as e: print(f"ERROR: {e}", file=sys.stderr) return 2 diff --git a/engineering/skills/slo-architect/scripts/slo_review.py b/engineering/skills/slo-architect/scripts/slo_review.py index 83a19532..afb70fa6 100755 --- a/engineering/skills/slo-architect/scripts/slo_review.py +++ b/engineering/skills/slo-architect/scripts/slo_review.py @@ -64,8 +64,16 @@ def _has_cpu_as_sli(text): return False -def audit_one(path): - text = _read(path) +# Embedded sample SLO doc — intentionally flawed (target too high, CPU-as-SLI, +# no error budget policy) so --sample exercises several finding paths. +SAMPLE_SLO_DOC = """# Checkout API SLO +target: 99.995% +window_days: 28 +sli: cpu_usage below 80% +""" + + +def audit_text(text): findings = [] target = _parse_target(text) window_days = _parse_window_days(text) @@ -103,6 +111,10 @@ def audit_one(path): return findings +def audit_one(path): + return audit_text(_read(path)) + + def _walk(target): if os.path.isfile(target): yield target @@ -140,15 +152,20 @@ def render_text(results): def main(): ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter) - ap.add_argument("--slo-doc", required=True, help="Path to SLO doc or directory of docs") + ap.add_argument("--slo-doc", help="Path to SLO doc or directory of docs") ap.add_argument("--format", choices=["text", "json"], default="text") + ap.add_argument("--sample", action="store_true", help="Audit an embedded sample SLO doc") args = ap.parse_args() - if not os.path.exists(args.slo_doc): - print(f"ERROR: not found: {args.slo_doc}", file=sys.stderr) - return 2 - - results = audit(args.slo_doc) + if args.sample: + results = [{"path": "<embedded sample>", "findings": audit_text(SAMPLE_SLO_DOC)}] + else: + if not args.slo_doc: + ap.error("--slo-doc is required (or use --sample)") + if not os.path.exists(args.slo_doc): + print(f"ERROR: not found: {args.slo_doc}", file=sys.stderr) + return 2 + results = audit(args.slo_doc) if args.format == "json": print(json.dumps(results, indent=2)) return 1 if any(f[0] == "FAIL" for r in results for f in r["findings"]) else 0 diff --git a/engineering/skills/tech-debt-tracker/SKILL.md b/engineering/skills/tech-debt-tracker/SKILL.md index 2253031d..19c86bbc 100644 --- a/engineering/skills/tech-debt-tracker/SKILL.md +++ b/engineering/skills/tech-debt-tracker/SKILL.md @@ -25,48 +25,42 @@ This skill offers three interconnected tools that form a complete tech debt mana Together, these tools enable engineering teams to make data-driven decisions about tech debt, balancing new feature development with maintenance work. +## Quick Start — scan → prioritize → dashboard + +All paths relative to this skill folder. The scanner's JSON output feeds the prioritizer directly; dated inventory snapshots feed the dashboard. + +### 1. Scan the codebase + +```bash +python3 scripts/debt_scanner.py /path/to/codebase --format json --output debt_inventory.json +``` + +Emits `debt_inventory.json` with `scan_metadata`, `summary`, `debt_items[]`, `file_statistics`, and `recommendations`. Report the `summary` counts to the user. (Dry run: `assets/sample_codebase`.) + +### 2. Prioritize the backlog + +```bash +python3 scripts/debt_prioritizer.py debt_inventory.json --framework wsjf --team-size 6 --sprint-capacity 20 --format json --output debt_priorities.json +``` + +Frameworks: `cost_of_delay` (default), `wsjf`, `rice`. Output contains `prioritized_backlog` (work top-down), `sprint_allocation` (paste into sprint planning), and `insights`. + +### 3. Track trends over time + +Keep dated snapshots (`debt_YYYY-MM-DD.json`), then: + +```bash +python3 scripts/debt_dashboard.py --input-dir snapshots/ --period monthly --format both --output debt_dashboard +``` + +Or pass files explicitly (samples: `assets/historical_debt_2024-01-15.json assets/historical_debt_2024-02-01.json`). The dashboard reports trend direction and executive-ready summaries — use it to verify a cleanup sprint actually reduced debt. + +### Verification loop + +After a remediation sprint: re-run step 1, re-run step 3 with the new snapshot, and assert the targeted categories' counts dropped. A cleanup that doesn't move the dashboard is rework, not debt paydown. + ## Technical Debt Classification Framework -→ See references/debt-frameworks.md for details - -## Implementation Roadmap - -### Phase 1: Foundation (Weeks 1-2) -1. Set up debt scanning infrastructure -2. Establish debt taxonomy and scoring criteria -3. Scan initial codebase and create baseline inventory -4. Train team on debt identification and reporting - -### Phase 2: Process Integration (Weeks 3-4) -1. Integrate debt tracking into sprint planning -2. Establish debt budgets and allocation rules -3. Create stakeholder reporting templates -4. Set up automated debt scanning in CI/CD - -### Phase 3: Optimization (Weeks 5-6) -1. Refine scoring algorithms based on team feedback -2. Implement trend analysis and predictive metrics -3. Create specialized debt reduction initiatives -4. Establish cross-team debt coordination processes - -### Phase 4: Maturity (Ongoing) -1. Continuous improvement of detection algorithms -2. Advanced analytics and prediction models -3. Integration with planning and project management tools -4. Organization-wide debt management best practices - -## Success Criteria - -**Quantitative Metrics:** -- 25% reduction in debt interest rate within 6 months -- 15% improvement in development velocity -- 30% reduction in production defects -- 20% faster code review cycles - -**Qualitative Metrics:** -- Improved developer satisfaction scores -- Reduced context switching during feature development -- Faster onboarding for new team members -- Better predictability in feature delivery timelines +→ See references/debt-frameworks.md for details (also: references/debt-classification-taxonomy.md, references/prioritization-framework.md, references/stakeholder-communication-templates.md) ## Common Pitfalls and How to Avoid Them diff --git a/engineering/slo-architect/skills/slo-architect/SKILL.md b/engineering/slo-architect/skills/slo-architect/SKILL.md index 056b5f0d..e1758733 100644 --- a/engineering/slo-architect/skills/slo-architect/SKILL.md +++ b/engineering/slo-architect/skills/slo-architect/SKILL.md @@ -155,7 +155,7 @@ This skill explicitly composes with three others: | `chaos-engineering` | Blast-radius calculator already takes monthly error budget as input — define it here | | `kubernetes-operator` | Operator capability L4 (Deep Insights) requires SLOs + Prometheus rules | -The `error_budget_calculator.py` output is in the same shape `chaos-engineering/scripts/blast_radius_calculator.py` expects on stdin. +The `error_budget_calculator.py` output is in the same shape `engineering/skills/chaos-engineering/scripts/blast_radius_calculator.py` expects on stdin. ## Workflows diff --git a/engineering/slo-architect/skills/slo-architect/scripts/error_budget_calculator.py b/engineering/slo-architect/skills/slo-architect/scripts/error_budget_calculator.py index 1fd9db0c..55ddedcc 100755 --- a/engineering/slo-architect/skills/slo-architect/scripts/error_budget_calculator.py +++ b/engineering/slo-architect/skills/slo-architect/scripts/error_budget_calculator.py @@ -125,13 +125,21 @@ def render_text(result): def main(): ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter) - ap.add_argument("--target", type=float, required=True, help="Target percent (e.g., 99.9)") + ap.add_argument("--target", type=float, help="Target percent (e.g., 99.9)") ap.add_argument("--window-days", type=int, default=28, help="Window in days (default: 28)") ap.add_argument("--format", choices=["text", "json"], default="text") + ap.add_argument("--sample", action="store_true", help="Run with embedded sample inputs (99.9%% / 28d)") args = ap.parse_args() + if args.sample: + target, window_days = 99.9, 28 + elif args.target is not None: + target, window_days = args.target, args.window_days + else: + ap.error("--target is required (or use --sample)") + try: - result = compute(args.target, args.window_days) + result = compute(target, window_days) except ValueError as e: print(f"ERROR: {e}", file=sys.stderr) return 2 diff --git a/engineering/slo-architect/skills/slo-architect/scripts/slo_review.py b/engineering/slo-architect/skills/slo-architect/scripts/slo_review.py index 83a19532..afb70fa6 100755 --- a/engineering/slo-architect/skills/slo-architect/scripts/slo_review.py +++ b/engineering/slo-architect/skills/slo-architect/scripts/slo_review.py @@ -64,8 +64,16 @@ def _has_cpu_as_sli(text): return False -def audit_one(path): - text = _read(path) +# Embedded sample SLO doc — intentionally flawed (target too high, CPU-as-SLI, +# no error budget policy) so --sample exercises several finding paths. +SAMPLE_SLO_DOC = """# Checkout API SLO +target: 99.995% +window_days: 28 +sli: cpu_usage below 80% +""" + + +def audit_text(text): findings = [] target = _parse_target(text) window_days = _parse_window_days(text) @@ -103,6 +111,10 @@ def audit_one(path): return findings +def audit_one(path): + return audit_text(_read(path)) + + def _walk(target): if os.path.isfile(target): yield target @@ -140,15 +152,20 @@ def render_text(results): def main(): ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter) - ap.add_argument("--slo-doc", required=True, help="Path to SLO doc or directory of docs") + ap.add_argument("--slo-doc", help="Path to SLO doc or directory of docs") ap.add_argument("--format", choices=["text", "json"], default="text") + ap.add_argument("--sample", action="store_true", help="Audit an embedded sample SLO doc") args = ap.parse_args() - if not os.path.exists(args.slo_doc): - print(f"ERROR: not found: {args.slo_doc}", file=sys.stderr) - return 2 - - results = audit(args.slo_doc) + if args.sample: + results = [{"path": "<embedded sample>", "findings": audit_text(SAMPLE_SLO_DOC)}] + else: + if not args.slo_doc: + ap.error("--slo-doc is required (or use --sample)") + if not os.path.exists(args.slo_doc): + print(f"ERROR: not found: {args.slo_doc}", file=sys.stderr) + return 2 + results = audit(args.slo_doc) if args.format == "json": print(json.dumps(results, indent=2)) return 1 if any(f[0] == "FAIL" for r in results for f in r["findings"]) else 0 diff --git a/engineering/universal-scraping-architect/.claude-plugin/plugin.json b/engineering/universal-scraping-architect/.claude-plugin/plugin.json index a6005509..e84d4bb2 100644 --- a/engineering/universal-scraping-architect/.claude-plugin/plugin.json +++ b/engineering/universal-scraping-architect/.claude-plugin/plugin.json @@ -9,7 +9,9 @@ "homepage": "https://github.com/alirezarezvani/claude-skills/tree/main/engineering/universal-scraping-architect", "repository": "https://github.com/alirezarezvani/claude-skills", "license": "MIT", - "skills": ["./"], + "skills": [ + "./skills" + ], "attribution": { "author": "Mehansh Barthwal", "source": "https://github.com/mehanshbarthwal-lab", diff --git a/engineering/universal-scraping-architect/agents/cs-scraping-architect.md b/engineering/universal-scraping-architect/agents/cs-scraping-architect.md index 5a5de5f1..911dd045 100644 --- a/engineering/universal-scraping-architect/agents/cs-scraping-architect.md +++ b/engineering/universal-scraping-architect/agents/cs-scraping-architect.md @@ -1,6 +1,43 @@ --- name: cs-scraping-architect -description: Expert persona for web scraping and data pipeline design. +description: Use when the user wants to scrape a website, crawl docs, extract data from PDFs/Excel/CSV/HTML, parse an API response into a dataset, or debug a brittle scraping script. Designs validated extraction pipelines (Firecrawl, local Python, or hybrid) — never one-off scripts that ship unvalidated data. +tools: Read, Write, Edit, Bash, Grep, Glob +model: sonnet --- + # cs-scraping-architect -Use this agent when you need to design a complex extraction strategy or debug scraping scripts. + +Data-extraction pipeline architect. Operates the `skills/universal-scraping-architect/SKILL.md` skill: route the approach, extract with checkpointing, validate before delivering. The defining behavior is the **validation gate** — no scraped output is handed to the user until `validate_extraction.py` exits 0. + +## Workflow + +1. **Load the skill.** Read `skills/universal-scraping-architect/SKILL.md` (and `project-context.md` if present) before asking the user anything. Determine target data format, scale, and deployment environment. +2. **Route the mode and say why** (never silently pick one): + - **Mode 1 — Firecrawl (API):** public URL, JS-heavy/SPA, search-first discovery, or bulk domain crawling. BYOK: key only via `os.getenv('FIRECRAWL_API_KEY')`. + - **Mode 2 — Local Python:** local files (PDF/Excel/CSV), private or sensitive data, or simple static HTML where an API is overkill. + - **Mode 3 — Hybrid:** Firecrawl for discovery/extraction, pandas locally for cleaning and normalization. +3. **Budget before bulk.** Estimate Firecrawl API quota or LLM token limits before any multi-page job; add checkpointing and pagination handling for anything beyond a single page. +4. **Start from the runner templates** (run from the plugin root; each `--sample` works offline): + ```bash + python3 skills/universal-scraping-architect/scripts/firecrawl_example.py --sample # Mode 1 (deps: firecrawl, requests) + python3 skills/universal-scraping-architect/scripts/local_bs4_example.py --sample # Mode 2 (deps: beautifulsoup4, pandas) + ``` + Edit a copy of the template for the actual job; never inline a from-scratch scraper when a template covers the mode. +5. **Validate — mandatory gate:** + ```bash + python3 skills/universal-scraping-architect/scripts/validate_extraction.py extracted_output.json --json + ``` + Exit 0 = `{"status": "ok"}` → proceed. Exit 1 → fix and re-extract; never deliver (parse the JSON `status` field for the `warning` = empty-output vs `error` = malformed-JSON distinction, since both share exit 1). Then check required fields and duplicates against the pipeline spec. +6. **Format and deliver:** CSV for tabular data, JSON for nested structures, Markdown (chunked for token limits) for crawled docs. Report row counts and empty-value summary. + +## Refusal & Flag Gates + +- **Hardcoded API keys** → stop and rewrite to `os.getenv('FIRECRAWL_API_KEY')` before anything else runs. +- **Private/sensitive local data bound for an external API** → flag the privacy risk and switch to Mode 2. +- **No robots.txt check / no rate limiting** on a live target → add both before scraping; refuse to scrape sites that disallow it. +- **Brittle selectors** (deep `nth-child` chains) → replace with data attributes or structural anchors. +- **Hundreds of records implied but no pagination/checkpointing** → add it proactively. + +## Output + +A routed, validated pipeline: the runner script (edited template), the validated dataset, and a one-paragraph summary stating the mode chosen and why, budget assumptions, and the validation result. diff --git a/engineering/universal-scraping-architect/commands/cs-scrape.md b/engineering/universal-scraping-architect/commands/cs-scrape.md index 5b411978..6863952e 100644 --- a/engineering/universal-scraping-architect/commands/cs-scrape.md +++ b/engineering/universal-scraping-architect/commands/cs-scrape.md @@ -1,6 +1,36 @@ --- name: cs-scrape -description: Execute a scraping task for a specific URL. +description: Route, extract, and validate a scraping job (URL or local file) via the universal-scraping-architect skill — refuses to deliver unvalidated data. +argument-hint: "<url-or-file-path> [desired output: csv|json|markdown]" --- -# /cs-scrape [url] -Triggers the scraping architect to analyze and extract data from the target URL. + +# /cs-scrape + +Run a gated extraction pipeline for `$ARGUMENTS` using `skills/universal-scraping-architect/SKILL.md`. + +## Pre-flight gates (stop if any fails) + +1. **Target stated?** If `$ARGUMENTS` is empty, ask for the URL or file path plus the desired output format — do not guess. +2. **Live-site etiquette:** for URLs, check `robots.txt` and plan rate limits; refuse disallowed targets. +3. **Privacy:** if the target is a local/sensitive file, do not send it to an external API — force Mode 2 (local Python). +4. **Secrets:** Firecrawl key only via `os.getenv('FIRECRAWL_API_KEY')`; if a key appears inline anywhere, fix that first. + +## Workflow + +1. **Route** — state the mode and why (per the skill's routing rules): + Mode 1 Firecrawl (public/JS-heavy URL, bulk crawl) · Mode 2 local Python (local files, private data, simple static HTML) · Mode 3 hybrid (Firecrawl extract + pandas clean). +2. **Budget** — estimate API quota / token limits before multi-page jobs; add checkpointing + pagination. +3. **Extract** — start from the matching runner template (run from the plugin root; `--sample` previews the summary shape offline): + ```bash + python3 skills/universal-scraping-architect/scripts/firecrawl_example.py --sample + python3 skills/universal-scraping-architect/scripts/local_bs4_example.py --sample + ``` +4. **Validate (mandatory, exit-code gated):** + ```bash + python3 skills/universal-scraping-architect/scripts/validate_extraction.py extracted_output.json --json + ``` + - exit 0 (`status: ok`) → continue + - exit 1 (`warning` = empty output, `error` = malformed JSON) → fix and re-extract; **never deliver unvalidated data** + + Then check required fields and duplicates against the job spec. +5. **Deliver** — CSV (tabular) / JSON (nested) / Markdown (docs, chunked), per the user's requested format, with a summary of mode chosen, row counts, empty values, and the validation verdict. diff --git a/engineering/universal-scraping-architect/SKILL.md b/engineering/universal-scraping-architect/skills/universal-scraping-architect/SKILL.md similarity index 68% rename from engineering/universal-scraping-architect/SKILL.md rename to engineering/universal-scraping-architect/skills/universal-scraping-architect/SKILL.md index 7af8a00b..35294d59 100644 --- a/engineering/universal-scraping-architect/SKILL.md +++ b/engineering/universal-scraping-architect/skills/universal-scraping-architect/SKILL.md @@ -5,9 +5,15 @@ description: "Use for web scraping, crawling, document extraction, API parsing, # Universal Scraping Architect -You are an expert web scraping and data extraction engineer. Your goal is to design complete, robust data pipelines with intelligent routing, validation, and token budget tracking—not brittle one-off scripts. +Design complete, robust data-extraction pipelines with intelligent routing, validation, and token-budget tracking — not brittle one-off scripts. -**Dependency Notice:** This skill utilizes `firecrawl`, `pandas`, `requests`, and `beautifulsoup4`. It uses a BYOK (Bring Your Own Key) pattern for Firecrawl. API keys must only be loaded via environment variables. +**Dependency Notice:** BYOK (Bring Your Own Key) pattern for Firecrawl; API keys must only be loaded via environment variables. Per-script dependencies: + +| Script | Dependencies | Exact CLI | +|---|---|---| +| `scripts/validate_extraction.py` | stdlib only | `python3 scripts/validate_extraction.py output.json --json` | +| `scripts/firecrawl_example.py` | `firecrawl`, `requests` (template; `--sample` runs offline) | `python3 scripts/firecrawl_example.py --sample` | +| `scripts/local_bs4_example.py` | `beautifulsoup4`, `pandas` (template; `--sample` runs offline) | `python3 scripts/local_bs4_example.py --sample` | ## Before Starting **Check for context first:** @@ -29,8 +35,8 @@ Use when Firecrawl handles URL discovery/web extraction, but local Python (Panda When executing a scraping task, always follow this sequence: 1. **Route the Approach:** Explicitly state whether Firecrawl or Local Python is being used and why. 2. **Track Budgets:** Estimate Firecrawl API quotas or LLM token context limits before executing large jobs. -3. **Extract Safely:** Implement checkpointing for multi-page jobs. Handle pagination and dynamic layouts gracefully. -4. **Validate & Clean:** Enforce required fields, catch empty outputs, flag duplicates, and normalize field names. +3. **Extract Safely:** Implement checkpointing for multi-page jobs. Handle pagination and dynamic layouts gracefully. Start from the editable runner templates — `scripts/firecrawl_example.py` (Mode 1) or `scripts/local_bs4_example.py` (Mode 2); run each with `--sample` first to see the expected summary shape without network access. +4. **Validate & Clean:** Run `python3 scripts/validate_extraction.py extracted_output.json --json` on every extraction result before delivering it. It exits 0 only on `{"status": "ok"}`; `warning` (empty output) or `error` (malformed JSON) exit 1 — fix and re-extract, never ship unvalidated data. Beyond this structural gate, also check required fields and duplicates against the pipeline spec before delivering. 5. **Format:** Default to CSV for tabular data, JSON for nested structures, and Markdown for clean text. ## Proactive Triggers diff --git a/engineering/universal-scraping-architect/references/firecrawl-technical-guide.md b/engineering/universal-scraping-architect/skills/universal-scraping-architect/references/firecrawl-technical-guide.md similarity index 100% rename from engineering/universal-scraping-architect/references/firecrawl-technical-guide.md rename to engineering/universal-scraping-architect/skills/universal-scraping-architect/references/firecrawl-technical-guide.md diff --git a/engineering/universal-scraping-architect/references/local-extraction-patterns.md b/engineering/universal-scraping-architect/skills/universal-scraping-architect/references/local-extraction-patterns.md similarity index 100% rename from engineering/universal-scraping-architect/references/local-extraction-patterns.md rename to engineering/universal-scraping-architect/skills/universal-scraping-architect/references/local-extraction-patterns.md diff --git a/engineering/universal-scraping-architect/references/scraping-ethics-security.md b/engineering/universal-scraping-architect/skills/universal-scraping-architect/references/scraping-ethics-security.md similarity index 100% rename from engineering/universal-scraping-architect/references/scraping-ethics-security.md rename to engineering/universal-scraping-architect/skills/universal-scraping-architect/references/scraping-ethics-security.md diff --git a/engineering/universal-scraping-architect/requirements.txt b/engineering/universal-scraping-architect/skills/universal-scraping-architect/requirements.txt similarity index 100% rename from engineering/universal-scraping-architect/requirements.txt rename to engineering/universal-scraping-architect/skills/universal-scraping-architect/requirements.txt diff --git a/engineering/universal-scraping-architect/scripts/firecrawl_example.py b/engineering/universal-scraping-architect/skills/universal-scraping-architect/scripts/firecrawl_example.py similarity index 100% rename from engineering/universal-scraping-architect/scripts/firecrawl_example.py rename to engineering/universal-scraping-architect/skills/universal-scraping-architect/scripts/firecrawl_example.py diff --git a/engineering/universal-scraping-architect/scripts/local_bs4_example.py b/engineering/universal-scraping-architect/skills/universal-scraping-architect/scripts/local_bs4_example.py similarity index 100% rename from engineering/universal-scraping-architect/scripts/local_bs4_example.py rename to engineering/universal-scraping-architect/skills/universal-scraping-architect/scripts/local_bs4_example.py diff --git a/engineering/universal-scraping-architect/scripts/validate_extraction.py b/engineering/universal-scraping-architect/skills/universal-scraping-architect/scripts/validate_extraction.py similarity index 100% rename from engineering/universal-scraping-architect/scripts/validate_extraction.py rename to engineering/universal-scraping-architect/skills/universal-scraping-architect/scripts/validate_extraction.py diff --git a/finance/.claude-plugin/plugin.json b/finance/.claude-plugin/plugin.json index 3b3f853a..88343be5 100644 --- a/finance/.claude-plugin/plugin.json +++ b/finance/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "finance-skills", - "description": "3 finance skills: financial analyst (ratio analysis, DCF valuation, budgeting, forecasting), SaaS metrics coach (ARR, MRR, churn, CAC, LTV, NRR, Quick Ratio, 12-month projections), and business investment advisor. 7 Python automation tools. Agent skill and plugin for Claude Code, Codex, Gemini CLI, Cursor, OpenClaw.", + "description": "2 finance skills plus a router: financial analyst (ratio analysis, DCF valuation, budgeting, forecasting) and SaaS metrics coach (ARR, MRR, churn, CAC, LTV, NRR, Quick Ratio, 12-month projections). 7 Python automation tools. The business-investment-advisor skill ships as a separate nested plugin. Agent skill and plugin for Claude Code, Codex, Gemini CLI, Cursor, OpenClaw.", "version": "2.9.0", "author": { "name": "Alireza Rezvani", @@ -12,4 +12,4 @@ "skills": [ "./skills" ] -} +} \ No newline at end of file diff --git a/finance/skills/finance-skills/SKILL.md b/finance/skills/finance-skills/SKILL.md index 61bfc00f..95a3bdee 100644 --- a/finance/skills/finance-skills/SKILL.md +++ b/finance/skills/finance-skills/SKILL.md @@ -1,6 +1,6 @@ --- name: "finance-skills" -description: "Financial analyst agent skill and plugin for Claude Code, Codex, Gemini CLI, Cursor, OpenClaw. Ratio analysis, DCF valuation, budget variance, rolling forecasts. 4 Python tools (stdlib-only)." +description: "Router/index for the 2 finance skills bundled in this plugin: financial-analyst (ratio analysis, DCF valuation, budget variance, rolling forecasts) and saas-metrics-coach (ARR/MRR, churn, CAC/LTV, NRR, quick ratio). Use when a finance request doesn't obviously match one skill and you need to pick the right one (e.g., 'analyze these financials', 'how healthy are my SaaS metrics')." version: 2.9.0 author: Alireza Rezvani license: MIT @@ -16,40 +16,36 @@ agents: - openclaw --- -# Finance Skills +# Finance Skills — Router -Production-ready financial analysis skill for strategic decision-making. +This plugin bundles **2 finance skills** (this router is the 3rd folder under `finance/skills/`). Each skill is self-contained. -## Quick Start +## Routing table -### Claude Code -``` -/read finance/financial-analyst/SKILL.md -``` +| Request signals | Skill | Path | +|---|---|---| +| Ratio analysis, DCF valuation, budget variance, driver-based forecasts | financial-analyst | `skills/financial-analyst/` | +| ARR/MRR, churn, CAC/LTV, NRR, quick ratio, SaaS benchmarks | saas-metrics-coach | `skills/saas-metrics-coach/` | -### Codex CLI -```bash -npx agent-skills-cli add alirezarezvani/claude-skills/finance -``` +If both match (e.g., "value my SaaS company"), ask whether the user wants statement-level analysis (financial-analyst) or SaaS operating metrics (saas-metrics-coach). -## Skills Overview - -| Skill | Folder | Focus | -|-------|--------|-------| -| Financial Analyst | `financial-analyst/` | Ratio analysis, DCF, budget variance, forecasting | - -## Python Tools - -4 scripts, all stdlib-only: +## Quick start ```bash -python3 financial-analyst/scripts/ratio_calculator.py --help -python3 financial-analyst/scripts/dcf_valuation.py --help -python3 financial-analyst/scripts/budget_variance_analyzer.py --help -python3 financial-analyst/scripts/forecast_builder.py --help +# Example: route a statement-analysis request +cat finance/skills/financial-analyst/SKILL.md +python3 finance/skills/financial-analyst/scripts/ratio_calculator.py --help + +# Or a SaaS metrics request +python3 finance/skills/saas-metrics-coach/scripts/metrics_calculator.py --help ``` +## Related (packaged separately, not in this bundle) + +- `finance/business-investment-advisor/` — investment thesis evaluation, ROI modeling (prompt-only skill, separate nested plugin) +- Root commands `/financial-health` and `/saas-health` wrap these skills' scripts. + ## Rules -- Load only the specific skill SKILL.md you need -- Always validate financial outputs against source data +- Route to exactly one skill, then follow that skill's workflow. This router ships no tools of its own. +- Always validate financial outputs against the user's source data; outputs are analysis support, not investment advice. diff --git a/finance/skills/financial-analyst/SKILL.md b/finance/skills/financial-analyst/SKILL.md index c0502d65..ca279fff 100644 --- a/finance/skills/financial-analyst/SKILL.md +++ b/finance/skills/financial-analyst/SKILL.md @@ -57,9 +57,9 @@ Calculate and interpret financial ratios from financial statement data. - **Valuation:** P/E, P/B, P/S, EV/EBITDA, PEG Ratio ```bash -python scripts/ratio_calculator.py sample_financial_data.json -python scripts/ratio_calculator.py sample_financial_data.json --format json -python scripts/ratio_calculator.py sample_financial_data.json --category profitability +python scripts/ratio_calculator.py assets/sample_financial_data.json +python scripts/ratio_calculator.py assets/sample_financial_data.json --format json +python scripts/ratio_calculator.py assets/sample_financial_data.json --category profitability ``` ### 2. DCF Valuation (`scripts/dcf_valuation.py`) @@ -74,9 +74,9 @@ Discounted Cash Flow enterprise and equity valuation with sensitivity analysis. - Two-way sensitivity analysis (discount rate vs growth rate) ```bash -python scripts/dcf_valuation.py valuation_data.json -python scripts/dcf_valuation.py valuation_data.json --format json -python scripts/dcf_valuation.py valuation_data.json --projection-years 7 +python scripts/dcf_valuation.py assets/sample_financial_data.json +python scripts/dcf_valuation.py assets/sample_financial_data.json --format json +python scripts/dcf_valuation.py assets/sample_financial_data.json --projection-years 7 ``` ### 3. Budget Variance Analyzer (`scripts/budget_variance_analyzer.py`) @@ -91,9 +91,9 @@ Analyze actual vs budget vs prior year performance with materiality filtering. - Executive summary generation ```bash -python scripts/budget_variance_analyzer.py budget_data.json -python scripts/budget_variance_analyzer.py budget_data.json --format json -python scripts/budget_variance_analyzer.py budget_data.json --threshold-pct 5 --threshold-amt 25000 +python scripts/budget_variance_analyzer.py assets/sample_financial_data.json +python scripts/budget_variance_analyzer.py assets/sample_financial_data.json --format json +python scripts/budget_variance_analyzer.py assets/sample_financial_data.json --threshold-pct 5 --threshold-amt 25000 ``` ### 4. Forecast Builder (`scripts/forecast_builder.py`) @@ -107,9 +107,9 @@ Driver-based revenue forecasting with rolling cash flow projection and scenario - Trend analysis using simple linear regression (standard library) ```bash -python scripts/forecast_builder.py forecast_data.json -python scripts/forecast_builder.py forecast_data.json --format json -python scripts/forecast_builder.py forecast_data.json --scenarios base,bull,bear +python scripts/forecast_builder.py assets/sample_financial_data.json +python scripts/forecast_builder.py assets/sample_financial_data.json --format json +python scripts/forecast_builder.py assets/sample_financial_data.json --scenarios base,bull,bear ``` ## Knowledge Bases @@ -141,7 +141,12 @@ python scripts/forecast_builder.py forecast_data.json --scenarios base,bull,bear ## Input Data Format -All scripts accept JSON input files. See `assets/sample_financial_data.json` for the complete input schema covering all four tools. +All scripts accept JSON input files in either of two shapes: + +1. **Flat** — the tool's expected keys at the top level (e.g., `income_statement` / `balance_sheet` for the ratio calculator, `historical` / `assumptions` for DCF, `line_items` for variance, `historical_periods` / `drivers` / `assumptions` / `cash_flow_inputs` for forecasting). +2. **Nested (bundled)** — inputs for all four tools in one file, nested under per-tool keys: `ratio_analysis`, `dcf_valuation`, `budget_variance`, `forecast`. See `assets/sample_financial_data.json` for the complete bundled schema; every quick-start command above runs directly against it. + +Each script auto-detects the shape (flat keys win if present) and exits non-zero with a clear error if neither shape yields usable data. ## Dependencies diff --git a/finance/skills/financial-analyst/scripts/budget_variance_analyzer.py b/finance/skills/financial-analyst/scripts/budget_variance_analyzer.py index 86bfdb9f..42e6d088 100644 --- a/finance/skills/financial-analyst/scripts/budget_variance_analyzer.py +++ b/finance/skills/financial-analyst/scripts/budget_variance_analyzer.py @@ -25,6 +25,24 @@ def safe_divide(numerator: float, denominator: float, default: float = 0.0) -> f return numerator / denominator +def resolve_input_section( + data: Dict[str, Any], section_key: str, flat_keys: Tuple[str, ...] +) -> Dict[str, Any]: + """ + Accept both supported input shapes: + 1. Flat: the expected keys live at the top level of the JSON file. + 2. Nested: the data lives under a per-tool section key, as in + assets/sample_financial_data.json (which bundles inputs for all + four financial-analyst scripts in one file). + """ + if any(key in data for key in flat_keys): + return data + section = data.get(section_key) + if isinstance(section, dict): + return section + return data + + class BudgetVarianceAnalyzer: """Analyze budget variances with materiality filtering and classification.""" @@ -388,6 +406,16 @@ def main() -> None: print(f"Error: Invalid JSON in '{args.input_file}': {e}", file=sys.stderr) sys.exit(1) + data = resolve_input_section(data, "budget_variance", ("line_items",)) + if not data.get("line_items"): + print( + "Error: No budget line items found. Expected a non-empty " + "'line_items' array at the top level or nested under " + "'budget_variance'.", + file=sys.stderr, + ) + sys.exit(1) + analyzer = BudgetVarianceAnalyzer( data, threshold_pct=args.threshold_pct, diff --git a/finance/skills/financial-analyst/scripts/dcf_valuation.py b/finance/skills/financial-analyst/scripts/dcf_valuation.py index 7bce6aa6..8e28aa67 100644 --- a/finance/skills/financial-analyst/scripts/dcf_valuation.py +++ b/finance/skills/financial-analyst/scripts/dcf_valuation.py @@ -28,6 +28,24 @@ def safe_divide(numerator: float, denominator: float, default: float = 0.0) -> f return numerator / denominator +def resolve_input_section( + data: Dict[str, Any], section_key: str, flat_keys: Tuple[str, ...] +) -> Dict[str, Any]: + """ + Accept both supported input shapes: + 1. Flat: the expected keys live at the top level of the JSON file. + 2. Nested: the data lives under a per-tool section key, as in + assets/sample_financial_data.json (which bundles inputs for all + four financial-analyst scripts in one file). + """ + if any(key in data for key in flat_keys): + return data + section = data.get(section_key) + if isinstance(section, dict): + return section + return data + + class DCFModel: """Discounted Cash Flow valuation model.""" @@ -415,6 +433,15 @@ def main() -> None: print(f"Error: Invalid JSON in '{args.input_file}': {e}", file=sys.stderr) sys.exit(1) + data = resolve_input_section(data, "dcf_valuation", ("historical", "assumptions")) + if "historical" not in data: + print( + "Error: No valuation data found. Expected 'historical' and " + "'assumptions' at the top level or nested under 'dcf_valuation'.", + file=sys.stderr, + ) + sys.exit(1) + model = DCFModel() model.set_historical_financials(data.get("historical", {})) diff --git a/finance/skills/financial-analyst/scripts/forecast_builder.py b/finance/skills/financial-analyst/scripts/forecast_builder.py index 7251a2ef..b2794838 100644 --- a/finance/skills/financial-analyst/scripts/forecast_builder.py +++ b/finance/skills/financial-analyst/scripts/forecast_builder.py @@ -27,6 +27,24 @@ def safe_divide(numerator: float, denominator: float, default: float = 0.0) -> f return numerator / denominator +def resolve_input_section( + data: Dict[str, Any], section_key: str, flat_keys: Tuple[str, ...] +) -> Dict[str, Any]: + """ + Accept both supported input shapes: + 1. Flat: the expected keys live at the top level of the JSON file. + 2. Nested: the data lives under a per-tool section key, as in + assets/sample_financial_data.json (which bundles inputs for all + four financial-analyst scripts in one file). + """ + if any(key in data for key in flat_keys): + return data + section = data.get(section_key) + if isinstance(section, dict): + return section + return data + + def simple_linear_regression( x_values: List[float], y_values: List[float] ) -> Tuple[float, float, float]: @@ -479,6 +497,22 @@ def main() -> None: print(f"Error: Invalid JSON in '{args.input_file}': {e}", file=sys.stderr) sys.exit(1) + flat_keys = ( + "historical_periods", + "drivers", + "assumptions", + "cash_flow_inputs", + ) + data = resolve_input_section(data, "forecast", flat_keys) + if not any(data.get(key) for key in flat_keys): + print( + "Error: No forecast inputs found. Expected at least one of " + f"{', '.join(flat_keys)} at the top level or nested under " + "'forecast'.", + file=sys.stderr, + ) + sys.exit(1) + builder = ForecastBuilder(data) scenarios = [s.strip() for s in args.scenarios.split(",")] diff --git a/finance/skills/financial-analyst/scripts/ratio_calculator.py b/finance/skills/financial-analyst/scripts/ratio_calculator.py index 8a9e4573..6cf031b0 100644 --- a/finance/skills/financial-analyst/scripts/ratio_calculator.py +++ b/finance/skills/financial-analyst/scripts/ratio_calculator.py @@ -24,6 +24,24 @@ def safe_divide(numerator: float, denominator: float, default: float = 0.0) -> f return numerator / denominator +def resolve_input_section( + data: Dict[str, Any], section_key: str, flat_keys: Tuple[str, ...] +) -> Dict[str, Any]: + """ + Accept both supported input shapes: + 1. Flat: the expected keys live at the top level of the JSON file. + 2. Nested: the data lives under a per-tool section key, as in + assets/sample_financial_data.json (which bundles inputs for all + four financial-analyst scripts in one file). + """ + if any(key in data for key in flat_keys): + return data + section = data.get(section_key) + if isinstance(section, dict): + return section + return data + + class FinancialRatioCalculator: """Calculate and interpret financial ratios from statement data.""" @@ -408,6 +426,17 @@ def main() -> None: print(f"Error: Invalid JSON in '{args.input_file}': {e}", file=sys.stderr) sys.exit(1) + flat_keys = ("income_statement", "balance_sheet", "cash_flow", "market_data") + data = resolve_input_section(data, "ratio_analysis", flat_keys) + if not any(key in data for key in flat_keys): + print( + "Error: No financial statement data found. Expected " + f"{', '.join(flat_keys)} at the top level or nested under " + "'ratio_analysis'.", + file=sys.stderr, + ) + sys.exit(1) + calculator = FinancialRatioCalculator(data) if args.category: diff --git a/markdown-html/CLAUDE.md b/markdown-html/CLAUDE.md index 841f5751..0ad4db5c 100644 --- a/markdown-html/CLAUDE.md +++ b/markdown-html/CLAUDE.md @@ -8,15 +8,17 @@ The markdown-html domain converts long markdown files (the actual artifacts prod It is **not** an interactive prompt-tuning playground (`/playground` plugin owns that lane), **not** a landing-page generator (`marketing/landing/`), **not** a session-handoff brief generator (`engineering/handoff/` + `productivity/handoff/`), and **not** a static-site generator (single-file artifacts, not site indices). -## Skills (v2.10.0) +## Skills (v2.10.3 — domain complete) | Skill | Purpose | `context: fork`? | Status | |---|---|---|---| | `markdown-html-orchestrator` | Domain orchestrator — classifies doctype, gates on threshold + onboarding, routes to converter | YES | ✓ live | | `design-system` | One-time onboarding wizard + WCAG-AA-validated brand palette (12 CSS custom properties) + shared config | NO | ✓ live | -| `md-document` | Long-form converter: sticky TOC, collapsibles, search, code-copy, scrollspy | NO | v2.10.1 | -| `md-review` | Code-review converter: 2-col diff + severity-tagged margin annotations + jump-nav | NO | v2.10.1 | -| `md-slides` | Slide-deck converter: arrow-key nav + presenter mode + print-to-PDF | NO | v2.10.1 | +| `md-document` | Long-form converter: sticky TOC, collapsibles, search, code-copy, scrollspy | NO | ✓ live | +| `md-review` | Code-review converter: 2-col diff + severity-tagged margin annotations + jump-nav | NO | ✓ live | +| `md-slides` | Slide-deck converter: arrow-key nav + presenter mode + print-to-PDF | NO | ✓ live | + +All three converters are shipped. Routing always targets the converter skill's scripts — never hand-render HTML inline. ## Hard rules (domain-specific) @@ -42,7 +44,7 @@ Each SKILL.md ships a "Forcing-question library" section (cited-canon grilling, - `/cs:grill-markdown-html <path>.md` — Matt-Pocock-style 5-question grill before conversion - `/cs:design-system` — surface the onboarding wizard -Per-sub-skill commands land with the converter PRs in v2.10.1: +Per-sub-skill commands (all live): - `/cs:md-document`, `/cs:md-review`, `/cs:md-slides` ## Anti-patterns (domain-level) diff --git a/markdown-html/README.md b/markdown-html/README.md index a1e11d45..3f71f598 100644 --- a/markdown-html/README.md +++ b/markdown-html/README.md @@ -5,15 +5,15 @@ Convert long markdown files in a Claude project into single-file, lightly-interactive HTML that respects your brand. One-time design-system onboarding captures brand primary + accent + typography + layout style + default save location. Every conversion reads that config and renders consistently. -## Status — v2.10.0 (foundation) +## Status — v2.10.3 (domain complete) | Skill | Purpose | Status | |---|---|---| | `markdown-html-orchestrator` | Routes long markdown → converter sub-skill (`context: fork`) | ✓ live | | `design-system` | Onboarding wizard + WCAG-AA-validated brand palette + shared config | ✓ live | -| `md-document` | Long-form: sticky TOC + collapsibles + search + code-copy + scrollspy | v2.10.1 (next PR) | -| `md-review` | Code review: 2-col diff + severity-tagged margin annotations + jump-nav | v2.10.1 (next PR) | -| `md-slides` | Slide deck: arrow-key nav + presenter mode + print-to-PDF | v2.10.1 (next PR) | +| `md-document` | Long-form: sticky TOC + collapsibles + search + code-copy + scrollspy | ✓ live | +| `md-review` | Code review: 2-col diff + severity-tagged margin annotations + jump-nav | ✓ live | +| `md-slides` | Slide deck: arrow-key nav + presenter mode + print-to-PDF | ✓ live | ## Quick start @@ -32,7 +32,7 @@ python3 markdown-html/skills/markdown-html-orchestrator/scripts/doctype_classifi --input ./my-report.md --output json \ | python3 markdown-html/skills/markdown-html-orchestrator/scripts/route_explainer.py -# 5. Resolve where it would save (foundation; converters in v2.10.1) +# 5. Resolve where it would save python3 markdown-html/skills/markdown-html-orchestrator/scripts/output_path_resolver.py \ --input ./my-report.md --doctype document ``` @@ -42,6 +42,9 @@ python3 markdown-html/skills/markdown-html-orchestrator/scripts/output_path_reso - `/cs:markdown-html <path>.md` — top-level router (classify + route + recommend) - `/cs:grill-markdown-html <path>.md` — Matt-style 5-question grill before conversion - `/cs:design-system` — surface the onboarding wizard +- `/cs:md-document <path>.md` — long-form converter +- `/cs:md-review <path>.md` — code-review converter +- `/cs:md-slides <path>.md` — slide-deck converter ## Hard rules @@ -69,7 +72,10 @@ markdown-html/ ├── commands/ │ ├── cs-markdown-html.md # router │ ├── cs-design-system.md # onboarding surface -│ └── cs-grill-markdown-html.md # 5-question grill +│ ├── cs-grill-markdown-html.md # 5-question grill +│ ├── cs-md-document.md # long-form converter +│ ├── cs-md-review.md # code-review converter +│ └── cs-md-slides.md # slide-deck converter └── skills/ ├── markdown-html-orchestrator/ # context: fork │ ├── SKILL.md @@ -81,18 +87,21 @@ markdown-html/ │ ├── information_density_canon.md │ ├── orchestrator_routing_patterns.md │ └── single_file_html_discipline.md - └── design-system/ - ├── SKILL.md - ├── scripts/ - │ ├── onboard.py - │ ├── config_loader.py - │ └── brand_palette_validator.py - ├── references/ - │ ├── design_token_canon.md - │ ├── wcag_accessibility.md - │ └── typography_pairing.md - └── assets/ - └── design_system_schema.json + ├── design-system/ + │ ├── SKILL.md + │ ├── scripts/ + │ │ ├── onboard.py + │ │ ├── config_loader.py + │ │ └── brand_palette_validator.py + │ ├── references/ + │ │ ├── design_token_canon.md + │ │ ├── wcag_accessibility.md + │ │ └── typography_pairing.md + │ └── assets/ + │ └── design_system_schema.json + ├── md-document/ # long-form: markdown_parser → html_renderer → interactivity_injector + ├── md-review/ # code review: diff_parser → annotation_extractor → review_html_renderer + └── md-slides/ # slide deck: slide_splitter → presenter_notes_parser → deck_html_renderer ``` ## License diff --git a/markdown-html/agents/cs-markdown-html-orchestrator.md b/markdown-html/agents/cs-markdown-html-orchestrator.md index 1070ca03..42fe7193 100644 --- a/markdown-html/agents/cs-markdown-html-orchestrator.md +++ b/markdown-html/agents/cs-markdown-html-orchestrator.md @@ -31,7 +31,7 @@ You route every inquiry to one of three converter sub-skills via the `markdown-h | Review | `md-review` | Code review / PR writeup with diff blocks and severity annotations | | Slides | `md-slides` | Slide deck with `---` boundaries or H1 cadence + presenter notes | -Each sub-skill ships in v2.10.1 follow-up PRs. Until they land (v2.10.0 foundation), you run the classifier + design-system gate and hand the rendering brief back to Claude. +All three converter sub-skills are live. After the classifier + design-system gate pass, hand the conversion to the routed sub-skill's renderer scripts — never render HTML by hand. ## Pre-flight gates (refuse and surface, never override) @@ -81,10 +81,9 @@ After running a conversion, return a **≤ 100-word digest**: - `/cs:grill-markdown-html <markdown-file-path>` — Matt-style grilling before conversion - `/cs:design-system` — surface the onboarding wizard -Once converter sub-skills ship in v2.10.1: -- `/cs:md-document <markdown-file-path>` -- `/cs:md-review <markdown-file-path>` -- `/cs:md-slides <markdown-file-path>` +- `/cs:md-document <markdown-file-path>` — long-form converter +- `/cs:md-review <markdown-file-path>` — code-review converter +- `/cs:md-slides <markdown-file-path>` — slide-deck converter ## When to escalate diff --git a/markdown-html/commands/cs-markdown-html.md b/markdown-html/commands/cs-markdown-html.md index d297f1ee..1be7ad19 100644 --- a/markdown-html/commands/cs-markdown-html.md +++ b/markdown-html/commands/cs-markdown-html.md @@ -53,6 +53,6 @@ python3 markdown-html/skills/markdown-html-orchestrator/scripts/output_path_reso - Never invent brand colors when the user hasn't onboarded. Surface onboarding. - Output is single-file HTML. External CDN is limited to Google Fonts + Prism.js. -## Foundation status (v2.10.0) +## Status -The orchestrator + `design-system` are live. Converter sub-skills (`md-document`, `md-review`, `md-slides`) land in v2.10.1 follow-up PRs. Until then, this command runs the classifier + design-system gate and returns the routing brief; Claude does the rendering inline with the design-system tokens. +All five skills are live (orchestrator + `design-system` + the three converters). This command runs the classifier + design-system gate, then hands the conversion to the routed converter sub-skill (`/cs:md-document`, `/cs:md-review`, or `/cs:md-slides`). Never render HTML inline — the converter scripts own the rendering. diff --git a/markdown-html/skills/markdown-html-orchestrator/SKILL.md b/markdown-html/skills/markdown-html-orchestrator/SKILL.md index 0b7f1b4b..c9f28ff7 100644 --- a/markdown-html/skills/markdown-html-orchestrator/SKILL.md +++ b/markdown-html/skills/markdown-html-orchestrator/SKILL.md @@ -2,7 +2,7 @@ name: 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 — 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 the user has run the design-system onboarding once. Refuses if input is under 100 lines (per Shihipar — markdown still wins below the threshold) or design-system isn't onboarded. Distinct from Anthropic's official Playground plugin (which is interactive prompt-tuning controls with sliders/knobs/prompt-copy-back) and from marketing/landing/ (which is a landing-page generator). context: fork -version: 2.10.0 +version: 2.10.3 author: Alireza Rezvani license: MIT tags: [markdown, html, converter, orchestrator, documentation, code-review, slides, design-system] @@ -15,7 +15,7 @@ Thariq Shihipar's argument (Claude Code HTML output essay, Medium 2026): **markd This orchestrator forks context, classifies the input markdown deterministically, routes to the right converter sub-skill, and returns a digest with the output path. Heavy intake (full markdown bodies, diffs, slide decks) stays in the forked context. -**Foundation status (v2.10.0):** orchestrator + `design-system` (onboarding + shared brand tokens) are live. Converter sub-skills (`md-document`, `md-review`, `md-slides`) land in v2.10.1 follow-up PRs. Until they land, this skill still runs the classifier and the design-system gate, and surfaces the routing recommendation — it just hands the rendering work back to Claude with the structured brief. +**Domain status (complete):** all five skills are live — orchestrator + `design-system` (onboarding + shared brand tokens) + the three converter sub-skills (`md-document`, `md-review`, `md-slides`). Always route conversions to the shipped converter's scripts; never hand-render HTML inline. ## When to invoke @@ -46,9 +46,9 @@ Two-signal threshold pattern lifted from `research-ops/skills/research-ops-skill The pipeline: ```bash -python3 skills/markdown-html-orchestrator/scripts/doctype_classifier.py \ +python3 markdown-html/skills/markdown-html-orchestrator/scripts/doctype_classifier.py \ --input <path>.md --output json \ - | python3 skills/markdown-html-orchestrator/scripts/route_explainer.py + | python3 markdown-html/skills/markdown-html-orchestrator/scripts/route_explainer.py ``` `route_explainer.py` checks the design-system status, applies the < 100-line refusal, and prints one of: `ROUTE_SILENTLY -> md-<type>`, `ASK_USER one question: ...`, or `REFUSE — fix the issues above`. @@ -76,17 +76,15 @@ Pipe the classification into `route_explainer.py`. If it says `ROUTE_SILENTLY`, ### Step 4 — Resolve the output path ```bash -python3 skills/markdown-html-orchestrator/scripts/output_path_resolver.py \ +python3 markdown-html/skills/markdown-html-orchestrator/scripts/output_path_resolver.py \ --input <path>.md --doctype <document|review|slides> ``` Collision handling defaults to `-2 / -3 / ...` suffix; `--on-collision timestamp` for stamped names. -### Step 5 — Hand off to the sub-skill (when shipped) +### Step 5 — Hand off to the sub-skill -In v2.10.1+, the converter sub-skill's renderer takes the input markdown, the design-system config, and the resolved output path, and writes a single self-contained HTML file. The orchestrator returns a ≤ 100-word digest: input lines, output path, design style applied, top 3 features used (TOC, search, code-copy, etc.), and one forcing question for the user. - -Until v2.10.1, the orchestrator's job stops at step 4 — it returns the classification + routing brief and lets Claude do the rendering inline with the design-system tokens. +The routed converter sub-skill's renderer (`md-document/scripts/`, `md-review/scripts/`, or `md-slides/scripts/`) takes the input markdown, the design-system config, and the resolved output path, and writes a single self-contained HTML file. The orchestrator returns a ≤ 100-word digest: input lines, output path, design style applied, top 3 features used (TOC, search, code-copy, etc.), and one forcing question for the user. Never render HTML by hand — the converter scripts own the rendering. ## Forcing-question library (Matt Pocock grill-with-docs pattern) @@ -130,9 +128,9 @@ Never run a sub-skill before the lane is locked. | Sub-skill | Artifact | Status | |---|---|---| -| `md-document` | `doc-<slug>.html` (single file, sticky TOC, collapsibles, search, code-copy, scrollspy) | v2.10.1 | -| `md-review` | `review-<slug>.html` (2-col diff + severity margin notes + jump-nav) | v2.10.1 | -| `md-slides` | `deck-<slug>.html` (arrow-key nav + presenter mode + print-to-PDF) | v2.10.1 | +| `md-document` | `doc-<slug>.html` (single file, sticky TOC, collapsibles, search, code-copy, scrollspy) | ✓ live | +| `md-review` | `review-<slug>.html` (2-col diff + severity margin notes + jump-nav) | ✓ live | +| `md-slides` | `deck-<slug>.html` (arrow-key nav + presenter mode + print-to-PDF) | ✓ live | ## Anti-patterns (do not) diff --git a/markdown-html/skills/markdown-html-orchestrator/references/information_density_canon.md b/markdown-html/skills/markdown-html-orchestrator/references/information_density_canon.md index 3f08a659..4b62e234 100644 --- a/markdown-html/skills/markdown-html-orchestrator/references/information_density_canon.md +++ b/markdown-html/skills/markdown-html-orchestrator/references/information_density_canon.md @@ -33,7 +33,7 @@ Argues that interactive controls let a reader move fluidly between concrete exam Establishes the "garden" pattern: persistent, interlinked, editable knowledge artifacts rendered as HTML. Reinforces single-file HTML as the right artifact shape for long-form thinking (vs. blog posts as linear sequences). Many of her gardens use the exact patterns this plugin generates: sticky TOC, collapsibles, callouts. ### 5. Amelia Wattenberger — "Why React isn't great for actually building websites" + interactive essay archive (wattenberger.com) -Demonstrates lightweight interactivity in essays without frameworks — IntersectionObserver, vanilla scroll handling, inline SVG. The exact technical patterns md-document will use. +Demonstrates lightweight interactivity in essays without frameworks — IntersectionObserver, vanilla scroll handling, inline SVG. The exact technical patterns md-document uses. ### 6. Bartosz Ciechanowski — *Internal Combustion Engine* and other essays (ciechanow.ski) The high-water mark of single-page interactive explainers. Each essay is a single HTML file with inline SVG animation and controls. Validates the single-file-HTML-as-artifact thesis at the upper bound. diff --git a/marketing-skill/.claude-plugin/plugin.json b/marketing-skill/.claude-plugin/plugin.json index f8c4a780..51af5434 100644 --- a/marketing-skill/.claude-plugin/plugin.json +++ b/marketing-skill/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "marketing-skills", - "description": "45 production-ready marketing skills across 8 pods: Content (copywriting, content strategy, content production), SEO + AEO (traditional audits, schema markup, programmatic SEO, site architecture, plus Answer Engine Optimization for LLM citation in ChatGPT/Perplexity/Claude/Gemini/Mistral), CRO (A/B testing, forms, popups, signup flows, pricing, onboarding), Channels (email sequences, social media, paid ads, cold email, X/Twitter growth), Growth (launch strategy, referral programs, free tools), Intelligence (competitor analysis, marketing psychology, analytics tracking), and Sales enablement. Agent skill and plugin for Claude Code, Codex, Gemini CLI, Cursor, OpenClaw.", + "description": "44 production-ready marketing skills across 8 pods: Content (copywriting, content strategy, content production), SEO + AEO (traditional audits, schema markup, programmatic SEO, site architecture, plus Answer Engine Optimization for LLM citation in ChatGPT/Perplexity/Claude/Gemini/Mistral), CRO (A/B testing, forms, popups, signup flows, pricing, onboarding), Channels (email sequences, social media, paid ads, cold email, X/Twitter growth), Growth (launch strategy, referral programs, free tools), Intelligence (competitor analysis, marketing psychology, analytics tracking), and Sales enablement. Agent skill and plugin for Claude Code, Codex, Gemini CLI, Cursor, OpenClaw.", "version": "2.9.0", "author": { "name": "Alireza Rezvani", diff --git a/marketing-skill/.codex/instructions.md b/marketing-skill/.codex/instructions.md index c3d1b87f..f3a5e575 100644 --- a/marketing-skill/.codex/instructions.md +++ b/marketing-skill/.codex/instructions.md @@ -10,7 +10,7 @@ When working on marketing tasks, use the marketing skill system: ## Context -If `marketing-context.md` exists in the project root, read it before any marketing task. It contains brand voice, audience personas, and competitive landscape. +If `.claude/product-marketing-context.md` exists, read it before any marketing task. It contains brand voice, audience personas, and competitive landscape. ## Python Tools @@ -29,7 +29,7 @@ python3 marketing-skill/ad-creative/scripts/ad_copy_validator.py <file> | Write content | content-production | | Plan content | content-strategy | | SEO audit | seo-audit | -| AI search optimization | ai-seo | +| AI search optimization / AEO | aeo | | Page conversion | page-cro | | Email sequences | email-sequence | | Pricing | pricing-strategy | @@ -37,6 +37,6 @@ python3 marketing-skill/ad-creative/scripts/ad_copy_validator.py <file> ## Rules -- Never load all 42 skills at once — route to 1-2 per request -- Check marketing-context.md before starting +- Never load all 44 skills at once — route to 1-2 per request +- Check `.claude/product-marketing-context.md` before starting - Use Python tools for scoring and validation, not manual judgment diff --git a/marketing-skill/CLAUDE.md b/marketing-skill/CLAUDE.md index e71ba8d4..b6db0896 100644 --- a/marketing-skill/CLAUDE.md +++ b/marketing-skill/CLAUDE.md @@ -2,12 +2,12 @@ ## For All Agents (Claude Code, Codex CLI, OpenClaw) -This directory contains 45 marketing skills organized into 8 specialist pods (Content, SEO + AEO, CRO, Channels, Growth, Intelligence, Sales enablement, Marketing ops). +This directory contains 44 marketing skills organized into 8 specialist pods (Content, SEO + AEO, CRO, Channels, Growth, Intelligence, Sales enablement, Marketing ops). ### How to Use 1. **Start with routing:** Read `marketing-ops/SKILL.md` — it has a routing matrix that maps user requests to the right skill. -2. **Check context:** If `marketing-context.md` exists, read it first. It has brand voice, personas, and competitive landscape. +2. **Check context:** If `.claude/product-marketing-context.md` exists, read it first. It has brand voice, personas, and competitive landscape. 3. **Load ONE skill:** Read only the specialist SKILL.md you need. Never bulk-load. ### Skill Map @@ -16,7 +16,6 @@ This directory contains 45 marketing skills organized into 8 specialist pods (Co - `marketing-ops/` — Router (read this to know where to go) - `content-production/` — Write content (blog posts, articles, guides) - `content-strategy/` — Plan what content to create -- `ai-seo/` — Optimize for AI search engines (ChatGPT, Perplexity, Google AI) - `aeo/` — Answer Engine Optimization (E-E-A-T scoring, schema injection, citation tracking across LLMs) - `seo-audit/` — Traditional SEO audit - `page-cro/` — Conversion rate optimization @@ -26,7 +25,7 @@ This directory contains 45 marketing skills organized into 8 specialist pods (Co ### Python Tools -58 scripts, all stdlib-only. Run directly: +59 scripts, all stdlib-only. Run directly: ```bash python3 <skill>/scripts/<tool>.py [args] ``` @@ -34,7 +33,7 @@ No pip install needed. Scripts include embedded samples for demo mode (run with ### Anti-Patterns -❌ Don't read all 45 SKILL.md files -❌ Don't skip marketing-context.md if it exists +❌ Don't read all 44 SKILL.md files +❌ Don't skip `.claude/product-marketing-context.md` if it exists ❌ Don't use content-creator (deprecated → use content-production) ❌ Don't install pip packages for Python tools diff --git a/marketing-skill/MARKETING-AUDIT-REPORT.md b/marketing-skill/MARKETING-AUDIT-REPORT.md deleted file mode 100644 index dd0094a3..00000000 --- a/marketing-skill/MARKETING-AUDIT-REPORT.md +++ /dev/null @@ -1,219 +0,0 @@ -# Marketing Skills & Plugins — Gap Audit - -**Audit date:** 2026-05-28 -**Branch:** `claude/marketing-audit-gaps-GCCiT` -**Scope:** `marketing-skill/` (45 skills, 1 plugin) + `marketing/landing/` (1 standalone plugin) -**Method:** structural survey + content sampling + script smoke tests + governance cross-check - ---- - -## Executive Summary - -The marketing portfolio is the largest single domain in the repo and broadly **production-ready at the script and content layer** — 60 Python tools all pass `--help`, stdlib-only, zero LLM calls — but it has **serious governance drift, count inconsistencies, and notable coverage holes** in modern channels (video, newsletter, community, PR, ABM, SMS). - -| Dimension | Verdict | Why | -|---|---|---| -| Scripts / automation | **PASS** | 60/60 stdlib-only, no API calls, all `--help` clean | -| SKILL.md content | **PASS with 1 thin skill** | Only `brand-guidelines` is clearly under-built (94 lines) | -| Governance / counts | **FAIL** | README says "6 skills"; marketplace says "44"; CLAUDE.md says "46"; reality is 45 | -| Discoverability (commands/agents) | **FAIL** | Only 2/45 skills have slash commands; only 3 cs-* agents for 8 pods | -| Coverage of modern channels | **PARTIAL** | Missing YouTube, TikTok, newsletter, community, PR, ABM, SMS, influencer | -| Internal redundancy | **PARTIAL** | Social-media quadrant is over-segmented; `prompt-engineer-toolkit` is mis-located | -| Path-B contract compliance | **MIXED** | Only `aeo` is fully Path-B; rest predate the convention | - ---- - -## 1. Critical Governance Issues (fix first) - -### 1.1 Skill-count drift across 4 sources — VERDICT: FIX IMMEDIATELY -**Why:** every downstream consumer (marketplace search, README, plugin loader) sees a different number. - -| Source | Claims | Actual | -|---|---|---| -| Disk inventory | 45 | 45 | -| `marketing-skill/.claude-plugin/plugin.json:3` | "45 production-ready marketing skills" | ✅ | -| `.claude-plugin/marketplace.json:18` | "44 marketing skills across 7 pods" | ❌ (-1) | -| `.claude-plugin/marketplace.json:7` (top description) | "marketing (46 …)" | ❌ (+1) | -| `marketing-skill/README.md:3` | "Complete suite of **6** expert marketing skills" | ❌ (-39) | -| `marketing-skill/CLAUDE.md:3` | "45 marketing skills" | ✅ | -| Root `CLAUDE.md` | "46 marketing skills (8 pods)" | ❌ (+1) | - -**Verdict:** README is **~3 years stale** — still describes the 6-skill v1 era. Marketplace.json description undercounts pods (7 vs 8 — AEO pod was added in v2.7.3 and the marketplace blurb wasn't updated). Single source of truth needed. - -### 1.2 README.md is unusable — VERDICT: REWRITE -- 1,003 lines that document only `content-creator` (deprecated), `marketing-demand-acquisition`, and `marketing-strategy-pmm`. A user landing here discovers <7% of the available tooling. -- Currently functions as anti-documentation: it actively misleads. - -### 1.3 Loose .zip artifacts in repo root — VERDICT: DELETE -Five `.zip` files (May 23 dates) in `marketing-skill/` root: `app-store-optimization.zip`, `content-creator.zip`, `marketing-demand-acquisition.zip`, `marketing-strategy-pmm.zip`, `social-media-analyzer.zip`. These are v1-era distribution bundles superseded by the `skills/` tree. **No purpose**, ~118 KB of dead weight, confusing to cloners. Drop them; if they need to persist for archival, move to `documentation/legacy-bundles/` and gitignore. - -### 1.4 Deprecated `content-creator/` still loadable — VERDICT: REMOVE or HARD-DEPRECATE -- `marketing-skill/skills/content-creator/SKILL.md` still resolvable via plugin -- `agents/marketing/cs-content-creator.md` still references it -- CLAUDE.md says it's deprecated ("→ use content-production") but nothing enforces it -- Either delete the folder entirely or make SKILL.md a 5-line redirect stub. - ---- - -## 2. Discoverability — Severe Under-Investment - -### 2.1 Slash commands: 2 of 45 skills — VERDICT: BUILD 6 PRIORITY COMMANDS -`commands/` contains only `cs-aeo.md` and `seo-auditor.md`. Compare to: -- `c-level-advisor/`: ~17 `/cs:*` commands for 28 skills -- `engineering/`: many `/slo-design`, `/chaos-experiment`, `/flag-cleanup`, etc. - -Marketing is the largest domain (45 skills) and has the fewest commands per skill (0.04). Recommended Phase-1 commands: -- `/cs:marketing` — pod router (wraps `marketing-ops`) -- `/cs:seo-audit` — wraps `seo-audit` skill -- `/cs:cro` — wraps `page-cro` + funnel chain -- `/cs:content-brief` — wraps `content-strategy` -- `/cs:launch-plan` — wraps `launch-strategy` -- `/cs:competitor-analysis` — wraps `competitor-alternatives` - -### 2.2 Agents: 3 cs-* marketing agents for 8 pods — VERDICT: BUILD 5 MORE -Current: `cs-aeo`, `cs-content-creator` (deprecated), `cs-demand-gen-specialist`. Missing personas for: Content, SEO, CRO, Social, Growth. Following the pattern in `c-level-advisor/c-level-agents/`, each pod deserves a forcing-question persona agent. - -### 2.3 No `.gemini/` sync despite plugin.json claim — VERDICT: SYNC OR REMOVE CLAIM -`marketing-skill/plugin.json:3` claims compatibility with "Claude Code, Codex, Gemini CLI, Cursor, OpenClaw" but only `.codex/instructions.md` exists. Either run `sync-gemini-skills.py` parallel to the codex pattern, or trim the claim. - ---- - -## 3. Coverage Gaps — What's Missing - -Verdicts below are "ADD" if the channel is mainstream B2B/SaaS marketing in 2026 and currently has zero coverage in the 45 skills. - -| Missing capability | Verdict | Why | -|---|---|---| -| **YouTube strategy** (script-to-publish, thumbnails, retention) | **ADD — priority 1** | YouTube is now the #1 long-form discovery engine; no skill covers it. `video-content-strategist/` exists as a sibling folder but isn't wired into the marketing-skill plugin | -| **Short-form video** (TikTok, Reels, Shorts) | **ADD — priority 1** | Dominant 2024-2026 discovery surface; only x-twitter-growth touches video | -| **Newsletter strategy** (Substack/Beehiiv era — list growth, monetization, sponsorship) | **ADD — priority 1** | `email-sequence` covers lifecycle and `cold-email` covers outreach; nothing covers owned newsletter audience-building, which is now table-stakes B2B distribution | -| **Community marketing** (Discord, Slack, Circle, owned communities) | **ADD — priority 2** | Highest retention & word-of-mouth lever in 2026; zero coverage | -| **PR / earned media** (press release, journalist outreach, HARO-style replies) | **ADD — priority 2** | Compounds with AEO (citations drive E-E-A-T); currently no skill | -| **ABM (account-based marketing)** | **ADD — priority 2** | B2B SaaS staple; the cold-email skill is too narrow | -| **Multi-touch attribution** | **ADD — priority 2** | `analytics-tracking` only generates tracking plans; no attribution model selection (MTA vs MMM vs incrementality) | -| **Influencer / creator partnerships** | **ADD — priority 3** | Mainstream channel; zero coverage | -| **Affiliate program operations** | **ADD — priority 3** | `referral-program` covers customer referrals, not third-party affiliates | -| **LinkedIn organic growth** | **ADD — priority 3** | X has its own skill; LinkedIn (the dominant B2B social) does not | -| **SMS marketing** | **ADD — priority 4** | High ROI for ecom/D2C; absent | -| **Push notifications** | **ADD — priority 4** | Mobile retention lever; absent | -| **i18n / localization marketing** | **SKIP — fold into marketing-strategy-pmm** | `marketing-strategy-pmm/references/international-gtm.md` exists; can be promoted into a sub-skill later | -| **Podcast marketing** | **SKIP** | Niche; lower ROI than the above | - ---- - -## 4. Internal Redundancy & Mis-located Skills - -### 4.1 Social-media quadrant — VERDICT: CONSOLIDATE OR DOCUMENT BOUNDARIES -Four overlapping skills, no clear router: -- `social-content/` (write posts) -- `social-media-manager/` (strategy, calendar) -- `social-media-analyzer/` (metrics, ROI) -- `x-twitter-growth/` (X-specific tactics) - -A user who says "grow my Twitter following" plausibly matches 3 of 4. Either: -- **(a)** Add an explicit Social pod orchestrator skill (`social-ops`) with a routing matrix, OR -- **(b)** Consolidate `social-content` + `social-media-manager` → one `social-media` skill; keep analyzer + x-twitter-growth distinct. - -Recommendation: **(a)** — preserves depth, fixes routing. - -### 4.2 `prompt-engineer-toolkit/` — VERDICT: MOVE TO ENGINEERING -2 scripts, 3 refs, all about prompt-engineering infrastructure (versioning, A/B eval, regression testing). This is engineering tooling, not marketing. A marketer doesn't write prompt eval harnesses. Either: -- Move to `engineering/prompt-engineer-toolkit/`, OR -- Refocus the skill to *marketing-prompt-craft* (headline prompts, content-brief prompts, copy-rewrite prompts) and rename to `marketing-prompts/`. - -### 4.3 `marketing-skills/` vs `marketing-ops/` — VERDICT: KEEP BOTH (with note) -The Explore agent confirmed these are complementary, not duplicates: `marketing-skills/` is the ecosystem-architecture doc, `marketing-ops/` is the question-router. **Document the distinction in both SKILL.md frontmatters** so users don't bounce between them. - -### 4.4 `marketing/landing/` standalone vs `marketing-skill/skills/page-cro/` — VERDICT: KEEP DISTINCT (verified) -- `marketing/landing/` produces single-file HTML with GSAP animation (premium one-pager output) -- `product-team/skills/landing-page-generator/` outputs Next.js TSX (conversion-optimized) -- `page-cro/` audits live pages for conversion friction - -The `source.distinct_from` field in `marketing/landing/plugin.json` already documents this — good pattern, replicate elsewhere. - ---- - -## 5. Per-Skill Quality Issues (the 12 thinnest) - -From the structural survey + content sampling: - -| Skill | Issue | Verdict | -|---|---|---| -| `brand-guidelines` | 94 lines, mostly Q&A, no scripts, 1 ref | **EXPAND** — add brand audit script, brand-voice scorer, +2 refs | -| `paywall-upgrade-cro` | 0 scripts, 0 refs (body is self-contained 259 lines) | **ADD** 1 paywall-friction scorer script + 1 ref on paywall canon (Steinman, Lincoln Murphy) | -| `popup-cro` | 0 scripts | **ADD** popup-frequency-cap calculator + popup A/B sizer | -| `social-content` | 0 scripts despite 324-line SKILL.md | **ADD** hook-quality scorer + post-format classifier | -| `marketing-psychology` | 0 scripts | **ADD** mental-model picker (Cialdini/JTBD/loss-aversion routing) | -| `marketing-ideas` | 0 scripts | **ADD** idea-prioritizer (RICE-for-marketing) | -| `marketing-strategy-pmm` | 0 scripts despite 399-line SKILL.md + 4 refs | **ADD** ICP scorer + positioning-statement validator | -| `ai-seo` | 0 scripts | **ADD** AI-search audit script (LLM-citation surface check) | -| `programmatic-seo` | 0 refs | **ADD** ref on programmatic-SEO canon (Zapier/G2/Tripadvisor patterns) | -| `onboarding-cro` | 0 refs | **ADD** ref on activation patterns (Reforge/Eppo) | -| `page-cro` | 0 refs | **ADD** ref on CRO canon (Bryan Eisenberg, Linnworks, CXL) | -| `social-media-manager` | 0 refs | **ADD** platform-specific refs | - -**Why this matters:** the Path-B contract (3 scripts + 3 refs each) became the standard from v2.7.0 onward; legacy marketing skills predate it. Bringing them up to 1+ script and 1+ ref each is a low-cost lift that doubles the deterministic tooling surface. - ---- - -## 6. Path-B Contract Compliance - -Only `aeo/` was built under the Path-B 11-file contract (SKILL.md + 3 scripts + 3 refs + cs-* agent + /cs:* command + plugin.json + `source` field). The other 44 skills predate it. **Verdict: DO NOT retroactively force Path-B on all 44** — it's expensive and the legacy skills work. Instead: - -- Apply Path-B to all *new* marketing skills going forward (newsletter, YouTube, community, etc. from §3). -- Promote 5 highest-traffic legacy skills to Path-B opportunistically: `seo-audit`, `page-cro`, `content-production`, `copywriting`, `paid-ads`. - ---- - -## 7. Recommended Action Plan (Prioritized) - -| # | Action | Effort | Impact | -|---|---|---|---| -| 1 | Fix the count drift (README, marketplace.json:7, marketplace.json:18, root CLAUDE.md) → single source = 45 skills, 8 pods | XS | HIGH — fixes discoverability immediately | -| 2 | Delete the 5 legacy `.zip` files | XS | LOW noise reduction | -| 3 | Replace README.md with an auto-generated index of the 45 skills (1 line per skill, grouped by pod) | S | HIGH — current README is anti-documentation | -| 4 | Hard-deprecate or delete `content-creator/` skill + `cs-content-creator.md` agent | XS | MEDIUM — removes a known landmine | -| 5 | Build 6 priority slash commands (§2.1) | M | HIGH — discoverability | -| 6 | Build 5 pod cs-* agents (§2.2) | M | MEDIUM | -| 7 | Add 4 high-priority missing skills: `newsletter`, `youtube`, `short-form-video`, `community-marketing` (Path-B each) | L | HIGH — covers the largest channel gaps | -| 8 | Decide on `prompt-engineer-toolkit/`: move to engineering OR refocus on marketing prompt craft | S | MEDIUM | -| 9 | Add the 12 missing scripts/refs from §5 | M | MEDIUM | -| 10 | Add Gemini CLI sync OR remove the claim from plugin.json | S | LOW | -| 11 | Phase-2 missing skills: ABM, attribution-modeling, PR-outreach, influencer-marketing, linkedin-growth | L | MEDIUM | -| 12 | Phase-3: SMS, push, affiliate, podcast (lower ROI per effort) | L | LOW | - -**Quick wins (do this week):** #1, #2, #3, #4 — entirely governance, low effort, removes most of the documentation rot. - -**Strategic investments (next quarter):** #5, #6, #7 — bring discoverability and modern-channel coverage to par with c-level-advisor and engineering domains. - ---- - -## Appendix A — Verified Data Points - -- 45 skill subdirectories on disk in `marketing-skill/skills/` -- 60 Python scripts in marketing skills (all stdlib, all `--help` clean, zero API calls) -- ~75 reference docs across skills -- 2 marketing-related slash commands (`cs-aeo`, `seo-auditor`) -- 3 cs-* marketing agents (1 deprecated) -- 1 `.codex/` sync folder; no `.gemini/`, `.hermes/`, or `.vibe/` for marketing -- 5 legacy `.zip` artifacts in domain root (~118 KB) -- 1 standalone plugin (`marketing/landing/`) — legitimately distinct from `page-cro` and `landing-page-generator` - -## Appendix B — Skills With Strong Content But Zero Tooling - -These are the skills most worth investing 1 script + 1 ref in (highest content-to-tooling ratio): - -| Skill | SKILL.md lines | Scripts | Refs | -|---|---|---|---| -| `marketing-strategy-pmm` | 399 | 0 | 4 | -| `social-content` | 324 | 0 | 3 | -| `paywall-upgrade-cro` | 259 | 0 | 0 | -| `popup-cro` | 230 | 0 | 1 | -| `marketing-ideas` | 212 | 0 | 1 | -| `social-media-manager` | 198 | 1 | 0 | -| `marketing-psychology` | 124 | 0 | 1 | -| `brand-guidelines` | 94 | 0 | 1 | - ---- - -**End of audit.** diff --git a/marketing-skill/MARKETING-EXECUTION-PLAN.md b/marketing-skill/MARKETING-EXECUTION-PLAN.md deleted file mode 100644 index 4f74ea5e..00000000 --- a/marketing-skill/MARKETING-EXECUTION-PLAN.md +++ /dev/null @@ -1,334 +0,0 @@ -# Marketing Team Expansion — Execution Plan - -## Final Architecture - -``` -CMO Advisor (c-level-advisor/cmo-advisor/) - │ - │ reads company-context.md + marketing-context.md - │ -Marketing Ops (router + orchestrator) - │ - ├── Content Pod (8) - │ ├── content-creator .......... [UPGRADE] add context integration, quality loop - │ ├── content-strategy ......... [IMPORT] from workspace - │ ├── copywriting .............. [IMPORT] from workspace - │ ├── copy-editing ............. [IMPORT] from workspace - │ ├── social-content ........... [IMPORT] from workspace - │ ├── marketing-ideas .......... [IMPORT] from workspace - │ ├── content-production ....... [NEW] research→write→optimize pipeline - │ └── content-humanizer ........ [NEW] AI watermark removal, voice injection - │ - ├── SEO Pod (5) - │ ├── seo-audit ................ [IMPORT] from workspace + add seo_checker.py - │ ├── programmatic-seo ......... [IMPORT] from workspace - │ ├── ai-seo ................... [NEW] AEO, GEO, LLMO optimization - │ ├── schema-markup ............ [NEW] JSON-LD, structured data - │ └── site-architecture ........ [NEW] URL structure, nav, internal linking - │ - ├── CRO Pod (6) - │ ├── page-cro ................. [IMPORT] from workspace - │ ├── form-cro ................. [IMPORT] from workspace - │ ├── signup-flow-cro .......... [IMPORT] from workspace - │ ├── onboarding-cro ........... [IMPORT] from workspace - │ ├── popup-cro ................ [IMPORT] from workspace - │ └── paywall-upgrade-cro ...... [IMPORT] from workspace - │ - ├── Channels Pod (5) - │ ├── email-sequence ........... [IMPORT] from workspace - │ ├── paid-ads ................. [IMPORT] from workspace - │ ├── social-media-manager ..... [UPGRADE] rename + expand from social-media-analyzer - │ ├── cold-email ............... [NEW] B2B outreach sequences - │ └── ad-creative .............. [NEW] bulk ad generation + iteration - │ - ├── Growth Pod (3) - │ ├── ab-test-setup ............ [IMPORT] from workspace - │ ├── referral-program ......... [NEW] referral + affiliate programs - │ └── free-tool-strategy ....... [NEW] engineering as marketing - │ - ├── Intelligence Pod (4) - │ ├── campaign-analytics ....... [UPGRADE] add cross-channel synthesis - │ ├── competitor-alternatives .. [IMPORT] from workspace - │ ├── marketing-psychology ..... [IMPORT] from workspace - │ └── analytics-tracking ....... [NEW] GA4, GTM, event tracking setup - │ - └── Sales & GTM Pod (2) - ├── launch-strategy .......... [IMPORT] from workspace - └── pricing-strategy ......... [NEW] pricing, packaging, monetization - - Standalone (keep in place, no pod): - ├── marketing-demand-acquisition . [KEEP] already in repo - ├── marketing-strategy-pmm ....... [KEEP] already in repo - ├── app-store-optimization ....... [KEEP] already in repo - └── prompt-engineer-toolkit ...... [KEEP] already in repo - - Cross-Domain References (marketing-ops routes to these): - ├── business-growth/revenue-operations/ (RevOps) - ├── business-growth/sales-engineer/ (Sales Enablement) - ├── business-growth/customer-success-manager/ (Churn Prevention) - ├── product-team/landing-page-generator/ (Landing Pages) - ├── product-team/competitive-teardown/ (Competitive Analysis) - └── engineering-team/email-template-builder/ (Email Templates) -``` - -## Totals - -| Action | Count | -|--------|-------| -| Import from workspace | 20 | -| Upgrade existing | 3 | -| Build new | 13 | -| Keep as-is | 4 | -| Cross-domain refs | 6 | -| **Total marketing skills** | **39** | -| **New Python tools** | ~20 | -| **New reference docs** | ~25 | -| **New agents** | 5-8 | - ---- - -## Iteration 1: Foundation + Import (20 workspace skills + 2 new) - -### 1A: Create branch and foundation skills - -**marketing-context/** (NEW — the foundation every skill reads) -``` -marketing-context/ -├── SKILL.md # How to use, interview flow -├── templates/ -│ ├── brand-voice.md # Voice pillars, tone by content type, terminology -│ ├── style-guide.md # Grammar, formatting, capitalization -│ ├── target-keywords.md # Keyword clusters, search intent, current rankings -│ ├── internal-links-map.md # Key pages, anchor text, topic clusters -│ ├── competitor-analysis.md # Primary competitors, strategies, gaps -│ ├── writing-examples.md # 3-5 exemplary pieces with annotations -│ └── audience-personas.md # ICP, segments, pain points, buying triggers -└── scripts/ - └── context_validator.py # Validates completeness of context files -``` -Inspired by: SEO Machine's 8 context files + marketingskills' product-marketing-context -Key difference: Templates (user fills in), not static files. Validator script checks completeness. - -**marketing-ops/** (NEW — the router) -``` -marketing-ops/ -├── SKILL.md # Router logic, pod assignments, escalation -├── references/ -│ ├── routing-matrix.md # Trigger keywords → skill mapping (all 39 + 6 cross-domain) -│ ├── campaign-workflow.md # End-to-end campaign orchestration steps -│ └── quality-checklist.md # Pre-delivery quality gate (mirrors C-Suite standard) -└── scripts/ - └── campaign_tracker.py # Track campaign status, tasks, owners, deadlines -``` - -### 1B: Import 20 workspace skills - -For each imported skill: -1. Copy from `~/.openclaw/workspace/skills/{name}/` to `marketing-skill/{name}/` -2. Verify YAML frontmatter (name, description, license, metadata) -3. Add `## Related Skills` section with cross-references -4. Add `## Integration` table (which pod, which skills it works with, cross-domain refs) -5. Add `## Communication` section (references marketing quality standard) - -**Import batch (parallel — 4 subagents):** - -| Subagent | Skills | Pod | -|----------|--------|-----| -| content-importer | content-strategy, copywriting, copy-editing, social-content, marketing-ideas | Content | -| seo-cro-importer | seo-audit, programmatic-seo, page-cro, form-cro, signup-flow-cro | SEO + CRO | -| cro-channel-importer | onboarding-cro, popup-cro, paywall-upgrade-cro, email-sequence, paid-ads | CRO + Channels | -| growth-intel-importer | ab-test-setup, competitor-alternatives, marketing-psychology, launch-strategy, brand-guidelines | Growth + Intel + GTM | - -Each subagent: -- Copies skill folder -- Adds Related Skills section -- Adds Integration table -- Adds Communication standard reference -- Standardizes YAML frontmatter -- Does NOT add Python tools yet (that's Iteration 3) - -### 1C: Upgrade 3 existing skills - -| Skill | Changes | -|-------|---------| -| content-creator | Add context integration (reads marketing-context), Related Skills, Communication standard | -| social-media-analyzer → social-media-manager | Rename, expand SKILL.md from analyzer to full manager (scheduling, strategy, community) | -| campaign-analytics | Add cross-channel synthesis section, Related Skills, Communication standard | - -### 1D: Update CLAUDE.md + marketplace + skills-index - -- Rewrite `marketing-skill/CLAUDE.md` (like we did for C-Suite) -- Update `.claude-plugin/marketplace.json` -- Update `.codex/skills-index.json` -- Update root `CLAUDE.md` skill counts -- Update `README.md` badge + counts - -### Iteration 1 Deliverables -- [ ] Branch `feat/marketing-expansion` -- [ ] marketing-context/ (foundation) -- [ ] marketing-ops/ (router) -- [ ] 20 imported skills (standardized) -- [ ] 3 upgraded skills -- [ ] Updated CLAUDE.md, marketplace, skills-index -- [ ] PR opened - ---- - -## Iteration 2: Build 13 New Skills (parallel subagents) - -### 2A: Content + SEO batch (5 skills — 2 subagents) - -**Subagent: content-builder** -| Skill | Key Deliverables | -|-------|-----------------| -| content-production | SKILL.md, references/production-pipeline.md, references/content-brief-template.md, scripts/content_scorer.py (readability + SEO + humanity score), scripts/outline_generator.py | -| content-humanizer | SKILL.md, references/ai-patterns-checklist.md, references/voice-injection-guide.md, scripts/humanizer_scorer.py (detect AI patterns: em-dashes, filler, passive, hedging) | - -**Subagent: seo-builder** -| Skill | Key Deliverables | -|-------|-----------------| -| ai-seo | SKILL.md, references/aeo-guide.md (answer engine optimization), references/llm-citation-tactics.md, references/ai-search-landscape.md | -| schema-markup | SKILL.md, references/schema-types-guide.md, references/implementation-patterns.md, scripts/schema_validator.py (validates JSON-LD) | -| site-architecture | SKILL.md, references/url-structure-guide.md, references/internal-linking-strategy.md, scripts/sitemap_analyzer.py | - -### 2B: Channels + Growth batch (4 skills — 2 subagents) - -**Subagent: channels-builder** -| Skill | Key Deliverables | -|-------|-----------------| -| cold-email | SKILL.md, references/outreach-frameworks.md (AIDA, PAS, BAB), references/deliverability-guide.md, templates/sequence-templates.md, scripts/email_sequence_analyzer.py | -| ad-creative | SKILL.md, references/ad-frameworks.md (by platform), references/creative-testing-guide.md, scripts/headline_scorer.py, scripts/ad_copy_generator.py | - -**Subagent: growth-builder** -| Skill | Key Deliverables | -|-------|-----------------| -| referral-program | SKILL.md, references/referral-mechanics.md, references/program-types.md (one-sided, two-sided, tiered), scripts/referral_roi_calculator.py | -| free-tool-strategy | SKILL.md, references/tool-types.md (calculators, generators, analyzers, checkers), references/build-vs-buy.md, scripts/tool_roi_estimator.py | - -### 2C: Intelligence + Sales batch (4 skills — 2 subagents) - -**Subagent: intel-builder** -| Skill | Key Deliverables | -|-------|-----------------| -| analytics-tracking | SKILL.md, references/ga4-setup-guide.md, references/gtm-patterns.md, references/event-taxonomy.md, scripts/tracking_plan_generator.py | -| pricing-strategy | SKILL.md, references/pricing-models.md (value, cost-plus, competitor, dynamic), references/packaging-guide.md, scripts/pricing_modeler.py, scripts/willingness_to_pay_analyzer.py | - -**Subagent: (main agent handles directly)** -These are kept lean — no subagent needed: -- Update marketing-ops routing matrix with all 13 new skills -- Cross-reference all new skills with existing pods - -### Iteration 2 Deliverables -- [ ] 13 new skills built (SKILL.md + refs + scripts) -- [ ] All integrated into marketing-ops routing matrix -- [ ] All cross-referenced with Related Skills -- [ ] Commit + push - ---- - -## Iteration 3: Python Tools for Knowledge-Only Skills - -Add automation to the 20 imported workspace skills (currently zero scripts). - -### Priority 1: SEO + Content tools (highest impact) -| Skill | Script | Purpose | -|-------|--------|---------| -| seo-audit | seo_checker.py | On-page SEO scoring (0-100): title, meta, headings, links, keyword density | -| seo-audit | keyword_density_analyzer.py | Keyword distribution + stuffing detection | -| content-strategy | topic_cluster_mapper.py | Map topic clusters, identify gaps, suggest pillar content | -| copywriting | headline_scorer.py | Score headlines: power words, emotional triggers, length, clarity | -| copy-editing | readability_scorer.py | Flesch Reading Ease, grade level, passive voice, sentence complexity | - -### Priority 2: CRO tools -| Skill | Script | Purpose | -|-------|--------|---------| -| page-cro | conversion_audit.py | Above-fold analysis, CTA scoring, trust signals, friction points | -| form-cro | form_friction_analyzer.py | Field count, required fields, multi-step scoring | -| signup-flow-cro | signup_funnel_analyzer.py | Step analysis, drop-off estimation | - -### Priority 3: Channel + Growth tools -| Skill | Script | Purpose | -|-------|--------|---------| -| paid-ads | roas_calculator.py | ROAS, CPA, budget allocation optimizer | -| email-sequence | email_flow_designer.py | Sequence timing, open/click estimation | -| ab-test-setup | sample_size_calculator.py | Statistical significance, test duration estimator | -| competitor-alternatives | competitor_matrix_builder.py | Feature comparison matrix generator | - -### Priority 4: Intelligence tools -| Skill | Script | Purpose | -|-------|--------|---------| -| campaign-analytics | channel_mixer.py | Cross-channel attribution synthesis | -| marketing-psychology | persuasion_audit.py | Score content against Cialdini's 6 principles | -| launch-strategy | launch_readiness_scorer.py | Pre-launch checklist scoring | - -### Iteration 3 Deliverables -- [ ] ~18 new Python scripts (stdlib-only, CLI-first, JSON output) -- [ ] All scripts have embedded sample data for zero-config runs -- [ ] Commit + push - ---- - -## Iteration 4: Quality Upgrade (C-Suite Standard) - -Apply to ALL 39 marketing skills: - -### 4A: Add to every skill -- [ ] Proactive Triggers (5-6 context-driven alerts per skill) -- [ ] Output Artifacts table (request → deliverable mapping) -- [ ] Communication standard reference -- [ ] Quality loop integration (self-verify, peer-verify) - -### 4B: Add marketing-specific agents -| Agent | Location | Purpose | -|-------|----------|---------| -| content-analyzer | marketing-ops/agents/ | Analyzes content for SEO, readability, brand voice | -| seo-optimizer | marketing-ops/agents/ | On-page SEO recommendations | -| meta-creator | marketing-ops/agents/ | Meta title/description generation | -| headline-generator | marketing-ops/agents/ | Headline variations + scoring | -| cro-analyst | marketing-ops/agents/ | CRO audit for any page | - -Inspired by SEO Machine's 10 agents, but lean (markdown agents, not Python services). - -### 4C: Parity check -Run same audit as C-Suite: -- [ ] All 39 skills: Keywords ✅, QuickStart ✅, Related Skills ✅, Integration ✅, Proactive ✅, Outputs ✅, Communication ✅ -- [ ] All Python scripts: syntax valid, sample data works, JSON output -- [ ] All cross-references: bidirectional (A references B, B references A) -- [ ] Marketing-ops routing matrix: all 39 skills + 6 cross-domain - -### Iteration 4 Deliverables -- [ ] Quality loop on all 39 skills -- [ ] 5 marketing agents -- [ ] Parity check passed -- [ ] Final commit + PR merge-ready - ---- - -## Execution Timeline - -| Iteration | Work | Subagents | Est. Files | -|-----------|------|-----------|-----------| -| 1: Foundation + Import | 22 skills (2 new + 20 import) + 3 upgrades + metadata | 4 | ~80 | -| 2: New Skills | 13 new skills | 6 | ~100 | -| 3: Python Tools | ~18 scripts | 2-3 | ~18 | -| 4: Quality Upgrade | Quality loop + agents + parity | 2-3 | ~50 | -| **Total** | **39 skills** | **~15** | **~250** | - ---- - -## Success Criteria - -1. **39 marketing skills** organized into 7 pods + orchestration -2. **~38 Python tools** (18 existing + ~20 new), all stdlib-only -3. **5 marketing agents** (content-analyzer, seo-optimizer, meta-creator, headline-generator, cro-analyst) -4. **Full orchestration** via marketing-ops router with routing matrix -5. **Context foundation** that every skill reads (brand voice, style guide, keywords, etc.) -6. **Cross-domain routing** to 6 skills in business-growth, product-team, engineering-team -7. **C-Suite quality standard** on all skills (proactive triggers, output artifacts, quality loop) -8. **Full cross-referencing** between all skills (Related Skills sections) -9. **CMO integration** — marketing-ops connects to c-level-advisor/cmo-advisor/ -10. **Zero external dependencies** — all Python scripts stdlib-only - ---- - -*Ready for execution on Reza's go.* diff --git a/marketing-skill/MARKETING-EXPANSION-PLAN.md b/marketing-skill/MARKETING-EXPANSION-PLAN.md deleted file mode 100644 index ba12065e..00000000 --- a/marketing-skill/MARKETING-EXPANSION-PLAN.md +++ /dev/null @@ -1,396 +0,0 @@ -# Marketing Team Expansion — Audit & Implementation Plan - -## Executive Summary - -We have **27 marketing skills** spread across two locations (7 in repo, 20 in workspace), zero orchestration, zero automation on the workspace skills, and significant gaps vs. the two reference repos. This plan consolidates, upgrades, and fills gaps to build a **complete marketing division** — from research to production to analytics. - ---- - -## Part 1: Competitive Audit - -### Source Repo Analysis - -#### SEO Machine (TheCraigHewitt/seomachine) -- **Focus:** SEO-first content production pipeline -- **Strengths we lack:** - - 🔴 **Content production workflow** — `/research → /write → /optimize → /publish` pipeline (we have no production workflow) - - 🔴 **10 specialized agents** — content-analyzer, seo-optimizer, meta-creator, internal-linker, keyword-mapper, editor, performance, headline-generator, cro-analyst, landing-page-optimizer - - 🔴 **23 Python analysis modules** — search intent, keyword density, readability scoring, content length comparator, SEO quality rater, above-fold analyzer, CTA analyzer, trust signal analyzer, landing page scorer - - 🔴 **Data integrations** — GA4, Google Search Console, DataForSEO - - 🔴 **Context-driven system** — brand-voice.md, style-guide.md, writing-examples.md, target-keywords.md, internal-links-map.md, competitor-analysis.md, seo-guidelines.md, cro-best-practices.md - - 🔴 **Landing page system** — `/landing-write`, `/landing-audit`, `/landing-research`, `/landing-competitor`, `/landing-publish` - - 🟡 **WordPress publishing** — API integration with Yoast SEO (useful but platform-specific) - - 🟡 **AI watermark scrubber** — `/scrub` command to remove AI patterns -- **Weaknesses:** - - No orchestration layer (CMO-level strategy missing) - - No cross-channel coordination - - External dependencies (nltk, scikit-learn, beautifulsoup4) — violates our stdlib-only rule - - WordPress-coupled publishing - - No quality loop or verification - -#### Marketing Skills (coreyhaines31/marketingskills) -- **Focus:** Broad marketing skill coverage for SaaS -- **Strengths we lack:** - - 🔴 **product-marketing-context** as foundation — every skill reads it first (like our company-context.md) - - 🔴 **ai-seo** — AI search optimization (AEO, GEO, LLMO) — entirely new category - - 🔴 **site-architecture** — page hierarchy, navigation, URL structure, internal linking - - 🔴 **schema-markup** — structured data implementation - - 🔴 **cold-email** — B2B cold outreach emails and sequences - - 🔴 **ad-creative** — bulk ad creative generation and iteration - - 🔴 **churn-prevention** — cancel flows, save offers, dunning, payment recovery - - 🔴 **referral-program** — referral and affiliate programs - - 🔴 **pricing-strategy** — pricing, packaging, monetization - - 🔴 **revops** — lead lifecycle, scoring, routing, pipeline management - - 🔴 **sales-enablement** — sales decks, one-pagers, objection handling, demo scripts - - 🔴 **Cross-referencing system** — skills reference each other with Related Skills sections -- **Weaknesses:** - - Zero Python automation (knowledge-only, same as our workspace skills) - - No orchestration or routing - - No quality loop - - No agents - -### What We Have vs What They Have - -| Capability | Us (repo) | Us (workspace) | SEO Machine | Marketing Skills | -|-----------|-----------|----------------|-------------|-----------------| -| **CRO skills** | 0 | 6 (page, form, signup, onboard, popup, paywall) | 2 (cro-analyst, landing-page-optimizer) | 6 (same as ours) | -| **SEO skills** | 0 | 3 (seo-audit, programmatic-seo, competitor-alt) | Full stack (5 agents + 5 modules) | 5 (seo-audit, ai-seo, programmatic, schema, site-arch) | -| **Content/Copy** | 1 (content-creator) | 4 (content-strategy, copywriting, copy-editing, social-content) | Full pipeline (research→write→optimize→publish) | 3 (copywriting, copy-editing, cold-email) | -| **Email** | 0 | 1 (email-sequence) | 0 | 2 (email-sequence, cold-email) | -| **Paid/Ads** | 0 | 1 (paid-ads) | 0 | 2 (paid-ads, ad-creative) | -| **Analytics** | 1 (campaign-analytics) | 1 (ab-test-setup) | 3 (GA4, GSC, DataForSEO) | 1 (analytics-tracking) | -| **Strategy** | 2 (pmm, demand-acq) | 3 (content-strategy, launch-strategy, marketing-ideas) | Content prioritization | 4 (launch, pricing, marketing-ideas, marketing-psych) | -| **Growth/Retention** | 0 | 0 | 0 | 3 (referral, free-tool, churn-prevention) | -| **Sales/RevOps** | 0 | 0 | 0 | 2 (revops, sales-enablement) | -| **Python tools** | 18 scripts | 0 | 23 modules (external deps) | 0 | -| **Agents** | 0 | 0 | 10 | 0 | -| **Orchestration** | 0 | 0 | 0 | product-marketing-context (foundation only) | -| **Context system** | 0 | 0 | 8 context files | 1 (product-marketing-context) | -| **Production workflow** | 0 | 0 | Full (research→write→optimize→publish) | 0 | -| **Landing pages** | 0 | 0 | Full (5 commands) | 0 | - ---- - -## Part 2: Gap Analysis — What's Missing - -### 🔴 Critical Gaps (must build) - -1. **Orchestration layer** — no router, no coordination between 27 skills -2. **Content production pipeline** — no research→write→optimize→publish workflow -3. **SEO automation** — our seo-audit is knowledge-only, no analysis tools -4. **Landing page system** — no landing page creation or CRO analysis -5. **AI SEO (AEO/GEO/LLMO)** — entirely missing category, increasingly important -6. **Context system** — no brand-voice, style-guide, or product-marketing-context foundation -7. **Cross-referencing** — skills don't know about each other - -### 🟡 Important Gaps (should build) - -8. **Schema markup** — structured data implementation -9. **Site architecture** — URL structure, navigation, internal linking strategy -10. **Cold email / outreach** — B2B outreach sequences -11. **Ad creative** — bulk ad generation and iteration -12. **Churn prevention** — cancel flows, save offers, dunning -13. **Referral programs** — referral and affiliate program design -14. **Pricing strategy** — pricing, packaging, monetization -15. **RevOps** — lead lifecycle, scoring, routing -16. **Sales enablement** — sales decks, objection handling - -### ⚪ Nice to Have - -17. **WordPress/CMS publishing** — platform-specific, lower priority -18. **AI watermark scrubber** — content de-robotification -19. **Social media manager** — full management vs. current analyzer - ---- - -## Part 3: Architecture - -``` -CMO Advisor (C-Suite — strategy, budget, growth model) - │ - │ reads company-context.md + marketing-context.md - │ - Marketing Ops (router + orchestrator) - │ - ┌────┼────────┬──────────┬──────────┬──────────┬──────────┐ - │ │ │ │ │ │ │ - Content SEO CRO Channels Growth Intel Sales - Pod Pod Pod Pod Pod Pod Pod - (8) (5) (6) (5) (4) (4) (3) - -Total: 35 skills + 1 orchestration + 1 context foundation = 37 -``` - -### Pod Breakdown - -#### Context Foundation (1 skill — NEW) -| Skill | Status | Source | -|-------|--------|--------| -| **marketing-context** | 🆕 Build | Inspired by SEO Machine's context system + marketingskills' product-marketing-context | - -Creates and maintains: brand-voice.md, style-guide.md, target-keywords.md, internal-links-map.md, competitor-analysis.md, writing-examples.md. Every marketing skill reads this first. - -#### Orchestration (1 skill — NEW) -| Skill | Status | Source | -|-------|--------|--------| -| **marketing-ops** | 🆕 Build | Router + campaign orchestrator (like C-Suite Chief of Staff) | - -Routes questions, coordinates campaigns, enforces quality loop, connects to CMO above. - -#### Content Pod (8 skills — 5 existing + 3 new) -| Skill | Status | Source | -|-------|--------|--------| -| content-creator | ✅ Upgrade | Repo (add context integration, quality loop) | -| content-strategy | ✅ Import | Workspace | -| copywriting | ✅ Import | Workspace | -| copy-editing | ✅ Import | Workspace | -| social-content | ✅ Import | Workspace | -| marketing-ideas | ✅ Import | Workspace | -| **content-production** | 🆕 Build | Inspired by SEO Machine's /research→/write→/optimize pipeline | -| **content-humanizer** | 🆕 Build | Inspired by SEO Machine's editor agent + /scrub command | - -#### SEO Pod (5 skills — 2 existing + 3 new) -| Skill | Status | Source | -|-------|--------|--------| -| seo-audit | ✅ Import | Workspace (+ add Python tools) | -| programmatic-seo | ✅ Import | Workspace | -| **ai-seo** | 🆕 Build | From marketingskills (AEO, GEO, LLMO optimization) | -| **schema-markup** | 🆕 Build | From marketingskills (structured data) | -| **site-architecture** | 🆕 Build | From marketingskills (URL structure, nav, internal linking) | - -#### CRO Pod (6 skills — all existing) -| Skill | Status | Source | -|-------|--------|--------| -| page-cro | ✅ Import | Workspace | -| form-cro | ✅ Import | Workspace | -| signup-flow-cro | ✅ Import | Workspace | -| onboarding-cro | ✅ Import | Workspace | -| popup-cro | ✅ Import | Workspace | -| paywall-upgrade-cro | ✅ Import | Workspace | - -#### Channels Pod (5 skills — 3 existing + 2 new) -| Skill | Status | Source | -|-------|--------|--------| -| email-sequence | ✅ Import | Workspace | -| paid-ads | ✅ Import | Workspace | -| social-media-analyzer → social-media-manager | ✅ Upgrade | Repo (expand from analyzer to manager) | -| **cold-email** | 🆕 Build | From marketingskills (B2B outreach) | -| **ad-creative** | 🆕 Build | From marketingskills (bulk ad generation) | - -#### Growth & Retention Pod (4 skills — 1 existing + 3 new) -| Skill | Status | Source | -|-------|--------|--------| -| ab-test-setup | ✅ Import | Workspace | -| **churn-prevention** | 🆕 Build | From marketingskills (cancel flows, save offers, dunning) | -| **referral-program** | 🆕 Build | From marketingskills (referral + affiliate) | -| **free-tool-strategy** | 🆕 Build | From marketingskills (engineering as marketing) | - -#### Intelligence Pod (4 skills — 3 existing + 1 new) -| Skill | Status | Source | -|-------|--------|--------| -| campaign-analytics | ✅ Upgrade | Repo (add cross-channel synthesis) | -| competitor-alternatives | ✅ Import | Workspace | -| marketing-psychology | ✅ Import | Workspace | -| **analytics-tracking** | 🆕 Build | From marketingskills (GA4, GTM, event tracking setup) | - -#### Sales & GTM Pod (3 skills — 1 existing + 2 new) -| Skill | Status | Source | -|-------|--------|--------| -| launch-strategy | ✅ Import | Workspace | -| **pricing-strategy** | 🆕 Build | From marketingskills (pricing, packaging, monetization) | -| **sales-enablement** | 🆕 Build | From marketingskills (sales decks, objection handling) | - -### Also Import (not in pods) -| Skill | Status | -|-------|--------| -| brand-guidelines | ✅ Import (merge into marketing-context) | -| marketing-demand-acquisition | ✅ Keep in repo | -| marketing-strategy-pmm | ✅ Keep in repo | -| app-store-optimization | ✅ Keep in repo | -| prompt-engineer-toolkit | ✅ Keep in repo | - ---- - -## Part 4: Totals - -| Category | Existing (import/upgrade) | New (build) | Total | -|----------|--------------------------|-------------|-------| -| Context | 0 | 1 | 1 | -| Orchestration | 0 | 1 | 1 | -| Content | 5 + 1 upgrade | 2 | 8 | -| SEO | 2 | 3 | 5 | -| CRO | 6 | 0 | 6 | -| Channels | 2 + 1 upgrade | 2 | 5 | -| Growth | 1 | 3 | 4 | -| Intelligence | 2 + 1 upgrade | 1 | 4 | -| Sales & GTM | 1 | 2 | 3 | -| Standalone | 4 (keep as-is) | 0 | 4 | -| **TOTAL** | **24** | **15** | **41** | - ---- - -## Part 5: What Each New Skill Needs - -Every new skill gets the C-Suite quality standard: -- YAML frontmatter (name, description, license, metadata) -- Keywords section (trigger-optimized) -- Quick Start (3-step) -- Key Questions (diagnostic) -- Integration table (which skills it works with) -- Proactive Triggers (context-driven alerts) -- Output Artifacts (request → deliverable) -- Communication standard (bottom line first, structured output) -- Related Skills section (cross-references) -- Python tools (stdlib-only, CLI-first, JSON output) -- Reference docs (heavy content here, not SKILL.md) - ---- - -## Part 6: Python Tools Plan - -### Import SEO Machine concepts (rebuilt stdlib-only) -| Script | Original | Our version | -|--------|----------|-------------| -| search_intent_analyzer.py | Uses nltk | Regex + heuristic (stdlib) | -| keyword_analyzer.py | Uses scikit-learn | Counter + re (stdlib) | -| readability_scorer.py | Uses textstat | Flesch formula (stdlib, pure math) | -| seo_quality_rater.py | External deps | Checklist scorer (stdlib) | -| content_length_comparator.py | Web scraping | Input-based comparison (stdlib) | -| above_fold_analyzer.py | BeautifulSoup | html.parser (stdlib) | -| cta_analyzer.py | BeautifulSoup | html.parser (stdlib) | -| landing_page_scorer.py | External | Composite scorer (stdlib) | - -### New tools for existing skills -| Skill | New tool | Purpose | -|-------|----------|---------| -| seo-audit | seo_checker.py | On-page SEO scoring (0-100) | -| content-strategy | topic_cluster_mapper.py | Map topic clusters and gaps | -| copywriting | headline_scorer.py | Score headlines by power words, length, emotion | -| email-sequence | email_flow_designer.py | Design drip sequences with timing | -| paid-ads | roas_calculator.py | ROAS and budget allocation | -| campaign-analytics | channel_mixer.py | Cross-channel attribution synthesis | -| pricing-strategy | pricing_modeler.py | Price sensitivity and packaging optimizer | -| churn-prevention | churn_risk_scorer.py | Score churn signals | - ---- - -## Part 7: Execution Phases - -### Phase 1: Foundation + Import (batch 1) -**Goal:** Import 20 workspace skills, create context foundation, build orchestration -**Estimated:** ~80 files, 6 subagents -- Import all 20 workspace skills into `marketing-skill/` -- Add YAML frontmatter standardization where needed -- Create `marketing-context/` (context foundation) -- Create `marketing-ops/` (router/orchestrator) -- Add Related Skills cross-references to all imported skills -- Update CLAUDE.md - -### Phase 2: New Skills (batch 2) -**Goal:** Build 13 missing skills -**Estimated:** ~100 files, 6 subagents -- SEO: ai-seo, schema-markup, site-architecture -- Content: content-production, content-humanizer -- Channels: cold-email, ad-creative -- Growth: churn-prevention, referral-program, free-tool-strategy -- Intelligence: analytics-tracking -- Sales: pricing-strategy, sales-enablement - -### Phase 3: Python Tools (batch 3) -**Goal:** Add automation to knowledge-only skills -**Estimated:** ~20 scripts -- SEO analysis tools (search intent, keyword, readability, SEO quality) -- Content tools (headline scorer, topic mapper) -- CRO tools (above-fold, CTA, landing page scorer) -- Channel tools (ROAS calculator, email flow designer) -- Growth tools (churn risk scorer, pricing modeler) - -### Phase 4: Quality Upgrade (batch 4) -**Goal:** Apply C-Suite quality standard to all 37 skills -- Proactive triggers on all skills -- Output artifacts on all skills -- Integration tables on all skills -- Communication standard references -- Quality loop integration -- Final parity check - ---- - -## Part 8: Already Exists Elsewhere in Repo — DO NOT DUPLICATE - -Cross-repo audit found these "missing" capabilities already exist in other domains. The marketing team should **reference** them, not rebuild them. - -| "Missing" Capability | Already Exists At | What It Has | -|---------------------|-------------------|-------------| -| **Revenue Operations / RevOps** | `business-growth/revenue-operations/` | 3 Python tools: pipeline_analyzer, forecast_accuracy_tracker, gtm_efficiency_calculator | -| **Sales Enablement** | `business-growth/sales-engineer/` | 3 Python tools: rfp_response_analyzer, poc_planner, competitive_matrix_builder | -| **Churn Prevention** | `business-growth/customer-success-manager/` | 3 Python tools: churn_risk_analyzer, expansion_opportunity_scorer, health_score_calculator | -| **Landing Pages** | `product-team/landing-page-generator/` | Full Next.js/React landing page generation with copy frameworks, CRO patterns | -| **Competitive Analysis** | `product-team/competitive-teardown/` | Feature matrices, SWOT, positioning maps, UX audits | -| **Email Templates** | `engineering-team/email-template-builder/` | React Email, provider integration, i18n, dark mode, spam optimization | -| **Pricing Strategy** (partial) | `product-team/product-strategist/` | OKR cascade, product strategy (pricing is a component) | -| **Financial Analysis** | `finance/financial-analyst/` | DCF, ratios, budget variance, forecasting | -| **Contract/Proposal** | `business-growth/contract-and-proposal-writer/` | Proposal generation | -| **Stripe/Payments** | `engineering-team/stripe-integration-expert/` | Payment flows, subscription billing | - -### Impact on Plan - -**Remove from "new to build" list:** -- ~~revops~~ → already at `business-growth/revenue-operations/` -- ~~sales-enablement~~ → already at `business-growth/sales-engineer/` -- ~~churn-prevention~~ → already at `business-growth/customer-success-manager/` - -**Keep building (truly missing):** -- ✅ pricing-strategy (dedicated marketing pricing, not product strategy) -- ✅ cold-email (B2B outreach — distinct from email-sequence) -- ✅ ad-creative (bulk ad generation) -- ✅ referral-program (referral + affiliate programs) -- ✅ free-tool-strategy (engineering as marketing) -- ✅ ai-seo (AEO/GEO/LLMO — entirely new category) -- ✅ schema-markup (structured data) -- ✅ site-architecture (URL structure, nav, internal linking) -- ✅ content-production (research→write→optimize pipeline) -- ✅ content-humanizer (AI watermark removal, voice injection) -- ✅ analytics-tracking (GA4, GTM, event tracking setup) -- ✅ marketing-context (foundation — brand voice, style guide, etc.) -- ✅ marketing-ops (orchestration router) - -**Cross-reference in marketing-ops routing matrix:** -The marketing-ops router should know about and route to these business-growth/product-team skills when relevant, just like C-Suite's Chief of Staff routes across domains. - -### Revised Totals - -| Category | Existing (import/upgrade) | New (build) | Total | -|----------|--------------------------|-------------|-------| -| Context | 0 | 1 | 1 | -| Orchestration | 0 | 1 | 1 | -| Content | 5 + 1 upgrade | 2 | 8 | -| SEO | 2 | 3 | 5 | -| CRO | 6 | 0 | 6 | -| Channels | 2 + 1 upgrade | 2 | 5 | -| Growth | 1 | 2 (referral, free-tool) | 3 | -| Intelligence | 2 + 1 upgrade | 1 | 4 | -| Sales & GTM | 1 | 1 (pricing-strategy) | 2 | -| Standalone | 4 (keep as-is) | 0 | 4 | -| **TOTAL** | **24** | **13** | **39** | - -Down from 41 to 39 — removed 3 duplicates, cleaner architecture. - ---- - -## Part 9: Skills NOT Included (and why) - -| Skill | Source | Reason for exclusion | -|-------|--------|---------------------| -| WordPress publishing | SEO Machine | Platform-specific, not universal | -| DataForSEO integration | SEO Machine | Paid API, violates stdlib-only rule | -| GA4/GSC Python clients | SEO Machine | External deps (google-api-python-client) | -| revops | marketingskills | Already at `business-growth/revenue-operations/` | -| sales-enablement | marketingskills | Already at `business-growth/sales-engineer/` | -| churn-prevention | marketingskills | Already at `business-growth/customer-success-manager/` | -| product-marketing-context | marketingskills | Replaced by our marketing-context (richer) | - ---- - -*Created: 2026-03-06* -*Target: PR on `feat/marketing-expansion` branch* diff --git a/marketing-skill/README.md b/marketing-skill/README.md index b4e0595a..545ddaa0 100644 --- a/marketing-skill/README.md +++ b/marketing-skill/README.md @@ -39,22 +39,22 @@ npx ai-agent-skills install alirezarezvani/claude-skills/marketing-skill --agent ```bash # Content Creator -npx ai-agent-skills install alirezarezvani/claude-skills/marketing-skill/content-creator +npx ai-agent-skills install alirezarezvani/claude-skills/marketing-skill/skills/content-creator # Demand Generation & Acquisition -npx ai-agent-skills install alirezarezvani/claude-skills/marketing-skill/marketing-demand-acquisition +npx ai-agent-skills install alirezarezvani/claude-skills/marketing-skill/skills/marketing-demand-acquisition # Product Marketing Strategy -npx ai-agent-skills install alirezarezvani/claude-skills/marketing-skill/marketing-strategy-pmm +npx ai-agent-skills install alirezarezvani/claude-skills/marketing-skill/skills/marketing-strategy-pmm # App Store Optimization -npx ai-agent-skills install alirezarezvani/claude-skills/marketing-skill/app-store-optimization +npx ai-agent-skills install alirezarezvani/claude-skills/marketing-skill/skills/app-store-optimization # Social Media Analyzer -npx ai-agent-skills install alirezarezvani/claude-skills/marketing-skill/social-media-analyzer +npx ai-agent-skills install alirezarezvani/claude-skills/marketing-skill/skills/social-media-analyzer # Campaign Analytics -npx ai-agent-skills install alirezarezvani/claude-skills/marketing-skill/campaign-analytics +npx ai-agent-skills install alirezarezvani/claude-skills/marketing-skill/skills/campaign-analytics ``` **Supported Agents:** Claude Code, Cursor, VS Code, Copilot, Goose, Amp, Codex @@ -90,7 +90,7 @@ This marketing skills collection provides comprehensive marketing capabilities f ## 📦 Skills Catalog ### 1. Content Creator -**Package:** `content-creator.zip` | **Status:** ✅ Production Ready | **Version:** 1.0 +**Folder:** `skills/content-production/` | **Status:** ⚠️ Deprecated as standalone — use content-production | **Version:** 1.0 **Purpose:** Transform content creation with professional-grade brand voice analysis, SEO optimization, and platform-specific best practices. @@ -132,7 +132,7 @@ This marketing skills collection provides comprehensive marketing capabilities f --- ### 2. Marketing Demand & Acquisition -**Package:** `marketing-demand-acquisition.zip` | **Status:** ✅ Production Ready | **Version:** 1.0 +**Folder:** `skills/marketing-demand-acquisition/` | **Status:** ✅ Production Ready | **Version:** 1.1 **Purpose:** Expert demand generation, paid media, SEO, and partnerships for Series A+ startups scaling internationally. @@ -185,7 +185,7 @@ This marketing skills collection provides comprehensive marketing capabilities f --- ### 3. Marketing Strategy & Product Marketing -**Package:** `marketing-strategy-pmm.zip` | **Status:** ✅ Production Ready | **Version:** 1.0 +**Folder:** `skills/marketing-strategy-pmm/` | **Status:** ✅ Production Ready | **Version:** 1.0 **Purpose:** Product marketing, positioning, GTM strategy, and competitive intelligence for product launches and market expansion. diff --git a/marketing-skill/app-store-optimization.zip b/marketing-skill/app-store-optimization.zip deleted file mode 100644 index 6a076c58..00000000 Binary files a/marketing-skill/app-store-optimization.zip and /dev/null differ diff --git a/marketing-skill/content-creator.zip b/marketing-skill/content-creator.zip deleted file mode 100644 index a8786e1a..00000000 Binary files a/marketing-skill/content-creator.zip and /dev/null differ diff --git a/marketing-skill/marketing-demand-acquisition.zip b/marketing-skill/marketing-demand-acquisition.zip deleted file mode 100644 index b6d61bf1..00000000 Binary files a/marketing-skill/marketing-demand-acquisition.zip and /dev/null differ diff --git a/marketing-skill/marketing-strategy-pmm.zip b/marketing-skill/marketing-strategy-pmm.zip deleted file mode 100644 index 925e8efc..00000000 Binary files a/marketing-skill/marketing-strategy-pmm.zip and /dev/null differ diff --git a/marketing-skill/marketing_skills_roadmap.md b/marketing-skill/marketing_skills_roadmap.md deleted file mode 100644 index 8f7674b5..00000000 --- a/marketing-skill/marketing_skills_roadmap.md +++ /dev/null @@ -1,245 +0,0 @@ -# Marketing Team Skills Suite - Implementation Roadmap - -## Completed Skill: content-creator ✅ - -The **content-creator** skill is ready for deployment and includes: - -### Key Components -- **Brand Voice Analyzer**: Python tool to analyze and maintain consistent brand voice -- **SEO Optimizer**: Automated SEO scoring and optimization recommendations -- **Content Frameworks**: 15+ templates for different content types -- **Social Media Guidelines**: Platform-specific best practices and algorithms -- **Content Calendar Template**: Monthly planning and tracking system - -### How to Deploy -1. Download the `content-creator.zip` file -2. Extract to your team's shared drive or tool repository -3. Install Python dependencies: `pip install pyyaml` -4. Team members can use with Claude by uploading the skill -5. Run training session on brand voice establishment - -## Additional Skills to Create - -### 1. seo-optimizer (Priority: High) -**Purpose**: Deep SEO analysis and technical optimization -**Components**: -- Technical SEO audit scripts -- Schema markup generators -- Keyword research workflows -- Competitor analysis tools -- Link building strategies -- Core Web Vitals optimization - -### 2. social-media-manager (Priority: High) -**Purpose**: Social media campaign management and automation -**Components**: -- Platform API integrations -- Hashtag research tools -- Engagement tracking dashboards -- Influencer outreach templates -- Community management workflows -- Crisis response protocols - -### 3. campaign-analytics (Priority: High) ✅ DELIVERED -**Purpose**: Performance measurement and reporting -**Deployed**: February 2026 -**Components**: -- Multi-touch attribution analyzer (5 models: first/last/linear/time-decay/position-based) -- Funnel conversion analyzer with bottleneck detection -- Campaign ROI calculator with budget reallocation -- Attribution models reference guide -- Campaign benchmarks by channel and industry -- Executive report, campaign brief, and A/B test templates - -### 4. email-marketing (Priority: Medium) -**Purpose**: Email campaign creation and automation -**Components**: -- Email template library -- Segmentation strategies -- Automation workflow builders -- Deliverability checkers -- Subject line optimizers -- Performance tracking - -### 5. paid-ads-manager (Priority: Medium) -**Purpose**: PPC campaign optimization -**Components**: -- Google Ads scripts -- Facebook Ads templates -- Budget optimization tools -- Ad copy generators -- Landing page frameworks -- Performance trackers - -### 6. competitor-intelligence (Priority: Medium) -**Purpose**: Market and competitor analysis -**Components**: -- Competitor tracking scripts -- SWOT analysis templates -- Market trend analyzers -- Pricing strategy tools -- Content gap analysis -- Share of voice calculators - -### 7. conversion-optimizer (Priority: Low) -**Purpose**: CRO and landing page optimization -**Components**: -- A/B testing scripts -- Heatmap analysis guides -- Landing page templates -- Form optimization tools -- Cart abandonment strategies -- User journey mappers - -### 8. influencer-outreach (Priority: Low) -**Purpose**: Influencer marketing management -**Components**: -- Influencer database templates -- Outreach email templates -- Contract templates -- Campaign briefs -- Performance tracking -- ROI calculators - -## Implementation Strategy - -### Phase 1: Foundation (Weeks 1-2) -1. Deploy content-creator skill -2. Establish brand voice and guidelines -3. Train team on skill usage -4. Gather feedback for improvements - -### Phase 2: Core Expansion (Weeks 3-6) -1. Create seo-optimizer skill -2. Create social-media-manager skill -3. Create campaign-analytics skill -4. Integrate with existing tools - -### Phase 3: Enhancement (Weeks 7-10) -1. Create email-marketing skill -2. Create paid-ads-manager skill -3. Create competitor-intelligence skill -4. Optimize based on usage patterns - -### Phase 4: Advanced (Weeks 11-12) -1. Create conversion-optimizer skill -2. Create influencer-outreach skill -3. Create custom skills based on team needs -4. Document best practices - -## Best Practices for Skill Adoption - -### Training Approach -1. **Skill Champions**: Assign one team member per skill -2. **Weekly Workshops**: 30-minute skill training sessions -3. **Documentation**: Create internal wikis for each skill -4. **Feedback Loops**: Weekly optimization based on usage - -### Success Metrics -- Time saved per content piece: Target 40% reduction -- Content quality score: Target 85%+ consistency -- SEO performance: Target 30% improvement in 90 days -- Team adoption rate: Target 100% within 30 days - -### Integration Points -- **CMS Integration**: WordPress, HubSpot, Contentful -- **Analytics**: Google Analytics, Adobe Analytics -- **Social Tools**: Hootsuite, Buffer, Sprout Social -- **Email Platforms**: Mailchimp, SendGrid, Klaviyo -- **Design Tools**: Canva, Figma, Adobe Creative Suite - -## Recommended Tech Stack Integration - -### Core Marketing Stack -```yaml -Content Creation: - - Claude + Skills (AI-powered creation) - - Grammarly (writing assistance) - - Canva (visual design) - -SEO & Analytics: - - Semrush/Ahrefs (keyword research) - - Google Analytics 4 - - Google Search Console - -Social Media: - - Hootsuite/Buffer (scheduling) - - Later (visual planning) - - Sprout Social (analytics) - -Email Marketing: - - Mailchimp/Klaviyo - - Litmus (testing) - - SendGrid (delivery) - -Project Management: - - Jira (task tracking) - - Confluence (documentation) - - Slack (communication) -``` - -## ROI Projections - -### Time Savings -- Content Creation: 3 hours → 1.5 hours per piece -- SEO Optimization: 2 hours → 30 minutes per piece -- Social Media: 5 hours → 2 hours per week -- **Total Monthly Savings**: ~80 hours - -### Quality Improvements -- Brand Consistency: 60% → 95% -- SEO Scores: Average 65 → 85 -- Engagement Rates: +40% expected -- Conversion Rates: +25% expected - -### Cost Benefits -- Reduced outsourcing: -$5,000/month -- Increased productivity: +$8,000 value/month -- Better results: +$10,000 revenue/month -- **Total Monthly Impact**: +$23,000 - -## Next Steps - -1. **Immediate Actions**: - - Deploy content-creator skill to team - - Schedule training session (this week) - - Identify skill champions - -2. **Week 1 Goals**: - - Run brand voice workshop - - Create first content using skill - - Gather initial feedback - -3. **Month 1 Targets**: - - 100% team adoption - - 20+ pieces created with skills - - Measurable time savings documented - -4. **Quarter 1 Objectives**: - - All Phase 1-2 skills deployed - - 40% time reduction achieved - - ROI demonstrated - -## Support Resources - -### Training Materials -- Video tutorials for each skill -- Written documentation -- Example use cases -- Troubleshooting guides - -### Technical Support -- Slack channel: #marketing-skills -- Weekly office hours -- Skill improvement requests -- Bug reporting process - -### Continuous Improvement -- Monthly skill reviews -- Quarterly updates -- User feedback integration -- Performance optimization - ---- - -**Ready to transform your marketing operations?** Start with the content-creator skill and build from there. Each skill compounds the value of the others, creating a powerful, AI-enhanced marketing machine. diff --git a/marketing-skill/skills/ab-test-setup/SKILL.md b/marketing-skill/skills/ab-test-setup/SKILL.md index 7fd11737..ef1a05fa 100644 --- a/marketing-skill/skills/ab-test-setup/SKILL.md +++ b/marketing-skill/skills/ab-test-setup/SKILL.md @@ -82,16 +82,30 @@ We'll know this is true when [metrics]. ## Sample Size +### Calculate It (bundled tool) + +Use this skill's own calculator — don't eyeball it: + +```bash +python3 scripts/sample_size_calculator.py --baseline 0.05 --mde 0.20 # human-readable +python3 scripts/sample_size_calculator.py --baseline 0.05 --mde 0.20 --json # for pipelines +python3 scripts/sample_size_calculator.py --baseline 0.05 --mde 0.20 --daily-traffic 2000 # adds test-duration estimate +``` + +Paste `sample_size_per_variation` and the duration estimate directly into the test plan's "Sample size + duration" row before any test is approved to run. + ### Quick Reference +Generated by `sample_size_calculator.py` (two-proportion z-test, α=0.05 two-tailed, 80% power; relative MDE): + | Baseline | 10% Lift | 20% Lift | 50% Lift | |----------|----------|----------|----------| -| 1% | 150k/variant | 39k/variant | 6k/variant | -| 3% | 47k/variant | 12k/variant | 2k/variant | -| 5% | 27k/variant | 7k/variant | 1.2k/variant | -| 10% | 12k/variant | 3k/variant | 550/variant | +| 1% | 163k/variant | 43k/variant | 7.7k/variant | +| 3% | 53k/variant | 14k/variant | 2.5k/variant | +| 5% | 31k/variant | 8.2k/variant | 1.5k/variant | +| 10% | 15k/variant | 3.8k/variant | 683/variant | -**Calculators:** +**Cross-check calculators** (should agree with the script within rounding): - [Evan Miller's](https://www.evanmiller.org/ab-testing/sample-size.html) - [Optimizely's](https://www.optimizely.com/sample-size-calculator/) diff --git a/marketing-skill/skills/ad-creative/SKILL.md b/marketing-skill/skills/ad-creative/SKILL.md index 35c672ac..fb4f8eff 100644 --- a/marketing-skill/skills/ad-creative/SKILL.md +++ b/marketing-skill/skills/ad-creative/SKILL.md @@ -16,7 +16,7 @@ You are a performance creative director who has written thousands of ads. You kn ## Before Starting **Check for context first:** -If `marketing-context.md` exists, read it before asking questions. Use that context and only ask for information not already covered. +If `.claude/product-marketing-context.md` exists, read it before asking questions. Use that context and only ask for information not already covered. Gather this context (ask if not provided): @@ -80,7 +80,7 @@ You have a winning creative. Now multiply it for testing or for multiple audienc |----------|--------|---------------|-----------------|-------| | Google RSA | Search | 30 chars (×15) | 90 chars (×4 descriptions) | Max 3 pinned | | Google Display | Display | 30 chars (×5) | 90 chars (×5) | Also needs 5 images | -| Meta (Facebook/Instagram) | Feed/Story | 40 chars (primary) | 125 chars primary text | Image text <20% | +| Meta (Facebook/Instagram) | Feed/Story | 40 chars (primary) | 125 chars primary text | Minimal image text (best practice) | | LinkedIn | Sponsored Content | 70 chars headline | 150 chars intro text | No click-bait | | Twitter/X | Promoted | 70 chars | 280 chars total | No deceptive tactics | | TikTok | In-Feed | No overlay headline | 80–100 chars caption | Hook in first 3s | diff --git a/marketing-skill/skills/ad-creative/references/platform-specs.md b/marketing-skill/skills/ad-creative/references/platform-specs.md index e86ff0e6..d66a03cb 100644 --- a/marketing-skill/skills/ad-creative/references/platform-specs.md +++ b/marketing-skill/skills/ad-creative/references/platform-specs.md @@ -50,7 +50,7 @@ Full specifications for each major ad platform. Use this when generating or vali | Description | 30 chars | Optional, below headline | | Link description | 20 chars | URL preview | -**Image text rule:** Images with >20% text surface area get reduced distribution. Meta's tool at meta.com/ads/inspector/ checks this. Keep text minimal on images — put copy in the primary text field. +**Image text:** Meta's old ">20% text = reduced distribution" rule was retired in 2021 and is no longer enforced — but text-light images still tend to outperform text-heavy ones, so keep image text minimal as a best practice and put copy in the primary text field. ### Story / Reel Ads | Element | Limit | Notes | @@ -102,7 +102,7 @@ Full specifications for each major ad platform. Use this when generating or vali **LinkedIn-specific rules:** - No "Click here" as standalone CTA -- No images with more than 20% text +- Keep image text minimal — text-heavy creative underperforms in feed (best practice, not an enforced rejection rule) - No misleading job descriptions or recruitment bait - Avoid generic corporate language — LinkedIn users are saturated with it - B2B works better when you lead with a specific insight or stat, not a product pitch diff --git a/marketing-skill/skills/aeo/SKILL.md b/marketing-skill/skills/aeo/SKILL.md index 64e5b082..72912017 100644 --- a/marketing-skill/skills/aeo/SKILL.md +++ b/marketing-skill/skills/aeo/SKILL.md @@ -72,9 +72,21 @@ The tracker (`citation_tracker.py`) maintains a local ledger of citations: Stores in `~/.aeo-data/citations.json` (local, no telemetry). +## References + +- `references/aeo_eeat_canon.md` — E-E-A-T methodology, industry thresholds, anti-patterns +- `references/llm_citation_patterns.md` — per-LLM citation selection heuristics (Perplexity, ChatGPT, Claude, Gemini, Mistral) +- `references/aeo_vs_seo.md` — when to invest in AEO vs SEO vs both +- `references/bot_access_and_monitoring.md` — AI crawler robots.txt matrix (the prerequisite check: a blocked bot zeroes that platform), Google Search Console AI Overviews monitoring, manual testing protocols, citation-drop diagnostic (merged from the former `ai-seo` skill) +- `references/extractable_content_patterns.md` — 7 copy-ready block templates (definition, steps, table, FAQ, attributed stat, expert quote, summary box) that answer engines reliably extract (merged from the former `ai-seo` skill) + ## Workflow ``` +0. Pre-flight: bot access + Check robots.txt against the crawler matrix in references/bot_access_and_monitoring.md + → a blocked GPTBot/PerplexityBot/ClaudeBot/Google-Extended is the first fix, always + 1. Audit existing content $ python3 scripts/aeo_audit.py --url https://example.com/blog/post → markdown report with composite score + 4-dimension breakdown diff --git a/marketing-skill/skills/aeo/references/bot_access_and_monitoring.md b/marketing-skill/skills/aeo/references/bot_access_and_monitoring.md new file mode 100644 index 00000000..017c3f3f --- /dev/null +++ b/marketing-skill/skills/aeo/references/bot_access_and_monitoring.md @@ -0,0 +1,137 @@ +# Bot Access + AI Citation Monitoring + +This reference answers two operational decisions: **can AI crawlers reach your content at all**, and **how do you know when you're being cited (or losing citations)?** + +Bot access is the prerequisite for every other AEO investment — perfect E-E-A-T and schema mean nothing if the crawler is blocked. Monitoring closes the loop: AEO is non-deterministic, so you iterate on evidence, not assumptions. + +Folded in from the former `ai-seo` skill (merged into `aeo` 2026-06); landscape data last validated 2026-03 — verify platform behavior with manual testing before major decisions. + +--- + +## Part 1: Bot Access + +### The AI Crawler Matrix + +Check `yourdomain.com/robots.txt`. These bots must NOT be blocked for the corresponding platform to index or cite you: + +| Bot user-agent | Platform it feeds | Blocking it means | +|---|---|---| +| `GPTBot` | OpenAI / ChatGPT | No ChatGPT search citations | +| `PerplexityBot` | Perplexity | No Perplexity citations | +| `ClaudeBot` / `anthropic-ai` | Anthropic / Claude | No Claude browse citations | +| `Google-Extended` | Google AI Overviews + Gemini | No AI Overview / Gemini grounding | +| `Applebot-Extended` | Apple Intelligence | No Apple Intelligence answers | +| `cohere-ai` | Cohere | No Cohere-backed answers | +| (Bingbot) | ChatGPT search + Microsoft Copilot | Both use Bing's index — Bing indexing is a prerequisite | + +**robots.txt to allow all major AI bots:** + +``` +User-agent: GPTBot +Allow: / + +User-agent: PerplexityBot +Allow: / + +User-agent: ClaudeBot +Allow: / + +User-agent: Google-Extended +Allow: / +``` + +Notes: + +- Blocking training crawl ≠ blocking citation — for most platforms they are the same crawl. Selective `Disallow:` rules trade training exposure against citation visibility; there is no confirmed way to get one without the other. +- **A blocked AI bot is the single highest-priority AEO finding.** It zeroes visibility on that platform and is a 5-minute fix. Flag it before anything else. +- JavaScript-only content is effectively invisible to most AI crawlers — content that requires JS execution to render may never be extracted. + +### Indexing prerequisites per platform + +| Platform | Index used | Prerequisite | +|---|---|---| +| Google AI Overviews | Google's own index | You must rank in traditional Google search first — AI Overviews strongly prefer top-10 pages | +| ChatGPT (search) | Bing API + internal | Submit sitemap to Bing Webmaster Tools; verify with URL Inspection | +| Perplexity | Own crawler + Brave + Bing | Allow PerplexityBot; real-time retrieval rewards fresh content | +| Claude (browse) | Brave + direct fetch | Allow ClaudeBot; clean fetchable HTML | +| Microsoft Copilot | Bing | Same Bing requirements as ChatGPT | + +### Cross-platform signal summary + +| Signal | AI Overviews | ChatGPT | Perplexity | Claude | Copilot | +|---|---|---|---|---|---| +| Must rank in traditional search | Yes | Bing only | No | No | Bing only | +| Schema markup impact | High | Medium | Low-Medium | Medium | Medium | +| Content recency weight | High | Medium | Very high | Medium | Medium | +| Original data advantage | High | High | High | High | High | +| Author attribution impact | Medium | High | Low | High | Medium | + +(For per-LLM citation selection heuristics, see `llm_citation_patterns.md` — this table covers only access/weighting signals.) + +--- + +## Part 2: Monitoring + +The honest truth: AI citation monitoring is immature. There is no Search Console equivalent for Perplexity or ChatGPT. The reliable stack today is **Google Search Console (for AI Overviews) + weekly manual testing + the `citation_tracker.py` ledger in this skill**. + +### Google Search Console — AI Overviews (best current tooling) + +1. Search Console → Performance → Search results +2. Filter: "Search type" → "AI Overviews" +3. Date range: last 90 days minimum + +What to act on: + +- Sort by impressions → your current AI Overview presences +- Impressions growing + clicks dropping on a query → an AI Overview is answering it; you're cited but not visited (AI Overview CTR typically runs 50-70% below organic) +- Sharp impression drops → you likely lost an AI Overview slot; run the drop diagnostic below + +Frequency: weekly check; monthly CSV export for trends. + +### Manual testing protocol (Perplexity, ChatGPT, Copilot) + +Weekly, for your top 10-20 target queries, in a fresh/incognito session: + +1. Run the query on each platform +2. Check the sources panel / citations +3. Record: cited (yes/no), position among sources, which URL, top cited competitor + +Log results with this skill's `citation_tracker.py` (local ledger at `~/.aeo-data/citations.json`). Interpretation: + +- Cited 4/4 weeks → stable (protect the page; don't restructure it) +- Cited 2/4 weeks → fragile (strengthen extractability + authority signals) +- Never cited → gap (page lacks extractable patterns — see `extractable_content_patterns.md`) + +ChatGPT citations vary by session — treat them as probabilistic and test monthly, not weekly; the goal is appearing in the citation set, not every time. + +### Indirect traffic signals + +- **Referrals**: filter GA4 for `perplexity.ai`, `chat.openai.com`, `claude.ai`, `copilot.microsoft.com` — low volume, high intent +- **Direct-traffic anomalies** to deep content pages (not homepage) can signal AI-driven attention (users copy/paste cited URLs) + +### When citations drop — diagnostic order + +1. **robots.txt** — did someone block an AI bot? (Most common, fastest fix; recovery typically 1-4 weeks after unblocking) +2. **Page structure** — was the definition block, FAQ, or steps section removed in an edit? +3. **Competitor** — did someone publish a more extractable page on the same query? +4. **Page health** — noindex added, canonical changed, Core Web Vitals regressed? +5. **Authority** — significant backlink loss; check for manual actions in Search Console + +| Root cause | Fix | +|---|---| +| AI bot blocked | Restore robots.txt allow rules | +| Patterns removed | Restore definition/FAQ/steps blocks | +| Competitor outranked | Add specifics, original data, schema | +| Authority drop | Rebuild links; check manual penalties | +| Content stale | Refresh data with current year | + +--- + +## Citations (6 sources) + +1. Google Search Central — "AI features and your website" + Search Console AI Overviews reporting documentation (developers.google.com/search) +2. OpenAI — GPTBot documentation (platform.openai.com/docs/gptbot) +3. Perplexity — PerplexityBot crawler documentation (docs.perplexity.ai) +4. Anthropic — "Does Anthropic crawl data from the web?" ClaudeBot support documentation (support.anthropic.com) +5. Bing Webmaster Tools documentation — indexing and URL inspection (bing.com/webmasters) +6. Kevin Indig — "Growth Memo" analyses of AI Overviews CTR impact and zero-click behavior (growth-memo.com) diff --git a/marketing-skill/skills/ai-seo/references/content-patterns.md b/marketing-skill/skills/aeo/references/extractable_content_patterns.md similarity index 90% rename from marketing-skill/skills/ai-seo/references/content-patterns.md rename to marketing-skill/skills/aeo/references/extractable_content_patterns.md index c644fbf1..8d30340a 100644 --- a/marketing-skill/skills/ai-seo/references/content-patterns.md +++ b/marketing-skill/skills/aeo/references/extractable_content_patterns.md @@ -1,6 +1,6 @@ -# Content Patterns for AI Citability +# Extractable Content Patterns for AI Citability -Ready-to-use block templates for each content pattern that AI search engines reliably extract and cite. Copy, adapt, and embed in your pages. +Ready-to-use block templates for the content patterns answer engines reliably extract and cite. Folded in from the former `ai-seo` skill (merged into `aeo` 2026-06). Use these when `aeo_audit.py` flags low structure scores, and apply them via `aeo_optimizer.py` rewrite modes. --- @@ -274,3 +274,14 @@ The most citable pages combine multiple patterns throughout the piece: 7. Expert quote (to add authority) A page with all 7 patterns has significantly more extractable surface area than a page with prose only. The AI has more options to pull from and a higher probability of finding something that perfectly matches the query. + +--- + +## Citations (6 sources) + +1. Google Search Central — Featured snippets and structured data guidelines (developers.google.com/search) +2. Schema.org — FAQPage and HowTo type definitions (schema.org) +3. Backlinko (Brian Dean) — "Definitive Guide to Featured Snippets" extraction-format research +4. Baymard Institute — UX benchmarking methodology cited in the statistic-attribution example (baymard.com) +5. Nielsen Norman Group — "How People Read Online" scanning research underpinning self-contained blocks (nngroup.com) +6. Aggarwal et al. — "GEO: Generative Engine Optimization" (KDD 2024), empirical evidence that citations, statistics, and quotations increase LLM source visibility diff --git a/marketing-skill/skills/ai-seo/SKILL.md b/marketing-skill/skills/ai-seo/SKILL.md deleted file mode 100644 index 0dd96e9f..00000000 --- a/marketing-skill/skills/ai-seo/SKILL.md +++ /dev/null @@ -1,331 +0,0 @@ ---- -name: "ai-seo" -description: "Optimize content to get cited by AI search engines — ChatGPT, Perplexity, Google AI Overviews, Claude, Gemini, Copilot. Use when you want your content to appear in AI-generated answers, not just ranked in blue links. Triggers: 'optimize for AI search', 'get cited by ChatGPT', 'AI Overviews', 'Perplexity citations', 'AI SEO', 'generative search', 'LLM visibility', 'GEO' (generative engine optimization). NOT for traditional SEO ranking (use seo-audit). NOT for content creation (use content-production)." -license: MIT -metadata: - version: 1.0.0 - author: Alireza Rezvani - category: marketing - updated: 2026-03-06 ---- - -# AI SEO - -You are an expert in generative engine optimization (GEO) — the discipline of making content citeable by AI search platforms. Your goal is to help content get extracted, quoted, and cited by ChatGPT, Perplexity, Google AI Overviews, Claude, Gemini, and Microsoft Copilot. - -This is not traditional SEO. Traditional SEO gets you ranked. AI SEO gets you cited. Those are different games with different rules. - -## Before Starting - -**Check for context first:** -If `marketing-context.md` exists, read it. It contains existing keyword targets, content inventory, and competitor information — all of which inform where to start. - -Gather what you need: - -### What you need -- **URL or content to audit** — specific page, or a topic area to assess -- **Target queries** — what questions do you want AI systems to answer using your content? -- **Current visibility** — are you already appearing in any AI search results for your targets? -- **Content inventory** — do you have existing pieces to optimize, or are you starting from scratch? - -If the user doesn't know their target queries: "What questions would your ideal customer ask an AI assistant that you'd want your brand to answer?" - -## How This Skill Works - -Three modes. Each builds on the previous, but you can start anywhere: - -### Mode 1: AI Visibility Audit -Map your current presence (or absence) across AI search platforms. Understand what's getting cited, what's getting ignored, and why. - -### Mode 2: Content Optimization -Restructure and enhance content to match what AI systems extract. This is the execution mode — specific patterns, specific changes. - -### Mode 3: Monitoring -Set up systems to track AI citations over time — so you know when you appear, when you disappear, and when a competitor takes your spot. - ---- - -## How AI Search Works (and Why It's Different) - -Traditional SEO: Google ranks your page. User clicks through. You get traffic. - -AI search: The AI reads your page (or has already indexed it), extracts the answer, and presents it to the user — often without a click. You get cited, not ranked. - -**The fundamental shift:** -- Ranked = user sees your link and decides whether to click -- Cited = AI decides your content answers the question; user may never visit your site - -This changes everything: -- **Keyword density** matters less than **answer clarity** -- **Page authority** matters less than **answer extractability** -- **Click-through rate** is irrelevant — the AI has already decided you're the answer -- **Structured content** (definitions, lists, tables, steps) outperforms flowing narrative - -But here's what traditional SEO and AI SEO share: **authority still matters**. AI systems prefer sources they consider credible — established domains, cited works, expert authorship. You still need backlinks and domain trust. You just also need structure. - -See [references/ai-search-landscape.md](references/ai-search-landscape.md) for how each platform (Google AI Overviews, ChatGPT, Perplexity, Claude, Gemini, Copilot) selects and cites sources. - ---- - -## The 3 Pillars of AI Citability - -Every AI SEO decision flows from these three: - -### Pillar 1: Structure (Extractable) - -AI systems pull content in chunks. They don't read your whole article and then paraphrase it — they find the paragraph, list, or definition that directly answers the query and lift it. - -Your content needs to be structured so that answers are self-contained and extractable: -- Definition block for "what is X" -- Numbered steps for "how to do X" -- Comparison table for "X vs Y" -- FAQ block for "questions about X" -- Statistics with attribution for "data on X" - -Content that buries the answer in page 3 of a 4,000-word essay is not extractable. The AI won't find it. - -### Pillar 2: Authority (Citable) - -AI systems don't just pull the most relevant answer — they pull the most credible one. Authority signals in the AI era: - -- **Domain authority**: High-DA domains get preferential treatment (traditional SEO signal still applies) -- **Author attribution**: Named authors with credentials beat anonymous pages -- **Citation chain**: Your content cites credible sources → you're seen as credible in turn -- **Recency**: AI systems prefer current information for time-sensitive queries -- **Original data**: Pages with proprietary research, surveys, or studies get cited more — AI systems value unique data they can't get elsewhere - -### Pillar 3: Presence (Discoverable) - -AI systems need to be able to find and index your content. This is the technical layer: - -- **Bot access**: AI crawlers must be allowed in robots.txt (GPTBot, PerplexityBot, ClaudeBot, etc.) -- **Crawlability**: Fast page load, clean HTML, no JavaScript-only content -- **Schema markup**: Structured data (Article, FAQPage, HowTo, Product) helps AI systems understand your content type -- **Canonical signals**: Duplicate content confuses AI systems even more than traditional search -- **HTTPS and security**: AI crawlers won't index pages with security warnings - ---- - -## Mode 1: AI Visibility Audit - -### Step 1 — Bot Access Check - -First: confirm AI crawlers can access your site. - -**Check robots.txt** at `yourdomain.com/robots.txt`. Verify these bots are NOT blocked: - -``` -# Should NOT be blocked (allow AI indexing): -GPTBot # OpenAI / ChatGPT -PerplexityBot # Perplexity -ClaudeBot # Anthropic / Claude -Google-Extended # Google AI Overviews -anthropic-ai # Anthropic (alternate identifier) -Applebot-Extended # Apple Intelligence -cohere-ai # Cohere -``` - -If any AI bot is blocked, flag it. That's an immediate visibility killer for that platform. - -**robots.txt to allow all AI bots:** -``` -User-agent: GPTBot -Allow: / - -User-agent: PerplexityBot -Allow: / - -User-agent: ClaudeBot -Allow: / - -User-agent: Google-Extended -Allow: / -``` - -To block specific AI training while allowing search: use `Disallow:` selectively, but understand that blocking training ≠ blocking citation — they're often the same crawl. - -### Step 2 — Current Citation Audit - -Manually test your target queries on each platform: - -| Platform | How to test | -|---|---| -| Perplexity | Search your target query at perplexity.ai — check Sources panel | -| ChatGPT | Search with web browsing enabled — check citations | -| Google AI Overviews | Google your query — check if AI Overview appears, who's cited | -| Microsoft Copilot | Search at copilot.microsoft.com — check source cards | - -For each query, document: -- Are you cited? (yes/no) -- Which competitors are cited? -- What content type gets cited? (definition? list? stats?) -- How is the answer structured? - -This tells you the pattern that's currently winning. Build toward it. - -### Step 3 — Content Structure Audit - -Review your key pages against the Extractability Checklist: - -- [ ] Does the page have a clear, answerable definition of its core concept in the first 200 words? -- [ ] Are there numbered lists or step-by-step sections for process-oriented queries? -- [ ] Does the page have a FAQ section with direct Q&A pairs? -- [ ] Are statistics and data points cited with source name and year? -- [ ] Are comparisons done in table format (not narrative)? -- [ ] Is the page's H1 phrased as the answer to a question, or as a statement? -- [ ] Does schema markup exist? (FAQPage, HowTo, Article, etc.) - -Score: 0-3 checks = needs major restructuring. 4-5 = good baseline. 6-7 = strong. - ---- - -## Mode 2: Content Optimization - -### The Content Patterns That Get Cited - -These are the block types AI systems reliably extract. Add at least 2-3 per key page. - -See [references/content-patterns.md](references/content-patterns.md) for ready-to-use templates for each pattern. - -**Pattern 1: Definition Block** -The AI's answer to "what is X" almost always comes from a tight, self-contained definition. Format: - -> **[Term]** is [concise definition in 1-2 sentences]. [One sentence of context or why it matters]. - -Placed within the first 300 words of the page. No hedging, no preamble. Just the definition. - -**Pattern 2: Numbered Steps (How-To)** -For process queries ("how do I X"), AI systems pull numbered steps almost universally. Requirements: -- Steps are numbered -- Each step is actionable (verb-first) -- Each step is self-contained (could be quoted alone and still make sense) -- 5-10 steps maximum (AI truncates longer lists) - -**Pattern 3: Comparison Table** -"X vs Y" queries almost always result in table citations. Two-column tables comparing features, costs, pros/cons — these get extracted verbatim. Format matters: clean markdown table with headers wins. - -**Pattern 4: FAQ Block** -Explicit Q&A pairs signal to AI: "this is the question, this is the answer." Mark up with FAQPage schema. Questions should exactly match how people phrase queries (voice search, question-style). - -**Pattern 5: Statistics With Attribution** -"According to [Source Name] ([Year]), X% of [population] [finding]." This format is extractable because it has a complete citation. Naked statistics without attribution get deprioritized — the AI can't verify the source. - -**Pattern 6: Expert Quote Block** -Attributed quotes from named experts get cited. The AI picks up: "According to [Name], [Role at Organization]: '[quote]'" as a citable unit. Build in a few of these per key piece. - -### Rewriting for Extractability - -When optimizing existing content: - -1. **Lead with the answer** — The first paragraph should contain the core answer to the target query. Don't save it for the conclusion. - -2. **Self-contained sections** — Every H2 section should be answerable as a standalone excerpt. If you have to read the introduction to understand a section, it's not self-contained. - -3. **Specific over vague** — "Response time improved by 40%" beats "significant improvement." AI systems prefer citable specifics. - -4. **Plain language summaries** — After complex explanations, add a 1-2 sentence plain language summary. This is what AI often lifts. - -5. **Named sources** — Replace "experts say" with "[Researcher Name], [Year]." Replace "studies show" with "[Organization] found in their [Year] survey." - -### Schema Markup for AI Discoverability - -Schema doesn't directly make you appear in AI results — but it helps AI systems understand your content type and structure. Priority schemas: - -| Schema Type | Use When | Impact | -|---|---|---| -| `Article` | Any editorial content | Establishes content as authoritative information | -| `FAQPage` | You have FAQ section | High — AI extracts Q&A pairs directly | -| `HowTo` | Step-by-step guides | High — AI uses step structure for process queries | -| `Product` | Product pages | Medium — appears in product comparison queries | -| `Organization` | Company pages | Medium — establishes entity authority | -| `Person` | Author pages | Medium — author credibility signal | - -Implement via JSON-LD in the page `<head>`. Validate at schema.org/validator. - ---- - -## Mode 3: Monitoring - -AI search is volatile. Citations change. Track them. - -### Manual Citation Tracking - -Weekly: test your top 10 target queries on Perplexity and ChatGPT. Log: -- Were you cited? (yes/no) -- Rank in citations (1st source, 2nd, etc.) -- What text was used? - -This takes ~20 minutes/week. Do it before automated solutions exist (they don't yet, not reliably). - -### Google Search Console for AI Overviews - -Google Search Console now shows impressions in AI Overviews under "Search type: AI Overviews" filter. Check: -- Which queries trigger AI Overview impressions for your site -- Click-through rate from AI Overviews (typically 50-70% lower than organic) -- Which pages get cited - -### Visibility Signals to Track - -| Signal | Tool | Frequency | -|---|---|---| -| Perplexity citations | Manual query testing | Weekly | -| ChatGPT citations | Manual query testing | Weekly | -| Google AI Overviews | Google Search Console | Weekly | -| Copilot citations | Manual query testing | Monthly | -| AI bot crawl activity | Server logs or Cloudflare | Monthly | -| Competitor AI citations | Manual query testing | Monthly | - -See [references/monitoring-guide.md](references/monitoring-guide.md) for the full tracking setup and templates. - -### When Your Citations Drop - -If you were cited and suddenly aren't: -1. Check if competitors published something more extractable on the same topic -2. Check if your robots.txt changed (block AI bots = instant disappearance) -3. Check if your page structure changed significantly (restructuring can break citation patterns) -4. Check if your domain authority dropped (backlink loss affects AI citation too) - ---- - -## Proactive Triggers - -Flag these without being asked: - -- **AI bots blocked in robots.txt** — If GPTBot, PerplexityBot, or ClaudeBot are blocked, flag it immediately. Zero AI visibility is possible until fixed, and it's a 5-minute fix. This trumps everything else. -- **No definition block on target pages** — If the page targets informational queries but has no self-contained definition in the first 300 words, it won't win definitional AI Overviews. Flag before doing anything else. -- **Unattributed statistics** — If key pages contain statistics without named sources and years, they're less citable than competitor pages that do. Flag all naked stats. -- **Schema markup absent** — If the site has no FAQPage or HowTo schema on relevant pages, flag it as a quick structural win with asymmetric impact for process and FAQ queries. -- **JavaScript-rendered content** — If important content only appears after JavaScript execution, AI crawlers may not see it at all. Flag content that's hidden behind JS rendering. - ---- - -## Output Artifacts - -| When you ask for... | You get... | -|---|---| -| AI visibility audit | Platform-by-platform citation test results + robots.txt check + content structure scorecard | -| Page optimization | Rewritten page with definition block, extractable patterns, schema markup spec, and comparison to original | -| robots.txt fix | Updated robots.txt with correct AI bot allow rules + explanation of what each bot is | -| Schema markup | JSON-LD implementation code for FAQPage, HowTo, or Article — ready to paste | -| Monitoring setup | Weekly tracking template + Google Search Console filter guide + citation log spreadsheet structure | - ---- - -## Communication - -All output follows the structured standard: -- **Bottom line first** — answer before explanation -- **What + Why + How** — every finding includes all three -- **Actions have owners and deadlines** — no "consider reviewing..." -- **Confidence tagging** — 🟢 verified (confirmed by citation test) / 🟡 medium (pattern-based) / 🔴 assumed (extrapolated from limited data) - -AI SEO is still a young field. Be honest about confidence levels. What gets cited can change as platforms evolve. State what's proven vs. what's pattern-matching. - ---- - -## Related Skills - -- **content-production**: Use to create the underlying content before optimizing for AI citation. Good AI SEO requires good content first. -- **content-humanizer**: Use after writing for AI SEO. AI-sounding content ironically performs worse in AI citation — AI systems prefer content that reads credibly, which usually means human-sounding. -- **seo-audit**: Use for traditional search ranking optimization. Run both — AI SEO and traditional SEO are complementary, not competing. Many signals overlap. -- **content-strategy**: Use when deciding which topics and queries to target for AI visibility. Strategy first, then optimize. diff --git a/marketing-skill/skills/ai-seo/references/ai-search-landscape.md b/marketing-skill/skills/ai-seo/references/ai-search-landscape.md deleted file mode 100644 index 4fe376ad..00000000 --- a/marketing-skill/skills/ai-seo/references/ai-search-landscape.md +++ /dev/null @@ -1,191 +0,0 @@ -# AI Search Landscape - -How each major AI search platform selects, weights, and cites sources. Use this to calibrate your optimization strategy per platform. - -Last updated: 2026-03 — this landscape changes fast. Verify platform behavior with manual testing before making major decisions. - ---- - -## The Fundamental Model - -Every AI search platform follows the same broad pipeline: - -1. **Index** — Crawl and store web content (or use a third-party index) -2. **Retrieve** — For a given query, retrieve candidate documents -3. **Extract** — Pull the most relevant passages from those documents -4. **Generate** — Synthesize an answer, often citing the sources -5. **Present** — Show the answer to the user, with or without sources visible - -Your leverage points are steps 1-3. By the time generation happens, you've either been selected or you haven't. - ---- - -## Platform-by-Platform Breakdown - -### Google AI Overviews - -**What it is:** AI-generated answer boxes appearing above organic search results. Rollout expanded globally in 2024-2025. - -**How it selects sources:** -- Uses Google's own index (you must rank in traditional Google search first — this is NOT optional) -- Strongly prefers pages that already rank in the top 10 for the query -- Favors content with structured data (FAQPage, HowTo schemas) -- The featured passage is typically lifted from a page's most extractable paragraph — usually a definition or a direct answer near the top -- Recency matters more here than elsewhere for news-adjacent queries - -**Citation behavior:** -- Shows 3-7 source links typically -- Cited sources don't always correlate with position 1-3 in organic results -- Pages that had featured snippets before AI Overviews launched tend to appear in AI Overviews - -**What to prioritize for Google AI Overviews:** -1. Rank in traditional search first (prerequisite) -2. Add FAQPage schema -3. Put a direct answer in the first 200 words -4. Get backlinks from high-authority sites (still matters) -5. Set `Google-Extended` to Allow in robots.txt - -**Monitoring:** Google Search Console → Performance → Search type: AI Overviews - ---- - -### ChatGPT (with Browsing / Search) - -**What it is:** OpenAI's ChatGPT has web browsing capability (via Bing) plus its own live search product. When users ask factual questions or enable browsing, it retrieves and cites web sources. - -**How it selects sources:** -- Uses Bing's index (Microsoft partnership) — Bing crawl and indexing quality matters -- GPTBot also crawls independently for training data (distinct from search citations) -- For search-backed answers: pulls several sources, synthesizes, cites inline -- Prefers authoritative domains — news outlets, Wikipedia, academic sources, established company blogs -- Content with clear, extractable answers wins over dense narrative - -**Citation behavior:** -- Inline citations in the answer ("according to [Source]") -- Sources panel at the bottom -- Not all cited sources get equal weight in the synthesis - -**What to prioritize for ChatGPT:** -1. Ensure Bing has indexed your pages (submit to Bing Webmaster Tools) -2. Allow `GPTBot` in robots.txt -3. Structure content with explicit definition and step patterns -4. Author attribution with credentials helps — include author bylines -5. Original data and research get preferential citation - -**Bing indexing check:** Bing Webmaster Tools → URL Inspection - ---- - -### Perplexity - -**What it is:** AI-native search engine built on real-time web retrieval. Every answer cites sources with a numbered reference panel. Among the most transparent about citation. - -**How it selects sources:** -- Has its own crawler (PerplexityBot) plus access to third-party indexes -- Real-time retrieval for every query — very current -- Strongly rewards structural clarity: numbered lists, definition blocks, tables -- Tends to pull from multiple perspectives on a query (shows variety in citations) -- Recency bias is strong — old content competes poorly against recent content on current topics - -**Citation behavior:** -- Numbers every cited source -- Shows the exact passage it pulled from (if you inspect carefully) -- Citations appear inline and in a source panel - -**What to prioritize for Perplexity:** -1. Allow `PerplexityBot` in robots.txt (critical) -2. Use numbered lists, definition blocks, and tables extensively -3. Keep content current — update pages when information changes -4. For competitive topics, publish comprehensive pieces that cover the query more completely than alternatives -5. Include specific data with dates ("In Q1 2025, X% of...") — Perplexity responds strongly to timestamped specifics - -**Tracking:** Perplexity doesn't offer a publisher dashboard. Manual testing is the only method currently. - ---- - -### Claude (Anthropic) - -**What it is:** Claude.ai now has web search capability. When users ask questions that require current information, Claude retrieves and cites sources. - -**How it selects sources:** -- Uses a third-party search index (search partnership) -- ClaudeBot crawls for training purposes — separate from search citations -- Prefers clearly structured, credible content -- High-authority domains get preference -- Technical and expert-authored content performs well given Claude's user base - -**Citation behavior:** -- Inline citations in responses -- Source list at end of response -- Tends toward fewer, higher-quality citations vs. showing many sources - -**What to prioritize for Claude:** -1. Allow `ClaudeBot` and `anthropic-ai` in robots.txt -2. Focus on content quality and accuracy — Claude's users are often technical and will notice errors -3. Expert authorship and institutional credibility matter here -4. Long-form, well-researched pieces tend to perform better than thin listicles - ---- - -### Google Gemini - -**What it is:** Google's AI assistant, separate from Google Search but increasingly integrated. Uses Google's web index. - -**How it selects sources:** -- Full access to Google's index -- Similar selection criteria to Google AI Overviews but different interface -- Schema markup influences what Gemini can understand about your content type -- Prefers content that directly answers conversational queries - -**What to prioritize for Gemini:** -- Same fundamentals as Google AI Overviews (they share the index) -- Conversational phrasing in your content helps — Gemini handles voice/chat-style queries -- Allow `Google-Extended` in robots.txt (covers both AI Overviews and Gemini) - ---- - -### Microsoft Copilot - -**What it is:** Microsoft's AI assistant integrated into Bing, Windows, Office 365, and Edge. Uses Bing's index. - -**How it selects sources:** -- Bing index (same as ChatGPT browsing) -- Integrated into productivity contexts — Office documents, business queries -- B2B and professional content performs particularly well -- Bing's relevance signals apply - -**Citation behavior:** -- Source cards in the Copilot interface -- Inline citations in longer answers - -**What to prioritize for Copilot:** -- Ensure strong Bing indexing (submit to Bing Webmaster Tools, build Bing-friendly signals) -- For B2B companies: professional tone and industry-specific expertise matters more here -- FAQ and definition patterns work well for business query types - ---- - -## Cross-Platform Summary - -| Signal | Google AI Overviews | ChatGPT | Perplexity | Claude | Copilot | -|---|---|---|---|---|---| -| Must rank in traditional search | ✅ Yes | Bing only | No | No | Bing only | -| Bot to allow | Google-Extended | GPTBot | PerplexityBot | ClaudeBot | (via Bing) | -| Schema markup impact | High | Medium | Low | Medium | Medium | -| Content recency weight | High | Medium | Very high | Medium | Medium | -| Original data advantage | High | High | High | High | High | -| FAQ pattern extraction | Very high | High | High | Medium | High | -| Numbered steps extraction | High | High | Very high | High | High | -| Author attribution impact | Medium | High | Low | High | Medium | - ---- - -## What No Platform Does (Yet) - -Things that are widely assumed but not confirmed: - -- **Direct "opt-in to citations" programs**: None of the major platforms have a verified publisher program that guarantees citation -- **Predictable citation ranking**: Even with perfect structure, citations are non-deterministic — the same query on the same platform can produce different citations on consecutive days -- **Real-time citation tracking**: No platform offers publishers a dashboard showing when they're cited and for which queries (Google Search Console for AI Overviews is the closest, and it's limited) - -Plan your AI SEO strategy for influence, not for guaranteed outcomes. Maximize your signal quality, then track and iterate. diff --git a/marketing-skill/skills/ai-seo/references/monitoring-guide.md b/marketing-skill/skills/ai-seo/references/monitoring-guide.md deleted file mode 100644 index f0f69284..00000000 --- a/marketing-skill/skills/ai-seo/references/monitoring-guide.md +++ /dev/null @@ -1,208 +0,0 @@ -# AI Visibility Monitoring Guide - -How to track whether your content is getting cited by AI search engines — and what to do when citations change. - -The honest truth: AI citation monitoring is immature. There's no Google Search Console equivalent for Perplexity or ChatGPT. Most tracking is manual today. This guide covers what works now and what to watch for as tooling matures. - ---- - -## What You're Tracking - -**Goal:** Know when you appear in AI answers, for which queries, on which platforms — and detect changes before your traffic is affected. - -**The challenge:** Most AI search platforms don't give publishers visibility into their citation data. You're reverse-engineering your presence through manual testing and indirect signals. - -**Four things to track:** -1. Citation presence — are you appearing at all? -2. Citation consistency — do you appear most of the time or occasionally? -3. Competitor citations — who else is cited for your target queries? -4. Traffic signals — is AI-driven traffic changing? - ---- - -## Platform-by-Platform Monitoring - -### Google AI Overviews — Best Current Tooling - -Google Search Console is the best data source available for any AI platform: - -**Setup:** -1. Open Google Search Console → Performance → Search results -2. Add filter: "Search type" → "AI Overviews" -3. Set date range to last 90 days minimum - -**What you see:** -- Queries where your pages appeared in AI Overviews -- Impressions from AI Overviews -- Clicks from AI Overviews (usually much lower than organic — users get the answer in the AI box) -- CTR from AI Overviews - -**What to do with it:** -- Sort by impressions: these are your current AI Overview presences -- Sort by clicks: these are the queries where users still clicked through (high-value) -- Identify queries where you have impressions but zero clicks — consider whether that's acceptable or if you need to gate more value behind the click -- Watch for queries where impressions drop sharply — you may have lost an AI Overview position - -**Frequency:** Weekly check. Pull a CSV monthly for trend analysis. - ---- - -### Perplexity — Manual Testing Protocol - -Perplexity has no publisher dashboard. Manual testing is the only reliable method. - -**Weekly test protocol:** -1. Identify your 10-20 highest-priority target queries -2. Search each query on perplexity.ai in an incognito window -3. Check the Sources panel on the right side -4. Record: cited (yes/no), position in sources (1st, 2nd, 3rd...), which page was cited - -**What to record in your tracking log:** - -| Date | Query | Cited? | Position | Cited URL | Top Competitor | -|---|---|---|---|---|---| -| 2026-03-06 | "how to reduce SaaS churn" | Yes | 2 | /blog/churn-reduction | competitor.com | -| 2026-03-06 | "SaaS churn rate benchmark" | No | — | — | competitor.com | - -**Patterns to watch for:** -- Same query cited 4/4 weeks → stable citation (protect it) -- Citation appearing intermittently (2 out of 4 weeks) → fragile position (strengthen the page) -- Consistent non-citation → gap to fill (page missing extractable patterns) - -**Frequency:** Weekly for top 10 queries. Monthly for the full list. - ---- - -### ChatGPT — Manual Testing Protocol - -**Requirements:** ChatGPT Plus (for web browsing) or ChatGPT with Search enabled. - -**Test protocol:** -1. Start a new conversation (fresh context window) -2. Enable browsing / search mode -3. Ask your target query as a natural question -4. Check citations in the response -5. Click through to verify which pages are cited - -**Note:** ChatGPT citations vary by session. The same query may cite different sources on consecutive days. This is by design — treat it as probabilistic. Your goal is to appear in the citation set, not to appear every time. - -**What to test:** -- Exact keyword queries ("best email marketing software") -- Natural question queries ("what's the best email marketing software for small teams?") -- Comparison queries ("mailchimp vs klaviyo") - -**Frequency:** Monthly (due to variability, weekly is too noisy to be useful). - ---- - -### Microsoft Copilot — Manual Testing Protocol - -Access at copilot.microsoft.com or via Edge sidebar. - -Same protocol as ChatGPT. Look for source cards that appear with citations. Copilot integrates Bing's index, so if your Bing presence is strong, Copilot citations follow. - -**Bing indexing check:** -- Submit sitemap to Bing Webmaster Tools -- Run URL inspection to verify pages are indexed -- Check Bing Webmaster Tools for crawl errors on key pages - -**Frequency:** Monthly. - ---- - -## Traffic Analysis for AI Citation Signals - -Even without direct citation data, traffic patterns can signal AI search activity: - -### Zero-Click Traffic Signals - -When AI answers queries, fewer users click through. Watch for: - -**Impression growth + traffic decline:** If Google Search Console shows impressions growing for a keyword but organic clicks dropping, an AI Overview may be answering the query. You're being cited but not visited. - -**Query pattern in GSC:** If informational queries show impression growth but navigational/commercial queries stay flat, AI Overviews are likely answering the informational queries. - -### Direct Traffic Anomalies - -Some AI platforms (Claude, Gemini) show traffic as "direct" since users often copy/paste URLs rather than clicking. An increase in direct traffic to specific content pages (not your homepage) can signal AI-driven attention. - -### Referral Traffic from AI Platforms - -Perplexity, ChatGPT, and Claude all send some referral traffic when users click cited sources. Set up in Google Analytics 4: - -1. Create a custom dimension tracking referral source -2. Filter for: `perplexity.ai`, `chat.openai.com`, `claude.ai`, `copilot.microsoft.com` -3. Track monthly — expect low absolute numbers but high engagement (these visitors are already pre-qualified) - ---- - -## Tracking Template - -**Weekly AI Citation Tracker (copy this structure):** - -``` -Week of: [DATE] - -GOOGLE AI OVERVIEWS (from Search Console): -- New queries with AI Overview impressions: [list] -- Queries that dropped out: [list] -- Top performing query: [query] — [# impressions] impressions - -PERPLEXITY (manual tests): -Query: [query 1] → Cited: Y/N → Position: [#] → Competitor: [domain] -Query: [query 2] → Cited: Y/N → Position: [#] → Competitor: [domain] -Query: [query 3] → Cited: Y/N → Position: [#] → Competitor: [domain] - -NOTABLE CHANGES: -- [Describe any significant wins or losses] - -ACTIONS FROM LAST WEEK: -- [What we optimized] → [Result this week] - -ACTIONS FOR NEXT WEEK: -- [Page to optimize]: [Specific change to make] -``` - ---- - -## When Citations Drop - -### Immediate Diagnostic - -If you notice a citation you had has disappeared: - -1. **Check robots.txt** — Did someone accidentally block an AI crawler? Check `yourdomain.com/robots.txt` and test each bot. - -2. **Check the page itself** — Did the page structure change? Was the definition block moved? Was the FAQ section deleted in an edit? - -3. **Check competitor pages** — Did a competitor publish a more extractable version of the same content? Search the query and see who now appears. - -4. **Check page performance** — Is the page load slower? Did it get added to a noindex? Did canonical tags change? - -5. **Check domain authority signals** — Did you lose significant backlinks? Authority drops can affect AI citations on competitive queries. - -### Response Playbook - -| Root cause | Fix | -|---|---| -| AI bot blocked | Update robots.txt — typically resolves in 1-4 weeks | -| Page restructured (patterns removed) | Restore extractable patterns (definition block, FAQ, steps) | -| Competitor outranked you | Strengthen the page: more specific data, better structure, schema markup | -| Authority drop | Rebuild backlinks; also check for manual penalty in Google Search Console | -| Page went slow | Fix Core Web Vitals — AI crawlers deprioritize slow pages | -| Content became outdated | Update with current data and year | - ---- - -## Emerging Tools to Watch - -The AI citation monitoring space is early-stage. Tools being developed as of early 2026: - -- **Semrush AI toolkit** — Testing AI Overview tracking features -- **Ahrefs AI Overviews** — Added to their rank tracker -- **Perplexity publisher analytics** — Announced but not launched at time of writing -- **OpenAI publisher program** — Rumored; no confirmed release date - -Track announcements from these vendors. First-mover advantage on publisher analytics will be significant. - -**Until then:** Manual testing + Google Search Console is the most reliable stack available. Don't let perfect be the enemy of done — weekly manual testing surfaces 80% of what you need to know. diff --git a/marketing-skill/skills/analytics-tracking/SKILL.md b/marketing-skill/skills/analytics-tracking/SKILL.md index 2047e248..8841e92d 100644 --- a/marketing-skill/skills/analytics-tracking/SKILL.md +++ b/marketing-skill/skills/analytics-tracking/SKILL.md @@ -18,7 +18,7 @@ Bad tracking is worse than no tracking. Duplicate events, missing parameters, un ## Before Starting **Check for context first:** -If `marketing-context.md` exists, read it before asking questions. Use that context and only ask for what's missing. +If `.claude/product-marketing-context.md` exists, read it before asking questions. Use that context and only ask for what's missing. Gather this context: @@ -41,7 +41,17 @@ Gather this context: ## How This Skill Works ### Mode 1: Set Up From Scratch -No analytics in place — we'll build the tracking plan, implement GA4 and GTM, define the event taxonomy, and configure conversions. +No analytics in place — we'll build the tracking plan, implement GA4 and GTM, define the event taxonomy, and configure key events. + +Start from the generator, then customize: + +```bash +python3 scripts/tracking_plan_generator.py # embedded sample → full tracking plan +python3 scripts/tracking_plan_generator.py plan.json # your funnel definition +python3 scripts/tracking_plan_generator.py --json # parseable JSON for pipelines +``` + +Its output (event taxonomy + parameters + GA4/GTM config checklist) is the working draft for the Event Taxonomy Design section below — review every generated event name against the naming convention before implementing. ### Mode 2: Audit Existing Tracking Tracking exists but you don't trust the data, coverage is incomplete, or you're adding new goals. We'll audit what's there, gap-fill, and clean up. @@ -156,18 +166,18 @@ window.dataLayer.push({ }); ``` -### Conversions Configuration +### Key Events Configuration -Mark these events as conversions in GA4 → Admin → Conversions: +Mark these events as key events in GA4 → Admin → Key events (GA4 renamed "Conversions" to "Key events" in March 2024 — "conversions" now refers only to Google Ads conversion actions): - `signup_completed` - `checkout_completed` - `demo_requested` - `trial_started` (if separate from signup) **Rules:** -- Max 30 conversion events per property — curate, don't mark everything -- Conversions are retroactive in GA4 — turning one on applies to 6 months of history -- Don't mark micro-conversions as conversions unless you're optimizing ad campaigns for them +- Max 30 key events per property — curate, don't mark everything +- Key events are retroactive in GA4 — turning one on applies to 6 months of history +- Don't mark micro-conversions as key events unless you're also optimizing ad campaigns for them --- @@ -348,7 +358,7 @@ Surface these without being asked: | "Set up GTM" | Tag/trigger/variable configuration for each event, container setup checklist | | "Debug missing events" | Structured debugging steps using GTM Preview + GA4 DebugView + Network tab | | "Set up conversion tracking" | Conversion action configuration for GA4 + Google Ads + Meta | -| "Generate tracking plan" | Run `scripts/tracking_plan_generator.py` with your inputs | +| "Generate tracking plan" | Run `python3 scripts/tracking_plan_generator.py [plan.json] [--json]` — event taxonomy + GA4/GTM checklist | --- diff --git a/marketing-skill/skills/churn-prevention/SKILL.md b/marketing-skill/skills/churn-prevention/SKILL.md index 3b2622cd..4f7f687a 100644 --- a/marketing-skill/skills/churn-prevention/SKILL.md +++ b/marketing-skill/skills/churn-prevention/SKILL.md @@ -18,7 +18,7 @@ Churn is a revenue leak you can plug. A 20% save rate on voluntary churners and ## Before Starting **Check for context first:** -If `marketing-context.md` exists, read it before asking questions. Use that context and only ask for what's missing. +If `.claude/product-marketing-context.md` exists, read it before asking questions. Use that context and only ask for what's missing. Gather this context (ask if not provided): diff --git a/marketing-skill/skills/cold-email/SKILL.md b/marketing-skill/skills/cold-email/SKILL.md index 51735f1a..ed6b3b73 100644 --- a/marketing-skill/skills/cold-email/SKILL.md +++ b/marketing-skill/skills/cold-email/SKILL.md @@ -16,7 +16,7 @@ You are an expert in B2B cold email outreach. Your goal is to help write, build, ## Before Starting **Check for context first:** -If `marketing-context.md` exists, read it before asking questions. +If `.claude/product-marketing-context.md` exists, read it before asking questions. Gather this context: @@ -242,15 +242,25 @@ Surface these without being asked: --- +## Tools + +| Tool | Invocation | Output | +|---|---|---| +| Sequence analyzer | `python3 scripts/email_sequence_analyzer.py sequence.json` (no arg = embedded demo; `-` reads stdin) | Per-email 0-100 score across word count, reading level, personalization, CTA clarity, spam triggers, subject lines | + +Run it on every drafted sequence before delivering: any email scoring below 70 gets rewritten against the flagged dimensions (spam triggers and CTA clarity first), then re-scored. + +--- + ## Output Artifacts | When you ask for... | You get... | |---------------------|------------| | Write a cold email | First-touch email + 3 subject line variants + brief rationale for structure choices | -| Build a sequence | 5-6 email sequence with send gaps, subject lines per email, and angle summary for each follow-up | +| Build a sequence | 5-6 email sequence with send gaps, subject lines per email, and angle summary for each follow-up — scored with `email_sequence_analyzer.py` before delivery | | Critique my email | Line-by-line assessment + rewrite + explanation of each change | | Write follow-ups only | Follow-up emails 2-6 with unique angles per email + breakup email | -| Analyze sequence performance | Diagnosis of where the sequence breaks (subject/body/CTA) + specific rewrite recommendations | +| Analyze sequence performance | `email_sequence_analyzer.py` score report + diagnosis of where the sequence breaks (subject/body/CTA) + specific rewrite recommendations | --- diff --git a/marketing-skill/skills/competitor-alternatives/SKILL.md b/marketing-skill/skills/competitor-alternatives/SKILL.md index 6490e557..1080d4f8 100644 --- a/marketing-skill/skills/competitor-alternatives/SKILL.md +++ b/marketing-skill/skills/competitor-alternatives/SKILL.md @@ -263,6 +263,16 @@ Proactively offer competitor page creation when: --- +## Tools + +| Tool | Invocation | Output | +|---|---|---| +| Comparison matrix builder | `python3 scripts/comparison_matrix_builder.py --input competitors.json --markdown` (no input = embedded demo; `--json` for pipelines) | Feature-by-feature comparison matrix ready to paste into the vs-page comparison table | + +Feed it the Competitor Intelligence File data (features + pricing per competitor); its markdown output is the canonical comparison table for every Vs Page below — don't hand-build the table. + +--- + ## Output Artifacts | Artifact | Format | Description | diff --git a/marketing-skill/skills/content-humanizer/SKILL.md b/marketing-skill/skills/content-humanizer/SKILL.md index 2be46ee2..39347ae4 100644 --- a/marketing-skill/skills/content-humanizer/SKILL.md +++ b/marketing-skill/skills/content-humanizer/SKILL.md @@ -18,13 +18,13 @@ This is not a cleaning service. You're not just removing "delve" and calling it ## Before Starting **Check for context first:** -If `marketing-context.md` exists, read it. It contains brand voice guidelines, writing examples, and the specific tone this brand uses. That context is your voice blueprint. Use it — don't improvise a voice when the brief already defines one. +If `.claude/product-marketing-context.md` exists, read it. It contains brand voice guidelines, writing examples, and the specific tone this brand uses. That context is your voice blueprint. Use it — don't improvise a voice when the brief already defines one. Gather what you need before starting: ### What you need - **The content** — paste the draft to humanize -- **Brand voice notes** — if no `marketing-context.md`, ask: "Is your voice direct/casual/technical/irreverent? Give me one example of writing you love." +- **Brand voice notes** — if no `.claude/product-marketing-context.md`, ask: "Is your voice direct/casual/technical/irreverent? Give me one example of writing you love." - **Audience** — who reads this? (This changes what "human" sounds like) - **Goal** — what should this piece do? (Knowing the goal tells you how much personality is appropriate) @@ -51,7 +51,15 @@ Run all three in one pass when you have enough context. Split them when the clie Scan the content for these categories. Score severity: 🔴 critical (kills credibility) / 🟡 medium (softens impact) / 🟢 minor (polish only). -See [references/ai-tells-checklist.md](references/ai-tells-checklist.md) for the comprehensive detection list. +Start with the mechanical pass: + +```bash +python3 scripts/humanizer_scorer.py draft.md --json +``` + +It emits a 0-100 human-ness score. Interpretation: **80+** light polish only; **60-79** targeted pattern removal (Mode 2); **below 60** the AI fingerprint density is too high for a patch job — recommend a full rewrite, not an edit. Re-run after humanizing; the score must move. + +See [references/ai-tells-checklist.md](references/ai-tells-checklist.md) for the comprehensive detection list. Note: the tell vocabulary below is a snapshot — newer models have different tells, so check the checklist's "last validated" date and refresh it when auditing against current-generation output. ### The Core AI Tell Categories @@ -137,7 +145,7 @@ Every vague claim is an invitation to doubt. Replace: **Before:** "Many companies have seen significant improvements by implementing this strategy." -**After:** "HubSpot published their onboarding funnel data in 2023 — companies that hit their first-value moment within 7 days showed 40% higher 90-day retention. That's not a rounding error." +**After:** "[Named company] published their onboarding funnel data in [year] — companies that hit their first-value moment within 7 days showed 40% higher 90-day retention. That's not a rounding error." (Name a real, current source with its year — the structure is what matters: named source + dated data + specific number.) If you don't have specific data, be honest: "I haven't seen controlled studies on this, but in my experience working with SaaS onboarding flows, the pattern is consistent: earlier activation = higher retention." @@ -170,7 +178,7 @@ Humanizing removes AI. Voice injection makes it *yours*. ### Read the Voice Blueprint First -If `marketing-context.md` is available: read the brand voice section and writing examples. If not, ask for one example of content this brand loves. One. Then extract the patterns from it. +If `.claude/product-marketing-context.md` is available: read the brand voice section and writing examples. If not, ask for one example of content this brand loves. One. Then extract the patterns from it. **What to extract from a voice example:** - Sentence length preference (short punchy vs. longer flowing?) @@ -222,7 +230,7 @@ What changed: Flag these without being asked: - **AI fingerprint density too high** — If the piece has 10+ AI tells per 500 words, a patch job won't work. Flag that the piece needs a full rewrite, not an edit. Trying to polish a piece that's 80% AI patterns produces AI patterns with nicer words. -- **Voice context missing** — If `marketing-context.md` doesn't exist and the user hasn't given voice guidance, pause before injecting voice. Ask for one example. Guessing the voice and being wrong wastes everyone's time. +- **Voice context missing** — If `.claude/product-marketing-context.md` doesn't exist and the user hasn't given voice guidance, pause before injecting voice. Ask for one example. Guessing the voice and being wrong wastes everyone's time. - **Specificity gap** — If the piece makes 5+ vague claims with zero data or attribution, flag it to the user. You can make the prose flow better, but you can't invent specific proof. They need to provide it. - **Tone mismatch after humanizing** — If the piece is now genuinely human but sounds like a different brand than everything else the client publishes, flag it. Consistency matters as much as quality. - **Over-editing risk** — If the original content has one or two genuinely good paragraphs buried in the AI mush, flag them before rewriting. Don't accidentally destroy the good parts. @@ -258,4 +266,4 @@ When auditing: name the pattern → explain why it reads as AI → give the spec - **content-production**: Use to produce the initial draft. Run content-humanizer after drafting, before the SEO optimization pass. - **copywriting**: Use for conversion copy — landing pages, CTAs, headlines. content-humanizer works on longer-form pieces; copywriting handles short punchy copy with different principles. - **content-strategy**: Use when deciding what content to create. NOT for voice or draft execution. -- **ai-seo**: Use after humanizing, to optimize for AI search citation. Human-sounding content gets cited more — but it still needs structure to get extracted. +- **aeo**: Use after humanizing, to optimize for AI search citation. Human-sounding content gets cited more — but it still needs structure to get extracted. diff --git a/marketing-skill/skills/content-humanizer/references/ai-tells-checklist.md b/marketing-skill/skills/content-humanizer/references/ai-tells-checklist.md index 474095e6..32351313 100644 --- a/marketing-skill/skills/content-humanizer/references/ai-tells-checklist.md +++ b/marketing-skill/skills/content-humanizer/references/ai-tells-checklist.md @@ -2,6 +2,8 @@ A comprehensive reference for detecting AI-generated or AI-assisted writing patterns. Use this during Mode 1 (Detect) to audit content before editing. +**Last validated:** 2026-06 against then-current frontier models. AI-tell vocabularies age fast — the "delve"-era list below reflects 2023-2025 model output; newer models exhibit different tells. Re-validate this list every ~6 months against fresh model output and date the revision here. + Rate each finding: 🔴 Critical (rewrites required) / 🟡 Medium (edits needed) / 🟢 Minor (polish) --- diff --git a/marketing-skill/skills/content-production/SKILL.md b/marketing-skill/skills/content-production/SKILL.md index 858c9a09..5f81a556 100644 --- a/marketing-skill/skills/content-production/SKILL.md +++ b/marketing-skill/skills/content-production/SKILL.md @@ -18,7 +18,7 @@ This is the execution engine — not the strategy layer. You're here to build, n ## Before Starting **Check for context first:** -If `marketing-context.md` exists, read it before asking questions. It contains brand voice, target audience, keyword targets, and writing examples. Use what's there — only ask for what's missing. +If `.claude/product-marketing-context.md` exists, read it before asking questions. It contains brand voice, target audience, keyword targets, and writing examples. Use what's there — only ask for what's missing. Gather this context (ask in one shot, don't drip): @@ -143,10 +143,18 @@ Don't pad the conclusion. If it's done, it's done. ## Mode 3: Optimize & Polish -Draft exists. Run this in order. +Draft exists. Run this in order. Each pass has a bundled tool — run the tool first, then do the manual checks on what it can't see. ### SEO Pass +Run the optimizer first: + +```bash +python3 scripts/seo_optimizer.py draft.md --keyword "primary keyword" --secondary "secondary,phrases" +``` + +Fix what it flags, then verify manually: + - **Title tag**: Contains primary keyword, under 60 characters, curiosity-driving - **H1**: Different from title tag, keyword-rich, reads naturally - **H2s**: At least 2-3 contain secondary keywords or related phrases @@ -156,7 +164,7 @@ Draft exists. Run this in order. ### Readability Pass -Run `scripts/content_scorer.py` on the draft. Target score: 70+. +Run `python3 scripts/content_scorer.py draft.md --json` on the draft (emits a 0-100 score). Target score: 70+. Manual checks: - Average sentence length: aim for 15-20 words, mix it up @@ -164,6 +172,16 @@ Manual checks: - No jargon without explanation (for non-expert audiences) - Active voice: find passive constructions and flip them +### Brand Voice Pass + +Check the draft against the brand's voice profile (from `.claude/product-marketing-context.md`): + +```bash +python3 scripts/brand_voice_analyzer.py draft.md --format json +``` + +It reports tone markers, sentence-rhythm stats, and vocabulary fingerprint. Compare against the brand's established profile; rewrite sections that drift (e.g., formal drift in a casual brand). + ### Structure Audit - Does the intro deliver on the headline's promise? @@ -187,7 +205,13 @@ Write: ### Quality Gates — Don't Publish Until These Pass -See [references/optimization-checklist.md](references/optimization-checklist.md) for the full pre-publish checklist. +Run the gate checker — it enforces the non-negotiables mechanically: + +```bash +python3 scripts/content_quality_gates.py draft.md --json +``` + +A failing gate blocks publish; fix and re-run until clean. See [references/optimization-checklist.md](references/optimization-checklist.md) for the full pre-publish checklist. Core gates: - [ ] Primary keyword appears naturally 3-5x (not stuffed) @@ -240,6 +264,6 @@ When reviewing drafts: flag issues → explain impact → give specific fix. Don - **content-strategy**: Use when deciding *what* to write — topics, calendar, pillar structure. NOT for writing the actual piece (that's this skill). - **content-humanizer**: Use after drafting when the piece sounds robotic or AI-generated. Run this before the optimization pass. -- **ai-seo**: Use when optimizing specifically for AI search citation (ChatGPT, Perplexity, AI Overviews) in addition to traditional SEO. +- **aeo**: Use when optimizing specifically for AI search citation (ChatGPT, Perplexity, AI Overviews) in addition to traditional SEO. - **copywriting**: Use for landing pages, CTAs, and conversion copy. NOT for long-form content (that's this skill). - **seo-audit**: Use when auditing an existing content library for SEO gaps. NOT for single-piece production. diff --git a/marketing-skill/skills/content-production/references/optimization-checklist.md b/marketing-skill/skills/content-production/references/optimization-checklist.md index 01531893..7fa8d160 100644 --- a/marketing-skill/skills/content-production/references/optimization-checklist.md +++ b/marketing-skill/skills/content-production/references/optimization-checklist.md @@ -102,7 +102,7 @@ Run this before every piece goes live. Each section is a gate — fail a gate, f ## Gate 6: Brand & Voice -- [ ] Matches brand voice (check `marketing-context.md` if available) +- [ ] Matches brand voice (check `.claude/product-marketing-context.md` if available) - [ ] Consistent POV throughout (first person, second person, or third — pick one) - [ ] Consistent tense (present or past — don't mix) - [ ] No off-brand claims (anything that overpromises, contradicts other content, or sounds unlike us) diff --git a/marketing-skill/skills/content-strategy/SKILL.md b/marketing-skill/skills/content-strategy/SKILL.md index c3400c50..bda4a5b7 100644 --- a/marketing-skill/skills/content-strategy/SKILL.md +++ b/marketing-skill/skills/content-strategy/SKILL.md @@ -44,7 +44,26 @@ Gather this context (ask if not provided): --- ## Searchable vs Shareable -→ See references/content-strategy-reference.md for details + +The core classification decision for every topic: + +- **Searchable** — people already query this (keyword volume exists). Goal: rank and convert. Format: use-case pages, comparisons, how-tos, hub/spoke clusters. Judged by rankings + organic conversions over 6-12 months. +- **Shareable** — nobody searches it yet, but it spreads (original data, contrarian POV, strong narrative). Goal: reach + links + brand. Judged by distribution (shares, referral traffic, backlinks) in the first weeks. + +**Decision rule:** if the topic has meaningful search volume AND clear buyer intent → searchable (build it into a cluster). If it has no volume but a distribution hook → shareable (plan the launch channel before writing). If both → searchable structure with a shareable angle (best ROI). If neither → don't write it. + +Full treatment: references/content-strategy-reference.md + +## Topic Cluster Mapping (bundled tool) + +Once priority topics exist, group them mechanically: + +```bash +python3 scripts/topic_cluster_mapper.py --file keywords.txt # one topic/keyword per line +python3 scripts/topic_cluster_mapper.py --file keywords.txt --json # for pipelines +``` + +Its cluster output is the starting point for §3 Topic Cluster Map below — review cluster boundaries by intent (the tool groups lexically; you verify buyer-stage coherence). ## Output Format diff --git a/marketing-skill/skills/copy-editing/SKILL.md b/marketing-skill/skills/copy-editing/SKILL.md index 2e2f206c..4c754fb5 100644 --- a/marketing-skill/skills/copy-editing/SKILL.md +++ b/marketing-skill/skills/copy-editing/SKILL.md @@ -50,10 +50,11 @@ Edit copy through seven sequential passes, each focusing on one dimension. After - Burying the point in qualifications **Process:** -1. Read through quickly, highlighting unclear parts -2. Don't correct yet—just note problem areas -3. After marking issues, recommend specific edits -4. Verify edits maintain the original intent +1. Score the draft mechanically first: `python3 scripts/readability_scorer.py --file draft.md` (Flesch score, passive-voice %, filler-word count; add `--json` for pipelines). Anything it flags is your starting highlight list. +2. Read through quickly, highlighting unclear parts the scorer can't see +3. Don't correct yet—just note problem areas +4. After marking issues, recommend specific edits +5. Verify edits maintain the original intent — re-run the scorer; the Flesch score should improve, not regress **After this sweep:** Confirm the "Rule of One" (one main idea per section) and "You Rule" (copy speaks to the reader) are intact. @@ -264,6 +265,16 @@ For every statement, ask "Okay, so what?" If the copy doesn't answer that questi Use these for faster reviews when a full seven-sweep process isn't needed. +### AI-Pattern Check + +If the draft may be AI-generated (or AI-assisted), run the detector before editing: + +```bash +python3 scripts/ai_content_detector.py draft.md --json # no arg = --demo mode +``` + +It scores burstiness, vocabulary diversity, and stock-phrase density. A high AI-likelihood score means the piece needs **content-humanizer** treatment before copy editing — polishing AI mush produces polished AI mush. + ### Word-Level Checks **Cut these words:** diff --git a/marketing-skill/skills/copywriting/SKILL.md b/marketing-skill/skills/copywriting/SKILL.md index fa044eb6..cb6603bc 100644 --- a/marketing-skill/skills/copywriting/SKILL.md +++ b/marketing-skill/skills/copywriting/SKILL.md @@ -122,6 +122,15 @@ Puns and wit make copy memorable—but only if it fits the brand and doesn't und - "Never {unpleasant event} again" - "{Question highlighting main pain point}" +**Score every headline candidate** with the bundled scorer before picking one: + +```bash +python3 scripts/headline_scorer.py "Ship dashboards in minutes, not sprints" +python3 scripts/headline_scorer.py --file headlines.txt --json # batch-score a list +``` + +It rates 0-100 across 6 dimensions (length, specificity, power words, clarity, emotional pull, format). Write 5-10 candidates, score them all, present the top 2-3 with their scores and dimension breakdowns — never present a sub-60 headline as the primary recommendation. + **For comprehensive headline formulas**: See [references/copy-frameworks.md](references/copy-frameworks.md) **For natural transition phrases**: See [references/natural-transitions.md](references/natural-transitions.md) diff --git a/marketing-skill/skills/email-sequence/SKILL.md b/marketing-skill/skills/email-sequence/SKILL.md index 96a91a8c..aa6df3c3 100644 --- a/marketing-skill/skills/email-sequence/SKILL.md +++ b/marketing-skill/skills/email-sequence/SKILL.md @@ -74,6 +74,16 @@ What to measure and benchmarks --- +## Tools + +| Tool | Invocation | Output | +|---|---|---| +| Sequence analyzer | `python3 scripts/sequence_analyzer.py --file sequence.json` (no arg = embedded demo; `--json` for pipelines) | Sequence quality score 0-100: pacing, subject-line variety, CTA consistency, exit-condition coverage | + +Run it on the assembled sequence (export the per-email blocks above as a JSON array) before handing off: fix anything it flags below 70, then attach the final score to the Metrics Plan. + +--- + ## Task-Specific Questions 1. What triggers entry to this sequence? @@ -86,15 +96,15 @@ What to measure and benchmarks ## Tool Integrations -For implementation, see the [tools registry](../../tools/REGISTRY.md). Key email tools: +Key email tools: -| Tool | Best For | MCP | Guide | -|------|----------|:---:|-------| -| **Customer.io** | Behavior-based automation | - | [customer-io.md](../../tools/integrations/customer-io.md) | -| **Mailchimp** | SMB email marketing | ✓ | [mailchimp.md](../../tools/integrations/mailchimp.md) | -| **Resend** | Developer-friendly transactional | ✓ | [resend.md](../../tools/integrations/resend.md) | -| **SendGrid** | Transactional email at scale | - | [sendgrid.md](../../tools/integrations/sendgrid.md) | -| **Kit** | Creator/newsletter focused | - | [kit.md](../../tools/integrations/kit.md) | +| Tool | Best For | MCP | +|------|----------|:---:| +| **Customer.io** | Behavior-based automation | - | +| **Mailchimp** | SMB email marketing | ✓ | +| **Resend** | Developer-friendly transactional | ✓ | +| **SendGrid** | Transactional email at scale | - | +| **Kit** | Creator/newsletter focused | - | --- diff --git a/marketing-skill/skills/form-cro/SKILL.md b/marketing-skill/skills/form-cro/SKILL.md index cd62386f..bb41a434 100644 --- a/marketing-skill/skills/form-cro/SKILL.md +++ b/marketing-skill/skills/form-cro/SKILL.md @@ -43,7 +43,22 @@ Before providing recommendations, identify: --- ## Core Principles -→ See references/form-cro-playbook.md for details + +The thresholds that drive every form audit (full treatment in references/form-cro-playbook.md): + +- **Field count**: every added field costs conversions. Lead-gen forms: 3-5 fields is the working ceiling; 7+ required fields is a high-priority finding unless lead-qualification value is proven. +- **Required vs optional**: each *required* field must justify itself with a downstream use. "Nice for sales" is not a justification — make it optional or cut it. +- **High-friction fields**: phone number, company size, and address are the biggest abandonment drivers on top-of-funnel forms — demand justification or move them to step 2 / progressive profiling. +- **Error recovery**: inline validation on blur (not on submit), specific error copy ("Enter a work email" not "Invalid input"), never clear filled fields on error. +- **CTA**: value-specific button text ("Get my report") outperforms generic ("Submit"). + +## Tools + +| Tool | Invocation | Output | +|---|---|---| +| Field analyzer | `python3 scripts/form_field_analyzer.py forms.json` (no arg = embedded demo; `--json` for pipelines) | Per-form field count, required-field ratio, high-friction field flags, CTA assessment | + +Run it on the form definition first; its flags become the seed list for the Form Audit below — each flag gets an Issue/Impact/Fix/Priority entry. ## Output Format diff --git a/marketing-skill/skills/free-tool-strategy/SKILL.md b/marketing-skill/skills/free-tool-strategy/SKILL.md index 5466871e..5e95c310 100644 --- a/marketing-skill/skills/free-tool-strategy/SKILL.md +++ b/marketing-skill/skills/free-tool-strategy/SKILL.md @@ -16,7 +16,7 @@ You are a growth engineer who has built and launched free tools that generated h ## Before Starting **Check for context first:** -If `marketing-context.md` exists, read it before asking questions. Use that context and only ask for information not already covered. +If `.claude/product-marketing-context.md` exists, read it before asking questions. Use that context and only ask for information not already covered. Gather this context (ask if not provided): diff --git a/marketing-skill/skills/launch-strategy/SKILL.md b/marketing-skill/skills/launch-strategy/SKILL.md index 23951273..60b6cb76 100644 --- a/marketing-skill/skills/launch-strategy/SKILL.md +++ b/marketing-skill/skills/launch-strategy/SKILL.md @@ -21,7 +21,28 @@ If `.claude/product-marketing-context.md` exists, read it before asking question --- ## Core Philosophy -→ See references/launch-frameworks-and-checklists.md for details + +A launch is a momentum system, not a day. Two frameworks drive everything (full treatment in references/launch-frameworks-and-checklists.md): + +**ORB channel model** — map every launch action to one of three channel types: +- **Owned** — email list, blog, in-app. You control reach; activate first. +- **Rented** — social platforms, communities. Algorithmic reach; you play by their rules. +- **Borrowed** — partner audiences, newsletters, podcasts, Product Hunt. Other people's reach; requires relationship work weeks before launch day. + +A plan that covers only one channel type is incomplete — the quality bar is all three. + +**Phase model** — sequence the launch instead of betting on one day: +1. **Pre-launch** (2-6 weeks out): waitlist/early access, borrowed-channel outreach, asset production +2. **Launch day**: time-boxed checklist, all channels firing, founder availability for engagement +3. **Post-launch** (30 days): momentum content — comparison pages, case studies, roundup email, retargeting + +## Tools + +| Tool | Invocation | Output | +|---|---|---| +| Readiness scorer | `python3 scripts/launch_readiness_scorer.py --checklist launch.json` (no arg = embedded demo; `--export-template` writes a blank checklist; `--json` for pipelines) | 0-100 readiness score by category with the weakest categories called out | + +Gate the launch date on it: score the checklist when planning starts and again one week out — launching below a passing score in the "owned channels ready" or "assets ready" categories means slipping the date, not hoping. ## Task-Specific Questions diff --git a/marketing-skill/skills/marketing-context/SKILL.md b/marketing-skill/skills/marketing-context/SKILL.md index 9cc9ee3a..9d803af5 100644 --- a/marketing-skill/skills/marketing-context/SKILL.md +++ b/marketing-skill/skills/marketing-context/SKILL.md @@ -13,7 +13,9 @@ metadata: You are an expert product marketer. Your goal is to capture the foundational positioning, messaging, and brand context that every other marketing skill needs — so users never repeat themselves. -The document is stored at `.agents/marketing-context.md` (or `marketing-context.md` in the project root). +The document is stored at `.claude/product-marketing-context.md` — the canonical path every marketing skill in this library reads. Always write to this path. + +> **Backward compatibility:** if you previously created `.agents/marketing-context.md` or a root-level `marketing-context.md`, move it to `.claude/product-marketing-context.md` so sibling skills can find it. ## How This Skill Works @@ -123,6 +125,18 @@ See `templates/marketing-context-template.md` for the full template. --- +## Validate the Result + +After writing (or updating) the context file, score its completeness: + +```bash +python3 scripts/context_validator.py .claude/product-marketing-context.md --json +``` + +It emits a 0-100 completeness score from required + optional section coverage. Below 70: go back to the interview and fill the missing sections before declaring the context "done" — sibling skills will silently degrade on an incomplete file. Re-run it during the freshness audit too. + +--- + ## Tips - **Be specific**: Ask "What's the #1 frustration that brings them to you?" not "What problem do they solve?" @@ -147,7 +161,7 @@ Surface these without being asked: | When you ask for... | You get... | |---------------------|------------| -| "Set up marketing context" | Guided interview → complete `marketing-context.md` | +| "Set up marketing context" | Guided interview → complete `.claude/product-marketing-context.md` | | "Auto-draft from codebase" | Codebase scan → V1 draft for review | | "Update positioning" | Targeted update of differentiation + competitive sections | | "Add customer quotes" | Customer language section populated with verbatim phrases | diff --git a/marketing-skill/skills/marketing-demand-acquisition/SKILL.md b/marketing-skill/skills/marketing-demand-acquisition/SKILL.md index 07ab9db6..d954f56f 100644 --- a/marketing-skill/skills/marketing-demand-acquisition/SKILL.md +++ b/marketing-skill/skills/marketing-demand-acquisition/SKILL.md @@ -1,6 +1,6 @@ --- name: "marketing-demand-acquisition" -description: Creates demand generation campaigns, optimizes paid ad spend across LinkedIn, Google, and Meta, develops SEO strategies, and structures partnership programs for Series A+ startups scaling internationally. Use when planning marketing strategy, growth marketing, advertising campaigns, PPC optimization, lead generation, pipeline generation, or startup 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 for hybrid PLG/Sales-Led motions in EU/US/Canada markets. +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) — adapt benchmarks for other stages and motions rather than skipping the skill. triggers: - demand gen - demand generation @@ -22,7 +22,7 @@ metadata: author: Alireza Rezvani category: marketing domain: demand-generation - updated: 2025-01 + updated: 2026-06 --- # Marketing Demand & Acquisition @@ -78,7 +78,7 @@ Acquisition playbook for Series A+ startups scaling internationally (EU/US/Canad ``` utm_source={channel} // linkedin, google, meta utm_medium={type} // cpc, display, email -utm_campaign={campaign-id} // q1-2025-linkedin-enterprise +utm_campaign={campaign-id} // {qN-yyyy}-linkedin-enterprise utm_content={variant} // ad-a, email-1 utm_term={keyword} // [paid search only] ``` @@ -239,7 +239,7 @@ See [attribution-guide.md](references/attribution-guide.md) for detailed setup. | Script | Purpose | Usage | |--------|---------|-------| -| `calculate_cac.py` | Calculate blended and channel CAC | `python scripts/calculate_cac.py --spend 40000 --customers 50` | +| `calculate_cac.py` | Calculate blended and channel CAC | `python scripts/calculate_cac.py` (no args — edit the `example_data` channel table in `main()` with your spend/customer numbers first) | ### HubSpot Integration diff --git a/marketing-skill/skills/marketing-demand-acquisition/scripts/calculate_cac.py b/marketing-skill/skills/marketing-demand-acquisition/scripts/calculate_cac.py index 82ee7a82..ae708ae0 100644 --- a/marketing-skill/skills/marketing-demand-acquisition/scripts/calculate_cac.py +++ b/marketing-skill/skills/marketing-demand-acquisition/scripts/calculate_cac.py @@ -6,6 +6,7 @@ Calculate blended and channel-specific CAC for marketing campaigns. Supports multiple time periods and channel breakdowns. """ +import argparse import sys from typing import Dict, List @@ -73,6 +74,8 @@ def print_results(results: Dict): print() def main(): + # TODO: accept channel data via --file <json> or stdin so the tool can be + # automated without hand-editing this list (known limitation). # Example data - replace with your actual numbers example_data = [ {'channel': 'LinkedIn Ads', 'spend': 15000, 'customers': 10}, @@ -98,4 +101,12 @@ def main(): print("Blended Target: <$300") if __name__ == "__main__": + parser = argparse.ArgumentParser( + description="Calculate blended and channel-specific CAC.", + formatter_class=argparse.RawDescriptionHelpFormatter, + epilog="Current limitation: channel data is the `example_data` list in " + "main() — edit it with your spend/customer numbers, then run with " + "no args. CLI input (--file <json> / stdin) is a planned " + "enhancement; until then this tool is not scriptable.") + parser.parse_args() main() diff --git a/marketing-skill/skills/marketing-ops/SKILL.md b/marketing-skill/skills/marketing-ops/SKILL.md index 7e9aa06d..e4a7a180 100644 --- a/marketing-skill/skills/marketing-ops/SKILL.md +++ b/marketing-skill/skills/marketing-ops/SKILL.md @@ -16,7 +16,7 @@ You are a senior marketing operations leader. Your goal is to route marketing qu ## Before Starting **Check for marketing context first:** -If `marketing-context.md` exists, read it. If it doesn't, recommend running the **marketing-context** skill first — everything works better with context. +If `.claude/product-marketing-context.md` exists, read it. If it doesn't, recommend running the **marketing-context** skill first — everything works better with context. ## How This Skill Works @@ -47,8 +47,8 @@ User wants to assess their marketing → you run a cross-functional audit touchi ### SEO Pod | Trigger | Route to | NOT this | |---------|----------|----------| -| "SEO audit," "technical SEO," "on-page SEO" | **seo-audit** | Not ai-seo (that's for AI search engines) | -| "AI search," "ChatGPT visibility," "Perplexity," "AEO" | **ai-seo** | Not seo-audit (that's traditional SEO) | +| "SEO audit," "technical SEO," "on-page SEO" | **seo-audit** | Not aeo (that's for AI answer engines) | +| "AI search," "ChatGPT visibility," "Perplexity," "AEO" | **aeo** | Not seo-audit (that's traditional SEO) | | "Schema markup," "structured data," "JSON-LD," "rich snippets" | **schema-markup** | | | "Site structure," "URL structure," "navigation," "sitemap" | **site-architecture** | | | "Programmatic SEO," "pages at scale," "template pages" | **programmatic-seo** | | @@ -71,6 +71,11 @@ User wants to assess their marketing → you run a cross-functional audit touchi | "Paid ads," "Google Ads," "Meta ads," "ad campaign" | **paid-ads** | Not ad-creative (that's for copy generation) | | "Ad copy," "ad headlines," "ad variations," "RSA" | **ad-creative** | Not paid-ads (that's for strategy) | | "Social media strategy," "social calendar," "community" | **social-media-manager** | Not social-content (that's for individual posts) | +| "X growth," "Twitter growth," "grow my X account" | **x-twitter-growth** | Not social-content (that's cross-platform posts) | +| "YouTube," "video SEO," "channel strategy," "thumbnails" | **youtube-full** | Not video-content-strategist (that's platform-agnostic strategy) | +| "Video strategy," "short-form video," "video content plan" | **video-content-strategist** (sibling folder `video-content-strategist/`) | Not youtube-full (that's YouTube-specific + API-backed) | +| "Webinar," "webinar funnel," "registration rate," "show-up rate" | **webinar-marketing** | | +| "App Store," "Play Store," "ASO," "app keywords" | **app-store-optimization** | Not seo-audit (that's web search) | ### Growth Pod | Trigger | Route to | NOT this | @@ -87,12 +92,17 @@ User wants to assess their marketing → you run a cross-functional audit touchi | "Set up tracking," "GA4," "GTM," "event tracking" | **analytics-tracking** | Not campaign-analytics (that's for analysis) | | "Competitor page," "vs page," "alternative page" | **competitor-alternatives** | | | "Psychology," "persuasion," "behavioral science" | **marketing-psychology** | | +| "Analyze my social accounts," "engagement rate," "social audit" | **social-media-analyzer** | Not social-media-manager (that's planning, not analysis) | +| "Marketing prompts," "prompt templates," "LLM governance for marketing" | **prompt-engineer-toolkit** | | ### Sales & GTM Pod | Trigger | Route to | NOT this | |---------|----------|----------| | "Product launch," "feature announcement," "Product Hunt" | **launch-strategy** | | | "Pricing," "how much to charge," "pricing tiers" | **pricing-strategy** | | +| "Positioning," "ICP," "product marketing," "messaging framework" | **marketing-strategy-pmm** | Not copywriting (that's execution) | +| "Demand gen," "lead gen program," "MQL/SQL funnel," "CRM campaigns" | **marketing-demand-acquisition** | Not paid-ads (that's one channel) | +| "Brand guidelines," "brand consistency," "style guide audit" | **brand-guidelines** | Not marketing-context (that's the foundation doc) | ### Cross-Domain (route outside marketing-skill/) | Trigger | Route to | Domain | @@ -107,6 +117,14 @@ User wants to assess their marketing → you run a cross-functional audit touchi --- +## Tools + +| Tool | Invocation | Output | +|---|---|---| +| Campaign tracker | `python3 scripts/campaign_tracker.py campaign.json` (no arg = embedded sample; add `--json` for machine-readable) | Per-task status, owners, deadlines, overdue flags across the skills involved in a campaign | + +Use it during orchestration: after laying out a campaign sequence (below), capture each step as a task in a campaign JSON and run the tracker at every check-in — the overdue/ownerless flags feed the Quality Gate ("actions have owners and deadlines"). + ## Campaign Orchestration For multi-skill campaigns, follow this sequence: diff --git a/marketing-skill/skills/marketing-ops/scripts/campaign_tracker.py b/marketing-skill/skills/marketing-ops/scripts/campaign_tracker.py index e99edf2d..f29fa931 100644 --- a/marketing-skill/skills/marketing-ops/scripts/campaign_tracker.py +++ b/marketing-skill/skills/marketing-ops/scripts/campaign_tracker.py @@ -45,7 +45,7 @@ def analyze_campaign(campaign: dict) -> dict: pods_covered = set() pod_map = { "content": ["content-strategy", "copywriting", "copy-editing", "social-content", "marketing-ideas", "content-production", "content-humanizer", "content-creator"], - "seo": ["seo-audit", "programmatic-seo", "ai-seo", "schema-markup", "site-architecture"], + "seo": ["seo-audit", "programmatic-seo", "aeo", "schema-markup", "site-architecture"], "cro": ["page-cro", "form-cro", "signup-flow-cro", "onboarding-cro", "popup-cro", "paywall-upgrade-cro"], "channels": ["email-sequence", "cold-email", "paid-ads", "ad-creative", "social-media-manager"], "growth": ["ab-test-setup", "referral-program", "free-tool-strategy", "churn-prevention"], diff --git a/marketing-skill/skills/marketing-psychology/SKILL.md b/marketing-skill/skills/marketing-psychology/SKILL.md index 92af2dda..c7bf222f 100644 --- a/marketing-skill/skills/marketing-psychology/SKILL.md +++ b/marketing-skill/skills/marketing-psychology/SKILL.md @@ -16,7 +16,7 @@ You are an expert in applied behavioral science for marketing. Your job is to id ## Before Starting **Check for marketing context first:** -If `marketing-context.md` exists, read it for audience personas and product positioning. Psychology works better when you know the audience. +If `.claude/product-marketing-context.md` exists, read it for audience personas and product positioning. Psychology works better when you know the audience. ## How This Skill Works diff --git a/marketing-skill/skills/marketing-skills/SKILL.md b/marketing-skill/skills/marketing-skills/SKILL.md index ed77e953..ac73b166 100644 --- a/marketing-skill/skills/marketing-skills/SKILL.md +++ b/marketing-skill/skills/marketing-skills/SKILL.md @@ -1,105 +1,121 @@ --- name: "marketing-skills" -description: "42 marketing agent skills and plugins for Claude Code, Codex, Gemini CLI, Cursor, OpenClaw, and 6 more coding agents. 7 pods: content, SEO, CRO, channels, growth, intelligence, sales. Foundation context + orchestration router. 27 Python tools (stdlib-only)." -version: 2.9.0 +description: "Directory and router for the marketing skills library. Use when you need to find the right marketing skill for a task, see what marketing capabilities exist, or get oriented in this plugin. 44 specialist skills across 8 pods (content, SEO + AEO, CRO, channels, growth, intelligence, sales enablement, ops), 59 stdlib Python tools. Routes to one skill — it does not execute marketing work itself." +version: 2.10.3 author: Alireza Rezvani license: MIT tags: - marketing - - seo - - content - - copywriting - - cro - - analytics - - ai-seo + - router + - index agents: - claude-code - codex-cli - openclaw --- -# Marketing Skills Division +# Marketing Skills — Directory + Router -42 production-ready marketing skills organized into 7 specialist pods with a context foundation and orchestration layer. +This is the index skill for the marketing plugin. It does one job: route you to the right specialist skill, then get out of the way. For request-by-request routing logic, [../marketing-ops/SKILL.md](../marketing-ops/SKILL.md) is the canonical router — this file is the map. -## Quick Start +**Counts (kept honest):** 44 specialist skills in `skills/` (plus this index and the deprecated `content-creator` redirect), 1 video skill in `video-content-strategist/`, 59 stdlib-only Python tools. No pip installs needed. -### Claude Code -``` -/read marketing-skill/marketing-ops/SKILL.md -``` -The router will direct you to the right specialist skill. +## Start Here -### Codex CLI -```bash -codex --full-auto "Read marketing-skill/marketing-ops/SKILL.md, then help me write a blog post about [topic]" -``` +1. **First run ever?** Use `skills/marketing-context/` to create `.claude/product-marketing-context.md`. Every other skill reads it for brand voice, personas, and competitive landscape. +2. **Know your task?** Find it in the route table below and load only that skill's `SKILL.md`. +3. **Ambiguous request?** Load `skills/marketing-ops/` — its routing matrix maps phrasings to skills. -### OpenClaw -Skills are auto-discovered from the repository. Ask your agent for marketing help — it routes via `marketing-ops`. +## Route Table -## Architecture +All paths are relative to `marketing-skill/`. -``` -marketing-skill/ -├── marketing-context/ ← Foundation: brand voice, audience, goals -├── marketing-ops/ ← Router: dispatches to the right skill -│ -├── Content Pod (8) ← Strategy → Production → Editing → Social -├── SEO Pod (5) ← Traditional + AI SEO + Schema + Architecture -├── CRO Pod (6) ← Pages, Forms, Signup, Onboarding, Popups, Paywall -├── Channels Pod (5) ← Email, Ads, Cold Email, Ad Creative, Social Mgmt -├── Growth Pod (4) ← A/B Testing, Referrals, Free Tools, Churn -├── Intelligence Pod (4) ← Competitors, Psychology, Analytics, Campaigns -└── Sales & GTM Pod (2) ← Pricing, Launch Strategy -``` +### Foundation + Ops +| Task | Skill | +|---|---| +| Capture brand/product context (run first) | `skills/marketing-context/` | +| Route a request, plan campaigns, pick channels | `skills/marketing-ops/` | +| Demand gen programs, funnel + CRM ops | `skills/marketing-demand-acquisition/` | +| Positioning, ICP, product marketing strategy | `skills/marketing-strategy-pmm/` | +| Brand voice/visual consistency audits | `skills/brand-guidelines/` | -## First-Time Setup +### Content +| Task | Skill | +|---|---| +| Write blog posts, articles, guides | `skills/content-production/` | +| Plan what content to create | `skills/content-strategy/` | +| Edit copy (Seven Sweeps) | `skills/copy-editing/` | +| Fix AI-sounding content | `skills/content-humanizer/` | +| Landing/sales page copy | `skills/copywriting/` | +| Headlines, hooks, idea generation | `skills/marketing-ideas/` | +| Persuasion frameworks, mental models | `skills/marketing-psychology/` | -Run `marketing-context` to create your `marketing-context.md` file. Every other skill reads this for brand voice, audience personas, and competitive landscape. Do this once — it makes everything better. +### SEO + AEO +| Task | Skill | +|---|---| +| Traditional SEO audit | `skills/seo-audit/` | +| AI search citations (ChatGPT, Perplexity, AI Overviews) | `skills/aeo/` | +| Programmatic SEO at scale | `skills/programmatic-seo/` | +| Structured data / schema.org | `skills/schema-markup/` | +| Site structure, internal linking | `skills/site-architecture/` | -## Pod Overview +### CRO (conversion) +| Task | Skill | +|---|---| +| Landing/marketing page conversion | `skills/page-cro/` | +| Forms | `skills/form-cro/` | +| Signup flow | `skills/signup-flow-cro/` | +| Onboarding/activation | `skills/onboarding-cro/` | +| Popups/modals | `skills/popup-cro/` | +| Paywall/upgrade screens | `skills/paywall-upgrade-cro/` | +| A/B test design + sample size | `skills/ab-test-setup/` | -| Pod | Skills | Python Tools | Key Capabilities | -|-----|--------|-------------|-----------------| -| **Foundation** | 2 | 2 | Brand context capture, skill routing | -| **Content** | 8 | 5 | Strategy → production → editing → humanization | -| **SEO** | 5 | 2 | Technical SEO, AI SEO (AEO/GEO), schema, architecture | -| **CRO** | 6 | 0 | Page, form, signup, onboarding, popup, paywall optimization | -| **Channels** | 5 | 2 | Email sequences, paid ads, cold email, ad creative | -| **Growth** | 4 | 2 | A/B testing, referral programs, free tools, churn prevention | -| **Intelligence** | 4 | 4 | Competitor analysis, marketing psychology, analytics, campaigns | -| **Sales & GTM** | 2 | 1 | Pricing strategy, launch planning | -| **Standalone** | 4 | 9 | ASO, brand guidelines, PMM strategy, prompt engineering | +### Channels +| Task | Skill | +|---|---| +| Email sequences/drips | `skills/email-sequence/` | +| Cold outbound email | `skills/cold-email/` | +| Paid ads (Google/Meta/LinkedIn) | `skills/paid-ads/` | +| Ad creative + copy | `skills/ad-creative/` | +| Social calendar + management | `skills/social-media-manager/` | +| Platform-native social posts | `skills/social-content/` | +| X/Twitter growth | `skills/x-twitter-growth/` | +| YouTube (data + strategy) | `skills/youtube-full/` | +| Video content strategy | `video-content-strategist/` (sibling folder, own plugin) | +| Webinars (funnel math) | `skills/webinar-marketing/` | +| App Store / Play Store (ASO) | `skills/app-store-optimization/` | -## Python Tools (27 scripts) +### Growth +| Task | Skill | +|---|---| +| Launches (PH, HN, etc.) | `skills/launch-strategy/` | +| Pricing + packaging | `skills/pricing-strategy/` | +| Referral programs | `skills/referral-program/` | +| Free tools as acquisition | `skills/free-tool-strategy/` | +| Churn prevention | `skills/churn-prevention/` | -All scripts are stdlib-only (zero pip installs), CLI-first with JSON output, and include embedded sample data for demo mode. +### Intelligence + Sales Enablement +| Task | Skill | +|---|---| +| Campaign performance, attribution | `skills/campaign-analytics/` | +| Tracking plans, UTM, GA4 key events | `skills/analytics-tracking/` | +| Social account analysis | `skills/social-media-analyzer/` | +| Competitor/alternatives pages | `skills/competitor-alternatives/` | +| LLM prompt templates + governance for marketing teams | `skills/prompt-engineer-toolkit/` | + +## Python Tools + +Each skill documents its own tools in its SKILL.md (a "Tools" or workflow section with exact CLI lines). Invoke from the skill's folder: ```bash -# Content scoring -python3 marketing-skill/content-production/scripts/content_scorer.py article.md - -# AI writing detection -python3 marketing-skill/content-humanizer/scripts/humanizer_scorer.py draft.md - -# Brand voice analysis -python3 marketing-skill/content-production/scripts/brand_voice_analyzer.py copy.txt - -# Ad copy validation -python3 marketing-skill/ad-creative/scripts/ad_copy_validator.py ads.json - -# Pricing scenario modeling -python3 marketing-skill/pricing-strategy/scripts/pricing_modeler.py - -# Tracking plan generation -python3 marketing-skill/analytics-tracking/scripts/tracking_plan_generator.py +python3 skills/<skill>/scripts/<tool>.py --help ``` -## Unique Features +All 59 scripts are stdlib-only; most run a demo with no args. -- **AI SEO (AEO/GEO/LLMO)** — Optimize for AI citation, not just ranking -- **Content Humanizer** — Detect and fix AI writing patterns with scoring -- **Context Foundation** — One brand context file feeds all 42 skills -- **Orchestration Router** — Smart routing by keyword + complexity scoring -- **Zero Dependencies** — All Python tools use stdlib only +## Rules + +- Load ONE specialist skill per task — never bulk-load. +- If `.claude/product-marketing-context.md` exists, read it before any marketing task. +- `content-creator` is deprecated — use `skills/content-production/`. +- Don't pip-install anything for these tools. diff --git a/marketing-skill/skills/onboarding-cro/SKILL.md b/marketing-skill/skills/onboarding-cro/SKILL.md index 57420cbe..a87536f0 100644 --- a/marketing-skill/skills/onboarding-cro/SKILL.md +++ b/marketing-skill/skills/onboarding-cro/SKILL.md @@ -164,14 +164,20 @@ Signup → Step 1 → Step 2 → Activation → Retention 100% 80% 60% 40% 25% ``` -Identify biggest drops and focus there. +Run the bundled analyzer on your step counts instead of eyeballing: + +```bash +python3 scripts/activation_funnel_analyzer.py funnel.json --json # no arg = embedded demo +``` + +It computes per-step drop-off, an activation score 0-100, and names the biggest-loss step. That step is where the audit focuses first. --- ## Output Format ### Onboarding Audit -For each issue: Finding → Impact → Recommendation → Priority +Lead with the analyzer's output: activation score + the named biggest-drop step. Then, for each issue: Finding → Impact → Recommendation → Priority ### Onboarding Flow Design - Activation goal diff --git a/marketing-skill/skills/page-cro/SKILL.md b/marketing-skill/skills/page-cro/SKILL.md index b4a10af1..656c86f7 100644 --- a/marketing-skill/skills/page-cro/SKILL.md +++ b/marketing-skill/skills/page-cro/SKILL.md @@ -108,9 +108,19 @@ Analyze the page across these dimensions, in order of impact: --- +## Tools + +| Tool | Invocation | Output | +|---|---|---| +| Conversion audit | `python3 scripts/conversion_audit.py --file page.html` (or `--url https://...`; `--json` for pipelines) | Mechanical scan for conversion signals: CTA presence/count, form weight, social proof, trust elements — with a score | + +Run it before the manual framework pass; its score anchors the audit and its flags seed the Quick Wins list. + +--- + ## Output Format -Structure your recommendations as: +Open with the `conversion_audit.py` score, then structure recommendations as: ### Quick Wins (Implement Now) Easy changes with likely immediate impact. diff --git a/marketing-skill/skills/paid-ads/SKILL.md b/marketing-skill/skills/paid-ads/SKILL.md index d44b76c6..1e4e3b10 100644 --- a/marketing-skill/skills/paid-ads/SKILL.md +++ b/marketing-skill/skills/paid-ads/SKILL.md @@ -76,10 +76,10 @@ Account ``` [Platform]_[Objective]_[Audience]_[Offer]_[Date] -Examples: -META_Conv_Lookalike-Customers_FreeTrial_2024Q1 +Examples (use the current year/quarter — {YYYY}/{Qn} are placeholders): +META_Conv_Lookalike-Customers_FreeTrial_{YYYY}Q1 GOOG_Search_Brand_Demo_Ongoing -LI_LeadGen_CMOs-SaaS_Whitepaper_Mar24 +LI_LeadGen_CMOs-SaaS_Whitepaper_{MonYY} ``` ### Budget Allocation @@ -227,9 +227,19 @@ LI_LeadGen_CMOs-SaaS_Whitepaper_Mar24 ## Reporting & Analysis +### Tools + +| Tool | Invocation | Output | +|---|---|---| +| ROAS calculator | `python3 scripts/roas_calculator.py --spend 5000 --revenue 18000 --conversions 120 --clicks 2400 --margin 0.7` (or `--file metrics.json`; `--json` for pipelines) | ROAS, CPA, CPC, CVR, margin-adjusted ROAS + recommendations | +| Ad health scorer | `python3 scripts/ad_health_scorer.py --checks checks.json --platform meta` (no arg = `--demo`; `--json` for pipelines) | Weighted 0-100 account health score with severity-ranked findings; see [references/scoring-system.md](references/scoring-system.md) for the scoring model | + ### Weekly Review + +Run both tools on the week's numbers, then review: - Spend vs. budget pacing -- CPA/ROAS vs. targets +- CPA/ROAS vs. targets — from `roas_calculator.py`, margin-adjusted, not platform-reported +- Account health score trend — from `ad_health_scorer.py`; investigate any category that dropped - Top and bottom performing ads - Audience performance breakdown - Frequency check (fatigue risk) @@ -297,16 +307,16 @@ Before launching campaigns, ensure proper tracking and account setup. ## Tool Integrations -For implementation, see the [tools registry](../../tools/REGISTRY.md). Key advertising platforms: +Key advertising platforms: -| Platform | Best For | MCP | Guide | -|----------|----------|:---:|-------| -| **Google Ads** | Search intent, high-intent traffic | ✓ | [google-ads.md](../../tools/integrations/google-ads.md) | -| **Meta Ads** | Demand gen, visual products, B2C | - | [meta-ads.md](../../tools/integrations/meta-ads.md) | -| **LinkedIn Ads** | B2B, job title targeting | - | [linkedin-ads.md](../../tools/integrations/linkedin-ads.md) | -| **TikTok Ads** | Younger demographics, video | - | [tiktok-ads.md](../../tools/integrations/tiktok-ads.md) | +| Platform | Best For | MCP | +|----------|----------|:---:| +| **Google Ads** | Search intent, high-intent traffic | ✓ | +| **Meta Ads** | Demand gen, visual products, B2C | - | +| **LinkedIn Ads** | B2B, job title targeting | - | +| **TikTok Ads** | Younger demographics, video | - | -For tracking, see also: [ga4.md](../../tools/integrations/ga4.md), [segment.md](../../tools/integrations/segment.md) +For tracking and attribution, pair these with GA4 and Segment. --- diff --git a/marketing-skill/skills/pricing-strategy/SKILL.md b/marketing-skill/skills/pricing-strategy/SKILL.md index 21d644bb..9fda84ea 100644 --- a/marketing-skill/skills/pricing-strategy/SKILL.md +++ b/marketing-skill/skills/pricing-strategy/SKILL.md @@ -18,7 +18,7 @@ Pricing is not math — it's positioning. The right price isn't the one that cov ## Before Starting **Check for context first:** -If `marketing-context.md` exists, read it before asking questions. Use that context and only ask for what's missing. +If `.claude/product-marketing-context.md` exists, read it before asking questions. Use that context and only ask for what's missing. Gather this context: diff --git a/marketing-skill/skills/programmatic-seo/SKILL.md b/marketing-skill/skills/programmatic-seo/SKILL.md index 3e8287a8..6cdfd1a1 100644 --- a/marketing-skill/skills/programmatic-seo/SKILL.md +++ b/marketing-skill/skills/programmatic-seo/SKILL.md @@ -128,7 +128,17 @@ You can layer multiple playbooks (e.g., "Best coworking spaces in San Diego"). - Is it first-party, scraped, licensed, public? - How is it updated? -### 3. Template Design +### 3. URL Pattern Generation (bundled tool) + +Generate and sanity-check the URL space before building templates: + +```bash +python3 scripts/url_pattern_generator.py pattern.json --json # no arg = embedded demo +``` + +Give it the template (e.g., `{tool}-vs-{competitor}-comparison`), base URL, and variable lists; it expands the combinations, reports the page count, and flags slug problems. If the expansion produces more pages than you have unique data for (see step 2), cut variables — don't ship thin pages. + +### 4. Template Design **Page structure:** - Header with target keyword @@ -142,7 +152,7 @@ You can layer multiple playbooks (e.g., "Best coworking spaces in San Diego"). - Conditional content based on data - Original insights/analysis per page -### 4. Internal Linking Architecture +### 5. Internal Linking Architecture **Hub and spoke model:** - Hub: Main category page @@ -154,7 +164,7 @@ You can layer multiple playbooks (e.g., "Best coworking spaces in San Diego"). - XML sitemap for all pages - Breadcrumbs with structured data -### 5. Indexation Strategy +### 6. Indexation Strategy - Prioritize high-volume patterns - Noindex very thin variations diff --git a/marketing-skill/skills/prompt-engineer-toolkit/SKILL.md b/marketing-skill/skills/prompt-engineer-toolkit/SKILL.md index 037d0b5d..c0613e72 100644 --- a/marketing-skill/skills/prompt-engineer-toolkit/SKILL.md +++ b/marketing-skill/skills/prompt-engineer-toolkit/SKILL.md @@ -1,6 +1,6 @@ --- name: "prompt-engineer-toolkit" -description: "Analyzes and rewrites prompts for better AI output, creates reusable prompt templates for marketing use cases (ad copy, email campaigns, social media), and structures end-to-end AI content workflows. Use when the user wants to improve prompts for AI-assisted marketing, build prompt templates, or optimize AI content workflows. Also use when the user mentions 'prompt engineering,' 'improve my prompts,' 'AI writing quality,' 'prompt templates,' or 'AI content workflow.'" +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 — or when the user mentions 'prompt engineering,' 'improve my prompts,' 'prompt templates,' 'prompt versioning,' 'AI content workflow,' or 'AI governance for marketing.'" license: MIT metadata: version: 1.0.0 @@ -106,9 +106,9 @@ python3 scripts/prompt_versioner.py changelog --name support_classifier ## References -- [references/prompt-templates.md](references/prompt-templates.md) -- [references/technique-guide.md](references/technique-guide.md) -- [references/evaluation-rubric.md](references/evaluation-rubric.md) +- [references/prompt-templates.md](references/prompt-templates.md) — 6 production marketing templates (ad copy, email sequence, social repurposing, landing sections, SEO meta, brand-voice rewrite) plus generic building blocks; each written to be graded by `prompt_tester.py` +- [references/technique-guide.md](references/technique-guide.md) — technique-selection table for marketing tasks + the LLM-governance stack for marketing teams (claim discipline, disclosure rules, data boundaries, human-review gates) +- [references/evaluation-rubric.md](references/evaluation-rubric.md) — mechanical scoring weights, acceptance gates, marketing quality dimensions, test-suite design, and eval anti-patterns - [README.md](README.md) ## Evaluation Design diff --git a/marketing-skill/skills/prompt-engineer-toolkit/references/evaluation-rubric.md b/marketing-skill/skills/prompt-engineer-toolkit/references/evaluation-rubric.md index 24886d59..d0cfb5b5 100644 --- a/marketing-skill/skills/prompt-engineer-toolkit/references/evaluation-rubric.md +++ b/marketing-skill/skills/prompt-engineer-toolkit/references/evaluation-rubric.md @@ -1,14 +1,64 @@ -# Evaluation Rubric +# Evaluation Rubric for Marketing Prompts -Score each case on 0-100 via weighted criteria: +How to score prompt outputs deterministically with `scripts/prompt_tester.py`, and how to extend the mechanical score with marketing-specific quality dimensions a regex can't fully capture. The principle throughout: evidence over intuition — a prompt is "better" only if it scores better on a realistic, edge-case-rich suite (never a single cherry-picked output). -- Expected content coverage: +weight -- Forbidden content violations: -weight -- Regex/format compliance: +weight -- Output length sanity: +/-weight +## Layer 1 — Mechanical Score (what `prompt_tester.py` computes) -Recommended acceptance gates: +Score each test case 0-100 via weighted criteria: -- Average score >= 85 -- No case below 70 -- Zero critical forbidden-content hits +| Criterion | Direction | Typical weight | Test-case field | +|---|---|---|---| +| Expected content coverage | + | 40% | `expected_contains` | +| Forbidden content violations | − (hard penalty) | 30% | `forbidden_contains` | +| Regex/format compliance | + | 20% | `expected_regex` | +| Output length sanity | ± | 10% | min/max length | + +**Acceptance gates (promote a prompt only if all hold):** + +- Average score ≥ 85 across the suite +- No individual case below 70 +- Zero critical forbidden-content hits (brand-banned words, invented statistics markers, competitor names where disallowed, compliance terms — see governance guide) + +## Layer 2 — Marketing Quality Dimensions + +Encode as many of these as possible into Layer-1 fields; what remains needs human review on a sample (5-10 outputs per variant): + +| Dimension | Mechanical proxy | Human check | +|---|---|---| +| **Specificity** | `expected_regex` for digits/named entities | Is the specific claim *true* and sourced? | +| **Brand voice** | `forbidden_contains` lexicon-no list | Does it sound like us, not "an AI"? | +| **Claim safety** | forbidden superlatives ("best", "#1", "guaranteed") unless proof token present | Would legal/compliance sign off? | +| **Format fitness** | char-count regex per platform | Does it read natively on the platform? | +| **CTA quality** | required CTA token | Single clear action, value-phrased? | +| **Audience fit** | required pain-point/persona token | Would the named persona care? | + +Scoring scale for human review (per Hamel Husain's eval guidance, keep it binary where possible): pass/fail per dimension beats 1-5 ratings — raters agree more, and failures become new `forbidden_contains`/`expected_regex` entries, ratcheting the mechanical suite forward. + +## Building the Test Suite + +A marketing prompt suite needs at minimum: + +1. **Happy-path cases (3-5)** — typical inputs with complete variables +2. **Sparse-input cases (2-3)** — missing proof points, vague audience: the prompt must degrade safely (omit proof, ask, or flag) rather than fabricate +3. **Adversarial cases (2-3)** — inputs that bait policy violations: competitor disparagement requests, unverifiable claims supplied as "facts", off-brand tone requests +4. **Edge-format cases (1-2)** — very long inputs, non-English fragments, emoji-laden source content + +Failure analysis loop: every production failure (rejected ad, spam-flagged email, off-brand post) becomes a new test case before the prompt is edited — the marketing equivalent of regression-test-first. + +## Anti-Patterns + +- **Single-output judgment** — comparing one generation per prompt; sampling variance swamps prompt differences. Run every case ≥ 3 times or compare suite averages. +- **LLM-as-judge without calibration** — if you add a model-graded criterion, calibrate it against human labels on 20+ examples first and re-check periodically (judges drift with model versions). +- **Score-only promotion** — a +2 average that introduces one compliance violation is a regression, not an improvement. Violations gate, scores rank. +- **Frozen suite** — a suite that never grows stops catching new failure modes; tie suite growth to the failure-analysis loop above. + +--- + +## Citations (6 sources) + +1. Anthropic — "Define your success criteria" + "Create strong empirical evaluations" (docs.anthropic.com/en/docs/build-with-claude/define-success, /develop-tests): measurable criteria and graded test suites before prompt iteration +2. OpenAI Evals — open-source eval framework and registry patterns for templated, deterministic graders (github.com/openai/evals) +3. Hamel Husain — "Your AI Product Needs Evals" (hamel.dev/blog/posts/evals): unit-test-style assertions, failure-driven suite growth, binary human labels +4. Zheng et al. — "Judging LLM-as-a-Judge with MT-Bench and Chatbot Arena" (NeurIPS 2023): LLM-judge agreement rates and bias modes (position, verbosity) +5. Eugene Yan — "Patterns for Building LLM-based Systems & Products" (eugeneyan.com): eval-first development, guardrails as gates vs. scores as ranks +6. Liu et al. — "G-Eval: NLG Evaluation using GPT-4 with Better Human Alignment" (EMNLP 2023): criteria-decomposed grading for content quality dimensions diff --git a/marketing-skill/skills/prompt-engineer-toolkit/references/prompt-templates.md b/marketing-skill/skills/prompt-engineer-toolkit/references/prompt-templates.md index 872669dc..16ea83fe 100644 --- a/marketing-skill/skills/prompt-engineer-toolkit/references/prompt-templates.md +++ b/marketing-skill/skills/prompt-engineer-toolkit/references/prompt-templates.md @@ -1,105 +1,140 @@ -# Prompt Templates +# Marketing Prompt Templates -## 1) Structured Extractor +Production-ready prompt templates for the marketing use cases this skill promises: ad copy, email campaigns, social media, landing pages, and SEO metadata. Each template is written to be testable with `scripts/prompt_tester.py` — explicit output format, explicit constraints, explicit exclusions — and versionable with `scripts/prompt_versioner.py` under the semantic name given. + +Design principles behind every template (see citations): role + goal up front, output schema explicit, constraints as bullets not prose, variables in `{{double_braces}}`, and a forbidden-content clause so `must_not_contain` checks have something to enforce. + +--- + +## 1) Ad Copy Variants — `ad_copy_shortform` ```text -You are an extraction assistant. -Return ONLY valid JSON matching this schema: -{{schema}} +You are a direct-response copywriter for {{brand}} ({{one_line_positioning}}). -Input: -{{input}} +Write {{count}} ad copy variants for {{platform}} promoting {{offer}}. + +Audience: {{audience}} — their #1 pain: {{pain_point}}. +Voice: {{voice_adjectives}}. Reading level: 7th grade. + +Hard constraints: +- Headline ≤ {{headline_limit}} characters; primary text ≤ {{body_limit}} characters +- Each variant uses a DIFFERENT angle: pain-led, outcome-led, proof-led, curiosity-led +- One specific, verifiable claim per variant ({{proof_points}}); never invent statistics +- No exclamation-point stacking, no "🚀", no "game-changing/revolutionary/unleash" + +Return JSON array: [{"angle":"...","headline":"...","primary_text":"...","cta":"..."}] ``` -## 2) Classifier +Test cases should assert character limits via `expected_regex` and ban the cliché list via `forbidden_contains`. + +## 2) Email Campaign Sequence — `email_campaign_writer` ```text -Classify input into one of: {{labels}}. -Return only the label. +You are a lifecycle email marketer for {{brand}}. -Input: {{input}} -``` +Write email {{n}} of {{total}} in a {{sequence_type}} sequence (goal: {{conversion_goal}}). +Reader context: {{what_they_did}} — they have NOT yet {{what_they_havent_done}}. -## 3) Summarizer - -```text -Summarize the input in {{max_words}} words max. -Focus on: {{focus_area}}. -Input: -{{input}} -``` - -## 4) Rewrite With Constraints - -```text -Rewrite for {{audience}}. Constraints: -- Tone: {{tone}} -- Max length: {{max_len}} -- Must include: {{must_include}} -- Must avoid: {{must_avoid}} +- Subject line ≤ 45 chars + preview text ≤ 90 chars; no spam-trigger words (free!!!, act now, limited time) +- Body 90-150 words, one idea, one CTA ({{cta_text}} → {{cta_url}}) +- Plain-text tone — write like a competent colleague, not a brand +- Reference the reader's situation in sentence 1; never open with "I hope this finds you well" -Input: +Return: +SUBJECT: ... +PREVIEW: ... +BODY: +... +CTA: ... +``` + +## 3) Social Media Post Set — `social_post_repurposer` + +```text +You are a social content editor. Repurpose the source content into {{count}} platform-native posts. + +Platforms: {{platforms}}. +Source: +{{source_content}} + +Per-platform rules: +- X: ≤ 280 chars, hook in first 8 words, max 1 hashtag, placed at the end +- LinkedIn: ≤ 1300 chars, line breaks every 1-2 sentences, no engagement-bait ("Agree?") +- Instagram: caption ≤ 150 words + 5 relevant hashtags at the end + +Every post must contain one specific detail (number, name, example) from the source. +Return JSON: [{"platform":"...","post":"...","specific_detail_used":"..."}] +``` + +## 4) Landing Page Section Copy — `landing_section_writer` + +```text +You are a conversion copywriter. Write the {{section}} section for a landing page. + +Product: {{product}} — for {{audience}} who want {{outcome}}. +Differentiator: {{differentiator}}. Proof available: {{proof_points}}. + +Constraints: +- Headline: specific outcome, ≤ 12 words, no category jargon +- Body: benefit-first, "you" language, ≤ 60 words +- Use ONLY the proof points provided; if none fit, omit proof rather than invent it +- CTA button: verb + value ("Get my report"), never "Submit"/"Learn more" + +Return markdown with HEADLINE / BODY / CTA blocks. +``` + +## 5) SEO Title + Meta Description — `seo_meta_writer` + +```text +You are an SEO editor. Write title tag + meta description for the page below. + +Primary keyword: {{keyword}} (must appear in title, near the front, naturally). +Search intent: {{intent}}. Page summary: {{summary}}. + +Constraints: +- Title ≤ 60 characters, no clickbait, no ALL CAPS, brand suffix " | {{brand}}" if it fits +- Meta description 150-160 characters, includes keyword once, ends with a reason to click +- Describe what the page actually contains — no promises the page doesn't keep + +Return JSON: {"title":"...","title_chars":N,"meta":"...","meta_chars":N} +``` + +## 6) Brand-Voice Content Rewrite — `brand_voice_rewriter` + +```text +You are {{brand}}'s editor. Rewrite the draft in our voice without changing facts or claims. + +Voice profile (from .claude/product-marketing-context.md): {{voice_profile}} +Words we use: {{lexicon_yes}}. Words we never use: {{lexicon_no}}. + +Constraints: +- Preserve every factual claim, number, and named source exactly +- Keep length within ±10% of the draft +- Flag (don't fix) any claim that lacks a source: [NEEDS SOURCE: ...] + +Draft: {{input}} ``` -## 5) QA Pair Generator +## 7) Generic Building Blocks + +The original toolkit templates (structured extractor, classifier, summarizer, constrained rewrite, persona rewrite, policy-compliance check, prompt critique) remain useful as building blocks for non-content marketing automation — lead triage, review mining, survey coding. Pattern: ```text -Generate {{count}} Q/A pairs from input. -Output JSON array: [{"question":"...","answer":"..."}] - -Input: -{{input}} -``` - -## 6) Issue Triage - -```text -Classify issue severity: P1/P2/P3/P4. -Return JSON: {"severity":"...","reason":"...","owner":"..."} -Input: -{{input}} -``` - -## 7) Code Review Summary - -```text -Review this diff and return: -1. Risks -2. Regressions -3. Missing tests -4. Suggested fixes - -Diff: -{{input}} -``` - -## 8) Persona Rewrite - -```text -Respond as {{persona}}. -Goal: {{goal}} -Format: {{format}} +Classify input into one of: {{labels}}. Return only the label. Input: {{input}} ``` -## 9) Policy Compliance Check +Compose them: e.g., review mining = extractor (pull quotes) → classifier (theme) → summarizer (theme digest). -```text -Check input against policy. -Return JSON: {"pass":bool,"violations":[...],"recommendations":[...]} -Policy: -{{policy}} -Input: -{{input}} -``` +--- -## 10) Prompt Critique +## Citations (6 sources) -```text -Critique this prompt for clarity, ambiguity, constraints, and failure modes. -Return concise recommendations and an improved version. -Prompt: -{{input}} -``` +1. Anthropic — Prompt engineering overview: role prompting, structured outputs, "be clear and direct" (docs.anthropic.com/en/docs/build-with-claude/prompt-engineering) +2. OpenAI — Prompt engineering guide: instructions-first, delimiters, reference text to limit fabrication (platform.openai.com/docs/guides/prompt-engineering) +3. Google — Gemini prompting strategies: task/context/format decomposition, few-shot examples (ai.google.dev/gemini-api/docs/prompting-strategies) +4. Brown et al. — "Language Models are Few-Shot Learners" (NeurIPS 2020): few-shot examples improve format adherence +5. DAIR.AI — Prompt Engineering Guide: technique taxonomy and template anatomy (promptingguide.ai) +6. Ethan Mollick — One Useful Thing essays on practitioner prompting patterns for business content (oneusefulthing.org) diff --git a/marketing-skill/skills/prompt-engineer-toolkit/references/technique-guide.md b/marketing-skill/skills/prompt-engineer-toolkit/references/technique-guide.md index 6ea0ae7f..fdbadfde 100644 --- a/marketing-skill/skills/prompt-engineer-toolkit/references/technique-guide.md +++ b/marketing-skill/skills/prompt-engineer-toolkit/references/technique-guide.md @@ -1,25 +1,61 @@ -# Technique Guide +# Technique Guide + LLM Governance for Marketing Teams -## Selection Rules +Two things in one reference: (1) which prompting technique to use for which marketing task, and (2) the governance layer — the rules a marketing team needs so AI-assisted content ships safely, legally, and on-brand at scale. -- Zero-shot: deterministic, simple tasks -- Few-shot: formatting ambiguity or label edge cases -- Chain-of-thought: multi-step reasoning tasks -- Structured output: downstream parsing/integration required -- Self-critique/meta prompting: prompt improvement loops +--- -## Prompt Construction Checklist +## Part 1: Technique Selection for Marketing Tasks -- Clear role and goal -- Explicit output format -- Constraints and exclusions -- Edge-case handling instruction -- Minimal token usage for repetitive tasks +| Technique | Use when | Marketing examples | +|---|---|---| +| **Zero-shot + tight constraints** | Task is well-specified and format is simple | SEO meta tags, UTM naming, subject lines | +| **Few-shot (2-5 examples)** | Voice/format is hard to describe but easy to show | Brand-voice posts, email tone, ad-angle patterns — paste your 3 best-performing examples | +| **Chain-of-thought / plan-then-write** | Multi-step reasoning before output | Campaign briefs (audience → angle → channel → copy), positioning drafts | +| **Structured output (JSON/schema)** | Output feeds another tool or script | Ad variant sets, calendar entries, anything `prompt_tester.py` will grade by regex | +| **Decomposition (prompt chains)** | One mega-prompt underperforms | Research → outline → draft → brand-voice rewrite → compliance check, each step testable separately | +| **Self-critique pass** | Quality gate before human review | "List 3 weaknesses of this draft against the brief, then fix them" | -## Failure Pattern Checklist +**Construction checklist** (every marketing prompt): explicit role + goal; the audience and their pain named; output format with limits (chars/words); constraints as bullets; a forbidden list (clichés, banned claims, competitor names); instruction for missing inputs ("if no proof point fits, omit proof — never invent"). -- Too broad objective -- Missing output schema -- Contradictory constraints -- No negative examples for unsafe behavior -- Hidden assumptions not stated in prompt +**Failure patterns to check before testing:** objective too broad ("write something engaging"); missing output schema; contradictory constraints (casual tone + formal compliance phrasing in one prompt); no negative instructions, so the model fills gaps with invented stats; hidden assumptions (brand voice referenced but not provided — pass the actual voice profile from `.claude/product-marketing-context.md`). + +--- + +## Part 2: LLM Governance for Marketing + +Marketing is a high-exposure surface for AI failure: invented statistics in ads, undisclosed AI-generated endorsements, off-brand tone at scale, and privacy violations in personalization. Governance turns those from incidents into checklist items. + +### The Governance Stack + +1. **Approved-use registry** — every production prompt lives in `prompt_versioner.py` with a named owner, author history, and change notes. No anonymous prompt edits in production workflows. +2. **Pre-deployment evaluation** — no prompt ships without passing its test suite (see evaluation-rubric.md). Model upgrades re-run the full baseline suite before switchover — a model swap is a change event. +3. **Claim discipline** — generated copy may only use claims from a maintained proof-point list. Test suites enforce this with `forbidden_contains` (superlatives, "guaranteed", unverifiable "%" patterns without a source token). A human verifies any new claim before it enters the proof list. +4. **Disclosure rules** — know where AI-generation disclosure is required: FTC rules cover endorsements/testimonials (fake or AI-fabricated reviews are actionable); the EU AI Act (Art. 50) requires disclosure for certain AI-generated content including synthetic media; platforms (Meta, TikTok, YouTube) require labels on AI-generated/altered media in ads, especially political/social-issue ads. +5. **Data boundaries** — customer data in prompts is processing under GDPR/CCPA: no PII in third-party model calls without a processing basis and vendor DPA; segment-level personalization over individual-level wherever possible; never paste customer lists into ad-hoc chat sessions. +6. **Human-in-the-loop gates** — mechanical scores gate, humans approve: anything paid (ad spend), anything legal-sensitive (claims, pricing, comparisons), anything brand-new (first run of a new prompt) gets human review before publishing. Routine regenerations of an approved prompt+suite can ship on green scores. +7. **Incident loop** — rejected ads, spam-folder complaints, brand-voice misses: each becomes a test case (evaluation-rubric.md, failure analysis) and, if systemic, a prompt version bump with a changelog entry. + +### Roles + +| Role | Owns | +|---|---| +| Prompt owner (per workflow) | Template, test suite, version history | +| Marketing ops | Registry, model-change re-evaluation calendar | +| Legal/compliance reviewer | Claim list, disclosure map, escalation calls | +| Brand lead | Voice profile, lexicon-yes/no lists | + +### Minimum Viable Governance (small team) + +If the full stack is too heavy: (1) version every production prompt, (2) maintain the forbidden-claims list and wire it into `forbidden_contains`, (3) human-review everything paid, (4) re-run the suite on model changes. These four catch the expensive failures. + +--- + +## Citations (7 sources) + +1. NIST — AI Risk Management Framework 1.0 (2023) + Generative AI Profile (NIST-AI-600-1, 2024): govern/map/measure/manage functions adapted here to content workflows +2. FTC — "Rule on the Use of Consumer Reviews and Testimonials" (2024) and FTC Act §5 guidance on AI-generated endorsements and deceptive claims (ftc.gov) +3. EU AI Act — Regulation (EU) 2024/1689, Art. 50 transparency obligations for AI-generated and manipulated content +4. ISO/IEC 42001:2023 — AI management systems: registry, role assignment, and change-management discipline mirrored in the governance stack +5. Anthropic — Usage policies + prompt engineering docs on constraining model claims and structured outputs (anthropic.com/legal/aup, docs.anthropic.com) +6. Meta — Advertising Standards on AI-disclosure requirements for altered/generated media in ads (transparency.fb.com / Meta Business Help Center) +7. GDPR (Regulation 2016/679) Arts. 6, 28 — processing basis and processor agreements governing customer data sent to model vendors diff --git a/marketing-skill/skills/referral-program/SKILL.md b/marketing-skill/skills/referral-program/SKILL.md index b5ca0d80..64ac9b0d 100644 --- a/marketing-skill/skills/referral-program/SKILL.md +++ b/marketing-skill/skills/referral-program/SKILL.md @@ -16,7 +16,7 @@ You are a growth engineer who has designed referral and affiliate programs for S ## Before Starting **Check for context first:** -If `marketing-context.md` exists, read it before asking questions. Use that context and only ask for information not already covered. +If `.claude/product-marketing-context.md` exists, read it before asking questions. Use that context and only ask for information not already covered. Gather this context (ask if not provided): diff --git a/marketing-skill/skills/schema-markup/SKILL.md b/marketing-skill/skills/schema-markup/SKILL.md index e3bc009f..5413b6d6 100644 --- a/marketing-skill/skills/schema-markup/SKILL.md +++ b/marketing-skill/skills/schema-markup/SKILL.md @@ -16,7 +16,7 @@ You are an expert in structured data and schema.org markup. Your goal is to help ## Before Starting **Check for context first:** -If `marketing-context.md` exists, read it before asking questions. Use that context and only ask for what's missing. +If `.claude/product-marketing-context.md` exists, read it before asking questions. Use that context and only ask for what's missing. Gather this context: diff --git a/marketing-skill/skills/seo-audit/SKILL.md b/marketing-skill/skills/seo-audit/SKILL.md index 765808ae..df136359 100644 --- a/marketing-skill/skills/seo-audit/SKILL.md +++ b/marketing-skill/skills/seo-audit/SKILL.md @@ -38,14 +38,32 @@ Before auditing, understand: --- ## Audit Framework -→ See references/seo-audit-reference.md for details + +The audit walks three layers — technical (crawl/indexation/speed), on-page (titles, headings, internal links, keyword targeting), content (intent match, E-E-A-T, thin/duplicate pages). Full framework: references/seo-audit-reference.md. + +**Core Web Vitals pass/fail thresholds** (75th percentile of real-user data; full triage in references/cwv-thresholds.md): + +| Metric | Good | Needs improvement | Poor | +|---|---|---|---| +| LCP (Largest Contentful Paint) | ≤ 2.5s | 2.5-4.0s | > 4.0s | +| INP (Interaction to Next Paint) | ≤ 200ms | 200-500ms | > 500ms | +| CLS (Cumulative Layout Shift) | ≤ 0.1 | 0.1-0.25 | > 0.25 | + +## Tools + +| Tool | Invocation | Output | +|---|---|---| +| On-page checker | `python3 scripts/seo_checker.py --file page.html` (or `--url https://...`; `--json`) | Scores a single page 0-100: title/meta/headings/links/images | +| Health scorer | `python3 scripts/seo_health_scorer.py --checks checks.json --industry saas` (no arg = `--demo`; industries: saas/ecommerce/local/publisher; `--json`) | Weighted 0-100 site health score across 7 categories | + +Run `seo_checker.py` on the key templates/pages during the on-page layer, and `seo_health_scorer.py` on the completed check matrix to produce the audit's headline score. ## Output Format ### Audit Report Structure **Executive Summary** -- Overall health assessment +- Overall health assessment — lead with the `seo_health_scorer.py` score and its weakest categories - Top 3-5 priority issues - Quick wins identified @@ -111,7 +129,7 @@ Same format as above ## Related Skills - **programmatic-seo** — WHEN: user wants to build SEO pages at scale after the audit identifies keyword gaps. WHEN NOT: don't use for diagnosing existing issues; stay in seo-audit mode. -- **ai-seo** — WHEN: user wants to optimize for AI answer engines (SGE, Perplexity, ChatGPT) in addition to traditional search. WHEN NOT: don't use for purely technical crawl/indexation issues. +- **aeo** — WHEN: user wants to optimize for AI answer engines (SGE, Perplexity, ChatGPT) in addition to traditional search. WHEN NOT: don't use for purely technical crawl/indexation issues. - **schema-markup** — WHEN: audit reveals missing structured data opportunities (FAQ, HowTo, Product, Review schemas). WHEN NOT: don't use as a standalone fix when core technical SEO is broken. - **site-architecture** — WHEN: audit uncovers poor internal linking, orphan pages, or crawl depth issues that need a structural redesign. WHEN NOT: don't involve when the audit scope is limited to on-page or content issues. - **content-strategy** — WHEN: audit reveals thin content, keyword gaps, or lack of topical authority requiring a content plan. WHEN NOT: don't use when the problem is purely technical (robots.txt, redirects, speed). diff --git a/marketing-skill/skills/signup-flow-cro/SKILL.md b/marketing-skill/skills/signup-flow-cro/SKILL.md index f0856087..e5b27c04 100644 --- a/marketing-skill/skills/signup-flow-cro/SKILL.md +++ b/marketing-skill/skills/signup-flow-cro/SKILL.md @@ -43,6 +43,14 @@ Before providing recommendations, understand: ## Core Principles → See references/signup-cro-playbook.md for details +## Tools + +| Tool | Invocation | Output | +|---|---|---| +| Funnel drop analyzer | `python3 scripts/funnel_drop_analyzer.py --steps funnel.json` (or `--stdin`; `--json` for pipelines; no arg = embedded demo) | Per-step drop-off %, the worst step named, and severity ranking | + +Feed it the step-by-step user counts (landing → form start → form complete → verify → done). The named worst step is where the audit starts; quantify each finding's Impact with its drop-off number. + ## Output Format ### Audit Findings diff --git a/marketing-skill/skills/site-architecture/SKILL.md b/marketing-skill/skills/site-architecture/SKILL.md index ef070b25..faeced3c 100644 --- a/marketing-skill/skills/site-architecture/SKILL.md +++ b/marketing-skill/skills/site-architecture/SKILL.md @@ -16,7 +16,7 @@ You are an expert in website information architecture and technical SEO structur ## Before Starting **Check for context first:** -If `marketing-context.md` exists, read it before asking questions. +If `.claude/product-marketing-context.md` exists, read it before asking questions. Gather this context: diff --git a/marketing-skill/skills/social-media-analyzer/SKILL.md b/marketing-skill/skills/social-media-analyzer/SKILL.md index f3f1fae3..85f23b65 100644 --- a/marketing-skill/skills/social-media-analyzer/SKILL.md +++ b/marketing-skill/skills/social-media-analyzer/SKILL.md @@ -1,6 +1,6 @@ --- name: "social-media-analyzer" -description: Social media campaign analysis and performance tracking. Calculates engagement rates, ROI, and benchmarks across platforms. Use for analyzing social media performance, calculating engagement rate, measuring campaign ROI, comparing platform metrics, or benchmarking against industry standards. +description: Social media campaign analysis and performance tracking. Calculates engagement rates, ROI, and benchmarks across platforms. Use when analyzing social media performance, calculating engagement rate, measuring campaign ROI, comparing platform metrics, or benchmarking against industry standards. Also use when the user mentions "social media audit," "engagement rate," or "which platform performs best." triggers: - analyze social media - calculate engagement rate diff --git a/marketing-skill/skills/social-media-manager/SKILL.md b/marketing-skill/skills/social-media-manager/SKILL.md index 9ee9afa9..0acb4aa5 100644 --- a/marketing-skill/skills/social-media-manager/SKILL.md +++ b/marketing-skill/skills/social-media-manager/SKILL.md @@ -16,7 +16,7 @@ You are a senior social media strategist who has grown accounts from zero to six ## Before Starting **Check for marketing context first:** -If `marketing-context.md` exists, read it for brand voice, audience personas, and goals. Only ask for what's missing. +If `.claude/product-marketing-context.md` exists, read it for brand voice, audience personas, and goals. Only ask for what's missing. Gather this context (ask if not provided): @@ -92,6 +92,14 @@ The 10% promotional cap is intentional. If your feed feels like an ad channel, p | Thu | Educational | Thread or how-to | Deep-dive content | | Fri | Social Proof or Promo | Case study or launch | End-of-week conversion focus | +### Generate the Calendar (bundled tool) + +```bash +python3 scripts/social_calendar_generator.py --config calendar.json --start 2026-06-15 --weeks 4 --markdown +``` + +Give it your pillars + platforms + cadence (no config = embedded demo; `--json` for pipelines); it emits a calendar with balanced pillar distribution. Use its output as the working calendar for the batch workflow below — rebalance manually only when a campaign (launch, event) needs to override a pillar slot. + ### Batch Creation Workflow ``` diff --git a/marketing-skill/skills/webinar-marketing/SKILL.md b/marketing-skill/skills/webinar-marketing/SKILL.md index 67300068..011d5353 100644 --- a/marketing-skill/skills/webinar-marketing/SKILL.md +++ b/marketing-skill/skills/webinar-marketing/SKILL.md @@ -18,7 +18,7 @@ A webinar is a funnel, not an event. Registrations are cheap; attention and acti ## Before Starting **Check for context first:** -If `marketing-context.md` exists, read it before asking questions. Use it for brand voice, audience personas, and customer language, and only ask for what's specific to this event. +If `.claude/product-marketing-context.md` exists, read it before asking questions. Use it for brand voice, audience personas, and customer language, and only ask for what's specific to this event. Gather this context (ask conversationally, one section at a time — don't dump every question at once): @@ -58,7 +58,21 @@ When there's no webinar yet — design the whole motion. When a webinar exists or recently ran and the numbers disappoint. Diagnose where the funnel breaks before rewriting anything. 1. Get the actual numbers: invited → registered → showed up → engaged → converted -2. Score the funnel with `scripts/webinar_funnel_scorer.py` to find the weakest stage +2. Score the funnel with `scripts/webinar_funnel_scorer.py` to find the weakest stage: + + ```bash + # Score a funnel from a JSON file (registrations + attended_live required; + # page_visits, cta_clicks, conversions, audience, runtime_min, avg_watch_min optional) + python3 scripts/webinar_funnel_scorer.py funnel.json + + # Or pipe JSON via stdin + cat funnel.json | python3 scripts/webinar_funnel_scorer.py - + + # Demo mode on embedded sample data + python3 scripts/webinar_funnel_scorer.py --sample + ``` + + Output: a 0-100 scorecard per stage against audience-temperature benchmarks (`customers` / `warm` / `owned_cold` / `paid_cold`), the bottleneck stage flagged, plus a JSON block for downstream use. 3. Fix the stage that's actually broken — don't rewrite the landing page when the problem is show-up rate 4. Deliver: diagnosis (where it breaks + why) + targeted fixes ranked by impact diff --git a/marketing-skill/skills/webinar-marketing/scripts/webinar_funnel_scorer.py b/marketing-skill/skills/webinar-marketing/scripts/webinar_funnel_scorer.py index a651dd7d..fc305b1f 100644 --- a/marketing-skill/skills/webinar-marketing/scripts/webinar_funnel_scorer.py +++ b/marketing-skill/skills/webinar-marketing/scripts/webinar_funnel_scorer.py @@ -22,8 +22,10 @@ Usage: python webinar_funnel_scorer.py data.json # score a JSON file cat data.json | python webinar_funnel_scorer.py - # read JSON from stdin python webinar_funnel_scorer.py # runs on embedded sample data + python webinar_funnel_scorer.py --sample # explicit demo mode """ +import argparse import json import sys @@ -138,19 +140,53 @@ def print_summary(r): def main(): - arg = sys.argv[1] if len(sys.argv) > 1 else None - if arg == "-": - # Explicit stdin. Only read here so we never block when no input exists. - raw = sys.stdin.read().strip() - data = json.loads(raw) if raw else SAMPLE - elif arg: - with open(arg) as f: - data = json.load(f) - else: - data = SAMPLE - print("(no input given — running on embedded sample data)\n") + parser = argparse.ArgumentParser( + description="Score a webinar funnel 0-100 against audience-temperature " + "benchmarks and name the bottleneck stage.", + formatter_class=argparse.RawDescriptionHelpFormatter, + epilog=( + "examples:\n" + " python3 webinar_funnel_scorer.py data.json # score a JSON file\n" + " cat data.json | python3 webinar_funnel_scorer.py - # read JSON from stdin\n" + " python3 webinar_funnel_scorer.py # embedded sample data\n" + " python3 webinar_funnel_scorer.py --sample # explicit demo mode" + ), + ) + parser.add_argument( + "file", + nargs="?", + help="Path to a funnel JSON file, or '-' to read JSON from stdin. " + "Omit to run on embedded sample data.", + ) + parser.add_argument( + "--sample", + action="store_true", + help="Run on the embedded sample funnel data and exit.", + ) + args = parser.parse_args() - result = analyze(data) + try: + if args.sample: + data = SAMPLE + elif args.file == "-": + # Explicit stdin. Only read here so we never block when no input exists. + raw = sys.stdin.read().strip() + data = json.loads(raw) if raw else SAMPLE + elif args.file: + with open(args.file) as f: + data = json.load(f) + else: + data = SAMPLE + print("(no input given — running on embedded sample data)\n") + except (OSError, json.JSONDecodeError) as exc: + print(f"Error reading input: {exc}", file=sys.stderr) + sys.exit(2) + + try: + result = analyze(data) + except ValueError as exc: + print(f"Error: {exc}", file=sys.stderr) + sys.exit(2) print_summary(result) print("JSON:") print(json.dumps(result, indent=2)) diff --git a/marketing-skill/social-media-analyzer.zip b/marketing-skill/social-media-analyzer.zip deleted file mode 100644 index 7c6308ca..00000000 Binary files a/marketing-skill/social-media-analyzer.zip and /dev/null differ diff --git a/marketing-skill/video-content-strategist/skills/video-content-strategist/SKILL.md b/marketing-skill/video-content-strategist/skills/video-content-strategist/SKILL.md index a94a6f92..700415a6 100644 --- a/marketing-skill/video-content-strategist/skills/video-content-strategist/SKILL.md +++ b/marketing-skill/video-content-strategist/skills/video-content-strategist/SKILL.md @@ -13,7 +13,7 @@ Video is the highest-trust content format. A viewer who watches 10 minutes of yo ## Before Starting -**Check for context first:** If marketing-context.md exists, read it before asking questions. It contains brand voice, audience, competitor analysis, and existing content assets. +**Check for context first:** If `.claude/product-marketing-context.md` exists, read it before asking questions. It contains brand voice, audience, competitor analysis, and existing content assets. Gather this context (ask in one shot): diff --git a/marketing/landing/agents/cs-landing.md b/marketing/landing/agents/cs-landing.md index 72d8307d..f3d93906 100644 --- a/marketing/landing/agents/cs-landing.md +++ b/marketing/landing/agents/cs-landing.md @@ -31,11 +31,11 @@ Visual-premium-focused, motion-aware, brand-respecting. Refuses to ship a generi The cs-landing agent orchestrates the `landing` skill across HTML one-pager generation: 1. **Grill-me intake (Q1 → Q4)** — product / audience / brand / tone, one at a time, with "why I'm asking" per question -2. **Pre-flight** — validate brand palette with `scripts/brand_palette_validator.py`; generate output slug with `scripts/kebab_slug_generator.py` +2. **Pre-flight** — validate brand palette with `skills/landing/scripts/brand_palette_validator.py`; generate output slug with `skills/landing/scripts/kebab_slug_generator.py` 3. **Content extraction** — from Q1 elevator pitch, derive hero headline, subtext, feature bullets, CTA copy, closing line 4. **Brand system** — default dark navy + teal OR overridden palette 5. **Generation (single pass)** — write the .html file with Hero + Features + Closing CTA sections, GSAP timeline, mouse-parallax handlers, scroll-triggered reveals, CSS floating shapes -6. **Post-flight** — validate output with `scripts/html_validator.py` (checks: 3 sections present, CDN deps included, `gsap.set()` initial states, responsive breakpoints, no external CSS/JS files) +6. **Post-flight** — validate output with `skills/landing/scripts/html_validator.py` (checks: 3 sections present, CDN deps included, `gsap.set()` initial states, responsive breakpoints, no external CSS/JS files) 7. **Deliver** — file path (CLI) or HTML artifact (Claude.ai web) Differentiates clearly: diff --git a/mkdocs.yml b/mkdocs.yml index ab9f28cd..af0f8f3c 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,6 +1,6 @@ site_name: Claude Code Skills & Agent Plugins site_url: https://alirezarezvani.github.io/claude-skills/ -site_description: "337 production-ready agent skills, 66 installable plugins, and 90+ slash commands across 17 domains — engineering, product, marketing, compliance, finance, and research. Works with Claude Code, OpenAI Codex, Gemini CLI, Cursor, Hermes Agent, Mistral Vibe, OpenClaw, and 6 more AI coding tools. Open source, MIT licensed, zero dependencies." +site_description: "345 production-ready agent skills, 78 installable plugins, and 90+ slash commands across 17 domains — engineering, product, marketing, compliance, finance, and research. Works with Claude Code, OpenAI Codex, Gemini CLI, Cursor, Hermes Agent, Mistral Vibe, OpenClaw, and 6 more AI coding tools. Open source, MIT licensed, zero dependencies." site_author: Alireza Rezvani repo_url: https://github.com/alirezarezvani/claude-skills repo_name: alirezarezvani/claude-skills @@ -65,6 +65,10 @@ plugins: 'skills/engineering/feature-flags-architect-feature-flags-architect.md': 'skills/engineering/feature-flags-architect.md' 'skills/engineering/kubernetes-operator-kubernetes-operator.md': 'skills/engineering/kubernetes-operator.md' 'skills/engineering/slo-architect-slo-architect.md': 'skills/engineering/slo-architect.md' + # Skills removed/renamed upstream — redirect old indexed URLs to their successors. + 'skills/marketing-skill/ai-seo.md': 'skills/marketing-skill/aeo.md' + 'skills/engineering/release-manager.md': 'skills/engineering/changelog-generator.md' + 'skills/engineering/command-guide.md': 'skills/engineering/index.md' extra: social: @@ -224,7 +228,6 @@ nav: - "PR Review Expert": skills/engineering/pr-review-expert.md - "Prompt Governance": skills/engineering/prompt-governance.md - "RAG Architect": skills/engineering/rag-architect.md - - "Release Manager": skills/engineering/release-manager.md - "Runbook Generator": skills/engineering/runbook-generator.md - "Secrets Vault Manager": skills/engineering/secrets-vault-manager.md - "Security Guidance": skills/engineering/security-guidance.md @@ -284,7 +287,6 @@ nav: - "A/B Test Setup": skills/marketing-skill/ab-test-setup.md - "Ad Creative": skills/marketing-skill/ad-creative.md - "AEO (Answer Engine Optimization)": skills/marketing-skill/aeo.md - - "AI SEO": skills/marketing-skill/ai-seo.md - "Analytics Tracking": skills/marketing-skill/analytics-tracking.md - "App Store Optimization": skills/marketing-skill/app-store-optimization.md - "Brand Guidelines": skills/marketing-skill/brand-guidelines.md diff --git a/orchestration/ORCHESTRATION.md b/orchestration/ORCHESTRATION.md index 65e584e1..f49a99b0 100644 --- a/orchestration/ORCHESTRATION.md +++ b/orchestration/ORCHESTRATION.md @@ -53,8 +53,8 @@ Personas know _what_ to do. Skills know _how_ to do it with precision. Load the ``` Load skills: -- engineering/aws-solution-architect/SKILL.md -- engineering/mcp-server-builder/SKILL.md +- engineering-team/skills/aws-solution-architect/SKILL.md +- engineering/skills/mcp-server-builder/SKILL.md ``` The persona drives decisions. The skills provide the structured steps, scripts, and templates. @@ -142,10 +142,10 @@ Best for: high-stakes decisions, launch readiness reviews, investor prep. No persona needed. Chain skills sequentially for procedural work. ``` -1. content-strategy/SKILL.md → Identify topics and angles -2. copywriting/SKILL.md → Write the content -3. seo-audit/SKILL.md → Optimize for search -4. analytics-tracking/SKILL.md → Set up measurement +1. marketing-skill/skills/content-strategy/SKILL.md → Identify topics and angles +2. marketing-skill/skills/copywriting/SKILL.md → Write the content +3. marketing-skill/skills/seo-audit/SKILL.md → Optimize for search +4. marketing-skill/skills/analytics-tracking/SKILL.md → Set up measurement ``` Best for: repeatable processes, content pipelines, compliance checklists. diff --git a/product-team/agile-product-owner/skills/agile-product-owner/SKILL.md b/product-team/agile-product-owner/skills/agile-product-owner/SKILL.md index f38f44d8..759d689f 100644 --- a/product-team/agile-product-owner/skills/agile-product-owner/SKILL.md +++ b/product-team/agile-product-owner/skills/agile-product-owner/SKILL.md @@ -1,6 +1,6 @@ --- name: "agile-product-owner" -description: Agile product ownership for backlog management and sprint execution. Covers user story writing, acceptance criteria, sprint planning, and velocity tracking. Use for writing user stories, creating acceptance criteria, planning sprints, estimating story points, breaking down epics, or prioritizing backlog. +description: Agile product ownership for backlog management and sprint execution. Covers user story writing, acceptance criteria, sprint planning, and velocity tracking. Use when writing user stories, creating acceptance criteria, planning sprints, estimating story points, breaking down epics, or prioritizing the backlog. not_for: Kanban-only workflows, waterfall project planning, general task management, non-Scrum agile frameworks (SAFe, LeSS) without adaptation triggers: - write user story diff --git a/product-team/apple-hig-expert/skills/apple-hig-expert/SKILL.md b/product-team/apple-hig-expert/skills/apple-hig-expert/SKILL.md index e50fe4cf..d2c9be6a 100644 --- a/product-team/apple-hig-expert/skills/apple-hig-expert/SKILL.md +++ b/product-team/apple-hig-expert/skills/apple-hig-expert/SKILL.md @@ -1,90 +1,108 @@ --- name: apple-hig-expert -description: "Expert guidance on Apple Human Interface Guidelines (HIG). Covers iOS, macOS, and visionOS with 2026 Liquid Glass aesthetics and accessibility-first design." +description: "Audits and designs iOS/macOS/watchOS/visionOS interfaces against the Apple Human Interface Guidelines, including the Liquid Glass design language (announced WWDC25, shipped with iOS 26/macOS Tahoe, Sept 2025). Use when reviewing an Apple-platform mockup or app for HIG compliance, checking contrast or tap-target sizes, or designing native-feeling Apple UI (e.g., 'audit my iOS app against the HIG', 'is this text readable on Liquid Glass?')." license: MIT metadata: - version: 1.0.0 + version: 1.1.0 author: Alireza Rezvani category: design - updated: 2026-04-09 + updated: 2026-06-11 --- # Apple HIG Expert -You are a Senior Apple Design Lead with decades of experience shipping award-winning apps on the App Store. Your goal is to help users design and audit apps that feel natively integrated into the Apple ecosystem while pushing the boundaries of the **Liquid Glass** aesthetic. +Design and audit apps against the Apple Human Interface Guidelines (HIG, [developer.apple.com/design/human-interface-guidelines](https://developer.apple.com/design/human-interface-guidelines)), including the **Liquid Glass** design language. HIG content evolves with each OS release — when a claim matters, verify against the live HIG pages cited in `references/`. ## Before Starting -**Check for context first:** -If `product-context.md` or `ios-design-context.md` exists, read it before asking questions. +If `product-context.md` or `ios-design-context.md` exists, read it before asking questions. Then gather: -Gather this context: -1. **Platform Target**: iOS, macOS, watchOS, or visionOS? -2. **Current State**: New project or auditing an existing mockup? -3. **App Category**: Utility, Productivity, Game, Social, etc.? +1. **Platform target**: iOS, macOS, watchOS, or visionOS? +2. **Current state**: new design or auditing an existing mockup/code? +3. **App category**: utility, productivity, game, social, etc. -## How This Skill Works +## Modes -This skill supports 2 primary modes: +- **Mode 1 — Design from scratch**: pick the platform navigation paradigm and layout primitives first (see `references/platform-specifics.md`), then apply typography and semantic color (`references/visual-design.md`). +- **Mode 2 — HIG audit**: fill in `templates/hig-audit-template.md`, run `scripts/hig_checker.py` on every measurable element, and deliver a scored report (see Worked example below). -### Mode 1: Design from Scratch -When starting fresh. Focus on atomic design, layout primitives, and navigation paradigms that align with Apple's core philosophies (Clarity, Deference, Depth). +## The Compliance Tool -### Mode 2: HIG Audit -When reviewing mockups or code. Use the [templates/hig-audit-template.md](templates/hig-audit-template.md) to systematically identify violations and refinement opportunities. +`scripts/hig_checker.py` (stdlib-only) has three subcommands: -## Core Design Principles (2026) +```bash +# 1. Contrast ratio (WCAG formula; pass >= 4.5:1 for normal text) +python3 scripts/hig_checker.py contrast "#8E8E93" "#FFFFFF" +# -> Contrast Ratio: 3.26 [FAILED] -### 1. Liquid Glass Aesthetic -Modern Apple design emphasizes translucency and fluid motion. -- **Translucency**: Use materials (thin, thick, ultra-thin) to create hierarchy. -- **Depth**: Layers should reflect z-axis relationships. -- **Fluidity**: Interactions should feel like physical objects responding to touch/eyes. +# 2. Tap-target size (pass >= 44x44 pt per HIG) +python3 scripts/hig_checker.py target 32 32 +# -> Tap Target: 32x32 [FAILED] -### 2. Accessibility First -Design for everyone from Day 1. -- **VoiceOver**: All elements must have semantic descriptions. -- **Tap Targets**: Minimum 44x44 points for all interactive elements. -- **Contrast**: Ensure legibility against translucent backgrounds. +# 3. Batch audit from JSON -> scorecard (starts at 100, -10 per violation) +python3 scripts/hig_checker.py batch audit.json +``` -## Workflows +Batch input shape: -### Phase 1: Navigation & Layout -Choose the right navigation pattern (Sidebars for macOS, Tab Bars for iOS, Ornaments for visionOS). -See [references/platform-specifics.md](references/platform-specifics.md) for details. +```json +{ + "checks": [ + {"type": "contrast", "name": "caption-on-card", "fg": "#8E8E93", "bg": "#FFFFFF"}, + {"type": "target", "name": "close-button", "w": 32, "h": 32} + ] +} +``` -### Phase 2: Visual Styling -Apply typography (San Francisco family) and semantic colors. -See [references/visual-design.md](references/visual-design.md). +**Scorecard rubric:** the batch score starts at 100 and subtracts 10 per failed check; violations are listed by element name. 90-100 = ship, 70-80 = fix before release, below 70 = systematic rework. Checks the tool cannot measure (VoiceOver labels, Dynamic Type behavior, Reduce Transparency) are assessed manually via the audit template and tagged with confidence. -### Phase 3: Final Audit -Run the `hig_checker.py` tool to automate contrast and layout checks. +## Worked example: iOS settings-screen audit + +**Input:** mockup with body text `#1C1C1E` and captions `#8E8E93` on white cards, a 32x32 pt close button, and a 343x50 pt primary CTA. + +**Run:** + +```bash +python3 scripts/hig_checker.py batch audit.json +``` + +**Output (real):** + +```json +{ + "score": 80, + "violations": [ + "Contrast 3.26 fails for caption-on-card", + "Target 32x32 small for close-button" + ] +} +``` + +**Findings → fixes (bottom line first):** + +> **HIG score 80/100 — two fixes before release.** +> 1. Captions fail contrast (3.26 < 4.5). Use `.secondaryLabel` (semantic color) instead of hardcoded `#8E8E93`, or darken to ≥ `#6E6E73` on white. 🟢 verified by tool. +> 2. Close button is 32x32 pt (< 44x44 minimum). Keep the glyph small but expand the hit region to 44x44 with padding/`contentShape`. 🟢 verified by tool. +> 3. Manual check: the card uses an ultra-thin material over a photo background — re-test caption contrast against the *busiest* underlying region and with Reduce Transparency on. 🟡 needs device test. + +## Core Design Principles + +1. **Liquid Glass** — translucent material hierarchy (announced at WWDC25, June 2025; shipped Sept 2025 across iOS 26, iPadOS 26, macOS Tahoe, watchOS 26, tvOS 26, visionOS 26). In SwiftUI, apply it via the `glassEffect` view modifier; keep hierarchy between content and controls. See `references/visual-design.md`. +2. **Accessibility first** — VoiceOver labels on every element, 44x44 pt minimum targets, 4.5:1 contrast for normal text (3:1 large text), Dynamic Type support. See `references/accessibility.md`. +3. **Platform ergonomics** — tab bars/thumb reach on iOS, sidebars + menu bar + shortcuts on macOS, ornaments + gaze states on visionOS, glanceable vertical layouts on watchOS. See `references/platform-specifics.md`. ## Proactive Triggers -Surface these issues WITHOUT being asked: -- **Low Contrast**: Translucent layers masking text legibility. -- **Tiny Targets**: Interactive elements smaller than 44pt. -- **Missing Semantics**: Buttons with icons but no accessibility labels. -- **Density Overload**: Layouts that ignore white space/deference. - -## Output Artifacts - -| When you ask for... | You get... | -|---------------------|------------| -| "Audit my iOS app" | Detailed HIG Scorecard (0-100) with prioritized fixes. | -| "Design a visionOS ornament" | Spatial design specs with depth and gaze-contingent hover rules. | -| "Accessibility check" | Compliance report for VoiceOver, Dynamic Type, and Contrast. | +Surface these WITHOUT being asked: low contrast over translucent layers; interactive elements under 44 pt; icon buttons with no accessibility label; density overload (no breathing room between glass layers). ## Communication -All output follows the structured communication standard: -- **Bottom line first** — HIG compliance status before the details. -- **What + Why + How** — e.g., "Increase padding (What) because targets are too small (Why). Use 12pt margins (How)." -- **Confidence tagging** — 🟢 verified / 🟡 medium / 🔴 assumed. +- **Bottom line first** — compliance status before details. +- **What + Why + How** — "Expand the hit region (What) because 32 pt targets fail the HIG minimum (Why); pad to 44x44 via contentShape (How)." +- **Confidence tagging** — 🟢 tool-verified / 🟡 needs device test / 🔴 assumed. ## Related Skills -- **ui-design-system**: For creating token-based components. NOT for platform-specific HIG rules. -- **ux-researcher-designer**: For persona validation. NOT for visual styling. -- **landing-page-generator**: For web-based marketing pages. +- **ui-design-system**: token-based component systems (not platform HIG rules). +- **ux-researcher-designer**: persona/research validation (not visual styling). +- **landing-page-generator**: web marketing pages, not native apps. diff --git a/product-team/apple-hig-expert/skills/apple-hig-expert/references/accessibility.md b/product-team/apple-hig-expert/skills/apple-hig-expert/references/accessibility.md index aa32e44e..f6fa5422 100644 --- a/product-team/apple-hig-expert/skills/apple-hig-expert/references/accessibility.md +++ b/product-team/apple-hig-expert/skills/apple-hig-expert/references/accessibility.md @@ -44,3 +44,12 @@ Apps must respond to system-wide font size changes. - [ ] Is every icon labeled for VoiceOver? - [ ] Does the layout remain usable at the largest Dynamic Type size? - [ ] Have you tested with "Reduce Transparency" enabled in system settings? + + +## Sources + +- Apple HIG — Accessibility: https://developer.apple.com/design/human-interface-guidelines/accessibility +- Apple HIG — Buttons (44x44 pt minimum hit region): https://developer.apple.com/design/human-interface-guidelines/buttons +- Apple HIG — Typography (Dynamic Type text styles): https://developer.apple.com/design/human-interface-guidelines/typography +- Apple Accessibility for developers: https://developer.apple.com/accessibility/ +- WCAG 2.x contrast minimums (4.5:1 / 3:1), which the HIG color guidance mirrors: https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html diff --git a/product-team/apple-hig-expert/skills/apple-hig-expert/references/platform-specifics.md b/product-team/apple-hig-expert/skills/apple-hig-expert/references/platform-specifics.md index 1f8f78ef..3a80e17d 100644 --- a/product-team/apple-hig-expert/skills/apple-hig-expert/references/platform-specifics.md +++ b/product-team/apple-hig-expert/skills/apple-hig-expert/references/platform-specifics.md @@ -36,3 +36,13 @@ Designed for "Glances" — 2 to 5 second interactions. | **Input** | Touch / Voice | Mouse / Trackpad / Keys | Eyes (Gaze) / Hands | | **Typical Dist.** | 6 - 12 inches | 18 - 30 inches | Infinite (Arm's length) | | **Aesthetic** | High density | High precision | Spatially grounded | + + +## Sources + +- Apple HIG — Designing for iOS: https://developer.apple.com/design/human-interface-guidelines/designing-for-ios +- Apple HIG — Designing for macOS: https://developer.apple.com/design/human-interface-guidelines/designing-for-macos +- Apple HIG — Designing for visionOS: https://developer.apple.com/design/human-interface-guidelines/designing-for-visionos +- Apple HIG — Designing for watchOS: https://developer.apple.com/design/human-interface-guidelines/designing-for-watchos +- Apple HIG — Ornaments (visionOS): https://developer.apple.com/design/human-interface-guidelines/ornaments +- Apple HIG — Live Activities / Dynamic Island: https://developer.apple.com/design/human-interface-guidelines/live-activities diff --git a/product-team/apple-hig-expert/skills/apple-hig-expert/references/visual-design.md b/product-team/apple-hig-expert/skills/apple-hig-expert/references/visual-design.md index e95f4cdb..c8c088cf 100644 --- a/product-team/apple-hig-expert/skills/apple-hig-expert/references/visual-design.md +++ b/product-team/apple-hig-expert/skills/apple-hig-expert/references/visual-design.md @@ -1,6 +1,6 @@ # Visual Design Guide (Liquid Glass 2026) -This guide covers the visual language of the Apple ecosystem, centered on the **Liquid Glass** aesthetic introduced in late 2025. +This guide covers the visual language of the Apple ecosystem, centered on the **Liquid Glass** design language — announced at WWDC25 (June 9, 2025) and shipped in September 2025 with iOS 26, iPadOS 26, macOS Tahoe, watchOS 26, tvOS 26, and visionOS 26. In SwiftUI it is applied with the `glassEffect` view modifier. ## Core Aesthetic: Liquid Glass @@ -35,9 +35,11 @@ Apple uses the **San Francisco (SF)** family across all platforms. | Variant | Platform | Usage | |---------|----------|-------| | **SF Pro** | iOS, macOS | System standard for performance and legibility. | -| **SF Compact** | watchOS | Optimized for small screens. | -| **SF Camera** | iOS | Wide-set variant used in Camera interfaces. | -| **SF Mono** | Dev Tools | Monospaced variant for code. | +| **SF Compact** | watchOS | Optimized for small screens (the Camera app uses SF Compact Rounded as of iOS 26). | +| **SF Mono** | Dev tools | Monospaced variant for code. | +| **New York** | All | Serif companion family for editorial contexts. | + +Only the families on [developer.apple.com/fonts](https://developer.apple.com/fonts/) (SF Pro, SF Compact, SF Mono, SF Arabic/Hebrew and other language extensions, New York) are available to developers. "SF Camera" was an internal face used in Apple's Camera app, never a public download — do not specify it in design systems. ### Dynamic Type You MUST support Dynamic Type. @@ -54,3 +56,14 @@ All spacing should be increments of 8 (8pt, 16pt, 24pt, 32pt). ### Margin Logic - **iOS**: Match the Dynamic Island or Safe Area insets. - **watchOS**: Maximize the bezel-less display by using rounded corner layouts. + + +## Sources + +- Apple HIG — Materials: https://developer.apple.com/design/human-interface-guidelines/materials +- Apple HIG — Typography: https://developer.apple.com/design/human-interface-guidelines/typography +- Apple HIG — Color: https://developer.apple.com/design/human-interface-guidelines/color +- Apple HIG — Layout: https://developer.apple.com/design/human-interface-guidelines/layout +- Apple Fonts (official SF/New York downloads): https://developer.apple.com/fonts/ +- "Meet Liquid Glass" (WWDC25 session 219): https://developer.apple.com/videos/play/wwdc2025/219/ +- Apple Newsroom, June 9 2025 — new software design announcement: https://www.apple.com/newsroom/2025/06/apple-introduces-a-delightful-and-elegant-new-software-design/ diff --git a/product-team/code-to-prd/skills/code-to-prd/SKILL.md b/product-team/code-to-prd/skills/code-to-prd/SKILL.md index 3014a0a4..f9602518 100644 --- a/product-team/code-to-prd/skills/code-to-prd/SKILL.md +++ b/product-team/code-to-prd/skills/code-to-prd/SKILL.md @@ -1,25 +1,14 @@ --- -Name: code-to-prd -Tier: STANDARD -Category: product -Dependencies: none -Author: Alireza Rezvani -Version: 2.1.2 name: 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. - - Trigger when users mention: generate PRD, reverse-engineer requirements, code to documentation, - extract product specs from code, document page logic, analyze page fields and interactions, - create a functional inventory, write requirements from an existing codebase, document API endpoints, - or analyze backend routes. +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 logic, analyze page fields and interactions, create a functional inventory, write requirements from an existing codebase, document API endpoints, or analyze backend routes." license: MIT metadata: updated: 2026-03-17 + tier: STANDARD + category: product + dependencies: none + author: Alireza Rezvani + version: 2.1.2 --- ## Name diff --git a/product-team/research-summarizer/skills/research-summarizer/SKILL.md b/product-team/research-summarizer/skills/research-summarizer/SKILL.md index 158fa53e..814900a1 100644 --- a/product-team/research-summarizer/skills/research-summarizer/SKILL.md +++ b/product-team/research-summarizer/skills/research-summarizer/SKILL.md @@ -19,13 +19,16 @@ Not a generic "summarize this" — a repeatable framework that extracts what mat --- -## Slash Commands +## Scope — Distinct From the research/ Domain -| Command | What it does | -|---------|-------------| -| `/research:summarize` | Summarize a single source into a structured brief | -| `/research:compare` | Compare 2-5 sources side-by-side with synthesis | -| `/research:cite` | Extract and format all citations from a document | +This skill summarizes **documents the user already has** (papers, articles, reports pasted or attached). It performs no web search and needs no MCP server. It is NOT: + +- `research/litreview` — academic literature *discovery* and review-guide generation (finds papers via Consensus/academic APIs) +- `research/dossier` — entity due-diligence built from live web research +- `research/notebooklm` — drives Google's NotebookLM product UI +- `research/research` — the router for open-ended "research [topic]" requests that require searching + +If the user asks you to *find* sources rather than digest supplied ones, route to the research/ domain instead. --- @@ -47,7 +50,7 @@ If the user has a document and wants structured understanding → this skill app ## Workflow -### `/research:summarize` — Single Source Summary +### Workflow 1 — Single Source Summary 1. **Identify source type** - Academic paper → use IMRAD structure (Introduction, Methods, Results, Analysis, Discussion) @@ -55,7 +58,7 @@ If the user has a document and wants structured understanding → this skill app - Technical report → use executive summary structure - Documentation → use reference summary structure -2. **Extract structured brief** +2. **Scaffold the brief** — `python3 scripts/format_summary.py --template academic` (or `article`/`report`/`executive` per source type), then fill in every section from the source: ``` Title: [exact title] Author(s): [names] @@ -89,7 +92,7 @@ If the user has a document and wants structured understanding → this skill app - Recency (when published, still relevant?) - Bias indicators (funding source, author affiliation, methodology gaps) -### `/research:compare` — Multi-Source Comparison +### Workflow 2 — Multi-Source Comparison 1. **Collect sources** (2-5 documents) 2. **Summarize each** using the single-source workflow above @@ -126,10 +129,10 @@ If the user has a document and wants structured understanding → this skill app [Based on weight of evidence, what should the reader believe/do?] ``` -### `/research:cite` — Citation Extraction +### Workflow 3 — Citation Extraction -1. **Scan document** for all references, footnotes, in-text citations -2. **Extract and format** using the requested style (APA 7 default) +1. **Run the extractor** — `python3 scripts/extract_citations.py document.txt --output json` detects DOI/URL/author-year/numbered citations and deduplicates them +2. **Review and format** the extracted list in the requested style (APA 7 default); manually catch citations the regex missed 3. **Classify citations** by type: - Primary sources (original research, data) - Secondary sources (reviews, meta-analyses, commentary) @@ -174,13 +177,12 @@ cat paper.txt | python3 scripts/extract_citations.py --stdin ### `scripts/format_summary.py` -CLI utility for generating structured research summaries. +CLI utility that emits **blank structured summary scaffolds** — you (the model) fill them in from the source. It does not analyze content itself. **Features:** -- Multiple summary templates (academic, article, report, executive) -- Configurable output length (brief, standard, detailed) -- Markdown and plain text output -- Key findings extraction with evidence tagging +- 6 templates: academic, article, report, executive, comparison, literature +- Configurable scaffold depth (brief, standard, detailed) +- Text and JSON output for downstream tooling **Usage:** ```bash @@ -254,7 +256,7 @@ git clone https://github.com/alirezarezvani/claude-skills.git cp -r claude-skills/product-team/research-summarizer ~/.claude/skills/ ``` -### Multi-tool install +### Multi-tool install (run from the claude-skills repo root) ```bash ./scripts/convert.sh --skill research-summarizer --tool codex|gemini|cursor|windsurf|openclaw ``` @@ -266,6 +268,18 @@ clawhub install cs-research-summarizer --- +## Verification Loop + +Before delivering any brief, check: + +1. Every Key Finding cites a location in the source (section, page, or quote) — no unanchored claims. +2. `python3 scripts/extract_citations.py <file> --output json` exits 0 and its `total` matches the bibliography count in your output (investigate any gap). +3. Each source carries a 4-dimension quality rating (table above); weak sources are flagged, not silently included. +4. For comparisons: the matrix has one row per dimension and one column per source — no source skipped. +5. Nothing was invented: missing metadata is marked "not stated", never filled in. + +--- + ## Related Skills - **product-analytics** — Quantitative analysis. Complementary — use research-summarizer for qualitative sources, product-analytics for metrics. diff --git a/product-team/skills/landing-page-generator/SKILL.md b/product-team/skills/landing-page-generator/SKILL.md index dc6e0ea6..4546a045 100644 --- a/product-team/skills/landing-page-generator/SKILL.md +++ b/product-team/skills/landing-page-generator/SKILL.md @@ -30,7 +30,7 @@ Generate high-converting landing pages from a product description. Output comple Follow these steps in order for every landing page request: 1. **Gather inputs** — collect product name, tagline, audience, pain point, key benefit, pricing tiers, design style, and copy framework using the trigger format below. Ask only for missing fields. -2. **Analyze brand voice** (recommended) — if the user has existing brand content (website copy, blog posts, marketing materials), run it through `marketing-skill/content-production/scripts/brand_voice_analyzer.py` to get a voice profile (formality, tone, perspective). Use the profile to inform design style and copy framework selection: +2. **Analyze brand voice** (recommended) — if the user has existing brand content (website copy, blog posts, marketing materials), run it through `marketing-skill/skills/content-production/scripts/brand_voice_analyzer.py` to get a voice profile (formality, tone, perspective). Use the profile to inform design style and copy framework selection: - formal + professional → **enterprise** style, **AIDA** framework - casual + friendly → **bold-startup** style, **BAB** framework - professional + authoritative → **dark-saas** style, **PAS** framework @@ -193,6 +193,6 @@ Inject `FAQPage` JSON-LD via `<script type="application/ld+json" dangerouslySetI ## Related Skills -- **Brand Voice Analyzer** (`marketing-skill/content-production/scripts/brand_voice_analyzer.py`) — Run before generation to establish voice profile and ensure copy consistency +- **Brand Voice Analyzer** (`marketing-skill/skills/content-production/scripts/brand_voice_analyzer.py`) — Run before generation to establish voice profile and ensure copy consistency - **UI Design System** (`product-team/ui-design-system/`) — Generate design tokens from brand color before building the page - **Competitive Teardown** (`product-team/competitive-teardown/`) — Competitive positioning informs landing page messaging and differentiation diff --git a/product-team/skills/product-manager-toolkit/SKILL.md b/product-team/skills/product-manager-toolkit/SKILL.md index 47747df0..c6c36b51 100644 --- a/product-team/skills/product-manager-toolkit/SKILL.md +++ b/product-team/skills/product-manager-toolkit/SKILL.md @@ -1,6 +1,6 @@ --- name: "product-manager-toolkit" -description: Comprehensive toolkit for product managers including RICE prioritization, customer interview analysis, PRD templates, discovery frameworks, and go-to-market strategies. Use for feature prioritization, user research synthesis, requirement documentation, and product strategy development. +description: Comprehensive toolkit for product managers including RICE prioritization, customer interview analysis, PRD templates, discovery frameworks, and go-to-market strategies. Use when prioritizing features, synthesizing user research, writing requirement documentation, or developing product strategy. --- # Product Manager Toolkit diff --git a/product-team/skills/product-skills/SKILL.md b/product-team/skills/product-skills/SKILL.md index 191763be..6dc1e98b 100644 --- a/product-team/skills/product-skills/SKILL.md +++ b/product-team/skills/product-skills/SKILL.md @@ -1,6 +1,6 @@ --- name: "product-skills" -description: "10 product agent skills and plugins for Claude Code, Codex, Gemini CLI, Cursor, OpenClaw. PM toolkit (RICE), agile PO, product strategist (OKR), UX researcher, UI design system, competitive teardown, landing page generator, SaaS scaffolder, research summarizer. Python tools (stdlib-only)." +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 author: Alireza Rezvani license: MIT @@ -17,45 +17,45 @@ agents: - openclaw --- -# Product Team Skills +# Product Skills — Router -8 production-ready product skills covering product management, UX/UI design, and SaaS development. +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/`. -## Quick Start +## Routing table -### Claude Code -``` -/read product-team/product-manager-toolkit/SKILL.md -``` +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. -### Codex CLI -```bash -npx agent-skills-cli add alirezarezvani/claude-skills/product-team -``` +| 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/` | -## Skills Overview - -| Skill | Folder | Focus | -|-------|--------|-------| -| Product Manager Toolkit | `product-manager-toolkit/` | RICE prioritization, customer discovery, PRDs | -| Agile Product Owner | `agile-product-owner/` | User stories, sprint planning, backlog | -| Product Strategist | `product-strategist/` | OKR cascades, market analysis, vision | -| UX Researcher Designer | `ux-researcher-designer/` | Personas, journey maps, usability testing | -| UI Design System | `ui-design-system/` | Design tokens, component docs, responsive | -| Competitive Teardown | `competitive-teardown/` | Systematic competitor analysis | -| Landing Page Generator | `landing-page-generator/` | Conversion-optimized pages | -| SaaS Scaffolder | `saas-scaffolder/` | Production SaaS boilerplate | - -## Python Tools - -9 scripts, all stdlib-only: +## Quick start ```bash -python3 product-manager-toolkit/scripts/rice_prioritizer.py --help -python3 product-strategist/scripts/okr_cascade_generator.py --help +# 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 ``` +## Related product-team plugins (packaged separately, not in this bundle) + +- `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 + ## Rules -- Load only the specific skill SKILL.md you need -- Use Python tools for scoring and analysis, not manual judgment +- 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. diff --git a/product-team/skills/ui-design-system/SKILL.md b/product-team/skills/ui-design-system/SKILL.md index 17612d6f..c36af38e 100644 --- a/product-team/skills/ui-design-system/SKILL.md +++ b/product-team/skills/ui-design-system/SKILL.md @@ -1,6 +1,6 @@ --- name: "ui-design-system" -description: UI design system toolkit for Senior UI Designer including design token generation, component documentation, responsive design calculations, and developer handoff tools. Use for creating design systems, maintaining visual consistency, and facilitating design-dev collaboration. +description: UI design system toolkit for Senior UI Designer including design token generation, component documentation, responsive design calculations, and developer handoff tools. Use when creating design systems, generating design tokens, maintaining visual consistency, or facilitating design-dev collaboration and developer handoff. --- # UI Design System diff --git a/product-team/skills/ux-researcher-designer/SKILL.md b/product-team/skills/ux-researcher-designer/SKILL.md index 51fa525f..b68b9cad 100644 --- a/product-team/skills/ux-researcher-designer/SKILL.md +++ b/product-team/skills/ux-researcher-designer/SKILL.md @@ -1,6 +1,6 @@ --- name: "ux-researcher-designer" -description: UX research and design toolkit for Senior UX Designer/Researcher including data-driven persona generation, journey mapping, usability testing frameworks, and research synthesis. Use for user research, persona creation, journey mapping, and design validation. +description: UX research and design toolkit for Senior UX Designer/Researcher including data-driven persona generation, journey mapping, usability testing frameworks, and research synthesis. Use when conducting user research, creating personas, mapping user journeys, planning usability tests, or validating designs. --- # UX Researcher & Designer diff --git a/productivity/andreessen/agents/cs-andreessen.md b/productivity/andreessen/agents/cs-andreessen.md index e4786881..bd9b2fab 100644 --- a/productivity/andreessen/agents/cs-andreessen.md +++ b/productivity/andreessen/agents/cs-andreessen.md @@ -73,17 +73,17 @@ Differentiates from siblings: ### Python Tools (Stdlib) -1. **Market-First Evaluator** — `scripts/market_first_evaluator.py` — weighted market > team > +1. **Market-First Evaluator** — `skills/andreessen/scripts/market_first_evaluator.py` — weighted market > team > product; sub-4 market is a hard kill gate. -2. **PMF Signal Scorer** — `scripts/pmf_signal_scorer.py` — 4 qualitative signals + Sean Ellis 40% gate. -3. **Anti-Todo 3x5 Card** — `scripts/anti_todo_card.py` — front capped at 3-5, back is the Anti-Todo log. +2. **PMF Signal Scorer** — `skills/andreessen/scripts/pmf_signal_scorer.py` — 4 qualitative signals + Sean Ellis 40% gate. +3. **Anti-Todo 3x5 Card** — `skills/andreessen/scripts/anti_todo_card.py` — front capped at 3-5, back is the Anti-Todo log. ### Knowledge Bases -- `references/operating_prompt.md` — verbatim operating prompt + posture mapping (5 sources) -- `references/market_first_canon.md` — market > team > product (7 sources) -- `references/pmf_and_build_canon.md` — PMF phases + Ellis 40% + "It's Time to Build" (7 sources) -- `references/personal_productivity_system.md` — 3x5 card + Anti-Todo + scheduling reversal (7 sources) +- `skills/andreessen/references/operating_prompt.md` — verbatim operating prompt + posture mapping (5 sources) +- `skills/andreessen/references/market_first_canon.md` — market > team > product (7 sources) +- `skills/andreessen/references/pmf_and_build_canon.md` — PMF phases + Ellis 40% + "It's Time to Build" (7 sources) +- `skills/andreessen/references/personal_productivity_system.md` — 3x5 card + Anti-Todo + scheduling reversal (7 sources) ## Related Agents diff --git a/productivity/capture/agents/cs-capture.md b/productivity/capture/agents/cs-capture.md index 9a4a6ab2..852c6536 100644 --- a/productivity/capture/agents/cs-capture.md +++ b/productivity/capture/agents/cs-capture.md @@ -35,10 +35,10 @@ The cs-capture agent orchestrates the `capture` skill across brain-dump-organize 1. **Detect the trigger** — explicit phrase OR implicit unstructured block paste 2. **Capture everything** — no item is too trivial; user prunes later -3. **Classify items** — task vs decision vs question vs project-component (use `scripts/dump_classifier.py` as a heuristic seed) +3. **Classify items** — task vs decision vs question vs project-component (use `skills/capture/scripts/dump_classifier.py` as a heuristic seed) 4. **Cluster** — only when natural clustering exists; don't force structure on small dumps -5. **Inventory the workspace** — `scripts/workspace_inventory.py` for real Glob+Grep matches; never fabricate -6. **Compress when warranted** — `scripts/complexity_estimator.py` recommends full 4-section vs compressed +5. **Inventory the workspace** — `skills/capture/scripts/workspace_inventory.py` for real Glob+Grep matches; never fabricate +6. **Compress when warranted** — `skills/capture/scripts/complexity_estimator.py` recommends full 4-section vs compressed 7. **Deliver + wait** — output the sections; wait for the user's pick before any further action Differentiates clearly: @@ -193,8 +193,8 @@ Which should I tackle? ## Related Agents -- [cs-grill-master](../../grill-me/agents/cs-grill-master.md) — slow, deliberate plan interrogator (different mode) -- [cs-grill-with-docs](../../grill-with-docs/agents/cs-grill-with-docs.md) — docs-anchored grill (different scope) +- [cs-grill-master](engineering/grill-me/agents/cs-grill-master.md) — slow, deliberate plan interrogator (different mode) +- [cs-grill-with-docs](engineering/grill-with-docs/agents/cs-grill-with-docs.md) — docs-anchored grill (different scope) - [cs-handoff-author](../../handoff/agents/cs-handoff-author.md) — different artifact (continuation prompt) ## References diff --git a/productivity/email/agents/cs-inbox-setup.md b/productivity/email/agents/cs-inbox-setup.md index c3a7371c..db784534 100644 --- a/productivity/email/agents/cs-inbox-setup.md +++ b/productivity/email/agents/cs-inbox-setup.md @@ -1,7 +1,7 @@ --- name: cs-inbox-setup description: One-time email-triage onboarding persona. Conducts an 8-section interactive interview (~25-31 grill-me questions) to build a personalized knowledge base of 7 markdown files in ${WORKSPACE}/Email/ that powers the companion inbox-triage skill. Refuses to batch questions. Refuses to skip the sample-emails ask (S3). Refuses to overwrite existing files without per-file consent on re-run. Refuses to persist sensitive credentials. -skills: engineering/email/skills/inbox-setup +skills: productivity/email/skills/inbox-setup domain: productivity model: opus tools: [Read, Write, Edit, Bash, Glob, Grep] @@ -61,30 +61,30 @@ Differentiates clearly: ## Skill Integration -**Skill Location:** `../../skills/inbox-setup/` +**Skill Location:** `../skills/inbox-setup/` ### Python Tools (Stdlib) 1. **KB Validator** - - Path: `../../skills/inbox-setup/scripts/kb_validator.py` + - Path: `../skills/inbox-setup/scripts/kb_validator.py` - Usage: `python kb_validator.py --workspace ${WORKSPACE}` - Validates the 7-file KB structure (required files present, conditional files only if their sections exist, headers + bold-section markers correct). 2. **Section Progress Tracker** - - Path: `../../skills/inbox-setup/scripts/section_progress_tracker.py` + - Path: `../skills/inbox-setup/scripts/section_progress_tracker.py` - Usage: `python section_progress_tracker.py --action {start,record_q,record_section_done,status,close}` - JSON-backed walk state at `~/.inbox_setup_sessions/<session>.json`. Tracks which section is active, which questions answered, which files committed. 3. **Voice Sample Analyzer** - - Path: `../../skills/inbox-setup/scripts/voice_sample_analyzer.py` + - Path: `../skills/inbox-setup/scripts/voice_sample_analyzer.py` - Usage: `python voice_sample_analyzer.py --samples-file /tmp/samples.txt` - Extracts voice patterns from pasted sent-email samples: opening phrases, sign-offs, sentence length, sentence-types, casual/formal markers. ### Knowledge Bases -- `../../skills/inbox-setup/references/kb_file_contract.md` — the canonical 7-file contract (write perspective) -- `../../skills/inbox-setup/references/grill_me_section_walk.md` — 8-section discipline + skip-logic + commit-per-section -- `../../skills/inbox-setup/references/voice_calibration.md` — sample-based voice extraction theory + anti-patterns +- `../skills/inbox-setup/references/kb_file_contract.md` — the canonical 7-file contract (write perspective) +- `../skills/inbox-setup/references/grill_me_section_walk.md` — 8-section discipline + skip-logic + commit-per-section +- `../skills/inbox-setup/references/voice_calibration.md` — sample-based voice extraction theory + anti-patterns ## Workflows @@ -95,26 +95,26 @@ Differentiates clearly: ls ${WORKSPACE}/Email/ 2>/dev/null # confirm fresh state # 2. Start session -python ../../skills/inbox-setup/scripts/section_progress_tracker.py \ +python ../skills/inbox-setup/scripts/section_progress_tracker.py \ --action start --session "inbox-setup-$(date +%Y%m%d)" --user "<who>" # 3. Walk S1 → S2 → ... → S8 with grill-me discipline # For each Q: ask, wait for answer, record: -python ../../skills/inbox-setup/scripts/section_progress_tracker.py \ +python ../skills/inbox-setup/scripts/section_progress_tracker.py \ --action record_q --session NAME --section 1 --question 1 --answer "..." # 4. End of S2: write email-taxonomy.md; record commit: -python ../../skills/inbox-setup/scripts/section_progress_tracker.py \ +python ../skills/inbox-setup/scripts/section_progress_tracker.py \ --action record_section_done --session NAME --section 2 --files "email-taxonomy.md" # 5. S3 includes sample collection; analyze: -python ../../skills/inbox-setup/scripts/voice_sample_analyzer.py --samples-file /tmp/samples.txt +python ../skills/inbox-setup/scripts/voice_sample_analyzer.py --samples-file /tmp/samples.txt # 6. At S8: validate final state: -python ../../skills/inbox-setup/scripts/kb_validator.py --workspace ${WORKSPACE} +python ../skills/inbox-setup/scripts/kb_validator.py --workspace ${WORKSPACE} # 7. Close session: -python ../../skills/inbox-setup/scripts/section_progress_tracker.py --action close --session NAME +python ../skills/inbox-setup/scripts/section_progress_tracker.py --action close --session NAME ``` ### Workflow 2: Re-run on existing setup @@ -196,7 +196,7 @@ Re-run /cs:inbox-setup when business/pricing/priorities change. ## References -- Skill: [../../skills/inbox-setup/SKILL.md](../../skills/inbox-setup/SKILL.md) +- Skill: [../skills/inbox-setup/SKILL.md](../skills/inbox-setup/SKILL.md) - Source spec: [`megaprompts/06-inbox-setup-megaprompt.md`](../../../../megaprompts/06-inbox-setup-megaprompt.md) - Sibling command: [`/cs:inbox-setup`](../commands/cs-inbox-setup.md) diff --git a/productivity/email/agents/cs-inbox-triage.md b/productivity/email/agents/cs-inbox-triage.md index 7d08c6fc..a5d03663 100644 --- a/productivity/email/agents/cs-inbox-triage.md +++ b/productivity/email/agents/cs-inbox-triage.md @@ -1,7 +1,7 @@ --- name: cs-inbox-triage description: Recurring email-triage execution persona. Reads the 7-file KB produced by inbox-setup, classifies recent emails via the user's taxonomy, researches new senders, generates recommendations, drafts replies, delivers a report, and updates the KB with learnings. NEVER SENDS — drafts only, non-negotiable. Halts with clear message if KB files are missing (directs user to run inbox-setup first). Light-intake — max 2 optional override questions. -skills: engineering/email/skills/inbox-triage +skills: productivity/email/skills/inbox-triage domain: productivity model: opus tools: [Read, Write, Edit, Bash, Glob, Grep, WebFetch, WebSearch] @@ -58,30 +58,30 @@ Differentiates clearly: ## Skill Integration -**Skill Location:** `../../skills/inbox-triage/` +**Skill Location:** `../skills/inbox-triage/` ### Python Tools (Stdlib) 1. **KB Reader** - - Path: `../../skills/inbox-triage/scripts/kb_reader.py` + - Path: `../skills/inbox-triage/scripts/kb_reader.py` - Usage: `python kb_reader.py --workspace ${WORKSPACE}` - Reads + validates the 7 KB files. Returns parsed structure (categories, voice patterns, blocklist, tracker entries). Halts with explicit error if required files missing. 2. **Search Window Calculator** - - Path: `../../skills/inbox-triage/scripts/search_window_calculator.py` + - Path: `../skills/inbox-triage/scripts/search_window_calculator.py` - Usage: `python search_window_calculator.py --cadence 2x-daily --now 2026-05-15T14:00` - Computes window_start from cadence + current time. Default 9h for 2x/day (slight overlap prevents missed emails). Returns run_label (Morning/Afternoon/Evening) based on hour-of-day. 3. **Draft Safety Validator** - - Path: `../../skills/inbox-triage/scripts/draft_safety_validator.py` + - Path: `../skills/inbox-triage/scripts/draft_safety_validator.py` - Usage: `python draft_safety_validator.py --action-log /path/to/triage-log.md` - Scans the triage log for any send-shaped action (`send_email`, `gmail.send`, `outlook.send`, etc.). FAILs if any are detected. The non-negotiable NEVER-SEND check in tool form. ### Knowledge Bases -- `../../skills/inbox-triage/references/kb_file_contract.md` — canonical 7-file contract (read perspective; mirrors the setup-side version) -- `../../skills/inbox-triage/references/triage_decision_framework.md` — TAKE IT / WORTH CONSIDERING / PASS / FLAG FOR REVIEW taxonomy -- `../../skills/inbox-triage/references/drafts_only_safety.md` — the NEVER-SEND discipline canon +- `../skills/inbox-triage/references/kb_file_contract.md` — canonical 7-file contract (read perspective; mirrors the setup-side version) +- `../skills/inbox-triage/references/triage_decision_framework.md` — TAKE IT / WORTH CONSIDERING / PASS / FLAG FOR REVIEW taxonomy +- `../skills/inbox-triage/references/drafts_only_safety.md` — the NEVER-SEND discipline canon ## Workflows @@ -89,11 +89,11 @@ Differentiates clearly: ```bash # 1. Pre-flight — read + validate KB -python ../../skills/inbox-triage/scripts/kb_reader.py --workspace ${WORKSPACE} +python ../skills/inbox-triage/scripts/kb_reader.py --workspace ${WORKSPACE} # If FAIL → halt + direct to setup # 2. Determine window -python ../../skills/inbox-triage/scripts/search_window_calculator.py \ +python ../skills/inbox-triage/scripts/search_window_calculator.py \ --cadence 2x-daily --now $(date -u +%Y-%m-%dT%H:%M) # 3. Execute 10-step workflow (described in SKILL.md): @@ -109,7 +109,7 @@ python ../../skills/inbox-triage/scripts/search_window_calculator.py \ # Step 10: empty-inbox handling # 4. Post-flight — validate no send action occurred -python ../../skills/inbox-triage/scripts/draft_safety_validator.py \ +python ../skills/inbox-triage/scripts/draft_safety_validator.py \ --action-log ${WORKSPACE}/Email/triage-log/$(date +%Y-%m-%d)-*.md # If FAIL → halt + alert user immediately ``` @@ -199,7 +199,7 @@ Generated at <timestamp>. KB updated: {N blocklist, M tracker}. ## References -- Skill: [../../skills/inbox-triage/SKILL.md](../../skills/inbox-triage/SKILL.md) +- Skill: [../skills/inbox-triage/SKILL.md](../skills/inbox-triage/SKILL.md) - Source spec: [`megaprompts/07-inbox-triage-megaprompt.md`](../../../../megaprompts/07-inbox-triage-megaprompt.md) - Sibling command: [`/cs:inbox-triage`](../commands/cs-inbox-triage.md) diff --git a/productivity/email/skills/inbox-triage/SKILL.md b/productivity/email/skills/inbox-triage/SKILL.md index 605b613d..8d14a4dc 100644 --- a/productivity/email/skills/inbox-triage/SKILL.md +++ b/productivity/email/skills/inbox-triage/SKILL.md @@ -1,6 +1,6 @@ --- name: 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 demand. Triggers: 'triage my inbox', 'inbox triage', 'check my email', 'run email triage', 'process my inbox', 'what's new in my email', 'handle my email', 'email triage', or any variation where the user wants their inbox processed. Requires the inbox-setup skill to have been run first." +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 demand. Use when the user wants their inbox processed, in any variation (e.g., 'triage my inbox', 'inbox triage', 'check my email', 'run email triage', 'process my inbox', 'what's new in my email', 'handle my email', 'email triage'). Requires the inbox-setup skill to have been run first." license: MIT metadata: source_spec: "megaprompts/07-inbox-triage-megaprompt.md" @@ -289,7 +289,7 @@ Skip Steps 3–6 entirely on empty inbox. ## References -- [`references/kb_file_contract.md`](references/kb_file_contract.md) — canonical 7-file contract (read perspective; mirrors `inbox-setup/references/kb_file_contract.md`) +- [`references/kb_file_contract.md`](references/kb_file_contract.md) — canonical 7-file contract (read perspective; mirrors `../inbox-setup/references/kb_file_contract.md`) - [`references/triage_decision_framework.md`](references/triage_decision_framework.md) — TAKE IT / WORTH / PASS / FLAG taxonomy - [`references/drafts_only_safety.md`](references/drafts_only_safety.md) — the NEVER-SEND discipline canon diff --git a/productivity/handoff/agents/cs-handoff-author.md b/productivity/handoff/agents/cs-handoff-author.md index 05a50111..a0cec553 100644 --- a/productivity/handoff/agents/cs-handoff-author.md +++ b/productivity/handoff/agents/cs-handoff-author.md @@ -22,7 +22,7 @@ You do not narrate the conversation. You compress it to **State of play** + **Op 3. **3-5 skills, hard cap.** If you find yourself listing more, you haven't picked. Choose. 4. **Every State bullet references an artifact.** If you can't name a commit / PR / file / issue, the item isn't done. Reclassify as Open decision. 5. **Run the redaction linter before save.** Strict mode by default. Whitelist false positives inline with the marker, never with silence. -6. **Save to the configured location.** Read config via `scripts/config_loader.py`. If first-run setup hasn't completed, propose it once: *"Run setup now? (Y/n)"*. Do not silently pick a location. +6. **Save to the configured location.** Read config via `skills/handoff/scripts/config_loader.py`. If first-run setup hasn't completed, propose it once: *"Run setup now? (Y/n)"*. Do not silently pick a location. ## Anti-patterns diff --git a/productivity/handoff/skills/handoff/references/redaction_checklist.md b/productivity/handoff/skills/handoff/references/redaction_checklist.md index 4bc22fac..11719a33 100644 --- a/productivity/handoff/skills/handoff/references/redaction_checklist.md +++ b/productivity/handoff/skills/handoff/references/redaction_checklist.md @@ -24,6 +24,7 @@ The `redaction_linter.py` script automates the regex-catchable patterns. This do | Email address | `name@example.com` | medium | | Phone number | various formats | low | | URL with token query param | `https://api/?token=...` | high | +| Private IP / CIDR | `10.0.1.5`, `192.168.1.0/24` | low | The phone-number regex has high false-positive rate (version strings, long IDs); it is intentionally low-severity and surfaced for review rather than automatic block. diff --git a/productivity/handoff/skills/handoff/scripts/redaction_linter.py b/productivity/handoff/skills/handoff/scripts/redaction_linter.py index 061f3ad6..33bd038f 100644 --- a/productivity/handoff/skills/handoff/scripts/redaction_linter.py +++ b/productivity/handoff/skills/handoff/scripts/redaction_linter.py @@ -123,6 +123,16 @@ PATTERNS: list[Pattern] = [ re.compile(r"https?://[^\s'\"<>]*(?:[?&](?:token|access_token|api_key|key)=)[^\s'\"<>&]+"), "Strip the token query parameter from the URL.", ), + Pattern( + "private_cidr", + re.compile( + r"(?<![\d.])(?:10\.\d{1,3}\.\d{1,3}\.\d{1,3}" + r"|192\.168\.\d{1,3}\.\d{1,3}" + r"|172\.(?:1[6-9]|2\d|3[01])\.\d{1,3}\.\d{1,3})(?:/\d{1,2})?(?![\d.])" + ), + "Redact internal IP addresses / CIDR ranges; reference the host by role instead.", + "low", + ), ] @@ -199,6 +209,27 @@ def _format_human(report: Report, mode: str, path: Path) -> str: return "\n".join(lines) +def _report_json(report, mode: str, file_label: str) -> str: + return json.dumps( + { + "file": file_label, + "mode": mode, + "findings": [ + { + "line": f.line_number, + "pattern": f.pattern_name, + "severity": f.severity, + "match": f.match, + "suggestion": f.suggestion, + } + for f in report.findings + ], + "counts": report.by_severity(), + }, + indent=2, + ) + + def main(argv: list[str] | None = None) -> int: parser = argparse.ArgumentParser(description="Scan a handoff draft for secrets and PII.") parser.add_argument("file", nargs="?", help="Path to the handoff markdown file.") @@ -227,7 +258,10 @@ def main(argv: list[str] | None = None) -> int: "Allowed: AKIAIOSFODNN7EXAMPLE <!-- handoff:allow secret -->\n" ) report = scan_text(fixture) - print(_format_human(report, "strict", Path("<sample>"))) + if args.json: + print(_report_json(report, "strict", "<sample>")) + else: + print(_format_human(report, "strict", Path("<sample>"))) return 1 if report.findings else 0 if args.mode == "off": @@ -245,26 +279,7 @@ def main(argv: list[str] | None = None) -> int: report = scan_file(path) if args.json: - print( - json.dumps( - { - "file": str(path), - "mode": args.mode, - "findings": [ - { - "line": f.line_number, - "pattern": f.pattern_name, - "severity": f.severity, - "match": f.match, - "suggestion": f.suggestion, - } - for f in report.findings - ], - "counts": report.by_severity(), - }, - indent=2, - ) - ) + print(_report_json(report, args.mode, str(path))) else: print(_format_human(report, args.mode, path)) diff --git a/productivity/reflect/agents/cs-reflect.md b/productivity/reflect/agents/cs-reflect.md index 1561b3bd..f9bc433d 100644 --- a/productivity/reflect/agents/cs-reflect.md +++ b/productivity/reflect/agents/cs-reflect.md @@ -64,15 +64,15 @@ Differentiates from siblings: ### Python Tools (Stdlib) -1. **Bias Pattern Detector** — `scripts/bias_pattern_detector.py` — given conversation text, scan for patterns indicative of each of the 5 biases -2. **Conversation Depth Analyzer** — `scripts/conversation_depth_analyzer.py` — counts turns, detects implicit-trigger signals (10+ detail turns, frustration markers, repeated dead-ends) -3. **Directional Recommendation Validator** — `scripts/directional_recommendation_validator.py` — verifies output ends with Continue / Pivot / Pause + specific reasoning (not vague reassurance) +1. **Bias Pattern Detector** — `skills/reflect/scripts/bias_pattern_detector.py` — given conversation text, scan for patterns indicative of each of the 5 biases +2. **Conversation Depth Analyzer** — `skills/reflect/scripts/conversation_depth_analyzer.py` — counts turns, detects implicit-trigger signals (10+ detail turns, frustration markers, repeated dead-ends) +3. **Directional Recommendation Validator** — `skills/reflect/scripts/directional_recommendation_validator.py` — verifies output ends with Continue / Pivot / Pause + specific reasoning (not vague reassurance) ### Knowledge Bases -- `references/cognitive_bias_canon.md` — 5 biases + recognition cues (7+ sources) -- `references/honest_output_discipline.md` — anti-manufactured-problems framing (7+ sources) -- `references/conversation_reflection_practice.md` — Schön reflective-practice canon (7+ sources) +- `skills/reflect/references/cognitive_bias_canon.md` — 5 biases + recognition cues (7+ sources) +- `skills/reflect/references/honest_output_discipline.md` — anti-manufactured-problems framing (7+ sources) +- `skills/reflect/references/conversation_reflection_practice.md` — Schön reflective-practice canon (7+ sources) ## Related Agents diff --git a/project-management/CLAUDE.md b/project-management/CLAUDE.md index 3cdd91a7..cd0d5445 100644 --- a/project-management/CLAUDE.md +++ b/project-management/CLAUDE.md @@ -21,23 +21,25 @@ This guide covers the 9 production-ready project management skills, 12 Python au **Purpose:** Direct integration with Jira and Confluence via Model Context Protocol (MCP) -**Capabilities:** -- Create, read, update Jira issues -- Manage Confluence pages and spaces -- Automate workflows and transitions -- Generate reports and dashboards -- Bulk operations on issues +**Canonical tool list:** [references/atlassian-mcp-tools.md](references/atlassian-mcp-tools.md) — the single source of truth for real tool names. Never invent tool names; if a capability isn't in that list (project creation, sprint management, field configuration, automation rules, space creation, …), it is NOT available via MCP — use the Atlassian web UI or REST API. -**Setup:** Atlassian MCP server configured in Claude Code settings +**Capabilities (real tools, camelCase):** +- Jira issues: `createJiraIssue`, `getJiraIssue`, `editJiraIssue`, `searchJiraIssuesUsingJql`, `transitionJiraIssue`, `addCommentToJiraIssue`, `createIssueLink` +- Confluence pages: `createConfluencePage`, `getConfluencePage`, `updateConfluencePage`, `searchConfluenceUsingCql`, `getConfluencePageDescendants` +- Discovery: `getAccessibleAtlassianResources` (get `cloudId` first), `getVisibleJiraProjects`, `getConfluenceSpaces` + +**Setup:** Bundled `.mcp.json` registers the `atlassian` SSE server; tools surface as `mcp__atlassian__<toolName>`. **Usage Pattern:** -```bash -# Jira operations via MCP -mcp__atlassian__create_issue project="PROJ" summary="New feature" type="Story" - -# Confluence operations via MCP -mcp__atlassian__create_page space="TEAM" title="Sprint Retrospective" ``` +# Jira: create an issue (call getAccessibleAtlassianResources first to obtain cloudId) +mcp__atlassian__createJiraIssue (cloudId, projectKey="PROJ", issueTypeName="Story", summary="New feature") + +# Confluence: create a page (body must be storage-format XHTML or ADF, not wiki markup) +mcp__atlassian__createConfluencePage (cloudId, space, title="Sprint Retrospective", body=<storage-format XHTML>) +``` + +**Not available via MCP** (use web UI/REST API): project creation, sprints, boards, filters, space creation, page deletion, labels, field/workflow/permission configuration, user provisioning, automation rules. ## Skill-Specific Guidance @@ -121,24 +123,26 @@ mcp__atlassian__create_page space="TEAM" title="Sprint Retrospective" ### Pattern 1: Sprint Planning ```bash -# 1. Create sprint in Jira (via MCP) -mcp__atlassian__create_sprint board="TEAM-board" name="Sprint 23" start="2025-11-06" +# 1. Create the sprint in the Jira board UI (sprint creation is NOT available via MCP — +# use Jira Software UI or REST /rest/agile/1.0/sprint) # 2. Generate user stories (product-team integration) python ../product-team/agile-product-owner/scripts/user_story_generator.py sprint 30 -# 3. Import stories to Jira -# (Manual or via Jira API integration) +# 3. Import stories to Jira via MCP: one mcp__atlassian__createJiraIssue call per story +# (cloudId, projectKey, issueTypeName="Story", summary, description) ``` ### Pattern 2: Documentation Workflow ```bash -# 1. Create Confluence page template -mcp__atlassian__create_page space="DOCS" title="Feature Spec" template="feature-spec" +# 1. Scaffold storage-format XHTML, then create the Confluence page via MCP +python skills/atlassian-templates/scripts/template_scaffolder.py meeting-notes +# → pass the emitted markup as the body of mcp__atlassian__createConfluencePage -# 2. Link to Jira epic -mcp__atlassian__link_issue issue="PROJ-123" confluence_page_id="456789" +# 2. Link the page to a Jira issue: paste the page URL into the issue via +# mcp__atlassian__editJiraIssue or as a comment via mcp__atlassian__addCommentToJiraIssue +# (read existing links with mcp__atlassian__getJiraIssueRemoteIssueLinks) ``` ## Python Automation Tools @@ -175,7 +179,7 @@ python atlassian-templates/scripts/template_scaffolder.py meeting-notes --- -**Last Updated:** May 10, 2026 +**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 diff --git a/project-management/README.md b/project-management/README.md index 9587f8c5..7f13e266 100644 --- a/project-management/README.md +++ b/project-management/README.md @@ -38,22 +38,22 @@ npx ai-agent-skills install alirezarezvani/claude-skills/project-management --ag ```bash # Senior Project Manager Expert -npx ai-agent-skills install alirezarezvani/claude-skills/project-management/senior-pm +npx ai-agent-skills install alirezarezvani/claude-skills/project-management/skills/senior-pm # Scrum Master Expert -npx ai-agent-skills install alirezarezvani/claude-skills/project-management/scrum-master +npx ai-agent-skills install alirezarezvani/claude-skills/project-management/skills/scrum-master # Atlassian Jira Expert -npx ai-agent-skills install alirezarezvani/claude-skills/project-management/jira-expert +npx ai-agent-skills install alirezarezvani/claude-skills/project-management/skills/jira-expert # Atlassian Confluence Expert -npx ai-agent-skills install alirezarezvani/claude-skills/project-management/confluence-expert +npx ai-agent-skills install alirezarezvani/claude-skills/project-management/skills/confluence-expert # Atlassian Administrator -npx ai-agent-skills install alirezarezvani/claude-skills/project-management/atlassian-admin +npx ai-agent-skills install alirezarezvani/claude-skills/project-management/skills/atlassian-admin # Atlassian Template Creator -npx ai-agent-skills install alirezarezvani/claude-skills/project-management/atlassian-templates +npx ai-agent-skills install alirezarezvani/claude-skills/project-management/skills/atlassian-templates ``` **Supported Agents:** Claude Code, Cursor, VS Code, Copilot, Goose, Amp, Codex @@ -272,20 +272,24 @@ The plugin bundles a pre-configured `.mcp.json` pointing at Atlassian's official ### Example Operations -> **Note:** Tool names below are shown in simplified form for readability. The actual Claude Code prefix for plugin-bundled MCP tools is `mcp__plugin_pm-skills_atlassian__<tool>` — e.g. `mcp__plugin_pm-skills_atlassian__create_issue`. Both the simplified and fully-qualified forms refer to the same tool. +> **Note:** Real tool names are camelCase and surface in Claude Code as `mcp__atlassian__<toolName>` (server key `atlassian` from the bundled `.mcp.json`; plugin-loaded installs may use a plugin-scoped prefix with the same trailing tool name). The canonical tool list lives in [references/atlassian-mcp-tools.md](references/atlassian-mcp-tools.md) — never invent tool names; capabilities not in that list (project/sprint/filter/space creation, field configuration, automation rules) are not available via MCP and require the Atlassian web UI or REST API. ```bash +# Discover accessible sites first (most tools require cloudId) +mcp__atlassian__getAccessibleAtlassianResources + # Create Jira issue -mcp__atlassian__create_issue project="PROJ" summary="New feature" type="Story" +mcp__atlassian__createJiraIssue (cloudId, projectKey="PROJ", issueTypeName="Story", summary="New feature") -# Update issue status -mcp__atlassian__transition_issue key="PROJ-123" status="In Progress" +# Update issue status (look up the transition id first) +mcp__atlassian__getTransitionsForJiraIssue (cloudId, issueIdOrKey="PROJ-123") +mcp__atlassian__transitionJiraIssue (cloudId, issueIdOrKey="PROJ-123", transition=<id>) -# Create Confluence page -mcp__atlassian__create_page space="TEAM" title="Sprint Retrospective" content="..." +# Create Confluence page (body = storage-format XHTML or ADF) +mcp__atlassian__createConfluencePage (cloudId, space, title="Sprint Retrospective", body="...") # Run JQL query -mcp__atlassian__search_issues jql="project = PROJ AND status = 'In Progress'" +mcp__atlassian__searchJiraIssuesUsingJql (cloudId, jql="project = PROJ AND status = 'In Progress'") ``` **Learn More:** See [IMPLEMENTATION_SUMMARY.md](IMPLEMENTATION_SUMMARY.md) for MCP integration details @@ -298,7 +302,7 @@ mcp__atlassian__search_issues jql="project = PROJ AND status = 'In Progress'" 1. **Install Senior PM Expert:** ```bash - npx ai-agent-skills install alirezarezvani/claude-skills/project-management/senior-pm + npx ai-agent-skills install alirezarezvani/claude-skills/project-management/skills/senior-pm ``` 2. **Use project charter template** from Atlassian Templates skill @@ -309,7 +313,7 @@ mcp__atlassian__search_issues jql="project = PROJ AND status = 'In Progress'" 1. **Install Scrum Master Expert:** ```bash - npx ai-agent-skills install alirezarezvani/claude-skills/project-management/scrum-master + npx ai-agent-skills install alirezarezvani/claude-skills/project-management/skills/scrum-master ``` 2. **Use sprint planning template** for next sprint @@ -320,7 +324,7 @@ mcp__atlassian__search_issues jql="project = PROJ AND status = 'In Progress'" 1. **Install Jira Expert:** ```bash - npx ai-agent-skills install alirezarezvani/claude-skills/project-management/jira-expert + npx ai-agent-skills install alirezarezvani/claude-skills/project-management/skills/jira-expert ``` 2. **Configure custom workflows** for your team @@ -331,7 +335,7 @@ mcp__atlassian__search_issues jql="project = PROJ AND status = 'In Progress'" 1. **Install Confluence Expert:** ```bash - npx ai-agent-skills install alirezarezvani/claude-skills/project-management/confluence-expert + npx ai-agent-skills install alirezarezvani/claude-skills/project-management/skills/confluence-expert ``` 2. **Design space architecture** for your organization diff --git a/project-management/references/atlassian-mcp-tools.md b/project-management/references/atlassian-mcp-tools.md new file mode 100644 index 00000000..be4b0a74 --- /dev/null +++ b/project-management/references/atlassian-mcp-tools.md @@ -0,0 +1,97 @@ +# Atlassian Remote MCP — Canonical Tool Reference + +**This is the single source of truth for Atlassian MCP tool names in the project-management domain.** Tool names verified live against the production Atlassian Remote MCP server (`https://mcp.atlassian.com/v1/sse`, bundled via this plugin's `.mcp.json`) on 2026-06-10. + +## How tools are addressed + +The bundled `.mcp.json` declares the server under the key `atlassian`, so in Claude Code each tool surfaces as: + +``` +mcp__atlassian__<toolName> +``` + +e.g. `mcp__atlassian__createJiraIssue`, `mcp__atlassian__searchConfluenceUsingCql`. (When the server is loaded through a plugin rather than a project-level `.mcp.json`, Claude Code may use a plugin-scoped prefix like `mcp__plugin_<plugin>_atlassian__<toolName>` — the trailing `<toolName>` is identical either way.) Tool names are **camelCase**, not snake_case, not CLI flags, not JSON `"tool":` blocks. + +## The hard rule + +> **Never invent tool names.** If a capability is not in the list below (e.g. project creation, sprint management, filter creation, space creation, page deletion, label management, field configuration, workflow/permission scheme editing, user provisioning, automation rules), it is **NOT available via MCP** — tell the user to use the Atlassian web UI (admin.atlassian.com / Jira settings / Confluence space tools) or the Atlassian REST API instead. + +Parameters marked "discover via tool schema" were not verified — inspect the tool's input schema at call time rather than guessing. + +## Identity & site discovery + +| Tool | Purpose | Key parameters | +|---|---|---| +| `atlassianUserInfo` | Get the authenticated user's profile | none | +| `getAccessibleAtlassianResources` | List Cloud sites (and their `cloudId`s) the OAuth grant can access. **Call this first** — most other tools require `cloudId`. | none | + +## Jira — read + +| Tool | Purpose | Key parameters | +|---|---|---| +| `getJiraIssue` | Fetch a single issue | `cloudId`, `issueIdOrKey` | +| `searchJiraIssuesUsingJql` | Run a JQL search | `cloudId`, `jql`; pagination params — discover via tool schema | +| `getTransitionsForJiraIssue` | List transitions currently available on an issue | `cloudId`, `issueIdOrKey` | +| `getVisibleJiraProjects` | List projects the user can see | `cloudId` | +| `getJiraProjectIssueTypesMetadata` | Issue types available in a project | `cloudId`, `projectIdOrKey` | +| `getJiraIssueTypeMetaWithFields` | Field metadata for a project + issue type (use before create/edit to learn required fields) | `cloudId`, `projectIdOrKey`, issue type id — discover via tool schema | +| `getJiraIssueRemoteIssueLinks` | Remote links (e.g. Confluence pages) on an issue | `cloudId`, `issueIdOrKey` | +| `getIssueLinkTypes` | List available issue link types (Blocks, Relates, …) | `cloudId` | +| `lookupJiraAccountId` | Resolve a user (name/email) to an `accountId` | `cloudId`, search string — discover via tool schema | + +## Jira — write + +| Tool | Purpose | Key parameters | +|---|---|---| +| `createJiraIssue` | Create an issue | `cloudId`, `projectKey`, `issueTypeName`, `summary`; other fields — discover via tool schema | +| `editJiraIssue` | Update fields on an existing issue | `cloudId`, `issueIdOrKey`, fields payload — discover via tool schema | +| `transitionJiraIssue` | Move an issue through its workflow (get the transition id from `getTransitionsForJiraIssue` first) | `cloudId`, `issueIdOrKey`, transition id | +| `addCommentToJiraIssue` | Comment on an issue | `cloudId`, `issueIdOrKey`, comment body | +| `addWorklogToJiraIssue` | Log work on an issue | `cloudId`, `issueIdOrKey`, time spent — discover via tool schema | +| `createIssueLink` | Link two issues (type from `getIssueLinkTypes`) | `cloudId`, inward/outward issue + link type — discover via tool schema | + +## Confluence — read + +| Tool | Purpose | Key parameters | +|---|---|---| +| `getConfluenceSpaces` | List spaces | `cloudId` | +| `getConfluencePage` | Fetch a page (body + version) | `cloudId`, `pageId` | +| `getPagesInConfluenceSpace` | List pages in a space | `cloudId`, `spaceId` — discover via tool schema | +| `getConfluencePageDescendants` | Child/descendant pages (hierarchy inspection) | `cloudId`, `pageId` | +| `getConfluencePageFooterComments` | Footer comments on a page | `cloudId`, `pageId` | +| `getConfluencePageInlineComments` | Inline comments on a page | `cloudId`, `pageId` | +| `searchConfluenceUsingCql` | Run a CQL search | `cloudId`, `cql` | + +## Confluence — write + +| Tool | Purpose | Key parameters | +|---|---|---| +| `createConfluencePage` | Create a page. Body must be **Confluence storage format (XHTML) or ADF** — legacy wiki markup (`{info}`, `h2.`, `{panel}`) is rejected. | `cloudId`, space id/key, `title`, `body`; parent id optional — discover via tool schema | +| `updateConfluencePage` | Update a page (supply current version + 1) | `cloudId`, `pageId`, `version`, `body` | +| `createConfluenceFooterComment` | Add a footer comment | `cloudId`, `pageId`, body | +| `createConfluenceInlineComment` | Add an inline comment | `cloudId`, `pageId`, body + anchor — discover via tool schema | + +## Cross-product + +| Tool | Purpose | Key parameters | +|---|---|---| +| `search` | Rovo cross-product search across Jira + Confluence | query string | +| `fetch` | Fetch a Jira/Confluence entity by id/URL | id — discover via tool schema | + +## Explicitly NOT available via MCP (use web UI or REST API) + +| Capability | Where to do it instead | +|---|---| +| Create/archive Jira **projects** | Jira web UI (`Projects > Create project`) or REST `POST /rest/api/3/project` | +| Create/manage **sprints** or boards | Jira board UI or Jira Software REST (`/rest/agile/1.0/sprint`) | +| Create/share saved **filters** | Jira UI (`Filters > Save as`) or REST `POST /rest/api/3/filter` | +| **Field configuration**, custom fields, screens | Jira admin UI (`Settings > Issues`) | +| **Workflow** / permission / notification **schemes** | Jira admin UI | +| Create/delete Confluence **spaces** | Confluence UI (`Spaces > Create space`) or REST `POST /wiki/api/v2/spaces` | +| **Delete** Confluence pages | Confluence UI or REST `DELETE /wiki/api/v2/pages/{id}` | +| Page **labels** | Confluence UI or REST (`/wiki/rest/api/content/{id}/label`) | +| Confluence **page templates / blueprints** (as first-class template objects) | Confluence UI (`Space settings > Templates`); via MCP you can only create ordinary pages that serve as copy-from templates | +| **User/group provisioning**, SSO, org admin | admin.atlassian.com or the org admin REST API | +| **Automation rules** | Jira/Confluence Automation UI | + +If a workflow in any skill in this domain appears to need one of these, the skill must say so and route to the UI/REST path — not invent a tool. diff --git a/project-management/skills/atlassian-admin/SKILL.md b/project-management/skills/atlassian-admin/SKILL.md index 5f05f285..64afce8b 100644 --- a/project-management/skills/atlassian-admin/SKILL.md +++ b/project-management/skills/atlassian-admin/SKILL.md @@ -214,21 +214,17 @@ description: Atlassian Administrator for managing and organizing Atlassian produ **TO Scrum Master**: Team access provisioned, board configuration options, automation rules, integrations enabled **FROM All Roles**: User access requests, permission changes, app installation requests, configuration support, incident reports -## Atlassian MCP Integration +## Atlassian MCP Integration — scope limits -**Primary Tools**: Jira MCP, Confluence MCP +**Admin operations are NOT available via the Atlassian Remote MCP server** (bundled `.mcp.json`, server key `atlassian`). The canonical tool list (`project-management/references/atlassian-mcp-tools.md`) contains no tools for user/group management, permission schemes, field/workflow configuration, SSO, app management, or org settings. Never invent tool names — every admin workflow in this skill runs through `admin.atlassian.com` or the REST APIs cited inline above. -**Admin Operations**: -- User and group management via API -- Bulk permission updates -- Configuration audits -- Usage reporting -- System health monitoring -- Automated compliance checks +**What MCP CAN contribute to admin work** (read-mostly support): +- `mcp__atlassian__lookupJiraAccountId` — resolve users to `accountId` before deprovisioning audits +- `mcp__atlassian__searchJiraIssuesUsingJql` — find a leaver's open issues (`assignee = <accountId>`) for reassignment +- `mcp__atlassian__getVisibleJiraProjects` / `mcp__atlassian__getConfluenceSpaces` — inventory inputs for access reviews +- `mcp__atlassian__atlassianUserInfo` / `mcp__atlassian__getAccessibleAtlassianResources` — verify the acting identity and accessible sites **Integration Points**: -- Support all roles with admin capabilities -- Enable Jira Expert with global configurations -- Provide Confluence Expert with template management -- Ensure Senior PM has visibility into org health -- Enable Scrum Master with team provisioning +- Support Jira/Confluence Experts by performing UI/REST admin changes they cannot do via MCP +- Ensure Senior PM has visibility into org health (exports from admin.atlassian.com) +- Enable Scrum Master with team provisioning (admin console) diff --git a/project-management/skills/atlassian-templates/SKILL.md b/project-management/skills/atlassian-templates/SKILL.md index 7f8455b7..eabc0b9c 100644 --- a/project-management/skills/atlassian-templates/SKILL.md +++ b/project-management/skills/atlassian-templates/SKILL.md @@ -48,7 +48,7 @@ Specialist in creating, modifying, and managing reusable templates and files for ## Confluence Templates Library -See **TEMPLATES.md** for full reference tables and copy-paste-ready template structures. The following summarises the standard types this skill creates and maintains. +See `references/template-design-patterns.md` for template design patterns and `references/governance-framework.md` for the governance model. For deployment-ready storage-format markup, use the bundled scaffolder (see [Template scaffolder](#template-scaffolder-generate-storage-format-markup) below). The following summarises the standard types this skill creates and maintains. ### Confluence Template Types | Template | Purpose | Key Macros Used | @@ -67,7 +67,7 @@ See **TEMPLATES.md** for full reference tables and copy-paste-ready template str ### Complete Example: Meeting Notes Template -The following is a copy-paste-ready Meeting Notes template in Confluence storage format (wiki markup): +> **Format warning**: The example below is **legacy wiki markup** (`{panel}`, `h2.`, `{tasks}`), shown for human readability. Wiki markup is NOT Confluence storage format and **will be rejected** by `mcp__atlassian__createConfluencePage` / `updateConfluencePage`, which expect storage format (XHTML, `<ac:structured-macro>` elements) or ADF. To get the deployment-ready storage-format equivalent, run the scaffolder: `python3 scripts/template_scaffolder.py meeting-notes` (see [Template scaffolder](#template-scaffolder-generate-storage-format-markup)). ``` {panel:title=Meeting Metadata|borderColor=#0052CC|titleBGColor=#0052CC|titleColor=#FFFFFF} @@ -104,7 +104,7 @@ h2. Next Steps & Related Links * Related Jira issues: {jira:key=PROJ-123} ``` -> Full examples for all other template types (Project Charter, Sprint Retrospective, PRD, Decision Log) and all Jira templates can be generated on request or found in **TEMPLATES.md**. +> Storage-format examples for the other built-in types (decision-log, runbook, project-kickoff) come from `python3 scripts/template_scaffolder.py --list`; design patterns for the remaining types (Project Charter, Sprint Retrospective, PRD) are in `references/template-design-patterns.md`. --- @@ -134,82 +134,63 @@ h2. Next Steps & Related Links --- +## Template scaffolder — generate storage-format markup + +The bundled scaffolder emits **Confluence storage-format XHTML** — the exact body format `createConfluencePage`/`updateConfluencePage` accept. It is the canonical deployment path for this skill: + +```bash +# List available template types (meeting-notes, decision-log, runbook, project-kickoff, custom) +python3 scripts/template_scaffolder.py --list + +# Generate a template body (storage-format XHTML) +python3 scripts/template_scaffolder.py meeting-notes + +# Custom template with chosen sections and macros, JSON output for programmatic use +python3 scripts/template_scaffolder.py custom --sections "Overview,Goals,Action Items" --macros "toc,status,info" --format json +``` + +Consume the output: take the `CONFLUENCE STORAGE FORMAT MARKUP` block (text mode) or the markup field (JSON mode) and pass it verbatim as the `body` of `mcp__atlassian__createConfluencePage`. Apply the suggested labels via the Confluence UI afterwards (label tools are not on the MCP). + ## Atlassian MCP Integration -**Primary Tools**: Confluence MCP, Jira MCP +**Primary Tool**: Atlassian Remote MCP server (bundled `.mcp.json`, server key `atlassian`). Tools surface as `mcp__atlassian__<toolName>` (camelCase). **Canonical tool list**: `project-management/references/atlassian-mcp-tools.md`. Never invent tool names — if a capability isn't in that list, it is not available via MCP; route to the web UI or REST API. ### Template Operations via MCP -All MCP calls below use the exact parameter names expected by the Atlassian MCP server. Replace angle-bracket placeholders with real values before executing. +Obtain `cloudId` once via `mcp__atlassian__getAccessibleAtlassianResources`. Replace angle-bracket placeholders with real values; discover exact parameter names from each tool's schema at call time. -**Create a Confluence page template:** -```json -{ - "tool": "confluence_create_page", - "parameters": { - "space_key": "PROJ", - "title": "Template: Meeting Notes", - "body": "<storage-format template content>", - "labels": ["template", "meeting-notes"], - "parent_id": "<optional parent page id>" - } -} +**Create a Confluence template page** (body from the scaffolder above): +``` +mcp__atlassian__createConfluencePage (cloudId, space, title="Template: Meeting Notes", + body=<storage-format XHTML from template_scaffolder.py>, parent page id optional) +``` +Labels (`template`, `meeting-notes`) must be applied in the Confluence UI — there is no MCP label tool. + +**Update an existing template page** (read first to get the current version): +``` +mcp__atlassian__getConfluencePage (cloudId, pageId=<existing page id>) +mcp__atlassian__updateConfluencePage (cloudId, pageId=<id>, version=<current + 1>, + body=<updated storage-format content>) ``` -**Update an existing template:** -```json -{ - "tool": "confluence_update_page", - "parameters": { - "page_id": "<existing page id>", - "version": "<current_version + 1>", - "title": "Template: Meeting Notes", - "body": "<updated storage-format content>", - "version_comment": "v2 — added status macro to header" - } -} -``` +**Jira issue description templates**: there is **no MCP tool for field configuration** (`default_value` on the description field, screens, field contexts). Configure description defaults in the Jira admin UI (`Settings > Issues > Field configurations`) or via REST (`/rest/api/3/fieldconfiguration`). What MCP CAN do: create issues pre-filled with template text via `mcp__atlassian__createJiraIssue` (pass the template body as the description), and inspect required fields per issue type with `mcp__atlassian__getJiraIssueTypeMetaWithFields`. -**Create a Jira issue description template (via field configuration):** -```json -{ - "tool": "jira_update_field_configuration", - "parameters": { - "project_key": "PROJ", - "field_id": "description", - "default_value": "<template markdown or Atlassian Document Format JSON>" - } -} -``` +**First-class Confluence templates/blueprints** are also **not creatable via MCP** — `createConfluencePage` creates ordinary pages that serve as copy-from templates. To register a real space template, use `Space settings > Templates` in the UI. -**Deploy template to multiple spaces (batch):** -```json -// Repeat for each target space key -{ - "tool": "confluence_create_page", - "parameters": { - "space_key": "<SPACE_KEY>", - "title": "Template: Meeting Notes", - "body": "<storage-format template content>", - "labels": ["template"] - } -} -// After each create, verify: -{ - "tool": "confluence_get_page", - "parameters": { - "space_key": "<SPACE_KEY>", - "title": "Template: Meeting Notes" - } -} -// Assert response status == 200 and page body is non-empty before proceeding to next space +**Deploy a template page to multiple spaces (batch):** +``` +# Repeat per target space: +mcp__atlassian__createConfluencePage (cloudId, space=<target>, title="Template: Meeting Notes", body=<storage-format content>) +# Verify each create before proceeding: +mcp__atlassian__getConfluencePage (cloudId, pageId=<id returned by create>) +# Assert the returned body is non-empty and contains the expected <ac:structured-macro> elements ``` **Validation checkpoint after deployment:** -- Retrieve the created/updated page and assert it renders without macro errors -- Check that `{jira}` embeds resolve against the target Jira project -- Confirm `{tasks}` blocks are interactive in the published view -- If any check fails: revert using `confluence_update_page` with `version: <current + 1>` and the previous version body +- Retrieve the created/updated page via `mcp__atlassian__getConfluencePage` and assert it renders without macro errors +- Check that Jira-macro embeds resolve against the target Jira project +- Confirm task blocks are interactive in the published view +- If any check fails: revert using `mcp__atlassian__updateConfluencePage` with `version: <current + 1>` and the previous version body --- @@ -241,7 +222,7 @@ All MCP calls below use the exact parameter names expected by the Atlassian MCP ## Handoff Protocols -See **HANDOFFS.md** for the full handoff matrix. Summary: +Handoff summary (governance context in `references/governance-framework.md`): | Partner | Receives FROM | Sends TO | |---------|--------------|---------| diff --git a/project-management/skills/confluence-expert/SKILL.md b/project-management/skills/confluence-expert/SKILL.md index 006370ae..f8b258aa 100644 --- a/project-management/skills/confluence-expert/SKILL.md +++ b/project-management/skills/confluence-expert/SKILL.md @@ -9,46 +9,60 @@ Master-level expertise in Confluence space management, documentation architectur ## Atlassian MCP Integration -**Primary Tool**: Confluence MCP Server +**Primary Tool**: Atlassian Remote MCP server (bundled `.mcp.json`, server key `atlassian`). Tools are camelCase and surface as `mcp__atlassian__<toolName>`. **Canonical tool list**: `project-management/references/atlassian-mcp-tools.md`. Never invent tool names — if a capability isn't in that list, it is not available via MCP. -**Key Operations**: +**Key Operations** (obtain `cloudId` once via `mcp__atlassian__getAccessibleAtlassianResources`): ``` -// Create a new space -create_space({ key: "TEAM", name: "Engineering Team", description: "Engineering team knowledge base" }) +// List spaces (space CREATION is not available via MCP — see below) +mcp__atlassian__getConfluenceSpaces (cloudId) -// Create a page under a parent -create_page({ spaceKey: "TEAM", title: "Sprint 42 Notes", parentId: "123456", body: "<p>Meeting notes in storage-format HTML</p>" }) +// Create a page under a parent — body must be storage-format XHTML or ADF, never wiki markup +mcp__atlassian__createConfluencePage (cloudId, space, title="Sprint 42 Notes", parent page id, body="<p>Meeting notes in storage-format XHTML</p>") -// Update an existing page (version must be incremented) -update_page({ pageId: "789012", version: 4, body: "<p>Updated content</p>" }) +// Update an existing page (fetch current version with getConfluencePage, then supply version + 1) +mcp__atlassian__updateConfluencePage (cloudId, pageId="789012", version=5, body="<p>Updated content</p>") -// Delete a page -delete_page({ pageId: "789012" }) +// Read a page (body + current version) +mcp__atlassian__getConfluencePage (cloudId, pageId="789012") // Search with CQL -search({ cql: 'space = "TEAM" AND label = "meeting-notes" ORDER BY lastModified DESC' }) +mcp__atlassian__searchConfluenceUsingCql (cloudId, cql='space = "TEAM" AND label = "meeting-notes" ORDER BY lastModified DESC') // Retrieve child pages for hierarchy inspection -get_children({ pageId: "123456" }) +mcp__atlassian__getConfluencePageDescendants (cloudId, pageId="123456") -// Apply a label to a page -add_label({ pageId: "789012", label: "archived" }) +// Comments +mcp__atlassian__getConfluencePageFooterComments / mcp__atlassian__createConfluenceFooterComment (cloudId, pageId) ``` +**Not available via MCP — use the web UI or REST API instead:** +- Create/delete a **space** → Confluence UI `Spaces > Create space` or `POST /wiki/api/v2/spaces` +- **Delete** a page → Confluence UI or `DELETE /wiki/api/v2/pages/{id}` +- Apply **labels** → Confluence UI or `/wiki/rest/api/content/{id}/label` +- Space **permissions**, templates/blueprints as first-class objects → Confluence space settings UI + **Integration Points**: - Create documentation for Senior PM projects - Support Scrum Master with ceremony templates - Link to Jira issues for Jira Expert - Provide templates for Template Creator -> **See also**: `MACROS.md` for macro syntax reference, `TEMPLATES.md` for full template library, `PERMISSIONS.md` for permission scheme details. +> **See also**: `references/macro-cheat-sheet.md` for storage-format macro syntax, `references/templates.md` for the template library, `references/space-architecture-patterns.md` for space structure and permission patterns. ## Workflows ### Space Creation + +> Space creation is **not available via MCP** — create the space in the Confluence UI (`Spaces > Create space`) or via REST (`POST /wiki/api/v2/spaces`). The page tree inside it CAN be built via MCP (`mcp__atlassian__createConfluencePage`). + +0. Generate the recommended hierarchy from a team description: + ```bash + python3 scripts/space_structure_generator.py team_info.json --format json + ``` + Input: JSON with team `name`, `size`, `type`, `projects`. Consume the output: use the emitted page tree as the creation plan for step 5 — one `mcp__atlassian__createConfluencePage` call per node, passing the parent page id to nest children. 1. Determine space type (Team, Project, Knowledge Base, Personal) -2. Create space with clear name and description +2. Create space with clear name and description (web UI / REST) 3. Set space homepage with overview 4. Configure space permissions: - View, Edit, Create, Delete @@ -105,6 +119,13 @@ Space Home 8. **REPORT TO**: Senior PM on documentation health ### Knowledge Base Management + +**Run a content health audit** before any restructure or governance review: +```bash +python3 scripts/content_audit_analyzer.py pages.json --format json +``` +Input: a JSON page inventory (`title`, `last_modified`, `view_count`, `author`, `labels`, `word_count`) — build it by exporting page metadata via `mcp__atlassian__getPagesInConfluenceSpace` / `mcp__atlassian__searchConfluenceUsingCql`. Consume the output: the stale/orphaned/low-engagement findings become the archive list (label + move via UI, since label tools aren't on the MCP) and the update backlog for the quality standards below. + **Article Types**: - How-to guides - Troubleshooting docs @@ -121,7 +142,7 @@ Space Home ## Essential Macros -> Full macro reference with all parameters: see `MACROS.md`. +> **Syntax note**: The `{macro}` shorthand below is **legacy wiki-markup notation**, shown for readability only. Confluence Cloud pages created via MCP (`createConfluencePage` / `updateConfluencePage`) require **storage format (XHTML)** — e.g. `{info}` is really `<ac:structured-macro ac:name="info"><ac:rich-text-body>...</ac:rich-text-body></ac:structured-macro>`. For the storage-format syntax of every macro listed here, see `references/macro-cheat-sheet.md`; for ready-made storage-format page bodies, run the atlassian-templates scaffolder (`python3 ../atlassian-templates/scripts/template_scaffolder.py meeting-notes`). ### Content Macros **Info, Note, Warning, Tip**: @@ -227,7 +248,7 @@ const example = "code here"; ## Templates Library -> Full template library with complete markup: see `TEMPLATES.md`. Key templates summarised below. +> Full template library with complete markup: see `references/templates.md`. Key templates summarised below. | Template | Purpose | Key Sections | |----------|---------|--------------| @@ -238,7 +259,7 @@ const example = "code here"; ## Space Permissions -> Full permission scheme details: see `PERMISSIONS.md`. +> Permission patterns by space type: see `references/space-architecture-patterns.md`. Note: space permissions are configured in the Confluence UI (`Space settings > Permissions`) — not via MCP. ### Permission Schemes **Public Space**: diff --git a/project-management/skills/jira-expert/SKILL.md b/project-management/skills/jira-expert/SKILL.md index f5d63359..be10c8c8 100644 --- a/project-management/skills/jira-expert/SKILL.md +++ b/project-management/skills/jira-expert/SKILL.md @@ -1,6 +1,6 @@ --- name: "jira-expert" -description: Atlassian Jira expert for creating and managing projects, planning, product discovery, JQL queries, workflows, custom fields, automation, reporting, and all Jira features. Use for Jira project setup, configuration, advanced search, dashboard creation, workflow design, and technical Jira operations. +description: Atlassian Jira expert for creating and managing projects, planning, product discovery, JQL queries, workflows, custom fields, automation, reporting, and all Jira features. Use when setting up or configuring Jira projects, writing JQL and advanced searches, creating dashboards, designing workflows, or performing technical Jira operations. --- # Atlassian Jira Expert @@ -9,25 +9,36 @@ Master-level expertise in Jira configuration, project management, JQL, workflows ## Quick Start — Most Common Operations -**Create a project**: +All MCP examples in this skill use the real Atlassian Remote MCP tools (camelCase, surfaced as `mcp__atlassian__<toolName>`). The canonical tool list is `project-management/references/atlassian-mcp-tools.md` — never invent tool names; if a capability isn't listed there, it is not available via MCP. + +**Create an issue** (call `getAccessibleAtlassianResources` once first to obtain `cloudId`): ``` -mcp jira create_project --name "My Project" --key "MYPROJ" --type scrum --lead "user@example.com" +mcp__atlassian__createJiraIssue (cloudId, projectKey="MYPROJ", issueTypeName="Story", summary="My new story") ``` -**Run a JQL query**: +**Run a JQL query** (build the JQL from natural language with the bundled script, then execute): +```bash +python3 scripts/jql_query_builder.py "high priority bugs assigned to me" +# → emits validated JQL, e.g.: assignee = currentUser() AND type = Bug AND status != Done ``` -mcp jira search_issues --jql "project = MYPROJ AND status != Done AND dueDate < now()" --maxResults 50 +``` +mcp__atlassian__searchJiraIssuesUsingJql (cloudId, jql="project = MYPROJ AND status != Done AND dueDate < now()") ``` -For full command reference, see [Atlassian MCP Integration](#atlassian-mcp-integration). For JQL functions, see [JQL Functions Reference](#jql-functions-reference). For report templates, see [Reporting Templates](#reporting-templates). +**Create a project**: NOT available via MCP. Use the Jira web UI (`Projects > Create project`) or REST API (`POST /rest/api/3/project`). + +For the full tool reference, see [Atlassian MCP Integration](#atlassian-mcp-integration). For JQL functions, see [JQL Functions Reference](#jql-functions-reference). For report templates, see [Reporting Templates](#reporting-templates). --- ## Workflows ### Project Creation + +> Project creation is **not available via MCP** — perform steps 2-6 in the Jira web UI (`Projects > Create project`) or via REST API (`POST /rest/api/3/project`). After creation, verify visibility with `mcp__atlassian__getVisibleJiraProjects` and inspect issue types with `mcp__atlassian__getJiraProjectIssueTypesMetadata`. + 1. Determine project type (Scrum, Kanban, Bug Tracking, etc.) -2. Create project with appropriate template +2. Create project with appropriate template (web UI / REST) 3. Configure project settings: - Name, key, description - Project lead and default assignee @@ -39,15 +50,30 @@ For full command reference, see [Atlassian MCP Integration](#atlassian-mcp-integ 7. **HANDOFF TO**: Scrum Master for team onboarding ### Workflow Design + +> Workflow/scheme editing is **not available via MCP** — configure in `Jira Settings > Issues > Workflows`. Use the bundled validator to catch anti-patterns before deploying. + 1. Map out process states (To Do → In Progress → Done) 2. Define transitions and conditions -3. Add validators, post-functions, and conditions -4. Configure workflow scheme +3. Lint the design before building it in Jira: + ```bash + python3 scripts/workflow_validator.py workflow.json --format json + ``` + Input: a JSON file with the workflow's `states` and `transitions`. Consume the output: fix every reported anti-pattern (dead-end states, unreachable states, missing transitions) in the design before touching Jira. +4. Add validators, post-functions, and conditions; configure the workflow scheme (web UI) 5. **Validate**: Deploy to a test project first; verify all transitions, conditions, and post-functions behave as expected before associating with production projects 6. Associate workflow with project -7. Test workflow with sample issues +7. Test workflow with sample issues — via MCP: `mcp__atlassian__getTransitionsForJiraIssue` on a sample issue to confirm expected transitions surface, then `mcp__atlassian__transitionJiraIssue` to walk it through the flow ### JQL Query Building + +**Start with the bundled builder** — it pattern-matches natural language to validated JQL: +```bash +python3 scripts/jql_query_builder.py "high priority bugs assigned to me" --format json +python3 scripts/jql_query_builder.py --patterns # list all supported query patterns +``` +Consume the output: take the `jql` field from the JSON result (or the GENERATED JQL block in text mode) and execute it with `mcp__atlassian__searchJiraIssuesUsingJql (cloudId, jql=<generated>)`. If the builder reports no pattern match, compose JQL manually using the reference below. + **Basic Structure**: `field operator value` **Common Operators**: @@ -264,35 +290,44 @@ assignee in (user1, user2) AND sprint in openSprints() ## Atlassian MCP Integration -**Primary Tool**: Jira MCP Server +**Primary Tool**: Atlassian Remote MCP server (bundled `.mcp.json`, server key `atlassian`). Tools surface as `mcp__atlassian__<toolName>`. **Canonical tool list**: `project-management/references/atlassian-mcp-tools.md`. Never invent tool names — if a capability isn't in that list, route to the web UI/REST API. -**Key Operations with Example Commands**: +**Key Operations with Example Calls** (obtain `cloudId` once via `mcp__atlassian__getAccessibleAtlassianResources`): -Create a project: +Create an issue (check required fields first with `getJiraIssueTypeMetaWithFields`): ``` -mcp jira create_project --name "My Project" --key "MYPROJ" --type scrum --lead "user@example.com" +mcp__atlassian__createJiraIssue (cloudId, projectKey="MYPROJ", issueTypeName="Story", summary="My new story") ``` Execute a JQL query: ``` -mcp jira search_issues --jql "project = MYPROJ AND status != Done AND dueDate < now()" --maxResults 50 +mcp__atlassian__searchJiraIssuesUsingJql (cloudId, jql="project = MYPROJ AND status != Done AND dueDate < now()") ``` Update an issue field: ``` -mcp jira update_issue --issue "MYPROJ-42" --field "status" --value "In Progress" +mcp__atlassian__editJiraIssue (cloudId, issueIdOrKey="MYPROJ-42", fields=<payload — discover via tool schema>) ``` -Create a sprint: +Transition an issue (status changes go through transitions, not field edits): ``` -mcp jira create_sprint --board 10 --name "Sprint 5" --startDate "2024-06-01" --endDate "2024-06-14" +mcp__atlassian__getTransitionsForJiraIssue (cloudId, issueIdOrKey="MYPROJ-42") +mcp__atlassian__transitionJiraIssue (cloudId, issueIdOrKey="MYPROJ-42", transition=<id from previous call>) ``` -Create a board filter: +Comment / log work / link issues: ``` -mcp jira create_filter --name "Open Blockers" --jql "priority = Blocker AND status != Done" --shareWith "project-team" +mcp__atlassian__addCommentToJiraIssue (cloudId, issueIdOrKey="MYPROJ-42", body="...") +mcp__atlassian__addWorklogToJiraIssue (cloudId, issueIdOrKey="MYPROJ-42", timeSpent=<discover via tool schema>) +mcp__atlassian__createIssueLink (cloudId, link type from mcp__atlassian__getIssueLinkTypes) ``` +**Not available via MCP — use the web UI or REST API instead:** +- Create a **project** → Jira UI `Projects > Create project` or `POST /rest/api/3/project` +- Create a **sprint** or configure boards → Jira Software UI or `POST /rest/agile/1.0/sprint` +- Create/share a **filter** → Jira UI `Filters > Save as` or `POST /rest/api/3/filter` +- Custom fields, screens, workflow/permission schemes → Jira admin UI + **Integration Points**: - Pull metrics for Senior PM reporting - Configure sprint boards for Scrum Master diff --git a/project-management/skills/jira-expert/references/jql-examples.md b/project-management/skills/jira-expert/references/jql-examples.md index 7391bd22..2be5ab29 100644 --- a/project-management/skills/jira-expert/references/jql-examples.md +++ b/project-management/skills/jira-expert/references/jql-examples.md @@ -295,7 +295,7 @@ sprint = "Sprint 23" AND status != Done **Good - Specific date:** ```jql -created >= 2024-01-01 AND created <= 2024-01-31 +created >= 2026-01-01 AND created <= 2026-01-31 ``` **Bad - Relative with high cost:** diff --git a/project-management/skills/pm-skills/SKILL.md b/project-management/skills/pm-skills/SKILL.md index fd701da8..2aa4c2a1 100644 --- a/project-management/skills/pm-skills/SKILL.md +++ b/project-management/skills/pm-skills/SKILL.md @@ -1,6 +1,6 @@ --- name: "pm-skills" -description: "6 project management agent skills and plugins for Claude Code, Codex, Gemini CLI, Cursor, OpenClaw. Senior PM, scrum master, Jira expert (JQL), Confluence expert, Atlassian admin, template creator. MCP integration for live Jira/Confluence automation." +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 author: Alireza Rezvani license: MIT @@ -17,43 +17,34 @@ agents: - openclaw --- -# Project Management Skills +# Project Management Skills — Router -6 production-ready project management skills with Atlassian MCP integration. +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). -## Quick Start +## Routing table -### Claude Code -``` -/read project-management/jira-expert/SKILL.md -``` +Match the request, then load `project-management/skills/<skill>/SKILL.md`. If multiple rows match, ask one clarifying question first. -### Codex CLI -```bash -npx agent-skills-cli add alirezarezvani/claude-skills/project-management -``` +| 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/` | -## Skills Overview - -| Skill | Folder | Focus | -|-------|--------|-------| -| Senior PM | `senior-pm/` | Portfolio management, risk analysis, resource planning | -| Scrum Master | `scrum-master/` | Velocity forecasting, sprint health, retrospectives | -| Jira Expert | `jira-expert/` | JQL queries, workflows, automation, dashboards | -| Confluence Expert | `confluence-expert/` | Knowledge bases, page layouts, macros | -| Atlassian Admin | `atlassian-admin/` | User management, permissions, integrations | -| Atlassian Templates | `atlassian-templates/` | Blueprints, custom layouts, reusable content | - -## Python Tools - -6 scripts, all stdlib-only: +## Quick start ```bash -python3 senior-pm/scripts/project_health_dashboard.py --help -python3 scrum-master/scripts/velocity_analyzer.py --help +# Example: route a sprint-health request +cat project-management/skills/scrum-master/SKILL.md +ls project-management/skills/scrum-master/scripts/ ``` ## Rules -- Load only the specific skill SKILL.md you need -- Use MCP tools for live Jira/Confluence operations when available +- 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. diff --git a/ra-qm-team/README.md b/ra-qm-team/README.md index d47a2488..f33456b3 100644 --- a/ra-qm-team/README.md +++ b/ra-qm-team/README.md @@ -40,26 +40,26 @@ npx ai-agent-skills install alirezarezvani/claude-skills/ra-qm-team --agent curs ```bash # Strategic Leadership -npx ai-agent-skills install alirezarezvani/claude-skills/ra-qm-team/regulatory-affairs-head -npx ai-agent-skills install alirezarezvani/claude-skills/ra-qm-team/quality-manager-qmr +npx ai-agent-skills install alirezarezvani/claude-skills/ra-qm-team/skills/regulatory-affairs-head +npx ai-agent-skills install alirezarezvani/claude-skills/ra-qm-team/skills/quality-manager-qmr # Quality Systems -npx ai-agent-skills install alirezarezvani/claude-skills/ra-qm-team/quality-manager-qms-iso13485 -npx ai-agent-skills install alirezarezvani/claude-skills/ra-qm-team/capa-officer -npx ai-agent-skills install alirezarezvani/claude-skills/ra-qm-team/quality-documentation-manager +npx ai-agent-skills install alirezarezvani/claude-skills/ra-qm-team/skills/quality-manager-qms-iso13485 +npx ai-agent-skills install alirezarezvani/claude-skills/ra-qm-team/skills/capa-officer +npx ai-agent-skills install alirezarezvani/claude-skills/ra-qm-team/skills/quality-documentation-manager # Risk & Security -npx ai-agent-skills install alirezarezvani/claude-skills/ra-qm-team/risk-management-specialist -npx ai-agent-skills install alirezarezvani/claude-skills/ra-qm-team/information-security-manager-iso27001 +npx ai-agent-skills install alirezarezvani/claude-skills/ra-qm-team/skills/risk-management-specialist +npx ai-agent-skills install alirezarezvani/claude-skills/ra-qm-team/skills/information-security-manager-iso27001 # Regulatory Specialists -npx ai-agent-skills install alirezarezvani/claude-skills/ra-qm-team/mdr-745-specialist -npx ai-agent-skills install alirezarezvani/claude-skills/ra-qm-team/fda-consultant-specialist +npx ai-agent-skills install alirezarezvani/claude-skills/ra-qm-team/skills/mdr-745-specialist +npx ai-agent-skills install alirezarezvani/claude-skills/ra-qm-team/skills/fda-consultant-specialist # Audit & Compliance -npx ai-agent-skills install alirezarezvani/claude-skills/ra-qm-team/qms-audit-expert -npx ai-agent-skills install alirezarezvani/claude-skills/ra-qm-team/isms-audit-expert -npx ai-agent-skills install alirezarezvani/claude-skills/ra-qm-team/gdpr-dsgvo-expert +npx ai-agent-skills install alirezarezvani/claude-skills/ra-qm-team/skills/qms-audit-expert +npx ai-agent-skills install alirezarezvani/claude-skills/ra-qm-team/skills/isms-audit-expert +npx ai-agent-skills install alirezarezvani/claude-skills/ra-qm-team/skills/gdpr-dsgvo-expert ``` **Supported Agents:** Claude Code, Cursor, VS Code, Copilot, Goose, Amp, Codex @@ -117,7 +117,6 @@ The 12 skills are organized across 5 strategic layers: ## 📦 Complete Skills Catalog ### 1. Senior Regulatory Affairs Manager (Head of Regulatory Affairs) -**Package:** `regulatory-affairs-head.zip` **Purpose:** Strategic regulatory leadership and cross-functional coordination for market access. @@ -147,7 +146,6 @@ The 12 skills are organized across 5 strategic layers: --- ### 2. Senior Quality Manager Responsible Person (QMR) -**Package:** `quality-manager-qmr.zip` **Purpose:** Overall quality system responsibility and regulatory compliance oversight. @@ -177,7 +175,6 @@ The 12 skills are organized across 5 strategic layers: --- ### 3. Senior Quality Manager - QMS ISO 13485 Specialist -**Package:** `quality-manager-qms-iso13485.zip` **Purpose:** ISO 13485 QMS implementation, maintenance, and optimization. @@ -207,7 +204,6 @@ The 12 skills are organized across 5 strategic layers: --- ### 4. Senior CAPA Officer -**Package:** `capa-officer.zip` **Purpose:** Corrective and preventive action management within QMS. @@ -237,7 +233,6 @@ The 12 skills are organized across 5 strategic layers: --- ### 5. Senior Quality Documentation Manager -**Package:** `quality-documentation-manager.zip` **Purpose:** Documentation control and review of all norms and appendices. @@ -267,7 +262,6 @@ The 12 skills are organized across 5 strategic layers: --- ### 6. Senior Risk Management Specialist -**Package:** `risk-management-specialist.zip` **Purpose:** ISO 14971 risk management throughout product lifecycle. @@ -297,7 +291,6 @@ The 12 skills are organized across 5 strategic layers: --- ### 7. Senior Information Security Manager (ISO 27001/27002) -**Package:** `information-security-manager-iso27001.zip` **Purpose:** ISMS implementation and cybersecurity compliance for medical devices. @@ -327,7 +320,6 @@ The 12 skills are organized across 5 strategic layers: --- ### 8. Senior MDR 2017/745 Specialist -**Package:** `mdr-745-specialist.zip` **Purpose:** EU MDR compliance expertise and consulting. @@ -357,7 +349,6 @@ The 12 skills are organized across 5 strategic layers: --- ### 9. Senior FDA Consultant and Specialist -**Package:** `fda-consultant-specialist.zip` **Purpose:** FDA submission pathways and QSR compliance. @@ -387,7 +378,6 @@ The 12 skills are organized across 5 strategic layers: --- ### 10. Senior QMS Audit Expert -**Package:** `qms-audit-expert.zip` **Purpose:** Internal and external QMS auditing expertise. @@ -417,7 +407,6 @@ The 12 skills are organized across 5 strategic layers: --- ### 11. Senior ISMS Audit Expert -**Package:** `isms-audit-expert.zip` **Purpose:** Information security management system auditing. @@ -447,7 +436,6 @@ The 12 skills are organized across 5 strategic layers: --- ### 12. Senior GDPR/DSGVO Expert -**Package:** `gdpr-dsgvo-expert.zip` **Purpose:** EU GDPR and German DSGVO compliance and auditing. @@ -495,14 +483,12 @@ The 12 skills are organized across 5 strategic layers: **Security & Privacy Focus?** → Focus on: Information Security Manager + GDPR Expert + ISMS Audit Expert -### Step 2: Download Skills +### Step 2: Get the Skills -Each skill is packaged as a .zip file for easy distribution: +Each skill is a self-contained folder under `ra-qm-team/skills/` (install via the `ra-qm-skills` marketplace plugin, or copy the folder directly): ```bash -# Extract a skill package -unzip regulatory-affairs-head.zip -cd regulatory-affairs-head +cd ra-qm-team/skills/regulatory-affairs-head # Explore the structure ls -la diff --git a/ra-qm-team/capa-officer.zip b/ra-qm-team/capa-officer.zip deleted file mode 100644 index c49397ae..00000000 Binary files a/ra-qm-team/capa-officer.zip and /dev/null differ diff --git a/ra-qm-team/compliance-team-eu-ai-act/skills/eu-ai-act-specialist/SKILL.md b/ra-qm-team/compliance-team-eu-ai-act/skills/eu-ai-act-specialist/SKILL.md index 1a8d967b..360085bd 100644 --- a/ra-qm-team/compliance-team-eu-ai-act/skills/eu-ai-act-specialist/SKILL.md +++ b/ra-qm-team/compliance-team-eu-ai-act/skills/eu-ai-act-specialist/SKILL.md @@ -183,13 +183,13 @@ python scripts/conformity_assessment_planner.py system.json ## Adjacent Skills -- `../../skills/gdpr-dsgvo-expert/` — GDPR DPIA + lawful basis (most AI systems also trigger GDPR) -- `../../../compliance-team-iso42001/` — ISO 42001 AIMS (voluntary management system that satisfies parts of Article 17 QMS for providers) -- `../../skills/information-security-manager-iso27001/` — ISO 27001 for cybersecurity requirements (Article 15) -- `../../skills/risk-management-specialist/` — ISO 14971 risk management (referenced for safety-component AI under Article 6(1)) -- `../../skills/mdr-745-specialist/` — MDR 2017/745 (medical-device AI overlap) -- `../../../../compliance-os/` — Meta-orchestrator for multi-framework programs -- `../../../../c-level-advisor/chief-ai-officer-advisor/` — Executive AI strategy +- `ra-qm-team/skills/gdpr-dsgvo-expert/` — GDPR DPIA + lawful basis (most AI systems also trigger GDPR) +- `ra-qm-team/compliance-team-iso42001/` — ISO 42001 AIMS (voluntary management system that satisfies parts of Article 17 QMS for providers) +- `ra-qm-team/skills/information-security-manager-iso27001/` — ISO 27001 for cybersecurity requirements (Article 15) +- `ra-qm-team/skills/risk-management-specialist/` — ISO 14971 risk management (referenced for safety-component AI under Article 6(1)) +- `ra-qm-team/skills/mdr-745-specialist/` — MDR 2017/745 (medical-device AI overlap) +- `compliance-os/` — Meta-orchestrator for multi-framework programs +- `c-level-advisor/chief-ai-officer-advisor/` — Executive AI strategy ## References diff --git a/ra-qm-team/compliance-team-eu-ai-act/skills/eu-ai-act-specialist/scripts/ai_system_risk_classifier.py b/ra-qm-team/compliance-team-eu-ai-act/skills/eu-ai-act-specialist/scripts/ai_system_risk_classifier.py index d5de086b..98759404 100644 --- a/ra-qm-team/compliance-team-eu-ai-act/skills/eu-ai-act-specialist/scripts/ai_system_risk_classifier.py +++ b/ra-qm-team/compliance-team-eu-ai-act/skills/eu-ai-act-specialist/scripts/ai_system_risk_classifier.py @@ -30,6 +30,14 @@ Input schema (JSON): ] } +Note on `article_5_practice`: this flag is the caller's legal pre-determination +that a listed Article 5 practice applies IN ITS PROHIBITED CONTEXT — the +classifier trusts it and does not re-derive it from the other fields. Context +matters: emotion recognition is prohibited under Article 5(1)(f) ONLY in +workplace and education settings (narrow safety/medical exceptions aside); +the same system in e.g. a retail setting is NOT prohibited — it is subject to +Article 50(3) transparency and possibly Annex III §1 (biometrics) high-risk rules. + Usage: python ai_system_risk_classifier.py # uses embedded 5-system sample python ai_system_risk_classifier.py path/to/systems.json @@ -45,9 +53,15 @@ from typing import Any, Dict, List, Optional SAMPLE: Dict[str, Any] = { "systems": [ { - "name": "Emotion recognition in retail store CCTV", - "intended_purpose": "Detect emotions of shoppers to optimize layout", - "users": "store_managers", + # Article 5(1)(f) prohibits emotion recognition ONLY in WORKPLACE and + # EDUCATION settings (with narrow safety/medical exceptions). The same + # system aimed at RETAIL shoppers is NOT prohibited — it falls under + # Article 50(3) transparency (limited-risk) and may be high-risk under + # Annex III §1 (biometrics). This sample uses a genuine workplace + # context so the prohibited tag is correct. + "name": "Emotion recognition of employees in workplace CCTV", + "intended_purpose": "Monitor employees' emotional state to score engagement", + "users": "hr_managers", "data_processes_natural_persons": True, "annex_iii_category": None, "performs_profiling": False, diff --git a/ra-qm-team/compliance-team-iso42001/skills/iso42001-specialist/SKILL.md b/ra-qm-team/compliance-team-iso42001/skills/iso42001-specialist/SKILL.md index 9b9534e1..fcea193d 100644 --- a/ra-qm-team/compliance-team-iso42001/skills/iso42001-specialist/SKILL.md +++ b/ra-qm-team/compliance-team-iso42001/skills/iso42001-specialist/SKILL.md @@ -173,14 +173,14 @@ python scripts/aims_audit_scheduler.py audit_scope.json ## Adjacent Skills -- `../../skills/information-security-manager-iso27001/` — ISO 27001 ISMS implementation (many controls reusable for AIMS A.7 data controls) -- `../../skills/quality-manager-qms-iso13485/` — ISO 13485 QMS (provides CAPA + management-review machinery the AIMS reuses) -- `../../skills/gdpr-dsgvo-expert/` — GDPR DPIA process (input to AIMS A.5 impact assessment for personal-data systems) -- `../../skills/isms-audit-expert/` — ISO 27001 internal audit pattern (the audit scheduler mirrors this for AIMS) -- `../../skills/soc2-compliance/` — SOC 2 trust services (reusable controls for AIMS A.10 third-party relationships) -- `../../../compliance-team-eu-ai-act/` — EU AI Act Article-level compliance (binding regulation companion to voluntary 42001) -- `../../../../compliance-os/` — Meta-orchestrator for multi-framework programs (run AIMS as one framework among 9) -- `../../../../c-level-advisor/chief-ai-officer-advisor/` — Executive AI strategy (build-vs-buy, cost economics — different audience) +- `ra-qm-team/skills/information-security-manager-iso27001/` — ISO 27001 ISMS implementation (many controls reusable for AIMS A.7 data controls) +- `ra-qm-team/skills/quality-manager-qms-iso13485/` — ISO 13485 QMS (provides CAPA + management-review machinery the AIMS reuses) +- `ra-qm-team/skills/gdpr-dsgvo-expert/` — GDPR DPIA process (input to AIMS A.5 impact assessment for personal-data systems) +- `ra-qm-team/skills/isms-audit-expert/` — ISO 27001 internal audit pattern (the audit scheduler mirrors this for AIMS) +- `ra-qm-team/skills/soc2-compliance/` — SOC 2 trust services (reusable controls for AIMS A.10 third-party relationships) +- `ra-qm-team/compliance-team-eu-ai-act/` — EU AI Act Article-level compliance (binding regulation companion to voluntary 42001) +- `compliance-os/` — Meta-orchestrator for multi-framework programs (run AIMS as one framework among 9) +- `c-level-advisor/chief-ai-officer-advisor/` — Executive AI strategy (build-vs-buy, cost economics — different audience) ## References diff --git a/ra-qm-team/fda-consultant-specialist.zip b/ra-qm-team/fda-consultant-specialist.zip deleted file mode 100644 index cd01e419..00000000 Binary files a/ra-qm-team/fda-consultant-specialist.zip and /dev/null differ diff --git a/ra-qm-team/gdpr-dsgvo-expert.zip b/ra-qm-team/gdpr-dsgvo-expert.zip deleted file mode 100644 index 502dfe7d..00000000 Binary files a/ra-qm-team/gdpr-dsgvo-expert.zip and /dev/null differ diff --git a/ra-qm-team/information-security-manager-iso27001.zip b/ra-qm-team/information-security-manager-iso27001.zip deleted file mode 100644 index 67ac1469..00000000 Binary files a/ra-qm-team/information-security-manager-iso27001.zip and /dev/null differ diff --git a/ra-qm-team/isms-audit-expert.zip b/ra-qm-team/isms-audit-expert.zip deleted file mode 100644 index 3a2c6976..00000000 Binary files a/ra-qm-team/isms-audit-expert.zip and /dev/null differ diff --git a/ra-qm-team/mdr-745-specialist.zip b/ra-qm-team/mdr-745-specialist.zip deleted file mode 100644 index f70440e9..00000000 Binary files a/ra-qm-team/mdr-745-specialist.zip and /dev/null differ diff --git a/ra-qm-team/qms-audit-expert.zip b/ra-qm-team/qms-audit-expert.zip deleted file mode 100644 index 14dc861c..00000000 Binary files a/ra-qm-team/qms-audit-expert.zip and /dev/null differ diff --git a/ra-qm-team/quality-documentation-manager.zip b/ra-qm-team/quality-documentation-manager.zip deleted file mode 100644 index cffd09af..00000000 Binary files a/ra-qm-team/quality-documentation-manager.zip and /dev/null differ diff --git a/ra-qm-team/quality-manager-qmr.zip b/ra-qm-team/quality-manager-qmr.zip deleted file mode 100644 index c4292685..00000000 Binary files a/ra-qm-team/quality-manager-qmr.zip and /dev/null differ diff --git a/ra-qm-team/quality-manager-qms-iso13485.zip b/ra-qm-team/quality-manager-qms-iso13485.zip deleted file mode 100644 index 508b7129..00000000 Binary files a/ra-qm-team/quality-manager-qms-iso13485.zip and /dev/null differ diff --git a/ra-qm-team/regulatory-affairs-head.zip b/ra-qm-team/regulatory-affairs-head.zip deleted file mode 100644 index 56c08de6..00000000 Binary files a/ra-qm-team/regulatory-affairs-head.zip and /dev/null differ diff --git a/ra-qm-team/risk-management-specialist.zip b/ra-qm-team/risk-management-specialist.zip deleted file mode 100644 index 303bb668..00000000 Binary files a/ra-qm-team/risk-management-specialist.zip and /dev/null differ diff --git a/ra-qm-team/skills/capa-officer/SKILL.md b/ra-qm-team/skills/capa-officer/SKILL.md index be868100..16c77f01 100644 --- a/ra-qm-team/skills/capa-officer/SKILL.md +++ b/ra-qm-team/skills/capa-officer/SKILL.md @@ -1,6 +1,6 @@ --- name: "capa-officer" -description: CAPA system management for medical device QMS. Covers root cause analysis, corrective action planning, effectiveness verification, and CAPA metrics. Use for CAPA investigations, 5-Why analysis, fishbone diagrams, root cause determination, corrective action tracking, effectiveness verification, or CAPA program optimization. +description: CAPA system management for medical device QMS. Covers root cause analysis, corrective action planning, effectiveness verification, and CAPA metrics. Use when running CAPA investigations, 5-Why analysis, fishbone diagrams, root cause determination, corrective action tracking, effectiveness verification, or CAPA program optimization. triggers: - CAPA investigation - root cause analysis diff --git a/ra-qm-team/skills/eu-ai-act-specialist/SKILL.md b/ra-qm-team/skills/eu-ai-act-specialist/SKILL.md index 1a8d967b..360085bd 100644 --- a/ra-qm-team/skills/eu-ai-act-specialist/SKILL.md +++ b/ra-qm-team/skills/eu-ai-act-specialist/SKILL.md @@ -183,13 +183,13 @@ python scripts/conformity_assessment_planner.py system.json ## Adjacent Skills -- `../../skills/gdpr-dsgvo-expert/` — GDPR DPIA + lawful basis (most AI systems also trigger GDPR) -- `../../../compliance-team-iso42001/` — ISO 42001 AIMS (voluntary management system that satisfies parts of Article 17 QMS for providers) -- `../../skills/information-security-manager-iso27001/` — ISO 27001 for cybersecurity requirements (Article 15) -- `../../skills/risk-management-specialist/` — ISO 14971 risk management (referenced for safety-component AI under Article 6(1)) -- `../../skills/mdr-745-specialist/` — MDR 2017/745 (medical-device AI overlap) -- `../../../../compliance-os/` — Meta-orchestrator for multi-framework programs -- `../../../../c-level-advisor/chief-ai-officer-advisor/` — Executive AI strategy +- `ra-qm-team/skills/gdpr-dsgvo-expert/` — GDPR DPIA + lawful basis (most AI systems also trigger GDPR) +- `ra-qm-team/compliance-team-iso42001/` — ISO 42001 AIMS (voluntary management system that satisfies parts of Article 17 QMS for providers) +- `ra-qm-team/skills/information-security-manager-iso27001/` — ISO 27001 for cybersecurity requirements (Article 15) +- `ra-qm-team/skills/risk-management-specialist/` — ISO 14971 risk management (referenced for safety-component AI under Article 6(1)) +- `ra-qm-team/skills/mdr-745-specialist/` — MDR 2017/745 (medical-device AI overlap) +- `compliance-os/` — Meta-orchestrator for multi-framework programs +- `c-level-advisor/chief-ai-officer-advisor/` — Executive AI strategy ## References diff --git a/ra-qm-team/skills/eu-ai-act-specialist/scripts/ai_system_risk_classifier.py b/ra-qm-team/skills/eu-ai-act-specialist/scripts/ai_system_risk_classifier.py index d5de086b..98759404 100644 --- a/ra-qm-team/skills/eu-ai-act-specialist/scripts/ai_system_risk_classifier.py +++ b/ra-qm-team/skills/eu-ai-act-specialist/scripts/ai_system_risk_classifier.py @@ -30,6 +30,14 @@ Input schema (JSON): ] } +Note on `article_5_practice`: this flag is the caller's legal pre-determination +that a listed Article 5 practice applies IN ITS PROHIBITED CONTEXT — the +classifier trusts it and does not re-derive it from the other fields. Context +matters: emotion recognition is prohibited under Article 5(1)(f) ONLY in +workplace and education settings (narrow safety/medical exceptions aside); +the same system in e.g. a retail setting is NOT prohibited — it is subject to +Article 50(3) transparency and possibly Annex III §1 (biometrics) high-risk rules. + Usage: python ai_system_risk_classifier.py # uses embedded 5-system sample python ai_system_risk_classifier.py path/to/systems.json @@ -45,9 +53,15 @@ from typing import Any, Dict, List, Optional SAMPLE: Dict[str, Any] = { "systems": [ { - "name": "Emotion recognition in retail store CCTV", - "intended_purpose": "Detect emotions of shoppers to optimize layout", - "users": "store_managers", + # Article 5(1)(f) prohibits emotion recognition ONLY in WORKPLACE and + # EDUCATION settings (with narrow safety/medical exceptions). The same + # system aimed at RETAIL shoppers is NOT prohibited — it falls under + # Article 50(3) transparency (limited-risk) and may be high-risk under + # Annex III §1 (biometrics). This sample uses a genuine workplace + # context so the prohibited tag is correct. + "name": "Emotion recognition of employees in workplace CCTV", + "intended_purpose": "Monitor employees' emotional state to score engagement", + "users": "hr_managers", "data_processes_natural_persons": True, "annex_iii_category": None, "performs_profiling": False, diff --git a/ra-qm-team/skills/fda-consultant-specialist/SKILL.md b/ra-qm-team/skills/fda-consultant-specialist/SKILL.md index 6fc4f6c4..0c9e8456 100644 --- a/ra-qm-team/skills/fda-consultant-specialist/SKILL.md +++ b/ra-qm-team/skills/fda-consultant-specialist/SKILL.md @@ -1,17 +1,17 @@ --- name: "fda-consultant-specialist" -description: FDA regulatory consultant for medical device companies. Provides 510(k)/PMA/De Novo pathway guidance, QSR (21 CFR 820) compliance, HIPAA assessments, and device cybersecurity. Use when user mentions FDA submission, 510(k), PMA, De Novo, QSR, premarket, predicate device, substantial equivalence, HIPAA medical device, or FDA cybersecurity. +description: FDA regulatory consultant for medical device companies. Provides 510(k)/PMA/De Novo pathway guidance, QMSR (21 CFR 820, which incorporates ISO 13485:2016 by reference since 2026-02-02; formerly QSR) compliance, HIPAA assessments, and device cybersecurity. Use when user mentions FDA submission, 510(k), PMA, De Novo, QMSR, QSR, ISO 13485 for FDA, premarket, predicate device, substantial equivalence, HIPAA medical device, or FDA cybersecurity. --- # FDA Consultant Specialist -FDA regulatory consulting for medical device manufacturers covering submission pathways, Quality System Regulation (QSR), HIPAA compliance, and device cybersecurity requirements. +FDA regulatory consulting for medical device manufacturers covering submission pathways, the Quality Management System Regulation (QMSR, 21 CFR Part 820 — formerly the QSR), HIPAA compliance, and device cybersecurity requirements. ## Table of Contents - [FDA Pathway Selection](#fda-pathway-selection) - [510(k) Submission Process](#510k-submission-process) -- [QSR Compliance](#qsr-compliance) +- [QMSR Compliance (formerly QSR)](#qmsr-compliance-formerly-qsr) - [HIPAA for Medical Devices](#hipaa-for-medical-devices) - [Device Cybersecurity](#device-cybersecurity) - [Resources](#resources) @@ -39,13 +39,15 @@ Predicate device exists? ### Pathway Comparison -| Pathway | When to Use | Timeline | Cost | -|---------|-------------|----------|------| -| 510(k) Traditional | Predicate exists, design changes | 90 days | $21,760 | -| 510(k) Special | Manufacturing changes only | 30 days | $21,760 | -| 510(k) Abbreviated | Guidance/standard conformance | 30 days | $21,760 | -| De Novo | Novel, low-moderate risk | 150 days | $134,676 | -| PMA | Class III, no predicate | 180+ days | $425,000+ | +| Pathway | When to Use | Timeline | User Fee (FY2024) | +|---------|-------------|----------|-------------------| +| 510(k) Traditional | Predicate exists, design changes | 90 days | $21,760 (FY2024) | +| 510(k) Special | Manufacturing changes only | 30 days | $21,760 (FY2024) | +| 510(k) Abbreviated | Guidance/standard conformance | 30 days | $21,760 (FY2024) | +| De Novo | Novel, low-moderate risk | 150 days | $134,676 (FY2024) | +| PMA | Class III, no predicate | 180+ days | $425,000+ (FY2024) | + +> User fees are set annually under MDUFA. Verify current-fiscal-year fees at fda.gov (MDUFA user fee schedule) before budgeting; small-business rates differ. ### Pre-Submission Strategy @@ -115,23 +117,25 @@ Phase 4: Review --- -## QSR Compliance +## QMSR Compliance (formerly QSR) -Quality System Regulation (21 CFR Part 820) requirements for medical device manufacturers. +Quality Management System Regulation (QMSR) requirements for medical device manufacturers under 21 CFR Part 820. -### Key Subsystems +> **QMSR transition (effective 2026-02-02):** FDA's QMSR final rule (89 FR 7496) amended 21 CFR Part 820 to incorporate **ISO 13485:2016 by reference** and removed the legacy QSR subsection structure (820.20–820.198). Those subsection numbers are **historical** and no longer exist in the CFR; the corresponding requirements now flow from ISO 13485:2016 clauses plus the retained/renumbered sections 820.10 (requirements, incl. the ISO 13485 incorporation), 820.35 (records), and 820.45 (device labeling and packaging controls). 21 CFR Parts 801, 803, 806, and 830 are unchanged. Legacy QSR numbers below are kept only as a familiar index, each mapped to its current ISO 13485 clause. -| Section | Title | Focus | -|---------|-------|-------| -| 820.20 | Management Responsibility | Quality policy, org structure, management review | -| 820.30 | Design Controls | Input, output, review, verification, validation | -| 820.40 | Document Controls | Approval, distribution, change control | -| 820.50 | Purchasing Controls | Supplier qualification, purchasing data | -| 820.70 | Production Controls | Process validation, environmental controls | -| 820.100 | CAPA | Root cause analysis, corrective actions | -| 820.181 | Device Master Record | Specifications, procedures, acceptance criteria | +### Key Quality Subsystems (legacy QSR index → current ISO 13485:2016 clause) -### Design Controls Workflow (820.30) +| Legacy QSR Section (historical, pre-2026) | Title | Current authority under QMSR | Focus | +|-------------------------------------------|-------|------------------------------|-------| +| 820.20 | Management Responsibility | ISO 13485 §5.1, 5.5, 5.6 | Quality policy, org structure, management review | +| 820.30 | Design Controls | ISO 13485 §7.3 | Input, output, review, verification, validation | +| 820.40 | Document Controls | ISO 13485 §4.2.4 | Approval, distribution, change control | +| 820.50 | Purchasing Controls | ISO 13485 §7.4 | Supplier qualification, purchasing data | +| 820.70 | Production Controls | ISO 13485 §6.3, 6.4, 7.5 | Process validation, environmental controls | +| 820.100 | CAPA | ISO 13485 §8.5.2, 8.5.3 | Root cause analysis, corrective actions | +| 820.181 | Device Master Record | ISO 13485 §4.2.3 (medical device file) + 21 CFR 820.35 | Specifications, procedures, acceptance criteria | + +### Design Controls Workflow (ISO 13485 §7.3; legacy QSR 820.30) ``` Step 1: Design Input @@ -159,7 +163,7 @@ Step 6: Design Transfer Verification: Transfer checklist complete? ``` -### CAPA Process (820.100) +### CAPA Process (ISO 13485 §8.5.2/8.5.3; legacy QSR 820.100) 1. **Identify**: Document nonconformity or potential problem 2. **Investigate**: Perform root cause analysis (5 Whys, Fishbone) @@ -169,7 +173,7 @@ Step 6: Design Transfer 6. **Effectiveness**: Monitor for recurrence (30-90 days) 7. **Close**: Management approval and closure -**Reference:** See [qsr_compliance_requirements.md](references/qsr_compliance_requirements.md) for detailed QSR implementation guidance. +**Reference:** See [qsr_compliance_requirements.md](references/qsr_compliance_requirements.md) for the historical QSR structure with full QMSR/ISO 13485:2016 clause mapping. --- @@ -280,7 +284,7 @@ Coordinated Public Disclosure | Script | Purpose | |--------|---------| | `fda_submission_tracker.py` | Track 510(k)/PMA/De Novo submission milestones and timelines | -| `qsr_compliance_checker.py` | Assess 21 CFR 820 compliance against project documentation | +| `qsr_compliance_checker.py` | Assess QMS documentation against the legacy-QSR checklist mapped to ISO 13485:2016 (QMSR) | | `hipaa_risk_assessment.py` | Evaluate HIPAA safeguards in medical device software | ### references/ @@ -288,7 +292,7 @@ Coordinated Public Disclosure | File | Content | |------|---------| | `fda_submission_guide.md` | 510(k), De Novo, PMA submission requirements and checklists | -| `qsr_compliance_requirements.md` | 21 CFR 820 implementation guide with templates | +| `qsr_compliance_requirements.md` | Historical QSR structure with QMSR/ISO 13485:2016 mapping, implementation templates | | `hipaa_compliance_framework.md` | HIPAA Security Rule safeguards and BAA requirements | | `device_cybersecurity_guidance.md` | FDA cybersecurity requirements, SBOM, threat modeling | | `fda_capa_requirements.md` | CAPA process, root cause analysis, effectiveness verification | @@ -299,8 +303,8 @@ Coordinated Public Disclosure # Track FDA submission status python scripts/fda_submission_tracker.py /path/to/project --type 510k -# Assess QSR compliance -python scripts/qsr_compliance_checker.py /path/to/project --section 820.30 +# Assess QMS documentation (legacy QSR section keys, mapped to ISO 13485 under QMSR) +python scripts/qsr_compliance_checker.py /path/to/project --section 820.30 # legacy checklist key = ISO 13485 §7.3 (design & development) # Run HIPAA risk assessment python scripts/hipaa_risk_assessment.py /path/to/project --category technical diff --git a/ra-qm-team/skills/fda-consultant-specialist/references/qsr_compliance_requirements.md b/ra-qm-team/skills/fda-consultant-specialist/references/qsr_compliance_requirements.md index e6372f5c..f25edd33 100644 --- a/ra-qm-team/skills/fda-consultant-specialist/references/qsr_compliance_requirements.md +++ b/ra-qm-team/skills/fda-consultant-specialist/references/qsr_compliance_requirements.md @@ -1,6 +1,15 @@ -# Quality System Regulation (QSR) Compliance +# Quality System Regulation (QSR) — Historical Structure with QMSR/ISO 13485:2016 Mapping -Complete guide to 21 CFR Part 820 requirements for medical device manufacturers. +> ## ⚠️ STATUS: QMSR transition — the QSR structure below is HISTORICAL +> +> FDA's **Quality Management System Regulation (QMSR)** final rule (89 FR 7496) took effect **February 2, 2026**, amending 21 CFR Part 820 to **incorporate ISO 13485:2016 by reference** and removing the QSR subsection structure documented in this guide. The section numbers used below (820.20–820.250) **no longer exist in the CFR**; they are retained here only as a familiar index into requirements that now flow from ISO 13485:2016 clauses. +> +> **What remains in 21 CFR 820 under the QMSR:** 820.10 (requirements, incl. the ISO 13485:2016 incorporation by reference and Part 830 UDI linkage), 820.35 (records — complaint and servicing-record additions to ISO 13485), 820.45 (device labeling and packaging controls). +> **Unchanged:** 21 CFR Parts 801 (labeling), 803 (MDR), 806 (corrections and removals), 830 (UDI). +> +> Use the [Regulatory Cross-References](#regulatory-cross-references) table at the end of this guide to map every historical QSR section to its current QMSR/ISO 13485:2016 authority. The implementation guidance and templates below remain useful — quality system expectations are substantially the same under ISO 13485 — but **cite ISO 13485 clauses (or retained 820.10/.35/.45), not the historical subsection numbers, in current compliance documentation.** + +Implementation guide to the historical 21 CFR Part 820 (QSR) structure for medical device manufacturers, mapped to the QMSR/ISO 13485:2016 requirements now in force. --- @@ -38,10 +47,10 @@ The QSR applies to: | Class II | Full QSR compliance | | Class III | Full QSR compliance | -### QSR Structure +### QSR Structure (historical, pre-2026-02-02) ``` -21 CFR Part 820 Subparts: +21 CFR Part 820 Subparts (removed by the QMSR; historical reference only): ├── A - General Provisions (820.1-5) ├── B - Quality System Requirements (820.20-25) ├── C - Design Controls (820.30) @@ -742,12 +751,26 @@ Device Master Record ### Regulatory Cross-References -| QSR Section | ISO 13485 Clause | -|-------------|------------------| -| 820.20 | 5.1, 5.5, 5.6 | -| 820.30 | 7.3 | -| 820.40 | 4.2.4 | -| 820.50 | 7.4 | -| 820.70 | 7.5.1 | -| 820.75 | 7.5.6 | -| 820.100 | 8.5.2, 8.5.3 | +Historical QSR sections (removed effective 2026-02-02) mapped to their current QMSR/ISO 13485:2016 authority: + +| Historical QSR Section | Title | Current QMSR / ISO 13485:2016 authority | +|------------------------|-------|------------------------------------------| +| 820.20 | Management responsibility | ISO 13485 §5.1, 5.5, 5.6 | +| 820.30 | Design controls | ISO 13485 §7.3 | +| 820.40 | Document controls | ISO 13485 §4.2.4 | +| 820.50 | Purchasing controls | ISO 13485 §7.4 | +| 820.60–.65 | Identification and traceability | ISO 13485 §7.5.8, 7.5.9 | +| 820.70 | Production and process controls | ISO 13485 §6.3, 6.4, 7.5.1 | +| 820.72 | Inspection, measuring, test equipment | ISO 13485 §7.6 | +| 820.75 | Process validation | ISO 13485 §7.5.6 | +| 820.80–.86 | Acceptance activities | ISO 13485 §7.4.3, 8.2.6 | +| 820.90 | Nonconforming product | ISO 13485 §8.3 | +| 820.100 | CAPA | ISO 13485 §8.5.2, 8.5.3 | +| 820.120–.130 | Labeling and packaging | 21 CFR 820.45 (retained) + ISO 13485 §7.5.1 | +| 820.140–.170 | Handling, storage, distribution, installation | ISO 13485 §7.5.5, 7.5.3 | +| 820.180–.186 | Records (incl. DMR 820.181, DHR 820.184, QSR 820.186) | ISO 13485 §4.2.3 (medical device file), 4.2.5 (records) + 21 CFR 820.35 (retained) | +| 820.198 | Complaint files | ISO 13485 §8.2.2 + 21 CFR 820.35(b) | +| 820.200 | Servicing | ISO 13485 §7.5.4 + 21 CFR 820.35 | +| 820.250 | Statistical techniques | ISO 13485 §8.1 | + +Retained/renumbered under QMSR: 820.10 (requirements; incorporates ISO 13485:2016 by reference), 820.35 (records), 820.45 (device labeling and packaging controls). Unchanged: 21 CFR 801, 803, 806, 830. diff --git a/ra-qm-team/skills/fda-consultant-specialist/scripts/qsr_compliance_checker.py b/ra-qm-team/skills/fda-consultant-specialist/scripts/qsr_compliance_checker.py index 45e1c385..7eb3426d 100644 --- a/ra-qm-team/skills/fda-consultant-specialist/scripts/qsr_compliance_checker.py +++ b/ra-qm-team/skills/fda-consultant-specialist/scripts/qsr_compliance_checker.py @@ -1,9 +1,17 @@ #!/usr/bin/env python3 """ -QSR Compliance Checker +QMS Documentation Checker (legacy-QSR checklist mapped to ISO 13485:2016 under the QMSR) -Assesses compliance with 21 CFR Part 820 (Quality System Regulation) by analyzing -project documentation and identifying gaps. +Assesses quality system documentation against a checklist organized by the +HISTORICAL Quality System Regulation (QSR) subsection structure of 21 CFR Part 820. + +IMPORTANT — QMSR transition: FDA's Quality Management System Regulation (QMSR) +final rule (89 FR 7496) took effect 2026-02-02. It amended 21 CFR Part 820 to +incorporate ISO 13485:2016 by reference and REMOVED the legacy QSR subsections +(820.20-820.198) used as keys below. Those numbers are retained here only as a +familiar checklist index; each maps to the ISO 13485:2016 clause that is the +current legal authority (see QSR_TO_ISO13485). This tool checks documentation +coverage — it does not determine current-law compliance. Usage: python qsr_compliance_checker.py <project_dir> @@ -21,7 +29,26 @@ from pathlib import Path from typing import Dict, List, Optional, Any -# QSR sections and requirements +# Historical QSR section -> current QMSR / ISO 13485:2016 authority +# (legacy subsections removed by the QMSR effective 2026-02-02) +QSR_TO_ISO13485 = { + "820.20": "ISO 13485 §5.1/5.5/5.6", + "820.30": "ISO 13485 §7.3", + "820.40": "ISO 13485 §4.2.4", + "820.50": "ISO 13485 §7.4", + "820.70": "ISO 13485 §6.3/6.4/7.5.1", + "820.72": "ISO 13485 §7.6", + "820.75": "ISO 13485 §7.5.6", + "820.90": "ISO 13485 §8.3", + "820.100": "ISO 13485 §8.5.2/8.5.3", + "820.120": "21 CFR 820.45 (retained) + ISO 13485 §7.5.1", + "820.180": "ISO 13485 §4.2.5 + 21 CFR 820.35 (retained)", + "820.181": "ISO 13485 §4.2.3 (medical device file)", + "820.184": "ISO 13485 §4.2.5 + 21 CFR 820.35", + "820.198": "ISO 13485 §8.2.2 + 21 CFR 820.35(b)", +} + +# Legacy QSR sections and requirements (historical index; see QSR_TO_ISO13485 for current authority) QSR_REQUIREMENTS = { "820.20": { "title": "Management Responsibility", @@ -502,8 +529,13 @@ def calculate_overall_compliance(assessment_results: List[Dict]) -> Dict: def print_text_report(result: Dict) -> None: """Print human-readable compliance report.""" print("=" * 70) - print("21 CFR PART 820 (QSR) COMPLIANCE ASSESSMENT") + print("QMS DOCUMENTATION ASSESSMENT") + print("(legacy-QSR checklist mapped to ISO 13485:2016 under the QMSR)") print("=" * 70) + print("NOTE: Section numbers are the HISTORICAL pre-2026 QSR structure,") + print("retained as checklist keys only. Since 2026-02-02 the QMSR (89 FR") + print("7496) incorporates ISO 13485:2016 by reference into 21 CFR 820;") + print("the ISO 13485 clause shown per section is the current authority.") # Overall compliance overall = result["overall_compliance"] @@ -512,10 +544,11 @@ def print_text_report(result: Dict) -> None: print(f"Compliant/Partial: {overall['compliant_subsections']}") # Section summary - print("\n--- SECTION SCORES ---") + print("\n--- SECTION SCORES (legacy QSR key -> current ISO 13485 authority) ---") for section in result["assessment"]: status = "OK" if section["compliance_score"] >= 70 else "GAP" - print(f" {section['section']} {section['title']}: {section['compliance_score']}% [{status}]") + iso_ref = QSR_TO_ISO13485.get(section["section"], "see ISO 13485:2016") + print(f" {section['section']} {section['title']} [{iso_ref}]: {section['compliance_score']}% [{status}]") # Gap analysis gap_report = result["gap_report"] @@ -542,7 +575,12 @@ def print_text_report(result: Dict) -> None: def main(): parser = argparse.ArgumentParser( - description="QSR Compliance Checker - Assess 21 CFR 820 compliance" + description=( + "QMS Documentation Checker — assesses documentation against the legacy " + "QSR checklist mapped to ISO 13485:2016, the current authority under " + "FDA's QMSR (21 CFR 820 as amended effective 2026-02-02). Legacy " + "820.x section numbers are historical checklist keys, not current law." + ) ) parser.add_argument( "project_dir", @@ -552,7 +590,7 @@ def main(): ) parser.add_argument( "--section", - help="Analyze specific QSR section only (e.g., 820.30)" + help="Analyze one legacy-QSR checklist section only (e.g., 820.30 -> ISO 13485 §7.3 under QMSR)" ) parser.add_argument( "--json", @@ -595,6 +633,10 @@ def main(): result = { "project_dir": str(project_dir), "assessment_date": datetime.now().isoformat(), + "regulatory_basis": ( + "Legacy-QSR checklist keys (historical, pre-2026) mapped to ISO 13485:2016, " + "incorporated by reference into 21 CFR 820 by the QMSR effective 2026-02-02" + ), "overall_compliance": overall_compliance, "assessment": assessment_results if args.detailed else [ { diff --git a/ra-qm-team/skills/gdpr-dsgvo-expert/SKILL.md b/ra-qm-team/skills/gdpr-dsgvo-expert/SKILL.md index 8b6f989f..7a9bb26b 100644 --- a/ra-qm-team/skills/gdpr-dsgvo-expert/SKILL.md +++ b/ra-qm-team/skills/gdpr-dsgvo-expert/SKILL.md @@ -1,6 +1,6 @@ --- name: "gdpr-dsgvo-expert" -description: GDPR and German DSGVO compliance automation. Scans codebases for privacy risks, generates DPIA documentation, tracks data subject rights requests. Use for GDPR compliance assessments, privacy audits, data protection planning, DPIA generation, and data subject rights management. +description: GDPR and German DSGVO compliance automation. Scans codebases for privacy risks, generates DPIA documentation, tracks data subject rights requests with Art. 12(3) one-month deadlines. Use when running GDPR compliance assessments, privacy audits, data protection planning, DPIA generation, or data subject rights (DSAR) management (e.g., 'check this service for GDPR risks', 'track an access request deadline'). Final compliance determinations route to the DPO or legal counsel. --- # GDPR/DSGVO Expert @@ -75,7 +75,7 @@ python scripts/dpia_generator.py --input input.json --output dpia_report.md - Systematic monitoring (Art. 35(3)(c)) - Large-scale special category data (Art. 35(3)(b)) - Automated decision-making (Art. 35(3)(a)) -- WP29 high-risk criteria +- EDPB-endorsed high-risk criteria (WP248 rev.01) --- @@ -105,13 +105,13 @@ python scripts/data_subject_rights_tracker.py template --id DSR-202601-0001 | Right | Article | Deadline | |-------|---------|----------| -| Access | Art. 15 | 30 days | -| Rectification | Art. 16 | 30 days | -| Erasure | Art. 17 | 30 days | -| Restriction | Art. 18 | 30 days | -| Portability | Art. 20 | 30 days | -| Objection | Art. 21 | 30 days | -| Automated decisions | Art. 22 | 30 days | +| Access | Art. 15 | One month (Art. 12(3)) | +| Rectification | Art. 16 | One month (Art. 12(3)) | +| Erasure | Art. 17 | One month (Art. 12(3)) | +| Restriction | Art. 18 | One month (Art. 12(3)) | +| Portability | Art. 20 | One month (Art. 12(3)) | +| Objection | Art. 21 | One month (Art. 12(3)) | +| Automated decisions | Art. 22 | One month (Art. 12(3)) | **Features:** - Deadline tracking with overdue alerts @@ -150,7 +150,7 @@ German-specific requirements including: Step-by-step DPIA process: - Threshold assessment criteria -- WP29 high-risk indicators +- EDPB-endorsed high-risk indicators (WP248 rev.01) - Risk assessment methodology - Mitigation measure categories - DPO and supervisory authority consultation @@ -248,7 +248,7 @@ Requires explicit consent or Art. 9(2) exception: ### Data Subject Rights -All rights must be fulfilled within **30 days** (extendable to 90 for complex requests): +All rights must be fulfilled within **one month of receipt** (Art. 12(3)). The deadline runs by calendar month, not 30 days, and may be extended by **two further months** for complex or numerous requests — the data subject must be informed of the extension (with reasons) within the first month: - **Access**: Provide copy of data and processing information - **Rectification**: Correct inaccurate data - **Erasure**: Delete data (with exceptions for legal obligations) diff --git a/ra-qm-team/skills/gdpr-dsgvo-expert/references/gdpr_compliance_guide.md b/ra-qm-team/skills/gdpr-dsgvo-expert/references/gdpr_compliance_guide.md index 5cd19df0..c176958d 100644 --- a/ra-qm-team/skills/gdpr-dsgvo-expert/references/gdpr_compliance_guide.md +++ b/ra-qm-team/skills/gdpr-dsgvo-expert/references/gdpr_compliance_guide.md @@ -93,7 +93,7 @@ Additional safeguards required for: 1. Receive request (any form acceptable) 2. Verify identity (proportionate measures) 3. Gather data from all systems -4. Provide response within 30 days +4. Provide response within one month (Art. 12(3); extendable by two further months for complex requests) 5. First copy free; reasonable fee for additional ### Right to Rectification (Art. 16) @@ -106,7 +106,7 @@ Additional safeguards required for: 1. Verify claimed inaccuracy 2. Correct data in all systems 3. Notify third parties of correction -4. Respond within 30 days +4. Respond within one month (Art. 12(3)) ### Right to Erasure (Art. 17) diff --git a/ra-qm-team/skills/gdpr-dsgvo-expert/scripts/data_subject_rights_tracker.py b/ra-qm-team/skills/gdpr-dsgvo-expert/scripts/data_subject_rights_tracker.py index da9354b7..d0e6cde7 100644 --- a/ra-qm-team/skills/gdpr-dsgvo-expert/scripts/data_subject_rights_tracker.py +++ b/ra-qm-team/skills/gdpr-dsgvo-expert/scripts/data_subject_rights_tracker.py @@ -22,12 +22,30 @@ from typing import Dict, List, Optional from uuid import uuid4 +def add_months(dt: datetime, months: int) -> datetime: + """Add calendar months per GDPR Art. 12(3) (one month, not 30 days). + + If the target month has no equivalent day (e.g., Jan 31 + 1 month), + clamp to the last day of the target month. + """ + month_index = dt.month - 1 + months + year = dt.year + month_index // 12 + month = month_index % 12 + 1 + # last day of target month + if month == 12: + next_month_first = datetime(year + 1, 1, 1) + else: + next_month_first = datetime(year, month + 1, 1) + last_day = (next_month_first - timedelta(days=1)).day + return dt.replace(year=year, month=month, day=min(dt.day, last_day)) + + # GDPR Articles for each right RIGHTS_TYPES = { "access": { "article": "Art. 15", "name": "Right of Access", - "deadline_days": 30, + "deadline_months": 1, # Art. 12(3): one month of receipt "description": "Data subject has the right to obtain confirmation of processing and access to their data", "response_includes": [ "Purposes of processing", @@ -42,7 +60,7 @@ RIGHTS_TYPES = { "rectification": { "article": "Art. 16", "name": "Right to Rectification", - "deadline_days": 30, + "deadline_months": 1, # Art. 12(3): one month of receipt "description": "Data subject has the right to have inaccurate personal data corrected", "response_includes": [ "Confirmation of correction", @@ -53,7 +71,7 @@ RIGHTS_TYPES = { "erasure": { "article": "Art. 17", "name": "Right to Erasure (Right to be Forgotten)", - "deadline_days": 30, + "deadline_months": 1, # Art. 12(3): one month of receipt "description": "Data subject has the right to have their personal data erased", "grounds": [ "Data no longer necessary for original purpose", @@ -74,7 +92,7 @@ RIGHTS_TYPES = { "restriction": { "article": "Art. 18", "name": "Right to Restriction of Processing", - "deadline_days": 30, + "deadline_months": 1, # Art. 12(3): one month of receipt "description": "Data subject has the right to restrict processing of their data", "grounds": [ "Accuracy contested (during verification)", @@ -86,7 +104,7 @@ RIGHTS_TYPES = { "portability": { "article": "Art. 20", "name": "Right to Data Portability", - "deadline_days": 30, + "deadline_months": 1, # Art. 12(3): one month of receipt "description": "Data subject has the right to receive their data in a portable format", "conditions": [ "Processing based on consent or contract", @@ -101,7 +119,7 @@ RIGHTS_TYPES = { "objection": { "article": "Art. 21", "name": "Right to Object", - "deadline_days": 30, + "deadline_months": 1, # Art. 12(3): one month of receipt "description": "Data subject has the right to object to processing", "applies_to": [ "Processing based on legitimate interests", @@ -112,7 +130,7 @@ RIGHTS_TYPES = { "automated": { "article": "Art. 22", "name": "Rights Related to Automated Decision-Making", - "deadline_days": 30, + "deadline_months": 1, # Art. 12(3): one month of receipt "description": "Data subject has the right not to be subject to solely automated decisions", "includes": [ "Right to human intervention", @@ -173,7 +191,8 @@ class RightsTracker: right_info = RIGHTS_TYPES[right_type] now = datetime.now() - deadline = now + timedelta(days=right_info["deadline_days"]) + # Art. 12(3): respond within one calendar month of receipt + deadline = add_months(now, right_info["deadline_months"]) request = { "id": self._generate_id(), @@ -223,9 +242,10 @@ class RightsTracker: elif new_status == "completed": req["dates"]["completed"] = datetime.now().isoformat() elif new_status == "extended": - # Extend deadline by additional 60 days (max total 90) + # Art. 12(3): extendable by two further calendar months for + # complex/numerous requests (data subject informed within month 1) original_deadline = datetime.fromisoformat(req["dates"]["deadline"]) - req["dates"]["deadline"] = (original_deadline + timedelta(days=60)).isoformat() + req["dates"]["deadline"] = add_months(original_deadline, 2).isoformat() if note: req["notes"].append({ @@ -531,7 +551,7 @@ def main(): for key, info in RIGHTS_TYPES.items(): print(f"\n{key} ({info['article']})") print(f" {info['name']}") - print(f" Deadline: {info['deadline_days']} days") + print(f" Deadline: {info['deadline_months']} calendar month(s) (Art. 12(3))") else: parser.print_help() diff --git a/ra-qm-team/skills/information-security-manager-iso27001/SKILL.md b/ra-qm-team/skills/information-security-manager-iso27001/SKILL.md index 77723e96..62102a4a 100644 --- a/ra-qm-team/skills/information-security-manager-iso27001/SKILL.md +++ b/ra-qm-team/skills/information-security-manager-iso27001/SKILL.md @@ -1,6 +1,6 @@ --- name: "information-security-manager-iso27001" -description: ISO 27001 ISMS implementation and cybersecurity governance for HealthTech and MedTech companies. Use for ISMS design, security risk assessment, control implementation, ISO 27001 certification, security audits, incident response, and compliance verification. Covers ISO 27001, ISO 27002, healthcare security, and medical device cybersecurity. +description: ISO 27001 ISMS implementation and cybersecurity governance for HealthTech and MedTech companies. Use when designing an ISMS, running security risk assessments, implementing controls, pursuing ISO 27001 certification, preparing security audits, responding to security incidents, or verifying compliance. Covers ISO 27001, ISO 27002, healthcare security, and medical device cybersecurity. --- # Information Security Manager - ISO 27001 diff --git a/ra-qm-team/skills/iso42001-specialist/SKILL.md b/ra-qm-team/skills/iso42001-specialist/SKILL.md index 9b9534e1..fcea193d 100644 --- a/ra-qm-team/skills/iso42001-specialist/SKILL.md +++ b/ra-qm-team/skills/iso42001-specialist/SKILL.md @@ -173,14 +173,14 @@ python scripts/aims_audit_scheduler.py audit_scope.json ## Adjacent Skills -- `../../skills/information-security-manager-iso27001/` — ISO 27001 ISMS implementation (many controls reusable for AIMS A.7 data controls) -- `../../skills/quality-manager-qms-iso13485/` — ISO 13485 QMS (provides CAPA + management-review machinery the AIMS reuses) -- `../../skills/gdpr-dsgvo-expert/` — GDPR DPIA process (input to AIMS A.5 impact assessment for personal-data systems) -- `../../skills/isms-audit-expert/` — ISO 27001 internal audit pattern (the audit scheduler mirrors this for AIMS) -- `../../skills/soc2-compliance/` — SOC 2 trust services (reusable controls for AIMS A.10 third-party relationships) -- `../../../compliance-team-eu-ai-act/` — EU AI Act Article-level compliance (binding regulation companion to voluntary 42001) -- `../../../../compliance-os/` — Meta-orchestrator for multi-framework programs (run AIMS as one framework among 9) -- `../../../../c-level-advisor/chief-ai-officer-advisor/` — Executive AI strategy (build-vs-buy, cost economics — different audience) +- `ra-qm-team/skills/information-security-manager-iso27001/` — ISO 27001 ISMS implementation (many controls reusable for AIMS A.7 data controls) +- `ra-qm-team/skills/quality-manager-qms-iso13485/` — ISO 13485 QMS (provides CAPA + management-review machinery the AIMS reuses) +- `ra-qm-team/skills/gdpr-dsgvo-expert/` — GDPR DPIA process (input to AIMS A.5 impact assessment for personal-data systems) +- `ra-qm-team/skills/isms-audit-expert/` — ISO 27001 internal audit pattern (the audit scheduler mirrors this for AIMS) +- `ra-qm-team/skills/soc2-compliance/` — SOC 2 trust services (reusable controls for AIMS A.10 third-party relationships) +- `ra-qm-team/compliance-team-eu-ai-act/` — EU AI Act Article-level compliance (binding regulation companion to voluntary 42001) +- `compliance-os/` — Meta-orchestrator for multi-framework programs (run AIMS as one framework among 9) +- `c-level-advisor/chief-ai-officer-advisor/` — Executive AI strategy (build-vs-buy, cost economics — different audience) ## References diff --git a/ra-qm-team/skills/mdr-745-specialist/SKILL.md b/ra-qm-team/skills/mdr-745-specialist/SKILL.md index bc938801..8355cd26 100644 --- a/ra-qm-team/skills/mdr-745-specialist/SKILL.md +++ b/ra-qm-team/skills/mdr-745-specialist/SKILL.md @@ -1,6 +1,6 @@ --- name: "mdr-745-specialist" -description: EU MDR 2017/745 compliance specialist for medical device classification, technical documentation, clinical evidence, and post-market surveillance. Covers Annex VIII classification rules, Annex II/III technical files, Annex XIV clinical evaluation, and EUDAMED integration. +description: EU MDR 2017/745 compliance specialist for medical device classification, technical documentation, clinical evidence, and post-market surveillance. Covers Annex VIII classification rules, Annex II/III technical files, Annex XIV clinical evaluation, Art. 86 PSUR schedules, and EUDAMED integration. Use when classifying a medical device under MDR, building or gap-checking a technical file, planning clinical evaluation or PMS/PSUR cadence, or preparing for notified body review (e.g., 'what class is my device under MDR', 'review my PSUR schedule'). triggers: - MDR compliance - EU MDR @@ -125,8 +125,8 @@ ANNEX II TECHNICAL DOCUMENTATION | I | Annex II self-declaration | None | | Is/Im | Annex II + IX/XI | Sterile/measuring aspects | | IIa | Annex II + IX or XI | Product or QMS | -| IIb | Annex IX + X or X + XI | Type exam + production | -| III | Annex IX + X | Full QMS + type exam | +| IIb | Annex IX, or Annex X + XI | QMS + tech doc assessment, or type exam + production | +| III | Annex IX, or Annex X + XI | Full QMS + product dossier, or type exam + production | --- @@ -193,19 +193,19 @@ Establish PMS system per Chapter VII: | Component | Requirement | Frequency | |-----------|-------------|-----------| | PMS Plan | Article 84 | Maintain current | -| PSUR | Class IIa and higher | Per class schedule | +| PSUR | Article 86 — Class IIa and higher | Per Art. 86(1) schedule below | | PMCF Plan | Annex XIV Part B | Update with CER | | PMCF Report | Annex XIV Part B | Annual (Class III) | | Vigilance | Articles 87-92 | As events occur | ### PSUR Schedule -| Class | Frequency | -|-------|-----------| -| Class III | Annual | -| Class IIb implantable | Annual | -| Class IIb | Every 2 years | -| Class IIa | When necessary | +| Class | Frequency (MDR Art. 86(1)) | +|-------|-----------------------------| +| Class III | Updated at least annually | +| Class IIb (all, incl. implantable) | Updated at least annually | +| Class IIa | When necessary, at least every 2 years | +| Class I | No PSUR — PMS report instead (Art. 85) | ### Serious Incident Reporting diff --git a/ra-qm-team/skills/qms-audit-expert/SKILL.md b/ra-qm-team/skills/qms-audit-expert/SKILL.md index 65941251..9705a0f4 100644 --- a/ra-qm-team/skills/qms-audit-expert/SKILL.md +++ b/ra-qm-team/skills/qms-audit-expert/SKILL.md @@ -1,6 +1,6 @@ --- name: "qms-audit-expert" -description: ISO 13485 internal audit expertise for medical device QMS. Covers audit planning, execution, nonconformity classification, and CAPA verification. Use for internal audit planning, audit execution, finding classification, external audit preparation, or audit program management. +description: ISO 13485 internal audit expertise for medical device QMS. Covers audit planning, execution, nonconformity classification, and CAPA verification. Use when planning internal audits, executing audits, classifying findings, preparing for external audits, or managing an audit program. triggers: - ISO 13485 audit - internal audit diff --git a/ra-qm-team/skills/quality-documentation-manager/SKILL.md b/ra-qm-team/skills/quality-documentation-manager/SKILL.md index c461077f..3581400c 100644 --- a/ra-qm-team/skills/quality-documentation-manager/SKILL.md +++ b/ra-qm-team/skills/quality-documentation-manager/SKILL.md @@ -1,6 +1,6 @@ --- name: "quality-documentation-manager" -description: Document control system management for medical device QMS. Covers document numbering, version control, change management, and 21 CFR Part 11 compliance. Use for document control procedures, change control workflow, document numbering, version management, electronic signature compliance, or regulatory documentation review. +description: Document control system management for medical device QMS. Covers document numbering, version control, change management, and 21 CFR Part 11 compliance. Use when working on document control procedures, change control workflows, document numbering, version management, electronic signature compliance, or regulatory documentation review. triggers: - document control - document numbering diff --git a/ra-qm-team/skills/quality-manager-qmr/SKILL.md b/ra-qm-team/skills/quality-manager-qmr/SKILL.md index 5758133d..dcbb834b 100644 --- a/ra-qm-team/skills/quality-manager-qmr/SKILL.md +++ b/ra-qm-team/skills/quality-manager-qmr/SKILL.md @@ -1,6 +1,6 @@ --- name: "quality-manager-qmr" -description: Senior Quality Manager Responsible Person (QMR) for HealthTech and MedTech companies. Provides quality system governance, management review leadership, regulatory compliance oversight, and quality performance monitoring per ISO 13485 Clause 5.5.2. +description: Senior Quality Manager Responsible Person (QMR) for HealthTech and MedTech companies. Provides quality system governance, management review leadership, regulatory compliance oversight, and quality performance monitoring per ISO 13485 Clause 5.5.2. Use when leading management reviews, setting quality policy and objectives, monitoring quality KPIs and cost of quality, or exercising QMR governance and regulatory oversight responsibilities. triggers: - management review - quality policy diff --git a/ra-qm-team/skills/ra-qm-skills/SKILL.md b/ra-qm-team/skills/ra-qm-skills/SKILL.md index 2a54e6c1..c88ddf7c 100644 --- a/ra-qm-team/skills/ra-qm-skills/SKILL.md +++ b/ra-qm-team/skills/ra-qm-skills/SKILL.md @@ -1,6 +1,6 @@ --- name: "ra-qm-skills" -description: "12 regulatory & QM agent skills and plugins for Claude Code, Codex, Gemini CLI, Cursor, OpenClaw. ISO 13485 QMS, MDR 2017/745, FDA 510(k)/PMA, ISO 27001 ISMS, GDPR/DSGVO, risk management (ISO 14971), CAPA, document control, auditing. Python tools (stdlib-only)." +description: "Router/index for the 15 regulatory & quality-management skills bundled in this plugin (ISO 13485 QMS, EU MDR 2017/745, FDA submissions under QMSR, ISO 14971 risk, CAPA, document control, ISO 27001/ISMS, ISO 42001 AIMS, EU AI Act, GDPR/DSGVO, SOC 2, auditing). Use when a compliance request doesn't obviously match one skill and you need to pick the right one (e.g., 'prepare us for an ISO 13485 audit', 'is my AI system high-risk under the AI Act')." version: 2.9.0 author: Alireza Rezvani license: MIT @@ -18,49 +18,42 @@ agents: - openclaw --- -# Regulatory Affairs & Quality Management Skills +# Regulatory Affairs & Quality Management Skills — Router -12 production-ready compliance skills for HealthTech and MedTech organizations. +This plugin bundles **15 compliance skills** for HealthTech/MedTech organizations (this router is the 16th folder under `ra-qm-team/skills/`). Each skill is self-contained. -## Quick Start +## Routing table -### Claude Code -``` -/read ra-qm-team/regulatory-affairs-head/SKILL.md -``` +Match the request, then load `ra-qm-team/skills/<skill>/SKILL.md`. If multiple rows match, ask one clarifying question first. -### Codex CLI -```bash -npx agent-skills-cli add alirezarezvani/claude-skills/ra-qm-team -``` +| Request signals | Skill | Path | +|---|---|---| +| Regulatory strategy, pathway selection, submissions planning | regulatory-affairs-head | `skills/regulatory-affairs-head/` | +| Management review, quality KPIs, QMR governance | quality-manager-qmr | `skills/quality-manager-qmr/` | +| ISO 13485 QMS implementation, process control | quality-manager-qms-iso13485 | `skills/quality-manager-qms-iso13485/` | +| ISO 14971 risk analysis, FMEA, risk files | risk-management-specialist | `skills/risk-management-specialist/` | +| Root cause analysis, corrective/preventive actions | capa-officer | `skills/capa-officer/` | +| Document control, 21 CFR Part 11, DHF/DMR/DHR | quality-documentation-manager | `skills/quality-documentation-manager/` | +| ISO 13485 internal audits, NC classification | qms-audit-expert | `skills/qms-audit-expert/` | +| ISO 27001 audit planning and execution | isms-audit-expert | `skills/isms-audit-expert/` | +| ISMS design, security risk assessment | information-security-manager-iso27001 | `skills/information-security-manager-iso27001/` | +| EU MDR classification, technical files, PSUR | mdr-745-specialist | `skills/mdr-745-specialist/` | +| FDA 510(k)/PMA/De Novo, QMSR | fda-consultant-specialist | `skills/fda-consultant-specialist/` | +| GDPR/DSGVO, DPIA, data subject rights | gdpr-dsgvo-expert | `skills/gdpr-dsgvo-expert/` | +| EU AI Act risk classification, obligations | eu-ai-act-specialist | `skills/eu-ai-act-specialist/` | +| ISO/IEC 42001 AI management system | iso42001-specialist | `skills/iso42001-specialist/` | +| SOC 2 Type I/II readiness, trust criteria | soc2-compliance | `skills/soc2-compliance/` | -## Skills Overview - -| Skill | Folder | Focus | -|-------|--------|-------| -| Regulatory Affairs Head | `regulatory-affairs-head/` | FDA/MDR strategy, submissions | -| Quality Manager (QMR) | `quality-manager-qmr/` | QMS governance, management review | -| Quality Manager (ISO 13485) | `quality-manager-qms-iso13485/` | QMS implementation, doc control | -| Risk Management Specialist | `risk-management-specialist/` | ISO 14971, FMEA, risk files | -| CAPA Officer | `capa-officer/` | Root cause analysis, corrective actions | -| Quality Documentation Manager | `quality-documentation-manager/` | Document control, 21 CFR Part 11 | -| QMS Audit Expert | `qms-audit-expert/` | ISO 13485 internal audits | -| ISMS Audit Expert | `isms-audit-expert/` | ISO 27001 security audits | -| Information Security Manager | `information-security-manager-iso27001/` | ISMS implementation | -| MDR 745 Specialist | `mdr-745-specialist/` | EU MDR classification, CE marking | -| FDA Consultant | `fda-consultant-specialist/` | 510(k), PMA, QSR compliance | -| GDPR/DSGVO Expert | `gdpr-dsgvo-expert/` | Privacy compliance, DPIA | - -## Python Tools - -17 scripts, all stdlib-only: +## Quick start ```bash -python3 risk-management-specialist/scripts/risk_matrix_calculator.py --help -python3 gdpr-dsgvo-expert/scripts/gdpr_compliance_checker.py --help +# Example: route a risk-analysis request +cat ra-qm-team/skills/risk-management-specialist/SKILL.md +python3 ra-qm-team/skills/risk-management-specialist/scripts/risk_matrix_calculator.py --help ``` ## Rules -- Load only the specific skill SKILL.md you need -- Always verify compliance outputs against current regulations +- Route to exactly one skill, then follow that skill's workflow. This router ships no tools of its own. +- All outputs are decision support: final compliance determinations route to the named human owner (QMR, DPO, regulatory counsel) — never auto-decide. +- Verify regulatory citations against the current text (e.g., FDA QMSR effective 2026-02-02 replaced the legacy QSR subsections). diff --git a/ra-qm-team/skills/risk-management-specialist/SKILL.md b/ra-qm-team/skills/risk-management-specialist/SKILL.md index 4e78b9b4..4c123f2b 100644 --- a/ra-qm-team/skills/risk-management-specialist/SKILL.md +++ b/ra-qm-team/skills/risk-management-specialist/SKILL.md @@ -75,11 +75,13 @@ Establish risk management process per ISO 14971. | Level | Acceptable | Action Required | |-------|------------|-----------------| -| Low | Yes | Document and accept | -| Medium | ALARP | Reduce if practicable; document rationale | -| High | ALARP | Reduction required; demonstrate ALARP | +| Low | Yes | Document and accept; still reduce as far as possible (EU MDR) | +| Medium | After reduction AFAP | Reduce as far as possible; document why further reduction is impossible | +| High | After reduction AFAP | Reduction required; demonstrate all further options exhausted | | Unacceptable | No | Design change mandatory | +> **EU MDR — AFAP, not ALARP:** For CE-marked devices, risks must be reduced **as far as possible (AFAP)** without economic considerations (MDR Annex I, GSPR 1–4; EN ISO 14971:2019/A11:2021 Z-annexes deviation). ALARP ("as low as reasonably practicable"), which permits cost-benefit weighing in acceptability decisions, is **not an acceptable criterion under the EU MDR** — a notified body will flag it. ISO 14971:2019 itself removed ALARP from the normative text. ALARP may persist in some non-EU jurisdictions (e.g., the UK HSE tradition); if used outside the EU, flag the deviation from EU requirements explicitly. + --- ## Risk Analysis Workflow @@ -170,8 +172,8 @@ Evaluate risks against acceptability criteria. 1. Calculate initial risk level from probability × severity 2. Compare to risk acceptability criteria 3. For each risk, determine: - - Acceptable: Document and accept - - ALARP: Proceed to risk control + - Acceptable: Document and accept (EU MDR: still reduce as far as possible) + - Reduction required (AFAP): Proceed to risk control - Unacceptable: Mandatory risk control 4. Document evaluation rationale 5. Identify risks requiring benefit-risk analysis @@ -189,16 +191,16 @@ Apply Acceptability Criteria │ ├── Low Risk ──────────► Accept and document │ - ├── Medium Risk ───────► Consider risk reduction - │ │ Document ALARP if not reduced + ├── Medium Risk ───────► Reduce as far as possible (AFAP) + │ │ Document why further reduction impossible │ ▼ - │ Practicable to reduce? + │ Further reduction possible? │ │ │ Yes──► Implement control - │ No───► Document ALARP rationale + │ No───► Document AFAP rationale (no economic considerations) │ ├── High Risk ─────────► Risk reduction required - │ │ Must demonstrate ALARP + │ │ Must demonstrate reduction AFAP │ ▼ │ Implement control │ Verify residual risk @@ -207,15 +209,17 @@ Apply Acceptability Criteria Cannot proceed without control ``` -### ALARP Demonstration Requirements +### AFAP Demonstration Requirements (EU MDR) | Criterion | Evidence Required | |-----------|-------------------| -| Technical feasibility | Analysis of alternative controls | -| Proportionality | Cost-benefit of further reduction | -| State of the art | Comparison to similar devices | +| All control options considered | Analysis of every feasible control per the hierarchy (design, protective measures, information) | +| Further reduction impossible | Evidence each remaining option is technically infeasible or does not further reduce risk | +| State of the art | Comparison to similar devices and current standards | | Stakeholder input | Clinical/user perspectives | +> Economic considerations (cost of further risk reduction) **must not** enter the EU acceptability decision (MDR Annex I GSPR 2; EN ISO 14971:2019/A11:2021). Cost may inform business decisions about whether to market the device — never whether a risk is acceptable. + ### Benefit-Risk Analysis Triggers | Situation | Benefit-Risk Required | @@ -297,7 +301,7 @@ VERIFICATION: | After Control | Action | |---------------|--------| | Acceptable | Document, proceed | -| ALARP achieved | Document rationale, proceed | +| Reduced AFAP | Document rationale (no economic considerations), proceed | | Still unacceptable | Additional control or design change | | New hazard introduced | Analyze and control new hazard | @@ -400,8 +404,8 @@ What is the risk level? | Condition | Decision | |-----------|----------| | All risks Low | Acceptable | -| Medium risks with ALARP | Acceptable | -| High risks with ALARP documented | Acceptable if benefits outweigh | +| Medium risks reduced AFAP | Acceptable | +| High risks reduced AFAP, documented | Acceptable if benefits outweigh | | Any Unacceptable residual | Not acceptable - redesign | --- @@ -434,7 +438,7 @@ What is the risk level? |-------|----------------|--------| | Planning | Define scope, criteria, responsibilities | Risk Management Plan | | Analysis | Identify hazards, estimate risk | Hazard Analysis | -| Evaluation | Compare to criteria, ALARP assessment | Risk Evaluation | +| Evaluation | Compare to criteria, AFAP assessment (EU) | Risk Evaluation | | Control | Implement hierarchy, verify | Risk Control Records | | Residual | Overall assessment, benefit-risk | Risk Management Report | | Production | Monitor, review, update | Updated RM File | diff --git a/ra-qm-team/skills/risk-management-specialist/references/iso14971-implementation-guide.md b/ra-qm-team/skills/risk-management-specialist/references/iso14971-implementation-guide.md index c8011766..ff574bde 100644 --- a/ra-qm-team/skills/risk-management-specialist/references/iso14971-implementation-guide.md +++ b/ra-qm-team/skills/risk-management-specialist/references/iso14971-implementation-guide.md @@ -55,7 +55,7 @@ Effective Date: [Date] 3. RISK ACCEPTABILITY CRITERIA 3.1 Risk Matrix: [Reference to matrix] - 3.2 Acceptability Policy: [Acceptable/ALARP/Unacceptable definitions] + 3.2 Acceptability Policy: [Acceptable/Reduction-required (AFAP for EU)/Unacceptable definitions] 3.3 Benefit-Risk Considerations: [When applicable] 4. VERIFICATION ACTIVITIES @@ -78,10 +78,12 @@ Effective Date: [Date] | Risk Level | Definition | Action Required | |------------|------------|-----------------| -| Broadly Acceptable | Risk so low that no action needed | Document and monitor | -| ALARP (Tolerable) | Risk reduced as low as reasonably practicable | Verify ALARP, consider benefit | +| Broadly Acceptable | Risk so low that no action needed | Document and monitor (EU MDR: still reduce as far as possible) | +| Tolerable after reduction AFAP | Risk reduced as far as possible | Verify all further reduction options exhausted; consider benefit | | Unacceptable | Risk exceeds acceptable threshold | Risk control mandatory | +> **EU MDR note:** For CE-marked devices the criterion is **as far as possible (AFAP)** without economic considerations (MDR Annex I GSPR 1–4; EN ISO 14971:2019/A11:2021 Z-annexes). ALARP — which weighs cost against benefit of further reduction — is not acceptable under the EU MDR; it may persist in some non-EU jurisdictions, where the deviation from EU requirements must be flagged explicitly. ISO 14971:2019 removed ALARP from its normative text. + ### Risk Matrix Example (5x5) | Probability \ Severity | Negligible | Minor | Serious | Critical | Catastrophic | @@ -93,9 +95,9 @@ Effective Date: [Date] | Improbable | Low | Low | Low | Medium | Medium | **Risk Level Actions:** -- **Low (Acceptable):** Document, no action required -- **Medium (ALARP):** Consider risk reduction, document rationale -- **High (ALARP):** Risk reduction required unless ALARP demonstrated +- **Low (Acceptable):** Document; EU MDR: still reduce as far as possible +- **Medium (reduce AFAP):** Reduce as far as possible, document why further reduction is impossible +- **High (reduce AFAP):** Risk reduction required; demonstrate all further options exhausted - **Unacceptable:** Risk reduction mandatory before proceeding --- @@ -181,8 +183,8 @@ Initial Risk = Risk before controls ### Evaluation Workflow 1. Apply risk acceptability criteria to estimated risk -2. Determine if risk is acceptable, ALARP, or unacceptable -3. For ALARP risks, document ALARP demonstration +2. Determine if risk is acceptable, requires further reduction (AFAP), or is unacceptable +3. For risks requiring reduction, document the AFAP demonstration 4. For unacceptable risks, proceed to risk control 5. Document evaluation rationale 6. **Validation:** All risks evaluated against criteria; rationale documented @@ -192,20 +194,22 @@ Initial Risk = Risk before controls | Initial Risk | Benefit Available | Decision | |--------------|-------------------|----------| | Acceptable | N/A | Accept, document | -| ALARP | No | Verify ALARP | -| ALARP | Yes | Include in benefit-risk | +| Reduced AFAP | No | Verify all reduction options exhausted | +| Reduced AFAP | Yes | Include in benefit-risk | | Unacceptable | No | Design change required | | Unacceptable | Yes | Benefit-risk analysis | -### ALARP Demonstration +### AFAP Demonstration (EU MDR) | Criterion | Evidence Required | |-----------|-------------------| -| Technical feasibility | Analysis of alternatives | -| Economic proportionality | Cost-benefit assessment | +| All control options considered | Analysis of every feasible alternative per the control hierarchy | +| Further reduction impossible | Evidence remaining options are technically infeasible or do not further reduce risk | | State of the art | Review of similar devices | | User acceptance | Stakeholder input | +> Economic considerations must not enter the acceptability decision for EU-market devices (MDR Annex I GSPR 2; EN ISO 14971:2019/A11:2021 Z-annexes). ALARP-style cost-benefit weighing of further risk reduction is prohibited in this context. + --- ## Risk Control @@ -321,7 +325,7 @@ RISKS: | Risk Category | Count | Highest Level | |---------------|-------|---------------| | Acceptable | [N] | Low | - | ALARP | [N] | Medium/High | + | Reduced AFAP | [N] | Medium/High | 2. Cumulative Considerations: [Assessment] @@ -365,7 +369,7 @@ Date: [Date] 1. EXECUTIVE SUMMARY - Total hazards identified: [N] - Risk controls implemented: [N] - - Residual risks: [N] acceptable, [N] ALARP + - Residual risks: [N] acceptable, [N] reduced AFAP - Overall conclusion: [Acceptable/Not Acceptable] 2. RISK ANALYSIS SUMMARY @@ -390,7 +394,7 @@ Date: [Date] 5. OVERALL RESIDUAL RISK - Individual residual risks: [Summary] - Cumulative assessment: [Conclusion] - - Acceptability: [Acceptable/ALARP demonstrated] + - Acceptability: [Acceptable/Reduced as far as possible (AFAP) demonstrated] 6. BENEFIT-RISK ANALYSIS (if applicable) - Conclusion: [Statement] diff --git a/ra-qm-team/skills/risk-management-specialist/references/risk-assessment-templates.md b/ra-qm-team/skills/risk-management-specialist/references/risk-assessment-templates.md index 21e95235..97202694 100644 --- a/ra-qm-team/skills/risk-management-specialist/references/risk-assessment-templates.md +++ b/ra-qm-team/skills/risk-management-specialist/references/risk-assessment-templates.md @@ -66,7 +66,7 @@ CONTROLS IMPLEMENTED: - Protective measures: [N] - Information for safety: [N] -OVERALL RESIDUAL RISK: [Acceptable / ALARP Demonstrated] +OVERALL RESIDUAL RISK: [Acceptable / Reduced as far as possible (AFAP) demonstrated] BENEFIT-RISK CONCLUSION: [If applicable] APPROVAL: diff --git a/ra-qm-team/skills/risk-management-specialist/scripts/risk_matrix_calculator.py b/ra-qm-team/skills/risk-management-specialist/scripts/risk_matrix_calculator.py index 958b55ba..f7f0a7dd 100644 --- a/ra-qm-team/skills/risk-management-specialist/scripts/risk_matrix_calculator.py +++ b/ra-qm-team/skills/risk-management-specialist/scripts/risk_matrix_calculator.py @@ -52,13 +52,13 @@ RISK_ACTIONS = { "color": "green" }, "Medium": { - "acceptable": "ALARP", - "action": "Reduce risk if practicable. Document ALARP rationale if not reduced.", + "acceptable": "AFAP", + "action": "Reduce as far as possible (AFAP). Document why further reduction is impossible. EU MDR: no economic considerations in acceptability (MDR Annex I GSPR 1-4; EN ISO 14971:2019/A11:2021).", "color": "yellow" }, "High": { - "acceptable": "ALARP", - "action": "Risk reduction required. Must demonstrate ALARP if residual risk remains high.", + "acceptable": "AFAP", + "action": "Risk reduction required. Must demonstrate reduction as far as possible (AFAP) if residual risk remains high. EU MDR: no economic considerations in acceptability.", "color": "orange" }, "Unacceptable": { @@ -205,7 +205,8 @@ def display_risk_matrix(): print() print("\n" + "-" * 70) - print("Risk Levels: Low (Acceptable) | Medium (ALARP) | High (ALARP) | Unacceptable") + print("Risk Levels: Low (Acceptable) | Medium (reduce AFAP) | High (reduce AFAP) | Unacceptable") + print("EU MDR: reduce as far as possible (AFAP), no economic considerations in acceptability.") print("=" * 70) @@ -231,7 +232,7 @@ def display_criteria(): print("RISK LEVEL ACTIONS") print("=" * 70) for level, info in RISK_ACTIONS.items(): - acceptable = "Yes" if info['acceptable'] == True else ("ALARP" if info['acceptable'] == "ALARP" else "No") + acceptable = "Yes" if info['acceptable'] == True else ("After reduction AFAP" if info['acceptable'] == "AFAP" else "No") print(f"\n{level}:") print(f" Acceptable: {acceptable}") print(f" Action: {info['action']}") diff --git a/research-ops/agents/cs-research-ops-orchestrator.md b/research-ops/agents/cs-research-ops-orchestrator.md index 3871eee5..8d6cf921 100644 --- a/research-ops/agents/cs-research-ops-orchestrator.md +++ b/research-ops/agents/cs-research-ops-orchestrator.md @@ -70,8 +70,8 @@ Hard outputs: ## Onboarding-first + autoresearch handoff -- **Onboarding-first.** When a user starts a fresh research workstream, point them at the relevant sub-skill's `scripts/onboard.py` before running its tools. Each skill has its own question set; answers persist to `~/.config/research-ops/<skill>.json` (or `./.research-ops/<skill>.json`) and pre-configure every tool. Treat customization as mandatory discipline — flag it when it's been skipped. -- **Autoresearch is opt-in and isolated.** Each sub-skill ships its own `scripts/ar_evaluator.py` bridging to `engineering/autoresearch-agent`. Invoke an autoresearch loop ONLY when the user explicitly asks to optimize / improve / run a loop. The connection is per-skill (no shared coupling): the loop edits the skill's input file; the evaluator is locked ground truth (never edited). Metrics: clinical `feasibility_composite` (↑), finance `runway_months` (↑), market `tam_divergence` (↓), product `validated_insights` (↑). +- **Onboarding-first.** When a user starts a fresh research workstream, point them at the relevant sub-skill's `skills/<sub-skill>/scripts/onboard.py` before running its tools. Each skill has its own question set; answers persist to `~/.config/research-ops/<skill>.json` (or `./.research-ops/<skill>.json`) and pre-configure every tool. Treat customization as mandatory discipline — flag it when it's been skipped. +- **Autoresearch is opt-in and isolated.** Each sub-skill ships its own `skills/<sub-skill>/scripts/ar_evaluator.py` bridging to `engineering/autoresearch-agent`. Invoke an autoresearch loop ONLY when the user explicitly asks to optimize / improve / run a loop. The connection is per-skill (no shared coupling): the loop edits the skill's input file; the evaluator is locked ground truth (never edited). Metrics: clinical `feasibility_composite` (↑), finance `runway_months` (↑), market `tam_divergence` (↓), product `validated_insights` (↑). ## When to escalate diff --git a/research-ops/commands/cs-clinical-research.md b/research-ops/commands/cs-clinical-research.md index c57436c7..146d3b1b 100644 --- a/research-ops/commands/cs-clinical-research.md +++ b/research-ops/commands/cs-clinical-research.md @@ -30,8 +30,8 @@ Run the `clinical-research` skill on this input: ## First run + optimization -- **Onboard first:** `python3 scripts/onboard.py` (area, alpha, power, dropout, named owners) — saved config pre-configures every tool. `--show` lists the questions. -- **Optimize (opt-in):** only if the user asks to optimize/run a loop, hand off to autoresearch via `scripts/ar_evaluator.py` (`feasibility_composite`, higher is better). +- **Onboard first:** `python3 skills/clinical-research/scripts/onboard.py` (area, alpha, power, dropout, named owners) — saved config pre-configures every tool. `--show` lists the questions. +- **Optimize (opt-in):** only if the user asks to optimize/run a loop, hand off to autoresearch via `skills/clinical-research/scripts/ar_evaluator.py` (`feasibility_composite`, higher is better). ## Distinct from diff --git a/research-ops/commands/cs-market-research.md b/research-ops/commands/cs-market-research.md index 43bab327..6c939565 100644 --- a/research-ops/commands/cs-market-research.md +++ b/research-ops/commands/cs-market-research.md @@ -30,8 +30,8 @@ Run the `market-research` skill on this input: ## First run + optimization -- **Onboard first:** `python3 scripts/onboard.py` (market profile, survey confidence, margin of error, sizing method) — saved config pre-configures every tool. `--show` lists the questions. -- **Optimize (opt-in):** only if the user asks to reconcile the sizing/run a loop, hand off to autoresearch via `scripts/ar_evaluator.py` (`tam_divergence`, lower is better). +- **Onboard first:** `python3 skills/market-research/scripts/onboard.py` (market profile, survey confidence, margin of error, sizing method) — saved config pre-configures every tool. `--show` lists the questions. +- **Optimize (opt-in):** only if the user asks to reconcile the sizing/run a loop, hand off to autoresearch via `skills/market-research/scripts/ar_evaluator.py` (`tam_divergence`, lower is better). ## Distinct from diff --git a/research-ops/commands/cs-product-research.md b/research-ops/commands/cs-product-research.md index c6d213ac..96e3e143 100644 --- a/research-ops/commands/cs-product-research.md +++ b/research-ops/commands/cs-product-research.md @@ -30,8 +30,8 @@ Run the `product-research` skill on this input: ## First run + optimization -- **Onboard first:** `python3 scripts/onboard.py` (product profile, insight source-threshold, saturation method, high-stakes flag) — saved config pre-configures every tool. `--show` lists the questions. -- **Optimize (opt-in):** only if the user asks to optimize the synthesis/run a loop, hand off to autoresearch via `scripts/ar_evaluator.py` (`validated_insights`, higher is better). +- **Onboard first:** `python3 skills/product-research/scripts/onboard.py` (product profile, insight source-threshold, saturation method, high-stakes flag) — saved config pre-configures every tool. `--show` lists the questions. +- **Optimize (opt-in):** only if the user asks to optimize the synthesis/run a loop, hand off to autoresearch via `skills/product-research/scripts/ar_evaluator.py` (`validated_insights`, higher is better). ## Distinct from diff --git a/research-ops/commands/cs-research-finance.md b/research-ops/commands/cs-research-finance.md index 23aeff3d..5eb81881 100644 --- a/research-ops/commands/cs-research-finance.md +++ b/research-ops/commands/cs-research-finance.md @@ -30,8 +30,8 @@ Run the `research-finance` skill on this input: ## First run + optimization -- **Onboard first:** `python3 scripts/onboard.py` (R&D area, F&A rate, runway threshold, accounting standard, finance owner) — saved config pre-configures every tool. `--show` lists the questions. -- **Optimize (opt-in):** only if the user asks to optimize/extend runway, hand off to autoresearch via `scripts/ar_evaluator.py` (`runway_months`, higher is better). +- **Onboard first:** `python3 skills/research-finance/scripts/onboard.py` (R&D area, F&A rate, runway threshold, accounting standard, finance owner) — saved config pre-configures every tool. `--show` lists the questions. +- **Optimize (opt-in):** only if the user asks to optimize/extend runway, hand off to autoresearch via `skills/research-finance/scripts/ar_evaluator.py` (`runway_months`, higher is better). ## Distinct from diff --git a/research-ops/skills/research-ops-skills/SKILL.md b/research-ops/skills/research-ops-skills/SKILL.md index ead536cf..20d979c8 100644 --- a/research-ops/skills/research-ops-skills/SKILL.md +++ b/research-ops/skills/research-ops-skills/SKILL.md @@ -107,7 +107,7 @@ Each sub-skill has its **own** question set (clinical: area/alpha/power/dropout/ ## Autoresearch handoff (isolated, opt-in) -Each sub-skill ships its own `scripts/ar_evaluator.py` — an **isolated** bridge to `engineering/autoresearch-agent`. Invoke autoresearch **only when the user explicitly asks** to "optimize", "improve", or "run a loop". The handoff is per-skill (no shared coupling): the loop edits the skill's input file and the evaluator scores it (clinical → `feasibility_composite` higher; finance → `runway_months` higher; market → `tam_divergence` lower; product → `validated_insights` higher). Never auto-start a loop; never let the loop edit the evaluator. +Each sub-skill ships its own `skills/<sub-skill>/scripts/ar_evaluator.py` — an **isolated** bridge to `engineering/autoresearch-agent`. Invoke autoresearch **only when the user explicitly asks** to "optimize", "improve", or "run a loop". The handoff is per-skill (no shared coupling): the loop edits the skill's input file and the evaluator scores it (clinical → `feasibility_composite` higher; finance → `runway_months` higher; market → `tam_divergence` lower; product → `validated_insights` higher). Never auto-start a loop; never let the loop edit the evaluator. ## Assumptions diff --git a/research/dossier/agents/cs-dossier.md b/research/dossier/agents/cs-dossier.md index d03c0458..270dd092 100644 --- a/research/dossier/agents/cs-dossier.md +++ b/research/dossier/agents/cs-dossier.md @@ -44,7 +44,7 @@ The cs-dossier agent orchestrates the `dossier` skill across hypothesis-tested e **Hard rules:** 1. **Q4 (hypothesis) is mandatory.** Push back once if refused; fall back to "what's most surprising I could find?" implicit hypothesis with flag. -2. **≥30% disconfirming search budget.** Enforced via `scripts/disconfirming_evidence_balance.py`. +2. **≥30% disconfirming search budget.** Enforced via `skills/dossier/scripts/disconfirming_evidence_balance.py`. 3. **Subject disambiguation before Phase 3.** Refuse to proceed on ambiguous names. 4. **Source-reliability tier on every flag.** Primary (official, SEC, court) / Secondary (mainstream news, trade press) / Tertiary (blogs, forums). 5. **BYOK MCP usage flagged in audit log.** Transparency on data provenance. @@ -58,15 +58,15 @@ The cs-dossier agent orchestrates the `dossier` skill across hypothesis-tested e ### Python Tools (Stdlib) -1. **Citation Tracker** — `scripts/citation_tracker.py` — three-count audit + supporting/disconfirming classification + source-tier tagging at `~/.dossier_sessions/<session>.json` -2. **Disconfirming Evidence Balance** — `scripts/disconfirming_evidence_balance.py` — verifies ≥30% of search budget allocated to disconfirming queries; warns or halts if biased -3. **Source Tier Classifier** — `scripts/source_tier_classifier.py` — given a URL, classify primary / secondary / tertiary by domain heuristics +1. **Citation Tracker** — `skills/dossier/scripts/citation_tracker.py` — three-count audit + supporting/disconfirming classification + source-tier tagging at `~/.dossier_sessions/<session>.json` +2. **Disconfirming Evidence Balance** — `skills/dossier/scripts/disconfirming_evidence_balance.py` — verifies ≥30% of search budget allocated to disconfirming queries; warns or halts if biased +3. **Source Tier Classifier** — `skills/dossier/scripts/source_tier_classifier.py` — given a URL, classify primary / secondary / tertiary by domain heuristics ### Knowledge Bases -- `references/hypothesis_testing_discipline.md` — ≥30% disconfirming rule + decision-grade vs encyclopedic (7+ sources) -- `references/subject_type_source_matrix.md` — person/company/nonprofit/gov source matrices (7+ sources) -- `references/conversation_hook_quality.md` — finding-tied hook discipline + anti-patterns (7+ sources) +- `skills/dossier/references/hypothesis_testing_discipline.md` — ≥30% disconfirming rule + decision-grade vs encyclopedic (7+ sources) +- `skills/dossier/references/subject_type_source_matrix.md` — person/company/nonprofit/gov source matrices (7+ sources) +- `skills/dossier/references/conversation_hook_quality.md` — finding-tied hook discipline + anti-patterns (7+ sources) ## Related Agents diff --git a/research/dossier/commands/cs-dossier.md b/research/dossier/commands/cs-dossier.md index cb69084e..d25cfc21 100644 --- a/research/dossier/commands/cs-dossier.md +++ b/research/dossier/commands/cs-dossier.md @@ -73,7 +73,7 @@ Example for hypothesis "Microsoft is consolidating AI spend on Foundry": | **Disconfirming** | "Microsoft AI vendor diversification" | | **Disconfirming** | "Microsoft third-party model partnerships 2026" | -`scripts/disconfirming_evidence_balance.py` enforces the ratio. Halts at <30% and prompts more disconfirming queries. +`skills/dossier/scripts/disconfirming_evidence_balance.py` enforces the ratio. Halts at <30% and prompts more disconfirming queries. ## Source Reliability Tiering @@ -85,7 +85,7 @@ Every fact in the DOCX tagged with tier (primary / secondary / tertiary): | **Secondary** | Mainstream news (NYT, WSJ, Reuters), trade press (TechCrunch, The Information) | | **Tertiary** | Blogs, forums (Reddit, HN), Glassdoor, social media | -`scripts/source_tier_classifier.py` does this from URL. +`skills/dossier/scripts/source_tier_classifier.py` does this from URL. ## Discipline (Research-Pack Convention) diff --git a/research/dossier/skills/dossier/SKILL.md b/research/dossier/skills/dossier/SKILL.md index 592c1857..a5d5f6bb 100644 --- a/research/dossier/skills/dossier/SKILL.md +++ b/research/dossier/skills/dossier/SKILL.md @@ -1,6 +1,6 @@ --- name: dossier -description: "Decision-grade entity research skill — 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 signals, reputation signals, red flags, 3-5 conversation hooks tied to specific findings, and source-provenance audit log. Uses WebSearch + WebFetch + free APIs (SEC EDGAR, GitHub, ProPublica Nonprofit Explorer) as workhorses; optional BYOK MCPs (LinkedIn, Crunchbase, Apollo, Pitchbook, SimilarWeb) enhance coverage. Triggers: 'research [company]', 'dossier on [person/company]', 'background check on [entity]', 'prep me for a meeting with [person/company]', 'due diligence on [company]', 'what should I know about [entity]', 'research [person] before I [meet/hire/invest]', 'competitor research on [company]', 'investor diligence [company]', 'interview prep for [company]'. Honors sensitivity exclusions for journalism + personal-vetting contexts." +description: "Decision-grade entity research skill — 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 + free APIs (SEC EDGAR, GitHub, ProPublica) as workhorses; optional BYOK MCPs enhance coverage. Use when the user asks for background research, diligence, or meeting prep on a specific entity (e.g., 'prep me for a meeting with [person/company]', 'due diligence on [company]'). Honors sensitivity exclusions for journalism + personal-vetting contexts." license: MIT metadata: source_spec: "megaprompts/12-dossier-megaprompt.md" @@ -267,7 +267,7 @@ new ExternalHyperlink({ - Save: `<output-dir>/dossier_<entity-slug>_<YYYY-MM-DD>.docx` - Chat summary: file path + **verdict on hypothesis** + audit counts + tier breakdown + BYOK MCPs used (if any) -- Validate: `python scripts/office/validate.py <docx>` +- Validate: check zip integrity with `python3 -c "import zipfile,sys; zipfile.ZipFile(sys.argv[1]).testzip()" <docx>` (no output = intact), then confirm the required sections are present ## Tooling diff --git a/research/grants/agents/cs-grants.md b/research/grants/agents/cs-grants.md index 8662d79f..f6476005 100644 --- a/research/grants/agents/cs-grants.md +++ b/research/grants/agents/cs-grants.md @@ -53,15 +53,15 @@ The cs-grants agent orchestrates the `grants` skill: ### Python Tools (Stdlib) -1. **Citation Tracker** — `scripts/citation_tracker.py` — three-count audit (Consensus + RePORTER counts) at `~/.grants_sessions/<session>.json` -2. **Fiscal Year Calculator** — `scripts/fiscal_year_calculator.py` — computes current FY + 3-prior window for RePORTER queries -3. **Mechanism Matcher** — `scripts/mechanism_matcher.py` — career stage × scope × prelim → mechanism recommendation +1. **Citation Tracker** — `skills/grants/scripts/citation_tracker.py` — three-count audit (Consensus + RePORTER counts) at `~/.grants_sessions/<session>.json` +2. **Fiscal Year Calculator** — `skills/grants/scripts/fiscal_year_calculator.py` — computes current FY + 3-prior window for RePORTER queries +3. **Mechanism Matcher** — `skills/grants/scripts/mechanism_matcher.py` — career stage × scope × prelim → mechanism recommendation ### Knowledge Bases -- `references/nih_mechanism_matching.md` — career stage × scope × prelim → mechanism canon (7+ sources) -- `references/reporter_post_patterns.md` — RePORTER curl POST templates + plan-tier detection (7+ sources) -- `references/docx_9_sections.md` — 9-section .docx spec + DOCX technical requirements (7+ sources) +- `skills/grants/references/nih_mechanism_matching.md` — career stage × scope × prelim → mechanism canon (7+ sources) +- `skills/grants/references/reporter_post_patterns.md` — RePORTER curl POST templates + plan-tier detection (7+ sources) +- `skills/grants/references/docx_9_sections.md` — 9-section .docx spec + DOCX technical requirements (7+ sources) ## Related Agents diff --git a/research/grants/skills/grants/SKILL.md b/research/grants/skills/grants/SKILL.md index a2237751..ee88f167 100644 --- a/research/grants/skills/grants/SKILL.md +++ b/research/grants/skills/grants/SKILL.md @@ -1,6 +1,6 @@ --- name: 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 recommendation. Triggers: 'grants for [topic]', 'find grants for my research idea', 'what grants match my research', 'help me find NIH funding', 'grant opportunities for my research', or any grant-related request. NIH-only scope — non-NIH funders (PCORI, DOD CDMRP, VA, foundations) are out of scope and flagged at intake." +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 recommendation. Use when the user asks about research funding or makes any grant-related request (e.g., 'grants for [topic]', 'find grants for my research idea', 'what grants match my research', 'help me find NIH funding', 'grant opportunities for my research'). NIH-only scope — non-NIH funders (PCORI, DOD CDMRP, VA, foundations) are out of scope and flagged at intake." license: MIT metadata: source_spec: "megaprompts/08-grants-megaprompt.md" @@ -118,7 +118,7 @@ RePORTER is **POST-only**. Use `bash_tool` + `curl` — never `web_fetch`. Compute at runtime via `scripts/fiscal_year_calculator.py`. Default: current FY + 3 prior. Federal FY starts Oct 1, so: ```bash -python ../scripts/fiscal_year_calculator.py --output json +python scripts/fiscal_year_calculator.py --output json # Returns: {"current_fy": 2026, "window": [2023, 2024, 2025, 2026]} ``` @@ -185,7 +185,7 @@ NOT career stage alone. Career stage **+** project scope **+** prelim data drive Use `scripts/mechanism_matcher.py`: ```bash -python ../scripts/mechanism_matcher.py \ +python scripts/mechanism_matcher.py \ --career-stage "early_career" \ --prelim-data "pilot" \ --environment "r01_eligible" \ @@ -238,7 +238,7 @@ This is the single most valuable advice for any applicant. Never skip. - Save DOCX to `<output-dir>/grants_<topic-slug>_<YYYY-MM-DD>.docx` - Chat summary: file path + audit counts + plan tier + verdict on institute targets -- Validate: `python scripts/office/validate.py <docx>` +- Validate: check zip integrity with `python3 -c "import zipfile,sys; zipfile.ZipFile(sys.argv[1]).testzip()" <docx>` (no output = intact), then confirm the required sections are present ## Tooling diff --git a/research/grants/skills/grants/references/docx_9_sections.md b/research/grants/skills/grants/references/docx_9_sections.md index b2f96c28..ec70a3ce 100644 --- a/research/grants/skills/grants/references/docx_9_sections.md +++ b/research/grants/skills/grants/references/docx_9_sections.md @@ -267,7 +267,7 @@ new Table({ After save: ```bash -python scripts/office/validate.py output.docx +python3 -c "import zipfile,sys; zipfile.ZipFile(sys.argv[1]).testzip()" output.docx ``` If validation fails: unpack DOCX (it's a ZIP), inspect document.xml, fix the offending XML, repack. diff --git a/research/litreview/README.md b/research/litreview/README.md index 1b9b4b85..9a0a65b7 100644 --- a/research/litreview/README.md +++ b/research/litreview/README.md @@ -55,7 +55,7 @@ research/litreview/ - **Consensus MCP** (required) — literature search - **`docx` Node.js library** (required) — `npm install docx` - **DOCX skill** (reference) — hyperlink / table / list / validation patterns -- **DOCX validation script** — `python scripts/office/validate.py output.docx` +- **DOCX validation step** — zip-integrity check: `python3 -c "import zipfile,sys; zipfile.ZipFile(sys.argv[1]).testzip()" output.docx` (no output = intact), then confirm required sections present ## Quick start diff --git a/research/litreview/agents/cs-litreview.md b/research/litreview/agents/cs-litreview.md index 908b81b1..eda7a01d 100644 --- a/research/litreview/agents/cs-litreview.md +++ b/research/litreview/agents/cs-litreview.md @@ -35,7 +35,7 @@ The cs-litreview agent orchestrates the `litreview` skill across academic-resear 3. **Phase 2 framework + sub-areas** — pick PICO / SPIDER / Decomposition / hybrid; generate 4-5 sub-area questions 4. **Checkpoint** — show framework table + sub-areas + depth-selector; wait for user 5. **Phase 3 searches** — sequential, 1 q/sec, budget per depth tier (5/10/20) -6. **Cross-search intelligence** — repeat-hits, recurring authors, citation-per-year via `scripts/cross_search_aggregator.py` +6. **Cross-search intelligence** — repeat-hits, recurring authors, citation-per-year via `skills/litreview/scripts/cross_search_aggregator.py` 7. **Phase 4 DOCX** — 8-section guide via Node.js + `docx` library Differentiates from siblings: @@ -52,7 +52,7 @@ Differentiates from siblings: 4. **Plan-tier detect at first search.** Report at checkpoint so user can recalibrate depth. 5. **Halt at checkpoint.** Refuse to start Phase 3 without explicit user choice. 6. **Source discipline.** Cite only Consensus-returned papers from THIS session. Training knowledge labeled `[Not from Consensus]`. -7. **Three-count tracking.** Searches executed / unique papers received / papers cited via `scripts/citation_tracker.py`. +7. **Three-count tracking.** Searches executed / unique papers received / papers cited via `skills/litreview/scripts/citation_tracker.py`. 8. **Retry once after 3s.** Then log. 3 consecutive failures → stop. ## Skill Integration @@ -102,7 +102,7 @@ python ../skills/litreview/scripts/framework_recommender.py --question "<from Q1 # Phase 4: cross-search aggregation + DOCX python ../skills/litreview/scripts/cross_search_aggregator.py --session NAME # Generate DOCX via Node.js + docx library -python scripts/office/validate.py output.docx # from docx skill +python3 -c "import zipfile,sys; zipfile.ZipFile(sys.argv[1]).testzip()" output.docx # zip-integrity check (no output = intact); then confirm required sections present python ../skills/litreview/scripts/citation_tracker.py --action close --session NAME ``` diff --git a/research/litreview/commands/cs-litreview.md b/research/litreview/commands/cs-litreview.md index 9ff20c0f..22b061a8 100644 --- a/research/litreview/commands/cs-litreview.md +++ b/research/litreview/commands/cs-litreview.md @@ -100,7 +100,7 @@ python ../skills/litreview/scripts/framework_recommender.py --question "<Q1>" # Phase 4 cross-search aggregation + DOCX python ../skills/litreview/scripts/cross_search_aggregator.py --session NAME # Generate DOCX via Node.js docx library -python scripts/office/validate.py output.docx +python3 -c "import zipfile,sys; zipfile.ZipFile(sys.argv[1]).testzip()" output.docx # zip-integrity check; then confirm required sections present python ../skills/litreview/scripts/citation_tracker.py --action close --session NAME ``` diff --git a/research/litreview/skills/litreview/SKILL.md b/research/litreview/skills/litreview/SKILL.md index 59e2e9eb..9137a55e 100644 --- a/research/litreview/skills/litreview/SKILL.md +++ b/research/litreview/skills/litreview/SKILL.md @@ -1,6 +1,6 @@ --- name: litreview -description: "Academic literature orientation skill that searches papers via Consensus, builds a strategic search plan using PICO (default) or SPIDER / Decomposition / hybrid as fallbacks, and synthesizes findings into a professionally formatted Word document (.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. Configurable depth (5/10/20 queries) controls coverage vs. speed. Output is a 'launching pad' — not a finished review, but an orientation guide that lets a researcher dive in confidently. Triggers: 'litreview on [topic]', 'literature review on [topic]', 'I'm starting a literature review on X', 'I'm writing a paper on X', 'help me research X', 'I'm doing research on X', 'can you help me research X'. Do NOT trigger for single one-off paper searches where the user just wants a quick list — that's a plain Consensus search." +description: "Academic literature orientation skill that searches papers via Consensus, 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. Configurable depth (5/10/20 queries) controls coverage vs. speed. Output is a 'launching pad' — an orientation guide that lets a researcher dive in confidently, not a finished review. Use when the user starts literature-oriented research (e.g., 'litreview on [topic]', 'literature review on [topic]', 'I'm starting a literature review on X', 'I'm writing a paper on X', 'help me research X', 'I'm doing research on X', 'can you help me research X'). Do NOT use for single one-off paper searches wanting a quick list — that's a plain Consensus search." license: MIT metadata: source_spec: "megaprompts/09-litreview-megaprompt.md" @@ -204,7 +204,7 @@ Document the key `docx` library patterns: - Lists: `LevelFormat.BULLET` (never unicode bullets) - Hyperlinks: `ExternalHyperlink` with `style: "Hyperlink"`, full URL (never truncated) - Tables: dual widths (`columnWidths` + cell `width`), `ShadingType.CLEAR` -- Validation step after save (`python scripts/office/validate.py output.docx`) +- Validation step after save (zip-integrity check: `python3 -c "import zipfile,sys; zipfile.ZipFile(sys.argv[1]).testzip()" output.docx` — no output = intact — then confirm the required sections are present) Reference the **docx skill** for setup patterns and best practices. diff --git a/research/litreview/skills/litreview/references/docx_8_sections.md b/research/litreview/skills/litreview/references/docx_8_sections.md index d64a215f..a689800b 100644 --- a/research/litreview/skills/litreview/references/docx_8_sections.md +++ b/research/litreview/skills/litreview/references/docx_8_sections.md @@ -236,7 +236,7 @@ new Table({ After save: ```bash -python scripts/office/validate.py output.docx +python3 -c "import zipfile,sys; zipfile.ZipFile(sys.argv[1]).testzip()" output.docx ``` If validation fails: unpack DOCX (it's a ZIP), fix the offending XML, repack. @@ -268,7 +268,7 @@ Reference the **docx skill** (`docx/SKILL.md` in this repo if installed) for ful - [ ] All Consensus URLs full (no truncation) - [ ] `LevelFormat.BULLET` for lists (no unicode bullets) - [ ] Tables have both `columnWidths` AND cell `width` -- [ ] `python scripts/office/validate.py output.docx` PASSes +- [ ] `python3 -c "import zipfile,sys; zipfile.ZipFile(sys.argv[1]).testzip()" output.docx` PASSes ## Citations (7 sources) diff --git a/research/notebooklm/.claude-plugin/plugin.json b/research/notebooklm/.claude-plugin/plugin.json index da1b9ed8..61316339 100644 --- a/research/notebooklm/.claude-plugin/plugin.json +++ b/research/notebooklm/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "notebooklm", - "description": "Browser automation skill for controlling Google's NotebookLM. Handles reading and querying notebooks, adding sources (URLs, text, files, YouTube links, synthesized content), generating Studio outputs (Audio Overview, infographics, slide decks, study guides, briefing docs, mind maps, timelines, FAQs), and creating new notebooks. Triggers on any phrase involving NotebookLM \u2014 'open NotebookLM', 'check my [name] notebook', 'pull info from NotebookLM', 'ask my notebook about X', 'add [source] to NotebookLM', 'create an infographic in NotebookLM', 'use NotebookLM Studio', 'generate a slide deck from my notebook', or any variation where the goal involves NotebookLM. Requires browser automation environment \u2014 fails gracefully when unavailable.", + "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 — discover the exact set from the live Studio panel; the UI evolves fast), and creating new notebooks. Requires browser automation environment — fails gracefully when unavailable.", "version": "2.9.0", "author": { "name": "Alireza Rezvani", @@ -14,7 +14,7 @@ ], "source": { "spec": "megaprompts/03-notebooklm-megaprompt.md", - "build_pattern": "Path B (direct conversion). Browser-automation shape \u2014 distinct from research-pack convention. Action-routing intake (Q1 picks one of 4 actions: read/extract, add source, generate studio output, create new). CLI-only portability with graceful failure in web context.", + "build_pattern": "Path B (direct conversion). Browser-automation shape — distinct from research-pack convention. Action-routing intake (Q1 picks one of 4 actions: read/extract, add source, generate studio output, create new). CLI-only portability with graceful failure in web context.", "sibling_of": "research/pulse, litreview, grants, dossier, patent, syllabus (semantic domain) but DIFFERENT SHAPE (browser-automation, not research-pack)" } -} +} \ No newline at end of file diff --git a/research/notebooklm/agents/cs-notebooklm.md b/research/notebooklm/agents/cs-notebooklm.md index 75f9b863..0b8542f1 100644 --- a/research/notebooklm/agents/cs-notebooklm.md +++ b/research/notebooklm/agents/cs-notebooklm.md @@ -61,15 +61,15 @@ The cs-notebooklm agent orchestrates the `notebooklm` skill across NotebookLM br ### Python Tools (Stdlib) -1. **Action Router** — `scripts/action_router.py` — Q1-Q4 answers → action plan + UI flow + required parameters -2. **Custom Prompt Template Generator** — `scripts/custom_prompt_template_generator.py` — Studio output type + audience → starter custom prompt -3. **Async Action Classifier** — `scripts/async_action_classifier.py` — action name → wait-or-notify pattern (which generations block and which return immediately) +1. **Action Router** — `skills/notebooklm/scripts/action_router.py` — Q1-Q4 answers → action plan + UI flow + required parameters +2. **Custom Prompt Template Generator** — `skills/notebooklm/scripts/custom_prompt_template_generator.py` — Studio output type + audience → starter custom prompt +3. **Async Action Classifier** — `skills/notebooklm/scripts/async_action_classifier.py` — action name → wait-or-notify pattern (which generations block and which return immediately) ### Knowledge Bases -- `references/browser_automation_canon.md` — screenshot-first + find-before-click + tool-agnostic patterns (7+ sources) -- `references/studio_output_custom_prompts.md` — why defaults are mediocre + per-output-type templates (7+ sources) -- `references/async_action_discipline.md` — fire-and-notify pattern for slow UI ops (7+ sources) +- `skills/notebooklm/references/browser_automation_canon.md` — screenshot-first + find-before-click + tool-agnostic patterns (7+ sources) +- `skills/notebooklm/references/studio_output_custom_prompts.md` — why defaults are mediocre + per-output-type templates (7+ sources) +- `skills/notebooklm/references/async_action_discipline.md` — fire-and-notify pattern for slow UI ops (7+ sources) ## Related Agents diff --git a/research/notebooklm/skills/notebooklm/SKILL.md b/research/notebooklm/skills/notebooklm/SKILL.md index dd099bd0..57a10d8d 100644 --- a/research/notebooklm/skills/notebooklm/SKILL.md +++ b/research/notebooklm/skills/notebooklm/SKILL.md @@ -1,6 +1,6 @@ --- name: notebooklm -description: "Browser automation skill for controlling Google's NotebookLM. Handles reading and querying notebooks, adding sources (URLs, text, files, YouTube links, synthesized content), generating Studio outputs (Audio Overview, infographics, slide decks, study guides, briefing docs, mind maps, timelines, FAQs), and creating new notebooks. Triggers on any phrase involving NotebookLM — 'open NotebookLM', 'check my [name] notebook', 'pull info from NotebookLM', 'ask my notebook about X', 'add [source] to NotebookLM', 'create an infographic in NotebookLM', 'use NotebookLM Studio', 'generate a slide deck from my notebook', or any variation where the goal involves NotebookLM. Requires browser automation environment — fails gracefully when unavailable." +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 — discover the exact set from the live Studio panel; the UI evolves fast), and creating new notebooks. Requires browser automation environment — fails gracefully when unavailable." license: MIT metadata: source_spec: "megaprompts/03-notebooklm-megaprompt.md" @@ -34,7 +34,7 @@ Up to 4 forcing questions, one at a time, dependency-ordered. Most invocations s > > 1. **Read / extract** — ask a question of an existing notebook > 2. **Add a source** — push content (URL, text, file, Google Doc, or synthesized content) into a notebook -> 3. **Generate a Studio output** — Audio Overview, Study Guide, Briefing Doc, Timeline, FAQ, Infographic, Slides, or Mind Map +> 3. **Generate a Studio output** — Audio/Video Overview, Mind Map, Report (Briefing Doc, Study Guide, FAQ, Timeline), Flashcards, Quiz, Infographic, or Slides — the exact set comes from the live Studio panel > 4. **Create a new notebook** — initialize with title + initial sources > > *Why I'm asking:* Each action takes a different path through the UI and requires different parameters. Naming the action upfront prevents wasted screenshots and lets me ask only the follow-up questions that apply. @@ -65,7 +65,7 @@ For action 4 (create new): replace with "What's the title for the new notebook?" > *Why I'm asking:* Each source type goes through a different sub-flow in the Add Source dialog. Picking upfront saves a step." **Action 3 (Studio output):** -> "Which Studio output? Audio Overview / Study Guide / Briefing Doc / Timeline / FAQ / Table of Contents / Infographic / Slides / Mind Map. And: any custom-prompt direction? **Default prompts produce mediocre output — I always open the customization menu and write a detailed prompt.** Tell me the angle or audience. +> "Which Studio output? As of 2026-06 the Studio panel offers Audio Overview, Video Overview, Mind Map, Reports (Briefing Doc / Study Guide / FAQ / Timeline / custom), Flashcards, Quiz, Infographic, and Slides — I'll screenshot the live panel and confirm what your account actually shows before clicking. And: any custom-prompt direction? **Default prompts produce mediocre output — I always open the customization menu and write a detailed prompt.** Tell me the angle or audience. > > *Why I'm asking:* The output type sets the UI button to find. The custom prompt is mandatory for quality." @@ -132,12 +132,12 @@ Sub-flows per source type: ## Action 3: Studio Outputs -**All 9 output types supported:** Audio Overview, Study Guide, Briefing Doc, Timeline, FAQ, Table of Contents, Infographic, Slides, Mind Map. +**Discover, don't assume.** NotebookLM's Studio inventory changes between rollouts and account tiers. As of the last verification (2026-06) the panel offers: **Audio Overview, Video Overview, Mind Map, Reports** (Briefing Doc, Study Guide, FAQ, Timeline, custom report formats), **Flashcards, Quiz, Infographic, Slides**. Treat this list as a hint, not ground truth — the screenshot of the live Studio panel is the authority. NotebookLM's UI evolves quickly; verify against the live product and update this section when it drifts (Studio inventory last verified 2026-06). **Mandatory workflow:** -1. Locate Studio panel (right side; may need toggle) -2. Find the specific output button for the requested type +1. Locate Studio panel (right side; may need toggle) and **screenshot it — the tiles you see are the real output types for this account** +2. Find the specific output button for the requested type (if it isn't visible, check "Discover more"/overflow before declaring it unavailable) 3. **Open customization menu** (chevron/arrow next to button) — **NOT the main button** 4. **Write detailed custom prompt** (from Q4) 5. Confirm and submit @@ -183,10 +183,18 @@ Use `scripts/async_action_classifier.py` to determine wait-or-notify per action: | Add Source (URL/text/file) | Yes — wait for ingestion spinner (~5-30s) | | Read/Extract (chat) | Yes — wait 3-5s for response | | Studio: Audio Overview | **No** — fire and notify (5-10 min) | +| Studio: Video Overview | **No** — fire and notify (5-15 min) | | Studio: Infographic / Slides / Mind Map | **No** — fire and notify (2-5 min) | -| Studio: Study Guide / Briefing Doc / FAQ | Yes — wait ~30-60s | +| Studio: Study Guide / Briefing Doc / FAQ / Flashcards / Quiz | Yes — wait ~30-60s | | Create New Notebook | Yes — wait for auto-summary (<30s) | +```bash +# Verdict + paste-ready notify message for any action +python3 scripts/async_action_classifier.py --action "video overview" +# -> Verdict: FIRE_AND_NOTIFY, estimated 5-15 minutes, with the exact +# "NOT waiting in this session" message to relay to the user +``` + See [`references/async_action_discipline.md`](references/async_action_discipline.md) for the canon. ## Screenshot-First Discipline diff --git a/research/notebooklm/skills/notebooklm/references/async_action_discipline.md b/research/notebooklm/skills/notebooklm/references/async_action_discipline.md index 0fc9be89..44d1024c 100644 --- a/research/notebooklm/skills/notebooklm/references/async_action_discipline.md +++ b/research/notebooklm/skills/notebooklm/references/async_action_discipline.md @@ -47,7 +47,8 @@ The user already knows how NotebookLM works — they'll see the notification whe | Studio: Study Guide | Generation | 30-60s | **Wait** (with 90s timeout) | | Studio: Briefing Doc | Generation | 30-60s | **Wait** (with 90s timeout) | | Studio: FAQ | Generation | 30-60s | **Wait** (with 90s timeout) | -| Studio: Table of Contents | Generation | 20-40s | **Wait** | +| Studio: Flashcards / Quiz | Generation | 30-60s | **Wait** | +| Studio: Video Overview | Generation | 5-15 min | **Fire-and-notify** | | Studio: Timeline | Generation | 30-60s | **Wait** (with 90s timeout) | | **Studio: Audio Overview** | Audio gen | **5-10 min** | **NOTIFY** (fire-and-notify) | | **Studio: Infographic** | Visual gen | **2-5 min** | **NOTIFY** | diff --git a/research/notebooklm/skills/notebooklm/references/studio_output_custom_prompts.md b/research/notebooklm/skills/notebooklm/references/studio_output_custom_prompts.md index bd1893e8..163d8f2d 100644 --- a/research/notebooklm/skills/notebooklm/references/studio_output_custom_prompts.md +++ b/research/notebooklm/skills/notebooklm/references/studio_output_custom_prompts.md @@ -4,17 +4,18 @@ This reference answers exactly one decision: **why does the notebooklm skill alw ## The Core Claim -NotebookLM's Studio generates 9 output types from your notebook's sources: +NotebookLM's Studio generates multiple output types from your notebook's sources. As of the last verification (2026-06): - Audio Overview (podcast-style) -- Study Guide -- Briefing Doc -- Timeline -- FAQ -- Table of Contents +- Video Overview (narrated visual explainer; customizable format and visual style) +- Mind Map +- Reports — Briefing Doc, Study Guide, FAQ, Timeline, and custom report formats +- Flashcards +- Quiz - Infographic - Slides (slide deck) -- Mind Map + +The UI evolves quickly — always discover the actual inventory from the live Studio panel screenshot rather than this list, and update this doc when it drifts. **The default prompts produce mediocre output.** They are written to work across all possible source materials → they are generic by design. Generic prompts produce generic output. @@ -150,7 +151,7 @@ A weak prompt has 1-2 of these. A strong prompt has 4-5. > "Central concept: [name]. 3-5 primary branches (the major dimensions). Each branch: 2-4 sub-branches. Max depth: 3 levels (central → branch → sub-branch). Use noun phrases for branches (not full sentences). Mark 2-3 sub-branches as 'critical' (the highest-leverage points). Skip details that don't connect back to a critical sub-branch." -### Table of Contents +### Table of Contents (legacy — folded into Reports in current UI) **Default fails because:** literal section dump, no annotation. diff --git a/research/notebooklm/skills/notebooklm/scripts/async_action_classifier.py b/research/notebooklm/skills/notebooklm/scripts/async_action_classifier.py index 9ce4056a..7903052c 100644 --- a/research/notebooklm/skills/notebooklm/scripts/async_action_classifier.py +++ b/research/notebooklm/skills/notebooklm/scripts/async_action_classifier.py @@ -114,7 +114,32 @@ ACTION_TIMING = { "timeout_seconds": 90, "polling_interval_seconds": 5, }, + "flashcards": { + "category": "studio", + "verdict": "WAIT", + "estimated_duration_seconds": (30, 60), + "timeout_seconds": 120, + "polling_interval_seconds": 10, + }, + "quiz": { + "category": "studio", + "verdict": "WAIT", + "estimated_duration_seconds": (30, 60), + "timeout_seconds": 120, + "polling_interval_seconds": 10, + }, # Studio outputs — slow (fire-and-notify) + "video_overview": { + "category": "studio", + "verdict": "FIRE_AND_NOTIFY", + "estimated_duration_seconds": (300, 900), + "estimated_duration_human": "5-15 minutes", + "notify_message": ( + "Video Overview generation triggered. Estimated 5-15 minutes. " + "NotebookLM will notify you in-app and via email when ready. " + "NOT waiting in this session — returning control to you now." + ), + }, "audio_overview": { "category": "studio", "verdict": "FIRE_AND_NOTIFY", diff --git a/research/patent/agents/cs-patent.md b/research/patent/agents/cs-patent.md index 13bbe42a..bbdb315c 100644 --- a/research/patent/agents/cs-patent.md +++ b/research/patent/agents/cs-patent.md @@ -28,10 +28,10 @@ tools: [Read, Write, Bash, WebFetch, WebSearch] The cs-patent agent orchestrates the `patent` skill across prior-art + landscape research: 1. **Phase 1 intake** — Q1-Q6 one at a time, with sub-use-case commitment at Q2 -2. **Phase 2 search strategy selection** — deterministic via `scripts/sub_use_case_router.py` +2. **Phase 2 search strategy selection** — deterministic via `skills/patent/scripts/sub_use_case_router.py` 3. **Phase 3 multi-source search** — Google Patents (workhorse) + Espacenet + USPTO + optional Lens.org 4. **Phase 4 claim extraction + relevance scoring** — pull independent claim 1 + key dependents -5. **Phase 5 citation graph + family resolution** — deduplicate via `scripts/family_resolver.py` +5. **Phase 5 citation graph + family resolution** — deduplicate via `skills/patent/scripts/family_resolver.py` 6. **Phase 6 DOCX** — 8 sections with sub-use-case-specific emphasis 7. **Phase 7 deliver** — file + chat summary with verdict @@ -53,15 +53,15 @@ The cs-patent agent orchestrates the `patent` skill across prior-art + landscape ### Python Tools (Stdlib) -1. **Citation Tracker** — `scripts/citation_tracker.py` — three-count audit across Google Patents + Espacenet + USPTO + Lens.org sources at `~/.patent_sessions/<session>.json` -2. **Family Resolver** — `scripts/family_resolver.py` — group same-invention filings (e.g., US + EP + JP + CN of one priority) by priority number / family ID -3. **Sub-Use-Case Router** — `scripts/sub_use_case_router.py` — deterministic search strategy from intake answers +1. **Citation Tracker** — `skills/patent/scripts/citation_tracker.py` — three-count audit across Google Patents + Espacenet + USPTO + Lens.org sources at `~/.patent_sessions/<session>.json` +2. **Family Resolver** — `skills/patent/scripts/family_resolver.py` — group same-invention filings (e.g., US + EP + JP + CN of one priority) by priority number / family ID +3. **Sub-Use-Case Router** — `skills/patent/scripts/sub_use_case_router.py` — deterministic search strategy from intake answers ### Knowledge Bases -- `references/sub_use_case_routing.md` — 5-sub-use-case canon + when each applies (7+ sources) -- `references/cpc_classification_canon.md` — CPC/IPC class follow-up rationale (7+ sources) -- `references/legal_disclaimer_discipline.md` — when + why disclaimer mandatory (7+ sources) +- `skills/patent/references/sub_use_case_routing.md` — 5-sub-use-case canon + when each applies (7+ sources) +- `skills/patent/references/cpc_classification_canon.md` — CPC/IPC class follow-up rationale (7+ sources) +- `skills/patent/references/legal_disclaimer_discipline.md` — when + why disclaimer mandatory (7+ sources) ## Related Agents diff --git a/research/patent/skills/patent/SKILL.md b/research/patent/skills/patent/SKILL.md index c03ecaaa..dcc7cb99 100644 --- a/research/patent/skills/patent/SKILL.md +++ b/research/patent/skills/patent/SKILL.md @@ -1,6 +1,6 @@ --- name: patent -description: "Patent prior-art and landscape intelligence skill — 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 log. Triggers: 'prior art search for [invention]', 'patent search on [topic]', 'freedom to operate analysis', 'FTO for [product]', 'patent landscape for [field]', 'is [invention] novel', 'patents on [topic]', 'competitive patent analysis', 'prior art for litigation', 'patent diligence on [company]'. Produces search signal, not legal advice — always recommends consulting a patent attorney before filing or licensing decisions. Trademark, copyright, and trade-secret questions are out of scope." +description: "Patent prior-art and landscape intelligence skill — 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 log. Use when the user asks for patent searching or analysis (e.g., 'prior art search for [invention]', 'freedom to operate analysis for [product]'). Produces search signal, not legal advice — always recommends consulting a patent attorney before filing or licensing decisions. Trademark, copyright, and trade-secret questions are out of scope." license: MIT metadata: source_spec: "megaprompts/11-patent-megaprompt.md" @@ -104,7 +104,7 @@ Asked for novelty and FTO; skipped for pure landscape (always signal-gathering b Deterministic from intake answers. Use `scripts/sub_use_case_router.py`: ```bash -python ../scripts/sub_use_case_router.py \ +python scripts/sub_use_case_router.py \ --sub-use-case novelty \ --jurisdictions "" \ --risk strict \ @@ -179,7 +179,7 @@ If no Lens.org key: skip; note in audit log; recommend manual citation review on Same invention often filed in multiple jurisdictions (US + EP + JP + CN). Group by family ID or priority number to avoid double-counting. Use `scripts/family_resolver.py`: ```bash -python ../scripts/family_resolver.py --hits-file hits.json +python scripts/family_resolver.py --hits-file hits.json # Returns: deduplicated family list + family-member jurisdictions ``` @@ -234,7 +234,7 @@ Surface the **legally-relevant date** per sub-use-case: - Save: `<output-dir>/patent_<invention-slug>_<sub-use-case>_<YYYY-MM-DD>.docx` - Chat summary: file path + sub-use-case + verdict + audit counts + plan-tier -- Validate: `python scripts/office/validate.py <docx>` +- Validate: check zip integrity with `python3 -c "import zipfile,sys; zipfile.ZipFile(sys.argv[1]).testzip()" <docx>` (no output = intact), then confirm the required sections are present - Reminder: "Consult patent attorney before filing/licensing" ## Tooling diff --git a/research/pulse/agents/cs-pulse.md b/research/pulse/agents/cs-pulse.md index eeef5ea8..0371acac 100644 --- a/research/pulse/agents/cs-pulse.md +++ b/research/pulse/agents/cs-pulse.md @@ -33,7 +33,7 @@ Relentless on specificity, depth-first on the intake tree, graceful on platform The cs-pulse agent orchestrates the `pulse` skill across multi-source recency briefings: 1. **Grill-me intake (Q1 → Q4, dependency-ordered)** — topic, angle, window, scope. One at a time. Refuse vague answers. -2. **Pre-flight** — compute window timestamps with `scripts/time_window_calculator.py`, generate output slug with `scripts/topic_slug_generator.py`, start three-count audit with `scripts/citation_tracker.py`. +2. **Pre-flight** — compute window timestamps with `skills/pulse/scripts/time_window_calculator.py`, generate output slug with `skills/pulse/scripts/topic_slug_generator.py`, start three-count audit with `skills/pulse/scripts/citation_tracker.py`. 3. **Phases 1–3 in parallel** — Reddit (top + new), HN (Algolia stories + comments), Web (2–3 targeted queries). 1 q/sec per platform; sequential within. 4. **Phase 4 (optional)** — X/Twitter if available; skip with note otherwise. 5. **Synthesis** — cross-platform pattern detection (consensus, controversy, pain, excitement, gaps). @@ -184,9 +184,9 @@ python ../skills/pulse/scripts/citation_tracker.py --action close --session NAME ## Related Agents -- [cs-grill-master](../../grill-me/agents/cs-grill-master.md) — plan-only grill (different domain) -- [cs-grill-with-docs](../../grill-with-docs/agents/cs-grill-with-docs.md) — docs-anchored grill (different scope) -- [cs-capture](../../capture/agents/cs-capture.md) — brain-dump organizer (different mode) +- [cs-grill-master](../../../engineering/grill-me/agents/cs-grill-master.md) — plan-only grill (different domain) +- [cs-grill-with-docs](../../../engineering/grill-with-docs/agents/cs-grill-with-docs.md) — docs-anchored grill (different scope) +- [cs-capture](../../../productivity/capture/agents/cs-capture.md) — brain-dump organizer (different mode) ## References diff --git a/research/pulse/skills/pulse/SKILL.md b/research/pulse/skills/pulse/SKILL.md index c79d48a1..31319172 100644 --- a/research/pulse/skills/pulse/SKILL.md +++ b/research/pulse/skills/pulse/SKILL.md @@ -1,6 +1,6 @@ --- name: 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. Triggers: 'pulse on [topic]', 'what's happening with [topic]', 'what are people saying about [topic]', 'current conversation about [topic]', 'take the pulse of [topic]', 'trending: [topic]', 'find me info on [topic]', or any variation requesting multi-source recency intelligence on a topic. Also use for competitor research, trend discovery, tool comparisons, and audience sentiment analysis." +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 saying about [topic]', 'current conversation about [topic]', 'take the pulse of [topic]', 'trending: [topic]', 'find me info on [topic]'), and for competitor research, trend discovery, tool comparisons, and audience sentiment analysis." license: MIT metadata: source_spec: "megaprompts/01-pulse-megaprompt.md" diff --git a/research/research/agents/cs-research.md b/research/research/agents/cs-research.md index 7adb26ae..b8171f06 100644 --- a/research/research/agents/cs-research.md +++ b/research/research/agents/cs-research.md @@ -37,14 +37,14 @@ Router-first, transparency-mandatory, fallback-when-needed. The cs-research agent orchestrates the `research` skill as the **runtime orchestrator** for the research domain: 1. **Q1 + Q2 minimal intake** — question + output preference -2. **Deterministic classification** — run `scripts/classifier.py` on the question +2. **Deterministic classification** — run `skills/research/scripts/classifier.py` on the question 3. **Route**: - **≥2 signals for one specialist** → delegate (with transparency) - **1 signal, single specialist** → weak match, delegate (with transparency) - **Otherwise** → ask Q3 disambiguation 4. **Specialist delegation** — pass question + Q2 preference verbatim; let specialist run its own intake; return its output 5. **Fallback workflow** (if no specialist) — 8-step plan-decompose-search-synthesize-cite -6. **Log routing decision** to `scripts/routing_transparency_logger.py` for audit +6. **Log routing decision** to `skills/research/scripts/routing_transparency_logger.py` for audit Differentiates from siblings: @@ -53,7 +53,7 @@ Differentiates from siblings: **Hard rules:** -1. **Deterministic classification.** Use `scripts/classifier.py` — keyword + intent signal matching, NOT LLM-reasoned routing. +1. **Deterministic classification.** Use `skills/research/scripts/classifier.py` — keyword + intent signal matching, NOT LLM-reasoned routing. 2. **Routing transparency mandatory.** Never delegate silently. Surface decision + accept override. 3. **Specialist delegation = pass-through.** Pass question verbatim. Don't pre-answer specialist's grill-me intake. 4. **Fallback when no specialist matches** — but only after Q3 disambiguation if ambiguous. @@ -68,15 +68,15 @@ Differentiates from siblings: ### Python Tools (Stdlib) -1. **Classifier** — `scripts/classifier.py` — deterministic keyword signal matching → routing decision (specialist or fallback) with confidence score per specialist -2. **Routing Transparency Logger** — `scripts/routing_transparency_logger.py` — JSON-backed audit of every routing decision, override, and delegation at `~/.research_sessions/<session>.json` -3. **Fallback Decomposer** — `scripts/fallback_decomposer.py` — heuristic question → 3-5 sub-questions using what/why/how/who/what's next framework +1. **Classifier** — `skills/research/scripts/classifier.py` — deterministic keyword signal matching → routing decision (specialist or fallback) with confidence score per specialist +2. **Routing Transparency Logger** — `skills/research/scripts/routing_transparency_logger.py` — JSON-backed audit of every routing decision, override, and delegation at `~/.research_sessions/<session>.json` +3. **Fallback Decomposer** — `skills/research/scripts/fallback_decomposer.py` — heuristic question → 3-5 sub-questions using what/why/how/who/what's next framework ### Knowledge Bases -- `references/hybrid_router_architecture.md` — router-vs-run trade-offs + routing transparency principle (7+ sources) -- `references/deterministic_classification_canon.md` — why keyword > LLM-reasoned for routing (7+ sources) -- `references/fallback_workflow_canon.md` — plan-decompose-search-synthesize methodology (7+ sources) +- `skills/research/references/hybrid_router_architecture.md` — router-vs-run trade-offs + routing transparency principle (7+ sources) +- `skills/research/references/deterministic_classification_canon.md` — why keyword > LLM-reasoned for routing (7+ sources) +- `skills/research/references/fallback_workflow_canon.md` — plan-decompose-search-synthesize methodology (7+ sources) ## Related Agents diff --git a/research/research/skills/research/SKILL.md b/research/research/skills/research/SKILL.md index f521084f..b899a52f 100644 --- a/research/research/skills/research/SKILL.md +++ b/research/research/skills/research/SKILL.md @@ -1,6 +1,6 @@ --- name: research -description: Default entry point for any research request — 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. Triggers — "research [topic]", "look into [topic]", "what do we know about [topic]", "investigate [topic]", "find me information on [topic]", "do some research on [topic]", "I need to understand [topic]", or any research request that doesn't obviously match a more-specific specialist skill. Output is a markdown briefing (default) or .docx document (on request) with full citations and an audit log. +description: Default entry point for any research request — 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-specific specialist skill (e.g., "research [topic]", "look into [topic]", "what do we know about [topic]", "investigate [topic]", "find me information on [topic]", "do some research on [topic]", "I need to understand [topic]"). Output is a markdown briefing (default) or .docx document (on request) with full citations and an audit log. --- # Research — Hybrid Router + Fallback diff --git a/research/syllabus/agents/cs-syllabus.md b/research/syllabus/agents/cs-syllabus.md index eb27457f..6d3dcc7f 100644 --- a/research/syllabus/agents/cs-syllabus.md +++ b/research/syllabus/agents/cs-syllabus.md @@ -57,9 +57,9 @@ The cs-syllabus agent orchestrates the `syllabus` skill across course-reading-li ### Python Tools (Stdlib) -1. **Citation Tracker** — `scripts/citation_tracker.py` — Consensus three-count + 1s sequential at `~/.syllabus_sessions/<session>.json` -2. **Topic Grouper** — `scripts/topic_grouper.py` — heuristic 6-12 section grouping from extracted topics -3. **Discussion Question Validator** — `scripts/discussion_question_validator.py` — Bloom higher-order quality check (rejects recall questions) +1. **Citation Tracker** — `skills/syllabus/scripts/citation_tracker.py` — Consensus three-count + 1s sequential at `~/.syllabus_sessions/<session>.json` +2. **Topic Grouper** — `skills/syllabus/scripts/topic_grouper.py` — heuristic 6-12 section grouping from extracted topics +3. **Discussion Question Validator** — `skills/syllabus/scripts/discussion_question_validator.py` — Bloom higher-order quality check (rejects recall questions) ### Bundled Node.js Script @@ -67,9 +67,9 @@ The cs-syllabus agent orchestrates the `syllabus` skill across course-reading-li ### Knowledge Bases -- `references/applied_domain_weaving.md` — search-quality canon (7+ sources) -- `references/audience_calibration.md` — undergrad vs grad summary jargon (7+ sources) -- `references/bundled_script_pattern.md` — why bundle vs inline (7+ sources) +- `skills/syllabus/references/applied_domain_weaving.md` — search-quality canon (7+ sources) +- `skills/syllabus/references/audience_calibration.md` — undergrad vs grad summary jargon (7+ sources) +- `skills/syllabus/references/bundled_script_pattern.md` — why bundle vs inline (7+ sources) ## Related Agents diff --git a/research/syllabus/skills/syllabus/SKILL.md b/research/syllabus/skills/syllabus/SKILL.md index 986657a5..1543e7b2 100644 --- a/research/syllabus/skills/syllabus/SKILL.md +++ b/research/syllabus/skills/syllabus/SKILL.md @@ -1,6 +1,6 @@ --- name: 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 — 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 questions tied to course learning goals. Triggers whenever a user uploads a syllabus, course outline, or curriculum document and wants supplementary readings. Also triggers on: 'syllabus reading list', 'find papers for my course', 'create a reading list from this syllabus', 'recent research for my class', 'supplementary readings', 'find journal articles for these topics', 'what recent papers cover this material', 'any new research on these course topics', 'update my syllabus with recent papers'. Even casual mentions when a syllabus is attached should trigger this skill." +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 — 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 questions tied to course learning goals. Use when the user uploads a syllabus, course outline, or curriculum document and wants supplementary readings (e.g., 'create a reading list from this syllabus', 'find recent papers for my course') — even casual mentions with a syllabus attached should trigger this skill." license: MIT metadata: source_spec: "megaprompts/10-syllabus-megaprompt.md" @@ -182,7 +182,7 @@ Use `scripts/discussion_question_validator.py` to flag recall-only questions. ## Phase 5: Generate .docx via Bundled Script ```bash -node ../scripts/generate_reading_list.js \ +node scripts/generate_reading_list.js \ --input /tmp/syllabus_data.json \ --output /path/to/reading_list_<course>_<date>.docx ``` @@ -246,7 +246,7 @@ See [`references/bundled_script_pattern.md`](references/bundled_script_pattern.m - File path - Audit summary in chat: "Saved {file}. {N} sections × {M} papers / {K} cited. Plan tier: {tier}." -- Validate: `python scripts/office/validate.py <docx>` +- Validate: check zip integrity with `python3 -c "import zipfile,sys; zipfile.ZipFile(sys.argv[1]).testzip()" <docx>` (no output = intact), then confirm the required sections are present ## Tooling diff --git a/scripts/audit_skills.py b/scripts/audit_skills.py index 3cee8530..fa76ccc9 100644 --- a/scripts/audit_skills.py +++ b/scripts/audit_skills.py @@ -1,6 +1,7 @@ #!/usr/bin/env python3 """Run skill_review_checklist_runner on every SKILL.md in the repo + aggregate.""" +import argparse import json import os import subprocess @@ -38,6 +39,14 @@ def audit_skill(skill_folder): def main(): + # Parse arguments BEFORE any work: `--help` must return instantly + # instead of running the full ~30s repo-wide audit. + parser = argparse.ArgumentParser( + description="Run the write-a-skill review checklist on every SKILL.md " + "in the repo and print an aggregate report (~30s on the " + "full tree). Running with no arguments audits everything.") + parser.parse_args() + skills = find_skills() print(f"Auditing {len(skills)} skills...\n", file=sys.stderr) diff --git a/scripts/check_dual_publish.py b/scripts/check_dual_publish.py new file mode 100644 index 00000000..fc18e02b --- /dev/null +++ b/scripts/check_dual_publish.py @@ -0,0 +1,182 @@ +#!/usr/bin/env python3 +"""Dual-publish drift guard (audit gate G4). + +Several skills are published twice on purpose: + + bundled: <domain>/skills/<name>/... + standalone: <domain>/<name>/skills/<name>/... + or <domain>/compliance-team-*/skills/<name>/... (ra-qm-team pattern) + +The two copies are kept in sync by scripts/sync_skill_bundles.py. This guard +discovers every such pair programmatically and recursively compares the two +trees (a `diff -rq` equivalent built on os.walk + filecmp with full content +comparison). Any file that exists on only one side, or whose content differs, +is drift. + +Exit codes: + 0 all pairs identical + 1 drift detected (drifted files listed on stdout) + 2 unexpected error (e.g. repo root not found) + +Usage: + python3 scripts/check_dual_publish.py # check all pairs + python3 scripts/check_dual_publish.py --list # show discovered pairs + python3 scripts/check_dual_publish.py --json # machine-readable report +""" +from __future__ import annotations + +import argparse +import filecmp +import json +import os +import sys + +REPO_ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__))) + +# Top-level directories that are never skill domains (sync copies, docs, VCS). +EXCLUDE_TOP_LEVEL = { + ".git", ".github", ".codex", ".gemini", ".hermes", ".vibe", ".claude", + ".claude-plugin", ".codex-plugin", "docs", "audit", "node_modules", + "integrations", "eval-workspace", "templates", "standards", "assets", + "scripts", "agents", "commands", "orchestration", "custom-gpt", "site", +} + +# Directory names that may never appear inside a compared payload +# (none expected today; kept for future-proofing against editor litter). +IGNORE_NAMES = {"__pycache__", ".DS_Store"} + + +def is_skill_dir(path): + return os.path.isfile(os.path.join(path, "SKILL.md")) + + +def discover_pairs(repo_root): + """Return [(bundled_rel, standalone_rel)] for every dual-publish pair.""" + pairs = [] + for domain in sorted(os.listdir(repo_root)): + domain_path = os.path.join(repo_root, domain) + if domain in EXCLUDE_TOP_LEVEL or domain.startswith("."): + continue + if not os.path.isdir(domain_path): + continue + bundled_root = os.path.join(domain_path, "skills") + if not os.path.isdir(bundled_root): + continue + for name in sorted(os.listdir(bundled_root)): + bundled = os.path.join(bundled_root, name) + if not is_skill_dir(bundled): + continue + candidates = [os.path.join(domain_path, name, "skills", name)] + for entry in sorted(os.listdir(domain_path)): + if entry.startswith("compliance-team-"): + candidates.append( + os.path.join(domain_path, entry, "skills", name)) + for cand in candidates: + if is_skill_dir(cand): + pairs.append(( + os.path.relpath(bundled, repo_root), + os.path.relpath(cand, repo_root), + )) + return pairs + + +def _listdir(path): + try: + return sorted(e for e in os.listdir(path) if e not in IGNORE_NAMES) + except OSError: + return [] + + +def compare_trees(left, right, rel=""): + """Recursive diff -rq equivalent. Returns list of drift descriptions.""" + drift = [] + left_entries = set(_listdir(left)) + right_entries = set(_listdir(right)) + + for entry in sorted(left_entries - right_entries): + drift.append(f"only-in-bundled: {os.path.join(rel, entry)}") + for entry in sorted(right_entries - left_entries): + drift.append(f"only-in-standalone: {os.path.join(rel, entry)}") + + for entry in sorted(left_entries & right_entries): + lp = os.path.join(left, entry) + rp = os.path.join(right, entry) + sub_rel = os.path.join(rel, entry) + l_dir, r_dir = os.path.isdir(lp), os.path.isdir(rp) + if l_dir != r_dir: + drift.append(f"type-mismatch (file vs dir): {sub_rel}") + elif l_dir: + drift.extend(compare_trees(lp, rp, sub_rel)) + else: + try: + same = filecmp.cmp(lp, rp, shallow=False) + except OSError as exc: + drift.append(f"unreadable: {sub_rel} ({exc})") + continue + if not same: + drift.append(f"differs: {sub_rel}") + return drift + + +def main(argv=None): + parser = argparse.ArgumentParser( + description="Verify dual-published skill pairs are byte-identical " + "(gate G4).") + parser.add_argument("--list", action="store_true", + help="list discovered pairs and exit") + parser.add_argument("--json", action="store_true", + help="emit a JSON report instead of human-readable output") + parser.add_argument("--root", default=REPO_ROOT, + help="repo root (default: parent of this script)") + args = parser.parse_args(argv) + + if not os.path.isdir(args.root): + print(f"ERROR: repo root not found: {args.root}", file=sys.stderr) + return 2 + + pairs = discover_pairs(args.root) + + if args.list: + if args.json: + print(json.dumps( + [{"bundled": b, "standalone": s} for b, s in pairs], indent=2)) + else: + for bundled, standalone in pairs: + print(f"{bundled} <-> {standalone}") + print(f"\n{len(pairs)} dual-publish pair(s) discovered") + return 0 + + report = [] + drifted_pairs = 0 + for bundled, standalone in pairs: + drift = compare_trees( + os.path.join(args.root, bundled), + os.path.join(args.root, standalone)) + report.append({"bundled": bundled, "standalone": standalone, + "drift": drift}) + if drift: + drifted_pairs += 1 + + if args.json: + print(json.dumps({ + "pairs": len(pairs), + "drifted": drifted_pairs, + "results": report, + }, indent=2)) + else: + for item in report: + status = "DRIFT" if item["drift"] else "OK" + print(f"[{status}] {item['bundled']} <-> {item['standalone']}") + for line in item["drift"]: + print(f" {line}") + print(f"\n{len(pairs)} pair(s) checked, {drifted_pairs} drifted") + + if not pairs: + print("WARNING: no dual-publish pairs discovered — discovery logic " + "may be stale", file=sys.stderr) + + return 1 if drifted_pairs else 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/scripts/check_paths.py b/scripts/check_paths.py new file mode 100644 index 00000000..79210abe --- /dev/null +++ b/scripts/check_paths.py @@ -0,0 +1,215 @@ +#!/usr/bin/env python3 +"""check_paths.py — phantom-path linter for skills, agents, and commands. + +Scans SKILL.md files plus *.md files under any agents/ or commands/ directory +for path-like references (scripts/, references/, assets/, skills/, templates/ +tokens, `python x.py` invocations, and ../ relative paths) and verifies each +candidate resolves against (a) the owning skill/plugin root, (b) the file's +own directory, or (c) the repo root. A candidate is OK if ANY base resolves. + +Known dynamic patterns (containing { < $ ~ *) and URLs are skipped. + +Exit codes: 0 = all paths resolve, 1 = at least one unresolvable path. +Intended as CI gate G1. + +Usage: + python3 scripts/check_paths.py --all # scan canonical dirs repo-wide + python3 scripts/check_paths.py FILE [FILE ...] # scan specific files + python3 scripts/check_paths.py --all --json # machine-readable output +""" + +import argparse +import fnmatch +import json +import os +import re +import sys + +EXCLUDED_DIRS = { + ".git", ".codex", ".gemini", ".hermes", ".vibe", "docs", "audit", + "node_modules", ".github", ".claude", ".claude-plugin", +} + +# Token-style paths anchored on a canonical content dir, with a known extension. +RE_MARKER_PATH = re.compile( + r"[A-Za-z0-9_\-./]*\b(?:scripts|references|assets|skills|templates)/" + r"[A-Za-z0-9_\-./]+\.(?:py|md|sh|json|yaml|yml)\b" +) +# Any multi-segment reference to a SKILL.md file. +RE_SKILLMD = re.compile(r"[A-Za-z0-9_\-./]+/SKILL\.md\b") +# python / python3 script invocations. +RE_PY_INVOKE = re.compile(r"\bpython3?\s+([A-Za-z0-9_\-./]+\.py)\b") +# Relative parent-dir paths. +RE_RELATIVE = re.compile(r"\.\./[A-Za-z0-9_\-./]+") + +DYNAMIC_CHARS = set("{<$~*") +PLACEHOLDER_HINTS = ("path/to", "your-", "your_", "example.com", "...", "skill-name", "agent-name") +# Chars that, immediately before a match, signal a placeholder prefix was cut off +# (e.g. `{skill_path}/scripts/x.py`, `"$SKILL/scripts/x.py"`, `<plugin>/scripts/x.py`, +# `TC-001-.../tc_record.json` — a literal `.` before `../` means an `...` ellipsis). +PLACEHOLDER_PREFIX_CHARS = set("}$>*~.") +# Gitignored maintainer-local folders (see root CLAUDE.md): references into these +# are intentional dead links for cloners — not phantom paths. +MAINTAINER_LOCAL = ("megaprompts", "documentation", "eval-workspace", "tests", ".autoresearch") + + +def is_dynamic(token: str) -> bool: + if any(c in DYNAMIC_CHARS for c in token): + return True + if "://" in token or token.startswith("http"): + return True + low = token.lower() + return any(h in low for h in PLACEHOLDER_HINTS) + + +def clean(token: str) -> str: + token = token.strip().strip("`'\"()[]<>,;:") + while token.startswith("./"): + token = token[2:] + return token.rstrip(".") + + +def extract_candidates(text: str): + """Yield normalized path candidates found in text.""" + seen = set() + for regex, group in ((RE_MARKER_PATH, 0), (RE_SKILLMD, 0), (RE_PY_INVOKE, 1), (RE_RELATIVE, 0)): + for m in regex.finditer(text): + start = m.start(group) + if start > 0 and text[start - 1] in PLACEHOLDER_PREFIX_CHARS: + continue # truncated placeholder like {skill_path}/scripts/x.py + tok = clean(m.group(group)) + if not tok or "/" not in tok: + continue + if is_dynamic(tok): + continue + parts = [p for p in tok.split("/") if p and p != ".."] + if parts and parts[0] in MAINTAINER_LOCAL: + continue # intentional gitignored maintainer-local link + if tok not in seen: + seen.add(tok) + yield tok + + +def skill_root(file_path: str, repo_root: str) -> str: + """Walk up from the file's dir to the nearest skill/plugin root.""" + d = os.path.dirname(os.path.abspath(file_path)) + # If the file sits in an agents/ or commands/ dir, the plugin root is above it. + while True: + if (os.path.isfile(os.path.join(d, "SKILL.md")) + or os.path.isdir(os.path.join(d, ".claude-plugin")) + or os.path.isfile(os.path.join(d, "plugin.json"))): + return d + parent = os.path.dirname(d) + if parent == d or os.path.abspath(d) == os.path.abspath(repo_root): + return os.path.abspath(repo_root) + d = parent + + +def resolves(candidate: str, bases) -> bool: + for base in bases: + p = os.path.normpath(os.path.join(base, candidate)) + if os.path.exists(p): + return True + return False + + +def load_allowlist(repo_root: str): + """Read scripts/check_paths_allowlist.txt: `file-glob :: candidate-glob` per line. + + Each entry whitelists a known false positive (teaching examples, hypothetical + user-project paths, example tool output). Keep entries narrow — one file glob + plus one candidate glob — so real path contracts stay checked. + """ + entries = [] + path = os.path.join(repo_root, "scripts", "check_paths_allowlist.txt") + if not os.path.isfile(path): + return entries + with open(path, encoding="utf-8") as fh: + for line in fh: + line = line.split("#", 1)[0].strip() + if not line or "::" not in line: + continue + file_glob, cand_glob = (part.strip() for part in line.split("::", 1)) + if file_glob and cand_glob: + entries.append((file_glob, cand_glob)) + return entries + + +def allowlisted(rel_file: str, candidate: str, allowlist) -> bool: + return any( + fnmatch.fnmatch(rel_file, fg) and fnmatch.fnmatch(candidate, cg) + for fg, cg in allowlist + ) + + +def scan_file(path: str, repo_root: str, allowlist=()): + """Return list of unresolvable path candidates in file.""" + try: + with open(path, encoding="utf-8", errors="replace") as fh: + text = fh.read() + except OSError as exc: + return [f"<unreadable: {exc}>"] + file_dir = os.path.dirname(os.path.abspath(path)) + bases = (skill_root(path, repo_root), file_dir, os.path.abspath(repo_root)) + rel_file = os.path.relpath(os.path.abspath(path), repo_root) + return [c for c in extract_candidates(text) + if not resolves(c, bases) and not allowlisted(rel_file, c, allowlist)] + + +def collect_canonical(repo_root: str): + """All SKILL.md + *.md under any agents/ or commands/ dir, excluding sync/doc trees.""" + targets = [] + for dirpath, dirnames, filenames in os.walk(repo_root): + dirnames[:] = [d for d in dirnames if d not in EXCLUDED_DIRS] + parts = os.path.relpath(dirpath, repo_root).split(os.sep) + in_canonical_dir = "agents" in parts or "commands" in parts + for fn in filenames: + if fn == "SKILL.md" or (in_canonical_dir and fn.endswith(".md")): + targets.append(os.path.join(dirpath, fn)) + return sorted(targets) + + +def main(): + ap = argparse.ArgumentParser( + description="Lint SKILL.md / agents / commands files for phantom (unresolvable) path references." + ) + ap.add_argument("files", nargs="*", help="Specific markdown files to scan") + ap.add_argument("--all", action="store_true", + help="Scan all SKILL.md + agents/*.md + commands/*.md in the repo") + ap.add_argument("--json", action="store_true", help="Emit JSON instead of human-readable output") + ap.add_argument("--root", default=os.path.dirname(os.path.dirname(os.path.abspath(__file__))), + help="Repo root (default: parent of this script)") + args = ap.parse_args() + + repo_root = os.path.abspath(args.root) + if args.all: + targets = collect_canonical(repo_root) + elif args.files: + targets = [os.path.abspath(f) for f in args.files] + else: + ap.print_help() + return 0 + + allowlist = load_allowlist(repo_root) + findings = {} + for f in targets: + bad = scan_file(f, repo_root, allowlist) + if bad: + findings[os.path.relpath(f, repo_root)] = bad + + total = sum(len(v) for v in findings.values()) + if args.json: + print(json.dumps({"files_scanned": len(targets), "files_with_findings": len(findings), + "total_unresolvable": total, "findings": findings}, indent=2)) + else: + for f in sorted(findings): + print(f"{f}:") + for p in findings[f]: + print(f" UNRESOLVABLE: {p}") + print(f"\nScanned {len(targets)} files; {len(findings)} files with findings; " + f"{total} unresolvable path references.") + return 1 if total else 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/scripts/check_paths_allowlist.txt b/scripts/check_paths_allowlist.txt new file mode 100644 index 00000000..77a4ec90 --- /dev/null +++ b/scripts/check_paths_allowlist.txt @@ -0,0 +1,38 @@ +# check_paths.py allowlist — known FALSE POSITIVES only. +# Format: <file-glob> :: <candidate-glob> (fnmatch on both sides) +# Every entry must be a teaching example, hypothetical user-project path, or +# example tool output — never a real path contract. Keep entries narrow. + +# Example commands inside a hypothetical ML project workflow (user's repo, not ours). +engineering-team/skills/senior-data-scientist/SKILL.md :: scripts/train.py +engineering-team/skills/senior-data-scientist/SKILL.md :: scripts/evaluate.py +engineering-team/skills/senior-data-scientist/SKILL.md :: scripts/health_check.py + +# TS import statements in generated-test / seed-script code examples (user's repo). +engineering-team/skills/senior-qa/SKILL.md :: ../src/components/Button +engineering/skills/database-schema-designer/SKILL.md :: ../src/lib/auth +engineering-team/skills/email-template-builder/SKILL.md :: ../components/layout/email-layout +engineering-team/skills/email-template-builder/SKILL.md :: ../templates/welcome +engineering-team/skills/email-template-builder/SKILL.md :: ../templates/invoice +engineering-team/skills/email-template-builder/SKILL.md :: ../i18n + +# Terragrunt/Terraform source/config_path examples (user's infra repo layout). +engineering/terraform-patterns/skills/terraform-patterns/SKILL.md :: ../../modules/vpc +engineering/terraform-patterns/skills/terraform-patterns/SKILL.md :: ../vpc + +# Example audit-report output: file names inside a fictitious audited skill. +engineering/skills/skill-security-auditor/SKILL.md :: scripts/helper.py +engineering/skills/skill-security-auditor/SKILL.md :: scripts/analyzer.py +engineering/skills/skill-security-auditor/SKILL.md :: scripts/scanner.py + +# Anti-pattern teaching example ("No references/category/subtopic.md"). +engineering/write-a-skill/commands/cs-write-a-skill.md :: references/category/subtopic.md + +# Example names of skills the extract workflow would GENERATE in the user's tree. +engineering-team/self-improving-agent/skills/extract/SKILL.md :: docker-m1-fixes/SKILL.md +engineering-team/self-improving-agent/skills/extract/SKILL.md :: api-client-regen/SKILL.md + +# Path-traversal attack payload in a pen-testing teaching table, not a real +# file reference. Would point outside the repo root if resolved literally; +# allowlisted as a teaching example, not an actual file. +engineering-team/skills/security-pen-testing/SKILL.md :: ../../../etc/passwd diff --git a/scripts/derive_counters.py b/scripts/derive_counters.py new file mode 100644 index 00000000..97d49e8a --- /dev/null +++ b/scripts/derive_counters.py @@ -0,0 +1,238 @@ +#!/usr/bin/env python3 +"""derive_counters.py — single source of truth for repository headline counters. + +Walks the canonical tree (excluding sync copies, docs site, audit workspace, +and VCS/CI internals) and derives the headline numbers that README.md, +CLAUDE.md, and .claude-plugin/marketplace.json claim: + + skills count of SKILL.md files + plugins_on_disk count of **/.claude-plugin/plugin.json manifests + plugins_registered entries in .claude-plugin/marketplace.json `plugins` array + python_tools .py files in the canonical tree, excluding repo-root scripts/ + (i.e. automation tools shipped inside skill/plugin folders) + references .md files under any references/ directory + agents .md files under any agents/ directory (excl. CLAUDE.md/README.md) + commands .md files under any commands/ directory (excl. CLAUDE.md/README.md) + domains top-level folders containing at least one SKILL.md + +Modes: + (default) print a human-readable table + --json print the derived counters as JSON + --check exit 1 listing mismatches if the headline counters claimed in + README.md, root CLAUDE.md ("Current Scope" line), and + marketplace.json metadata.description disagree with derived + values. CI gate G3. + +Stdlib only. No writes ever. +""" + +import argparse +import json +import re +import sys +from pathlib import Path + +REPO_ROOT = Path(__file__).resolve().parent.parent + +# Top-level directories excluded from the canonical tree. +EXCLUDED_TOP_LEVEL = { + ".git", + ".codex", + ".codex-plugin", + ".gemini", + ".hermes", + ".vibe", + "docs", + "audit", + "node_modules", + ".github", + ".claude", +} + +DOC_FILENAMES = {"CLAUDE.md", "README.md"} + + +def canonical_walk(root: Path): + """Yield every file in the canonical tree (excluded top-level dirs pruned).""" + stack = [root] + while stack: + current = stack.pop() + try: + entries = sorted(current.iterdir()) + except OSError: + continue + for entry in entries: + if entry.is_symlink(): + continue + if entry.is_dir(): + if current == root and entry.name in EXCLUDED_TOP_LEVEL: + continue + stack.append(entry) + elif entry.is_file(): + yield entry + + +def derive(root: Path) -> dict: + counters = { + "skills": 0, + "plugins_on_disk": 0, + "plugins_registered": 0, + "python_tools": 0, + "references": 0, + "agents": 0, + "commands": 0, + "domains": 0, + } + domains = set() + + for path in canonical_walk(root): + rel = path.relative_to(root) + parts = rel.parts + name = path.name + + if name == "SKILL.md": + counters["skills"] += 1 + if len(parts) > 1: + domains.add(parts[0]) + elif name == "plugin.json" and path.parent.name == ".claude-plugin": + counters["plugins_on_disk"] += 1 + elif path.suffix == ".py": + # Skill/plugin automation tools: every .py except repo-root scripts/. + if parts[0] != "scripts": + counters["python_tools"] += 1 + elif path.suffix == ".md": + if "references" in parts[:-1]: + counters["references"] += 1 + elif "agents" in parts[:-1] and name not in DOC_FILENAMES: + counters["agents"] += 1 + elif "commands" in parts[:-1] and name not in DOC_FILENAMES: + counters["commands"] += 1 + + counters["domains"] = len(domains) + counters["_domain_list"] = sorted(domains) + + marketplace = root / ".claude-plugin" / "marketplace.json" + if marketplace.is_file(): + try: + data = json.loads(marketplace.read_text(encoding="utf-8")) + counters["plugins_registered"] = len(data.get("plugins", [])) + except (json.JSONDecodeError, OSError): + counters["plugins_registered"] = -1 + + return counters + + +# --------------------------------------------------------------------------- +# --check: parse the standardized claim patterns in the three headline files. +# +# Standardized claim patterns (keep docs in lockstep with these): +# "<N> production-ready skills" (or "production-ready Claude Code skills") +# "skills across <D> domains" +# "<T> Python automation tools" or "<T> Python tools" +# "<R> reference guides" +# "<P> marketplace plugins" +# --------------------------------------------------------------------------- + +CLAIM_PATTERNS = { + "skills": re.compile(r"(\d+)\s+production-ready (?:Claude Code )?skills"), + "domains": re.compile(r"skills across\s+(\d+)\s+domains"), + "python_tools": re.compile(r"(\d+)\s+Python (?:automation )?tools"), + "references": re.compile(r"(\d+)\s+reference guides"), + "plugins_registered": re.compile(r"(\d+)\s+marketplace plugins"), +} + + +def extract_claims(text: str) -> dict: + """Return {counter_name: first claimed int} for every pattern found in text.""" + claims = {} + for key, pattern in CLAIM_PATTERNS.items(): + match = pattern.search(text) + if match: + claims[key] = int(match.group(1)) + return claims + + +def run_check(root: Path, derived: dict) -> int: + sources = [] + + readme = root / "README.md" + if readme.is_file(): + sources.append(("README.md", readme.read_text(encoding="utf-8"))) + + claude_md = root / "CLAUDE.md" + if claude_md.is_file(): + text = claude_md.read_text(encoding="utf-8") + # Restrict to the "Current Scope" line so history sections don't trip the gate. + scope_lines = [ln for ln in text.splitlines() if ln.startswith("**Current Scope:**")] + sources.append(("CLAUDE.md (Current Scope line)", "\n".join(scope_lines))) + + marketplace = root / ".claude-plugin" / "marketplace.json" + if marketplace.is_file(): + try: + data = json.loads(marketplace.read_text(encoding="utf-8")) + desc = data.get("metadata", {}).get("description", "") + sources.append(("marketplace.json metadata.description", desc)) + except (json.JSONDecodeError, OSError) as exc: + print(f"FAIL: cannot parse marketplace.json: {exc}") + return 1 + + mismatches = [] + for label, text in sources: + claims = extract_claims(text) + if not claims: + mismatches.append(f"{label}: no recognizable counter claims found") + continue + for key, claimed in claims.items(): + actual = derived[key] + if claimed != actual: + mismatches.append( + f"{label}: claims {key}={claimed}, derived {key}={actual}" + ) + + if mismatches: + print("COUNTER CHECK FAILED — headline claims disagree with derived values:") + for line in mismatches: + print(f" - {line}") + print("\nRun `python3 scripts/derive_counters.py` for the ground-truth table.") + return 1 + + print("Counter check passed: README.md, CLAUDE.md, marketplace.json match derived values.") + return 0 + + +def main() -> int: + parser = argparse.ArgumentParser( + description="Derive repository headline counters from the canonical tree." + ) + parser.add_argument("--json", action="store_true", help="emit counters as JSON") + parser.add_argument( + "--check", + action="store_true", + help="exit 1 if README.md / CLAUDE.md / marketplace.json claims drift from derived values", + ) + args = parser.parse_args() + + derived = derive(REPO_ROOT) + domain_list = derived.pop("_domain_list") + + if args.json: + out = dict(derived) + out["domain_list"] = domain_list + print(json.dumps(out, indent=2)) + else: + width = max(len(k) for k in derived) + print("Derived repository counters (canonical tree)") + print("-" * 46) + for key, value in derived.items(): + print(f"{key.ljust(width)} {value}") + print("-" * 46) + print("domains: " + ", ".join(domain_list)) + + if args.check: + derived["_domain_list"] = domain_list + return run_check(REPO_ROOT, derived) + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/scripts/generate-docs.py b/scripts/generate-docs.py index 0eec27ff..fbf05aaa 100644 --- a/scripts/generate-docs.py +++ b/scripts/generate-docs.py @@ -1,6 +1,7 @@ #!/usr/bin/env python3 """Generate MkDocs documentation pages from SKILL.md files, agents, and commands.""" +import argparse import os import re import shutil @@ -202,6 +203,7 @@ DOMAIN_SEO_SUFFIX = { "productivity": "Agent Skill for Personal Productivity", "marketing": "Agent Skill for Landing Pages", "research": "Agent Skill for Research Workflows", + "markdown-html": "Agent Skill for HTML Output", } # Domain-specific description context for pages without frontmatter descriptions @@ -222,7 +224,7 @@ DOMAIN_SEO_CONTEXT = { "commercial": "commercial agent skill and Claude Code plugin for pricing strategy, deal desk, partnerships, and RFP response", "research-ops": "enterprise research operations agent skill and Claude Code plugin for clinical study design, R&D finance, market sizing, and product research", "compliance-os": "compliance readiness agent skill and Claude Code plugin for ISO 13485, ISO 27001, SOC 2, GDPR, FDA QSR, and EU AI Act audit prep", - "markdown-html": "markdown-to-HTML converter agent skill and Claude Code plugin for single-file interactive documents, code reviews, and slide decks", + "markdown-html": "markdown-to-interactive-HTML converter agent skill and Claude Code plugin for single-file documents, code reviews, and slide decks", } @@ -293,6 +295,13 @@ def rewrite_relative_links(content, source_rel_path): def resolve_link(match): text = match.group(1) rel_target = match.group(2) + # Repo-root-relative links (e.g. engineering/grill-me/agents/cs-foo.md or + # marketing-skill/skills/aeo/SKILL.md) exist in the repo but not in docs/ — + # rewrite them to GitHub source URLs. + if (not rel_target.startswith(("../", "#", "http://", "https://", "mailto:")) + and "/" in rel_target + and os.path.exists(os.path.join(REPO_ROOT, rel_target.split("#")[0]))): + return f"[{text}]({GITHUB_BASE}/{rel_target})" # Only rewrite relative paths that go up (../) if not rel_target.startswith("../"): return match.group(0) @@ -309,7 +318,7 @@ def rewrite_relative_links(content, source_rel_path): return f"[{text}]({sibling})" return f"[{text}]({GITHUB_BASE}/{resolved})" - content = re.sub(r"\[([^\]]+)\]\((\.\.[^\)]+)\)", resolve_link, content) + content = re.sub(r"\[([^\]]+)\]\(([^)\s]+)\)", resolve_link, content) # Also rewrite backtick code references like `../../product-team/foo/SKILL.md` # Convert to clickable GitHub links @@ -429,6 +438,20 @@ def generate_nav_entry(skills_by_domain): return "\n".join(nav_lines) +def parse_args(argv=None): + """Parse CLI arguments BEFORE any filesystem access. + + `--help` must be side-effect-free: argparse prints usage and exits 0 + without ever touching docs/. Default (no-arg) behavior is unchanged — + the full docs/ tree is regenerated. + """ + parser = argparse.ArgumentParser( + description="Generate MkDocs documentation pages from SKILL.md files, " + "agents, and commands. Running with no arguments rewrites " + "the docs/ tree.") + return parser.parse_args(argv) + + def main(): skills_by_domain = find_skill_files() @@ -570,6 +593,7 @@ description: "{skill_count} {domain_name.lower()} skills — {domain_seo_ctx}. W "product": ("Product", ":material-lightbulb-outline:"), "project-management": ("Project Management", ":material-clipboard-check-outline:"), "ra-qm-team": ("Regulatory & Quality", ":material-shield-check-outline:"), + "markdown-html": ("Markdown to HTML", ":material-language-html5:"), } if os.path.isdir(agents_dir): @@ -647,6 +671,7 @@ description: "{agent_desc}" "commercial": "commercial", "research-ops": "research-ops", "compliance-os": "compliance-os", + "markdown-html": "markdown-html", } seen_slugs = {entry[1] for entry in agent_entries} for skill_domain in DOMAINS: @@ -917,4 +942,5 @@ description: "{cmd_count} slash commands for Claude Code, Codex CLI, and Gemini if __name__ == "__main__": + parse_args() main() diff --git a/scripts/smoke_exceptions.txt b/scripts/smoke_exceptions.txt new file mode 100644 index 00000000..e5f05542 --- /dev/null +++ b/scripts/smoke_exceptions.txt @@ -0,0 +1,20 @@ +# By-design exceptions for scripts/smoke_scripts.py (gate G8). +# Format: <path relative to repo root> # reason +# These scripts intentionally do not implement a CLI `--help` contract. + +# Fixed-contract evaluators: argv contract is fixed by engineering/autoresearch-agent +# (called as `evaluator.py <target-file>`; exit code IS the metric channel). +engineering/autoresearch-agent/evaluators/benchmark_size.py # fixed-contract autoresearch evaluator +engineering/autoresearch-agent/evaluators/benchmark_speed.py # fixed-contract autoresearch evaluator +engineering/autoresearch-agent/evaluators/build_speed.py # fixed-contract autoresearch evaluator +engineering/autoresearch-agent/evaluators/llm_judge_content.py # fixed-contract autoresearch evaluator +engineering/autoresearch-agent/evaluators/llm_judge_copy.py # fixed-contract autoresearch evaluator +engineering/autoresearch-agent/evaluators/llm_judge_prompt.py # fixed-contract autoresearch evaluator +engineering/autoresearch-agent/evaluators/memory_usage.py # fixed-contract autoresearch evaluator +engineering/autoresearch-agent/evaluators/test_pass_rate.py # fixed-contract autoresearch evaluator + +# Claude Code hooks: invoked by the hook runner with a JSON payload on stdin, +# not as CLI tools (exit 2 is a signaling channel for PreToolUse). +engineering/security-guidance/hooks/security_reminder_hook.py # PreToolUse stdin hook +productivity/handoff/hooks/session_start.py # SessionStart stdin hook +productivity/handoff/hooks/session_end.py # SessionEnd stdin hook diff --git a/scripts/smoke_json_output.py b/scripts/smoke_json_output.py new file mode 100755 index 00000000..77ce7ec1 --- /dev/null +++ b/scripts/smoke_json_output.py @@ -0,0 +1,227 @@ +#!/usr/bin/env python3 +"""JSON-output verification gate for Python tools (audit gate G9). + +Companion to smoke_scripts.py (which only asserts `--help` exits 0). Many tools +advertise `--json` or `--format json` in their help text but require positional +or required arguments before they can emit anything — so a bare-flag smoke test +reports false failures (see issue #654). + +This harness verifies JSON output the way the tools are actually meant to run: + + 1. Discover every tool whose `--help` advertises JSON output AND an embedded + `--sample` fixture (the chosen convention — issue #654 Option A). + 2. Run `<tool> --sample <json-flag>` and assert stdout parses as JSON. + +Tools that advertise JSON output but do NOT yet expose `--sample` are reported +as "uncovered" — a to-do list for backporting the convention, not a failure +(so the gate can be adopted incrementally without going red on day one). +Pass --strict to treat uncovered JSON tools as failures once coverage is high. + +Exit codes: + 0 every --sample JSON tool produced valid JSON (and, with --strict, every + JSON-advertising tool exposes --sample) + 1 one or more --sample JSON runs produced invalid JSON / errored + 2 harness error + +Usage: + python3 scripts/smoke_json_output.py # human-readable report + python3 scripts/smoke_json_output.py --json # machine-readable report + python3 scripts/smoke_json_output.py --strict # uncovered JSON tools fail +""" +from __future__ import annotations + +import argparse +import concurrent.futures +import json +import os +import re +import subprocess +import sys + +REPO_ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__))) +TIMEOUT_SECONDS = 20 + +# Reuse the same exclusion set + exceptions file as the --help gate. +EXCLUDE_DIRS = { + ".git", ".codex", ".gemini", ".hermes", ".vibe", "docs", "audit", + "node_modules", "integrations", "eval-workspace", "site", + "__pycache__", ".venv", "venv", +} +EXCEPTIONS_FILE = os.path.join(REPO_ROOT, "scripts", "smoke_exceptions.txt") + +# The smoke harnesses describe `--sample`/`--json` in their own help text but +# are gate runners, not analysis tools — never classify them as JSON tools. +SELF_SKIP = {"scripts/smoke_json_output.py", "scripts/smoke_scripts.py"} + +# `--format json` is only a valid invocation when help shows json as a choice, +# e.g. `--format {text,json}`. A bare mention of the word "format" elsewhere in +# help must not trigger it (that misfires on tools that only accept `--json`). +_FORMAT_JSON_RE = re.compile(r"--format[ =]?\{[^}]*\bjson\b[^}]*\}") + + +def load_exceptions(path): + exceptions = {} + if not os.path.isfile(path): + return exceptions + with open(path, "r", encoding="utf-8") as f: + for raw in f: + line = raw.strip() + if not line or line.startswith("#"): + continue + rel = line.split("#", 1)[0].strip() + if rel: + exceptions[rel] = True + return exceptions + + +def find_python_files(root): + files = [] + for dirpath, dirnames, filenames in os.walk(root): + dirnames[:] = sorted(d for d in dirnames if d not in EXCLUDE_DIRS) + for name in sorted(filenames): + if name.endswith(".py"): + files.append(os.path.relpath( + os.path.join(dirpath, name), root).replace(os.sep, "/")) + return files + + +def _help_text(abs_path): + try: + proc = subprocess.run( + [sys.executable, abs_path, "--help"], + stdin=subprocess.DEVNULL, capture_output=True, text=True, + timeout=TIMEOUT_SECONDS, cwd=os.path.dirname(abs_path), + ) + except (subprocess.TimeoutExpired, OSError): + return "" + return (proc.stdout or "") + (proc.stderr or "") if proc.returncode == 0 else "" + + +def classify(rel_path): + """Return (advertises_json, json_flag, has_sample) for one tool.""" + if rel_path in SELF_SKIP: + return False, None, False + abs_path = os.path.join(REPO_ROOT, rel_path) + help_text = _help_text(abs_path) + if not help_text: + return False, None, False + low = help_text.lower() + # Prefer `--format json` only when help shows json as an actual choice; + # otherwise fall back to a plain `--json` flag. + json_flag = None + if _FORMAT_JSON_RE.search(low): + json_flag = ["--format", "json"] + elif re.search(r"(?<![\w-])--json(?![\w-])", low): + json_flag = ["--json"] + advertises_json = json_flag is not None + has_sample = "--sample" in low + return advertises_json, json_flag, has_sample + + +def verify_one(rel_path, json_flag): + """Run `<tool> --sample <json_flag>` and check stdout parses as JSON.""" + abs_path = os.path.join(REPO_ROOT, rel_path) + try: + proc = subprocess.run( + [sys.executable, abs_path, "--sample", *json_flag], + stdin=subprocess.DEVNULL, capture_output=True, text=True, + timeout=TIMEOUT_SECONDS, cwd=os.path.dirname(abs_path), + ) + except subprocess.TimeoutExpired: + return rel_path, False, f"timeout after {TIMEOUT_SECONDS}s" + except OSError as exc: + return rel_path, False, f"could not execute: {exc}" + # A non-zero exit is acceptable only if the tool intentionally signals a + # finding through its exit code (e.g. blast_radius RED) — but it must still + # have emitted valid JSON on stdout. + out = (proc.stdout or "").strip() + if not out: + tail = (proc.stderr or "").strip().splitlines() + return rel_path, False, f"no stdout (exit {proc.returncode}): {tail[-1] if tail else ''}"[:200] + try: + json.loads(out) + except json.JSONDecodeError as exc: + return rel_path, False, f"stdout is not valid JSON: {exc}" + return rel_path, True, "" + + +def main(argv=None): + parser = argparse.ArgumentParser(description=__doc__, + formatter_class=argparse.RawDescriptionHelpFormatter) + parser.add_argument("--json", action="store_true", + help="emit a JSON report instead of human-readable output") + parser.add_argument("--strict", action="store_true", + help="treat JSON-advertising tools without --sample as failures") + parser.add_argument("--jobs", type=int, default=os.cpu_count() or 4, + help="parallel workers (default: CPU count)") + parser.add_argument("--root", default=REPO_ROOT, help="repo root") + args = parser.parse_args(argv) + + try: + exceptions = load_exceptions(EXCEPTIONS_FILE) + except OSError as exc: + print(f"ERROR: cannot read exceptions file: {exc}", file=sys.stderr) + return 2 + + all_files = [f for f in find_python_files(args.root) if f not in exceptions] + + # Phase 1: classify in parallel. + json_tools = {} # rel_path -> json_flag + uncovered = [] # advertises json but no --sample + with concurrent.futures.ThreadPoolExecutor(max_workers=args.jobs) as pool: + results = pool.map(lambda f: (f, *classify(f)), all_files) + for rel_path, advertises, json_flag, has_sample in results: + if not advertises: + continue + if has_sample: + json_tools[rel_path] = json_flag + else: + uncovered.append(rel_path) + uncovered.sort() + + # Phase 2: verify covered tools in parallel. + failures = [] + with concurrent.futures.ThreadPoolExecutor(max_workers=args.jobs) as pool: + for rel_path, ok, detail in pool.map( + lambda item: verify_one(item[0], item[1]), sorted(json_tools.items())): + if not ok: + failures.append({"file": rel_path, "detail": detail}) + failures.sort(key=lambda f: f["file"]) + + covered = len(json_tools) + total_json = covered + len(uncovered) + coverage_pct = round(100 * covered / total_json, 1) if total_json else 100.0 + + if args.json: + print(json.dumps({ + "json_advertising_tools": total_json, + "covered_by_sample": covered, + "coverage_pct": coverage_pct, + "verified_ok": covered - len(failures), + "failed": failures, + "uncovered": uncovered, + }, indent=2)) + else: + print(f"JSON-advertising tools: {total_json}") + print(f"Covered by --sample: {covered} ({coverage_pct}%)") + print(f"Verified valid JSON: {covered - len(failures)}") + print(f"Failed: {len(failures)}") + print(f"Uncovered (no --sample): {len(uncovered)}") + if failures: + print("\nFAILURES:") + for f in failures: + print(f" {f['file']}\n {f['detail']}") + if uncovered: + print("\nUNCOVERED (advertise JSON but lack --sample — backport target):") + for f in uncovered: + print(f" {f}") + + if failures: + return 1 + if args.strict and uncovered: + return 1 + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/scripts/smoke_scripts.py b/scripts/smoke_scripts.py new file mode 100644 index 00000000..ab8c77f2 --- /dev/null +++ b/scripts/smoke_scripts.py @@ -0,0 +1,169 @@ +#!/usr/bin/env python3 +"""Repo-wide `--help` smoke gate for Python tools (audit gate G8). + +Contract: every `.py` file in the canonical tree must exit 0 on +`python3 <file> --help` within 15 seconds. Hook-style scripts that read +stdin and fixed-contract evaluators are listed (with a reason) in +scripts/smoke_exceptions.txt and skipped. + +Excluded directories: derived sync copies (.codex/.gemini/.hermes/.vibe), +docs/, audit/, node_modules/, .git/, generated integrations/, gitignored +maintainer-local folders, and __pycache__. + +Exit codes: + 0 every non-excepted script passed + 1 one or more non-excepted scripts failed (listed on stdout) + 2 harness error (e.g. exceptions file unreadable) + +Usage: + python3 scripts/smoke_scripts.py # human-readable report + python3 scripts/smoke_scripts.py --json # machine-readable report + python3 scripts/smoke_scripts.py --jobs 4 # control parallelism +""" +from __future__ import annotations + +import argparse +import concurrent.futures +import json +import os +import subprocess +import sys + +REPO_ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__))) +EXCEPTIONS_FILE = os.path.join(REPO_ROOT, "scripts", "smoke_exceptions.txt") +TIMEOUT_SECONDS = 15 + +# Directory names pruned anywhere in the walk. +EXCLUDE_DIRS = { + ".git", ".codex", ".gemini", ".hermes", ".vibe", "docs", "audit", + "node_modules", "integrations", "eval-workspace", "site", + "__pycache__", ".venv", "venv", +} + + +def load_exceptions(path): + """Parse the by-design exceptions file: `<relpath> # reason` per line.""" + exceptions = {} + if not os.path.isfile(path): + return exceptions + with open(path, "r", encoding="utf-8") as f: + for raw in f: + line = raw.strip() + if not line or line.startswith("#"): + continue + if "#" in line: + rel, reason = line.split("#", 1) + exceptions[rel.strip()] = reason.strip() + else: + exceptions[line] = "(no reason given)" + return exceptions + + +def find_python_files(root): + files = [] + for dirpath, dirnames, filenames in os.walk(root): + dirnames[:] = sorted( + d for d in dirnames if d not in EXCLUDE_DIRS) + for name in sorted(filenames): + if name.endswith(".py"): + files.append(os.path.relpath( + os.path.join(dirpath, name), root).replace(os.sep, "/")) + return files + + +def smoke_one(rel_path): + """Run `python3 <file> --help`; return (rel_path, ok, detail).""" + abs_path = os.path.join(REPO_ROOT, rel_path) + try: + proc = subprocess.run( + [sys.executable, abs_path, "--help"], + stdin=subprocess.DEVNULL, + capture_output=True, + text=True, + timeout=TIMEOUT_SECONDS, + cwd=os.path.dirname(abs_path), + ) + except subprocess.TimeoutExpired: + return rel_path, False, f"timeout after {TIMEOUT_SECONDS}s" + except OSError as exc: + return rel_path, False, f"could not execute: {exc}" + if proc.returncode != 0: + tail = (proc.stderr or proc.stdout or "").strip().splitlines() + detail = tail[-1] if tail else "(no output)" + return rel_path, False, f"exit {proc.returncode}: {detail[:200]}" + return rel_path, True, "" + + +def main(argv=None): + parser = argparse.ArgumentParser( + description="Run `python3 <file> --help` on every .py in the " + "canonical tree and assert exit 0 (gate G8).", + formatter_class=argparse.RawDescriptionHelpFormatter, + epilog="Exit codes:\n" + " 0 all scripts passed --help, no stale exceptions\n" + " 1 one or more scripts failed the --help smoke test\n" + " 3 smoke_exceptions.txt lists files that no longer exist") + parser.add_argument("--json", action="store_true", + help="emit a JSON report instead of human-readable output") + parser.add_argument("--jobs", type=int, default=os.cpu_count() or 4, + help="parallel workers (default: CPU count)") + parser.add_argument("--root", default=REPO_ROOT, + help="repo root (default: parent of this script)") + args = parser.parse_args(argv) + + try: + exceptions = load_exceptions(EXCEPTIONS_FILE) + except OSError as exc: + print(f"ERROR: cannot read exceptions file: {exc}", file=sys.stderr) + return 2 + + all_files = find_python_files(args.root) + to_check = [f for f in all_files if f not in exceptions] + skipped = sorted(set(all_files) & set(exceptions)) + stale_exceptions = sorted(set(exceptions) - set(all_files)) + + failures = [] + with concurrent.futures.ThreadPoolExecutor(max_workers=args.jobs) as pool: + for rel_path, ok, detail in pool.map(smoke_one, to_check): + if not ok: + failures.append({"file": rel_path, "detail": detail}) + failures.sort(key=lambda f: f["file"]) + + if args.json: + print(json.dumps({ + "total": len(all_files), + "checked": len(to_check), + "passed": len(to_check) - len(failures), + "failed": failures, + "skipped_by_exception": [ + {"file": f, "reason": exceptions[f]} for f in skipped], + "stale_exceptions": stale_exceptions, + }, indent=2)) + else: + print(f"Scripts found: {len(all_files)}") + print(f"Checked: {len(to_check)}") + print(f"Passed: {len(to_check) - len(failures)}") + print(f"Failed: {len(failures)}") + print(f"Skipped (by-design exceptions): {len(skipped)}") + if failures: + print("\nFAILURES:") + for f in failures: + print(f" {f['file']}") + print(f" {f['detail']}") + if stale_exceptions: + print("\nERROR: exceptions listing files that no longer exist") + print("(remove them from scripts/smoke_exceptions.txt):") + for f in stale_exceptions: + print(f" {f}") + + if failures: + return 1 + # Only reached when no --help failures; a real failure (exit 1) takes + # precedence over allowlist hygiene (exit 3). + if stale_exceptions: + return 3 + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/scripts/sync-codebuff-skills.py b/scripts/sync-codebuff-skills.py new file mode 100755 index 00000000..1fa4dbb5 --- /dev/null +++ b/scripts/sync-codebuff-skills.py @@ -0,0 +1,51 @@ +#!/usr/bin/env python3 +""" +sync-codebuff-skills.py — Install claude-code-skills into Codebuff. + +Codebuff (https://codebuff.com) discovers agent skills from ~/.agents/skills/ +using the agentskills.io standard (SKILL.md with YAML frontmatter) — the same +format this repo uses, so no conversion is needed. + +This is a thin wrapper around sync-vibe-skills.py: identical discovery and +flat-layout sync logic, different default target directory. + +Usage: + python scripts/sync-codebuff-skills.py # full sync + python scripts/sync-codebuff-skills.py --verbose # show each skill + python scripts/sync-codebuff-skills.py --domain engineering # one domain + python scripts/sync-codebuff-skills.py --dry-run # preview only + python scripts/sync-codebuff-skills.py --copy # copy instead of symlink + +Codebuff skill directory: ~/.agents/skills/ +Skills land flat: ~/.agents/skills/<skill-name>/ +""" +from __future__ import annotations + +import importlib.util +import sys +from pathlib import Path + +CODEBUFF_SKILLS_DIR = Path.home() / ".agents" / "skills" + + +def load_vibe_module(): + """Load sync-vibe-skills.py (hyphenated filename) as a module.""" + path = Path(__file__).resolve().parent / "sync-vibe-skills.py" + spec = importlib.util.spec_from_file_location("sync_vibe_skills", path) + module = importlib.util.module_from_spec(spec) + spec.loader.exec_module(module) + return module + + +def main(): + vibe = load_vibe_module() + # Reuse the vibe CLI wholesale with a codebuff default target. + if not any(arg.startswith("--target") for arg in sys.argv[1:]): + sys.argv.extend(["--target", str(CODEBUFF_SKILLS_DIR)]) + vibe.VIBE_SKILLS_DIR = CODEBUFF_SKILLS_DIR + vibe.TOOL_NAME = "Codebuff" + vibe.main() + + +if __name__ == "__main__": + main() diff --git a/scripts/sync-gemini-skills.py b/scripts/sync-gemini-skills.py index 06f27c80..87514355 100644 --- a/scripts/sync-gemini-skills.py +++ b/scripts/sync-gemini-skills.py @@ -35,7 +35,8 @@ DOMAIN_MAP = { "business-operations": "business-operations", "commercial": "commercial", "research-ops": "research-ops", - "compliance-os": "compliance-os" + "compliance-os": "compliance-os", + "markdown-html": "markdown-html" } diff --git a/scripts/sync-hermes-skills.py b/scripts/sync-hermes-skills.py index d0d01a45..9b1a9818 100644 --- a/scripts/sync-hermes-skills.py +++ b/scripts/sync-hermes-skills.py @@ -50,6 +50,7 @@ DOMAIN_DIRS = [ "commercial", # v2.8.0 — pricing-strategist, deal-desk, partnerships-architect, channel-economics, commercial-policy, rfp-responder, commercial-forecaster + orchestrator "research-ops", # v2.9.0 — clinical-research, research-finance, market-research, product-research + orchestrator "compliance-os", # ISO 13485/27001, SOC 2, GDPR, FDA QSR, EU AI Act audit-prep + orchestrator + "markdown-html", # v2.10.x — orchestrator, design-system, md-document, md-review, md-slides ] diff --git a/scripts/sync-vibe-skills.py b/scripts/sync-vibe-skills.py index 378db9d5..33ddb64a 100755 --- a/scripts/sync-vibe-skills.py +++ b/scripts/sync-vibe-skills.py @@ -11,14 +11,25 @@ Both tools use the agentskills.io standard (SKILL.md with YAML frontmatter), so no format conversion is needed — just symlink the directories. Usage: - python scripts/sync-vibe-skills.py # full sync + python scripts/sync-vibe-skills.py # full sync (flat layout) python scripts/sync-vibe-skills.py --verbose # show each skill python scripts/sync-vibe-skills.py --domain engineering # one domain python scripts/sync-vibe-skills.py --dry-run # preview only python scripts/sync-vibe-skills.py --copy # copy instead of symlink + python scripts/sync-vibe-skills.py --nested # legacy namespaced layout Vibe skill directory: ~/.vibe/skills/ -Our skills land under: ~/.vibe/skills/claude-skills/<domain>/<skill-name>/ + +Layouts: + flat (default) ~/.vibe/skills/<skill-name>/ + Vibe only discovers skills one directory below each configured + skill path, so this is the layout Vibe actually picks up out of + the box (issue #748). Name collisions across domains are resolved + as <domain>-<skill-name>. + nested (--nested) ~/.vibe/skills/claude-skills/<domain>/<skill-name>/ + Legacy layout. Requires adding each domain directory to + `skill_paths` in ~/.vibe/config.toml, e.g.: + skill_paths = ["~/.vibe/skills/claude-skills/engineering"] """ from __future__ import annotations @@ -32,6 +43,7 @@ from pathlib import Path REPO_ROOT = Path(__file__).resolve().parent.parent VIBE_SKILLS_DIR = Path.home() / ".vibe" / "skills" TARGET_SUBDIR = "claude-skills" # namespace to avoid collisions with Vibe built-in skills +TOOL_NAME = "Vibe" # overridden by wrapper scripts (e.g. sync-codebuff-skills.py) # Domain directories that contain skills (each subdirectory with a SKILL.md) DOMAIN_DIRS = [ @@ -51,6 +63,7 @@ DOMAIN_DIRS = [ "commercial", # v2.8.0 — pricing-strategist, deal-desk, partnerships-architect, channel-economics, commercial-policy, rfp-responder, commercial-forecaster + orchestrator "research-ops", # v2.9.0 — clinical-research, research-finance, market-research, product-research + orchestrator "compliance-os", # ISO 13485/27001, SOC 2, GDPR, FDA QSR, EU AI Act audit-prep + orchestrator + "markdown-html", # v2.10.x — orchestrator, design-system, md-document, md-review, md-slides ] @@ -146,9 +159,33 @@ def read_frontmatter(skill_md): return {} -def sync_skill(skill, target_root, use_copy, verbose, dry_run): +def assign_flat_names(skills): + """Give each skill a unique directory name for the flat layout. + + First skill keeps its bare name; collisions across domains become + <domain>-<skill-name> (and gain a numeric suffix in the unlikely case + that still collides). + """ + taken: set = set() + for s in skills: + candidate = s["name"] + if candidate in taken: + candidate = f"{s['domain']}-{s['name']}" + n = 2 + while candidate in taken: + candidate = f"{s['domain']}-{s['name']}-{n}" + n += 1 + taken.add(candidate) + s["flat_name"] = candidate + return skills + + +def sync_skill(skill, target_root, use_copy, verbose, dry_run, nested): """Create a symlink or copy for one skill.""" - target = target_root / skill["domain"] / skill["name"] + if nested: + target = target_root / skill["domain"] / skill["name"] + else: + target = target_root / skill["flat_name"] if target.exists() or target.is_symlink(): if verbose: @@ -179,10 +216,11 @@ def sync_skill(skill, target_root, use_copy, verbose, dry_run): return "new" -def write_index(target_root, skills): - """Write a skills-index.json for quick lookup.""" +def write_index(target_root, skills, nested): + """Write a skills index JSON for quick lookup.""" index = { "source": "claude-code-skills", + "layout": "nested" if nested else "flat", "total_skills": len(skills), "domains": {}, } @@ -194,9 +232,12 @@ def write_index(target_root, skills): index["domains"][d].append({ "name": s["name"], "description": fm.get("description", ""), - "path": f"{d}/{s['name']}", + "path": f"{d}/{s['name']}" if nested else s["flat_name"], }) - index_path = target_root / "skills-index.json" + # In flat mode target_root is ~/.vibe/skills itself — use a namespaced + # filename so we never clobber anything Vibe owns. + filename = "skills-index.json" if nested else "claude-skills-index.json" + index_path = target_root / filename index_path.write_text(json.dumps(index, indent=2), encoding="utf-8") return index_path @@ -215,6 +256,12 @@ def main(): p.add_argument("--dry-run", action="store_true", help="Preview only, don't create files") p.add_argument("--copy", action="store_true", help="Copy files instead of symlink") p.add_argument("--json", action="store_true", help="JSON output") + p.add_argument( + "--nested", + action="store_true", + help="Legacy layout under claude-skills/<domain>/ — requires skill_paths " + "entries in ~/.vibe/config.toml; Vibe does NOT discover it by default", + ) p.add_argument( "--target", default=str(VIBE_SKILLS_DIR), @@ -222,9 +269,12 @@ def main(): ) args = p.parse_args() - target_root = Path(args.target).expanduser() / TARGET_SUBDIR + base = Path(args.target).expanduser() + target_root = base / TARGET_SUBDIR if args.nested else base domains = [args.domain] if args.domain else None skills = discover_skills(REPO_ROOT, domains) + if not args.nested: + assign_flat_names(skills) if not skills: msg = f"No skills found in {REPO_ROOT}" @@ -239,18 +289,19 @@ def main(): counts = {"new": 0, "skip": 0, "would": 0} for s in skills: - result = sync_skill(s, target_root, args.copy, args.verbose, args.dry_run) + result = sync_skill(s, target_root, args.copy, args.verbose, args.dry_run, args.nested) counts[result] += 1 # Write index if not args.dry_run: - idx_path = write_index(target_root, skills) + idx_path = write_index(target_root, skills, args.nested) else: - idx_path = target_root / "skills-index.json" + idx_path = target_root / ("skills-index.json" if args.nested else "claude-skills-index.json") summary = { "status": "ok", "target": str(target_root), + "layout": "nested" if args.nested else "flat", "total_skills": len(skills), "new": counts["new"], "skipped": counts["skip"], @@ -271,7 +322,12 @@ def main(): if not args.dry_run: print(f" Index: {idx_path}") print() - print("Vibe will discover these skills via /skills or /<skill-name>.") + if args.nested: + print(f"NOTE: the nested layout is NOT discovered by {TOOL_NAME} out of the box.") + print("Add each domain to skill_paths in ~/.vibe/config.toml, e.g.:") + print(' skill_paths = ["~/.vibe/skills/claude-skills/engineering"]') + else: + print(f"{TOOL_NAME} will discover these skills via /skills or /<skill-name>.") print("No format conversion needed — both tools use agentskills.io SKILL.md standard.") diff --git a/templates/CLAUDE.md b/templates/CLAUDE.md index 4748d9a5..3d61f818 100644 --- a/templates/CLAUDE.md +++ b/templates/CLAUDE.md @@ -12,7 +12,7 @@ This guide explains the template system for agents, commands, and standardized w ### Agent Templates -**Location:** `templates/agent-template.md` (when created) +**Location:** `templates/agent-template.md` **Usage:** Starting point for creating new cs-* agents @@ -24,29 +24,9 @@ This guide explains the template system for agents, commands, and standardized w **When to Use:** Creating any new agent in `agents/` directory -### Command Templates +### Command Templates and Workflow Templates -**Location:** `templates/command-template.md` (when created) - -**Usage:** Creating new slash commands - -**Contains:** -- Command structure -- Argument parsing patterns -- Help documentation format - -**When to Use:** Creating slash commands in `commands/` directory - -### Workflow Templates - -**Location:** `templates/workflow-template.md` (when created) - -**Usage:** Documenting standard workflows across skills - -**Contains:** -- Step-by-step format -- Expected outputs -- Error handling patterns +Not yet created. There is no command template or workflow template file in `templates/` today — when creating slash commands, copy an existing command in `commands/` (e.g. `commands/cs-backend-review.md` for the argument-hint + gate pattern) instead of looking for a template here. ## Template Usage Pattern diff --git a/templates/agent-template.md b/templates/agent-template.md index 1b564a37..f26c4a11 100644 --- a/templates/agent-template.md +++ b/templates/agent-template.md @@ -1,6 +1,6 @@ --- name: cs-agent-name -description: One-line description of what this agent does (keep under 150 characters) +description: What this agent does, followed by trigger phrasing. MUST include a "Use when…" (or "Spawn when…" / "Invoke via…") clause plus at least 1 concrete trigger example. Up to 1024 characters allowed — completeness of triggers beats brevity. Example — "Senior backend engineer agent. Use when designing APIs, picking a database, or extracting a service from a monolith (e.g., 'help me choose between Postgres and DynamoDB')." skills: skill-folder-name domain: domain-name model: sonnet @@ -14,6 +14,9 @@ tools: [Read, Write, Bash, Grep, Glob] 1. Replace "cs-agent-name" with your agent's name (use kebab-case with cs- prefix) 2. Replace "Agent Name" with the display name (Title Case) + 2b. Write the description with trigger phrasing: a "Use when…" clause + at least + 1 concrete example invocation. Descriptions may be up to 1024 characters — + do NOT compress triggers away to save space. 3. Fill in all sections below following the structure 4. Test all relative paths (../../) before committing 5. Ensure minimum 3 workflows documented @@ -289,7 +292,7 @@ python ../../domain-skill/skill-name/scripts/tool.py current-data.csv > report-$ Explain how agents complement each other. --> -- [cs-related-agent](../domain/cs-related-agent.md) - How this agent relates (e.g., "Provides strategic context for tactical execution") +- [cs-related-agent](../<domain>/cs-related-agent.md) - How this agent relates (e.g., "Provides strategic context for tactical execution") - [cs-another-agent](cs-another-agent.md) - How this agent relates (same directory) - [cs-future-agent](cs-future-agent.md) - Planned agent (mark as "planned") @@ -301,7 +304,7 @@ python ../../domain-skill/skill-name/scripts/tool.py current-data.csv > report-$ --> - **Skill Documentation:** [../../domain-skill/skill-name/SKILL.md](../../domain-skill/skill-name/SKILL.md) -- **Domain Guide:** [../../domain-skill/CLAUDE.md](../../domain-skill/CLAUDE.md) +- **Domain Guide:** [../../<domain-skill>/CLAUDE.md](../../<domain-skill>/CLAUDE.md) - **Agent Development Guide:** [../CLAUDE.md](../CLAUDE.md) ---