portfolio/agentlab/rules/readme-maintenance.md

README Maintenance

These rules are written for Claude Code but the concepts apply to any AI agent system.

The Pattern: Human README + Agent Entrypoint

Every repo in this system follows a hybrid pattern:

• README.md — human-facing landing page (GitHub/Forgejo renders this first)
• LLM-ENTRYPOINT.md (or equivalent) — agent-facing startup chain

These are not duplicates. They serve different audiences and must both exist. Never collapse them into one file. Never let README.md become agent instructions.

README.md Must Contain

1. What this repo is — one paragraph, plain English
2. Current state table — key services/components and their live status
3. Key documents table — links to the most important docs an operator needs
4. Repo structure — top-level directory layout with one-line descriptions
5. Branch model — who owns which branch and its purpose
6. Agent entry point note — a single line at the bottom: *Agent entry point: LLM-ENTRYPOINT.md*

When to Update README.md

Update README.md when state changes, not when work happens:

Trigger	README update required
A service goes live or is decommissioned	Yes — update current state table
A new key document is created	Yes — add to key documents table
Repo top-level structure changes	Yes — update structure section
Existing state entry becomes stale	Yes — update it
Routine commit (config fix, doc edit)	No
Bug fix or minor feature work	No

Rule: If the commit message would reasonably include the word "add", "remove", or "complete" for a system component or major document, check whether the README current state table needs updating.

When Creating a New Repo

Before the first meaningful commit, write a README.md with all five sections above. A stub README is not acceptable as a permanent state.

What README.md Must NOT Contain

• Agent startup chains or read-order instructions (those go in LLM-ENTRYPOINT.md)
• Secrets, tokens, or credential paths
• Internal agent coordination details
• Architecture deep-dives (link to the relevant doc instead)