meta-project
AGENTS.md0 starsChanged yesterdayMITView on GitHub
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository19 other files it gives its agents.
- templates/AGENTS.mdAGENTS.md
- decommission-meta-projectSkill
- ground-meta-projectSkill
- init-meta-projectSkill
- manage-meta-projectSkill
- record-observationSkill
- scan-meta-projectSkill
- sync-architectureSkill
- tune-meta-projectSkill
- update-meta-projectSkill
- decommission-meta-projectSkill
- ground-meta-projectSkill
- init-meta-projectSkill
- manage-meta-projectSkill
- record-observationSkill
- scan-meta-projectSkill
- sync-architectureSkill
- tune-meta-projectSkill
- update-meta-projectSkill
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
- Very specific: line 9
Structural Canonicity and Validation: All skills and templates must strictly conform to the format specification (YAML frontmatter, "When …
- Distinctive: line 10
Opportunistic Refresh (Read + Opportunistic Refresh): When consulting any meta-knowledge slice, the agent closes identified gaps and …
- Distinctive: line 24
Before taking any action, the agent MUST consult the corresponding knowledge slices.
- Distinctive: line 25
Opportunistic Knowledge Refresh: when reading any slice, evaluate data completeness — fill in missing details, fix outdated information, …
- Very specific: line 72
If global agent skills (such as python-pro or Meta-Project skills) are unavailable in the host harness, the agent operates in Base Fallback …
- Distinctive: line 89
When tasked with code exploration, repository assessment, or architecture review without explicit instruction to implement changes:
- Very specific: line 90
Do NOT generate temporary files, .lock files, or intermediate scratchpads.
- Very specific: line 91
Do NOT add telemetry rows to role profiles or tasks to tasks.md.
- Very specific: line 92
Use python scripts/inspect_meta_project.py --read-only --json for safe discovery.
- Distinctive: line 95
Verify against Section 1: ensure the planned solution does not contradict project principles and invariants.
- Very specific: line 99
When encountering hidden environment quirks, record the fact via record-observation (or scripts/record_obs.py).
≈ “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.
Files
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.mdis 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)
- No Context Bloat: The root
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 intoobservations.md.sync-architecture— updating the component map and data flows inarchitecture.md.
Skill Responsibility Boundaries (invariant):
| Skill | Owns | Must NOT do |
| init | survey, scenario agreement, scaffold prep | deploy teams |
| manage | roles & bindings configuration | re-agree the scenario |
| update | framework components & migrations | revise team composition or North Stars |
| ground | recover understanding of goal/state/authority | change configuration to silence a discrepancy |
| tune | propose config improvements with evidence | apply 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,
.lockfiles, 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 --jsonfor safe discovery.
6. Base Working Protocol
- Verify against Section 1: ensure the planned solution does not contradict project principles and invariants.
- Consult the target slice from Section 3; update the slice immediately upon discovering gaps or inaccuracies.
- Apply stack skills from Section 4 (or local stdlib tools from Section 5 in Base Fallback Mode) to inspect code and run tests.
- Changes must be minimally sufficient; refactoring of unrelated areas is prohibited; changes must be minimal in diff width, but maximal in root-cause depth.
- When encountering hidden environment quirks, record the fact via
record-observation(orscripts/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.jsonand verifies integrity viascripts/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 -->
[](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 -->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
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.

