diff --git a/.claude/commands/workflow/analyze-with-file.md b/.claude/commands/workflow/analyze-with-file.md index c02958ce..9d6b32b0 100644 --- a/.claude/commands/workflow/analyze-with-file.md +++ b/.claude/commands/workflow/analyze-with-file.md @@ -9,26 +9,23 @@ allowed-tools: TodoWrite(*), Agent(*), AskUserQuestion(*), Read(*), Grep(*), Glo When `--yes` or `-y`: Auto-confirm exploration decisions, use recommended analysis angles. -# Workflow Analyze Command + +Interactive collaborative analysis workflow combining codebase exploration (cli-explore-agent) with CLI-assisted analysis (Gemini/Codex). Produces a documented discussion timeline with evolving understanding, decision trails, and actionable conclusions. -**Context Source**: cli-explore-agent + Gemini/Codex analysis -**Output Directory**: `.workflow/.analysis/{session-id}/` -**Core Innovation**: Documented discussion timeline with evolving understanding +Invoked when user needs deep, multi-perspective analysis of a topic or codebase question — e.g., architecture review, implementation analysis, concept exploration, or decision evaluation. -## Output Artifacts +Produces: `discussion.md` (evolving analysis document with TOC, rounds, narrative synthesis), `explorations.json`/`perspectives.json` (structured findings), `conclusions.json` (final synthesis with recommendations). All artifacts stored in `.workflow/.analysis/{session-id}/`. + -| Phase | Artifact | Description | -|-------|----------|-------------| -| 1 | `discussion.md` | Initialized with TOC, Current Understanding block, timeline, metadata | -| 1 | Session variables | Dimensions, focus areas, analysis depth | -| 2 | `exploration-codebase.json` | Single codebase context from cli-explore-agent | -| 2 | `explorations/*.json` | Multi-perspective codebase explorations (parallel, up to 4) | -| 2 | `explorations.json` | Single perspective aggregated findings | -| 2 | `perspectives.json` | Multi-perspective findings (up to 4) with synthesis | -| 2 | Updated `discussion.md` | Round 1 + Initial Intent Coverage Check + Current Understanding replaced | -| 3 | Updated `discussion.md` | Round 2-N: feedback, insights, narrative synthesis; TOC + Current Understanding updated each round | -| 4 | `conclusions.json` | Final synthesis with recommendations (incl. steps[] + review_status) | -| 4 | Final `discussion.md` | Complete analysis with conclusions, recommendation review summary, intent coverage matrix | + + +### AskUserQuestion Constraints + +All `AskUserQuestion` calls MUST comply: +- **questions**: 1-4 questions per call +- **options**: 2-4 per question (system auto-adds "Other" for free-text input) +- **header**: max 12 characters +- **label**: 1-5 words per option ### Decision Recording Protocol @@ -38,7 +35,7 @@ When `--yes` or `-y`: Auto-confirm exploration decisions, use recommended analys |---------|---------------|----------------| | **Direction choice** | What chosen, why, alternatives discarded | `#### Decision Log` | | **Key finding** | Content, impact scope, confidence level, hypothesis impact | `#### Key Findings` | -| **Assumption change** | Old → new understanding, reason, impact | `#### Corrected Assumptions` | +| **Assumption change** | Old -> new understanding, reason, impact | `#### Corrected Assumptions` | | **User feedback** | Input, rationale for adoption/adjustment | `#### User Input` | | **Disagreement & trade-off** | Conflicting views, trade-off basis, final choice | `#### Decision Log` | | **Scope adjustment** | Before/after scope, trigger reason | `#### Decision Log` | @@ -63,23 +60,33 @@ When `--yes` or `-y`: Auto-confirm exploration decisions, use recommended analys **Principles**: Immediacy (record as-it-happens), Completeness (context+options+chosen+reason+rejected), Traceability (later phases trace back), Depth (capture reasoning, not just outcomes) -## Implementation +### Output Artifacts -### AskUserQuestion Constraints +| Phase | Artifact | Description | +|-------|----------|-------------| +| 1 | `discussion.md` | Initialized with TOC, Current Understanding block, timeline, metadata | +| 1 | Session variables | Dimensions, focus areas, analysis depth | +| 2 | `exploration-codebase.json` | Single codebase context from cli-explore-agent | +| 2 | `explorations/*.json` | Multi-perspective codebase explorations (parallel, up to 4) | +| 2 | `explorations.json` | Single perspective aggregated findings | +| 2 | `perspectives.json` | Multi-perspective findings (up to 4) with synthesis | +| 2 | Updated `discussion.md` | Round 1 + Initial Intent Coverage Check + Current Understanding replaced | +| 3 | Updated `discussion.md` | Round 2-N: feedback, insights, narrative synthesis; TOC + Current Understanding updated each round | +| 4 | `conclusions.json` | Final synthesis with recommendations (incl. steps[] + review_status) | +| 4 | Final `discussion.md` | Complete analysis with conclusions, recommendation review summary, intent coverage matrix | -All `AskUserQuestion` calls MUST comply: -- **questions**: 1-4 questions per call -- **options**: 2-4 per question (system auto-adds "Other" for free-text input) -- **header**: max 12 characters -- **label**: 1-5 words per option + -### Session Initialization + + + +**Initialize session and create progress tracking.** 1. Extract topic/question from `$ARGUMENTS` 2. Generate session ID: `ANL-{slug}-{date}` (slug: lowercase alphanumeric+Chinese, max 40 chars; date: YYYY-MM-DD UTC+8) 3. Define session folder: `.workflow/.analysis/{session-id}` 4. Parse options: `-c`/`--continue` for continuation, `-y`/`--yes` for auto-approval -5. Auto-detect: If session folder + discussion.md exist → continue mode +5. Auto-detect: If session folder + discussion.md exist -> continue mode 6. Create directory structure 7. **Create Progress Tracking** (TodoWrite — MANDATORY): ``` @@ -95,10 +102,12 @@ All `AskUserQuestion` calls MUST comply: - **`next-step` is a terminal gate** — workflow is NOT complete until this todo is `"completed"` **Session Variables**: `sessionId`, `sessionFolder`, `autoMode` (boolean), `mode` (new|continue) + -### Phase 1: Topic Understanding + +**Phase 1: Parse topic, identify dimensions, and capture user preferences.** -1. **Parse Topic & Identify Dimensions** — Match keywords against Analysis Dimensions table +1. **Parse Topic & Identify Dimensions** — Match keywords against Analysis Dimensions table (see Configuration) 2. **Initial Scoping** (if new session + not auto mode) — use **single AskUserQuestion call with up to 3 questions**: - Q1 **Focus** (multiSelect: true, header: "分析方向"): Top 3-4 directions from Dimension-Direction Mapping (options max 4) - Q2 **Perspectives** (multiSelect: true, header: "分析视角"): Up to 4 from Analysis Perspectives table (options max 4), default: single comprehensive @@ -109,17 +118,21 @@ All `AskUserQuestion` calls MUST comply: - Session metadata, user context, initial questions, empty discussion timeline, initial dimension selection rationale 4. **Record Phase 1 Decisions** — Dimension selection reasoning, depth rationale, any user adjustments -**Success**: Session folder + discussion.md created, dimensions identified, preferences captured, decisions recorded -**TodoWrite**: Update `phase-1` → `"completed"`, `phase-2` → `"in_progress"` +| Condition | Action | +|-----------|--------| +| Session folder + discussion.md created | Continue to Phase 2 | +| User provides no input (timeout) | Save state, show resume command `# (see code: E003)` | -### Phase 2: CLI Exploration +**TodoWrite**: Update `phase-1` -> `"completed"`, `phase-2` -> `"in_progress"` + -Codebase exploration FIRST, then CLI analysis. + +**Phase 2: Codebase exploration FIRST, then CLI analysis.** **Step 1: Codebase Exploration** (cli-explore-agent, parallel up to 6) -- **Single**: General codebase analysis → `{sessionFolder}/exploration-codebase.json` -- **Multi-perspective**: Parallel per-perspective → `{sessionFolder}/explorations/{perspective}.json` +- **Single**: General codebase analysis -> `{sessionFolder}/exploration-codebase.json` +- **Multi-perspective**: Parallel per-perspective -> `{sessionFolder}/explorations/{perspective}.json` - **Common tasks**: `ccw tool exec get_modules_by_depth '{}'`, keyword searches, read `.workflow/project-tech.json` ```javascript @@ -143,15 +156,15 @@ Session: ${sessionFolder} ### Layer 1 — Module Discovery (Breadth) - Search by topic keywords, identify ALL relevant files -- Map module boundaries and entry points → relevant_files[] with annotations +- Map module boundaries and entry points -> relevant_files[] with annotations ### Layer 2 — Structure Tracing (Depth) - Top 3-5 key files: trace call chains 2-3 levels deep -- Identify data flow paths and dependencies → call_chains[], data_flows[] +- Identify data flow paths and dependencies -> call_chains[], data_flows[] ### Layer 3 — Code Anchor Extraction (Detail) - Each key finding: extract code snippet (20-50 lines) with file:line -- Annotate WHY this matters → code_anchors[] +- Annotate WHY this matters -> code_anchors[] ## Output Write to: ${sessionFolder}/exploration-codebase.json @@ -177,7 +190,7 @@ PRIOR EXPLORATION CONTEXT: - Findings: ${explorationResults.key_findings.slice(0,3).join(', ')} - Code anchors: ${(explorationResults.code_anchors || []).slice(0,5).map(a => ` [${a.file}:${a.lines}] ${a.significance}\n \`\`\`\n ${a.snippet}\n \`\`\``).join('\n')} -- Call chains: ${(explorationResults.call_chains || []).slice(0,3).map(c => `${c.entry} → ${c.chain.join(' → ')}`).join('; ')}` +- Call chains: ${(explorationResults.call_chains || []).slice(0,3).map(c => `${c.entry} -> ${c.chain.join(' -> ')}`).join('; ')}` // Single perspective (for multi: loop selectedPerspectives with perspective.purpose/tasks/constraints) Bash({ @@ -188,10 +201,10 @@ Success: Actionable insights with clear reasoning ${explorationContext} TASK: -• Build on exploration findings — reference specific code anchors -• Analyze common patterns and anti-patterns with code evidence -• Highlight potential issues/opportunities with file:line references -• Generate discussion points for user clarification +- Build on exploration findings — reference specific code anchors +- Analyze common patterns and anti-patterns with code evidence +- Highlight potential issues/opportunities with file:line references +- Generate discussion points for user clarification MODE: analysis CONTEXT: @**/* | Topic: ${topic_or_question} @@ -230,10 +243,17 @@ CONSTRAINTS: Focus on ${dimensions.join(', ')} - `synthesis`: {convergent_themes, conflicting_views, unique_contributions} - code_anchors/call_chains include `perspective` field -**Success**: Exploration + CLI artifacts created, discussion.md Round 1, key findings and exploration decisions recorded -**TodoWrite**: Update `phase-2` → `"completed"`, `phase-3` → `"in_progress"` +| Condition | Action | +|-----------|--------| +| Exploration + CLI artifacts created | Continue to Phase 3 | +| cli-explore-agent fails | Continue with available context, note limitation `# (see code: E001)` | +| CLI timeout | Retry with shorter prompt, or skip perspective `# (see code: E002)` | -### Phase 3: Interactive Discussion +**TodoWrite**: Update `phase-2` -> `"completed"`, `phase-3` -> `"in_progress"` + + + +**Phase 3: Interactive discussion loop with evolving understanding.** **Guideline**: Delegate complex tasks to agents (cli-explore-agent) or CLI calls. Avoid direct analysis in main process. @@ -249,26 +269,26 @@ CONSTRAINTS: Focus on ${dimensions.join(', ')} - **继续深入**: Direction correct — deepen automatically or user specifies direction (combines agree+deepen and agree+suggest) - **调整方向**: Different focus or specific questions to address - **补充信息**: User has additional context, constraints, or corrections to provide - - **分析完成**: Sufficient → exit to Phase 4 + - **分析完成**: Sufficient -> exit to Phase 4 4. **Process Response** (always record user choice + impact to discussion.md): - **继续深入** → Sub-question to choose direction (AskUserQuestion, single-select, header: "深入方向"): + **继续深入** -> Sub-question to choose direction (AskUserQuestion, single-select, header: "深入方向"): - Dynamically generate **max 3** context-driven options from: unresolved questions, low-confidence findings, unexplored dimensions, user-highlighted areas - Add **1** heuristic option that breaks current frame (e.g., "compare with best practices", "review from security perspective", "explore simpler alternatives") - Total: **max 4 options**. Each specifies: label, description, tool (cli-explore-agent for code-level / Gemini CLI for pattern-level), scope - **"Other" is auto-provided** by AskUserQuestion — covers user-specified custom direction (no need for separate "suggest next step" option) - - Execute selected direction → merge new code_anchors/call_chains → record confirmed assumptions + deepen angle + - Execute selected direction -> merge new code_anchors/call_chains -> record confirmed assumptions + deepen angle - **调整方向** → AskUserQuestion (header: "新方向", user selects or provides custom via "Other") → new CLI exploration → Record Decision (old vs new direction, reason, impact) + **调整方向** -> AskUserQuestion (header: "新方向", user selects or provides custom via "Other") -> new CLI exploration -> Record Decision (old vs new direction, reason, impact) - **补充信息** → Capture user input, integrate into context, answer questions via CLI/analysis if needed → Record corrections/additions + updated understanding + **补充信息** -> Capture user input, integrate into context, answer questions via CLI/analysis if needed -> Record corrections/additions + updated understanding - **分析完成** → Exit loop → Record why concluding + **分析完成** -> Exit loop -> Record why concluding 5. **Update discussion.md**: - **Append** Round N: user input, direction adjustment, Q&A, corrections, new insights - - **Replace** `## Current Understanding` block with latest consolidated understanding (follow Consolidation Rules: promote confirmed, track corrections, focus on NOW) + - **Replace** `## Current Understanding` block with latest consolidated understanding (follow Consolidation Rules) - **Update** `## Table of Contents` with links to new Round N sections 6. **Round Narrative Synthesis** (append to discussion.md after each round update): @@ -291,12 +311,19 @@ CONSTRAINTS: Focus on ${dimensions.join(', ')} - ⚠️ Intent 3: [implicitly absorbed by X — needs confirmation] - ❌ Intent 4: [not yet discussed] ``` - - If ❌ or ⚠️ items exist → **proactively surface** to user at start of next round: "以下原始意图尚未充分覆盖：[list]。是否需要调整优先级？" + - If ❌ or ⚠️ items exist -> **proactively surface** to user at start of next round: "以下原始意图尚未充分覆盖：[list]。是否需要调整优先级？" -**Success**: All rounds documented with narrative synthesis, assumptions corrected, all decisions recorded with rejection reasoning, direction changes with before/after -**TodoWrite**: Update `phase-3` → `"completed"`, `phase-4` → `"in_progress"` +| Condition | Action | +|-----------|--------| +| User selects "分析完成" | Exit loop, proceed to Phase 4 | +| Max rounds (5) reached | Force synthesis, offer continuation `# (see code: E004)` | +| User timeout | Save state, show resume command `# (see code: E003)` | -### Phase 4: Synthesis & Conclusion +**TodoWrite**: Update `phase-3` -> `"completed"`, `phase-4` -> `"in_progress"` + + + +**Phase 4: Synthesize findings, verify intent coverage, and determine next steps.** 1. **Intent Coverage Verification** (MANDATORY before synthesis): - Check each original intent: ✅ Addressed / 🔀 Transformed / ⚠️ Absorbed / ❌ Missed @@ -305,7 +332,7 @@ CONSTRAINTS: Focus on ${dimensions.join(', ')} | # | Original Intent | Status | Where Addressed | Notes | |---|----------------|--------|-----------------|-------| | 1 | [intent] | ✅ Addressed | Round N, Conclusion #M | | - | 2 | [intent] | 🔀 Transformed | Round N → M | Original: X → Final: Y | + | 2 | [intent] | 🔀 Transformed | Round N -> M | Original: X -> Final: Y | | 3 | [intent] | ❌ Missed | — | Reason | ``` - **Gate**: ❌ Missed items must be either (a) addressed in additional round or (b) confirmed deferred by user @@ -336,11 +363,11 @@ CONSTRAINTS: Focus on ${dimensions.join(', ')} ``` 1. Display all recommendations with numbering (action, rationale, priority, steps[]) - 2. Single AskUserQuestion call — one question per recommendation (max 4, ordered by priority high→medium→low): + 2. Single AskUserQuestion call — one question per recommendation (max 4, ordered by priority high->medium->low): Each question (single-select, header: "建议#N"): - - **确认** (label: "确认", desc: "Accept as-is") → review_status = "accepted" - - **修改** (label: "修改", desc: "Adjust scope/steps") → review_status = "modified" - - **删除** (label: "删除", desc: "Not needed") → review_status = "rejected" + - **确认** (label: "确认", desc: "Accept as-is") -> review_status = "accepted" + - **修改** (label: "修改", desc: "Adjust scope/steps") -> review_status = "modified" + - **删除** (label: "删除", desc: "Not needed") -> review_status = "rejected" 3. If >4 recommendations: batch in groups of 4 with additional AskUserQuestion calls 4. For "修改" selections: follow up to capture modification details 5. Record all review decisions to discussion.md Decision Log @@ -353,7 +380,7 @@ CONSTRAINTS: Focus on ${dimensions.join(', ')} 6. **MANDATORY GATE: Next Step Selection** — workflow MUST NOT end without executing this step. - **TodoWrite**: Update `phase-4` → `"completed"`, `next-step` → `"in_progress"` + **TodoWrite**: Update `phase-4` -> `"completed"`, `next-step` -> `"in_progress"` > **CRITICAL**: This AskUserQuestion is a **terminal gate**. The workflow is INCOMPLETE if this question is not asked. After displaying conclusions (step 4) and recommendation review (step 5), you MUST immediately proceed here. @@ -364,7 +391,7 @@ CONSTRAINTS: Focus on ${dimensions.join(', ')} **Handle user selection**: - **"执行任务"** → MUST invoke Skill tool (do NOT just display a summary and stop): + **"执行任务"** -> MUST invoke Skill tool (do NOT just display a summary and stop): 1. Build `taskDescription` from high/medium priority recommendations (fallback: summary) 2. Assemble context: `## Prior Analysis ({sessionId})` + summary + key files (up to 8) + key findings (up to 5) from exploration-codebase.json 3. **Invoke Skill tool immediately**: @@ -374,15 +401,15 @@ CONSTRAINTS: Focus on ${dimensions.join(', ')} If Skill invocation is omitted, the workflow is BROKEN. 4. After Skill invocation, analyze-with-file is complete — do not output any additional content - **"产出Issue"** → Convert recommendations to issues: + **"产出Issue"** -> Convert recommendations to issues: 1. For each recommendation in conclusions.recommendations (priority high/medium): - Build issue JSON: `{title, context: rec.action + rec.rationale, priority: rec.priority == 'high' ? 2 : 3, source: 'discovery', labels: dimensions}` - Create via pipe: `echo '' | ccw issue create` 2. Display created issue IDs with next step hint: `/issue:plan ` - **"完成"** → No further action needed. + **"完成"** -> No further action needed. - **TodoWrite**: Update `next-step` → `"completed"` after user selection is handled + **TodoWrite**: Update `next-step` -> `"completed"` after user selection is handled **conclusions.json Schema**: - `session_id`, `topic`, `completed`, `total_rounds`, `summary` @@ -393,10 +420,43 @@ CONSTRAINTS: Focus on ${dimensions.join(', ')} - `decision_trail[]`: {round, decision, context, options_considered, chosen, rejected_reasons, reason, impact} - `narrative_trail[]`: {round, starting_point, key_progress, hypothesis_impact, updated_understanding, remaining_questions} - `intent_coverage[]`: {intent, status, where_addressed, notes} + -**Success**: conclusions.json created, discussion.md finalized, Intent Coverage Matrix verified, complete decision trail documented, `next-step` gate completed + -## Configuration + + +| Code | Severity | Description | Stage | +|------|----------|-------------|-------| +| E001 | error | cli-explore-agent fails — continue with available context, note limitation | cli_exploration | +| E002 | error | CLI timeout — retry with shorter prompt, or skip perspective | cli_exploration | +| E003 | error | User timeout — save state, show resume command | topic_understanding, interactive_discussion | +| E004 | warning | Max discussion rounds (5) reached — force synthesis, offer continuation | interactive_discussion | +| E005 | error | No relevant findings from exploration — broaden search, ask user for clarification | cli_exploration | +| E006 | warning | Session folder conflict — append timestamp suffix | session_init | +| E007 | error | Gemini unavailable — fallback to Codex or manual analysis | cli_exploration | + + + + +- [ ] Session folder created with valid session ID +- [ ] Progress tracking (TodoWrite) initialized with all 5 items +- [ ] Dimensions identified and user preferences captured (Phase 1) +- [ ] discussion.md initialized with TOC, Current Understanding, metadata +- [ ] Codebase exploration completed with code_anchors and call_chains (Phase 2) +- [ ] CLI analysis executed and findings aggregated +- [ ] Initial Intent Coverage Check appended to discussion.md +- [ ] Interactive discussion rounds documented with narrative synthesis (Phase 3) +- [ ] Intent Drift Check performed each round >= 2 +- [ ] All decisions recorded per Decision Recording Protocol +- [ ] Intent Coverage Matrix verified in Phase 4 +- [ ] conclusions.json created with key_conclusions, recommendations, decision_trail +- [ ] discussion.md finalized with conclusions, Decision Trail, session statistics +- [ ] Recommendation review completed (non-auto mode) +- [ ] Next Step terminal gate executed — `next-step` todo is `"completed"` + + + ### Analysis Perspectives @@ -440,22 +500,12 @@ Present 2-3 top directions per dimension, allow multi-select + custom. | Rule | Description | |------|-------------| | Promote confirmed insights | Move validated findings to "What We Established" | -| Track corrections | Keep important wrong→right transformations | +| Track corrections | Keep important wrong->right transformations | | Focus on current state | What do we know NOW | | Avoid timeline repetition | Don't copy discussion details | | Preserve key learnings | Keep insights valuable for future reference | -## Error Handling - -| Error | Resolution | -|-------|------------| -| cli-explore-agent fails | Continue with available context, note limitation | -| CLI timeout | Retry with shorter prompt, or skip perspective | -| User timeout | Save state, show resume command | -| Max rounds reached | Force synthesis, offer continuation | -| No relevant findings | Broaden search, ask user for clarification | -| Session folder conflict | Append timestamp suffix | -| Gemini unavailable | Fallback to Codex or manual analysis | + > **Lite-plan handoff**: Phase 4「执行任务」assembles analysis context as inline `## Prior Analysis` block, allowing lite-plan to skip redundant exploration. diff --git a/.claude/skills/command-generator/SKILL.md b/.claude/skills/command-generator/SKILL.md deleted file mode 100644 index 28e084f7..00000000 --- a/.claude/skills/command-generator/SKILL.md +++ /dev/null @@ -1,307 +0,0 @@ ---- -name: command-generator -description: Command file generator - 5 phase workflow for creating Claude Code command files with YAML frontmatter. Generates .md command files for project or user scope. Triggers on "create command", "new command", "command generator". -allowed-tools: Read, Write, Edit, Bash, Glob, AskUserQuestion ---- - - -Generate Claude Code command .md files with concrete, domain-specific content in GSD style. Produces command files at project-level (`.claude/commands/`) or user-level (`~/.claude/commands/`) with YAML frontmatter, XML semantic tags (``, ``, ``, ``, ``), and actionable execution logic — NOT empty placeholders. - -Invoked when user requests "create command", "new command", or "command generator". - - - -- @.claude/skills/command-generator/specs/command-design-spec.md -- @.claude/skills/command-generator/templates/command-md.md - - - - - -**Parse and validate all input parameters.** - -Extract from `$ARGUMENTS` or skill args: - -| Parameter | Required | Validation | Example | -|-----------|----------|------------|---------| -| `$SKILL_NAME` | Yes | `/^[a-z][a-z0-9-]*$/`, min 1 char | `deploy`, `create` | -| `$DESCRIPTION` | Yes | min 10 chars | `"Deploy application to production"` | -| `$LOCATION` | Yes | `"project"` or `"user"` | `project` | -| `$GROUP` | No | `/^[a-z][a-z0-9-]*$/` or null | `issue`, `workflow` | -| `$ARGUMENT_HINT` | No | any string or empty | `" [--priority 1-5]"` | - -**Validation rules:** -- Missing required param → Error with specific message (e.g., `"skillName is required"`) -- Invalid `$SKILL_NAME` pattern → Error: `"skillName must be lowercase alphanumeric with hyphens, starting with a letter"` -- Invalid `$LOCATION` → Error: `"location must be 'project' or 'user'"` -- Invalid `$GROUP` pattern → Warning, continue - -**Normalize:** trim + lowercase for `$SKILL_NAME`, `$LOCATION`, `$GROUP`. - - - -**Resolve target file path based on location and group.** - -Path mapping: - -| Location | Base Directory | -|----------|---------------| -| `project` | `.claude/commands` | -| `user` | `~/.claude/commands` (expand `~` to `$HOME`) | - -Path construction: - -``` -If $GROUP: - $TARGET_DIR = {base}/{$GROUP} - $TARGET_PATH = {base}/{$GROUP}/{$SKILL_NAME}.md -Else: - $TARGET_DIR = {base} - $TARGET_PATH = {base}/{$SKILL_NAME}.md -``` - -Check if `$TARGET_PATH` already exists → store as `$FILE_EXISTS` (true/false). - - - -**Gather domain-specific requirements to generate concrete content.** - -Infer the command's domain from `$SKILL_NAME`, `$DESCRIPTION`, and `$ARGUMENT_HINT`: - -| Signal | Extract | -|--------|---------| -| `$SKILL_NAME` | Action verb (deploy, create, analyze, sync) → step naming | -| `$DESCRIPTION` | Domain keywords → execution logic, error scenarios | -| `$ARGUMENT_HINT` | Flags/args → parse_input step details, validation rules | -| `$GROUP` | Command family → related commands, shared patterns | - -**Determine command complexity:** - -| Complexity | Criteria | Steps to Generate | -|------------|----------|-------------------| -| Simple | Single action, no flags | 2-3 steps | -| Standard | 1-2 flags, clear workflow | 3-4 steps | -| Complex | Multiple flags, multi-phase | 4-6 steps | - -**If complexity is unclear**, ask user: - -``` -AskUserQuestion( - header: "Command Scope", - question: "What are the main execution steps for this command?", - options: [ - { label: "Simple", description: "Single action: validate → execute → report" }, - { label: "Standard", description: "Multi-step: parse → process → verify → report" }, - { label: "Complex", description: "Full workflow: parse → explore → execute → verify → report" }, - { label: "I'll describe", description: "Let me specify the steps" } - ] -) -``` - -Store as `$COMMAND_STEPS`, `$ERROR_SCENARIOS`, `$SUCCESS_CONDITIONS`. - - - -**Generate concrete, domain-specific command content in GSD style.** - -This is the core generation step. Draft the COMPLETE command file — not a template with placeholders — using the gathered requirements. - -**YAML Frontmatter:** -```yaml ---- -name: $SKILL_NAME -description: $DESCRIPTION -argument-hint: $ARGUMENT_HINT # only if provided ---- -``` - -**`` section:** Write 2-3 sentences describing: -- What the command does (action + target) -- When it's invoked (trigger conditions) -- What it produces (output artifacts or effects) - -**`` section:** Infer from domain: -- If command reads config → `@.claude/CLAUDE.md` or relevant config files -- If command modifies code → relevant source directories -- If command is part of a group → other commands in the same group - -**`` section with `` blocks:** - -For each step in `$COMMAND_STEPS`, generate a `` block containing: - -1. **`parse_input`** (always first, `priority="first"`): - - Parse `$ARGUMENTS` for flags and positional args derived from `$ARGUMENT_HINT` - - Include specific flag detection logic (e.g., `if arguments contain "--env"`) - - Include validation with specific error messages - - Include decision routing table if multiple modes exist - -2. **Domain-specific execution steps** (2-4 steps): - - Each step has a **bold action description** - - Include concrete shell commands, file operations, or tool calls - - Use `$UPPER_CASE` variables for user input, `${computed}` for derived values - - Include conditional logic with specific conditions (not generic) - - Reference actual file paths and tool names - -3. **`report`** (always last): - - Format output with banner and status - - Include file paths, timestamps, next step suggestions - -**Shell Correctness Checklist (MANDATORY for every shell block):** - -| Rule | Wrong | Correct | -|------|-------|---------| -| Multi-line output | `echo "{ ... }"` (unquoted multi-line) | `cat <<'EOF' > file`...`EOF` (heredoc) | -| Variable init | Use `$VAR` after conditional | `VAR="default"` BEFORE any conditional that sets it | -| Error exit | `echo "Error: ..."` (no exit) | `echo "Error: ..." # (see code: E00X)` + `exit 1` | -| Quoting | `$VAR` in commands | `"$VAR"` (double-quoted in all expansions) | -| Exit on fail | Command chain without checks | `set -e` or explicit `|| { echo "Failed"; exit 1; }` | -| Command from var | `$CMD --flag` (word-split fragile) | `eval "$CMD" --flag` or use array: `cmd=(...); "${cmd[@]}"` | -| Prerequisites | Implicit `git`/`curl` usage | Declare in `` section | - -**Golden Example — a correctly-written execution step:** - -```markdown - -**Execute deployment to target environment.** - -$DEPLOY_STATUS="pending" # Initialize before conditional - -```bash -# Save current state for rollback -cp .deploy/latest.json .deploy/previous.json 2>/dev/null || true - -# Write deployment manifest via heredoc -cat < .deploy/latest.json -{ - "env": "$ENV", - "tag": "$DEPLOY_TAG", - "timestamp": "$(date -u +%Y-%m-%dT%H:%M:%SZ)", - "commit": "$(git rev-parse --short HEAD)", - "status": "deploying" -} -EOF - -# Execute deployment -if ! deploy_cmd --env "$ENV" --tag "$DEPLOY_TAG" 2>&1 | tee .deploy/latest.log; then - echo "Error: Deployment to $ENV failed" # (see code: E004) - exit 1 -fi - -$DEPLOY_STATUS="success" -``` - -| Condition | Action | -|-----------|--------| -| Deploy succeeds | Update status → `"deployed"`, continue to verify | -| Deploy fails | Log error `# (see code: E004)`, exit 1 | -| `$ROLLBACK_MODE` | Load `.deploy/previous.json`, redeploy prior version | - -``` - -**Optional `` section** (include when command uses external tools): - -```markdown - -- git (2.20+) — version control operations -- curl — health check endpoints -- jq — JSON processing (optional) - -``` - -**`` table:** Generate 3-6 specific error codes: -- Derive from `$ARGUMENT_HINT` validation failures (E001-E003) -- Derive from domain-specific failure modes (E004+) -- Include 1-2 warnings (W001+) -- Each code has: Code, Severity, Description, **Stage** (which step triggers it) -- **Cross-reference rule**: Every `# (see code: E00X)` comment in `` MUST have a matching row in ``, and every error code row MUST be referenced by at least one inline comment - -**`` checkboxes:** Generate 4-8 verifiable conditions: -- Input validation passed -- Each execution step completed its action -- Output artifacts exist / effects applied -- Report displayed - -**Quality rules for generated content:** -- NO bracket placeholders (`[Describe...]`, `[List...]`) — all content must be concrete -- Steps must contain actionable logic, not descriptions of what to do -- Error codes must reference specific failure conditions from this command's domain -- Success criteria must be verifiable (not "command works correctly") -- Every shell block must pass the Shell Correctness Checklist above -- Follow patterns from @.claude/skills/command-generator/templates/command-md.md for structural reference only - - - -**Write generated content to target path.** - -**If `$FILE_EXISTS`:** Warn: `"Command file already exists at {path}. Will overwrite."` - -```bash -mkdir -p "$TARGET_DIR" -``` - -Write the drafted content to `$TARGET_PATH` using Write tool. - -**Verify:** Read back the file and confirm: -- File exists and is non-empty -- Contains `` tag with concrete content (no placeholders) -- Contains at least 2 `` with at least 3 rows including Stage column -- Contains `` with at least 4 checkboxes -- No unresolved `{{...}}` or `[...]` placeholders remain -- Every `# (see code: E0XX)` has a matching `` row (cross-ref check) -- Every shell block uses heredoc for multi-line output (no bare multi-line echo) -- All state variables initialized before conditional use -- All error paths include `exit 1` after error message - -**If verification fails:** Fix the content in-place using Edit tool. - -**Report completion:** - -``` -Command generated successfully! - -File: {$TARGET_PATH} -Name: {$SKILL_NAME} -Description: {$DESCRIPTION} -Location: {$LOCATION} -Group: {$GROUP or "(none)"} -Steps: {number of blocks generated} -Error codes: {number of error codes} - -Next Steps: -1. Review and customize {$TARGET_PATH} -2. Test: /{$GROUP}:{$SKILL_NAME} or /{$SKILL_NAME} -``` - - - - - - -| Code | Severity | Description | Stage | -|------|----------|-------------|-------| -| E001 | error | skillName is required | validate_params | -| E002 | error | description is required (min 10 chars) | validate_params | -| E003 | error | location is required ("project" or "user") | validate_params | -| E004 | error | skillName must be lowercase alphanumeric with hyphens | validate_params | -| E005 | error | Failed to infer command domain from description | gather_requirements | -| E006 | error | Failed to write command file | write_file | -| E007 | error | Generated content contains unresolved placeholders | write_file | -| W001 | warning | group must be lowercase alphanumeric with hyphens | validate_params | -| W002 | warning | Command file already exists, will overwrite | write_file | -| W003 | warning | Could not infer required_reading, using defaults | draft_content | - - - - -- [ ] All required parameters validated ($SKILL_NAME, $DESCRIPTION, $LOCATION) -- [ ] Target path resolved with correct scope (project vs user) and group -- [ ] Command domain inferred from description and argument hint -- [ ] Concrete `` drafted (no placeholders) -- [ ] 2-6 `` blocks generated with domain-specific logic -- [ ] `` table generated with 3+ specific codes -- [ ] `` generated with 4+ verifiable checkboxes -- [ ] File written to $TARGET_PATH and verified -- [ ] Zero bracket placeholders in final output -- [ ] Completion report displayed - diff --git a/.claude/skills/command-generator/specs/command-design-spec.md b/.claude/skills/command-generator/specs/command-design-spec.md deleted file mode 100644 index c7966599..00000000 --- a/.claude/skills/command-generator/specs/command-design-spec.md +++ /dev/null @@ -1,65 +0,0 @@ -# Command Design Specification - -Guidelines for Claude Code command files generated by command-generator. - -## 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 ---- -``` - -## Naming Conventions - -| Element | Convention | Examples | -|---------|-----------|----------| -| Command name | lowercase, hyphens, 2-3 words max | `deploy`, `create-issue` | -| Group name | singular noun | `issue`, `session`, `workflow` | -| Verbs for actions | imperative | `deploy`, `create`, `analyze` | - -## 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 (GSD Style) - -Generated commands should use XML semantic tags: - -| Tag | Required | Purpose | -|-----|----------|---------| -| `` | Yes | What the command does, when invoked, what it produces | -| `` | Yes | Files to read before execution (@ notation) | -| `` | Yes | Container for execution steps | -| `` | Yes | Individual execution steps with snake_case names | -| `` | No | Error code table with severity and description | -| `` | Yes | Checkbox list of verifiable completion conditions | - -## Step Naming - -- Use snake_case: `parse_input`, `validate_config`, `write_output` -- Use action verbs: `discover`, `validate`, `spawn`, `collect`, `report` -- First step gets `priority="first"` attribute - -## Error Messages - -``` -Good: Error: GitHub issue URL required - Usage: /issue:create - -Bad: Error: Invalid input -``` - -## Scope Guidelines - -| Scope | Location | Use For | -|-------|----------|---------| -| Project | `.claude/commands/` | Team workflows, project integrations | -| User | `~/.claude/commands/` | Personal tools, cross-project utilities | diff --git a/.claude/skills/command-generator/templates/command-md.md b/.claude/skills/command-generator/templates/command-md.md deleted file mode 100644 index 1b543237..00000000 --- a/.claude/skills/command-generator/templates/command-md.md +++ /dev/null @@ -1,112 +0,0 @@ -# Command Template — Structural Reference - -This template defines the **structural pattern** for generated commands. The `draft_content` step uses this as a guide to generate concrete, domain-specific content — NOT as a literal copy target. - -## Required Structure - -```markdown ---- -name: {$SKILL_NAME} -description: {$DESCRIPTION} -argument-hint: {$ARGUMENT_HINT} # omit line if empty ---- - - -{2-3 concrete sentences: what it does + when invoked + what it produces} - - - -{@ references to files this command needs before execution} - - - -- {tool} ({version}+) — {what it's used for} - - - - - -**Parse arguments and validate input.** - -Parse `$ARGUMENTS` for: -- {specific flags from $ARGUMENT_HINT} -- {positional args} - -{Decision routing table if multiple modes:} -| Condition | Action | -|-----------|--------| -| flag present | set variable | -| missing required | Error: "message" `# (see code: E001)` + `exit 1` | - - - - -**{Concrete action description.}** - -$STATE_VAR="default" - -```bash -# Use heredoc for multi-line output -cat < output-file -{structured content with $VARIABLES} -EOF - -# Every error path: message + code ref + exit -if [ ! -f "$REQUIRED_FILE" ]; then - echo "Error: Required file missing" # (see code: E003) - exit 1 -fi -``` - -| Condition | Action | -|-----------|--------| -| success | Continue to next step | -| failure | Error `# (see code: E0XX)`, exit 1 | - - - -**Format and display results.** - -{Banner with status, file paths, next steps} - - - - - - -| Code | Severity | Description | Stage | -|------|----------|-------------|-------| -| E001 | error | {specific to parse_input validation} | parse_input | -| E002 | error | {specific to domain action failure} | {step_name} | -| W001 | warning | {specific recoverable condition} | {step_name} | - - - - - -- [ ] {Input validated} -- [ ] {Domain action 1 completed} -- [ ] {Domain action 2 completed} -- [ ] {Output produced / effect applied} - -``` - -## Content Quality Rules - -| Rule | Bad Example | Good Example | -|------|-------------|--------------| -| No bracket placeholders | `[Describe purpose]` | `Deploy to target environment with rollback on failure.` | -| Concrete step names | `execute` | `run_deployment`, `validate_config` | -| Specific error codes | `E001: Invalid input` | `E001: --env must be "prod" or "staging"` | -| Verifiable criteria | `Command works` | `Deployment log written to .deploy/latest.log` | -| Real shell commands | `# TODO: implement` | `kubectl apply -f $MANIFEST_PATH` | - -## Step Naming Conventions - -| Domain | Typical Steps | -|--------|--------------| -| Deploy/Release | `validate_config`, `run_deployment`, `verify_health`, `report` | -| CRUD operations | `parse_input`, `validate_entity`, `persist_changes`, `report` | -| Analysis/Review | `parse_input`, `gather_context`, `run_analysis`, `present_findings` | -| Sync/Migration | `parse_input`, `detect_changes`, `apply_sync`, `verify_state` | -| Build/Generate | `parse_input`, `resolve_dependencies`, `run_build`, `write_output` | diff --git a/.claude/skills/prompt-generator/SKILL.md b/.claude/skills/prompt-generator/SKILL.md new file mode 100644 index 00000000..2818bcd0 --- /dev/null +++ b/.claude/skills/prompt-generator/SKILL.md @@ -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 +--- + + +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". + + + +- @.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 + + + + +## 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 | `" [--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 | `` + 1-2 domain sections | +| Standard | Multi-aspect domain | `` + 2-4 domain sections | +| Expert | Deep domain with rules | `` + 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. **``** — 2-3 sentences: what + when + what it produces +2. **``** — @ references to context files +3. **``** — 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 + `` with next actions +4. **``** — 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 ``, ``, `` blocks +- Include `` 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 `` 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. **``** — identity + spawned-by + core responsibilities + mandatory initial read +3. **Domain sections** (2-6 based on scope): + - `` — guiding principles, anti-patterns + - `` — how to honor upstream decisions + - `` / `` — concrete output rules with examples + - `` — self-check criteria before returning + - Custom domain sections as needed +4. **Output contract** — structured return markers to orchestrator + +**Agent writing rules:** +- `` 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 ``, ``, numbered `## N.` steps | command | +| Contains ``, `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 ``, ``) 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 | +|-------|---------------| +| `` | 2-3 sentences, no placeholders | +| `` 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 `` | +| Agent spawning (if complex) | `Task(` call with `subagent_type` | +| Agent prompt structure | `` + `` or `` blocks | +| Return handling | Routes on `## TASK COMPLETE` / `## TASK BLOCKED` markers | +| `` | Banner + summary + next command suggestion | +| `` | 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 | +| `` is first section | Appears before any domain section | +| `` has spawned-by | States which command spawns it | +| `` has mandatory read | `` instruction present | +| `` has responsibilities | 3+ bullet points with verb phrases | +| Domain sections named | After domain concepts, not generic (``, ``) | +| Examples present | Each domain section has 1+ comparison table or decision table | +| `` | Defines return markers (COMPLETE/BLOCKED/CHECKPOINT) | +| `` | 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}" + +─────────────────────────────────────────────────────── +``` + + + + +- [ ] 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 + diff --git a/.claude/skills/prompt-generator/specs/agent-design-spec.md b/.claude/skills/prompt-generator/specs/agent-design-spec.md new file mode 100644 index 00000000..3d336b7c --- /dev/null +++ b/.claude/skills/prompt-generator/specs/agent-design-spec.md @@ -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 (``) | 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. `` 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 | +|---------|---------|-----------------| +| `` | Identity, spawner, responsibilities | **Always** | +| `` | How to discover project conventions | Agent reads project files | +| `` | Guiding principles, anti-patterns | Agent has opinionated approach | +| `` | Honor upstream decisions (locked/deferred/discretion) | Agent receives user decisions | +| `` | What the agent receives and how to use it | Agent has structured input | +| `` | Research depth protocol (L0-L3) | Agent does research | +| `` | Task anatomy, sizing, ordering | Agent produces tasks | +| `` | How to build dependency graphs | Agent manages dependencies | +| `` | Exact output structure with templates | Agent produces structured output | +| `` | Central verification or design principle | Agent has one key insight | +| `` | Return markers to orchestrator | **Always** | +| `` | Self-check before returning | **Always** | + +### Section Ordering Convention + +``` + ← Identity (always first) + ← How to orient in the project + ← Guiding beliefs + ← What agent receives + ← How to honor decisions + ← Key insight +... domain sections ← Expertise (2-6 sections) + ← Return protocol + ← Self-check (always last content section) +``` + +## Section Writing Rules + +### `` — Identity (ALWAYS FIRST) + +Pattern from `gsd-planner.md` and `gsd-plan-checker.md`: + +```markdown + +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 `` 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 + +``` + +### `` — Project Discovery + +Pattern from `gsd-planner.md`: + +```markdown + +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 + +``` + +### `` — Guiding Principles + +Pattern from `gsd-planner.md`: + +```markdown + +## {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} + +``` + +### `` — Structured Input Handling + +Pattern from `gsd-plan-checker.md`: + +```markdown + +**{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. | + +``` + +### `` — Decision Honoring + +Pattern from `gsd-planner.md`: + +```markdown + +## 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)" + +``` + +### 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 ``:** + +```markdown + +## Task Anatomy + +Every task has four required fields: + +**:** Exact paths. +- Good: `src/app/api/auth/login/route.ts` +- Bad: "the auth files" + +**:** 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? + +``` + +### `` — Return Protocol + +```markdown + +## 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} +``` + +``` + +### `` — Self-Check (ALWAYS LAST) + +```markdown + +Before returning, verify: +- [ ] {Check 1 — concrete, grep-verifiable} +- [ ] {Check 2 — concrete, counts/exists} +- [ ] {Check 3 — concrete, structural} +- [ ] {Check 4 — no prohibited content} + +``` + +## 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 | +| `` is not first section | Identity must be established first | Always lead with `` | +| 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 | diff --git a/.claude/skills/prompt-generator/specs/command-design-spec.md b/.claude/skills/prompt-generator/specs/command-design-spec.md new file mode 100644 index 00000000..abe9e55a --- /dev/null +++ b/.claude/skills/prompt-generator/specs/command-design-spec.md @@ -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 ``: + +| Tag | Required | Purpose | +|-----|----------|---------| +| `` | Yes | What + when + what it produces (2-3 sentences) | +| `` | Yes | @ file references loaded before execution | +| `` | Yes | Steps — numbered or named (see Step Styles below) | +| `` | Optional | Behavior when `--auto` flag present | +| `` | Recommended | Formatted completion status + next actions | +| `` | 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 + + +## 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. + + +``` + +### Style B: Named `` 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 + + + +Load context, parse arguments. + + + +Check preconditions. + + + +Construct prompt, spawn agent. + + + +Display results. + + + +``` + +### Which style to use? + +| Criteria | Numbered | Named `` | +|----------|----------|----------------| +| 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 + +What to accomplish — specific and measurable. + + + +- {path1} (description — what this file provides) +- {path2} (description) + + + +**Phase:** {number} +**Mode:** {standard | revision | gap_closure} +Extra info the agent needs. + + + +Write to: {output_path} + +``` + +### 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 ``: + +```markdown + +## 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 + +``` + +## offer_next Pattern + +```markdown + +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + SKILL ► TASK COMPLETE +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +**{Summary line}** + +| Key | Value | +|-----|-------| +| ... | ... | + +Status: {metric 1} | {metric 2} + +─────────────────────────────────────────────────────── + +## Next Up + +**{Primary next action}** + +/{next-command} {args} + +/clear first — fresh context window + +─────────────────────────────────────────────────────── + +**Also available:** +- /{alt-1} — description +- /{alt-2} — description + +─────────────────────────────────────────────────────── + +``` + +## 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 `` | +| 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 | diff --git a/.claude/skills/prompt-generator/specs/conversion-spec.md b/.claude/skills/prompt-generator/specs/conversion-spec.md new file mode 100644 index 00000000..39e4ef42 --- /dev/null +++ b/.claude/skills/prompt-generator/specs/conversion-spec.md @@ -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 | `` + `` with numbered `## N.` steps | +| `## Implementation` + `### Phase N` | `` with numbered steps, content preserved | +| `## Overview` / `## Core Principle` | `` (merge into 2-3 sentences) + keep details in steps | +| `## Usage` with examples | Keep as-is inside `` step 1 or before `` | +| `## Auto Mode` / `## Auto Mode Defaults` | `` 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 +## Process / ## Implementation → content moves to +## Success Criteria → content moves to +## Error Codes → preserve as-is (optional section) +``` + +**Everything else**: Wrap in appropriate GSD tag or keep as custom section inside ``. + +### What to ADD (with TODO markers) + +| Missing Element | Add | +|----------------|-----| +| `` | Extract from overview/description, mark `` if uncertain | +| `` | Generate from existing content, mark `` | +| `` | Add skeleton with `` | +| Banners | Add before major transitions if missing | + +## Agent Conversion Rules + +### Source Pattern → Target Pattern + +| Source Style | Target Style | +|-------------|-------------| +| Plain prose role description | `` with structured format | +| `## Core Philosophy` / `## Principles` | `` | +| `## Execution Process` / `## How to` | Domain section with descriptive name | +| `## Quality Gates` / `## Standards` | `` with checkbox format | +| Flat numbered list of responsibilities | `` 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. **`` MUST be first** — gather identity content from wherever it appears +2. **Add "Spawned by:"** if missing — infer from description or mark `` +3. **Add "Mandatory Initial Read"** block if missing +4. **Rename generic sections**: `` → descriptive name based on content +5. **Add ``** if missing — with TODO marker +6. **Add ``** 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 | diff --git a/.claude/skills/prompt-generator/templates/agent-md.md b/.claude/skills/prompt-generator/templates/agent-md.md new file mode 100644 index 00000000..2a677235 --- /dev/null +++ b/.claude/skills/prompt-generator/templates/agent-md.md @@ -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 +--- + + +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 `` 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 + + + +## {Guiding Principle Name} + +{Core beliefs — 3-5 bullet points} + +**Anti-patterns (delete if seen):** +- {Anti-pattern 1} +- {Anti-pattern 2} + + +<{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_2}> +## {Another Domain Concept} + +{Format templates, structural rules, required fields.} + +Every {output unit} has {N} required fields: +- **:** {What it contains, why it matters} +- **:** {What it contains, why it matters} + + + +## 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} +``` + + + +Before returning, verify: +- [ ] {Check 1 — concrete, verifiable} +- [ ] {Check 2 — concrete, verifiable} +- [ ] {Check 3 — concrete, verifiable} +- [ ] {Check 4 — concrete, verifiable} + +``` + +## Section Design Guidelines + +### Section Naming + +Name sections after the domain concept they cover: + +| Good | Bad | +|------|-----| +| `` | `` | +| `` | `` | +| `` | `` | +| `` | `` | + +### 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 | diff --git a/.claude/skills/prompt-generator/templates/command-md.md b/.claude/skills/prompt-generator/templates/command-md.md new file mode 100644 index 00000000..400a20fd --- /dev/null +++ b/.claude/skills/prompt-generator/templates/command-md.md @@ -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 +--- + + +{2-3 sentences: what it does + when invoked + what it produces} + + + +{@ references to files needed before execution} + + + + +## 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 , , 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 .} + + + + +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + 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 + + + +- [ ] {Precondition validated} +- [ ] {Core action completed} +- [ ] {Agent spawned and returned (if applicable)} +- [ ] {Output artifact produced / effect applied} +- [ ] {Status displayed to user} + +``` + +## 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` |