diff --git a/e2e/README.md b/e2e/README.md index 88bd8536..abba176c 100644 --- a/e2e/README.md +++ b/e2e/README.md @@ -40,6 +40,13 @@ graph TD | Publish | `/publish` | Push branch, create draft PR | `06-pr-description.md` | | Respond | `/respond` | Address reviewer comments | `07-review-responses.md` | +Each phase command invokes `skills/dispatch.md` with the requested phase. The +dispatcher resolves any project override, loads only that phase, and passes +along the command context. After the phase reports its result, +`skills/completion.md` supplies the shared next-step guidance without loading +the full controller. The controller remains the entry point for workflow +discovery and ambiguous requests. + ## Typical Flow ```text @@ -143,7 +150,9 @@ e2e/ ├── guidelines.md # Behavioral rules and guardrails ├── README.md # This file ├── skills/ -│ ├── controller.md # Phase dispatcher and transitions +│ ├── controller.md # Discovery and ambiguous-input router +│ ├── dispatch.md # Explicit-phase dispatcher +│ ├── completion.md # Shared next-step guidance │ ├── ingest.md # Fetch story, explore e2e infrastructure │ ├── plan.md # Map ACs to test scenarios │ ├── revise.md # Incorporate plan feedback diff --git a/e2e/SKILL.md b/e2e/SKILL.md index f097b15c..3fd17b10 100644 --- a/e2e/SKILL.md +++ b/e2e/SKILL.md @@ -1,6 +1,6 @@ --- name: e2e -version: 0.6.1 +version: 0.7.0 description: >- Story-to-e2e-test workflow that takes a Jira [QE] Story, discovers the project's e2e testing infrastructure, plans test scenarios, writes e2e diff --git a/e2e/commands/code.md b/e2e/commands/code.md index e5c5f455..f76808c9 100644 --- a/e2e/commands/code.md +++ b/e2e/commands/code.md @@ -4,8 +4,8 @@ description: "Write e2e test code following discovered patterns, committing incr --- # /code -Read `../skills/controller.md` and follow it. +Read `../skills/dispatch.md` and follow it with `PHASE=code`. -Dispatch the **code** phase. Context: +Context: $ARGUMENTS diff --git a/e2e/commands/ingest.md b/e2e/commands/ingest.md index 52f143f1..ff5e013f 100644 --- a/e2e/commands/ingest.md +++ b/e2e/commands/ingest.md @@ -4,8 +4,8 @@ description: "Fetch [QE] story, verify dependencies, explore e2e infrastructure, --- # /ingest -Read `../skills/controller.md` and follow it. +Read `../skills/dispatch.md` and follow it with `PHASE=ingest`. -Dispatch the **ingest** phase. Context: +Context: $ARGUMENTS diff --git a/e2e/commands/plan.md b/e2e/commands/plan.md index a6f8b560..075595e6 100644 --- a/e2e/commands/plan.md +++ b/e2e/commands/plan.md @@ -4,8 +4,8 @@ description: "Map acceptance criteria to e2e test scenarios, select reference su --- # /plan -Read `../skills/controller.md` and follow it. +Read `../skills/dispatch.md` and follow it with `PHASE=plan`. -Dispatch the **plan** phase. Context: +Context: $ARGUMENTS diff --git a/e2e/commands/publish.md b/e2e/commands/publish.md index d6f2e550..0b521a13 100644 --- a/e2e/commands/publish.md +++ b/e2e/commands/publish.md @@ -4,8 +4,8 @@ description: "Push feature branch and create draft PR for e2e tests" --- # /publish -Read `../skills/controller.md` and follow it. +Read `../skills/dispatch.md` and follow it with `PHASE=publish`. -Dispatch the **publish** phase. Context: +Context: $ARGUMENTS diff --git a/e2e/commands/respond.md b/e2e/commands/respond.md index 5019348a..e118a879 100644 --- a/e2e/commands/respond.md +++ b/e2e/commands/respond.md @@ -4,8 +4,8 @@ description: "Fetch and address PR reviewer comments on e2e test code" --- # /respond -Read `../skills/controller.md` and follow it. +Read `../skills/dispatch.md` and follow it with `PHASE=respond`. -Dispatch the **respond** phase. Context: +Context: $ARGUMENTS diff --git a/e2e/commands/revise.md b/e2e/commands/revise.md index ee37a597..5e7d4aa2 100644 --- a/e2e/commands/revise.md +++ b/e2e/commands/revise.md @@ -4,8 +4,8 @@ description: "Incorporate user feedback into the e2e test plan" --- # /revise -Read `../skills/controller.md` and follow it. +Read `../skills/dispatch.md` and follow it with `PHASE=revise`. -Dispatch the **revise** phase. Context: +Context: $ARGUMENTS diff --git a/e2e/commands/validate.md b/e2e/commands/validate.md index dc6df134..1911ab7b 100644 --- a/e2e/commands/validate.md +++ b/e2e/commands/validate.md @@ -4,8 +4,8 @@ description: "Run e2e tests, check for anti-patterns, verify scenario coverage, --- # /validate -Read `../skills/controller.md` and follow it. +Read `../skills/dispatch.md` and follow it with `PHASE=validate`. -Dispatch the **validate** phase. Context: +Context: $ARGUMENTS diff --git a/e2e/skills/code.md b/e2e/skills/code.md index 980aa8e8..6d9153d6 100644 --- a/e2e/skills/code.md +++ b/e2e/skills/code.md @@ -516,4 +516,4 @@ Report your results: - Any discoveries (especially feature defects) - Overall implementation status -Then **re-read the controller** (`controller.md`) for next-step guidance. +Then return to the invoking workflow router for completion guidance. diff --git a/e2e/skills/completion.md b/e2e/skills/completion.md new file mode 100644 index 00000000..400f5805 --- /dev/null +++ b/e2e/skills/completion.md @@ -0,0 +1,36 @@ +--- +name: completion +description: Recommend next steps after one attended e2e phase. +--- + +# E2E Phase Completion + +After the completed `PHASE` reports its results, recommend the best next step +for the actual outcome, mention relevant alternatives briefly, and stop for the +user. + +- **ingest:** Recommend `/plan` unless the story context, [DEV] dependencies, + or test infrastructure has blocking gaps. Recommend clarification or waiting + for dependencies when planning cannot proceed safely. +- **plan:** Recommend `/revise` for user-requested changes, or `/code` when the + user has already reviewed and accepted the plan. +- **revise:** Recommend `/code` when the user is satisfied, or another + `/revise` round when further changes remain. +- **code:** Recommend `/validate`. If implementation exposed a plan gap, note + the inline plan update or offer `/plan` when user review is needed. For a + feature defect, report it without recommending an out-of-scope product-code + fix. For missing test infrastructure, present the documented deviation + options for user choice. +- **validate:** Recommend `/publish` only when validation passed. When failures + or anti-patterns remain, recommend fixing them and rerunning `/validate`. + Add missing scenarios when an acceptance-criteria gap is fixable; escalate + ambiguous or non-e2e-testable criteria to the user. +- **publish:** Recommend `/respond` when review comments arrive; otherwise the + workflow is complete for now. +- **respond:** Recommend `/validate` after code changes, another `/respond` + round while comments remain, or note completion when the PR is approved and + no work remains. + +The user may start at `/code` with an existing plan or partial test +implementation, and may skip `/publish` and `/respond` when working locally. +Never auto-advance between attended phases. diff --git a/e2e/skills/controller.md b/e2e/skills/controller.md index a0abb223..4bd37b4d 100644 --- a/e2e/skills/controller.md +++ b/e2e/skills/controller.md @@ -1,16 +1,19 @@ --- name: controller -description: Top-level workflow controller that manages phase transitions for e2e test implementation. +description: Discover and route ambiguous e2e test implementation requests. --- # E2E Test Workflow Controller -You are the workflow controller. Your job is to manage the e2e test -implementation workflow by executing phases and handling transitions -between them. +Use this controller for workflow discovery and ambiguous-input routing. Once a +phase is selected, delegate its execution and completion guidance to the +lightweight dispatcher. ## Phases +Keep this phase list synchronized with the command wrappers, phase files, +dispatcher filename mapping, and per-phase completion guidance. + 1. **Ingest** (`/ingest`) — `ingest.md` Fetch the [QE] Jira story, verify [DEV] dependencies are merged, explore the project's e2e test infrastructure, and build a test-execution profile. @@ -59,95 +62,36 @@ the source repo: ## How to Execute a Phase -1. **Announce** the phase to the user: *"Starting /plan."* -2. **Locate** the skill file — read and follow - `../../_shared/recipes/phase-override-resolution.md` with - WORKFLOW=`e2e`, PHASE_FILE=`{phase}.md`. -3. **Read** the resolved skill file -4. **Execute** the skill's steps — the user should see your progress -5. When the skill is done, it will tell you to report findings and - re-read this controller. Do that — then use "Recommending Next Steps" - below to offer options. -6. Present the skill's results and your recommendations to the user -7. **Stop and wait** for the user to tell you what to do next. - -## Recommending Next Steps - -After each phase completes, present the user with **options** — not just one -next step. Use the typical flow as a baseline, but adapt to what actually -happened. - -### Typical Flow - -```text -ingest → plan → [revise loop] → code → validate → publish → [respond loop] -``` - -### What to Recommend - -**Continuing forward:** - -- `/ingest` completed → recommend `/plan` (almost always the right next step) -- `/plan` completed → recommend `/revise` for user review of the plan, or `/code` if the user has already reviewed inline -- `/revise` completed (user satisfied) → recommend `/code`, or another `/revise` round -- `/code` completed → recommend `/validate` (always — never skip validation) -- `/validate` completed (all passing) → recommend `/publish` -- `/validate` completed (failures remain) → recommend fixing issues, then re-running `/validate` -- `/publish` completed → recommend `/respond` when review comments arrive -- `/respond` completed → recommend another `/respond` round, or note that the workflow is done when the PR is approved and merged - -**Looping back:** - -- `/plan` reveals story gaps or contradictions → suggest the user clarify with the story author or update the story -- `/code` reveals plan gaps → the plan is updated inline during implementation; offer `/validate` when implementation is complete -- `/code` discovers a feature defect (test reveals a bug in the [DEV] implementation) → note it in the implementation report; the test may need to xfail or skip. Do NOT recommend fixing the feature — that is out of scope -- `/code` discovers a missing test infrastructure method (plan referenced a method that doesn't exist) → see deviation rules in `code.md`; a local helper may suffice, or the user decides whether to adjust the plan or add test infrastructure support outside this workflow -- `/validate` reveals test failures → offer to diagnose and fix, then re-run `/validate` -- `/validate` reveals anti-patterns → fix them during validation, then re-run the affected checks -- `/validate` reveals unsatisfied acceptance criteria → if fixable (missing test scenarios), write them during validation; if the criterion is ambiguous or not e2e-testable, escalate to the user -- `/respond` requires code changes → apply changes, re-run `/validate`, then continue responding - -**Skipping:** - -- If the user already has a plan or partial test implementation, they may start at `/code` -- If the user wants to skip PR creation (e.g., working locally), `/publish` and `/respond` may be skipped - -### How to Present Options - -Lead with your top recommendation, then list alternatives briefly: - -```text -Recommended next step: /code — begin writing e2e test code following the -approved plan. - -Other options: -- /revise — if you want to adjust the plan first -- /validate — if you've already written test code and want to check it -``` +Set `PHASE` to the selected phase, then read `dispatch.md` and follow it. The +dispatcher owns phase announcement, override resolution, execution, and +completion routing for both built-in phases and project overrides. ## Starting the Workflow -Before dispatching any phase, check if the project has its own `AGENTS.md` -or `CLAUDE.md`. If so, read it — it may contain project-specific conventions, -testing standards, or other guidance that affects how the workflow operates. - When the user provides a Jira issue key or URL: -1. Execute the **ingest** phase -2. After ingestion, present results and wait +1. Set `PHASE=ingest`. +2. Read `dispatch.md` and follow it. + +If the user invokes a specific command (e.g., `/code`), set `PHASE` to that +command's phase, then read `dispatch.md` and follow it. Do not force the user +through earlier phases. -If the user invokes a specific command (e.g., `/code`), execute that phase -directly — don't force them through earlier phases. +For any other input, summarize the available phases, ask the user for a Jira +issue key or URL or a specific phase command, and stop without reading +`dispatch.md`. ## Error Handling -If any phase fails (Jira MCP errors, test failures, git errors): +If a phase cannot complete because of an operational error (for example, a +Jira MCP or git error): 1. **Stop immediately.** Do not advance to the next phase. 2. **Report the error** to the user with the specific error message. 3. **Offer options:** retry the failed step, skip the phase (if optional), or escalate. Do not fabricate results when a tool call fails. Do not silently continue -past errors. +past errors. A completed validation report with a failing verdict is a valid +phase outcome; route it through `completion.md` for fix-and-rerun guidance. ## Context Management @@ -164,7 +108,8 @@ subagent spawning. ## Rules - **Never auto-advance.** Always wait for the user between phases. -- **Recommendations come from this file, not from skills.** Skills report findings; this controller decides what to recommend next. +- **Recommendations come from `completion.md`.** Phase skills report findings; + the completion guide provides the authoritative next-step model. - **Jira is read-only.** The `/ingest` phase reads from Jira but never modifies it. No phase in this workflow writes to Jira. - **Plan evolves during implementation.** `/code` updates `02-plan.md` as tasks are completed. This is expected, not a sign of plan failure. - **Validation is mandatory before publishing.** Never recommend `/publish` unless `/validate` has passed. diff --git a/e2e/skills/dispatch.md b/e2e/skills/dispatch.md new file mode 100644 index 00000000..69cb9abf --- /dev/null +++ b/e2e/skills/dispatch.md @@ -0,0 +1,33 @@ +--- +name: dispatch +description: Resolve and execute one explicitly requested e2e phase. +--- + +# E2E Phase Dispatch + +E2E phase filenames follow the `{PHASE}.md` convention. If a phase uses a +different filename, define its mapping here before resolving overrides. + +Before dispatching, read the project's `AGENTS.md` or `CLAUDE.md` only if +neither is already in the session. Then, given `PHASE`, initialize +`COMPLETION_CONSUMED=false`, announce `Starting /{PHASE}.`, and read and follow +`../../_shared/recipes/phase-override-resolution.md` with `WORKFLOW=e2e` and +`PHASE_FILE={PHASE}.md`. Read and execute the resolved phase file, passing +through the command context unchanged. + +The built-in fallback is the phase file beside this dispatcher. Follow the +phase through its reporting step. Treat any supported phase exit—returning to +the invoking router, requesting completion guidance, or re-reading the +controller—as a return to this dispatcher. If the returned +`COMPLETION_HANDOFF` executes `completion.md`, set `COMPLETION_CONSUMED=true` +before executing that handoff. When the phase returns, read the guide once and +follow its guidance for `PHASE` only when `COMPLETION_CONSUMED=false`; the +dispatcher is the only component that reads the completion guide. + +If the recipe rejects a project override, continue with its built-in fallback. +If that fallback cannot be resolved, an operational error prevents the phase +from completing, or the phase has no completion behavior compatible with this +workflow, report the failure and stop without reading `completion.md`. A +completed phase report with a failing verdict, including `validate.md` reporting +`FAIL`, is a valid outcome: read `completion.md` so it can provide fix-and-rerun +guidance. diff --git a/e2e/skills/ingest.md b/e2e/skills/ingest.md index 5a9b89dd..71d6a378 100644 --- a/e2e/skills/ingest.md +++ b/e2e/skills/ingest.md @@ -744,4 +744,4 @@ Report your findings: - Story test plan status (test cases found / expected zero / anomalous zero / no testplan) - Assessment of readiness for `/plan` -Then **re-read the controller** (`controller.md`) for next-step guidance. +Then return to the invoking workflow router for completion guidance. diff --git a/e2e/skills/plan.md b/e2e/skills/plan.md index 1f81410c..647a410f 100644 --- a/e2e/skills/plan.md +++ b/e2e/skills/plan.md @@ -349,4 +349,4 @@ Report your results: - Note any risks or open questions - Assessment of plan completeness -Then **re-read the controller** (`controller.md`) for next-step guidance. +Then return to the invoking workflow router for completion guidance. diff --git a/e2e/skills/publish.md b/e2e/skills/publish.md index 5667ef3c..976501e0 100644 --- a/e2e/skills/publish.md +++ b/e2e/skills/publish.md @@ -230,7 +230,6 @@ Present: - PR URL (the full `https://github.com/...` link, not just `owner/repo#number`) - Branch name and base - Number of commits included -- Next steps (share with reviewers, wait for comments, then use `/respond`) ## Output @@ -244,6 +243,5 @@ Present: Report your results: - PR URL and branch name - Commits included -- Suggested next steps -Then **re-read the controller** (`controller.md`) for next-step guidance. +Then return to the invoking workflow router for completion guidance. diff --git a/e2e/skills/respond.md b/e2e/skills/respond.md index cc1411ee..3c92e1cd 100644 --- a/e2e/skills/respond.md +++ b/e2e/skills/respond.md @@ -231,4 +231,4 @@ Report your results: - Re-validation recommendation - Outstanding items -Then **re-read the controller** (`controller.md`) for next-step guidance. +Then return to the invoking workflow router for completion guidance. diff --git a/e2e/skills/revise.md b/e2e/skills/revise.md index 11052ac7..fa0f3d50 100644 --- a/e2e/skills/revise.md +++ b/e2e/skills/revise.md @@ -134,4 +134,4 @@ Report your results: - Any consistency updates made as a side effect - Assessment of plan readiness for `/code` -Then **re-read the controller** (`controller.md`) for next-step guidance. +Then return to the invoking workflow router for completion guidance. diff --git a/e2e/skills/validate.md b/e2e/skills/validate.md index 9426f4f7..bcd43cf5 100644 --- a/e2e/skills/validate.md +++ b/e2e/skills/validate.md @@ -394,4 +394,4 @@ Report your results: - Regression status - Overall verdict -Then **re-read the controller** (`controller.md`) for next-step guidance. +Then return to the invoking workflow router for completion guidance.