Primitives

FJX relies on Forgejo primitives (issues, pull requests, comments, labels, assignees) to bear the load. No second source of truth, no out-of-band coordination layer. This section documents the conventions that turn those primitives into a workflow.

• Labels — required agent/* lifecycle labels and recommended risk / type labels.
• Issues — the unit of work; the canonical home for all agent ledgers and the conversation.
• Pull Requests — evidence containers, not conversation; how PRs link to issues and what goes in the body.

Pull Requests are the durable record of work. Issues may get garbage collected & compacted into durable wiki entries.

System Mapping

State Diagram

How an issue moves from creation to release. The state machine is encoded in Forgejo's native primitives — labels record state, assignees route work, comments carry per-role artifacts.

stateDiagram-v2
    [*] --> New : issue created with agent/new

    New --> Dev : PM triages (parses /commands, curates brief, assigns to agent-dev, strips agent/new)

    Dev --> Working : Developer claims (adds agent/working)
    Working --> Review : Developer hands off (agent/review, reassigns to agent-pm)
    Review --> Dev : PM or QA routes back (spec rejected, revision requested, concerns flagged)
    Review --> Build : $FJX_OWNER accepts PR (PM reassigns to agent-build)
    Build --> Release : ready for deployment (agent/release)

    Working --> Blocked : /block <reason>
    Blocked --> Dev : /unblock

    Released --> [*]

    note left of Working
        The dev → working → review cycle runs
        once per phase: spec, implementation, revision.
        Phase is carried by the PM brief, not by labels.
    end note

Dispatch is by assignment, not label. PM hands work to a role by setting assignee=agent-<role> on the issue. Working agents pick up via fjx <role> next (filters by assignee). Labels record state; they do not name the next worker.

Labels are authoritative for state. Read labels before acting; if they're wrong, fix them rather than work around them. This holds for the user acting manually as PM too.

/<command> syntax is reserved for the PM (sole interpreter — see PM role for the trust map and command vocabulary). Working agents MUST NOT parse /commands as directives; treat them as inert text. Natural-language directives in comments are still in scope (see PR conventions).

Phase (spec proposal / implementation / spec revision) lives in the PM brief, not in labels — see PM role.

Ledgers

All agent ledgers live on the issue. PM, dev, qa, and build each maintain their own <!-- agent-<role>:ledger --> comment on the issue. Treat the issue as the single thread of record; assume PR comments carry nothing of import.

Every working-agent cycle produces a PR, including investigations, reporting requests, and "won't fix" / "not reproducible" outcomes. Non-code deliverables land in ./wiki/findings/<issue-id>-<slug>.md — one bucket covers bug investigations, reports, audits, and any cycle whose deliverable is a decision rather than code. "I looked and decided no" is a finding; record the justification.

See issue conventions for the ledger model in detail, and PR conventions for what goes in the PR.

Runbooks

Executable workflows shared by humans and agents.

• orchestrate multiple commands
• synthesize command output
• branch based on results
• retry safely
• validate outcomes
• define rollback paths

Layering

1. just commands: small deterministic primitives
2. runbooks: orchestration logic over those primitives
3. agents: readers/executors of runbooks

Principles

• Runbooks can branch and synthesize.
• just commands should remain simple primitives.
• Do not hide important decision logic inside shell scripts.
• Every agent action should leave evidence.
• Humans must be able to follow the runbook without paying AI cost.

Long-Term Memory

Local in ./wiki

Travels with code, participates in PR review, and can change atomically with implementation.

• agent rules
• architecture notes
• validation commands
• runbooks
• local gotchas
• repo-specific decisions

When you learn something durable about the system (architectural decision, non-obvious constraint, recurring gotcha), update the relevant wiki page in the same PR. Don't let the wiki drift.

Global in Forgejo Wiki

Do not duplicate ownership. Duplicate summaries are fine. Duplicate sources of truth are goblin bait.

• release notes
• cross-repo decisions
• onboarding
• operational summaries
• human-facing documentation

Milestones & Projects

Milestones are outcome containers, not merely deadline buckets. Use milestones to group issues into coherent outcomes. Good examples:

• MVP: Agent-driven deploy loop
• Stabilize LogBus ingestion pipeline
• FotoLog: map-first UI baseline

Projects are visualization layers for humans. They should mirror labels, not replace them. The system should still work if the Project board disappears.