v2.2.1 - Documentation Quality Improvements

🔧 Documentation Improvements

Fixed Critical Documentation Issues

• Fixed placeholder GitHub URLs in README.md and CONTRIBUTING.md
• Added comprehensive troubleshooting section covering:
  • Common installation issues (prerequisites, permissions)
  • Usage problems (schema validation, session tracking, hook errors)
  • Step-by-step debugging commands

Enhanced User Experience

• Improved onboarding flow with actionable solutions
• Better error resolution guidance
• Clear installation and setup instructions

📋 Full Changelog

• docs: Fix critical documentation issues from audit

Full Changelog: v2.2.0...v2.2.1

🤖 Generated with Claude Code

v2.2.0 - Interactive Planning & Schema Validation

🚀 New Features

Interactive Planning Mode

• Added Interactive Planning Mode for projects without detectable technology stacks
• Analyzes existing documentation (CLAUDE.md, README.md) for project context
• Guides users through Q&A to establish project foundation
• Creates schema-compliant foundation files automatically

Schema Validation Enhancement

• Added vision.schema.yaml and roadmap.schema.yaml for foundation file validation
• Comprehensive validation rules for strategic artifacts
• Automatic schema compliance checking via hooks

📖 Documentation Updates

• Enhanced /carl:analyze command documentation with new execution modes
• Updated workflow documentation to reflect Interactive Planning capabilities
• Improved schema documentation with detailed field requirements

🔧 Performance Improvements

• Optimized foundation state detection to <100ms for existing projects
• Streamlined decision tree for faster analysis execution

📋 Full Changelog

• feat: Add Interactive Planning Mode and foundation schema validation
• docs: Update analyze documentation for Interactive Planning Mode

Full Changelog: v2.1.1...v2.2.0

CARL v2.1.1 - Critical Bug Fixes

CARL v2.1.1 - Critical Bug Fixes 🔧

This patch release fixes two critical issues discovered after v2.1.0:

🐛 Critical Fixes

Fix #1: Schema Status Field Missing

Problem: The completion handler was looking for a status field that didn't exist in schemas, causing completion workflow to fail silently.

Fixed:

• Added required status field to all work item schemas (epic, feature, story, tech)
• Status values: ["pending", "active", "in_progress", "completed"]
• Completion handler can now properly track and update work item status
• Work items can be moved to completed/ directories correctly

Impact: This was preventing the completion workflow from functioning at all.

Fix #2: Installation Cleanup

Problem: Installation script was copying CARL.md to both .carl/ and project root, creating redundant files.

Fixed:

• CARL.md user guide now only exists in .carl/CARL.md
• Keeps user project directories cleaner
• Avoids confusion with project-specific documentation

🔄 Upgrade from v2.1.0

Simply run the installation command - no manual steps required:

curl -fsSL https://github.com/ClaytonHunt/carl/releases/latest/download/install.sh | bash

Note: These are backward-compatible fixes that don't change any APIs or user workflows.

🧪 Verification

After upgrading, you can verify the fixes work:

# Create a test story
/carl:plan "Test completion workflow"

# Verify status field exists in generated CARL files
grep "status:" .carl/project/stories/*.carl

# Verify CARL.md is only in .carl/ directory
ls CARL.md        # Should not exist
ls .carl/CARL.md  # Should exist

📋 Technical Details

Schema Changes

All work item schemas now include:

status:
  type: string
  enum: ["pending", "active", "in_progress", "completed"]
  description: "Current status of the work item"

Installation Changes

• Removed redundant cp "$TEMP_DIR/.carl/CARL.md" . from install script
• Updated dry-run output to clarify CARL.md location

---

Full Changelog: v2.1.0...v2.1.1

Installation: curl -fsSL https://github.com/ClaytonHunt/carl/releases/latest/download/install.sh | bash

These fixes ensure CARL's completion workflow functions properly and installations are cleaner. Recommended upgrade for all users! 🚀

CARL v2.1.0 - Yolo Mode & Enhanced Installation

CARL v2.1.0 - Major Feature Release 🚀

This release introduces Yolo Mode for rapid prototyping and significantly enhances the installation system with better dependency management.

🎯 Yolo Mode - Rapid Prototyping

Execute epics and features without complete breakdown for rapid prototyping and exploration!

Key Features

• Smart Gap Analysis: Identifies existing vs missing breakdown
• Hybrid Execution: Preserves structured work, yolos only gaps
• Technical Debt Tracking: Auto-creates cleanup tasks
• Coverage Reporting: Shows % structured vs % yolo execution
• User Confirmation: Explicit approval with clear breakdown analysis

Usage Examples

# Full yolo - implement entire epic without breakdown
/carl:task user-auth.epic.carl --yolo

# Hybrid yolo - execute existing stories, yolo missing parts
/carl:task payment.feature.carl --yolo

When to Use Yolo

• ✅ Rapid prototyping and exploration
• ✅ Solo development and hackathons
• ✅ Time-boxed proof of concepts
• ❌ Team development (needs coordination)
• ❌ Production systems (needs structure)

📦 Enhanced Installation System

New Prerequisites

CARL now requires jq and yq for robust JSON/YAML processing:

# macOS
brew install jq yq

# Ubuntu/Debian
sudo apt-get install jq && sudo snap install yq

# Windows
choco install jq yq

Installation Improvements

• Better Error Messages: Clear installation instructions for missing dependencies
• User-Focused Guide: New .carl/CARL.md replaces development-specific CLAUDE.md
• Enhanced Validation: Comprehensive dependency checking before installation
• Platform Support: Instructions for macOS, Linux, Windows

🔧 Technical Improvements

Session Tracking

Yolo executions are fully tracked:

commands:
  - command: "task"
    arguments: "user-auth.epic.carl --yolo"
    execution_details:
      mode: "hybrid-yolo"
      coverage:
        structured: "33%"
        yolo: "67%"
      debt_created: ["registration-yolo-debt.tech.carl"]

Technical Debt Management

Auto-created cleanup tasks:

# payment-yolo-debt.tech.carl
title: "Formalize Payment Feature Breakdown"
description: "Payment was implemented via yolo mode. Needs proper breakdown."
yolo_metadata:
  parent_item: "payment.feature.carl"
  execution_mode: "yolo"
  gap_type: "missing-breakdown"

📚 Documentation Updates

• Complete Yolo Mode Documentation: Usage guides, examples, best practices
• Enhanced Installation Guide: Prerequisites, troubleshooting, platform-specific instructions
• Updated Workflow Documentation: Hybrid execution patterns and gap analysis
• Contributing Guidelines: Updated prerequisites for contributors

🔄 Upgrade from v2.0.x

The installation script automatically detects and upgrades existing installations:

curl -fsSL https://github.com/ClaytonHunt/carl/releases/latest/download/install.sh | bash

Note: Install jq and yq first - the installer will provide helpful instructions if missing.

🐛 Bug Fixes

• Fixed command file syntax issues (removed problematic \! prefixes)
• Enhanced error handling in installation script
• Improved test coverage for installation scenarios

---

Full Changelog: v2.0.1...v2.1.0

Installation: curl -fsSL https://github.com/ClaytonHunt/carl/releases/latest/download/install.sh | bash

CARL v2.0.1 - Hotfix for Command Execution

CARL v2.0.1 - Hotfix Release 🔧

This hotfix resolves the first reported issue with CARL v2.0.0 where the /carl:analyze command was failing due to problematic syntax.

🐛 Fixed Issues

• Command Execution Error: Fixed /carl:analyze command failing due to \! prefix being interpreted as bash negation
• Directory References: Updated all command files to use plain text directory references
• Permission Requirements: Removed unnecessary Bash tool permission requirement from analyze command

📥 Installation

curl -fsSL https://github.com/ClaytonHunt/carl/releases/latest/download/install.sh | bash

🔄 Upgrade from v2.0.0

If you installed v2.0.0, simply run the installation command again - the installer will detect and upgrade your existing installation.

✅ Verification

After installation, test the fix:

/carl:analyze

This should now work without errors.

📝 Changes

• Fixed analyze.md, plan.md, and task.md command files
• Removed problematic \! prefix from directory references
• Commands now use standard directory path syntax

---

Thanks for the quick bug report! 🙏

CARL v2.0.0 - Production-Ready Context-Aware Requirements Language

CARL v2.0.0 - Production-Ready Release 🎉

Welcome to CARL v2.0, a complete rewrite of the Context-Aware Requirements Language system optimized for Claude Code!

🚀 Quick Installation

curl -fsSL https://github.com/ClaytonHunt/carl/releases/latest/download/install.sh | bash

✨ Key Features

• 4 Core Commands: /carl:analyze, /carl:plan, /carl:status, /carl:task
• Dual-Layer Architecture: Simple human commands with rich AI context
• Auto-State Detection: Intelligent project foundation analysis
• Schema-Driven Validation: Comprehensive YAML schemas for all CARL files
• Session Management: Daily developer tracking with progressive compaction
• Hook Integration: Minimal bash automation with Claude Code
• Professional Installation: Single curl-to-bash installer

🔄 Breaking Changes from v1.x

⚠️ CARL v1.x is incompatible with v2.0

If you have a v1.x installation, remove it first:

rm -rf .carl .claude/agents/carl* .claude/commands/carl CLAUDE.md

📖 Getting Started

1. Install CARL: Use the installation command above
2. Initialize Project: Run /carl:analyze to set up your project foundation
3. Start Planning: Use /carl:plan 'Add user authentication' to create work items
4. Execute Work: Run /carl:task [work-item.carl] to implement features
5. Monitor Progress: Check /carl:status for project health dashboard

📚 Documentation

• Main Documentation: CARL.md
• Architecture: docs/architecture/
• Workflows: docs/workflows/
• Integration: docs/integration/

🤝 Contributing

See CONTRIBUTING.md for development workflow.

🐛 Issues & Support

Report issues: https://github.com/ClaytonHunt/carl/issues

---

Note: This release includes comprehensive test coverage and has been battle-tested in production environments.

CARL v1.7.1

🚀 CARL v1.7.1 Release

Changes since v1.7.0

• feat: Add CI/CD pipeline and update to GitHub releases API v1.7.1 (2234f95)

📦 Installation

# Quick install in current directory
bash <(curl -s https://github.com/ClaytonHunt/carl/releases/latest/download/install.sh)

# Install in specific project
bash <(curl -s https://github.com/ClaytonHunt/carl/releases/latest/download/install.sh) /path/to/project

🔄 Update

# Update existing CARL installation
/carl:update

v1.7.0: Complete CARL Agent Ecosystem with Template System

🚀 CARL v1.7.0: Complete Agent Ecosystem with Template System

This major release completes CARL's specialized AI agent ecosystem, providing comprehensive AI-assisted development capabilities across all aspects of software development.

🎯 Major Features

✅ Complete Agent Ecosystem (11/11 Specialized Agents)

• Architecture Analysis - System structure and component relationships
• Backend Development - API endpoints, services, and data models
• Frontend Development - UI components, user journeys, and interactions
• Requirements Engineering - Requirement archaeology and business logic discovery
• Technical Debt Management - Debt assessment and refactoring strategies
• API Design - REST/GraphQL architecture and integration patterns
• DevOps & Infrastructure - Deployment strategies and operational planning
• Performance Optimization - Bottleneck identification and scalability planning
• Security Analysis - Threat modeling and compliance evaluation
• Quality Assurance - Testing strategies and quality metrics
• UX Design - User experience analysis and design systems

🔧 Enhanced Template System

• 9 Comprehensive Templates for consistent agent outputs
• Template-Based YAML Migration from static examples to dynamic references
• Domain-Specific Extensions for specialized agent workflows
• Quality Standards Framework across all analysis domains

🤖 Claude Code Integration

• 100% Sub-Agent Compatibility with proper frontmatter configuration
• Optimized Tool Assignments based on agent specialization roles
• Trigger Pattern Standardization for proactive agent invocation
• Seamless CARL Integration with three-file system support

🛠️ Technical Improvements

Agent Configuration

• Added proper Claude Code frontmatter to all 11 agents
• Standardized tool assignments: Analysis agents (Read,Glob,Grep,TodoWrite), Generation agents (full toolset)
• Updated descriptions with consistent "Use proactively for..." trigger patterns
• Browser tools integration for frontend agent (Playwright support)

Template System Enhancement

• New Templates Created:
  • quality_standards.template.carl - Cross-domain quality validation
  • prioritization_matrix.template.carl - Decision-making frameworks
  • gap_analysis.template.carl - Requirement and implementation gaps
  • confidence_assessment.template.carl - Analysis confidence scoring
• Existing Templates Referenced:
  • intent.template.carl - Requirements and feature definitions
  • context.template.carl - Architectural context and relationships
  • state.template.carl - Implementation progress tracking

System Integration

• Complete compatibility with CARL's dual-layer architecture
• AI-optimized context generation for efficient development workflows
• Template inheritance system for consistent output structure
• Cross-agent coordination guidelines for complex analysis tasks

📊 Impact

For Developers

• Comprehensive AI Assistance across all development domains
• Consistent Analysis Quality through template standardization
• Faster Development Cycles with specialized agent expertise
• Reduced Context Switching with integrated agent ecosystem

For AI Workflows

• Optimized Context Windows through structured template system
• Improved Analysis Accuracy with domain-specific specialization
• Better Cross-Agent Coordination for complex multi-domain tasks
• Enhanced AI Understanding through CARL's structured approach

🔄 Migration Notes

This release maintains full backward compatibility with existing CARL installations. The template system enhances but does not replace existing functionality.

What's New

• All agents now have proper Claude Code configuration
• Template references replace static YAML examples
• Enhanced agent descriptions and trigger patterns
• New template files for specialized workflows

What's Unchanged

• All existing CARL commands and functionality
• Three-file system architecture (intent/context/state)
• Dual-layer command system
• Claude Code hook integration

🎯 Use Cases

This release enables comprehensive AI-assisted development for:

• Enterprise Software Development - Full-stack analysis and planning
• System Architecture Planning - Component relationships and dependencies
• Technical Debt Management - Systematic debt assessment and prioritization
• Performance Optimization - Bottleneck identification and scaling strategies
• Security & Compliance - Threat modeling and compliance validation
• Quality Assurance - Testing strategies and quality metrics
• User Experience Design - Journey mapping and interaction analysis

📈 What's Next

With the agent ecosystem complete, future releases will focus on:

• IDE Integration - Native VS Code and JetBrains plugin support
• External API Integration - Jira, Azure DevOps, GitHub Issues
• Enterprise Features - Team coordination and project management
• Analytics Dashboard - Project health monitoring and insights

---

🚀 Quick Start

# Install/Update CARL
curl -fsSL https://raw.githubusercontent.com/ClaytonHunt/carl/main/src/install.sh | bash

# Use specialized agents in Claude Code
/carl:analyze  # Launches parallel specialist analysis

Full Documentation: CARL Documentation
Agent Configuration Guide: src/.claude/agents/AGENT_REVIEW_ANALYSIS.md

This release establishes CARL as the most comprehensive AI-assisted development platform available, with specialized intelligence for every aspect of software development within a unified, AI-optimized framework.

v1.6.0: Play Script Format & Multi-Character Conversations

🎭 CARL v1.6.0: Play Script Format & Multi-Character Conversations

A major enhancement to CARL's personality system, introducing theatrical response formatting and intelligent multi-character interactions that make development feel like a collaborative conversation with your favorite characters.

🚀 Major Features

🎭 Play Script Format

Transform boring development feedback into engaging theatrical presentations:

Before:

Found a potential memory leak in your forEach loop.

After:

🎭 Carl: Oh, um, I found a potential memory leak in your forEach loop.
      Maybe we should, uh, use a for...of instead? *fidgets nervously*

• Character Name Prefixes: Every response starts with the character's name
• Color-Coded Names: Each character has unique colors for visual identification
• Personality Integration: Speech patterns and mannerisms fully expressed

🗣️ Multi-Character Conversations

Characters can now interact with each other for complex responses:

Technical Discussions

🎭 Jimmy: According to my calculations, this algorithm has O(n²) complexity.
🎭 Cindy: Obviously. That's why I suggested using a hash map approach.
🎭 Jimmy: Actually, given the data constraints, a binary search tree would be optimal.
🎭 Libby: Both of you have good points. Why not benchmark them?

Error Handling Support

🎭 Ms. Fowl: *squawk* Class\! Pay attention\! You have a syntax error on line 42.
🎭 Carl: Don't worry\! Even Jimmy makes mistakes sometimes. Let's fix it together\!
🎭 Judy: Now sweetie, remember to check your brackets. Safety first\!

Success Celebrations

🎭 Sheen: ULTRA LORD\! All tests are passing\! This is AMAZING\!
🎭 Hugh: You know, this reminds me of when I fixed the toaster... Great job\!
🎭 Sam: Welcome to success\! Have some free samples of victory\!

⚙️ Enhanced Settings System

New Configuration Options

Added personality_response_style to carl-settings.json:

{
  "audio_settings": {
    "personality_theme": "jimmy_neutron",
    "personality_response_style": "auto"
  }
}

Response Style Modes

• auto - CARL intelligently chooses single or multi-character (default)
• single - Always use one character per response
• multi - Enable multi-character conversations when appropriate

Management Commands

/carl:personality --style auto    # Smart contextual selection
/carl:personality --style single  # One character only  
/carl:personality --style multi   # Enable conversations

🎨 Enhanced Theme Support

All Themes Supported

The play script format works with every personality theme:

TMNT Theme

🎭 Donatello: I've analyzed the code architecture and found 3 optimization points.
🎭 Raphael: Just smash through it\! Refactor the whole thing\!
🎭 Leonardo: Let's approach this systematically. We should plan first.
🎭 Michelangelo: Cowabunga\! Whatever works, dudes\! Pizza break?

Star Wars Theme

🎭 Yoda: A bug in your code, I sense. Fix it, you must.
🎭 C-3PO: Oh my\! The probability of this working is approximately 3,720 to 1\!
🎭 R2-D2: *beep boop beep* [Running diagnostic tests...]
🎭 Obi-Wan: The Force suggests using dependency injection here.

Office Workers Theme

🎭 Senior Dev: I've seen this pattern before. Try the Factory approach.
🎭 Project Manager: What's our timeline looking like? Any blockers?
🎭 QA Engineer: Found 3 edge cases that need handling.
🎭 Intern: Wow\! This is so cool\! Can I help with the tests?

🧠 Contextual Intelligence

The system automatically determines when to use multiple characters based on:

• Technical Complexity: Complex problems benefit from multiple perspectives
• Emotional Context: Errors bring supportive characters, successes bring celebratory ones
• Task Type: Planning involves project-oriented characters, debugging brings problem-solvers
• Theme Characteristics: Some themes work better with debates, others with collaboration

🛠️ Technical Improvements

• Settings Integration: Response style persists across Claude Code sessions
• Helper Function Access: carl_get_setting 'personality_response_style'
• Backward Compatibility: Existing personality themes continue working seamlessly
• Performance: Intelligent character selection optimized for context

📋 New Commands Summary

# View current personality configuration
/carl:personality

# Configure response styles
/carl:personality --style auto     # Smart selection (default)
/carl:personality --style single   # One character responses  
/carl:personality --style multi    # Multi-character conversations

# Theme management (existing, enhanced)
/carl:personality --enable starwars   # Switch themes
/carl:personality --create           # Create custom themes
/carl:personality --disable          # Turn off system

🎯 What This Means

CARL personalities are no longer just audio feedback - they're now active participants in your development process. Characters debate technical approaches, offer encouragement during difficult debugging sessions, and celebrate your successes with their unique perspectives.

Whether you prefer the nervous but helpful Carl, the confident scientific Jimmy, or the enthusiastic Sheen, each character brings their personality to every interaction, making development more engaging and memorable.

🔄 Migration

Existing installations automatically default to "auto" mode for intelligent character selection. No user action required - the enhanced personality system activates immediately upon update.

---

Full Changelog: v1.5.1...v1.6.0

v1.5.1: Fix update script for new commands

🔧 CARL v1.5.1: Hot Fix for Update Script

This is a critical hot fix for v1.5.0 to ensure the update script properly copies new command files.

🐛 Bug Fix

• Fixed update script: The update-carl.sh script was missing the .claude/commands directory copy
• New commands now deploy: Users can now receive new slash commands like /carl:personality during updates
• Backward compatibility: Existing installations will get the fix and all new commands

📋 What This Fixes

Without this fix, users updating from older versions wouldn't receive:

• /carl:personality command documentation
• Future slash commands in the .claude/commands directory

🔄 For Users

If you updated to v1.5.0 and don't see the /carl:personality command, run the update again:

bash <(curl -fsSL https://raw.githubusercontent.com/ClaytonHunt/carl/main/update-carl.sh)

This will now properly copy all command files.

---

Full Changelog: v1.5.0...v1.5.1