context-steward

name	context-steward
description	Unified context lifecycle for FlowDeck sessions — ingest, filter, prune, protect, summarize, and persist with telemetry.
origin	FlowDeck

Context Steward

FlowDeck sessions accumulate noise. Tool outputs, rule loads, failed attempts, and multi-agent chatter fill the context window. This skill defines a unified lifecycle to keep context lean, relevant, and recoverable.

When to Activate

Activate when:

• Context exceeds 50% of the window and response quality drops
• Multiple agents have contributed outputs in one session
• Tool results are large (logs, diffs, file reads)
• You are about to switch phases (plan → execute → verify)
• A /fd-checkpoint is imminent

Core Principles

• Context is a liability — every token not serving the current task is a distraction
• Prune with purpose — never drop what the agent needs to continue
• Protect the thread — user intent, active plans, and safety records are non-negotiable
• Telemetry is cheap — write stats before pruning so patterns are visible later

---

Unified Context Lifecycle

1. Ingest

Everything that enters the session window:

Source	Typical Size	Risk Level
User prompts	Small	Low — never prune
Tool results (read, edit, bash)	Variable	High — can be huge
Skill loads	Medium	Medium — load once per session
Rule injections	Small-Medium	Medium — stage-gated already
Agent outputs	Medium	Medium — may contain plans or decisions
Memory queries	Small	Low
codegraph results	Small-Medium	Low

Ingest discipline: Before any large output enters context, ask whether it is needed for the next 5 turns. If not, summarize or redirect to file.

---

2. Filter

FlowDeck already gates rules by stage. Extend this discipline to all context sources.

Current Stage	Load	Defer / Skip
discuss	Behavioral rules, AGENTS.md	Coding standards, testing rules
plan	Architecture rules, planning rules	Security rules, lint rules
execute	Coding standards, language patterns, security	Debug rules (until needed)
verify	Testing, security, linting rules	Planning rules
fix-bug	Debug, testing rules	Architecture rules

Filter action: If a skill or rule is not relevant to the current stage, do not load it. Use load-rules on demand rather than pre-loading.

---

3. Prune — Three-Pass Pipeline

Pruning is surgical. It runs when context exceeds 50% of the window or when switching tasks.

Pass 1: Deduplicate

What gets pruned:

• Identical tool outputs repeated across agents (e.g., two agents reading the same file)
• Duplicate skill loads (same skill invoked twice with identical parameters)
• Redundant codegraph queries returning the same symbols

What stays:

• First occurrence of any unique output
• Outputs with different parameters or timestamps
• User prompts (never deduplicated)

How to invoke:

• Agent-triggered: after parallel agent execution, the orchestrator deduplicates before presenting results
• Manual: agents may call a deduplication routine directly; there is no dedicated slash command

FlowDeck-native pattern: When @parallel-coordinator dispatches 3 agents that all read src/config.ts, keep only the first read result. Reference the others by index.

---

Pass 2: Purge Errors

What gets pruned:

• Failed tool executions that have been superseded by a later success
• Stack traces from resolved errors
• Old build failures after a successful build
• Retry loops where the final attempt succeeded

What stays:

• The most recent failure if the issue is still unresolved
• Failures linked to an active FAILURES.json entry
• Errors that inform the current debugging session

How to invoke:

• Agent-triggered: @debug-specialist purges resolved error chains after root cause is found
• Automatic: after bun test exits 0, purge prior failing test output

FlowDeck-native pattern: If @debug-specialist fixes a type error, purge the type-checker output but keep the fix description in SESSION_SUMMARY.md.

---

Pass 3: Compress Stale Ranges

What gets pruned:

• Old conversation turns (> 10 turns back) not touching current files
• Large file reads from modules no longer being edited
• Tool outputs from completed sub-tasks
• Agent outputs for tasks already merged or abandoned

What stays:

• Last 2 user messages (see Protected Patterns)
• Active plan and STATE.md content
• Decisions and failures linked to current work
• Any output touching files in the current git diff

How to invoke:

• /fd-checkpoint — full session save + context clear
• Agent-triggered: @orchestrator compresses after each wave in a multi-wave plan

FlowDeck-native pattern: Replace 20 turns of exploratory editing on src/auth.ts with a single synthetic summary: "Explored 3 approaches for token refresh; selected sliding-window with 15-min expiry. See DECISIONS.jsonl:auth-refresh-2026-06-10."

---

4. Protect

Protected patterns are immune to all pruning passes.

Category A: Core System

Pattern	Why Protected
Orchestrator rules (agent-orchestration.md)	Routing depends on them
AGENTS.md	Defines agent boundaries and non-negotiables
STATE.md	Current phase, plan, blockers
PLAN.md (active)	Success criteria and step order

Category B: Safety

Pattern	Why Protected
.codebase/DECISIONS.jsonl	Rationale for current design
.codebase/FAILURES.json	Prevents repeating failed approaches
.codebase/CONSTRAINTS.md	Architecture guards

Category C: User Intent

Pattern	Why Protected
Last 2 user messages	Most recent instructions
Active plan reference	What the user asked for
Explicitly pinned context	User said "keep this in mind"

Category D: Tool-Specific (In-Flight)

Pattern	Why Protected
write output for current file	Must verify what was written
edit diff for current change	Must confirm diff is correct
bash output for running command	Command may still be relevant

Protection rule: If a tool operation is in-flight or its result is referenced in the next 3 turns, do not prune it. Mark it as pinned until the agent acknowledges it.

---

5. Summarize

After pruning, replace removed ranges with synthetic summary messages.

Summary format:

[Context Steward] Pruned N turns (M tokens). Retained: [list].
Summary: [1-2 sentences]. Evidence: [link to DECISIONS.jsonl or SESSION_SUMMARY.md].

What to summarize:

• Exploratory edits → decision + chosen approach
• Research → conclusion + source
• Multi-agent discussion → consensus + dissent (if relevant)
• Build/test cycles → final status + any remaining failures

What NOT to summarize:

• Active user instructions (keep verbatim)
• In-flight tool operations (keep verbatim)
• Unresolved errors (keep verbatim until fixed)

---

6. Persist

Write pruning stats to .codebase/TELEMETRY.jsonl for pattern analysis.

Entry format:

{"ts":"2026-06-10T14:32:00Z","event":"context-prune","session_id":"abc123","before_tokens":85000,"after_tokens":42000,"passes":{"dedup":12,"purge_errors":8,"compress":25},"protected":15,"summary_tokens":180}

Why persist: Over time, telemetry reveals which agents produce the most noise, which skills bloat context, and when pruning is most effective.

---

Decision Matrix: Prune vs Compact vs Checkpoint

Situation	Tokens	Action	Command
Minor bloat, same task	40-60%	Prune (3-pass)	Agent-triggered
Major bloat, same task	60-80%	Compact + prune	Agent-triggered, then /fd-checkpoint
Task complete, new task next	Any	Checkpoint	/fd-checkpoint
Phase switch (plan → execute)	Any	Compact	Agent-triggered summary
Multi-wave plan, wave done	Any	Compact	@orchestrator summarizes wave
Session > 1 hour	Any	Checkpoint	/fd-checkpoint
Context > 80%	Any	Checkpoint immediately	/fd-checkpoint

Prune: Remove noise, keep session alive. Compact: Replace ranges with summaries, keep session alive. Checkpoint: Save state, start fresh session.

---

Anti-Patterns

Do Not Prune Active User Instructions

The last 2 user messages are sacred. If they contain a multi-part instruction, keep all parts until the agent has addressed each one.

Bad: Prune turn 5 where the user said "also fix the test" because it is 10 turns back, while the agent is still working on the first part.

Good: Pin the instruction and unpin after confirmation.

Do Not Duplicate Tool Results Across Agents

When @parallel-coordinator dispatches agents, each agent may read the same file. Do not carry all N copies forward.

Bad: 3 agents read src/db.ts; all 3 full file contents stay in context.

Good: Keep the first read. Subsequent agents reference it by citation.

Do Not Compress Without Preserving Evidence Links

A summary without a link is a rumor. Always attach evidence.

Bad: "We decided on approach A."

Good: "Selected approach A (sliding-window expiry). See DECISIONS.jsonl:auth-refresh-2026-06-10."

---

FlowDeck Tool Reference

Tool / Command	Role in Context Steward
codegraph	Find symbols without reading full files — reduces ingest size
memory	Query past decisions instead of loading full DECISIONS.jsonl
decision-trace	Record decisions before compressing the discussion that led to them
/fd-checkpoint	Full save + clear — use at 80% or task boundaries
/fd-resume	Load summarized context instead of full history
load-rules	Stage-gated rule loading — reduces ingest at session start

---

Cross-Reference

Skill	Relationship
context-budget	Sets thresholds and audit practices. Context Steward executes the pruning when those thresholds are breached.
session-persistence	Defines what to save at session boundaries. Context Steward decides what to prune before that save happens.
strategic-compact	Advises on when to compact manually. Context Steward automates compaction as part of the prune pipeline.
context-guard	Defines boundary checks. Context Steward uses those boundaries to decide what is protected during pruning.

---

Quick Reference

Ingest  → Filter by stage → Prune (dedup → purge → compress)
            ↓                    ↓
        load-rules            Protect core / safety / intent / in-flight
            ↓                    ↓
        Skip irrelevant       Summarize pruned ranges
            ↓                    ↓
        rules/skills          Persist telemetry

Protected always: AGENTS.md, STATE.md, active PLAN.md, .codebase/DECISIONS.jsonl, .codebase/FAILURES.json, last 2 user messages, in-flight tool results.

Prune first: Duplicate reads, resolved errors, stale exploratory turns.

Checkpoint when: > 80% tokens, task complete, phase switch, session > 1 hour.