@epicparty/skills 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 EpicParty
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE

@@ -0,0 +1,27 @@
+epicparty/skills
+
+Parts of this pack are adapted from mattpocock/skills (https://github.com/mattpocock/skills).
+UPSTREAM.md in the source repository lists which files, and where each one went.
+Those parts are used under the following license:
+
+MIT License
+
+Copyright (c) 2026 Matt Pocock
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,110 @@
-# Temporary Holding Version
+# epicparty/skills
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A delivery workflow for coding agents: from a request to a merged, deployed pull request. Explore the work, write it up as a story, build it test-first, open the PR, watch it, and ship it. A router skill reads a request and walks you through the route.
+
+**Credit:** several skills build on [Matt Pocock's skills](https://github.com/mattpocock/skills) — `grill`, `diagnose`, `architect` and `writing-for-agents`, and the test-first, seams, glossary and hand-off parts of others. Thank you, Matt. [`UPSTREAM.md`](./UPSTREAM.md) lists what came from where.
+
+The skills install under **your project's prefix**. Generic names like `implement` or `copy` say nothing about where a skill comes from, and they collide with other packs. With the prefix `acme`, you get `/acme` (the router), `/acme-implement`, `/acme-to-pr`, and so on. Each project picks its own.
+
+## Install
+
+```sh
+npx @epicparty/skills add --prefix acme
+```
+
+Without `--prefix`, the CLI asks for one. It builds the skills under that prefix and installs them with the [`skills`](https://github.com/vercel-labs/skills) CLI, which links them for every agent it supports (Claude Code, Codex, Cursor and others). Pass `--agent <name>` to choose agents.
+
+The prefix and the version go into `epicparty-skills.json` at the project root. Commit it.
+
+```sh
+npx @epicparty/skills@latest update   # same prefix and agents, newer skills
+npx @epicparty/skills remove
+npx @epicparty/skills add --dry-run --prefix acme   # build and check only
+```
+
+Do not install this repository with `npx skills add epicparty/skills` directly. That installs the skills under their bare folder names (`implement`, `copy`), while their text refers to each other with a prefix.
+
+## The skills
+
+| Skill | What it does |
+| --- | --- |
+| `<prefix>` | Reads a request, names the route through the skills, and walks it. Start here. `/<prefix> handoff` hands a thread to a fresh agent. |
+| `<prefix>-setup` | Asks every unset setting up front, or changes one. |
+| `<prefix>-explore` | Maps what a piece of work involves before anything is decided. |
+| `<prefix>-grill` | Grills you on a plan in rounds of questions, and keeps the glossary and ADRs as it settles things. |
+| `<prefix>-to-story` | Writes the conversation up as one user story on the tracker. |
+| `<prefix>-triage` | Judges one existing issue and ends in one verdict. |
+| `<prefix>-implement` | Builds one story on one branch: test-first, validated, reviewed, committed. |
+| `<prefix>-diagnose` | Finds and fixes a failure with a loop that goes red on it before any theory. |
+| `<prefix>-architect` | Recommends how to architect a feature, or judges your design. On request, scans a named area for modules worth deepening. |
+| `<prefix>-code-review` | Reviews code on two axes: the project's standards, and the spec. |
+| `<prefix>-to-pr` | Opens a pull request with its suite report and issue link. |
+| `<prefix>-babysit` | Sweeps an open PR toward merged. |
+| `<prefix>-ship` | Merges, confirms the production deploy, and cleans the checkout. |
+| `<prefix>-deliver` | Delivers the stories marked to start, in sequence or across parallel workers. |
+| `<prefix>-copy` | Writes or reviews user-facing copy. |
+| `<prefix>-research` | Investigates a question against primary sources. |
+| `<prefix>-outdated` | Reports which dependencies of a pnpm workspace have newer releases, and what changed. |
+| `<prefix>-upgrade` | Upgrades those dependencies and migrates the code. |
+| `<prefix>-writing-for-agents` | How to write skills, `AGENTS.md` and anything else an agent reads. |
+
+GitHub (issues, pull requests, Projects) is built in. Another tracker works when you describe it in the **Tracker** setting, and a project with no tracker answers **None**.
+
+## Settings
+
+The skills ask for a project fact the first time they need it: the tracker, the labels, how to run the full test suite, how a deploy is confirmed. Each answer is saved where you choose — by default `docs/agents/<topic>.md`, one file per topic — and is never asked again. Run `/<prefix>-setup` to answer them all at once, or to change one.
+
+Each skill declares its own settings in its `## Settings` section, so the list grows with the skills you install.
+
+## How the prefix is applied
+
+The skills in this repository are written with the prefix `ep`, and the router's folder is `skills/router`. The CLI rewrites, in every Markdown file:
+
+- `/ep` to `/<prefix>`, and `/ep-<skill>` or `ep-<skill>` to `<prefix>-<skill>`;
+- `ep-*` to `<prefix>-*`;
+- links into a sibling skill's folder, `../<skill>/`, to `../<prefix>-<skill>/`, and `../router/` to `../<prefix>/`;
+- each `SKILL.md`'s `name` to its installed name: `router` becomes `<prefix>`.
+
+Then it checks the result: every name matches its folder, every link and heading anchor resolves, and every skill named in the text is installed. Each skill also carries `pack: epicparty/skills` under `metadata`, which is how `/<prefix>-setup` finds the pack's skills whatever the prefix.
+
+`npx @epicparty/skills check` runs the same check on an installed project.
+
+## Limits
+
+- Project installs only. Global (`-g`) installs are not supported yet.
+- `outdated` and `upgrade` work on pnpm workspaces only. The other skills read the package manager from the lockfile.
+- Unattended runs (`/loop`) read the board and the dependency edges with `gh api`, and link branches with `gh issue develop`. Allow both in your agent's permissions, or each beat stops at its first read.
+- A repo with no remote works up to a local commit: the skills that push, open a PR, merge or deploy stop there and say so.
+- The `skills` CLI records each skill it installs in `skills-lock.json`. This CLI removes its own skills from that file, because the `skills` CLI cannot update them; `update` here replaces `skills update` for this pack.
+
+## Versions
+
+The pack has a version, and so does each skill: `metadata.version` in its `SKILL.md`. A skill's version moves only when that skill changes, so `implement` can stay at 0.3.0 while `triage` reaches 0.5.1. `epicparty-skills.json` records the version of every installed skill, and `update` lists the skills it added, removed or moved to a new version.
+
+[`CHANGELOG.md`](./CHANGELOG.md) says what changed in each release, skill by skill.
+
+## Develop
+
+```sh
+npm install
+npm test
+node bin/cli.mjs build --prefix acme --out /tmp/acme
+node bin/cli.mjs add --from ./skills --prefix acme   # in a test project
+npx changeset                                        # describe a change for the next release
+```
+
+## Releasing
+
+Releases run on [Changesets](https://github.com/changesets/changesets), the way [mattpocock/skills](https://github.com/mattpocock/skills) runs them:
+
+1. **Every pull request that changes the pack adds a changeset** — `npx changeset` — whose entry starts with the skills it changes. [`.changeset/README.md`](./.changeset/README.md) has the format and the bump levels. CI fails a pull request that changes a skill and names it in no changeset.
+2. **On each push to `main`**, the Release workflow opens or updates a `chore: release` pull request. It bumps the pack's version and each named skill's, and writes `CHANGELOG.md`.
+3. **Merging that pull request is the release.** The workflow tags `v<version>` and publishes a GitHub release from the changelog.
+
+Until npm publishing is on, a project installs a release from GitHub: `npx github:epicparty/skills#v<version> add --prefix acme`. To turn npm on, set up [trusted publishing](https://docs.npmjs.com/trusted-publishers) for `@epicparty/skills`, add `id-token: write` to the workflow's permissions, and change its `publish-script` to `npx changeset publish`.
+
+The GitHub repository must allow it: **Settings → Actions → General → Allow GitHub Actions to create and approve pull requests**.
+
+## License
+
+MIT. Parts are adapted from [mattpocock/skills](https://github.com/mattpocock/skills), also MIT: [`NOTICE`](./NOTICE) carries its license, and every installed skill that holds adapted text ships a copy. [`UPSTREAM.md`](./UPSTREAM.md) maps each adapted file and says how to sync with upstream.

package/bin/cli.mjs

@@ -0,0 +1,175 @@
+#!/usr/bin/env node
+// Installs the epicparty/skills pack under a project's own prefix, through the `skills` CLI.
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { createInterface } from 'node:readline/promises';
+import { parseArgs } from 'node:util';
+import { fileURLToPath } from 'node:url';
+import { build, check, packSkills, skillVersion, validatePrefix } from '../lib/transform.mjs';
+
+const PKG_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const PKG = JSON.parse(readFileSync(join(PKG_ROOT, 'package.json'), 'utf8'));
+const LOCK = 'epicparty-skills.json';
+const SKILLS_CLI = process.env.EPICPARTY_SKILLS_CLI ?? 'skills@1';
+
+const HELP = `${PKG.name} ${PKG.version}
+
+Usage:
+  npx ${PKG.name} add [--prefix <p>] [--agent <a>]...   Install the pack as <p>, <p>-implement, ...
+  npx ${PKG.name} update                                Reinstall with the prefix and agents in ${LOCK}
+  npx ${PKG.name} remove                                Remove the pack's skills
+  npx ${PKG.name} build --prefix <p> --out <dir>        Write the prefixed skills to a folder, install nothing
+  npx ${PKG.name} check --prefix <p> [<dir>]            Check installed skills (default .agents/skills)
+
+Options:
+  --prefix <p>   The project's prefix. Asked on first install, then read from ${LOCK}.
+  --agent <a>    Passed to the skills CLI (repeatable). Default: the agents it detects.
+  --from <dir>   Use the skills in <dir> instead of the ones bundled with this version.
+  --dry-run      Build and check in a temporary folder, install nothing.
+`;
+
+function fail(message) {
+  console.error(`error: ${message}`);
+  process.exit(1);
+}
+
+function readLock(cwd) {
+  const path = join(cwd, LOCK);
+  return existsSync(path) ? JSON.parse(readFileSync(path, 'utf8')) : null;
+}
+
+/** The installed skills a lock records, as { name: version }. Older locks list names only. */
+function lockedSkills(lock) {
+  const skills = lock?.skills ?? {};
+  return Array.isArray(skills) ? Object.fromEntries(skills.map((n) => [n, null])) : skills;
+}
+
+/** One line per skill that is new, gone or at another version. */
+function versionChanges(before, after) {
+  const lines = [];
+  for (const [name, version] of Object.entries(after)) {
+    if (!(name in before)) lines.push(`  + ${name} ${version}`);
+    else if (before[name] !== version) lines.push(`  ~ ${name} ${before[name] ?? '?'} -> ${version}`);
+  }
+  for (const name of Object.keys(before)) if (!(name in after)) lines.push(`  - ${name}`);
+  return lines;
+}
+
+function writeLock(cwd, lock) {
+  writeFileSync(join(cwd, LOCK), `${JSON.stringify(lock, null, 2)}\n`);
+}
+
+function skillsCli(args, cwd) {
+  console.log(`$ npx ${SKILLS_CLI} ${args.join(' ')}`);
+  const r = spawnSync('npx', ['-y', SKILLS_CLI, ...args], { cwd, stdio: 'inherit' });
+  if (r.status !== 0) fail(`the skills CLI exited with ${r.status}`);
+}
+
+// The skills CLI records each install from a local folder in skills-lock.json. That folder is
+// gone after install, so those entries could never be restored or updated: this CLI owns them.
+function dropFromSkillsLock(cwd, names) {
+  const path = join(cwd, 'skills-lock.json');
+  if (!existsSync(path)) return;
+  const lock = JSON.parse(readFileSync(path, 'utf8'));
+  let changed = false;
+  for (const name of names) {
+    if (lock.skills?.[name]?.sourceType === 'local') {
+      delete lock.skills[name];
+      changed = true;
+    }
+  }
+  if (!changed) return;
+  if (Object.keys(lock.skills ?? {}).length === 0) rmSync(path);
+  else writeFileSync(path, `${JSON.stringify(lock, null, 2)}\n`);
+}
+
+async function askPrefix() {
+  if (!process.stdin.isTTY) fail(`no prefix: pass --prefix <p>, or run once with a terminal to be asked`);
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  const answer = (await rl.question('Prefix for this project\'s skills (e.g. "ep" gives /ep, /ep-implement): ')).trim();
+  rl.close();
+  return answer;
+}
+
+function sourceDir(from) {
+  const dir = from ? resolve(from) : join(PKG_ROOT, 'skills');
+  if (!existsSync(dir)) fail(`no skills folder at ${dir}`);
+  return dir;
+}
+
+function buildChecked(source, prefix, out) {
+  const names = build(source, prefix, out);
+  const problems = check(out, prefix, { canonicalSkills: packSkills(source) });
+  if (problems.length) fail(`the built skills are inconsistent:\n  ${problems.join('\n  ')}`);
+  return names;
+}
+
+async function install(cwd, opts, lock) {
+  const prefix = validatePrefix(opts.prefix ?? lock?.prefix ?? (await askPrefix()));
+  const agents = opts.agent?.length ? opts.agent : (lock?.agents ?? []);
+  const stage = mkdtempSync(join(tmpdir(), 'epicparty-skills-'));
+  try {
+    const names = buildChecked(sourceDir(opts.from), prefix, join(stage, 'skills'));
+    if (opts['dry-run']) {
+      console.log(`Built ${names.length} skills for prefix "${prefix}" in ${stage}: ${names.join(', ')}`);
+      return;
+    }
+    const before = lockedSkills(lock);
+    const after = Object.fromEntries(names.map((n) => [n, skillVersion(join(stage, 'skills', n))]));
+    const stale = Object.keys(before).filter((n) => !names.includes(n));
+    if (stale.length) skillsCli(['remove', ...stale, '-y'], cwd);
+    skillsCli(['add', stage, '--skill', '*', ...agents.flatMap((a) => ['--agent', a]), '-y'], cwd);
+    dropFromSkillsLock(cwd, names);
+    writeLock(cwd, {
+      prefix,
+      version: PKG.version,
+      source: opts.from ? resolve(opts.from) : PKG.name,
+      agents,
+      skills: after,
+    });
+    console.log(`Installed ${names.length} skills as ${prefix}, ${prefix}-*. Recorded in ${LOCK}.`);
+    const changes = versionChanges(before, after);
+    if (lock && changes.length) console.log(`Changed:\n${changes.join('\n')}`);
+  } finally {
+    if (!opts['dry-run']) rmSync(stage, { recursive: true, force: true });
+  }
+}
+
+const { values: opts, positionals } = parseArgs({
+  allowPositionals: true,
+  options: {
+    prefix: { type: 'string' },
+    agent: { type: 'string', multiple: true },
+    from: { type: 'string' },
+    out: { type: 'string' },
+    'dry-run': { type: 'boolean' },
+    help: { type: 'boolean', short: 'h' },
+    version: { type: 'boolean', short: 'v' },
+  },
+});
+const [command, ...rest] = positionals;
+const cwd = process.cwd();
+
+if (opts.version) console.log(PKG.version);
+else if (opts.help || !command) console.log(HELP);
+else if (command === 'add') await install(cwd, opts, readLock(cwd));
+else if (command === 'update') {
+  const lock = readLock(cwd) ?? fail(`no ${LOCK} here: run "add" first`);
+  await install(cwd, { ...opts, prefix: opts.prefix ?? lock.prefix }, lock);
+} else if (command === 'remove') {
+  const lock = readLock(cwd) ?? fail(`no ${LOCK} here: nothing to remove`);
+  skillsCli(['remove', ...Object.keys(lockedSkills(lock)), '-y'], cwd);
+  rmSync(join(cwd, LOCK));
+} else if (command === 'build') {
+  if (!opts.prefix || !opts.out) fail('build needs --prefix and --out');
+  const names = buildChecked(sourceDir(opts.from), validatePrefix(opts.prefix), resolve(opts.out));
+  console.log(`Built ${names.length} skills in ${resolve(opts.out)}`);
+} else if (command === 'check') {
+  const prefix = validatePrefix(opts.prefix ?? readLock(cwd)?.prefix ?? fail('check needs --prefix'));
+  const dir = resolve(rest[0] ?? '.agents/skills');
+  const problems = check(dir, prefix, { canonicalSkills: packSkills(sourceDir(opts.from)) });
+  if (problems.length) fail(`${problems.length} problem(s):\n  ${problems.join('\n  ')}`);
+  console.log(`OK: the ${prefix} skills in ${dir} are consistent.`);
+} else fail(`unknown command "${command}"\n\n${HELP}`);

package/lib/transform.mjs

@@ -0,0 +1,185 @@
+// Turns the pack's unprefixed skills into skills named for one project's prefix,
+// and checks that a set of installed skills is consistent with that prefix.
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, join, relative, resolve } from 'node:path';
+
+/** The prefix the pack's own text is written with. */
+export const CANONICAL = 'ep';
+/** The router's folder in the pack. It installs under the bare prefix. */
+export const ROUTER = 'router';
+export const MARKER = 'pack: epicparty/skills';
+
+/** Marks text adapted from another project; UPSTREAM.md maps each one. */
+export const UPSTREAM_MARK = '<!-- upstream: ';
+
+const PREFIX_RE = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+
+export function validatePrefix(prefix) {
+  if (!PREFIX_RE.test(prefix ?? '')) {
+    throw new Error(`Invalid prefix "${prefix}": use lowercase letters, digits and single hyphens, starting with a letter (e.g. "ep", "acme").`);
+  }
+  return prefix;
+}
+
+/** The skill folders of the pack: every directory holding a SKILL.md. */
+export function packSkills(sourceDir) {
+  return readdirSync(sourceDir)
+    .filter((name) => existsSync(join(sourceDir, name, 'SKILL.md')))
+    .sort();
+}
+
+/** The name a pack skill installs under. The router takes the bare prefix. */
+export function installedName(skill, prefix) {
+  return skill === ROUTER ? prefix : `${prefix}-${skill}`;
+}
+
+const escape = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+/** One-pass rewrite of every canonical reference in a Markdown text. */
+export function rewriteText(text, skills, prefix) {
+  const names = [...skills].filter((s) => s !== ROUTER).sort((a, b) => b.length - a.length).map(escape);
+  const alt = names.join('|');
+  const re = new RegExp(
+    [
+      // ../<skill>/  — a link into a sibling skill's folder
+      `(?<link>\\.\\./)(?<dir>${escape(ROUTER)}|${alt})(?=/)`,
+      // ep-<skill> and ep-*  — a skill name, with or without its slash
+      `(?<![\\w-])${escape(CANONICAL)}-(?<name>${alt}|\\*)(?![\\w-])`,
+      // /ep  — the router's slash command
+      `(?<![\\w/.-])/${escape(CANONICAL)}(?<router>)(?![\\w-])`,
+    ].join('|'),
+    'g',
+  );
+  return text.replace(re, (...args) => {
+    const g = args.at(-1);
+    if (g.link !== undefined) return `../${installedName(g.dir, prefix)}`;
+    if (g.name !== undefined) return `${prefix}-${g.name}`;
+    return `/${prefix}`;
+  });
+}
+
+function rewriteFrontmatterName(text, skill, prefix) {
+  const end = text.indexOf('\n---', 3);
+  if (!text.startsWith('---\n') || end < 0) throw new Error(`${skill}/SKILL.md has no frontmatter`);
+  const head = text.slice(0, end).replace(/^name: .*$/m, `name: ${installedName(skill, prefix)}`);
+  return head + text.slice(end);
+}
+
+function walk(dir) {
+  return readdirSync(dir).flatMap((entry) => {
+    const path = join(dir, entry);
+    return statSync(path).isDirectory() ? walk(path) : [path];
+  });
+}
+
+/** Writes the prefixed skills into outDir, one folder per installed name. Returns the names. */
+export function build(sourceDir, prefix, outDir) {
+  validatePrefix(prefix);
+  const skills = packSkills(sourceDir);
+  if (!skills.includes(ROUTER)) throw new Error(`The pack at ${sourceDir} has no "${ROUTER}" skill.`);
+  mkdirSync(outDir, { recursive: true });
+  for (const skill of skills) {
+    const from = join(sourceDir, skill);
+    const to = join(outDir, installedName(skill, prefix));
+    for (const file of walk(from)) {
+      const target = join(to, relative(from, file));
+      mkdirSync(dirname(target), { recursive: true });
+      if (!file.endsWith('.md')) {
+        cpSync(file, target);
+        continue;
+      }
+      let text = rewriteText(readFileSync(file, 'utf8'), skills, prefix);
+      if (relative(from, file) === 'SKILL.md') text = rewriteFrontmatterName(text, skill, prefix);
+      writeFileSync(target, text);
+    }
+    // A skill carrying text adapted from another project ships that project's license with it.
+    const notice = join(sourceDir, '..', 'NOTICE');
+    const adapted = walk(from).some((f) => f.endsWith('.md') && readFileSync(f, 'utf8').includes(UPSTREAM_MARK));
+    if (adapted && existsSync(notice)) cpSync(notice, join(to, 'NOTICE'));
+  }
+  return skills.map((s) => installedName(s, prefix));
+}
+
+/** A skill's own version: `metadata.version` in its SKILL.md frontmatter, or null. */
+export function skillVersion(skillDir) {
+  const fm = /^---\n([\s\S]*?)\n---/.exec(readFileSync(join(skillDir, 'SKILL.md'), 'utf8'))?.[1] ?? '';
+  return /^ {2}version: (\S+)\s*$/m.exec(fm)?.[1] ?? null;
+}
+
+/** GitHub's heading anchor: lowercase, punctuation dropped, spaces to hyphens. */
+export function slug(heading) {
+  return heading
+    .trim()
+    .toLowerCase()
+    .replace(/[`*_]/g, '')
+    .replace(/[^\p{L}\p{N}\s-]/gu, '')
+    .replace(/\s/g, '-');
+}
+
+function anchors(text) {
+  const seen = new Map();
+  const out = new Set();
+  for (const line of text.replace(/```[\s\S]*?```/g, '').split('\n')) {
+    const m = /^#{1,6}\s+(.*)$/.exec(line);
+    if (!m) continue;
+    const base = slug(m[1]);
+    const n = seen.get(base) ?? 0;
+    seen.set(base, n + 1);
+    out.add(n === 0 ? base : `${base}-${n}`);
+  }
+  return out;
+}
+
+/**
+ * Checks installed pack skills in dir (folders named <prefix>-<skill> and <prefix>).
+ * Returns a list of problems; empty means consistent.
+ */
+export function check(dir, prefix, { canonicalSkills } = {}) {
+  validatePrefix(prefix);
+  const problems = [];
+  const installed = readdirSync(dir).filter((name) => {
+    const file = join(dir, name, 'SKILL.md');
+    return existsSync(file) && readFileSync(file, 'utf8').includes(`\n  ${MARKER}\n`);
+  });
+  const set = new Set(installed);
+  if (!set.has(prefix)) problems.push(`router "${prefix}" is not installed`);
+  const nameRe = new RegExp(`(?<![\\w-])/?${escape(prefix)}-([a-z0-9]+(?:-[a-z0-9]+)*|\\*)(?![\\w-])`, 'g');
+  const canonical = canonicalSkills?.filter((s) => s !== ROUTER).map(escape).join('|');
+  const leftovers = [];
+  if (prefix !== CANONICAL && canonical) leftovers.push(`(?<![\\w-])${CANONICAL}-(?:${canonical})(?![\\w-])`, `(?<![\\w/.-])/${CANONICAL}(?![\\w-])`);
+  if (prefix !== ROUTER) leftovers.push(`\\.\\./${ROUTER}/`);
+  const leftover = leftovers.length ? new RegExp(leftovers.join('|'), 'g') : null;
+
+  for (const name of installed) {
+    const root = join(dir, name);
+    const skillText = readFileSync(join(root, 'SKILL.md'), 'utf8');
+    const fm = /^---\n([\s\S]*?)\n---/.exec(skillText)?.[1] ?? '';
+    const declared = /^name: (.*)$/m.exec(fm)?.[1];
+    if (declared !== name) problems.push(`${name}/SKILL.md: name is "${declared}", folder is "${name}"`);
+    if (!/^description: .+/m.test(fm)) problems.push(`${name}/SKILL.md: no description`);
+
+    for (const file of walk(root).filter((f) => f.endsWith('.md'))) {
+      const where = relative(dir, file);
+      const text = readFileSync(file, 'utf8');
+      const prose = text.replace(/```[\s\S]*?```/g, '').replace(/`[^`\n]*`/g, '');
+      for (const m of prose.matchAll(/\]\(([^)\s]+)\)/g)) {
+        const href = m[1];
+        if (/^[a-z]+:/i.test(href)) continue;
+        const [path, hash] = href.split('#');
+        const target = path ? resolve(dirname(file), path) : file;
+        if (!existsSync(target)) {
+          problems.push(`${where}: link ${href} points to a missing file`);
+          continue;
+        }
+        if (hash && target.endsWith('.md') && !anchors(readFileSync(target, 'utf8')).has(hash)) {
+          problems.push(`${where}: link ${href} points to a missing heading`);
+        }
+      }
+      for (const m of text.matchAll(nameRe)) {
+        if (m[1] !== '*' && !set.has(`${prefix}-${m[1]}`)) problems.push(`${where}: names ${m[0]}, which is not installed`);
+      }
+      if (leftover) for (const m of text.matchAll(leftover)) problems.push(`${where}: canonical reference "${m[0]}" was not rewritten`);
+    }
+  }
+  return problems;
+}

package/package.json

@@ -1,6 +1,39 @@
 {
   "name": "@epicparty/skills",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "A delivery workflow for coding agents — explore, story, implement, PR, ship — installed under your project's own prefix.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "epicparty-skills": "bin/cli.mjs"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "skills",
+    "NOTICE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "node --test",
+    "changeset": "changeset",
+    "version": "node scripts/version-skills.mjs && changeset version",
+    "check:changesets": "node scripts/version-skills.mjs --check"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/epicparty/skills.git"
+  },
+  "keywords": [
+    "agent-skills",
+    "claude-code",
+    "codex",
+    "skills"
+  ],
+  "devDependencies": {
+    "@changesets/changelog-github": "1.0.1",
+    "@changesets/cli": "3.0.3"
+  }
+}

package/skills/architect/DESIGN-IT-TWICE.md

@@ -0,0 +1,46 @@
+# Design it twice
+
+<!-- upstream: mattpocock/skills skills/engineering/codebase-design/DESIGN-IT-TWICE.md -->
+
+When the shape of an interface is the open question — for a new feature's module, or a chosen deepening candidate — use this parallel sub-agent pattern. Where subagents are unavailable, write the designs yourself, one after another, each under its own constraint, and keep step 3 as it is. Based on "Design It Twice" (Ousterhout): your first idea is unlikely to be the best.
+
+Uses the vocabulary in [`SEAMS.md`](../to-story/SEAMS.md): **module**, **interface**, **seam**, **adapter**, **leverage**.
+
+## Process
+
+### 1. Frame the problem space
+
+Before spawning sub-agents, write a user-facing explanation of the problem space for the chosen candidate:
+
+- The constraints any new interface would need to satisfy
+- The dependencies it would rely on, and which category they fall into (see [`SEAMS.md`](../to-story/SEAMS.md#dependencies-decide-how-a-seam-is-tested))
+- A rough illustrative code sketch to ground the constraints, not a proposal, just a way to make the constraints concrete
+
+Show this to the user, then immediately proceed to Step 2. The user reads and thinks while the sub-agents work in parallel.
+
+### 2. Spawn sub-agents
+
+Spawn 3+ sub-agents in parallel, each with a fresh context window. Each must produce a **radically different** interface for the deepened module.
+
+Prompt each sub-agent with a separate technical brief (file paths, coupling details, dependency category from `SEAMS.md`, what sits behind the seam). The brief is independent of the user-facing problem-space explanation in Step 1. Give each agent a different design constraint:
+
+- Agent 1: "Minimize the interface: aim for 1–3 entry points max. Maximise leverage per entry point."
+- Agent 2: "Maximise flexibility: support many use cases and extension."
+- Agent 3: "Optimise for the most common caller: make the default case trivial."
+- Agent 4 (if applicable): "Design around ports & adapters for cross-seam dependencies."
+
+Include both the `SEAMS.md` vocabulary and the project glossary's in the brief so each sub-agent names things consistently with the architecture language and the project's domain language.
+
+Each sub-agent outputs:
+
+1. Interface (types, methods, params, plus invariants, ordering, error modes)
+2. Usage example showing how callers use it
+3. What the implementation hides behind the seam
+4. Dependency strategy and adapters, by the `SEAMS.md` categories
+5. Trade-offs: where leverage is high, where it's thin
+
+### 3. Present and compare
+
+Present designs sequentially so the user can absorb each one, then compare them in prose. Contrast by **depth** (leverage at the interface), **locality** (where change concentrates), and **seam placement**.
+
+After comparing, give your own recommendation: which design you think is strongest and why. If elements from different designs would combine well, propose a hybrid. Be opinionated: the user wants a strong read, not a menu.