[Feature]: Add mandatory plan step before task execution

[louisdevzz]

Summary

Add a mandatory plan confirmation step for all agent tasks, regardless of size, ensuring users are informed and can approve the approach before execution begins.

Problem statement

Currently, the agent executes tasks immediately without presenting a plan first, especially for smaller tasks that do not trigger the factory build workflow. This creates several issues:

1. Lack of transparency: Users do not know what the agent intends to do before it starts executing
2. Unexpected changes: The agent may make changes that the user did not anticipate or want
3. No opportunity for feedback: Users cannot provide input or corrections to the plan before work begins
4. Inconsistent UX: Large tasks (using factory_build) show plans, but small tasks execute immediately

This violates the principle of user control and informed consent in autonomous agent interactions.

Proposed solution

Implement a universal plan-before-execute requirement for all agent tasks:

1. Plan generation: Before any execution, the agent must generate a concise plan outlining:

   • What files will be created/modified/deleted
   • What commands will be executed
   • Expected outcomes and deliverables
   • Estimated complexity/time

2. User confirmation: Present the plan to the user and wait for explicit approval

   • Format: Clear, bullet-point plan with file paths and actions
   • Approval options: Yes / No / Modify plan
   • Default behavior: Do not proceed without user confirmation

3. Edge cases:

   • Read-only operations (e.g., explaining code) may skip plan
   • Emergency fixes with explicit user override
   • Configurable via user preferences (opt-out)

4. Implementation location:

   • Modify the agent orchestration loop in "src/agent/"
   • Add plan generation before tool execution phase
   • Update system prompt to enforce plan-first behavior

Non-goals / out of scope

• Complex interactive plan editing UI
• Automatic plan optimization based on user feedback
• Plan templates for common tasks
• Integration with external project management tools
• Historical plan tracking and analytics

Alternatives considered

1. Status quo: Keep current behavior where small tasks execute immediately

   • Rejected: Creates inconsistent user experience and reduces user control

2. Size-based planning: Only require plans for tasks above certain complexity

   • Rejected: Complexity estimation is error-prone; all tasks should be transparent

3. Post-execution summary: Show what was done after completion

   • Rejected: Too late for user to provide input or prevent unwanted changes

4. Opt-in planning: Make planning optional via configuration

   • Partially accepted: Can be implemented as future enhancement, but default must be plan-first

Acceptance criteria

• All agent tool executions (except read-only) require a user-approved plan first
• Plan clearly lists files to be modified and commands to be executed
• User can approve, reject, or request plan modifications
• Plan is logged for audit purposes
• Documentation updated in AGENTS.md
• No regression in existing factory_build planning for complex tasks

Architecture impact

• src/agent/: Modify orchestration loop to insert planning phase
• src/tools/: Add plan metadata collection before execution
• AGENTS.md: Update workflow documentation
• System prompts: Update to enforce plan-first requirement

Risk and rollback

Risk: May slow down simple tasks with additional confirmation step.
Mitigation: Plans should be concise; read-only operations exempt.
Rollback: Revert agent loop changes; restore previous immediate-execution behavior via feature flag.

Breaking change?

No

Data hygiene checks

• I removed personal/sensitive data from examples, payloads, and logs.
• I used neutral, project-focused wording and placeholders.