task-harness

Task Harness — Structured Task Management System

Break down any requirement into a structured task list and establish a reliable task tracking system for long-running Agents.

Based on the Effective harnesses for long-running agents methodology.

When to Use

• A large requirement needs to be broken down into multiple subtasks
• The project needs continuous development across multiple Agent sessions
• Feature completion progress needs to be tracked (completed / not completed)
• The user says "break down tasks", "task management", "project planning", "create a task list"

Core Workflow

Step 1: Analyze the codebase

Explore the project structure and understand:

• Tech stack (language, framework, build tools)
• Directory structure and architectural patterns
• Existing configuration (package.json, go.mod, etc.)
• Key entry files

Step 2: Design the task list

Based on the user's requirements, break the work down into specific features. Each feature requires:

• A unique id(e.g., feat-01、v2-05）
• category Category (foundation, layout, components, etc.)
• priority Priority (the smaller the number, the higher the priority)
• description A one-sentence description
• file The main file paths involved (can be null)
• steps An array of specific operation steps (one string per step)
• passes A boolean value (initially false)
• verification Verification conditions

Step 3: Generate 4 Harness files

Generate the following files in the project root directory:

feature_list.json — Task list (single source of truth)

{
  "project": "项目名称",
  "description": "项目描述",
  "features": [
    {
      "id": "feat-01",
      "category": "foundation",
      "priority": 1,
      "description": "一句话描述要做什么",
      "file": "path/to/main/file.js",
      "steps": [
        "具体步骤 1",
        "具体步骤 2"
      ],
      "passes": false,
      "verification": "如何验证这个功能已完成"
    }
  ]
}

See the full template at references/templates/feature_list.json

Why use JSON instead of Markdown? Models tend to freely rewrite Markdown files (rewording, restructuring, deleting content). JSON files are treated more cautiously by models—they are more likely to modify only specific fields. This is crucial for maintaining task integrity.

progress.txt — Narrative progress log

Record the detailed work content of each session so that subsequent sessions can understand the context.

See the full template at references/templates/progress.txt

init.sh — Environment initialization script

Run at the start of each new session to restore all context within 5 seconds.

See the full template at references/templates/init.sh

task.json — Project overview

Record project-level information such as milestones, rules, and file lists.

See the full template at references/templates/task.json

Step 4: Configure AGENTS.md rules

In the project's AGENTS.md file, add a Task Management System section to ensure all Agent sessions follow the workflow. Refer to the corresponding section in the current project's AGENTS.md .

Step 5: First verification

Run bash init.shand confirm:

• The script executes normally
• feature_list.json parses correctly
• Progress statistics are displayed accurately

Step 6: Output next-step guidance

Tell the user:

• The list of files created
• How to start the first task
• How to resume work in a new session

Agent workflow (per session)

1. bash init.sh                    ← 5 秒上下文恢复
2. Read progress.txt               ← 理解之前做了什么、为什么
3. Read feature_list.json          ← 找到优先级最高的未完成功能
4. Pick 1~2 features               ← 不要贪多，增量推进是关键
5. Execute the feature's steps     ← 严格按步骤执行
6. Verify                          ← 必须实际验证，不要假设
7. Update feature_list.json        ← 只改 passes: false → true
8. git commit                      ← 一个功能一个 commit
9. git push                        ← 同步到远程
10. Append progress.txt            ← 记录本次会话的工作

Strict rules

• Only modify the passes field: In feature_list.json, only change passes from false to true. Never delete features, edit descriptions, change priorities, or restructure the JSON.
• One feature at a time: Unless the feature is very small (for example, changing a constant), do only one feature per session.
• Must commit + push: After each feature is completed, you must git commit and push to ensure progress is never lost and can be rolled back independently.
• Must verify before marking complete: Read the code, run the dev server, or check the output. Do not trust assumptions.
• Must update progress.txt: Update the progress log at the end of the session so the next session has full context.
• Stop when blocked: Record the reason for the blockage in progress.txt and stop. Do not silently work around the problem.

Relationships between files

init.sh ──读取──→ feature_list.json (任务状态)
    │
    └──提示──→ progress.txt (历史上下文)

task.json ────→ 项目总览（里程碑、规则、文件清单）

AGENTS.md ────→ Agent 行为规范（引用 harness 规则）

References

• Methodology details — why use a harness, common issues, best practices
• Template files — blank templates for all harness files