Skip to main content
Not everything the agent observes belongs in AGENTS.md. The scratchpad is where patterns are experimental. AGENTS.md is where proven knowledge lives. Promotion is the deliberate step between the two — the agent flags candidates, and you decide what moves.

​
How the workflow works

Patterns start as session notes. When something recurs across three or more sessions, the agent flags it in the ## Ready to Promote section of .agents.local.md. You review the candidates and move the ones that have proven themselves into AGENTS.md. 
Session notes → .agents.local.md → agent flags stable patterns → you promote to AGENTS.md
                    (personal)                                        (shared)
This separation is intentional. The scratchpad is gitignored and personal. AGENTS.md is committed, shared with your team, and loaded into every agent’s context on every turn.

​
The Ready to Promote format

When the agent identifies a recurring pattern, it writes a row into the ## Ready to Promote table using a standard format: 
## Ready to Promote

| Category | Item | Detail |
|----------|------|--------|
| Pattern | Result<T> for error handling | All services return Result<T>, never throw |
| Gotcha | DB_URL required for unit tests | Set DB_URL even for unit tests |
Each row has three fields: the category (Pattern, Gotcha, or Boundary), a short name, and a detail line that explains the rule or trap and how to handle it.

​
The AGENTS.md format patterns are promoted into

AGENTS.md uses a compressed pipe-delimited format. When you promote a pattern, it becomes a single line in the relevant section: 
[Result types, not try/catch | src/lib/errors.ts]
[DB_URL required even for unit tests | docker compose up db first]
The pipe separates the rule from its context — where to see it or what to do about it. Keeping each entry to one line is what makes the file fast to load and easy to scan.

​
Running the promote command

1

Check what's ready to promote

agent-context promote
This scans .agents.local.md for the ## Ready to Promote section and shows you what the agent has flagged. No files are written until you confirm.
2

Review and approve each candidate

For each flagged item, decide whether it belongs in AGENTS.md. Items you approve are appended to the appropriate section. Items you skip stay in ## Ready to Promote for next time.
3

Commit the result

git add AGENTS.md && git commit -m "promote: add Result<T> pattern and DB_URL gotcha"
Your teammates and all future agent sessions now have access to this knowledge.

​
Automatic promotion

If you have configured promote=auto in .agents.local.md, patterns are promoted directly to AGENTS.md when they recur 3 or more times — no manual review step. 
<!-- auto-reflect: promote=auto -->
You can also trigger automatic promotion from the command line: 
agent-context promote --autopromote
With --autopromote, any item in ## Ready to Promote that has recurred 3+ times is appended to AGENTS.md immediately. The agent logs what it promoted under ## Auto-Promoted in .agents.local.md so you can review after the fact.
Because AGENTS.md is version-controlled, any auto-promotion is reversible. If the agent promotes something you disagree with, delete the line from AGENTS.md and commit the removal.

​
Keeping AGENTS.md under 120 lines

As you promote patterns, watch the line count. The 120-line cap is not arbitrary — frontier models reliably follow roughly 150–200 instructions, and Claude Code’s system prompt already uses around 50. Every line you add to AGENTS.md competes for that budget. When the file approaches the cap, compress: merge related entries, tighten phrasing, and move deep detail into agent_docs/ files that the agent reads on demand.
Promotion is not about accumulation — it is about distillation. The goal is a file where every line earns its place on every turn.