Plan mode: agree on the work first

Back to the Codex learning hub

Goal and preparation

Start with clear requests. Use Plan when choices remain, code needs investigation or work has several steps. Codex can gather context, ask questions and propose a plan. Merely writing “plan” is insufficient, and Plan is not the same as a read-only sandbox. Verify permissions and directory separately.

Step 1: Establish a repeatable starting point

Get the ZIP from your first project. Copy the five files inside start into a new codex-plan-lab root: index.html, style.css, app.js, core.mjs and core.test.mjs. Do not use expected, whose filters already work. Open that folder, verify the terminal path and node --version, and keep original start files for restoration. Use this isolated lab.

node --test core.test.mjs

Run the baseline and retain its summary: start should pass two tests and fail one. This is an intentional defect; do not weaken tests. If results differ, verify start rather than broken or expected; they are distinct fixtures.

For UI checks, reuse the first project's Python preview. Stop your earlier practice server and launch from codex-plan-lab. Windows: py -m http.server 4173 --bind 127.0.0.1; macOS/Linux: replace py with python3. Open http://127.0.0.1:4173 rather than double-clicking HTML. Keep this terminal for the server, use another for tests, and stop the server with Ctrl+C when finished.

Once the preview opens, preserve any old practice records you still need. Under About this exercise, use Reset practice data, choose All tasks and verify an empty list. Add Read and Build, complete only Read, then select Active/Completed: both incorrectly show these two tasks. Reset only the fixture data, not all browser storage.

Step 2: Enable Plan and investigate

Create a task for the lab in the desktop app and use /plan in its composer or Plan mode in Add. In CLI, run codex from the lab and enter /plan when idle; the official guide also lists Shift+Tab for toggling. Check the mode before sending the prompt. Enter /plan inside Codex, not your shell. If unavailable, update and inspect supported commands instead of guessing shortcuts.

Plan before implementation. In this codex-plan-lab, inspect index.html, app.js, core.mjs and core.test.mjs. Do not edit files yet.
Goal: make All, Active and Completed filters correct.
Keep the current UI, storage format and task ordering. Add no dependencies.
Report the existing selector and event wiring, the failing behavior and the smallest implementation scope. Ask about unresolved behavior before proposing a plan.
The plan must name files, acceptance cases, test commands and a scoped restoration method. Separate observations from assumptions.

Check whether it identifies the existing selector in index.html, wiring in app.js and missing visibleTasks logic in core.mjs. If it proposes a UI rewrite or framework, request evidence that makes this necessary. Specify All as default, Active as unfinished, Completed as finished, unchanged order and empty output for empty input. Resolve these choices explicitly.

Step 3: Review and revise the plan

A useful plan looks like the reference below: inputs, edit locations and success criteria, not merely “analyze, develop, test.” Wording may vary but scope must be assessable. Test outcomes here are future acceptance criteria, not completed results. Separate manual preview checks from whether the agent has browser tools.

# Filter plan
1. Read the existing selector, event handler and tests. Confirm the start fixture's failing filter assertion.
2. Edit only visibleTasks in core.mjs: active selects unfinished tasks; completed selects finished tasks; all keeps every task in order.
3. Run node --test core.test.mjs. Target: all 3 tests pass without changing their assertions.
4. Preview Read (completed) and Build (active). Expect All=Read,Build; Active=Build; Completed=Read. Empty lists stay empty.
Scope: no dependencies, storage migrations, UI redesign or deployment.
Restore: copy only core.mjs from the preserved start fixture back into this lab. The known failing baseline should return.

Add: “Do not mutate the input array; include how to verify this.” The revision should explain that filter creates a new array without changing task objects. All may return the original array but must not reorder or alter it. Resolve any newly necessary edits and update the allowed scope explicitly rather than relying on an ambiguous “OK.”

Reject a detailed but incorrect plan before implementation

Worked case: a plan proposes rebuilding filter buttons, installing a package and changing tests to pass. Detail does not make it suitable. The buttons and events already exist; visibleTasks is the gap. Identify steps unsupported by the code and request the revision below. Check scope, empty input and nonmutation again before implementation.

Revise the plan only; do not implement yet. Use the existing filter controls and event wiring. Limit program changes to visibleTasks in core.mjs, add no dependencies and preserve all test assertions. For each proposed change, cite the observed gap. Include empty input, stable order, no input mutation, actual test execution and separate browser checks. Mark unknown facts instead of assuming them.

Step 4: Implement and verify

After review, switch back using the visible mode control; in CLI follow the current Shift+Tab hint, and in desktop verify Plan is off. Send the explicit request below. If you receive another plan, inspect mode rather than repeatedly resubmitting. Review the diff: this lab needs only the function in core.mjs. The reference is for comparison, not blindly replacing the whole file.

Implement the reviewed filter plan now. Modify only visibleTasks in core.mjs. Preserve task order and do not mutate inputs. Keep tests and other files unchanged. Run node --test core.test.mjs, inspect the final diff and report actual results. If browser verification is unavailable, list the manual cases as NOT RUN. Do not publish or deploy this practice project.

export function visibleTasks(tasks, filter) {
  if (filter === "active") return tasks.filter((task) => !task.completed);
  if (filter === "completed") return tasks.filter((task) => task.completed);
  return tasks;
}

Rerun tests: the reference patch should pass all three. Then check the UI matrix. Avoid old localStorage by using a dedicated practice browser profile or deleting only fictional tasks through the UI; do not clear your everyday browser's entire storage. Add Read and Build, complete only Read, and also test an empty list. Record actual and unperformed checks.

Troubleshooting, restoration and completion

If vague, ask for files and acceptance cases per step. If assumptions contradict code, reread it. Review and remove out-of-scope test/dependency changes. Remaining in Plan explains no implementation; it is not a website defect. If implementation is permission-blocked, resolve the specific required access rather than disabling every protection. Without test output, record NOT RUN.

Keep the final plan, core.mjs-only diff, three test outcomes and UI matrix to distinguish a ready plan from an accepted feature. To repeat, restore only start/core.mjs into the lab and expect the original two passes/one failure. Do not reset unrelated folders or authentication. Diagram 1 is baseline, 2 investigation/review, 3 implementation/acceptance. For longer tasks, write a handoff.

Back to the Codex learning hub

Read the full description

Questions to /plan to Implementation

• AI tools
• Tutorials
• Codex