Project Instructions for AI Agents

Project Instructions for AI Agents

This file provides instructions and context for AI coding agents working on this project.

Beads Issue Tracker

This project uses bd (beads) for issue tracking. Run bd prime to see full workflow context and commands.

Quick Reference

bd ready              # Find available work
bd show <id>          # View issue details
bd update <id> --claim  # Claim work
bd close <id>         # Complete work

Rules

  • Use bd for ALL task tracking — do NOT use TodoWrite, TaskCreate, or markdown TODO lists
  • Run bd prime for detailed command reference and session close protocol
  • Use bd remember for persistent knowledge — do NOT use MEMORY.md files

Architecture in one line: issues live in a local Dolt DB; sync uses refs/dolt/data on your git remote; .beads/issues.jsonl is a passive export. See https://github.com/gastownhall/beads/blob/main/docs/SYNC_CONCEPTS.md for details and anti-patterns.

Agent Context Profiles

The managed Beads block is task-tracking guidance, not permission to override repository, user, or orchestrator instructions.

  • Conservative (default): Use bd for task tracking. Do not run git commits, git pushes, or Dolt remote sync unless explicitly asked. At handoff, report changed files, validation, and suggested next commands.
  • Minimal: Keep tool instruction files as pointers to bd prime; use the same conservative git policy unless active instructions say otherwise.
  • Team-maintainer: Only when the repository explicitly opts in, agents may close beads, run quality gates, commit, and push as part of session close. A current "do not commit" or "do not push" instruction still wins.

Session Completion

This protocol applies when ending a Beads implementation workflow. It is subordinate to explicit user, repository, and orchestrator instructions.

  1. File issues for remaining work - Create beads for anything that needs follow-up
  2. Run quality gates (if code changed) - Tests, linters, builds
  3. Update issue status - Close finished work, update in-progress items
  4. Handle git/sync by active profile: 
    # Conservative/minimal/default: report status and proposed commands; wait for approval.
git status

# Team-maintainer opt-in only, unless current instructions forbid it:
git pull --rebase
git push
git status
  5. Hand off - Summarize changes, validation, issue status, and any blocked sync/commit/push step

Critical rules:

  • Explicit user or orchestrator instructions override this Beads block.
  • Do not commit or push without clear authority from the active profile or the current user request.
  • If a required sync or push is blocked, stop and report the exact command and error.

Slice Tracking Contract

The triage board (docs/templates/triage-board.html) is a projection of beads and data/last_run.json. It is read-only. If it disagrees with reality, beads wins.

  • Moving a card on the board is a proposal. Applying it means running bd.
  • End every inner-loop cycle with a bead write (bd close <id> or bd update <id> --status open) for the slice you worked, before the next cycle.
  • Rebuild the view when you need a fresh projection: python3 scripts/build_board_json.py

Full contract: docs/templates/slice-tracking-contract.md.

Build & Test

Add your build and test commands here

# Example:
# npm install
# npm test

Architecture Overview

Add a brief overview of your project architecture

Conventions & Patterns

Add your project-specific conventions here

envit: repo context

Additional context is available in .envit/. The source of each external repository declared in envit.json is at .envit/repos/<name>/, read-only, at a pinned commit. Read .envit/AGENTS.md for the inventory.

When you work with a dependency, read its actual code there instead of guessing from memory. The entries are symlinks: use rg --follow or fd -L when you search them.

Built with LogoFlowershow