Experimental

Spec Kit + Archcore

Plan features against existing decisions. Keep Spec Kit specs and tasks linked to Archcore records.

How Spec Kit + Archcore work together

Spec Kit + Archcore connects a feature’s spec and plan to the decisions your project already made. Spec Kit organizes the feature work. Archcore supplies the relevant decisions and keeps new decision records linked to the feature files.

Say a feature plan brings in a calculation method that contradicts an accepted decision. The agent shows you the conflict while the plan can still change, and records new decisions as drafts once you approve the design.

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

Archcore ↗
Keeps project decisions and rules in Git so your agent can check feature plans against them.
Spec Kit ↗
Guides work from project principles through a feature specification, implementation plan, tasks and code.

From a feature specification to checked implementation

The instructions ask your agent to:

  1. Read the principles and decisions

    The agent checks the feature spec and the Spec Kit constitution (the project's agreed principles) against Archcore decisions. If the constitution is missing or blank, it tells you.

  2. Review the plan, then link decisions

    Spec Kit keeps the spec, plan and design files, and you review them before any code. After you approve, the agent saves new decisions as draft ADRs (architecture decision records) linked to those files.

  3. Build and pick up later

    The agent follows Spec Kit's task list and keeps the plan's status lines current. A later session reads the feature files and records before it asks you anything again.

Spec Kit keeps the spec, plan and tasks; Archcore records point to those files.

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. Spec Kit: You keep integer cents, and the agent writes the spec and plan where Spec Kit expects them, marks open points as assumptions and waits for your review.

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

  4. Spec Kit: The agent works through the task list, runs the tests and updates the status lines in the plan.

  5. Agent: A new session answers from the saved files: 13 cents off and 612 cents total for one tea with SAVE10, plus where the documents disagree with the code.

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 Spec Kit

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

2. Add instructions

CLAUDE.md / AGENTS.md / GEMINI.md
### Archcore + Spec Kit

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 a Spec Kit workflow.
5. When an Archcore command leaves design or execution work open, pass its prepared inputs to the matching Spec Kit workflow.
6. When the user starts through Spec Kit, follow its installed constitution, specification, planning, task and implementation instructions.
7. Before planning a feature, call `search_documents` for relevant decisions and rules.
8. Compare the found records with the feature's specification and constitution.
9. Before any code edit, call `search_documents` on the affected area, including for a one-line change.
10. If the constitution is missing or still a template, report that state to the user.
11. If the constitution is missing or still a template, ask whether to establish it or use existing project rules.
12. When Spec Kit owns the feature, keep its specification, plan, design files and tasks in native locations, not in Archcore.
13. If an existing Archcore plan tracks the same tasks, report the overlap in the task result.
14. If an existing Archcore plan tracks the same tasks, keep that Archcore plan as written.
15. Before implementation, obtain the user's approval of the saved specification and design plan unless already given in the task.
16. After design approval, record newly settled architectural decisions as draft ADRs linked to the native feature artifacts by path.
17. Before recording a decision, call `search_documents` for an existing record.
18. When a design includes an assumption, keep it identified as an assumption until the user resolves it.
19. Create and update `.archcore/` records through Archcore's document tools.
20. Create every new `.archcore/**/*.md` record with status `draft`.
21. Set status `accepted` only after the user's explicit acceptance of that record in the task.
22. If the specification, constitution or proposed work conflicts with an accepted decision or rule, report the conflict to the user.
23. If the specification, constitution or proposed work conflicts with an accepted decision or rule, stop the affected work.
24. If a document carries `read_only: true`, name its owning project instead of writing to it.
25. If more than one writable `.archcore/` is present, confirm the target project before writing a record.
26. If the project has no `.archcore/`, do not call `init_project` without the user's request.
27. Before reporting completion, check code against the approved specification and contracts.
28. Report failed or unrun checks in the task result.
29. Mark native tasks complete only when their work and required checks are complete.
30. After implementation, reconcile status statements in the plan, research and checklists with the code and decision records.
31. In a new session, read the saved feature artifacts and Archcore decisions before repeating requirements questions.
32. For a read-only status request, report document disagreements and draft versus accepted decisions without changing records.
33. If a required input or contribution is missing, name it before proceeding with the work that needs it.
34. End a task that changed code or records with `Archcore: <records read or written>` or `Archcore: not used — <reason>`.
35. If another connected recipe conflicts with these instructions, report the conflict in the task result.
36. 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 Spec Kit, 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

Keep feature plans connected to project decisions.

You review a feature plan next to the decisions it must respect, and the reasons for new choices stay linked to the feature files.

A feature conflicts with an accepted decision

In both runs, the agent reported the conflict before planning and kept the accepted decision after the owner settled it.

The benchmark asked for the conflict check, and a filled-in constitution was not tested.

Specifications, tasks and decisions stay connected

Both runs kept the files where Spec Kit expects them and created linked draft ADRs, and the code passed all ten checks.

The plan still held stale claims about which records existed, which the revised text now checks.

Start with Archcore.

Keep your project decisions ready for the next task.

Spec Kit + Archcore

Source & verification

Category
Spec-driven development
Instruction revision
e69205d09d50
Source
Landing repository · src/recipes/spec-kit/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 a pinned Spec Kit snapshot.
  • A filled-in constitution, extensions and multi-feature work were not covered.
  • Nothing enforces the instructions. Review the tests, the documents 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.