{"owner":"AndyMik90","repo":"Aperant","hasSkills":true,"totalSkillsCount":2,"totalTokensCount":5448,"categories":["claude-rule","command-prompt"],"hasMcp":false,"mcpConfig":null,"found":["CLAUDE.md",".claude/commands/setup-statusline.md"],"skills":{"CLAUDE.md":"# CLAUDE.md\n\nThis file provides guidance to Claude Code when working with this repository.\n\nAuto Claude is an autonomous multi-agent coding framework that plans, builds, and validates software for you. It's a TypeScript-first Electron desktop application with a self-contained AI agent layer (Vercel AI SDK v6). A lightweight Python sidecar provides the optional Graphiti memory system.\n\n> **Deep-dive reference:** [ARCHITECTURE.md](shared_docs/ARCHITECTURE.md) | **Frontend contributing:** [apps/desktop/CONTRIBUTING.md](apps/desktop/CONTRIBUTING.md)\n\n## Product Overview\n\nAuto Claude is a desktop application (+ CLI) where users describe a goal and AI agents autonomously handle planning, implementation, and QA validation. All work happens in isolated git worktrees so the main branch stays safe.\n\n**Core workflow:** User creates a task → Spec creation pipeline assesses complexity and writes a specification → Planner agent breaks it into subtasks → Coder agent implements (can spawn parallel subagents) → QA reviewer validates → QA fixer resolves issues → User reviews and merges.\n\n**Main features:**\n\n- **Autonomous Tasks** — Multi-agent pipeline (planner, coder, QA) that builds features end-to-end\n- **Kanban Board** — Visual task management from planning through completion\n- **Agent Terminals** — Up to 12 parallel AI-powered terminals with task context injection\n- **Insights** — AI chat interface for exploring and understanding your codebase\n- **Roadmap** — AI-assisted feature planning with strategic roadmap generation\n- **Ideation** — Discover improvements, performance issues, and security vulnerabilities\n- **GitHub/GitLab Integration** — Import issues, AI-powered investigation, PR/MR review and creation\n- **Changelog** — Generate release notes from completed tasks\n- **Memory System** — Graphiti-based knowledge graph retains insights across sessions\n- **Isolated Workspaces** — Git worktree isolation for every build; AI-powered semantic merge\n- **Flexible Authentication** — Use a Claude Code subscription (OAuth) or API profiles with any Anthropic-compatible endpoint (e.g., Anthropic API, z.ai for GLM models)\n- **Multi-Account Swapping** — Register multiple Claude accounts; when one hits a rate limit, Auto Claude automatically switches to an available account\n- **Cross-Platform** — Native desktop app for Windows, macOS, and Linux with auto-updates\n\n## Critical Rules\n\n**Vercel AI SDK only** — All AI interactions use the Vercel AI SDK v6 (`ai` package) via the TypeScript agent layer in `apps/desktop/src/main/ai/`. NEVER use `@anthropic-ai/sdk` or `anthropic.Anthropic()` directly. Use `createProvider()` from `ai/providers/factory.ts` and `streamText()`/`generateText()` from the `ai` package. Provider-specific adapters (e.g., `@ai-sdk/anthropic`, `@ai-sdk/openai`) are managed through the provider registry.\n\n**i18n required** — All frontend user-facing text uses `react-i18next` translation keys. Hardcoded strings in JSX/TSX break localization for non-English users. Add keys to both `en/*.json` and `fr/*.json`.\n\n**Platform abstraction** — Never use `process.platform` directly. Import from `apps/desktop/src/main/platform/`. CI tests all three platforms.\n\n**No time estimates** — Provide priority-based ordering instead of duration predictions.\n\n**PR target** — Always target the `develop` branch for PRs, not `main`. Main is reserved for releases.\n\n**No console.log in production code** — `console.log` output is invisible in bundled Electron apps. Use Sentry for error tracking in production; reserve `console.log` for development only.\n\n## Work Approach: Orchestrator-First\n\nYou are an orchestrator. Your primary role is to understand what needs to be done, break it into workstreams, and delegate execution to agent teams. This keeps your context window focused on coordination and decision-making rather than filling up with implementation details.\n\n<orchestrator_pattern>\nWhen given a task, follow this pattern:\n\n1. **Investigate first** — Read the actual code before forming any hypothesis. Use targeted searches (Glob, Grep, Read) for simple lookups. For broader exploration, spawn an Explore agent.\n\n2. **Plan the approach** — Identify what needs to change, which files are involved, and whether work can be parallelized. For multi-step tasks, create a task list to track workstreams.\n\n3. **Delegate execution** — Spawn agent teams to do the implementation work. Each agent gets a clear, self-contained assignment with all the context it needs: relevant file paths, the specific change to make, and acceptance criteria. Run independent workstreams in parallel.\n\n4. **Verify and integrate** — Review agent outputs, run tests, and ensure changes work together. Fix integration issues or spawn follow-up agents as needed.\n</orchestrator_pattern>\n\n**When to delegate vs. do directly:**\n- Delegate: multi-file changes, research across the codebase, independent parallel workstreams, tasks that would consume significant context\n- Do directly: single-file edits, simple bug fixes, quick lookups, tasks where you already have the context\n\n**Giving agents good assignments** — Each agent works with a fresh context. Include: the specific goal, relevant file paths, code patterns to follow, and what \"done\" looks like. Agents perform better with explicit, complete instructions than with vague references to \"the current task.\"\n\n**Minimal changes only** — Prefer the simplest approach (e.g., prompt-only changes, single guard clause) before suggesting multi-component solutions. If the user asks for X, implement X — don't bundle additional fixes they didn't request.\n\n**Default to action** — When the user's intent implies making changes, implement them rather than only suggesting. If something is unclear, read the relevant code to fill in the gaps rather than asking. Only ask when genuine ambiguity remains about what the user wants.\n\n## Context Management\n\nYour context window will be automatically compacted as it approaches its limit, allowing you to continue working indefinitely. Do not stop tasks early due to context concerns — instead, persist progress and keep going.\n\n**For long-running tasks:** Use git commits, task lists, and structured notes to track state. When context compacts, review git log and any progress files to re-orient. Focus on incremental progress — complete one component before moving to the next, and commit working states along the way.\n\n**Parallel tool calls** — When reading multiple files, running independent searches, or executing unrelated commands, make all calls in parallel rather than sequentially. This significantly speeds up investigation and implementation.\n\n## Known Gotchas\n\n**Electron path resolution** — For bug fixes in the Electron app, check path resolution differences between dev and production builds (`app.isPackaged`, `process.resourcesPath`). Paths that work in dev often break when Electron is bundled for production — verify both contexts.\n\n### Resetting PR Review State\n\nTo fully clear all PR review data so reviews run fresh, delete/reset these three things in `.auto-claude/github/`:\n\n1. `rm .auto-claude/github/pr/logs_*.json` — review log files\n2. `rm .auto-claude/github/pr/review_*.json` — review result files\n3. Reset `pr/index.json` to `{\"reviews\": [], \"last_updated\": null}`\n4. Reset `bot_detection_state.json` to `{\"reviewed_commits\": {}}` — this is the gatekeeper; without clearing it, the bot detector skips already-seen commits\n\n## Project Structure\n\n```\nautonomous-coding/\n├── apps/\n│   └── desktop/                 # Electron desktop application (sole app)\n│       ├── prompts/             # Agent system prompts (.md)\n│       └── src/\n│           ├── main/            # Electron main process\n│           │   ├── ai/          # TypeScript AI agent layer (Vercel AI SDK v6)\n│           │   │   ├── providers/   # Multi-provider registry + factory (9+ providers)\n│           │   │   ├── tools/       # Builtin tools (Read, Write, Edit, Bash, Glob, Grep, etc.)\n│           │   │   ├── security/    # Bash validator, command parser, path containment\n│           │   │   ├── config/      # Agent configs (25+ types), phase config, model resolution\n│           │   │   ├── session/     # streamText() agent loop, error classification, progress\n│           │   │   ├── agent/       # Worker thread executor + bridge\n│           │   │   ├── orchestration/ # Build pipeline (planner → coder → QA)\n│           │   │   ├── runners/     # Utility runners (insights, roadmap, PR review, etc.)\n│           │   │   ├── mcp/         # MCP client integration\n│           │   │   ├── client/      # Client factory convenience constructors\n│           │   │   └── auth/        # Token resolution (reuses claude-profile/)\n│           │   ├── agent/       # Agent queue, process, state, events\n│           │   ├── claude-profile/ # Multi-profile credentials, token refresh, usage\n│           │   ├── terminal/    # PTY daemon, lifecycle, Claude integration\n│           │   ├── platform/    # Cross-platform abstraction\n│           │   ├── ipc-handlers/# 40+ handler modules by domain\n│           │   ├── services/    # Session recovery, profile service\n│           │   └── changelog/   # Changelog generation and formatting\n│           ├── preload/         # Electron preload scripts (electronAPI bridge)\n│           ├── renderer/        # React UI\n│           │   ├── components/  # UI components (onboarding, settings, task, terminal, github, etc.)\n│           │   ├── stores/      # 24+ Zustand state stores\n│           │   ├── contexts/    # React contexts (ViewStateContext)\n│           │   ├── hooks/       # Custom hooks (useIpc, useTerminal, etc.)\n│           │   ├── styles/      # CSS / Tailwind styles\n│           │   └── App.tsx      # Root component\n│           ├── shared/          # Shared types, i18n, constants, utils\n│           │   ├── i18n/locales/# en/*.json, fr/*.json\n│           │   ├── constants/   # themes.ts, etc.\n│           │   ├── types/       # 19+ type definition files\n│           │   └── utils/       # ANSI sanitizer, shell escape, provider detection\n│           └── types/           # TypeScript type definitions\n├── guides/                      # Documentation\n└── scripts/                     # Build and utility scripts\n```\n\n## Commands Quick Reference\n\n### Setup\n```bash\nnpm run install:all              # Install all dependencies from root\n# Or separately:\ncd apps/desktop && npm install\n```\n\n### Testing\n\n| Stack | Command | Tool |\n|-------|---------|------|\n| Frontend unit | `cd apps/desktop && npm test` | Vitest |\n| Frontend E2E | `cd apps/desktop && npm run test:e2e` | Playwright |\n\n### Releases\n```bash\nnode scripts/bump-version.js patch|minor|major  # Bump version\ngit push && gh pr create --base main             # PR to main triggers release\n```\n\nSee [RELEASE.md](RELEASE.md) for full release process.\n\n## AI Agent Layer (`apps/desktop/src/main/ai/`)\n\nAll AI agent logic lives in TypeScript using the Vercel AI SDK v6. This replaces the previous Python `claude-agent-sdk` integration.\n\n### Architecture Overview\n\n- **Provider Layer** (`providers/`) — Multi-provider support via `createProviderRegistry()`. Supports Anthropic, OpenAI, Google, Bedrock, Azure, Mistral, Groq, xAI, and Ollama. Provider-specific transforms handle thinking token normalization and prompt caching.\n- **Session Runtime** (`session/`) — `runAgentSession()` uses `streamText()` with `stopWhen: stepCountIs(N)` for agentic tool-use loops. Includes error classification (429/401/400) and progress tracking.\n- **Worker Threads** (`agent/`) — Agent sessions run in `worker_threads` to avoid blocking the Electron main process. The `WorkerBridge` relays `postMessage()` events to the existing `AgentManagerEvents` interface.\n- **Build Orchestration** (`orchestration/`) — Full planner → coder → QA pipeline. Parallel subagent execution via `Promise.allSettled()`.\n- **Tools** (`tools/`) — 8 builtin tools (Read, Write, Edit, Bash, Glob, Grep, WebFetch, WebSearch) defined with Zod schemas via AI SDK `tool()`.\n- **Security** (`security/`) — Bash validator, command parser, and path containment ported from Python with identical allowlist behavior.\n- **Config** (`config/`) — `AGENT_CONFIGS` registry (25+ agent types), phase-aware model resolution, thinking budgets.\n\n### Key Patterns\n\n```typescript\n// Agent session using streamText()\nimport { streamText, stepCountIs } from 'ai';\n\nconst result = streamText({\n  model: provider,\n  system: systemPrompt,\n  messages: conversationHistory,\n  tools: toolRegistry.getToolsForAgent(agentType),\n  stopWhen: stepCountIs(1000),\n  onStepFinish: ({ toolCalls, text, usage }) => {\n    progressTracker.update(toolCalls, text);\n  },\n});\n\n// Tool definition with Zod schema\nimport { tool } from 'ai';\nimport { z } from 'zod';\n\nconst readTool = tool({\n  description: 'Read a file from the filesystem',\n  inputSchema: z.object({\n    file_path: z.string(),\n    offset: z.number().optional(),\n    limit: z.number().optional(),\n  }),\n  execute: async ({ file_path, offset, limit }) => { /* ... */ },\n});\n```\n\n### Agent Prompts (`apps/desktop/prompts/`)\n\n| Prompt | Purpose |\n|--------|---------|\n| planner.md | Implementation plan with subtasks |\n| coder.md / coder_recovery.md | Subtask implementation / recovery |\n| qa_reviewer.md / qa_fixer.md | Acceptance validation / issue fixes |\n| spec_gatherer/researcher/writer/critic.md | Spec creation pipeline |\n| complexity_assessor.md | AI-based complexity assessment |\n\n### Spec Directory Structure\n\nEach spec in `.auto-claude/specs/XXX-name/` contains: `spec.md`, `requirements.json`, `context.json`, `implementation_plan.json`, `qa_report.md`, `QA_FIX_REQUEST.md`\n\n### Memory System (Graphiti)\n\nGraph-based semantic memory accessed via a Python MCP sidecar (lives outside `apps/desktop/`). The AI layer connects to it via `createMCPClient` from `@ai-sdk/mcp`. Configured through the Electron app's onboarding/settings UI. See [ARCHITECTURE.md](shared_docs/ARCHITECTURE.md#memory-system) for details.\n\n## Frontend Development\n\n### Tech Stack\n\nReact 19, TypeScript (strict), Electron 39, Vercel AI SDK v6, Zustand 5, Tailwind CSS v4, Radix UI, xterm.js 6, Vite 7, Vitest 4, Biome 2, Motion (Framer Motion)\n\n### Path Aliases (tsconfig.json)\n\n| Alias | Maps to |\n|-------|---------|\n| `@/*` | `src/renderer/*` |\n| `@shared/*` | `src/shared/*` |\n| `@preload/*` | `src/preload/*` |\n| `@features/*` | `src/renderer/features/*` |\n| `@components/*` | `src/renderer/shared/components/*` |\n| `@hooks/*` | `src/renderer/shared/hooks/*` |\n| `@lib/*` | `src/renderer/shared/lib/*` |\n\n### State Management (Zustand)\n\nAll state lives in `src/renderer/stores/`. Key stores:\n\n- `project-store.ts` — Active project, project list\n- `task-store.ts` — Tasks/specs management\n- `terminal-store.ts` — Terminal sessions and state\n- `settings-store.ts` — User preferences\n- `github/issues-store.ts`, `github/pr-review-store.ts` — GitHub integration\n- `insights-store.ts`, `roadmap-store.ts`, `kanban-settings-store.ts`\n\nMain process also has stores: `src/main/project-store.ts`, `src/main/terminal-session-store.ts`\n\n### Styling\n\n- **Tailwind CSS v4** with `@tailwindcss/postcss` plugin\n- **7 color themes** (Default, Dusk, Lime, Ocean, Retro, Neo + more) defined in `src/shared/constants/themes.ts`\n- Each theme has light/dark mode variants via CSS custom properties\n- Utility: `clsx` + `tailwind-merge` via `cn()` helper\n- Component variants: `class-variance-authority` (CVA)\n\n### IPC Communication\n\nMain ↔ Renderer communication via Electron IPC:\n- **Handlers:** `src/main/ipc-handlers/` — organized by domain (github, gitlab, ideation, context, etc.)\n- **Preload:** `src/preload/` — exposes safe APIs to renderer\n- Pattern: renderer calls via `window.electronAPI.*`, main handles in IPC handler modules\n\n### Agent Management (`src/main/agent/`)\n\nThe frontend manages agent lifecycle end-to-end:\n- **`agent-queue.ts`** — Queue routing, prioritization, spec number locking\n- **`agent-process.ts`** — Spawns worker threads via `WorkerBridge` for agent execution\n- **`agent-state.ts`** — Tracks running agent state and status\n- **`agent-events.ts`** — Agent lifecycle events and state transitions (structured events from worker threads)\n\n### Claude Profile System (`src/main/claude-profile/`)\n\nMulti-profile credential management for switching between Claude accounts:\n- **`credential-utils.ts`** — OS credential storage (Keychain/Windows Credential Manager)\n- **`token-refresh.ts`** — OAuth token lifecycle and automatic refresh\n- **`usage-monitor.ts`** — API usage tracking and rate limiting per profile\n- **`profile-scorer.ts`** — Scores profiles by usage and availability\n\n### Terminal System (`src/main/terminal/`)\n\nFull PTY-based terminal integration:\n- **`pty-daemon.ts`** / **`pty-manager.ts`** — Background PTY process management\n- **`terminal-lifecycle.ts`** — Session creation, cleanup, event handling\n- **`claude-integration-handler.ts`** — Claude SDK integration within terminals\n- Renderer: xterm.js 6 with WebGL, fit, web-links, serialize addons. Store: `terminal-store.ts`\n\n## Code Quality\n\n### Frontend\n- **Linting:** Biome (`npm run lint` / `npm run lint:fix`)\n- **Type checking:** `npm run typecheck` (strict mode)\n- **Pre-commit:** Husky + lint-staged runs Biome on staged `.ts/.tsx/.js/.jsx/.json`\n- **Testing:** Vitest + React Testing Library + jsdom\n\n\n## i18n Guidelines\n\nAll frontend UI text uses `react-i18next`. Translation files: `apps/desktop/src/shared/i18n/locales/{en,fr}/*.json`\n\n**Namespaces:** `common`, `navigation`, `settings`, `dialogs`, `tasks`, `errors`, `onboarding`, `welcome`\n\n```tsx\nimport { useTranslation } from 'react-i18next';\nconst { t } = useTranslation(['navigation', 'common']);\n\n<span>{t('navigation:items.githubPRs')}</span>     // CORRECT\n<span>GitHub PRs</span>                             // WRONG\n\n// With interpolation:\n<span>{t('errors:task.parseError', { error })}</span>\n```\n\nWhen adding new UI text: add keys to ALL language files, use `namespace:section.key` format.\n\n## Cross-Platform\n\nSupports Windows, macOS, Linux. CI tests all three.\n\n**Platform modules:** `apps/desktop/src/main/platform/`\n\n| Function | Purpose |\n|----------|---------|\n| `isWindows()` / `isMacOS()` / `isLinux()` | OS detection |\n| `getPathDelimiter()` | `;` (Win) or `:` (Unix) |\n| `findExecutable(name)` | Cross-platform executable lookup |\n| `requiresShell(command)` | `.cmd/.bat` shell detection (Win) |\n\nUse `findExecutable()` and `joinPaths()` instead of hardcoded paths. See [ARCHITECTURE.md](shared_docs/ARCHITECTURE.md#cross-platform-development) for extended guide.\n\n## E2E Testing (Electron MCP)\n\nQA agents can interact with the running Electron app via Chrome DevTools Protocol:\n\n1. Start app: `npm run dev:debug` (debug mode for AI self-validation via Electron MCP)\n2. Enable Electron MCP in settings\n3. QA runs automatically through the TypeScript agent pipeline\n\nTools: `take_screenshot`, `click_by_text`, `fill_input`, `get_page_structure`, `send_keyboard_shortcut`, `eval`. See [ARCHITECTURE.md](shared_docs/ARCHITECTURE.md#end-to-end-testing) for full capabilities.\n\n## Running the Application\n\n```bash\n# Desktop app\nnpm start          # Production build + run\nnpm run dev        # Development mode with HMR\nnpm run dev:debug  # Debug mode with verbose output\nnpm run dev:mcp    # Electron MCP server for AI debugging\n\n# Project data: .auto-claude/specs/ (gitignored)\n```\n",".claude/commands/setup-statusline.md":"# Setup ccstatusline Integration for Auto-Build\n\nConfigure ccstatusline to display real-time auto-claude progress in your Claude Code status bar.\n\n## Prerequisites\n\n1. **ccstatusline** must be installed and configured\n2. **auto-claude** must be in your project\n\n## Installation\n\n### Step 1: Install ccstatusline (if not already installed)\n\n```bash\n# Using npx\nnpx ccstatusline@latest\n\n# Or using bunx\nbunx ccstatusline@latest\n```\n\nThis launches the interactive TUI to configure your status line.\n\n### Step 2: Add Custom Command Widget\n\nIn the ccstatusline TUI config, add a **Custom Command** widget with:\n\n```\nCommand: python /path/to/your/project/auto-claude/statusline.py --format compact\n```\n\n**Recommended widget settings:**\n- Position: Left or center of status line\n- Update interval: 5 seconds (default)\n- Show only when active: Yes (recommended)\n\n### Step 3: Alternative - JSON Config\n\nEdit `~/.config/ccstatusline/settings.json` and add to your widgets array:\n\n```json\n{\n  \"type\": \"custom\",\n  \"command\": \"python /path/to/your/project/auto-claude/statusline.py --format compact\",\n  \"interval\": 5,\n  \"showWhenEmpty\": false\n}\n```\n\n## Output Formats\n\nThe statusline.py script supports three output formats:\n\n### Compact (recommended for status line)\n```\n--format compact\n```\nOutput: `▣ 3/12 | ◆ Setup → | ⚡2 | 25%`\n\nShows: chunks completed/total | current phase | active workers | progress %\n\n### Full (detailed multi-line)\n```\n--format full\n```\nOutput:\n```\nAUTO-BUILD: my-feature\nState: BUILDING\nChunks: 3/12 (1 in progress)\nPhase: 2/4 - Setup\nWorkers: 2 active\n```\n\n### JSON (for scripting)\n```\n--format json\n```\nOutput: Raw JSON status data\n\n## Status File\n\nAuto-build writes status to `.auto-claude-status` in your project root:\n\n```json\n{\n  \"active\": true,\n  \"spec\": \"001-feature\",\n  \"state\": \"building\",\n  \"chunks\": {\n    \"completed\": 3,\n    \"in_progress\": 1,\n    \"pending\": 8,\n    \"total\": 12\n  },\n  \"phase\": {\n    \"current\": \"Setup\",\n    \"id\": 2,\n    \"total\": 4\n  },\n  \"workers\": {\n    \"active\": 2,\n    \"max\": 3\n  }\n}\n```\n\n## Icons Reference\n\nWhen active, you'll see these indicators:\n\n| Icon | Meaning |\n|------|---------|\n| ▣/▢ | Chunk progress (filled/empty) |\n| ◆ | Current phase |\n| ⚡ | Active workers |\n| → | In progress indicator |\n| ✓ | Completed |\n| ✗ | Error |\n\n## Troubleshooting\n\n### Status not showing?\n1. Check if `.auto-claude-status` exists in your project root\n2. Verify the path to `statusline.py` is correct\n3. Try running the command manually: `python auto-claude/statusline.py --format compact`\n\n### Updates too slow?\n- Decrease the polling interval in ccstatusline config (minimum 1 second)\n\n### Wrong project directory?\n- Use `--project-dir /path/to/project` to specify the project root explicitly\n\n## Example Configurations\n\n### Minimal Status Line\nJust chunks and phase:\n```\npython auto-claude/statusline.py --format compact\n```\n\n### With Specific Spec\nMonitor a specific spec:\n```\npython auto-claude/statusline.py --format compact --spec 001-my-feature\n```\n\n### Full Path for Global Use\n```\npython ~/projects/my-app/auto-claude/statusline.py --format compact --project-dir ~/projects/my-app\n```\n"},"files":{"CLAUDE.md":"# CLAUDE.md\n\nThis file provides guidance to Claude Code when working with this repository.\n\nAuto Claude is an autonomous multi-agent coding framework that plans, builds, and validates software for you. It's a TypeScript-first Electron desktop application with a self-contained AI agent layer (Vercel AI SDK v6). A lightweight Python sidecar provides the optional Graphiti memory system.\n\n> **Deep-dive reference:** [ARCHITECTURE.md](shared_docs/ARCHITECTURE.md) | **Frontend contributing:** [apps/desktop/CONTRIBUTING.md](apps/desktop/CONTRIBUTING.md)\n\n## Product Overview\n\nAuto Claude is a desktop application (+ CLI) where users describe a goal and AI agents autonomously handle planning, implementation, and QA validation. All work happens in isolated git worktrees so the main branch stays safe.\n\n**Core workflow:** User creates a task → Spec creation pipeline assesses complexity and writes a specification → Planner agent breaks it into subtasks → Coder agent implements (can spawn parallel subagents) → QA reviewer validates → QA fixer resolves issues → User reviews and merges.\n\n**Main features:**\n\n- **Autonomous Tasks** — Multi-agent pipeline (planner, coder, QA) that builds features end-to-end\n- **Kanban Board** — Visual task management from planning through completion\n- **Agent Terminals** — Up to 12 parallel AI-powered terminals with task context injection\n- **Insights** — AI chat interface for exploring and understanding your codebase\n- **Roadmap** — AI-assisted feature planning with strategic roadmap generation\n- **Ideation** — Discover improvements, performance issues, and security vulnerabilities\n- **GitHub/GitLab Integration** — Import issues, AI-powered investigation, PR/MR review and creation\n- **Changelog** — Generate release notes from completed tasks\n- **Memory System** — Graphiti-based knowledge graph retains insights across sessions\n- **Isolated Workspaces** — Git worktree isolation for every build; AI-powered semantic merge\n- **Flexible Authentication** — Use a Claude Code subscription (OAuth) or API profiles with any Anthropic-compatible endpoint (e.g., Anthropic API, z.ai for GLM models)\n- **Multi-Account Swapping** — Register multiple Claude accounts; when one hits a rate limit, Auto Claude automatically switches to an available account\n- **Cross-Platform** — Native desktop app for Windows, macOS, and Linux with auto-updates\n\n## Critical Rules\n\n**Vercel AI SDK only** — All AI interactions use the Vercel AI SDK v6 (`ai` package) via the TypeScript agent layer in `apps/desktop/src/main/ai/`. NEVER use `@anthropic-ai/sdk` or `anthropic.Anthropic()` directly. Use `createProvider()` from `ai/providers/factory.ts` and `streamText()`/`generateText()` from the `ai` package. Provider-specific adapters (e.g., `@ai-sdk/anthropic`, `@ai-sdk/openai`) are managed through the provider registry.\n\n**i18n required** — All frontend user-facing text uses `react-i18next` translation keys. Hardcoded strings in JSX/TSX break localization for non-English users. Add keys to both `en/*.json` and `fr/*.json`.\n\n**Platform abstraction** — Never use `process.platform` directly. Import from `apps/desktop/src/main/platform/`. CI tests all three platforms.\n\n**No time estimates** — Provide priority-based ordering instead of duration predictions.\n\n**PR target** — Always target the `develop` branch for PRs, not `main`. Main is reserved for releases.\n\n**No console.log in production code** — `console.log` output is invisible in bundled Electron apps. Use Sentry for error tracking in production; reserve `console.log` for development only.\n\n## Work Approach: Orchestrator-First\n\nYou are an orchestrator. Your primary role is to understand what needs to be done, break it into workstreams, and delegate execution to agent teams. This keeps your context window focused on coordination and decision-making rather than filling up with implementation details.\n\n<orchestrator_pattern>\nWhen given a task, follow this pattern:\n\n1. **Investigate first** — Read the actual code before forming any hypothesis. Use targeted searches (Glob, Grep, Read) for simple lookups. For broader exploration, spawn an Explore agent.\n\n2. **Plan the approach** — Identify what needs to change, which files are involved, and whether work can be parallelized. For multi-step tasks, create a task list to track workstreams.\n\n3. **Delegate execution** — Spawn agent teams to do the implementation work. Each agent gets a clear, self-contained assignment with all the context it needs: relevant file paths, the specific change to make, and acceptance criteria. Run independent workstreams in parallel.\n\n4. **Verify and integrate** — Review agent outputs, run tests, and ensure changes work together. Fix integration issues or spawn follow-up agents as needed.\n</orchestrator_pattern>\n\n**When to delegate vs. do directly:**\n- Delegate: multi-file changes, research across the codebase, independent parallel workstreams, tasks that would consume significant context\n- Do directly: single-file edits, simple bug fixes, quick lookups, tasks where you already have the context\n\n**Giving agents good assignments** — Each agent works with a fresh context. Include: the specific goal, relevant file paths, code patterns to follow, and what \"done\" looks like. Agents perform better with explicit, complete instructions than with vague references to \"the current task.\"\n\n**Minimal changes only** — Prefer the simplest approach (e.g., prompt-only changes, single guard clause) before suggesting multi-component solutions. If the user asks for X, implement X — don't bundle additional fixes they didn't request.\n\n**Default to action** — When the user's intent implies making changes, implement them rather than only suggesting. If something is unclear, read the relevant code to fill in the gaps rather than asking. Only ask when genuine ambiguity remains about what the user wants.\n\n## Context Management\n\nYour context window will be automatically compacted as it approaches its limit, allowing you to continue working indefinitely. Do not stop tasks early due to context concerns — instead, persist progress and keep going.\n\n**For long-running tasks:** Use git commits, task lists, and structured notes to track state. When context compacts, review git log and any progress files to re-orient. Focus on incremental progress — complete one component before moving to the next, and commit working states along the way.\n\n**Parallel tool calls** — When reading multiple files, running independent searches, or executing unrelated commands, make all calls in parallel rather than sequentially. This significantly speeds up investigation and implementation.\n\n## Known Gotchas\n\n**Electron path resolution** — For bug fixes in the Electron app, check path resolution differences between dev and production builds (`app.isPackaged`, `process.resourcesPath`). Paths that work in dev often break when Electron is bundled for production — verify both contexts.\n\n### Resetting PR Review State\n\nTo fully clear all PR review data so reviews run fresh, delete/reset these three things in `.auto-claude/github/`:\n\n1. `rm .auto-claude/github/pr/logs_*.json` — review log files\n2. `rm .auto-claude/github/pr/review_*.json` — review result files\n3. Reset `pr/index.json` to `{\"reviews\": [], \"last_updated\": null}`\n4. Reset `bot_detection_state.json` to `{\"reviewed_commits\": {}}` — this is the gatekeeper; without clearing it, the bot detector skips already-seen commits\n\n## Project Structure\n\n```\nautonomous-coding/\n├── apps/\n│   └── desktop/                 # Electron desktop application (sole app)\n│       ├── prompts/             # Agent system prompts (.md)\n│       └── src/\n│           ├── main/            # Electron main process\n│           │   ├── ai/          # TypeScript AI agent layer (Vercel AI SDK v6)\n│           │   │   ├── providers/   # Multi-provider registry + factory (9+ providers)\n│           │   │   ├── tools/       # Builtin tools (Read, Write, Edit, Bash, Glob, Grep, etc.)\n│           │   │   ├── security/    # Bash validator, command parser, path containment\n│           │   │   ├── config/      # Agent configs (25+ types), phase config, model resolution\n│           │   │   ├── session/     # streamText() agent loop, error classification, progress\n│           │   │   ├── agent/       # Worker thread executor + bridge\n│           │   │   ├── orchestration/ # Build pipeline (planner → coder → QA)\n│           │   │   ├── runners/     # Utility runners (insights, roadmap, PR review, etc.)\n│           │   │   ├── mcp/         # MCP client integration\n│           │   │   ├── client/      # Client factory convenience constructors\n│           │   │   └── auth/        # Token resolution (reuses claude-profile/)\n│           │   ├── agent/       # Agent queue, process, state, events\n│           │   ├── claude-profile/ # Multi-profile credentials, token refresh, usage\n│           │   ├── terminal/    # PTY daemon, lifecycle, Claude integration\n│           │   ├── platform/    # Cross-platform abstraction\n│           │   ├── ipc-handlers/# 40+ handler modules by domain\n│           │   ├── services/    # Session recovery, profile service\n│           │   └── changelog/   # Changelog generation and formatting\n│           ├── preload/         # Electron preload scripts (electronAPI bridge)\n│           ├── renderer/        # React UI\n│           │   ├── components/  # UI components (onboarding, settings, task, terminal, github, etc.)\n│           │   ├── stores/      # 24+ Zustand state stores\n│           │   ├── contexts/    # React contexts (ViewStateContext)\n│           │   ├── hooks/       # Custom hooks (useIpc, useTerminal, etc.)\n│           │   ├── styles/      # CSS / Tailwind styles\n│           │   └── App.tsx      # Root component\n│           ├── shared/          # Shared types, i18n, constants, utils\n│           │   ├── i18n/locales/# en/*.json, fr/*.json\n│           │   ├── constants/   # themes.ts, etc.\n│           │   ├── types/       # 19+ type definition files\n│           │   └── utils/       # ANSI sanitizer, shell escape, provider detection\n│           └── types/           # TypeScript type definitions\n├── guides/                      # Documentation\n└── scripts/                     # Build and utility scripts\n```\n\n## Commands Quick Reference\n\n### Setup\n```bash\nnpm run install:all              # Install all dependencies from root\n# Or separately:\ncd apps/desktop && npm install\n```\n\n### Testing\n\n| Stack | Command | Tool |\n|-------|---------|------|\n| Frontend unit | `cd apps/desktop && npm test` | Vitest |\n| Frontend E2E | `cd apps/desktop && npm run test:e2e` | Playwright |\n\n### Releases\n```bash\nnode scripts/bump-version.js patch|minor|major  # Bump version\ngit push && gh pr create --base main             # PR to main triggers release\n```\n\nSee [RELEASE.md](RELEASE.md) for full release process.\n\n## AI Agent Layer (`apps/desktop/src/main/ai/`)\n\nAll AI agent logic lives in TypeScript using the Vercel AI SDK v6. This replaces the previous Python `claude-agent-sdk` integration.\n\n### Architecture Overview\n\n- **Provider Layer** (`providers/`) — Multi-provider support via `createProviderRegistry()`. Supports Anthropic, OpenAI, Google, Bedrock, Azure, Mistral, Groq, xAI, and Ollama. Provider-specific transforms handle thinking token normalization and prompt caching.\n- **Session Runtime** (`session/`) — `runAgentSession()` uses `streamText()` with `stopWhen: stepCountIs(N)` for agentic tool-use loops. Includes error classification (429/401/400) and progress tracking.\n- **Worker Threads** (`agent/`) — Agent sessions run in `worker_threads` to avoid blocking the Electron main process. The `WorkerBridge` relays `postMessage()` events to the existing `AgentManagerEvents` interface.\n- **Build Orchestration** (`orchestration/`) — Full planner → coder → QA pipeline. Parallel subagent execution via `Promise.allSettled()`.\n- **Tools** (`tools/`) — 8 builtin tools (Read, Write, Edit, Bash, Glob, Grep, WebFetch, WebSearch) defined with Zod schemas via AI SDK `tool()`.\n- **Security** (`security/`) — Bash validator, command parser, and path containment ported from Python with identical allowlist behavior.\n- **Config** (`config/`) — `AGENT_CONFIGS` registry (25+ agent types), phase-aware model resolution, thinking budgets.\n\n### Key Patterns\n\n```typescript\n// Agent session using streamText()\nimport { streamText, stepCountIs } from 'ai';\n\nconst result = streamText({\n  model: provider,\n  system: systemPrompt,\n  messages: conversationHistory,\n  tools: toolRegistry.getToolsForAgent(agentType),\n  stopWhen: stepCountIs(1000),\n  onStepFinish: ({ toolCalls, text, usage }) => {\n    progressTracker.update(toolCalls, text);\n  },\n});\n\n// Tool definition with Zod schema\nimport { tool } from 'ai';\nimport { z } from 'zod';\n\nconst readTool = tool({\n  description: 'Read a file from the filesystem',\n  inputSchema: z.object({\n    file_path: z.string(),\n    offset: z.number().optional(),\n    limit: z.number().optional(),\n  }),\n  execute: async ({ file_path, offset, limit }) => { /* ... */ },\n});\n```\n\n### Agent Prompts (`apps/desktop/prompts/`)\n\n| Prompt | Purpose |\n|--------|---------|\n| planner.md | Implementation plan with subtasks |\n| coder.md / coder_recovery.md | Subtask implementation / recovery |\n| qa_reviewer.md / qa_fixer.md | Acceptance validation / issue fixes |\n| spec_gatherer/researcher/writer/critic.md | Spec creation pipeline |\n| complexity_assessor.md | AI-based complexity assessment |\n\n### Spec Directory Structure\n\nEach spec in `.auto-claude/specs/XXX-name/` contains: `spec.md`, `requirements.json`, `context.json`, `implementation_plan.json`, `qa_report.md`, `QA_FIX_REQUEST.md`\n\n### Memory System (Graphiti)\n\nGraph-based semantic memory accessed via a Python MCP sidecar (lives outside `apps/desktop/`). The AI layer connects to it via `createMCPClient` from `@ai-sdk/mcp`. Configured through the Electron app's onboarding/settings UI. See [ARCHITECTURE.md](shared_docs/ARCHITECTURE.md#memory-system) for details.\n\n## Frontend Development\n\n### Tech Stack\n\nReact 19, TypeScript (strict), Electron 39, Vercel AI SDK v6, Zustand 5, Tailwind CSS v4, Radix UI, xterm.js 6, Vite 7, Vitest 4, Biome 2, Motion (Framer Motion)\n\n### Path Aliases (tsconfig.json)\n\n| Alias | Maps to |\n|-------|---------|\n| `@/*` | `src/renderer/*` |\n| `@shared/*` | `src/shared/*` |\n| `@preload/*` | `src/preload/*` |\n| `@features/*` | `src/renderer/features/*` |\n| `@components/*` | `src/renderer/shared/components/*` |\n| `@hooks/*` | `src/renderer/shared/hooks/*` |\n| `@lib/*` | `src/renderer/shared/lib/*` |\n\n### State Management (Zustand)\n\nAll state lives in `src/renderer/stores/`. Key stores:\n\n- `project-store.ts` — Active project, project list\n- `task-store.ts` — Tasks/specs management\n- `terminal-store.ts` — Terminal sessions and state\n- `settings-store.ts` — User preferences\n- `github/issues-store.ts`, `github/pr-review-store.ts` — GitHub integration\n- `insights-store.ts`, `roadmap-store.ts`, `kanban-settings-store.ts`\n\nMain process also has stores: `src/main/project-store.ts`, `src/main/terminal-session-store.ts`\n\n### Styling\n\n- **Tailwind CSS v4** with `@tailwindcss/postcss` plugin\n- **7 color themes** (Default, Dusk, Lime, Ocean, Retro, Neo + more) defined in `src/shared/constants/themes.ts`\n- Each theme has light/dark mode variants via CSS custom properties\n- Utility: `clsx` + `tailwind-merge` via `cn()` helper\n- Component variants: `class-variance-authority` (CVA)\n\n### IPC Communication\n\nMain ↔ Renderer communication via Electron IPC:\n- **Handlers:** `src/main/ipc-handlers/` — organized by domain (github, gitlab, ideation, context, etc.)\n- **Preload:** `src/preload/` — exposes safe APIs to renderer\n- Pattern: renderer calls via `window.electronAPI.*`, main handles in IPC handler modules\n\n### Agent Management (`src/main/agent/`)\n\nThe frontend manages agent lifecycle end-to-end:\n- **`agent-queue.ts`** — Queue routing, prioritization, spec number locking\n- **`agent-process.ts`** — Spawns worker threads via `WorkerBridge` for agent execution\n- **`agent-state.ts`** — Tracks running agent state and status\n- **`agent-events.ts`** — Agent lifecycle events and state transitions (structured events from worker threads)\n\n### Claude Profile System (`src/main/claude-profile/`)\n\nMulti-profile credential management for switching between Claude accounts:\n- **`credential-utils.ts`** — OS credential storage (Keychain/Windows Credential Manager)\n- **`token-refresh.ts`** — OAuth token lifecycle and automatic refresh\n- **`usage-monitor.ts`** — API usage tracking and rate limiting per profile\n- **`profile-scorer.ts`** — Scores profiles by usage and availability\n\n### Terminal System (`src/main/terminal/`)\n\nFull PTY-based terminal integration:\n- **`pty-daemon.ts`** / **`pty-manager.ts`** — Background PTY process management\n- **`terminal-lifecycle.ts`** — Session creation, cleanup, event handling\n- **`claude-integration-handler.ts`** — Claude SDK integration within terminals\n- Renderer: xterm.js 6 with WebGL, fit, web-links, serialize addons. Store: `terminal-store.ts`\n\n## Code Quality\n\n### Frontend\n- **Linting:** Biome (`npm run lint` / `npm run lint:fix`)\n- **Type checking:** `npm run typecheck` (strict mode)\n- **Pre-commit:** Husky + lint-staged runs Biome on staged `.ts/.tsx/.js/.jsx/.json`\n- **Testing:** Vitest + React Testing Library + jsdom\n\n\n## i18n Guidelines\n\nAll frontend UI text uses `react-i18next`. Translation files: `apps/desktop/src/shared/i18n/locales/{en,fr}/*.json`\n\n**Namespaces:** `common`, `navigation`, `settings`, `dialogs`, `tasks`, `errors`, `onboarding`, `welcome`\n\n```tsx\nimport { useTranslation } from 'react-i18next';\nconst { t } = useTranslation(['navigation', 'common']);\n\n<span>{t('navigation:items.githubPRs')}</span>     // CORRECT\n<span>GitHub PRs</span>                             // WRONG\n\n// With interpolation:\n<span>{t('errors:task.parseError', { error })}</span>\n```\n\nWhen adding new UI text: add keys to ALL language files, use `namespace:section.key` format.\n\n## Cross-Platform\n\nSupports Windows, macOS, Linux. CI tests all three.\n\n**Platform modules:** `apps/desktop/src/main/platform/`\n\n| Function | Purpose |\n|----------|---------|\n| `isWindows()` / `isMacOS()` / `isLinux()` | OS detection |\n| `getPathDelimiter()` | `;` (Win) or `:` (Unix) |\n| `findExecutable(name)` | Cross-platform executable lookup |\n| `requiresShell(command)` | `.cmd/.bat` shell detection (Win) |\n\nUse `findExecutable()` and `joinPaths()` instead of hardcoded paths. See [ARCHITECTURE.md](shared_docs/ARCHITECTURE.md#cross-platform-development) for extended guide.\n\n## E2E Testing (Electron MCP)\n\nQA agents can interact with the running Electron app via Chrome DevTools Protocol:\n\n1. Start app: `npm run dev:debug` (debug mode for AI self-validation via Electron MCP)\n2. Enable Electron MCP in settings\n3. QA runs automatically through the TypeScript agent pipeline\n\nTools: `take_screenshot`, `click_by_text`, `fill_input`, `get_page_structure`, `send_keyboard_shortcut`, `eval`. See [ARCHITECTURE.md](shared_docs/ARCHITECTURE.md#end-to-end-testing) for full capabilities.\n\n## Running the Application\n\n```bash\n# Desktop app\nnpm start          # Production build + run\nnpm run dev        # Development mode with HMR\nnpm run dev:debug  # Debug mode with verbose output\nnpm run dev:mcp    # Electron MCP server for AI debugging\n\n# Project data: .auto-claude/specs/ (gitignored)\n```\n",".claude/commands/setup-statusline.md":"# Setup ccstatusline Integration for Auto-Build\n\nConfigure ccstatusline to display real-time auto-claude progress in your Claude Code status bar.\n\n## Prerequisites\n\n1. **ccstatusline** must be installed and configured\n2. **auto-claude** must be in your project\n\n## Installation\n\n### Step 1: Install ccstatusline (if not already installed)\n\n```bash\n# Using npx\nnpx ccstatusline@latest\n\n# Or using bunx\nbunx ccstatusline@latest\n```\n\nThis launches the interactive TUI to configure your status line.\n\n### Step 2: Add Custom Command Widget\n\nIn the ccstatusline TUI config, add a **Custom Command** widget with:\n\n```\nCommand: python /path/to/your/project/auto-claude/statusline.py --format compact\n```\n\n**Recommended widget settings:**\n- Position: Left or center of status line\n- Update interval: 5 seconds (default)\n- Show only when active: Yes (recommended)\n\n### Step 3: Alternative - JSON Config\n\nEdit `~/.config/ccstatusline/settings.json` and add to your widgets array:\n\n```json\n{\n  \"type\": \"custom\",\n  \"command\": \"python /path/to/your/project/auto-claude/statusline.py --format compact\",\n  \"interval\": 5,\n  \"showWhenEmpty\": false\n}\n```\n\n## Output Formats\n\nThe statusline.py script supports three output formats:\n\n### Compact (recommended for status line)\n```\n--format compact\n```\nOutput: `▣ 3/12 | ◆ Setup → | ⚡2 | 25%`\n\nShows: chunks completed/total | current phase | active workers | progress %\n\n### Full (detailed multi-line)\n```\n--format full\n```\nOutput:\n```\nAUTO-BUILD: my-feature\nState: BUILDING\nChunks: 3/12 (1 in progress)\nPhase: 2/4 - Setup\nWorkers: 2 active\n```\n\n### JSON (for scripting)\n```\n--format json\n```\nOutput: Raw JSON status data\n\n## Status File\n\nAuto-build writes status to `.auto-claude-status` in your project root:\n\n```json\n{\n  \"active\": true,\n  \"spec\": \"001-feature\",\n  \"state\": \"building\",\n  \"chunks\": {\n    \"completed\": 3,\n    \"in_progress\": 1,\n    \"pending\": 8,\n    \"total\": 12\n  },\n  \"phase\": {\n    \"current\": \"Setup\",\n    \"id\": 2,\n    \"total\": 4\n  },\n  \"workers\": {\n    \"active\": 2,\n    \"max\": 3\n  }\n}\n```\n\n## Icons Reference\n\nWhen active, you'll see these indicators:\n\n| Icon | Meaning |\n|------|---------|\n| ▣/▢ | Chunk progress (filled/empty) |\n| ◆ | Current phase |\n| ⚡ | Active workers |\n| → | In progress indicator |\n| ✓ | Completed |\n| ✗ | Error |\n\n## Troubleshooting\n\n### Status not showing?\n1. Check if `.auto-claude-status` exists in your project root\n2. Verify the path to `statusline.py` is correct\n3. Try running the command manually: `python auto-claude/statusline.py --format compact`\n\n### Updates too slow?\n- Decrease the polling interval in ccstatusline config (minimum 1 second)\n\n### Wrong project directory?\n- Use `--project-dir /path/to/project` to specify the project root explicitly\n\n## Example Configurations\n\n### Minimal Status Line\nJust chunks and phase:\n```\npython auto-claude/statusline.py --format compact\n```\n\n### With Specific Spec\nMonitor a specific spec:\n```\npython auto-claude/statusline.py --format compact --spec 001-my-feature\n```\n\n### Full Path for Global Use\n```\npython ~/projects/my-app/auto-claude/statusline.py --format compact --project-dir ~/projects/my-app\n```\n"},"items":[{"name":"CLAUDE.md","path":"CLAUDE.md","rawUrl":"https://raw.githubusercontent.com/AndyMik90/Aperant/HEAD/CLAUDE.md","title":"Claude Agent Guidelines & System Prompt","category":"claude-rule","format":"markdown","content":"# CLAUDE.md\n\nThis file provides guidance to Claude Code when working with this repository.\n\nAuto Claude is an autonomous multi-agent coding framework that plans, builds, and validates software for you. It's a TypeScript-first Electron desktop application with a self-contained AI agent layer (Vercel AI SDK v6). A lightweight Python sidecar provides the optional Graphiti memory system.\n\n> **Deep-dive reference:** [ARCHITECTURE.md](shared_docs/ARCHITECTURE.md) | **Frontend contributing:** [apps/desktop/CONTRIBUTING.md](apps/desktop/CONTRIBUTING.md)\n\n## Product Overview\n\nAuto Claude is a desktop application (+ CLI) where users describe a goal and AI agents autonomously handle planning, implementation, and QA validation. All work happens in isolated git worktrees so the main branch stays safe.\n\n**Core workflow:** User creates a task → Spec creation pipeline assesses complexity and writes a specification → Planner agent breaks it into subtasks → Coder agent implements (can spawn parallel subagents) → QA reviewer validates → QA fixer resolves issues → User reviews and merges.\n\n**Main features:**\n\n- **Autonomous Tasks** — Multi-agent pipeline (planner, coder, QA) that builds features end-to-end\n- **Kanban Board** — Visual task management from planning through completion\n- **Agent Terminals** — Up to 12 parallel AI-powered terminals with task context injection\n- **Insights** — AI chat interface for exploring and understanding your codebase\n- **Roadmap** — AI-assisted feature planning with strategic roadmap generation\n- **Ideation** — Discover improvements, performance issues, and security vulnerabilities\n- **GitHub/GitLab Integration** — Import issues, AI-powered investigation, PR/MR review and creation\n- **Changelog** — Generate release notes from completed tasks\n- **Memory System** — Graphiti-based knowledge graph retains insights across sessions\n- **Isolated Workspaces** — Git worktree isolation for every build; AI-powered semantic merge\n- **Flexible Authentication** — Use a Claude Code subscription (OAuth) or API profiles with any Anthropic-compatible endpoint (e.g., Anthropic API, z.ai for GLM models)\n- **Multi-Account Swapping** — Register multiple Claude accounts; when one hits a rate limit, Auto Claude automatically switches to an available account\n- **Cross-Platform** — Native desktop app for Windows, macOS, and Linux with auto-updates\n\n## Critical Rules\n\n**Vercel AI SDK only** — All AI interactions use the Vercel AI SDK v6 (`ai` package) via the TypeScript agent layer in `apps/desktop/src/main/ai/`. NEVER use `@anthropic-ai/sdk` or `anthropic.Anthropic()` directly. Use `createProvider()` from `ai/providers/factory.ts` and `streamText()`/`generateText()` from the `ai` package. Provider-specific adapters (e.g., `@ai-sdk/anthropic`, `@ai-sdk/openai`) are managed through the provider registry.\n\n**i18n required** — All frontend user-facing text uses `react-i18next` translation keys. Hardcoded strings in JSX/TSX break localization for non-English users. Add keys to both `en/*.json` and `fr/*.json`.\n\n**Platform abstraction** — Never use `process.platform` directly. Import from `apps/desktop/src/main/platform/`. CI tests all three platforms.\n\n**No time estimates** — Provide priority-based ordering instead of duration predictions.\n\n**PR target** — Always target the `develop` branch for PRs, not `main`. Main is reserved for releases.\n\n**No console.log in production code** — `console.log` output is invisible in bundled Electron apps. Use Sentry for error tracking in production; reserve `console.log` for development only.\n\n## Work Approach: Orchestrator-First\n\nYou are an orchestrator. Your primary role is to understand what needs to be done, break it into workstreams, and delegate execution to agent teams. This keeps your context window focused on coordination and decision-making rather than filling up with implementation details.\n\n<orchestrator_pattern>\nWhen given a task, follow this pattern:\n\n1. **Investigate first** — Read the actual code before forming any hypothesis. Use targeted searches (Glob, Grep, Read) for simple lookups. For broader exploration, spawn an Explore agent.\n\n2. **Plan the approach** — Identify what needs to change, which files are involved, and whether work can be parallelized. For multi-step tasks, create a task list to track workstreams.\n\n3. **Delegate execution** — Spawn agent teams to do the implementation work. Each agent gets a clear, self-contained assignment with all the context it needs: relevant file paths, the specific change to make, and acceptance criteria. Run independent workstreams in parallel.\n\n4. **Verify and integrate** — Review agent outputs, run tests, and ensure changes work together. Fix integration issues or spawn follow-up agents as needed.\n</orchestrator_pattern>\n\n**When to delegate vs. do directly:**\n- Delegate: multi-file changes, research across the codebase, independent parallel workstreams, tasks that would consume significant context\n- Do directly: single-file edits, simple bug fixes, quick lookups, tasks where you already have the context\n\n**Giving agents good assignments** — Each agent works with a fresh context. Include: the specific goal, relevant file paths, code patterns to follow, and what \"done\" looks like. Agents perform better with explicit, complete instructions than with vague references to \"the current task.\"\n\n**Minimal changes only** — Prefer the simplest approach (e.g., prompt-only changes, single guard clause) before suggesting multi-component solutions. If the user asks for X, implement X — don't bundle additional fixes they didn't request.\n\n**Default to action** — When the user's intent implies making changes, implement them rather than only suggesting. If something is unclear, read the relevant code to fill in the gaps rather than asking. Only ask when genuine ambiguity remains about what the user wants.\n\n## Context Management\n\nYour context window will be automatically compacted as it approaches its limit, allowing you to continue working indefinitely. Do not stop tasks early due to context concerns — instead, persist progress and keep going.\n\n**For long-running tasks:** Use git commits, task lists, and structured notes to track state. When context compacts, review git log and any progress files to re-orient. Focus on incremental progress — complete one component before moving to the next, and commit working states along the way.\n\n**Parallel tool calls** — When reading multiple files, running independent searches, or executing unrelated commands, make all calls in parallel rather than sequentially. This significantly speeds up investigation and implementation.\n\n## Known Gotchas\n\n**Electron path resolution** — For bug fixes in the Electron app, check path resolution differences between dev and production builds (`app.isPackaged`, `process.resourcesPath`). Paths that work in dev often break when Electron is bundled for production — verify both contexts.\n\n### Resetting PR Review State\n\nTo fully clear all PR review data so reviews run fresh, delete/reset these three things in `.auto-claude/github/`:\n\n1. `rm .auto-claude/github/pr/logs_*.json` — review log files\n2. `rm .auto-claude/github/pr/review_*.json` — review result files\n3. Reset `pr/index.json` to `{\"reviews\": [], \"last_updated\": null}`\n4. Reset `bot_detection_state.json` to `{\"reviewed_commits\": {}}` — this is the gatekeeper; without clearing it, the bot detector skips already-seen commits\n\n## Project Structure\n\n```\nautonomous-coding/\n├── apps/\n│   └── desktop/                 # Electron desktop application (sole app)\n│       ├── prompts/             # Agent system prompts (.md)\n│       └── src/\n│           ├── main/            # Electron main process\n│           │   ├── ai/          # TypeScript AI agent layer (Vercel AI SDK v6)\n│           │   │   ├── providers/   # Multi-provider registry + factory (9+ providers)\n│           │   │   ├── tools/       # Builtin tools (Read, Write, Edit, Bash, Glob, Grep, etc.)\n│           │   │   ├── security/    # Bash validator, command parser, path containment\n│           │   │   ├── config/      # Agent configs (25+ types), phase config, model resolution\n│           │   │   ├── session/     # streamText() agent loop, error classification, progress\n│           │   │   ├── agent/       # Worker thread executor + bridge\n│           │   │   ├── orchestration/ # Build pipeline (planner → coder → QA)\n│           │   │   ├── runners/     # Utility runners (insights, roadmap, PR review, etc.)\n│           │   │   ├── mcp/         # MCP client integration\n│           │   │   ├── client/      # Client factory convenience constructors\n│           │   │   └── auth/        # Token resolution (reuses claude-profile/)\n│           │   ├── agent/       # Agent queue, process, state, events\n│           │   ├── claude-profile/ # Multi-profile credentials, token refresh, usage\n│           │   ├── terminal/    # PTY daemon, lifecycle, Claude integration\n│           │   ├── platform/    # Cross-platform abstraction\n│           │   ├── ipc-handlers/# 40+ handler modules by domain\n│           │   ├── services/    # Session recovery, profile service\n│           │   └── changelog/   # Changelog generation and formatting\n│           ├── preload/         # Electron preload scripts (electronAPI bridge)\n│           ├── renderer/        # React UI\n│           │   ├── components/  # UI components (onboarding, settings, task, terminal, github, etc.)\n│           │   ├── stores/      # 24+ Zustand state stores\n│           │   ├── contexts/    # React contexts (ViewStateContext)\n│           │   ├── hooks/       # Custom hooks (useIpc, useTerminal, etc.)\n│           │   ├── styles/      # CSS / Tailwind styles\n│           │   └── App.tsx      # Root component\n│           ├── shared/          # Shared types, i18n, constants, utils\n│           │   ├── i18n/locales/# en/*.json, fr/*.json\n│           │   ├── constants/   # themes.ts, etc.\n│           │   ├── types/       # 19+ type definition files\n│           │   └── utils/       # ANSI sanitizer, shell escape, provider detection\n│           └── types/           # TypeScript type definitions\n├── guides/                      # Documentation\n└── scripts/                     # Build and utility scripts\n```\n\n## Commands Quick Reference\n\n### Setup\n```bash\nnpm run install:all              # Install all dependencies from root\n# Or separately:\ncd apps/desktop && npm install\n```\n\n### Testing\n\n| Stack | Command | Tool |\n|-------|---------|------|\n| Frontend unit | `cd apps/desktop && npm test` | Vitest |\n| Frontend E2E | `cd apps/desktop && npm run test:e2e` | Playwright |\n\n### Releases\n```bash\nnode scripts/bump-version.js patch|minor|major  # Bump version\ngit push && gh pr create --base main             # PR to main triggers release\n```\n\nSee [RELEASE.md](RELEASE.md) for full release process.\n\n## AI Agent Layer (`apps/desktop/src/main/ai/`)\n\nAll AI agent logic lives in TypeScript using the Vercel AI SDK v6. This replaces the previous Python `claude-agent-sdk` integration.\n\n### Architecture Overview\n\n- **Provider Layer** (`providers/`) — Multi-provider support via `createProviderRegistry()`. Supports Anthropic, OpenAI, Google, Bedrock, Azure, Mistral, Groq, xAI, and Ollama. Provider-specific transforms handle thinking token normalization and prompt caching.\n- **Session Runtime** (`session/`) — `runAgentSession()` uses `streamText()` with `stopWhen: stepCountIs(N)` for agentic tool-use loops. Includes error classification (429/401/400) and progress tracking.\n- **Worker Threads** (`agent/`) — Agent sessions run in `worker_threads` to avoid blocking the Electron main process. The `WorkerBridge` relays `postMessage()` events to the existing `AgentManagerEvents` interface.\n- **Build Orchestration** (`orchestration/`) — Full planner → coder → QA pipeline. Parallel subagent execution via `Promise.allSettled()`.\n- **Tools** (`tools/`) — 8 builtin tools (Read, Write, Edit, Bash, Glob, Grep, WebFetch, WebSearch) defined with Zod schemas via AI SDK `tool()`.\n- **Security** (`security/`) — Bash validator, command parser, and path containment ported from Python with identical allowlist behavior.\n- **Config** (`config/`) — `AGENT_CONFIGS` registry (25+ agent types), phase-aware model resolution, thinking budgets.\n\n### Key Patterns\n\n```typescript\n// Agent session using streamText()\nimport { streamText, stepCountIs } from 'ai';\n\nconst result = streamText({\n  model: provider,\n  system: systemPrompt,\n  messages: conversationHistory,\n  tools: toolRegistry.getToolsForAgent(agentType),\n  stopWhen: stepCountIs(1000),\n  onStepFinish: ({ toolCalls, text, usage }) => {\n    progressTracker.update(toolCalls, text);\n  },\n});\n\n// Tool definition with Zod schema\nimport { tool } from 'ai';\nimport { z } from 'zod';\n\nconst readTool = tool({\n  description: 'Read a file from the filesystem',\n  inputSchema: z.object({\n    file_path: z.string(),\n    offset: z.number().optional(),\n    limit: z.number().optional(),\n  }),\n  execute: async ({ file_path, offset, limit }) => { /* ... */ },\n});\n```\n\n### Agent Prompts (`apps/desktop/prompts/`)\n\n| Prompt | Purpose |\n|--------|---------|\n| planner.md | Implementation plan with subtasks |\n| coder.md / coder_recovery.md | Subtask implementation / recovery |\n| qa_reviewer.md / qa_fixer.md | Acceptance validation / issue fixes |\n| spec_gatherer/researcher/writer/critic.md | Spec creation pipeline |\n| complexity_assessor.md | AI-based complexity assessment |\n\n### Spec Directory Structure\n\nEach spec in `.auto-claude/specs/XXX-name/` contains: `spec.md`, `requirements.json`, `context.json`, `implementation_plan.json`, `qa_report.md`, `QA_FIX_REQUEST.md`\n\n### Memory System (Graphiti)\n\nGraph-based semantic memory accessed via a Python MCP sidecar (lives outside `apps/desktop/`). The AI layer connects to it via `createMCPClient` from `@ai-sdk/mcp`. Configured through the Electron app's onboarding/settings UI. See [ARCHITECTURE.md](shared_docs/ARCHITECTURE.md#memory-system) for details.\n\n## Frontend Development\n\n### Tech Stack\n\nReact 19, TypeScript (strict), Electron 39, Vercel AI SDK v6, Zustand 5, Tailwind CSS v4, Radix UI, xterm.js 6, Vite 7, Vitest 4, Biome 2, Motion (Framer Motion)\n\n### Path Aliases (tsconfig.json)\n\n| Alias | Maps to |\n|-------|---------|\n| `@/*` | `src/renderer/*` |\n| `@shared/*` | `src/shared/*` |\n| `@preload/*` | `src/preload/*` |\n| `@features/*` | `src/renderer/features/*` |\n| `@components/*` | `src/renderer/shared/components/*` |\n| `@hooks/*` | `src/renderer/shared/hooks/*` |\n| `@lib/*` | `src/renderer/shared/lib/*` |\n\n### State Management (Zustand)\n\nAll state lives in `src/renderer/stores/`. Key stores:\n\n- `project-store.ts` — Active project, project list\n- `task-store.ts` — Tasks/specs management\n- `terminal-store.ts` — Terminal sessions and state\n- `settings-store.ts` — User preferences\n- `github/issues-store.ts`, `github/pr-review-store.ts` — GitHub integration\n- `insights-store.ts`, `roadmap-store.ts`, `kanban-settings-store.ts`\n\nMain process also has stores: `src/main/project-store.ts`, `src/main/terminal-session-store.ts`\n\n### Styling\n\n- **Tailwind CSS v4** with `@tailwindcss/postcss` plugin\n- **7 color themes** (Default, Dusk, Lime, Ocean, Retro, Neo + more) defined in `src/shared/constants/themes.ts`\n- Each theme has light/dark mode variants via CSS custom properties\n- Utility: `clsx` + `tailwind-merge` via `cn()` helper\n- Component variants: `class-variance-authority` (CVA)\n\n### IPC Communication\n\nMain ↔ Renderer communication via Electron IPC:\n- **Handlers:** `src/main/ipc-handlers/` — organized by domain (github, gitlab, ideation, context, etc.)\n- **Preload:** `src/preload/` — exposes safe APIs to renderer\n- Pattern: renderer calls via `window.electronAPI.*`, main handles in IPC handler modules\n\n### Agent Management (`src/main/agent/`)\n\nThe frontend manages agent lifecycle end-to-end:\n- **`agent-queue.ts`** — Queue routing, prioritization, spec number locking\n- **`agent-process.ts`** — Spawns worker threads via `WorkerBridge` for agent execution\n- **`agent-state.ts`** — Tracks running agent state and status\n- **`agent-events.ts`** — Agent lifecycle events and state transitions (structured events from worker threads)\n\n### Claude Profile System (`src/main/claude-profile/`)\n\nMulti-profile credential management for switching between Claude accounts:\n- **`credential-utils.ts`** — OS credential storage (Keychain/Windows Credential Manager)\n- **`token-refresh.ts`** — OAuth token lifecycle and automatic refresh\n- **`usage-monitor.ts`** — API usage tracking and rate limiting per profile\n- **`profile-scorer.ts`** — Scores profiles by usage and availability\n\n### Terminal System (`src/main/terminal/`)\n\nFull PTY-based terminal integration:\n- **`pty-daemon.ts`** / **`pty-manager.ts`** — Background PTY process management\n- **`terminal-lifecycle.ts`** — Session creation, cleanup, event handling\n- **`claude-integration-handler.ts`** — Claude SDK integration within terminals\n- Renderer: xterm.js 6 with WebGL, fit, web-links, serialize addons. Store: `terminal-store.ts`\n\n## Code Quality\n\n### Frontend\n- **Linting:** Biome (`npm run lint` / `npm run lint:fix`)\n- **Type checking:** `npm run typecheck` (strict mode)\n- **Pre-commit:** Husky + lint-staged runs Biome on staged `.ts/.tsx/.js/.jsx/.json`\n- **Testing:** Vitest + React Testing Library + jsdom\n\n\n## i18n Guidelines\n\nAll frontend UI text uses `react-i18next`. Translation files: `apps/desktop/src/shared/i18n/locales/{en,fr}/*.json`\n\n**Namespaces:** `common`, `navigation`, `settings`, `dialogs`, `tasks`, `errors`, `onboarding`, `welcome`\n\n```tsx\nimport { useTranslation } from 'react-i18next';\nconst { t } = useTranslation(['navigation', 'common']);\n\n<span>{t('navigation:items.githubPRs')}</span>     // CORRECT\n<span>GitHub PRs</span>                             // WRONG\n\n// With interpolation:\n<span>{t('errors:task.parseError', { error })}</span>\n```\n\nWhen adding new UI text: add keys to ALL language files, use `namespace:section.key` format.\n\n## Cross-Platform\n\nSupports Windows, macOS, Linux. CI tests all three.\n\n**Platform modules:** `apps/desktop/src/main/platform/`\n\n| Function | Purpose |\n|----------|---------|\n| `isWindows()` / `isMacOS()` / `isLinux()` | OS detection |\n| `getPathDelimiter()` | `;` (Win) or `:` (Unix) |\n| `findExecutable(name)` | Cross-platform executable lookup |\n| `requiresShell(command)` | `.cmd/.bat` shell detection (Win) |\n\nUse `findExecutable()` and `joinPaths()` instead of hardcoded paths. See [ARCHITECTURE.md](shared_docs/ARCHITECTURE.md#cross-platform-development) for extended guide.\n\n## E2E Testing (Electron MCP)\n\nQA agents can interact with the running Electron app via Chrome DevTools Protocol:\n\n1. Start app: `npm run dev:debug` (debug mode for AI self-validation via Electron MCP)\n2. Enable Electron MCP in settings\n3. QA runs automatically through the TypeScript agent pipeline\n\nTools: `take_screenshot`, `click_by_text`, `fill_input`, `get_page_structure`, `send_keyboard_shortcut`, `eval`. See [ARCHITECTURE.md](shared_docs/ARCHITECTURE.md#end-to-end-testing) for full capabilities.\n\n## Running the Application\n\n```bash\n# Desktop app\nnpm start          # Production build + run\nnpm run dev        # Development mode with HMR\nnpm run dev:debug  # Debug mode with verbose output\nnpm run dev:mcp    # Electron MCP server for AI debugging\n\n# Project data: .auto-claude/specs/ (gitignored)\n```\n","isInternal":false,"tokens":4596,"sizeBytes":19940},{"name":"setup-statusline.md","path":".claude/commands/setup-statusline.md","rawUrl":"https://raw.githubusercontent.com/AndyMik90/Aperant/HEAD/.claude/commands/setup-statusline.md","title":"Command: /setup-statusline","category":"command-prompt","format":"markdown","content":"# Setup ccstatusline Integration for Auto-Build\n\nConfigure ccstatusline to display real-time auto-claude progress in your Claude Code status bar.\n\n## Prerequisites\n\n1. **ccstatusline** must be installed and configured\n2. **auto-claude** must be in your project\n\n## Installation\n\n### Step 1: Install ccstatusline (if not already installed)\n\n```bash\n# Using npx\nnpx ccstatusline@latest\n\n# Or using bunx\nbunx ccstatusline@latest\n```\n\nThis launches the interactive TUI to configure your status line.\n\n### Step 2: Add Custom Command Widget\n\nIn the ccstatusline TUI config, add a **Custom Command** widget with:\n\n```\nCommand: python /path/to/your/project/auto-claude/statusline.py --format compact\n```\n\n**Recommended widget settings:**\n- Position: Left or center of status line\n- Update interval: 5 seconds (default)\n- Show only when active: Yes (recommended)\n\n### Step 3: Alternative - JSON Config\n\nEdit `~/.config/ccstatusline/settings.json` and add to your widgets array:\n\n```json\n{\n  \"type\": \"custom\",\n  \"command\": \"python /path/to/your/project/auto-claude/statusline.py --format compact\",\n  \"interval\": 5,\n  \"showWhenEmpty\": false\n}\n```\n\n## Output Formats\n\nThe statusline.py script supports three output formats:\n\n### Compact (recommended for status line)\n```\n--format compact\n```\nOutput: `▣ 3/12 | ◆ Setup → | ⚡2 | 25%`\n\nShows: chunks completed/total | current phase | active workers | progress %\n\n### Full (detailed multi-line)\n```\n--format full\n```\nOutput:\n```\nAUTO-BUILD: my-feature\nState: BUILDING\nChunks: 3/12 (1 in progress)\nPhase: 2/4 - Setup\nWorkers: 2 active\n```\n\n### JSON (for scripting)\n```\n--format json\n```\nOutput: Raw JSON status data\n\n## Status File\n\nAuto-build writes status to `.auto-claude-status` in your project root:\n\n```json\n{\n  \"active\": true,\n  \"spec\": \"001-feature\",\n  \"state\": \"building\",\n  \"chunks\": {\n    \"completed\": 3,\n    \"in_progress\": 1,\n    \"pending\": 8,\n    \"total\": 12\n  },\n  \"phase\": {\n    \"current\": \"Setup\",\n    \"id\": 2,\n    \"total\": 4\n  },\n  \"workers\": {\n    \"active\": 2,\n    \"max\": 3\n  }\n}\n```\n\n## Icons Reference\n\nWhen active, you'll see these indicators:\n\n| Icon | Meaning |\n|------|---------|\n| ▣/▢ | Chunk progress (filled/empty) |\n| ◆ | Current phase |\n| ⚡ | Active workers |\n| → | In progress indicator |\n| ✓ | Completed |\n| ✗ | Error |\n\n## Troubleshooting\n\n### Status not showing?\n1. Check if `.auto-claude-status` exists in your project root\n2. Verify the path to `statusline.py` is correct\n3. Try running the command manually: `python auto-claude/statusline.py --format compact`\n\n### Updates too slow?\n- Decrease the polling interval in ccstatusline config (minimum 1 second)\n\n### Wrong project directory?\n- Use `--project-dir /path/to/project` to specify the project root explicitly\n\n## Example Configurations\n\n### Minimal Status Line\nJust chunks and phase:\n```\npython auto-claude/statusline.py --format compact\n```\n\n### With Specific Spec\nMonitor a specific spec:\n```\npython auto-claude/statusline.py --format compact --spec 001-my-feature\n```\n\n### Full Path for Global Use\n```\npython ~/projects/my-app/auto-claude/statusline.py --format compact --project-dir ~/projects/my-app\n```\n","isInternal":false,"tokens":852,"sizeBytes":3156}],"systemPromptSnippet":"<yakaai_skills repo=\"AndyMik90/Aperant\">\n<!-- File: CLAUDE.md (Tokens: ~4596 | Category: claude-rule) -->\n# CLAUDE.md\n\nThis file provides guidance to Claude Code when working with this repository.\n\nAuto Claude is an autonomous multi-agent coding framework that plans, builds, and validates software for you. It's a TypeScript-first Electron desktop application with a self-contained AI agent layer (Vercel AI SDK v6). A lightweight Python sidecar provides the optional Graphiti memory system.\n\n> **Deep-dive reference:** [ARCHITECTURE.md](shared_docs/ARCHITECTURE.md) | **Frontend contributing:** [apps/desktop/CONTRIBUTING.md](apps/desktop/CONTRIBUTING.md)\n\n## Product Overview\n\nAuto Claude is a desktop application (+ CLI) where users describe a goal and AI agents autonomously handle planning, implementation, and QA validation. All work happens in isolated git worktrees so the main branch stays safe.\n\n**Core workflow:** User creates a task → Spec creation pipeline assesses complexity and writes a specification → Planner agent breaks it into subtasks → Coder agent implements (can spawn parallel subagents) → QA reviewer validates → QA fixer resolves issues → User reviews and merges.\n\n**Main features:**\n\n- **Autonomous Tasks** — Multi-agent pipeline (planner, coder, QA) that builds features end-to-end\n- **Kanban Board** — Visual task management from planning through completion\n- **Agent Terminals** — Up to 12 parallel AI-powered terminals with task context injection\n- **Insights** — AI chat interface for exploring and understanding your codebase\n- **Roadmap** — AI-assisted feature planning with strategic roadmap generation\n- **Ideation** — Discover improvements, performance issues, and security vulnerabilities\n- **GitHub/GitLab Integration** — Import issues, AI-powered investigation, PR/MR review and creation\n- **Changelog** — Generate release notes from completed tasks\n- **Memory System** — Graphiti-based knowledge graph retains insights across sessions\n- **Isolated Workspaces** — Git worktree isolation for every build; AI-powered semantic merge\n- **Flexible Authentication** — Use a Claude Code subscription (OAuth) or API profiles with any Anthropic-compatible endpoint (e.g., Anthropic API, z.ai for GLM models)\n- **Multi-Account Swapping** — Register multiple Claude accounts; when one hits a rate limit, Auto Claude automatically switches to an available account\n- **Cross-Platform** — Native desktop app for Windows, macOS, and Linux with auto-updates\n\n## Critical Rules\n\n**Vercel AI SDK only** — All AI interactions use the Vercel AI SDK v6 (`ai` package) via the TypeScript agent layer in `apps/desktop/src/main/ai/`. NEVER use `@anthropic-ai/sdk` or `anthropic.Anthropic()` directly. Use `createProvider()` from `ai/providers/factory.ts` and `streamText()`/`generateText()` from the `ai` package. Provider-specific adapters (e.g., `@ai-sdk/anthropic`, `@ai-sdk/openai`) are managed through the provider registry.\n\n**i18n required** — All frontend user-facing text uses `react-i18next` translation keys. Hardcoded strings in JSX/TSX break localization for non-English users. Add keys to both `en/*.json` and `fr/*.json`.\n\n**Platform abstraction** — Never use `process.platform` directly. Import from `apps/desktop/src/main/platform/`. CI tests all three platforms.\n\n**No time estimates** — Provide priority-based ordering instead of duration predictions.\n\n**PR target** — Always target the `develop` branch for PRs, not `main`. Main is reserved for releases.\n\n**No console.log in production code** — `console.log` output is invisible in bundled Electron apps. Use Sentry for error tracking in production; reserve `console.log` for development only.\n\n## Work Approach: Orchestrator-First\n\nYou are an orchestrator. Your primary role is to understand what needs to be done, break it into workstreams, and delegate execution to agent teams. This keeps your context window focused on coordination and decision-making rather than filling up with implementation details.\n\n<orchestrator_pattern>\nWhen given a task, follow this pattern:\n\n1. **Investigate first** — Read the actual code before forming any hypothesis. Use targeted searches (Glob, Grep, Read) for simple lookups. For broader exploration, spawn an Explore agent.\n\n2. **Plan the approach** — Identify what needs to change, which files are involved, and whether work can be parallelized. For multi-step tasks, create a task list to track workstreams.\n\n3. **Delegate execution** — Spawn agent teams to do the implementation work. Each agent gets a clear, self-contained assignment with all the context it needs: relevant file paths, the specific change to make, and acceptance criteria. Run independent workstreams in parallel.\n\n4. **Verify and integrate** — Review agent outputs, run tests, and ensure changes work together. Fix integration issues or spawn follow-up agents as needed.\n</orchestrator_pattern>\n\n**When to delegate vs. do directly:**\n- Delegate: multi-file changes, research across the codebase, independent parallel workstreams, tasks that would consume significant context\n- Do directly: single-file edits, simple bug fixes, quick lookups, tasks where you already have the context\n\n**Giving agents good assignments** — Each agent works with a fresh context. Include: the specific goal, relevant file paths, code patterns to follow, and what \"done\" looks like. Agents perform better with explicit, complete instructions than with vague references to \"the current task.\"\n\n**Minimal changes only** — Prefer the simplest approach (e.g., prompt-only changes, single guard clause) before suggesting multi-component solutions. If the user asks for X, implement X — don't bundle additional fixes they didn't request.\n\n**Default to action** — When the user's intent implies making changes, implement them rather than only suggesting. If something is unclear, read the relevant code to fill in the gaps rather than asking. Only ask when genuine ambiguity remains about what the user wants.\n\n## Context Management\n\nYour context window will be automatically compacted as it approaches its limit, allowing you to continue working indefinitely. Do not stop tasks early due to context concerns — instead, persist progress and keep going.\n\n**For long-running tasks:** Use git commits, task lists, and structured notes to track state. When context compacts, review git log and any progress files to re-orient. Focus on incremental progress — complete one component before moving to the next, and commit working states along the way.\n\n**Parallel tool calls** — When reading multiple files, running independent searches, or executing unrelated commands, make all calls in parallel rather than sequentially. This significantly speeds up investigation and implementation.\n\n## Known Gotchas\n\n**Electron path resolution** — For bug fixes in the Electron app, check path resolution differences between dev and production builds (`app.isPackaged`, `process.resourcesPath`). Paths that work in dev often break when Electron is bundled for production — verify both contexts.\n\n### Resetting PR Review State\n\nTo fully clear all PR review data so reviews run fresh, delete/reset these three things in `.auto-claude/github/`:\n\n1. `rm .auto-claude/github/pr/logs_*.json` — review log files\n2. `rm .auto-claude/github/pr/review_*.json` — review result files\n3. Reset `pr/index.json` to `{\"reviews\": [], \"last_updated\": null}`\n4. Reset `bot_detection_state.json` to `{\"reviewed_commits\": {}}` — this is the gatekeeper; without clearing it, the bot detector skips already-seen commits\n\n## Project Structure\n\n```\nautonomous-coding/\n├── apps/\n│   └── desktop/                 # Electron desktop application (sole app)\n│       ├── prompts/             # Agent system prompts (.md)\n│       └── src/\n│           ├── main/            # Electron main process\n│           │   ├── ai/          # TypeScript AI agent layer (Vercel AI SDK v6)\n│           │   │   ├── providers/   # Multi-provider registry + factory (9+ providers)\n│           │   │   ├── tools/       # Builtin tools (Read, Write, Edit, Bash, Glob, Grep, etc.)\n│           │   │   ├── security/    # Bash validator, command parser, path containment\n│           │   │   ├── config/      # Agent configs (25+ types), phase config, model resolution\n│           │   │   ├── session/     # streamText() agent loop, error classification, progress\n│           │   │   ├── agent/       # Worker thread executor + bridge\n│           │   │   ├── orchestration/ # Build pipeline (planner → coder → QA)\n│           │   │   ├── runners/     # Utility runners (insights, roadmap, PR review, etc.)\n│           │   │   ├── mcp/         # MCP client integration\n│           │   │   ├── client/      # Client factory convenience constructors\n│           │   │   └── auth/        # Token resolution (reuses claude-profile/)\n│           │   ├── agent/       # Agent queue, process, state, events\n│           │   ├── claude-profile/ # Multi-profile credentials, token refresh, usage\n│           │   ├── terminal/    # PTY daemon, lifecycle, Claude integration\n│           │   ├── platform/    # Cross-platform abstraction\n│           │   ├── ipc-handlers/# 40+ handler modules by domain\n│           │   ├── services/    # Session recovery, profile service\n│           │   └── changelog/   # Changelog generation and formatting\n│           ├── preload/         # Electron preload scripts (electronAPI bridge)\n│           ├── renderer/        # React UI\n│           │   ├── components/  # UI components (onboarding, settings, task, terminal, github, etc.)\n│           │   ├── stores/      # 24+ Zustand state stores\n│           │   ├── contexts/    # React contexts (ViewStateContext)\n│           │   ├── hooks/       # Custom hooks (useIpc, useTerminal, etc.)\n│           │   ├── styles/      # CSS / Tailwind styles\n│           │   └── App.tsx      # Root component\n│           ├── shared/          # Shared types, i18n, constants, utils\n│           │   ├── i18n/locales/# en/*.json, fr/*.json\n│           │   ├── constants/   # themes.ts, etc.\n│           │   ├── types/       # 19+ type definition files\n│           │   └── utils/       # ANSI sanitizer, shell escape, provider detection\n│           └── types/           # TypeScript type definitions\n├── guides/                      # Documentation\n└── scripts/                     # Build and utility scripts\n```\n\n## Commands Quick Reference\n\n### Setup\n```bash\nnpm run install:all              # Install all dependencies from root\n# Or separately:\ncd apps/desktop && npm install\n```\n\n### Testing\n\n| Stack | Command | Tool |\n|-------|---------|------|\n| Frontend unit | `cd apps/desktop && npm test` | Vitest |\n| Frontend E2E | `cd apps/desktop && npm run test:e2e` | Playwright |\n\n### Releases\n```bash\nnode scripts/bump-version.js patch|minor|major  # Bump version\ngit push && gh pr create --base main             # PR to main triggers release\n```\n\nSee [RELEASE.md](RELEASE.md) for full release process.\n\n## AI Agent Layer (`apps/desktop/src/main/ai/`)\n\nAll AI agent logic lives in TypeScript using the Vercel AI SDK v6. This replaces the previous Python `claude-agent-sdk` integration.\n\n### Architecture Overview\n\n- **Provider Layer** (`providers/`) — Multi-provider support via `createProviderRegistry()`. Supports Anthropic, OpenAI, Google, Bedrock, Azure, Mistral, Groq, xAI, and Ollama. Provider-specific transforms handle thinking token normalization and prompt caching.\n- **Session Runtime** (`session/`) — `runAgentSession()` uses `streamText()` with `stopWhen: stepCountIs(N)` for agentic tool-use loops. Includes error classification (429/401/400) and progress tracking.\n- **Worker Threads** (`agent/`) — Agent sessions run in `worker_threads` to avoid blocking the Electron main process. The `WorkerBridge` relays `postMessage()` events to the existing `AgentManagerEvents` interface.\n- **Build Orchestration** (`orchestration/`) — Full planner → coder → QA pipeline. Parallel subagent execution via `Promise.allSettled()`.\n- **Tools** (`tools/`) — 8 builtin tools (Read, Write, Edit, Bash, Glob, Grep, WebFetch, WebSearch) defined with Zod schemas via AI SDK `tool()`.\n- **Security** (`security/`) — Bash validator, command parser, and path containment ported from Python with identical allowlist behavior.\n- **Config** (`config/`) — `AGENT_CONFIGS` registry (25+ agent types), phase-aware model resolution, thinking budgets.\n\n### Key Patterns\n\n```typescript\n// Agent session using streamText()\nimport { streamText, stepCountIs } from 'ai';\n\nconst result = streamText({\n  model: provider,\n  system: systemPrompt,\n  messages: conversationHistory,\n  tools: toolRegistry.getToolsForAgent(agentType),\n  stopWhen: stepCountIs(1000),\n  onStepFinish: ({ toolCalls, text, usage }) => {\n    progressTracker.update(toolCalls, text);\n  },\n});\n\n// Tool definition with Zod schema\nimport { tool } from 'ai';\nimport { z } from 'zod';\n\nconst readTool = tool({\n  description: 'Read a file from the filesystem',\n  inputSchema: z.object({\n    file_path: z.string(),\n    offset: z.number().optional(),\n    limit: z.number().optional(),\n  }),\n  execute: async ({ file_path, offset, limit }) => { /* ... */ },\n});\n```\n\n### Agent Prompts (`apps/desktop/prompts/`)\n\n| Prompt | Purpose |\n|--------|---------|\n| planner.md | Implementation plan with subtasks |\n| coder.md / coder_recovery.md | Subtask implementation / recovery |\n| qa_reviewer.md / qa_fixer.md | Acceptance validation / issue fixes |\n| spec_gatherer/researcher/writer/critic.md | Spec creation pipeline |\n| complexity_assessor.md | AI-based complexity assessment |\n\n### Spec Directory Structure\n\nEach spec in `.auto-claude/specs/XXX-name/` contains: `spec.md`, `requirements.json`, `context.json`, `implementation_plan.json`, `qa_report.md`, `QA_FIX_REQUEST.md`\n\n### Memory System (Graphiti)\n\nGraph-based semantic memory accessed via a Python MCP sidecar (lives outside `apps/desktop/`). The AI layer connects to it via `createMCPClient` from `@ai-sdk/mcp`. Configured through the Electron app's onboarding/settings UI. See [ARCHITECTURE.md](shared_docs/ARCHITECTURE.md#memory-system) for details.\n\n## Frontend Development\n\n### Tech Stack\n\nReact 19, TypeScript (strict), Electron 39, Vercel AI SDK v6, Zustand 5, Tailwind CSS v4, Radix UI, xterm.js 6, Vite 7, Vitest 4, Biome 2, Motion (Framer Motion)\n\n### Path Aliases (tsconfig.json)\n\n| Alias | Maps to |\n|-------|---------|\n| `@/*` | `src/renderer/*` |\n| `@shared/*` | `src/shared/*` |\n| `@preload/*` | `src/preload/*` |\n| `@features/*` | `src/renderer/features/*` |\n| `@components/*` | `src/renderer/shared/components/*` |\n| `@hooks/*` | `src/renderer/shared/hooks/*` |\n| `@lib/*` | `src/renderer/shared/lib/*` |\n\n### State Management (Zustand)\n\nAll state lives in `src/renderer/stores/`. Key stores:\n\n- `project-store.ts` — Active project, project list\n- `task-store.ts` — Tasks/specs management\n- `terminal-store.ts` — Terminal sessions and state\n- `settings-store.ts` — User preferences\n- `github/issues-store.ts`, `github/pr-review-store.ts` — GitHub integration\n- `insights-store.ts`, `roadmap-store.ts`, `kanban-settings-store.ts`\n\nMain process also has stores: `src/main/project-store.ts`, `src/main/terminal-session-store.ts`\n\n### Styling\n\n- **Tailwind CSS v4** with `@tailwindcss/postcss` plugin\n- **7 color themes** (Default, Dusk, Lime, Ocean, Retro, Neo + more) defined in `src/shared/constants/themes.ts`\n- Each theme has light/dark mode variants via CSS custom properties\n- Utility: `clsx` + `tailwind-merge` via `cn()` helper\n- Component variants: `class-variance-authority` (CVA)\n\n### IPC Communication\n\nMain ↔ Renderer communication via Electron IPC:\n- **Handlers:** `src/main/ipc-handlers/` — organized by domain (github, gitlab, ideation, context, etc.)\n- **Preload:** `src/preload/` — exposes safe APIs to renderer\n- Pattern: renderer calls via `window.electronAPI.*`, main handles in IPC handler modules\n\n### Agent Management (`src/main/agent/`)\n\nThe frontend manages agent lifecycle end-to-end:\n- **`agent-queue.ts`** — Queue routing, prioritization, spec number locking\n- **`agent-process.ts`** — Spawns worker threads via `WorkerBridge` for agent execution\n- **`agent-state.ts`** — Tracks running agent state and status\n- **`agent-events.ts`** — Agent lifecycle events and state transitions (structured events from worker threads)\n\n### Claude Profile System (`src/main/claude-profile/`)\n\nMulti-profile credential management for switching between Claude accounts:\n- **`credential-utils.ts`** — OS credential storage (Keychain/Windows Credential Manager)\n- **`token-refresh.ts`** — OAuth token lifecycle and automatic refresh\n- **`usage-monitor.ts`** — API usage tracking and rate limiting per profile\n- **`profile-scorer.ts`** — Scores profiles by usage and availability\n\n### Terminal System (`src/main/terminal/`)\n\nFull PTY-based terminal integration:\n- **`pty-daemon.ts`** / **`pty-manager.ts`** — Background PTY process management\n- **`terminal-lifecycle.ts`** — Session creation, cleanup, event handling\n- **`claude-integration-handler.ts`** — Claude SDK integration within terminals\n- Renderer: xterm.js 6 with WebGL, fit, web-links, serialize addons. Store: `terminal-store.ts`\n\n## Code Quality\n\n### Frontend\n- **Linting:** Biome (`npm run lint` / `npm run lint:fix`)\n- **Type checking:** `npm run typecheck` (strict mode)\n- **Pre-commit:** Husky + lint-staged runs Biome on staged `.ts/.tsx/.js/.jsx/.json`\n- **Testing:** Vitest + React Testing Library + jsdom\n\n\n## i18n Guidelines\n\nAll frontend UI text uses `react-i18next`. Translation files: `apps/desktop/src/shared/i18n/locales/{en,fr}/*.json`\n\n**Namespaces:** `common`, `navigation`, `settings`, `dialogs`, `tasks`, `errors`, `onboarding`, `welcome`\n\n```tsx\nimport { useTranslation } from 'react-i18next';\nconst { t } = useTranslation(['navigation', 'common']);\n\n<span>{t('navigation:items.githubPRs')}</span>     // CORRECT\n<span>GitHub PRs</span>                             // WRONG\n\n// With interpolation:\n<span>{t('errors:task.parseError', { error })}</span>\n```\n\nWhen adding new UI text: add keys to ALL language files, use `namespace:section.key` format.\n\n## Cross-Platform\n\nSupports Windows, macOS, Linux. CI tests all three.\n\n**Platform modules:** `apps/desktop/src/main/platform/`\n\n| Function | Purpose |\n|----------|---------|\n| `isWindows()` / `isMacOS()` / `isLinux()` | OS detection |\n| `getPathDelimiter()` | `;` (Win) or `:` (Unix) |\n| `findExecutable(name)` | Cross-platform executable lookup |\n| `requiresShell(command)` | `.cmd/.bat` shell detection (Win) |\n\nUse `findExecutable()` and `joinPaths()` instead of hardcoded paths. See [ARCHITECTURE.md](shared_docs/ARCHITECTURE.md#cross-platform-development) for extended guide.\n\n## E2E Testing (Electron MCP)\n\nQA agents can interact with the running Electron app via Chrome DevTools Protocol:\n\n1. Start app: `npm run dev:debug` (debug mode for AI self-validation via Electron MCP)\n2. Enable Electron MCP in settings\n3. QA runs automatically through the TypeScript agent pipeline\n\nTools: `take_screenshot`, `click_by_text`, `fill_input`, `get_page_structure`, `send_keyboard_shortcut`, `eval`. See [ARCHITECTURE.md](shared_docs/ARCHITECTURE.md#end-to-end-testing) for full capabilities.\n\n## Running the Application\n\n```bash\n# Desktop app\nnpm start          # Production build + run\nnpm run dev        # Development mode with HMR\nnpm run dev:debug  # Debug mode with verbose output\nnpm run dev:mcp    # Electron MCP server for AI debugging\n\n# Project data: .auto-claude/specs/ (gitignored)\n```\n\n<!-- File: .claude/commands/setup-statusline.md (Tokens: ~852 | Category: command-prompt) -->\n# Setup ccstatusline Integration for Auto-Build\n\nConfigure ccstatusline to display real-time auto-claude progress in your Claude Code status bar.\n\n## Prerequisites\n\n1. **ccstatusline** must be installed and configured\n2. **auto-claude** must be in your project\n\n## Installation\n\n### Step 1: Install ccstatusline (if not already installed)\n\n```bash\n# Using npx\nnpx ccstatusline@latest\n\n# Or using bunx\nbunx ccstatusline@latest\n```\n\nThis launches the interactive TUI to configure your status line.\n\n### Step 2: Add Custom Command Widget\n\nIn the ccstatusline TUI config, add a **Custom Command** widget with:\n\n```\nCommand: python /path/to/your/project/auto-claude/statusline.py --format compact\n```\n\n**Recommended widget settings:**\n- Position: Left or center of status line\n- Update interval: 5 seconds (default)\n- Show only when active: Yes (recommended)\n\n### Step 3: Alternative - JSON Config\n\nEdit `~/.config/ccstatusline/settings.json` and add to your widgets array:\n\n```json\n{\n  \"type\": \"custom\",\n  \"command\": \"python /path/to/your/project/auto-claude/statusline.py --format compact\",\n  \"interval\": 5,\n  \"showWhenEmpty\": false\n}\n```\n\n## Output Formats\n\nThe statusline.py script supports three output formats:\n\n### Compact (recommended for status line)\n```\n--format compact\n```\nOutput: `▣ 3/12 | ◆ Setup → | ⚡2 | 25%`\n\nShows: chunks completed/total | current phase | active workers | progress %\n\n### Full (detailed multi-line)\n```\n--format full\n```\nOutput:\n```\nAUTO-BUILD: my-feature\nState: BUILDING\nChunks: 3/12 (1 in progress)\nPhase: 2/4 - Setup\nWorkers: 2 active\n```\n\n### JSON (for scripting)\n```\n--format json\n```\nOutput: Raw JSON status data\n\n## Status File\n\nAuto-build writes status to `.auto-claude-status` in your project root:\n\n```json\n{\n  \"active\": true,\n  \"spec\": \"001-feature\",\n  \"state\": \"building\",\n  \"chunks\": {\n    \"completed\": 3,\n    \"in_progress\": 1,\n    \"pending\": 8,\n    \"total\": 12\n  },\n  \"phase\": {\n    \"current\": \"Setup\",\n    \"id\": 2,\n    \"total\": 4\n  },\n  \"workers\": {\n    \"active\": 2,\n    \"max\": 3\n  }\n}\n```\n\n## Icons Reference\n\nWhen active, you'll see these indicators:\n\n| Icon | Meaning |\n|------|---------|\n| ▣/▢ | Chunk progress (filled/empty) |\n| ◆ | Current phase |\n| ⚡ | Active workers |\n| → | In progress indicator |\n| ✓ | Completed |\n| ✗ | Error |\n\n## Troubleshooting\n\n### Status not showing?\n1. Check if `.auto-claude-status` exists in your project root\n2. Verify the path to `statusline.py` is correct\n3. Try running the command manually: `python auto-claude/statusline.py --format compact`\n\n### Updates too slow?\n- Decrease the polling interval in ccstatusline config (minimum 1 second)\n\n### Wrong project directory?\n- Use `--project-dir /path/to/project` to specify the project root explicitly\n\n## Example Configurations\n\n### Minimal Status Line\nJust chunks and phase:\n```\npython auto-claude/statusline.py --format compact\n```\n\n### With Specific Spec\nMonitor a specific spec:\n```\npython auto-claude/statusline.py --format compact --spec 001-my-feature\n```\n\n### Full Path for Global Use\n```\npython ~/projects/my-app/auto-claude/statusline.py --format compact --project-dir ~/projects/my-app\n```\n</yakaai_skills>"}