Agent & LLM Guidelines
Relevant source files
The following files were used as context for generating this wiki page:
PRKS implements a scoped instruction system for AI agents and contributors to manage a complex architecture transition. The project moves from a legacy JavaScript and SQLite foundation toward a modular PostgreSQL backend and a Vue 3 + TypeScript frontend. These guidelines ensure that modifications respect current correctness contracts, such as local-first sync, while aligning with long-term roadmap targets.
Sources: AGENTS.md:3-8, backend/AGENTS.md:7-13
Scoped Instruction Architecture
The project distributes rules across multiple AGENTS.md files located near the code they govern. This prevents agents from loading unrelated context for specific tasks.
Instruction Precedence and Routing
Nested AGENTS.md files refine root rules. If a conflict occurs, directory-specific nested instructions take precedence over repository-root instructions. However, nested files must not override load-bearing root invariants like storage safety or privacy policies.
Sources: AGENTS.md:30-36
Core Instruction Map
| File Path | Scope and Governance |
|---|---|
AGENTS.md (root) | Global invariants, PR merge coordination, target architecture, and general commands. |
backend/AGENTS.md | Persistence, SQLite/PostgreSQL transition, privacy logging, and backup/restore rules. |
frontend/AGENTS.md | UI behavior, navigation, Saved Views, and offline/PWA/sync contracts. |
frontend-app/AGENTS.md | Vue 3 + TypeScript source, component ownership, and migration boundaries. |
tests/AGENTS.md | Test-only routing to production-domain instructions. |
DESIGN.md | Authoritative UI/interaction design contract. |
Sources: AGENTS.md:14-28, frontend-app/AGENTS.md:12-20
Implementation vs. Target Architecture
Agents must distinguish between current implementation details and accepted target architecture defined in roadmaps #310 and #311.
Current Constraints
- Storage: SQLite and local-file trees are the current relational and binary stores.
- Networking: Standard library HTTP adapters and durable browser-side sync.
- Frontend: Vue 3 is replacing legacy JavaScript via a bridge.
Sources: AGENTS.md:43-52, backend/AGENTS.md:7-13
Roadmap Targets (#310/#311)
- Database: PostgreSQL is the long-term canonical relational store.
- Architecture: Modular-monolith with explicit User/Library boundaries.
- Storage: Abstraction layer with user-configurable local data roots.
- API: Stateless-capable processes and durable jobs.
Sources: AGENTS.md:43-52, frontend-app/AGENTS.md:44-48
Workflow and Commands
The following diagram represents the standard task lifecycle for an agent working on the PRKS repository.
The diagram shows the iterative implementation loop focusing on unit and narrow E2E tests before PR creation.
Sources: CLAUDE.md:16-24, AGENTS.md:113-118
Critical Safety Rules
- Storage Safety: Never use production
data/or a livePRKS_STORAGE. Testing mode (--testing) must targetdata_testing/. - Environment: Validate the Python environment (3.12+ and
requirements.txtpins) before server startup. - Privacy: Logs must be metadata-only. Never log research content, request bodies, or absolute paths.
Sources: CLAUDE.md:11-13, backend/AGENTS.md:35-40
Testing Policy
PRKS enforces a strict hierarchy for test execution to ensure performance and reliability.
- Unit/API Tests: Prefer these for logic and contract validation. Run via
python run_tests.py. - Node Selftests: Use for frontend logic without a browser.
- Scoped E2E: Use
scripts/e2e agentfor narrow feature validation. - Full E2E Gate: Reserved for final validation before PR completion. Never run while iterating.
Sources: CLAUDE.md:16-20, AGENTS.md:82-93
Frontend Migration Boundaries
The migration of the frontend to Vue 3 follows a specific "bridge" pattern. Agents must not duplicate canonical models during this transition.
The diagram illustrates the relationship between the new Vue source and the legacy runtime components it depends on.
Sources: frontend-app/AGENTS.md:5-10, frontend-app/AGENTS.md:23-28
Cross-Domain Coordination
When work crosses the legacy/runtime bridge, agents must load both frontend-app/AGENTS.md and frontend/AGENTS.md. This is common for:
- Offline/Sync contracts.
- Workspace ownership and tab lifecycle.
- Durable operation families.
Sources: tests/AGENTS.md:11-15, frontend-app/AGENTS.md:35-40
Pull Request and Merging
PRKS requires explicit maintainer coordination for all merges.
- Approval: Every merge into
masterrequires maintainer approval. - Auto-merge: Agents must NOT enable auto-merge, Mergify queues, or comment
@mergifyio queue. - Prerequisites: Use
Depends-On: #<PR>in the description for PR-to-PR dependencies. - Issue Linking: Link tracking issues rather than duplicating history.
Sources: AGENTS.md:55-68, AGENTS.md:120-130
Summary
Agent guidelines in PRKS serve as a runtime contract for both code and behavior. By following scoped instructions, respecting the target architecture roadmaps, and adhering to strict privacy and testing policies, agents maintain the integrity of the research-library application during its architecture transition. Significant changes should always be validated through narrow unit or API tests before moving to browser-based E2E suites.