Skip to content

Commit 1076b6c

Browse files
markhazletonmarkhazleton
committed
feat: introduce /speckit.harvest command for knowledge preservation and repository cleanup
1 parent 0fe7482 commit 1076b6c

5 files changed

Lines changed: 350 additions & 1 deletion

File tree

‎.documentation/harvest-usage.md‎

Lines changed: 338 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,338 @@
1+
# Harvest Command Guide
2+
3+
## Overview
4+
5+
The `/speckit.harvest` command performs **knowledge-preserving cleanup** of your repository: completed specs, stale documentation, and draft artifacts are triaged and archived, while their valuable content is extracted into living documents (CHANGELOG, Guide.md, copilot-instructions) before anything moves.
6+
7+
Additionally, `/speckit.harvest` scans source code for comments that reference completed specs, plans, or tasks — and rewrites them as self-contained code documentation.
8+
9+
> **Note**: This command modifies files. Use `--scope=scan` to preview all harvest candidates without making any changes.
10+
11+
## Prerequisites
12+
13+
- A Git repository (recommended; required for accurate branch and merge detection)
14+
- PowerShell 7+ (for pre-scan script)
15+
- `.documentation/` directory with at least some content to triage
16+
17+
## Quick Start
18+
19+
### Preview Before Harvesting
20+
21+
```bash
22+
/speckit.harvest --scope=scan
23+
```
24+
25+
Runs the full pre-scan and presents a harvest plan — no files are moved or edited.
26+
27+
### Full Harvest
28+
29+
```bash
30+
/speckit.harvest
31+
```
32+
33+
Performs all phases: spec archival, doc cleanup, comment rewriting, CHANGELOG updates, and archival.
34+
35+
## Harvest Scopes
36+
37+
Control what the harvest covers using the `--scope` flag:
38+
39+
### Full Harvest (Default)
40+
41+
```bash
42+
/speckit.harvest
43+
```
44+
45+
All phases enabled: specs, docs, comments, and CHANGELOG updates.
46+
47+
### Completed Specs Only
48+
49+
```bash
50+
/speckit.harvest --scope=specs
51+
```
52+
53+
Finds specs with all tasks marked `[x]` in `tasks.md`, harvests their knowledge into CHANGELOG, then archives the spec folder.
54+
55+
### Stale Documentation Only
56+
57+
```bash
58+
/speckit.harvest --scope=docs
59+
```
60+
61+
Triages `.documentation/` for completed reviews, stale drafts, session notes, impl plans, backup files, and orphaned assets. Archives eligible files.
62+
63+
### Code Comment Cleanup Only
64+
65+
```bash
66+
/speckit.harvest --scope=comments
67+
```
68+
69+
Finds spec/task references in source code (e.g., `# FR-013`, `# spec 026 Phase 5`, `# T006`) and rewrites them as self-contained behavior descriptions. No file moves.
70+
71+
### CHANGELOG Update Only
72+
73+
```bash
74+
/speckit.harvest --scope=changelog
75+
```
76+
77+
Adds CHANGELOG entries for completed specs that lack them. No archival.
78+
79+
### Scan / Dry Run
80+
81+
```bash
82+
/speckit.harvest --scope=scan
83+
```
84+
85+
Runs the full pre-scan and presents the plan — reads only, no writes.
86+
87+
### Combined Scopes
88+
89+
```bash
90+
/speckit.harvest --scope=specs,comments
91+
```
92+
93+
Harvest completed specs and rewrite code comments in one pass.
94+
95+
## What Gets Harvested
96+
97+
### Spec Completion Criteria
98+
99+
A spec is eligible for harvest when **all** of the following are true:
100+
101+
| Criterion | Check |
102+
|-----------|-------|
103+
| `tasks.md` exists | All tasks marked `[x]` |
104+
| No incomplete tasks | `incomplete_tasks == 0` |
105+
| Work reflected in CHANGELOG | Already documented, or added now |
106+
107+
Specs with any incomplete tasks are left in place.
108+
109+
### Documentation Categories
110+
111+
| Category | Path Pattern | Default Action |
112+
|----------|-------------|----------------|
113+
| Completed PR reviews | `.documentation/specs/pr-review/*.md` | Archive |
114+
| Completed audits | `.documentation/copilot/audit/*.md` | Archive |
115+
| Stale drafts | `.documentation/drafts/*.md` | Archive |
116+
| Session notes | `.documentation/copilot/session*/` | Archive (if merged) |
117+
| Impl plans (completed) | `*-implementation-plan.md` | Archive |
118+
| Superseded release docs | `.documentation/releases/` (older versions) | Archive |
119+
| Quickfix records | `.documentation/quickfixes/` | Archive |
120+
| Backup files | `*.bak`, `*.backup`, `*.old` | Archive |
121+
| **Living reference** | Top-level `.documentation/*.md`, Guide.md | Keep / update |
122+
123+
**Never archived:**
124+
- `/.documentation/memory/constitution.md`
125+
- `/.documentation/scripts/` and `/.documentation/templates/`
126+
- `CHANGELOG.md`
127+
- `.documentation/Guide.md` (updated instead)
128+
129+
### Code Comment Patterns Detected
130+
131+
The pre-scan identifies comments matching these patterns across Python, TypeScript, C#, Go, Rust, and JavaScript source files:
132+
133+
| Pattern | Example | Rewrite Action |
134+
|---------|---------|---------------|
135+
| `# spec NNN` | `# spec 026 Phase 5` | Rewrite as behavior description |
136+
| `# FR-NNN` | `# FR-013: always send transcript` | Strip prefix; keep/rewrite description |
137+
| `# T-NNN` / `# TNNN:` | `# T006: audit trail` | Rewrite as self-contained comment |
138+
| `# Phase N` | `# Phase 3 implementation` | Remove or rewrite |
139+
| `# TODO(spec-NNN)` | `# TODO(spec-018): migrate later` | Remove if spec is complete |
140+
141+
**Rewrite rule**: Replace the spec/task reference with a description of WHAT the code does and WHY — no spec document reference needed.
142+
143+
## Understanding Harvest Output
144+
145+
### Harvest Report
146+
147+
A harvest report is written to: `/.documentation/copilot/harvest-YYYY-MM-DD.md`
148+
149+
It contains:
150+
- Summary counts (specs archived, docs archived, comments rewritten, CHANGELOG entries added)
151+
- Full table of archived specs with CHANGELOG status
152+
- Full table of archived docs with destination paths
153+
- Before/after for every rewritten code comment
154+
- List of items left in place with reasons
155+
156+
### Archive Structure
157+
158+
Archived files are moved to date-stamped folders under `.archive/`:
159+
160+
```
161+
.archive/
162+
└── YYYY-MM-DD/
163+
├── .documentation/
164+
│ ├── specs/NNN-completed-spec/
165+
│ ├── specs/pr-review/
166+
│ ├── drafts/
167+
│ └── copilot/
168+
```
169+
170+
The directory structure mirrors the source tree, preserving full traceability.
171+
172+
## Common Workflows
173+
174+
### Workflow 1: Post-Release Cleanup
175+
176+
After a release, archive completed specs and their review artifacts:
177+
178+
```bash
179+
# Preview what would be archived
180+
/speckit.harvest --scope=scan
181+
182+
# Review the plan, then execute
183+
/speckit.harvest --scope=specs,docs
184+
```
185+
186+
### Workflow 2: Code Comment Cleanup Sprint
187+
188+
Clean up accumulated spec references in source code without moving any files:
189+
190+
```bash
191+
# Scan first to see all references
192+
/speckit.harvest --scope=scan
193+
194+
# Then clean just the comments
195+
/speckit.harvest --scope=comments
196+
```
197+
198+
### Workflow 3: CHANGELOG Catch-Up
199+
200+
Add CHANGELOG entries for completed specs that were missed:
201+
202+
```bash
203+
/speckit.harvest --scope=changelog
204+
```
205+
206+
### Workflow 4: Quarterly Full Harvest
207+
208+
Regular, comprehensive cleanup at the end of a development cycle:
209+
210+
```bash
211+
# 1. Preview everything
212+
/speckit.harvest --scope=scan
213+
214+
# 2. Review and approve the plan
215+
# 3. Execute full harvest
216+
/speckit.harvest
217+
218+
# 4. Run a site audit to confirm health
219+
/speckit.site-audit
220+
```
221+
222+
## Approval Gate
223+
224+
`/speckit.harvest` always presents a **harvest plan** before making any changes:
225+
226+
```markdown
227+
## Harvest Plan — YYYY-MM-DD
228+
229+
### Specs to Archive (N)
230+
| Spec | CHANGELOG? | Action |
231+
...
232+
233+
### Docs to Archive (N)
234+
| File | Category | Action |
235+
...
236+
237+
### Code Comments to Rewrite (N)
238+
| File | Line | Current | Proposed |
239+
...
240+
```
241+
242+
You must confirm before execution. You can also respond with **"modify"** to adjust the plan before it runs.
243+
244+
## Best Practices
245+
246+
### 1. Scan Before Every Harvest
247+
248+
Always preview first with `--scope=scan`. The harvest plan shows exactly what will change — review it carefully before approving.
249+
250+
### 2. Harvest After Each Release Cycle
251+
252+
Run a full harvest after each release to keep `.documentation/` clean and CHANGELOG current.
253+
254+
### 3. Never Delete — Always Archive
255+
256+
All files go to `.archive/YYYY-MM-DD/` — never deleted. Git history is preserved as an additional safety net.
257+
258+
### 4. Harvest Preserves Knowledge
259+
260+
The value of harvest is knowledge extraction, not disk cleanup. If the CHANGELOG or Guide.md wouldn't be enriched by archiving something, reconsider whether to archive it.
261+
262+
### 5. Keep `.archive/` Write-Only
263+
264+
Never reference archived files from active prompts, scripts, or documentation. The archive is for audit and traceability only.
265+
266+
## Troubleshooting
267+
268+
### "harvest.ps1 not found"
269+
270+
**Problem**: The pre-scan script is missing.
271+
272+
**Solution**: Run `specify upgrade` to install the latest scripts, or copy `harvest.ps1` from the source repo's `scripts/powershell/` to `/.documentation/scripts/powershell/`.
273+
274+
### "No specs found to harvest"
275+
276+
**Problem**: No completed specs detected.
277+
278+
**Possible causes**:
279+
- Specs don't have a `tasks.md`, or tasks are not yet all marked `[x]`
280+
- Specs are already in `.archive/`
281+
282+
### "Script execution failed"
283+
284+
**Problem**: PowerShell script cannot execute.
285+
286+
**Solutions**:
287+
288+
1. Ensure PowerShell 7+ is installed
289+
2. Check execution policy: `Get-ExecutionPolicy`
290+
3. Run from repository root directory
291+
292+
### Harvest archived something it shouldn't have
293+
294+
**Solution**: Files are in `.archive/YYYY-MM-DD/` — move them back with `Move-Item`. Nothing is deleted.
295+
296+
## Integration with Development Workflow
297+
298+
### After Feature Work
299+
300+
```bash
301+
# When all tasks in a spec are complete and PR is merged
302+
/speckit.harvest --scope=specs
303+
304+
# Clean up any code comments added during development
305+
/speckit.harvest --scope=comments
306+
```
307+
308+
### Before Release
309+
310+
```bash
311+
# Ensure CHANGELOG is up to date for all completed specs
312+
/speckit.harvest --scope=changelog
313+
314+
# Then run release workflow
315+
/speckit.release
316+
```
317+
318+
### Regular Maintenance
319+
320+
```bash
321+
# Monthly cleanup
322+
/speckit.harvest --scope=docs
323+
324+
# Monitor for accumulated spec comments
325+
/speckit.harvest --scope=comments
326+
```
327+
328+
## Support
329+
330+
If you encounter issues:
331+
332+
- Check [Troubleshooting](#troubleshooting) section above
333+
- Review [Spec Kit Issues](https://github.com/MarkHazleton/spec-kit/issues)
334+
335+
---
336+
337+
*Part of the Spec Kit - Spec-Driven Development Toolkit*
338+
*For more information: <https://github.com/MarkHazleton/spec-kit>*

‎.documentation/index.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,7 @@ Traditional spec-driven development works well for greenfield projects with majo
2121
| Greenfield bias | `/speckit.discover-constitution` generates constitutions from existing code |
2222
| Task overhead | `/speckit.quickfix` provides lightweight workflow for small tasks |
2323
| Documentation drift | `/speckit.release` archives artifacts and maintains living documentation |
24+
| Repo clutter | `/speckit.harvest` consolidates knowledge and archives obsolete artifacts |
2425
| Constitution staleness | `/speckit.evolve-constitution` proposes amendments from PR findings |
2526
| Context management | Right-sized workflows optimize AI agent effectiveness |
2627

@@ -37,6 +38,7 @@ Traditional spec-driven development works well for greenfield projects with majo
3738
| `/speckit.quickfix` | ❌ | ✅ Lightweight workflow |
3839
| `/speckit.release` | ❌ | ✅ Release documentation |
3940
| `/speckit.evolve-constitution` | ❌ | ✅ Constitution evolution |
41+
| `/speckit.harvest` | ❌ | ✅ Knowledge harvest and cleanup |
4042
| Multi-agent support | Limited | ✅ 17+ AI agents |
4143

4244
Learn more: [Adaptive Lifecycle Documentation](adaptive-lifecycle.md)

‎.documentation/toc.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -41,6 +41,8 @@
4141
href: site-audit-usage.md
4242
- name: Critic Guide (Spec Workflow)
4343
href: critic-usage.md
44+
- name: Harvest Guide
45+
href: harvest-usage.md
4446

4547
# About This Fork
4648
- name: About Spec Kit Spark

‎CHANGELOG.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,13 @@ All notable changes to the Specify CLI and templates are documented here.
77
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
88
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
99

10+
## [1.4.0] - 2026-03-25
11+
12+
### Added
13+
14+
- **New `/speckit.harvest` command**: Knowledge-preserving cleanup for completed specs, stale documentation, and spec-linked code comments. The command scans `.documentation/specs/` for all-complete specs, triages `.documentation/` files into archive categories (completed reviews, stale drafts, session notes, impl plans, backup files, orphaned assets), and rewrites source-code comments that reference specs/tasks/FRs as self-contained behavior descriptions. An explicit approval gate presents the full harvest plan before any file is moved or edited. Files are moved to `.archive/YYYY-MM-DD/` (never deleted), and knowledge is extracted into `CHANGELOG.md` and `.documentation/Guide.md` before archival. Output: `/.documentation/copilot/harvest-YYYY-MM-DD.md`.
15+
- **`harvest.ps1` pre-scan script**: PowerShell context-gathering script (`scripts/powershell/harvest.ps1`) installed to `/.documentation/scripts/powershell/harvest.ps1` in consumer projects. Outputs JSON with spec completion status (completed/completed-needs-changelog/in-progress/draft), doc taxonomy scores, disposition recommendations, code comment hits, CHANGELOG gap analysis, and existing archive inventory. Supports `-Scope` (`full`, `specs`, `docs`, `comments`, `changelog`, `scan`) and `-Json` flags. Language-agnostic comment scanning covers Python, TypeScript, JavaScript, C#, Go, and Rust.
16+
1017
## [1.3.0] - 2026-03-19
1118

1219
### Fixed

‎pyproject.toml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
[project]
22
name = "specify-cli"
3-
version = "1.3.0"
3+
version = "1.4.0"
44
description = "Specify CLI, part of Spec Kit Spark. A community extension with constitution-powered commands for Spec-Driven Development (SDD)."
55
requires-python = ">=3.11"
66
dependencies = [

0 commit comments

Comments
 (0)