{"id":44008649,"url":"https://github.com/girishr/specpilot","last_synced_at":"2026-04-02T19:01:49.096Z","repository":{"id":316901059,"uuid":"1065274650","full_name":"girishr/SpecPilot","owner":"girishr","description":"A powerful CLI tool for initializing specification-driven development projects with flexible, production-ready structures. ","archived":false,"fork":false,"pushed_at":"2026-03-29T13:40:03.000Z","size":725,"stargazers_count":16,"open_issues_count":0,"forks_count":3,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-03-29T16:34:07.495Z","etag":null,"topics":["ai-assisted-coding","cli","development-tools","npm-package","productivity","project-initialization","python","sdd","specification-driven-development","typescript"],"latest_commit_sha":null,"homepage":"https://specpilot.dev","language":"TypeScript","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/girishr.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"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":"2025-09-27T11:51:17.000Z","updated_at":"2026-03-29T13:40:07.000Z","dependencies_parsed_at":"2025-09-27T13:28:59.258Z","dependency_job_id":"0619271d-1662-44c1-aeed-b4b5ad723a36","html_url":"https://github.com/girishr/SpecPilot","commit_stats":null,"previous_names":["girishr/specpilot"],"tags_count":12,"template":false,"template_full_name":null,"purl":"pkg:github/girishr/SpecPilot","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/girishr%2FSpecPilot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/girishr%2FSpecPilot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/girishr%2FSpecPilot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/girishr%2FSpecPilot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/girishr","download_url":"https://codeload.github.com/girishr/SpecPilot/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/girishr%2FSpecPilot/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31313851,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-02T12:59:32.332Z","status":"ssl_error","status_checked_at":"2026-04-02T12:54:48.875Z","response_time":89,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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-assisted-coding","cli","development-tools","npm-package","productivity","project-initialization","python","sdd","specification-driven-development","typescript"],"created_at":"2026-02-07T14:03:50.423Z","updated_at":"2026-04-02T19:01:49.086Z","avatar_url":"https://github.com/girishr.png","language":"TypeScript","readme":"# SpecPilot\n\n[![npm version](https://img.shields.io/npm/v/specpilot.svg)](https://www.npmjs.com/package/specpilot)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\nA CLI tool for initializing specification-driven development projects with flexible, production-ready structures.\n\n## Quick Start\n\n```bash\n# Install globally\nnpm install -g specpilot\n\n# Create a new project\nspecpilot init my-project --lang typescript --framework react\n\n# Add specs to existing project\ncd existing-project\nspecpilot add-specs\n\n# Validate specifications\nspecpilot validate\n```\n\n### 🚀 Next Steps to Populate Your Specs with AI\n\nAfter creating a project, follow these steps to populate your specifications using AI:\n\n1. **Open the generated guide**: Check `.specs/README.md` for full guidance\n2. **Copy the onboarding prompt**: Use the prompt from `.specs/development/prompts.md`\n3. **Paste into your AI agent**: ChatGPT, Claude, or other AI assistants\n4. **Review generated spec files**: Examine the AI-generated requirements and architecture\n\nThis AI-assisted approach ensures comprehensive, high-quality specifications tailored to your project needs.\n\n## Commands\n\n| Command                 | Description                                         |\n| ----------------------- | --------------------------------------------------- |\n| `init \u003cname\u003e`           | Initialize new SDD project                          |\n| `init \u003cname\u003e --dry-run` | Preview files that would be created without writing |\n| `add-specs`             | Add specs to existing project                       |\n| `validate`              | Validate specification files                        |\n| `archive`               | Archive oversized `prompts.md` / `tasks.md` entries |\n| `list`                  | Show available templates                            |\n| `migrate`               | Migrate between spec versions                       |\n| `refine [desc]`         | Refine project specifications                       |\n\n\u003e **Tip — command aliases:** All commands have a short alias you can use instead of the full name.\n\u003e `init` → `i` \u0026nbsp;·\u0026nbsp; `validate` → `v` \u0026nbsp;·\u0026nbsp; `migrate` → `m` \u0026nbsp;·\u0026nbsp; `list` → `ls` \u0026nbsp;·\u0026nbsp; `refine` → `ref` \u0026nbsp;·\u0026nbsp; `archive` → `ar` \u0026nbsp;·\u0026nbsp; `add-specs` → `add`\n\u003e Example: `specpilot i my-app` is identical to `specpilot init my-app`.\n\n### Examples\n\n```bash\n# Initialize with specific language/framework\nspecpilot init api --lang python --framework fastapi\n\n# Preview files that would be created without writing anything\nspecpilot init api --dry-run\n\n# Refine specifications\nspecpilot refine \"REST API for user management\" --update\n\n# Validate with auto-fix\nspecpilot validate --fix\n```\n\n## Supported Languages \u0026 Frameworks\n\n### TypeScript\n\n- **React**: SPA applications\n- **Express**: REST APIs\n- **Next.js**: Full-stack apps\n- **Nest.js**: Scalable server-side apps\n- **Vue**: Progressive UI framework\n- **Angular**: Enterprise SPA framework\n\n### JavaScript\n\n- **React**: SPA applications\n- **Express**: REST APIs\n\n\u003e Note: no framework prompt is shown for JavaScript — pass `--framework` explicitly if needed.\n\n### Python\n\n- **FastAPI**: Modern REST APIs\n- **Django**: Full-stack applications\n- **Flask**: Lightweight REST APIs\n- **Streamlit**: Data Science / ML apps\n\n## Project Structure\n\nSpecPilot generates a `.specs/` folder with organized subdirectories:\n\n```\n.specs/\n├── architecture/\n│   ├── api.yaml              # CLI / REST API / GraphQL interface spec\n│   └── architecture.md       # System design decisions and patterns\n├── development/\n│   ├── context.md            # Development memory, decisions, learnings\n│   ├── docs.md               # Dev guidelines, spec conventions, checklist\n│   └── prompts.md            # AI interaction log — MANDATED, update every session\n├── planning/\n│   ├── roadmap.md            # Release milestones and objectives\n│   └── tasks.md              # Sprint tracker (backlog / current / completed)\n├── project/\n│   ├── project.yaml          # Project config, rules, and AI context (MANDATED)\n│   └── requirements.md       # Functional \u0026 non-functional requirements\n├── quality/\n│   └── tests.md              # Test strategy, coverage targets, acceptance criteria\n└── security/\n    ├── security-decisions.md # ADR-style security design decisions\n    └── threat-model.md       # Threat inventory with impact/likelihood/mitigation\n```\n\n\u003e Also generated at project root: `.github/copilot-instructions.md` (AI mandate enforcement)\n\n## Configuration\n\nSpecPilot requires no global configuration. Each project is self-contained with settings in `project.yaml`.\n\n### IDE \u0026 Agent Support\n\nSpecPilot generates AI agent configuration files during project initialization. When you run `specpilot init`, you'll be prompted to select your AI IDE/Agent:\n\n**Desktop IDEs (Workspace Settings):**\n\n- **VSCode** - Industry standard with Copilot integration\n- **Cursor** - AI-first code editor with enhanced AI context\n- **Windsurf** - Advanced AI coding assistant\n- **Kiro** - Specialized AI development environment\n- **Antigravity** - AI-powered IDE with context awareness\n\n**Cloud-Based AI Agents (Instruction Files):**\n\n- **Cowork** - Anthropic Claude agent with Skills framework\n- **Codex** - OpenAI Codex agent with instruction context\n\n**Generated Configuration Files:**\n\nFor **all** IDE/Agent selections: `.github/copilot-instructions.md`\n\n- Critical mandates injected into every AI request automatically\n- Read on every interaction by GitHub Copilot, Cursor, and most AI tools\n- Contains project name/stack, 5 critical mandates, and a Re-Anchor Prompt reference\n\nFor desktop IDEs: `.vscode/settings.json` (or `.cursor/`, `.windsurf/`, etc.)\n\n- IDE-specific workspace folder setup for code + .specs\n- Extensions recommendations for development\n- AI context configuration for better spec integration\n\nFor cloud agents:\n\n- **Cowork**: `.claude/skills/specpilot-project/SKILL.md` with project context and development guidelines\n- **Codex**: `CODEX_INSTRUCTIONS.md` at project root with architecture overview and mandates\n\nThe generated settings/instructions automatically configure your AI agent to:\n\n- Include `.specs/` folder in AI context\n- Understand project structure and requirements\n- Follow specification-driven development principles\n- Access development guidelines and onboarding prompts\n\n**Example:**\n\n```bash\n# During init, you'll be prompted to select your IDE/Agent\nspecpilot init my-project --lang typescript --framework react\n# Respond with your preferred IDE/Agent:\n# - vscode, cursor, windsurf, kiro, antigravity (desktop)\n# - cowork, codex (cloud agents)\n```\n\n## Troubleshooting\n\n### Common Issues\n\n#### Permission Errors\n\n```bash\nsudo chown -R $USER ~/.npm-global\nnpm config set prefix '~/.npm-global'\n```\n\n#### Template Not Found\n\n```bash\nspecpilot list --verbose\n```\n\n#### Validation Failures\n\n```bash\nspecpilot validate --verbose --fix\n```\n\n#### Migration Issues\n\n**Error: \"Source structure 'complex' not found\"**\n\n```bash\n# For NEW projects, use:\nspecpilot init my-project\n\n# For EXISTING projects without specs:\nspecpilot add-specs\n\n# Only use migrate if you have an old .project-spec folder\nspecpilot migrate --from complex --to simple --backup\n```\n\n### Debug Mode\n\n```bash\nDEBUG=specpilot specpilot \u003ccommand\u003e\n```\n\n## Why SpecPilot?\n\nSpecPilot implements **Specification-Driven Development (SDD)** where specifications come first:\n\n```\nSpecifications → Architecture → Code → Tests → Deployment\n```\n\n**Benefits:**\n\n- **Clarity**: Everyone understands what needs to be built\n- **Consistency**: Standardized structure across projects\n- **Quality**: Built-in validation and testing\n- **AI-Ready**: Clear context for AI assistants\n- **Maintainable**: Comprehensive documentation\n\n## Contributing\n\nThis project follows SDD principles. See [`.specs/`](.specs/) for contribution guidelines.\n\n### Development Setup\n\n```bash\ngit clone https://github.com/girishr/SpecPilot.git\ncd SpecPilot\nnpm install\nnpm run build\nnpm link  # For local testing\n```\n\n### Quick Contribution Guide\n\n1. Review [`.specs/project/requirements.md`](.specs/project/requirements.md)\n2. Check [`.specs/planning/tasks.md`](.specs/planning/tasks.md)\n3. Update specs when making changes\n4. Run `specpilot validate` before committing\n\n## Documentation\n\n- **[Full Guide](docs/GUIDE.md)**: Comprehensive documentation\n- **[SpecPilot vs GitHub Spec Kit](docs/comparison.md)**: Side-by-side comparison to help you choose the right tool\n- **[CHANGELOG](CHANGELOG.md)**: Version history\n- **[Issues](https://github.com/girishr/SpecPilot/issues)**: Bug reports \u0026 feature requests\n\n## License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n---\n\n_Built with specification-driven development principles for serious production projects._\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgirishr%2Fspecpilot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgirishr%2Fspecpilot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgirishr%2Fspecpilot/lists"}