diff --git a/.github/workflows/check-online.yml b/.github/workflows/check-online.yml new file mode 100644 index 0000000..3a16286 --- /dev/null +++ b/.github/workflows/check-online.yml @@ -0,0 +1,42 @@ +name: check-online + +# Runs full external link checking on a schedule and on manual trigger. +# Kept separate from the main `check` workflow so everyday push/PR CI +# is not slowed down or broken by transient network issues. + +on: + schedule: + # Every Monday at 09:00 UTC + - cron: "0 9 * * 1" + workflow_dispatch: + +jobs: + check-online: + name: check-online (ubuntu-latest) + runs-on: ubuntu-latest + + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Install shellcheck + run: sudo apt-get update -q && sudo apt-get install -y -q shellcheck + + - name: Install ripgrep + run: sudo apt-get install -y -q ripgrep + + - name: Install Node.js + uses: actions/setup-node@v4 + with: + node-version: "22" + + - name: Install pnpm + uses: pnpm/action-setup@v4 + with: + version: "10" + + - name: Install dependencies + run: pnpm install --frozen-lockfile + + - name: Run full quality suite with external link checking + run: pnpm run verify:docs:online diff --git a/.github/workflows/check.yml b/.github/workflows/check.yml new file mode 100644 index 0000000..62d8162 --- /dev/null +++ b/.github/workflows/check.yml @@ -0,0 +1,48 @@ +name: check + +on: + push: + branches: ["**"] + pull_request: + branches: ["**"] + +jobs: + check: + name: check (${{ matrix.os }}) + runs-on: ${{ matrix.os }} + strategy: + fail-fast: false + matrix: + os: [ubuntu-latest, macos-latest] + + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Install shellcheck (Ubuntu) + if: runner.os == 'Linux' + run: sudo apt-get update -q && sudo apt-get install -y -q shellcheck + + - name: Install shellcheck (macOS) + if: runner.os == 'macOS' + run: brew install shellcheck + + - name: Install ripgrep (Ubuntu) + if: runner.os == 'Linux' + run: sudo apt-get install -y -q ripgrep + + - name: Install Node.js + uses: actions/setup-node@v4 + with: + node-version: "22" + + - name: Install pnpm + uses: pnpm/action-setup@v4 + with: + version: "10" + + - name: Install dependencies + run: pnpm install --frozen-lockfile + + - name: Run full quality suite (offline link-checking) + run: pnpm run check diff --git a/CHANGELOG.md b/CHANGELOG.md index 331dad9..bafe987 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,83 @@ Entries are milestone-scoped; stories within each milestone are listed for trace --- +## M5 — Final hardening, CI surface, and documentation closeout + +### What changed in M5 + +**S-501 — CI workflow added** + +`.github/workflows/check.yml` runs on every push and pull request against a +matrix of `ubuntu-latest` and `macos-latest`. Each job: + +1. Installs `shellcheck` (apt on Ubuntu, brew on macOS). +2. Installs `ripgrep` (apt on Ubuntu; pre-installed on macOS runners). +3. Installs Node.js 22 and pnpm 10. +4. Runs `pnpm install --frozen-lockfile`. +5. Runs `pnpm run check` (full quality suite, offline link-checking). + +`.github/workflows/check-online.yml` runs `verify:docs:online` on a weekly +schedule (Monday 09:00 UTC) and on manual `workflow_dispatch`. This keeps +external link checking out of the push/PR critical path. + +**S-502 — Root README contributing section** + +`README.md` now includes a "Contributing / Development" section that names +`pnpm run check` as the single quality gate, lists prerequisites, and links +to `docs/DEVELOPMENT.md`. + +**S-503 — `docs/DEVELOPMENT.md` finalised** + +Added: + +- **"Adding a new agent variant"** recipe (6 steps from canonical source to CI). +- **"Adding a new skill"** recipe (6 steps). +- **"CI"** section describing both workflows and how to add new prerequisites. +- **Permanent `check` contract** replacing the transitional M1 wording. +- Cross-reference links to `.github/workflows/check.yml` and + `.github/workflows/check-online.yml`. + +**S-504 — Baseline report closed** + +`docs/CLEANUP-BASELINE.md` updated with a "Final state" section showing every +baseline failure resolved, a baseline status summary table, and the +post-M5 `pnpm run check` output. The document is now closed. + +**S-505 — `package.json` file list synced** + +`docs/DEVELOPMENT.md` and `docs/REVIEWERS.md` added to the `files` array. +All listed entries verified to exist in the post-M5 tree. + +**S-506 — Changelog extended (this entry)** + +**S-507 — Final green run confirmed** + +`pnpm run check` exits 0 on macOS 15 (arm64) with Node 22.14.0 and +pnpm 10.18.1. CI workflow exercises the same gate on both `ubuntu-latest` +and `macos-latest`. + +### `pnpm run check` status after M5 + +```text +PASS lint +PASS typecheck +PASS test +PASS verify:pi +PASS verify:reviewers +PASS verify:docs +PASS verify:generated +``` + +All checks green. CI enforces this on every push and PR. + +--- + +## M4 — Shared-abstraction extraction and dead-code removal + +*See `docs/CLEANUP-BASELINE.md` § "Post-M4 state" for the full M4 delta.* + +--- + ## M3 — Shared-source generator for agent variants ### Package metadata change ⚠️ diff --git a/README.md b/README.md index 0851b5a..dfe2ac2 100644 --- a/README.md +++ b/README.md @@ -169,3 +169,20 @@ Additional pi-specific guidance lives in [docs/PI.md](docs/PI.md). For development prerequisites, quality tooling, and the `pnpm run check` contract, see [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md). + +## Contributing / Development + +See **[docs/DEVELOPMENT.md](docs/DEVELOPMENT.md)** for the full development guide. + +Quick reference — the single quality gate every contributor must pass: + +```bash +pnpm install +pnpm run check # lint · typecheck · test · verify:pi · verify:reviewers · verify:docs · verify:generated +``` + +Prerequisites: Node.js 20+, pnpm 10+, `shellcheck` (brew / apt), `ripgrep` (brew / apt). + +CI runs the same `pnpm run check` command on both `ubuntu-latest` and `macos-latest` +(see `.github/workflows/check.yml`). External link checking runs separately on a +weekly schedule (`.github/workflows/check-online.yml`). diff --git a/docs/CLEANUP-BASELINE.md b/docs/CLEANUP-BASELINE.md index 6acd050..22dac99 100644 --- a/docs/CLEANUP-BASELINE.md +++ b/docs/CLEANUP-BASELINE.md @@ -3,10 +3,9 @@ Captured: 2026-05-03 · Platform: macOS (arm64, Apple Silicon) · Node 22.14.0 · pnpm 10.18.1 This document records the as-is state of every quality check at the start of -the refactor series. The transitional `pnpm run check` contract allows the -aggregate check to exit non-zero **only** on issues listed here. Any failure -not covered by this document represents a regression introduced by a later -milestone. +the refactor series. All pre-existing failures listed here have since been +resolved. As of M5 `pnpm run check` exits **0** on a clean checkout. Any +failure now represents a regression and must be fixed before merge. --- @@ -471,3 +470,89 @@ Overall exit: **0** — all checks green (no regressions from M3). | `pnpm run test:installer` (root scripts) | 80 | | `atlassian/shared/scripts` | 29 | | **Total** | **109** | + +--- + +## Final state (post-M5) — CLOSED + +Captured: 2026-05-03 · Platform: macOS 15 (arm64) · Node 22.14.0 · pnpm 10.18.1 + +M5 added CI configuration, finalised documentation, closed out this baseline +report, and locked in a permanently green `pnpm run check` gate. No +pre-existing failures remain open. + +### `pnpm run check` aggregate (post-M5 — macOS) + +```text +PASS lint +PASS typecheck +PASS test +PASS verify:pi +PASS verify:reviewers +PASS verify:docs +PASS verify:generated + +All checks passed. +``` + +Overall exit: **0** — all checks green (no regressions from M4). + +### What changed in M5 + +- **S-501** — `.github/workflows/check.yml` added: matrix over `ubuntu-latest` + and `macos-latest`; installs `shellcheck` (apt/brew), `ripgrep` (apt), pnpm, + and Node.js 22; runs `pnpm run check`. +- **S-501** — `.github/workflows/check-online.yml` added: weekly schedule + + `workflow_dispatch`; runs `verify:docs:online` for full external link checking. +- **S-502** — Root `README.md` gained a "Contributing / Development" section + naming `pnpm run check` as the single quality gate and linking to + `docs/DEVELOPMENT.md`. +- **S-503** — `docs/DEVELOPMENT.md` finalised: added "Adding a new agent", + "Adding a new skill", and "CI" sections; transitional contract replaced by + the permanent M5 contract; baseline links updated. +- **S-504** — This file (`docs/CLEANUP-BASELINE.md`) closed out with the + "Final state" section. +- **S-505** — Root `package.json` `files` list updated: `docs/DEVELOPMENT.md` + and `docs/REVIEWERS.md` added. +- **S-506** — `CHANGELOG.md` extended with the M5 consolidated entry. +- **S-507** — Final `pnpm run check` run confirmed green (output above). + +### Baseline status summary + +Every pre-existing failure recorded in this document is now **resolved**. +No waivers are required. + +| Check | M1 status | Final status | Resolution | +|-------|-----------|--------------|------------| +| `lint` (ESLint) | FAIL — 2 errors | **PASS** | Fixed in M3 (S-302) | +| `lint` (shellcheck) | FAIL — 7 findings | **PASS** | Fixed in M3 (S-302) | +| `typecheck` | PASS | **PASS** | Never regressed | +| `test` | PASS | **PASS** | Never regressed | +| `verify:pi` | PASS | **PASS** | Portability hardened in M2 | +| `verify:reviewers` | PASS | **PASS** | Never regressed | +| `verify:docs` (markdownlint) | FAIL — 1160 errors | **PASS** | Fixed in M2 | +| `verify:docs` (link-check) | PASS | **PASS** | Never regressed | +| `verify:generated` | PASS (stub) | **PASS** | Real implementation in M3 | + +### Ubuntu smoke test + +The CI workflow (`.github/workflows/check.yml`) runs the same `pnpm run check` +command on `ubuntu-latest`. This replaces the Docker one-liner that was the +only documented Ubuntu smoke test path in M1–M4. + +For local reproduction on Linux: + +```bash +# Requires Docker +docker run --rm \ + -v "$PWD:/w" \ + -w /w \ + node:22-bookworm \ + bash -lc 'apt-get update -q && apt-get install -y -q shellcheck ripgrep python3 \ + && corepack enable \ + && pnpm install --frozen-lockfile \ + && pnpm run check' +``` + +*This baseline report is now closed. Future regressions must be caught by CI +and fixed before merge; they should NOT reopen this document.* diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md index 70119b7..791c083 100644 --- a/docs/DEVELOPMENT.md +++ b/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//_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//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// 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 diff --git a/package.json b/package.json index 6389ef0..5efe794 100644 --- a/package.json +++ b/package.json @@ -27,6 +27,8 @@ "docs/PI-SUPERPOWERS.md", "docs/PI-COMMON-REVIEWER.md", "docs/WEB-AUTOMATION.md", + "docs/DEVELOPMENT.md", + "docs/REVIEWERS.md", "pi-package/skills", "skills/reviewer-runtime/pi", "scripts/install-pi-package.sh",