skilldrop-cli 0.11.5 → 0.11.7

package/README.md

@@ -20,55 +20,194 @@ Every skill is a plain `SKILL.md` folder — the [**Agent Skills open standard**
 
 ## How skilldrop works
 
-skilldrop runs two value streams, and **nothing comes out of either until it passes a review gate.** Both diagrams render on GitHub; the Mermaid sources live in [`docs/`](docs/) for easy re-rendering.
+skilldrop ships **loops**, not just parts. A loop is a named sequence of stages over existing skills with a gate between them: [`loops/<name>/LOOP.md`](loops/) is what an agent reads, `loop.json` is the machine-readable contract ([RFC-0028](docs/rfcs/0028-loops-as-a-primitive.md)). **Nothing comes out of a loop until it passes that loop's gate.**
 
-### Knowledge-work pipeline
+A loop *sequences* skills — it never contains one. Every skill stays independently installable and runnable on its own, which is what keeps a single-folder copy working in Cursor, Kiro, or Aider.
 
-Raw input becomes a stakeholder-ready artifact — and loops back through review until it's approved.
+Four loops cover the lifecycle, and they are separated by **reversibility** — how expensive the mistake is to unwind — which is why each gets its own gate rather than folding into a neighbour:
+
+| Loop | Takes | Gate | Produces | Mistake costs |
+|---|---|---|---|---|
+| [`discover`](loops/discover/LOOP.md) | interviews, journeys, a strategy question | **G0** human — a person ratifies the brief | a ratified requirement | a re-brief |
+| [`design`](loops/design/LOOP.md) | a ratified requirement | **G1** review — `council-review`'s panel | a recorded decision (ADR) | months, unwound in code |
+| [`build`](loops/build/LOOP.md) | an agreed requirement or triaged defect | **G2** mechanical — `pre-merge-review`'s gate script decides | merged code | a revert |
+| [`operate`](loops/operate/LOOP.md) | a shipped service | **G3** human — the incident is closed | a postmortem and runbook deltas | live users, irreversible |
+
+Plus one **wrapper**, which is not a lifecycle stage but the two passes either side of *any* generator:
+
+| Wrapper | Takes | Gate | Produces |
+|---|---|---|---|
+| [`ship-a-draft`](loops/ship-a-draft/LOOP.md) | raw notes, a transcript, a ticket | **G4** review — `doc-critique`'s verdict | a stakeholder-ready artifact |
+
+Every gate emits a verdict from one shared vocabulary ([`contracts/terminals.json`](contracts/terminals.json)) in five classes — pass, conditional, revise, redirect, blocked — so `READY`, `PROCEED` and `SHIP IT` are recognisably the same kind of answer. Both diagrams render on GitHub; the Mermaid sources live in [`docs/`](docs/) for easy re-rendering.
+
+*Diagrams below are generated from each loop's `loop.json` by [`build_loops.py`](build_loops.py) — edit the contract, not the picture.*
+
+### `discover` — raw signal to a ratified requirement
+
+Interviews, journeys and strategy questions become one tagged brief, then numbered requirements a **human ratifies** before any design starts.
+
+<!-- loop:discover:start -->
+
+```mermaid
+%%{init: {'theme':'base','themeVariables':{'fontFamily':'Segoe UI, Helvetica, Arial','fontSize':'15px','lineColor':'#9AA5B1'},'flowchart':{'curve':'basis','rankSpacing':70,'nodeSpacing':50,'padding':16}}}%%
+flowchart LR
+    classDef gen    fill:#E8F0FE,stroke:#4C7DF0,stroke-width:1.5px,color:#1A3A8F;
+    classDef review fill:#FDEAEA,stroke:#E05B5B,stroke-width:1.5px,color:#8A1F1F;
+    classDef gate   fill:#FBE3A2,stroke:#D9971E,stroke-width:2px,color:#6B4500,font-weight:bold;
+    classDef ship   fill:#E6F7EC,stroke:#34A853,stroke-width:2px,color:#0F6B33,font-weight:bold;
+
+    gather["gather<br/><small>requirements-interview +2</small>"]:::gen
+    structure["structure<br/><small>brief-intake</small>"]:::gen
+    specify["specify<br/><small>prd-draft</small>"]:::gen
+    ratify["ratify<br/><small>doc-critique</small>"]:::gate
+    G0{"G0 · human"}:::gate
+    DONE(["complete"]):::ship
+
+    gather --> structure
+    structure --> specify
+    specify --> ratify
+    ratify --> G0
+    G0 == "PROCEED" ==> DONE
+
+    G0 -- "REVISE (max 3)" --> structure
+```
+
+<!-- loop:discover:end -->
+
+### `design` — a requirement to a recorded decision
+
+Constraints first, then structure and diagrams, then an attack, then a panel that must agree — and only then is the decision written down as an ADR.
+
+<!-- loop:design:start -->
+
+```mermaid
+%%{init: {'theme':'base','themeVariables':{'fontFamily':'Segoe UI, Helvetica, Arial','fontSize':'15px','lineColor':'#9AA5B1'},'flowchart':{'curve':'basis','rankSpacing':70,'nodeSpacing':50,'padding':16}}}%%
+flowchart LR
+    classDef gen    fill:#E8F0FE,stroke:#4C7DF0,stroke-width:1.5px,color:#1A3A8F;
+    classDef review fill:#FDEAEA,stroke:#E05B5B,stroke-width:1.5px,color:#8A1F1F;
+    classDef gate   fill:#FBE3A2,stroke:#D9971E,stroke-width:2px,color:#6B4500,font-weight:bold;
+    classDef ship   fill:#E6F7EC,stroke:#34A853,stroke-width:2px,color:#0F6B33,font-weight:bold;
+
+    constrain["constrain<br/><small>nfr-spec</small>"]:::gen
+    shape["shape<br/><small>design-doc·architecture-diagrams</small>"]:::gen
+    threat["threat<br/><small>threat-model</small>"]:::review
+    ratify["ratify<br/><small>council-review</small>"]:::gate
+    record["record<br/><small>adr-generator</small>"]:::gen
+    G1{"G1 · review"}:::gate
+    DONE(["complete"]):::ship
+
+    constrain --> shape
+    shape --> threat
+    threat --> ratify
+    ratify --> G1
+    G1 == "PROCEED" ==> record
+    record --> DONE
+
+    G1 -- "REVISE (max 3)" --> shape
+```
+
+<!-- loop:design:end -->
+
+### `build` — a requirement to merged code
+
+A vertical slice becomes shippable code through a self-correcting loop, gated by a script whose exit code decides. The inner generate-challenge cycle is the [`feature-implement-loop`](skills/feature-implement-loop/SKILL.md) skill.
+
+<!-- loop:build:start -->
 
 ```mermaid
 %%{init: {'theme':'base','themeVariables':{'fontFamily':'Segoe UI, Helvetica, Arial','fontSize':'15px','lineColor':'#9AA5B1'},'flowchart':{'curve':'basis','rankSpacing':70,'nodeSpacing':50,'padding':16}}}%%
 flowchart LR
-    classDef input  fill:#FFF4E0,stroke:#E8A93B,stroke-width:2px,color:#7A4E00,font-weight:bold;
     classDef gen    fill:#E8F0FE,stroke:#4C7DF0,stroke-width:1.5px,color:#1A3A8F;
     classDef review fill:#FDEAEA,stroke:#E05B5B,stroke-width:1.5px,color:#8A1F1F;
+    classDef gate   fill:#FBE3A2,stroke:#D9971E,stroke-width:2px,color:#6B4500,font-weight:bold;
     classDef ship   fill:#E6F7EC,stroke:#34A853,stroke-width:2px,color:#0F6B33,font-weight:bold;
 
-    IN(["Raw input<br/>notes · ticket · transcript"]):::input
-    brief["Structure the brief"]:::gen
-    gens["Draft the artifact"]:::gen
-    crit["Review and refine"]:::review
-    ART(["Stakeholder-ready<br/>artifact"]):::ship
+    shape["shape<br/><small>user-story-splitter·bug-triage</small>"]:::gen
+    implement["implement<br/><small>feature-implement-loop</small>"]:::gen
+    verify["verify<br/><small>pre-merge-review</small>"]:::review
+    decide["decide<br/><small>council-review</small>"]:::gate
+    G2{"G2 · mechanical"}:::gate
+    G2_1{"G2.1 · human"}:::gate
+    DONE(["complete"]):::ship
+
+    shape --> implement
+    implement --> verify
+    verify --> G2
+    G2 == "READY" ==> decide
+    decide --> G2_1
+    G2_1 == "PROCEED" ==> DONE
+
+    G2 -- "NOT READY (max 3)" --> implement
+    G2_1 -- "REVISE (max 3)" --> shape
+```
+
+<!-- loop:build:end -->
+
+### `operate` — a shipped service through detection and learning
+
+Instrument, write the runbook, communicate the incident, then feed the postmortem's runbook deltas straight back into the runbook. The one loop whose failures are live.
+
+<!-- loop:operate:start -->
 
-    IN --> brief --> gens --> crit
-    crit -- "revise" --> brief
-    crit == "approved" ==> ART
+```mermaid
+%%{init: {'theme':'base','themeVariables':{'fontFamily':'Segoe UI, Helvetica, Arial','fontSize':'15px','lineColor':'#9AA5B1'},'flowchart':{'curve':'basis','rankSpacing':70,'nodeSpacing':50,'padding':16}}}%%
+flowchart LR
+    classDef gen    fill:#E8F0FE,stroke:#4C7DF0,stroke-width:1.5px,color:#1A3A8F;
+    classDef review fill:#FDEAEA,stroke:#E05B5B,stroke-width:1.5px,color:#8A1F1F;
+    classDef gate   fill:#FBE3A2,stroke:#D9971E,stroke-width:2px,color:#6B4500,font-weight:bold;
+    classDef ship   fill:#E6F7EC,stroke:#34A853,stroke-width:2px,color:#0F6B33,font-weight:bold;
+
+    instrument["instrument<br/><small>observability-plan</small>"]:::gen
+    document["document<br/><small>runbook-generator</small>"]:::gen
+    respond["respond<br/><small>incident-comms</small>"]:::gen
+    learn["learn<br/><small>postmortem-generator</small>"]:::review
+    G3{"G3 · human"}:::gate
+    DONE(["complete"]):::ship
+
+    instrument --> document
+    document --> respond
+    respond --> learn
+    learn --> G3
+    G3 == "PROCEED" ==> DONE
+
+    G3 -- "REVISE (max 3)" --> document
 ```
 
-### Code: implement and verify
+<!-- loop:operate:end -->
+
+### `ship-a-draft` — raw input to a stakeholder-ready artifact
 
-A feature spec becomes shippable code through a self-correcting loop — generate, adversarially challenge, close the gaps, re-check — until the review is clean or a 3-round cap is hit. This is the [`feature-implement-loop`](skills/feature-implement-loop/SKILL.md) skill.
+The wrapper: structured intake before any generator, critique and a machine-residue scrub after. Loops back through intake — not the draft — until it's approved.
+
+<!-- loop:ship-a-draft:start -->
 
 ```mermaid
 %%{init: {'theme':'base','themeVariables':{'fontFamily':'Segoe UI, Helvetica, Arial','fontSize':'15px','lineColor':'#9AA5B1'},'flowchart':{'curve':'basis','rankSpacing':70,'nodeSpacing':50,'padding':16}}}%%
 flowchart LR
-    classDef input  fill:#FFF4E0,stroke:#E8A93B,stroke-width:2px,color:#7A4E00,font-weight:bold;
     classDef gen    fill:#E8F0FE,stroke:#4C7DF0,stroke-width:1.5px,color:#1A3A8F;
     classDef review fill:#FDEAEA,stroke:#E05B5B,stroke-width:1.5px,color:#8A1F1F;
     classDef gate   fill:#FBE3A2,stroke:#D9971E,stroke-width:2px,color:#6B4500,font-weight:bold;
     classDef ship   fill:#E6F7EC,stroke:#34A853,stroke-width:2px,color:#0F6B33,font-weight:bold;
 
-    IN(["Feature / story<br/>description + acceptance criteria"]):::input
-    gC["Write and update<br/>code and tests"]:::gen
-    revC["Challenge the code"]:::review
-    gate{"Gaps found?"}:::gate
-    SHIP(["Feature ready<br/>to be shipped"]):::ship
+    intake["intake<br/><small>brief-intake</small>"]:::gen
+    draft["draft<br/><small>*</small>"]:::gen
+    critique["critique<br/><small>doc-critique</small>"]:::review
+    polish["polish<br/><small>output-hygiene</small>"]:::review
+    G4{"G4 · review"}:::gate
+    DONE(["complete"]):::ship
+
+    intake --> draft
+    draft --> critique
+    critique --> G4
+    G4 == "SHIP IT" ==> polish
+    polish --> DONE
 
-    IN --> gC --> revC --> gate
-    gate -- "yes (up to 3 rounds)" --> gC
-    gate == "no" ==> SHIP
+    G4 -- "MAJOR REWRITE (max 3)" --> intake
 ```
 
+<!-- loop:ship-a-draft:end -->
+
 ## Skills in this repo
 
 ### Pipeline glue

package/contracts/loop.schema.json

@@ -0,0 +1,87 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/sananthanarayan/skilldrop/contracts/loop.schema.json",
+  "title": "skilldrop loop",
+  "$comment": "RFC-0028. A loop sequences existing skills; it never contains one. Skills stay in flat skills/<name> folders and stay independently installable — a loop is a named order plus the gates between stages. Enforced by validate.py with hand-rolled stdlib checks: skilldrop ships zero runtime dependencies and this file must not become a reason to add `jsonschema`.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["name", "description", "entrypoint", "kind", "stages"],
+  "properties": {
+    "$comment": { "type": "string" },
+    "name": {
+      "type": "string",
+      "pattern": "^[a-z0-9][a-z0-9-]*$",
+      "description": "Kebab-case. Must equal the folder name and the LOOP.md frontmatter name — the same triple-match skills are held to."
+    },
+    "version": { "type": "string" },
+    "description": {
+      "type": "string",
+      "description": "Use-case-first. First half says what the loop delivers; second half states the trigger phrases an agent matches on."
+    },
+    "entrypoint": { "const": "LOOP.md" },
+    "kind": {
+      "enum": ["loop", "wrapper"],
+      "description": "`loop` advances stage to stage toward a terminal. `wrapper` wraps an arbitrary generator skill chosen at run time — its stages are the passes either side of that generator."
+    },
+    "cap": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 10,
+      "default": 3,
+      "description": "Maximum revision rounds before the loop stops looping and emits its conditional or blocked terminal. Default 3, matching agent-loop-design's revision cap."
+    },
+    "stages": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "type", "intent", "skills"],
+        "properties": {
+          "id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$" },
+          "type": {
+            "enum": ["generate", "verify", "gate"],
+            "description": "The three state types agent-loop-design mandates: 'Every loop has exactly these three state types.'"
+          },
+          "intent": { "type": "string", "description": "One line: what this stage is for." },
+          "skills": {
+            "type": "array",
+            "minItems": 1,
+            "items": { "type": "string" },
+            "description": "Skill folder names, in order. Each must be a real skills/<name>. `*` means any generator, and is legal only in a wrapper."
+          },
+          "gate": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["id", "kind", "verdicts"],
+            "properties": {
+              "id": {
+                "type": "string",
+                "pattern": "^G[0-9]+(\\.[0-9]+)?$",
+                "description": "Named gate, unique across the repo. A gate is a place a human or a script can point at."
+              },
+              "kind": {
+                "enum": ["mechanical", "review", "human"],
+                "description": "mechanical = a script's exit code decides. review = a skill or subagent panel decides. human = a person decides and the agent may not proceed without it."
+              },
+              "script": {
+                "type": "string",
+                "description": "Repo-relative path to the deciding script. Required when kind is mechanical, forbidden otherwise."
+              },
+              "verdicts": {
+                "type": "array",
+                "minItems": 2,
+                "items": { "type": "string" },
+                "description": "Every verdict this gate can emit. All must exist in contracts/terminals.json. Must include >=1 pass-class and >=1 non-pass."
+              },
+              "revise_to": {
+                "type": "string",
+                "description": "Stage id a revise-class verdict returns to. Must be an earlier stage in this loop."
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/contracts/terminals.json

@@ -0,0 +1,33 @@
+{
+  "$comment": "RFC-0028 — the shared verdict vocabulary. Before this file, every gating skill invented its own terminal words: feature-implement-loop says VERIFIED, pre-merge-review says READY, council-review says PROCEED, doc-critique says SHIP IT. They mean the same five things. A loop's gate declares which verdicts it can emit, and validate.py checks every one against this file — so a new loop cannot invent a sixth kind of 'yes'.",
+  "version": "1.0.0",
+  "classes": {
+    "pass": "The gate is satisfied. The loop advances to the next stage, or terminates successfully.",
+    "conditional": "The gate is satisfied, but named open items travel forward with the artifact. Advancing is allowed; forgetting the items is not.",
+    "revise": "The gate is not satisfied and the fix is known. Return to the stage named by the loop's revision edge, subject to the cap.",
+    "redirect": "The gate is not satisfied and the work is the wrong shape. Do not revise — re-enter a different stage, a different loop, or a different artifact.",
+    "blocked": "The gate cannot be evaluated. A required input, decision, or permission is missing. Stop and name what is needed."
+  },
+  "verdicts": {
+    "VERIFIED":                 { "class": "pass",        "origin": "feature-implement-loop" },
+    "READY":                    { "class": "pass",        "origin": "pre-merge-review" },
+    "PROCEED":                  { "class": "pass",        "origin": "council-review" },
+    "SHIP IT":                  { "class": "pass",        "origin": "doc-critique" },
+    "VERIFIED WITH OPEN ITEMS": { "class": "conditional", "origin": "feature-implement-loop" },
+    "PROCEED WITH CONDITIONS":  { "class": "conditional", "origin": "council-review" },
+    "SHIP WITH CHANGES":        { "class": "conditional", "origin": "doc-critique" },
+    "NOT READY":                { "class": "revise",      "origin": "pre-merge-review" },
+    "REVISE":                   { "class": "revise",      "origin": "council-review" },
+    "MAJOR REWRITE":            { "class": "revise",      "origin": "doc-critique" },
+    "RECONSIDER":               { "class": "redirect",    "origin": "council-review" },
+    "SPLIT":                    { "class": "redirect",    "origin": "council-review" },
+    "WRONG ARTIFACT":           { "class": "redirect",    "origin": "doc-critique" },
+    "BLOCKED":                  { "class": "blocked",     "origin": "feature-implement-loop" }
+  },
+  "rules": [
+    "Every gate declares at least one `pass` verdict and at least one non-pass verdict. A gate that can only succeed is not a gate.",
+    "Every gate can emit BLOCKED. A missing input is always possible and must never be fabricated past (AGENTS.md, non-interactive invocation).",
+    "A `revise` verdict is subject to the loop's `cap`. On the cap-th revise, the loop emits its conditional or blocked terminal instead of looping again.",
+    "A `redirect` verdict leaves the loop. It names where the work goes instead."
+  ]
+}

package/loops/build/LOOP.md

@@ -0,0 +1,65 @@
+---
+name: build
+description: Take an agreed requirement to merged code through a capped generate-verify-gate loop, with a mechanical gate that decides and a human who owns the merge. Use when the user wants to implement a story, fix a triaged bug, or ask whether a change is safe to merge.
+---
+
+# build
+
+The repo-scope loop: a requirement enters, merged code leaves, and nothing crosses a stage
+boundary without passing that stage's gate. This loop *sequences* skills — it never contains
+one. Every skill named below stays independently installable and runnable on its own.
+
+## Stages
+
+| # | Stage | Type | Skills | Gate |
+|---|---|---|---|---|
+| 1 | `shape` | generate | [`user-story-splitter`](../../skills/user-story-splitter/SKILL.md), [`bug-triage`](../../skills/bug-triage/SKILL.md) | — |
+| 2 | `implement` | generate | [`feature-implement-loop`](../../skills/feature-implement-loop/SKILL.md) | — |
+| 3 | `verify` | verify | [`pre-merge-review`](../../skills/pre-merge-review/SKILL.md) | **G2** mechanical |
+| 4 | `decide` | gate | [`council-review`](../../skills/council-review/SKILL.md) | **G2.1** human |
+
+## How to run this loop
+
+1. **Establish the unit of work.** New capability → `user-story-splitter`. Reported defect →
+   `bug-triage`. The stage is done when there is one vertical slice with acceptance criteria a
+   test can assert. Vague criteria are the single largest cause of a wasted round 3.
+2. **Implement.** Hand the slice to `feature-implement-loop`, which runs its own capped
+   generate-challenge-gate cycle internally. Do not re-implement its rounds here — this loop's
+   `cap` governs returns from G2, not the inner skill's rounds.
+3. **Verify at G2.** Run `pre-merge-review`. Its script decides and its panel explains:
+   `python3 skills/pre-merge-review/scripts/gate.py`. The exit code is the verdict —
+   `READY`, `NOT READY`, or `BLOCKED`.
+4. **Honour the gate.** `NOT READY` returns to `implement`, up to `cap` (3) times. On the
+   third return, stop looping and emit `BLOCKED` naming what did not converge. Never edit the
+   gate to make it pass.
+5. **Decide at G2.1.** The merge is a human's. Escalate design disagreements surfaced at G2 to
+   `council-review` rather than arguing them inside the diff; `RECONSIDER` and `SPLIT` both
+   leave this loop rather than revising within it.
+
+## Verdicts
+
+Defined in [`contracts/terminals.json`](../../contracts/terminals.json). G2 emits
+`READY` / `NOT READY` / `BLOCKED`. G2.1 emits the council vocabulary. A `revise`-class verdict
+returns to the stage named in `revise_to`; a `redirect`-class verdict leaves the loop.
+
+## When a stage's skill is not installed
+
+Skills install à la carte, so a stage may name a skill the target environment does not have.
+Name the missing skill and skilldrop as its source, do the minimal inline version of that
+stage, and record that the stage ran degraded. A missing skill is never a reason to skip a
+**gate** — the gate is the loop's whole value.
+
+## Quality bar
+
+- **The gate decides, not the agent.** G2's verdict is `gate.py`'s exit code. An agent that reasons its way past a red gate has broken the loop, not passed it.
+- **The cap is honoured.** Three returns to `implement`, then `BLOCKED` with what did not converge. A fourth round is a defect in this loop, not diligence.
+- **Every stage leaves evidence.** Each stage names its skill, its verdict, and its round number, so the run is auditable after the fact rather than asserted.
+- **Acceptance criteria exist before `implement` starts.** A slice whose criteria a test cannot assert is not shaped; return it to `shape`.
+
+## Anti-patterns to avoid
+
+- ❌ **Calling a skill from inside a skill to "continue the loop."** The loop sequences; skills do not chain. This is what keeps every skill portable to Cursor, Kiro, and Aider.
+- ❌ **Editing `gate.py`, its config, or a test to turn G2 green.** That converts a mechanical gate into a decorative one.
+- ❌ **Treating `PROCEED WITH CONDITIONS` as `PROCEED`.** The conditions travel with the artifact; dropping them is how conditional approvals become unconditional ones.
+- ❌ **Running `decide` for every change.** G2.1 exists for escalated disagreement and the merge itself, not as a ceremony on top of a green gate.
+- ❌ **Starting at `implement` because the story "is obvious."** Unshaped work is what produces a diff nobody can review against anything.

package/loops/build/loop.json

@@ -0,0 +1,48 @@
+{
+  "$comment": "RFC-0028. This loop is docs/code-implement-verify.mmd promoted from a hand-maintained diagram into the machine-readable source that diagram is now generated from.",
+  "name": "build",
+  "version": "0.1.0",
+  "description": "Take an agreed requirement to merged code through a capped generate-verify-gate loop, with a mechanical gate that decides and a human who owns the merge. Use when the user wants to implement a story, fix a triaged bug, or ask whether a change is safe to merge.",
+  "entrypoint": "LOOP.md",
+  "kind": "loop",
+  "cap": 3,
+  "stages": [
+    {
+      "id": "shape",
+      "type": "generate",
+      "intent": "Turn a requirement or defect into one vertically-sliced unit of work with acceptance criteria.",
+      "skills": ["user-story-splitter", "bug-triage"]
+    },
+    {
+      "id": "implement",
+      "type": "generate",
+      "intent": "Write the code and its tests against the acceptance criteria, challenging the result each round.",
+      "skills": ["feature-implement-loop"]
+    },
+    {
+      "id": "verify",
+      "type": "verify",
+      "intent": "Judge the diff that now exists. The script decides; the panel explains.",
+      "skills": ["pre-merge-review"],
+      "gate": {
+        "id": "G2",
+        "kind": "mechanical",
+        "script": "skills/pre-merge-review/scripts/gate.py",
+        "verdicts": ["READY", "NOT READY", "BLOCKED"],
+        "revise_to": "implement"
+      }
+    },
+    {
+      "id": "decide",
+      "type": "gate",
+      "intent": "A human merges. Design disagreements surfaced at G2 are adjudicated here, not argued in the diff.",
+      "skills": ["council-review"],
+      "gate": {
+        "id": "G2.1",
+        "kind": "human",
+        "verdicts": ["PROCEED", "PROCEED WITH CONDITIONS", "REVISE", "RECONSIDER", "SPLIT", "BLOCKED"],
+        "revise_to": "shape"
+      }
+    }
+  ]
+}

package/loops/design/LOOP.md

@@ -0,0 +1,68 @@
+---
+name: design
+description: Take a ratified requirement to a recorded architectural decision — constraints, structure, diagrams, threats, then a panel that must agree before the decision is written down. Use when the user is designing a system, choosing an architecture, or asking how something should be built.
+---
+
+# design
+
+The loop with the worst reversibility profile in the repo. A discovery mistake costs a
+re-brief; a design mistake surfaces months later, in code nobody wants to unwind. That is why
+its gate is a **panel** — independent positions, surfaced cruxes, recorded dissent — and not
+a script, and why the decision is recorded only *after* the panel agrees.
+
+## Stages
+
+| # | Stage | Type | Skills | Gate |
+|---|---|---|---|---|
+| 1 | `constrain` | generate | [`nfr-spec`](../../skills/nfr-spec/SKILL.md) | — |
+| 2 | `shape` | generate | [`design-doc`](../../skills/design-doc/SKILL.md), [`architecture-diagrams`](../../skills/architecture-diagrams/SKILL.md) | — |
+| 3 | `threat` | verify | [`threat-model`](../../skills/threat-model/SKILL.md) | — |
+| 4 | `ratify` | gate | [`council-review`](../../skills/council-review/SKILL.md) | **G1** review |
+| 5 | `record` | generate | [`adr-generator`](../../skills/adr-generator/SKILL.md) | — |
+
+## How to run this loop
+
+1. **Constrain before shaping.** `nfr-spec` first, always. A design produced before its
+   quality targets exist gets judged on taste, and taste does not survive a review panel.
+2. **Shape prose and picture together.** `design-doc` and `architecture-diagrams` are one
+   artifact in two renderings. A diagram that disagrees with the doc is a defect in both.
+3. **Attack it before ratifying.** `threat-model` consumes the design directly. Running it
+   after G1 means the panel ratified something nobody had attacked.
+4. **Ratify at G1.** `council-review` seats the standing panel, takes positions *before*
+   cross-talk, names the cruxes, and records dissent with "what would change our mind".
+   `REVISE` returns to `shape`. `SPLIT` and `RECONSIDER` leave the loop.
+5. **Record last.** `adr-generator` writes the decision *after* it is a decision, with the
+   rejected options and the reasoning that killed them. An ADR written before G1 is a proposal
+   wearing an ADR's clothes.
+
+## Verdicts
+
+Defined in [`contracts/terminals.json`](../../contracts/terminals.json). `PROCEED WITH
+CONDITIONS` is the common outcome and the most abused: the conditions are part of the
+decision, and `record` must carry them into the ADR.
+
+## Non-interactive runs
+
+`council-review` can be run by an agent seating the panel itself, so G1 is satisfiable without
+a human. `SPLIT` is not — a genuine unresolved split needs a person. Emit
+`BLOCKED: need a decision-maker for <the crux>` and name the positions.
+
+## When a stage's skill is not installed
+
+Name the missing skill and skilldrop as its source, do the minimal inline version, and record
+the stage as degraded. If `council-review` is missing, do not skip G1 — run the panel inline
+from the design's own quality attributes and say the seating was improvised.
+
+## Quality bar
+
+- **Quality targets exist before structure does.** `nfr-spec` is stage 1 because a design without numbers can only be argued about.
+- **The ADR names what was rejected and why.** A decision record with one option is a description of what happened, not a decision.
+- **Dissent is recorded, not resolved away.** A panel that always reaches consensus is not seating real positions.
+- **The diagram and the doc say the same thing.** They are checked against each other before G1, not after someone builds from the wrong one.
+
+## Anti-patterns to avoid
+
+- ❌ **Writing the ADR before G1.** It pre-commits the panel to a decision it has not made, and every reviewer can feel it.
+- ❌ **Running `threat-model` after ratification.** The panel then ratified an unattacked design, which is the failure this ordering exists to prevent.
+- ❌ **Treating `PROCEED WITH CONDITIONS` as `PROCEED`.** The conditions must reach the ADR; dropping them is how a conditional approval silently becomes unconditional.
+- ❌ **Skipping `constrain` because the NFRs are "obvious".** Obvious targets are the ones nobody writes down and everybody remembers differently.

package/loops/design/loop.json

@@ -0,0 +1,47 @@
+{
+  "$comment": "RFC-0028. The loop with the worst reversibility profile: a design mistake surfaces months later in code nobody wants to unwind. That is why its gate is a panel, not a script.",
+  "name": "design",
+  "version": "0.1.0",
+  "description": "Take a ratified requirement to a recorded architectural decision — constraints, structure, diagrams, threats, then a panel that must agree before the decision is written down. Use when the user is designing a system, choosing an architecture, or asking how something should be built.",
+  "entrypoint": "LOOP.md",
+  "kind": "loop",
+  "cap": 3,
+  "stages": [
+    {
+      "id": "constrain",
+      "type": "generate",
+      "intent": "Name the quality targets before the structure, so the design is judged against numbers rather than taste.",
+      "skills": ["nfr-spec"]
+    },
+    {
+      "id": "shape",
+      "type": "generate",
+      "intent": "Write the design and render it. The prose and the picture are one artifact and must not disagree.",
+      "skills": ["design-doc", "architecture-diagrams"]
+    },
+    {
+      "id": "threat",
+      "type": "verify",
+      "intent": "Attack the design that now exists, before it is ratified rather than after it is built.",
+      "skills": ["threat-model"]
+    },
+    {
+      "id": "ratify",
+      "type": "gate",
+      "intent": "A standing panel takes independent positions before cross-talk, surfaces the cruxes, and records dissent.",
+      "skills": ["council-review"],
+      "gate": {
+        "id": "G1",
+        "kind": "review",
+        "verdicts": ["PROCEED", "PROCEED WITH CONDITIONS", "REVISE", "RECONSIDER", "SPLIT", "BLOCKED"],
+        "revise_to": "shape"
+      }
+    },
+    {
+      "id": "record",
+      "type": "generate",
+      "intent": "Write the decision down with its rejected alternatives, so the next team inherits the reasoning and not just the outcome.",
+      "skills": ["adr-generator"]
+    }
+  ]
+}

package/loops/discover/LOOP.md

@@ -0,0 +1,66 @@
+---
+name: discover
+description: Take raw signal — interviews, journeys, a strategy question — to a requirement a human has ratified, so design starts from an agreed problem rather than an assumed one. Use when the user is deciding what to build, scoping a feature, or turning stakeholder conversations into requirements.
+---
+
+# discover
+
+The first loop of the lifecycle, and the cheapest one to run twice. Everything downstream
+inherits whatever this loop got wrong, which is why it ends at a **human** gate rather than a
+script: no check can tell you that you solved the wrong problem well.
+
+## Stages
+
+| # | Stage | Type | Skills | Gate |
+|---|---|---|---|---|
+| 1 | `gather` | generate | [`requirements-interview`](../../skills/requirements-interview/SKILL.md), [`user-journey-map`](../../skills/user-journey-map/SKILL.md), [`strategy-analysis`](../../skills/strategy-analysis/SKILL.md) | — |
+| 2 | `structure` | generate | [`brief-intake`](../../skills/brief-intake/SKILL.md) | — |
+| 3 | `specify` | generate | [`prd-draft`](../../skills/prd-draft/SKILL.md) | — |
+| 4 | `ratify` | gate | [`doc-critique`](../../skills/doc-critique/SKILL.md) | **G0** human |
+
+## How to run this loop
+
+1. **Gather from whichever direction the signal arrives.** A stakeholder conversation →
+   `requirements-interview`. An existing experience with known friction → `user-journey-map`.
+   An open strategic question → `strategy-analysis`. Run one; running all three on the same
+   input produces three views of the same thing and no more information.
+2. **Structure once.** `brief-intake` tags every field `[explicit]` / `[implied]` /
+   `[inferred]` / `[missing]` with verbatim quotes. The tags are the deliverable — an
+   untagged brief hides which parts are somebody's assumption.
+3. **Resolve the missing before specifying.** `brief-intake` ends with what the downstream
+   skill will refuse to start without. Answer those; do not let `prd-draft` invent them.
+4. **Specify.** `prd-draft` turns the brief into numbered requirements a design can be held to.
+5. **Ratify at G0.** Run `doc-critique` against the PRD, then put the decision to a human.
+   The critique informs; the human decides. `REVISE` returns to `structure`, not to `specify`
+   — a weak PRD almost always means a thin brief.
+
+## Verdicts
+
+Defined in [`contracts/terminals.json`](../../contracts/terminals.json). G0 emits `PROCEED`,
+`PROCEED WITH CONDITIONS`, `REVISE`, `RECONSIDER`, or `BLOCKED`. `RECONSIDER` leaves the loop:
+the problem itself is wrong, and no amount of re-briefing fixes that.
+
+## Non-interactive runs
+
+With no human present, G0 cannot be satisfied. Emit `BLOCKED: need ratification of <the
+brief's central claim>` and stop. Do not self-ratify — a fabricated goal corrupts every
+artifact the other four loops produce.
+
+## When a stage's skill is not installed
+
+Name the missing skill and skilldrop as its source, do the minimal inline version of that
+stage, and record that it ran degraded. Never skip G0.
+
+## Quality bar
+
+- **Every field carries a provenance tag.** A brief that does not distinguish quoted from inferred cannot be ratified, only believed.
+- **`[missing]` is resolved or stated, never filled.** Inventing the goal, the customer, or the success measure is the one failure this loop exists to prevent.
+- **The requirements are numbered and testable.** "Fast" is not a requirement; a latency target is.
+- **A human ratifies before design starts.** G0 is the loop's only reason to exist — an unratified brief is a draft, whatever the critique said.
+
+## Anti-patterns to avoid
+
+- ❌ **Running all three `gather` skills to be thorough.** Three lenses on one input is not three inputs; pick the one that matches where the signal came from.
+- ❌ **Letting `prd-draft` fill a `[missing]` field.** That converts an open question into a fact nobody agreed to.
+- ❌ **Treating `doc-critique`'s `SHIP IT` as ratification.** The critique judges the document; G0 judges the problem.
+- ❌ **Returning `REVISE` to `specify`.** Re-writing the PRD from the same thin brief reproduces the same gaps in better prose.

package/loops/discover/loop.json

@@ -0,0 +1,41 @@
+{
+  "$comment": "RFC-0028. The first loop of the lifecycle: nothing is designed or built until a human has ratified what problem is being solved. Cheapest loop to redo and the most expensive to skip.",
+  "name": "discover",
+  "version": "0.1.0",
+  "description": "Take raw signal — interviews, journeys, a strategy question — to a requirement a human has ratified, so design starts from an agreed problem rather than an assumed one. Use when the user is deciding what to build, scoping a feature, or turning stakeholder conversations into requirements.",
+  "entrypoint": "LOOP.md",
+  "kind": "loop",
+  "cap": 3,
+  "stages": [
+    {
+      "id": "gather",
+      "type": "generate",
+      "intent": "Collect the raw signal from whichever direction it arrives: a stakeholder conversation, an existing user journey, or a strategic question.",
+      "skills": ["requirements-interview", "user-journey-map", "strategy-analysis"]
+    },
+    {
+      "id": "structure",
+      "type": "generate",
+      "intent": "Turn the mess into one brief with every field tagged explicit / implied / inferred / missing, so downstream can see what was assumed.",
+      "skills": ["brief-intake"]
+    },
+    {
+      "id": "specify",
+      "type": "generate",
+      "intent": "Turn the ratified brief into numbered requirements a design can be held to.",
+      "skills": ["prd-draft"]
+    },
+    {
+      "id": "ratify",
+      "type": "gate",
+      "intent": "A human agrees this is the problem worth solving. The critique informs that decision; it does not make it.",
+      "skills": ["doc-critique"],
+      "gate": {
+        "id": "G0",
+        "kind": "human",
+        "verdicts": ["PROCEED", "PROCEED WITH CONDITIONS", "REVISE", "RECONSIDER", "BLOCKED"],
+        "revise_to": "structure"
+      }
+    }
+  ]
+}

package/loops/operate/LOOP.md

@@ -0,0 +1,69 @@
+---
+name: operate
+description: Take a shipped service through detection, response, and learning — instrument it, write the runbook, communicate the incident, then feed the postmortem's deltas back into the runbook. Use when the user is preparing to run a service, is in an incident, or is writing a postmortem.
+---
+
+# operate
+
+The only loop whose failures are **irreversible and live**. The other four can be re-run at
+the cost of time; this one runs while real users are affected. Its feedback edge is the point:
+`postmortem-generator` emits runbook deltas phrased as edits, and those go straight back into
+`document`. An incident that changes no procedure has not been learned from.
+
+## Stages
+
+| # | Stage | Type | Skills | Gate |
+|---|---|---|---|---|
+| 1 | `instrument` | generate | [`observability-plan`](../../skills/observability-plan/SKILL.md) | — |
+| 2 | `document` | generate | [`runbook-generator`](../../skills/runbook-generator/SKILL.md) | — |
+| 3 | `respond` | generate | [`incident-comms`](../../skills/incident-comms/SKILL.md) | — |
+| 4 | `learn` | verify | [`postmortem-generator`](../../skills/postmortem-generator/SKILL.md) | **G3** human |
+
+## How to run this loop
+
+1. **Instrument first.** `observability-plan` decides what is measured and what pages a human.
+   You cannot respond to what you never detected, and you cannot write a runbook entry for an
+   alert that does not exist.
+2. **Write the runbook per alert.** Each alert the previous stage defined maps to a
+   `runbook-generator` entry. An alert with no procedure wakes someone who then has to think.
+3. **Respond to the audience the incident actually has.** `incident-comms` is staged —
+   detect, mitigate, resolve — and the stage determines the message. Writing a resolution
+   update during mitigation is the most common error here.
+4. **Learn at G3.** `postmortem-generator` analyses blamelessly and ends with runbook deltas.
+   A human signs off that the incident is closed. `REVISE` returns to `document`: the deltas
+   are the loop's output, and applying them is what closes it.
+
+Entering mid-loop is normal and expected. An incident starts at `respond`; a new service
+starts at `instrument`. Do not replay earlier stages for their own sake.
+
+## Verdicts
+
+Defined in [`contracts/terminals.json`](../../contracts/terminals.json). G3 emits `PROCEED`,
+`PROCEED WITH CONDITIONS`, `REVISE`, or `BLOCKED`. `PROCEED WITH CONDITIONS` means the
+incident is closed but named follow-ups are outstanding — they travel with the postmortem.
+
+## Non-interactive runs
+
+Never fabricate incident facts — timings, impact, customer counts, root cause. When the
+timeline is incomplete, emit `BLOCKED: need <the missing facts>` and name them. A confident
+postmortem built on guessed impact is worse than no postmortem.
+
+## When a stage's skill is not installed
+
+Name the missing skill and skilldrop as its source, do the minimal inline version, and record
+the stage as degraded. During a live incident, prefer the degraded inline version over
+stopping to install anything.
+
+## Quality bar
+
+- **Every alert has a runbook entry.** An alert that pages someone with no procedure is an interruption, not a signal.
+- **The postmortem ends in runbook deltas.** Analysis with no procedural change is a story about an outage.
+- **Comms match the incident's actual stage.** Detect, mitigate, and resolve have different audiences and different truths.
+- **Blameless means blameless.** Naming a person is a defect in the postmortem; naming a missing guardrail is the point.
+
+## Anti-patterns to avoid
+
+- ❌ **Writing the runbook before the observability plan.** Procedures for alerts that do not exist, and none for the alerts that do.
+- ❌ **Skipping `learn` because the incident was small.** Small incidents are where the cheap runbook deltas are.
+- ❌ **Guessing impact numbers to finish the postmortem.** State the gap; a postmortem's value is entirely in its accuracy.
+- ❌ **Replaying `instrument` during a live incident.** Enter at `respond`; the loop is not a checklist to complete in order.

package/loops/operate/loop.json

@@ -0,0 +1,41 @@
+{
+  "$comment": "RFC-0028. The only loop whose failures are irreversible and live. Its feedback edge is real and already documented in the repo: postmortem-generator emits runbook deltas phrased as edits for runbook-generator.",
+  "name": "operate",
+  "version": "0.1.0",
+  "description": "Take a shipped service through detection, response, and learning — instrument it, write the runbook, communicate the incident, then feed the postmortem's deltas back into the runbook. Use when the user is preparing to run a service, is in an incident, or is writing a postmortem.",
+  "entrypoint": "LOOP.md",
+  "kind": "loop",
+  "cap": 3,
+  "stages": [
+    {
+      "id": "instrument",
+      "type": "generate",
+      "intent": "Decide what is measured and what pages a human. You cannot respond to what you never detected.",
+      "skills": ["observability-plan"]
+    },
+    {
+      "id": "document",
+      "type": "generate",
+      "intent": "Write the procedure the on-call follows at 3am, per alert the previous stage defined.",
+      "skills": ["runbook-generator"]
+    },
+    {
+      "id": "respond",
+      "type": "generate",
+      "intent": "Communicate during the incident, to the audience that needs it, at the stage the incident is actually in.",
+      "skills": ["incident-comms"]
+    },
+    {
+      "id": "learn",
+      "type": "verify",
+      "intent": "Analyse blamelessly and emit runbook deltas. An incident that changes no procedure has not been learned from.",
+      "skills": ["postmortem-generator"],
+      "gate": {
+        "id": "G3",
+        "kind": "human",
+        "verdicts": ["PROCEED", "PROCEED WITH CONDITIONS", "REVISE", "BLOCKED"],
+        "revise_to": "document"
+      }
+    }
+  ]
+}

package/loops/ship-a-draft/LOOP.md

@@ -0,0 +1,62 @@
+---
+name: ship-a-draft
+description: Take raw mess to a stakeholder-ready artifact by wrapping any skilldrop generator in the two passes either side of it — structured intake before, critique and machine-residue scrub after. Use when the user has notes, a transcript, or a ticket and wants a finished document rather than a first draft.
+---
+
+# ship-a-draft
+
+A **wrapper**, not a lifecycle loop. Its centre stage is whichever generator the user actually
+needs — an ADR, a design doc, a runbook, a deck, an exec summary. The wrapper contributes the
+two passes every generator otherwise leaves to chance: collect the input properly before, and
+check the argument and the surface after.
+
+## Stages
+
+| # | Stage | Type | Skills | Gate |
+|---|---|---|---|---|
+| 1 | `intake` | generate | [`brief-intake`](../../skills/brief-intake/SKILL.md) | — |
+| 2 | `draft` | generate | any generator (`*`) | — |
+| 3 | `critique` | verify | [`doc-critique`](../../skills/doc-critique/SKILL.md) | **G4** review |
+| 4 | `polish` | verify | [`output-hygiene`](../../skills/output-hygiene/SKILL.md) | — |
+
+## How to run this wrapper
+
+1. **Pick the generator first.** The brief is shaped *for a target*, so `draft` is chosen
+   before `intake` runs, not after. `brief-intake`'s own routing table maps trigger phrases to
+   targets; use it.
+2. **Collect once.** Run `brief-intake`. Every field is tagged `[explicit]` / `[implied]` /
+   `[inferred]` / `[missing]`, and its "Missing for downstream" section predicts what the
+   chosen generator will refuse to start without. Resolve those before drafting.
+3. **Draft.** Run the chosen generator on the brief. It is a normal skilldrop skill with its
+   own quality bar — this wrapper does not override it.
+4. **Critique at G4.** Run `doc-critique`, which dispatches to the same rubric the generator
+   was held to. `MAJOR REWRITE` returns to `intake` (not to `draft` — a rewrite usually means
+   the input was wrong, not the prose). `WRONG ARTIFACT` leaves the wrapper entirely.
+5. **Polish last.** Run `output-hygiene` only once the argument is settled. It is a surface
+   pass; running it on a draft that is about to be rewritten wastes it.
+
+## Verdicts
+
+Defined in [`contracts/terminals.json`](../../contracts/terminals.json). G4 emits the critique
+vocabulary. `SHIP WITH CHANGES` carries its changes forward to `polish`; it does not mean the
+changes are optional.
+
+## When a stage's skill is not installed
+
+Name the missing skill and skilldrop as its source, do the minimal inline version of that
+stage, and say the stage ran degraded. Do not skip G4 — an unreviewed artifact is the failure
+mode this wrapper exists to prevent.
+
+## Quality bar
+
+- **The generator is chosen before intake runs.** A brief collected for no particular target is a summary, and downstream will reject it for missing fields.
+- **`polish` runs after the argument is settled, never before.** Scrubbing prose that is about to be rewritten is wasted work and hides the rewrite.
+- **A `[missing]` tag is resolved or stated, never silently filled.** Fabricating a goal, an owner, or a decision corrupts every downstream artifact.
+- **Every run ends by naming what was not touched.** `output-hygiene`'s "Not touched" section is part of the deliverable, not an appendix.
+
+## Anti-patterns to avoid
+
+- ❌ **Running `polish` as the whole review.** Clean prose with a broken argument still fails; that is what G4 is for.
+- ❌ **Skipping `intake` because the input "is already structured."** A Slack thread that looks organized is still untagged — nobody downstream can tell what was inferred.
+- ❌ **Looping `critique` → `draft` instead of `critique` → `intake`.** Re-drafting from the same incomplete brief reproduces the same gaps with new words.
+- ❌ **Treating `WRONG ARTIFACT` as a severe `MAJOR REWRITE`.** It is a redirect: the user wanted a different document, and revising this one cannot get there.

package/loops/ship-a-draft/loop.json

@@ -0,0 +1,41 @@
+{
+  "$comment": "RFC-0028. This wrapper is docs/knowledge-work-pipeline.mmd promoted from a hand-maintained diagram into the machine-readable source that diagram is now generated from. It is a wrapper, not a loop: the generator at its centre is chosen at run time from whichever artifact the user actually wants.",
+  "name": "ship-a-draft",
+  "version": "0.1.0",
+  "description": "Take raw mess to a stakeholder-ready artifact by wrapping any skilldrop generator in the two passes either side of it — structured intake before, critique and machine-residue scrub after. Use when the user has notes, a transcript, or a ticket and wants a finished document rather than a first draft.",
+  "entrypoint": "LOOP.md",
+  "kind": "wrapper",
+  "cap": 3,
+  "stages": [
+    {
+      "id": "intake",
+      "type": "generate",
+      "intent": "Collect the raw input once, into the shape the chosen generator expects, tagging every field explicit / implied / inferred / missing.",
+      "skills": ["brief-intake"]
+    },
+    {
+      "id": "draft",
+      "type": "generate",
+      "intent": "Run the generator the brief was shaped for. Any artifact skill is legal here — that choice is the wrapper's whole point.",
+      "skills": ["*"]
+    },
+    {
+      "id": "critique",
+      "type": "verify",
+      "intent": "Review the draft against the same rubric the generator was held to.",
+      "skills": ["doc-critique"],
+      "gate": {
+        "id": "G4",
+        "kind": "review",
+        "verdicts": ["SHIP IT", "SHIP WITH CHANGES", "MAJOR REWRITE", "WRONG ARTIFACT", "BLOCKED"],
+        "revise_to": "intake"
+      }
+    },
+    {
+      "id": "polish",
+      "type": "verify",
+      "intent": "Strip what the machine left behind before the artifact leaves the building. Surface pass only — never a substitute for the critique above.",
+      "skills": ["output-hygiene"]
+    }
+  ]
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "skilldrop-cli",
-  "version": "0.11.5",
-  "description": "Portable AI-agent skills for the deliverables knowledge workers ship — diagrams, ADRs, PRDs, runbooks, decks, reviews — installable into Claude Code, Cursor, Kiro, and any IDE that takes custom instructions. One command per skill or per role-based pack.",
+  "version": "0.11.7",
+  "description": "Portable AI-agent skills for the deliverables knowledge workers ship \u2014 diagrams, ADRs, PRDs, runbooks, decks, reviews \u2014 installable into Claude Code, Cursor, Kiro, and any IDE that takes custom instructions. One command per skill or per role-based pack.",
   "author": {
     "name": "Sanjay Ananthanarayan",
     "url": "https://github.com/sananthanarayan"
@@ -13,6 +13,8 @@
     "bin/",
     "skills/",
     "agents/",
+    "loops/",
+    "contracts/",
     "packs.json",
     "model-routing.json"
   ],

package/skills/architecture-diagrams/manifest.json

@@ -14,6 +14,9 @@
   "related": [
     "figma-diagrams"
   ],
+  "handoff": [
+    { "to": "figma-diagrams", "when": "the diagram needs to live where designers work", "purpose": "Push the rendered diagram into Figma.", "fallback": "If figma-diagrams is absent, leave the Mermaid source and say it needs manual import; never fabricate a Figma URL." }
+  ],
   "tags": [
     "diagrams",
     "mermaid",

package/skills/bug-triage/manifest.json

@@ -6,6 +6,9 @@
   "deps": { "npm": [], "pip": [] },
   "env": { "required": [], "optional": [] },
   "related": ["feature-implement-loop", "postmortem-generator", "user-story-splitter"],
+  "handoff": [
+    { "to": "feature-implement-loop", "when": "the defect is reproduced and scoped", "purpose": "Fix the triaged defect through the same capped loop a story gets.", "fallback": "If feature-implement-loop is absent, fix inline with a regression test that fails before the fix." }
+  ],
   "tags": ["bug-triage", "bug-report", "ticket", "qa", "repro", "severity"],
   "model": { "tier": "standard", "rationale": "Extraction plus judgment calls (severity vs priority, hypothesis ranking) — same shape as brief-intake: above light, below heavy." }
 }

package/skills/design-doc/manifest.json

@@ -6,6 +6,9 @@
   "deps": { "npm": [], "pip": [] },
   "env": { "required": [], "optional": [] },
   "related": ["architecture-diagrams"],
+  "handoff": [
+    { "to": "architecture-diagrams", "when": "the design is written and needs rendering", "purpose": "Render the prose as a diagram that must not disagree with it.", "fallback": "If architecture-diagrams is absent, emit Mermaid inline and check every node against a claim in the doc." }
+  ],
   "tags": ["design-doc", "documentation", "engineering", "review"],
   "model": { "tier": "standard", "rationale": "Synthesizes a design doc from a brief. Escalates to opus on big or genuinely contested inputs." }
 }

package/skills/feature-implement-loop/manifest.json

@@ -6,6 +6,9 @@
   "deps": { "npm": [], "pip": [] },
   "env": { "required": [], "optional": [] },
   "related": ["design-doc", "devils-advocate", "doc-critique", "pre-merge-review"],
+  "handoff": [
+    { "to": "pre-merge-review", "when": "the code exists and the question is whether it can merge", "purpose": "Judge the diff that now exists against a mechanical gate.", "fallback": "If pre-merge-review is absent, run the repo's own lint and tests and honour the exit code; do not self-certify." }
+  ],
   "tags": ["dev-workflow", "implementation", "tdd", "acceptance-criteria", "adversarial", "self-correcting", "code-generation"],
   "model": { "tier": "standard", "rationale": "Code + test generation against acceptance criteria. The adversarial pass delegates to devils-advocate (heavy) where available; the loop itself is generation." }
 }

package/skills/incident-comms/manifest.json

@@ -6,6 +6,9 @@
   "deps": { "npm": [], "pip": [] },
   "env": { "required": [], "optional": [] },
   "related": ["postmortem-generator", "runbook-generator"],
+  "handoff": [
+    { "to": "postmortem-generator", "when": "the incident is resolved", "purpose": "Analyse blamelessly and emit runbook deltas.", "fallback": "If postmortem-generator is absent, write the timeline, the contributing factors, and the procedural changes inline." }
+  ],
   "tags": ["incident", "communication", "status-page", "outage", "stakeholder", "sre"],
   "model": { "tier": "standard", "rationale": "Audience-segmented message generation under a strict don't-retract discipline. Same shape as exec-summary/audience-profile — translation and altitude, not adversarial reasoning." }
 }

package/skills/nfr-spec/manifest.json

@@ -6,6 +6,11 @@
   "deps": { "npm": [], "pip": [] },
   "env": { "required": [], "optional": [] },
   "related": ["capacity-cost-model", "design-doc", "prd-draft", "test-plan-generator", "threat-model"],
+  "handoff": [
+    { "to": "design-doc", "when": "the quality targets are set", "purpose": "Design against the stated numbers rather than against taste.", "fallback": "If design-doc is absent, restate each target beside the design choice that serves it." },
+    { "to": "threat-model", "when": "the design has a trust boundary worth attacking", "purpose": "Attack the design before it is ratified.", "fallback": "If threat-model is absent, list the trust boundaries and one abuse case per boundary inline." },
+    { "to": "test-plan-generator", "when": "the targets need verifying, not just stating", "purpose": "Turn each quality target into a coverage entry.", "fallback": "If test-plan-generator is absent, name the test that would falsify each target." }
+  ],
   "tags": ["nfr", "requirements", "slo", "performance", "availability", "quality-attributes"],
   "model": { "tier": "standard", "rationale": "Rubric-driven sweep with archetype defaults; the judgment is calibrating targets to business reality. Bounded by the catalog; escalate via ambiguous-input on contested SLOs." }
 }

package/skills/observability-plan/manifest.json

@@ -6,6 +6,10 @@
   "deps": { "npm": [], "pip": [] },
   "env": { "required": [], "optional": [] },
   "related": ["capacity-cost-model", "incident-comms", "nfr-spec", "postmortem-generator", "runbook-generator", "success-metrics"],
+  "handoff": [
+    { "to": "runbook-generator", "when": "the alerts are defined and each needs a procedure", "purpose": "Write the procedure the on-call follows per alert.", "fallback": "If runbook-generator is absent, write one numbered procedure per alert inline." },
+    { "to": "incident-comms", "when": "detection fired and an audience needs telling", "purpose": "Communicate at the stage the incident is actually in.", "fallback": "If incident-comms is absent, state the stage, the impact, and the next update time inline." }
+  ],
   "tags": ["observability", "slo", "sli", "alerting", "monitoring", "sre"],
   "model": { "tier": "standard", "rationale": "Methodology synthesis against fixed SRE practices (golden signals, burn-rate alerting, pillar split). SLO calibration needs judgment but is bounded; escalate via ambiguous-input on contested reliability targets." }
 }

package/skills/output-hygiene/manifest.json

@@ -15,6 +15,9 @@
     "doc-critique",
     "ai-usage-policy"
   ],
+  "handoff": [
+    { "to": "doc-critique", "when": "the surface is clean and the draft is still weak", "purpose": "The fault is the argument, not the residue.", "fallback": "If doc-critique is absent, name the weakest claim and what evidence it needs." }
+  ],
   "tags": [
     "hygiene",
     "cleanup",

package/skills/postmortem-generator/manifest.json

@@ -6,6 +6,9 @@
   "deps": { "npm": [], "pip": [] },
   "env": { "required": [], "optional": [] },
   "related": ["runbook-generator"],
+  "handoff": [
+    { "to": "runbook-generator", "when": "the postmortem produced runbook deltas", "purpose": "Apply the deltas as edits to the existing runbook.", "fallback": "If runbook-generator is absent, phrase each delta as a concrete before/after edit so a human can apply it." }
+  ],
   "tags": ["postmortem", "incident", "rca", "sre", "blameless", "outage"],
   "model": { "tier": "standard", "rationale": "Synthesizes a structured doc from incident notes. Contributing-factor chains need judgment but are bounded; escalate via large-input on huge scrollbacks." }
 }

package/skills/prd-draft/manifest.json

@@ -6,6 +6,11 @@
   "deps": { "npm": [], "pip": [] },
   "env": { "required": [], "optional": [] },
   "related": ["brief-intake", "bug-triage", "business-case", "design-doc", "nfr-spec", "success-metrics", "user-story-splitter"],
+  "handoff": [
+    { "to": "nfr-spec", "when": "the functional requirements are agreed", "purpose": "Set the quality targets the design will be judged against.", "fallback": "If nfr-spec is absent, state latency, availability and scale targets inline as numbers, not adjectives." },
+    { "to": "user-story-splitter", "when": "the requirements are ready to become units of work", "purpose": "Split into vertically-sliced stories with acceptance criteria.", "fallback": "If user-story-splitter is absent, slice inline and give each story acceptance criteria a test can assert." },
+    { "to": "design-doc", "when": "the what is agreed and the how is open", "purpose": "Design the system that satisfies these requirements.", "fallback": "If design-doc is absent, write the approach, the alternatives, and the trade-offs inline." }
+  ],
   "tags": ["prd", "requirements", "product", "discovery", "moscow", "non-goals"],
   "model": { "tier": "standard", "rationale": "Synthesizes a structured requirements doc from a brief. The solution-language discipline needs care; bounded by the template. Escalate via ambiguous-input on contested scope." }
 }

package/skills/pre-merge-review/manifest.json

@@ -6,6 +6,9 @@
   "deps": { "npm": [], "pip": [] },
   "env": { "required": [], "optional": [] },
   "related": ["feature-implement-loop", "devils-advocate", "council-review", "doc-critique"],
+  "handoff": [
+    { "to": "council-review", "when": "the blocker is a design disagreement, not a defect", "purpose": "Adjudicate the disagreement outside the diff.", "fallback": "If council-review is absent, state each position and its strongest counter inline, and name the crux the decision turns on." }
+  ],
   "tags": ["dev-workflow", "code-review", "pre-merge", "quality-gate", "subagents", "production-readiness"],
   "model": { "tier": "standard", "rationale": "Coordination: runs a deterministic gate script, dispatches the (heavy) reviewer subagents, and renders a rule-based go/no-go. The adversarial reasoning is delegated to the panel, so the skill itself is orchestration, not deep judgment." }
 }

package/skills/requirements-interview/manifest.json

@@ -6,6 +6,9 @@
   "deps": { "npm": [], "pip": [] },
   "env": { "required": [], "optional": [] },
   "related": ["brief-intake", "decision-log", "prd-draft"],
+  "handoff": [
+    { "to": "brief-intake", "when": "the interview is done and the notes are raw", "purpose": "Collect the transcript into a tagged brief before any generator sees it.", "fallback": "If brief-intake is absent, tag each captured field [explicit]/[implied]/[inferred]/[missing] inline and say which downstream skill the brief is shaped for." }
+  ],
   "tags": ["discovery", "interviews", "requirements", "elicitation", "stakeholders", "user-research"],
   "model": { "tier": "standard", "rationale": "Question banks are rubric-shaped, but ranking by design impact and deriving falsification conditions for the specific feature is synthesis — above light." }
 }

package/skills/strategy-analysis/manifest.json

@@ -6,6 +6,10 @@
   "deps": { "npm": [], "pip": [] },
   "env": { "required": [], "optional": [] },
   "related": ["business-case", "okr-cascade", "prfaq", "tech-comparison-matrix"],
+  "handoff": [
+    { "to": "tech-comparison-matrix", "when": "the options are named and need comparing on stated criteria", "purpose": "Score the named options against weighted criteria.", "fallback": "If tech-comparison-matrix is absent, build a plain criteria-by-option table inline and state the weights." },
+    { "to": "business-case", "when": "the direction is chosen and needs costing before approval", "purpose": "Cost the chosen option against a do-nothing baseline.", "fallback": "If business-case is absent, state option 0 and the three cost layers (build, run, opportunity) inline." }
+  ],
   "tags": ["strategy", "swot", "tows", "five-forces", "pestle", "competitive-analysis", "market-analysis"],
   "model": { "tier": "heavy", "rationale": "Framework selection plus evidenced multi-factor judgment ending in a ranked, committal verdict. Cheaper models fill cells with generic filler, skip the TOWS crossings, and refuse to take a side. Never downgrade." }
 }

package/skills/user-journey-map/manifest.json

@@ -6,6 +6,10 @@
   "deps": { "npm": [], "pip": [] },
   "env": { "required": [], "optional": [] },
   "related": ["architecture-diagrams", "prd-draft", "reverse-architecture", "success-metrics", "user-story-splitter"],
+  "handoff": [
+    { "to": "prd-draft", "when": "a friction point on the journey is worth fixing", "purpose": "Turn the named friction into numbered requirements.", "fallback": "If prd-draft is absent, write the requirements inline as numbered, testable statements and note that prd-draft in skilldrop would structure them." },
+    { "to": "success-metrics", "when": "the fix needs a measure before it is built", "purpose": "Design the measurement for the journey step being changed.", "fallback": "If success-metrics is absent, state one baseline and one target per fixed step inline." }
+  ],
   "tags": ["journey-map", "customer-experience", "ux", "touchpoints", "mermaid", "personas"],
   "model": { "tier": "standard", "rationale": "Structured synthesis into a fixed four-row stage model plus bounded ranking judgment. Escalate via ambiguous-input when the persona or outcome is contested or research inputs conflict." }
 }

package/skills/user-story-splitter/manifest.json

@@ -6,6 +6,9 @@
   "deps": { "npm": [], "pip": [] },
   "env": { "required": [], "optional": [] },
   "related": ["feature-implement-loop"],
+  "handoff": [
+    { "to": "feature-implement-loop", "when": "a story has acceptance criteria a test can assert", "purpose": "Implement the slice through a capped generate-verify loop.", "fallback": "If feature-implement-loop is absent, implement inline but still challenge the result and cap the rounds at three." }
+  ],
   "tags": ["user-stories", "agile", "backlog", "acceptance-criteria", "planning", "sprint"],
   "model": { "tier": "standard", "rationale": "Decomposes an epic into INVEST slices with testable ACs. Structured synthesis; escalation rules cover large or contradictory PRDs." }
 }