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, specs and tasks together. Archcore gives the agent the decisions to check before it touches code, and a place to record new ones after you approve the design.

Say a request to simplify price math conflicts with an accepted rule about exact money arithmetic. The agent shows you the conflict during design, while you can still keep the rule or change it.

The pilot findings and instruction changes describe what was measured. Commands and installation are on the OpenSpec project page.

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 decisions before design

    The agent reads the relevant Archcore decisions and OpenSpec files first. If your request conflicts with an accepted decision, you settle it before work goes on.

  2. Review the proposal

    OpenSpec keeps the proposal, specs, design and tasks. You review the saved design; after you approve it, the agent records new decisions as draft ADRs (architecture decision records) linked to those files.

  3. Build, archive and pick up later

    The agent follows the OpenSpec tasks, syncs the specs and archives the change. A later session reads the specs and records and says which decisions are still drafts.

Both tools must already be set up. OpenSpec keeps the feature work; Archcore records link to it.

One request, start to finish

Request Introduce coupon discounts in this quotation library. Use floating-point arithmetic for the monetary intermediate values. Check existing project decisions and report any conflict before implementing.

  1. Archcore: The agent finds the accepted integer-cents decision, reports the conflict with the float request and stops before changing any file.

  2. OpenSpec: You keep integer cents, and the agent writes the proposal, design, specs and tasks in OpenSpec's folders, then waits for your review.

  3. Archcore: After you approve the design, its decisions become draft ADRs linked to the OpenSpec files.

  4. OpenSpec: The agent works through the tasks, runs the tests, syncs the specs and archives the change.

  5. Agent: A new session answers from the saved files: 13 cents off and 612 cents total for one tea with SAVE10, plus which decisions are still drafts.

This is what the instructions ask for, not a recorded run. An earlier revision completed this scenario twice; this one has not run yet.

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. A tool, skill, or command that the session shows only by name counts as loaded. An instruction naming only Archcore tools applies in any session with those tools.

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

A request conflicts with an existing decision

In both runs, the agent raised the conflict before changing code and kept the accepted decision once the owner settled it.

The benchmark asked for the conflict check, so detection without that prompt was not tested.

Picking up work in another session

A later session recovered the coupon behavior and told accepted decisions from drafts.

This was a scripted step in the same working tree, not proof for every later session.

Start with Archcore.

Keep your project decisions ready for the next task.

OpenSpec + Archcore

Source & verification

Category
Spec-driven development
Instruction revision
c0f36be31f87
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.

  • Experimental until this exact text is tested. The pilot used Claude Code 2.1.268, claude-opus-5[1m], Archcore 0.8.3 and an OpenSpec 1.13.0 snapshot.
  • Two runs of one scenario do not prove better code or lower cost.
  • Nothing enforces the instructions. Review the design, the code and the draft ADRs yourself.

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.