Agent Workflow Guide

This guide provides step-by-step instructions for AI agents working on the katana-openapi-client project. Follow these guidelines to work efficiently and safely in parallel with other agents.

Quick Reference

See CLAUDE.md "Essential Commands" for the full command table with timings.

Pre-commit Hooks:

.pre-commit-config-lite.yaml - Fast iteration
.pre-commit-config.yaml - Full validation

Using Custom GitHub Copilot Agents

This project defines specialized GitHub Copilot agents for different development tasks. Each agent has domain-specific knowledge and follows project patterns.

Available Agents

Specialist Agents

@agent-dev - Development agent for feature implementation and bug fixes
- Implements new features following established patterns
- Fixes bugs with proper error handling and logging
- Refactors code for consistency
- References ADRs for architectural decisions
@agent-plan - Planning agent for breaking down complex tasks
- Creates detailed implementation plans with phases
- Identifies dependencies and blockers
- Estimates effort (p1-high, p2-medium, p3-low)
- Writes comprehensive issues following templates
@agent-docs - Documentation agent for maintaining docs
- Creates and updates documentation
- Writes Architecture Decision Records (ADRs)
- Keeps guides current with code changes
- Ensures consistent markdown formatting
@agent-test - Testing agent for comprehensive test coverage
- Writes unit and integration tests
- Debugs test failures
- Maintains 87%+ coverage on core logic
- Implements reusable test fixtures
@agent-review - Review agent for thorough code reviews
- Checks adherence to project patterns
- Verifies type safety and error handling
- Identifies potential bugs and edge cases
- Suggests improvements with rationale

Coordinator Agent

@agent-coordinator - Orchestrates multi-agent work and project management
- Monitors all open PRs and their status
- Routes tasks to appropriate specialist agents
- Ensures PRs meet merge criteria
- Tracks dependencies and blockers
- Maintains project velocity

Agent Workflow Patterns

Single Agent (Direct Task)

For straightforward tasks, use a specialist agent directly:

@agent-dev implement the create_sales_order tool following the purchase order pattern

@agent-test write comprehensive tests for the inventory helper functions

@agent-docs create an ADR for the new Pydantic domain model architecture

Multi-Agent Coordination

For complex tasks requiring multiple agents, use the coordinator:

@agent-coordinator get PR #125 ready to merge
→ Analyzes PR status (review comments, CI failures, etc.)
→ Delegates to @agent-dev for code fixes
→ Delegates to @agent-test for test coverage
→ Delegates to @agent-docs for documentation
→ Verifies all criteria met
→ Merges when ready

@agent-coordinator complete the MCP v0.1.0 milestone
→ Identifies all open issues and PRs
→ Routes work to specialist agents
→ Tracks progress across parallel workstreams
→ Reports blockers and status
→ Coordinates release when all work complete

Project-Level Coordination

For ongoing project management:

@agent-coordinator check in on all open PRs
→ Scans all PRs for status
→ Identifies ready-to-merge PRs
→ Assigns specialists to PRs needing work
→ Reports blockers and stale PRs
→ Provides project health summary

Agent Definition Files

All custom agents are defined in .github/copilot/agents/:

agent-dev.yml - Development agent configuration
agent-plan.yml - Planning agent configuration
agent-docs.yml - Documentation agent configuration
agent-test.yml - Testing agent configuration
agent-review.yml - Review agent configuration
agent-coordinator.yml - Coordinator agent configuration

Each agent has:

Specialized instructions based on project patterns
References to key documentation (CLAUDE.md, ADRs)
Context about which files they work with
Examples of typical tasks and approaches

When to Use Which Agent

Use @agent-dev when:

Implementing new features
Fixing bugs
Addressing review comments
Resolving merge conflicts
Refactoring code

Use @agent-plan when:

Breaking down epic-level work
Creating implementation plans
Identifying dependencies
Estimating effort
Designing architecture

Use @agent-docs when:

Writing new documentation
Updating existing docs
Creating ADRs
Adding examples to cookbook
Documenting APIs

Use @agent-test when:

Writing new tests
Fixing test failures
Improving coverage
Debugging test issues
Creating test fixtures

Use @agent-review when:

Reviewing pull requests
Checking code quality
Verifying patterns
Identifying bugs
Suggesting improvements

Use @agent-coordinator when:

Managing multiple PRs
Coordinating agent work
Tracking project progress
Unblocking stalled work
Preparing releases

Example: Complete Feature Workflow

Here's how multiple agents work together on a feature:

Planning Phase

@agent-plan break down "Add sales order support" into implementation tasks
→ Creates detailed plan with phases
→ Identifies dependencies
→ Creates individual issues

Implementation Phase

@agent-dev implement sales_orders.py following purchase order pattern
→ Implements tool with proper patterns
→ Adds error handling and logging
→ Creates PR with changes

Testing Phase

@agent-test write comprehensive tests for sales_orders tool
→ Writes unit tests for all functions
→ Tests success and error paths
→ Verifies 90%+ coverage

Documentation Phase

@agent-docs document the sales_orders tool
→ Adds docstrings
→ Updates README
→ Adds cookbook example

Review Phase

@agent-review review PR #123 for sales orders
→ Checks pattern adherence
→ Verifies test coverage
→ Validates documentation
→ Suggests improvements

Coordination Phase

@agent-coordinator get PR #123 merged
→ Ensures all feedback addressed
→ Verifies CI passing
→ Confirms merge criteria met
→ Merges PR
→ Updates milestone

This coordinated workflow ensures high-quality, well-tested, documented features.

Step-by-Step Workflow

1. Starting Work on an Issue

Check for Conflicts

Before starting, ensure no other agent is working on the same code:

# Check if issue is already assigned
gh issue view <issue-number>

# Check recent PRs touching same files
gh pr list --search "is:open <keyword>"

# Look at current branch activity
git branch -r | grep feature

Create Your Branch

Use consistent naming conventions:

# Pattern: feature/{issue-number}-{short-description}
git checkout -b feature/88-agent-workflow-doc

# Alternative: agent/{agent-id}/{issue-number}-{description}
git checkout -b agent/claude-1/88-agent-workflow-doc

Branch Naming Rules:

Use feature/ for general work
Use agent/ prefix if coordinating multiple agents
Always include issue number
Keep description short and kebab-case
Examples:
- feature/92-release-concurrency
- feature/94-pytest-xdist
- agent/copilot-1/95-coverage-ratchet

Update Issue Status

Comment on the issue to claim it:

gh issue comment <issue-number> --body "🤖 Starting work on this issue"

2. Development Workflow

Fast Iteration Loop

During active development, use quick validation for fast feedback:

# Make changes to code
vim src/file.py

# Quick validation (5-10 seconds)
uv run poe quick-check

# If using pre-commit lite
pre-commit run --config .pre-commit-config-lite.yaml --all-files

# Continue iterating

When to Use Quick Check:

✅ During active coding
✅ Testing different approaches
✅ Experimenting with solutions
✅ Multiple iterations needed

When NOT to Use:

❌ Before committing (use agent-check)
❌ Before opening PR (use check)
❌ Before requesting review (use full-check)

Before Committing

Run more thorough validation:

# Agent-level validation (10-15 seconds)
uv run poe agent-check

# Or use pre-commit lite
pre-commit run --config .pre-commit-config-lite.yaml --all-files

# If all passes, commit
git add <files>
git commit -m "feat: your commit message"

Commit Message Format: Follow conventional commits:

<type>(<scope>): <description>

[optional body]

[optional footer]

Types:

feat - New feature (triggers release)
fix - Bug fix (triggers release)
docs - Documentation only
test - Test changes
refactor - Code refactoring
chore - Maintenance tasks
ci - CI/CD changes

Scopes (for monorepo):

client - Releases katana-openapi-client
mcp - Releases katana-mcp-server
(no scope) - Releases katana-openapi-client (default)

Examples:

git commit -m "feat(mcp): add inventory resources"
git commit -m "fix(client): handle null values in variants"
git commit -m "docs: update AGENT_WORKFLOW.md"
git commit -m "test: add coverage for edge cases"

3. Before Opening a Pull Request

Run Full Validation

CRITICAL: PRs must be green with full validation. No skips, no excludes.

# Full validation (required before PR)
uv run poe check

# Or use full pre-commit
pre-commit run --all-files

# Expected time: ~40 seconds (or ~12-15s with parallel tests)

What check does:

Format check (ruff, markdown)
Linting (ruff, ty, yamllint)
Tests (pytest with coverage, excluding slow docs tests)

If any checks fail:

❌ DO NOT add skips or excludes
❌ DO NOT use --no-verify without justification
✅ FIX the actual issue
✅ ASK for help if blocked

Exception: Only skip checks if:

You document WHY in PR description
You create a follow-up issue to fix properly
The skip is temporary and necessary

Push Your Branch

# Push to remote
git push -u origin feature/88-agent-workflow-doc

# If you need to force push (be careful!)
git push --force-with-lease

4. Opening the Pull Request

Use GitHub CLI

# Create PR with template
gh pr create --fill

# Or specify details
gh pr create \
  --title "feat: add agent workflow documentation" \
  --body "Closes #88

## Description
Adds comprehensive AGENT_WORKFLOW.md guide for AI agents.

## Changes
- Created AGENT_WORKFLOW.md with step-by-step workflow
- Updated CLAUDE.md to link to new guide

## Testing
- Validated all commands work
- Reviewed formatting and links"

PR Checklist

Before requesting review, ensure:

All CI checks passing (green)
Full validation run locally (uv run poe check)
Tests added/updated for changes
Documentation updated if needed
Commit messages follow conventional commits
No test/lint skips or excludes (unless justified)
Issue number referenced in PR (e.g., "Closes #88")

Request Review

# Self-assign
gh pr edit --add-assignee @me

# Add labels
gh pr edit --add-label "documentation"

# Mark ready for review (if draft)
gh pr ready

5. Handling Review Feedback

Make Changes

# Make requested changes
vim files.py

# Validate
uv run poe check

# Commit
git add .
git commit -m "fix: address review feedback"

# Push
git push

Respond to Comments

# Comment on PR
gh pr comment <pr-number> --body "✅ Updated per your feedback"

# Resolve conversations (on GitHub web UI)

6. Before Merge

Final Validation

CRITICAL: Before merging, run complete validation:

# Full check including docs
uv run poe full-check

# This includes:
# - Format check
# - Linting (ruff, ty, yamllint)
# - All tests (including docs tests)
# - Coverage check

# Expected time: ~50 seconds

Ensure CI is Green

Check GitHub UI or:

gh pr checks

# Should show all checks passing

Merge

# Squash and merge (recommended)
gh pr merge --squash

# Or merge commit
gh pr merge --merge

# Or rebase (be careful!)
gh pr merge --rebase

Validation Tiers Reference

See CLAUDE.md "Essential Commands" for the authoritative command table with timings.

Quick Check

Command: uv run poe quick-check | Use during development

Runs ruff format check and linting. Skips type checking and tests.

Agent Check

Command: uv run poe agent-check | Use before committing

Runs format check, linting, and ty type checking. Skips tests.

Check

Command: uv run poe check | Required before opening PR

Runs format check (ruff, markdown), linting (ruff, ty, yamllint), and tests (pytest, excluding docs). This is the standard for "PR ready."

Full Check

Command: uv run poe full-check | Use before requesting review

Runs everything in check plus documentation build. This is the gold standard.

Conflict Resolution

Detecting Conflicts

Before Starting Work

# Check who's working on what
gh issue list --assignee @me
gh pr list --author @me

# Check file history
git log --oneline --follow <file>

# Check open PRs touching same files
gh pr list --search "is:open"

During Work

# Keep your branch updated
git fetch origin
git rebase origin/main

# Check for conflicts
git status

Resolving Conflicts

Simple Rebase

# Update main
git checkout main
git pull

# Rebase your branch
git checkout feature/your-branch
git rebase main

# If conflicts, resolve them
# Edit conflicting files
git add <resolved-files>
git rebase --continue

# Force push (safe with --force-with-lease)
git push --force-with-lease

Complex Conflicts

If you encounter complex conflicts:

Communicate in the issue:

gh issue comment <issue-number> --body "Encountered conflicts with #<other-issue>. Coordinating resolution."

Check with other agent (if parallel work):
- Review the other PR
- Determine which changes take precedence
- Coordinate in issue comments
If blocked:
- Comment on issue explaining blockage
- Provide details on conflict
- Wait for guidance or coordinate with other agent

Common Pitfalls & Solutions

❌ Pitfall: Skipping Validation

Problem: Using --no-verify or skipping checks to speed up workflow

Solution:

Use tiered validation (quick-check, agent-check, check)
Only full validation required before PR
Fast iteration OK during development

❌ Pitfall: Committing with Failures

Problem: Committing when tests or linting fail

Solution:

Always run uv run poe agent-check before committing
Fix issues, don't skip them
If blocked, ask for help in issue comments

❌ Pitfall: Adding Test/Lint Skips

Problem: Adding # type: ignore, # noqa, or pytest skips to pass CI

Solution:

Fix the actual issue
Only skip if absolutely necessary AND document why in PR
Create follow-up issue to remove skip

❌ Pitfall: Force Pushing Without Care

Problem: Using git push --force and overwriting others' work

Solution:

Use git push --force-with-lease (safer)
Check if anyone else is on your branch
Communicate before force pushing shared branches

❌ Pitfall: Not Updating Branch

Problem: Working on stale branch, causing conflicts

Solution:

# Update regularly
git fetch origin
git rebase origin/main

# Or merge if preferred
git merge origin/main

❌ Pitfall: Unclear Commit Messages

Problem: Vague commits like "fix stuff" or "update code"

Solution:

Follow conventional commits format
Be specific: "fix(client): handle null variant names"
Include context: "refactor: extract helper for variant display names"

Pre-commit Hook Usage

Lite Config (Fast Iteration)

File: .pre-commit-config-lite.yaml

Usage:

# Run lite hooks
pre-commit run --config .pre-commit-config-lite.yaml --all-files

# Install as default
pre-commit install --config .pre-commit-config-lite.yaml

When to Use:

During development
Fast feedback loop
Experimenting

Full Config (Complete Validation)

File: .pre-commit-config.yaml

Usage:

# Run full hooks (includes tests)
pre-commit run --all-files

# Install as default
pre-commit install

When to Use:

Before opening PR
Before requesting review
Final validation

Note: With pytest-xdist (parallel tests), this is now ~12-15 seconds instead of ~27 seconds.

Working with Multiple Agents

When multiple AI agents work on the same codebase in parallel, coordination is essential to avoid conflicts and wasted effort. Follow these patterns for smooth parallel development.

Coordination Strategies

1. Claim Issues Early

Always comment on an issue as soon as you start working on it:

# As soon as you start
gh issue comment <issue-number> --body "🤖 Starting work on this issue"

# Self-assign if possible
gh issue edit <issue-number> --add-assignee "@me"

Why: Other agents can see someone is already working on it.

2. Check for Conflicts BEFORE Starting

Critical: Before starting work, check if anyone else is already working on similar changes:

# 1. Check open PRs that might overlap
gh pr list --state open

# 2. Check issues assigned to others
gh issue list --state open --assignee "@others"

# 3. Check recent activity on files you'll touch
git log --oneline -10 --follow <file-path>

# 4. Check open branches
git branch -r | grep feature

Decision tree:

No conflicts? → Start work, claim issue
Similar work in progress? → Comment on issue, coordinate with other agent
Depends on other PR? → Wait for that PR to merge, or coordinate merge order

3. Communicate Progress in Issue Comments

Keep issue comments updated so other agents know your status:

# Update progress
gh issue comment <issue-number> --body "✅ Completed X, working on Y"

# Signal blocks
gh issue comment <issue-number> --body "⚠️ Blocked by #<other-issue>, waiting for resolution"

# Ask for coordination
gh issue comment <issue-number> --body "📋 This may conflict with #<other-issue>. Coordinating..."

# Signal completion
gh issue comment <issue-number> --body "✅ PR #<pr-number> ready for review"

4. Branch Naming for Clarity

Standard pattern: feature/<issue-number>-<description>

git checkout -b feature/88-agent-workflow

Agent-specific pattern (if coordinating multiple agents on same project):

# Agent 1
git checkout -b agent/claude-1/88-agent-workflow

# Agent 2
git checkout -b agent/copilot-1/89-update-instructions

Why agent-specific branches help:

Clearly shows which agent owns which work
Prevents accidental branch name collisions
Makes it easy to see parallel work in git branch -r

5. File-Level Conflict Detection

Before starting, identify which files you'll modify and check for conflicts:

# Check who else recently touched these files
git log --oneline -10 -- path/to/file.py

# Check open PRs touching same files
gh pr list --json number,title,files --jq '.[] | select(.files[].path == "path/to/file.py") | {number, title}'

# Check for unmerged branches touching same files
git branch -r --contains <commit> | grep -v "$(git rev-parse --abbrev-ref HEAD)"

If conflicts detected:

Same file, different sections → Can work in parallel, coordinate merge order
Same file, same sections → One agent should wait or pick different issue
Dependencies → Work sequentially, file issue dependencies

6. Merge Order Coordination

When multiple PRs will conflict, coordinate merge order:

# Option A: Sequential (safest)
# Agent 1: Open PR #100, merge
# Agent 2: Wait for #100 to merge, rebase, then open PR #101

# Option B: Parallel with coordination (faster)
# Agent 1: Open PR #100 (touches file A)
# Agent 2: Open PR #101 (touches file B, no conflicts)
# Both can merge independently

# Option C: Stacked PRs (for dependencies)
# Agent 1: Open PR #100 (foundation)
# Agent 2: Branch from PR #100, open PR #101 (depends on #100)
# Merge #100 first, then #101 rebases and merges

7. Self-Coordination Strategies

Pattern 1: Claim and Complete

# 1. Check issue list, pick unclaimed issue
gh issue list --no-assignee

# 2. Claim it
gh issue edit <issue-number> --add-assignee "@me"
gh issue comment <issue-number> --body "🤖 Starting work"

# 3. Complete end-to-end (no partial work)
# 4. Open PR, get it merged
# 5. Move to next issue

Pattern 2: Avoid Overlap

# Before starting, check if files overlap with open PRs
ISSUE=92
FILES="path/to/file.py path/to/other.py"

for FILE in $FILES; do
  echo "Checking $FILE..."
  gh pr list --json number,files --jq ".[] | select(.files[].path == \"$FILE\") | .number"
done

# If overlap found, choose different issue or coordinate

Pattern 3: Phase-Based Work

Work on issues grouped by phase to minimize conflicts:

# Agent 1: Works on Phase 1 issues (#88, #89, #90)
# Agent 2: Works on Phase 2 issues (#92, #93)
# Agent 3: Works on Phase 3 issues (#94, #95)

# Check your assigned phase
gh issue list --label "phase-1"

8. Rebase Frequently

If working on a long-running branch, rebase frequently to stay current:

# Every few hours or before opening PR
git fetch origin
git rebase origin/main

# If conflicts, resolve them immediately
git status
# Fix conflicts, then:
git add .
git rebase --continue

9. Use GitHub Projects for Visibility

If available, use GitHub Projects to show what each agent is working on:

# View project status
gh project list

# See what's in progress
gh project item-list <project-number> --format json | jq '.[] | select(.status == "In Progress")'

10. Coordinate Breaking Changes

If your change will break other agents' work, coordinate explicitly:

# Announce in main issue
gh issue comment <tracking-issue> --body "⚠️ PR #<number> will rename function X → Y. Other agents should wait for this to merge."

# Or create tracking issue
gh issue create --title "Coordination: Breaking change in PR #<number>" --body "..."

Troubleshooting

Tests Failing Locally

# Run tests with verbose output
uv run pytest -v

# Run specific test
uv run pytest tests/test_specific.py::test_function

# Run with coverage
uv run poe test-coverage

# Check test markers
uv run pytest --markers

Linting Errors

# See all linting issues
uv run poe lint

# Auto-fix what's possible
uv run poe fix

# Check specific file
uv run ruff check path/to/file.py

Type Checking Errors

# Run ty type checker
uv run poe typecheck

# Or run ty directly
uv run ty check

# See ty config
# Check [tool.ty] in pyproject.toml

# Note: ty is pre-alpha and may report false positives
# Uses --exit-zero to prevent CI failures during early adoption

Pre-commit Hook Timeouts

If pre-commit hooks timeout (e.g., in network-restricted environments):

# Use lite config
pre-commit run --config .pre-commit-config-lite.yaml --all-files

# Or skip hooks temporarily
git commit --no-verify

# But then run full validation manually
uv run poe check

Coverage Failures

# Run tests with coverage report
uv run poe test-coverage

# View HTML coverage report
open htmlcov/index.html

# Check coverage for specific files
uv run pytest --cov=katana_public_api_client --cov-report=term-missing

Additional Resources

CLAUDE.md - Project overview and quick start
docs/CONTRIBUTING.md - Contribution guidelines
.github/copilot-instructions.md - Detailed instructions for GitHub Copilot
pyproject.toml - See all poe tasks and configurations
GitHub Project - Automation & Agent Infrastructure roadmap

Using Git Worktrees for Parallel Sessions

Git worktrees let you run multiple Claude Code sessions on the same repository without conflicts. Each worktree is an isolated copy of the repo with its own working directory and branch.

When to Use Worktrees

Running multiple Claude Code sessions in parallel on different tasks
Working on a feature while keeping main clean for reviews
Testing changes in isolation without stashing or committing

Quick Setup

# Create a worktree for a specific task
git worktree add ../katana-feature-123 -b feature/123-my-task

# Work in the worktree (each Claude Code session gets its own)
cd ../katana-feature-123

# When done, clean up
git worktree remove ../katana-feature-123

Tips

Each worktree has its own .venv - run uv sync --all-extras in new worktrees
Worktrees share the same .git history - commits in one are visible in all
Don't have two worktrees on the same branch (causes confusion)
Clean up worktrees when done: git worktree list to see all, git worktree prune to remove stale entries

Summary: The Golden Rules

✅ Use tiered validation - quick-check during dev, check before PR, full-check before review
✅ PRs must be green - No skips, no excludes, no failures
✅ Communicate early - Claim issues, update progress, signal blocks
✅ Follow conventions - Branch naming, commit messages, PR format
✅ Coordinate conflicts - Check before starting, rebase regularly, resolve proactively
✅ Ask for help - If blocked, ask in issue comments
✅ Document exceptions - If you must skip/exclude, document why in PR

Happy coding! 🤖

Uh oh!

FilesExpand file tree

AGENT_WORKFLOW.md

Latest commit

History

AGENT_WORKFLOW.md

File metadata and controls

Agent Workflow Guide

Quick Reference

Using Custom GitHub Copilot Agents

Available Agents

Specialist Agents

Coordinator Agent

Agent Workflow Patterns

Single Agent (Direct Task)

Multi-Agent Coordination

Project-Level Coordination

Agent Definition Files

When to Use Which Agent

Example: Complete Feature Workflow

Step-by-Step Workflow

1. Starting Work on an Issue

Check for Conflicts

Create Your Branch

Update Issue Status

2. Development Workflow

Fast Iteration Loop

Before Committing

3. Before Opening a Pull Request

Run Full Validation

Push Your Branch

4. Opening the Pull Request

Use GitHub CLI

PR Checklist

Request Review

5. Handling Review Feedback

Make Changes

Respond to Comments

6. Before Merge

Final Validation

Ensure CI is Green

Merge

Validation Tiers Reference

Quick Check

Agent Check

Check

Full Check

Conflict Resolution

Detecting Conflicts

Before Starting Work

During Work

Resolving Conflicts

Simple Rebase

Complex Conflicts

Common Pitfalls & Solutions

❌ Pitfall: Skipping Validation

❌ Pitfall: Committing with Failures

❌ Pitfall: Adding Test/Lint Skips

❌ Pitfall: Force Pushing Without Care

❌ Pitfall: Not Updating Branch

❌ Pitfall: Unclear Commit Messages

Pre-commit Hook Usage

Lite Config (Fast Iteration)

Full Config (Complete Validation)

Working with Multiple Agents

Coordination Strategies

1. Claim Issues Early

2. Check for Conflicts BEFORE Starting

3. Communicate Progress in Issue Comments

4. Branch Naming for Clarity

5. File-Level Conflict Detection

6. Merge Order Coordination

7. Self-Coordination Strategies

8. Rebase Frequently

9. Use GitHub Projects for Visibility

10. Coordinate Breaking Changes

Troubleshooting

Tests Failing Locally

Linting Errors

Type Checking Errors