@thegpvc/gp-foundry 0.1.0 → 0.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -2,36 +2,36 @@
2
2
 
3
3
  **Stand up a "dark factory" for your repo: issues in → reviewed, auto-merged PRs out.**
4
4
 
5
- `gp-foundry` turns an autonomous agent pipeline into something you **declare once as a
6
- directed graph and compile** into a repo. You describe the crew and the flow in a single
7
- `harness.dot`; a deterministic compiler emits plain GitHub Actions workflows; **GitHub stays
8
- the executor** (native events, per-job least-privilege, Environment approvals, secrets,
9
- scheduling). The result runs with minimal effort and keeps itself alive: it is
10
- **self-healing** (rebases conflicts, re-drives stranded work, escalates to a human only when
11
- truly stuck) and **self-improving** (mines its own merged PRs and reviews for recurring
12
- lessons and feeds them back to every agent). Nothing here is code-specific — the same shape
13
- that ships a library can ship docs, marketing copy, or config.
5
+ `gp-foundry` lets you **declare an autonomous agent pipeline as a directed graph and compile
6
+ it** into a repo. You describe the crew and the flow in one `harness.dot`; a deterministic
7
+ compiler emits plain GitHub Actions workflows. There's no orchestrator to run — **GitHub is
8
+ the executor** (native events, per-job least-privilege, Environment approvals, secrets, cron).
9
+
10
+ The pipeline keeps itself moving: it's **self-healing** (rebases conflicts, re-drives
11
+ stranded work, escalates to a human only when truly stuck) and **self-improving** (mines its
12
+ own merged PRs and reviews for recurring lessons, then feeds them back to every agent). And
13
+ it isn't code-specific — the same shape that ships a library can ship docs or marketing copy.
14
14
 
15
15
  ## Why this exists (and what it deliberately isn't)
16
16
 
17
- Most agent-pipeline systems ship an **orchestrator**: a long-running engine that walks the
18
- graph, holds state, and executes agents (StrongDM's Attractor is the best-articulated
19
- version — gp-foundry borrows its DOT-graph representation directly). That model buys rich
20
- control flow and millisecond hops, at the price of a new stateful service you must deploy,
21
- secure, and trust. gp-foundry makes the opposite bet: **compile the graph away and let
22
- GitHub be the executor.** There is no server — state lives in labels, PRs, reviews, and
23
- cron; every transition is an artifact your team already knows how to read *and override*;
24
- and the compiler can verify the topology (bounded loops, livelock detection) before
25
- anything runs.
26
-
27
- The honest cost: everything must round-trip through GitHub-observable events. Hops take
28
- minutes, not milliseconds; gates poll on cron; rich dataflow between agents is reduced to
29
- labels and comment markers; and GitHub's event model has sharp edges the runtime works
30
- around rather than owns. gp-foundry targets the **issue → PR → review → merge granularity**
31
- — where hops are naturally slow and auditability matters more than latency — and covers
32
- that case with roughly 1% of the infrastructure. If you need tight multi-agent
33
- choreography, dynamic subgraphs, or streaming state between nodes, run an orchestrator;
34
- this isn't one.
17
+ Most agent-pipeline systems ship an **orchestrator** — a long-running engine that walks the
18
+ graph, holds state, and runs the agents. (StrongDM's Attractor is one well-articulated
19
+ example; gp-foundry borrows its DOT-graph representation.) That buys rich control flow and
20
+ fast hops, but it's a stateful service you have to deploy, secure, and trust.
21
+
22
+ gp-foundry takes the opposite bet: **compile the graph away and let GitHub run it.** No
23
+ server — state lives in labels, PRs, reviews, and cron. Every transition is an artifact your
24
+ team already knows how to read *and override*, and the compiler checks the topology (bounded
25
+ loops, livelock detection) before anything runs.
26
+
27
+ The cost is real: everything round-trips through GitHub-observable events. Hops take minutes,
28
+ not milliseconds; gates poll on cron; data between agents narrows to labels and comment
29
+ markers; and GitHub's event model has sharp edges the runtime works around rather than owns.
30
+
31
+ So gp-foundry aims at one altitude — **issue → PR → review → merge** — where hops are slow
32
+ anyway and auditability matters more than latency, and it covers that without running any
33
+ infrastructure of its own. Need tight multi-agent choreography, dynamic subgraphs, or
34
+ streaming state between nodes? Run an orchestrator — this isn't one.
35
35
 
36
36
  ## Zero-install: point your coding agent at this
37
37
 
@@ -41,9 +41,9 @@ The fastest path — don't install anything yourself. Paste this into your codin
41
41
  > Fetch https://unpkg.com/@thegpvc/gp-foundry/AGENTS.md and follow it to set up an
42
42
  > autonomous delivery pipeline in this repository.
43
43
 
44
- [`AGENTS.md`](./AGENTS.md) walks the agent through the whole bring-up via `npx` (no global
45
- install): scaffold, adapt the toolchain/scope/roles to the repo with you, `up`, and the
46
- two secrets only a human can set. Claude Code agents are steered to the richer
44
+ [`AGENTS.md`](./AGENTS.md) walks the agent through the bring-up via `npx` — no global
45
+ install: scaffold, adapt the toolchain/scope/roles with you, run `up`, then hand off the two
46
+ secrets only a human can set. Claude Code agents get steered to the richer
47
47
  [Socratic skill](#or-set-it-up-conversationally-the-claude-skill) instead.
48
48
 
49
49
  ## Dark factory in 6 commands
@@ -102,10 +102,10 @@ takes an issue from triage to merge, plus the lanes that keep the factory health
102
102
  | 🕵️ | scout | Triage an incoming issue; label it for a lane (`build` / `plan`). |
103
103
  | 📋 | planner | For big/ambiguous issues, post a plan before any code is written (read-only). |
104
104
  | 👷 | builder | Turn a labeled issue into a small, tested, shippable PR (the only code-writer). |
105
- | 👩‍⚖️ | reviewer | Read the diff, run gates, post an approve / request-changes verdict. |
106
- | 🧑‍🔧 | fixer | Apply review feedback in a bounded retry loop with the reviewer. |
105
+ | ⚖️ | reviewer | Read the diff, run gates, post an approve / request-changes verdict. |
106
+ | 🔧 | fixer | Apply review feedback in a bounded retry loop with the reviewer. |
107
107
  | 🧹 | janitor | Scheduled sweep: rebase PRs the gate flagged `needs-rebase` so they can merge. |
108
- | 🧑‍✈️ | supervisor | Scheduled sweep: re-drive stranded issues/PRs; escalate to `needs-human` after 2 nudges. |
108
+ | 🧭 | supervisor | Scheduled sweep: re-drive stranded issues/PRs; escalate to `needs-human` after 2 nudges. |
109
109
  | ♻️ | retro | Scheduled: mine merged PRs/reviews/CI for recurring lessons; write them to team memory. |
110
110
  | 🔀 | merge_gate | **Policy gate, not a persona** — enforces merge policy (approval, CI green, size, protected paths); auto-merges or labels `needs-rebase`/`needs-human`. |
111
111
 
@@ -169,15 +169,15 @@ unbounded loops at build time. Full vocabulary in
169
169
 
170
170
  ## Self-healing & self-improving
171
171
 
172
- **Self-healing** — the factory does not silently stall:
172
+ **Self-healing** — stuck work gets re-driven or escalated, not left silently stranded:
173
173
  - 🧹 **janitor** runs on a schedule and rebases every PR the merge gate flagged
174
174
  `needs-rebase`, so conflicts don't strand mergeable work.
175
- - 🧑‍✈️ **supervisor** runs on a schedule, re-drives stranded issues and PRs (no PR for a
175
+ - 🧭 **supervisor** runs on a schedule, re-drives stranded issues and PRs (no PR for a
176
176
  `build`-labeled issue, idle PRs), and escalates to `needs-human` after 2 nudges.
177
177
  - The **merge gate** posts a 🔀 audit comment explaining each decision and labels
178
178
  `needs-rebase` on conflicts rather than merging a broken state.
179
179
  - Agent **failures are visibly red** — no green no-ops. A failing job fails the run.
180
- - The 🧑‍🔧 **fixer** has a real attempt budget: it stamps a marker comment each attempt and,
180
+ - The 🔧 **fixer** has a real attempt budget: it stamps a marker comment each attempt and,
181
181
  at `max_attempts`, labels the PR `needs-human` and stops instead of looping forever.
182
182
 
183
183
  **Self-improving** — the factory learns from its own record:
@@ -198,11 +198,9 @@ unbounded loops at build time. Full vocabulary in
198
198
  human-gate as mandatory for anything irreversible. The reviewer is also an LLM — the
199
199
  gate's policy (CI green, size caps, protected paths) is the non-negotiable backstop.
200
200
  - **Limits** — `parallel`/`fan_in` support **clean diamonds only** (one fan-out event, ≥2
201
- agent lanes, one join): the diamond compiles to a single workflow whose fan_in job
202
- `needs:` the lane jobs. Staggered/non-diamond joins are a v2 concern. Merges are
203
- serialized one per gate sweep.
204
- Cross-workflow races (e.g. janitor and fixer pushing together) resolve by retry, not
205
- transactions — the supervisor sweep is the safety net.
201
+ agent lanes, one join); staggered/non-diamond joins are a v2 concern. Merges are serialized
202
+ one per gate sweep. Cross-workflow races (e.g. janitor and fixer pushing at once) resolve by
203
+ retry, not transactions — the supervisor sweep is the safety net.
206
204
 
207
205
  ## Day-2 operations
208
206
 
@@ -242,7 +240,7 @@ spec change and the regenerated workflows together so `build --check` stays gree
242
240
  | `roles/` | generic role packs (`software/`, `content/`, `docs/`) — the job descriptions |
243
241
  | `skill/` | the packaged Claude skill: `SKILL.md`, `reference/`, and the scaffolding `templates/` |
244
242
  | `schema/` | JSON Schema for `foundry.config.yaml` |
245
- | `examples/` | example harness specs (`examples/dixie/`, `examples/marketing/`) |
243
+ | `examples/` | a complete reference harness — [`examples/starter/`](./examples/starter/), exactly what `init` scaffolds |
246
244
  | `docs/` | design docs (`docs/plans/`) |
247
245
 
248
246
  ## Docs