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
401
.claude/skills/prompt-generator/SKILL.md
Normal file
401
.claude/skills/prompt-generator/SKILL.md
Normal file
@@ -0,0 +1,401 @@
|
||||
---
|
||||
name: prompt-generator
|
||||
description: Generate or convert Claude Code prompt files — command orchestrators, agent role definitions, or style conversion of existing files. Follows GSD-style content separation with built-in quality gates. Triggers on "create command", "new command", "create agent", "new agent", "convert command", "convert agent", "prompt generator".
|
||||
allowed-tools: Read, Write, Edit, Bash, Glob, AskUserQuestion
|
||||
---
|
||||
|
||||
<purpose>
|
||||
Generate or convert Claude Code prompt files with concrete, domain-specific content. Three modes:
|
||||
|
||||
- **Create command** — new orchestration workflow at `.claude/commands/` or `~/.claude/commands/`
|
||||
- **Create agent** — new role + expertise file at `.claude/agents/`
|
||||
- **Convert** — restyle existing command/agent to GSD conventions with zero content loss
|
||||
|
||||
Content separation principle (from GSD): commands own orchestration flow; agents own domain knowledge.
|
||||
|
||||
Invoked when user requests "create command", "new command", "create agent", "new agent", "convert command", "convert agent", or "prompt generator".
|
||||
</purpose>
|
||||
|
||||
<required_reading>
|
||||
- @.claude/skills/prompt-generator/specs/command-design-spec.md
|
||||
- @.claude/skills/prompt-generator/specs/agent-design-spec.md
|
||||
- @.claude/skills/prompt-generator/specs/conversion-spec.md
|
||||
- @.claude/skills/prompt-generator/templates/command-md.md
|
||||
- @.claude/skills/prompt-generator/templates/agent-md.md
|
||||
</required_reading>
|
||||
|
||||
<process>
|
||||
|
||||
## 1. Determine Artifact Type
|
||||
|
||||
Parse `$ARGUMENTS` to determine what to generate.
|
||||
|
||||
| Signal | Type |
|
||||
|--------|------|
|
||||
| "command", "workflow", "orchestrator" in args | `command` |
|
||||
| "agent", "role", "worker" in args | `agent` |
|
||||
| "convert", "restyle", "refactor" + file path in args | `convert` |
|
||||
| Ambiguous or missing | Ask user |
|
||||
|
||||
**Convert mode detection:** If args contain a file path (`.md` extension) + conversion keywords, enter convert mode. Extract `$SOURCE_PATH` from args.
|
||||
|
||||
If ambiguous:
|
||||
|
||||
```
|
||||
AskUserQuestion(
|
||||
header: "Artifact Type",
|
||||
question: "What type of prompt file do you want to generate?",
|
||||
options: [
|
||||
{ label: "Command", description: "New orchestration workflow — process steps, user interaction, agent spawning" },
|
||||
{ label: "Agent", description: "New role definition — identity, domain expertise, behavioral rules" },
|
||||
{ label: "Convert", description: "Restyle existing command/agent to GSD conventions (zero content loss)" }
|
||||
]
|
||||
)
|
||||
```
|
||||
|
||||
Store as `$ARTIFACT_TYPE` (`command` | `agent` | `convert`).
|
||||
|
||||
## 2. Validate Parameters
|
||||
|
||||
**If `$ARTIFACT_TYPE` is `convert`:** Skip to Step 2c.
|
||||
|
||||
Extract from `$ARGUMENTS` or ask interactively:
|
||||
|
||||
**Common parameters (create mode):**
|
||||
|
||||
| Parameter | Required | Validation | Example |
|
||||
|-----------|----------|------------|---------|
|
||||
| `$NAME` | Yes | `/^[a-z][a-z0-9-]*$/` | `deploy`, `gsd-planner` |
|
||||
| `$DESCRIPTION` | Yes | min 10 chars | `"Deploy to production with rollback"` |
|
||||
|
||||
**Command-specific parameters:**
|
||||
|
||||
| Parameter | Required | Validation | Example |
|
||||
|-----------|----------|------------|---------|
|
||||
| `$LOCATION` | Yes | `"project"` or `"user"` | `project` |
|
||||
| `$GROUP` | No | `/^[a-z][a-z0-9-]*$/` | `issue`, `workflow` |
|
||||
| `$ARGUMENT_HINT` | No | any string | `"<phase> [--skip-verify]"` |
|
||||
|
||||
**Agent-specific parameters:**
|
||||
|
||||
| Parameter | Required | Validation | Example |
|
||||
|-----------|----------|------------|---------|
|
||||
| `$TOOLS` | No | comma-separated tool names | `Read, Write, Bash, Glob` |
|
||||
| `$SPAWNED_BY` | No | which command spawns this agent | `/plan-phase orchestrator` |
|
||||
|
||||
Normalize: trim + lowercase for `$NAME`, `$LOCATION`, `$GROUP`.
|
||||
|
||||
## 3. Resolve Target Path
|
||||
|
||||
**Command:**
|
||||
|
||||
| Location | Base |
|
||||
|----------|------|
|
||||
| `project` | `.claude/commands` |
|
||||
| `user` | `~/.claude/commands` |
|
||||
|
||||
```
|
||||
If $GROUP:
|
||||
$TARGET_PATH = {base}/{$GROUP}/{$NAME}.md
|
||||
Else:
|
||||
$TARGET_PATH = {base}/{$NAME}.md
|
||||
```
|
||||
|
||||
**Agent:**
|
||||
|
||||
```
|
||||
$TARGET_PATH = .claude/agents/{$NAME}.md
|
||||
```
|
||||
|
||||
Check if `$TARGET_PATH` exists → `$FILE_EXISTS`.
|
||||
|
||||
## 4. Gather Requirements
|
||||
|
||||
**4a. Pattern discovery** — Find 3+ similar files in the project for style reference:
|
||||
|
||||
```bash
|
||||
# For commands: scan existing commands
|
||||
ls .claude/commands/**/*.md 2>/dev/null | head -5
|
||||
|
||||
# For agents: scan existing agents
|
||||
ls .claude/agents/*.md 2>/dev/null | head -5
|
||||
```
|
||||
|
||||
Read 1-2 similar files to extract patterns: section structure, naming conventions, XML tag usage, prompt style.
|
||||
|
||||
**4b. Domain inference** from `$NAME`, `$DESCRIPTION`, and context:
|
||||
|
||||
| Signal | Extract |
|
||||
|--------|---------|
|
||||
| `$NAME` | Action verb → step/section naming |
|
||||
| `$DESCRIPTION` | Domain keywords → content structure |
|
||||
| `$ARGUMENT_HINT` | Flags → parse_input logic (command only) |
|
||||
| `$SPAWNED_BY` | Upstream contract → role boundary (agent only) |
|
||||
|
||||
**For commands — determine complexity:**
|
||||
|
||||
| Complexity | Criteria | Steps |
|
||||
|------------|----------|-------|
|
||||
| Simple | Single action, no flags | 3-5 numbered steps |
|
||||
| Standard | 1-2 flags, clear workflow | 5-8 numbered steps |
|
||||
| Complex | Multiple flags, agent spawning | 8-14 numbered steps |
|
||||
|
||||
**For agents — determine expertise scope:**
|
||||
|
||||
| Scope | Criteria | Sections |
|
||||
|-------|----------|----------|
|
||||
| Focused | Single responsibility | `<role>` + 1-2 domain sections |
|
||||
| Standard | Multi-aspect domain | `<role>` + 2-4 domain sections |
|
||||
| Expert | Deep domain with rules | `<role>` + 4-6 domain sections |
|
||||
|
||||
If unclear, ask user with AskUserQuestion.
|
||||
|
||||
## 5. Generate Content
|
||||
|
||||
Route to the appropriate generation logic based on `$ARTIFACT_TYPE`.
|
||||
|
||||
### 5a. Command Generation
|
||||
|
||||
Follow `@specs/command-design-spec.md` and `@templates/command-md.md`.
|
||||
|
||||
Generate a complete command file with:
|
||||
|
||||
1. **`<purpose>`** — 2-3 sentences: what + when + what it produces
|
||||
2. **`<required_reading>`** — @ references to context files
|
||||
3. **`<process>`** — numbered steps (GSD workflow style):
|
||||
- Step 1: Initialize / parse arguments
|
||||
- Steps 2-N: Domain-specific orchestration logic
|
||||
- Each step: banner display, validation, agent spawning via `Task()`, error handling
|
||||
- Final step: status display + `<offer_next>` with next actions
|
||||
4. **`<success_criteria>`** — checkbox list of verifiable conditions
|
||||
|
||||
**Command writing rules:**
|
||||
- Steps are **numbered** (`## 1.`, `## 2.`) — follow `plan-phase.md` and `new-project.md` style
|
||||
- Use banners for phase transitions: `━━━ SKILL ► ACTION ━━━`
|
||||
- Agent spawning uses `Task(prompt, subagent_type, description)` pattern
|
||||
- Prompt to agents uses `<objective>`, `<files_to_read>`, `<output>` blocks
|
||||
- Include `<offer_next>` block with formatted completion status
|
||||
- Handle agent return markers: `## TASK COMPLETE`, `## TASK BLOCKED`, `## CHECKPOINT REACHED`
|
||||
- Shell blocks use heredoc for multi-line, quote all variables
|
||||
- Include `<auto_mode>` section if command supports `--auto` flag
|
||||
|
||||
### 5b. Agent Generation
|
||||
|
||||
Follow `@specs/agent-design-spec.md` and `@templates/agent-md.md`.
|
||||
|
||||
Generate a complete agent definition with:
|
||||
|
||||
1. **YAML frontmatter** — name, description, tools, color (optional)
|
||||
2. **`<role>`** — identity + spawned-by + core responsibilities + mandatory initial read
|
||||
3. **Domain sections** (2-6 based on scope):
|
||||
- `<philosophy>` — guiding principles, anti-patterns
|
||||
- `<context_fidelity>` — how to honor upstream decisions
|
||||
- `<task_breakdown>` / `<output_format>` — concrete output rules with examples
|
||||
- `<quality_gate>` — self-check criteria before returning
|
||||
- Custom domain sections as needed
|
||||
4. **Output contract** — structured return markers to orchestrator
|
||||
|
||||
**Agent writing rules:**
|
||||
- `<role>` is ALWAYS first after frontmatter — defines identity
|
||||
- Each section owns ONE concern — no cross-cutting
|
||||
- Include concrete examples (good vs bad comparison tables) in every domain section
|
||||
- Include decision/routing tables for conditional logic
|
||||
- Quality gate uses checkbox format for self-verification
|
||||
- Agent does NOT contain orchestration logic, user interaction, or argument parsing
|
||||
|
||||
### 5c. Convert Mode (Restyle Existing File)
|
||||
|
||||
**CRITICAL: Zero content loss.** Follow `@specs/conversion-spec.md`.
|
||||
|
||||
**Step 5c.1: Read and inventory source file.**
|
||||
|
||||
Read `$SOURCE_PATH` completely. Build content inventory:
|
||||
|
||||
```
|
||||
$INVENTORY = {
|
||||
frontmatter: { fields extracted },
|
||||
sections: [ { name, tag, line_range, line_count, has_code_blocks, has_tables } ],
|
||||
code_blocks: count,
|
||||
tables: count,
|
||||
total_lines: count
|
||||
}
|
||||
```
|
||||
|
||||
**Step 5c.2: Classify source type.**
|
||||
|
||||
| Signal | Type |
|
||||
|--------|------|
|
||||
| Contains `<process>`, `<step>`, numbered `## N.` steps | command |
|
||||
| Contains `<role>`, `tools:` in frontmatter, domain sections | agent |
|
||||
| Flat markdown with `## Implementation`, `## Phase N` | command (unstructured) |
|
||||
| Flat prose with role description, no process steps | agent (unstructured) |
|
||||
|
||||
**Step 5c.3: Build conversion map.**
|
||||
|
||||
Map every source section to its target location. Follow `@specs/conversion-spec.md` transformation rules.
|
||||
|
||||
**MANDATORY**: Every line of source content must appear in the conversion map. If a source section has no clear target, keep it as a custom section.
|
||||
|
||||
**Step 5c.4: Generate converted content.**
|
||||
|
||||
Apply structural transformations while preserving ALL content verbatim:
|
||||
- Rewrap into GSD XML tags
|
||||
- Restructure sections to match target template ordering
|
||||
- Add missing required sections (empty `<quality_gate>`, `<output_contract>`) with `TODO` markers
|
||||
- Preserve all code blocks, tables, examples, shell commands exactly as-is
|
||||
|
||||
**Step 5c.5: Content loss verification (MANDATORY).**
|
||||
|
||||
Compare source and output:
|
||||
|
||||
| Metric | Source | Output | Pass? |
|
||||
|--------|--------|--------|-------|
|
||||
| Total lines | `$SRC_LINES` | `$OUT_LINES` | output >= source × 0.95 |
|
||||
| Code blocks | `$SRC_BLOCKS` | `$OUT_BLOCKS` | output >= source |
|
||||
| Tables | `$SRC_TABLES` | `$OUT_TABLES` | output >= source |
|
||||
| Sections | `$SRC_SECTIONS` | `$OUT_SECTIONS` | output >= source |
|
||||
|
||||
If ANY metric fails → STOP, display diff, ask user before proceeding.
|
||||
|
||||
Set `$TARGET_PATH = $SOURCE_PATH` (in-place conversion) unless user specifies output path.
|
||||
|
||||
### Content quality rules (both types):
|
||||
- NO bracket placeholders (`[Describe...]`) — all content concrete
|
||||
- NO generic instructions ("handle errors appropriately") — be specific
|
||||
- Include domain-specific examples derived from `$DESCRIPTION`
|
||||
- Every shell block: heredoc for multi-line, quoted variables, error exits
|
||||
|
||||
## 6. Quality Gate
|
||||
|
||||
**MANDATORY before writing.** Read back the generated content and validate against type-specific checks.
|
||||
|
||||
### 6a. Structural Validation (both types)
|
||||
|
||||
| Check | Pass Condition |
|
||||
|-------|---------------|
|
||||
| YAML frontmatter | Has `name` + `description` |
|
||||
| No placeholders | Zero `[...]` or `{...}` bracket placeholders in prose |
|
||||
| Concrete content | Every section has actionable content, not descriptions of what to write |
|
||||
| Section count | Command: 3+ sections; Agent: 4+ sections |
|
||||
|
||||
### 6b. Command-Specific Checks
|
||||
|
||||
| Check | Pass Condition |
|
||||
|-------|---------------|
|
||||
| `<purpose>` | 2-3 sentences, no placeholders |
|
||||
| `<process>` with numbered steps | At least 3 `## N.` headers |
|
||||
| Step 1 is initialization | Parses args or loads context |
|
||||
| Last step is status/report | Displays results or routes to `<offer_next>` |
|
||||
| Agent spawning (if complex) | `Task(` call with `subagent_type` |
|
||||
| Agent prompt structure | `<files_to_read>` + `<objective>` or `<output>` blocks |
|
||||
| Return handling | Routes on `## TASK COMPLETE` / `## TASK BLOCKED` markers |
|
||||
| `<offer_next>` | Banner + summary + next command suggestion |
|
||||
| `<success_criteria>` | 4+ checkbox items, all verifiable |
|
||||
| Content separation | No domain expertise embedded — only orchestration |
|
||||
|
||||
### 6c. Agent-Specific Checks
|
||||
|
||||
| Check | Pass Condition |
|
||||
|-------|---------------|
|
||||
| YAML `tools` field | Lists tools agent needs |
|
||||
| `<role>` is first section | Appears before any domain section |
|
||||
| `<role>` has spawned-by | States which command spawns it |
|
||||
| `<role>` has mandatory read | `<files_to_read>` instruction present |
|
||||
| `<role>` has responsibilities | 3+ bullet points with verb phrases |
|
||||
| Domain sections named | After domain concepts, not generic (`<rules>`, `<guidelines>`) |
|
||||
| Examples present | Each domain section has 1+ comparison table or decision table |
|
||||
| `<output_contract>` | Defines return markers (COMPLETE/BLOCKED/CHECKPOINT) |
|
||||
| `<quality_gate>` | 3+ checkbox self-check items |
|
||||
| Content separation | No `AskUserQuestion`, no banner display, no argument parsing |
|
||||
|
||||
### 6d. Quality Gate Result
|
||||
|
||||
Count errors and warnings:
|
||||
|
||||
| Gate | Condition | Action |
|
||||
|------|-----------|--------|
|
||||
| **PASS** | 0 errors, 0-2 warnings | Proceed to write |
|
||||
| **REVIEW** | 1-2 errors or 3+ warnings | Fix errors, display warnings |
|
||||
| **FAIL** | 3+ errors | Re-generate from step 5 |
|
||||
|
||||
If FAIL and second attempt also fails:
|
||||
|
||||
```
|
||||
AskUserQuestion(
|
||||
header: "Quality Gate Failed",
|
||||
question: "Generated content failed quality checks twice. How to proceed?",
|
||||
options: [
|
||||
{ label: "Show issues and proceed", description: "Write as-is, fix manually" },
|
||||
{ label: "Provide more context", description: "I'll give additional details" },
|
||||
{ label: "Abort", description: "Cancel generation" }
|
||||
]
|
||||
)
|
||||
```
|
||||
|
||||
## 7. Write and Verify
|
||||
|
||||
**If `$FILE_EXISTS`:** Warn user before overwriting.
|
||||
|
||||
```bash
|
||||
mkdir -p "$(dirname "$TARGET_PATH")"
|
||||
```
|
||||
|
||||
Write content to `$TARGET_PATH` using Write tool.
|
||||
|
||||
**Post-write verification** — Read back and confirm file integrity:
|
||||
- File exists and is non-empty
|
||||
- Content matches what was generated (no corruption)
|
||||
- File size is reasonable (command: 50-500 lines; agent: 80-600 lines)
|
||||
|
||||
**If verification fails:** Fix in-place with Edit tool.
|
||||
|
||||
## 8. Present Status
|
||||
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
PROMPT-GEN ► {COMMAND|AGENT} GENERATED
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
Type: {command | agent}
|
||||
File: {$TARGET_PATH}
|
||||
Name: {$NAME}
|
||||
|
||||
| Section | Status |
|
||||
|---------|--------|
|
||||
| {section 1} | concrete |
|
||||
| {section 2} | concrete |
|
||||
| ... | ... |
|
||||
|
||||
Quality Gate: {PASS | REVIEW (N warnings)}
|
||||
|
||||
───────────────────────────────────────────────────────
|
||||
|
||||
## Next Up
|
||||
|
||||
1. Review: cat {$TARGET_PATH}
|
||||
2. Test: /{invocation}
|
||||
|
||||
**If command + needs an agent:**
|
||||
/prompt-generator agent {agent-name} "{agent description}"
|
||||
|
||||
**If agent + needs a command:**
|
||||
/prompt-generator command {command-name} "{command description}"
|
||||
|
||||
───────────────────────────────────────────────────────
|
||||
```
|
||||
|
||||
</process>
|
||||
|
||||
<success_criteria>
|
||||
- [ ] Artifact type determined (command or agent)
|
||||
- [ ] All required parameters validated
|
||||
- [ ] Target path resolved correctly
|
||||
- [ ] 1-2 similar existing files read for pattern reference
|
||||
- [ ] Domain requirements gathered from description
|
||||
- [ ] Content generated with concrete, domain-specific logic
|
||||
- [ ] GSD content separation respected (commands = orchestration, agents = expertise)
|
||||
- [ ] Quality gate passed (structural + type-specific checks)
|
||||
- [ ] No bracket placeholders in final output
|
||||
- [ ] File written and post-write verified
|
||||
- [ ] Status banner displayed with quality gate result
|
||||
</success_criteria>
|
||||
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 |
|
||||
145
.claude/skills/prompt-generator/templates/agent-md.md
Normal file
145
.claude/skills/prompt-generator/templates/agent-md.md
Normal file
@@ -0,0 +1,145 @@
|
||||
# Agent Template — Structural Reference
|
||||
|
||||
Defines the structural pattern for generated **agent definition files**. The generator uses this as a guide to produce concrete, domain-specific content — NOT as a literal copy target.
|
||||
|
||||
## Required Structure
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: {$NAME}
|
||||
description: {One-line purpose. Spawned by /command-name orchestrator.}
|
||||
tools: {Read, Write, Bash, Glob, Grep}
|
||||
color: {green|blue|yellow|red} # optional
|
||||
---
|
||||
|
||||
<role>
|
||||
You are a {role name}. You {primary action} {what you produce}.
|
||||
|
||||
Spawned by:
|
||||
- `/{command}` orchestrator (standard mode)
|
||||
- `/{command} --flag` orchestrator (variant mode)
|
||||
|
||||
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:**
|
||||
- {Verb phrase — primary task}
|
||||
- {Verb phrase — secondary task}
|
||||
- {Verb phrase — quality assurance}
|
||||
- Return structured results to orchestrator
|
||||
</role>
|
||||
|
||||
<philosophy>
|
||||
## {Guiding Principle Name}
|
||||
|
||||
{Core beliefs — 3-5 bullet points}
|
||||
|
||||
**Anti-patterns (delete if seen):**
|
||||
- {Anti-pattern 1}
|
||||
- {Anti-pattern 2}
|
||||
</philosophy>
|
||||
|
||||
<{domain_section_1}>
|
||||
## {Domain Concept Name}
|
||||
|
||||
{Rules, heuristics, decision tables for this aspect.}
|
||||
|
||||
| {Condition} | {Action} |
|
||||
|-------------|----------|
|
||||
| ... | ... |
|
||||
|
||||
{Concrete examples — good vs bad:}
|
||||
|
||||
| TOO VAGUE | JUST RIGHT |
|
||||
|-----------|------------|
|
||||
| "..." | "..." |
|
||||
</{domain_section_1}>
|
||||
|
||||
<{domain_section_2}>
|
||||
## {Another Domain Concept}
|
||||
|
||||
{Format templates, structural rules, required fields.}
|
||||
|
||||
Every {output unit} has {N} required fields:
|
||||
- **<field_1>:** {What it contains, why it matters}
|
||||
- **<field_2>:** {What it contains, why it matters}
|
||||
</{domain_section_2}>
|
||||
|
||||
<output_contract>
|
||||
## Return Protocol
|
||||
|
||||
Agent returns one of these markers to the orchestrator:
|
||||
|
||||
### Success
|
||||
```
|
||||
## TASK COMPLETE
|
||||
|
||||
{Structured output summary}
|
||||
{Artifact locations}
|
||||
```
|
||||
|
||||
### Blocked
|
||||
```
|
||||
## TASK BLOCKED
|
||||
|
||||
**Blocker:** {What's missing}
|
||||
**Need:** {What would unblock}
|
||||
```
|
||||
|
||||
### Checkpoint
|
||||
```
|
||||
## CHECKPOINT REACHED
|
||||
|
||||
**Question:** {Decision needed from user}
|
||||
**Options:**
|
||||
1. {Option A} — {effect}
|
||||
2. {Option B} — {effect}
|
||||
```
|
||||
</output_contract>
|
||||
|
||||
<quality_gate>
|
||||
Before returning, verify:
|
||||
- [ ] {Check 1 — concrete, verifiable}
|
||||
- [ ] {Check 2 — concrete, verifiable}
|
||||
- [ ] {Check 3 — concrete, verifiable}
|
||||
- [ ] {Check 4 — concrete, verifiable}
|
||||
</quality_gate>
|
||||
```
|
||||
|
||||
## Section Design Guidelines
|
||||
|
||||
### Section Naming
|
||||
|
||||
Name sections after the domain concept they cover:
|
||||
|
||||
| Good | Bad |
|
||||
|------|-----|
|
||||
| `<task_breakdown>` | `<rules>` |
|
||||
| `<dependency_graph>` | `<guidelines>` |
|
||||
| `<code_style>` | `<misc>` |
|
||||
| `<review_dimensions>` | `<other>` |
|
||||
|
||||
### Section Independence
|
||||
|
||||
Each section owns ONE concern. Test: can you explain the section's scope in one sentence?
|
||||
|
||||
| One Concern | Multiple Concerns (split it) |
|
||||
|-------------|------------------------------|
|
||||
| How to size tasks | How to size tasks AND how to order them |
|
||||
| Review criteria | Review criteria AND how to present results |
|
||||
| Error handling rules | Error handling AND logging AND monitoring |
|
||||
|
||||
### Example Density
|
||||
|
||||
Domain sections MUST include concrete examples. Minimum per section:
|
||||
|
||||
| Section Type | Minimum Examples |
|
||||
|-------------|-----------------|
|
||||
| Rules/heuristics | 1 good-vs-bad table |
|
||||
| Format definitions | 1 complete template |
|
||||
| Decision logic | 1 routing table |
|
||||
| Quality criteria | 3+ checkbox items |
|
||||
117
.claude/skills/prompt-generator/templates/command-md.md
Normal file
117
.claude/skills/prompt-generator/templates/command-md.md
Normal file
@@ -0,0 +1,117 @@
|
||||
# Command Template — Structural Reference
|
||||
|
||||
Defines the structural pattern for generated **command files**. The generator uses this as a guide to produce concrete, domain-specific content — NOT as a literal copy target.
|
||||
|
||||
## Required Structure
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: {$NAME}
|
||||
description: {$DESCRIPTION}
|
||||
argument-hint: {$ARGUMENT_HINT} # omit if empty
|
||||
allowed-tools: {tools} # omit if unrestricted
|
||||
---
|
||||
|
||||
<purpose>
|
||||
{2-3 sentences: what it does + when invoked + what it produces}
|
||||
</purpose>
|
||||
|
||||
<required_reading>
|
||||
{@ references to files needed before execution}
|
||||
</required_reading>
|
||||
|
||||
<process>
|
||||
|
||||
## 1. Initialize
|
||||
|
||||
{Load context, parse $ARGUMENTS, validate preconditions.}
|
||||
|
||||
{Argument table:}
|
||||
| Flag/Arg | Required | Description |
|
||||
|----------|----------|-------------|
|
||||
| `$ARG1` | Yes | ... |
|
||||
| `--flag` | No | ... |
|
||||
|
||||
{Validation: missing required → error, invalid → error with usage hint.}
|
||||
|
||||
## 2. {Domain Action}
|
||||
|
||||
{Display banner:}
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
SKILL ► ACTION
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
```
|
||||
|
||||
{Core orchestration logic — file checks, state validation, conditional routing.}
|
||||
|
||||
## 3. Spawn Agent (if applicable)
|
||||
|
||||
{Construct prompt with <files_to_read>, <objective>, <output> blocks.}
|
||||
|
||||
```
|
||||
Task(
|
||||
prompt=filled_prompt,
|
||||
subagent_type="{agent-name}",
|
||||
description="{Verb} {target}"
|
||||
)
|
||||
```
|
||||
|
||||
## 4. Handle Result
|
||||
|
||||
{Route on agent return markers:}
|
||||
- `## TASK COMPLETE` → continue to next step
|
||||
- `## TASK BLOCKED` → display blocker, offer options
|
||||
- `## CHECKPOINT REACHED` → present to user, relay response
|
||||
|
||||
## N. Present Status
|
||||
|
||||
{Route to <offer_next>.}
|
||||
|
||||
</process>
|
||||
|
||||
<offer_next>
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
SKILL ► TASK COMPLETE
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
**{Summary line}**
|
||||
|
||||
{Status table or key-value pairs}
|
||||
|
||||
## Next Up
|
||||
|
||||
/{next-command} {args}
|
||||
|
||||
**Also available:**
|
||||
- /{alt-command-1} — description
|
||||
- /{alt-command-2} — description
|
||||
</offer_next>
|
||||
|
||||
<success_criteria>
|
||||
- [ ] {Precondition validated}
|
||||
- [ ] {Core action completed}
|
||||
- [ ] {Agent spawned and returned (if applicable)}
|
||||
- [ ] {Output artifact produced / effect applied}
|
||||
- [ ] {Status displayed to user}
|
||||
</success_criteria>
|
||||
```
|
||||
|
||||
## Step Naming Conventions
|
||||
|
||||
| Domain | Typical Steps |
|
||||
|--------|--------------|
|
||||
| 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 |
|
||||
| Multi-Agent | Initialize, Spawn Agent A, Handle A Result, Spawn Agent B, Revision Loop, Present Status |
|
||||
| Pipeline | Initialize, Stage 1, Handle Stage 1, Stage 2, Handle Stage 2, Present Status |
|
||||
|
||||
## Content Quality Rules
|
||||
|
||||
| Rule | Bad | Good |
|
||||
|------|-----|------|
|
||||
| No placeholders | `[Describe purpose]` | `Deploy to target environment with rollback on failure.` |
|
||||
| Concrete steps | `Handle the deployment` | `Run kubectl apply, wait for rollout, check health endpoint` |
|
||||
| Specific errors | `Error: invalid` | `Error: --env must be "prod" or "staging"` |
|
||||
| Verifiable criteria | `Works correctly` | `Health endpoint returns 200 within 30s` |
|
||||
Reference in New Issue
Block a user