Skip to content

AGENTS.md

Latest commit

 

History

History
81 lines (59 loc) · 3.53 KB

AGENTS.md

File metadata and controls

81 lines (59 loc) · 3.53 KB
Raw

Agent Instructions

This repository uses Beads (bd) for durable issue tracking. Run bd prime for the current workflow, commands, and session-close protocol.

Beads Architecture

Issues live in the local Dolt database under .beads/. Cross-machine issue sync uses bd dolt push/pull and the remote refs/dolt/data ref, independently of Git branches under refs/heads/*.

.beads/issues.jsonl is a passive export, not a source of truth or the normal sync mechanism; do not import it during routine sync. Changes to the generated .beads/interactions.jsonl must be left dirty and must not be staged, committed, or pushed. See SYNC_CONCEPTS.md for the sync model and anti-patterns.

Collaboration and Worktrees

Assume other people and agents may be working concurrently.

  • Use a dedicated Git worktree for implementation work by default.
  • Base new worktrees on main unless the task targets another branch.
  • Inspect git status before editing and before committing.
  • Preserve unrelated changes and never include them in an agent commit.

Active Profile and Authority

This repository uses the team-maintainer profile. Unless the user or a higher-priority instruction says otherwise, agents completing implementation work are authorized to:

  • run relevant quality gates;
  • close completed Beads issues;
  • commit only their own completed changes;
  • push their working branch and open a pull request;
  • run bd dolt push after updating Beads state.

Explicit instructions such as "do not commit" or "do not push" always win. If a required commit or sync fails, report the exact command and error.

Signing

  • Sign GitHub comments with: _{agent_runtime}-{model}-{reasoning} on behalf of {user}_
  • Add this trailer to agent commits: Agent-Signature: {agent_runtime}-{model}-{reasoning} on behalf of {user}

Non-Interactive and Destructive Commands

  • Use non-interactive flags appropriate to the active shell; do not assume Unix flag syntax works in PowerShell.
  • Use batch mode for ssh and scp, and non-interactive options for package managers or other commands that may prompt.
  • Before recursive delete or move operations, resolve and verify the exact target path. Never target a workspace root, home directory, or unresolved variable.

Beads Issue Tracker

Use Beads (bd) for durable task tracking in repositories that include it. Use the beads skill at .agents/skills/beads/SKILL.md (project install) or ~/.agents/skills/beads/SKILL.md (global install) for Beads workflow guidance, then use the bd CLI for issue operations.

Quick Reference

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

Rules

  • Use bd for all task tracking; do not create markdown TODO lists.
  • Run bd prime when Beads context is missing or stale. Codex 0.129.0+ can load Beads context automatically through native hooks; use /hooks to inspect or toggle them.
  • Keep persistent project memory in Beads via bd remember; do not create ad hoc memory 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.