@acme-skunkworks/agent-skills 1.0.0 → 1.1.0

package/skills/changelog/scripts/validate-changelog.mjs

@@ -0,0 +1,264 @@
+#!/usr/bin/env node
+import { parseFrontmatter } from "./lib/frontmatter.mjs";
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join, basename } from "node:path";
+
+const CHANGELOG_DIR = "changelog";
+const FILENAME_RE = /^(\d{8})-(\d{6})-([a-z0-9-]+)\.md$/;
+const ISO_UTC_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$/;
+const SHA7_RE = /^[0-9a-f]{7}$/;
+const ISSUE_RE = /^[A-Z]{2,}-\d+$/;
+const CATEGORIES = new Set([
+  "chore",
+  "docs",
+  "feature",
+  "fix",
+  "perf",
+  "refactor",
+]);
+const MERGE_STRATEGIES = new Set(["merge", "rebase", "squash"]);
+const SECTION_RE = /^##\s+(Breaking|Added|Changed|Fixed)\b/m;
+const BREAKING_RE = /^##\s+Breaking\b/m;
+
+const REQUIRED = [
+  "title",
+  "created_at",
+  "branch",
+  "author",
+  "category",
+  "breaking",
+  "co_authors",
+];
+
+const errors = [];
+function fail(file, msg) {
+  errors.push(`${file}: ${msg}`);
+}
+
+function isInt(v) {
+  return typeof v === "number" && Number.isInteger(v);
+}
+
+function isNonNegInt(v) {
+  return isInt(v) && v >= 0;
+}
+
+function isStringArray(v) {
+  return Array.isArray(v) && v.every((x) => typeof x === "string");
+}
+
+function validateEntry(file, raw) {
+  const name = basename(file);
+
+  if (!FILENAME_RE.test(name)) {
+    fail(
+      file,
+      "filename must match YYYYMMDD-HHMMSS-<slug>.md (slug: [a-z0-9-]+)",
+    );
+    return;
+  }
+
+  let parsed;
+  try {
+    parsed = parseFrontmatter(raw);
+  } catch (error) {
+    fail(file, `frontmatter unparseable: ${error.message}`);
+    return;
+  }
+
+  const fm = parsed.data ?? {};
+  const body = parsed.content ?? "";
+
+  for (const key of REQUIRED) {
+    if (!(key in fm)) {
+      fail(file, `missing required field: ${key}`);
+    }
+  }
+
+  if (
+    "title" in fm &&
+    (typeof fm.title !== "string" || fm.title.trim() === "")
+  ) {
+    fail(file, "title must be a non-empty string");
+  }
+
+  if (
+    "release_note" in fm &&
+    fm.release_note !== null &&
+    typeof fm.release_note !== "string"
+  ) {
+    fail(file, "release_note must be a string or null when present");
+  }
+
+  if ("created_at" in fm) {
+    const v =
+      typeof fm.created_at === "string"
+        ? fm.created_at
+        : (fm.created_at?.toISOString?.() ?? "");
+    if (!ISO_UTC_RE.test(v)) {
+      fail(
+        file,
+        `created_at must be ISO 8601 UTC with Z suffix (got ${JSON.stringify(fm.created_at)})`,
+      );
+    }
+  }
+
+  if (fm.merged_at != null && fm.merged_at !== "") {
+    const v =
+      typeof fm.merged_at === "string"
+        ? fm.merged_at
+        : (fm.merged_at?.toISOString?.() ?? "");
+    if (!ISO_UTC_RE.test(v)) {
+      fail(file, "merged_at must be ISO 8601 UTC with Z suffix when set");
+    }
+  }
+
+  if (
+    "branch" in fm &&
+    (typeof fm.branch !== "string" || fm.branch.trim() === "")
+  ) {
+    fail(file, "branch must be a non-empty string");
+  }
+
+  if (fm.pr != null && fm.pr !== "" && (!isInt(fm.pr) || Number(fm.pr) <= 0)) {
+    fail(file, "pr must be a positive integer when set");
+  }
+
+  if (fm.commit != null && fm.commit !== "" && !SHA7_RE.test(fm.commit)) {
+    fail(file, "commit must be a 7-char hex SHA when set");
+  }
+
+  if (
+    fm.merge_strategy != null &&
+    fm.merge_strategy !== "" &&
+    !MERGE_STRATEGIES.has(fm.merge_strategy)
+  ) {
+    fail(
+      file,
+      `merge_strategy must be one of: ${[...MERGE_STRATEGIES].join(", ")}`,
+    );
+  }
+
+  if (
+    "author" in fm &&
+    (typeof fm.author !== "string" || fm.author.trim() === "")
+  ) {
+    fail(file, "author must be a non-empty string");
+  }
+
+  if ("co_authors" in fm && !isStringArray(fm.co_authors)) {
+    fail(file, "co_authors must be an array of strings (use [] when none)");
+  }
+
+  if ("category" in fm && !CATEGORIES.has(fm.category)) {
+    fail(file, `category must be one of: ${[...CATEGORIES].join(", ")}`);
+  }
+
+  if ("breaking" in fm && typeof fm.breaking !== "boolean") {
+    fail(file, "breaking must be a boolean");
+  }
+
+  if ("issues" in fm) {
+    if (isStringArray(fm.issues)) {
+      for (const id of fm.issues) {
+        if (!ISSUE_RE.test(id)) {
+          fail(
+            file,
+            `issues entry ${JSON.stringify(id)} must match [A-Z]{2,}-\\d+`,
+          );
+        }
+      }
+    } else {
+      fail(file, "issues must be an array of strings when present");
+    }
+  }
+
+  // affected_packages is owned by the post-merge enrich step. The author emits
+  // an empty array as a placeholder; the enrich step overwrites it with the
+  // canonical list derived from PR files. Only enforce structure (string array).
+  if (
+    "affected_packages" in fm &&
+    fm.affected_packages != null &&
+    !isStringArray(fm.affected_packages)
+  ) {
+    fail(
+      file,
+      "affected_packages must be an array of strings (use [] when unpopulated)",
+    );
+  }
+
+  // PR stats live under stats: { files_changed, loc_added, loc_removed }.
+  const statKeys = ["files_changed", "loc_added", "loc_removed"];
+  for (const k of statKeys) {
+    if (k in fm) {
+      fail(file, `${k} must be under stats, not top-level`);
+    }
+  }
+
+  if (!("stats" in fm) || fm.stats == null) {
+    fail(file, "missing required field: stats");
+  } else if (typeof fm.stats !== "object" || Array.isArray(fm.stats)) {
+    fail(file, "stats must be an object");
+  } else {
+    for (const k of statKeys) {
+      if (
+        k in fm.stats &&
+        fm.stats[k] != null &&
+        fm.stats[k] !== "" &&
+        !isNonNegInt(fm.stats[k])
+      ) {
+        fail(file, `stats.${k} must be a non-negative integer when set`);
+      }
+    }
+  }
+
+  if (fm.breaking === true && !BREAKING_RE.test(body)) {
+    fail(file, 'breaking: true requires a "## Breaking" section in the body');
+  }
+
+  if (!SECTION_RE.test(body)) {
+    fail(
+      file,
+      "body must contain at least one of: ## Breaking | ## Added | ## Changed | ## Fixed",
+    );
+  }
+}
+
+function listEntries() {
+  let stat;
+  try {
+    stat = statSync(CHANGELOG_DIR);
+  } catch {
+    console.error(`changelog directory not found: ${CHANGELOG_DIR}`);
+    process.exit(2);
+  }
+
+  if (!stat.isDirectory()) {
+    console.error(`${CHANGELOG_DIR} is not a directory`);
+    process.exit(2);
+  }
+
+  return readdirSync(CHANGELOG_DIR)
+    .filter((n) => n.endsWith(".md") && n !== "README.md")
+    .map((n) => join(CHANGELOG_DIR, n));
+}
+
+const entries = listEntries();
+for (const file of entries) {
+  validateEntry(file, readFileSync(file, "utf8"));
+}
+
+if (errors.length > 0) {
+  console.error(
+    `Changelog validation failed with ${errors.length} error(s):\n`,
+  );
+  for (const e of errors) {
+    console.error(`  - ${e}`);
+  }
+
+  process.exit(1);
+}
+
+console.log(
+  `Changelog validation passed (${entries.length} entr${entries.length === 1 ? "y" : "ies"} checked).`,
+);

package/skills/linear-sync/README.md

@@ -0,0 +1,47 @@
+# linear-sync
+
+Transition the Linear issues linked to the current branch through their workflow
+states (In Progress / In Review / Done) — resolving state IDs by team **name**,
+extracting issue IDs from the branch, and applying the transition idempotently.
+
+## Install
+
+From any consumer repo:
+
+```bash
+npx skills add https://github.com/acme-skunkworks/agent-skills --skill linear-sync --agent claude-code --agent cursor --copy
+```
+
+`--copy` writes real files so the bundle is portable. Don't use `-g` / `--global`
+— the install should live in the consumer repo.
+
+## Configure
+
+The shipped [`config.json`](config.json) carries **ACME Skunkworks defaults**
+(`linearTeamName` and `issueKeys`) — update them for your organisation on install,
+or the state lookups will target the wrong team and branch issue-IDs won't match.
+A neutral [`config.example.json`](config.example.json) ships alongside it as a
+template — copy it over `config.json` and fill in your values, or edit
+`config.json` directly.
+
+| Key | Meaning | Default |
+| --- | --- | --- |
+| `linearTeamName` | Linear team **name** used to resolve live state IDs. Stable across team-key renames — always resolve by name, not key. | `"ACME Skunkworks"` |
+| `issueKeys` | Team-key prefixes that may appear in branch names; the issue-ID regex is built from these. Keep legacy keys so old branches still match. | `["ASW", "AKW", "SKW"]` |
+
+## Requirements
+
+- The Linear MCP server (the `mcp__linear-server__*` tools). The skill drives it
+  directly and has no non-MCP fallback — if it is unavailable, the skill cannot run.
+- The `git` CLI, to read the current branch name.
+
+## What it does
+
+Resolves the target state's live ID once (by team name), extracts the branch's
+issue IDs (from `issueKeys`), reads each issue's current state, and applies the
+target transition idempotently — skipping any issue already at or past it. The
+default standalone target is **In Progress** (the start-of-work transition).
+
+See [`SKILL.md`](SKILL.md) for the full transition-rules table, the
+team-name-not-key gotcha, and the caller-responsibility (when/whether to fire)
+boundaries.

package/skills/linear-sync/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: linear-sync
+description: >-
+  Transition the Linear issues linked to the current branch through their
+  workflow states (In Progress / In Review / Done) — resolve live state IDs by
+  team name, extract issue IDs from the branch, and apply the transition
+  idempotently. Use when starting work on an issue, when a PR opens or updates,
+  during branch cleanup, or whenever a branch's Linear issues need their state
+  synced. Resolves state IDs by team name (not key — keys go stale on rename),
+  reads the team name and issue-ID prefixes from config.json, and skips any issue
+  already at or past the target state.
+license: MIT
+compatibility: >-
+  Requires the Linear MCP server (the `mcp__linear-server__*` tools). The branch
+  read needs the `git` CLI. If the Linear MCP server is unavailable the skill
+  cannot run — it has no non-MCP fallback.
+metadata:
+  version: 0.1.1
+allowed-tools: Bash(git:*), mcp__linear-server__get_issue, mcp__linear-server__save_issue, mcp__linear-server__list_issue_statuses
+---
+
+# linear-sync
+
+Move the Linear issues linked to the current branch through their workflow
+states. This skill is the single source of truth for **how** issues are
+transitioned: resolving the live state IDs, extracting issue IDs from a branch
+name, and the per-state transition rules. Callers decide **when** and **whether**
+to fire it; the mechanics live here once so the rules don't drift across the
+ship flow, branch cleanup, and the start-of-work transition.
+
+## Configuration
+
+Two knobs live in [`config.json`](config.json) beside this file. Read it at the
+start of a run and use its values throughout. Edit your copied `config.json` to
+match the consuming repo:
+
+| Key | Meaning | Default |
+| --- | --- | --- |
+| `linearTeamName` | Linear team **name** used to resolve the live state IDs. Use the name, not the key — the key is renamed over time but the name is stable. | `"ACME Skunkworks"` |
+| `issueKeys` | Team-key prefixes that may appear in branch names. The issue-ID regex is built from these. Keep legacy keys so old branches still match. | `["ASW", "AKW", "SKW"]` |
+
+A neutral [`config.example.json`](config.example.json) ships alongside it as a
+template — copy it over `config.json` and fill in your values, or edit
+`config.json` directly.
+
+## Resolving state IDs (do this once per run)
+
+Call `mcp__linear-server__list_issue_statuses` with `team: <linearTeamName>`
+**once** to resolve the live state IDs for the target state(s).
+
+**Pass the team _name_, not the key.** Linear state IDs are per-team, and a
+workspace's team can be renamed over its lifetime (e.g. CAT → WTF → AKW → ASW),
+so a hardcoded key goes stale. The team _name_ (`linearTeamName`) does not move.
+This is the canonical gotcha for adopters — resolve by name, every run.
+
+## Extracting issue IDs from the branch
+
+Build the issue-ID regex by joining `issueKeys` with `|`:
+`\b((?:ASW|AKW|SKW)-\d+)\b` for the defaults above. Match it against the
+**upper-cased** branch name — branches like `asw-7-as-acquired` carry the key in
+lower case, and a flow such as `--issue=ASW-7` produces upper-case branch names
+like `ASW-7-as-acquired`. Keeping the legacy keys means leftover branches from
+before a team-key rename are still recognised. Deduplicate the matches. Bogus or
+malformed IDs simply error on lookup and are skipped with a warning — no separate
+validation pass.
+
+When a caller already has an `issues` list to hand (e.g. a changelog step emits
+one), use that instead of re-extracting.
+
+## Transition rules
+
+For each issue ID, call `mcp__linear-server__get_issue` to read its current
+state, then apply the rule for the target transition. All transitions are
+**idempotent** — an issue already at or past the target state is skipped
+silently.
+
+| Target          | Apply when current state is …              | Skip when current state is …                                | Fired by                            |
+| --------------- | ------------------------------------------ | ----------------------------------------------------------- | ----------------------------------- |
+| **In Progress** | `Triage`, `Backlog`, `Todo`                | `In Progress`, `In Review`, `Done`, `Canceled`, `Duplicate` | Starting work on an issue           |
+| **In Review**   | `Triage`, `Backlog`, `Todo`, `In Progress` | `In Review`, `Done`, `Canceled`, `Duplicate`                | PR open/update (a ship flow)        |
+| **Done**        | `Triage`, `Backlog`, `Todo`, `In Progress`, `In Review` | `Done`, `Canceled`, `Duplicate`                             | Branch cleanup                      |
+
+Apply a transition by calling `mcp__linear-server__save_issue` with
+`state: "<target>"` (or the resolved state ID).
+
+> `Canceled` is the Linear API's own US spelling — keep it as-is when referenced
+> in code or config.
+
+## Caller responsibilities (when / whether to fire)
+
+The skill owns the mechanics; each caller owns the policy:
+
+- **Start of work** — transition to `In Progress` when work begins on an issue
+  (unless already In Progress or further along). Run automatically; no prompt.
+- **Ship flow** (PR open/update) — transition linked issues to `In Review`
+  automatically after the PR is created or updated. No prompt.
+- **Branch cleanup** — transition orphaned issues to `Done` only **after explicit
+  confirmation, default no**. Linear's GitHub integration normally handles the
+  `Done` transition on PR merge, so this prompt exists only for the rare case
+  where the integration didn't fire (e.g. the issue ID was added after merge).
+
+## Standalone vs inside a caller
+
+- **Standalone** — resolve the target state, extract the branch's issue IDs,
+  apply the transition, and report which issues moved and which were skipped. The
+  default target is **In Progress** (the start-of-work transition that has no
+  other home).
+- **Inside a caller** — the caller supplies the target (and often the `issues`
+  list) and decides whether to prompt; the mechanics above are unchanged.
+
+## Implementation
+
+No supporting scripts — the skill drives the Linear MCP tools directly
+(`list_issue_statuses`, `get_issue`, `save_issue`). The only repo-specific inputs
+are the team name and the issue-ID prefixes, both read from `config.json`.

package/skills/linear-sync/config.example.json

@@ -0,0 +1,4 @@
+{
+  "linearTeamName": "Your Linear Team",
+  "issueKeys": ["ABC", "XYZ"]
+}

package/skills/linear-sync/config.json

@@ -0,0 +1,4 @@
+{
+  "linearTeamName": "ACME Skunkworks",
+  "issueKeys": ["ASW", "AKW", "SKW", "SK"]
+}

package/skills/linear-sync/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@acme-skunkworks/skill-linear-sync",
+  "version": "0.1.1",
+  "private": true,
+  "description": "Agent skill: transition the Linear issues linked to the current branch through their workflow states (In Progress / In Review / Done), resolving state IDs by team name and applying transitions idempotently.",
+  "keywords": [
+    "agent-skill",
+    "claude-code",
+    "cursor",
+    "linear",
+    "workflow",
+    "issue-tracking"
+  ],
+  "homepage": "https://github.com/acme-skunkworks/agent-skills/tree/main/skills/linear-sync#readme",
+  "bugs": {
+    "url": "https://github.com/acme-skunkworks/agent-skills/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/acme-skunkworks/agent-skills.git",
+    "directory": "skills/linear-sync"
+  },
+  "license": "MIT",
+  "author": {
+    "name": "Rob Easthope",
+    "url": "https://github.com/RobEasthope"
+  },
+  "engines": {
+    "node": ">=22"
+  }
+}

package/skills/preflight/README.md

@@ -0,0 +1,70 @@
+# preflight
+
+Change-gated, branch-scoped lint preflight: lint only the categories a branch
+touched (ESLint / markdownlint / actionlint) on `origin/<base>...HEAD` changed
+paths, classify each violation as **introduced** vs **pre-existing**, and drive a
+fix/defer loop via an exit-code contract (0 pass, 1 introduced/blocking, 2
+pre-existing only).
+
+## Install
+
+From any consumer repo:
+
+```bash
+npx skills add https://github.com/acme-skunkworks/agent-skills --skill preflight --agent claude-code --agent cursor --copy
+```
+
+`--copy` writes real files so the bundle is portable. Don't use `-g` / `--global`
+— the install should live in the consumer repo.
+
+## Requirements
+
+- Node.js ≥22 (per the package's `engines`) for the bundled scripts — **no npm
+  dependencies**, Node built-ins only, no build step.
+- The `git` CLI, for the branch/diff analysis.
+- The consumer repo's own **ESLint** and **markdownlint-cli2** (invoked via
+  `pnpm exec`), with their configs in place. preflight lints with your toolchain;
+  it does not bundle linters.
+- **actionlint** is optional: preflight warns and skips workflow linting if the
+  binary isn't on `PATH`.
+- The Linear MCP server is **optional**: the deferred-debt-issue step is skipped
+  silently when it is unavailable.
+
+## Configure
+
+Both repo-specific inputs **auto-detect**, so most repos configure nothing:
+
+- **Linted workspaces** come from `pnpm-workspace.yaml` + each package's `lint`
+  script (a workspace without a `lint` script is excluded automatically).
+- **Base branch** comes from `origin/HEAD`, falling back to `main`.
+
+To override either, drop a `preflight.config.json` at your **repo root**. A
+[`config.example.json`](config.example.json) ships as a template:
+
+```json
+{
+  "baseBranch": "main",
+  "workspaces": {
+    "web": { "filter": "@acme/web", "prefix": "apps/web/" }
+  }
+}
+```
+
+Either key may be supplied on its own; the other is still auto-detected. Use the
+override for non-pnpm repos, deliberate exclusions, or nested workspace globs the
+detector does not expand.
+
+## What it does
+
+Run from the repo root:
+
+```bash
+node skills/preflight/scripts/preflight.mjs            # the gate
+node skills/preflight/scripts/preflight.mjs --dry-run  # report scope only
+node skills/preflight/scripts/lint-fix.mjs             # scoped --fix pass
+```
+
+`preflight.mjs` writes `.preflight-summary.json` (categories run, introduced vs
+pre-existing counts) and exits `0` / `1` / `2` per the contract above. See
+[`SKILL.md`](SKILL.md) for the full loop, including how a standalone `/preflight`
+run differs from the lint gate inside a ship flow.

package/skills/preflight/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: preflight
+description: >-
+  Run a change-gated, branch-scoped lint preflight (ESLint / markdownlint /
+  actionlint) on the files a branch changes versus its base, classify each
+  violation as introduced vs pre-existing, and drive the fix/defer loop via an
+  exit-code contract (0 pass, 1 introduced/blocking, 2 pre-existing only). Use
+  when asked to run preflight, check whether a branch will pass lint before
+  pushing, or as the lint gate inside a ship/PR flow. Lints only the categories
+  the branch touched — not a whole-repo lint — with linted workspaces and the
+  base branch auto-detected, so a consuming repo configures nothing in the
+  common case.
+license: MIT
+compatibility: >-
+  Requires Node.js ≥22 for the bundled scripts (no npm dependencies — Node
+  built-ins only) and the `git` CLI for branch/diff analysis. ESLint,
+  markdownlint-cli2, and actionlint are invoked from the consumer repo's own
+  toolchain (via `pnpm exec`); actionlint is optional — preflight warns and skips
+  workflow linting if its binary is absent. The optional Linear debt-issue step
+  needs the Linear MCP server; skip it silently if unavailable.
+metadata:
+  version: 0.1.0
+allowed-tools: Read, Bash(git:*), Bash(pnpm:*), Bash(node:*), mcp__linear-server__save_issue, mcp__linear-server__list_issue_statuses
+---
+
+# preflight
+
+Change-gated, branch-scoped lint preflight. It lints only the categories relevant
+to `origin/<base>...HEAD`, on changed paths only — not a whole-repo `pnpm lint` —
+then classifies each violation as **introduced** (on a line this branch added or
+changed) or **pre-existing** (already there, in a file the branch happens to
+touch).
+
+This skill is the single source of truth for the preflight loop. It is invoked
+two ways:
+
+- **Standalone** (`/preflight`) — a quick "will my branch pass scoped lint?"
+  check, leaving any fixes in the working tree.
+- **Inside a ship flow** (e.g. `/send-it`) — the lint gate that runs after commits
+  and before the changelog/push steps.
+
+All bundled scripts use only Node built-ins — no `npm install`, no build step.
+They operate on the **consumer repo's root** (run them from the repo root, where
+`git` resolves the branch diff).
+
+## Running it
+
+1. Make sure the base branch is up to date: `git fetch origin <base>` (the base is
+   auto-detected — see Configuration).
+2. Run the preflight: `node skills/preflight/scripts/preflight.mjs` (append
+   `--dry-run` to report categories and scoped file lists without classifying
+   violations).
+3. Read `.preflight-summary.json` for the categories run and the violation counts
+   (`passed`, `deferred`, `blocking`).
+
+The script's exit code drives the loop:
+
+- **Exit 0 — pass.** No introduced violations and every linter ran cleanly.
+  Continue.
+- **Exit 1 — introduced violations (blocking).** Run
+  `node skills/preflight/scripts/lint-fix.mjs` on the branch-scoped paths, then
+  re-run preflight. Repeat until introduced violations clear or the user aborts.
+  (Inside a ship flow, commit the fixes; standalone, leave them in the working
+  tree for the user to review and commit.)
+- **Exit 2 — pre-existing violations only.** Show the list and ask the user to
+  choose:
+  - **Fix now** — apply the fixes, (commit if shipping), re-run preflight.
+  - **Defer** — open a debt issue in the project's tracker (assign the maintainer;
+    link the branch/PR context), then decide whether to continue or abort.
+
+Exit 1 can also signal a linter that failed to run (non-zero exit with no
+parseable violations) — inspect its stderr; this is blocking too.
+
+## Categories
+
+Each category is gated on what the branch changed (mirrors CI path triggers,
+narrower scope):
+
+| Category     | Runs when                                                                   | Skipped when                                                                                                        |
+| ------------ | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| ESLint       | Branch diff includes lintable code or eslint/tsconfig config paths          | Markdown-only or non-lintable changes                                                                               |
+| markdownlint | Branch diff includes `.md` / `.mdx` (respecting repo ignores)               | No markdown changes                                                                                                 |
+| actionlint   | Branch diff includes `.github/workflows/*.yml` or `.github/actionlint.yaml` | No workflow changes; config-only changes lint all tracked workflows; warns and skips if `actionlint` binary missing |
+
+ESLint runs per workspace (via `pnpm --filter`), plus a root/scripts bucket.
+Typecheck, tests, and framework checks (e.g. `astro check`) are **not** part of
+preflight — they stay in CI.
+
+## Standalone vs inside a ship flow
+
+- **Standalone (`/preflight`)** does the lint preflight and the exit-code loop,
+  then **reports**. On introduced violations it may run
+  `node skills/preflight/scripts/lint-fix.mjs` and re-run, but it leaves fixes
+  **in the working tree** — it never commits, writes a changelog, pushes, or opens
+  a PR.
+- **Inside `/send-it`** the same loop runs as the lint gate (after commits, before
+  changelog work); fixes are committed so the branch is clean before the changelog
+  is written. The changelog and its validation are **separate gates owned by the
+  ship flow** — they are not part of this skill.
+
+## Configuration
+
+The two repo-specific inputs are auto-detected — a consuming repo edits nothing in
+the common case:
+
+- **Linted workspaces** are derived from `pnpm-workspace.yaml` plus each package's
+  `package.json`: a workspace is included only if it declares a `lint` script. This
+  auto-excludes intentionally-unlinted workspaces and non-package directories
+  without a hand-maintained list.
+- **Base branch** is detected from `origin/HEAD` (e.g. `main`, `master`,
+  `develop`), falling back to `main` when that symbolic ref is absent.
+
+To override either, add a `preflight.config.json` at the **consumer repo root**
+(a [`config.example.json`](config.example.json) ships beside this file as a
+template):
+
+```json
+{
+  "baseBranch": "main",
+  "workspaces": {
+    "web": { "filter": "@acme/web", "prefix": "apps/web/" }
+  }
+}
+```
+
+Either key may be supplied on its own; the other is still auto-detected. Use the
+override for non-pnpm repos, deliberate exclusions, or nested workspace globs the
+detector does not expand.
+
+## Implementation
+
+The bundled scripts live beside this file under
+[`scripts/`](scripts/) and are invoked directly with `node` — no `pnpm` aliases,
+no `npm install`:
+
+- `scripts/preflight.mjs` — the change-gated preflight and exit-code contract.
+- `scripts/lint-fix.mjs` — scoped `eslint --fix` / `markdownlint-cli2 --fix` on the
+  branch-changed paths.
+- `scripts/classify-lint.mjs` — parse + classify violations as introduced vs
+  pre-existing.
+- `scripts/lib/{scope,diff-lines,paths}.mjs` — shared helpers (workspace/base-branch
+  detection, diff-line mapping, path normalisation).
+
+They have no external npm dependencies (Node built-ins only).
+
+## Arguments
+
+$ARGUMENTS