{"id":31580968,"url":"https://github.com/marcusgoll/spec-flow","last_synced_at":"2026-05-04T17:33:31.633Z","repository":{"id":317943294,"uuid":"1069457150","full_name":"marcusgoll/Spec-Flow","owner":"marcusgoll","description":"Turn product ideas into production launches with Spec-Driven Development. Repeatable Claude Code workflows with quality gates, token budgets, and auditable artifacts.","archived":false,"fork":false,"pushed_at":"2025-10-04T01:46:12.000Z","size":216,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-04T03:36:14.792Z","etag":null,"topics":["ai-agents","ai-assisted-development","ai-workflows","automation","bash","claude","claude-ai","claude-code","developer-tools","documentation","powershell","productivity","spec-driven-development","workflow","workflow-automation"],"latest_commit_sha":null,"homepage":"https://github.com/marcusgoll/Spec-Flow","language":"PowerShell","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/marcusgoll.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-10-04T01:21:22.000Z","updated_at":"2025-10-04T01:59:36.000Z","dependencies_parsed_at":"2025-10-04T03:36:17.854Z","dependency_job_id":null,"html_url":"https://github.com/marcusgoll/Spec-Flow","commit_stats":null,"previous_names":["marcusgoll/spec-flow"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/marcusgoll/Spec-Flow","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcusgoll%2FSpec-Flow","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcusgoll%2FSpec-Flow/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcusgoll%2FSpec-Flow/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcusgoll%2FSpec-Flow/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/marcusgoll","download_url":"https://codeload.github.com/marcusgoll/Spec-Flow/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcusgoll%2FSpec-Flow/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278526242,"owners_count":26001325,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-05T02:00:06.059Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["ai-agents","ai-assisted-development","ai-workflows","automation","bash","claude","claude-ai","claude-code","developer-tools","documentation","powershell","productivity","spec-driven-development","workflow","workflow-automation"],"created_at":"2025-10-05T21:51:36.586Z","updated_at":"2026-05-04T17:33:31.626Z","avatar_url":"https://github.com/marcusgoll.png","language":"PowerShell","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003ch1\u003eSpec-Flow\u003c/h1\u003e\n  \u003cp\u003e\u003cstrong\u003eShip features faster with AI-powered spec-driven development.\u003c/strong\u003e\u003c/p\u003e\n\n  \u003cp\u003e\n    \u003ca href=\"https://www.npmjs.com/package/spec-flow\"\u003e\n      \u003cimg src=\"https://img.shields.io/npm/v/spec-flow.svg?logo=npm\u0026color=CB3837\" alt=\"npm package\"\u003e\n    \u003c/a\u003e\n    \u003ca href=\"https://github.com/marcusgoll/Spec-Flow/blob/main/LICENSE\"\u003e\n      \u003cimg src=\"https://img.shields.io/badge/license-MIT-blue.svg\" alt=\"License: MIT\"\u003e\n    \u003c/a\u003e\n    \u003ca href=\"https://github.com/marcusgoll/Spec-Flow/actions/workflows/ci.yml\"\u003e\n      \u003cimg src=\"https://img.shields.io/github/actions/workflow/status/marcusgoll/Spec-Flow/ci.yml?branch=main\" alt=\"CI Status\"\u003e\n    \u003c/a\u003e\n    \u003ca href=\"https://github.com/marcusgoll/Spec-Flow/stargazers\"\u003e\n      \u003cimg src=\"https://img.shields.io/github/stars/marcusgoll/Spec-Flow?style=social\" alt=\"GitHub Stars\"\u003e\n    \u003c/a\u003e\n  \u003c/p\u003e\n\u003c/div\u003e\n\n---\n\nSpec-Flow is a workflow toolkit for [Claude Code](https://claude.ai/code) that transforms how you build software with AI. Instead of ad-hoc prompting, you get a structured pipeline that takes ideas from specification to production.\n\n```\n/feature \"add user authentication\"\n```\n\nThat's it. Spec-Flow handles the rest: writing specs, planning architecture, breaking down tasks, implementing with TDD, running quality gates, and deploying.\n\n## Why Spec-Flow?\n\n| Without Spec-Flow | With Spec-Flow |\n|-------------------|----------------|\n| \"What were we building again?\" | Every decision tracked in NOTES.md |\n| Features shipped without tests | TDD enforced, quality gates block bad code |\n| Context bloat slows Claude down | Auto-compaction keeps context efficient |\n| Each feature starts from scratch | Reusable patterns, proven workflows |\n| \"Did we test this? Who approved?\" | Auditable artifacts for every phase |\n\n## Quick Start\n\n### 1. Install\n\n```bash\nnpx spec-flow init\n```\n\nThis copies workflow files directly into your project (`.claude/`, `.spec-flow/`, `CLAUDE.md`). No dependency is added to your `package.json` — Spec-Flow becomes part of your codebase.\n\n`npx spec-flow ...` is the installer and maintenance CLI. After installation,\nyou use the installed workflow commands such as `/feature`, `/plan`, and\n`/ship` inside your tool environment.\n\n### 2. Build your first feature\n\n```bash\n/feature \"add dark mode toggle\"\n```\n\nSpec-Flow runs you through:\n\n```\nspec → plan → tasks → implement → optimize → ship\n```\n\nEach phase produces artifacts, runs quality checks, and hands off cleanly to the next.\n\n### 3. That's it\n\nYour feature is deployed. All decisions documented. Tests passing. Ready for the next one.\n\n### Staying Updated\n\nCheck for updates anytime:\n\n```bash\nnpx spec-flow status\n```\n\nUpdate to the latest version:\n\n```bash\nnpx spec-flow update\n```\n\nFor CI/CD pipelines, use `--check` to fail if outdated:\n\n```bash\nnpx spec-flow status --check\n```\n\n---\n\n## The Workflow\n\n### Features (\u003c 16 hours)\n\nFor focused work on a single subsystem:\n\n```bash\n/feature \"user profile editing\"     # Start the workflow\n/feature continue                   # Resume after a break\n```\n\n### Epics (\u003e 16 hours)\n\nFor complex work spanning multiple subsystems:\n\n```bash\n/epic \"OAuth 2.1 authentication\"    # Multi-sprint orchestration\n/epic continue                      # Resume epic work\n```\n\nEpics break down into parallel sprints with locked API contracts, giving you 3-5x velocity through parallelization.\n\n### Quick fixes (\u003c 30 min)\n\nFor small changes that don't need the full workflow:\n\n```bash\n/quick \"fix login button alignment\"\n```\n\n## Commands\n\n### Core Workflow\n\n| Command | What it does |\n|---------|--------------|\n| `/feature \"name\"` | Start a feature workflow |\n| `/epic \"goal\"` | Start a multi-sprint epic |\n| `/quick \"fix\"` | Fast path for small changes |\n| `/help` | Context-aware guidance |\n\n### Phase Commands\n\n| Command | Phase |\n|---------|-------|\n| `/spec` | Generate specification |\n| `/plan` | Create implementation plan |\n| `/tasks` | Break down into TDD tasks |\n| `/implement` | Execute tasks |\n| `/optimize` | Run quality gates |\n| `/ship` | Deploy to staging/production |\n\n### Project Setup\n\n| Command | What it does |\n|---------|--------------|\n| `/init-project` | Generate project documentation |\n| `/init-preferences` | Configure workflow defaults |\n| `/roadmap` | Manage features via GitHub Issues |\n\nSee [the public installed workflow command reference](docs/commands.md) for\nthe slash-command surface. For installer and maintenance commands, run\n`npx spec-flow help`.\n\n## How It Works\n\n### 1. Specification Phase\n\n```bash\n/spec \"user authentication\"\n```\n\nGenerates `spec.md` with:\n\n- User scenarios in Gherkin format\n- Functional and non-functional requirements\n- Acceptance criteria\n- Success metrics\n\n### 2. Planning Phase\n\n```bash\n/plan\n```\n\nCreates `plan.md` with:\n\n- Architecture decisions\n- Component breakdown\n- Code reuse opportunities\n- Risk assessment\n\n### 3. Task Breakdown\n\n```bash\n/tasks\n```\n\nProduces `tasks.md` with:\n\n- 20-30 concrete implementation tasks\n- TDD sequencing (Red → Green → Refactor)\n- Dependency ordering\n- Acceptance criteria per task\n\n### 4. Implementation\n\n```bash\n/implement\n```\n\nExecutes tasks with:\n\n- Test-first development\n- Specialist agents (backend, frontend, database)\n- Parallel batch execution\n- Automatic error recovery\n\n### 5. Quality Gates\n\n```bash\n/optimize\n```\n\nRuns parallel checks:\n\n- Performance benchmarks\n- Security scanning\n- Accessibility audits\n- Code review\n- Test coverage validation\n\n### 6. Deployment\n\n```bash\n/ship\n```\n\nHandles:\n\n- Staging deployment\n- Validation checks\n- Production promotion\n- Rollback capability\n\n## Installed Project Structure\n\nThis is the typical consumer-project layout after `npx spec-flow init`. It is\nnot the source repo layout for Spec-Flow itself.\n\n```\nyour-project/\n├── .claude/\n│   ├── commands/         # Slash commands\n│   ├── agents/           # Specialist agent briefs\n│   ├── skills/           # Progressive disclosure content\n│   └── hooks/            # Event handlers\n├── .spec-flow/\n│   ├── scripts/          # Automation scripts\n│   ├── config/           # User preferences\n│   └── templates/        # Artifact templates\n├── specs/\n│   └── NNN-feature/      # Feature workspaces\n├── epics/\n│   └── NNN-epic/         # Epic workspaces\n└── docs/\n    └── project/          # Project documentation\n```\n\n## Using with Gemini CLI\n\nSpec-Flow can be installed as a Gemini CLI extension to bring the same structured workflow to Gemini.\n\n1. **Install**:\n\n    ```bash\n    # From within your project root\n    npx spec-flow install-gemini-extension\n    ```\n\n    *Alternatively, run: `gemini extensions install .` inside your project.*\n\n2. **Use**:\n    The extension provides the same slash commands (`/feature`, `/plan`, etc.) directly within your Gemini CLI session.\n\n    ```\n    /feature \"add user authentication\"\n    ```\n\n3. **Skills \u0026 Agents**:\n    The Gemini extension automatically adapts Spec-Flow's agents and skills to work within the Gemini environment, allowing you to leverage specialized personas like `backend-dev` or `git-workflow-enforcer`.\n\n## Requirements\n\n- **Claude Code** with slash command support\n- **Git** 2.39+\n- **Python** 3.10+\n- **yq** 4.0+ for YAML processing\n\nWindows users: Install [Git for Windows](https://git-scm.com/download/win) for full compatibility.\n\n## Documentation\n\n| Guide | Description |\n|-------|-------------|\n| [Getting Started](docs/getting-started.md) | Step-by-step tutorial |\n| [Developer Guide](docs/developer-guide.md) | Complete reference |\n| [Commands Reference](docs/commands.md) | All slash commands |\n| [Architecture](docs/architecture.md) | System design |\n| [Troubleshooting](docs/troubleshooting.md) | Common issues |\n\n## Examples\n\nChecked-in example project docs live under\n[`docs/examples/flightpro-sample-project/`](docs/examples/flightpro-sample-project/).\nConsumer projects will create `specs/NNN-feature/` and `epics/NNN-epic/`\nworkspaces after installation.\n\n## 🆕 Recent Updates\n\n### v11.9.1 (April 2026)\n\n**Source-of-Truth Cleanup and Honest Engine Surfaces** - Align the shipped package with the repo's real public and internal boundaries\n\n- **Locked domain contract**: Added `CONTEXT.md` to define source-repo ownership, consumer-project boundaries, and canonical terms\n- **Truthful command surfaces**: Public docs now clearly separate `npx spec-flow ...` installer commands from installed workflow commands\n- **Honest shared engine**: `spec-cli.py` now labels planned surfaces and compatibility shims explicitly instead of failing through missing-file behavior\n- **Safer compatibility path**: Phase shim entrypoints for `tasks`, `validate`, `implement`, and `preview` now fail cleanly with structured guidance\n\n---\n\n### v11.9.0 (December 2025)\n\n**shadcn/ui Integration with Token Bridge Pattern** - Generate OKLCH tokens + shadcn-compatible CSS variables\n\n- **8 customization options**: Style Preset, Base Color, Theme Mode, Icon Library, Font Family, Border Radius, Menu Color, Menu Accent\n- **Token Bridge Pattern**: OKLCH tokens remain source of truth, shadcn CSS variable aliases generated\n- **Brownfield scanning**: Auto-detect and consolidate existing color tokens\n- **Menu theming**: New menu-specific tokens for background, hover, active, and accent styles\n\n**Ultrathink Philosophy Checkpoints** - Deep thinking embedded across all workflow phases\n\n- **Phase checkpoints**: Think Different (spec), Obsess+Simplify (plan), Simplify Ruthlessly (tasks), Craft Don't Code (implement)\n- **Progressive depth**: Trivial → Standard → Complex → Epic with increasing thinking requirements\n- **Assumption inventory**: Question everything before designing\n- **Complexity budgets**: Justify each new component\n\n---\n\n### v11.7.0 (December 2025)\n\n**Auto-Mode for End-to-End Workflow Execution** - Run entire workflows without stopping\n\n- **`--auto` flag**: Added to `/feature` and `/epic` commands\n  - Continue automatically through optimize → ship → finalize\n  - Skip manual approval prompts\n  - Auto-merge PR when CI passes (controlled by preference)\n- **`/ship --auto`**: Full autopilot for deployment phase\n- **New preferences**: `deployment.auto_ship`, `deployment.auto_merge`, `deployment.auto_finalize`\n- **Full autopilot**: `/feature \"add auth\" --auto` runs entire workflow unattended\n\n---\n\n### v11.5.0 (December 2025)\n\n**CLI Version Awareness** - Stay current with automatic update detection\n\n- **Version checking**: `npx spec-flow status` shows installed vs latest version\n  - Fetches from npm registry with graceful offline handling\n  - Clear \"update available\" indicator when behind\n- **CI/CD integration**: `--check` flag exits code 1 if update available\n- **Bug fix**: Fixed healthCheck variable shadowing bug\n\n---\n\n### v11.3.0 (December 2025)\n\n**Git Worktree Integration** - Parallel development with isolated git state per feature/epic\n\n- **worktree-context.sh**: Root orchestration utilities for worktree-based development\n  - Automatic worktree creation for features/epics\n  - Merge and cleanup functions for ship workflow\n  - Task() agent context generation with cd-first pattern\n- **Worktree-aware agents**: Worker agent supports isolated worktree execution\n- **Command integration**: `/feature`, `/implement-epic`, `/ship` now create and manage worktrees\n- **Enabled by default**: `worktrees.auto_create: true` - reduces merge conflicts ~90%\n\n---\n\n### v11.2.0 (December 2025)\n\n**Automatic Regression Test Generation** - Bugs captured as tests to prevent recurrence\n\n- **regression-test-generator skill**: Auto-generates framework-specific regression tests\n  - Framework auto-detection (Jest, Vitest, pytest, Playwright)\n  - Arrange-Act-Assert test structure with error ID references\n  - Links tests back to error-log.md entries\n- **Auto-invoke /debug on test failures**: When tests fail during `/implement`, `/debug` is automatically invoked\n  - Generates regression test for the failure (Step 3.5)\n  - Updates error-log.md with test reference\n- **Continuous checks integration**: Check 7/7 triggers auto-debug on test failures\n\n---\n\n### v11.1.0 (December 2025)\n\n**/quick Command - Task() Orchestrator Pattern** - Consistent architecture across all workflow commands\n\n- **quick-worker agent**: Isolated agent for atomic quick change execution\n  - Domain detection (backend/frontend/test/docs)\n  - Test framework detection and execution\n  - Style guide validation (UI changes)\n  - Automatic commit with conventional message\n- **Delimiter-based returns**: `---COMPLETED---`, `---NEEDS_INPUT---`, `---FAILED---`\n- **Full Q\u0026A support**: Test failure decisions batched to main context\n\n---\n\n### v11.0.0 (December 2025)\n\n**Imperative Task() Architecture** - Commands now properly spawn isolated agents\n\n- **Breaking Change**: `/feature` and `/epic` commands rewritten to use imperative Task() spawning\n  - Phase agents now return structured delimiters (`---COMPLETED---`, `---NEEDS_INPUT---`, `---FAILED---`)\n  - Questions batch to main context - agents return questions, main asks user, re-spawns with answers\n  - Parallel sprint execution for epics via `run_in_background: true`\n- **Ultra-lightweight Orchestrator Pattern**\n  - Read state from disk, spawn isolated agents, handle Q\u0026A, update state\n  - Never carry implementation details in context\n  - Unlimited feature/epic complexity (no context overflow)\n- **Updated Agents**:\n  - `spec-agent.md`, `plan-agent.md`: Delimiter-based return format\n  - `worker.md`: WORKER_COMPLETED, WORKER_FAILED, ALL_DONE, BLOCKED delimiters\n  - `initializer.md`: INITIALIZED, INIT_FAILED delimiters\n\n---\n\n### v10.17.0 (December 2025)\n\n**Domain Memory v2 - Full Phase Isolation** - Revolutionary architecture preventing context overflow\n\n- **Domain Memory System** - Persistent disk-based state for unlimited iterations\n  - Workers pick ONE task, implement, test, update disk, exit\n  - Zero shared context between workers (prevents overflow)\n  - 13-command CLI for state management\n- **Phase Isolation Pattern** - All phases spawn isolated agents via Task()\n  - Question batching: agents return questions, main asks user, agents resume\n  - Resumable at any point via interaction-state.yaml\n- **Project Setup Agents** - Hybrid pattern for /init-project, /prototype, /roadmap\n  - Questionnaire inline, heavy generation isolated\n- **mgrep Semantic Search** - Find code by meaning, not exact text\n  - Integrated as PRIMARY search in anti-duplication skill\n  - Added to agent boot-up rituals\n\n---\n\n### v10.16.0 (December 2025)\n\n**Quality Feedback Loop System** - Multi-agent voting, continuous checks, and perpetual learning\n\n- **Multi-Agent Voting** - Error decorrelation through diverse sampling (MAKER algorithm)\n  - 3-agent voting with k=2 strategy for code reviews, security audits, breaking changes\n  - Temperature variation (0.5, 0.7, 0.9) decorrelates errors across agents\n  - Automatic in `/optimize` phase, manual via `/review --voting`\n- **Continuous Quality Checks** - Lightweight validation during `/implement` phase\n  - Runs after each task batch (3-4 tasks), \u003c 30s performance target\n  - 6 checks: linting (auto-fix), type checking, unit tests, coverage delta, dead code, gap detection\n  - Non-blocking warnings with user choice: fix now, continue, or abort\n- **Progressive Quality Gates** - Three escalating levels throughout workflow\n  - Level 1: Continuous (after each batch, \u003c 30s, warn \u0026 continue)\n  - Level 2: Full quality gates (`/optimize` phase, 10-15m, block deployment)\n  - Level 3: Critical pre-flight (`/ship`, \u003c 2m, block production)\n- **On-Demand Review** - New `/review` command for anytime code review\n  - Quick review (single agent, ~2-3 min) or comprehensive voting review (3 agents, ~5-8 min)\n  - Auto-fix linting, extract file:line references, generate coverage gaps\n- **Perpetual Learning** - Auto-apply proven patterns at workflow start\n  - Performance optimizations (≥0.90 confidence) auto-applied\n  - Anti-patterns (≥0.85 confidence) generate warnings\n  - Custom abbreviations (≥0.95 confidence) auto-expanded\n- **Early Gap Detection** - Find missing implementations before staging validation\n  - Scans for TODO/FIXME/HACK comments, placeholders, edge cases\n  - High-confidence gaps (≥0.8) flag likely issues before deployment\n\n---\n\n### v10.15.1 (December 2025)\n\n**Command Architecture Optimization** - Cleaner package structure with 27% size reduction\n\n- **Consolidated Commands**: Merged 11 archived commands into 4 active commands\n  - `/gate` now handles both CI and security gates\n  - `/create` consolidated 6 creation commands\n  - `/context` merged session management commands\n  - `/init` updated routing to new active paths\n- **Optimized Distribution**: Excluded 48 archived commands from npm package\n  - Package size: 8.5 MB → 6.27 MB (27% reduction)\n  - Archived commands accessible via GitHub source only\n  - All essential functionality in 30 active commands\n- **Moved Essential Commands**: Project, deployment, and meta commands organized in active directories\n\n---\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n## Changelog\n\nSee [CHANGELOG.md](CHANGELOG.md) for version history and release notes.\n\n## License\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n---\n\n\u003cdiv align=\"center\"\u003e\n  \u003cp\u003eBuilt by \u003ca href=\"https://x.com/marcusgoll\"\u003e@marcusgoll\u003c/a\u003e\u003c/p\u003e\n  \u003cp\u003e\n    \u003ca href=\"https://github.com/marcusgoll/Spec-Flow/issues\"\u003eReport a bug\u003c/a\u003e ·\n    \u003ca href=\"https://github.com/marcusgoll/Spec-Flow/discussions\"\u003eAsk a question\u003c/a\u003e ·\n    \u003ca href=\"https://github.com/marcusgoll/Spec-Flow/stargazers\"\u003eStar on GitHub\u003c/a\u003e\n  \u003c/p\u003e\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarcusgoll%2Fspec-flow","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmarcusgoll%2Fspec-flow","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarcusgoll%2Fspec-flow/lists"}