@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.
Files changed (50) hide show
  1. package/AGENTS.md +89 -0
  2. package/LICENSE +21 -0
  3. package/README.md +270 -0
  4. package/actions/agent-context/README.md +67 -0
  5. package/actions/agent-context/action.yml +33 -0
  6. package/actions/agent-fallback/README.md +89 -0
  7. package/actions/agent-fallback/action.yml +204 -0
  8. package/actions/config-loader/README.md +81 -0
  9. package/actions/config-loader/action.yml +50 -0
  10. package/actions/dependency-chain/README.md +116 -0
  11. package/actions/dependency-chain/action.yml +57 -0
  12. package/actions/merge-gate/README.md +111 -0
  13. package/actions/merge-gate/action.yml +60 -0
  14. package/actions/run-agent/README.md +75 -0
  15. package/actions/run-agent/action.yml +213 -0
  16. package/actions/sanitize-untrusted-input/README.md +110 -0
  17. package/actions/sanitize-untrusted-input/action.yml +47 -0
  18. package/actions/setup-agent/README.md +51 -0
  19. package/actions/setup-agent/action.yml +100 -0
  20. package/actions/wait-for-checks/README.md +91 -0
  21. package/actions/wait-for-checks/action.yml +58 -0
  22. package/dist/cli/index.cjs +130 -0
  23. package/package.json +79 -0
  24. package/roles/README.md +124 -0
  25. package/roles/content/brand-critic.md +64 -0
  26. package/roles/content/brief-triager.md +58 -0
  27. package/roles/content/copywriter.md +55 -0
  28. package/roles/content/editor.md +51 -0
  29. package/roles/docs/reviewer.md +62 -0
  30. package/roles/docs/writer.md +54 -0
  31. package/roles/software/builder.md +28 -0
  32. package/roles/software/fixer.md +26 -0
  33. package/roles/software/janitor.md +30 -0
  34. package/roles/software/planner.md +29 -0
  35. package/roles/software/retro.md +42 -0
  36. package/roles/software/reviewer.md +27 -0
  37. package/roles/software/scout.md +30 -0
  38. package/roles/software/supervisor.md +52 -0
  39. package/schema/config.schema.json +167 -0
  40. package/skill/SKILL.md +280 -0
  41. package/skill/reference/cli.md +108 -0
  42. package/skill/reference/node-types.md +99 -0
  43. package/skill/reference/role-packs.md +95 -0
  44. package/skill/templates/agent-setup.yml +15 -0
  45. package/skill/templates/communication.md +64 -0
  46. package/skill/templates/foundry.config.yaml +49 -0
  47. package/skill/templates/harness.dot +54 -0
  48. package/skill/templates/policy-merge.yaml +54 -0
  49. package/skill/templates/role.md +33 -0
  50. 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
+ ```