[Feature]: Add --json output to preset info and extension info with fully-expanded per-contribution detail (per-pack detail view; complements list --json summary counts)

[nicolehaugen]

Problem Statement

Today specify preset info <id> and specify extension info <id> emit only text. speckit-wizard-canvas reads the raw preset.yml / extension.yml files with js-yaml and re-normalizes the shape itself in composition/collect.mjs::parseProvidesEntries and ::parseHookDeclarations — including strategy inference from shorthand keys (replaces vs. wraps vs. prepends vs. appends), hook-phase normalization (phase vs. trigger, command vs. targetCommand), and script-runtime inference by globbing scripts/{bash,powershell,python}/*.{sh,ps1,py}. All of this is server-side data being reconstructed on the client.

Downstream consumers need the structured shape returned by the CLI itself so they can stop reconstructing it.

How this differs from the companion preset list --json / extension list --json issue. The list variant operates on the collection of installed packs and returns a JSON array, one row per pack, where provides is just integer counts ({ commands: 4, templates: 2, scripts: 1, hooks: 3 }) — a summary/catalog view suitable for "here's every preset the project has". info operates on one pack, addressed by id, and returns a single JSON object where provides is fully expanded — every command, template, script, and hook enumerated with its full per-contribution schema (id, name, description, artifact, optional, handoffs, strategy, sourcePath, runtimes, etc.). A wizard rendering "here's what speckit.git contributes to my project" needs the info detail; list's counts are not enough. Both surfaces are required; neither is a subset of the other.

Proposed Solution

Add --json to both info commands. Output shape:

{
  "id": "…", "name": "…", "description": "…", "version": "…",
  "author": "…", "priority": 100, "enabled": true, "source": { "…": "…" },
  "commands": [
    { "id": "…", "name": "speckit.plan", "description": "…",
      "artifact": "specs/{feature}/plan.md", "optional": false,
      "handoffs": [ { "to": "speckit.tasks", "when": "…", "message": "…" } ],
      "strategy": "wrap",
      "source": { "layer": "preset", "presetId": "…" },
      "sourcePath": "commands/speckit.plan.md" }
  ],
  "templates": [
    { "id": "…", "name": "…", "description": "…",
      "strategy": "replace",
      "source": { "…": "…" }, "sourcePath": "templates/…" }
  ],
  "scripts": [
    { "id": "…", "name": "…", "description": "…",
      "strategy": "replace",
      "source": { "…": "…" }, "sourcePath": "scripts/bash/…",
      "runtimes": ["bash", "powershell", "python"] }
  ],
  "hooks": [
    { "id": "…", "name": "…", "description": "…",
      "trigger": "before_speckit.plan", "targetCommand": "speckit.git.checklist",
      "sourcePath": "commands/speckit.git.checklist.md",
      "optional": false, "priority": 10 }
  ]
}

Notes:

• Preset objects omit hooks.
• Extension commands/templates/scripts entries omit strategy (they are always replace, per the replace-only rule enforced at extensions/__init__.py:622-626).
• id values use the stable-id scheme from the companion "stable id / lookupId" issue; the id on a per-contribution entry is what the companion specify artifact info --json stack's lookupId points at.
• artifact, optional, handoffs on commands come from the companion "artifact/optional/handoffs" issue.
• runtimes on scripts comes directly from the manifest (extensions post-[Feature]: Allow extensions to declare templates and scripts in their manifest #4010; add the same field to preset script entries for parity).
• All shorthand-key normalization (replaces/wraps/prepends/appends → strategy: "replace"|"wrap"|"prepend"|"append") is done server-side.

Alternatives Considered

• Fold everything into the companion specify artifact info --json command. Rejected — artifact info is per-artifact (walks one composition stack across all installed packs); info --json is per-source (walks one preset/extension across all its contributions). Both are needed and neither is a subset of the other.
• Fold everything into the companion preset list --json / extension list --json. Rejected — that surface is per-collection with summary counts; info is per-pack with full expansion. Different shape, different call pattern, different use cases (see Problem Statement).
• Emit YAML. Rejected — the whole point is to let the wizard drop js-yaml.
• Leave hook-phase / strategy shorthand un-normalized. Rejected — every consumer would reproduce the client-side logic from composition/collect.mjs and drift over time.

Component

Specify CLI (initialization, commands)

AI Agent (if applicable)

Not applicable

Use Cases

1. speckit-wizard-canvas deletes composition/collect.mjs::parseProvidesEntries and ::parseHookDeclarations, replacing them with JSON.parse(execFileSync("specify", ["preset", "info", "<id>", "--json"])) / specify extension info <id> --json. This is the change that removes the js-yaml dependency.
2. An IDE plugin renders hover-cards on command names by looking up the commands[] entry (description, artifact, handoffs).
3. A pre-commit check walks extension info --json's hooks[] to warn when two extensions register the same trigger at the same priority.

Acceptance Criteria

• specify preset info <id> --json and specify extension info <id> --json emit a single JSON object with top-level fields matching the companion list --json issue (id, name, description, version, author, priority, enabled, source) plus fully-expanded commands, templates, scripts arrays (and hooks for extensions) — not integer counts.
• Command entries include artifact, optional, handoffs (from the companion command-fields issue).
• Script entries include runtimes for both presets and extensions.
• Preset command/template/script entries include strategy; extension entries omit it (or set to "replace" for informational purposes).
• Shorthand keys (replaces/wraps/prepends/appends) are normalized server-side into strategy.
• Hook entries include trigger, targetCommand, sourcePath, optional, priority — phase/command shorthand normalized.
• All id values follow the stable-id scheme and are stable across reinstalls, matching the lookupId values emitted by specify artifact info --json.
• Unknown id → non-zero exit + stderr JSON error.
• Tests: schema round-trip, strategy normalization (all four shorthand forms), hook shorthand normalization, extension replace-only enforcement, handoffs frontmatter-merge, and id cross-reference with specify artifact info --json output.
• Docs: preset info / extension info sections in the CLI reference show the --json shape and normalization rules, plus a note contrasting info --json (per-pack, full expansion) with list --json (per-collection, count summary).

Additional Context

Direct replacement for plugins/spec-kit-copilot-wizard/extensions/speckit-wizard-canvas/composition/collect.mjs::parseProvidesEntries and ::parseHookDeclarations in github/spec-kit-copilot. Depends on the companion "artifact/optional/handoffs" and "stable id / lookupId" issues; benefits from the companion "structured source provenance" issue.

[github-actions]

Feature assessment — info-json-full-expansion · Stage 1/5: Intake

Idea Intake: Add --json to preset info and extension info

• Slug: info-json-full-expansion
• Created: 2026-08-19
• Source: GitHub issue [Feature]: Add --json output to preset info and extension info with fully-expanded per-contribution detail (per-pack detail view; complements list --json summary counts) #4213, github/spec-kit, raised by @nicolehaugen
• Type: improvement

Idea (as captured)

Add --json to both specify preset info <id> and specify extension info <id> commands. The output should be a single JSON object with top-level metadata fields (id, name, description, version, author, priority, enabled, source) plus fully-expanded arrays: commands, templates, scripts (and hooks for extensions) — each item enumerated with its full per-contribution schema (id, name, description, artifact, optional, handoffs, strategy, sourcePath, runtimes, etc.). Strategy shorthand keys (replaces/wraps/prepends/appends) are normalized server-side. Hook shorthand (phase/command vs trigger/targetCommand) is also normalized. Unknown id exits non-zero with a JSON error on stderr.

Restated

Today specify preset info and specify extension info emit only human-readable text; downstream consumers such as speckit-wizard-canvas reconstruct the structured shape by parsing raw YAML files directly. This feature adds --json to both commands, returning a single, fully-normalized JSON object so clients can stop duplicating server-side normalization logic.

Origin & Context

• Raised by: @nicolehaugen
• Trigger: The speckit-wizard-canvas component in the github/spec-kit-copilot repository re-parses preset.yml/extension.yml with js-yaml and re-implements strategy-inference and hook-normalization logic (parseProvidesEntries, parseHookDeclarations in composition/collect.mjs). This creates a fragile client-side mirror of server-side logic that drifts over time.

First-Glance Unknowns

• [NEEDS CLARIFICATION: What is the exact stable-id scheme for per-contribution id fields? The issue references a companion "stable id / lookupId" issue but does not link it.]
• [NEEDS CLARIFICATION: What fields does the companion "artifact/optional/handoffs" issue define for command entries? Both are hard dependencies.]
• [NEEDS CLARIFICATION: Should specify artifact info --json cross-reference IDs be validated in this PR or deferred to the companion issue?]
• [NEEDS CLARIFICATION: Is speckit-wizard-canvas the only known consumer, or are there other downstream clients depending on this shape?]

Generated by 💡 Assess a Feature Request by Installing and Running Spec Kit for issue #4213 · 614.8 AIC · ⌖ 12.3 AIC · ⊞ 38K · ◷

[github-actions]

Feature assessment — info-json-full-expansion · Stage 2/5: Research

Idea Research: Add --json to preset info and extension info

• Slug: info-json-full-expansion
• Created: 2026-08-19
• Evidence confidence (overall): high

Users & Demand

• speckit-wizard-canvas (github/spec-kit-copilot, composition/collect.mjs) explicitly re-parses raw preset.yml/extension.yml using js-yaml and re-implements parseProvidesEntries and parseHookDeclarations, including strategy-shorthand inference and hook-phase normalization. This is the direct, stated motivation; the consumer is identified by name. — [source: issue [Feature]: Add --json output to preset info and extension info with fully-expanded per-contribution detail (per-pack detail view; complements list --json summary counts) #4213 body] (confidence: high, cited)
• IDE plugin hover-cards and pre-commit hook-collision checks are listed as additional use cases in the issue. These are plausible but unnamed/unlinked. — [source: issue [Feature]: Add --json output to preset info and extension info with fully-expanded per-contribution detail (per-pack detail view; complements list --json summary counts) #4213 body] (confidence: low, assumption)

Prior Art

• specify preset list --json / specify extension list --json: The issue references a companion list-JSON issue as existing or in-flight; this feature is explicitly scoped as complementary to it (per-pack detail vs. per-collection counts). No PR/issue number is linked. — [NEEDS CLARIFICATION: Is list --json already shipped or also planned?] (confidence: medium, assumption)
• specify artifact info --json: A companion issue covers per-artifact lookup. Neither supersedes the other. — [source: issue [Feature]: Add --json output to preset info and extension info with fully-expanded per-contribution detail (per-pack detail view; complements list --json summary counts) #4213 body] (confidence: high, cited)
• Current preset info implementation (src/specify_cli/presets/_commands.py, line 461): outputs Rich-formatted text only; no --json flag exists. Confirmed by codebase inspection. — [source: codebase] (confidence: high, cited)
• Current extension info implementation (src/specify_cli/extensions/_commands.py, line 1337): text-only, no JSON path. — [source: codebase] (confidence: high, cited)
• Strategy normalization already exists (src/specify_cli/presets/__init__.py, line 258: VALID_PRESET_STRATEGIES = {"replace", "prepend", "append", "wrap"}; line 451: strategy defaults to "replace" and is validated). The canonical longform is already stored in the Python layer after YAML parsing. — [source: codebase] (confidence: high, cited)
• Extension strategy is already rejected (src/specify_cli/extensions/__init__.py, lines 622–626): extensions cannot author strategy — enforced at the Python layer. — [source: codebase] (confidence: high, cited)
• runtimes field exists for extension scripts (src/specify_cli/extensions/__init__.py, lines 628–639): validated as a list of strings. — [source: codebase] (confidence: high, cited)

Market & Context

• CLI-first tools (e.g., Homebrew, npm, gh) routinely expose --json on detail commands as a first-class contract for scripting and tooling. The pattern is well-established. — [source: general knowledge] (confidence: medium, assumption)
• Without --json, downstream consumers parsing preset info text output are brittle to Rich formatting changes. The wizard currently bypasses the CLI entirely by reading raw YAML, which can silently drift from the CLI's validated schema. — [source: issue [Feature]: Add --json output to preset info and extension info with fully-expanded per-contribution detail (per-pack detail view; complements list --json summary counts) #4213 body] (confidence: high, cited)

Data & Constraints

• The fully-expanded JSON shape depends on multiple companion issues for id, artifact, optional, handoffs. These are hard dependencies; shipping before companions means either omitting fields or risking a breaking shape change later. — [source: issue [Feature]: Add --json output to preset info and extension info with fully-expanded per-contribution detail (per-pack detail view; complements list --json summary counts) #4213 body] (confidence: high, cited)
• No JSON test coverage currently exists for preset info / extension info. — [source: codebase] (confidence: medium, cited)

Evidence Against the Idea

• Companion dependency risk: artifact/optional/handoffs and stable id / lookupId are hard dependencies. If those ship after this issue, the JSON contract would be incomplete on first release, requiring a follow-up breaking change or stubs.
• Surface area / maintenance: Adding --json to two commands requires schema stability guarantees going forward. Any output shape change becomes a breaking change for consumers.
• Duplication concern: The issue pre-empts the argument that artifact info --json covers this use case, but reviewers may still question whether both surfaces are necessary. The distinction (per-pack vs. per-artifact) is clear in the issue text but not self-evident to new readers.

Gaps & Open Questions

• [NEEDS CLARIFICATION: Are the companion issues (stable id / lookupId, artifact/optional/handoffs) already merged or still open?]
• [NEEDS CLARIFICATION: Does the current preset.yml loader normalize replaces/wraps/prepends/appends shorthand keys, or does it only accept canonical longform?]
• [NEEDS CLARIFICATION: Are there additional known consumers beyond speckit-wizard-canvas?]

Sources

• github.com/[Feature]: Add --json output to preset info and extension info with fully-expanded per-contribution detail (per-pack detail view; complements list --json summary counts) #4213 (host: github.com, policy: allowlisted)
• Codebase: src/specify_cli/presets/_commands.py, src/specify_cli/extensions/_commands.py, src/specify_cli/presets/init.py, src/specify_cli/extensions/init.py (local filesystem)

Generated by 💡 Assess a Feature Request by Installing and Running Spec Kit for issue #4213 · 614.8 AIC · ⌖ 12.3 AIC · ⊞ 38K · ◷

[github-actions]

Feature assessment — info-json-full-expansion · Stage 3/5: Problem

Problem Definition: Add --json to preset info and extension info

• Slug: info-json-full-expansion
• Created: 2026-08-19
• Inputs used: intake.md | research.md

Problem Statement

Downstream consumers of specify preset info and specify extension info cannot programmatically obtain the fully-normalized, per-contribution detail for a pack (commands, templates, scripts, hooks with strategy, handoffs, runtimes, etc.) because both commands emit only human-readable text. As a result, clients must parse raw YAML files directly and re-implement server-side normalization logic — creating a fragile, drift-prone mirror of the CLI's own data model.

Affected Users & Stakeholders

• Users: Tooling authors (wizard canvas, IDE plugins, pre-commit hooks) who need structured pack detail to render UI, enforce constraints, or feed downstream automation — they currently parse preset.yml/extension.yml directly.
• Stakeholders: Spec Kit CLI maintainers — any change to preset.yml/extension.yml schema silently breaks client-side parsers without the CLI ever raising an error; this creates hidden coupling.

Goals

• specify preset info <id> --json and specify extension info <id> --json emit a single, fully-normalized JSON object with all metadata and expanded per-contribution arrays.
• Strategy shorthand normalization and hook-phase normalization are done server-side in the CLI, not re-implemented in clients.
• Unknown IDs exit non-zero with a JSON-formatted error on stderr.
• The output shape is stable and testable (schema round-trip, normalization tests).

Non-Goals

• Not a replacement for specify artifact info --json (per-artifact cross-pack view vs. per-pack view).
• Not a replacement for specify preset list --json / specify extension list --json (collection summary vs. single-pack detail).
• No other subcommands get --json in this work.
• Architectural redesign of the YAML data model is out of scope.

Success Metrics

• speckit-wizard-canvas can delete parseProvidesEntries and parseHookDeclarations from composition/collect.mjs and replace them with a single specify preset info --json / specify extension info --json call. (qualitative, binary)
• Zero divergence between CLI-reported structure and raw YAML structure for a given pack, verified by round-trip tests. (measurable)
• All four strategy shorthand forms normalize correctly in output. (measurable, testable)

Cost of Inaction

Without this, every new downstream consumer must independently parse and normalize YAML — each accumulates its own version of the same drift risk. When the Spec Kit data model evolves, client-side parsers silently produce wrong data rather than surfacing an error. The js-yaml dependency in speckit-wizard-canvas remains, and the normalization surface grows with each new consumer.

Open Questions

• [NEEDS CLARIFICATION: Are the companion issues (stable id / lookupId, artifact/optional/handoffs) already merged? The id, artifact, optional, and handoffs fields on command entries are blocked on them.]
• [NEEDS CLARIFICATION: Does preset.yml accept shorthand strategy keys (replaces, wraps, etc.) or only canonical longform?]
• [NEEDS CLARIFICATION: Should runtimes be added to preset script entries for parity in this PR, or is it already supported?]

Generated by 💡 Assess a Feature Request by Installing and Running Spec Kit for issue #4213 · 614.8 AIC · ⌖ 12.3 AIC · ⊞ 38K · ◷

[github-actions]

Feature assessment — info-json-full-expansion · Stage 4/5: Concept

Concept: Add --json to preset info and extension info

• Slug: info-json-full-expansion
• Created: 2026-08-19
• Recommended option: Option A — Phased delivery: core JSON now, companion-dependent fields via stubs

Options

Option A — Phased delivery: core JSON now, companion-dependent fields via stubs

• Sketch: Add --json to both commands immediately, emitting all fields that are currently available in the Python data model (metadata, commands with name/description/sourcePath/strategy, templates with strategy, scripts with runtimes, hooks with trigger/targetCommand/sourcePath/priority). Fields that depend on companion issues (id stable scheme, artifact, optional, handoffs) are included as null with a documented note that they are filled by the companion PRs. The JSON contract is versioned so consumers can check completeness. Shorthand normalization ships now (canonical form is already stored in the Python layer). This delivers the primary value — eliminating js-yaml parsing and most of the collect.mjs logic — while unblocking the companions to fill in the remaining fields.
• Appetite: medium (weeks)
• Trade-offs: Wins: immediate value for speckit-wizard-canvas, unblocks companions, establishes the contract early. Sacrifices: consumers see null fields until companions land; the schema has a "v1 incomplete" period.
• Rabbit holes: Defining a stable-enough output shape that companions can fill without breaking the contract. A schema_version field mitigates this.

Option B — Wait for all companion issues before shipping

• Sketch: Do not add --json until stable id / lookupId, artifact/optional/handoffs, and structured source provenance are all merged. Ship the complete shape in one PR.
• Appetite: large (months, depending on companions)
• Trade-offs: Wins: clean, complete contract from day one. Sacrifices: speckit-wizard-canvas keeps js-yaml and client-side normalization for months; other consumers cannot start adopting the output.
• Rabbit holes: Companion timelines are unknown; this could slip indefinitely.

Option C — Minimal metadata-only JSON, no expanded contributions

• Sketch: Add --json but return only top-level metadata (id, name, description, version, author, priority, enabled, source); omit commands, templates, scripts, hooks arrays.
• Appetite: small (days)
• Trade-offs: Wins: trivially easy, low risk. Sacrifices: does not address the primary use case — speckit-wizard-canvas still needs the contribution arrays and still needs js-yaml. Almost no payoff.
• Rabbit holes: None, but no value either.

Recommendation

Option A — phased delivery with null stubs for companion-dependent fields. The primary value (eliminating client-side YAML parsing and normalization re-implementation) is achievable now without the companions. A null stub is better than no field: it signals the contract shape and lets consumers code against it before real values arrive. The shorthand normalization logic is already encoded in the Python layer; exposing it via --json is additive. Shape instability is mitigated by documenting the contract and including a schema_version field.

Out of Scope (for the recommended option)

• specify artifact info --json (companion issue)
• specify preset list --json / specify extension list --json (companion issue)
• Stable-id scheme implementation (companion issue)
• artifact, optional, handoffs fields on command entries (stubs to null here; companion fills them)
• Changes to preset.yml / extension.yml schema

Assumptions to Validate

• Canonical longform strategy values are already stored after YAML parsing and do not require additional shorthand normalization in the --json path.
• The runtimes field can be populated for preset scripts at pack-read time (or is already stored).
• Companion issues will merge within weeks, not quarters, justifying phased over Option B.
• speckit-wizard-canvas is willing to handle null stubs for companion-dependent fields during transition.

Generated by 💡 Assess a Feature Request by Installing and Running Spec Kit for issue #4213 · 614.8 AIC · ⌖ 12.3 AIC · ⊞ 38K · ◷

[github-actions]

Feature assessment — info-json-full-expansion · Stage 5/5: Decision — verdict needs-clarification

Decision: Add --json to preset info and extension info

• Slug: info-json-full-expansion
• Decided: 2026-08-19
• Verdict: needs-clarification
• Artifacts reviewed: intake.md | research.md | problem.md | concept.md

Scorecard

Criterion	Rating	Justification
Problem validity	strong	Real, concrete downstream consumer (speckit-wizard-canvas) is explicitly identified, with named files that must be replaced. The fragility risk is clear and well-argued.
Evidence strength	adequate	The primary consumer is directly cited. Additional use cases (IDE plugins, pre-commit checks) are plausible but unlinked. Companion issue timelines and their merge status are unknown — this is the binding gap.
Value vs. inaction	strong	Without this, every new consumer re-implements server-side normalization; the CLI never surfaces schema drift to clients. Value of building is high; cost of inaction compounds with each new consumer.
Feasibility / appetite	adequate	The core JSON path (metadata + contribution arrays with currently-known fields) is implementable in medium appetite. Companion-dependent fields (id, artifact, optional, handoffs) require a phased approach with stubs, which introduces shape-completeness risk.
Strategic fit	strong	Aligns with the Spec Kit principle that the CLI is the single source of truth for pack metadata. Eliminating client-side YAML parsing is a direct expression of that principle.
Risk posture	adequate	The main risks — companion timeline uncertainty and JSON schema stability — are identified and have credible mitigations (stubs + schema_version). The risk of a breaking shape change is real but manageable.

Verdict & Rationale

needs-clarification — The problem is real, well-evidenced, and strategically aligned; the concept is credible. However, two blocking questions must be answered before a go can be issued:

1. Companion merge status: The JSON shape explicitly depends on companion issues (stable id / lookupId and artifact/optional/handoffs) for the id, artifact, optional, and handoffs fields on command entries. If those companions are already merged, Option A (phased delivery with stubs) is straightforwardly viable. If they are still open, the assessment needs explicit confirmation that the project is comfortable with a null-stub period — or the team reconsiders in favor of Option B (wait for all companions).

2. Shorthand normalization scope: The issue asserts that replaces/wraps/prepends/appends shorthand keys must be normalized server-side. Codebase inspection confirms canonical longform is stored after parsing, but does not confirm whether shorthand is currently accepted as input. If shorthand is accepted today, normalization work is non-trivial; if not, this is simpler.

Evidence strength is adequate (not weak) because the primary consumer is concretely identified and the codebase confirms both the problem and the feasibility of the core path. However, the companion dependency makes a go verdict premature without knowing whether the full shape can be delivered coherently or requires a staged rollout the team must explicitly accept.

If needs-clarification

• Blocking questions:
  • [NEEDS CLARIFICATION: Are the companion issues (stable id / lookupId and artifact/optional/handoffs) already merged or open? If open, what is their expected timeline?]
  • [NEEDS CLARIFICATION: Does the current preset.yml loader accept shorthand strategy keys (replaces, wraps, prepends, appends), or only canonical longform (replace, wrap, prepend, append)?]
• Revisit stage: research (confirm companion status and shorthand scope) → decide

Generated by 💡 Assess a Feature Request by Installing and Running Spec Kit for issue #4213 · 614.8 AIC · ⌖ 12.3 AIC · ⊞ 38K · ◷

[nicolehaugen]

[NEEDS CLARIFICATION: Are the companion issues (stable id / lookupId and artifact/optional/handoffs) already merged or open? If open, what is their expected timeline?] => this is the companion issue mentioned: #4210

[NEEDS CLARIFICATION: Does the current preset.yml loader accept shorthand strategy keys (replaces, wraps, prepends, appends), or only canonical longform (replace, wrap, prepend, append)?] => Short is fine.