{"id":31580968,"url":"https://github.com/marcusgoll/spec-flow","last_synced_at":"2025-10-05T21:51:38.731Z","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":"2025-10-05T21:51:38.717Z","avatar_url":"https://github.com/marcusgoll.png","language":"PowerShell","readme":"\u003cdiv align=\"center\"\u003e\n  \u003ch1\u003eSpec-Flow Workflow Kit\u003c/h1\u003e\n  \u003cp\u003e\u003cem\u003eBuild high-quality features faster with repeatable Claude workflows.\u003c/em\u003e\u003c/p\u003e\n\n  \u003cp\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://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/releases\"\u003e\n      \u003cimg src=\"https://img.shields.io/github/v/release/marcusgoll/Spec-Flow\" alt=\"Latest Release\"\u003e\n    \u003c/a\u003e\n    \u003ca href=\"https://github.com/marcusgoll/Spec-Flow/issues\"\u003e\n      \u003cimg src=\"https://img.shields.io/github/issues/marcusgoll/Spec-Flow\" alt=\"GitHub Issues\"\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\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eAn open toolkit that turns product ideas into production launches through Spec-Driven Development.\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cdiv align=\"center\"\u003e\n  \u003cp\u003e\n    \u003ca href=\"#-quick-start\"\u003eQuick Start\u003c/a\u003e •\n    \u003ca href=\"#-why-spec-flow\"\u003eWhy Spec-Flow?\u003c/a\u003e •\n    \u003ca href=\"docs/getting-started.md\"\u003eTutorial\u003c/a\u003e •\n    \u003ca href=\"docs/architecture.md\"\u003eArchitecture\u003c/a\u003e •\n    \u003ca href=\"#-examples\"\u003eExamples\u003c/a\u003e •\n    \u003ca href=\"#-contributing\"\u003eContributing\u003c/a\u003e\n  \u003c/p\u003e\n\u003c/div\u003e\n\n---\n\n## Table of Contents\n\n- [What is Spec-Driven Development?](#what-is-spec-driven-development)\n- [Get Started](#get-started)\n- [Supported AI Agents](#supported-ai-agents)\n- [Script Reference](#script-reference)\n- [Core Philosophy](#core-philosophy)\n- [Development Phases](#development-phases)\n- [Prerequisites](#prerequisites)\n- [Learn More](#learn-more)\n- [Detailed Process](#detailed-process)\n- [Troubleshooting](#troubleshooting)\n- [Packages \u0026 Releases](#packages--releases)\n- [Maintainers](#maintainers)\n- [License](#license)\n\n## 🌟 Why Spec-Flow?\n\nBuilding software with AI assistants is powerful, but without structure, projects drift. You lose context, forget decisions, skip testing, and ship inconsistent features. **Spec-Flow solves this.**\n\n### The Problem Without Spec-Flow\n\n| Challenge | Without Spec-Flow | With Spec-Flow |\n|-----------|-------------------|----------------|\n| **Context Loss** | \"What were we building again?\" after interruptions | NOTES.md tracks all decisions, checkpoints restore context instantly |\n| **Inconsistent Quality** | Features shipped without tests, reviews vary | Every feature follows same rigorous process: spec → plan → implement → review → ship |\n| **Token Waste** | Conversations balloon to 100k+ tokens, Claude slows down | Auto-compaction at 80% budget keeps context efficient (75k/100k/125k per phase) |\n| **No Accountability** | \"Did we test this? Who approved?\" | Auditable artifacts for every phase, approval gates enforced |\n| **Reinventing Process** | Each feature starts from scratch | Reusable templates, proven patterns, documented workflows |\n\n### What You Get\n\n✅ **Repeatable Process** - Every feature follows the same proven workflow (spec → plan → tasks → ship)\n\n✅ **Context Discipline** - Token budgets enforced per phase, auto-compaction prevents context bloat\n\n✅ **Quality Gates** - Automated checks for accessibility, performance, testing, security\n\n✅ **Auditable Trail** - Every decision documented in NOTES.md, every phase produces artifacts\n\n✅ **Faster Velocity** - Skip decision paralysis, let the workflow guide you\n\n✅ **Team Alignment** - Specs reviewed upfront, parallel work enabled, consistent outcomes\n\n### Use Cases\n\n- **Web Apps** - Full-stack features with frontend + backend coordination\n- **APIs** - Contract-first development with automated testing\n- **CLIs** - Command structure definition to distribution\n- **Mobile Apps** - Offline-first architecture with platform-specific handling\n- **Design Systems** - Component libraries with accessibility built-in\n- **Infrastructure** - Terraform modules with security scanning\n- **ML Projects** - Experiment tracking with reproducible pipelines\n\n👉 **See more**: [Use Cases](docs/use-cases.md)\n\n---\n\n## What is Spec-Driven Development?\n\nSpec-Driven Development flips the traditional model: specifications become executable assets that orchestrate planning, implementation, QA, and release. Each Claude command owns a phase of delivery, produces auditable artifacts, and tees up the next specialist.\n\n### The Workflow\n\n```\n💡 Ideas → 🗺️ Roadmap → 📝 Spec → 📋 Plan → ✅ Tasks → 🔍 Analyze →\n💻 Implement → ⚡ Optimize → 👀 Preview → 🚀 Staging → ✅ Validate → 🎉 Production\n```\n\n**Key Principle**: Plan your roadmap first, then write specifications from prioritized features, and let AI agents execute faithfully.\n\n## 🚀 Quick Start\n\n### Option 1: NPM (Recommended)\n\nInstall Spec-Flow with a single command:\n\n```bash\n# Initialize in current directory\nnpx spec-flow init\n\n# Or specify target directory\nnpx spec-flow init --target ./my-project\n```\n\n### Option 2: Manual Installation\n\nClone and run the interactive wizard:\n\n```bash\n# 1. Clone Spec-Flow repository\ngit clone https://github.com/marcusgoll/Spec-Flow.git\ncd Spec-Flow\n\n# 2. Run the installation wizard (Windows)\npowershell -File .spec-flow/scripts/powershell/install-wizard.ps1\n\n# OR (macOS/Linux)\n./.spec-flow/scripts/bash/install-wizard.sh\n```\n\n**What gets installed:**\n- ✅ `.claude/` - Agents, commands, and settings\n- ✅ `.spec-flow/` - Scripts, templates, and memory\n- ✅ `CLAUDE.md` - Workflow documentation\n- ✅ `QUICKSTART.md` - Quick start guide (copied to your project)\n- ✅ Memory files initialized with defaults\n\n**Next steps after installation:**\n\n1. **Read the guide** - Open `QUICKSTART.md` in your project\n2. **Open in Claude Code** - Navigate to your project directory\n3. **Set up your project** (optional but recommended):\n   ```bash\n   /constitution         # Interactive Q\u0026A for engineering standards\n   /roadmap              # Plan and prioritize features with ICE scoring\n   /design-inspiration   # Curate visual references for consistency\n   ```\n4. **Start building:**\n   ```bash\n   /spec-flow \"my-feature\"  # Create specification\n   /flow \"my-feature\"       # Automate full workflow\n   ```\n\n👉 **Full guide**: [QUICKSTART.md](QUICKSTART.md) | **Detailed tutorial**: [Getting Started](docs/getting-started.md)\n\n---\n\n## Get Started\n\n### 1. Install the toolkit\n\n**From npm (fastest):**\n\n```bash\nnpm install -g spec-flow\n# or use npx without a global install\nnpx spec-flow init --target ./my-project\n```\n\n**From source:**\n\nClone this repository and ensure you have either PowerShell 7.3+ (`pwsh`) or a POSIX shell (`bash`) plus Python 3.10+ available. Scripts live under `.spec-flow/scripts/powershell/` and `.spec-flow/scripts/bash/`.\n\n**Full installation guide**: [docs/installation.md](docs/installation.md)\n\nCopy `.claude/settings.example.json` to `.claude/settings.local.json` and update the allow list for your environment.\n\n### 2. Establish principles\n\nRun the `/constitution` command in Claude to document the engineering principles that guard every feature. Store the output in `.spec-flow/memory/constitution.md`.\n\n### 3. Build your roadmap\n\nUse `/roadmap` to add features, prioritize them with ICE scoring (Impact × Confidence / Effort), and organize them into:\n- **Backlog** - Ideas to consider\n- **Next** - Top 5-10 prioritized features\n- **In Progress** - Currently being built\n- **Shipped** - Completed features\n\n### 4. Kick off a feature\n\nSelect a feature from your roadmap and use `/spec-flow \"\u003cfeature-slug\u003e\"` to initiate the workflow. Follow with `/plan`, `/tasks`, `/implement`, and the remaining commands until `/phase-2-ship` completes.\n\nFor a fully automated pass, use `/flow \"\u003cfeature-slug\u003e\"` to step through the entire state machine with manual gates for approvals.\n\n## Supported AI Agents\n\n| Agent | Status | Notes |\n|-------|--------|-------|\n| Claude Code | Supported | Optimised for slash-command workflow. |\n| Cursor | Supported | Pair with `.spec-flow/memory/` context files. |\n| Windsurf | Supported | Share roadmap + constitution for planning. |\n| GitHub Copilot | Partial | Works for code edits; manual command execution. |\n| Gemini CLI | Experimental | Requires manual prompt translation. |\n\n## Script Reference\n\nEvery automation script is provided in both PowerShell (`.ps1`) and shell (`.sh`) form. Pick the variant that matches your environment.\n\n| Task | Windows / Cross-platform | macOS / Linux |\n|------|--------------------------|---------------|\n| Validate prerequisites | `pwsh -File .spec-flow/scripts/powershell/check-prerequisites.ps1 -Json` | `.spec-flow/scripts/bash/check-prerequisites.sh --json` |\n| Scaffold a feature | `pwsh -File .spec-flow/scripts/powershell/create-new-feature.ps1 \"Dashboard revamp\"` | `.spec-flow/scripts/bash/create-new-feature.sh \"Dashboard revamp\"` |\n| Estimate token budget | `pwsh -File .spec-flow/scripts/powershell/calculate-tokens.ps1 -FeatureDir specs/015-dashboard` | `.spec-flow/scripts/bash/calculate-tokens.sh --feature-dir specs/015-dashboard` |\n| Compact context | `pwsh -File .spec-flow/scripts/powershell/compact-context.ps1 -FeatureDir specs/015-dashboard` | `.spec-flow/scripts/bash/compact-context.sh --feature-dir specs/015-dashboard` |\n\n\u003e Additional scripts such as `enable-auto-merge`, `wait-for-ci`, and `update-agent-context` also ship with `.sh` wrappers that delegate to PowerShell so you can run them from a POSIX shell while we build native equivalents.\n\n## Core Philosophy\n\n1. **Specification first**  every artifact traces back to an explicit requirement.\n2. **Agents as teammates**  commands encode expectations so assistants stay aligned.\n3. **Context discipline**  token budgets are measured, compacted, and recycled.\n4. **Ship in stages**  staging and production have dedicated rituals with human gates.\n\n## Development Phases\n\n| Phase | Command | Primary Outputs |\n|-------|---------|-----------------|\n| -1 | `/roadmap` | `roadmap.md` with ICE-scored features |\n| 0 | `/spec-flow` | `spec.md`, `NOTES.md`, `visuals/README.md` |\n| 0.5 | `/clarify` | Clarification log inside the spec |\n| 1 | `/plan` | `plan.md`, `research.md` |\n| 2 | `/tasks` | `tasks.md` with acceptance criteria |\n| 3 | `/analyze` | Risk analysis report |\n| 4 | `/implement` | Implementation checklist \u0026 validation hooks |\n| 5 | `/optimize` | Code review summary \u0026 optimization plan |\n| 6 | `/debug` | Error triage and remediation plan |\n| 7 | `/preview` | Release notes \u0026 preview checklist |\n| 8 | `/phase-1-ship` | Staging deployment ritual |\n| 9 | `/validate-staging` | Sign-off for staging |\n| 10 | `/phase-2-ship` | Production launch and follow-up |\n| - | `/compact [phase]` | **Optional:** Reduce token usage between phases |\n\n**Context Management**: The `/compact` command is optional and reduces token usage by summarizing verbose artifacts. Use it between phases when context feels heavy or when suggested by auto-progression. In `/flow` mode, compaction happens automatically.\n\n## Prerequisites\n\n- Git 2.39+\n- Python 3.10+\n- PowerShell 7.3+ (`pwsh`) for Windows scripts\n- Bash 5+ (or Zsh) for shell scripts\n- Claude Code access with slash-command support\n\nOptional:\n- GitHub CLI (`gh`) for auto-merge helpers\n- Pester 5 for PowerShell test suites\n\n## 📚 Examples\n\n### Complete Working Example: Dark Mode Toggle\n\nExplore a fully-documented feature workflow in [`specs/001-example-feature/`](specs/001-example-feature/):\n\n```\nspecs/001-example-feature/\n├── spec.md                    # Feature specification with user scenarios\n├── NOTES.md                   # Progress tracking and decisions\n├── artifacts/\n│   ├── plan.md                # Implementation plan with architecture\n│   ├── tasks.md               # 28 tasks with acceptance criteria\n│   ├── analysis-report.md     # Risk assessment (0 critical issues)\n│   ├── optimization-report.md # Performance metrics (145ms avg)\n│   └── release-notes.md       # v1.2.0 release notes\n└── visuals/\n    └── README.md              # Design references and color tokens\n```\n\n**What's included**:\n- Complete specification with FR/NFR requirements\n- 28 tasks broken down across 5 implementation phases\n- Performance benchmarks (27% better than target)\n- WCAG 2.1 AA accessibility compliance\n- Cross-browser testing matrix\n- Release notes for v1.2.0\n\n👉 **Browse the example**: [`specs/001-example-feature/`](specs/001-example-feature/)\n\n---\n\n## Learn More\n\n- [`docs/architecture.md`](docs/architecture.md) — how the repository fits together\n- [`docs/commands.md`](docs/commands.md) — quick lookup for every slash command\n- [`docs/getting-started.md`](docs/getting-started.md) — step-by-step tutorial for your first feature\n- [`docs/installation.md`](docs/installation.md) — platform-specific installation guide\n- [`docs/troubleshooting.md`](docs/troubleshooting.md) — common issues and solutions\n- [`docs/use-cases.md`](docs/use-cases.md) — examples for different project types\n- [`PUBLISHING.md`](PUBLISHING.md) — release checklist for npm \u0026 GitHub Packages\n- [`AGENTS.md`](AGENTS.md) — contributor guide for working in this repo\n- [`CONTRIBUTING.md`](CONTRIBUTING.md) — branching, reviews, and release process\n\n## Detailed Process\n\n1. Run `.spec-flow/scripts/bash/check-prerequisites.sh --json` (or the PowerShell variant) to ensure your environment is ready.\n2. Build your roadmap with `/roadmap` - add features, prioritize with ICE scoring, and organize into Backlog → Next → In Progress → Shipped.\n3. Select a feature from the roadmap and launch `/spec-flow \"\u003cfeature-slug\u003e\"` in Claude to scaffold the spec from the roadmap entry.\n4. Progress through `/clarify`, `/plan`, `/tasks`, and `/analyze`, addressing blockers as they appear.\n5. Use `calculate-tokens` to watch context budgets and `compact-context` to summarise when approaching thresholds.\n6. Walk the release staircase: `/preview`, `/phase-1-ship`, `/validate-staging`, `/phase-2-ship`.\n7. The feature automatically moves to \"Shipped\" in the roadmap, and changelog is updated with the release.\n\n## Packages \u0026 Releases\n\n- **npm**: Published as [`spec-flow`](https://www.npmjs.com/package/spec-flow). Install globally with `npm install -g spec-flow` or run one-off with `npx spec-flow`.\n- **GitHub Packages**: The `Publish Packages` workflow mirrors each release to GitHub Packages under the scoped name `@marcusgoll/spec-flow`, enabling the repository's *Packages* tab.\n- **Automation**: Creating a GitHub release (or manually running the workflow) triggers the dual publish. Set the `NPM_TOKEN` repository secret with an npm automation token that has `publish` rights; GitHub packages use the built-in `GITHUB_TOKEN`.\n\n## Troubleshooting\n\n| Issue | Resolution |\n|-------|------------|\n| `pwsh` command not found | Install PowerShell 7 (`winget install Microsoft.PowerShell` or `brew install --cask powershell`). |\n| Shell script reports missing feature directory | Run `/spec-flow` first or use `create-new-feature` to scaffold `specs/NNN-slug`. |\n| Token estimate returns zero | Verify files are UTF-8 encoded and not empty. |\n| Context delta lacks checkpoints | Ensure `NOTES.md` records checkpoints prefixed with `-`. |\n\n## Maintainers\n\n- Marcus Gollahon (@marcusgoll)\n- Community contributors  join via pull requests!\n\n## License\n\nReleased under the [MIT License](LICENSE).\n\n\n\n","funding_links":[],"categories":[],"sub_categories":[],"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"}