If agents-context.sh or agents-finalize.sh fails (non-zero exit or "status":"error" in its JSON) print ⚠️ <error.message> and stop — except a lint error from finalize: cut lines and retry (max 2 retries). Other failing commands are findings — report and continue.

Steps

Audit. Run .agents/skills/pflow-agents/scripts/agents-context.sh → {agents_md, claude_md, other_rule_files[], nested_agent_files[], docs[], manifests[], package_manager, task_runner, runner_targets[], npm_scripts[], composer_scripts[], tooling[], ci[], monorepo[], top_dirs[], installed_skills[], gitignored[]}.
Learn the rules. Read .agents/skills/pflow-agents/references/agents-md-guide.md. Apply its three tests (removal, derivability, duplication) to every line you write.
Read inputs, not to copy them. Read existing AGENTS.md, CLAUDE.md, other_rule_files (candidate rules to keep or drop), then docs (README, CONTRIBUTING…) to learn what is already documented and must not be repeated, and the task runner / CI config to get the real command names. Do not read the whole codebase; skim entry points only when a gotcha needs confirming.
Ask once. With one AskUserQuestion round (skip questions the conversation already answers; every question gets a "nothing / skip" option), collect the facts only the user knows:
- mistakes agents or new contributors keep making here;
- directories or files agents must not edit, or must ask before touching;
- the gate that must pass before a commit or PR, if ci/runner_targets leave it ambiguous;
- conventions no tool enforces (commits, branches, PR rules, where new code goes) that README does not already state;
- for monorepo projects: whether per-package AGENTS.md files are wanted (this skill writes the root file only).
Draft. Write the file in the guide's shape, ≤ 60 lines. Every bullet: imperative, concrete, one instruction, exact command or path. When an existing file had lines that fail the tests, drop them and list what you dropped and why. Point to installed_skills instead of restating their procedures. If package_manager, task_runner or the test command is unambiguous from the manifests alone, mention it only if several choices are plausible.
Write. One non-interactive Bash call feeding the Markdown through a quoted heredoc:

pflow-agents

Steps