Context engineering: Introducing open-source Context Specs

Every developer has had the same experience: The AI writes code confidently, only for you to realize that it has missed the mark. The fix isn’t a better model, it’s better context.

Right context, right time. That's the whole game. 

To address this challenge, Capital One is open-sourcing Context Specs, a framework for spec-driven development (SDD) that treats context engineering—the practice of building systems that dynamically decide what your agent sees and when it sees it—as the primary lever for AI-assisted coding. The framework achieves this by capturing a team’s domain-specific knowledge into reusable “experts” that you create once and compose across the entire workflow, and then using automated feedback “signals” to verify the agent’s work.

Every AI coding agent operates within a context window, a fixed amount of information it can see at any given moment. This constraint creates three mechanical failure modes that plague every developer using AI tools today: 

• Context decay: Older messages in a conversation get ignored, summarized or dropped entirely. That careful instruction you gave 20 messages ago? Gone.
• Context pollution: When an agent searches your codebase autonomously, it pulls in irrelevant files. Every irrelevant token displaces a useful one.
• Compaction loss: When the window fills up, the system summarizes history to make room. You don't control what gets dropped.

These aren't edge cases; they're the default experience. Most frameworks for AI-assisted development weren't designed with these constraints in mind.

Some frameworks generate thousands of lines of specification markdown before a single line of code is written, burning millions of tokens on ceremony. Other frameworks are so lightweight they leave everything to interpretation, forcing the agent to search blindly and pollute its own context window. One floods the window with the wrong context, and the other leaves the agent to find it alone. Spoiler alert: Neither delivers the right context at the right time.

Solving these constraints requires shifting our focus from how we phrase our questions to how we manage our data. We can look at it as a shift between the following:

• Prompt engineering asks: What words do I use to get a good response?
• And context engineering asks: What information does this agent need, when does it need it, and how do I keep everything else out?

This is a fundamentally different design problem. It’s not about crafting the perfect instruction, it’s about building systems that dynamically curate information for agents as they work. A coding task succeeds when the right context arrives at the right time. It fails when it doesn’t. That’s the entire equation.

Context Specs is built around this principle. Every design decision—from how specs are structured, to how planning is separated from implementation, to how experts inject domain knowledge—serves one goal: Give the agent the right context at the right time, and protect the context window from everything else.

Context Specs provides a three-agent skill workflow. Each skill operates in its own agent session—a fresh context window—reading only the artifacts it needs from disk.

Spec planning (/spec-planning) works backward from done. First, define your end state, or the main spec. Then decompose it into temporal slices—ordered chunks of intent that read like a story, each one building on the last.

Slices are roughly user-story sized. The difference from traditional story writing is that these slices are grounded in your actual codebase—real file paths, real code patterns, real architectural constraints—not abstract requirements docs.

Context windows forget. Files don’t. The agent reads the spec fresh every time—no decay, no drift. This means the plan survives compaction. It survives session boundaries. It survives the developer closing their laptop and coming back on Monday.

Each slice includes curated codebase context: exact file paths, before and after states, type contracts and sequence diagrams. The implementation agent doesn’t have to search blindly, because the context it needs is already specified. This is progressive disclosure: The agent reads only the slice it’s implementing, pulling in dense context only when needed.

A single reviewer has blind spots. Context Specs addresses this with multi-agent validation (/spec-validate). Three or more independent agents review your spec in parallel. They don’t see each other’s work. Consensus scoring provides quantitative confidence: If all three flag the same issue, it’s real. If only one flags it, use judgment. This eliminates the false confidence of a single pass/fail review.

After consensus review, domain experts perform a specialized validation pass. They check for framework anti-patterns, internal library misuse, and gaps that only domain knowledge would catch.

The result: a hardened plan. Gaps are found before a line of code is written, and issues are surfaced while they’re cheap to fix in the spec, not in production.

Implementation (/implement-mainspec) reads the hardened plan and executes it. The implementation agent starts with a fresh context window so there's no leftover conversation noise and loads only the slice it’s working on.

For larger features, Context Specs automatically parallelizes work using git worktrees. The dependency-directed acyclic graph (DAG) from your spec plan determines which slices can run concurrently. Independent slices execute in parallel across isolated worktrees. Dependent slices wait for their prerequisites.

Each slice becomes its own feature branch and pull request (PR). Code review happens per slice, not as one massive PR, and the slices read like a story. Reviewers understand not just what changed, but why and in what order.

Large language models (LLMs) are trained on public knowledge. They know React, Spring Boot and PostgreSQL, but they don't know your internal component library, your team's testing conventions or your deployment pipeline. This gap between generic knowledge and organizational knowledge is where most AI-generated code falls short.

Context Specs helps solve this gap with experts.

An expert is created from your existing documentation using a single command. It captures your framework patterns, anti-patterns, naming conventions and validation approaches. Once created, that expert automatically participates in three phases:

• During planning: Curates domain-specific context into the spec, such as patterns to follow and mistakes to avoid
• During validation: Reviews the spec for domain-specific anti-patterns and gaps
• During implementation: Provides runtime feedback that proves the code actually works

While most AI coding tools stop at code generation, Context Specs continues into verification through signals, which is, essentially, a feedback loop that is built into every slice. Each slice specifies a signal that runs the tests, calls the endpoint and checks the build output. After writing code, the implementation agent invokes the signal and iterates until it passes. This transforms implementation from a single shot into a closed loop. The agent knows if it's on track, and it corrects course before moving on.

That’s why experts define custom signals for their domains. For example, a testing framework expert might run the test suite and validate coverage, whereas an application programming interface (API) expert might deploy to a lower environment and hit the endpoint.

Context Specs is also composable by design, allowing multiple experts to activate for a single feature. Building a full-stack feature? The React expert and the DynamoDB expert both contribute during planning, validation and implementation. Add your organization's private experts without modifying anything that already exists.

Context Specs is available now on GitHub under the Apache 2.0 license. It ships as installable Agent Skills. Add them to any project with a single command.

We believe the AI-native software development life cycle isn't about faster typing, it's about better thinking. Context engineering is how you get there. Capital One is giving this framework to the developer community and inviting you to extend it with your own experts, your own signals and your own workflows.

Explore the framework and start contributing today.