Extension command rendering does not strip `scripts:` from the agent-facing frontmatter

[Yash-Chindam]

Problem Statement

Command rendering strips the scripts: key from the agent-facing frontmatter on the core path, but not on the extension path. An extension command that declares scripts: therefore ships a rendered artifact carrying a key that core's equivalent does not, leaking an internal build detail into the agent-visible file.

Split out of #4421 at a maintainer's request, so that stage 1 (#4488) stays additive and this shared-render fix is not smuggled into it.

Reproduction

main at d848fb4, with the bundled github extension from #4488 installed into a Copilot commands-mode project:

specify init proj --integration copilot --integration-options="--commands" --script sh
cd proj && specify extension add github

Extension render — .github/agents/speckit.github.taskstoissues.agent.md:

---
description: Convert existing tasks into actionable, dependency-ordered GitHub issues ...
tools:
- github/github-mcp-server/list_issues
- github/github-mcp-server/issue_write
scripts:
  sh: .specify/extensions/github/scripts/bash/resolve-tasks.sh --json
  ps: .specify/extensions/github/scripts/powershell/resolve-tasks.ps1 -Json
  py: .specify/extensions/github/scripts/python/resolve_tasks.py --json
---

Core render — .github/agents/speckit.taskstoissues.agent.md, same project, from a source template that declares the same key:

---
description: Convert existing tasks into actionable, dependency-ordered GitHub issues ...
tools: ['github/github-mcp-server/list_issues', 'github/github-mcp-server/issue_write']
---

No scripts: key. The path substitution happened in both — {SCRIPT} is resolved in each body — only the cleanup step differs.

Cause

The core path strips the key as step 3 of process_command_template in src/specify_cli/integrations/base.py, after it has been consumed for {SCRIPT} substitution. The extension path (CommandRegistrar.register_commands / _register_extension_skills, src/specify_cli/extensions/__init__.py) calls _adjust_script_paths and substitutes {SCRIPT}, but never removes the key before serialising the frontmatter.

Why it has gone unnoticed

No bundled extension declared scripts: before the github extension in #4488. agent-context and git both spell their script paths out in prose instead, so this branch of the render had no coverage.

Impact

Cosmetic today rather than a functional break — the rendered paths are correct and the commands run. The concerns are that the two render paths disagree where they should agree, and that a build-time key reaches agent-visible output.

One caveat worth checking during the fix: tools: is emitted inline (flow style) by the core render and block style by the extension render, as visible above. Semantically identical YAML, but it suggests the two paths serialise frontmatter through different code, which may be the right place to look.

Suggested Fix

Strip scripts: in the extension render once it has been consumed, matching process_command_template, and add a regression test asserting the key is absent from rendered extension commands in both command mode and skills mode.

Component

Specify CLI (initialization, commands)

---

Disclosure: I used an AI assistant (Claude Code, model Claude Opus 5) to investigate this and draft this report. The reproduction above was produced by installing the extension into a scratch project against main and reading the generated files back; I reviewed the findings before filing.

[github-actions]

Bug assessment — extension-frontmatter: Valid · severity low

---

Bug Assessment: Extension command rendering does not strip scripts: from the agent-facing frontmatter

• Slug: extension-frontmatter
• Created: 2026-09-12T13:11:33Z
• Source: issue Extension command rendering does not strip scripts: from the agent-facing frontmatter #4554
• Verdict: valid
• Severity: low

Report (summarized)

The report says core command rendering consumes scripts: to resolve {SCRIPT} and removes that build-time key from generated agent frontmatter, while extension command rendering resolves the paths but leaves scripts: visible. The supplied reproduction uses Copilot commands mode, installs the bundled github extension, and compares the generated .agent.md files. The reported result is cosmetic: paths and command execution are correct, but the two rendering paths produce inconsistent agent-facing metadata.

The issue has no additional comments. The issue metadata references an open remediation PR, #4559, but this assessment is based on the checked-out code and report.

Symptom

When an extension command declares a scripts: frontmatter mapping, the generated extension artifact can expose that internal mapping to the agent after {SCRIPT} has already been substituted. Core-rendered commands remove the same key, so equivalent commands have inconsistent frontmatter. Expected behavior is for both paths to consume and omit scripts:.

Reproduction

1. Use a project initialized with Copilot commands mode and a selected script type, as described in the report.
2. Install the bundled github extension with specify extension add github.
3. Inspect the generated extension command under .github/agents/.
4. Compare it with the equivalent core command under the same project.

The report provides the exact initialization command and generated frontmatter excerpts. [NEEDS CLARIFICATION: the report does not state whether the same leak was independently observed for every non-Copilot command-layout integration.]

Suspected Code Paths

• src/specify_cli/integrations/base.py:809-875 — IntegrationBase.process_template() explicitly selects a script variant, substitutes {SCRIPT}, and strips the scripts: section; this is the core behavior the report compares against.
• src/specify_cli/agents.py:616-778 — CommandRegistrar.register_commands() parses extension command frontmatter and calls _adjust_script_paths() before rendering command-layout output. The shared path normalizer rewrites values but does not remove the scripts mapping.
• src/specify_cli/agents.py:187-203 — CommandRegistrar._adjust_script_paths() deep-copies frontmatter and rewrites paths under scripts, leaving the mapping present for serialization.
• src/specify_cli/extensions/__init__.py:1530-1680 — _register_extension_skills() follows the extension skill path, calls _adjust_script_paths(), then serializes generated frontmatter without an explicit scripts removal. This is the parallel path that should be checked alongside command mode.
• src/specify_cli/agents.py:850-885 — command-layout rendering serializes the processed frontmatter, while the non-skills post-processing hook runs afterward; whether a given integration removes the key depends on that integration's hook, creating the reported path divergence.

Root Cause Hypothesis

Confidence: high. The shared extension registrar uses _adjust_script_paths() as a normalization step, but that helper only rewrites script values. The core process_template() has a separate explicit cleanup step that removes the entire scripts: section after substitution. Extension command and skill registration do not apply an equivalent cleanup before frontmatter serialization, so the internal mapping remains visible whenever an extension source declares it.

Proposed Remediation

Preferred: Add one shared frontmatter cleanup operation for consumed scripts: metadata and invoke it in both extension command-layout and extension skill rendering after script placeholders have been resolved, before the output frontmatter is serialized. Preserve the existing path rewriting and selected-script behavior; only remove the scripts key from the emitted metadata. If agent_scripts is a separate supported internal key, define explicitly whether it is also consumed rather than removing it opportunistically.

The implementation should cover both CommandRegistrar.register_commands() and _register_extension_skills() so command mode and skills mode cannot diverge. Reusing a small helper is preferable to duplicating frontmatter.pop("scripts", None) at multiple serialization sites, provided the helper's contract clearly states that script resolution has already occurred.

Alternatives:

• Call the existing integration process_template() or a generalized post-render cleanup from extension registration. Trade-off: this risks reapplying substitutions or path rewrites to already-rendered output and couples extension registration to integration-specific processing.
• Remove scripts: in _adjust_script_paths() itself. Trade-off: the helper is also used before placeholder resolution, so this could discard the mapping before {SCRIPT} or skill placeholder consumers have read it.

Files likely to change:

• src/specify_cli/agents.py
• src/specify_cli/extensions/__init__.py
• Relevant integration/extension rendering tests, likely tests/test_post_process.py and/or tests/test_extensions.py

Tests to add or update:

• Build a minimal extension command whose frontmatter contains scripts: and whose body contains {SCRIPT}; assert the rendered Copilot command-mode artifact contains the resolved path but not the scripts: key.
• Exercise the same source through the skills path and assert the generated SKILL.md also omits scripts: while retaining the resolved body command.
• Cover at least one ordinary Markdown command-layout agent to ensure the cleanup is shared and does not depend on Copilot-specific formatting.
• Retain a regression case for commands without scripts: and for frontmatter unrelated to script resolution.

Risks & Considerations

• Cleanup must occur after the selected script command has been consumed; doing it earlier would prevent {SCRIPT} resolution.
• Do not remove script mappings from source templates or installed extension files; only generated agent-facing output should change.
• Existing users may have generated files containing scripts:; the fix should apply on reinstall/upgrade and should not require a migration for a cosmetic artifact.
• YAML serialization style differences (tools: flow versus block style) are separate from the reported key leak and should not be broadened into this fix unless a test demonstrates semantic impact.
• The change is low risk and should not alter command invocation or script path semantics.

Open Questions

• [NEEDS CLARIFICATION: Should agent_scripts receive the same treatment, or is it intentionally agent-visible metadata?]
• [NEEDS CLARIFICATION: Should cleanup be applied to all extension command formats, including TOML and YAML, or only Markdown/Copilot output? The shared behavior suggests all generated agent-facing formats should be covered.]

Generated by 🐛 Assess Bug from Labeled Issue for #4554 · copilot · gpt52codex · 3.45 AIC · ⌖ 9.37 AIC · ⊞ 25.5K · ◷