Spec Kit: from testable intent to traceable acceptance
Spec Kit architecture: artifact intent, template precedence and installed commands
Trace how durable feature artifacts differ from runtime template resolution and integration-specific command files.
What you will learn
- Separate product intent from workflow instructions
- Template selection and command installation happen at different times
- Choose extension, preset or bundle by responsibility
Before you start
- Basic requirements, Git and testing concepts
- Understanding of local development versus application deployment
Trace a small feature from intent to evidence and distinguish workflow contracts from verified behavior.
Key takeaways
- Feature intent and workflow templates are different layers.
- Runtime template selection differs from installed command files.
- Effective configuration matters more than the mere presence of a package.
Separate product intent from workflow instructions
The feature’s spec, plan and tasks describe the thing being built. Templates and agent commands describe how that material is produced and assessed. A project constitution supplies governing constraints. Mixing these layers makes troubleshooting difficult: changing a template does not retroactively validate existing feature specifications.
For example, a privacy requirement belongs in the feature’s intent and relevant project principles. A preset can require a privacy section in future artifacts, but the presence of that section alone does not enforce the runtime behavior. Review both the document content and the implementation it requires.
Template selection and command installation happen at different times
The README presents a precedence stack: project-local overrides, presets, extensions and core templates. It says templates are resolved at runtime, while extension and preset command files are applied to agent directories at installation time. These mechanisms explain why editing one file may not change the command you see in an already initialized integration.
Do not infer the complete composition algorithm from that summary alone. The inspected Python resolver entry point delegates content resolution to common helpers. It handles returned content and errors; we did not execute or audit the full precedence and composition implementation in this review.
Choose extension, preset or bundle by responsibility
Extensions add capabilities, presets customize existing instructions and formats, and bundles package a selected component set for a role. A project-local override can serve a narrow single-project adjustment. More layers increase the need to record the effective configuration and the origin of the instructions being followed.
When diagnosing a surprising result, identify the artifact being generated, the effective template source, the installed command and the selected integration before changing anything. A newer core template does not necessarily win over a deliberate local override, and reinstalling blindly can obscure the actual cause.
Decision guide
| Criterion | Option A | Option B |
|---|---|---|
| Best when | You need predictable behavior and easy auditing | You need adaptive optimization and have reliable telemetry |
| Main risk | May leave performance on the table | Can become difficult to explain or debug |
Implementation steps
- 1
Locate the feature artifact and its governing constraints.
- 2
Identify overrides and installed customization components.
- 3
Inspect the integration’s effective command.
- 4
Record the source of the template actually used.
Copy-ready example
{
"diagnostic": true,
"featureArtifact": "spec.md",
"documentedPriority": [
"project-local",
"presets",
"extensions",
"core"
],
"effectiveSource": null,
"commandRefreshChecked": false,
"fullResolverTested": false
}Frequently asked questions
Does editing a core template always change the result?
Not necessarily; a higher-priority override may be active.
Did this review test the full template resolver?
No. It inspected the entry point and README contract, not the full composition engine.
Sources
- Spec Kit / README.mdSource checked 2026-09-14
- Spec Kit / scripts/python/resolve_template.pySource checked 2026-09-14
- Spec Kit / templates/commands/converge.mdSource checked 2026-09-14