Getting Started

If README.md exists at the repo root, read it first.

Ecosystem

All projects with lintmax in deps are managed by pm4ai (bunx pm4ai@latest). The tool syncs configs, generates CLAUDE.md, enforces conventions, and runs maintenance.

Key repos:

• pm4ai — the management tool. Rules in apps/docs/content/rules/*.mdx. Checks in packages/pm4ai/src/.
• lintmax — max-strict lint/format orchestrator. All projects depend on it.
• cnsync — canonical source for readonly/ui (shadcn + ai-elements components).

For full documentation: curl https://pm4ai.vercel.app/llms-full.txt

Managed Files

These files are auto-generated and synced by pm4ai. Never edit them directly:

• CLAUDE.md — generated from rules based on project dependencies
• .github/workflows/ci.yml — universal CI workflow
• clean.sh — universal cleanup script
• up.sh — universal maintenance cycle (clean + install + build + fix + check)
• bunfig.toml — bun configuration
• .gitignore — universal ignore patterns
• readonly/ui/ — synced from cnsync

Role Detection

Run gh auth status to determine your role:

• If you are the repo owner (1qh): you can modify pm4ai rules and checks directly in the pm4ai repo
• Otherwise: do not edit managed files, only use companion files

Owner Workflow

• bunx pm4ai@latest status — check current project
• bunx pm4ai@latest fix — sync + maintain (requires clean git)
• bunx pm4ai@latest fix --all — all projects
• New universal rule → add .mdx to pm4ai apps/docs/content/rules/ with infer frontmatter
• New check → add to pm4ai packages/pm4ai/src/audit.ts or checks.ts
• If you discover something during this session that should apply to all projects, note it for pm4ai

Companion Files

Use these for project-specific content:

• LEARNING.md — lessons learned, gotchas, known issues
• RULES.md — project-specific rules that don’t apply to other projects
• PROGRESS.md — tracking ongoing work
• PLAN.md — planning and architecture decisions

Health Check

Run bunx pm4ai@latest status to see issues in this project. Run bunx pm4ai@latest fix to sync and maintain.

Check states:

• check: passed 5m ago (current) — safe to proceed
• check: passed 3h ago (before 2 commits) — stale, run bunx pm4ai@latest status again and wait for refresh
• check: failed 5m ago (current), 15 violations — fix violations before proceeding
• check: running... — wait, do not edit files until complete
• check: never run — run bunx pm4ai@latest fix first