sdd-render

name	sdd-render
description	Render JSON specs to human-readable markdown with AI-enhanced insights, visualizations, and progressive disclosure

Spec Rendering Skill

Overview

Transform JSON specification files into beautifully formatted, human-readable markdown documentation. The sdd-render skill bridges the gap between machine-readable specs and human comprehension, making it easy to review progress, share status, and understand project structure at a glance.

Features:

• Markdown generation - Convert JSON specs to formatted markdown with progress tracking
• Visual progress indicators - Status icons and percentage completion for phases/tasks
• Dependency visualization - Show task dependencies and blockers
• Hierarchical structure - Phases, groups, tasks, and subtasks clearly organized
• Metadata display - Estimates, complexity, reasoning, and file paths
• Multiple output destinations - Default location or custom paths via --output flag

Core Workflow

⚠️ CRITICAL REQUIREMENT: MANDATORY PRE-EXECUTION CHECKLIST ⚠️

Before executing ANY sdd render command, you MUST complete this validation:

┌─────────────────────────────────────────────────────────────┐
│ PRE-EXECUTION DECISION TREE (MANDATORY)                     │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│ ❓ Has user EXPLICITLY specified a rendering mode?         │
│    (e.g., "use basic mode", "render with full AI")         │
│                                                             │
│         YES ─────────┐              NO                      │
│                      │               │                      │
│                      │               ▼                      │
│                      │      ✋ STOP - DO NOT RENDER YET     │
│                      │               │                      │
│                      │               ▼                      │
│                      │      🔴 REQUIRED ACTION:            │
│                      │         Use AskUserQuestion tool     │
│                      │         to ask for mode preference   │
│                      │               │                      │
│                      │               ▼                      │
│                      └──────────► ✅ Proceed with render    │
│                                                             │
└─────────────────────────────────────────────────────────────┘

CRITICAL: Always Ask User for Rendering Mode

Unless the user has explicitly specified a rendering mode in their request, you MUST use the AskUserQuestion tool to ask which mode they want:

Example Usage:

AskUserQuestion(
  questions: [{
    question: "Which rendering mode would you like to use?",
    header: "Render Mode",
    multiSelect: false,
    options: [
      {
        label: "Basic (fast, no AI)",
        description: "Quick rendering without AI features (< 2 seconds)"
      },
      {
        label: "Enhanced - Summary",
        description: "Executive summary with AI (~1-2 minutes)"
      },
      {
        label: "Enhanced - Standard (recommended)",
        description: "Balanced AI features (~3-5 minutes) [DEFAULT]"
      },
      {
        label: "Enhanced - Full",
        description: "Complete AI analysis (~5-8 minutes)"
      },
      {
        label: "Generate all versions for comparison",
        description: "Creates basic, standard, and full versions"
      }
    ]
  }]
)

When to skip asking:

• User explicitly requested a mode: "render with basic mode", "use full AI enhancement"
• User requested multiple versions: "generate all three versions", "compare enhancement levels"
• User is batch rendering multiple specs (use default enhanced standard)

After getting the answer:

• Map user's choice to the appropriate CLI flags
• Execute sdd render with the selected mode
• Report the rendering time and output location

---

❌ ANTI-PATTERNS: What NOT to Do

WRONG APPROACH #1: Immediate execution without asking

User: "Let's call the sdd-render skill for /path/to/spec.json"

❌ Assistant: I'll render the specification file for you.
   [Immediately executes: sdd render /path/to/spec.json]

   PROBLEM: Skipped asking about rendering mode preference

CORRECT APPROACH #1: Ask first, then execute

User: "Let's call the sdd-render skill for /path/to/spec.json"

✅ Assistant: I'll help you render that specification. First, let me ask
   which rendering mode you'd like to use.
   [Uses AskUserQuestion tool to present mode options]
   [After user answers, executes with chosen mode]

---

WRONG APPROACH #2: Assuming default is okay

User: "Can you render this spec?"

❌ Assistant: I'll use the default enhanced standard mode.
   [Executes without asking]

   PROBLEM: Assumed user wants default without confirming

CORRECT APPROACH #2: Explicit confirmation

User: "Can you render this spec?"

✅ Assistant: Which rendering mode would you prefer?
   [Presents options with AskUserQuestion]
   [User selects mode]
   [Executes with selected mode]

---

ONLY ACCEPTABLE: User explicitly specifies mode

User: "Render this spec with basic mode for speed"

✅ Assistant: I'll render using basic mode as you requested.
   [Executes: sdd render <spec-id> --mode basic]

   REASON: User explicitly specified "basic mode" - no need to ask

3-Phase Process:

1. Prepare - Ask user for mode (unless explicit), locate spec file, verify output destination
2. Render - Execute sdd render with appropriate flags based on user choice
3. Review/Share - View output and distribute as needed

Key principles:

• Rendering is read-only - Never modifies source JSON specs
• Output customization - Use --output for specific destinations
• Batch operations - Process multiple specs when needed
• Always render AFTER updates - Let other skills modify specs first, then render
• Always ask for mode - Unless explicitly specified by user

Quick decision guide:

• ✅ Need quick status check? → Ask user, they might want basic mode for speed
• ✅ Sharing with team? → Ask user, they might want enhanced standard
• ✅ Multiple specs? → Use default enhanced standard for batch operations
• ❌ Need to modify spec? → Use Skill(sdd-toolkit:sdd-plan) instead
• ❌ Need to update tasks? → Use sdd-update-subagent first, then render

Skill Family

This skill is part of the Spec-Driven Development family:

• Skill(sdd-toolkit:sdd-plan) - Creates specifications and task hierarchies
• Skill(sdd-toolkit:sdd-next) - Identifies next tasks and creates execution plans
• Skill(sdd-toolkit:sdd-render) (this skill) - Renders JSON specs to human-readable formats
• sdd-update-subagent - Updates task and spec progress

Use This Skill When

Reporting and Communication:

• Need to review a spec's overall structure and progress quickly
• Want to share spec status with team members or stakeholders
• Creating documentation for project planning meetings
• Generating weekly/monthly progress reports
• Onboarding new developers to understand project scope

Analysis and Planning:

• Analyzing task dependencies visually before starting work
• Identifying blockers across multiple phases
• Understanding critical path and task relationships
• Reviewing spec structure for completeness
• Validating phase organization and task breakdown

Documentation:

• Creating permanent records of project plans
• Archiving completed specifications for reference
• Generating proposals or estimates from specs
• Producing client-facing project timelines

Decision Matrix

Rendering Scope Decision

Scenario	Action	Why
Single active spec review	sdd render {spec-id}	Quick status check
All active specs status	Batch render all active specs	Comprehensive project overview
Client presentation	sdd render {spec-id} --output client/report.md	Professional delivery
Debugging spec structure	sdd render {spec-id} --verbose	Detailed diagnostics
Daily standup prep	Render + grep for progress	Extract quick metrics
Post-update verification	Render after sdd-update	Visualize changes

Output Destination Decision

Audience	Destination	Format Considerations
Development team	specs/.human-readable/ (default)	Version controlled, easy access
Stakeholders	docs/reports/ or docs/status/	Permanent documentation location
Clients	Custom path + PDF conversion	Professional presentation format
CI/CD pipelines	stdout (--output -)	Pipeline integration, no file I/O
Archive	docs/archive/ with timestamp	Historical record keeping

Troubleshooting Decision Tree

When rendering fails, check in order:

1. Spec file exists?

   • ❌ No → Use sdd find-specs --verbose to locate
   • ✅ Yes → Continue to step 2

2. JSON is valid?

   • Test: python3 -m json.tool <spec-file>.json
   • ❌ Invalid → Fix JSON syntax or regenerate with sdd-plan
   • ✅ Valid → Continue to step 3

3. Output directory writable?

   • Test: ls -la $(dirname <output-path>)
   • ❌ No permission → Create directory or use default location
   • ✅ Writable → Continue to step 4

4. Still failing?

   • Run with --debug flag for detailed error messages
   • Check Troubleshooting section (line 799) for specific errors
   • Verify sdd CLI is properly installed: sdd render --help

Do NOT Use For

Spec Modification:

• Creating new specifications (use Skill(sdd-toolkit:sdd-plan))
• Updating task status or progress (use sdd-update-subagent)
• Modifying spec structure or metadata (use Skill(sdd-toolkit:sdd-plan))
• Adding or removing tasks (use Skill(sdd-toolkit:sdd-plan))

Task Execution:

• Finding next tasks to work on (use Skill(sdd-toolkit:sdd-next))
• Creating execution plans (use Skill(sdd-toolkit:sdd-next))
• Actually implementing code (use appropriate coding tools)
• Running tests or verification (use Skill(sdd-toolkit:run-tests))

Other:

• Writing conceptual documentation (tutorials, guides)
• Generating code or test files
• Real-time collaboration (this creates static snapshots)

Tool Verification

Before using this skill, verify the required tools are available:

# Verify sdd render command is installed
sdd render --help

Expected output: Help text showing available options for the render command

IMPORTANT - CLI Usage Only:

• ✅ DO: Use sdd render CLI command (e.g., sdd render {spec-id})
• ❌ DO NOT: Execute Python scripts directly (e.g., python cli.py, python renderer.py)

The CLI provides proper error handling, validation, argument parsing, and interface consistency. Direct script execution bypasses these safeguards and may fail.

If the verification command fails, ensure the SDD toolkit is properly installed and accessible in your environment.

Agent Boundaries

CRITICAL: This skill is READ-ONLY

This skill transforms JSON specs into markdown. It NEVER modifies the source specification files or any code.

MANDATORY: Pre-Execution Mode Selection

Before executing ANY render command, you MUST ask the user for their preferred rendering mode using the AskUserQuestion tool (unless the user explicitly specified a mode in their request). This is a non-negotiable requirement of the skill contract. See the Pre-Execution Decision Tree in the Core Workflow section above.

What this skill does:

• ✅ Reads JSON spec files from specs/active, specs/completed, specs/archived
• ✅ Generates markdown output files
• ✅ Writes to specs/.human-readable/ or custom --output path
• ✅ Displays progress, dependencies, and task metadata

What this skill NEVER does:

• ❌ Modifies source JSON spec files
• ❌ Updates task status or completion timestamps
• ❌ Creates or modifies code files
• ❌ Changes spec metadata or structure
• ❌ Executes tests or verification steps

Handoff Points - When to Use Other Skills:

After successful rendering:

1. Spec structure looks wrong?

   • → Hand off to Skill(sdd-toolkit:sdd-plan) to modify spec structure
   • Example: Missing phases, incorrect task organization

2. Task status needs updating?

   • → Hand off to sdd-update-subagent to update progress
   • Example: Mark tasks as completed, update timestamps
   • IMPORTANT: Update first, THEN render to visualize changes

3. Ready to implement tasks?

   • → Hand off to Skill(sdd-toolkit:sdd-next) to identify next task
   • Example: Need execution plan with gathered context

4. Need to verify implementation?

   • → Hand off to Skill(sdd-toolkit:run-tests) to run tests
   • Example: Run verification steps from spec

5. Output is satisfactory?

   • → Done, no further action needed
   • Share the rendered markdown as needed

Never chain this skill with spec modification:

• ❌ Wrong: Update task status → Render (race condition risk)
• ✅ Correct: Use sdd-update-subagent → Then render separately

Always render AFTER making changes:

• Create new spec with sdd-plan → Render to review
• Complete tasks with sdd-update → Render to visualize progress
• Major spec updates → Render to verify changes

Consultation is never required for rendering:

• Rendering is a deterministic transformation (JSON → Markdown)
• If rendering fails, use Troubleshooting Decision Tree (line 102)
• No external tool consultation needed for render operations

---

Quick Start

Execution Workflow:

1. Ask user for mode preference (unless they explicitly specified):

   • Use AskUserQuestion tool (see example in Core Workflow section above)
   • Present the 5 mode options

2. Execute the appropriate command based on user's answer:

   If user chose "Basic (fast, no AI)":

   sdd render {spec-id} --mode basic
   # ~2 seconds
   

   If user chose "Enhanced - Summary":

   sdd render {spec-id} --enhancement-level summary
   # ~1-2 minutes
   # Note: --mode enhanced is implied when --enhancement-level is specified
   

   If user chose "Enhanced - Standard" (or didn't specify):

   sdd render {spec-id}
   # Default: enhanced mode with standard level (~3-5 minutes)
   # Equivalent to: sdd render {spec-id} --enhancement-level standard
   

   If user chose "Enhanced - Full":

   sdd render {spec-id} --enhancement-level full
   # ~5-8 minutes
   # Note: --mode enhanced is implied when --enhancement-level is specified
   

   If user chose "Generate all versions for comparison":

   # Generate all three versions with different output names
   sdd render {spec-id} --mode basic -o specs/.human-readable/{spec-id}-basic.md
   sdd render {spec-id} --enhancement-level standard -o specs/.human-readable/{spec-id}-standard.md
   sdd render {spec-id} --enhancement-level full -o specs/.human-readable/{spec-id}-full.md
   

3. Report results to the user (output location and any relevant information)

Output Location: By default, rendered markdown is saved to specs/.human-readable/{spec-id}.md

Mode Options for AskUserQuestion:

Present these 5 options to the user:

Option Label	CLI Command	Use Case
"Basic (fast, no AI)"	--mode basic	Quick status checks (~2s)
"Enhanced - Summary"	--enhancement-level summary	Executive summaries (~1-2 min)
"Enhanced - Standard (recommended)"	(default, no flags needed)	Most use cases (~3-5 min) [DEFAULT]
"Enhanced - Full"	--enhancement-level full	Comprehensive analysis (~5-8 min)
"Generate all versions for comparison"	Multiple commands with different -o paths	Side-by-side comparison

See the AI Enhancement Modes section below for detailed feature comparison.

---

Current Rendering Features

Basic Markdown Generation

The renderer converts JSON specification files into clean, readable markdown with:

Header Section:

• Spec title and ID
• Overall status and progress (X/Y tasks, percentage)
• Estimated effort and complexity
• Description and objectives

Phase Sections:

• Phase titles with progress indicators
• Phase-level metadata (purpose, risk level, estimates)
• Phase dependencies (blocked by, depends on)
• Nested task groups

Task Details:

• Task title with status icon
• File path being modified
• Estimated hours
• Changes description and reasoning
• Dependencies and blockers
• Subtask hierarchy

Verification Steps:

• Verification type (manual, automated, integration)
• Commands to execute
• Expected outcomes

Status Icons

Visual indicators make progress instantly recognizable:

• ⏳ Pending - Task not yet started
• 🔄 In Progress - Currently being worked on
• ✅ Completed - Successfully finished
• 🚫 Blocked - Waiting on dependencies
• ❌ Failed - Encountered errors

Progress Tracking

Progress is calculated and displayed at multiple levels:

Spec Level:

User Authentication System
Status: in_progress (15/23 tasks, 65%)

Phase Level:

## Phase 2: Authentication Service (5/8 tasks, 62%)

Group Level:

### File Modifications (4/5 tasks)

Dependency Visualization

Dependencies are clearly shown to understand task relationships:

**Depends on:** task-1-2, task-1-3
**Blocked by:** task-2-1
**Blocks:** task-3-1, task-3-2, task-3-3

This makes it easy to:

• Identify what must be completed before starting a task
• See what's blocking progress
• Understand which tasks depend on the current task

Output Customization

Default Output:

sdd render my-spec-001
# Creates: specs/.human-readable/my-spec-001.md

Custom Output Path:

sdd render my-spec-001 --output docs/current-project.md
# Creates: docs/current-project.md

Specify Specs Directory:

sdd render my-spec-001 --path /path/to/specs
# Useful when working with multiple projects

---

AI Enhancement Modes

The sdd-render skill supports multiple rendering modes to balance speed and feature richness. Choose the mode based on your needs for performance versus detailed AI-generated insights.

Mode Overview

Default Rendering: When you run sdd render {spec-id} without any flags, it uses Enhanced Mode with Standard level for balanced performance and features (~3-5 minutes).

Two primary modes:

1. Basic Mode (--mode basic)

   • Fast, traditional markdown rendering
   • No AI features
   • Uses SpecRenderer for deterministic output
   • Typical rendering time: < 2 seconds
   • Use when speed is critical or AI features aren't needed
   • Must be explicitly specified to override the enhanced default

2. Enhanced Mode (default, --mode enhanced optional)

   • AI-powered analysis and insights
   • Uses external AI CLI tools (gemini, cursor-agent, codex)
   • Default enhancement level: standard
   • Typical rendering time: 1-8 minutes depending on level
   • Automatically falls back to basic mode if AI tools unavailable
   • The --mode enhanced flag is optional - specifying --enhancement-level automatically enables enhanced mode

Enhancement Levels

When using enhanced mode (the default), you can optionally specify one of three enhancement levels:

Level	Features	Performance	Best For
summary	Executive summary only	~1-2 minutes	Quick AI overview for stakeholders
standard	Base features + narrative enhancement	~3-5 minutes	Team reviews and status reports
full	All AI features (insights, visualizations, analysis)	~5-8 minutes	Comprehensive documentation and planning

Feature Comparison

Feature	Basic	Enhanced (summary)	Enhanced (standard)	Enhanced (full)
Markdown generation	✅	✅	✅	✅
Progress indicators	✅	✅	✅	✅
Dependency visualization	✅	✅	✅	✅
Task hierarchies	✅	✅	✅	✅
Executive summary	❌	✅	✅	✅
Narrative enhancement	❌	❌	✅	✅
Priority ranking	❌	❌	❌	✅
Complexity scoring	❌	❌	❌	✅
AI insights & recommendations	❌	❌	❌	✅
Dependency graphs (Mermaid)	❌	❌	❌	✅
Task grouping suggestions	❌	❌	❌	✅

Usage Examples

Default Rendering (Enhanced Standard):

# Uses enhanced mode with standard level by default
sdd render my-spec-001

# Equivalent explicit forms
sdd render my-spec-001 --enhancement-level standard
sdd render my-spec-001 --mode enhanced --enhancement-level standard

# With custom output
sdd render my-spec-001 --output docs/team-status.md

Basic Mode (fastest, no AI):

# Must explicitly specify --mode basic to override enhanced default
sdd render my-spec-001 --mode basic

# For quick status checks
sdd render my-spec-001 --mode basic --output /tmp/quick-status.md

# When AI features aren't needed
sdd render my-spec-001 --mode basic

Enhanced Mode with Summary:

# Specifying --enhancement-level automatically enables enhanced mode
sdd render my-spec-001 --enhancement-level summary

# For stakeholder updates (--mode enhanced is optional, implied by --enhancement-level)
sdd render my-spec-001 --enhancement-level summary --output reports/exec-summary.md

Enhanced Mode with Full Features:

# Specifying --enhancement-level automatically enables enhanced mode
sdd render my-spec-001 --enhancement-level full

# Maximum AI analysis with all features (--mode enhanced is implied)
sdd render my-spec-001 --enhancement-level full --output docs/comprehensive-plan.md

Generating Multiple Versions for Comparison

You can generate all three versions to compare outputs:

#!/bin/bash
SPEC_ID="my-spec-001"

# Generate basic version (fast reference)
sdd render $SPEC_ID --mode basic --output specs/.human-readable/${SPEC_ID}-basic.md

# Generate standard enhanced version (balanced)
sdd render $SPEC_ID --mode enhanced --enhancement-level standard --output specs/.human-readable/${SPEC_ID}-standard.md

# Generate full enhanced version (comprehensive)
sdd render $SPEC_ID --mode enhanced --enhancement-level full --output specs/.human-readable/${SPEC_ID}-full.md

echo "Generated three versions in specs/.human-readable/"
ls -lh specs/.human-readable/${SPEC_ID}-*.md

Choosing the Right Mode

Use Default (Enhanced Standard) when:

• ✅ Most common use case - balanced speed and features
• ✅ Team reviews and status reports
• ✅ Narrative flow improves comprehension
• ✅ Weekly/monthly updates
• ✅ Client-facing documentation
• ✅ No special requirements (this is the default!)

Override to Basic Mode when:

• You need quick status checks (< 2 seconds)
• Working iteratively with frequent renders (rapid feedback loop)
• AI insights are not needed
• Output will be consumed by automated tools
• CI/CD pipeline integration where speed matters
• Daily standup preparation with time constraints
• Offline environment or AI tools unavailable

Override to Enhanced Summary when:

• Stakeholders need high-level AI overview only
• Executive reporting required (lighter than standard)
• Want faster than standard (~1-2 minutes vs ~3-5 minutes)
• AI-generated executive summary is the primary value
• Quick decision-making with AI context

Override to Enhanced Full when:

• Comprehensive project planning with deep analysis
• Need AI insights, recommendations, and visualizations
• Visual dependency graphs are valuable
• Archiving/documentation purposes (one-time comprehensive render)
• New team member onboarding (detailed explanations helpful)
• Performance not critical (~5-8 minutes acceptable)
• Maximum information density desired

Interactive Mode Selection

When invoked via the sdd-render skill (not direct CLI):

The skill will proactively ask you which rendering mode you prefer using an interactive question:

Which rendering mode would you like to use?
○ Basic (fast, < 2 seconds, no AI)
○ Enhanced - Summary (executive summary, ~1-2 minutes)
○ Enhanced - Standard (recommended, balanced, ~3-5 minutes) ← default
○ Enhanced - Full (comprehensive analysis, ~5-8 minutes)

Benefits of interactive selection:

• No need to remember command-line flags
• Clear explanation of each option's tradeoffs
• Visual comparison of performance vs features
• Can choose "Other" to specify custom CLI parameters
• Default option clearly marked (Enhanced Standard)

When to skip the question: If you already know which mode you want, you can specify it in your initial request:

• "Render with basic mode"
• "Render with full AI enhancement"
• "Generate all three versions for comparison"

The skill will respect your explicit request and skip the interactive question.

AI Tooling

Enhanced mode uses external CLI tools for AI processing:

Tool Priority Order:

1. gemini (pro) - Primary for strategic analysis and summaries
2. cursor-agent (composer-1) - Secondary for repository-wide context
3. codex (gpt-5-codex) - Tertiary for code-level insights (disabled by default)

Automatic Fallback:

• System detects available tools automatically
• Tries tools in priority order
• Falls back to basic rendering if no AI tools available
• Configurable via .claude/ai_config.yaml (sdd-render.tools and sdd-render.models)

Performance Considerations

Rendering Times:

• Basic: < 2 seconds (deterministic, no network calls)
• Enhanced (summary): ~1-2 minutes (one AI call for executive summary)
• Enhanced (standard): ~3-5 minutes (summary + narrative enhancement)
• Enhanced (full): ~5-8 minutes (all AI features, multiple analysis passes)

Network Requirements:

• Basic mode: No network required
• Enhanced mode: Requires AI tool availability and API access
• Offline fallback: Enhanced mode falls back to basic if tools unavailable

Cost Considerations:

• Basic mode: No API costs
• Enhanced mode: AI tool usage may incur API costs depending on configured tools
• Full enhancement level uses the most AI tokens

---

Output Samples

Spec Header

# User Authentication System

**Spec ID:** user-auth-2025-10-24-001
**Status:** in_progress (15/23 tasks, 65%)
**Estimated Effort:** 45 hours
**Complexity:** High

## Description

Implement a secure user authentication system with JWT tokens, role-based access control, and session management.

## Objectives

- Secure password hashing with bcrypt
- JWT token generation and validation
- Role-based access control middleware
- Session management and refresh tokens
- Account lockout after failed attempts

Phase with Tasks

## Phase 2: Authentication Service (5/8 tasks, 62%)

**Purpose:** Implement core authentication logic
**Risk Level:** Medium
**Estimated Hours:** 18

### Tasks

#### ✅ task-2-1: Create AuthService class
**File:** src/services/authService.ts
**Estimated:** 3 hours
**Status:** completed
**Completed:** 2025-10-24 14:30:15

**Changes:**
Implement user registration with password hashing, add login method with JWT generation, include password validation logic

**Reasoning:** Centralizes authentication logic

**Blocks:** task-2-2, task-2-3

---

#### 🔄 task-2-2: Implement JWT middleware
**File:** src/middleware/auth.ts
**Estimated:** 2 hours
**Status:** in_progress

**Changes:**
Create Express middleware for JWT verification, add token expiration checking, handle invalid token responses

**Reasoning:** Protects API routes

**Depends on:** task-2-1 ✅
**Blocks:** task-2-3, task-2-4, task-2-5

---

#### ⏳ task-2-3: Add role-based authorization
**File:** src/middleware/rbac.ts
**Estimated:** 2.5 hours
**Status:** pending

**Changes:**
Create role checking middleware, define permission mappings, add route-level access control

**Reasoning:** Enables fine-grained access control

**Blocked by:** task-2-2 🔄

Verification Steps

#### verify-2-1: Verify authentication flow
**Type:** integration
**Estimated:** 1 hour

**Commands:**
```bash
npm test -- auth.integration.spec.ts

Expected Outcome: All authentication tests pass, JWT token format is valid, protected routes reject invalid tokens

### Before/After Comparison

**JSON Input:**
```json
{
  "id": "task-2-1",
  "type": "task",
  "title": "Create AuthService class",
  "status": "completed",
  "metadata": {
    "file_path": "src/services/authService.ts",
    "estimated_hours": 3,
    "changes": "Implement user registration with password hashing",
    "reasoning": "Centralizes authentication logic"
  },
  "dependencies": {
    "blocks": ["task-2-2", "task-2-3"]
  }
}

Rendered Output:

#### ✅ task-2-1: Create AuthService class
**File:** src/services/authService.ts
**Estimated:** 3 hours
**Status:** completed

**Changes:**
Implement user registration with password hashing

**Reasoning:** Centralizes authentication logic

**Blocks:** task-2-2, task-2-3

---

CLI Tools Reference

Core Commands

Default Rendering (Enhanced Standard):

sdd render {spec-id}

Renders a JSON spec with AI-enhanced narrative to markdown in the default location (specs/.human-readable/). Uses enhanced mode with standard level by default.

Basic Mode (Fast, No AI):

sdd render {spec-id} --mode basic

Quick rendering without AI features for speed-critical scenarios. Must explicitly specify --mode basic to override the enhanced default.

Full AI Enhancement:

sdd render {spec-id} --enhancement-level full

Maximum AI analysis with insights, visualizations, and recommendations. The --mode enhanced flag is optional - it's automatically enabled when you specify --enhancement-level.

Custom Output Path:

sdd render {spec-id} --output {path}
sdd render {spec-id} -o {path}

Specify where to save the rendered markdown file

Specify Specs Directory:

sdd render {spec-id} --path {specs-dir}

Use when specs are not in the default location

Render from File Path:

sdd render /path/to/spec-file.json

Directly render a JSON file by providing its full path

Command Options

Available Options:

Option	Short	Description	Default
--mode		Rendering mode: basic (fast, no AI) or enhanced (AI features). Optional - automatically set to enhanced when --enhancement-level is specified.	enhanced (with standard level)
--enhancement-level		AI enhancement level: summary, standard, or full. Automatically enables enhanced mode.	standard
--output	-o	Output file path	specs/.human-readable/{spec-id}.md
--path		Specs directory path	Auto-discovery
--verbose	-v	Show detailed output	Off
--debug		Show debug information	Off

Key Options Explained:

• --mode basic - Explicitly disables AI features for fast rendering (< 2 seconds). Must be specified to override enhanced default.
• --mode enhanced - Enables AI features (default, can be omitted). Automatically enabled when --enhancement-level is specified.
• --enhancement-level summary - Executive summary only (~1-2 minutes). Automatically enables enhanced mode.
• --enhancement-level standard - Balanced AI features (default, ~3-5 minutes). Automatically enables enhanced mode.
• --enhancement-level full - All AI features including visualizations (~5-8 minutes). Automatically enables enhanced mode.

Examples

Render with default settings (enhanced standard):

sdd render user-auth-2025-10-24-001
# Uses: mode=enhanced (default), level=standard (default) (~3-5 minutes)

Fast render without AI (basic mode):

sdd render user-auth-2025-10-24-001 --mode basic
# Must explicitly specify --mode basic to override enhanced default
# Quick status check (< 2 seconds)

Executive summary only:

sdd render user-auth-2025-10-24-001 --enhancement-level summary
# Automatically enables enhanced mode (~1-2 minutes)

Full AI analysis:

sdd render user-auth-2025-10-24-001 --enhancement-level full
# Automatically enables enhanced mode (~5-8 minutes)

Render to custom location:

sdd render user-auth-2025-10-24-001 --output docs/auth-plan.md
# Default enhanced standard mode with custom path

Basic mode to custom location (fast):

sdd render user-auth-2025-10-24-001 --mode basic --output /tmp/quick-status.md
# Speed-optimized with custom output

Render with verbose output:

sdd render user-auth-2025-10-24-001 --verbose
# Shows: Total tasks, output size, processing time, AI tool used

Render from specific specs directory:

sdd render my-spec-001 --path /projects/myapp/specifications

Render and view immediately:

sdd render my-spec-001 && less specs/.human-readable/my-spec-001.md

Generate multiple versions for comparison:

# Basic (fast reference)
sdd render my-spec-001 --mode basic -o specs/.human-readable/my-spec-001-basic.md

# Standard (default, balanced)
sdd render my-spec-001 -o specs/.human-readable/my-spec-001-standard.md

# Full (comprehensive)
sdd render my-spec-001 --enhancement-level full -o specs/.human-readable/my-spec-001-full.md

---

Workflow Examples

Example 1: Weekly Progress Report

Situation: Need to generate a progress report for the weekly team meeting

When to use this approach:

• ✓ Regular team meetings require status updates
• ✓ Spec has been updated recently (tasks completed, status changed)
• ✓ Need to track progress over time with dated reports
• ✓ Team members prefer markdown over JSON

Decision checklist:

• Spec updated? → Yes → Render will show current progress
• Need comparison? → Keep previous week's report for comparison
• Multiple projects? → Batch render all active specs (see Example 3)
• Presentation format? → Consider PDF conversion (see Example 2)

Steps:

1. Render current spec:

sdd render user-auth-2025-10-24-001 -o reports/week-$(date +%Y-%m-%d).md

2. Review the output:

less reports/week-2025-10-24.md

3. Share with team:

# Copy to shared docs folder
cp reports/week-2025-10-24.md /shared/team-docs/

# Or email directly
mail -s "Weekly Progress" [e-mail] < reports/week-2025-10-24.md

Output includes:

• Overall progress percentage
• Completed tasks this week
• Upcoming tasks
• Any blockers

Why this approach works:

• Timestamped filenames create historical record
• Custom output path keeps reports organized
• Markdown format is email-friendly and readable in any text editor

Example 2: Client Status Update

Situation: Client wants to see project progress in readable format

Steps:

1. Render spec to client docs:

sdd render mobile-app-2025-09-15-001 --output client/project-status-$(date +%B).md

2. Convert to PDF (optional, requires pandoc):

pandoc client/project-status-October.md -o client/project-status-October.pdf

3. Send to client:

• Markdown is readable in email or GitHub
• PDF is professional and printable

Example 3: Onboarding New Developer

Situation: New developer joins and needs to understand project scope

Steps:

1. Render all active specs:

for spec in specs/active/*.json; do
  spec_id=$(basename $spec .json)
  sdd render $spec_id
done

2. Create index document:

ls specs/.human-readable/ > docs/project-index.txt

3. Point developer to documentation:

• All specs are now in readable format
• Developer can browse and understand scope
• No need to parse JSON manually

Example 4: Pre-Planning Review

Situation: Before starting implementation, review the spec structure

When to use this approach:

• ✓ New spec just created with Skill(sdd-toolkit:sdd-plan)
• ✓ Want to verify structure before beginning work
• ✓ Looking for dependency issues or circular references
• ✓ Assessing scope and task breakdown quality

Decision checklist:

• New spec? → Always review before implementation starts
• Complex dependencies? → Look for dependency visualization in output
• Team review? → Share rendered version for feedback
• Issues found? → Hand off to Skill(sdd-toolkit:sdd-plan) to modify

Steps:

1. Render the spec:

sdd render api-redesign-2025-10-01-001 --verbose

2. Review for issues:

• Check dependency chains (look for circular dependencies)
• Verify phase organization (logical progression?)
• Look for missing tasks (gaps in implementation?)
• Identify potential blockers (tasks with no dependencies marked?)

3. Make adjustments (if needed):

• Use Skill(sdd-toolkit:sdd-plan) to update spec
• Re-render to verify changes

sdd render api-redesign-2025-10-01-001

Why this approach works:

• Human-readable format makes structural issues obvious
• Verbose mode shows additional diagnostics
• Iterative review-modify-verify cycle ensures quality
• Catches planning issues before implementation begins

Example 5: Archiving Completed Project

Situation: Project is complete, need permanent documentation

Steps:

1. Render final version:

sdd render user-dashboard-2025-08-01-001 --output archive/user-dashboard-final-$(date +%Y-%m-%d).md

2. Create summary document:

echo "# User Dashboard Project - Completed $(date +%Y-%m-%d)" > archive/README.md
echo "" >> archive/README.md
echo "See user-dashboard-final-*.md for complete specification" >> archive/README.md

3. Archive the spec:

• Move JSON to specs/completed/
• Keep markdown in permanent docs
• Commit to git for history

Example 6: Comparing Enhancement Levels

Situation: Evaluating AI enhancement value or choosing the right level for your workflow

When to use this approach:

• ✓ First time using AI enhancements (want to see differences)
• ✓ Deciding which level to use for regular workflows
• ✓ Demonstrating AI capabilities to stakeholders
• ✓ Benchmarking rendering performance
• ✓ Creating documentation at multiple detail levels

Decision checklist:

• Evaluating features? → Generate all three to compare side-by-side
• Performance testing? → Time each mode with time command
• Choosing default? → Try all levels once, then stick with preferred
• Multiple audiences? → Keep multiple versions (basic for developers, full for stakeholders)

Steps:

1. Generate all three versions:

#!/bin/bash
SPEC_ID="user-auth-2025-10-24-001"

echo "Generating basic version (no AI)..."
time sdd render $SPEC_ID --mode basic \
  --output specs/.human-readable/${SPEC_ID}-basic.md

echo "Generating standard version (default AI)..."
time sdd render $SPEC_ID --enhancement-level standard \
  --output specs/.human-readable/${SPEC_ID}-standard.md

echo "Generating full version (maximum AI)..."
time sdd render $SPEC_ID --enhancement-level full \
  --output specs/.human-readable/${SPEC_ID}-full.md

echo "All versions generated!"

2. Compare file sizes and render times:

ls -lh specs/.human-readable/${SPEC_ID}-*.md

# Example output:
# -rw-r--r-- 1 user user  45K Oct 24 10:15 user-auth-2025-10-24-001-basic.md     (1.2s)
# -rw-r--r-- 1 user user  78K Oct 24 10:16 user-auth-2025-10-24-001-standard.md (58s)
# -rw-r--r-- 1 user user 120K Oct 24 10:17 user-auth-2025-10-24-001-full.md     (92s)

3. Review each version:

# Quick scan of basic version
less specs/.human-readable/${SPEC_ID}-basic.md

# Review standard enhancements
less specs/.human-readable/${SPEC_ID}-standard.md

# Examine full AI features
less specs/.human-readable/${SPEC_ID}-full.md

4. Compare specific sections using diff:

# Compare basic vs standard
diff specs/.human-readable/${SPEC_ID}-basic.md \
     specs/.human-readable/${SPEC_ID}-standard.md | head -50

# Compare standard vs full
diff specs/.human-readable/${SPEC_ID}-standard.md \
     specs/.human-readable/${SPEC_ID}-full.md | head -50

What to look for in each version:

Basic Mode:

• Clean, fast markdown rendering
• Standard progress indicators and task lists
• No AI-generated content
• Smallest file size

Enhanced Standard:

• Includes basic features plus:
• Executive summary section
• Narrative transitions between phases
• Contextual explanations
• Moderately larger file size

Enhanced Full:

• Includes standard features plus:
• AI-generated insights and recommendations
• Priority ranking analysis
• Complexity scoring
• Dependency graphs (Mermaid diagrams)
• Task grouping suggestions
• Largest file size with most detail

Why this approach works:

• Side-by-side comparison shows clear value of each level
• Timing data helps make performance tradeoff decisions
• Can choose different levels for different use cases
• One-time evaluation informs long-term workflow choices
• Demonstrates ROI of AI features to team/management

Making your choice:

• Choose Basic if speed > features and you don't need AI insights
• Choose Standard if you want AI narrative without full analysis (balanced default)
• Choose Full if you need comprehensive AI features and time isn't critical

---

Integration Points

With Skill(sdd-toolkit:sdd-plan)

Creating Specs → Rendering Specs:

1. Create spec with sdd-plan
   ↓
2. Spec saved as JSON in specs/active/
   ↓
3. Render with sdd-render for human review
   ↓
4. Share rendered markdown with team

Use case: After creating a new specification, immediately render it to markdown for team review before beginning implementation.

With Skill(sdd-toolkit:sdd-next)

Understanding Context → Finding Tasks:

1. Render spec to understand overall structure
   ↓
2. Use sdd-next to identify next actionable task
   ↓
3. Render again after completing tasks to see progress

Use case: Before starting work, render the spec to understand the big picture, then use sdd-next for focused task execution.

With sdd-update-subagent

Tracking Progress → Visualizing Progress:

1. Complete a task
   ↓
2. Update status with sdd-update
   ↓
3. Render spec to see updated progress
   ↓
4. Share progress report with stakeholders

Use case: After completing milestones, render the spec to generate a progress report showing what's been accomplished.

With Skill(sdd-toolkit:run-tests)

Verification → Documentation:

1. Run tests with run-tests skill
   ↓
2. Update verification steps with results
   ↓
3. Render spec to document test outcomes

Use case: After running verification steps, the rendered spec shows which verifications passed and which are pending.

With External Tools

Generated markdown can be:

• Committed to git for version control of project plans
• Converted to PDF using pandoc or similar tools
• Embedded in wikis (GitHub, Confluence, Notion)
• Included in reports using standard markdown processors
• Shared via email (readable in plain text)
• Published to static sites using Jekyll, Hugo, etc.

---

Common Workflows

Daily: Quick Status Check

# Render and view current status
sdd render current-project-001 && less specs/.human-readable/current-project-001.md

# Look for:
# - Progress percentage
# - Tasks completed today
# - Upcoming blockers

Weekly: Team Sync

# Generate weekly report
sdd render current-project-001 -o team-sync/week-$(date +%U).md

# Review in meeting:
# - Progress since last week
# - Upcoming milestones
# - Team allocation

Monthly: Stakeholder Update

# Render all active projects
for spec in specs/active/*.json; do
  spec_id=$(basename $spec .json)
  sdd render $spec_id -o stakeholder-updates/$(date +%Y-%m)/$spec_id.md
done

# Create summary:
# - Cross-project status
# - Key achievements
# - Upcoming priorities

As-Needed: Debugging Spec Structure

# Render with verbose output
sdd render problem-spec-001 --verbose --debug

# Check for:
# - Malformed JSON
# - Circular dependencies
# - Missing metadata
# - Progress calculation issues

---

Troubleshooting

Issue: Spec Not Found

Symptoms:

Error: Spec not found: my-spec-001

Solutions:

1. Check spec ID is correct:

# List available specs
sdd find-specs --verbose

2. Specify specs directory explicitly:

sdd render my-spec-001 --path /path/to/specs

3. Use full path to JSON file:

sdd render /path/to/specs/active/my-spec-001.json

Issue: Output File Permission Denied

Symptoms:

Error: Permission denied: /output/path/file.md

Solutions:

1. Check directory permissions:

ls -la /output/path/

2. Create output directory:

mkdir -p /output/path

3. Use default output location:

# Omit --output flag to use default
sdd render my-spec-001

Issue: Malformed JSON

Symptoms:

Error: Failed to load spec file: Invalid JSON

Solutions:

1. Validate JSON:

python3 -m json.tool specs/active/my-spec-001.json

2. Check for common issues:

• Trailing commas
• Missing quotes
• Unclosed brackets

3. Regenerate spec:

# Use sdd-plan to recreate the spec
# This ensures valid JSON structure

Issue: Missing Metadata

Symptoms: Rendered markdown shows "Untitled" or missing information

Solutions:

1. Update spec with missing information:

• Use Skill(sdd-toolkit:sdd-plan) to add metadata
• Ensure title, description, objectives are populated

2. Re-render:

sdd render my-spec-001

---

Advanced Usage

Batch Rendering

Render all active specs:

#!/bin/bash
for spec in specs/active/*.json; do
  spec_id=$(basename "$spec" .json)
  echo "Rendering $spec_id..."
  sdd render "$spec_id"
done

Render all specs in a status folder:

# Render all completed specs
for spec in specs/completed/*.json; do
  spec_id=$(basename "$spec" .json)
  sdd render "$spec_id" -o docs/completed/$spec_id.md
done

Integration with Git Hooks

Pre-commit hook to render specs:

#!/bin/bash
# .git/hooks/pre-commit

# Render all active specs before committing
for spec in specs/active/*.json; do
  if [ -f "$spec" ]; then
    spec_id=$(basename "$spec" .json)
    sdd render "$spec_id"
    git add "specs/.human-readable/$spec_id.md"
  fi
done

Benefits:

• Always have up-to-date rendered versions
• Track changes in readable markdown
• Easy to review spec changes in PRs

Custom Output Processing

Extract progress percentage:

sdd render my-spec-001 -o /tmp/spec.md
grep "Status:" /tmp/spec.md | grep -oP '\d+%'

Generate progress badge:

progress=$(sdd render my-spec-001 -o - | grep -oP '\d+%' | head -1)
echo "![Progress](https://img.shields.io/badge/progress-$progress-blue)"

Create searchable index:

# Render all specs and create full-text search index
for spec in specs/active/*.json; do
  spec_id=$(basename "$spec" .json)
  sdd render "$spec_id" >> docs/searchable-index.md
done

---

Performance Considerations

Rendering Speed by Mode

Basic Mode Performance:

• Small spec (10-20 tasks): < 100ms
• Medium spec (50-100 tasks): < 500ms
• Large spec (200+ tasks): < 2 seconds
• Very large spec (500+ tasks): < 5 seconds

Enhanced Mode Performance: Performance depends on the enhancement level chosen:

Mode	Small Spec	Medium Spec	Large Spec	Very Large Spec
Basic (no AI)	< 100ms	< 500ms	< 2s	< 5s
Enhanced (summary)	~1 min	~1.5 min	~2 min	~2.5 min
Enhanced (standard)	~3 min	~4 min	~5 min	~6 min
Enhanced (full)	~5 min	~6 min	~7 min	~8 min

Note: Enhanced mode times are dominated by AI processing rather than spec size, so scaling is relatively flat.

Factors affecting basic mode performance:

• Number of tasks and subtasks
• Depth of task hierarchy
• Size of metadata fields
• Output file I/O

Factors affecting enhanced mode performance:

• AI tool response time (network latency)
• Enhancement level (summary < standard < full)
• AI model availability (gemini is fastest)
• Spec complexity affects AI analysis quality, not time

Optimization Tips

For speed-critical workflows:

# Use basic mode when speed matters
sdd render my-spec-001 --mode basic

# Output to stdout (skips file I/O)
sdd render my-spec-001 --mode basic --output -

# Batch render with basic mode
for spec in specs/active/*.json; do
  sdd render $(basename $spec .json) --mode basic
done

For balanced workflows (default):

# Default enhanced standard provides good balance
sdd render my-spec-001

# Cache results for repeated access
sdd render my-spec-001 --output /tmp/cached-spec.md

For comprehensive analysis (one-time renders):

# Full enhancement for documentation
sdd render my-spec-001 --enhancement-level full --output docs/comprehensive.md

AI Enhancement Performance

Default Behavior:

• Mode: Enhanced (can be changed with --mode basic)
• Level: Standard (can be changed with --enhancement-level)
• Estimated time: ~3-5 minutes for most specs

AI Tooling: AI enhancements use external CLI tools via subprocess. The default priority order is:

1. gemini (pro model) - Primary for strategic analysis and summaries
2. cursor-agent (composer-1 model) - Secondary for repository-wide context
3. codex (gpt-5-codex model) - Tertiary for code-level insights (disabled by default)

Automatic Fallback:

• System detects available tools automatically
• Tries tools in priority order
• Falls back to basic rendering if no AI tools available
• No user intervention required

Configuration: AI tool settings can be customized in .claude/ai_config.yaml (sdd-render section)

Performance characteristics:

• AI processing is one-time per render (results embedded in markdown)
• Output file is static (no runtime overhead when viewing)
• Can switch between modes based on needs
• Enhanced mode results are cacheable for repeated access

---

File Locations

Default Paths

Input:

• Auto-discovered from: specs/active/, specs/completed/, specs/archived/
• Can be overridden with --path option

Output:

• Default: specs/.human-readable/{spec-id}.md
• Can be overridden with --output option

Directory Structure

project/
├── specs/
│   ├── active/               # Active specifications (JSON)
│   │   └── my-spec-001.json
│   ├── completed/            # Completed specifications
│   ├── archived/             # Archived specifications
│   └── .human-readable/      # Rendered markdown (generated)
│       └── my-spec-001.md    # Human-readable version
└── docs/
    └── planning/             # Optional: copy rendered docs here

Note: The .human-readable/ directory is automatically created if it doesn't exist.

---

Success Criteria

A rendering operation is successful when:

File Creation:

• ✓ Markdown file created at expected location
• ✓ File size > 0 bytes (not empty)
• ✓ File is valid markdown format

Content Completeness:

• ✓ Contains expected sections (metadata, phases, tasks)
• ✓ Progress percentages calculated correctly
• ✓ Dependencies displayed accurately
• ✓ All task metadata present (file paths, estimates, status)
• ✓ Verification steps included (if present in spec)

No Errors:

• ✓ No error messages during rendering
• ✓ No warnings about missing data
• ✓ Spec JSON file unchanged (read-only verified)

Validation Checklist

Run these commands to verify successful rendering:

# 1. Check file exists
test -f specs/.human-readable/{spec-id}.md && echo "✓ File created"

# 2. Check file size (should be > 0)
test -s specs/.human-readable/{spec-id}.md && echo "✓ File not empty"

# 3. Check key sections present
grep -q "^## Phase" specs/.human-readable/{spec-id}.md && echo "✓ Phases found"

# 4. Check progress indicators
grep -q "tasks, [0-9]*%)" specs/.human-readable/{spec-id}.md && echo "✓ Progress calculated"

# 5. Check status icons present
grep -E "^#### (✅|⏳|🔄|🚫|❌)" specs/.human-readable/{spec-id}.md && echo "✓ Status icons present"

# 6. Verify source JSON unchanged
git diff specs/active/{spec-id}.json && echo "✓ Source spec unchanged"

When Rendering is NOT Successful

Symptoms and solutions:

Symptom	Likely Cause	Solution
File created but empty	Invalid JSON spec	Validate with python3 -m json.tool
Missing sections	Incomplete spec structure	Check spec has phases and tasks
Progress shows 0% with completed tasks	Task status fields incorrect	Verify task.status values
No dependency info	Dependencies not in spec	Check spec.dependencies structure
Permission denied	Output directory not writable	Use default location or create directory
"Spec not found" error	Wrong spec-id or path	Use sdd find-specs --verbose

When to troubleshoot vs escalate:

• Minor issues (formatting, missing optional fields) → Check Troubleshooting section
• Cannot render at all → Verify installation: sdd render --help
• Spec structure problems → Use Skill(sdd-toolkit:sdd-plan) to fix spec
• Persistent errors → Check spec JSON validity with validation tools

---

Summary

Core Responsibility: Transform JSON specification files into human-readable, well-formatted markdown documentation for easy review, sharing, and understanding.

Current Capabilities:

• ✅ Convert JSON specs to formatted markdown
• ✅ Display progress with visual indicators
• ✅ Show task hierarchies and dependencies
• ✅ Include metadata (estimates, complexity, reasoning)
• ✅ Support custom output paths
• ✅ Handle specs from multiple status folders

Integration Points:

• Reads specs created by Skill(sdd-toolkit:sdd-plan)
• Visualizes progress updated by sdd-update-subagent
• Complements Skill(sdd-toolkit:sdd-next) for context understanding
• Works alongside Skill(sdd-toolkit:run-tests) for verification documentation

Key Benefits:

• Make specs accessible to non-technical stakeholders
• Enable quick progress reviews without parsing JSON
• Facilitate team communication and reporting
• Create permanent records of project plans
• Support multiple use cases (reports, onboarding, planning)

When to Use: Use this skill whenever you need to convert a machine-readable spec into a human-friendly format for review, sharing, or documentation purposes.