> ## Documentation Index
> Fetch the complete documentation index at: https://mainbranch.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Promote patterns from scratchpad to shared context

> The promotion workflow moves recurring patterns from your personal scratchpad into AGENTS.md — the committed file every agent and teammate reads each session.

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:

```markdown theme={null}
## 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

<Steps>
  <Step title="Check what's ready to promote">
    ```bash theme={null}
    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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Commit the result">
    ```bash theme={null}
    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.
  </Step>
</Steps>

## 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.

```markdown theme={null}
<!-- auto-reflect: promote=auto -->
```

You can also trigger automatic promotion from the command line:

```bash theme={null}
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.

<Note>
  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.
</Note>

## Keeping AGENTS.md under 120 lines

<Tip>
  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.
</Tip>

Promotion is not about accumulation — it is about distillation. The goal is a file where every line earns its place on every turn.