Transform project ideas into production-ready codebases through intelligent validation, planning, and automated implementation with comprehensive demo mode for immediate usage.

• 🎭 Demo Mode: Immediate usage without API keys - try all features with fallback implementations
• 🔍 Idea Validation: Critical idea validation with external API integration and business viability scoring
• 🎯 Enhanced Planning: AI-powered feature breakdown into epics and implementable stories
• 🏗️ Smart Scaffolding: Language-aware project generation (Python/Node.js) with comprehensive templates
• 🔄 Micro-Prompt Queue: Test-driven development automation with multi-provider LLM support
• 📊 Experience Learning: Automatic failure analysis and guard-rail generation from development experiences
• 🐛 Issue Reporting: Automated GitHub issue creation with system diagnostics and log collection
• 🔧 Configuration Management: JSON schema validation with user-friendly setup

# Install from PyPI pip install ai-idea-cli # Or create a virtual environment first (recommended) python -m venv .venv source .venv/bin/activate # On Windows: .venv\Scripts\activate pip install ai-idea-cli

# Initialize configuration (enables demo mode by default) idea init-config # Validate an idea (demo mode) idea validate "AI-powered task management CLI" # Create a project (demo mode) idea new "AI-powered task management CLI" --dry-run

✅ Success check: All commands work immediately with demo responses and guidance

# Edit configuration file nano ~/.idea-cli/config.json # Set your API keys and disable demo mode: { "demoMode": false, "validator": { "apiKeyEnv": "VALIDATOR_API_KEY" }, "models": { "apiKeyEnv": "ANTHROPIC_API_KEY" } } # Set environment variables export ANTHROPIC_API_KEY="your_claude_key" export VALIDATOR_API_KEY="your_validator_key"

Demo Mode (Default - No API keys required):

• ✅ Immediate usage for testing and exploration
• ✅ All CLI commands functional with fallback responses
• ✅ Basic project scaffolding with "hello world" templates
• ✅ Clear upgrade paths and configuration guidance
• ✅ Issue reporting with manual instructions

Full Mode (API keys configured):

• 🚀 Real idea validation with business scoring
• 🚀 AI-enhanced planning with detailed breakdowns
• 🚀 Complete TDD implementation cycle
• 🚀 Automatic lesson generation and guard-rail updates
• 🚀 Automated GitHub issue reporting

• JSON schema validation ensures configuration integrity
• User config stored in ~/.idea-cli/config.json
• Auto-detection of demo mode vs full mode based on API key availability

• Demo Mode: Provides neutral scoring with upgrade guidance
• Full Mode: Real validation using external validator API with business viability scoring
• Configurable score thresholds and acceptance criteria

• Demo Mode: Basic project structure with common patterns
• Full Mode: AI-powered breakdown into epics and implementable stories
• Technology stack recommendations based on idea analysis

• Demo Mode: Static templates with development guidance
• Full Mode: Micro-prompt queue drives TDD implementation
• Support for multiple LLM providers (Anthropic Claude, OpenAI GPT)

• Experience collection from development failures
• AI summarization into actionable lessons
• Auto-generated guard-rails from lessons

For Demo Mode (Default - No Setup Required):

idea init-config # Creates config with demo mode enabled idea validate "test idea" # Works immediately

For Full Mode (API Keys Required):

# 1. Initialize configuration idea init-config # 2. Set environment variables export ANTHROPIC_API_KEY="your_claude_api_key_here" export VALIDATOR_API_KEY="your_validator_api_key_here" # Optional # 3. Edit config to disable demo mode nano ~/.idea-cli/config.json # Change: "demoMode": false

The configuration file is automatically created when you run idea init-config. Here's what each section does:

Demo Mode Configuration (Default):

{ "demoMode": true, "retentionDays": 30, "scaffold": { "templateVersion": "main" } }

Full Mode Configuration:

{ "demoMode": false, "validator": { "endpoint": "https://api.example.com/validate", "apiKeyEnv": "VALIDATOR_API_KEY", "minScore": 0.7 }, "models": { "plan": "claude-3-5-sonnet-20241022", "queue": "claude-3-5-sonnet-20241022", "summarise": "claude-3-5-sonnet-20241022", "apiKeyEnv": "ANTHROPIC_API_KEY" }, "scaffold": { "templateVersion": "main" }, "retentionDays": 30 }

Anthropic Claude (Recommended):

• Models: claude-3-5-sonnet-20241022, claude-3-haiku-20240307
• Get API key: https://console.anthropic.com/
• Install: pip install anthropic

OpenAI GPT:

• Models: gpt-4, gpt-3.5-turbo
• Get API key: https://platform.openai.com/api-keys
• Install: pip install openai

idea-cli/ ├── idea/ # Core package │ ├── cli.py # Main CLI with global error handling │ ├── config.py # Configuration management with JSON schema │ ├── demo.py # Demo mode implementations │ ├── validator.py # Idea validation with demo support │ ├── llm.py # Multi-provider LLM integration │ ├── issue_reporter.py # GitHub issue reporting │ ├── planner.py # AI-powered planning │ ├── queue.py # Queue management │ ├── runner.py # Story implementation engine │ ├── experience.py # Learning system │ └── scaffold/ # Project scaffolding │ ├── python.py # Python project scaffolder │ └── node.py # Node.js project scaffolder ├── config/ # Configuration schema and defaults │ ├── schema.json # JSON schema for validation │ └── default.json # Default configuration template ├── templates/ # Copier templates ├── .github/workflows/ # CI/CD pipelines └── scripts/ # Development scripts 

my-project/ ├── .idea/ # Project metadata │ ├── plan.json # Enhanced plan with epics/stories │ ├── queue.json # Implementation queue │ └── _logs/ # Development logs and failures ├── src/ # Source code ├── tests/ # Test files ├── lessons/ # Project-specific lessons ├── .github/workflows/ # CI/CD for the project └── README.md # ADHD-friendly instructions 

When errors occur, idea-cli can automatically create GitHub issues with:

• System information (OS, Python version, architecture)
• Configuration summary (sanitized, no secrets)
• Recent log files from .idea/_logs/
• Steps to reproduce template

# Report an issue manually idea report-issue "CLI command failed" --dry-run # Automatic issue reporting on unexpected errors # (triggered automatically with user confirmation)

If GitHub CLI is not available, idea-cli provides:

• Pre-formatted issue content
• System diagnostics
• Copy-paste ready templates

"Command 'idea' not found"

• Fix: Ensure package is installed: pip install ai-idea-cli
• Check: pip show ai-idea-cli should show installation
• Try: Restart your terminal or source your shell profile

"Configuration error: API key environment variable not configured"

• For Demo Mode: Run idea init-config and verify "demoMode": true in config
• For Full Mode: Set export ANTHROPIC_API_KEY=your_key and ensure "demoMode": false

"Failed to initialize config"

• Fix: Check permissions: ls -la ~/ (should be writable)
• Try: mkdir -p ~/.idea-cli && idea init-config
• Alternative: Use --config-dir flag to specify different location

"Import errors for anthropic/openai packages"

• Fix: pip install anthropic (for Claude) or pip install openai (for GPT)
• Note: Only needed for full mode, demo mode works without these packages

Commands work but show demo responses

• This is normal! Demo mode is the default
• To upgrade: Set API keys and change "demoMode": false in config
• Verify: echo $ANTHROPIC_API_KEY should show your key

• Use --dry-run for testing without API calls
• Use --demo flag to force demo mode temporarily
• Set appropriate model choices in config (haiku for speed, sonnet for quality)

# Enable verbose logging export IDEA_CLI_DEBUG=1 idea validate "test idea" # Check configuration idea init-config # Shows current config path and status

We welcome contributions! Here's how to get started:

# Fork the repository on GitHub git clone https://github.com/yourusername/ai-idea-cli.git cd ai-idea-cli # Install in development mode pip install -e . # Test the installation idea --help

1. Test demo mode: All commands should work without API keys
2. Test full mode: Set API keys and test enhanced features
3. Run quality checks: ruff check . && ruff format --check .
4. Test error handling: Verify issue reporting functionality
5. Update documentation: Keep README and docstrings current

• Test both demo and full modes
• Include tests for new features
• Update documentation for user-facing changes
• Follow existing code style and patterns

MIT License - see LICENSE file for details.

🎭 Start in demo mode, upgrade when ready!