Skip to content

Commit d6dba6a

Browse files
sakitAsakitA
committed
feat: Initial release v1.0.0 — constitution audit, token tracking, session learning
3 commands for AI governance optimization: - speckit.optimize.run: Constitution audit (6 analysis categories) - speckit.optimize.tokens: Token usage tracking with historical trends - speckit.optimize.learn: Session learning for mistake pattern detection
0 parents  commit d6dba6a

10 files changed

Lines changed: 1163 additions & 0 deletions

‎.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
optimize-config.yml
2+
optimize-config.local.yml
3+
*.local.yml

‎CHANGELOG.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# Changelog
2+
3+
All notable changes to the Optimize 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-04-03
9+
10+
### Added
11+
12+
- Constitution audit command (`/speckit.optimize.run`) with 6 analysis categories:
13+
- Token Budget Analysis
14+
- Rule Health Analysis
15+
- AI Interpretability Analysis
16+
- Semantic Compression
17+
- Constitution Coherence
18+
- Governance Echo Detection
19+
- Token usage tracker (`/speckit.optimize.tokens`) with historical trend support
20+
- Session learning command (`/speckit.optimize.learn`) for AI mistake pattern detection
21+
- Configuration template with category toggles and thresholds
22+
- Suggest-only design: no modifications without explicit user consent
23+
- Spec-kit standard path resolution with redirect following

‎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 sakitA
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: 129 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,129 @@
1+
# Spec-Kit Optimize Extension
2+
3+
Audits and optimizes AI governance documents for context efficiency. Designed for long-term AI-driven development where constitutions grow organically and accumulate token debt.
4+
5+
## Why This Extension Exists
6+
7+
In AI-driven development, the constitution is loaded into every AI session's context window. Over time:
8+
9+
- **Token bloat**: Rules, examples, and version history accumulate — costing tokens on every invocation
10+
- **Rule decay**: Incident-specific rules persist forever because AI has no institutional memory
11+
- **Non-deterministic governance**: Ambiguous rules cause different AI sessions to behave differently
12+
- **Governance echoes**: The same rule gets restated across multiple files, wasting tokens and risking contradictions
13+
- **No learning loop**: AI sessions make the same mistakes repeatedly with no mechanism to capture learnings
14+
15+
This extension provides tooling to detect and fix these problems.
16+
17+
## Installation
18+
19+
```bash
20+
# From the spec-kit catalog (when published)
21+
specify extension add optimize
22+
23+
# From a direct URL
24+
specify extension add optimize --from https://github.com/sakitA/spec-kit-optimize/archive/refs/tags/v1.0.0.zip
25+
26+
# For local development
27+
specify extension add --dev /path/to/spec-kit-optimize
28+
```
29+
30+
## Commands
31+
32+
### `/speckit.optimize.run` — Constitution Audit
33+
34+
Analyzes the constitution across 6 categories uniquely relevant to AI-driven development:
35+
36+
1. **Token Budget Analysis** — measures per-section token cost and governance density
37+
2. **Rule Health Analysis** — detects stale, incident-specific, superseded, and graduated rules
38+
3. **AI Interpretability Analysis** — finds ambiguity, contradictions, unenforceable rules
39+
4. **Semantic Compression** — identifies collapsible rule clusters, redundant examples, inline-to-reference conversions
40+
5. **Constitution Coherence** — evaluates principle balance, rule scatter, cross-references, CLAUDE.md drift
41+
6. **Governance Echo Detection** — finds cross-file duplication and total governance token budget
42+
43+
```bash
44+
# Full audit
45+
/speckit.optimize.run
46+
47+
# Single category
48+
/speckit.optimize.run --category token_budget
49+
50+
# Report only (no apply step)
51+
/speckit.optimize.run --report-only
52+
```
53+
54+
### `/speckit.optimize.tokens` — Token Usage Tracker
55+
56+
Measures the token footprint of all governance files and extension commands. Tracks trends over time.
57+
58+
```bash
59+
# Full token report
60+
/speckit.optimize.tokens
61+
62+
# Compare against previous report
63+
/speckit.optimize.tokens --diff
64+
65+
# Extensions only (skip governance files)
66+
/speckit.optimize.tokens --extensions-only
67+
```
68+
69+
### `/speckit.optimize.learn` — Session Learning
70+
71+
End-of-session analysis: detects AI mistake patterns, repetitive corrections, and governance gaps. Suggests constitution rules or memory entries to prevent recurrence.
72+
73+
```bash
74+
# Full session analysis
75+
/speckit.optimize.learn
76+
77+
# Rules only (no memory suggestions)
78+
/speckit.optimize.learn --rules-only
79+
80+
# Analyze from a specific commit
81+
/speckit.optimize.learn --since abc1234
82+
```
83+
84+
## Design Philosophy
85+
86+
**Suggest-only by default.** Every command produces a report first. Nothing is modified until the user explicitly approves. The flow is always: Analyze → Report → Propose → User Consent → Apply.
87+
88+
**Spec-kit standard paths.** The extension works with any spec-kit project. It uses `.specify/memory/constitution.md` as the primary constitution path and follows redirects for project-specific layouts. It never hardcodes project-specific paths.
89+
90+
**Semantic preservation.** Optimization removes redundancy in expression, not in intent. Every governance rule survives compression — only its token cost changes.
91+
92+
## Configuration
93+
94+
Copy `config-template.yml` to `optimize-config.yml` in the extension directory:
95+
96+
```bash
97+
cp .specify/extensions/optimize/config-template.yml \
98+
.specify/extensions/optimize/optimize-config.yml
99+
```
100+
101+
Key settings:
102+
- `categories.*` — toggle individual analysis categories on/off
103+
- `thresholds.max_constitution_tokens` — flag constitutions exceeding this token estimate
104+
- `thresholds.governance_budget_percent` — max % of context window for governance overhead
105+
- `target_context_window` — context window size for budget calculations (default: 200K)
106+
- `learn.min_corrections_to_flag` — minimum repeated corrections before flagging a pattern
107+
108+
## Integration
109+
110+
- **`/speckit.constitution`** — authoring tool. Optimize hands off to it for applying approved changes with proper version bumping.
111+
- **`/speckit.analyze`** — consistency checker. Run after optimization to verify cross-artifact alignment.
112+
- **`/speckit.optimize.tokens`** → **`/speckit.optimize.run`** — if token tracker reveals high governance overhead, run the full audit.
113+
- **`/speckit.optimize.learn`** → **`/speckit.constitution`** — approved rules from session learning are applied via the constitution skill.
114+
115+
## Reports
116+
117+
Reports are saved to `.specify/optimize/` (with user consent):
118+
- `token-report.md` — latest token usage snapshot (enables historical trends)
119+
- `learning-report-<date>.md` — per-session learning analysis
120+
121+
## Requirements
122+
123+
- Spec-Kit >= 0.1.0
124+
- An existing populated constitution (not a raw template)
125+
- Git repository (for learn command's session analysis)
126+
127+
## License
128+
129+
MIT

‎catalog-entry.json‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
{
2+
"name": "Optimize Extension",
3+
"id": "optimize",
4+
"description": "Audits and optimizes AI governance for context efficiency",
5+
"author": "sakitA",
6+
"version": "1.0.0",
7+
"download_url": "https://github.com/sakitA/spec-kit-optimize/archive/refs/tags/v1.0.0.zip",
8+
"repository": "https://github.com/sakitA/spec-kit-optimize",
9+
"homepage": "https://github.com/sakitA/spec-kit-optimize",
10+
"documentation": "https://github.com/sakitA/spec-kit-optimize/blob/main/README.md",
11+
"changelog": "https://github.com/sakitA/spec-kit-optimize/blob/main/CHANGELOG.md",
12+
"license": "MIT",
13+
"requires": {
14+
"speckit_version": ">=0.1.0"
15+
},
16+
"provides": {
17+
"commands": 3,
18+
"hooks": 0
19+
},
20+
"tags": [
21+
"constitution",
22+
"optimization",
23+
"token-budget",
24+
"governance",
25+
"audit"
26+
],
27+
"verified": false,
28+
"downloads": 0,
29+
"stars": 0,
30+
"created_at": "2026-04-03T00:00:00Z",
31+
"updated_at": "2026-04-03T00:00:00Z"
32+
}

0 commit comments

Comments
 (0)