plan-cache

---
name: plan-cache
description: This skill should be used when the user asks to "cache the plan", "load plan SSoT", "remember the plan sections", or when starting a new session in a worktree containing `.blueprint/plans/*.md`. Replaces the 5-section briefing template friction by pre-loading plan parent context once per session.
mode: [coding, engineering, ops, personal]
effort: low
---

# Plan-Cache — Eliminate briefing template friction (v7.3+)

## Purpose

The `feedback_always_reference_initial_plan` rule (NON-NEGOTIABLE) requires reading sections A/B/F/G/H of the parent plan BEFORE coding. This is great for intent alignment but creates **briefing template friction** — every spawned agent prompt was getting a 5-section template re-pasted, costing ~2-3 min per invocation.

**plan-cache solves this** by reading the plan ONCE at session start, extracting key sections, and caching them in `~/.atlas/runtime/plan-cache.json` for subsequent reference via 1-line `<plan-ref>` instead of full re-paste.

## When to invoke

Auto-invoked at SessionStart if `.blueprint/plans/*.md` exists in cwd. Manually invoke when:
- Plan was just modified (cache stale)
- Switching between worktrees with different plans
- User asks "what's in the parent plan?" or similar

## Workflow

### Phase 1 — Discover plan parent

```bash
# Find newest plan file
PLAN_FILE=$(ls -t .blueprint/plans/*.md 2>/dev/null | head -1)
[ -z "$PLAN_FILE" ] && echo "No plan in .blueprint/plans/" && exit 0
```

### Phase 2 — Cache freshness check

```bash
# Hash the source plan
PLAN_SHA=$(sha256sum "$PLAN_FILE" | cut -d' ' -f1)
CACHE_FILE="$HOME/.atlas/runtime/plan-cache.json"

if [ -f "$CACHE_FILE" ]; then
  CACHED_SHA=$(jq -r '.sha // ""' "$CACHE_FILE" 2>/dev/null)
  if [ "$PLAN_SHA" = "$CACHED_SHA" ]; then
    echo "✅ Plan cache fresh (sha=$PLAN_SHA)"
    exit 0
  fi
fi
```

### Phase 3 — Extract sections A/B/F/G/H

```bash
# Run the cache-plan.sh script (extract via awk on heading regex)
bash "${CLAUDE_PLUGIN_ROOT}/skills/plan-cache/scripts/cache-plan.sh" "$PLAN_FILE"
```

### Phase 4 — Verify

```bash
# Validate cache content
jq -e '.sections.A and .sections.B and .sections.F and .sections.G and .sections.H' "$CACHE_FILE" \
  && echo "✅ Plan cached with all 5 sections"
```

## Cache schema

```json
{
  "plan_path": "/abs/path/to/plan.md",
  "plan_id": "ATLAS-V7.3-MODE-SWITCH",
  "sha": "sha256-hash",
  "cached_at": "2026-05-02T12:00:00Z",
  "sections": {
    "A": "Context...",
    "B": "Goals & Non-Goals...",
    "F": "Files Critical...",
    "G": "Verification...",
    "H": "Persona E2E Acceptance..."
  },
  "frontmatter": {
    "plan_id": "...",
    "status": "...",
    "target_release": "..."
  }
}
```

## Replaces

The 5-section briefing template (per `feedback_always_reference_initial_plan`):
```markdown
**Plan parent SSoT** : `.blueprint/plans/{plan-name}.md`
**Sections critiques à lire AVANT de coder** :
- A. Context & Vision
- B. Architecture
- F. Files critical
- G. Verification
- H. Persona E2E acceptance
```

After plan-cache loads, this 5-section block is replaced by:
```markdown
<plan-ref path="..." sha="..." cached_at="..." />
```

The LLM reads cache file when needed (1 file read vs full briefing re-paste).

## Integration

### SessionStart hook

Add to `${CLAUDE_PLUGIN_ROOT}/hooks/hooks.json` SessionStart array:
```json
{
  "type": "command",
  "command": "\"${CLAUDE_PLUGIN_ROOT}/skills/plan-cache/scripts/cache-plan.sh\" --auto",
  "async": true,
  "timeout": 5
}
```

### atlas-team briefing (V2 future)

Replace the 5-section briefing block in spawned agent prompts with `<plan-ref/>` self-closing tag pointing to cache. Agents can read cache via Read tool when needed.

## Failure modes

- No `.blueprint/plans/` → exit 0 silent (not an error, just no plan)
- Multiple plans → use newest (mtime) by default
- Sections missing → cache what's present, log missing
- jq/awk missing → log warning, skip cache (LLM falls back to full read)

## Tests

`tests/test_plan_cache.py` covers:
- Empty plans dir → no-op
- Single plan → full cache
- Multi plan → newest wins
- Stale cache → rebuild
- Section A/B/F/G/H extraction accuracy

## Related

- Plan: `.blueprint/plans/ultrathink-je-veux-que-soft-aurora.md` (v7.3 plan)
- Hook: `${CLAUDE_PLUGIN_ROOT}/hooks/mode-resolver` (reads plan presence for boost)
- Feedback: `feedback_always_reference_initial_plan.md` (the rule this skill optimizes)
- Feedback: `feedback_plan_anchored_caching.md` (rationale for caching pattern)