chore(ai-research-workflows): v0.2.0 prep — command triggers, retreat paths, private skill

plugins/ai-research-workflows/agents/research-workflow-orchestrator.md

@@ -125,98 +125,17 @@ Each phase has a dedicated command (e.g., `/research`, `/plan`, `/implement`) th
 
 # Core Decision-Making Framework
 
-## When to Suggest Research (`/research`)
-
-Suggest research when:
-- User wants to understand existing code
-- User asks "how does X work?"
-- Planning a change and context about current implementation is missing
-- Need to document architecture or patterns
-- Building knowledge base for future work
-
-**Example triggers:**
-- "How does authentication work?"
-- "Where is the payment processing logic?"
-- "I need to understand the API architecture"
-
-## When to Suggest Planning (`/plan`)
-
-Suggest planning when:
-- User wants to implement a new feature
-- User describes a change requiring multiple files
-- User wants to refactor or redesign something
-- Implementation approach needs thought and structure
-
-**Check if research exists first:**
-- Look in `.agents/` for relevant `research-*.md` files
-- If found, reference them in planning
-- If missing and would be valuable, suggest researching first
-
-**Example triggers:**
-- "Add OAuth support"
-- "Refactor the database layer"
-- "Implement user notifications"
-
-## When to Suggest Plan Iteration (`/iterate-plan`)
-
-Suggest iteration when:
-- User wants to adjust an existing plan
-- Requirements have changed
-- Experiment results need to be incorporated
-- Plan needs scope adjustment or phase restructuring
-
-**Example triggers:**
-- "Let's not implement email notifications yet"
-- "Add a phase for database migration"
-- "Update the plan based on the experiment results"
-
-## When to Suggest Experimentation (`/experiment`)
-
-Suggest experimentation when:
-- User is genuinely uncertain about the best approach
-- Multiple valid technical solutions exist
-- Performance or integration characteristics are unknown
-- Architectural decision has significant trade-offs
-
-**Don't suggest for:**
-- Obvious decisions
-- Approaches already used in codebase
-- Low-risk choices
-
-**Example triggers:**
-- "Should I use JWT or sessions?"
-- "Which caching strategy is better?"
-- "How should we structure the microservices?"
-
-## When to Suggest Implementation (`/implement`)
-
-Suggest implementation when:
-- A plan exists and is approved
-- User says they're ready to implement
-- Plan has been iterated to satisfaction
-
-**Check first:**
-- Does a plan exist?
-- Is it in `.agents/` directory?
-- Has it been reviewed?
-
-**Example triggers:**
-- "Let's implement the plan"
-- "I'm ready to start coding"
-- "Execute the OAuth plan"
-
-## When to Suggest Validation (`/validate`)
-
-Suggest validation when:
-- Implementation is complete (or claimed complete)
-- User wants to verify correctness
-- Tests are failing and systematic review is needed
-- Before creating a pull request
-
-**Example triggers:**
-- "Is the implementation correct?"
-- "Verify the implementation matches the plan"
-- "Some tests are failing"
+Each command file now owns its own `## When to use` section. When a user's request arrives, consult the relevant command file for authoritative trigger guidance:
+
+- `/research` — `commands/research.md`
+- `/plan` — `commands/plan.md`
+- `/iterate-plan` — `commands/iterate-plan.md` (floating utility — reachable from any phase)
+- `/experiment` — `commands/experiment.md`
+- `/implement` — `commands/implement.md`
+- `/validate` — `commands/validate.md`
+- `/handoff` — `commands/handoff.md`
+
+This agent's job is to **route** between commands and track workflow state (which artifacts exist in `.agents/`, what phase the user is in, which retreat paths apply) — not to duplicate per-command trigger logic.
 
 # Key Preferences
 

plugins/ai-research-workflows/commands/experiment.md

@@ -17,6 +17,26 @@ This step is OPTIONAL in the workflow — only use when the best approach is gen
 - Every solution has downsides
 - Document both successes and failures
 
+## When to use
+
+Invoke `/experiment` when:
+
+- The user is genuinely uncertain about the best technical approach
+- Multiple valid solutions exist with real trade-offs
+- Performance or integration characteristics are unknown
+- An architectural decision has significant trade-offs worth measuring
+
+**Example triggers:**
+- "Should I use JWT or sessions?"
+- "Which caching strategy is better?"
+- "How should we structure the microservices?"
+
+**Do not invoke `/experiment`** for:
+- Decisions that are obvious from existing codebase patterns
+- Low-risk choices where being wrong is cheap
+- Preference questions dressed up as uncertainty
+- End-to-end feasibility questions — those are `/prototype` (v0.2.0+)
+
 # Initial Setup
 
 When this command is invoked:
@@ -455,3 +475,14 @@ Before completing experimentation, verify:
 - [ ] Code snippets include file paths or locations
 
 Remember: Good experiments provide evidence for decisions. They trade short-term investment for long-term confidence.
+
+# Retreat Paths
+
+If experimentation cannot produce a defensible recommendation, do not invent one — retreat.
+
+| If this happens | Go to |
+|---|---|
+| None of the tested approaches meet the success criteria | `/plan` (revisit requirements) or `/research <missing-context>` |
+| The experiment reveals the plan's assumptions are wrong | `/iterate-plan <plan-file>` to update approach and success criteria |
+| The experiment exposes missing context about the codebase | `/research <topic>` first, then re-run `/experiment` with that context |
+| The trade-offs are genuinely tied; no approach dominates | Report the tie honestly and ask the user to choose based on product priorities |

plugins/ai-research-workflows/commands/handoff.md

@@ -3,6 +3,23 @@ description: Create a handoff document to transfer work context to another sessi
 user-invocable: true
 ---
 
+## When to use
+
+Invoke `/handoff` when:
+
+- The current session will end (timebox, context limit, end of workday) and work is not complete
+- You want another session or contributor to resume the same work without losing context
+- A long-running workflow has paused between phases and needs a clean restart point
+
+**Example triggers:**
+- "Create a handoff so I can resume tomorrow"
+- "Summarize context for the next session"
+- "I'm running low on context — hand off to a new conversation"
+
+**Do not invoke `/handoff`** for:
+- Completed work that needs documentation — use `/implement` or `/validate` outputs, or a standard commit message
+- Work that fits in the current session with no resume step needed
+
 # Create Handoff
 
 You are tasked with writing a handoff document to transfer your work context to another agent in a new session. The handoff must be **thorough but concise** — compact and summarize your context without losing key details of what you're working on.

plugins/ai-research-workflows/commands/implement.md

@@ -3,6 +3,27 @@ description: Implement changes based on an approved plan, tracking progress phas
 user-invocable: true
 ---
 
+## When to use
+
+Invoke `/implement` when:
+
+- An approved plan exists in `.agents/plan-*.md`
+- The plan has been reviewed (iterated as needed) and the user is ready to execute
+- Manual verification between phases is acceptable
+
+**Check first:**
+- Does a plan file exist? If not, run `/plan` first.
+- Has it been reviewed? If substantive changes are pending, run `/iterate-plan` first.
+
+**Example triggers:**
+- "Let's implement the plan"
+- "I'm ready to start coding"
+- "Execute the OAuth plan"
+
+**Do not invoke `/implement`** for:
+- Exploratory "let me try something" work — use `/experiment` or `/prototype` (v0.2.0+)
+- Plans with open questions or unresolved decisions
+
 # Getting Started
 
 When this command is invoked with a plan path or reference:
@@ -387,3 +408,14 @@ Before marking implementation as complete:
 - **Focus on one phase at a time** — Complete fully before moving on
 
 Good implementation balances faithfulness to the plan with responsiveness to reality. When in doubt, communicate.
+
+# Retreat Paths
+
+If implementation hits a blocker the existing plan cannot resolve, stop and retreat — do not improvise silently.
+
+| If this happens | Go to |
+|---|---|
+| Plan does not match the current codebase (files moved, APIs changed) | STOP; use `/iterate-plan <plan-file>` to update references and re-approve |
+| An automated verification check fails and the fix is outside the phase's scope | STOP; use `/iterate-plan` to adjust scope or success criteria |
+| Implementation reveals a better approach that changes the plan's architecture | STOP; use `/iterate-plan`, or `/experiment` if uncertainty is high |
+| A phase takes dramatically longer than the plan anticipated | Pause; use `/iterate-plan` to split the phase |

plugins/ai-research-workflows/commands/iterate-plan.md

@@ -3,6 +3,30 @@ description: Update an existing implementation plan based on feedback
 user-invocable: true
 ---
 
+## When to use
+
+`/iterate-plan` is a **floating utility** — it can be invoked from any point in the workflow, not just after `/plan`.
+
+Invoke `/iterate-plan` when:
+
+- Scope needs to change (adding or removing features)
+- A phase needs to be split, merged, or reordered
+- Research, experiment, or validate findings require plan updates
+- Success criteria need to be adjusted
+- An `/implement` run hit a plan-vs-reality mismatch
+- A `/validate` run flagged a conformance or empirical failure
+- An `/optimize` run (v0.2.0+) surfaced out-of-scope issues
+
+**Example triggers:**
+- "Let's not implement email notifications yet"
+- "Add a phase for database migration"
+- "Update the plan based on the experiment results"
+- "The validate report found we missed Phase 2; fix the plan"
+
+**Do not invoke `/iterate-plan`** for:
+- A plan that does not yet exist — use `/plan` first
+- Cosmetic rewrites with no substantive change
+
 # Initial Response
 
 When this command is invoked, parse the input to identify the plan file path and requested changes.

plugins/ai-research-workflows/commands/plan.md

@@ -3,6 +3,28 @@ description: Create a detailed implementation plan through interactive research
 user-invocable: true
 ---
 
+## When to use
+
+Invoke `/plan` when:
+
+- The user wants to implement a new feature
+- The user describes a change that touches multiple files
+- The user wants to refactor or redesign something
+- The implementation approach needs structure before code is written
+
+**Check first:**
+- Does relevant research already exist in `.agents/research-*.md`? If so, reference it.
+- If research is missing and would be valuable, suggest `/research <topic>` first.
+
+**Example triggers:**
+- "Add OAuth support"
+- "Refactor the database layer"
+- "Implement user notifications"
+
+**Do not invoke `/plan`** for:
+- Single-file, single-line bug fixes
+- Tasks with no architectural ambiguity (just implement)
+
 # Initial Response
 
 When this command is invoked, determine what context you have:

plugins/ai-research-workflows/commands/research.md

@@ -14,6 +14,25 @@ YOUR ONLY JOB IS TO DOCUMENT AND EXPLAIN THE CODEBASE AS IT EXISTS TODAY.
 
 You and all sub-agents are documentarians, not evaluators. Document what IS, not what SHOULD BE.
 
+## When to use
+
+Invoke `/research` when:
+
+- The user wants to understand existing code
+- The user asks "how does X work?"
+- Context about current implementation is missing and would be valuable for planning
+- Architecture or patterns need to be documented
+- You are building a knowledge base for future work
+
+**Example triggers:**
+- "How does authentication work?"
+- "Where is the payment processing logic?"
+- "I need to understand the API architecture"
+
+**Do not invoke `/research`** for:
+- Questions answered by a single file read (just read it)
+- Evaluative questions ("is this design good?") — that is `/plan` or `/experiment` territory
+
 # Initial Setup
 
 When this command is invoked:
@@ -282,4 +301,15 @@ Before completing research, verify:
 - [ ] Document is self-contained and readable independently
 - [ ] Task list is updated to show completion
 
-Remember: Your job is to illuminate how the codebase works TODAY, not to suggest how it should work tomorrow.
+Remember: Your job is to illuminate how the codebase works TODAY, not to suggest how it should work tomorrow.
+
+# Retreat Paths
+
+If research stalls or its results cannot support the next workflow step, do not force a document — retreat to a more appropriate command instead.
+
+| If this happens | Go to |
+|---|---|
+| Topic is too broad; findings are shallow or contradictory | Re-run `/research <narrower-topic>` or ask the user to narrow scope |
+| The code you need to document does not yet exist | Stop research; suggest `/plan` first, then revisit research once the code lands |
+| Research reveals genuine approach uncertainty | Suggest `/experiment <approach A vs approach B>` |
+| Research surfaces the need for a structural change | Suggest `/plan <change>` |

plugins/ai-research-workflows/commands/validate.md

@@ -3,6 +3,24 @@ description: Validate that an implementation was correctly executed against its
 user-invocable: true
 ---
 
+## When to use
+
+Invoke `/validate` when:
+
+- An implementation is complete (or claimed complete) and needs systematic verification
+- You are preparing to create a pull request and want to catch issues first
+- Tests are failing and a structured review of plan-vs-implementation is needed
+- You are resuming old work and need to know its current state
+
+**Example triggers:**
+- "Is the implementation correct?"
+- "Verify the implementation matches the plan"
+- "Some tests are failing"
+
+**Do not invoke `/validate`** for:
+- Work that has not yet been implemented
+- Code review tasks unrelated to a plan (use a general code-review command)
+
 # Initial Setup
 
 When this command is invoked:
@@ -465,3 +483,15 @@ FAILED tests/test_auth.py::test_token_refresh - TimeoutError: Token refresh time
 - **Be honest** — Document problems even if they're inconvenient
 
 Good validation catches issues before they reach production. It's worth the time investment.
+
+# Retreat Paths
+
+Validation is a diagnostic step — when it fails, it routes work back to earlier phases rather than forcing fixes in place.
+
+| If this happens | Go to |
+|---|---|
+| Conformance fails: claimed work is not actually done | `/implement <plan-file>` to finish the missing work |
+| Conformance fails: the implementation matches reality but the plan is wrong | `/iterate-plan <plan-file>` to correct the plan |
+| Automated verification commands from the plan do not run (env/setup issues) | Fix the environment; do not silently skip checks |
+| Empirical validation against real data fails (v0.2.0+ mode) | `/iterate-plan` to revise approach or success criteria |
+| Validation surfaces large amounts of new, unplanned cleanup work | `/optimize <validate-doc>` if present (v0.2.0 PR7+) — otherwise file follow-ups; do not expand scope in place |