The plugin uses the Paseo 0.8 layout (index.client.tsx / index.server.ts\nentries, client/ / server/ / shared/ split, manifest\nrequirements.paseo >= 0.8.0).
paseo plugin add xpufx/paseo --path plugins/forges\nOr from a local monorepo checkout:
\npaseo plugin add ./plugins/forges\n![\"Forges](\"screenshots/forge-main.png\")
| ![\"Forge](\"screenshots/forge-list.png\")
| ![\"Forge](\"screenshots/forge-issue-detail.png\")
|\n\n## Highlights\n\n- **No CLI dependency.** All forge access goes through an embedded TypeScript\n `fetch` client (`server/forge-client.ts`) against the Gitea-family\n `/api/v1`. There is no `git`/`fgj`/`fgjx` subprocess and no dependency on any\n host dotfile.\n- **Daemon-side tokens.** The API token is stored per host in plugin settings\n and only ever attached to `fetch` calls in the daemon. It never reaches the\n client.\n- **Live label vocabulary.** Scopes are derived from the labels actually on the\n board, so a foreign board degrades gracefully instead of failing on an\n unknown scope.\n- **Paged reads.** Issue list, keyword search, label list, and comment list are\n all collections: each call returns **one page**, and the default page size is\n **server-defined and can change**. Treat every list as paged\n (`limit`/`page`, or follow `Link`/`X-Total-Count`) instead of assuming a\n single call is complete; one unpaged call is never evidence of \"no results\".\n A surface that lists results should page internally rather than render a\n truncated set (#189).\n- **Example skills.** Our agent workflow ships under `examples/` as a starting\n point to adapt (see [`examples/README.md`](./examples/README.md)).\n\nSupported forges (verified live, anonymous reads): any Forgejo/Gitea-family\nhost, including Forgejo, Gitea, and Codeberg.\n\n## Workflow Augmentation: Turn Issues into Agent Fleet Automation\n\nOut of the box, `forges` gives you in-app issue management, scoped label chips, and steering comments directly inside Paseo.\n\nWhen augmented with our scoped label taxonomy and lightweight webhook bridge ([`examples/hook-service/`](./examples/hook-service/)), `forges` becomes an autonomous agent coordination layer:\n\n- **Automated Webhook Ingestion:** New issues, label edits, or comments on your forge immediately dispatch events to your orchestrator agent via Paseo's agent transport.\n- **Autonomous Agent Handoffs:** Coding agents pick up assigned tickets, transition `state/` chips (`0-triage` → `1-wip` → `2-review` → `3-verify` → `4-done`), publish structured status envelopes, and pass attention back to the operator when human signoff is required.\n- **Drop-In Scoped Label Taxonomy:** Seed our four core scopes (`state/`, `priority/`, `attention/`, `spec/`) using the generic template in [`examples/labels/label-base.yaml`](./examples/labels/label-base.yaml).\n- **Adaptable Agent Skills:** Ships with zero-CLI skills (using plugin `/api/v1` RPCs directly) as well as CLI-assisted workflows ([`examples/skills/`](./examples/skills/)).\n\nSee [`docs/workflow.md`](./docs/workflow.md) for the end-to-end architecture and [`examples/README.md`](./examples/README.md) for starter templates.\n\n## Install\n\nThe plugin uses the Paseo 0.8 layout (`index.client.tsx` / `index.server.ts`\nentries, `client/` / `server/` / `shared/` split, manifest\n`requirements.paseo >= 0.8.0`).\n\n```sh\npaseo plugin add xpufx/paseo --path plugins/forges\n```\n\nOr from a local monorepo checkout:\n\n```sh\npaseo plugin add ./plugins/forges\n```\n\n## Configuration\n\nOpen the plugin's **Settings** tab inside a workspace.\n\n- **Active forge.** Each workspace watches one active forge at a time. The\n list holds the workspace's forge remotes (any `parseForgeRemote` form plus\n a bare `owner/repo`); **Auto** derives the remote from the workspace's git\n `origin`. An explicit selection wins absolutely: an invalid or unreachable\n selection fails loudly instead of silently deriving.\n- **API token.** Saved per host in daemon-side plugin settings. Reads work\n anonymously on public repos; labels and comments need an accepted token with\n write scope on both public and private repos. For Forgejo/Gitea create the\n PAT with `read:user`, `read:repository`, and `write:issue` (add\n `write:repository` if label management still 403s). Edit capability is read\n from the repo's permission object (`permissions.push`/`admin`, or GitLab\n `access_level >= 30`), so a token that is accepted but under-scoped shows\n \"token lacks write scope\" instead of enabling edits.\n\n## Development\n\n```sh\nnpm install --workspace=plugins/forges\nnpm run typecheck --workspace=plugins/forges\nnpm test --workspace=plugins/forges\n```\n\nThe helper audit also applies:\n\n```sh\nnode packages/paseo-plugin-helper/bin/paseo-plugin-helper.js audit plugins/forges\n```\n\nSee [`docs/specs/forge-workflow-gui.md`](./docs/specs/forge-workflow-gui.md)\nfor the data model, RPC contracts, and UI surfaces, and\n[`docs/workflow.md`](./docs/workflow.md) for the end-to-end agent workflow\n(hook service, label usage, agent responsibilities, and what the plugin ships\nversus what an adopter supplies).\n"}