AGENTS.md - Frontend Coding Guidelines

Engineering Workflow

bun install # ([bun.sh](https://bun.sh/docs/cli/install?utm_source=openai))
bun run build # ([bun.sh](https://bun.sh/docs/cli/run?utm_source=openai))
bun run dev # ([bun.sh](https://bun.sh/docs/cli/run?utm_source=openai))
bun run lint # ([bun.sh](https://bun.sh/docs/cli/run?utm_source=openai))

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

• Summary: This frontend models a Code Confluence platform that connects GitHub/GitLab repositories, collects metadata for ingestion jobs, and tracks workflow runs plus codebase status. It surfaces AI “agent” snapshot outputs (engineering workflows, dependency guides, business logic summaries, app interface scans) and stores user feedback tied to those runs. Supporting domains include credential/provider onboarding, model provider configuration (including OAuth), and tool configuration for integrations.
• Key domains:
  • Repository onboarding, provider credential handling, and multi-repository routing/metadata state.
  • Workflow run tracking, agent snapshot storage, and presentation of Agent MD artifacts.
  • Agent MD artifact formatting and markdown conversion for UI display.
  • Model provider configuration, OAuth-based connections, and tool configuration for analysis pipelines.
  • Feedback capture, rating/comment submission, and downstream issue reporting.
• Key data models & modules:
  • Agent feedback: src/features/agent-feedback/api.ts, src/features/agent-feedback/schema.ts, src/features/agent-feedback/store.ts, src/types/agent-feedback.ts.
  • Agent snapshots & events: src/features/repository-agent-snapshots/collection.ts, src/features/repository-agent-snapshots/hooks.ts, src/features/repository-agent-snapshots/schema.ts, src/features/repository-agent-snapshots/transformers.ts, src/types/agent-events.ts.
  • Agent MD artifacts: src/lib/agent-md-to-markdown.ts.
  • Model configuration & OAuth: src/features/model-config/provider-schema.ts, src/features/model-config/schema-generator.ts, src/features/model-config/types.ts, src/hooks/useCodexOauth.ts, src/hooks/useSaveModelConfig.ts.
  • Tool configuration: src/features/tool-config/types.ts, src/hooks/useSaveToolConfig.ts.
  • Repository/provider APIs & routing: src/lib/api.ts, src/lib/api/repositories-api.ts, src/lib/api/repository-provider-api.ts, src/lib/utils/provider-route-utils.ts, src/lib/utils/provider-utils.ts, src/types/repository-provider.ts, src/routeTree.gen.ts.
  • Credentials & auth state: src/lib/validation/credential-schemas.ts, src/types/credential-enums.ts, src/lib/github-token-utils.ts, src/lib/env.ts, src/stores/useAuthStore.ts.
  • UI state & shared types: src/hooks/use-data-table.ts, src/forms/types.ts, src/stores/useDevModeStore.ts, src/stores/useThemeStore.ts, src/types/data-table.ts, src/types/index.ts, src/types.ts.
• Reference: See business_logic_references.md for a detailed index of domain artifacts.

Commands

bun install                      # Install dependencies
vite                            # Dev server (http://localhost:5173)
vite build                      # TypeScript check + build
bun eslint .                    # Lint all files
bun eslint src/path/file.tsx    # Lint single file

Code Style (from .cursor/rules)

• TypeScript: Use interfaces over types, avoid enums (use maps), no any types, precise types always
• Functions: Use function keyword for pure functions, functional/declarative patterns over classes
• Naming: Descriptive with auxiliary verbs (isLoading, hasError), lowercase-with-dashes for directories
• Imports: Preserve existing formatting, use @/* absolute path alias, use axios for HTTP (never fetch)
• Formatting: Preserve existing code/comments unless necessary, curly braces for all conditionals
• Constraints: Do not remove code/comments unless necessary, just do what's asked (ask before doing more)

Architecture

• Stack: React 19 + TypeScript + Vite + TanStack Router + TanStack Query + shadcn/ui + TailwindCSS
• Routing: TanStack Router (file-based in src/routes/), __root.tsx redirects / to /onboarding
• State: Zustand (client state), TanStack Query (server state, 5min stale), URL state via useDataTableWithRouter
• UI: shadcn/ui components use CVA variants as props (variant="outline" NOT variant={{ outline: true }})
• API: Axios client in src/lib/api.ts, wrap all calls in TanStack Query hooks, dual error handling system
• Forms: Tanstack Form
• Tables: DiceUI + TanStack Table v8 with URL state sync via TanStack Router (NOT nuqs)

File Structure

src/components/ui/ shadcn base | src/components/custom/ business | src/pages/ pages | src/routes/ routes | src/lib/ api/utils/env

Operating Instructions

1. Use Context7 docs for dependency versions | Check existing code before changes | Structure: exported component → subcomponents → helpers → types
2. When in read mode always remember to raise access from user for any command that you want to execute.

Skill Loading

Before substantial work:

• Skill check: run npx @tanstack/intent@latest list, or use skills already listed in context.
• Skill guidance: if one local skill clearly matches the task, run npx @tanstack/intent@latest load <package>#<skill> and follow the returned SKILL.md.
• Monorepos: when working across packages, run the skill check from the workspace root and prefer the local skill for the package being changed.
• Multiple matches: prefer the most specific local skill for the package or concern you are changing; load additional skills only when the task spans multiple packages or concerns.

<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

• bun install — repository root; config: package.json and bun.lock

Build

• bun run build — repository root; config: package.json (tsc -b && vite build)

Dev

• bun run dev — repository root; config: package.json (vite)

Test

• Not detected

Lint

• bun run lint — repository root; config: package.json

Type Check

• bunx tsc -b — repository root; config: tsconfig.json and package.json (build script)

Dependency Guide

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

Business Domain

Description

This frontend is for a code analysis and repository operations platform centered on onboarding GitHub/GitLab repositories, ingesting them into workflow runs, and displaying AI agent snapshot outputs such as engineering workflows, dependency guides, business logic summaries, and app interface scans. It also covers model-provider and tool configuration, OAuth and credential handling, and feedback flows that turn app or agent feedback into GitHub issues.

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.