nspecgen

A Node.js + TypeScript CLI tool for generating comprehensive project specifications using AI. Creates structured markdown documentation for architecture, UI/UX, API, deployment, roadmap, and actionable task lists.

Usage Video

https://youtu.be/9usxe3V3Fuw

✨ Features

• 🤖 AI-Powered Generation - Uses OpenAI GPT-4 (with support for other providers)
• 📋 Comprehensive Specs - Architecture, UI/UX, API, Deployment, and Roadmap documentation
• ⚡ Two Modes - Quick (minimal questions) or Detailed (comprehensive questionnaire)
• 📝 Structured Output - Clean markdown with Summary, Main Content, and Assumptions sections
• ✅ Task Generation - Automatic task list creation with actionable checkboxes
• 🔧 Configurable - Support for multiple AI providers and custom settings
• 🛡️ Safe Operations - Smart file handling with overwrite protection

🚀 Installation

Global Installation (Recommended)

npm install -g nspecgen

Local Development Installation

git clone https://github.com/nuvo-code/nspecgen.git
cd nspecgen
npm install
npm run build
npm link

Verify Installation

nspecgen --version

📖 Quick Start

1. Initialize configuration:

   nspecgen init

2. Generate specifications:

   nspecgen run --mode quick

3. View generated files:

   ls specs/
   # architecture.md  ui-ux.md  api.md  deployment.md  roadmap.md  tasks.md

🎯 Usage

Commands

# Initialize configuration
nspecgen init [--force]

# Generate all specifications
nspecgen run [options]

# Add specific specification
nspecgen add <step> [options]

# Update existing specifications
nspecgen update [step] [options]

Options

• --mode <mode> - Generation mode: quick or detailed (default: quick)
• --steps <steps> - Comma-separated list of steps: architecture,ui,api,deployment,roadmap
• --output <dir> - Output directory (default: ./specs)
• --force - Overwrite existing files without prompting
• --provider <provider> - AI provider: openai, anthropic, gemini, local
• --model <model> - AI model to use

Examples

# Quick generation with minimal questions
nspecgen run --mode quick

# Detailed generation with comprehensive questionnaire
nspecgen run --mode detailed --output ./documentation

# Generate only architecture and API specs
nspecgen run --steps architecture,api

# Update all existing specifications
nspecgen update --all

# Use specific AI provider and model
nspecgen run --provider openai --model gpt-4-turbo

⚙️ Configuration

Run nspecgen init to create a specgen.config.json file in your project root:

{
  "provider": "openai",
  "model": "gpt-4",
  "outputDir": "./specs",
  "defaultMode": "quick",
  "steps": {
    "architecture": true,
    "ui": true,
    "api": true,
    "deployment": true,
    "roadmap": true
  }
}

Environment Variables

Set your API key using environment variables:

# OpenAI
export OPENAI_API_KEY="your-api-key"

# Anthropic
export ANTHROPIC_API_KEY="your-api-key"

# Google Gemini
export GEMINI_API_KEY="your-api-key"

# Or set in config
export NSPECGEN_API_KEY="your-api-key"
export NSPECGEN_PROVIDER="openai"
export NSPECGEN_MODEL="gpt-4"

📁 Generated Output

After running nspecgen run, you'll find structured documentation:

specs/
├── architecture.md    # System architecture and technology stack
├── ui-ux.md          # User interface and experience design
├── api.md            # API specification and endpoints
├── deployment.md     # Infrastructure and deployment strategy
├── roadmap.md        # Project timeline and milestones
└── tasks.md          # Actionable task checklist

Each file follows a consistent structure:

• Summary - Key points and decisions (5-7 bullets)
• Main Content - Detailed specifications and guidelines
• Assumptions & Open Questions - Areas needing clarification

🔧 Development

Building from Source

git clone https://github.com/nuvo-code/nspecgen.git
cd nspecgen
npm install
npm run build

Running Tests

npm test
npm run test:watch

Local Development

npm run dev        # Watch mode compilation
npm run link       # Link for global usage
npm run unlink     # Remove global link

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Submit a pull request

📋 Roadmap

• Additional AI provider implementations (Local)
• CI/CD integration for automatic spec updates
• Plugin system for custom specification steps
• Web UI interface
• Template system for different project types
• Export to different formats (PDF, Word, etc.)

📄 License

MIT License - see LICENSE file for details.

🆘 Support

• 📖 Documentation
• 🐛 Issue Tracker
• 💬 Discussions