Spec-driven development with "reasoning" layer.

A spec-driven context engineering framework that also capture reasoning for AI coding agents like Claude Code, Cursor, Copilot, and more. Plan before coding, capture what actually happened after coding, and preserve the why behind each change for future chats, debugging, and reviews.

Our Vision

Code tells you what was built. Tests tell you how it works. Only reasoning tells you why it exists.

• Plan before coding — surface decisions upfront
• Capture after coding — record what actually happened
• Track the delta — see what changed and what surprised you

In an era where AI writes most of the code, the human contribution isn't the syntax — it's the judgment. WhySpec preserves that judgment so it survives beyond the chat session that created it.

See it in action

You: /whyspec-plan add-jwt-auth
AI:  Created whyspec/changes/add-jwt-auth/
     ✓ intent.md  — why this change exists
     ✓ design.md  — approach + 3 decisions to make
     ✓ tasks.md   — verification-first checklist
     Decision Bridge: 3 open questions to resolve.

You: /whyspec-execute add-jwt-auth
AI:  Implementing with full context...
     ✓ 1. Add token verification middleware
     ✓ 2. Create login endpoint with bcrypt
     ✓ 3. Wire up protected routes
     All tasks complete! 3 decisions resolved.

You: /whyspec-capture add-jwt-auth
AI:  Decision Bridge resolved:
     ✓ Token storage: httpOnly cookie (XSS > CSRF)
     ✓ Hashing: bcrypt (Node.js ecosystem)
     ⚠ SURPRISE: Added 2FA (security review)
     Saved to ctx_a1b2c3d4.md

Install

npm install -g @gitwhy-cli/whyspec

Quick Start

cd your-project
whyspec init                        # Set up WhySpec
# Then use /whyspec-plan in Claude Code and Cursor, or $whyspec-plan in Codex

That's it. WhySpec teaches your AI agent to plan before coding and capture reasoning after.

Docs

→ Getting Started: first steps → Commands: slash commands & skills → CLI: terminal reference → Concepts: Decision Bridge, context IDs, philosophy → Supported Agents: agent integrations & install paths → Workflows: common patterns → GitWhy Integration: SaaS platform & team sharing

Cross-Agent Support

| AI Agent | Integration | How | |---------|------------|-----| | Claude Code | Project skills | skills/whyspec-*/SKILL.md | | Cursor | Slash commands | .cursor/commands/whyspec-*.md | | Codex CLI | Native skills + project instructions | ~/.codex/skills/whyspec-* + AGENTS.md | | GitHub Copilot | Project instructions | AGENTS.md | | Windsurf | Project instructions | AGENTS.md | | Cline | Project instructions | AGENTS.md | | Amazon Q | Project instructions | AGENTS.md | | RooCode | Project instructions | AGENTS.md |

Run whyspec init and select your tools. WhySpec generates the right config for each.

Works With

WhySpec is complementary to existing AI coding tools. It fills the reasoning gap they leave open.

| Tool | What it owns | WhySpec adds | |------|-------------|--------------| | OpenSpec | Planning before code | Reasoning capture after code | | GSD | Deep planning + execution | Decision Bridge: plan vs outcome tracking | | gstack | Sprint lifecycle (review, QA, ship) | Persistent WHY behind each change |

WhySpec works alongside all three. Use them for planning and execution. Use WhySpec for reasoning.

Contributing

See CONTRIBUTING.md for development setup, testing, and PR guidelines.

License

MIT -- free forever. Go capture some reasoning.