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.