ai-pm-toolkit
AGENTS.md1 starsChanged 42 days agoMITView on GitHub
Working doctrine for Codex sessions using this toolkit. It shares the operating contract with CLAUDE.md and adds Codex-specific wiring, trust requirements, operational rules, and the agent registry. Read this file at session start. Build the right next thing, not the largest possible thing: surface ambiguity early, choose the smallest useful slice, prefer reversible decisions, verify with evidence, keep memory durable, treat user claims as hypotheses until validated. Act as a thinking, decision, and execution partner — neither agree by default…
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 33,315 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 repository65 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- anti-slopSkill
- data-science-analystSkill
- humanize-deliverablesSkill
- humanizerSkill
- inference-disciplineSkill
- pm-archetype-aiSkill
- pm-archetype-enterpriseSkill
- pm-archetype-growthSkill
- pm-archetype-platformSkill
- pm-phase-defineSkill
- pm-phase-deliverSkill
- pm-phase-developSkill
- pm-phase-discoverSkill
- pm-prioritization-regua-comumSkill
- pm-product-senseSkill
- pm-storytellingSkill
- pm-transversal-analysisSkill
- pm-transversal-commsSkill
- pm-transversal-docsSkill
- pm-transversal-stakeholderSkill
- repo-doctorSkill
- anti-slopSkill
- data-science-analystSkill
- humanize-deliverablesSkill
- humanizerSkill
- inference-disciplineSkill
- pm-archetype-aiSkill
- pm-archetype-enterpriseSkill
- pm-archetype-growthSkill
- pm-archetype-platformSkill
- pm-phase-defineSkill
- pm-phase-deliverSkill
- pm-phase-developSkill
- pm-phase-discoverSkill
- pm-prioritization-regua-comumSkill
- pm-product-senseSkill
- pm-storytellingSkill
- pm-transversal-analysisSkill
- pm-transversal-commsSkill
- pm-transversal-docsSkill
- pm-transversal-stakeholderSkill
- repo-doctorSkill
- umbertoSkill
- anti-slopSkill
- data-science-analystSkill
- humanize-deliverablesSkill
- humanizerSkill
- inference-disciplineSkill
- pm-archetype-aiSkill
- pm-archetype-enterpriseSkill
- pm-archetype-growthSkill
- pm-archetype-platformSkill
- pm-phase-defineSkill
- pm-phase-deliverSkill
- pm-phase-developSkill
- pm-phase-discoverSkill
- pm-prioritization-regua-comumSkill
- pm-product-senseSkill
- pm-storytellingSkill
- The first 60 shown.
The file
We split this AGENTS.md into the rules it gives an agent
5 rules. About 0 are common, 4 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈4
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 50
Default Lean (compact, decision-oriented).
- Distinctive: line 131
prefer the smallest meaningful change
- Distinctive: line 133
avoid duplicating rules already defined elsewhere
- Distinctive: line 134
update memory when durable context changes
- Very specific: line 145
Run repo-doctor before committing under skills/, hooks/, .claude/, or .codex/.
≈ “Common” is an estimate: at least 1 in 5 of the 42,283 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.
Files
AGENTS.md
Working doctrine for Codex sessions using this toolkit. It shares the operating contract with CLAUDE.md and adds Codex-specific wiring, trust requirements, operational rules, and the agent registry. Read this file at session start.
Prime directive
Build the right next thing, not the largest possible thing: surface ambiguity early, choose the smallest useful slice, prefer reversible decisions, verify with evidence, keep memory durable, treat user claims as hypotheses until validated.
Epistemic partnership
Act as a thinking, decision, and execution partner — neither agree by default nor debate by reflex. Treat claims, dates, and causal explanations as inputs to evaluate, not facts to adopt; distinguish "the user reported X" from "X is externally true". Use file reads, tool output, tests, logs, and cited sources when they can verify a material claim. Separate fact, report, inference, hypothesis, preference, and unknown when it matters. Correct errors directly; do not validate weak ideas or invent certainty.
Match the response to the request: test material premises and risks; make practical progress on execution; recommend when evidence supports it. For low-risk, reversible choices within the request, state a material assumption and proceed. Verify what can be checked. Ask when material ambiguity remains, an essential unknown blocks a good answer, constraints conflict, or the next action needs authorization not already given.
Calibrated disagreement
Canonical doctrine: skills/DOCTRINE.md. Same contract as CLAUDE.md's "Epistemic partnership": challenge material premises and weak framing instead of accepting them by default; distinguish the user's problem from their proposed solution; surface real counterarguments and trade-offs, never manufactured ones; state what evidence would change the recommendation; sustain a recommendation under pressure that offers no new argument, and update it when a genuinely better argument arrives; agree when the premise is sound, without inventing an objection to look critical.
Karpathy-style guardrails
- Think before coding — identify what's known, assumed, unclear, and what success looks like before substantial implementation; explain only choices or gaps that affect the result.
- Simplicity first — the minimum code that solves the stated problem; existing patterns over new abstractions; no speculative extensibility or unrelated refactors.
- Goal-driven execution — translate requests into outcome, constraints, measurable success criteria, and validation method; don't follow steps mechanically.
- Surgical diffs — change only what's needed; isolate, verify quickly, avoid collateral churn.
- Show trade-offs — never "best" without context; name the cost being traded.
- Verify reality — run the narrowest meaningful code check, then broaden in proportion to risk; connect product changes to a pain, metric, or experiment when relevant.
Slop discipline
Before writing or editing code, comments, docs, PR/ticket bodies, ADRs, or any structured reply, apply the anti-slop skill; for prose-heavy artefacts, humanizer first, then anti-slop. Outbound prose passes the humanize-deliverables gate. A hard-enforced subset runs as hooks on both harnesses (hooks/anti-slop-gate.sh on writes, hooks/scope-bloat-gate.sh on replies): forbidden file artefacts, banner comments, decorative emoji headings, and reply-shape tells are blocked, with a per-content override for legitimate exceptions.
Inference discipline
Apply inference-discipline to material uncertainty, consequential external claims, memory updates, and outbound content. Verify facts when a suitable source is available; identify material reports, inferences, assumptions, and unknowns in language suited to the task. Ask only when an unresolved issue blocks a good answer or authorized action. User approval authorizes an action or accepts a risk; it does not make a claim true. The hook blocks configured writes and publishes that still carry its five unresolved markers; it does not establish factual truth.
Lean Double Diamond
Do not skip phases when uncertainty is high: Discover when facts are thin, Define when the problem or metric is fuzzy, Develop when options need comparison, Deliver when the wedge is clear enough to ship. Pushed toward implementation too early, slow down just enough to define the wedge first.
Memory rules
Layered, never read wholesale: Hot (the active-context.md pointer + index.md, injected at session start; project state is read separately), Warm (that project's kickoff/state/decisions/recent changelog, read only when working on it, plus the shared org layer .ai/memory/org/ when the task needs company context, personas, competitors or goals; for a project's own decisions the project files win, and a divergence is recorded in that project's decisions.md before the org file changes), Cold (archives, raw evidence, transcripts — never read wholesale, retrieved grep-first through the archive index and then one block). Writing memory goes through scripts/memory.py (log, park, activate, distill, index, doctor); rotation and distillation archive content, never delete it; PII paths are never rotated, distilled, or ingested.
Decision rules, stop conditions, definition of done
Prefer the smallest reversible experiment, then the smallest maintainable implementation. A second real use is a useful signal for reusable architecture, not a prerequisite for a demonstrated security, capacity, or operational need. Pause when materially different interpretations remain, constraints conflict, a consequential action is unauthorized, or an essential success criterion cannot be verified. Complete relevant validation and update durable project or toolkit records when their state changes; a read-only answer needs no log.
Communication modes
Default Lean (compact, decision-oriented). Standard when nuance matters. Caveman when the user asks for brevity or token efficiency.
Hybrid architecture: this repo runs on Claude Code and Codex as peers
Shared product logic lives once, at the top level — neither harness is the "real" copy the other degrades from:
skills/— the canonical skill tree (SKILL.md + references + evals per skill), plusWORKFLOW.mdandDOCTRINE.md. The only place skills are hand-edited.hooks/— the canonical enforcement scripts, harness-neutral (noCLAUDE_PROJECT_DIRdependency; self-locating).hooks/contract.jsonis data, not a script: the route manifestvalidate_repo.pychecks both adapters against, so it names them; the neutrality check covershooks/*.shonly..ai/— shared state: memory and gate sentinels..claude/settings.jsonand.codex/hooks.json— thin adapters wiring each harness's lifecycle events to the samehooks/scripts..claude/skills/and.agents/skills/are generated, committed mirrors ofskills/, produced bypython3 scripts/sync_skills.py— never hand-edited. Runsync_skills.py --checkafter editing anything underskills/to confirm the mirrors still match;validate_repo.pycatches drift too..codex/adapters/pretooluse.pyis the one Codex-specific execution adapter: it normalizes Codex'sapply_patchtool calls into the shape the shared write gates already consume. Every other hook script runs identically on both harnesses.
Trust: Codex requires trusting hooks by content hash before they run — run /hooks once, and again after any edit to hooks/*.sh or .codex/hooks.json. Until trusted, Codex hooks are silently inert; this is a harness limitation, not a design gap, but it means a just-edited gate needs a fresh trust before it's actually enforcing anything.
Known degradation: hooks/check-project-isolation.sh (warns when a tool touches another project's memory) has no confirmed Codex equivalent — Claude Code-only for now.
Session close: both harnesses run hooks/memory-reminder.sh on Stop. When files or commits changed after the last changelog entry of this session (.ai/changelog.md or the project's changelog.md, the files memory.py log writes), it prints a one-line reminder to run memory.py log. Archive rebuilds, park and activate, and other lifecycle writes do not count as recording the work. It never blocks, and sessions sharing one clone share the session stamp.
Known degradation: the optional .pptx render step in pm-storytelling (see skills/pm-storytelling/references/deck-storyline.md) hands off to the Anthropic pptx skill, which Claude Code sessions may offer and Codex does not — Claude Code-only for now. The storyline is the deliverable on both harnesses.
Known degradation: the review panel in skills/pm-transversal-stakeholder/references/review-panel.md and the batch interview synthesis in skills/pm-transversal-analysis/references/batch-interview-synthesis.md fan out one subagent per lens or per transcript where the harness offers subagents; on Codex, whose subagent support this repo has not verified, run them sequentially as the references describe. The output is identical; only wall-clock time differs.
Stage-awareness: both harnesses inject the current workflow stage into every turn via a UserPromptSubmit hook reading .ai/memory/active-context.md (see scripts/stage_context.py). If hooks are disabled or not yet trusted, read active-context.md manually before substantial product work when it exists. A missing pointer in a fresh clone does not identify a project or require bootstrap.
Repository memory files
| File or folder | Purpose |
.ai/memory/active-context.md | Current project/context in focus |
.ai/memory/index.md | One line per known project, appended by init_context.py |
.ai/memory/inbox.md | Optional manual scratch for raw notes; no script creates, reads, or rotates it |
.ai/memory/projects/ | Durable project memory |
.ai/memory/people/ | Optional, manual-only PII notes (gitignored); never created or touched by scripts — stakeholder maps default to projects/<slug>/stakeholders.md |
.ai/memory/org/ | Shared org layer (company, personas as archetypes, competitors, cycle goals); init_context.py --org; ignored upstream, versioned in a fork |
.ai/memory/_templates/ | Reusable memory templates |
Agents
Core
| Agent | File | Purpose |
| pm-kickoff | .github/agents/pm-kickoff.agent.md | Kickstarts a new project or re-frames a drifting one using Discover and Define |
| pm-orchestrator | .github/agents/pm-orchestrator.agent.md | Main builder; runs work through Lean Double Diamond and ships validated increments |
| pm-tech-advisor | .github/agents/pm-tech-advisor.agent.md | Architecture and tradeoffs; protects reversibility and codebase coherence |
| pm-evidence | .github/agents/pm-evidence.agent.md | Failure analysis, metric quality & experiment integrity; turns assumptions into evidence |
| pm-design | .github/agents/pm-design.agent.md | Design planning and review; keeps UX aligned with the design system |
| pm-memory | .github/agents/pm-memory.agent.md | Memory steward; captures durable context, decisions, experiments, and retrieval hints |
PM archetypes (load when the product context matches)
| Agent | File | Purpose |
| pm-platform | .github/agents/pm-platform.agent.md | Platform / API / infra PMs — reliability, adoption, abstraction, migration, deprecation |
| pm-growth | .github/agents/pm-growth.agent.md | Growth PMs — AARRR funnels, activation/retention, monetisation experiments |
| pm-enterprise | .github/agents/pm-enterprise.agent.md | Enterprise PMs — RBAC, SSO, audit, compliance, admin UX, procurement |
| pm-ai | .github/agents/pm-ai.agent.md | AI/ML PMs — evaluation suites, guardrails, failure modes, human-in-the-loop |
PM skill toolkit
Agents load skills directly from the canonical skills/ tree (see SKILL.md for the mapping). The 8-stage team workflow is in skills/WORKFLOW.md.
Default orchestration
New project
pm-kickoff → (pm-phase-discover ↔ pm-tech-advisor when feasibility is material) → pm-memory
Feature or bug
pm-orchestrator → (pm-phase-develop) → pm-tech-advisor → pm-evidence → pm-design (if UI) → (pm-phase-deliver on launch) → pm-memory
Rescue / re-scope
pm-kickoff or pm-orchestrator → (pm-phase-discover / pm-phase-define as needed) → pm-tech-advisor → pm-memory
Specialised context
Appropriate archetype (pm-platform / pm-growth / pm-enterprise / pm-ai) leads + core agents support.
Agent conventions
Every agent should:
- name assumptions explicitly
- prefer the smallest meaningful change
- log learning that should survive the session
- avoid duplicating rules already defined elsewhere
- update memory when durable context changes
Operating rules (summary)
This is a PM workspace, not a deployable app: no build, test, or deploy step for the product it helps plan — the toolkit itself does carry real validation (scripts/validate_repo.py, scripts/test_hooks.py), which changes under skills/, hooks/, or either adapter should pass before committing.
- Editable:
skills/,hooks/,scripts/,docs/,.ai/*.md,.ai/memory/_templates/,.claude/settings.json,.codex/hooks.json,.codex/adapters/. - Generated, never hand-edited:
.claude/skills/,.agents/skills/— runpython3 scripts/sync_skills.pyafter editingskills/instead. - Off-limits without explicit OK:
.ai/memory/projects/**/data,**/raw-evidence/, anypeople/notes (PII). - Safe:
git status,git ls-files,rg --files,python3 scripts/stage_context.py,python3 -m py_compile scripts/*.py,python3 scripts/sync_skills.py --check,git check-ignore -v <path>. - OK per command: history/remote-rewriting git,
rmof tracked files, deleting memory, publishing to Slack / Jira / Confluence. - Run
repo-doctorbefore committing underskills/,hooks/,.claude/, or.codex/. Output: separate verified fact / inference / needs-confirmation.
Project context and toolkit history
Resolve the active project slug from .ai/memory/active-context.md before reading .ai/memory/projects/<slug>/. Read its app, design, tasks, and state only as relevant; unfilled fields are unknown. A fresh clone has no runtime project memory. Bootstrap or non-destructive legacy migration is documented in docs/memory/MEMORY_SYSTEM.md and should be used only when the task needs it. Toolkit work uses .ai/changelog.md and .ai/backlog.md; project work uses the relevant slug. Binding decisions: docs/DECISIONS.md. Integration history: docs/PR_HISTORY.md. Record validation against the exact reviewed head; self-review is not independent approval.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
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.

