Claude-Code-Workflow/.claude/skills/prompt-generator/specs/conversion-spec.md

Conversion Specification

Rules for restyling existing command/agent files to GSD conventions. Zero content loss is mandatory.

Core Principle

Conversion = structural transformation, NOT content rewriting. Every line of source content must appear in the output. Only the container (XML tags, section ordering, frontmatter format) changes.

Content Loss Prevention Protocol

Pre-conversion Inventory

Before converting, count:

• $SRC_LINES — total non-empty lines
• $SRC_BLOCKS — code block count (``` pairs)
• $SRC_TABLES — table count (lines starting with |)
• $SRC_SECTIONS — section count (## headers)

Post-conversion Verification

Metric	Rule	Action on Fail
Lines	output >= source × 0.95	STOP — find missing content
Code blocks	output >= source	STOP — find missing blocks
Tables	output >= source	STOP — find missing tables
Sections	output >= source	WARN — sections may have merged

Diff Display

After conversion, show summary:

Conversion Summary:
  Source: {path} ({src_lines} lines, {src_blocks} code blocks)
  Output: {path} ({out_lines} lines, {out_blocks} code blocks)
  Delta:  {+/-} lines, {+/-} code blocks
  New sections added: {list of TODO sections}

Artifact Type Detection

Before applying conversion rules, determine the source type:

Source Location	Type
.claude/commands/**/*.md	command
.claude/skills/*/SKILL.md	skill
.claude/agents/*.md	agent

Skill detection signals: allowed-tools: in frontmatter, located in .claude/skills/ directory, progressive phase loading pattern (Read("phases/..."))

Skill Conversion Rules

Critical: No @ References

Skills are loaded progressively inline into the conversation context. They CANNOT use @ file references — these only work in commands.

Source Pattern → Target Pattern (Skill)

Source Style	Target Style
# Title + flat markdown overview	<purpose> (2-3 sentences)
## Implementation / ## Execution Flow / ## Phase Summary	<process> with numbered ## N. steps
Phase file references as prose	Read("phases/...") calls within process steps
## Success Criteria / ## Coordinator Checklist	<success_criteria> with checkbox list
## Auto Mode / ## Auto Mode Defaults	<auto_mode> section
## Error Handling	Preserve as-is within <process> or as standalone section
Code blocks, tables, ASCII diagrams	Preserve exactly

What NOT to Add (Skill-Specific)

Element	Why NOT
<required_reading>	Skills cannot use @ refs — progressive loading
@specs/... or @phases/...	@ syntax not supported in skills
<offer_next>	Skills chain via Skill() calls, not offer menus

What to ADD (Skill-Specific)

Missing Element	Add
<purpose>	Extract from overview/description
<process> wrapper	Wrap implementation steps
<success_criteria>	Generate from coordinator checklist or existing content
<auto_mode>	If auto mode behavior exists, wrap in tag

Frontmatter Conversion (Skill)

Source Field	Target Field	Transformation
name	name	Keep as-is
description	description	Keep as-is
allowed-tools	allowed-tools	Keep as-is
Missing allowed-tools	allowed-tools	Infer from content

Command Conversion Rules

Source Pattern → Target Pattern

Source Style	Target Style
# Title + ## Phase N: flat markdown	<purpose> + <process> with numbered ## N. steps
## Implementation + ### Phase N	<process> with numbered steps, content preserved
## Overview / ## Core Principle	<purpose> (merge into 2-3 sentences) + keep details in steps
## Usage with examples	Keep as-is inside <process> step 1 or before <process>
## Auto Mode / ## Auto Mode Defaults	<auto_mode> section
## Quick Reference	Preserve as-is within appropriate section
Inline AskUserQuestion calls	Preserve verbatim — these belong in commands
Agent() / agent spawning calls	Preserve verbatim within process steps
Banner displays (━━━)	Preserve verbatim
Code blocks (bash, javascript, etc.)	Preserve exactly — never modify code content
Tables	Preserve exactly — never reformat table content

Frontmatter Conversion

Source Field	Target Field	Transformation
name	name	Keep as-is
description	description	Keep as-is
argument-hint	argument-hint	Keep as-is
allowed-tools	allowed-tools	Keep as-is
Missing allowed-tools	allowed-tools	Infer from content (Read, Write, etc.)

Section Wrapping

Content that was under plain ## headers gets wrapped in XML tags:

## Overview / ## Core Principle  → content moves to <purpose>
## Process / ## Implementation  → content moves to <process>
## Success Criteria             → content moves to <success_criteria>
## Error Codes                  → preserve as-is (optional section)

Everything else: Wrap in appropriate GSD tag or keep as custom section inside <process>.

What to ADD (with TODO markers)

Missing Element	Add
<purpose>	Extract from overview/description, mark <!-- TODO: refine --> if uncertain
<success_criteria>	Generate from existing content, mark <!-- TODO: verify -->
<offer_next>	Add skeleton with <!-- TODO: fill next commands -->
Banners	Add before major transitions if missing

Agent Conversion Rules

Source Pattern → Target Pattern

Source Style	Target Style
Plain prose role description	<role> with structured format
## Core Philosophy / ## Principles	<philosophy>
## Execution Process / ## How to	Domain section with descriptive name
## Quality Gates / ## Standards	<quality_gate> with checkbox format
Flat numbered list of responsibilities	<role> core responsibilities bullet list
## Examples section	Move examples INTO relevant domain sections

Frontmatter Conversion

Source Field	Target Field	Transformation
name	name	Keep as-is
description	description	Append "Spawned by /command orchestrator." if missing
color	color	Keep as-is
Missing tools	tools	Infer from content (Read, Write, Bash, etc.)

Section Restructuring

1. <role> MUST be first — gather identity content from wherever it appears
2. Add "Spawned by:" if missing — infer from description or mark <!-- TODO: specify spawner -->
3. Add "Mandatory Initial Read" block if missing
4. Rename generic sections: <rules> → descriptive name based on content
5. Add <output_contract> if missing — with TODO marker
6. Add <quality_gate> if missing — with TODO marker

What NOT to Change

• Code blocks inside sections — preserve exactly
• Tables — preserve exactly
• Concrete examples (good/bad comparisons) — preserve exactly
• Shell commands — preserve exactly
• Agent prompts — preserve exactly
• Domain-specific terminology — preserve exactly

Batch Conversion

For converting multiple files:

# List candidates
ls .claude/commands/**/*.md .claude/agents/*.md

# Convert one at a time, verify each
/prompt-generator convert .claude/commands/issue/new.md
/prompt-generator convert .claude/agents/universal-executor.md

Anti-Patterns

Anti-Pattern	Why It's Wrong
Rewriting code blocks	Content loss — code is sacred
Summarizing verbose sections	Content loss — preserve verbatim
Removing "redundant" content	User may depend on it
Merging sections without inventory	May lose content silently
Adding content beyond structural tags	Conversion adds structure, not content
Skipping post-conversion line count	Cannot verify zero content loss