Harness Init

📖 New to harness? Read README.md (日本語: README.ja.md) for concepts, terminology (Tier-A / rubric / Principal Skinner / foundation-sprint / ...), and the three-skill overview before diving into implementation details.

harness-init — Install the Harness Control Loop

Sets up a user project so the /harness series (harness-plan, harness-loop, harness-rules-update) can drive autonomous sprint development. This skill runs once per project; re-running reconciles existing configuration.

Required Reading — Open BEFORE doing the step

Claude Code tends to skim SKILL.md. For each step below you MUST open and read the listed reference file(s) before acting.

Language Rules

Resolve narrative language: explicit override (in English, 日本語で) > project mandate in CLAUDE.md / AGENTS.md > current user prompt > fallback skill source language (English).

Never infer from machine text (git log, progress.md, JSON keys, state enums, file paths, commands). Keep such tokens unchanged. AskUserQuestion body uses resolved language; option labels/descriptions stay bilingual (English / 日本語).

Reference files exist as <name>.md (English) and <name>.ja.md (Japanese). Pick the pair matching the resolved language for narrative guidance; schemas (templates, JSON) are language-agnostic.

Prerequisites

Before any generation step, check:

1. Git repo — git rev-parse --is-inside-work-tree must succeed.

2. jq available — command -v jq. All hooks require it (Claude Code hooks receive their input as JSON on stdin; scripts parse fields via jq).

3. Not already initialised — if .harness/_config.yml exists, switch to reconfigure mode (see Step 0).

4. Shared foundation — check for docs/coding-rules.md, docs/review_rules.md, and docs/issue-to-pr-workflow.md. These are the shared substrate between /spec and /harness skill series. They are generated by /spec-rules-init and /spec-workflow-init. If any are missing, surface a warning but do not block:

   AskUserQuestion:
     question: "Shared rules files are missing under docs/. Proceed anyway?" /
               "docs/ の共有ルールファイルが不在です。続行しますか？"
     options:
       - "Run /spec-rules-init first (Recommended)" /
         "先に /spec-rules-init を実行（推奨）"
         → stop harness-init with guidance
       - "Proceed without them (reduced rubric coverage)" /
         "無しで続行（rubric カバレッジ低下）"
         → continue; Evaluator will score Craft axis conditionally
   

   The Craft rubric axis treats coding-rules.md as "adhered to if present, unscored otherwise", so harness can function without it but quality gates are weaker.

If checks 1–3 fail, stop with a clear error. Do not partially generate.

Execution Flow

Step 0: Detect Existing Installation

if .harness/_config.yml exists:
  AskUserQuestion:
    question: "Existing harness install detected. What to do?" / "既存のハーネス設定を検出しました。"
    options:
      - "Reconfigure (merge)" / "再設定（マージ）"
      - "Re-init from scratch (backup old)" / "一から再初期化（旧設定はバックアップ）"
      - "Cancel" / "キャンセル"
else:
  proceed to Step 1

When presenting the Reconfigure (merge) option, its description MUST warn the user with bilingual content like:

⚠️ Generated artifacts under .claude/agents/, .codex/agents/, .harness/templates/, .harness/scripts/, .codex/hooks/ will be re-rendered from the latest templates — any hand-edits to these files will be overwritten.

Preserved: _config.yml keys not asked in this hearing (e.g. user-set codex_cli_binary), runtime state (_state.json / progress.md / metrics.jsonl), and .claude/settings.json (non-clobber merge).

To keep hand-edits: commit them to git first (recover with git checkout), or choose Re-init from scratch to back up the entire .harness/ tree.

⚠️ 上記パス配下の生成物は最新 template から再 render され、手 edit は 失われます。残したい場合は事前 git commit を推奨。

See Mode Behavior Matrix for the full per-step contract.

On "Re-init from scratch", rename existing .harness/ to .harness.backup-<ISO8601>/ before proceeding.

Mode Behavior Matrix

The mode chosen at Step 0 determines what each subsequent step does. This table is the canonical contract — Steps 1–10 below describe the unified action; this matrix says how the action specializes per mode.

Rule of thumb:

• Generated artifacts (Steps 3–7): templates are source of truth → both modes (re-)render; hand-edits are overwritten without prompting (commit to git first to preserve).
• Runtime state (Step 10): the only step where modes are inverted (fresh writes new state / merge must never touch — would corrupt an in-progress sprint).
• Config (Step 2): the only step needing a true merge strategy — hearing-asked keys updated, all other keys (incl. user customizations like codex_cli_binary) preserved.

Step 1: Environment Hearing

Six AskUserQuestion rounds collect the full _config.yml. Exact question text is in references/hearing-questions.md (or .ja.md). The axis being collected on each round:

Defaults are chosen to be safe: strict hook level is recommended for any generator_backend other than claude, but the user decides.

Round 2 backend choices are limited to the supported enum (claude / codex_cli / codex_cmux); the legacy other value has been removed. Adding a new backend requires a coordinated PR that updates this hearing AND harness-plan/references/roadmap-guide.md Backend Recommendation rubric AND harness-loop/references/generator-dispatch.md invocation switch — keep them in sync.

Before presenting Round 2 options, detect Codex availability (see Step 6 below). If codex CLI is not installed, remove codex_cli and codex_cmux options and advise the user to install it first.

Step 2: Write _config.yml

Atomic write to .harness/_config.yml:

schema_version: 1
project_type: <from hearing>
generator_backend: <from hearing>                   # claude | codex_cli | codex_cmux (epic default)
sprint_level_generator_override: true               # default: enable Planner roadmap-phase AskUserQuestion + 4-layer resolution at runtime. Set to false to bypass everything and always use generator_backend (legacy compat path)
evaluator_tools: [<from Phase 3 tooling hearing>]
hook_level: <strict|warn|minimal>
tracker: <github|gitlab|none>
max_iterations: 8
max_wall_time_sec: 28800
max_cost_usd: 20.0
rubric_stagnation_n: 3
allowed_mcp_servers: [<from hearing>]
negotiation_max_rounds: 3

# Mid-impl replan (Step 6' in harness-loop — dispatches Planner when a frozen
# contract proves infeasible without resetting the iteration counter).
mid_impl_replan:
  enabled: true
  min_consecutive_signals: 2
  max_per_sprint: 2
  axis_band_threshold: 0.05

# Codex-specific settings (populated in Step 6 when generator_backend ∈ codex_*)
codex_cli_binary: /opt/homebrew/bin/codex
codex_cli_sandbox: danger-full-access
codex_generator_model: "gpt-5.4" # passed via --model on every Codex invocation
codex_cmux_idle_dwell_polls: 2   # completion signal: required consecutive idle polls
codex_cmux_idle_poll_seconds: 20 # seconds between idle polls for codex_cmux

Step 3: Copy Templates

Copy from references/templates/ to .harness/templates/:

• product-spec.md (EN) or product-spec.ja.md (JA) → .harness/templates/product-spec.md
• sprint-contract.md / .ja.md → .harness/templates/sprint-contract.md
• shared_state.md / .ja.md → .harness/templates/shared_state.md
• foundation-sprint-checklist.md → .harness/templates/foundation-sprint-checklist.md (language-agnostic; used by /harness-plan when foundation-readiness detects greenfield — see ../harness-plan/references/foundation-sprint-guide.md)

Only the language matching detected input is copied for the bilingual files; the other remains in the skill package for reference.

Step 4: Generate Agent Definitions

Render three agent files to .claude/agents/ using _config.yml values:

• planner.md — orchestrates, writes product-spec/roadmap/contract, rules on negotiation stalemates
• generator.md — receives contract, implements, negotiates. Backend is switched per generator_backend (inline Claude, Codex CLI, or Codex via cmux)
• evaluator.md — runs acceptance scenarios (Playwright MCP / Playwright CLI / curl / custom-script), scores rubric axes, produces evidence

Pick the language variant matching detected input: <role>.md (EN) or <role>.ja.md (JA) from references/agent-templates/.

If generator_backend ∈ {codex_cli, codex_cmux} OR the project already has a .codex/ directory (indicating Codex CLI is configured), also render Codex TOML role configs (plain ConfigToml layers with top-level name + description + model + developer_instructions):

• .codex/agents/planner.toml — from references/agent-templates/planner{.ja}.toml
• .codex/agents/evaluator.toml — from references/agent-templates/evaluator{.ja}.toml
• .codex/agents/generator.toml — from references/agent-templates/generator{.ja}.toml

.ja.toml carries Japanese developer_instructions and is used when the detected input language is Japanese, keeping Codex's role overlay in the same language as Claude's sub-agent definition.

Each TOML's developer_instructions field carries the full role contract (Boot Sequence, Pre-flight Gates, output protocol incl. the mandatory feedback/<role>-<iter>-report.json, and prohibitions — matching the Claude sub-agent definition in .claude/agents/<role>.md). Activation happens via the Orchestrator's prompt-file opening line ("You are the 'generator' agent defined in .codex/agents/generator.toml...").

Model caveat: codex-plugin-cc's task command does NOT honor the model field from agent TOML. The Orchestrator passes --model <name> on every invocation, reading codex_generator_model from _config.yml. The TOML's model is kept for forward compat (a future plugin version may respect it).

Patch .codex/config.toml non-destructively: append [agents.planner], [agents.evaluator], [agents.generator] role declarations (with description and config_file pointing to the TOML above) if not already present. Preserve all existing entries (e.g., workflow-implementer).

Step 5: Generate Scripts

Write executable scripts to .harness/scripts/ (chmod 755):

• progress-append.sh — PostToolUse hook; reads stdin JSON via jq
• restore-after-compact.sh — SessionStart(compact) hook; dumps progress tail + state to stdout for reinjection
• stop-guard.sh — Stop hook; enforces Principal Skinner, self-manages stop_hook_active anti-loop flag
• tier-a-guard.sh — PreToolUse(Bash) hook; regex match against .harness/tier-a-patterns.txt, sets pending_human=true on hit
• mcp-allowlist.sh — PreToolUse(mcp__*) hook; denies non-allow-listed servers
• codex-progress-bridge.sh — Orchestrator helper for codex_* backends; parses Codex's feedback/<role>-<iter>-report.json and appends equivalent rows to progress.md + atomically updates _state.json. Copied verbatim regardless of backend selection so reconfiguration is a no-op
• codex-cli-dispatch.sh — Orchestrator helper for codex_cli; invokes codex exec, canonicalises narrative/report outputs, and bridges them into harness state
• check-sprint-prs-complete.sh — retroactive check for completed/done epics missing required _state.json.sprint_prs[n]
• staleness-watchdog.sh — optional Autonomous Ralph liveness monitor; appends STALE-WATCHDOG warnings when progress.md has no fresh timestamp and can opt-in respawn the wrapper via _config.yml
• foundation-readiness.sh — probing script used by /harness-plan Step 3.5. Accepts --epic <slug> (full assessment, writes .harness/<epic>/foundation-readiness.md and emits JSON summary) or --check <probe-key> (single probe, used by /harness-loop for foundation-sprint deliverable verification). See ../harness-plan/references/foundation-sprint-guide.md
• .harness/tier-a-patterns.txt — initial destructive-pattern regex set

Step 6: Codex Backend Setup (conditional)

Runs only when generator_backend ∈ {codex_cli, codex_cmux}.

1. Detect Codex CLI — codex --version. If it fails:
   • For codex_cli / codex_cmux selection: surface an error and advise npm install -g @openai/codex, then loop back to Round 2 with the selection restricted to claude.
   • For claude selection: proceed silently (skip this Step entirely).
2. Resolve Codex CLI settings:
   • Write codex_cli_binary (default /opt/homebrew/bin/codex) and codex_cli_sandbox (default danger-full-access) into _config.yml.
3. Deploy Codex-side hook scripts — copy (chmod 755) from references/codex-hooks/ to <project>/.codex/hooks/:
   • inject-harness-context.sh
   • tier-a-guard-codex.sh
   • codex-bash-log.sh
4. Generate <project>/.codex/hooks.json — render references/codex-hooks/hooks.json.template, substituting {{PROJECT_ROOT}} with the absolute project root path.
5. Enable codex_hooks feature flag — non-destructively patch <project>/.codex/config.toml:

   [features]
   codex_hooks = true
   

   Preserve any existing [features] entries and all other config.
6. Append Codex hook summary to the Step 10 summary report so the user sees what was installed on the Codex side.

If generator_backend == claude, skip this entire Step; the Claude backend does not require Codex CLI / hooks. (The legacy other value has been removed from the supported enum — see Step 1 hearing.)

Steps 7–10: Installation Integration

Read references/installation-integration.md completely (.ja.md for Japanese), then execute its Steps 7 through 10 in order. Also read every secondary reference it names before writing settings, CLAUDE.md, resilience state, or ignore rules.

Step 11: Summary Report

Emit to the user:

• Files created (paths relative to project root)
• Files patched (with "approved" or "proposed-only" suffix)
• Next recommended action: fully exit Claude Code, relaunch this repository with claude --resume, then run /harness-plan to create the first epic

Error Handling

Usage

# First-time install
/harness-init

# Re-run (reconfigure mode)
/harness-init

# Read-only preview (future; v1 always writes after final approval)
/harness-init --dry-run

What harness-init does NOT do

• Does not write product-spec.md — that is harness-plan's job
• Does not run any sprint — that is harness-loop's job
• Does not install worker agents for spec-driven workflows — use spec-workflow-init for that lane
• Does not add CI jobs, pre-commit hooks, or build pipelines — only .claude/settings.json hooks (ms tier). Other speed tiers are out of scope

References

• hearing-questions.md — bilingual question text
• rubric-presets.md — axis sets per project type
• hooks-templates.md — settings.json by level (Claude + Codex hook matrix)
• settings-merge.md — non-clobbering merge algorithm
• scripts.md — guard scripts in .harness/scripts/ (incl. codex-progress-bridge.sh)
• codex-hooks/ — Codex-side hook scripts + hooks.json.template (installed when generator_backend ∈ codex_*)
• agent-templates/ — Claude .md + Codex .toml role contracts for planner / generator / evaluator
• untrusted-content.md — external-content wrapping
• claudemd-patch.md — idempotent CLAUDE.md pointer patch
• resilience-schema.md — progress/state/metrics schemas
• templates/ — product-spec, sprint-contract, shared_state