Build high-quality software faster with Spec-Driven Development.
Co-OmniSpec is an open-source toolkit for Spec-Driven Development: specifications become executable and guide your AI coding agent through specification, design, task breakdown, and implementation. This project is a localized and extended adaptation of GitHub Spec Kit, optimized for Cursor and other agent environments.
- What is Spec-Driven Development?
- Get Started
- Features
- Development Workflow
- Supported Environments
- Core Philosophy
- Development Phases
- Project Structure
- Learn More
- Prerequisites
- Troubleshooting
- Support
- Acknowledgments
- License
中文说明 — 请参阅 README-zh-CN.md。
Spec-Driven Development flips the script on traditional development: specifications drive implementation. Instead of code-first, you define the what and why first; your AI agent then uses those specs to produce design artifacts, task lists, and code. Co-OmniSpec provides commands and skills so that:
- Specifications are created from natural language and validated with checklists.
- Technical plans and design docs are generated from specs.
- Tasks are ordered by dependency and ready for step-by-step implementation.
- Implementation follows the plan and respects your project constitution.
Clone this repository, then run the install script from the build/ directory:
Linux / macOS:
./build/install.sh cursor /path/to/your/projectWindows (PowerShell):
.\build\install.ps1 cursor C:\path\to\your\projectThe script copies from Co-OmniSpec's src/agent/ and src/specify/ into your project's .cursor and .specify directories.
Open the project folder in Cursor. The OmniSpec commands will be available in the AI chat.
Use /omni.constitution to create your project's governing principles and development guidelines:
/omni.constitution Create principles focused on code quality, testing standards, user experience consistency, and performance requirements.
Use /omni.specify and describe what you want to build. Focus on the what and why, not the tech stack:
/omni.specify Build a photo album app. Users can create albums, upload photos, and view them in a grid. Albums are flat (no nesting). No login in this first version.
Use /omni.design with your tech stack and architecture choices:
/omni.design Use Vite with minimal libraries. Vanilla HTML, CSS, and JavaScript. Store metadata in a local SQLite database.
Use /omni.tasks to generate an actionable task list from your design:
/omni.tasks
Use /omni.implement to execute all tasks and build the feature:
/omni.implement
For detailed step-by-step instructions, see the Getting Started guide and the User Guide.
| Area | Description |
|---|---|
| Constitution | Project principles and guidelines that steer all later phases. |
| Specify | Turn a short feature description into a full spec (branch, context, spec, requirements checklist). |
| Clarify | Targeted questions to remove ambiguity before design. |
| Design | Generate technical plan, data model, contracts, quickstart from spec. |
| Tasks | Break the plan into ordered, dependency-aware tasks in tasks.md. |
| Implement | Execute tasks from tasks.md in sequence. |
| Analyze | Cross-artifact consistency checks (spec, design, tasks) before implementation. |
| Checklist | Custom checklists to validate requirement quality. |
| Reverse | Reverse-engineer existing code into full specification and context. |
Metamodel and templates support requirements, context, scenarios, logic architecture, functions, entities, interfaces, and relations for both greenfield and brownfield workflows.
/omni.constitution → /omni.specify → /omni.clarify → /omni.design → /omni.tasks → /omni.analyze → /omni.implement
│ │ │ │ │ │
Principles spec.md Clarifications design.md tasks.md Consistency Code
context.md in spec research.md check
checklists data-model.md
optional contracts/
Optional commands: /omni.checklist (requirement checklists), /omni.reverse (code → spec).
| Environment | Support | Notes |
|---|---|---|
| Cursor | Yes | Primary target; slash commands and skills are provided for Cursor. |
| Other AI agents | Adapted | The command/skill pattern and .specify/ layout can be adapted for other agents (e.g. Claude Code, Windsurf) by adjusting the agent directory name when installing. |
Co-OmniSpec's Spec-Driven Development emphasizes:
- Intent-driven development — Specifications define the what before the how.
- Rich specification creation — Guardrails, checklists, and constitution guide quality.
- Multi-step refinement — Clarify → design → tasks → implement, rather than one-shot code generation.
- Heavy reliance on AI — The agent interprets specs, fills templates, and runs tasks under your principles.
| Phase | Focus | Key activities |
|---|---|---|
| 0-to-1 (Greenfield) | Generate from scratch | Start with requirements → spec → design → tasks → implementation. |
| Iterative enhancement (Brownfield) | Add or modernize | Use /omni.reverse to document existing code, then refine and extend with specify/design/tasks. |
| Quality and consistency | Before implementation | Use /omni.clarify, /omni.analyze, and /omni.checklist to reduce rework. |
After installation, your project will contain:
your-project/
├── .cursor/
│ ├── commands/ # OmniSpec slash commands
│ └── skills/ # Skills for specify, design, tasks, implement, etc.
├── .specify/
│ ├── memory/
│ │ └── constitution.md
│ ├── metamodel/ # Requirement, context, scenario, architecture, etc.
│ ├── scripts/ # Bash and PowerShell helpers
│ └── templates/ # spec, design, tasks, checklist templates
└── changes/ # Feature directories (created by /omni.specify)
└── 001-feature-name/
├── spec.md
├── context.md
├── design.md
├── tasks.md
└── checklists/
- Getting Started — Installation and first run (English).
- Getting Started (中文) — 安装与首次使用（中文）。
- User Guide — Full workflow and command reference (English).
- User Guide (中文) — 完整工作流与命令说明（中文）。
- Build scripts — Co-OmniSpec build and packaging (Linux/Windows).
📋 Click to expand detailed step-by-step process
After installing Co-OmniSpec and opening your project in Cursor:
- Constitution — Run
/omni.constitutionand describe your project principles. This creates or updates.specify/memory/constitution.md. - Specify — Run
/omni.specifyand provide a feature description (what and why). This creates a branch,changes/<branch>/spec.md,context.md, and a requirements checklist. - Clarify (recommended before design) — Run
/omni.clarifyto resolve ambiguities; answers are written back into the spec. - Design — Run
/omni.designwith your tech stack. This producesdesign.md,research.md,data-model.md,quickstart.md, and optionalcontracts/. - Tasks — Run
/omni.tasksto generatetasks.mdwith ordered, dependency-aware tasks. - Analyze (optional) — Run
/omni.analyzeto check consistency across spec, design, and tasks before implementing. - Implement — Run
/omni.implementto execute the tasks in order. The agent may run CLI commands (e.g.npm,dotnet); ensure required tools are installed.
For full details and troubleshooting, see the Getting Started and User Guide.
- Cursor (or another AI coding agent that supports the provided command/skill pattern).
- Git (for feature branches and
changes/workflow). - Bash (Linux/macOS) or PowerShell (Windows) for scripts.
Ensure Co-OmniSpec is installed in this project: check that .cursor/commands/ and .specify/ exist. Reload the window or restart Cursor to load the new commands.
- Use absolute paths for the target project.
- Windows: Run PowerShell with an execution policy that allows scripts (e.g.
Set-ExecutionPolicy -Scope CurrentUser RemoteSigned). - Linux/macOS: Make the script executable:
chmod +x build/install.sh.
Ensure Git is available and the current directory is a valid repository. You can run the create-branch script manually to see errors (see User Guide — Troubleshooting).
For more issues and solutions, see the User Guide.
For questions or issues, open a GitHub issue in this repository. For detailed workflow and command help, see the User Guide and Getting Started.
Co-OmniSpec is inspired by and extends GitHub Spec Kit, following its Spec-Driven Development philosophy and adapting the workflow for Cursor and other agent toolchains.
See LICENSE for terms.
