swe-workflow-skills 0.1.0 → 0.3.0

package/skills/resilience-engineering/evals/evals.json

@@ -0,0 +1,40 @@
+{
+  "skill_name": "resilience-engineering",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Our e-commerce platform runs on one Postgres instance, a Node API, and Redis, all in a single AWS availability zone. Leadership asked: 'what happens if AWS has a bad day?' Design our resilience strategy.",
+      "expected_output": "Runs failure-mode analysis per dependency (down/slow/partial/data-corruption, single points of failure), sets explicit targets first (availability tier, RTO/RPO per store) noting cost scales with the numbers, applies stability patterns at boundaries (timeouts, retries with backoff+jitter on idempotent ops, circuit breakers, graceful degradation deciding in advance what turns off), designs data recovery (automated backups, isolated copy, scheduled restore tests), and proposes verification via small chaos experiments and a game day rather than declaring the design done",
+      "assertions": [
+        "Performs failure-mode analysis across the dependencies, covering slow/partial failures and data corruption — not just total outage — and identifies single points of failure",
+        "Sets explicit RTO/RPO and availability targets before choosing mechanisms, noting that cost scales with the targets (backups vs standby vs multi-AZ/region)",
+        "Applies concrete stability patterns: timeouts, retries with backoff and jitter (idempotent only), circuit breakers, and pre-decided graceful degradation",
+        "Treats backups as unproven until restored — schedules restore testing and keeps a copy isolated from the blast radius",
+        "Proposes verifying with chaos experiments (hypothesis-driven, small blast radius) and/or a game day rehearsing the runbooks"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "We already have retries everywhere — every service retries failed calls 5 times. Last month a 30-second blip in our auth service somehow became a 45-minute full-platform outage. Make us more resilient.",
+      "expected_output": "Diagnoses the retry storm / cascade: unbudgeted retries amplified load (5 retries per hop compound multiplicatively across the chain), likely no timeouts or breakers so threads piled onto a hung dependency; prescribes retry budgets, exponential backoff with jitter, idempotency checks, circuit breakers to fail fast, load shedding at the edge, and bulkheads to contain blast radius — showing that MORE retrying is the opposite of resilience here",
+      "assertions": [
+        "Identifies the naive retries as an amplifier (retry storm / cascading failure), including how retries compound across call-chain hops",
+        "Recommends retry budgets and exponential backoff with jitter, restricted to idempotent operations, instead of fixed retry counts",
+        "Adds circuit breakers and timeouts so a hung or flapping dependency fails fast instead of tying up resources",
+        "Recommends load shedding/backpressure and/or bulkheads to contain the blast radius of a degraded dependency",
+        "Frames the fix as controlling and bounding retries — explicitly countering the assumption that more retrying equals more resilience"
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "Production is down RIGHT NOW — the primary database failed over but the app servers are still erroring and customers can't check out. What do we do?",
+      "expected_output": "Recognizes an active incident under time pressure — hands off to incident-response for triage/mitigation/comms rather than starting a peacetime resilience design; may note that post-recovery, the failure feeds back into failure-mode analysis and a game-day-style review via retrospective",
+      "assertions": [
+        "Recognizes this as an active production incident, not a resilience design exercise",
+        "Refers to the incident-response skill/workflow for triage, mitigation, and communication",
+        "Does not respond with a peacetime workflow (failure-mode analysis, chaos experiments, DR design) as the immediate answer",
+        "States or implies the boundary: resilience-engineering is peacetime design and rehearsal; incident-response handles the live fire (with learnings looping back afterward)"
+      ]
+    }
+  ]
+}

package/skills/security-audit/SKILL.md

@@ -1,7 +1,10 @@
 ---
 name: security-audit
-description: "Comprehensive security analysis — OWASP Top 10, auth/authz flows, injection vulnerabilities, data exposure, secrets detection, dependency CVEs, hardening recommendations. Triggers: security audit, vulnerability, is this secure, security review, pentest prep, OWASP, harden this, check for vulnerabilities, injection, XSS, CSRF, auth security."
+description: "Comprehensive security analysis — OWASP Top 10, auth/authz flows, injection vulnerabilities, data exposure, secrets detection, dependency CVEs, hardening recommendations. Reviews EXISTING code/config — design-time analysis of a system not yet built → threat-modeling."
+when_to_use: "Triggers: security audit, vulnerability, is this secure, security review, pentest prep, OWASP, harden this, check for vulnerabilities, injection, XSS, CSRF, auth security."
 model: opus
+context: fork
+agent: general-purpose
 allowed-tools: Read, Grep, Glob, Write, Edit, WebFetch, WebSearch
 ---
 
@@ -11,7 +14,7 @@ Perform a structured security assessment of an application. This skill goes far
 
 ## Scope Boundary
 
-This skill analyzes code, configuration, and architecture for security vulnerabilities through static analysis and design review. It does not replace penetration testing, but it prepares code for one by catching the issues a pentester would find.
+This skill analyzes code, configuration, and architecture for security vulnerabilities through static analysis and design review. It does not replace penetration testing, but it prepares code for one by catching the issues a pentester would find. It is the *reactive* half of the pair: for design-time analysis of a system that isn't built yet (trust boundaries, STRIDE, abuse cases), use `threat-modeling` — and when a threat model exists, use it as this audit's checklist.
 
 ## ⛔ The Iron Law
 
@@ -31,7 +34,7 @@ Before reviewing code line by line, map what's exposed:
 - **External integrations**: Third-party APIs, OAuth providers, payment processors
 - **Infrastructure**: Cloud services, databases, caches, queues
 
-Present the attack surface map to the user. Gaps in understanding here mean gaps in the audit.
+Record the attack surface map as the first section of the report — gaps in understanding here mean gaps in the audit, so anything you could not map (unreachable config, undocumented integrations) goes under Open questions rather than being assumed safe.
 
 ### Step 2: Assess by OWASP Top 10
 
@@ -113,6 +116,14 @@ Suggest using the `dependency-management` skill for remediation planning.
 
 Output the audit report using the template at [templates/security-report.md](templates/security-report.md). Organize findings by severity, with Critical and High items first.
 
+**Write the full report to a file** (default a gitignored location, e.g.
+`.local/security-audit-<date>.md`) and state its path in your final summary — this
+skill runs in a forked context: only the summary returns, everything unwritten is
+lost. The summary must lead with the Critical/High count. Judgment calls that need
+user input (unclear trust boundary, whether a data store is in scope, unverifiable
+control) go in an **Open questions** section of the report — never silently assumed
+safe.
+
 ## What This Skill Does NOT Cover
 
 - Runtime penetration testing (requires running the application)

package/skills/skill-router/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: skill-router
-description: "Orchestrator and entry point for the swe-workflow skills library — consult FIRST when starting any non-trivial software task; most skills load name-only and only activate when invoked here. Triggers: starting a feature, planning, an architecture or design decision, implementing, debugging, reviewing, refactoring, testing, security, deployment, an incident, shipping, or unsure which skill fits. Routes intent to the right skill(s) and invokes them by name; shows the Golden Path chains."
+description: "Orchestrator and entry point for the swe-workflow skills library — consult FIRST when starting any non-trivial software task; most skills load name-only and only activate when invoked here. Routes intent to the right skill(s) and invokes them by name; shows the Golden Path chains."
+when_to_use: "Triggers: starting a feature, planning, an architecture or design decision, implementing, debugging, reviewing, refactoring, testing, security, deployment, an incident, shipping, or unsure which skill fits."
 model: haiku
 allowed-tools: Read, Grep, Glob, Skill
 ---
@@ -87,7 +88,9 @@ installed skill by name, regardless of role.
 ## Catalog by SDLC phase
 
 ### Plan & Define
+- **brainstorming** — divergent Socratic ideation *before* a spec exists; opens options, then hands off
 - **feature-planning** — break a feature into scoped tasks, acceptance criteria, dependencies
+- **build-vs-buy** — build in-house vs vendor/SaaS vs adopt OSS: TCO, lock-in, exit costs
 - **prd-writing** — write a PRD / RFC / tech spec to align on the WHAT and WHY
 - **project-proposal** — business case / budget / go-no-go before a project starts
 - **strategic-review** — vision, positioning, defensible wedge, live competitive/market analysis before going public
@@ -102,14 +105,19 @@ installed skill by name, regardless of role.
 - **ui-ux-design** — user flows, wireframes, loading/error/empty states, responsive
 - **frontend-architecture** — component hierarchy, state management, design tokens
 - **accessibility-design** — WCAG, ARIA, keyboard nav, focus, screen readers
+- **threat-modeling** — design-time security: trust boundaries, STRIDE, abuse cases, mitigations
+- **compliance-privacy** — GDPR/SOC 2 obligations: data mapping, retention/deletion, DSRs, controls
 - **configuration-strategy** — env config, secrets management, feature-flag hierarchy
 - **dependency-impact-analysis** — blast radius of a change *before* implementing
 - **dependency-management** — evaluate, audit (CVEs), and upgrade libraries
 
 ### Build & Test
+- **plan-execution** — execute an APPROVED plan: checkpoints, verification evidence, drift → re-plan
 - **tdd-workflow** — NEW code, test-first, red-green-refactor
 - **test-suite-design** — add tests to EXISTING code, coverage strategy
 - **test-data-strategy** — factories, synthetic data, property-based, contract testing
+- **browser-verification** — drive the real UI to prove a web change works: console/network/state evidence
+- **subagent-orchestration** — fan work out across subagents/worktrees; verify and synthesize results
 - **git-workflow** — commit messages, PR descriptions, branching strategy
 - **project-documentation** — README, contributing guide, changelog, docstrings
 
@@ -120,6 +128,8 @@ installed skill by name, regardless of role.
 - **refactoring** — systematic, test-protected code improvement
 - **technical-debt-review** — codebase health, hotspots, remediation roadmap
 - **project-review** — whole-project execution health: scope alignment, roadmap adherence, implementation maturity, evidence-it-works
+- **code-archaeology** — understand unfamiliar/legacy code first: history mining, tracing, characterization tests
+- **dx-audit** — developer-experience audit: feedback loops, CI wait, flakes, onboarding, tooling friction
 
 ### Diagnose & Fix
 - **bug-investigating** — systematic debugging, reproduce → isolate → hypothesize → verify
@@ -129,27 +139,50 @@ installed skill by name, regardless of role.
 - **rollback-strategy** — safe rollback plans, irreversible-change detection
 - **containerization** — Dockerfiles, docker-compose, Kubernetes manifests
 - **cicd-pipeline** — CI/CD pipelines, quality gates (GitHub Actions, GitLab CI)
+- **release-management** — semver, changelog, tagging, publish gates, registry publishing, release automation (right-sized to the project)
 - **infrastructure-as-code** — Terraform, CloudFormation, Pulumi, CDK
 - **deployment-repo** — GitOps polyrepo orchestration, version pinning, promotion
 - **gitops-delivery** — ArgoCD / Flux declarative delivery, drift detection
 - **observability-design** — SLI/SLO/SLA, OpenTelemetry, structured logging, alerting
+- **resilience-engineering** — failure modes, stability patterns, chaos experiments, DR/RTO/RPO, game days
+- **finops-cost-optimization** — cloud spend: allocation, unit economics, rightsizing, commitments, egress
 - **incident-response** — ACTIVE production incident: triage, mitigate, communicate
 
+### Mobile
+- **mobile-architecture** — platform choice, navigation, offline-first/sync, state, push, fleet constraints
+- **mobile-release** — signing, store review, staged rollouts, no-rollback playbook, beta channels
+
 ### Reflect
 - **retrospective** — sprint retros, project / incident post-mortems, action items
 
 ### MLOps
-- **ml-pipeline-design** — training & data pipelines, feature engineering, orchestration
+- **ml-pipeline-design** — ML training & feature pipelines, point-in-time correctness, orchestration
 - **ml-experiment-tracking** — MLflow / W&B / DVC, run comparison, reproducibility
 - **ml-model-deployment** — serving, monitoring, drift detection, safe rollouts
 
+### AI / LLM Apps
+- **llm-app-engineering** — prompt/context engineering, RAG architecture, agent design, memory
+- **ai-evaluation** — golden datasets, RAG metrics, LLM-as-judge design, eval gates in CI, online A/B
+
+### Data Engineering
+- **data-pipeline-design** — batch/streaming ELT, dbt layering, Airflow/Dagster, idempotency, backfill
+- **data-quality** — dbt tests, expectations, data contracts, freshness, lineage / blast radius
+
+### Data Science
+- **exploratory-data-analysis** — profile an unfamiliar dataset: missingness structure, distributions, leakage, hypotheses
+- **statistical-analysis** — hypothesis tests, experiment design/power, confidence intervals, multiple-comparison discipline
+- **notebook-to-production** — refactor analysis notebooks to tested, parameterized, scheduled production code
+
 ## Golden Path workflow chains
 
 When work spans phases, chain skills rather than improvising:
 
 **New feature**
-`feature-planning` → `architecture-design` (if structural) → `data-modeling`
-(if schema) → `tdd-workflow` → `code-reviewing` → `deployment-checklist`
+`brainstorming` (if the idea is still fuzzy) → `feature-planning` →
+`architecture-design` (if structural) → `data-modeling` (if schema) →
+`threat-modeling` (if new trust boundaries) → `plan-execution` (work the
+approved plan; wraps `tdd-workflow` per task) → `code-reviewing` →
+`deployment-checklist`
 
 **Bug / incident**
 `incident-response` (if prod is down) → `bug-investigating` → `tdd-workflow`
@@ -159,6 +192,26 @@ When work spans phases, chain skills rather than improvising:
 `technical-debt-review` → `refactoring` → `dependency-impact-analysis`
 (blast radius) → `test-suite-design` (if coverage is thin)
 
+**Ship a release**
+`git-workflow` (commits carry the bump intent) → `release-management` (version,
+changelog, tag, publish gate, registry) → `deployment-checklist` (if it deploys) →
+`rollback-strategy`. `cicd-pipeline` automates the gate as a pipeline stage.
+App-store releases (signing, review, staged rollout) → `mobile-release`.
+
+**LLM feature**
+`feature-planning` → `llm-app-engineering` (prompt/RAG/agent design) →
+`ai-evaluation` (golden set, judge, CI gate) → `deployment-checklist`.
+`ml-model-deployment` joins when serving your own model.
+
+**Analytics / data pipeline**
+`data-pipeline-design` (ELT, layering, orchestration) → `data-modeling`
+(marts schema) → `data-quality` (tests, contracts, freshness) →
+`observability-design` (pipeline SLOs, alerting).
+Notebook to production: `exploratory-data-analysis` (understand the data) →
+`statistical-analysis` (test the hypotheses) → `notebook-to-production`
+(modules, tests, scheduling); if the notebook trains a model →
+`ml-pipeline-design` instead.
+
 **Pre-public / pre-milestone review**
 `strategic-review` (vision, positioning, market) → `project-review` (scope,
 roadmap, implementation, evidence) → synthesis → `artifact-design` (interactive

package/skills/statistical-analysis/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: statistical-analysis
+description: "Design and analyze experiments and statistical tests — test selection with stated assumptions, sample size and power, effect sizes and confidence intervals over bare p-values, and pitfall discipline (multiple comparisons, p-hacking, peeking/optional stopping). Owns experiment statistics generally; live A/B evaluation of AI/LLM apps (quality metrics, judges, feedback) → ai-evaluation."
+when_to_use: "Triggers: hypothesis test, t-test, chi-square, p-value, statistical significance, confidence interval, sample size, power analysis, design an experiment, A/B test, multiple comparisons, is this difference real."
+model: opus
+allowed-tools: Read, Grep, Glob, Write, Edit, Bash
+---
+
+# Statistical Analysis
+
+Get the statistics of a question right — the test, its assumptions, the
+uncertainty, and the traps — so a decision rests on evidence rather than on a
+lone p-value. The deliverable is a decision-ready answer: effect size,
+uncertainty, assumptions, caveats.
+
+## Workflow
+
+### 1. Frame the question as a hypothesis
+
+State the null and alternative in plain words before touching data ("the new
+flow's conversion equals the old flow's"). Identify the unit of analysis
+(user? session? order?) — mismatching it with the randomization unit silently
+breaks independence.
+
+### 2. Design before data (when the experiment hasn't run yet)
+
+- Choose the primary metric and **pre-register it** — one primary, the rest
+  explicitly secondary/exploratory.
+- Compute **sample size from power**: minimum detectable effect worth acting
+  on, α (typically 0.05), power (typically 0.8). Run until n is reached —
+  don't stop early on a good-looking result.
+- Randomize at the unit you'll analyze; check the split is balanced on key
+  covariates.
+
+### 3. Choose the test and state its assumptions
+
+Match the test to the data (two proportions → two-proportion z-test / χ²;
+means → t-test or its nonparametric fallback; counts → Poisson/χ²; paired data
+→ paired tests). **Always state the assumptions and check the ones you can**:
+independence of observations (the usual casualty — repeated measures per user,
+network effects, shared fixtures), adequate counts for normal approximations
+(rule of thumb: ≥10 successes and failures per arm), variance assumptions for
+t-tests. If an assumption fails, switch tests rather than pretending.
+
+### 4. Report effect size and interval, not a verdict
+
+Work the actual numbers. Report the effect (absolute and relative difference)
+with a **confidence interval**, and the p-value as supporting detail — never a
+bare "significant/not significant". The CI is what the decision needs: a CI of
+[+0.1%, +1.7%] and a CI of [+0.8%, +1.0%] are both "significant" and mean very
+different things.
+
+### 5. Run the pitfall gate
+
+Before reporting anything, check:
+
+- **Peeking / optional stopping**: was n fixed in advance? Repeatedly testing
+  as data arrives inflates false positives badly. If peeking happened, say so
+  and treat the result as suggestive (or use sequential methods designed for it).
+- **Multiple comparisons**: k tests at α=0.05 ≈ k/20 false positives expected.
+  Correct (Holm/Bonferroni for strict control, Benjamini-Hochberg FDR when many
+  metrics), and label post-hoc findings as exploratory — they are hypotheses
+  for the *next* experiment, not wins from this one.
+- **Subgroup fishing**: subgroup effects found after the fact need the same
+  exploratory label and a confirmatory follow-up.
+- **Survivorship / selection**: does the analyzed sample still represent the
+  population the decision is about?
+
+### 6. Translate to the decision
+
+Distinguish statistical from practical significance: a real +0.05% lift may
+not pay for the complexity; a non-significant result with a wide CI is "we
+don't know yet", not "no effect". Give the ship/don't-ship framing with the
+caveats attached, and say what additional data would resolve remaining
+uncertainty.
+
+## Principles
+
+- **KISS**: a well-checked z-test beats a fancy model with unexamined
+  assumptions.
+- **Pre-register or label**: every metric is either declared up front or
+  reported as exploratory — no third category.
+- **Uncertainty is the product**: any answer without an interval is opinion
+  with extra steps.
+
+## Cross-skill boundaries
+
+- Live A/B testing of an AI/LLM app — defining answer quality, LLM-as-judge,
+  human feedback loops, eval gates → **ai-evaluation** (this skill still owns
+  the underlying experiment statistics if asked).
+- Generating the hypotheses to test → **exploratory-data-analysis**.
+- Tracking and comparing model-training runs → **ml-experiment-tracking**.
+- Defining what business metric to move → **metrics-and-okrs**.

package/skills/statistical-analysis/evals/evals.json

@@ -0,0 +1,43 @@
+{
+  "skill_name": "statistical-analysis",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "We ran an experiment: 2,400 users saw the new checkout flow and converted at 6.8%; 2,350 saw the old one and converted at 5.9%. My PM wants to ship it today — is this difference real? How confident can we be?",
+      "expected_output": "Should treat this as a two-proportion hypothesis test: state the null, run or outline the test with the actual numbers, report a confidence interval on the difference, ask whether the sample size was fixed in advance (peeking), and separate statistical from practical significance before giving a ship recommendation.",
+      "assertions": [
+        "Frames the question as a hypothesis test (two-proportion z-test or equivalent) and states the null hypothesis",
+        "Works the actual numbers given (or sets up the exact computation) rather than answering qualitatively",
+        "Reports uncertainty as a confidence interval on the difference, not only a p-value or a yes/no verdict",
+        "Asks or checks whether the sample size was fixed in advance and flags the peeking/optional-stopping problem",
+        "Distinguishes statistical significance from practical/business significance",
+        "States the assumptions behind the chosen test (independent samples, adequate counts)",
+        "Gives a clear ship/don't-ship framing with the statistical caveats attached"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "We measured 20 different metrics in our experiment and 2 came out significant at p < 0.05. Which ones should we report as wins?",
+      "expected_output": "Should identify the multiple-comparisons problem (about one false positive is expected by chance at that rate), recommend a correction (Holm/Bonferroni or FDR), distinguish pre-registered primary metrics from exploratory ones, and treat the 2 hits as hypotheses for a confirmatory follow-up — not report them as wins.",
+      "assertions": [
+        "Identifies the multiple-comparisons problem explicitly — with 20 tests, roughly one false positive at p < 0.05 is expected by chance",
+        "Recommends a concrete correction (Bonferroni, Holm, or FDR / Benjamini-Hochberg) and notes the trade-off between them",
+        "Warns against reporting the 2 nominal hits as wins (p-hacking / cherry-picking)",
+        "Distinguishes pre-registered primary metrics from exploratory findings",
+        "Recommends treating the surviving hits as hypotheses for a follow-up confirmatory experiment",
+        "Does not simply declare the two significant metrics real effects"
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "We're about to launch a new system prompt for our support chatbot and want to A/B test it live against the current one to see which gives better answers. Can you set this up?",
+      "expected_output": "Should recognize this as online A/B evaluation of an LLM app and hand off to the ai-evaluation skill for the evaluation design (answer-quality metrics, LLM-as-judge or human feedback, eval gates); statistical-analysis contributes at most the underlying experiment statistics (sample size, significance), not the AI evaluation design.",
+      "assertions": [
+        "Recognizes this as AI-app evaluation territory and hands off to or invokes the ai-evaluation skill",
+        "Raises AI-specific measurement concerns (defining answer quality, LLM-as-judge or human feedback signals) rather than treating it as a pure two-sample statistics problem",
+        "Does not respond with only a generic A/B test design ignoring how answer quality gets measured",
+        "If it retains anything, retains only the experiment statistics (sample size, significance testing) as this skill's contribution"
+      ]
+    }
+  ]
+}

package/skills/strategic-review/SKILL.md

@@ -1,7 +1,10 @@
 ---
 name: strategic-review
-description: "Review a project's strategic position before going public, launching, or raising — vision, mission, value proposition, scope positioning, the defensible wedge, and a live competitive / market comparative analysis. Triggers: strategic review, positioning, go public, go-to-market, market analysis, competitive landscape, value proposition, is there a moat, who are our competitors, platform absorption risk, market positioning, comparable products. Use project-review for execution/roadmap/implementation health; delegates deep market scans to deep-research."
+description: "Review a project's strategic position before going public, launching, or raising — vision, mission, value proposition, scope positioning, the defensible wedge, and a live competitive / market comparative analysis. Use project-review for execution/roadmap/implementation health; delegates deep market scans to deep-research."
+when_to_use: "Triggers: strategic review, positioning, go public, go-to-market, market analysis, competitive landscape, value proposition, is there a moat, who are our competitors, platform absorption risk, market positioning, comparable products."
 model: opus
+context: fork
+agent: general-purpose
 allowed-tools: Read, Grep, Glob, WebFetch, WebSearch, Write, Edit
 ---
 
@@ -60,6 +63,9 @@ Survey the field with current evidence, not memory:
   absorb the category.
 - For a deep, multi-source, fact-checked sweep, **delegate to `deep-research`** and
   fold its cited report in. For a lighter pass, use `WebSearch`/`WebFetch` directly.
+  (This skill runs in a forked context — if the `deep-research` skill is not
+  invocable from here, do the lighter pass yourself and note under Open questions
+  that a deep-research sweep is the recommended follow-up.)
 - **Tag each comparable** with its relationship: **competitor**, **complement**,
   or **integration target** — and what it means for this project.
 - Label every finding confirmed-vs-inferred and date it.
@@ -86,8 +92,16 @@ Integrate the above into a decision instrument:
   default is options + a recommendation.
 - **A readiness picture** mapped to the project's own gates, if it has them.
 
+**Write the full review to a file** — default a gitignored path (e.g.
+`.local/strategic-review-<date>.md`) — and state its path in your final summary.
+This skill runs in a forked context: only the summary returns, everything unwritten
+is lost. The summary leads with the thesis verdict and the top weak point.
+Anything that needs the user's judgment (which strategic fork to take, an
+unverifiable market assumption, missing vision docs) goes in an **Open questions**
+section of the report — never silently decided.
+
 For the rendered deliverable (interactive HTML, scorecards, a forks comparison
-panel), hand off to `artifact-design`; default to a gitignored path (e.g. `.local/`).
+panel), hand off to `artifact-design`.
 
 ## Principles Applied
 

package/skills/subagent-orchestration/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: subagent-orchestration
+description: "Decompose big or parallelizable work across subagents — when to fan out vs stay solo, scoping self-contained sub-tasks, prompting agents that don't share your context, isolating parallel edits (git worktrees), skeptically verifying and synthesizing results you didn't produce. Triggers: use subagents, parallelize this, fan out, orchestrate agents, multi-agent, spawn agents, worktree, delegate to agents, split this across agents, agent team. Sequencing checkpoints of an approved plan → plan-execution (orchestration parallelizes within its batches)."
+model: sonnet
+allowed-tools: Read, Grep, Glob, Write, Edit, Bash
+---
+
+# Subagent Orchestration
+
+Structure work across multiple agents so the result is *more* trustworthy than
+one agent's pass — not just faster. The two failure modes this skill counters:
+fanning out work that needed shared context (agents produce incompatible
+pieces), and trusting subagent reports as if they were evidence (they're
+claims). Exact tool names and mechanics vary by harness and move fast — apply
+these principles through whatever agent-spawning surface is available.
+Boundary: `plan-execution` sequences an approved plan's checkpoints;
+orchestration is *how a batch* gets executed when it parallelizes.
+
+## Workflow
+
+### Step 1: Decide Fan-Out vs Solo — Honestly
+
+Fan out when the work is **divisible into independent pieces** (per-file
+migration, multi-angle research, review dimensions), when you need
+**independent perspectives** (adversarial verification, judge panels), or when
+the reading wouldn't fit one context (broad audits). Stay solo when the task
+needs **one coherent design voice** (an API's shape, a refactor's structure),
+when pieces are tightly coupled, or when the task is small — orchestration has
+overhead, and a fleet of agents building a feature without shared design
+produces expensive incoherence. Sub-agents also can't ask you clarifying
+questions mid-flight: ambiguity you'd resolve interactively must be resolved
+*before* the fan-out.
+
+### Step 2: Decompose into Self-Contained Tasks
+
+Each sub-task needs: a **crisp goal** with a definition of done, **explicit
+inputs** (files, constraints, conventions), **no shared mutable state** with
+its siblings, and an **output contract** (exactly what to return, in what
+form). If two tasks keep needing to talk to each other, they're one task —
+re-cut the boundaries. Interfaces first: when pieces must fit together, fix
+the contract between them *yourself, up front*, and hand each agent the
+contract rather than hoping parallel guesses converge.
+
+### Step 3: Prompt for a Cold Start
+
+The subagent knows nothing you don't say — none of your conversation, your
+constraints, or your taste. State the context it needs (or say exactly which
+files to read first), the conventions to follow, the boundaries ("do NOT touch
+X"), and the output contract. Ask for **raw findings and artifacts** (data,
+diffs, file paths, failure output) rather than summaries — you need material
+you can verify, not reassurance. A vague prompt costs a full agent-run to
+discover; read your prompt as a stranger before sending it.
+
+### Step 4: Isolate Parallel Writers
+
+Agents editing the same working tree concurrently corrupt each other. Reads
+parallelize freely; **writes need isolation** — one writer per area, or git
+worktrees (each agent on its own branch/copy, merged deliberately afterward).
+Budget for the merge: parallel edits that touch shared files turn saved
+wall-clock into conflict resolution. If the merge looks expensive, re-cut
+Step 2 along file boundaries instead.
+
+### Step 5: Verify Like You Didn't Write It — Because You Didn't
+
+A subagent's "done, tests pass" is a report, not evidence
+(`verification-before-completion` applies with extra force). Run the proving
+command on their artifact yourself; spot-read the diff (`code-reviewing` for
+substantial changes). For *findings* (bugs, research claims), use structure:
+**adversarial verification** (a second agent prompted to *refute* each
+finding), **diverse lenses** (verifiers checking different failure modes beat
+N identical passes), and majority voting where individual judgments are noisy.
+Expect and discard duplicates and false positives from parallel finders —
+that's normal yield, not failure.
+
+### Step 6: Synthesize — the Step That Makes It One Answer
+
+Merging results is real work you own: dedup overlapping findings, reconcile
+contradictions (two agents asserting opposite things means *you* investigate,
+not average), integrate parallel diffs and re-run the full suite on the
+combined result, and write the coherent summary. The whole was your task; the
+agents only did the parts. Close with a completeness check: did every
+sub-task actually complete, and what fell between the cracks of the
+decomposition?
+
+## Principles Applied
+
+- **Decomposition quality bounds output quality**: bad task boundaries can't
+  be fixed by more agents.
+- **Reports aren't evidence**: verify artifacts, adversarially where stakes
+  warrant — trust is for people, not processes.
+- **Parallelize reads freely, writes deliberately**: isolation is cheap before
+  the fan-out and expensive after.
+
+## Cross-Skill References
+
+- `plan-execution` — the checkpoint discipline; orchestration executes its batches
+- `feature-planning` — producing the task breakdown worth parallelizing
+- `verification-before-completion` — the evidence gate applied to every agent's claim
+- `code-reviewing` — reviewing substantial subagent diffs before integration
+- `git-workflow` — branch/merge hygiene for worktree-isolated work

package/skills/subagent-orchestration/evals/evals.json

@@ -0,0 +1,40 @@
+{
+  "skill_name": "subagent-orchestration",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "I need to migrate 40 API endpoint files from our old error-handling pattern to the new Result-type pattern. The transformation is mechanical but each file has quirks. Can we parallelize this across subagents?",
+      "expected_output": "Confirms good fan-out shape (divisible, independent files, mechanical core), decomposes with an explicit output contract and conventions per agent, fixes the shared pattern/contract up front (an exemplar transformation), prompts for cold start (files to read, boundaries, exact return format), isolates parallel writers (per-file ownership or worktrees), then verifies the combined result itself — running the full suite on the merged output and spot-reviewing diffs — rather than trusting per-agent 'done' reports",
+      "assertions": [
+        "Evaluates the task's fan-out fitness (independent per-file work, mechanical transformation) rather than parallelizing by default",
+        "Fixes the shared contract up front — an exemplar of the new pattern/conventions each agent receives — so parallel results converge",
+        "Prompts agents for a cold start: explicit inputs, boundaries (files they own, what not to touch), and an exact output contract",
+        "Isolates parallel writes (one agent per file/area or git worktrees) to avoid corrupting the shared working tree",
+        "Verifies the merged result directly (full test suite on the combined diff, spot-reading changes) instead of trusting subagent completion reports"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "Designing our new public API is taking long. Let's speed it up: spawn 6 subagents — one designs the auth endpoints, one the user endpoints, one the billing endpoints, one picks the pagination style, one the error format, one versioning. Then we'll glue their outputs together.",
+      "expected_output": "Pushes back on the decomposition: an API's shape needs one coherent design voice — pagination, error format, versioning, and resource conventions are cross-cutting decisions that must be fixed once, not designed in parallel and glued; recommends deciding the cross-cutting contract first (solo or via api-design), then fanning out only genuinely independent work (e.g. drafting per-resource specs against the fixed contract, or independent reviews of a draft), warning that parallel guesses produce incompatible pieces and expensive reconciliation",
+      "assertions": [
+        "Identifies that the proposed decomposition splits tightly-coupled, cross-cutting design decisions (pagination, errors, versioning, conventions) that need a single coherent voice",
+        "Recommends fixing the shared contract/conventions first, before any fan-out, rather than gluing independently-designed pieces afterward",
+        "Explains the failure mode: parallel agents without a shared contract produce incompatible outputs and costly reconciliation",
+        "Offers a legitimate parallel structure instead — e.g. per-resource spec drafting against the fixed contract, or a multi-perspective review/judge panel of a single draft",
+        "Does not simply execute the 6-way split as requested"
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "Here's our approved 5-phase implementation plan for the billing feature. Execute it phase by phase, verifying each phase before moving to the next.",
+      "expected_output": "Recognizes this as sequential checkpointed execution of an approved plan — refers to plan-execution for the checkpoint/verification/drift discipline, noting orchestration only enters if a batch inside the plan parallelizes; states the boundary between sequencing a plan and fanning out sub-tasks",
+      "assertions": [
+        "Recognizes the request as checkpointed sequential execution of an approved plan, not a parallelization problem",
+        "Refers to the plan-execution skill for the checkpoint, verification-evidence, and drift discipline",
+        "Does not spawn subagents or propose a fan-out as the primary answer",
+        "States or implies the boundary: plan-execution sequences the plan's checkpoints; subagent-orchestration is how an individual batch runs when it genuinely parallelizes"
+      ]
+    }
+  ]
+}

package/skills/technical-debt-review/SKILL.md

@@ -1,7 +1,10 @@
 ---
 name: technical-debt-review
-description: "Strategic codebase health assessment — identify hotspots, categorize debt, produce remediation roadmap. Triggers: technical debt, tech debt, debt review, codebase health, hotspots, debt assessment, remediation plan, what should we fix first, debt roadmap, code rot, legacy code audit."
+description: "Strategic codebase health assessment — identify hotspots, categorize debt, produce remediation roadmap."
+when_to_use: "Triggers: technical debt, tech debt, debt review, codebase health, hotspots, debt assessment, remediation plan, what should we fix first, debt roadmap, code rot, legacy code audit."
 model: opus
+context: fork
+agent: general-purpose
 allowed-tools: Read, Grep, Glob, Write, Edit
 ---
 
@@ -34,7 +37,7 @@ Don't try to review everything. Focus on where pain is concentrated.
 - Tests that only test happy paths (no edge cases, no error cases)
 - Test files significantly longer than the code they test (over-specified tests that break on refactoring)
 
-Ask the user: Where do engineers slow down? What parts of the codebase do people avoid touching? Where do bugs keep appearing?
+If the request came with team pain points (where engineers slow down, code people avoid touching, where bugs keep appearing), weight those hotspots first. This skill runs in a forked context and cannot ask mid-run — when that input is missing, proceed on the code signals above and list "where does the team actually hurt?" under Open questions in the report.
 
 ## Step 2: Categorize by Debt Type and Severity
 
@@ -99,6 +102,13 @@ Output a prioritized action plan:
 
 Use [templates/debt-audit.md](templates/debt-audit.md) for the full audit format.
 
+**Write the full audit to a file** (default a gitignored location, e.g.
+`.local/debt-review-<date>.md`) and state its path in your final summary — this
+skill runs in a forked context: only the summary returns, everything unwritten is
+lost. Judgment calls that need user input (e.g. which subsystem matters most,
+unknown team pain points) go in an **Open questions** section of the report, never
+guessed silently.
+
 ## Principles Applied
 
 - **KISS**: Simplify complexity first — complex code is the root cause of most other debt