speci

AI-powered implementation loop orchestrator for GitHub Copilot. Speci automates development workflows by dispatching Copilot agents to plan, implement, review, and fix code, with quality gate validation (lint, typecheck, test) between each step.

How It Works

Speci operates as an autonomous loop that reads a PROGRESS.md file to determine what needs to be done, then dispatches the appropriate Copilot agent:

Plan your feature or change (generates a structured plan)
Task breaks the plan into trackable tasks with a PROGRESS.md file
Run enters the implementation loop:

When tasks remain incomplete (state: WORK_LEFT), an implementation agent is dispatched
Gate validation runs your lint, typecheck, and test commands
If gates fail, a fix agent attempts repairs (up to a configurable limit)
Tasks marked IN_REVIEW get a review agent
When all remaining tasks are blocked (state: BLOCKED), a tidy agent is dispatched
The loop continues until all tasks are DONE or limits are reached

Workflow Diagram

  ┌─────────────────────────────────────────────────────────────────────┐
  │                        speci workflow                               │
  └─────────────────────────────────────────────────────────────────────┘

  ┌──────────┐      ┌──────────┐      ┌──────────────────────────────┐
  │          │      │          │      │          speci run           │
  │  plan    ├─────►│  task    ├─────►│    (implementation loop)     │
  │  agent   │      │  agent   │      │                              │
  └──────────┘      └──────────┘      └──────────────┬───────────────┘
   Generates a       Breaks plan                     │
   structured        into tasks &                    ▼
   plan              PROGRESS.md          ┌─────────────────────┐
                                          │  Read PROGRESS.md   │◄─────────────┐
                                          │  Determine STATE    │              │
                                          └────────┬────────────┘              │
                         ┌─────────────────────────┼──────────────────┐        │
                         │                         │                  │        │
                         ▼                         ▼                  ▼        │
                  ┌─────────────┐         ┌──────────────┐   ┌────────────┐    │
                  │  WORK_LEFT  │         │  IN_REVIEW   │   │  BLOCKED   │    │
                  └──────┬──────┘         └──────┬───────┘   └─────┬──────┘    │
                         │                       │                 │           │
                         ▼                       ▼                 ▼           │
                  ┌─────────────┐         ┌──────────────┐   ┌────────────┐    │
                  │    impl     │         │   review     │   │   tidy     │    │
                  │    agent    │         │   agent      │   │   agent    │    │
                  └──────┬──────┘         └──────┬───────┘   └─────┬──────┘    │
                         │                       │                 │           │
                         ▼                       │                 │           │
                  ┌─────────────┐                │                 │           │
                  │  run gates  │                │                 │           │
                  │ lint/type/  │                │                 │           │
                  │   test      │                │                 │           │
                  └──┬──────┬───┘                │                 │           │
                     │      │                    │                 │           │
                pass ▼      ▼ fail               │                 │           │
                     │ ┌─────────┐               │                 │           │
                     │ │  fix    │               │                 │           │
                     │ │  agent  │               │                 │           │
                     │ └────┬────┘               │                 │           │
                     │      │                    │                 │           │
                     │      ▼                    │                 │           │
                     │ ┌─────────┐               │                 │           │
                     │ │ re-run  │               │                 │           │
                     │ │ gates   ├──► (retry up  │                 │           │
                     │ └─────────┘    to N times)│                 │           │
                     │                           │                 │           │
                     └───────────┬───────────────┘                 │           │
                                 │                                 │           │
                                 └────────────┬────────────────────┘           │
                                              │                                │
                                              ▼                                │
                                    ┌───────────────────┐                      │
                                    │  State changed?   │                      │
                                    │  DONE? ─► exit    │                      │
                                    │  otherwise ───────┼──────────────────────┘
                                    └───────────────────┘

Agent Summary

Agent	Triggered By	Purpose
`plan`	`speci plan`	Generate a structured implementation plan
`task`	`speci task`	Break plan into tasks and create PROGRESS.md
`refactor`	`speci refactor`	Analyze codebase for refactoring opportunities
`impl`	WORK_LEFT	Implement the next task
`review`	IN_REVIEW	Review completed work for correctness
`fix`	Gate failure	Repair lint, typecheck, or test failures
`tidy`	BLOCKED	Clean up or unblock dependencies

Quick Start

# Initialize speci in your project
npx speci init

# Create a plan from a prompt or design doc
npx speci plan -p "Add user authentication with JWT"

# Break the plan into tasks and generate PROGRESS.md
npx speci task --plan docs/plan.md

# Run the implementation loop
npx speci run

Or run the entire plan → task → run pipeline in one command:

npx speci yolo -p "Add user authentication with JWT"

Prerequisites

Node.js 22.0.0 or later
GitHub Copilot CLI installed and authenticated
Git repository initialized in your project

Install GitHub Copilot CLI

# Install via npm (all platforms)
npm install -g @github/copilot

# Or via WinGet (Windows)
winget install GitHub.Copilot

# Or via Homebrew (macOS/Linux)
brew install copilot-cli

On first launch, use the /login slash command to authenticate, or set the GH_TOKEN environment variable with a personal access token.

See https://docs.github.com/en/copilot/how-tos/copilot-cli/install-copilot-cli for more details.

Installation

# Run directly without installing
npx speci --help

# Or install globally
npm install -g speci

Commands

All commands support -v, --verbose for detailed output and --no-color to disable colored output.

`speci init` (alias: `i`)

Initialize speci in your current project. Creates configuration files, task directories, and Copilot agent definitions.

npx speci init

Options:

Flag	Description
`-u, --update-agents`	Update agent files even if they already exist

Creates:

speci.config.json in the project root
docs/tasks/ directory for task definitions
.speci-logs/ directory for execution logs
.github/agents/ directory with Copilot agent definitions

# Update bundled agent files to the latest version
npx speci init --update-agents

`speci plan` (alias: `p`)

Generate an implementation plan using Copilot. Requires at least --prompt or --input.

npx speci plan -p "Build a REST API for user authentication"

Options:

Flag	Description
`-p, --prompt <text>`	Initial prompt describing what to plan
`-i, --input <files...>`	Input files for context (design docs, specs)
`-o, --output <path>`	Save plan to a specific file
`--sleep-after`	Put machine to sleep after command completes

# Plan using a design doc as context
npx speci plan -i docs/design.md

# Combine input files with a prompt
npx speci plan -i spec.md -p "Focus on the authentication module"

# Save plan to a specific file
npx speci plan -i design.md -o docs/plan.md

`speci task` (alias: `t`)

Generate task definitions and a PROGRESS.md file from an implementation plan.

npx speci task --plan docs/plan.md

Options:

Flag	Description
`-p, --plan <path>`	Path to plan file (required)
`-c, --clean`	Clean task files and progress before generating
`--sleep-after`	Put machine to sleep after command completes

# Clean existing tasks and regenerate from a new plan
npx speci task --clean --plan docs/plan.md

`speci refactor` (alias: `r`)

Analyze the codebase for refactoring opportunities using Copilot.

npx speci refactor

Options:

Flag	Description
`-s, --scope <path>`	Directory or glob pattern to analyze
`-o, --output <path>`	Save refactoring plan to a file

# Analyze a specific directory
npx speci refactor --scope src/

# Analyze only TypeScript files
npx speci r -s "src/**/*.ts"

# Save the refactoring plan
npx speci refactor -o docs/refactor-plan.md

`speci status` (alias: `s`)

Show current loop state and task statistics. By default, opens a live fullscreen dashboard that refreshes automatically. Press q or ESC to exit the dashboard.

npx speci status

Options:

Flag	Description
`--json`	Output status as JSON and exit
`--once`	Show status once and exit (non-interactive)

Status fields:

Current loop state (WORK_LEFT, IN_REVIEW, BLOCKED, DONE)
Task statistics (total, completed, remaining, in review, blocked)
Lock status and current task

# Static one-time output
npx speci status --once

# Machine-readable output for scripts
npx speci s --json

`speci run`

Execute the implementation loop. This is the main command that drives autonomous development. It acquires a lock file to prevent concurrent runs and logs all agent activity to .speci-logs/.

npx speci run

Options:

Flag	Description
`--max-iterations <n>`	Maximum loop iterations (default: 100)
`--dry-run`	Show what would execute without running
`--verify`	Pause on manual verification tasks (MVTs) at milestone boundaries
`--force`	Override an existing lock file
`-y, --yes`	Skip the confirmation prompt
`--sleep-after`	Put machine to sleep after command completes

This command has no short alias, by design, to prevent accidental execution.

# Preview what would happen
npx speci run --dry-run

# Limit to 10 iterations
npx speci run --max-iterations 10

# Skip confirmation and force past a stale lock
npx speci run -y --force

Verify Mode (Human-in-the-Loop)

Speci supports milestone verification testing (MVT) - manual checkpoints at milestone boundaries where a human reviews the completed work before the loop continues.

Enable verify mode with the --verify flag:

npx speci run --verify

Startup check: Before acquiring the lock, speci checks if any milestones have all tasks completed but an unfinished MVT. If found, it warns and prompts Continue anyway? [y/N].

In-loop pause: During each iteration, if the current milestone's tasks are all done and an MVT is ready, speci pauses the loop, releases the lock, and exits cleanly. Perform the manual verification, mark the MVT as COMPLETE in PROGRESS.md, then re-run speci run --verify.

Flag interactions:

--yes auto-continues past the startup MVT warning without prompting
--dry-run displays MVT status per milestone without executing
Non-TTY environments abort automatically if --yes is not set

Note: speci yolo intentionally does not support --verify - it is designed for fully unattended operation.

`speci yolo`

Run the full plan → task → run pipeline in a single unattended command. Accepts the same options as speci plan and forwards them automatically through each phase. The run phase is started with --yes automatically, so no confirmation prompt is shown.

npx speci yolo -p "Build a REST API for user authentication"

Options:

Flag	Description
`-p, --prompt <text>`	Initial prompt describing what to plan
`-i, --input <files...>`	Input files for context (design docs, specs)
`-o, --output <path>`	Save plan to a specific file
`--force`	Override an existing lock file
`--sleep-after`	Put machine to sleep after command completes

Requires at least --prompt or --input. Only one yolo command can run at a time - a lock file prevents concurrent executions.

# Run full pipeline from a design doc
npx speci yolo -i docs/design.md

# Combine input files with a prompt
npx speci yolo -i spec.md -p "Focus on the authentication module"

# Override a stale lock
npx speci yolo -p "Build feature" --force

`speci clean` (alias: `c`)

Remove generated task files and the PROGRESS.md file. Useful for resetting before re-running the full pipeline. This command is safe to run multiple times (idempotent) and refuses to run while a lock file is present.

npx speci clean

Options:

Flag	Description
`-v, --verbose`	Show detailed output

# Reset and regenerate tasks from a plan
npx speci clean
npx speci task --plan docs/plan.md

# Or combine into a single task command
npx speci task --clean --plan docs/plan.md

Configuration

speci.config.json

Created by speci init. Speci discovers this file by walking up from the current directory, similar to how ESLint finds its config.

{
  "version": "1.0.0",
  "paths": {
    "progress": "docs/PROGRESS.md",
    "tasks": "docs/tasks",
    "logs": ".speci-logs",
    "lock": ".speci-lock"
  },
  "copilot": {
    "permissions": "allow-all",
    "models": {
      "plan": "claude-opus-4.6",
      "task": "claude-sonnet-4.6",
      "refactor": "claude-sonnet-4.6",
      "impl": "gpt-5.3-codex",
      "review": "claude-sonnet-4.6",
      "fix": "claude-sonnet-4.6",
      "tidy": "gpt-5.2"
    },
    "extraFlags": []
  },
  "gate": {
    "commands": ["npm run lint", "npm run typecheck", "npm test"],
    "maxFixAttempts": 5,
    "strategy": "sequential"
  },
  "loop": {
    "maxIterations": 100
  }
}

Configuration Reference

paths - File and directory locations used by speci.

Field	Default	Description
`progress`	`docs/PROGRESS.md`	Path to the progress tracking file
`tasks`	`docs/tasks`	Directory for task definition files
`logs`	`.speci-logs`	Directory for execution logs
`lock`	`.speci-lock`	Lock file to prevent concurrent runs

copilot - Copilot CLI settings.

Field	Default	Description
`permissions`	`allow-all`	Permission mode: `allow-all`, `yolo`, `strict`, or `none`
`models`	(see above)	Model to use for each agent type
`extraFlags`	`[]`	Additional flags passed to the Copilot CLI

gate - Quality gate configuration. Gate commands run after each implementation step.

Field	Default	Description
`commands`	`["npm run lint", ...]`	Shell commands to run as quality gates
`maxFixAttempts`	`5`	Maximum automatic fix attempts after gate failures (0 to disable)
`strategy`	`sequential`	`sequential` or `parallel` execution of gate commands

Parallel strategy can be 30-50% faster but requires that gate commands are independent (no shared resources like lock files or ports).

loop - Loop behavior settings.

Field	Default	Description
`maxIterations`	`100`	Maximum loop iterations before stopping

Environment Variables

Environment variables override corresponding config file settings.

Variable	Config Path	Description
`SPECI_PROGRESS_PATH`	`paths.progress`	Path to PROGRESS.md file
`SPECI_TASKS_PATH`	`paths.tasks`	Path to tasks directory
`SPECI_LOG_PATH`	`paths.logs`	Path to log directory
`SPECI_LOGS_PATH`	`paths.logs`	Alias for `SPECI_LOG_PATH`
`SPECI_LOCK_PATH`	`paths.lock`	Path to lock file
`SPECI_MAX_ITERATIONS`	`loop.maxIterations`	Maximum loop iterations
`SPECI_MAX_FIX_ATTEMPTS`	`gate.maxFixAttempts`	Maximum fix attempts
`SPECI_COPILOT_PERMISSIONS`	`copilot.permissions`	Permission mode
`SPECI_DEBUG`	N/A	Enable debug logging (`1` or `true`)
`SPECI_ASCII`	N/A	Force ASCII glyph fallback
`SPECI_NO_ANIMATION`	N/A	Disable banner animation
`NO_COLOR`	N/A	Disable colored output

Speci warns if it detects an unknown SPECI_* environment variable that looks like a typo of a known one.

Error Codes

Speci uses structured error codes for diagnostics. Use --verbose to see full error details including causes and suggested solutions.

Prerequisite Errors (ERR-PRE-*)

Code	Message	Solution
ERR-PRE-01	Copilot CLI is not installed	Run `npm install -g @github/copilot`
ERR-PRE-02	Copilot CLI is not authenticated	Run `/login` in Copilot CLI or set `GH_TOKEN`
ERR-PRE-03	Not a git repository	Run `git init` in your project root
ERR-PRE-04	Configuration file not found	Run `npx speci init`
ERR-PRE-05	PROGRESS.md file not found	Run `npx speci task --plan <plan-file>`
ERR-PRE-06	No PROGRESS.md found during run	Generate tasks first with `npx speci task`

Input Errors (ERR-INP-*)

Code	Message	Solution
ERR-INP-01	Required argument missing	Check command usage with `--help`
ERR-INP-02	Agent file not found	Verify the path, or set to `null` in config for bundled agents
ERR-INP-03	Config file is malformed	Fix JSON syntax in `speci.config.json`
ERR-INP-04	Config validation failed	Check config values against the reference above
ERR-INP-05	Plan file not found	Provide a valid path with `--plan`
ERR-INP-06	Config version is not compatible	Update to version 1.x or re-run `npx speci init`
ERR-INP-07	Path escapes project directory	Use paths within the project root, avoid `../` traversal
ERR-INP-08	Invalid permissions value	Use `allow-all`, `yolo`, `strict`, or `none`
ERR-INP-09	Invalid maxFixAttempts value	Must be a non-negative integer (0 disables fix attempts)
ERR-INP-10	Invalid maxIterations value	Must be a positive integer
ERR-INP-11	Subagent prompt not found	Reinstall speci or provide a custom agent path

State Errors (ERR-STA-*)

Code	Message	Solution
ERR-STA-01	Another speci instance is running	Wait for it to finish or use `--force`
ERR-STA-02	Cannot parse PROGRESS.md	Verify the markdown table format in PROGRESS.md
ERR-STA-03	Invalid state transition	Check PROGRESS.md state markers
ERR-STA-04	Malformed milestone header	Check the `## Milestone:` heading format in PROGRESS.md
ERR-STA-05	Unknown MVT status	Verify the MVT status column value in PROGRESS.md
ERR-STA-06	Failed to read milestone state	Check file permissions and PROGRESS.md path in config

Execution Errors (ERR-EXE-*)

Code	Message	Solution
ERR-EXE-01	Gate command failed	Fix lint, typecheck, or test errors in your code
ERR-EXE-02	Copilot execution failed	Check Copilot authentication and permissions
ERR-EXE-03	Max iterations reached	Review progress and increase `--max-iterations` if needed
ERR-EXE-04	Max fix attempts exceeded	Review gate failures and fix issues manually
ERR-EXE-05	Failed to create directory	Check file system permissions and disk space
ERR-EXE-06	Failed to write file	Check file system permissions and disk space
ERR-EXE-07	Agent templates directory not found	Reinstall speci
ERR-EXE-08	Failed to copy agent files	Check file system permissions and disk space
ERR-EXE-09	Failed to read tasks directory	Check directory permissions and ensure the path exists
ERR-EXE-10	Failed to delete during clean	Check file permissions and ensure no other process has the file open

Exit Codes

Code	Meaning
0	Success
1	General error
2	Invalid command or arguments
130	Interrupted by SIGINT (Ctrl+C)
143	Terminated by SIGTERM

Troubleshooting

"Copilot CLI not found"

The GitHub Copilot CLI must be installed and available in your PATH:

# Install via npm
npm install -g @github/copilot

# Or via WinGet (Windows)
winget install GitHub.Copilot

# Or via Homebrew (macOS/Linux)
brew install copilot-cli

# Verify installation
copilot --version

"Another speci instance is running"

A lock file from a previous run may still exist:

# Check if speci is actually running
# On Linux/macOS:
ps aux | grep speci
# On Windows:
tasklist | findstr speci

# If the process is not running, force past the stale lock
npx speci run --force

# Or remove the lock file manually
rm .speci-lock

"Config file not found"

Initialize speci in your project:

npx speci init

"PROGRESS.md file not found"

Generate tasks from a plan first. The task command creates the PROGRESS.md file:

npx speci plan -p "Describe what you want to build"
npx speci task --plan docs/plan.md

Gate commands failing

Speci runs gate commands defined in speci.config.json. Make sure your project has the corresponding scripts in package.json:

{
  "scripts": {
    "lint": "eslint .",
    "typecheck": "tsc --noEmit",
    "test": "vitest run"
  }
}

You can customize which commands speci runs by editing the gate.commands array in speci.config.json.

Verbose mode

Use --verbose (or -v) with any command for detailed output including stack traces, config loading details, state transitions, and timing information:

npx speci run --verbose

# Or set the environment variable
SPECI_DEBUG=1 npx speci run

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 360 Commits
.changeset		.changeset
.github		.github
.husky		.husky
bin		bin
docs		docs
images		images
lib		lib
templates		templates
test		test
.gitignore		.gitignore
.prettierrc		.prettierrc
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
codecov.yml		codecov.yml
eslint.config.mjs		eslint.config.mjs
package-lock.json		package-lock.json
package.json		package.json
tsconfig.build.json		tsconfig.build.json
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts
vitest.integration.config.ts		vitest.integration.config.ts

Folders and files

Latest commit

History

Repository files navigation

speci

How It Works

Workflow Diagram

Agent Summary

Quick Start

Prerequisites

Install GitHub Copilot CLI

Installation

Commands

speci init (alias: i)

speci plan (alias: p)

speci task (alias: t)

speci refactor (alias: r)

speci status (alias: s)

speci run

Verify Mode (Human-in-the-Loop)

speci yolo

speci clean (alias: c)

Configuration

speci.config.json

Configuration Reference

Environment Variables

Error Codes

Prerequisite Errors (ERR-PRE-*)

Input Errors (ERR-INP-*)

State Errors (ERR-STA-*)

Execution Errors (ERR-EXE-*)

Exit Codes

Troubleshooting

"Copilot CLI not found"

"Another speci instance is running"

"Config file not found"

"PROGRESS.md file not found"

Gate commands failing

Verbose mode

License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 20

Contributors

Uh oh!

Languages

`speci init` (alias: `i`)

`speci plan` (alias: `p`)

`speci task` (alias: `t`)

`speci refactor` (alias: `r`)

`speci status` (alias: `s`)

`speci run`

`speci yolo`

`speci clean` (alias: `c`)