specpilot 1.2.2 → 1.3.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 +91 -396
- 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 +2 -9
- package/dist/commands/add-specs.js.map +1 -1
- package/dist/commands/init.d.ts.map +1 -1
- package/dist/commands/init.js +41 -35
- package/dist/commands/init.js.map +1 -1
- package/dist/commands/list.d.ts.map +1 -1
- package/dist/commands/list.js +3 -31
- 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 +14 -5
- 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/logger.d.ts +19 -0
- package/dist/utils/logger.d.ts.map +1 -1
- package/dist/utils/logger.js +149 -0
- package/dist/utils/logger.js.map +1 -1
- package/package.json +2 -1
package/README.md
CHANGED
|
@@ -1,47 +1,9 @@
|
|
|
1
|
-
# SpecPilot
|
|
1
|
+
# SpecPilot
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[](https://badge.fury.io/js/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,236 +11,98 @@ 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
|
-
|
|
93
|
-
|
|
94
|
-
```bash
|
|
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
|
-
```
|
|
25
|
+
### 🚀 Next Steps to Populate Your Specs with AI
|
|
104
26
|
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
- **70% of software projects fail** due to poor planning - SDD reduces this by 60%
|
|
108
|
-
- **AI-assisted coding** becomes reliable when guided by specifications
|
|
109
|
-
- **Team collaboration** improves with shared understanding
|
|
110
|
-
- **Enterprise-ready** approach for serious production projects
|
|
111
|
-
|
|
112
|
-
**SpecPilot gives you a professional project foundation in seconds, so you can focus on building great features instead of figuring out folder structures.**
|
|
113
|
-
|
|
114
|
-
## Prerequisites
|
|
115
|
-
|
|
116
|
-
- **Node.js**: 16.0.0 or higher (18+ recommended)
|
|
117
|
-
- **npm**: 8.0.0 or higher (or yarn 1.22+)
|
|
118
|
-
- **Git**: For version control (recommended)
|
|
119
|
-
- **Operating System**: Windows, macOS, or Linux
|
|
120
|
-
|
|
121
|
-
## Installation
|
|
122
|
-
|
|
123
|
-
```bash
|
|
124
|
-
npm install -g specpilot
|
|
125
|
-
```
|
|
27
|
+
After creating a project, follow these steps to populate your specifications using AI:
|
|
126
28
|
|
|
127
|
-
|
|
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
|
|
128
33
|
|
|
129
|
-
|
|
130
|
-
specpilot --version
|
|
131
|
-
# Should output: 1.2.2 (or current version)
|
|
34
|
+
This AI-assisted approach ensures comprehensive, high-quality specifications tailored to your project needs.
|
|
132
35
|
|
|
133
|
-
|
|
134
|
-
# Shows available commands
|
|
135
|
-
```
|
|
36
|
+
## Commands
|
|
136
37
|
|
|
137
|
-
|
|
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 |
|
|
138
46
|
|
|
139
|
-
###
|
|
47
|
+
### Examples
|
|
140
48
|
|
|
141
49
|
```bash
|
|
142
|
-
# Initialize with
|
|
143
|
-
specpilot init
|
|
144
|
-
|
|
145
|
-
# Specify language and framework
|
|
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
|
|
50
|
+
# Initialize with specific language/framework
|
|
51
|
+
specpilot init api --lang python --framework fastapi
|
|
150
52
|
|
|
151
|
-
#
|
|
152
|
-
specpilot
|
|
53
|
+
# Update specifications
|
|
54
|
+
specpilot specify "REST API for user management" --update
|
|
153
55
|
|
|
154
|
-
#
|
|
155
|
-
specpilot init my-project --no-prompts
|
|
156
|
-
```
|
|
157
|
-
|
|
158
|
-
### Additional Commands
|
|
159
|
-
|
|
160
|
-
```bash
|
|
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
|
|
56
|
+
# Validate with auto-fix
|
|
169
57
|
specpilot validate --fix
|
|
170
|
-
|
|
171
|
-
# List available templates
|
|
172
|
-
specpilot list
|
|
173
|
-
|
|
174
|
-
# Migrate legacy structures (only if you have old .project-spec folder)
|
|
175
|
-
# Note: Only use this if you're upgrading from an older SpecPilot version
|
|
176
|
-
specpilot migrate --from complex --to simple --backup
|
|
177
|
-
|
|
178
|
-
# Generate or update specs from a natural language description
|
|
179
|
-
specpilot specify "A simple REST API for todos" --update
|
|
180
58
|
```
|
|
181
59
|
|
|
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
|
|
189
|
-
|
|
190
|
-
> Tip: Run `specpilot --help` or `specpilot <command> --help` for full options.
|
|
60
|
+
## Supported Languages & Frameworks
|
|
191
61
|
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
### Global Configuration
|
|
62
|
+
### TypeScript
|
|
195
63
|
|
|
196
|
-
|
|
64
|
+
- **React**: SPA applications
|
|
65
|
+
- **Express**: REST APIs
|
|
66
|
+
- **Next.js**: Full-stack apps
|
|
67
|
+
- **CLI**: Command-line tools
|
|
197
68
|
|
|
198
|
-
|
|
69
|
+
### JavaScript
|
|
199
70
|
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
71
|
+
- **React**: SPA applications
|
|
72
|
+
- **Express**: REST APIs
|
|
73
|
+
- **Next.js**: Full-stack apps
|
|
74
|
+
- **CLI**: Command-line tools
|
|
204
75
|
|
|
205
|
-
###
|
|
76
|
+
### Python
|
|
206
77
|
|
|
207
|
-
|
|
78
|
+
- **FastAPI**: Modern REST APIs
|
|
79
|
+
- **Django**: Full-stack applications
|
|
80
|
+
- **Data Science**: ML/Data Science projects
|
|
208
81
|
|
|
209
|
-
|
|
210
|
-
project:
|
|
211
|
-
name: "my-project"
|
|
212
|
-
description: "My awesome project"
|
|
213
|
-
language: "typescript"
|
|
214
|
-
framework: "react"
|
|
215
|
-
version: "1.1.1"
|
|
82
|
+
## Project Structure
|
|
216
83
|
|
|
217
|
-
|
|
218
|
-
- "Follow specification-driven development"
|
|
219
|
-
- "Maintain comprehensive documentation"
|
|
220
|
-
- "Use TypeScript strict mode"
|
|
84
|
+
SpecPilot generates a `.specs/` folder with organized subdirectories:
|
|
221
85
|
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
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
|
|
225
93
|
```
|
|
226
94
|
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
### Available Templates
|
|
230
|
-
|
|
231
|
-
#### TypeScript / JavaScript
|
|
232
|
-
|
|
233
|
-
- **Generic**: Basic TypeScript/JavaScript project structure
|
|
234
|
-
- **React**: React application with modern tooling
|
|
235
|
-
- **Express**: REST API server setup
|
|
236
|
-
|
|
237
|
-
#### Python
|
|
238
|
-
|
|
239
|
-
- **Generic**: Basic Python project structure
|
|
240
|
-
- **FastAPI**: Modern API development
|
|
241
|
-
- **Django**: Web application framework
|
|
242
|
-
|
|
243
|
-
> **Note**: SpecPilot uses built-in templates that are embedded in the code for reliability and consistency. Run `specpilot list` to see all currently available templates.
|
|
244
|
-
|
|
245
|
-
### Custom Templates
|
|
246
|
-
|
|
247
|
-
> **Note**: SpecPilot currently uses built-in templates that are embedded in the code for optimal reliability and consistency. Custom external template support is not currently implemented.
|
|
248
|
-
|
|
249
|
-
If you need different project structures, you can:
|
|
250
|
-
|
|
251
|
-
1. Use `specpilot init` to create the base `.specs` structure
|
|
252
|
-
2. Manually customize the generated files in `.specs/` to match your needs
|
|
253
|
-
3. Use the built-in templates as a starting point and extend them in your project
|
|
95
|
+
### Key Files
|
|
254
96
|
|
|
255
|
-
|
|
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)
|
|
256
102
|
|
|
257
|
-
|
|
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
|
|
103
|
+
## Configuration
|
|
266
104
|
|
|
267
|
-
|
|
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
|
|
281
|
-
```
|
|
105
|
+
SpecPilot requires no global configuration. Each project is self-contained with settings in `project.yaml`.
|
|
282
106
|
|
|
283
107
|
## Troubleshooting
|
|
284
108
|
|
|
@@ -287,218 +111,89 @@ project-root/
|
|
|
287
111
|
#### Permission Errors
|
|
288
112
|
|
|
289
113
|
```bash
|
|
290
|
-
# Fix permission issues
|
|
291
114
|
sudo chown -R $USER ~/.npm-global
|
|
292
115
|
npm config set prefix '~/.npm-global'
|
|
293
116
|
```
|
|
294
117
|
|
|
295
|
-
## Configuration examples
|
|
296
|
-
|
|
297
118
|
#### Template Not Found
|
|
298
119
|
|
|
299
120
|
```bash
|
|
300
|
-
|
|
301
|
-
specpilot list
|
|
121
|
+
specpilot list --verbose
|
|
302
122
|
```
|
|
303
123
|
|
|
304
124
|
#### Validation Failures
|
|
305
125
|
|
|
306
126
|
```bash
|
|
307
|
-
|
|
308
|
-
specpilot validate --verbose
|
|
309
|
-
|
|
310
|
-
# Auto-fix common issues
|
|
311
|
-
specpilot validate --fix
|
|
127
|
+
specpilot validate --verbose --fix
|
|
312
128
|
```
|
|
313
129
|
|
|
314
130
|
#### Migration Issues
|
|
315
131
|
|
|
316
132
|
**Error: "Source structure 'complex' not found"**
|
|
317
133
|
|
|
318
|
-
This means you're trying to migrate from a structure that doesn't exist in your project.
|
|
319
|
-
|
|
320
134
|
```bash
|
|
321
|
-
# Check what's in your project directory
|
|
322
|
-
ls -la
|
|
323
|
-
|
|
324
135
|
# For NEW projects, use:
|
|
325
136
|
specpilot init my-project
|
|
326
137
|
|
|
327
138
|
# For EXISTING projects without specs:
|
|
328
139
|
specpilot add-specs
|
|
329
140
|
|
|
330
|
-
# Only use migrate if you have an old .project-spec folder
|
|
141
|
+
# Only use migrate if you have an old .project-spec folder
|
|
331
142
|
specpilot migrate --from complex --to simple --backup
|
|
332
143
|
```
|
|
333
144
|
|
|
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
145
|
### Debug Mode
|
|
347
146
|
|
|
348
147
|
```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
|
|
148
|
+
DEBUG=specpilot specpilot <command>
|
|
357
149
|
```
|
|
358
150
|
|
|
359
|
-
|
|
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
|
|
371
|
-
```
|
|
372
|
-
|
|
373
|
-
## Getting Started
|
|
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
|
|
151
|
+
## Why SpecPilot?
|
|
410
152
|
|
|
411
|
-
|
|
153
|
+
SpecPilot implements **Specification-Driven Development (SDD)** where specifications come first:
|
|
412
154
|
|
|
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
155
|
```
|
|
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
|
|
156
|
+
Specifications → Architecture → Code → Tests → Deployment
|
|
445
157
|
```
|
|
446
158
|
|
|
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
|
|
452
|
-
|
|
453
|
-
> **Note**: Programmatic API support is not currently available. SpecPilot is designed as a CLI-first tool.
|
|
159
|
+
**Benefits:**
|
|
454
160
|
|
|
455
|
-
**
|
|
456
|
-
|
|
457
|
-
|
|
458
|
-
|
|
459
|
-
|
|
460
|
-
specpilot validate --fix
|
|
461
|
-
```
|
|
161
|
+
- **Clarity**: Everyone understands what needs to be built
|
|
162
|
+
- **Consistency**: Standardized structure across projects
|
|
163
|
+
- **Quality**: Built-in validation and testing
|
|
164
|
+
- **AI-Ready**: Clear context for AI assistants
|
|
165
|
+
- **Maintainable**: Comprehensive documentation
|
|
462
166
|
|
|
463
167
|
## Contributing
|
|
464
168
|
|
|
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
|
|
169
|
+
This project follows SDD principles. See [`.specs/`](.specs/) for contribution guidelines.
|
|
474
170
|
|
|
475
171
|
### Development Setup
|
|
476
172
|
|
|
477
173
|
```bash
|
|
478
|
-
# Clone and setup
|
|
479
174
|
git clone https://github.com/girishr/SpecPilot.git
|
|
480
175
|
cd SpecPilot
|
|
481
176
|
npm install
|
|
177
|
+
npm run build
|
|
178
|
+
npm link # For local testing
|
|
179
|
+
```
|
|
482
180
|
|
|
483
|
-
|
|
484
|
-
npm run dev -- init test-project --lang typescript
|
|
181
|
+
### Quick Contribution Guide
|
|
485
182
|
|
|
486
|
-
|
|
487
|
-
|
|
183
|
+
1. Review [`.specs/project/requirements.md`](.specs/project/requirements.md)
|
|
184
|
+
2. Check [`.specs/planning/tasks.md`](.specs/planning/tasks.md)
|
|
185
|
+
3. Update specs when making changes
|
|
186
|
+
4. Run `specpilot validate` before committing
|
|
488
187
|
|
|
489
|
-
|
|
490
|
-
npm run test:coverage
|
|
188
|
+
## Documentation
|
|
491
189
|
|
|
492
|
-
|
|
493
|
-
|
|
494
|
-
|
|
495
|
-
# Test CLI locally
|
|
496
|
-
node cli.js init my-test --lang python
|
|
497
|
-
```
|
|
190
|
+
- **[Full Guide](docs/GUIDE.md)**: Comprehensive documentation
|
|
191
|
+
- **[CHANGELOG](CHANGELOG.md)**: Version history
|
|
192
|
+
- **[Issues](https://github.com/girishr/SpecPilot/issues)**: Bug reports & feature requests
|
|
498
193
|
|
|
499
194
|
## License
|
|
500
195
|
|
|
501
|
-
MIT License - see LICENSE file for details.
|
|
196
|
+
MIT License - see [LICENSE](LICENSE) file for details.
|
|
502
197
|
|
|
503
198
|
---
|
|
504
199
|
|
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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"}
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"add-specs.d.ts","sourceRoot":"","sources":["../../src/commands/add-specs.ts"],"names":[],"mappings":"AAWA,MAAM,WAAW,eAAe;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,OAAO,CAAC;IACpB,YAAY,EAAE,OAAO,CAAC;IACtB,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,wBAAsB,eAAe,CAAC,OAAO,EAAE,eAAe,
|
|
1
|
+
{"version":3,"file":"add-specs.d.ts","sourceRoot":"","sources":["../../src/commands/add-specs.ts"],"names":[],"mappings":"AAWA,MAAM,WAAW,eAAe;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,OAAO,CAAC;IACpB,YAAY,EAAE,OAAO,CAAC;IACtB,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,wBAAsB,eAAe,CAAC,OAAO,EAAE,eAAe,iBAuH7D"}
|
|
@@ -106,15 +106,8 @@ async function addSpecsCommand(options) {
|
|
|
106
106
|
});
|
|
107
107
|
logger.success('✅ .specs folder created successfully!');
|
|
108
108
|
logger.info(`📁 Location: ${specsDir}`);
|
|
109
|
-
// Show next steps
|
|
110
|
-
|
|
111
|
-
🚀 Next steps to populate your specs with AI:
|
|
112
|
-
1. Open .specs/README.md for full guidance
|
|
113
|
-
2. Copy the onboarding prompt from .specs/development/prompts.md
|
|
114
|
-
3. Paste into your AI agent and run it
|
|
115
|
-
4. Review the generated spec files
|
|
116
|
-
|
|
117
|
-
Your project is now ready for AI-assisted development!`));
|
|
109
|
+
// Show next steps with logo
|
|
110
|
+
logger.displayInitSuccess(projectInfo?.name || 'Project', projectDir, specsDir);
|
|
118
111
|
}
|
|
119
112
|
catch (error) {
|
|
120
113
|
logger.error(`❌ Failed to add specs: ${error instanceof Error ? error.message : 'Unknown error'}`);
|