speckit-launch

One command to launch a GitHub Spec Kit project with mainstream AI agent integrations and a shared canonical .agents/skills tree.

Works on Windows, macOS, and Linux. Not locked to one coding agent or OS.

Why

Official init sets up one agent:

specify init <name> --integration copilot --script sh --non-interactive

This launcher installs the mainstream set in one step, consolidates speckit-* skills into .agents/skills, creates junction/symlink mounts, updates .gitignore, and overlays a chained Spec Kit pipeline (clarify / analyze as real steps; pause only when those steps still have issues).

Prerequisites

Node.js (18+)
specify on PATH, or uv (the CLI installs specify-cli via uv tool install if needed)
git (unless you pass --no-git)

Spec Kit compatibility

This launcher uses whatever specify is on PATH. It does not vendor Spec Kit skills or pin a CLI in package.json.

Line endings are LF in this repo and in generated projects (.gitattributes: * text=auto eol=lf), so Windows core.autocrlf does not split diffs or break shebangs.

	Version
Supported	Spec Kit >=1.0.0 <2.0.0 (`specify workflow overlay`, overlay path `.specify/workflows/overlays/`)
Last smoke-tested	1.0.4 (2026-09-08)
Newer 1.x	warning, then continue
<1.0.0 or >=2.0.0	init and upgrade refuse

Init checks specify --version. Upgrade checks that and .specify/init-options.json speckit_version (the version that wrote the project). A missing specify on PATH does not block upgrade — the command does not call it — but a too-old or untested-major project version does. Dev suffixes compare as the numeric triple (1.0.6.dev0 is 1.0.6).

The chained-SDD overlay is written against the bundled speckit workflow step ids (specify, review-spec, plan, review-plan, tasks, implement). A newer CLI that renames those ids needs an overlay edit — see After upgrading the specify CLI.

Quick start

git clone https://github.com/timoyan/speckit-launch.git
node speckit-launch/bin/new-project.mjs my-app

# Init the current directory
node speckit-launch/bin/new-project.mjs --here

# Custom parent and script type
node speckit-launch/bin/new-project.mjs my-app --dir ~/projects --script sh

Default installs these Spec Kit integrations:

copilot, claude, cursor-agent, gemini, grok, codex, agy

No --ai flag needed. Use --only <integration> only if you want a single agent.

Local link and global usage (`npm link`)

If you clone this repository and want to run speckit-launch or npx speckit-launch from any directory:

cd speckit-launch
npm run link          # equivalent to npm link

Once linked, create new projects from any working path:

npx speckit-launch my-app
# or directly:
speckit-launch my-app

To unlink later:

npm run unlink        # equivalent to npm unlink -g speckit-launch

Flags

Flag	Description
`--here`	Initialize in the current directory (or `--dir` if set)
`--dir <path>`	Parent directory for `<name>`, or target path with `--here`
`--primary <agent>`	Set the primary/default AI agent (e.g. `agy`, `claude`, `cursor-agent`) while installing all mainstream integrations
`--only <agent>`	Install only this Spec Kit integration (skip the mainstream set)
`--non-interactive`	Skip interactive prompt and use auto-detected defaults
`--script sh\|ps\|py`	Helper script type (default: `ps` on Windows, `sh` elsewhere)
`--no-git`	Skip `git init` and the Spec Kit git extension (no feature-branch hook)
`--version`, `-v`	Print version
`--help`	Show usage

In an interactive terminal, if --primary is not specified, the launcher auto-detects CLIs on PATH and presents an interactive menu to choose your primary agent. Named projects are created under the current working directory unless --dir is set.

What it does

Ensures specify is available (uv tool install specify-cli if needed)
git init (optional; skipped with --no-git)
specify init for the first integration (with --extension git unless --no-git), then specify integration install --force for the rest of the mainstream set (including agy) (or only --only if set). The git extension registers hooks.before_specify → speckit.git.feature, so /speckit-specify creates and checks out a feature branch before writing the spec. Spec Kit 1.0+ does not do that unless the extension is installed.
Dedupes speckit-* skills into .agents/skills and applies production-tested enhancements:
- Immediate Clarify Persistence: Candidate questions and default recommendations written directly into spec.md with interactive checkboxes.
- Actionable analysis.md Audit Report: Structured findings table and user-editable remediation checklist (- [x] R...).
- Auto-Remediation in Implement: Automatically applies checked items from analysis.md to spec.md / plan.md / tasks.md before coding.
- Clean Converge with Auto-ADR & Living Spec: Distills architectural decisions to docs/adr/, flattens completed features into high-signal living specs (specs/<id>-<name>.md), and cleans transient files.
Writes .agents/skills.json and .agents/AGENTS.md (chained pipeline rules, remediation workflow, and model routing)
Writes .cursor/rules/speckit-pipeline.mdc and installs .specify/workflows/overlays/speckit/chained-sdd.yml with interactive gates (review-clarify and review-analyze) configured with on_reject: retry to prevent fatal aborts
Installs the local chained-sdd preset (specify preset add --dev) so /speckit-constitution appends the pipeline principle. Also seeds an unfilled constitution.md. Does not copy another project's filled constitution. Not published to a Spec Kit catalog.
Creates multi-agent bridge pointer files (CLAUDE.md, .cursorrules, .github/copilot-instructions.md) pointing to .agents/AGENTS.md and merges pipeline pointers into any existing agent docs (AGENTS.md, CLAUDE.md, GEMINI.md, .cursorrules, .github/copilot-instructions.md) for zero-config multi-IDE discovery
Copies and runs scripts/link-agent-skills.mjs (Windows junction / Unix symlink)
Merges skill-mount rules and local extension/credential patterns into .gitignore
Writes or merges .gitattributes (* text=auto eol=lf, plus explicit text/binary hints) so generated projects keep LF on Windows / macOS / Linux
If missing, copies optional process starters into .agents/rules/ (every agent) and a Cursor alwaysApply mirror under .cursor/rules/. Also copies the commit-push-pr skill and a generic dangerous-command hook. Fill {{GITHUB_REPO}} and the three commit-check commands in .agents/rules/. A docs-only CI ignore snippet lives at templates/github/ci-paths-ignore.snippet.yml — paste it under on.push only; do not put it on pull_request, and do not add [skip ci] to a PR tip.
If missing, copies React / Next.js role prompts to agent-roles/react-reviewer.md, agent-roles/react-implementer.md, and agent-roles/react-checker.md. They are not tied to a particular agent. Each file declares a Scope. After implement, match checkers and reviewers to changed files (a mixed diff runs every match). Versions do not choose the role: after a match, read the versions that Scope names and judge against those. Review and implement follow that project's state and CSS libraries. The checker runs the project's own typecheck, lint, and test commands (Biome, Oxlint, ESLint, or whatever is configured). Starting panes is still manual (node scripts/start-herdr-roles.mjs --kind <agent>). After implement, the coordinator dispatches to live matching role agents (checker → reviewer → implementer for Blocking). If no live pane, it applies the role files itself. It does not auto-start panes and does not pick roles from the diff. One session, one pane per role file. --kind is required. --only limits which files start. Existing live agent names are skipped.

node scripts/start-herdr-roles.mjs --kind agy
node scripts/start-herdr-roles.mjs --kind agy --only react-checker,react-reviewer
herdr session attach speckit-<repo>

It does not copy another project's product constitution, changelog entries, deploy commands, or CI job body. After bootstrap, run /speckit-constitution in the new project (keep the seeded pipeline principle; fill the rest for this product).

Spec Kit pipeline (from production use)

Official Spec Kit treats clarify / analyze / checklist as optional quality gates, and the bundled workflow inserts unconditional “review the spec / plan” stops.

This launcher overlays the production chained run used in real Spec Kit repos:

specify → clarify → review-clarify [gate] → plan → tasks → analyze → review-analyze [gate] → implement → review-code [gate] → converge

Step	Default behavior
After specify	Always run clarify (do not jump to plan)
After clarify	Questions and default recommendations persisted to `spec.md`. `review-clarify` pauses with `on_reject: retry`. Unanswered questions or failing checklists → Pause; clean → continue to plan
After plan	Always run tasks
After tasks	Always run analyze
After analyze	Analysis report written to `analysis.md`. `review-analyze` pauses for checklist inspection. Zero findings or only LOW → continue to implement
During implement	Step 2.5 auto-applies checked remediations from `analysis.md` before executing tasks
After implement	Stop at `review-code`. Do not run converge yet. Match `agent-roles/-checker.md` and `-reviewer.md` to changed files by Scope (more than one may match). Read the versions that Scope names. If inside Herdr and those named agents are live, prompt them (checker then reviewer; implementer only for Blocking). Do not auto-start panes. Otherwise apply the matching role files locally. Apply Blocking first
After review-code	User proceeds, then run converge. If tasks were appended, implement then converge again (stop when converged, or after 3 passes). When converged: auto-extracts ADR, consolidates living spec, and cleans transient files

A single slash command (/speckit-plan only, …) does not start the chain. /speckit-checklist stays optional and is not in the default chain.

Overlays written into the new project:

.agents/AGENTS.md — canonical pipeline + autonomy rules + remediation / ADR converge workflow
.cursor/rules/speckit-pipeline.mdc — Cursor alwaysApply copy of the pause rules
.specify/workflows/overlays/speckit/chained-sdd.yml — Spec Kit 1.0 overlay: inserts clarify / analyze / converge, with non-destructive retry gates. If specify workflow overlay list speckit does not already show chained-sdd enabled, --apply runs specify workflow overlay add <src> --priority 10 first (dry-run does not). Failure copies the file. Official workflow.yml stays upgradable.
chained-sdd preset — appends the Autonomy & Spec Kit pipeline principle onto constitution-template (local --dev install; not a catalog release). Unfilled constitution.md is seeded the same way.

Model & capability tier routing

Because Spec Kit decouples stages via disk artifacts in specs/<feature>/, you can route stages across models and agents based on strengths across any AI tool (AGY, Claude Code, Cursor, Copilot, Aider, Herdr):

Stage	Capability Tier	Recommended Model Classes	Primary Purpose
`specify` / `clarify`	High reasoning / Thinking (CoT)	`gemini-3.1-pro` / `claude-3-7-sonnet` (thinking) / `o3-mini` / `r1`	Uncovers hidden constraints, edge cases, and ambiguities early
`plan`	Architectural reasoning	`gemini-3.1-pro` / `claude-3-7-sonnet` / `o3-mini`	Solid system boundaries, data contracts, and dependency planning
`tasks`	Structured decomposition	`gemini-3.8-flash` / `claude-3-5-haiku` / `gpt-4o-mini`	Generates clean, dependency-ordered, actionable task graphs
`analyze`	Large context / Deep verification	`gemini-3.1-pro` / `claude-3-7-sonnet` / `o3-mini`	Whole-repo consistency and spec vs code audit without context loss
`implement` / `converge`	Fast, high-throughput coding	`gemini-3.8-flash` / `claude-3-5-sonnet` / `gpt-4o`	Rapid code writing, test-driven loops, and convergence passes

Multi-Agent / Subagent-Capable Environments (AGY, Claude Code Task, Herdr multi-pane):
- specify / clarify / plan are assigned to the Architect Role (pro / high-reasoning tier) for deep reasoning and system modeling.
- tasks decomposition is handled by the primary coordinator.
- analyze consistency and quality audit is assigned to the Reviewer Role (pro / high-reasoning tier, read-only) for comprehensive cross-artifact verification.
- implement / converge are executed by the Coder Role (flash / fast coding tier) for rapid TDD loops.
Single-Agent / Interactive Chat Environments (Cursor Composer, Windsurf, Claude Desktop, Aider):
- When subagent spawning is unavailable, the primary agent adopts each persona sequentially:
  - Act as Architect during specify and plan (focus on constraints and contracts).
  - Act as Coordinator during tasks (focus on clear atomicity).
  - Act as Reviewer during analyze (audit specs vs code before coding).
  - Act as Coder during implement and converge (focus on minimal diffs and running tests).
Automated CLI / Workflow Orchestration:
- In Spec Kit CLI: configured via .specify/workflows/overlays/speckit/chained-sdd.yml.
- In Herdr: after implement, prompt live matching agent-roles agents. Do not auto-start panes. The user starts them with node scripts/start-herdr-roles.mjs.
- User override priority: explicit model: or integration: settings in workflow files take strict precedence.

Product-specific rules (domain model, UI kit, changelog entries, deploy commands, CI job body) stay out of this launcher. The changelog policy (link the pull request, never a commit SHA) is an optional starter, not a constitution principle. Write domain rules with /speckit-constitution for the new project.

After upgrading the `specify` CLI

This repo is a launcher, not a Spec Kit project. There is no .specify/ here. Do not run specify integration upgrade in this directory.

New projects pick up the new CLI automatically the next time you run node bin/new-project.mjs. To keep the launcher itself compatible:

Confirm the CLI: specify --version (supported >=1.0.0 <2.0.0; last smoke-tested: 1.0.4). After retesting a newer release, raise SPECKIT_VERSION_SUPPORT in bin/new-project.mjs so the warning or refusal matches what you verified.
Skim specify init --help and specify integration install --help if a major release changed flags
Check that the bundled speckit workflow still has these step ids (overlay anchors): specify, review-spec, plan, review-plan, tasks, implement
Smoke-test: node bin/new-project.mjs --only grok --no-git smoke-app --dir %TEMP% (or $TMPDIR)
In the smoke project, confirm .specify/workflows/overlays/speckit/chained-sdd.yml exists and specify workflow resolve speckit shows clarify / analyze, a review-code gate after implement, then converge
Commit launcher/overlay changes if anything in steps 2–5 required an edit

Already-created apps are upgraded in that repo. Do not re-run new-project.mjs --here as an upgrade path — that runs specify init --here --force.

Refresh launcher-owned layer 2 files with:

npx speckit-launch upgrade                 # plan only; writes nothing
npx speckit-launch upgrade --apply         # write the allowlist
npx speckit-launch upgrade --dir <path>    # target project (default: cwd)

--dry-run is the explicit form of the default. The command fails if the target has no .specify/ (not a Spec Kit project), if Spec Kit is older than 1.0.0, or if it is 2.0.0 or newer. A newer 1.x than 1.0.4 warns and continues. Each planned file is printed as same, update, skip, or add. A dry-run update means the file would be written.

--apply updates only:

.specify/workflows/overlays/speckit/chained-sdd.yml (if specify workflow overlay list speckit already shows chained-sdd enabled, this only overwrites the file; otherwise --apply runs specify workflow overlay add first — dry-run does not)
.agents/skills/speckit-clarify, speckit-analyze, speckit-implement, speckit-converge SKILL.md (script type from .specify/init-options.json script, else .specify/scripts; bash and powershell together do not default to bash)
.cursor/rules/speckit-pipeline.mdc
scripts/link-agent-skills.mjs, scripts/new-worktree.mjs, and scripts/start-herdr-roles.mjs
known files under .specify/presets/chained-sdd/ (extra files in that directory are kept; this does not rely on specify preset add, which skips when the preset is already installed)

It does not run specify init or specify integration install --force, and it does not rewrite workflow.yml, .specify/templates/, .specify/scripts/, a filled constitution.md, .gitignore, .gitattributes, or package.json. Optional starters (changelog, commit-checks, shell-encoding, commit-push-pr, hooks, safety-check) and agent-roles/react-{reviewer,implementer,checker}.md are copied only when missing. .agents/AGENTS.md is updated only between paired  …  markers. A start marker with no end marker is skipped (pipeline section has no end marker).

Specify CLI upgrades in that app are still separate:

specify integration upgrade          # once per installed integration key
specify extension update
specify extension add git            # if this project was created before the git extension was installed
node scripts/link-agent-skills.mjs   # if that project uses skill mounts

After clone

In a project created by this launcher:

node scripts/link-agent-skills.mjs

(Optional: add "postinstall": "node scripts/link-agent-skills.mjs" in that project's package.json.)

Multi-Agent / Multi-Branch Parallelism (Git Worktree)

Spec Kit's chained SDD pipeline (specify → clarify → plan → tasks → analyze → implement, then a review-code pause before converge) produces artifacts scoped strictly inside specs/<feature>/, without global locks.

To have multiple AI agents work on separate feature branches concurrently, do not switch branches inside the same working directory (which causes Git state collisions and feature anchoring mismatches). Instead, use Git Worktrees:

1. One-command isolated worktree setup

The launcher includes a helper script that automatically creates the worktree, checks out the branch, and mounts agent skills:

# Create a worktree for a branch (defaults to ../<repo>-<branch>)
node scripts/new-worktree.mjs 002-billing

# Or specify a custom directory
node scripts/new-worktree.mjs 002-billing ../my-app-billing

# Or via npm script if package.json exists:
npm run worktree:new -- 002-billing

2. Independent execution per directory

Open each directory in a separate agent terminal or IDE window (Cursor, Claude Code, Antigravity, etc.) and run the chained pipeline independently:

cd ../my-app-billing
# Run specify to kick off the pipeline
/speckit-specify <feature description>

3. Cleanup after completion

Once the feature converges (converge), is reviewed via PR, and merged to main, remove the worktree:

git worktree remove ../my-app-billing

User-level agent skill

Copy skill/new-project/SKILL.md into your agent's user skills directory (for example ~/.cursor/skills/new-project/ or ~/.claude/skills/new-project/).

Point the skill at this repo via SPECKIT_STARTER or a path you provide — do not hardcode machine-specific locations.

Architecture & Layout

speckit-launch cleanly decouples Chained SDD Methodology Assets from Generic Repository Scaffolding:

speckit-launch/
├── bin/
│   └── new-project.mjs                      # Main launcher CLI orchestrator
├── scripts/
│   ├── link-agent-skills.mjs                # OS junction / symlink mount utility
│   ├── new-worktree.mjs                     # Automated Git Worktree isolation & skill mount tool
│   └── start-herdr-roles.mjs                # One Herdr session, one pane per agent-roles file
├── presets/chained-sdd/                     # [Self-Contained Chained SDD Methodology Bundle]
│   ├── preset.yml                           # Spec Kit Preset declaration
│   ├── install.mjs                          # Standalone preset installer for existing projects
│   ├── README.md                            # Preset usage and integration guide
│   ├── LICENSE
│   ├── workflows/
│   │   └── chained-sdd.yml                  # SDD step graph with retry review gates
│   ├── rules/
│   │   ├── pipeline-rules.md                # Single source of truth for chained SDD rules
│   │   └── speckit-pipeline.mdc             # Agent chained pause/continue rules (Cursor)
│   ├── templates/
│   │   └── constitution-pipeline.md         # Seeded pipeline principle for constitution
│   └── skills/                              # Enhanced workflow execution skills
│       ├── speckit-clarify/SKILL.md         # Immediate question & default persistence
│       ├── speckit-analyze/SKILL.md         # Structured analysis.md with remediation checklist
│       ├── speckit-implement/SKILL.md       # Step 2.5 auto-remediation application
│       └── speckit-converge/SKILL.md        # Automated ADR extraction & living spec consolidation
├── templates/                               # [Pure Repository Infrastructure Scaffolding]
│   ├── AGENTS.md                            # Base agent autonomy scaffolding (pipeline rules injected at launch)
│   ├── gitattributes.fragment               # LF line endings plus explicit text/binary hints
│   ├── gitignore.fragment                   # Gitignore template (extension caches, skill-mounts, local credentials)
│   ├── skills.json                          # Shared .agents/skills catalog metadata
│   ├── rules/                               # Canonical process rules for every agent
│   ├── skills/commit-push-pr/               # Commit, push, then append the PR link
│   ├── agents/                              # Generic dangerous-command hook (no deploy/db-reset)
│   └── github/ci-paths-ignore.snippet.yml   # Paste under push only; not a workflow
├── skill/new-project/
│   └── SKILL.md                             # Agent user skill for invoking speckit-launch
├── tests/
│   └── launcher.test.mjs                    # Automated test suite (node --test)
├── package.json
├── LICENSE
├── README.md
└── README.zh-Hant.md

Architectural Layer Responsibilities

Layer	Directory	Purpose	Lifecycle & Scope
Chained SDD Methodology	`presets/chained-sdd/`	Bundles workflow graphs, agent pause rules, constitution fragments, and the 4 specialized SDD skills.	Portable & self-contained. Can be installed into any existing Spec Kit project via `specify preset add --dev`.
Repo Scaffolding	`templates/`	Pure project-level files (`.gitignore`, `.gitattributes`, `AGENTS.md`, `skills.json`).	Initialized once upon project bootstrap; decoupled from specific workflow presets.
Agent Mounts Engine	`scripts/`	Rebuilds Windows directory junctions or Unix symlinks pointing to `.agents/skills`.	Ensures cross-agent skill discovery without duplicate file copies or agent lock-in.

License

MIT — see LICENSE.

Navigation Menu

Repository files navigation

speckit-launch

Why

Prerequisites

Spec Kit compatibility

Quick start

Local link and global usage (`npm link`)

Flags

What it does

Spec Kit pipeline (from production use)

Model & capability tier routing

After upgrading the `specify` CLI

After clone

Multi-Agent / Multi-Branch Parallelism (Git Worktree)

1. One-command isolated worktree setup

2. Independent execution per directory

3. Cleanup after completion

User-level agent skill

Architecture & Layout

Architectural Layer Responsibilities

License

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
bin		bin
presets/chained-sdd		presets/chained-sdd
scripts		scripts
skill/new-project		skill/new-project
templates		templates
tests		tests
.editorconfig		.editorconfig
.gitattributes		.gitattributes
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
README.zh-Hant.md		README.zh-Hant.md
package.json		package.json

Latest commit

History

Folders and files

Repository files navigation

speckit-launch

Why

Prerequisites

Spec Kit compatibility

Quick start

Local link and global usage (npm link)

Flags

What it does

Spec Kit pipeline (from production use)

Model & capability tier routing

After upgrading the specify CLI

After clone

Multi-Agent / Multi-Branch Parallelism (Git Worktree)

1. One-command isolated worktree setup

2. Independent execution per directory

3. Cleanup after completion

User-level agent skill

Architecture & Layout

Architectural Layer Responsibilities

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Local link and global usage (`npm link`)

After upgrading the `specify` CLI