AI Factory (Forgejo + opencode)

A personal AI software factory: discuss a specification with an agent in Forgejo issues, then let it implement the spec and open a pull request.

 you ──issue+label `agent`──▶ PLAN agent (read-only) ──comments──▶ you
                                │  every reply ends with a spec block
 you ──edit spec / discuss──────┘
 you ──label `build`─────────▶ BUILD agent ──branch `agent/issue-N` + PR──▶ you review & merge

How it works

• Entry points: add the agent label to an issue (or comment @agent plan).

• Plan phase: a read-only opencode agent (bash/edit denied via agent permissions) explores the repo and discusses in issue comments. Every reply ends with the current spec inside invisible markers:

  <!-- opencode:spec:start -->
  # Spec: ...
  <!-- opencode:spec:end -->
  

  You can edit the spec directly in the comment — the build always picks the last spec block in the thread (issue body as fallback).

• Build phase: add the build label (or comment @agent build). The build agent implements the spec on branch agent/issue-N, force-pushes it and opens a PR that links back and closes the issue on merge.

• Memory: the issue thread is the memory — each run re-reads the full thread. Plan sessions are additionally resumed by title when possible.

Repository layout

Path	Purpose
.forgejo/workflows/agent.yml	Reusable workflow called by project repos
examples/project-agent.yml	Thin workflow to copy into each project repo
image/Dockerfile	Agent image (opencode + glue), pushed to the Forgejo registry
glue/	TypeScript glue: fetch thread → prompt → opencode run → comment/PR
docs/setup.md	Full setup guide (bot, secrets, labels, protection)

Design decisions

• Thread-as-memory over persisted LLM sessions: stateless, auditable, crash-tolerant; users repair context by editing comments.
• Spec lives in comments (not in git): editable by the human, visible in the discussion, machine-parsed by the glue.
• Dedicated bot user + PAT: makes the self-trigger guard trivial (ignore the bot's own comments) and scopes what a hijacked agent can do.
• CI-model (batch): each hop is a fresh container. Slow (~1 min) but isolated and reproducible.
• Human gate: agent never pushes the default branch; everything lands via PRs you review.

Security notes

• Issue text is untrusted input to an agent that executes code by design. On a private single-user instance the risk is mostly cost/quality, but: the bot PAT is scoped to write:repository + write:issue, the default branch is push-protected, agents are instructed never to touch workflow files, and provider keys live in repo secrets — never in the image.
• Never expose the runner or the registry publicly without revisiting this.

Limitations (v1)

• Comments on pull requests are ignored (natural place for a future reviewer agent).
• Cross-repo reusable workflows require this repo to be public on the instance (fine behind a firewall; see docs/setup.md for the private workaround).
• One build label = one rebuild: build runs force-push agent/issue-N.
• No cost dashboards yet; check opencode stats inside a job or the run logs.

Quickstart

See docs/setup.md.