Skip to content

Commit 17fffed

Browse files
markhazletonmarkhazleton
committed
updates
1 parent 379691b commit 17fffed

3 files changed

Lines changed: 261 additions & 0 deletions

File tree

‎docs/toc.yml‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,3 +35,9 @@
3535
href: site-audit-usage.md
3636
- name: Critic Guide (Spec Workflow)
3737
href: critic-usage.md
38+
39+
# About This Fork
40+
- name: About Spec Kit Spark
41+
items:
42+
- name: Why I Forked Spec Kit
43+
href: why-i-forked-spec-kit.md

‎docs/why-i-forked-spec-kit.md‎

Lines changed: 232 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,232 @@
1+
# Why I Forked GitHub Spec Kit
2+
3+
*Building on the shoulders of giants to unlock the full potential of project constitutions.*
4+
5+
---
6+
7+
## The Starting Point: A Brilliant Foundation
8+
9+
GitHub's [Spec Kit](https://github.com/github/spec-kit) introduced something genuinely innovative—**Spec-Driven Development (SDD)**. The methodology flips traditional software development on its head: instead of treating specifications as disposable scaffolding, SDD makes them the executable source of truth that drives implementation.
10+
11+
The original toolkit includes a powerful concept: the **project constitution**. This document captures your team's governing principles, development guidelines, and quality standards. The AI agent then references this constitution during specification, planning, and implementation phases.
12+
13+
I was immediately drawn to this approach. The constitution concept resonated with how I think about sustainable software development—principles-first, then implementation.
14+
15+
But as I used Spec Kit, I kept asking: *"What else could we do with a well-crafted constitution?"*
16+
17+
---
18+
19+
## The Gap I Saw
20+
21+
The original Spec Kit uses the constitution primarily during the **spec workflow**:
22+
23+
1. **`/speckit.specify`** → Define requirements
24+
2. **`/speckit.plan`** → Create implementation plan
25+
3. **`/speckit.tasks`** → Break down into actionable tasks
26+
4. **`/speckit.implement`** → Execute the plan
27+
28+
This is excellent for greenfield development. But I saw three opportunities:
29+
30+
### 1. Constitutions Should Govern More Than Just New Features
31+
32+
If you invest time writing a thoughtful constitution, why should it only apply during feature development? Every pull request, every code review, every codebase audit should leverage those principles.
33+
34+
### 2. Brownfield Projects Need a Path to SDD
35+
36+
Most teams aren't starting fresh. They have existing codebases with implicit patterns, undocumented conventions, and years of accumulated decisions. How do you retrofit a constitution onto an existing project?
37+
38+
### 3. Risk Analysis Before Implementation
39+
40+
The original workflow focuses on *what to build* and *how to build it*. I wanted a step that asks *what could go wrong*—an adversarial pre-mortem before writing a single line of code.
41+
42+
---
43+
44+
## What Spec Kit Spark Adds
45+
46+
I created **Spec Kit Spark** as a community extension that keeps the original SDD workflow intact while adding four constitution-powered capabilities:
47+
48+
### `/speckit.pr-review` — Constitution-Based Pull Request Reviews
49+
50+
**The problem:** Traditional PR reviews depend on individual reviewer knowledge. Different reviewers catch different issues based on their experience and focus.
51+
52+
**The solution:** Use the constitution as an objective standard. Every PR gets evaluated against the same principles.
53+
54+
**Key design decisions:**
55+
- Works for **any PR in any branch**—not limited to feature branches
56+
- Only requires a constitution—no spec, plan, or tasks needed
57+
- Saves review history to `/specs/pr-review/pr-{number}.md`
58+
- Tracks commit SHAs so you can re-review after changes
59+
60+
This means constitution-powered reviews work for:
61+
- Hotfixes to main
62+
- Documentation updates to develop
63+
- Any contribution, regardless of whether it followed the SDD workflow
64+
65+
### `/speckit.site-audit` — Codebase-Wide Compliance Auditing
66+
67+
**The problem:** Constitution principles mean nothing if they're not enforced consistently across the entire codebase.
68+
69+
**The solution:** A comprehensive audit command that evaluates your entire codebase against constitution principles.
70+
71+
**What it checks:**
72+
- Constitution compliance (principle-by-principle)
73+
- Security vulnerabilities and patterns
74+
- Dependency health (outdated, unused, vulnerable packages)
75+
- Code quality metrics (complexity, duplication)
76+
- Unused code detection
77+
78+
**Key design decisions:**
79+
- Supports scoped audits (`--scope=constitution`, `--scope=packages`, etc.)
80+
- Produces trend-trackable reports in `/docs/copilot/audit/`
81+
- Compares against previous audits to show improvement or regression
82+
83+
### `/speckit.critic` — Adversarial Risk Analysis
84+
85+
**The problem:** Plans and task lists can look perfect on paper but fail spectacularly in production. Teams with limited experience in a new tech stack often miss edge cases.
86+
87+
**The solution:** A skeptical reviewer that identifies showstoppers *before* implementation begins.
88+
89+
**How it differs from `/speckit.analyze`:**
90+
- `/speckit.analyze` = Consistency checking (are artifacts aligned?)
91+
- `/speckit.critic` = Adversarial analysis (what will fail in production?)
92+
93+
**Severity levels:**
94+
- **SHOWSTOPPER** — Will cause production outage, data loss, or security breach
95+
- **CRITICAL** — Major user-facing issues or costly rework
96+
- **HIGH** — Technical debt or operational burden
97+
- **MEDIUM** — Development slowdown or minor issues
98+
99+
**Key design decisions:**
100+
- Constitution violations are automatically SHOWSTOPPER severity
101+
- Provides a clear Go/No-Go recommendation
102+
- Runs after `/speckit.tasks` but before `/speckit.implement`
103+
104+
### `/speckit.discover-constitution` — Brownfield Constitution Discovery
105+
106+
**The problem:** Existing codebases have implicit patterns and conventions baked into the code. Teams adopting SDD need a way to extract these patterns into a constitution.
107+
108+
**The solution:** Analyze the codebase, discover patterns, and guide teams through interactive questions to formalize a constitution.
109+
110+
**How it works:**
111+
1. Scans for patterns (testing frameworks, security practices, architecture conventions)
112+
2. Reports high-confidence patterns (>80% consistent) vs. inconsistent areas
113+
3. Asks 8-10 targeted questions to validate findings
114+
4. Generates a draft constitution at `/memory/constitution-draft.md`
115+
116+
**Key design decisions:**
117+
- Discovery-first: analyze code before asking questions
118+
- Draft output: produces a starting point for team review, not a final document
119+
- Respects existing work: treats discovered patterns as valuable
120+
121+
---
122+
123+
## Additional Improvements
124+
125+
Beyond the four major features, Spec Kit Spark includes:
126+
127+
### PowerShell Parity
128+
129+
Every bash script has a corresponding PowerShell script. Windows developers get first-class support.
130+
131+
| Script | Purpose |
132+
|--------|---------|
133+
| `site-audit.ps1` | Codebase auditing |
134+
| `get-pr-context.ps1` | PR data extraction via GitHub CLI |
135+
| `create-github-release.ps1` | Release management |
136+
| `generate-release-notes.ps1` | Automated changelog generation |
137+
138+
### Repository Health Analysis
139+
140+
Integrated Git Spark reports provide insights into:
141+
- Contributor activity and bus factor
142+
- File hotspots (high churn, many authors)
143+
- Governance scores (commit message quality, traceability)
144+
- Risk analysis based on code churn patterns
145+
146+
### Enhanced Documentation
147+
148+
- Constitutional governance guide with examples
149+
- PR review usage documentation
150+
- Site audit usage guide
151+
- Critic command documentation
152+
- Local development instructions
153+
154+
---
155+
156+
## The Philosophy: Continuous Constitution Value
157+
158+
The core philosophy of Spec Kit Spark is simple:
159+
160+
> **A project constitution should provide value continuously, not just during feature development.**
161+
162+
If you write a constitution that says "All public APIs must have input validation," that principle should:
163+
- Guide new feature development (original Spec Kit)
164+
- Catch violations in pull requests (`/speckit.pr-review`)
165+
- Identify existing violations in the codebase (`/speckit.site-audit`)
166+
- Flag missing validation as a risk before implementation (`/speckit.critic`)
167+
168+
This creates a **closed loop** where constitution principles are enforced at every stage of the development lifecycle.
169+
170+
---
171+
172+
## Attribution and Relationship to Original
173+
174+
Full credit goes to the GitHub team—particularly [Den Delimarsky](https://github.com/localden) and [John Lam](https://github.com/jflam)—for creating the Spec-Driven Development methodology and the original Spec Kit toolkit.
175+
176+
**Spec Kit Spark is an extension, not a replacement.** The original SDD workflow remains unchanged. All additions are additive and maintain backward compatibility.
177+
178+
If you're looking for the official, GitHub-maintained version, visit [github.com/github/spec-kit](https://github.com/github/spec-kit).
179+
180+
Spec Kit Spark is part of the [WebSpark](https://github.com/MarkHazleton?tab=repositories&q=webspark) demonstration suite—a collection of projects exploring modern development practices.
181+
182+
---
183+
184+
## Try It Yourself
185+
186+
Install Spec Kit Spark:
187+
188+
```bash
189+
uv tool install specify-cli --from git+https://github.com/MarkHazleton/spec-kit.git
190+
```
191+
192+
Initialize in your existing project (brownfield):
193+
194+
```bash
195+
cd /path/to/your-project
196+
specify init --here --ai copilot
197+
198+
# Discover patterns and draft a constitution
199+
# (use /speckit.discover-constitution in your AI agent)
200+
```
201+
202+
Or start fresh (greenfield):
203+
204+
```bash
205+
specify init my-project --ai claude
206+
```
207+
208+
Then try the constitution-powered commands:
209+
- `/speckit.discover-constitution` — Draft a constitution from existing code
210+
- `/speckit.pr-review #123` — Review a PR against your constitution
211+
- `/speckit.site-audit` — Audit your entire codebase
212+
- `/speckit.critic` — Identify risks before implementation
213+
214+
---
215+
216+
## Summary
217+
218+
| Why I Forked | What I Added |
219+
|--------------|--------------|
220+
| Constitutions should govern more than specs | `/speckit.pr-review` for any PR |
221+
| Existing codebases need a path to SDD | `/speckit.discover-constitution` for brownfield |
222+
| Risk analysis should happen before coding | `/speckit.critic` for pre-mortems |
223+
| Codebase-wide compliance matters | `/speckit.site-audit` for auditing |
224+
| Windows developers deserve parity | PowerShell scripts for all operations |
225+
226+
The goal is simple: **maximize the return on investment for crafting a thoughtful project constitution**.
227+
228+
---
229+
230+
*— Mark Hazleton*
231+
232+
*Part of the [WebSpark](https://github.com/MarkHazleton?tab=repositories&q=webspark) demonstration suite*

‎release_notes.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# Spec Kit Spark
2+
3+
A community extension of GitHub Spec Kit with constitution-powered commands for enhanced development workflows. Part of the WebSpark demonstration suite.
4+
5+
## Spark-Specific Features
6+
7+
- **Discover Constitution**: Analyze existing codebases to reverse-engineer project principles
8+
- **PR Review Command**: Constitution-based pull request review workflow
9+
- **Site Audit**: Comprehensive codebase auditing against constitution principles
10+
- **Critic Command**: Adversarial risk analysis for spec artifacts
11+
- **Extended Agent Support**: 17+ AI coding assistants supported
12+
13+
## Using This Release
14+
15+
You can use these releases with your agent of choice. We recommend using the Specify CLI to scaffold your projects, however you can download these independently and manage them yourself.
16+
17+
## Changelog
18+
19+
- Refactor release notes and versioning for Spec Kit Spark - Update documentation and references for Mark Hazleton Edition of Spec Kit - Add Git Spark Report for repository health analysis and contributor insights - update documentation for spec driven development and site audit tool - Add /speckit.critic command for adversarial risk analysis and update changelog - Add README for local testing scripts in PowerShell - Add fork-specific scripts and documentation for release management - Add /speckit.pr-review command for constitution-based PR reviews
20+
21+
---
22+
23+
*Based on upstream GitHub Spec Kit. Spec Kit Spark is a community extension that may contain features not yet available in the upstream project.*

0 commit comments

Comments
 (0)