skilldrop-cli 0.16.29 → 0.16.31

package/packs/ai-engineering/skills/mcp-pairing/evals/files/4/.mcp.json

@@ -0,0 +1,47 @@
+{
+  "mcpServers": {
+    "github": {
+      "command": "docker",
+      "args": ["run", "-i", "--rm", "-e", "GITHUB_PERSONAL_ACCESS_TOKEN", "ghcr.io/github/github-mcp-server"],
+      "env": {
+        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_EXAMPLEEXAMPLEEXAMPLEEXAMPLE0001"
+      },
+      "_comment": "classic PAT, scopes: repo, workflow, admin:org, delete_repo -- easiest to just give it everything"
+    },
+    "github-reviewer": {
+      "command": "docker",
+      "args": ["run", "-i", "--rm", "-e", "GITHUB_PERSONAL_ACCESS_TOKEN", "ghcr.io/github/github-mcp-server"],
+      "env": {
+        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_EXAMPLEEXAMPLEEXAMPLEEXAMPLE0001",
+        "GITHUB_TOOLSETS": "all"
+      },
+      "_comment": "used by the review stage so it can approve + merge when it's happy"
+    },
+    "jira": {
+      "command": "npx",
+      "args": ["-y", "jira-mcp-plus-unofficial@latest"],
+      "env": {
+        "JIRA_URL": "https://example-team.atlassian.net",
+        "JIRA_EMAIL": "build-bot@example.com",
+        "JIRA_API_TOKEN": "EXAMPLE-JIRA-TOKEN-DO-NOT-USE"
+      },
+      "_comment": "found this on a forum thread, works better than the official one"
+    },
+    "slack": {
+      "command": "npx",
+      "args": ["-y", "slack-mcp-server-community"],
+      "env": {
+        "SLACK_BOT_TOKEN": "xoxb-EXAMPLE-EXAMPLE-EXAMPLE",
+        "_scopes": "chat:write, chat:write.public, channels:history, groups:history, im:history, users:read.email, admin"
+      }
+    },
+    "postgres": {
+      "command": "npx",
+      "args": ["-y", "some-postgres-mcp"],
+      "env": {
+        "DATABASE_URL": "postgresql://app_owner:EXAMPLEPASSWORD@prod-db.internal.example:5432/orders"
+      },
+      "_comment": "handy for the implement stage to check schemas"
+    }
+  }
+}

package/packs/ai-engineering/skills/mcp-pairing/evals/files/4/docs/pr-loop.md

@@ -0,0 +1,12 @@
+# Our agent PR loop
+
+The coding agent runs this loop for every ticket in the "Agent-ready" Jira column.
+
+1. **Pick up** - read the Jira ticket (description, acceptance criteria, linked tickets). Move it to "In Progress".
+2. **Implement** - branch off `main`, write the change and tests, push the branch, open a draft PR on GitHub.
+3. **Review** - a second agent session reads the PR diff, the CI results and the ticket, and decides if it meets the acceptance criteria.
+4. **Merge gate** - a human tech lead approves and merges. Nothing merges without a human.
+5. **Announce** - post a one-line summary with the PR link to `#team-orders-dev` in Slack.
+
+Repo: one GitHub repo, `example-org/orders-service`. CI is GitHub Actions.
+The `.mcp.json` lives in the repo root and is committed so everyone gets the same setup.

package/packs/ai-engineering/skills/mcp-pairing/evals/files/5/docs/oncall-triage.md

@@ -0,0 +1,18 @@
+# On-call triage loop (draft)
+
+Trigger: a Sentry alert fires for `payments-api` or a Grafana alert pages the on-call.
+
+1. **Gather** - pull the Sentry issue (stack trace, release, affected users count) and the
+   Grafana dashboard panels for latency / error rate around the alert window.
+2. **Correlate** - find the GitLab merge requests and deploys that landed in the 24h before
+   the first event. Look at the diff of the suspect MR.
+3. **Check data** - if the error looks data-related, run a couple of SELECTs against the
+   `payments` Postgres database to see whether bad rows exist.
+4. **Ticket** - open a Linear issue in the `PAY` team with the findings, priority Urgent, and
+   assign it to the on-call.
+5. **Postmortem draft** - write a first-draft postmortem in markdown from everything above,
+   for the on-call to edit.
+
+Constraints: Sentry is self-hosted at sentry.internal.example. Grafana is Grafana Cloud.
+Payments DB has a primary and one read replica. We're PCI-scoped, so card data columns exist
+in `payments.transactions` (pan_last4, card_token, billing_address).

package/packs/ai-engineering/skills/mcp-pairing/examples/build-loop-github-jira-datadog.md

@@ -0,0 +1,69 @@
+# Worked example — the build loop on GitHub, Jira and Datadog
+
+## Input given to the skill
+
+> We're adopting the build loop for the `orders-api` repo. We use GitHub for code and PRs,
+> Jira (project ORD) for stories and bugs, and Datadog for logs and APM. Which MCP servers
+> should we connect, and with what access? We'd like the agent to open the PR itself if that's
+> sensible. About one bug a week needs logs; stories come in daily. Outside contractors open
+> PRs too.
+
+---
+
+# MCP pairing — build loop for `orders-api`
+
+**Tools in use:** GitHub, Jira (project ORD), Datadog · **Assumptions:** the developer's
+checkout is local, so implement needs no repo server `[assumption]`; Jira issues in ORD are
+written by staff and by people raising bugs from support `[assumption]`.
+
+## The plan
+
+Connect two servers, both read-only: Jira for the shape stage and GitHub for the verify stage.
+Implement and decide need none. Datadog is cut: one bug a week is a saved log query, not a live
+server. Opening the PR is the one write worth granting, on its own GitHub credential used only
+at the end of implement, and only if the team wants it; otherwise the developer opens the PR.
+
+## Pairing by stage
+
+| Stage (type, cadence) | Needs | Server | Grant | Must not | Fallback without it | Risk |
+|---|---|---|---|---|---|---|
+| shape (generate, daily) | Tracker issue: the story or bug, its comments and links | Atlassian's own server — confirm Atlassian publishes it in Atlassian's docs before connecting | A Jira account with Browse on project ORD only; the server acts with that account's permissions | Create, transition, comment, assign, edit fields; see any project but ORD | The issue exported from Jira to a text file, or the filter exported as CSV | Issue text and comments are untrusted (support-raised bugs). Shape holds no write or exec tool, so reading them is safe here; it writes the story file and nothing else |
+| shape, bugs only (generate, ~weekly) | Logs and traces for the failing request | Cut — see below | — | — | The Datadog log query result saved as JSON, and the trace's spans exported, for the bug's time window | Log lines carry request fields an attacker writes; a file a person picked keeps that bounded |
+| implement (generate, per story) | None — works from the story file shape wrote and the local checkout | None | — | — | — | Implement runs tests (exec) and edits files (write), so it gets **no** tracker or GitHub server: live issue text next to a shell is the dangerous combination. A person skims the story file before implement starts |
+| implement → open PR (generate, per story, optional) | Action: open a draft PR from the pushed branch | GitHub's own server, write configuration — confirm GitHub publishes it (GitHub's own organization, docs on GitHub's domain) | A separate fine-grained token, `orders-api` only: Pull requests read and write, Contents read and write; branch protection on `main` requires review | Merge, approve, push to `main`, change settings or branch protection, touch other repositories | The developer runs the push and opens the PR by hand | Write and exec in one stage, so this stage reads nothing untrusted: no issue comments, no PR comments |
+| verify (verify, per PR) | Repo: the PR diff, description, CI status | GitHub's own server in its read-only mode, limited to the repositories, pull requests and Actions toolsets | A separate fine-grained token, `orders-api` only: Contents read, Pull requests read, Actions read | Merge, approve, comment, request changes, label, re-run CI | The diff saved as a `.diff` file and the PR description copied to a file; the CI summary saved | Contractor PRs and comments are untrusted, and the gate script is exec. Allow only the gate script command in this session; the verdict goes to a person, never posted by the agent |
+| decide (gate, per PR) | None — reads verify's verdict and any design disagreement | None | — | — | — | The merge stays a person's action in GitHub's own UI under their own login |
+
+## Credentials
+
+| Variable | Server | Scope | Used by stages | Kind |
+|---|---|---|---|---|
+| None — OAuth sign-in, no stored token | Atlassian | Browse, project ORD | shape | Read |
+| `GH_ORDERS_READ` | GitHub | Contents, Pull requests, Actions: read; `orders-api` | verify | Read |
+| `GH_ORDERS_PR_WRITE` | GitHub | Pull requests and Contents: read and write; `orders-api` | implement → open PR (optional) | Write, separate token |
+
+Tokens live in environment variables or the client's secret store. The project's committed MCP
+config holds variable names only. The write server is a separate server entry, enabled only in
+the session that opens the PR, so the verify session never loads it.
+
+## Servers cut
+
+- **Datadog** — needed for about one bug a week. A saved log query and exported trace cover it,
+  with no standing token to the team's logs and no live attacker-written log lines in context.
+  Revisit if bugs needing logs reach several a week.
+
+## Check before installing
+
+- **Atlassian's own server** — confirm publisher; it acts with the account's own permissions,
+  so the account must have nothing beyond Browse on ORD.
+- **GitHub's own server** — confirm publisher, use its read-only mode for verify, and turn off
+  every toolset verify doesn't use.
+
+## To confirm
+
+- Whether the team wants the agent to open PRs at all; if not, drop `GH_ORDERS_PR_WRITE`.
+- That branch protection on `main` requires an approving review, so even the write token cannot
+  land code alone.
+
+Next step: review the finished setup for any path where issue or PR text could make the agent
+send private data out, before the first real story runs through it.

package/packs/ai-engineering/skills/mcp-pairing/manifest.json

@@ -0,0 +1,17 @@
+{
+  "name": "mcp-pairing",
+  "version": "0.1.0",
+  "description": "Recommend which MCP servers to connect for a loop, workflow or task, stage by stage, with the narrowest access that works — what outside context or action each stage needs, the server that provides it (only ones the user named or the vendor officially publishes), the scopes to grant (read-only by default, never write on a review or gate stage), what it must not be able to do, the export-file fallback that keeps the stage running without it, and which stages need no server at all. Use when the user asks \"which MCP servers should we hook up for this loop\", \"what should our agent connect to\", \"what token scopes does this stage need\", \"is this MCP setup too broad\", or wants to wire GitHub, GitLab, Jira, Linear, Slack, Sentry, Grafana or a database into an agent workflow.",
+  "entrypoint": "SKILL.md",
+  "deps": { "npm": [], "pip": [] },
+  "env": { "required": [], "optional": [] },
+  "related": ["agent-loop-design", "agent-threat-model", "ai-usage-policy", "subagent-design"],
+  "handoff": [{
+    "to": "agent-threat-model",
+    "when": "the pairing still puts private data, untrusted content and any way to send data out in one session, or before the setup is connected at work",
+    "purpose": "Attack the finished capability surface path by path and break a leg on every path that can leak data.",
+    "fallback": "If agent-threat-model is absent, list each stage's session with three marks — private data, untrusted content, egress (write, network, rendered output) — and split or drop any session that holds all three."
+  }],
+  "tags": ["mcp", "least-privilege", "tool-permissions", "agentic", "prompt-injection"],
+  "model": { "tier": "standard", "rationale": "Matching a loop's stages to the context each needs and the narrowest access that provides it is bounded judgment over a short checklist." }
+}

package/packs/ai-engineering/skills/mcp-pairing/reference.md

@@ -0,0 +1,136 @@
+# mcp-pairing — reference
+
+## Stage types and their access ceiling
+
+The type sets the most a stage may ever hold. The stage's output decides whether it gets
+anything at all.
+
+| Type | What it does | Ceiling | Why |
+|---|---|---|---|
+| `generate` | Produces an artifact | Read; write **only** when the output *is* the write (a published release, a draft merge request), on its own credential | The write is the deliverable, so it is the one place a write is justified |
+| `verify` | Judges an artifact that exists | Read only | A reviewer that can approve, merge, comment or close has become an actor, and its verdict can no longer be trusted as independent |
+| `gate` | A person or script decides | Read only, and often nothing | The decision is the person's; the merge or ship button stays in the vendor's own UI under the person's own login |
+
+A stage that runs a fixed script (a gate script, a test suite) holds **exec**. Exec counts as
+write for rule 6: it must not sit beside live untrusted content unless the only command it can
+run is that fixed script.
+
+## Needs by category
+
+| Need | Typical stages | Untrusted? | Read grant | Must not | Export fallback |
+|---|---|---|---|---|---|
+| Tracker issues | shape, triage, status, gather | Yes — anyone with project access, and customers on a service desk | Issues read, one project or team | Create, transition, comment, assign, change fields | The filter exported as CSV, or the issue copied to a text file |
+| Repo / PR / merge request / diff | verify, announce, plan | Yes — PR and merge request text and comments; outside contributors' diffs | Contents and pull/merge requests read, one repository | Merge, approve, push, comment, change settings, read other repositories | The diff saved as a `.diff` file plus the description copied |
+| CI status | verify, ready | Partly — job logs echo whatever the code printed | Pipeline / Actions read, one repository | Re-run, cancel, edit secrets or variables | The pipeline summary page saved, failed job log saved |
+| Docs and wiki | plan, specify, design | Yes when many people edit it | Pages read, one space | Edit, create, change permissions | The page exported to Markdown or PDF |
+| Logs / metrics / traces | triage, ready, respond, learn | Log lines: yes (request fields are attacker-written). Metric values: no | Viewer role, one org or folder; no query of other teams' data sources | Edit dashboards or alerts, silence alerts, create API keys | The panel's data downloaded as CSV; the log query result saved as JSON |
+| Error events | triage, respond, learn | Yes — messages and breadcrumbs carry user input | Issues and events read, one project | Resolve, assign, change alert rules | The event JSON saved from the event page |
+| Design files | specify, design | Comments: yes | File read, one file or project | Edit, comment, share | Frames exported as PNG plus the spec copied |
+| Chat history | respond, status, decision capture | Yes — every member, and external guests in shared channels | History read, named channels only | Post, react, invite, read DMs or all channels | The thread exported or copied to a text file |
+| Database read | review, spec, measure | Free-text columns: yes | A read-only role on a replica, one schema, row limit | Any DDL or DML, superuser, production primary | The query result saved as CSV |
+| Cloud billing | cost review | No | Billing read for one account or profile | Change budgets, buy reservations, touch resources | The cost report exported as CSV |
+| Web | research, gather | Yes, always | Fetch only, no form submission | Hold any write or exec tool in the same session | The pages saved as files the user picked |
+
+## The vetting checks
+
+Run all five for any server that is not the vendor's own, and confirm the first three for one
+that is:
+
+1. **Publisher.** Who publishes it, and is that the vendor of the tool it talks to? A personal
+   account or an unrelated organization is a community server.
+2. **Source available.** Can the code be read? A server that ships only a binary or a remote
+   endpoint with no published source is trusted on reputation alone.
+3. **Pinned version.** A local server runs a pinned version or commit, never `@latest` or an
+   unpinned `npx` / `uvx` call; container images are pinned to a digest. Upgrades are
+   deliberate.
+4. **Tools exposed.** List the tools it registers. Any tool the stage doesn't need is turned off
+   in the server's own toolset option or the client's disabled-tools list.
+5. **Code and network reach.** Can any tool run a shell, execute code, or call a host other
+   than the vendor's API? Either one makes the server an egress path and an exec path, and
+   rule 6 applies to every stage it is enabled in.
+
+A server that fails 1 or 2 and has no official alternative gets the export-file fallback until
+someone reads its source and pins a commit.
+
+## Known vendor controls
+
+Checked 2026-10-01 from the vendors' docs. Confirm in the vendor's current docs before relying
+on any of them; vendors change these without notice.
+
+- **GitHub's own server** has a read-only mode and lets a client limit it to named toolsets
+  (for example repositories and issues). Fine-grained tokens limit to named repositories.
+- **Linear's own server** offers a read-only mode and a `read` OAuth scope; API keys can be
+  created with only the Read permission.
+- **Atlassian's own server** acts with the signed-in user's Jira and Confluence permissions.
+  Whatever that user can delete, the agent can delete; use an account with read access to the
+  one project.
+- **Supabase's own server** takes a read-only flag and a single-project scope.
+- **GitLab** personal, project and group tokens have a `read_api` scope that is read-only for
+  the API, and project tokens limit to one project.
+- **Grafana** service accounts take the Viewer role, which reads dashboards and queries data
+  sources without editing anything.
+- **Slack** workspace admins approve which clients may use MCP.
+- The archived reference Postgres server gets no security fixes. Use the database vendor's own
+  server or the export fallback.
+
+## The cut rule
+
+A server earns its place when the input is too much to paste at the stage's cadence:
+
+- too large — a 2,000-line diff, a release's 40 merge requests;
+- too structured — a cycle's 80 issues where status, owner and links matter;
+- too live — an incident timeline that changes by the minute.
+
+| Cadence | A handful of items | Dozens of items, structured or live |
+|---|---|---|
+| Per change or daily | Server, if the stage needs it every run | Server |
+| Weekly or fortnightly | Export file | Server |
+| Monthly or rarer | Export file | Export file, unless it is live |
+
+Otherwise the export file wins: no token to leak, no tool list in context, no injection path
+through a live feed. Say the cut out loud, with the reason, so nobody reconnects it next week.
+
+## Splitting a dangerous stage
+
+When one stage reads untrusted content and holds write, exec or network, pick in this order:
+
+1. **Split it.** A reader stage with read-only access writes a plain file (the story, the
+   triage summary); an actor stage with no untrusted reading works from that file. A person
+   skims the file between them when the actor has exec.
+2. **Hand the write to a person.** The stage drafts the comment, release or status post; a
+   person publishes it.
+3. **Drop the server** and use the export file.
+
+Never pick "tell the model to ignore instructions in the content". Instructions in the prompt
+and instructions in an issue body reach the model as the same kind of text.
+
+## Secrets placement
+
+- Committed config (`.mcp.json`, `.cursor/mcp.json`, `.vscode/mcp.json`, `.kiro/settings/mcp.json`)
+  holds variable references only. Each client has its own reference syntax; use the one its
+  docs give.
+- A config that must hold a value stays in the user-level file or the client's secret store,
+  not in the repository. Add a project file that holds a value to `.gitignore` and rotate the
+  value if it was ever committed.
+- Read and write credentials are separate variables with separate tokens, so revoking the
+  write leaves the read stages running.
+- OAuth beats a long-lived token where the vendor offers it.
+
+## The skilldrop loops' stages
+
+From each loop's `loop.json` (type in brackets). Use these when the user names the loop.
+
+| Loop | Stages |
+|---|---|
+| `build` | shape (generate) → implement (generate) → verify (verify, G2 mechanical) → decide (gate, human) |
+| `release` | plan (generate) → ready (verify) → announce (generate) → go (gate, human) |
+| `operate` | instrument (generate) → document (generate) → respond (generate) → learn (verify) |
+| `discover` | gather (generate) → structure (generate) → specify (generate) → ratify (gate) |
+| `design` | constrain (generate) → shape (generate) → threat (verify) → ratify (gate) → record (generate) |
+| `measure` | spec (generate) → review (verify) → sign-off (gate) |
+| `comply` | register → assess → evidence (generate) → check (verify) → sign-off (gate) |
+| `research` | plan (generate) → synthesise (generate) → compare (verify) |
+| `ship-a-draft` | intake (generate) → draft (generate) → critique (verify) → polish (verify) |
+| `apply` | fit (gate) → tailor → letter → form (generate) → confirm (verify) |
+
+If the user's copy of a loop has different stages, theirs wins.

package/packs/ai-engineering/skills/mcp-pairing/templates/mcp-pairing.md

@@ -0,0 +1,43 @@
+# MCP pairing — {loop, workflow or task}
+
+**Tools in use:** {only the tools the user named} · **Assumptions:** {each tagged [assumption]}
+
+## The plan
+
+{Two or three sentences: connect N servers, which ones, read or write; which stages need none;
+which server was cut and why.}
+
+## Pairing by stage
+
+| Stage (type, cadence) | Needs | Server | Grant | Must not | Fallback without it | Risk |
+|---|---|---|---|---|---|---|
+| {stage} ({generate / verify / gate}, {per change / daily / weekly / monthly}) | {category of context or action} | {server the user named, or "{vendor}'s own server, confirm {how}", or the category + vetting} | {scope, one project / repo / role} | {merge, comment, transition, post, write SQL…} | {the export file a person produces} | {untrusted content read; write, exec or network held; what to split} |
+| {stage} | None — works from {previous stage's output} | None | — | — | — | — |
+
+## Credentials
+
+| Variable | Server | Scope | Used by stages | Kind |
+|---|---|---|---|---|
+| {NAME_READ} | {server} | {scope, project} | {stages} | Read |
+| {NAME_WRITE} | {server} | {scope, project} | {the one stage whose output is the write} | Write, separate token |
+
+Tokens live in {environment variables / the client's secret store}. Committed config holds
+variable names only; {any project file that holds a value} stays out of git.
+
+## Servers cut
+
+- **{server or category}** — {cadence and why the export file wins}.
+
+## Check before installing
+
+For each server not confirmed as the vendor's own: publisher, source available, pinned version
+or commit, tools it exposes (turn off the rest), and whether it can run code or reach the
+network beyond its own API.
+
+- **{server}** — {which checks are still open}
+
+## To confirm
+
+- {each fact the plan needs and the input didn't give}
+
+{One plain sentence on the next step, e.g. reviewing the finished setup for ways data could be sent out.}

package/packs/dev-team/loops/build/LOOP.md

@@ -13,7 +13,7 @@ one. Every skill named below stays independently installable and runnable on its
 
 | # | Stage | Type | Skills | Gate |
 |---|---|---|---|---|
-| 1 | `shape` | generate | [`user-story-splitter`](../../skills/user-story-splitter/SKILL.md), [`bug-triage`](../../skills/bug-triage/SKILL.md) | — |
+| 1 | `shape` | generate | [`user-story-splitter`](../../skills/user-story-splitter/SKILL.md), [`bug-triage`](../../skills/bug-triage/SKILL.md), [`codebase-tour`](../../skills/codebase-tour/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`](../../../core/skills/council-review/SKILL.md) | **G2.1** human |
@@ -22,7 +22,9 @@ one. Every skill named below stays independently installable and runnable on its
 
 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.
+   test can assert. Vague criteria are the single largest cause of a wasted round 3. In a
+   repository nobody on the change knows yet, run `codebase-tour` on the slice first: where
+   the change goes, the commands that test it, and the traps, each cited to a file.
 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.

package/packs/dev-team/loops/build/loop.json

@@ -1,7 +1,7 @@
 {
   "$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.2.0",
+  "version": "0.3.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",
@@ -11,7 +11,7 @@
       "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"]
+      "skills": ["user-story-splitter", "bug-triage", "codebase-tour"]
     },
     {
       "id": "implement",

package/packs/dev-team/loops/release/LOOP.md

@@ -14,17 +14,19 @@ being folded into either neighbour.
 
 | # | Stage | Type | Skills | Gate |
 |---|---|---|---|---|
-| 1 | `plan` | generate | [`migration-plan`](../../skills/migration-plan/SKILL.md) | — |
+| 1 | `plan` | generate | [`migration-plan`](../../skills/migration-plan/SKILL.md), [`rollout-plan`](../../skills/rollout-plan/SKILL.md) | — |
 | 2 | `ready` | verify | [`launch-readiness`](../../skills/launch-readiness/SKILL.md) | **G3** review |
 | 3 | `announce` | generate | [`release-notes`](../../skills/release-notes/SKILL.md) | — |
 | 4 | `go` | gate | [`council-review`](../../../core/skills/council-review/SKILL.md) | **G3.1** human |
 
 ## How to run this loop
 
-1. **Plan the rollout and the way back.** `migration-plan` sets out the phases, a tested
-   rollback for each one, and at most one named point of no return. For a code-only change
-   behind a flag, the plan can be short: the flag, the stages and how to turn it off. It still
-   has to exist.
+1. **Plan the rollout and the way back.** A change to data, a schema or a platform →
+   `migration-plan`: the phases, a tested rollback for each, and at most one named point of
+   no return. A code change released behind a flag or a canary → `rollout-plan`: the exposure
+   steps, the metric and threshold that decide each one, how long each must run to detect a
+   regression, and what turning the flag off doesn't undo. A change that does both gets both.
+   The plan can be short, but it has to exist.
 2. **Judge readiness at G3.** `launch-readiness` lists the change's own failure modes, then
    checks rollback, detection, response, measured targets, data and privacy, comms and
    exposure, each with evidence. `REVISE` returns to `plan`, and the report names which gap to

package/packs/dev-team/loops/release/loop.json

@@ -1,7 +1,7 @@
 {
   "$comment": "RFC-0031. Covers the step between build (ends at merge, G2.1) and operate (starts at instrument). Its gates are G3 and G3.1: the whole number places the loop in the lifecycle (discover G0 through operate G4), and a decimal is a second gate inside the same loop (RFC-0044).",
   "name": "release",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Take merged code to live users through a planned, reversible rollout — plan the phases and the rollback, judge readiness on evidence, draft the release notes, then a human makes the go/no-go call. Use when the user has merged a change and asks how to roll it out, whether they are ready to launch, or for a go/no-go decision.",
   "entrypoint": "LOOP.md",
   "kind": "loop",
@@ -11,7 +11,7 @@
       "id": "plan",
       "type": "generate",
       "intent": "Decide the rollout phases, the rollback for each, and the one point of no return, before anything reaches users.",
-      "skills": ["migration-plan"]
+      "skills": ["migration-plan", "rollout-plan"]
     },
     {
       "id": "ready",

package/packs/dev-team/skills/codebase-tour/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: codebase-tour
+description: Get a newcomer (a new engineer, or the agent itself) oriented in an unfamiliar repository before they make one specific change, with a short tour scoped to that change. It gives the install, run and test commands taken from CI, package scripts and the Makefile; the path the change touches, traced through the code with file:line citations; where the change goes; the conventions the code actually follows; the traps (generated files, a second copy of the logic, untested code, env vars, flags); and a first step that can be checked. Use when someone says "I'm new to this repo", "get me oriented", "where would I make this change", "walk me through the code for X", "onboard me before I start this ticket", or "how do I run and test this".
+---
+
+# codebase-tour
+
+Orients someone in a repository they have never seen, for **one change they are about to make**. The tour is not a map of the system. It follows the path the change will touch, and it ends at the file and function where the work starts.
+
+Two failures make a plain orientation worse than none. The first is a **confident wrong command**: `make dev` copied from a README into a repo whose Makefile has no `dev` target. The second is the **trap nobody mentions**: the generated file someone hand-edits, the second copy of the logic that stays unchanged, the test suite that skips the area. This skill is built around two rules. **Every claim cites the file and line it was read from. The README gives leads to check; the code gives the facts.**
+
+Boundaries: a full as-is architecture write-up is `reverse-architecture`. A diagram is `interactive-diagram` or `architecture-diagrams`. A standing agent-policy file for the repo is `agents-md-generator`. Writing the change itself is `feature-implement-loop`, which takes this tour's "where the change goes" and first step as its input. Reviewing the finished diff is `pre-merge-review`.
+
+## How to respond
+
+**Four rules come before the steps and outrank them:**
+
+- **Answer what was asked, first.** Open the reply with the 3–5 things this person most needs to know for this change. A directory listing is never first.
+- **Use only what you read.** Every statement carries `path:line` (or a path, for a whole file) from this repository. Anything not checked is tagged `[inferred]` with the reason. A fact the repo doesn't give goes under "Open questions". It is not filled in from what the framework usually does.
+- **Deliver from what you have.** Read the repo, state any assumption in one line, and produce the tour. Ask nothing when the repo and the change are both in hand.
+- **Write for someone who has never heard of this skill.** No skill names, no paths or scripts from this folder, no internal terms, and nothing about how the run was set up. A next step is one plain sentence at the end.
+- **For this skill:** where the README and the code disagree, say so in one line with both citations, and follow the code.
+
+1. **Pin the change in code terms.** Restate it in one sentence using the words the code will use. ✅ *"Reject `POST /orders/{order_id}/refunds` when the event ended more than 14 days ago."* ❌ *"Tighten up refunds."* If no change is named, tour the main path from the primary entry point, tag that scope `[assumption]`, and replace "Where the change goes" with one line asking for the change.
+
+2. **Inventory what the repo says about itself.** Run the fact lister. It is read-only: it prints commands, test files, generated-file markers, env reads and README claims that don't resolve, each with `path:line`.
+
+   ```bash
+   # Claude Code
+   python3 "${CLAUDE_SKILL_DIR}/scripts/repo_facts.py" <repo-root>
+   # Other IDEs (from the skill folder)
+   python3 scripts/repo_facts.py <repo-root>
+   ```
+
+   If no script can run, read these by hand in order: CI workflows (`.github/workflows/`, `.gitlab-ci.yml`), then package scripts, `Makefile`, `justfile`, `tox.ini`, `noxfile.py` and `pyproject.toml`, then `README` and `CONTRIBUTING`. CI ranks first because its commands are the ones that have to pass.
+
+3. **Take commands only from those files, and say which ones ran.** Quote each command with its source. ✅ `make test` (`.github/workflows/ci.yml:21`, which runs `pytest -q -m "not e2e"` per `Makefile:8`). ❌ `make dev` (named in the README; the Makefile has no `dev` target). Prefer CI's form of a command over the script's bare form, and list anything CI needs that a laptop lacks (a database service, an env var set in the workflow). Give each command one status:
+   - `ran: passed` or `ran: failed` with the first error line. Run only commands that stay inside the repo: tests, lint, typecheck or build, and only when the toolchain and dependencies are already installed.
+   - `read, not run` for everything else. That covers dependency installs, anything that needs a database, a network service or credentials, deploys, migrations, publishing, and generators that rewrite tracked files. Run these only when the user asks.
+
+   A command to run one test file or one test is **derived**. It goes through the repo's own script or runner, plus that runner's filter argument, and it is labelled `derived from <source>`. ✅ `pytest -q -m "not e2e" tests/rules/test_refunds.py` (derived from `Makefile:8`). ❌ `python -m unittest` in a repo that runs pytest. A runner the repo never calls is invented. Leave it out.
+
+4. **Trace the path the change touches.** Search for the change's nouns: the route string, the CLI flag, the field or column name, the error code. Work outward to the entry point (`main`, the server bootstrap, the console script, the job scheduler). Then write the path forward as numbered hops. Each hop is `path:line` `function`, plus one line on what it does there. Stop at the far edge of the change, usually the database call or the outbound request. Keep it to 10 hops or fewer. A hop you couldn't trace is `[inferred]`, with what you'd need to confirm it.
+
+5. **Say where the change goes, and why there.** Name the files and functions. Justify each one with the pattern its nearest sibling already follows. ✅ *"Every other refund rule lives in `check_refundable` (`tallyhall/rules/refunds.py:9`), which the route calls at `tallyhall/api/refunds.py:22`. The window check goes in `check_refundable` too."* List **everything that has to change together**: a spec and the types generated from it, a registry the new code must be added to, a second copy of the logic.
+
+6. **Read the conventions from the code nearest the change, not from the README.** Cover naming, how errors are raised and returned, test layout and naming, how config and env vars are read, and logging, but only the ones this change will hit. Each gets a citation from code. ✅ *"Errors: raise `RefundRejected(code, message)`; the route turns it into a 422 (`tallyhall/rules/refunds.py:4`, `tallyhall/api/refunds.py:25`)."* Where a file on the path breaks its own convention, say so. That file is the one a newcomer copies by mistake. Every README or `CONTRIBUTING` claim the code contradicts (a command, a path, where config lives, how a plugin is registered) goes under "Where the README is wrong", with both citations.
+
+7. **Hunt the traps.** Check each one and report what you found. Write "none found" when a check comes up empty, so the person knows it was done.
+   - **Generated files**: the marker line, the source they come from, the command that regenerates them, and whether CI checks for drift.
+   - **Duplicated logic**: search for the change's identifiers, SQL, literals and constants outside the main path. A second copy is either updated in the same change or left alone on purpose, and the tour says which is the open question.
+   - **Untested code on the path**: name each function on the path that no test calls.
+   - **Tests the default command skips**: markers (`-m "not slow"`), build tags, include globs.
+   - **Env vars and feature flags the path reads**: the name, the default, and the line that reads it.
+   - **Vendored code** on the path, and where it comes from upstream.
+
+8. **Find the tests for the area, and how to run just those.** Name the test files that exercise the path, the command for the whole suite, and the derived command for only these files. When the area has no tests, say so plainly: ✅ *"Nothing tests `tallyhall/admin/bulk_refund.py`. The first step adds one."*
+
+9. **Name the first step: small, local, and verifiable.** It says what to do in which file, the command to run, and the result that shows it worked. A failing test next to an existing one is the usual best first step. ✅ *"Add `test_rejects_refund_after_window` to `tests/rules/test_refunds.py`, with an order whose event ended 15 days ago; run `pytest -q -m "not e2e" tests/rules/test_refunds.py`; it fails until `check_refundable` checks the window."*
+
+10. **List open questions for a maintainer.** Five at most. Each one can be answered in a sentence and points at the evidence that raised it. ✅ *"Should the support bulk-refund tool (`tallyhall/admin/bulk_refund.py:27`) apply the 14-day window too, or is it the override?"*
+
+11. **Write it with [`templates/codebase-tour.md`](templates/codebase-tour.md), under the caps.** The whole tour is ≤ ~120 lines and each section is ≤ ~15 lines, about one screen. The scope line names what was **deliberately skipped**: the areas not on the path, the services not read. That way the person knows it is a scoped tour and not a survey. If a section would overflow, cut the hops and conventions furthest from the change first.
+
+12. **Reply.** Lead with the 3–5 bullets, then the tour. Put the tour in the reply. Write it to a file only when the user names a path, and change nothing else in the repository.
+
+**Non-interactive runs** (subagent, CI, headless): an unnamed change becomes a main-path tour tagged `[assumption]` (step 1). Unclear scope boundaries become `[assumption]` lines at the top. A repository that cannot be read emits `BLOCKED: need read access to the repository — every claim in the tour cites a file in it`, followed by one plain sentence saying the tour follows once the files can be read. A tour is never written from a description of a repo.
+
+## Useful references in this skill
+
+- [`templates/codebase-tour.md`](templates/codebase-tour.md): the tour skeleton, with section order and line budgets
+- [`scripts/repo_facts.py`](scripts/repo_facts.py): read-only, stdlib-only fact lister (commands with provenance, README commands and paths that don't resolve, tests, generated markers, env reads)
+- [`examples/refund-window.md`](examples/refund-window.md): worked input → output for a Python service, including a README that disagrees with the code and a second copy of a rule
+
+## Quality bar
+
+- **Every claim has a citation or an `[inferred]` tag.** Run a spot check: pick any three statements in the tour, and each must lead to a file and line that says it.
+- **Zero invented commands.** Every command traces to CI, a package script, a Makefile, a tox or nox session or pyproject, or it is a labelled derived filter of a runner the repo already calls.
+- **Ran and read are never blurred.** Every command carries `ran: passed`, `ran: failed`, or `read, not run`.
+- **README-versus-code conflicts are named**, each with both citations and the code taken as the fact.
+- **Scoped, not surveyed.** The path stops at the change's far edge, the tour fits the caps, and the scope line says what was skipped.
+- **The trap checks all report**, including "none found". A second copy of the logic, when one exists, is named with its location.
+- **The tests for the area are named, with a command for just those**, or the tour says plainly that there are none.
+- **It ends at a place to work.** Files and functions, then a first step with a command and an expected result, then at most five open questions.
+- **The reply leads with the 3–5 things that matter**, not a tree.
+
+## When to use this skill
+
+- ✅ "I'm new to this repo and need to add X. Get me oriented."
+- ✅ A ticket is picked up in an unfamiliar codebase and the first hour is going on finding where things live
+- ✅ An agent is about to implement a change in a repo it has not read, and needs the commands and traps before writing code
+- ✅ "How do I run and test this, and where would this change go?"
+- ✅ Handing a scoped piece of work to a contractor or a new teammate with a page that is true
+
+## When NOT to use this skill
+
+- ❌ A full as-is architecture write-up or diagram of the whole system: `reverse-architecture`
+- ❌ Drawing a diagram of a flow or a system: `interactive-diagram` or `architecture-diagrams`
+- ❌ Writing a standing `AGENTS.md` or agent-policy file for the repo: `agents-md-generator`
+- ❌ Writing the code for the change: `feature-implement-loop`
+- ❌ Reviewing a diff that already exists: `pre-merge-review`
+
+## Anti-patterns to avoid
+
+- ❌ **Copying the README's commands.** A README goes stale first. Check every command it names against the scripts and CI, and report the ones that don't exist.
+- ❌ **Ecosystem-default commands.** `pytest` for a repo that runs `nox -s tests`, `make test` in a repo with no Makefile. The repo says what it runs.
+- ❌ **"Run the tests" without saying whether you did.** A reader can't tell a command that passed from one copied out of a file.
+- ❌ **The architecture survey.** Twelve services described, and the one function the change touches never named. Follow the path; skip the rest and say so.
+- ❌ **A directory tree as the opening.** The person can run `ls`. Open with what changes their next hour.
+- ❌ **Conventions from the style guide.** `CONTRIBUTING.md` says "use custom error classes"; the handler on the path returns `{ error: string }`. Report what the code does, and flag the gap.
+- ❌ **Missing the second copy.** The change lands in the API route, and the admin tool with its own copy of the same rule keeps the old behaviour. Search for the identifiers before naming where the change goes.
+- ❌ **Editing a generated file in the first step.** Name the source and the regenerate command instead.
+- ❌ **Running something with side effects to "check it works".** Deploys, migrations, installs that hit the network, and generators that rewrite tracked files stay `read, not run` unless the user asks.
+- ❌ **A first step that can't be checked.** "Get familiar with the handler" is not a step. Name a file, a command and an expected result.
+- ❌ **Showing the machinery.** No skill names, script names or caps in the reply or the tour.

package/packs/dev-team/skills/codebase-tour/evals/eval_queries.json

@@ -0,0 +1,13 @@
+[
+  { "query": "I'm new to this repo and need to add rate limiting to the login endpoint. Get me oriented.", "should_trigger": true },
+  { "query": "Before I start this ticket, walk me through the code that handles invoice exports", "should_trigger": true },
+  { "query": "Where would I make this change? I've never seen this codebase", "should_trigger": true },
+  { "query": "How do I run and test this project, and where does the payment retry logic live?", "should_trigger": true },
+  { "query": "Onboard me to this repo so I can fix the timezone bug in the scheduler", "should_trigger": true },
+
+  { "query": "Reverse-engineer the architecture of this whole system and draw the as-is diagram", "should_trigger": false },
+  { "query": "Write an AGENTS.md for this repo so agents stop running the wrong commands", "should_trigger": false },
+  { "query": "Implement the carrier filter on GET /shipments with tests, here are the acceptance criteria", "should_trigger": false },
+  { "query": "Review my diff before I merge it", "should_trigger": false },
+  { "query": "Make an interactive diagram of how a request flows through our services", "should_trigger": false }
+]