karloows/orchraft

We are a clan of orcs who haul the mundane, repetitive chores of shipping software off your plate — branch names, commit messages, PR write-ups, review nits, remembering what's still open — the stuff every developer does by hand every single time and nobody looks forward to, so the chief can spend the saved hours on the code that's actually interesting. Built first for the solo dev with no one else to hand the busywork to, welcome at any war table: your repo's rules, real sources behind every claim, and nothing touches git or GitHub until you say go.

The name joins orchestration and craft. The orc does the crafting.

Clan Laws

• The chief decides. No commit, push, merge, or PR comment happens without your go-ahead in the current turn, by default (context/policies/approval-policy.md). Opt into Autonomous Mode there if you want routine mutations pre-authorized — merge, force-push, delete, and issue close/reopen stay gated either way.
• Your stronghold, your rules. We read your project's policies, templates, and CI config first. Our bundled policies are only defaults.
• No bluffing. Branch names, commits, reviews, and explanations come from the real diff, history, and docs.
• Any stack. No assumptions about language, CI provider, or hosting.

The War Band So Far

Each skill is one tool in the clan's kit. These are forged today; more are on the anvil as we cover the rest of the lifecycle.

Today's march is warplan → quest → lore → chronicle → ship → roast → fix → ship → land → herald, with yap available at any point.

What A March Looks Like

Asking for a fix gets you the fix and nothing more. Asking to ship is what sends it: ship it in the current turn authorizes that whole run — branch, commit, push, and pull request.

chief ▸ the login crashes on a null token — fix it

orc   ▸ We read before we swing: the guard was missing in
        src/auth/session.ts. Patched it.
        Validation: `npm test -- auth` → passed.

        Nothing committed. Say the word when you want it shipped.

chief ▸ ship it

orc   ▸ 🚢 Grah! War party launched. PR #123 holds the beach for review, chief. ✨

        Branch: `fix/login-null-token`
        Commit: `fix(auth): guard null login token`
        PR: https://github.com/example/repo/pull/123
        Validation: `npm test -- auth`

The gate sits between the work and git, not inside ship: a request to fix, address, or resolve something is approval to edit, never to commit. It does not carry forward either — the next push to that branch needs the word again. roast posts no review, land merges nothing, and quest closes no issue until you say so.

Status

Stable enough to build on. The public surface is the skill names, the policy filenames and what they promise, and the .orchraft.jsonc keys — a breaking change to any of those comes with a major version bump, so an upgrade never moves the ground under an installed copy.

Requirements

• Local git and file access — enough for lore and chronicle on a diff or file, and for warchief, which routes to the right skill without reading GitHub state itself.
• A GitHub MCP connector configured for the session, authenticated with write access (not just read) for ship, roast, land, and quest — they create/update pull requests, post reviews, merge, and manage issues. gh installed and authenticated works as a fallback when the MCP connector is unavailable mid-session.
• gh with write access for herald to publish release notes, since the GitHub MCP connector can't write releases. Drafting them needs only read access.
• Read-only GitHub access is enough for runes, reckoning, plunder, watchtower, yap, and warplan when they're only reading PR/issue state, not changing it.
• jq for the two ambient hooks (watchtower-nudge.sh and main-commit-nudge.sh) to parse their JSON input — both degrade to silence, not an error, when it's missing.

Layout

• skills/: canonical agent skills, read directly by Claude Code, Codex, and Grok Build once orchraft is installed — no per-ecosystem symlink layer.
• .claude-plugin/: Claude Code plugin manifest and marketplace.
• .codex-plugin/ and .agents/plugins/marketplace.json: Codex CLI plugin manifest and marketplace, reading the same skills/.
• .grok-plugin/: Grok Build plugin marketplace, reading the same skills/.
• hooks/: a SessionStart hook that runs watchtower's status checks automatically (a plain script, not a model call) so the nudge shows up without asking for it, and a PreToolUse hook that nudges — never blocks — when a git commit/push is about to run directly against the repository's default branch. The only ambient behaviors here — every other skill is invoked on purpose.
• context/policies/: reusable approval, branch, commit, config, lore, docs, review, and PR writing policies.
• .orchraft.example.jsonc: a starting point holding every setting at its default, with the accepted values in comments. Copy it to .orchraft.jsonc (or .orchraft.json) and edit what you want to change; context/policies/config-policy.md documents each setting and how it ranks against your repository's own settings. Optional — the skills work with no config file at all.
• context/personality.md: the orc's character and voice, and where it applies.
• evals/: claude plugin eval cases that check skill behavior (e.g. ship refusing to commit without a request) rather than file syntax.
• assets/: art used by this README. orc.png is the mascot in the header, orc-intro.svg is the animated banner, and orc-armor.png is the original illustration that banner embeds — kept as the source of the artwork, not referenced directly by any page.

Edit the canonical skill files in skills/ directly.

Install As A Claude Code Plugin

/plugin marketplace add karloows/orchraft
/plugin install orchraft@orchraft

If the install reports that the plugin isn't active yet, run /reload-plugins (or /reload-plugins --force if it warns about the prompt cache).

The skills load as /orchraft:warplan, /orchraft:quest, /orchraft:ship, /orchraft:land, /orchraft:roast, /orchraft:yap, /orchraft:lore, /orchraft:chronicle, /orchraft:runes, /orchraft:reckoning, /orchraft:plunder, /orchraft:herald, /orchraft:warchief, and /orchraft:watchtower. They read context/policies/ from your repo when present and fall back to the policies bundled with the plugin.

To try a local checkout without installing, run claude --plugin-dir /path/to/orchraft.

Install As A Codex Plugin

codex plugin marketplace add karloows/orchraft
codex plugin add orchraft@orchraft

The skills load the same way as in Claude Code, from the same skills/ files, and read context/policies/ from your repo the same way.

Install As A Grok Build Plugin

grok plugin marketplace add karloows/orchraft
grok plugin install orchraft --trust

The skills load the same way as in Claude Code and Codex, from the same skills/ files, and read context/policies/ from your repo the same way.

Copy Into A Project

For other agents, or to customize the files, copy the parts you need into a target project:

• skills/ for the canonical warplan, quest, ship, land, roast, yap, lore, chronicle, runes, reckoning, plunder, herald, warchief, and watchtower workflows.
• context/policies/ for approval, branch, commit, lore, docs, review, and PR writing rules.
• context/personality.md for the orc voice the skills use in success lines.
• hooks/hooks.json, hooks/watchtower-nudge.sh, and hooks/main-commit-nudge.sh for the ambient watchtower nudge and the direct-to-default-branch commit/push nudge. This directory is only auto-discovered when loaded as a Claude Code plugin; outside that, copy all three files to hooks/ at your project root and copy the hooks object from hooks/hooks.json into your own .claude/settings.json. Each command falls back from ${CLAUDE_PLUGIN_ROOT} to ${CLAUDE_PROJECT_DIR}, so it resolves either way without editing the path.

Copy context/ together with the skills. The skills fall back to ${CLAUDE_PLUGIN_ROOT}/context/ only when running as the plugin; outside it, that path doesn't resolve.

Project-local instructions, PR templates, hooks, and CI checks should override these defaults.

Releases

Versioning and CHANGELOG.md are managed by release-please. Merge the open release PR to publish a new version; release-please writes the changelog itself, so never edit CHANGELOG.md by hand.

License

Apache-2.0