arch-dotfiles/.pi/agent/prompts/repo-init.md

description
Set up or optimize the current repository for agent-first development (AGENTS.md, docs structure, progressive disclosure)

Set up or optimize the current repository for agent-first development. Based on principles from OpenAI's harness engineering and HumanLayer's CLAUDE.md guide.

Additional user context and constraints: $ARGUMENTS

Before changing anything:

1. Inspect the repository state first.
2. Compare the repo against the checklist below.
3. Prefer minimal, high-leverage, versioned changes.
4. Preserve useful project-specific guidance instead of replacing it blindly.

When to Use

• Setting up a new repo for agent-driven development
• Optimizing an existing repo's AGENTS.md / CLAUDE.md
• Restructuring docs for agent legibility

Core Principles

1. AGENTS.md = Table of Contents, Not Encyclopedia

• Max ~100 lines. Short, stable entry point.
• Only universally applicable instructions (applies to EVERY task).
• Points to deeper sources of truth — doesn't contain them.
• Domain-specific rules go in sub-files (docs/, skills, or scoped AGENTS.md in subdirs).

2. Progressive Disclosure

• Agent starts with a small map and is taught where to look next.
• Use nested AGENTS.md files in subdirectories for scoped context.
• Skills for domain-specific workflows (loaded on demand, not always).
• Don't frontload — let the agent discover context as needed.

3. Repository = System of Record

• If it's not in the repo, it doesn't exist to the agent.
• Push decisions, architecture, plans, conventions INTO the repo as versioned artifacts.
• No tribal knowledge in Slack, Google Docs, or people's heads.
• Docs are code — they get reviewed, updated, and maintained.

4. Agent Legibility First

• Optimize for agent comprehension, not just human readability.
• Favor "boring" tech — composable, stable APIs, well-represented in training data.
• Make the app inspectable: logs, metrics, test output should be agent-parseable.
• Structured formats (JSON, markdown with clear headers) > prose walls.

5. Enforce, Don't Instruct

• Invariants via CI/linters > instructions in AGENTS.md.
• Type checks, tests, formatting rules catch mistakes mechanically.
• Agent can run verification itself (make check, npm test, etc.).
• Instructions the agent can't verify will eventually be ignored.

6. Less Instructions = Better Compliance

• LLMs reliably follow ~150-200 instructions max (frontier thinking models).
• Agent harnesses already consume ~50 instructions in system prompt.
• Every instruction in AGENTS.md competes for attention budget.
• When everything is "important," nothing is.

AGENTS.md Template

# AGENTS.md

## Project
<1-2 sentences: what this project is and does>

## Stack
<bullet list of key tech: language, framework, DB, infra>

## Structure
<brief map of key directories and what they contain>

## Development
<how to build, run, test — the essential commands>

## Docs
Detailed documentation lives in `docs/`:
- `docs/ARCHITECTURE.md` — system design, package layering, domain map
- `docs/CONVENTIONS.md` — code style, patterns, naming
- `docs/PLANS.md` — active execution plans and progress
- `docs/DECISIONS.md` — architecture decision records (ADRs)

## Verification
<how to verify changes: test commands, type checks, linters>

## Rules
<only universal, always-applicable rules — keep to <10 items>

docs/ Structure

docs/
├── ARCHITECTURE.md    # System design, domain map, package layering
├── CONVENTIONS.md     # Code style, patterns, naming conventions
├── DECISIONS.md       # Architecture Decision Records (ADRs)
├── PLANS.md           # Active plans, completed plans, tech debt
└── <domain>/          # Domain-specific deep docs as needed

AGENTS.md ↔ CLAUDE.md Symlink

Always ensure both files exist so the repo works with any agent harness (Claude Code, OpenCode, Codex, etc.).

Rules:

• AGENTS.md is the source of truth (canonical file).
• CLAUDE.md is a symlink to AGENTS.md.
• If only CLAUDE.md exists, rename it to AGENTS.md and create the symlink.
• If both exist as separate files, merge into AGENTS.md and replace CLAUDE.md with symlink.
• Add CLAUDE.md symlink to git (git tracks symlinks fine).

Commands:

# If AGENTS.md exists but no CLAUDE.md
ln -s AGENTS.md CLAUDE.md

# If only CLAUDE.md exists
mv CLAUDE.md AGENTS.md
ln -s AGENTS.md CLAUDE.md

# Verify
ls -la CLAUDE.md  # should show -> AGENTS.md

Checklist

When initializing or optimizing a repo:

• AGENTS.md exists and is <100 lines
• CLAUDE.md is symlinked to AGENTS.md (or vice versa)
• AGENTS.md contains: project summary, stack, structure map, dev commands, verification
• Domain-specific instructions are NOT in root AGENTS.md
• docs/ directory exists with at minimum ARCHITECTURE.md
• Verification commands are documented and runnable by agent
• CI/linters enforce key invariants (not just documented)
• No critical knowledge lives only outside the repo

Anti-Patterns

• ❌ Stuffing every possible command into AGENTS.md
• ❌ Adding "hotfix" instructions for one-off behavior issues
• ❌ Instructions that aren't verifiable or enforceable
• ❌ Monolithic instruction files that rot over time
• ❌ Architecture decisions living in chat/docs outside repo

Sources

• OpenAI: https://openai.com/index/harness-engineering/
• HumanLayer: https://www.humanlayer.dev/blog/writing-a-good-claude-md