ragappv3

Apply when implementing features, fixing bugs, debugging errors, investigating failures, tracing root causes, reviewing tech debt, tracing issues, planning fixes, or completing any task. Enforces parallel sub-agent implementation, independent adversarial review, and a 95% confidence gate before stopping.

RAGAPPv3 testing policy and conventions. Load before writing or modifying any test, fixing a test/CI failure, or adding coverage. Covers backend pytest + unittest (SimpleConnectionPool dependency-override harness, FK cascades, the Python 3.11-vs-local event-loop trap) and frontend Vitest + React Testing Library + jsdom (MemoryRouter, Radix Select, react-virtual mock patterns). This repo's frontend uses Vitest, NOT bun:test.

Keep dependency and lockfile changes aligned with CI expectations.

Verify all required QA gate artifacts and completion criteria before marking a task or phase complete.

Keep mocks, async setup, and test assertions clean and aligned with the code under test.

Lightweight PR-time audit for whether changes are compatible with the actual RAGAPPv3 GitHub Actions workflow, dependency lockfiles, scripts, and cross-platform local validation.

Evidence-first code review for correctness bugs, AI-generated code smells, unsupported claims, unwired functionality, dependency hallucinations, and release-to-code mismatches.

Verify that README changes, release notes, changelog bullets, migration notes, PR descriptions, examples, and docstrings match what the code actually ships.

End-to-end regression tests for async generator copy logic

RAGAPPv3 testing policy and conventions. Load before writing or modifying any test, fixing a test/CI failure, or adding coverage. Covers backend pytest + unittest (SimpleConnectionPool dependency-override harness, FK cascades, the Python 3.11-vs-local event-loop trap) and frontend Vitest + React Testing Library + jsdom (MemoryRouter, Radix Select, react-virtual mock patterns). This repo's frontend uses Vitest, NOT bun:test.

Apply when committing, pushing, opening or updating a PR, writing a pull request, creating release notes, or closing out remote CI. Enforces the opencode-swarm invariant audit, release-note fragment workflow, full validation suite, issue comment requirement, and post-PR lifecycle rules.

Full execution protocol for MODE: LOOP — the compound-engineering loop: brainstorm → plan → build → review → improve, iterating under defense-in-depth stop conditions with generator/critic separation, durable resumable state, and mandatory compounding learning capture. Loaded on demand by the architect when the loop command emits a [MODE: LOOP ...] signal.

Monitor a pull request after creation and act autonomously on pushed PR activity. Use when subscribing to a PR after opening it, when asked to watch, babysit, or autofix a PR until merge, or when a <pr-activity> wake message or [pr-monitor:...] advisory arrives for a subscribed PR. Owns event triage (fix / ask / skip), bounded-retry escalation, and terminal-state cleanup.

Document the discipline of propagating timestamp fields through token invalidation flows. Use when implementing access-token refresh reuse, password change epoch, or any token revocation flow that must invalidate outstanding tokens.

Document two anti-patterns in the auth override branch: (a) masking non-401 HTTPExceptions when falling back to an alternative auth mechanism, and (b) using inspect.isawaitable() instead of inspect.iscoroutine() on the evaluate closure, which yields None for async def overrides. Critical for auth dependencies with JWT + service-account (SA) fallback (get_chat_stream_auth_context, get_wiki_events_auth_context, and any override branch calling get_evaluate_policy).

Document the discipline of isolating module-level mutable state in tests. Use when adding tests that touch global registries, singletons, or class attributes. Prevents test pollution that surfaces only in combined pytest sessions.

Document pytest pollution patterns observed in this repo where tests pass in isolation but fail in combined sessions due to shared global state. Recommend autouse fixture scoping or explicit teardown patterns to make tests reliable in any combination.

Apply when implementing features, fixing bugs, debugging errors, investigating failures, tracing root causes, reviewing tech debt, tracing issues, planning fixes, or completing any task. Enforces parallel sub-agent implementation, independent adversarial review, and a 95% confidence gate before stopping.

Execute complex implementation work with a swarm-like Codex workflow: parallel exploration, scoped planning, selective deep validation, and independent reviewer/critic checks where risk justifies them. Use for feature work, bug fixes, refactors, and multi-file changes.

Run a graph-guided, tool-augmented Swarm PR review using context packing, parallel exploration, triggered plugin micro-lanes, independent reviewer validation, critic challenge, and metrics writeback. Use for deep pull request review with low false-positive tolerance and high recall.

Execute complex implementation work with a swarm-like Claude Code workflow: parallel exploration, scoped planning, selective deep validation, and independent reviewer/critic checks where risk justifies them. Use for feature work, bug fixes, refactors, and multi-file changes.

Monitor and fix CI on an open RAGAPPv3 pull request until every required check is green. Load when asked to watch CI, diagnose red checks, or drive a PR to passing. Maps the three real CI jobs (Frontend, Backend, Quality contracts), enforces diagnose-before-fix, and covers re-push / rebase. This repo has NO dist-check, biome, bun, or per-OS matrix — ignore that guidance. Updated for PR #215 (issue #209): Backend now runs the full `pytest tests/` suite (3918 tests, ~18m on CI Linux) — NOT the old 3-file subset. Job timeout is 60m. pytest-timeout=300 caps per-test hangs.

Monitor and fix CI on an open RAGAPPv3 pull request until every required check is green. Load when asked to watch CI, diagnose red checks, or drive a PR to passing. Maps the three real CI jobs (Frontend, Backend, Quality contracts), enforces diagnose-before-fix, and covers re-push / rebase. This repo has NO dist-check, biome, bun, or per-OS matrix — ignore that guidance. Updated for PR #215 (issue #209): Backend now runs the full `pytest tests/` suite (3918 tests, ~18m on CI Linux) — NOT the old 3-file subset. Job timeout is 60m. pytest-timeout=300 caps per-test hangs.

Run a rigorous, quote-grounded codebase review or security/QA/accessibility/performance/AI-slop/enhancement audit. Adapter pointing to the canonical opencode-swarm skill; refer to that for the full protocol.

Run a rigorous, quote-grounded codebase review or security/QA/accessibility/performance/AI-slop/enhancement audit. Adapter pointing to the canonical opencode-swarm skill; refer to that for the full protocol.

Run a rigorous, quote-grounded codebase review or security/QA/accessibility/performance/AI-slop/enhancement audit. Use for full-repo or large-subsystem review reports; not for normal implementation. Performs Phase 0 inventory, selected exhaustive tracks with non-diluting depth, coverage closure, reviewer/critic validation, and writes .swarm/review-v8 artifacts without modifying source files.

RAGAPPv3 engineering conventions — backend (FastAPI + SQLite + LanceDB), frontend (React + TypeScript + Vite + Vitest), database/migration/RBAC patterns, and the multi-agent skill layout. Load before implementing or refactoring backend routes/services/migrations or frontend pages/components, or when you need to know "how does this repo do X".

Full execution protocol for MODE: DEEP_DIVE — read-only codebase audit with parallel explorer waves, 2 independent reviewers, and sequential critic challenge for HIGH/CRITICAL findings. Loaded on demand by the architect when the deep-dive command emits a [MODE: DEEP_DIVE ...] signal.

RAGAPPv3 engineering conventions — backend (FastAPI + SQLite + LanceDB), frontend (React + TypeScript + Vite + Vitest), database/migration/RBAC patterns, and the multi-agent skill layout. Load before implementing or refactoring backend routes/services/migrations or frontend pages/components, or when you need to know "how does this repo do X".

Connection pool topology, double-connection pattern detection, semaphore/lock inventory, and exhaustion headroom calculation for RAGAPPv3. Load before reviewing scalability, connection pool sizing, or concurrent user throughput.

End-to-end contribution workflow for RAGAPPv3 (KnowledgeVault). Load before creating branches, commits, or PRs. Covers branch hygiene against master, conventional commits, the three real CI gates (Frontend, Backend, Quality contracts), and where to go for publication. This repo is Python/FastAPI + npm/Vite — there is NO release-please, biome, bun, or dist-check.

RAGAPPv3 test EXECUTION patterns. Load when you need to run, scope, or diagnose tests — backend pytest and frontend Vitest — not when authoring them (see writing-tests for that). Covers per-file/-test targeting, CI-equivalent local runs, reading CI failure logs, output truncation recovery, and the Python 3.11 event-loop trap. This repo's frontend uses Vitest, NOT bun:test.

Safe Python subprocess patterns for RAGAPPv3. Load before adding, modifying, or reviewing any code that calls subprocess.run / subprocess.Popen / asyncio.create_subprocess_exec. Covers list-form args (no shell=True with untrusted input), timeout, cwd, bounded stdout/stderr capture, returncode checks, cleanup, and the async variant. This repo's backend is Python only — ignore any Bun / Node child_process / Windows .cmd guidance.

Full execution protocol for MODE: BRAINSTORM -- structured discovery dialogue, approach selection, spec drafting, QA gate selection, and transition handling.

Full execution protocol for MODE: COUNCIL -- General Council research, parallel member dispatch, disagreement handling, and synthesis.

Full execution protocol for MODE: EXECUTE -- task execution, coder retry handling, QA gates, completion evidence, and per-task closure.

Full execution protocol for MODE: PHASE-WRAP -- phase boundary evidence, drift and hallucination gates, retrospectives, phase completion, and final council.

Full execution protocol for MODE: PLAN -- plan creation, external plan ingestion, QA gate persistence, task granularity, and traceability checks.

Full execution protocol for MODE: PRE-PHASE BRIEFING -- phase-start context assembly, evidence review, and task readiness checks.

Full execution protocol for MODE: SPECIFY -- spec creation, codebase reality checks, SME input, QA gate persistence, and optional council spec review.