Skip to content

Commit 7f272c2

Browse files
dsrednickidsrednicki
committed
refactor: migrate cleanup command to extension system
- Move /speckit.cleanup from core templates to extensions/cleanup/ - Follow spec-kit extension mechanism with proper manifest (extension.yml) - Register command as speckit.cleanup.run with alias speckit.cleanup - Add after_implement hook for automatic cleanup prompting - Update README.md to document cleanup as extension command - Update catalog.json with cleanup extension entry - Add LICENSE, CHANGELOG.md, README.md, .gitignore for extension BREAKING CHANGE: /speckit.cleanup now requires extension installation: specify extension add cleanup
1 parent 34665bb commit 7f272c2

File tree

10 files changed

+257
-20
lines changed

10 files changed

+257
-20
lines changed

‎README.md‎

Lines changed: 20 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -132,11 +132,15 @@ Use **`/speckit.implement`** to execute all tasks and build your feature accordi
132132
/speckit.implement
133133
```
134134

135-
### 7. Review and clean up
135+
### 7. Review and clean up (Extension)
136136

137-
Use **`/speckit.cleanup`** to review all implementation changes, identify tech debt, and ensure code quality.
137+
Install and use the **cleanup extension** to review all implementation changes, identify tech debt, and ensure code quality.
138138

139139
```bash
140+
# Install the cleanup extension
141+
specify extension add cleanup
142+
143+
# Run cleanup
140144
/speckit.cleanup
141145
```
142146

@@ -266,7 +270,14 @@ Essential commands for the Spec-Driven Development workflow:
266270
| `/speckit.plan` | Create technical implementation plans with your chosen tech stack |
267271
| `/speckit.tasks` | Generate actionable task lists for implementation |
268272
| `/speckit.implement` | Execute all tasks to build the feature according to the plan |
269-
| `/speckit.cleanup` | Review implementation, fix small issues, identify tech debt |
273+
274+
#### Extension Commands
275+
276+
Commands provided by optional extensions:
277+
278+
| Command | Extension | Description |
279+
| ----------------------- | --------- | ------------------------------------------------------------------------ |
280+
| `/speckit.cleanup` | cleanup | Review implementation, fix small issues, identify tech debt |
270281

271282
#### Optional Commands
272283

@@ -623,11 +634,15 @@ The `/speckit.implement` command will:
623634
624635
Once the implementation is complete, test the application and resolve any runtime errors that may not be visible in CLI logs (e.g., browser console errors). You can copy and paste such errors back to your AI agent for resolution.
625636

626-
### **STEP 8:** Clean up and review
637+
### **STEP 8:** Clean up and review (Extension)
627638

628-
After implementation is complete, use the `/speckit.cleanup` command to perform a final quality review:
639+
After implementation is complete, install and use the cleanup extension to perform a final quality review:
629640

630641
```text
642+
# Install the cleanup extension first
643+
specify extension add cleanup
644+
645+
# Run cleanup
631646
/speckit.cleanup
632647
```
633648

‎extensions/catalog.json‎

Lines changed: 28 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,32 @@
11
{
22
"schema_version": "1.0",
3-
"updated_at": "2026-02-03T00:00:00Z",
3+
"updated_at": "2026-02-20T00:00:00Z",
44
"catalog_url": "https://raw.githubusercontent.com/github/spec-kit/main/extensions/catalog.json",
5-
"extensions": {}
5+
"extensions": {
6+
"cleanup": {
7+
"name": "Cleanup",
8+
"id": "cleanup",
9+
"description": "Post-implementation quality gate that reviews changes, fixes small issues (scout rule), creates tasks for medium issues, and generates analysis for large issues.",
10+
"author": "Spec Kit Contributors",
11+
"version": "1.0.0",
12+
"download_url": "https://github.com/github/spec-kit/archive/refs/heads/main.zip",
13+
"repository": "https://github.com/github/spec-kit",
14+
"homepage": "https://github.com/github/spec-kit/tree/main/extensions/cleanup",
15+
"documentation": "https://github.com/github/spec-kit/tree/main/extensions/cleanup/README.md",
16+
"license": "MIT",
17+
"requires": {
18+
"speckit_version": ">=0.1.0"
19+
},
20+
"provides": {
21+
"commands": 1,
22+
"hooks": 1
23+
},
24+
"tags": ["quality", "tech-debt", "review", "cleanup", "scout-rule"],
25+
"verified": true,
26+
"downloads": 0,
27+
"stars": 0,
28+
"created_at": "2026-02-20T00:00:00Z",
29+
"updated_at": "2026-02-20T00:00:00Z"
30+
}
31+
}
632
}

‎extensions/cleanup/.gitignore‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
# Local configuration (user-specific overrides)
2+
*-config.local.yml
3+
4+
# IDE
5+
.idea/
6+
.vscode/
7+
*.swp
8+
*.swo
9+
10+
# OS
11+
.DS_Store
12+
Thumbs.db

‎extensions/cleanup/CHANGELOG.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
# Changelog
2+
3+
All notable changes to the Cleanup extension will be documented in this file.
4+
5+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
6+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7+
8+
## [1.0.0] - 2026-02-20
9+
10+
### Added
11+
12+
- Initial release of the Cleanup extension
13+
- Post-implementation quality gate command (`/speckit.cleanup.run`)
14+
- Issue detection by severity (CRITICAL, LARGE, MEDIUM, SMALL)
15+
- Scout Rule implementation for small issues (auto-fix with confirmation)
16+
- Tech debt task creation for medium issues
17+
- Tech debt report generation for large issues
18+
- Constitution validation for all cleanup actions
19+
- Linter and test runner integration
20+
- `after_implement` hook for automatic cleanup prompting
21+
- Alias support (`/speckit.cleanup` -> `/speckit.cleanup.run`)

‎extensions/cleanup/LICENSE‎

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

‎extensions/cleanup/README.md‎

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
# Cleanup Extension for Spec Kit
2+
3+
Post-implementation quality gate that reviews changes, fixes small issues (scout rule), creates tasks for medium issues, and generates analysis for large issues.
4+
5+
## Installation
6+
7+
```bash
8+
# From the spec-kit extensions directory
9+
specify extension add cleanup
10+
11+
# Or install from local development
12+
specify extension add --dev /path/to/spec-kit/extensions/cleanup
13+
```
14+
15+
## Usage
16+
17+
After completing implementation with `/speckit.implement`, run the cleanup command:
18+
19+
```bash
20+
/speckit.cleanup
21+
```
22+
23+
The cleanup command will:
24+
25+
1. **Review all implementation changes** - Analyzes files modified during implementation
26+
2. **Detect issues by severity**:
27+
- **CRITICAL**: Security vulnerabilities requiring immediate attention
28+
- **LARGE**: Architecture concerns requiring team discussion
29+
- **MEDIUM**: Code quality issues requiring follow-up tasks
30+
- **SMALL**: Mechanical fixes that can be applied immediately
31+
3. **Apply fixes with user confirmation** - Small issues are fixed following the Scout Rule
32+
4. **Create tech debt tasks** - Medium issues become follow-up tasks in tasks.md
33+
5. **Generate analysis reports** - Large issues get detailed analysis in tech-debt-report.md
34+
35+
## Issue Detection
36+
37+
### Small Issues (Auto-fixable)
38+
- Debugging artifacts (console.log, print statements, debugger)
39+
- Unused imports
40+
- Dead/unreachable code
41+
- Hardcoded localhost URLs
42+
43+
### Medium Issues (Task Creation)
44+
- Missing error handling
45+
- Code duplication
46+
- Missing documentation
47+
- Disabled tests without reason
48+
49+
### Large Issues (Analysis Required)
50+
- Circular dependencies
51+
- Business logic in wrong layer
52+
- Performance anti-patterns
53+
- Security design issues
54+
55+
### Critical Issues (Halt)
56+
- Hardcoded credentials/secrets
57+
- Disabled authentication checks
58+
59+
## Outputs
60+
61+
| Artifact | Description |
62+
|----------|-------------|
63+
| Direct fixes | Small issues fixed in-place with commit |
64+
| tasks.md | Tech Debt Tasks section appended for medium issues |
65+
| tech-debt-report.md | Detailed analysis for large issues with options |
66+
67+
## Workflow Integration
68+
69+
The cleanup command integrates with the Spec Kit workflow:
70+
71+
```
72+
/speckit.specify -> /speckit.plan -> /speckit.tasks -> /speckit.implement -> /speckit.cleanup
73+
|
74+
v
75+
/speckit.implement (for tech debt tasks)
76+
```
77+
78+
## Configuration
79+
80+
No additional configuration required. The extension uses the project's existing:
81+
- Constitution (`/memory/constitution.md`) - for validation rules
82+
- Linter configuration - for style deference
83+
- Test runner - for validation
84+
85+
## Commands
86+
87+
| Command | Description |
88+
|---------|-------------|
89+
| `/speckit.cleanup.run` | Run post-implementation quality gate |
90+
| `/speckit.cleanup` | Alias for `/speckit.cleanup.run` |
91+
92+
## Hooks
93+
94+
This extension provides an `after_implement` hook that optionally prompts to run cleanup after `/speckit.implement` completes.
95+
96+
## Requirements
97+
98+
- Spec Kit >= 0.1.0
99+
- Completed implementation (tasks.md with completed tasks)
100+
101+
## License
102+
103+
MIT

templates/commands/cleanup.md renamed to extensions/cleanup/commands/cleanup.md

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
---
22
description: Post-implementation quality gate that reviews changes, fixes small issues (scout rule), creates tasks for medium issues, and generates analysis for large issues.
33
scripts:
4-
sh: scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks
5-
ps: scripts/powershell/check-prerequisites.ps1 -Json -RequireTasks -IncludeTasks
4+
sh: ../../scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks
5+
ps: ../../scripts/powershell/check-prerequisites.ps1 -Json -RequireTasks -IncludeTasks
66
handoffs:
77
- label: Re-implement follow-up tasks
88
agent: speckit.implement
@@ -30,7 +30,7 @@ Perform a final quality gate after implementation. Review all changes made durin
3030

3131
## Operating Constraints
3232

33-
**Constitution Authority**: The project constitution (`/memory/constitution.md`) is **non-negotiable**. Any cleanup action that would violate constitution principles is forbidden. If a fix would conflict with a MUST principle, escalate to large issue instead of fixing.
33+
**Constitution Authority**: The project constitution (`.specify/memory/constitution.md`) is **non-negotiable**. Any cleanup action that would violate constitution principles is forbidden. If a fix would conflict with a MUST principle, escalate to large issue instead of fixing.
3434

3535
**Linter Deference**: For style and formatting issues, defer to the project's configured linters. Do NOT manually fix issues that linters should handle - instead, run the linter with auto-fix if available.
3636

@@ -45,7 +45,7 @@ Run `{SCRIPT}` once from repo root and parse JSON for FEATURE_DIR and AVAILABLE_
4545
- SPEC = FEATURE_DIR/spec.md
4646
- PLAN = FEATURE_DIR/plan.md
4747
- TASKS = FEATURE_DIR/tasks.md
48-
- CONSTITUTION = /memory/constitution.md
48+
- CONSTITUTION = .specify/memory/constitution.md
4949
- TECH_DEBT_REPORT = FEATURE_DIR/tech-debt-report.md
5050

5151
Abort with error if TASKS does not exist or has no completed tasks (implementation not run).
@@ -381,7 +381,7 @@ Create FEATURE_DIR/tech-debt-report.md:
381381
- **Specification**: FEATURE_DIR/spec.md
382382
- **Implementation Plan**: FEATURE_DIR/plan.md
383383
- **Tasks**: FEATURE_DIR/tasks.md (Tech Debt section)
384-
- **Constitution**: /memory/constitution.md
384+
- **Constitution**: .specify/memory/constitution.md
385385

386386
## Next Steps
387387

@@ -455,9 +455,9 @@ Output final report:
455455

456456
### Proportional Response
457457
Match effort to issue severity:
458-
- SMALL → Fix now (minutes)
459-
- MEDIUM → Task for next sprint (hours)
460-
- LARGE → Analyze and decide (days, needs discussion)
458+
- SMALL -> Fix now (minutes)
459+
- MEDIUM -> Task for next sprint (hours)
460+
- LARGE -> Analyze and decide (days, needs discussion)
461461

462462
### Non-Destructive by Default
463463
- Always confirm before modifying files
@@ -472,7 +472,7 @@ Every cleanup action must respect constitution principles. When in conflict, con
472472
All outputs stay in FEATURE_DIR:
473473
- Links tech debt to the feature that introduced it
474474
- Enables re-running `/speckit.implement` for follow-ups
475-
- Supports audit trail: Spec → Plan → Tasks → Implement → Cleanup
475+
- Supports audit trail: Spec -> Plan -> Tasks -> Implement -> Cleanup
476476

477477
### Idempotency
478478
Safe to run multiple times:

‎extensions/cleanup/extension.yml‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
schema_version: "1.0"
2+
3+
extension:
4+
id: "cleanup"
5+
name: "Cleanup"
6+
version: "1.0.0"
7+
description: "Post-implementation quality gate that reviews changes, fixes small issues (scout rule), creates tasks for medium issues, and generates analysis for large issues."
8+
author: "Spec Kit Contributors"
9+
repository: "https://github.com/github/spec-kit"
10+
license: "MIT"
11+
homepage: "https://github.com/github/spec-kit/tree/main/extensions/cleanup"
12+
13+
requires:
14+
speckit_version: ">=0.1.0"
15+
commands:
16+
- "speckit.implement"
17+
- "speckit.tasks"
18+
19+
provides:
20+
commands:
21+
- name: "speckit.cleanup.run"
22+
file: "commands/cleanup.md"
23+
description: "Review implementation, fix small issues, identify tech debt"
24+
aliases: ["speckit.cleanup"]
25+
26+
hooks:
27+
after_implement:
28+
command: "speckit.cleanup.run"
29+
optional: true
30+
prompt: "Run cleanup to review implementation changes and identify tech debt?"
31+
description: "Post-implementation quality gate"
32+
33+
tags:
34+
- "quality"
35+
- "tech-debt"
36+
- "review"
37+
- "cleanup"
38+
- "scout-rule"

‎templates/commands/implement.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,9 +4,9 @@ scripts:
44
sh: scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks
55
ps: scripts/powershell/check-prerequisites.ps1 -Json -RequireTasks -IncludeTasks
66
handoffs:
7-
- label: Run cleanup phase
7+
- label: Run cleanup phase (requires cleanup extension)
88
agent: speckit.cleanup
9-
prompt: Review implementation changes, fix small issues, and identify tech debt
9+
prompt: Review implementation changes, fix small issues, and identify tech debt (install cleanup extension first with 'specify extension add cleanup')
1010
---
1111

1212
## User Input

‎templates/tasks-template.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -159,11 +159,11 @@ Examples of foundational tasks (adjust based on your project):
159159

160160
---
161161

162-
## Phase N+1: Cleanup & Tech Debt Review
162+
## Phase N+1: Cleanup & Tech Debt Review (Extension)
163163

164164
**Purpose**: Final quality gate - review all changes, identify tech debt, and ensure code hygiene
165165

166-
**Executed by**: `/speckit.cleanup` command (run after `/speckit.implement` completes)
166+
**Executed by**: `/speckit.cleanup` command (requires cleanup extension - install with `specify extension add cleanup`)
167167

168168
The cleanup phase handles issues by severity:
169169

0 commit comments

Comments
 (0)