AGENTS.md git:20261027.510ceb9A

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

# 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 changeset` | record a change for the next release |
| `pnpm run version` | apply changesets locally; CI does this in the release PR |
| `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 |
| `.changeset/` | changeset configuration |

## 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.
- 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

Changesets drive versions. A feature pull request includes a changeset; on push
to `main`, the Version Packages workflow opens or updates a release pull request.

`.changeset/` is required: `config.json` and the pending changeset files feed
the Version Packages PR. Without them there is no automatic version or
changelog.

That release PR runs `pnpm run version`, which executes `changeset version` and
`sync-plugin-version`, so `package.json`, the changelog and both plugin manifests
are generated, never edited by hand.

Merge the release PR to cut the version. The tag job tags `main` with
`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 changesets.
- 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.