ReadMeABook/AGENTS.md

AGENTS.md - Project Standards & Workflow

Critical: This document defines AI-optimized documentation standards and development workflow.

---

1. Token-Efficient Documentation System

Why Token Efficiency Matters

Problem: Documentation consumes significant token budget, leaving limited context for implementation.

Solution: Documentation optimized for AI consumption, not human reading. Average 68-72% token reduction while preserving all technical details.

Documentation Structure

documentation/
├── TABLEOFCONTENTS.md          # Navigation index (read THIS FIRST)
├── README.md                    # Project overview
├── backend/
│   ├── database.md             # Schema, Prisma, migrations
│   └── services/
│       ├── auth.md             # Plex OAuth, JWT, RBAC
│       ├── config.md           # Settings, encryption
│       ├── jobs.md             # Bull queue, processors
│       └── scheduler.md        # Cron jobs, recurring tasks
├── integrations/
│   ├── plex.md                 # Library scanning, OAuth, matching
│   └── audible.md              # Web scraping, metadata
├── phase3/                     # Automation pipeline
│   ├── README.md               # Pipeline overview
│   ├── qbittorrent.md          # Download client
│   ├── prowlarr.md             # Indexer search
│   ├── ranking-algorithm.md    # Torrent selection
│   └── file-organization.md    # File management, seeding
├── frontend/
│   ├── components.md           # React components
│   ├── routing-auth.md         # Route protection
│   └── pages/
│       └── login.md            # Login page design
├── deployment/
│   └── docker.md               # Docker Compose, volumes
└── [feature-specific docs]

---

2. Using TABLEOFCONTENTS.md (MANDATORY)

RULE: Always Start Here

Before reading ANY documentation:

1. Read documentation/TABLEOFCONTENTS.md FIRST
2. Identify relevant sections for your task
3. Read ONLY the specific files you need
4. Never read all files sequentially (wastes tokens)

Example Workflow

Bad (Token wasteful):

Task: Fix Plex authentication
❌ Read README.md → backend/* → integrations/* → ...

Good (Token efficient):

Task: Fix Plex authentication
✅ Read TABLEOFCONTENTS.md → Identify: backend/services/auth.md, integrations/plex.md
✅ Read only those 2 files
✅ Begin implementation

TABLEOFCONTENTS.md Format

Maps questions/features to specific documentation files:

• "How does authentication work?" → backend/services/auth.md
• "How do downloads work?" → phase3/qbittorrent.md, backend/services/jobs.md
• Organized by: Authentication, Configuration, Database, Integrations, Automation, etc.

---

3. Token-Efficient Documentation Format

Mandatory Format Standards

All documentation MUST follow this token-optimized format:

Structure

# [Title]

**Status:** [✅ Implemented / ⏳ In Progress / ❌ Not Started] [Brief description]

## Overview
[1-2 sentence summary]

## Key Details
- Compact bullet lists (not prose)
- API endpoints with request/response
- Data models with field names/types
- Configuration keys
- Critical implementation notes

## API/Interfaces
[Tables or compact code blocks]

## Critical Issues (if any)
[Only important items]

## Related: [links to other docs]

Forbidden Content (Removed for Token Efficiency)

• ❌ Verbose prose explanations
• ❌ "Why?" sections (keep brief rationale only)
• ❌ Large ASCII diagrams (minimal only)
• ❌ Excessive examples (max 1-2)
• ❌ "Future Enhancements" sections
• ❌ "Testing Strategy" (unless critical)
• ❌ "Performance Considerations" (unless critical)
• ❌ Empty sections
• ❌ Decorative formatting

Required Content (Preserve Completely)

• ✅ API endpoint definitions
• ✅ Data model field names and types
• ✅ Configuration keys and values
• ✅ Status values and enums
• ✅ File paths and code locations
• ✅ Critical implementation details
• ✅ "Fixed Issues" (troubleshooting context)
• ✅ Essential code examples (1-2 max)

Format Examples

Before (Token wasteful - 180 lines):

# User Authentication Service

## Current State

**Status:** Implemented ✅

This service handles all authentication and authorization logic for the
ReadMeABook application, including Plex OAuth integration, JWT session
management, and role-based access control.

## Design Architecture

### Why Plex OAuth?

Plex OAuth was chosen for several important reasons:
- No need to manage passwords
- Users already have Plex accounts
- Seamless integration with Plex ecosystem
...
[continues for 150+ more lines]

After (Token efficient - 50 lines):

# User Authentication Service

**Status:** ✅ Implemented | Plex OAuth + JWT sessions + RBAC

## Overview
Handles Plex OAuth, JWT session management, role-based access control (user/admin).

## Key Details
- **Auth:** Plex OAuth flow → JWT tokens (access: 1h, refresh: 7d)
- **Roles:** user (requests only), admin (full access)
- **First user:** Auto-promoted to admin
- **Endpoints:**
  - POST /api/auth/plex/login → {authUrl, pinId}
  - GET /api/auth/plex/callback?pinId → {accessToken, refreshToken, user}
  - POST /api/auth/refresh → {accessToken}
  - GET /api/auth/me → {user}
- **Middleware:** requireAuth(), requireAdmin()
- **Storage:** HTTP-only cookies + localStorage

## JWT Payload
```json
{
  "sub": "user-uuid",
  "plexId": "plex-id",
  "role": "admin",
  "exp": 1234571490
}

---

4. Implementation Strategy

Step 1: Navigate with TABLEOFCONTENTS.md

• Read TABLEOFCONTENTS.md to find relevant docs
• Identify 1-3 specific files needed (not all docs)

Step 2: Read Minimal Context

• Read ONLY the identified files
• Focus on "Key Details" and "API/Interfaces" sections
• Skip examples unless implementing similar functionality

Step 3: Reiterate Understanding

• Brief paragraph (3-4 sentences max)
• What user wants, what's affected, expected outcome

Step 4: Create Implementation Plan (TodoWrite)

- [ ] Read: [specific doc files]
- [ ] Update: [specific doc files]
- [ ] Implement: [specific changes]
- [ ] Verify: [test steps]

Step 5: Implement

• Follow plan
• Update docs using token-efficient format
• Add file headers linking to docs

---

5. Documentation Maintenance

RULE: Update TABLEOFCONTENTS.md

When adding new documentation:

1. Create doc file using token-efficient format
2. Update TABLEOFCONTENTS.md with new mapping
3. Update parent README.md if needed

Example:

# Added new feature: Email notifications

Files created:
- documentation/backend/services/notifications.md

Updates required:
- ✅ Create notifications.md (token-efficient format)
- ✅ Add to TABLEOFCONTENTS.md: "Email notifications" → backend/services/notifications.md
- ✅ Update documentation/README.md → Backend section

RULE: Keep Docs Up-to-Date

• Before code changes: Read relevant docs
• After code changes: Update docs immediately
• Use token-efficient format for all updates

---

6. Code Standards

File Size Limits

• Max 300-400 lines per file
• Refactor if exceeding limit

Mandatory File Headers

/**
 * Component: User Authentication Service
 * Documentation: documentation/backend/services/auth.md
 */

Link Accuracy

• Header path MUST point to existing doc file
• Create doc BEFORE implementing code
• Use relative paths from project root

---

7. Token Budget Management

Critical Principle

Preserve tokens for implementation, not context gathering.

Token Budget Allocation:

• 20-30%: Reading relevant documentation (via TABLEOFCONTENTS.md)
• 70-80%: Implementation, problem-solving, code generation

Anti-Patterns (Token wasteful):

• ❌ Reading all documentation files
• ❌ Reading verbose examples when not needed
• ❌ Re-reading same docs multiple times
• ❌ Reading "Future Enhancements" sections

Best Practices (Token efficient):

• ✅ Use TABLEOFCONTENTS.md to target specific files
• ✅ Read only "Key Details" and "API/Interfaces" sections
• ✅ Skip examples unless implementing similar code
• ✅ Cache understanding in memory, don't re-read

---

8. Examples

Example 1: Bug Fix

Task: "Plex authentication fails with 403 error"

Process:

1. Read TABLEOFCONTENTS.md → Find: backend/services/auth.md, integrations/plex.md
2. Read only those 2 files (focus on API endpoints, error handling)
3. Identify issue: Token refresh logic
4. Fix code
5. Update backend/services/auth.md (token-efficient format)

Example 2: New Feature

Task: "Add email notifications for completed requests"

Process:

1. Read TABLEOFCONTENTS.md → Find: backend/services/scheduler.md, backend/services/jobs.md
2. Read those files for background job patterns
3. Create documentation/backend/services/notifications.md (token-efficient format)
4. Update TABLEOFCONTENTS.md: "Email notifications" → backend/services/notifications.md
5. Implement notification service
6. Add file header linking to notifications.md

---

9. Quality Checklist

Before completing any task:

• Used TABLEOFCONTENTS.md to find docs (not read all files)
• Read only necessary documentation
• Updated documentation in token-efficient format
• Updated TABLEOFCONTENTS.md if added new docs
• Added file headers to new code files
• No file exceeds 400 lines
• Documentation matches implementation

---

10. Summary

Key Points:

1. Always start with TABLEOFCONTENTS.md (navigation index)
2. Read only what you need (not all docs)
3. Use token-efficient format (bullets, tables, minimal prose)
4. Preserve tokens for implementation (not context gathering)
5. Update docs immediately (before/after code changes)
6. Update TABLEOFCONTENTS.md (when adding new docs)

Result:

• 68-72% token reduction in documentation
• Faster context gathering
• More tokens available for implementation
• Better AI performance on complex tasks

---

Remember: Documentation is for AI consumption. Token efficiency is critical. Always use TABLEOFCONTENTS.md.