genie

Genie 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.

The 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.

Install

curl -fsSL https://raw.githubusercontent.com/automagik-dev/genie/main/install.sh | bash

Every 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.

The 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.

Genie ships exactly three surfaces, and nothing else:

1. The signed binary — installed and updated by install.sh and genie update.
2. The skills — delivered by the 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).
3. The Orca plugin — an optional lifecycle integration you register with Orca yourself (see below).

There is no Claude marketplace plugin, no Codex plugin, no Genie-installed hooks, and no role-agent profiles.

--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.

Upgrading 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.

From 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.

Standalone and Orca authority

Genie has two explicit lifecycle modes. standalone is the default, including when the configuration omits orchestration.mode; merely installing or opening Orca never changes authority. Standalone keeps the existing local task, board, and roadmap behavior. Select Orca only when you intend Orca to become the sole lifecycle authority:

genie setup --orchestration-mode orca
genie doctor

The switch first verifies the shipped plugin payload and a compatible Orca runtime (Orca 1.4.192 or newer with orchestration.contract.v1). Only after that probe succeeds does Genie back up its configuration and atomically select Orca. In Orca mode, Genie does not open .genie/genie.db for lifecycle reads or writes and refuses roadmap writes, syncs, and exports before they can create or change local files. Existing local history is preserved in place, but it is not imported, mirrored, or treated as current. The plugin keeps no fallback database: if Orca is unavailable, the operation fails instead of silently returning to standalone.

Switching back is also deliberate and does not import Orca state:

genie setup --orchestration-mode standalone
genie doctor

genie doctor reports the selected authority, plugin ownership state, resolved runtime version, and compatibility. unsupported_environment means the host cannot provide the supported public CLI/child-process boundary; install or start a compatible Orca runtime and repeat the Orca selection. Do not work around it with a private API, internal RPC, terminal injection, or a local fallback.

Installing the plugin in Orca

genie setup --orchestration-mode orca selects Orca as Genie's lifecycle authority. It does not register the Genie plugin with Orca — that is a separate, Orca-side install. Orca accepts exactly two kinds of source:

• a marketplace source: a git repo whose root holds orca-marketplace.json;
• a plugin source: a git repo whose root holds orca-plugin.json, or a local folder containing orca-plugin.json.

The genie repository root can never be the plugin tree. Orca's loader rejects any install tree containing a symlink ("unsafe file path or symlink") and caps an install at 2000 files / 50 MB. This repo has docs -> .docs-vendor/genie, runs to roughly 14,000 files in a dev checkout, and keeps its manifest nested at plugins/genie/orca-plugin.json, which a git plugin source never looks at. So the plugin is published as a tree-only git ref whose root is plugins/genie — symlink-free, ~132 files, ~1.3 MB:

.github/workflows/orca-plugin-ref.yml republishes those refs: every push to main that touches plugins/genie force-pushes a parentless commit carrying that subtree to refs/heads/orca-plugin, and every such push to dev does the same to refs/heads/orca-plugin-dev. They are tree-only by design — no history, no shared ancestry with main, never merged back. Orca pins the commit it fetched, so a republish cannot retroactively change an existing install.

The repo root carries only orca-marketplace.json, a source-only index no release tarball contains. scripts/orca-manifest-parity.test.ts fails the build if the index drifts from the plugin's identity, or if plugins/genie ever grows a symlink or crosses Orca's file cap.

Install, update, rollback, and uninstall

Signed release tarballs include plugins/genie/orca-plugin.json and the compiled Orca entrypoint on every supported platform. The normal installer stages and verifies that payload; authority remains standalone until the explicit setup command above. genie update preserves the selected mode and lifecycle history, verifies the replacement payload, and refreshes a prior Genie ownership claim only after an Orca compatibility probe. Run genie doctor after installation or update before resuming lifecycle mutations.

genie update --rollback checks the retained rollback state and prints signed-version reinstall guidance when a safe in-place rollback is unavailable; follow that guidance, then run genie doctor. A failed update, rollback, or mode preflight leaves the prior configuration and authority unchanged. genie uninstall removes only ownership-proven Genie artifacts and registrations. Modified or unproven files are preserved, and neither local Genie history nor Orca records are deleted. Review the command's backup/recovery output before removing any retained files manually.

Ambiguous Orca receipts and recovery

The plugin invokes only a closed subset of official orca orchestration ... --json commands. Successful mutations require a bounded receipt and, where the public CLI supports it, an immediate public read-back. If the process times out, exceeds its output cap, or loses transport after launch without a complete identifying receipt, Genie reports ambiguous_after_possible_commit. Do not automatically retry: Orca may already have committed the operation. Inspect the exact public read operation named by the error only when the identifier was known before launch; otherwise confirm the outcome with an Orca operator before deciding whether to issue a new mutation. Genie never guesses an identifier from a collection or infers success from a partial response.

MCP retirement

The legacy Genie MCP server is retired. genie mcp exits non-zero with a stable diagnostic and never starts a server; use the standalone genie task and genie board commands instead. genie init removes only marker-owned or exact Genie-owned historical project registrations and preserves unrelated or unproven user configuration byte-for-byte. Rollback to a pre-A7 signed release remains the migration escape hatch.

Maintainers should read the public Orca boundary and verb-amendment contract before changing the adapter or its operator guidance.

Quickstart

The 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:

1. /brainstorm or "brainstorm this"   an idea → DESIGN.md → mandatory design review
2. /wish or "turn that into a wish"   accepted DESIGN.md → a scoped WISH.md
3. /review                            mandatory plan review; persist APPROVED or concrete gaps
4. /work                              native role subagents build each approved group
5. /review                            independent implementation review: SHIP, FIX-FIRST, or BLOCKED

Skills 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.

Re-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.

What's inside

• 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.