Docs

Get started with ZeNorm

ZeNorm ships as a public CLI with bundled agent skills. Install the CLI once, run zenorm setup <agent> to sign in and install the skills into your agent of choice, then invoke ZeNorm by name from inside any session.

Quickstart

01
Sign up
Create an account at /sign-up. Start free — no credit card required.
02
Connect GitHub and import your repo
In the dashboard, connect GitHub and import the repo you'll be working in under Repositories. This grounds specs in your actual code, and it is required before zenorm work will claim anything: it matches ready tasks against your checkout's git remote, so a repo that was never imported yields no tasks and zenorm work just keeps polling.
03
Install the CLI
Install the public CLI globally with npm:
```
npm install -g @ze-norm/cli
```
04
Set up your agent
One command does both halves of onboarding: zenorm setup signs you in through the device flow (opening a browser for approval) and installs the bundled ZeNorm skills into the agent you name. This step is required — the run command the dashboard gives you for a finished spec (/zenorm Z-123 and its per-harness equivalents) is a skill invocation and does nothing until the skill is installed. Pick whichever agent you actually run, and set up others later.
```
zenorm setup claude-code      # Claude Code
zenorm setup codex            # Codex CLI
zenorm setup cursor           # Cursor
zenorm setup opencode         # OpenCode
zenorm setup github-copilot   # GitHub Copilot
zenorm setup codex --force    # reinstall over existing ZeNorm skills
zenorm setup cursor --project # install into this repo, not globally
```
Already signed in, or want to add a harness without touching auth? zenorm install-skills <agent> installs skills on their own, and zenorm install-skills '*' --project covers every project target at once.
05
Create your first spec
In the dashboard, describe a feature in plain language. The agent will challenge you with the right questions until the spec is ready for an agent to act on.
06
Invoke ZeNorm inside your agent
Each harness has its own invocation syntax. The skill knows how to list, read, and apply specs — just ask for one by id or tag. This is the only way to run a spec in a harness zenorm work cannot drive, such as Cursor, OpenCode, or GitHub Copilot.
```
# Claude Code, OpenCode, GitHub Copilot, Gemini CLI
/zenorm spec-007

# Cursor
@zenorm spec-007

# Codex
$zenorm spec-007
```
07
Or run the whole spec hands-free
From inside the imported repo, zenorm work watches for ready tasks and runs each one through your agent. --agent takes claude or codex here — these are runner names, not the install-skills slugs. If it sits on no ready tasks, the repo is almost certainly not imported (step 02).
```
zenorm work --agent claude
zenorm work --agent codex
```

Harness reference

What zenorm setup (or install-skills) writes with --project, and how to invoke ZeNorm once it's in place.

Harness	Install path	Invoke
`claude-code`	`.claude/skills/zenorm/SKILL.md`	`/zenorm <spec-id>`
`codex`	`.agents/skills/zenorm/SKILL.md`	`$zenorm <spec-id>`
`cursor`	`.agents/skills/zenorm/SKILL.md`	`@zenorm <spec-id>`
`opencode`	`.agents/skills/zenorm/SKILL.md`	`/zenorm <spec-id>`
`github-copilot`	`.agents/skills/zenorm/SKILL.md`	`/zenorm <spec-id>`
`gemini-cli`	`.agents/skills/zenorm/SKILL.md`	`/zenorm <spec-id>`

claude-code — Auto-discovered. Claude reads the SKILL frontmatter to decide when to invoke. Installs globally to ~/.claude/skills/ without --project. Runnable by zenorm work --agent claude.

codex — Installed as a local Codex skill in the current repo. Runnable by zenorm work --agent codex.

cursor — Installed as a local skill in the current repo; globally to ~/.cursor/skills/. zenorm work cannot drive Cursor — invoke the skill in-session instead.

opencode — Installed as a local OpenCode skill in the current repo. zenorm work cannot drive OpenCode — invoke the skill in-session instead.

github-copilot — Installed as a local skill in the current repo; globally to ~/.copilot/skills/. zenorm work cannot drive Copilot — invoke the skill in-session instead.

gemini-cli — Installed as a local skill in the current repo; globally to ~/.gemini/skills/. zenorm work cannot drive Gemini CLI — invoke the skill in-session instead.

CLI reference

Command	What it does
`zenorm setup <agent>`	One-shot onboarding, and the recommended starting point: signs you in if you aren't already, installs the bundled skills for that agent, then prints what to run next. Equivalent to zenorm login followed by zenorm install-skills <agent>. Takes the same slugs as install-skills, plus --project, --global, and --force.
`zenorm login`	Authenticate the CLI with your ZeNorm account via device flow. Run it on its own if you only need to re-authenticate — zenorm setup already does this for you.
`zenorm install-skills <agent>`	Install the bundled ZeNorm skills through the skills package, without touching authentication. Use any supported agent slug, such as claude-code, cursor, codex, opencode, gemini-cli, or github-copilot.
`zenorm install-skills '*' --project`	Install the bundled skills into every project-level agent target supported by the skills package.
`zenorm install-skills <agent> --project`	Install into the current repo instead of global agent directories.
`zenorm whoami`	Show the signed-in user and active workspace.
`zenorm work --agent <agent>`	Hands-free execution: watch for ready tasks and run each one through your coding agent with full spec context. Note the agent names differ from install-skills — work takes claude or codex (not claude-code). Requires the repo to be imported under Repositories; it only claims tasks whose spec is linked to your checkout's git remote.

FAQ

Why a skill, not a per-project glue layer?

A skill is the harness's native extension point. Install it once into your agent's skill dir and every session has ZeNorm context — no per-project markdown to maintain, no MCP plumbing for harnesses that don't speak MCP.

What does the skill actually do?

The skill teaches your agent to pull a ZeNorm spec by key or id, implement its tasks against the spec's acceptance criteria, and complete each task back to ZeNorm. The agent calls the CLI under the hood — credentials live in the CLI's local config on your machine, not in the skill file.

Does my agent need to be online?

The skill calls the ZeNorm API for spec content, so yes — for reads. The skill file itself is local and works offline (the agent will just fail any list/read until the network is back).

Can I install the skill into multiple harnesses at once?

Yes. Run zenorm install-skills '*' --project, or set up one agent at a time with zenorm setup <agent> using any skills-supported agent slug. Each writes to that agent's expected path; nothing conflicts.

Do I need an organization?

No. Personal workspaces work for individual ICs. Orgs are for teams that need shared specs and pooled billing — see the pricing page.

Ready to ground your agents?

Start writing specs in the dashboard — your first ten minutes will tell you whether this loop fits your work.

Start free See pricing