AGENTS.md

1# AutoGPT Platform Contribution Guide
2 
3This guide provides context for coding agents when updating the **autogpt_platform** folder.
4 
5## Directory overview
6 
7- `autogpt_platform/backend` – FastAPI based backend service.
8- `autogpt_platform/autogpt_libs` – Shared Python libraries.
9- `autogpt_platform/frontend` – Next.js + Typescript frontend.
10- `autogpt_platform/docker-compose.yml` – development stack.
11 
12See `docs/content/platform/getting-started.md` for setup instructions.
13 
14## Code style
15 
16- Format Python code with `poetry run format`.
17- Format frontend code using `pnpm format`.
18 
19## Frontend guidelines:
20 
21See `/frontend/CONTRIBUTING.md` for complete patterns. Quick reference:
22 
231. **Pages**: Create in `src/app/(platform)/feature-name/page.tsx`
24   - Add `usePageName.ts` hook for logic
25   - Put sub-components in local `components/` folder
262. **Components**: Structure as `ComponentName/ComponentName.tsx` + `useComponentName.ts` + `helpers.ts`
27   - Use design system components from `src/components/` (atoms, molecules, organisms)
28   - Never use `src/components/__legacy__/*`
293. **Data fetching**: Use generated API hooks from `@/app/api/__generated__/endpoints/`
30   - Regenerate with `pnpm generate:api`
31   - Pattern: `use{Method}{Version}{OperationName}`
324. **Styling**: Tailwind CSS only, use design tokens, Phosphor Icons only
335. **Testing**: Integration tests (Vitest + RTL + MSW) are the default (~90%, page-level). Playwright for E2E critical flows. Storybook for design system components. See `autogpt_platform/frontend/TESTING.md`
346. **Code conventions**: Function declarations (not arrow functions) for components/handlers
35 
36- Component props should be `interface Props { ... }` (not exported) unless the interface needs to be used outside the component
37- Separate render logic from business logic (component.tsx + useComponent.ts + helpers.ts)
38- Colocate state when possible and avoid creating large components, use sub-components ( local `/components` folder next to the parent component ) when sensible
39- Avoid large hooks, abstract logic into `helpers.ts` files when sensible
40- Use function declarations for components, arrow functions only for callbacks
41- No barrel files or `index.ts` re-exports
42- Avoid comments at all times unless the code is very complex
43- Do not use `useCallback` or `useMemo` unless asked to optimise a given function
44- Do not type hook returns, let Typescript infer as much as possible
45- Never type with `any`, if not types available use `unknown`
46 
47## Testing
48 
49- Backend: `poetry run test` (runs pytest with a docker based postgres + prisma).
50- Frontend integration tests: `pnpm test:unit` (Vitest + RTL + MSW, primary testing approach).
51- Frontend E2E tests: `pnpm test` or `pnpm test-ui` for Playwright tests.
52- See `autogpt_platform/frontend/TESTING.md` for the full testing strategy.
53 
54Always run the relevant linters and tests before committing.
55Use conventional commit messages for all commits (e.g. `feat(backend): add API`).
56Types: - feat - fix - refactor - ci - dx (developer experience)
57Scopes: - platform - platform/library - platform/marketplace - backend - backend/executor - frontend - frontend/library - frontend/marketplace - blocks
58 
59## Pull requests
60 
61- Use the template in `.github/PULL_REQUEST_TEMPLATE.md`.
62- Rely on the pre-commit checks for linting and formatting
63- Fill out the **Changes** section and the checklist.
64- Use conventional commit titles with a scope (e.g. `feat(frontend): add feature`).
65- Keep out-of-scope changes under 20% of the PR.
66- Ensure PR descriptions are complete.
67- For changes touching `data/*.py`, validate user ID checks or explain why not needed.
68- If adding protected frontend routes, update `frontend/lib/supabase/middleware.ts`.
69- Use the linear ticket branch structure if given codex/open-1668-resume-dropped-runs
70