Using Harness

Using Harness

Purpose

Use this skill as the lightweight router for Harness. Keep it in memory only long enough to decide which specific Harness skill, reference, or script is needed.

This skill does not create Feature, ADR, Lesson, Evidence, Backlog, or handoff artifacts. It routes to the smallest next action.

Naming Boundary

The formal system name is Harness. Use the full name when introducing the system, writing durable project memory, or distinguishing it from a project's own test harness, runtime harness, evaluation harness, or business feature named "harness".

Do not use Harness as the skill-suite short name. Treat lowercase harness as a generic engineering word unless the current context explicitly defines it as Harness history.

The installed skill slugs are using-harness plus short semantic workflow slugs such as harness-start-gate, harness-readiness-dashboard, and harness-knowledge-capture. Pre-rename public skill slugs were removed by the breaking rename. Do not create harness-*, ai-coding-harness-*, or suite-prefixed workflow skills unless a future ADR explicitly accepts another migration path.

When the user or repository mentions "harness" ambiguously, distinguish project-internal harness code from Harness gates before acting.

Activation Contract

After this skill is loaded:

1. Resolve whether Harness is triggered before implementation, commit writing, PR writing, handoff, or completion language.
2. For non-trivial work, run harness-start-gate before implementation.
3. For completion/readiness claims, route to harness-knowledge-capture.
4. For commit, PR, release, handoff, progress, or rejected-path narrative, route to harness-change-narrative.
5. When real cases, validation, or user feedback contradict an existing spec, run harness-spec-drift before changing code.
6. If no Harness action is needed, say Harness: not triggered with a short reason and continue.

Entry And Exit Gates

For non-trivial work, Harness is a two-gate protocol:

• Entry Gate: run harness-start-gate before implementation and satisfy any required retrieval, Vision Anchor, Feature, spec, plan, ADR, or delegation decision before coding.
• Exit Gate: run harness-knowledge-capture before saying the work is complete, fixed, verified, ready for PR, ready for review, ready for handoff, safely closed, or mergeable.
• A spec, plan, ADR, Feature page, or Evidence document created during the work is an input to Exit Gate, not a substitute for it.
• If Exit Gate has not produced Evidence level, check status, closeout verdict, and completion-claim permission, describe the state as implementation done, Harness closeout pending.

Goal-Driven Feature Flow

Goal is the user authorization boundary. When the user has stated a clear Goal with problem, pain point, desired capability, non-goals, acceptance source, and the scope in which the agent may decompose work, the agent may continue through multiple in-scope Features without asking for per-Feature design approval.

Feature pages are engineering memory, not approval gates. For non-trivial work inside an approved Goal, create or update the Feature page before implementation so later agents can recover the capability boundary, acceptance source, Evidence, Patch History, and Recovery Snapshot. Do not require default per-Feature design approval.

Ask the user only when the Goal is missing or ambiguous, a proposed Feature exceeds the approved Goal, acceptance criteria conflict, high-risk architecture/data/security/cost/external-contract choices are needed, or patch churn suggests the direction may be wrong. Otherwise, route to the next implementation or harness-knowledge-capture action.

Empty Approval Guard

Do not ask the user to approve a Feature, design, or plan that has not been created or shown. If the artifact is missing, the next action belongs to the agent: create the Feature memory, present the necessary summary only when the user must decide, or ask a targeted clarification question. Never invent an Fxxx id or unblock phrase as a substitute for an existing artifact.

Core Rule

If future sessions, agents, reviewers, or teammates may need to recover what happened, why it happened, what was verified, or what should not be repeated, check the Harness flow before closing the task.

Harness is not a documentation tax. The required behavior is checking whether shared project memory is needed; the correct result may be no formal artifact needed.

Harness Presence Check

Trigger Harness when any of these apply:

• The user mentions Harness, harness, gates, Start Gate, Evidence, ADR, Lesson, Feature, Backlog, handoff, recovery, project memory, patch churn, or process drift.
• The task is non-trivial: multi-file change, behavior change, refactor, cross-module bugfix, review, merge, release, handoff, or a decision future agents may question.
• The repository has Harness memory or tooling such as docs/features, docs/decisions, docs/lessons, docs/evidence, docs/BACKLOG.md, or vendored Harness scripts/templates.
• The repository has Markdown with Harness doc_kind frontmatter, even if it is under legacy paths such as docs/superpowers.
• The user reports a bug, regression, validation failure, or broken accepted behavior that may belong to an existing Feature or prior fix chain.
• A stale spec, outdated spec, acceptance criteria drift, SDD drift, spec vs reality conflict, or implementation follows spec but still wrong signal appears.

Tiny local edits may skip retrieval and formal artifacts when project memory cannot change the outcome.

Routing Order

Prefer the most specific skill that can answer the current transition:

1. harness-start-gate before non-trivial implementation.
2. harness-knowledge-retrieval when prior Feature, ADR, Lesson, spec, plan, Evidence, or bug attribution may change the fix.
3. harness-spec-drift when real cases, validation, or user feedback contradict an existing spec, stale spec, acceptance criteria drift, or implementation follows spec but still wrong signal.
4. harness-doc-lifecycle for stale, archived, superseded, deprecated, invalidated, or replaced documents.
5. harness-incident-learning after a fixed or stabilized bug, incident, recurring failure, or patch chain needs prevention analysis.
6. harness-delegation-gate before work that may need subagents or independent review.
7. harness-vision-gate when intent, scope, product direction, or acceptance may drift.
8. harness-readiness-dashboard for review, release, handoff, progress assessment, maturity assessment, distance to target, roadmap gap, blocker, or readiness rollups.
9. harness-change-narrative for commit messages, PR descriptions, release notes, handoff notes, progress summaries, root cause, rejected paths, and history-aware change explanations.
10. harness-knowledge-capture for Evidence, closeout, durable memory, completion verdict, and completion-claim permission.
11. harness-project-rules before promoting a decision, Lesson, or repeated constraint into AGENTS.md or another project-level rule file.

If the user describes a long-running or unattended task, route to Delegation Gate early so the main agent explicitly chooses single_agent, delegate, or blocked before progress depends on that choice.

For non-trivial or high-risk implementation work, Start Gate must produce an explicit Delegation Gate decision before implementation may begin.

For a non-tiny bug, regression, validation failure, or broken accepted behavior, retrieval should establish Feature attribution before code search or edits.

When no direct Feature ref is present, retrieval should use docs/features/INDEX.md as the coarse recall entry if it exists, then open only the 1-3 most plausible Feature candidates. If the index is absent, fall back to Feature filenames. Do not read every Feature merely because memory exists.

Feature Index governance is local by default. When the current work creates, renames, archives, deprecates, supersedes, splits, merges, or materially changes the boundary of a Feature, or when a bugfix shows that the related Feature was not recalled, validate only the current Feature entry:

python /using-harness/scripts/knowledge_check.py --root  --docs-path docs --feature-index 

Do not run a global Feature Index audit by default, including during ordinary --strict closeout. Run --feature-index-all only when the user explicitly asks for a full Feature Index audit or all-links/duplicates check.

Harness knowledge artifacts must use canonical directories under the selected docs root:

• Feature: docs/features/Fxxx-slug.md
• ADR: docs/decisions/ADR-xxx-slug.md
• Lesson: docs/lessons/LL-xxx-slug.md
• Evidence: docs/evidence/EV-xxx-slug.md

Legacy Superpowers documents under docs/superpowers/** may remain as linked specs or plans, but do not create Harness Feature, ADR, Lesson, or Evidence artifacts there.

Superpowers specs and plans are linked material, not Harness artifacts. When Superpowers writes docs/superpowers/specs/... or docs/superpowers/plans/..., create or update the owning Harness Feature separately under docs/features/Fxxx-slug.md and link the spec or plan from that Feature when the work needs durable recovery.

Closeout Convergence Protocol

This entrypoint routes transitions; it must not become a recursive closeout loop.

• Do not re-enter using-harness for the same task transition after it has already routed to a more specific Harness skill.
• harness-knowledge-capture owns the final completion verdict. When it returns pass, or an explicitly permitted conditional verdict for the requested stage, the closeout is terminal.
• Reuse fresh verification, knowledge-check, readiness, and narrative evidence already gathered in this turn instead of restarting equivalent Harness gates.
• Do not route a normal final response to harness-change-narrative. Use change narrative for commit messages, PR descriptions, handoff notes, release notes, progress summaries, rejected-path explanations, and history-aware engineering narratives.
• If a specific Harness skill reports blocked or conditional status, preserve that status directly instead of re-routing through this entrypoint to look for a different answer.

Reference Map

Use references only when their trigger applies.

• references/routing.md: read when routing is ambiguous, multiple Harness skills appear to apply, or trigger wording needs detail.
• references/task-routing-fixtures.md: read when a common workflow route is unclear or a regression test needs expected Harness behavior.
• assets/templates/: copy templates when creating Feature, ADR, Lesson, Evidence, or AGENTS artifacts.
• assets/templates/CLOSEOUT_COMPACT.md: use when a concise visible closeout block is needed.

Script Use

Execute bundled scripts; do not read script source unless debugging or editing that script.

• scripts/knowledge_check.py: execute to validate Harness Markdown artifacts.
• scripts/harness_closeout_check.py: execute to validate a closeout block.
• scripts/skill_metadata_check.py: execute to validate skill metadata and bundled resources.
• scripts/hook_diagnostics.py: execute after optional hook installation or suspected hook drift to check local Stop runner smoke.
• scripts/usage_record.py: execute to append a doc-used event after an Harness document materially affects a decision or change narrative.

For this repository, prefer scripts/install.ps1 codex or scripts/install.sh codex to sync Harness skills into the local Codex skills directory instead of hand-copying individual files.

Run knowledge_check.py in --strict mode for review, closeout, or CI. The validator checks every Markdown file with doc_kind frontmatter and rejects Harness artifacts outside their canonical directory.

--strict does not run the global Feature Index audit. Use --feature-index for current-Feature recall-entry governance, and reserve --feature-index-all for explicit user-requested global audits.

Optional Hook Runtime

Skills-only install remains valid. Hooks are an optional runtime enhancement, not a prerequisite for using Harness.

Hook resources live under this Skill so the Skill owns scripts and hook entrypoints:

• hooks/Harness_hook.py: normalized hook runner. Default examples use only stop; post-tool-use remains available for explicit experiments.
• hooks/codex-hooks.example.json: Codex hook configuration example.
• hooks/claude-settings.example.json: Claude Code hook configuration example.
• hooks/opencode-plugin.example.ts: OpenCode plugin example.

Default examples install only stop. Hook installation or runtime failure must fail open unless the hook clearly proves an Harness rule failed at a completion boundary. A broken hook config must not roll back Skills, block Skill loading, or replace normal Skill-triggered gates. The default hook slice only automates:

• Checking completion claims with harness_closeout_check.py before the agent stops. This is the default hard boundary for incomplete closeout blocks.

Harness no longer provides default pre-compact / session-start recovery hooks. Platform compaction remains the platform's responsibility. Use explicit handoff notes only when the user asks for handoff or an unfinished task is intentionally paused.

Do not run knowledge_check.py from PostToolUse by default. Tool-call granularity is too fine for multi-edit Harness artifacts and can slow the agent down. Run knowledge_check.py --strict at Stop/readiness/closeout/CI boundaries instead. The post-tool-use runner mode is experimental and should only be wired manually when immediate feedback is explicitly worth the cost.

Do not move Start Gate, Vision Gate, ADR, Lesson, or Feature ownership judgment into deterministic hook code.

After installing or changing Codex hooks, verify actual runner evidence instead of relying only on UI visibility or cached files:

python /using-harness/scripts/hook_diagnostics.py codex --project-root 

Codex plugin-bundled hooks should keep both root-level hooks.json and hooks/hooks.json available with identical content. The user config must enable both [features].hooks = true and [features].plugin_hooks = true; UI visibility and trusted hashes do not prove runtime dispatch. Route commands through hooks/run-Harness-hook.cmd instead of calling python ./skills/... directly. On Windows, commandWindows must be safe when Codex invokes it through PowerShell: wrap the %PLUGIN_ROOT% command in cmd /d /s /c so %PLUGIN_ROOT% expands in cmd.exe and the .cmd wrapper is actually executed. Runtime proof comes from .harness/hook-events/events.jsonl or the expected Stop check output.

Verification Use

Run verification commands before reading verification source.

Do not read test files, validator scripts, or workflow files merely to verify behavior. Read them only when debugging a failure, editing them, reviewing them, or explaining their behavior.

Non-Goals

• Do not load every Harness skill preemptively.
• Do not read bundled scripts just to learn how to run them.
• Do not create documents for every small change.
• Do not edit AGENTS.md just because Harness memory exists; route through harness-project-rules.

Red Flags

| Thought | Reality | | --- | --- | | "This is done; I can just say completed." | Completion needs Evidence status and a closeout verdict. | | "I wrote a spec, so Harness is done." | A spec anchors intent; Exit Gate still needs Evidence, check status, and completion permission. | | "The next agent can infer intent from the diff." | Diffs show what changed, not why alternatives were rejected. | | "No formal artifact is needed, so no Harness skill is needed." | Harness may conclude no artifact is needed; the check is still the gate. | | "This Superpowers plan is the Feature." | Plans can be

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: solitudeTG
• Source: solitudeTG/harness-coding-skills
• License: MIT

Install and usage instructions live in the source repository linked above.