Home/ai-coding-skills
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(M1): Baseline verification, quality tooling foundation, and current-state report

Browse Source
This commit is contained in:
Stefano Fiorini
2026-05-03 19:26:55 -05:00
parent 2deab1c1b4
commit 0443381aa0
19 changed files with 4100 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/CLEANUP-BASELINE.md
+292
View File
@@ -0,0 +1,292 @@
# Cleanup Baseline — ai-coding-skills (M1)
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.
---
## Byte-equivalence assertion
Before any file was modified in M1, `git status` showed a clean working tree.
After all S-101 through S-107 changes were applied, `git status` confirms:
- **Zero** modifications to any nested `package.json` under `skills/` or `pi-package/`.
- **Zero** modifications to any file under `skills/*/{codex,claude-code,cursor,opencode,pi}/`
(the generated agent-variant directories).
- All changes are confined to new root-level config files, new scripts, updated
root `package.json` (devDependencies + scripts), and new docs.
---
## 1. Pre-existing root scripts
### `pnpm run sync:pi`
```text
Synced pi package skill mirror into …/pi-package/skills.
EXIT: 0
```
### `pnpm run verify:pi`
```text
package metadata ok
pi resources verified
pi workflow skill docs verified
EXIT: 0
```
### `pnpm run verify:reviewers`
```text
reviewer support verified
EXIT: 0
```
### `pnpm run test:installer`
```text
TAP version 13
# tests 22
# pass 22
# fail 0
EXIT: 0
```
---
## 2. Nested package scripts
### atlassian/shared/scripts — `test`
```text
TAP version 13
# tests 23
# pass 23
# fail 0
EXIT: 0
```
### atlassian/shared/scripts — `typecheck`
```text
EXIT: 0
```
### atlassian/codex/scripts — `typecheck`
```text
EXIT: 0
```
### atlassian/claude-code/scripts — `typecheck`
```text
EXIT: 0
```
### atlassian/cursor/scripts — `typecheck`
```text
EXIT: 0
```
### atlassian/opencode/scripts — `typecheck`
```text
EXIT: 0
```
### atlassian/pi/scripts — `typecheck`
```text
EXIT: 0
```
### web-automation/codex/scripts — `typecheck`
```text
EXIT: 0
```
### web-automation/codex/scripts — `lint`
```text
EXIT: 0
```
### web-automation/claude-code/scripts — `typecheck`
```text
EXIT: 0
```
### web-automation/cursor/scripts — `typecheck`
```text
EXIT: 0
```
### web-automation/opencode/scripts — `typecheck`
```text
EXIT: 0
```
### web-automation/pi/scripts — `typecheck`
```text
EXIT: 0
```
---
## 3. reviewer-runtime tests
All three test scripts under `skills/reviewer-runtime/tests/` passed:
```text
claude-review-template-guard.sh PASS
smoke-test.sh PASS
telegram-notify-test.sh PASS
EXIT: 0 (each)
```
---
## 4. M1 quality tooling — baseline violations
### 4a. ESLint (`pnpm run lint` — ESLint stage)
Exit code: **1** — 2 pre-existing errors (no new errors from M1 additions).
Files with violations in the existing codebase:
| File | Line | Rule | Message |
|------|------|------|---------|
| `scripts/lib/skill-manager-core.mjs` | 282 | `no-useless-assignment` | Value assigned to `entries` is not used |
| `scripts/manage-skills.mjs` | 270 | `no-unused-vars` | `client` is assigned a value but never used |
Action: Fix in a later milestone. Do not suppress with eslint-disable comments
unless the code is intentionally dead.
### 4b. shellcheck (`pnpm run lint` — shellcheck stage)
Exit code: **1** — 7 files with pre-existing findings (no new violations from M1).
| File | Finding |
|------|---------|
| `scripts/verify-pi-resources.sh` | SC2016 (info, ×3): single-quoted backtick strings; SC2251 (info, ×1): `!` outside condition |
| `scripts/verify-pi-workflows.sh` | SC2016 (info, ×2): single-quoted backtick strings; SC2251 (info, ×1): `!` outside condition |
| `skills/reviewer-runtime/pi/run-review.sh` | SC2329 (info): unused `handle_signal`; SC2034 (warning, ×2): unused variables |
| `skills/reviewer-runtime/run-review.sh` | SC2329 (info): unused `handle_signal`; SC2034 (warning, ×2): unused variables |
| `skills/reviewer-runtime/tests/claude-review-template-guard.sh` | SC2016 (info, ×1): single-quoted expansion |
| `skills/reviewer-runtime/tests/smoke-test.sh` | SC2064 (warning, ×1): `trap` should use single quotes |
| `skills/reviewer-runtime/tests/telegram-notify-test.sh` | SC2064 (warning, ×1): `trap` should use single quotes |
The following files pass shellcheck with EXIT 0:
- `scripts/install-pi-package.sh`
- `scripts/manage-skills.sh`
- `scripts/sync-pi-package-skills.sh`
- `scripts/verify-reviewer-support.sh`
- `skills/reviewer-runtime/notify-telegram.sh`
- `skills/reviewer-runtime/pi/notify-telegram.sh`
- `skills/web-automation/scripts/sync-variants.sh`
Action: Fix `SC2064` trap issues and `SC2034` warnings in a later milestone.
SC2016 findings are intentional (single-quoted strings containing backticks are
used as literal grep patterns to match markdown text).
### 4c. markdownlint (`pnpm run verify:docs`)
Exit code: **1** — 1160 errors across 62 files (no new violations from M1 additions).
markdownlint-cli2 v0.22.1 scanned `README.md`, `docs/**/*.md`, and canonical
`SKILL.md` files (excluding node\_modules and generated agent-variant
directories).
Rule breakdown (selected):
| Rule | Description |
|------|-------------|
| MD013 | Line length > 120 chars (majority of errors) |
| MD012 | Multiple consecutive blank lines |
| MD024 | Duplicate headings |
| MD029 | Ordered list item prefix |
| MD032 | Blanks around lists |
| MD038 | Spaces inside code span |
| MD040 | Fenced code without language |
| MD058 | Blanks around tables |
Affected files include (non-exhaustive): `docs/ATLASSIAN.md`,
`docs/CREATE-PLAN.md`, `docs/DO-TASK.md`, `docs/IMPLEMENT-PLAN.md`,
`docs/INSTALLER.md`, `docs/PI-COMMON-REVIEWER.md`, `docs/PI-RESEARCH.md`,
`docs/PI-SUPERPOWERS.md`, `docs/PI.md`, `docs/README.md`,
`docs/TELEGRAM-NOTIFICATIONS.md`, `docs/WEB-AUTOMATION.md`, `README.md`,
and all `skills/*/*/SKILL.md` variants.
Action: Bulk-fix in a dedicated doc-cleanup milestone. New docs added in M1
(`docs/DEVELOPMENT.md`, `docs/CLEANUP-BASELINE.md`) pass all enabled rules.
### 4d. markdown-link-check (offline, `pnpm run verify:docs`)
Exit code: **0** — no broken repo-relative or anchor links found.
53 markdown files scanned (offline mode: external http/https links ignored).
All internal links are valid.
### 4e. `pnpm run typecheck` (workspace aggregate)
Exit code: **0**.
Ran `typecheck` in workspace members:
- `skills/atlassian/shared/scripts` — PASS
- `skills/web-automation/codex/scripts` — PASS
### 4f. `pnpm run test` (workspace aggregate)
Exit code: **0**.
Ran:
- `pnpm run test:installer` (22/22 tests)
- `skills/atlassian/shared/scripts test` (23/23 tests)
### 4g. `pnpm run check` aggregate (M1 transitional state)
```text
FAIL lint (exit 1) — ESLint + shellcheck pre-existing violations (§4a, §4b)
PASS typecheck
PASS test
PASS verify:pi
PASS verify:reviewers
FAIL verify:docs (exit 1) — markdownlint pre-existing violations (§4c)
PASS verify:generated (stub)
```
Overall exit: **1** — expected per transitional contract; all failures are
pre-existing and documented in this file.
---
## 5. Platform notes
- Tested on macOS 15 (arm64). No GNU/Linux run available at M1 capture time.
- shellcheck 0.11.0 installed via `brew install shellcheck`.
- `stat` variant: BSD stat (macOS default). The `scripts/` shell scripts do
not call `stat`; this affects only M5 CI configuration.
- `rg` (ripgrep) is required by `scripts/verify-pi-workflows.sh`. It is
present on the test machine; absent systems should install via
`brew install ripgrep` / `apt-get install ripgrep`.
---
*This file is generated once (M1) and updated only when a subsequent milestone
changes the baseline status of a check.*
docs/DEVELOPMENT.md
+166
View File
@@ -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
docs/README.md
+6
View File
@@ -27,6 +27,12 @@ This directory contains user-facing docs for each skill.
- [TELEGRAM-NOTIFICATIONS.md](./TELEGRAM-NOTIFICATIONS.md) — Shared Telegram notification setup used by reviewer-driven skills.
- [WEB-AUTOMATION.md](./WEB-AUTOMATION.md) — Includes requirements, install, dependency verification, and usage examples for web-automation.
## Development
- [DEVELOPMENT.md](./DEVELOPMENT.md) — prerequisites, `pnpm run check`, workspace policy,
and the transitional quality contract.
- [CLEANUP-BASELINE.md](./CLEANUP-BASELINE.md) — as-is quality baseline captured at M1.
## Repo Setup
Clone the repo first: