Skip to content

AGENTS.md

Latest commit

 

History

History
256 lines (184 loc) · 14.3 KB

AGENTS.md

File metadata and controls

256 lines (184 loc) · 14.3 KB

RULE NUMBER 1 (NEVER EVER EVER FORGET THIS RULE!!!): YOU ARE NEVER ALLOWED TO DELETE A FILE WITHOUT EXPRESS PERMISSION FROM ME OR A DIRECT COMMAND FROM ME. EVEN A NEW FILE THAT YOU YOURSELF CREATED, SUCH AS A TEST CODE FILE. YOU HAVE A HORRIBLE TRACK RECORD OF DELETING CRITICALLY IMPORTANT FILES OR OTHERWISE THROWING AWAY TONS OF EXPENSIVE WORK THAT I THEN NEED TO PAY TO REPRODUCE. AS A RESULT, YOU HAVE PERMANENTLY LOST ANY AND ALL RIGHTS TO DETERMINE THAT A FILE OR FOLDER SHOULD BE DELETED. YOU MUST ALWAYS ASK AND RECEIVE CLEAR, WRITTEN PERMISSION FROM ME BEFORE EVER EVEN THINKING OF DELETING A FILE OR FOLDER OF ANY KIND!!!

IRREVERSIBLE GIT & FILESYSTEM ACTIONS — DO-NOT-EVER BREAK GLASS

  1. Absolutely forbidden commands: git reset --hard, git clean -fd, rm -rf, or any command that can delete or overwrite code/data must never be run unless the user explicitly provides the exact command and states, in the same message, that they understand and want the irreversible consequences.
  2. No guessing: If there is any uncertainty about what a command might delete or overwrite, stop immediately and ask the user for specific approval. “I think it’s safe” is never acceptable.
  3. Safer alternatives first: When cleanup or rollbacks are needed, request permission to use non-destructive options (git status, git diff, git stash, copying to backups) before ever considering a destructive command.
  4. Mandatory explicit plan: Even after explicit user authorization, restate the command verbatim, list exactly what will be affected, and wait for a confirmation that your understanding is correct. Only then may you execute it—if anything remains ambiguous, refuse and escalate.
  5. Document the confirmation: When running any approved destructive command, record (in the session notes / final response) the exact user text that authorized it, the command actually run, and the execution time. If that record is absent, the operation did not happen.

We only use flutter and dart via fvm in this project, NEVER directly. So it's fvm flutter <some_command> instead of flutter <some_command>, and fvm dart <some_command> instead of dart <some_command>.

NEVER run a script that processes/changes code files in this repo, EVER! That sort of brittle, regex based stuff is always a huge disaster and creates far more problems than it ever solves. DO NOT BE LAZY AND ALWAYS MAKE CODE CHANGES MANUALLY, EVEN WHEN THERE ARE MANY INSTANCES TO FIX. IF THE CHANGES ARE MANY BUT SIMPLE, THEN USE SEVERAL SUBAGENTS IN PARALLEL TO MAKE THE CHANGES GO FASTER. But if the changes are subtle/complex, then you must methodically do them all yourself manually!

We do not care at all about backwards compatibility since we are still in early development with no users-- we just want to do things the RIGHT way in a clean, organized manner with NO TECH DEBT. That means, never create "compatibility versions" or any other nonsense like that.

We need to AVOID uncontrolled proliferation of code files. If you want to change something or add a feature, then you MUST revise the existing code file in place. You may NEVER, EVER take an existing code file, say, "document_processor.dart" and then create a new file called "document_processorV2.dart", or "document_processor_improved.dart", or "document_processor_enhanced.dart", or "document_processor_unified.dart", or ANYTHING ELSE REMOTELY LIKE THAT! New code files are reserved for GENUINELY NEW FUNCTIONALITY THAT MAKES ZERO SENSE AT ALL TO INCLUDE IN ANY EXISTING CODE FILE. It should be an INCREDIBLY high bar for you to EVER create a new code file!

We want all console output to be informative, detailed, stylish, colorful, etc.

If you aren't 100% sure about how to use a third party library, then you must SEARCH ONLINE to find the latest documentation website for the library to understand how it is supposed to work and the latest (mid-2025) suggested best practices and usage.

CRITICAL: Whenever you make any substantive changes or additions to the dart code, you MUST check that you didn't introduce any compile errors or lint errors. Check FLUTTER_DART_BEST_PRACTICES.md for commands to do that.

Getting Feedback

ALWAYS make you are on the right track to achieving you goal. You can use whatever is at your disposal to do that.

  • Check FLUTTER_DART_BEST_PRACTICES.md for commands to run tests and format code.
  • Alternatively you can use tools provided by flutter-mcp.
  • Use the maestro tool to start the app and make screenshots of it. Start doing this as soon as you have an (even minimal) app that can actually be started.
  • Use the playwright and playwright-extension tools to inspect the desktop version of the app via screenshots.
  • You can start an emulated android app using ~/Library/Android/sdk/emulator/emulator -avd <avd_name>.
  • Long running and potentially blocking processes like running maestro or the android emulator should ALWAYS be run in a tmux session. Check for tmux sessions named tools or similar. Use send-keys to interact with the sessions.

Integrating with Beads (dependency‑aware task planning)

Beads provides a lightweight, dependency‑aware issue database and a CLI (bd) for selecting “ready work,” setting priorities, and tracking status. It complements MCP Agent Mail’s messaging, audit trail, and file‑reservation signals. Project: steveyegge/beads

Recommended conventions

  • Single source of truth: Use Beads for task status/priority/dependencies; use Agent Mail for conversation, decisions, and attachments (audit).
  • Shared identifiers: Use the Beads issue id (e.g., bd-123) as the Mail thread_id and prefix message subjects with [bd-123].
  • Reservations: When starting a bd-### task, call file_reservation_paths(...) for the affected paths; include the issue id in the reason and release on completion.
  • New Beads: File new issues when you encounter a problem or a TODO that requires a new task.

Beads Viewer (bv) — AI-Friendly Task Analysis

The Beads Viewer (bv) is a fast terminal UI for Beads projects that also provides robot flags designed specifically for AI agent integration. Project: Dicklesworthstone/beads_viewer

Why bv for Agents?

While bd (Beads CLI) handles task CRUD operations, bv provides precomputed graph analytics that help agents make intelligent prioritization decisions:

  • PageRank scores: Identify high-impact tasks that unblock the most downstream work
  • Critical path analysis: Find the longest dependency chain to completion
  • Cycle detection: Spot circular dependencies before they cause deadlocks
  • Parallel track planning: Determine which tasks can run concurrently

Instead of agents parsing .beads/beads.jsonl directly or attempting to compute graph metrics (risking hallucinated results), they can call bv's deterministic robot flags and get JSON output they can trust.

Robot Flags for AI Integration

Flag Output Agent Use Case
bv --robot-help All AI-facing commands Discovery / capability check
bv --robot-insights PageRank, betweenness, HITS, critical path, cycles Quick triage: "What's most impactful?"
bv --robot-plan Parallel tracks, items per track, unblocks lists Execution planning: "What can run in parallel?"
bv --robot-priority Priority recommendations with reasoning + confidence Task selection: "What should I work on next?"
bv --robot-recipes Available filter presets (actionable, blocked, etc.) Workflow setup: "Show me ready work"
bv --robot-diff --diff-since <ref> Changes since commit/date, new/closed items, cycles Progress tracking: "What changed?"

Example: Agent Task Selection Workflow

# 1. Get priority recommendations with reasoning
bv --robot-priority
# Returns JSON with ranked tasks, impact scores, and confidence levels

# 2. Check what completing a task would unblock
bv --robot-plan
# Returns parallel tracks showing dependency chains

# 3. After completing work, check what changed
bv --robot-diff --diff-since "1 hour ago"
# Returns new items, closed items, cycle changes

When to Use bv vs bd

Tool Best For
bd Creating, updating, closing tasks; bd ready for simple "what's next"
bv Graph analysis, impact assessment, parallel planning, change tracking

Rule of thumb: Use bd for task operations, use bv for task intelligence.

Integration with Agent Mail

Combine bv insights with Agent Mail coordination:

  1. Agent A runs bv --robot-priority → identifies bd-42 as highest-impact
  2. Agent A reserves files: file_reservation_paths(..., reason="bd-42")
  3. Agent A announces: send_message(..., thread_id="bd-42", subject="[bd-42] Starting high-impact refactor")
  4. Other agents see the reservation and Mail announcement, pick different tasks
  5. Agent A completes, runs bv --robot-diff to report downstream unblocks

This creates a feedback loop where graph intelligence drives coordination.

Landing the Plane

When the user says "let's land the plane", you MUST complete ALL steps below. The plane is NOT landed until git push succeeds. NEVER stop before pushing. NEVER say "ready to push when you are!" - that is a FAILURE.

MANDATORY WORKFLOW - COMPLETE ALL STEPS:

  1. File beads issues for any remaining work that needs follow-up

  2. Ensure all quality gates pass (only if code changes were made) - run tests, linters, builds (file P0 issues if broken)

  3. Update beads issues - close finished work, update status

  4. PUSH TO REMOTE - NON-NEGOTIABLE - This step is MANDATORY. Execute ALL commands below:

    # Pull first to catch any remote changes
git pull --rebase

# If conflicts in .beads/beads.jsonl, resolve thoughtfully:
#   - git checkout --theirs .beads/beads.jsonl (accept remote)
#   - bd import -i .beads/beads.jsonl (re-import)
#   - Or manual merge, then import

# Sync the database (exports to JSONL, commits)
bd sync

# MANDATORY: Push everything to remote
# DO NOT STOP BEFORE THIS COMMAND COMPLETES
git push

# MANDATORY: Verify push succeeded
git status  # MUST show "up to date with origin/main"

    CRITICAL RULES:

    • The plane has NOT landed until git push completes successfully
    • NEVER stop before git push - that leaves work stranded locally
    • NEVER say "ready to push when you are!" - YOU must push, not the user
    • If git push fails, resolve the issue and retry until it succeeds
    • The user is managing multiple agents - unpushed work breaks their coordination workflow

  5. Clean up git state - Clear old stashes and prune dead remote branches:

    git stash clear                    # Remove old stashes
git remote prune origin            # Clean up deleted remote branches

  6. Verify clean state - Ensure all changes are committed AND PUSHED, no untracked files remain

  7. Choose a follow-up issue for next session

    • Provide a prompt for the user to give to you in the next session
    • Format: "Continue work on bd-X: [issue title]. [Brief context about what's been done and what's next]"

REMEMBER: Landing the plane means EVERYTHING is pushed to remote. No exceptions. No "ready when you are". PUSH IT.

Example "land the plane" session:

# 1. File remaining work
bd create "Add integration tests for sync" -t task -p 2 --json

# 2. Run quality gates (only if code changes were made)
go test -short ./...
golangci-lint run ./...

# 3. Close finished issues
bd close bd-42 bd-43 --reason "Completed" --json

# 4. PUSH TO REMOTE - MANDATORY, NO STOPPING BEFORE THIS IS DONE
git pull --rebase
# If conflicts in .beads/beads.jsonl, resolve thoughtfully:
#   - git checkout --theirs .beads/beads.jsonl (accept remote)
#   - bd import -i .beads/beads.jsonl (re-import)
#   - Or manual merge, then import
bd sync        # Export/import/commit
git push       # MANDATORY - THE PLANE IS STILL IN THE AIR UNTIL THIS SUCCEEDS
git status     # MUST verify "up to date with origin/main"

# 5. Clean up git state
git stash clear
git remote prune origin

# 6. Verify everything is clean and pushed
git status

# 7. Choose next work
bd ready --json
bd show bd-44 --json

Then provide the user with:

  • Summary of what was completed this session
  • What issues were filed for follow-up
  • Status of quality gates (all passing / issues filed)
  • Confirmation that ALL changes have been pushed to remote
  • Recommended prompt for next session

CRITICAL: Never end a "land the plane" session without successfully pushing. The user is coordinating multiple agents and unpushed work causes severe rebase conflicts.

Agent Session Workflow

IMPORTANT for AI agents: When you finish making issue changes, always run:

bd sync

This immediately:

  1. Exports pending changes to JSONL (no 30s wait)
  2. Commits to git
  3. Pulls from remote
  4. Imports any updates
  5. Pushes to remote

Example agent session:

# Make multiple changes (batched in 30-second window)
bd create "Fix bug" -p 1
bd create "Add tests" -p 1
bd update bd-42 --status in_progress
bd close bd-40 --reason "Completed"

# Force immediate sync at end of session
bd sync

# Now safe to end session - everything is committed and pushed

Why this matters:

  • Without bd sync, changes sit in 30-second debounce window
  • User might think you pushed but JSONL is still dirty
  • bd sync forces immediate flush/commit/push

STRONGLY RECOMMENDED: Install git hooks for automatic sync (prevents stale JSONL problems):

# One-time setup - run this in each beads workspace
bd hooks install

This installs:

  • pre-commit - Flushes pending changes immediately before commit (bypasses 30s debounce)
  • post-merge - Imports updated JSONL after pull/merge (guaranteed sync)
  • pre-push - Exports database to JSONL before push (prevents stale JSONL from reaching remote)
  • post-checkout - Imports JSONL after branch checkout (ensures consistency)

Why git hooks matter: Without the pre-push hook, you can have database changes committed locally but stale JSONL pushed to remote, causing multi-workspace divergence. The hooks guarantee DB ↔ JSONL consistency.

Note: Hooks are embedded in the bd binary and work for all bd users (not just source repo users).