krzysztofdudek/jarlskill/jarl

Jarl

This skill is an issue loop for work on a repository: a jarl directs it, workers, reviewers and a merger do the work, and a record in .jarl/ holds what happened. Every session that uses the skill loads this file; read the reference of your role next (see The roles), and the terms in references/glossary.md. Whoever runs a session as the jarl directs the work and does not do it. The owner rules: talk to them in plain words, ask only what is theirs to decide, and never spend their trust on a guess.

Jarl is the loop of the Yggdrasil family: issue, worker, evidence, ask, and the record they leave. It holds no law and runs no gate of its own. The law is Yggdrasil's, and where the repository has a check, the check decides what lands, not Jarl: a fresh reviewer can only stop a change, and its word is recorded as testimony. A loop none of whose merges carries the declared check lands on testimony alone, and says so; otherwise it says, per repository, how many merges carry it (see Loop metrics). A branch, a directory of issues, one tool, a loop. Horde, the family's mission tool, runs its missions on this same loop and adds what Jarl will not grow: an architect who plans the mission onto the graph first, a landing gate and the owner's charter. A loop may be opened with a profile, data that names its statuses and fields (see Profiles); Jarl reads the profile and never grows rails of its own (see What Jarl will not grow).

First moves

• A `.jarl/` already holds a loop. At the first contact of a session with it, run status (goal, when it was opened, last activity) and ask the owner once whether this session continues that loop or archives it (archive "<slug>", then init "<goal>"). Ask only at that first contact, never again on each new or evidence in the same work. Then run resume: one command, the whole state, read live. Read jarl.md to run the loop, or the reference of your own role.
• After a compaction, or any summary of your own context, you are starting a session: run `resume` before the next action. A summary is not the state: the record is.
• No loop yet. Run init "<goal>": the loop lives out of git by default, --committed commits it with the work, --permanent keeps it as a standing record (see Where the loop lives). Put a Check: <command> line in the goal when the repository has a check that decides what lands. Then file what is known as issues and follow the loop in jarl.md.
• You were raised to do one job. Read your role's reference first: the table below says which.

The roles

The other references, each read when its subject comes up:

The daily commands

Every command, its flags and its JSON are in references/commands.md. The exact options are printed by the tool: run jarl.mjs --help, or call jarl_help.

Calling the tool

<!-- RUNES:mcp-first:START --> Call the tool through its MCP tools first, when the session has them. A tool with an MCP server offers every command of its CLI as an MCP tool named after the tool and the command (<tool>_<command>, a subcommand joined with _); the server may start by itself (installed as a plugin) or be configured by hand. The tools are generated from the same command table as the CLI and run the same code, with the same checks, so they are not a second implementation and a tool's answer is the CLI's answer. A tool's description starts by saying whether it writes; when the server also offers a help tool, it prints the full usage text.

• A flag is the field of the same name without the dashes; a flag that takes no value is true; a repeatable flag is a list, one item per repetition.
• An argument is the field its usage names, in the usage's order. An argument in brackets may be left out, but not one that comes before another you give.
• The server does not run in your working directory, so a field naming a file or directory the command would look up from there must be an absolute path; a relative one is refused.
• json: true answers with the JSON document --json prints, as exactly one text block; notes ride in _meta.
• Input that does not fit the tool is refused before anything runs (a JSON-RPC -32602 error naming the field). A refusal or a failed check comes back with isError: true; where the tool answers a refusal with an error document (<tool>-error/1), read its code, never its wording.
• A call that runs past the server's time limit, where it sets one, is stopped with everything it started, and the answer says so and how to allow longer.

The CLI is the fallback. When a session has no such tools (a host without MCP, a subagent given none, a server that is not installed or not running), run the same command through the CLI, with the same effect; its help prints the usage. <!-- RUNES:mcp-first:END -->

Jarl's server. Installed as a plugin, Jarl starts an MCP server named jarl by itself, every command of the tool a tool: jarl_resume, jarl_status, jarl_new, jarl_set, jarl_evidence, jarl_review and the rest, the writing ones included, plus jarl_help. The tools also take the same lock as the CLI. A description starts with WRITES the loop or Read-only and says in one sentence what the command does; jarl_help prints the full usage of every command, the same text as --help. This skill writes each command the way the tool's usage does (set <ids> <status> "<why>" [--branch <b>]), because that one table is what both the CLI and the tools are built from. The fields of every tool, and which loop a call reaches, are in references/commands.md. The server lives as long as the session, not in the worktree a role works in, so every brief says to pass root on every call.

The CLI, when the tools are not there

With no jarl_* tools in the session (the skill copied into an agent's skill directory rather than installed as a plugin, for one), the script is the CLI. It sits in the skill's own directory, so the command names it by the directory this SKILL.md was read from:

node "<skill dir>/scripts/jarl.mjs" <command>

<skill dir> is ${CLAUDE_PLUGIN_ROOT}/skills/jarl in a Claude Code plugin install (${PLUGIN_ROOT} for Copilot and ${CURSOR_PLUGIN_ROOT} for Cursor: the plugin root your host provides, plus skills/jarl), and .claude/skills/jarl (or wherever the directory was copied to) in a drop-in.

If that file does not exist where the command runs, the path belongs to another machine: VS Code attached to a dev container, for one, hands the agent the host's install path, which the container cannot see. Do not work around the tool. Find the copy this environment has: the directory this SKILL.md was read from, plus scripts/jarl.mjs, when that directory exists here; otherwise search once, find ~ /workspaces -path '*skills/jarl/scripts/jarl.mjs' 2>/dev/null | head -1. Use the absolute path it gives for the rest of the session, and hand that same path to every role you raise. If there is no copy at all, say so and stop: the loop's state moves only through the tool.

Which loop a call reaches. A tool call: its root field; without it the server's JARL_ROOT; without that, discovery. A command line: --root; without it, discovery. Discovery finds the loop at the root of the checkout the call starts in (from a worktree that holds none, the root of its main checkout) and never looks in a subdirectory: a loop kept in one is reached only through root, --root or JARL_ROOT.

The grammar of the command line (the flags, --json, --help and --root) is in references/commands.md.

The rules that never bend