gigaspec

v5.0.1

Published

5 months ago

AI collaboration framework for software specification

0High
0Medium
0Low

syntarix

specification ai llm claude framework collaboration gigaspec

🚀 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

| Feature | Description | |---------|-------------| | 🚀 Gigaspec v5.0 | Ultimate spec kit with forced AI compliance | | 🔒 Immutable Rules | CLAUDE.md enforces standards that AI cannot override | | ✅ Automated Verification | Every code change validated before completion | | 🛠️ Universal Tool Support | Claude Code, Cursor, Kimi adapters | | 🌍 Model-Agnostic | Works with Claude, GPT, Gemini, Llama | | 🤖 AI-Native Workflow | Designed for AI assistants to drive development | | 💬 Intelligent Q&A | AI asks clarifying questions, not keyword matching | | 📋 Living Documentation | STATE.md tracks progress, AGENT.md guides AI coding | | 🎯 Stack Recommendations | Deep analysis with transparent reasoning | | 🔧 MCP Server | Native integration with AI IDEs | | 📦 Zero Config | Works out of the box with sensible defaults |

🚀 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

# Generate v5.0 Ultimate Spec Kit (RECOMMENDED)
gigaspec generate --name "MyApp" --stack "Node.js/Express" --v5

🚀 Gigaspec v5.0 (Ultimate Spec Kit)

The specification framework that forces AI compliance.

# Generate v5.0 spec kit with immutable rules
gigaspec generate --name "MyApp" --stack "Node.js/Express" --v5

What makes v5.0 different:

CLAUDE.md - Immutable system rules that AI cannot override
Automated Verification - Every code change validated
Multi-Tool Adapters - Claude Code, Cursor, Kimi support
Model-Agnostic - Works with any LLM

Generated v5.0 Structure:

my-project/
├── CLAUDE.md          ← IMMUTABLE system rules (AI cannot override)
├── AGENT.md           ← Project-specific standards
├── STATE.md           ← Living project status
├── ARCHITECTURE.md    ← System design
├── PLAN.md            ← Development roadmap
├── RULES/             ← Modular rule modules
│   ├── security.md
│   └── testing.md
├── .claude/           ← Claude Code adapter
│   ├── CLAUDE.md
│   ├── skills/
│   └── agents/
├── .cursorrules       ← Cursor IDE adapter
├── .cursor/
│   └── agents/
└── .kimi/             ← Kimi CLI adapter
    └── AGENT.md

What Gets Created (v4.x)

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

| Command | Description | |---------|-------------| | gigaspec init | Initialize project with AI collaboration framework | | gigaspec analyze "<description>" | Create analysis prompt for AI | | gigaspec generate | Generate specification files | | gigaspec status | Show current project status | | gigaspec continue | Get next development task | | gigaspec verify | Verify code against AGENT.md |

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

| | Traditional Tools | Gigaspec | |--|-------------------|----------| | Analysis | Keyword matching | Deep AI reasoning | | Questions | None | Intelligent Q&A | | Explanations | "Use X" | "Use X because of Y" | | Tailored | One-size-fits-all | Project-specific | | AI Workflow | Not designed for AI | Built for AI collaboration |

📁 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.

Made with ❤️ for AI-human collaboration

⭐ Star us on GitHub • 🐛 Report Issues