OpenSpec Compound Engineering Layers

OpenSpec compound engineering is best understood as an editorial layering pattern, not a documented product integration. OpenSpec can organize change intent and implementation artifacts. Compound Engineering can preserve reusable work knowledge. A proposed external code graph can supply current structural facts. Each layer answers a different question, and source code plus tests remain the final behavior check.

The value comes from clean handoffs. The risk comes from letting three independently changing layers appear to agree when they do not.

Quick Verdict

Use the layers this way:

This OpenSpec compound engineering split is useful only when each layer keeps its own authority and update rule.

Layer	Primary question	Typical artifact	Authority limit
OpenSpec	What change are we agreeing to build?	proposal, delta specs, design, tasks	Expresses intended behavior and work, not current code structure.
Compound Engineering	What did prior engineering work teach us?	plan, review findings, solution record	Preserves scoped workflow knowledge, not an exhaustive system map.
Proposed external code graph	How is this revision structurally connected?	typed, provenance-bearing nodes and edges	Generated facts can be incomplete and need source verification.

There is no documented first-party integration among OpenSpec, Compound Engineering, and Graphify in the pinned primary sources. [OPENSPEC-OVERVIEW-20260724] [CE-README-20260724] The workflow below is therefore a proposed composition that teams must implement and govern themselves.

Also separate two uses of “graph.” OpenSpec's schema can define dependencies among change artifacts. That artifact dependency graph controls creation order. It is not a code knowledge graph of symbols, calls, implementations, or tests. [OPENSPEC-SCHEMA-20260724]

The structural layer is introduced in Knowledge Graph for AI Coding Assistants. The broader memory model is covered in Compound Engineering Memory Explained.

OpenSpec as Intent Context

OpenSpec provides a structured process for agreeing on a change before implementation. Its current overview describes a change folder with artifacts such as a proposal explaining why and scope, delta specifications describing added or modified behavior, a design explaining technical decisions, and tasks tracking implementation work. [OPENSPEC-OVERVIEW-20260724]

That makes it useful intent context, but “intent” should not be reduced to one proposal file. In spec-driven development:

• the proposal frames the problem and change boundary;
• delta specs define expected behavior through requirements and scenarios;
• the design records the implementation approach and trade-offs;
• tasks turn the agreement into executable work.

The current OPSX command flow uses /opsx:* commands to explore, propose, apply, verify, and archive changes. [OPENSPEC-COMMANDS-20260724] Teams should use the terminology present in their installed version rather than copying older command examples from secondary guides.

OpenSpec artifacts are strongest when reviewers can test them for internal consistency. Does each task implement a requirement? Does the design address the constraints in the proposal? Do scenarios cover the edge case that motivated the change? They are weaker as evidence of current runtime behavior. A spec may be correct while the code is incomplete, or obsolete while the code moved on.

Compound Engineering as Work Memory

Compound Engineering contributes reusable knowledge about how work was understood, implemented, and reviewed. The pinned current repository documents planning, review, and compounding capabilities. Its ce-compound skill writes one selected durable learning to solutions/, and ce-compound-refresh can maintain stale or overlapping solution records. [CE-README-20260724] [CE-COMPOUND-20260724] [CE-REFRESH-20260724]

This work-memory layer must not be conflated with Claude Code auto memory, which is supplied by the host rather than the Compound Engineering plugin. [ANTHROPIC-MEMORY-20260724]

The accepted search form Everyinc/compound-engineering-plugin refers to the canonical repository spelling EveryInc/compound-engineering-plugin. The distinction is small for search, but exact entity naming matters when a team pins a repository or commit for audit.

Work memory should not duplicate the OpenSpec change package. A useful solution record might explain why a production failure evaded the original scenario, which diagnostic path found it, and which validation now prevents recurrence. The associated OpenSpec artifacts still own the intended change. The solution record owns the transferable learning from performing or repairing the work.

Compound Engineering does not provide OpenSpec's artifact model in the cited repository, and OpenSpec does not provide Compound Engineering's solution workflow. Any connector between them must state how artifact IDs, repository revisions, review status, and permissions are carried across.

Code Graphs as System Structure

A proposed external code graph answers questions neither artifact set can answer exhaustively: which current symbol implements a specified behavior, which callers are in the change radius, which tests reach the path, or whether a path named in an old solution still exists.

The graph should use typed edges and expose provenance. A fact such as CheckoutHandler CALLS PaymentService needs a repository, indexed commit, source location, extraction method, and access scope. It is a structural candidate for the agent to verify, not a statement of intended behavior.

Graphify can be considered as one possible external code graph layer. It is not a built-in OpenSpec or Compound Engineering component, and this article makes no first-party integration claim.

Do not import OpenSpec's artifact dependency graph and call it a code graph. The former can say that a design artifact depends on approved specs before it is created. The latter represents properties of a code revision. [OPENSPEC-SCHEMA-20260724] A connector may link a requirement to candidate symbols, but that cross-layer link should show whether it was curated, inferred, or generated by similarity.

The graph is most valuable when it narrows verification. If it cannot support the requested language, branch, generated source, or runtime configuration, it should return uncertainty and let the agent inspect the repository directly.

How the Layers Fit an Agent Workflow

Consider a change to idempotent payment retries.

1. Explore the request. Clarify the failure, constraints, and affected user behavior. Do not write graph facts or durable solutions yet.
2. Create the OpenSpec change. Capture why and scope in the proposal, behavior in delta specs, technical choices in design, and implementation work in tasks. [OPENSPEC-OVERVIEW-20260724]
3. Retrieve prior work memory. Search reviewed Compound Engineering solutions for the same subsystem, error class, or constraint. Preserve their version scope and treat conflicting records as a review signal.
4. Query proposed structural context. Resolve requirement terms and prior solution references to candidate symbols, callers, and tests on the target revision. Return provenance and uncertainty.
5. Plan and implement. Use the intent artifacts as the acceptance boundary, prior solutions as scoped evidence, and graph results as navigation. Open the source and run tests before accepting any claim.
6. Verify. OpenSpec's current /opsx:verify workflow checks implementation against change artifacts and is designed to report findings rather than block all progress automatically. [OPENSPEC-COMMANDS-20260724]
7. Update the changed layer. Revise the spec if agreed behavior changed, compound a reusable lesson if the work produced one, and rebuild structural facts for the new revision.

The order may loop. A structural query may reveal a hidden caller that changes the design. A prior solution may expose a missing scenario. When that happens, update the authoritative artifact before continuing rather than carrying an informal exception in the conversation.

Limits and Handoff Risks

Cross-layer references can look precise while being stale. A task may link to a requirement that was revised. A solution may name a removed path. A graph may cover main while implementation occurs on a release branch. Every handoff should carry stable artifact IDs, repository revision, review status, and source permissions.

Disagreement is normal and should be visible:

• spec versus code may mean incomplete implementation or obsolete intent;
• solution versus spec may mean a historical workaround conflicts with a new requirement;
• graph versus code may mean ingestion lag or extraction error;
• artifact dependency versus code dependency may be a category mistake.

OpenSpec documents a review process for checking change artifacts, and its verification workflow should be treated as evidence within a broader engineering review, not proof of runtime correctness. [OPENSPEC-REVIEW-20260724] [OPENSPEC-COMMANDS-20260724]

Privacy also crosses layers. A public spec should not make a private incident or repository relationship visible through a generated summary. Query-time permission checks, derived-data deletion, and audit logs are required when systems have different access models.

Finally, measure the composed workflow on matched tasks. Track missing scenarios, stale links, irrelevant retrievals, reviewer corrections, and time to verified evidence. Do not assert a universal token-saving percentage for the three-layer design.

FAQ

Which layer should be updated first?

Update the layer whose authoritative knowledge changed. If agreed behavior changes, revise OpenSpec before implementation proceeds. If only the code structure changed, rebuild the graph after the commit. If the work produced a reusable diagnostic or solution, compound that lesson after it has been validated. Cross-links should update after their targets are stable.

Can specs and graphs disagree?

Yes. A spec expresses intended behavior; a graph reflects extracted structure for a revision. Disagreement may indicate incomplete implementation, stale intent, ingestion lag, or an extraction error. Surface both sources and ask the responsible reviewer to classify the mismatch rather than automatically preferring one.

Who owns cross-layer review?

The change owner should coordinate it, with artifact-specific responsibility retained by spec reviewers, subsystem maintainers, and the platform team operating retrieval. Security and privacy owners should review cross-system permissions. No connector should erase those ownership boundaries.

What is OpenSpec for Claude Code?

OpenSpec is a spec-driven workflow that can expose slash commands and change artifacts to supported AI coding tools, including Claude Code configurations documented by the project. [OPENSPEC-OVERVIEW-20260724] It organizes change intent and work; it is not Claude Code memory or a code graph.

Conclusion

OpenSpec, Compound Engineering, and a proposed external code graph can form a coherent context architecture when their responsibilities stay narrow. OpenSpec owns agreed change artifacts. Compound Engineering preserves reviewed work learning. The graph supplies revision-aware structural candidates.

The composition is a design pattern, not an official integration. Make every handoff carry identity, revision, status, provenance, and permissions, then verify behavior in source code and tests. Clear boundaries make the three layers useful; blurred authority makes them dangerous.