{"id":51635028,"url":"https://github.com/griddynamics/specflow","last_synced_at":"2026-07-13T13:01:38.759Z","repository":{"id":368402999,"uuid":"1273429446","full_name":"griddynamics/specflow","owner":"griddynamics","description":"Agentic harness for large-scale AI code generation - by Grid Dynamics","archived":false,"fork":false,"pushed_at":"2026-07-07T14:11:14.000Z","size":2966,"stargazers_count":6,"open_issues_count":6,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-07T14:18:18.235Z","etag":null,"topics":["agentic-sdlc","ai","ai-agents","ai-native","code-generation","developer-tools","griddynamics","llm","mcp-server","python","specflow"],"latest_commit_sha":null,"homepage":"","language":"Python","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/griddynamics.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","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-06-18T14:11:01.000Z","updated_at":"2026-07-07T14:15:28.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/griddynamics/specflow","commit_stats":null,"previous_names":["griddynamics/specflow"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/griddynamics/specflow","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/griddynamics%2Fspecflow","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/griddynamics%2Fspecflow/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/griddynamics%2Fspecflow/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/griddynamics%2Fspecflow/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/griddynamics","download_url":"https://codeload.github.com/griddynamics/specflow/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/griddynamics%2Fspecflow/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35423100,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-13T02:00:06.543Z","response_time":119,"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":["agentic-sdlc","ai","ai-agents","ai-native","code-generation","developer-tools","griddynamics","llm","mcp-server","python","specflow"],"created_at":"2026-07-13T13:01:38.013Z","updated_at":"2026-07-13T13:01:38.754Z","avatar_url":"https://github.com/griddynamics.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\u003cimg src=\"docs/logo/specflow-logo.png\" alt=\"SpecFlow logo\" width=\"200\"/\u003e\n\n### Agentic Harness for Large-Scale Code Generation\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n[![PyPI version](https://img.shields.io/pypi/v/gd-specflow?label=gd-specflow)](https://pypi.org/project/gd-specflow/)\n[![Python 3.13](https://img.shields.io/badge/python-3.13-blue.svg)](https://www.python.org/downloads/)\n[![Publish to PyPI](https://github.com/griddynamics/specflow/actions/workflows/publish-mcp.yml/badge.svg)](https://github.com/griddynamics/specflow/actions/workflows/publish-mcp.yml)\n\n\u003c/div\u003e\n\n---\nAI agent harness for automated code generation and complexity estimation.\nMultiple deployable codebases built by multiple SOTA AI models.\nWhen their code complexity scores align, it proves the specs are complete.\n\nSpecFlow is an AI agent harness that automates code generation, deployment, and testing through parallel AI agents in isolated, sandboxed execution environments.\n\nValidator agents continuously assess, resume, and refine work until delivery standards are met.\n\n\n\u003cimg src=\"docs/images/specflow-iconography.png\" alt=\"SpecFlow iconography\" style=\"max-width: 100vw; width: 100%; display: block; margin: 0 auto;\" /\u003e\n\n\n[https://github.com/user-attachments/assets/0783c394-1bf0-449f-a36e-1d46e899661c](https://github.com/user-attachments/assets/0783c394-1bf0-449f-a36e-1d46e899661c)\n\n\n\u003c!-- GETTING STARTED --\u003e\n## Getting Started\n\n\n\n### Software\n\n\n| Requirement | Notes                                                                                                        |\n| ----------- | ------------------------------------------------------------------------------------------------------------ |\n| Docker      | Container runtime for the harness sandbox. [Install Docker](https://docs.docker.com/get-started/get-docker/) |\n| `uv`        | Python package manager. Install via `brew install uv` or [see docs](https://github.com/astral-sh/uv)         |\n| IDE         | SpecFlow is used as MCP in a IDE with agentic AI enabled: Cursor, Claude Code, Copilot, Gemini etc. This is the users project.         |\n\n\n\n\n### Keys and Tokens\n\n\n| Key                          | Name in `.env`                              | Notes                                                                                                                                            |\n| ---------------------------- | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |\n| GitHub Personal Access Token | `GITHUB_TOKEN`                              | For disposable workspace repos. Scope: `repo` + `read:user` + `workflow` `repo,read:user`. Advan                           |\n| P10Y API key                 | `P10Y_API_KEY`                              | Code complexity scoring. [Setup guide](docs/quickstart-compass.md)                                                                               |\n| LLM provider key             | `OPENROUTER_API_KEY` or `ANTHROPIC_API_KEY` | One key required. [Get OpenRouter key](https://openrouter.ai/keys) (default) or [Get Anthropic key](https://console.anthropic.com/settings/keys) |\n\n\n\n\n### Installation\n\nFew simple steps to get you going:\n\n- clone repo\n  ```sh\n  git clone https://github.com/griddynamics/specflow.git \u0026\u0026 cd specflow\n  ```\n- install Specflow (includes the Terminal UI that guides you through onboarding)\n  ```sh\n  uv tool install --editable ./mcp_server\n  ```\n- start Specflow app and follow instructions\n  ```\n  specflow tui\n  ```\n\n\n\u003e [!Important]\n\u003e Specflow Harness Sandbox is now running locally.\n\u003e **Easiest:** in `specflow tui`, press **`c`** (*Add MCP to AI tool*) — the setup screen detects\n\u003e Claude Code, Gemini CLI, and Cursor and wires SpecFlow up for you (one key), with an honest\n\u003e connected/added/failed status per client.\n\u003e Prefer to do it by hand? Copy-paste the content of `.specflow-local/mcp-config.json` into your client.\n\n\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003ctd align=\"center\"\u003e\u003cimg src=\"https://cdn.simpleicons.org/cursor/000000\" width=\"40\" height=\"40\" alt=\"Cursor\"/\u003e\u003cbr\u003e\u003cb\u003eCursor\u003c/b\u003e\u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\u003cimg src=\"https://cdn.simpleicons.org/claude/D4A27F\" width=\"40\" height=\"40\" alt=\"Claude Code\"/\u003e\u003cbr\u003e\u003cb\u003eClaude Code\u003c/b\u003e\u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\u003cimg src=\"https://cdn.simpleicons.org/claude/D4A27F\" width=\"40\" height=\"40\" alt=\"Claude Desktop\"/\u003e\u003cbr\u003e\u003cb\u003eClaude Desktop\u003c/b\u003e\u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\u003cimg src=\"https://cdn.simpleicons.org/githubcopilot/000000\" width=\"40\" height=\"40\" alt=\"GitHub Copilot\"/\u003e\u003cbr\u003e\u003cb\u003eCopilot\u003c/b\u003e\u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\u003cimg src=\"https://cdn.simpleicons.org/googlegemini/8E75B2\" width=\"40\" height=\"40\" alt=\"Gemini CLI\"/\u003e\u003cbr\u003e\u003cb\u003eGemini CLI\u003c/b\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n...and any other IDE or client that supports the [Model Context Protocol](https://modelcontextprotocol.io).\n\n\n\u003c!-- USAGE --\u003e\n## Usage\n\nMCP is now ready to use in any project. Prompt your IDE agent to talk to the harness.\n\nLet's say specification files are in `specs` directory, you can follow these steps:\n\n1. Start a new project in IDE and put your specs files into `specs` directory\n   ```text\n   specs/\n   |-- product-requirements.md\n   |-- user-flows.pdf\n   \\-- acceptance-criteria.md\n   ```\n2. Check your specification completeness using `check_specification_completeness`  tool\n\n   ```text\n   Use SpecFlow MCP to check specification completeness in specs directory\n   ```\n\n3. Create a detailed plan using our `run_planning` tool\n\n   ```text\n   Create implementation plan using SpecFlow MCP\n   ```\n\n4. When you are happy with the plan, run generation using `run_generation` as above\n   ```text\n   Run generation with SpecFlow MCP\n   ```\n\n5. Generation usually takes many hours, use our TUI to monitor progress and receive Desktop Notifications:\n\n   ```sh\n   # Any terminal\n   specflow tui\n   ```\n\n\u003cimg src=\"docs/images/tui-screen.png\" alt=\"SpecFlow iconography\" style=\"max-width: 100vw; width: 100%; display: block; margin: 0 auto;\" /\u003e\n\n\n6. When the generation has been completed, you can retrieve the results and P10Y reports from harness:\n   ```text\n   Download outputs using Specflow MCP\n   ```\n   **The rule of thumb is: if the P10Y score spread is low, then your specification is ready!**\n\n7. Use the built-in prompt to compare the variants and identify their strong and weak sides, together with a plan to automatically assemble the best variant.\n   ```text\n   use SpecFlow MCP prompt: specflow-compare-variants\n   ```\n\n\n### MCP Tools\n\n\n| Tool                               | Description                                                 |\n| ---------------------------------- | ----------------------------------------------------------- |\n| `check_specification_completeness` | Analyze specs for gaps and contradictions (local)           |\n| `run_planning`                     | Generate a phased implementation plan (local)               |\n| `read_document`                    | Extract PDF/DOCX/PPTX/XLSX/CSV to markdown (local)          |\n| `run_generation`                   | Upload and launch parallel codegen on the backend (2-8 hrs) |\n| `check_status`                     | Poll generation progress                                    |\n| `download_outputs`                 | Download archived artifacts from a completed run            |\n| `retry_generation`                 | Retry a failed generation                                   |\n\n\n\n\u003c!-- IF YOU WANT TO GO DEEPER --\u003e\n## If you want to go deeper\n### Install only SpecFlow skills\n\nWe have portable set of skills that is normally used as preparation phase for Human-In-The-Loop AI assisted specification checks and planning.\n\nExample for Claude Code:\n```bash\n/plugin marketplace add griddynamics/specflow\n/plugin install specflow\n```\n\n\n### SpecFlow Detailed Overview\n\n[https://github.com/user-attachments/assets/ea1dd95d-5742-4c51-bf2c-c2cb582669c3](https://github.com/user-attachments/assets/ea1dd95d-5742-4c51-bf2c-c2cb582669c3)\n\n\nFull MCP config and usage: **[MCP_USER.md](MCP_USER.md)**\n\n\nFull MCP API reference: **[docs/mcp/API_REFERENCE.md](docs/mcp/API_REFERENCE.md)**\n\n\nDetailed SpecFlow harness instructions: [QUICKSTART.md](QUICKSTART.md)\n\n\n\u003e [!Important]\n\u003e AI agents work in **scratchpad repos** that are reset before each run — we create them for you. \n\u003e **Do not point SpecFlow at repositories with code or history you want to keep.\n\u003e ** The managed SpecFlow service is for Grid Dynamics employees only. Open-source users should run the local quickstart.\n\n\n\n### Documentation\n\n\n| Document                                                                 | Description                                 |\n| ------------------------------------------------------------------------ | ------------------------------------------- |\n| [QUICKSTART.md](QUICKSTART.md)                                           | Local setup and first run                   |\n| [CONTRIBUTING.md](docs/CONTRIBUTING.md)                                  | How to contribute — workflow and PR checklist |\n| [CLAUDE.md](CLAUDE.md)                                                   | Development protocol and STEEL commandments |\n| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)                             | System design and data flow                 |\n| [docs/mcp/API_REFERENCE.md](docs/mcp/API_REFERENCE.md)                   | MCP tool reference                          |\n| [docs/backend/DEVELOPMENT.md](docs/backend/DEVELOPMENT.md)               | Backend development guide                   |\n| [docs/backend/API_REFERENCE.md](docs/backend/API_REFERENCE.md)           | REST API reference                          |\n| [docs/operations/TROUBLESHOOTING.md](docs/operations/TROUBLESHOOTING.md) | Troubleshooting guide                       |\n| [docs/IDE-SETUP.md](docs/IDE-SETUP.md)                                   | IDE configuration (Cursor + Claude Code)    |\n| [docs/examples/deployment-spec-example.md](docs/examples/deployment-spec-example.md) | Example spec for agentic deployment + E2E tests |\n| [SECURITY.md](SECURITY.md)                                               | Security policy and vulnerability reporting |\n\n\n\n\u003c!-- CONTACT --\u003e\n## Contact\n\nQuestions, feedback, or anything that doesn't fit a GitHub issue: [specflow@griddynamics.com](mailto:specflow@griddynamics.com)\n\nFound a security vulnerability? Please report it privately per [SECURITY.md](SECURITY.md) rather than opening a public issue.\n\n\n\u003c!-- LICENSE --\u003e\n## License\n\n[MIT](LICENSE) — Copyright (c) 2024 Grid Dynamics International, Inc.\n\n\n\u003cp align=\"right\"\u003e(\u003ca href=\"#readme-top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgriddynamics%2Fspecflow","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgriddynamics%2Fspecflow","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgriddynamics%2Fspecflow/lists"}