skilldrop-cli 0.11.5 → 0.11.6

package/README.md

@@ -20,9 +20,18 @@ 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.
+
+| Loop | Takes | Gate | Produces |
+|---|---|---|---|
+| [`build`](loops/build/LOOP.md) | an agreed requirement or triaged defect | **G2** mechanical — `pre-merge-review`'s gate script decides | merged code |
+| [`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.
+
+### `ship-a-draft` — the knowledge-work loop
 
 Raw input becomes a stakeholder-ready artifact — and loops back through review until it's approved.
 
@@ -45,7 +54,7 @@ flowchart LR
     crit == "approved" ==> ART
 ```
 
-### Code: implement and verify
+### `build` — code: implement and verify
 
 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.
 

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/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.6",
+  "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"
   ],