Task Planning Mode

Task Planning Mode#

MassGen’s task planning mode enables agents to create structured plans before execution, separating the “what to build” from the “how to build it” phases.

Overview#

Task planning mode provides three workflows:

  1. Planning Only (--plan) - Agents create a structured task plan interactively

  2. Plan and Execute (--plan-and-execute) - Full workflow: create plan, then execute it

  3. Execute Plan (--execute-plan) - Execute an existing plan without re-planning

This separation enables:

  • Human review of plans before execution

  • Iteration on plans without re-running expensive execution

  • Reuse of plans across multiple execution attempts

  • Clear accountability for what was planned vs what was built

Quick Start#

Create a plan:

uv run massgen --config my_agents.yaml --plan "Build a portfolio website with dark mode"

Create and execute a plan:

uv run massgen --config my_agents.yaml --plan-and-execute "Build a portfolio website"

Execute an existing plan:

# By plan ID
uv run massgen --config my_agents.yaml --execute-plan 20260115_173113_836955

# By path
uv run massgen --config my_agents.yaml --execute-plan .massgen/plans/plan_20260115_173113_836955

# Most recent plan
uv run massgen --config my_agents.yaml --execute-plan latest

TUI Plan and Execute Mode#

Added in version 0.1.44: Interactive Plan and Execute modes in the Textual TUI.

The TUI provides interactive modes for creating and executing plans without command-line flags.

Mode Cycling#

Press Shift+Tab to cycle through four modes:

  1. Normal Mode - Standard chat with agents

  2. Planning Mode - Create new plans interactively

  3. Execute Mode - Browse and execute existing plans chunk-by-chunk

  4. Analysis Mode - Analyze prior run logs and improve workflows

Normal ──[Shift+Tab]──> Planning ──[Shift+Tab]──> Execute ──[Shift+Tab]──> Analysis ──[Shift+Tab]──> Normal

Or click the plan mode button in the mode bar to cycle through modes.

Using Planning Mode#

Step 1: Enter Planning Mode

uv run massgen --display textual

Press Shift+Tab once to enter Planning mode.

Step 2: Configure Plan Options (Optional)

Click the plan options button to set:

  • Plan Depth: dynamic (default), shallow (5-10 tasks), medium (20-50 tasks), or deep (100-200+ tasks)

  • Task Count Target: dynamic (default) or an explicit target

  • Chunk Count Target: dynamic (default) or an explicit target

  • Broadcast Mode: agents (agent coordination), human (ask user), or false (autonomous)

Step 3: Create Plan

Type your planning request and press Enter:

"Create a Python web scraper for news articles with error handling"

Agents will collaborate to create a structured task plan without executing any code.

Step 4: Review Plan

After planning completes, the review modal opens and the plan is saved immediately to .massgen/plans/.

You can:

  • Continue Planning (multi-agent refinement turn; requires a non-empty prompt)

  • Quick Edit (Single Agent) (focused refinement turn; requires a non-empty prompt)

  • Finalize Plan and Execute (default Enter action)

The modal also includes an inline JSON editor so you can directly edit project_plan.json before continuing or finalizing.

Using Execute Mode#

Step 1: Enter Execute Mode

uv run massgen --display textual

Press Shift+Tab twice to enter Execute mode.

Step 2: Browse Plans

A plan selector popover appears showing:

  • Up to 10 most recent plans

  • Timestamps when plans were created

  • Original prompts used to create each plan

Step 3: View Plan Details (Optional)

Click “View Full Plan” to see complete task breakdown in a modal.

Step 4: Execute

  • Select a plan (or use the default latest plan)

  • Press Enter to execute the selected plan’s current chunk

  • Optionally type a chunk label (or chunk range like C02-C04) before pressing Enter

  • Optionally type additional execution instructions

Step 5: Control Chunk Flow

In execute options you can choose:

  • Auto-continue next chunk (default)

  • Pause after each chunk (manual confirmation between chunks)

  • Execute refinement mode: inherit / force ON / force OFF

Note

CWD context toggling (Ctrl+P) is disabled while Execute mode is active. Set CWD context before entering Execute mode, or pass --cwd-context ro|rw at launch.

Context Path Preservation#

Context paths from the planning phase are automatically preserved:

  • If you created a plan with @/path/to/file context injection

  • Those same paths are restored when you execute the plan later

  • Ensures consistent file access between planning and execution

Execution Workspace Contract#

During each execute turn:

  • tasks/plan.json contains only the active chunk tasks

  • previous chunk snapshots are retained as tasks/tasks_cXX.json files

  • planning_docs/full_plan.json contains the frozen full plan for read-only reference

  • supporting planning docs are available under planning_docs/

Note

TUI Plan Workflow Benefits:

  • Planning Mode: Create plans interactively with visual feedback

  • Execute Mode: Browse saved plans and re-run without re-planning

  • Flexibility: Switch modes on-the-fly without restarting MassGen

Planning Phase (CLI)#

In planning mode, agents create:

  • Task Plan (plan.json) - Structured list of tasks with dependencies (required)

  • Supporting docs (optional) - Requirements, design decisions, or other markdown documentation

Plan Depth#

Control plan granularity with --plan-depth:

# Quick overview (5-10 tasks)
uv run massgen --config my_agents.yaml --plan --plan-depth shallow "Build a blog"

# Balanced detail (20-50 tasks) - default
uv run massgen --config my_agents.yaml --plan --plan-depth medium "Build a blog"

# Comprehensive breakdown (100-200+ tasks)
uv run massgen --config my_agents.yaml --plan --plan-depth deep "Build a blog"

Broadcast Modes#

Control how agents collaborate during planning:

# Agents ask user critical questions (default)
uv run massgen --config my_agents.yaml --plan --broadcast human "Build a blog"

# Agents coordinate and clarify with each other
uv run massgen --config my_agents.yaml --plan --broadcast agents "Build a blog"

# Fully autonomous - no questions
uv run massgen --config my_agents.yaml --plan --broadcast false "Build a blog"

Note

In automation mode (--automation), human broadcast automatically switches to false since there’s no human to respond.

Task Plan Structure#

Plans are stored as JSON with this structure:

{
  "tasks": [
    {
      "id": "F001",
      "description": "Initialize Next.js project with Tailwind CSS",
      "chunk": "C01_foundation",
      "status": "pending",
      "depends_on": [],
      "priority": "high",
      "metadata": {
        "verification": "Dev server runs successfully",
        "verification_method": "Start dev server and verify it loads",
        "verification_group": "foundation"
      }
    },
    {
      "id": "F002",
      "description": "Create responsive navigation component",
      "chunk": "C02_ui_shell",
      "status": "pending",
      "depends_on": ["F001"],
      "priority": "high",
      "metadata": {
        "verification": "Navigation renders on mobile and desktop",
        "verification_method": "Check responsive rendering at different viewport sizes",
        "verification_group": "components"
      }
    }
  ]
}

Task Fields:

Field

Required

Description

id

Yes

Unique task identifier (e.g., “F001”, “T001”)

description

Yes

What the task accomplishes

chunk

Yes

Planner-defined chunk label used for chunk-by-chunk execution order

status

Yes

pending, in_progress, completed, verified, or blocked

depends_on

Yes

Array of task IDs that must complete first

priority

No

high, medium, or low

completed_at

No

Timestamp when task was completed (ISO format)

verified_at

No

Timestamp when task was verified (ISO format)

metadata.verification

No

How to verify task completion

metadata.verification_method

No

Specific command or action to verify

metadata.verification_group

No

Group name for batch verification (e.g., “foundation”, “frontend_ui”)

Execution Phase#

During execution:

  1. The frozen plan (from frozen/plan.json) is loaded

  2. tasks/plan.json is written with only the active chunk tasks for that turn

  3. planning_docs/full_plan.json is copied for read-only full-plan reference

  4. Previous chunk snapshots are archived as tasks/tasks_cXX.json files

  5. Agents use MCP planning tools to track progress

  6. Agents execute tasks respecting dependencies

  7. Agents update task status as they work

MCP Planning Tools#

Agents have access to these tools during execution:

get_task_plan()                              # View full plan with status
get_ready_tasks()                            # Tasks with satisfied dependencies
update_task_status(id, status, notes)        # Mark task progress
add_task(description, depends_on, priority)  # Add new task if needed
create_task_plan(tasks)                      # Replace entire plan (adoption)

Example agent workflow:

1. get_ready_tasks() → ["F001"]
2. update_task_status("F001", "in_progress")
3. ... execute task ...
4. update_task_status("F001", "completed", "Created Next.js project")
5. get_ready_tasks() → ["F002", "F003"]  # Dependencies now satisfied
6. ... complete more foundation tasks ...
7. # Verify foundation group: run npm run dev → works!
8. update_task_status("F001", "verified", "Dev server runs successfully")

Task Status Flow:

  • pending → in_progress → completed → verified

  • completed: Implementation is done (code written)

  • verified: Task has been tested and confirmed working

Agents verify tasks in groups using verification_group labels, not after every task.

Plan Storage#

Plans are stored in .massgen/plans/:

.massgen/plans/
└── plan_20260115_173113_836955/
    ├── plan_metadata.json      # Session info, status
    ├── execution_log.jsonl     # Event log
    ├── plan_diff.json          # Changes from original (after execution)
    ├── frozen/                  # Immutable snapshot from planning
    │   ├── plan.json
    │   ├── requirements.md
    │   └── design_decisions.md
    └── workspace/              # Modified plan after execution

Plan Metadata:

{
  "plan_id": "20260115_173113_836955",
  "created_at": "2026-01-15T17:31:13.837534",
  "planning_session_id": "log_20260115_171953_153808",
  "execution_session_id": "log_20260115_195506_513599",
  "status": "completed"
}

Status Values:

  • planning - Plan creation in progress

  • ready - Planning complete, awaiting execution

  • executing - Execution in progress

  • completed - Execution finished

  • failed - Execution failed

Configuration#

Enable planning tools in your config:

orchestrator:
  coordination:
    enable_agent_task_planning: true
    task_planning_filesystem_mode: true

These are automatically enabled when using --plan, --plan-and-execute, or --execute-plan flags.

Automation Mode#

For CI/CD or programmatic usage:

# Plan and execute with automation output
uv run massgen --automation --config my_agents.yaml \
    --plan-and-execute "Build the feature"

# Execute existing plan
uv run massgen --automation --config my_agents.yaml \
    --execute-plan latest

Automation output includes:

LOG_DIR: .massgen/massgen_logs/log_20260115_195506_513599
PLAN_DIR: .massgen/plans/plan_20260115_173113_836955
PLAN_ID: 20260115_173113_836955
STATUS: 0

Best Practices#

1. Review Plans Before Execution

# Create plan only
uv run massgen --config my_agents.yaml --plan "Build feature X"

# Review the plan
cat .massgen/plans/plan_*/frozen/plan.json

# Execute when satisfied
uv run massgen --config my_agents.yaml --execute-plan latest

2. Use Appropriate Depth

  • shallow - Quick prototypes, simple features

  • medium - Most projects (default)

  • deep - Complex systems, detailed specifications

3. Include Verification in Plans

Good plans include verification methods:

{
  "id": "F001",
  "description": "Setup project",
  "metadata": {
    "verification": "Project builds without errors",
    "verification_method": "Run build and check for errors"
  }
}

Agents are instructed to verify at checkpoints:

  • After project setup - run dev server, confirm it starts

  • After completing a feature group - test the feature works

  • Before declaring complete - run full build, fix errors

4. Iterate on Plans

If execution reveals issues:

  1. Review the plan diff (--plan-report)

  2. Create a new plan incorporating lessons learned

  3. Execute the improved plan

Troubleshooting#

Plan not found:

# List available plans
ls .massgen/plans/

# Use full path if ID doesn't work
uv run massgen --execute-plan .massgen/plans/plan_20260115_173113_836955

Agents not following plan:

Check that planning tools are enabled in your config and that the plan was properly loaded. Agents should call get_task_plan() at the start.

Verification steps not running:

Agents are instructed to verify at checkpoints (after setup, after feature groups, before completion), not after every individual task. If verification is still being skipped, ensure your plan has clear verification_method fields and consider adding explicit “verify build” tasks at key milestones.

See Also#