diff --git a/AGENTS.md b/AGENTS.md index fe8ffca..b97b7fd 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -31,8 +31,8 @@ bd close # Complete work ```bash git pull --rebase bd dolt push - git push - git status # MUST show "up to date with origin" + git push forgejo + git status # MUST show "up to date with forgejo/" ``` 5. **Clean up** - Clear stashes, prune remote branches 6. **Verify** - All changes committed AND pushed @@ -69,6 +69,21 @@ Working style that avoids common problems here: - Keep `.env` aligned with `.env.example`; adapters default to synthetic modes for local development. - Dev runners persist child PID state in `.tmp/`; if a previous run crashed, restart via the standard `bun run dev*` commands so stale processes are cleaned up. +## 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 ` 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. + ## Required Turn Documentation At the end of every completed implementation task, before final handoff, create a user-readable HTML document describing the work. @@ -134,8 +149,8 @@ A task is not complete until: 3. Relevant quality gates have passed or failures are documented 4. Changes are committed 5. `bd dolt push` succeeds -6. `git push` succeeds -7. `git status` shows the branch is up to date with origin +6. `git push forgejo ` succeeds +7. `git status` shows the branch is up to date with `forgejo/` For trivial changes, the document may be brief, but it must still exist and clearly explain what changed and how it was validated. diff --git a/docs/turns/2026-05-22-forgejo-primary-agent-workflow.html b/docs/turns/2026-05-22-forgejo-primary-agent-workflow.html new file mode 100644 index 0000000..9bb130e --- /dev/null +++ b/docs/turns/2026-05-22-forgejo-primary-agent-workflow.html @@ -0,0 +1,169 @@ + + + + + + 2026-05-22 - Forgejo Primary Agent Workflow + + + +
+
+

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.
    • +
+
+
+ +