improve-template

name	improve-template
description	Use when modifying the Geniro plugin itself — fix a Geniro skill, agent, hook, or ARCHITECTURE.md. Researches via parallel agents (codebase + ARCHITECTURE.md + internet), presents evidence, implements after approval. Skip for general codebase Q&A (/geniro:investigate) or app-code bugs (/geniro:debug).
context	main
model	inherit
allowed-tools	["Read","Write","Edit","Bash","Glob","Grep","Agent","AskUserQuestion","WebSearch","WebFetch"]
argument-hint	<issue description or area to improve>

/improve-template — Template Investigation & Fix Pipeline

You are the orchestrator for investigating and fixing issues in the Geniro plugin. You coordinate research agents, cross-reference findings, present evidence, and delegate implementation. You NEVER implement changes directly except trivial fixes (1-2 lines, obvious target, no ambiguity) — everything else goes through subagents.

Template path: (repo root — skills/, agents/, hooks/, lib/, scripts/, cursor/) Architecture path: ARCHITECTURE.md (consolidated design decisions from all milestones + operational rules)

Subagent Model Tiering

Follow the canonical rule in ${CLAUDE_PLUGIN_ROOT}/skills/_shared/model-tiering.md: spawn sites OMIT model= so every subagent inherits the orchestrator tier — the user picked that tier at session start and owns the cost/quality trade-off; a skill-side hardcode (e.g. forcing opus from a Sonnet session) overrides that choice silently. For plugin-defined subagents (the agents under ${CLAUDE_PLUGIN_ROOT}/agents/), also follow the ladder in ${CLAUDE_PLUGIN_ROOT}/skills/_shared/spawn-agent.md §The rule: try Agent(subagent_type="geniro:<agent>", ...) first — the marketplace-install happy path; on Agent type '<name>' not found, retry with the bare <agent> (vendored / harness installs); if that also returns "not found", degrade to general-purpose with the agent body inlined (frontmatter stripped). Cache whichever rung resolved for the rest of the session — registration is fixed at session init. Skipping the prefixed rung silently degrades every spawn to general-purpose on a normal install.

Skill-specific mapping:

Spawn	Tier	Why
Phase 1 research agents (codebase / ARCHITECTURE.md / internet)	inherit (OMIT model=)	Reasoning-grade research runs at the tier the user chose for the session
Phase 2b validation	orchestrator-inline (no spawn)	Synthesis-of-findings — light reasoning that fits orchestrator's main context cleanly per subagent rationalization
Phase 4 implementation agents	inherit (OMIT model=)	Template edits are the deliverable — they run at the user's chosen tier
Phase 5 review agent	inherit (OMIT model=)	Fresh reviewer judges at the same tier that authored the changes
Create-skill Phase A duplicate-check + Phase B author agent	inherit (OMIT model=)	Semantic comparison and skill authoring are reasoning-grade

---

State Persistence

After completing each phase, write a checkpoint to .geniro/state/improve-template/state-<slug>.md (compute <slug> per ${CLAUDE_PLUGIN_ROOT}/skills/_shared/within-skill-state-handoff.md § Slug rules):

Branch: <git branch --show-current OR detached-<short-sha>>
Worktree: <git rev-parse --show-toplevel>
Timestamp: <ISO-8601 UTC>
Phase [N] completed: [phase name]
Issue: [one-line description]
Findings count: [N approved]
Files to change: [list]

Capital Branch:/Worktree:/Timestamp: are mandatory per ${CLAUDE_PLUGIN_ROOT}/skills/_shared/within-skill-state-handoff.md § Producer contract.

On skill start: compute <slug> per the helper § Slug rules, then Glob(".geniro/state/improve-template/state-<slug>.md"). If present, run the helper § Consumer contract (Case A/B/C/D mismatch handling). After "proceed", read the file and resume from the next incomplete phase. Ask the user if this is still the active improvement or a new one.

---

Mode Detection (before Complexity Gate)

Detect which of three modes the request wants — process-handoff (consume findings from /analyze-thread), create-skill (author a new skill), or fix/improve an existing skill (default mode). Check in this order:

process-handoff mode. Triggers when $ARGUMENTS matches process-handoff, process handoff, or process handoff from analyze-thread. Route to the handoff-ingestion path below — it reads the /analyze-thread findings file and feeds each finding through the existing Complexity Gate, so it does not skip the normal pipeline.

create-skill mode. Triggers when:

• $ARGUMENTS matches create skill, new skill, author skill, write a skill, make a skill, add a skill, /improve-template create-skill
• $ARGUMENTS describes a capability that does not yet exist (no SKILL.md matches the named scope)

If create-skill mode is detected, route to the create-skill flow below — skip the Complexity Gate and Phase 1 Investigate (those are improve-existing-skill mechanics; create-skill has its own 3-phase author flow).

Otherwise default to improve-existing-skill mode (Complexity Gate → Phase 1).

Handoff-ingestion path (process-handoff mode)

1. Resolve the branch (git branch --show-current) and read .geniro/state/handoff/from-analyze-thread-<branch>.md. If absent, report that no handoff exists for this branch and ask the user to name the area to improve instead (falls back to improve-existing-skill mode).
2. Parse the frontmatter open_questions[] array — each entry carries id / source (the check that surfaced it) / question / severity / suggested_action / status, plus an optional recurrence: <M>/<T> when the analysis ran over several threads. Skip entries already status: resolved or wontfix.
3. For each unresolved finding, run the Complexity Gate below to classify it (obvious bug fix → Phase 1-fast; targeted improvement or open-ended → full pipeline). The suggested_action and any context framing seed the Step 1 request-parse; the source check and findings_count set the scope. Order the findings by recurrence before severity where it is present — a defect reproduced across several independent threads is a systematic instruction failure, while a one-off may be a single run's noise.
4. Group findings that touch the same file into one implementation unit (Phase 4 grouping) rather than running the whole pipeline per finding.
5. After the changes land and the user ships them (Phase 6), the consumed handoff is stale — note it for the user; do not re-process it on a later run.

---

Complexity Gate (before Phase 1) — improve-existing-skill mode only

Classify the request — this picks both the pipeline depth AND which research sources Phase 1 spawns. Self-classify; do not spawn a triage subagent.

Request type	Signals	Pipeline	Default research sources
Obvious bug fix	Screenshot/error shown; broken file & fix obvious (regex false positive, wrong path, typo, broken cross-reference)	Phase 1-fast	Codebase only — or 0 agents if fix is 1-2 lines and unambiguous
Targeted improvement	Specific skill/agent/hook named; clear scope; user cites the file or behavior	Full pipeline	Codebase always; ARCHITECTURE.md / Internet conditional on triggers below
Open-ended investigation	"Make X better"; broad area; vague target; no specifics	Full pipeline	All three (codebase + ARCHITECTURE.md + internet)

Research Selection Matrix

Codebase research — always runs in the full pipeline. Reading current template state is mandatory.

ARCHITECTURE.md research — run when the change touches a pattern or structure (phase shape, agent-spawning syntax, anti-rationalization, cross-cutting consistency across N skills). Skip for trivial typo / wrong path / cross-reference repair / YAML-syntax error / pure reword that does not change semantics.

Internet research — run when ANY of: a new skill / agent / hook is being added; a new pattern or behavior is being introduced (one not already in the template); an external SDK / API / tool / Claude Code feature is referenced; the request is abstract and lacks specifics ("make X better" with no concrete target). Skip when the request is internal-only logic of our skills, a reword/clarify/rename/reorder of existing instructions, or a bug fix the user has already located.

Record the selected sources in the state checkpoint as research-sources: [list] so Phase 5 reviewers can see scope was narrowed by the matrix, not by oversight.

Phase 1-fast: Quick Fix Path

For obvious bug fixes. The user already showed what's broken.

1. Read the affected file(s) to confirm the bug; capture pre-fix content as the baseline for the Phase 5 review prompt
2. Spawn the research sources the matrix selected (often Codebase only, sometimes none); note the selected sources in any checkpoint you write
3. Present the fix with evidence, then use the AskUserQuestion tool (do NOT output options as plain text) to ask "Approve this fix or investigate deeper?" with options: "Approve — apply the fix" / "Investigate deeper — run full pipeline"
4. If approved: apply the fix (directly if 1-2 lines, subagent if more)
5. Spawn a fresh review agent (Phase 5 Step 1) to verify
6. Skip to Phase 6

---

PHASE 1: INVESTIGATE (parallel research)

Purpose: Gather evidence from the research sources the Matrix selected — up to three independent sources (codebase / ARCHITECTURE.md / internet).

Input: User describes an issue, shows a screenshot, or names an area to improve.

Step 1: Parse the request

Classify the request, then look up its research sources in the Matrix above:

• Bug fix — something broken (screenshot, error, false positive). Extract: what happened, expected behavior, affected file(s).
• Improvement — enhance existing behavior. Extract: which skill/agent/hook, what aspect.
• New capability — add something missing. Extract: what, why, which files affected. Internet research is mandatory here — new patterns require external evidence.

Step 2: Spawn the selected research agents in ONE response

Spawn ONLY the agents the Matrix selected — all in the same assistant turn, NOT one per turn. Skipped sources are NOT failures; the matrix is the contract. Log omitted source(s) in the state checkpoint with the matching skip reason. The agent prompts below stay as written; just omit the agents you skip. Replace every {{placeholder}} with the actual content from Step 1 before spawning.

Agent(prompt="""
## Task: Internet Research
Search for patterns, best practices, and known solutions related to:
{{issue description from Step 1}}

Search for:
- Claude Code documentation and GitHub issues related to this
- Community patterns from claude-code plugins/frameworks
- General best practices for {{relevant domain from Step 1}}

For each finding, provide:
- Source (URL or reference)
- Key pattern or technique
- Direct applicability to our issue
- Evidence strength (strong/moderate/weak)

Return findings as a structured table. Do NOT suggest implementation — research only.
""", description="Research: internet patterns")

Agent(prompt="""
## Task: ARCHITECTURE.md Research
Read `ARCHITECTURE.md` and search for sections relevant to:
{{issue description from Step 1}}

This is a ~220-line consolidated decision record — one section per milestone (state files, memory layers, each skill) plus cross-cutting sections (subagent model selection, deep mode, self-learning, operational rules). Each section lists key rulings as bullets with file-path citations.
Search strategy:
1. Read the file fully — it is short; no grep or ToC sampling needed
2. Extract every decision, invariant, or operational rule that constrains or informs the issue
3. When a decision cites a `_shared/` helper or skill file, read that target for the full contract
4. If survey-depth evidence is needed (how production frameworks solve this), the historical 14-framework best-practices survey (4,440 lines) is available via `git show 3bb0857~1:report.md` — it was removed from the working tree when the docs were consolidated

For each finding, provide:
- Section name and line range in ARCHITECTURE.md (or the cited helper file)
- The specific decision or rule
- How it applies to our issue
- Whether our template already follows it or not

Return findings as a structured table. Do NOT suggest implementation — research only.
""", description="Research: ARCHITECTURE.md decisions")

Agent(prompt="""
## Task: Codebase Exploration
Explore the current state of the template files related to:
{{issue description from Step 1}}

Template root: repo root (skills/, agents/, hooks/, lib/, scripts/, cursor/)

Exploration strategy:
1. Identify which files are affected (skills, agents, hooks, lib helpers, build scripts, the Cursor port under cursor/)
2. Read each affected file fully
3. Identify current patterns, gaps, and inconsistencies
4. Check cross-references (does file A reference file B correctly? Are paths valid?)
5. Check for related patterns in other skills that solve similar problems

For each finding, provide:
- File path and line range
- Current behavior
- Gap or inconsistency found
- How other template files handle similar situations

Return findings as a structured table. Do NOT suggest implementation — research only.
""", description="Research: codebase exploration")

Step 3: Collect and record

Wait for all spawned agents. Write key findings plus research-sources: [list] to the state checkpoint.

---

PHASE 2: CROSS-REFERENCE & FILTER

Purpose: Filter raw research to evidence-backed improvements only. This is orchestrator work — you aggregate and filter directly, no subagents needed.

Step 1: Build a combined findings list

Merge findings from the research agents that ran (1-3, depending on the Matrix). Group by topic. Same finding from multiple sources = stronger evidence — note the convergence. If only one source ran, evidence strength caps at what that source supports.

Step 2: Filter each finding

For each finding, assess yourself:

Structural compatibility:

• Compatible with template architecture? (skills = orchestrators, agents = leaf workers, <500 lines)
• Would it break existing patterns or cross-references?
• Which files would need changes?

Evidence quality:

• Strong: documented in official Claude Code docs, proven in production framework, or demonstrated by screenshot/error
• Moderate: backed by a recorded decision in ARCHITECTURE.md, used by 2+ frameworks in the historical survey (git show 3bb0857~1:report.md), or a logical extension of documented behavior
• Weak: single blog post, theoretical benefit, "should work" reasoning
• Rejected: no evidence, contradicts known limitations, or speculative

Step 3: Build the evidence table

Keep only findings that are:

• Structurally compatible (or adaptable)
• Evidence quality: strong or moderate
• Not contradicted by other findings

Write checkpoint with approved finding count.

---

PHASE 2b: REDUNDANCY & RELEVANCE VALIDATION (orchestrator-inline)

Purpose: Adversarial gate BEFORE the user sees findings — catches items that duplicate existing instructions or propose theoretical/over-engineered changes.

Orchestrator-inline validation per finding (no subagent — folded under subagent rationalization; same Anthropic rationale as /review Phase 3 dedup). For each Phase 2-approved finding, the orchestrator:

1. Redundancy check (ALIGNS / CONTRADICTS / NEUTRAL): Grep target files for instructions covering the same ground. CONTRADICTS = duplicate; ALIGNS = compatible with existing; NEUTRAL = novel-but-non-conflicting.
2. Relevance check (APPROPRIATE / OVER-ENGINEERED): weigh against current scope — APPROPRIATE if needed for stated purpose; OVER-ENGINEERED if YAGNI or defensive polish.
3. One-line rationale captures the why.

Then tag: FILTER if CONTRADICTS (redundant) or OVER-ENGINEERED (not needed); otherwise KEEP. Write checkpoint with KEEP count. Filtered findings appear in Phase 3's "Filtered" section for transparency but are not proposed for implementation.

---

PHASE 3: PRESENT TO USER (WAIT)

Purpose: Show evidence-backed findings and get approval before any changes.

Step 1: Present the evidence table

## Investigation Results: [issue/area]

### Findings (evidence-backed only)

| # | Finding | Evidence | Source(s) | Files Affected | Complexity |
|---|---------|----------|-----------|----------------|------------|
| 1 | [what to change] | [why — specific evidence] | [internet/report/codebase] | [file list] | [trivial/small/medium] |
| 2 | ... | ... | ... | ... | ... |

### Rejected (insufficient evidence)
- [finding] — rejected because [reason]

### Filtered by Phase 2b (redundant or over-engineering)
- [finding] — filtered because [redundant with <file:line> | over-engineering for current scope]

### Implementation plan
For each finding: which files change, what changes, estimated line impact.

Step 2: Ask for approval

Use the AskUserQuestion tool (do NOT output options as plain text — the tool provides a structured UI). Call it with:

• Question: "How should I proceed with these findings?"
• Options (use these exactly):
  • "Implement all findings"
  • "Let me pick which ones to implement"
  • "I disagree with some findings — let me challenge them"
  • "Research deeper on specific items"

If user picks C or D: Go to Phase 3b.

Phase 3b: Challenge Resolution

For each challenged finding, spawn a research agent with: the finding description, the user's concern, and instructions to search for definitive evidence. Update the evidence table based on results. Re-present to user. Loop until approved.

---

PHASE 4: IMPLEMENT (delegated)

Purpose: Apply approved changes through subagents. Orchestrator does NOT edit files (except trivial 1-2 line fixes where the target and change are unambiguous).

Step 0: Capture baseline

Read and record the current content of all files that will be modified — Phase 5 needs this baseline for before/after comparison.

Step 1: Group changes by file/module

Group approved findings into implementation units:

• Trivial (1-2 lines, obvious target): Apply directly using Edit tool. No subagent needed. Guard: If you find yourself reading more than 2 files or the fix touches logic, delegate instead.
• Single file changes: One agent per file
• Cross-file changes: One agent per logical group (same module/feature)

Step 2: Spawn implementation agents in ONE response (all Agent() calls in the same assistant turn, NOT one per turn)

Pre-inline the current file content each agent needs (from Phase 1 codebase research).

Agent(prompt="""
## Task: Implement Changes
Apply the following approved changes:

### Change 1: [description]
**File:** [path]
**Current behavior (line N-M):**
[paste relevant current code — pre-inlined from Phase 1 research]

**Required change:**
[specific description of what to change and why]

### Constraints
- Stay under 500 lines for SKILL.md files
- Preserve existing patterns (phase structure, agent spawning syntax, anti-rationalization tables)
- Do NOT add features beyond what was approved
- Do NOT refactor surrounding code
- Do NOT add comments explaining the change itself
- **Edit-in-place principle:** When fixing or improving an instruction, rewrite the
  original instruction to be explicit about the correct behavior. NEVER add separate
  notes, exceptions, caveats, or conditions below/after the original. Adding
  "NOTE: also handle X" or "Exception: when Y, do Z" creates context distance and
  instruction rot. The original instruction should read correctly on its own.
- **Minimum-tokens principle:** Write the change at the lowest token cost that fully
  preserves meaning and behavior — don't restate a rule already present in the file,
  don't re-explain standard tool or model behavior, and prefer tightening an existing
  line over adding a new one. The bar is zero degradation: a tightening that drops a
  load-bearing nuance, edge case, or behavioral condition is a degradation, not a
  compaction — keep the longer wording. Signal density, not line count, is the target.
- **Assume a capable model** (per `.claude/rules/skill-prose.md` §Assume a capable
  model): in the sections you touch, also REMOVE over-detailed mechanics the model
  derives itself — platform command recipes, shell idiom hand-holding, prescribed
  loop shapes where goal + bound suffices, chewed-up substeps for a one-step goal.
  Excess detail isn't just token cost: it primes one mechanism and confuses the run
  when the environment wants another. An improvement pass removes the unnecessary,
  not only adds. Contracts stay: schemas, paths, thresholds, canonical option labels,
  and explain-WHY on rationalization-prone rules are not "detail".

### Definition of Done
- [ ] All approved changes applied
- [ ] No unintended side effects on surrounding code
- [ ] File line count verified (under 500 for skills)
- [ ] Cross-references to other files still valid
""", description="Implement: [group name]")

Step 3: Validation gate

Orchestrator runs these checks directly (no subagent). All must pass before Phase 5:

1. Line counts: wc -l on each changed SKILL.md — 500 lines is the target, 700 the hard ceiling (.claude/rules/skill-structure.md § File-size limits). Over 700 → move detail into a companion reference file before proceeding; 500-700 is a soft flag, not a blocker (line caps are guidelines — never trim load-bearing content to hit a number).
2. Outbound references: Glob for every path/agent/skill name mentioned in changed files — all must exist
3. Inbound references: Grep the entire template for filenames of changed files — verify referencing files aren't broken
4. YAML frontmatter: Verify changed SKILL.md files have valid frontmatter (name, description fields present)
5. Pattern consistency: Compare phase structure and agent-spawning syntax in changed skills against 1-2 other skills
6. Description-format checks (6 sub-checks): apply when any changed SKILL.md's YAML description: field was added or modified; full procedure in the "Description-format validator" section below. Items: length ≤1024 chars (warning), third person (warning), "Use when" trigger clause (warning), "Skip for" anti-trigger clause (note), no {{placeholder}} residue (blocker), valid YAML frontmatter (blocker, overlaps with check #4 — counts once).
7. README/docs sync + generated-file sync (when changes touch user-facing surface or agents/*.md): apply when the change adds/removes/renames a sub-command (verb), modifies YAML description or argument-hint, alters advertised behavior of an existing slash command, or adds/removes a top-level skill. Grep README.md and any docs/*.md for the changed skill's name (e.g., geniro:actions); also grep CLAUDE.md since it carries the skills-table row. For each matched section, read it and compare against the new behavior — flag as warning any drift: missing or extra sub-commands in lists, contradictory or stale behavioral descriptions, outdated usage examples, stale frontmatter mirrors. Propose the specific README/CLAUDE.md edits as part of the Phase 6 Step 1 summary so they ship with the same commit the user approves; do NOT silently apply them. If no README/CLAUDE.md/docs mention exists for the changed skill, note "no docs mention to sync". Warning-level — does NOT trigger the fix agent. Generated Cursor agents: when the change edited any agents/*.md, run scripts/build-cursor-agents.sh and include the regenerated cursor/agents/*.md in the same change set — cursor/agents/ is generated from agents/, and tests/cursor/build-agents-fresh.sh hard-fails CI on drift between them. Never hand-edit cursor/agents/; re-run the script instead of routing this to the fix agent.
8. Compaction & redundancy (added text): scan the lines this change ADDED for weight without payload — a restatement of an instruction already in the file, a re-explanation of standard tool or model behavior, or a hedge with no condition. Propose a tightening only when it fully preserves meaning and behavior — the bar is zero degradation; never trade away a load-bearing nuance, edge case, or behavioral condition to save tokens (the description field is out of scope here — the Description-format validator owns it). Warning-level — surfaces in the Phase 6 Step 1 Summary, does NOT trigger the fix agent.

If any check fails: spawn a fix agent. Re-run failed checks only. Max 1 fix round. Write checkpoint. Warnings (#6 sub-items 1-4, #7 README/docs drift, and #8 compaction/redundancy) do NOT trigger the fix agent — they appear in the Phase 6 Step 1 Summary as advisory items.

---

PHASE 5: SELF-REVIEW (fresh subagent)

Purpose: Independent review by a fresh agent that wasn't involved in research or implementation.

Step 1: Spawn review agent

MUST be a fresh agent — never reuse implementation agents (avoids anchoring bias).

Agent(prompt="""
## Task: Independent Review of Template Changes
Review changes made to the Geniro plugin template. You were NOT involved in
researching or implementing these changes — review with fresh eyes.

### Changes made:
{{git diff output of all changes}}

### Pre-change baseline:
{{file contents captured in Phase 4 Step 0}}

### Review checklist:
1. **Correctness:** Do the changes do what they claim? Any logic errors?
2. **Consistency:** Do changes match patterns used elsewhere in the template?
   - Phase structure consistent with other skills?
   - Agent spawning syntax matches template conventions?
   - Anti-rationalization tables present where needed?
3. **Scope creep:** Were any changes made beyond what was approved?
4. **Edit-in-place:** Were original instructions rewritten to be explicit, or were
   notes/exceptions/caveats added separately? Separate notes = blocker.
5. **Regressions:** Compare the diff against the baseline. Check:
   - Did any existing instruction's meaning change unintentionally?
   - Are cross-references that worked before still valid?
   - Could downstream skills/agents behave differently due to these changes?
6. **Pre-existing bugs:** While reviewing the changed files, also note any bugs, inconsistencies, or broken patterns that existed BEFORE this change. Report these separately — they are opportunities, not blockers.

### For each issue found, report:
- File and line
- Issue description
- Severity (blocker/warning/nit)
- **Category: "introduced" or "pre-existing"**
- Suggested fix

If no issues in either category: report "LGTM — all checks passed"
""", description="Review: independent template review")

Step 2: Process review results

Introduced issues (from the current changes):

• Blockers: Spawn a fresh fix agent (not the implementer). Then re-review with another fresh agent. Max 1 fix round.
• Warnings: Present to user — let them decide.
• Nits: Apply if trivial, skip if subjective.
• LGTM: Proceed to Step 3.

Step 3: Surface pre-existing bugs

If the reviewer found pre-existing bugs, present them to the user in a separate table:

### Pre-existing bugs found during review

These were NOT introduced by the current changes but were discovered while reviewing the affected files:

| # | File | Bug | Severity | Suggested fix |
|---|------|-----|----------|---------------|
| 1 | [path:line] | [description] | [blocker/warning/nit] | [fix] |

Use the AskUserQuestion tool (do NOT output options as plain text) to ask:

• Question: "Want to fix any of these pre-existing bugs?"

• Options:

  • "Fix all of them"
  • "Let me pick which ones to fix"
  • "Skip — focus on the current changes only"

• If fix all: spawn implementation agents for the pre-existing fixes (same Phase 4 flow), then re-run Phase 5 review on the new changes only.

• If pick: present each bug individually and let the user select, then implement selected fixes.

• If skip: proceed to Phase 6.

If no pre-existing bugs were found, skip this step.

---

PHASE 6: REPORT, LEARN & COMPLETE

Step 1: Summary

Present to the user:

## Changes Applied

| File | Change | Lines |
|------|--------|-------|
| [path] | [what changed] | [before → after line count] |

### Review result: [LGTM / N warnings]
[any warnings from Phase 5]

Step 2: Extract learnings to memory

Scan for user corrections, convention discoveries, and limitations encountered. Before writing, check if existing memory already covers the topic — update rather than duplicate. Skip if nothing novel was discovered.

Step 3: Cleanup

Remove .geniro/state/improve-template/state-<slug>.md per ${CLAUDE_PLUGIN_ROOT}/skills/_shared/within-skill-state-handoff.md § Cleanup contract — delete only the current branch's slug, never globbing all state-*.md files. Also clear two generations of legacy state files (best-effort; either may not exist):

rm -f ".geniro/improve-template/state-${slug}.md" 2>/dev/null  # intermediate legacy: pre-state-dir, slug-scoped
rm -f .geniro/improve-template-state.md           2>/dev/null  # original legacy: pre-slug, non-scoped

Step 4: Suggest commit & push

After cleanup, run git status --short and git diff --stat to show what's staged vs. unstaged. Then use the AskUserQuestion tool (do NOT output options as plain text) to offer shipping the changes:

• Question: "Ship these template changes?"
• Options:
  • "Commit and push (Recommended)" — orchestrator stages changed files by name, creates a commit with a message summarizing the findings, and pushes to the current branch's upstream
  • "Commit only — I'll push later"
  • "Skip — I'll commit manually"

If the user picks commit+push or commit-only:

• Stage only the files listed in the Phase 6 Step 1 summary table (never git add -A or git add .).
• Write the commit message via HEREDOC, following the repo's commit style (check git log -5 --oneline first).
• For commit+push: run git push after the commit succeeds. If the branch has no upstream, report the exact git push -u origin <branch> command and ask the user to confirm before running it.
• Never use --no-verify, --amend, or any destructive flag.
• If a pre-commit hook fails, surface the failure and stop — do not retry or bypass.

If the user picks skip, print the suggested commit message and the git add / git commit / git push commands for them to run manually.

---

Create-Skill Mode (3-phase author flow)

When Mode Detection routes to create-skill, run this flow instead of the Investigate → Filter → Implement pipeline. Adapted from Pocock's write-a-skill (3-phase: Gather requirements → Draft → Review) but uses your existing validation infrastructure (validation gate + relevance-filter

• self-review) for production rigor.

Phase A: Gather Requirements (interactive)

1. Determine target. Ask via AskUserQuestion with header "Skill kind":

   • Plugin-facing (/geniro:<name>) — adds to skills/<name>/SKILL.md in the plugin
   • Project-local (/<name>) — adds to .claude/skills/<name>/SKILL.md in the user's project
   • Plugin-internal helper (no slash invocation) — _shared/<name>.md referenced by other skills

2. Read the official Skills authoring docs once to ground recommendations:

   • WebFetch https://docs.claude.com/en/docs/claude-code/skills — Claude Code Skills overview
   • WebFetch https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills — Anthropic's authoring guidance
   • Cache in conversation context; do NOT re-fetch within the session.

3. Interview the user via 3-5 sequential AskUserQuestion calls (one question per AUQ — don't batch in this phase, the answers compound):

   • Trigger: "What should activate this skill? (1-3 phrases or contexts users would describe)" — collect to use in the description's "Use when" clause
   • Anti-trigger: "When should this skill explicitly NOT fire?" — collect to use in description's "Skip for" clause
   • Inputs: "What does the skill receive? ($ARGUMENTS shape, files, conversation context)"
   • Outputs: "What artifacts does it produce? (files written, commits made, comments posted, AskUserQuestion gates fired)"
   • Tools needed: "Which Claude Code tools does the skill need? (Read, Write, Edit, Bash, Grep, Glob, Agent, AskUserQuestion, WebSearch, WebFetch, TodoWrite, MCP servers)"
   • (Optional, if applicable) Subagents: "Does this skill spawn subagents? Which existing agent definitions, or new ones?"
   • (Optional, if applicable) Workflow file integration: "Should this skill read from .geniro/workflow/*.md (Linear, GitHub Issues, etc.)?"

4. Pre-existing-instruction check. Spawn a generic Agent (subagent_type="general-purpose", model= omitted — inherits orchestrator tier) with a focused prompt: pre-inline (a) the proposed skill's purpose + trigger + outputs, (b) the existing skills inventory (Glob skills/**/SKILL.md summary as a list of name | description-first-line pairs), (c) the project-local skills inventory (Glob .claude/skills/**/SKILL.md). The agent's task: read each existing skill's full description (and the first 30 lines of any with significant trigger overlap), then return a structured table with columns name | overlap-level (none|partial|significant) | overlap-rationale | recommendation (proceed | extend-existing | reject). The orchestrator decides KEEP (proceed to Phase B) or REJECT (route the user to the existing skill instead). Without this check, the codebase accumulates near-duplicate skills.

Phase B: Draft (one author-agent spawn, then validate)

1. Spawn an author agent (general-purpose, model= omitted — inherits orchestrator tier) with:

   • The full Phase A interview transcript (pre-inlined)
   • The path target (skills/<name>/SKILL.md or .claude/skills/<name>/SKILL.md)
   • Constraints (pre-inlined): description rules from Phase 4 validator below + the 500-line target / 700-line hard ceiling from .claude/rules/skill-structure.md § File-size limits + reference depth ≤1 hop + edit-in-place principle
   • 1-2 exemplar SKILL.md files closest in shape to the proposed skill (e.g., for a small command-style skill, point at instructions/SKILL.md; for a multi-phase pipeline, point at refactor/SKILL.md)
   • Output instructions: "Write the SKILL.md file using the Write tool. Follow the structure of the exemplars. Description must be <1024 chars, third person, include 'Use when' AND 'Skip for' clauses. SKILL.md targets 500 lines with a 700-line hard ceiling (per .claude/rules/skill-structure.md); split overflow into companion reference files (e.g., <name>-reference.md) rather than trimming load-bearing content — the implement skill's implement-reference.md is the canonical example of this split."

2. Validate (Phase 4 Step 3 validation gate from improve-template's existing flow) — including the new description-format checks (see "Description-format validator" below).

Phase C: Review (fresh agent, your existing pattern)

Run the standard Phase 5 self-review with a fresh agent that did NOT see the author prompt. Review checklist for create-skill is:

• All Phase A interview answers reflected in the SKILL.md
• Description meets all 6 format rules (validator checks 1-6 below)
• SKILL.md ≤300 lines OR has companion files split logically
• No invented tools (every tool in allowed-tools actually exists in Claude Code's tool surface)
• No invented ${CLAUDE_PLUGIN_ROOT}/... references (every cited path actually exists)
• Frontmatter valid (name, description, allowed-tools, model)
• When to Use section explicit and matches the description's triggers
• Examples section concrete (not "use this for things")

Process review results per the existing Phase 5 routing (Blockers → fresh fix agent, max 1 round).

Phase D: Report & Commit (reuse Phase 6)

Same Phase 6 as improve-existing-skill mode. Skip Step 3 cleanup (no state file written for create-skill — the 3-phase flow is short enough to fit in conversation context).

---

Description-format validator (Phase 4 Step 3 extension)

Adds 6 format checks to the existing Phase 4 validation gate. Applies to BOTH improve-existing-skill (when changes touch a SKILL.md description field) AND create-skill mode.

For each changed/created SKILL.md, check the YAML description: field:

1. Length ≤1024 chars: Anthropic's hard limit on description budget. Warning if violated (not blocker — content matters more than character count). Flag a description only for exceeding this limit, never for verbosity: its trigger keywords + what/when drive skill selection, so trimming them to save tokens degrades discovery.
2. Third person: description should read as "use when X" / "the skill does Y" — NOT "I will X" / "you should X". Check: grep for \b(I |my |me |you |your )\b in the description; if matches, flag as warning.
3. "Use when" trigger clause: description should include a phrase like "Use when …" / "Use for …" / "Trigger when …" — names the conditions that activate the skill. Required (warning if missing).
4. "Skip for" anti-trigger clause (recommended, not required): "Skip for X — use Y instead" — disambiguates against neighbor skills. Adds a recommendation note when missing; not a warning.
5. No {{placeholder}} patterns: residual template variables. Blocker if found.
6. Single line OR clean multi-line YAML: description must parse as valid YAML; check for unescaped quotes or unbalanced | > indicators that break frontmatter parsing. Blocker if YAML invalid.

Report results in the existing Phase 4 validation summary. Warnings do not block; blockers route to a fresh fix agent (max 1 round) per existing Phase 4 routing.

---

Mid-flow User Input

If the user interjects mid-phase: corrections/context fold into the current phase (note in checkpoint); preferences apply at the next decision point; blockers halt the phase and you ask how to proceed; new issues are noted and queued for after the current pipeline completes.

---

Anti-rationalization

Your reasoning	Why it's wrong
"I'll implement this multi-file change directly"	Changes touching 3+ files or any logic go through implementation subagents. Orchestrator coordinates, agents edit.
"The research is clear enough, skip cross-referencing"	Phase 2 exists because Phase 1 agents have no context about each other's findings. Cross-referencing catches contradictions and duplicates.
"The user will probably approve all, skip presenting"	Phase 3 is a WAIT gate. The user MUST see evidence and approve. No assumptions.
"I'll reuse the implementation agent for review"	Fresh agents avoid anchoring bias. The reviewer must NOT have seen the implementation prompt.
"I already know the answer from previous sessions"	Memory is context, not evidence. Verify against current file state before acting.
"I'll spawn agents one at a time"	All parallel agents MUST be spawned in ONE response — multiple Agent() calls in the same assistant turn. Separate turns = no concurrency, full wall-clock latency per agent.
"I'll add a note about the edge case"	Rewrite the original instruction to handle it explicitly. Separate notes create context distance and rot — the original must read correctly on its own.
"The change is too small to affect other skills"	Small changes to shared patterns (agent spawning syntax, phase structure, naming conventions) propagate through cross-references. The validation gate catches this — never skip it.
"The findings are obviously good, skip the redundancy check"	Phase 2b exists because orchestrator self-filtering inherits the researcher's framing. A fresh subagent greps the target file for existing instructions and flags over-engineering — catches what the proposer cannot see.
"I'll skip internet research because the request feels local"	Wrong unless the Matrix says skip. The triggers (new skill / new pattern / external API / abstract request) override your gut feel — internal-feeling requests can still introduce new patterns.
"I'll run all 3 research agents to be safe even though it's a typo fix"	The Matrix is mandatory both ways. Over-research wastes context and inflates Phase 2 with irrelevant findings the orchestrator must then filter.

Definition of Done

improve-existing-skill mode

• Mode Detection routed to improve-existing-skill (no create-skill triggers in $ARGUMENTS)
• Complexity gate applied (fast path or full pipeline)
• Phase 1: Research sources selected per Matrix; only those agents spawned (logged in state checkpoint)
• Phase 2: Findings cross-referenced and filtered to evidence-backed only
• Phase 2b: Redundancy & relevance validated orchestrator-inline
• Phase 3: Evidence table presented, user approved specific changes
• Phase 4: Changes implemented (subagents for multi-file, direct for trivial)
• Phase 4 Step 3 validation gate: 8 standard checks (line counts / outbound refs / inbound refs / YAML / pattern consistency / description-format meta / README+CLAUDE.md+docs sync / compaction-redundancy) PLUS 6 description-format sub-checks (length / third person / Use-when clause / Skip-for clause / no placeholders / valid YAML) for any changed SKILL.md
• Phase 5: Independent review by fresh agent passed
• Phase 6: Summary presented, state file cleaned up
• Phase 6: Commit & push offered to the user (Step 4)
• All changed SKILL.md files under 500 lines (preferred: ≤300 with companion files split)
• No scope creep beyond approved changes

create-skill mode

• Mode Detection routed to create-skill (explicit trigger OR named scope does not exist)
• Phase A: Skill kind asked (plugin-facing / project-local / plugin-internal helper)
• Phase A: Official Skills authoring docs fetched once and cached
• Phase A: 3-5 sequential AskUserQuestion calls completed (trigger / anti-trigger / inputs / outputs / tools / optional subagents / optional workflow)
• Phase A: Pre-existing-instruction check via generic Agent (sonnet) — overlap table reviewed; duplicates rejected, user routed to existing skill if overlap
• Phase B: Author agent spawned with interview transcript + constraints + 1-2 exemplar SKILL.md files; SKILL.md written to disk
• Phase B: Phase 4 Step 3 validation gate run including 6 description-format checks AND checks #7 (README/CLAUDE.md/docs sync) + #8 (compaction/redundancy) for any new top-level skill
• Phase C: Fresh review agent spawned; 8-item create-skill review checklist applied; blockers fixed (max 1 round)
• Phase D: Phase 6 Summary + Commit & push offered
• Created SKILL.md within the 500-line target / 700-line hard ceiling (Phase 4 Step 3 check #1); overflow split into companion reference files rather than trimmed