AGENTS.md

1# Agent Guidelines
2 
3## Engineering Workflow
4- **Install**: `task sync` (from `Taskfile.yml`)
5- **Dev**: `task run-query-engine-backend-dev` (from `Taskfile.yml`)
6- **Test**: `task test` (from `Taskfile.yml`)
7- **Lint**: `task lint` (from `Taskfile.yml`)
8- **Type check**: `task typecheck` (from `Taskfile.yml`)
9 
10## Dependency Guide
11- **Overview**: Full dependency descriptions are maintained in `dependencies_overview.md`.
12- **Usage**: Keep this section concise and treat `dependencies_overview.md` as the source-of-truth dependency catalog.
13 
14## Business Logic Domain
15- **Overview**: AI-driven codebase analysis service that orchestrates repository workflows to generate structured documentation outputs and track execution across codebases.
16- **Core data focus**: Provider configuration (including OAuth flows), model parameters/catalogs, tool/MCP server setup, repository rulesets/metadata, and agent runtime dependencies.
17- **Workflow telemetry**: Agent events, workflow envelopes, and usage/cost statistics capture lifecycle and execution monitoring.
18- **Structured outputs**: Typed schemas for agent markdown responses, AGENTS.md updates, engineering workflows, and business logic summaries.
19- **Primary references**: See `business_logic_references.md` for the source-of-truth module map.
20 
21## App Interfaces
22- **Protocol**: FastAPI HTTP endpoints under `src/unoplat_code_confluence_query_engine/api/v1/endpoints`.
23- **Surface area**: Model configuration + provider/OAuth flows, feature flag CRUD, repository agent rules/snapshots/markdown PR endpoints, and tool configuration management.
24- **Reference map**: See `app_interfaces.md` for endpoint-to-module details.
25 
26## Architecture
27See [`architecture.md`](./architecture.md) for the current validated Mermaid architecture diagram when external interfaces are detected.
28 
29## Commands
30- **Test all**: `task test` (starts deps, runs tests with coverage, stops deps)
31- **Test single**: `uv run --group test pytest tests/path/to/test_file.py::test_function_name -v`
32- **Lint**: `task lint` (check) or `task lint-fix` (auto-fix)
33- **Format**: `task format` (ruff formatter)
34- **Type check**: `task typecheck` (pyrefly strict preset)
35- **Dev server**: `task run-query-engine-backend-dev` (port 8001)
36 
37## Code Style
38- **Imports**: Absolute only (no relative), use ruff for ordering (`task lint-fix`)
39- **Types**: Always precise types - never use `Any`, use `typing` module generics
40- **Functions**: No nested functions - keep flat structure at module level
41- **Pydantic**: Use `model_dump_json()` for JSON serialization (not `json.dumps`)
42- **Docstrings**: Google format, omit `ctx` param (dependency injection magic)
43- **Sessions**: Always `session.begin()` but yield `AsyncSession` for auto-transactions
44- **Error handling**: Use structured exceptions, add proper context/trace IDs
45- **Tool verification**: Use context7 tool to verify API methods before implementation
46- **Python commands**: Always use `uv run --group <group>` (e.g., `--group test` for tests)
47 
48 
49## Caveats
501. When a shell command fails with "failed in sandbox", use the permission request tool (with 'with_escalated_permissions") to ask the user for approval before
51retrying.
522. always when want to run python script open shell with 'uv run python'.
53 
54## Backlog Workflow
55 
56This project uses Backlog.md MCP for all task and project management. Before creating tasks or tracking work, read [`backlog_instructions.md`](./backlog_instructions.md) for the complete workflow guidance.
57 
58<!-- UNOPLAT_CODE_CONFLUENCE_CONTEXT:BEGIN -->
59<CRITICAL_INSTRUCTION>
60 
61> Generated from branch `dev` at commit `5ecdba39d57f50c5188a8e32b9dd4f52d01611fe` (2026-07-18). Content may become stale as new commits land.
62 
63</CRITICAL_INSTRUCTION>
64 
65## Engineering Workflow
66### Install
67- `task sync` (repo root; `Taskfile.yml` -> `uv sync`)
68### Build
69- Not detected
70### Dev
71- `task run-query-engine-backend-dev` (repo root; `Taskfile.yml` -> `uv run fastapi dev --port 8001` in `src/unoplat_code_confluence_query_engine`)
72### Test
73- `task test` (repo root; `Taskfile.yml` -> starts dependencies, runs `uv sync --group test`, then `uv run --python 3.13 --group test pytest --cov=src/unoplat_code_confluence_query_engine --cov-report=html:coverage_reports tests/ -v`)
74### Lint
75- `task lint` (repo root; `Taskfile.yml` -> `uv run --group dev ruff check src/`)
76### Type Check
77- `task typecheck` (repo root; `Taskfile.yml` -> `uv run --group dev pyrefly check src/`)
78 
79## Dependency Guide
80See [`dependencies_overview.md`](./dependencies_overview.md) for the full dependency catalog and usage notes.
81 
82## Business Domain
83### Description
84 
85This service is an AI-assisted codebase analysis and repository automation engine. It manages model/provider and tool credentials, launches Temporal workflows that inspect repositories, generate engineering and dependency guidance, validate framework usage, and produce/update AGENTS.md artifacts and pull requests. It also supports Codex OAuth, feedback submission, and feature flags for operating the agent runtime.
86 
87### References
88 
89See [`business_domain_references.md`](./business_domain_references.md) for the supporting source references used to derive this domain summary.
90 
91## App Interfaces
92See [`app_interfaces.md`](./app_interfaces.md) for the canonical interface and endpoint reference.
93 
94## Architecture
95See [`architecture.md`](./architecture.md) for the canonical system architecture diagram.
96 
97<!-- UNOPLAT_CODE_CONFLUENCE_CONTEXT:END -->
98