| 1 | # Plan 005: Add a contributor `AGENTS.md` |
| 2 | |
| 3 | > **Executor instructions**: Follow this plan step by step. If anything in |
| 4 | > "STOP conditions" occurs, stop and report. When done, update the status row |
| 5 | > in `plans/README.md`. |
| 6 | > |
| 7 | > **Drift check (run first)**: `git diff --stat c63cb120..HEAD -- AGENTS.md CONTRIBUTING.md package.json scripts/publish.mjs` |
| 8 | > On a mismatch with the excerpts below, treat it as a STOP condition. |
| 9 | |
| 10 | ## Status |
| 11 | |
| 12 | - **Priority**: P3 |
| 13 | - **Effort**: S |
| 14 | - **Risk**: LOW |
| 15 | - **Depends on**: none (references 003's `verify` script if it exists) |
| 16 | - **Category**: dx / docs |
| 17 | - **Planned at**: commit `c63cb120`, 2026-07-10 |
| 18 | |
| 19 | ## Why this matters |
| 20 | |
| 21 | This repo *ships* agent tooling to its users (`.claude-plugin/`, `skills/slidev/`) |
| 22 | but has **no** `AGENTS.md`/`CLAUDE.md` for agents or newcomers working *in* the |
| 23 | repo. Several conventions are non-obvious and easy to get wrong: tests need a |
| 24 | prior build, dependencies are pinned through pnpm **catalogs** (not raw versions), |
| 25 | and `skills/` is **generated** (must not be hand-edited) and is copied into the |
| 26 | published package. A short `AGENTS.md` captures the executable ground rules. |
| 27 | |
| 28 | ## Current state |
| 29 | |
| 30 | - No `AGENTS.md` or `CLAUDE.md` exists anywhere (glob returns none). |
| 31 | - Monorepo layout (from `CONTRIBUTING.md:76-84`): |
| 32 | ``` |
| 33 | packages/slidev/ - Node.js side (CLI, Vite plugins) |
| 34 | packages/client/ - frontend Vue app (shipped as source) |
| 35 | packages/parser/ - Slidev extended-Markdown parser |
| 36 | packages/create-app/, create-theme/ - scaffolding |
| 37 | packages/vscode/ - VSCode extension |
| 38 | packages/types/ - shared types |
| 39 | ``` |
| 40 | - Scripts (`package.json:9-28`): `build`, `dev`, `lint`, `typecheck`, `test`, |
| 41 | `docs`. Tests require a prior build. |
| 42 | - Dependency management: pnpm catalogs in `pnpm-workspace.yaml` (`catalog:prod`, |
| 43 | `catalog:dev`, `catalog:frontend`, etc.) — deps reference catalog keys, not |
| 44 | literal versions. |
| 45 | - `skills/` is generated: `skills/GENERATION.md` documents the process, and |
| 46 | `scripts/publish.mjs:4` copies `skills` into `packages/slidev/skills` at publish |
| 47 | time (so it ships in `@slidev/cli`). It must be regenerated from `docs/`, not |
| 48 | edited by hand. |
| 49 | |
| 50 | ## Commands you will need |
| 51 | |
| 52 | | Purpose | Command | Expected | |
| 53 | |---------|---------|----------| |
| 54 | | Lint (markdown is ignored, but run anyway) | `pnpm lint` | exit 0 | |
| 55 | |
| 56 | (No build/test required — this plan adds one Markdown file.) |
| 57 | |
| 58 | ## Scope |
| 59 | |
| 60 | **In scope**: |
| 61 | - `AGENTS.md` (create, repo root) |
| 62 | |
| 63 | **Out of scope**: |
| 64 | - `CONTRIBUTING.md` (leave as the human-facing doc; `AGENTS.md` complements it). |
| 65 | - Any config that would make tools *load* AGENTS.md differently. |
| 66 | - Generating/editing `skills/` content. |
| 67 | |
| 68 | ## Git workflow |
| 69 | |
| 70 | - Branch: `docs/agents-md`. |
| 71 | - Conventional commit: `docs: add AGENTS.md for contributors`. |
| 72 | - Do NOT push/PR unless instructed. |
| 73 | |
| 74 | ## Steps |
| 75 | |
| 76 | ### Step 1: Write `AGENTS.md` |
| 77 | |
| 78 | Create `AGENTS.md` at the repo root with these sections (keep it under ~60 lines, |
| 79 | factual, matching the current state above): |
| 80 | |
| 81 | - **Project map** — the package table from Current state, one line each. |
| 82 | - **Build & verify** — `pnpm install`, then `pnpm build` **before** `pnpm test` |
| 83 | (tests resolve workspace packages to `dist/`). If plan 003 landed, point at |
| 84 | `pnpm verify`. List `pnpm typecheck` (`vue-tsc --noEmit`) and `pnpm lint` |
| 85 | (`eslint . --cache`). |
| 86 | - **Dependencies** — versions are managed via pnpm **catalogs** in |
| 87 | `pnpm-workspace.yaml`; reference a catalog key (`catalog:prod`, etc.), don't |
| 88 | hardcode versions; `taze` manages bumps. |
| 89 | - **Generated content — do not hand-edit** — `skills/slidev/**` is generated |
| 90 | from `docs/` (see `skills/GENERATION.md`) and copied into the published |
| 91 | package by `scripts/publish.mjs`; regenerate via the documented process. |
| 92 | Also note `docs/components.d.ts` and other generated artifacts if present. |
| 93 | - **Conventions** — Conventional Commits for messages and PR titles; code style |
| 94 | is enforced by ESLint via a pre-commit hook (`simple-git-hooks` + |
| 95 | `lint-staged`), so no manual formatting needed. |
| 96 | - **Releases** — never release autonomously; version bumps/tags are |
| 97 | human-approved (`pnpm release` is maintainer-run). |
| 98 | |
| 99 | **Verify**: `test -f AGENTS.md && wc -l AGENTS.md` prints a line count > 0. |
| 100 | |
| 101 | ## Test plan |
| 102 | |
| 103 | - No tests. This is documentation. Verify it is internally consistent with |
| 104 | `package.json` scripts and `CONTRIBUTING.md` by re-reading both. |
| 105 | |
| 106 | ## Done criteria |
| 107 | |
| 108 | - [ ] `AGENTS.md` exists at repo root and covers: project map, build/verify (build-before-test), catalogs, generated `skills/`, conventions, releases |
| 109 | - [ ] Every command it names matches a real script in `package.json` |
| 110 | - [ ] `pnpm lint` exits 0 |
| 111 | - [ ] Only `AGENTS.md` added (`git status`) |
| 112 | - [ ] `plans/README.md` status row updated |
| 113 | |
| 114 | ## STOP conditions |
| 115 | |
| 116 | Stop and report if: |
| 117 | |
| 118 | - `package.json` scripts differ from the excerpts (document what actually exists, |
| 119 | and report the drift). |
| 120 | |
| 121 | ## Maintenance notes |
| 122 | |
| 123 | - Keep the command list in sync with `package.json` scripts. |
| 124 | - If a `CLAUDE.md`/tool-specific file is also wanted, symlink or re-export from |
| 125 | `AGENTS.md` rather than duplicating. |
| 126 |