Agent Ready Repository

Agent-Ready Repository

Treat repeated agent failures as repository feedback. Fix missing context and deterministic enforcement before adding more generic instructions.

Principles

1. Evidence before policy: Add guidance for observed mistakes, real boundaries, and repository-specific commands.
2. Progressive context: Keep root guidance short; place local rules near the subsystem they govern.
3. Executable truth: Prefer scripts, schemas, linters, and structural tests over prose that can drift.
4. Teaching failures: Validation errors should identify the violation, consequence, and correct path.
5. Small maintenance loops: Remove stale guidance and dead automation before they become trusted misinformation.

Workflow

1. Collect Failure Evidence

Gather concrete examples:

• wrong command or package manager
• missed setup or validation step
• import or module-boundary violation
• stale documentation followed as truth
• generated files edited directly
• destructive operation attempted without approval
• repeated changes that pass tests but violate architecture

Do not add rules for hypothetical problems that the repository already makes obvious.

Use the reported failure to select the relevant checks below. A focused repair does not require a full repository audit.

2. Audit Context Discovery

Check:

• root AGENTS.md scope and size
• nested AGENTS.md files where commands or boundaries differ
• README and docs accuracy
• discoverability of setup, test, lint, build, and deploy commands
• ownership of generated files and migrations
• links from guidance to canonical implementation or validation

Use agents-md-hierarchy when the repository specifically needs nested guidance.

3. Choose the Smallest Durable Fix

A rule without a realistic enforcement or verification path is weak. Keep it only when deterministic enforcement is impractical.

4. Improve Feedback

A useful failure message states:

• what failed
• exact file or resource
• why the repository forbids it
• the supported alternative
• the command or document that explains the fix

Run checks locally through one obvious entry point when possible, such as bin/check or make verify.

5. Add Structural Protection

Use repository-native tools to enforce only important boundaries:

• forbidden imports or dependency direction
• API or schema compatibility
• generated-file ownership
• documentation links and examples
• migration safety
• artifact size or performance budgets

Avoid arbitrary universal thresholds. Derive gates from product risk and existing repository expectations.

6. Remove Entropy

Periodically check for:

• rules that no longer match the code
• duplicate or contradictory guidance
• unused dependencies and dead scripts
• docs with no implementation owner
• generated artifacts committed in source paths
• warnings that everyone ignores
• mandatory broad reading, repeated checks, or fixed test sequences without a concrete need

Keep completion criteria: implement the requested behavior, exercise it where practical, fix failures caused by the change, and continue to the agreed endpoint or a concrete blocker. Allow safe local verification with disposable data within the task's authorization. Retain approval boundaries for destructive actions, shared resources, external writes, and deployment.

Automated cleanup may propose changes, but destructive cleanup still requires normal review and validation.

Load patterns.md when creating a guidance template or structural check.

Completion Report

Report:

• failure evidence reviewed
• context or discoverability gaps found
• guidance changed and its scope
• deterministic checks added or updated
• stale rules removed
• commands used to verify the repository harness
• remaining failures that cannot yet be enforced