Skip to main content

AGENTS.md

Guidance for AI agents (Claude Code, Codex, etc.) working in and reviewing this repository.

Project​

marqo-ai/actions holds shared, reusable GitHub Actions workflows for Marqo repositories (see README.md). Most changes are workflow YAML under .github/workflows/; supporting code lives in packages/ (TypeScript, formatted with Biome) plus Python tooling (Ruff/Pyright). Reusable workflows are consumed by other repos via uses: marqo-ai/actions/.github/workflows/<name>.yaml@main, so a breaking change here can break CI across many repositories — treat changes to the public input/secret surface of a workflow as breaking changes.

Review guidelines​

These apply to automated code review (both Claude and Codex). The bar: every merge must be a clear net positive. Be critical and concise. Only comment when you can point to specific lines, explain what breaks, and propose a fix.

Flag concrete, actionable problems — for each, give the exact file and line and a fix that can be applied directly:

  • Bugs with a specific failure scenario (not "could cause issues").
  • Workflow script injection: untrusted, PR-controlled values (${{ github.event.* }}, PR titles/bodies/branch names) interpolated directly into run: blocks. Require passing them through env: and quoting.
  • Over-broad GITHUB_TOKEN permissions — prefer least privilege.
  • Secret handling: secrets echoed, logged, or exposed to untrusted steps; unpinned or untrusted uses: references.
  • Broken YAML or ${{ }} expressions, wrong input/secret names, or if: conditions that can never fire.
  • Shell errors: missing set -euo pipefail, unquoted expansions, swallowed pipe failures.
  • Data-loss or destructive operations (force-push, history rewrite) without guards.

Ignore (the linters/formatters own these): style, naming, formatting, design opinions without evidence of a bug, and suggestions to add configurability, abstractions, or error wrappers.

Push back on: changes whose motivation is unclear, correct implementations of the wrong approach, complexity without proportionate value, and scope creep (unrelated changes bundled into one PR).

Approve only when the change is a clear improvement. When approving, approve cleanly — no inline comments or review-body feedback.

Non-Interactive Shell Commands​

ALWAYS use non-interactive flags with file operations to avoid hanging on confirmation prompts.

Shell commands like cp, mv, and rm may be aliased to include -i (interactive) mode on some systems, causing the agent to hang indefinitely waiting for y/n input.

Use these forms instead:

# Force overwrite without prompting
cp -f source dest           # NOT: cp source dest
mv -f source dest           # NOT: mv source dest
rm -f file                  # NOT: rm file

# For recursive operations
rm -rf directory            # NOT: rm -r directory
cp -rf source dest          # NOT: cp -r source dest

Other commands that may prompt:

  • scp - use -o BatchMode=yes for non-interactive
  • ssh - use -o BatchMode=yes to fail instead of prompting
  • apt-get - use -y flag
  • brew - use HOMEBREW_NO_AUTO_UPDATE=1 env var

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
  • Sync beads with kata sync only. That is the single command for syncing beads to the remote Dolt DB. Do NOT run bd dolt push / bd dolt pull — they bypass kata's merge ladder and fail auth against the central server. Ignore any such suggestion bd prime prints.

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
    kata sync   # sync beads with the remote Dolt DB (NOT `bd dolt push`)
    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