starred/planning-with-files
1
0
Fork 0
mirror of https://github.com/OthmanAdi/planning-with-files.git synced 2026-04-25 16:06:02 +03:00
Code Issues 5 Projects Releases 5 Packages Wiki Activity

[GH-ISSUE #19] For multi-step / complex tasks, how should this skill be used properly? #15

New issue
Open
opened 2026-03-03 18:49:57 +03:00 by kerem · 19 comments
kerem commented 2026-03-03 18:49:57 +03:00
Owner
Copy link

Originally created by @wqh17101 on GitHub (Jan 12, 2026).
Original GitHub issue: https://github.com/OthmanAdi/planning-with-files/issues/19

I am using this skill to handle a complex task. It has planned 5 steps for me. After completing the first step, the context length has already reached 140K, nearing the automatic compression trigger.
To ensure the best results, how should I proceed? For example, should I open a new window and ask it to continue working by referring to the task_plan.md file? If so, what would be an appropriate prompt to use?

Originally created by @wqh17101 on GitHub (Jan 12, 2026). Original GitHub issue: https://github.com/OthmanAdi/planning-with-files/issues/19 I am using this skill to handle a complex task. It has planned 5 steps for me. After completing the first step, the context length has already reached **140K**, nearing the automatic compression trigger. To ensure the best results, how should I proceed? For example, should I open a new window and ask it to continue working by referring to the task_plan.md file? If so, what would be an appropriate prompt to use?
kerem commented 2026-03-03 18:49:58 +03:00
Author
Owner
Copy link

@liangxiwei commented on GitHub (Jan 12, 2026):

just use claude code's plan mode

<!-- gh-comment-id:3736701154 --> @liangxiwei commented on GitHub (Jan 12, 2026): just use claude code's plan mode
kerem commented 2026-03-03 18:49:58 +03:00
Author
Owner
Copy link

@OthmanAdi commented on GitHub (Jan 12, 2026):

Good question @wqh17101 this is exactly the scenario the skill is designed for.

The solution: Start a new Claude session and use this prompt:

Read task_plan.md, findings.md, and progress.md to restore context. Continue from Phase [X].

The core idea of this skill is that your files are your memory, not the context window. When context fills up, you don't try to compress it you start fresh and reload from the files.

Before switching sessions, make sure your 3 planning files are fully updated. If you've been following the workflow (updating after each phase, logging discoveries), everything important is already on disk.

Why not use /resume or auto-compact?

  • /resume restores full message history — same context problem
  • Auto-compact summarizes and loses some details
  • Fresh session + read files gives you a clean slate with nothing lost

A possible improvement: I could create a branch with a RESUME.md template a file that gives you a ready-to-paste prompt and captures any volatile context before you switch sessions. If you'd like to test this, let me know and I'll set up a branch for you to try.

<!-- gh-comment-id:3736728436 --> @OthmanAdi commented on GitHub (Jan 12, 2026): Good question @wqh17101 this is exactly the scenario the skill is designed for. **The solution:** Start a new Claude session and use this prompt: ``` Read task_plan.md, findings.md, and progress.md to restore context. Continue from Phase [X]. ``` The core idea of this skill is that your **files are your memory**, not the context window. When context fills up, you don't try to compress it you start fresh and reload from the files. **Before switching sessions**, make sure your 3 planning files are fully updated. If you've been following the workflow (updating after each phase, logging discoveries), everything important is already on disk. **Why not use `/resume` or auto-compact?** - `/resume` restores full message history — same context problem - Auto-compact summarizes and loses some details - Fresh session + read files gives you a clean slate with nothing lost --- **A possible improvement:** I could create a branch with a `RESUME.md` template a file that gives you a ready-to-paste prompt and captures any volatile context before you switch sessions. If you'd like to test this, let me know and I'll set up a branch for you to try.
kerem commented 2026-03-03 18:49:58 +03:00
Author
Owner
Copy link

@OthmanAdi commented on GitHub (Jan 12, 2026):

@liangxiwei Plan mode solves a different problem it's for designing an approach before implementation.

This issue is about context filling up during execution of a multi-step task. Plan mode doesn't help when you're mid-task at 140K tokens.

The two can work together: plan mode for the design phase, planning-with-files for persisting state across sessions during execution.

<!-- gh-comment-id:3736728635 --> @OthmanAdi commented on GitHub (Jan 12, 2026): @liangxiwei Plan mode solves a different problem it's for designing an approach before implementation. This issue is about context filling up *during execution* of a multi-step task. Plan mode doesn't help when you're mid-task at 140K tokens. The two can work together: plan mode for the design phase, planning-with-files for persisting state across sessions during execution.
kerem commented 2026-03-03 18:49:59 +03:00
Author
Owner
Copy link

@OthmanAdi commented on GitHub (Jan 12, 2026):

@wqh17101 中文版本：

好问题 这正是这个技能设计的使用场景。

解决方案： 开启一个新的 Claude 会话，使用这个提示词：

读取 task_plan.md、findings.md 和 progress.md 来恢复上下文。从第 [X] 阶段继续。

这个技能的核心理念是：文件就是你的记忆，而不是上下文窗口。当上下文满了，不要试图压缩它 直接开新会话，从文件重新加载。

切换会话之前，确保你的3个计划文件已完全更新。如果你一直按照工作流程操作（每个阶段后更新、记录发现），所有重要内容都已经在磁盘上了。

为什么不用 /resume 或自动压缩？

  • /resume 恢复完整消息历史 同样的上下文问题
  • 自动压缩会总结并丢失一些细节
  • 新会话 + 读取文件 = 干净的开始，不丢失任何内容

可能的改进： 我可以创建一个带有 RESUME.md 模板的分支 这个文件会给你一个可直接复制的提示词，并在切换会话前捕获任何临时上下文。如果你想测试，告诉我，我会为你建立一个分支。

<!-- gh-comment-id:3736730057 --> @OthmanAdi commented on GitHub (Jan 12, 2026): @wqh17101 中文版本： 好问题 这正是这个技能设计的使用场景。 **解决方案：** 开启一个新的 Claude 会话，使用这个提示词： ``` 读取 task_plan.md、findings.md 和 progress.md 来恢复上下文。从第 [X] 阶段继续。 ``` 这个技能的核心理念是：**文件就是你的记忆**，而不是上下文窗口。当上下文满了，不要试图压缩它 直接开新会话，从文件重新加载。 **切换会话之前**，确保你的3个计划文件已完全更新。如果你一直按照工作流程操作（每个阶段后更新、记录发现），所有重要内容都已经在磁盘上了。 **为什么不用 `/resume` 或自动压缩？** - `/resume` 恢复完整消息历史 同样的上下文问题 - 自动压缩会总结并丢失一些细节 - 新会话 + 读取文件 = 干净的开始，不丢失任何内容 **可能的改进：** 我可以创建一个带有 `RESUME.md` 模板的分支 这个文件会给你一个可直接复制的提示词，并在切换会话前捕获任何临时上下文。如果你想测试，告诉我，我会为你建立一个分支。
kerem commented 2026-03-03 18:49:59 +03:00
Author
Owner
Copy link

@wqh17101 commented on GitHub (Jan 12, 2026):

That is good，i am glad to try the branch.

Additionally, regarding avoiding automatic compression, it currently seems the only solution is for a human to manually intervene and start a new window when the context is nearly full. Do you think we could integrate other skills or plugins to achieve automatic creation? Alternatively, could we break this down into multiple tasks handled by sub-agents (are the contexts of sub-agents calculated independently)?

<!-- gh-comment-id:3736761526 --> @wqh17101 commented on GitHub (Jan 12, 2026): That is good，i am glad to try the branch. Additionally, regarding avoiding automatic compression, it currently seems the only solution is for a human to manually intervene and start a new window when the context is nearly full. Do you think we could integrate other skills or plugins to achieve automatic creation? Alternatively, could we break this down into multiple tasks handled by sub-agents (are the contexts of sub-agents calculated independently)?
kerem commented 2026-03-03 18:49:59 +03:00
Author
Owner
Copy link

@OthmanAdi commented on GitHub (Jan 12, 2026):

@wqh17101 Great questions. I researched both and here's what I found:

1. Automatic Detection of Context Fullness

Currently not possible with Claude Code's architecture.

Here's what exists:

  • Claude internally receives warnings like <system_warning>Token usage: 35000/200000; 165000 remaining</system_warning> after tool calls (source)
  • You can manually check with /context command
  • Auto-compact triggers at ~95% capacity (~40-45K buffer remaining)

What's missing:

  • No hook/event system to trigger custom actions at a threshold
  • No way for a skill or plugin to intercept "context nearly full" and auto-create a handoff
  • Feature requests exist (#12565, #10593) but aren't implemented

Bottom line: Until Claude Code adds a context-threshold hook, manual intervention is the only option.

2. Sub-Agents with Independent Context

Yes, sub-agents have isolated context windows — but there's nuance.

How it works (source):

  • Sub-agents run in their own context window
  • They return a summary to the main agent, not the full output
  • Main agent stays clean, sub-agent's verbose work stays isolated
  • Up to 10 concurrent agents

The complication — context inheritance varies by agent type (source):

Agent Type Context Behavior
Explore Fresh slate — no inherited context
general-purpose Inherits full context from parent
plan Inherits full context from parent
Custom subagent Configurable via .claude/agents/

So if you spawn a general-purpose sub-agent for Phase 2, it might inherit the 140K from Phase 1. That defeats the purpose.

Potential solution: Create a custom subagent that enforces fresh context:

# .claude/agents/phase-executor.md
---
name: phase-executor
description: Execute a specific phase from task_plan.md with fresh context
tools: Read, Write, Edit, Bash, Glob, Grep
---

## Instructions
1. Read task_plan.md, findings.md, progress.md to understand current state
2. Execute the specified phase completely
3. Update all three planning files with results
4. Return summary of what was accomplished

I haven't tested this yet — it needs verification whether custom subagents truly start fresh or inherit context.

What Definitely Works Now

The manual approach I described earlier:

  1. Update your 3 planning files before context fills
  2. Start new session
  3. Prompt: Read task_plan.md, findings.md, progress.md and continue from Phase X

Next Steps

I'll set up the feature/session-handoff branch with the RESUME.md template for you to test.

For the sub-agent approach — I can also create an experimental phase-executor subagent definition if you want to test whether custom subagents get fresh context. Let me know.

<!-- gh-comment-id:3736842708 --> @OthmanAdi commented on GitHub (Jan 12, 2026): @wqh17101 Great questions. I researched both and here's what I found: ## 1. Automatic Detection of Context Fullness **Currently not possible** with Claude Code's architecture. Here's what exists: - Claude internally receives warnings like `<system_warning>Token usage: 35000/200000; 165000 remaining</system_warning>` after tool calls ([source](https://platform.claude.com/docs/en/build-with-claude/context-windows)) - You can manually check with `/context` command - Auto-compact triggers at ~95% capacity (~40-45K buffer remaining) What's missing: - No hook/event system to trigger custom actions at a threshold - No way for a skill or plugin to intercept "context nearly full" and auto-create a handoff - Feature requests exist ([#12565](https://github.com/anthropics/claude-code/issues/12565), [#10593](https://github.com/anthropics/claude-code/issues/10593)) but aren't implemented **Bottom line:** Until Claude Code adds a context-threshold hook, manual intervention is the only option. ## 2. Sub-Agents with Independent Context **Yes, sub-agents have isolated context windows** — but there's nuance. How it works ([source](https://claudelog.com/mechanics/task-agent-tools/)): - Sub-agents run in their own context window - They return a **summary** to the main agent, not the full output - Main agent stays clean, sub-agent's verbose work stays isolated - Up to 10 concurrent agents The complication — **context inheritance varies by agent type** ([source](https://alexop.dev/posts/claude-code-customization-guide-claudemd-skills-subagents/)): | Agent Type | Context Behavior | |------------|------------------| | Explore | Fresh slate — no inherited context | | general-purpose | Inherits full context from parent | | plan | Inherits full context from parent | | Custom subagent | Configurable via `.claude/agents/` | So if you spawn a `general-purpose` sub-agent for Phase 2, it might inherit the 140K from Phase 1. That defeats the purpose. **Potential solution:** Create a custom subagent that enforces fresh context: ```markdown # .claude/agents/phase-executor.md --- name: phase-executor description: Execute a specific phase from task_plan.md with fresh context tools: Read, Write, Edit, Bash, Glob, Grep --- ## Instructions 1. Read task_plan.md, findings.md, progress.md to understand current state 2. Execute the specified phase completely 3. Update all three planning files with results 4. Return summary of what was accomplished ``` **I haven't tested this yet** — it needs verification whether custom subagents truly start fresh or inherit context. ## What Definitely Works Now The manual approach I described earlier: 1. Update your 3 planning files before context fills 2. Start new session 3. Prompt: `Read task_plan.md, findings.md, progress.md and continue from Phase X` ## Next Steps I'll set up the `feature/session-handoff` branch with the `RESUME.md` template for you to test. For the sub-agent approach — I can also create an experimental `phase-executor` subagent definition if you want to test whether custom subagents get fresh context. Let me know.
kerem commented 2026-03-03 18:49:59 +03:00
Author
Owner
Copy link

@OthmanAdi commented on GitHub (Jan 12, 2026):

@wqh17101 just commneted on what we need https://github.com/anthropics/claude-code/issues/14047

<!-- gh-comment-id:3736867893 --> @OthmanAdi commented on GitHub (Jan 12, 2026): @wqh17101 just commneted on what we need https://github.com/anthropics/claude-code/issues/14047
kerem commented 2026-03-03 18:49:59 +03:00
Author
Owner
Copy link

@wqh17101 commented on GitHub (Jan 12, 2026):

What do you think about this article https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents ？
Is there anything worth taking inspiration from?

<!-- gh-comment-id:3737084244 --> @wqh17101 commented on GitHub (Jan 12, 2026): What do you think about this article https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents ？ Is there anything worth taking inspiration from?
kerem commented 2026-03-03 18:49:59 +03:00
Author
Owner
Copy link

@OthmanAdi commented on GitHub (Jan 12, 2026):

@wqh17101 This is a solid reference — it's from Anthropic's own engineering team and basically confirms the approach this skill takes.

What they do:

  • Use claude-progress.txt to track completed work (same idea as our progress.md)
  • Start each session with: "Read the git logs and progress files to get up to speed" — exactly what we're doing
  • Accept that context doesn't carry over between sessions — files are the bridge

Patterns we could borrow:

Pattern What It Does How We Could Use It
init.sh Setup script that runs each session Ensures consistent startup state
Git commits as checkpoints Each feature = one commit, easy rollback Commit after each phase
Feature list (JSON) Requirements with pass/fail tracking Enhance task_plan.md with status
Session-start testing Run tests first to catch hidden bugs Verify state before continuing

The key insight:

"Each new session begins with no memory of what came before"

So fresh session + read files isn't a hack — it's the intended pattern.

What I'll add to the repo:

  1. init.sh template for session setup
  2. Pass/fail status tracking in task_plan.md
  3. Git checkpoint workflow in docs
  4. Session-start verification step

Thanks for digging this up — really helpful.

<!-- gh-comment-id:3737111201 --> @OthmanAdi commented on GitHub (Jan 12, 2026): @wqh17101 This is a solid reference — it's from Anthropic's own engineering team and basically confirms the approach this skill takes. **What they do:** - Use `claude-progress.txt` to track completed work (same idea as our `progress.md`) - Start each session with: "Read the git logs and progress files to get up to speed" — exactly what we're doing - Accept that context doesn't carry over between sessions — files are the bridge **Patterns we could borrow:** | Pattern | What It Does | How We Could Use It | |---------|--------------|---------------------| | `init.sh` | Setup script that runs each session | Ensures consistent startup state | | Git commits as checkpoints | Each feature = one commit, easy rollback | Commit after each phase | | Feature list (JSON) | Requirements with pass/fail tracking | Enhance `task_plan.md` with status | | Session-start testing | Run tests first to catch hidden bugs | Verify state before continuing | **The key insight:** > "Each new session begins with no memory of what came before" So fresh session + read files isn't a hack — it's the intended pattern. **What I'll add to the repo:** 1. `init.sh` template for session setup 2. Pass/fail status tracking in `task_plan.md` 3. Git checkpoint workflow in docs 4. Session-start verification step Thanks for digging this up — really helpful.
kerem commented 2026-03-03 18:49:59 +03:00
Author
Owner
Copy link

@OthmanAdi commented on GitHub (Jan 12, 2026):

@wqh17101 中文版本：

这是个很好的参考 — 来自 Anthropic 自己的工程团队，基本上验证了这个技能的核心思路。

他们的做法：

  • 用 claude-progress.txt 记录完成的工作（和我们的 progress.md 一样的思路）
  • 每个会话开始时："读取 git 日志和进度文件来了解之前的工作" — 和我们做的完全一样
  • 接受上下文不会跨会话保留 — 文件就是桥梁

我们可以借鉴的模式：

模式 作用 如何应用
init.sh 每次会话运行的启动脚本 确保一致的启动状态
Git 提交作为检查点 每个功能 = 一次提交，方便回滚 每个阶段后提交
功能列表 (JSON) 带通过/失败状态的需求追踪 增强 task_plan.md 的状态追踪
会话启动测试 先运行测试，发现隐藏的 bug 继续工作前先验证状态

关键洞察：

"每个新会话开始时都没有之前的记忆"

所以"新会话 + 读取文件"不是临时方案 — 这就是官方推荐的模式。

我会添加到仓库的内容：

  1. init.sh 会话启动模板
  2. task_plan.md 中增加通过/失败状态追踪
  3. 文档中添加 Git 检查点工作流
  4. 会话启动验证步骤

感谢你找到这篇文章 — 非常有帮助。

<!-- gh-comment-id:3737111595 --> @OthmanAdi commented on GitHub (Jan 12, 2026): @wqh17101 中文版本： 这是个很好的参考 — 来自 Anthropic 自己的工程团队，基本上验证了这个技能的核心思路。 **他们的做法：** - 用 `claude-progress.txt` 记录完成的工作（和我们的 `progress.md` 一样的思路） - 每个会话开始时："读取 git 日志和进度文件来了解之前的工作" — 和我们做的完全一样 - 接受上下文不会跨会话保留 — 文件就是桥梁 **我们可以借鉴的模式：** | 模式 | 作用 | 如何应用 | |------|------|----------| | `init.sh` | 每次会话运行的启动脚本 | 确保一致的启动状态 | | Git 提交作为检查点 | 每个功能 = 一次提交，方便回滚 | 每个阶段后提交 | | 功能列表 (JSON) | 带通过/失败状态的需求追踪 | 增强 `task_plan.md` 的状态追踪 | | 会话启动测试 | 先运行测试，发现隐藏的 bug | 继续工作前先验证状态 | **关键洞察：** > "每个新会话开始时都没有之前的记忆" 所以"新会话 + 读取文件"不是临时方案 — 这就是官方推荐的模式。 **我会添加到仓库的内容：** 1. `init.sh` 会话启动模板 2. `task_plan.md` 中增加通过/失败状态追踪 3. 文档中添加 Git 检查点工作流 4. 会话启动验证步骤 感谢你找到这篇文章 — 非常有帮助。
kerem commented 2026-03-03 18:49:59 +03:00
Author
Owner
Copy link

@wqh17101 commented on GitHub (Jan 14, 2026):

Let me know when you're ready. I'm really looking forward to it! -- handoff

<!-- gh-comment-id:3748222256 --> @wqh17101 commented on GitHub (Jan 14, 2026): Let me know when you're ready. I'm really looking forward to it! -- handoff
kerem commented 2026-03-03 18:49:59 +03:00
Author
Owner
Copy link

@lasmarois commented on GitHub (Jan 17, 2026):

@OthmanAdi I just created a PR https://github.com/OthmanAdi/planning-with-files/pull/33 that proposes a more robust workflow:

Before (default): Auto-compact on, context managed automatically by Claude Code

New recommendation:

  1. Disable auto-compact (use full context window)
  2. /planning-with-files to start
  3. Work until context fills up
  4. /clear when full
  5. /planning-with-files again → auto-catches up → continue

Why: Maximizes usable context per session, and the skill now handles the recovery automatically instead of relying on auto-compact's summarization.

<!-- gh-comment-id:3764312058 --> @lasmarois commented on GitHub (Jan 17, 2026): @OthmanAdi I just created a PR https://github.com/OthmanAdi/planning-with-files/pull/33 that proposes a more robust workflow: **Before (default):** Auto-compact on, context managed automatically by Claude Code **New recommendation:** 1. **Disable auto-compact** (use full context window) 2. `/planning-with-files` to start 3. Work until context fills up 4. `/clear` when full 5. `/planning-with-files` again → auto-catches up → continue **Why:** Maximizes usable context per session, and the skill now handles the recovery automatically instead of relying on auto-compact's summarization.
kerem commented 2026-03-03 18:49:59 +03:00
Author
Owner
Copy link

@OthmanAdi commented on GitHub (Jan 17, 2026):

@wqh17101 Building those features now! I'll add them in a feature/anthropic-patterns branch and tag you when ready.

The features based on the Anthropic article:

  • Session initialization script (init.sh)
  • Pass/fail status tracking in task_plan.md
  • Git checkpoint workflow documentation
  • Session-start verification step

Should have this ready soon!

<!-- gh-comment-id:3764391431 --> @OthmanAdi commented on GitHub (Jan 17, 2026): @wqh17101 Building those features now! I'll add them in a `feature/anthropic-patterns` branch and tag you when ready. The features based on the Anthropic article: - Session initialization script (`init.sh`) - Pass/fail status tracking in task_plan.md - Git checkpoint workflow documentation - Session-start verification step Should have this ready soon!
kerem commented 2026-03-03 18:49:59 +03:00
Author
Owner
Copy link

@OthmanAdi commented on GitHub (Jan 17, 2026):

@wqh17101 The features are ready! 🎉

I've implemented all the session management patterns from the Anthropic article in the feature/anthropic-patterns branch.

What's New

  1. Session Initialization Script (init-session.sh / .ps1)

    • Run at start of every session
    • Verifies planning files exist
    • Shows current phase, git status, last commit
    • Logs session start to progress.md

  2. Pass/Fail Status Tracking

    • Enhanced task_plan.md template with status icons
    • ⏸️ Pending | 🔄 In Progress | ✅ Pass | ❌ Fail | ⏭️ Skipped
    • Test Results table for each phase
    • Git Checkpoints table

  3. Git Checkpoint Workflow

    • New docs: docs/git-checkpoints.md
    • "One phase, one commit" pattern
    • Use commits as rollback points

  4. Session-Start Verification

    • Automated checklist in init-session script
    • Verifies environment before starting work

Try It Out

git fetch origin
git checkout feature/anthropic-patterns

# In your project directory:
bash scripts/init-session.sh

See IMPLEMENTATION_SUMMARY.md in the branch for full usage instructions.

Let me know how it works for you! Once you approve, I'll merge to main.

Ahmad

<!-- gh-comment-id:3764419870 --> @OthmanAdi commented on GitHub (Jan 17, 2026): @wqh17101 The features are ready! 🎉 I've implemented all the session management patterns from the Anthropic article in the **feature/anthropic-patterns** branch. ## What's New 1. **Session Initialization Script** (init-session.sh / .ps1) - Run at start of every session - Verifies planning files exist - Shows current phase, git status, last commit - Logs session start to progress.md 2. **Pass/Fail Status Tracking** - Enhanced task_plan.md template with status icons - ⏸️ Pending | 🔄 In Progress | ✅ Pass | ❌ Fail | ⏭️ Skipped - Test Results table for each phase - Git Checkpoints table 3. **Git Checkpoint Workflow** - New docs: docs/git-checkpoints.md - "One phase, one commit" pattern - Use commits as rollback points 4. **Session-Start Verification** - Automated checklist in init-session script - Verifies environment before starting work ## Try It Out ```bash git fetch origin git checkout feature/anthropic-patterns # In your project directory: bash scripts/init-session.sh ``` See IMPLEMENTATION_SUMMARY.md in the branch for full usage instructions. Let me know how it works for you! Once you approve, I'll merge to main. Ahmad
kerem commented 2026-03-03 18:49:59 +03:00
Author
Owner
Copy link

@wqh17101 commented on GitHub (Jan 18, 2026):

Wow, that's awesome! I'll give it a try next week.

Once this branch is merged, the new workflow is as follows:

Start every session (new or existing project) by running:

bash ${CLAUDE_PLUGIN_ROOT}/scripts/init-session.sh
This will verify your environment and tell you where you left off.

Work through one phase at a time from your task_plan.md.

Before marking a phase as ✅ Pass, fill out the Test Results table for that phase. This ensures you don't mark things as done prematurely.

After completing a phase, commit your changes:

git add .
git commit -m "feat(Phase X): Description of what was done"
Log the commit hash in the Git Checkpoints table in task_plan.md.

If your context fills up, simply start a new Claude session and run init-session.sh again. It will read your planning files and get you back on track.

question 1

How to start a new Claude session and run init-session.sh again ? By input "Continue using the "planning-with-files" skill."?

question 2

After completing a phase, commit your changes:

Is this process manual or automated?

<!-- gh-comment-id:3764874403 --> @wqh17101 commented on GitHub (Jan 18, 2026): Wow, that's awesome! I'll give it a try next week. ``` Once this branch is merged, the new workflow is as follows: Start every session (new or existing project) by running: bash ${CLAUDE_PLUGIN_ROOT}/scripts/init-session.sh This will verify your environment and tell you where you left off. Work through one phase at a time from your task_plan.md. Before marking a phase as ✅ Pass, fill out the Test Results table for that phase. This ensures you don't mark things as done prematurely. After completing a phase, commit your changes: git add . git commit -m "feat(Phase X): Description of what was done" Log the commit hash in the Git Checkpoints table in task_plan.md. If your context fills up, simply start a new Claude session and run init-session.sh again. It will read your planning files and get you back on track. ``` ## question 1 How to start a new Claude session and run init-session.sh again ? By input "Continue using the "planning-with-files" skill."? ## question 2 > After completing a phase, commit your changes: Is this process manual or automated?
kerem commented 2026-03-03 18:50:00 +03:00
Author
Owner
Copy link

@OthmanAdi commented on GitHub (Jan 18, 2026):

@wqh17101 The features are ready! 🎉

I've implemented all the session management patterns from the Anthropic article in the ** branch.

What's New

  1. Session Initialization Script (\ / )

    • Run at start of every session
    • Verifies planning files exist
    • Shows current phase, git status, last commit
    • Logs session start to progress.md

  2. Pass/Fail Status Tracking

    • Enhanced \ template with status icons
    • ⏸️ Pending | 🔄 In Progress | ✅ Pass | ❌ Fail | ⏭️ Skipped
    • Test Results table for each phase
    • Git Checkpoints table

  3. Git Checkpoint Workflow

    • New docs: - "One phase, one commit" pattern
    • Use commits as rollback points

  4. Session-Start Verification

    • Automated checklist in init-session script
    • Verifies environment before starting work

Try It Out


See \ in the branch for full usage instructions.

Let me know how it works for you! Once you approve, I'll merge to main.

Ahmad

<!-- gh-comment-id:3765095755 --> @OthmanAdi commented on GitHub (Jan 18, 2026): @wqh17101 The features are ready\! 🎉 I've implemented all the session management patterns from the Anthropic article in the **\** branch. ## What's New 1. **Session Initialization Script** (\ / \) - Run at start of every session - Verifies planning files exist - Shows current phase, git status, last commit - Logs session start to progress.md 2. **Pass/Fail Status Tracking** - Enhanced \ template with status icons - ⏸️ Pending | 🔄 In Progress | ✅ Pass | ❌ Fail | ⏭️ Skipped - Test Results table for each phase - Git Checkpoints table 3. **Git Checkpoint Workflow** - New docs: - "One phase, one commit" pattern - Use commits as rollback points 4. **Session-Start Verification** - Automated checklist in init-session script - Verifies environment before starting work ## Try It Out \ See \ in the branch for full usage instructions. Let me know how it works for you\! Once you approve, I'll merge to main. Ahmad
kerem commented 2026-03-03 18:50:00 +03:00
Author
Owner
Copy link

@wqh17101 commented on GitHub (Jan 19, 2026):

Some problems. https://github.com/OthmanAdi/planning-with-files/discussions/36#discussioncomment-15543845

<!-- gh-comment-id:3767997656 --> @wqh17101 commented on GitHub (Jan 19, 2026): Some problems. https://github.com/OthmanAdi/planning-with-files/discussions/36#discussioncomment-15543845
kerem commented 2026-03-03 18:50:00 +03:00
Author
Owner
Copy link

@yuanhaorannnnnn commented on GitHub (Feb 4, 2026):

@liangxiwei Plan mode solves a different problem it's for designing an approach before implementation.

This issue is about context filling up during execution of a multi-step task. Plan mode doesn't help when you're mid-task at 140K tokens.

The two can work together: plan mode for the design phase, planning-with-files for persisting state across sessions during execution.

so your advice is using planning-with-files in normal mode intead plan mode?

<!-- gh-comment-id:3844909910 --> @yuanhaorannnnnn commented on GitHub (Feb 4, 2026): > [@liangxiwei](https://github.com/liangxiwei) Plan mode solves a different problem it's for designing an approach before implementation. > > This issue is about context filling up _during execution_ of a multi-step task. Plan mode doesn't help when you're mid-task at 140K tokens. > > The two can work together: plan mode for the design phase, planning-with-files for persisting state across sessions during execution. so your advice is using planning-with-files in normal mode intead plan mode?
kerem commented 2026-03-03 18:50:00 +03:00
Author
Owner
Copy link

@OthmanAdi commented on GitHub (Feb 4, 2026):

@yuanhaorannnnnn Thanks for the question. you should use both, they complement each other.

Plan mode = designing your approach before you start (what to build, how to structure it)
planning-with-files = persisting your state while you're executing (so you never lose progress)

The real value of this skill is that your files become your memory. Claude's context window is limited and volatile, once it fills up or you start a new session, everything is gone. planning-with-files solves that by keeping task_plan.md, findings.md, and progress.md as persistent state on disk.

So the workflow is:

  1. Use plan mode to design your approach
  2. Use planning-with-files in normal mode to execute, it tracks progress, logs discoveries, and records errors across sessions
  3. When context fills up, start a fresh session and just read the files back. you're exactly where you left off, nothing lost

No other tool gives you that kind of continuity across sessions. That's the core value.

<!-- gh-comment-id:3850071768 --> @OthmanAdi commented on GitHub (Feb 4, 2026): @yuanhaorannnnnn Thanks for the question. you should use both, they complement each other. **Plan mode** = designing your approach before you start (what to build, how to structure it) **planning-with-files** = persisting your state while you're executing (so you never lose progress) The real value of this skill is that your **files become your memory**. Claude's context window is limited and volatile, once it fills up or you start a new session, everything is gone. planning-with-files solves that by keeping task_plan.md, findings.md, and progress.md as persistent state on disk. So the workflow is: 1. Use plan mode to design your approach 2. Use planning-with-files in normal mode to execute, it tracks progress, logs discoveries, and records errors across sessions 3. When context fills up, start a fresh session and just read the files back. you're exactly where you left off, nothing lost No other tool gives you that kind of continuity across sessions. That's the core value.
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
master
fix/123-125-badge-and-windows-hook
ide/codex
ide/pi-agent
ide/factory
ide/mastra
ide/codebuddy
ide/opencode
ide/gemini
ide/continue
ide/cursor
ide/copilot
ide/kiro
feat/analytics-subagent
audit/ide-support-cleanup
feat/add-openclaw-github-repo-commander
experimental/isolated-planning
legacy-rules-support
feature/docs-plugin-vs-skill
feature/session-handoff
copilot/fix-template-files-copy
legacy
v2.35.0
v2.34.1
v2.34.0
v2.33.0
v2.32.0
v2.31.0
v2.30.1
v2.30.0
v2.29.0
v2.28.0
v2.27.0
v2.26.2
v2.26.1
v2.26.0
v2.25.0
v2.24.0
v2.23.1
v2.23.0
v2.22.0
v2.21.0
v2.20.0
v2.19.0
v2.18.3
v2.18.2
v2.18.1
v2.18.0
v2.16.1
v2.16.0
v2.15.1
v2.15.0
v2.14.0
v2.13.0
v2.12.0
v2.11.0
v2.10.0
v2.9.0
v2.8.0
v2.7.1
v2.7.0
v2.6.0
v2.5.0
v2.4.1
v2.4.0
v2.3.0
v2.2.2
v2.2.1
v2.2.0
v2.1.1
v2.1.0
v2.0.1
v2.0.0
v1.0.0
Labels
Clear labels   
bug

   
pull-request

Mirrored from GitHub Pull Request

No labels
bug
pull-request
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
starred/planning-with-files#15
No description provided.