Skip to content

Commit 6cc9d52

Browse files
kanfilkanfil
committed
refactor: modularize levelup into extension with 5 CDR-based commands (#56)
- Add extensions/levelup/ with init, clarify, spec, skills, implement commands - Replace monolithic /spec.levelup with /levelup.spec (feature extraction) - Add /levelup.init for brownfield codebase scanning - Introduce Context Decision Records (CDRs) similar to ADRs - Add bash and PowerShell scripts for setup and analysis - Update catalog.json with levelup extension entry - Remove old templates/commands/levelup.md - Update docs to reference new command structure BREAKING CHANGE: /spec.levelup renamed to /levelup.spec
1 parent 254d0d7 commit 6cc9d52

File tree

22 files changed

+2903
-154
lines changed

22 files changed

+2903
-154
lines changed

‎README.md‎

Lines changed: 14 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -482,16 +482,21 @@ Use **`/spec.trace`** to generate comprehensive AI session execution traces capt
482482
/spec.trace
483483
```
484484

485-
**Benefits**: Session traces document AI agent decision-making, execution context, quality gates, and reusable patterns. Stored in `specs/{BRANCH}/trace.md` with your feature artifacts. Optional but enriches `/spec.levelup` context packets when present.
485+
**Benefits**: Session traces document AI agent decision-making, execution context, quality gates, and reusable patterns. Stored in `specs/{BRANCH}/trace.md` with your feature artifacts. Optional but enriches `/levelup.spec` CDR extraction when present.
486486

487487
### 8. Level up and contribute knowledge
488488

489-
Use **`/spec.levelup`** to capture learnings from completed work and contribute reusable knowledge back to your team's shared repository.
489+
Use the **levelup extension** to extract patterns from your completed feature and contribute reusable knowledge back to your team's shared repository.
490490

491491
```bash
492-
/spec.levelup "Document the patterns learned from this implementation for future reference"
492+
/levelup.spec # Extract CDRs from current feature spec (after /implement)
493+
/levelup.clarify # Resolve ambiguities in discovered CDRs
494+
/levelup.skills python-patterns # Build a skill from accepted CDRs
495+
/levelup.implement # Create PR to team-ai-directives
493496
```
494497

498+
For brownfield projects, use `/levelup.init` to scan the entire codebase for patterns.
499+
495500
For detailed step-by-step instructions, see our [comprehensive guide](./spec-driven.md).
496501

497502
## 🤖 Supported AI Agents
@@ -845,8 +850,12 @@ Essential commands for the Spec-Driven Development workflow:
845850
| `/spec.plan` | Create technical implementation plans with your chosen tech stack & SYNC/ASYNC triage |
846851
| `/spec.tasks` | Generate actionable task lists for implementation |
847852
| `/spec.implement` | Execute all tasks to build the feature according to the plan with dual execution loops (SYNC/ASYNC modes) |
848-
| `/spec.trace` | Generate AI session execution traces with decisions, patterns, and evidence (optional, enriches `/levelup`) |
849-
| `/spec.levelup` | Capture learnings and contribute to team knowledge repository |
853+
| `/spec.trace` | Generate AI session execution traces with decisions, patterns, and evidence (optional, enriches `/levelup.spec`) |
854+
| `/levelup.spec` | Extract CDRs from current feature spec context (replaces old `/spec.levelup`) |
855+
| `/levelup.init` | Discover CDRs from entire codebase (brownfield analysis) |
856+
| `/levelup.clarify` | Resolve ambiguities in discovered CDRs |
857+
| `/levelup.skills` | Build a single skill from accepted CDRs |
858+
| `/levelup.implement` | Compile accepted CDRs into PR to team-ai-directives |
850859

851860
#### Optional Commands
852861

‎docs/installation.md‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -110,7 +110,10 @@ After initialization, you should see the following commands available in your AI
110110
- `/spec.plan` - Generate implementation plans
111111
- `/spec.tasks` - Break down into actionable tasks
112112
- `/spec.implement` - Execute implementation with SYNC/ASYNC dual execution loops
113-
- `/spec.levelup` - Capture learnings and contribute to team knowledge
113+
- `/levelup.spec` - Extract patterns from current feature and create CDRs for team knowledge
114+
- `/levelup.init` - Discover patterns from entire codebase (brownfield)
115+
- `/levelup.clarify` - Resolve ambiguities in discovered CDRs
116+
- `/levelup.implement` - Compile CDRs into PR to team-ai-directives
114117
- `/spec.analyze` - Cross-artifact consistency and alignment reports
115118
- `/spec.checklist` - Generate quality checklists for requirements validation
116119
- `/spec.clarify` - Structured questions to de-risk ambiguous areas

‎docs/quickstart.md‎

Lines changed: 25 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -169,24 +169,38 @@ The per-spec architecture enables advanced workflows:
169169

170170
## Stage 4: Leveling Up
171171

172-
**Goal:** Capture best practices from the completed feature, draft a reusable knowledge asset in `team-ai-directives`, and generate traceability notes for the original issue.
173-
**Note:** `/levelup` runs inside the IDE and relies on the locally cloned directives repository from Stage 0.
172+
**Goal:** Capture best practices from the completed feature, create Context Decision Records (CDRs) for reusable patterns, and contribute them back to `team-ai-directives`.
173+
**Note:** The levelup extension runs inside the IDE and relies on the locally cloned directives repository from Stage 0.
174174
**Alignment with 12 Factors:** This stage encompasses [IX. Traceability](https://tikalk.github.io/agentic-sdlc-12-factors/content/traceability.html), [X. Strategic Tooling](https://tikalk.github.io/agentic-sdlc-12-factors/content/strategic-tooling.html), [XI. Directives as Code](https://tikalk.github.io/agentic-sdlc-12-factors/content/directives-as-code.html), and [XII. Team Capability](https://tikalk.github.io/agentic-sdlc-12-factors/content/team-capability.html), linking artifacts, managing tools, versioning AI behavior, and systematizing learning.
175175

176-
1. **Run Level-Up Workflow (`/levelup`)**
177-
**Action:** Invoke `/levelup` with a strategic directive (e.g., highlight what should become reusable). Agentic SDLC Spec Kit gathers spec/plan/tasks metadata, validates the directives repo, and prompts you to synthesize a knowledge asset plus PR/issue summaries.
178-
**Purpose:** Produces a draft markdown asset under `.specify/memory/team-ai-directives/drafts/`, along with a pull-request description and trace comment for review.
179-
2. **Review & Publish**
180-
**Action:** Inspect the generated asset and summaries. When satisfied, confirm inside `/levelup` to let it create a `levelup/{slug}` branch, commit the asset, push (when remotes are configured), open a PR via `gh pr create` (or emit the command), and post the trace comment (or provide the text if automation is unavailable).
181-
**Purpose:** Ensures lessons learned become part of the team's shared brain and closes the loop with traceability artifacts without manual branching overhead.
176+
1. **Extract CDRs from Feature (`/levelup.spec`)**
177+
**Action:** Invoke `/levelup.spec` after completing `/implement` to extract patterns from the current feature. The command creates Context Decision Records (CDRs) in `.specify/memory/cdr.md` based on your spec, plan, tasks, and optional trace.
178+
**Purpose:** Captures coding patterns, best practices, and reusable knowledge from your completed implementation.
182179

183-
**Example Command:**
180+
2. **Clarify and Accept (`/levelup.clarify`)**
181+
**Action:** Run `/levelup.clarify` to review discovered CDRs, answer clarifying questions about validity/scope/priority, and update CDR statuses to "Accepted" or "Rejected".
182+
**Purpose:** Validates that patterns are team-wide (not project-specific) and ready for contribution.
183+
184+
3. **Build Skills (Optional) (`/levelup.skills`)**
185+
**Action:** Run `/levelup.skills {topic}` to build a self-contained skill from accepted CDRs. Skills are created in `.specify/drafts/skills/`.
186+
**Purpose:** Packages related CDRs into reusable skills that AI agents can load.
187+
188+
4. **Create PR (`/levelup.implement`)**
189+
**Action:** Run `/levelup.implement` to compile accepted CDRs into a draft PR to team-ai-directives. The command creates a `levelup/{slug}` branch, commits context modules, and creates a PR.
190+
**Purpose:** Ensures lessons learned become part of the team's shared repository with proper review.
191+
192+
**Example Commands:**
184193

185194
```text
186-
/levelup "Capture the FastAPI error-handling patterns we refined while closing ISSUE-123. Summarize why the retry strategy works, when to apply it, and provide links to the final implementation."
195+
/levelup.spec "Focus on the error handling patterns we developed"
196+
/levelup.clarify
197+
/levelup.skills python-error-handling
198+
/levelup.implement
187199
```
188200

189-
**Outcome:** A knowledge asset ready for PR, a drafted trace comment for the issue tracker, and clear next steps for team review.
201+
**Note:** For brownfield projects (scanning entire codebase without a feature context), use `/levelup.init` instead of `/levelup.spec`.
202+
203+
**Outcome:** CDRs documented in `.specify/memory/cdr.md`, optional skills in `.specify/drafts/skills/`, and a draft PR to team-ai-directives for team review.
190204

191205
## The 6-Step Process
192206

‎extensions/catalog.json‎

Lines changed: 33 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,37 @@
11
{
22
"schema_version": "1.0",
3-
"updated_at": "2026-02-03T00:00:00Z",
3+
"updated_at": "2026-03-03T00:00:00Z",
44
"catalog_url": "https://raw.githubusercontent.com/github/spec-kit/main/extensions/catalog.json",
5-
"extensions": {}
5+
"extensions": {
6+
"levelup": {
7+
"id": "levelup",
8+
"name": "LevelUp - Team AI Directives Contributor",
9+
"version": "1.0.0",
10+
"description": "Discover and contribute context modules (rules, personas, examples, skills) to team-ai-directives using Context Decision Records (CDRs)",
11+
"author": "Agentic SDLC Team",
12+
"repository": "https://github.com/tikalk/agentic-sdlc-spec-kit",
13+
"homepage": "https://github.com/tikalk/agentic-sdlc-spec-kit/tree/main/extensions/levelup",
14+
"license": "MIT",
15+
"requires": {
16+
"speckit_version": ">=0.1.0"
17+
},
18+
"commands": [
19+
"speckit.levelup.init",
20+
"speckit.levelup.clarify",
21+
"speckit.levelup.spec",
22+
"speckit.levelup.skills",
23+
"speckit.levelup.implement"
24+
],
25+
"tags": [
26+
"team-ai-directives",
27+
"brownfield",
28+
"context-modules",
29+
"skills",
30+
"cdr",
31+
"contribution"
32+
],
33+
"verified": false,
34+
"featured": false
35+
}
36+
}
637
}

‎extensions/levelup/CHANGELOG.md‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
# Changelog
2+
3+
All notable changes to the LevelUp 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-03-03
9+
10+
### Added
11+
12+
- Initial release of LevelUp extension
13+
- `levelup.init` command for brownfield CDR discovery
14+
- `levelup.clarify` command for resolving CDR ambiguities
15+
- `levelup.spec` command for refining CDRs from feature context
16+
- `levelup.skills` command for building skills from accepted CDRs
17+
- `levelup.implement` command for creating PRs to team-ai-directives
18+
- Context Decision Record (CDR) template
19+
- Support for both submodule and clone paths for team-ai-directives
20+
- Bash and PowerShell scripts for setup and analysis
21+
22+
### Related
23+
24+
- GitHub Issue: [#56](https://github.com/tikalk/agentic-sdlc-spec-kit/issues/56)
25+
- Replaces monolithic `/spec.levelup` command

‎extensions/levelup/README.md‎

Lines changed: 136 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,136 @@
1+
# LevelUp Extension
2+
3+
Discover and contribute context modules (rules, personas, examples, skills) to team-ai-directives using Context Decision Records (CDRs).
4+
5+
## Overview
6+
7+
The LevelUp extension helps brownfield projects analyze their codebase and contribute reusable context modules back to the team's shared AI directives repository. It introduces **Context Decision Records (CDRs)** - similar to Architecture Decision Records (ADRs) - for tracking what, why, and how context is being contributed.
8+
9+
## Commands
10+
11+
| Command | Purpose |
12+
|---------|---------|
13+
| `/levelup.init` | Scan codebase and discover CDRs (like `/architect.init`) |
14+
| `/levelup.clarify` | Resolve ambiguities in discovered CDRs (like `/architect.clarify`) |
15+
| `/levelup.spec` | Refine CDRs using current feature spec context |
16+
| `/levelup.skills` | Build a single skill from accepted CDRs |
17+
| `/levelup.implement` | Compile accepted CDRs into a PR to team-ai-directives |
18+
19+
## Quick Start
20+
21+
### 1. Initialize CDR Discovery
22+
23+
Scan your codebase for patterns that could become team-wide directives:
24+
25+
```bash
26+
/levelup.init
27+
```
28+
29+
This creates CDRs in `.specify/memory/cdr.md` with status "Discovered".
30+
31+
### 2. Clarify and Accept CDRs
32+
33+
Review discovered CDRs and resolve ambiguities:
34+
35+
```bash
36+
/levelup.clarify
37+
```
38+
39+
This validates patterns and updates CDR statuses to "Accepted" or "Rejected".
40+
41+
### 3. Build Skills (Optional)
42+
43+
Build a skill from accepted CDRs:
44+
45+
```bash
46+
/levelup.skills python-error-handling
47+
```
48+
49+
This creates a skill in `.specify/drafts/skills/`.
50+
51+
### 4. Create PR
52+
53+
Compile accepted CDRs into a PR to team-ai-directives:
54+
55+
```bash
56+
/levelup.implement
57+
```
58+
59+
This creates a draft PR with all accepted contributions.
60+
61+
## Context Decision Records (CDRs)
62+
63+
CDRs are stored in `.specify/memory/cdr.md` and track:
64+
65+
- **Target Module**: Where the contribution goes in team-ai-directives
66+
- **Context Type**: Rule, Persona, Example, Constitution Amendment, or Skill
67+
- **Status**: Discovered → Proposed → Accepted/Rejected → Implemented
68+
- **Evidence**: Links to code, commits, and discussions
69+
70+
### CDR Status Values
71+
72+
| Status | Description |
73+
|--------|-------------|
74+
| **Discovered** | Inferred from codebase during brownfield analysis |
75+
| **Proposed** | Suggested for review, awaiting validation |
76+
| **Accepted** | Approved for implementation |
77+
| **Rejected** | Not accepted (reason documented) |
78+
| **Implemented** | PR created to team-ai-directives |
79+
80+
## Configuration
81+
82+
### Team AI Directives Path
83+
84+
The extension resolves the team-ai-directives path in this order:
85+
86+
1. `SPECIFY_TEAM_DIRECTIVES` environment variable
87+
2. `.specify/team-ai-directives` (submodule - recommended)
88+
3. `.specify/memory/team-ai-directives` (clone - legacy)
89+
90+
### Extension Config
91+
92+
Optional configuration in `.specify/extensions/levelup/levelup-config.yml`:
93+
94+
```yaml
95+
cdr:
96+
heuristic: "surprising" # surprising | all | minimal
97+
location: ".specify/memory/cdr.md"
98+
99+
skills:
100+
drafts_location: ".specify/drafts/skills"
101+
102+
discovery:
103+
rules: true
104+
personas: true
105+
examples: true
106+
constitution: true
107+
skills: true
108+
109+
pull_request:
110+
draft: true
111+
branch_prefix: "levelup/"
112+
target_branch: "main"
113+
```
114+
115+
## Command Flow
116+
117+
```
118+
levelup.init levelup.clarify levelup.skills levelup.implement
119+
(Discover CDRs) ───▶ (Resolve Ambiguities) ───▶ (Build Skills) ───▶ (Create PR)
120+
│ │ │ │
121+
│ [handoff] │ [handoff] │ │
122+
└──▶ levelup.spec ◀────┘ │ │
123+
(Refine from │ │
124+
feature context) │ │
125+
```
126+
127+
## Related Issues
128+
129+
- [#56](https://github.com/tikalk/agentic-sdlc-spec-kit/issues/56) - Feature request for this extension
130+
- [#49](https://github.com/tikalk/agentic-sdlc-spec-kit/issues/49) - Skills discovery (format compatibility)
131+
- [#53](https://github.com/tikalk/agentic-sdlc-spec-kit/issues/53) - Git submodule for team-ai-directives
132+
- [#36](https://github.com/tikalk/agentic-sdlc-spec-kit/issues/36) - Convert architect commands to extension (pattern reference)
133+
134+
## License
135+
136+
MIT

0 commit comments

Comments
 (0)