harness-mode

Files (1)

• SKILL.md

SKILL.md (first lines)

> [← Skills index](../../README.md)

# /dev-kit:harness-mode — session-scoped local-hook mode

## What it does

Writes `.dev-kit/harness-mode.session.json` via `lib/harness_mode_state.py`,
which every gated skill and local hook (for example
`hooks/slop-detector.sh` and `lib/execute.py`'s intent-integrity gate) reads
on each invocation. Four **correctness local hooks** — `stop_verify`,
`secret_scan`, `intent_integrity` (high), `gh_ci_required` — are hardcoded
in `lib/harness_mode_state.resolved_gate()` to always resolve `"on"`; no
mode, and no hand-edited state file, can turn them off.

**Session-scoped, not project-level.** A SessionStart hook
(`hooks/session-start-harness-mode-reset.sh`) resets the state file to
`{"mode": "full"}` at the start of every session. A new window always starts
strict — `fast` or `custom` must be chosen explicitly every session.

**This skill controls *local hooks only*.** The GH-Actions workflow gates
(review / security / maintenance / severity gate / lint / test / validate /
merge-queue-ready-check / ...) are out of scope — see
[CI workflow gates (not affected by harness-mode)](#ci-workflow-gates-not-affected-by-harness-mode)
below.

## Sub-commands

```bash
/dev-kit:harness-mode fast     # instant: every optional local hook OFF, correctness local hooks stay ON
/dev-kit:harness-mode full     # instant: everything ON (this is also the SessionStart default)
/dev-kit:harness-mode custom   # interactive: pick each optional local hook individually
/dev-kit:harness-mode show     # print the resolved local-hook table for this session, no prompts
```

### `fast` / `full`

Run directly, no confirmation needed:

```bash
python3 -m lib.harness_mode_state write fast
python3 -m lib.harness_mode_state write full
```

Then print the resolved table (`python3 -m lib.harness_mode_state show`) so the
user sees exactly what changed.

### `custom`

Issue exactly two `AskUserQuestion` calls, with at most 3 questions per call.
**Call 1 must complete before Call 2 is issued** — keep the screens legible.

Each row's `Question` cell now explicitly names the local hook (so the user
knows they are toggling a *local* switch, not a CI workflow gate) and the
`Options` cell names the trade-off (e.g. "skipping defers to CI" for the
gates CI re-checks anyway).

**Call 1:**

| Question | Options |
|---|---|
| Run the **slop-detector** local hook on each write? | Keep it ON (Recommended) / Skip locally (CI slop-detector + review gate re-runs) |
| Run the **pre-commit codex:review** local hook before each commit? | Keep it ON (Recommended) / Skip locally (no CI equivalent) |

**Call 2:**

| Question | Options |
|---|---|
| Run the **maintenance** local hook (CC/OE/VM) before each commit? | Keep it ON (Recommended) / Skip locally (CI `/dev-kit:maintenance` always re-runs) |
| **security_owasp** local hook depth this session? | Full 10-dim OWASP fan-out (Recommended) / Quick single-dim summary / Skip locally |
| **babysit_pr** local hook behavior? | Full auto-fix polling loop (Recommended) / Manual: one `gh pr checks` dump + exit |

Map each answer to a gate key and write them all in one call:

```bash
python3 -m lib.harness_mode_state write custom --gates '{
  "slop_detector": "on",
  "pre_commit_review": "off",
  "maintenance": "on",
  "security_owasp": "quick",
  "babysit_pr": "manual"
}'
```

Correctness gates must never appear as `AskUserQuestion` options and must
never be written into `--gates` — `lib/harness_mode_state.write_state()`
silently drops any correctness-gate key passed to it as defense in depth, but
the picker itself should not offer them at all.

**Non-interactive fallback**: if `AskUserQuestion` is unavailable (e.g. a
headless/CI invocation), print the same 5 questions as a markdown table and
tell the caller to run `fast` or `full` instead of hanging on interactive
input.

### `show`

```bash
python3 -m lib.harness_mode_state show
```

Prints the current `mode` plus the resolved value of every local hook grouped
by category (correctness / quality / style / process), with a one-line
`description` per hook so readers know what each one does. Example:

```json
{
  "mode": "full",
  "local_hooks": {
    "correctness": {
      "stop_verify":     {"value": "on",   "type": "local_hook", "description": "L3 evidence: refuse 'done' without quoted exit code + test count + log"},
      "secret_scan":     {"value": "on",   "type": "local_hook", "description": "credential-leak detection on every Write/Edit"},
      "intent_integrity":{"value": "on",   "type": "local_hook", "description": "plan-vs-execution drift detection"},
      "gh_ci_required":  {"value": "on",   "type": "local_hook", "description": "refuse edits that would break GH-Actions"}
    },
    "quality": {
      "security_owasp":  {"value": "full", "type": "local_hook", "description": "local security scan depth (full 10-dim / quick / off)"}
    },
    "style": {
      "slop_detector":   {"value": "on",   "type": "local_hook", "description": "TODO/stub/placeholder markers on every Write/Edit"},
      "maintenance":     {"value": "on",   "type": "local_hook", "description": "code-sanity (CC/OE/VM) gate, locally"}
    },

From sh-ai-x/dev-harness-kit, MIT.

More from sh-ai-x/dev-harness-kit