chore(agents): one worktree per agent, and a Forgejo CLI instead of curl/Python snippets #118

New issue

Closed

opened 2026-09-25 19:10:24 +00:00 by gabogg · 1 comment

gabogg commented

2026-09-25 19:10:24 +00:00

Owner

Problem

Several agent sessions work on this repo at the same time, and some of them run git switch, git stash or commits directly in the main folder (~/Trabajo/Orinokia/hikcentral). They step on each other.

Incident, 2026-09-25 15:03–15:04:

Session A switched the main tree to fix/occupancy-config-save-preserves-calibration and edited app/static/js/app.js for the PR #115 review fix.
Session B, working on fix/occupancy-review-followups-53-54 (#65/#66), stashed that uncommitted change as wip-occupancy-config-save-appjs and switched the main tree back to its own branch.
Session A's commit then ran on the wrong branch with nothing staged, so the fix silently didn't land.

Nothing was lost (the change is still in the stash), but the only thing that caught it was an odd git log line.

2. Forgejo is driven with ad-hoc `curl` and Python snippets

Agents talk to the Forgejo API with hand-written curl calls and inline Python (urllib) to list PRs, post comments, create issues, set labels and merge. This has several costs:

it's verbose and error-prone (quoting, JSON escaping);
it's slow to review;
it spreads the API token across command lines. The token is also embedded in the origin remote URL.

docs/agents/issue-tracker.md documents only the raw REST endpoints.

Proposal

A. Workspace rule (AGENTS.md)

Every agent works in its own git worktree, e.g. git worktree add ../hikcentral-wt<topic> <branch> or one under the agent's scratchpad, and removes it when done.
The main folder is the maintainer's. Agents never run switch/checkout/stash/reset/commit there, and never stash or discard changes they did not make.
Before committing, check you are where you think you are (git status -sb shows the expected branch). If anything looks foreign, stop and report instead of "cleaning up".
Sub-agents run in throwaway worktrees, which the code-review skill already requires.

B. Forgejo CLI

Install a Forgejo-capable CLI, authenticated once through its own config (not tokens on command lines). Candidates:
- tea: Gitea's official CLI; works against Forgejo's Gitea-compatible API.
- fj (forgejo-cli): Forgejo-native.
Document it in docs/agents/issue-tracker.md and reference it from AGENTS.md "Agent skills". Include the exact commands for what agents do today:
- list open PRs and issues;
- read a PR or issue with its comments;
- create an issue with labels;
- comment on a PR or issue;
- set labels;
- edit a PR body, or retarget its base;
- merge with a merge commit, custom title and branch deletion.
Agents use the CLI instead of curl/Python for these operations. Keep the REST endpoints as a fallback only.
Consider moving the token out of the origin remote URL into a credential helper once the CLI holds its own login.

Open decisions (hence `needs-triage`)

tea or fj: both work. tea is more mature; fj is Forgejo-native. Check which one supports every operation above, especially merge with a custom title and delete_branch_after_merge.
How it's installed: system package, Go/Cargo binary, or a pinned download recorded in the repo like the Tailwind binary (#57).
Whether the workspace rule should also be enforced by a hook, e.g. refusing commits from agents in the main folder. The existing git-guardrails skill could do this.

🤖 Generated with Claude Code

## Problem ### 1. Agents share the main working tree Several agent sessions work on this repo at the same time, and some of them run `git switch`, `git stash` or commits directly in the main folder (`~/Trabajo/Orinokia/hikcentral`). They step on each other. **Incident, 2026-09-25 15:03–15:04:** - Session A switched the main tree to `fix/occupancy-config-save-preserves-calibration` and edited `app/static/js/app.js` for the PR #115 review fix. - Session B, working on `fix/occupancy-review-followups-53-54` (#65/#66), stashed that uncommitted change as `wip-occupancy-config-save-appjs` and switched the main tree back to its own branch. - Session A's commit then ran on the wrong branch with nothing staged, so the fix silently didn't land. Nothing was lost (the change is still in the stash), but the only thing that caught it was an odd `git log` line. ### 2. Forgejo is driven with ad-hoc `curl` and Python snippets Agents talk to the Forgejo API with hand-written `curl` calls and inline Python (`urllib`) to list PRs, post comments, create issues, set labels and merge. This has several costs: - it's verbose and error-prone (quoting, JSON escaping); - it's slow to review; - it spreads the API token across command lines. The token is also embedded in the `origin` remote URL. `docs/agents/issue-tracker.md` documents only the raw REST endpoints. ## Proposal ### A. Workspace rule (AGENTS.md) - **Every agent works in its own git worktree**, e.g. `git worktree add ../hikcentral-wt<topic> <branch>` or one under the agent's scratchpad, and removes it when done. - **The main folder is the maintainer's.** Agents never run `switch`/`checkout`/`stash`/`reset`/commit there, and never stash or discard changes they did not make. - **Before committing, check you are where you think you are** (`git status -sb` shows the expected branch). If anything looks foreign, stop and report instead of "cleaning up". - **Sub-agents run in throwaway worktrees**, which the code-review skill already requires. ### B. Forgejo CLI - Install a Forgejo-capable CLI, authenticated once through its own config (not tokens on command lines). Candidates: - **`tea`**: Gitea's official CLI; works against Forgejo's Gitea-compatible API. - **`fj` (forgejo-cli)**: Forgejo-native. - Document it in `docs/agents/issue-tracker.md` and reference it from AGENTS.md "Agent skills". Include the exact commands for what agents do today: - list open PRs and issues; - read a PR or issue with its comments; - create an issue with labels; - comment on a PR or issue; - set labels; - edit a PR body, or retarget its base; - merge with a merge commit, custom title and branch deletion. - Agents use the CLI instead of `curl`/Python for these operations. Keep the REST endpoints as a fallback only. - Consider moving the token out of the `origin` remote URL into a credential helper once the CLI holds its own login. ## Open decisions (hence `needs-triage`) 1. `tea` or `fj`: both work. `tea` is more mature; `fj` is Forgejo-native. Check which one supports every operation above, especially merge with a custom title and `delete_branch_after_merge`. 2. How it's installed: system package, Go/Cargo binary, or a pinned download recorded in the repo like the Tailwind binary (#57). 3. Whether the workspace rule should also be enforced by a hook, e.g. refusing commits from agents in the main folder. The existing `git-guardrails` skill could do this. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

gabogg added the

needs-triage

label

2026-09-25 19:10:24 +00:00

gabogg commented

2026-09-26 21:23:50 +00:00

Author

Owner

Implemented by #139 (c096d72) and hardened by #141 (02f0971):

Workspace rule: one git worktree per branch under .worktrees/, managed by scripts/wt (new, pr, ls, rm, prune). The main checkout stays on a clean master. Ownership is defined by uncommitted or unpushed work, and wt pr refuses to hand over a worktree someone is still working in. Set work aside with WIP commits instead of the shared stash. See docs/agents/workspaces.md; AGENTS.md §4 points to it.
Forgejo CLI: tea 0.16.0, which also acts as git's HTTPS credential helper. The token was removed from the origin remote URL. See docs/agents/forgejo-cli.md; issue-tracker.md no longer lists raw REST endpoints.

Remaining follow-ups live in #140. Closing.

Implemented by #139 (`c096d72`) and hardened by #141 (`02f0971`): - **Workspace rule:** one git worktree per branch under `.worktrees/`, managed by `scripts/wt` (`new`, `pr`, `ls`, `rm`, `prune`). The main checkout stays on a clean `master`. Ownership is defined by uncommitted or unpushed work, and `wt pr` refuses to hand over a worktree someone is still working in. Set work aside with WIP commits instead of the shared stash. See `docs/agents/workspaces.md`; AGENTS.md §4 points to it. - **Forgejo CLI:** `tea` 0.16.0, which also acts as git's HTTPS credential helper. The token was removed from the `origin` remote URL. See `docs/agents/forgejo-cli.md`; `issue-tracker.md` no longer lists raw REST endpoints. Remaining follow-ups live in #140. Closing.

gabogg closed this issue

2026-09-26 21:23:51 +00:00