Context Management

Agents use a multi-layered approach to manage context across phases and sessions, preventing assumption contamination while maintaining traceability.

Disk Artifacts (Source of Truth)

All persistent state lives in versioned files on disk. Board is the source of truth for task status and ownership. Disk artifacts are the source of truth for design decisions, specifications, and architecture.

Artifact	Path	Phase
Strategic vision	docs/envisioning/README.md	Envision
Feature specification	docs/features/*/spec.md	Specify
Technical plan	docs/features/*/plan.md	Plan
Task decomposition	docs/features/*/tasks.md	Decompose
Architecture decisions	docs/architecture/decisions/*.md	Plan
Migration specification	docs/migrations/*/spec.md	Specify
Migration tasks	docs/migrations/*/tasks.md	Decompose
Sprint records	docs/sprints/sprint-N.md	Sprint

Copilot Memory

Built-in memory that stores stable facts discovered during work:

• Code conventions: Detected patterns and project-specific rules
• Verified commands: Build, test, and deployment commands that work
• Synchronization patterns: Board and repository sync status
• Project structure: Key directories, entry points, and configuration

Characteristics: automatic, validated via citations, shared between agents, expires in 28 days.

Used by: implement, plan, review, security agents.

Handoff Envelope

Structured context passing between phases (ADR 0003):

Relevant Artifacts

Paths to files the next phase should read (spec.md, plan.md, ADRs, tasks.md).

Inherited Assumptions

Decisions and assumptions from the current phase that carry forward.

Pending Decisions

Open questions or decisions that the next phase needs to resolve.

Discarded Information

Context that was considered but explicitly excluded from the handoff.

Note

Each phase starts with clean context and reads artifacts from disk. This isolation prevents assumption contamination from previous phases.

Context Flow Between Phases

flowchart LR
  subgraph envision["Envision"]
    E1["envisioning.md"]
  end
  subgraph specify["Specify"]
    S1["spec.md"]
  end
  subgraph plan["Plan"]
    P1["plan.md"]
    P2["ADRs"]
  end
  subgraph decompose["Decompose"]
    D1["tasks.md"]
    D2["Work Items"]
  end
  subgraph implement["Implement"]
    I1["Source Code"]
    I2["Pull Request"]
  end
  subgraph review["Review"]
    R1["Review Log"]
  end

  E1 -->|"handoff envelope"| S1
  S1 -->|"handoff envelope"| P1
  P1 -->|"handoff envelope"| D1
  P2 -->|"read from disk"| D1
  D1 -->|"handoff envelope"| I1
  D2 -->|"board state"| I1
  I1 --> I2
  I2 -->|"clean context"| R1

Each arrow represents a phase boundary where context is explicitly passed via a handoff envelope or read from disk artifacts. Agents never inherit the previous phase’s working memory.

Phase Cleanup Points

1. specify to plan: Spec locked, plan starts fresh reading spec from disk
2. plan to decompose: ADRs locked, decompose reads decisions from files
3. decompose to implement: Tasks locked, implement picks one task at a time
4. implement to review: Code committed, review reads independently with clean context

Session Memory

The .memory/ directory stores session-scoped configuration (not committed to git):

File	Purpose	Populated By
board-config.md	Detected work item platform	detect-repo-platform.sh hook
git-config.md	Detected branching strategy	detect-branching-strategy.sh hook

---

What to Read Next

• Reasoning and Handoff for how decisions transfer between agents
• Hooks for lifecycle automation points