Files

T

Stefano Fiorini be993429c1 feat(M2): Documentation flow, accuracy, consistency cleanup, and cross-platform shell portability

2026-05-03 20:14:44 -05:00

8.2 KiB

Raw Blame History

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

# 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 + docs-flow verifier
`pnpm run verify:docs:online`	Same as `verify:docs` but with full external link checking
`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".

Cross-platform shell support (M2)

All shell scripts under scripts/ and skills/reviewer-runtime/ that are exercised by verify:pi, verify:reviewers, sync:pi, and test:installer must work on both macOS (BSD userland) and Ubuntu/Debian (GNU userland) without modification.

BSD vs GNU differences encountered

Feature	macOS (BSD)	Linux (GNU)	Portable form
`stat` permissions	`stat -f '%Lp' <path>`	`stat -c '%a' <path>`	`portable_stat_perms` helper
herestrings (`<<<`)	supported (bash)	supported (bash)	OK (scripts use `#!/usr/bin/env bash`)
`find -E` (extended regex)	macOS-only	not available	use `grep` or POSIX `-name`
`sed -i ''`	macOS form	use `sed -i` on Linux	detect or avoid in-place sed
`date -j` (date arithmetic)	macOS-only	use `date -d` on Linux	Node helper or `date +%s`
`readlink -f`	not on macOS by default	GNU standard	`realpath` or `cd && pwd`

`scripts/lib/portable.sh`

A shared helper that abstracts the two known BSD/GNU divergences hit in this repo:

# Source from any script that needs portable stat
# shellcheck source=lib/portable.sh
source "$(dirname "${BASH_SOURCE[0]}")/lib/portable.sh"

# Returns octal permission string: e.g. "755"
portable_stat_perms "$path"

The shellcheck wrapper passes -x --source-path=SCRIPTDIR so source directives resolve relative to the script file, not the working directory.

How to run the Ubuntu smoke test locally

# Requires Docker
docker run --rm \
  -v "$PWD:/w" \
  -w /w \
  node:20-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 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)

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.

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.

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.

8.2 KiB Raw Blame History