mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-03-18 18:48:48 +08:00
Add agent, command, and conversion specifications; introduce templates for agent and command structures
- Created `agent-design-spec.md` detailing agent identity, knowledge, and structure. - Established `command-design-spec.md` outlining command orchestration, user interaction, and agent coordination. - Introduced `conversion-spec.md` for guidelines on converting existing files to GSD conventions without content loss. - Added `agent-md.md` and `command-md.md` templates to standardize the creation of agent and command files.
This commit is contained in:
catlog22
299
.claude/skills/prompt-generator/specs/agent-design-spec.md
Normal file
299
.claude/skills/prompt-generator/specs/agent-design-spec.md
Normal file
@@ -0,0 +1,299 @@
|
||||
# Agent Design Specification
|
||||
|
||||
Guidelines for Claude Code **agent definition files** (role + domain expertise). Agents own identity, knowledge, and quality standards — NOT orchestration flow.
|
||||
|
||||
## Content Separation Principle
|
||||
|
||||
Agents are spawned by commands via `Task()`. The agent file defines WHO the agent is and WHAT it knows. It does NOT define WHEN or HOW it gets invoked.
|
||||
|
||||
| Concern | Belongs in Agent | Belongs in Command |
|
||||
|---------|-----------------|-------------------|
|
||||
| Role identity (`<role>`) | Yes | No |
|
||||
| Domain expertise | Yes | No |
|
||||
| Output format/structure | Yes | No |
|
||||
| Quality heuristics | Yes | No |
|
||||
| Self-check criteria | Yes | No |
|
||||
| Philosophy/principles | Yes | No |
|
||||
| Discovery protocol | Yes | No |
|
||||
| Specificity examples | Yes | No |
|
||||
| Argument parsing | No | Yes |
|
||||
| User interaction | No | Yes |
|
||||
| Flow control | No | Yes |
|
||||
| Agent spawning | No | Yes |
|
||||
| Status banners | No | Yes |
|
||||
| Revision loop logic | No | Yes |
|
||||
|
||||
## YAML Frontmatter
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: agent-name
|
||||
description: One-line purpose. Spawned by /command-name orchestrator.
|
||||
tools: Read, Write, Bash, Glob, Grep # Tools this agent needs
|
||||
color: green # Optional: terminal color
|
||||
---
|
||||
```
|
||||
|
||||
**Naming convention:** `{domain}-{role}` or `{project}-{role}` — e.g., `gsd-planner`, `gsd-plan-checker`, `code-reviewer`.
|
||||
|
||||
## Content Structure
|
||||
|
||||
Agent files use XML semantic tags. `<role>` is ALWAYS first after frontmatter.
|
||||
|
||||
### Section Catalog
|
||||
|
||||
Derived from GSD agent patterns (`gsd-planner`, `gsd-plan-checker`, `gsd-phase-researcher`):
|
||||
|
||||
| Section | Purpose | When to Include |
|
||||
|---------|---------|-----------------|
|
||||
| `<role>` | Identity, spawner, responsibilities | **Always** |
|
||||
| `<project_context>` | How to discover project conventions | Agent reads project files |
|
||||
| `<philosophy>` | Guiding principles, anti-patterns | Agent has opinionated approach |
|
||||
| `<context_fidelity>` | Honor upstream decisions (locked/deferred/discretion) | Agent receives user decisions |
|
||||
| `<upstream_input>` | What the agent receives and how to use it | Agent has structured input |
|
||||
| `<discovery_levels>` | Research depth protocol (L0-L3) | Agent does research |
|
||||
| `<task_breakdown>` | Task anatomy, sizing, ordering | Agent produces tasks |
|
||||
| `<dependency_graph>` | How to build dependency graphs | Agent manages dependencies |
|
||||
| `<output_format>` | Exact output structure with templates | Agent produces structured output |
|
||||
| `<core_principle>` | Central verification or design principle | Agent has one key insight |
|
||||
| `<output_contract>` | Return markers to orchestrator | **Always** |
|
||||
| `<quality_gate>` | Self-check before returning | **Always** |
|
||||
|
||||
### Section Ordering Convention
|
||||
|
||||
```
|
||||
<role> ← Identity (always first)
|
||||
<project_context> ← How to orient in the project
|
||||
<philosophy> ← Guiding beliefs
|
||||
<upstream_input> ← What agent receives
|
||||
<context_fidelity> ← How to honor decisions
|
||||
<core_principle> ← Key insight
|
||||
... domain sections ← Expertise (2-6 sections)
|
||||
<output_contract> ← Return protocol
|
||||
<quality_gate> ← Self-check (always last content section)
|
||||
```
|
||||
|
||||
## Section Writing Rules
|
||||
|
||||
### `<role>` — Identity (ALWAYS FIRST)
|
||||
|
||||
Pattern from `gsd-planner.md` and `gsd-plan-checker.md`:
|
||||
|
||||
```markdown
|
||||
<role>
|
||||
You are a {role name}. You {primary action verb} {what you produce}.
|
||||
|
||||
Spawned by:
|
||||
- `/{command}` orchestrator (standard mode)
|
||||
- `/{command} --flag` orchestrator (variant mode)
|
||||
- `/{command}` in revision mode (updating based on checker feedback)
|
||||
|
||||
Your job: {One sentence — what downstream consumers get from you.}
|
||||
|
||||
**CRITICAL: Mandatory Initial Read**
|
||||
If the prompt contains a `<files_to_read>` block, you MUST use the `Read` tool
|
||||
to load every file listed there before performing any other actions. This is your
|
||||
primary context.
|
||||
|
||||
**Core responsibilities:**
|
||||
- **FIRST: {Most important action}** ({why it's first})
|
||||
- {Responsibility 2 — verb phrase}
|
||||
- {Responsibility 3 — verb phrase}
|
||||
- {Responsibility 4 — verb phrase}
|
||||
- Return structured results to orchestrator
|
||||
</role>
|
||||
```
|
||||
|
||||
### `<project_context>` — Project Discovery
|
||||
|
||||
Pattern from `gsd-planner.md`:
|
||||
|
||||
```markdown
|
||||
<project_context>
|
||||
Before {acting}, discover project context:
|
||||
|
||||
**Project instructions:** Read `./CLAUDE.md` if it exists. Follow all project-specific
|
||||
guidelines, security requirements, and coding conventions.
|
||||
|
||||
**Project skills:** Check `.claude/skills/` directory if exists:
|
||||
1. List available skills (subdirectories)
|
||||
2. Read `SKILL.md` for each skill
|
||||
3. Load specific files as needed during {action}
|
||||
4. Ensure {output} accounts for project patterns
|
||||
</project_context>
|
||||
```
|
||||
|
||||
### `<philosophy>` — Guiding Principles
|
||||
|
||||
Pattern from `gsd-planner.md`:
|
||||
|
||||
```markdown
|
||||
<philosophy>
|
||||
## {Principle Name}
|
||||
|
||||
{Core belief about how this agent approaches work.}
|
||||
|
||||
| Context Usage | Quality | Agent's State |
|
||||
|---------------|---------|---------------|
|
||||
| 0-30% | PEAK | Thorough |
|
||||
| 50-70% | DEGRADING | Efficiency mode |
|
||||
| 70%+ | POOR | Rushed |
|
||||
|
||||
**Anti-patterns (delete if seen):**
|
||||
- {Anti-pattern 1 with specific indicator}
|
||||
- {Anti-pattern 2 with specific indicator}
|
||||
</philosophy>
|
||||
```
|
||||
|
||||
### `<upstream_input>` — Structured Input Handling
|
||||
|
||||
Pattern from `gsd-plan-checker.md`:
|
||||
|
||||
```markdown
|
||||
<upstream_input>
|
||||
**{Input name}** (if exists) — {Source description}
|
||||
|
||||
| Section | How You Use It |
|
||||
|---------|----------------|
|
||||
| `## Section A` | LOCKED — {must implement exactly}. Flag if contradicted. |
|
||||
| `## Section B` | Freedom areas — {can choose approach}, don't flag. |
|
||||
| `## Section C` | Out of scope — {must NOT include}. Flag if present. |
|
||||
</upstream_input>
|
||||
```
|
||||
|
||||
### `<context_fidelity>` — Decision Honoring
|
||||
|
||||
Pattern from `gsd-planner.md`:
|
||||
|
||||
```markdown
|
||||
<context_fidelity>
|
||||
## CRITICAL: User Decision Fidelity
|
||||
|
||||
**Before creating ANY {output}, verify:**
|
||||
|
||||
1. **Locked Decisions** — MUST be implemented exactly as specified
|
||||
- If user said "use library X" → {output} MUST use X, not alternative
|
||||
- If user said "card layout" → {output} MUST implement cards
|
||||
|
||||
2. **Deferred Ideas** — MUST NOT appear in {output}
|
||||
- If user deferred "search" → NO search tasks allowed
|
||||
|
||||
3. **Discretion Areas** — Use your judgment
|
||||
- Make reasonable choices and document in {output}
|
||||
|
||||
**Self-check before returning:**
|
||||
- [ ] Every locked decision has coverage
|
||||
- [ ] No deferred idea appears
|
||||
- [ ] Discretion areas handled reasonably
|
||||
|
||||
**If conflict exists** (research vs user decision):
|
||||
- Honor the user's locked decision
|
||||
- Note: "Using X per user decision (research suggested Y)"
|
||||
</context_fidelity>
|
||||
```
|
||||
|
||||
### Domain Sections — One Concern Each
|
||||
|
||||
Name sections after the domain concept. Include concrete examples in EVERY section.
|
||||
|
||||
**Required elements per domain section:**
|
||||
|
||||
| Element | Minimum |
|
||||
|---------|---------|
|
||||
| Good vs bad comparison table | 1 per section |
|
||||
| Decision/routing table | 1 per section (if conditional logic exists) |
|
||||
| Format template | 1 per section (if structured output) |
|
||||
| Concrete example | 2+ per section |
|
||||
|
||||
**Example from gsd-planner.md `<task_breakdown>`:**
|
||||
|
||||
```markdown
|
||||
<task_breakdown>
|
||||
## Task Anatomy
|
||||
|
||||
Every task has four required fields:
|
||||
|
||||
**<files>:** Exact paths.
|
||||
- Good: `src/app/api/auth/login/route.ts`
|
||||
- Bad: "the auth files"
|
||||
|
||||
**<action>:** Specific instructions.
|
||||
- Good: "Create POST endpoint accepting {email, password}, validates using bcrypt,
|
||||
returns JWT in httpOnly cookie with 15-min expiry. Use jose library."
|
||||
- Bad: "Add authentication"
|
||||
|
||||
## Specificity Examples
|
||||
|
||||
| TOO VAGUE | JUST RIGHT |
|
||||
|-----------|------------|
|
||||
| "Add auth" | "Add JWT auth with refresh rotation, jose library, httpOnly cookie" |
|
||||
| "Style the dashboard" | "Tailwind: 3-col grid on lg, 1 on mobile, card shadows, hover states" |
|
||||
|
||||
**Test:** Could a different agent execute without clarifying questions?
|
||||
</task_breakdown>
|
||||
```
|
||||
|
||||
### `<output_contract>` — Return Protocol
|
||||
|
||||
```markdown
|
||||
<output_contract>
|
||||
## Return Protocol
|
||||
|
||||
Return ONE of these markers as the LAST section of output:
|
||||
|
||||
### Success
|
||||
```
|
||||
## TASK COMPLETE
|
||||
|
||||
{Summary of what was produced}
|
||||
{Artifact locations: file paths}
|
||||
{Key metrics: counts, coverage}
|
||||
```
|
||||
|
||||
### Blocked
|
||||
```
|
||||
## TASK BLOCKED
|
||||
|
||||
**Blocker:** {What's missing or preventing progress}
|
||||
**Need:** {Specific action/info that would unblock}
|
||||
**Attempted:** {What was tried before declaring blocked}
|
||||
```
|
||||
|
||||
### Checkpoint (needs user decision)
|
||||
```
|
||||
## CHECKPOINT REACHED
|
||||
|
||||
**Question:** {Decision needed from user}
|
||||
**Context:** {Why this matters}
|
||||
**Options:**
|
||||
1. {Option A} — {effect on output}
|
||||
2. {Option B} — {effect on output}
|
||||
```
|
||||
</output_contract>
|
||||
```
|
||||
|
||||
### `<quality_gate>` — Self-Check (ALWAYS LAST)
|
||||
|
||||
```markdown
|
||||
<quality_gate>
|
||||
Before returning, verify:
|
||||
- [ ] {Check 1 — concrete, grep-verifiable}
|
||||
- [ ] {Check 2 — concrete, counts/exists}
|
||||
- [ ] {Check 3 — concrete, structural}
|
||||
- [ ] {Check 4 — no prohibited content}
|
||||
</quality_gate>
|
||||
```
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
| Anti-Pattern | Why It's Wrong | Correct Approach |
|
||||
|-------------|----------------|------------------|
|
||||
| Agent contains `AskUserQuestion` | Agents don't interact with users | Return `## CHECKPOINT REACHED` |
|
||||
| Agent parses `$ARGUMENTS` | Arguments belong to the command | Receive pre-parsed values in prompt |
|
||||
| Agent displays banners | UI is the command's job | Return structured data |
|
||||
| `<role>` is not first section | Identity must be established first | Always lead with `<role>` |
|
||||
| Generic section names | Hard to scan, unclear scope | Name after domain concept |
|
||||
| No examples in domain sections | Rules without examples are ambiguous | Include comparison tables |
|
||||
| Agent spawns other agents | Spawning belongs to commands | Request via `## CHECKPOINT REACHED` |
|
||||
| Agent defines its own invocation syntax | That's the command's responsibility | Document in `Spawned by:` only |
|
||||
| Domain section covers multiple concerns | Violates single-concern rule | Split into separate sections |
|
||||
318
.claude/skills/prompt-generator/specs/command-design-spec.md
Normal file
318
.claude/skills/prompt-generator/specs/command-design-spec.md
Normal file
@@ -0,0 +1,318 @@
|
||||
# Command Design Specification
|
||||
|
||||
Guidelines for Claude Code **command files** (orchestration workflows). Commands own process flow, user interaction, and agent coordination — NOT domain expertise.
|
||||
|
||||
## Content Separation Principle
|
||||
|
||||
| Concern | Belongs in Command | Belongs in Agent |
|
||||
|---------|-------------------|-----------------|
|
||||
| Argument parsing | Yes | No |
|
||||
| Path resolution | Yes | No |
|
||||
| User prompts (AskUserQuestion) | Yes | No |
|
||||
| Status banners | Yes | No |
|
||||
| Agent spawning (Task) | Yes | No |
|
||||
| Flow control (if/else routing) | Yes | No |
|
||||
| Init/context loading (CLI tools) | Yes | No |
|
||||
| Revision loops | Yes | No |
|
||||
| Domain knowledge | No | Yes |
|
||||
| Quality heuristics | No | Yes |
|
||||
| Output format rules | No | Yes |
|
||||
| Role identity | No | Yes |
|
||||
|
||||
## YAML Frontmatter
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: command-name # Required: lowercase with hyphens
|
||||
description: Description # Required: brief purpose
|
||||
argument-hint: "[args]" # Optional: argument format hint
|
||||
allowed-tools: Tool1, Tool2 # Optional: restricted tool set
|
||||
---
|
||||
```
|
||||
|
||||
## Path Structure
|
||||
|
||||
```
|
||||
.claude/commands/deploy.md # Top-level command
|
||||
.claude/commands/issue/create.md # Grouped command
|
||||
~/.claude/commands/global-status.md # User-level command
|
||||
```
|
||||
|
||||
## Content Structure
|
||||
|
||||
Commands use XML semantic tags with process steps inside `<process>`:
|
||||
|
||||
| Tag | Required | Purpose |
|
||||
|-----|----------|---------|
|
||||
| `<purpose>` | Yes | What + when + what it produces (2-3 sentences) |
|
||||
| `<required_reading>` | Yes | @ file references loaded before execution |
|
||||
| `<process>` | Yes | Steps — numbered or named (see Step Styles below) |
|
||||
| `<auto_mode>` | Optional | Behavior when `--auto` flag present |
|
||||
| `<offer_next>` | Recommended | Formatted completion status + next actions |
|
||||
| `<success_criteria>` | Yes | Checkbox list of verifiable conditions |
|
||||
|
||||
## Step Styles
|
||||
|
||||
GSD uses two step styles. Choose based on command nature:
|
||||
|
||||
### Style A: Numbered Steps (for complex orchestrators)
|
||||
|
||||
Used by: `plan-phase.md`, `new-project.md`, `research-phase.md`
|
||||
|
||||
Best for: Multi-agent orchestration, long workflows with branching, revision loops.
|
||||
|
||||
```markdown
|
||||
<process>
|
||||
|
||||
## 1. Initialize
|
||||
|
||||
Load context, parse arguments.
|
||||
|
||||
## 2. Validate Phase
|
||||
|
||||
Check preconditions.
|
||||
|
||||
## 3. Spawn Agent
|
||||
|
||||
Display banner, construct prompt, spawn.
|
||||
|
||||
## 4. Handle Result
|
||||
|
||||
Route on return markers.
|
||||
|
||||
## 5. Present Status
|
||||
|
||||
Display offer_next.
|
||||
|
||||
</process>
|
||||
```
|
||||
|
||||
### Style B: Named `<step>` Blocks (for focused commands)
|
||||
|
||||
Used by: `execute-phase.md`, `discuss-phase.md`, `verify-work.md`
|
||||
|
||||
Best for: Sequential steps, clear atomic actions, step-level priority.
|
||||
|
||||
```markdown
|
||||
<process>
|
||||
|
||||
<step name="initialize" priority="first">
|
||||
Load context, parse arguments.
|
||||
</step>
|
||||
|
||||
<step name="validate_phase">
|
||||
Check preconditions.
|
||||
</step>
|
||||
|
||||
<step name="spawn_agent">
|
||||
Construct prompt, spawn agent.
|
||||
</step>
|
||||
|
||||
<step name="report">
|
||||
Display results.
|
||||
</step>
|
||||
|
||||
</process>
|
||||
```
|
||||
|
||||
### Which style to use?
|
||||
|
||||
| Criteria | Numbered | Named `<step>` |
|
||||
|----------|----------|----------------|
|
||||
| Agent spawning with revision loops | Yes | No |
|
||||
| Multiple conditional branches | Yes | No |
|
||||
| Sequential with clear boundaries | No | Yes |
|
||||
| Steps reference each other by number | Yes | No |
|
||||
| First step needs `priority="first"` | No | Yes |
|
||||
|
||||
## Init Pattern
|
||||
|
||||
Most GSD commands start by loading context via CLI tools:
|
||||
|
||||
```bash
|
||||
INIT=$(node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" init {command} "${ARG}")
|
||||
if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
|
||||
```
|
||||
|
||||
For non-GSD commands, the equivalent is reading config/state files:
|
||||
|
||||
```bash
|
||||
# Read project state
|
||||
CONFIG=$(cat .claude/config.json 2>/dev/null || echo '{}')
|
||||
```
|
||||
|
||||
## Banner Style
|
||||
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
SKILL ► ACTION
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
```
|
||||
|
||||
Display banners before major phase transitions (agent spawning, user decisions, completion).
|
||||
|
||||
## Agent Spawning Pattern
|
||||
|
||||
Commands spawn agents via `Task()` with structured prompts:
|
||||
|
||||
```markdown
|
||||
Task(
|
||||
prompt=filled_prompt,
|
||||
subagent_type="agent-name",
|
||||
model="{model}",
|
||||
description="Verb Phase {X}"
|
||||
)
|
||||
```
|
||||
|
||||
### Prompt Structure for Agents
|
||||
|
||||
The prompt passed to agents uses XML blocks:
|
||||
|
||||
```markdown
|
||||
<objective>
|
||||
What to accomplish — specific and measurable.
|
||||
</objective>
|
||||
|
||||
<files_to_read>
|
||||
- {path1} (description — what this file provides)
|
||||
- {path2} (description)
|
||||
</files_to_read>
|
||||
|
||||
<additional_context>
|
||||
**Phase:** {number}
|
||||
**Mode:** {standard | revision | gap_closure}
|
||||
Extra info the agent needs.
|
||||
</additional_context>
|
||||
|
||||
<output>
|
||||
Write to: {output_path}
|
||||
</output>
|
||||
```
|
||||
|
||||
### Return Handling
|
||||
|
||||
Commands route on agent return markers:
|
||||
|
||||
```markdown
|
||||
## Handle Agent Return
|
||||
|
||||
- **`## TASK COMPLETE`:** Display confirmation, continue to next step.
|
||||
- **`## TASK BLOCKED`:** Display blocker, offer user options:
|
||||
1) Provide context 2) Skip 3) Abort
|
||||
- **`## CHECKPOINT REACHED`:** Present question to user, relay response.
|
||||
```
|
||||
|
||||
## Revision Loop Pattern
|
||||
|
||||
For commands that iterate between generation and verification:
|
||||
|
||||
```markdown
|
||||
## N. Revision Loop (Max 3 Iterations)
|
||||
|
||||
Track `iteration_count` (starts at 1).
|
||||
|
||||
**If iteration_count < 3:**
|
||||
- Display: "Sending back for revision... (iteration {N}/3)"
|
||||
- Spawn agent with revision prompt + checker issues
|
||||
- After agent returns → spawn checker again, increment count
|
||||
|
||||
**If iteration_count >= 3:**
|
||||
- Display remaining issues
|
||||
- Offer: 1) Force proceed 2) Provide guidance 3) Abandon
|
||||
```
|
||||
|
||||
## Auto Mode Pattern
|
||||
|
||||
Commands supporting `--auto` flag define behavior in `<auto_mode>`:
|
||||
|
||||
```markdown
|
||||
<auto_mode>
|
||||
## Auto Mode Detection
|
||||
|
||||
Check if `--auto` flag is present in $ARGUMENTS.
|
||||
|
||||
**If auto mode:**
|
||||
- Skip confirmation prompts
|
||||
- Use smart defaults for optional choices
|
||||
- Auto-approve intermediate results
|
||||
- Chain to next command on success
|
||||
|
||||
**Document requirement (if applicable):**
|
||||
- What --auto requires as input
|
||||
- Error message if requirements not met
|
||||
</auto_mode>
|
||||
```
|
||||
|
||||
## offer_next Pattern
|
||||
|
||||
```markdown
|
||||
<offer_next>
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
SKILL ► TASK COMPLETE
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
**{Summary line}**
|
||||
|
||||
| Key | Value |
|
||||
|-----|-------|
|
||||
| ... | ... |
|
||||
|
||||
Status: {metric 1} | {metric 2}
|
||||
|
||||
───────────────────────────────────────────────────────
|
||||
|
||||
## Next Up
|
||||
|
||||
**{Primary next action}**
|
||||
|
||||
/{next-command} {args}
|
||||
|
||||
<sub>/clear first — fresh context window</sub>
|
||||
|
||||
───────────────────────────────────────────────────────
|
||||
|
||||
**Also available:**
|
||||
- /{alt-1} — description
|
||||
- /{alt-2} — description
|
||||
|
||||
───────────────────────────────────────────────────────
|
||||
</offer_next>
|
||||
```
|
||||
|
||||
## AskUserQuestion Pattern
|
||||
|
||||
For user decisions within commands:
|
||||
|
||||
```markdown
|
||||
AskUserQuestion(
|
||||
header: "Context",
|
||||
question: "Descriptive question?",
|
||||
options: [
|
||||
{ label: "Option A", description: "Effect of choosing A" },
|
||||
{ label: "Option B", description: "Effect of choosing B" }
|
||||
]
|
||||
)
|
||||
|
||||
If "Option A": {action}
|
||||
If "Option B": {action}
|
||||
```
|
||||
|
||||
## Shell Correctness Rules
|
||||
|
||||
| Rule | Wrong | Correct |
|
||||
|------|-------|---------|
|
||||
| Multi-line output | `echo "{ ... }"` | `cat <<'EOF' > file`...`EOF` |
|
||||
| Variable init | Use `$VAR` after conditional | Initialize BEFORE conditional |
|
||||
| Error exit | `echo "Error"` (no exit) | `echo "Error" && exit 1` |
|
||||
| Quoting | `$VAR` bare | `"$VAR"` quoted |
|
||||
| Prerequisites | Implicit tool usage | Declare in `<prerequisites>` |
|
||||
| File existence | Assume file exists | `test -f "$FILE" && ...` |
|
||||
|
||||
## Step Naming Conventions
|
||||
|
||||
| Domain | Typical Steps |
|
||||
|--------|--------------|
|
||||
| Multi-Agent Pipeline | Initialize, Validate, Spawn Agent A, Handle A Result, Spawn Agent B, Revision Loop, Present Status |
|
||||
| Deploy/Release | Initialize, Validate Config, Run Deployment, Verify Health, Present Status |
|
||||
| CRUD | Initialize, Validate Entity, Persist Changes, Present Status |
|
||||
| Analysis | Initialize, Gather Context, Spawn Analyzer, Present Findings |
|
||||
151
.claude/skills/prompt-generator/specs/conversion-spec.md
Normal file
151
.claude/skills/prompt-generator/specs/conversion-spec.md
Normal file
@@ -0,0 +1,151 @@
|
||||
# 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}
|
||||
```
|
||||
|
||||
## 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 |
|
||||
| `Task()` / 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:
|
||||
|
||||
```bash
|
||||
# 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 |
|
||||
Reference in New Issue
Block a user