Context Engineer Skill - Project Context & Memory

Version: 9.0 | Updated: 01-July-2026 | Architect: Karim Bhalwani | Tiered: core (~150 lines) + on-demand references

Unified reference for project initialization, context management, and persistent memory.

Project Bible Structure

.copilot/context/
  PROJECT_CONTEXT.md   -- Tier 1: always loaded (< 200 lines)
  ORIENTATION.md       -- Tier 1: 5-minute quick-start summary
  ARCHITECTURE.md      -- Tier 2: loaded by task match
  CODEBASE_PATTERNS.md -- Tier 2: loaded by task match
  AGENT_GUIDE.md       -- Tier 2: loaded by task match
  DECISIONS.md         -- Tier 3: loaded on reference

.copilot/state/
  SESSION_STATE.md     -- Pipeline checkpoint for cross-session resume

.copilot/specs/
  SPEC.md              -- Written by Architect; consumed by Developer and Guardian

.copilot/holdout/     -- Written by Architect; read only by Guardian

.copilot/artifacts/
  review-report.md     -- Written by Guardian; consumed by Release Manager

Artifact Directory Convention

Producers create directories if needed. Files always reflect "latest" (no versioning).

Tiered Loading

• Tier 1 (< 200 lines): Identity, tech stack, critical rules. Loaded at session start.
• Tier 2: Architecture, patterns, agent guide. Load per these explicit triggers:
  • ARCHITECTURE.md: load when the task involves adding, removing, or evaluating components or dependencies
  • CODEBASE_PATTERNS.md: load when the task involves writing, reviewing, or refactoring code
  • AGENT_GUIDE.md: load when the task involves coordinating between agents or reviewing agent output
• Tier 3: Decision log, historical context. Loaded only when referenced.

Smart Project Initialization

Scan Phase

1. Detect frameworks: pyproject.toml, package.json, requirements.txt, Cargo.toml
2. Detect test runners: pytest, jest, go test
3. Detect CI: .github/workflows/, Jenkinsfile, azure-pipelines.yml
4. Detect infrastructure: Dockerfile, docker-compose.yml, terraform/, bicep/

Draft Phase

• Generate Tier 1 context from scan results
• Mark items as [CONFIRMED], [INFERRED], or [UNKNOWN]

Validate Phase

• Cross-reference context with actual code
• Verify build/test commands actually work
• Flag stale or contradictory information

Session State Management

Agents persist pipeline progress to .copilot/state/SESSION_STATE.md for cross-session resume. Follow the Session Resume Protocol from core-behavior.instructions.md §9 for startup/checkpoint/completion procedures.

Load session_state_schema.md for the full schema. Keep under 60 lines.

Context Evolution Rules

Update Protocol

See Context File Write Rules for the authoritative ordered protocol.

Context File Write Rules

All write operations to context files follow this ordered priority list:

1. Read before write: always read existing context before any update; never overwrite blindly
2. Mark changes: annotate changes with date and reason
3. Confidence override hierarchy (highest to lowest): [CONFIRMED] > [DECLARED] > [INFERRED]
   • A new [CONFIRMED] entry replaces an existing [DECLARED] or [INFERRED] entry for the same field
   • A [DECLARED] entry replaces an existing [INFERRED] entry for the same field
   • An existing [CONFIRMED] entry is never replaced by [DECLARED] or [INFERRED] evidence; only newer [CONFIRMED] evidence may update a [CONFIRMED] entry
4. Supersede, don't delete: move deprecated decisions to [SUPERSEDED] with a link to the replacement
5. Surface unknowns: [UNKNOWN] items are always surfaced to the user

Definition of Done

Apply Context File Write Rules when producing or updating any context file. All of the following must be true:

• Tier 1 PROJECT_CONTEXT.md exists and is under 200 lines
• All detected items marked [CONFIRMED], [INFERRED], or [UNKNOWN]
• Build and test commands verified (actually run, not assumed)
• No [UNKNOWN] items remain without an inline note in PROJECT_CONTEXT.md explaining why the value could not be determined (e.g., [UNKNOWN] - no package manifest found)
• Context files are consistent with actual codebase state

Constraints

• Does NOT write application code or tests
• Does NOT generate speculative documentation (everything must have a source)
• For confidence-level override rules, see Context File Write Rules above

Integration Points

• brownfield-discovery: Produces [CONFIRMED] findings for the Project Bible
• greenfield-interview: Produces [DECLARED] founding documents
• architect: Consumes the Project Bible as primary input
• holdout-validation: Evaluation reports feed into retrospective tracking
• memory tool: Cross-session facts stored via Copilot Memory

Scripts

Missing script fallback: If a referenced script does not exist at the expected path, stop and notify the user with the exact missing path before proceeding. Do not attempt to recreate the script.

• scripts/scaffold_bible.py - Create stub files for all 6 Project Bible documents. Run at the start of the documentation phase. Mode: --mode greenfield or --mode brownfield.
• scripts/verify_bible.py - Verification gate for the Project Bible. Exits 1 if any of the 6 files is still a stub or missing.
• scripts/scaffold_session_state.py - Create .copilot/state/SESSION_STATE.md from the schema template. Idempotent; does not overwrite existing files.
• scripts/verify_session_state.py - Verify SESSION_STATE.md exists and contains all required schema sections and a valid Status: value.
• scripts/context_cache.py - Manage the ## Context Cache section in SESSION_STATE.md. Agents query this before reading shared files (SPEC.md, STORIES.md, PROJECT_CONTEXT.md) and add entries after reading. Commands: add, query, list, clear.

References

Load on demand for specific sub-tasks:

• templates-and-retrospectives.md - Memory system templates (bug log, ADR, key facts, work history), retrospective workflow, rework tracking, workflow effectiveness audit, environment auditing, 5-minute orientation details. Load for retrospectives or project memory work.
• context_snippet.md - Context snippet template for consistent format and tiered citations.
• orientation_template.md - 5-Minute Orientation template.
• session_state_schema.md - Session State schema for cross-session resume.
• entropy_audit.md - Entropy Audit checklist for quarterly audits.
• pipeline-loop.md - Cross-session iteration tracking and 3-strike circuit breaker for the Release Manager / Senior Developer / Guardian review cycle.