product-wiki
AGENTS.md8 starsChanged 5 months agoMITView on GitHub
This repo is a product-wiki harness for coding agents. Use it to turn product intent into reviewed wiki changes before implementation. Do not take a non-trivial product request straight to code. First create or update a proposal in intake/proposals/. Only compile to code after the proposal is approved by the user. The user should not need to ask for a skill by name. When a request looks like a feature idea, bug report, workflow change, product question, or retrofit task,…
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 32,671 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 repository8 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- apply-wiki-changeSkill
- compile-changeSkill
- generate-checksSkill
- import-codebaseSkill
- propose-changeSkill
- reconcile-wikiSkill
- review-architectureSkill
The file
Show its rules and text
We split this AGENTS.md into the rules it gives an agent
28 rules. About 0 are common, 18 are distinctive, and 10 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈18
Distinctive · estimate
This author's own choices. Worth a look.
10
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 4
Use it to turn product intent into reviewed wiki changes before implementation.
- Very specific: line 8
Do not take a non-trivial product request straight to code.
- Distinctive: line 10
Only compile to code after the proposal is approved by the user.
- Distinctive: line 13
When a request looks like a feature idea, bug report, workflow change, product question, or retrofit task, route it into the right Product …
- Distinctive: line 17
If a change can be described in one sentence and has no product or architecture impact, make the edit and run the relevant checks.
- Distinctive: line 24
Keep it short enough to scan before every meaningful change.
- Distinctive: line 25
Update or review it whenever a change affects the whole-product picture.
- Very specific: line 27
Use wiki/index.md as the linked catalog.
- Very specific: line 31
Do not use Obsidian-only [[type.slug]] links.
- Very specific: line 32
Use stable IDs in frontmatter, and list related unit ids in the frontmatter links: array (the machine-readable graph).
- Very specific: line 58
Use repo skills from .agents/skills.
- Very specific: line 70
When a skill names a template under templates/, load that template before writing the artifact.
- Distinctive: line 71
If the template or skill contract is missing, first run:
- Distinctive: line 79
Stop only if the canonical contract cannot be restored.
- Distinctive: line 80
Do not reconstruct proposal, wiki-unit, import, compiler-plan, or check-manifest shapes from schemas, lint output, examples, or memory.
- Distinctive: line 88
Import every capability, one reviewable proposal at a time, ticking the inventory as you go.
- Distinctive: line 91
Do not stop after one capability.
- Very specific: line 106
When searching code, first grep for PW: anchors, then fall back to normal code search.
- Distinctive: line 107
Use anchors only at useful boundaries: routes, services, workflows, domain modules, and tests.
- Distinctive: line 108
Do not annotate every line.
- Distinctive: line 130
Run deterministic loops with:
- Distinctive: line 136
Run the same lightweight loop the Stop hook calls with:
- Very specific: line 144
When a routine finds drift that needs judgement, use reconcile-wiki to fix safe links or raise a proposal.
- Very specific: line 145
Use node scripts/ratchet-lint.mjs after implementation to make sure current checks, approval coverage, and wiki anchors have not slipped …
- Distinctive: line 149
Use subagents only when separate context helps.
- Distinctive: line 150
Do not spawn one reviewer per step by default.
- Distinctive: line 160
Before finishing work, run:
- Very specific: line 182
Do not treat CONSTITUTION.md as enforcement.
≈ “Common” is an estimate: at least 1 in 5 of the 41,581 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
This repo is a product-wiki harness for coding agents. Use it to turn product intent into reviewed wiki changes before implementation.
Core rule
Do not take a non-trivial product request straight to code.
First create or update a proposal in intake/proposals/.
Only compile to code after the proposal is approved by the user.
The user should not need to ask for a skill by name. When a request looks like a feature idea, bug report, workflow change, product question, or retrofit task, route it into the right Product Wiki skill automatically. Explicit skill names are only a fallback when routing is unclear.
Small mechanical edits can take a lighter path. If a change can be described in one sentence and has no product or architecture impact, make the edit and run the relevant checks.
Product wiki
The product wiki lives in wiki/.
Read wiki/overview.md first.
It is the whole-product map: what this product is, who it serves, the main journeys, main capabilities, important rules, boundaries, and key decisions.
Keep it short enough to scan before every meaningful change.
Update or review it whenever a change affects the whole-product picture.
Use wiki/index.md as the linked catalog.
Link units in prose with standard relative markdown links so GitHub, Cursor previews, Obsidian, Codex, and Claude Code can all follow the graph.
From the repo root, link to real wiki paths such as wiki/stories/.
From a wiki unit, link to related units with paths such as ../jobs/<job-slug>.md.
Do not use Obsidian-only [[type.slug]] links; they ship as dead text on GitHub.
Use stable IDs in frontmatter, and list related unit ids in the frontmatter links: array (the machine-readable graph).
Core units:
overview: whole-product map and entrypoint.index: linked catalog for navigation.actor: role involved in the system.job: solution-free problem worth solving.story: one chosen solution slice.acceptance-criterion: observable done condition.rule: product logic that applies across stories.journey: flow or end-to-end path.capability: reusable product or system function.decision: ADR-style rationale.
Growth units:
outcome: measurable success signal.non-goal: explicitly out of scope.assumption: risk or uncertain belief.glossary: shared language.
For how to size and split units, when to make a separate story, and when a choice is a decision rather than a rule, see .agents/skills/propose-change/references/proposal-rubric.md ("Sizing and splitting units"). Right-sized, not maximal: do not create a unit that carries nothing another unit does not.
Skills
Use repo skills from .agents/skills.
propose-change: turn a request into a reviewable wiki proposal.apply-wiki-change: apply an approved proposal towiki/.compile-change: turn an approved wiki change into code and executable checks.import-codebase: completely reverse-import an existing repo into the wiki. Inventory the whole codebase first, then import every capability until coverage is complete. Not a single sample.reconcile-wiki: find drift between wiki, tests, architecture, design, and code.review-architecture: check reuse, boundaries, dependencies, and refactor pressure.generate-checks: turn acceptance criteria into executable checks.
Contracts repair before stopping
When a skill names a template under templates/, load that template before writing the artifact.
If the template or skill contract is missing, first run:
node scripts/repair-contracts.mjs --writeThen re-run node scripts/template-lint.mjs and node scripts/skill-lint.mjs.
Continue if repair succeeds.
Stop only if the canonical contract cannot be restored.
Do not reconstruct proposal, wiki-unit, import, compiler-plan, or check-manifest shapes from schemas, lint output, examples, or memory.
Retrofitting an existing repo
A retrofit is a complete, end-to-end import, not a sample. Use import-codebase and:
- Inventory the WHOLE codebase first into
intake/import-inventory.md(every surface, module, route, job, data store, and cross-cutting concern). - Split the inventory into small batches and record the next resume point.
- Import every capability, one reviewable proposal at a time, ticking the inventory as you go. Resume from the inventory across sessions for large repos.
- The retrofit is done only when
node scripts/import-coverage.mjsreports 0 pending and no unmapped top-level source directory.
Do not stop after one capability. Do not edit application code during import.
How the wiki connects to code
The wiki is natural language. It does not contain code, and it is not compiled to code mechanically. The wiki is the reviewed source of truth; the code the compiler writes from it traces back to it three ways:
PW:<id>comment anchors in the code name the wiki unit each part implements. Grep an id to find its code..product-wiki/source-map.jsonis the generated index from each anchored wiki id to its code location.checks/manifest.jsonties each acceptance criterion to a test command that runs against the code.
So the bridge from intent to code is by reference and by executable check, not by the wiki holding the code. Capability, rule, and journey units carry the code anchors; the other unit types connect to code through them and through acceptance criteria.
Wiki anchors
When searching code, first grep for PW: anchors, then fall back to normal code search.
Use anchors only at useful boundaries: routes, services, workflows, domain modules, and tests.
Do not annotate every line.
Example:
// PW:capability.self-serve-flight-change
// PW:rule.fare-difference-confirmationRun:
node scripts/wiki-anchor-lint.mjs --write-reportThis validates anchors and writes a local source map to .product-wiki/source-map.json.
Loops
Recurring loops are defined in routines/manifest.json.
Native turn-end loops are wired through .codex/config.toml and .claude/settings.json.
Run deterministic loops with:
node scripts/routine-runner.mjs --allRun the same lightweight loop the Stop hook calls with:
node scripts/hook-loop.mjs --event manualLoop reports are written to .product-wiki/routine-runs/ and .product-wiki/hook-loops/.
They should not be committed.
When a routine finds drift that needs judgement, use reconcile-wiki to fix safe links or raise a proposal.
Use node scripts/ratchet-lint.mjs after implementation to make sure current checks, approval coverage, and wiki anchors have not slipped backwards.
Subagents
Use subagents only when separate context helps. Do not spawn one reviewer per step by default.
Good uses:
- Architecture review for cross-module or high-risk changes.
- Verification review after code and checks are produced.
- Consistency review when the wiki and code may have drifted.
Checks
Before finishing work, run:
node scripts/product-wiki-check.mjsThat includes wiki-overview-lint, which checks the overview exists, is linked from the index, links back to the index, and is reviewed when active wiki units change.
Also run the product repo's normal tests when this harness is copied into an application repo.
Hard guardrails
Markdown files guide the agent. Scripts, CI, checks, and the host agent's own permission settings enforce the hard rules. The native Stop hook only runs the Product Wiki maintenance loop.
The approval gate is enforced deterministically at check time.
scripts/intent-lint.mjs fails if an acceptance criterion is active without an approved or implemented proposal introducing it.
scripts/checks-lint.mjs requires manifest coverage once a proposal is implemented, while approved proposals can remain pending compile.
This runs inside node scripts/product-wiki-check.mjs and CI.
Do not treat CONSTITUTION.md as enforcement.
It records principles.
The executable guardrails live in scripts/, CI, checks, and the host agent's permission settings.
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.

