Skip to content

AGENTS.md

Prompt History Convention

Every time an agent works on this repository, it must append both sides of the current conversation turn to the appropriate per-session chat file under docs/dev/chats/CHAT-XXXX.md as two separate, fenced plaintext code blocks — in this order:

  1. User block — the exact user message that triggered this session.
  2. Agent block — a concise summary of what the agent did / replied.

Format






````

### Rules

- Always append to the **end** of `PROMPT.md`; never edit existing blocks.
- Use plain fenced code blocks (triple backticks, no language tag).
- Keep the agent block short but informative (one or a few sentences).
- Do this **before** calling `report_progress` for the final commit so that
  the turn is included in the same commit as the rest of the changes.

---

## ⚠️ Conversation Logging Convention — PRIMARY PROTOCOL (supersedes PROMPT.md) ⚠️

**Every agent session must update the conversation logs** by appending to a
new per-session file under `docs/dev/chats/CHAT-XXXX.md`.

The `PROMPT.md` section above is **legacy**; once `PROTOCOL.md` exists, skip it.

### Turn structure

```markdown
## Turn #N — <short description>

### Message #0 — @human

### Message #1 — Agent

<formatted markdown prose: `code` spans, **bold**, lists, etc.>

```markdown
<verbatim agent reply, all markdown formatting preserved>

THOUGHTS

````

Rules (memorise these)

  1. Human is always #0 and always starts every turn.
  2. Human blocks: plain ``` fence, no language tag, verbatim text only.
  3. Agent blocks: formatted markdown prose + the agent's full, complete, verbatim response inside a ```markdown fence. Not a summary — the entire reply.
  4. Turn numbers are sequential from 1 — never skip or reuse.
  5. Missing turns → reconstruct from PROMPT.md, commit history, and context. Mark reconstructed messages with <!-- reconstructed --> on the header line.
  6. Gap detection: ## Turn # lines must be sequential; every turn must have ### Message #0. A missing #0 or a gap in N means a turn needs filling.
  7. Parsing turns: scan for ## Turn #N → extract N as integer → content ends at next ## Turn # or EOF.
  8. Parsing messages: within a turn, scan for ### Message #M → extract M → content ends at next ### Message # or ## Turn # or EOF.
  9. Do this before report_progress — the turn must be in the same commit.
  10. THOUGHTS: after the ```markdown block, add #### THOUGHTS (four #) with a short note on the agent's reasoning for the turn — what was considered, what was rejected, why (like "showing how the brain works"). Optional but encouraged; omit if nothing to record.
  11. Files Accessed: after THOUGHTS (or after the verbatim block if THOUGHTS omitted), add #### Files Accessed listing every repo-local file path read, created, or modified — one bullet per file with a brief note. Omit if no repo files were accessed. Mark <!-- reconstructed --> on the header for past turns.

Per-session chat files (docs/dev/chats/CHAT-XXXX.md)

Each agent session must be logged in its own file under docs/dev/chats/, following the same turn/message format defined above and in PROTOCOL.md.

  • One file per session: when you first touch the conversation log in a new Cursor session, create a fresh docs/dev/chats/CHAT-XXXX.md file for it.
  • Naming: use zero-padded, monotonically increasing numbers:
  • CHAT-0001.md, CHAT-0002.md, CHAT-0003.md, …
  • Header: start each file with:

```markdown # Chat #N — Conversation Logs

Canonical conversation log for this repository. See PROTOCOL.md for the format specification.

```

  • Content: inside each CHAT-XXXX.md, append turns exactly as you would to CHATS.md (same headers, verbatim blocks, THOUGHTS, and Files Accessed sections).
  • Index: keep docs/dev/chats/devindex.md in sync:
  • Append a new row to the table for each new CHAT-XXXX.md.
  • Use the next sequential index number and link to the new file.
  • Append-only: never rename or reuse an existing CHAT-XXXX.md; only append new turns or retroactively reconstruct missing ones when needed.

Key Project Files

Files every agent should know exist in this repository:

File Purpose
PROMPT.md Legacy per-turn conversation log (append-only, superseded by per-session files)
CHATS.md Legacy aggregate conversation log (no longer updated for new work)
PROTOCOL.md Self-contained spec for the conversation log format
AGENTS.md This file — conventions and key-file reference for agents
docs/dev/chats/devindex.md Index of per-session chat files (CHAT-XXXX.md)
docs/dev/chats/CHAT-XXXX.md One file per agent session, full conversation log for that session
docs/index.md Main documentation home page
docs/dev/LLM-PARAMS.md LLM session-parameters reference (privacy, exposure, reproducibility)
docs/ci/DEPLOYMENT.md Pre-flight deployment checklist
mkdocs.yml MkDocs site configuration and nav