feat(extensions): move trace command to levelup extension

kanfil · kanfil · commit 137ef11c93f4 · 2026-03-06T14:38:20.000+02:00
- Move trace command from templates/ to levelup extension
- Add trace command to extension.yml with /levelup.trace alias
- Create symlinks for trace scripts in extension folder
- Move trace-template.md to extension templates
- Add pre-installed extension banner to CLI init output
- Update catalog.json with trace command
- Update roadmap and tests for new locations
- Remove extension references from core CLI banner

BREAKING: /trace command now requires levelup extension
diff --git a/extensions/catalog.json b/extensions/catalog.json
@@ -21,7 +21,8 @@
         "adlc.levelup.clarify",
         "adlc.levelup.spec",
         "adlc.levelup.skills",
-        "adlc.levelup.implement"
+        "adlc.levelup.implement",
+        "adlc.levelup.trace"
       ],
       "tags": [
         "team-ai-directives",
diff --git a/extensions/levelup/README.md b/extensions/levelup/README.md
@@ -15,10 +15,21 @@ The LevelUp extension helps brownfield projects analyze their codebase and contr
 | `/levelup.spec` | 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 |
 
 ## Quick Start
 
-### 1. Initialize CDR Discovery
+### 1. Generate Session Trace (Optional but Recommended)
+
+After implementing a feature, generate a trace to document the session:
+
+```bash
+/levelup.trace
+```
+
+This creates `specs/{BRANCH}/trace.md` with execution summary.
+
+### 2. Initialize CDR Discovery
 
 Scan your codebase for patterns that could become team-wide directives:
 
@@ -114,6 +125,26 @@ pull_request:
 
 ## Command Flow
 
+```
+levelup.init          levelup.clarify        levelup.skills        levelup.implement
+(Discover CDRs)  ───▶  (Resolve Ambiguities) ───▶ (Build Skills)  ───▶ (Create PR)
+     │                      │                      │                      │
+     │    [handoff]         │    [handoff]         │                      │
+     └──▶ levelup.spec ◀────┘                      │                      │
+           (Refine from                             │                      │
+            feature context)                        │                      │
+                                                     │                      │
+                    ┌───────────────────────────────┘                      │
+                    │                                                      │
+                    ▼                                                      │
+             levelup.trace ◀───────────────────────────────────────────────┘
+             (Generate Trace)
+                    │
+                    │ [handoff]
+                    ▼
+             levelup.spec
+             (Extract CDRs with
+              trace enrichment)
 ```
 levelup.init          levelup.clarify        levelup.skills        levelup.implement
 (Discover CDRs)  ───▶  (Resolve Ambiguities) ───▶ (Build Skills)  ───▶  (Create PR)
diff --git a/extensions/levelup/commands/spec.md b/extensions/levelup/commands/spec.md
@@ -33,7 +33,7 @@ Extract **Context Directive Records (CDRs)** from the **current feature specific
 
 **Input**:
 - Current feature spec, plan, tasks (from `specs/{feature}/`)
-- Optional: `trace.md` if generated by `/trace` (enriches CDR extraction)
+- Optional: `trace.md` if generated by `/levelup.trace` (enriches CDR extraction)
 - Existing CDRs from `.specify/memory/cdr.md` (if any)
 
 **Output**: 
diff --git a/extensions/levelup/commands/trace.md b/extensions/levelup/commands/trace.md
@@ -10,7 +10,7 @@ validation_script:
 
 ## Overview
 
-The `/trace` command generates comprehensive AI session execution traces from implementation metadata and feature artifacts. Traces include a **human-friendly Summary** (Problem → Key Decisions → Final Solution) followed by detailed technical sections for tool integration and learning.
+The `/levelup.trace` command generates comprehensive AI session execution traces from implementation metadata and feature artifacts. Traces include a **human-friendly Summary** (Problem → Key Decisions → Final Solution) followed by detailed technical sections for tool integration and learning.
 
 **Purpose**:
 
@@ -25,14 +25,16 @@ The `/trace` command generates comprehensive AI session execution traces from im
 
 **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.
+
 ## When to Use
 
-Run `/trace` after completing `/implement` to capture the full execution session:
+Run `/levelup.trace` after completing `/implement` to capture the full execution session:
 
 ```text
 /implement → tasks_meta.json created
      ↓
-/trace → Generate session trace
+/levelup.trace → Generate session trace
      ↓
 specs/{BRANCH}/trace.md created
      ↓
@@ -187,10 +189,10 @@ If validation fails (coverage <80%), show warnings and recommendations:
 
 ```text
 ⚠️  Warnings:
-  - Reusable Patterns section missing or incomplete
-  
+   - Reusable Patterns section missing or incomplete
+   
 💡 Recommendations:
-  - Identify effective methodologies and applicable contexts
+   - Identify effective methodologies and applicable contexts
 ```
 
 ## Mode Awareness
@@ -222,7 +224,7 @@ If validation fails (coverage <80%), show warnings and recommendations:
 
 **Idempotent Operation**:
 
-- Re-running `/trace` overwrites previous trace
+- Re-running `/levelup.trace` overwrites previous trace
 - Always reflects latest execution state
 - Single trace.md per feature (latest)
 
@@ -231,21 +233,22 @@ If validation fails (coverage <80%), show warnings and recommendations:
 - `/levelup.spec` reads trace.md if exists (optional)
 - `/analyze` can validate trace completeness
 - Version-controlled with feature artifacts
+- Natural handoff to other LevelUp commands
 
 ## Common Scenarios
 
 ### Scenario 1: Post-Implementation Trace
 
 ```text
-User: /trace
+User: /levelup.trace
 Agent: [Generates trace from tasks_meta.json]
 Result: specs/001-feature/trace.md created with 5 sections
 ```
 
 ### Scenario 2: Trace Before Levelup
 
 ```text
-User: /trace
+User: /levelup.trace
 Agent: [Generates comprehensive trace]
 User: /levelup.spec
 Agent: [Reads trace.md for enriched context packet]
@@ -254,7 +257,7 @@ Agent: [Reads trace.md for enriched context packet]
 ### Scenario 3: Update Existing Trace
 
 ```text
-User: /trace
+User: /levelup.trace
 Agent: [Overwrites previous trace with latest execution data]
 Result: Updated trace reflects current implementation state
 ```
@@ -279,7 +282,7 @@ Check execution metadata for corruption.
 
 - Non-blocking: Trace still generated
 - Warnings displayed with recommendations
-- User can address gaps and re-run `/trace`
+- User can address gaps and re-run `/levelup.trace`
 
 ## Important Notes
 
@@ -289,6 +292,7 @@ Check execution metadata for corruption.
 - **Spec Mode**: Supported - generates comprehensive traces
 - **Optional**: Trace not required for workflow but enhances `/levelup.spec`
 - **Version Control**: Commit trace.md with feature implementation
+- **Extension**: This command is part of LevelUp extension for team learning
 
 ## Success Criteria
 
@@ -306,4 +310,12 @@ Check execution metadata for corruption.
 
 ---
 
-**Next Steps**: After generating trace, optionally run `/levelup.spec` to extract Context Decision 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.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.
+
+## 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.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
@@ -49,6 +49,12 @@ provides:
       description: "Compile accepted CDRs into a draft PR to team-ai-directives repository"
       aliases: ["levelup.implement"]
 
+    # Trace - Session execution tracing
+    - name: "adlc.levelup.trace"
+      file: "commands/trace.md"
+      description: "Generate and validate AI session execution traces from implementation metadata"
+      aliases: ["levelup.trace", "trace"]
+
   config:
     - name: "levelup-config.yml"
       template: "config-template.yml"
@@ -77,13 +83,21 @@ handoffs:
       prompt: "Build skills from accepted CDRs"
       send: false
 
+  levelup.trace:
+    - label: "Extract CDRs from Trace"
+      agent: "levelup.spec"
+      prompt: "Extract CDRs using trace.md for enriched context"
+      send: false
+
 tags:
   - "team-ai-directives"
   - "brownfield"
   - "context-modules"
   - "skills"
   - "cdr"
   - "contribution"
+  - "trace"
+  - "session-tracing"
 
 defaults:
   cdr:
diff --git a/extensions/levelup/scripts/bash/generate-trace.sh b/extensions/levelup/scripts/bash/generate-trace.sh
@@ -0,0 +1 @@
+../../../../scripts/bash/generate-trace.sh
diff --git a/extensions/levelup/scripts/bash/validate-trace.sh b/extensions/levelup/scripts/bash/validate-trace.sh
@@ -0,0 +1 @@
+../../../../scripts/bash/validate-trace.sh
diff --git a/extensions/levelup/scripts/powershell/generate-trace.ps1 b/extensions/levelup/scripts/powershell/generate-trace.ps1
@@ -0,0 +1 @@
+../../../../scripts/powershell/generate-trace.ps1
diff --git a/extensions/levelup/scripts/powershell/validate-trace.ps1 b/extensions/levelup/scripts/powershell/validate-trace.ps1
@@ -0,0 +1 @@
+../../../../scripts/powershell/validate-trace.ps1
diff --git a/extensions/levelup/templates/trace-template.md b/extensions/levelup/templates/trace-template.md
diff --git a/roadmap.md b/roadmap.md
@@ -423,20 +423,21 @@ Feature-level architecture controlled via:
 - ❌ **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
 
-#### **Session Trace Command (/trace)** *(100% Complete)* - **HIGH PRIORITY** - AI session documentation and learning
+#### **Session Trace Command (/levelup.trace)** *(100% Complete)* - **HIGH PRIORITY** - AI session documentation and learning
 
 - ✅ **Trace Generation Scripts**: Created bash and PowerShell scripts to generate traces from tasks_meta.json and feature artifacts
 - ✅ **Trace Validation Scripts**: Implemented validation for section completeness, coverage percentage, and quality gate statistics
-- ✅ **Command Template**: Created `/trace` command template with generation and validation workflows
+- ✅ **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)
 - ✅ **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 `/trace` overwrites previous trace (single latest version)
+- ✅ **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.
 
-**Workflow**: `/implement` → `/trace` (generate session trace) → `/levelup.spec` (consume trace for CDR extraction)
+**Workflow**: `/implement` → `/levelup.trace` (generate session trace) → `/levelup.spec` (consume trace for CDR extraction)
 
 #### **Levelup Command Build Mode Compatibility** *(100% Complete)* - **COMPLETED** - AI session context management
 
diff --git a/scripts/bash/validate-trace.sh b/scripts/bash/validate-trace.sh
@@ -44,7 +44,7 @@ if [[ ! -f "$TRACE_FILE" ]]; then
         printf '{"valid":false,"error":"Trace file not found: %s"}\n' "$TRACE_FILE"
     else
         echo "ERROR: Trace file not found: $TRACE_FILE" >&2
-        echo "Run /trace to generate a session trace." >&2
+        echo "Run /levelup.trace to generate a session trace." >&2
     fi
     exit 1
 fi
diff --git a/scripts/powershell/validate-trace.ps1 b/scripts/powershell/validate-trace.ps1
@@ -40,7 +40,7 @@ if (-not (Test-Path $TraceFile)) {
         } | ConvertTo-Json -Compress
         Write-Output $output
     } else {
-        Write-Error "Trace file not found: $TraceFile. Run /trace to generate a session trace."
+        Write-Error "Trace file not found: $TraceFile. Run /levelup.trace to generate a session trace."
     }
     exit 1
 }
diff --git a/src/specify_cli/__init__.py b/src/specify_cli/__init__.py
@@ -2961,6 +2961,43 @@ def install_bundled_extensions(
             tracker.skip("extensions", "none available")
 
 
+def get_preinstalled_extensions(project_path: Path) -> list[dict]:
+    """Get list of pre-installed extensions from catalog.json.
+
+    Returns list of dicts with: id, name, description, commands
+    """
+    extensions = []
+
+    # Check multiple locations for catalog
+    catalog_paths = [
+        project_path / ".specify" / "extensions" / "catalog.json",
+        Path(__file__).parent / "bundled_extensions" / "catalog.json",
+        Path(__file__).parent.parent.parent / "extensions" / "catalog.json",
+    ]
+
+    for catalog_path in catalog_paths:
+        if catalog_path.exists():
+            try:
+                with open(catalog_path) as f:
+                    catalog_data = json.load(f)
+
+                for ext_id, ext_data in catalog_data.get("extensions", {}).items():
+                    if ext_data.get("preinstall", False):
+                        extensions.append(
+                            {
+                                "id": ext_id,
+                                "name": ext_data.get("name", ext_id),
+                                "description": ext_data.get("description", ""),
+                                "commands": ext_data.get("commands", []),
+                            }
+                        )
+                break
+            except Exception:
+                continue
+
+    return extensions
+
+
 def _validate_ai_assistant(value: Optional[str]) -> Optional[str]:
     """Validate the ai_assistant option value."""
     if value is None:
@@ -3098,7 +3135,6 @@ def init(
     6. Optionally clone or reference a shared team-ai-directives repository
     7. Optionally configure MCP servers for issue tracker integration
     8. Optionally configure MCP servers for AI agent integration
-    9. Capture learnings after delivery with /levelup.spec
 
     Examples:
         specify init my-project
@@ -3669,28 +3705,19 @@ def init(
     steps_lines.append(f"{step_num}. Start using slash commands with your AI agent:")
 
     steps_lines.append(
-        f"   2.1 [{ACCENT_COLOR}]/architect.specify[/{ACCENT_COLOR}] - Interactive PRD exploration to create system ADRs"
-    )
-    steps_lines.append(
-        f"   2.2 [{ACCENT_COLOR}]/architect.implement[/{ACCENT_COLOR}] - Execute architecture implementation from ADRs"
+        f"   2.1 [{ACCENT_COLOR}]/spec.constitution[/{ACCENT_COLOR}] - Establish project principles"
     )
     steps_lines.append(
-        f"   2.3 [{ACCENT_COLOR}]/spec.constitution[/{ACCENT_COLOR}] - Establish project principles"
+        f"   2.2 [{ACCENT_COLOR}]/spec.specify[/{ACCENT_COLOR}] - Create baseline specification"
     )
     steps_lines.append(
-        f"   2.4 [{ACCENT_COLOR}]/spec.specify[/{ACCENT_COLOR}] - Create baseline specification"
+        f"   2.3 [{ACCENT_COLOR}]/spec.plan[/{ACCENT_COLOR}] - Create implementation plan"
     )
     steps_lines.append(
-        f"   2.5 [{ACCENT_COLOR}]/spec.plan[/{ACCENT_COLOR}] - Create implementation plan"
+        f"   2.4 [{ACCENT_COLOR}]/spec.tasks[/{ACCENT_COLOR}] - Generate actionable tasks"
     )
     steps_lines.append(
-        f"   2.6 [{ACCENT_COLOR}]/spec.tasks[/{ACCENT_COLOR}] - Generate actionable tasks"
-    )
-    steps_lines.append(
-        f"   2.7 [{ACCENT_COLOR}]/spec.implement[/{ACCENT_COLOR}] - Execute implementation"
-    )
-    steps_lines.append(
-        f"   2.8 [{ACCENT_COLOR}]/levelup.spec[/{ACCENT_COLOR}] - Extract learnings and create CDRs for team knowledge"
+        f"   2.5 [{ACCENT_COLOR}]/spec.implement[/{ACCENT_COLOR}] - Execute implementation"
     )
 
     steps_panel = Panel(
@@ -3718,6 +3745,37 @@ def init(
     console.print()
     console.print(enhancements_panel)
 
+    # Get pre-installed extensions and display their commands
+    preinstalled = get_preinstalled_extensions(project_path)
+
+    if preinstalled:
+        ext_lines = [
+            "Pre-installed extensions with additional commands:",
+            "",
+        ]
+
+        for ext in preinstalled:
+            ext_lines.append(f"[{ACCENT_COLOR}]📦 {ext['name']}[/{ACCENT_COLOR}]")
+            ext_lines.append(f"  {ext['description']}")
+            ext_lines.append("")
+            ext_lines.append("  Commands:")
+
+            for cmd in ext["commands"]:
+                # Convert command format: adlc.levelup.init -> /levelup.init
+                cmd_display = "/" + cmd.replace("adlc.", "").replace(".", ".")
+                ext_lines.append(f"    [{ACCENT_COLOR}]{cmd_display}[/{ACCENT_COLOR}]")
+
+            ext_lines.append("")  # Blank line between extensions
+
+        extensions_panel = Panel(
+            "\n".join(ext_lines[:-1]),  # Remove final blank line
+            title="Pre-Installed Extensions",
+            border_style=ACCENT_COLOR,
+            padding=(1, 2),
+        )
+        console.print()
+        console.print(extensions_panel)
+
     # Display recommended skills from team manifest if any
     if recommended_skills_info:
         skills_lines = [
diff --git a/tests/test_trace_command.py b/tests/test_trace_command.py

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+../../../../scripts/bash/generate-trace.sh`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+../../../../scripts/bash/validate-trace.sh`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+../../../../scripts/powershell/generate-trace.ps1`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+../../../../scripts/powershell/validate-trace.ps1`