Harvest Command Guide

Overview

The /devspark.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.

Additionally, /devspark.harvest scans source code for comments that reference completed specs, plans, or tasks — and rewrites them as self-contained code documentation.

/devspark.harvest is the canonical cleanup-and-archival workflow. /devspark.archive now exists only as a deprecated compatibility alias and should not be used in new documentation or examples.

Note: This command modifies files. Use --scope=scan to preview all harvest candidates without making any changes.

Prerequisites

  • A Git repository (recommended; required for accurate branch and merge detection)
  • PowerShell 7+ (for pre-scan script)
  • .documentation/ directory with at least some content to triage

Quick Start

Preview Before Harvesting

/devspark.harvest --scope=scan

Runs the full pre-scan and presents a harvest plan — no files are moved or edited.

Full Harvest

/devspark.harvest

Performs all phases: spec archival, doc cleanup, comment rewriting, CHANGELOG updates, and archival.

Harvest Scopes

Control what the harvest covers using the --scope flag:

Full Harvest (Default)

/devspark.harvest

All phases enabled: specs, docs, comments, and CHANGELOG updates.

Completed Specs Only

/devspark.harvest --scope=specs

Finds specs with all tasks marked [x] in tasks.md, harvests their knowledge into CHANGELOG, then archives the spec folder.

Stale Documentation Only

/devspark.harvest --scope=docs

Triages .documentation/ for completed reviews, stale drafts, session notes, impl plans, backup files, and orphaned assets. Archives eligible files.

Code Comment Cleanup Only

/devspark.harvest --scope=comments

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.

CHANGELOG Update Only

/devspark.harvest --scope=changelog

Adds CHANGELOG entries for completed specs that lack them. No archival.

Scan / Dry Run

/devspark.harvest --scope=scan

Runs the full pre-scan and presents the plan — reads only, no writes.

Combined Scopes

/devspark.harvest --scope=specs,comments

Harvest completed specs and rewrite code comments in one pass.

What Gets Harvested

Spec Completion Criteria

A spec is eligible for harvest when all of the following are true:

Criterion Check
tasks.md exists All tasks marked [x]
No incomplete tasks incomplete_tasks == 0
Work reflected in CHANGELOG Already documented, or added now

Specs with any incomplete tasks are left in place.

Documentation Categories

Category Path Pattern Default Action
Completed PR reviews .documentation/specs/pr-review/*.md Archive
Completed audits .documentation/copilot/audit/*.md Archive
Stale drafts .documentation/drafts/*.md Archive
Session notes .documentation/copilot/session*/ Archive (if merged)
Impl plans (completed) *-implementation-plan.md Archive
Superseded release docs .documentation/releases/ (older versions) Archive
Quickfix records .documentation/quickfixes/ Archive
Backup files *.bak, *.backup, *.old Archive
Living reference Top-level .documentation/*.md, Guide.md Keep / update

Never archived:

  • /.documentation/memory/constitution.md
  • /.documentation/scripts/ and /.documentation/templates/
  • CHANGELOG.md
  • .documentation/Guide.md (updated instead)

Code Comment Patterns Detected

The pre-scan identifies comments matching these patterns across Python, TypeScript, C#, Go, Rust, and JavaScript source files:

Pattern Example Rewrite Action
# spec NNN # spec 026 Phase 5 Rewrite as behavior description
# FR-NNN # FR-013: always send transcript Strip prefix; keep/rewrite description
# T-NNN / # TNNN: # T006: audit trail Rewrite as self-contained comment
# Phase N # Phase 3 implementation Remove or rewrite
# TODO(spec-NNN) # TODO(spec-018): migrate later Remove if spec is complete

Rewrite rule: Replace the spec/task reference with a description of WHAT the code does and WHY — no spec document reference needed.

Understanding Harvest Output

Harvest Report

A harvest report is written to: /.documentation/copilot/harvest-YYYY-MM-DD.md

It contains:

  • Summary counts (specs archived, docs archived, comments rewritten, CHANGELOG entries added)
  • Full table of archived specs with CHANGELOG status
  • Full table of archived docs with destination paths
  • Before/after for every rewritten code comment
  • List of items left in place with reasons

Archive Structure

Archived files are moved to date-stamped folders under .archive/:

.archive/
└── YYYY-MM-DD/
    ├── .documentation/
    │   ├── specs/NNN-completed-spec/
    │   ├── specs/pr-review/
    │   ├── drafts/
    │   └── copilot/

The directory structure mirrors the source tree, preserving full traceability.

Common Workflows

Workflow 1: Post-Release Cleanup

After a release, archive completed specs and their review artifacts:

# Preview what would be archived
/devspark.harvest --scope=scan

# Review the plan, then execute
/devspark.harvest --scope=specs,docs

Workflow 2: Code Comment Cleanup Sprint

Clean up accumulated spec references in source code without moving any files:

# Scan first to see all references
/devspark.harvest --scope=scan

# Then clean just the comments
/devspark.harvest --scope=comments

Workflow 3: CHANGELOG Catch-Up

Add CHANGELOG entries for completed specs that were missed:

/devspark.harvest --scope=changelog

Workflow 4: Quarterly Full Harvest

Regular, comprehensive cleanup at the end of a development cycle:

# 1. Preview everything
/devspark.harvest --scope=scan

# 2. Review and approve the plan
# 3. Execute full harvest
/devspark.harvest

# 4. Run a site audit to confirm health
/devspark.site-audit

Approval Gate

/devspark.harvest always presents a harvest plan before making any changes:

## Harvest Plan — YYYY-MM-DD

### Specs to Archive (N)
| Spec | CHANGELOG? | Action |
...

### Docs to Archive (N)
| File | Category | Action |
...

### Code Comments to Rewrite (N)
| File | Line | Current | Proposed |
...

You must confirm before execution. You can also respond with "modify" to adjust the plan before it runs.

Best Practices

1. Scan Before Every Harvest

Always preview first with --scope=scan. The harvest plan shows exactly what will change — review it carefully before approving.

2. Harvest After Each Release Cycle

Run a full harvest after each release to keep .documentation/ clean and CHANGELOG current.

3. Never Delete — Always Archive

All files go to .archive/YYYY-MM-DD/ — never deleted. Git history is preserved as an additional safety net.

4. Harvest Preserves Knowledge

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.

5. Keep .archive/ Write-Only

Never reference archived files from active prompts, scripts, or documentation. The archive is for audit and traceability only.

Troubleshooting

"harvest.ps1 not found"

Problem: The pre-scan script is missing.

Solution: Run devspark upgrade to install the latest scripts, or copy harvest.ps1 from the source repo's scripts/powershell/ to /.documentation/scripts/powershell/.

"No specs found to harvest"

Problem: No completed specs detected.

Possible causes:

  • Specs don't have a tasks.md, or tasks are not yet all marked [x]
  • Specs are already in .archive/

"Script execution failed"

Problem: PowerShell script cannot execute.

Solutions:

  1. Ensure PowerShell 7+ is installed
  2. Check execution policy: Get-ExecutionPolicy
  3. Run from repository root directory

Harvest archived something it shouldn't have

Solution: Files are in .archive/YYYY-MM-DD/ — move them back with Move-Item. Nothing is deleted.

Integration with Development Workflow

After Feature Work

# When all tasks in a spec are complete and PR is merged
/devspark.harvest --scope=specs

# Clean up any code comments added during development
/devspark.harvest --scope=comments

Before Release

# Ensure CHANGELOG is up to date for all completed specs
/devspark.harvest --scope=changelog

# Then run release workflow
/devspark.release

Regular Maintenance

# Monthly cleanup
/devspark.harvest --scope=docs

# Monitor for accumulated spec comments
/devspark.harvest --scope=comments

Support

If you encounter issues:

Part of DevSpark - Adaptive System Life Cycle Development (ASLCD) Toolkit For more information: https://github.com/MarkHazleton/devspark

Edit this page