skilldrop-cli 0.9.2 → 0.9.3

package/README.md

@@ -3,9 +3,9 @@
 [![npm](https://img.shields.io/npm/v/skilldrop-cli)](https://www.npmjs.com/package/skilldrop-cli)
 [![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
-**[Browse the catalogue →](https://sananthanarayan.github.io/skilldrop/)** — all 55 skills, filterable by pack, tag, and model tier.
+**[Browse the catalogue →](https://sananthanarayan.github.io/skilldrop/)** — all 56 skills, filterable by pack, tag, and model tier.
 
-**55 portable AI-agent skills for the deliverables knowledge workers actually ship** — diagrams, design docs, ADRs, PRDs, runbooks, decks, decision logs, threat models, adversarial reviews — installable into **Claude Code**, **Cursor**, **Kiro**, **Codex**, **GitHub Copilot**, and any AI tool that accepts custom instructions, one skill or one role-based pack at a time:
+**56 portable AI-agent skills for the deliverables knowledge workers actually ship** — diagrams, design docs, ADRs, PRDs, runbooks, decks, decision logs, threat models, adversarial reviews — installable into **Claude Code**, **Cursor**, **Kiro**, **Codex**, **GitHub Copilot**, and any AI tool that accepts custom instructions, one skill or one role-based pack at a time:
 
 ```bash
 npx skilldrop-cli install --pack product-manager     # or: solution-architect, dev-team,
@@ -160,6 +160,7 @@ Designing the agentic systems themselves — the loops, orchestrations, and budg
 
 | Skill | What it does |
 |---|---|
+| [`agent-adoption-stage`](skills/agent-adoption-stage/SKILL.md) | Place an engineering team on the agentic-coding ladder — **0 gated → 1 assisted (~1 agent) → 2 parallel (~10) → 3 supervised autonomy (~100) → 4 intent-steered (~1000+)** — from observables (agents in flight, who writes the code, what still gets reviewed), never from licence counts or ambition. The load-bearing idea is that **the bottleneck moves**: your attention → review throughput → trust in the loop → finding the work to automate, so the fix that unlocked the last step does nothing for the next. Forces **exactly one stage** and **exactly one unlock**, names the guardrail to *retire* (reading every diff is right at stage 1 and arithmetically impossible at stage 3), and routes each unlock to the skill that implements it (`pre-merge-review`, `agent-loop-design`, `subagent-design`, `agent-budget`). Adapted from Boris Cherny's *Steps of AI Adoption*, stated as capabilities rather than products so it survives the next vendor release. |
 | [`ai-readiness-assessment`](skills/ai-readiness-assessment/SKILL.md) | Score readiness to adopt AI across **six fixed dimensions** — data, tooling, skills, governance, process, culture — each 0–4 with a **one-line evidence reference**, or `[insufficient evidence]` rather than a guessed middle number. Gaps are ranked by **what blocks first**, not by lowest score, with the dependency named ("Skills can't move until Tooling ≥ 2"), and each carries a first action and an owner *role*. Ends with a posture sentence that takes a position and names what would change it — never a bare maturity label, because "you are Level 2 of 5" is not something a leader can fund. |
 | [`ai-use-case-triage`](skills/ai-use-case-triage/SKILL.md) | Rank candidate AI use cases on value × feasibility × risk with the **weights shown** (default 40/35/25). Each candidate is restated as *a workflow and a person*, never a technology; feasibility asks whether the output can be **verified before it matters**, not whether a model can produce it. Produces a recommended first slice with an **observable kill condition** and a time box, plus a mandatory **not-yet list** where every rejection carries the condition that would promote it. A portfolio with no rejections hasn't triaged anything. |
 | [`ai-adoption-rollout`](skills/ai-adoption-rollout/SKILL.md) | Plan the **human** rollout (the counterpart to `migration-plan`'s technical one) — cohorts smallest-first with a reason each is next, per-cohort hands-on enablement built from what the pilot actually got stuck on, champions as roles **with protected hours**, and an adoption **gate per wave** (observable + threshold + bake time + rollback). The comms plan must state explicitly **what will not change** about headcount and evaluation; silence there is read as bad news and is the biggest driver of quiet non-adoption. Licences activated is not adoption. |

package/model-routing.json

@@ -115,6 +115,7 @@
     "sonar-review": { "tier": "standard", "rationale": "Formats Sonar API findings into a report. The hard analysis is Sonar's; this is synthesis. Escalate on very large diffs." },
     "ai-usage-report": { "tier": "standard", "rationale": "Tabulates telemetry into a report. Mostly mechanical, but the 'AI theater' effectiveness call needs judgment." },
     "ai-readiness-assessment": { "tier": "standard", "rationale": "Scores six fixed dimensions against a rubric and ranks gaps by blocking order. Bounded structured judgment, not adversarial reasoning; escalate via ambiguous-input when the evidence is thin or contested." },
+    "agent-adoption-stage": { "tier": "standard", "rationale": "Places a team on a fixed 5-stage ladder from observables and routes one unlock. Bounded diagnosis against a rubric; escalate via ambiguous-input when the observables are contradictory or the distribution is heavily skewed." },
     "ai-use-case-triage": { "tier": "standard", "rationale": "Scores candidates on weighted axes and forces a rejection list. Structured comparison with stated weights; escalate via ambiguous-input when candidates are numerous or the value data is contested." },
     "ai-adoption-rollout": { "tier": "standard", "rationale": "Generates a phased people-rollout with gates and enablement from a stated tool and population. Structured planning against a fixed shape; escalate via ambiguous-input for large or politically contested rollouts." },
     "ai-usage-policy": { "tier": "standard", "rationale": "Drafts a policy document against a fixed structure (tiers, behaviours, review matrix, exception route). Bounded generation; escalate via ambiguous-input where a regulatory regime is named or contested." },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skilldrop-cli",
-  "version": "0.9.2",
+  "version": "0.9.3",
   "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.",
   "author": {
     "name": "Sanjay Ananthanarayan",

package/packs.json

@@ -96,7 +96,8 @@
         "ai-readiness-assessment",
         "ai-use-case-triage",
         "ai-adoption-rollout",
-        "ai-usage-policy"
+        "ai-usage-policy",
+        "agent-adoption-stage"
       ]
     }
   }

package/skills/agent-adoption-stage/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: agent-adoption-stage
+description: Place an engineering team on the agentic-coding adoption ladder (0 gated → 4 intent-steered) using observables like agents-in-flight per engineer and who writes the code, name the one bottleneck gating the next step, prescribe the single next unlock, and state which current guardrail must change. Use when a leader asks "how far along are we with coding agents", "why has our AI adoption plateaued", or "what do we do next to get more out of this". Do NOT use to assess organisational preconditions like data, policy, and culture (that's ai-readiness-assessment) or to plan a tool's human rollout (that's ai-adoption-rollout).
+---
+
+# agent-adoption-stage
+
+Answer one question honestly: **which rung is this team actually on, and what is the single next thing that moves them up?** Not a scorecard, not a tool list — a placement backed by observables, the bottleneck that gates the next step, and one unlock.
+
+Adapted from Boris Cherny's *Steps of AI Adoption* (2026-07-16). The stage names and the bottleneck-shift are his; the guardrail changes and the routing here are skilldrop's, and everything is stated as a **capability** rather than a product so it stays true across tools and across years.
+
+The load-bearing idea: **the bottleneck moves.** Each stage is limited by something different, so a fix that unlocked the last step does nothing for the next one. Diagnosing the *current* bottleneck is the whole job; the stage number is just its index.
+
+## The ladder
+
+| Stage | Shape | Observable | The bottleneck |
+|---|---|---|---|
+| **0 · Gated** | no real access | tools unapproved, gateways slow, no path to run outputs | approval process — a legacy security posture optimising cost-per-token instead of outcomes |
+| **1 · Assisted** | you + one agent | **~1 agent**, synchronous, you read nearly every change | **your attention.** Low trust and no self-verification, so you watch instead of moving on |
+| **2 · Parallel** | you orchestrate | **~5–10 agents**, isolated checkouts, agent checks its own work first | **review throughput.** You're checking six streams instead of writing one |
+| **3 · Supervised autonomy** | manager of managers | **~100**, agent writes nearly all code, agents start agents | **trust in the loop**, and token efficiency as volume climbs |
+| **4 · Intent-steered** | steer by intent | **~1000+**, loop closed, monitor by exception | **finding and automating the work**, with the right guardrail per work type |
+
+## How to respond
+
+1. **Place the team on exactly one stage, from observables.** Ask for (or extract) three things: how many agents a typical engineer has in flight, who writes most of the code now, and what gets reviewed — every diff, final diffs, or exceptions. Quote the evidence. **A range is a refusal** — pick the stage the team is *operating at*, not the best day it ever had. Cap clarifying questions at 2.
+
+2. **Discount aspiration.** A team that bought licences for 200 people and has three power users is at stage 1 with an outlier, not stage 2. Place on the median engineer, and say so when the distribution is lopsided — the spread is itself a finding.
+
+3. **Name the current bottleneck in one sentence,** and check it against the table. If the team's stated pain doesn't match the stage's bottleneck, that mismatch is the most interesting thing in the assessment — surface it. ("You say review is the constraint, but engineers still run one agent at a time; the constraint is trust, not throughput.")
+
+4. **Prescribe exactly one unlock.** The next step, never a backlog of ten. The transitions:
+   - **0 → 1:** an approved path to run agents and land their output. Executive alignment, not tooling.
+   - **1 → 2:** **a self-verification loop the engineer trusts** — tests, build, lint, typecheck running *before* they look — plus more than one agent at a time and pre-approved safe commands so permission prompts stop blocking.
+   - **2 → 3:** context and delegation — let agents read the code, docs and discussions; automate review so it isn't the queue; break work into loops and routines; let agents start agents.
+   - **3 → 4:** scaled automation of domain-specific work (migrations, fuzzing, remediation) with per-work-type guardrails.
+
+5. **State which guardrail must change**, not just what to add. Guardrails are stage-appropriate, and carrying the old one forward is what stalls teams: reading every diff is right at stage 1 and *arithmetically impossible* at stage 3, where the control moves to the loop (automated review, sandboxing, isolation) and humans review by exception. Name the one to retire and the one to introduce.
+
+6. **Route the unlock to something concrete.** Each unlock has an implementation:
+
+   | Unlock | Where it's implemented |
+   |---|---|
+   | a trusted self-verification loop | [`pre-merge-review`](../pre-merge-review/SKILL.md) — a mechanical gate whose exit code decides, plus the reviewer panel |
+   | automated review that isn't the queue | the reviewer panel (`devils-advocate`, `security-reviewer`, `code-quality`) |
+   | loops and routines | [`agent-loop-design`](../agent-loop-design/SKILL.md) — generate→verify→gate with exit criteria and a cap |
+   | parallel agents without collision | [`subagent-design`](../subagent-design/SKILL.md) — topology, isolation, typed contracts |
+   | token efficiency as volume climbs | [`agent-budget`](../agent-budget/SKILL.md) + a provider-neutral model tier per task |
+   | encoding standards so agents inherit them | [`agents-md-generator`](../agents-md-generator/SKILL.md) and skills themselves |
+   | guardrails for autonomous work | [`agent-threat-model`](../agent-threat-model/SKILL.md) |
+
+7. **End with the re-measure date and what would prove the unlock landed.** An observable: "median agents-in-flight ≥ 3 and engineers stop reading intermediate diffs, in 6 weeks."
+
+## Quality bar
+
+- **Exactly one stage, cited to observables.** No ranges, no "between 2 and 3" — and never a placement asserted from ambition or licence count.
+- **Placement is on the median engineer**, with the distribution named when it's lopsided.
+- **Exactly one unlock.** A list of ten is a backlog, and it guarantees none of them happens.
+- **The bottleneck is the one gating the *next* step**, not a general complaint about AI.
+- **A guardrail to retire is named**, not only one to add — stage-appropriateness cuts both ways.
+- **Every unlock routes to a concrete implementation**, never to a product name.
+- **Vendor-neutral throughout.** Capabilities, not SKUs; a skill that names this quarter's products is wrong by next quarter.
+- **The source framework is credited.**
+
+## When to use this skill
+
+- ✅ "How far along are we with coding agents, really?"
+- ✅ Adoption plateaued and nobody can name why.
+- ✅ A leader wants to scale agent usage and needs to know whether the loop can carry it yet.
+- ✅ Re-measuring a quarter after a previous placement.
+
+## When NOT to use this skill
+
+- ❌ Assessing organisational preconditions — data, policy ownership, incentives — that's [`ai-readiness-assessment`](../ai-readiness-assessment/SKILL.md), a different axis (a team can be governance-ready and stuck at stage 1).
+- ❌ Planning how a tool reaches people — cohorts, enablement, comms — that's [`ai-adoption-rollout`](../ai-adoption-rollout/SKILL.md).
+- ❌ Choosing which use cases to build — that's [`ai-use-case-triage`](../ai-use-case-triage/SKILL.md).
+- ❌ Reporting measured usage from telemetry — that's [`ai-usage-report`](../ai-usage-report/SKILL.md).
+- ❌ Designing one specific loop or fleet — that's `agent-loop-design` / `subagent-design`, which this skill routes *to*.
+
+## Anti-patterns to avoid
+
+- ❌ **Scaling agent count before the loop has earned trust.** The named trap of stage 2→3: more agents on an unverified loop multiplies review burden instead of output. Trust first, count second.
+- ❌ **A stage claimed from ambition.** Licences bought, a mandate announced, or one enthusiastic staff engineer are not a stage. Median engineer, observable behaviour.
+- ❌ **Carrying stage-1 guardrails upward.** "Read every diff" doesn't scale to ten streams and is arithmetically impossible at a hundred; insisting on it is what caps a team at stage 1 while everyone blames the model.
+- ❌ **Answering with a product list.** Tools don't move a team up a rung — a trusted verification loop does. Name the capability and the loop change.
+- ❌ **Prescribing the whole ladder.** Handing someone stages 2, 3 and 4 at once guarantees stage 1 forever.
+- ❌ **Treating the stage as a status symbol.** Stage 4 is not better for a team whose work doesn't need it; the right stage is the one the work and the trust support.
+
+**Non-interactive:** with no user to ask, infer the stage from whatever observables the input contains and tag the placement `[assumption]`, naming what to confirm. If the input has no observable at all — no agent counts, no review posture, no statement of who writes the code — emit `BLOCKED: need at least one observable (agents in flight per engineer, who writes most of the code, or what gets reviewed)` rather than guessing a stage, because a wrong placement prescribes the wrong unlock.

package/skills/agent-adoption-stage/evals/eval_queries.json

@@ -0,0 +1,34 @@
+[
+  {
+    "query": "How far along are we with coding agents?",
+    "should_trigger": true
+  },
+  {
+    "query": "Our AI adoption has plateaued — what's the next unlock?",
+    "should_trigger": true
+  },
+  {
+    "query": "Which stage of agentic coding maturity is my team at?",
+    "should_trigger": true
+  },
+  {
+    "query": "We want engineers running more agents — are we ready to scale that?",
+    "should_trigger": true
+  },
+  {
+    "query": "Assess whether our organisation's data and governance are ready for AI",
+    "should_trigger": false
+  },
+  {
+    "query": "Plan the rollout cohorts and enablement for this tool",
+    "should_trigger": false
+  },
+  {
+    "query": "Which AI use cases should we build first?",
+    "should_trigger": false
+  },
+  {
+    "query": "Design the subagent topology for this specific fleet",
+    "should_trigger": false
+  }
+]

package/skills/agent-adoption-stage/evals/evals.json

@@ -0,0 +1,19 @@
+{
+  "skill_name": "agent-adoption-stage",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "We bought Claude Code for our 60 engineers six months ago. Most people use it like autocomplete for one task at a time and still read every diff before merging. Two staff engineers run several sessions at once. Tests are flaky so nobody trusts them. Where are we and what's next?",
+      "assertions": [
+        "Places the team on exactly one stage — no range — citing the observables from the prompt (one agent at a time, every diff read)",
+        "Places on the median engineer and calls out the two power users as an outlier rather than counting them as the stage",
+        "Names the bottleneck as attention/trust rather than review throughput, and connects it to the untrusted test suite",
+        "Prescribes exactly one unlock — a self-verification loop the engineer trusts — not a list of improvements",
+        "Names a guardrail to retire (reading every diff) alongside the one to introduce",
+        "Routes the unlock to a concrete implementation rather than to a product name",
+        "Ends with an observable that would prove the unlock landed and a re-measure date",
+        "Credits the source framework"
+      ]
+    }
+  ]
+}

package/skills/agent-adoption-stage/manifest.json

@@ -0,0 +1,39 @@
+{
+  "name": "agent-adoption-stage",
+  "version": "0.1.0",
+  "description": "Place an engineering team on the agentic-coding adoption ladder (0 gated → 4 intent-steered) using observables like agents-in-flight per engineer and who writes the code, name the one bottleneck gating the next step, prescribe the single next unlock, and state which current guardrail must change. Use when a leader asks \"how far along are we with coding agents\", \"why has our AI adoption plateaued\", or \"what do we do next to get more out of this\". Do NOT use to assess organisational preconditions like data, policy, and culture (that's ai-readiness-assessment) or to plan a tool's human rollout (that's ai-adoption-rollout).",
+  "entrypoint": "SKILL.md",
+  "deps": {
+    "npm": [],
+    "pip": []
+  },
+  "env": {
+    "required": [],
+    "optional": []
+  },
+  "related": [
+    "agent-budget",
+    "agent-loop-design",
+    "agent-threat-model",
+    "agents-md-generator",
+    "ai-adoption-rollout",
+    "ai-readiness-assessment",
+    "ai-usage-report",
+    "ai-use-case-triage",
+    "devils-advocate",
+    "pre-merge-review",
+    "subagent-design"
+  ],
+  "tags": [
+    "ai-adoption",
+    "agentic-coding",
+    "maturity-ladder",
+    "orchestration",
+    "engineering-leadership",
+    "bottleneck"
+  ],
+  "model": {
+    "tier": "standard",
+    "rationale": "Places a team on a fixed 5-stage ladder from observables and routes one unlock. Bounded diagnosis against a rubric; escalate via ambiguous-input when the observables are contradictory or the distribution is heavily skewed."
+  }
+}

package/skills/ai-readiness-assessment/SKILL.md

@@ -54,6 +54,7 @@ Readiness assessments fail in one of two ways: a number with no evidence behind
 - ❌ Writing the rules for what people may put into a tool — that's [`ai-usage-policy`](../ai-usage-policy/SKILL.md).
 - ❌ A market or competitive question ("should we enter this space?") — that's `strategy-analysis`.
 - ❌ Measuring adoption that has already happened — that's `ai-usage-report`.
+- ❌ **Assessing how far an engineering team's agent practice has actually got** — agents in flight, who writes the code, what still gets reviewed — that's [`agent-adoption-stage`](../agent-adoption-stage/SKILL.md). It's the orthogonal axis: this skill scores whether the *organisation* can adopt at all; that one scores how far the *practice* has got. A team can be governance-ready and stuck at stage 1, or running ten agents with no policy at all — run both when the answers disagree.
 
 ## Anti-patterns to avoid
 

package/skills/ai-readiness-assessment/manifest.json

@@ -12,6 +12,7 @@
     "optional": []
   },
   "related": [
+    "agent-adoption-stage",
     "ai-adoption-rollout",
     "ai-usage-policy",
     "ai-usage-report",