automagik-dev/genie: a planning layer that turns one sentence into a reviewed PR

The problem genie targets: agents that start coding before the plan exists

Most terminal coding agents take a prompt and begin editing. The prompt is usually underspecified, the acceptance criteria live in the author's head, and the diff arrives before anyone has agreed on what done means. Genie inserts three steps between the sentence and the merge: an interview that turns the sentence into a plan, parallel execution in isolated worktrees, and a review pass against acceptance criteria before you see the code. The README describes the output as "something ready to merge", and the tagline is "Wishes in, PRs out."

It is aimed at engineers who already drive agents from a shell and are tired of writing the same orchestration glue per repository. The repository topics list worktrees, parallel agents, orchestration and context engineering, which matches the shape of the tool rather than a chat product. If your workflow is one agent, one prompt, one diff, the planning and review layers add latency you will not recover.

How genie works: markdown plans, per-repo SQLite, and isolated worktrees

The architecture is deliberately thin. The README calls the whole thing "a lightweight body: a set of skills, plain-markdown documents in git, and a single per-repo SQLite file." There is no daemon and no Postgres. A command opens the database, runs one transaction, and exits. That single-transaction model is the important design constraint: state changes are atomic per invocation, and nothing is resident between commands.

Genie ships exactly three surfaces and, per the README, nothing else. The signed binary is installed and updated by `install.sh` and `genie update`. The skills are delivered by the skills.sh channel, with `genie install` and `genie update` running a pinned skills CLI over the tree the signed release put on disk and recording the result in `~/.genie/skills-install.json`. The Orca plugin is an optional lifecycle integration you register with Orca yourself. The README is explicit that there is no Claude marketplace plugin, no Codex plugin, no Genie-installed hooks, and no role-agent profiles.

Lifecycle authority is a two-mode switch. `standalone` is the default, including when the configuration omits `orchestration.mode`, and it keeps local task, board and roadmap behavior. Orca mode makes Orca the sole lifecycle authority: Genie does not open `.genie/genie.db` for lifecycle reads or writes and refuses roadmap writes, syncs and exports. Existing local history is preserved in place but is not imported, mirrored or treated as current. The plugin keeps no fallback database, so if Orca is unavailable the operation fails instead of silently returning to standalone. That is a real trade-off: you get a single authority and no split-brain state, and you lose the ability to keep working locally when Orca is down.

Installing genie and running a first plan

The README gives one install path. The installer verifies the binary before it runs, using `gh attestation verify` and falling back to `cosign verify-blob`:

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

Every release is cosign-signed with keyless OIDC and carries SLSA provenance, so a failed verification should stop the install rather than leave you with an unverified binary.

From inside a trusted initialized repo, scaffold state with `genie init`, which also retires proven-owned historical MCP routes. Then confirm the install:

genie init
genie doctor

`genie doctor` reports one `skills: <agent> <present>/<total> @ <ref>` line per known agent skill home, prints `not detected` for a home the host does not have, and warns naming `genie update` when skills are missing or older than the running binary. Read those lines before you trust anything else; a stale ref means the skills on disk do not match the binary you are running.

If you want the skills without the binary, the README gives the alternative directly:

npx skills add automagik-dev/genie

Add `-g --all` to target every agent home. The consent scope for the skills channel is `--integrations auto|codex|claude|all|none`, or `--skip-integrations`. 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 remedy command and exits non-zero.

Where genie stops helping: consent scope, retirement and npm

The integration flag is coarser than it looks. Passing `--integrations codex` does not restrict installation to Codex; the README states that any value other than `none` installs to every detected agent skill home. If you wanted to keep one agent's skill directory clean, this flag will not do it.

The upgrade path from the plugin era is backup-first and conservative by design. `genie update` runs a one-shot retirement of Codex and Claude plugin registrations and caches, the stamped Claude workflow, role-agent TOMLs, managed skill mirrors, and Hermes and pi links. Every asset is classified before anything is touched, and only assets 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 must follow manual steps in the docs. If you are on an older host, budget time for that work rather than expecting `genie update` to handle it.

npm is not a distribution channel. The package description states that npm distribution was discontinued on 2026-05-09 and points at the install script. Anyone reaching for `npm install @automagik/genie` is on a dead path. The package version in `package.json` is `5.260901.3` while the most recent release listed is `v5.260915.1`, so the manifest and the release channel are not the same source of truth; treat the repository-hosted `.well-known/latest.json` and `dev.json` manifests as the authoritative channel pointers, which the README says they are.

Orca as lifecycle authority, and why the plugin cannot ship from the repo root

Selecting Orca is a two-command operation:

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. Switching back uses `genie setup --orchestration-mode standalone` and does not import Orca state. `genie doctor` reports the selected authority, plugin ownership state, resolved runtime version and compatibility. An `unsupported_environment` result means the host cannot provide the supported public CLI or child-process boundary; the README tells you to install or start a compatible Orca runtime and repeat the selection, and explicitly not to work around it with a private API, internal RPC, terminal injection or a local fallback.

The plugin packaging constraint is the most concrete limitation in the documentation. Orca accepts either a marketplace source (a git repo whose root holds `orca-marketplace.json`) or a plugin source (a git repo whose root holds `orca-plugin.json`, or a local folder containing it). The genie repository root can never be the plugin tree. Orca's loader rejects any install tree containing a symlink, and caps an install at 2000 files and 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. The plugin is therefore published as a tree-only git ref whose root is `plugins/genie`: symlink-free, about 132 files and 1.3 MB. If you maintain a fork, that packaging rule is the first thing that will break your Orca install.

genie versus running Claude Code with hand-written worktree scripts

The obvious alternative is doing this yourself: a shell script that creates a git worktree per task, launches your coding agent of choice in each, and opens a PR when the branch passes tests. That approach has one advantage Genie does not: you control every step and there is no schema to migrate. It also has the failure mode Genie exists to remove, which is that the plan lives in your head and the review happens after the diff exists.

The difference in approach is where the state lives. A hand-rolled script keeps task state in whatever you choose, usually files or a tracker. Genie keeps it in a per-repo SQLite file at `.genie/genie.db` in standalone mode, or delegates it entirely to Orca in Orca mode. That means Genie can refuse operations it cannot perform atomically, and it means your history is tied to a file in the repository rather than to a service. There is no hosted board in the documentation, so a lost checkout is a lost local history unless you committed the database or kept Orca as authority. The README does not document rollback of the Orca selection beyond switching back and not importing state, so plan the switch as one-way in practice.

Maintenance, licence and the cost of staying current

The last push to the default branch was on 2026-09-15, and the most recent release listed is `v5.260915.1` from the same day, with `v5.260909.1` and `v5.260907.2` before it. Release cadence is high: three releases in roughly a week. That cadence is the upgrade cost. Because `genie doctor` warns when skills are older than the running binary, every binary update creates a follow-up task to re-run the skills channel and confirm the recorded ref in `~/.genie/skills-install.json`. Skipping it leaves you with a binary and skills at different refs, which `doctor` will report but not fix for you.

The licence is MIT, which permits commercial use and modification. The README does not describe any trademark or attribution requirement beyond including the licence text, and nothing here should be read as legal advice; if you fork and redistribute a modified binary, check the MIT terms and the cosign and SLSA provenance chain yourself, because a rebuilt binary will not carry the original signatures. The repository also carries `SECURITY.md` and an incident-response document, which suggests the maintainers treat the signed-release path as part of the security boundary rather than a convenience.

Editorial conclusion

Adopt Genie if you already run coding agents from a terminal and want the planning, worktree isolation and pre-review step managed as one signed binary rather than hand-rolled scripts. Do not adopt it if you need a published npm package (npm distribution was discontinued on 2026-05-09), if you want a hosted board that survives a machine loss, or if your team cannot tolerate a lifecycle authority that fails closed when Orca is unavailable. Verify three things first: that `genie doctor` reports every skill home as present at the running binary's ref, that the pinned skills CLI version recorded in `~/.genie/skills-install.json` matches what you expect, and that `genie setup --orchestration-mode orca` succeeds on your host before you commit any roadmap writes to Orca.

Frequently asked questions

Official sources

1. automagik-dev/genie on GitHub
2. License: MIT
3. Project website
4. README
5. Releases