From harness-loom
Use when `/harness-auto-setup` is invoked to bootstrap and configure a project-shaped harness, expand an existing harness without refreshing its foundation, or migrate an existing harness foundation with snapshot-first preservation.
How this skill is triggered — by the user, by Claude, or both
Slash command
/harness-loom:harness-auto-setup [--setup | --migration] [--provider claude,codex,gemini][--setup | --migration] [--provider claude,codex,gemini]The summary Claude sees in its skill listing — used to decide when to auto-load this skill
`harness-auto-setup` is the factory-side setup and migration workflow for a target harness. `--setup` bootstraps fresh targets or expands an existing harness without changing its foundation, then the assistant continues with project analysis, concise user dialogue when needed, and actual pair/finalizer authoring. `--migration` exists because rerunning `/harness-init` is intentionally simple and...
harness-auto-setup is the factory-side setup and migration workflow for a target harness. --setup bootstraps fresh targets or expands an existing harness without changing its foundation, then the assistant continues with project analysis, concise user dialogue when needed, and actual pair/finalizer authoring. --migration exists because rerunning /harness-init is intentionally simple and destructive: it reseeds the foundation, but it does not preserve project-specific pairs, finalizer work, or active cycle state.
This workflow does not introduce a second human-authored setup source of truth. The durable truth remains the target's live harness files:
.harness/loom/registry.md — pair roster, order, and reviewer topology.harness/loom/skills/<pair>/ — pair skill bodies.harness/loom/agents/<producer-or-reviewer>.md — pair agents.harness/loom/agents/harness-finalizer.md — singleton cycle-end roleSnapshots are machine provenance and convergence input, not restore sources. Old files may explain intent, but current output must be regenerated against the current templates, authoring rubric, and target repo evidence.
/harness-auto-setup [--setup | --migration] [--provider <list>]
The workflow always targets the current working directory. Run /harness-auto-setup from the project root. --setup is the default mode and covers fresh bootstrap plus project-shaped authoring for fresh or existing harnesses. --migration is for snapshot-first foundation refresh of an existing harness. --provider only shapes the printed sync command; sync itself is never run here.
/harness-init remains the foundation installer. Auto-setup may invoke it, but must not move pair/finalizer authoring into harness-init./harness-pair-dev remains the pair-authoring layer. Auto-setup may use existing pair files as evidence, but must author current pair outputs through the current templates, authoring rubric, and registry contract./harness-pair-dev --add ... --from <source> remains the pair-source resolver. Live registered pair slugs, snapshot:<ts>/<pair>, and archive:<ts>/<pair> are valid sources; arbitrary filesystem paths and provider-tree paths are not..harness/loom/registry.md remains the pair roster SSOT. The planner and finalizer are never registry entries.harness-finalizer remains a singleton cycle-end role. Reviewer-less cycle-end work belongs in .harness/loom/agents/harness-finalizer.md, not in ## Registered pairs.node .harness/loom/sync.ts --provider <list> remains an explicit user-run command after convergence. Auto-setup must not derive .claude/, .codex/, or .gemini/ automatically..harness/cycle/ only for fresh setup or migration-mode foundation refresh. Existing-target --setup must not reseed cycle state or fabricate pair task/review history.Before any destructive refresh on a target with existing harness runtime state (.harness/loom/ or .harness/cycle/), create a machine snapshot under:
.harness/_snapshots/auto-setup/<YYYYMMDDTHHMMSSZ>/
The snapshot preserves pre-refresh .harness/loom/ and .harness/cycle/ when present, plus deterministic manifest.json provenance. Read references/snapshot-provenance.md before changing snapshot id allocation, copied namespaces, manifest keys, active-cycle fields, or failure behavior.
Do not snapshot derived platform trees by default; they are deployment outputs and are refreshed only by explicit sync.
If snapshot creation fails, stop before running install or deleting anything. Existing-target --setup does not refresh the foundation and therefore does not create a snapshot.
Inspect .harness/cycle/ before refresh. Apply the classifications in the order below so the pristine scaffold is not treated as active only because its initial planner Next block is non-empty.
Classify the cycle as:
absent — no .harness/cycle/pristine — fresh scaffold with Goal (from <none yet>), Phase: planner, loop: false, no emitted EPICs, and the initial planner Nextactive — loop: true, a non-empty runnable Next outside the pristine scaffold, any live EPIC whose current is not done or superseded, or any ambiguous state that may still need runtime dispatchhalted — loop: false, no runnable Next, and every EPIC is terminal or no EPIC existsunknown — state cannot be parsed safelyFor active or unknown, silent deletion is forbidden. In --migration, the default policy is:
.harness/cycle/ in the snapshot.harness/cycle/ is reseeded freshThis policy forbids silent destruction, not destruction itself. Existing-target --setup reports the cycle classification but leaves cycle files untouched.
harness-auto-setup has two execution modes:
--setup — bootstrap a fresh target, or expand an existing harness with project-shaped pair/finalizer authoring. Existing-target --setup must not snapshot, reseed, restore, reconstruct, migrate, or otherwise refresh existing foundation files. It may add new pair files, register new pairs, and update the singleton finalizer after LLM project analysis and any necessary user clarification.--migration — upgrade an existing harness foundation with the smallest reasonable blast radius. This mode optimizes for snapshot-first contract refresh and customization preservation. It refreshes contract-owned surfaces, preserves compatible user-authored H2 sections, restores non-pair custom loom entries, and emits an explicit migration plan for pair/finalizer overlay review.Fresh targets may use only --setup. --migration requires existing .harness/loom/ or .harness/cycle/ state.
When .harness/loom/ exists, or .harness/cycle/ exists without .harness/loom/:
In --setup:
.harness/loom/registry.md, harness-finalizer.md, .harness/cycle/, and target repo signals..harness/cycle/, restore snapshot files, reconstruct pairs, migrate finalizer text, or edit provider trees.In --migration:
.harness/loom/ when present and .harness/cycle/ when present per the snapshot contract.loom/registry.md, parse it for registered pair order, producer slug, reviewer slug(s), and skill slug.harness-finalizer.md when present and decide whether it is missing, default no-op, or customized./harness-init or its installer implementation to reseed the foundation.loom/skills/* and loom/agents/*.md entries that are not foundation or registered-pair artifacts.skills:, and Output Format blocks.Old pair and finalizer files are evidence only. Do not blind-copy them over the refreshed foundation.
If .harness/cycle/ existed without .harness/loom/, there is no pair/finalizer source to converge:
--setup, leave the cycle untouched and recommend --migration for foundation repair or refresh--migration, snapshot the cycle, reseed the foundation, and report that no live loom source was available for pair/finalizer migrationWhen both .harness/loom/ and .harness/cycle/ are absent:
--setup targets it invokes the foundation installer and collects script-level repository signals.--setup, author the initial pair roster from that project analysis and user clarification. Docs/tests/CI presence alone is not enough to author a stock pair.--setup, update the singleton finalizer only when project analysis or user clarification identifies a concrete cycle-end duty; otherwise keep the safe no-op.--migration is invalid here because there is no existing harness state to preserve.Do not create evidence-free stock pairs just to fill the registry. If repo evidence is insufficient, ask focused questions before authoring; leave the roster empty only when the project is effectively blank or the user declines to choose a workflow boundary.
registry.md as a strong topology/order hint, not as immutable truth.manifest.json and the user summary.--setup, author concrete project-shaped pairs after analysis or user clarification. Do not stop after listing recommendations.--setup, do not rewrite or reconstruct registered pair files unless the user explicitly asks for an improvement pass. Registered pairs are current coverage; new setup work is additive.--migration, use /harness-pair-dev --add ... --from snapshot:<ts>/<pair> (or archive: when appropriate) as the source-resolution path for preserved pair intent. Do not pass arbitrary file paths through --from; record the resulting source/target overlay plan in convergence.migrationPlan.--migration, preserve compatible custom H2 sections instead of silently dropping renamed sections such as ## Approach or extra sections such as ## Rollout Plan.--setup, do not author harness-document, harness-verification, or generic implementation pairs solely from docs/tests/CI/code-directory presence.## Registered pairs order and use the registry helper rather than hand-editing the section.--setup, do not rewrite a customized harness-finalizer.md unless the user explicitly asks to change the cycle-end role.--setup, keep the safe no-op until cycle-end work is selected through project analysis or user clarification.--migration, preserve the customized finalizer's intro, principles, task, and compatible custom H2 sections where possible while refreshing contract-owned surfaces such as required skills, Output Format, and Structural Issue block. Use references/finalizer-overlay.md for singleton finalizer overlay rules.## Registered pairs.Auto-setup must stop before platform derivation. The final user-facing summary must include a target-local command such as:
node .harness/loom/sync.ts --provider claude,codex,gemini
Use any subset the user requested or that the workflow recommends, but never execute sync automatically.
Run the script-owned execution path:
node plugins/harness-loom/skills/harness-auto-setup/scripts/auto-setup.ts [--setup | --migration] [--provider claude,codex,gemini]
The script installs the foundation on fresh --setup targets. On existing --setup targets, it inspects the live harness and emits setup summary data without refreshing .harness/. Setup-mode JSON includes convergence.setupAuthoring so callers can tell that the script phase is not the end of the user-facing workflow. On --migration, it snapshots existing .harness/loom/ / .harness/cycle/, classifies active-cycle risk, calls the harness-init installer for foundation refresh, restores non-pair custom loom entries, and applies protected overlay for pairs/finalizer. The script is only the mechanical phase of setup: the assistant must continue with LLM project analysis, ask focused questions when needed, then author actual pair/finalizer files under .harness/loom/ before finishing. --provider only shapes the printed sync command; it never runs sync.
--setup leaves foundation and already-registered pair files untouched unless the user requests an improvement pass; additive pair/finalizer authoring is allowed..harness/cycle/ state is warned about and copied before discard/reseed./harness-init remains foundation-only.registry.md remains the sole pair roster source of truth and contains only executable producer-reviewer pairs.--setup targets do not receive docs/tests-driven stock pairs; authored pairs come from assistant-side LLM project analysis and cite project-specific evidence when available.loom/skills/* and loom/agents/*.md entries survive migration refreshes.node .harness/loom/sync.ts --provider <list> next action.setup.md or equivalent setup SSOT..harness/ foundation state in --setup; use --migration for that.--migration on a fresh target with no harness state to preserve./harness-init.sync.ts automatically or write .claude/, .codex/, or .gemini/ directly.../harness-init/SKILL.md — foundation installer boundary../harness-pair-dev/SKILL.md — pair authoring and registry mutation boundaryreferences/snapshot-provenance.md — snapshot directory, manifest shape, and failure contractreferences/finalizer-overlay.md — singleton finalizer migration overlay rules../harness-init/references/runtime/registry.md — target-side pair roster contract../harness-init/references/runtime/harness-finalizer.template.md — singleton finalizer skeleton and Output Formatnpx claudepluginhub kinggyusuh/harness-loom --plugin harness-loomGuides creation, editing, and verification of skills for AI coding agents using test-driven development with subagent scenarios. Use when authoring or debugging skills.