feat(M5): Final hardening, CI surface, and documentation closeout
This commit is contained in:
Stefano Fiorini
@@ -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.*
|
||||
|
||||
+130
-20
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user