fleetcode/AGENTS.md
Anish Lakhwara a4a5d262ec init beads
2025-11-08 22:01:39 -08:00

4.8 KiB

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:

bd ready --json

Create new issues:

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:

bd update bd-42 --status in_progress --json
bd update bd-42 --priority 1 --json

Complete work:

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 <id> --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:<parent-id>
  5. Complete: bd close <id> --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