Multi-Sites

A Spec Kit community extension that brings multi-site awareness to the Spec Kit workflow using just three commands: setup, specify, and continue.

Overview

In multi-site projects (Drupal, custom frameworks, monorepos with multiple web apps) each website is an independent scope. This extension provides a guided, site-aware workflow that:

1. Auto-detects the sites folder from your project structure (e.g. docroot/sites for Drupal, or generic sites/ folders).
2. Asks which site (or core) the spec belongs to, listing all detected websites.
3. Keeps auto-increment numbers separate per scope, checking both local folders and remote git branches for the next available number.
4. Supports two spec organisation modes with different file placement and naming strategies.
5. Carries a feature all the way through clarify → plan → tasks → implement with a single command, asking after each step whether to keep going or pause.
6. Tracks all configuration in one place — the sites folder, spec mode, and every feature's current workflow stage all live in a single project config file, so nothing needs to be re-detected or guessed from the filesystem on later runs.

Commands

Command	Purpose
speckit.multi-sites.setup	One-time project setup — detect/confirm the sites folder and choose a spec organisation mode
speckit.multi-sites.specify	Create a new spec in the correct site or core folder with auto-incremented numbering
speckit.multi-sites.continue	Pick up a spec wherever it was left off and run the next step: clarify, plan, tasks, or implement

All three commands read from and write to the same single config file — see Configuration below.

How continue works

continue is a state machine. Every feature created by specify is registered in the shared config file with a stage field — the last completed phase. continue reads that field to know exactly what to run next:

stage: specify   → Clarify   (resolve gaps/ambiguities in the spec)
stage: clarify   → Plan      (generate plan.md)
stage: plan      → Tasks     (generate tasks.md)
stage: tasks     → Implement (write the code, check off tasks)
stage: done      → suggests review, test, commit, push

After each phase it updates the stage field and asks: continue now to the next phase, or stop here and resume later by running /speckit.multi-sites.continue again. Implementation is the last phase — instead of offering to continue, it tells you to review, test, and then commit/push yourself (it never commits or pushes on your behalf). Because every feature's target and stage are already known from the config, continue never asks which site a spec belongs to — it just lists every feature that isn't done yet (across all sites and core) and lets you pick one.

Spec Modes

Targeted Specs

Each website has its own specs/ folder inside its directory. Core specs go in a root-level specs/ folder. Every feature is placed in its own folder starting with the spec number, and uses clean filenames like spec.md and plan.md inside.

specs/
  001-feature-a/
    spec.md                     ← core specs
    plan.md
    tasks.md
docroot/sites/
  websiteA/
    specs/
      001-login/
        spec.md                 ← websiteA specs
        plan.md
  websiteB/
    specs/
      001-homepage/
        spec.md                 ← websiteB specs

Auto-increment counters are fully independent: adding a spec to websiteB never affects websiteA or core counters.

Single Specs

All specs share one root-level specs/ folder, split into a sub-folder per target (site name, or core). Each target's counter is independent. Inside each feature folder, files use clean names like spec.md and plan.md.

specs/
  core/
    001-auth/
      spec.md
      plan.md
  websiteA/
    001-login/
      spec.md
      plan.md
  websiteB/
    001-homepage/
      spec.md

The difference from Targeted specs is purely where the per-target folder lives: Targeted keeps it inside the website's own directory tree; Single keeps every target's folder centralised under one root specs/ folder.

Installation

specify extension add multi-sites --from https://github.com/teeyo/spec-kit-multi-sites

Or install from a local checkout during development:

specify extension add multi-sites --from /path/to/multi-sites --dev

Known: installer creates symlinks

The specify extension add command installs extensions using ln -s (symlinks) rather than copying files. This means the extension resolves at runtime through the symlink, which is normally fine — but if the global Spec Kit store is cleaned up, updated, or moved, the symlink may break silently.

This behaviour repeats on every update or reinstall. If you find commands fail to load after an update, replace the symlink with a real copy:

# Run from the project root
EXT_DIR=".specify/extensions/multi-sites"
cp -rL "$EXT_DIR" "${EXT_DIR}-copy"
rm "$EXT_DIR"
mv "${EXT_DIR}-copy" "$EXT_DIR"

Tip: If you want real files from the start, install from a local checkout with --dev (see above) and then copy the folder manually — the --dev flag already resolves to your local path, so a plain cp -r of the checkout is sufficient.

Usage

In your AI coding agent's chat, run the three commands in order:

/speckit.multi-sites.setup      (once per project)
/speckit.multi-sites.specify    (once per feature)
/speckit.multi-sites.continue   (as many times as needed, per feature)

---

/speckit.multi-sites.setup — first run only

A quick-pick shows the auto-detected sites folder. Confirm it or choose "Enter manually" to type a custom path.

Which folder contains your website sub-folders?
❯ docroot/sites   (Auto-detected)
  Enter manually

On a Drupal project the command detects docroot/sites automatically. On a generic multi-site setup it may detect sites/, apps/, tenants/, etc.

Then choose how specs are organised across sites:

How would you like to organise your specs?
❯ Targeted specs   Each site has its own specs/ folder with independent numbering
  Single specs     All specs share a root specs/ folder, split into a per-site sub-folder

Both choices are persisted to .specify/extensions/multi-sites/multi-sites-config.yml so you are never asked again (re-run setup any time to change them).

---

/speckit.multi-sites.specify — once per feature

Target site — pick the site (or core) this spec belongs to, built from sub-directories found inside your sites folder:

Where should this spec be created?
❯ core            Shared core feature — top-level, applies to all websites
  website-alpha   docroot/sites/website-alpha
  website-beta    docroot/sites/website-beta
  website-gamma   docroot/sites/website-gamma

Feature name — a name is suggested from your request; accept it, or type your own (spaces are converted to hyphens automatically):

What is the name of this feature?
❯ password-reset          Suggested from your request
  (type your own instead)

Confirmation — review the computed path and branch name before anything is written to disk:

Ready to create the spec — confirm the details below:
Mode: targeted | Target: website-alpha | Folder: docroot/sites/website-alpha/specs/001-user-authentication | Branch: 001-user-authentication

❯ Create spec
  Cancel

Spec created, then you're asked what to do next:

✅ Spec created successfully!

File:   docroot/sites/website-alpha/specs/001-user-authentication/spec.md
Target: website-alpha
Mode:   targeted

What would you like to do next?
❯ Continue now — clarify this spec
  Stop here — I'll continue later

Choosing "Continue now" immediately kicks off the continue workflow (see below) without needing to type another command.

---

/speckit.multi-sites.continue — repeat until done

No site/target question — every feature already knows its own target from the config, so you're taken straight to a list of everything still in progress (stage not yet done):

Which feature would you like to continue?
❯ website-alpha/001-user-authentication   Stage: clarify
  core/001-billing-export                 Stage: tasks

Each run then executes exactly one phase for the selected feature, updates its stage, and offers to keep going:

✅ Spec clarified!
What would you like to do next?
❯ Continue now — plan
  Stop here — I'll continue later

✅ Plan created!
What would you like to do next?
❯ Continue now — tasks
  Stop here — I'll continue later

✅ Tasks file created!
What would you like to do next?
❯ Continue now — implement
  Stop here — I'll continue later

✅ Implementation complete!

Next step: Review your changes and run the project's tests.
Once everything looks good, commit and push your changes.

Folder Detection

The extension scans the project root and applies these rules in order:

Pattern	Framework
docroot/sites/	Drupal (composer-based)
web/sites/	Drupal (alternative layout)
sites/	Drupal (legacy), generic CMS
webs/, domains/, tenants/, apps/, vhosts/	Generic multi-site setups

If no sites folder is detected automatically, you will be prompted to enter the path manually.

Configuration

Copy the template to create your project config:

cp .specify/extensions/multi-sites/multi-sites-config.template.yml \
   .specify/extensions/multi-sites/multi-sites-config.yml

Available options:

Key	Default	Description
sites_folder	(auto-detect)	Override the sites folder path
spec_mode	(ask every time)	Lock in targeted or single
excluded_sites	["all", "default"]	Site sub-directories to ignore
features	[]	Auto-managed by specify/continue — tracks every spec's id, target, folder, branch, and current workflow stage (with created/updated timestamps). You don't need to edit this by hand.

This one file is the only place Multi-Sites stores state: project settings and per-feature workflow progress both live here, so there's nothing else to configure or keep in sync.

Spec Template

Every generated spec follows the standard Spec Kit structure:

• Overview — what the feature does and why it exists
• Goals / Non-Goals — scope boundaries
• User Stories — role-based requirements
• Acceptance Criteria — testable checkboxes
• Technical Notes — constraints and architectural decisions
• Open Questions — items to resolve before implementation
• References — links to related specs, tickets, designs

License

MIT — see LICENSE