Aigile with OpenSpec

The aigile kit referenced below is on the downloads page and at the kit repository; <kit-path> means your local clone of it.

OpenSpec has no plugin API, so this adapter is a composition: you keep OpenSpec’s delta-spec workflow (propose, apply, archive) and add the aigile layers on top. This tutorial shows the combined setup and one feature through it, using the same Taggr tagging example as the other tutorials. It assumes OpenSpec is already installed and initialized in your project per its own documentation; everything here is the aigile layer.

1. What you need

• A project with OpenSpec set up (its CLI and an AGENTS.md)
• Any coding agent that reads AGENTS.md
• The aigile kit, for its core commands and the fragment
• Windows: run shell snippets in Git Bash (ships with Git), or use the PowerShell equivalents noted in the kit’s docs/INSTALL.md

2. Install the aigile layer

Three steps:

mkdir -p .aigile/standards .aigile/domain .aigile/corpus .aigile/features
cat <kit-path>/adapters/openspec/AGENTS-fragment.md >> AGENTS.md

Then register the nine commands from <kit-path>/core/commands/ in your agent (as slash commands where supported, or keep them as prompt files you paste; every command marks its input with $ARGUMENTS). Write .aigile/constitution.md with your ground rules; the Taggr example constitution is in the SpecKit tutorial, section 3, and is identical here. OpenSpec’s own source-of-truth specs keep working; the fragment you appended tells agents how the two systems compose.

3. The mapping, in one view

4. Run the feature

Intent first, before any proposal. Run the intent command with the Taggr seed (see the other tutorials for the text). Tagging adds a user-facing surface, so the intent is FULL weight: the command elicits your primary scenario, made vs deferred decisions, and a sketch, then runs the readiness gate. A NOT READY intent produces no proposals; that ordering is the point, because OpenSpec makes proposing cheap and the gate is what keeps cheap from meaning thoughtless.

Slices become proposals. Run the slice command, then create one OpenSpec change proposal per slice, in slice order, skeleton first. Each proposal carries the one-screen spec as its content, including the Standards: and Domain: lines; agents applying the change load exactly those files plus the constitution.

Apply under the protocol. While a change is applied, the deviation rules from the fragment hold: behavioral findings stop the change and produce a deviation report; your decision’s spec fix lands in the same PR. Implementation details proceed and are logged.

Demo before archive. This is the one hard change to OpenSpec habits: applying and merging a change does not archive it. You drive the running slice, record the verdict with the verdict command, and only VALIDATED archives the proposal. Misaligned feedback becomes proposal updates before the session ends.

Retro and the prose problem. Close the feature with the retro command. Pay attention to its drift sweep here more than anywhere: OpenSpec’s archived changes merge into source-of-truth prose, and that prose is exactly the drift surface aigile warns about. Move behavior descriptions into the derived layer (a regeneration prompt instead of a maintained page) and keep only intent-level statements maintained.

5. Common early questions

• Why not just use OpenSpec’s flow as is? It has no intent gate, no demo verdicts, and no drift pipeline; proposals are cheap, which is a virtue exactly until it is not. The aigile layer adds the gates and keeps the archive honest.
• Do the aigile workflows run here? No; those are SpecKit artifacts. The gates are manual discipline in this composition, which works, but if you want machine-held gates, the SpecKit or Claude Code paths provide them.
• Can I migrate later? Yes, cheaply: everything aigile lives in .aigile/ as plain markdown, and both other adapters read the same layout.