feat(M5): Final hardening, CI surface, and documentation closeout

docs/DEVELOPMENT.md

@@ -1,7 +1,7 @@
 # Development Guide — ai-coding-skills
 
-This document covers prerequisites, how to run checks locally, the M1 quality
-tooling, the workspace policy, and the transitional `pnpm run check` contract.
+This document covers prerequisites, how to run checks locally, the quality
+tooling, the workspace policy, and the `pnpm run check` contract.
 
 ## Prerequisites
 
@@ -154,22 +154,29 @@ This runs the full `pnpm run check` suite (lint, typecheck, test, verify:pi,
 verify:reviewers, verify:docs, verify:generated) inside a clean Debian Bookworm
 container with Node 20.
 
-## Transitional `check` contract (M1)
+## `check` contract (final — M5)
 
-`pnpm run check` may exit non-zero in M1.  This is expected.  The contract is:
+`pnpm run check` is **fully green** on a clean checkout with the documented
+prerequisites installed.
 
-> `pnpm run check` exits non-zero **only** on issues recorded in
-> `docs/CLEANUP-BASELINE.md`.  Previously-green checks remain green.  No
-> violations are introduced by M1's own changes.
+```text
+PASS  lint
+PASS  typecheck
+PASS  test
+PASS  verify:pi
+PASS  verify:reviewers
+PASS  verify:docs
+PASS  verify:generated
+```
 
-**M2 update:** `verify:docs` is now green. `lint` still fails on the same
-2 pre-existing ESLint violations and 7 pre-existing shellcheck findings
-documented in `docs/CLEANUP-BASELINE.md`. Those will be fixed in a dedicated
-cleanup pass. No violations were introduced by M2.
+This is the only acceptable state for merge.  Any failure on a check not in
+`docs/CLEANUP-BASELINE.md` is a regression and must be fixed before merge.
 
-**M3 update:** `pnpm run check` is now **fully green**. All pre-existing lint
-violations have been fixed (2 ESLint errors, 7 shellcheck findings). The
-`verify:generated` check is now a real implementation (was a stub in M2).
+> **History:** In M1 the contract was transitional and allowed pre-existing
+> failures recorded in the baseline.  M2 fixed `verify:docs`.  M3 fixed
+> `lint` and promoted `verify:generated` from stub to real implementation.
+> M4 added abstractions without regressions.  M5 added CI and finalized docs.
+> The baseline is now closed out — see `docs/CLEANUP-BASELINE.md`.
 
 ## pnpm workspace policy (updated in M3)
 
@@ -210,12 +217,10 @@ config or generator is broken.
 
 ## How to interpret the baseline report
 
-See `docs/CLEANUP-BASELINE.md` for the full as-is capture.  When a CI run
-fails on a check, compare the output against the baseline:
-
-- If the failure matches a baseline entry → it is a known pre-existing issue.
-- If the failure does not appear in the baseline → it is a regression
-  introduced by recent changes and must be fixed before merge.
+See `docs/CLEANUP-BASELINE.md` for the historical as-is capture from M1.  That
+baseline is now **closed** — all pre-existing failures have been resolved.
+When a CI run fails on any check it is a regression and must be fixed before
+merge.
 
 ## How variants are generated (M3)
 
@@ -321,9 +326,114 @@ This replaces the previous non-unique `name` fields (`atlassian-skill-scripts`,
 `web-automation-scripts`).  These packages are private and are never published.
 See `CHANGELOG.md` for the full rename list.
 
+## Adding a new agent variant
+
+To add support for a brand-new agent (e.g. `mynewagent`) across all skills:
+
+1. **Create canonical source files** for every skill:
+
+   ```bash
+   mkdir -p skills/<skill>/_source/mynewagent
+   # Add SKILL.md (copy and adapt from an existing agent variant)
+   ```
+
+2. **Update the generator** (`scripts/generate-skills.mjs`):
+   - Add `"mynewagent"` to the `AGENTS` array (or the per-skill agent list).
+   - Ensure any agent-specific substitution logic is handled.
+
+3. **Regenerate all variants:**
+
+   ```bash
+   pnpm run sync:pi
+   pnpm run verify:generated     # must exit 0
+   ```
+
+4. **Update the workspace** (`pnpm-workspace.yaml`):
+   - Add entries for every `skills/<skill>/mynewagent/scripts` package that
+     has a `package.json` (e.g. atlassian and web-automation).
+
+5. **Update documentation:**
+   - Add a row to the skills table in `README.md`.
+   - Add a row to the reviewer matrix in `docs/REVIEWERS.md` if the agent
+     exposes a reviewer CLI.
+   - Add an install guide at `docs/MYNEWAGENT.md` and link it from
+     `docs/README.md`.
+   - Add the doc file to the `files` list in root `package.json`.
+
+6. **Verify the full suite:**
+
+   ```bash
+   pnpm install
+   pnpm run check
+   ```
+
+## Adding a new skill
+
+To add an entirely new skill (e.g. `my-skill`):
+
+1. **Create the canonical source tree:**
+
+   ```bash
+   mkdir -p skills/my-skill/_source/{claude-code,codex,cursor,opencode,pi}
+   # Add SKILL.md to each _source/<agent>/ directory
+   ```
+
+2. **Update the generator** (`scripts/generate-skills.mjs`):
+   - Add `"my-skill"` to the `SKILLS` array.
+   - Provide a `getSkillMeta(skill)` entry with agents list, source resolver,
+     and any extra files to copy (templates, scripts, etc.).
+
+3. **Regenerate:**
+
+   ```bash
+   pnpm run sync:pi
+   pnpm run verify:generated
+   ```
+
+4. **Add the pi-package entry** if the skill should be distributed via the
+   Pi package:
+   - Update `package.json` → `pi.skills` with the new path.
+   - Update the `files` array to include the new skill directory.
+
+5. **Write documentation** in `docs/MY-SKILL.md` and link from `docs/README.md`
+   and the skills table in `README.md`.
+
+6. **Run the full suite:** `pnpm run check`.
+
+## CI
+
+Two GitHub Actions workflows live in `.github/workflows/`:
+
+| File | Trigger | Purpose |
+|------|---------|---------|
+| `check.yml` | push, pull_request (all branches) | Full `pnpm run check` on `ubuntu-latest` **and** `macos-latest`. Offline link-checking (no network dependency). |
+| `check-online.yml` | weekly schedule (Mon 09:00 UTC) + `workflow_dispatch` | `pnpm run verify:docs:online` with full external link checking. |
+
+### What the `check` workflow does
+
+1. Checks out the repository.
+2. Installs `shellcheck` via `apt-get` (Ubuntu) or `brew` (macOS).
+3. Installs `ripgrep` via `apt-get` (Ubuntu only; pre-installed on macOS runners).
+4. Installs Node.js 22 via `actions/setup-node`.
+5. Installs pnpm 10 via `pnpm/action-setup`.
+6. Runs `pnpm install --frozen-lockfile`.
+7. Runs `pnpm run check` (the same command contributors run locally).
+
+The matrix runs both `ubuntu-latest` and `macos-latest` to guard against
+platform-specific regressions. Because M2 made all shell scripts portable
+across BSD and GNU coreutils, both runners should stay green.
+
+### Adding new prerequisites to CI
+
+If a new tool is required (e.g. a new binary called by a verify script),
+add the install step to **both** OS branches in `check.yml`. Document the
+new prerequisite in the Prerequisites table at the top of this file.
+
 ## Links
 
 - [CLEANUP-BASELINE.md](./CLEANUP-BASELINE.md) — as-is quality baseline
 - [README.md](../README.md) — project overview
 - [docs/README.md](./README.md) — documentation index
 - [CHANGELOG.md](../CHANGELOG.md) — milestone-by-milestone change record
+- [.github/workflows/check.yml](../.github/workflows/check.yml) — CI workflow
+- [.github/workflows/check-online.yml](../.github/workflows/check-online.yml) — weekly online link check