by-harness

by-harness

is an independent skill used to install and run a stable engineering closed-loop for target repositories:

text

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

The core goal is not to "add more documents", but to ensure that every model development has clear task sources, specifications, implementation boundaries, acceptance methods, and session closure records.

1. First determine user intent

After receiving a request, first categorize the user's intent into one of the items in the table below, then perform the corresponding action.

User Intent	Common Phrases	Main Actions
Initialize harness	"Initialize", "Initialize this repository with by-harness"	Run `scripts/scaffold.py` , then prompt to execute or execute `.harness/scripts/init.sh`
Continuous task decomposition	"Decompose tasks continuously", "Split into 5 tasks", "Split this topic"	Run `scripts/decompose_tasks.py` and write to the active bucket
Execute a specific task	"Execute feat-03", "Continue the current task"	Read the task and advance through the plan/build/qa/fix/mark_pass closed-loop
Session closure	"Close the session", "Save progress", "session_close"	Run `.harness/scripts/session_close.py`
Automatic resumption	"Continue to the next task", "Automatic resumption"	Run `.harness/scripts/task_switch.py continue --target-dir .`
Legacy repository upgrade	"Upgrade harness", "Sync runtime", "Update scaffolding"	Run `scripts/update_runtime.py` , prioritizing backup and versioned migration
Java specification constraint	"Java hard rules", "Service interface implementation", "MapStruct/amount/Redis/pagination rules"	Use Chapter 7 Java Gate of `.harness/docs/java-dev-conventions.md` to constrain plan/build/qa
Distributed Java constraint	"Distributed coding specifications", "Idempotency/retry/lock/transaction/message/cache consistency"	Use Chapter 14 Distributed Java Gate of `.harness/docs/java-dev-conventions.md` to constrain spec/contract/build/qa
Frontend specification constraint	"Frontend specifications", "UI constraints", "Follow design draft/reference page"	Use the issued three-tier frontend specifications and BYAI HTML references to constrain implementation

If the project name, target directory, or task ID is missing, infer it directly from the current repository and

.harness/task-harness/index.json

when possible; ask a brief question only if the inference risk is high.

2. Initialize target repository

Initialization uses the skill's built-in script:

bash

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 entries:
```
AGENTS.md
```
,
```
CLAUDE.md
```
Codex / Claude configurations:
```
.codex/
```
,
```
.claude/
```

Harness workspace:

.harness/config/

.harness/docs/

.harness/scripts/

.harness/task-harness/

Task index:
```
.harness/task-harness/index.json
```

Default task bucket:

.harness/task-harness/features/backlog-core.json

Runtime version:
```
.harness/config/runtime-version.json
```
Update policy:
```
.harness/config/update-policy.json
```

After initialization is complete, execute or prompt:

bash

bash .harness/scripts/init.sh

Do not use

--force

by default in existing projects. Only use it when the user explicitly requests overwriting.

3. Task storage model

Sharded task storage is used by default:

```
.harness/task-harness/index.json
```
: Routing index, records the active bucket.
```
.harness/task-harness/features/*.json
```
: Task shards.
```
.harness/task-harness/progress/latest.txt
```
: Latest session snapshot, for quick resumption in new sessions.

.harness/task-harness/progress/YYYY-MM.md

: Monthly appended session history.

.harness/feature_list.json

is only used for legacy project compatibility: If the file already exists in an old project, you can continue to sync the active bucket view; do not actively create it for new projects.

4. Continuous task decomposition

When users request to decompose requirements, append tasks, or expand the backlog, run:

bash

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

Execution principles:

Try to meet the quantity specified by the user; if not specified, usually split into 4-8 executable tasks.

Each task must be able to enter the

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

closed-loop.

New tasks are written to the active bucket by default; switch buckets only when specified by the user.
Report the new task IDs, priorities, recommended execution order, and next command.

When there are too many tasks or the old

feature_list.json

is too large, you can run:

bash

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

5. Execute task closed-loop

When users request to execute a feature, proceed in the following order:

Locate the task: Prioritize using the
```
feat-id
```
provided by the user; if not available, use
```
.harness/scripts/ensure_task_branch.py
```
to select the current task.

Read the task: Check

description

steps

spec_path

contract_path

qa_report_path

Plan: Generate or update
```
.harness/docs/specs/<feature>.md
```
.
Build: Only implement content within the contract scope.
QA: Run available tests; QA is non-blocking by default, but failures must be recorded.
Fix: Fix up to 3 rounds if unit tests fail.
Mark pass: Only change
```
passes=false
```
to
```
true
```
after unit tests pass and the
```
spec_path
```
/
```
contract_path
```
files actually exist.
Session close: Call the session closure script to refresh the latest progress.

If unit tests still fail after 3 rounds, keep

passes=false

, record the reason, attempted fixes, and next-step suggestions.

6. Session closure and resumption

Run the following each time a session ends or the user requests to save progress:

bash

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

The closure script will:

Append progress logs.

Refresh

.harness/task-harness/progress/latest.txt

Output suggestions for the next task.

Run the following to continue to the next task:

bash

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

7. Legacy repository upgrade

Prioritize versioned upgrades for legacy repositories, do not re-overwrite entirely:

bash

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

Upgrade behavior:

First back up key configurations, scripts, and runtime documents.
Read
```
.harness/config/runtime-version.json
```
.
Pull from the remote manifest and verify the checksum if
```
manifest_url
```
exists.
Only perform local compatibility migration if there is no
```
manifest_url
```
.
Only issue an alert and do not downgrade/overwrite if the current version is higher than the built-in or remote version.

Use the following for remote scheduled checks:

bash

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

The default

update-policy.json

enabled=false

; automatic checks are only performed after the user configures

manifest_url

and enables it.

8. Engineering specification distribution

Two types of engineering specifications are distributed during initialization:

Backend:
```
.harness/docs/java-dev-conventions.md
```

Frontend entry:

.harness/docs/frontend-dev-conventions.md

Java backend adopts Java Gate:

Declare trigger items in the Plan phase: Service, entry dependencies, MapStruct, Chinese comments, amount, pagination, Redis, logs, configuration keys.
All Java changes must declare Distributed Java Gate: Explain the reason if not triggered; when triggering external calls, Dubbo/HTTP/RPC, MQ, asynchronous operations, thread pools, locks, Redis, transactions, compensation, or release downtime, must check against Chapter 14 item by item.
In the Contract phase, Java Gate and Distributed Java Gate must be converted into an acceptable checklist, not just write "have read the specifications".
In the Build phase, repeat the applicable checklist and implement according to positive and negative examples.
In the QA phase, accept according to the contract and convention-check results.
In the Stop hook phase, automatically intercept machine-identifiable fail/warn.

Frontend adopts a three-tier structure:

Constraint layer:
```
.harness/docs/frontend/rules.md
```
Demonstration layer:
```
.harness/docs/frontend/code-design.md
```
Visual layer:
```
.harness/docs/frontend/ui-design.md
```

Visual reference:

.harness/docs/frontend/references/byai-ds-v/index.html

When the current task involves React, Vue, Next.js, TypeScript components, UI, styles, tables, forms, charts, Agent interfaces, or interaction states, the model must first read

.harness/docs/frontend-dev-conventions.md

, then read the three-tier specifications according to the task type.

When adding a new page, refactoring a page, or making obvious visual changes, you must also open the BYAI HTML reference page. The reference page is used to understand layout, density, status, tokens, and visual temperament; do not directly copy the demo HTML into business implementations.

9. Runtime constraints

```
AGENTS.md
```
is the main contract, defining Plan / Build / Verify / Fix.
```
.harness/docs/TASK-HARNESS.md
```
is the task-level contract and must not overwrite the main contract.
Regular tasks only update task status, progress, and closed-loop artifacts; do not arbitrarily modify the task structure.
```
passes=true
```
can only be set after unit tests pass and the spec/contract has been saved to disk; QA reports are non-blocking by default, but results must be recorded.
For any feature marked
```
passes=true
```
, if the corresponding
```
spec_path
```
or
```
contract_path
```
file is missing, the pre-completion hook must block completion.
All newly added or modified functions and methods must be supplemented with Chinese comments explaining their purpose, key parameters, return values, and side effects.
When involving Java, self-check Java Gate before completion: Service interface/implementation, entry dependency interface, MapStruct ERROR, amount, pagination, Redis, logs, configuration keys; also self-check Distributed Java Gate and run convention-check.
When involving frontend, self-check tokens, status coverage, responsiveness, accessibility, alignment with BYAI reference pages, and avoidance of negative examples before completion.
Do not use destructive git commands, do not overwrite existing user modifications, and do not use
```
--force
```
by default in existing projects.

10. Reporting format

After execution is complete, report using a concise structure:

What was done: Initialization, task decomposition, task execution, session closure, or upgrade.
Where changes were made: List key files or directories.
Verification results: Script output, tests, dry-run, or reason for no verification.
Next step: Provide the most appropriate command or task ID.

11. Typical prompts

Initialize this repository with by-harness, project name xxx, goal is xxx

Continuously decompose tasks, topic: Payment link stability, split into 5 tasks

Execute feat-03, strictly follow read task -> plan -> build -> qa -> fix -> mark_pass

Close the current session, record the qa score and next step

Upgrade the harness runtime in this project

Check this Java feature against Java Gate for Service, amount, Redis, pagination, and configuration

Check this Java feature against distributed coding specifications for idempotency, retry, lock, transaction, and message

Redo this frontend page according to BYAI references and three-tier specifications

by-harness

NPX Install

Tags

SKILL.md Content (Chinese)

by-harness

1. First determine user intent

2. Initialize target repository

3. Task storage model

4. Continuous task decomposition

5. Execute task closed-loop

6. Session closure and resumption

7. Legacy repository upgrade

8. Engineering specification distribution

9. Runtime constraints

10. Reporting format

11. Typical prompts