# OpenSpec + Archcore

> Connect OpenSpec + Archcore to check changes against project decisions, keep specs in OpenSpec, and carry decision context into the next session.

Instruction revision: aaeec535cc719a655f00493b3dd92faa15eb434fc50302def967ec9e0ff3e95c
Instruction text: https://archcore.ai/integrations/openspec/cooperation.md
Source: https://github.com/archcore-ai/landing — src/recipes/openspec/cooperation.md (unpublished)

## Tools

- Archcore — Keeps project decisions and rules in Git so your agent can check proposed changes against them.
- OpenSpec — Organizes each change through its proposal, specifications, design, tasks and archive.

## How OpenSpec + Archcore work together

OpenSpec + Archcore connects a proposed change to the project decisions behind it.
OpenSpec keeps the proposal, design, specifications and tasks together. Archcore
gives the agent relevant decisions to check before changing the code and a place
to record new decisions after you approve the design.

For example, a request to simplify price calculations might conflict with an
accepted rule about exact money arithmetic. The agent brings that conflict to you
during design. You can keep the existing rule or explicitly change the decision
before implementation proceeds.

The instructions below build on a small pilot and address gaps found in its saved
records. Read the [pilot findings and instruction changes](/integration-evidence/2026-09-11-spec-workflows.md)
for the measured scope. For the native change process and installation, see the
[OpenSpec project](https://github.com/Fission-AI/OpenSpec).

## From a proposed change to a saved decision

The instructions ask your agent to:

1. **Check the project before design.** The agent reads relevant Archcore decisions and OpenSpec artifacts. If your request conflicts with an accepted decision, you resolve that conflict before the affected work continues.
2. **Review one change proposal.** OpenSpec keeps the proposal, specs, design and task list. You review the saved design before implementation.
3. **Record the reasons behind the design.** After your approval, the agent checks for existing decisions and records new architectural decisions as draft ADRs in Archcore, linked to the OpenSpec files. An ADR is an architecture decision record; accepting it is a separate decision.
4. **Implement, check and archive.** The agent follows the OpenSpec tasks and checks the result against the requirements. When you authorize closing the change, it synchronizes specs, archives the change and updates references to moved files.
5. **Continue from saved context.** A later session reads the current specs, archived change and decision records. It reports what is complete, which decisions remain drafts and where the records disagree.

Use this recipe for a project already set up with both tools. OpenSpec keeps the feature work; Archcore records link to it.


## Benefits & limits

### Review changes with their project context.

You get a proposal to review alongside the decisions it must respect. The instructions also preserve the reasons behind new decisions for later work.

### A request conflicts with an existing decision

In both pilot runs with the earlier recipe, the agent raised the conflict before changing code and preserved the accepted decision after the owner resolved it.

The benchmark explicitly asked for a conflict check and supplied the owner's resolution. It did not test detection without that prompt.

### One home for specifications and tasks

Both runs produced native OpenSpec artifacts, synchronized the current specification and archived the change. New Archcore decision records remained drafts.

Saved records still had gaps, including stale references to whether ADRs existed. The revised instructions add a check for those statements.

### Picking up work in another session

The recorded recall answers recovered the coupon behavior and distinguished accepted from draft decisions. They also identified disagreements in the saved documents.

This was a scripted recall step in the same working tree. It does not prove that every later session will recover all context.

### Limits

The earlier recipe completed one coupon-change scenario twice in Claude Code. This revised instruction text has not had a joint run. The pilot does not establish better code, lower cost or reliable behavior across projects and agents.


## Known limits

- The published instructions are a revision of the measured recipe. They remain experimental until this exact text is tested.
- The pilot used Claude Code 2.1.268, model identifier claude-opus-5[1m], Archcore 0.8.3 and an OpenSpec 1.13.0 snapshot. Other hosts and tool revisions were not tested.
- Both recipe runs passed the benchmark's six primary checks and four additional contract checks. Passing those checks does not establish complete correctness.
- The pilot used explicit design and implementation approvals. The instructions cannot enforce approvals or document consistency outside the agent's behavior.
- This pair only. Adding another planning tool needs a separate compatibility check.