Good first issue · Documentation
Take issue #300 Fix ambiguous plan-selection instructions.
The resolver refuses to guess between active plans. Some manual instructions still say “choose the newest.” Help make them agree.
Your AI Agent Says
'Done.' It's Lying.
The patch is written. The boundary tests aren’t.
Give the next session a plan it can pick up.
A planning skill for coding agents. Three files. In your project.
Context resets.
The plan stays.
Try clearing the conversation
Interactive illustrationState saved to the project
Current session
“Implementation done.”
Expiry boundary tests still pending
task_plan.md✓ saved
Ship the expiry fix
- ✓ Find the cause
- ✓ Write the patch
- Add boundary tests
Next: test just before & at expiry.
The unfinished step is saved, even if the chat disappears.
A sketch of the workflow, not a live agent run.
Stop keeping the whole
project in the conversation.
The goal, the decisions, the next step. Save them where you can inspect them, review the changes, and carry them into another session.
task_plan.mdExample file
# Ship the expiry fix
## Goal
Reject expired tokens at the exact boundary.
## Phases
[x] Reproduce the bug
[x] Implement the fix
[ ] Verify expiry boundaries
## Next step
Test one second before expiry, then at expiry.# Findings
## Boundary decision
The token is invalid when now >= expires_at.
## Keep
Use the existing UTC clock abstraction.
Keep the public API unchanged.
## Avoid
Do not compare formatted date strings.# Progress
## Completed
Reproduced the expired-token acceptance bug.
Changed the boundary comparison.
## Verification
Existing validation tests passed.
New expiry boundary tests: not run.
## Resume here
Write and run the missing boundary cases.Plain Markdown. Readable by you and your agents. Only recorded work can be recovered.
Works with your agent.
On its terms.
Keep the file-based workflow across tools. Add the lifecycle support your host actually provides.
Find your host’s setupBring the plan back
Activated integrations surface selected planning context at supported lifecycle points.
Catch unfinished phases
Optional gated mode can block a stop or ask for another pass, with retry and stall limits. Some hosts can only notify.
Give parallel work its own plan
Pin each task to its own plan or use separate worktrees. One shared selection is not a boundary between sessions.
Completion checks read recorded state. Tests and review establish whether the code is right.
New session.
Same next step.
Save the task before the conversation ends. Let the next session start with what remains.
5-second illustrated walkthroughMake the next session
better for someone else.
A small docs fix. A reproducible failure. A clearer example.
Here are three places your contribution can help.
Reproducible example · Evaluation
Take issue #303 Show what survives a reset.
Try the current file-only recovery default. Share your host, saved state, expected next step and actual result. Missed steps are useful evidence.
Open discussion · Long-running work
Join discussion #218 Put a large plan through its paces.
Move the active phase deep into a long file. Compare default and smart injection. Show which decisions and next steps remain visible.
Another first contribution: fix the Codex opt-out docs (#302). Check the thread before starting. Read the contribution guide ↗
The conversation can end.
The work can carry on.
Install the skill. Give it a real task.
Keep the next step in the project.
npx skills add OthmanAdi/planning-with-files --skill planning-with-files -gHooks and native plugins may need additional setup.