mirror of
https://github.com/alirezarezvani/claude-skills.git
synced 2026-08-28 04:24:58 +00:00
feat(skills): wave-3 optimization — domain overhauls per newgen audit
marketing: context-file unified on .claude/product-marketing-context.md;
ai-seo merged into aeo (2 new cited references, folder deleted); index +
marketing-ops routers rebuilt honestly; 24 orphan scripts wired with exact
CLIs; prompt-engineer-toolkit stub references rewritten with cited content;
Meta 20%-rule + GA4 terminology freshness; 5 zips + 3 planning docs removed
c-level-advisor: role registry 9->14 across all 6 routing surfaces; decision
memory unified on ~/.claude/decisions/{raw,approved}; onboarding schema
canonicalized; 12 phantom commands resolved; index repaired (33/37/68 real
counts); ma-playbook sourced + verification loop; 28 trigger descriptions
engineering(+team): agent-designer 279->76 lines and rag-architect 318->71
lines rebuilt around their tools (stale ada-002/pricing gone); release-manager
merged into changelog-generator (version_bumper + hotfix refs moved, crashing
release_planner dropped); 6 skills' orphan scripts wired; ms365 tools gained
real CLIs; 5 brochure skills de-filled; 4 unreferenced zips removed;
bundle counts trued (25->37, 23->32); 18 trigger descriptions
product/research/compliance/bizops: apple-hig-expert rebuilt around
hig_checker's real CLI with web-verified facts; notebooklm re-verified against
live product; 5 index skills converted to honest routers; research-summarizer
repaired with explicit lane statement; 8 over-1024 descriptions compressed;
9 sub-skills gained fenced CLI examples; GDPR one-month (Art. 12(3)) with
calendar-month deadline math; MDR PSUR table per Art. 86(1); 12 ra-qm zips
removed; 24 trigger descriptions
Verified: check_paths 0 findings; check_dual_publish 0 drifted; smoke 581/581;
check_plugin_json 77 OK; compileall rc=0; all descriptions <=1024 chars
https://claude.ai/code/session_019AJddAL1NADWMXsy1qNPQF
This commit is contained in:
Claude
parent
7a3aca8640
commit
aecfb8e0bb
221 changed files with 2513 additions and 8883 deletions
|
|
@ -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"
|
||||
]
|
||||
}
|
||||
}
|
||||
|
|
@ -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/skills/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
|
||||
# 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
|
||||
python3 business-growth/skills/revenue-operations/scripts/pipeline_analyzer.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.
|
||||
|
|
|
|||
|
|
@ -83,6 +83,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 &
|
||||
|
|
|
|||
|
|
@ -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 <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*.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
name: "boardroom"
|
||||
description: "/cs:boardroom <brief> — 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 <brief> — 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
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
name: "brief"
|
||||
description: "/cs:brief <topic> — Generate a one-page strategy brief from an office-hours intake. First step in the strategic sprint pipeline."
|
||||
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 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-<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
|
||||
|
|
|
|||
|
|
@ -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.)
|
||||
|
|
@ -32,9 +32,9 @@ Each agent wraps an existing c-level skill and adds:
|
|||
|
||||
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,7 +90,7 @@ 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
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
name: "caio-review"
|
||||
description: "/cs:caio-review <plan> — 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 <plan> — 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
|
||||
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
name: "cco-review"
|
||||
description: "/cs:cco-review <plan> — 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 <plan> — 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
|
||||
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
name: "cdo-review"
|
||||
description: "/cs:cdo-review <plan> — 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 <plan> — 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
|
||||
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
name: "cfo-review"
|
||||
description: "/cs:cfo-review <plan> — Numerate-skeptic interrogation of any plan that touches money. Unit economics, runway, dilution, capital allocation."
|
||||
description: "/cs:cfo-review <plan> — 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
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
name: "ciso-review"
|
||||
description: "/cs:ciso-review <plan> — Risk-paranoid interrogation of any plan that touches data, compliance, or production access."
|
||||
description: "/cs:ciso-review <plan> — 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
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
name: "cmo-review"
|
||||
description: "/cs:cmo-review <plan> — Narrative-first interrogation of positioning, ICP, message house, and channel mix."
|
||||
description: "/cs:cmo-review <plan> — 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
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
name: "cpo-review"
|
||||
description: "/cs:cpo-review <plan> — JTBD-driven interrogation of product roadmap, PMF signal, and portfolio focus."
|
||||
description: "/cs:cpo-review <plan> — 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
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
name: "cro-review"
|
||||
description: "/cs:cro-review <plan> — Pipeline-paranoid interrogation of revenue, win rate, NRR, and ramp time."
|
||||
description: "/cs:cro-review <plan> — 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
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
name: "cross-eval"
|
||||
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 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
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
name: "cto-review"
|
||||
description: "/cs:cto-review <plan> — Architecture and scaling interrogation. Tech debt, scaling cliffs, team scaling, build-vs-buy."
|
||||
description: "/cs:cto-review <plan> — 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
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
name: "decide"
|
||||
description: "/cs:decide <memo> — Log a decision to two-layer memory via decision-logger. Approved memo becomes durable; raw transcripts kept for reference."
|
||||
description: "/cs:decide <memo> — 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
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
name: "execute"
|
||||
description: "/cs:execute <decision> — Generate a 90-day execution plan with weekly milestones, DRIs, and check-in cadence from an approved decision."
|
||||
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 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
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
name: "founder-mode"
|
||||
description: "/cs:founder-mode <question> — 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 <question> — 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)
|
||||
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
name: "freeze"
|
||||
description: "/cs:freeze <decision> <days> — Lock a strategic decision for a cooldown period to prevent impulse reversal. Mirrors gstack's safety primitives for the business layer."
|
||||
description: "/cs:freeze <decision> <days> — 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
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
name: "gc-review"
|
||||
description: "/cs:gc-review <plan> — General Counsel interrogation of contracts, IP, regulatory, term sheets, and employment-law surface."
|
||||
description: "/cs:gc-review <plan> — 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
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
name: "office-hours"
|
||||
description: "/cs:office-hours <topic> — YC-style 6-question founder interrogation before any advice. Forces clarity on problem, customer, distribution, defensibility, capital, and founder fit."
|
||||
description: "/cs:office-hours <topic> — 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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
name: "post-mortem"
|
||||
description: "/cs:post-mortem <decision> — Honest retrospective on an executed decision, scored against original assumptions and dissent. Closes the strategic sprint loop."
|
||||
description: "/cs:post-mortem <decision> — 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
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
name: "vpe-review"
|
||||
description: "/cs:vpe-review <plan> — Throughput-first VP of Engineering interrogation of any plan that touches delivery, eng hiring, team structure, or production discipline."
|
||||
description: "/cs:vpe-review <plan> — 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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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-<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 |
|
||||
|
|
@ -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:**
|
||||
```
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
|
|
@ -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):**
|
||||
```
|
||||
|
|
@ -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-<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` → "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
|
||||
|
|
@ -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 |
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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]
|
||||
|
||||
|
|
|
|||
|
|
@ -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-<slug>.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]-<slug>.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: <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` 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
|
||||
|
|
|
|||
|
|
@ -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,7 +152,9 @@ 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/`.
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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 |
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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-<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
|
||||
|
|
@ -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]-<slug>.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-<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
|
||||
|
||||
---
|
||||
|
|
@ -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-<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
|
||||
```
|
||||
|
||||
---
|
||||
|
|
|
|||
|
|
@ -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",
|
||||
|
|
|
|||
|
|
@ -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:** <!-- DATE of the previous decision on this topic, if any -->
|
||||
**Superseded by:** <!-- Leave blank. Will be filled in if a later decision overrides this. -->
|
||||
|
||||
**Raw transcript:** memory/board-meetings/[YYYY-MM-DD]-raw.md
|
||||
**Raw transcript:** ~/.claude/decisions/raw/[YYYY-MM-DD]-<slug>.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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
Binary file not shown.
Binary file not shown.
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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,7 +20,7 @@ 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
|
||||
|
||||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
@ -467,10 +469,3 @@ python scripts/pir_generator.py --incident assets/sample_incident_pir_data.json
|
|||
- 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.
|
||||
|
|
|
|||
|
|
@ -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())
|
||||
|
|
@ -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()
|
||||
File diff suppressed because it is too large
Load diff
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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()
|
||||
|
|
|
|||
|
|
@ -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()
|
||||
|
|
|
|||
|
|
@ -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()
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
```
|
||||
|
|
|
|||
Binary file not shown.
Binary file not shown.
|
|
@ -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",
|
||||
|
|
|
|||
|
|
@ -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 |
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
- `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
|
||||
|
|
|
|||
|
|
@ -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",
|
||||
|
|
|
|||
|
|
@ -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"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
|
@ -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.
|
||||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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.*
|
||||
## 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.
|
||||
|
|
|
|||
|
|
@ -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,7 +20,7 @@ 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
|
||||
|
||||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
Some files were not shown because too many files have changed in this diff Show more
Loading…
Add table
Reference in a new issue