@thegpvc/gp-foundry 0.1.0
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/AGENTS.md +89 -0
- package/LICENSE +21 -0
- package/README.md +270 -0
- package/actions/agent-context/README.md +67 -0
- package/actions/agent-context/action.yml +33 -0
- package/actions/agent-fallback/README.md +89 -0
- package/actions/agent-fallback/action.yml +204 -0
- package/actions/config-loader/README.md +81 -0
- package/actions/config-loader/action.yml +50 -0
- package/actions/dependency-chain/README.md +116 -0
- package/actions/dependency-chain/action.yml +57 -0
- package/actions/merge-gate/README.md +111 -0
- package/actions/merge-gate/action.yml +60 -0
- package/actions/run-agent/README.md +75 -0
- package/actions/run-agent/action.yml +213 -0
- package/actions/sanitize-untrusted-input/README.md +110 -0
- package/actions/sanitize-untrusted-input/action.yml +47 -0
- package/actions/setup-agent/README.md +51 -0
- package/actions/setup-agent/action.yml +100 -0
- package/actions/wait-for-checks/README.md +91 -0
- package/actions/wait-for-checks/action.yml +58 -0
- package/dist/cli/index.cjs +130 -0
- package/package.json +79 -0
- package/roles/README.md +124 -0
- package/roles/content/brand-critic.md +64 -0
- package/roles/content/brief-triager.md +58 -0
- package/roles/content/copywriter.md +55 -0
- package/roles/content/editor.md +51 -0
- package/roles/docs/reviewer.md +62 -0
- package/roles/docs/writer.md +54 -0
- package/roles/software/builder.md +28 -0
- package/roles/software/fixer.md +26 -0
- package/roles/software/janitor.md +30 -0
- package/roles/software/planner.md +29 -0
- package/roles/software/retro.md +42 -0
- package/roles/software/reviewer.md +27 -0
- package/roles/software/scout.md +30 -0
- package/roles/software/supervisor.md +52 -0
- package/schema/config.schema.json +167 -0
- package/skill/SKILL.md +280 -0
- package/skill/reference/cli.md +108 -0
- package/skill/reference/node-types.md +99 -0
- package/skill/reference/role-packs.md +95 -0
- package/skill/templates/agent-setup.yml +15 -0
- package/skill/templates/communication.md +64 -0
- package/skill/templates/foundry.config.yaml +49 -0
- package/skill/templates/harness.dot +54 -0
- package/skill/templates/policy-merge.yaml +54 -0
- package/skill/templates/role.md +33 -0
- package/skill/templates/scope.yaml +21 -0
package/AGENTS.md
ADDED
|
@@ -0,0 +1,89 @@
|
|
|
1
|
+
# gp-foundry — agent bootstrap
|
|
2
|
+
|
|
3
|
+
<!-- Contributing to gp-foundry itself? This file is the CONSUMER bootstrap (setting up a
|
|
4
|
+
pipeline in another repo). For hacking on gp-foundry, see README.md → Development. -->
|
|
5
|
+
|
|
6
|
+
> **You are a coding agent.** A human pointed you here to set up an autonomous delivery
|
|
7
|
+
> pipeline ("dark factory") in the repository you're working in: issues in → triaged,
|
|
8
|
+
> planned, implemented, reviewed, auto-merged PRs out — self-healing and self-improving.
|
|
9
|
+
> Follow this file top to bottom. Requires Node >= 20 and a git repo; the `gh` CLI
|
|
10
|
+
> (authenticated) makes setup fully automatic but is optional until push time.
|
|
11
|
+
|
|
12
|
+
Everything runs through `npx` — **no global install needed**.
|
|
13
|
+
|
|
14
|
+
## If you are Claude Code: install the skill and use it instead
|
|
15
|
+
|
|
16
|
+
```bash
|
|
17
|
+
npx -y @thegpvc/gp-foundry@latest skill
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
Then follow `.claude/skills/gp-foundry/SKILL.md` — it is the richer, Socratic version of
|
|
21
|
+
this file (a five-question interview that designs the pipeline with the user). Everything
|
|
22
|
+
below is the condensed flow for agents without skill support.
|
|
23
|
+
|
|
24
|
+
## 1. Scaffold
|
|
25
|
+
|
|
26
|
+
```bash
|
|
27
|
+
npx -y @thegpvc/gp-foundry@latest init
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
This writes `.github/harness.dot` (the pipeline as a DOT graph — the single source of
|
|
31
|
+
truth), `.github/agents/` (config, scope, merge policy, communication guide, and a role
|
|
32
|
+
file per agent: scout/planner/builder/reviewer/fixer/janitor/supervisor/retro), and
|
|
33
|
+
`.github/agent-setup/action.yml`.
|
|
34
|
+
|
|
35
|
+
## 2. Adapt to this repo (ask the user; don't guess silently)
|
|
36
|
+
|
|
37
|
+
Confirm with the user, then edit:
|
|
38
|
+
|
|
39
|
+
- **`.github/agent-setup/action.yml`** — add the project's toolchain (setup-python,
|
|
40
|
+
setup-go, pnpm, …) below the agent-CLI step, so pipeline agents can build and test.
|
|
41
|
+
- **`.github/agents/scope.yaml`** — what must agents NEVER touch (`immutable_paths`)?
|
|
42
|
+
Add the repo's build/test commands to `guidance:` (e.g. "run `make test` before any PR").
|
|
43
|
+
- **`.github/agents/roles/*.md`** — the "Repo-specific guidance" of `builder.md`,
|
|
44
|
+
`reviewer.md`, `fixer.md`: test commands, conventions, gotchas. Role edits need no rebuild.
|
|
45
|
+
- Optional topology changes (add/remove lanes) go in `.github/harness.dot` — never edit
|
|
46
|
+
`.github/workflows/*.yml` by hand; they are generated.
|
|
47
|
+
|
|
48
|
+
## 3. Bring the factory up
|
|
49
|
+
|
|
50
|
+
```bash
|
|
51
|
+
npx -y @thegpvc/gp-foundry@latest up
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
Creates the labels (`build`/`plan`/`needs-human`/`needs-rebase`), vendors the runtime
|
|
55
|
+
actions into `.github/actions/`, compiles the workflows, and runs `doctor`. It exits
|
|
56
|
+
non-zero with specific ✗ items until the factory is ready — fix what it names and re-run.
|
|
57
|
+
(Offline/no-remote? It skips the GitHub steps cleanly; re-run after `gh repo create`.)
|
|
58
|
+
|
|
59
|
+
## 4. Hand two secrets to the human (you cannot do this part)
|
|
60
|
+
|
|
61
|
+
Tell the user to run:
|
|
62
|
+
|
|
63
|
+
```bash
|
|
64
|
+
gh secret set CLAUDE_CODE_OAUTH_TOKEN # the coding agent's auth token
|
|
65
|
+
gh secret set AGENT_PAT # fine-grained PAT: Contents + Pull requests + Issues + Actions, RW, this repo
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
(`AGENT_PAT` exists because the built-in `GITHUB_TOKEN` cannot trigger downstream
|
|
69
|
+
workflows — the pipeline would silently stall between stages.)
|
|
70
|
+
|
|
71
|
+
## 5. Ship it
|
|
72
|
+
|
|
73
|
+
```bash
|
|
74
|
+
git add .github && git commit -m "add agent harness (gp-foundry)" && git push
|
|
75
|
+
npx -y @thegpvc/gp-foundry@latest doctor # everything green?
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
Then have the user **file an issue** describing a small change. The 🕵️ scout triages it
|
|
79
|
+
within a minute and the factory takes it from there. Day-2: `npx -y @thegpvc/gp-foundry@latest status`
|
|
80
|
+
shows work in flight and anything stalled; add `gp-foundry build --check` to CI as a
|
|
81
|
+
drift gate.
|
|
82
|
+
|
|
83
|
+
## Rules you must respect afterwards
|
|
84
|
+
|
|
85
|
+
1. `.github/workflows/*.yml` are **generated** — change `.github/harness.dot` and re-run
|
|
86
|
+
`npx -y @thegpvc/gp-foundry@latest build`, never hand-edit.
|
|
87
|
+
2. Role/policy/scope files are runtime content — edit freely, no rebuild needed.
|
|
88
|
+
3. Every retry loop in the graph must keep a bounded escape edge (the default graph's
|
|
89
|
+
`fixer -> needs_human [when="attempts>=3"]`).
|
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 The General Partnership
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
ADDED
|
@@ -0,0 +1,270 @@
|
|
|
1
|
+
# gp-foundry
|
|
2
|
+
|
|
3
|
+
**Stand up a "dark factory" for your repo: issues in → reviewed, auto-merged PRs out.**
|
|
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.
|
|
14
|
+
|
|
15
|
+
## Why this exists (and what it deliberately isn't)
|
|
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.
|
|
35
|
+
|
|
36
|
+
## Zero-install: point your coding agent at this
|
|
37
|
+
|
|
38
|
+
The fastest path — don't install anything yourself. Paste this into your coding agent
|
|
39
|
+
(Claude Code, Cursor, or any agent with shell access), inside the target repo:
|
|
40
|
+
|
|
41
|
+
> Fetch https://unpkg.com/@thegpvc/gp-foundry/AGENTS.md and follow it to set up an
|
|
42
|
+
> autonomous delivery pipeline in this repository.
|
|
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
|
|
47
|
+
[Socratic skill](#or-set-it-up-conversationally-the-claude-skill) instead.
|
|
48
|
+
|
|
49
|
+
## Dark factory in 6 commands
|
|
50
|
+
|
|
51
|
+
```bash
|
|
52
|
+
npm i -g @thegpvc/gp-foundry
|
|
53
|
+
gp-foundry init # scaffold .github/harness.dot + config + roles + scope + policy
|
|
54
|
+
gp-foundry up # labels + vendor actions + build workflows + doctor
|
|
55
|
+
gh secret set CLAUDE_CODE_OAUTH_TOKEN # agent auth (paste the Claude Code OAuth token)
|
|
56
|
+
gh secret set AGENT_PAT # fine-grained PAT: Contents + Pull requests + Issues RW
|
|
57
|
+
git add .github && git commit -m "add agent harness" && git push
|
|
58
|
+
# then file an issue — the 🕵️ scout triages it and the factory takes it from there
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
`gp-foundry up` is offline-safe: it skips the `gh`-dependent steps (labels, doctor's
|
|
62
|
+
repo checks) cleanly when there's no GitHub remote yet, and builds the workflows regardless.
|
|
63
|
+
|
|
64
|
+
### Required secrets
|
|
65
|
+
|
|
66
|
+
| Secret | What it is | Scopes |
|
|
67
|
+
|--------|-----------|--------|
|
|
68
|
+
| `CLAUDE_CODE_OAUTH_TOKEN` | The coding agent's auth token — how each agent job authenticates to Claude Code. | n/a (agent credential) |
|
|
69
|
+
| `AGENT_PAT` | A fine-grained Personal Access Token used for the agents' git writes, PRs, and comments. Needed because pushes made with the built-in `GITHUB_TOKEN` do **not** trigger downstream workflows, so the pipeline couldn't cascade stage to stage. | Contents · Pull requests · Issues · Actions — **read/write**, scoped to this repo |
|
|
70
|
+
|
|
71
|
+
(`AGENT_PAT` is the default `auth.mode: pat`. You can instead run under a GitHub App
|
|
72
|
+
(`mode: app`, set `app_id_secret`/`app_key_secret`) or the built-in token (`mode:
|
|
73
|
+
github-token`, zero setup but no cascading) — see `foundry.config.yaml`.)
|
|
74
|
+
|
|
75
|
+
### Or: set it up conversationally (the Claude skill)
|
|
76
|
+
|
|
77
|
+
The package ships a **Claude skill** — a Socratic front door that interviews you about your
|
|
78
|
+
repo and builds the harness for you, instead of you editing the spec files by hand:
|
|
79
|
+
|
|
80
|
+
```bash
|
|
81
|
+
gp-foundry skill # install into this repo (.claude/skills/gp-foundry/)
|
|
82
|
+
gp-foundry skill --user # or once, for every project (~/.claude/skills/)
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
Then in Claude Code, type **`/gp-foundry`** — or just ask *"set up an agent pipeline for
|
|
86
|
+
this repo"*. The skill runs a five-question interview (what does this repo produce? who
|
|
87
|
+
approves? what must agents never touch? what roles and handoffs? what cadence and
|
|
88
|
+
identity?), drafts `harness.dot` + roles + policy from your answers, shows you the graph,
|
|
89
|
+
and then drives the same `gp-foundry` CLI — it never hand-writes workflow YAML. It also
|
|
90
|
+
handles **evolving** an existing harness ("add a docs lane", "tighten the merge gate").
|
|
91
|
+
|
|
92
|
+
The CLI quickstart above and the skill produce the same thing; the skill is for people who'd
|
|
93
|
+
rather answer questions than read `reference/node-types.md`.
|
|
94
|
+
|
|
95
|
+
## The crew
|
|
96
|
+
|
|
97
|
+
The default `init` scaffolds the **software pack** — an autonomous engineering team that
|
|
98
|
+
takes an issue from triage to merge, plus the lanes that keep the factory healthy.
|
|
99
|
+
|
|
100
|
+
| | Role | What it does |
|
|
101
|
+
|---|------|--------------|
|
|
102
|
+
| 🕵️ | scout | Triage an incoming issue; label it for a lane (`build` / `plan`). |
|
|
103
|
+
| 📋 | planner | For big/ambiguous issues, post a plan before any code is written (read-only). |
|
|
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. |
|
|
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. |
|
|
109
|
+
| ♻️ | retro | Scheduled: mine merged PRs/reviews/CI for recurring lessons; write them to team memory. |
|
|
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
|
+
|
|
112
|
+
Roles are generic; a consumer repo supplies its stack (label strings, build/test commands,
|
|
113
|
+
size thresholds, merge policy) via config and the `roles/*.md` overlay, never baked into the
|
|
114
|
+
role's contract.
|
|
115
|
+
|
|
116
|
+
## The DOT → Actions model
|
|
117
|
+
|
|
118
|
+
```
|
|
119
|
+
harness.dot ──▶ parse ──▶ validate ──▶ model-check ──▶ assemble ──▶ .github/workflows/*.yml
|
|
120
|
+
(topology) IR schema reachability fragments (GENERATED,
|
|
121
|
+
+ cycle bounds + wiring drift-checked)
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
- **Nodes are roles.** Each node has a `type` (mechanical: `analyst`, `issue-agent`,
|
|
125
|
+
`producer`, `pr-review`, `pr-fix`, `merge-gate`, `human-gate`, `scheduled-agent`, plus
|
|
126
|
+
`start`/`exit`) and a `role="agents/roles/<name>.md"` carrying the domain-specific job
|
|
127
|
+
description. The type is the GitHub interaction; the role is the behavior.
|
|
128
|
+
- **Edges are transitions.** Expressed only in GitHub-observable primitives
|
|
129
|
+
(`on="issues.opened"`, `when="label=build"`, `when="verdict=approve"`), so the
|
|
130
|
+
platform — not a bespoke engine — drives the loop.
|
|
131
|
+
- **Generated workflows are a build artifact.** Every emitted `.yml` (and `HARNESS.md`)
|
|
132
|
+
carries a `# GENERATED FROM harness.dot — DO NOT EDIT` header and is drift-checked in CI.
|
|
133
|
+
You evolve a harness by editing the spec and rebuilding in a PR, never by hand.
|
|
134
|
+
- **Content is runtime-loaded.** Editing a prompt, role, or merge policy needs no rebuild;
|
|
135
|
+
only topology changes (`harness.dot`) recompile.
|
|
136
|
+
|
|
137
|
+
The default graph `gp-foundry init` scaffolds (`.github/harness.dot`) — a complete dark
|
|
138
|
+
factory with self-healing and self-improving lanes:
|
|
139
|
+
|
|
140
|
+
```dot
|
|
141
|
+
digraph harness {
|
|
142
|
+
start [type=start]
|
|
143
|
+
scout [type=issue-agent, role="agents/roles/scout.md", context=issue]
|
|
144
|
+
planner [type=analyst, role="agents/roles/planner.md", context=issue, output=comment]
|
|
145
|
+
builder [type=producer, role="agents/roles/builder.md", context=issue]
|
|
146
|
+
reviewer [type=pr-review, role="agents/roles/reviewer.md", context="pr-diff"]
|
|
147
|
+
fixer [type=pr-fix, role="agents/roles/fixer.md", max_attempts=3]
|
|
148
|
+
merge_gate [type=merge-gate, policy="agents/policy/merge.yaml", schedule="*/30 * * * *"]
|
|
149
|
+
janitor [type=scheduled-agent, role="agents/roles/janitor.md", schedule="*/30 * * * *"]
|
|
150
|
+
supervisor [type=scheduled-agent, role="agents/roles/supervisor.md", schedule="17 * * * *"]
|
|
151
|
+
retro [type=scheduled-agent, role="agents/roles/retro.md", schedule="0 7 * * 1-5"]
|
|
152
|
+
needs_human [type=exit]
|
|
153
|
+
|
|
154
|
+
start -> scout [on="issues.opened"]
|
|
155
|
+
scout -> planner [when="label=plan"]
|
|
156
|
+
scout -> builder [when="label=build"]
|
|
157
|
+
planner -> builder [when="label=build"]
|
|
158
|
+
builder -> reviewer [on="pull_request.opened"]
|
|
159
|
+
reviewer -> merge_gate [when="verdict=approve"]
|
|
160
|
+
reviewer -> fixer [when="verdict=request_changes"]
|
|
161
|
+
fixer -> reviewer [on="push"] // retry loop…
|
|
162
|
+
fixer -> needs_human [when="attempts>=3"] // …with a bounded escape
|
|
163
|
+
}
|
|
164
|
+
```
|
|
165
|
+
|
|
166
|
+
Every cycle must keep a bounded escape edge to an `exit` node; the model-checker rejects
|
|
167
|
+
unbounded loops at build time. Full vocabulary in
|
|
168
|
+
[skill/reference/node-types.md](./skill/reference/node-types.md).
|
|
169
|
+
|
|
170
|
+
## Self-healing & self-improving
|
|
171
|
+
|
|
172
|
+
**Self-healing** — the factory does not silently stall:
|
|
173
|
+
- 🧹 **janitor** runs on a schedule and rebases every PR the merge gate flagged
|
|
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
|
|
176
|
+
`build`-labeled issue, idle PRs), and escalates to `needs-human` after 2 nudges.
|
|
177
|
+
- The **merge gate** posts a 🔀 audit comment explaining each decision and labels
|
|
178
|
+
`needs-rebase` on conflicts rather than merging a broken state.
|
|
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,
|
|
181
|
+
at `max_attempts`, labels the PR `needs-human` and stops instead of looping forever.
|
|
182
|
+
|
|
183
|
+
**Self-improving** — the factory learns from its own record:
|
|
184
|
+
- ♻️ **retro** mines merged PRs, reviews, and CI for lessons that recur (≥ 2 occurrences),
|
|
185
|
+
and writes evidence-cited notes to `.github/agents/memory/topics/`.
|
|
186
|
+
- `scope.yaml` guidance makes every agent **read that memory before working**, so a lesson
|
|
187
|
+
learned once shapes every subsequent run.
|
|
188
|
+
|
|
189
|
+
## Costs, security, limits
|
|
190
|
+
|
|
191
|
+
- **Cost** — every agent hop is a model call inside an Actions run: a busy factory spends
|
|
192
|
+
real tokens and CI minutes. Start with the scheduled lanes at modest cadence, watch
|
|
193
|
+
`gp-foundry status`, and cap intake (labels are your throttle). There are no built-in
|
|
194
|
+
per-day budget caps yet.
|
|
195
|
+
- **Security** — agents write with `AGENT_PAT`; scope it to the one repo. On public repos,
|
|
196
|
+
issue text is untrusted input to the agents: keep `scope.yaml` immutable paths tight
|
|
197
|
+
(`.github/` at minimum), keep the merge gate's protected paths on, and treat the
|
|
198
|
+
human-gate as mandatory for anything irreversible. The reviewer is also an LLM — the
|
|
199
|
+
gate's policy (CI green, size caps, protected paths) is the non-negotiable backstop.
|
|
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.
|
|
206
|
+
|
|
207
|
+
## Day-2 operations
|
|
208
|
+
|
|
209
|
+
| Command | Use |
|
|
210
|
+
|---------|-----|
|
|
211
|
+
| `gp-foundry status` | Operator dashboard: work in flight per lane, agent PRs, stalled items, failed runs (last 24h). |
|
|
212
|
+
| `gp-foundry doctor` | Preflight: config validity, workflow drift, vendored actions, `gh` auth, labels, secrets, committed. |
|
|
213
|
+
| `gp-foundry build --check` | The **CI drift gate** — exit non-zero if the committed workflows are stale vs the graph. Add it to your CI. |
|
|
214
|
+
|
|
215
|
+
**Where to make a change** — three surfaces, only one of which recompiles:
|
|
216
|
+
|
|
217
|
+
| To change… | Edit | Rebuild? |
|
|
218
|
+
|------------|------|----------|
|
|
219
|
+
| An agent's **behavior** (job description, quality bar) | `agents/roles/<name>.md` | No — runtime content |
|
|
220
|
+
| The **merge policy** (size gates, protected paths, approvals) | `agents/policy/merge.yaml` | No — runtime content |
|
|
221
|
+
| The **topology** (add a role/lane, rewire handoffs, change a schedule) | `.github/harness.dot` | Yes — `gp-foundry build` |
|
|
222
|
+
|
|
223
|
+
Roles and policy are runtime-loaded, so tuning them is a content edit with no regenerated
|
|
224
|
+
YAML. Changing the graph is the only thing that recompiles — do it in a PR, and commit the
|
|
225
|
+
spec change and the regenerated workflows together so `build --check` stays green.
|
|
226
|
+
|
|
227
|
+
### Distribution: vendored vs pinned
|
|
228
|
+
|
|
229
|
+
`runtime.mode` controls how the generated workflows reference the runtime-core actions:
|
|
230
|
+
- **`vendored`** (default) — `gp-foundry vendor` (and `up`) copy the actions into
|
|
231
|
+
`.github/actions/`, and the workflows reference them by local path. Self-contained, no
|
|
232
|
+
external dependency; upgrade by re-running `vendor`.
|
|
233
|
+
- **`pinned`** — reference `<owner_repo>/actions/<name>@<ref>` centrally (set a SHA/tag).
|
|
234
|
+
Smaller consumer repos, central upgrades — available once the actions repo is public.
|
|
235
|
+
|
|
236
|
+
## Repository layout
|
|
237
|
+
|
|
238
|
+
| Path | Contents |
|
|
239
|
+
|------|----------|
|
|
240
|
+
| `src/` | the compiler — parser, IR types, validate, model-check, role & step handlers, CLI |
|
|
241
|
+
| `actions/` | the runtime core (JS + composite actions the generated workflows call) |
|
|
242
|
+
| `roles/` | generic role packs (`software/`, `content/`, `docs/`) — the job descriptions |
|
|
243
|
+
| `skill/` | the packaged Claude skill: `SKILL.md`, `reference/`, and the scaffolding `templates/` |
|
|
244
|
+
| `schema/` | JSON Schema for `foundry.config.yaml` |
|
|
245
|
+
| `examples/` | example harness specs (`examples/dixie/`, `examples/marketing/`) |
|
|
246
|
+
| `docs/` | design docs (`docs/plans/`) |
|
|
247
|
+
|
|
248
|
+
## Docs
|
|
249
|
+
|
|
250
|
+
- **[docs/plans/](./docs/plans/)** — dated design specs (start with the
|
|
251
|
+
[system design](./docs/plans/2026-07-01-gp-foundry-system-design.md)).
|
|
252
|
+
- **[skill/SKILL.md](./skill/SKILL.md)** — the Socratic setup skill and its
|
|
253
|
+
[CLI](./skill/reference/cli.md), [node-type](./skill/reference/node-types.md), and
|
|
254
|
+
[role-pack](./skill/reference/role-packs.md) references.
|
|
255
|
+
- Each runtime-core action documents its contract in `actions/<name>/`.
|
|
256
|
+
|
|
257
|
+
## Development
|
|
258
|
+
|
|
259
|
+
```bash
|
|
260
|
+
npm ci
|
|
261
|
+
npm run typecheck # tsc --noEmit
|
|
262
|
+
npm test # vitest run
|
|
263
|
+
npm run build # bundle the CLI to dist/cli/index.cjs
|
|
264
|
+
npm run build:actions # bundle the runtime-core actions to actions/*/dist/
|
|
265
|
+
npm run check:dist # fail if bundled action dist drifts from source
|
|
266
|
+
```
|
|
267
|
+
|
|
268
|
+
CI runs the above, plus `actionlint` + `zizmor` over this repo's workflows and every
|
|
269
|
+
generated example harness, and guards that no generated workflow uses a local action path or
|
|
270
|
+
splices `${{ github.event.* }}` into a shell.
|
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
# agent-context
|
|
2
|
+
|
|
3
|
+
Fetches GitHub issue/PR data via the Octokit REST API and formats it into a
|
|
4
|
+
labeled plaintext context file for an agent prompt. Writes the file to a temp
|
|
5
|
+
path and exposes it via the `context-file` output.
|
|
6
|
+
|
|
7
|
+
This is a Node20 JavaScript action authored in TypeScript
|
|
8
|
+
(`src/*.ts`) and bundled to `dist/index.js` by the build pipeline.
|
|
9
|
+
|
|
10
|
+
## Inputs
|
|
11
|
+
|
|
12
|
+
| Name | Required | Default | Description |
|
|
13
|
+
| -------------------- | -------- | -------- | ----------- |
|
|
14
|
+
| `type` | yes | — | Context type: `issue`, `pr-diff`, `pr-review`, or `pr-full`. |
|
|
15
|
+
| `number` | yes | — | Issue or PR number. |
|
|
16
|
+
| `token` | yes | — | GitHub token used for API calls. |
|
|
17
|
+
| `include-diff` | no | `"true"` | Include the full unified diff for PR types. Any value other than `"false"` is treated as true. |
|
|
18
|
+
| `triggering-comment` | no | `""` | Body of the comment that triggered the workflow; appended as a final section when non-empty. |
|
|
19
|
+
| `base-branch` | no | `""` | Optional base branch noted in the log for the comparison. The PR diff is always taken relative to the PR's own base ref; this input is surfaced for logging and downstream steps, not to re-target the diff. |
|
|
20
|
+
|
|
21
|
+
## Outputs
|
|
22
|
+
|
|
23
|
+
| Name | Description |
|
|
24
|
+
| -------------- | ----------- |
|
|
25
|
+
| `context-file` | Absolute path to the formatted context file (written under `$RUNNER_TEMP`, falling back to the OS temp dir). |
|
|
26
|
+
|
|
27
|
+
## Context types
|
|
28
|
+
|
|
29
|
+
- **`issue`** — issue header (number, title, labels, body) plus all issue comments.
|
|
30
|
+
- **`pr-diff`** — PR header (title, file/line stats, body) plus the diff only.
|
|
31
|
+
- **`pr-review`** — PR header, issue comments, reviews, inline review comments, and diff.
|
|
32
|
+
- **`pr-full`** — identical to `pr-review`.
|
|
33
|
+
|
|
34
|
+
Empty sections are omitted. The diff is capped at ~100KB (100,000 bytes); larger
|
|
35
|
+
diffs are truncated with a `[Diff truncated at 100KB. Use Read tool to examine
|
|
36
|
+
full files.]` marker.
|
|
37
|
+
|
|
38
|
+
## Example
|
|
39
|
+
|
|
40
|
+
```yaml
|
|
41
|
+
- id: ctx
|
|
42
|
+
uses: ./.github/actions/agent-context
|
|
43
|
+
with:
|
|
44
|
+
type: pr-review
|
|
45
|
+
number: ${{ github.event.pull_request.number }}
|
|
46
|
+
token: ${{ secrets.GITHUB_TOKEN }}
|
|
47
|
+
triggering-comment: ${{ github.event.comment.body }}
|
|
48
|
+
|
|
49
|
+
- name: Use the context
|
|
50
|
+
run: cat "${{ steps.ctx.outputs.context-file }}"
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
## Layout
|
|
54
|
+
|
|
55
|
+
- `src/index.ts` — action entrypoint: reads inputs, orchestrates fetch/format, writes the file.
|
|
56
|
+
- `src/fetchers.ts` — Octokit fetch logic per context type (`fetchContext`).
|
|
57
|
+
- `src/formatters.ts` — pure formatting of fetched data into labeled sections (`formatContext`) plus shared types.
|
|
58
|
+
- `src/fetchers.test.ts`, `src/formatters.test.ts` — Vitest unit tests.
|
|
59
|
+
|
|
60
|
+
## Development
|
|
61
|
+
|
|
62
|
+
```sh
|
|
63
|
+
# From the repo root:
|
|
64
|
+
npx vitest run actions/agent-context
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
The `dist/` bundle is produced by the repo's build pipeline; do not edit it by hand.
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
name: Agent Context
|
|
2
|
+
description: Fetch and format GitHub issue/PR context for agent prompts
|
|
3
|
+
|
|
4
|
+
inputs:
|
|
5
|
+
type:
|
|
6
|
+
description: "Context type: issue, pr-diff, pr-review, pr-full"
|
|
7
|
+
required: true
|
|
8
|
+
number:
|
|
9
|
+
description: Issue or PR number
|
|
10
|
+
required: true
|
|
11
|
+
token:
|
|
12
|
+
description: GitHub token for API calls
|
|
13
|
+
required: true
|
|
14
|
+
include-diff:
|
|
15
|
+
description: Whether to include the full diff (for PR types)
|
|
16
|
+
default: "true"
|
|
17
|
+
triggering-comment:
|
|
18
|
+
description: Body of the comment that triggered the workflow
|
|
19
|
+
default: ""
|
|
20
|
+
base-branch:
|
|
21
|
+
description: >-
|
|
22
|
+
Optional base branch to note as the comparison base. The PR diff is always
|
|
23
|
+
taken relative to the PR's own base ref; this input is surfaced for logging
|
|
24
|
+
and downstream steps.
|
|
25
|
+
default: ""
|
|
26
|
+
|
|
27
|
+
outputs:
|
|
28
|
+
context-file:
|
|
29
|
+
description: Path to the formatted context file
|
|
30
|
+
|
|
31
|
+
runs:
|
|
32
|
+
using: node24
|
|
33
|
+
main: dist/index.cjs
|
|
@@ -0,0 +1,89 @@
|
|
|
1
|
+
# agent-fallback
|
|
2
|
+
|
|
3
|
+
A composite action that acts as a **safety net** after an agent (Claude, etc.)
|
|
4
|
+
finishes running in a workflow. If the agent left work uncommitted, forgot to
|
|
5
|
+
push, or forgot to open a PR, this action finishes the job. It also protects
|
|
6
|
+
paths the agent must never touch and can post a "no changes" comment when the
|
|
7
|
+
agent produced nothing.
|
|
8
|
+
|
|
9
|
+
It is fully generalized: nothing about a specific bot, app, label, model, or
|
|
10
|
+
repository layout is hardcoded. Everything is driven by inputs and a scope file.
|
|
11
|
+
|
|
12
|
+
## What it does (in order)
|
|
13
|
+
|
|
14
|
+
1. **Resolve immutable paths.** Reads the `immutable_paths:` list from the scope
|
|
15
|
+
YAML file (`scope-path`, default `.github/agents/scope.yaml`) using a
|
|
16
|
+
dependency-free `awk` scan. If the file or the key is missing, it defaults to
|
|
17
|
+
`.github/workflows/`.
|
|
18
|
+
2. **Strip protected path changes.** Reverts any changes to the immutable paths —
|
|
19
|
+
both committed (via `git checkout <base> -- <file>` / `git rm`, amended into
|
|
20
|
+
the tip commit) and uncommitted (working tree + index). This prevents pushes
|
|
21
|
+
from being rejected when the token lacks permission for those paths (e.g. the
|
|
22
|
+
GitHub `workflows` permission).
|
|
23
|
+
3. **Commit uncommitted changes.** If the working tree is dirty, stages
|
|
24
|
+
everything and commits with `commit-message` (or a generated default using
|
|
25
|
+
`agent-name`).
|
|
26
|
+
4. **Check for changes.** Compares `HEAD` against `origin/<base-branch>`.
|
|
27
|
+
5. **Post no-changes comment.** If there were no changes and
|
|
28
|
+
`no-changes-comment` is set, posts it to the PR or the issue per
|
|
29
|
+
`comment-target`.
|
|
30
|
+
6. **Push branch.** Pushes `branch` when there are changes.
|
|
31
|
+
7. **Create PR if needed.** If no PR already exists for `branch` and `pr-title`
|
|
32
|
+
is set, opens a PR against `base-branch` with the given title/body/label, and
|
|
33
|
+
optionally links it back to `issue-number`.
|
|
34
|
+
|
|
35
|
+
## Inputs
|
|
36
|
+
|
|
37
|
+
| Input | Required | Default | Description |
|
|
38
|
+
| -------------------- | -------- | --------------------------- | ----------- |
|
|
39
|
+
| `branch` | yes | — | Branch name to push. |
|
|
40
|
+
| `token` | yes | — | GitHub token for push, PR creation, and comments. |
|
|
41
|
+
| `agent-name` | yes | — | Agent name used in fallback commit messages and the PR-link comment. |
|
|
42
|
+
| `base-branch` | no | `main` | Base branch to diff against and to target for the fallback PR. |
|
|
43
|
+
| `scope-path` | no | `.github/agents/scope.yaml` | Scope YAML file whose `immutable_paths:` list is stripped before pushing. |
|
|
44
|
+
| `commit-message` | no | `""` | Fallback commit message. Empty → `Agent <agent-name>: automated changes`. |
|
|
45
|
+
| `pr-title` | no | `""` | Fallback PR title. Empty → never create a fallback PR. |
|
|
46
|
+
| `pr-body` | no | `""` | Fallback PR body. |
|
|
47
|
+
| `pr-label` | no | `""` | Label applied to the fallback PR. |
|
|
48
|
+
| `issue-number` | no | `""` | Issue to comment on with the PR link (and optional no-changes comment). |
|
|
49
|
+
| `no-changes-comment` | no | `""` | Comment posted if no changes were made. Empty → skip. |
|
|
50
|
+
| `comment-target` | no | `pr` | Where to post `no-changes-comment`: `pr` or `issue`. |
|
|
51
|
+
|
|
52
|
+
## Notes
|
|
53
|
+
|
|
54
|
+
- Composite actions have **no `secrets` context**; pass the token explicitly via
|
|
55
|
+
the `token` input.
|
|
56
|
+
- The action assumes a checked-out repo with `origin/<base-branch>` fetched and
|
|
57
|
+
git identity configured by an earlier step.
|
|
58
|
+
- Immutable paths may be directories (e.g. `.github/workflows/`) or individual
|
|
59
|
+
files; each entry is passed to `git` as-is.
|
|
60
|
+
|
|
61
|
+
## Scope file format
|
|
62
|
+
|
|
63
|
+
```yaml
|
|
64
|
+
immutable_paths: # enforced here: stripped before push
|
|
65
|
+
- .github/workflows/
|
|
66
|
+
- .github/agents/scope.yaml
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
Only the `immutable_paths:` key is consulted. Other keys (e.g. `forbidden_paths`,
|
|
70
|
+
`guidance`) are ignored by this action.
|
|
71
|
+
|
|
72
|
+
## Example
|
|
73
|
+
|
|
74
|
+
```yaml
|
|
75
|
+
- uses: ./actions/agent-fallback
|
|
76
|
+
with:
|
|
77
|
+
branch: agent/implement-${{ github.event.issue.number }}
|
|
78
|
+
token: ${{ steps.app-token.outputs.token }}
|
|
79
|
+
agent-name: implement
|
|
80
|
+
base-branch: main
|
|
81
|
+
scope-path: .github/agents/scope.yaml
|
|
82
|
+
commit-message: "Agent implement: automated changes"
|
|
83
|
+
pr-title: "Implement #${{ github.event.issue.number }}"
|
|
84
|
+
pr-body: "Automated implementation. Closes #${{ github.event.issue.number }}."
|
|
85
|
+
pr-label: agent-generated
|
|
86
|
+
issue-number: ${{ github.event.issue.number }}
|
|
87
|
+
no-changes-comment: "The agent did not produce any changes."
|
|
88
|
+
comment-target: issue
|
|
89
|
+
```
|