klaude-code 2.10.3__py3-none-any.whl → 2.10.4__py3-none-any.whl

klaude_code/core/tool/__init__.py

@@ -1,3 +1,4 @@
+from .backtrack.backtrack_tool import BacktrackTool
 from .context import FileTracker, RunSubtask, SubAgentResumeClaims, TodoContext, ToolContext, build_todo_context
 from .file.apply_patch import DiffError, process_patch
 from .file.apply_patch_tool import ApplyPatchTool
@@ -19,6 +20,7 @@ from .web.web_search_tool import WebSearchTool
 
 __all__ = [
     "ApplyPatchTool",
+    "BacktrackTool",
     "BashTool",
     "DiffError",
     "EditTool",

klaude_code/core/tool/backtrack/__init__.py

@@ -0,0 +1,3 @@
+from klaude_code.core.tool.backtrack.backtrack_tool import BacktrackTool
+
+__all__ = ["BacktrackTool"]

klaude_code/core/tool/backtrack/backtrack_tool.md

@@ -0,0 +1,17 @@
+Revert conversation history to a previous checkpoint, discarding everything after it.
+
+Use this tool when:
+- You spent many tokens on exploration that turned out unproductive
+- You read large files but only need to keep key information
+- A deep debugging session can be summarized before continuing
+- The current approach is stuck and you want to try a different path
+
+The note you provide will be shown to your future self at the checkpoint, so include:
+- Key findings from your exploration
+- What approaches did not work and why
+- Important context needed to continue
+
+IMPORTANT:
+- File system changes are NOT reverted - only conversation history is affected
+- Checkpoints are created automatically at the start of each turn
+- Available checkpoints appear as <system>Checkpoint N</system> in the conversation

klaude_code/core/tool/backtrack/backtrack_tool.py

@@ -0,0 +1,65 @@
+from pathlib import Path
+
+from pydantic import BaseModel, Field
+
+from klaude_code.core.tool.context import ToolContext
+from klaude_code.core.tool.tool_abc import ToolABC, load_desc
+from klaude_code.core.tool.tool_registry import register
+from klaude_code.protocol import llm_param, message, tools
+
+
+class BacktrackArguments(BaseModel):
+    checkpoint_id: int = Field(description="The checkpoint ID to revert to")
+    note: str = Field(description="A note to your future self with key findings/context to preserve")
+    rationale: str = Field(description="Why you are performing this backtrack")
+
+
+@register(tools.BACKTRACK)
+class BacktrackTool(ToolABC):
+    @classmethod
+    def schema(cls) -> llm_param.ToolSchema:
+        return llm_param.ToolSchema(
+            name=tools.BACKTRACK,
+            type="function",
+            description=load_desc(Path(__file__).parent / "backtrack_tool.md"),
+            parameters={
+                "type": "object",
+                "properties": {
+                    "checkpoint_id": {
+                        "type": "integer",
+                        "description": "The checkpoint ID to revert to",
+                    },
+                    "note": {
+                        "type": "string",
+                        "description": "A note to your future self with key findings/context",
+                    },
+                    "rationale": {
+                        "type": "string",
+                        "description": "Why you are performing this backtrack",
+                    },
+                },
+                "required": ["checkpoint_id", "note", "rationale"],
+                "additionalProperties": False,
+            },
+        )
+
+    @classmethod
+    async def call(cls, arguments: str, context: ToolContext) -> message.ToolResultMessage:
+        try:
+            args = BacktrackArguments.model_validate_json(arguments)
+        except ValueError as exc:
+            return message.ToolResultMessage(status="error", output_text=f"Invalid arguments: {exc}")
+
+        backtrack_manager = context.backtrack_manager
+        if backtrack_manager is None:
+            return message.ToolResultMessage(
+                status="error",
+                output_text="Backtrack is not available in this context",
+            )
+
+        try:
+            result = backtrack_manager.send_backtrack(args.checkpoint_id, args.note, args.rationale)
+        except ValueError as exc:
+            return message.ToolResultMessage(status="error", output_text=str(exc))
+
+        return message.ToolResultMessage(status="success", output_text=result)

klaude_code/core/tool/context.py

@@ -4,6 +4,7 @@ import asyncio
 from collections.abc import Awaitable, Callable, MutableMapping
 from dataclasses import dataclass, replace
 
+from klaude_code.core.backtrack import BacktrackManager
 from klaude_code.protocol import model
 from klaude_code.protocol.sub_agent import SubAgentResult
 from klaude_code.session.session import Session
@@ -85,9 +86,13 @@ class ToolContext:
     sub_agent_resume_claims: SubAgentResumeClaims | None = None
     record_sub_agent_session_id: Callable[[str], None] | None = None
     register_sub_agent_metadata_getter: Callable[[GetMetadataFn], None] | None = None
+    backtrack_manager: BacktrackManager | None = None
 
     def with_record_sub_agent_session_id(self, callback: Callable[[str], None] | None) -> ToolContext:
         return replace(self, record_sub_agent_session_id=callback)
 
     def with_register_sub_agent_metadata_getter(self, callback: Callable[[GetMetadataFn], None] | None) -> ToolContext:
         return replace(self, register_sub_agent_metadata_getter=callback)
+
+    def with_backtrack_manager(self, manager: BacktrackManager | None) -> ToolContext:
+        return replace(self, backtrack_manager=manager)

klaude_code/core/turn.py

@@ -5,6 +5,7 @@ from dataclasses import dataclass, field
 from typing import TYPE_CHECKING
 
 from klaude_code.const import RETRY_PRESERVE_PARTIAL_MESSAGE, SUPPORTED_IMAGE_SIZES
+from klaude_code.core.backtrack import BacktrackManager
 from klaude_code.core.tool import ToolABC
 from klaude_code.core.tool.context import SubAgentResumeClaims, ToolContext
 
@@ -49,6 +50,7 @@ class TurnExecutionContext:
     tools: list[llm_param.ToolSchema]
     tool_registry: dict[str, type[ToolABC]]
     sub_agent_state: model.SubAgentState | None = None
+    backtrack_manager: BacktrackManager | None = None
 
 
 @dataclass
@@ -404,6 +406,7 @@ class TurnExecutor:
             session_id=session_ctx.session_id,
             run_subtask=session_ctx.run_subtask,
             sub_agent_resume_claims=SubAgentResumeClaims(),
+            backtrack_manager=ctx.backtrack_manager,
         )
 
         executor = ToolExecutor(

klaude_code/llm/input_common.py

@@ -108,17 +108,86 @@ def build_tool_message(
     msg: message.ToolResultMessage,
     attachment: DeveloperAttachment,
 ) -> dict[str, object]:
+    """Build a tool message. Note: image_url in tool message is not supported by
+    OpenAI Chat Completions API. Use build_tool_message_for_chat_completions instead.
+    """
     merged_text = merge_reminder_text(
         msg.output_text or EMPTY_TOOL_OUTPUT_MESSAGE,
         attachment.text,
     )
+    content: list[dict[str, object]] = [{"type": "text", "text": merged_text}]
+    for part in msg.parts:
+        if isinstance(part, message.ImageFilePart):
+            content.append({"type": "image_url", "image_url": {"url": image_file_to_data_url(part)}})
+        elif isinstance(part, message.ImageURLPart):
+            content.append({"type": "image_url", "image_url": {"url": part.url}})
+    for image in attachment.images:
+        if isinstance(image, message.ImageFilePart):
+            content.append({"type": "image_url", "image_url": {"url": image_file_to_data_url(image)}})
+        else:
+            content.append({"type": "image_url", "image_url": {"url": image.url}})
     return {
         "role": "tool",
-        "content": [{"type": "text", "text": merged_text}],
+        "content": content,
         "tool_call_id": msg.call_id,
     }
 
 
+def build_tool_message_for_chat_completions(
+    msg: message.ToolResultMessage,
+    attachment: DeveloperAttachment,
+) -> tuple[dict[str, object], dict[str, object] | None]:
+    """Build tool message for OpenAI Chat Completions API.
+
+    OpenAI Chat Completions API does not support image_url in tool messages.
+    Images are extracted and returned as a separate user message to be appended after the tool message.
+
+    Returns:
+        A tuple of (tool_message, optional_user_message_with_images).
+        The user_message is None if there are no images.
+    """
+    merged_text = merge_reminder_text(
+        msg.output_text or EMPTY_TOOL_OUTPUT_MESSAGE,
+        attachment.text,
+    )
+
+    # Collect all images
+    image_urls: list[dict[str, object]] = []
+    for part in msg.parts:
+        if isinstance(part, message.ImageFilePart):
+            image_urls.append({"type": "image_url", "image_url": {"url": image_file_to_data_url(part)}})
+        elif isinstance(part, message.ImageURLPart):
+            image_urls.append({"type": "image_url", "image_url": {"url": part.url}})
+    for image in attachment.images:
+        if isinstance(image, message.ImageFilePart):
+            image_urls.append({"type": "image_url", "image_url": {"url": image_file_to_data_url(image)}})
+        else:
+            image_urls.append({"type": "image_url", "image_url": {"url": image.url}})
+
+    # If only images (no text), use placeholder
+    has_text = bool(merged_text.strip())
+    tool_content = merged_text if has_text else "(see attached image)"
+
+    tool_message: dict[str, object] = {
+        "role": "tool",
+        "content": tool_content,
+        "tool_call_id": msg.call_id,
+    }
+
+    # Build user message with images if any
+    user_message: dict[str, object] | None = None
+    if image_urls:
+        user_message = {
+            "role": "user",
+            "content": [
+                {"type": "text", "text": "Attached image(s) from tool result:"},
+                *image_urls,
+            ],
+        }
+
+    return tool_message, user_message
+
+
 def build_assistant_common_fields(
     msg: message.AssistantMessage,
     *,

klaude_code/llm/openai_compatible/input.py

@@ -12,7 +12,7 @@ from klaude_code.llm.input_common import (
     attach_developer_messages,
     build_assistant_common_fields,
     build_chat_content_parts,
-    build_tool_message,
+    build_tool_message_for_chat_completions,
     collect_text_content,
 )
 from klaude_code.protocol import llm_param, message
@@ -50,7 +50,10 @@ def convert_history_to_input(
                 parts = build_chat_content_parts(msg, attachment)
                 messages.append(cast(chat.ChatCompletionMessageParam, {"role": "user", "content": parts}))
             case message.ToolResultMessage():
-                messages.append(cast(chat.ChatCompletionMessageParam, build_tool_message(msg, attachment)))
+                tool_msg, user_msg = build_tool_message_for_chat_completions(msg, attachment)
+                messages.append(cast(chat.ChatCompletionMessageParam, tool_msg))
+                if user_msg is not None:
+                    messages.append(cast(chat.ChatCompletionMessageParam, user_msg))
             case message.AssistantMessage():
                 messages.append(_assistant_message_to_openai(msg))
             case _:

klaude_code/llm/openrouter/input.py

@@ -15,7 +15,7 @@ from klaude_code.llm.input_common import (
     attach_developer_messages,
     build_assistant_common_fields,
     build_chat_content_parts,
-    build_tool_message,
+    build_tool_message_for_chat_completions,
     collect_text_content,
     split_thinking_parts,
 )
@@ -153,7 +153,10 @@ def convert_history_to_input(
                 parts = build_chat_content_parts(msg, attachment)
                 messages.append(cast(chat.ChatCompletionMessageParam, {"role": "user", "content": parts}))
             case message.ToolResultMessage():
-                messages.append(cast(chat.ChatCompletionMessageParam, build_tool_message(msg, attachment)))
+                tool_msg, user_msg = build_tool_message_for_chat_completions(msg, attachment)
+                messages.append(cast(chat.ChatCompletionMessageParam, tool_msg))
+                if user_msg is not None:
+                    messages.append(cast(chat.ChatCompletionMessageParam, user_msg))
             case message.AssistantMessage():
                 messages.append(_assistant_message_to_openrouter(msg, model_name))
             case _:

klaude_code/llm/registry.py

@@ -21,7 +21,6 @@ _PROTOCOL_MODULES: dict[llm_param.LLMClientProtocol, str] = {
     llm_param.LLMClientProtocol.OPENROUTER: "klaude_code.llm.openrouter",
     llm_param.LLMClientProtocol.RESPONSES: "klaude_code.llm.openai_responses",
     llm_param.LLMClientProtocol.GOOGLE: "klaude_code.llm.google",
-    llm_param.LLMClientProtocol.ANTIGRAVITY: "klaude_code.llm.antigravity",
 }
 
 

klaude_code/protocol/events.py

@@ -14,6 +14,7 @@ __all__ = [
     "AssistantTextDeltaEvent",
     "AssistantTextEndEvent",
     "AssistantTextStartEvent",
+    "BacktrackEvent",
     "BashCommandEndEvent",
     "BashCommandOutputDeltaEvent",
     "BashCommandStartEvent",
@@ -116,6 +117,14 @@ class CompactionEndEvent(Event):
     kept_items_brief: list[message.KeptItemBrief] = Field(default_factory=list)  # pyright: ignore[reportUnknownVariableType]
 
 
+class BacktrackEvent(Event):
+    checkpoint_id: int
+    note: str
+    rationale: str
+    original_user_message: str
+    messages_discarded: int | None = None
+
+
 class TaskFinishEvent(Event):
     task_result: str
     has_structured_output: bool = False
@@ -220,6 +229,7 @@ type ReplayEventUnion = (
     | ErrorEvent
     | CompactionStartEvent
     | CompactionEndEvent
+    | BacktrackEvent
 )
 
 

klaude_code/protocol/llm_param.py

@@ -16,7 +16,6 @@ class LLMClientProtocol(Enum):
     BEDROCK = "bedrock"
     CODEX_OAUTH = "codex_oauth"
     GOOGLE = "google"
-    ANTIGRAVITY = "antigravity"
 
 
 class ToolSchema(BaseModel):

klaude_code/protocol/message.py

@@ -85,6 +85,15 @@ class CompactionEntry(BaseModel):
     created_at: datetime = Field(default_factory=datetime.now)
 
 
+class BacktrackEntry(BaseModel):
+    checkpoint_id: int
+    note: str
+    rationale: str
+    reverted_from_index: int
+    original_user_message: str
+    created_at: datetime = Field(default_factory=datetime.now)
+
+
 # Part types
 
 
@@ -196,7 +205,7 @@ class ToolResultMessage(MessageBase):
 
 Message = SystemMessage | DeveloperMessage | UserMessage | AssistantMessage | ToolResultMessage
 
-HistoryEvent = Message | StreamErrorItem | TaskMetadataItem | CompactionEntry
+HistoryEvent = Message | StreamErrorItem | TaskMetadataItem | CompactionEntry | BacktrackEntry
 
 StreamItem = AssistantTextDelta | AssistantImageDelta | ThinkingTextDelta | ToolCallStartDelta
 

klaude_code/protocol/tools.py

@@ -12,6 +12,7 @@ WEB_SEARCH = "WebSearch"
 REPORT_BACK = "report_back"
 TASK = "Task"
 IMAGE_GEN = "ImageGen"
+BACKTRACK = "Backtrack"
 
 # SubAgentType is just a string alias now; agent types are defined via SubAgentProfile
 SubAgentType = str

klaude_code/session/session.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import json
+import re
 import time
 import uuid
 from collections.abc import Iterable, Sequence
@@ -15,6 +16,15 @@ from klaude_code.session.store import JsonlSessionStore, build_meta_snapshot
 
 _DEFAULT_STORES: dict[str, JsonlSessionStore] = {}
 
+_CHECKPOINT_RE = re.compile(r"<system>Checkpoint (\d+)</system>")
+
+
+def _extract_checkpoint_id(text: str) -> int | None:
+    match = _CHECKPOINT_RE.search(text)
+    if match is None:
+        return None
+    return int(match.group(1))
+
 
 def _read_json_dict(path: Path) -> dict[str, Any] | None:
     try:
@@ -51,6 +61,8 @@ class Session(BaseModel):
     todos: list[model.TodoItem] = Field(default_factory=list)  # pyright: ignore[reportUnknownVariableType]
     model_name: str | None = None
 
+    next_checkpoint_id: int = 0
+
     model_config_name: str | None = None
     model_thinking: llm_param.Thinking | None = None
     created_at: float = Field(default_factory=lambda: time.time())
@@ -153,6 +165,8 @@ class Session(BaseModel):
         model_name = raw.get("model_name") if isinstance(raw.get("model_name"), str) else None
         model_config_name = raw.get("model_config_name") if isinstance(raw.get("model_config_name"), str) else None
 
+        next_checkpoint_id = int(raw.get("next_checkpoint_id", 0))
+
         model_thinking_raw = raw.get("model_thinking")
         model_thinking = (
             llm_param.Thinking.model_validate(model_thinking_raw) if isinstance(model_thinking_raw, dict) else None
@@ -169,6 +183,7 @@ class Session(BaseModel):
             model_name=model_name,
             model_config_name=model_config_name,
             model_thinking=model_thinking,
+            next_checkpoint_id=next_checkpoint_id,
         )
         session._store = store
         return session
@@ -221,19 +236,103 @@ class Session(BaseModel):
             model_name=self.model_name,
             model_config_name=self.model_config_name,
             model_thinking=self.model_thinking,
+            next_checkpoint_id=self.next_checkpoint_id,
         )
         self._store.append_and_flush(session_id=self.id, items=items, meta=meta)
 
+    @property
+    def n_checkpoints(self) -> int:
+        return self.next_checkpoint_id
+
+    def create_checkpoint(self) -> int:
+        checkpoint_id = self.next_checkpoint_id
+        self.next_checkpoint_id += 1
+        checkpoint_msg = message.DeveloperMessage(
+            parts=[message.TextPart(text=f"<system>Checkpoint {checkpoint_id}</system>")]
+        )
+        self.append_history([checkpoint_msg])
+        return checkpoint_id
+
+    def find_checkpoint_index(self, checkpoint_id: int) -> int | None:
+        target_text = f"<system>Checkpoint {checkpoint_id}</system>"
+        for i, item in enumerate(self.conversation_history):
+            if not isinstance(item, message.DeveloperMessage):
+                continue
+            text = message.join_text_parts(item.parts)
+            if target_text in text:
+                return i
+        return None
+
+    def get_user_message_before_checkpoint(self, checkpoint_id: int) -> str | None:
+        checkpoint_idx = self.find_checkpoint_index(checkpoint_id)
+        if checkpoint_idx is None:
+            return None
+
+        for i in range(checkpoint_idx - 1, -1, -1):
+            item = self.conversation_history[i]
+            if isinstance(item, message.UserMessage):
+                return message.join_text_parts(item.parts)
+        return None
+
+    def get_checkpoint_user_messages(self) -> dict[int, str]:
+        checkpoints: dict[int, str] = {}
+        last_user_message = ""
+        for item in self.conversation_history:
+            if isinstance(item, message.UserMessage):
+                last_user_message = message.join_text_parts(item.parts)
+                continue
+            if not isinstance(item, message.DeveloperMessage):
+                continue
+            text = message.join_text_parts(item.parts)
+            checkpoint_id = _extract_checkpoint_id(text)
+            if checkpoint_id is None:
+                continue
+            checkpoints[checkpoint_id] = last_user_message
+        return checkpoints
+
+    def revert_to_checkpoint(self, checkpoint_id: int, note: str, rationale: str) -> message.BacktrackEntry:
+        target_idx = self.find_checkpoint_index(checkpoint_id)
+        if target_idx is None:
+            raise ValueError(f"Checkpoint {checkpoint_id} not found")
+
+        user_message = self.get_user_message_before_checkpoint(checkpoint_id) or ""
+        reverted_from = len(self.conversation_history)
+        entry = message.BacktrackEntry(
+            checkpoint_id=checkpoint_id,
+            note=note,
+            rationale=rationale,
+            reverted_from_index=reverted_from,
+            original_user_message=user_message,
+        )
+
+        self.conversation_history = self.conversation_history[: target_idx + 1]
+        self.next_checkpoint_id = checkpoint_id + 1
+        self._invalidate_messages_count_cache()
+        self._user_messages_cache = None
+        return entry
+
     def get_llm_history(self) -> list[message.HistoryEvent]:
         """Return the LLM-facing history view with compaction summary injected."""
         history = self.conversation_history
+
+        def _convert(item: message.HistoryEvent) -> message.HistoryEvent:
+            if isinstance(item, message.BacktrackEntry):
+                return message.DeveloperMessage(
+                    parts=[
+                        message.TextPart(
+                            text=f"<system>After this, some operations were performed and context was refined via Backtrack. Rationale: {item.rationale}. Summary: {item.note}. Please continue.</system>"
+                        )
+                    ]
+                )
+            return item
+
         last_compaction: message.CompactionEntry | None = None
         for item in reversed(history):
             if isinstance(item, message.CompactionEntry):
                 last_compaction = item
                 break
         if last_compaction is None:
-            return [it for it in history if not isinstance(it, message.CompactionEntry)]
+            return [_convert(it) for it in history if not isinstance(it, message.CompactionEntry)]
 
         summary_message = message.UserMessage(parts=[message.TextPart(text=last_compaction.summary)])
         kept = [it for it in history[last_compaction.first_kept_index :] if not isinstance(it, message.CompactionEntry)]
@@ -246,7 +345,7 @@ class Session(BaseModel):
                 first_non_tool += 1
             kept = kept[first_non_tool:]
 
-        return [summary_message, *kept]
+        return [summary_message, *[_convert(it) for it in kept]]
 
     def fork(self, *, new_id: str | None = None, until_index: int | None = None) -> Session:
         """Create a new session as a fork of the current session.
@@ -266,6 +365,7 @@ class Session(BaseModel):
         forked.model_name = self.model_name
         forked.model_config_name = self.model_config_name
         forked.model_thinking = self.model_thinking.model_copy(deep=True) if self.model_thinking is not None else None
+        forked.next_checkpoint_id = self.next_checkpoint_id
         forked.file_tracker = {k: v.model_copy(deep=True) for k, v in self.file_tracker.items()}
         forked.todos = [todo.model_copy(deep=True) for todo in self.todos]
 
@@ -437,6 +537,15 @@ class Session(BaseModel):
                     yield events.DeveloperMessageEvent(session_id=self.id, item=dm)
                 case message.StreamErrorItem() as se:
                     yield events.ErrorEvent(error_message=se.error, can_retry=False, session_id=self.id)
+                case message.BacktrackEntry() as be:
+                    yield events.BacktrackEvent(
+                        session_id=self.id,
+                        checkpoint_id=be.checkpoint_id,
+                        note=be.note,
+                        rationale=be.rationale,
+                        original_user_message=be.original_user_message,
+                        messages_discarded=None,
+                    )
                 case message.CompactionEntry() as ce:
                     yield events.CompactionStartEvent(session_id=self.id, reason="threshold")
                     yield events.CompactionEndEvent(

klaude_code/session/store.py

@@ -169,6 +169,7 @@ def build_meta_snapshot(
     model_name: str | None,
     model_config_name: str | None,
     model_thinking: llm_param.Thinking | None,
+    next_checkpoint_id: int = 0,
 ) -> dict[str, Any]:
     return {
         "id": session_id,
@@ -186,4 +187,5 @@ def build_meta_snapshot(
         "model_thinking": model_thinking.model_dump(mode="json", exclude_defaults=True, exclude_none=True)
         if model_thinking
         else None,
+        "next_checkpoint_id": next_checkpoint_id,
     }

klaude_code/skill/assets/executing-plans/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: executing-plans
+description: Use when you have a written implementation plan to execute in a separate session with review checkpoints
+---
+
+# Executing Plans
+
+## Overview
+
+Load plan, review critically, execute tasks in batches, report for review between batches.
+
+**Core principle:** Batch execution with checkpoints for architect review.
+
+**Announce at start:** "I'm using the executing-plans skill to implement this plan."
+
+## The Process
+
+### Step 1: Load and Review Plan
+1. Read plan file
+2. Review critically - identify any questions or concerns about the plan
+3. If concerns: Raise them with your human partner before starting
+4. If no concerns: Create TodoWrite and proceed
+
+### Step 2: Execute Batch
+**Default: First 3 tasks**
+
+For each task:
+1. Mark as in_progress
+2. Follow each step exactly (plan has bite-sized steps)
+3. Run verifications as specified
+4. Mark as completed
+
+### Step 3: Report
+When batch complete:
+- Show what was implemented
+- Show verification output
+- Say: "Ready for feedback."
+
+### Step 4: Continue
+Based on feedback:
+- Apply changes if needed
+- Execute next batch
+- Repeat until complete
+
+### Step 5: Complete Development
+
+After all tasks complete and verified:
+- Announce: "I'm using the finishing-a-development-branch skill to complete this work."
+- **REQUIRED SUB-SKILL:** Use superpowers:finishing-a-development-branch
+- Follow that skill to verify tests, present options, execute choice
+
+## When to Stop and Ask for Help
+
+**STOP executing immediately when:**
+- Hit a blocker mid-batch (missing dependency, test fails, instruction unclear)
+- Plan has critical gaps preventing starting
+- You don't understand an instruction
+- Verification fails repeatedly
+
+**Ask for clarification rather than guessing.**
+
+## When to Revisit Earlier Steps
+
+**Return to Review (Step 1) when:**
+- Partner updates the plan based on your feedback
+- Fundamental approach needs rethinking
+
+**Don't force through blockers** - stop and ask.
+
+## Remember
+- Review plan critically first
+- Follow plan steps exactly
+- Don't skip verifications
+- Reference skills when plan says to
+- Between batches: just report and wait
+- Stop when blocked, don't guess
+- Never start implementation on main/master branch without explicit user consent
+
+## Integration
+
+**Required workflow skills:**
+- **superpowers:using-git-worktrees** - REQUIRED: Set up isolated workspace before starting
+- **superpowers:writing-plans** - Creates the plan this skill executes
+- **superpowers:finishing-a-development-branch** - Complete development after all tasks