{"id":45186114,"url":"https://github.com/ianchak/speci","last_synced_at":"2026-02-25T21:07:45.172Z","repository":{"id":336514448,"uuid":"1148350893","full_name":"ianchak/speci","owner":"ianchak","description":"AI-powered implementation loop orchestrator for GitHub Copilot. Automates plan → implement → gate → review → fix cycles autonomously.","archived":false,"fork":false,"pushed_at":"2026-02-22T09:59:52.000Z","size":1042,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-02-22T16:53:42.718Z","etag":null,"topics":["agentic-ai","ai-agents","automation","cli","copilot-cli","developer-tools","github-copilot","nodejs","orchestrator","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ianchak.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-02T21:35:52.000Z","updated_at":"2026-02-22T09:59:19.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ianchak/speci","commit_stats":null,"previous_names":["ianchak/speci"],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/ianchak/speci","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ianchak%2Fspeci","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ianchak%2Fspeci/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ianchak%2Fspeci/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ianchak%2Fspeci/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ianchak","download_url":"https://codeload.github.com/ianchak/speci/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ianchak%2Fspeci/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29837401,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-25T19:08:47.527Z","status":"ssl_error","status_checked_at":"2026-02-25T18:59:04.705Z","response_time":61,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentic-ai","ai-agents","automation","cli","copilot-cli","developer-tools","github-copilot","nodejs","orchestrator","typescript"],"created_at":"2026-02-20T11:00:51.612Z","updated_at":"2026-02-25T21:07:45.140Z","avatar_url":"https://github.com/ianchak.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# speci\n\n[![CI](https://github.com/ianchak/speci/actions/workflows/ci.yml/badge.svg)](https://github.com/ianchak/speci/actions/workflows/ci.yml)\n[![Release](https://github.com/ianchak/speci/actions/workflows/release.yml/badge.svg)](https://github.com/ianchak/speci/actions/workflows/release.yml)\n[![codecov](https://codecov.io/gh/ianchak/speci/graph/badge.svg?token=SS57WL1RRX)](https://codecov.io/gh/ianchak/speci)\n[![npm version](https://img.shields.io/npm/v/speci.svg)](https://www.npmjs.com/package/speci)\n[![Node.js](https://img.shields.io/node/v/speci.svg)](https://nodejs.org/)\n[![TypeScript](https://img.shields.io/badge/TypeScript-strict-blue.svg)](https://www.typescriptlang.org/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\nAI-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.\n\n## How It Works\n\nSpeci operates as an autonomous loop that reads a PROGRESS.md file to determine what needs to be done, then dispatches the appropriate Copilot agent:\n\n1. **Plan** your feature or change (generates a structured plan)\n2. **Task** breaks the plan into trackable tasks with a PROGRESS.md file\n3. **Run** enters the implementation loop:\n\n- Tasks marked WORK_LEFT get an implementation agent\n- Gate validation runs your lint, typecheck, and test commands\n- If gates fail, a fix agent attempts repairs (up to a configurable limit)\n- Tasks marked IN_REVIEW get a review agent\n- Tasks marked BLOCKED get a tidy agent\n- The loop continues until all tasks are DONE or limits are reached\n\n### Workflow Diagram\n\n```\n  ┌─────────────────────────────────────────────────────────────────────┐\n  │                        speci workflow                               │\n  └─────────────────────────────────────────────────────────────────────┘\n\n  ┌──────────┐      ┌──────────┐      ┌──────────────────────────────┐\n  │          │      │          │      │          speci run           │\n  │  plan    ├─────►│  task    ├─────►│    (implementation loop)     │\n  │  agent   │      │  agent   │      │                              │\n  └──────────┘      └──────────┘      └──────────────┬───────────────┘\n   Generates a       Breaks plan                     │\n   structured        into tasks \u0026                    ▼\n   plan              PROGRESS.md          ┌─────────────────────┐\n                                          │  Read PROGRESS.md   │◄─────────────┐\n                                          │  Determine STATE    │              │\n                                          └────────┬────────────┘              │\n                         ┌─────────────────────────┼──────────────────┐        │\n                         │                         │                  │        │\n                         ▼                         ▼                  ▼        │\n                  ┌─────────────┐         ┌──────────────┐   ┌────────────┐    │\n                  │  WORK_LEFT  │         │  IN_REVIEW   │   │  BLOCKED   │    │\n                  └──────┬──────┘         └──────┬───────┘   └─────┬──────┘    │\n                         │                       │                 │           │\n                         ▼                       ▼                 ▼           │\n                  ┌─────────────┐         ┌──────────────┐   ┌────────────┐    │\n                  │    impl     │         │   review     │   │   tidy     │    │\n                  │    agent    │         │   agent      │   │   agent    │    │\n                  └──────┬──────┘         └──────┬───────┘   └─────┬──────┘    │\n                         │                       │                 │           │\n                         ▼                       │                 │           │\n                  ┌─────────────┐                │                 │           │\n                  │  run gates  │                │                 │           │\n                  │ lint/type/  │                │                 │           │\n                  │   test      │                │                 │           │\n                  └──┬──────┬───┘                │                 │           │\n                     │      │                    │                 │           │\n                pass ▼      ▼ fail               │                 │           │\n                     │ ┌─────────┐               │                 │           │\n                     │ │  fix    │               │                 │           │\n                     │ │  agent  │               │                 │           │\n                     │ └────┬────┘               │                 │           │\n                     │      │                    │                 │           │\n                     │      ▼                    │                 │           │\n                     │ ┌─────────┐               │                 │           │\n                     │ │ re-run  │               │                 │           │\n                     │ │ gates   ├──► (retry up  │                 │           │\n                     │ └─────────┘    to N times)│                 │           │\n                     │                           │                 │           │\n                     └───────────┬───────────────┘                 │           │\n                                 │                                 │           │\n                                 └────────────┬────────────────────┘           │\n                                              │                                │\n                                              ▼                                │\n                                    ┌───────────────────┐                      │\n                                    │  State changed?   │                      │\n                                    │  DONE? ─► exit    │                      │\n                                    │  otherwise ───────┼──────────────────────┘\n                                    └───────────────────┘\n```\n\n### Agent Summary\n\n| Agent      | Triggered By     | Purpose                                        |\n| ---------- | ---------------- | ---------------------------------------------- |\n| `plan`     | `speci plan`     | Generate a structured implementation plan      |\n| `task`     | `speci task`     | Break plan into tasks and create PROGRESS.md   |\n| `refactor` | `speci refactor` | Analyze codebase for refactoring opportunities |\n| `impl`     | WORK_LEFT        | Implement the next task                        |\n| `review`   | IN_REVIEW        | Review completed work for correctness          |\n| `fix`      | Gate failure     | Repair lint, typecheck, or test failures       |\n| `tidy`     | BLOCKED          | Clean up or unblock dependencies               |\n\n## Quick Start\n\n```bash\n# Initialize speci in your project\nnpx speci init\n\n# Create a plan from a prompt or design doc\nnpx speci plan -p \"Add user authentication with JWT\"\n\n# Break the plan into tasks and generate PROGRESS.md\nnpx speci task --plan docs/plan.md\n\n# Run the implementation loop\nnpx speci run\n```\n\nOr run the entire plan → task → run pipeline in one command:\n\n```bash\nnpx speci yolo -p \"Add user authentication with JWT\"\n```\n\n## Prerequisites\n\n- **Node.js** 22.0.0 or later\n- **GitHub Copilot CLI** installed and authenticated\n- **Git repository** initialized in your project\n\n### Install GitHub Copilot CLI\n\n```bash\n# Install via npm (all platforms)\nnpm install -g @github/copilot\n\n# Or via WinGet (Windows)\nwinget install GitHub.Copilot\n\n# Or via Homebrew (macOS/Linux)\nbrew install copilot-cli\n```\n\nOn first launch, use the `/login` slash command to authenticate, or set the `GH_TOKEN` environment variable with a personal access token.\n\nSee https://docs.github.com/en/copilot/how-tos/copilot-cli/install-copilot-cli for more details.\n\n## Installation\n\n```bash\n# Run directly without installing\nnpx speci --help\n\n# Or install globally\nnpm install -g speci\n```\n\n## Commands\n\nAll commands support `-v, --verbose` for detailed output and `--no-color` to disable colored output.\n\n### `speci init` (alias: `i`)\n\nInitialize speci in your current project. Creates configuration files, task directories, and Copilot agent definitions.\n\n```bash\nnpx speci init\n```\n\n**Options:**\n\n| Flag                  | Description                                   |\n| --------------------- | --------------------------------------------- |\n| `-u, --update-agents` | Update agent files even if they already exist |\n\n**Creates:**\n\n- `speci.config.json` in the project root\n- `docs/tasks/` directory for task definitions\n- `.speci-logs/` directory for execution logs\n- `.github/agents/` directory with Copilot agent definitions\n\n```bash\n# Update bundled agent files to the latest version\nnpx speci init --update-agents\n```\n\n### `speci plan` (alias: `p`)\n\nGenerate an implementation plan using Copilot. Requires at least `--prompt` or `--input`.\n\n```bash\nnpx speci plan -p \"Build a REST API for user authentication\"\n```\n\n**Options:**\n\n| Flag                     | Description                                  |\n| ------------------------ | -------------------------------------------- |\n| `-p, --prompt \u003ctext\u003e`    | Initial prompt describing what to plan       |\n| `-i, --input \u003cfiles...\u003e` | Input files for context (design docs, specs) |\n| `-o, --output \u003cpath\u003e`    | Save plan to a specific file                 |\n\n```bash\n# Plan using a design doc as context\nnpx speci plan -i docs/design.md\n\n# Combine input files with a prompt\nnpx speci plan -i spec.md -p \"Focus on the authentication module\"\n\n# Save plan to a specific file\nnpx speci plan -i design.md -o docs/plan.md\n```\n\n### `speci task` (alias: `t`)\n\nGenerate task definitions and a PROGRESS.md file from an implementation plan.\n\n```bash\nnpx speci task --plan docs/plan.md\n```\n\n**Options:**\n\n| Flag                | Description                                     |\n| ------------------- | ----------------------------------------------- |\n| `-p, --plan \u003cpath\u003e` | Path to plan file (required)                    |\n| `-c, --clean`       | Clean task files and progress before generating |\n\n```bash\n# Clean existing tasks and regenerate from a new plan\nnpx speci task --clean --plan docs/plan.md\n```\n\n### `speci refactor` (alias: `r`)\n\nAnalyze the codebase for refactoring opportunities using Copilot.\n\n```bash\nnpx speci refactor\n```\n\n**Options:**\n\n| Flag                  | Description                          |\n| --------------------- | ------------------------------------ |\n| `-s, --scope \u003cpath\u003e`  | Directory or glob pattern to analyze |\n| `-o, --output \u003cpath\u003e` | Save refactoring plan to a file      |\n\n```bash\n# Analyze a specific directory\nnpx speci refactor --scope src/\n\n# Analyze only TypeScript files\nnpx speci r -s \"src/**/*.ts\"\n\n# Save the refactoring plan\nnpx speci refactor -o docs/refactor-plan.md\n```\n\n### `speci status` (alias: `s`)\n\nShow current loop state and task statistics. By default, opens a live fullscreen dashboard that refreshes automatically. Press `q` or `ESC` to exit the dashboard.\n\n```bash\nnpx speci status\n```\n\n**Options:**\n\n| Flag     | Description                                 |\n| -------- | ------------------------------------------- |\n| `--json` | Output status as JSON and exit              |\n| `--once` | Show status once and exit (non-interactive) |\n\n**Status fields:**\n\n- Current loop state (WORK_LEFT, IN_REVIEW, BLOCKED, DONE)\n- Task statistics (total, completed, remaining, in review, blocked)\n- Lock status and current task\n\n```bash\n# Static one-time output\nnpx speci status --once\n\n# Machine-readable output for scripts\nnpx speci s --json\n```\n\n### `speci run`\n\nExecute 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/`.\n\n```bash\nnpx speci run\n```\n\n**Options:**\n\n| Flag                   | Description                             |\n| ---------------------- | --------------------------------------- |\n| `--max-iterations \u003cn\u003e` | Maximum loop iterations (default: 100)  |\n| `--dry-run`            | Show what would execute without running |\n| `--force`              | Override an existing lock file          |\n| `-y, --yes`            | Skip the confirmation prompt            |\n\nThis command has no short alias, by design, to prevent accidental execution.\n\n```bash\n# Preview what would happen\nnpx speci run --dry-run\n\n# Limit to 10 iterations\nnpx speci run --max-iterations 10\n\n# Skip confirmation and force past a stale lock\nnpx speci run -y --force\n```\n\n### `speci yolo`\n\nRun 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.\n\n```bash\nnpx speci yolo -p \"Build a REST API for user authentication\"\n```\n\n**Options:**\n\n| Flag                     | Description                                  |\n| ------------------------ | -------------------------------------------- |\n| `-p, --prompt \u003ctext\u003e`    | Initial prompt describing what to plan       |\n| `-i, --input \u003cfiles...\u003e` | Input files for context (design docs, specs) |\n| `-o, --output \u003cpath\u003e`    | Save plan to a specific file                 |\n| `--force`                | Override an existing lock file               |\n\nRequires at least `--prompt` or `--input`. Only one `yolo` command can run at a time - a lock file prevents concurrent executions.\n\n```bash\n# Run full pipeline from a design doc\nnpx speci yolo -i docs/design.md\n\n# Combine input files with a prompt\nnpx speci yolo -i spec.md -p \"Focus on the authentication module\"\n\n# Override a stale lock\nnpx speci yolo -p \"Build feature\" --force\n```\n\n### `speci clean` (alias: `c`)\n\nRemove 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.\n\n```bash\nnpx speci clean\n```\n\n**Options:**\n\n| Flag            | Description          |\n| --------------- | -------------------- |\n| `-v, --verbose` | Show detailed output |\n\n```bash\n# Reset and regenerate tasks from a plan\nnpx speci clean\nnpx speci task --plan docs/plan.md\n\n# Or combine into a single task command\nnpx speci task --clean --plan docs/plan.md\n```\n\n## Configuration\n\n### speci.config.json\n\nCreated by `speci init`. Speci discovers this file by walking up from the current directory, similar to how ESLint finds its config.\n\n```json\n{\n  \"version\": \"1.0.0\",\n  \"paths\": {\n    \"progress\": \"docs/PROGRESS.md\",\n    \"tasks\": \"docs/tasks\",\n    \"logs\": \".speci-logs\",\n    \"lock\": \".speci-lock\"\n  },\n  \"copilot\": {\n    \"permissions\": \"allow-all\",\n    \"models\": {\n      \"plan\": \"claude-opus-4.6\",\n      \"task\": \"claude-sonnet-4.6\",\n      \"refactor\": \"claude-sonnet-4.6\",\n      \"impl\": \"gpt-5.3-codex\",\n      \"review\": \"claude-sonnet-4.6\",\n      \"fix\": \"claude-sonnet-4.6\",\n      \"tidy\": \"gpt-5.2\"\n    },\n    \"extraFlags\": []\n  },\n  \"gate\": {\n    \"commands\": [\"npm run lint\", \"npm run typecheck\", \"npm test\"],\n    \"maxFixAttempts\": 5,\n    \"strategy\": \"sequential\"\n  },\n  \"loop\": {\n    \"maxIterations\": 100\n  }\n}\n```\n\n### Configuration Reference\n\n**paths** - File and directory locations used by speci.\n\n| Field      | Default            | Description                          |\n| ---------- | ------------------ | ------------------------------------ |\n| `progress` | `docs/PROGRESS.md` | Path to the progress tracking file   |\n| `tasks`    | `docs/tasks`       | Directory for task definition files  |\n| `logs`     | `.speci-logs`      | Directory for execution logs         |\n| `lock`     | `.speci-lock`      | Lock file to prevent concurrent runs |\n\n**copilot** - Copilot CLI settings.\n\n| Field         | Default     | Description                                               |\n| ------------- | ----------- | --------------------------------------------------------- |\n| `permissions` | `allow-all` | Permission mode: `allow-all`, `yolo`, `strict`, or `none` |\n| `models`      | (see above) | Model to use for each agent type                          |\n| `extraFlags`  | `[]`        | Additional flags passed to the Copilot CLI                |\n\n**gate** - Quality gate configuration. Gate commands run after each implementation step.\n\n| Field            | Default                 | Description                                           |\n| ---------------- | ----------------------- | ----------------------------------------------------- |\n| `commands`       | `[\"npm run lint\", ...]` | Shell commands to run as quality gates                |\n| `maxFixAttempts` | `5`                     | Maximum automatic fix attempts after gate failures    |\n| `strategy`       | `sequential`            | `sequential` or `parallel` execution of gate commands |\n\nParallel strategy can be 30-50% faster but requires that gate commands are independent (no shared resources like lock files or ports).\n\n**loop** - Loop behavior settings.\n\n| Field           | Default | Description                             |\n| --------------- | ------- | --------------------------------------- |\n| `maxIterations` | `100`   | Maximum loop iterations before stopping |\n\n### Environment Variables\n\nEnvironment variables override corresponding config file settings.\n\n| Variable                    | Config Path           | Description                          |\n| --------------------------- | --------------------- | ------------------------------------ |\n| `SPECI_PROGRESS_PATH`       | `paths.progress`      | Path to PROGRESS.md file             |\n| `SPECI_TASKS_PATH`          | `paths.tasks`         | Path to tasks directory              |\n| `SPECI_LOG_PATH`            | `paths.logs`          | Path to log directory                |\n| `SPECI_LOGS_PATH`           | `paths.logs`          | Alias for `SPECI_LOG_PATH`           |\n| `SPECI_LOCK_PATH`           | `paths.lock`          | Path to lock file                    |\n| `SPECI_MAX_ITERATIONS`      | `loop.maxIterations`  | Maximum loop iterations              |\n| `SPECI_MAX_FIX_ATTEMPTS`    | `gate.maxFixAttempts` | Maximum fix attempts                 |\n| `SPECI_COPILOT_PERMISSIONS` | `copilot.permissions` | Permission mode                      |\n| `SPECI_DEBUG`               | N/A                   | Enable debug logging (`1` or `true`) |\n| `SPECI_NO_ANIMATION`        | N/A                   | Disable banner animation             |\n| `NO_COLOR`                  | N/A                   | Disable colored output               |\n\nSpeci warns if it detects an unknown `SPECI_*` environment variable that looks like a typo of a known one.\n\n## Error Codes\n\nSpeci uses structured error codes for diagnostics. Use `--verbose` to see full error details including causes and suggested solutions.\n\n### Prerequisite Errors (ERR-PRE-\\*)\n\n| Code       | Message                          | Solution                                      |\n| ---------- | -------------------------------- | --------------------------------------------- |\n| ERR-PRE-01 | Copilot CLI is not installed     | Run `npm install -g @github/copilot`          |\n| ERR-PRE-02 | Copilot CLI is not authenticated | Run `/login` in Copilot CLI or set `GH_TOKEN` |\n| ERR-PRE-03 | Not a git repository             | Run `git init` in your project root           |\n| ERR-PRE-04 | Configuration file not found     | Run `npx speci init`                          |\n| ERR-PRE-05 | PROGRESS.md file not found       | Run `npx speci task --plan \u003cplan-file\u003e`       |\n| ERR-PRE-06 | No PROGRESS.md found during run  | Generate tasks first with `npx speci task`    |\n\n### Input Errors (ERR-INP-\\*)\n\n| Code       | Message                          | Solution                                                       |\n| ---------- | -------------------------------- | -------------------------------------------------------------- |\n| ERR-INP-01 | Required argument missing        | Check command usage with `--help`                              |\n| ERR-INP-02 | Agent file not found             | Verify the path, or set to `null` in config for bundled agents |\n| ERR-INP-03 | Config file is malformed         | Fix JSON syntax in `speci.config.json`                         |\n| ERR-INP-04 | Config validation failed         | Check config values against the reference above                |\n| ERR-INP-05 | Plan file not found              | Provide a valid path with `--plan`                             |\n| ERR-INP-06 | Config version is not compatible | Update to version 1.x or re-run `npx speci init`               |\n| ERR-INP-07 | Path escapes project directory   | Use paths within the project root, avoid `../` traversal       |\n| ERR-INP-08 | Invalid permissions value        | Use `allow-all`, `yolo`, `strict`, or `none`                   |\n| ERR-INP-09 | Invalid maxFixAttempts value     | Must be a positive integer                                     |\n| ERR-INP-10 | Invalid maxIterations value      | Must be a positive integer                                     |\n| ERR-INP-11 | Subagent prompt not found        | Reinstall speci or provide a custom agent path                 |\n\n### State Errors (ERR-STA-\\*)\n\n| Code       | Message                           | Solution                                        |\n| ---------- | --------------------------------- | ----------------------------------------------- |\n| ERR-STA-01 | Another speci instance is running | Wait for it to finish or use `--force`          |\n| ERR-STA-02 | Cannot parse PROGRESS.md          | Verify the markdown table format in PROGRESS.md |\n| ERR-STA-03 | Invalid state transition          | Check PROGRESS.md state markers                 |\n\n### Execution Errors (ERR-EXE-\\*)\n\n| Code       | Message                             | Solution                                                             |\n| ---------- | ----------------------------------- | -------------------------------------------------------------------- |\n| ERR-EXE-01 | Gate command failed                 | Fix lint, typecheck, or test errors in your code                     |\n| ERR-EXE-02 | Copilot execution failed            | Check Copilot authentication and permissions                         |\n| ERR-EXE-03 | Max iterations reached              | Review progress and increase `--max-iterations` if needed            |\n| ERR-EXE-04 | Max fix attempts exceeded           | Review gate failures and fix issues manually                         |\n| ERR-EXE-05 | Failed to create directory          | Check file system permissions and disk space                         |\n| ERR-EXE-06 | Failed to write file                | Check file system permissions and disk space                         |\n| ERR-EXE-07 | Agent templates directory not found | Reinstall speci                                                      |\n| ERR-EXE-08 | Failed to copy agent files          | Check file system permissions and disk space                         |\n| ERR-EXE-09 | Failed to read tasks directory      | Check directory permissions and ensure the path exists               |\n| ERR-EXE-10 | Failed to delete during clean       | Check file permissions and ensure no other process has the file open |\n\n### Exit Codes\n\n| Code | Meaning                        |\n| ---- | ------------------------------ |\n| 0    | Success                        |\n| 1    | General error                  |\n| 2    | Invalid command or arguments   |\n| 130  | Interrupted by SIGINT (Ctrl+C) |\n| 143  | Terminated by SIGTERM          |\n\n## Troubleshooting\n\n### \"Copilot CLI not found\"\n\nThe GitHub Copilot CLI must be installed and available in your PATH:\n\n```bash\n# Install via npm\nnpm install -g @github/copilot\n\n# Or via WinGet (Windows)\nwinget install GitHub.Copilot\n\n# Or via Homebrew (macOS/Linux)\nbrew install copilot-cli\n\n# Verify installation\ncopilot --version\n```\n\n### \"Another speci instance is running\"\n\nA lock file from a previous run may still exist:\n\n```bash\n# Check if speci is actually running\n# On Linux/macOS:\nps aux | grep speci\n# On Windows:\ntasklist | findstr speci\n\n# If the process is not running, force past the stale lock\nnpx speci run --force\n\n# Or remove the lock file manually\nrm .speci-lock\n```\n\n### \"Config file not found\"\n\nInitialize speci in your project:\n\n```bash\nnpx speci init\n```\n\n### \"PROGRESS.md file not found\"\n\nGenerate tasks from a plan first. The task command creates the PROGRESS.md file:\n\n```bash\nnpx speci plan -p \"Describe what you want to build\"\nnpx speci task --plan docs/plan.md\n```\n\n### Gate commands failing\n\nSpeci runs gate commands defined in `speci.config.json`. Make sure your project has the corresponding scripts in `package.json`:\n\n```json\n{\n  \"scripts\": {\n    \"lint\": \"eslint .\",\n    \"typecheck\": \"tsc --noEmit\",\n    \"test\": \"vitest run\"\n  }\n}\n```\n\nYou can customize which commands speci runs by editing the `gate.commands` array in `speci.config.json`.\n\n### Verbose mode\n\nUse `--verbose` (or `-v`) with any command for detailed output including stack traces, config loading details, state transitions, and timing information:\n\n```bash\nnpx speci run --verbose\n\n# Or set the environment variable\nSPECI_DEBUG=1 npx speci run\n```\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fianchak%2Fspeci","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fianchak%2Fspeci","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fianchak%2Fspeci/lists"}