Every skill's closing "next step" text must tell the user three things, in this order:
- Conversation — whether to stay in the current conversation or start a fresh one.
- Mode — normal mode, or plan mode. When plan mode is recommended, say explicitly whether to approve the plan (see "Plan mode" below).
- Next skill — the exact slash command to invoke, or "none" if the chain ends here.
Closing tip (append verbatim whenever recommending a next skill):
Tip: for best results, start a fresh conversation for the next skill — each skill gathers its own context from scratch.
The default tip above applies when the next skill gathers its own context. Some skills instead capture the current conversation's context (design decisions, non-goals, trade-offs discussed during implementation) into a durable artifact. For those skills, a fresh conversation strips the very context they need. Override the default tip when the next skill is one of these.
The continuation skills are:
/optimus:commit— captures the conversation's understanding of why the changes were made into the commit message body. A commit message generated from the diff alone records what changed; a commit message generated in the implementation conversation also records why./optimus:commit-message— same intent capture as/optimus:commit, but read-only (suggests a message without committing). Same continuation rationale./optimus:pr— captures the conversation's intent (problem, scope, non-goals, key decisions) into the PR description./optimus:code-reviewlater consumes that description as author intent context./optimus:handoff— compacts the current conversation itself intodocs/handoffs/<slug>.md; by definition it must run in the conversation being handed off. It is user-invoked and sits outside the canonical implementation chain below, but any closing that recommends it must use the stay-in-conversation wording.
The canonical implementation chain is implement → /optimus:commit → /optimus:pr → /optimus:code-review. The first three should run in the same conversation as the implementation (or in the code-review conversation — code-review's closing recommends the continuation skills in its own conversation whether or not fixes were applied). /optimus:code-review itself, and other downstream skills like /optimus:unit-test, run in fresh conversations because they gather their own context.
The implement step has two dedicated, test-aware implementers: /optimus:tdd (supervised, sequential, test-first Red-Green-Refactor) and /optimus:workflow (a self-orchestrated parallel build that runs a Claude Code dynamic workflow, with test-first applied as a quality bar rather than a per-cycle gate). Both feed the same downstream chain. They differ in plan-mode usage: when a plan-mode iteration precedes /optimus:tdd, it is reached via the review-only plan-mode carve-out below (simple tasks route to tdd directly, with no plan mode), while /optimus:workflow launches a workflow directly in normal mode and never uses plan mode (workflow subagents auto-approve edits regardless of mode, so the carve-out does not apply to it).
/optimus:tdd is not a continuation skill itself (it gathers its own task context from scratch), but its Step 9 summary block is a load-bearing input for the downstream continuation chain. When /optimus:tdd finishes, it pushes the branch and recommends /optimus:pr in the same conversation; /optimus:pr reads the conversation's ## TDD Summary + ### Behaviors Implemented table + ### Coverage delta (the exact heading strings emitted by skills/tdd/SKILL.md) to populate the PR description's ## Intent (Scope, Non-goals, Key decisions) and ## Test plan (per-behavior items, coverage delta). Inline PR/MR creation from inside /optimus:tdd is deliberately not supported — /optimus:pr owns default-branch detection, CLI install, existing-PR detection, and preview/confirm UX that the inline path would only duplicate.
/optimus:workflow follows the same pattern with its own load-bearing block: when it finishes it pushes the branch and recommends /optimus:pr in the same conversation; /optimus:pr reads the conversation's ## Implementation Summary + ### Components Built table + ### Coverage delta (the exact heading strings emitted by skills/workflow/SKILL.md) to populate the same ## Intent and ## Test plan sections.
Skills that emit a closing tip must use one of the variants below verbatim (substituting only the explicit placeholders). Drift is the failure mode this section exists to prevent — never paraphrase to skill-specific wording like "refactor's rationale", "deliverable's rationale", or "fix context". The umbrella term "implementation context" is intentional and covers design decisions, refactor rationale, fix context, and deliverable rationale.
When the closing block recommends one or more continuation skills (and no non-continuation skill is recommended as an immediate next step), emit:
Tip: stay in this conversation when running
<continuation-skill(s)>so the implementation context is captured. Other downstream skills (<non-continuation-examples>) should still run in fresh conversations.
Substitute <continuation-skill(s)> with the actual skill(s) — one (e.g., /optimus:pr) or several joined by "or"/"and" when the recommendation offers alternatives (e.g., /optimus:commit or /optimus:pr). Substitute <non-continuation-examples> with the relevant examples (e.g., /optimus:code-review, /optimus:unit-test, etc.).
When the closing block recommends two or more skills with a mix of continuation and non-continuation paths, emit:
Tip: for
<continuation-skill(s)>, stay in this conversation so they can capture the implementation context. For other downstream skills (<non-continuation-examples>), start a fresh conversation — each gathers its own context from scratch.
Use commas + "and" for multiple continuation skills (e.g., `/optimus:commit` and `/optimus:pr`).
When the closing block recommends only non-continuation skills, emit the plain default:
Tip: for best results, start a fresh conversation for the next skill — each skill gathers its own context from scratch.
The criterion: the skill's primary value comes from reading the current conversation, not from independent context gathering. Skills that load docs, run pre-flight checks, or analyze code from scratch are not continuation skills.
Claude Code's plan mode has built-in semantics the plugin cannot change: approving a plan executes it immediately in the same conversation. This same-conversation approve-and-implement is the intended flow and the right default for most deliverables. The one exception is work routed to /optimus:tdd afterwards: there, approving would bypass TDD's Red-Green-Refactor discipline (the Iron Law, verification protocol, circuit breaker), so those skills deliberately keep plan mode review-only (see the decision below). This carve-out is specific to /optimus:tdd. The other implementer, /optimus:workflow, is launched directly in normal mode and is never preceded by a plan-mode iteration, so nothing here applies to it.
Plan mode is also read-only: Claude cannot write files while the conversation is in plan mode. Any persistence ("append the refined plan to the doc") happens after the user toggles plan mode off and sends a follow-up message in normal mode, in the same conversation — the toggle itself is a permission-state change that does not trigger Claude; Claude only acts on the next user message, and only because the pasted plan-mode prompt told it to. There is no automatic persistence; it is prompt-driven.
Plan mode is a client UI toggle — no phrase exits it. The user must press the client's plan-mode control (CLI: Shift+Tab; VSCode extension and other clients: the equivalent toggle). Alternate entry points: launch with claude --permission-mode plan, or prefix the first message with /plan. Skill closing copy should describe the action client-agnostically and mention Shift+Tab only as an example. Note: some approval dialogs offer an "Ultraplan" option — it executes the plan, so treat it like approval and ignore it.
When a skill recommends plan mode as a handoff step, choose by deliverable type:
Default — a prose deliverable, or any plan NOT routed to /optimus:tdd: iterate against the real codebase, then approve the plan to implement in the same conversation. This is plan mode's intended flow and keeps the rich context just built — no "Refined plan" doc, no fresh conversation. After implementation, the continuation skills (/optimus:commit, /optimus:pr) stay in the conversation (see "Continuation skills" above).
Carve-out — a deliverable routed to /optimus:tdd (test-first production code): treat plan mode as review-only. Tell the user not to approve the plan — approval executes immediately and bypasses Red-Green-Refactor. Instead:
- The generated plan-mode prompt must include a closing instruction telling Claude to append a "Refined plan" section to the underlying spec or task file (
docs/specs/…ordocs/jira/…) once the user signals they're done iterating. Append (not overwrite) preserves the original spec/task context for audit. The write happens in normal mode after the user toggles plan mode off and sends a follow-up message — it is prompt-driven and requires an explicit trigger message, not automatic. - After Claude writes the refined plan, the user starts a fresh conversation and invokes
/optimus:tdd, which gathers context from scratch against the updated doc.
/optimus:brainstorm and /optimus:jira use this carve-out for their code paths — their generated prompts and user instructions come from the canonical blocks below.
Close the generated plan-mode prompt with this section, substituting <doc-path> with the actual spec/task file path. The ### Refined plan heading is exact for both skills — jira's refresh and enrichment procedures preserve that section by that literal string:
## How this conversation should run
Treat this conversation as a review loop — validate the plan against the actual codebase and iterate with me. When I say I'm done iterating, acknowledge but do not write yet — plan mode is read-only. I will then toggle plan mode off and send a short follow-up message (e.g. "go"). On that follow-up, append a `### Refined plan` section (heading exactly `### Refined plan`) to `<doc-path>` to capture the refined plan, and stop. I will start a fresh conversation to run `/optimus:tdd`.
After presenting the prompt, tell the user these three steps verbatim (substituting <doc-path>):
- Start a fresh Claude Code conversation in plan mode (CLI: press
Shift+Tabuntil the mode indicator shows plan mode; other clients: use the equivalent toggle). Paste the prompt above.- Iterate with Claude. Do not approve the plan — approval executes immediately and skips
/optimus:tdd's Red-Green-Refactor discipline. When you're satisfied, tell Claude you're done iterating; Claude will acknowledge. Then toggle plan mode off using the same control and send a short follow-up message (e.g. "go") — Claude will append a### Refined plansection to<doc-path>in response.- Start a second fresh conversation and paste the execution prompt below.
Each skill gathers its own context (doc loads, pre-flight checks, suitability analysis). Reusing a conversation mixes unrelated context and can bias the new skill's decisions. A fresh conversation keeps every skill's Step 1 honest.
The exception is continuation skills (see "Continuation skills — exception to fresh-conversation" above), where the current conversation is the context. For those, staying in the conversation is the honest choice.