{"id":50941262,"url":"https://github.com/fhightower/fly-half","last_synced_at":"2026-06-17T15:03:59.735Z","repository":{"id":364583599,"uuid":"1267836536","full_name":"fhightower/fly-half","owner":"fhightower","description":"A system for managing event-driven AI agents. A \"fly half\" is the rugby equivalent of a quarterback responsible for directing the team's attack.","archived":false,"fork":false,"pushed_at":"2026-06-13T15:39:52.000Z","size":84,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-13T17:15:22.858Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","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/fhightower.png","metadata":{"files":{"readme":"README.md","changelog":null,"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},"funding":{"github":"fhightower"}},"created_at":"2026-06-12T22:49:02.000Z","updated_at":"2026-06-13T15:39:56.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/fhightower/fly-half","commit_stats":null,"previous_names":["fhightower/fly-half"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/fhightower/fly-half","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fhightower%2Ffly-half","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fhightower%2Ffly-half/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fhightower%2Ffly-half/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fhightower%2Ffly-half/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fhightower","download_url":"https://codeload.github.com/fhightower/fly-half/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fhightower%2Ffly-half/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34453438,"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-17T02:00:05.408Z","response_time":127,"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":[],"created_at":"2026-06-17T15:03:58.820Z","updated_at":"2026-06-17T15:03:59.730Z","avatar_url":"https://github.com/fhightower.png","language":"JavaScript","funding_links":["https://github.com/sponsors/fhightower"],"categories":[],"sub_categories":[],"readme":"# Fly Half\n\nA simple, file-based system for capturing workflows (\"playbooks\") that AI agents act on, plus a local GUI for creating and managing them.\n\nIn rugby, the fly-half reads the game and decides which play to run. Fly Half does the same for agents: an agent runs on a loop, scans a list of scenarios, and when one matches, executes the corresponding playbook.\n\n## How it works\n\nEverything is plain YAML on disk — agents read the files directly, no database or API required.\n\n```\nwork-directory/\n  scenarios.yaml        # the single file agents scan for triggers\n  playbooks/\n    \u003cname\u003e.yaml         # one file per playbook\n```\n\n### Scenarios\n\n`scenarios.yaml` maps trigger conditions to playbooks. Keeping all triggers in one file means an agent loop only has to scan a single file, not every playbook:\n\n```yaml\nscenarios:\n  - when: There is a ticket in \"In Review\" that's assigned to me\n    then: Review a ticket assigned to me\n    ai_agent_notes:\n      - Only act on tickets assigned to me, not ones I'm just watching.\n  - when: A release is cut\n    then:\n      - Notify the team\n      - Validate release live on prod\n```\n\n- `when` — a natural-language description of the condition, interpreted by the agent\n- `then` — the playbook to run, or a list of playbooks to run in order (a single name is kept as a scalar)\n- `ai_agent_notes` — optional list of free-form guidance strings for the agent (a single string is accepted and normalized to a one-item list)\n\n### Playbooks\n\nA playbook is an ordered list of steps. Each step is a plain-text instruction that can reference other playbooks — playbooks nest and compose, so common procedures are written once and reused:\n\n```yaml\nname: Review a ticket assigned to me\ndescription: Review a ticket that has been assigned to me\nai_agent_notes:\n  - Pass the PR URL/number as args. The skill runs `gh pr view --json title,body,...` + `gh pr diff`.\n  - For config-only diffs the diff alone is not enough — fetch the full surrounding source to validate claims.\n  - Run gh from /tmp.\n\nsteps:\n  - Pull details for the ticket\n  - text: A step can also carry its own notes\n    ai_agent_notes:\n      - Skip this if the ticket has no description\n```\n\nA step is a plain string or `{text, ai_agent_notes}` — `ai_agent_notes` is an optional list of free-form guidance strings for the executing agent (a single string is accepted and normalized to a one-item list).\n\nStep text references other playbooks *inline* with wiki-link syntax:\n\n```yaml\nsteps:\n  - Start a new tmux session with [[start_tmux_agent]] and send it the ticket details\n  - Tell the new tmux agent to [[review_ticket]]\n```\n\nInline `[[refs]]` are first-class: renames rewrite them, deletes warn about them, and missing targets are flagged.\n\nThere is deliberately no distinction between \"playbooks\" and \"actions\" — everything is a playbook, and small reusable ones serve as building blocks for larger ones.\n\n## The GUI\n\n[`fly-half-gui/`](fly-half-gui/) is a local web app for visually creating, editing, and deleting scenarios and playbooks. It reads and writes the same YAML files the agents consume.\n\n```bash\ncd fly-half-gui\nnpm install\nnpm run build\nnode bin/cli.js /path/to/your/project   # serves on http://localhost:4242\n```\n\n`/path/to/your/project` is the **data directory** — where `scenarios.yaml` and `playbooks/` live. It is independent of where the GUI is installed, so you can keep your scenario files anywhere and point the GUI at them:\n\n```bash\nnode /opt/fly-half-gui/bin/cli.js ~/my-agent-workflows\n```\n\nIf omitted, the data directory defaults to the current working directory. Either way, `scenarios.yaml` and `playbooks/` must be siblings under that one directory; missing ones are created on first run.\n\nOther flags:\n\n- `--no-open` — don't auto-open a browser\n- `PORT=\u003cn\u003e` — serve on a different port (default `4242`)\n\nAfter `npm install`, the package also exposes a `fly-half-gui` binary equivalent to `node bin/cli.js`.\n\nFor development, a Vite dev server with API proxy:\n\n```bash\nnpm run dev   # UI on http://localhost:5173, API on :4242\n```\n\nTests run with `npm test`.\n\nFeatures:\n\n- Sidebar library of playbooks with search, plus the scenario list\n- Structured step editor (drag to reorder, `[[ref]]` typeahead with click-through navigation) and an editable YAML source tab, kept in sync\n- Explicit save with dirty indicators; writes are atomic so an agent never reads a half-written file\n- Renaming a playbook automatically updates every reference to it; deleting one warns you about referrers; broken references are flagged with ⚠\n\n## Design principles\n\n- **Files are the source of truth.** Agents and humans share the same plain YAML — diffable, version-controllable, editable by hand, by GUI, or by another agent.\n- **One scan file.** Triggers live in `scenarios.yaml` so the agent loop is cheap.\n- **Natural language where it helps.** Conditions and steps are prose for an LLM to interpret; structure exists only where it buys consistency (references, ordering).\n- **Compose, don't duplicate.** Nested playbook references keep procedures DRY.\n\n## Similar libraries\n\n- **[Agent Events](https://agentevents.io)** — an open format for scheduled and event-driven agent workflows. Each event is a directory package (`EVENT.md` with YAML frontmatter plus optional `scripts/`, `references/`, `skills/`) and the spec defines a taxonomy of eight trigger types (cron, webhooks, state changes, absence, composite, …). Fly Half covers similar ground with a deliberately smaller surface: a single free-text `when` interpreted by the agent, one central scan file instead of per-package discovery, and nested playbook composition. The two could interoperate — a Fly Half scenario + playbook maps fairly naturally onto an `EVENT.md`.\n- **[Anthropic Agent Skills](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/overview)** — markdown skill packages that define *what* an agent can do; Fly Half's scenarios focus on *when* to act and playbooks sequence the steps, so skills can be referenced from playbook steps.\n- **Workflow engines (n8n, Temporal, GitHub Actions)** — deterministic, machine-executed pipelines with explicit triggers. Fly Half targets the opposite end: loosely specified, natural-language procedures executed by an LLM agent that fills in the gaps.\n\n![Fly Half](fly-half.png)\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffhightower%2Ffly-half","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffhightower%2Ffly-half","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffhightower%2Ffly-half/lists"}