specpilot 1.2.1 → 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 +90 -419
- 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 +18 -9
- 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/dist/utils/specGenerator.d.ts.map +1 -1
- package/dist/utils/specGenerator.js +1 -0
- package/dist/utils/specGenerator.js.map +1 -1
- package/package.json +5 -4
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,251 +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
|
-
|
|
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
|
|
128
|
-
|
|
129
|
-
```bash
|
|
130
|
-
specpilot --version
|
|
131
|
-
# Should output: 1.1.2 (or current version)
|
|
132
|
-
|
|
133
|
-
specpilot --help
|
|
134
|
-
# Shows available commands
|
|
135
|
-
```
|
|
50
|
+
# Initialize with specific language/framework
|
|
51
|
+
specpilot init api --lang python --framework fastapi
|
|
136
52
|
|
|
137
|
-
|
|
53
|
+
# Update specifications
|
|
54
|
+
specpilot specify "REST API for user management" --update
|
|
138
55
|
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
```bash
|
|
142
|
-
# Initialize with default settings (.specs folder)
|
|
143
|
-
specpilot init my-project
|
|
144
|
-
|
|
145
|
-
# Specify language and framework
|
|
146
|
-
specpilot init my-project --lang typescript --framework react
|
|
147
|
-
specpilot init my-project --lang typescript --framework express
|
|
148
|
-
specpilot init my-project --lang python --framework fastapi
|
|
149
|
-
specpilot init my-project --lang python --framework django
|
|
150
|
-
|
|
151
|
-
# Use a custom specs folder name
|
|
152
|
-
specpilot init my-project --specs-name .project-specs
|
|
153
|
-
|
|
154
|
-
# Skip interactive prompts
|
|
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.
|
|
191
|
-
|
|
192
|
-
## Configuration
|
|
193
|
-
|
|
194
|
-
### Global Configuration
|
|
60
|
+
## Supported Languages & Frameworks
|
|
195
61
|
|
|
196
|
-
|
|
62
|
+
### TypeScript
|
|
197
63
|
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
license: "MIT"
|
|
203
|
-
aiTracking: true
|
|
64
|
+
- **React**: SPA applications
|
|
65
|
+
- **Express**: REST APIs
|
|
66
|
+
- **Next.js**: Full-stack apps
|
|
67
|
+
- **CLI**: Command-line tools
|
|
204
68
|
|
|
205
|
-
|
|
206
|
-
typescript:
|
|
207
|
-
framework: "express"
|
|
208
|
-
python:
|
|
209
|
-
framework: "fastapi"
|
|
69
|
+
### JavaScript
|
|
210
70
|
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
71
|
+
- **React**: SPA applications
|
|
72
|
+
- **Express**: REST APIs
|
|
73
|
+
- **Next.js**: Full-stack apps
|
|
74
|
+
- **CLI**: Command-line tools
|
|
215
75
|
|
|
216
|
-
###
|
|
76
|
+
### Python
|
|
217
77
|
|
|
218
|
-
|
|
78
|
+
- **FastAPI**: Modern REST APIs
|
|
79
|
+
- **Django**: Full-stack applications
|
|
80
|
+
- **Data Science**: ML/Data Science projects
|
|
219
81
|
|
|
220
|
-
|
|
221
|
-
project:
|
|
222
|
-
name: "my-project"
|
|
223
|
-
description: "My awesome project"
|
|
224
|
-
language: "typescript"
|
|
225
|
-
framework: "react"
|
|
226
|
-
version: "1.1.1"
|
|
82
|
+
## Project Structure
|
|
227
83
|
|
|
228
|
-
|
|
229
|
-
- "Follow specification-driven development"
|
|
230
|
-
- "Maintain comprehensive documentation"
|
|
231
|
-
- "Use TypeScript strict mode"
|
|
84
|
+
SpecPilot generates a `.specs/` folder with organized subdirectories:
|
|
232
85
|
|
|
233
|
-
ai-context:
|
|
234
|
-
- "Track all development prompts"
|
|
235
|
-
- "Maintain architectural decisions"
|
|
236
86
|
```
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
- **Generic**: Basic TypeScript project structure
|
|
245
|
-
- **React**: React application with modern tooling
|
|
246
|
-
- **Express**: REST API server setup
|
|
247
|
-
|
|
248
|
-
#### Python
|
|
249
|
-
|
|
250
|
-
- **Generic**: Basic Python project structure
|
|
251
|
-
- **FastAPI**: Modern API development
|
|
252
|
-
- **Django**: Web application framework
|
|
253
|
-
|
|
254
|
-
> **Note**: Run `specpilot list` to see all currently available templates and their status.
|
|
255
|
-
|
|
256
|
-
### Custom Templates
|
|
257
|
-
|
|
258
|
-
> **Coming Soon**: Custom template support is planned for future releases. Currently, SpecPilot uses built-in templates optimized for specification-driven development.
|
|
259
|
-
|
|
260
|
-
**Planned custom template structure:**
|
|
261
|
-
|
|
262
|
-
```text
|
|
263
|
-
~/.specpilot-templates/
|
|
264
|
-
├── my-custom-template/
|
|
265
|
-
│ ├── template.yaml
|
|
266
|
-
│ ├── .specs/
|
|
267
|
-
│ └── src/
|
|
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
|
|
268
93
|
```
|
|
269
94
|
|
|
270
|
-
|
|
95
|
+
### Key Files
|
|
271
96
|
|
|
272
|
-
-
|
|
273
|
-
-
|
|
274
|
-
-
|
|
275
|
-
-
|
|
276
|
-
-
|
|
277
|
-
- **AI Integration**: Dedicated prompts tracking for development cycles
|
|
278
|
-
- **Migration Support**: Helps transition older structures
|
|
279
|
-
- **Template Listing**: Discover available language/framework combinations
|
|
280
|
-
- **Developer Attribution**: Prompts for developer name and personalizes generated specs
|
|
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)
|
|
281
102
|
|
|
282
|
-
##
|
|
103
|
+
## Configuration
|
|
283
104
|
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
```text
|
|
287
|
-
project-root/
|
|
288
|
-
├── .specs/
|
|
289
|
-
│ ├── project/ # project.yaml, requirements.md, project-plan.md
|
|
290
|
-
│ ├── architecture/ # architecture.md, api.yaml
|
|
291
|
-
│ ├── planning/ # tasks.md, roadmap.md
|
|
292
|
-
│ ├── quality/ # tests.md
|
|
293
|
-
│ └── development/ # docs.md, context.md, prompts.md
|
|
294
|
-
├── src/
|
|
295
|
-
└── README.md
|
|
296
|
-
```
|
|
105
|
+
SpecPilot requires no global configuration. Each project is self-contained with settings in `project.yaml`.
|
|
297
106
|
|
|
298
107
|
## Troubleshooting
|
|
299
108
|
|
|
@@ -302,228 +111,90 @@ project-root/
|
|
|
302
111
|
#### Permission Errors
|
|
303
112
|
|
|
304
113
|
```bash
|
|
305
|
-
# Fix permission issues
|
|
306
114
|
sudo chown -R $USER ~/.npm-global
|
|
307
115
|
npm config set prefix '~/.npm-global'
|
|
308
116
|
```
|
|
309
117
|
|
|
310
|
-
````text
|
|
311
|
-
# Configuration examples
|
|
312
|
-
|
|
313
118
|
#### Template Not Found
|
|
314
119
|
|
|
315
120
|
```bash
|
|
316
|
-
|
|
317
|
-
specpilot list
|
|
121
|
+
specpilot list --verbose
|
|
318
122
|
```
|
|
319
123
|
|
|
320
124
|
#### Validation Failures
|
|
321
125
|
|
|
322
126
|
```bash
|
|
323
|
-
|
|
324
|
-
specpilot validate --verbose
|
|
325
|
-
|
|
326
|
-
# Auto-fix common issues
|
|
327
|
-
specpilot validate --fix
|
|
127
|
+
specpilot validate --verbose --fix
|
|
328
128
|
```
|
|
329
129
|
|
|
330
130
|
#### Migration Issues
|
|
331
131
|
|
|
332
132
|
**Error: "Source structure 'complex' not found"**
|
|
333
133
|
|
|
334
|
-
This means you're trying to migrate from a structure that doesn't exist in your project.
|
|
335
|
-
|
|
336
134
|
```bash
|
|
337
|
-
# Check what's in your project directory
|
|
338
|
-
ls -la
|
|
339
|
-
|
|
340
135
|
# For NEW projects, use:
|
|
341
136
|
specpilot init my-project
|
|
342
137
|
|
|
343
138
|
# For EXISTING projects without specs:
|
|
344
139
|
specpilot add-specs
|
|
345
140
|
|
|
346
|
-
# Only use migrate if you have an old .project-spec folder
|
|
141
|
+
# Only use migrate if you have an old .project-spec folder
|
|
347
142
|
specpilot migrate --from complex --to simple --backup
|
|
348
143
|
```
|
|
349
144
|
|
|
350
|
-
**When to use migrate:**
|
|
351
|
-
- You have an old `.project-spec` folder from a previous SpecPilot version
|
|
352
|
-
- You're upgrading between SpecPilot structure versions
|
|
353
|
-
- You need to convert between specification formats
|
|
354
|
-
|
|
355
|
-
**When NOT to use migrate:**
|
|
356
|
-
- Starting a new project (use `init` instead)
|
|
357
|
-
- Adding specs to existing code (use `add-specs` instead)
|
|
358
|
-
- Your project has no specification folder yet
|
|
359
|
-
|
|
360
145
|
### Debug Mode
|
|
361
146
|
|
|
362
147
|
```bash
|
|
363
|
-
|
|
364
|
-
DEBUG=specpilot specpilot init my-project
|
|
365
|
-
|
|
366
|
-
# Verbose output
|
|
367
|
-
specpilot validate --verbose
|
|
368
|
-
|
|
369
|
-
# Check what templates are available
|
|
370
|
-
specpilot list --verbose
|
|
148
|
+
DEBUG=specpilot specpilot <command>
|
|
371
149
|
```
|
|
372
150
|
|
|
373
|
-
|
|
374
|
-
|
|
375
|
-
```bash
|
|
376
|
-
# Show help
|
|
377
|
-
specpilot --help
|
|
378
|
-
|
|
379
|
-
# Command-specific help
|
|
380
|
-
specpilot init --help
|
|
381
|
-
specpilot validate --help
|
|
382
|
-
specpilot list --help
|
|
383
|
-
specpilot migrate --help
|
|
384
|
-
specpilot specify --help
|
|
385
|
-
```
|
|
386
|
-
|
|
387
|
-
## Getting Started
|
|
388
|
-
|
|
389
|
-
1. **Initialize your project**: `specpilot init my-project --lang typescript`
|
|
390
|
-
2. **Review the generated `.specs` structure** - This provides your flexible framework
|
|
391
|
-
3. **Customize the specifications** in `.specs/project/project.yaml`
|
|
392
|
-
4. **Document your architecture** in `.specs/architecture/architecture.md`
|
|
393
|
-
5. **Track all development prompts** in `.specs/development/prompts.md`
|
|
394
|
-
6. **Plan your work** in `.specs/planning/tasks.md` and `.specs/planning/roadmap.md`
|
|
395
|
-
7. **Define tests** in `.specs/quality/tests.md`
|
|
396
|
-
8. **Start building** your production code in `src/`
|
|
397
|
-
|
|
398
|
-
### Best Practices
|
|
399
|
-
|
|
400
|
-
- **Start with specifications**: Define what you're building before coding
|
|
401
|
-
- **Keep prompts updated**: Log all AI interactions for future reference
|
|
402
|
-
- **Validate regularly**: Use `specpilot validate` during development
|
|
403
|
-
- **Follow the subfolder structure**: Organize specs in `project/`, `architecture/`, `planning/`, `quality/`, `development/`
|
|
404
|
-
- **Use stable IDs**: Reference requirements and tasks by their IDs (e.g., `REQ-001`, `TASK-002`)
|
|
405
|
-
- **Version control everything**: Include `.specs/` in your git repository
|
|
406
|
-
- **Update metadata**: Keep `lastUpdated` and `version` fields current in spec files
|
|
407
|
-
|
|
408
|
-
## How to Contribute
|
|
409
|
-
|
|
410
|
-
We welcome contributions! Please:
|
|
411
|
-
|
|
412
|
-
1. Fork the repo and create a feature branch
|
|
413
|
-
2. Follow the existing code style and add tests for new features
|
|
414
|
-
3. Update documentation for new functionality
|
|
415
|
-
4. Submit a pull request with a clear description
|
|
416
|
-
|
|
417
|
-
## Version History
|
|
418
|
-
|
|
419
|
-
See [CHANGELOG.md](CHANGELOG.md) for detailed version history.
|
|
420
|
-
|
|
421
|
-
## MIT License
|
|
151
|
+
## Why SpecPilot?
|
|
422
152
|
|
|
423
|
-
|
|
153
|
+
SpecPilot implements **Specification-Driven Development (SDD)** where specifications come first:
|
|
424
154
|
|
|
425
|
-
## Extended Configuration
|
|
426
|
-
|
|
427
|
-
### CI/CD Integration
|
|
428
|
-
|
|
429
|
-
```yaml
|
|
430
|
-
# .github/workflows/specs-validation.yml
|
|
431
|
-
name: Validate Specs
|
|
432
|
-
on: [push, pull_request]
|
|
433
|
-
jobs:
|
|
434
|
-
validate:
|
|
435
|
-
runs-on: ubuntu-latest
|
|
436
|
-
steps:
|
|
437
|
-
- uses: actions/checkout@v3
|
|
438
|
-
- uses: actions/setup-node@v3
|
|
439
|
-
with:
|
|
440
|
-
node-version: '18'
|
|
441
|
-
- run: npm install -g specpilot
|
|
442
|
-
- run: specpilot validate --verbose
|
|
443
155
|
```
|
|
444
|
-
|
|
445
|
-
### Team Collaboration
|
|
446
|
-
|
|
447
|
-
```bash
|
|
448
|
-
# Initialize project for team collaboration
|
|
449
|
-
specpilot init team-project --lang typescript --framework react
|
|
450
|
-
|
|
451
|
-
# Share specs folder structure with team
|
|
452
|
-
git add .specs/
|
|
453
|
-
git commit -m "feat: add specification-driven development structure"
|
|
454
|
-
|
|
455
|
-
# Team members can validate specs consistently
|
|
456
|
-
specpilot validate --verbose
|
|
156
|
+
Specifications → Architecture → Code → Tests → Deployment
|
|
457
157
|
```
|
|
458
158
|
|
|
459
|
-
|
|
460
|
-
|
|
461
|
-
Your organization can wrap SpecPilot with internal tooling and templates. For now, use `specpilot list` to explore built-ins.
|
|
462
|
-
|
|
463
|
-
### API Usage
|
|
159
|
+
**Benefits:**
|
|
464
160
|
|
|
465
|
-
|
|
466
|
-
|
|
467
|
-
**
|
|
468
|
-
|
|
469
|
-
|
|
470
|
-
const { initProject, validateSpecs } = require("specpilot");
|
|
471
|
-
|
|
472
|
-
await initProject({
|
|
473
|
-
name: "my-project",
|
|
474
|
-
language: "typescript",
|
|
475
|
-
framework: "react"
|
|
476
|
-
});
|
|
477
|
-
```
|
|
478
|
-
|
|
479
|
-
For now, use the CLI commands or shell integration:
|
|
480
|
-
```bash
|
|
481
|
-
# Use in shell scripts
|
|
482
|
-
specpilot init my-project --lang typescript --no-prompts
|
|
483
|
-
specpilot validate --fix
|
|
484
|
-
```
|
|
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
|
|
485
166
|
|
|
486
167
|
## Contributing
|
|
487
168
|
|
|
488
|
-
This project follows
|
|
489
|
-
|
|
490
|
-
### Quick Contribution Guide
|
|
491
|
-
|
|
492
|
-
1. **Read the specs**: Review [`.specs/project/requirements.md`](.specs/project/requirements.md) and [`.specs/architecture/architecture.md`](.specs/architecture/architecture.md)
|
|
493
|
-
2. **Check current tasks**: See [`.specs/planning/tasks.md`](.specs/planning/tasks.md) for open issues
|
|
494
|
-
3. **Follow conventions**: Use the metadata format documented in [`.specs/development/docs.md`](.specs/development/docs.md)
|
|
495
|
-
4. **Update specs**: Modify relevant spec files when making changes
|
|
496
|
-
5. **Validate**: Run `specpilot validate` before committing
|
|
169
|
+
This project follows SDD principles. See [`.specs/`](.specs/) for contribution guidelines.
|
|
497
170
|
|
|
498
171
|
### Development Setup
|
|
499
172
|
|
|
500
173
|
```bash
|
|
501
|
-
# Clone and setup
|
|
502
174
|
git clone https://github.com/girishr/SpecPilot.git
|
|
503
175
|
cd SpecPilot
|
|
504
176
|
npm install
|
|
177
|
+
npm run build
|
|
178
|
+
npm link # For local testing
|
|
179
|
+
```
|
|
505
180
|
|
|
506
|
-
|
|
507
|
-
npm run dev -- init test-project --lang typescript
|
|
181
|
+
### Quick Contribution Guide
|
|
508
182
|
|
|
509
|
-
|
|
510
|
-
|
|
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
|
|
511
187
|
|
|
512
|
-
|
|
513
|
-
npm run test:coverage
|
|
188
|
+
## Documentation
|
|
514
189
|
|
|
515
|
-
|
|
516
|
-
|
|
517
|
-
|
|
518
|
-
# Test CLI locally
|
|
519
|
-
node cli.js init my-test --lang python
|
|
520
|
-
```
|
|
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
|
|
521
193
|
|
|
522
194
|
## License
|
|
523
195
|
|
|
524
|
-
MIT License - see LICENSE file for details.
|
|
196
|
+
MIT License - see [LICENSE](LICENSE) file for details.
|
|
525
197
|
|
|
526
198
|
---
|
|
527
199
|
|
|
528
200
|
_Built with specification-driven development principles for serious production projects._
|
|
529
|
-
````
|
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"}
|