🚀 Gigaspec

AI-Native Specification Framework

The AI does the thinking. We provide the structure.

Installation • Quick Start • Documentation • GitHub

🎯 What is Gigaspec?

Gigaspec is an AI-native collaboration framework that transforms how software projects are planned and built. Instead of static templates or keyword-based recommendations, Gigaspec enables deep AI analysis of your requirements with intelligent Q&A workflows.

The Problem with Traditional Tools

User: "I want to build a real-time collaborative app"
Traditional Tool: "Use Elixir!" ← No questions, no reasoning

The Gigaspec Way

User: "I want to build a real-time collaborative app"
AI: "Tell me more! What's your expected user count? Do you need 
     offline support? What's your team's expertise?"
     
     → Analyzes deeply
     → Explains reasoning  
     → Recommends tailored stack

✨ Features

🚀 Quick Start

Installation

# Global installation
npm install -g gigaspec

# Or use without installing
npx gigaspec init --name "MyApp"

Create Your First Project

# Interactive AI-guided wizard
gigaspec init

# Or specify your stack directly
gigaspec init --name "MyApp" --stack "Node.js/Next.js"

# Non-interactive with defaults
gigaspec init --name "MyApp" --yes

What Gets Created

my-project/
├── AGENT.md           ← AI coding standards & constraints
├── ARCHITECTURE.md    ← System design & decisions  
├── PLAN.md            ← Development roadmap
├── STATE.md           ← Project status (living document)
├── WORKFLOW.md        ← AI development protocols
├── SETUP.md           ← Local development guide
├── DEPLOYMENT.md      ← Production deployment
├── ENVIRONMENT.md     ← Secrets & configuration
├── CLAUDE.md          ← Claude Code integration guide
├── .cursorrules       ← Cursor IDE rules
├── .github/workflows/ ← CI/CD automation
├── .hooks/            ← Git hooks
├── scripts/           ← Utility scripts
└── prompts/           ← AI prompt templates

🤖 For AI Assistants

Gigaspec works both as a CLI tool (for humans) and an MCP server (for AI IDEs). Use whichever fits your workflow:

• CLI: Run gigaspec commands directly in terminal
• MCP: AI assistants use tools via MCP integration

All CLI commands support --json for structured output:

# Start AI workflow
gigaspec init --json

# Get current task to implement  
gigaspec continue --json

# Verify code compliance
gigaspec verify --json

MCP Integration

Gigaspec includes an MCP (Model Context Protocol) server for AI IDEs like Kimi, Claude Desktop, and Cline.

Configuration

Add to your AI IDE's MCP settings:

Option 1: Global Install (Recommended)

npm install -g gigaspec

Then configure your AI IDE:

Kimi Desktop (~/.kimi/mcp.json):

{
  "mcpServers": {
    "gigaspec": {
      "command": "gigaspec-mcp"
    }
  }
}

Claude Desktop (%APPDATA%/Claude/claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "gigaspec": {
      "command": "gigaspec-mcp"
    }
  }
}

Option 2: Using npx (No Install)

{
  "mcpServers": {
    "gigaspec": {
      "command": "npx",
      "args": ["-y", "gigaspec-mcp"]
    }
  }
}

Option 3: Local Development (Project Path)

When developing gigaspec itself or using a local copy:

{
  "mcpServers": {
    "gigaspec": {
      "command": "node",
      "args": [
        "./bin/mcp-server.js"
      ],
      "env": {}
    }
  }
}

Available Tools

Once configured, your AI assistant can use:

• gigaspec-init — Initialize project
• gigaspec-analyze — Create analysis prompt
• gigaspec-generate — Generate specification files
• gigaspec-status — Get project status
• gigaspec-wizard — Interactive project setup

📚 Commands

Core Commands

Options

# JSON output for AI consumption
gigaspec init --name "MyApp" --json

# Specify stack
gigaspec init --name "MyApp" --stack "Elixir/Phoenix"

# With all options
gigaspec init \
  --name "MyApp" \
  --stack "Node.js/Express" \
  --database "PostgreSQL" \
  --deploy "Railway" \
  --yes

🎓 How It Works

1. Describe Your Project

"I want to build a math learning app for kids"

2. AI Analyzes Deeply

The AI receives a structured prompt and:

• ✅ Analyzes core requirements
• ✅ Identifies user types and scale
• ✅ Considers technical challenges
• ✅ Asks clarifying questions

3. Intelligent Q&A

AI: "I have some questions to better understand your needs:

1. What age range are you targeting?
2. Do you need offline capability?  
3. Will this be free or subscription?
4. Any compliance requirements (COPPA)?"

4. Tailored Recommendations

AI: "Based on your answers, I recommend:

Stack: Next.js 14 with PWA capabilities
Why: PWA gives offline capability, Next.js excels at interactive content

Database: PostgreSQL via Supabase  
Why: Built-in realtime for progress sync, COPPA compliance features

Services: Clerk (COPPA-compliant auth), Stripe (payments)"

5. Generate & Build

gigaspec generate --stack "Next.js 14" --name "MathLearn"

🆚 Comparison

📁 Project Structure

When you run gigaspec init, you get a complete specification framework:

📦 my-project/
├── 📄 AGENT.md              AI coding standards (the "rulebook")
├── 📄 ARCHITECTURE.md       System design & tech decisions
├── 📄 PLAN.md               Development phases & milestones
├── 📄 STATE.md              Current status & next tasks
├── 📄 WORKFLOW.md           AI collaboration protocols
├── 📄 SETUP.md              Environment setup guide
├── 📄 DEPLOYMENT.md         Production deployment
├── 📄 ENVIRONMENT.md        Secrets & configuration
├── 📄 CLAUDE.md             Claude Code integration
├── ⚙️  .cursorrules          Cursor IDE rules
├── 🗂️  .github/workflows/    CI/CD automation
├── 🗂️  .hooks/               Git hooks
├── 🗂️  scripts/              Utility scripts
└── 🗂️  prompts/              AI prompt templates

🧪 Example Walkthrough

See EXAMPLE.md for a complete walkthrough of building a math learning app, including:

• Initial project description
• AI analysis and questions
• Stack recommendation with reasoning
• Full specification generation
• Development workflow

🔧 Requirements

• Node.js >= 16.0.0
• npm or yarn

📄 License

Apache License 2.0 — see LICENSE file for details.