Skip to content

Commit d3888fe

Browse files
KevinBrown5280KevinBrown5280
committed
Initial release: spec-kit-spec-reference-loader v1.0.0
Reads ## References from feature specs and loads listed files into LLM context before lifecycle commands.
0 parents  commit d3888fe

5 files changed

Lines changed: 229 additions & 0 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
# Changelog
2+
3+
## [1.0.0] - 2026-04-20
4+
5+
### Added
6+
- Initial release
7+
- `speckit.spec-reference-loader.load` command to parse and load `## References` from feature specs
8+
- `before_*` hooks for plan, tasks, implement, clarify, checklist, and analyze lifecycle commands
9+
- Graceful handling of missing specs, missing references section, and unreadable files

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2026 KevinBrown5280
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md‎

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
# spec-kit-spec-reference-loader
2+
3+
A [Spec Kit](https://github.com/github/spec-kit) extension that reads the `## References` section from the current feature spec and loads the listed files into LLM context. Only fires on commands where the spec already exists.
4+
5+
## Problem
6+
7+
Feature specs often reference external documents — API references, integration guides, decision records — but spec-kit lifecycle commands don't automatically load those files. The LLM agent plans and implements without access to the reference material that the spec author intended to be consulted.
8+
9+
## Solution
10+
11+
The Spec Reference Loader extension parses the `## References` section of the current feature's `spec.md` and loads every listed file into context before lifecycle commands execute.
12+
13+
## Installation
14+
15+
```bash
16+
# From release
17+
specify extension add spec-reference-loader --from \
18+
https://github.com/KevinBrown5280/spec-kit-spec-reference-loader/archive/refs/tags/v1.0.0.zip
19+
20+
# From main branch
21+
specify extension add spec-reference-loader --from \
22+
https://github.com/KevinBrown5280/spec-kit-spec-reference-loader/archive/refs/heads/main.zip
23+
24+
# Development mode (local clone)
25+
specify extension add --dev /path/to/spec-kit-spec-reference-loader
26+
```
27+
28+
## Commands
29+
30+
| Command | Description | Modifies Files? |
31+
|---------|-------------|-----------------|
32+
| `speckit.spec-reference-loader.load` | Load reference docs listed in the feature spec's `## References` section | No — read-only |
33+
34+
## How It Works
35+
36+
1. **Find the spec**: Locates the feature spec at the path provided by the calling context (e.g., `specs/NNN-<feature>/spec.md`). If no spec exists yet, outputs a message and skips.
37+
38+
2. **Parse references**: Reads the spec's `## References` section and extracts file paths from markdown list items:
39+
```markdown
40+
## References
41+
42+
- docs/reference/api-reference.md
43+
- docs/reference/integration-guide.md
44+
```
45+
46+
3. **Load each file**: For each file path found, reads the contents and outputs:
47+
```
48+
## Reference: {filename}
49+
50+
{file contents}
51+
```
52+
53+
4. **Summarize**: After all files, outputs:
54+
```
55+
Spec references loaded: {count} files
56+
```
57+
58+
## Hooks
59+
60+
The extension fires automatically before these lifecycle commands:
61+
62+
| Hook | Command | Description |
63+
|------|---------|-------------|
64+
| `before_plan` | `speckit.spec-reference-loader.load` | Load references before planning |
65+
| `before_tasks` | `speckit.spec-reference-loader.load` | Load references before task generation |
66+
| `before_implement` | `speckit.spec-reference-loader.load` | Load references before implementation |
67+
| `before_clarify` | `speckit.spec-reference-loader.load` | Load references before clarification |
68+
| `before_checklist` | `speckit.spec-reference-loader.load` | Load references before checklist generation |
69+
| `before_analyze` | `speckit.spec-reference-loader.load` | Load references before analysis |
70+
71+
**Does NOT fire on `before_specify`** — the spec doesn't exist yet at that point. A companion memory-loader extension can provide sufficient context for spec authoring.
72+
73+
## Design Decisions
74+
75+
- **Read-only** — never modifies any files
76+
- **Spec-gated** — only fires when a spec already exists; skips silently otherwise
77+
- **Complementary** — handles feature-specific references; pairs well with a memory-loader extension for project governance context
78+
- **Graceful degradation** — missing files or missing `## References` section are handled with warnings, not errors
79+
80+
## Requirements
81+
82+
- Spec Kit >= 0.6.0
83+
84+
## License
85+
86+
MIT

‎commands/speckit.spec-reference-loader.load.md‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
---
2+
description: "Load reference docs listed in the feature spec's ## References section"
3+
---
4+
5+
# Load Spec Reference Docs
6+
7+
Read the current feature's `spec.md`, find the `## References` section, and load every file listed there.
8+
9+
## Steps
10+
11+
1. **Find the spec**: Locate the feature spec at the path provided by the
12+
calling context (e.g., `specs/NNN-<feature>/spec.md`). If no spec exists
13+
yet (e.g., during `/speckit.specify`), output "No spec found — skipping
14+
reference loading." and stop.
15+
16+
2. **Parse references**: Read the spec and find the `## References` section.
17+
Extract every markdown list item that contains a file path. Expected format:
18+
19+
```markdown
20+
## References
21+
22+
- docs/reference/api-reference.md
23+
- docs/reference/integration-guide.md
24+
```
25+
26+
Each line should be a `- path/to/file.md` entry. Ignore blank lines,
27+
comments, and list items that don't look like file paths.
28+
29+
If the `## References` section is missing or empty, output
30+
"No references listed in spec — skipping." and stop.
31+
32+
3. **Load each file**: For each file path found:
33+
- Read the file contents.
34+
- If the file cannot be found or read, output a warning and continue
35+
with the next file.
36+
- Print a headed section:
37+
38+
```
39+
## Reference: {filename}
40+
41+
{file contents}
42+
```
43+
44+
4. **Summarize**: After all files, output:
45+
46+
```
47+
Spec references loaded: {count} files
48+
```
49+
50+
## Usage Notes
51+
52+
- Fires on `before_plan`, `before_tasks`, `before_implement`, `before_clarify`,
53+
`before_checklist`, and `before_analyze` — commands where the spec already exists.
54+
- Does NOT fire on `before_specify` (spec doesn't exist yet). The memory-loader
55+
provides sufficient context for spec authoring.
56+
- Paths are relative to the workspace root.
57+
- This is a read-only operation — do NOT modify any files.

‎extension.yml‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
schema_version: "1.0"
2+
3+
extension:
4+
id: "spec-reference-loader"
5+
name: "Spec Reference Loader"
6+
version: "1.0.0"
7+
description: "Reads the ## References section from the current feature spec and loads the listed files into context"
8+
author: "KevinBrown5280"
9+
repository: "https://github.com/KevinBrown5280/spec-kit-spec-reference-loader"
10+
license: "MIT"
11+
homepage: "https://github.com/KevinBrown5280/spec-kit-spec-reference-loader"
12+
13+
requires:
14+
speckit_version: ">=0.6.0"
15+
16+
provides:
17+
commands:
18+
- name: "speckit.spec-reference-loader.load"
19+
file: "commands/speckit.spec-reference-loader.load.md"
20+
description: "Load reference docs listed in the feature spec's ## References section"
21+
22+
hooks:
23+
before_plan:
24+
command: "speckit.spec-reference-loader.load"
25+
optional: false
26+
description: "Load spec references before planning"
27+
28+
before_tasks:
29+
command: "speckit.spec-reference-loader.load"
30+
optional: false
31+
description: "Load spec references before task generation"
32+
33+
before_implement:
34+
command: "speckit.spec-reference-loader.load"
35+
optional: false
36+
description: "Load spec references before implementation"
37+
38+
before_clarify:
39+
command: "speckit.spec-reference-loader.load"
40+
optional: false
41+
description: "Load spec references before clarification"
42+
43+
before_checklist:
44+
command: "speckit.spec-reference-loader.load"
45+
optional: false
46+
description: "Load spec references before checklist generation"
47+
48+
before_analyze:
49+
command: "speckit.spec-reference-loader.load"
50+
optional: false
51+
description: "Load spec references before analysis"
52+
53+
tags:
54+
- "references"
55+
- "context"
56+
- "docs"

0 commit comments

Comments
 (0)