Imported from 4nibhal/bodhi-rag (AGENTS.md). Install upstream with npx skills add 4nibhal/bodhi-rag. Copyright stays with the author.

Rules: bodhi-rag Root

Context & Responsibility

This file is the root governance contract for bodhi-rag. The product is a backend-first document processing and retrieval platform. Terminal UX, local developer runtimes, and AI workflow infrastructure are supporting concerns, not the product core.

Product Boundary

Product code lives under src/ and future product-facing docs/tests.
ai-workflow/, .opencode/, and .aiwf/ are developer operating model infrastructure and must not become runtime dependencies of the shipped product.

Architectural Direction

Prefer backend-first service boundaries over TUI-centric orchestration.
New business logic belongs in src/bodhi_rag/ using domain/application/ports/infrastructure separation.
Treat UI, CLI, API, workers, and TUI as adapters over application services.
Keep configuration explicit, typed, and environment-driven.
No import-time side effects for model loading, vector store creation, filesystem writes, or network initialization.

Operational Standards

Environment: Use uv as the canonical Python workflow for local development and CI.
Verification: Favor uv sync, targeted tests, packaging checks, and CI parity over ad hoc local-only flows.
Quality Gates: Refactors must add characterization coverage before changing legacy behavior materially.
Release Safety: Product packaging, CI, Dependabot, and observability are part of the architecture, not optional polish.
Separation of Concerns: Product work and AIWF/dev-infra work should stay logically separated unless the change explicitly couples both.

Capability Graph

@skill/rules-creator
@skill/skill-creator
@skill/opencode-agent-creator

Auto-invoke Skills

When performing these actions, ALWAYS invoke the corresponding skill FIRST:

Action	Skill
After creating/modifying a skill	`skill-sync`
After creating/modifying a skill	`skill-sync`
Before creating a commit	`git-excellence`
Before creating a commit or PR	`git-excellence`
Creating new OpenCode sub-agents	`opencode-agent-creator`
Creating new OpenCode sub-agents	`opencode-agent-creator`
Creating or scaffolding new skills	`skill-creator`
Creating or scaffolding new skills	`skill-creator`
Defining new rules or scaffolding AGENTS.md	`rules-creator`
Defining new rules or scaffolding AGENTS.md	`rules-creator`
During Pull Request creation	`git-excellence`
Modifying AGENTS.md structure or adding new rules	`rules-sync`
Modifying AGENTS.md structure or adding new rules	`rules-sync`
Regenerate AGENTS.md Auto-invoke tables (sync.sh)	`skill-sync`
Regenerate AGENTS.md Auto-invoke tables (sync.sh)	`skill-sync`
Running AIWF init or refining bootstrap intake behavior	`bootstrap`
Starting a new feature or change that requires design thinking	`brainstorm`
Starting a spec-driven development workflow	`spec-workflow`
Synchronize all systems (OpenCode runtime, AGENTS.md, skill/rule metadata)	`system-sync`
Troubleshoot why a skill is missing from AGENTS.md auto-invoke	`skill-sync`
Troubleshoot why a skill is missing from AGENTS.md auto-invoke	`skill-sync`
User describes intent to build something without a clear spec	`brainstorm`
When an agent needs to operate the AIWF CLI or machine API	`aiwf-cli-operator`
When detecting staged changes	`git-excellence`

Specialized Sub-agents (OpenCode Flows)

Source definitions live in opencode-flows/agent/ and synchronize into .opencode/agents/ for runtime use.

Domain / Trigger	Agent
Backend architecture, module boundaries, migration design	`backend-architect`
RAG retrieval, chunking, reranking, citations, evals	`rag-systems-engineer`
Python quality, packaging, testing, runtime safety	`python-quality-engineer`
GitHub workflows, Dependabot, PR/release operations	`github-ops-engineer`

Platform Native Sub-agents (OpenCode Flows)

Source definitions live in opencode-flows/agent/ and mirror to .opencode/agents/ (gitignored, runtime copy). The system-architect is a mode: primary orchestrator; the rest are mode: subagent.

Agent	Mode	Purpose
`devops-scripter`	subagent	Automation scripts, file bulk operations, log/text parsing.
`doc-retriever`	subagent	Verifying technical facts and consulting official documentation.
`git-specialist`	subagent	Local Git operations (status, diff, commit, branch).
`tooling-specialist`	subagent	Auditing and maintaining infrastructure, CI/CD, repo structure.
`system-architect`	primary	High-level orchestrator; subsumes plan/build roles.

Delegation & Boundaries

Nested Rules

Rule Scope	Location
`src/`	`src/AGENTS.md`
`src/bodhi_rag/`	`src/bodhi_rag/AGENTS.md`
`tests/`	`tests/AGENTS.md`
`opencode-flows/`	`opencode-flows/AGENTS.md`

bodhi-rag

About