{
  "markdown": "<p align=\"center\">\n  <img src=\".github/assets/genie-header.png\" alt=\"Genie\" width=\"800\" />\n</p>\n\n<p align=\"center\"><strong>Wishes in, PRs out.</strong></p>\n\n<p align=\"center\">\n  <a href=\"https://github.com/automagik-dev/genie/releases\"><img alt=\"signed release channels\" src=\"https://img.shields.io/badge/releases-signed%20channels-00D9FF?style=flat-square\" /></a>\n  <a href=\"https://github.com/automagik-dev/genie/stargazers\"><img alt=\"stars\" src=\"https://img.shields.io/github/stars/automagik-dev/genie?style=flat-square&color=00D9FF\" /></a>\n  <a href=\"LICENSE\"><img alt=\"license\" src=\"https://img.shields.io/github/license/automagik-dev/genie?style=flat-square&color=00D9FF\" /></a>\n  <a href=\"https://discord.gg/xcW8c7fF3R\"><img alt=\"discord\" src=\"https://img.shields.io/discord/1095114867012292758?style=flat-square&color=00D9FF&label=discord\" /></a>\n</p>\n\n<br />\n\nGenie is a planning-and-execution layer for AI coding agents. You describe what you want in one sentence; Genie interviews you into a plan, dispatches agents to build it in parallel, reviews the result against acceptance criteria, and hands you something ready to merge.\n\nThe whole thing is a lightweight body: a set of skills, plain-markdown documents in git, and a single per-repo SQLite file. No daemons, no Postgres, nothing resident. A command opens the database, runs one transaction, and exits.\n\n## Install\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/automagik-dev/genie/main/install.sh | bash\n```\n\nEvery release is cosign-signed (keyless OIDC) with SLSA provenance; the installer verifies the binary — via `gh attestation verify`, falling back to `cosign verify-blob` — before it runs.\n\nThe repository-hosted `.well-known/latest.json` and `dev.json` manifests are the authoritative channel pointers. GitHub's `/releases/latest` route and prerelease badge are deliberately not channel authority: a promotion advances only a monotonic manifest and never rewrites already-published assets or channel-significant draft/prerelease/latest metadata.\n\nGenie ships exactly three surfaces, and nothing else:\n\n1. **The signed binary** — installed and updated by `install.sh` and `genie update`.\n2. **The skills** — delivered by the [skills.sh](https://skills.sh) channel. `genie install` and `genie update` run the pinned skills CLI over the tree the signed release put on disk, then record what landed in `~/.genie/skills-install.json`. Without the binary, the same skills install with `npx skills add automagik-dev/genie` (add `-g --all` for every agent home).\n3. **The Orca plugin** — an optional lifecycle integration you register with Orca yourself (see below).\n\nThere is no Claude marketplace plugin, no Codex plugin, no Genie-installed hooks, and no role-agent profiles.\n\n`--integrations auto|codex|claude|all|none` (or `--skip-integrations`) is the consent scope for the skills channel. Any value other than `none` installs to **every** detected agent skill home, because the skills CLI already installs per agent; `none` skips the channel entirely, writes no record, and reports `skills: skipped (consent: none)`. A failed skills install never rolls back the promoted binary — it prints the exact remedy command and sets a non-zero exit code.\n\nUpgrading from a plugin-era release? `genie update` runs a one-shot, backup-first retirement of what that era left on the host — Codex and Claude plugin registrations and caches, the stamped Claude workflow, role-agent TOMLs, managed skill mirrors, Hermes and pi links. Every asset is classified before anything is touched, and only the ones provably Genie-owned and unmodified are removed; modified, unmanaged or ambiguous assets are preserved and reported. Backups land under `~/.genie/state-backups/integration-retirement-<timestamp>/`. The window covers assets written by releases `5.260711.6` or newer; older hosts follow the manual steps in the docs.\n\nFrom inside a trusted initialized repo, run `genie init` to scaffold state and retire proven-owned historical MCP routes. Then run `genie doctor` to confirm the install: it reports one `skills: <agent> <present>/<total> @ <ref>` line per known agent skill home, `not detected` for a home this host does not have, and a warning naming `genie update` when skills are missing or older than the running binary.\n\n## Standalone and Orca authority\n\nGenie has two explicit lifecycle modes. `standalone` is the default, including when the configuration omits\n`orchestration.mode`; merely installing or opening Orca never changes authority. Standalone keeps the existing local\ntask, board, and roadmap behavior. Select Orca only when you intend Orca to become the sole lifecycle authority:\n\n```bash\ngenie setup --orchestration-mode orca\ngenie doctor\n```\n\nThe switch first verifies the shipped plugin payload and a compatible Orca runtime (Orca `1.4.192` or newer with\n`orchestration.contract.v1`). Only after that probe succeeds does Genie back up its configuration and atomically select\nOrca. In Orca mode, Genie does not open `.genie/genie.db` for lifecycle reads or writes and refuses roadmap writes,\nsyncs, and exports before they can create or change local files. Existing local history is preserved in place, but it is\nnot imported, mirrored, or treated as current. The plugin keeps no fallback database: if Orca is unavailable, the\noperation fails instead of silently returning to standalone.\n\nSwitching back is also deliberate and does not import Orca state:\n\n```bash\ngenie setup --orchestration-mode standalone\ngenie doctor\n```\n\n`genie doctor` reports the selected authority, plugin ownership state, resolved runtime version, and compatibility.\n`unsupported_environment` means the host cannot provide the supported public CLI/child-process boundary; install or\nstart a compatible Orca runtime and repeat the Orca selection. Do not work around it with a private API, internal RPC,\nterminal injection, or a local fallback.\n\n### Installing the plugin in Orca\n\n`genie setup --orchestration-mode orca` selects Orca as Genie's lifecycle authority. It does **not** register the Genie\nplugin with Orca — that is a separate, Orca-side install. Orca accepts exactly two kinds of source:\n\n- a **marketplace source**: a git repo whose *root* holds `orca-marketplace.json`;\n- a **plugin source**: a git repo whose *root* holds `orca-plugin.json`, or a local folder containing `orca-plugin.json`.\n\n**The genie repository root can never be the plugin tree.** Orca's loader rejects any install tree containing a symlink\n(\"unsafe file path or symlink\") and caps an install at 2000 files / 50 MB. This repo has `docs -> .docs-vendor/genie`,\nruns to roughly 14,000 files in a dev checkout, and keeps its manifest nested at `plugins/genie/orca-plugin.json`, which\na git plugin source never looks at. So the plugin is published as a **tree-only git ref whose root *is*\n`plugins/genie`** — symlink-free, ~132 files, ~1.3 MB:\n\n| Route | What to give Orca |\n|-------|-------------------|\n| Marketplace source | `https://github.com/automagik-dev/genie.git`, ref `main` — the index; the plugin itself resolves to ref `orca-plugin` |\n| Plugin git source | `https://github.com/automagik-dev/genie.git`, ref `orca-plugin` (stable) or `orca-plugin-dev` (pre-release) |\n| Local folder | `~/.genie/plugins/genie` (what `genie install`/`genie update` ships) |\n\n`.github/workflows/orca-plugin-ref.yml` republishes those refs: every push to `main` that touches `plugins/genie`\nforce-pushes a parentless commit carrying that subtree to `refs/heads/orca-plugin`, and every such push to `dev` does the\nsame to `refs/heads/orca-plugin-dev`. They are tree-only by design — no history, no shared ancestry with `main`, never\nmerged back. Orca pins the commit it fetched, so a republish cannot retroactively change an existing install.\n\nThe repo root carries only `orca-marketplace.json`, a source-only index no release tarball contains.\n`scripts/orca-manifest-parity.test.ts` fails the build if the index drifts from the plugin's identity, or if\n`plugins/genie` ever grows a symlink or crosses Orca's file cap.\n\n### Install, update, rollback, and uninstall\n\nSigned release tarballs include `plugins/genie/orca-plugin.json` and the compiled Orca entrypoint on every supported\nplatform. The normal installer stages and verifies that payload; authority remains standalone until the explicit setup\ncommand above. `genie update` preserves the selected mode and lifecycle history, verifies the replacement payload, and\nrefreshes a prior Genie ownership claim only after an Orca compatibility probe. Run `genie doctor` after installation or\nupdate before resuming lifecycle mutations.\n\n`genie update --rollback` checks the retained rollback state and prints signed-version reinstall guidance when a safe\nin-place rollback is unavailable; follow that guidance, then run `genie doctor`. A failed update, rollback, or mode\npreflight leaves the prior configuration and authority unchanged. `genie uninstall` removes only ownership-proven Genie\nartifacts and registrations. Modified or unproven files are preserved, and neither local Genie history nor Orca records\nare deleted. Review the command's backup/recovery output before removing any retained files manually.\n\n### Ambiguous Orca receipts and recovery\n\nThe plugin invokes only a closed subset of official `orca orchestration ... --json` commands. Successful mutations\nrequire a bounded receipt and, where the public CLI supports it, an immediate public read-back. If the process times out,\nexceeds its output cap, or loses transport after launch without a complete identifying receipt, Genie reports\n`ambiguous_after_possible_commit`. Do not automatically retry: Orca may already have committed the operation. Inspect\nthe exact public read operation named by the error only when the identifier was known before launch; otherwise confirm\nthe outcome with an Orca operator before deciding whether to issue a new mutation. Genie never guesses an identifier\nfrom a collection or infers success from a partial response.\n\n### MCP retirement\n\nThe legacy Genie MCP server is retired. `genie mcp` exits non-zero with a stable diagnostic and never starts a server;\nuse the standalone `genie task` and `genie board` commands instead. `genie init` removes only marker-owned or exact\nGenie-owned historical project registrations and preserves unrelated or unproven user configuration byte-for-byte.\nRollback to a pre-A7 signed release remains the migration escape hatch.\n\nMaintainers should read the [public Orca boundary and verb-amendment contract](plugins/genie/references/orca-orchestration.md)\nbefore changing the adapter or its operator guidance.\n\n## Quickstart\n\nThe lifecycle is shared by every agent the skills channel reaches. Claude Code invokes a skill as a slash command; Codex and the rest invoke it by name or in plain language:\n\n```text\n1. /brainstorm or \"brainstorm this\"   an idea → DESIGN.md → mandatory design review\n2. /wish or \"turn that into a wish\"   accepted DESIGN.md → a scoped WISH.md\n3. /review                            mandatory plan review; persist APPROVED or concrete gaps\n4. /work                              native role subagents build each approved group\n5. /review                            independent implementation review: SHIP, FIX-FIRST, or BLOCKED\n```\n\nSkills are discovered from the agent's own global skills home, so there is no owner-qualified selector and no plugin tier to disambiguate against. The starter cards shipped inside each skill stay selector-free for the same reason.\n\nRe-run `genie board` any time for a current snapshot of task state on the kanban. The plan documents land in git as you go; the operational state lives in `.genie/genie.db`.\n\n## What's inside\n\n- **Skills** carry the methodology — `brainstorm → design review → wish → plan review → work → implementation review`, authored once in runtime-neutral form and delivered to every agent skill home.\n- **Documents in git.** Wishes, designs, and brainstorms are plain markdown under `.genie/wishes/<slug>/` and `.genie/brainstorms/<slug>/`; you diff, review, and version them like any other code.\n- **One file of state.** Tasks, boards, dependency edges, and wish-group execution state live in a single per-repo SQLite file (`.genie/genie.db`), on Bun's built-in engine.\n- **Small.** 15 CLI commands, 4 runtime dependencies (`@inquirer/prompts`, `commander`, `zod`, `nats`) — `nats` initializes only when the omni runner starts. A ~0.9 MB single-file bundle. Bun-powered.\n- **Spawn-context contract.** `genie context --wish <slug> [--group g] [--plan]` emits one line of versioned JSON — composed branch + resolved base SHA + ready tasks — that a spawn consumes. `--plan` previews the same payload without side effects; the wishless form resolves the repo's integration branch for plain spawns.\n- **Zero daemons, no Postgres.** Nothing runs in the background between invocations.\n\n## Commands\n\n```bash\ngenie --help\n```\n\n| Command | What it does |\n|---------|-------------|\n| `genie init` | Scaffold per-repo state and retire proven Genie-owned project MCP registrations |\n| `genie context` | Resolve spawn context — wish/group branch + base SHA, or the integration branch (versioned JSON; `--plan` previews) |\n| `genie board` | Kanban view of task state, derived live by query |\n| `genie idea` | Capture an idea into the roadmap board Idea lane (creates the board if absent) |\n| `genie task` | Inspect and drive task state (SQLite, zero-daemon) |\n| `genie ui-bridge` | Return the stable non-zero UI-bridge-retirement diagnostic |\n| `genie install` | Finish a verified install and converge the skills channel under the recorded consent scope |\n| `genie mcp` | Return the stable non-zero MCP-retirement diagnostic |\n| `genie omni` | Bridge agents to WhatsApp via Omni — remote approvals + inbound one-shots (`serve`, `status`, `inbox`, `handshake`) |\n| `genie setup` | Configure Genie; `setup --orchestration-mode` selects the lifecycle authority |\n| `genie doctor` | Run diagnostic checks on the installation |\n| `genie shortcuts` | Manage terminal keyboard shortcuts |\n| `genie update` | Update Genie to the latest GitHub release |\n| `genie uninstall` | Remove Genie, the recorded skills install, and plugin-era leftovers proven to be Genie-owned |\n| `genie help` | Show help for any command |\n\n## Skills\n\nSkills are the product. Invoke them as `/name` in Claude Code, or by name or plain language in Codex and every other agent that reads the shared skills home:\n\n| Skill | What it does |\n|-------|-------------|\n| `brainstorm` | Explore a vague idea until it's a concrete DESIGN.md |\n| `wish` | Turn a design into a scoped WISH.md with execution groups |\n| `work` | Dispatch native role subagents wave by wave |\n| `review` | Severity-gated verdict — SHIP, FIX-FIRST, or BLOCKED |\n| `council` | Independent architecture, delivery, product, security, and dissent assessment |\n\nShared skill bodies use a runtime-neutral delegation contract: they name portable roles and let each runtime map them onto its own native subagents. Genie installs no custom agent profiles. Subagents share a workspace, so task claims own scope; worktree isolation, when required, is orchestrator-arranged per the dispatch contract. The engineer reports completion, an independent reviewer returns a verdict, and only the orchestrator runs `genie task done`. `/level-up` remains Claude-only because it evaluates Claude Code mastery.\n\n### Where the skills land\n\n`genie install` and `genie update` run the pinned skills.sh CLI over the delivered tree under `~/.genie/skills`,\nnever over a GitHub ref — the signed tarball's own bytes are the only source genuinely pinned to your binary. The\npublic `npx skills add automagik-dev/genie` command serves the repository's default branch instead, so it can be\nahead of or behind any release.\n\nEvery known agent skill home gets a copy:\n\n| Agent | Skill home |\n|-------|------------|\n| Claude Code | `~/.claude/skills` |\n| Codex (and every other agent reading the shared home) | `~/.agents/skills` |\n| Goose | `~/.config/goose/skills` |\n| Windsurf | `~/.codeium/windsurf/skills` |\n\nCodex reads the shared `~/.agents/skills` home; the skills CLI creates no `~/.codex/skills`. A skill directory a\ndifferent tool already owned is backed up before it is overwritten, and the backup location is reported.\n\nAfter a zero-exit install, Genie records `~/.genie/skills-install.json` — the release tag, the pinned CLI version,\nthe skill inventory, every agent directory the install actually wrote (a bounded scan of your home, not a fixed\ntable), a content digest per directory, and any collisions it backed up. That record is what `genie doctor` reads\nfor its `skills:` lines and what `genie uninstall` proves against before it deletes anything: a directory whose\ndigest no longer matches is preserved and reported, never removed.\n\n### Verifying and removing\n\n```bash\ngenie doctor      # one skills: <agent> <present>/<total> @ <ref> line per known home\ngenie uninstall   # removes the recorded install, then the binary\n```\n\n`genie doctor` never repairs this surface — not even with `--fix`. `genie update` owns every mutation. `genie\nuninstall` deletes only the recorded skill directories it can still prove are Genie's, leaves skills you installed\nyourself in place, and does not restore a foreign directory a previous install overwrote (the backup it took is\nyours to restore).\n\n## How it works\n\nDocuments live in git; operational state lives in one SQLite file. `work` fans agents out through the active client's native subagents — each gets a task claim, with state changes serialized through `genie.db` rather than a coordinator. Review runs as a separate subagent from the one that wrote the code (reviewer ≠ engineer), so the verdict is independent evidence against the wish criteria.\n\nAll linked worktrees of a repository share one `genie.db`, resolved from the git common directory, so a task created in one worktree is immediately visible in another with no sync step.\n\n## Omni (WhatsApp bridge)\n\n`genie omni` wires a running agent to WhatsApp through an [Omni](https://automagik.dev) hub, so you can drive approvals and short tasks from your phone.\n\n**How it works** (verified by the test suite against a fake transport; the live WhatsApp round-trip is a documented manual-QA step — see `.genie/wishes/omni-runner-port/qa.md`):\n\n- **Remote approvals.** `genie omni serve` bridges a chat to the global approval queue: reply `y`/`n` (or `sim`/`nao`), or react 👍/👎. The feature is off by default and the queue is now driven by CLI-originated approvals only — Genie no longer installs the in-session permission hook, so an agent's own permission prompt is not approvable from a chat.\n- **Inbound one-shots.** Each mapped chat selects `agent: claude|codex`. Codex JSONL thread ids persist per provider/instance/chat and resume on later messages. Unmapped chats are stored, not answered.\n\n**What it needs:**\n\n- An **Omni hub** plus a connected **WhatsApp instance** — Genie speaks to Omni over NATS; the hub owns the WhatsApp session.\n- `genie omni handshake` once per host — registers an ed25519 keypair so outbound sends are signed.\n- `genie omni serve` running as the one resident process. It is the *only* NATS client — `--help`, `task`, `board`, and every other command stay transport-free (`nats` never initializes on those paths).\n\n## MCP retirement\n\nThe legacy cross-client MCP server, its write tools, plugin launchers, and Genie-owned registrations are retired.\n`genie mcp` prints `Error: genie mcp has been retired; use \\`genie task\\` and \\`genie board\\`, or roll back to a\npre-A7 signed release.` to stderr and exits 1 without reading or speaking MCP. `genie init` removes only historical\nregistrations proven to be Genie-owned; unowned same-name routes and every unrelated config key remain untouched.\n\nThe UI-owned `genie ui-bridge` is retired on the same terms: there is no separate Genie UI any more, the Orca\nintegration is the supported UI surface, and the private stdio transport, tool registry, and change watcher behind the\nbridge are deleted. `genie ui-bridge` prints `Error: genie ui-bridge has been retired; the Orca integration is the\nsupported UI surface, or roll back to a pre-retirement signed release.` to stderr and exits 1. Standalone `genie task`\nand `genie board` retain their existing behavior in standalone mode; Orca mode continues to use the public\n`orca orchestration ... --json` adapter as its sole authority.\n\n## Roadmap\n\nNo dates — direction, not promises:\n\n- **More emit targets.** Continue expanding native clients beyond Claude, Codex, and Hermes.\n- **CDN distribution.** Serve signed releases from a CDN for faster, wider installs.\n\n## Coming from v4?\n\nv4 is preserved on the [`v4` branch](https://github.com/automagik-dev/genie/tree/v4), and its final npm release stays published for existing v4 users — nothing you're running today disappears.\n\nv5 is a deliberate cutover to a lightweight body. The v4 harness — a Postgres backend, pane-based process orchestration, executor registries, the telemetry spine, the full-screen console, and the desktop app — is gone. What remains is the part that always did the work: the skills, the documents, and one SQLite file of state.\n\n---\n\n<p align=\"center\">\n  <a href=\"https://automagik.dev/genie\"><strong>Docs</strong></a> &middot;\n  <a href=\"https://github.com/automagik-dev/genie/releases\"><strong>Releases</strong></a> &middot;\n  <a href=\"https://discord.gg/xcW8c7fF3R\"><strong>Discord</strong></a> &middot;\n  <a href=\"LICENSE\"><strong>MIT License</strong></a>\n</p>\n\n<p align=\"center\"><sub>You describe the problem. Genie does the rest.</sub></p>\n\n> **Channel migration (2026-07):** the `homolog` channel was retired. Configs pinned to `homolog` are migrated to **stable** automatically on next run; `genie update --homolog` no longer exists — use `--stable` or `--dev`.\n",
  "bytes": 21871,
  "sha": "c47d68a7216a31fb6383059bfe5aa7420c164cb6f3126f6dfa5f56bebfdee3cc",
  "repo_slug": "namastexlabs/automagik-genie",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/skl_namastexlabs_automagik_genie_claude_skil_adc8be9e/readme"
}