[!WARNING] Under Construction: This CLI tool is currently in active development and is not yet fully functional. Some features may be missing, broken, or change significantly without notice.

Why Ship Spec?

Planning new features and evaluating production readiness are complex tasks that require deep codebase understanding. Ship Spec uses AI to streamline both:

• Spec-Driven Development — Interactively plan features with AI-generated PRDs, tech specs, and implementation tasks
• Production Readiness Analysis — Semantic code analysis, security audits, and compliance evaluation on demand

# Initialize project and set API keys
ship-spec init

# Plan a new feature with guided workflow
ship-spec planning "Add OAuth authentication" --cloud-ok

# Analyze production readiness
ship-spec productionalize "B2B SaaS handling PII, targeting SOC 2" --cloud-ok

Ship Spec handles the heavy lifting—parsing your code into semantic chunks, building a searchable vector index, and orchestrating AI agents to either guide feature planning or evaluate your project against industry standards.

✨ Features

• 📋 Interactive Planning Workflow — Spec-driven development with AI-guided clarification, PRD generation, tech specs, and task breakdowns
• 🔍 Semantic Code Understanding — Uses Tree-sitter for AST-based parsing across TypeScript, JavaScript, Python, Go, and Rust
• ☁️ Unified Model Gateway — Access Gemini, Claude, and GPT models through a single OpenRouter endpoint
• 🧠 Agentic Workflow — LangGraph.js orchestrates workflows with human-in-the-loop review cycles
• 🛡️ Production Readiness Analysis — Hybrid planner combines deterministic signals with dynamic research and SAST scans
• 🗄️ Local-First Vector Store — Embedded LanceDB for fast similarity search without external dependencies
• 🏠 Local Inference Support — Maintains local-first philosophy with optional Ollama integration
• 🔐 Secure Credential Management — Stores API keys in your OS keychain (macOS Keychain, Windows Credential Vault, Linux Secret Service)
• ⚡ High Performance — Concurrent file processing with configurable parallelism and batching

🚀 Quick Start

Prerequisites

• Node.js 20+ required
• OpenRouter API Key: Required for cloud models. Get one at openrouter.ai/keys.
• Tavily API Key: Required for web research. Get one at app.tavily.com (free tier available).

1. Install

npm install -g shipspec-cli

2. Initialize and configure API keys

cd your-project
ship-spec init

The init command will:

• Prompt you for your OpenRouter and Tavily API keys
• Store them securely in your OS keychain (one-time setup per machine)
• Create a .ship-spec/ directory in your project for tracking state and outputs

3. Plan features or analyze production readiness

Plan a new feature:

ship-spec planning "Add user authentication" --cloud-ok

The tool will:

• Guide you through clarifying questions
• Generate PRD and tech spec with your approval
• Create actionable implementation tasks
• Save all artifacts to .ship-spec/planning/<track-id>/

Analyze production readiness:

ship-spec productionalize --cloud-ok

The tool will:

• Automatically index your codebase on the first run
• Run parallel analysis agents
• Save the results to .ship-spec/outputs/

📦 Installation

Global Installation (Recommended)

npm install -g shipspec-cli

Local Installation

npm install shipspec-cli
npx ship-spec --help

From Source

git clone https://github.com/your-org/shipspec-cli.git
cd shipspec-cli
# Recommendation: use npm ci for deterministic installs
npm ci
npm run build
npm link

📖 Usage

ship-spec init

Initialize Ship Spec in the current directory and configure global API keys.

# Interactive setup
ship-spec init

# Non-interactive setup (for CI/CD)
OPENROUTER_API_KEY=sk-or-... TAVILY_API_KEY=tvly-... ship-spec init --non-interactive

ship-spec model <subcommand>

Manage your chat model selection.

# List available model aliases
ship-spec model list

# Show currently configured model
ship-spec model current

# Set model (gemini-flash, claude-sonnet, or gpt-pro)
ship-spec model set gemini-flash

ship-spec planning [idea]

Guide you through spec-driven development to plan new features or bootstrap new projects. This interactive command uses AI to help clarify requirements, generate a Product Requirements Document (PRD), create a Technical Specification, and produce actionable implementation tasks.

# Interactive mode - you'll be prompted for your idea
ship-spec planning

# Provide idea upfront
ship-spec planning "Build a user authentication system with email/password"

# Resume an existing planning session
ship-spec planning --track <track-id>

# Force re-indexing of codebase for better context
ship-spec planning --reindex

Workflow:

The planning command follows an interactive, iterative workflow:

1. Clarification — AI asks follow-up questions to understand your requirements
2. PRD Generation — Creates a Product Requirements Document based on clarified needs
3. PRD Review — You review and approve or provide feedback for revision
4. Tech Spec Generation — Generates a technical specification from the approved PRD
5. Tech Spec Review — You review and approve or provide feedback for revision
6. Task Generation — Produces implementation task prompts ready for coding agents

Outputs:

All planning artifacts are saved to .ship-spec/planning/<track-id>/:

• prd.md — Product Requirements Document
• tech-spec.md — Technical Specification
• tasks.md — Implementation task prompts
• context.md — Project signals and code context used
• track.json — Session metadata for resumption

Options:

| Option | Description | Default | |--------|-------------|---------| | --track <id> | Resume an existing planning session | Creates new | | --reindex | Force full re-index of the codebase | false | | --no-save | Don't save artifacts to disk | false | | --cloud-ok | Acknowledge sending data to cloud LLMs | Required | | --local-only | Use only local models (Ollama) | false |

Example Session:

$ ship-spec planning --cloud-ok
? Describe what you want to build: Add rate limiting to our API

📝 Clarifying questions:
1. What type of rate limiting do you want? (e.g., per-user, per-IP, per-endpoint)
> Per-user, based on API key

2. What are the rate limits? (e.g., requests per minute/hour)
> 1000 requests per hour, 100 per minute

✓ PRD generated. Awaiting review...
PRD written to: .ship-spec/planning/abc123/prd.md
? Review the PRD and reply 'approve' or provide feedback: approve

✓ Tech spec generated. Awaiting review...
Tech Spec written to: .ship-spec/planning/abc123/tech-spec.md
? Review and reply 'approve' or provide feedback: approve

✓ Generated 5 implementation tasks.
All artifacts saved to: .ship-spec/planning/abc123/

ship-spec productionalize [context]

Analyze your codebase for production readiness. This command automatically indexes your codebase, then combines code analysis, web research (SOC 2, OWASP), and SAST scans.

# Basic usage
ship-spec productionalize

# With specific context
ship-spec productionalize "B2B SaaS handling PII, targeting SOC 2"

# Force full re-indexing
ship-spec productionalize --reindex

# Enable SAST scans (Semgrep, Gitleaks, Trivy)
ship-spec productionalize --enable-scans

Outputs: Analysis reports and task prompts are automatically saved to:

• .ship-spec/outputs/report-YYYYMMDD-HHMMSS.md
• .ship-spec/outputs/task-prompts-YYYYMMDD-HHMMSS.md
• Latest results are always available at .ship-spec/latest-report.md and .ship-spec/latest-task-prompts.md.

Options:

| Option | Description | Default | |--------|-------------|---------| | --reindex | Force full re-index of the codebase | false | | --enable-scans | Run SAST scanners (requires binaries) | false | | --categories <list> | Filter to specific categories (csv) | all | | --no-stream | Disable real-time progress output | false |

ship-spec config

Display the resolved configuration.

ship-spec config

Global Options

ship-spec --help        # Show help
ship-spec --version     # Show version
ship-spec -v, --verbose # Enable verbose logging
ship-spec -c, --config <path>  # Use custom config file

Configuration Precedence

Ship Spec resolves configuration in the following order (highest priority first):

1. CLI Flags: Explicitly passed arguments when running a command.
2. Environment Variables: OPENROUTER_API_KEY, TAVILY_API_KEY, OLLAMA_BASE_URL, etc.
3. Configuration File: shipspec.json (or .shipspec.json) in the project root.
4. Default Values: Built-in defaults as defined in the schema.

🤝 Contributing

We welcome contributions! Here's how to get started:

Development Setup

git clone https://github.com/your-org/shipspec-cli.git
cd shipspec-cli
npm ci
npm run build

Commands

npm run dev          # Watch mode
npm run typecheck    # Type checking
npm run lint         # Linting
npm test             # Run tests
npm run test:watch   # Tests in watch mode
npm run test:coverage # Coverage report

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Built with these amazing open-source projects:

• LangChain.js — AI application framework
• LangGraph.js — Agentic workflow orchestration
• LanceDB — Embedded vector database
• Tree-sitter — Incremental parsing system
• Commander.js — CLI framework
• keytar — OS keychain integration