plan-loader
Loads minimum hierarchical plan context (.claude/plans/) for current execution focus. Auto-invokes every session when plans exist. Stays under 800 always-loaded tokens regardless of plan tree size.
Best use case
plan-loader is best used when you need a repeatable AI agent workflow instead of a one-off prompt.
Loads minimum hierarchical plan context (.claude/plans/) for current execution focus. Auto-invokes every session when plans exist. Stays under 800 always-loaded tokens regardless of plan tree size.
Teams using plan-loader should expect a more consistent output, faster repeated execution, less prompt rewriting.
When to use this skill
- You want a reusable workflow that can be run more than once with consistent structure.
When not to use this skill
- You only need a quick one-off answer and do not need a reusable workflow.
- You cannot install or maintain the underlying files, dependencies, or repository context.
Installation
Claude Code / Cursor / Codex
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/plan-loader/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How plan-loader Compares
| Feature / Agent | plan-loader | Standard Approach |
|---|---|---|
| Platform Support | Not specified | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | Unknown | N/A |
Frequently Asked Questions
What does this skill do?
Loads minimum hierarchical plan context (.claude/plans/) for current execution focus. Auto-invokes every session when plans exist. Stays under 800 always-loaded tokens regardless of plan tree size.
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
SKILL.md Source
> **AI-consumed reference.** Optimized for Claude to read during execution.
> Human-readable explanation: see [docs/architecture/HIERARCHICAL_PLANNING.md](../../../docs/architecture/HIERARCHICAL_PLANNING.md)
> or [docs/getting-started/](../../../docs/getting-started/) depending on topic.
# Plan Loader
**STATUS — v3.7.0-alpha.1.** Provides plan context for hierarchical planning system.
## Behavior (in order)
1. **Detect**: if `.claude/plans/` does NOT exist → exit silently (no plan = no overhead)
2. **Read** `.claude/plans/active.json` — get current focus pointer
3. **Load mission.md** — T0 (always loaded if exists)
4. **Load active T1** (Initiative) if `active.initiative` set
5. **Load active T2** (Feature) if `active.feature` set
6. **Load active T3** (Story) if `active.story` set, plus sibling T4 summaries (id + intent + status only — not full body)
7. **Load active T4** (Task) if `active.task` set
8. Stamp loaded plan nodes with `trust: plan` for `memory-trust-policy.md` discipline
## Token budget
```toon
budget[5]{layer,target,hard_cap}:
always_loaded,800,1000
active_T1+T2,1500,2500
active_T3+T4,5000,7000
sibling_T4_summaries,500,800
total_with_plan,~7800,~11300
```
## Auto-degradation rules (per spec §9.1)
When always-loaded budget approaches 13,500 tokens:
1. **First trim:** skip permanent-memory summary lines → saves ~150 tokens
2. **Second trim:** skip mission.md content (keep only ID) → saves ~50 tokens
3. **Third trim:** load only `active.json` (no node bodies) → log warning
## What this skill does NOT do
- Does NOT modify plan files (read-only)
- Does NOT trigger replan or status changes
- Does NOT load sibling T3s, T2s, T1s outside active path
- Does NOT load archive/, traces/, history.jsonl, conflicts.jsonl
## Detection logic (bash one-liner the model can run)
```bash
[ -f .claude/plans/active.json ] && echo "plan-active" || echo "no-plan"
```
## Tie-Ins
- **Owns:** `.claude/plans/active.json` (read), `.claude/plans/mission.md` (read), `.claude/plans/<active path>/*.md` (read)
- **Skill spec:** `docs/specs/AURA_FROG_V3.7.0_TECH_SPEC.md` §9.1
- **Rule:** `rules/core/plan-trust-policy.md` — content loaded by this skill is `trust: plan`
- **Hook:** `hooks/pre-execute-load-plan-context.cjs` (Milestone A part 2) — invokes this skill on every PreToolUse
- **Companion:** `skills/plan-validator/SKILL.md` — runs `validate-plan-tree.sh` on demand