Aigile with SpecKit

Install the extension, preset, and workflow, then run one feature through the gated loop.

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

This tutorial takes you from installation to your first sealed feature using the aigile extension, preset, and workflow for GitHub Spec Kit. It uses one small example throughout: a notes app called Taggr gets a tagging feature. Expect one to two hours for the full pass, most of it real work on the feature.

1. What you need

  • Spec Kit 0.9 or later (pip install specify-cli, or per its docs)
  • A coding agent integration Spec Kit supports (Claude Code, Copilot, Gemini, or opencode)
  • The aigile kit repository, cloned locally or referenced from its catalog entry
  • 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

From your project root (a Spec Kit project; run specify init first if it is a fresh repository):

specify extension add <kit-path>/adapters/speckit/extension/aigile
specify preset add    <kit-path>/adapters/speckit/preset/aigile

Verify:

specify extension list

You should see aigile ... Commands: 9 ... Enabled. The extension adds the nine loop commands. The preset replaces two stock commands, speckit.constitution and speckit.specify, with aigile flavors; the other stock commands remain installed, but in an aigile project you will not use the specify-plan-tasks-implement pipeline.

3. Set up the durable layer

Run the constitution command in your agent (in Claude Code it appears as /speckit.constitution, in other integrations under the same name) and give it your ground rules. For Taggr, a first constitution is five clauses:

Version: 1.0.0
C-01 Notes are never deleted by tag operations.
C-02 All list views respond under 200 ms at 10k notes.
C-03 The web UI works without JavaScript for reading.
C-04 SQLite is the only datastore (ADR-0001).
C-05 Amendment: PR with rationale; maintainer decides in 48h.

Every clause passes the admission test: violating it should stop work. Conventions that do not pass the test (naming, error handling, test layout) go to .aigile/standards/<area>.md, one screen each. Business facts that span features go to .aigile/domain/<topic>.md. Create the folders now, even if they start nearly empty:

mkdir -p .aigile/standards .aigile/domain .aigile/features

4. Run the feature, gated

The workflow runs the whole loop with its human gates:

specify workflow run <kit-path>/adapters/speckit/workflows/aigile-feature/workflow.yml

It prompts for the intent. Give it the light-form seed:

A note taker wants to group notes with tags so that related notes can
be found together. Success: she tags three notes and finds them again
through the tag. Out of scope: sharing, tag colors.

What happens next, step by step:

  1. Intent. The intent command drafts the artifact and, because this adds a user-facing surface, classifies it FULL weight. It will interview you for the primary scenario, made vs deferred decisions, and a sketch reference. Answer in your own words; the command is built to challenge you, not to invent for you.
  2. Readiness gate. The workflow pauses. If you can walk your scenario, choose ready. If not, choose not-ready: the workflow routes back through the intent command with your open questions, which is the cheap place to discover the feature was half-thought.
  3. Slice. The slice command proposes vertical slices. For Taggr, expect something like: S1 skeleton (add one tag to one note and see it on the note), S2 filter notes by a tag, S3 remove a tag, S4 tag management (rename, merge). Reject anything sliced by layer.
  4. Spec and gate. Slice 1 gets a one-screen spec with Standards: and Domain: lines and mostly [test] criteria. The gate asks the one-sitting question: does this spec alone let you verify the right thing will be built?
  5. Build and the deviation check. The agent builds tests-first. If it reports a BEHAVIORAL deviation, choose deviation at the gate; the andon command presents options and you decide inside the time budget. The spec fix ships in the same PR as the code.
  6. Skeleton demo. The workflow stops and tells you to drive the running slice yourself. Do it literally: add a tag, look at the note. Record the verdict at the gate; a misaligned choice routes your feedback into spec changes before you continue.
  7. Remaining slices. The workflow loops: spec, gate, build, and a per-slice gate where you also flag risk-demo for anything that touched a constitution clause.
  8. Feature demo and retro. You drive the full walkthrough, choose the verdict (validated, misaligned, or intent-evolved), and the retro command routes the learnings: system facts to spec changes, collaboration lessons to .aigile/corpus/, drift findings to triage.

You can also run every command manually (/speckit.aigile.intent, .slice, .spec, .build, .andon, .verdict, .retro) without the workflow; the workflow only adds the gates and the pause/resume.

5. Where things landed

.aigile/
  constitution.md              (or .specify/memory/constitution.md)
  standards/  domain/  corpus/
  features/tags/
    intent.md   slices.md
    slices/1-spec.md ...       verdicts/  deviation-log.md

Every PR body carries the constitution stamp (run core/scripts/stamp.sh to print it); the stamp-check CI workflow in ci/github/ enforces it if you install it.

6. Common early questions

  • Can I still use /speckit.plan and /speckit.tasks? They are installed but unused here; the slice spec is the planning artifact, and reintroducing the pipeline reintroduces its failure shape.
  • The workflow feels heavy for a tiny fix. It is. Small changes go through the commands directly, or through nothing but the atomic PR rule; the workflow earns its gates on features.
  • Where do I see drift? Run /speckit.aigile.conformance at your retro, or install ci/github/conformance.yml once the retro ritual keeps finding real drift.