f0rge — outline

Status: committed build. Scope: the coordination layer — a git forge that lives inside the repository, built for one person and a swarm of agents, with the grammar of gh.

1. Thesis

f0rge is gh with a different backend. Same commands, same flags, same --json fields the models are already trained on — but instead of talking to api.github.com, it reads and writes files under .forge/.

Built for one person and a swarm of agents. You do not need a team of people to work on a thing; you need a team of agents, and they already speak gh. The repo is simultaneously the product, the payload, and the protocol. No server, because it was never a server question: one person does not need federation — they need a local forge their agents already know how to use.

2. The model (one owner, many agents)

• One owner, N agents. You are the only human, the only merge authority, the only policy-setter. Nothing enforces; .forge/merges/ records.
• The contract lives in the CLI, not the repo: f0rge --skill prints the convention (schema, naming rules, grammar) cold to any agent. No README in .forge/ — the repo is data; the CLI is the spec. Schema drift is a CLI-version question, not a self-modifying-doc one.
• Every copy of the repo is coincidentally a complete forge — zip it, hand it over: full git, full .forge/ state, and the grammar comes from the CLI the recipient already has. Free property, not the story. No canonical remote unless you declare one.
• Agent worktrees are the unit of work. Parallelism is structural: disjoint worktrees, disjoint files, one trunk, merges serialized onto main. Collisions are designed for, not feared: when they happen (shared files, shared forge state) an agent reconciles them inline as part of the ritual. f0rge merge is a helper, not a flagship.
• Work claims: when two agents both want the same issue, assignee + state: in-progress is the claim; agents respect it.
• A PR is a folder: patch or branch, plus .forge/prs/<uuid>/ record (base, title, issue links, CI verdict). It crosses machine boundaries by hand (zip, USB, or a plain bare remote between your own machines), and you decide whether it merges.

3. Coordination protocol (the agent workflow)

f0rge is the postal system of the swarm: issues are the queue, PRs are deliverables, CI is the gate, the wiki is memory, merges are the record.

agent starts in its own worktree (a herdr pane)
  → takes an issue from .forge/issues/                    (claims it)
  → does the work, scripts verify with .forge/ci/
  → files a PR folder back (diff + .forge/prs/<uuid>/ record)
  → you (or an agent under your policy) merge it onto main
  → merge record lands in .forge/merges/

• CI runs in the PR before merge; main stays green by construction.
• Forge state flows through the same pipeline as code: an agent's edits to issues, comments, and wiki arrive inside its PR diff and merge the same way. No second channel.

4. Feature surface

gh-literal where gh exists; better than gh where gh has nothing. The prior is a tool, not a cage — but the default is: same grammar.

Port as gh (models are trained on gh; keep the muscle memory):

• Issues: create, list, get, comment, close, reopen, assign, label, search — --title, --body, --label, --assignee, --milestone.
• PRs: create, diff, review/comment, merge, close — --base / --head / --draft.
• Labels, milestones: list, create, edit, delete.
• CI: run, list, view, watch, status, log, rerun, cancel — mirroring gh run.
• Releases: create, list, view.
• --json / --jq on every command, field names matching gh's output schemas (number,title,state,labels,assignees,milestone,body, databaseId,status,conclusion, …). Never parse human text.

The one deliberate difference: there is no gh api — the files are the API; any agent already in the repo reads and edits .forge/ directly.

Better than gh (nothing to inherit):

• Wiki: a coherent markdown home for docs, research, and experiment records — the swarm's persistent project memory; the antidote to scattering and compaction. gh has no wiki surface at all.
• Todo/kanban: cards in .forge/tasks/; columns derived from status, never stored.
• Local CI: .forge/ci/steps/ scripts run by a thin skill; local, dockerised, or remote per what each repo's scripts say. Runs recorded as files, gitignored — the verdict is the durable record.
• Releases: per-version notes plus build/ scripts that checkout a tag and build binaries per platform. No binaries stored; out/ gitignored.
• f0rge init — bootstrap the skeleton. f0rge --skill — the contract.
• f0rge merge — reconcile two divergent states (code and forge state); a utility for imports and conflict resolution, not a ceremony between civilizations.

Explicitly not ported from gh: hosting commands (repo create/fork/…), auth, api, secret, gist, codespace, browse — server creatures.

5. Storage layout

.forge/                          # no README — contract is `f0rge --skill`
├── issues/<uuid>/issue.md       # frontmatter + body; comments/<uuid>.md
├── prs/<uuid>/pr.md             # base/head, reviews, merge state
│                                #   + patch.diff; comments/
├── tasks/<uuid>.md              # todo/kanban cards; column = status
├── labels.md  ·  milestones.md
├── wiki/                        # docs/, research/, experiments/;
│                                #   index.md derived
├── ci/
│   ├── ci.env                   # optional non-secret knobs
│   ├── steps/                   # ordered by filename (00_fmt.sh, 10_check.sh)
│   └── runs/<ts>/               # gitignored: summary.md + steps/<name>.log
├── releases/
│   ├── <version>.md             # release notes
│   ├── build/                   # checkout-and-build per platform
│   └── out/                     # built artifacts, gitignored
└── merges/<ts>.md               # import/conflict records

Rules: UUIDs for identity (numbers are derived aliases, never references); one file per entity (git merges independently); indexes derived, never stored (issue numbering, kanban columns, wiki index); frontmatter for structure, markdown for prose; exit code as CI verdict. Everything versioned except releases/out/ and ci/runs/. .forge/ is committed by default; it is the state.

6. Agent story

• gl0w files an issue, reviews a PR, reads CI logs, edits the wiki — via the f0rge CLI wrapped in a skill whose whole text is: "f0rge is gh; same flags, same --json. Files instead of api.github.com. Run f0rge --skill / f0rge --help."
• The swarm runs itself: worktrees as workers, issues as the queue, PRs as deliverables, CI as the gate, the wiki as memory that survives compaction. You are the owner of the only repo that matters; the agents staff the whole pipeline.
• When two agents touch the same file, a third reconciles; you are never in the loop unless policy says so.

7. Stances (resolved)

• Merge authority: the owner — you, or an agent under your trust policy. Nothing enforces; the record logs.
• CI isolation: per-side posture per payload, under the running agent's permission mode; docker/sandbox when the payload is untrusted.
• Secrets: your keychain/env; never in repo or payload. A rule, not a feature.
• The CLI is a thin script over the files; markdown is the truth, the CLI is the enforced view, the skill stays one line, the contract is --skill.
• Portability (zip / USB / bare remote between your own machines) is a free property of files-in-git, not an interface to design for.
• Server: optional rendezvous later, and only as a sync point between your own endpoints; nothing depends on it.

8. Open questions

• Where CI runs day to day (local shell, docker, herdr panes, later runners).
• Claim semantics under concurrency: is assignee + state: in-progress enough, or do agents need a lock/heartbeat to avoid dueling on one issue?
• Ghost-issue duplicates: two agents independently file the same task → two UUIDs, two numbers, no way to know. Does f0rge merge need a "did this already land?" check?
• Schema evolution: how the --skill contract version migrates across existing .forge/ stores (CLI knows schema N and N−1, one hop).
• Trust boundary: ci/steps/ arrive inside PRs — what runs bare vs. sandbox, and who decides (owner policy, or per-repo posture in ci.env)?
• gooey rendering forge state later; ch4t never touches it; cl0ud stays separate.

9. Relationship to the world

• gl0w: the worker; primary user of f0rge via CLI + skills.
• herdr fork: the housing; agent panes are the worktrees.
• swarm (tooey/gooey): gooey can render forge state later; nothing blocks.
• wr1te: the human editor for wiki pages, issue bodies, release notes.
• cl0ud: separate by design; cl0ud is user data, f0rge is repo-bound.
• ch4t: separate; could file results into a repo if it ever earns it.

10. Resolved from §8 (M8 hardening; §8 kept as asked)

• CI home: local shell day to day; docker per payload via ci.env (runner:) or --docker. Posture explicit, never implicit.
• Claims: assignee + state: in-progress is the claim. No locks/heartbeats — collisions reconcile by agent, not by tool.
• Duplicates: patch-hash check against merges/ history; replays report and stop.
• Schema: CLI knows N and N-1; older marker warns one line naming the file and keeps going (one hop).
• Trust: PR steps run under the posture the merging side chooses; forge injects no secrets, .forge/ gets no special trust.
• Rendering: gooey may render later; ch4t never touches forge state.