Skip to content

AGENTS.md

Latest commit

 

History

History
172 lines (118 loc) · 6.56 KB

AGENTS.md

File metadata and controls

172 lines (118 loc) · 6.56 KB
Raw

Project Instructions for AI Agents

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

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: Dolt-powered version control with native sync
  • 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" --description="Detailed context" -t bug|feature|task -p 0-4 --json
bd create "Issue title" --description="What this issue is about" -p 1 --deps discovered-from:bd-123 --json

Claim and update:

bd update <id> --claim --json
bd update bd-42 --priority 1 --json

Complete work:

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 atomically: bd update <id> --claim
  3. Work on it: Implement, test, document
  4. Discover new work? Create linked issue:
    • bd create "Found bug" --description="Details about what was found" -p 1 --deps discovered-from:<parent-id>
  5. Complete: bd close <id> --reason "Done"

Quality

  • Use --acceptance and --design fields when creating issues
  • Use --validate to check description completeness

Lifecycle

  • bd defer <id> / bd supersede <id> for issue management
  • bd stale / bd orphans / bd lint for hygiene
  • bd human <id> to flag for human decisions
  • bd formula list / bd mol pour <name> for structured workflows

Sync

bd stores issue history in Dolt:

  • Each write auto-commits to Dolt history
  • Use bd dolt push/bd dolt pull for remote sync
  • Do not treat .beads/issues.jsonl as the sync protocol

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/core-concepts/sync-concepts.md for details and anti-patterns.

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?"
  • ❌ Do NOT create markdown TODO lists
  • ❌ Do NOT use external issue trackers
  • ❌ Do NOT duplicate tracking systems

For more details, see README.md and https://github.com/gastownhall/beads/blob/main/docs/getting-started/quickstart.md.

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
bd dolt push
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.

GitHub Issues vs beads

Public product work stays on GitHub Issues. squad-oc watch / triage / loop still use that tracker.

Beads (bd) tracks in-repo agent work: implementation tasks, discovered follow-ups, and session memory. Do not replace the GitHub flow with beads, and do not keep a second markdown TODO list.

Playwright screenshots

Save MCP screenshots and page dumps under .playwright-mcp/ (gitignored). Do not write dummy-*.png or other shots at the repo root.

filename: .playwright-mcp/dummy-mentions-summary.png

A bare dummy-foo.png lands in the workspace root. Unnamed snapshots already go in .playwright-mcp/.

Build & Test

go test ./...
go build -o squad-oc.exe ./cmd/squad-oc

Prefer Task when it is on PATH (task --list): task test, task build, task ci, task release (snapshot only), task bump TAG=vX.Y.Z. Real publish is task release:tag TAG=vX.Y.Z on main then task release:push. Do not edit internal/version/version.go.

Live OpenCode HTTP checks need a running opencode serve and use the live build tag.

Architecture

cmd/squad-oc is a thin main. Command handling lives in internal/cli. Team files and templates are internal/squad. OpenCode HTTP is internal/opencodeclient. GitHub issue triage is internal/watch.

See README.md and docs/get-started.md.

Docs

docs/ is product and domain only (get-started, workshop, use-cases). Agent specs, plans, and SDD scratch stay in gitignored .superpowers/. Do not write brainstorm or design docs under docs/superpowers/.