Specification-driven development for AI coding agents. An experiment in how documentation, quickstarts, and best practices should be delivered in a world where AI agents write code.
SpecCraft creates comprehensive feature specifications through natural conversations with Claude Code, then generates opinionated Next.js + KeystoneJS applications with embedded architectural guidance.
Current State: Developers (and AI agents) struggle with:
- Single-prompt complexity - Attempting to build features with vague requirements
- Documentation fragmentation - Scattered across multiple sites, often outdated
- Pattern inconsistency - Every project reinvents the wheel
- Lost knowledge - Critical decisions buried in chat histories or Slack threads
- Template decay - Static boilerplates become outdated quickly
The Insight: In a world of AI coding agents, the bottleneck isn't writing code—it's communicating intent and ensuring consistency.
SpecCraft introduces specification-as-source-of-truth combined with opinionated, self-documenting architectures:
- 📋 Interactive Specification Creation - AI-guided questionnaires that extract comprehensive requirements
- 🏗️ Opinionated Architecture - Battle-tested patterns from production apps (not theoretical examples)
- 📚 Live Documentation - Real-time docs from official sources, not static snapshots
- 🤖 AI-Native Design - Every output optimized for AI agent consumption
- 💡 Self-Documenting Projects - Generated
CLAUDE.mdfiles embed architectural patterns directly in the codebase
# One-line installation
npx @opensaas/speccraft install
# Start creating specifications
/speccraft:new "Shopping Cart" "Add items to cart and checkout"Instead of single prompts like "build a blog", SpecCraft asks:
- Who are your users? What are their goals?
- What workflows need to be supported?
- What are the edge cases and error scenarios?
- What security requirements exist?
- How does this integrate with existing systems?
Output: A comprehensive markdown specification that serves as:
- Source of truth for features
- Version-controlled documentation
- Input for AI code generation
- Reference for human developers
SpecCraft doesn't generate generic templates—it provides battle-tested architecture from real production apps:
Reference Architecture: on-the-hill-drama-club
- Next.js 15 with App Router
- KeystoneJS 6 embedded via
getContext()(NOT as separate server) - NextAuth 5 for authentication
- Neon PostgreSQL with serverless adapter
- Server Actions for mutations (no custom GraphQL resolvers)
- Type-safe GraphQL with gql.tada
Key Innovation: Generated projects include CLAUDE.md—a comprehensive guide that embeds:
- Critical architectural patterns
- Working code examples
- Common workflows
- Troubleshooting guides
- Links to relevant documentation
This means AI agents (and developers) always have context-aware guidance when working in the project.
Automated deployment to Vercel + Neon with:
- Environment variable management
- Database migration execution
- Health checks and monitoring
| Command | Purpose | Example |
|---|---|---|
/speccraft:new |
Create specification interactively | /speccraft:new "User Auth" "Login with OAuth" |
/speccraft:build |
Generate project with architecture | /speccraft:build spec.md |
/speccraft:validate |
AI quality assessment | /speccraft:validate spec.md |
/speccraft:help |
Live Keystone.js documentation | /speccraft:help relationship |
User: "Build a user authentication system"
AI: "Here's some generic code..."
→ Missing edge cases
→ Inconsistent patterns
→ No architectural guidance
→ Patterns become outdated
User: /speccraft:new "User Authentication" "Login with email and OAuth"
AI: [Asks 21 intelligent questions about users, security, workflows, etc.]
→ Comprehensive 5-page specification
→ Battle-tested Next.js + Keystone architecture
→ CLAUDE.md with embedded patterns and examples
→ Live documentation from official sources
→ Type-safe, production-ready code guidance
After collecting context, SpecCraft can intelligently suggest answers:
You: "This is a user profile dashboard"
Q: Does this feature require authentication?
💡 Based on "user profile dashboard", I'm 95% confident this needs
authentication because it's personal user data.
Accept? [Yes / No]
Reduces 21 questions to ~12-15 for most features while maintaining quality.
Instead of static templates, SpecCraft fetches real-time documentation:
/speccraft:help relationship # Latest Keystone.js relationship patterns
/speccraft:help auth # Current authentication examples
/speccraft:help access-control # Security best practicesSources:
- Official Keystone.js docs from GitHub
- Real example projects
- Current best practices
Every generated project includes CLAUDE.md:
# Your Feature - Development Guide
## Critical Patterns
❌ NEVER run Keystone as separate server
✅ ALWAYS use getContext()
✅ ALWAYS use Server Actions (not custom resolvers)
## Common Tasks
### Adding a New Schema
1. Create src/keystone/lists/YourList.ts
2. [Complete example with working code]
### Creating a Server Action
1. Create src/app/actions/yourAction.ts
2. [Complete example with type safety]
## Troubleshooting
### "getContext is not a function"
- Check src/keystone/context/index.ts exists
- [Specific solution steps]This means:
- ✅ AI agents always have architectural context
- ✅ New developers understand patterns immediately
- ✅ Consistency maintained across codebase
- ✅ Knowledge preserved, not buried in chat logs
Not theoretical—actual patterns from production SaaS applications:
Key Decisions:
- Embed Keystone via
getContext()(not separate server) - Use Next.js Server Actions for mutations
- Type-safe GraphQL with gql.tada
- Neon serverless PostgreSQL for Vercel
- NextAuth 5 synced with Keystone users
Why This Matters:
- Patterns are proven at scale
- Best practices are enforced
- Security is built-in
- Performance is optimized
SpecCraft is an experiment in AI-native development tooling:
Hypothesis: In a world of AI coding agents, the most valuable assets are:
- Clear specifications (not vague prompts)
- Opinionated architectures (not infinite flexibility)
- Embedded knowledge (not external docs)
- Live documentation (not static snapshots)
- Self-documenting code (not separate wikis)
Questions We're Exploring:
- Can AI-guided questionnaires produce better specifications than human-written ones?
- Should documentation live IN the codebase rather than external sites?
- Are opinionated architectures better than flexible templates for AI agents?
- Can inference reduce cognitive load while maintaining quality?
- How should best practices be communicated to AI agents?
- 📝 Vague specifications → Missing edge cases
- 🔀 Inconsistent patterns → Technical debt
- 📚 Scattered docs → Outdated information
- 🤔 Trial-and-error → Wasted time
- 📋 Comprehensive specs → Complete requirements
- 🏗️ Battle-tested patterns → Production-ready code
- 📖 Embedded guidance → Always current
- 🚀 Clear path → Immediate productivity
speccraft/
├── .claude/commands/speccraft/ # 4 slash commands for Claude Code
├── src/
│ ├── mcp-server/ # MCP server (session management)
│ ├── lib/
│ │ ├── specification-engine/ # AI questionnaire system
│ │ └── guidance/ # Architecture guidance + CLAUDE.md generation
│ └── keystone/ # Keystone schema and context
└── generated-projects/
└── your-project/
├── CLAUDE.md # Embedded architectural guide
├── SPECIFICATION.md # Feature specification
└── src/ # Opinionated Next.js + Keystone app
- MCP Server: Model Context Protocol for Claude Code integration
- AI Questionnaires: Intelligent follow-up questions based on responses
- Live Documentation: Real-time fetching from GitHub
- Smart Caching: Efficient documentation retrieval
- Answer Inference: 90%+ confidence threshold for suggestions
- 21 comprehensive questions across 6 categories
- Visual progress bars (████████░░░░ 8/21)
- Smart answer inference (reduces to ~12-15 questions)
- Category preview upfront
- Production-tested patterns from real apps
- Complete Next.js + Keystone setup
- NextAuth integration (when auth detected)
- Neon serverless PostgreSQL
- Type-safe GraphQL with gql.tada
- Real-time Keystone.js docs from GitHub
- Official examples and patterns
- Smart topic mapping (handles plurals, synonyms)
- Efficient caching with error handling
CLAUDE.mdembedded in every project- Critical patterns with examples
- Common workflows and troubleshooting
- Architecture decisions explained
# Clone and setup
git clone https://github.com/opensaas/speccraft.git
cd speccraft
pnpm install
# Build MCP server
pnpm run build
# Test locally
npx . install
# Remove from Claude Code
npx @opensaas/speccraft uninstall- Automatically suggests answers with 90%+ confidence
- Reduces questionnaire from 21 to ~12-15 questions
- Transparent reasoning shown to user
- User maintains full control
- Complete Next.js + Keystone + NextAuth setup
- Production patterns from on-the-hill-drama-club
- Critical DO/DON'T patterns embedded
- Smart auth detection from specifications
- Comprehensive architectural guide in every project
- Working code examples for common tasks
- Troubleshooting guides specific to the stack
- Self-documenting, always accessible
- Progress bars throughout questionnaire
- Category overview before starting
- Real-time completion tracking
This is an open experiment. We're exploring:
- How should AI agents receive documentation?
- What makes a specification "good enough" for AI code generation?
- How opinionated should architectures be?
- What patterns work best for AI + human collaboration?
Contributions, experiments, and feedback welcome!
MIT
SpecCraft: Teaching AI agents to build better by teaching them to ask better questions first.
An experiment by OpenSaas in specification-driven AI development.