task-execute

Continuous Execution Framework (Task Execute)

Inspiration source:Anthropic - Effective Harnesses for Long-Running Agents

Agents work in discrete sessions, and each new session has no memory of previous work. This means complex tasks spanning hours or even days can easily fail. This framework addresses two core failure modes:

Over-ambition: trying to complete the entire project in one go, running out of context midway through implementation, and leaving behind undocumented half-finished work
Premature declaration of completion: subsequent sessions see partial progress and incorrectly claim the project is complete

Phase 1: Initializer session (Initializer)

The first session has two tasks: quickly establish the framework files, thenimmediately begin development of the first feature. Do not spend the entire session on "preparation work"—the user wants to see actual progress.

Framework setup is limited to no more than 5 tool calls(create init.sh + create claude-progress.md + git add + git commit), and after completion, immediately move into coding.

1. Create the startup script `init.sh`

Write it according to the actual project situation, including: dependency installation, database migration, service startup, and health checks. The script must be able to run idempotently (repeated execution does not cause errors).

#!/bin/bash
set -e
npm install
npx prisma migrate dev 2>/dev/null || true
npm run dev &
# 等待服务就绪后输出确认
for i in $(seq 1 15); do
  curl -s http://localhost:3000 > /dev/null 2>&1 && echo "就绪" && exit 0
  sleep 1
done
echo "启动超时" && exit 1

2. Create `claude-progress.md`

Depending on whether the project already has a documentation system, choose a different mode:

Judgment criterion: does the project contain docs/specs、docs/plans or a similar solution/plan directory?

Mode A: Full mode (the project has no existing documentation system)

Suitable for projects starting from scratch; progress.md serves both as the feature list and the progress record.

# 项目进度

## 功能清单

| # | 功能 | 优先级 | 状态 | 依赖 |
|---|------|--------|------|------|
| 1 | 用户登录页面 | high | pending | - |
| 2 | 用户注册流程 | high | pending | #1 |
| 3 | 书籍列表与搜索 | high | pending | - |

## 已完成
（暂无）

## 下一步
- #1: 用户登录页面

## 已知问题
（暂无）

Feature list principles：

Each feature point must be small enough to be completed withina single session. If unsure, split it more finely
done = the code is written and runnable;verified = verified through end-to-end testing. Only verified counts as complete
For projects taken over midway: existing features are also included in the list and marked verified(provided you have personally verified them)

Mode B: Session log mode (the project already has a documentation system such as specs/plans)

Suitable for projects that already have solution documents (docs/specs) and development plans (docs/plans).Do not maintain the feature list repeatedly, and only record session continuation information.

# 会话日志

## 相关文档
- 方案设计：docs/specs/
- 开发计划：docs/plans/
- 产品文档：docs/prd/

## 最近会话

### 2026-03-14 会话 #5
- 做了：购物车 API 的数量修改和删除接口（B3）
- 状态：B3 约 80%，价格计算还没做
- 遗留决策：价格服务端算，快照价格策略（详见 docs/specs/cart.md）
- 下一步：完成 B3 价格计算，然后等设计稿确认再开前端

### 2026-03-13 会话 #4
- 做了：购物车 API 的 CRUD 基础接口（B3）
- 状态：B3 约 40%
- 下一步：数量修改 + 删除接口

## 已知问题
- 搜索接口 >1000 条时慢，需加索引（不阻塞当前任务）

Key principles of Mode B：

Do not copy: the feature list and solution content are already in specs/plans, and are not repeated in progress.md. Reference them only by file path
Append only: append one record at the end of each session, keep the most recent 5-8 records, and earlier ones may be deleted (they are in git history)
Point to rather than include: for legacy decisions, write "see docs/specs/cart.md" instead of moving the solution content over
When the Agent starts, reading the most recent 2-3 session records is enough to get into state; when solution details are needed, read specs/plans on demand

3. Commit and immediately begin the first feature

git add init.sh claude-progress.md
git commit -m "chore(init): 建立长期运行框架文件"

Then go directly into the second-phase development loop and start working on the first feature. Don't wait until the "next session."

Phase Two: Development Session (Coding Agent)

Session Startup Routine

At the start of each new session, quickly get up to speed:

Mode A (Full Mode)：

1. cat claude-progress.md    → 功能清单 + 上次做到哪了
2. git log --oneline -10     → 最近的变更历史
3. bash init.sh              → 启动开发环境
4. 快速冒烟测试               → 确认已有功能没坏

Mode B (Session Log Mode)：

1. cat claude-progress.md          → 最近 2-3 条会话记录，快速了解上下文
2. 按需读 docs/plans/当前模块.md   → 当前阶段的开发计划和任务清单
3. 按需读 docs/specs/相关方案.md   → 当前功能涉及的设计方案
4. git log --oneline -10           → 最近的变更历史
5. bash init.sh                    → 启动开发环境
6. 快速冒烟测试                     → 确认已有功能没坏

Steps 2-3 of Mode B are "on demand"—only read the documents related to the feature you're currently working on, don't read through all the specs/plans.

The startup routine should be fast. The goal is to get up to speed, not to conduct an audit.

Continue the previously unfinished Plan: if there are leftover decisions in progress.md (in the "in progress" section for Mode A, in the most recent session record for Mode B), it means the previous session interrupted a large feature. In this case, use EnterPlanMode to rebuild the Plan based on the leftover information—not analyze from scratch, but continue based on the previous decisions. The parts of the Plan marked "follow previous decisions" can be abbreviated; only expand the newly added or adjusted parts.

Single-Feature Development Loop

选择功能 → Plan 方案设计 → 用户 approve → 实现 → 验证 → 提交 → 更新进度

Select a feature: from the list, select the highest-priority feature whose dependencies are satisfied and whose status is pending.

Plan design: after selecting a feature, use EnterPlanMode to do the design. The Plan is responsible for "how to do it in this session," whileclaude-progress.md is responsible for "how far the whole project has progressed"—the two have different responsibilities, don't confuse them:

Plan(single session): the implementation approach for the current feature, which files are involved, technical decisions, implementation steps
claude-progress.md(cross-session): feature list, completion status, work in progress, known issues

The Plan does not need to repeat the project-wide information already in progress.md; it should only focus on the implementation approach for the current feature. Start coding only after the user approves.

Simple features can skip the Plan: if the feature is very small (changes no more than 2-3 files, implementation path is clear and unambiguous), you can code directly without going through the Plan process.

Implement: git commit after each meaningful step is completed. Benefits—errors can be rolled back, and subsequent sessions have a fine-grained history.

Verify: you can't rely only on "the code looks right." Use Playwright/Puppeteer or a testing framework to do end-to-end verification. Absolutely do not modify tests just to make them pass—this hides real problems and makes subsequent sessions continue on a false premise.

Update progress：Update immediately each time a feature is completed claude-progress.md and git commit, don't save it all up to update at the end. Reason: you don't know when an interruption will happen, and saving up updates = losing the progress record when interrupted.

Mode A update content—change the feature list status + write clearly in the "completed" section what was done:

## 已完成
- #1: 用户登录页面 — commit abc1234
  - 登录表单 + 客户端验证 + 对接 /api/auth/login
  - 已通过 Playwright 端到端验证

Mode B update content—append a record in the "recent sessions" section:

### 2026-03-14 会话 #5
- 做了：购物车 API 的数量修改和删除接口（B3）
- 状态：B3 约 80%，价格计算还没做
- 遗留决策：价格服务端算（详见 docs/specs/cart.md 第 3 节）
- 下一步：完成 B3 价格计算

The common goal of both modes: let the next session understand the current state within 30 seconds. Write specific facts, not vague summaries.

Connecting subtasks' task-start / task-finish

In the development loop, each subtask can trigger other skills in the workflow as needed:

When starting a new subtask: if the subtask has ambiguous points or involves 3+ files, trigger task-start for requirement alignment and design
When a subtask is completed: trigger task-finish to perform a CR self-check. When all major tasks are completed, perform a full retrospective

Context protection: know when to stop

The Agent has no API to check "how many tokens are left," so it needs to rely on observable signals to actively manage this.

Specific signals—when any of the following occurs, prepare to wrap up:

Signal	How to judge	Urgency
The system has compressed early messages	Claude Code automatically compresses the conversation history, and you will notice that early details become blurry	High—must wrap up immediately
2-3 medium-sized features have been completed	Count how many features were completed in this session	Medium—wrap up after completing the current feature
The current feature is done, and the next one is very large	Check the complexity of the next feature in the list	Medium—do not start, leave it for next time
You begin to have a blurry memory of earlier code	You need to reread previously modified files to recall it	High—this indicates the context has been compressed
Tool calls in a single session exceed 30	Roughly estimate how many times you called tools	Medium—start paying attention and prepare to wrap up

Rule of thumb: it is better to wrap up one time too early (cost: the 2 minutes of starting one more session) than to wrap up too late (cost: a half-finished product + a large number of tokens in the next session used for recovery).

Safe exit protocol—when you feel you are approaching the limit:

Stop starting new features
Commit the current work to a runnable state (better to have an incomplete feature than code that cannot run)
Distill the Plan into progress.md: the Plan is session-level, and the next session cannot see it. Before exiting, you must write the key unexecuted information from the Plan into claude-progress.md：

## 进行中
- #5: 购物车（约 60%）
  - ✅ 数据模型和 API
  - ✅ 添加/删除商品
  - ❌ 数量修改（API 已写好，前端待对接，参考 /api/cart/items/[id]）
  - ❌ 价格计算（需考虑优惠券，目前按百分比折扣实现）

### 上次 Plan 遗留的设计决策
- 购物车价格计算采用"先算原价再减折扣"策略，不是"逐项折扣"
- 优惠券模型已建好（见 prisma/schema.prisma），支持百分比和固定金额两种
- 前端购物车组件计划用 /components/Cart.tsx，复用已有的 ProductCard 样式

Principles of distillation:Only write information that the next session needs but cannot infer from the code—design decisions, reasons for technical choices, and the context of unfinished steps. Implementation details visible in the code do not need to be repeated.

After the next session reads this information, it can quickly rebuild the Plan and continue pushing forward, instead of analyzing "why it was designed this way" from scratch.

States that must never be left behind: compilation failure, runtime errors, database migrations not run. The first thing the next session does is bash init.sh, and if even this fails, a large number of tokens will be wasted on debugging the environment.

Taking over a project midway

When the user says "the project is half done," the initialization process needs to be adjusted—first understand the current state, then build the framework.

Takeover process

1. 阅读项目结构和技术栈          → ls, package.json, 核心目录
2. 阅读已有代码                 → 理解架构模式、命名规范、错误处理方式
3. git log --oneline -30        → 了解开发历史
4. 尝试运行项目                 → 确认能跑起来
5. 验证用户说的"已完成"功能      → 不能假设，要亲自验
6. 建立框架文件                 → init.sh + claude-progress.md
7. 开始第一个新功能

Key differences:

Existing features should be added to the list and marked as verified(but only if you have actually verified them)
init.sh should be written according to the actual situation of the project, not copied from a template
New code must remain stylistically consistent with existing code—pay attention to recording conventions when reading code

Phase 3: Verification and wrap-up

When all features are marked as verified :

Full end-to-end testing: go through the user flow of all features
Regression check: focus on interactions between features
Code cleanup: remove debug code, console.log, temporary files
Final progress update: mark the project as complete
Trigger task-finish retrospective: use the task-finish skill's retrospective process. Long-term projects spanning multiple sessions are typical "large tasks" and must be retrospected. Focus on:
- Is the handoff between sessions smooth? Is the information in progress.md sufficient?
- Which features have an appropriate granularity of decomposition? Which were split too large or too small?
- Where is the deviation between the design and the actual implementation?
- Deposit reusable lessons into the memory system (feedback or project type)

Failure Mode Quick Reference

Problem	Root cause	Countermeasure
Declaring completion too early	No feature checklist for comparison	Must read claude-progress.md at the start of a session
Code has bugs but is marked complete	No end-to-end verification done	verified = tests pass, not "I think I'm done writing it"
Context exhausted leaving half-finished work	No proactive context management	Detection signal + safe exit protocol
Follow-up sessions don't know where to start	Progress records too vague	Write specific facts: what was done, commit hash, next step
Environment setup wastes tokens	Figuring it out from scratch every time	init.sh one-click startup
New code style is inconsistent	Starting work without reading existing code	Step 2 of the mid-project takeover process
Complex feature implementation goes off track	Starting work without doing design	Use task-start to focus + Plan to align on the approach
Plan and progress.md content overlap	Unclear responsibilities	Plan = how to do the current session; progress = how far the project has gotten

Usage Guide

1. Assess scale: should this framework be enabled?

Condition (any one satisfied)	Judgment
≤ 3 feature points, and each change involves ≤ 5 files	Not needed, just do it
> 3 feature points, or any feature involves > 5 files	This framework is needed
Expected to require spanning more than 2 sessions	This framework is needed
User says "the project is large", "do it in phases", "long-term task"	This framework is needed

2. Feature status transitions

pending → in-progress → done → verified

Status	Meaning	Transition condition
`pending`	Not started	Initial state
`in-progress`	In progress	Marked when coding begins
`done`	Code written	Code is runnable, already committed
`verified`	Verified	Passed end-to-end tests or manually verified the complete user flow

Only verified counts as "complete".done means it still needs to be verified in a subsequent session.

3. The first feature of the initialization session

The first feature selected for the initialization sessionSkip Plan, and code directly. Reason: during the initialization phase, the project has already been comprehensively understood, and the first feature is usually a foundational feature (such as project scaffolding, data models) with a clear path. Starting from the second feature, decide based on complexity whether to go through Plan.

4. What the smoke test specifically does

The specific operations for step 4 "quick smoke test" of the startup routine:

Has a test suite：npm test or an equivalent command, run the full test suite. If it takes more than 2 minutes, run only the tests related to the most recent commit
No test suite: manually verify the most recently modified features—open the page, click through the core paths, and confirm there are no errors
API project: use curl to call 2-3 key endpoints and confirm the responses are normal

The goal is to confirm within 2 minutes that "existing features are not broken," not to do a full regression.

5. What to tell the user at the end of the session

At the end of each session (whether it is a normal wrap-up or a safe exit), communicate with the user using the following template:

## 本次会话总结
- 完成：#1 用户登录、#2 用户注册
- 进行中：#3 书籍搜索（约 70%，API 完成，前端待对接）
- 下次会话计划：完成 #3 剩余部分，然后开始 #4 购物车
- 已知问题：搜索分页超过 100 条时性能下降，需要加索引

No need for a long speech; explain clearly in 4 lines or fewer.

Connection with other skills

task-start — 启动：对焦需求 + 设计方案
  │
  ↓
task-execute（本 skill）— 执行：持续编码 + 跨会话进度管理
  │
  ├─ 子任务开始 → 按需触发 task-start（需求模糊或 3+ 文件时）
  ├─ 子任务完成 → 触发 task-finish 的 CR 自检
  ├─ 全部完成 → 触发 task-finish 的完整复盘
  │
  ↓
task-finish — 收尾：CR 自检 + 复盘沉淀