Task Plan: Build Command-Line Todo App【免费下载链接】planning-with-filesPersistent file-based planning for AI coding agents and long-running tasks. Crash-proof markdown plans, session recovery after /clear and compaction, per-turn re-injection against context rot, deterministic completion gate. Manus-style. Install from npm, the Claude Code plugin marketplace, or npx skills. Codex, Cursor, OpenCode, 60 agents.项目地址: https://gitcode.com/GitHub_Trending/pl/planning-with-filesGoalCreate a Python CLI todo app with add, list, and delete functionality.Current PhasePhase 1PhasesPhase 1: Requirements DiscoveryUnderstand user intentIdentify constraints and requirementsDocument findings in findings.mdStatus:in_progressPhase 2: Planning StructureDefine technical approachCreate project structureDocument decisions with rationaleStatus:pendingPhase 3: ImplementationWrite todo.py with core functionsImplement add functionalityImplement list functionalityImplement delete functionalityStatus:pendingPhase 4: Testing VerificationTest add operationTest list operationTest delete operationVerify error handlingStatus:pendingPhase 5: DeliveryReview code qualityEnsure all features workDeliver to userStatus:pendingKey QuestionsShould tasks persist between sessions? (Yes - need file storage)What format for storing tasks? (JSON file)Command-line interface style? (Simple argparse)Decisions MadeDecisionRationaleErrors EncounteredErrorAttemptResolution1NotesUpdate phase status as you progress: pending → in_progress → completeRe-read this plan before major decisions (plan recitation)Log ALL errors - they help avoid repetition注意初始状态的设计细节任务被拆成 5 个可验证的阶段需求发现、规划与结构、实现、测试与验证、交付每个阶段带 - [ ] 复选框和 pending/in_progress/complete 三态状态标记Key Questions 先列出悬而未决的问题Decisions Made 与 Errors Encountered 留空待填。这套结构与 [templates/task_plan.md](https://link.gitcode.com/i/c45f3c1f9cbd02411c841b5db5e8d295) 模板一致模板中还额外包含 Next Step 小节——[SKILL.md](https://link.gitcode.com/i/82dea64e4bd57041fb3314a244554df0) 要求每当阶段状态变化时就刷新 ## Next Step让它明确写出下一个唯一动作。 ### findings.md初始状态 markdown # Findings Decisions ## Requirements - Command-line interface - Add tasks - List all tasks - Delete tasks - Python implementation - Tasks should persist (survive app restart) ## Research Findings - (To be filled as we explore) ## Technical Decisions | Decision | Rationale | |----------|-----------| | | | ## Issues Encountered | Issue | Resolution | |-------|------------| | | | ## Resources - Python argparse documentation (to be referenced) ## Visual/Browser Findings - (To be updated after research) --- *Update this file after every 2 view/browser/search operations* *This prevents visual information from being lost*findings.md的尾部注释对应 SKILL.md 的2-Action RuleAfter every 2 view/browser/search operations, IMMEDIATELY save key findings to text files.之所以如此强调是因为视觉/多模态信息截图、网页内容、PDF一旦离开视野就很容易丢失必须尽快转写成文本。progress.md初始状态# Progress Log ## Session: 2026-01-15 ### Phase 1: Requirements Discovery - **Status:** in_progress - **Started:** 2026-01-15 10:00 - Actions taken: - Created task_plan.md - Created findings.md - Created progress.md - Files created/modified: - task_plan.md (created) - findings.md (created) - progress.md (created) ### Phase 2: Planning Structure - **Status:** pending - Actions taken: - - Files created/modified: - ## Test Results | Test | Input | Expected | Actual | Status | |------|-------|----------|--------|--------| | | | | | | ## Error Log | Timestamp | Error | Attempt | Resolution | |-----------|-------|---------|------------| | | | 1 | | ## 5-Question Reboot Check | Question | Answer | |----------|--------| | Where am I? | Phase 1 - Requirements Discovery | | Where am I going? | Phase 2-5: Planning, Implementation, Testing, Delivery | | Whats the goal? | Build Python CLI todo app with add/list/delete | | What have I learned? | See findings.md | | What have I done? | Created planning files | --- *Update after completing each phase or encountering errors*progress.md内嵌的5-Question Reboot Check是断点恢复的关键工具。当你或 Agent在中断后重启只需回答这 5 个问题即可快速回到状态详见 SKILL.md 的 The 5-Question Reboot Test问题答案来源Where am I?我在哪task_plan.md 中的 Current PhaseWhere am I going?要去哪剩余阶段Whats the goal?目标是什么计划中的 GoalWhat have I learned?学到了什么findings.mdWhat have I done?做了什么progress.md源码视角这三个文件是怎么出生的手工创建这三个文件之外仓库提供了自动化入口scripts/init-session.sh。不带参数时它在项目根目录写出task_plan.md、findings.md、progress.mdlegacy 模式向后兼容传入任务名时则进入 slug 模式在.planning/YYYY-MM-DD-slug/下创建隔离的计划目录并打印PLAN_ID从 init-session.sh 的用法注释可见。脚本只会为缺失的文件写模板已存在的文件会被跳过$plan_path already exists, skipping这保证了恢复会话时不会覆盖已有工作。Phase 2研究与规划之后 —— 文件如何随工作演进完成需求调研与技术选型后三个文件同步更新task_plan.md勾选完成项、沉淀决策findings.md记录调研结论progress.md追加动作与时间线。task_plan.md更新后# Task Plan: Build Command-Line Todo App ## Goal Create a Python CLI todo app with add, list, and delete functionality. ## Current Phase Phase 2 ## Phases ### Phase 1: Requirements Discovery - [x] Understand user intent ✓ - [x] Identify constraints and requirements ✓ - [x] Document findings in findings.md ✓ - **Status:** complete ### Phase 2: Planning Structure - [x] Define technical approach ✓ - [x] Create project structure ✓ - [x] Document decisions with rationale ✓ - **Status:** complete ### Phase 3: Implementation - [ ] Write todo.py with core functions - [ ] Implement add functionality - [ ] Implement list functionality - [ ] Implement delete functionality - **Status:** in_progress ### Phase 4: Testing Verification - [ ] Test add operation - [ ] Test list operation - [ ] Test delete operation - [ ] Verify error handling - **Status:** pending ### Phase 5: Delivery - [ ] Review code quality - [ ] Ensure all features work - [ ] Deliver to user - **Status:** pending ## Key Questions 1. Should tasks persist between sessions? ✓ Yes - using JSON file 2. What format for storing tasks? ✓ JSON file (todos.json) 3. Command-line interface style? ✓ argparse with subcommands ## Decisions Made | Decision | Rationale | |----------|-----------| | Use JSON for storage | Simple, human-readable, built-in Python support | | argparse with subcommands | Clean CLI: python todo.py add task, python todo.py list | | Store in todos.json | Standard location, easy to find and debug | ## Errors Encountered | Error | Attempt | Resolution | |-------|---------|------------| | | 1 | | ## Notes - Update phase status as you progress: pending → in_progress → complete - Re-read this plan before major decisions (plan recitation) - Log ALL errors - they help avoid repetition关键变化Phase 1、2 的复选框全部勾选并标记completeCurrent Phase前进到 Phase 3ImplementationKey Questions里每个问题后追加了带 ✓ 的答案Decisions Made从空表变为三条带理由的技术决策。这正是 SKILL.md 的 Critical Rule #4 Update After Act——完成阶段后标记状态in_progress→complete、记录错误、注明创建/修改的文件。findings.md更新后# Findings Decisions ## Requirements - Command-line interface - Add tasks - List all tasks - Delete tasks - Python implementation - Tasks should persist (survive app restart) ## Research Findings - Pythons argparse module is perfect for CLI subcommands - json module handles file persistence easily - Standard pattern: python todo.py command [args] - File structure: Single todo.py file is sufficient for this scope ## Technical Decisions | Decision | Rationale | |----------|-----------| | Use JSON for storage | Simple, human-readable, built-in Python support | | argparse with subcommands | Clean CLI: python todo.py add task, python todo.py list | | Store in todos.json | Standard location, easy to find and debug | | Single file structure | Simple enough for one file, can refactor later if needed | ## Issues Encountered | Issue | Resolution | |-------|------------| | | | ## Resources - Python argparse documentation: https://docs.python.org/3/library/argparse.html - Python json module: https://docs.python.org/3/library/json.html ## Visual/Browser Findings - Reviewed argparse examples - subcommand pattern is straightforward - JSON file format: array of objects with id and task fields --- *Update this file after every 2 view/browser/search operations* *This prevents visual information from being lost*注意findings.md的角色边界它专门收纳来自外部文档、搜索结果、浏览内容的信息Visual/Browser Findings小节用于把多模态观察转写成文字。这与 SKILL.md 的安全规则一脉相承——外部内容一律视为不可信数据只能写入findings.md绝不能写进会被钩子自动注入上下文的task_plan.md。progress.md更新后# Progress Log ## Session: 2026-01-15 ### Phase 1: Requirements Discovery - **Status:** complete - **Started:** 2026-01-15 10:00 - **Completed:** 2026-01-15 10:15 - Actions taken: - Created task_plan.md - Created findings.md - Created progress.md - Researched Python CLI patterns - Decided on JSON storage - Files created/modified: - task_plan.md (created, updated) - findings.md (created, updated) - progress.md (created) ### Phase 2: Planning Structure - **Status:** complete - **Started:** 2026-01-15 10:15 - **Completed:** 2026-01-15 10:20 - Actions taken: - Defined technical approach (argparse JSON) - Documented decisions in findings.md - Updated task_plan.md with decisions - Files created/modified: - task_plan.md (updated) - findings.md (updated) ### Phase 3: Implementation - **Status:** in_progress - **Started:** 2026-01-15 10:20 - Actions taken: - Starting to write todo.py - Files created/modified: - (todo.py will be created) ## Test Results | Test | Input | Expected | Actual | Status | |------|-------|----------|--------|--------| | | | | | | ## Error Log | Timestamp | Error | Attempt | Resolution | |-----------|-------|---------|------------| | | | 1 | | ## 5-Question Reboot Check | Question | Answer | |----------|--------| | Where am I? | Phase 3 - Implementation | | Where am I going? | Phase 4-5: Testing, Delivery | | Whats the goal? | Build Python CLI todo app with add/list/delete | | What have I learned? | argparse subcommands, JSON storage pattern (see findings.md) | | What have I done? | Completed planning, starting implementation | --- *Update after completing each phase or encountering errors*progress.md记录了每个阶段的Started/Completed时间戳、动作清单和文件变更清单相当于 Agent 的可审计流水账。Phase 3实现中遭遇错误 —— 错误日志与恢复是规划模式的核心价值真正体现这套模式价值的时刻是出错的时候。演练中实现list功能时先后遇到两个典型错误读取不存在的todos.json抛FileNotFoundError以及空文件导致JSONDecodeError。task_plan.md遭遇错误后# Task Plan: Build Command-Line Todo App ## Goal Create a Python CLI todo app with add, list, and delete functionality. ## Current Phase Phase 3 ## Phases ### Phase 1: Requirements Discovery - [x] Understand user intent ✓ - [x] Identify constraints and requirements ✓ - [x] Document findings in findings.md ✓ - **Status:** complete ### Phase 2: Planning Structure - [x] Define technical approach ✓ - [x] Create project structure ✓ - [x] Document decisions with rationale ✓ - **Status:** complete ### Phase 3: Implementation - [x] Write todo.py with core functions ✓ - [x] Implement add functionality ✓ - [ ] Implement list functionality (CURRENT) - [ ] Implement delete functionality - **Status:** in_progress ### Phase 4: Testing Verification - [ ] Test add operation - [ ] Test list operation - [ ] Test delete operation - [ ] Verify error handling - **Status:** pending ### Phase 5: Delivery - [ ] Review code quality - [ ] Ensure all features work - [ ] Deliver to user - **Status:** pending ## Key Questions 1. Should tasks persist between sessions? ✓ Yes - using JSON file 2. What format for storing tasks? ✓ JSON file (todos.json) 3. Command-line interface style? ✓ argparse with subcommands ## Decisions Made | Decision | Rationale | |----------|-----------| | Use JSON for storage | Simple, human-readable, built-in Python support | | argparse with subcommands | Clean CLI: python todo.py add task, python todo.py list | | Store in todos.json | Standard location, easy to find and debug | | Use incremental IDs | Simple counter, easier than UUIDs for this use case | ## Errors Encountered | Error | Attempt | Resolution | |-------|---------|------------| | FileNotFoundError when reading todos.json | 1 | Check if file exists, create empty list if not | | JSONDecodeError on empty file | 2 | Handle empty file case explicitly | ## Notes - Update phase status as you progress: pending → in_progress → complete - Re-read this plan before major decisions (plan recitation) - Log ALL errors - they help avoid repetitionErrors Encountered表中如实记录了两个错误、尝试次数和解决方案。这是 SKILL.md 的 Critical Rule #5 Log ALL ErrorsEvery error goes in the plan file. This builds knowledge and prevents repetition.和 Rule #6 Never Repeat Failures 的直接体现。仓库还给出了更严格的三次尝试协议3-Strike Error Protocol第 1 次失败 → 诊断并修复第 2 次失败 → 换一种方法不同工具/库绝不重复同样失败的动作用例第 3 次失败 → 重新质疑假设、考虑更新计划三次都失败则上报用户。progress.md含错误日志# Progress Log ## Session: 2026-01-15 ### Phase 1: Requirements Discovery - **Status:** complete - **Started:** 2026-01-15 10:00 - **Completed:** 2026-01-15 10:15 - Actions taken: - Created task_plan.md - Created findings.md - Created progress.md - Researched Python CLI patterns - Decided on JSON storage - Files created/modified: - task_plan.md (created, updated) - findings.md (created, updated) - progress.md (created) ### Phase 2: Planning Structure - **Status:** complete - **Started:** 2026-01-15 10:15 - **Completed:** 2026-01-15 10:20 - Actions taken: - Defined technical approach (argparse JSON) - Documented decisions in findings.md - Updated task_plan.md with decisions - Files created/modified: - task_plan.md (updated) - findings.md (updated) ### Phase 3: Implementation - **Status:** in_progress - **Started:** 2026-01-15 10:20 - Actions taken: - Created todo.py with basic structure - Implemented add functionality - Encountered FileNotFoundError (handled) - Encountered JSONDecodeError on empty file (handled) - Working on list functionality - Files created/modified: - todo.py (created, modified) - todos.json (created by app) ## Test Results | Test | Input | Expected | Actual | Status | |------|-------|----------|--------|--------| | Add task | python todo.py add Buy milk | Task added to todos.json | Task added successfully | ✓ | | List tasks | python todo.py list | Shows all tasks | FileNotFoundError (fixed) | Fixed | ## Error Log | Timestamp | Error | Attempt | Resolution | |-----------|-------|---------|------------| | 2026-01-15 10:35 | FileNotFoundError when reading todos.json | 1 | Added file existence check, create empty list if not exists | | 2026-01-15 10:37 | JSONDecodeError on empty file | 2 | Added explicit empty file handling before json.load() | ## 5-Question Reboot Check | Question | Answer | |----------|--------| | Where am I? | Phase 3 - Implementation (working on list functionality) | | Where am I going? | Phase 4-5: Testing, Delivery | | Whats the goal? | Build Python CLI todo app with add/list/delete | | What have I learned? | Need to handle file not existing, empty file edge cases (see findings.md) | | What have I done? | Completed add functionality, fixed file handling errors, working on list | --- *Update after completing each phase or encountering errors*这段日志的实战价值在于错误不是被静默重试掩盖而是连同时间戳、尝试次数与解决方案一起落盘。仓库 examples.md 中的 Error Recovery Pattern 对此有明确的正确与错误示范对比——错误示范是连续三次静默重读config.json正确示范是先记入task_plan.md的Errors Encountered再改用写默认配置的方式解决问题。这个理念也呼应了 reference.md 中 Manus 的 Principle 5 Keep the Wrong Stuff In保留失败动作与堆栈让模型隐式修正信念避免重复犯错。Phase 4任务完成 —— 规划的最终形态与交付task_plan.md最终状态# Task Plan: Build Command-Line Todo App ## Goal Create a Python CLI todo app with add, list, and delete functionality. ## Current Phase Phase 5 (Complete) ## Phases ### Phase 1: Requirements Discovery - [x] Understand user intent ✓ - [x] Identify constraints and requirements ✓ - [x] Document findings in findings.md ✓ - **Status:** complete ### Phase 2: Planning Structure - [x] Define technical approach ✓ - [x] Create project structure ✓ - [x] Document decisions with rationale ✓ - **Status:** complete ### Phase 3: Implementation - [x] Write todo.py with core functions ✓ - [x] Implement add functionality ✓ - [x] Implement list functionality ✓ - [x] Implement delete functionality ✓ - **Status:** complete ### Phase 4: Testing Verification - [x] Test add operation ✓ - [x] Test list operation ✓ - [x] Test delete operation ✓ - [x] Verify error handling ✓ - **Status:** complete ### Phase 5: Delivery - [x] Review code quality ✓ - [x] Ensure all features work ✓ - [x] Deliver to user ✓ - **Status:** complete ## Key Questions 1. Should tasks persist between sessions? ✓ Yes - using JSON file 2. What format for storing tasks? ✓ JSON file (todos.json) 3. Command-line interface style? ✓ argparse with subcommands ## Decisions Made | Decision | Rationale | |----------|-----------| | Use JSON for storage | Simple, human-readable, built-in Python support | | argparse with subcommands | Clean CLI: python todo.py add task, python todo.py list | | Store in todos.json | Standard location, easy to find and debug | | Use incremental IDs | Simple counter, easier than UUIDs for this use case | ## Errors Encountered | Error | Attempt | Resolution | |-------|---------|------------| | FileNotFoundError when reading todos.json | 1 | Check if file exists, create empty list if not | | JSONDecodeError on empty file | 2 | Handle empty file case explicitly | ## Notes - Update phase status as you progress: pending → in_progress → complete - Re-read this plan before major decisions (plan recitation) - Log ALL errors - they help avoid repetitionCurrent Phase标记为Phase 5 (Complete)全部 5 个阶段、全部复选框均为完成状态。这一状态也是仓库自动化工具判定任务结束的依据scripts/check-complete.sh会解析task_plan.md中每个阶段的**Status:** complete标记当全部阶段完成时输出完成结论其头部注释说明了计划文件的解析顺序显式路径参数 →resolve-plan-dir.sh$PLAN_ID环境变量 →.planning/.active_plan→ 按 mtime 最新的计划目录→ 回退到 legacy 根目录./task_plan.md。因此保持Status标记的规范书写必须是字面量complete是机器可判定完成的前提。交付后的延续任务完成 ≠ 工作结束SKILL.md 的 Critical Rule #7 Continue After Completion 说明如果所有阶段完成但用户追加了新需求就为task_plan.md增加新阶段如 Phase 6、Phase 7在progress.md中记录新会话条目然后按正常流程继续——规划文件是增量演进的不是一次性的。三个文件如何协同工作模式总结各自的职责task_plan.md 你的路线图在任何工作开始前最先创建每个阶段完成后更新重大决策前重新阅读可通过钩子自动注入追踪已完成、下一步、出过什么错findings.md 你的知识库沉淀研究与发现记录带理由的技术决策每 2 次 view/browser 操作后更新2-Action Rule防止重要信息丢失progress.md 你的会话日志记录做了什么、何时做的追踪测试结果记录所有错误包括已修复的回答5-Question Reboot Test工作流模式START TASK ↓ Create task_plan.md (NEVER skip this!) ↓ Create findings.md ↓ Create progress.md ↓ [Work on task] ↓ Update files as you go: - task_plan.md: Mark phases complete, log errors - findings.md: Save discoveries (especially after 2 view/browser ops) - progress.md: Log actions, tests, errors ↓ Re-read task_plan.md before major decisions ↓ COMPLETE TASK常见模式速查出错了吗→ 同时记入task_plan.md和progress.md做了决策→ 带理由记录到findings.md浏览/查看了 2 次→ 立即把发现存入findings.md开始新阶段→ 更新task_plan.md和progress.md的状态不确定该做什么→ 重读task_plan.md刷新目标自动化支撑钩子如何让三文件模式被动生效手写三文件只是基础planning-with-files 的真正威力在于用生命周期钩子把重读计划变成自动行为。从 SKILL.md 的 frontmatter 可以看到它以 Claude Code Hook 形式注册了多个事件统一由 scripts/skill-hook.sh 分发UserPromptSubmit每次用户提交提示词时注入选中的计划上下文PreToolUse每次匹配的 Read/Write/Edit/Bash/Glob/Grep 工具调用前注入计划片段实现plan recitationPostToolUse每次写入/编辑后校验计划状态并提醒更新进度PreCompact上下文压缩前打印诊断提示与记录的Plan-SHA256摘要v2.38.0Stop会话结束前校验计划完成状态在可选的 gated 模式下可以成为完成门check-complete.sh 的--gate分支按五条件决策表判断是否放行停止。这套注入遵循严格的安全边界钩子输出包裹在BEGIN PLAN DATA/END PLAN DATA定界符内注入内容一律视为结构化数据而非指令SKILL.md 的 Security Boundary 一节。同时钩子只在选中了计划时才工作resolve-plan-dir.sh按$PLAN_ID→.planning/.active_plan→ 最新计划目录 → legacy 根目录的顺序解析计划目录多个计划并存且未指定PLAN_ID时钩子会拒绝注入而不是猜。更进一步的实战变体并行任务每个任务一个 PLAN_ID多个 Agent 在同一仓库并行工作时用scripts/init-session.sh Task Name为每个任务创建独立的.planning/date-slug/计划并各自export PLAN_ID打印的ID固定宿主互不干扰见 SKILL.md 的 Parallel task workflow完整用法含 PowerShell 下的$env:PLAN_ID设置。沙箱集成BoxLite 微虚拟机仓库的 examples/boxlite/ 目录提供了在 BoxLite 微虚拟机沙箱内运行本模式的可执行示例examples/boxlite/quickstart.py通过 ClaudeBox 的 Skill API 把SKILL.md与scripts/check-complete.sh注入虚拟机文件系统在 VM 内发起规划会话并验证task_plan.md等文件是否生成还演示了ClaudeBox.reconnect()跨会话续跑同一工作区的模式完整集成指南见 docs/boxlite.md。运行方式为pip install claudebox export CLAUDE_CODE_OAUTH_TOKENsk-ant-oat01-... python examples/boxlite/quickstart.py【免费下载链接】planning-with-filesPersistent file-based planning for AI coding agents and long-running tasks. Crash-proof markdown plans, session recovery after /clear and compaction, per-turn re-injection against context rot, deterministic completion gate. Manus-style. Install from npm, the Claude Code plugin marketplace, or npx skills. Codex, Cursor, OpenCode, 60 agents.项目地址: https://gitcode.com/GitHub_Trending/pl/planning-with-files创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考