--- name: hess-run description: >- HESS (Harness Engineering Skill Set): auto-detects current state and runs the correct phase. Use when the user says "HESS", "hess-run", or asks to continue/start a HESS task without specifying which phase. --- # HESS — Harness Engineering Skill Set Single-entry dispatcher for the HESS workflow. This file defines the shared conventions (state machine, artifact formats, phase contracts) and routes to the appropriate phase file. Phase workflows: `.agent/skills/hess-run/phases/{plan,review,execute,verify}.md` Templates: `.agent/skills/hess-run/templates/{design,contract}.md` --- ## Task Folder Structure Every task operates on a dedicated folder as its single source of truth: ``` / ├── context.md # Input: task goals, scope, references (user-provided) ├── state.md # State machine tracker (managed by phases) ├── evaluation.md # Exploration findings (plan) ├── design.md # Architecture & design decisions (plan) ├── tasks.md # Incremental task breakdown (plan) ├── contract.json # Risk tier & verification contract (plan) ├── reviews.md # Review findings as actionable tasks (review) ├── verifies.md # Verification findings as actionable tasks (verify) └── verifies.json # Machine-readable verification results (verify) ``` --- ## State Machine ``` DRAFT ----> PLANNING ----> REVIEWING ----> REVIEWED ----> EXECUTING ----> EXECUTED ----> VERIFYING ----> VERIFIED ^ | ^ | \-- --------- / \--- ----------------------------- / \--------------------------------- when contract.json verified failed -----------------------------------/ ``` ### Allowed Transitions | Current State | Phase | Next State | |---------------|-------------|------------| | DRAFT | plan | PLANNING | | PLANNING | plan | REVIEWING | | REVIEWING | review | REVIEWED | | REVIEWING | review | PLANNING (rejection) | | REVIEWED | execute | EXECUTING | | EXECUTING | execute | EXECUTED | | EXECUTED | verify | VERIFYING | | VERIFYING | verify | VERIFIED | | VERIFYING | verify | EXECUTING (rework or continue rest tasks) | | VERIFYING | verify | PLANNING (contract failure) | ### State Guard (All Phases) Every phase **MUST** validate the current state before executing. At the start of each workflow: 1. Read `state.md` (or confirm it does not exist for DRAFT). 2. Check if the current state is in this phase's allowed entry states. 3. If the state is **not** allowed: - **STOP** immediately — do not proceed with any work. - Inform the user of the current state and which phase should run next. - Provide a suggestion based on the routing table below. ### State Routing | Current State | Phase to run | |---------------|--------------| | DRAFT | plan | | PLANNING | plan | | REVIEWING | review | | REVIEWED | execute | | EXECUTING | execute | | EXECUTED | verify | | VERIFYING | verify | | VERIFIED | (done) | --- ## state.md Format ```markdown --- state: last_phase: updated_at: --- history | state | phase | reason | time | |-------|-------|--------|------| | | | | | | | | | | ``` The `reason` field is **required** for rejection/rework transitions (REVIEWING→PLANNING, VERIFYING→EXECUTING, VERIFYING→PLANNING) and optional for forward transitions. For rejection/rework, `reason` must be a complete sentence that names the specific issue and the file or criterion involved. One-word entries like "issues found" are not acceptable. Example: `"Scenario walkthrough failed: multi-address pagination uses single cursor string (design.md § Single-Chain Fast Path)"`. --- ## evaluation.md Format Full template: **`.agent/skills/hess-run/templates/evaluation.md`** — load it when writing or reviewing `evaluation.md`. Key rules (summary): - Task knowledge base for all phase when required --- ## design.md Format Full template: **`.agent/skills/hess-run/templates/design.md`** — load it when writing `design.md`. Key rules (summary): - All sections required; write `N/A` for inapplicable sections. - Multi-option designs: add `### Option A` / `### Option B` under Solution Architecture; leave "Chosen" blank for the reviewer. - Include `## Criteria Coverage Map` at the end (see contract.md template for format). --- ## tasks.md Format Full template: **`.agent/skills/hess-run/templates/tasks.md`** — load it when updating `tasks.md`. --- ## contract.json Schema Full reference: **`.agent/skills/hess-run/templates/contract.md`** — load it when writing or validating `contract.json`. Key rules (summary): - `taskRiskTier`: highest tier among all affected files — drives autonomy gate in execute phase. - `riskTierRules.high`: auth/authz, DB migrations, proto files, secret handling, payment logic, infra/deployment config. - `riskTierRules.medium`: general business logic, new API endpoints, external integrations, config changes. - `riskTierRules.low` (`"**"`): format, simple bugfix, tests, docs. - `mergePolicy.requiredChecks`: automated checks block on failure; manual checks (`Browser Evidence`) get `[pending: ...]` annotation. - `verificationCriteria`: EARS-formatted descriptions, one criterion per acceptance criterion from `context.md`. - After generating criteria, append `## Criteria Coverage Map` to `design.md`. hess-verify checks each criterion by ID and marks it pass/fail in `verifies.md`. --- ## verifies.json Format Machine-readable verification results, produced alongside `verifies.md` by the verify phase. Used by `scripts/contract-check.sh` for automated aggregate gating. ```json { "date": "", "phase": "", "criteria": [ { "id": "vc-N", "dimension": "", "result": "", "evidence": "" } ], "dimensions": { "constraint": { "status": "", "findings": [] }, "code": { "status": "", "findings": [""] }, "correctness": { "status": "", "findings": [] }, "performance": { "status": "", "findings": [] }, "security": { "status": "", "findings": [] } }, "overall": "" } ``` Rules: - `overall` is `"pass"` only when all criteria are PASS or SKIP **and** all dimensions have status `"pass"`. - `verifies.json` follows the same lifecycle as `verifies.md`: both are removed when all checks pass (signaling approval). - `scripts/contract-check.sh --with-git-diff` reads `verifies.json` for the verify results gate check. --- ## Dispatcher Workflow ### Step 1: Locate task folder Determine the task folder from user input: - If the user specifies a folder, use it. - If the user references a `context.md`, use its parent folder. - If ambiguous, ask the user which task folder to use. ### Step 2: Read state Read `state.md` in the task folder. If it does not exist, treat as `DRAFT`. ### Step 3: Route and dispatch Use the **State Routing** table above to determine which phase to run. If the state is `VERIFIED`, inform the user: "Task is complete." Otherwise, execute the phase **inline in the current session** — do NOT spawn a sub-agent. Inline execution preserves accumulated context (already-read files, repo understanding, conversation history) and avoids redundant reloading. Read and follow the phase file directly: ``` .agent/skills/hess-run/phases/.md ``` #### Phase Model Reference Different phases benefit from different model strengths. If the user has configured model switching, use the following as a guide: | Phase | Preferred Model | Rationale | |---------|-----------------|--------------------------------------------------| | plan | opus | Deep analysis and design require strongest model | | review | opus | Critical judgment; catches subtle issues | | execute | sonnet | Balanced speed/quality for implementation work | | verify | sonnet | Systematic verification; speed matters | ### Step 4: Report After the phase completes, report to the user: - Which phase ran and what state transition occurred - What the next step is (which phase will run next, or "task complete") If the completed phase involved heavy file exploration (common in `plan`), add this note: > Context tip: if the conversation feels long, you can run `/compact` before > the next `hess-run` — all progress is saved in files and nothing will be lost.