docs

name	docs
description	Maintains evergreen documentation in docs/. Use this skill when a major feature is added, changed, or removed to keep the corresponding explainer up to date. Also use when the user asks to document something or references this skill.
globs	docs/**

Documentation Skill

You maintain the docs/ directory as the source of truth for how Opal works. Each major feature or subsystem gets an evergreen explainer that stays current as the code changes.

When to act

• A feature is added, significantly changed, or removed → update or create the relevant doc.
• The user explicitly asks to document something.
• A pull request changes behavior described in an existing doc.

Format guidelines

Write docs that are right-sized — long enough to be useful, short enough to actually be read.

• Start with a one-paragraph overview of what the feature does and why it exists.
• Show the interface (tool schema, function signature, config keys) before explaining internals.
• Use Mermaid diagrams for pipelines, data flow, and architecture — never ASCII art. Wrap in ```mermaid fenced blocks.
• Include a "How it works" section with just enough detail to debug or extend the feature. Skip implementation trivia.
• End with a References section linking to external sources, blog posts, papers, or benchmarks that informed the design. Always include references the user has provided.
• No timestamps or version numbers — the doc describes the current state, not a changelog.

File organization

docs/
├── ARCHITECTURE.md       # System-level overview
├── tools/
│   ├── edit.md           # Edit tool (hashline, str_replace history)
│   └── ...               # One file per major tool or tool concept
├── agent-loop.md         # Agent execution model
├── compaction.md         # Context compaction
├── supervision.md        # OTP supervision tree
└── ...                   # One file per subsystem

Place tool docs in docs/tools/. Place subsystem docs directly in docs/.

Style

• Write for a developer who knows the language but not the codebase.
• Prefer concrete examples over abstract descriptions.
• Use code blocks for schemas, configs, and short snippets.
• Keep headings to 3 levels max (##, ###, no ####).
• Link to source files when referencing specific modules (e.g. lib/opal/tool/edit_lines.ex).

References

When the user provides external references (blog posts, papers, benchmarks), always include them in a ## References section at the bottom of the doc with title, author/source, year, and a one-line description of relevance.