Skip to content

AGENTS.md

Latest commit

 

History

History
250 lines (180 loc) · 8.08 KB

AGENTS.md

File metadata and controls

250 lines (180 loc) · 8.08 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

PHP CLI tool for Buddy.works CI/CD pipelines, built on buddy-works/buddy-works-php-api and symfony/console. Package name: jtsternberg/buddy-cli.

Special Instructions

  • Use 'bd' for task tracking
  • Test-Driven Development (TDD) — For new behavior and bugfixes, write or update a failing test first, implement the smallest change that makes it pass, then refactor. Do not add production code without a test that defines the expected behavior (unless the user explicitly asks otherwise).

Commands

# Install dependencies
composer install

# Run the CLI
buddy <command>                # Global (after self:install)
./bin/buddy <command>          # Development

# Run tests
./vendor/bin/phpunit

# Run a single test
./vendor/bin/phpunit tests/Path/To/TestFile.php
./vendor/bin/phpunit --filter testMethodName

# Code style (if configured)
./vendor/bin/php-cs-fixer fix
./vendor/bin/phpstan analyse

Architecture

bin/buddy                    # Entry point
src/
├── Application.php          # Symfony Console application bootstrap
├── Commands/                # Command classes organized by resource
│   ├── Pipelines/           # pipelines:list, pipelines:run, pipelines:show, etc.
│   ├── Executions/          # executions:list, executions:show, executions:failed
│   ├── Projects/            # projects:list, projects:show
│   └── Config/              # config:show, config:set, config:clear
├── Services/
│   ├── BuddyService.php     # Wraps buddy-works/buddy-works-php-api SDK
│   └── ConfigService.php    # Manages config from env vars and config files
└── Output/
    ├── JsonFormatter.php    # --json flag output
    └── TableFormatter.php   # Human-readable table output

Key Dependencies

buddy-works/buddy-works-php-api: Handles all Buddy API calls. Throws BuddyResponseException (API errors) and BuddySDKException (SDK errors). Read vendor source for actual method signatures.

symfony/console: Command framework. Commands extend Symfony\Component\Console\Command\Command. Use InputInterface for args/options, OutputInterface for output.

Configuration Precedence

  1. Command-line flags (--workspace, --project)
  2. Environment variables (BUDDY_TOKEN, BUDDY_WORKSPACE, BUDDY_PROJECT)
  3. Project config (.buddy-cli.json)
  4. User config (~/.config/buddy-cli/config.json)

Output Conventions

All commands support --json flag. Default is human-readable tables. JSON output must be valid and parseable for tool integration.

Required API Token Scopes

WORKSPACE, EXECUTION_INFO, EXECUTION_RUN

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

Beads Workflow Integration

This project uses beads_viewer for issue tracking. Issues are stored in .beads/ and tracked in git.

Essential Commands

# View issues (launches TUI - avoid in automated sessions)
bv

# CLI commands for agents (use these instead)
bd ready              # Show issues ready to work (no blockers)
bd list --status=open # All open issues
bd show <id>          # Full issue details with dependencies
bd create --title="..." --type=task --priority=2
bd update <id> --status=in_progress
bd close <id> --reason="Completed"
bd close <id1> <id2>  # Close multiple issues at once
bd sync               # Commit and push changes

Workflow Pattern

  1. Start: Run bd ready to find actionable work
  2. Claim: Use bd update <id> --status=in_progress
  3. Work: Implement the task
  4. Complete: Use bd close <id>
  5. Sync: Always run bd sync at session end

Key Concepts

  • Dependencies: Issues can block other issues. bd ready shows only unblocked work.
  • Priority: P0=critical, P1=high, P2=medium, P3=low, P4=backlog (use numbers, not words)
  • Types: task, bug, feature, epic, question, docs
  • Blocking: bd dep add <issue> <depends-on> to add dependencies

Session Protocol

Before ending any session, run this checklist:

git status              # Check what changed
git add <files>         # Stage code changes
bd sync                 # Commit beads changes
git commit -m "..."     # Commit code
bd sync                 # Commit any new beads changes
git push                # Push to remote

Best Practices

  • Check bd ready at session start to find available work
  • Update status as you work (in_progress → closed)
  • Create new issues with bd create when you discover tasks
  • Use descriptive titles and set appropriate priority/type
  • Always bd sync before ending session

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: Auto-syncs to JSONL for version control
  • 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 bd-42 --status in_progress --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: bd update <id> --status in_progress
  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"

Auto-Sync

bd automatically syncs with git:

  • Exports to .beads/issues.jsonl after changes (5s debounce)
  • Imports from JSONL when newer (e.g., after git pull)
  • No manual export/import needed!

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 docs/QUICKSTART.md.