[Feature]: Add specify artifact command exposing composition stacks as JSON

[nicolehaugen]

Problem Statement

PresetResolver.collect_all_layers() (presets/__init__.py:5460) and resolve_content() (presets/__init__.py:5688) already implement the composition math needed to expose an artifact's layer stack — ordered layer stack, per-layer strategy, winner selection, and shadowing — but nothing serializes it. speckit-wizard-canvas resorts to shelling specify preset resolve <id> and parsing text output one line at a time (composition/collect.mjs::batchResolveTemplates), and re-implements strategy resolution and shadowing itself in composition/assembler.mjs (~23 KB). The wizard's own header comment on composition/collect.mjs says:

"Once the CLI grows equivalent commands (e.g. specify composition list --json), this whole file goes away and the scanner calls those commands directly."

This is a direct in-code TODO for this issue.

Proposed Solution

Add a new specify artifact command group:

• specify artifact list --json — every artifact SpecKit knows about (commands, templates, scripts), one row each:

  { "id": "…", "name": "speckit.constitution", "kind": "command",
    "description": "…" }

• specify artifact info <name> --json — the full stack for one artifact:

  {
    "id": "…", "name": "speckit.constitution", "kind": "command",
    "description": "…",
    "stack": [
      { "layer": "preset", "presetId": "speckit.corp",
        "presetName": "Corp Preset",
        "strategy": "wrap", "active": true, "hidden": false,
        "manifestPath": ".specify/presets/speckit.corp/preset.yml",
        "lookupId": "preset:speckit.corp:command:speckit.constitution" },
      { "layer": "preset", "presetId": "speckit.core", "…": "…",
        "strategy": "replace", "active": false, "hidden": true },
      { "layer": "core", "presetId": null, "presetName": null,
        "strategy": "replace", "active": false, "hidden": true,
        "manifestPath": null,
        "lookupId": "core:_:command:speckit.constitution" }
    ]
  }

Stack rules:

• Ordered highest-priority-first (matches collect_all_layers today).
• Exactly one layer has active: true (the winner from resolve_content).
• Layers below a higher-priority replace get hidden: true (they stay in the stack for provenance/debug).
• Each stack ends with a layer: "core" row when SpecKit ships a baseline version of that artifact (folds the baseline into every stack view without needing a separate scan).
• lookupId uses the stable-id scheme from the companion "stable id / lookupId" issue so a UI can hop from the stack row to the full per-contribution detail from the preset info --json / extension info --json issue.

Implementation: wrap the existing collect_all_layers + resolve_content output; add a small enumerator for core baseline artifacts (command names come from CORE_COMMAND_NAMES at extensions/__init__.py:119; templates/scripts are enumerated via a frontmatter parser over the shipped .md/.sh/.ps1/.py files, reusing the existing _locate_core_pack() / _repo_root() canonical asset resolvers).

Alternatives Considered

• Extend specify preset resolve <id> with --json. Rejected — that command answers "which file wins?", not "what does the stack look like?" Consumers would still have to compose multiple calls.
• Fold the core inventory into a separate specify core list --json. Rejected as the primary surface — same data, splits consumers. Filed as a separate specify core inventory issue for the inventory case where a UI wants the baseline without walking every artifact stack.
• Include the resolved content in info --json. Rejected — content can be large; a separate artifact resolve (already exists as preset resolve) covers that.

Component

Specify CLI (initialization, commands)

AI Agent (if applicable)

Not applicable

Use Cases

1. speckit-wizard-canvas deletes composition/assembler.mjs and composition/collect.mjs::batchResolveTemplates, calling specify artifact info <name> --json for each artifact it needs to render.
2. A debugger renders "why is my speckit.plan command not what I expect?" by walking the stack — the answer is the active: true row's presetId and strategy.
3. A CI diff shows "before/after" of the artifact stack when a preset is added or its priority changes.

Acceptance Criteria

• specify artifact list --json emits one row per artifact with id, name, kind (command|template|script), description.
• specify artifact info <name> --json emits {id, name, kind, description, stack: [...]} where every stack entry has layer, presetId/presetName (or null for core), strategy, active, hidden, manifestPath, lookupId.
• Exactly one stack entry has active: true; entries shadowed by a higher-priority replace have hidden: true.
• Core baseline appears as a layer: "core" row at the bottom of every stack whose artifact ships with SpecKit itself.
• lookupId values conform to the stable-id scheme and match the id values returned by the companion preset info --json / extension info --json issue.
• Every stack row with layer: "extension" has strategy: "replace" (invariant already enforced at extensions/__init__.py:622-626, where any strategy key on an extension provides entry raises ValidationError).
• Error handling: unknown artifact name → non-zero exit, stderr JSON {"error": "unknown artifact <name>"}.
• Tests: composition parity against resolve_content (winner matches), shadow flag correctness, core-layer presence for baseline artifacts, absence for extension-only artifacts, lookupId round-trip with the companion info --json output.
• Docs: new specify artifact section in the CLI reference with the full JSON shape and stack semantics.

Additional Context

Direct replacement for plugins/spec-kit-copilot-wizard/extensions/speckit-wizard-canvas/composition/assembler.mjs and composition/collect.mjs::batchResolveTemplates in github/spec-kit-copilot. Depends on the companion "stable id / lookupId" issue (for lookupId); benefits from the companion "structured source provenance" issue (source on layer rows) once available.

Scope note (out of scope). A separate WorkflowResolver exists in src/specify_cli/workflows/overlays/__init__.py with its own collect_all_layers() for .specify/workflows/overlays/* composition. That is a distinct system from preset artifact composition and is not covered by this issue — this issue is scoped to commands, templates, and scripts. A future specify workflow composition view would be a separate issue against the workflow resolver.

[github-actions]

Feature assessment — artifact-composition-api · Stage 1/5: Intake

Idea Intake: Add specify artifact command exposing composition stacks as JSON

• Slug: artifact-composition-api
• Created: 2026-08-19
• Source: GitHub issue [Feature]: Add specify artifact command exposing composition stacks as JSON #4212 (github/spec-kit), raised by @nicolehaugen
• Type: new-capability

Idea (as captured)

PresetResolver.collect_all_layers() and resolve_content() already implement the composition math needed to expose an artifact's layer stack — but nothing serializes it. speckit-wizard-canvas resorts to shelling specify preset resolve and parsing text output one line at a time, and re-implements strategy resolution and shadowing itself in composition/assembler.mjs (~23 KB). The wizard's own header comment says: "Once the CLI grows equivalent commands (e.g. specify composition list --json), this whole file goes away."

Proposed: a new specify artifact command group with:

• specify artifact list --json — every artifact SpecKit knows about (commands, templates, scripts), one row each
• specify artifact info <name> --json — the full layer stack for one artifact: id, name, kind, description, plus a stack array where each entry has layer, presetId/presetName, strategy, active, hidden, manifestPath, lookupId

Restated

Add a specify artifact CLI command group that wraps the existing PresetResolver.collect_all_layers() and resolve_content() internals to expose composition stacks as structured JSON, eliminating the need for consumers like speckit-wizard-canvas to shell-parse text output or re-implement composition logic.

Origin & Context

• Raised by: @nicolehaugen
• Trigger: speckit-wizard-canvas (in github/spec-kit-copilot) re-implements ~23 KB of composition logic that already exists in the CLI; the wizard's source even contains a TODO comment calling for this exact CLI surface. A companion "stable id / lookupId" issue exists for the lookupId scheme the stack rows would reference.

First-Glance Unknowns

• [NEEDS CLARIFICATION: What is the stable id / lookupId scheme from the companion issue? The lookupId format is described in the issue body but depends on a companion spec not yet linked.]
• [NEEDS CLARIFICATION: Does specify artifact list enumerate only installed/active artifacts, or all artifacts that exist across all presets (including shadowed ones)?]
• [NEEDS CLARIFICATION: What is the exact scope of "core baseline artifacts" — does CORE_COMMAND_NAMES cover all three artifact kinds (commands, templates, scripts), or only commands?]
• [NEEDS CLARIFICATION: Is there an existing specify preset resolve command this partially overlaps with, and how should the two commands relate in user-facing docs?]

Generated by 💡 Assess a Feature Request by Installing and Running Spec Kit for issue #4212 · 463.3 AIC · ⌖ 41.2 AIC · ⊞ 38.1K · ◷

[github-actions]

Feature assessment — artifact-composition-api · Stage 2/5: Research

Idea Research: Add specify artifact command exposing composition stacks as JSON

• Slug: artifact-composition-api
• Created: 2026-08-19
• Evidence confidence (overall): high

Users & Demand

• speckit-wizard-canvas maintainers need machine-readable composition data; the wizard's composition/assembler.mjs (~23 KB) and composition/collect.mjs::batchResolveTemplates re-implement layer resolution and strategy shadowing that already exists in the CLI. — [source: issue [Feature]: Add specify artifact command exposing composition stacks as JSON #4212 body, @nicolehaugen] (confidence: high, cited)
• The in-code TODO comment "Once the CLI grows equivalent commands (e.g. specify composition list --json), this whole file goes away" in composition/collect.mjs is a direct developer request baked into the source. — [source: issue [Feature]: Add specify artifact command exposing composition stacks as JSON #4212] (confidence: high, cited)
• Debuggers/operators need to answer "why is my command not what I expect?" — the stack view shows which preset and strategy won. — [source: issue [Feature]: Add specify artifact command exposing composition stacks as JSON #4212 use cases] (confidence: medium, cited)
• CI diff tools need before/after stack snapshots when preset priority changes. — [source: issue [Feature]: Add specify artifact command exposing composition stacks as JSON #4212 use cases] (confidence: medium, cited)

Prior Art

• specify preset resolve <name> already exists (confirmed via specify preset --help) and answers "which file wins?" — but only outputs a file path, not the full stack with all layers, strategies, and shadowing. — [source: codebase] (confidence: high, cited)
• PresetResolver.collect_all_layers() (presets/init.py:5460) and resolve_content() (presets/init.py:5688) implement the full composition math including priority ordering, strategy (replace/prepend/append/wrap), and winner selection. Both are internal Python methods, not exposed as JSON CLI output. — [source: codebase] (confidence: high, cited)
• WorkflowResolver.collect_all_layers() (workflows/overlays/init.py:47) is a parallel implementation for overlay workflows, explicitly out of scope. — [source: codebase + issue [Feature]: Add specify artifact command exposing composition stacks as JSON #4212 scope note] (confidence: high, cited)
• CORE_COMMAND_NAMES (extensions/init.py:119) enumerates 10 core commands (analyze, checklist, clarify, constitution, converge, implement, plan, specify, tasks, taskstoissues), discoverable from templates/commands/*.md. Templates (5 .md files) and scripts are also present under templates/ but not covered by CORE_COMMAND_NAMES. — [source: codebase] (confidence: high, cited)
• No existing specify artifact command group found in the CLI. The commands subpackage contains only __init__.py, bundle/, event.py, and init.py. — [source: codebase] (confidence: high, cited)

Market & Context

• JSON output flags (--json) on CLI inventory commands are standard practice in developer tools (GitHub CLI gh issue list --json, npm list --json, cargo metadata). Users expect them. — [source: ASSUMPTION] (confidence: medium)
• The issue explicitly notes specify preset resolve <name> is insufficient; the gap forces consumers to either make N calls or re-implement composition logic in their own code. — [source: issue [Feature]: Add specify artifact command exposing composition stacks as JSON #4212 alternatives] (confidence: high, cited)

Data & Constraints

• PresetResolver.collect_all_layers() returns layers with keys path, source, strategy; the proposed JSON adds presetId, presetName, active, hidden, manifestPath, lookupId. This is additive over existing internal data. — [source: codebase] (confidence: high, cited)
• The lookupId scheme depends on a companion "stable id / lookupId" issue that is referenced but not linked in [Feature]: Add specify artifact command exposing composition stacks as JSON #4212. The format is described inline in the issue body, but a formal spec may not yet exist in the codebase. — [NEEDS CLARIFICATION: link or content of the companion stable-id issue] (confidence: low for this sub-item)
• Core artifact enumeration for templates and scripts must use _locate_core_pack() / _repo_root() resolvers; these are already used by PresetResolver and _load_core_command_names(). — [source: codebase] (confidence: high, cited)

Evidence Against the Idea

• Dependency on an unfinished companion spec: the lookupId field requires a stable-id scheme from a companion issue. If that issue is blocked, the lookupId field cannot be fully validated or round-trip tested, weakening one acceptance criterion. This is a sequencing risk, not a fundamental objection.
• specify preset resolve partial overlap: documentation must clearly differentiate preset resolve ("which file wins?") from artifact info ("what is the full stack?") to avoid user confusion.
• Schema growth risk: the JSON shape has many fields per stack row; if the companion source provenance issue adds more fields, the schema may drift quickly.

Gaps & Open Questions

• [NEEDS CLARIFICATION: What is the companion "stable id / lookupId" issue number/link? Is the scheme already implemented anywhere in the codebase?]
• [NEEDS CLARIFICATION: Does specify artifact list enumerate only currently-active artifacts, or all artifacts across all installed presets/extensions?]
• [NEEDS CLARIFICATION: Is layer: "extension" a valid stack value? The issue body shows layer: "preset" and layer: "core", but acceptance criteria mention extension layers.]

Sources

• Issue [Feature]: Add specify artifact command exposing composition stacks as JSON #4212 body (github.com, policy: allowlisted)
• src/specify_cli/presets/__init__.py lines 5460–5760 (codebase)
• src/specify_cli/extensions/__init__.py lines 48–119 (codebase)
• templates/commands/ directory listing (codebase)
• specify preset --help output (codebase)
• src/specify_cli/workflows/overlays/__init__.py (codebase)

Generated by 💡 Assess a Feature Request by Installing and Running Spec Kit for issue #4212 · 463.3 AIC · ⌖ 41.2 AIC · ⊞ 38.1K · ◷

[github-actions]

Feature assessment — artifact-composition-api · Stage 3/5: Problem

Problem Definition: Add specify artifact command exposing composition stacks as JSON

• Slug: artifact-composition-api
• Created: 2026-08-19
• Inputs used: intake.md | research.md

Problem Statement

Consumers of the Specify CLI — such as speckit-wizard-canvas — cannot obtain machine-readable composition stack data (layer order, strategy, winner selection, shadowing) for a given artifact without shelling out to text-format CLI commands and re-implementing composition logic themselves, because PresetResolver's full layer stack is only available as an internal Python API. This forces duplication of ~23 KB of composition code in downstream tools, with the risk of divergence when the CLI's resolution logic changes.

Affected Users & Stakeholders

• Users: speckit-wizard-canvas developers (github/spec-kit-copilot) — must maintain a ~23 KB parallel implementation of composition logic that they explicitly want to delete once the CLI exposes an equivalent command.
• Users: Spec Kit plugin/extension authors who build tooling on top of composition — need a stable JSON contract to reason about artifact precedence.
• Users: Operators debugging "why is my command not what I expect?" — need a stack view showing which layer is active and why.
• Users: CI/CD pipeline authors — need a before/after stack diff when presets change priority.
• Stakeholders: Spec Kit maintainers — duplication in speckit-wizard-canvas is a maintenance liability; any change to PresetResolver must be mirrored in the wizard's composition code or bugs emerge silently.

Goals

• Expose a stable JSON representation of the full artifact layer stack via a new specify artifact CLI command group.
• Allow consumers to enumerate all artifacts (artifact list --json) and inspect the full stack for any artifact (artifact info <name> --json) without re-implementing composition math.
• Allow speckit-wizard-canvas to delete its ~23 KB of composition re-implementation and call the CLI directly.

Non-Goals

• Exposing the resolved content of artifacts as part of the stack (that is preset resolve, which already exists).
• Covering workflow overlay composition (WorkflowResolver — a separate system, separate future issue).
• Automatically migrating or changing existing presets or integrations.
• Producing a design, architecture, or API specification here.

Success Metrics

• speckit-wizard-canvas deletes composition/assembler.mjs and composition/collect.mjs::batchResolveTemplates after adopting specify artifact info --json (baseline: both files exist today, ~23 KB of duplicated logic).
• Zero divergence bugs between specify artifact info stack output and PresetResolver.resolve_content() winner — verified by parity tests (baseline: no parity test exists today).
• specify artifact list --json and artifact info --json parse successfully with JSON consumers (baseline: no JSON artifact output exists today).

Cost of Inaction

Without this command, speckit-wizard-canvas continues maintaining ~23 KB of composition logic that must be manually kept in sync with PresetResolver. Every future change to composition strategy semantics, preset priority, or layer ordering in the CLI requires a corresponding update to the wizard's code — a silent divergence risk. The wizard's own source already documents this as known debt ("this whole file goes away").

Open Questions

• [NEEDS CLARIFICATION: Is the companion "stable id / lookupId" issue implemented or blocked? If blocked, lookupId may need to be deferred or delivered as a partial stub.]
• [NEEDS CLARIFICATION: Should specify artifact list include artifacts only from installed presets/extensions, or also enumerate the core baseline when no presets are installed?]
• [NEEDS CLARIFICATION: Is layer: "extension" a first-class value in the stack (the acceptance criteria mention it, the JSON examples in the issue do not)?]

Generated by 💡 Assess a Feature Request by Installing and Running Spec Kit for issue #4212 · 463.3 AIC · ⌖ 41.2 AIC · ⊞ 38.1K · ◷

[github-actions]

Feature assessment — artifact-composition-api · Stage 4/5: Concept

Concept: Add specify artifact command exposing composition stacks as JSON

• Slug: artifact-composition-api
• Created: 2026-08-19
• Recommended option: Option A — Thin JSON wrapper over existing PresetResolver

Options

Option A — Thin JSON wrapper over existing PresetResolver

• Sketch: Add a specify artifact sub-command group with two commands: list --json (enumerate all artifacts the resolver can see) and info <name> --json (return the full layer stack for one artifact). Both commands call the existing PresetResolver.collect_all_layers() and map its internal dict representation to the proposed JSON shape. The active and hidden flags are computed the same way resolve_content() selects the winner. Core baseline artifacts are folded in via CORE_COMMAND_NAMES / _locate_core_pack(). The lookupId field is generated from the described format (preset:<presetId>:<kind>:<name>, core:_:<kind>:<name>) without requiring the companion issue to ship first.
• Appetite: medium (weeks) — the math is already implemented; the work is adding the CLI surface, enumeration of core templates/scripts, and parity tests.
• Trade-offs: wins — minimal new logic, high fidelity (cannot diverge from the resolver), directly deletes the wizard's composition files; sacrifices — lookupId format may need revision when the companion stable-id issue ships.
• Rabbit holes: Core template/script enumeration (templates and scripts are not covered by CORE_COMMAND_NAMES; need a scanner using _locate_core_pack() / _repo_root() for all three kinds); schema stability for lookupId before the companion issue is merged; ensuring --json output is machine-stable.

Option B — Extend specify preset resolve with --json and stack output

• Sketch: Add --json and --stack flags to the existing specify preset resolve <name> command. Avoids a new command group but retrofits the shape onto an existing command with a different primary purpose.
• Appetite: small (days) — smaller surface but incomplete.
• Trade-offs: wins — no new top-level command; sacrifices — does not address artifact list; conflates two distinct queries; semantically confusing; explicitly rejected in the issue.
• Rabbit holes: Users still need a second command for enumeration, defeating the design goal.

Option C — Defer until companion stable-id issue ships

• Sketch: Block the entire specify artifact command on the companion "stable id / lookupId" issue being finalized and merged.
• Appetite: unknown (blocked on external issue).
• Trade-offs: wins — lookupId is correct from day one; sacrifices — the wizard continues carrying ~23 KB of duplication indefinitely.
• Rabbit holes: Waiting for the companion could be indefinite; the wizard's TODO is already documented maintenance debt.

Recommendation

Option A: deliver the thin JSON wrapper now, generating lookupId from the inline format described in the issue. Mark lookupId in docs as "provisional — subject to alignment with the companion stable-id issue." This eliminates the maintenance debt immediately and leaves lookupId format revision as a non-breaking follow-on.

Out of Scope (for the recommended option)

• Workflow overlay composition (WorkflowResolver) — separate issue
• Resolved artifact content in the stack response — use preset resolve for that
• Companion stable-id issue implementation — referenced, not blocked on
• Any changes to PresetResolver internals beyond serialization

Assumptions to Validate

• lookupId format described in the issue body is sufficiently stable to ship as "provisional" without the companion spec.
• Core templates and scripts can be reliably enumerated via _locate_core_pack() / _repo_root() analogously to how CORE_COMMAND_NAMES works today.
• The active/hidden flag computation from collect_all_layers() + winner selection is the correct semantic.

Generated by 💡 Assess a Feature Request by Installing and Running Spec Kit for issue #4212 · 463.3 AIC · ⌖ 41.2 AIC · ⊞ 38.1K · ◷

[github-actions]

Feature assessment — artifact-composition-api · Stage 5/5: Decision — verdict go

Decision: Add specify artifact command exposing composition stacks as JSON

• Slug: artifact-composition-api
• Decided: 2026-08-19
• Verdict: go
• Artifacts reviewed: intake.md | research.md | problem.md | concept.md

Scorecard

Criterion	Rating	Justification
Problem validity	strong	The problem is real, documented in-code (wizard TODO), and affects a known consumer (speckit-wizard-canvas) with ~23 KB of duplicated composition logic.
Evidence strength	adequate	Direct in-code TODO, cited issue body, codebase grep confirming the gap; lookupId companion spec is unlinked but the core problem and proposed JSON shape are well-evidenced.
Value vs. inaction	strong	Inaction leaves the wizard maintaining ~23 KB of parallel composition code with silent divergence risk; acting allows deletion of that code. Asymmetric benefit.
Feasibility / appetite	strong	PresetResolver.collect_all_layers() and resolve_content() already implement the required math; the work is serialization, CLI wiring, and parity tests — medium appetite with no novel algorithm.
Strategic fit	strong	Directly supports the spec-kit-copilot wizard, a first-party consumer. Adds a stable JSON contract that benefits any tooling built on Spec Kit. Consistent with the existing --json pattern expected in CLI tools.
Risk posture	adequate	Primary risk is lookupId format revision when the companion stable-id issue ships; mitigated by shipping the field as "provisional." Rabbit hole (core template/script enumeration) is bounded and uses existing resolvers. No novel security or performance risks.

Verdict & Rationale

go. The problem is valid, well-evidenced, and affects a real first-party consumer. The implementation path is clear: wrap the already-correct PresetResolver.collect_all_layers() in a new specify artifact CLI command group, compute active/hidden flags from resolve_content() winner logic, and enumerate core artifacts via _locate_core_pack() / _repo_root(). Evidence strength is adequate (not weak): the gap between internal API and CLI surface is confirmed by codebase inspection, and the wizard's in-code TODO provides direct demand signal. The only open uncertainty is the lookupId companion spec, which is a contained, non-blocking risk — the field can be shipped as provisional and revised non-breakingly. Option A (thin wrapper) is the correct scope.

Handoff to /speckit-specify

• Problem: CLI consumers cannot obtain machine-readable composition stack data without re-implementing PresetResolver internals; speckit-wizard-canvas carries ~23 KB of duplicated composition logic as a result.
• Chosen approach: Option A — thin JSON wrapper over existing PresetResolver.collect_all_layers() + resolve_content(). New specify artifact command group with list --json and info <name> --json. Core baseline artifacts folded in via _locate_core_pack() / _repo_root(). lookupId generated from inline-described format, marked provisional.
• In scope: specify artifact list --json, specify artifact info <name> --json, all three artifact kinds (command/template/script), active/hidden flag semantics, core baseline as layer: "core", error handling for unknown artifact names, parity tests against resolve_content(), CLI docs update.
• Out of scope: workflow overlay composition, resolved artifact content in stack response, companion stable-id spec implementation.
• Success metrics: speckit-wizard-canvas deletes its composition files; parity tests pass; --json output is jq-parseable.
• Carried-forward open questions:
  • [NEEDS CLARIFICATION: companion stable-id / lookupId issue number and status — determine whether to ship lookupId as provisional or defer the field.]
  • [NEEDS CLARIFICATION: Is layer: "extension" a valid stack value? Acceptance criteria mention it; the issue's JSON examples do not include it.]
  • [NEEDS CLARIFICATION: Does specify artifact list enumerate artifacts only visible given installed presets, or also core artifacts regardless of preset state?]

Generated by 💡 Assess a Feature Request by Installing and Running Spec Kit for issue #4212 · 463.3 AIC · ⌖ 41.2 AIC · ⊞ 38.1K · ◷