██╗ ██╗██╗ ██╗██╗ ██╗███████╗██████╗ ███████╗ ██████╗ ██║ ██║██║ ██║╚██╗ ██╔╝██╔════╝██╔══██╗██╔════╝██╔════╝ ██║ █╗ ██║███████║ ╚████╔╝ ███████╗██████╔╝█████╗ ██║ ██║███╗██║██╔══██║ ╚██╔╝ ╚════██║██╔═══╝ ██╔══╝ ██║ ╚███╔███╔╝██║ ██║ ██║ ███████║██║ ███████╗╚██████╗ ╚══╝╚══╝ ╚═╝ ╚═╝ ╚═╝ ╚══════╝╚═╝ ╚══════╝ ╚═════╝
Built by GitWhy
Spec-driven development that captures reasoning.
A spec-driven context engineering framework for AI coding agents.
npm install -g @gitwhy-cli/whyspec
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.
Claude Code, Cursor, Copilot, Codex, Windsurf, Cline, and 8+ more
Claude Code, Cursor, GitHub Copilot, Codex CLI, Windsurf, Cline, Amazon Q, RooCode, Aider, Continue, Devin, JetBrains AI, Gemini Code Assist, Sourcegraph Cody
+ any agent that reads AGENTS.md or runs CLI commands
Track how reasoning evolves from intent to outcome. The plan predicts decisions. The capture records them. The delta shows what changed and what surprised you.
## Decisions to Make - [ ] Token storage: cookie vs localStorage? - [ ] Hashing: bcrypt vs argon2? - [ ] Sessions: JWT vs server-side?
<decisions> - [x] Token storage: httpOnly cookie XSS protection outweighs CSRF - [x] Hashing: bcrypt Better library support - [x] JWT (stateless) No session store needed SURPRISE: Added 2FA (not in plan) Security review required it </decisions>
The reasoning lifecycle. Declare intent before coding. Implement with full context. Record decisions, surprises, and trade-offs after.
Created .gitwhy/changes/add-jwt-auth/
intent.md goal, constraints, assumptions
design.md approach, decisions to make
tasks.md verification-first checklist
Read intent.md + design.md Mapped 3 decisions to outcomes Detected 1 surprise decision Linked 4 commits, 6 files changed Wrote ctx_a1b2c3d4.md
Your reasoning lives in .gitwhy/ alongside your code. Visible, grep-able, version-controlled. Survives context resets. Works across sessions. Searchable forever.
.gitwhy/ ├── config.yaml ├── changes/ │ ├── add-jwt-auth/ │ │ ├── intent.md │ │ ├── design.md │ │ ├── tasks.md │ │ └── ctx_a1b2c3d4.md │ └── fix-safari-login/ │ ├── debug.md │ └── ctx_e5f6g7h8.md └── archive/
<context> <title>JWT auth with httpOnly cookies</title> <story> Phase 1: Created middleware... Phase 2: Added token signing with RS256 for key rotation... </story> <reasoning> <decisions> - RS256 over HS256 - 24h expiry </decisions> <rejected> - Session cookies </rejected> </reasoning> </context>
Structured debugging with the scientific method. Form hypotheses. Gather evidence. Prove root cause before fixing. Past contexts surface automatically.
Created .gitwhy/changes/login-fails-safari/ Searching past contexts... Found 2 related: add-jwt-auth "httpOnly cookie, SameSite=Lax" fix-cors-headers "Safari ITP restrictions" Created debug.md Symptoms expected vs actual Hypotheses 3+ falsifiable Investigation evidence trail Root Cause no fix without proof Prevention avoid next time
OpenSpec plans before code. GSD executes with deep context. gstack manages sprint lifecycle. WhySpec captures reasoning AFTER code. The "why" that none of them preserve. It works WITH all three.
The best insights happen DURING implementation. Plans predict decisions. Reality reveals surprises. The delta between plan and outcome is where the learning lives.
A system that maps "Decisions to Make" from your plan to "Decisions Made" after implementation. It shows what changed, what was surprising, and WHY.
If your agent can read files or run CLI commands, yes. Native support for Claude Code, Cursor, Copilot, Codex, Windsurf, Cline, Amazon Q, RooCode, and more.
In .gitwhy/changes/ in your project root. Gitignored by default. Remove from .gitignore to share with your team. Or sync to GitWhy cloud.
No. Documentation describes WHAT exists. WhySpec captures WHY it was built that way. The reasoning, rejected alternatives, trade-offs, and surprises that docs never include.
WhySpec is the free, open-source CLI. GitWhy is the paid SaaS with cloud sync, team search, and dashboards. WhySpec contexts work with GitWhy. Zero conversion.