Technical Design: z-shortcut-and-rename

Technical Design: z-shortcut-and-rename

Metadata

• Feature: z-shortcut-and-rename
• Status: DRAFT
• Created: 2026-01-30

1. Overview

1.1 Summary

Two coordinated changes: (1) generate z:*.md shortcut files that redirect to zerg:*.md slash commands, update install/uninstall to handle both prefixes; (2) rename troubleshoot → debug across all code, commands, docs, and tests (26+ files).

1.2 Goals

• /z:rush works identically to /zerg:rush for all 20 commands
• zerg debug replaces zerg troubleshoot at CLI
• Zero behavioral regression

1.3 Non-Goals

• Changing any diagnostic logic or test assertions
• Adding new troubleshoot/debug features
• Backward compat alias (old name simply stops existing)

2. Architecture

2.1 /z Shortcut Approach

Each z:*.md file is a thin redirect that includes the full zerg:*.md content. Implementation:

# zerg/data/commands/z:rush.md (generated)
<!-- Z-SHORTCUT: This is a shortcut for /zerg:rush -->
<!-- Auto-generated by ZERG. Do not edit directly. Edit zerg:rush.md instead. -->

<command-name>/z:rush</command-name>
<import>zerg:rush</import>

However, Claude Code slash commands don't support <import>. The practical approach:

Option A: Duplicate content (bloat, drift risk) Option B: Generate z:*.md at install time by copying content with zerg: → z: in the command-name tag Option C: Symlink z:rush.md → zerg:rush.md (simplest, no drift)

Decision: Option C — Symlinks. install-commands already uses symlinks. Each z:*.md symlinks to the corresponding zerg:*.md source file. The slash command system reads the file content regardless of name. The file name determines the command prefix (z:rush vs zerg:rush), but the content is shared.

2.2 Install Commands Changes

# Current: COMMAND_GLOB = "zerg:*.md"
# New: Also generate z:*.md symlinks pointing to zerg:*.md source files

def _install(...):
    # 1. Install zerg:*.md as before
    # 2. For each zerg:*.md, create z:*.md symlink → same source

2.3 Rename Strategy

Pure file rename + find-and-replace. No architectural changes.

Rename map:

Symbol renames:

3. Key Decisions

Decision: Symlinks for /z shortcuts

Context: Need /z:rush to behave identically to /zerg:rush. Options: (1) Duplicate files, (2) Generate at install, (3) Symlink Decision: Symlink. z:rush.md → zerg:rush.md in the install target directory. Rationale: Zero drift, zero maintenance, install-commands already uses symlinks.

Decision: No backward compat for troubleshoot

Context: Keep old name as alias? Decision: No. Clean break. zerg troubleshoot → error. Rationale: Backlog item explicitly says "rename", not "alias". Keeping both adds confusion.

4. Implementation Plan

Phase Summary

File Ownership

Dependency Graph

L1: ZR-L1-001 (rename cmd file) ──┐
    ZR-L1-002 (install_commands)──┤
                                   │
L2: ZR-L2-001 (__init__.py)      ─┤─ depends on L1
    ZR-L2-002 (cli.py)           ─┤
    ZR-L2-003 (slash cmd)        ─┤
    ZR-L2-004 (diagnostics refs) ─┘
                                   │
L3: ZR-L3-001 (unit tests)      ─┤─ depends on L2
    ZR-L3-002 (integration tests)─┤
    ZR-L3-003 (diag test refs)   ─┘
                                   │
L4: ZR-L4-001 (docs)            ─┤─ depends on L3
    ZR-L4-002 (project docs)    ─┘
                                   │
L5: ZR-L5-001 (quality gates)   ──┘─ depends on L4

5. Risk Assessment

6. Parallel Execution Notes

Recommended Workers

• Minimum: 2 workers
• Optimal: 4 workers (widest level is L2 with 4 tasks)
• Maximum: 4 workers

7. Approval