AGENTS.md ยท diff
git:20261027.2ff3d55 to git:20261027.d8fa524
23 added, 15 removed. Audit A to A.
# 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 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 |
- | `.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.
+ - 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
- 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.
+ Versions come from conventional commits since the last tag:
- `.changeset/` is required: `config.json` and the pending changeset files feed
- the Version Packages PR. Without them there is no automatic version or
- changelog.
+ - `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.
- 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.
+ 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.
- 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.
+ 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 changesets.
+ - `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.