neo-harness-project

Project Harness Builder

Establish an engineering environment that is readable, verifiable, and recoverable based on the current state of the project. Do not apply a fixed technology stack or an ideal architecture, and do not create empty shells without real checking capability.

Boundaries

This skill inventories and builds the Harness for the entire project.
When the requirement only involves AGENTS.md , use instead neo-harness。
The Harness assets of the target project must be centralized in the root directory .neo_harness/; the only exception is the AGENTS.md。
The skill package's own references/、assets/ and evals/ are skill implementation resources and do not belong to the Harness output locations of the target project.
Do not add third-party dependencies, services, deployments, or external connections that the user did not request.
Skill content and outputs must remain vendor-neutral and must not mention any specific model vendor, product, package family, official website, or vendor-specific metadata.
If necessary project facts cannot be accurately recorded while complying with the neutrality requirement, stop the related output and report the conflict; do not omit or rewrite facts to circumvent the conflict.

Harness Asset Location Specification

The following paths are all relative to the target project root directory:

Asset	Official Path
Project entry point and working rules	`AGENTS.md`
Architecture documents	`.neo_harness/ARCHITECTURE.md`
Plan specification	`.neo_harness/PLANS.md`
Project command list	`.neo_harness/docs/scripts.md`
In-progress execution plans	`.neo_harness/docs/exec-plans/active/`
Completed execution plans	`.neo_harness/docs/exec-plans/completed/`

Do not create .neo_harness/AGENTS.md; the root directory AGENTS.md is the only Agent entry point.
All other Harness core or conditional assets must be placed in .neo_harness/ and linked from the root directory AGENTS.md or related documents.
.neo_harness/ is a formal project asset that should be included in version control; if it is excluded by .gitignore or other ignore rules, first mark it as blocked, and do not modify the ignore rules yourself.
Do not move non-Harness documents, existing project documents, or the skill package's own resources into .neo_harness/。

Migration of Existing Legacy Paths

If the inventory finds that the following legacy paths exist, a migration preview must first be provided and explicit user confirmation of the exact list must be obtained:

Legacy Path	Official Path
`ARCHITECTURE.md`	`.neo_harness/ARCHITECTURE.md`
`PLANS.md`	`.neo_harness/PLANS.md`
`docs/scripts.md`	`.neo_harness/docs/scripts.md`
`docs/exec-plans/`	`.neo_harness/docs/exec-plans/`

The migration preview must list the source, destination, affected links or indexes, verification commands, and recovery method.
When the destination already exists, the source and destination contents conflict, or the destination is excluded by ignore rules, mark the action as blocked; do not overwrite, delete, create duplicate copies, or create symbolic links.
Do not migrate, batch rename, or delete legacy paths without confirmation; only after confirmation may affected Harness links be updated, and a basis for recovery from version control or a reported snapshot must be retained.
Legacy documents not belonging to the above list are not migrated automatically unless the user separately confirms.

Required Workflow

1. Inventory, without writing

First read the project specifications, version control status, root directory, package and build configuration, tests, CI, documentation, main entry points, and existing Harness assets, including .neo_harness/ the existing files at the official path and the aforementioned legacy paths. Commands must come from verifiable configuration or documentation and must not be guessed based on the technology stack.

During inventory, you must read the project assessment model, and determine maturity and gaps based on source evidence. Mark unknown information as "unknown" and do not fill it in as an ideal state.

2. Select outputs

Read the asset selection matrixand classify candidate paths as:

create: the path does not exist and there is sufficient evidence to create it.
update: retain valid content and fill the gaps.
rebuild: the existing content conflicts with confirmed goals and needs to be rebuilt.
migrate: a legacy Harness path exists and needs to be moved to .neo_harness/ based on the confirmation result, with affected links updated.
skip: there is no requirement or evidence, so do not create it.
blocked: key facts are missing or neutrality requirements are violated.

By default, include core knowledge, the command list, and plan assets; include CI, architecture checks, execution environment, observability, and continuous cleanup only when the matrix conditions are met.

3. Provide a write preview

Before writing, provide:

Project evidence and maturity.
The exact target path and the create、update、rebuild、migrate、skip or blocked action.
The factual basis and content summary for each action.
Conflicts with existing files, verification commands, and failure recovery methods.

Obtain the user's explicit confirmation for all paths or specified paths. The user's initial request to "create a Harness" does not mean they have confirmed an unknown list of rebuilds or migrations; do not write before providing a preview.

4. Generate according to the confirmation result

Before writing, read generation, verification, and recovery, use the core template as the structural starting point; rewrite according to project facts and remove all template markers, and do not directly copy an unfinished template.

Use the current project's naming, tools, and documentation language; when this cannot be determined, use the user's language.
Modify only the confirmed paths listed in the preview; during migration, the source, destination, and link updates must all be listed in the confirmation list.
rebuild must retain project facts that are still correct and be recoverable from version control or a reported temporary snapshot.
migrate may only be executed after confirmation; first complete the verification of content and links, then remove the source path, and do not overwrite an existing destination.
Keep an empty execution plan directory with a minimal tracking file, and do not fill it with fictional plans.
The filename of a newly created execution plan must use YYYYMMDDHHmmss_<原計畫檔名>.md; the timestamp takes the local time of the execution environment at creation, and when moving from active to completed , retain the original timestamp. When migrating an existing plan to .neo_harness/ , retain the original filename and timestamp.
Do not batch-rename existing plans that lack timestamps; when updating an existing plan, use the original filename.
.neo_harness/docs/scripts.md must contain only a Markdown table with the two columns 指令、用途 , including all commands verifiable from the project configuration or documentation; when there are no verifiable commands, keep only the empty header.
When there is no verifiable unified verification command, remove the unified verification command and the corresponding completion conditions from AGENTS.md , and do not retain template markers.
When a rule can be reliably judged by a machine, preferentially use existing tools to create an executable check; otherwise, explicitly record it as a documentation rule.

5. Closed-loop verification

Confirm that the files created, updated, rebuilt, or relocated are all in the confirmation checklist.
If there has been a relocation, confirm that the source has been handled according to the approved plan, the destination content is complete, and all affected links point to .neo_harness/。
Check document links, commands, paths, architecture descriptions, and template markers.
Verify the timestamp format of the new plan filename, as well as .neo_harness/docs/scripts.md two-column Markdown table format.
Run the project's original quick checks and the newly added unified verification entry point.
On failure, read the full error, fix the root cause, and rerun.
Report outputs, unresolved gaps, commands, and results; do not declare completion without passing evidence.

Completion conditions

A new work session can find the knowledge, constraints, and verification methods required for the core assets based only on the current project.
.neo_harness/docs/scripts.md List complete and traceable project commands.
Newly created plan files can be sorted by timestamp prefix, and the prefix is retained when moving through the lifecycle.
Root directory AGENTS.md is the only entry point, and the remaining Harness assets are all located in .neo_harness/ with consistent links.
All commands can be traced back to the project configuration and are executable.
There are no false-success commands, unfinished templates, fabricated architecture, or unconfirmed rebuilds.
There is no unconfirmed relocation, batch rename, overwrite, or deletion; relocation conflicts are explicitly marked as blocked。
Conditional assets all have project evidence, and unused items all have clear reasons.
Outputs remain vendor-neutral and deliver verification results and remaining gaps.