wespec

OpenSpec-compatible CLI that turns raw ideas into structured spec workflows. Ships with an interactive brainstorm flow and integrates with AI coding assistants like Claude Code and Codex CLI.

Other languages: See README_ZH.md for the Chinese version.

Features

• Brainstorm command (wespec brainstorm) with phased prompts for design ideation
• Native slash commands for Claude Code and Codex CLI
• Project autofill slash command to prefill openspec/project.md from repo docs
• Compatible with openspec/ directory layout
• Bun-based toolchain: oxlint, Vitest 4, tsdown bundling
• Locale autodetect with optional --language override

Installation

npm install -g wespec
# or
bun install && bun run build

Quick Start: AI Coding Assistants

Install Slash Commands

# For Claude Code (global)
wespec install claude-code --global

# For Codex CLI (always global)
wespec install codex

# Project autofill slash command (dynamically reads headings in openspec/project.md)
wespec install claude-code --global --command project
wespec install codex --command project

Usage in Claude Code

/wespec:brainstorm Add user authentication with OAuth
# Autofill openspec/project.md from repo docs (confirms each section interactively)
# You can override languages at call time:
#   /wespec:project lang=zh file-lang=en
/wespec:project

Usage in Codex CLI

/prompts:wespec-brainstorm Add user authentication with OAuth
# Autofill openspec/project.md from repo docs (confirms each section interactively)
# You can override languages at call time:
#   /prompts:wespec-project lang=zh file-lang=en
/prompts:wespec-project

Brainstorm Workflow

The brainstorm command guides you through a structured 3-phase process:

Phase 1: Understanding

• AI asks ONE question at a time to understand your idea
• Gathers: purpose, constraints, success criteria
• Prefers multiple choice questions when possible

Phase 2: Exploration

• AI proposes 2-3 different approaches
• Each approach includes: architecture, trade-offs, complexity
• You choose which approach resonates

Phase 3: Design Presentation

• AI presents design in 200-300 word sections
• Covers: architecture, components, data flow, error handling, testing
• Validates each section: "Does this look right so far?"

Output: OpenSpec Files

When complete, AI creates files in openspec/changes/<change-id>/:

openspec/changes/add-user-auth/
├── proposal.md      # Why and what changes
├── tasks.md         # Implementation checklist
├── design.md        # Technical decisions (optional)
└── specs/
    └── auth/
        └── spec.md  # Requirements and scenarios

CLI Commands

brainstorm

wespec brainstorm "your idea"
wespec brainstorm -i "your idea"          # interactive mode via xling proxy
wespec brainstorm -l en "your idea"       # force English
wespec brainstorm --openspec "your idea"  # use openspec/ directory

install

wespec install claude-code           # project-level (.claude/commands/)
wespec install claude-code --global  # global (~/.claude/commands/)
wespec install codex                 # global (~/.codex/prompts/)
wespec install codex -l en           # specify language

Other Commands

wespec init <change-id>       # initialize change proposal
wespec validate <change-id>   # validate proposal structure
wespec list                   # list all changes
wespec show <change-id>       # show change details
wespec archive <change-id>    # archive completed change
wespec spec                   # list specifications
wespec spec-show <capability> # show spec details

Development

bun install          # install dependencies
bun run lint         # oxlint
bun run test         # Vitest 4
bun run build        # tsdown bundle to dist/

Prompts

• Template: wespec/prompts/brainstorm.md
• Placeholders: {{language}}, {{idea}}

Roadmap

The CLI is designed to grow with more proposal/spec commands over time.