Agent Guidelines

Engineering Workflow

• Install: task sync (from Taskfile.yml)
• Dev: task run-query-engine-backend-dev (from Taskfile.yml)
• Test: task test (from Taskfile.yml)
• Lint: task lint (from Taskfile.yml)
• Type check: task typecheck (from Taskfile.yml)

Dependency Guide

• Overview: Full dependency descriptions are maintained in dependencies_overview.md.
• Usage: Keep this section concise and treat dependencies_overview.md as the source-of-truth dependency catalog.

Business Logic Domain

• Overview: AI-driven codebase analysis service that orchestrates repository workflows to generate structured documentation outputs and track execution across codebases.
• Core data focus: Provider configuration (including OAuth flows), model parameters/catalogs, tool/MCP server setup, repository rulesets/metadata, and agent runtime dependencies.
• Workflow telemetry: Agent events, workflow envelopes, and usage/cost statistics capture lifecycle and execution monitoring.
• Structured outputs: Typed schemas for agent markdown responses, AGENTS.md updates, engineering workflows, and business logic summaries.
• Primary references: See business_logic_references.md for the source-of-truth module map.

App Interfaces

• Protocol: FastAPI HTTP endpoints under src/unoplat_code_confluence_query_engine/api/v1/endpoints.
• Surface area: Model configuration + provider/OAuth flows, feature flag CRUD, repository agent rules/snapshots/markdown PR endpoints, and tool configuration management.
• Reference map: See app_interfaces.md for endpoint-to-module details.

Architecture

See architecture.md for the current validated Mermaid architecture diagram when external interfaces are detected.

Commands

• Test all: task test (starts deps, runs tests with coverage, stops deps)
• Test single: uv run --group test pytest tests/path/to/test_file.py::test_function_name -v
• Lint: task lint (check) or task lint-fix (auto-fix)
• Format: task format (ruff formatter)
• Type check: task typecheck (pyrefly strict preset)
• Dev server: task run-query-engine-backend-dev (port 8001)

Code Style

• Imports: Absolute only (no relative), use ruff for ordering (task lint-fix)
• Types: Always precise types - never use Any, use typing module generics
• Functions: No nested functions - keep flat structure at module level
• Pydantic: Use model_dump_json() for JSON serialization (not json.dumps)
• Docstrings: Google format, omit ctx param (dependency injection magic)
• Sessions: Always session.begin() but yield AsyncSession for auto-transactions
• Error handling: Use structured exceptions, add proper context/trace IDs
• Tool verification: Use context7 tool to verify API methods before implementation
• Python commands: Always use uv run --group <group> (e.g., --group test for tests)

Caveats

1. 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 retrying.
2. always when want to run python script open shell with 'uv run python'.

Backlog Workflow

This project uses Backlog.md MCP for all task and project management. Before creating tasks or tracking work, read backlog_instructions.md for the complete workflow guidance.

<CRITICAL_INSTRUCTION>

Generated from branch dev at commit 5ecdba39d57f50c5188a8e32b9dd4f52d01611fe (2026-07-18). Content may become stale as new commits land.

</CRITICAL_INSTRUCTION>

Engineering Workflow

Install

• task sync (repo root; Taskfile.yml -> uv sync)

Build

• Not detected

Dev

• task run-query-engine-backend-dev (repo root; Taskfile.yml -> uv run fastapi dev --port 8001 in src/unoplat_code_confluence_query_engine)

Test

• 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)

Lint

• task lint (repo root; Taskfile.yml -> uv run --group dev ruff check src/)

Type Check

• task typecheck (repo root; Taskfile.yml -> uv run --group dev pyrefly check src/)

Dependency Guide

See dependencies_overview.md for the full dependency catalog and usage notes.

Business Domain

Description

This 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.

References

See business_domain_references.md for the supporting source references used to derive this domain summary.

App Interfaces

See app_interfaces.md for the canonical interface and endpoint reference.

Architecture

See architecture.md for the canonical system architecture diagram.

🎥 Demo: Agents.md-first Context

What's in the demo: automatic AGENTS.md generation per repo and an org index that gives any coding agent a precise source of truth. See a sample PR created by the tool.

⚠️ The Problem

AI coding agents excel at greenfield projects (new codebases built from scratch) but struggle with brownfield codebases (mature, production systems with existing code).

Why? They burn most of their context window on exploration—searching files, tracing flows, connecting dots—leaving little capacity for actual implementation. By the time they're ready to code, they've hit the "dumb zone" where performance degrades sharply. And since they lack long-term memory, this cycle repeats with every conversation.

Multi-repo complexity makes it worse. When code is split across connected repositories, the agent exhausts its context just mapping dependencies between codebases—often before writing a single line.

Internal dependencies present another failure mode. The agent has no onboarding to proprietary systems, so it hallucinates usage patterns. Worse, when internal documentation has drifted from actual implementation, the agent trusts those "lies" and produces code that doesn't work.

The end result: slop code requiring heavy rework.

🎯 The Solution

Unoplat Code Confluence is the context engine for application development, organizing precise, up-to-date knowledge of your data models, entry points, endpoints, and more—so coding agents can deliver and maintain features 2–3x faster with higher quality.

AGENTS.md-first Context

Auto-generates machine-readable AGENTS.md files per repo to give coding agents a precise source of truth:

• Engineering Workflow — Canonical install/build/dev/test/lint/type_check commands plus key config files and their responsibilities
• Business Logic — Core application logic, domain entities, and database entities
• Entry Points & Interfaces — Main entry points, API endpoints, and external interfaces
• External Dependencies — Roles and responsibilities of external libraries

🌟 Core Principles

1. Precision First

• Extensible Language Support: Modular Tree-sitter based grammar extraction delivers consistent, accurate code context across all programming languages
• Extensible Framework-Aware Parsing: Specialized grammar engines recognize framework and library-specific patterns based on project dependencies

2. Context Engineering

• All important metadata about application—dependencies, inbound/outbound interfaces, domain models, and data store models—are identified and their relationships preserved

3. Enterprise-Grade Scalability, Reliability and Auditability

• Scalable, auditable and reliable processing powered by workflow orchestrator

🚀 Getting Started

Ready to enhance your development workflow?

Check out our Quick Start Guide.

🧠 Agent Skill

This repository includes a portable agent skill for the Unoplat Code Confluence CLI at skills/unoplat-code-confluence-cli/SKILL.md.

Install it with the skills CLI:

npx skills add https://github.com/unoplat/unoplat-code-confluence --skill unoplat-code-confluence-cli

The skill teaches compatible coding agents how to use ucc from PATH, help users install it with uv tool install "git+https://github.com/unoplat/unoplat-code-confluence.git#subdirectory=unoplat-code-confluence-cli" when needed, ingest repositories, and run the single-command ucc agent-md <repository_git_url> flow.

📊 Project Status

  ALPHA ████████████████░░░░ BETA

For detailed roadmap, language support status, and planned features, see our Product Roadmap.

Maintainers

💬 Product Feedback & Alpha Disclaimer

Unoplat Code Confluence is in alpha. We’re building for our own daily use first, prioritizing stability and bug fixes. We’re collecting feedback now and will act on it once the core is solid. Early adopters welcome. Expect rapid changes and rough edges.

• Discord: Join our community channel
• GitHub Issues: Create an issue for bug reports or feature requests
• GitHub Discussions: Start a discussion for broader conversations

Your feedback is invaluable as we work toward production readiness and helps us prioritize our roadmap to better serve the developer community.

License

Unoplat-CodeConfluence is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0) + COMMONS CLAUSE.