Claude/Agents MD files

Source of truth: the registry row in _processes/_shared/request-types.md, the agent prompt _processes/00_app/claude-agents-md-files.prompt.md, and the committed baseline packet _processes/00_app/_shared/claude-agents-md-files-baseline.md.

The flow

claude-agents-md-files runs outside the per-job pipeline. It first resolves the host root (the host project at ../ when installed, the repo root in standalone mode) and runs its self-target guard, then surveys the host read-only for the facts a good canonical CLAUDE.md needs (project identity, build & test commands, conventions, directory map, existing instruction files). It consults the committed baseline packet and re-validates current web guidance, generates a fresh CLAUDE.md candidate, then applies the locked regenerate-with-confirmation policy — create freely when missing, ask before replacing any divergent file — establishing AGENTS.md as a relative symlink to CLAUDE.md (or a user-selected real-copy fallback). Finally it authors an operation_record job born complete in 4_done/ so the run is tracked like every other action.

What it is for

claude-agents-md-files exists to give a host project a clean, current, single-source pair of root agent-instruction files. AGENTS.md is the open agent-instructions standard read by a wide ecosystem of tools; CLAUDE.md is Claude Code's auto-loaded project-memory file (which does not natively read AGENTS.md). Keeping AGENTS.md as a relative symlink to the canonical CLAUDE.md (always the main one) means both audiences read the same bytes, with zero drift.

• Create or refresh. When the files are missing it writes them; when they exist and diverge from a freshly-generated candidate it shows you the difference and asks before replacing — it never silently overwrites host-authored instructions.
• Always current. Each run consults a committed baseline best-practices packet and re-validates current web guidance (citing its sources), so the generated files reflect the latest recommended shape rather than a frozen snapshot.
• Idempotent. Run it as often as you like — on a host that already has the right files it confirms and exits; it only changes what diverges, and only with your confirmation.

The logic

claude-agents-md-files sits in the operation layer with shape op-card. Like the other op-cards it is direct-invoked: you send its prompt path yourself and it runs immediately. It is not orchestrator-routed and never enters the stage pipeline.

• The symlink sync model. CLAUDE.md is the real, canonical file at the host repo root (always the main one); AGENTS.md is a relative symlink to it — one set of bytes serving both. When symlinks are unavailable (e.g. a restricted filesystem) the agent offers, as a user-selected fallback, a real AGENTS.md copy of CLAUDE.md (there is no cross-tool import directive — the @path import is Claude-Code-only). It never falls back automatically.
• Regenerate with confirmation. The safety policy uses no sentinel markers and no managed-block scheme: create freely when a file is missing; ask before replacing any divergent existing file; ask on any symlink conflict, non-symlink existing file, or symlink-creation-unavailable — never auto-overwrite, auto-convert, or auto-fallback.
• Self-target guard. In standalone mode the resolved host root is the workflow root, whose canonical root file is CLAUDE.md with AGENTS.md a relative symlink to it. The agent detects this case and never silently replaces or demotes the workflow's own CLAUDE.md — it surfaces any divergence as a conflict to ask about.
• Records its own work. At end-of-run it authors an operation_record job born complete in 4_done/ (D-44, D-54) — a small, report-only, no-Git folder — so every action the workflow performs is tracked. It writes only its own record and never moves or edits another job's state.

The fields

Its "inputs" are the host project it surveys, the committed baseline packet it consults, the current web guidance it re-validates, and your answers at any conflict point. Its "outputs" are the host's two root instruction files (and, at end-of-run, its own tracked operation_record folder).

How to run it

claude-agents-md-files is an op-card: there is no intake to drop and no orchestrator to route it. Send the prompt path directly to a fresh Claude Code session.

_processes/00_app/claude-agents-md-files.prompt.md

See also