Load full project context at session start. Read STATE.md, PLAN.md, PROJECT.md, CONVENTIONS.md, and ARCHITECTURE.md to brief any agent on where work stands.

2026-07-2215

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.