#522 Support partials in skills and subagent definitions

[williamthorsen]

What

Authors of subagent and skill markdown can now extract repeated content into shared partials and reference them via include directives, with optional inline slot content for per-call variation. This eliminates the cross-file drift that was already producing false-positive findings during automated review.

Why

Five reviewer subagent definitions carried near-identical copies of the same ~40-line section, and the duplication was already producing observable harm. During #452 wrap-up, a reviewer flagged an intentional carve-out as a bug because four-of-five files agreed and the fifth deliberately differed — agent compute and developer time were spent disambiguating a false positive. Wording variants slipped through earlier review because keeping five files in sync is structurally fragile. Every future tweak required edits in five places, with no in-source signal to distinguish a bug from an intentional difference. The directive expander already existed for platform guidance; extending it to subagents and skills closes the gap that motivated the original work.

Details

🎉 Features

• Directive grammar extended in directive-expander.ts to recognize three explicit shapes — self-close (<!-- include: path / -->), open (<!-- include: path -->), close (<!-- /include -->) — plus a <!-- children --> slot placeholder. Slot content is substituted verbatim (no whitespace normalization) so partial authors control output spacing predictably. Cycle detection threads the visited-set through the slot expansion path; recursion, source-tree containment, and the existing single-file-stack discipline continue to apply.
• installSubagents() and installSkillEntry() invoke expandIncludes before downstream transforms (frontmatter merge, marker injection, path rewriting), mirroring installPlatformGuidance's integration. Skill directories validate-by-expanding all .md files into a memoized map first, then write from the map — eager error detection without expanding each file twice.
• _partials/ directories at any depth under content/ are excluded from install copy. Their contents are referenced through includes, not installed directly.
• Documentation at content/_partials/README.md covers grammar, location convention, install pipeline ordering, the verbatim slot rule, common patterns, three forward-compatibility constraints (reserved <!-- slot: --> tokens, children as canonical default-slot name, rejection of unrecognized parameters), the no-frontmatter-in-partials constraint, and the structured error catalog.

🐛 Bug fixes

• Malformed include directives missing whitespace after the colon (e.g., <!-- include:foo unknown -->) now surface as a structured unrecognized-parameter error with file:line context. Previously they matched none of the recognized directive shapes — including the catch-all — and fell through to plain content, silently dropping the typo at install. Detection is now consistent with the well-formed <!-- include: foo unknown --> variant.

♻️ Refactoring

• Five reviewer subagents (orchestrated-reviewer, aspect-code-reviewer, aspect-silent-failure-reviewer, aspect-test-reviewer, code-simplification-reviewer) and orchestrated-coder.md migrated to consume nine new partials under content/subagents/_partials/ for the previously duplicated "Incremental review writes" / "Incremental change-summary writes" section. The simplifier's carve-outs (no re-review note, no return-block sentence in finalize) are expressed as bare self-close includes; the four return-block reviewers fill open/close slots with their per-call variation.
• Two .prettierignore updates (root and packages/agents/) exclude _partials/ and the consuming files with an inline comment explaining slot-substitution sensitivity. Prevents future Prettier runs from silently breaking expansion by inserting blank lines around HTML comments.
• Three platform-guidance directives migrated from the legacy bare-open form to the self-closing form, and the test fixtures in install-guidance.test.ts migrated alongside.
• expandFile body wrapped in try { ... } finally { visited.delete(filePath); } so the visited-set invariant is locally held; an exception between add and delete no longer leaves a leaked entry. Behavior unchanged in the success path.
• appendLines accepts a filePath parameter so its invariant-violation message embeds the file under expansion, matching the diagnostic content of the post-loop guard.
• installSkillEntry standardizes on srcPath.endsWith('.md') at both decision points (the early populate-cache check and the late write-from-cache check) for consistency.

🧪 Tests

• Expander grammar coverage: all three directive shapes, all seven structured-error reasons (cycle, not-found, orphan-close, out-of-tree, slot-without-children, unclosed-open, unrecognized-parameter), slot substitution with content, empty slots via bare include and via empty open/close pair, nested includes inside slot content, partials including other partials, recursive cycle detection through the open/close slot path, nested open frames at stack depth >1, sequential non-nested open/close blocks, inline <!-- /include --> in prose treated as plain content, verbatim slot whitespace preservation, and a regression test for the malformed-directive bug fix above.
• Install-time tests: subagent self-close expansion, open/close with slot, dry-run errors surfaced before write, _partials/ exclusion at top level and at nested depth (modules/_partials/), and an expand-then-rewrite ordering check that catches a regression where path rewriting would otherwise miss links inside expanded partial content.
• Real-content round-trip tests: the four return-block reviewers and the simplifier produce expected expanded content from the actual content/ tree, with the simplifier's carve-outs verified explicitly via not.toContain assertions.

Closes #522

[github-actions]

Dependency audit

Production dependency audit passed.