fix(agents): sync agent.md descriptions with SKILL.md, fix gitignore guidance#15
Closed
bburda wants to merge 1 commit into
Closed
fix(agents): sync agent.md descriptions with SKILL.md, fix gitignore guidance#15bburda wants to merge 1 commit into
bburda wants to merge 1 commit into
Conversation
…guidance (#12) The 71 .github/agents/pharaoh.*.agent.md files shipped with descriptions that diverged from their source SKILL.md. Two were catastrophically truncated at the first '.' (split caught 'e.g.' and 'index.rst'), producing unclosed parens and backticks that broke Markdown rendering in Copilot's review UI on downstream PRs (sphinx-needs-demo#51). Changes: - 61 thin-wrapper agents: regenerate description and body verbatim from SKILL.md frontmatter; preserve existing handoffs. - 8 fat agents (mece, plan, change, spec, setup, decide, release, trace): update only the frontmatter description; leave hand-tailored inline content untouched. - pharaoh.setup.agent.md Step 3: rewrite gitignore guidance to mirror SKILL.md Step 4b. Ignore only ephemeral subpaths (.pharaoh/runs/, .pharaoh/plans/, .pharaoh/session.json, .pharaoh/cache/); .pharaoh/project/ tailoring stays tracked. - ci.yaml: add a guard that fails the agent-frontmatter step when the description has unbalanced parens, brackets, or backticks. Catches the truncation class that produced the original regression.
There was a problem hiding this comment.
Pull request overview
This PR fixes agent template regressions by synchronizing .github/agents/*.agent.md descriptions with their corresponding skills/*/SKILL.md descriptions, updates pharaoh.setup’s .gitignore guidance to only ignore ephemeral .pharaoh/ paths, and hardens CI to catch future truncated/broken agent descriptions.
Changes:
- Regenerated thin-wrapper agents so both frontmatter
description:and the one-line body description matchSKILL.mdverbatim (preservinghandoffs:). - Updated
pharaoh.setup.agent.mdto recommend ignoring only ephemeral.pharaoh/subpaths (keeping.pharaoh/project/tracked). - Extended CI validation to fail on unbalanced parentheses/brackets/backticks in agent frontmatter descriptions.
Reviewed changes
Copilot reviewed 72 out of 72 changed files in this pull request and generated no comments.
Show a summary per file
| File | Description |
|---|---|
| .github/workflows/ci.yaml | Add CI guard to detect unbalanced markdown delimiters in agent frontmatter description:. |
| .github/agents/pharaoh.activity-diagram-draft.agent.md | Sync agent description with SKILL.md. |
| .github/agents/pharaoh.api-coverage-check.agent.md | Sync agent description with SKILL.md. |
| .github/agents/pharaoh.arch-draft.agent.md | Sync agent description with SKILL.md. |
| .github/agents/pharaoh.arch-review.agent.md | Sync agent description with SKILL.md. |
| .github/agents/pharaoh.audit-fanout.agent.md | Sync agent description with SKILL.md. |
| .github/agents/pharaoh.block-diagram-draft.agent.md | Sync agent description with SKILL.md. |
| .github/agents/pharaoh.bootstrap.agent.md | Sync agent description with SKILL.md. |
| .github/agents/pharaoh.change.agent.md | Sync agent frontmatter description with SKILL.md. |
| .github/agents/pharaoh.class-diagram-draft.agent.md | Sync agent description with SKILL.md. |
| .github/agents/pharaoh.component-diagram-draft.agent.md | Sync agent description with SKILL.md. |
| .github/agents/pharaoh.context-gather.agent.md | Sync agent description with SKILL.md. |
| .github/agents/pharaoh.coverage-gap.agent.md | Sync agent description with SKILL.md. |
| .github/agents/pharaoh.decide.agent.md | Sync agent frontmatter description with SKILL.md. |
| .github/agents/pharaoh.decision-record.agent.md | Sync agent description with SKILL.md. |
| .github/agents/pharaoh.decision-review.agent.md | Sync agent description with SKILL.md. |
| .github/agents/pharaoh.deployment-diagram-draft.agent.md | Sync agent description with SKILL.md. |
| .github/agents/pharaoh.diagram-lint.agent.md | Sync agent description with SKILL.md. |
| .github/agents/pharaoh.diagram-review.agent.md | Sync agent description with SKILL.md. |
| .github/agents/pharaoh.dispatch-signal-check.agent.md | Sync agent description with SKILL.md. |
| .github/agents/pharaoh.execute-plan.agent.md | Sync agent description with SKILL.md. |
| .github/agents/pharaoh.fault-tree-diagram-draft.agent.md | Sync agent description with SKILL.md. |
| .github/agents/pharaoh.feat-balance.agent.md | Sync agent description with SKILL.md. |
| .github/agents/pharaoh.feat-component-extract.agent.md | Sync agent description with SKILL.md. |
| .github/agents/pharaoh.feat-draft-from-docs.agent.md | Sync agent description with SKILL.md. |
| .github/agents/pharaoh.feat-file-map.agent.md | Sync agent description with SKILL.md. |
| .github/agents/pharaoh.feat-flow-extract.agent.md | Sync agent description with SKILL.md. |
| .github/agents/pharaoh.feat-review.agent.md | Sync agent description with SKILL.md. |
| .github/agents/pharaoh.finding-record.agent.md | Sync agent description with SKILL.md. |
| .github/agents/pharaoh.flow.agent.md | Sync agent description with SKILL.md. |
| .github/agents/pharaoh.fmea.agent.md | Sync agent description with SKILL.md. |
| .github/agents/pharaoh.fmea-review.agent.md | Sync agent description with SKILL.md. |
| .github/agents/pharaoh.gate-advisor.agent.md | Sync agent description with SKILL.md. |
| .github/agents/pharaoh.id-allocate.agent.md | Sync agent description with SKILL.md. |
| .github/agents/pharaoh.id-convention-check.agent.md | Sync agent description with SKILL.md. |
| .github/agents/pharaoh.lifecycle-check.agent.md | Sync agent description with SKILL.md. |
| .github/agents/pharaoh.link-completeness-check.agent.md | Sync agent description with SKILL.md. |
| .github/agents/pharaoh.mece.agent.md | Sync agent frontmatter description with SKILL.md. |
| .github/agents/pharaoh.output-validate.agent.md | Sync agent description with SKILL.md. |
| .github/agents/pharaoh.papyrus-non-empty-check.agent.md | Sync agent description with SKILL.md. |
| .github/agents/pharaoh.plan.agent.md | Sync agent frontmatter description with SKILL.md. |
| .github/agents/pharaoh.process-audit.agent.md | Sync agent description with SKILL.md. |
| .github/agents/pharaoh.prose-migrate.agent.md | Sync agent description with SKILL.md. |
| .github/agents/pharaoh.quality-gate.agent.md | Sync agent description with SKILL.md. |
| .github/agents/pharaoh.release.agent.md | Sync agent frontmatter description with SKILL.md. |
| .github/agents/pharaoh.reproducibility-check.agent.md | Sync agent description with SKILL.md. |
| .github/agents/pharaoh.req-code-grounding-check.agent.md | Sync agent description with SKILL.md. |
| .github/agents/pharaoh.req-codelink-annotate.agent.md | Sync agent description with SKILL.md. |
| .github/agents/pharaoh.req-draft.agent.md | Sync agent description with SKILL.md. |
| .github/agents/pharaoh.req-from-code.agent.md | Sync agent description with SKILL.md. |
| .github/agents/pharaoh.req-regenerate.agent.md | Sync agent description with SKILL.md. |
| .github/agents/pharaoh.req-review.agent.md | Sync agent description with SKILL.md. |
| .github/agents/pharaoh.review-completeness.agent.md | Sync agent description with SKILL.md. |
| .github/agents/pharaoh.self-review-coverage-check.agent.md | Sync agent description with SKILL.md. |
| .github/agents/pharaoh.sequence-diagram-draft.agent.md | Sync agent description with SKILL.md. |
| .github/agents/pharaoh.setup.agent.md | Sync frontmatter description with SKILL.md; fix .gitignore guidance to ignore only ephemeral .pharaoh/ paths. |
| .github/agents/pharaoh.spec.agent.md | Sync agent frontmatter description with SKILL.md. |
| .github/agents/pharaoh.sphinx-extension-add.agent.md | Sync agent description with SKILL.md. |
| .github/agents/pharaoh.standard-conformance.agent.md | Sync agent description with SKILL.md. |
| .github/agents/pharaoh.state-diagram-draft.agent.md | Sync agent description with SKILL.md. |
| .github/agents/pharaoh.status-lifecycle-check.agent.md | Sync agent description with SKILL.md. |
| .github/agents/pharaoh.tailor-bootstrap.agent.md | Sync agent description with SKILL.md. |
| .github/agents/pharaoh.tailor-code-grounding-filters.agent.md | Sync agent description with SKILL.md. |
| .github/agents/pharaoh.tailor-detect.agent.md | Sync agent description with SKILL.md. |
| .github/agents/pharaoh.tailor-fill.agent.md | Sync agent description with SKILL.md. |
| .github/agents/pharaoh.tailor-review.agent.md | Sync agent description with SKILL.md. |
| .github/agents/pharaoh.toctree-emit.agent.md | Fix previously truncated description by syncing with SKILL.md. |
| .github/agents/pharaoh.trace.agent.md | Sync agent frontmatter description with SKILL.md. |
| .github/agents/pharaoh.use-case-diagram-draft.agent.md | Sync agent description with SKILL.md. |
| .github/agents/pharaoh.vplan-draft.agent.md | Sync agent description with SKILL.md. |
| .github/agents/pharaoh.vplan-review.agent.md | Sync agent description with SKILL.md. |
| .github/agents/pharaoh.write-plan.agent.md | Fix previously truncated description by syncing with SKILL.md. |
Contributor
Author
|
#16 included this |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #12.
Summary
description:and body line now copy the SKILL.md description verbatim. Existinghandoffs:entries preserved.mece,plan,change,spec,setup,decide,release,trace): only the frontmatterdescription:is swapped for the SKILL.md value. Hand-tailored inline body content (Process, Steps, Constraints) is left untouched to avoid UX regression.pharaoh.setup.agent.mdStep 3: rewritten to mirrorskills/pharaoh-setup/SKILL.mdStep 4b. Now ignores only the ephemeral subpaths (.pharaoh/runs/,.pharaoh/plans/,.pharaoh/session.json,.pharaoh/cache/);.pharaoh/project/tailoring stays tracked..github/workflows/ci.yaml: the agent-frontmatter validation step now fails whendescription:has unbalanced parentheses, brackets, or backticks. Catches the exact truncation class that produced the original regression ((e.and`index.).Why
Issue #12 surfaced two visibly broken descriptions (
pharaoh.write-plan,pharaoh.toctree-emit) flagged by Copilot Code Review onuseblocks/sphinx-needs-demo#51, plus contradictory.gitignoreguidance inpharaoh.setup.agent.mdthat conflicted with its ownSKILL.md. Auditing all 71 agents showed they all diverged from theirSKILL.mdto varying degrees, so the cleanup is repo-wide.Test plan
python3audit confirms 0 description mismatches againstSKILL.md(was 71)python3audit confirms 0 unbalanced markdown in any agent description (was 2)Validate agent frontmatterstep passes (status 0)bootstrap,diagram-lint,status-lifecycle-check,use-case-diagram-draft) — handoffs preserved verbatimmece,setup,execute-plan) — fat-agent body content untouched, onlydescription:line changed