Getting Started

pm4ai manages every repo with lintmax in deps — syncs configs, generates CLAUDE.md, enforces conventions, runs maintenance.

MUST

Read root README.md first WHEN it exists. Why: project-specific entry.
Determine role via gh auth status: owner (1qh) may edit pm4ai rules/checks directly; never hand-edit a managed file. Why: managed files are regenerated on the next fix.
Keep project-specific docs — decisions, gotchas, plans — in the project's doc repo (the X-doc sibling), never in code-repo companion files. Why: the code repo carries only code and machine-readable config; docs have one home in the doc repo.
Capture a gotcha into its topic-owner doc in the project doc repo the moment it surfaces, committed with the work that taught it. Why: an uncaptured surprise re-costs the same hour; one home per fact, never duplicated.
Owner adds a universal rule → .mdx in pm4ai apps/docs/content/rules/ with infer frontmatter; a new check → packages/pm4ai/src/{audit,checks}.ts. Why: rules generate CLAUDE.md, checks run in status.
Note any cross-project discovery for pm4ai. Why: a lesson hit on many projects becomes a universal rule/check.
Act only on a current check: proceed on check: passed (current); wait on check: running... (don’t edit); fix violations on check: failed; re-run + wait when stale (passed before N commits); run bunx pm4ai@latest fix first on check: never run. Why: stale/absent checks aren’t evidence.

Edit a managed file directly — CLAUDE.md, .github/workflows/ci.yml, clean.sh, up.sh, bunfig.toml, .gitignore, readonly/ui/. Cost: next pm4ai fix overwrites it.

pm4ai — manager; rules apps/docs/content/rules/*.mdx, checks packages/pm4ai/src/.
lintmax — max-strict lint/format orchestrator; every project depends on it.
cnsync — canonical readonly/ui (shadcn + ai-elements).

bunx pm4ai@latest status — check current project (--all for every project).
bunx pm4ai@latest fix — sync + maintain, requires clean git (--all for every project).
curl https://pm4ai.vercel.app/llms-full.txt — full docs.