ai-coding-skills/docs/DEVELOPMENT.md

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
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 — as-is quality baseline
• README.md — project overview
• docs/README.md — documentation index