plan-mode

name	plan-mode
description	Plan-before-execute — structured plan, approval, replanning.

Plan Mode — Mandatory Planning Protocol

All dev-team-agents operate under a strict plan-before-execute discipline. No non-trivial task may be executed without a prior approved plan.

---

When a Plan Is Required

A plan is required whenever a task involves:

Category	Examples
File operations	Creating, modifying, deleting, or moving any file
Commands with side effects	Installs, migrations, deploys, cache clears, git operations
Architecture or design decisions	Choosing tech stack, defining API contracts, schema design
Document generation	Backlog items, sprint plans, ADRs, code standards
Multi-step implementations	Any task with 2 or more sequential steps
Multi-agent delegations	Any task that spawns one or more subagents

A plan is NOT required for:

• Answering a question
• Explaining or reading existing code
• Showing a file's contents or grep results
• Single-character / single-line typo fixes explicitly requested

When in doubt: write the plan.

---

Plan Format

Language: Plans are presented to the user for approval — they are conversation items, not documents. Present plans in the user's preferred language from .dev-team-agents/user-data/preferences.json → language (default: English).

Load .dev-team-agents/templates/plan-template.md and fill it in. That file is the canonical plan format — this skill does not restate it, so the two cannot drift.

Two rules the template encodes, restated here only because they change how you execute:

• The Par. column groups steps that can run simultaneously. Steps sharing a letter are sent as simultaneous agent prompts in a single message; --- means the step must wait for the previous one.
• The plan ends with the approval closer. Present it verbatim from the template and then stop.

Plans render as pure markdown — no box-drawing characters or decorative symbols, per skills/shared/output-format/SKILL.md.

---

Approval Protocol

Formatting rule — the plan and the approval question are two separate messages, never one. First, output the filled plan-template.md as plain markdown chat text — headings, tables, and line breaks intact. Only after that, if using AskUserQuestion to collect approval, send the short "Plan approval gate" pattern from skills/shared/interaction-patterns/SKILL.md (question: "Plan ready. Do you approve?", options: Approved / Adjust first / Cancel). Never paste the plan body — or any part of the Steps table — into the question, header, or option description fields; those fields collapse line breaks and render the plan as an unreadable wall of text.

After presenting the plan:

1. Stop. Do not execute any step.
2. Wait for an explicit approval signal from the user — either a plain-text reply or the "Plan approval gate" quiz above.
3. Approval signals: "approved", "go ahead", "proceed", "yes", "looks good", "do it", or selecting "Approved — proceed"
4. Rejection signals: any feedback, correction, question, "no", or selecting "Adjust first" / "Cancel"

On rejection: acknowledge the feedback, adjust the plan, re-present the full plan. Never partially execute before replanning.

On approval: execute steps in order (agents with Execution Strategy Gate enabled MUST present the gate before executing). Report progress after each step. If execution reveals a problem that changes the plan, stop and replan before continuing.

---

Execution Strategy Gate

This optional gate applies between plan approval and execution. When an agent's configuration mandates it, the agent MUST present an interactive quiz after the user approves the plan and before executing any step.

Trigger

After the user signals approval ("approved", "go ahead", "proceed", "yes", "looks good", "do it"), before executing step 1.

Procedure

1. Read the worktree preferences from .dev-team-agents/user-data/preferences.json:

   python3 -c "import json;d=json.load(open('.dev-team-agents/user-data/preferences.json'));print(json.dumps({k:d.get(k) for k in['worktree_active','worktree_base_branch','worktree_path','worktree_docker_isolate']}))" 2>/dev/null
   

   If the file is unreadable or keys are absent, assume defaults: worktree_active=true, worktree_base_branch = auto-detected default, worktree_path=.worktrees, worktree_docker_isolate=true.

2. Determine the recommended option:

   • worktree_active == true → recommend Isolated worktree (first option)
   • worktree_active == false → recommend New branch (second option)
   • key absent → recommend Isolated worktree (first option)

3. Present the quiz using the AskUserQuestion tool. Use the user's preferred language from preferences.json → language. The recommended option MUST be the first option with the label showing it is recommended.

   Quiz structure (pt-BR example):

   {
     "questions": [
       {
         "question": "Como este plano deve ser executado?",
         "header": "Estratégia",
         "multiSelect": false,
         "options": [
           { "label": "Worktree isolada (Recomendado)"   
                
                
                
         
       
     
   
   

---

Replanning During Execution

If you discover mid-execution that a step cannot be done as planned:

1. Stop immediately.
2. Describe what was found and why the original plan needs to change.
3. Present an updated plan covering only the remaining steps.
4. Wait for approval again before continuing.

Do not silently improvise. If the plan changes, the user must know.

---

Agents Must Self-Enforce

Every agent in dev-team-agents is responsible for applying this protocol independently. The plan-mode rule is not optional and is not enforced by an external system — it is part of each agent's operating discipline.

If a user asks an agent to "just do it" without a plan: explain that the plan takes less than a minute to write, protects against misunderstandings, and produces better results. Then write the plan. Never skip it.

---

Context Self-Monitoring

After any response that involved reading many large files, producing long outputs, or running multiple tool calls in sequence, add a brief context advisory when appropriate:

⚡ Context advisory: this session has accumulated significant context. If responses start feeling less precise, run /compact or start a fresh session before the next task.

Apply this judgment after: reading 5+ files, producing 3+ large tool outputs, or a long back-and-forth session. You cannot see the exact percentage — err toward mentioning it. This supplements the automated hook-based warning, which fires based on a transcript token estimate.