agentleFS
Sign inStart free
docxologydocxology/template/infrastructure/AGENTS.md

template / infrastructure

AGENTS.md20 starsChanged 2 months agoApache-2.0View on GitHub

Layer 1 contains reusable tooling for the research template: project discovery, pipeline execution, validation, rendering, reporting, publishing, skills, and agent-facing documentation. Project-specific science stays in projects/{name}/src/; root and project scripts stay thin. - Business logic lives in infrastructure/ or projects/{name}/src/. - Scripts orchestrate only; moving computation into scripts breaks the template contract and the thin-orchestrator drift checks. - Do not hard-code rotating private project names. Link docs/generated/activeprojects.md for public rendered scope. - .codegraph/, .leann/, .omo/, coverage files, local/private output trees,…

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

4 rules. About 0 are common, 1 is distinctive, and 3 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 3

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Do not hard-code rotating private project names.

    line 31
  2. Very specific:

    Add new routable packages with AGENTS.md, README.md, and SKILL.md when they are intended for agent discovery.

    line 43
  3. Very specific:

    Keep generated facts in generated files.

    line 45
  4. Distinctive:

    Use focused pytest slices for changed packages, then broaden only when the changed surface crosses package or pipeline boundaries.

    line 61

≈ “Common” is an estimate: at least 1 in 5 of the 36,368 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

Infrastructure Layer

Purpose

Layer 1 contains reusable tooling for the research template: project discovery, pipeline execution, validation, rendering, reporting, publishing, skills, and agent-facing documentation. Project-specific science stays in projects/{name}/src/; root and project scripts stay thin.

Where To Look

TaskPrimary packageNotes
Run or inspect the pipelinecore/pipeline/, orchestration/, scripts/run.sh delegates into infrastructure.orchestration; stage semantics live in core/pipeline/pipeline.yaml.
Validate manuscripts and outputsvalidation/CLI entry point: uv run python -m infrastructure.validation.cli ....
Render PDFs, slides, web, DOCX, EPUBrendering/Rendering preflight may import validation leaves, not broad validators.
Project roster, sidecar links, git guardsproject/Public scope comes from project.public_scope; private mirrors are local-only. Sidecar sync for all four top-level trees is registered in orchestration/link_sync.py.
Resource pools (fonds, rules, tools)fonds/, rules/, tools/Passive data pools, governance rules, and invocable tools mirror projects/ with git-tracked templates/* exemplars.
Reports and release readinessreporting/Local evidence dashboards only; network publication is outside release-readiness aggregation.
Generated docs and live countsdocumentation/COUNTS.md, active projects, API reference, publication records.
Methods orchestrationmethods/Read-only mapping of pipeline contracts, methods prose, artifacts, evidence, validation commands.
Skill discovery and manifestsskills/Regenerates docs/_generated/skills_index.md and .cursor/skill_manifest.json.
Optional companionssearch/, llm/, steganography/, sia/, autoresearch/Keep opt-in dependencies and generated state out of default CI/pipeline unless documented.
Expose the agent surface over MCPmcp_server.pyOpt-in self-contained stdio JSON-RPC server (python -m infrastructure.mcp_server) exposing list_operations / describe_pipeline / list_skills / invoke_cli as MCP tools. Dual-era: legacy 2024-11-05 initialize plus stateless 2026-07-28 server/discover and per-request metadata. Standard-library only; not wired into CI/pipeline.

Boundaries

  • Business logic lives in infrastructure/ or projects/{name}/src/.
  • Scripts orchestrate only; moving computation into scripts breaks the template contract and the thin-orchestrator drift checks.
  • Do not hard-code rotating private project names. Link docs/_generated/active_projects.md for public rendered scope.
  • .codegraph/, .leann/, .omo/, coverage files, local/private output trees, and other local indexes are generated state and must not be tracked. Canonical public exemplar outputs admitted by the repository allowlist are publication evidence.
  • Optional tools such as CodeGraph and LEANN are navigation aids. Publication claims require source files, tests, evidence registries, artifacts, and gates.

Public API Rules

  • Infrastructure packages that re-export symbols must keep explicit __all__ entries and pass uv run python -m infrastructure.skills check-all-exports.
  • Add new routable packages with AGENTS.md, README.md, and SKILL.md when they are intended for agent discovery.
  • Keep generated facts in generated files. Do not copy measured counts into long-lived prose; regenerate docs/_generated/COUNTS.md instead.

Verification

uv run python -m infrastructure.project.public_scope lint-paths | xargs uv run ruff check
uv run python -m infrastructure.project.public_scope source-paths | xargs uv run mypy
uv run python scripts/audit/check_template_drift.py --strict
uv run python scripts/audit/check_tracked_all.py
uv run python scripts/audit/check_tracked_generated_artifacts.py
uv run python scripts/gates/module_line_count_check.py
uv run python -m infrastructure.skills check
uv run python -m infrastructure.skills check-all-exports

Use focused pytest slices for changed packages, then broaden only when the changed surface crosses package or pipeline boundaries.

Documentation Contract

  • AGENTS.md: operating contract for agents; concise and non-redundant.
  • README.md: human guide and deeper examples.
  • SKILL.md: routing contract with YAML frontmatter.
  • docs/_generated/*: generated facts; update via generator commands, not by hand.

See Also

  • README.md
  • methods/AGENTS.md
  • project/AGENTS.md
  • validation/AGENTS.md
  • rendering/AGENTS.md

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.

Reviews can't be read right now.

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.

Check your setup, free