xoai/context-loader

Context Loader

The context window is the most precious resource in AI agent work. Loading everything wastes tokens and overwhelms the agent. Loading nothing means uninformed decisions.

Principle: load the minimum context needed for the current action.

This capability defines the loading strategy. Platform generators read this to decide what goes where.

When to Use

• When building or updating a platform generator
• When deciding what to inline vs reference in platform instruction files
• When evaluating whether a new skill or capability should be always-on

Three Layers

Layer 1: Always-On (inlined in main instruction file)

Content that MUST be in context at all times. Small enough to never hurt, critical enough to never skip.

| Content | Budget | Rationale | |---------|--------|-----------| | Process constitution (5 rules) | ~200 words | Governance must always be active | | Commands / workflows table | ~100 words | User needs to know what's available | | Interaction patterns | ~80 words | Consistent UX across all steps | | Project state reference | ~50 words | Where to find .sage/ artifacts |

Total Layer 1 budget: ~500 words / ~700 tokens. This is the floor that every platform must support. If a platform can't hold 700 tokens of always-on instructions, it can't run Sage.

Layer 2: On-Demand (referenced, loaded when needed)

Content loaded when a specific task requires it. The agent reads the file at the moment it's needed, not before.

| Content | When to Load | How to Reference | |---------|-------------|-----------------| | sage-navigator | Task start, session start | "Read the sage-navigator skill" | | Workflow details | When a workflow is triggered | "Follow the [X] workflow" | | Domain skills (jtbd, ux-audit...) | When navigator selects them | "Read and follow [skill] SKILL.md" | | Skill references (patterns, templates) | When the skill needs them | Skill's own instructions say when | | .sage/work/ frontmatter | Session start | Constitution rule 1 handles this | | .sage/decisions.md | Session start, checkpoints | Rule 7 handles this | | .sage/work/*/brief.md, spec.md... | When working on that initiative | Navigator/workflow references them |

Key principle: generators should REFERENCE these by path, not inline them. The agent reads them on demand. This keeps the always-on context lean.

Layer 3: Strategy (how generators decide)

Decision framework for generators:

Should this content be inlined?
├── Is it < 100 words AND needed on every response? → INLINE (Layer 1)
├── Is it needed only for specific tasks? → REFERENCE (Layer 2)
├── Is it needed only when a skill requests it? → REFERENCE (Layer 2)
└── Is it platform-specific boilerplate? → GENERATOR handles it

When in doubt, reference. It's always better to have the agent read a file when needed than to bloat the always-on context.

Platform Adaptation Rules

Generators MUST follow these rules when adapting core content:

1. Constitution: Always inline in the main instruction file. Read from core/constitution/sage-process.constitution.md.

2. Workflows: Generate as platform-native commands/workflows. Read from core/workflows/*.workflow.md. Substitute skill references with platform-specific paths.

3. Main instruction file: Use the canonical template at templates/main-instructions.template.md. Fill placeholders with platform-specific content.

4. Skills: Deploy or reference depending on platform mechanism. Never inline skill content in the main instruction file.

5. Navigator: Deploy or reference. Never inline — it's 300 lines and only needed at task boundaries.

Failure Modes

Generator inlines too much: Main instruction file exceeds 2,000 words. Agent drowns in instructions, follows none reliably. Fix: audit what's inlined, move to Layer 2.

Generator references non-existent paths: Agent tries to read a file that wasn't deployed. Fix: generators must verify paths exist in the target project structure.

Platform doesn't support on-demand file reading: Some platforms may not allow the agent to read arbitrary files. Fix: generator must inline critical Layer 2 content (navigator, active workflow) at the cost of a larger main instruction file. Document the trade-off.