What Is Plan Mode in GenericAgent and How It Handles Multi-Step Tasks with Verification

Plan Mode is a deterministic, four-phase workflow in the GenericAgent framework that structures complex tasks through checkbox-driven execution, mandatory verification sub-agents, and built-in guardrails to prevent premature task completion.

The GenericAgent repository (lsdefine/GenericAgent) implements this mode to handle complex, multi-step operations such as multi-file migrations, conditional branching, and project builds. Unlike the default reactive mode, Plan Mode forces the agent to follow a strict operating procedure defined in memory/plan_sop.md, ensuring every step is auditable and verified before final success is reported.

Activating Plan Mode in GenericAgent

To enter Plan Mode, the agent invokes handler.enter_plan_mode("<plan_dir>/plan.md") as defined in [ga.py](https://github.com/lsdefine/GenericAgent/blob/main/ga.py#L439-L442). This call performs two critical actions: it stores the absolute plan path in self.working['in_plan_mode'] and expands the turn budget to 80 iterations, allowing the agent to execute lengthy multi-step workflows without hitting conversation limits.

# Trigger Plan Mode from any code execution context

handler.enter_plan_mode("./plan_myfeature/plan.md")

Once activated, the agent references memory/plan_sop.md as the single source of truth for behavior, proceeding through four distinct phases: Exploration, Planning, Execution, and Verification.

Phase 1: Exploration (Read-Only Environment Probing)

In the Exploration phase, the main agent creates the working directory and spawns a dedicated sub-agent to perform read-only environment probing. According to the SOP defined in [plan_sop.md](https://github.com/lsdefine/GenericAgent/blob/main/memory/plan_sop.md#L1-L7), the main agent never touches files or executes side effects during this phase; it only orchestrates the sub-agent that returns structured findings in exploration_findings.md.

Phase 2: Planning (Checkbox-Driven Task Skeleton)

After receiving the exploration findings, the agent enters the Planning phase and writes a plan.md skeleton. Each step is marked with a checkbox ([ ]) and optional execution tags:

• [D] — Delegate to a sub-agent
• [P] — Execute in parallel map mode
• [?] — Conditional branch execution

The SOP mandates this checklist template in plan.md to create an auditable trail of intended work, as documented in the Planning section of [plan_sop.md](https://github.com/lsdefine/GenericAgent/blob/main/memory/plan_sop.md).

Phase 3: Execution Loop with Mini-Verification

The Execution phase follows a strict loop defined in the SOP's "Execution State" section. The agent repeatedly:

1. Reads plan.md to locate the first unchecked [ ] item
2. Loads the referenced SOP file for that step
3. Executes according to tags (delegating for [D], mapping for [P], branching for [?])
4. Performs a Mini-verification to confirm the artifact exists
5. Patches the checkbox from [ ] to [✓] with a summary via file_patch
6. Returns to step 1

This loop continues until all checkboxes are marked complete, with each iteration documented in [agent_loop.py](https://github.com/lsdefine/GenericAgent/blob/main/agent_loop.py).

Phase 4: Mandatory Verification Sub-Agent

Once all checkboxes display [✓], the agent cannot immediately exit. The SOP forces a VERIFY step requiring the main agent to launch a dedicated verification sub-agent. This sub-agent consumes verify_context.json and must return a VERDICT before Plan Mode can conclude.

According to [plan_sop.md](https://github.com/lsdefine/GenericAgent/blob/main/memory/plan_sop.md#L107-L112), only a positive verdict permits the agent to report task completion. The verification SOP in [memory/verify_sop.md](https://github.com/lsdefine/GenericAgent/blob/main/memory/verify_sop.md) defines the exact format for this final validation.

Verification Guardrails and Completion Logic

The engine enforces these verification requirements through the do_no_tool hook in [ga.py](https://github.com/lsdefine/GenericAgent/blob/main/ga.py#L72-L75). If the agent claims task completion while self._in_plan_mode() is true but lacks a VERDICT or [VERIFY] marker, the engine returns a blocking warning:

⛔ [验证拦截] 检测到你在plan模式下声称完成，但未执行[VERIFY]验证步骤。请先按plan_sop §四启动验证subagent，获得VERDICT后才能声称完成。

This guardrail prevents premature exit from complex workflows.

Plan completion is calculated by _check_plan_completion() in [ga.py](https://github.com/lsdefine/GenericAgent/blob/main/ga.py#L42-L45), which counts remaining unchecked [ ] boxes in the active plan file. When the count reaches zero, the engine automatically calls _exit_plan_mode().

# Automatic exit occurs when check_plan_completion returns 0 unchecked items

handler._check_plan_completion()  # Returns 0 remaining tasks

# _exit_plan_mode() called automatically by engine

Practical Plan Mode Implementation Examples

Creating a Structured Plan File

Below is a minimal plan.md skeleton generated during Phase 2, demonstrating checkbox syntax and delegation tags:

# My Feature Implementation

需求：实现自动化登录 | 约束：仅使用公开 API

## 探索发现

- 发现1：项目根目录下有 `auth.py`（来源：file_read）
- 发现2：登录页面需要 CSRF token（来源：web_scan）

## 执行计划

1. [ ] 检查 `auth.py` 是否已实现登录函数
   SOP: login_sop.md
2. [D] 编写登录脚本并进行本地测试
   SOP: test_sop.md
3. [ ] 将登录脚本集成到 CI 流水线
   SOP: ci_sop.md
4. [ ] **[VERIFY]** 启动独立验证 sub-agent
   SOP: verify_sop.md

Manual Exit After Verification

While the engine auto-exits upon completion, the verification sub-agent can explicitly signal completion:

# Inside verification sub-agent after positive VERDICT

handler._exit_plan_mode()
print("[Info] Plan completed and exited.")

Summary

• Plan Mode transforms GenericAgent from reactive to deterministic by activating via handler.enter_plan_mode() in [ga.py](https://github.com/lsdefine/GenericAgent/blob/main/ga.py#L439-L442).
• The workflow follows four phases: Exploration (read-only sub-agent), Planning (checkbox skeleton), Execution (step-by-step with mini-verification), and Verification (mandatory sub-agent VERDICT).
• Tags like [D] (delegate), [P] (parallel), and [?] (conditional) control execution flow within the loop defined in [plan_sop.md](https://github.com/lsdefine/GenericAgent/blob/main/memory/plan_sop.md).
• The do_no_tool guard in [ga.py](https://github.com/lsdefine/GenericAgent/blob/main/ga.py#L72-L75) blocks completion claims until the verification sub-agent returns a valid VERDICT.
• Completion is determined by _check_plan_completion() counting unchecked [ ] boxes, automatically triggering _exit_plan_mode() when zero remain.

Frequently Asked Questions

How does Plan Mode differ from GenericAgent's default reactive mode?

Plan Mode imposes a structured, deterministic workflow governed by memory/plan_sop.md with mandatory verification steps, whereas the default reactive mode allows free-form responses without checkbox tracking or forced verification sub-agents. When Plan Mode is active, the agent follows the four-phase protocol (Exploration, Planning, Execution, Verification) and cannot claim task completion without a VERDICT from a verification sub-agent.

What happens if the agent tries to complete a task without the verification step?

The do_no_tool hook in ga.py (lines 72-75) intercepts any completion claim made while self._in_plan_mode() is true. If the reply lacks the [VERIFY] marker or a valid VERDICT, the engine returns a blocking warning message and forces the agent to launch the verification sub-agent before proceeding. This guardrail ensures no task exits Plan Mode without independent validation.

What do the checkbox tags [D], [P], and [?] mean in the plan.md file?

These tags within the plan.md checklist control execution behavior during the Execution phase: [D] delegates the step to a sub-agent, [P] executes the step in parallel map mode, and [?] indicates a conditional branch requiring the agent to evaluate conditions before proceeding. The main agent parses these tags after reading the first unchecked [ ] item in the plan file.

How does the agent know when to exit Plan Mode?

The engine continuously monitors the active plan file through _check_plan_completion() in ga.py (lines 42-45), which counts remaining unchecked [ ] checkboxes. When the count reaches zero and the verification sub-agent has returned a positive VERDICT, the engine automatically invokes _exit_plan_mode(). Alternatively, the verification sub-agent may explicitly call handler._exit_plan_mode() to signal completion.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}