boshu2__agentops/AGENTS.md

Agent Instructions

This project uses bd (beads) for issue tracking. Run bd onboard to get started.

Session Start (Zero-Context Agent)

If you spawn into this repo without context, do this first:

1. Open docs/README.md then docs/INDEX.md to get the current doc map.
2. Identify your task domain:
   • CLI behavior: cli/cmd/ao/, cli/internal/, cli/docs/COMMANDS.md
   • Skill behavior: skills/<name>/SKILL.md
   • Hook/gate behavior: hooks/hooks.json + hooks/*.sh
   • Validation/release/security flows: scripts/*.sh + tests/
3. Use source-of-truth precedence when docs disagree:
   1. Executable code and generated artifacts (cli/**, hooks/**, scripts/**, cli/docs/COMMANDS.md)
   2. Skill contracts and manifests (skills/**/SKILL.md, hooks/hooks.json, schemas/**)
   3. Explanatory docs (docs/**, README.md)
4. If you find conflicts, follow the higher-precedence source and call out the mismatch explicitly in your report/PR.

Installing/Updating Skills

Use the skills.sh npm package to install AgentOps skills for any agent:

# Install for all supported agents
npx skills@latest add boshu2/agentops --all -g

# Install for specific agents
npx skills@latest add boshu2/agentops -g -a codex -s '*' -y
npx skills@latest add boshu2/agentops -g -a opencode -s '*' -y
npx skills@latest add boshu2/agentops -g -a cursor -s '*' -y

# Update all installed skills
npx skills@latest update

Quick Reference

# Issue tracking
bd ready              # Find available work
bd show <id>          # View issue details
bd update <id> --status in_progress  # Claim work
bd close <id>         # Complete work
bd sync               # Sync with git

# CLI development
cd cli && make build  # Build ao binary
cd cli && make test   # Run tests
cd cli && make lint   # Run linter

# Validation
scripts/ci-local-release.sh     # Full local release gate
scripts/validate-go-fast.sh     # Quick Go validation
scripts/security-gate.sh        # Security scanning

Releasing

Standard release flow:

1. Run scripts/ci-local-release.sh to validate
2. Tag and push: git tag v2.X.0 && git push origin v2.X.0
3. GitHub Actions runs GoReleaser — builds binaries, creates release, updates Homebrew tap
4. Upgrade locally: brew update && brew upgrade agentops

For retagging (rolling post-tag commits into an existing release):

scripts/retag-release.sh v2.13.0

This moves the tag to HEAD, pushes, rebuilds the GitHub release, updates the Homebrew tap, and upgrades locally. One command, no manual steps.

Landing the Plane (Session Completion)

When ending a work session, you MUST complete ALL steps below. Work is NOT complete until git push succeeds.

MANDATORY WORKFLOW:

1. File issues for remaining work - Create issues 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. PUSH TO REMOTE - This is MANDATORY:

   git pull --rebase
   bd sync
   git push
   git status  # MUST show "up to date with origin"
   

5. Clean up - Clear stashes, prune remote branches
6. Verify - All changes committed AND pushed
7. Hand off - Provide context for next session

CRITICAL RULES:

• Work is NOT complete until git push succeeds
• NEVER stop before pushing - that leaves work stranded locally
• NEVER say "ready to push when you are" - YOU must push
• If push fails, resolve and retry until it succeeds