{"id":46905462,"url":"https://github.com/yimwoo/hotl-plugin","last_synced_at":"2026-07-02T06:00:45.581Z","repository":{"id":342190237,"uuid":"1173185585","full_name":"yimwoo/hotl-plugin","owner":"yimwoo","description":"HOTL plugin for Codex, Claude Code, and Cline. Human-on-the-Loop AI coding workflows with planning, review, and verification.","archived":false,"fork":false,"pushed_at":"2026-06-29T23:55:23.000Z","size":1000,"stargazers_count":24,"open_issues_count":0,"forks_count":3,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-30T00:16:20.737Z","etag":null,"topics":["agent-workflow","ai-coding","claude-code","cline","codex","developer-tools","hotl","skills","workflow"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/yimwoo.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-05T05:03:38.000Z","updated_at":"2026-06-29T23:55:27.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/yimwoo/hotl-plugin","commit_stats":null,"previous_names":["yimwoo/hotl-plugin"],"tags_count":55,"template":false,"template_full_name":null,"purl":"pkg:github/yimwoo/hotl-plugin","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yimwoo%2Fhotl-plugin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yimwoo%2Fhotl-plugin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yimwoo%2Fhotl-plugin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yimwoo%2Fhotl-plugin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yimwoo","download_url":"https://codeload.github.com/yimwoo/hotl-plugin/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yimwoo%2Fhotl-plugin/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35034985,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-02T02:00:06.368Z","response_time":173,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-workflow","ai-coding","claude-code","cline","codex","developer-tools","hotl","skills","workflow"],"created_at":"2026-03-11T01:07:40.010Z","updated_at":"2026-07-02T06:00:45.575Z","avatar_url":"https://github.com/yimwoo.png","language":"Shell","funding_links":[],"categories":["Codex Workflow Frameworks"],"sub_categories":[],"readme":"# HOTL Plugin for Codex, Claude Code, and Cline\n\n**HOTL (Human-on-the-Loop)** is an AI coding workflow plugin and skill pack for **Codex**, **Claude Code**, and **Cline**. It keeps implementation work grounded in a design, an executable workflow, review checkpoints, and verification evidence.\n\nUse HOTL for feature work, refactors, and risky changes where \"just start coding\" is too loose. It stays out of the way for code questions, debugging, and obvious one-line fixes.\n\nAdapter templates are also available for Cursor and GitHub Copilot.\n\nFor host-native execution, HOTL exposes a portable boundary: `runtime/hotl-rt normalize` produces a read-only workflow contract, drivers share one lifecycle protocol, and `runtime/hotl-rt receipt` proves completion from persisted evidence rather than chat claims.\n\n## Table of Contents\n\n- [Why HOTL](#why-hotl)\n- [Quick Start](#quick-start)\n- [First HOTL Run](#first-hotl-run)\n- [The HOTL Workflow](#the-hotl-workflow)\n- [When To Use It](#smart-task-routing)\n- [Host Capability Baseline](#host-capability-baseline)\n- [Governed Execution](#governed-execution)\n- [Commands \u0026 Usage](#commands--usage)\n- [Skills Overview](#skills-overview)\n- [Updating](#updating)\n- [Supported Tools](#supported-tools)\n- [Automation Templates](#automation-templates)\n- [Repository Structure](#repository-structure)\n- [Contributing](#contributing)\n\n## Why HOTL\n\nMost 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.\n\nHOTL prevents all four by enforcing structured workflows for implementation tasks while staying out of the way for code questions, quick fixes, and debugging.\n\nIf someone searches for a \"HOTL plugin\" or a \"Human-on-the-Loop AI coding workflow\", this repo is the main project: it contains the canonical HOTL skills, workflow templates, and installation docs for Codex, Claude Code, and Cline.\n\n## Quick Start\n\nPick the install path for the tool you use. Codex users should prefer plugin install; native skills are only for older Codex builds or local HOTL development.\n\n### Claude Code\n\n```text\n/plugin marketplace add yimwoo/hotl-plugin\n/plugin install hotl@hotl-plugin\n```\n\n### Codex\n\nRecommended plugin install for both Codex CLI and Codex app users:\n\n```bash\ngit clone https://github.com/yimwoo/hotl-plugin /tmp/hotl-plugin\nbash /tmp/hotl-plugin/install.sh --codex-plugin\ncodex plugin add hotl@codex-plugins\n```\n\nRestart Codex or start a new session after installation. The final command above\nis the direct CLI install path. To install from the interactive plugin browser\ninstead:\n\nCodex CLI:\n\n```text\ncodex\n/plugins\n```\n\nIn the plugin browser, switch to **Local Plugins**, open **HOTL**, and select\n`Install plugin`. If HOTL is installed but disabled, press `Space` to enable it.\n\nCodex app: open **Plugins**, switch to **Local Plugins**, and install HOTL. The CLI and app share the same Codex plugin configuration when they use the same Codex profile.\n\nPlugin install does not automatically remove an older native-skills install. If both are present, Codex may discover duplicate HOTL sources. See [`docs/README.codex.md`](docs/README.codex.md) for the recommended migration path.\n\nNative skills fallback for older Codex builds or local HOTL development: clone to `~/.codex/hotl` and symlink `~/.agents/skills/hotl` to its `skills/` directory. In that mode, `~/.codex/hotl` is the stable channel and should track `origin/main`. Full guide: [`docs/README.codex.md`](docs/README.codex.md).\n\n### Cline\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/yimwoo/hotl-plugin/main/install-cline.sh | bash\n```\n\nFull guide: [`docs/README.cline.md`](docs/README.cline.md)\n\n## First HOTL Run\n\nAfter install, start with a design request. HOTL will choose the right workflow stage and save durable artifacts in the project.\n\n| Tool | Try this |\n| --- | --- |\n| Codex | `@hotl brainstorm this feature before coding: \u003cyour feature\u003e` |\n| Claude Code | `/hotl:brainstorm \u003cyour feature\u003e` |\n| Cline | `brainstorm this feature before coding: \u003cyour feature\u003e` |\n\nTypical outputs:\n\n- Design doc: `docs/designs/YYYY-MM-DD-\u003cslug\u003e-design.md`\n- Executable workflow: `docs/plans/YYYY-MM-DD-\u003cslug\u003e-workflow.md`\n- Execution state and reports: `.hotl/state/` and `.hotl/reports/`\n\n## The HOTL Workflow\n\nImplementation tasks follow eight phases:\n\n| Phase | What happens |\n| --- | --- |\n| **Brainstorm** | Clarify requirements. Compare approaches. Define intent, verification, and governance contracts. Save a design doc in `docs/designs/`. |\n| **Write Workflow** | Use `writing-plans` to generate `docs/plans/YYYY-MM-DD-\u003cslug\u003e-workflow.md` with steps, verification, loop conditions, and gates. |\n| **Lint** | Self-check built into planning. Structural lint runs automatically in execution preflight. |\n| **Branch** | Resolve an execution root. Default is a git worktree on `hotl/\u003cslug\u003e`; `worktree: false` stays in the current checkout and may switch/create the target branch; `worktree: host` keeps the current feature branch exactly as provided by Codex or another host tool. Non-HOTL dirty files and protected-branch host mode hard-fail unless explicitly allowed. |\n| **Execute** | Prefer `governed-execution`, which routes to an explicitly enabled native Codex/Claude driver or the conformant generic fallback. Direct loop, manual, and subagent modes remain available. |\n| **Review** | Review findings are checked against the codebase and HOTL contracts before acting. |\n| **Verify** | Run tests, lint, and verify commands. No green light without proof. |\n| **Finish** | Decide what happens to the execution branch/worktree: merge back, publish/PR, keep, or discard. HOTL records that disposition so execution history stays understandable later. |\n\nHere is what a real HOTL feature-delivery session can look like:\n\n```text\nExecution Summary\n\n| Step                                          | Status             | Iterations |\n|-----------------------------------------------|--------------------|------------|\n| Step 1: Add feature flag and config wiring    | Done               | 1          |\n| Step 2: Add backend endpoint for saved views  | Done               | 2          |\n| Step 3: Add database migration and model      | Done               | 1          |\n| Step 4: Build saved views panel UI            | Done               | 3          |\n| Step 5: Connect UI to API state flow          | Done               | 2          |\n| Step 6: Add analytics + audit logging         | Done               | 1          |\n| Step 7: Add unit tests for reducers/hooks     | Done (28/28)       | 2          |\n| Step 8: Add API integration tests             | Done (12/12)       | 2          |\n| Step 9: Add e2e coverage for create/apply     | Done (6/6)         | 3          |\n| Step 10: Run lint and typecheck               | Done               | 2          |\n| Step 11: Run full test suite                  | Done (46/46)       | 1          |\n| Step 12: Human review and acceptance          | Approved           | 1          |\n\n9 files modified, 1 migration added, 3 new test files. Unit, integration, and e2e suites all passing.\n```\n\nEvery step has a verify command. If verification fails, execution stops and reports instead of silently claiming success.\n\n**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. State persistence and resumable execution require [`jq`](https://jqlang.github.io/jq/) — install it with `brew install jq` (macOS), `apt-get install jq` (Linux), or `scoop install jq` (Windows). Without `jq`, HOTL still works but runs without state files or durable reports. For the deeper execution model, see [`docs/how-it-works.md`](docs/how-it-works.md) and [`docs/workflow-format.md`](docs/workflow-format.md).\n\n## Smart Task Routing\n\nHOTL does not force ceremony on every task. It routes by intent:\n\n| What you're doing | What HOTL does |\n| --- | --- |\n| Asking a question (\"how does this work?\") | Just answers — no workflow |\n| Quick fix (typo, config, one-liner) | Fixes it, verifies, reports back |\n| Debugging (\"why is this failing?\") | Structured debugging — no brainstorm needed |\n| Building something new | Full workflow: brainstorm, write workflow, execute, verify |\n\n## Host Capability Baseline\n\nHOTL maintains a source-backed [host capability matrix](docs/host-capabilities.md)\nfor the Codex, Claude Code, and generic fallback features that matter to governed\nexecution. The canonical catalog lives at\n`runtime/capabilities/catalog.json`; regenerate the matrix with\n`scripts/hotl-capabilities.sh render` and inspect the current machine without\nchanging it with `scripts/hotl-capabilities.sh probe`.\n\nThe probe deliberately reports `unknown` when an installed host does not expose\nenough evidence to prove entitlement, rollout, administrator enablement, or\nusable permissions. Provider documentation, local detection, and HOTL\nconformance are separate claims.\n\nThe capability catalog itself is descriptive only. It does **not** choose an\nexecution driver, enable host features, or change permissions. Driver selection\nis implemented separately under `runtime/drivers/`. HOTL now includes\nexperimental Codex and Claude Code native drivers, while `hotl-rt` remains the\nconformant generic execution path.\n\n## Governed Execution\n\n`governed-execution` is the preferred entry point for running a workflow. Its\ndefault `auto` mode is conservative: it selects the generic fallback unless\nnative execution is explicitly enabled with `HOTL_CODEX_NATIVE=1`,\n`HOTL_CLAUDE_NATIVE=1`, or `--mode native`. Host permissions, sandboxes, and\napproval policy always remain authoritative. See [Host-Native Drivers](docs/host-native-drivers.md)\nand the [migration guide](docs/migration-host-native.md).\n\nThe portable execution boundary also provides:\n\n- Normalized workflow contracts and state-derived, redacted completion receipts:\n  [portable workflow and receipt contract](docs/contracts/portable-workflow-and-receipt.md)\n- Sensitive-action decisions, observed budgets, and verify-first recovery:\n  [policy, budget, and recovery contract](docs/contracts/policy-budget-recovery.md)\n- Deterministic driver evidence and optional model-neutral evaluations:\n  [driver conformance](docs/contracts/driver-conformance.md) and\n  [evaluation result](docs/contracts/evaluation-result-output.md)\n- Offline, safety-first profile comparison with\n  `scripts/hotl-evaluation-report.sh`\n- Budgeted evaluation campaigns, append-only history, drift detection, and\n  proposal-only profile review with `scripts/hotl-evaluation-{campaign,collect,history,proposal}.sh`\n- Local, read-only adoption reporting with `scripts/hotl-adoption-report.sh`\n- Proposal-only memory candidates with `scripts/hotl-memory-proposal.sh`; this\n  helper never writes to a memory system directly\n\n### Measured Adaptive Evaluation\n\nCompare existing evaluation records locally, with deterministic JSON by default\nor a concise human view:\n\n```bash\nscripts/hotl-evaluation-report.sh --format text results/*.json\n```\n\nRecommendation eligibility requires at least two explicit profile identities,\nthree shared scenario/revision pairs, and a fully known matching environment.\nProfiles with incomplete outcomes, contract failures, or post-completion defects\nare disqualified. Missing duration, agent, token, or cost telemetry remains\nunknown and cannot improve a profile's standing. The output may say\n`collect_more_evidence`, require human review, or present one profile for human\nreview; it never changes a model, driver, policy, permission, or routing\nconfiguration. See the\n[evaluation summary contract](docs/contracts/evaluation-summary-output.md).\n\n### Continuous Evaluation and Drift Detection\n\nPhase 8 turns approved profiles and shared scenarios into repeatable campaigns:\n\n```bash\nbash scripts/hotl-evaluation-campaign.sh plan campaign.json\nbash scripts/hotl-evaluation-collect.sh run campaign.json --approve-live\nbash scripts/hotl-evaluation-history.sh append-run .hotl/evaluation-history \\\n  campaign.json .hotl/evaluations/example/campaign-run.json\nbash scripts/hotl-evaluation-history.sh report .hotl/evaluation-history \\\n  \u003e .hotl/evaluation-history-report.json\nbash scripts/hotl-evaluation-proposal.sh --format text \\\n  .hotl/evaluation-history-report.json\n```\n\nPlanning is read-only. Live collection requires explicit approval and hard call\nand elapsed-time budgets; provider cost limits are accepted only when the host\ncan enforce them before a call. History is append-only and separates workload,\nprompt/schema, host, adapter/model, toolchain, telemetry, incomplete-campaign,\nand quality-regression states before comparing trends.\n\nEvery proposal requires human review and declares\n`automatic_selection_performed: false` and\n`configuration_changes_performed: false`. See\n[Continuous Evaluation and Drift Detection](docs/continuous-evaluation.md).\n\n## Commands \u0026 Usage\n\n### Claude Code\n\n| Command | What it does |\n| --- | --- |\n| `/hotl:brainstorm` | Design the change before coding and save a design doc |\n| `/hotl:write-plan` | Create `docs/plans/YYYY-MM-DD-\u003cslug\u003e-workflow.md` from the approved design |\n| `/hotl:governed-execution` | Run a workflow through the preferred native-or-fallback governed driver |\n| `/hotl:loop` | Run the workflow with autonomous loop execution |\n| `/hotl:execute-plan` | Run the workflow with manual checkpoints |\n| `/hotl:subagent-execute` | Run the workflow with delegated subagent execution |\n| `/hotl:resume` | Resume an interrupted workflow run |\n| `/hotl:pr-review` | Review a PR across multiple dimensions |\n| `/hotl:check-update` | Check if a newer HOTL version is available |\n| `/hotl:setup` | Generate adapter files for other tools |\n\n### Codex\n\nThere is no `/hotl:*` command syntax in Codex. Instead, describe the task in natural language with `@hotl`, or force a specific skill with `$hotl:brainstorming`, `$hotl:writing-plans`, or `$hotl:pr-reviewing`. Plain text like `hotl:brainstorming` is not a reliable user-facing invocation form in Codex. In the picker, Codex may display these skills as `Hotl:brainstorming`-style labels. For setup and prompt examples, see [`.codex/INSTALL.md`](.codex/INSTALL.md) and [`docs/README.codex.md`](docs/README.codex.md).\n\n## Skills Overview\n\n| Category | Skills | What they do |\n| --- | --- | --- |\n| Design \u0026 Planning | `brainstorming`, `writing-plans`, `document-review` | Clarify requirements, define contracts, write design docs, and create executable workflows |\n| Execution | `governed-execution`, `loop-execution`, `executing-plans`, `subagent-execution`, `resuming`, `dispatch-agents` | Route governed workflows to native or fallback drivers with verification, retries, persistence, and delegation |\n| Finish | `finishing-a-development-branch` | Close the execution lifecycle intentionally: merge back, publish for review, keep, or discard the execution checkout |\n| Quality \u0026 Review | `pr-reviewing`, `code-review`, `requesting-code-review`, `receiving-code-review`, `verification-before-completion` | Review changes and require evidence before completion. Both `code-review` and `pr-reviewing` reference shared [review checklists](docs/checklists/) for SOLID/architecture, security, performance/boundary conditions, and removal/simplification heuristics. |\n| Dev Practices | `tdd`, `systematic-debugging`, `skill-authoring` | Apply test-first development, structured debugging, and disciplined skill/prompt authoring workflows |\n| Setup | `setup-project`, `using-hotl` | Generate adapter files and establish HOTL operating context |\n\nFor detailed descriptions and phase mappings, see the [full skills reference](docs/skills.md).\n\nWant to create or modify HOTL skills? Use `skill-authoring` first, then see [Authoring Skills vs Agents](docs/authoring-skills-vs-agents.md).\n\n## Updating\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/yimwoo/hotl-plugin/main/update.sh | bash\n```\n\nCovers Claude Code, Codex (both native-skills and plugin source checkout), and Cline. Skips tools that are not installed. For a Codex plugin install, this refreshes the source checkout and cached files; rerun `install.sh --codex-plugin` when you also need to refresh marketplace version metadata, then reconcile the installed plugin through the Codex plugin CLI or UI. In Claude Code, you can also run `/hotl:check-update`. For backup behavior, target-specific commands, manual checks, and `--force-codex`, see [Updating HOTL](docs/updating.md).\n\n## Supported Tools\n\n| Tool | Integration |\n| --- | --- |\n| Claude Code | Plugin — commands, skills, hooks, and bundled `code-reviewer` agent |\n| Codex | Plugin install (recommended) or native skill discovery |\n| Cline | Global rules plus local HOTL skill files |\n| Cursor | Adapter templates via `/hotl:setup` |\n| GitHub Copilot | Adapter templates via `/hotl:setup` |\n\n## Automation Templates\n\nHOTL includes optional Codex automation and GitHub Actions review templates in\n[`docs/codex-automations-and-ci.md`](docs/codex-automations-and-ci.md). They are\nnot active by default; copy them into a target project only after testing the\nprompt manually.\n\nContinuous-evaluation templates for Codex project automations and Claude\nDesktop local scheduled tasks live under\n[`automations/continuous-evaluation/`](automations/continuous-evaluation/).\nThey are prompt templates only: installation never registers or enables a\nschedule. Use `scripts/hotl-evaluation-schedule.sh preflight` and approve the\ncampaign, cadence, credentials, capture/retention policy, and budgets before\nnative host enablement.\n\n## Repository Structure\n\n```text\nskills/          HOTL skills (loaded by Skill tool or native discovery)\ncommands/        Claude Code slash command definitions\nhooks/           SessionStart hook for Claude Code\nworkflows/       Workflow templates (feature, bugfix, refactor)\nautomations/      Inert native-host prompt templates; never auto-enabled\ncline/rules/     Global rules for Cline\nadapters/        Templates for AGENTS.md, Cursor, Copilot, and other tools\nscripts/         Utility scripts including document-lint.sh\ndocs/            Published user-facing docs, setup guides, and references\ndocs/contracts/  Output, execution, and governance contracts\ndocs/checklists/ Reusable review heuristics\nruntime/capabilities/ Source-backed host capability catalog\nruntime/contracts/    Portable workflow and receipt JSON schemas\nruntime/drivers/      Generic and experimental host-native execution drivers\n```\n\nRepo-local work-product docs such as `docs/designs/`, `docs/plans/`, `docs/research/`, `docs/reviews/`, and `docs/requirements/` are intentionally gitignored in this repo so releases only ship end-user documentation.\n\n## Contributing\n\nRun the smoke tests:\n\n```bash\nbats test/smoke.bats\n```\n\nBug reports and feature requests: [github.com/yimwoo/hotl-plugin/issues](https://github.com/yimwoo/hotl-plugin/issues)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyimwoo%2Fhotl-plugin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyimwoo%2Fhotl-plugin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyimwoo%2Fhotl-plugin/lists"}