dev-context-engineering

What this skill does

# Context Engineering

Use this skill to design repo-native agent context that is portable, high-signal, and maintainable. It owns the context model, migration path, maturity assessment, and context-graph discipline across `AGENTS.md`, runtime-specific layers, specs, rules, hooks, compiled markdown knowledge bases, and related artifacts.

## Quick Reference

| Task | Use |
|------|-----|
| Portable repo instructions | the `agents-memory` skill, [references/fast-track-guide.md](references/fast-track-guide.md) |
| Spec and plan flow | [docs-ai-prd](../docs-ai-prd/SKILL.md), [dev-workflow-planning](../dev-workflow-planning/SKILL.md) |
| Context graph design | [references/context-graph-guide.md](references/context-graph-guide.md), `python3 scripts/scan_context_artifacts.py --help`, `python3 scripts/validate_context_graph.py --help` |
| Hot-tier staleness + supersession integrity checks | `scripts/validate_context_graph.py` (checks `check_stale_tiers`, `check_supersession_integrity`) |
| Query a context graph (PPR, BFS, fan-in, tier budget) | `python3 scripts/query_context_graph.py <graph> --help` (modes: `--node`, `--impact`, `--rank`, `--ppr --seed`, `--tier-budget`) |
| Compiled markdown knowledge layer | the `docs-notes-retrieval` skill, [references/context-graph-guide.md](references/context-graph-guide.md), [references/multi-repo-strategy.md](references/multi-repo-strategy.md) |
| Multi-repo strategy | [references/multi-repo-strategy.md](references/multi-repo-strategy.md), [dev-context-multi-repo](../dev-context-multi-repo/SKILL.md) |
| Pick a framework (superpowers, GSD, Spec Kit, OpenSpec, …) | [references/framework-selection-matrix.md](references/framework-selection-matrix.md) |
| Regulated environment rollout | [references/regulated-environment-patterns.md](references/regulated-environment-patterns.md), [assets/ai-agent-governance.md](assets/ai-agent-governance.md), [assets/compliance-fca-emi.md](assets/compliance-fca-emi.md) |

## When to Use

- Set up or modernize `AGENTS.md`, `CLAUDE.md`, Copilot instructions, hooks, or agent rule layers.
- Migrate a repo from ad hoc prompting to durable agent context.
- Decide what belongs in always-on context vs docs, retrieval, or on-demand artifacts.
- Build a context graph and loading-tier model for a repo.
- Define a maturity path for AI-assisted development across one repo or a portfolio.
- Design the operating model for a large compiled repo knowledge base where agents create and refresh repo descriptions, indexes, and reports from structured artifacts.

## Route Elsewhere

- Writing the portable repo instructions themselves: use the `agents-memory` skill.
- Repo-portfolio discovery and hub generation: use [dev-context-multi-repo](../dev-context-multi-repo/SKILL.md).
- Symbol-level code graphs and blast radius: use [dev-context-code-graph](../dev-context-code-graph/SKILL.md).
- Task decomposition and verification plans: use [dev-workflow-planning](../dev-workflow-planning/SKILL.md).
- Hooks, MCP, or subagent implementation details: use [agents-hooks](../agents-hooks/SKILL.md), [agents-mcp](../agents-mcp/SKILL.md), or [agents-subagents](../agents-subagents/SKILL.md).

## Defaults

- Keep `AGENTS.md` as the portable baseline.
- Add runtime-specific layers only when they unlock a real capability.
- Put only non-inferable constraints in always-on context.
- Use a small hot instruction layer plus a larger compiled markdown knowledge base instead of one giant manifest.
- Prefer better state and structure over more text.
- Let the LLM maintain cold knowledge layers and derived notes; humans review policy, safety, and architectural constraints.
- Prefer outputs as durable files that can be filed back into the repo context instead of living only in chat history.
- Run a documentation placement gate before creating new Markdown; prefer updating canonical docs or generated context artifacts over adding one-off files.
- Treat context changes like code changes: review, validate, and prune.
- Generate `context-graph.json` once a repo reaches structured-context maturity.
- **Tool-set minimization**: Only give agents the tools they actually need. If a human engineer cannot say which tool should be used for a given task, an AI agent will not do better. Start small; expand on demand.
- **Resolver over accretion**: when the hot layer starts growing to handle a new edge case, prefer a pointer-style resolver (description-matched skill selection) that loads the right document on demand. See [references/context-resolver-pattern.md](references/context-resolver-pattern.md).

## May 2026 Validation Stance

Current context engineering should treat context as an evolving system, not a larger prompt. The strongest source-backed principles are:

- Context is finite working memory: optimize for the smallest high-signal token set that changes the outcome, then load deeper evidence just in time.
- Context adaptation is a first-class engineering loop: generate, reflect, curate, and validate updates without letting iterative summaries collapse detail.
- Raw evidence must stay retrievable. Summaries, memories, and graph nodes are routing layers; they are not substitutes for source files, transcripts, artifacts, or primary docs.
- Memory needs lifecycle semantics: provenance, freshness, supersession, contradiction handling, and user or tenant scope. Use temporal graph memory only when temporal reasoning, relationship change, or cross-session continuity matters.
- Graph retrieval is conditional. Use direct reads or lexical search for simple lookup; use graph traversal, PPR, or community summaries only for relational, multi-hop, or global sensemaking questions.
- Tool and context surfaces should be minimal and governed. More tools or more always-on rules create ambiguity unless the selection boundary is explicit.

## Multi-Tool Composition

Teams that ship fastest use the right tool for each task rather than forcing one agent to do everything. As of May 2026, the most effective pattern is:

| Tool | Best For | Context Model |
|------|----------|---------------|
| **Cursor / IDE agent** | Day-to-day editing, inline completions, tab-to-accept, quick refactors | IDE-native: open files + project index |
| **Claude Code** | Complex agentic tasks, multi-file changes, agent teams, code review, architecture | CLI: AGENTS.md + .claude/rules + skills + subagents |
| **Codex** | Parallel background work, batch processing, CI-adjacent tasks | Threads: AGENTS.md + .codex/agents + sandboxed workers |

**How to keep context consistent across tools:**
1. `AGENTS.md` is the portable baseline — all three tools read it.
2. Runtime-specific layers (`.claude/rules/`, `.codex/agents/`, `.cursor/rules/`) extend the baseline for each tool's strengths.
3. `docs/` in the repo is universally readable — invest knowledge there, not in tool-specific memory.
4. Use [dev-context-multi-repo](../dev-context-multi-repo/SKILL.md) to keep multi-repo context aligned across tools.

**Anti-pattern**: Duplicating conventions in Cursor rules, Claude rules, AND Codex agents. Write it once in `AGENTS.md` or `docs/`, then reference it.

**Stack on top of the IDE layer** when discipline drift or feature ambiguity is the bottleneck:

| Layer | Role | Pick from |
|-------|------|-----------|
| **L0 portable baseline** | Cross-tool conventions | `AGENTS.md` |
| **L1 runtime-specific** | Tool-specific extensions | `.claude/rules/`, `.codex/agents/`, `.cursor/rules/`, `.github/copilot-instructions.md`, `.clinerules/`, Aider `CONVENTIONS.md` |
| **L2 capability / methodology** | On-demand or enforced discipline | Claude Code Skills · superpowers (obra/superpowers) · GSD (gsd-build/get-shit-done) |
| **L3 artifact pipeline** | Spec → plan → tasks → code | GitHub Spec Kit (`.specify/specs/`) · OpenSpec (Fission-AI, `openspec/changes/`) |

L0 is mandatory; L1 is mandatory for tools that don't read AGENTS.md natively; L2 and L3 are optional but high-leverage when their named symptoms are pres