d5ef629a54
Architecture, overview, homelab build plan, agent handbook, ADRs, and agent operating rules. All sensitive operational details sanitized (real IPs, hostnames, client names replaced with generic placeholders). Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
47 lines
2.1 KiB
Markdown
47 lines
2.1 KiB
Markdown
# 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)
|