agent.md files in .github/agents have truncated descriptions and contradict their own skill specs

[bburda]

Summary

Files under .github/agents/pharaoh.*.agent.md are copied into user projects by pharaoh-setup. Three of them surface as review-time issues on downstream PRs and were flagged by GitHub Copilot Code Review on useblocks/sphinx-needs-demo#51.

(1) Truncated description: fields

pharaoh.write-plan.agent.md line 4:

description: Use when you have an intent (e.

pharaoh.toctree-emit.agent.md line 4:

description: Use when a composition skill has just emitted a set of RST files into a directory and needs to add (or regenerate) an `index.

Both end mid-sentence and break Markdown rendering (unmatched parenthesis in the first, unclosed backtick in the second). The pattern looks like the generator splits the source skill description on the first . character, which incorrectly catches e.g. and `index.rst`. The body of each file (line 7) shows the same truncation, suggesting both fields are derived from the same source string.

Likely root cause: the agent-frontmatter generator uses something like description.split('.', 1)[0] instead of a sentence-aware splitter or just-take-the-full-first-line.

(2) pharaoh.setup.agent.md contradicts skills/pharaoh-setup/SKILL.md

pharaoh.setup.agent.md line 71:

### Step 3: Configure .gitignore

Add `.pharaoh/` to `.gitignore` if not already present.

But skills/pharaoh-setup/SKILL.md Step 4b explicitly says:

Ignoring the whole tree is wrong, it hides .pharaoh/project/ tailoring which IS shared across the team. The skill ignores only the ephemeral subpaths.

The agent file therefore instructs Copilot to write a .gitignore rule that the skill itself rejects. Downstream PRs reviewed by Copilot flag the inconsistency.

Suggested fixes

1. Replace the generator's first-period split with a sentence-aware splitter, or take the full first line of the description verbatim.
2. Regenerate pharaoh.setup.agent.md from the SKILL.md spec, or hand-rewrite Step 3 to mirror Step 4b of the skill: narrow ignores only (.pharaoh/runs/, .pharaoh/plans/, .pharaoh/session.json, .pharaoh/cache/), with .pharaoh/project/ left tracked.

Repro

See review comments on useblocks/sphinx-needs-demo#51.

[bburda]

Audit on useblocks/sphinx-needs-demo#51 showed the truncation pattern affects more than the two files I originally listed. Same description.split('.', 1)[0] shape in:

• pharaoh.write-plan.agent.md (cut at e.g., unmatched paren) — original report
• pharaoh.toctree-emit.agent.md (cut at index.rst, unclosed backtick) — original report
• pharaoh.execute-plan.agent.md (cut at plan.yaml to Use when executing a plan.) — new
• pharaoh.feat-file-map.agent.md (cut at it. Reads the source tree... to ...implement it.) — new

Plus one description that diverges from SKILL.md for a different reason:

• pharaoh.papyrus-non-empty-check.agent.md — agent says Verify that a Papyrus workspace received at least N writes during a plan run., skill says Use when verifying that a Papyrus workspace actually received writes during a plan run. Single mechanical check .... Not a truncation, but the mismatch should be intentional or aligned.

Cross-checking 71 agent files against their SKILL.md siblings: only the four above are first-period-truncation; everything else either matches verbatim, is a deliberate Copilot-registry summary (shorter than the skill description but a complete sentence), or is the papyrus-non-empty-check divergence above.

Suggested fix for the generator: take the full first line of the SKILL.md description without splitting on ., and have a separate optional agent_description field in the skill frontmatter when an explicit shorter form is needed for the Copilot registry.

[bburda]

#16 included this