Technical Design: Command Authoring Framework (GitHub Issue #64)

Technical Design: Command Authoring Framework (GitHub Issue #64)

Metadata

• Feature: github-issue-64
• Status: APPROVED
• Created: 2026-02-04
• Author: Factory Design Mode

1. Overview

1.1 Summary

Extend ZERG's command validation infrastructure with authoring capabilities: scaffold new commands from templates with Task ecosystem boilerplate, validate required sections and patterns, generate pressure test scaffolds, and auto-generate documentation.

1.2 Goals

• Reduce command authoring friction (copy → scaffold, validate → live feedback)
• Prevent Task ecosystem drift via automated pattern validation
• Enable behavioral testing via pressure test framework
• Keep documentation in sync via auto-generation

1.3 Non-Goals

• GUI/TUI authoring interface
• AI-assisted command generation
• Automatic migration of old command formats

2. Architecture

2.1 High-Level Design

┌─────────────────────────────────────────────────────────────┐
│                    /zerg:create-command                     │
│                   (slash command file)                      │
└────────────────────────┬────────────────────────────────────┘
                         │ invokes
                         ▼
┌─────────────────────────────────────────────────────────────┐
│               validate_commands.py (extended)               │
│  ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐│
│  │ Validation  │ │  Scaffold   │ │   Documentation Gen     ││
│  │  (existing) │ │  (new)      │ │   (new)                 ││
│  └─────────────┘ └─────────────┘ └─────────────────────────┘│
└─────────────────────────────────────────────────────────────┘
                         │ writes
                         ▼
┌─────────────────────────────────────────────────────────────┐
│                    Generated Artifacts                       │
│  ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐│
│  │ {cmd}.md    │ │test_{cmd}.py│ │ docs/commands/{cmd}.md  ││
│  │ (+.core.md) │ │ (pressure)  │ │ (+wiki index update)    ││
│  └─────────────┘ └─────────────┘ └─────────────────────────┘│
└─────────────────────────────────────────────────────────────┘

2.2 Component Breakdown

2.3 Data Flow

1. User invokes /zerg:create-command foo
2. Command reads _template.md
3. Replaces placeholders with command metadata
4. Injects Task tracking boilerplate
5. Writes foo.md (and .core.md/.details.md if >300 lines)
6. Generates tests/pressure/test_foo.py scaffold
7. Generates docs/commands/foo.md reference
8. Updates docs/commands.md index

3. Detailed Design

3.1 Scaffold Generator

# In validate_commands.py

class ScaffoldGenerator:
    """Generate command files from _template.md."""

    def __init__(self, commands_dir: Path):
        self.commands_dir = commands_dir
        self.template_path = commands_dir / "_template.md"

    def scaffold(
        self,
        name: str,
        description: str = "",
        flags: list[dict] | None = None,
        interactive: bool = False,
    ) -> Path:
        """Generate command file from template.

        Args:
            name: Command name (e.g., "my-command")
            description: One-line description
            flags: List of {name, default, description} dicts
            interactive: If True, prompt for missing metadata

        Returns:
            Path to created command file
        """
        ...

3.2 Section Validator

Required sections (configurable):

• Pre-Flight or Pre-flight: Setup and validation logic
• Task Tracking: TaskCreate/TaskUpdate pattern
• Help: Help text for --help flag

REQUIRED_SECTIONS = {
    "pre-flight": ["Pre-Flight", "Pre-flight", "Preflight"],
    "task_tracking": ["Task Tracking"],
    "help": ["Help"],
}

def validate_required_sections(filepath: Path) -> tuple[bool, list[str]]:
    """Check that required sections exist in command file."""
    ...

3.3 Task Pattern Checker

Validates Task ecosystem integration matches minimum pattern:

TASK_PATTERN_RULES = [
    {
        "name": "lifecycle_start",
        "pattern": r"TaskCreate:\s*\n\s*-\s*subject:",
        "message": "Missing TaskCreate with subject field",
    },
    {
        "name": "lifecycle_update",
        "pattern": r"TaskUpdate:\s*\n\s*-\s*taskId:",
        "message": "Missing TaskUpdate with taskId field",
    },
    {
        "name": "status_in_progress",
        "pattern": r'status:\s*["']?in_progress',
        "message": "Missing status: in_progress transition",
    },
    {
        "name": "status_completed",
        "pattern": r'status:\s*["']?completed',
        "message": "Missing status: completed transition",
    },
]

3.4 Pressure Test Scaffold

Generated test structure:

# tests/pressure/test_{name}.py
"""Pressure tests for /zerg:{name} command."""

import pytest
from pathlib import Path

COMMAND_FILE = Path("zerg/data/commands/{name}.md")


class TestCommand{Name}:
    """Verify /zerg:{name} command behavior."""

    def test_command_file_exists(self):
        """Command file must exist."""
        assert COMMAND_FILE.exists()

    def test_passes_validation(self):
        """Command must pass validate_commands checks."""
        from zerg.validate_commands import validate_task_references
        passed, errors = validate_task_references(COMMAND_FILE.parent)
        # Filter to just this command
        relevant = [e for e in errors if "{name}" in e]
        assert not relevant, relevant

    def test_has_required_sections(self):
        """Command must have Pre-Flight, Task Tracking, Help."""
        content = COMMAND_FILE.read_text()
        assert "## Pre-Flight" in content or "## Pre-flight" in content
        assert "## Task Tracking" in content
        assert "## Help" in content

    @pytest.mark.skip(reason="Pressure test - manual verification")
    def test_execution_without_command(self):
        """Verify behavior when command not loaded."""
        # TODO: Implement pressure test
        pass

    @pytest.mark.skip(reason="Pressure test - manual verification")
    def test_execution_with_command(self):
        """Verify behavior when command is loaded."""
        # TODO: Implement pressure test
        pass

3.5 Documentation Generator

class DocGenerator:
    """Generate documentation from command files."""

    def __init__(self, commands_dir: Path, docs_dir: Path):
        self.commands_dir = commands_dir
        self.docs_dir = docs_dir

    def generate_command_doc(self, name: str) -> Path:
        """Generate docs/commands/{name}.md from command file."""
        ...

    def update_wiki_index(self, name: str, description: str) -> None:
        """Add entry to docs/commands.md index."""
        ...

    def extract_help_text(self, filepath: Path) -> str:
        """Extract help block from command file."""
        ...

4. Key Decisions

4.1 Extend validate_commands.py vs New Module

Context: Requirements specify authoring functions in validate_commands.py.

Options Considered:

1. New module (zerg/command_authoring.py): Cleaner separation
2. Extend validate_commands.py: Single source of truth, specified in requirements

Decision: Extend validate_commands.py

Rationale: Requirements explicitly state "Extend existing validate_commands.py (single source of truth)" (NFR-1). Keeps validation and authoring co-located.

Consequences: validate_commands.py grows from 630 to ~900 lines. Consider splitting later if maintenance burden increases.

4.2 Pressure Tests Optional

Context: Should pressure tests be required to ship commands?

Decision: Optional (FR-3.4)

Rationale: Passing pressure tests NOT required to ship. Framework provides scaffolds and basic structural tests that run, but behavioral tests require human judgment.

5. Implementation Plan

5.1 Phase Summary

5.2 File Ownership

5.3 Consumer Matrix

5.4 Dependency Graph

graph TD
    T001[TASK-001: ScaffoldGenerator] --> T005[TASK-005: create-command.md]
    T002[TASK-002: SectionValidator] --> T001
    T003[TASK-003: TaskPatternChecker] --> T001
    T004[TASK-004: DocGenerator] --> T005
    T005 --> T006[TASK-006: pressure test]
    T005 --> T007[TASK-007: docs reference]
    T001 --> T008[TASK-008: unit tests]
    T005 --> T009[TASK-009: integration tests]

6. Risk Assessment

7. Testing Strategy

7.1 Unit Tests

• ScaffoldGenerator.scaffold() creates valid file
• SectionValidator detects missing sections
• TaskPatternChecker finds missing patterns
• DocGenerator extracts correct content

7.2 Integration Tests

• Full authoring flow: scaffold → validate → generate docs
• Generated command passes validation
• Pressure test scaffold is runnable

7.3 Verification Commands

# Unit tests
pytest tests/unit/test_scaffold_generator.py -v

# Integration tests
pytest tests/integration/test_authoring_flow.py -v

# Validation check
python -m zerg.validate_commands

# Full test suite
pytest tests/ -x --timeout=60

8. Parallel Execution Notes

8.1 Safe Parallelization

• Level 1 (Foundation): TASK-002, TASK-003 can run in parallel (no shared files)
• Level 2 (Core): TASK-001, TASK-004 can run after L1 completes
• Level 3 (Integration): TASK-005 after L2 completes
• Level 4 (Testing): TASK-006, TASK-007, TASK-008, TASK-009 can run in parallel

8.2 Recommended Workers

• Minimum: 2 workers
• Optimal: 4 workers (based on widest level)
• Maximum: 4 workers (diminishing returns beyond)

9. Approval