{"id":"c747c131-6572-492c-bc7d-b3ede97ce4bc","slug":"flexx-loop","kind":"skill","name":"fleXX-loop","summary":"Three-skill dev loop (spec, build, review) for Hermes Agent","owner":"Fl3xxRichie","repoUrl":"https://github.com/Fl3xxRichie/fleXX-loop","license":"MIT","licenseTier":"permissive","trust":"community","stars":3,"match":null,"fewStars":true,"format":"skill","createdAt":"2026-07-27T00:56:49.000Z","addedAt":"2026-10-21T23:34:09.899Z","logoUrl":"https://avatars.githubusercontent.com/u/185129287?u=c61b96d3702dad85ee3bf033700b322725a43a0a&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["writing"],"tags":[],"runtime":"binary","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-22T02:33:30.637Z","sample":false,"url":"https://conduits.dev/tools/flexx-loop","language":"Shell","transports":["stdio"],"install":{},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# fleXX-loop\n\nA three-skill dev loop for Hermes Agent: **spec -> build -> review**.\n\nEach skill is a self-contained SKILL.md that plugs into Hermes Agent's skill system. Together they form an autonomous development loop where:\n\n1. **flexx-spec** interviews you about a raw idea until the spec is unambiguous, then files a build-ready task\n2. **flexx-build** picks up the next ready task, implements every acceptance criterion, pushes a branch\n3. **flexx-review** audits the branch against its spec, posts a structured verdict\n\nYou stay the gatekeeper. No skill ever merges.\n\n## The contract system\n\nEvery task has:\n- **AC-N** (Acceptance Criteria) - observable, testable outcomes\n- **NG-N** (Non-goals) - what must NOT change\n\nThese IDs flow through all three skills. Spec writes them, build implements them, review checks them. Once filed, IDs never change.\n\n## Task schema\n\n```yaml\n---\nslug: <kebab-case-slug>\nstatus: draft | agent-ready | in-progress | built | blocked | merged\ndepends_on: []\ncreated: <ISO date>\nclaimed_at: <set by build agent when locking>\npriority: normal | high | low\n---\n```\n\n## Task states\n\n| State | Meaning |\n|---|---|\n| `draft` | Spec written, not yet approved for build |\n| `agent-ready` | Flexx marked it ready for the build loop |\n| `in-progress` | Build agent claimed it (lock) |\n| `built` | Build pushed the branch, awaiting review/merge |\n| `blocked` | Build hit an ambiguity, waiting on Flexx |\n| `merged` | Merged to default branch |\n\n## Installation\n\nCopy the three skill directories into your Hermes skills folder:\n\n```bash\ncp -r skills/flexx-spec ~/.hermes/skills/software-development/\ncp -r skills/flexx-build ~/.hermes/skills/software-development/\ncp -r skills/flexx-review ~/.hermes/skills/software-development/\n```\n\nOr install via the Hermes skill management tool:\n\n```\nskill_manage(action='create', name='flexx-spec', content=<SKILL.md content>, category='software-development')\nskill_manage(action='create', name='flexx-build', content=<SKILL.md content>, category='software-development')\nskill_manage(action='create', name='flexx-review', content=<SKILL.md content>, category='software-development')\n```\n\n## How to use\n\n### Manual (with buttons)\n\n1. Tell your agent \"spec this\" and describe your idea -> agent interviews you, drafts the spec\n2. Agent shows a **Mark Agent Ready** button -> you click it, agent files the task as `agent-ready`\n3. Agent shows a **Work Queue** button (if no git hook) -> you click it, build starts\n4. Build implements, pushes branch, **auto-fires review** (no button needed)\n5. Review audits, posts verdict, shows a **Merge** button (if safe to merge) -> you click it, branch merges\n\nYou never edit frontmatter or type commands. The buttons are `clarify` tool calls that work on every surface (desktop, CLI, Telegram, Discord).\n\n### Event-driven (git hooks, fully local, no VPS)\n\nThe loop can run fully autonomously on your local machine using git hooks. No VPS, no gateway, no network dependency.\n\n**Setup:**\n\n```bash\n# Install hooks into any repo where you use fleXX-loop\nbash scripts/setup-hooks.sh /path/to/your/repo\n```\n\nThis installs a `post-commit` hook that detects when a task file flips to `status: agent-ready` and automatically triggers the build agent via `hermes chat -q`.\n\nAfter build pushes the branch, it automatically fires review as a background one-shot.\n\n**Flow:**\n\n```\nYou commit task with status: agent-ready\n    ↓ (post-commit hook fires instantly)\nhermes chat -q triggers flexx-build\n    ↓ (build implements, pushes branch)\nhermes chat -q triggers flexx-review\n    ↓ (review audits, posts verdict to chat)\nYou see the verdict, you merge\n```\n\nYou never type \"work the queue\" or \"review this\". The loop is reactive.\n\n### Cron (polling, for unattended machines)\n\nSet up two cron jobs (spec is interactive only, never cron):\n- **Build**: runs every N hours, picks the next `agent-ready` task, builds it, reports back\n- **Review**: runs after build, reviews unmerged branches, posts verdicts\n\n## Design principles\n\n- **Human is the merge button.** No skill ever merges or enables auto-merge.\n- **Contract first.** AC-N and NG-N IDs are immutable once filed.\n- **One task per pass.** Each cron run does one thing and exits.\n- **Never guess.** If something is ambiguous, the skill blocks and asks.\n- **Scope is binding.** Build only touches ACs. Review flags anything beyond them.\n\n## Requirements\n\n- Hermes Agent (or any agent system that supports SKILL.md skills)\n- Git\n- `gh` CLI (optional, for branch detection)\n\n## License\n\nMIT"}