Progressive Disclosure

Loading Rules

1. Always load L1 — this is automatic via opencode.json instructions
2. Load L2 when entering a package — read the package's AGENTS.md before modifying its code
3. Load L3 on demand — only read SKILL.md when you need to call the package's API
4. Load L4 when stuck — read GOTCHAS.md when debugging, FRICTION_LOG.md when hitting pain points
5. Load L5 for planning — read specs and CONSTITUTION.md when making architecture decisions

Why This Matters

Context window is finite. Loading everything upfront:

• Wastes tokens on irrelevant context
• Increases risk of compaction losing important details
• Slows down the agent with unnecessary information
• Makes it harder to find what's actually relevant

Document Size Caps

These caps exist to enforce progressive disclosure at the authoring level:

What to Do When a Document Exceeds Its Cap

1. Identify content that belongs at a different layer — API details in AGENTS.md should move to SKILL.md
2. Split by scope — a 300-line AGENTS.md probably covers multiple packages
3. Reference instead of repeat — link to detailed docs rather than inlining them
4. Remove obvious information — if it's in CONSTITUTION.md, don't repeat it

Context Budget

For a typical context window (~200k tokens), budget roughly:

When approaching the budget:

1. Use strategic compaction (see strategic-compact skill)
2. Don't load L4-L5 unless specifically needed
3. Rely on search tools rather than reading entire files

Anti-Patterns

See Also

• strategic-compact — When and how to compress context