Harness Step 3: Establish Cross-Session State Management

Objectives

Create three files to enable agents to resume work status within 30 seconds at the start of any new session:

```
init.sh
```
: Environment initialization script to verify the project can start normally
```
tasks.json
```
: Current task list, the source of work instructions for agents
```
progress.md
```
: Human-readable progress summary that records key information from each session

Core Principle: State is transferred via files, not agent memory. git log is the primary record, and these three files are supplementary.

Implementation Steps

Step 1: Scan Project Startup Methods

Before writing

init.sh

, first confirm how the project starts and is tested:

bash

# Read scripts in package.json (Node.js projects)
cat package.json 2>/dev/null | grep -A 20 '"scripts"'

# Or read Makefile (multi-language projects)
cat Makefile 2>/dev/null | head -40

# Or read pyproject.toml (Python projects)
cat pyproject.toml 2>/dev/null | grep -A 20 '\[tool.poetry.scripts\]'

# Confirm startup commands in existing AGENTS.md
grep -A 5 '启动命令\|start\|dev\|run' AGENTS.md 2>/dev/null

Collect:

Development server startup command
Test command
Type checking/lint command (if available)
Any initialization steps that need to be run first (such as database migration)

Step 2: Create

init.sh

The role of

init.sh

: Run at the start of each session to quickly verify if the environment is normal, and fix issues immediately if not before proceeding.

bash

#!/bin/bash
# init.sh — Run at the start of each session
# Verify that the development environment is in a working state

set -e  # Stop if any step fails

echo "=== Checking Environment ==="

# 1. Confirm in the correct directory
echo "Working Directory: $(pwd)"

# 2. Install dependencies (if node_modules does not exist)
# [Choose based on tech stack, the following is an example]
# Node.js:
if [ ! -d "node_modules" ]; then
  echo "Installing dependencies..."
  npm install
fi

# 3. Smoke test: Verify the project can start normally
# [Write according to actual project situation, the goal is to verify basic functionality in the fastest way]
# Example: Run the fastest test
# npm run test -- --testPathPattern=smoke 2>/dev/null || echo "Warning: Smoke test failed, please fix first"

echo "=== Environment check completed, ready to start working ==="
echo "Tip: Run 'git log --oneline -10' to view recent work history"

Writing Requirements:

Fill in according to the actual startup commands scanned, do not leave example comments
Smoke tests should be fast (< 30 seconds), aimed at quickly detecting environment issues rather than running the full test suite
If the project has a database, add a step to check if the database connection is normal
Run the script after writing to confirm no errors:
```
bash init.sh
```

Step 3: Create

tasks.json

Structure Design:

json

{
  "project": "[Project Name]",
  "last_updated": "[Today's Date, Format YYYY-MM-DD]",
  "current_focus": "[The most important thing right now, one sentence]",
  "tasks": [
    {
      "id": "[Module Abbreviation]-[Serial Number]",
      "title": "[Task Title]",
      "description": "[What to do specifically, 1-3 sentences]",
      "status": "pending | in_progress | done | blocked",
      "priority": "high | medium | low",
      "blocked_by": "[Blocking reason, only fill in when status is blocked]",
      "verify": "[How to verify this task is completed]",
      "requires_eval": false
    }
  ]
}

Field Explanation (Must fill in each field when adding a new task, cannot omit):

Field	Required	Explanation
`id`	Required	Module abbreviation + serial number, e.g., `auth-01` , `ui-03` , short and readable
`title`	Required	Task title, one sentence
`description`	Required	What to do specifically, 1-3 sentences
`status`	Required	Initial value is `pending` , updated by the agent during work
`priority`	Required	`high / medium / low`
`blocked_by`	Only when blocked	Blocking reason
`verify`	Required	How to verify completion, must be executable steps (commands or operations)
`requires_eval`	Required	Whether independent Evaluator review is needed, default `false` , see judgment criteria

requires_eval
Judgment Criteria (Must compare against when adding tasks, cannot fill false without thinking):

Set to

true

if any of the following conditions are met:

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

Set to

false

only if all of the following conditions are met:

Pure bug fix with clear scope of changes
Document updates, comment additions
Configuration adjustments, environment variable modifications
Unit test additions

How to Determine the Initial Task List:

Prioritize extracting from the following sources:

Plan files in
```
docs/exec-plans/active/
```
(if available)
High-priority debts in
```
docs/exec-plans/tech-debt-tracker.md
```
TODOs or roadmaps mentioned in README
Ask the user: "What are the 3-5 tasks you most want to advance right now?"

Writing Requirements:

The
```
verify
```
field must be executable steps, cannot write vague phrases like "confirm functionality is normal"
Task granularity: A task should be completed within 1-2 hours, split larger tasks
Initial status: All tasks are
```
pending
```
, updated by the agent during work

Ask the User (If tasks cannot be inferred from existing documents):

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 advance right now? Just describe each task in one sentence.

Step 4: Create

progress.md

Initial content:

markdown

# Project Progress Record

> After completing tasks in each session, append records at the top. Do not delete history.
> Format: ## [Date] [Task Name]

---

## [Today's Date] Initialize Harness

- Completed harness-step1: Established docs/ skeleton
- Completed harness-step2: Filled knowledge base content
- Completed harness-step3: Established state management
- Number of initial tasks in tasks.json: [N]
- Next start here: Read tasks.json, select tasks with priority=high and status=pending to start

Step 4b: Update

AGENTS.md

— Write Task Management Rules

Find the section "After completing each task" written in step2 of

AGENTS.md

, replace it with the following content:

markdown

### When adding tasks, you must:
1. Fill in all fields in tasks.json, cannot omit
2. Judge `requires_eval` against the following criteria, cannot default to false without thinking:
   - New features / involving security permissions / modifying more than 3 files / refactoring → true
   - Pure bug fixes / document updates / configuration adjustments → false

### After completing each task, you must execute in order:
1. Perform the verification steps described in the `verify` field of the task in tasks.json
2. If the task's `requires_eval` is `true`: Fill in `sprint_output.md`, wait for Evaluator review approval before marking as `done`
   If the task's `requires_eval` is `false`: Mark as `done` once verification passes
3. git commit, format: `type(scope): What was done, any leftovers (if applicable)`
4. Append this session's record at the top of `progress.md`

**Prohibited**: Skipping the verify step and judging task completion on your own.
**Prohibited**: Setting `requires_eval` to false without judgment.

Step 5: Verify Overall Integration

After creating the three files, simulate a complete session startup process to verify normal integration:

bash

# Simulate the operation sequence when an agent starts a new session
echo "=== Simulating New Session Startup ==="

# 1. Run init.sh
bash init.sh

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

# 3. Read progress.md (Confirm the file exists and is readable)
head -20 progress.md

# 4. Read tasks.json (Confirm correct format)
cat tasks.json | python3 -m json.tool > /dev/null && echo "tasks.json format is correct" || echo "tasks.json format is incorrect"

Only pass all steps to complete.

Quality Inspection

Does
```
init.sh
```
run without errors?
Is
```
tasks.json
```
in valid JSON format? Does each task have
```
verify
```
and
```
requires_eval
```
fields?
Is
```
requires_eval
```
filled in according to the judgment criteria for each task, not defaulting to false?
Does
```
progress.md
```
have initial records?
Does
```
AGENTS.md
```
include the two rules for adding and completing tasks?

Inform User After Completion

Output summary:

Created Files:

```
init.sh
```
: [Describe what checks are performed]
```
tasks.json
```
: [N] tasks, [N] of which require Evaluator review
```
progress.md
```
: Initialized

How to Use:

Now you can hand the project over to Claude Code. It will automatically read these three files + git log each time it starts, and resume work status. You don't need to explain "where we left off last time" every time.

What You Need to Do:

Check if the task list in
```
tasks.json
```
meets your expectations, you can manually add or delete tasks
Confirm if the
```
requires_eval
```
judgments are reasonable
If any step in
```
init.sh
```
fails, let me know and I will fix it

Next Steps:

Harness foundation is completed (step1 + step2 + step3)
You can start formal development with Claude Code
When agents repeatedly violate code specifications, run
```
harness-step4-linter
```
to turn rules into mechanical constraints
When agent self-assessment is untrustworthy, run
```
harness-step5-evaluator
```
to introduce independent review

harness-step3-session-management

NPX Install

Tags

SKILL.md Content (Chinese)

Harness Step 3: Establish Cross-Session State Management

Objectives

Implementation Steps

Step 1: Scan Project Startup Methods

Step 2: Create
`init.sh`

Step 3: Create
`tasks.json`

Step 4: Create
`progress.md`

Step 4b: Update
`AGENTS.md`
— Write Task Management Rules

Step 5: Verify Overall Integration

Quality Inspection

Inform User After Completion