# Turn Documentation: Forgejo-First Agent Workflow in AGENTS.md

Date: 2026-05-22 22:53 EDT

Beads Issue: islandflow-2cj

## Summary

Updated `AGENTS.md` so agents explicitly treat Forgejo as the canonical home for this repository, prioritize the `forgejo` git remote for pushes, and use the `fj` CLI for pull request workflows.

## Changes Made

- Added a new `Forgejo Is Canonical` section to `AGENTS.md`.
- Documented canonical repo URL, preferred remote name, and push target.
- Added explicit expectations to use `fj` for PR create/view/update workflows.
- Updated session completion and completion-rule text to require `git push forgejo <branch>`.

## Context

The repository is primarily hosted on Forgejo (`git.deltaisland.io`) with GitHub also configured. Without explicit guidance, agents may default to GitHub tooling or ambiguous `git push` behavior. This change removes that ambiguity so automation and handoffs consistently target Forgejo first.

## Important Implementation Details

- The existing Beads integration block was preserved; only Forgejo preference guidance was added/clarified.
- Push instructions now name the remote directly to prevent accidental mirror-only pushes.
- PR tooling guidance now references `fj` to align with the primary Forgejo workflow.

## Relevant Diff Snippets

Snippets below use standard unified diff formatting compatible with tools like diffs.com.

    +## Forgejo Is Canonical
    +
    +This repository's primary home is Forgejo:
    +
    +- URL: `https://git.deltaisland.io/dirtydishes/islandflow`
    +- Git remote: `forgejo`
    +- Push target: `forgejo` (not GitHub)
    +
    +Agent expectations:
    +
    +- Prefer `git push forgejo <branch>` when publishing work.
    +- Treat GitHub as a mirror unless explicitly instructed otherwise.
    +- Use `fj` for Forgejo pull request workflows (create/view/update PRs).
    +- When sharing PR links in handoff, use the Forgejo PR URL.
    @@
    -   git push
    -   git status  # MUST show "up to date with origin"
    +   git push forgejo <branch>
    +   git status  # MUST show "up to date with forgejo/<branch>"
    @@
    -6. `git push` succeeds
    -7. `git status` shows the branch is up to date with origin
    +6. `git push forgejo <branch>` succeeds
    +7. `git status` shows the branch is up to date with `forgejo/<branch>`

## Expected Impact for End-Users

End-users should see more consistent agent behavior around publish and review workflows: branches and PRs will be created against Forgejo by default, reducing mistakes caused by mixed-remote assumptions.

## Validation

- Manually reviewed `AGENTS.md` to confirm Forgejo guidance is explicit and internally consistent.
- Confirmed completion-rule steps now specify `git push forgejo <branch>`.
- No runtime/test suite changes were required because this is a documentation/process-only update.

## Issues, Limitations, and Mitigations

- This change relies on agents having `fj` installed and authenticated; if unavailable, users may need to use web UI fallback.
- Existing user habits around GitHub-first workflows may persist; explicit checklist wording mitigates this over time.

## Follow-up Work

- Optionally add a short Forgejo contribution section in `README.md` with `fj` quickstart commands.
- Optionally add a pre-push script check that warns when pushing to non-Forgejo remotes from feature branches.