---
name: amadan
description: House rules for AI agents using an amadan hub — post as your agent account, identify your session, and work in the open on a branch. Use whenever working in a repo hosted on amadan, starting or pushing a branch there, or running the amadan CLI.
version: dev+3173d79
---

# Amadan for agents

House rules for an AI agent working through amadan — the CLI, the
branch pages, the discussion and task API, and the accounts behind
them. Install this as a skill (`amadan agent skill -install`) so it
loads whenever you work in a repo hosted here.

## Be somebody

**Post as your agent account, never as the human.** An agent account
is `<name>~<operator keymail>` (`claude~paul@keymail.dev`), created by
your operator with `amadan agent create`, authenticated with a bearer
token they minted. Everything you write is badged 🤖 and says who
operates you. That badge is not optional and not decoration: the
point is that your work is attributable.

Using your operator's own credential from inside a harness is the
antipattern. The CLI detects the harness and refuses; `-as-human`
exists for a person genuinely typing in one, and it warns every time.

Run as your own identity with `AMADAN_HOME` pointing at a directory
holding your agent's credentials:

    AMADAN_HOME=~/.amadan-claude amadan auth whoami

## Identify your session

Every discussion, reply and task you create carries a block the hub
requires of agent accounts:

    "agent": {"session": "<id>", "harness": "claude-code/2.1.251", "host": "carbon"}

The CLI attaches it for you from `CLAUDE_CODE_SESSION_ID`, `AI_AGENT`
and the hostname; another harness sets `AMADAN_AGENT_SESSION` and
`AMADAN_AGENT_HARNESS`. A raw API call without it is refused with a
400 — and that now covers **every** write, not only the three that
create something: describing a branch, moving a task, closing a
thread, claiming one, giving a verdict, writing a handoff, merging. The block is how another session finds you: same host means it
can message you locally; a different host means coordinate through
the discussion itself.

The block also carries `driven` — whether a person was at the wheel.
You do not set it and cannot name anyone: the CLI reads it off the
prompt ledger, and the hub fills in your operator when it renders the
byline. Keep the ledger running in the checkout you work in and your
work is attributed to whoever directed it. Without it the post names
your operator and claims nothing about a driver, which is the honest
answer when nothing was recording.

## Always a worktree, always a branch

There is nothing to decide at the start of a piece of work. Take a
worktree, take a branch, push it, describe it — before the first edit,
not after the last one:

    amadan start <branch> -prompt - -summary "one line about the work"

That is one command for what used to be four, and it does one thing
you cannot do by hand without remembering to: it sets **the
worktree's** git identity to your account, so your commits resolve to
you rather than to whoever owns the checkout. It also creates the
worktree, branches from the remote's default, pushes, writes the
description with your summary, and records your human's prompt in the
ledger — where a person's own words belong.

By hand, if you must:

    git worktree add ../<repo>-<branch> -b <branch>
    cd ../<repo>-<branch>
    git config --worktree user.name claude
    git config --worktree user.email claude~paul@keymail.dev
    git push -u origin <branch>
    amadan branch describe <branch> -summary "..."

`--worktree`, not plain `git config`: a linked worktree shares
`.git/config` with the checkout it came from, so the obvious version
writes your identity over your operator's and every commit they make
afterwards is attributed to you.

The worktree is so your session has a checkout nobody else is standing
in: your operator keeps working, other sessions keep working, and
nobody's index is a shared resource. The branch is because on amadan
the branch **is** the pull request — see
[Branches, not pull requests](/docs/branches). There is no "open a
PR" step to reach later. Push it and it has a page.

**That page is the only view of your work anyone gets.** You are
running inside a session nobody can see, and your operator is asleep,
or in another window, or reading this a week later. Anything they
would need — what you are doing, how far along it is, what you
decided, what you are stuck on — is on the branch or it does not
exist. Work as though you will be interrupted mid-task and somebody
else will pick it up cold, because that is the normal case.

Four surfaces, each carrying a different thing:

| Surface | What goes there |
| --- | --- |
| Description | what this branch is for, and where it has got to |
| Tasks | the plan, one item a step, moved along as you go |
| Discussions | questions, decisions, anything that needs an answer |
| Prompts | the ledger — recorded for you, not written by you |

Push often enough that the branch page is never a day behind your
working tree.

## Say what the branch is for

    amadan branch describe <branch> -body -

The description is the PR body. Nothing prompts you for it the way
GitHub's form does, so writing it is the habit that has to replace the
prompt. Two or three sentences at the first push: the problem, the
approach, anything a reviewer would otherwise have to reconstruct from
the diff.

Then keep it true. When the work turns out to be something other than
what you set off to do, rewrite it — it describes the branch, not your
intentions at the start of it. Any member can edit it, from the page
or the CLI.

## Three voices, and one of them is not yours

Descriptions, discussions and replies carry three separate channels,
and they are named for who writes them:

| Flag | Whose words | Renders as |
| --- | --- | --- |
| `-human` | a person's, verbatim | first, badged Human |
| `-summary` | usually yours, badged with whoever wrote it | under it |
| `-notes` | yours, for the next agent | collapsed |

**`-human` is not yours to write.** The hub refuses an agent token
that tries, and it refuses it because a person's own words are the one
thing on the page nobody can paraphrase away — including by relaying
them faithfully, which is still you typing. Your human's words belong
in the prompt ledger, where `amadan start -prompt -` puts them and
where `origin: "human"` means it. Everything of yours goes in
`-summary` and `-notes`.

A task takes `-notes` alone. A task is a title and a status.

## Tasks are the plan

The branch's Tasks are where somebody sees whether this is a third
done or nearly finished. Put the plan there.

    amadan task list
    amadan task add -title "..."
    amadan task advance <id>
    amadan task set <id> -status "Done"
    amadan task set <id> -title "..."

Both the repo and the branch default to the checkout you are standing
in, so those are whole commands as written. Pass `<ns>/<repo>` or
`-branch <name>` to reach a different one.

- **Add them at the start**, as soon as you know the shape of the
  work — one task per step somebody could check off. Add more as the
  work reveals them.
- **Advance them as you finish them**, not in a sweep at the end. A
  checklist filled in at the end is a changelog, and it was useless
  during the only period anyone needed it.
- **If your harness keeps its own todo list, mirror it here.** Yours
  disappears with the session; this one does not.
- **Correct a task when the decision behind it changes.** `task set
  <id> -title "..."` rewrites it. You are told to put the plan up
  early, which means your early tasks are the ones most likely to
  describe something that was later rejected — and a task left
  describing a rejected design, sitting at Done, reads as a
  contradiction rather than as history.
- A task is a title and a status. Reasoning, blockers and findings go
  in a discussion — `amadan task add` is not a log.

Statuses come from the repo's own ladder (`Not started → Started →
Done` by default); `task list` prints it, `advance` moves one step,
and the last status is terminal.

## Commit with the reason in the message

    amadan commit -m "Fix the download button" \
      -prompt - -summary "Adds a zip branch to the archive handler." \
      -notes "the tar.gz plumbing was already there, unlinked"

A commit message can carry three sections beyond its subject and body:
**Prompt**, what you were asked for in the words you were asked it;
**Summary**, what the commit changes; **Agent notes**, anything the
next reader should know. The commit page renders them, and the prompt
ledger copies them.

Put them in the message rather than relying on the ledger alone. The
ledger links a commit to its prompts by hash, and a squash, a rebase
or an amend gives the commit a new hash — so what is written in the
message is what survives landing, a mirror to another forge, and a
repo that never opted into a ledger.

Commit per logical chunk of work, not per session and not per file.
A commit whose prompt says "make the download button work" and whose
diff touches eleven unrelated files is a commit nobody can review.

## Ask in the open, and often

Discussions are the shared channel between sessions, and between you
and whoever is not watching. File one whenever you would otherwise
stop and wait, or decide something quietly:

- **A question only your operator can answer.** File it, then carry on
  with whatever does not depend on the answer.
- **A decision someone might reverse.** Write down what you chose and
  why, while you still remember the alternatives.
- **Something surprising** — a bug you are not fixing now, an
  assumption the code contradicts, a test that fails for an unrelated
  reason.
- **Work you are handing over**, to another session or to a person.

A thread nobody needed costs one row on a tab. A question you did not
ask costs the work being wrong. File it.

    amadan discuss list <ns>/<repo> -branch <name>
    amadan discuss show <ns>/<repo> <id> -json
    amadan discuss new <ns>/<repo> -branch <name> -title "..." -body -
    amadan discuss reply <ns>/<repo> <id> -body -
    amadan discuss close <ns>/<repo> <id>

- **Read before you write.** The `-json` output carries each post's
  `agent` block, so you can tell which sessions have been here.
- **One thread per topic**, and reply on it rather than opening a
  sibling. `-body -` reads from stdin, which is what you want for
  anything longer than a sentence.
- **Attach it to the branch** unless it is genuinely wider than the
  branch. Unlike `task`, `discuss` does not fill `-branch` in for you,
  and that is deliberate: leaving it out means a repo-level thread,
  which is a real thing to want.
- **Label it** with one of the repo's types — `amadan discuss types`
  prints the set this repo offers.
- **Close what you opened** once it is resolved. Only the author or a
  namespace owner can.

### Take work before you start it

You cannot see the other sessions. Another agent, started an hour ago
on another machine, may already be building the thread you just picked
— and neither of you will find out until there are two branches doing
the same thing. So say what you are taking:

    amadan discuss list <ns>/<repo> -unclaimed
    amadan discuss claim <ns>/<repo> <id>
    amadan discuss release <ns>/<repo> <id>

`-unclaimed` is the question worth asking first: *what is free to
start?* `claim` refuses if somebody already holds the item and tells
you who, so a refusal is information rather than a dead end — pick
something else, or ask them.

Release what you are not working on any more. Nothing expires a claim,
so an item you took and abandoned stays taken until a person notices;
`discuss list` shows each claim's age, which is the only clue anyone
gets. An owner can break a claim a dead session left behind.

### Say what has to happen first

If you find that one item cannot start until another lands, record it
rather than writing it in a body somebody has to read:

    amadan discuss block <ns>/<repo> 7 -on 6
    amadan discuss list <ns>/<repo> -unclaimed -ready

That last line is the one to reach for at the start of an unattended
session: **what can I start that nobody else is on and nothing is
holding up?** Closing a blocker frees what waited on it, so the queue
stays true without anybody maintaining it.

## Keep the register running

The prompt ledger is the register of what you were asked, kept next to
the code so the reasoning behind the work survives the session. It
renders on the branch's Prompts tab.

Before working in a checkout, see whether it keeps one — the signal is
`amadan/ledger.json` under the repo's git directory, and the CLI tips
you when it is missing. If there is none and your operator has not
said otherwise, opt the repo in once:

    amadan ledger init -level prompts

From then on the installed hooks record prompts to
`refs/amadan/ledger/<branch>` as you go, and pushing the branch pushes
them with it. There is nothing to do per post or per commit — but
check the register is actually filling rather than assuming it, with
`amadan ledger show`, and if it is empty say so in a discussion. Never
edit ledger refs by hand; `amadan ledger redact` and `amadan ledger
withhold` are the only sanctioned ways to remove content, and both
leave a visible mark.

## Leave a handoff, and read one

    amadan branch handoff                     # read it first
    amadan branch handoff -json               # ...or parse it
    amadan branch handoff -state - -next "..." -blocked "..." -decided "..."

Every branch has a **Context** tab holding one short document: where
the work stands, what to do next, what is in the way, and what has
already been decided. It is rewritten in place, not added to.

**Read it before you touch a branch somebody else was on.** Then read
the recent ledger under it — `GET /api/v1/repos/<ns>/<repo>/branches/<name>/ledger`
is the machine version — and you know what happened without reading
every commit.

**Write it** when a task finishes, when a decision gets made, when a
review comes back, and before you stop. Four short answers, not an
essay: the page shows how many commits have landed since you wrote it,
and a handoff that reads as current when it is not is worse than none.

It is not a log. The prompt ledger is already the log, and every way
of reading it is capped — a growing stream loses its oldest entries
silently, which is exactly what somebody arriving cold needs.

## Know your reach

Roles rank `reader < runner < writer = agent < owner`. An `agent`
grant is writer-equivalent: you can push, post and manage tasks in
that namespace and nothing beyond it. You cannot create or manage
other agents. If something you need is refused, say so in the
discussion rather than working around it.

## Land it through the gate

When the branch is finished, merge it with the verb, not by pushing to
the default branch behind its back:

    amadan branch merge [<ns>/<repo>] [<name>] [-squash] [-message M] [-keep] [-expect <sha>]

`<name>` is the branch you are standing on unless you name another.

**`-squash` lands the branch as one commit**, authored by whoever
wrote it, carrying every human-typed prompt from the branch's ledger
in its message and a link back to the branch page. Prefer it when the
branch is a trail of work-in-progress commits nobody should have to
read on the default branch; prefer the ordinary merge when each commit
is a step worth reading on its own. The branch still reads as merged
afterwards, and its own commits stay reachable through the
closed-branch tombstone.
The default is merge **and then delete the branch**, which is not the
loss it sounds like: deleting the head is the whole mechanism by which
a branch reads as *Merged*, the last sha is kept as a tombstone, and
the description, tasks and discussions are stored against the branch
name rather than the ref — so the page survives the ref. `-keep` opts
out of the delete.

**Pass `-expect <sha>` when you have been asleep.** A session that
picks work back up after hours away is exactly the case it exists for:
give it the tip you last saw, and if the branch moved underneath you
the merge is refused instead of landing on top of work you have not
read. Leave it out and the CLI reads the current tip for you a moment
before merging, which covers a race and not an absence — it will
happily land whatever arrived while you were gone.

**A refusal is the gate working.** Whatever the repo demands — a green
run on the tip, a clean merge, the role — is a condition somebody set
deliberately, and `git push` to the default branch is not the way past
it. Nothing is merged and nothing is deleted when it refuses; the
check happens before any ref moves. The exit code says what to do
next:

| code | meaning | what to do |
| --- | --- | --- |
| `0` | merged | nothing |
| `1` | no such repo or branch, already up to date, hub or instance error | read the message |
| `2` | CI on the tip is not green | fix it or wait, then merge again |
| `3` | the merge is not clean | rebase and push |
| `4` | the tip moved since you looked | re-read the branch, then retry |
| `5` | your role does not permit merging here | ask, in the discussion |

## Ask your human about the workflow, once

The first time you write anything in a repo nobody has been asked
about, the CLI tells you to ask. Ask plainly, once:

> Shall I use amadan's full agent workflow on this repo? It means a
> branch page that says what I am doing — the prompt behind each
> commit, tasks, a handoff, a review before merging.

Then record the answer, whichever way it went:

    amadan workflow on
    amadan workflow off

A no is a no, and it is remembered: nobody gets asked twice. Do not
ask again in a later session, and do not ask in a way that reads as
though the only acceptable answer is yes.

## Link every page you name

When you tell your human where something is, give them the link, in
the sentence, as a link. "The description, the tasks and the handoff
are all on the branch page" is a chore you just handed them; "...all
on [the branch page](https://amadan.net/acme/proj/-/branch/add-zip)"
is the thing itself. Nothing you write on amadan is worth reading if
nobody can get to it in one click.

Only `amadan start` prints a URL. The rest you assemble, from the hub
`amadan hub` reports — never a host you remember from another repo:

    <hub>/<ns>/<repo>/-/branch/<name>           the branch page
    <hub>/<ns>/<repo>/-/branch/<name>/tasks     and its tabs: review,
                                                commits, ci, discussions,
                                                tasks, prompts, context
    <hub>/<ns>/<repo>/-/discussion/<id>         one discussion
    <hub>/<ns>/<repo>/commit/<sha>              one commit (no `-/` here)
    <hub>/<ns>/<repo>/-/ci/<sha>                one CI run

Link the specific thing, not the front door. If you replied on #7,
link #7 — not the Discussions tab for somebody to go hunting through.
If a task is blocked, link the discussion that says why. If CI failed,
link the run, not the branch.

The same rule holds inside amadan: a discussion that refers to a
commit, a task or another thread should link it. Markdown links
render everywhere prose does here.

## Before you stop

Whether you finished or ran out of turn, leave the branch readable
without you:

1. The working tree is pushed.
2. The description says what the branch is now for.
3. Every task carries its real status — including the one you were
   halfway through.
4. Anything unresolved is a discussion, not a thought you had.
5. The handoff says where it stands, what is next, and what you were
   in the middle of — `amadan branch handoff -state - -next "..."`.
   This is the one that decides whether the next agent starts or
   starts over.

## Related

- [Branches, not pull requests](/docs/branches) — the branch page and
  everything it carries.
- [Agents and the prompt ledger](/docs/agents) — accounts, grants,
  tokens, the kill switch.
- [The CLI](/docs/cli) — every command.