This skill is responsible for connecting Harness to a specific project. The machine environment, persistent source code, and user-level skill links are handled by harness-download . This skill starts from an available CLI. During the complete onboarding process, the same Agent executes continuously, and the user is not required to re-issue instructions between stages.
Entry point and version
Use the complete skill package from the source code selected for this installation, and do not mix skills and the CLI from different versions. The official source distribution comes from main; you can use git show origin/main:skills/harness-install/SKILL.md to verify the release branch; when explicitly validating a candidate branch, use that candidate package and record the version.
Do not write before reading the project. Check the existing harness/、.harness/, configuration, and CLI-readable status:
- There is already a currently usable ledger: reuse the workspace, move on to master control initialization and the user task, and do not re-
init。 - It is clearly confirmed to be a legacy-generation ledger and the user wants to migrate: go to harness-migration, and retain its data-handling approval.
harness/is an unrelated business directory, or the existing content cannot be determined: show the real conflict, clarify first, and do not overwrite.- There is no ledger: continue.
0. Read the project first
Read the project layout, Git status and history, existing AGENTS.md / CLAUDE.md, ignore rules, CI, and build and test entry points. Do not ask the user for answers that can be obtained from disk.
| Observation | Impact on the next step |
|---|---|
| The current initialization method requires Git, but the project has no repository or commit | First establish the necessary foundation within the target authorized by the user, and do not operate on other directories |
| Existing Agent instructions | Prepare a merge draft, retain the original instructions, and obtain specific merge approval |
| Existing ignore rules | After initialization, read back the diff to confirm that the private ledger will not enter the public project |
| There is CI | Record the real verification entry point, and close out the first task according to actual results |
| There is no CI | Do not treat completion parameters as real runtime evidence; obtain verifiable results according to the task type, and clearly state that CI was not run |
| Multi-person collaboration | Explain in advance the actual binding of the owner and review identities; environment variables cannot be treated as another person |
| The user has already given a first task | Reuse it directly, and do not create another placeholder task named "installation test" |
Only merge in the project identifier, first task, and other information still missing from the inquiry. The owner identity and instruction file merge still retain specific approval as described below.
1. Obtain the current CLI entry point
Reuse harness-download the absolute source entry point and Node path passed in. When the tool is not ready, read the download skill in the same skill package, complete its environment, source code, and linking stages, and then return; do not copy the clone or npm installation recipe again here.
Below, ha represents the CLI verified for this session. If source code is used, subsequent calls are all expanded to node "<源码目录>/packages/cli/src/index.ts" ...; a temporary shell function will not be automatically retained across tool calls, so do not pack "node plus arguments" into a string and then execute it as a command.
Check whether the target already has a central registration and an in-flight initialization, and use the normal service root. Do not pass HARNESS_DAEMON_USER_ROOT to switch to a test root for a formal installation; if you find that an existing environment points to an isolated root, first verify its purpose, explicitly choose the formal entry point, and do not silently wipe out the user's existing configuration.
2. Confirm the initial owner
Read the current ha init --help. Show the user the person identifier, display name, and current transport identity binding that will be written, then obtain an explicit answer. If the same content has already been confirmed, reuse it; do not guess the owner from git config user.name and write it directly.
For example, a local Unix socket transport may use the following binding; the actual fields are provided by the current initialization capability:
{
"personId": "<用户确认的标识>",
"displayName": "<用户确认的显示名>",
"roles": ["owner"],
"credentials": [{ "kind": "unix-socket-owner-boundary", "issuer": "host:<主机>", "subject": "<uid>" }]
}
Explain the correspondence boundary between one system account and one human identity; changing an environment variable will not make it a different user. Subsequent personnel changes go through the existing write entry point of ha people , do not hand-edit people.yaml, and do not bypass the personnel registration contract via general document synchronization.
3. Initialize and read back
The command shape is subject to the current help; execute it in the explicit target repository:
ha --root "<目标仓库绝对路径>" init --repo-id <项目标识> --person-id <人员标识> --display-name "<显示名>"
If the initial local installation requires a Git baseline, first verify whether a repository and commits already exist, and only add what is genuinely missing; do not reset the original history. Multiple edge nodes cannot each initialize the same logical workspace; the party currently authorized to coordinate completes the central write, and other nodes connect to the existing record.
Read back rather than only looking at the success receipt:
preserved/driftedcontains the original Agent file, confirm whether the new entry point has not yet been added, and continue to the next section.- Use
git check-ignore -v harness .harnessandgit ls-files harness .harnessto check the private directory boundaries and inspect the actual ignore differences.git check-ignore -qpasses only one path at a time. - Use the current JSON status entry point to check whether the workspace is registered and attached, and do not mechanically redo the next step in the receipt.
- Automatic ledger commits and target project commits are two different things. List the instructions and ignore files created or modified in the project; whether to commit project changes is handled according to the user's scope.
- The ledger branch may differ from the project branch; do not rename a branch that is currently in service just to unify names.
On failure, first identify which writes have completed, whether there is a current holder, and what recovery paths are available. Do not automatically delete the ledger, clear locks, or restart the service to start over. Necessary destructive cleanup must be confirmed by the user for the specific objects and impact; it must not affect other projects under the same service.
4. Merge existing Agent instructions
Merge only when the original file exists and the Harness entry point has not yet been added. Use the current template render to read the repository template, such as template://repository/agent-base@1、agent-overlay@1、claude-entry@1, and take the returned body and required anchors as authoritative; do not copy someone else's AGENTS file.
Preserve the original text and project-specific rules; first prepare the complete merge result and diff, then have the user approve this specific modification. Preserve the explicitly required anchors and do not overwrite user content with the template. If the same diff has already been approved, do not confirm again.
5. Verify readability and initialize the knowledge location
ha --root "<目标仓库绝对路径>" --json daemon status
ha --root "<目标仓库绝对路径>" --json task list
Inspect the real status and errors of the target workspace; do not judge the service as broken just because the text summary is too short. An empty task set is a normal result for a new workspace.
In some CLI receipts, evidence is a JSON-encoded string. Parse it according to the actual type and do not directly assume the fields are at the top level; for example, when reading tasks, first parse the outer layer, then parse evidence. Errors and business data must be judged separately.
Then read the harness-ceo 'sknowledge initialization method, establish or reuse the landing points for user agreements, model matrix, runtime issues, feedback, and execution evidence. Create only necessary indexes, do not fill empty tables, and do not treat suggestions from public skills as user facts.
6. Have the main controller complete a real task
Reuse the first task given by the user, and complete the real work and the repository-required closure under the main controller method. This stage is the same task as the first task in the download guidance.
Genuine review independence
If the current completion contract requires independent review execution, the available review identity and responsible person should be clarified before implementation. Possible refusals are:
Execution Review requires an independent transport-bound arbiter.
HARNESS_ACTOR=agent:... is an identity declaration, not a method for creating an independent reviewer. The same executor cannot rename itself to approve its own work, nor can clearing variables impersonate the user's judgment. When another real executor, user judgment, or a host-supported independent review channel is needed, deliver reviewable materials and have that identity complete it. Having only one model does not mean having only one identity, but whether it is independent must conform to the current contract.
Creation, execution, and evidence collection
First read preset-trigger to select the current preset; the general task shape is as follows:
ha --root "<目标仓库绝对路径>" task create --title "<真实任务>" --vertical software/coding --preset standard-task
ha --root "<目标仓库绝对路径>" task start <任务标识>
Obtain the real task path from the receipt; do not manually assemble a derived slug. Execute according to the current lifecycle requirements, and read back existing executions before restarting. If the start receipt does not carry an execution identifier, query task show; some versions place it in evidence.lease.executionId, and it is necessary to first parse the evidence string, then read ["lease"]["executionId"]。
Do the actual work and obtain evidence. Delivery logs and reports belong to this execution; reviewable observations that will support subsequent judgments are recorded through the current fact entry point, and facts are not fabricated to pad the count. The repository-stipulated fact and relationship requirements remain in effect.
Record decisions when there are genuinely load-bearing choices
Read the current decision capability and input contract; the following shows a common structure, and the actual fields and legal values are subject to the version in use:
{
"title": "<决策标题>",
"question": "<要解决的问题>",
"riskTier": "low",
"urgency": "low",
"decisionClass": "ordinary",
"appliesTo": { "modules": [], "productLines": [] },
"chosen": [{ "id": "CH1", "text": "<选择>", "rationale": "<理由>" }],
"rejected": [{ "id": "RJ1", "text": "<真实替代>", "whyNot": "<未采用原因>" }],
"claims": [], "fulfillments": [], "relations": []
}
decisionClass commonly used ordinary or standing_policy; do not fabricate alternatives. Input files are placed in task artifact locations allowed by the workspace. When encountering fromFile must stay inside the workspace , correct the input landing point; do not treat a temporary directory as a valid source.
Record raw observations first, then according to the current ha relation contract associate the decision declaration with evidence, and choose to associate derived tasks. Do not copy the retired decision relate command. When the user needs to adjudicate, present the question, options, alternatives, and evidence and obtain approval, handled by a genuinely authorized identity; do not substitute for the user by changing environment variables. For questions that cannot be answered for the moment, onboarding acceptance, or consent requests, use ha relation relate --type awaits to attach the task or decision to that person's name (write the reason as <question|acceptance|consent|reopen>: <问的是什么>), and it will appear in the other party's ha agenda'Waiting for you to handle'.
Submission, independent review, consent, and completion
Write the closure materials truthfully, first doc status check the candidate, then register this task's documents through the supported doc sync --submit . Do not submit irrelevant candidates; the combination of path qualification and execution identity is subject to the current capability.
Example submission materials:
{
"completionClaim": "<已成立的结果>",
"deliverables": ["<真实产物>"],
"outputs": ["<收口记录>"],
"verificationNotes": ["<实际执行和结果>"],
"knownGaps": [],
"residualRisks": [],
"commitSha": "<实际源码提交>"
}
ha --root "<目标仓库绝对路径>" task submit <任务标识> --execution-id <执行标识> --from-file "<工作区内提交材料>"
Code documentation anchors are produced at the required stage through the current task code-doc reconcile , not by hand-writing machine files. The review is submitted by a genuinely independent reviewer, and its materials include:
{ "verdict": "approved", "reason": "<依据>", "evidenceChecked": ["<实际检查的证据>"] }
verdict use current legal values, such as approved、changes_requested、dismissed. The owner's consent binds to the actually recorded review and content version; do not treat the worker's report as consent. Complete using the current task review-consent and task complete contract; do not add outdated submission version parameters or fabricate a digest yourself.
--ci passed is a declaration and will not run CI for you. Without real evidence, you cannot claim on this basis that the check passed. When the selected task does not require CI, handle it according to the actual contract; when a required gate cannot be satisfied, deliver the specific gap and do not fake completion.
Finally, read back whether the task has really reached done, and check that the original goal has indeed been implemented. When independent review is still missing, accurately report "the environment and repository are ready, and the first task is awaiting review"; do not describe the entire bootstrap as verified.
7. Handoff
Deliver the absolute CLI entry point, the target workspace, the user knowledge index, the first task and its evidence, the real review identity, and the unfinished items. The option for putting the tool into PATH is handled uniformly by the download skill; this skill does not provide a second set of installation commands.
Explain the respective historical boundaries of the ledger and the project, and do not manually add git commitin the ledger. List the files still uncommitted in the project, and do not conceal these changes on the user's behalf. The next time, use harness-ceo; for another new project, use this skill directly.
Completion conditions
- The CLI and the same-version skill are available; the actual target workspace is readable and writable.
- The private ledger has not entered the public project; modifications to existing instructions have received specific approval.
- The user knowledge entry point can locate the model, issues, feedback, and evidence.
- A real task specified by the user has completed the evidence collection, submission, independent review, and consent required by the current contract, and the read-back status is
done。 - Uncommitted files, unverified parts, and commands used have been truthfully handed off; if any required stage is still blocked, report that stage and do not claim in advance that the entire process is complete.