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

meta-project

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. Very specific:

    Structural Canonicity and Validation: All skills and templates must strictly conform to the format specification (YAML frontmatter, "When …

    line 9
  2. Distinctive:

    Opportunistic Refresh (Read + Opportunistic Refresh): When consulting any meta-knowledge slice, the agent closes identified gaps and …

    line 10
  3. Distinctive:

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

    line 24
  4. Distinctive:

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

    line 25
  5. 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 72
  6. Distinctive:

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

    line 89
  7. Very specific:

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

    line 90
  8. Very specific:

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

    line 91
  9. Very specific:

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

    line 92
  10. Distinctive:

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

    line 95
  11. Very specific:

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

    line 99

≈ “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: Meta-Project

1. Concept, Principles, and North Stars

  • Service Purpose: Agentic environment and context organization framework for repositories: project passport (AGENTS.md), dynamic knowledge slices (.agents/project_knowledge/), and procedural skills (skills/).
  • Technology Stack: Python 3.10+ (stdlib unittest), Markdown, GitHub Actions CI.
  • Key Invariant: Zero-dependency policy — all templates, validation utilities, and integrity tests must run without external runtime dependencies, using only the Python standard library.
  • Principles and Architectural Orientations (North Stars):
    • No Context Bloat: The root AGENTS.md is concise, free of dynamic logs, and contains only fundamental guidelines, meta-map, and protocols.
    • Structural Canonicity and Validation: All skills and templates must strictly conform to the format specification (YAML frontmatter, "When to invoke skill" and "Execution steps" sections) and be verified by test_integrity.py.
    • Opportunistic Refresh (Read + Opportunistic Refresh): When consulting any meta-knowledge slice, the agent closes identified gaps and updates the repository picture without destructive overwriting of accumulated data.
    • 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. (Any decisions contradicting these principles are prohibited)

2. Repository Meta-Map

  • Core Code & Skills: skills/ (init-meta-project, manage-meta-project, decommission-meta-project, ground-meta-project, scan-meta-project, tune-meta-project, update-meta-project, record-observation, sync-architecture)
  • Canonical Templates: templates/ (templates/AGENTS.md, templates/project_knowledge/, templates/team/)
  • CI/CD & Ownership: .github/workflows/ci.yml, .github/CODEOWNERS
  • Integrity Tests: tests/test_integrity.py
  • Automation Scripts: scripts/check_boundaries.py, scripts/compact_memory.py, scripts/sync_templates.py, scripts/record_obs.py, scripts/verify_identity.py, scripts/inspect_meta_project.py, scripts/manage_reports.py, scripts/update_meta_project.py
  • Documentation and Decisions: docs/decisions_and_roadmap.md, README.md, CHANGELOG.md

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 skills structure, templates, CI/CD, or documentation.
    • 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 integrity tests, skills format, or template structures.
    • 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 skills, templates, or orchestration changes.
    • What to update: eliminate blind spots in the component map, describe actual connections and data flows (directly or via sync-architecture).
  • Observation Base (.agents/project_knowledge/observations.md):
    • When to consult: upon test validation errors, runtime issues, or suspicious environment behavior.
    • What to update: immediately and atomically record solved non-trivial bugs using record-observation.
  • 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:

  • python-pro — Python development and refactoring, adhering to Python 3.10+ standards.
  • github-actions-creator — audit and maintenance of GitHub Actions CI/CD workflows.
  • clean-code — adherence to clean code principles and minimal sufficient changes.
  • code-reviewer — verification of code and template quality prior to commit. (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 (.agents/team/)

Authoritative role bindings and installation identities are defined in .agents/meta-project.json.

  • Identity Determination Protocol: In runtime execution, every active agent determines its qualified actor_id (<project_id>::<harness_id>::<installation_id>::<role_id>) from .agents/meta-project.json and verifies integrity via scripts/verify_identity.py --check.
  • 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 validated against .agents/meta-project.json, the agent must fail closed and report an unresolved identity.
  • Lead Developer & Dispatcher — Task decomposition, user request intake analysis, rapid execution of core Python utilities, scripts, and feature implementation (invoked by: "plan task", "decompose request", "implement feature", "write script", "develop component", "fix logic")
  • Quality & Meta-Architecture Guardian — Ecosystem integrity oversight, canonical passport audit, test suite execution, knowledge base consistency, and dead code/broken links auditing (invoked by: "verify meta-project structure", "run tests", "audit passport", "audit knowledge base", "check links", "check dead code")
  • GitHub Steward & Release Captain — Git hygiene, conventional commits, GitHub Actions CI/CD workflows, release readiness, and Code-to-README truth parity (invoked by: "git hygiene", "audit ci", "prepare release", "check readme parity", "conventional commit") (Granular legacy roles archived in .agents/team/archive/)

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.