For multi-step / complex tasks, how should this skill be used properly?

[wqh17101]

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?

[liangxiwei]

just use claude code's plan mode

[OthmanAdi]

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.

[OthmanAdi]

@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.

[OthmanAdi]

@wqh17101 中文版本：

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

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

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

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

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

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

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

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

[wqh17101]

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)?

[OthmanAdi]

@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.

[OthmanAdi]

@wqh17101 just commneted on what we need anthropics/claude-code#14047

[wqh17101]

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?

[OthmanAdi]

@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.

[OthmanAdi]

@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. 会话启动验证步骤

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

[wqh17101]

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

[lasmarois]

@OthmanAdi I just created a PR #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.