AGENTS.md Critique Report

What worked well

• Clear purpose statement: The opening line immediately tells me this is a REST API backend that routes chat requests and implements AG-UI protocol streaming.
• Explicit "do not modify" list: Calling out migrations/env.py, static/, templates/, and alembic_migration.py prevents common mistakes.
• Command reference with context: All commands show they must be run from project root, and include the dr task run prefix consistently.
• Technology stack clarity: SQLModel, Pydantic v2, async/await, SSE streaming — I know what patterns to expect.
• Migration workflow: The two-step process for database changes is clearly documented with example commands.
• Critical constraints section: Calling out async DB limitations, required env vars, and mypy strict mode sets clear expectations.
• Dependency on core: Explicitly mentions the shared core/ library and when to reinstall.

What was unclear or missing

1. What is "AG-UI protocol" and where is the spec?

The AGENTS.md mentions "AG-UI protocol" and "ag-ui-protocol spec" multiple times but never explains what it is or links to documentation. I see app/ag_ui/ exists, but I don't know what protocol constraints I need to maintain.

Suggested fix: Add to the Key directories section:

- `app/ag_ui/` — AG-UI protocol implementation (streaming, storage, translation)
  - Implements the [ag-ui-protocol spec](link-to-spec) for server-sent events (SSE) based chat streaming
  - Key modules: `stream_manager.py` (SSE handling), `storage.py` (chat persistence), `translate.py` (protocol translation)

2. What does "deployed agent" mean?

The opening says it routes "chat requests to the deployed agent" but never explains what/where this agent is, how it's configured, or what the integration point looks like.

Suggested fix: Add to a new "Architecture" section:

## Architecture overview

This FastAPI server acts as a middleware layer:
- Frontend → FastAPI (this server) → Agent backend (configured via `AGENT_URL` env var)
- The agent backend implements the actual AI/LLM logic
- This server translates between frontend requests and AG-UI protocol streaming

3. How do I know which route module to create for a new feature?

The conventions say "create module in app/api/v1/, register in app/main.py" but I don't know:

• What naming convention to use for the module?
• What the registration pattern looks like in main.py?
• Should I follow the pattern from existing modules like chat.py or auth.py?

Suggested fix: Add to Conventions:

- New routes: create module in `app/api/v1/` (e.g., `users.py` for `/api/v1/users` endpoints)
  - Use `APIRouter` from FastAPI
  - Register in `app/main.py` via `app.include_router(router, prefix="/api/v1", tags=["tag_name"])`
  - See `app/api/v1/chat.py` for reference pattern

4. What's the relationship between app/models/ and migrations?

I know SQLModel models live in app/models/ and I need to generate migrations after changes, but:

• Do I need to import new models anywhere for Alembic to detect them?
• Are there base classes or mixins I should use?
• What's the file structure inside app/models/?

Suggested fix: Add to Database migrations section:

After changing SQLModel models in `app/models/`:
- Ensure new models are imported in `app/models/__init__.py` for Alembic auto-detection
- All models should inherit from `SQLModel` with `table=True`
- Then generate and apply migrations:

5. What authentication/authorization pattern should I follow?

I see app/auth/ and app/deps.py mentioned, but no guidance on:

• How to protect a route (decorator? dependency?)
• What the session management looks like
• Whether there are different permission levels

Suggested fix: Add to Conventions:

- Authentication: Use dependency injection from `app/deps.py`
  - `get_current_user` dependency for protected routes
  - `get_optional_user` for routes that work with/without auth
  - Example: `async def my_route(user: User = Depends(get_current_user)):`

6. What's the test structure and how do I run specific tests?

The AGENTS.md says tests mirror app/ structure, but:

• Are there fixtures I should know about?
• How do I run a single test file or test function?
• What's the difference between tests/ and tests/integration/?

Suggested fix: Add to Commands section:

dr task run fastapi_server:test              # all tests with coverage
dr task run fastapi_server:test -- tests/api/v1/test_chat.py  # specific file
dr task run fastapi_server:test -- -k test_name  # specific test

Tests use fixtures from `tests/conftest.py` (DB setup, test client, auth mocks).
Integration tests in `tests/integration/` test full request/response cycles.

7. What environment variables are required vs optional?

Critical constraints mention some env vars, but I don't have a complete list or know defaults.

Suggested fix: Add new section:

## Environment variables

Required:
- `SESSION_SECRET_KEY` — session encryption (use `test-secret-key` for tests)

Optional:
- `DATABASE_URL` — defaults to SQLite `./test.db` (use PostgreSQL with asyncpg in production)
- `AGENT_URL` — agent backend endpoint (defaults to `http://localhost:8842`)
- `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET` — for Google OAuth
- `BOX_CLIENT_ID`, `BOX_CLIENT_SECRET` — for Box OAuth
- `LOG_LEVEL` — logging verbosity (default: `INFO`)

Commands or instructions that need fixing

1. Migration command description is ambiguous

dr task run fastapi_server:migrate-generate -- "describe the change"

The -- separator suggests the description is passed as an argument, but it's unclear if this is the migration message or if there's a -m flag needed.

Suggested fix: Show the actual Alembic pattern:

dr task run fastapi_server:migrate-generate -- -m "describe the change"

2. No command for running a single test

The test command only shows running all tests, but during development I'd want to run specific tests.

Suggested fix: Already covered in gap #6 above.

Suggested additions

1. Add a "Quick Start" section

## Quick Start

First time setup:
```shell
# From project root
dr task run fastapi_server:install
dr task run fastapi_server:migrate
export SESSION_SECRET_KEY="dev-secret-key-change-in-production"
dr task run fastapi_server:dev

Server runs on http://localhost:8080 API docs at http://localhost:8080/docs (Swagger UI)

### 2. **Add "Common Tasks" section**
```markdown
## Common Tasks

**Add a new API endpoint:**
1. Create/modify route handler in `app/api/v1/your_module.py`
2. Register router in `app/main.py` if new module
3. Add tests in `tests/api/v1/test_your_module.py`
4. Run `dr task run fastapi_server:test` and `dr task run fastapi_server:lint`

**Add a new database model:**
1. Define SQLModel class in `app/models/your_model.py`
2. Import in `app/models/__init__.py`
3. Generate migration: `dr task run fastapi_server:migrate-generate -- -m "add your_model"`
4. Review migration in `migrations/versions/`
5. Apply: `dr task run fastapi_server:migrate`

**Debug a failing test:**
```shell
dr task run fastapi_server:test -- -v -s tests/path/to/test.py::test_function_name

### 3. **Add "File Organization" section**
```markdown
## File Organization

app/ ├── api/v1/ # REST endpoints (chat.py, auth.py, oauth.py) ├── ag_ui/ # AG-UI protocol streaming implementation ├── auth/ # Authentication middleware and utilities ├── models/ # SQLModel database models ├── deps.py # FastAPI dependencies (auth, DB session) ├── db.py # Database engine and session factory └── main.py # Application factory and router registration

4. Add troubleshooting section

## Troubleshooting

**"No module named 'core'"**: Run `dr task run fastapi_server:install` after pulling core changes

**Migration conflicts**: If multiple branches modify models, you may need to merge migration files or regenerate

**SQLite "database is locked"**: SQLite doesn't support async well; use PostgreSQL for concurrent requests

**OAuth redirect fails**: Ensure `*_CLIENT_ID` and `*_CLIENT_SECRET` are set and callback URLs match OAuth app config

Overall verdict

NEEDS WORK — The AGENTS.md provides good structural orientation and command reference, but lacks critical context about the AG-UI protocol, agent integration, authentication patterns, and practical examples that would prevent a new agent from having to grep through the codebase to understand how to implement common tasks.