archcore
Star Install
Menu
Experimental

OpenSpec + Archcore

Check proposed changes against project decisions. Keep specs and archives in OpenSpec.

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 for the measured scope. For the native change process and installation, see the OpenSpec project.

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.

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.

See benefits and limits →

Connect the two tools

1. Install Archcore and OpenSpec

Install Archcore and OpenSpec in the agent you use for this project.

2. Add instructions

CLAUDE.md / AGENTS.md / GEMINI.md 
### Archcore + OpenSpec

Applies when both contributions are loaded. An instruction naming only Archcore tools applies in any session with those tools.

1. When the user names a skill or `/archcore:*` command, load and follow its own instructions.
2. When an `/archcore:*` command is invoked, let it finish before starting an OpenSpec workflow.
3. When an Archcore command leaves design or execution work open, pass its prepared inputs to the matching OpenSpec workflow.
4. When the user starts through OpenSpec, follow its installed proposal, application, synchronization and archive instructions.
5. Before designing an OpenSpec change, call `search_documents` for relevant decisions and rules.
6. When OpenSpec owns the change, keep its proposal, specs, design and tasks in their native locations instead of creating copies in Archcore.
7. If an existing Archcore plan tracks the same tasks, report the overlap and keep that plan as written.
8. Before implementing a change, obtain the user's approval of the saved design unless already given in the task.
9. After design approval, record newly settled architectural decisions as draft ADRs linked to the OpenSpec artifacts by path.
10. Before recording a decision, call `search_documents` for an existing record.
11. When a design includes an assumption, keep it identified as an assumption until the user resolves it.
12. Create and update `.archcore/` records through Archcore's document tools.
13. Create every new `.archcore/**/*.md` record with status `draft`.
14. Set status `accepted` only after the user's explicit acceptance of that record in the task.
15. If the change conflicts with an accepted decision or applicable rule, report the conflict and stop the affected work for the user's decision.
16. If a document carries `read_only: true`, name its owning project instead of writing to it.
17. If more than one writable `.archcore/` is present, confirm the target project before writing a record.
18. If the project has no `.archcore/`, do not call `init_project` without the user's request.
19. Before reporting completion, check code against the approved specs and report failed or unrun checks.
20. Before closing the change, reconcile task status and statements about decision records with the work actually completed.
21. When the user authorizes closing the change, synchronize and archive through OpenSpec, then check the resulting spec and archive paths.
22. If an artifact moves, update references in the records you maintain without changing unrelated decisions or their status.
23. In a new session, read the saved OpenSpec artifacts and Archcore decisions before repeating requirements questions.
24. For a read-only status request, report document disagreements and draft versus accepted decisions without changing records.
25. If a required input or contribution is missing, name it before proceeding with the work that needs it.
26. If another connected recipe conflicts with these instructions, report the conflict and preserve that recipe's applicable contribution.

3. Check in a new session

Start a new session in this project and ask your agent:

Confirm you can use Archcore and OpenSpec, and have read this project’s cooperation instructions.

If the agent reports a missing tool or instruction file, finish that setup before starting work.

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.

Start with Archcore.

Keep your project decisions ready for the next task.

Install Archcore →See how it works

OpenSpec + Archcore

Source & verification

Category
Spec-driven development
Instruction revision
aaeec535cc71
Source
Landing repository · src/recipes/openspec/cooperation.md · This revision is not published yet.
Maintainer
Archcore maintainers
Page updated
September 12, 2026

Verification

No joint run has been recorded for this instruction revision.

  • 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.

Update or disconnect

To update, review changes to the instructions before replacing your copy. To disconnect, remove the added instructions from your project file. Both tools and their documents stay in place.