# FleetCode - Agent Development Guide ## Build & Run Commands - `npm run build:all` - Build everything (CSS, TypeScript, web bundle) - `npm run server` - Start web server on port 3000 (recommended) - `npm run dev:server` - Development mode with hot reload - `npm run dev` - Run Electron desktop app - No tests defined yet ## Architecture - **Dual mode**: Electron desktop app (`main.ts`) OR web server (`server.ts`) with Socket.IO - **Frontend**: `renderer.ts` (web + Electron), `index.html`, `styles.css` (Tailwind) - **Backend**: `server.ts` - manages PTY sessions, git worktrees, Socket.IO events - **Git worktrees**: Each session runs in isolated worktree (created in `~/worktrees/` by default) - **Key files**: `types.ts` (shared interfaces), `ipc-adapter.ts` (Electron/Socket.IO abstraction), `terminal-utils.ts` - **Storage**: JSON file at `~/.fleetcode-store.json` for persisted sessions ## Code Style - **TypeScript**: Strict mode, ES2020, CommonJS modules - **Imports**: Use relative paths for local files, type imports from `./types` - **Formatting**: No semicolons optional, use template literals, prefer `const`/`let` over `var` - **Naming**: camelCase for variables/functions, PascalCase for types/interfaces - **DOM**: Use `getElementById` with null checks, sanitize user input with `textContent` - **Error handling**: Try/catch for async operations, emit Socket.IO error events - **Comments**: Avoid unless code is complex; explanation belongs in responses, not code ## Issue Tracking with bd (beads) **IMPORTANT**: This project uses **bd (beads)** for ALL issue tracking. Do NOT use markdown TODOs, task lists, or other tracking methods. ### Why bd? - Dependency-aware: Track blockers and relationships between issues - Git-friendly: Auto-syncs to JSONL for version control - Agent-optimized: JSON output, ready work detection, discovered-from links - Prevents duplicate tracking systems and confusion ### Quick Start **Check for ready work:** ```bash bd ready --json ``` **Create new issues:** ```bash bd create "Issue title" -t bug|feature|task -p 0-4 --json bd create "Issue title" -p 1 --deps discovered-from:bd-123 --json ``` **Claim and update:** ```bash bd update bd-42 --status in_progress --json bd update bd-42 --priority 1 --json ``` **Complete work:** ```bash bd close bd-42 --reason "Completed" --json ``` ### Issue Types - `bug` - Something broken - `feature` - New functionality - `task` - Work item (tests, docs, refactoring) - `epic` - Large feature with subtasks - `chore` - Maintenance (dependencies, tooling) ### Priorities - `0` - Critical (security, data loss, broken builds) - `1` - High (major features, important bugs) - `2` - Medium (default, nice-to-have) - `3` - Low (polish, optimization) - `4` - Backlog (future ideas) ### Workflow for AI Agents 1. **Check ready work**: `bd ready` shows unblocked issues 2. **Claim your task**: `bd update --status in_progress` 3. **Work on it**: Implement, test, document 4. **Discover new work?** Create linked issue: - `bd create "Found bug" -p 1 --deps discovered-from:` 5. **Complete**: `bd close --reason "Done"` 6. **Commit together**: Always commit the `.beads/issues.jsonl` file together with the code changes so issue state stays in sync with code state ### Auto-Sync bd automatically syncs with git: - Exports to `.beads/issues.jsonl` after changes (5s debounce) - Imports from JSONL when newer (e.g., after `git pull`) - No manual export/import needed! ### Managing AI-Generated Planning Documents AI assistants often create planning and design documents during development: - PLAN.md, IMPLEMENTATION.md, ARCHITECTURE.md - DESIGN.md, CODEBASE_SUMMARY.md, INTEGRATION_PLAN.md - TESTING_GUIDE.md, TECHNICAL_DESIGN.md, and similar files **Best Practice: Use a dedicated directory for these ephemeral files** **Recommended approach:** - Create a `history/` directory in the project root - Store ALL AI-generated planning/design docs in `history/` - Keep the repository root clean and focused on permanent project files - Only access `history/` when explicitly asked to review past planning **Example .gitignore entry (optional):** ``` # AI planning documents (ephemeral) history/ ``` **Benefits:** - ✅ Clean repository root - ✅ Clear separation between ephemeral and permanent documentation - ✅ Easy to exclude from version control if desired - ✅ Preserves planning history for archeological research - ✅ Reduces noise when browsing the project ### Important Rules - ✅ Use bd for ALL task tracking - ✅ Always use `--json` flag for programmatic use - ✅ Link discovered work with `discovered-from` dependencies - ✅ Check `bd ready` before asking "what should I work on?" - ✅ Store AI planning docs in `history/` directory - ❌ Do NOT create markdown TODO lists - ❌ Do NOT use external issue trackers - ❌ Do NOT duplicate tracking systems - ❌ Do NOT clutter repo root with planning documents