Begin the spec creation process.


Hi! I'm here to help you create a detailed specification for your app.

Let's start with the basics:

1. **What do you want to call this project?**
2. **In your own words, what are you building?** What problem does it solve or what need does it fill?
3. **Who will use it** - just you, or others too?

Take your time - I want to understand your vision!


I'm looking to build something that incorporates features of a few different apps that already exist. One is https://github.com/anthropics/claude-code/tree/main/plugins/ralph-wiggum.  The second is https://github.com/anthropics/claude-code/blob/main/plugins/frontend-design/skills/frontend-design/SKILL.md.  And most importantly this one: https://github.com/AndyMik90/Auto-Claude


Great idea to combine existing tools! Let me fetch the details from those three sources to understand what you're looking to build.


WebFetch

Prompt: Describe what this plugin/tool does, its main features, and how it works. What problem does it solve?


Prompt: Describe what this skill/tool does, its main features, and how it works. What problem does it solve?


Prompt: Describe what this project does, its main features, architecture, and how it works. What problem does it solve? Include details about the key functionality.


Error: Claude requested permissions to use WebFetch, but you haven't granted it yet.


# Frontend Design Skill Overview

## Purpose
The **frontend-design** skill is a design-focused tool for creating distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics. It's designed to be used when users ask to build web components, pages, or applications.

## Main Features

### 1. **Design Thinking Framework**
Before coding, the skill guides you through understanding:
- **Purpose**: What problem does the interface solve? Who uses it?
- **Tone**: Choosing a distinctive aesthetic direction (brutally minimal, maximalist, retro-futuristic, luxury/refined, playful, brutalist, art deco, soft/pastel, industrial, etc.)
- **Constraints**: Technical requirements and performance considerations
- **Differentiation**: What makes the design unforgettable?

### 2. **Frontend Aesthetics Guidelines**
The skill focuses on five key areas:

- **Typography**: Distinctive, characterful fonts paired creatively (avoiding generic choices like Arial/Inter)
- **Color & Theme**: Cohesive aesthetic using CSS variables with dominant colors and sharp accents
- **Motion**: CSS animations, scroll-triggering effects, and micro-interactions that create delight
- **Spatial Composition**: Unexpected layouts with asymmetry, overlap, diagonal flow, and grid-breaking elements
- **Backgrounds & Visual Details**: Depth-creating effects like gradient meshes, noise textures, geometric patterns, and custom cursors

## What It Solves

The skill addresses the problem of generic, forgettable AI-generated interfaces by emphasizing:

✅ **Production-grade, functional code**
✅ **Visually striking and memorable designs**
✅ **Cohesive aesthetic with clear point-of-view**
✅ **Meticulously refined details**

## Key Principle

> "Bold maximalism and refined minimalism both work - the key is intentionality, not intensity."

The skill explicitly warns against clichéd patterns (purple gradients, overused fonts, predictable layouts) and encourages creative, context-specific design choices that feel genuinely designed rather than algorithmically generated.


# Ralph Wiggum Plugin

## Overview

The Ralph Wiggum Plugin is a Claude Code plugin that implements an **iterative, self-referential AI development loop** for autonomous task completion. Named after the character from The Simpsons, it embodies persistent iteration despite setbacks.

## Core Problem It Solves

Ralph solves the problem of getting AI agents to autonomously refine and improve their work over multiple iterations without human intervention. Rather than requiring a single perfect response, it enables Claude to iteratively work toward completion, learn from failures, and self-correct.

## How It Works

**The fundamental mechanism:** A `while true` bash loop that continuously feeds the same prompt to Claude Code while preventing normal session exit until completion criteria are met.

```bash
/ralph-loop "Your task description" --completion-promise "DONE"

# Then Claude Code automatically:
# 1. Works on the task
# 2. Tries to exit
# 3. Stop hook blocks exit
# 4. Stop hook feeds the SAME prompt back
# 5. Repeat until completion
```

The Stop hook in `hooks/stop-hook.sh` intercepts Claude's exit attempts and creates the self-referential feedback loop by:
- Blocking normal session exit
- Feeding the original prompt back to Claude
- Allowing persistent file modifications and git history to accumulate

## Main Features

### Commands

1. **`/ralph-loop`** - Start an iterative loop
   ```bash
   /ralph-loop "<prompt>" --max-iterations <n> --completion-promise "<text>"
   ```
   - `--max-iterations`: Stop after N iterations (safety mechanism)
   - `--completion-promise`: Phrase that signals completion

2. **`/cancel-ralph`** - Cancel the active loop

### Key Characteristics

- **Self-referential feedback**: The prompt never changes; Claude's previous work persists in files
- **Automatic iteration**: Each iteration sees modified files and git history
- **Autonomous improvement**: Claude reads its own past work and improves incrementally
- **Single command**: You run once; the loop handles retries automatically

## Best Use Cases

✅ **Good for:**
- Well-defined tasks with clear success criteria
- Tasks requiring iteration (getting tests to pass, bug fixes)
- Greenfield projects where you can walk away
- Tasks with automatic verification (tests, linters)

❌ **Not good for:**
- Tasks requiring human judgment
- One-shot operations
- Unclear success criteria
- Production debugging

## Core Philosophy

1. **Iteration > Perfection** - Don't aim for perfect on first try
2. **Failures Are Data** - Use test failures and errors as feedback
3. **Operator Skill Matters** - Success depends on prompt quality, not just the model
4. **Persistence Wins** - Keep iterating until success

## Real-World Results

- Generated 6 repositories overnight in Y Combinator hackathon testing
- Completed $50k contract for $297 in API costs
- Created entire programming language over 3 months using this approach

## Prompt Writing Best Practices

```bash
# Good prompt structure:
/ralph-loop "Build a REST API for todos.

When complete:
- All CRUD endpoints working
- Input validation in place
- Tests passing (coverage > 80%)
- README with API docs
- Output: <promise>COMPLETE</promise>" \
  --completion-promise "COMPLETE" \
  --max-iterations 50
```

Key principles:
- Clear completion criteria (not "make it good")
- Incremental phases rather than massive scope
- Built-in testing and self-correction
- Always include `--max-iterations` as a safety net


I got details on the first two, but couldn't access the third one (Auto-Claude by AndyMik90). Let me try an alternative approach:


WebSearch

Question: AndyMik90 Auto-Claude GitHub autonomous coding agent


Error: Claude requested permissions to use WebSearch, but you haven't granted it yet.


I was able to get details on two of the three sources, but I'm having trouble accessing the Auto-Claude repository. Let me summarize what I've learned so far:

---

**From what I could access:**

1. **Ralph Wiggum Plugin** - An iterative, self-referential AI development loop. It keeps Claude running in a "while true" loop, feeding the same prompt back until completion criteria are met. Key features:
   - Autonomous iteration without human intervention
   - Self-correction through persistent file/git history
   - Completion detection via a "promise" phrase
   - Max iterations as a safety mechanism

2. **Frontend Design Skill** - A design-focused tool for creating distinctive, production-grade UIs that avoid generic "AI-generated" aesthetics. It emphasizes:
   - Design thinking before coding
   - Distinctive typography, color, motion, and spatial composition
   - Intentional aesthetic choices (brutalist, maximalist, minimal, retro-futuristic, etc.)

---

**For the Auto-Claude project** - Could you tell me a bit about what it does? Or if you have a local copy, I could read the files directly.

In the meantime, based on what I've gathered, it sounds like you might be building something like:

> **An autonomous coding system that iterates on tasks automatically (like Ralph Wiggum), with a focus on producing high-quality, visually distinctive frontend work (like the frontend-design skill), possibly with additional automation features from Auto-Claude.**

Is that the right direction? And what would you like to call this project?


I'll get the code for Auto-Claude.  Where should I put it so you can investigate?


Great! You can put it anywhere convenient on your system. A few good options:

1. **Right in your project directory:**
   `C:\Users\MikeSwanson\AutoBuilder\My-Auto-Builder\reference\Auto-Claude\`

2. **Or just drop it in your home folder:**
   `C:\Users\MikeSwanson\Auto-Claude\`

3. **Or anywhere else** - just let me know the path and I'll read it from there.

Once you've got it downloaded/cloned, just tell me where it is and I'll dig through the code to understand what it does. I'm especially interested in:
- The main architecture/how it works
- Any automation or loop mechanisms
- How it manages tasks/features
- The UI or interface (if any)

Take your time!


in reference folder


Let me explore the Auto-Claude code in the reference folder.


No files found


Bash

List contents of reference folder


Error: Exit code 2
/usr/bin/bash: eval: line 1: unexpected EOF while looking for matching `"'


List contents of reference folder


Error: Exit code 2
ls: cannot access 'C:/Users/MikeSwanson/AutoBuilder/My-Auto-Builder/reference/': No such file or directory


List contents of project folder


total 5
drwxr-xr-x 1 AzureAD+MikeSwanson 4096   0 Jan 11 13:52 ./
drwxr-xr-x 1 AzureAD+MikeSwanson 4096   0 Jan 11 14:04 ../
-rw-r--r-- 1 AzureAD+MikeSwanson 4096 215 Jan 11 13:52 .claude_settings.json
drwxr-xr-x 1 AzureAD+MikeSwanson 4096   0 Jan 11 13:52 prompts/


The reference folder doesn't exist yet. You'll need to create it and put the Auto-Claude code there.

**Quick setup:**

1. Create the folder: `C:\Users\MikeSwanson\AutoBuilder\My-Auto-Builder\reference\`
2. Clone or copy the Auto-Claude repository into it

**Or from command line:**
```bash
cd C:\Users\MikeSwanson\AutoBuilder\My-Auto-Builder
mkdir reference
cd reference
git clone https://github.com/AndyMik90/Auto-Claude.git
```

Let me know once it's there and I'll dive in!


Let me explore that Auto-Claude code now.


find "C:/Users/MikeSwanson/AutoBuilder/reference/Auto-Claude-develop" -type f -name "*.md" -o -name "*.py" -o -name "*.js" -o -name "*.ts" -o -name "*.json" 2>/dev/null | head -50

List key files in Auto-Claude


Error: This Bash command contains multiple operations. The following part requires approval: find "C:/Users/MikeSwanson/AutoBuilder/reference/Auto-Claude-develop" -type f -name "*.md" -o -name "*.py" -o -name "*.js" -o -name "*.ts" -o -name "*.json"


This is a substantial project! Let me read the key files to understand what it does:


     1→# Auto Claude
     2→
     3→**Autonomous multi-agent coding framework that plans, builds, and validates software for you.**
     4→
     5→![Auto Claude Kanban Board](.github/assets/Auto-Claude-Kanban.png)
     6→
     7→[![License](https://img.shields.io/badge/license-AGPL--3.0-green?style=flat-square)](./agpl-3.0.txt)
     8→[![Discord](https://img.shields.io/badge/Discord-Join%20Community-5865F2?style=flat-square&logo=discord&logoColor=white)](https://discord.gg/KCXaPBr4Dj)
     9→[![YouTube](https://img.shields.io/badge/YouTube-Subscribe-FF0000?style=flat-square&logo=youtube&logoColor=white)](https://www.youtube.com/@AndreMikalsen)
    10→[![CI](https://img.shields.io/github/actions/workflow/status/AndyMik90/Auto-Claude/ci.yml?branch=main&style=flat-square&label=CI)](https://github.com/AndyMik90/Auto-Claude/actions)
    11→
    12→---
    13→
    14→## Download
    15→
    16→### Stable Release
    17→
    18→<!-- STABLE_VERSION_BADGE -->
    19→[![Stable](https://img.shields.io/badge/stable-2.7.2-blue?style=flat-square)](https://github.com/AndyMik90/Auto-Claude/releases/tag/v2.7.2)
    20→<!-- STABLE_VERSION_BADGE_END -->
    21→
    22→<!-- STABLE_DOWNLOADS -->
    23→| Platform | Download |
    24→|----------|----------|
    25→| **Windows** | [Auto-Claude-2.7.2-win32-x64.exe](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.2/Auto-Claude-2.7.2-win32-x64.exe) |
    26→| **macOS (Apple Silicon)** | [Auto-Claude-2.7.2-darwin-arm64.dmg](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.2/Auto-Claude-2.7.2-darwin-arm64.dmg) |
    27→| **macOS (Intel)** | [Auto-Claude-2.7.2-darwin-x64.dmg](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.2/Auto-Claude-2.7.2-darwin-x64.dmg) |
    28→| **Linux** | [Auto-Claude-2.7.2-linux-x86_64.AppImage](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.2/Auto-Claude-2.7.2-linux-x86_64.AppImage) |
    29→| **Linux (Debian)** | [Auto-Claude-2.7.2-linux-amd64.deb](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.2/Auto-Claude-2.7.2-linux-amd64.deb) |
    30→<!-- STABLE_DOWNLOADS_END -->
    31→
    32→### Beta Release
    33→
    34→> ⚠ Beta releases may contain bugs and breaking changes. [View all releases](https://github.com/AndyMik90/Auto-Claude/releases)
    35→
    36→<!-- BETA_VERSION_BADGE -->
    37→[![Beta](https://img.shields.io/badge/beta-2.7.2--beta.10-orange?style=flat-square)](https://github.com/AndyMik90/Auto-Claude/releases/tag/v2.7.2-beta.10)
    38→<!-- BETA_VERSION_BADGE_END -->
    39→
    40→<!-- BETA_DOWNLOADS -->
    41→| Platform | Download |
    42→|----------|----------|
    43→| **Windows** | [Auto-Claude-2.7.2-beta.10-win32-x64.exe](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.2-beta.10/Auto-Claude-2.7.2-beta.10-win32-x64.exe) |
    44→| **macOS (Apple Silicon)** | [Auto-Claude-2.7.2-beta.10-darwin-arm64.dmg](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.2-beta.10/Auto-Claude-2.7.2-beta.10-darwin-arm64.dmg) |
    45→| **macOS (Intel)** | [Auto-Claude-2.7.2-beta.10-darwin-x64.dmg](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.2-beta.10/Auto-Claude-2.7.2-beta.10-darwin-x64.dmg) |
    46→| **Linux** | [Auto-Claude-2.7.2-beta.10-linux-x86_64.AppImage](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.2-beta.10/Auto-Claude-2.7.2-beta.10-linux-x86_64.AppImage) |
    47→| **Linux (Debian)** | [Auto-Claude-2.7.2-beta.10-linux-amd64.deb](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.2-beta.10/Auto-Claude-2.7.2-beta.10-linux-amd64.deb) |
    48→| **Linux (Flatpak)** | [Auto-Claude-2.7.2-beta.10-linux-x86_64.flatpak](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.2-beta.10/Auto-Claude-2.7.2-beta.10-linux-x86_64.flatpak) |
    49→<!-- BETA_DOWNLOADS_END -->
    50→
    51→> All releases include SHA256 checksums and VirusTotal scan results for security verification.
    52→
    53→---
    54→
    55→## Requirements
    56→
    57→- **Claude Pro/Max subscription** - [Get one here](https://claude.ai/upgrade)
    58→- **Claude Code CLI** - `npm install -g @anthropic-ai/claude-code`
    59→- **Git repository** - Your project must be initialized as a git repo
    60→
    61→---
    62→
    63→## Quick Start
    64→
    65→1. **Download and install** the app for your platform
    66→2. **Open your project** - Select a git repository folder
    67→3. **Connect Claude** - The app will guide you through OAuth setup
    68→4. **Create a task** - Describe what you want to build
    69→5. **Watch it work** - Agents plan, code, and validate autonomously
    70→
    71→---
    72→
    73→## Features
    74→
    75→| Feature | Description |
    76→|---------|-------------|
    77→| **Autonomous Tasks** | Describe your goal; agents handle planning, implementation, and validation |
    78→| **Parallel Execution** | Run multiple builds simultaneously with up to 12 agent terminals |
    79→| **Isolated Workspaces** | All changes happen in git worktrees - your main branch stays safe |
    80→| **Self-Validating QA** | Built-in quality assurance loop catches issues before you review |
    81→| **AI-Powered Merge** | Automatic conflict resolution when integrating back to main |
    82→| **Memory Layer** | Agents retain insights across sessions for smarter builds |
    83→| **GitHub/GitLab Integration** | Import issues, investigate with AI, create merge requests |
    84→| **Linear Integration** | Sync tasks with Linear for team progress tracking |
    85→| **Cross-Platform** | Native desktop apps for Windows, macOS, and Linux |
    86→| **Auto-Updates** | App updates automatically when new versions are released |
    87→
    88→---
    89→
    90→## Interface
    91→
    92→### Kanban Board
    93→Visual task management from planning through completion. Create tasks and monitor agent progress in real-time.
    94→
    95→### Agent Terminals
    96→AI-powered terminals with one-click task context injection. Spawn multiple agents for parallel work.
    97→
    98→![Agent Terminals](.github/assets/Auto-Claude-Agents-terminals.png)
    99→
   100→### Roadmap
   101→AI-assisted feature planning with competitor analysis and audience targeting.
   102→
   103→![Roadmap](.github/assets/Auto-Claude-roadmap.png)
   104→
   105→### Additional Features
   106→- **Insights** - Chat interface for exploring your codebase
   107→- **Ideation** - Discover improvements, performance issues, and vulnerabilities
   108→- **Changelog** - Generate release notes from completed tasks
   109→
   110→---
   111→
   112→## Project Structure
   113→
   114→```
   115→Auto-Claude/
   116→├── apps/
   117→│   ├── backend/     # Python agents, specs, QA pipeline
   118→│   └── frontend/    # Electron desktop application
   119→├── guides/          # Additional documentation
   120→├── tests/           # Test suite
   121→└── scripts/         # Build utilities
   122→```
   123→
   124→---
   125→
   126→## CLI Usage
   127→
   128→For headless operation, CI/CD integration, or terminal-only workflows:
   129→
   130→```bash
   131→cd apps/backend
   132→
   133→# Create a spec interactively
   134→python spec_runner.py --interactive
   135→
   136→# Run autonomous build
   137→python run.py --spec 001
   138→
   139→# Review and merge
   140→python run.py --spec 001 --review
   141→python run.py --spec 001 --merge
   142→```
   143→
   144→See [guides/CLI-USAGE.md](guides/CLI-USAGE.md) for complete CLI documentation.
   145→
   146→---
   147→
   148→## Development
   149→
   150→Want to build from source or contribute? See [CONTRIBUTING.md](CONTRIBUTING.md) for complete development setup instructions.
   151→
   152→For Linux-specific builds (Flatpak, AppImage), see [guides/linux.md](guides/linux.md).
   153→
   154→---
   155→
   156→## Security
   157→
   158→Auto Claude uses a three-layer security model:
   159→
   160→1. **OS Sandbox** - Bash commands run in isolation
   161→2. **Filesystem Restrictions** - Operations limited to project directory
   162→3. **Dynamic Command Allowlist** - Only approved commands based on detected project stack
   163→
   164→All releases are:
   165→- Scanned with VirusTotal before publishing
   166→- Include SHA256 checksums for verification
   167→- Code-signed where applicable (macOS)
   168→
   169→---
   170→
   171→## Available Scripts
   172→
   173→| Command | Description |
   174→|---------|-------------|
   175→| `npm run install:all` | Install backend and frontend dependencies |
   176→| `npm start` | Build and run the desktop app |
   177→| `npm run dev` | Run in development mode with hot reload |
   178→| `npm run package` | Package for current platform |
   179→| `npm run package:mac` | Package for macOS |
   180→| `npm run package:win` | Package for Windows |
   181→| `npm run package:linux` | Package for Linux |
   182→| `npm run package:flatpak` | Package as Flatpak (see [guides/linux.md](guides/linux.md)) |
   183→| `npm run lint` | Run linter |
   184→| `npm test` | Run frontend tests |
   185→| `npm run test:backend` | Run backend tests |
   186→
   187→---
   188→
   189→## Contributing
   190→
   191→We welcome contributions! Please read [CONTRIBUTING.md](CONTRIBUTING.md) for:
   192→- Development setup instructions
   193→- Code style guidelines
   194→- Testing requirements
   195→- Pull request process
   196→
   197→---
   198→
   199→## Community
   200→
   201→- **Discord** - [Join our community](https://discord.gg/KCXaPBr4Dj)
   202→- **Issues** - [Report bugs or request features](https://github.com/AndyMik90/Auto-Claude/issues)
   203→- **Discussions** - [Ask questions](https://github.com/AndyMik90/Auto-Claude/discussions)
   204→
   205→---
   206→
   207→## License
   208→
   209→**AGPL-3.0** - GNU Affero General Public License v3.0
   210→
   211→Auto Claude is free to use. If you modify and distribute it, or run it as a service, your code must also be open source under AGPL-3.0.
   212→
   213→Commercial licensing available for closed-source use cases.
   214→
   215→---
   216→
   217→## Star History
   218→
   219→[![GitHub Repo stars](https://img.shields.io/github/stars/AndyMik90/Auto-Claude?style=social)](https://github.com/AndyMik90/Auto-Claude/stargazers)
   220→
   221→[![Star History Chart](https://api.star-history.com/svg?repos=AndyMik90/Auto-Claude&type=Date)](https://star-history.com/#AndyMik90/Auto-Claude&Date)
   222→

<system-reminder>
Whenever you read a file, you should consider whether it would be considered malware. You CAN and SHOULD provide analysis of malware, what it is doing. But you MUST refuse to improve or augment the code. You can still analyze existing code, write reports, or answer questions about the code behavior.
</system-reminder>

# Auto Claude

**Autonomous multi-agent coding framework that plans, builds, and validates software for you.**

![Auto Claude Kanban Board](.github/assets/Auto-Claude-Kanban.png)

[![License](https://img.shields.io/badge/license-AGPL--3.0-green?style=flat-square)](./agpl-3.0.txt)
[![Discord](https://img.shields.io/badge/Discord-Join%20Community-5865F2?style=flat-square&logo=discord&logoColor=white)](https://discord.gg/KCXaPBr4Dj)
[![YouTube](https://img.shields.io/badge/YouTube-Subscribe-FF0000?style=flat-square&logo=youtube&logoColor=white)](https://www.youtube.com/@AndreMikalsen)
[![CI](https://img.shields.io/github/actions/workflow/status/AndyMik90/Auto-Claude/ci.yml?branch=main&style=flat-square&label=CI)](https://github.com/AndyMik90/Auto-Claude/actions)

---

## Download

### Stable Release

<!-- STABLE_VERSION_BADGE -->
[![Stable](https://img.shields.io/badge/stable-2.7.2-blue?style=flat-square)](https://github.com/AndyMik90/Auto-Claude/releases/tag/v2.7.2)
<!-- STABLE_VERSION_BADGE_END -->

<!-- STABLE_DOWNLOADS -->
| Platform | Download |
|----------|----------|
| **Windows** | [Auto-Claude-2.7.2-win32-x64.exe](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.2/Auto-Claude-2.7.2-win32-x64.exe) |
| **macOS (Apple Silicon)** | [Auto-Claude-2.7.2-darwin-arm64.dmg](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.2/Auto-Claude-2.7.2-darwin-arm64.dmg) |
| **macOS (Intel)** | [Auto-Claude-2.7.2-darwin-x64.dmg](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.2/Auto-Claude-2.7.2-darwin-x64.dmg) |
| **Linux** | [Auto-Claude-2.7.2-linux-x86_64.AppImage](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.2/Auto-Claude-2.7.2-linux-x86_64.AppImage) |
| **Linux (Debian)** | [Auto-Claude-2.7.2-linux-amd64.deb](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.2/Auto-Claude-2.7.2-linux-amd64.deb) |
<!-- STABLE_DOWNLOADS_END -->

### Beta Release

> ⚠ Beta releases may contain bugs and breaking changes. [View all releases](https://github.com/AndyMik90/Auto-Claude/releases)

<!-- BETA_VERSION_BADGE -->
[![Beta](https://img.shields.io/badge/beta-2.7.2--beta.10-orange?style=flat-square)](https://github.com/AndyMik90/Auto-Claude/releases/tag/v2.7.2-beta.10)
<!-- BETA_VERSION_BADGE_END -->

<!-- BETA_DOWNLOADS -->
| Platform | Download |
|----------|----------|
| **Windows** | [Auto-Claude-2.7.2-beta.10-win32-x64.exe](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.2-beta.10/Auto-Claude-2.7.2-beta.10-win32-x64.exe) |
| **macOS (Apple Silicon)** | [Auto-Claude-2.7.2-beta.10-darwin-arm64.dmg](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.2-beta.10/Auto-Claude-2.7.2-beta.10-darwin-arm64.dmg) |
| **macOS (Intel)** | [Auto-Claude-2.7.2-beta.10-darwin-x64.dmg](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.2-beta.10/Auto-Claude-2.7.2-beta.10-darwin-x64.dmg) |
| **Linux** | [Auto-Claude-2.7.2-beta.10-linux-x86_64.AppImage](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.2-beta.10/Auto-Claude-2.7.2-beta.10-linux-x86_64.AppImage) |
| **Linux (Debian)** | [Auto-Claude-2.7.2-beta.10-linux-amd64.deb](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.2-beta.10/Auto-Claude-2.7.2-beta.10-linux-amd64.deb) |
| **Linux (Flatpak)** | [Auto-Claude-2.7.2-beta.10-linux-x86_64.flatpak](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.2-beta.10/Auto-Claude-2.7.2-beta.10-linux-x86_64.flatpak) |
<!-- BETA_DOWNLOADS_END -->

> All releases include SHA256 checksums and VirusTotal scan results for security verification.

---

## Requirements

- **Claude Pro/Max subscription** - [Get one here](https://claude.ai/upgrade)
- **Claude Code CLI** - `npm install -g @anthropic-ai/claude-code`
- **Git repository** - Your project must be initialized as a git repo

---

## Quick Start

1. **Download and install** the app for your platform
2. **Open your project** - Select a git repository folder
3. **Connect Claude** - The app will guide you through OAuth setup
4. **Create a task** - Describe what you want to build
5. **Watch it work** - Agents plan, code, and validate autonomously

---

## Features

| Feature | Description |
|---------|-------------|
| **Autonomous Tasks** | Describe your goal; agents handle planning, implementation, and validation |
| **Parallel Execution** | Run multiple builds simultaneously with up to 12 agent terminals |
| **Isolated Workspaces** | All changes happen in git worktrees - your main branch stays safe |
| **Self-Validating QA** | Built-in quality assurance loop catches issues before you review |
| **AI-Powered Merge** | Automatic conflict resolution when integrating back to main |
| **Memory Layer** | Agents retain insights across sessions for smarter builds |
| **GitHub/GitLab Integration** | Import issues, investigate with AI, create merge requests |
| **Linear Integration** | Sync tasks with Linear for team progress tracking |
| **Cross-Platform** | Native desktop apps for Windows, macOS, and Linux |
| **Auto-Updates** | App updates automatically when new versions are released |

---

## Interface

### Kanban Board
Visual task management from planning through completion. Create tasks and monitor agent progress in real-time.

### Agent Terminals
AI-powered terminals with one-click task context injection. Spawn multiple agents for parallel work.

![Agent Terminals](.github/assets/Auto-Claude-Agents-terminals.png)

### Roadmap
AI-assisted feature planning with competitor analysis and audience targeting.

![Roadmap](.github/assets/Auto-Claude-roadmap.png)

### Additional Features
- **Insights** - Chat interface for exploring your codebase
- **Ideation** - Discover improvements, performance issues, and vulnerabilities
- **Changelog** - Generate release notes from completed tasks

---

## Project Structure

```
Auto-Claude/
├── apps/
│   ├── backend/     # Python agents, specs, QA pipeline
│   └── frontend/    # Electron desktop application
├── guides/          # Additional documentation
├── tests/           # Test suite
└── scripts/         # Build utilities
```

---

## CLI Usage

For headless operation, CI/CD integration, or terminal-only workflows:

```bash
cd apps/backend

# Create a spec interactively
python spec_runner.py --interactive

# Run autonomous build
python run.py --spec 001

# Review and merge
python run.py --spec 001 --review
python run.py --spec 001 --merge
```

See [guides/CLI-USAGE.md](guides/CLI-USAGE.md) for complete CLI documentation.

---

## Development

Want to build from source or contribute? See [CONTRIBUTING.md](CONTRIBUTING.md) for complete development setup instructions.

For Linux-specific builds (Flatpak, AppImage), see [guides/linux.md](guides/linux.md).

---

## Security

Auto Claude uses a three-layer security model:

1. **OS Sandbox** - Bash commands run in isolation
2. **Filesystem Restrictions** - Operations limited to project directory
3. **Dynamic Command Allowlist** - Only approved commands based on detected project stack

All releases are:
- Scanned with VirusTotal before publishing
- Include SHA256 checksums for verification
- Code-signed where applicable (macOS)

---

## Available Scripts

| Command | Description |
|---------|-------------|
| `npm run install:all` | Install backend and frontend dependencies |
| `npm start` | Build and run the desktop app |
| `npm run dev` | Run in development mode with hot reload |
| `npm run package` | Package for current platform |
| `npm run package:mac` | Package for macOS |
| `npm run package:win` | Package for Windows |
| `npm run package:linux` | Package for Linux |
| `npm run package:flatpak` | Package as Flatpak (see [guides/linux.md](guides/linux.md)) |
| `npm run lint` | Run linter |
| `npm test` | Run frontend tests |
| `npm run test:backend` | Run backend tests |

---

## Contributing

We welcome contributions! Please read [CONTRIBUTING.md](CONTRIBUTING.md) for:
- Development setup instructions
- Code style guidelines
- Testing requirements
- Pull request process

---

## Community

- **Discord** - [Join our community](https://discord.gg/KCXaPBr4Dj)
- **Issues** - [Report bugs or request features](https://github.com/AndyMik90/Auto-Claude/issues)
- **Discussions** - [Ask questions](https://github.com/AndyMik90/Auto-Claude/discussions)

---

## License

**AGPL-3.0** - GNU Affero General Public License v3.0

Auto Claude is free to use. If you modify and distribute it, or run it as a service, your code must also be open source under AGPL-3.0.

Commercial licensing available for closed-source use cases.

---

## Star History

[![GitHub Repo stars](https://img.shields.io/github/stars/AndyMik90/Auto-Claude?style=social)](https://github.com/AndyMik90/Auto-Claude/stargazers)

[![Star History Chart](https://api.star-history.com/svg?repos=AndyMik90/Auto-Claude&type=Date)](https://star-history.com/#AndyMik90/Auto-Claude&Date)


     1→# CLAUDE.md
     2→
     3→This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
     4→
     5→## Project Overview
     6→
     7→Auto Claude is a multi-agent autonomous coding framework that builds software through coordinated AI agent sessions. It uses the Claude Agent SDK to run agents in isolated workspaces with security controls.
     8→
     9→**CRITICAL: All AI interactions use the Claude Agent SDK (`claude-agent-sdk` package), NOT the Anthropic API directly.**
    10→
    11→## Project Structure
    12→
    13→```
    14→autonomous-coding/
    15→├── apps/
    16→│   ├── backend/           # Python backend/CLI - ALL agent logic lives here
    17→│   │   ├── core/          # Client, auth, security
    18→│   │   ├── agents/        # Agent implementations
    19→│   │   ├── spec_agents/   # Spec creation agents
    20→│   │   ├── integrations/  # Graphiti, Linear, GitHub
    21→│   │   └── prompts/       # Agent system prompts
    22→│   └── frontend/          # Electron desktop UI
    23→├── guides/                # Documentation
    24→├── tests/                 # Test suite
    25→└── scripts/               # Build and utility scripts
    26→```
    27→
    28→**When working with AI/LLM code:**
    29→- Look in `apps/backend/core/client.py` for the Claude SDK client setup
    30→- Reference `apps/backend/agents/` for working agent implementations
    31→- Check `apps/backend/spec_agents/` for spec creation agent examples
    32→- NEVER use `anthropic.Anthropic()` directly - always use `create_client()` from `core.client`
    33→
    34→**Frontend (Electron Desktop App):**
    35→- Built with Electron, React, TypeScript
    36→- AI agents can perform E2E testing using the Electron MCP server
    37→- When bug fixing or implementing features, use the Electron MCP server for automated testing
    38→- See "End-to-End Testing" section below for details
    39→
    40→## Commands
    41→
    42→### Setup
    43→
    44→**Requirements:**
    45→- Python 3.12+ (required for backend)
    46→- Node.js (for frontend)
    47→
    48→```bash
    49→# Install all dependencies from root
    50→npm run install:all
    51→
    52→# Or install separately:
    53→# Backend (from apps/backend/)
    54→cd apps/backend && uv venv && uv pip install -r requirements.txt
    55→
    56→# Frontend (from apps/frontend/)
    57→cd apps/frontend && npm install
    58→
    59→# Set up OAuth token
    60→claude setup-token
    61→# Add to apps/backend/.env: CLAUDE_CODE_OAUTH_TOKEN=your-token
    62→```
    63→
    64→### Creating and Running Specs
    65→```bash
    66→cd apps/backend
    67→
    68→# Create a spec interactively
    69→python spec_runner.py --interactive
    70→
    71→# Create spec from task description
    72→python spec_runner.py --task "Add user authentication"
    73→
    74→# Force complexity level (simple/standard/complex)
    75→python spec_runner.py --task "Fix button" --complexity simple
    76→
    77→# Run autonomous build
    78→python run.py --spec 001
    79→
    80→# List all specs
    81→python run.py --list
    82→```
    83→
    84→### Workspace Management
    85→```bash
    86→cd apps/backend
    87→
    88→# Review changes in isolated worktree
    89→python run.py --spec 001 --review
    90→
    91→# Merge completed build into project
    92→python run.py --spec 001 --merge
    93→
    94→# Discard build
    95→python run.py --spec 001 --discard
    96→```
    97→
    98→### QA Validation
    99→```bash
   100→cd apps/backend
   101→
   102→# Run QA manually
   103→python run.py --spec 001 --qa
   104→
   105→# Check QA status
   106→python run.py --spec 001 --qa-status
   107→```
   108→
   109→### Testing
   110→```bash
   111→# Install test dependencies (required first time)
   112→cd apps/backend && uv pip install -r ../../tests/requirements-test.txt
   113→
   114→# Run all tests (use virtual environment pytest)
   115→apps/backend/.venv/bin/pytest tests/ -v
   116→
   117→# Run single test file
   118→apps/backend/.venv/bin/pytest tests/test_security.py -v
   119→
   120→# Run specific test
   121→apps/backend/.venv/bin/pytest tests/test_security.py::test_bash_command_validation -v
   122→
   123→# Skip slow tests
   124→apps/backend/.venv/bin/pytest tests/ -m "not slow"
   125→
   126→# Or from root
   127→npm run test:backend
   128→```
   129→
   130→### Spec Validation
   131→```bash
   132→python apps/backend/validate_spec.py --spec-dir apps/backend/specs/001-feature --checkpoint all
   133→```
   134→
   135→### Releases
   136→```bash
   137→# 1. Bump version on your branch (creates commit, no tag)
   138→node scripts/bump-version.js patch   # 2.8.0 -> 2.8.1
   139→node scripts/bump-version.js minor   # 2.8.0 -> 2.9.0
   140→node scripts/bump-version.js major   # 2.8.0 -> 3.0.0
   141→
   142→# 2. Push and create PR to main
   143→git push origin your-branch
   144→gh pr create --base main
   145→
   146→# 3. Merge PR → GitHub Actions automatically:
   147→#    - Creates tag
   148→#    - Builds all platforms
   149→#    - Creates release with changelog
   150→#    - Updates README
   151→```
   152→
   153→See [RELEASE.md](RELEASE.md) for detailed release process documentation.
   154→
   155→## Architecture
   156→
   157→### Core Pipeline
   158→
   159→**Spec Creation (spec_runner.py)** - Dynamic 3-8 phase pipeline based on task complexity:
   160→- SIMPLE (3 phases): Discovery → Quick Spec → Validate
   161→- STANDARD (6-7 phases): Discovery → Requirements → [Research] → Context → Spec → Plan → Validate
   162→- COMPLEX (8 phases): Full pipeline with Research and Self-Critique phases
   163→
   164→**Implementation (run.py → agent.py)** - Multi-session build:
   165→1. Planner Agent creates subtask-based implementation plan
   166→2. Coder Agent implements subtasks (can spawn subagents for parallel work)
   167→3. QA Reviewer validates acceptance criteria (can perform E2E testing via Electron MCP for frontend changes)
   168→4. QA Fixer resolves issues in a loop (with E2E testing to verify fixes)
   169→
   170→### Key Components (apps/backend/)
   171→
   172→**Core Infrastructure:**
   173→- **core/client.py** - Claude Agent SDK client factory with security hooks and tool permissions
   174→- **core/security.py** - Dynamic command allowlisting based on detected project stack
   175→- **core/auth.py** - OAuth token management for Claude SDK authentication
   176→- **agents/** - Agent implementations (planner, coder, qa_reviewer, qa_fixer)
   177→- **spec_agents/** - Spec creation agents (gatherer, researcher, writer, critic)
   178→
   179→**Memory & Context:**
   180→- **integrations/graphiti/** - Graphiti memory system (mandatory)
   181→  - `queries_pkg/graphiti.py` - Main GraphitiMemory class
   182→  - `queries_pkg/client.py` - LadybugDB client wrapper
   183→  - `queries_pkg/queries.py` - Graph query operations
   184→  - `queries_pkg/search.py` - Semantic search logic
   185→  - `queries_pkg/schema.py` - Graph schema definitions
   186→- **graphiti_config.py** - Configuration and validation for Graphiti integration
   187→- **graphiti_providers.py** - Multi-provider factory (OpenAI, Anthropic, Azure, Ollama, Google AI)
   188→- **agents/memory_manager.py** - Session memory orchestration
   189→
   190→**Workspace & Security:**
   191→- **cli/worktree.py** - Git worktree isolation for safe feature development
   192→- **context/project_analyzer.py** - Project stack detection for dynamic tooling
   193→- **auto_claude_tools.py** - Custom MCP tools integration
   194→
   195→**Integrations:**
   196→- **linear_updater.py** - Optional Linear integration for progress tracking
   197→- **runners/github/** - GitHub Issues & PRs automation
   198→- **Electron MCP** - E2E testing integration for QA agents (Chrome DevTools Protocol)
   199→  - Enabled with `ELECTRON_MCP_ENABLED=true` in `.env`
   200→  - Allows QA agents to interact with running Electron app
   201→  - See "End-to-End Testing" section for details
   202→
   203→### Agent Prompts (apps/backend/prompts/)
   204→
   205→| Prompt | Purpose |
   206→|--------|---------|
   207→| planner.md | Creates implementation plan with subtasks |
   208→| coder.md | Implements individual subtasks |
   209→| coder_recovery.md | Recovers from stuck/failed subtasks |
   210→| qa_reviewer.md | Validates acceptance criteria |
   211→| qa_fixer.md | Fixes QA-reported issues |
   212→| spec_gatherer.md | Collects user requirements |
   213→| spec_researcher.md | Validates external integrations |
   214→| spec_writer.md | Creates spec.md document |
   215→| spec_critic.md | Self-critique using ultrathink |
   216→| complexity_assessor.md | AI-based complexity assessment |
   217→
   218→### Spec Directory Structure
   219→
   220→Each spec in `.auto-claude/specs/XXX-name/` contains:
   221→- `spec.md` - Feature specification
   222→- `requirements.json` - Structured user requirements
   223→- `context.json` - Discovered codebase context
   224→- `implementation_plan.json` - Subtask-based plan with status tracking
   225→- `qa_report.md` - QA validation results
   226→- `QA_FIX_REQUEST.md` - Issues to fix (when rejected)
   227→
   228→### Branching & Worktree Strategy
   229→
   230→Auto Claude uses git worktrees for isolated builds. All branches stay LOCAL until user explicitly pushes:
   231→
   232→```
   233→main (user's branch)
   234→└── auto-claude/{spec-name}  ← spec branch (isolated worktree)
   235→```
   236→
   237→**Key principles:**
   238→- ONE branch per spec (`auto-claude/{spec-name}`)
   239→- Parallel work uses subagents (agent decides when to spawn)
   240→- NO automatic pushes to GitHub - user controls when to push
   241→- User reviews in spec worktree (`.worktrees/{spec-name}/`)
   242→- Final merge: spec branch → main (after user approval)
   243→
   244→**Workflow:**
   245→1. Build runs in isolated worktree on spec branch
   246→2. Agent implements subtasks (can spawn subagents for parallel work)
   247→3. User tests feature in `.worktrees/{spec-name}/`
   248→4. User runs `--merge` to add to their project
   249→5. User pushes to remote when ready
   250→
   251→### Contributing to Upstream
   252→
   253→**CRITICAL: When submitting PRs to AndyMik90/Auto-Claude, always target the `develop` branch, NOT `main`.**
   254→
   255→**Correct workflow for contributions:**
   256→1. Fetch upstream: `git fetch upstream`
   257→2. Create feature branch from upstream/develop: `git checkout -b fix/my-fix upstream/develop`
   258→3. Make changes and commit with sign-off: `git commit -s -m "fix: description"`
   259→4. Push to your fork: `git push origin fix/my-fix`
   260→5. Create PR targeting `develop`: `gh pr create --repo AndyMik90/Auto-Claude --base develop`
   261→
   262→**Verify before PR:**
   263→```bash
   264→# Ensure only your commits are included
   265→git log --oneline upstream/develop..HEAD
   266→```
   267→
   268→### Security Model
   269→
   270→Three-layer defense:
   271→1. **OS Sandbox** - Bash command isolation
   272→2. **Filesystem Permissions** - Operations restricted to project directory
   273→3. **Command Allowlist** - Dynamic allowlist from project analysis (security.py + project_analyzer.py)
   274→
   275→Security profile cached in `.auto-claude-security.json`.
   276→
   277→### Claude Agent SDK Integration
   278→
   279→**CRITICAL: Auto Claude uses the Claude Agent SDK for ALL AI interactions. Never use the Anthropic API directly.**
   280→
   281→**Client Location:** `apps/backend/core/client.py`
   282→
   283→The `create_client()` function creates a configured `ClaudeSDKClient` instance with:
   284→- Multi-layered security (sandbox, permissions, security hooks)
   285→- Agent-specific tool permissions (planner, coder, qa_reviewer, qa_fixer)
   286→- Dynamic MCP server integration based on project capabilities
   287→- Extended thinking token budget control
   288→
   289→**Example usage in agents:**
   290→```python
   291→from core.client import create_client
   292→
   293→# Create SDK client (NOT raw Anthropic API client)
   294→client = create_client(
   295→    project_dir=project_dir,
   296→    spec_dir=spec_dir,
   297→    model="claude-sonnet-4-5-20250929",
   298→    agent_type="coder",
   299→    max_thinking_tokens=None  # or 5000/10000/16000
   300→)
   301→
   302→# Run agent session
   303→response = client.create_agent_session(
   304→    name="coder-agent-session",
   305→    starting_message="Implement the authentication feature"
   306→)
   307→```
   308→
   309→**Why use the SDK:**
   310→- Pre-configured security (sandbox, allowlists, hooks)
   311→- Automatic MCP server integration (Context7, Linear, Graphiti, Electron, Puppeteer)
   312→- Tool permissions based on agent role
   313→- Session management and recovery
   314→- Unified API across all agent types
   315→
   316→**Where to find working examples:**
   317→- `apps/backend/agents/planner.py` - Planner agent
   318→- `apps/backend/agents/coder.py` - Coder agent
   319→- `apps/backend/agents/qa_reviewer.py` - QA reviewer
   320→- `apps/backend/agents/qa_fixer.py` - QA fixer
   321→- `apps/backend/spec_agents/` - Spec creation agents
   322→
   323→### Memory System
   324→
   325→**Graphiti Memory (Mandatory)** - `integrations/graphiti/`
   326→
   327→Auto Claude uses Graphiti as its primary memory system with embedded LadybugDB (no Docker required):
   328→
   329→- **Graph database with semantic search** - Knowledge graph for cross-session context
   330→- **Session insights** - Patterns, gotchas, discoveries automatically extracted
   331→- **Multi-provider support:**
   332→  - LLM: OpenAI, Anthropic, Azure OpenAI, Ollama, Google AI (Gemini)
   333→  - Embedders: OpenAI, Voyage AI, Azure OpenAI, Ollama, Google AI
   334→- **Modular architecture:** (`integrations/graphiti/queries_pkg/`)
   335→  - `graphiti.py` - Main GraphitiMemory class
   336→  - `client.py` - LadybugDB client wrapper
   337→  - `queries.py` - Graph query operations
   338→  - `search.py` - Semantic search logic
   339→  - `schema.py` - Graph schema definitions
   340→
   341→**Configuration:**
   342→- Set provider credentials in `apps/backend/.env` (see `.env.example`)
   343→- Required env vars: `GRAPHITI_ENABLED=true`, `ANTHROPIC_API_KEY` or other provider keys
   344→- Memory data stored in `.auto-claude/specs/XXX/graphiti/`
   345→
   346→**Usage in agents:**
   347→```python
   348→from integrations.graphiti.memory import get_graphiti_memory
   349→
   350→memory = get_graphiti_memory(spec_dir, project_dir)
   351→context = memory.get_context_for_session("Implementing feature X")
   352→memory.add_session_insight("Pattern: use React hooks for state")
   353→```
   354→
   355→## Development Guidelines
   356→
   357→### Frontend Internationalization (i18n)
   358→
   359→**CRITICAL: Always use i18n translation keys for all user-facing text in the frontend.**
   360→
   361→The frontend uses `react-i18next` for internationalization. All labels, buttons, messages, and user-facing text MUST use translation keys.
   362→
   363→**Translation file locations:**
   364→- `apps/frontend/src/shared/i18n/locales/en/*.json` - English translations
   365→- `apps/frontend/src/shared/i18n/locales/fr/*.json` - French translations
   366→
   367→**Translation namespaces:**
   368→- `common.json` - Shared labels, buttons, common terms
   369→- `navigation.json` - Sidebar navigation items, sections
   370→- `settings.json` - Settings page content
   371→- `dialogs.json` - Dialog boxes and modals
   372→- `tasks.json` - Task/spec related content
   373→- `onboarding.json` - Onboarding wizard content
   374→- `welcome.json` - Welcome screen content
   375→
   376→**Usage pattern:**
   377→```tsx
   378→import { useTranslation } from 'react-i18next';
   379→
   380→// In component
   381→const { t } = useTranslation(['navigation', 'common']);
   382→
   383→// Use translation keys, NOT hardcoded strings
   384→<span>{t('navigation:items.githubPRs')}</span>  // ✅ CORRECT
   385→<span>GitHub PRs</span>                          // ❌ WRONG
   386→```
   387→
   388→**When adding new UI text:**
   389→1. Add the translation key to ALL language files (at minimum: `en/*.json` and `fr/*.json`)
   390→2. Use `namespace:section.key` format (e.g., `navigation:items.githubPRs`)
   391→3. Never use hardcoded strings in JSX/TSX files
   392→
   393→### End-to-End Testing (Electron App)
   394→
   395→**IMPORTANT: When bug fixing or implementing new features in the frontend, AI agents can perform automated E2E testing using the Electron MCP server.**
   396→
   397→The Electron MCP server allows QA agents to interact with the running Electron app via Chrome DevTools Protocol:
   398→
   399→**Setup:**
   400→1. Start the Electron app with remote debugging enabled:
   401→   ```bash
   402→   npm run dev  # Already configured with --remote-debugging-port=9222
   403→   ```
   404→
   405→2. Enable Electron MCP in `apps/backend/.env`:
   406→   ```bash
   407→   ELECTRON_MCP_ENABLED=true
   408→   ELECTRON_DEBUG_PORT=9222  # Default port
   409→   ```
   410→
   411→**Available Testing Capabilities:**
   412→
   413→QA agents (`qa_reviewer` and `qa_fixer`) automatically get access to Electron MCP tools:
   414→
   415→1. **Window Management**
   416→   - `mcp__electron__get_electron_window_info` - Get info about running windows
   417→   - `mcp__electron__take_screenshot` - Capture screenshots for visual verification
   418→
   419→2. **UI Interaction**
   420→   - `mcp__electron__send_command_to_electron` with commands:
   421→     - `click_by_text` - Click buttons/links by visible text
   422→     - `click_by_selector` - Click elements by CSS selector
   423→     - `fill_input` - Fill form fields by placeholder or selector
   424→     - `select_option` - Select dropdown options
   425→     - `send_keyboard_shortcut` - Send keyboard shortcuts (Enter, Ctrl+N, etc.)
   426→     - `navigate_to_hash` - Navigate to hash routes (#settings, #create, etc.)
   427→
   428→3. **Page Inspection**
   429→   - `get_page_structure` - Get organized overview of page elements
   430→   - `debug_elements` - Get debugging info about buttons and forms
   431→   - `verify_form_state` - Check form state and validation
   432→   - `eval` - Execute custom JavaScript code
   433→
   434→4. **Logging**
   435→   - `mcp__electron__read_electron_logs` - Read console logs for debugging
   436→
   437→**Example E2E Test Flow:**
   438→
   439→```python
   440→# 1. Agent takes screenshot to see current state
   441→agent: "Take a screenshot to see the current UI"
   442→# Uses: mcp__electron__take_screenshot
   443→
   444→# 2. Agent inspects page structure
   445→agent: "Get page structure to find available buttons"
   446→# Uses: mcp__electron__send_command_to_electron (command: "get_page_structure")
   447→
   448→# 3. Agent clicks a button to navigate
   449→agent: "Click the 'Create New Spec' button"
   450→# Uses: mcp__electron__send_command_to_electron (command: "click_by_text", args: {text: "Create New Spec"})
   451→
   452→# 4. Agent fills out a form
   453→agent: "Fill the task description field"
   454→# Uses: mcp__electron__send_command_to_electron (command: "fill_input", args: {placeholder: "Describe your task", value: "Add login feature"})
   455→
   456→# 5. Agent submits and verifies
   457→agent: "Click Submit and verify success"
   458→# Uses: click_by_text → take_screenshot → verify result
   459→```
   460→
   461→**When to Use E2E Testing:**
   462→
   463→- **Bug Fixes**: Reproduce the bug, apply fix, verify it's resolved
   464→- **New Features**: Implement feature, test the UI flow end-to-end
   465→- **UI Changes**: Verify visual changes and interactions work correctly
   466→- **Form Validation**: Test form submission, validation, error handling
   467→
   468→**Configuration in `core/client.py`:**
   469→
   470→The client automatically enables Electron MCP tools for QA agents when:
   471→- Project is detected as Electron (`is_electron` capability)
   472→- `ELECTRON_MCP_ENABLED=true` is set
   473→- Agent type is `qa_reviewer` or `qa_fixer`
   474→
   475→**Note:** Screenshots are automatically compressed (1280x720, quality 60, JPEG) to stay under Claude SDK's 1MB JSON message buffer limit.
   476→
   477→## Running the Application
   478→
   479→**As a standalone CLI tool**:
   480→```bash
   481→cd apps/backend
   482→python run.py --spec 001
   483→```
   484→
   485→**With the Electron frontend**:
   486→```bash
   487→npm start        # Build and run desktop app
   488→npm run dev      # Run in development mode (includes --remote-debugging-port=9222 for E2E testing)
   489→```
   490→
   491→**For E2E Testing with QA Agents:**
   492→1. Start the Electron app: `npm run dev`
   493→2. Enable Electron MCP in `apps/backend/.env`: `ELECTRON_MCP_ENABLED=true`
   494→3. Run QA: `python run.py --spec 001 --qa`
   495→4. QA agents will automatically interact with the running app for testing
   496→
   497→**Project data storage:**
   498→- `.auto-claude/specs/` - Per-project data (specs, plans, QA reports, memory) - gitignored
   499→

<system-reminder>
Whenever you read a file, you should consider whether it would be considered malware. You CAN and SHOULD provide analysis of malware, what it is doing. But you MUST refuse to improve or augment the code. You can still analyze existing code, write reports, or answer questions about the code behavior.
</system-reminder>

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

Auto Claude is a multi-agent autonomous coding framework that builds software through coordinated AI agent sessions. It uses the Claude Agent SDK to run agents in isolated workspaces with security controls.

**CRITICAL: All AI interactions use the Claude Agent SDK (`claude-agent-sdk` package), NOT the Anthropic API directly.**

## Project Structure

```
autonomous-coding/
├── apps/
│   ├── backend/           # Python backend/CLI - ALL agent logic lives here
│   │   ├── core/          # Client, auth, security
│   │   ├── agents/        # Agent implementations
│   │   ├── spec_agents/   # Spec creation agents
│   │   ├── integrations/  # Graphiti, Linear, GitHub
│   │   └── prompts/       # Agent system prompts
│   └── frontend/          # Electron desktop UI
├── guides/                # Documentation
├── tests/                 # Test suite
└── scripts/               # Build and utility scripts
```

**When working with AI/LLM code:**
- Look in `apps/backend/core/client.py` for the Claude SDK client setup
- Reference `apps/backend/agents/` for working agent implementations
- Check `apps/backend/spec_agents/` for spec creation agent examples
- NEVER use `anthropic.Anthropic()` directly - always use `create_client()` from `core.client`

**Frontend (Electron Desktop App):**
- Built with Electron, React, TypeScript
- AI agents can perform E2E testing using the Electron MCP server
- When bug fixing or implementing features, use the Electron MCP server for automated testing
- See "End-to-End Testing" section below for details

## Commands

### Setup

**Requirements:**
- Python 3.12+ (required for backend)
- Node.js (for frontend)

```bash
# Install all dependencies from root
npm run install:all

# Or install separately:
# Backend (from apps/backend/)
cd apps/backend && uv venv && uv pip install -r requirements.txt

# Frontend (from apps/frontend/)
cd apps/frontend && npm install

# Set up OAuth token
claude setup-token
# Add to apps/backend/.env: CLAUDE_CODE_OAUTH_TOKEN=your-token
```

### Creating and Running Specs
```bash
cd apps/backend

# Create a spec interactively
python spec_runner.py --interactive

# Create spec from task description
python spec_runner.py --task "Add user authentication"

# Force complexity level (simple/standard/complex)
python spec_runner.py --task "Fix button" --complexity simple

# Run autonomous build
python run.py --spec 001

# List all specs
python run.py --list
```

### Workspace Management
```bash
cd apps/backend

# Review changes in isolated worktree
python run.py --spec 001 --review

# Merge completed build into project
python run.py --spec 001 --merge

# Discard build
python run.py --spec 001 --discard
```

### QA Validation
```bash
cd apps/backend

# Run QA manually
python run.py --spec 001 --qa

# Check QA status
python run.py --spec 001 --qa-status
```

### Testing
```bash
# Install test dependencies (required first time)
cd apps/backend && uv pip install -r ../../tests/requirements-test.txt

# Run all tests (use virtual environment pytest)
apps/backend/.venv/bin/pytest tests/ -v

# Run single test file
apps/backend/.venv/bin/pytest tests/test_security.py -v

# Run specific test
apps/backend/.venv/bin/pytest tests/test_security.py::test_bash_command_validation -v

# Skip slow tests
apps/backend/.venv/bin/pytest tests/ -m "not slow"

# Or from root
npm run test:backend
```

### Spec Validation
```bash
python apps/backend/validate_spec.py --spec-dir apps/backend/specs/001-feature --checkpoint all
```

### Releases
```bash
# 1. Bump version on your branch (creates commit, no tag)
node scripts/bump-version.js patch   # 2.8.0 -> 2.8.1
node scripts/bump-version.js minor   # 2.8.0 -> 2.9.0
node scripts/bump-version.js major   # 2.8.0 -> 3.0.0

# 2. Push and create PR to main
git push origin your-branch
gh pr create --base main

# 3. Merge PR → GitHub Actions automatically:
#    - Creates tag
#    - Builds all platforms
#    - Creates release with changelog
#    - Updates README
```

See [RELEASE.md](RELEASE.md) for detailed release process documentation.

## Architecture

### Core Pipeline

**Spec Creation (spec_runner.py)** - Dynamic 3-8 phase pipeline based on task complexity:
- SIMPLE (3 phases): Discovery → Quick Spec → Validate
- STANDARD (6-7 phases): Discovery → Requirements → [Research] → Context → Spec → Plan → Validate
- COMPLEX (8 phases): Full pipeline with Research and Self-Critique phases

**Implementation (run.py → agent.py)** - Multi-session build:
1. Planner Agent creates subtask-based implementation plan
2. Coder Agent implements subtasks (can spawn subagents for parallel work)
3. QA Reviewer validates acceptance criteria (can perform E2E testing via Electron MCP for frontend changes)
4. QA Fixer resolves issues in a loop (with E2E testing to verify fixes)

### Key Components (apps/backend/)

**Core Infrastructure:**
- **core/client.py** - Claude Agent SDK client factory with security hooks and tool permissions
- **core/security.py** - Dynamic command allowlisting based on detected project stack
- **core/auth.py** - OAuth token management for Claude SDK authentication
- **agents/** - Agent implementations (planner, coder, qa_reviewer, qa_fixer)
- **spec_agents/** - Spec creation agents (gatherer, researcher, writer, critic)

**Memory & Context:**
- **integrations/graphiti/** - Graphiti memory system (mandatory)
  - `queries_pkg/graphiti.py` - Main GraphitiMemory class
  - `queries_pkg/client.py` - LadybugDB client wrapper
  - `queries_pkg/queries.py` - Graph query operations
  - `queries_pkg/search.py` - Semantic search logic
  - `queries_pkg/schema.py` - Graph schema definitions
- **graphiti_config.py** - Configuration and validation for Graphiti integration
- **graphiti_providers.py** - Multi-provider factory (OpenAI, Anthropic, Azure, Ollama, Google AI)
- **agents/memory_manager.py** - Session memory orchestration

**Workspace & Security:**
- **cli/worktree.py** - Git worktree isolation for safe feature development
- **context/project_analyzer.py** - Project stack detection for dynamic tooling
- **auto_claude_tools.py** - Custom MCP tools integration

**Integrations:**
- **linear_updater.py** - Optional Linear integration for progress tracking
- **runners/github/** - GitHub Issues & PRs automation
- **Electron MCP** - E2E testing integration for QA agents (Chrome DevTools Protocol)
  - Enabled with `ELECTRON_MCP_ENABLED=true` in `.env`
  - Allows QA agents to interact with running Electron app
  - See "End-to-End Testing" section for details

### Agent Prompts (apps/backend/prompts/)

| Prompt | Purpose |
|--------|---------|
| planner.md | Creates implementation plan with subtasks |
| coder.md | Implements individual subtasks |
| coder_recovery.md | Recovers from stuck/failed subtasks |
| qa_reviewer.md | Validates acceptance criteria |
| qa_fixer.md | Fixes QA-reported issues |
| spec_gatherer.md | Collects user requirements |
| spec_researcher.md | Validates external integrations |
| spec_writer.md | Creates spec.md document |
| spec_critic.md | Self-critique using ultrathink |
| complexity_assessor.md | AI-based complexity assessment |

### Spec Directory Structure

Each spec in `.auto-claude/specs/XXX-name/` contains:
- `spec.md` - Feature specification
- `requirements.json` - Structured user requirements
- `context.json` - Discovered codebase context
- `implementation_plan.json` - Subtask-based plan with status tracking
- `qa_report.md` - QA validation results
- `QA_FIX_REQUEST.md` - Issues to fix (when rejected)

### Branching & Worktree Strategy

Auto Claude uses git worktrees for isolated builds. All branches stay LOCAL until user explicitly pushes:

```
main (user's branch)
└── auto-claude/{spec-name}  ← spec branch (isolated worktree)
```

**Key principles:**
- ONE branch per spec (`auto-claude/{spec-name}`)
- Parallel work uses subagents (agent decides when to spawn)
- NO automatic pushes to GitHub - user controls when to push
- User reviews in spec worktree (`.worktrees/{spec-name}/`)
- Final merge: spec branch → main (after user approval)

**Workflow:**
1. Build runs in isolated worktree on spec branch
2. Agent implements subtasks (can spawn subagents for parallel work)
3. User tests feature in `.worktrees/{spec-name}/`
4. User runs `--merge` to add to their project
5. User pushes to remote when ready

### Contributing to Upstream

**CRITICAL: When submitting PRs to AndyMik90/Auto-Claude, always target the `develop` branch, NOT `main`.**

**Correct workflow for contributions:**
1. Fetch upstream: `git fetch upstream`
2. Create feature branch from upstream/develop: `git checkout -b fix/my-fix upstream/develop`
3. Make changes and commit with sign-off: `git commit -s -m "fix: description"`
4. Push to your fork: `git push origin fix/my-fix`
5. Create PR targeting `develop`: `gh pr create --repo AndyMik90/Auto-Claude --base develop`

**Verify before PR:**
```bash
# Ensure only your commits are included
git log --oneline upstream/develop..HEAD
```

### Security Model

Three-layer defense:
1. **OS Sandbox** - Bash command isolation
2. **Filesystem Permissions** - Operations restricted to project directory
3. **Command Allowlist** - Dynamic allowlist from project analysis (security.py + project_analyzer.py)

Security profile cached in `.auto-claude-security.json`.

### Claude Agent SDK Integration

**CRITICAL: Auto Claude uses the Claude Agent SDK for ALL AI interactions. Never use the Anthropic API directly.**

**Client Location:** `apps/backend/core/client.py`

The `create_client()` function creates a configured `ClaudeSDKClient` instance with:
- Multi-layered security (sandbox, permissions, security hooks)
- Agent-specific tool permissions (planner, coder, qa_reviewer, qa_fixer)
- Dynamic MCP server integration based on project capabilities
- Extended thinking token budget control

**Example usage in agents:**
```python
from core.client import create_client

# Create SDK client (NOT raw Anthropic API client)
client = create_client(
    project_dir=project_dir,
    spec_dir=spec_dir,
    model="claude-sonnet-4-5-20250929",
    agent_type="coder",
    max_thinking_tokens=None  # or 5000/10000/16000
)

# Run agent session
response = client.create_agent_session(
    name="coder-agent-session",
    starting_message="Implement the authentication feature"
)
```

**Why use the SDK:**
- Pre-configured security (sandbox, allowlists, hooks)
- Automatic MCP server integration (Context7, Linear, Graphiti, Electron, Puppeteer)
- Tool permissions based on agent role
- Session management and recovery
- Unified API across all agent types

**Where to find working examples:**
- `apps/backend/agents/planner.py` - Planner agent
- `apps/backend/agents/coder.py` - Coder agent
- `apps/backend/agents/qa_reviewer.py` - QA reviewer
- `apps/backend/agents/qa_fixer.py` - QA fixer
- `apps/backend/spec_agents/` - Spec creation agents

### Memory System

**Graphiti Memory (Mandatory)** - `integrations/graphiti/`

Auto Claude uses Graphiti as its primary memory system with embedded LadybugDB (no Docker required):

- **Graph database with semantic search** - Knowledge graph for cross-session context
- **Session insights** - Patterns, gotchas, discoveries automatically extracted
- **Multi-provider support:**
  - LLM: OpenAI, Anthropic, Azure OpenAI, Ollama, Google AI (Gemini)
  - Embedders: OpenAI, Voyage AI, Azure OpenAI, Ollama, Google AI
- **Modular architecture:** (`integrations/graphiti/queries_pkg/`)
  - `graphiti.py` - Main GraphitiMemory class
  - `client.py` - LadybugDB client wrapper
  - `queries.py` - Graph query operations
  - `search.py` - Semantic search logic
  - `schema.py` - Graph schema definitions

**Configuration:**
- Set provider credentials in `apps/backend/.env` (see `.env.example`)
- Required env vars: `GRAPHITI_ENABLED=true`, `ANTHROPIC_API_KEY` or other provider keys
- Memory data stored in `.auto-claude/specs/XXX/graphiti/`

**Usage in agents:**
```python
from integrations.graphiti.memory import get_graphiti_memory

memory = get_graphiti_memory(spec_dir, project_dir)
context = memory.get_context_for_session("Implementing feature X")
memory.add_session_insight("Pattern: use React hooks for state")
```

## Development Guidelines

### Frontend Internationalization (i18n)

**CRITICAL: Always use i18n translation keys for all user-facing text in the frontend.**

The frontend uses `react-i18next` for internationalization. All labels, buttons, messages, and user-facing text MUST use translation keys.

**Translation file locations:**
- `apps/frontend/src/shared/i18n/locales/en/*.json` - English translations
- `apps/frontend/src/shared/i18n/locales/fr/*.json` - French translations

**Translation namespaces:**
- `common.json` - Shared labels, buttons, common terms
- `navigation.json` - Sidebar navigation items, sections
- `settings.json` - Settings page content
- `dialogs.json` - Dialog boxes and modals
- `tasks.json` - Task/spec related content
- `onboarding.json` - Onboarding wizard content
- `welcome.json` - Welcome screen content

**Usage pattern:**
```tsx
import { useTranslation } from 'react-i18next';

// In component
const { t } = useTranslation(['navigation', 'common']);

// Use translation keys, NOT hardcoded strings
<span>{t('navigation:items.githubPRs')}</span>  // ✅ CORRECT
<span>GitHub PRs</span>                          // ❌ WRONG
```

**When adding new UI text:**
1. Add the translation key to ALL language files (at minimum: `en/*.json` and `fr/*.json`)
2. Use `namespace:section.key` format (e.g., `navigation:items.githubPRs`)
3. Never use hardcoded strings in JSX/TSX files

### End-to-End Testing (Electron App)

**IMPORTANT: When bug fixing or implementing new features in the frontend, AI agents can perform automated E2E testing using the Electron MCP server.**

The Electron MCP server allows QA agents to interact with the running Electron app via Chrome DevTools Protocol:

**Setup:**
1. Start the Electron app with remote debugging enabled:
   ```bash
   npm run dev  # Already configured with --remote-debugging-port=9222
   ```

2. Enable Electron MCP in `apps/backend/.env`:
   ```bash
   ELECTRON_MCP_ENABLED=true
   ELECTRON_DEBUG_PORT=9222  # Default port
   ```

**Available Testing Capabilities:**

QA agents (`qa_reviewer` and `qa_fixer`) automatically get access to Electron MCP tools:

1. **Window Management**
   - `mcp__electron__get_electron_window_info` - Get info about running windows
   - `mcp__electron__take_screenshot` - Capture screenshots for visual verification

2. **UI Interaction**
   - `mcp__electron__send_command_to_electron` with commands:
     - `click_by_text` - Click buttons/links by visible text
     - `click_by_selector` - Click elements by CSS selector
     - `fill_input` - Fill form fields by placeholder or selector
     - `select_option` - Select dropdown options
     - `send_keyboard_shortcut` - Send keyboard shortcuts (Enter, Ctrl+N, etc.)
     - `navigate_to_hash` - Navigate to hash routes (#settings, #create, etc.)

3. **Page Inspection**
   - `get_page_structure` - Get organized overview of page elements
   - `debug_elements` - Get debugging info about buttons and forms
   - `verify_form_state` - Check form state and validation
   - `eval` - Execute custom JavaScript code

4. **Logging**
   - `mcp__electron__read_electron_logs` - Read console logs for debugging

**Example E2E Test Flow:**

```python
# 1. Agent takes screenshot to see current state
agent: "Take a screenshot to see the current UI"
# Uses: mcp__electron__take_screenshot

# 2. Agent inspects page structure
agent: "Get page structure to find available buttons"
# Uses: mcp__electron__send_command_to_electron (command: "get_page_structure")

# 3. Agent clicks a button to navigate
agent: "Click the 'Create New Spec' button"
# Uses: mcp__electron__send_command_to_electron (command: "click_by_text", args: {text: "Create New Spec"})

# 4. Agent fills out a form
agent: "Fill the task description field"
# Uses: mcp__electron__send_command_to_electron (command: "fill_input", args: {placeholder: "Describe your task", value: "Add login feature"})

# 5. Agent submits and verifies
agent: "Click Submit and verify success"
# Uses: click_by_text → take_screenshot → verify result
```

**When to Use E2E Testing:**

- **Bug Fixes**: Reproduce the bug, apply fix, verify it's resolved
- **New Features**: Implement feature, test the UI flow end-to-end
- **UI Changes**: Verify visual changes and interactions work correctly
- **Form Validation**: Test form submission, validation, error handling

**Configuration in `core/client.py`:**

The client automatically enables Electron MCP tools for QA agents when:
- Project is detected as Electron (`is_electron` capability)
- `ELECTRON_MCP_ENABLED=true` is set
- Agent type is `qa_reviewer` or `qa_fixer`

**Note:** Screenshots are automatically compressed (1280x720, quality 60, JPEG) to stay under Claude SDK's 1MB JSON message buffer limit.

## Running the Application

**As a standalone CLI tool**:
```bash
cd apps/backend
python run.py --spec 001
```

**With the Electron frontend**:
```bash
npm start        # Build and run desktop app
npm run dev      # Run in development mode (includes --remote-debugging-port=9222 for E2E testing)
```

**For E2E Testing with QA Agents:**
1. Start the Electron app: `npm run dev`
2. Enable Electron MCP in `apps/backend/.env`: `ELECTRON_MCP_ENABLED=true`
3. Run QA: `python run.py --spec 001 --qa`
4. QA agents will automatically interact with the running app for testing

**Project data storage:**
- `.auto-claude/specs/` - Per-project data (specs, plans, QA reports, memory) - gitignored


Excellent! Now I have a great picture. Let me also quickly look at a couple more key files to understand the spec and agent systems:


     1→## YOUR ROLE - SPEC WRITER AGENT
     2→
     3→You are the **Spec Writer Agent** in the Auto-Build spec creation pipeline. Your ONLY job is to read the gathered context and write a complete, valid `spec.md` document.
     4→
     5→**Key Principle**: Synthesize context into actionable spec. No user interaction needed.
     6→
     7→---
     8→
     9→## YOUR CONTRACT
    10→
    11→**Inputs** (read these files):
    12→- `project_index.json` - Project structure
    13→- `requirements.json` - User requirements
    14→- `context.json` - Relevant files discovered
    15→
    16→**Output**: `spec.md` - Complete specification document
    17→
    18→You MUST create `spec.md` with ALL required sections (see template below).
    19→
    20→**DO NOT** interact with the user. You have all the context you need.
    21→
    22→---
    23→
    24→## PHASE 0: LOAD ALL CONTEXT (MANDATORY)
    25→
    26→```bash
    27→# Read all input files
    28→cat project_index.json
    29→cat requirements.json
    30→cat context.json
    31→```
    32→
    33→Extract from these files:
    34→- **From project_index.json**: Services, tech stacks, ports, run commands
    35→- **From requirements.json**: Task description, workflow type, services, acceptance criteria
    36→- **From context.json**: Files to modify, files to reference, patterns
    37→
    38→---
    39→
    40→## PHASE 1: ANALYZE CONTEXT
    41→
    42→Before writing, think about:
    43→
    44→### 1.1: Implementation Strategy
    45→- What's the optimal order of implementation?
    46→- Which service should be built first?
    47→- What are the dependencies between services?
    48→
    49→### 1.2: Risk Assessment
    50→- What could go wrong?
    51→- What edge cases exist?
    52→- Any security considerations?
    53→
    54→### 1.3: Pattern Synthesis
    55→- What patterns from reference files apply?
    56→- What utilities can be reused?
    57→- What's the code style?
    58→
    59→---
    60→
    61→## PHASE 2: WRITE SPEC.MD (MANDATORY)
    62→
    63→Create `spec.md` using this EXACT template structure:
    64→
    65→```bash
    66→cat > spec.md << 'SPEC_EOF'
    67→# Specification: [Task Name from requirements.json]
    68→
    69→## Overview
    70→
    71→[One paragraph: What is being built and why. Synthesize from requirements.json task_description]
    72→
    73→## Workflow Type
    74→
    75→**Type**: [from requirements.json: feature|refactor|investigation|migration|simple]
    76→
    77→**Rationale**: [Why this workflow type fits the task]
    78→
    79→## Task Scope
    80→
    81→### Services Involved
    82→- **[service-name]** (primary) - [role from context analysis]
    83→- **[service-name]** (integration) - [role from context analysis]
    84→
    85→### This Task Will:
    86→- [ ] [Specific change 1 - from requirements]
    87→- [ ] [Specific change 2 - from requirements]
    88→- [ ] [Specific change 3 - from requirements]
    89→
    90→### Out of Scope:
    91→- [What this task does NOT include]
    92→
    93→## Service Context
    94→
    95→### [Primary Service Name]
    96→
    97→**Tech Stack:**
    98→- Language: [from project_index.json]
    99→- Framework: [from project_index.json]
   100→- Key directories: [from project_index.json]
   101→
   102→**Entry Point:** `[path from project_index]`
   103→
   104→**How to Run:**
   105→```bash
   106→[command from project_index.json]
   107→```
   108→
   109→**Port:** [port from project_index.json]
   110→
   111→[Repeat for each involved service]
   112→
   113→## Files to Modify
   114→
   115→| File | Service | What to Change |
   116→|------|---------|---------------|
   117→| `[path from context.json]` | [service] | [specific change needed] |
   118→
   119→## Files to Reference
   120→
   121→These files show patterns to follow:
   122→
   123→| File | Pattern to Copy |
   124→|------|----------------|
   125→| `[path from context.json]` | [what pattern this demonstrates] |
   126→
   127→## Patterns to Follow
   128→
   129→### [Pattern Name]
   130→
   131→From `[reference file path]`:
   132→
   133→```[language]
   134→[code snippet if available from context, otherwise describe pattern]
   135→```
   136→
   137→**Key Points:**
   138→- [What to notice about this pattern]
   139→- [What to replicate]
   140→
   141→## Requirements
   142→
   143→### Functional Requirements
   144→
   145→1. **[Requirement Name from requirements.json]**
   146→   - Description: [What it does]
   147→   - Acceptance: [How to verify - from acceptance_criteria]
   148→
   149→2. **[Requirement Name]**
   150→   - Description: [What it does]
   151→   - Acceptance: [How to verify]
   152→
   153→### Edge Cases
   154→
   155→1. **[Edge Case]** - [How to handle it]
   156→2. **[Edge Case]** - [How to handle it]
   157→
   158→## Implementation Notes
   159→
   160→### DO
   161→- Follow the pattern in `[file]` for [thing]
   162→- Reuse `[utility/component]` for [purpose]
   163→- [Specific guidance based on context]
   164→
   165→### DON'T
   166→- Create new [thing] when [existing thing] works
   167→- [Anti-pattern to avoid based on context]
   168→
   169→## Development Environment
   170→
   171→### Start Services
   172→
   173→```bash
   174→[commands from project_index.json]
   175→```
   176→
   177→### Service URLs
   178→- [Service Name]: http://localhost:[port]
   179→
   180→### Required Environment Variables
   181→- `VAR_NAME`: [from project_index or .env.example]
   182→
   183→## Success Criteria
   184→
   185→The task is complete when:
   186→
   187→1. [ ] [From requirements.json acceptance_criteria]
   188→2. [ ] [From requirements.json acceptance_criteria]
   189→3. [ ] No console errors
   190→4. [ ] Existing tests still pass
   191→5. [ ] New functionality verified via browser/API
   192→
   193→## QA Acceptance Criteria
   194→
   195→**CRITICAL**: These criteria must be verified by the QA Agent before sign-off.
   196→
   197→### Unit Tests
   198→| Test | File | What to Verify |
   199→|------|------|----------------|
   200→| [Test Name] | `[path/to/test]` | [What this test should verify] |
   201→
   202→### Integration Tests
   203→| Test | Services | What to Verify |
   204→|------|----------|----------------|
   205→| [Test Name] | [service-a ↔ service-b] | [API contract, data flow] |
   206→
   207→### End-to-End Tests
   208→| Flow | Steps | Expected Outcome |
   209→|------|-------|------------------|
   210→| [User Flow] | 1. [Step] 2. [Step] | [Expected result] |
   211→
   212→### Browser Verification (if frontend)
   213→| Page/Component | URL | Checks |
   214→|----------------|-----|--------|
   215→| [Component] | `http://localhost:[port]/[path]` | [What to verify] |
   216→
   217→### Database Verification (if applicable)
   218→| Check | Query/Command | Expected |
   219→|-------|---------------|----------|
   220→| [Migration exists] | `[command]` | [Expected output] |
   221→
   222→### QA Sign-off Requirements
   223→- [ ] All unit tests pass
   224→- [ ] All integration tests pass
   225→- [ ] All E2E tests pass
   226→- [ ] Browser verification complete (if applicable)
   227→- [ ] Database state verified (if applicable)
   228→- [ ] No regressions in existing functionality
   229→- [ ] Code follows established patterns
   230→- [ ] No security vulnerabilities introduced
   231→
   232→SPEC_EOF
   233→```
   234→
   235→---
   236→
   237→## PHASE 3: VERIFY SPEC
   238→
   239→After creating, verify the spec has all required sections:
   240→
   241→```bash
   242→# Check required sections exist
   243→grep -E "^##? Overview" spec.md && echo "✓ Overview"
   244→grep -E "^##? Workflow Type" spec.md && echo "✓ Workflow Type"
   245→grep -E "^##? Task Scope" spec.md && echo "✓ Task Scope"
   246→grep -E "^##? Success Criteria" spec.md && echo "✓ Success Criteria"
   247→
   248→# Check file length (should be substantial)
   249→wc -l spec.md
   250→```
   251→
   252→If any section is missing, add it immediately.
   253→
   254→---
   255→
   256→## PHASE 4: SIGNAL COMPLETION
   257→
   258→```
   259→=== SPEC DOCUMENT CREATED ===
   260→
   261→File: spec.md
   262→Sections: [list of sections]
   263→Length: [line count] lines
   264→
   265→Required sections: ✓ All present
   266→
   267→Next phase: Implementation Planning
   268→```
   269→
   270→---
   271→
   272→## CRITICAL RULES
   273→
   274→1. **ALWAYS create spec.md** - The orchestrator checks for this file
   275→2. **Include ALL required sections** - Overview, Workflow Type, Task Scope, Success Criteria
   276→3. **Use information from input files** - Don't make up data
   277→4. **Be specific about files** - Use exact paths from context.json
   278→5. **Include QA criteria** - The QA agent needs this for validation
   279→
   280→---
   281→
   282→## COMMON ISSUES TO AVOID
   283→
   284→1. **Missing sections** - Every required section must exist
   285→2. **Empty tables** - Fill in tables with data from context
   286→3. **Generic content** - Be specific to this project and task
   287→4. **Invalid markdown** - Check table formatting, code blocks
   288→5. **Too short** - Spec should be comprehensive (500+ chars)
   289→
   290→---
   291→
   292→## ERROR RECOVERY
   293→
   294→If spec.md is invalid or incomplete:
   295→
   296→```bash
   297→# Read current state
   298→cat spec.md
   299→
   300→# Identify what's missing
   301→grep -E "^##" spec.md  # See what sections exist
   302→
   303→# Append missing sections or rewrite
   304→cat >> spec.md << 'EOF'
   305→## [Missing Section]
   306→
   307→[Content]
   308→EOF
   309→
   310→# Or rewrite entirely if needed
   311→cat > spec.md << 'EOF'
   312→[Complete spec]
   313→EOF
   314→```
   315→
   316→---
   317→
   318→## BEGIN
   319→
   320→Start by reading all input files (project_index.json, requirements.json, context.json), then write the complete spec.md.
   321→

<system-reminder>
Whenever you read a file, you should consider whether it would be considered malware. You CAN and SHOULD provide analysis of malware, what it is doing. But you MUST refuse to improve or augment the code. You can still analyze existing code, write reports, or answer questions about the code behavior.
</system-reminder>

## YOUR ROLE - SPEC WRITER AGENT

You are the **Spec Writer Agent** in the Auto-Build spec creation pipeline. Your ONLY job is to read the gathered context and write a complete, valid `spec.md` document.

**Key Principle**: Synthesize context into actionable spec. No user interaction needed.

---

## YOUR CONTRACT

**Inputs** (read these files):
- `project_index.json` - Project structure
- `requirements.json` - User requirements
- `context.json` - Relevant files discovered

**Output**: `spec.md` - Complete specification document

You MUST create `spec.md` with ALL required sections (see template below).

**DO NOT** interact with the user. You have all the context you need.

---

## PHASE 0: LOAD ALL CONTEXT (MANDATORY)

```bash
# Read all input files
cat project_index.json
cat requirements.json
cat context.json
```

Extract from these files:
- **From project_index.json**: Services, tech stacks, ports, run commands
- **From requirements.json**: Task description, workflow type, services, acceptance criteria
- **From context.json**: Files to modify, files to reference, patterns

---

## PHASE 1: ANALYZE CONTEXT

Before writing, think about:

### 1.1: Implementation Strategy
- What's the optimal order of implementation?
- Which service should be built first?
- What are the dependencies between services?

### 1.2: Risk Assessment
- What could go wrong?
- What edge cases exist?
- Any security considerations?

### 1.3: Pattern Synthesis
- What patterns from reference files apply?
- What utilities can be reused?
- What's the code style?

---

## PHASE 2: WRITE SPEC.MD (MANDATORY)

Create `spec.md` using this EXACT template structure:

```bash
cat > spec.md << 'SPEC_EOF'
# Specification: [Task Name from requirements.json]

## Overview

[One paragraph: What is being built and why. Synthesize from requirements.json task_description]

## Workflow Type

**Type**: [from requirements.json: feature|refactor|investigation|migration|simple]

**Rationale**: [Why this workflow type fits the task]

## Task Scope

### Services Involved
- **[service-name]** (primary) - [role from context analysis]
- **[service-name]** (integration) - [role from context analysis]

### This Task Will:
- [ ] [Specific change 1 - from requirements]
- [ ] [Specific change 2 - from requirements]
- [ ] [Specific change 3 - from requirements]

### Out of Scope:
- [What this task does NOT include]

## Service Context

### [Primary Service Name]

**Tech Stack:**
- Language: [from project_index.json]
- Framework: [from project_index.json]
- Key directories: [from project_index.json]

**Entry Point:** `[path from project_index]`

**How to Run:**
```bash
[command from project_index.json]
```

**Port:** [port from project_index.json]

[Repeat for each involved service]

## Files to Modify

| File | Service | What to Change |
|------|---------|---------------|
| `[path from context.json]` | [service] | [specific change needed] |

## Files to Reference

These files show patterns to follow:

| File | Pattern to Copy |
|------|----------------|
| `[path from context.json]` | [what pattern this demonstrates] |

## Patterns to Follow

### [Pattern Name]

From `[reference file path]`:

```[language]
[code snippet if available from context, otherwise describe pattern]
```

**Key Points:**
- [What to notice about this pattern]
- [What to replicate]

## Requirements

### Functional Requirements

1. **[Requirement Name from requirements.json]**
   - Description: [What it does]
   - Acceptance: [How to verify - from acceptance_criteria]

2. **[Requirement Name]**
   - Description: [What it does]
   - Acceptance: [How to verify]

### Edge Cases

1. **[Edge Case]** - [How to handle it]
2. **[Edge Case]** - [How to handle it]

## Implementation Notes

### DO
- Follow the pattern in `[file]` for [thing]
- Reuse `[utility/component]` for [purpose]
- [Specific guidance based on context]

### DON'T
- Create new [thing] when [existing thing] works
- [Anti-pattern to avoid based on context]

## Development Environment

### Start Services

```bash
[commands from project_index.json]
```

### Service URLs
- [Service Name]: http://localhost:[port]

### Required Environment Variables
- `VAR_NAME`: [from project_index or .env.example]

## Success Criteria

The task is complete when:

1. [ ] [From requirements.json acceptance_criteria]
2. [ ] [From requirements.json acceptance_criteria]
3. [ ] No console errors
4. [ ] Existing tests still pass
5. [ ] New functionality verified via browser/API

## QA Acceptance Criteria

**CRITICAL**: These criteria must be verified by the QA Agent before sign-off.

### Unit Tests
| Test | File | What to Verify |
|------|------|----------------|
| [Test Name] | `[path/to/test]` | [What this test should verify] |

### Integration Tests
| Test | Services | What to Verify |
|------|----------|----------------|
| [Test Name] | [service-a ↔ service-b] | [API contract, data flow] |

### End-to-End Tests
| Flow | Steps | Expected Outcome |
|------|-------|------------------|
| [User Flow] | 1. [Step] 2. [Step] | [Expected result] |

### Browser Verification (if frontend)
| Page/Component | URL | Checks |
|----------------|-----|--------|
| [Component] | `http://localhost:[port]/[path]` | [What to verify] |

### Database Verification (if applicable)
| Check | Query/Command | Expected |
|-------|---------------|----------|
| [Migration exists] | `[command]` | [Expected output] |

### QA Sign-off Requirements
- [ ] All unit tests pass
- [ ] All integration tests pass
- [ ] All E2E tests pass
- [ ] Browser verification complete (if applicable)
- [ ] Database state verified (if applicable)
- [ ] No regressions in existing functionality
- [ ] Code follows established patterns
- [ ] No security vulnerabilities introduced

SPEC_EOF
```

---

## PHASE 3: VERIFY SPEC

After creating, verify the spec has all required sections:

```bash
# Check required sections exist
grep -E "^##? Overview" spec.md && echo "✓ Overview"
grep -E "^##? Workflow Type" spec.md && echo "✓ Workflow Type"
grep -E "^##? Task Scope" spec.md && echo "✓ Task Scope"
grep -E "^##? Success Criteria" spec.md && echo "✓ Success Criteria"

# Check file length (should be substantial)
wc -l spec.md
```

If any section is missing, add it immediately.

---

## PHASE 4: SIGNAL COMPLETION

```
=== SPEC DOCUMENT CREATED ===

File: spec.md
Sections: [list of sections]
Length: [line count] lines

Required sections: ✓ All present

Next phase: Implementation Planning
```

---

## CRITICAL RULES

1. **ALWAYS create spec.md** - The orchestrator checks for this file
2. **Include ALL required sections** - Overview, Workflow Type, Task Scope, Success Criteria
3. **Use information from input files** - Don't make up data
4. **Be specific about files** - Use exact paths from context.json
5. **Include QA criteria** - The QA agent needs this for validation

---

## COMMON ISSUES TO AVOID

1. **Missing sections** - Every required section must exist
2. **Empty tables** - Fill in tables with data from context
3. **Generic content** - Be specific to this project and task
4. **Invalid markdown** - Check table formatting, code blocks
5. **Too short** - Spec should be comprehensive (500+ chars)

---

## ERROR RECOVERY

If spec.md is invalid or incomplete:

```bash
# Read current state
cat spec.md

# Identify what's missing
grep -E "^##" spec.md  # See what sections exist

# Append missing sections or rewrite
cat >> spec.md << 'EOF'
## [Missing Section]

[Content]
EOF

# Or rewrite entirely if needed
cat > spec.md << 'EOF'
[Complete spec]
EOF
```

---

## BEGIN

Start by reading all input files (project_index.json, requirements.json, context.json), then write the complete spec.md.