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 specification and implementation plan to the decisions already made in your project. Spec Kit organizes the feature work. Archcore supplies relevant decisions and keeps new decision records linked to the feature files.

For example, a feature plan may introduce a calculation method that contradicts an accepted project decision. The instructions ask the agent to surface the conflict while you can still change the plan. Once you approve the design, new architectural decisions are recorded as drafts for separate acceptance.

The instructions also address stale status statements found in the pilot’s plans and research. Read the pilot findings and instruction changes for the measured scope. For native commands and installation, see the Spec Kit project.

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 specification and Spec Kit constitution against relevant Archcore decisions. The constitution is the project's agreed set of principles. A missing or blank one is reported for your decision.

  2. Review the feature plan

    Spec Kit keeps the specification, plan and supporting design files. You review them before implementation, with conflicts and open assumptions made explicit.

  3. Link the new decisions

    After design approval, the agent checks for existing decisions before creating draft ADRs in Archcore. Each architecture decision record links to the native feature files and distinguishes approved choices from assumptions.

  4. Implement from the native tasks

    The agent follows Spec Kit's task list, checks code against the approved specification and contracts, and updates current status statements in the plan and research.

  5. Resume with the saved feature context

    A later session reads the feature files and decision records before repeating requirements questions. It reports unfinished work and separates draft decisions from accepted ones.

Spec Kit keeps the feature specification, plan and tasks. The integration asks Archcore to reference those files when recording decisions.

One request, start to finish

Request Introduce coupon discounts in this quotation library. Use floating-point arithmetic for the monetary intermediate values. Use the installed Spec Kit specify, plan, tasks and implement workflow. Check existing project decisions and report any conflict before implementing.

  1. Archcore: Before planning, the agent searches the project records and compares them with the request. It finds the accepted decision on integer cents, reports the conflict with the float request and stops. No file has changed.

  2. Spec Kit: You keep integer cents. The agent writes the specification and plan where Spec Kit expects them, marks open points as assumptions, and stops at the saved design for your review.

  3. Archcore: You approve the design. The decisions it settles become draft ADRs linked to the feature files by path. The money decision stays as it was.

  4. Spec Kit: You ask for the implementation. The agent works through the task list, runs the tests, and brings the status lines in the plan and research up to date with the records that now exist.

  5. Agent: A new session reads the feature files and the decision records and answers from them: the coupon contract, 13 cents off and 612 cents total for one tea with SAVE10, and 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 in Claude Code with a blank constitution; see the pilot note. This revision has not had a joint run.

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 can review the proposed implementation alongside existing decisions, then keep the reasons for new choices linked to the feature files as work proceeds.

A feature conflicts with an accepted decision

In both pilot runs with the earlier recipe, the agent reported the conflict before planning or implementation and preserved the accepted decision after the owner's resolution.

The benchmark explicitly requested the conflict check. Both runs used project instructions and the accepted ADR because the constitution was blank.

Specifications, tasks and decisions stay connected

Both runs kept feature files in Spec Kit's native locations and created linked draft ADRs in Archcore. Code passed the benchmark's six primary and four additional contract checks.

Plan and research sections still contained stale claims about which records existed. Passing code tests did not make those documents consistent.

A later session reviews the result

The recorded recall answers recovered the coupon behavior, draft ADR status and document disagreements from the saved feature work.

Some assumptions had been described as settled decisions. The revised instructions explicitly separate assumptions from owner approval.

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.

  • 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 a pinned Spec Kit runtime snapshot documented in the pilot note.
  • Two repetitions of one scripted feature do not establish better code, lower cost or compatibility across repositories and agents.
  • A populated constitution, extensions, multi-feature work and additional planning tools were not covered by this pilot.
  • The instructions rely on the agent following them. Review remains necessary for tests, document consistency and decision approval.

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.