Extension capability system: portable commands across agent harnesses #3303

Activity

1. mnriem commented on Jul 2, 2026

   

   mnriem

   on Jul 2, 2026

   Collaborator

   More actions

   Thanks for such a thoughtful writeup, @rhuss — and for reading the source before filing. You've correctly identified the real seam: spec-kit solves structural portability (format, paths, placeholders) but not content portability, and the building blocks you pointed at (post_process_skill_content, process_template, expressions.py) are the right places to be looking. cc-spex is a great stress test for this.

   I want to give you an honest answer rather than a vague "maybe," so let me split the proposal into the part we'd welcome in core and the part we'd push back on — and then suggest where the bulk of this most naturally lives.

   The part that fits in core. Generalizing the skills-only post_process_skill_content() into a post_process_command_content() available to all formats is reasonable and low-risk. Each integration owns its own transform, it's branch-free, and it's testable per-integration. If you'd like to open a focused PR for just that hook, we'd be glad to review it — it gives extension authors a clean per-agent seam without any shared machinery.

   The part we'd steer away from — the capability matrix plus conditional template blocks. Not because the pain isn't real (it is), but because that specific design pushes against an invariant that a lot of spec-kit's value quietly rests on.

   When you run specify init, everything is materialized into the project: scripts, templates, memory, workflows, and the rendered command files all land under the project (.specify/… and the agent's own folders). Extensions install into .specify/extensions/<id>/; presets compose the command files in place. After init, the coding agent only ever reads local files — the user never has to clone spec-kit core or any catalog repo, everything works offline, and the on-disk files are the whole truth. That self-containment is what makes the output auditable, forkable, and diffable, and it's what lets non-Python authors (prompt engineers, domain experts writing aide-style workflows) create and review commands with confidence.

   A capability system with {{#if subagents}}…{{else}}…{{/if}} would be the first feature to puncture that invariant, and it does so at the level of meaning, not just files:

   • The rendered command on disk stays concrete (the branch resolves at install), but the semantics of the template — which capability keys exist, what they resolve to for each agent — live in core's Python integration classes, which are never materialized into the project. For the first time, fully understanding or reproducing your own project's commands would require reaching outside the project, into core code on a different release cadence.
   • Extension and preset templates live in separate catalog repos, disjoint from core's Python. A {{#if subagents}} block there references a capability defined in another repo entirely, so those userland templates could no longer be validated on their own — a reviewer would need core's sources they may not have and shouldn't need.
   • It also turns agnostic, one-file-one-meaning commands into N latent variants, and imports workflow-style logic into files meant to be static docs (the pull toward expressions.py is the tell).

   And two operational realities make the matrix especially costly in core:

   • The data is volatile and externally controlled — tool names, hook names, and even "does this exist at all" change on each agent vendor's schedule, silently. Core would effectively be subscribing to dozens of external changelogs, and staleness would mis-render agnostic commands for everyone.
   • The maintainers can't reliably test the matrix — we don't have all ~40 agents installed and observable, so capability claims could be linted for shape but never verified for truth. The people who can verify a given agent's behavior are the folks who actually run it.

   It's worth being precise about what the capability system would actually save, because I don't think it's the user's experience. A user doesn't install "N variants" — they pick the agent(s) they actually use, and that maps to the matching extension (if any) plus the matching preset for that agent. Each user only ever consumes the one variant for their own agent. The N-variants exist only as an author-maintenance cost — and that cost sits most appropriately with the person who wants multi-agent reach and can actually test each agent, rather than being centralized into a core matrix no one can verify.

   Put together, agent-specific optimization tends to be local (each user only wants their own agent's variant), volatile (tracks that agent's churn), testable only by its owner, and opt-in — and those properties line up with our userland extensibility layers, not with core metadata.

   Where we'd suggest putting it instead — and it's genuinely buildable there:

   • Presets are built for "take an agnostic command and specialize it for an agent" via prepend/replace. A community preset like copilot-sub-agents already does your subagent-fanout case for Copilot; a claude-… counterpart would do it for Claude. A user just installs the one matching the agent they use — each variant is self-contained plain text, owned and tested by someone who runs that agent, and it stays materialized in the project like everything else.
   • Extensions already install helper scripts to a stable, project-local path (.specify/extensions/<id>/), and path rewriting preserves extension-local references — so your concern doco(spec-driven): Fix small typo in spec-driven.md #4 (script discovery) is largely handled today without a new __PLUGIN_ROOT__ placeholder. With post_process_command_content() added, you'd also get the per-agent content-transform seam.

   So the capability behavior you're after can be assembled on top of spec-kit — a neutral extension plus a thin per-agent preset — while keeping each piece materialized, self-contained, and auditable: the specialization stays right there in the project as plain text anyone can read, diff, and fork, owned by someone who can actually verify it against the agent it targets. That preserves the guarantee a capability matrix in core would break — that your project is the whole truth, reviewable without reaching into core Python we couldn't reliably test.

   If it's helpful, I'm happy to sketch what a "portable subagent" preset would look like using cc-spex's cases as the example, and to review that post_process_command_content() PR if you'd like to take it on. Really appreciate you pushing on this — it's exactly the right conversation to be having.
2. rhuss commented on Jul 2, 2026

   

   rhuss

   on Jul 2, 2026

   ContributorAuthor

   More actions

   The materialization invariant argument sold me. I hadn't thought about it that way: a capability matrix would be the first thing that forces you outside the project to understand your own commands. That's not just an engineering tradeoff, it's a design problem.

   Here's what I'm planning based on your feedback:

   post_process_command_content() PR. I'll open a focused PR. Add the method to IntegrationBase with a no-op default, call it from register_commands() for markdown/TOML/YAML, include tests against the existing skills-format agents to make sure nothing breaks.

   Presets for agent specialization. Your reframing clicked for me. I was stuck on this as an authoring problem ("one command that works everywhere") when it's really distribution ("each user gets the right variant for their agent"). Presets handle that, and the result stays materialized in the project. I'll prototype a claude-spex preset using prepend/replace to inject Claude Code tool references into neutral commands.

   One question on presets. For complex agent-specific sections (say, a ship pipeline that dispatches 4 subagents into isolated worktrees vs. running everything sequentially), replace might not be enough. The neutral and specialized versions aren't just different words, they're different control flow. Can replace handle multi-line block replacements keyed on a marker? Or is this a case where two genuinely different commands is the cleaner answer?

   I'll start with the post_process_command_content() PR since that's useful on its own.
3. mnriem commented on Jul 2, 2026

   

   mnriem

   on Jul 2, 2026

   Collaborator

   More actions

   Answering your question about markers. No markers are not supported currently.. Would love tho see the PR you said you will start with first
4. rhuss commented on Jul 2, 2026

   

   rhuss

   on Jul 2, 2026

   ContributorAuthor

   More actions

   allright, I'm on it :-) Thanks for the quick turnaround.
5. rhuss

   added a commit that references this issue on Jul 2, 2026

   feat(integrations): add post_process_command_content() hook for all f…

   ...

   70d165e
6. rhuss commented on Jul 6, 2026

   

   rhuss

   on Jul 6, 2026

   Last edited by rhuss

   ContributorAuthor

   More actions

   Closing this in favor of two focused follow-ups:

   • post_process_command_content() hook: #3311. This gives extensions a per-integration content transform seam without any shared capability metadata.
   • Extension lifecycle hook for post-install setup: #3359. Instead of a capability matrix in core, extensions get an on_install hook to self-adapt based on the detected harness. The result stays fully materialized and auditable, consistent with the invariant @mnriem outlined here.

   Thanks for the thorough response on the materialization invariant, it reframed the problem well.
7. rhuss

   closed this as completedon Jul 6, 2026
8. mnriem

   added a commit that references this issue on Jul 7, 2026

   feat(integrations): generalize post-processing to all format types (#…

   ...

   d4e7d2b