---
name: post-dev
description: "Post-development cleanup: update AGENTS.md and docs/agent/ knowledge files to reflect code changes. MUST activate before git commit (or when user asks to commit/push). Also activate after any code modification that adds/removes files, changes architecture, or modifies core behavior."
---

# Knowledge Management

Maintain a living knowledge base so future sessions (with zero memory) can work effectively.

## Iron Rules

1. **Every file referenced in AGENTS.md MUST exist on disk.** Before adding a reference, create the file. Before removing a file, remove its reference. Broken references are worse than no references.
2. **Knowledge files (docs/agent/) are the primary deliverable, not AGENTS.md.** AGENTS.md is just an index. When you learn something non-obvious, write it into the appropriate knowledge file. Only update AGENTS.md's index entry if the file list changed.
3. **Read before write.** Before updating any knowledge file, read it first. Before creating AGENTS.md references, verify the target file exists.
4. **Do NOT copy the structure from this skill into AGENTS.md.** Every project is different. Observe the actual project structure and document what exists, not what a template says should exist.

## Two-Layer Architecture

```
AGENTS.md (auto-injected into prompt — the single source of truth)
  → project summary, build commands, architecture overview
  → GOTCHAS: critical pitfalls written directly here (no separate file)
  → Knowledge Files index: tells you WHERE to look for details
  → should make you want to Read specific files, not answer questions directly

docs/agent/ (the actual knowledge, on disk — use Read/FileReplace/FileCreate)
  → agent reads them with Read tool when needed
  → each file is self-contained on one topic
  → AGENTS.md references them; agent uses them
```

## AGENTS.md

Auto-loaded into system prompt (up to 10000 chars). Keep it concise but information-dense.

Purpose: tell your future self **where to look** AND **what will kill you**.

What belongs:
- One-line project summary
- Architecture overview (2-3 sentences, link to detail file for more)
- Build/test/lint commands
- **GOTCHAS section**: critical pitfalls that MUST be visible without opening extra files. These are non-negotiable — if a pitfall can waste hours or crash the process, it goes here. Keep it to bullet points, no prose.
- **Knowledge Files section**: list of existing files with one-line descriptions
- Key conventions that don't fit elsewhere (max 5 bullets)

What does NOT belong:
- Anything that belongs in a knowledge file (except critical gotchas)
- Specific line numbers, function signatures, or code snippets
- Information already in README
- Minor/niche gotchas that are package-specific → put those in the relevant knowledge file

## Knowledge Files (docs/agent/)

These are where the real knowledge lives. **Create them freely — one file per topic, no need to consolidate.** More small files is better than fewer large ones.

### Directory Structure

Mirror the repository's directory structure under `docs/agent/`. This makes it trivial to find the right file:

```
docs/agent/                    ← knowledge root
  architecture.md              ← cross-cutting: message flow, pipeline, conventions
  conventions.md               ← cross-cutting: coding style, error handling
  agent.md                     ← agent/ package: loop, engine, middleware
  channel.md                   ← channel/ package: CLI, Feishu, Web, QQ
  llm.md                       ← llm/ package: OpenAI, Anthropic, retry, streaming
  tools.md                     ← tools/ package: built-in tools, sandbox, hooks
  memory.md                    ← memory/ package: letta, flat, providers
```

When you explore a new subsystem or package, create its knowledge file. Don't worry about having too many — future sessions will use AGENTS.md's index to find exactly the right file.

### When to create a new knowledge file

- You explored a subsystem deeply enough to document it
- A knowledge file would save future sessions from re-exploring the same code
- A topic is growing too large in an existing file — split it

### When to update an existing knowledge file

- You discovered something that changes or contradicts what's documented
- The project structure changed (files moved, APIs renamed)
- You found a bug, workaround, or gotcha worth recording

## Decision Flow

After completing a task, update knowledge:

1. **Did I encounter or fix a gotcha/pitfall? → Write it directly into AGENTS.md's GOTCHAS section.** Critical gotchas (crashes, silent data loss, hours-wasting traps) go into AGENTS.md so they're always visible without opening extra files. Package-specific/niche gotchas can go into the relevant knowledge file instead.
2. Did I learn something about the codebase (APIs, dependencies, conventions, architecture)? → Write it into the relevant knowledge file under `docs/agent/`
3. Did the file/knowledge list change? → Update AGENTS.md's Knowledge Files index
4. Did any existing documentation become stale due to my changes? → Update it in place
5. Did I add gotchas to AGENTS.md? → Remove redundant entries from docs/agent/ if they're now fully covered in AGENTS.md. AGENTS.md should be the single source of truth for critical pitfalls.

**Default to updating.** Every session should leave the knowledge base more accurate than it found it. The only exception is truly trivial changes (typo fixes, comment-only edits).

## Accuracy Maintenance

- Before writing: Read the existing file first
- After writing: Verify AGENTS.md references match actual files on disk
- When deleting/renaming files: Update all references in AGENTS.md and other knowledge files
- Do NOT just append — revise outdated content
- Keep each file focused on one topic; split when a file grows beyond ~200 lines
- After significant updates: spot-check that AGENTS.md index entries match actual files on disk
