diff --git a/CHANGELOG.md b/CHANGELOG.md index 96cfc60259..380c7b46ed 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,15 @@ All notable changes to the Specify CLI and templates are documented here. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to to [Semantic Versioning](https://semver.org/spec/v2.0.0/). +## [0.0.117] - 2026-03-09 + +### Changed + +- **LevelUp Command Rename**: Renamed `/levelup.spec` to `/levelup.specify` for consistency with `architect.specify` and full-verb naming convention + - Renamed command file `spec.md` β†’ `specify.md` + - Updated all internal references across extension files and documentation + - No backward compatibility - users must use `/levelup.specify` + ## [0.0.116] - 2026-03-08 ### Fixed @@ -335,7 +344,7 @@ Integrated upstream changes while preserving fork-specific features: - **LevelUp Extension**: Modularized `/spec.levelup` into dedicated extension with 5 CDR-based commands (#56) - `/levelup.init` - Brownfield codebase scan to discover Context Decision Records (CDRs) - `/levelup.clarify` - Resolve CDR ambiguities and accept/reject decisions - - `/levelup.spec` - Extract CDRs from current feature spec context (replaces old `/spec.levelup`) + - `/levelup.specify` - Extract CDRs from current feature spec context (replaces old `/spec.levelup`) - `/levelup.skills` - Build ONE skill at a time from accepted CDRs - `/levelup.implement` - Compile accepted CDRs into PR to team-ai-directives - CDRs stored in `.specify/memory/cdr.md` (similar to ADRs) @@ -345,7 +354,7 @@ Integrated upstream changes while preserving fork-specific features: ### Changed -- **CLI Help Text**: Updated `/spec.levelup` references to `/levelup.spec` in init command help and next steps panel +- **CLI Help Text**: Updated `/spec.levelup` references to `/levelup.specify` in init command help and next steps panel - **Context View Blackbox Enforcement**: Updated architect commands to strictly enforce blackbox system representation in Context View - System MUST appear as a single unified node (no internal components) - Only external actors (stakeholders/users) and external systems shown diff --git a/README.md b/README.md index 85ffc1715f..42e3071212 100644 --- a/README.md +++ b/README.md @@ -260,114 +260,34 @@ team-ai-directives/ ### Optional Architecture Support -The toolkit includes comprehensive architecture documentation support via the **Architect extension**. Architecture commands work in any project. +The toolkit includes comprehensive architecture documentation support via the **Architect extension**, which creates and manages Architecture Decision Records (ADRs) and Architecture Descriptions (AD.md) using the Rozanski & Woods methodology. > **Note**: The Architect extension is bundled and auto-installed during `specify init`. -#### Two-Level Architecture System +**Key Features:** +- **Two-level architecture** - System-level ADRs on main branch, feature-level ADRs on feature branches +- **Automatic integration** - Hooks create feature ADRs during `/spec.plan` and validate alignment +- **Greenfield & Brownfield** - `/architect.specify` for new projects, `/architect.init` for existing codebases -| Level | Location | ADR File | Architecture Description | Hook Timing | -|-------|----------|----------|--------------------------|--------------| -| **System** | Main branch | `memory/adr.md` | `AD.md` (root) | N/A | -| **Feature** | Feature branch | `specs/{feature}/adr.md` | `specs/{feature}/AD.md` | before_plan with architect extension | -| **Validation** | Plan level | READ-ONLY via architect.validate | Validates plan alignment | after_plan with architect extension | - -#### Architecture Workflow +**Quick Start:** ```bash -# Interactive PRD exploration to create system-level ADRs (greenfield) +# Greenfield: Create ADRs from PRD /architect.specify "B2B SaaS platform for real-time supply chain management" -# Reverse-engineer architecture from existing codebase (brownfield) -/architect.init "Django monolith with PostgreSQL, React frontend, deployed on AWS ECS" - -# Refine and clarify ADRs through targeted questions -/architect.clarify +# Brownfield: Reverse-engineer ADRs from code +/architect.init "Django monolith with PostgreSQL, React frontend" -# Generate full Architecture Description from ADRs +# Generate Architecture Description /architect.implement -# Then proceed with normal workflow -/spec.specify "Feature within this architecture" - -# Plan generation with architecture validation (if architect extension installed) -/spec.plan - - **before_plan hook** (architect extension): Create feature ADRs using architect.specify/clarify/implement - - **after_plan hook** (architect extension): Validate plan alignment using architect.validate --for-plan -``` - -**Architecture Integration via Hooks**: - -- **before_plan** (architect extension): Automatically creates feature ADRs if adr.md exists -- **after_plan** (architect extension): Validates plan alignment with architecture (READ-ONLY) -- Hooks only activate if architect extension installed and adr.md present - -#### Architecture Commands - -| Command | Description | -|---------|-------------| -| `architect.init` | Reverse-engineer architecture from existing codebase (brownfield) | -| `architect.specify` | Interactive PRD exploration to create system-level ADRs | -| `architect.clarify` | Refine ADRs through targeted clarification questions | -| `architect.implement` | Generate full Architecture Description (AD.md) from ADRs | -| `architect.analyze` | Validate ADR ↔ AD consistency and quality | -| `architect.validate` | READ-ONLY: Validate plan alignment with architecture (plan level) | - -**Feature Architecture Workflow**: - -Feature-level ADRs and AD.md are created automatically via architect extension hooks during `/spec.plan` execution (if architect is installed and system architecture exists). No manual --architecture flag needed for feature architecture generation. - -#### Architecture Configuration Options - -The architecture commands support additional configuration options for fine-tuned control: - -**Views Selection** (`--views`): - -- `core` (default) - Generate the essential 5 views: Context, Functional, Information, Development, Deployment -- `all` - Include all 7 views including Concurrency and Operational -- `concurrency,operational` - Custom selection (comma-separated), always includes core views - -```bash -# Default core views -/architect.init "E-commerce platform" - -# All views including concurrency and operational -/architect.init --views all "High-throughput trading system" - -# Custom selection -/architect.init --views concurrency "Real-time data processing pipeline" -``` - -**ADR Generation Heuristic** (`--adr-heuristic`): - -- `surprising` (default) - Only document decisions that deviate from obvious ecosystem defaults -- `all` - Document every architectural decision -- `minimal` - Document only high-risk or non-obvious decisions - -```bash -# Skip documenting obvious choices (PostgreSQL for relational data, React for SPA) -/architect.specify --adr-heuristic surprising "Standard web application" - -# Document every decision -/architect.specify --adr-heuristic all "Complex multi-tenant system" - -# Minimal documentation -/architect.specify --adr-heuristic minimal "Internal tool with simple requirements" +# Validate consistency +/architect.analyze ``` -#### Rozanski & Woods Viewpoints +**Commands:** `architect.init`, `architect.specify`, `architect.clarify`, `architect.implement`, `architect.analyze`, `architect.validate` -The `architect.*` commands generate documentation covering: - -1. **Context View** - System scope and external interactions -2. **Functional View** - Functional elements and responsibilities -3. **Information View** - Data storage, management, and flow -4. **Concurrency View** - Runtime processes and coordination -5. **Development View** - Code organization and CI/CD -6. **Deployment View** - Physical infrastructure and environments -7. **Operational View** - Operations, monitoring, and support - -Plus cross-cutting **Perspectives**: Security, Performance & Scalability +πŸ“– **Full documentation:** [extensions/architect/README.md](./extensions/architect/README.md) ### Framework Options @@ -465,14 +385,14 @@ Use **`/spec.trace`** to generate comprehensive AI session execution traces capt /spec.trace ``` -**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. +**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.specify` CDR extraction when present. ### 8. Level up and contribute knowledge -Use the **levelup extension** to extract patterns from your completed feature and contribute reusable knowledge back to your team's shared repository. +Use the **levelup extension** to extract patterns from your completed feature and contribute reusable knowledge back to your team's shared repository via Context Decision Records (CDRs). ```bash -/levelup.spec # Extract CDRs from current feature spec (after /implement) +/levelup.specify # Extract CDRs from current feature spec (after /implement) /levelup.clarify # Resolve ambiguities in discovered CDRs /levelup.skills python-patterns # Build a skill from accepted CDRs /levelup.implement # Create PR to team-ai-directives @@ -480,6 +400,10 @@ Use the **levelup extension** to extract patterns from your completed feature an For brownfield projects, use `/levelup.init` to scan the entire codebase for patterns. +**Commands:** `levelup.init`, `levelup.specify`, `levelup.clarify`, `levelup.skills`, `levelup.implement`, `levelup.trace` + +πŸ“– **Full documentation:** [extensions/levelup/README.md](./extensions/levelup/README.md) + For detailed step-by-step instructions, see our [comprehensive guide](./spec-driven.md). ## πŸ“½οΈ Video Overview @@ -806,22 +730,12 @@ Essential commands for the Spec-Driven Development workflow: | Command | Description | |--------------------------|-----------------------------------------------------------------------| -| `/architect.init` | Reverse-engineer architecture from codebase (brownfield) *(via architect extension)* | -| `/architect.specify` | Interactive PRD exploration to create ADRs *(via architect extension)* | -| `/architect.clarify` | Refine ADRs through clarification questions *(via architect extension)* | -| `/architect.implement`| Generate AD.md from ADRs *(via architect extension)* | -| `/architect.analyze` | Validate ADR <-> AD consistency *(via architect extension)* | | `/spec.constitution` | Create or update project governing principles and development guidelines | | `/spec.specify` | Define what you want to build (requirements and user stories) | | `/spec.plan` | Create technical implementation plans with your chosen tech stack & SYNC/ASYNC triage | | `/spec.tasks` | Generate actionable task lists for implementation | | `/spec.implement` | Execute all tasks to build the feature according to the plan with dual execution loops (SYNC/ASYNC modes) | -| `/spec.trace` | Generate AI session execution traces with decisions, patterns, and evidence (optional, enriches `/levelup.spec`) | -| `/levelup.spec` | Extract CDRs from current feature spec context (replaces old `/spec.levelup`) | -| `/levelup.init` | Discover CDRs from entire codebase (brownfield analysis) | -| `/levelup.clarify` | Resolve ambiguities in discovered CDRs | -| `/levelup.skills` | Build a single skill from accepted CDRs | -| `/levelup.implement` | Compile accepted CDRs into PR to team-ai-directives | +| `/spec.trace` | Generate AI session execution traces with decisions, patterns, and evidence (optional, enriches `/levelup.specify`) | #### Optional Commands @@ -833,6 +747,41 @@ Additional commands for enhanced quality and validation: | `/spec.analyze` | Cross-artifact consistency & coverage analysis (run after `/spec.tasks`, before `/spec.implement`) | | `/spec.checklist` | Generate custom quality checklists that validate requirements completeness, clarity, and consistency (like "unit tests for English") | +#### Extension Commands + +Commands provided by bundled extensions. See extension READMEs for full documentation. + +**Architect Extension** - [πŸ“– Documentation](./extensions/architect/README.md) + +| Command | Description | +|--------------------------|-----------------------------------------------------------------------| +| `/architect.init` | Reverse-engineer architecture from codebase (brownfield) | +| `/architect.specify` | Interactive PRD exploration to create ADRs (greenfield) | +| `/architect.clarify` | Refine ADRs through clarification questions | +| `/architect.implement`| Generate AD.md from ADRs | +| `/architect.analyze` | Validate ADR ↔ AD consistency | +| `/architect.validate` | Validate plan alignment with architecture (READ-ONLY) | + +**LevelUp Extension** - [πŸ“– Documentation](./extensions/levelup/README.md) + +| Command | Description | +|--------------------------|-----------------------------------------------------------------------| +| `/levelup.init` | Discover CDRs from entire codebase (brownfield analysis) | +| `/levelup.specify` | Extract CDRs from current feature spec context | +| `/levelup.clarify` | Resolve ambiguities in discovered CDRs | +| `/levelup.skills` | Build a single skill from accepted CDRs | +| `/levelup.implement` | Compile accepted CDRs into PR to team-ai-directives | +| `/levelup.trace` | Generate AI session execution traces | + +**TDD Extension** - [πŸ“– Documentation](./extensions/tdd/README.md) + +| Command | Description | +|--------------------------|-----------------------------------------------------------------------| +| `/tdd.plan` | Planning phase - design before coding | +| `/tdd.tasks` | Detect language/framework + generate hybrid tests | +| `/tdd.implement`| Execute REDβ†’GREENβ†’REFACTOR | +| `/tdd.validate` | Validate test quality | + ### Environment Variables | Variable | Description | diff --git a/docs/installation.md b/docs/installation.md index 8d4f5443e6..e30c7686bb 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -85,7 +85,7 @@ After initialization, you should see the following commands available in your AI - `/spec.plan` - Generate implementation plans - `/spec.tasks` - Break down into actionable tasks - `/spec.implement` - Execute implementation with SYNC/ASYNC dual execution loops -- `/levelup.spec` - Extract patterns from current feature and create CDRs for team knowledge +- `/levelup.specify` - Extract patterns from current feature and create CDRs for team knowledge - `/levelup.init` - Discover patterns from entire codebase (brownfield) - `/levelup.clarify` - Resolve ambiguities in discovered CDRs - `/levelup.implement` - Compile CDRs into PR to team-ai-directives diff --git a/docs/quickstart.md b/docs/quickstart.md index 5b7bb70da6..ab8107bc8a 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -89,8 +89,8 @@ This guide will help you get started with Spec-Driven Development using Agentic **Note:** The levelup extension runs inside the IDE and relies on the locally cloned directives repository from Stage 0. **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. -1. **Extract CDRs from Feature (`/levelup.spec`)** - **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. +1. **Extract CDRs from Feature (`/levelup.specify`)** + **Action:** Invoke `/levelup.specify` 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. **Purpose:** Captures coding patterns, best practices, and reusable knowledge from your completed implementation. 2. **Clarify and Accept (`/levelup.clarify`)** @@ -108,13 +108,13 @@ This guide will help you get started with Spec-Driven Development using Agentic **Example Commands:** ```text -/levelup.spec "Focus on the error handling patterns we developed" +/levelup.specify "Focus on the error handling patterns we developed" /levelup.clarify /levelup.skills python-error-handling /levelup.implement ``` -**Note:** For brownfield projects (scanning entire codebase without a feature context), use `/levelup.init` instead of `/levelup.spec`. +**Note:** For brownfield projects (scanning entire codebase without a feature context), use `/levelup.init` instead of `/levelup.specify`. **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. diff --git a/extensions/architect/README.md b/extensions/architect/README.md index d2451f02f4..18bd7bd160 100644 --- a/extensions/architect/README.md +++ b/extensions/architect/README.md @@ -60,6 +60,16 @@ Greenfield: /architect.specify --> /architect.clarify --> /architect.implement | Feature ADRs | `specs/{feature}/adr.md` | Feature-level decisions | | Feature AD | `specs/{feature}/AD.md` | Feature-level architecture | +## Two-Level Architecture System + +| Level | Location | ADR File | Architecture Description | Hook Timing | +|-------|----------|----------|--------------------------|--------------| +| **System** | Main branch | `memory/adr.md` | `AD.md` (root) | N/A | +| **Feature** | Feature branch | `specs/{feature}/adr.md` | `specs/{feature}/AD.md` | before_plan hook | +| **Validation** | Plan level | READ-ONLY via architect.validate | Validates plan alignment | after_plan hook | + +**Feature-level ADRs and AD.md** are created automatically via extension hooks during `/spec.plan` execution (if system architecture exists). + ## Installation The architect extension is **bundled by default** during project initialization: @@ -130,6 +140,40 @@ analysis: block_on_critical: true ``` +### Views Selection (`--views`) + +- `core` (default) - Generate the essential 5 views: Context, Functional, Information, Development, Deployment +- `all` - Include all 7 views including Concurrency and Operational +- `concurrency,operational` - Custom selection (comma-separated), always includes core views + +```bash +# Default core views +/architect.init "E-commerce platform" + +# All views including concurrency and operational +/architect.init --views all "High-throughput trading system" + +# Custom selection +/architect.init --views concurrency "Real-time data processing pipeline" +``` + +### ADR Generation Heuristic (`--adr-heuristic`) + +- `surprising` (default) - Only document decisions that deviate from obvious ecosystem defaults +- `all` - Document every architectural decision +- `minimal` - Document only high-risk or non-obvious decisions + +```bash +# Skip documenting obvious choices (PostgreSQL for relational data, React for SPA) +/architect.specify --adr-heuristic surprising "Standard web application" + +# Document every decision +/architect.specify --adr-heuristic all "Complex multi-tenant system" + +# Minimal documentation +/architect.specify --adr-heuristic minimal "Internal tool with simple requirements" +``` + ## ADR Format (MADR) Architecture Decision Records follow the MADR format: diff --git a/extensions/catalog.json b/extensions/catalog.json index 8d215e0294..69bca1c0bc 100644 --- a/extensions/catalog.json +++ b/extensions/catalog.json @@ -48,7 +48,7 @@ "commands": [ "adlc.levelup.init", "adlc.levelup.clarify", - "adlc.levelup.spec", + "adlc.levelup.specify", "adlc.levelup.skills", "adlc.levelup.implement", "adlc.levelup.trace" diff --git a/extensions/levelup/CHANGELOG.md b/extensions/levelup/CHANGELOG.md index 9b3cc060c7..1ba95a01a3 100644 --- a/extensions/levelup/CHANGELOG.md +++ b/extensions/levelup/CHANGELOG.md @@ -12,7 +12,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Initial release of LevelUp extension - `levelup.init` command for brownfield CDR discovery - `levelup.clarify` command for resolving CDR ambiguities -- `levelup.spec` command for refining CDRs from feature context +- `levelup.specify` command for refining CDRs from feature context - `levelup.skills` command for building skills from accepted CDRs - `levelup.implement` command for creating PRs to team-ai-directives - Context Directive Record (CDR) template diff --git a/extensions/levelup/README.md b/extensions/levelup/README.md index 0fd5283924..32c28636d2 100644 --- a/extensions/levelup/README.md +++ b/extensions/levelup/README.md @@ -12,7 +12,7 @@ The LevelUp extension helps brownfield projects analyze their codebase and contr |---------|---------| | `/levelup.init` | Scan codebase and discover CDRs (like `/architect.init`) | | `/levelup.clarify` | Resolve ambiguities in discovered CDRs (like `/architect.clarify`) | -| `/levelup.spec` | Refine CDRs using current feature spec context | +| `/levelup.specify` | Refine CDRs using current feature spec context | | `/levelup.skills` | Build a single skill from accepted CDRs | | `/levelup.implement` | Compile accepted CDRs into a PR to team-ai-directives | | `/levelup.trace` | Generate and validate AI session execution traces | @@ -130,7 +130,7 @@ levelup.init levelup.clarify levelup.skills levelup.imple (Discover CDRs) ───▢ (Resolve Ambiguities) ───▢ (Build Skills) ───▢ (Create PR) β”‚ β”‚ β”‚ β”‚ β”‚ [handoff] β”‚ [handoff] β”‚ β”‚ - └──▢ levelup.spec β—€β”€β”€β”€β”€β”˜ β”‚ β”‚ + └──▢ levelup.specify β—€β”€β”€β”€β”€β”˜ β”‚ β”‚ (Refine from β”‚ β”‚ feature context) β”‚ β”‚ β”‚ β”‚ @@ -142,7 +142,7 @@ levelup.init levelup.clarify levelup.skills levelup.imple β”‚ β”‚ [handoff] β–Ό - levelup.spec + levelup.specify (Extract CDRs with trace enrichment) ``` @@ -150,7 +150,7 @@ levelup.init levelup.clarify levelup.skills levelup.imple (Discover CDRs) ───▢ (Resolve Ambiguities) ───▢ (Build Skills) ───▢ (Create PR) β”‚ β”‚ β”‚ β”‚ β”‚ [handoff] β”‚ [handoff] β”‚ β”‚ - └──▢ levelup.spec β—€β”€β”€β”€β”€β”˜ β”‚ β”‚ + └──▢ levelup.specify β—€β”€β”€β”€β”€β”˜ β”‚ β”‚ (Refine from β”‚ β”‚ feature context) β”‚ β”‚ ``` diff --git a/extensions/levelup/commands/clarify.md b/extensions/levelup/commands/clarify.md index 20ff3cda0f..c4c2753c39 100644 --- a/extensions/levelup/commands/clarify.md +++ b/extensions/levelup/commands/clarify.md @@ -2,7 +2,7 @@ description: Resolve ambiguities in discovered/proposed CDRs through clarifying questions handoffs: - label: Refine from Feature Context - agent: adlc.levelup.spec + agent: adlc.levelup.specify prompt: Add context from current feature spec to CDRs send: false - label: Build Skills @@ -309,7 +309,7 @@ Present manual handoff options: ### Available Handoffs **Option 1: Refine from Feature Context** -Run `/levelup.spec` to: +Run `/levelup.specify` to: - Add evidence from current feature spec - Link CDRs to implementation @@ -340,7 +340,7 @@ Run `/levelup.implement` to: ## Related Commands - `/levelup.init` - Discover CDRs from codebase -- `/levelup.spec` - Refine CDRs from feature context +- `/levelup.specify` - Refine CDRs from feature context - `/levelup.skills` - Build skills from accepted CDRs - `/levelup.implement` - Create PR to team-ai-directives - `/architect.clarify` - Similar pattern for ADR clarification diff --git a/extensions/levelup/commands/implement.md b/extensions/levelup/commands/implement.md index ce3ece55ef..1165a91ee2 100644 --- a/extensions/levelup/commands/implement.md +++ b/extensions/levelup/commands/implement.md @@ -280,7 +280,7 @@ Context module contributions from **{project-name}**. These contributions were discovered and validated through: - `/levelup.init` - Brownfield codebase analysis - `/levelup.clarify` - Team validation -- `/levelup.spec` - Feature implementation evidence +- `/levelup.specify` - Feature implementation evidence ### Checklist @@ -422,5 +422,5 @@ For each implemented CDR: - `/levelup.init` - Discover CDRs from codebase - `/levelup.clarify` - Accept CDRs for implementation -- `/levelup.spec` - Enrich CDRs with feature context +- `/levelup.specify` - Enrich CDRs with feature context - `/levelup.skills` - Build skills from CDRs diff --git a/extensions/levelup/commands/init.md b/extensions/levelup/commands/init.md index 59b7542365..7d1d587119 100644 --- a/extensions/levelup/commands/init.md +++ b/extensions/levelup/commands/init.md @@ -13,7 +13,7 @@ handoffs: Focus on validating assumptions, not suggesting new patterns. send: false - label: Refine from Feature Context - agent: adlc.levelup.spec + agent: adlc.levelup.specify prompt: Refine CDRs using current feature spec context send: false scripts: @@ -47,7 +47,7 @@ Scan an **existing codebase** (brownfield) and discover patterns that could beco 1. **CDRs** documenting discovered context patterns in `.specify/memory/cdr.md` 2. **Summary** of discovered patterns by context type -3. **Manual handoff options** to `/levelup.clarify` or `/levelup.spec` +3. **Manual handoff options** to `/levelup.clarify` or `/levelup.specify` **Key Concept**: @@ -396,7 +396,7 @@ Run `/levelup.clarify` to: - Refine CDR content **Option 2: Refine from Feature Context** -Run `/levelup.spec` to: +Run `/levelup.specify` to: - Add context from current feature spec - Link CDRs to implementation evidence @@ -427,7 +427,7 @@ Run `/levelup.implement` to: ## Related Commands - `/levelup.clarify` - Resolve ambiguities in discovered CDRs -- `/levelup.spec` - Refine CDRs from feature context +- `/levelup.specify` - Refine CDRs from feature context - `/levelup.skills` - Build skills from accepted CDRs - `/levelup.implement` - Create PR to team-ai-directives - `/architect.init` - Similar pattern for ADR discovery diff --git a/extensions/levelup/commands/skills.md b/extensions/levelup/commands/skills.md index 751dd82d08..f3f30eda16 100644 --- a/extensions/levelup/commands/skills.md +++ b/extensions/levelup/commands/skills.md @@ -334,5 +334,5 @@ Check skill completeness: - `/levelup.init` - Discover CDRs from codebase - `/levelup.clarify` - Accept CDRs for skill building -- `/levelup.spec` - Enrich CDRs with feature context +- `/levelup.specify` - Enrich CDRs with feature context - `/levelup.implement` - Move skill to team-ai-directives diff --git a/extensions/levelup/commands/spec.md b/extensions/levelup/commands/specify.md similarity index 100% rename from extensions/levelup/commands/spec.md rename to extensions/levelup/commands/specify.md diff --git a/extensions/levelup/commands/trace.md b/extensions/levelup/commands/trace.md index 59d2b6bc12..576595cc7b 100644 --- a/extensions/levelup/commands/trace.md +++ b/extensions/levelup/commands/trace.md @@ -25,7 +25,7 @@ The `/levelup.trace` command generates comprehensive AI session execution traces **Structure**: Summary section (3-part narrative) + 5 technical sections (metadata and patterns) -**Note**: This command LevelUp extension. is part of the Run `/levelup.spec` after trace to extract CDRs with enriched context. +**Note**: This command LevelUp extension. is part of the Run `/levelup.specify` after trace to extract CDRs with enriched context. ## When to Use @@ -38,13 +38,13 @@ Run `/levelup.trace` after completing `/implement` to capture the full execution ↓ specs/{BRANCH}/trace.md created ↓ -/levelup.spec β†’ Consume trace for CDR extraction (optional) +/levelup.specify β†’ Consume trace for CDR extraction (optional) ``` **Best Practices**: - Run after all tasks complete and quality gates pass -- Generate before `/levelup.spec` for richer CDR extraction +- Generate before `/levelup.specify` for richer CDR extraction - Re-run to update trace as understanding evolves - Review trace for learning and knowledge transfer @@ -211,7 +211,7 @@ If validation fails (coverage <80%), show warnings and recommendations: - Detailed evidence linking - Rich context for knowledge sharing -**Both modes**: Trace is optional but valuable for learning and `/levelup.spec` enrichment. +**Both modes**: Trace is optional but valuable for learning and `/levelup.specify` enrichment. ## Key Features @@ -230,7 +230,7 @@ If validation fails (coverage <80%), show warnings and recommendations: **Integration Points**: -- `/levelup.spec` reads trace.md if exists (optional) +- `/levelup.specify` reads trace.md if exists (optional) - `/analyze` can validate trace completeness - Version-controlled with feature artifacts - Natural handoff to other LevelUp commands @@ -250,7 +250,7 @@ Result: specs/001-feature/trace.md created with 5 sections ```text User: /levelup.trace Agent: [Generates comprehensive trace] -User: /levelup.spec +User: /levelup.specify Agent: [Reads trace.md for enriched context packet] ``` @@ -290,7 +290,7 @@ Check execution metadata for corruption. - **Overwrite**: Previous trace replaced (single latest trace) - **Build Mode**: Supported - generates lightweight traces - **Spec Mode**: Supported - generates comprehensive traces -- **Optional**: Trace not required for workflow but enhances `/levelup.spec` +- **Optional**: Trace not required for workflow but enhances `/levelup.specify` - **Version Control**: Commit trace.md with feature implementation - **Extension**: This command is part of LevelUp extension for team learning @@ -310,12 +310,12 @@ Check execution metadata for corruption. --- -**Next Steps**: After generating trace, optionally run `/levelup.spec` to extract Context Directive Records (CDRs) from your completed feature for team-ai-directives contributions. The trace enriches CDR extraction with detailed execution context. +**Next Steps**: After generating trace, optionally run `/levelup.specify` to extract Context Directive Records (CDRs) from your completed feature for team-ai-directives contributions. The trace enriches CDR extraction with detailed execution context. ## Related Commands - `/levelup.init` - Discover CDRs from codebase - `/levelup.clarify` - Resolve ambiguities and accept CDRs -- `/levelup.spec` - Extract CDRs from feature context (uses trace if available) +- `/levelup.specify` - Extract CDRs from feature context (uses trace if available) - `/levelup.skills` - Build skills from accepted CDRs - `/levelup.implement` - Create PR to team-ai-directives diff --git a/extensions/levelup/extension.yml b/extensions/levelup/extension.yml index 4c3a2c3461..8c25d80e3c 100644 --- a/extensions/levelup/extension.yml +++ b/extensions/levelup/extension.yml @@ -32,10 +32,10 @@ provides: aliases: ["levelup.clarify"] # Refine CDRs from feature context - handoff only - - name: "adlc.levelup.spec" - file: "commands/spec.md" + - name: "adlc.levelup.specify" + file: "commands/specify.md" description: "Refine CDRs using current feature spec context (handoff from init/clarify)" - aliases: ["levelup.spec"] + aliases: ["levelup.specify"] # Build single skill from user input - name: "adlc.levelup.skills" @@ -69,13 +69,13 @@ handoffs: prompt: "Review discovered CDRs and resolve ambiguities" send: false - label: "Refine from Feature Context" - agent: "levelup.spec" + agent: "levelup.specify" prompt: "Refine CDRs using current feature spec context" send: false levelup.clarify: - label: "Refine from Feature Context" - agent: "levelup.spec" + agent: "levelup.specify" prompt: "Add context from current feature spec" send: false - label: "Build Skills" @@ -85,7 +85,7 @@ handoffs: levelup.trace: - label: "Extract CDRs from Trace" - agent: "levelup.spec" + agent: "levelup.specify" prompt: "Extract CDRs using trace.md for enriched context" send: false diff --git a/extensions/levelup/templates/trace-template.md b/extensions/levelup/templates/trace-template.md index 2947086270..023d5b9fc1 100644 --- a/extensions/levelup/templates/trace-template.md +++ b/extensions/levelup/templates/trace-template.md @@ -189,6 +189,6 @@ References to implementation artifacts, commits, issues, and code paths for trac **Trace Generation**: This trace was automatically generated from execution metadata and feature artifacts by the `/trace` command. For detailed implementation information, refer to the linked artifacts above. -**Usage**: This trace can be consumed by `/levelup.spec` for extracting Context Decision Records (CDRs) and analyzing contributions to team-ai-directives (rules, constitution, personas, examples, skills). +**Usage**: This trace can be consumed by `/levelup.specify` for extracting Context Decision Records (CDRs) and analyzing contributions to team-ai-directives (rules, constitution, personas, examples, skills). **Reusability**: Patterns and approaches documented here can inform similar implementations in other projects or features with comparable requirements. diff --git a/pyproject.toml b/pyproject.toml index 2dcaad7664..549c33f1d5 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "agentic-sdlc-specify-cli" -version = "0.0.116" +version = "0.0.117" description = "Specify CLI, part of GitHub Spec Kit. A tool to bootstrap your projects for Spec-Driven Development (SDD)." requires-python = ">=3.11" dependencies = [ diff --git a/roadmap.md b/roadmap.md index dd81b738b4..17d790588d 100644 --- a/roadmap.md +++ b/roadmap.md @@ -394,7 +394,7 @@ Feature-level architecture controlled via: - ❌ **Add --issue Parameter to Specify**: Implement `--issue ISSUE-ID` parameter for specify command to fetch issue data from configured tracker - ❌ **Store Issue Context Persistently**: Save issue ID, tracker type, and metadata in context.md for automatic propagation -- ❌ **Automatic Issue Propagation**: Subsequent commands (/clarify, /plan, /tasks, /analyze, /levelup.spec) automatically use stored issue context +- ❌ **Automatic Issue Propagation**: Subsequent commands (/clarify, /plan, /tasks, /analyze, /levelup.specify) automatically use stored issue context - ❌ **Dynamic MCP Tool Resolution**: Use declarative tools pattern with configuration-driven tool selection based on detected issue tracker - ❌ **Multi-Tracker Support**: Support GitHub/Jira/Linear/GitLab issue formats with appropriate MCP tool routing @@ -404,15 +404,15 @@ Feature-level architecture controlled via: - βœ… **Trace Validation Scripts**: Implemented validation for section completeness, coverage percentage, and quality gate statistics - βœ… **Command Template**: Created `/levelup.trace` command as part of LevelUp extension with generation and validation workflows - βœ… **Trace Template**: Defined 5-section trace structure (Session Overview, Decision Patterns, Execution Context, Reusable Patterns, Evidence Links) -- βœ… **Levelup Integration**: Modified `/levelup.spec` to consume trace.md if exists (optional enrichment) +- βœ… **Levelup Integration**: Modified `/levelup.specify` to consume trace.md if exists (optional enrichment) - βœ… **Mode Support**: Works in both build and spec modes with appropriate trace depth - βœ… **Storage Location**: Traces stored in specs/{BRANCH}/trace.md with feature artifacts - βœ… **Overwrite Behavior**: Re-running `/levelup.trace` overwrites previous trace (single latest version) - βœ… **Extension Migration**: Moved trace command to LevelUp extension for better integration with team learning workflow -**Purpose**: Generate comprehensive AI session execution traces for knowledge sharing, pattern identification, and learning. Traces capture decision-making patterns, execution outcomes, quality gate results, and evidence links. Optional but enriches `/levelup.spec` CDR extraction when present. +**Purpose**: Generate comprehensive AI session execution traces for knowledge sharing, pattern identification, and learning. Traces capture decision-making patterns, execution outcomes, quality gate results, and evidence links. Optional but enriches `/levelup.specify` CDR extraction when present. -**Workflow**: `/implement` β†’ `/levelup.trace` (generate session trace) β†’ `/levelup.spec` (consume trace for CDR extraction) +**Workflow**: `/implement` β†’ `/levelup.trace` (generate session trace) β†’ `/levelup.specify` (consume trace for CDR extraction) #### **Levelup Command Migration** *(100% Complete)* - **COMPLETED** - Removed build mode paths @@ -562,7 +562,7 @@ Consolidates: Command-level model selection + context budgeting + two-model revi - `/implement`: Default Sonnet β†’ Options: Opus (analysis), Haiku (lightweight) - `/analyze`: Default Opus β†’ Options: Sonnet (time-constrained) - `/trace`: Default Haiku β†’ Options: Sonnet (richer traces) - - `/levelup.spec`: Default Sonnet β†’ Options: Opus (comprehensive CDR extraction) + - `/levelup.specify`: Default Sonnet β†’ Options: Opus (comprehensive CDR extraction) - ❌ **Admin Commands**: - `/architect`: Default Sonnet β†’ Options: Opus (critical systems), Haiku (exploration) - `/constitution`: Default Sonnet β†’ Options: Opus (complex governance) @@ -958,7 +958,7 @@ Integrate Beads (native issue tracker) with `/tasks` command as dual-output syst - Complements `/trace` command (which captures session decisions) by making them queryable -- Enables future `/levelup.spec` enhancements (extract patterns from beads issue history) +- Enables future `/levelup.specify` enhancements (extract patterns from beads issue history) - Works with existing `/implement` (Phase 1) and enhances it (Phase 2-3) **References**: - Beads Article: [https://steve-yegge.medium.com/introducing-beads-a-coding-agent-memory-system-637d7d92514a](https://steve-yegge.medium.com/introducing-beads-a-coding-agent-memory-system-637d7d92514a) @@ -1391,7 +1391,7 @@ Integrate Beads (native issue tracker) with `/tasks` command as dual-output syst - Skill scaffolding: Auto-generate SKILL.md with trigger keywords, references, and scripts based on detected patterns - Contribution workflow: Create PR-ready skill packages with proper structure for team-ai-directives submission - Skill templates: Provide templates for common skill types (testing patterns, code generators, validation rules) - - Integration with `/levelup.spec`: Extract patterns from session traces and suggest CDR creation during levelup + - Integration with `/levelup.specify`: Extract patterns from session traces and suggest CDR creation during levelup - Quality validation: Ensure generated skills meet team-ai-directives standards before contribution #### **Resilience & Self-Healing** *(0% Complete)* - **MEDIUM PRIORITY** - Automation robustness diff --git a/tests/test_trace_command.py b/tests/test_trace_command.py index 4ad8e1362b..e7eab9d418 100755 --- a/tests/test_trace_command.py +++ b/tests/test_trace_command.py @@ -90,13 +90,13 @@ def test_levelup_integration(): """Test that levelup extension spec command references trace consumption""" repo_root = Path(__file__).parent.parent - # Levelup is now an extension at extensions/levelup/commands/spec.md - levelup_spec = repo_root / "extensions/levelup/commands/spec.md" - assert levelup_spec.exists(), f"Levelup spec command not found: {levelup_spec}" + # Levelup is now an extension at extensions/levelup/commands/specify.md + levelup_spec = repo_root / "extensions/levelup/commands/specify.md" + assert levelup_spec.exists(), f"Levelup specify command not found: {levelup_spec}" content = levelup_spec.read_text() - # Verify levelup.spec mentions trace + # Verify levelup.specify mentions trace assert "trace" in content.lower() or "TRACE" in content, ( "Levelup spec doesn't mention trace" )