AGENTS.md

1# AutoGPT Platform
2 
3This file provides guidance to coding agents when working with code in this repository.
4 
5## Repository Overview
6 
7AutoGPT Platform is a monorepo containing:
8 
9- **Backend** (`backend`): Python FastAPI server with async support
10- **Frontend** (`frontend`): Next.js React application
11- **Shared Libraries** (`autogpt_libs`): Common Python utilities
12 
13## Component Documentation
14 
15- **Backend**: See @backend/AGENTS.md for backend-specific commands, architecture, and development tasks
16- **Frontend**: See @frontend/AGENTS.md for frontend-specific commands, architecture, and development patterns
17 
18## Key Concepts
19 
201. **Agent Graphs**: Workflow definitions stored as JSON, executed by the backend
212. **Blocks**: Reusable components in `backend/backend/blocks/` that perform specific tasks
223. **Integrations**: OAuth and API connections stored per user
234. **Store**: Marketplace for sharing agent templates
245. **Virus Scanning**: ClamAV integration for file upload security
25 
26### Environment Configuration
27 
28#### Configuration Files
29 
30- **Backend**: `backend/.env.default` (defaults) → `backend/.env` (user overrides)
31- **Frontend**: `frontend/.env.default` (defaults) → `frontend/.env` (user overrides)
32- **Platform**: `.env.default` (Supabase/shared defaults) → `.env` (user overrides)
33 
34#### Docker Environment Loading Order
35 
361. `.env.default` files provide base configuration (tracked in git)
372. `.env` files provide user-specific overrides (gitignored)
383. Docker Compose `environment:` sections provide service-specific overrides
394. Shell environment variables have highest precedence
40 
41#### Key Points
42 
43- All services use hardcoded defaults in docker-compose files (no `${VARIABLE}` substitutions)
44- The `env_file` directive loads variables INTO containers at runtime
45- Backend/Frontend services use YAML anchors for consistent configuration
46- Supabase services (`db/docker/docker-compose.yml`) follow the same pattern
47 
48### Branching Strategy
49 
50- **`dev`** is the main development branch. All PRs should target `dev`.
51- **`master`** is the production branch. Only used for production releases.
52 
53### Creating Pull Requests
54 
55- Create the PR against the `dev` branch of the repository.
56- **Split PRs by concern** — each PR should have a single clear purpose. For example, "usage tracking" and "credit charging" should be separate PRs even if related. Combining multiple concerns makes it harder for reviewers to understand what belongs to what.
57- Ensure the branch name is descriptive (e.g., `feature/add-new-block`)
58- Use conventional commit messages (see below)
59- **Structure the PR description with Why / What / How** — Why: the motivation (what problem it solves, what's broken/missing without it); What: high-level summary of changes; How: approach, key implementation details, or architecture decisions. Reviewers need all three to judge whether the approach fits the problem.
60- Fill out the .github/PULL_REQUEST_TEMPLATE.md template as the PR description
61- Always use `--body-file` to pass PR body — avoids shell interpretation of backticks and special characters:
62```bash
63  PR_BODY=$(mktemp)
64  cat > "$PR_BODY" << 'PREOF'
65  ## Summary
66  - use `backticks` freely here
67  PREOF
68  gh pr create --title "..." --body-file "$PR_BODY" --base dev
69  rm "$PR_BODY"
70```
71- Run the github pre-commit hooks to ensure code quality.
72 
73### Test-Driven Development (TDD)
74 
75When fixing a bug or adding a feature, follow a test-first approach:
76 
771. **Write a failing test first** — create a test that reproduces the bug or validates the new behavior, marked with `@pytest.mark.xfail` (backend) or `.fixme` (Playwright). Run it to confirm it fails for the right reason.
782. **Implement the fix/feature** — write the minimal code to make the test pass.
793. **Remove the xfail marker** — once the test passes, remove the `xfail`/`.fixme` annotation and run the full test suite to confirm nothing else broke.
80 
81This ensures every change is covered by a test and that the test actually validates the intended behavior.
82 
83### Reviewing/Revising Pull Requests
84 
85Use `/pr-review` to review a PR or `/pr-address` to address comments.
86 
87When fetching comments manually:
88- `gh api repos/Significant-Gravitas/AutoGPT/pulls/{N}/reviews --paginate` — top-level reviews
89- `gh api repos/Significant-Gravitas/AutoGPT/pulls/{N}/comments --paginate` — inline review comments (always paginate to avoid missing comments beyond page 1)
90- `gh api repos/Significant-Gravitas/AutoGPT/issues/{N}/comments` — PR conversation comments
91 
92### Conventional Commits
93 
94Use this format for commit messages and Pull Request titles:
95 
96**Conventional Commit Types:**
97 
98- `feat`: Introduces a new feature to the codebase
99- `fix`: Patches a bug in the codebase
100- `refactor`: Code change that neither fixes a bug nor adds a feature; also applies to removing features
101- `ci`: Changes to CI configuration
102- `docs`: Documentation-only changes
103- `dx`: Improvements to the developer experience
104 
105**Recommended Base Scopes:**
106 
107- `platform`: Changes affecting both frontend and backend
108- `frontend`
109- `backend`
110- `infra`
111- `blocks`: Modifications/additions of individual blocks
112 
113**Subscope Examples:**
114 
115- `backend/executor`
116- `backend/db`
117- `frontend/builder` (includes changes to the block UI component)
118- `infra/prod`
119 
120Use these scopes and subscopes for clarity and consistency in commit messages.
121