Cast spells to ship software — the methodology layer for AI-assisted development.

AI agents can write your code; Arcane gives them the discipline to plan it, govern it, test it, review it, and ship it.

npm install -g arcane-cli   #  then:  spell init

🔁 opinionated lifecycle  ·  📜 41 spells  ·  🤖 12 agents  ·  ⚖️ 25 governance standards  ·  📝 markdown-native  ·  🔌 any AI client / tracker

See it in action

The problem

AI coding agents are great at generating code. They're terrible at shipping software.

Ask one to "build a feature" and you get a pile of plausible code with no plan, no tests you trust, no review, no governance, and no repeatable path from idea to a merged, deployed change. The gap isn't code generation — it's methodology.

Arcane is that missing layer. It's a structured, opinionated lifecycle — the Spell Loop — plus the governance, agent roles, and templates that make AI-driven development reproducible instead of chaotic. You stay in the driver's seat and cast spells; the framework keeps the work on rails.

The Spell Loop

One opinionated lifecycle. Each phase is a spell you cast — and the build→test→review core loops until the work actually passes.

/spell-plan → /spell-architect → [ /spell-implement → /spell-test → /spell-review ]* → /spell-ship

Plus session and operational spells — /spell-open-session, /spell-close-session, /spell-commit-work, /spell-bug, and more. Workflow spells are cast from your AI client as prompts; the spell CLI manages installation and the agent roster.

What's in the box

Arcane isn't a prompt snippet — it's a full framework. Everything installs into your repo as plain, reviewable markdown. Each spell is authored once, in .arcane/spells/, and reaches Copilot, Claude Code and Codex through thin generated shims — one source of truth, no per-client copies to drift apart.

| Layer | What you get | | --- | --- | | 📜 Spells | 41 prompt-driven workflows spanning the entire lifecycle — planning, architecture, implementation, testing, review, shipping, session management, and ops. | | ⚖️ Governance | 25 battle-tested standards as drop-in templates: git conventions, testing standards, CI/CD, threat model, ADR format, naming, security hardening, and more. | | 🤖 Agents | 12 ready-made agent personas with roles, clusters, and a gamified autonomy model — assign work and power levels per repo. | | 🛠️ CLI | spell init / add / update / status / uninstall — install by profile or à la carte, and keep everything in sync as new versions ship. spell report turns a program's PLAN.md into a Show Report — a generated completion page — offline. |

Session — open-session · close-session · commit-work · status · arcane-version Capture — save-idea · todo · feedback · suggest-feature · document · verification-ledger · brainstorm · explain-concept Delivery — create-pull-request · sync-pull-request · address-review Review — review · review-batch Planning — plan · architect · scope · product-review Build — implement · test · full-cycle · bug · bump · dotnet-expert · security-review · ship · enchant · generate-bot-icons · make-discoverable · scry · eas-store-deploy · compliance Docs — adopt-docs Venture — summon-venture · manifest Meta — present-arcane · check-drift

git-conventions · testing-standards · framework-decisions · decision-documentation-standard · agent-work-queue-model · naming-conventions · agent-policies · threat-model · hardening-checklist · authentication-strategy · new-business-setup · agent-approved-paths · portable-bootstrap · development-methodology · cicd-standards · poc-management-pattern · product-excellence-standards · spell-authoring-standards · rca-process-standard · universal-agent-rules · records-conventions · external-verification-standards · web-discoverability-standards · mobile-release-standards · compliance-standards

Meet the agents

Twelve legendary agents ship with Arcane — the Arcanos. Each is a role with a code name; within Arcane the two are aliases: summon Merlin or summon the architect and you get the same agent. Every namesake is public domain — golden-age stage magicians, myth, and classic literature. Run spell agents init and choose how they're named — the Arcanos roster below, plain generic role labels, random names, or your own custom universe.

Use the roster as-is, rename them to your own universe, or define new roles entirely — it's just a starting point. Agent portraits © Code Magician LLC.

Quick start

# Install the CLI (binary is `spell`; `arcane` works too)
npm install -g arcane-cli

# Bootstrap the current repo with a governance profile
spell init

# Optional: set up the agent roster (Arcanos, generic, random, or custom names)
spell agents init

# Then cast workflow spells from your AI client, per the Spell Loop:
#   /spell-plan → /spell-architect → /spell-implement → /spell-test → /spell-review → /spell-ship

# Keep your installed governance current
spell status     # what's installed + available updates
spell update     # pull the latest

# When a program in docs/plans/<slug>/ has shipped, generate its Show Report -- offline
spell report     # writes docs/plans/<slug>/show-report.{json,html}

spell or arcane? Both commands invoke the same CLI. spell ties to the Spell Loop; arcane is there for when you reach for the brand name. Use whichever you like.

Requires Node.js 18+.

Profiles

Install everything, or just the slice you want:

| Profile | Contents | | --- | --- | | lite | Spell library + core git & testing conventions — fast start | | methodology | Spells + the full methodology (no security/infra docs) | | governance-only | All standards docs — no spells or agents | | full | Everything — spells, governance, templates, agent definitions |

spell init --profile full
spell add agent-policies   # or install any component à la carte
spell add spells-build compliance-standards   # or several, in order

spell add takes one or more names. It checks each component's files before writing any of them: if one already exists, it prints one line naming the file and --force, exits 1, and writes nothing from that component. With several names it stops at the first failure and says which were added and which were not attempted; a name that is already installed is skipped. A component that keeps your own file (.gitattributes, for example) leaves an existing one alone and creates a missing one. --dry-run lists each file as identical, differing or missing, or as one that would be kept or refused, and writes nothing.

What spell update installs

Beyond refreshing what you have, spell update installs two things, and reports each by name (ARC-052):

• Missing prerequisites. A component that cites another one in requires (spells-build cites the standards documents) gets it installed when it is missing. It is tracked with hashes like any other component. If a file at its destination already exists, or it is an initOnly component, update leaves it alone and keeps it in the list with the reason.
• Newly available components, only when you ask. In a terminal, spell update offers them as a checklist with nothing ticked. Without one, pass spell update --add-new. With neither, nothing is installed and the list prints as before. --add-new is for repositories, not the user tier.

spell update never installs an initOnly component (line-ending-baseline, docs-baseline): adding one changes how Git treats files you already have, so it stays a spell add you run yourself. --dry-run names exactly the components a real run would install. spell doctor installs nothing; it names the command.

Setup questions, answered by flags

spell init asks a few questions about the repository and records the answers in .arcane.json; spell update asks any that an older install predates. Each question has a flag, on both commands, so a script or an agent harness can answer without a terminal:

| Flag | Answers | | --- | --- | | --role <hub\|consumer> | Does this repository manage other ventures as a hub? | | --tracking-mode <internal\|external> | Is work tracked in this repository, or in an external tracker? | | --external-provider <ado\|github\|jira\|other> | Which tracker. Only with --tracking-mode external, which requires it. | | --content-sensitivity <standard\|sensitive> | May agents quote this repository's contents? | | --push-policy <open\|guarded\|blocked> | May this repository push to a remote? See Push safety. | | --subject-root <path> | Which directory holds the subject's documents (docs profile). |

spell init --profile lite --tracking-mode internal --push-policy guarded
spell update --role consumer --content-sensitivity standard

A flag answers its question with no prompt, even under --profile; a question without a flag is asked on a terminal and skipped without one. A run that skips questions prints the exact spell update line that answers them. Values are checked by the same validator as .arcane.json, and a bad one exits 1.

A flag only ever answers a question that has no recorded answer yet. To change a recorded answer, edit .arcane.json deliberately; the flag is refused and names the current value. The one exception is --push-policy, which may also tighten a recorded policy (open → guarded → blocked). It can never loosen one.

Push safety

A repository whose history must never reach a remote records push_policy: "blocked", and gets two controls: a pre-push hook, and a disabled push URL on every remote. guarded installs nothing; spell doctor reports it, and the spells that push state it and ask first.

spell block-push     # enforce "blocked" on an initialized repository
spell unblock-push   # lift it: interactive terminal only, and you type the repository name

• spell block-push installs exactly what spell init installs for blocked, with the same refusals. It never takes over a core.hooksPath that another hook manager owns, and it refuses when a push URL is configured outside the repository. It records blocked only once both controls are in force, so a refusal changes nothing. Running it again on an enforced repository reports that and changes nothing. It needs no terminal, because it can only tighten.
• spell update never installs push controls. When it records blocked, from a question or from --push-policy, it tells you the policy is not enforced yet and to run spell block-push (ARC-049).
• Loosening is only possible through spell unblock-push, from an interactive terminal. No flag, script or other command can move a repository from blocked or guarded toward open: spell update --push-policy open on a blocked repository exits 1 and points you at spell unblock-push.

These controls stop an accidental push, not a determined operator (ARC-034).

Once per machine

Working across many Arcane repositories at once? Install the spells a single time at the user tier, instead of (or as well as) per repository:

spell init --user       # ~/.arcane/spells/<id>.md, plus one Codex/Copilot skill and one Claude Code command per spell in your home directory
spell status --user     # what the tier holds, and whether any client file is missing or customized
spell update --user     # after upgrading the CLI
spell uninstall --user  # removes only what it wrote; an edited client file is kept and named

Codex, VS Code Copilot and Claude Code each discover the user tier from their own home-directory locations (~/.agents/skills and ~/.claude/commands), so no VS Code setting is needed. Governance stays per repository — only spell delivery moves up a level.

Agents move the same way. Your agent roster can live once per machine too:

spell agents init --user   # ~/.arcane/agents.yaml plus one definition file per role
spell agents sync --user   # renders ~/.claude/agents/<name>.md — read by VS Code and Claude Code
spell agents list --user   # the roster the tier holds

Unlike spells, agent files are never delivered by spell init or spell update: they are rendered from your roster, whose naming strategy decides each file's name and contents, so an upgrade leaves them alone by design (ARC-047). And unlike skills, VS Code does not collapse two agents that share a name — a repository carrying its own .github/agents files adds a second entry beside the tier's rather than replacing it, so opting the repository out is what produces one set.

~/.claude/agents is read by VS Code and by Claude Code, so one file gives you the persona in both. Each description ends by saying the persona is for when you ask for it by name: Claude Code reads that field to decide whether to route work to a subagent unprompted, and twelve personas installed once per machine would otherwise start answering in projects that have nothing to do with Arcane. Change that sentence in renderUserTierAgent if you want the opposite.

A repository that opts in and has no roster of its own now takes the machine-wide one for its roster tables, rather than refusing.

Then let a repository stop carrying its own copies. spell init offers this when the machine already has a tier, and an existing repository opts in by setting one field:

// .arcane.json
{ "spell_scope": "user" }   // absent, or "repo", means this repository carries its own spells and agents

spell update          # lists the spell files this repository no longer manages — deletes nothing
spell update --prune  # removes the untouched ones; anything you edited is kept and named
spell agents sync     # stops writing .github/agents here; names the leftovers and the git rm line
spell doctor          # fails loudly if the user tier it now depends on is missing

This is what removes the duplication: with the repository's own copies gone, one workspace holding ten Arcane projects shows one set of /spell-* entries, not ten. It is also what makes the answer predictable — while both tiers own a command name, which copy a client runs is not something you can read off the docs.

Tired of answering that question in every new repository? Tell the machine once:

spell update --user --default-scope user   # or repo, to go back

That pre-selects the answer spell init offers in new repositories on this machine. It rewrites nothing that already exists, and the question is still asked, so a repository you want to keep self-contained is one keystroke away. An absent spell_scope means repo permanently, on every machine (ARC-048) — a preference decides what you are offered, never what an existing repository means.

If a repository that opted in ever lands on a machine with no tier, spell update there now says so, names the store path, and gives you both ways out.

Shared, team and cloud repositories should stay repo. The field is committed and inherited by every clone, so opting in tells everyone who clones that repository to get their spells from a machine-wide install they may not have. Reverse it by setting the field back and running spell update, which reinstalls every spell file.

Philosophy

• Opinionated about how, pluggable about which. Arcane is strict about the lifecycle, governance, and commit discipline — and adapter-friendly about your tools (any AI client, any tracker, GitHub or Azure DevOps).
• Markdown is the source of truth. Everything is plain, reviewable, version-controlled text. No lock-in, no opaque state.
• Reproducible by design. Spinning up a new project should mean running spell init, not redoing months of process work.

Built in public

Arcane is built with Arcane. From this repo's first commit forward, development happens in the open — planned, implemented, reviewed, and shipped using its own spells, with each session logged. Want to see how the methodology actually works? Watch the commit history.

Contributing

PRs welcome. See CONTRIBUTING.md for dev setup and conventions, and SECURITY.md to report a vulnerability. By contributing you agree your contributions are licensed under MIT.

npm ci             # install dependencies
npm test           # run the test suite
npm run build      # produces dist/index.js + dist/assets/
npm run lint       # lint
npm run typecheck  # type-check

Claude Code preview config: .claude/launch.json registers dev-server launch configs (arcane-website, arcane-ui) for Claude Code's in-editor preview tooling. It assumes both repos are cloned as sibling directories next to this one (../arcane-website, ../arcane-ui).

License

MIT — see LICENSE. Copyright © 2026 Code Magician LLC.

The Arcane name, logo, and agent art are brand assets of Code Magician LLC; the source code is MIT-licensed.