claude-dev-env 1.34.1 → 1.36.0

package/skills/pr-converge/workflows/ahk-auto-continue-loop.md

@@ -0,0 +1,108 @@
+# AHK auto-continue loop pacing (pr-converge)
+
+Load this document when **`ScheduleWakeup` is not available** in this session (orchestrated teams disabled, restricted tool registry, Cursor
+  without that primitive, or the user wants a visibly-running pacer). Follow it for **every** instruction below that depends on that choice.
+  Shared bugbot / bugteam / Fix protocol steps stay in the main `SKILL.md`.
+
+## Session behavior
+
+Keep ticks in the **same** window the auto-typer targets so each `continue` re-enters here and reads the same state line and `gh` context.
+
+## Why this path exists
+
+It is not a separate "mode" the user must remember — bare `/pr-converge` already implies loop-until-done; when the primary wakeup tool is
+  missing, fall through to AHK automatically. The per-tick work is unchanged; what changes is who fires the next tick. Instead of
+  `ScheduleWakeup` re-entering the skill, an external AutoHotkey utility auto-types `continue` into the active Claude Code window every 5
+  minutes, and the model treats each `continue` as the next tick trigger.
+
+**AHK is loop pacing only:** every `phase == BUGTEAM` tick still runs **`/bugteam`** via the bugteam skill per Step 2 of the main skill —
+  nothing here replaces that audit.
+
+**Fix protocol** commits use **`Task`** with **`subagent_type: "generalPurpose"`** and the **clean-coder preamble** from the main
+  [`SKILL.md` Fix protocol](../SKILL.md#fix-protocol) section (same as ScheduleWakeup pacing — Cursor has no `clean-coder` `subagent_type`).
+
+Ensure `~/.claude/agents/clean-coder.md` exists (Windows: `%USERPROFILE%\.claude\agents\clean-coder.md`). Optionally also copy it to
+  `.cursor/agents/clean-coder.md` in the repo when you want the file co-located with the checkout; the spawn **prompt** must still name the
+  absolute path the subagent should **Read** first.
+
+### One-time setup at the start of the loop
+
+The skill bundles its driver scripts under `scripts/` and resolves them at runtime via `$HOME\.claude\skills\pr-converge\scripts\…` (the same
+  convention `/logifix` uses). The bundled `.cmd` launchers locate their siblings via `%~dp0`, so they need no path arguments — only the AHK
+  target PID.
+
+Run these two commands in order (PowerShell-friendly Bash escaping):
+
+1. Resolve the PID of the GUI ancestor that hosts this Claude Code session:
+   ```bash
+   pwsh -NoProfile -ExecutionPolicy Bypass -File "$HOME\.claude\skills\pr-converge\scripts\caller-window-pid.ps1"
+   ```
+   Capture the printed integer as `caller_pid`. Verify it points at the right window before continuing:
+   ```bash
+   pwsh -NoProfile -Command "Get-Process -Id $caller_pid | Select-Object Id,ProcessName,MainWindowTitle"
+   ```
+2. Launch the auto-typer attached to that PID with auto-start enabled. The bundled launcher accepts the PID as its first arg and the
+  `--start-on` flag is forwarded to the AHK script:
+   ```bash
+   "$HOME\.claude\skills\pr-converge\scripts\cursor-agents-continue.cmd" $caller_pid --start-on
+   ```
+   AutoHotkey v2 must be installed at `C:\Program Files\AutoHotkey\v2\AutoHotkey64.exe`.
+
+### Per-tick behavior under this driver
+
+- Run Steps 1–3 of **Per-tick work** in the main `SKILL.md` exactly as written.
+- In **Step 4**, do **not** call `ScheduleWakeup` — the auto-typer is the pacer (this is the fallback branch of Step 4 in the main skill).
+- End every assistant response with the literal sentence `Awaiting next "continue" tick.` so the next iteration is unambiguously identifiable
+  in the transcript.
+- When the next user message is `continue` (auto-typed by AHK) or any close paraphrase, treat it as the next tick of default-loop
+  `/pr-converge` and re-enter from Step 1 against the freshest PR state.
+
+### Convergence cleanup
+
+On back-to-back clean (the existing convergence rule in the main skill), run `gh pr ready`, then kill the auto-typer when this session used
+  this AHK pacing path:
+
+```bash
+pwsh -NoProfile -Command "Get-CimInstance Win32_Process -Filter \"Name='AutoHotkey64.exe'\" | Where-Object CommandLine -like '*cursor-agents-continue.ahk*' | ForEach-Object { Stop-Process -Id $_.ProcessId -Force }"
+```
+
+Report convergence in the same one-sentence shape as the standard flow, plus a second sentence noting the auto-typer was stopped. The skill
+  returns; no next tick fires.
+
+### Gotchas
+
+- **Resolver fallback semantics matter.** `caller-window-pid.ps1` walks up the parent process chain, terminates at `explorer.exe`, and falls
+  back to the foreground window when no GUI ancestor is found. Always verify `MainWindowTitle` after capture — if it isn't the Claude Code
+  session, the auto-typer will fire `continue` into the wrong window and the loop stalls silently.
+- **Tick-duration vs. 5-minute cadence.** The auto-typer fires every 5 minutes regardless of model activity. A tick that runs longer than 5
+  minutes will receive a queued `continue` while still in flight; Claude Code processes these sequentially, so there's no corruption, but the
+  loop pace becomes irregular. Don't try to "fix" this by shortening the AHK interval — the `bugbot run` cadence already has its own pacing
+  baked into the standard flow.
+- **AHK runs as `#SingleInstance Force`.** Re-running the launcher replaces the prior instance silently. Safe to re-issue if the loop appears
+  stalled.
+- **`Stop-Process -Force` on `AutoHotkey64` is broad.** It kills every AHK instance, not just the one this skill started. When the user has
+  unrelated AHK utilities running, scope the kill by command-line match instead:
+  ```bash
+  pwsh -NoProfile -Command "Get-CimInstance Win32_Process -Filter \"Name='AutoHotkey64.exe'\" | Where-Object CommandLine -like '*cursor-agents-continue.ahk*' | ForEach-Object { Stop-Process -Id $_.ProcessId -Force }"
+  ```
+- **State-line responsibility is unchanged.** The state line (phase, bugbot_clean_at, inline_lag_streak, tick_count) is still emitted at the
+  end of every tick — it's how the next tick reads prior state. The auto-typer only fires `continue`; it does not preserve state for you.
+- **No `tick_count` ceiling.** `tick_count` is observability-only (same as the main skill and `state-schema.md`). This path ends on convergence or **Stop conditions** in `SKILL.md`, not on a tick counter.
+- **`/bugteam` is not optional for BUGTEAM ticks.** AHK only paces **when** the next tick runs; it does not replace the bugteam skill. Skipping
+  **`/bugteam`** after a clean Bugbot review breaks the back-to-back contract.
+- **Fix protocol:** use **`Task` + `generalPurpose`** with the clean-coder **Read** preamble from the main [`SKILL.md` Fix protocol](../SKILL.md#fix-protocol)
+  (never a bare `generalPurpose` production edit). Ensure the clean-coder agent markdown exists at `~/.claude/agents/clean-coder.md` (Windows:
+  `%USERPROFILE%\.claude\agents\clean-coder.md`); copy into `.cursor/agents/` only if you want a repo-local duplicate.
+
+## BUGBOT inline-lag (this path only)
+
+When Step 2 BUGBOT branch c routes to API lag and you are on **this** pacing path: complete Step 4 per **Per-tick behavior under this driver**
+  above (fixed AHK cadence — there is no 60s shortcut). The inline comments should appear on the next tick.
+
+## Convergence
+
+On back-to-back clean: stop the auto-typer per **Convergence cleanup** above; omit `ScheduleWakeup` (not used on this path).
+
+## Stop / safety (this path)
+
+On hard blockers or user stop: omit loop pacing and stop the AHK auto-typer if it was started, per main skill **Stop conditions**. Use the same **scoped** `Get-CimInstance` / `Stop-Process` command as **Convergence cleanup** (command-line match on `cursor-agents-continue.ahk`) so unrelated AutoHotkey instances are not killed.

package/skills/pr-converge/workflows/schedule-wakeup-loop.md

@@ -0,0 +1,37 @@
+# ScheduleWakeup loop pacing (pr-converge)
+
+Load this document when **`ScheduleWakeup` is available** in the parent harness session and you use it for converge **loop pacing** (primary /
+  orchestrated-teams path). Follow it for **every** instruction below that depends on that choice. Shared bugbot / bugteam / Fix protocol steps
+  stay in the main `SKILL.md`.
+
+## Session behavior
+
+Call `ScheduleWakeup` from this same session so the next tick fires back into **this** transcript with the prior tick's state line and PR
+  context still addressable.
+
+## Step 4 — `ScheduleWakeup` branch
+
+At end of tick (unless convergence or another stop condition already omitted pacing), call `ScheduleWakeup` with:
+
+- `delaySeconds: 270` whenever bugbot was just re-triggered (whether by Step 3 directly, by the Fix protocol's mandatory re-trigger, or by
+  BUGTEAM branch 1's same-tick re-trigger). Bugbot finishes a review in 1–4 minutes, so 270s stays under the 5-minute prompt-cache TTL while
+  giving a margin past bugbot's typical upper bound. The single exception is the BUGBOT inline-lag branch in Step 2 of the main skill, which
+  uses `delaySeconds: 60` because no re-trigger fired and the only thing being awaited is GitHub's inline-comments API catching up.
+- `reason`: one short sentence on what is being awaited, including the current `phase` and `bugbot_clean_at` SHA when set.
+- `prompt: "/pr-converge"` — re-enters this skill on the next firing with default loop semantics (no need for the user to type `/loop`). If
+  the parent harness requires the `/loop` wrapper for wakeups to execute, `prompt: "/loop /pr-converge"` is equivalent.
+
+## BUGBOT inline-lag (this path only)
+
+When Step 2 BUGBOT branch c routes to API lag and you are on **this** pacing path: complete Step 4 with `ScheduleWakeup` using `delaySeconds:
+  60` (lag is short-lived).
+
+## Convergence
+
+On back-to-back clean: **omit** further `ScheduleWakeup` calls. Do not start the AHK auto-typer for loop pacing when this path is the active
+  pacer.
+
+## Stop / safety (this path)
+
+On hard blockers or user stop: omit `ScheduleWakeup` per main skill **Stop conditions**. If the session never used AHK for pacing,
+  skip AHK shutdown commands in the companion AHK workflow.

package/skills/qbug/SKILL.md

@@ -19,8 +19,8 @@ description: >-
 
 Shared artifacts with /bugteam are referenced below by path, using the `${CLAUDE_SKILL_DIR}` host-substitution convention (both skills land under `~/.claude/skills/` after install):
 
-- Pre-flight script: `${CLAUDE_SKILL_DIR}/../bugteam/scripts/bugteam_preflight.py`
-- Code-rules gate script: `${CLAUDE_SKILL_DIR}/../bugteam/scripts/bugteam_code_rules_gate.py`
+- Pre-flight script: `${CLAUDE_SKILL_DIR}/../../_shared/pr-loop/scripts/preflight.py`
+- Code-rules gate script: `${CLAUDE_SKILL_DIR}/../../_shared/pr-loop/scripts/code_rules_gate.py`
 - Bug category rubric A–J: [`bugteam/PROMPTS.md`](../bugteam/PROMPTS.md#audit-spawn-prompt-xml-bugfind-teammate)
 - **Audit contract** (finding schema, proof-of-absence, adversarial pass, Haiku secondary, post-fix self-audit, diagnostics JSON): [`bugteam/reference/audit-contract.md`](../bugteam/reference/audit-contract.md)
 - PR comment lifecycle shape: [`bugteam/SKILL.md`](../bugteam/SKILL.md#step-25-pr-comments-one-review-per-loop)
@@ -48,7 +48,7 @@ Refusals — first match wins; respond with the quoted line exactly and stop:
 ## Step 0: Pre-flight
 
 ```bash
-python "${CLAUDE_SKILL_DIR}/../bugteam/scripts/bugteam_preflight.py"
+python "${CLAUDE_SKILL_DIR}/../../_shared/pr-loop/scripts/preflight.py"
 ```
 
 `${CLAUDE_SKILL_DIR}` is host-substituted before the shell runs. Non-zero → fix before continuing. `BUGTEAM_PREFLIGHT_SKIP=1` is emergency only. Add `--pre-commit` when `.pre-commit-config.yaml` exists.
@@ -97,7 +97,7 @@ import os
 from pathlib import Path
 
 skill_dir = Path(os.environ["CLAUDE_SKILL_DIR"])
-gate_script_path = (skill_dir / ".." / "bugteam" / "scripts" / "bugteam_code_rules_gate.py").resolve()
+gate_script_path = (skill_dir / ".." / ".." / "_shared" / "pr-loop" / "scripts" / "code_rules_gate.py").resolve()
 categories_file_path = (skill_dir / ".." / "bugteam" / "PROMPTS.md").resolve()
 ```
 

package/skills/qbug/test_qbug_skill_post_fix_audit.py

@@ -22,8 +22,8 @@ def _load_skill_text() -> str:
 
 def test_should_require_post_fix_gate_before_git_add() -> None:
     skill_text = _load_skill_text()
-    assert "bugteam_code_rules_gate" in skill_text, (
-        "FIX step must run bugteam_code_rules_gate against modified files"
+    assert "code_rules_gate" in skill_text, (
+        "FIX step must run code_rules_gate against modified files"
     )
     assert "post-fix" in skill_text.lower() or "post_fix" in skill_text.lower(), (
         "FIX step must reference a post-fix audit phase"

package/skills/resume-review/SKILL.md

@@ -0,0 +1,261 @@
+---
+name: resume-review
+description: >-
+  Audit a resume for nitty-gritty offenses that bury signal. Resumes are
+  overviews scanned in 6-30 seconds, not detailed proof artifacts. This skill
+  identifies bullets that drift into workflow internals, multi-item technical
+  lists, library names, mechanism narration, or implementation detail, and
+  proposes tighter rewrites that keep the proof points (numbers, scope,
+  outcomes) while dropping the granular how-it-works text. Triggers:
+  "/resume-review", "review my resume", "audit this resume", "is my resume too
+  detailed", "tighten my resume bullets".
+---
+
+# Resume Review
+
+A resume is an **overview**. Hiring managers scan a resume in 6-30 seconds on
+first pass. Granular technical detail buries the signal. Stats, scope, and
+quantified outcomes belong on the resume; workflow internals, multi-item
+technical lists, and how-it-works narration belong in the interview.
+
+## Source authority
+
+Three established sources govern this skill. When a bullet violates one of
+these principles, cite the source in the review comment.
+
+- **Laszlo Bock**, *Work Rules!* (2015), Twelve Books, p. 71 (Bock served as
+  SVP People Operations at Google, 2006-2016): bullets describe "what you
+  accomplished, not what you did." Quantified outcomes beat task descriptions.
+- **Steve Dalton**, *The 2-Hour Job Search* (2012), Ten Speed Press, Ch. 3:
+  hiring managers initially scan a resume in 6-30 seconds. Granular technical
+  detail buries the signal in that scan.
+- **Lou Adler**, *Hire With Your Head* (4th ed., 2021), Wiley: bullets convey
+  **scope and impact**, not tools and tasks.
+
+## The principle
+
+Every bullet earns its place by carrying one of three things:
+
+1. **Scope** — what surface area of work this covered (catalog size, team
+   size, user count, transaction volume, geographic reach).
+2. **Impact** — the outcome the work produced (revenue, time saved, error
+   rate reduced, problem prevented, capability unlocked).
+3. **Quantified proof** — a single number that anchors scope or impact and
+   makes the bullet harder to dismiss as boilerplate.
+
+Bullets that describe the **mechanism** of how the work was done (workflow
+steps, internal architecture, library choices, sequencing of operations) fail
+the overview test. Move that content to the interview.
+
+## Offense categories
+
+The audit walks every bullet and flags any of these patterns. Each pattern
+has a fix template.
+
+### 1. Multi-item parenthetical lists
+
+A parenthetical that enumerates 3+ named items (tools, systems, features,
+sub-tasks).
+
+> **Offender:** "Built and maintain three production Python automation
+> systems (theme submission, theme exports, certification failure
+> processing) backed by a shared utility library."
+
+> **Fix:** Drop the parenthetical. Keep the count. "Built and maintain three
+> production Python automations handling [scope]."
+
+### 2. Workflow-step narration
+
+The bullet describes the sequence of operations the work performs.
+
+> **Offender:** "Manage Samsung's annual catalog-update cycle when 2,800+
+> themes must each be updated, exported, and resubmitted one by one within a
+> 1-2 month window."
+
+> **Fix:** Drop the workflow steps. Keep the scope numbers. "Manage Samsung's
+> annual catalog-update cycle: 2,800+ themes refreshed within a 1-2 month
+> window."
+
+### 3. Engineering-pattern jargon for non-engineering audience
+
+Multiple named technical patterns in one bullet, written for an audience
+that does not share the domain (e.g., infrastructure terms in an operations
+or trust-and-safety resume).
+
+> **Offender:** "Turn recurring failures into stronger error classification
+> (transient vs. permanent), circuit breakers, and checkpoint/resume
+> recovery."
+
+> **Fix:** Replace the pattern enumeration with a single capability noun.
+> "Turn recurring failures into reusable error-handling patterns so the same
+> failure does not happen twice."
+
+### 4. Mechanism narration
+
+The bullet explains how a tool or system internally works.
+
+> **Offender:** "Author and maintain pr-converge, a Claude Code skill that
+> automates the pull request review-and-fix loop until reviewers converge on
+> ready, with three open pull requests (11,000+ lines) actively extending
+> it."
+
+> **Fix:** State the outcome the skill produces. Drop the loop description.
+> "Author and maintain pr-converge, an open-source Claude Code skill that
+> drives draft pull requests to merge-ready autonomously."
+
+### 5. Library or tool names embedded mid-bullet
+
+A library, framework, or tool name appears inside a sentence about
+capability. Library names belong in the dedicated Tools section, not in
+capability bullets.
+
+> **Offender:** "Implemented authenticated workflows end-to-end: account
+> creation, token handling, local-first data with IndexedDB/Dexie, and
+> conflict-aware sync between client and server."
+
+> **Fix:** Drop the library names. State the capabilities. "Implemented
+> authentication, local-first data persistence, and conflict-aware
+> client-server sync end-to-end."
+
+### 6. Redundant statistics
+
+Two numbers in the same bullet that express the same quantity at different
+granularities.
+
+> **Offender:** "Roughly 30 new theme submissions per day (150 per week)."
+
+> **Fix:** Pick one. The daily number is usually the strongest scan signal.
+
+### 7. Implementation detail
+
+Phrases that describe how the work was built rather than what it does.
+
+> **Offender:** "Backed by a shared utility library, with zero manual
+> intervention beyond starting the script."
+
+> **Fix:** Drop the implementation phrase entirely. The capability statement
+> should stand on its own.
+
+### 8. Two-sentence bullets
+
+A bullet that requires two sentences usually carries one bullet of scope and
+one bullet of mechanism. The mechanism sentence should be removed, not
+combined.
+
+> **Offender:** "Author and maintain pr-converge, a Claude Code skill
+> that... [first sentence describes what]. Recent work adds mergeability
+> gates, GitHub Copilot reviewer integration, and post-convergence Copilot
+> follow-up across three open pull requests (11,000+ lines)."
+
+> **Fix:** Keep the capability sentence. Move the second sentence to a cover
+> letter or interview talking point.
+
+## Review protocol
+
+Walk this protocol against every bullet on the resume. Mark each bullet
+PASS, MINOR, or MAJOR.
+
+### Step 1: Scope check
+
+Read the bullet aloud in 4 seconds or less. If you cannot finish in 4
+seconds, the bullet is too long. **Action:** trim to one sentence under 25
+words unless the bullet carries a justified centerpiece (and centerpiece
+bullets stay under 40 words).
+
+### Step 2: Offense scan
+
+For each bullet, scan for the eight offense categories above. Record any
+hits with the category number.
+
+### Step 3: Verify proof points
+
+Every numeric claim in a bullet must be verifiable. If a number cannot be
+sourced, drop it. Hedging numbers ("roughly", "around", "approximately")
+are acceptable when the underlying number is verifiable but variable.
+
+### Step 4: Audience alignment
+
+For each bullet, ask: would the hiring manager for **this specific role**
+recognize the terms used? If the bullet uses domain language outside the
+target role's vocabulary (engineering jargon on a trust-and-safety resume,
+finance acronyms on an engineering resume), rewrite using domain-neutral
+capability nouns.
+
+### Step 5: Mechanism removal pass
+
+For each bullet that survived steps 1-4, ask: does this bullet describe
+**what** the work accomplished, or **how** the work was done? If it
+describes **how**, rewrite to describe **what** and move the **how** to
+interview prep notes.
+
+### Step 6: Section-level coherence
+
+After per-bullet review, scan each section. Check for:
+
+- **Bullet count consistency** — sections with similar weight should have
+  similar bullet counts. A 5-bullet section next to a 1-bullet section
+  signals imbalance.
+- **Voice consistency** — verb tense, sentence structure, and bullet length
+  should match across sections.
+- **Relevance ordering** — the most-relevant-to-the-target-role section
+  should appear first within its time band (Steve Dalton, *The 2-Hour Job
+  Search* §6: relevance over strict chronology when chronology does not
+  conflict).
+
+## Output format
+
+The audit produces a markdown report with this structure:
+
+```markdown
+# Resume Audit Report
+
+## Top offenders (worst first)
+
+### #1 — [Section] bullet [N]. [Severity]
+
+[Quote of current bullet]
+
+**Offenses:** [comma-separated category numbers]
+
+**Proposed rewrite:** [tighter version]
+
+**Words saved:** [N words → M words]
+
+(repeat for each offender)
+
+## Sections that pass
+
+- [Section name]: [bullet count] bullets, all PASS
+- (repeat)
+
+## Section-level findings
+
+[Coherence issues from Step 6, if any]
+
+## Sources cited
+
+- Bock, *Work Rules!* (2015), p. 71 — for offenses [N]
+- Dalton, *2-Hour Job Search* (2012), Ch. 3 — for offenses [N]
+- Adler, *Hire With Your Head* (2021) — for offenses [N]
+```
+
+## When this skill applies
+
+- User asks to review or audit a resume
+- User asks "is my resume too detailed"
+- User asks for tighter resume bullets
+- A resume document is shared and the user wants feedback
+- Before submitting a resume to a target role
+
+## When this skill does not apply
+
+- Cover letter review (use a separate cover-letter-review skill if needed)
+- Resume formatting fixes (font, spacing, layout) — this skill audits
+  content only
+- Resume creation from scratch — this skill assumes a draft exists
+
+## Triggers
+
+`/resume-review`, "review my resume", "audit this resume", "is my resume
+too detailed", "tighten my resume bullets", "what offenses do you see in my
+resume", "are my bullets too granular".

package/agents/agent-writer.md

@@ -1,157 +0,0 @@
----
-name: agent-writer
-description: Use this agent when you need to create a new subagent for Claude Code. This agent guides you through designing, structuring, and writing effective subagents with proper frontmatter, system prompts, and best practices. Trigger when user asks to "create an agent", "write a new subagent", "design an agent", or "help me build an agent".
-tools: Read,Write,Glob,AskUserQuestion
-model: sonnet
-color: blue
----
-
-# Agent Writer - Subagent Creation Assistant
-
-You are a specialized agent that helps create well-structured, effective subagents for Claude Code. Your role is to guide the user through the entire agent creation process, ensuring best practices and proper structure.
-
-## Your Process
-
-### Phase 1: Discovery & Design
-
-Ask the user these key questions to understand their needs:
-
-1. **Purpose & Scope**
-   - What specific problem or workflow will this agent handle?
-   - What makes this task worthy of a dedicated agent vs a skill or direct implementation?
-   - What is the expected trigger context? (e.g., "after code completion", "when user mentions X")
-
-2. **Specialization Level**
-   - Is this a narrow, focused task (recommended) or broader capability?
-   - What expertise domain does this require? (e.g., testing, refactoring, documentation)
-
-3. **Tool Requirements**
-   - Which tools does this agent need? (Read, Write, Edit, Bash, Grep, Glob, Task, etc.)
-   - Should it have restricted access for safety? (e.g., read-only agents)
-   - Will it need to invoke other agents via Task tool?
-
-4. **Invocation Strategy**
-   - Should this be PROACTIVE (auto-invoked when context matches)?
-   - Or explicit-only (user must request it)?
-   - What keywords/patterns should trigger it?
-
-5. **Examples & Edge Cases**
-   - What are 2-3 concrete examples of when this agent should be used?
-   - What are scenarios where it should NOT be used?
-
-### Phase 2: Generate Agent Structure
-
-Based on discovery, create the agent file with:
-
-**Frontmatter Requirements:**
-```yaml
----
-name: agent-name-in-kebab-case
-description: Clear description of when to use this agent, including trigger keywords and scenarios. For proactive agents, include "Use PROACTIVELY" or "MUST be used when".
-tools: comma,separated,tool,list (or omit for all tools)
-model: sonnet (or opus/haiku/inherit)
----
-```
-
-**System Prompt Structure:**
-
-```markdown
-# [Agent Name] - [Brief Subtitle]
-
-You are a specialized agent that [primary purpose]. Your role is to [detailed responsibility].
-
-## Your Responsibilities
-
-[Bulleted list of what this agent does]
-
-## Your Process
-
-[Step-by-step workflow the agent should follow]
-
-## Critical Rules
-
-[Mandatory constraints and requirements]
-
-## When to Use This Agent
-
-[Specific triggering scenarios with examples]
-
-## When NOT to Use This Agent
-
-[Anti-patterns and exclusions]
-
-## Examples
-
-<example>
-Context: [Scenario description]
-user: "[Example user request]"
-assistant: "[How this agent should respond]"
-<commentary>
-[Why this agent is appropriate here]
-</commentary>
-</example>
-
-[2-3 more examples showing variety]
-
-## Output Format
-
-[Expected deliverables and communication style]
-```
-
-### Phase 3: Validation & Refinement
-
-Before finalizing, check:
-
-1. **Single Responsibility**: Does it do ONE thing well?
-2. **Clear Triggers**: Is it obvious when to invoke this agent?
-3. **Tool Minimization**: Does it have only necessary tools?
-4. **Actionable Instructions**: Can another AI follow these instructions?
-5. **Example Coverage**: Do examples show both use and non-use cases?
-
-### Phase 4: Placement Decision
-
-Determine where to save the agent:
-
-- **Project-specific**: `.claude/agents/` (version controlled, team-shared)
-- **Personal/global**: `~/.claude/agents/` (user-specific, cross-project)
-- **Plugin**: For distribution to others
-
-Default to project-specific unless user specifies otherwise.
-
-## Best Practices You Must Follow
-
-1. **Focused Purpose**: "Design focused subagents with single responsibilities"
-2. **Detailed Prompts**: "Write detailed prompts with specific instructions and constraints"
-3. **Tool Restriction**: "Limit tool access to only necessary ones"
-4. **Proactive Language**: Use "Use PROACTIVELY" for auto-invocation
-5. **Action-Oriented Descriptions**: "Make descriptions specific and action-oriented"
-6. **Multiple Examples**: Always include 2-3 diverse examples showing when to use
-7. **Clear Boundaries**: Define both when to use AND when not to use
-
-## Anti-Patterns to Avoid
-
-- ❌ Vague descriptions like "helps with code"
-- ❌ Agents that do multiple unrelated things
-- ❌ Missing examples or edge cases
-- ❌ Unclear tool requirements
-- ❌ No guidance on when NOT to use
-- ❌ Generic system prompts without specific instructions
-
-## Your Communication Style
-
-- Ask clarifying questions when requirements are unclear
-- Propose concrete examples to validate understanding
-- Suggest improvements to overly broad agent concepts
-- Show the user the generated agent before saving
-- Explain your design decisions
-
-## Workflow Summary
-
-1. **Ask discovery questions** (use AskUserQuestion for key decisions)
-2. **Propose agent structure** based on answers
-3. **Generate complete agent file** with frontmatter + system prompt
-4. **Review with user** before saving
-5. **Save to appropriate location**
-6. **Provide usage guidance** (how to invoke, test scenarios)
-
-Remember: A great agent is narrow, focused, and has crystal-clear triggering conditions. When in doubt, make it more specific, not more general.