agentleFS
vlv-codevlv-code/meta-project/templates/AGENTS.md

meta-project / templates

AGENTS.md0 starsChanged yesterdayMITView on GitHub

The file

We split this AGENTS.md into the rules it gives an agent

11 rules. About 0 are common, 5 are distinctive, and 6 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈5

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 6

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Adversarial Testing Invariant: When applying TDD, write negative/adversarial tests (boundary conditions, malformed input, failure modes) …

    line 14
  2. Distinctive:

    Before taking any action, the agent MUST consult the corresponding knowledge slices.

    line 24
  3. Distinctive:

    Opportunistic Knowledge Refresh: when reading any slice, evaluate data completeness — fill in missing details, fix outdated information, …

    line 25
  4. Very specific:

    If global agent skills (such as python-pro or Meta-Project skills) are unavailable in the host harness, the agent operates in Base Fallback …

    line 69
  5. Distinctive:

    When tasked with code exploration, repository assessment, or architecture review without explicit instruction to implement changes:

    line 86
  6. Very specific:

    Do NOT generate temporary files, .lock files, or intermediate scratchpads.

    line 87
  7. Very specific:

    Do NOT add telemetry rows to role profiles or tasks to tasks.md.

    line 88
  8. Very specific:

    Use python scripts/inspect_meta_project.py --read-only --json for safe discovery.

    line 89
  9. Distinctive:

    Verify against Section 1: ensure the planned solution does not contradict project principles and invariants.

    line 92
  10. Very specific:

    When encountering hidden environment quirks, record the fact via record-observation (or scripts/record_obs.py).

    line 96
  11. Very specific:

    Identity Determination Protocol: Every agent operating in the repository must resolve its qualified actor_id …

    line 100

≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

Project Passport: {{PROJECT_NAME}}

1. Concept, Principles, and North Stars

  • Service Purpose: {{PROJECT_DESCRIPTION}}
  • Technology Stack: {{PROJECT_STACK}}
  • Key Invariant: {{CRITICAL_INVARIANT}} (e.g.: API backward compatibility, data immutability, preserving DB schema).
  • Principles and Architectural Orientations (North Stars):
    • {{PRINCIPLE_1}} (e.g.: dependency minimalism, avoiding unnecessary abstractions).
    • {{PRINCIPLE_2}} (e.g.: strict typing and validation at system boundaries).
    • {{PRINCIPLE_3}} (e.g.: explicit error handling without swallowing exceptions).
    • Circuit Breaker & Flow Tracing: repeatedly failing edits targeting one defect, or new regressions appearing in adjacent code while fixing it, are a semantic signal to STOP editing and trace the full data path (origin ➔ transport ➔ persistence ➔ consumer) before the next diff. A normal iterative TDD loop is NOT a violation.
    • Default Deny Boundaries: Any directory not explicitly mapped in boundaries is strictly Red Zone.
    • Default Closed Tooling: Core framework and agents operate in a zero-dependency closed loop by default. External tools and third-party dependencies are permitted ONLY when explicitly declared (opt-in) in project specification or requested by user. Liability for external tool failures rests on the project/operator.
    • Adversarial Testing Invariant: When applying TDD, write negative/adversarial tests (boundary conditions, malformed input, failure modes) and confirm RED before writing implementation code to transition to GREEN. (Any decisions contradicting these principles are prohibited)

2. Repository Meta-Map

  • Core Code: {{SRC_PATH}}
  • Entry Points: {{ENTRY_POINTS}}
  • Configuration: {{CONFIG_PATHS}}
  • Tests: {{TEST_PATHS}}

3. Directive Meta-Knowledge Protocol

Before taking any action, the agent MUST consult the corresponding knowledge slices. Opportunistic Knowledge Refresh: when reading any slice, evaluate data completeness — fill in missing details, fix outdated information, and eliminate blind spots without destructive overwriting:

  • Responsibilities and Boundaries (.agents/project_knowledge/boundaries.md):
    • When to consult: before modifying data schemas, module boundaries, dependencies, security, or configs.
    • What to update: supplement and refine glob path patterns to match the real repository structure.
  • Weak Spots and Risks (.agents/project_knowledge/weak_spots.md):
    • When to consult: before modifying fragile services, external APIs, queues, or complex legacy code.
    • What to update: record newly identified risks, hidden couplings, and remove resolved issues.
  • Architectural Foundations (.agents/project_knowledge/architecture.md):
    • When to consult: before adding new components, changing data flows, or modifying interaction contracts.
    • What to update: eliminate blind spots in the subsystem map, describe actual connections and data flows (directly or via the sync-architecture skill).
  • Observation Base (.agents/project_knowledge/observations.md):
    • When to consult: upon build failures, runtime errors, or unexpected environment behavior.
    • What to update: immediately and atomically record solved non-trivial bugs using the record-observation skill.
  • Active Tasks (.agents/project_knowledge/tasks.md):
    • When to consult: at the beginning of any session and upon completing subtasks.
    • What to update: track execution progress, register new tasks and delegated steps with author and timestamp [<actor_id> @ ISO_DATETIME].

4. Procedural Skills Registry

Built-in meta-project skills:

  • init-meta-project — repository scaffolding and non-destructive initialization.
  • manage-meta-project — scale-adaptive agent team orchestration and materialization.
  • decommission-meta-project — non-destructive decommissioning, resizing, and archiving of agent roles.
  • ground-meta-project — context recovery and drift diagnosis: restores goal, state, identity, and authority after session changes, moves, updates, or compaction; diagnoses context drift without automatic rollback.
  • scan-meta-project — integrity inspection, boundary coverage audit, and backfilling meta-knowledge without re-init.
  • tune-meta-project — git friction diagnostics, role topology tuning, and non-bloating North Star crystallization.
  • update-meta-project — non-destructive upstream updating from GitHub or local cache with local_repo_data preservation.
  • record-observation — atomic logging of findings and quirks into observations.md.
  • sync-architecture — updating the component map and data flows in architecture.md.

Skill Responsibility Boundaries (invariant):

SkillOwnsMust NOT do
initsurvey, scenario agreement, scaffold prepdeploy teams
manageroles & bindings configurationre-agree the scenario
updateframework components & migrationsrevise team composition or North Stars
groundrecover understanding of goal/state/authoritychange configuration to silence a discrepancy
tunepropose config improvements with evidenceapply them directly (routes via manage/update/decommission)

Connected stack skills from environment:

{{STACK_SKILLS}} (Managing build, linting, testing, and framework specifics is delegated to these skills)

5. Local Verification Tooling & Autonomous Fallback

If global agent skills (such as python-pro or Meta-Project skills) are unavailable in the host harness, the agent operates in Base Fallback Mode using zero-dependency Python 3.10+ stdlib utilities:

  • Repository Inspection & Capability Audit: python scripts/inspect_meta_project.py --json
  • Role Identity & Binding Verification: python scripts/verify_identity.py --check
  • Boundary Gate & Responsibility Audit: python scripts/check_boundaries.py --boundaries .agents/project_knowledge/boundaries.md --audit-tree
  • Working Tree Diff Verification: python scripts/check_boundaries.py --boundaries .agents/project_knowledge/boundaries.md --diff HEAD --allow-red-zone
  • Memory Compaction Check: python scripts/compact_memory.py --dry-run
  • Atomic Observation Logging: python scripts/record_obs.py --category <cat> --path <path> --issue <text> --solution <text>
  • Initialization & Management Report Audit: python scripts/manage_reports.py [init|manage|latest|verify]

Read-Only Exploration Mode

When tasked with code exploration, repository assessment, or architecture review without explicit instruction to implement changes:

  • Do NOT generate temporary files, .lock files, or intermediate scratchpads.
  • Do NOT add telemetry rows to role profiles or tasks to tasks.md.
  • Use python scripts/inspect_meta_project.py --read-only --json for safe discovery.

6. Base Working Protocol

  1. Verify against Section 1: ensure the planned solution does not contradict project principles and invariants.
  2. Consult the target slice from Section 3; update the slice immediately upon discovering gaps or inaccuracies.
  3. Apply stack skills from Section 4 (or local stdlib tools from Section 5 in Base Fallback Mode) to inspect code and run tests.
  4. Changes must be minimally sufficient; refactoring of unrelated areas is prohibited; changes must be minimal in diff width, but maximal in root-cause depth.
  5. When encountering hidden environment quirks, record the fact via record-observation (or scripts/record_obs.py).

7. Project Agent Team & Multi-Harness Identity

Project roles and multi-harness bindings are authoritative in .agents/meta-project.json.

  • Identity Determination Protocol: Every agent operating in the repository must resolve its qualified actor_id (<project_id>::<harness_id>::<installation_id>::<role_id>) from .agents/meta-project.json using scripts/verify_identity.py.
  • Invariance of Identity: Reading another role's passport (profile.md) or private workspace (notes.md) does NOT alter the active actor's identity. If identity cannot be verified, the agent must fail closed and report an unresolved identity.
  • Active Team Roster: {{TEAM_ROSTER}}

8. Dual-Entry & Canonical Repository Badge

For shared discovery across human operators and external agent harnesses, README.md incorporates the canonical block:

<!-- META-PROJECT:ENTRY:BEGIN -->
[![Built with Meta-Project](https://img.shields.io/badge/Built%20with-Meta--Project-blueviolet)](https://github.com/vlv-code/meta-project)

Agent instructions: [AGENTS.md](AGENTS.md) | Policy: [.agents/project_knowledge/boundaries.md](.agents/project_knowledge/boundaries.md)
*To inspect, configure, or adapt your environment, run `python scripts/inspect_meta_project.py` or invoke the `init-meta-project` skill.*
<!-- META-PROJECT:ENTRY:END -->

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.