init beads
This commit is contained in:
parent
f75c054e65
commit
a4a5d262ec
0
.beads/beads.base.jsonl
Normal file
0
.beads/beads.base.jsonl
Normal file
1
.beads/beads.base.meta.json
Normal file
1
.beads/beads.base.meta.json
Normal file
|
|
@ -0,0 +1 @@
|
|||
{"version":"0.23.0","timestamp":"2025-11-08T21:59:02.627395674-08:00","commit":"f75c054"}
|
||||
0
.beads/beads.left.jsonl
Normal file
0
.beads/beads.left.jsonl
Normal file
1
.beads/beads.left.meta.json
Normal file
1
.beads/beads.left.meta.json
Normal file
|
|
@ -0,0 +1 @@
|
|||
{"version":"0.23.0","timestamp":"2025-11-08T21:59:00.691604477-08:00","commit":"f75c054"}
|
||||
0
.beads/issues.jsonl
Normal file
0
.beads/issues.jsonl
Normal file
133
AGENTS.md
Normal file
133
AGENTS.md
Normal file
|
|
@ -0,0 +1,133 @@
|
|||
# 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 <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
|
||||
Loading…
Reference in a new issue