Zero-dependency spec-driven development. Turn brainstorms into agent-executable specs.
BRAINDUMP → PRD → ARCHITECTURE → STORIES → Agent executes
(messy) (what) (how) (do it)
Inspired by BMAD-METHOD, OpenSpec, GitHub Spec Kit, and Agent OS — without the ceremony.
Choose your method:
# In your project root
npx bauspec init
# Custom directory name
npx bauspec init --dir specificationscurl -sSL https://raw.githubusercontent.com/riggd/bauspec/main/install.sh | bash
# Custom directory name
curl -sSL https://raw.githubusercontent.com/riggd/bauspec/main/install.sh | bash -s -- my-specsClick "Use this template" on the GitHub repo and copy the templates/ folder into your project as specs/.
npx degit riggd/bauspec/templates specsgit clone https://github.com/riggd/bauspec.git /tmp/bauspec
cp -r /tmp/bauspec/templates ./specs
rm -rf /tmp/bauspecThe installer:
- Copies 5 markdown templates into
specs/(constitution, braindump, PRD, architecture, stories) - Scaffolds directories —
specs/features/for future features,specs/drafts/for WIP - Auto-detects your tech stack and pre-fills
constitution.md(framework, DB, auth, etc.) - Scans for AI agent configs (CLAUDE.md, .cursorrules, AGENTS.md, etc.) and suggests how to make them Bauspec-aware
- Updates .gitignore to exclude draft braindumps
specs/
├── constitution.md ← Project principles (auto-detected stack pre-filled)
├── 01-braindump.md ← Raw idea capture
├── 02-prd.md ← Product requirements
├── 03-architecture.md ← Technical architecture
├── 04-stories.md ← Agent-executable dev stories
├── features/ ← Per-feature spec folders
└── drafts/ ← WIP braindumps (gitignored)
npx bauspec init
# Fill in constitution.md (5 min)
# Braindump into 01-braindump.md (10-30 min)
# Hand off to your AI agent for the restnpx bauspec add dark-mode
# Creates specs/features/dark-mode/ with braindump, PRD, and stories templates
# Architecture skipped — uses project-levelYou don't need to babysit the agent between phases. Bauspec templates include embedded <!-- AGENT INSTRUCTIONS --> that guide the AI.
To start the process, just tell your agent:
"Read
specs/01-braindump.mdand follow its instructions."
The agent will automatically read the constitution, ask clarifying questions, and prompt you for approval before generating the PRD, Architecture, and Stories in sequence.
The installer detects and provides integration suggestions for:
| Agent | Config File(s) |
|---|---|
| Claude Code | CLAUDE.md, .claude/settings.json, .claude/skills/ |
| Cursor | .cursorrules, .cursor/rules/ |
| Windsurf | .windsurfrules |
| GitHub Copilot | .github/copilot-instructions.md, .github/agents/ |
| Gemini / Antigravity | AGENTS.md, .gemini/, .antigravity/ |
| Agent OS | agent-os/, .agent-os/ |
| GitHub Spec Kit | .specify/ |
| OpenSpec | openspec/ |
| BMAD-METHOD | .bmad/ |
| Roo Code | .roomodes |
| Continue | .continuerules |
When an existing SDD framework is detected (Spec Kit, OpenSpec, BMAD), the installer notes the overlap and suggests whether to coexist or migrate.
| Decision | Why |
|---|---|
| Zero dependencies | Works everywhere. Nothing to update, audit, or break. |
| Markdown only | Every AI coding agent reads it natively. |
| No agent personas | Clear instructions beat role-play wrappers and cost fewer tokens. |
| Single-file phases | One file = one context window load. No cross-reference chasing. |
| Stories embed context | Agent reads one story + constitution. Nothing else needed. |
| Stack auto-detection | Reduces setup friction from 15 min to 5 min. |
| Agent config awareness | Meets developers where they already are. |
- Constitution: Keep under 500 words. It's loaded with every interaction.
- Braindump: Can be messy — it's only human-facing. The PRD replaces it.
- Stories: Each embeds its own context. Agent reads ~1500 words per story, not the entire spec.
- Drafts folder: Gitignored. Keeps messy WIP out of your repo.
See examples/saas-dashboard/ for a complete end-to-end example:
- Braindump → PRD → Architecture → 7 implementation stories
- Shows a Stripe-connected analytics dashboard built with Next.js + Supabase
PRs welcome. Keep it light — the core principle is zero dependencies.
MIT