harness-step3-session-management

Harness Step 3: Establish cross-session state management

Goal

Create three files so that the agent can restore its working state within 30 seconds at the start of any new session:

init.sh: environment initialization script, verifies that the project can start normally
tasks.json: current task list, the source of the agent's work instructions
progress.md: human-readable progress summary, recording key information from each session

Core principles: state is passed through files, not through the agent's memory. git log is the primary record; these three files are auxiliary.

Execution steps

Step 1: Scan how the project starts

Before writing init.sh , first confirm how the project starts and tests:

# 读 package.json 的 scripts（Node.js 项目）
cat package.json 2>/dev/null | grep -A 20 '"scripts"'

# 或读 Makefile（多语言项目）
cat Makefile 2>/dev/null | head -40

# 或读 pyproject.toml（Python 项目）
cat pyproject.toml 2>/dev/null | grep -A 20 '\[tool.poetry.scripts\]'

# 确认现有 AGENTS.md 里的启动命令
grep -A 5 '启动命令\|start\|dev\|run' AGENTS.md 2>/dev/null

Collect:

Development server startup command
Test command
Type-check/lint command (if any)
Whether there are initialization steps that need to be run first (such as database migrations)

Step 2: Create `init.sh`

init.sh 's purpose: run at the start of each session,quickly verify whether the environment is normal, and if it is not normal, fix it immediately before continuing.

#!/bin/bash
# init.sh — 每次 session 开始时运行
# 验证开发环境处于可工作状态

set -e  # 任何步骤失败就停止

echo "=== 检查环境 ==="

# 1. 确认在正确目录
echo "工作目录: $(pwd)"

# 2. 安装依赖（如果 node_modules 不存在）
# [根据技术栈选择，以下是示例]
# Node.js:
if [ ! -d "node_modules" ]; then
  echo "安装依赖..."
  npm install
fi

# 3. 冒烟测试：验证项目能正常启动
# [根据项目实际情况写，目标是用最快的方式验证基本功能正常]
# 示例：跑一个最快的测试
# npm run test -- --testPathPattern=smoke 2>/dev/null || echo "警告：冒烟测试失败，请先修复"

echo "=== 环境检查完成，可以开始工作 ==="
echo "提示：运行 'git log --oneline -10' 查看最近工作历史"

Writing requirements：

Fill in based on the actual startup commands found during scanning; do not leave example comments
The smoke test must be fast (< 30 seconds); the purpose is to quickly detect environment problems, not to run the full test suite
If the project has a database, add a step to check whether the database connection is normal
After writing, actually run it once to confirm the script has no errors:bash init.sh

Step 3: Create `tasks.json`

Structure design：

{
  "project": "[项目名]",
  "last_updated": "[今天日期，格式 YYYY-MM-DD]",
  "current_focus": "[当前最重要的一件事，一句话]",
  "tasks": [
    {
      "id": "[模块缩写]-[序号]",
      "title": "[任务标题]",
      "description": "[具体做什么，1-3句话]",
      "status": "pending | in_progress | done | blocked",
      "priority": "high | medium | low",
      "blocked_by": "[阻塞原因，仅 blocked 状态时填写]",
      "verify": "[如何验证这个任务完成了]",
      "requires_eval": false
    }
  ]
}

Field descriptions(when adding a new task, every field must be filled in; none may be omitted):

Field	Required	Description
`id`	Required	Module abbreviation + sequence number, such as `auth-01`、`ui-03`, short and readable
`title`	Required	Task title, one sentence
`description`	Required	What specifically to do, 1-3 sentences
`status`	Required	Initial value is `pending`, updated by the agent while working
`priority`	Required	`high / medium / low`
`blocked_by`	Fill in only when blocked	Blocking reason
`verify`	Required	How to verify completion; must be executable steps (commands or operations)
`requires_eval`	Required	Whether an independent Evaluator review is needed, default `false`, see the criteria

requires_eval criteria(when adding a new task, you must check against the criteria; do not directly fill in false without thinking):

Conditions for setting true : if any one is met, review is needed:

This is a new feature (not just a bug fix or configuration change)
Involves security, permissions, or data validation-related logic
Expected to modify more than 3 files
The task description includes "refactor" or "architecture adjustment"

Conditions for setting false conditions (review can be skipped only if all of the following are met):

Pure bug fixes with a clear scope of changes
Documentation updates, comment additions
Configuration adjustments, environment variable changes
Unit test additions

How to determine the initial task list：

Prioritize extracting from the following sources:

docs/exec-plans/active/ plan files in (if any)
docs/exec-plans/tech-debt-tracker.md high-priority debt in
TODO or roadmap mentioned in the README
Ask the user: "What are the 3-5 tasks you most want to push forward right now?"

Writing requirements：

verify The field must contain actionable steps; do not write meaningless filler like "confirm the feature works"
Task granularity: a task should be completable within 1-2 hours; split anything larger
Initial state: all tasks are pending, updated by the agent while working

Ask the user(if tasks cannot be inferred from existing documentation):

I have scanned the project and am ready to create the task list. Please tell me: What are the 3-5 tasks you most want to push forward right now? A one-sentence description for each task is fine.

Step 4: Create `progress.md`

Initial content:

# 项目进度记录

> 每次 session 完成任务后，在顶部追加记录。不要删除历史。
> 格式：## [日期] [任务名]

---

## [今天日期] 初始化 Harness

- 完成 harness-step1：建立 docs/ 骨架
- 完成 harness-step2：填充知识库内容
- 完成 harness-step3：建立状态管理
- tasks.json 初始任务数：[N] 个
- 下次从这里开始：读 tasks.json，选 priority=high 且 status=pending 的任务开始

Step 4b: Update `AGENTS.md` — write the task management rules

Find AGENTS.md the "after each task is completed" section written in step2,replacewith the following content:

### 新增任务时，必须：
1. 填写 tasks.json 里的所有字段，不能省略
2. 对照以下标准判断 `requires_eval`，不能默认填 false 不加思考：
   - 新功能 / 涉及安全权限 / 改动超过 3 个文件 / 重构 → true
   - 纯 bug 修复 / 文档更新 / 配置调整 → false

### 每次完成一个任务后，必须按顺序执行：
1. 执行 `tasks.json` 里该任务 `verify` 字段描述的验证步骤
2. 若该任务 `requires_eval` 为 `true`：填写 `sprint_output.md`，等待 Evaluator 评审通过后才能标记 `done`
   若该任务 `requires_eval` 为 `false`：验证通过即可标记 `done`
3. git commit，格式：`type(scope): 做了什么，遗留了什么（如有）`
4. 在 `progress.md` 顶部追加本次记录

**禁止**：跳过 verify 步骤自行判断任务已完成。
**禁止**：不经判断直接把 `requires_eval` 设为 false。

Step 5: Verify the overall integration

After the three files are created, simulate a complete session startup flow to verify that the integration works properly:

# 模拟 agent 新 session 开始的操作序列
echo "=== 模拟新 session 启动 ==="

# 1. 跑 init.sh
bash init.sh

# 2. 看 git log
git log --oneline -10

# 3. 读 progress.md（确认文件存在且可读）
head -20 progress.md

# 4. 读 tasks.json（确认格式正确）
cat tasks.json | python3 -m json.tool > /dev/null && echo "tasks.json 格式正确" || echo "tasks.json 格式有误"

Only count it as complete when everything passes.

Quality checks

init.sh Does it actually run without errors?
tasks.json Is the JSON format valid? Does every task have verify and requires_eval fields?
For each task, is requires_eval filled in against the judgment criteria, rather than defaulting to false?
progress.md Is there an initial record?
AGENTS.md Does it include both rules: adding new tasks and completing tasks?

Notify the user when done

Output summary:

Files created：

init.sh: [describe what check was done]
tasks.json: [N] tasks, of which [N] require Evaluator review
progress.md: initialized

How to use：

Now you can hand the project over to Claude Code. On each startup it will automatically read these three files + git log, restore the working state. You no longer need to explain "where we left off" every time.

What you need to do：

Check whether the task list in tasks.json matches your expectations; you can manually add or remove items
Confirm whether the judgments in requires_eval are reasonable
If init.sh has a step that fails, tell me and I will fix it

Next steps：

The Harness foundation is complete (step1 + step2 + step3)
You can start using Claude Code for formal development
When the agent repeatedly violates the code standards, run harness-step4-linterto turn the rules into mechanical constraints
When the agent's self-assessment cannot be trusted, run harness-step5-evaluatorto introduce independent review

About this skill