monty-autonomous-fullstack-dev-multillm 1.0.0

package/LICENSE

@@ -0,0 +1,81 @@
+Creative Commons Attribution-NonCommercial 4.0 International License (CC BY-NC 4.0)
+
+Copyright (c) 2025 Dobeu Tech Solutions LLC
+
+This work is licensed under the Creative Commons Attribution-NonCommercial 4.0
+International License. To view a copy of this license, visit:
+https://creativecommons.org/licenses/by-nc/4.0/
+
+================================================================================
+                           LICENSE SUMMARY
+================================================================================
+
+You are free to:
+
+  SHARE - Copy and redistribute the material in any medium or format
+  ADAPT - Remix, transform, and build upon the material
+
+Under the following terms:
+
+  ATTRIBUTION - You must give appropriate credit to Dobeu Tech Solutions LLC,
+  provide a link to the license, and indicate if changes were made. You may
+  do so in any reasonable manner, but not in any way that suggests the
+  licensor endorses you or your use.
+
+  NON-COMMERCIAL - You may not use the material for commercial purposes.
+  Commercial purposes include, but are not limited to:
+    - Selling the software or derivatives
+    - Using the software to provide paid services
+    - Incorporating the software into commercial products
+    - Any use intended for or directed toward commercial advantage or
+      monetary compensation
+
+  NO ADDITIONAL RESTRICTIONS - You may not apply legal terms or technological
+  measures that legally restrict others from doing anything the license permits.
+
+================================================================================
+                         IMPORTANT NOTICES
+================================================================================
+
+1. OWNERSHIP
+   This software and all associated intellectual property rights are owned by
+   Dobeu Tech Solutions LLC. The "Monty Full-Stack Agent" name, branding, and
+   related trademarks are property of Dobeu Tech Solutions LLC.
+
+2. WARRANTY DISCLAIMER
+   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+   IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+   FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+
+3. LIMITATION OF LIABILITY
+   IN NO EVENT SHALL DOBEU TECH SOLUTIONS LLC BE LIABLE FOR ANY CLAIM, DAMAGES
+   OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+   ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+   DEALINGS IN THE SOFTWARE.
+
+4. COMMERCIAL LICENSING
+   For commercial use, please contact Dobeu Tech Solutions LLC for licensing
+   options at: jeremyw@dobeu.net or https://github.com/dobeutech
+
+   Company Website: https://dobeu.net
+   Terms of Service: https://dobeu.net/tos
+   Privacy Policy: https://dobeu.net/privacy
+
+5. CONTRIBUTIONS
+   By contributing to this project, you agree that your contributions will be
+   licensed under the same CC BY-NC 4.0 license.
+
+================================================================================
+                              ATTRIBUTION
+================================================================================
+
+When using this software, please include the following attribution:
+
+"Powered by Monty Full-Stack Agent by Dobeu Tech Solutions LLC"
+or
+"Built with Monty Full-Stack Agent (https://github.com/dobeutech/monty-ai-fullstackdev-coder)"
+
+================================================================================
+
+For the full legal text of CC BY-NC 4.0, visit:
+https://creativecommons.org/licenses/by-nc/4.0/legalcode

package/README.md

@@ -0,0 +1,608 @@
+# Monty Full-Stack Agent
+
+[![npm version](https://img.shields.io/npm/v/monty-autonomous-fullstack-dev-multillm.svg)](https://www.npmjs.com/package/monty-autonomous-fullstack-dev-multillm)
+[![License: CC BY-NC 4.0](https://img.shields.io/badge/License-CC%20BY--NC%204.0-lightgrey.svg)](https://creativecommons.org/licenses/by-nc/4.0/)
+[![Node.js Version](https://img.shields.io/node/v/monty-autonomous-fullstack-dev-multillm.svg)](https://nodejs.org)
+
+An autonomous full-stack development agent powered by the Claude Agent SDK. Takes your project from **idea to production** with incremental progress tracking across multiple sessions.
+
+Based on [Anthropic's best practices](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents) for long-running agents.
+
+## Installation
+
+### Prerequisites
+
+- **Node.js** >= 18.0.0
+- **Claude Code Subscription** or **Anthropic API Key** - Sign in with `monty login` or get a key at [console.anthropic.com](https://console.anthropic.com)
+
+### Windows Installation
+
+```powershell
+# 1. Install Node.js (if not installed)
+# Download from https://nodejs.org or use winget:
+winget install OpenJS.NodeJS.LTS
+
+# 2. Install Monty globally
+npm install -g monty-autonomous-fullstack-dev-multillm
+
+# 3. Authenticate (RECOMMENDED - interactive login)
+monty login
+
+# 3b. Or set API key manually (PowerShell - current session)
+$env:ANTHROPIC_API_KEY="your-api-key-here"
+
+# 3c. Or set API key permanently (PowerShell - persistent)
+[Environment]::SetEnvironmentVariable("ANTHROPIC_API_KEY", "your-api-key-here", "User")
+
+# 4. Verify installation
+monty --help
+```
+
+### macOS Installation
+
+```bash
+# 1. Install Node.js (if not installed)
+# Using Homebrew (recommended):
+brew install node
+
+# Or download from https://nodejs.org
+
+# 2. Install Monty globally
+npm install -g monty-autonomous-fullstack-dev-multillm
+
+# 3. Authenticate (RECOMMENDED - interactive login)
+monty login
+
+# 3b. Or set API key manually (current session)
+export ANTHROPIC_API_KEY="your-api-key-here"
+
+# 3c. Or set API key permanently (add to ~/.zshrc or ~/.bash_profile)
+echo 'export ANTHROPIC_API_KEY="your-api-key-here"' >> ~/.zshrc
+source ~/.zshrc
+
+# 4. Verify installation
+monty --help
+```
+
+### Linux Installation
+
+```bash
+# 1. Install Node.js (if not installed)
+# Ubuntu/Debian:
+curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
+sudo apt-get install -y nodejs
+
+# Fedora/RHEL:
+sudo dnf install nodejs
+
+# Arch Linux:
+sudo pacman -S nodejs npm
+
+# Or use nvm (all distros):
+curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
+nvm install 20
+nvm use 20
+
+# 2. Install Monty globally
+npm install -g monty-autonomous-fullstack-dev-multillm
+
+# 3. Authenticate (RECOMMENDED - interactive login)
+monty login
+
+# 3b. Or set API key manually (current session)
+export ANTHROPIC_API_KEY="your-api-key-here"
+
+# 3c. Or set API key permanently (add to ~/.bashrc or ~/.zshrc)
+echo 'export ANTHROPIC_API_KEY="your-api-key-here"' >> ~/.bashrc
+source ~/.bashrc
+
+# 4. Verify installation
+monty --help
+```
+
+### Run Directly with npx (No Install)
+
+```bash
+# Works on all platforms - no installation needed
+npx monty-autonomous-fullstack-dev-multillm --help
+
+# Initialize a new project
+npx monty-autonomous-fullstack-dev-multillm init --spec="Build a todo app with React and Supabase"
+
+# Continue development
+npx monty-autonomous-fullstack-dev-multillm code
+```
+
+### Project-Level Installation
+
+```bash
+# Add to an existing project
+npm install --save-dev monty-autonomous-fullstack-dev-multillm
+
+# Add scripts to package.json:
+# "scripts": {
+#   "agent:init": "monty init",
+#   "agent:code": "monty code"
+# }
+```
+
+### Alternative Package Managers
+
+```bash
+# Yarn
+yarn global add monty-autonomous-fullstack-dev-multillm
+
+# pnpm
+pnpm add -g monty-autonomous-fullstack-dev-multillm
+
+# Bun
+bun add -g monty-autonomous-fullstack-dev-multillm
+```
+
+## Quick Start
+
+### Starting a New Project
+
+```bash
+# Create a new directory
+mkdir my-awesome-app && cd my-awesome-app
+
+# Initialize with your idea
+monty init --spec="Build a modern todo app with React, TypeScript, Tailwind CSS, and Supabase backend. Include user authentication, real-time updates, and dark mode."
+
+# Continue development
+monty code
+```
+
+### Using with an Existing Codebase
+
+```bash
+# Navigate to your existing project
+cd your-existing-project
+
+# Initialize Monty (it will detect your tech stack)
+monty init --spec="Complete the authentication system and add user dashboard"
+
+# The agent will analyze your codebase and create a feature list
+# Continue with incremental development
+monty code
+```
+
+### Resuming Work
+
+```bash
+# Check project status
+monty status
+
+# Continue where you left off
+monty code
+
+# Add specific context for this session
+monty code --context="Focus on fixing the login bug in auth.ts"
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `monty` | Auto-detect mode (shows help if not initialized) |
+| `monty init` | Initialize a new project with feature list |
+| `monty code` | Continue incremental development |
+| `monty status` | Show project progress and feature status |
+| `monty setup` | Set up Monty in current directory |
+| `monty --help` | Show detailed help |
+
+### Authentication Commands
+
+| Command | Description |
+|---------|-------------|
+| `monty login` | Sign in with Claude Code subscription or Anthropic API key |
+| `monty logout` | Sign out and clear stored credentials |
+| `monty whoami` | Show current authentication status |
+
+### Options
+
+| Option | Description |
+|--------|-------------|
+| `--spec="..."` | Project specification for initialization |
+| `--context="..."` | Additional context for coding session |
+| `--help, -h` | Show help |
+| `--version, -v` | Show version |
+
+## How It Works
+
+### Two-Agent Architecture
+
+Monty uses a sophisticated two-agent system:
+
+```
+┌─────────────────┐     First Run     ┌─────────────────┐
+│                 │ ───────────────── │   Initializer   │
+│   Your Idea     │                   │      Agent      │
+│                 │                   │                 │
+└─────────────────┘                   └────────┬────────┘
+                                               │
+                                               │ Creates
+                                               ▼
+                                      ┌─────────────────┐
+                                      │ .agent/         │
+                                      │ - feature_list  │
+                                      │ - progress.txt  │
+                                      └────────┬────────┘
+                                               │
+┌─────────────────┐   Subsequent      ┌────────▼────────┐
+│   Production    │ ◄──────────────── │    Coding       │
+│   Ready App     │     Runs          │    Agent        │
+│                 │                   │                 │
+└─────────────────┘                   └─────────────────┘
+```
+
+### Initializer Agent (First Run)
+
+When you first run `monty init`:
+
+1. Analyzes your project specification
+2. Detects existing tech stack (if any)
+3. Generates comprehensive `feature_list.json` with ALL features marked as `passes: false`
+4. Creates `claude-progress.txt` for session bridging
+5. Makes initial git commit
+
+### Coding Agent (Every Session)
+
+When you run `monty code`:
+
+1. Reads progress file and git logs to understand current state
+2. Runs health checks and validates environment
+3. Selects highest-priority failing feature
+4. Implements feature incrementally
+5. Tests using browser automation
+6. Updates feature status and commits changes
+7. Logs progress for the next session
+
+## Feature Detection
+
+Monty automatically detects and adapts to:
+
+**Frameworks:** React, Next.js, Vue, Svelte, Angular, Vanilla JS
+**Build Tools:** Vite, Webpack, Rollup, Turbopack
+**Testing:** Vitest, Jest, Playwright, Cypress
+**Backend:** Supabase, Express, Fastify, Next.js API
+**Databases:** PostgreSQL, MySQL, MongoDB, SQLite
+**Styling:** Tailwind CSS, CSS Modules, Styled Components, SASS
+**Package Managers:** npm, yarn, pnpm, bun
+
+## Files Created
+
+```
+your-project/
+└── .agent/                        # Monty's working directory
+    ├── feature_list.json          # Feature tracking (immutable structure)
+    ├── claude-progress.txt        # Session logs for context bridging
+    ├── error-log.json             # Error history for recovery
+    └── checkpoints.json           # Recovery checkpoints
+```
+
+## Feature List Format
+
+```json
+{
+  "project": {
+    "name": "My App",
+    "description": "A modern todo application",
+    "created_at": "2025-01-15T00:00:00Z",
+    "stack": ["react", "typescript", "tailwind", "supabase"]
+  },
+  "features": [
+    {
+      "id": "feat-001",
+      "category": "functional",
+      "priority": 1,
+      "description": "User can create new todo items",
+      "steps": [
+        "Navigate to main interface",
+        "Click 'Add Todo' button",
+        "Enter todo text",
+        "Verify todo appears in list"
+      ],
+      "passes": false,
+      "last_tested": null,
+      "notes": ""
+    }
+  ]
+}
+```
+
+### Feature Categories
+
+- **functional** - Core application logic and features
+- **ui** - User interface elements, styling, responsiveness
+- **integration** - API calls, data flow, third-party services
+- **performance** - Loading times, optimizations
+- **accessibility** - Keyboard navigation, screen readers, ARIA
+
+## Poka-yoke Safeguards
+
+The framework enforces these rules to prevent common agent failures:
+
+1. **Cannot delete features** from the feature list
+2. **Cannot modify test steps** (steps are immutable after creation)
+3. **Cannot modify descriptions** after creation
+4. **Must verify via browser** before marking features as passing
+5. **Must commit changes** before ending a session
+
+## Best Practices
+
+Based on [Anthropic's documentation](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents):
+
+| Best Practice | Implementation |
+|--------------|----------------|
+| Incremental Progress | Work on ONE feature at a time |
+| Clean State | Always leave codebase in committable state |
+| Browser Verification | Test as a human user would |
+| Progress Logging | Document everything for the next session |
+| Git Discipline | Descriptive commits for every change |
+
+## Failure Modes Addressed
+
+| Problem | Solution |
+|---------|----------|
+| Agent declares victory too early | Feature list requires ALL features to pass |
+| Leaves environment with bugs | Must verify via browser before marking done |
+| Marks features done prematurely | Browser automation required for verification |
+| Spends time figuring out setup | Automated project detection and init scripts |
+| Loses context between sessions | claude-progress.txt + git logs |
+
+## Configuration
+
+For advanced customization, modify `src/config/agent-config.ts`:
+
+```typescript
+export const agentConfig = {
+  paths: {
+    agentDir: '.agent',
+    featureList: '.agent/feature_list.json',
+    progressFile: '.agent/claude-progress.txt',
+  },
+  tools: {
+    initializer: ['Read', 'Write', 'Bash', 'Glob'],
+    coding: ['Read', 'Edit', 'Bash', 'Glob', 'Browser'],
+  },
+  permissionMode: 'acceptEdits',
+  session: {
+    maxRetries: 3,
+    autoCommit: true,
+  },
+};
+```
+
+## Development
+
+### Building from Source
+
+```bash
+# Clone the repository
+git clone https://github.com/dobeutech/monty-ai-fullstackdev-coder.git
+cd monty-ai-fullstackdev-coder
+
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Run in development mode
+npm run dev
+```
+
+### Project Structure
+
+```
+monty-fullstack-agent/
+├── bin/
+│   └── cli.js                 # CLI entry point
+├── src/
+│   ├── agents/
+│   │   ├── initializer.ts     # First-run setup agent
+│   │   ├── coding.ts          # Incremental progress agent
+│   │   └── prompts/           # System prompts
+│   ├── config/
+│   │   ├── agent-config.ts    # Shared configuration
+│   │   └── mcp-config.ts      # Browser automation settings
+│   ├── utils/                 # Utility modules
+│   └── index.ts               # Main entry point
+├── templates/                 # File templates
+└── scripts/                   # Init scripts
+```
+
+## Authentication
+
+Monty supports multiple authentication methods:
+
+### 1. Auto-Detection (Primary)
+
+If you are already authenticated with [Claude Code](https://docs.anthropic.com/claude/docs/claude-code), Monty will automatically detect and import your credentials.
+
+```bash
+monty login
+# ✓ Found Claude Code credentials!
+# ✓ Imported successfully
+```
+
+### 2. Interactive Login
+
+```bash
+# Sign in with Claude Code subscription (OAuth) or Anthropic API key
+monty login
+
+# Check your authentication status
+monty whoami
+
+# Sign out when needed
+monty logout
+```
+
+The interactive login will:
+1. First attempt to auto-detect Claude Code credentials
+2. If not found, offer OAuth login (opens browser) or manual API Key entry
+3. Validate your credentials
+4. Store them securely in `~/.monty/credentials.json`
+
+### 3. Environment Variables
+
+You can also authenticate using environment variables:
+
+| Variable | Description | Required |
+|----------|-------------|----------|
+| `ANTHROPIC_API_KEY` | Anthropic API key | No (if using login) |
+| `ANTHROPIC_SUBSCRIPTION_KEY` | Claude Code subscription key | No (if using login) |
+| `FORCE_INIT` | Force initialization mode | No |
+
+### Authentication Priority
+
+When multiple credential sources exist, the priority is:
+1. `ANTHROPIC_SUBSCRIPTION_KEY` environment variable
+2. `ANTHROPIC_API_KEY` environment variable
+3. Subscription key from `~/.monty/credentials.json`
+4. API key from `~/.monty/credentials.json`
+
+## Troubleshooting
+
+### Authentication Issues
+
+#### "Authentication required"
+
+You need to authenticate before using Monty. Choose one of these methods:
+
+**Option 1: Auto-detect (recommended)** - If you have Claude Code CLI installed:
+```bash
+# First, authenticate with Claude Code
+claude login
+
+# Then let Monty auto-detect your credentials
+monty login
+```
+
+**Option 2: Manual API Key**:
+```bash
+# Interactive login
+monty login
+# Select "API Key" method
+# Paste your key from console.anthropic.com
+
+# OR set environment variable
+export ANTHROPIC_API_KEY="sk-ant-..."
+```
+
+**Option 3: Environment Variable** (for automation/CI):
+```bash
+export ANTHROPIC_API_KEY="your-key-here"
+monty init --spec="your project"
+```
+
+#### "Token expired"
+
+Monty automatically refreshes expired tokens if you authenticated via Claude Code CLI.
+
+If auto-refresh fails, re-authenticate:
+```bash
+monty logout
+monty login
+```
+
+#### "Could not validate credentials"
+
+Your API key may be invalid or expired:
+
+1. **For Claude Code subscription**: Run `claude login` to refresh, then `monty login`
+2. **For API key**: Get a new key from [console.anthropic.com/settings/keys](https://console.anthropic.com/settings/keys)
+3. **Check your key**: Run `monty whoami` to verify authentication status
+
+#### Debugging Authentication
+
+Check your current authentication status:
+```bash
+monty whoami
+```
+
+This command shows:
+- Authentication method (Claude subscription or API key)
+- Token expiration (if applicable)
+- Key preview (first 8 and last 4 characters)
+- Credential source (environment variable or file)
+
+If authentication is working but agents fail:
+- Verify network connectivity to api.anthropic.com
+- Check that credentials file permissions are correct:
+  - Unix/Mac: `ls -la ~/.monty/credentials.json` (should be `-rw-------`)
+  - Windows: Only current user should have access
+- Try setting API key directly: `export ANTHROPIC_API_KEY="your-key"`
+
+### Other Issues
+
+#### "Feature list not found"
+
+Run `monty init` first to initialize the project:
+```bash
+monty init --spec="Build a todo app with React"
+```
+
+#### "Permission denied"
+
+Ensure the CLI is executable:
+```bash
+# Unix/Mac
+chmod +x $(which monty)
+
+# Windows (run as Administrator if needed)
+# No action usually required on Windows
+```
+
+#### Agent fails to start
+
+1. Check authentication: `monty whoami`
+2. Verify Node.js version: `node --version` (must be >= 18.0.0)
+3. Check for error messages in the output
+4. Try running with explicit auth: `ANTHROPIC_API_KEY="your-key" monty code`
+
+## Contributing
+
+Contributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) for details.
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+## References
+
+- [Effective Harnesses for Long-Running Agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)
+- [Building Effective Agents](https://www.anthropic.com/engineering/building-effective-agents)
+- [Demystifying Evals for AI Agents](https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents)
+- [Claude Agent SDK](https://github.com/anthropics/claude-agent-sdk)
+
+## License
+
+This project is licensed under the **Creative Commons Attribution-NonCommercial 4.0 International License (CC BY-NC 4.0)**.
+
+**You are free to:**
+- Share and redistribute the material
+- Adapt, remix, and build upon the material
+
+**Under these terms:**
+- **Attribution** - You must give appropriate credit to Dobeu Tech Solutions LLC
+- **NonCommercial** - You may not use the material for commercial purposes
+
+**For commercial licensing:**
+- Email: jeremyw@dobeu.net
+- Website: [dobeu.net](https://dobeu.net)
+- Terms of Service: [dobeu.net/tos](https://dobeu.net/tos)
+- Privacy Policy: [dobeu.net/privacy](https://dobeu.net/privacy)
+
+See [LICENSE](LICENSE) for full details.
+
+---
+
+Copyright (c) 2025 **[Dobeu Tech Solutions LLC](https://dobeu.net)** - All Rights Reserved
+
+Made with Claude Agent SDK