{"id":51276647,"url":"https://github.com/fhajjej-ship-it/loop-it","last_synced_at":"2026-06-29T21:03:21.784Z","repository":{"id":366121444,"uuid":"1274926508","full_name":"fhajjej-ship-it/loop-it","owner":"fhajjej-ship-it","description":"Set bounded, verifiable coding loops for Codex, Claude Code, Cursor, and SKILL.md-compatible agents.","archived":false,"fork":false,"pushed_at":"2026-06-20T10:51:07.000Z","size":52,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-20T11:25:40.333Z","etag":null,"topics":["agent-skills","ai-agents","claude-code","codex","cursor","developer-workflow"],"latest_commit_sha":null,"homepage":"https://swarmixai.com/experiments/loop-it-poc","language":"JavaScript","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/fhajjej-ship-it.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","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-06-20T03:38:04.000Z","updated_at":"2026-06-20T10:51:11.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/fhajjej-ship-it/loop-it","commit_stats":null,"previous_names":["fhajjej-ship-it/loop-it"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/fhajjej-ship-it/loop-it","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fhajjej-ship-it%2Floop-it","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fhajjej-ship-it%2Floop-it/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fhajjej-ship-it%2Floop-it/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fhajjej-ship-it%2Floop-it/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fhajjej-ship-it","download_url":"https://codeload.github.com/fhajjej-ship-it/loop-it/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fhajjej-ship-it%2Floop-it/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34942665,"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-06-29T02:00:05.398Z","response_time":58,"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-skills","ai-agents","claude-code","codex","cursor","developer-workflow"],"created_at":"2026-06-29T21:03:20.580Z","updated_at":"2026-06-29T21:03:21.775Z","avatar_url":"https://github.com/fhajjej-ship-it.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"skills/loop-it/assets/loop-it-logo-black.svg\" alt=\"Loop it\" width=\"120\" /\u003e\n\u003c/p\u003e\n\n# Loop it\n\n[![Release](https://img.shields.io/github/v/release/fhajjej-ship-it/loop-it?label=release)](https://github.com/fhajjej-ship-it/loop-it/releases)\n[![Check](https://github.com/fhajjej-ship-it/loop-it/actions/workflows/check.yml/badge.svg)](https://github.com/fhajjej-ship-it/loop-it/actions/workflows/check.yml)\n[![License: MIT](https://img.shields.io/badge/license-MIT-111111.svg)](LICENSE)\n[![Node \u003e=18](https://img.shields.io/badge/node-%3E%3D18-111111.svg)](package.json)\n[![npm package](https://img.shields.io/badge/npm-%40fhajjej%2Floop--it-111111.svg)](https://www.npmjs.com/package/@fhajjej/loop-it)\n\nLoop it is a portable loop writer, library, launcher, and Agent Skill for turning coding goals into verifier-gated loops for Codex, Claude Code, Cursor, and other tools that understand `SKILL.md`.\n\nIt turns a vague instruction like \"keep fixing it\" into a useful loop: write the loop contract, choose a proven pattern from the library when one fits, launch it in the right agent, track evidence, then stop when the verifier passes or the budget is spent.\n\nProduct page: https://swarmixai.com/experiments/loop-it-poc\n\n## What Is Inside\n\n- `skills/loop-it/SKILL.md`: the canonical portable skill.\n- `bin/loop-it.mjs`: installer, loop writer, loop launcher, and loop-file helper.\n- `skills/loop-it/references/library/loops.json`: bundled loop library.\n- `skills/loop-it/scripts/select-loop.mjs`: zero-dependency loop selector and recommender.\n- `skills/loop-it/scripts/start-loop.mjs`: zero-dependency goal/verifier launcher.\n- `skills/loop-it/references/loop-template.md`: durable loop state template.\n- `skills/loop-it/scripts/create-loop.mjs`: zero-dependency loop contract generator.\n- `.codex-plugin/plugin.json`: Codex plugin metadata.\n- `.claude-plugin/plugin.json`: Claude Code plugin metadata.\n- `.cursor-plugin/plugin.json`: Cursor plugin metadata.\n- `tests/smoke-install.mjs`: installer and packed-package smoke test.\n\n## Quickstart\n\nRun the install command from the project where you want Loop it available:\n\nCurrent public install:\n\n```bash\nnpx @fhajjej/loop-it@latest install --agent all --scope project\n```\n\nIf you are following an example that says `cd /path/to/your-project`, replace that placeholder with a real project folder on your machine. You can also stay anywhere and pass the project explicitly:\n\n```bash\nnpx @fhajjej/loop-it@latest install --agent all --scope project --cwd /real/path/to/your-project\n```\n\nGitHub install:\n\n```bash\ngit clone https://github.com/fhajjej-ship-it/loop-it.git\ncd loop-it\nnode ./bin/loop-it.mjs install --agent all --scope project\n```\n\nThat copies the skill into:\n\n| Agent | Install path | Invoke with |\n| --- | --- | --- |\n| Codex | `.agents/skills/loop-it/` | `Use $loop-it` |\n| Claude Code | `.claude/skills/loop-it/` | `/loop-it` |\n| Cursor | `.cursor/skills/loop-it/` | `/loop-it` |\n\nFor a global install:\n\n```bash\nnpx @fhajjej/loop-it@latest install --agent all --scope global\n```\n\nSee [docs/install.md](docs/install.md) for host paths, global install notes, and verification steps.\n\n## Write, Choose, Launch\n\nLoop it has three product verbs:\n\n1. **Write** a verifier-gated loop when you know the goal and check.\n2. **Choose** a proven loop from the bundled library when you want a starter pattern.\n3. **Launch** the loop into Codex, Claude Code, or Cursor with the right host prompt.\n\nWrite a custom loop:\n\n```bash\nnpx @fhajjej/loop-it@latest write \\\n  --goal \"Fix failing checkout tests\" \\\n  --check \"npm test -- checkout\" \\\n  --max-iterations 5\n```\n\nChoose from the library:\n\n```bash\nnpx @fhajjej/loop-it@latest recommend --goal \"fix failing CI\"\nnpx @fhajjej/loop-it@latest write --from failing-ci-repair --goal \"Fix failing CI\" --check \"npm run check\"\n```\n\n## Start A Loop\n\nFor finish-line work, start with the verifier gate. `start` writes `.loop-it/LOOP.md`, `.loop-it/progress.json`, and `.loop-it/LAUNCH.md`, then prints the host-specific launch prompt.\n\n```bash\nnpx @fhajjej/loop-it@latest start \\\n  --goal \"Fix failing checkout tests\" \\\n  --check \"npm test -- checkout\" \\\n  --max-iterations 5 \\\n  --agent codex\n```\n\nUse `--agent claude` for Claude Code, `--agent cursor` for Cursor, or `--agent all` to generate every host prompt.\n\n## Four-Step Workflow\n\nLoop it is meant to answer four questions in order:\n\n1. What is the goal?\n2. What verifier rejects bad output?\n3. Does a library loop already fit?\n4. Which host should launch the loop?\n\n```bash\nnpx @fhajjej/loop-it@latest start --goal \"fix failing checkout test\" --check \"npm test -- checkout\" --agent all\nnpx @fhajjej/loop-it@latest next --cwd .\n```\n\n`next` continues an active loop when progress is still open. When progress is complete, stopped, or blocked, it uses the recorded evidence to recommend the next loop.\n\n## First Loop\n\nCodex example:\n\n```bash\nnpx @fhajjej/loop-it@latest start \\\n  --goal \"Fix the failing checkout test without unrelated refactors\" \\\n  --check \"npm test -- checkout\" \\\n  --max-iterations 3 \\\n  --agent codex\n```\n\nPaste the generated Codex launch prompt. It uses `/goal` when available and falls back to the portable `.loop-it` contract when native goals are unavailable.\n\nMore examples: [docs/examples.md](docs/examples.md).\n\n## Loop Library\n\nThe library is still useful, but it is no longer the product center. Use it to pick a proven loop shape, then launch with a concrete goal and verifier.\n\n```bash\nnpx @fhajjej/loop-it@latest library list\nnpx @fhajjej/loop-it@latest library search \"failing ci\"\nnpx @fhajjej/loop-it@latest recommend --goal \"fix failing checkout test\"\nnpx @fhajjej/loop-it@latest next --cwd .\n```\n\nCreate a loop from the bundled library:\n\n```bash\nnpx @fhajjej/loop-it@latest new --from failing-ci-repair\nnpx @fhajjej/loop-it@latest start --from failing-ci-repair --goal \"Fix failing CI\" --check \"npm run check\"\n```\n\nLibrary-backed loops create `.loop-it/LOOP.md` and `.loop-it/progress.json` so the agent can decide whether to continue the current loop or recommend the next one.\n\nThe bundled catalog currently includes 13 local-first loops:\n\n| Loop | Category | Best for |\n| --- | --- | --- |\n| `ticket-to-verified-fix` | engineering | Turn a bug report or small defect into the smallest patch with proof. |\n| `failing-ci-repair` | engineering | Repair a failing build, lint, type-check, or test job with the smallest verified change. |\n| `docs-sweep` | content | Find and fix stale setup, API, command, or workflow documentation. |\n| `review-repair` | operations | Address blocking review findings until the diff is ready to ship. |\n| `release-readiness` | operations | Prepare a package, app, or feature for a public release with evidence. |\n| `fresh-setup` | engineering | Validate a clean checkout or clean project setup and repair hidden assumptions. |\n| `test-coverage-gap` | evaluation | Add focused tests around risky behavior without broad test churn. |\n| `ux-polish` | product | Improve a specific user flow for clarity, responsiveness, and accessibility. |\n| `performance-measurement` | engineering | Improve speed, memory, bundle size, or latency using before-and-after evidence. |\n| `dependency-upgrade` | engineering | Upgrade one dependency or toolchain surface with compatibility proof. |\n| `security-hardening` | security | Reduce a concrete security risk with scoped evidence and approval gates. |\n| `refactor-containment` | engineering | Refactor a narrow area while proving behavior stays the same. |\n| `product-evaluation` | evaluation | Run realistic scenarios, repair misses, and prove the flow meets a quality bar. |\n\n## Good Loop Contract\n\nEvery useful loop needs:\n\n- Objective: the concrete outcome, not a theme.\n- Scope: repository, files, feature area, data source, or environment.\n- Verifier gate: command, benchmark, manual inspection, review criterion, or measurable threshold that can reject bad output.\n- Iteration cap: maximum passes or time budget.\n- Stop conditions: success, repeated failure, blocked access, unsafe action, or approval requirement.\n- Evidence: changed files, verification output, residual risk, and the next decision.\n- Approval gates: production writes, external messages, payments, destructive git operations, credentials, deploys, or irreversible data changes.\n\nCreate a durable loop file:\n\n```bash\nnpx @fhajjej/loop-it@latest new \\\n  --name \"Docs sweep\" \\\n  --objective \"Find and update stale setup documentation\" \\\n  --check \"run the documented setup commands from a clean checkout\" \\\n  --max-iterations 3\n```\n\nThis creates `.loop-it/LOOP.md` and `.loop-it/progress.json` in the current directory.\n\n## Host Notes\n\n- [Codex](docs/hosts/codex.md)\n- [Claude Code](docs/hosts/claude-code.md)\n- [Cursor](docs/hosts/cursor.md)\n\n## Review Pack\n\n- [Reviewer FAQ](docs/reviewer-faq.md)\n- [Marketplace checklist](docs/marketplace-checklist.md)\n- [Release checklist](RELEASE.md)\n- [Changelog](CHANGELOG.md)\n- [Security policy](SECURITY.md)\n- [Contributing guide](CONTRIBUTING.md)\n\n## CLI\n\n```bash\nnpm run check\nnpm run smoke\nnpm publish --dry-run --access public\nnode ./bin/loop-it.mjs install --agent all --scope project\nnode ./bin/loop-it.mjs write --goal \"Fix failing CI\" --check \"npm run check\"\nnode ./bin/loop-it.mjs start --goal \"Fix failing CI\" --check \"npm run check\" --agent all\nnode ./bin/loop-it.mjs library search \"release readiness\"\nnode ./bin/loop-it.mjs recommend --goal \"fix failing CI\"\nnode ./bin/loop-it.mjs new --name \"Release readiness\" --objective \"Prepare public release\" --check \"npm run check\"\n```\n\n`npm run check` verifies CLI syntax, selector syntax, skill generator syntax, loop launcher syntax, plugin metadata JSON, Codex/Claude/Cursor installs, library selection, loop-file creation, loop launch creation, packed-tarball execution, and package contents.\n\n## Release Status\n\nLoop it is published as the scoped npm package `@fhajjej/loop-it`.\n\n```bash\nnpx @fhajjej/loop-it@latest install --agent all --scope project\n```\n\n## Version Boundaries\n\nLoop it deliberately avoids hosted accounts, ratings, background scheduling, production automation, multi-agent orchestration, billing, dashboards, and external-message sending. It compiles and launches local verifier-gated loops; host tools provide the actual heartbeat when they support one.\n\n## License\n\nMIT License. See [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffhajjej-ship-it%2Floop-it","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffhajjej-ship-it%2Floop-it","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffhajjej-ship-it%2Floop-it/lists"}