spec-builder
SKILL.md
Spec Builder
Transforms vague ideas into detailed specifications for autonomous coding.
Takes users through guided discovery to create complete, actionable specs ready for autonomous start:.
Quick Start
Start Spec Building
I want to build a todo app
or
build spec: project management tool
or
help me define what I want to build
How It Works
┌─────────────────────────────────────────────────────────────────┐
│ SPEC BUILDER FLOW │
├─────────────────────────────────────────────────────────────────┤
│ │
│ USER INPUT │
│ "I want to build something like Notion" │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ PHASE 1: DISCOVERY │ │
│ │ │ │
│ │ Q1: What type of application? │ │
│ │ → Workspace/productivity app │ │
│ │ │ │
│ │ Q2: Who are the target users? │ │
│ │ → Teams and individuals │ │
│ │ │ │
│ │ Q3: What are the 3-5 core features? │ │
│ │ → Pages, Editor, Collaboration, Search │ │
│ │ │ │
│ │ Q4: Any technology preferences? │ │
│ │ → Modern stack, real-time │ │
│ │ │ │
│ │ Q5: Any constraints or requirements? │ │
│ │ → Must be self-hostable │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ PHASE 2: ELABORATION │ │
│ │ │ │
│ │ For each core feature, expand: │ │
│ │ • Sub-features │ │
│ │ • User stories │ │
│ │ • Edge cases │ │
│ │ • Integrations │ │
│ │ │ │
│ │ Pages: │ │
│ │ ├─ Hierarchical structure │ │
│ │ ├─ Page templates │ │
│ │ ├─ Page sharing │ │
│ │ └─ Page history/versioning │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ PHASE 3: TECHNOLOGY RECOMMENDATION │ │
│ │ │ │
│ │ Based on requirements, suggest: │ │
│ │ • Frontend: Next.js + TypeScript │ │
│ │ • Editor: Tiptap or Slate │ │
│ │ • Backend: Node.js + Prisma │ │
│ │ • Database: PostgreSQL │ │
│ │ • Real-time: Socket.io or Liveblocks │ │
│ │ • Hosting: Vercel + Railway │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ PHASE 4: SPECIFICATION OUTPUT │ │
│ │ │ │
│ │ Generate complete spec ready for autonomous-master: │ │
│ │ │ │
│ │ ┌────────────────────────────────────────────────────┐ │ │
│ │ │ autonomous start: Build a collaborative workspace │ │ │
│ │ │ application similar to Notion with: │ │ │
│ │ │ │ │ │
│ │ │ CORE FEATURES: │ │ │
│ │ │ - Hierarchical pages with drag-and-drop │ │ │
│ │ │ - Rich text editor with block-based content │ │ │
│ │ │ - Real-time collaboration (multiple cursors) │ │ │
│ │ │ - Full-text search across all content │ │ │
│ │ │ - Sharing with granular permissions │ │ │
│ │ │ ... │ │ │
│ │ │ │ │ │
│ │ │ TECHNOLOGY STACK: │ │ │
│ │ │ - Next.js 14 with App Router │ │ │
│ │ │ - TypeScript │ │ │
│ │ │ - Tiptap for rich text editor │ │ │
│ │ │ - Prisma + PostgreSQL │ │ │
│ │ │ - Socket.io for real-time │ │ │
│ │ └────────────────────────────────────────────────────┘ │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ Ready for autonomous-master! │
│ │
└─────────────────────────────────────────────────────────────────┘
Discovery Questions
Core Questions (Always Asked)
| # | Question | Purpose |
|---|---|---|
| 1 | What type of application? | Categorize (web, mobile, API, etc.) |
| 2 | Who are the users? | Define audience and scale |
| 3 | What are 3-5 core features? | Identify must-haves |
| 4 | Technology preferences? | Constrain or open stack choices |
| 5 | Any constraints? | Budget, timeline, integrations |
Follow-up Questions (Based on Answers)
| Trigger | Follow-up |
|---|---|
| "authentication" mentioned | OAuth providers? SSO? MFA? |
| "payments" mentioned | Stripe? Subscriptions? One-time? |
| "real-time" mentioned | Chat? Notifications? Collaboration? |
| "mobile" mentioned | Native? PWA? React Native? |
| "API" mentioned | REST? GraphQL? Who consumes it? |
Project Templates
Quick-start templates for common project types:
SaaS Application
Template: saas
Includes:
- User auth with multi-tenancy
- Subscription billing
- Admin dashboard
- User settings
- API access
E-Commerce
Template: ecommerce
Includes:
- Product catalog
- Shopping cart
- Checkout flow
- Order management
- Inventory tracking
Social Platform
Template: social
Includes:
- User profiles
- Posts/content feed
- Likes/comments
- Follow system
- Notifications
Internal Tool
Template: internal
Includes:
- SSO authentication
- Role-based access
- Data tables/CRUD
- Reports/dashboards
- Audit logging
Usage Examples
Example 1: Vague Idea
User: I want to build a todo app
Spec Builder: I'll help you define your todo app. Let me ask a few questions:
1. Who will use this? (personal, team, enterprise)
2. What makes it different from existing todo apps?
3. Any specific features you need? (recurring tasks, collaboration, etc.)
4. Web only or also mobile?
[After Q&A]
Generated Spec:
autonomous start: Build a collaborative task management app with:
- User authentication (email + Google OAuth)
- Personal and shared task lists
- Tasks with due dates, priorities, and labels
- Subtasks and checklists
- Recurring task support
- Real-time collaboration
- Mobile-responsive design
- Push notifications for due dates
Use Next.js, TypeScript, Prisma, PostgreSQL, and Tailwind CSS.
Example 2: Clear Vision
User: build spec: Uber for dog walking
Spec Builder: Great concept! Let me clarify the specifics:
1. Two-sided marketplace (walkers + dog owners)?
2. Real-time tracking during walks?
3. Payment processing?
4. Scheduling (on-demand, recurring)?
5. Geographic scope?
[After Q&A]
Generated Spec:
autonomous start: Build an on-demand dog walking marketplace with:
DOG OWNER FEATURES:
- Registration with dog profiles
- Search nearby walkers with ratings
- Book on-demand or schedule recurring
- Real-time GPS tracking during walks
- In-app messaging with walkers
- Payment with saved cards
- Walk history and reports
WALKER FEATURES:
- Walker onboarding with background check
- Set availability and service area
- Accept/decline walk requests
- GPS tracking and walk logging
- Earnings dashboard
- Direct deposit payouts
ADMIN FEATURES:
- User management
- Dispute resolution
- Analytics dashboard
Use React Native (iOS + Android), Node.js, PostgreSQL,
Stripe Connect, Google Maps API, and Firebase for real-time.
Integration with Autonomous-Master
After generating a spec:
┌─────────────────┐
│ SPEC-BUILDER │
│ │
│ [Generated │
│ Spec] │
└────────┬────────┘
│
│ Copy or auto-invoke
▼
┌─────────────────┐
│AUTONOMOUS-MASTER│
│ │
│ autonomous │
│ start: [spec] │
└─────────────────┘
Scripts
scripts/spec_builder.py- Core discovery enginescripts/question_engine.py- Dynamic question generationscripts/template_expander.py- Template expansionscripts/tech_recommender.py- Technology recommendationsscripts/spec_formatter.py- Format final specification
References
references/QUESTION-BANK.md- All discovery questionsreferences/TEMPLATES.md- Project templatesreferences/TECH-STACKS.md- Technology recommendations
Templates
templates/saas.md- SaaS application templatetemplates/ecommerce.md- E-commerce templatetemplates/social.md- Social platform templatetemplates/internal.md- Internal tool template