Skip to content
/
Tier A A11 Governance

HOTL Plugin

hotl-plugin · yimwoo/hotl-plugin · ★ 22 · last commit 2026-05-10

Human-on-the-loop structured workflows that enforce design-before-code, resumable execution with state persistence, and explicit branch disposition — across 5 AI coding tools.

Best whenSmart routing should decide when to use a workflow (implementation) vs when to just answer (question/fix/debug) — forcing ceremony on every task creates fric…
Skip ifStarting code before requirements are clear, Skipping verification
vs seeds
bmad-method(skill-based phase progression). Differs from kiro in tool-agnosticity (5 tools vs 1 IDE). Differs from BMAD in resumabl…
Primitive shape 29 total
Commands 9 Skills 19 Hooks 1
00

Summary

HOTL Plugin — Summary

HOTL (Human-on-the-Loop) is a multi-tool AI coding workflow plugin for Codex, Claude Code, and Cline that enforces structured 8-phase workflows for feature work while staying out of the way for questions, quick fixes, and debugging. With 22 stars, it ships 19 skills, 1 hook (SessionStart), update/install shell scripts, adapter templates for Cursor and GitHub Copilot, and 8 execution phases (Brainstorm → Write Workflow → Lint → Branch → Execute → Review → Verify → Finish). Key design: the brainstorm skill produces HOTL contracts (intent/verification/governance) before any implementation; the loop-execution skill persists state in .hotl/state/ for resumable runs; every step has an explicit verify command; and the finish phase records the disposition of the execution branch (merge/PR/keep/discard). Closest seed comparison: resembles kiro (structured workflow phases with approval gates) but is tool-agnostic (Codex + Claude Code + Cline) rather than IDE-locked; resembles BMAD-METHOD in its skill-based phase progression but adds the execution state persistence and resume capability that BMAD lacks.

01

Overview

HOTL Plugin — Overview

Origin

Created by yimwoo. Single contributor. 22 stars. Self-described: "the main project" for HOTL skills, workflow templates, and installation docs. Last commit May 2026.

Philosophy

"Most AI coding sessions fail in predictable ways: code starts before requirements are clear, plans skip verification, risky changes execute without review, and the agent claims success without evidence. HOTL prevents all four by enforcing structured workflows for implementation tasks while staying out of the way for code questions, quick fixes, and debugging."

Smart Task Routing

Intent HOTL Response
Asking a question Just answers — no workflow
Quick fix (typo, config, one-liner) Fixes it, verifies, reports
Debugging Structured debugging — no brainstorm needed
Building something new Full workflow: brainstorm → write workflow → execute → verify

Human-on-the-Loop Meaning

The "HOTL" framing means humans are checkpoints, not the loop itself — HOTL enforces human review at the Review and Verify phases, but the agent executes autonomously within each phase.

Resumable Execution

"HOTL persists state in .hotl/state/ so interrupted runs can pick up where they stopped. Resume is verify-first: HOTL re-checks the last step before advancing."

Explicit Branch Disposition

The Finish phase decides what happens to the execution branch/worktree: merge back, publish/PR, keep, or discard. "HOTL records that disposition so execution history stays understandable later."

Supported Tools

Tool Integration type
Claude Code Plugin — commands, skills, hooks
Codex Plugin install (recommended) or native skill discovery
Cline Global rules + local HOTL skill files
Cursor Adapter templates via /hotl:setup
GitHub Copilot Adapter templates via /hotl:setup
02

Architecture

HOTL Plugin — Architecture

Distribution

  • Claude Code: /plugin marketplace add yimwoo/hotl-plugin && /plugin install hotl@hotl-plugin
  • Codex: git clone && bash install.sh --codex-plugin
  • Cline: curl -fsSL .../install-cline.sh | bash
  • Update: curl -fsSL .../update.sh | bash

Required Runtime

  • Claude Code, Codex CLI, or Cline
  • jq (optional but recommended for state persistence)
  • Bash

Directory Tree

hotl-plugin/
├── skills/              — 19 SKILL.md files
│   ├── brainstorming/
│   ├── writing-plans/
│   ├── loop-execution/
│   ├── executing-plans/
│   ├── subagent-execution/
│   ├── resuming/
│   ├── dispatch-agents/
│   ├── finishing-a-development-branch/
│   ├── pr-reviewing/
│   ├── code-review/
│   ├── requesting-code-review/
│   ├── receiving-code-review/
│   ├── document-review/
│   ├── verification-before-completion/
│   ├── tdd/
│   ├── systematic-debugging/
│   ├── skill-authoring/
│   ├── setup-project/
│   └── using-hotl/
├── hooks/
│   ├── hooks.json       — SessionStart hook (Codex/Claude Code)
│   ├── run-hook.cmd     — Windows hook runner
│   ├── session-start.ps1 — PowerShell session start
│   └── session-start/   — Session start scripts
├── commands/            — Slash commands for Claude Code
│   ├── brainstorm
│   ├── write-plan
│   ├── loop
│   ├── execute-plan
│   ├── subagent-execute
│   ├── resume
│   ├── pr-review
│   ├── check-update
│   └── setup
├── adapters/            — Adapter templates (Cursor, Copilot, strategic design)
├── agents/              — Agent definitions
├── docs/                — Documentation + checklists
│   └── checklists/      — SOLID/architecture, security, performance review checklists
├── runtime/             — Runtime scripts
├── workflows/           — Workflow documentation
├── .claude-plugin/      — Claude Code plugin manifest
├── .codex-plugin/       — Codex plugin manifest
├── .codex/              — Codex install guide
├── .cline/              — Cline install guide
└── install.sh, update.sh, install-cline.sh

Target AI Tools

Claude Code, Codex CLI, Cline (primary), Cursor + GitHub Copilot (adapter only)

State Root

.hotl/ in project directory:

  • .hotl/state/ — execution state for resume
  • .hotl/reports/ — execution reports
03

Components

HOTL Plugin — Components

Commands (Claude Code)

Command Purpose
/hotl:brainstorm Design the change, save design doc
/hotl:write-plan Create docs/plans/YYYY-MM-DD-<slug>-workflow.md
/hotl:loop Run workflow with autonomous loop execution
/hotl:execute-plan Run workflow with manual checkpoints
/hotl:subagent-execute Run workflow with delegated subagent execution
/hotl:resume Resume interrupted workflow run
/hotl:pr-review Review PR across multiple dimensions
/hotl:check-update Check for newer HOTL version
/hotl:setup Generate adapter files for other tools

Skills (19)

Category Skills
Design & Planning brainstorming, writing-plans, document-review
Execution loop-execution, executing-plans, subagent-execution, resuming, dispatch-agents
Finish finishing-a-development-branch
Quality & Review pr-reviewing, code-review, requesting-code-review, receiving-code-review, verification-before-completion
Dev Practices tdd, systematic-debugging, skill-authoring
Setup setup-project, using-hotl

Hooks (hooks.json)

Event Matcher Handler
SessionStart startup/clear/compact run-hook.cmd session-start

Only 1 hook event type.

Review Checklists (docs/checklists/)

Both code-review and pr-reviewing reference shared checklists for:

  • SOLID/architecture review
  • Security review
  • Performance/boundary conditions
  • Removal/simplification heuristics

8 Execution Phases

Phase Description
Brainstorm Clarify requirements, design, save design doc in docs/designs/
Write Workflow Generate docs/plans/YYYY-MM-DD-<slug>-workflow.md
Lint Self-check in planning; structural lint in preflight
Branch Resolve execution root (worktree or branch)
Execute Run plan in loop/manual/subagent mode
Review Review findings checked against codebase + HOTL contracts
Verify Run tests, lint, verify commands — no green light without proof
Finish Decide branch disposition: merge/PR/keep/discard
05

Prompts

HOTL Plugin — Prompts

Verbatim Excerpt 1: brainstorming/SKILL.md (HOTL Contracts)

Prompting technique: Scope-first classification; triple contract (intent/verification/governance); hard gate before code

<HARD-GATE>
Do NOT write any implementation code until the design is approved and writing-plans has generated the executable workflow.
</HARD-GATE>

## Process

1. **Explore context (cheap preflight first)**

   **Phase 1 — Cheap preflight** (Glob only, current project directory):
   - If user's message references a doc path → read it
   - Check for canonical design docs in `docs/designs/*.md`
   - Check for legacy design docs in `docs/plans/*.md`

2. **Determine scope** — decide between `feature`, `phase`, or `initiative` before the clarifying-questions loop.

   - **`feature`** — one feature, one bug fix, one refactor. Output: `docs/designs/YYYY-MM-DD-<slug>-design.md`
   - **`phase`** — one slice of a multi-phase initiative.
   - **`initiative`** — a multi-phase project. Output: `docs/designs/<topic>.md` (undated, strategic)

3. **Ask clarifying questions** — one at a time
4. **Propose 2-3 approaches** — with trade-offs and recommendation
5. **Present design in sections** — get approval after each section
6. **Define HOTL contracts** — always include all three:

### Intent Contract
intent: [one sentence goal]
constraints: [what must not change/break]
success_criteria: [how we know it's done]
risk_level: low | medium | high

### Verification Contract
verify_steps:
  - run tests: [test command]
  - check: [what to inspect]

Verbatim Excerpt 2: README.md (Real Execution Summary)

Prompting technique: Tabular execution evidence with step/status/iteration tracking

| Step                                          | Status             | Iterations |
|-----------------------------------------------|--------------------|------------|
| Step 1: Add feature flag and config wiring    | Done               | 1          |
| Step 2: Add backend endpoint for saved views  | Done               | 2          |
| Step 3: Add database migration and model      | Done               | 1          |
| Step 7: Add unit tests for reducers/hooks     | Done (28/28)       | 2          |
| Step 8: Add API integration tests             | Done (12/12)       | 2          |
| Step 12: Human review and acceptance          | Approved           | 1          |

9 files modified, 1 migration added, 3 new test files.
Unit, integration, and e2e suites all passing.

Note: This is from an actual HOTL execution session cited in the README — a real output, not an example.

09

Uniqueness

HOTL Plugin — Uniqueness

Differs From Seeds

Most similar to kiro (structured phased workflow with approval gates) and BMAD-METHOD (skill-based phase progression). Differs from kiro in being tool-agnostic (Codex + Claude Code + Cline + Cursor + Copilot) rather than IDE-locked. Differs from BMAD in having resumable execution state (.hotl/state/) and the explicit Finish phase with branch disposition record. The three-contract model (intent/verification/governance defined at brainstorm time) is unique in the batch — no seed defines all three contract types upfront before any implementation. Smart task routing (question/fix/debug/build-something-new) mirrors spec-kit's intent-first design but applies to tool routing rather than command routing.

Positioning

  • Broadest tool support in batch (5 tools: Codex, Claude Code, Cline, Cursor, Copilot)
  • The only framework with an explicit branch disposition record (Finish phase)
  • Three-contract model (intent/verification/governance) established before coding is unique
  • Resumable state via .hotl/state/ with verify-first resume is more rigorous than most peers
  • Smart routing distinguishes implementation from questions/quick-fixes without user deciding

Observable Failure Modes

  • jq dependency: state persistence silently degrades without jq
  • Scope classification ambiguity: feature/phase/initiative determination can be unclear
  • Worktree conflicts: non-HOTL dirty files in host mode hard-fail unless explicitly allowed
  • Design approval gate: if user skips design approval, HARD-GATE prevents code — could frustrate quick-fix users who hit this accidentally
  • 1 hook only (SessionStart): no PostToolUse or Stop hooks — verification is skill-driven, not hook-enforced
04

Workflow

HOTL Plugin — Workflow

Smart Routing

Intent HOTL action
Question Just answers
Quick fix Fix → verify → report
Debugging Systematic debugging skill
Implementation Full 8-phase workflow

8-Phase Workflow

Phase Artifact Gate
Brainstorm docs/designs/YYYY-MM-DD-<slug>-design.md + HOTL contracts User design approval
Write Workflow docs/plans/YYYY-MM-DD-<slug>-workflow.md User plan approval
Lint Structural lint report Pass required
Branch git worktree on hotl/<slug> (default) None
Execute Code changes + .hotl/state/ updates None
Review Review findings report Findings checked against contracts
Verify Test/lint/verify output All green required
Finish Branch disposition record Explicit disposition required

HOTL Contracts (from Brainstorm)

# Intent Contract
intent: [one sentence goal]
constraints: [what must not change/break]
success_criteria: [how we know it's done]
risk_level: low | medium | high

# Verification Contract
verify_steps:
  - run tests: [test command]
  - check: [what to inspect]

# Governance Contract
approval_required: [which phases need human approval]

Branch Strategy

  • Default: git worktree on hotl/<slug>
  • worktree: false — stays in current checkout, may switch/create target branch
  • worktree: host — keeps current feature branch as provided by host tool

Resumable Execution

.hotl/state/ persists execution state
Resume is verify-first: re-checks last step before advancing
Requires jq for full state persistence

Execution Modes (loop vs manual vs subagent)

Mode Skill Description
Loop loop-execution Autonomous execution until done
Manual executing-plans Manual checkpoints per step
Subagent subagent-execution Delegated to subagents
06

Memory Context

HOTL Plugin — Memory & Context

State Persistence

.hotl/state/ — execution state for resumable runs
.hotl/reports/ — execution reports per run
docs/designs/ — design docs (dated tactical or undated strategic)
docs/plans/ — workflow files (dated, executable)

Requires jq

jq must be installed for full state persistence and durable reports.
Without jq: HOTL still works but runs without state files.

Resume Protocol

  1. $hotl:resuming reads .hotl/state/ to identify last completed step
  2. Verify-first: re-checks last step output before advancing
  3. If last step was verified, advance to next step
  4. If not, re-run verification before continuing

Cross-Session Handoff

Design doc + workflow plan + .hotl/state/ provide full context for session resume.
Execution history stays understandable via Finish phase disposition records.

Context Compaction

No explicit compaction handling documented.
Design docs and workflow plans in docs/ provide persistent context anchors.

07

Orchestration

HOTL Plugin — Orchestration

Multi-Agent: Yes (optional)

subagent-execution skill and dispatch-agents skill enable multi-agent execution.
Parent agent delegates to subagents for individual workflow steps.

Orchestration Pattern

sequential (8 phases execute in order) + optional parallel subagent dispatch within Execute phase

Multi-Model

No — no model routing documented

Isolation Mechanism

git-worktree (default branch strategy: hotl/<slug>)
Also supports: current checkout (worktree: false) or host-provided branch (worktree: host)

Execution Mode

interactive-loop (loop-execution skill) + event-driven (manual checkpoints)

Consensus Mechanism

None — human review is the gate at Review phase

Prompt Chaining

Yes: brainstorm contracts → workflow plan → execution is a chained pipeline

Context Compaction

Not explicitly handled

08

Ui Cli Surface

HOTL Plugin — UI & CLI Surface

No Dedicated CLI Binary

HOTL has no standalone CLI — it installs into the target tool's plugin system.

Commands (Claude Code)

9 slash commands: brainstorm, write-plan, loop, execute-plan, subagent-execute, resume, pr-review, check-update, setup

Codex Invocation

No /hotl:* syntax in Codex. Natural language with @hotl or $hotl:brainstorming.

Update Mechanism

Self-updating via URL:

curl -fsSL https://raw.githubusercontent.com/yimwoo/hotl-plugin/main/update.sh | bash

Or /hotl:check-update in Claude Code.

Cross-Platform Adapters

/hotl:setup generates adapter files for:

  • Cursor
  • GitHub Copilot

No Dashboard

No web dashboard.

Observability

  • .hotl/state/ — execution state per run
  • .hotl/reports/ — execution reports
  • Tabular execution summary in output (step/status/iterations)

Related frameworks

same archetype · same primary tool · same memory type

OpenHarness ★ 13k
A11 Governance

Open-source Python agent runtime providing complete harness infrastructure: tools, memory, governance, swarm coordination, and…

Trae Agent ★ 12k
A11 Governance

Research-friendly open-source CLI coding agent by ByteDance, designed for academic ablation studies and modular LLM provider…

Sweep AI ★ 7.7k
A11 Governance

Autonomous GitHub bot that converts issues to pull requests using a sequential multi-agent pipeline.

Agent Governance Toolkit (microsoft) ★ 2.3k
A11 Governance

Enterprise-grade AI agent governance: YAML policy enforcement, 12-vector prompt injection defense, zero-trust identity,…

TDD Guard ★ 2.1k
A11 Governance

Mechanically enforces the Red-Green-Refactor TDD cycle by blocking file writes that violate TDD principles via a PreToolUse hook…

Agentic Coding Flywheel Setup (ACFS) ★ 1.5k
A11 Governance

Take a complete beginner from laptop to three AI coding agents running on a VPS in 30 minutes via an idempotent manifest-driven…