AGENTS.md git:20261027.d8fa524A

Immutable. This exact content never changes and is served at /api/v1/blob/b126e81018e38f19.

# Natuleadan Skills: Agent Guide

Technical guide for working in this repository. The README is the product
overview.

## Requirements

- Node.js 24 or newer, which runs TypeScript entry points directly.
- pnpm 12.
- No Python: validation, hooks and CI run on Node.

## Commands

| Command | What it does |
|---|---|
| `pnpm validate` | full validation: skills, audit, notices and scripts |
| `pnpm validate:skills` | skills, audit and script freshness |
| `pnpm industry` | audit the sixteen industry skills |
| `pnpm notices` | regenerate `ThirdPartyNotices.txt` |
| `pnpm scripts:generate` | regenerate every skill script stub |
| `pnpm scripts:check` | verify stubs and run their smoke tests |
| `pnpm md:check` | reject spaced hyphens in Markdown prose |
| `pnpm badges` | regenerate README counts |
| `pnpm badges:check` | verify counts in README |
| `pnpm skill <name>` | run `skills/<name>/scripts/main.ts` |
| `pnpm release:plan` | show the next version from commits |
| `pnpm release:prepare` | write version, manifests and changelog |
| `pnpm release:check` | verify the version matches the commits |
| `pnpm changelog:check` | verify changelog versions, sections and tags |
| `pnpm check-plugin-version` | verify plugin manifests match `package.json` |

## Project structure

| Path | Purpose |
|---|---|
| `skills/<name>/SKILL.md` | frontmatter and instructions |
| `skills/<name>/metadata.json` | version, abstract, references |
| `skills/<name>/references/` | prose notes with mermaid diagrams |
| `skills/<name>/scripts/main.ts` | generated entry point, required |
| `tools/` | validator, industry audit, notices and skill runner |
| `.claude-plugin/` | marketplace and plugin manifests |

## Development

Clone the repository and run `pnpm install`; the `prepare` script installs the
Husky hooks. Use `pnpm validate` as the single gate before pushing.

## Validation

`pnpm validate` enforces:

- Frontmatter and directory names match.
- Every declared reference exists and has a mermaid sequence diagram.
- No fenced code blocks in markdown except mermaid.
- No spaced hyphen ` - ` in Markdown prose; the only exception is the
  copyright line `2023 - Present.`.
- No `code/`, no executables and no Python.
- `scripts/` starts at `main.ts` and holds only TypeScript or ESM.
- Every skill is registered in both plugin manifests.
- License and version match across manifests.
- `ThirdPartyNotices.txt` matches the installed dependencies.
- Every skill has a generated `scripts/main.ts` and passes the smoke test.
- README badges match the skill, reference and script counts.
- The version matches the commits since the last tag.
- Changelog versions, sections and past tags are consistent.
- Industry skills stay neutral: no platform concepts, vendor names or pricing.

The `pre-commit` hook runs `pnpm validate:skills`; the `pre-push` hook and CI run
`pnpm validate`.

## Branches

`main` is the only permanent branch. Every work item goes on a short-lived
branch (`feat/...`, `fix/...`, `docs/...`) and reaches `main` through a pull
request. The branch is deleted after merge. A branch can hold one or many
commits; there is no branch per commit.

## Commits

Format: `type(scope): description`, scope in English and lower case.

- Title has 3 to 7 words, counting `type(scope):`.
- Maximum 100 characters, no trailing period.
- Blank line after the title.
- At least 3 bullets shaped `- **Label**: body`, each body with 3 to 7 words.
- Types: feat, fix, upgrade, docs, style, refactor, perf, test, chore, ci,
  revert.
- Scopes: `skills`, `tools`, `docs`, `ci`, `workflow`, `hooks`, `release`,
  `license`, `deps`. CI rejects any other scope.

Release commits (`chore(release): ...`) are exempt because the release pipeline
creates them.

## Releases

Versions come from conventional commits since the last tag:

- `fix` and `perf` bump patch.
- `feat` bumps minor.
- `upgrade` or a breaking change bumps major.
- `docs`, `ci`, `chore`, `test`, `style` and `refactor` do not release.

A functional PR includes its own version bump and changelog entry. Run
`pnpm release:prepare` before committing; it updates `package.json`, both plugin
manifests and `CHANGELOG.md`. The release check in CI fails when the bump is
missing.

The PR is the only approval. After merge, the tag job creates `v<version>` and
publishes `skills_v<version>.zip`. Version `0.0.0` means unreleased and is
skipped.

## Generated files

- `ThirdPartyNotices.txt` is generated by `pnpm notices`; never edit it by hand.
- `CHANGELOG.md` and the versions are generated by `pnpm release:prepare`.
- The plugin manifests are generated by `scripts/sync-plugin-version.mjs`.
- `skills/<name>/scripts/main.ts` is generated by `pnpm scripts:generate`; never
  edit it by hand. It is self-contained and does not read `metadata.json` at
  runtime.
- The README badges are generated by `pnpm badges`; `pnpm validate` checks them.

## Links

- [README.md](README.md): product overview.
- [SKILLS.md](SKILLS.md): complete catalog.
- [CONTRIBUTING.md](CONTRIBUTING.md): skill format and contribution rules.
- [SECURITY.md](SECURITY.md): vulnerability reporting policy.