From f1a91991f06d2d4ac190222b37be97d25601009b Mon Sep 17 00:00:00 2001 From: Landung 'Don' Setiawan Date: Mon, 20 Apr 2026 14:01:51 -0700 Subject: [PATCH 1/5] chore(ai-research-workflows): mark research-workflow-management skill as private The skill exists to load templates and workflow guidance into the orchestrator agent; it is not intended to be invoked directly by users. Flipping user-invocable to false removes it from the user-facing skill index. Refs #93 --- .../skills/research-workflow-management/SKILL.md | 1 + 1 file changed, 1 insertion(+) diff --git a/plugins/ai-research-workflows/skills/research-workflow-management/SKILL.md b/plugins/ai-research-workflows/skills/research-workflow-management/SKILL.md index 4817c88..ccf1998 100644 --- a/plugins/ai-research-workflows/skills/research-workflow-management/SKILL.md +++ b/plugins/ai-research-workflows/skills/research-workflow-management/SKILL.md @@ -1,6 +1,7 @@ --- name: research-workflow-management description: Structured AI-enabled research workflows for software development. Covers the six-phase workflow (Research, Plan, Iterate Plan, Experiment, Implement, Validate) with templates for each phase. +user-invocable: false metadata: assets: - assets/research-template.md From 36cb76ec1fc21f65180f8130b9be0a7b5868a37d Mon Sep 17 00:00:00 2001 From: Landung 'Don' Setiawan Date: Mon, 20 Apr 2026 14:04:25 -0700 Subject: [PATCH 2/5] docs(ai-research-workflows): add retreat paths to failure-capable commands Every failure-capable command now documents where to go when it cannot produce a usable artifact. Maps failure modes to the next command (iterate-plan, plan, research, experiment, optimize) so users do not dead-end on first friction. Refs #93 --- .../ai-research-workflows/commands/experiment.md | 11 +++++++++++ plugins/ai-research-workflows/commands/implement.md | 11 +++++++++++ plugins/ai-research-workflows/commands/research.md | 13 ++++++++++++- plugins/ai-research-workflows/commands/validate.md | 12 ++++++++++++ 4 files changed, 46 insertions(+), 1 deletion(-) diff --git a/plugins/ai-research-workflows/commands/experiment.md b/plugins/ai-research-workflows/commands/experiment.md index ec6e5cc..544dd17 100644 --- a/plugins/ai-research-workflows/commands/experiment.md +++ b/plugins/ai-research-workflows/commands/experiment.md @@ -455,3 +455,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 ` | +| The experiment reveals the plan's assumptions are wrong | `/iterate-plan ` to update approach and success criteria | +| The experiment exposes missing context about the codebase | `/research ` 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 | diff --git a/plugins/ai-research-workflows/commands/implement.md b/plugins/ai-research-workflows/commands/implement.md index e231e3c..dc781be 100644 --- a/plugins/ai-research-workflows/commands/implement.md +++ b/plugins/ai-research-workflows/commands/implement.md @@ -387,3 +387,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 ` 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 | diff --git a/plugins/ai-research-workflows/commands/research.md b/plugins/ai-research-workflows/commands/research.md index b61b1b9..d551f9e 100644 --- a/plugins/ai-research-workflows/commands/research.md +++ b/plugins/ai-research-workflows/commands/research.md @@ -282,4 +282,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. \ No newline at end of file +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 ` 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 ` | +| Research surfaces the need for a structural change | Suggest `/plan ` | \ No newline at end of file diff --git a/plugins/ai-research-workflows/commands/validate.md b/plugins/ai-research-workflows/commands/validate.md index 3005d07..4544317 100644 --- a/plugins/ai-research-workflows/commands/validate.md +++ b/plugins/ai-research-workflows/commands/validate.md @@ -465,3 +465,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 ` to finish the missing work | +| Conformance fails: the implementation matches reality but the plan is wrong | `/iterate-plan ` 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 ` if present (v0.2.0 PR7+) — otherwise file follow-ups; do not expand scope in place | From bfe3f108f951849a2a2385e957b4694600e4ba1b Mon Sep 17 00:00:00 2001 From: Landung 'Don' Setiawan Date: Mon, 20 Apr 2026 14:56:21 -0700 Subject: [PATCH 3/5] docs(ai-research-workflows): add CSO 'When to use' trigger sections to every command MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Each command now carries its own trigger list at the top, migrated from the orchestrator's per-command guidance blocks. This makes commands discoverable and usable without routing through the orchestrator, and sets up the orchestrator trim in a follow-up commit. The /handoff section is authored fresh — no prior orchestrator block existed for it. Refs #93 --- .../commands/experiment.md | 20 ++++++++++++++++ .../ai-research-workflows/commands/handoff.md | 17 +++++++++++++ .../commands/implement.md | 21 ++++++++++++++++ .../commands/iterate-plan.md | 24 +++++++++++++++++++ .../ai-research-workflows/commands/plan.md | 22 +++++++++++++++++ .../commands/research.md | 19 +++++++++++++++ .../commands/validate.md | 18 ++++++++++++++ 7 files changed, 141 insertions(+) diff --git a/plugins/ai-research-workflows/commands/experiment.md b/plugins/ai-research-workflows/commands/experiment.md index 544dd17..1fd1b81 100644 --- a/plugins/ai-research-workflows/commands/experiment.md +++ b/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: diff --git a/plugins/ai-research-workflows/commands/handoff.md b/plugins/ai-research-workflows/commands/handoff.md index e5a669c..cf413f2 100644 --- a/plugins/ai-research-workflows/commands/handoff.md +++ b/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. diff --git a/plugins/ai-research-workflows/commands/implement.md b/plugins/ai-research-workflows/commands/implement.md index dc781be..7054f08 100644 --- a/plugins/ai-research-workflows/commands/implement.md +++ b/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: diff --git a/plugins/ai-research-workflows/commands/iterate-plan.md b/plugins/ai-research-workflows/commands/iterate-plan.md index 93d0d8f..1205eba 100644 --- a/plugins/ai-research-workflows/commands/iterate-plan.md +++ b/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. diff --git a/plugins/ai-research-workflows/commands/plan.md b/plugins/ai-research-workflows/commands/plan.md index b427c80..f078342 100644 --- a/plugins/ai-research-workflows/commands/plan.md +++ b/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 ` 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: diff --git a/plugins/ai-research-workflows/commands/research.md b/plugins/ai-research-workflows/commands/research.md index d551f9e..4d2b031 100644 --- a/plugins/ai-research-workflows/commands/research.md +++ b/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: diff --git a/plugins/ai-research-workflows/commands/validate.md b/plugins/ai-research-workflows/commands/validate.md index 4544317..6cfe331 100644 --- a/plugins/ai-research-workflows/commands/validate.md +++ b/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: From 9e7c0358dc30505cc4bc77c1186f9899d823d96c Mon Sep 17 00:00:00 2001 From: Landung 'Don' Setiawan Date: Mon, 20 Apr 2026 15:06:28 -0700 Subject: [PATCH 4/5] refactor(ai-research-workflows): trim orchestrator's per-command guidance MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Each command now owns its own 'When to use' section after the previous commit. The orchestrator no longer duplicates trigger logic — it points to the command files and retains its real responsibilities: routing, workflow-state tracking, and retreat-path decisions. Net: orchestrator shrinks by roughly 80-90 lines. Sets up the structural refactor in #87. Refs #93 --- .../agents/research-workflow-orchestrator.md | 103 ++---------------- 1 file changed, 11 insertions(+), 92 deletions(-) diff --git a/plugins/ai-research-workflows/agents/research-workflow-orchestrator.md b/plugins/ai-research-workflows/agents/research-workflow-orchestrator.md index 1414e57..3077cef 100644 --- a/plugins/ai-research-workflows/agents/research-workflow-orchestrator.md +++ b/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 From 473f09f3ca08221826fed0e2b0a8a75f55be97c3 Mon Sep 17 00:00:00 2001 From: Landung 'Don' Setiawan Date: Wed, 22 Apr 2026 13:45:29 -0700 Subject: [PATCH 5/5] refactor(ai-research-workflows): slim research-workflow-management skill per Tessl review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Address Tessl skill review findings (35% → targeting higher): - Cut Workflow Philosophy, Integration, Common Patterns sections - Collapse verbose 'When to Use Each Step' into decision tree (commands already carry per-command triggers) - Add concrete command syntax examples with real arguments and resulting artifact paths - Add Success Criteria Automated/Manual split with executable verification command examples - Move per-phase checklists to references/checklists.md for progressive disclosure SKILL.md trimmed from ~2000 to ~620 words. --- .../research-workflow-management/SKILL.md | 296 +++++------------- .../references/checklists.md | 69 ++++ 2 files changed, 152 insertions(+), 213 deletions(-) create mode 100644 plugins/ai-research-workflows/skills/research-workflow-management/references/checklists.md diff --git a/plugins/ai-research-workflows/skills/research-workflow-management/SKILL.md b/plugins/ai-research-workflows/skills/research-workflow-management/SKILL.md index ccf1998..b1b3cca 100644 --- a/plugins/ai-research-workflows/skills/research-workflow-management/SKILL.md +++ b/plugins/ai-research-workflows/skills/research-workflow-management/SKILL.md @@ -1,6 +1,6 @@ --- name: research-workflow-management -description: Structured AI-enabled research workflows for software development. Covers the six-phase workflow (Research, Plan, Iterate Plan, Experiment, Implement, Validate) with templates for each phase. +description: Orchestration skill for the six-phase AI research workflow (Research → Plan → Iterate → Experiment → Implement → Validate). Loaded by the research-workflow-orchestrator agent to select the next workflow command, enforce `.agents/` naming, and wire cross-references between phase documents. user-invocable: false metadata: assets: @@ -13,252 +13,122 @@ metadata: # Research Workflow Management -A structured, AI-enabled workflow for software development that guides you from initial research through to validated implementation. This skill provides a systematic approach to complex development tasks through distinct, well-defined phases. +Orchestrates six slash commands into a single auditable workflow. Each phase produces a markdown artifact under `.agents/` that the next phase consumes. -## Workflow Overview +## Phase → Command → Artifact -The research workflow consists of six phases: +| Phase | Command | Input | Artifact | +|-------|---------|-------|----------| +| Research | `/research ` | topic string | `.agents/research-.md` | +| Plan | `/plan ` | feature name | `.agents/plan-.md` | +| Iterate Plan | `/iterate-plan ` | existing plan + edit brief | edits plan in place | +| Experiment | `/experiment ` | approach question | `.agents/experiment-.md` | +| Implement | `/implement ` | approved plan path | `.agents/implement-.md` | +| Validate | `/validate ` | plan path | inline validation report | -1. **Research** (`/research`) — Document and understand existing code, patterns, and architecture -2. **Plan** (`/plan`) — Create detailed, testable implementation plans through interactive research -3. **Iterate Plan** (`/iterate-plan`) — Refine existing plans based on feedback or changed requirements -4. **Experiment** (`/experiment`) — Try multiple approaches before committing (optional) -5. **Implement** (`/implement`) — Execute the plan phase by phase with verification -6. **Validate** (`/validate`) — Systematically verify implementation against plan criteria +Slugs are lowercased-hyphenated from the argument: `/research "Auth System"` → `research-auth-system.md`. -Each phase produces a structured markdown document saved to `.agents/` in your project root, creating an auditable trail of technical decisions and implementation details. - -## Quick Reference Card - -Use this decision tree to choose which workflow step to run: +## Decision Tree — Which Command Next ``` Need to understand existing code? -└─> Research + → /research Ready to design an implementation? -├─> Have research docs? -│ └─> Plan (references research automatically) -└─> No research docs? - └─> Run Research first, then Plan + ├─ research docs already exist? + │ → /plan + └─ no research? + → /research first, then /plan -Need to adjust an existing plan? -└─> Iterate Plan +Plan exists but needs edits? + → /iterate-plan .agents/plan-.md "" -Uncertain about the best approach? -└─> Experiment +Uncertain which approach wins? + → /experiment "" -Ready to execute the plan? -└─> Implement +Plan is approved? + → /implement .agents/plan-.md -Implementation complete, need verification? -└─> Validate +Implementation claimed complete? + → /validate .agents/plan-.md ``` -## Document Naming Convention +Command-level trigger details live in each command file's `## When to use` section — do not duplicate them here. + +## Concrete Command Examples + +```bash +# 1. Build context on an unfamiliar subsystem +/research "How does the auth middleware verify session tokens" +# → .agents/research-how-does-the-auth-middleware-verify-session-tokens.md + +# 2. Plan a feature that builds on that research +/plan "Add OAuth2 provider to auth system" +# → .agents/plan-add-oauth2-provider-to-auth-system.md -All workflow documents are saved to `.agents/` with this naming pattern: +# 3. Adjust the plan after review feedback +/iterate-plan .agents/plan-add-oauth2-provider-to-auth-system.md \ + "Split Phase 2 into token-exchange and refresh-flow subphases" -- `research-.md` — Example: `research-auth-system.md` -- `plan-.md` — Example: `plan-auth-system.md` -- `experiment-.md` — Example: `experiment-jwt-vs-session.md` -- `implement-.md` — Example: `implement-auth-system.md` +# 4. Compare approaches when the plan is ambiguous +/experiment "JWT in HttpOnly cookie vs Bearer header for SPA clients" -The slug is automatically derived from the command argument (lowercased and hyphenated). +# 5. Execute the approved plan +/implement .agents/plan-add-oauth2-provider-to-auth-system.md -**Note:** The `/iterate-plan` command edits existing plan documents in place. The `/validate` command produces inline validation reports rather than templated documents. +# 6. Verify the implementation against plan criteria +/validate .agents/plan-add-oauth2-provider-to-auth-system.md +``` + +## Cross-Referencing Rules -## Cross-Referencing Between Steps +Every artifact links back to the artifacts that informed it. Use relative markdown links inside `.agents/`: -Workflow phases build on each other through explicit references: +- **Plan docs** include a `## References` section listing every research doc consulted +- **Experiment docs** reference both the research and the plan that motivated them +- **Implement docs** reference the exact plan file being executed +- **Validation reports** reference both the plan and the implement doc -- **Plan documents** include a `## References` section listing research docs consulted -- **Experiment documents** reference both research and plan docs that inform the experiments -- **Implement documents** reference the specific plan being executed -- **Validation reports** reference both the plan and the implementation document +Example (inside `plan-auth-system.md`): -Each document uses relative links to referenced docs: ```markdown -[Research: Auth System](research-auth-system.md) -[Plan: Auth System Implementation](plan-auth-system.md) +## References + +- [Research: Auth System](research-auth-system.md) +- [Research: Session Storage](research-session-storage.md) ``` -This creates a navigable graph of technical decisions and their implementation. +This creates a navigable graph: every claim in any document traces back to the research that supports it. -## When to Use Each Step +## Success Criteria Format -### Research — Use when you need to: -- Understand how existing code works -- Document architecture patterns in the codebase -- Find where specific functionality lives -- Map out component interactions -- Build context before planning changes -- Answer technical questions about the codebase - -**Output:** A comprehensive technical document explaining the current state with file references and architecture insights. - -**Key principle:** Document what IS, not what SHOULD BE. You are a technical documentarian, not a critic. - -### Plan — Use when you need to: -- Design a new feature implementation -- Plan a refactoring or architectural change -- Create a roadmap for complex multi-file changes -- Define success criteria and testing strategy -- Get stakeholder buy-in before implementation - -**Output:** A detailed, phased implementation plan with measurable success criteria, specific file references, and testing strategy. - -**Key principle:** Interactive and iterative. Ask questions, research patterns, get feedback at each stage before finalizing. - -### Iterate Plan — Use when you need to: -- Adjust scope based on new requirements -- Add or remove phases from an existing plan -- Update success criteria after discoveries -- Refine implementation approach -- Fix issues found during planning review +Plans must split success criteria into two groups so `/validate` can execute the automated half: -**Output:** Updated plan document with surgical edits maintaining consistency. +```markdown +## Success Criteria -**Key principle:** Verify assumptions with code research. Confirm understanding before making changes. +### Automated +- [ ] `pytest tests/auth/` passes +- [ ] `ruff check src/auth/` reports zero errors +- [ ] `mypy src/auth/` reports zero errors -### Experiment — Use when you need to: -- Compare 2-3 distinct technical approaches -- Prototype before committing to a design -- Validate performance characteristics -- Test integration patterns with existing code -- Make evidence-based architectural decisions +### Manual +- [ ] Login flow works end-to-end in staging +- [ ] Session persists across browser restart +``` -**Output:** Comparative analysis with code prototypes, observations, and a clear recommendation. +`/validate` runs each Automated command verbatim and records pass/fail with output; it lists Manual items for the human to confirm. -**Key principle:** Actually run code. Don't theorize — test real implementations and record honest observations. +## Templates -**Note:** This step is OPTIONAL. Only use when the best approach is genuinely uncertain. +Templates live in `${CLAUDE_PLUGIN_ROOT}/skills/research-workflow-management/assets/`. Commands load them directly — do not inline template content into this skill. -### Implement — Use when you need to: -- Execute an approved plan phase by phase -- Track implementation progress with checkmarks -- Verify work against success criteria -- Pause for manual verification between phases -- Create an auditable implementation record +- `research-template.md` +- `plan-template.md` +- `experiment-template.md` +- `implement-template.md` +- `handoff-template.md` -**Output:** Working implementation with updated plan checkmarks and an implementation summary document. - -**Key principle:** Follow the plan's intent while adapting to reality. Communicate mismatches clearly. - -### Validate — Use when you need to: -- Verify implementation matches the plan -- Run all automated verification checks -- Identify what needs manual testing -- Catch incomplete or incorrect implementations -- Generate a validation report for review - -**Output:** Comprehensive validation report showing pass/fail status for each success criterion. - -**Key principle:** Systematic and thorough. Validate what was actually built, not what was intended. +## Additional Resources -## Best Practices Checklist - -### Research Phase -- [ ] Read referenced files completely (full file reads) -- [ ] Use parallel research when possible for comprehensive exploration -- [ ] Include specific file paths and line numbers -- [ ] Document patterns, not problems -- [ ] Save to `.agents/research-.md` - -### Planning Phase -- [ ] Reference existing research documents -- [ ] Read all context files completely before delegating sub-tasks -- [ ] Ask focused questions that can't be answered from code -- [ ] Include measurable success criteria split into Automated and Manual -- [ ] Define "what we're NOT doing" -- [ ] Get feedback before finalizing each section -- [ ] Resolve ALL open questions before completing the plan -- [ ] Save to `.agents/plan-.md` - -### Experimentation Phase (Optional) -- [ ] Define clear hypothesis and success criteria -- [ ] Actually run code prototypes, don't just theorize -- [ ] Record all observations, including failures -- [ ] Create honest comparison with trade-offs -- [ ] Make a clear recommendation with reasoning -- [ ] Save to `.agents/experiment-.md` - -### Implementation Phase -- [ ] Read the plan and all referenced files completely -- [ ] Create a task list to track progress -- [ ] Implement phases sequentially, not in parallel -- [ ] Update plan checkmarks as you complete sections -- [ ] Run automated verification after each phase -- [ ] Pause for human verification between phases -- [ ] Stop and communicate if reality doesn't match the plan -- [ ] Save to `.agents/implement-.md` on completion - -### Validation Phase -- [ ] Read the plan completely -- [ ] Verify each phase's completion status -- [ ] Run all automated verification commands from the plan -- [ ] Document pass/fail status for each check -- [ ] List clear manual testing steps -- [ ] Identify deviations from the plan -- [ ] Provide actionable recommendations - -## Template Assets - -This skill provides four document templates in `${CLAUDE_PLUGIN_ROOT}/skills/research-workflow-management/assets/`: - -- `research-template.md` — Structure for research documentation -- `plan-template.md` — Structure for implementation plans -- `experiment-template.md` — Structure for experiment reports -- `implement-template.md` — Structure for implementation summaries - -Commands automatically use these templates when generating workflow documents. - -## Workflow Philosophy - -This structured approach provides several benefits: - -1. **Separation of concerns** — Research, planning, and implementation are distinct activities with different goals -2. **Incremental progress** — Each phase produces concrete artifacts that can be reviewed independently -3. **Reduced cognitive load** — Focus on one type of work at a time rather than trying to do everything simultaneously -4. **Better collaboration** — Documents provide clear communication artifacts for stakeholders -5. **Auditable decisions** — Technical choices are documented with their context and reasoning -6. **Reduced rework** — Issues are caught during planning rather than after implementation - -The workflow is designed to be flexible — you can skip optional phases like experimentation or iterate on plans as requirements evolve. The key is maintaining clear documentation of what was built and why. - -## Common Workflow Patterns - -### Pattern 1: Simple Feature Addition -1. Research existing patterns -2. Plan new feature -3. Implement plan - -### Pattern 2: Complex Architectural Change -1. Research current architecture -2. Plan architectural change -3. Experiment with approach comparison -4. Iterate plan to incorporate experiment results -5. Implement plan -6. Validate plan - -### Pattern 3: Rapid Iteration -1. Plan initial approach -2. Iterate plan for scope adjustment -3. Iterate plan to add phase -4. Implement plan - -### Pattern 4: Investigation + Documentation -1. Research system behavior -2. Research related component (follow-up) -3. Use research docs for future planning - -## Integration with Other Workflows - -This workflow integrates seamlessly with standard development practices: - -- **After implementation**: Create a git commit with your changes -- **After validation passes**: Create a pull request for review -- **During planning**: Reference existing documentation and code patterns -- **During research**: Use available code exploration tools - -The structured workflow complements rather than replaces your existing development process. +- **`references/checklists.md`** — Full per-phase quality-gate checklists. Load when executing a phase and needing a complete pre-commit checklist. diff --git a/plugins/ai-research-workflows/skills/research-workflow-management/references/checklists.md b/plugins/ai-research-workflows/skills/research-workflow-management/references/checklists.md new file mode 100644 index 0000000..8eb343e --- /dev/null +++ b/plugins/ai-research-workflows/skills/research-workflow-management/references/checklists.md @@ -0,0 +1,69 @@ +# Per-Phase Checklists + +Detailed checklists for each workflow phase. Load when executing a specific phase and needing a complete quality gate. + +## Research Phase (`/research`) + +- [ ] Read referenced files completely (no partial reads) +- [ ] Use parallel sub-agents when exploring >2 independent areas +- [ ] Include specific file paths and line numbers (`path/to/file.py:42`) +- [ ] Document patterns and current behavior, not critiques +- [ ] Save to `.agents/research-.md` + +**Verification:** `test -f .agents/research-.md && grep -q '^## ' .agents/research-.md` + +## Plan Phase (`/plan`) + +- [ ] Reference existing research docs in `## References` section +- [ ] Read all context files completely before delegating sub-tasks +- [ ] Ask focused questions that cannot be answered from code alone +- [ ] Split success criteria into **Automated** (commands) and **Manual** (human checks) +- [ ] Include `## What We're NOT Doing` section +- [ ] Resolve every open question before marking the plan complete +- [ ] Save to `.agents/plan-.md` + +**Verification:** Confirm plan contains `## Success Criteria`, `## Phases`, and `## What We're NOT Doing`. + +## Iterate Plan Phase (`/iterate-plan`) + +- [ ] Verify assumptions with code research before editing +- [ ] Confirm understanding with user before applying changes +- [ ] Preserve existing phase numbering and cross-references +- [ ] Edit the plan in place, not as a new file + +## Experiment Phase (`/experiment`, optional) + +- [ ] State hypothesis and success criteria up front +- [ ] Actually run prototype code — no pure theorizing +- [ ] Record failures alongside successes +- [ ] Produce a comparison table with trade-offs +- [ ] End with a single recommendation and reasoning +- [ ] Save to `.agents/experiment-.md` + +## Implement Phase (`/implement`) + +- [ ] Read the plan and all referenced files completely +- [ ] Create a task list mirroring the plan's phases +- [ ] Implement phases sequentially (never in parallel) +- [ ] Update plan checkmarks (`[ ]` → `[x]`) as sections complete +- [ ] Run the plan's automated verification commands after each phase +- [ ] Pause for human verification between phases +- [ ] Stop and flag any divergence between plan and reality +- [ ] Save implementation summary to `.agents/implement-.md` + +## Validate Phase (`/validate`) + +- [ ] Read the plan completely before running checks +- [ ] Execute every automated verification command listed in the plan +- [ ] Record pass/fail for each Success Criteria item with command output +- [ ] List manual testing steps the user must run +- [ ] Identify and flag deviations from the plan +- [ ] Provide actionable next steps (iterate, fix, or ship) + +**Verification commands typically include:** +- `` — e.g. `pytest tests/`, `npm test`, `cargo test` +- `` — e.g. `ruff check .`, `eslint src/` +- `` — e.g. `mypy .`, `tsc --noEmit` +- `` — e.g. `npm run build`, `cargo build --release` + +The specific commands come from the plan's Success Criteria section, not this skill.