swe-workflow-skills 0.1.0 → 0.2.0

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/threat-modeling/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: threat-modeling
+description: "Design-time security analysis of a system or feature before it's built — trust boundaries, attack surface, STRIDE per element, abuse cases, prioritized mitigations that become security requirements. Triggers: threat model, STRIDE, trust boundary, attack surface, what could go wrong security-wise, security design review, abuse case, secure this design, security requirements. Reviewing EXISTING code/config for vulnerabilities → security-audit; use this skill while the design is still on the whiteboard."
+model: opus
+allowed-tools: Read, Grep, Glob, Write, Edit
+---
+
+# Threat Modeling
+
+Find the security flaws while they're still cheap — in the design, before the
+code exists. A missing authorization check found here is a requirement; found by
+`security-audit` it's a rework ticket; found by an attacker it's an incident.
+The frame is Shostack's four questions: **what are we building, what can go
+wrong, what are we doing about it, did we do a good job?**
+
+Boundary: this skill is proactive and design-time. Once code exists, verify it
+against this model with `security-audit` — the two are complements, not
+alternatives.
+
+## Workflow
+
+### Step 1: Model the System
+
+Sketch a data-flow view of what's being built: components (processes, stores,
+external services), the data flowing between them, and **classification** of
+that data (what here is worth stealing or corrupting — credentials, PII,
+payment data, tokens?). Then draw the **trust boundaries**: every place data
+crosses a privilege, ownership, or network line — internet → load balancer,
+app → database, user → admin, your service → a third party, webhook → your
+endpoint. Threats cluster at these crossings; a model without explicit
+boundaries finds only generic threats.
+
+### Step 2: Enumerate the Attack Surface
+
+List the entry points ranked by exposure — unauthenticated internet-facing
+first, then authenticated user, then internal/partner, then admin. Name the
+assets an attacker actually wants (from Step 1's classification) and the
+realistic attackers: opportunist with a scanner, malicious or curious insider,
+targeted attacker after your data specifically. Effort should follow exposure ×
+asset value, not enumeration order.
+
+### Step 3: STRIDE Each Boundary Crossing
+
+Apply STRIDE **per element and boundary crossing**, not once globally — that's
+what makes it systematic rather than a vibes checklist:
+
+| Category | The question at each crossing |
+|---|---|
+| **S**poofing | Can the caller pretend to be someone/something else? |
+| **T**ampering | Can data or code be modified in transit or at rest? |
+| **R**epudiation | Could an actor deny an action with no way to prove it? |
+| **I**nformation disclosure | Can data leak to someone unauthorized? |
+| **D**enial of service | Can this element be exhausted or made unavailable? |
+| **E**levation of privilege | Can a lower-privilege actor gain higher privilege? |
+
+Per-category threat patterns and standard mitigations:
+[references/stride-mitigations.md](references/stride-mitigations.md).
+
+### Step 4: Write Abuse Cases
+
+For each key user story, write the attacker's version: "As a malicious user, I
+can share a link that grants more than I have", "As a former employee, I can
+still call the API with my cached token." Abuse cases catch the logic-level
+threats STRIDE's element-by-element pass misses — especially authorization
+logic, workflow bypasses, and quota/limit abuse.
+
+### Step 5: Rank and Decide
+
+Score each threat roughly by likelihood × impact — precision theater (long
+DREAD decimals) wastes the room's time; high/medium/low is enough to order the
+work. For each threat, record an explicit decision: **mitigate** (name the
+control), **eliminate** (remove the feature/flow), **transfer** (vendor,
+insurance), or **accept** (documented, with an owner — silent acceptance is the
+only wrong answer). Mitigations become **security requirements with acceptance
+criteria** — feed them into `feature-planning` so they ship with the feature
+instead of after it.
+
+### Step 6: Validate and Keep It Alive
+
+Check coverage: every trust boundary STRIDE'd, every entry point owned, every
+threat decided. Then treat the model as living documentation — revisit when the
+architecture changes (new integration, new entry point, new data class), and
+hand it to `security-audit` as the checklist when the built system gets
+reviewed.
+
+## Principles Applied
+
+- **Threats cluster at trust boundaries** — model the boundaries first and the
+  threats enumerate themselves; skip them and you get a generic list.
+- **A decision per threat, even "accept"** — an undocumented accepted risk is
+  indistinguishable from an unnoticed one.
+- **KISS on scoring**: rank to order the work, not to defend the numbers.
+
+## Cross-Skill References
+
+- `security-audit` — reactive review of the *built* system; consumes this model
+- `architecture-design` — record structural security decisions as ADRs
+- `api-design` — authn/authz contracts for the boundaries identified here
+- `data-modeling` — where the classified data actually lives
+- `configuration-strategy` — secrets handling for the credentials in the model
+- `feature-planning` — turns the mitigations into scheduled, testable tasks

package/skills/threat-modeling/evals/evals.json

@@ -0,0 +1,40 @@
+{
+  "skill_name": "threat-modeling",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "We're designing a new file-sharing feature: users upload documents and can share them via public links, with optional password protection and expiry. Nothing is built yet. Can you threat model it before we start?",
+      "expected_output": "Models the system and data flows with explicit trust boundaries (internet → app, app → storage, anonymous link-holder → protected document), classifies the data at stake, enumerates the attack surface ranked by exposure, applies STRIDE per element/boundary crossing (e.g. link enumeration/guessing as information disclosure, password brute force as spoofing, upload abuse as DoS/tampering), writes abuse cases, and outputs prioritized mitigations framed as security requirements to feed into planning",
+      "assertions": [
+        "Models the system's components and data flows and identifies explicit trust boundaries before enumerating threats",
+        "Classifies the data at stake and enumerates entry points / attack surface ranked by exposure (unauthenticated public links first)",
+        "Applies STRIDE categories systematically per element or boundary crossing, naming the categories, rather than producing an unstructured threat list",
+        "Includes threats specific to this design, such as public-link guessing/enumeration, password brute-forcing, expired-link enforcement, and malicious file upload",
+        "Produces prioritized mitigations with an explicit decision per threat, framed as security requirements/acceptance criteria for implementation planning"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "New design to review before we build: we're adding inbound webhooks from a payment provider (they POST us payment events) plus an internal admin panel where support staff can issue refunds. Threat model this.",
+      "expected_output": "Treats the third-party webhook and the admin privilege line as distinct trust boundaries: webhook threats include spoofed/forged events (signature verification), replay (timestamp/nonce), and DoS/flooding; admin-panel threats center on elevation of privilege (function-level authz on refunds), repudiation (audit trail for refund actions), and insider abuse cases; ranks by exposure and emits concrete mitigations",
+      "assertions": [
+        "Identifies the inbound webhook from the payment provider as a trust boundary crossing and covers spoofed/forged events with signature verification as a mitigation",
+        "Covers replay of webhook events (timestamp, nonce, or idempotency handling) and denial of service on the webhook endpoint",
+        "Treats the admin/support refund capability as a privilege boundary — covering elevation of privilege and server-side function-level authorization",
+        "Addresses repudiation for refund actions (audit logging of who refunded what) and includes an insider/abuse-case perspective",
+        "Prioritizes threats by exposure and impact and records an explicit decision or mitigation per threat"
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "Here's our Express API that's been in production for a year — can you go through the code and check it for vulnerabilities like SQL injection, XSS, and broken auth?",
+      "expected_output": "Recognizes this as a reactive security review of existing code, not design-time threat modeling — refers to security-audit for the OWASP-style code review, stating the boundary: threat-modeling analyzes designs before they're built; security-audit reviews built systems",
+      "assertions": [
+        "Recognizes the request as a security review of existing, deployed code rather than design-time analysis",
+        "Refers to the security-audit skill for the vulnerability review",
+        "Does not produce a design-time threat model (DFDs, STRIDE-per-boundary of a not-yet-built system) as the answer",
+        "States the boundary: threat-modeling is proactive/design-time, security-audit is the reactive review of built code"
+      ]
+    }
+  ]
+}

package/skills/threat-modeling/references/stride-mitigations.md

@@ -0,0 +1,90 @@
+# STRIDE: Threat Patterns and Standard Mitigations
+
+Per-category catalog for Step 3. For each boundary crossing, scan the category's
+typical threats and pick from the standard controls — invent a custom control
+only when a standard one genuinely doesn't fit (custom security controls are
+where vulnerabilities live).
+
+## Spoofing (authentication)
+
+**Typical threats**: credential stuffing/phishing at login; forged webhook or
+callback calls; service-to-service calls with no caller identity; DNS/ARP
+spoofing on internal traffic; replayed tokens or signed URLs.
+
+**Standard mitigations**: strong auth (MFA for humans, mTLS or signed requests
+for services); webhook signature verification **plus** timestamp/nonce to block
+replay; short-lived tokens over long-lived API keys; OIDC/OAuth flows instead of
+home-grown login; certificate pinning only where the threat justifies its
+operational cost.
+
+## Tampering (integrity)
+
+**Typical threats**: parameter/payload manipulation (IDs, prices, quantities);
+modification of data in transit; direct writes to a shared store bypassing the
+app's rules; CI/CD or dependency supply-chain injection; unsigned mobile/desktop
+update channels.
+
+**Standard mitigations**: TLS everywhere (internal too); server-side validation
+of every client-supplied value (client-side checks are UX, not security);
+integrity signatures/HMACs on anything that round-trips through the client
+(cookies, tokens, callback params); least-privilege DB accounts per service;
+signed artifacts and locked dependencies in the pipeline.
+
+## Repudiation (auditability)
+
+**Typical threats**: admin or support actions with no trail; shared/service
+accounts hiding who acted; logs an attacker can edit or delete; missing
+before/after values on sensitive mutations.
+
+**Standard mitigations**: append-only or write-once audit logs, shipped off the
+host that generates them; per-human accounts (no shared logins) with actions
+attributed through impersonation records; log the actor, action, target, and
+before/after for sensitive operations; clock sync so timelines reconstruct.
+
+## Information Disclosure (confidentiality)
+
+**Typical threats**: IDOR (guessable IDs + missing object-level authz); verbose
+errors/stack traces leaking internals; sensitive data in logs, URLs, or
+analytics; overly broad API responses (returning the whole object when the
+client needs two fields); backups/exports with weaker controls than the source;
+enumeration via timing or error differences (valid vs invalid username).
+
+**Standard mitigations**: object-level authorization on every read (not just
+route-level); non-enumerable IDs where exposure matters; encrypt sensitive data
+at rest and classify what "sensitive" means (Step 1); scrub PII/secrets from
+logs and error responses; response shaping (field allowlists); uniform errors
+and timing for auth failures.
+
+## Denial of Service (availability)
+
+**Typical threats**: unauthenticated endpoints doing expensive work (search,
+export, PDF render); unbounded request sizes/collections ("give me all
+records"); resource exhaustion via file upload; amplification through webhooks
+or fan-out; a single tenant starving the rest.
+
+**Standard mitigations**: rate limiting keyed to the right identity (IP for
+anonymous, account for authenticated); pagination and hard caps on collection
+endpoints; size limits and timeouts on every external input; queue + backpressure
+for expensive work instead of doing it in-request; per-tenant quotas.
+
+## Elevation of Privilege (authorization)
+
+**Typical threats**: missing function-level checks (the admin route trusts the
+hidden menu); role changes that don't re-evaluate existing sessions; mass
+assignment setting `is_admin` from a request body; confused-deputy flows (your
+service does something *for* a caller with *its own* elevated rights); path
+traversal / injection escalating code execution.
+
+**Standard mitigations**: deny-by-default authorization enforced server-side at
+the function/object level; centralized policy (one authz module, not checks
+scattered per handler); explicit field allowlists on writes; scoped credentials
+so a deputy can only act with the caller's authority; re-check privileges on
+sensitive actions, not just at login.
+
+## Using the catalog
+
+Walk each trust-boundary crossing from SKILL.md Step 3 down this list. Most
+crossings surface 2–4 real threats, not all six categories — a database
+crossing rarely has a repudiation story, a webhook crossing almost always has
+spoofing + replay + DoS. Record only threats with a plausible attacker and
+path; padding the model with theoretical entries buries the real ones.

package/skills/writing-skills/SKILL.md

@@ -7,11 +7,12 @@ allowed-tools: Read, Grep, Glob, Write, Edit, Bash
 
 # Writing Skills
 
-Author and maintain skills for this library. The canonical rule set lives in the
-README's "Building Skills" section — read it for descriptions, listing budget,
-frontmatter, and common mistakes. This skill adds the parts that must be
-*applied*, not just read: how to reproduce a skill's failure before fixing it,
-how to write a description that actually triggers, and how to pressure-test.
+Author and maintain skills for this library. The canonical rule set lives in
+**docs/AUTHORING.md** — read it for descriptions, listing budget, frontmatter,
+dynamic context injection, and common mistakes. This skill adds the parts that
+must be *applied*, not just read: how to reproduce a skill's failure before
+fixing it, how to write a description that actually triggers, and how to
+pressure-test.
 
 ## ⛔ The Iron Law
 
@@ -53,16 +54,25 @@ description over the body, so get it right.
 - **Our format is a compliant hybrid:** `<when/purpose>. Triggers: <keywords>. <boundary>`.
   The `Triggers:` list *is* the when-to-use expressed as the phrases a user
   actually types — keep casting that net wide.
-- **~350 chars** (listing-budget constraint; hard cap 1024). Longer descriptions
-  get silently dropped at scale — `/doctor` reports it. See README "Listing Budget".
+- **Keep the hybrid format for now** (don't move triggers to `when_to_use` yet):
+  the catalog builder reads only `description`, so the router would lose the
+  trigger phrases. The `when_to_use` migration is a coordinated roadmap change
+  (builder + skills + routing re-baseline together).
+- **~350 chars** for `description` (listing-budget constraint; hard cap 1024).
+  Over budget, the *least-invoked* skills' descriptions drop silently — `/doctor`
+  reports it. See AUTHORING.md "Listing Budget".
 - **Anti-pattern:** describing mechanics/steps instead of triggering situations.
 
-## Structure and budget (brief — see README for detail)
+## Structure and budget (brief — see AUTHORING.md for detail)
 
 - Frontmatter: `name`, `description`, `model` (haiku/sonnet/opus by reasoning
-  need), `allowed-tools`.
+  need), `allowed-tools`. Newer fields where they fit: `when_to_use`,
+  `context: fork` + `agent` (heavy read-only skills), `paths` (file-scoped),
+  `disable-model-invocation` (deliberate-only workflows), `effort`.
 - Progressive disclosure: keep SKILL.md tight (aim < 300 lines); push deep
-  domain knowledge to `references/`, output formats to `templates/`.
+  domain knowledge to `references/`, output formats to `templates/`. On
+  compaction only a skill's first ~5k tokens are re-attached — front-load the
+  Iron Law and workflow; write standing instructions, not one-time steps.
 - Exactly **3 evals** (happy path / edge case / scope boundary) with specific,
   verifiable assertions. For hardened skills, add an optional `pressure` eval
   (see `verification-before-completion` and the safety-critical skills for the
@@ -79,9 +89,15 @@ Apply rigor where mistakes are expensive; keep freedom where judgment matters.
   architecture exploration, UX, estimation, proposals. Rigidity there produces
   worse outcomes, not better ones.
 
+## Retiring skills
+
+As base models improve, a skill can become pure overhead. Periodically re-run a
+skill's evals RED (without the skill); if RED ≈ GREEN, slim or retire it rather
+than letting it spend listing budget and re-attachment tokens.
+
 ## See also
 
-- README "Building Skills" — the canonical rules and common mistakes.
+- docs/AUTHORING.md — the canonical rules and common mistakes.
 - [references/pressure-testing.md](references/pressure-testing.md) — running baseline scenarios and the pressure levers.
 - `docs/EVALS.md` — the automated RED/GREEN harness that replays evals through subagents and gates regressions in CI.
 - `verification-before-completion` — the discipline that proves a skill change works (run the eval, read the result).