Skip to the content.

Harper Workflow

Overview

The current codebase implements Harper as an iterative, repository-aware pipeline:

IDEA → SPEC → PLAN → KIT → EVAL → GATE → FINALIZE

A delivered project evolves release by release with /idea --extend (IDEA, SPEC and PLAN of the next release merged in continuity, then the same KIT → EVAL → GATE → FINALIZE per new REQ):

release v1: IDEA → SPEC → PLAN → (KIT → EVAL → GATE)* → FINALIZE
release v2: /idea --extend → (KIT → EVAL → GATE)* for the new REQs → FINALIZE

This is not a purely prompt-only flow. It is backed by:

Phase-by-phase behavior

IDEA

Purpose:

Primary output:

Entry:

SPEC

Purpose:

Primary output:

Entry:

PLAN

Purpose:

Primary outputs:

Entry:

KIT

Purpose:

Primary output area:

Common outputs:

Entry:

EVAL

Purpose:

Primary output:

Entry:

GATE

Purpose:

Primary output:

Entry:

FINALIZE

Purpose:

Typical output:

Entry:

Current KIT model

KIT is candidate-first and REQ-oriented.

Default target resolution

If the user does not specify a REQ, the extension resolves the next open eligible REQ from the plan.

Candidate output roots

Current allowed candidate roots are:

Canonical protection

The current execution contract explicitly protects canonical roots from direct local-agent mutation:

Early document phases on the local agent

/idea, /spec, and /plan can also run through the same execution-agent architecture used by /kit, /eval, /finalize, and /extend. They reuse the orchestrator execution policy, run_phase dispatch, the local-agent package envelope, /local-agent/complete normalization, and the extension actuator. The only phase-specific differences are the expected outputs, allowed write paths, phase prompt, and phase validation.

The write policy for these phases is narrow:

Every other docs/harper/ path remains protected, and src/, test/, tests/, and .git/ stay forbidden. Cloud and local execution stay semantically equivalent: the phase definitions under orchestrator/phases/ (cloud system prompts cloud_*.md, local-agent phase.yaml / text.yaml) are the canonical source of phase behavior, CLike governance remains canonical, and the agent only performs bounded document work that CLike then validates and governs.

Follow-up KIT phases

The inspected sources implement a multi-step KIT follow-up sequence:

kit
integrity_eval
promotion_hardener
promotion_eval

These phases are treated as explicit follow-up work on an existing candidate slice, not as aliases for the base KIT phase.

EVAL model

The current sources support two eval layers.

Canonical eval

The canonical eval path is owned by CLike through /v1/eval/run.

Optional local-agent eval pre-pass

If local-agent eval is enabled:

This means the current implementation should be documented as:

Acceptance-first KIT (clike.kit.acceptanceFirst, opt-in)

By default one KIT call writes both the code and the tests that judge it. With clike.kit.acceptanceFirst, /kit REQ makes two calls:

  1. acceptance stage (kit.phases=["acceptance"]): only test/**, ci/LTC.json, ci/HOWTO.md, test manifests and docs/ACCEPTANCE_<REQ>.md (criterion → test → LTC check), derived from SPEC.md, PLAN.md and the REQ in plan.json; src/ outputs are dropped;
  2. the extension writes them and locks them (POST /v1/acceptance/lock) — before any code exists;
  3. code KIT (kit.acceptance_first=true): receives the locked files read-only and writes the code to pass them; test/LTC changes go through the same governance as an auto-eval repair (rejected, or restored when a local agent wrote them).

Works with the cloud and with local agents. Benchmark: --acceptance-first.

Auto-eval and regression

/eval <REQ-ID> --fix ["hint"] runs a bounded, governed repair loop (KIT repair from the real failures → eval) and, by default, eval and gate also re-run the acceptance checks of the promoted REQs. /gate <REQ-ID> --fix ["hint"] runs the same loop from a failing gate. The hint is optional: CLike flags failures that passed in earlier runs as nondeterministic. See auto-eval.md.

Native programs a check needs (database and messaging clients, cloud and IaC CLIs, a JDK…) are installed in the eval sandbox from CLike’s tools catalog when an eval needs them, after the developer’s confirmation; /tools shows and manages them. See auto-eval.md.

GATE model

Current gate characteristics:

The current docs should treat GATE as a policy-and-promotion decision phase, not merely a test status wrapper.

FINALIZE model

/finalize closes a release: it brings the promoted solution to running and configured. The REQ test suites are not run again (each REQ passed them at its gate); CLike installs, builds, configures, starts and smoke-checks the solution in the eval sandbox (ci/SOLUTION_LTC.json, ci/solution/) and repairs it until it passes. It writes the README (marked as a CLike project), docs/harper/FINALIZE_REPORT.md for the developer, docs/harper/SOLUTION_EVAL.md, and scripts/setup_local / start_solution_local (Docker, Podman or native; free host ports), then offers to configure and start the solution on the developer’s machine. See commands.md.

Evolving a delivered project (/idea --extend)

Cloud and local agents get the same context

A local agent (Codex, Claude Code) reads the workspace; a cloud model sees only its prompt. CLike puts in the prompt what the local agent would read, bounded:

History scope and core context

Harper requests carry contextual state including:

This is one of the key differences between Harper and the legacy /v1/generate flow.

What the current workflow is not

The current workflow should not be documented as: