codesavant 3.4.1 → 4.0.0

package/README.md

@@ -1,6 +1,6 @@
 # CodeSavant
 
-> AI-powered coding assistant CLI that brings Claude, GPT-4, and other leading AI models directly to your terminal.
+> AI-powered autonomous coding agent CLI that brings Claude, GPT-4, and other leading AI models directly to your terminal. Features autonomous workflows, a skill marketplace, self-improving brain, and design intelligence.
 
 [![NPM Version](https://img.shields.io/npm/v/codesavant.svg)](https://www.npmjs.com/package/codesavant)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
@@ -8,22 +8,34 @@
 
 ---
 
-## ✨ Features
+## What's New in v4.0
 
-- 🤖 **Multi-Provider Support** - Works with Anthropic Claude, OpenAI GPT-4, Groq, DeepSeek, Google Gemini, Ollama, and AWS Bedrock
-- 🎯 **Interactive REPL** - Rich terminal interface with streaming responses and real-time tool execution
-- 🔧 **20+ Built-in Tools** - File operations, web search, code analysis, task management
-- 🎨 **Aurora Theme** - Beautiful, modern color scheme optimized for terminal readability
-- 💾 **Session Management** - Save, resume, and checkpoint your conversations
-- 🔌 **MCP Integration** - Model Context Protocol support for extensibility
-- 🎭 **Craft Skills** - AI-powered workflows for TDD, debugging, planning, and code review
-- 🚀 **Multiple Execution Modes** - Interactive, single-command, pipe mode, or resume sessions
-- 🛡️ **Security First** - Permission system with SSRF protection and command validation
-- 📊 **Context Management** - Automatic token tracking and conversation compression
+- **Autonomous /craft Cycle** - End-to-end feature building: research, question, plan, build, verify -- all orchestrated automatically
+- **Skill Marketplace** - Browse, install, and publish reusable AI skills with version management and hash verification
+- **Self-Improving Brain** - Cross-session learning that detects patterns, captures failures, and optimizes over time
+- **Design Intelligence Foundation** - Frontend detection, design token vocabulary, and DesignBrief schemas for style-aware code generation
+- **360+ Test Files** - Comprehensive test coverage across unit, integration, e2e, performance, and security suites
 
 ---
 
-## 📦 Installation
+## Features
+
+- **Multi-Provider Support** - Works with Anthropic Claude, OpenAI GPT-4, Groq, DeepSeek, Google Gemini, Ollama, and AWS Bedrock
+- **Interactive REPL** - Rich terminal interface with streaming responses and real-time tool execution
+- **20+ Built-in Tools** - File operations, web search, code analysis, task management
+- **Autonomous Agent** - Self-directed research, questioning, planning, and building via /craft
+- **Skill Marketplace** - Browse, install, and publish community skills
+- **Self-Improving Brain** - Pattern detection, failure capture, and cross-session learning
+- **Design Intelligence** - Frontend detection, style vocabulary, and design token resolution
+- **Craft Skills** - AI-powered workflows for TDD, debugging, planning, and code review
+- **Session Management** - Save, resume, and checkpoint your conversations
+- **MCP Integration** - Model Context Protocol support for extensibility
+- **Security First** - Permission system with SSRF protection and command validation
+- **Context Management** - Automatic token tracking and conversation compression
+
+---
+
+## Installation
 
 CodeSavant requires [Bun](https://bun.sh) runtime (v1.0.0+).
 
@@ -49,7 +61,7 @@ npm install -g codesavant
 
 ---
 
-## 🚀 Quick Start
+## Quick Start
 
 ### 1. Launch Interactive REPL
 
@@ -95,7 +107,7 @@ file: src/utils/parser.ts
 
 ---
 
-## 📖 Usage
+## Usage
 
 ### Command-Line Interface
 
@@ -144,7 +156,7 @@ codesavant --strict
 
 ---
 
-## 🎮 REPL Commands
+## REPL Commands
 
 Once in the interactive REPL, use these slash commands:
 
@@ -194,7 +206,7 @@ Once in the interactive REPL, use these slash commands:
 
 ---
 
-## 🤖 Supported AI Providers
+## Supported AI Providers
 
 ### Anthropic Claude
 
@@ -300,9 +312,9 @@ codesavant --provider bedrock --model anthropic.claude-3-sonnet-20240229-v1:0
 
 ---
 
-## 🎭 Craft Skills (AI Workflows)
+## Autonomous /craft Workflows
 
-Craft skills are specialized AI workflows for software engineering tasks.
+The `/craft` command provides fully autonomous AI workflows that research, plan, build, and verify features end-to-end.
 
 ### Process Skills (Use First)
 
@@ -314,22 +326,6 @@ Craft skills are specialized AI workflows for software engineering tasks.
 /craft diagnose <bug description>
 ```
 
-**Example:**
-```
-> /craft ideate user authentication system
-
-│ I'm using the ideate skill to brainstorm the authentication system.
-│
-│ Let's explore the requirements. What authentication method do you prefer?
-│ 1. JWT tokens (stateless)
-│ 2. Session-based (server-side state)
-│ 3. OAuth 2.0 (third-party)
-│
-> 1
-
-│ Great choice! Let's design a JWT-based auth system...
-```
-
 ### Implementation Skills (During Work)
 
 ```bash
@@ -349,23 +345,6 @@ Craft skills are specialized AI workflows for software engineering tasks.
 /craft workspace <feature-name>
 ```
 
-**Example:**
-```
-> /craft proof login endpoint
-
-│ I'm using TDD workflow. Let me write failing tests first...
-│
-[Tool: Write] ✓ Complete
-file: tests/auth/login.test.ts
-
-│ Tests written. Running to verify they fail...
-│
-[Tool: Bash] ✓ Complete
-command: bun test tests/auth/login.test.ts
-
-│ ✗ 3 tests failing (expected). Now implementing minimal code to pass...
-```
-
 ### Quality Skills (After Work)
 
 ```bash
@@ -379,9 +358,61 @@ command: bun test tests/auth/login.test.ts
 /craft ship
 ```
 
+### Full Autonomous Cycle
+
+```bash
+# Fully autonomous: research → question → plan → build → verify
+/craft <feature description>
+```
+
+The craft orchestrator spawns research agents in parallel, asks targeted questions, builds a development roadmap, executes plans with atomic commits, and verifies output quality -- all autonomously.
+
 ---
 
-## 🔧 Built-in Tools
+## Skill Marketplace
+
+Browse and install community-created skills, or publish your own.
+
+```bash
+# Browse available skills
+/skills marketplace
+
+# Install a skill
+/skills install <skill-name>
+
+# Publish your skill
+/skills publish <skill-path>
+```
+
+Skills are verified with SHA-256 hash integrity checks, support semantic versioning, and handle slug collisions gracefully.
+
+---
+
+## Self-Improving Brain
+
+CodeSavant learns across sessions:
+
+- **Pattern Detection** - Identifies recurring coding patterns and preferences
+- **Failure Capture** - Records what went wrong and how it was fixed
+- **Optimization** - Detects opportunities to improve workflows
+- **Memory Resolution** - Three-tier priority system (project > user > global)
+
+The brain operates transparently -- it writes insights after sessions and reads them before the next one, getting better over time without manual configuration.
+
+---
+
+## Design Intelligence
+
+CodeSavant automatically detects frontend work and applies design-aware context:
+
+- **Frontend Detection** - Identifies frontend tasks from file extensions (.tsx, .jsx, .css, .vue, .svelte), import patterns, and intent keywords
+- **Style Vocabulary** - 50+ design buzzwords (minimal, bold, cinematic, etc.) mapped to concrete design tokens
+- **Design Brief Schema** - Structured, validated design preferences with opinionated defaults
+- **Token Resolution** - Translates style buzzwords into actionable token hints (border-radius, spacing, contrast, etc.)
+
+---
+
+## Built-in Tools
 
 CodeSavant provides 20+ tools that AI can use to help you:
 
@@ -428,7 +459,7 @@ CodeSavant provides 20+ tools that AI can use to help you:
 
 ---
 
-## 📁 Configuration
+## Configuration
 
 ### Settings File
 
@@ -498,193 +529,7 @@ Follow these steps to deploy:
 
 ---
 
-## 🎨 Aurora Theme
-
-CodeSavant features a modern "Aurora" color scheme:
-
-- **Electric Blue** - Assistant messages, primary UI
-- **Aqua** - User input, selections
-- **Emerald** - Success states, completions
-- **Amber** - Warnings, processing
-- **Crimson** - Errors, failures
-- **Violet** - Keywords, special states
-
-Colors are optimized for terminal readability on both light and dark backgrounds.
-
----
-
-## 💡 Examples
-
-### Example 1: Code Review
-
-```bash
-codesavant
-
-> Review the changes in src/auth.ts and suggest improvements
-
-[Tool: Read] ✓ Complete
-file: src/auth.ts
-
-│ I've reviewed the authentication code. Here are my findings:
-│
-│ **Security Issues:**
-│ 1. Line 23: Password stored in plaintext - should use bcrypt
-│ 2. Line 45: JWT secret hardcoded - move to environment variable
-│
-│ **Code Quality:**
-│ 1. Consider extracting validation logic into separate function
-│ 2. Add error handling for database connection failures
-│
-│ Would you like me to fix these issues?
-
-> Yes, fix the security issues
-
-[Tool: Edit] ✓ Complete
-file: src/auth.ts
-
-│ I've updated the code to:
-│ - Hash passwords with bcrypt
-│ - Load JWT secret from environment variable
-│ - Add proper error handling
-│
-│ Changes made to src/auth.ts (lines 23-50)
-```
-
-### Example 2: TDD Workflow
-
-```bash
-codesavant
-
-> /craft proof user registration endpoint
-
-│ Starting TDD workflow. Writing failing tests first...
-
-[Tool: Write] ✓ Complete
-file: tests/api/register.test.ts
-
-│ Test cases written:
-│ 1. Should register new user with valid data
-│ 2. Should reject duplicate email
-│ 3. Should validate password strength
-│ 4. Should return JWT token on success
-│
-│ Running tests...
-
-[Tool: Bash] ✓ Complete
-command: bun test tests/api/register.test.ts
-
-│ ✗ All 4 tests failing (expected)
-│
-│ Now implementing minimal code to pass tests...
-
-[Tool: Write] ✓ Complete
-file: src/api/register.ts
-
-[Tool: Bash] ✓ Complete
-command: bun test tests/api/register.test.ts
-
-│ ✓ All 4 tests passing!
-│
-│ Implementation complete. Ready to commit?
-
-> Yes
-
-[Tool: Bash] ✓ Complete
-command: git add . && git commit -m "feat: add user registration endpoint"
-```
-
-### Example 3: Debugging
-
-```bash
-codesavant
-
-> My app crashes with "Cannot read property 'name' of undefined"
-
-│ Let's debug this systematically. Can you share the error stack trace
-│ or the file where the error occurs?
-
-> Read src/components/UserProfile.tsx
-
-[Tool: Read] ✓ Complete
-file: src/components/UserProfile.tsx
-
-│ Found the issue at line 15:
-│
-│ ```typescript
-│ const userName = user.name; // user might be undefined
-│ ```
-│
-│ The problem is accessing `user.name` without checking if `user` exists first.
-│
-│ Root cause: The component renders before the user data is loaded.
-│
-│ Fix: Add a loading check:
-│
-│ ```typescript
-│ if (!user) return <Loading />;
-│ const userName = user.name;
-│ ```
-│
-│ Should I apply this fix?
-
-> Yes
-
-[Tool: Edit] ✓ Complete
-file: src/components/UserProfile.tsx
-```
-
-### Example 4: Pipe Mode
-
-```bash
-# Analyze an error log
-cat error.log | codesavant --pipe -p "analyze this error and suggest a fix"
-
-# Review a diff
-git diff | codesavant --pipe -p "review these changes"
-
-# Explain code
-cat complex-algorithm.ts | codesavant --pipe -p "explain this algorithm step by step"
-```
-
-### Example 5: Session Management
-
-```bash
-# Start working on a feature
-codesavant
-
-> I need to add OAuth authentication
-
-│ Let's plan the OAuth implementation...
-│ [Long conversation with code changes]
-
-> /checkpoint oauth-implementation
-
-│ ✓ Checkpoint created: oauth-implementation
-
-> /exit
-
-# Later, resume the session
-codesavant -r
-
-> /resume
-
-│ Recent sessions:
-│ 1. [2h ago] OAuth authentication (15 messages)
-│ 2. [1d ago] Bug fix in parser (8 messages)
-│
-│ Which session? (1-2)
-
-> 1
-
-│ Resuming session...
-│ [Previous conversation restored]
-
-> Continue with the OAuth implementation
-```
-
----
-
-## 🔐 Security
+## Security
 
 CodeSavant includes comprehensive security features:
 
@@ -697,28 +542,15 @@ CodeSavant includes comprehensive security features:
 
 ### Built-in Protections
 
-- ✅ **SSRF Protection** - Blocks private IPs, localhost in WebFetch
-- ✅ **Path Validation** - Prevents traversal attacks in file operations
-- ✅ **Command Safety** - Array-based command spawning (no shell injection)
-- ✅ **Secrets Handling** - API keys from environment/config only
-- ✅ **Tool Risk Assessment** - High-risk tools require approval
-
-### Best Practices
-
-```bash
-# Use plan mode for exploratory analysis
-codesavant --plan
-
-# Review changes before committing
-codesavant  # (default mode prompts for destructive ops)
-
-# Avoid YOLO mode in production environments
-codesavant --yolo  # ⚠️ Use only in safe environments
-```
+- **SSRF Protection** - Blocks private IPs, localhost in WebFetch
+- **Path Validation** - Prevents traversal attacks in file operations
+- **Command Safety** - Array-based command spawning (no shell injection)
+- **Secrets Handling** - API keys from environment/config only
+- **Tool Risk Assessment** - High-risk tools require approval
 
 ---
 
-## 🚀 Advanced Features
+## Advanced Features
 
 ### Hooks System
 
@@ -791,42 +623,93 @@ command: git restore src/config.ts
 
 ---
 
-## 📊 Context Management
+## Examples
 
-CodeSavant automatically manages context window:
+### Example 1: Autonomous Feature Building
 
 ```bash
-> /context
+codesavant
 
-│ Context Usage:
-│ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 45,230 / 200,000 tokens (23%)
+> /craft user authentication with JWT
+
+│ Starting autonomous craft cycle...
+│
+│ [Research] Spawning 4 parallel research agents...
+│ ✓ Stack research complete
+│ ✓ Architecture research complete
+│ ✓ Security research complete
+│ ✓ Patterns research complete
 │
-│ Breakdown:
-│ - System:    2,450 tokens (5%)
-│ - User:      18,920 tokens (42%)
-│ - Assistant: 20,860 tokens (46%)
-│ - Tools:     3,000 tokens (7%)
+│ [Questioning] I have 2 questions before building:
+│ 1. Do you want refresh token rotation?
+│ 2. Session storage: Redis or in-memory?
 │
-│ Status: ✓ Healthy
+> Yes to refresh tokens, use Redis
+
+│ [Planning] Creating development roadmap...
+│ [Building] Executing 3 plans with atomic commits...
+│ [Verifying] Running quality checks...
+│
+│ ✓ Feature complete: 12 files, 8 commits, all tests passing
 ```
 
-When approaching limits, use `/compact` to compress:
+### Example 2: TDD Workflow
 
 ```bash
-> /compact
+codesavant
 
-│ Compressing conversation history...
-│
-│ Before: 45,230 tokens (23%)
-│ After:  22,100 tokens (11%)
-│
-│ ✓ Compressed 50% of conversation
-│ ✓ Key information preserved
+> /craft proof login endpoint
+
+│ Starting TDD workflow. Writing failing tests first...
+
+[Tool: Write] ✓ Complete
+file: tests/api/login.test.ts
+
+│ ✗ 4 tests failing (expected). Now implementing minimal code to pass...
+
+[Tool: Write] ✓ Complete
+file: src/api/login.ts
+
+│ ✓ All 4 tests passing!
+```
+
+### Example 3: Pipe Mode
+
+```bash
+# Analyze an error log
+cat error.log | codesavant --pipe -p "analyze this error and suggest a fix"
+
+# Review a diff
+git diff | codesavant --pipe -p "review these changes"
+
+# Explain code
+cat complex-algorithm.ts | codesavant --pipe -p "explain this algorithm step by step"
+```
+
+### Example 4: Session Management
+
+```bash
+# Start working on a feature
+codesavant
+
+> I need to add OAuth authentication
+
+│ Let's plan the OAuth implementation...
+│ [Long conversation with code changes]
+
+> /checkpoint oauth-implementation
+
+│ ✓ Checkpoint created: oauth-implementation
+
+> /exit
+
+# Later, resume the session
+codesavant -r
 ```
 
 ---
 
-## 🐛 Troubleshooting
+## Troubleshooting
 
 ### Provider Not Working
 
@@ -845,25 +728,9 @@ codesavant
 │ ✓ All systems operational
 ```
 
-### Session Not Saving
-
-```bash
-# Check permissions
-ls -la ~/.codesavant/
-
-# Should see:
-# drwxr-xr-x sessions/
-# -rw-r--r-- settings.json
-
-# Fix permissions if needed
-chmod 755 ~/.codesavant
-chmod 644 ~/.codesavant/settings.json
-```
-
 ### API Rate Limits
 
 ```bash
-# Check cost/usage
 > /cost
 
 │ Token Usage (This Session):
@@ -876,7 +743,7 @@ chmod 644 ~/.codesavant/settings.json
 
 ---
 
-## 🤝 Contributing
+## Contributing
 
 We welcome contributions! CodeSavant is open source under the MIT license.
 
@@ -906,33 +773,39 @@ bun run build
 codesavant/
 ├── src/
 │   ├── cli.ts              # CLI entry point
-│   ├── repl-ink.tsx        # Interactive REPL
-│   ├── agent.ts            # AI agent orchestration
-│   ├── providers/          # AI provider implementations
-│   ├── tools/              # Built-in tools
-│   ├── skills/             # Craft skills
-│   ├── components/         # UI components
+│   ├── repl-ink.tsx         # Interactive REPL
+│   ├── agent.ts             # AI agent orchestration
+│   ├── providers/           # AI provider implementations
+│   ├── tools/               # Built-in tools
+│   ├── skills/              # Unified skill system
+│   ├── craft/               # Craft skill engine
+│   ├── craft-orchestrator/  # Autonomous build cycle
+│   ├── marketplace/         # Skill marketplace
+│   ├── brain/               # Self-improving brain
+│   ├── design/              # Design intelligence
+│   ├── components/          # UI components
 │   └── ...
-├── tests/                  # Test suite (4,500+ tests)
-├── docs/                   # Documentation
+├── tests/                   # Test suite (360+ test files)
+├── docs/                    # Documentation
 └── package.json
 ```
 
 ---
 
-## 📄 License
+## License
 
 MIT License - see [LICENSE](LICENSE) file for details.
 
 ---
 
-## 🙏 Acknowledgments
+## Acknowledgments
 
 Built with:
 - [Bun](https://bun.sh) - Fast JavaScript runtime
 - [Ink](https://github.com/vadimdemedes/ink) - React for CLIs
 - [Commander.js](https://github.com/tj/commander.js) - CLI framework
 - [Chalk](https://github.com/chalk/chalk) - Terminal styling
+- [Zod](https://zod.dev) - TypeScript schema validation
 
 Powered by:
 - [Anthropic Claude](https://anthropic.com)
@@ -943,26 +816,11 @@ Powered by:
 
 ---
 
-## 📞 Support
+## Support
 
 - **Issues**: [GitHub Issues](https://github.com/vaggarwal039/codesavant/issues)
 - **Discussions**: [GitHub Discussions](https://github.com/vaggarwal039/codesavant/discussions)
-- **Email**: vishal.a.aggarwal@pwc.com
 
 ---
 
-## 🗺️ Roadmap
-
-Coming soon:
-- [ ] Web dashboard for session management
-- [ ] VS Code extension
-- [ ] Custom theme editor
-- [ ] Team collaboration features
-- [ ] Cloud session sync
-- [ ] More AI providers (Cohere, Mistral, etc.)
-
----
-
-**Made with ❤️ by Vishal Aggarwal**
-
-**Star ⭐ this repo if you find it useful!**
+**Made with care by [Vishal Aggarwal](https://github.com/vaggarwal039)**