AGENTS.md - Guide for AI Agents

Copy this template to new repositories and customize for your project.

Documentation Structure

Keep documentation minimal and focused:

1. AGENTS.md (this file) - HOW to work on this codebase
2. PROJECT_STATUS.md - WHAT's done, what's next, current blockers
3. README.md - Project overview for humans

Rule: Update AGENTS.md when conventions change. Update PROJECT_STATUS.md after every task.

Project Overview

Project Name: [Your Project Name]

Goal: [One sentence describing the project goal]

Tech Stack: [Languages, frameworks, key tools]

See PROJECT_STATUS.md for current sprint and next steps.

Core Principles

1. TDD (Test-Driven Development)

MANDATORY: Write tests FIRST, then implementation.

# Run tests
pytest tests/ -v

# Check coverage
pytest tests/ --cov=. --cov-report=term-missing

Coverage requirement: ≥80% for all new code.

2. Never Write Code Directly

RULE: AI agents NEVER write code directly. Always delegate to droid exec.

Why:

• Droid exec follows TDD properly (writes tests first)
• You writing code = no tests = bugs in production
• Delegation is faster and higher quality

Your role:

• ✅ Write specs
• ✅ Review droid exec output
• ✅ Verify correctness
• ❌ Write code

3. Git Workflow (Simplified)

Default: Work on develop branch

# Daily workflow
git checkout develop
git pull

# Make changes (via droid exec)
git add files
git commit -m "type: description"
git push

Feature branches: Only if needed, MAX 24 hours

# Create short-lived branch
git checkout -b feat/quick-feature

# Work (max 1 day!)
git commit -m "feat: something"

# Merge same day
git checkout develop
git merge feat/quick-feature --no-ff
git branch -d feat/quick-feature
git push

Rules:

• Merge daily (no long-lived branches)
• Never commit to master directly
• Feature branches MAX 24 hours

Droid Exec Delegation

When to Delegate

ALWAYS delegate if:

• Writing any code (even "quick" fixes)
• Creating new files
• Modifying multiple files
• Writing tests
• Bug fixes

Only do yourself:

• Reading/analyzing code
• Writing specs
• Code review
• Planning with user

Delegation Workflow

# 1. Create spec in tasks/pending/
vim tasks/pending/feature_name.md

# 2. Commit spec FIRST
git add tasks/pending/feature_name.md
git commit -m "spec: add feature spec"

# 3. Run droid exec
droid exec --auto {low|medium|high} -f tasks/pending/feature_name.md

# 4. Review ALL output
# - Read generated files
# - Run tests
# - Verify correctness

# 5. Commit droid exec output
git add {files}
git commit -m "feat: description (via droid exec)

Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>"

# 6. Move spec to completed
mv tasks/pending/feature_name.md tasks/completed/$(date +%Y-%m-%d)_feature_name.md
git add tasks/
git commit -m "chore: mark feature as completed"

Autonomy Levels

• --auto low: File operations only (create, edit, delete files)
• --auto medium: File operations + commands (pip, npm, pytest, build tools)
• --auto high: Production operations (git push, deploys)

How to choose:

• Need to run tests? → medium
• Need to install packages? → medium
• Just creating/editing files? → low
• Need to push code? → high

Spec Guidelines

Droid exec is SMART - don't write implementation code for it.

Good spec:

• 50-100 lines
• Focus on WHAT (not HOW)
• List requirements clearly
• Include TDD section (tests to write FIRST)
• Define success criteria
• Provide validation steps

Bad spec:

• 200+ lines of code examples
• Detailed implementation instructions
• No mention of tests

TDD section (MANDATORY in every spec):

## TDD Approach

### Write Tests FIRST

Create `tests/test_feature.py` with:
- test_function_handles_valid_input()
- test_function_rejects_invalid_input()
- test_function_handles_edge_cases()

Run: pytest tests/test_feature.py -v
Expected: All tests FAIL (no implementation yet)

### Implement to Make Tests Pass

Create/modify implementation files...

Task Organization

tasks/
├── pending/           # Not started or in progress
├── completed/         # Done (dated: 2025-10-11_task_name.md)
└── templates/         # Spec templates

Completion script:

# Mark task complete
python scripts/complete_task.py task_name
# Moves from pending/ to completed/YYYY-MM-DD_task_name.md
# Updates PROJECT_STATUS.md

Code Conventions

Style:

• Formatter: [Black / Prettier / your choice]
• Linter: [Flake8 / ESLint / your choice]
• Files: lowercase_with_underscores
• Classes: PascalCase
• Functions: snake_case

Commit messages:

type(scope): description

Types: feat, fix, test, docs, refactor, chore

Testing Standards

Test structure:

tests/
├── test_module_name.py     # Unit tests
├── test_integration.py      # Integration tests
└── conftest.py             # Pytest fixtures

Naming:

• Test files: test_<module_name>.py
• Test functions: test_<function>_<scenario>()
• Test classes: Test<ClassName>

Coverage:

• Minimum: 80%
• Critical paths: 100%
• Check: pytest --cov=. --cov-report=term-missing

Common Commands

# Test
pytest tests/ -v

# Format
[your formatter command]

# Lint
[your linter command]

# Run project
[your run command]

AI-Specific Rules

1. Read PROJECT_STATUS.md FIRST every session
2. Create feature branch before work (if needed)
3. Write tests before implementation (TDD)
4. Run tests before committing
5. Update PROJECT_STATUS.md after completing work
6. Keep responses SHORT (no walls of text)
7. Default to delegation (droid exec does work, you review)
8. Never write code directly

Resources

• Droid Exec Docs: [Link to your droid exec documentation]
• Project Status: PROJECT_STATUS.md (READ FIRST)
• Task Examples: tasks/completed/ for delegation patterns

---

Customization Checklist

When copying this template to a new repo:

• Update project name and goal
• Update tech stack
• Update test commands
• Update formatting/linting tools
• Update common commands
• Add project-specific conventions
• Create PROJECT_STATUS.md
• Create tasks/ directory structure