A new-org setup runs once.  Per-repo setup is `fjx init` and a commit.  The whole thing is roughly thirty minutes if you've used Forgejo before.

## 1. Create a Forgejo organization

FJX is designed to run against an **org**, not a personal namespace.  Agents are real Forgejo accounts that need to be added to teams with scoped permissions — that's an org-level concept.

Create the org through the Forgejo UI (`Site → New Organization`).  Add your personal account (`$FJX_OWNER`) to the org as an owner.

## 2. Create the label set at the organization level

Create the required `agent/*` lifecycle labels (and the recommended `type/*` and `risk/*` sets if you want them) **at the org level** (`<org>/-/labels`) so every repo inherits them. Make the `agent/*` labels **exclusive** so only one can be applied at a time.

See [Labels](./primitives/labels.md) for the full table — names, suggested colors, and meaning.

## 3. Create the agent user accounts

Create one Forgejo user per role.  Names are convention, but the prompts and `fjx` defaults assume:

- `agent-pm`
- `agent-dev`
- `agent-qa`
- `agent-build` *(planned; skip for now)*

Each needs:

- A real email address (Forgejo requires one; a `+alias` on your own domain works fine).
- A personal access token with `repo` scope (and `write:wiki` for `agent-pm`).  Store these tokens — the agent will use them via `FJX_TOKEN`.

## 4. Add the agents to teams with scoped permissions

Create org teams that grant just what each role needs.  A reasonable starting matrix:

| Team       | Members     | Permissions               |
| --------   | ----------- | ------------------------- |
| Managers   | `agent-pm`  | Write: Issues, Wiki       |
| Developers | `agent-dev` | Write: Code, Issues, PR's |
| Testers    | `agent-qa`  | Write: Issues             |
| Builders   | `agent-build` | TBD                     |

The **human** (`$FJX_OWNER`) is an org owner; they hold the trust map and the final-merge authority.  No team membership needed beyond that.

> [!NOTE]
> The current permission model is identity-based.  Action-tiered permissions (read / staging-write / prod-write / delete / external-send) are the planned next step — see [Roles & Chairs](https://git.tfks.net/tfks/fjx/src/branch/main/wiki/roles-chairs.md).

## 5. Install fjx

Requires [Deno](https://deno.com) 2.x.

```sh
deno install -gA -n fjx jsr:@tfks/fjx
```

Verify:

```sh
fjx --version
```

Install fjx on every machine that will run an agent — typically each agent gets its own host (or its own container) so cycles don't step on each other.

## 6. `fjx init` in each repo

In every repo the agents will operate on:

```sh
cd <repo>
fjx init
```

This scaffolds slash-command wrappers in `.agents/commands/fjx/` that delegate to `fjx <role>`.  It's idempotent — safe to re-run.  Use `--force` to overwrite files that have drifted from the stub.

Then **commit the scaffold**:

```sh
git add .agents AGENTS.md
git commit -m "chore: bootstrap fjx agent wrappers"
git push
```

Committing matters: the agents read these files from the repo when they run, so they have to be on whatever branch the agent checks out.

## 7. Install a coding agent

FJX has been tested with **Claude Code** on a Claude Pro plan.  The scaffold from `fjx init` is Claude Code-specific.

Install Claude Code per the [official instructions](https://docs.claude.com/en/docs/claude-code).  Then, from each agent's machine:

```sh
# Configure the agent's identity (one-time)
export FJX_TOKEN=<the agent's personal access token>
export FJX_CACHE=.fjx-cache-<role>.json  # e.g. .fjx-cache-dev.json

# Run one agent cycle
just agent-dev   # or agent-qa, or agent-pm
```

Each invocation is a one-shot: the agent claims work, executes one cycle, and exits. An external executor (cron, scheduler, supervisor) is responsible for re-invoking the agent on its cadence. The `just agent-*` recipes in this repo's `Justfile` are concrete examples of how to drive a single cycle; copy them into your own project's `Justfile` and adjust.

For unattended operation, run `fjx supervise` under a process supervisor — see [Supervisor setup](./supervise-setup.md) for systemd, launchd, and tmux recipes. Per-project overrides (container images per role) go in [`fjx.json`](./fjx-json.md) at each project root.

Other agent harnesses (Codex, Aider, etc.) should work in principle — the agent just needs to be able to read prompts from `fjx <role> prompt`, run shell commands, and edit files — but the wrappers `fjx init` lays down are tested against Claude Code.

## 8. Profit!

From here:

1. File an issue, give it the `agent/new` label.
2. Start `agent-pm` (it'll write the initial brief and assign to `agent-dev`).
3. Start `agent-dev` (it'll claim the issue and open a PR).
4. Start `agent-qa` once there's a PR to review.

Sit back and watch your bank balance sky rocket!  More realistically, things will go wrong.  The agents will record their blockers in ledgers on the issue.  Read the ledgers, fix the prompts, try again.  Encoding catches into the prompts is the work — see [the senior-practitioner chair](https://git.tfks.net/tfks/fjx/src/branch/main/wiki/roles-chairs.md).