by-harness

by-harness

by-harness is a standalone skill used to install and run a stable engineering closed loop for the target repository:

read task -> plan -> build -> qa -> fix -> mark_pass -> session_close

The core goal is not to "put in more documentation," but to ensure that every development session by the model has a clear task source, specification, implementation boundary, acceptance method, and session closure record.

1. First determine the user's intent

After receiving the request, first classify the user's intent into one of the following categories, then perform the corresponding action.

User intent	Common phrasing	Main action
Initialize harness	"Initialize" "Use by-harness to initialize this repository"	Run scripts/scaffold.py, then prompt to execute or execute .harness/scripts/init.sh
Continuous task decomposition	"Continuously decompose tasks" "Decompose 5 tasks" "Decompose this topic"	Run scripts/decompose_tasks.py, by default add a v3 single-task file
Execute a certain task	"Execute a certain task ID" "Continue the current task"	Read the task, advance through the plan/build/qa/agent-review/fix/mark_pass closed loop
Quick mode	"quick fix" "fast-track" "fix an error" "locally adjust validation rules"	Natural language changes that do not explicitly specify plan/build/qa/sprint also first run .harness/scripts/quick_fix_classifier.py; high quick-fix goes through lightweight repair, high/medium fast-track goes through the local fast lane, low automatically returns to the standard closed loop
Session closure	"closure" "save progress" "session_close"	Run .harness/scripts/session_close.py
Automatic continuation	"Continue to the next task" "automatic continuation"	Run .harness/scripts/task_switch.py continue --target-dir .
Legacy repository upgrade	"Upgrade harness" "Sync runtime" "Update scaffolding"	Run scripts/update_runtime.py, by default no backup file is created; when a rollback snapshot is truly needed, explicitly pass --backup
Java specification constraints	"Java hard rules" "Service interface implementation" "MapStruct/amount/Redis/pagination rules"	First read the .harness/docs/java-dev-conventions.md entry point, then read the .harness/docs/java/rules/ sharded rules according to the trigger dimension
Distributed Java constraints	"Distributed coding specification" "idempotency/retry/lock/transaction/message/cache consistency"	Use .harness/docs/java/rules/distributed-java-gate.md to constrain spec/contract/build/qa

After the user initiates a by-harness instruction, the technical solution, requirement description, or task background provided by default has already been confirmed by the user. Do not repeatedly clarify requirements; when it can be inferred from the current repository, technical solution,.harness/task-harness/index.json and existing spec/contract, directly form assumptions, trade-offs, risks, and out-of-scope items and continue producing. Only when the target directory/task ID cannot be located at all, or the next step would perform a destructive operation, ask one necessary question.

2. Initialize the target repository

Initialization uses the skill's built-in script:

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

After initialization, the following are generated:

• Root directory entry:AGENTS.md、CLAUDE.md
• Codex / Claude configuration:.codex/、.claude/
• Harness workspace:.harness/config/、.harness/docs/、.harness/scripts/、.harness/task-harness/
• Task index:.harness/task-harness/index.json
• Default task directory:.harness/task-harness/tasks/
• Runtime version:.harness/config/runtime-version.json
• Update policy:.harness/config/update-policy.json

If the target repository already has AGENTS.md / AGENT.md / agents.md / agent.md or CLAUDE.md / claude.md, both initialization and upgrade must preserve the original content and only merge or replace the by-harness managed block between <!-- BEGIN BY-HARNESS MANAGED BLOCK --> and <!-- END BY-HARNESS MANAGED BLOCK --> .

After initialization is complete, execute or prompt:

bash .harness/scripts/init.sh

Project root AGENTS.md / CLAUDE.md will require that at the start of every new session, before handling user requests, the following is run first:

python3 .harness/scripts/update_runtime.py --target-dir . --check-remote

This check is still subject to .harness/config/update-policy.json 's check_interval_minutes limit; by default it will not access the remote repeatedly within 12 hours; failures only record the reason and do not block development.

Do not use --forceby default in an existing project. Use it only when the user explicitly requests overwriting.

3. Task storage model

By default, use v3 single-task file storage:

• .harness/task-harness/index.json: stable routing index, records task_globs, and daily task breakdown does not modify it.
• .harness/task-harness/tasks/*.json and .harness/task-harness/tasks/**/*.json: authoritative task source, with one independent JSON file per task; new tasks are archived by batch directory by default.
• .harness/task-harness/progress/YYYY-MM/*.md: one independent progress file per session, avoiding multiple branches appending to the same monthly file at the same time.
• .harness/task-harness/progress/latest.txt: legacy-compatible snapshot, not used as the authoritative progress source.
• .harness/task-harness/features/*.json: only used for v2/legacy bucket read compatibility, not as the default write target for new tasks.
• session-context.json / session-boundary.json is disabled: closure and continuation rely only on session logs, task status, and model prompts, and no longer write session runtime JSON that causes branch conflicts.

.harness/feature_list.json is only used for legacy project compatibility: if the file already exists in an old project, it can continue to serve as the old active bucket view; new projects should not proactively create it.

Task IDs no longer use feat-01 this kind of globally incrementing sequence number. Internally, new tasks still retain a machine ID composed of a UTC timestamp, type prefix, description slug, and short hash, for example:

20260508T153012Z-feat-login-rate-limit-a3f9c2

File names and display names use the batch number, task number, Chinese title, and short hash, for example:

.harness/task-harness/tasks/B001-20260508T153012Z-音频转写/
  T001-音频转写记录DDL和Mapper仓储-a3f9c2.json

The task JSON will contain batch_id、batch_name、display_id、local_display_id、task_no、title and display_name. For daily location, prefer display_id(such as B001-T001), and the full machine ID is also compatible. Sorting depends on priority、created_at、id, do not encode execution order into the machine ID.

4. Continuous task breakdown

When the user requests decomposing requirements, appending tasks, or expanding the backlog, run:

python3 {{SKILL_PATH}}/scripts/decompose_tasks.py \
  --target-dir "<项目目录>" \
  --item "<任务描述1>" \
  --item "<任务描述2>" \
  --category "feature"

Execution principles:

• Task granularity should preferably be fewer and complete, not fragmented; when no quantity is specified, usually break down into 2-5 independently acceptable functional tasks.
• Each task must be a complete, verifiable, independently closed-loop functional slice: including business goals, main implementation surfaces, acceptance criteria, and verification methods, and able to enter the read task -> plan -> build -> qa -> fix -> mark_pass closed loop.
• Do not break down tasks by technical layer, file, or step: do not split the same feature into DDL、Mapper/DAO、Service、Controller/API、前端页面、测试、文档 and other separate tasks; these should be treated as the same functional task's steps。
• Only when the sub-item itself can be independently released, independently verified, independently rolled back, and has its own acceptance criteria should it be split into a separate task.
• New tasks are added by default to .harness/task-harness/tasks/<批次目录>/, and backlog-core.json or index.json。
• must not be modified in order to append tasks. Report the new task ID, priority, suggested execution order, and next command.

Old feature_list.json Only when or the v2 bucket is too large, consider running the legacy rebalancing tool:

python3 {{SKILL_PATH}}/scripts/rebalance_tasks.py --target-dir "<项目目录>"

5. Task Execution Loop

When the user requests executing a feature, proceed in the following order:

1. Locate task: prefer the task ID given by the user; if absent, use .harness/scripts/ensure_task_branch.py scan the single-task files and legacy bucket, then select the current task.
2. Read task: see description、steps、spec_path、contract_path、qa_report_path。
3. Plan: generate or update .harness/docs/specs/<feature>.md。
4. Build: only implement content within the contract scope.
5. QA Gate: run available tests,convention-check, required integration test gates, and Agent Review Closeout (single-pass, review only once); failures must record the issue.
6. Fix: fix all issues in one pass based on the QA Gate and Agent Review results; when unit tests fail, fix at most 3 rounds.
7. Mark pass: only after unit tests pass, required QA Gate passes, required Agent Review (if enabled) has no accepted/actionable finding, and the spec_path / contract_path file actually exists, may passes=false be changed to true。
8. Session close: call the session closeout script, and write an independent progress shard.

If unit tests still fail after 3 rounds, keep passes=false, and record the reason, attempted fixes, and next-step suggestions.

6. Quick / Fast Track Triage

When the user requests a clear, local, verifiable change, run the classifier first instead of directly entering the full feature loop. Even if the user does not explicitly say quick-fix or fast-track, as long as the request is a natural-language change such as fixing, adjusting, optimizing, adding tests, changing validation, changing prompts, or handling an error, and plan/build/qa/sprint is not explicitly specified, classification must be performed first:

python3 .harness/scripts/quick_fix_classifier.py \
  --target-dir . \
  --prompt "<用户原始改动描述>"

Classifier output confidence、recommended_mode、risk_flags、changed_files and diff statistics:

• confidence=high and recommended_mode=quick_fix: may enter quick-fix.
• recommended_mode=fast_track and confidence=high|medium: may enter fast-track.
• confidence=low or recommended_mode=standard_feature: must go through the standard read task -> plan -> build -> qa -> fix -> mark_pass。

Allowed scope for Quick/Fast Track:

• quick-fix: clear errors, null protection, typos, log levels, error messages, small unit test/compilation fixes; expected no more than 5 files, post-diff no more than 200 lines.
• fast-track: local business logic adjustments, internal validation rules, Mapper/conversion logic, non-public configuration, small frontend interactions, test supplementation, local exception handling; expected no more than 8 files, post-diff no more than 400 lines.
• Does not involve DB migration, permissions/security, billing, rate limiting, cache consistency, transactions, idempotency, external APIs, public DTOs, or interface contracts.

After execution, must review:

python3 .harness/scripts/quick_fix_classifier.py \
  --target-dir . \
  --phase post-diff \
  --prompt "<用户原始 bug 描述>"

If post-diff shows risk_flags, exceeds the file/line thresholds, or the reason for verification failure is unclear, immediately supplement spec/contract and escalate to the standard loop. quick-fix/fast-track only writes progress logs, and must not modify the task definition or set feature passes to true。

Quick-fix closeout uses:

python3 .harness/scripts/session_close.py \
  --target-dir . \
  --quick-fix \
  --title "<bug 标题>" \
  --outcome pass \
  --note "<修改文件、验证命令和结果>"

If quick-fix is associated with an existing task, --feature-id "<task-id>" may be appended as a log reference, but the task's spec/contract/QA Gate gates still cannot be bypassed.

Fast-track closeout uses:

python3 .harness/scripts/session_close.py \
  --target-dir . \
  --fast-track \
  --title "<改动标题>" \
  --outcome pass \
  --note "<范围、风险判断、验证命令和结果>"

7. Session Closeout and Resumption

At the end of each session or when the user requests saving progress, run:

python3 .harness/scripts/session_close.py \
  --target-dir . \
  --feature-id "<task-id>" \
  --outcome "pass|fail|blocked|in-progress" \
  --qa-score "<0-100，可选>" \
  --note "<本轮摘要>"

completed as a legacy command compatibility alias, which will be mapped by the script to pass; new commands must prioritize pass。

The closeout script will:

• Write .harness/task-harness/progress/YYYY-MM/<timestamp>-<task-id>.md Independent progress log.
• quick-fix/fast-track writes .harness/task-harness/progress/YYYY-MM/<timestamp>-quickfix|fasttrack-<slug>.md, and records in the log work_mode=quick_fix|fast_track。
• legacy project compatibility refresh .harness/task-harness/progress/latest.txt。
• Outputs the next task suggestion.

To continue with the next task, run:

python3 .harness/scripts/task_switch.py continue --target-dir .

8. Legacy repository upgrades

Legacy repositories should prioritize versioned upgrades; do not overwrite everything in full again:

python3 {{SKILL_PATH}}/scripts/update_runtime.py --target-dir "<项目目录>"

Upgrade behavior:

• By default, no backup files are created; if a pre-upgrade snapshot is truly needed, explicitly pass --backup。
• Read .harness/runtime-cache/runtime-version.json, and if there is no cache state, then read .harness/config/runtime-version.json。
• When there is manifest_url When present, pull from the remote manifest and verify the checksum; the Python runtime and hook write to .harness/runtime-cache/, and only a stable wrapper is kept in the project tracked location, to avoid repeated runtime diffs across multiple branches.
• When there is no manifest_url only local compatibility migration is performed.
• When the current version is higher than the built-in or remote version, only warn; do not downgrade and overwrite.

Remote scheduled checks use:

python3 .harness/scripts/update_runtime.py --target-dir . --check-remote

Default update-policy.json is enabled=false; it only checks automatically after the user configures manifest_url and enables it.

9. Engineering standards distribution

Initialization distributes Java engineering standards:

• Java entry point:.harness/docs/java-dev-conventions.md
• Java shards:.harness/docs/java/rules/

The Java backend adopts a sharded Java master gate and incorporates implementation rules validated by real projects:

• During the Plan phase, first read the Java entry point, then read shard rules according to trigger dimensions:00-core.md、java-ddd.md、dubbo-api.md、logging-error.md、persistence-infra.md、testing-security.md、distributed-java-gate.md。
• During the Plan phase, a minimal entity and cost assessment must be performed: do not add entities unless necessary; for small changes in legacy projects, prioritize reusing existing entities, tables, DTOs, Services, configurations, and extension points.
• All Java changes must address the 5 Java master gate items: contract before implementation, local before general, boundaries not breached, risks explicitly addressed, and verification traceable.
• Business states, task types, action types, error codes, configuration keys, and thresholds must not be scattered as magic strings/magic numbers; use enums, semantic constants, or configuration items for centralized management.
• Append about 5 core gates by trigger dimension: general engineering, layering and DDD, Dubbo and public API, logging and exceptions, persistence and infrastructure, test security operations, distributed Java gate.
• All Java changes must declare the distributed Java gate: if not triggered, provide a reason; when external calls, Dubbo/HTTP/RPC, MQ, async, thread pools, locks, Redis, transactions, compensation, or release downtime are triggered, they must be checked item by item against distributed-java-gate.md。
• During the Contract phase, the Java master gate, trigger dimension core gates, and distributed Java gate must be converted into an acceptance checklist; do not merely write “standards have been read”.
• During the Build phase, restate the master gate and trigger dimension gates, and implement according to positive and negative examples.
• During the QA phase, accept against the contract, trigger shards, convention-check, Testcontainers integration test matrix, and QA result JSON.
• During the Stop hook phase, automatically intercept machine-identifiable fail/warn.

10. Runtime constraints

• AGENTS.md is the master contract, defining Plan / Build / Verify / Fix.
• .harness/docs/TASK-HARNESS.md is the task-level contract and must not override the master contract.
• Routine tasks only update the status, progress, and closed-loop artifacts of the corresponding single-task JSON, and do not arbitrarily change the task structure.
• quick-fix/fast-track is only used for quick bypass logging and must not be used as the basis for feature completion; when a feature must be completed, you must return to the standard gates.
• The planning solution must follow "do not add entities unless necessary"; small changes to historical projects are implemented at minimum cost by default, and any new entity/table/DTO/Service/configuration item must state its necessity, alternatives, migration cost, and rollback impact.
• Only after unit tests pass, the required QA Gate passes, the required Agent Review (if enabled) passes, and the spec/contract has been written to disk may passes=true; advisory/manual QA and Agent Review results must be recorded.
• For any feature that has been marked passes=true , if it lacks spec_path or contract_path corresponding file, the pre-completion hook must block completion.
• All newly added or modified functions and methods must have Chinese comments added, explaining their purpose, key parameters, return values, and side effects.
• When Java is involved, before completion self-check the Java overall gate, magic value governance, trigger dimension core gates, and distributed Java gates, and run convention-check. When reading specifications, you must first read the entry point, then read the shards by trigger dimension; you must not load all rules as a whole package by default.
• Do not use destructive git commands, do not overwrite the user's existing changes, and do not by default in an existing project --force。

11. Reporting format

After execution is complete, report briefly in a structured way:

• What was done: initialization, task breakdown, task execution, quick-fix/fast-track, wrap-up, or escalation.
• What was changed: list key files or directories.
• Verification results: script output, tests, dry-run, or the reason verification was not performed.
• Next step: provide the single most appropriate command or task ID.

12. Typical prompts

• 用 by-harness 初始化这个仓库，项目名 xxx，目标是 xxx
• 持续拆任务 主题：支付链路稳定性，拆 5 个
• 执行 20260508T153012Z-feat-login-rate-limit-a3f9c2，严格按 read task -> plan -> build -> qa -> fix -> mark_pass
• quick-fix 修复一个明确小 bug，先分类，修完后 quick close
• fast-track 调整一个局部校验规则，先分类，修完后 fast close
• 把当前会话收口，记录 qa 分数和下一步
• 升级这个项目里的 harness runtime
• 这个 Java 功能按 Java 总门禁检查 Service、金额、Redis、分页和配置
• 这个 Java 功能按分布式编码规范检查幂等、重试、锁、事务和消息