{"id":46905462,"url":"https://github.com/yimwoo/hotl-plugin","last_synced_at":"2026-04-01T18:18:36.329Z","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-03-26T07:36:34.000Z","size":345,"stargazers_count":13,"open_issues_count":0,"forks_count":2,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-26T20:49:48.532Z","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":null,"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":null,"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-03-26T07:36:37.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":36,"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":31290808,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T13:12:26.723Z","status":"ssl_error","status_checked_at":"2026-04-01T13:12:25.102Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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-04-01T18:18:36.317Z","avatar_url":"https://github.com/yimwoo.png","language":"Shell","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 adds design, planning, review, and verification guardrails so AI-generated changes do not land without evidence.\n\nUse HOTL when you want a structured AI development workflow: brainstorm before coding, write a plan before implementation, review risky changes, and verify results before claiming success.\n\nWorks with **Claude Code**, **Codex**, and **Cline**. Adapter templates are also available for Cursor and GitHub Copilot.\n\n## Table of Contents\n\n- [Why HOTL](#why-hotl)\n- [Quick Start](#quick-start)\n- [How It Works](#how-it-works)\n- [When To Use It](#smart-task-routing)\n- [Commands \u0026 Usage](#commands--usage)\n- [Skills Overview](#skills-overview)\n- [Updating](#updating)\n- [Supported Tools](#supported-tools)\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\n### Claude Code\n\n```text\n/plugin marketplace add yimwoo/hotl-plugin\n/plugin install hotl@hotl-plugin\n```\n\n### Codex\n\n```bash\ngit clone https://github.com/yimwoo/hotl-plugin /tmp/hotl-plugin\nbash /tmp/hotl-plugin/install.sh --codex-plugin\n```\n\nAfter install, restart Codex, switch the plugin directory to **Local Plugins**, and click **Add to Codex** for HOTL.\n\nFor native skills install (local dev, older Codex): clone to `~/.codex/hotl` + symlink to `~/.agents/skills/hotl`.\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\nFor native skills installs, `~/.codex/hotl` is the stable channel and should track `origin/main`. Restart Codex after install. 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## How It Works\n\nImplementation tasks follow seven phases:\n\n| Phase | What happens |\n| --- | --- |\n| **Brainstorm** | Clarify requirements. Compare approaches. Define intent, verification, and governance contracts. |\n| **Plan** | Generate a `hotl-workflow-\u003cslug\u003e.md` with steps, verification, loop conditions, and gates. |\n| **Lint** | Self-check built into planning. Structural lint runs automatically in execution preflight. |\n| **Branch** | Create an isolated git branch. Dirty repos hard-fail. |\n| **Execute** | Run the plan in loop, manual, or subagent mode. |\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\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, plan, execute, verify |\n\n## Commands \u0026 Usage\n\n### Claude Code\n\n| Command | What it does |\n| --- | --- |\n| `/hotl:brainstorm` | Design the change before coding |\n| `/hotl:write-plan` | Create a `hotl-workflow-\u003cslug\u003e.md` |\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, and create executable workflow plans |\n| Execution | `loop-execution`, `executing-plans`, `subagent-execution`, `resuming`, `dispatch-agents` | Run workflows with verification, retries, persistence, and delegation |\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` | Apply test-first development and structured debugging 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? 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. In Claude Code, you can also run `/hotl:check-update`. For backup behavior, 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, and hooks |\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## 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)\ncline/rules/     Global rules for Cline\nadapters/        Templates for AGENTS.md, Cursor, Copilot, and other tools\nscripts/         Utility scripts including document-lint.sh\ndocs/            Setup docs, workflow format reference, and detailed guides\ndocs/contracts/  Output contracts (PR review, code review, execution report)\ndocs/checklists/ Reusable review heuristics\n```\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","funding_links":[],"categories":[],"sub_categories":[],"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"}