Specs Wizard 🪄

Transform vague product ideas into production-ready specifications optimized for human-AI collaboration

What is Specs Wizard?

Specs Wizard is an intelligent conversation framework that bridges the gap between "I have an idea" and "Here are the detailed, AI-ready tasks for development." It transforms product concepts into comprehensive specifications through guided conversations with AI assistants (like Claude), producing output perfectly structured for modern hybrid human-AI development teams.

The Problem We Solve

In today's development landscape:

• Product teams struggle to translate ideas into actionable, detailed specifications
• Development teams receive incomplete requirements that lead to rework
• AI coding assistants need precise, well-structured tasks to be effective
• Project managers lack a systematic way to ensure nothing is missed

Specs Wizard solves this by providing a conversation-driven framework that:

• Extracts complete requirements through strategic questioning
• Ensures technical feasibility through systematic discovery
• Optimizes for AI collaboration with proper task classification
• Maintains project coherence with Epic Integrity and Wave Management

🚀 Quick Start

Prerequisites

• Node.js (v14 or higher)
• Bash shell (macOS/Linux)
• Claude Code or another AI assistant
• ido4 (optional, for task management)

Installation

# Clone the repository
git clone https://github.com/ido4-dev/ido4-specs-wizard.git
cd ido4-specs-wizard

# Install dependencies
npm install

# Make scripts executable
chmod +x bin/*.sh

Basic Usage

1. Start a New Project

# Initialize a new project
./bin/init-project.sh my-saas-app user-feature

# Start the specification conversation
./bin/start-specs.sh my-saas-app

2. Work with Your AI Assistant

Tell Claude (or your AI assistant):

"Start specs wizard for this project"

The AI will guide you through an engaging conversation to extract:

• Problem definition and user pain points
• Business context and constraints
• Technical requirements and architecture
• Work breakdown into epics and tasks

3. Export to Development-Ready Format

# Generate issues.json for ido4 or other tools
./bin/export-issues.sh my-saas-app

# Import to ido4 (if using)
ido4 project:import projects/my-saas-app/issues.json

🎯 Key Features

Intelligent Conversation Design

Unlike simple questionnaires, Specs Wizard uses strategic conversation patterns to:

• Uncover hidden requirements through follow-up questions
• Challenge assumptions to prevent costly mistakes
• Extract specific examples instead of vague descriptions
• Maintain engagement through dynamic, contextual questioning

Adaptive Project Workflows

Different project types need different approaches:

Project Type	Workflow	Focus Areas
user-feature	Full 6-stage process	Discovery, user research, requirements
tech-debt	Technical assessment	Performance, architecture, refactoring
migration	Architecture-focused	Risk assessment, rollback planning
bugfix	Streamlined	Root cause, impact analysis
integration	Technical	API design, data mapping
enhancement	Requirements-focused	User feedback, incremental value

AI-Ready Task Classification

Every task is classified for optimal human-AI collaboration:

• 🧑 human-only: Strategic decisions, architecture, business logic
• 🤖 ai-reviewed: Implementation with human oversight
• 🤝 hybrid: Collaborative human-AI work
• ✨ ai-only: Routine, well-defined tasks (used sparingly)

Wave-Based Execution

Tasks are organized into waves (2-4 week cycles) following ido4 principles:

• Epic Integrity: All tasks in an epic stay together
• Wave Self-Sufficiency: Each wave has all its dependencies
• Progressive Complexity: Waves build on each other logically

📋 The 6-Stage Process

Stage 1: Concept Capture

Goal: Extract and clarify the core idea

The AI will explore:

• The problem you're solving and why it matters
• Who experiences this pain and how severely
• What triggered the need for action now
• Initial vision and success criteria

Stage 2: Discovery

Goal: Deep dive into context and constraints

Uncover:

• User personas and their journeys
• Competitive landscape and alternatives
• Technical and business constraints
• Risks and mitigation strategies

Stage 3: Requirements

Goal: Transform insights into structured requirements

Define:

• Functional capabilities with acceptance criteria
• Non-functional requirements (performance, security)
• User stories from multiple perspectives
• Integration and compliance needs

Stage 4: Architecture

Goal: Design the technical approach

Decide on:

• System architecture and patterns
• Technology stack with justifications
• Data models and flows
• Security and deployment strategies

Stage 5: Epic Breakdown

Goal: Organize work into coherent capabilities

Create:

• Business-focused epics (3-8 tasks each)
• Clear value propositions for each epic
• Strategic rationale and success metrics
• Wave assignments maintaining Epic Integrity

Stage 6: Task Generation

Goal: Create detailed, actionable tasks

Generate:

• Tasks sized for 1-5 days of work
• Complete acceptance criteria
• Technical context for developers
• Testing requirements and DoD

🛠️ Advanced Features

Document-Driven Mode

Have existing documentation? Upload it and let the AI extract specifications:

# Initialize document analysis project
./bin/init-docs-project.sh my-project

# Place documents in documents/uploaded/
cp meeting-notes.md requirements.pdf documents/uploaded/

# Run analysis
./bin/analyze-docs.sh my-project

The AI will:

• Extract information from all documents
• Identify gaps in specifications
• Ask only essential clarifying questions
• Generate complete specs with minimal interaction

Progress Tracking

The system maintains detailed progress metadata:

• Section-level completion tracking
• Quality assessments (basic/detailed/comprehensive)
• Key insights discovered during conversations
• Time spent per stage

🤔 Who Benefits?

Product Managers & Owners

• Transform ideas into complete specifications systematically
• Ensure no critical requirements are missed
• Get technical feasibility validated early
• Create specs optimized for modern development

Software Developers

• Receive clear, detailed task specifications
• Understand business context and rationale
• Get tasks properly sized and scoped
• Know exactly what "done" looks like

Technical Leads & Architects

• Ensure architectural decisions are captured
• Validate technical approach before implementation
• Properly classify tasks for AI assistance
• Maintain system coherence across waves

Startup Founders & Entrepreneurs

• Quickly validate and specify product ideas
• Understand technical implications and effort
• Create investor-ready specifications
• Bridge the gap between vision and execution

🚧 Project Status

✅ What's Working

• Complete conversation framework with Claude
• Adaptive workflows for different project types
• Template-driven specification generation
• Basic JSON export for ido4
• Document analysis mode
• Progress tracking and metadata

🔧 What's In Progress

• Automated markdown-to-JSON parsing
• Enhanced validation algorithms
• Web-based interface
• Integration with more PM tools

🎯 What's Planned

• Multi-project dependency management
• Team collaboration features
• Custom template creation
• API for programmatic access
• VS Code extension

🤝 Contributing

We need your help to make Specs Wizard better! This is a community-driven project that benefits from diverse perspectives.

How You Can Help

For Product People

• Share conversation patterns that work
• Contribute industry-specific templates
• Test with real projects and provide feedback

For Developers

• Improve parsing and validation
• Add integrations with other tools
• Enhance AI conversation patterns
• Fix bugs and improve scripts

For Everyone

• Report issues and suggest features
• Improve documentation
• Share success stories
• Help others in discussions

See CONTRIBUTING.md for detailed guidelines.

Getting Started with Contributing

# Fork and clone
git clone https://github.com/your-username/ido4-specs-wizard.git

# Create feature branch
git checkout -b feature/your-improvement

# Make changes and test
./bin/init-project.sh test-project
./bin/start-specs.sh test-project

# Submit PR with clear description

📚 Documentation

• CLAUDE.md - Complete instructions for AI assistants
• Knowledge Base - Deep methodology and patterns
• Templates - Conversation templates for each stage
• Contributing Guide - How to contribute

🎬 Example Session

$ ./bin/init-project.sh task-automation-tool user-feature
✅ Created project: task-automation-tool

$ ./bin/start-specs.sh task-automation-tool
📋 Project: task-automation-tool
📊 Progress: Stage 1 of 6 (Concept)
💬 Tell Claude: "Start specs wizard for this project"

# In Claude:
You: Start specs wizard for this project

Claude: Hi! I'm your Specs Wizard - I transform product ideas into 
production-ready specifications. I can see you're working on 
'task-automation-tool'. 

This sounds like a fascinating challenge! Let's start with the human 
side of this problem. Tell me about the last time you or someone on 
your team experienced the frustration that led to this idea...

You: Our team spends hours every week manually updating JIRA tickets 
based on PR reviews...

Claude: Hours every week - that's painful! And I bet it's not just the 
time, it's the context switching and mental energy drain. Help me 
understand: when you say "manually updating based on PR reviews", 
walk me through what that actually looks like. What specific steps 
does someone have to do?

[Conversation continues, building deep understanding...]

🛡️ Security

• No data is sent to external services (except your AI assistant)
• All specifications remain local until you export
• Templates don't contain sensitive defaults
• See Security Policy for details

📄 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

• Built for the ido4 ecosystem
• Inspired by best practices in requirements engineering
• Designed for the age of AI-assisted development

💬 Support & Community

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Updates: Watch this repo for updates

---

Ready to transform your next idea into reality?

./bin/init-project.sh your-amazing-idea

Built with ❤️ for product builders and development teams everywhere