Ship Spec

AI-powered codebase analysis and production readiness evaluation

Turn your codebase into actionable production reports with one command.

Quick Start •
Features •
Installation •
Usage •
Configuration •
Contributing •
Security

> [!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

``bash

`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
$3
- 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).
$3

`bash npm install -g shipspec-cli`

`$3`

`bash cd your-project ship-spec init`

The initcommand 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 a new feature:`bash 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//

Analyze production readiness:`bash 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`

`$3`

`bash npm install -g shipspec-cli`

`$3`

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

`$3`

`bash 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
$3
Initialize Ship Spec in the current directory and configure global API keys.

`bash

`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


$3
Manage your chat model selection.

`bash

`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


$3
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.

`bash

`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 
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//: -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 | 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:

`bash $ 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/`

`$3`

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

`bash

`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 | Filter to specific categories (csv) | all| |--no-stream | Disable real-time progress output | false |

`$3`

Display the resolved configuration.

`bash ship-spec config`

`$3`

`bash ship-spec --help # Show help ship-spec --version # Show version ship-spec -v, --verbose # Enable verbose logging ship-spec -c, --config # Use custom config file`

`$3`

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:

`$3`

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

`$3`

`bash 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

---

Made with ❤️ by the Ship Spec community

Ship Spec

AI-powered codebase analysis and production readiness evaluation

Turn your codebase into actionable production reports with one command.

Quick Start •
Features •
Installation •
Usage •
Configuration •
Contributing •
Security

---

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:

``bash

`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
$3
- 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).
$3

`bash npm install -g shipspec-cli`

`$3`

`bash cd your-project ship-spec init`

`$3`

Plan a new feature:`bash 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//

Analyze production readiness:`bash 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`

`$3`

`bash npm install -g shipspec-cli`

`$3`

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

`$3`

`bash 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
$3
Initialize Ship Spec in the current directory and configure global API keys.

`bash

`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


$3
Manage your chat model selection.

`bash

`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


$3
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.

`bash

`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 
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:

Options:

Example Session:

`bash $ 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/`

`$3`

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

`bash

`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

Options:

`$3`

Display the resolved configuration.

`bash ship-spec config`

`$3`

`bash ship-spec --help # Show help ship-spec --version # Show version ship-spec -v, --verbose # Enable verbose logging ship-spec -c, --config # Use custom config file`

`$3`

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

---

`🤝 Contributing`

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

`$3`

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

`$3`

`bash 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:

---

Made with ❤️ by the Ship Spec community