{
  "markdown": "<div align=\"center\">\n  <h1>Spec-Flow</h1>\n  <p><strong>Ship features faster with AI-powered spec-driven development.</strong></p>\n\n  <p>\n    <a href=\"https://www.npmjs.com/package/spec-flow\">\n      <img src=\"https://img.shields.io/npm/v/spec-flow.svg?logo=npm&color=CB3837\" alt=\"npm package\">\n    </a>\n    <a href=\"https://github.com/marcusgoll/Spec-Flow/blob/main/LICENSE\">\n      <img src=\"https://img.shields.io/badge/license-MIT-blue.svg\" alt=\"License: MIT\">\n    </a>\n    <a href=\"https://github.com/marcusgoll/Spec-Flow/actions/workflows/ci.yml\">\n      <img src=\"https://img.shields.io/github/actions/workflow/status/marcusgoll/Spec-Flow/ci.yml?branch=main\" alt=\"CI Status\">\n    </a>\n    <a href=\"https://github.com/marcusgoll/Spec-Flow/stargazers\">\n      <img src=\"https://img.shields.io/github/stars/marcusgoll/Spec-Flow?style=social\" alt=\"GitHub Stars\">\n    </a>\n  </p>\n</div>\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 (< 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 (> 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 (< 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 & 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&A 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&A, 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), < 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, < 30s, warn & continue)\n  - Level 2: Full quality gates (`/optimize` phase, 10-15m, block deployment)\n  - Level 3: Critical pre-flight (`/ship`, < 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<div align=\"center\">\n  <p>Built by <a href=\"https://x.com/marcusgoll\">@marcusgoll</a></p>\n  <p>\n    <a href=\"https://github.com/marcusgoll/Spec-Flow/issues\">Report a bug</a> ·\n    <a href=\"https://github.com/marcusgoll/Spec-Flow/discussions\">Ask a question</a> ·\n    <a href=\"https://github.com/marcusgoll/Spec-Flow/stargazers\">Star on GitHub</a>\n  </p>\n</div>\n",
  "bytes": 17530,
  "sha": "ff54862b0eca6e819960a0c6687a3ed77bdc4105eb900e8943f7006f21f9077c",
  "repo_slug": "marcusgoll/spec-flow",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_marcusgoll_spec_flow_78675da2/readme"
}