specpilot 1.2.2 → 1.5.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +126 -378
- package/dist/cli.js +13 -0
- package/dist/cli.js.map +1 -1
- package/dist/commands/add-specs.d.ts.map +1 -1
- package/dist/commands/add-specs.js +6 -18
- package/dist/commands/add-specs.js.map +1 -1
- package/dist/commands/init.d.ts.map +1 -1
- package/dist/commands/init.js +123 -48
- package/dist/commands/init.js.map +1 -1
- package/dist/commands/list.d.ts.map +1 -1
- package/dist/commands/list.js +26 -34
- package/dist/commands/list.js.map +1 -1
- package/dist/commands/migrate.d.ts.map +1 -1
- package/dist/commands/migrate.js +16 -11
- package/dist/commands/migrate.js.map +1 -1
- package/dist/commands/specify.d.ts.map +1 -1
- package/dist/commands/specify.js +112 -20
- package/dist/commands/specify.js.map +1 -1
- package/dist/commands/validate.d.ts.map +1 -1
- package/dist/commands/validate.js +35 -19
- package/dist/commands/validate.js.map +1 -1
- package/dist/utils/agentConfigGenerator.d.ts +15 -0
- package/dist/utils/agentConfigGenerator.d.ts.map +1 -0
- package/dist/utils/agentConfigGenerator.js +234 -0
- package/dist/utils/agentConfigGenerator.js.map +1 -0
- package/dist/utils/codeAnalyzer.js +10 -10
- package/dist/utils/codeAnalyzer.js.map +1 -1
- package/dist/utils/frameworks.d.ts +2 -0
- package/dist/utils/frameworks.d.ts.map +1 -0
- package/dist/utils/frameworks.js +11 -0
- package/dist/utils/frameworks.js.map +1 -0
- package/dist/utils/ideConfigGenerator.d.ts +20 -0
- package/dist/utils/ideConfigGenerator.d.ts.map +1 -0
- package/dist/utils/ideConfigGenerator.js +176 -0
- package/dist/utils/ideConfigGenerator.js.map +1 -0
- package/dist/utils/logger.d.ts +19 -0
- package/dist/utils/logger.d.ts.map +1 -1
- package/dist/utils/logger.js +145 -0
- package/dist/utils/logger.js.map +1 -1
- package/dist/utils/projectDetector.d.ts.map +1 -1
- package/dist/utils/projectDetector.js.map +1 -1
- package/dist/utils/projectMigrator.d.ts.map +1 -1
- package/dist/utils/projectMigrator.js +36 -33
- package/dist/utils/projectMigrator.js.map +1 -1
- package/dist/utils/specFileGenerator.d.ts +25 -0
- package/dist/utils/specFileGenerator.d.ts.map +1 -0
- package/dist/utils/specFileGenerator.js +677 -0
- package/dist/utils/specFileGenerator.js.map +1 -0
- package/dist/utils/specGenerator.d.ts +11 -14
- package/dist/utils/specGenerator.d.ts.map +1 -1
- package/dist/utils/specGenerator.js +24 -430
- package/dist/utils/specGenerator.js.map +1 -1
- package/dist/utils/specValidator.d.ts.map +1 -1
- package/dist/utils/specValidator.js +4 -6
- package/dist/utils/specValidator.js.map +1 -1
- package/dist/utils/templateEngine.d.ts +9 -3
- package/dist/utils/templateEngine.d.ts.map +1 -1
- package/dist/utils/templateEngine.js +36 -36
- package/dist/utils/templateEngine.js.map +1 -1
- package/package.json +8 -3
package/README.md
CHANGED
|
@@ -1,47 +1,9 @@
|
|
|
1
|
-
# SpecPilot
|
|
1
|
+
# SpecPilot
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[](https://www.npmjs.com/package/specpilot)
|
|
4
|
+
[](https://opensource.org/licenses/MIT)
|
|
4
5
|
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
- [Quick Start](#quick-start)
|
|
8
|
-
- [Description](#description)
|
|
9
|
-
- [Why SpecPilot?](#why-specpilot)
|
|
10
|
-
- [The Problem with Traditional Development](#the-problem-with-traditional-development)
|
|
11
|
-
- [The SpecPilot Solution](#the-specpilot-solution)
|
|
12
|
-
- [🏗️ Analogy: Building a House](#️-analogy-building-a-house)
|
|
13
|
-
- [💡 Example: Building a Task Management App](#-example-building-a-task-management-app)
|
|
14
|
-
- [🌟 Why SDD is the Future](#-why-sdd-is-the-future)
|
|
15
|
-
- [Prerequisites](#prerequisites)
|
|
16
|
-
- [Installation](#installation)
|
|
17
|
-
- [Usage Examples](#usage-examples)
|
|
18
|
-
- [Basic Project Initialization](#basic-project-initialization)
|
|
19
|
-
- [Additional Commands](#additional-commands)
|
|
20
|
-
- [Configuration](#configuration)
|
|
21
|
-
- [Global Configuration](#global-configuration)
|
|
22
|
-
- [Project Configuration](#project-configuration)
|
|
23
|
-
- [Templates](#templates)
|
|
24
|
-
- [Available Templates](#available-templates)
|
|
25
|
-
- [Custom Templates](#custom-templates)
|
|
26
|
-
- [Features](#features)
|
|
27
|
-
- [Project Structure](#project-structure)
|
|
28
|
-
- [Troubleshooting](#troubleshooting)
|
|
29
|
-
- [Common Issues](#common-issues)
|
|
30
|
-
- [Debug Mode](#debug-mode)
|
|
31
|
-
- [Getting Help](#getting-help)
|
|
32
|
-
- [Getting Started](#getting-started)
|
|
33
|
-
- [Best Practices](#best-practices)
|
|
34
|
-
- [How to Contribute](#how-to-contribute)
|
|
35
|
-
- [Version History](#version-history)
|
|
36
|
-
- [MIT License](#mit-license)
|
|
37
|
-
- [Extended Configuration](#extended-configuration)
|
|
38
|
-
- [CI/CD Integration](#cicd-integration)
|
|
39
|
-
- [Team Collaboration](#team-collaboration)
|
|
40
|
-
- [Enterprise Integration](#enterprise-integration)
|
|
41
|
-
- [API Usage](#api-usage)
|
|
42
|
-
- [Contributing](#contributing)
|
|
43
|
-
- [Development Setup](#development-setup)
|
|
44
|
-
- [License](#license)
|
|
6
|
+
A CLI tool for initializing specification-driven development projects with flexible, production-ready structures.
|
|
45
7
|
|
|
46
8
|
## Quick Start
|
|
47
9
|
|
|
@@ -49,235 +11,150 @@ A CLI tool for initializing specification-driven development projects with flexi
|
|
|
49
11
|
# Install globally
|
|
50
12
|
npm install -g specpilot
|
|
51
13
|
|
|
52
|
-
#
|
|
14
|
+
# Create a new project
|
|
53
15
|
specpilot init my-project --lang typescript --framework react
|
|
54
16
|
|
|
55
|
-
#
|
|
56
|
-
cd
|
|
57
|
-
|
|
58
|
-
```
|
|
59
|
-
|
|
60
|
-
## Description
|
|
61
|
-
|
|
62
|
-
`SpecPilot SDD CLI` is designed to give developers the freedom to decide and control their projects, not prescribe the entire implementation. My goal with this project is to provide a helping tool that offers basic guidelines for serious developers writing production code for critical development tasks who need better control over their project, its architecture, and its structure.
|
|
63
|
-
|
|
64
|
-
The tool generates customizable `.specs` directories that serve as flexible frameworks for specification-driven development, integrating seamlessly with AI-assisted coding workflows. It provides structure and guidance without dictating implementation, allowing you to maintain full ownership of your production code while establishing robust foundations for scalable, maintainable projects.
|
|
65
|
-
|
|
66
|
-
## Why SpecPilot?
|
|
67
|
-
|
|
68
|
-
### The Problem with Traditional Development
|
|
69
|
-
|
|
70
|
-
Most software projects start with good intentions but end up with unclear requirements, inconsistent architecture, and difficult maintenance. Developers spend 50%+ of their time on planning, debugging, and refactoring.
|
|
71
|
-
|
|
72
|
-
### The SpecPilot Solution
|
|
73
|
-
|
|
74
|
-
SpecPilot brings **Specification-Driven Development (SDD)** to your workflow - a methodology where you define what you're building _before_ you start coding.
|
|
75
|
-
|
|
76
|
-
### 🏗️ **Analogy: Building a House**
|
|
77
|
-
|
|
78
|
-
**Traditional Coding**: Like building a house without blueprints - you start hammering nails and hope it turns out right.
|
|
79
|
-
|
|
80
|
-
**With SpecPilot**: Like getting detailed architectural plans first - you know exactly what rooms you need, where the plumbing goes, and how everything connects before breaking ground.
|
|
81
|
-
|
|
82
|
-
### 💡 **Example: Building a Task Management App**
|
|
83
|
-
|
|
84
|
-
**Without SpecPilot:**
|
|
17
|
+
# Add specs to existing project
|
|
18
|
+
cd existing-project
|
|
19
|
+
specpilot add-specs
|
|
85
20
|
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
npm init -y
|
|
89
|
-
# Now what? Start coding randomly, figure out structure later...
|
|
21
|
+
# Validate specifications
|
|
22
|
+
specpilot validate
|
|
90
23
|
```
|
|
91
24
|
|
|
92
|
-
|
|
25
|
+
### 🚀 Next Steps to Populate Your Specs with AI
|
|
93
26
|
|
|
94
|
-
|
|
95
|
-
npm install -g specpilot
|
|
96
|
-
specpilot init task-manager --lang typescript --framework react
|
|
97
|
-
cd task-manager
|
|
98
|
-
# Instantly get:
|
|
99
|
-
# - Complete project structure with API specs
|
|
100
|
-
# - Test plans and validation rules
|
|
101
|
-
# - AI prompt tracking for accountability
|
|
102
|
-
# - Development guidelines and best practices
|
|
103
|
-
```
|
|
104
|
-
|
|
105
|
-
### 🌟 **Why SDD is the Future**
|
|
27
|
+
After creating a project, follow these steps to populate your specifications using AI:
|
|
106
28
|
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
29
|
+
1. **Open the generated guide**: Check `.specs/README.md` for full guidance
|
|
30
|
+
2. **Copy the onboarding prompt**: Use the prompt from `.specs/development/prompts.md`
|
|
31
|
+
3. **Paste into your AI agent**: ChatGPT, Claude, or other AI assistants
|
|
32
|
+
4. **Review generated spec files**: Examine the AI-generated requirements and architecture
|
|
111
33
|
|
|
112
|
-
|
|
34
|
+
This AI-assisted approach ensures comprehensive, high-quality specifications tailored to your project needs.
|
|
113
35
|
|
|
114
|
-
##
|
|
36
|
+
## Commands
|
|
115
37
|
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
-
|
|
38
|
+
| Command | Description |
|
|
39
|
+
| ---------------- | ----------------------------- |
|
|
40
|
+
| `init <name>` | Initialize new SDD project |
|
|
41
|
+
| `add-specs` | Add specs to existing project |
|
|
42
|
+
| `validate` | Validate specification files |
|
|
43
|
+
| `list` | Show available templates |
|
|
44
|
+
| `migrate` | Migrate between spec versions |
|
|
45
|
+
| `specify <desc>` | Update project specifications |
|
|
120
46
|
|
|
121
|
-
|
|
47
|
+
### Examples
|
|
122
48
|
|
|
123
49
|
```bash
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
### Verify Installation
|
|
50
|
+
# Initialize with specific language/framework
|
|
51
|
+
specpilot init api --lang python --framework fastapi
|
|
128
52
|
|
|
129
|
-
|
|
130
|
-
specpilot --
|
|
131
|
-
# Should output: 1.2.2 (or current version)
|
|
53
|
+
# Update specifications
|
|
54
|
+
specpilot specify "REST API for user management" --update
|
|
132
55
|
|
|
133
|
-
|
|
134
|
-
|
|
56
|
+
# Validate with auto-fix
|
|
57
|
+
specpilot validate --fix
|
|
135
58
|
```
|
|
136
59
|
|
|
137
|
-
##
|
|
60
|
+
## Supported Languages & Frameworks
|
|
138
61
|
|
|
139
|
-
###
|
|
62
|
+
### TypeScript
|
|
140
63
|
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
64
|
+
- **React**: SPA applications
|
|
65
|
+
- **Express**: REST APIs
|
|
66
|
+
- **Next.js**: Full-stack apps
|
|
67
|
+
- **CLI**: Command-line tools
|
|
144
68
|
|
|
145
|
-
|
|
146
|
-
specpilot init my-project --lang typescript --framework react
|
|
147
|
-
specpilot init my-project --lang javascript --framework express
|
|
148
|
-
specpilot init my-project --lang python --framework fastapi
|
|
149
|
-
specpilot init my-project --lang python --framework django
|
|
69
|
+
### JavaScript
|
|
150
70
|
|
|
151
|
-
|
|
152
|
-
|
|
71
|
+
- **React**: SPA applications
|
|
72
|
+
- **Express**: REST APIs
|
|
73
|
+
- **Next.js**: Full-stack apps
|
|
74
|
+
- **CLI**: Command-line tools
|
|
153
75
|
|
|
154
|
-
|
|
155
|
-
specpilot init my-project --no-prompts
|
|
156
|
-
```
|
|
76
|
+
### Python
|
|
157
77
|
|
|
158
|
-
|
|
78
|
+
- **FastAPI**: Modern REST APIs
|
|
79
|
+
- **Django**: Full-stack applications
|
|
80
|
+
- **Data Science**: ML/Data Science projects
|
|
159
81
|
|
|
160
|
-
|
|
161
|
-
# Add .specs folder to an existing project
|
|
162
|
-
specpilot add-specs
|
|
163
|
-
specpilot add-specs --lang typescript --framework react
|
|
164
|
-
specpilot add-specs --no-analysis # Skip codebase analysis
|
|
165
|
-
specpilot add-specs --no-prompts # Non-interactive mode
|
|
166
|
-
|
|
167
|
-
# Validate project specs
|
|
168
|
-
specpilot validate --verbose
|
|
169
|
-
specpilot validate --fix
|
|
170
|
-
|
|
171
|
-
# List available templates
|
|
172
|
-
specpilot list
|
|
82
|
+
## Project Structure
|
|
173
83
|
|
|
174
|
-
|
|
175
|
-
# Note: Only use this if you're upgrading from an older SpecPilot version
|
|
176
|
-
specpilot migrate --from complex --to simple --backup
|
|
84
|
+
SpecPilot generates a `.specs/` folder with organized subdirectories:
|
|
177
85
|
|
|
178
|
-
|
|
179
|
-
|
|
86
|
+
```
|
|
87
|
+
.specs/
|
|
88
|
+
├── project/ # Project config & requirements
|
|
89
|
+
├── architecture/ # System design & API specs
|
|
90
|
+
├── planning/ # Roadmap & task tracking
|
|
91
|
+
├── quality/ # Testing & documentation
|
|
92
|
+
└── development/ # AI prompts & context
|
|
180
93
|
```
|
|
181
94
|
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
- **`specpilot init <name>`** - Starting a brand new project from scratch
|
|
185
|
-
- **`specpilot add-specs`** - Adding specifications to an existing codebase
|
|
186
|
-
- **`specpilot migrate`** - Upgrading from old .project-spec structure (legacy)
|
|
187
|
-
- **`specpilot validate`** - Checking your specs for errors
|
|
188
|
-
- **`specpilot specify`** - Generating specs from natural language description
|
|
95
|
+
### Key Files
|
|
189
96
|
|
|
190
|
-
|
|
97
|
+
- **`project.yaml`**: Project configuration and rules
|
|
98
|
+
- **`requirements.md`**: Functional/non-functional requirements
|
|
99
|
+
- **`architecture.md`**: System architecture decisions
|
|
100
|
+
- **`prompts.md`**: AI interaction tracking (MANDATED)
|
|
101
|
+
- **`tasks.md`**: Task management (backlog/sprint/completed)
|
|
191
102
|
|
|
192
103
|
## Configuration
|
|
193
104
|
|
|
194
|
-
|
|
105
|
+
SpecPilot requires no global configuration. Each project is self-contained with settings in `project.yaml`.
|
|
195
106
|
|
|
196
|
-
|
|
107
|
+
### IDE & Agent Support
|
|
197
108
|
|
|
198
|
-
|
|
109
|
+
SpecPilot generates AI agent configuration files during project initialization. When you run `specpilot init`, you'll be prompted to select your AI IDE/Agent:
|
|
199
110
|
|
|
200
|
-
|
|
201
|
-
# Configure via command-line options
|
|
202
|
-
specpilot init my-project --lang typescript --framework react --specs-name .specs
|
|
203
|
-
```
|
|
111
|
+
**Desktop IDEs (Workspace Settings):**
|
|
204
112
|
|
|
205
|
-
|
|
113
|
+
- **VSCode** - Industry standard with Copilot integration
|
|
114
|
+
- **Cursor** - AI-first code editor with enhanced AI context
|
|
115
|
+
- **Windsurf** - Advanced AI coding assistant
|
|
116
|
+
- **Kiro** - Specialized AI development environment
|
|
117
|
+
- **Antigravity** - AI-powered IDE with context awareness
|
|
206
118
|
|
|
207
|
-
|
|
119
|
+
**Cloud-Based AI Agents (Instruction Files):**
|
|
208
120
|
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
name: "my-project"
|
|
212
|
-
description: "My awesome project"
|
|
213
|
-
language: "typescript"
|
|
214
|
-
framework: "react"
|
|
215
|
-
version: "1.1.1"
|
|
216
|
-
|
|
217
|
-
rules:
|
|
218
|
-
- "Follow specification-driven development"
|
|
219
|
-
- "Maintain comprehensive documentation"
|
|
220
|
-
- "Use TypeScript strict mode"
|
|
221
|
-
|
|
222
|
-
ai-context:
|
|
223
|
-
- "Track all development prompts"
|
|
224
|
-
- "Maintain architectural decisions"
|
|
225
|
-
```
|
|
121
|
+
- **Cowork** - Anthropic Claude agent with Skills framework
|
|
122
|
+
- **Codex** - OpenAI Codex agent with instruction context
|
|
226
123
|
|
|
227
|
-
|
|
124
|
+
**Generated Configuration Files:**
|
|
228
125
|
|
|
229
|
-
|
|
126
|
+
For **all** IDE/Agent selections: `.github/copilot-instructions.md`
|
|
230
127
|
|
|
231
|
-
|
|
128
|
+
- Critical mandates injected into every AI request automatically
|
|
129
|
+
- Read on every interaction by GitHub Copilot, Cursor, and most AI tools
|
|
130
|
+
- Contains project name/stack, 5 critical mandates, and a Re-Anchor Prompt reference
|
|
232
131
|
|
|
233
|
-
|
|
234
|
-
- **React**: React application with modern tooling
|
|
235
|
-
- **Express**: REST API server setup
|
|
132
|
+
For desktop IDEs: `.vscode/settings.json` (or `.cursor/`, `.windsurf/`, etc.)
|
|
236
133
|
|
|
237
|
-
|
|
134
|
+
- IDE-specific workspace folder setup for code + .specs
|
|
135
|
+
- Extensions recommendations for development
|
|
136
|
+
- AI context configuration for better spec integration
|
|
238
137
|
|
|
239
|
-
|
|
240
|
-
- **FastAPI**: Modern API development
|
|
241
|
-
- **Django**: Web application framework
|
|
138
|
+
For cloud agents:
|
|
242
139
|
|
|
243
|
-
|
|
140
|
+
- **Cowork**: `.claude/skills/specpilot-project/SKILL.md` with project context and development guidelines
|
|
141
|
+
- **Codex**: `CODEX_INSTRUCTIONS.md` at project root with architecture overview and mandates
|
|
244
142
|
|
|
245
|
-
|
|
143
|
+
The generated settings/instructions automatically configure your AI agent to:
|
|
246
144
|
|
|
247
|
-
|
|
145
|
+
- Include `.specs/` folder in AI context
|
|
146
|
+
- Understand project structure and requirements
|
|
147
|
+
- Follow specification-driven development principles
|
|
148
|
+
- Access development guidelines and onboarding prompts
|
|
248
149
|
|
|
249
|
-
|
|
150
|
+
**Example:**
|
|
250
151
|
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
- **Flexible Structure**: Generates `.specs` with customizable, production-ready layout
|
|
258
|
-
- **Language Support**: Built-in templates for TypeScript, JavaScript, and Python
|
|
259
|
-
- **Existing Project Support**: Add `.specs` to existing projects with `add-specs` command
|
|
260
|
-
- **Intelligent Analysis**: Auto-detect language/framework, scan TODOs/FIXMEs, analyze tests
|
|
261
|
-
- **Spec Validation**: Built-in validation with optional auto-fix
|
|
262
|
-
- **AI Integration**: Comprehensive AI onboarding prompt in `.specs/development/prompts.md`
|
|
263
|
-
- **Migration Support**: Helps transition from legacy `.project-spec` structures with helpful error messages
|
|
264
|
-
- **Template Listing**: Discover available language/framework combinations
|
|
265
|
-
- **Developer Attribution**: Prompts for developer name and personalizes generated specs
|
|
266
|
-
|
|
267
|
-
## Project Structure
|
|
268
|
-
|
|
269
|
-
After initialization, your project will have:
|
|
270
|
-
|
|
271
|
-
```text
|
|
272
|
-
project-root/
|
|
273
|
-
├── .specs/
|
|
274
|
-
│ ├── project/ # project.yaml, requirements.md, project-plan.md
|
|
275
|
-
│ ├── architecture/ # architecture.md, api.yaml
|
|
276
|
-
│ ├── planning/ # tasks.md, roadmap.md
|
|
277
|
-
│ ├── quality/ # tests.md
|
|
278
|
-
│ └── development/ # docs.md, context.md, prompts.md
|
|
279
|
-
├── src/
|
|
280
|
-
└── README.md
|
|
152
|
+
```bash
|
|
153
|
+
# During init, you'll be prompted to select your IDE/Agent
|
|
154
|
+
specpilot init my-project --lang typescript --framework react
|
|
155
|
+
# Respond with your preferred IDE/Agent:
|
|
156
|
+
# - vscode, cursor, windsurf, kiro, antigravity (desktop)
|
|
157
|
+
# - cowork, codex (cloud agents)
|
|
281
158
|
```
|
|
282
159
|
|
|
283
160
|
## Troubleshooting
|
|
@@ -287,218 +164,89 @@ project-root/
|
|
|
287
164
|
#### Permission Errors
|
|
288
165
|
|
|
289
166
|
```bash
|
|
290
|
-
# Fix permission issues
|
|
291
167
|
sudo chown -R $USER ~/.npm-global
|
|
292
168
|
npm config set prefix '~/.npm-global'
|
|
293
169
|
```
|
|
294
170
|
|
|
295
|
-
## Configuration examples
|
|
296
|
-
|
|
297
171
|
#### Template Not Found
|
|
298
172
|
|
|
299
173
|
```bash
|
|
300
|
-
|
|
301
|
-
specpilot list
|
|
174
|
+
specpilot list --verbose
|
|
302
175
|
```
|
|
303
176
|
|
|
304
177
|
#### Validation Failures
|
|
305
178
|
|
|
306
179
|
```bash
|
|
307
|
-
|
|
308
|
-
specpilot validate --verbose
|
|
309
|
-
|
|
310
|
-
# Auto-fix common issues
|
|
311
|
-
specpilot validate --fix
|
|
180
|
+
specpilot validate --verbose --fix
|
|
312
181
|
```
|
|
313
182
|
|
|
314
183
|
#### Migration Issues
|
|
315
184
|
|
|
316
185
|
**Error: "Source structure 'complex' not found"**
|
|
317
186
|
|
|
318
|
-
This means you're trying to migrate from a structure that doesn't exist in your project.
|
|
319
|
-
|
|
320
187
|
```bash
|
|
321
|
-
# Check what's in your project directory
|
|
322
|
-
ls -la
|
|
323
|
-
|
|
324
188
|
# For NEW projects, use:
|
|
325
189
|
specpilot init my-project
|
|
326
190
|
|
|
327
191
|
# For EXISTING projects without specs:
|
|
328
192
|
specpilot add-specs
|
|
329
193
|
|
|
330
|
-
# Only use migrate if you have an old .project-spec folder
|
|
194
|
+
# Only use migrate if you have an old .project-spec folder
|
|
331
195
|
specpilot migrate --from complex --to simple --backup
|
|
332
196
|
```
|
|
333
197
|
|
|
334
|
-
**When to use migrate:**
|
|
335
|
-
|
|
336
|
-
- You have an old `.project-spec` folder from a previous SpecPilot version
|
|
337
|
-
- You're upgrading between SpecPilot structure versions
|
|
338
|
-
- You need to convert between specification formats
|
|
339
|
-
|
|
340
|
-
**When NOT to use migrate:**
|
|
341
|
-
|
|
342
|
-
- Starting a new project (use `init` instead)
|
|
343
|
-
- Adding specs to existing code (use `add-specs` instead)
|
|
344
|
-
- Your project has no specification folder yet
|
|
345
|
-
|
|
346
198
|
### Debug Mode
|
|
347
199
|
|
|
348
200
|
```bash
|
|
349
|
-
|
|
350
|
-
DEBUG=specpilot specpilot init my-project
|
|
351
|
-
|
|
352
|
-
# Verbose output
|
|
353
|
-
specpilot validate --verbose
|
|
354
|
-
|
|
355
|
-
# Check what templates are available
|
|
356
|
-
specpilot list --verbose
|
|
357
|
-
```
|
|
358
|
-
|
|
359
|
-
### Getting Help
|
|
360
|
-
|
|
361
|
-
```bash
|
|
362
|
-
# Show help
|
|
363
|
-
specpilot --help
|
|
364
|
-
|
|
365
|
-
# Command-specific help
|
|
366
|
-
specpilot init --help
|
|
367
|
-
specpilot validate --help
|
|
368
|
-
specpilot list --help
|
|
369
|
-
specpilot migrate --help
|
|
370
|
-
specpilot specify --help
|
|
201
|
+
DEBUG=specpilot specpilot <command>
|
|
371
202
|
```
|
|
372
203
|
|
|
373
|
-
##
|
|
374
|
-
|
|
375
|
-
1. **Initialize your project**: `specpilot init my-project --lang typescript`
|
|
376
|
-
2. **Review the generated `.specs` structure** - This provides your flexible framework
|
|
377
|
-
3. **Use the AI onboarding prompt**: Open `.specs/development/prompts.md` and copy the comprehensive onboarding prompt to have your AI agent populate all spec files
|
|
378
|
-
4. **Customize the specifications** in `.specs/project/project.yaml`
|
|
379
|
-
5. **Document your architecture** in `.specs/architecture/architecture.md`
|
|
380
|
-
6. **Track all development prompts** in `.specs/development/prompts.md`
|
|
381
|
-
7. **Plan your work** in `.specs/planning/tasks.md` and `.specs/planning/roadmap.md`
|
|
382
|
-
8. **Define tests** in `.specs/quality/tests.md`
|
|
383
|
-
9. **Start building** your production code in `src/`
|
|
384
|
-
|
|
385
|
-
### Best Practices
|
|
386
|
-
|
|
387
|
-
- **Start with specifications**: Define what you're building before coding
|
|
388
|
-
- **Use the AI onboarding prompt**: Found in `.specs/development/prompts.md` to help AI agents populate your specs with project-specific details
|
|
389
|
-
- **Keep prompts updated**: Log all AI interactions in `.specs/development/prompts.md` for complete traceability
|
|
390
|
-
- **Validate regularly**: Use `specpilot validate` during development
|
|
391
|
-
- **Follow the subfolder structure**: Organize specs in `project/`, `architecture/`, `planning/`, `quality/`, `development/`
|
|
392
|
-
- **Use stable IDs**: Reference requirements and tasks by their IDs (e.g., `REQ-001`, `TASK-002`)
|
|
393
|
-
- **Version control everything**: Include `.specs/` in your git repository
|
|
394
|
-
- **Update metadata**: Keep `lastUpdated` and `version` fields current in spec files
|
|
395
|
-
|
|
396
|
-
## How to Contribute
|
|
397
|
-
|
|
398
|
-
We welcome contributions! Please:
|
|
399
|
-
|
|
400
|
-
1. Fork the repo and create a feature branch
|
|
401
|
-
2. Follow the existing code style and add tests for new features
|
|
402
|
-
3. Update documentation for new functionality
|
|
403
|
-
4. Submit a pull request with a clear description
|
|
404
|
-
|
|
405
|
-
## Version History
|
|
406
|
-
|
|
407
|
-
See [CHANGELOG.md](CHANGELOG.md) for detailed version history.
|
|
408
|
-
|
|
409
|
-
## MIT License
|
|
204
|
+
## Why SpecPilot?
|
|
410
205
|
|
|
411
|
-
|
|
206
|
+
SpecPilot implements **Specification-Driven Development (SDD)** where specifications come first:
|
|
412
207
|
|
|
413
|
-
## Extended Configuration
|
|
414
|
-
|
|
415
|
-
### CI/CD Integration
|
|
416
|
-
|
|
417
|
-
```yaml
|
|
418
|
-
# .github/workflows/specs-validation.yml
|
|
419
|
-
name: Validate Specs
|
|
420
|
-
on: [push, pull_request]
|
|
421
|
-
jobs:
|
|
422
|
-
validate:
|
|
423
|
-
runs-on: ubuntu-latest
|
|
424
|
-
steps:
|
|
425
|
-
- uses: actions/checkout@v3
|
|
426
|
-
- uses: actions/setup-node@v3
|
|
427
|
-
with:
|
|
428
|
-
node-version: "18"
|
|
429
|
-
- run: npm install -g specpilot
|
|
430
|
-
- run: specpilot validate --verbose
|
|
431
208
|
```
|
|
432
|
-
|
|
433
|
-
### Team Collaboration
|
|
434
|
-
|
|
435
|
-
```bash
|
|
436
|
-
# Initialize project for team collaboration
|
|
437
|
-
specpilot init team-project --lang typescript --framework react
|
|
438
|
-
|
|
439
|
-
# Share specs folder structure with team
|
|
440
|
-
git add .specs/
|
|
441
|
-
git commit -m "feat: add specification-driven development structure"
|
|
442
|
-
|
|
443
|
-
# Team members can validate specs consistently
|
|
444
|
-
specpilot validate --verbose
|
|
209
|
+
Specifications → Architecture → Code → Tests → Deployment
|
|
445
210
|
```
|
|
446
211
|
|
|
447
|
-
|
|
448
|
-
|
|
449
|
-
> **Note**: SpecPilot is currently a CLI-first tool. Organizations can wrap SpecPilot with internal tooling and scripts. Use `specpilot list` to explore built-in templates and `specpilot --help` for available commands.
|
|
450
|
-
|
|
451
|
-
### API Usage
|
|
212
|
+
**Benefits:**
|
|
452
213
|
|
|
453
|
-
|
|
454
|
-
|
|
455
|
-
**
|
|
456
|
-
|
|
457
|
-
|
|
458
|
-
# Use in shell scripts
|
|
459
|
-
specpilot init my-project --lang typescript --no-prompts
|
|
460
|
-
specpilot validate --fix
|
|
461
|
-
```
|
|
214
|
+
- **Clarity**: Everyone understands what needs to be built
|
|
215
|
+
- **Consistency**: Standardized structure across projects
|
|
216
|
+
- **Quality**: Built-in validation and testing
|
|
217
|
+
- **AI-Ready**: Clear context for AI assistants
|
|
218
|
+
- **Maintainable**: Comprehensive documentation
|
|
462
219
|
|
|
463
220
|
## Contributing
|
|
464
221
|
|
|
465
|
-
This project follows
|
|
466
|
-
|
|
467
|
-
### Quick Contribution Guide
|
|
468
|
-
|
|
469
|
-
1. **Read the specs**: Review [`.specs/project/requirements.md`](.specs/project/requirements.md) and [`.specs/architecture/architecture.md`](.specs/architecture/architecture.md)
|
|
470
|
-
2. **Check current tasks**: See [`.specs/planning/tasks.md`](.specs/planning/tasks.md) for open issues
|
|
471
|
-
3. **Follow conventions**: Use the metadata format documented in [`.specs/development/docs.md`](.specs/development/docs.md)
|
|
472
|
-
4. **Update specs**: Modify relevant spec files when making changes
|
|
473
|
-
5. **Validate**: Run `specpilot validate` before committing
|
|
222
|
+
This project follows SDD principles. See [`.specs/`](.specs/) for contribution guidelines.
|
|
474
223
|
|
|
475
224
|
### Development Setup
|
|
476
225
|
|
|
477
226
|
```bash
|
|
478
|
-
# Clone and setup
|
|
479
227
|
git clone https://github.com/girishr/SpecPilot.git
|
|
480
228
|
cd SpecPilot
|
|
481
229
|
npm install
|
|
230
|
+
npm run build
|
|
231
|
+
npm link # For local testing
|
|
232
|
+
```
|
|
482
233
|
|
|
483
|
-
|
|
484
|
-
npm run dev -- init test-project --lang typescript
|
|
485
|
-
|
|
486
|
-
# Run tests
|
|
487
|
-
npm test
|
|
234
|
+
### Quick Contribution Guide
|
|
488
235
|
|
|
489
|
-
|
|
490
|
-
|
|
236
|
+
1. Review [`.specs/project/requirements.md`](.specs/project/requirements.md)
|
|
237
|
+
2. Check [`.specs/planning/tasks.md`](.specs/planning/tasks.md)
|
|
238
|
+
3. Update specs when making changes
|
|
239
|
+
4. Run `specpilot validate` before committing
|
|
491
240
|
|
|
492
|
-
|
|
493
|
-
npm run build
|
|
241
|
+
## Documentation
|
|
494
242
|
|
|
495
|
-
|
|
496
|
-
|
|
497
|
-
|
|
243
|
+
- **[Full Guide](docs/GUIDE.md)**: Comprehensive documentation
|
|
244
|
+
- **[CHANGELOG](CHANGELOG.md)**: Version history
|
|
245
|
+
- **[Issues](https://github.com/girishr/SpecPilot/issues)**: Bug reports & feature requests
|
|
498
246
|
|
|
499
247
|
## License
|
|
500
248
|
|
|
501
|
-
MIT License - see LICENSE file for details.
|
|
249
|
+
MIT License - see [LICENSE](LICENSE) file for details.
|
|
502
250
|
|
|
503
251
|
---
|
|
504
252
|
|
package/dist/cli.js
CHANGED
|
@@ -1,13 +1,18 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
2
|
"use strict";
|
|
3
|
+
var __importDefault = (this && this.__importDefault) || function (mod) {
|
|
4
|
+
return (mod && mod.__esModule) ? mod : { "default": mod };
|
|
5
|
+
};
|
|
3
6
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
4
7
|
const commander_1 = require("commander");
|
|
8
|
+
const chalk_1 = __importDefault(require("chalk"));
|
|
5
9
|
const init_1 = require("./commands/init");
|
|
6
10
|
const validate_1 = require("./commands/validate");
|
|
7
11
|
const migrate_1 = require("./commands/migrate");
|
|
8
12
|
const list_1 = require("./commands/list");
|
|
9
13
|
const specify_1 = require("./commands/specify");
|
|
10
14
|
const add_specs_1 = require("./commands/add-specs");
|
|
15
|
+
const logger_1 = require("./utils/logger");
|
|
11
16
|
const packageJson = require('../package.json');
|
|
12
17
|
commander_1.program
|
|
13
18
|
.name('specpilot')
|
|
@@ -75,5 +80,13 @@ commander_1.program
|
|
|
75
80
|
.option('--no-prompts', 'Skip interactive prompts')
|
|
76
81
|
.action(add_specs_1.addSpecsCommand);
|
|
77
82
|
// Parse command line arguments
|
|
83
|
+
const args = process.argv.slice(2);
|
|
84
|
+
// If no arguments provided, show welcome message
|
|
85
|
+
if (args.length === 0) {
|
|
86
|
+
const logger = new logger_1.Logger();
|
|
87
|
+
logger.displayWelcome();
|
|
88
|
+
console.log('\n' + chalk_1.default.gray('Use --help to see all available commands'));
|
|
89
|
+
process.exit(0);
|
|
90
|
+
}
|
|
78
91
|
commander_1.program.parse();
|
|
79
92
|
//# sourceMappingURL=cli.js.map
|
package/dist/cli.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"
|
|
1
|
+
{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}
|