# 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