Technical Design: github-issues-129-163-165

Technical Design: github-issues-129-163-165

Metadata

• Feature: github-issues-129-163-165
• Status: DRAFT
• Created: 2026-02-07
• Author: Factory Design Mode

1. Overview

1.1 Summary

Three prompt-level and one code-level change across ZERG's documentation, planning, and design commands. The --tone flag adds tone-controlled documentation generation to /zerg:document (with 3 tone definition files). Anti-implementation guards harden /z:plan against workflow drift. A new Section 11 in the plan template and mandatory doc tasks in the design command ensure documentation stays current. All project docs are updated to reflect these changes.

1.2 Goals

• Educational documentation as default output from /zerg:document
• Zero-tolerance plan→design→rush workflow boundary enforcement
• Documentation drift eliminated via systematic impact tracking

1.3 Non-Goals

• Python-level runtime enforcement of workflow boundaries (deferred)
• Programmatic tone transformation engine (tone is prompt-level)
• Splitting document.md (stays under 300 lines)

2. Architecture

2.1 High-Level Design

┌─────────────────────────────────────────────────────┐
│                 Slash Commands (prompt layer)        │
│                                                     │
│  ┌──────────┐  ┌──────────┐  ┌──────────────────┐  │
│  │ plan.md  │  │design.md │  │  document.md     │  │
│  │ +guards  │  │ +doc     │  │  +--tone flag    │  │
│  │          │  │  tasks   │  │  reads tone/*.md │  │
│  └──────────┘  └──────────┘  └──────────────────┘  │
│                                       │             │
│                              ┌────────▼─────────┐   │
│                              │ zerg/data/tones/  │   │
│                              │ ├ educational.md  │   │
│                              │ ├ reference.md    │   │
│                              │ └ tutorial.md     │   │
│                              └──────────────────┘   │
│                                                     │
│  ┌──────────────────────────────────────────────┐   │
│  │ zerg/commands/document.py  (+--tone option)  │   │
│  └──────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────┘

2.2 Component Breakdown

2.3 Data Flow

1. User invokes /zerg:document target --tone educational
2. Click parses --tone flag (default: educational)
3. Python passes tone to DocRenderer
4. Prompt layer reads zerg/data/tones/educational.md for style instructions
5. DocRenderer generates documentation following tone guidelines
6. Output to stdout or --output path

3. Detailed Design

3.1 Tone Flag (document.py)

@click.option(
    "--tone",
    type=click.Choice(["educational", "reference", "tutorial"]),
    default="educational",
    help="Documentation tone (default: educational)",
)

The tone string is passed to DocRenderer.render() and stored for prompt-layer use. The renderer loads the corresponding tone definition file.

3.2 Tone Definition Files

Each tone file at zerg/data/tones/{tone}.md contains:

• Tone name and description
• Output structure template
• Required sections per concept
• Example output format

Educational (default): CONCEPT → NARRATIVE → DIAGRAM → COMMAND sections for every concept. Explanatory, teaches "why" not just "what".

Reference: Terse tables, API signatures, parameter lists. Current behavior preserved for backward compatibility.

Tutorial: Step-by-step walkthrough with simulated dialogue, progressive complexity.

3.3 Plan Anti-Implementation Guards

Four guard locations in plan.core.md:

1. Top-of-file banner (existing, strengthen)
2. Before Phase 2 (new) — "DO NOT write code"
3. Before Phase 5 (new) — "DO NOT proceed to design"
4. Post-approval section (existing, strengthen) — "PLANNING COMPLETE" banner

Terminal output format:

═══════════════════════════════════════════════════════════════
                    ⛔ PLANNING COMPLETE ⛔
═══════════════════════════════════════════════════════════════

This command has finished. DO NOT proceed to implementation.
The user must manually run /z:design to continue.

EXIT NOW — do not write code, do not invoke other commands.
═══════════════════════════════════════════════════════════════

3.4 Documentation Impact Analysis (Section 11)

Added to plan.details.md requirements template after Section 10:

## 11. Documentation Impact Analysis

### 11.1 Files Requiring Documentation Updates
| File | Current State | Required Update | Priority |
|------|--------------|-----------------|----------|

### 11.2 Documentation Tasks for Design Phase
- [ ] CHANGELOG.md update task (ALWAYS required)
- [ ] README.md update (if applicable)
- [ ] Command reference updates (if command/flag functionality changed)
- [ ] CLAUDE.md update (if project conventions changed)
- [ ] Wiki updates (if user-facing behavior changed)

3.5 Mandatory Doc Tasks in Design

design.core.md gets a new subsection in Phase 2 requiring:

• CHANGELOG.md task ALWAYS in Level 5
• Doc update tasks when command/flag behavior changes

4. Key Decisions

4.1 Tone as Prompt-Level Directive

Context: Need to control documentation output style.

Options Considered:

1. Programmatic tone engine in Python: Complex, requires template system
2. Prompt-level directive via tone files: Simple, extensible, no code complexity
3. Hardcoded tone templates in renderer: Not extensible

Decision: Prompt-level directive (option 2)

Rationale: Adding a tone file = adding a new tone. No code changes needed. Claude reads the tone file and follows its instructions. This is the simplest approach that works.

Consequences: Tone quality depends on prompt engineering, not code logic. New tones are trivially added.

4.2 Guard Placement Strategy

Context: /z:plan sometimes auto-implements despite existing guard.

Options Considered:

1. Single stronger guard at top: Insufficient — Claude forgets by Phase 5
2. Redundant guards at 4 locations: Repetitive but effective
3. Python-level enforcement: Complex, requires intercepting tool calls

Decision: Redundant guards at 4 locations (option 2)

Rationale: Claude's context window means single guards get forgotten. Redundancy at decision boundaries (before code-touching phases) is the most cost-effective prevention.

Consequences: Slightly longer command file but well within 300-line split threshold.

5. Implementation Plan

5.1 Phase Summary

5.2 File Ownership

5.3 Dependency Graph

graph TD
    T001[TASK-001: Educational tone] --> T004[TASK-004: Document --tone flag]
    T002[TASK-002: Reference tone] --> T004
    T003[TASK-003: Tutorial tone] --> T004
    T004 --> T008[TASK-008: Unit tests]
    T005[TASK-005: Plan guards] --> T008
    T006[TASK-006: Plan Section 11] --> T008
    T007[TASK-007: Design doc tasks] --> T008
    T008 --> T009[TASK-009: Project docs batch 1]
    T008 --> T010[TASK-010: Project docs batch 2]
    T008 --> T011[TASK-011: Wiring verification]

6. Risk Assessment

7. Testing Strategy

7.1 Unit Tests

• --tone flag parsing: default (educational), explicit (reference, tutorial), invalid (error)
• --tone passed to renderer correctly
• Tone definition files exist at expected paths

7.2 Integration Tests

• validate_commands passes after all changes
• No drift in command files (Task tool references preserved)

7.3 Verification Commands

• python -m pytest tests/unit/test_document_tone.py -x -q
• python -m zerg.validate_commands
• grep -c "MUST NEVER" zerg/data/commands/plan.core.md (expect >= 4 guard markers)

8. Parallel Execution Notes

8.1 Safe Parallelization

• Level 1: 3 tone files, fully parallel, no shared files
• Level 2: 3 tasks modifying disjoint command files, fully parallel
• Level 3: 2 doc tasks modifying disjoint doc sets, fully parallel
• No two tasks modify the same file

8.2 Recommended Workers

• Minimum: 1 worker (sequential by level)
• Optimal: 3 workers (widest level is L1/L2 at 3 tasks)
• Maximum: 3 workers (only 3 parallel at widest)

8.3 Estimated Duration

• Single worker: ~80 min
• With 3 workers: ~45 min
• Speedup: ~1.8x

9. Consumer Matrix

10. Approval