kv0906kv0906/pm-kit/AGENTS.md

pm-kit

AGENTS.md138 starsChanged 7 months agoMITView on GitHub

Audience: PM-Kit users/operators. Key paths: - Framework docs: README.md, CLAUDE.md, START_HERE.md, CHANGELOG.md - Runtime/config: _core/ (including _core/config.yaml) - Reusable templates: _templates/ - Agent assets: .claude/ (agents/, skills/, rules/, hooks/) - Distribution metadata: .claude-plugin/plugin.json - Automation scripts: scripts/setup.sh, scripts/update.sh - Reference material: handbook/, examples/

We split this AGENTS.md into the rules it gives an agent

13 rules. About 0 are common, 6 are distinctive, and 7 are very specific to this project.

≈0
Common · estimate
Many files like this have a rule of this kind.
≈6
Distinctive · estimate
This author's own choices. Worth a look.
7
Very specific
Tied to their project's names, files or tools. Probably skip.

Common
Distinctive
Very specific

Very specific:
Use rg/rg --files for fast discovery instead of manual folder scanning.
line 18
Very specific:
Use ./scripts/setup.sh after cloning to initialize or validate a local PM-Kit vault.
line 19
Distinctive:
Before changing automation, read the script you are touching end-to-end and keep guardrails intact.
line 20
Distinctive:
Keep edits repository-relative and avoid machine-specific absolute paths in docs and scripts.
line 21
Distinctive:
If a change affects user-facing flow, update both docs and templates in the same PR.
line 22
Distinctive:
Treat changes as incomplete until affected flows can be executed without manual patch-ups.
line 41
Distinctive:
Prefer clear Markdown with short, action-oriented sections.
line 44
Very specific:
Use heading hierarchy in order: #, ##, ###.
line 45
Very specific:
Use kebab-case filenames for new docs/scripts/templates.
line 46
Very specific:
Use conventional commit prefixes: feat:, fix:, docs:, chore:, release: (optional scope allowed, e.g.
line 50
Very specific:
Ensure ## Changelog Entry is completed in the PR template.
line 52
Distinctive:
Run relevant local checks before opening/merging a PR.
line 58
Very specific:
Use handbook/maintainer-runbook.md for maintainer flow.
line 62

≈ “Common” is an estimate: at least 1 in 5 of the 36,368 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.

Files

AGENTS.md

Audience: PM-Kit users/operators.

Project snapshot

PM-Kit is a markdown-first workspace template. Most work is in docs, templates, and shell scripts rather than compiled code.

Key paths:

Framework docs: README.md, CLAUDE.md, START_HERE.md, CHANGELOG.md
Runtime/config: _core/ (including _core/config.yaml)
Reusable templates: _templates/
Agent assets: .claude/ (agents/, skills/, rules/, hooks/)
Distribution metadata: .claude-plugin/plugin.json
Automation scripts: scripts/setup.sh, scripts/update.sh
Reference material: handbook/, examples/

Dev environment tips

Use rg/rg --files for fast discovery instead of manual folder scanning.
Use ./scripts/setup.sh after cloning to initialize or validate a local PM-Kit vault.
Before changing automation, read the script you are touching end-to-end and keep guardrails intact.
Keep edits repository-relative and avoid machine-specific absolute paths in docs and scripts.
If a change affects user-facing flow, update both docs and templates in the same PR.

Core commands

./scripts/setup.sh: initialize or verify local PM-Kit setup.
./scripts/update.sh --check: detect whether upstream framework updates are available.
./scripts/update.sh --dry-run: preview update effects without mutating files.
./scripts/update.sh: apply framework updates.
git status && git diff: required local sanity check before commit/PR.

Testing instructions

Inspect CI definitions in .github/workflows/ before significant changes.
Primary CI checks include:
- PR Changelog Check (.github/workflows/pr-changelog-check.yml)
- PR Auto Labeler (.github/workflows/pr-labeler.yml)
- Changelog On Merge (.github/workflows/changelog-on-merge.yml)
For script changes, test both:
- happy path
- guardrails (dirty git tree, missing prerequisites, invalid inputs)
For docs/template changes, verify command examples and paths still resolve.
Treat changes as incomplete until affected flows can be executed without manual patch-ups.

Style and naming rules

Prefer clear Markdown with short, action-oriented sections.
Use heading hierarchy in order: #, ##, ###.
Use kebab-case filenames for new docs/scripts/templates.
For new shell scripts, use bash and set -euo pipefail.

PR instructions

Use conventional commit prefixes: feat:, fix:, docs:, chore:, release: (optional scope allowed, e.g. fix(update): ...).
Use .github/PULL_REQUEST_TEMPLATE.md.
Ensure ## Changelog Entry is completed in the PR template.
Include:
- what changed
- why it changed
- manual test evidence
- screenshots/examples for workflow UX changes
Run relevant local checks before opening/merging a PR.

Maintainer-only operations

Release, tagging, and branch-protection workflow are intentionally separated from this core guide. Use handbook/maintainer-runbook.md for maintainer flow.

Download now (ZIP)

Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 28,693 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository41 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- .github/copilot-instructions.mdCopilot instructions
- askSkill
- blockSkill
- dailySkill
- decideSkill
- discoverSkill
- docSkill
- docxSkill
- excalidraw-generatorSkill
- explainSkill
- gwsSkill
- healthSkill
- helpSkill
- inboxSkill
- interviewSkill
- jiraSkill
- journeySkill
- json-canvasSkill
- linearSkill
- meetSkill
- mermaid-visualizerSkill
- notionSkill
- obsidian-basesSkill
- obsidian-cliSkill
- obsidian-markdownSkill
- onboardSkill
- pdfSkill
- pptxSkill
- previewSkill
- prioritizeSkill
- progressSkill
- pushSkill
- reportSkill
- show-meSkill
- skill-creatorSkill
- todaySkill
- updateSkill
- vault-opsSkill
- weeklySkill
- xlsxSkill

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

Reviews can't be read right now.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free