archcore
Star Install
Menu
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.

See benefits and limits →

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. 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 a Spec Kit workflow.
3. When an Archcore command leaves design or execution work open, pass its prepared inputs to the matching Spec Kit workflow.
4. When the user starts through Spec Kit, follow its installed constitution, specification, planning, task and implementation instructions.
5. Before planning a feature, call `search_documents` for relevant decisions and rules and compare them with its specification and constitution.
6. If the constitution is missing or still a template, report that state and ask whether to establish it or proceed with existing project rules.
7. When Spec Kit owns the feature, keep its specification, plan, supporting design files and tasks in their native locations instead of creating copies in Archcore.
8. If an existing Archcore plan tracks the same tasks, report the overlap and keep that plan as written.
9. Before implementation, obtain the user's approval of the saved specification and design plan unless already given in the task.
10. After design approval, record newly settled architectural decisions as draft ADRs linked to the native feature artifacts by path.
11. Before recording a decision, call `search_documents` for an existing record.
12. When a design includes an assumption, keep it identified as an assumption until the user resolves it.
13. Create and update `.archcore/` records through Archcore's document tools.
14. Create every new `.archcore/**/*.md` record with status `draft`.
15. Set status `accepted` only after the user's explicit acceptance of that record in the task.
16. If the specification, constitution or proposed work conflicts with an accepted decision or applicable rule, report the conflict and stop the affected work for the user's decision.
17. If a document carries `read_only: true`, name its owning project instead of writing to it.
18. If more than one writable `.archcore/` is present, confirm the target project before writing a record.
19. If the project has no `.archcore/`, do not call `init_project` without the user's request.
20. Before reporting completion, check code against the approved specification and contracts and report failed or unrun checks.
21. Mark native tasks complete only when their work and required checks are complete.
22. After implementation, reconcile current status statements in the plan, research and checklists with the code and decision records that now exist.
23. In a new session, read the saved feature 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 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.

Install Archcore →See how it works

Spec Kit + Archcore

Source & verification

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