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.
Files changed (60) hide show
  1. package/README.md +126 -378
  2. package/dist/cli.js +13 -0
  3. package/dist/cli.js.map +1 -1
  4. package/dist/commands/add-specs.d.ts.map +1 -1
  5. package/dist/commands/add-specs.js +6 -18
  6. package/dist/commands/add-specs.js.map +1 -1
  7. package/dist/commands/init.d.ts.map +1 -1
  8. package/dist/commands/init.js +123 -48
  9. package/dist/commands/init.js.map +1 -1
  10. package/dist/commands/list.d.ts.map +1 -1
  11. package/dist/commands/list.js +26 -34
  12. package/dist/commands/list.js.map +1 -1
  13. package/dist/commands/migrate.d.ts.map +1 -1
  14. package/dist/commands/migrate.js +16 -11
  15. package/dist/commands/migrate.js.map +1 -1
  16. package/dist/commands/specify.d.ts.map +1 -1
  17. package/dist/commands/specify.js +112 -20
  18. package/dist/commands/specify.js.map +1 -1
  19. package/dist/commands/validate.d.ts.map +1 -1
  20. package/dist/commands/validate.js +35 -19
  21. package/dist/commands/validate.js.map +1 -1
  22. package/dist/utils/agentConfigGenerator.d.ts +15 -0
  23. package/dist/utils/agentConfigGenerator.d.ts.map +1 -0
  24. package/dist/utils/agentConfigGenerator.js +234 -0
  25. package/dist/utils/agentConfigGenerator.js.map +1 -0
  26. package/dist/utils/codeAnalyzer.js +10 -10
  27. package/dist/utils/codeAnalyzer.js.map +1 -1
  28. package/dist/utils/frameworks.d.ts +2 -0
  29. package/dist/utils/frameworks.d.ts.map +1 -0
  30. package/dist/utils/frameworks.js +11 -0
  31. package/dist/utils/frameworks.js.map +1 -0
  32. package/dist/utils/ideConfigGenerator.d.ts +20 -0
  33. package/dist/utils/ideConfigGenerator.d.ts.map +1 -0
  34. package/dist/utils/ideConfigGenerator.js +176 -0
  35. package/dist/utils/ideConfigGenerator.js.map +1 -0
  36. package/dist/utils/logger.d.ts +19 -0
  37. package/dist/utils/logger.d.ts.map +1 -1
  38. package/dist/utils/logger.js +145 -0
  39. package/dist/utils/logger.js.map +1 -1
  40. package/dist/utils/projectDetector.d.ts.map +1 -1
  41. package/dist/utils/projectDetector.js.map +1 -1
  42. package/dist/utils/projectMigrator.d.ts.map +1 -1
  43. package/dist/utils/projectMigrator.js +36 -33
  44. package/dist/utils/projectMigrator.js.map +1 -1
  45. package/dist/utils/specFileGenerator.d.ts +25 -0
  46. package/dist/utils/specFileGenerator.d.ts.map +1 -0
  47. package/dist/utils/specFileGenerator.js +677 -0
  48. package/dist/utils/specFileGenerator.js.map +1 -0
  49. package/dist/utils/specGenerator.d.ts +11 -14
  50. package/dist/utils/specGenerator.d.ts.map +1 -1
  51. package/dist/utils/specGenerator.js +24 -430
  52. package/dist/utils/specGenerator.js.map +1 -1
  53. package/dist/utils/specValidator.d.ts.map +1 -1
  54. package/dist/utils/specValidator.js +4 -6
  55. package/dist/utils/specValidator.js.map +1 -1
  56. package/dist/utils/templateEngine.d.ts +9 -3
  57. package/dist/utils/templateEngine.d.ts.map +1 -1
  58. package/dist/utils/templateEngine.js +36 -36
  59. package/dist/utils/templateEngine.js.map +1 -1
  60. package/package.json +8 -3
package/README.md CHANGED
@@ -1,47 +1,9 @@
1
- # SpecPilot SDD CLI
1
+ # SpecPilot
2
2
 
3
- A CLI tool for initializing specification-driven development projects with flexible, production-ready structures.
3
+ [![npm version](https://img.shields.io/npm/v/specpilot.svg)](https://www.npmjs.com/package/specpilot)
4
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
4
5
 
5
- ## Table of Contents
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
- # Initialize your first project
14
+ # Create a new project
53
15
  specpilot init my-project --lang typescript --framework react
54
16
 
55
- # Start coding with full control
56
- cd my-project
57
- # Your .specs/ folder is ready with guidelines, not prescriptions
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
- ```bash
87
- mkdir my-app && cd my-app
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
- **With SpecPilot:**
25
+ ### 🚀 Next Steps to Populate Your Specs with AI
93
26
 
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
- ```
104
-
105
- ### 🌟 **Why SDD is the Future**
27
+ After creating a project, follow these steps to populate your specifications using AI:
106
28
 
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
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
- **SpecPilot gives you a professional project foundation in seconds, so you can focus on building great features instead of figuring out folder structures.**
34
+ This AI-assisted approach ensures comprehensive, high-quality specifications tailored to your project needs.
113
35
 
114
- ## Prerequisites
36
+ ## Commands
115
37
 
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
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
- ## Installation
47
+ ### Examples
122
48
 
123
49
  ```bash
124
- npm install -g specpilot
125
- ```
126
-
127
- ### Verify Installation
50
+ # Initialize with specific language/framework
51
+ specpilot init api --lang python --framework fastapi
128
52
 
129
- ```bash
130
- specpilot --version
131
- # Should output: 1.2.2 (or current version)
53
+ # Update specifications
54
+ specpilot specify "REST API for user management" --update
132
55
 
133
- specpilot --help
134
- # Shows available commands
56
+ # Validate with auto-fix
57
+ specpilot validate --fix
135
58
  ```
136
59
 
137
- ## Usage Examples
60
+ ## Supported Languages & Frameworks
138
61
 
139
- ### Basic Project Initialization
62
+ ### TypeScript
140
63
 
141
- ```bash
142
- # Initialize with default settings (.specs folder)
143
- specpilot init my-project
64
+ - **React**: SPA applications
65
+ - **Express**: REST APIs
66
+ - **Next.js**: Full-stack apps
67
+ - **CLI**: Command-line tools
144
68
 
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
69
+ ### JavaScript
150
70
 
151
- # Use a custom specs folder name
152
- specpilot init my-project --specs-name .project-specs
71
+ - **React**: SPA applications
72
+ - **Express**: REST APIs
73
+ - **Next.js**: Full-stack apps
74
+ - **CLI**: Command-line tools
153
75
 
154
- # Skip interactive prompts
155
- specpilot init my-project --no-prompts
156
- ```
76
+ ### Python
157
77
 
158
- ### Additional Commands
78
+ - **FastAPI**: Modern REST APIs
79
+ - **Django**: Full-stack applications
80
+ - **Data Science**: ML/Data Science projects
159
81
 
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
169
- specpilot validate --fix
170
-
171
- # List available templates
172
- specpilot list
82
+ ## Project Structure
173
83
 
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
84
+ SpecPilot generates a `.specs/` folder with organized subdirectories:
177
85
 
178
- # Generate or update specs from a natural language description
179
- specpilot specify "A simple REST API for todos" --update
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
- #### When to Use Which Command
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
- > Tip: Run `specpilot --help` or `specpilot <command> --help` for full options.
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
- ### Global Configuration
105
+ SpecPilot requires no global configuration. Each project is self-contained with settings in `project.yaml`.
195
106
 
196
- > **Note**: Global configuration file support (`~/.specpilot-config.yaml`) is not currently implemented. Configuration is done through command-line options and project-level `.specs/project/project.yaml` files.
107
+ ### IDE & Agent Support
197
108
 
198
- **Current configuration options via CLI:**
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
- ```bash
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
- ### Project Configuration
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
- After initialization, customize `.specs/project/project.yaml`:
119
+ **Cloud-Based AI Agents (Instruction Files):**
208
120
 
209
- ```yaml
210
- project:
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
- ## Templates
124
+ **Generated Configuration Files:**
228
125
 
229
- ### Available Templates
126
+ For **all** IDE/Agent selections: `.github/copilot-instructions.md`
230
127
 
231
- #### TypeScript / JavaScript
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
- - **Generic**: Basic TypeScript/JavaScript project structure
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
- #### Python
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
- - **Generic**: Basic Python project structure
240
- - **FastAPI**: Modern API development
241
- - **Django**: Web application framework
138
+ For cloud agents:
242
139
 
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.
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
- ### Custom Templates
143
+ The generated settings/instructions automatically configure your AI agent to:
246
144
 
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.
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
- If you need different project structures, you can:
150
+ **Example:**
250
151
 
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
254
-
255
- ## Features
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
- # List available templates
301
- specpilot list
174
+ specpilot list --verbose
302
175
  ```
303
176
 
304
177
  #### Validation Failures
305
178
 
306
179
  ```bash
307
- # Run with detailed error output
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
- # Enable debug logging
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
- ## 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
204
+ ## Why SpecPilot?
410
205
 
411
- MIT License - see [LICENSE](LICENSE) file for details.
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
- ### Enterprise Integration
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
- > **Note**: Programmatic API support is not currently available. SpecPilot is designed as a CLI-first tool.
454
-
455
- **Use in shell scripts:**
456
-
457
- ```bash
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 specification-driven development principles. Please review our [`.specs/`](.specs/) folder for detailed contribution guidelines, architecture decisions, and development context.
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
- # Run in development mode
484
- npm run dev -- init test-project --lang typescript
485
-
486
- # Run tests
487
- npm test
234
+ ### Quick Contribution Guide
488
235
 
489
- # Run tests with coverage
490
- npm run test:coverage
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
- # Build for production
493
- npm run build
241
+ ## Documentation
494
242
 
495
- # Test CLI locally
496
- node cli.js init my-test --lang python
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":"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"}
1
+ {"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}