# 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.