4.8 KiB
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 reloadnpm 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.jsonfor 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/letovervar - Naming: camelCase for variables/functions, PascalCase for types/interfaces
- DOM: Use
getElementByIdwith null checks, sanitize user input withtextContent - 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 brokenfeature- New functionalitytask- Work item (tests, docs, refactoring)epic- Large feature with subtaskschore- 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
- Check ready work:
bd readyshows unblocked issues - Claim your task:
bd update <id> --status in_progress - Work on it: Implement, test, document
- Discover new work? Create linked issue:
bd create "Found bug" -p 1 --deps discovered-from:<parent-id>
- Complete:
bd close <id> --reason "Done" - Commit together: Always commit the
.beads/issues.jsonlfile 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.jsonlafter 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
--jsonflag for programmatic use - ✅ Link discovered work with
discovered-fromdependencies - ✅ Check
bd readybefore 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