# FJX

FJX is an agent-accelerated forge. It turns a Forgejo instance into a workspace where humans and LLM agents collaborate on software using the same artifacts — issues, pull requests, comments, labels — under conventions that stay legible to both.

FJX is opinionated and a work-in-progress. Take what's useful; leave the rest.

FJX is for individuals & teams that see the value in a more autonomous agent harness but either a) don't know where to begin, or b) are hesitant to hand control over. FJX uses familiar tooling & workflows to software development teams, namely Forgejo. Forgejo was chosen since that is what the author uses, but the same idea & implementation could be applied Gitea, Github, and Gitlab users. FJX is designed to still be functional if any or all of the agents are removed from the system - it's simply business as usual before agentic coding.

FJX is transparent and has a lightweight deployment & maintenance story. Concretely:

• Ledgers, not databases. Each agent's state on an issue lives in a single comment with a stable marker (<!-- agent-pm:ledger -->, <!-- agent-dev:ledger -->). No external store, no schema migrations, no "where did this state go" — it's in the issue timeline where everyone can see it.
• Briefs, not prompts-in-comments. PM curates a per-role context brief (<!-- pm:brief:dev -->) on the issue. Working agents read the brief, follow the phase prompt it points at, and act. The human can read the brief too.
• Labels & assignees for control flow. agent/working, agent/review, agent/blocked, assignee=agent-dev — Forgejo's native primitives carry the workflow state. No second source of truth.
• fjx makes the agent's job easier. An agent that drives fjx dev done 42 does not have to discover the API shape, sequence three calls, remember the convention, or burn tokens on any of it. The guardrails and the audit trail are downstream effects of that ergonomics — fewer tokens spent on plumbing, fewer ways to get the plumbing wrong.

FJX is three layers stacked deliberately: Forgejo (the stage — durable state and shared workspace), fjx (the director — deterministic CLI that turns intent into action), and agents (the actors — judgment, discretion, work). A Kubernetes analogy: Forgejo is the cluster, fjx is kubectl, agents are the operators. See Concepts for the full picture.

FJX defines a small set of named roles. Each is described in Agents:

• Project Manager aka PM (agent-pm) — curator, librarian, command-interpreter. Off the critical path; removing PM degrades to manual mode without breaking the workflow.
• Developer aka DEV (agent-dev) — the worker. Claims issues, runs phase prompts (simple, investigate, propose, apply), opens PRs, maintains its ledger.
• QA (agent-qa) — the deliberately-misaligned second pair of eyes. Reads the Actions output, finds the gaps the harness can't catch, returns pass / concerns / fail.
• Builder (agent-build) — planned. Release manager. Will own deployment triggers (cost, irreversibility, confidence, drift).
• Human ($FJX_OWNER) — author of taste (prompts, AGENTS.md, wiki), holder of authority (the trust map, /spec-approved, the final merge).

The role architecture maps onto the five leadership "chairs" described in Roles & Chairs.

The full new-org walkthrough — organization, labels, agent accounts, teams, install, fjx init, and the coding-agent install — is in Setup.

For a quick look at the command surface, install fjx (requires Deno 2.x) and run --help:

deno install -gA -n fjx jsr:@tfks/fjx
fjx --help