feat(M1): Baseline verification, quality tooling foundation, and current-state report
This commit is contained in:
Stefano Fiorini
@@ -0,0 +1,166 @@
|
||||
# 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.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
| Tool | Minimum version | Install |
|
||||
|------|----------------|---------|
|
||||
| Node.js | 20 | `fnm install 22` or `nvm install 22` |
|
||||
| pnpm | 10 | `npm install -g pnpm` |
|
||||
| `rg` (ripgrep) | any | `brew install ripgrep` / `apt-get install ripgrep` |
|
||||
| **shellcheck** | **any** | `brew install shellcheck` / `apt-get install shellcheck` |
|
||||
| `stat` (BSD or GNU) | any | pre-installed on macOS; GNU variant on Linux |
|
||||
| Python 3 | 3.8+ | pre-installed on most systems |
|
||||
|
||||
**`shellcheck` is required.** The `pnpm run lint` script will exit 2 with a
|
||||
clear error message if `shellcheck` is not on `PATH`. Every contributor must
|
||||
install it before running any quality checks.
|
||||
|
||||
## Quick start
|
||||
|
||||
```bash
|
||||
# Install dependencies (workspace-aware, no nested package.json modifications)
|
||||
pnpm install
|
||||
|
||||
# Run the full quality suite
|
||||
pnpm run check
|
||||
```
|
||||
|
||||
## Individual checks
|
||||
|
||||
| Command | What it does |
|
||||
|---------|-------------|
|
||||
| `pnpm run sync:pi` | Mirror pi skill variants into `pi-package/skills/` |
|
||||
| `pnpm run verify:pi` | Assert pi resource and workflow invariants |
|
||||
| `pnpm run verify:reviewers` | Assert reviewer-runtime skill invariants |
|
||||
| `pnpm run test:installer` | Run root-level Node.js unit tests (22 tests) |
|
||||
| `pnpm run lint` | ESLint on root scripts + shellcheck on all `.sh` files |
|
||||
| `pnpm run lint:fix` | Auto-fix ESLint + Prettier (do not run on pre-existing code until M2) |
|
||||
| `pnpm run typecheck` | TypeScript `tsc --noEmit` in workspace packages |
|
||||
| `pnpm run test` | Run all tests (root + workspace packages) |
|
||||
| `pnpm run verify:docs` | markdownlint + offline link-check |
|
||||
| `pnpm run verify:generated` | Assert generated output freshness (stub; fleshed out in M3) |
|
||||
| `pnpm run check` | Aggregate: run every gate above and report a summary |
|
||||
|
||||
## Quality tooling (added in M1)
|
||||
|
||||
### ESLint
|
||||
|
||||
Root-level flat config in `eslint.config.mjs`. Covers `scripts/**/*.mjs`
|
||||
and `scripts/**/*.js`. Uses `@eslint/js` recommended rules and Node.js
|
||||
globals. Nested workspace packages are responsible for their own ESLint
|
||||
configuration.
|
||||
|
||||
### Prettier
|
||||
|
||||
Config in `.prettierrc.json` (print-width 100, LF line endings). Ignore
|
||||
file at `.prettierignore` excludes generated agent-variant directories and
|
||||
`pnpm-lock.yaml`.
|
||||
|
||||
### markdownlint
|
||||
|
||||
Config in `.markdownlint.jsonc` (rules) and `.markdownlint-cli2.jsonc`
|
||||
(file globs and ignores). Key overrides vs defaults:
|
||||
|
||||
- `MD013` line-length relaxed to 120 chars (code blocks and tables excluded).
|
||||
- `MD033` (inline HTML) disabled.
|
||||
- `MD034` (bare URLs) disabled.
|
||||
- `MD041` (first-line heading) disabled.
|
||||
- `MD060` (table column style) disabled.
|
||||
|
||||
Run `pnpm run verify:docs` to lint all `README.md`, `docs/*.md`, and
|
||||
`skills/**/SKILL.md` files (node\_modules excluded automatically).
|
||||
|
||||
### markdown-link-check
|
||||
|
||||
Two configs:
|
||||
|
||||
- `markdown-link-check.json` — **offline** mode (default): ignores all
|
||||
`http://` and `https://` links. Safe for local dev and CI.
|
||||
- `markdown-link-check.online.json` — **online** mode: checks external links
|
||||
with a 10 s timeout, 2 retries, and retry-on-429. Use `--online` flag on
|
||||
`scripts/lib/run-link-check.mjs`.
|
||||
|
||||
`pnpm run verify:docs` uses the offline config by default.
|
||||
|
||||
### shellcheck
|
||||
|
||||
Wrapper script at `scripts/lib/run-shellcheck.mjs`. Discovers every `*.sh`
|
||||
file under `scripts/` and `skills/` (excluding node\_modules and generated
|
||||
agent-variant directories) and runs shellcheck on each.
|
||||
|
||||
**Installation:**
|
||||
|
||||
- macOS: `brew install shellcheck`
|
||||
- Debian/Ubuntu: `sudo apt-get install shellcheck`
|
||||
- Other: <https://github.com/koalaman/shellcheck#installing>
|
||||
|
||||
The wrapper exits with code **2** (not 1) when shellcheck is missing, so CI
|
||||
can distinguish "shellcheck absent" from "shellcheck found violations".
|
||||
|
||||
## Transitional `check` contract (M1)
|
||||
|
||||
`pnpm run check` may exit non-zero in M1. This is expected. The contract is:
|
||||
|
||||
> `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.
|
||||
|
||||
The current baseline failures are:
|
||||
|
||||
1. `lint` — 2 ESLint violations in existing root scripts; 7 shellcheck
|
||||
findings in existing `.sh` files.
|
||||
2. `verify:docs` — 1160 markdownlint violations in pre-existing docs and
|
||||
`SKILL.md` files.
|
||||
|
||||
All other checks (`typecheck`, `test`, `verify:pi`, `verify:reviewers`,
|
||||
`verify:generated`) pass with EXIT 0.
|
||||
|
||||
Once later milestones fix the baseline violations, `pnpm run check` will
|
||||
reach EXIT 0 and the transitional contract expires.
|
||||
|
||||
## pnpm workspace policy (M1 exclusion-only)
|
||||
|
||||
The `pnpm-workspace.yaml` at the repo root implements the **non-mutating,
|
||||
exclusion-only** policy for M1:
|
||||
|
||||
**Included** (canonical source packages):
|
||||
|
||||
- `skills/atlassian/shared/scripts` — shared Atlassian runtime source
|
||||
- `skills/web-automation/codex/scripts` — provisional canonical copy; M3
|
||||
will rename and/or consolidate
|
||||
|
||||
**Excluded** (generated agent-variant directories):
|
||||
|
||||
- `skills/atlassian/{codex,claude-code,cursor,opencode,pi}/scripts`
|
||||
- `skills/web-automation/{claude-code,cursor,opencode,pi}/scripts`
|
||||
- `pi-package/**`
|
||||
|
||||
**Why exclusion-only in M1?**
|
||||
|
||||
The generated agent-variant directories contain `package.json` files with the
|
||||
same `name` field as the canonical source. Including them in the workspace
|
||||
would cause pnpm to complain about duplicate package names. Renaming them to
|
||||
unique names (e.g. `atlassian-skill-scripts-codex`) requires a generator-driven
|
||||
update that touches every generated file — this is deferred to **M3** to keep
|
||||
M1 byte-identical for those files.
|
||||
|
||||
After `pnpm install`, `git status` should show zero modifications to any file
|
||||
under the excluded directories. If it does not, the workspace config 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.
|
||||
|
||||
## Links
|
||||
|
||||
- [CLEANUP-BASELINE.md](./CLEANUP-BASELINE.md) — as-is quality baseline
|
||||
- [README.md](../README.md) — project overview
|
||||
- [docs/README.md](./README.md) — documentation index
|
||||
Reference in New Issue
Block a user