task-harness

Task Harness — Structured Task Management System

Decompose 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.

By default, used in combination with harness-engineering Combined usage：

• harness-engineering is responsible for the main loop (AGENTS.md + Plan/Build/Verify rules)
• task-harness is responsible for the task layer (feature_list.json + TASK-HARNESS.md + progress tracking)
• After the two are merged, they form:Decompose tasks -> Execute sprints -> QA acceptance -> Update task status

When to use

• Large requirements need to be decomposed into multiple subtasks
• The project needs continuous development across multiple Agent sessions
• Need to track feature completion progress (completed / not completed)
• The user says "decompose tasks", "task management", "project planning", "create task list"

Prerequisites (recommended)

Prioritize executing harness-engineering initialization in the project to ensure the following exist:

• Root directory AGENTS.md(Codex main execution contract)
• docs/specs/、docs/contracts/、docs/plans/
• hooks and Plan-Build-Verify rules

If the project has not yet initialized Harness Engineering, first prompt the user to complete initialization, then create the task-harness files.

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 user requirements, decompose the work into specific feature points (features). Each feature point needs:

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

Step 3: Execute scaffolding (preferred)

Prefer using the scaffolding script to generate task-layer files:

python3 {{SKILL_PATH}}/scripts/scaffold.py \
  --project-name "<项目名称>" \
  --description "<项目描述>" \
  --tech-stack "<技术栈>" \
  --design-guidance "<设计约束，可选>" \
  --target-dir "<当前项目目录>"

The script by default requires the target directory to contain AGENTS.md(main loop contract).
If this check really needs to be skipped, append:--allow-missing-main-contract。

Step 4: Generate 5 Harness files (script outputs)

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 complete template at references/templates/feature_list.json

Why use JSON instead of Markdown? Models tend to freely rewrite Markdown files (rewording, reorganizing structure, deleting content). JSON files are treated more cautiously by models—they are more likely to modify only specific fields. This is critical 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 complete template at references/templates/progress.txt

init.sh — Environment initialization script

Run at the start of every 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

TASK-HARNESS.md — Task-layer execution contract (does not override AGENTS.md)

Define task breakdown and progress tracking rules, and explicitly require following the Harness main loop in the root directory AGENTS.md during execution.

See the full template at references/templates/TASK-HARNESS.md

Step 5: Validate TASK-HARNESS.md rules

Replace according to the project context TASK-HARNESS.md placeholders in the template (project name, project description), and ensure its rules are consistent with feature_list.json .

Also check whether the root directory AGENTS.md exists:

• Exists: keep it without overriding, and integrate it directly for use
• Does not exist: prompt to first run harness-engineering initialization

Step 6: First validation

Run bash init.sh, and confirm:

• The script executes normally
• feature_list.json parses correctly
• Progress statistics display accurately
• TASK-HARNESS.md has been created
• Root directory AGENTS.md exists and can be used for the Codex main loop

Step 7: Output next-step guidance

Tell the user:

• The list of created files
• How to start the first task according to AGENTS.md + TASK-HARNESS.md Start the first task
• How to resume work in a new session

Agent workflow (each session)

1. bash init.sh                    ← 5 秒上下文恢复
2. Read AGENTS.md                  ← 主闭环（Plan/Build/Verify）契约
3. Read TASK-HARNESS.md            ← 任务层契约
4. Read progress.txt               ← 理解之前做了什么、为什么
5. Read feature_list.json          ← 找到优先级最高的未完成功能
6. Pick 1 feature                  ← 一次只推进一个功能
7. Execute plan/build/qa loop      ← 严格按 Harness Engineering 流程
8. Verify unit tests pass          ← 通过后才允许标记完成（QA 非阻塞）
9. Update feature_list.json        ← 仅改 passes: false → true
10. Append progress.txt            ← 记录本次会话结果与下一步
11. git commit + git push          ← 同步稳定进度

Strict rules

• AGENTS.md is the primary contract: The Plan -> Contract -> Build -> QA -> Fix loop process must be executed; skipping stages is prohibited.
• Only modify the passes field: In feature_list.json, only change passes from false to true. Never delete features, edit descriptions, modify priorities, or reorganize the JSON.
• One feature at a time: Each session should preferably do only one feature to avoid context pollution.
• Use unit tests as the passing gate: Once unit tests pass, update passes=true; QA reports are used for quality tracking and do not block the process.
• Must commit + push: After each feature is completed, git commit and push must be performed to ensure progress is never lost and can be rolled back independently.
• Must update progress.txt: Update the progress log at the end of the session so the next session has complete context.
• Stop when blocked: Record the blocking reason in progress.txt and stop. Do not silently bypass the problem.

Relationships between files

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

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

AGENTS.md ───────→ Harness 主执行契约（Plan/Build/Verify）
TASK-HARNESS.md ─→ 任务层执行契约（挑任务/更新 passes/记录进度）

References

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