@sassywares/skills 0.0.0-stage → 0.2.0

package/CONCEPTS.md

@@ -0,0 +1,59 @@
+# Sassy Skills — Concepts
+
+## Source of truth
+
+The repo's `skills/` directory is the only copy of the skills. It ships as the npm package `@sassywares/skills`, so consumers pin a version rather than linking a directory; the sync service handles git commit and push.
+
+## Skill
+
+A directory containing `SKILL.md`, discovered by a harness from a project skills directory, a user skills directory, or an installed package. Skills are explicit workflows, not always-on instructions. Most have `disable-model-invocation: true` and are invoked with `/skill:<name>`.
+
+## Agent
+
+A specialized subagent defined under `~/.pi/agent/agents/`. Skills delegate bounded work to agents such as `scout`, `worker`, `reviewer`, and `validator`.
+
+## Orchestrator
+
+A skill that mostly coordinates. It reads compact results, writes briefs, and avoids reading source or diffs in the main context. `sassy-work`, `sassy-lfg`, `sassy-ship`, and `sassy-debug` are orchestrators.
+
+## Cycle
+
+`sassy-cycle` runs one unit of work through implement → review → validate → fix → re-check. It never commits. Work, LFG, and debug all use it.
+
+## Gates
+
+A gate is a deliberate stop or pass/fail condition.
+
+- **Fix gate** — `sassy-debug` presents the causal chain, fix, and risks before changing code.
+- **Code approval gate** — the user approves the code before committing or shipping. Always on for `sassy-work` and `sassy-lfg`.
+- **Ship review gate** — `sassy-ship` summarizes the close-out and waits in `mode:manual` (default); skipped only when the caller passed `mode:auto`.
+- **QA gate** — manual QA checklists, part of phase completion rather than a separate track: a phase turns `Done` only when the code is approved and every QA row passed. The user runs the rows; no agent ticks its own. It exists only when the plan document has QA tables; an in-context brief has none.
+
+## Modes
+
+Two mode tokens: `mode:manual` (default) and `mode:auto`. `mode:manual` asks at the skill's gate; `mode:auto` means pre-authorized, no review.
+
+- `sassy-ship` and `sassy-compound` accept both. Ship reviews the whole close-out in `mode:manual` and forwards `mode:auto` to compound once its own gate is answered.
+- `sassy-debug` accepts no mode. It always leaves ship's review gate in place.
+- `sassy-work` and `sassy-lfg` accept no mode.
+
+Everything else is decided by the artifact, not a mode:
+
+- A plan document under `docs/plans/` drives phased execution and carries manual QA tables.
+- An in-context brief drives one cycle and has no plan file and no QA tables.
+
+## Plan
+
+A durable document under `docs/plans/` with intent, decisions, constraints, phase tracking, and per-phase manual QA tables.
+
+## Brief
+
+A settled in-context brief produced by `sassy-plan` when the user picks "start working now" or "take it all the way". It carries the goal, decisions, constraints, work, and done-when, but no plan file and no QA tables.
+
+## Handoff
+
+`sassy-handoff` uses the `/handoff` extension to summarize the current session and continue in a fresh session. It is command-only because a skill cannot replace a session by itself.
+
+## Sync
+
+There is no background watcher. Any agent that changes a skill must run `scripts/sync.sh` immediately, without asking for confirmation. The sync script commits the change, rebases on `origin/main`, and pushes. It installs nothing: a changed skill reaches consumers only when a new version is released and a consumer bumps its pin.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sassywares
+
+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,334 @@
-# Temporary Holding Version
+# Sassy 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.
+**Lean and mean skills for shipping fast — with full control and 100% reliability.**
+
+Sassy Skills is a suite of explicit-invocation Agent Skills. It follows the Agent Skills format, so it works with any harness that can load `SKILL.md` workflows.
+
+It covers the whole path from a rough idea to a shipped PR, and from a bug report to a verified fix — without giving up human control at the moments that matter.
+
+## Table of contents
+
+- [Why this suite](#why-this-suite)
+- [Quick start](#quick-start)
+- [Skills](#skills)
+- [Project config](#project-config)
+- [Workflows](#workflows)
+  - [From idea to ship](#from-idea-to-ship)
+  - [From bug to ship](#from-bug-to-ship)
+- [Gates and controls](#gates-and-controls)
+- [Repository layout](#repository-layout)
+- [Installation](#installation)
+- [Repository maintenance](#repository-maintenance)
+
+## Why this suite
+
+- **Lean.** Skills are indexes and workflows, not documentation dumps. Detail moves into `references/` only when it is conditionally needed.
+- **Explicit.** Every skill is invoked deliberately. No silent background behavior.
+- **Controlled.** Code approval, manual QA, and ship review are visible gates that all run in sequence. There are two mode tokens, `mode:manual` (default) and `mode:auto`, accepted by `sassy-ship` and `sassy-compound` only; every other skill takes no mode.
+- **Reliable.** Work runs through `sassy-cycle` with isolated subagents for implementation, review, validation, and fixes.
+- **Context-efficient.** Orchestrators coordinate; subagents do the heavy reading and return compact results.
+- **Never surprising.** Nothing is committed just because a step finished. Shipping is its own phase.
+
+## Quick start
+
+Examples use simple slash commands.
+
+An optional first step: `/sassy-setup` detects the project and writes `.sassywares/config.yaml`, so plans, learnings, and PR bases land where your repo actually keeps them. Skipping it is fine — every key falls back to a documented default.
+
+```text
+/sassy-plan Add workspace invitations
+```
+
+That discussion settles the work, then offers a pick:
+
+```text
+Settled. Pick one:
+1. Write it to docs/plans/<slug>.md
+2. Start working now — stop before ship
+3. Take it all the way — run it, ship it, babysit the PR
+```
+
+Pick 1 to get a plan file, then run one phase at a time:
+
+```text
+/sassy-work docs/plans/add-workspace-invitations.md
+```
+
+Or take the whole plan through one session:
+
+```text
+/sassy-lfg docs/plans/add-workspace-invitations.md
+```
+
+For small work that does not need a plan document, choose 2 or 3 at the picker, or invoke the executor directly with the brief:
+
+```text
+/sassy-work "Add a copy-link button to the invite modal"
+/sassy-lfg "Add a copy-link button to the invite modal"
+```
+
+Debugging:
+
+```text
+/sassy-debug https://github.com/org/repo/issues/123
+```
+
+## Skills
+
+### Planning and execution
+
+| Skill | What it does |
+|---|---|
+| **`sassy-plan`** | Brainstorms and settles the work in one discussion, then offers three choices: write the plan, start working now, or take it all the way to a PR. |
+| **`sassy-scout`** | Grounds an area on demand and writes the shared grounding brief other agents read instead of re-exploring. |
+| **`sassy-work`** | Executes exactly one plan phase, or one in-context brief, commits after code approval, then hands off the next phase — a brief stops before ship. |
+| **`sassy-lfg`** | Executes every phase of a plan, or one in-context brief, then closes out via `sassy-ship` after code approval. |
+| **`sassy-cycle`** | Runs one unit of work through implement → review → validate → fix → re-check. |
+| **`sassy-debug`** | Diagnoses a bug, gates the fix, fixes via `sassy-cycle`, then ships after code approval. Debug takes no mode and always leaves ship's review gate in place unless you invoke ship yourself with `mode:auto`. |
+| **`sassy-handoff`** | Summarizes the session and opens a fresh one via `/handoff`, with the continuation prompt seeded in the editor for you to submit. |
+
+### Code quality
+
+| Skill | What it does |
+|---|---|
+| **`sassy-review`** | Reviews a diff, branch, PR, or files for bugs, project-rule conformance, and design-system conformance, then offers to fix findings. |
+| **`sassy-validate`** | Checks whether work matches a plan or stated intent, then offers to close gaps. |
+
+### Shipping
+
+| Skill | What it does |
+|---|---|
+| **`sassy-ship`** | Compound learnings, optional handbook, commit, PR, and babysit. Review gate in `mode:manual` (default), skipped by `mode:auto`. |
+| **`sassy-commit`** | Creates a local commit with a clear message. No push, no PR. |
+| **`sassy-commit-push-pr`** | Commits, pushes, opens or updates a PR, and babysits by default. |
+| **`sassy-babysit`** | Watches a PR until it looks merge-ready or blocked. |
+
+### Knowledge and docs
+
+| Skill | What it does |
+|---|---|
+| **`sassy-compound`** | Records a solved problem as a durable repo learning. Takes `mode:manual` or `mode:auto`; ship passes `mode:auto` after its own gate. |
+| **`sassy-handbook`** | Writes a plain-English team handbook with mermaid diagrams. |
+
+### Meta
+
+| Skill | What it does |
+|---|---|
+| **`sassy-skill`** | Creates, retunes, or restructures Agent Skills. |
+| **`sassy-setup`** | Detects the project topology and writes `.sassywares/config.yaml`; installs the snapshot tooling for a multi-repo workspace. |
+| **`sassy-compare`** | Runs one prompt against two models in isolated worktrees, with optional per-side thinking levels, and compares output, code changes, timing, tokens, and errors. |
+
+## Project config
+
+Every skill resolves one file, `.sassywares/config.yaml`, found by walking up from where you are. It is optional — no file means the documented defaults.
+
+```yaml
+artifacts:                       # where plans, learnings, handbooks, and the glossary live
+  plans: docs/plans
+  solutions: docs/solutions
+  handbooks: docs/handbooks
+  concepts: CONCEPTS.md
+knowledge:
+  read: [docs/solutions, CONCEPTS.md]   # searched for prior learnings
+  write: true                           # false = this project takes no learnings
+git:
+  repo: origin                   # a remote name | workspace (repos below, none here) | none (no git)
+  # remote: org/backup           # workspace only: the snapshot mirror; required when repo: workspace
+  default_branch: main           # what branches are cut from and PRs target
+repos:                           # workspace only: each nested repo -> the base its PRs target
+  fe: dev
+commit:
+  branch: current
+pr:
+  babysit: true
+  merge: false                   # true authorizes merging every babysat PR here
+  delete_branch: false
+hooks:                           # project steps injected into the PR pipeline
+  pr:
+    before_create: []            # after the commit, before the PR opens
+    after_create: []             # the moment the PR exists
+    before_merge: []             # this run is about to merge
+    after_merge: []              # this run observed the merge
+```
+
+### Extending the pipeline
+
+A project adds its own steps by naming a skill that lives in its own `.agents/skills/`. Nothing declared means nothing runs.
+
+| Hook | Runs | Typical use |
+|---|---|---|
+| `before_create` | after the commit, before the PR opens | release artifacts: changeset, release notes, i18n sync |
+| `after_create` | the PR was just created | labels, deploy-target comment |
+| `before_merge` | this run is about to merge | a final approval gate |
+| `after_merge` | this run observed the merge | sync a back-merge branch, tag, notify |
+
+Hooks run in declared order, one subagent each, and fail closed: a declared skill that is missing or returns `blocked` stops the run. Only `before_create` may commit its own output, because it runs after the pipeline's commit. `before_merge` and `after_merge` never fire unless this run merges.
+
+This is deliberately not a fork mechanism. A project skill that *adds* a step is a hook; one that *restates* our steps is a copy, and copies rot. Rules are not hooks either — those belong in `AGENTS.md`.
+
+Precedence is always explicit token > session instruction > config > skill default. `sassy-setup` writes the file from the tree it detects and keeps `pr.merge` off unless you say otherwise. The full schema, resolution chains, and the three topologies are in [`skills/sassy-setup/references/config.md`](skills/sassy-setup/references/config.md).
+
+In a `workspace` there is exactly one ignore file, and it is not at the root:
+
+```text
+.sassywares/
+├── config.yaml
+└── workspace/
+    ├── snapshot      installed by sassy-setup
+    ├── .gitignore    what the snapshot leaves out
+    └── mirror/       the side clone, excluded by the script itself
+```
+
+## Workflows
+
+### From idea to ship
+
+```mermaid
+flowchart LR
+  A[Idea] --> B[sassy-plan]
+  B --> C[Discussion]
+  C --> D{3-option picker}
+  D -->|1. plan document| E[docs/plans/slug.md]
+  D -->|2. start working| F[sassy-work]
+  D -->|3. take it all the way| G[sassy-lfg]
+  E --> F
+  E --> G
+  F --> H[sassy-cycle]
+  G --> H
+  H --> I{Code approval}
+  I -->|changes| H
+  I --> Q{Manual QA}
+  Q -->|fails| H
+  Q -->|passes, via sassy-work| J[Commit on current branch and stop]
+  Q -->|passes, via sassy-lfg| K[sassy-ship]
+  K --> L{Ship review}
+  L -->|approve or mode:auto| M[Commit, PR, babysit]
+```
+
+Option 1 produces a durable plan with phased slices and manual QA tables. Options 2 and 3 keep the whole job as one settled in-context brief and write no plan file.
+
+`sassy-work` handles one phase and hands off the next. `sassy-lfg` drains the whole plan in one session. Both delegate to `sassy-cycle` and stop at one gate carrying code approval plus the manual QA checklist; nothing is `Done`, committed, or shipped until both pass. With an in-context brief there are no QA rows, so the gate is code approval alone.
+
+Work always commits to the current branch; `sassy-ship` creates the shipping branch at close-out when the checked-out branch is the repo default.
+
+`sassy-ship` is the close-out. It summarizes what is about to ship and waits, unless the caller passed `mode:auto`.
+
+### From bug to ship
+
+```mermaid
+flowchart LR
+  A[Bug or issue] --> B[sassy-debug]
+  B --> C[Triage]
+  C --> D[scout helper]
+  D --> E{Fix gate}
+  E -->|1. fix it now| F[sassy-work]
+  E -->|2. write a plan| G[sassy-plan]
+  E -->|3. hand off| H[sassy-handoff]
+  E -->|4. stop| I[Diagnosis only]
+  F --> J{Code approval}
+  J -->|changes| F
+  J -->|approved| K[sassy-ship]
+  K --> L{Ship review}
+  L -->|approve| M[Commit, PR, babysit]
+```
+
+`sassy-debug` diagnoses inline, using the read-only `scout` as a helper to ground the failure surface; the causal reasoning stays in the main context. It then stops at the fix gate with the causal chain, proposed fix, and risks.
+
+The fix gate offers four options:
+
+- **Fix it now** — hand the fix brief to `sassy-work`: one cycle, its own code approval gate, a commit, then a stop before ship
+- **Write a plan** — carry the diagnosis into `sassy-plan`, which ends in its own 3-option picker
+- **Hand off** — continue in a fresh session via `sassy-handoff`
+- **Stop here** — keep the diagnosis and change nothing
+
+`sassy-debug` takes no mode. Shipping keeps its own `mode:manual` gate unless you invoke `sassy-ship` yourself with `mode:auto`.
+
+## Gates and controls
+
+| Control | When it applies |
+|---|---|
+| Code approval | Always on for `sassy-work` and `sassy-lfg`. |
+| Manual QA | Part of the same gate, and only when the plan document has QA tables. The user runs the rows; a phase is `Done` only when both pass. |
+| Ship review | On in `mode:manual` (default), skipped by `mode:auto`. |
+
+The artifact decides QA: a plan document carries manual QA tables that gate phase completion, an in-context brief does not. Gates are deliberate stops; the only way past one is the user's approval. `mode:auto` is accepted only by `sassy-ship` and `sassy-compound`.
+
+## Repository layout
+
+```text
+sassy-skills/
+├── skills/
+│   ├── sassy-plan/
+│   ├── sassy-work/
+│   ├── sassy-lfg/
+│   └── ...
+├── scripts/
+│   └── sync.sh
+├── AGENTS.md
+├── CONCEPTS.md
+└── README.md
+```
+
+## Installation
+
+The suite ships as the npm package **`@sassywares/skills`**. Pin it, don't symlink it into a global directory — the version in your lockfile is the pin, and upgrading is one command.
+
+### As a project dependency (recommended for teams)
+
+```bash
+bun add -d @sassywares/skills
+```
+
+Nothing scans `node_modules` on its own, so give your harness the directory it does read:
+
+```bash
+mkdir -p .agents/skills
+for d in node_modules/@sassywares/skills/skills/*/; do
+  ln -sfn "../../$d" ".agents/skills/$(basename "$d")"
+done
+```
+
+`.agents/skills/` is read by Cursor and pi. Claude Code reads `.claude/skills/` only, so add one directory symlink:
+
+```bash
+mkdir -p .claude && ln -sfn ../.agents/skills .claude/skills
+```
+
+Ignore both: they're derived from the lockfile, like any build output. A `postinstall` that runs the loop gives teammates zero setup beyond `bun install`; a preflight in the skills tells anyone who skipped it what to run.
+
+### As a pi package
+
+pi resolves packages directly, so no links are needed:
+
+```bash
+pi install npm:@sassywares/skills@0.1.0            # user-level, all projects
+pi install npm:@sassywares/skills@0.1.0 --local     # project-level → commit .pi/settings.json
+```
+
+### While editing the suite
+
+Point a consumer at your checkout instead of a published version:
+
+```bash
+bun link @sassywares/skills
+```
+
+Inside this repo, `.pi/settings.json` already declares `./skills`, so pi loads the working copy directly.
+
+Get the skills however they arrive — package, link, or vendored copy — and invoke them with your harness's skill syntax.
+
+## Repository maintenance
+
+`scripts/sync.sh` commits skill changes, rebases on `origin/main`, and pushes. Any agent that changes a skill must run it immediately, without asking for confirmation. It installs nothing anywhere — a change reaches consumers when a version is released and they bump their pin. `AGENTS.md` documents the workflow for agents working on this repo.
+
+### Releases
+
+Publishing is tag-driven. The `Publish` workflow (`.github/workflows/publish.yml`) validates every `skills/*/SKILL.md`, checks that the tag matches `package.json`, and publishes `@sassywares/skills` to npm on a `v*` tag push.
+
+```bash
+npm version patch --no-git-tag-version
+git add -A && git commit -m "chore: release v$(node -p "require('./package.json').version")"
+git push origin main
+git tag "v$(node -p "require('./package.json').version")"
+git push origin --tags
+```

package/bin/sassy-skills.mjs

@@ -0,0 +1,193 @@
+#!/usr/bin/env node
+// sassy-skills — wire this package's skills into a project.
+//
+// Nothing scans node_modules on its own, so the harnesses that read a project
+// skills directory need links. This tool creates them, checks them, and updates
+// the pinned version.
+//
+//   sassy-skills sync            link skills into .agents/skills (and .claude/skills)
+//   sassy-skills check           exit 1 if the wiring is missing or stale
+//   sassy-skills update          bump to the latest published version, then sync
+//
+// Options: --root <dir>  --quiet  --help
+import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, readlinkSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { execFileSync } from "node:child_process";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const SKILLS_DIR = resolve(HERE, "..", "skills");
+const PKG = JSON.parse(readFileSync(resolve(HERE, "..", "package.json"), "utf8"));
+const NAME = PKG.name;
+const VERSION = PKG.version;
+const REGISTRY = process.env.SASSY_SKILLS_REGISTRY ?? "https://registry.npmjs.org";
+
+const args = process.argv.slice(2);
+const quiet = args.includes("--quiet");
+const rootFlag = args.indexOf("--root");
+const rootValueIndex = rootFlag >= 0 ? rootFlag + 1 : -1;
+const ROOT = rootFlag >= 0 ? resolve(args[rootFlag + 1] ?? ".") : process.cwd();
+if (args.includes("--help") || args.includes("-h")) {
+  console.log(`sassy-skills@${VERSION}\n\n  sync     link skills into .agents/skills and .claude/skills\n  check    exit 1 when the wiring is missing or stale\n  update   bump ${NAME} to the latest version, then sync\n  outdated print a one-line nudge when a newer version is published (throttled, offline-safe)\n\nOptions: --root <dir>  --quiet  --force`);
+  process.exit(0);
+}
+
+const command = args.find((a, i) => !a.startsWith("-") && i !== rootValueIndex) ?? "sync";
+
+const log = (...a) => { if (!quiet) console.log(...a); };
+const ok = (m) => log(`  ✓ ${m}`);
+const warn = (m) => console.error(`  ! ${m}`);
+const die = (m) => { console.error(`  ✗ ${m}`); process.exit(1); };
+
+const IS_WIN = process.platform === "win32";
+
+function linkedSkills() {
+  if (!existsSync(SKILLS_DIR)) die(`package has no skills/ directory at ${SKILLS_DIR}`);
+  return readdirSync(SKILLS_DIR, { withFileTypes: true })
+    .filter((e) => e.isDirectory() && existsSync(join(SKILLS_DIR, e.name, "SKILL.md")))
+    .map((e) => e.name)
+    .sort();
+}
+
+function makeLink(target, linkPath) {
+  try {
+    if (lstatSync(linkPath).isSymbolicLink()) rmSync(linkPath);
+    else { warn(`${linkPath} exists and is not a symlink — leaving it alone`); return false; }
+  } catch { /* does not exist */ }
+  symlinkSync(target, linkPath, IS_WIN ? "junction" : "dir");
+  return true;
+}
+
+function sync() {
+  const skills = linkedSkills();
+  const agents = join(ROOT, ".agents", "skills");
+  mkdirSync(agents, { recursive: true });
+
+  let made = 0;
+  for (const name of skills) {
+    const target = resolve(SKILLS_DIR, name);
+    if (makeLink(target, join(agents, name))) made++;
+  }
+  ok(`${skills.length} skills linked into .agents/skills (${NAME}@${VERSION})`);
+
+  // Claude Code reads .claude/skills only. A directory symlink is enough, and it
+  // is the least invasive form when the directory does not already exist.
+  const claude = join(ROOT, ".claude", "skills");
+  try {
+    const st = lstatSync(claude);
+    if (!st.isSymbolicLink()) {
+      warn(".claude/skills exists and is not a symlink — Claude Code will not see the project skills unless you link them yourself");
+    }
+  } catch {
+    mkdirSync(dirname(claude), { recursive: true });
+    symlinkSync(IS_WIN ? join(ROOT, ".agents", "skills") : "../.agents/skills", claude, IS_WIN ? "junction" : "dir");
+    ok("linked .claude/skills → .agents/skills");
+  }
+
+  if (made) log(`\nRestart or /reload your harness to pick up the new skills.`);
+  return 0;
+}
+
+function check() {
+  const skills = linkedSkills();
+  const agents = join(ROOT, ".agents", "skills");
+  let problems = 0;
+
+  for (const name of skills) {
+    const link = join(agents, name);
+    const target = resolve(SKILLS_DIR, name);
+    try {
+      const st = lstatSync(link);
+      if (!st.isSymbolicLink()) { warn(`${name}: real directory, not a link`); problems++; continue; }
+      const points = resolve(agents, readlinkSync(link));
+      if (points !== target) { warn(`${name}: points at ${points}, expected ${target}`); problems++; }
+    } catch {
+      warn(`${name}: not linked`);
+      problems++;
+    }
+  }
+  if (!existsSync(join(ROOT, ".claude", "skills"))) warn(".claude/skills missing (Claude Code only)");
+  if (problems) { console.error(`  ✗ ${problems} skill link(s) need attention — run: sassy-skills sync`); return 1; }
+  ok(`${skills.length} skills correctly linked (${NAME}@${VERSION})`);
+  return 0;
+}
+
+function detectPM() {
+  if (existsSync(join(ROOT, "bun.lock")) || existsSync(join(ROOT, "bun.lockb"))) return "bun";
+  if (existsSync(join(ROOT, "pnpm-lock.yaml"))) return "pnpm";
+  if (existsSync(join(ROOT, "yarn.lock"))) return "yarn";
+  if (existsSync(join(ROOT, "package-lock.json"))) return "npm";
+  return null;
+}
+
+function update() {
+  const pm = detectPM();
+  if (!pm) die("no lockfile found — cannot tell which package manager to update with");
+  const spec = `${NAME}@latest`;
+  const cmd = {
+    bun: ["bun", ["add", "--dev", "--exact", spec]],
+    npm: ["npm", ["install", "--save-dev", "--save-exact", spec]],
+    pnpm: ["pnpm", ["add", "--save-dev", "--save-exact", spec]],
+    yarn: ["yarn", ["add", "--dev", "--exact", spec]],
+  }[pm];
+  log(`Updating ${NAME} with ${pm}…`);
+  execFileSync(cmd[0], cmd[1], { cwd: ROOT, stdio: "inherit" });
+  return sync();
+}
+
+function newerThan(a, b) {
+  const pa = String(a).split(/[.+-]/).map((x) => parseInt(x, 10) || 0);
+  const pb = String(b).split(/[.+-]/).map((x) => parseInt(x, 10) || 0);
+  for (let i = 0; i < 3; i++) {
+    if ((pa[i] ?? 0) !== (pb[i] ?? 0)) return (pa[i] ?? 0) > (pb[i] ?? 0);
+  }
+  return false;
+}
+
+function updateHint() {
+  const pm = detectPM();
+  const script = pm === "bun" ? "bun run skills:update"
+    : pm ? `${pm} run skills:update`
+    : "sassy-skills update";
+  return script;
+}
+
+// Non-blocking version nudge. Throttled to once a day per machine, silent when
+// offline, and it never fails a run — a stale pin is worth mentioning, not
+// worth blocking work over.
+async function outdated(force = false) {
+  const cacheFile = join(tmpdir(), "sassy-skills-version-check.json");
+  const TTL = 24 * 60 * 60 * 1000;
+  let cached = null;
+  try { cached = JSON.parse(readFileSync(cacheFile, "utf8")); } catch { /* first run */ }
+
+  let latest = null;
+  const fresh = cached && typeof cached.checkedAt === "number" && Date.now() - cached.checkedAt < TTL;
+  if (fresh && !force) {
+    latest = cached.latest ?? null;
+  } else {
+    try {
+      const res = await fetch(`${REGISTRY}/${encodeURIComponent(NAME)}/latest`, {
+        signal: AbortSignal.timeout(2000),
+        headers: { accept: "application/json" },
+      });
+      const body = await res.json();
+      latest = typeof body?.version === "string" ? body.version : null;
+    } catch { latest = null; }
+    try { writeFileSync(cacheFile, JSON.stringify({ checkedAt: Date.now(), latest })); } catch { /* read-only tmp */ }
+  }
+
+  if (!latest || !newerThan(latest, VERSION)) return 0;
+  console.log(`  ↑ ${NAME} ${VERSION} → ${latest} available — ${updateHint()}`);
+  return 0;
+}
+
+switch (command) {
+  case "outdated": process.exit(await outdated(args.includes("--force")));
+  case "sync": process.exit(sync());
+  case "check": process.exit(check());
+  case "update": process.exit(update());
+  default:
+    die(`unknown command: ${command} (try --help)`);
+}

package/package.json

@@ -1,6 +1,43 @@
 {
   "name": "@sassywares/skills",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Lean, explicit-invocation Agent Skills for shipping fast: plan, work, review, validate, ship.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Sassywares",
+  "homepage": "https://github.com/sassywares/sassy-skills#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sassywares/sassy-skills.git"
+  },
+  "bugs": {
+    "url": "https://github.com/sassywares/sassy-skills/issues"
+  },
+  "keywords": [
+    "pi-package",
+    "pi",
+    "agent-skills",
+    "skills",
+    "workflow",
+    "planning",
+    "code-review"
+  ],
+  "files": [
+    "skills",
+    "bin",
+    "README.md",
+    "CONCEPTS.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "pi": {
+    "skills": [
+      "./skills"
+    ]
+  },
+  "bin": {
+    "sassy-skills": "./bin/sassy-skills.mjs"
+  }
+}