automagik-forge 0.3.2 → 0.3.5

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,159 +1,510 @@
-# Vibe Kanban
+<p align="center">
+  <a href="https://forge.automag.ik">
+    <img src="frontend/public/forge-clear.svg" alt="Automagik Forge Logo" width="400">
+  </a>
+</p>
+<h2 align="center">The Vibe Coding++™ Platform for Human-AI Development</h2>
+
+<p align="center">
+  <strong>🎯 Where Vibe Coding Meets Structured Execution</strong><br>
+  Works with any AI coding tool through natural language, execute in isolated environments,<br>
+  ship confident code with complete control and visibility
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/automagik-forge"><img alt="npm version" src="https://img.shields.io/npm/v/automagik-forge?style=flat-square&color=00D9FF" /></a>
+  <a href="https://github.com/namastexlabs/automagik-forge/actions"><img alt="Build Status" src="https://img.shields.io/github/actions/workflow/status/namastexlabs/automagik-forge/test.yml?branch=main&style=flat-square" /></a>
+  <a href="https://github.com/namastexlabs/automagik-forge/blob/main/LICENSE"><img alt="License" src="https://img.shields.io/github/license/namastexlabs/automagik-forge?style=flat-square&color=00D9FF" /></a>
+  <a href="https://discord.gg/automagik"><img alt="Discord" src="https://img.shields.io/discord/1234567890?style=flat-square&color=00D9FF&label=discord" /></a>
+</p>
+
+<p align="center">
+  <a href="#-key-features">Features</a> •
+  <a href="#-quick-start">Quick Start</a> •
+  <a href="#-roadmap">Roadmap</a> •
+  <a href="#-development">Development</a> •
+  <a href="#-contributing">Contributing</a>
+</p>
+
+![Automagik Forge Dashboard](frontend/public/screenshot.png)
 
-> A visual project management tool for developers that integrates with git repositories and coding agents like Claude Code and Amp.
+---
+
+## 🚀 What is Automagik Forge?
+
+**Automagik Forge** is the vibe coding++ platform where humans stay in control. It's the structured home for your AI development tasks - plan them yourself or vibe with AI to create them, experiment with different agents to find what works, review everything before shipping. No more code that breaks in 2 weeks.
+
+### 🎭 Vibe Coding++™ Philosophy
+
+**Regular vibe coding problem**: You chat with AI, get code, ship it. Two weeks later? Everything breaks and you can't fix it because you let AI do everything.
+
+**Vibe Coding++™ solution**: Perfect human-AI integration where you:
+
+- 📋 **You Plan Tasks**: Break down work yourself or use AI to help plan
+- 🏠 **Forge is Home**: All tasks live in persistent kanban, not lost in chat history or random .md files scattered across your codebase
+- 🧪 **You Experiment**: Try different agents on same task - see what works best
+- 🎯 **You Choose Agents**: Pick which coding agent AND specialized agent for each task
+- 🔒 **Isolated Attempts**: Each attempt in its own Git worktree - no conflicts
+- 👀 **You Review**: Understand what changed before merging
+- 🚀 **Ship Confident Code**: Code that won't mysteriously break in 2 weeks
+
+### 🚫 Why Regular Vibe Coding Fails
+
+The "just let AI do it" approach creates a ticking time bomb:
+- **No Structure**: Random chat conversations, no task tracking
+- **No Control**: AI makes all decisions, you don't understand the code
+- **No Memory**: What did we build last week? Who knows! Lost in chat history or random .md files
+- **No Experimentation**: Stuck with one agent's approach
+- **The 2-Week Curse**: Code works today, breaks tomorrow, unfixable forever
+
+### ✅ The Vibe Coding++™ Solution
+
+Forge elevates human potential - you orchestrate, AI executes:
+- **You Own the Kanban**: Tasks you create, not AI's whims
+- **You Pick the Agent**: Try Claude, then Gemini, see what works
+- **You Choose Specialization**: Apply "test writer" or "PR reviewer" as needed
+- **Multiple Attempts**: Each task can have multiple attempts with different agents
+- **Git Worktree Isolation**: Every attempt isolated, no conflicts
+- **You Review & Understand**: Know exactly what's changing before merge
+- **MCP Control**: Create/update tasks from your coding agent without leaving your flow
+
+---
+
+## 🌟 Key Features
+
+- **8 AI Coding Agents**: Claude, Cursor CLI, Gemini, Codex, and more - including open-source options
+- **Specialized Agents**: Custom prompts that work with ANY coding agent (test-writer, pr-reviewer, etc.)
+- **Multiple Attempts Per Task**: Try different agents, compare results, choose the best
+- **Parallel Execution**: Run multiple agents simultaneously on different tasks
+- **Git Worktree Isolation**: Every attempt in its own isolated environment
+- **Persistent Kanban Board**: Tasks live forever, not lost in chat history
+- **Task Templates**: Reusable patterns for common workflows
+- **MCP Server Built-in**: Control from any AI coding agent without leaving your flow
+- **Visual Context**: Attach screenshots and diagrams to tasks
+- **Real-time Progress**: Watch agents work, see diffs as they happen
+- **GitHub Integration**: OAuth authentication and repository management
+- **100% Open Source**: Free forever, self-hostable, no vendor lock-in
+
+---
+
+## 🤖 Two Types of Agents, Clear and Simple
+
+> **The Key Distinction:**
+> - **AI Coding Agents** = The AI execution platforms (CLI tools that run AI models)
+> - **Specialized Agents** = Custom prompts that work with ANY coding agent
+> - Example: Your "test-writer" specialized agent can run on Claude today, Gemini tomorrow
+
+### 🛠️ AI Coding Agents Available in Forge
+
+Forge can execute tasks using these AI coding agents - including open-source and LLM-agnostic options:
+
+- **Claude Code** - Anthropic's Claude models
+- **Claude Code Router** - LLM-agnostic, use ANY model instead of Claude
+- **Cursor CLI** - Cursor's CLI agent (separate from their IDE)
+- **Gemini** - Google's Gemini models
+- **Codex** - OpenAI's code models
+- **Amp** - Sourcegraph's code intelligence
+- **OpenCode** - Open-source models, fully local execution
+- **Qwen Code** - Alibaba's open-source models
+
+**The Power:** Not locked to subscriptions - use open-source models, route to any LLM, or bring your own API keys
+
+### 🧪 Task Attempts: Experiment Until It Works
+
+Each task can have multiple attempts - try different approaches:
+
+```yaml
+Task: "Implement user authentication"
+├── Attempt 1: Claude + "security-expert" → Too complex
+├── Attempt 2: Gemini + default → Missing edge cases  
+├── Attempt 3: Cursor + "auth-specialist" → Perfect! ✅
+└── Result: You choose Attempt 3 to merge
+```
+
+**The Power of Attempts:**
+- Each attempt runs in isolated Git worktree
+- Compare different agent outputs side-by-side
+- No commits until YOU approve
+- Learn which agent works best for which task type
+
+**Available Templates:**
+- 🔍 **Code Review**: Multi-agent PR analysis
+- 🐛 **Bug Hunt**: Reproduce → Fix → Test → Document
+- ✨ **Feature Dev**: Design → Implement → Test → Deploy
+- 🔧 **Refactor**: Analyze → Plan → Execute → Verify
+- 📚 **Documentation**: Code → Comments → README → Examples
+
+---
+
+## 📸 Visual Context
+
+Attach screenshots, diagrams, or mockups to any task - agents see the visual context and generate better solutions.
+
+---
+
+## 📡 MCP: Remote Control from Anywhere
+
+Automagik Forge acts as a **Model Context Protocol (MCP) server**, enabling AI coding agents to programmatically manage tasks. Control your Forge task board from your preferred AI coding agent without leaving your flow.
+
+### Typical Workflow
+
+1. **Planning Phase**: Use your AI agent to help brainstorm and plan tasks
+2. **Task Creation**: You (or your agent) creates task cards via MCP
+3. **Bug Discovery**: Find issues while coding? Add them to the backlog via MCP
+4. **Status Updates**: Update task progress as work completes
+5. **Cross-Agent Access**: Any MCP-compatible agent can access your task board
+
+### Example Use Cases
+
+- 🎯 **"Help me plan a complete authentication system with OAuth, JWT, and role-based access"** → You create epic with subtasks
+- 🐛 **"Add bug: API returns 500 on malformed JSON input in /api/users endpoint"** → Create detailed bug card via MCP
+- ✅ **"Mark all database migration tasks as complete and move API tasks to in-progress"** → Batch update statuses via MCP
+- 📋 **"Show me all high-priority tasks that are blocked or have dependencies"** → Query tasks with filters via MCP
+
+### Available MCP Tools
+
+| Tool | Description | Example Usage |
+|------|-------------|---------------|
+| `list_projects` | Get all projects | "List all my active projects" |
+| `list_tasks` | View tasks with filters | "Show pending backend tasks" |
+| `create_task` | Add new task to project | "Create task: Implement Redis caching layer" |
+| `get_task` | Get detailed task info | "Show details for task-abc123" |
+| `update_task` | Modify task properties | "Move task-xyz to in-review" |
+| `delete_task` | Remove completed/obsolete tasks | "Delete all cancelled tasks" |
+
+### Quick Setup
+
+<details>
+<summary><b>Getting Your Project ID</b></summary>
+
+1. Run `npx automagik-forge` to open the UI
+2. Create or select your project
+3. The Project ID (UUID) appears in:
+   - The browser URL: `http://localhost:3000/projects/{PROJECT_ID}/tasks`
+   - The project settings panel
+   - Example: `a1b2c3d4-e5f6-7890-abcd-ef1234567890`
+
+</details>
+
+<details>
+<summary><b>🤖 Claude Code Configuration</b></summary>
+
+1. Open Claude Code settings
+2. Navigate to MCP Servers section
+3. Add Forge server configuration:
+
+```json
+{
+  "mcpServers": {
+    "automagik-forge": {
+      "command": "npx",
+      "args": ["automagik-forge", "mcp-server"],
+      "env": {
+        "PROJECT_ID": "your-project-uuid-here"
+      }
+    }
+  }
+}
+```
+
+4. Restart Claude Code
+5. Use natural language: "Create tasks for implementing a real-time chat feature"
+
+</details>
+
+<details>
+<summary><b>🎯 Cursor Configuration</b></summary>
+
+1. Open Cursor Settings (`Cmd/Ctrl + ,`)
+2. Search for "MCP" in settings
+3. Add to MCP configuration:
+
+```json
+{
+  "mcp.servers": {
+    "automagik-forge": {
+      "command": "npx",
+      "args": ["automagik-forge", "mcp-server"],
+      "projectId": "your-project-uuid-here"
+    }
+  }
+}
+```
+
+4. Reload window (`Cmd/Ctrl + R`)
+5. Tasks are now accessible via `@automagik-forge`
+
+</details>
+
+<details>
+<summary><b>📝 VSCode + Cline Configuration</b></summary>
+
+**For Cline Extension:**
+1. Install Cline from VSCode marketplace
+2. Open Cline settings (`Cmd/Ctrl + Shift + P` → "Cline: Settings")
+3. Add MCP server:
+
+```json
+{
+  "cline.mcpServers": [
+    {
+      "name": "automagik-forge",
+      "command": "npx",
+      "args": ["automagik-forge", "mcp-server"],
+      "env": {
+        "PROJECT_ID": "your-project-uuid-here"
+      }
+    }
+  ]
+}
+```
+
+4. Restart VSCode
+5. Cline can now manage tasks directly
+
+</details>
+
+<details>
+<summary><b>🚀 Roo Code Configuration</b></summary>
+
+1. Open Roo Code preferences
+2. Navigate to Extensions → MCP
+3. Add new server:
+
+```yaml
+servers:
+  automagik-forge:
+    command: npx
+    args: 
+      - automagik-forge
+      - mcp-server
+    environment:
+      PROJECT_ID: your-project-uuid-here
+```
+
+4. Save and restart Roo Code
+5. Access via command palette: "Roo: Create Task"
+
+</details>
+
+<details>
+<summary><b>💎 Gemini CLI Configuration</b></summary>
+
+1. Edit Gemini CLI config file (`~/.gemini/config.json`)
+2. Add MCP server entry:
+
+```json
+{
+  "mcp": {
+    "servers": {
+      "automagik-forge": {
+        "type": "stdio",
+        "command": "npx",
+        "args": ["automagik-forge", "mcp-server"],
+        "env": {
+          "PROJECT_ID": "your-project-uuid-here"
+        }
+      }
+    }
+  }
+}
+```
 
-## Quick Start
+3. Run: `gemini reload-config`
+4. Use: `gemini task create "Implement user dashboard with charts"`
 
-Run vibe kanban instantly without installation:
+</details>
 
+<details>
+<summary><b>🔧 Generic MCP Configuration</b></summary>
+
+For any MCP-compatible tool, use this standard configuration:
+
+```json
+{
+  "command": "npx",
+  "args": ["automagik-forge", "mcp-server"],
+  "env": {
+    "PROJECT_ID": "your-project-uuid-here"
+  }
+}
+```
+
+**Tool-Specific Paths:**
+- Check your tool's MCP or extensions documentation
+- Look for "MCP Servers", "External Tools", or "Model Context Protocol" settings
+- The configuration format is typically JSON or YAML
+
+</details>
+
+---
+
+## 🎭 Vibe Coding++™ Workflows
+
+### Human Orchestration, Not AI Automation
+
+```mermaid
+graph LR
+    A[You Plan Tasks] --> B[You Choose Agents]
+    B --> C[Try Multiple Attempts]
+    C --> D[Compare Results]
+    D --> E[You Review & Decide]
+    E --> F[Ship Clean PRs]
+```
+
+### Example: Building a Feature
 ```bash
-npx vibe-kanban
+You: "I need a user dashboard with charts and real-time updates"
+
+Your Process:
+1. YOU create tasks (or use AI to help plan):
+   ├── Task 1: Design dashboard layout
+   ├── Task 2: Create chart components  
+   ├── Task 3: Build WebSocket service
+   ├── Task 4: Write integration tests
+   └── Task 5: Generate documentation
+
+2. YOU experiment with different agents:
+   Task 2 - Chart Components:
+   ├── Attempt 1: Try Claude → Too abstract
+   ├── Attempt 2: Try Cursor → Good but verbose
+   └── Attempt 3: Try Gemini → Perfect! ✅
+   
+3. YOU review and choose what to merge
+
+The Power: You're in control, not hoping AI gets it right
 ```
 
-This will launch the application locally and open it in your browser automatically.
-
-## What is Vibe Kanban?
-
-Vibe Kanban is a modern project management tool designed specifically for developers. It helps you organize your coding projects with kanban-style task management while providing powerful integrations with git repositories and AI coding agents.
-
-### ✨ Key Features
-
-**🗂️ Project Management**
-- Add git repositories as projects (existing or create new ones)
-- Automatic git integration and repository validation
-- Project search functionality across all files
-- Custom setup and development scripts per project
+---
 
-**📋 Task Management**
-- Create and manage tasks with kanban-style boards
-- Task status tracking (Todo, In Progress, Done)
-- Rich task descriptions and notes
-- Task execution with multiple AI agents
-
-**🤖 AI Agent Integration**
-- **Claude**: Advanced AI coding assistant
-- **Amp**: Powerful development agent
-- **Echo**: Simple testing/debugging agent
-- Create tasks and immediately start agent execution
-- Follow-up task execution for iterative development
-
-**⚡ Development Workflow**
-- Create isolated git worktrees for each task attempt
-- View diffs of changes made by agents
-- Merge successful changes back to main branch
-- Rebase task branches to stay up-to-date
-- Manual file editing and deletion
-- Integrated development server support
-
-**🎛️ Developer Tools**
-- Browse and validate git repositories from filesystem
-- Open task worktrees in your preferred editor (VS Code, Cursor, Windsurf, IntelliJ, Zed)
-- Real-time execution monitoring and process control
-- Stop running processes individually or all at once
-- Sound notifications for task completion
-
-## How It Works
-
-1. **Add Projects**: Import existing git repositories or create new ones
-2. **Create Tasks**: Define what needs to be built or fixed
-3. **Execute with AI**: Let coding agents work on your tasks in isolated environments
-4. **Review Changes**: See exactly what was modified using git diffs
-5. **Merge Results**: Incorporate successful changes into your main codebase
-
-## Core Functionality
-
-Vibe Kanban provides a complete project management experience with these key capabilities:
-
-**Project Repository Management**
-- Full CRUD operations for managing coding projects
-- Automatic git repository detection and validation  
-- Initialize new repositories or import existing ones
-- Project-wide file search functionality
-
-**Task Lifecycle Management**
-- Create, update, and delete tasks with rich descriptions
-- Track task progress through customizable status workflows
-- One-click task creation with immediate AI agent execution
-- Task attempt tracking with detailed execution history
-
-**AI Agent Execution Environment**
-- Isolated git worktrees for safe code experimentation
-- Real-time execution monitoring and activity logging
-- Process management with ability to stop individual or all processes
-- Support for follow-up executions to iterate on solutions
-
-**Code Change Management**
-- View detailed diffs of all changes made during task execution
-- Branch status monitoring to track divergence from main
-- One-click merging of successful changes back to main branch
-- Automatic rebasing to keep task branches up-to-date
-- Manual file deletion and cleanup capabilities
-
-**Development Integration**
-- Open task worktrees directly in your preferred code editor
-- Start and manage development servers for testing changes
-- Browse local filesystem to add new projects
-- Health monitoring for service availability
-
-## Configuration
-
-Vibe Kanban supports customization through its configuration system:
-
-- **Editor Integration**: Choose your preferred code editor
-- **Sound Notifications**: Customize completion sounds
-- **Project Defaults**: Set default setup and development scripts
-
-## Technical Architecture
-
-- **Backend**: Rust with Axum web framework
-- **Frontend**: React with TypeScript
-- **Database**: SQLite for local data storage
-- **Git Integration**: Native git operations for repository management
-- **Process Management**: Tokio-based async execution monitoring
-
-## Requirements
-
-- Node.js (for npx execution)
-- Git (for repository operations)
-- Your preferred code editor (optional, for opening task worktrees)
-
-## Supported Platforms
-
-- Linux x64
-- Windows x64
-- macOS x64 (Intel)
-- macOS ARM64 (Apple Silicon)
-
-## Use Cases
-
-**🔧 Bug Fixes**
-- Create a task describing the bug
-- Let an AI agent analyze and fix the issue
-- Review the proposed changes
-- Merge if satisfied, or provide follow-up instructions
-
-**✨ Feature Development**
-- Break down features into manageable tasks
-- Use agents for initial implementation
-- Iterate with follow-up executions
-- Test using integrated development servers
-
-**🚀 Project Setup**
-- Bootstrap new projects with AI assistance
-- Set up development environments
-- Configure build and deployment scripts
-
-**📚 Code Documentation**
-- Generate documentation for existing code
-- Create README files and API documentation
-- Maintain up-to-date project information
+## 📊 Vibe Coding vs Vibe Coding++™
+
+| Feature | Forge (Vibe Coding++™) | Lovable (Regular Vibe Coding) |
+|---------|----------------------|-------------------------------|
+| **Human Control** | ✅ You orchestrate every decision | ❌ AI acts autonomously |
+| **Task Persistence** | ✅ Kanban board - tasks live forever | ❌ Lost in chat conversations |
+| **Multiple Attempts** | ✅ Try different agents per task | ❌ One AI, one approach |
+| **8 AI Coding Agents** | ✅ Claude, Cursor CLI, Gemini, etc. | ❌ Single AI model |
+| **Specialized Agents** | ✅ Custom prompts for any agent | ❌ Fixed behavior |
+| **Git Worktree Isolation** | ✅ Every attempt isolated | ❌ Direct code changes |
+| **MCP Server** | ✅ 6 tools for remote control | ❌ No external integration |
+| **2-Week Curse Protection** | ✅ You understand the code | ❌ AI black box magic |
+| **Code Review** | ✅ Review before merge | ❌ Auto-applies changes |
+| **Visual Context** | ✅ Attach screenshots to tasks | ✅ Can generate images |
+| **Open Source** | ✅ 100% open-source | ❌ Proprietary |
+| **Pricing Model** | ✅ Free forever | 💰 Usage-based credits |
+| **Self-Hostable** | ✅ Your infrastructure | ❌ Cloud-only |
 
 ---
 
-**Ready to supercharge your development workflow?**
+## 📦 Quick Start
+
+### Prerequisites
+
+- Node.js 18+ and pnpm 8+
+- Authenticated AI coding agent (Claude Code, Gemini CLI, etc.)
+- Git repository to work with
+
+### Installation
 
 ```bash
-npx vibe-kanban
+# Install globally
+npm install -g automagik-forge
+
+# Or run directly with npx
+npx automagik-forge
 ```
 
-*Start managing your projects with the power of AI coding agents today!*
+### First Run
+
+```bash
+# Navigate to your project
+cd your-project
+
+# Launch Forge
+automagik-forge
+
+# Open browser to http://localhost:3000
+```
+
+---
+
+## 🛠️ Development
+
+Interested in contributing or building from source? Check out our [Developer Guide](DEVELOPER.md) for detailed instructions on:
+- Setting up the development environment
+- Building from source
+- Running tests
+- Database migrations
+- Architecture details
+
+---
+
+## 🗺️ Roadmap
+
+### Completed ✅
+- [x] Multi-agent orchestration
+- [x] Kanban task management
+- [x] Git worktree isolation
+- [x] MCP server implementation
+- [x] Real-time progress streaming
+
+### Next Up 🚀
+- [ ] **Wish System & Genie** - Natural language wishes become epics with subtasks, interactive AI assistant navigates the UI
+- [ ] **Bilateral sync** - Two-way sync with GitHub Issues, Jira, Notion, Linear
+- [ ] **Epics & Subtasks** - Hierarchical task organization with dependency management
+- [ ] Agent performance analytics
+- [ ] Team collaboration features
+- [ ] Community templates
+- [ ] Integration with CI/CD pipelines
+
+---
+
+## 🤝 Contributing
+
+We love contributions! However, to maintain project coherence:
+
+1. **Discuss First**: Open an issue before starting work
+2. **Align with Roadmap**: Ensure changes fit our vision
+3. **Follow Standards**: Match existing code patterns
+4. **Test Thoroughly**: Include tests for new features
+5. **Document Well**: Update docs with your changes
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.
+---
+
+## 🙏 Acknowledgments
+
+Special thanks to:
+- Vibe Kanban team, for inspiring us to build Forge.
+- All our early adopters and contributors
+
+---
+
+## 📄 License
+
+MIT License - see [LICENSE](LICENSE) file for details.
+
+---
+
+## 🔗 Links
+
+- **Website**: [forge.automag.ik](https://forge.automag.ik)
+- **NPM Package**: [npmjs.com/package/automagik-forge](https://www.npmjs.com/package/automagik-forge)
+- **GitHub**: [github.com/namastexlabs/automagik-forge](https://github.com/namastexlabs/automagik-forge)
+- **Discord**: [discord.gg/automagik](https://discord.gg/automagik)
+- **Twitter**: [@automagikdev](https://twitter.com/automagikdev)
+
+---
+
+<p align="center">
+  <strong>🚀 Stop the 2-week curse. Start shipping code you actually understand.</strong><br>
+  <strong>Vibe Coding++™ - Where Human Control Meets AI Power</strong><br><br>
+  <a href="https://github.com/namastexlabs/automagik-forge">Star us on GitHub</a> • 
+  <a href="https://discord.gg/automagik">Join our Discord</a> • 
+</p>
+
+<p align="center">
+  Made with ❤️ by <a href="https://namastex.ai">Namastex Labs</a><br>
+  <em>AI that elevates human potential, not replaces it</em>
+</p>

package/{bin → npx-cli/bin}/cli.js

@@ -98,8 +98,9 @@ function extractAndRun(baseName, launch) {
 }
 
 if (isMcpMode) {
-  extractAndRun("vibe-kanban-mcp", (bin) => {
-    const proc = spawn(bin, [], { stdio: "inherit" });
+  extractAndRun("automagik-forge-mcp", (bin) => {
+    const env = { ...process.env };
+    const proc = spawn(bin, [], { stdio: "inherit", env });
     proc.on("exit", (c) => process.exit(c || 0));
     proc.on("error", (e) => {
       console.error("❌ MCP server error:", e.message);
@@ -113,12 +114,19 @@ if (isMcpMode) {
   });
 } else {
   console.log(`📦 Extracting automagik-forge...`);
-  extractAndRun("vibe-kanban", (bin) => {
+  extractAndRun("automagik-forge", (bin) => {
     console.log(`🚀 Launching automagik-forge...`);
+    
+    // Set default environment variables if not already set
+    const env = { ...process.env };
+    if (!env.BACKEND_PORT && !env.PORT) {
+      env.BACKEND_PORT = "8887";
+    }
+    
     if (platform === "win32") {
-      execSync(`"${bin}"`, { stdio: "inherit" });
+      execSync(`"${bin}"`, { stdio: "inherit", env });
     } else {
-      execSync(`"${bin}"`, { stdio: "inherit" });
+      execSync(`"${bin}"`, { stdio: "inherit", env });
     }
   });
 }

package/npx-cli/dist/linux-arm64/README.txt

@@ -0,0 +1 @@
+Binaries for linux-arm64 need to be built on that platform

package/npx-cli/dist/macos-arm64/README.txt

@@ -0,0 +1 @@
+Binaries for macos-arm64 need to be built on that platform

package/npx-cli/dist/macos-x64/README.txt

@@ -0,0 +1 @@
+Binaries for macos-x64 need to be built on that platform

package/npx-cli/dist/windows-arm64/README.txt

@@ -0,0 +1 @@
+Binaries for windows-arm64 need to be built on that platform

package/npx-cli/dist/windows-x64/README.txt

@@ -0,0 +1 @@
+Binaries for windows-x64 need to be built on that platform

package/package.json

@@ -1,17 +1,62 @@
 {
   "name": "automagik-forge",
+  "version": "0.3.5",
   "private": false,
-  "version": "0.3.2",
-  "main": "index.js",
   "bin": {
-    "automagik-forge": "bin/cli.js"
+    "automagik-forge": "npx-cli/bin/cli.js"
   },
-  "keywords": [],
-  "author": "namastex",
-  "license": "",
-  "description": "NPX wrapper around automagik-forge and automagik-forge-mcp",
   "files": [
-    "dist",
-    "bin"
-  ]
+    "npx-cli/bin/cli.js",
+    "npx-cli/dist/**"
+  ],
+  "scripts": {
+    "check": "npm run frontend:check && npm run backend:check",
+    "dev": "export FRONTEND_PORT=$(node scripts/setup-dev-environment.js frontend) && export BACKEND_PORT=$(node scripts/setup-dev-environment.js backend) && concurrently \"npm run backend:dev:watch\" \"npm run frontend:dev\"",
+    "test:npm": "./test-npm-package.sh",
+    "frontend:dev": "cd frontend && npm run dev -- --port ${FRONTEND_PORT:-3000} --host",
+    "frontend:check": "cd frontend && npm run check",
+    "backend:dev": "BACKEND_PORT=$(node scripts/setup-dev-environment.js backend) npm run backend:dev:watch",
+    "backend:check": "cargo check",
+    "backend:dev:watch": "DISABLE_WORKTREE_ORPHAN_CLEANUP=1 RUST_LOG=debug cargo watch -w crates -x 'run --bin server'",
+    "generate-types": "cargo run --bin generate_types",
+    "generate-types:check": "cargo run --bin generate_types -- --check",
+    "prepare-db": "node scripts/prepare-db.js",
+    "build:npx": "bash ./local-build.sh",
+    "prepack": "npm run build:npx"
+  },
+  "devDependencies": {
+    "@tailwindcss/container-queries": "^0.1.1",
+    "concurrently": "^8.2.2",
+    "vite": "^6.3.5"
+  },
+  "engines": {
+    "node": ">=18",
+    "pnpm": ">=8"
+  },
+  "packageManager": "pnpm@10.12.4+sha512.5ea8b0deed94ed68691c9bad4c955492705c5eeb8a87ef86bc62c74a26b037b08ff9570f108b2e4dbd1dd1a9186fea925e527f141c648e85af45631074680184",
+  "description": "Vibe coding orchestrator for human-AI development. You create tasks, choose agents, experiment with approaches, ship code you understand.",
+  "keywords": [
+    "vibe-coding",
+    "ai-pair-programming",
+    "human-ai-collaboration",
+    "mcp-server",
+    "task-orchestration",
+    "agent-agnostic",
+    "git-worktree-isolation",
+    "kanban-for-ai",
+    "claude-code",
+    "cursor-cli",
+    "gemini",
+    "coding-agents"
+  ],
+  "author": "Genie <genie@namastex.ai>",
+  "homepage": "https://forge.automag.ik",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/namastexlabs/automagik-forge.git"
+  },
+  "bugs": {
+    "url": "https://github.com/namastexlabs/automagik-forge/issues"
+  },
+  "license": "MIT"
 }