@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
@@ -0,0 +1,108 @@
1
+ # The `gp-foundry` CLI — what the skill shells out to
2
+
3
+ The CLI (component B8) is the **deterministic engine**. The skill (you) is a Socratic
4
+ wrapper over it: you never parse DOT, run the model-check, or emit YAML yourself. Every
5
+ structural operation goes through these subcommands. The same CLI runs in CI's drift-check,
6
+ so behavior is identical for agent and human.
7
+
8
+ All commands run from the consumer repo root and operate on `.github/harness.dot` and the
9
+ sibling spec files unless a path is given. Add `--json` to any command for machine-readable
10
+ output you can parse. Non-zero exit = failure; read stderr and surface diagnostics verbatim.
11
+
12
+ ## `gp-foundry init [--dir <path>] [--force]`
13
+ Scaffold the canonical spec layout (`harness.dot`, `foundry.config.yaml`, `scope.yaml`,
14
+ `policy/merge.yaml`, `communication.md`, one `roles/<name>.md` per role the graph
15
+ references, and an `.github/agent-setup/action.yml` shim that installs the agent CLI — add your project toolchain to it). Run this once at the start of
16
+ setup, then fill in the drafted spec. Idempotent — it skips files that already exist (and
17
+ reports them) unless you pass `--force`.
18
+
19
+ ## `gp-foundry validate [--json]`
20
+ Static checks over the spec: structural integrity, referential integrity (every
21
+ `role`/`prompt`/`policy` path exists), **role handoffs == out-edges**, human-gate-has-
22
+ environment, and the topology model-check (reachability, bounded loops, label races,
23
+ placeholder/vendored-action checks). Prints `Diagnostic[]` with `level`, `code`, `message`,
24
+ `where.file:line`, and `hint`. Run before every build. Exit non-zero on any `error`.
25
+
26
+ ## `gp-foundry graph [--json]`
27
+ Render the topology. Default prints a **Mermaid flowchart** to stdout — the same diagram
28
+ the compiler writes to `.github/HARNESS.md` on `build`, so you can show the graph before any
29
+ YAML exists. `--json` emits the parsed IR (`name`, `nodes`, `edges`) — use this to load
30
+ current topology at the start of an *evolve* session.
31
+
32
+ ## `gp-foundry build [--check] [--dry-run] [--out <dir>] [--force] [--json]`
33
+ Compile `harness.dot` + spec → `.github/workflows/*.yml` (plus `.github/HARNESS.md`).
34
+ - **`--dry-run`** — compile and print the generated files, write **nothing**. Always do this
35
+ first and explain the diff before a real build.
36
+ - (default) — write the generated workflows (each carries `# GENERATED FROM harness.dot —
37
+ DO NOT EDIT`). Generated files are fully compiler-owned: `build` overwrites them, so a
38
+ hand edit to a generated `.yml` is simply replaced (that is the point; `--check` catches
39
+ the drift in CI). If there are error diagnostics, `build` refuses to write unless `--force`.
40
+ - **`--check`** — compile in memory and compare against the files on disk; exit non-zero if
41
+ any generated file is out of date. This is the CI drift gate. You rarely run it yourself,
42
+ but explain it to users as the guarantee that the graph and the YAML agree.
43
+ - **`--out <dir>`** — write to a different repo root (default: the repo root — the parent of the `.github/` dir containing `harness.dot`).
44
+
45
+ ## `gp-foundry explain <node> [--json]`
46
+ Show the workflow a single node compiles to (its permission set, trigger surface `on:`, `if:`
47
+ guard, which runtime-core action(s) it calls, and its steps). Use it to answer "what does the
48
+ builder actually do?" and to justify a diff before writing.
49
+
50
+ ## Ops commands — bring-up and day-2
51
+
52
+ These wrap the factory lifecycle around `build`. Everything gh-dependent degrades to a clean
53
+ "skip" (with a hint) when `gh` is missing or unauthenticated, so they also work offline.
54
+
55
+ ### `gp-foundry vendor [--dir <path>]`
56
+ Copy the packaged runtime-core actions into `.github/actions/` (the self-contained,
57
+ `runtime.mode: vendored` layout the generated workflows reference by local path). Scaffolds
58
+ `.github/agent-setup/action.yml` if absent, never overwriting it. Commit `.github/actions/`.
59
+
60
+ ### `gp-foundry skill [--user] [--dir <path>]`
61
+ Install this skill into `.claude/skills/gp-foundry/` (project) or `~/.claude/skills/`
62
+ (`--user`), so Claude Code can run the Socratic setup: `/gp-foundry` or "set up an agent
63
+ pipeline for this repo".
64
+
65
+ ### `gp-foundry up`
66
+ One command from `init` to a runnable factory: create the repo labels
67
+ (`build`/`plan`/`needs-human`/`needs-rebase`), vendor the runtime actions (in vendored mode),
68
+ `build` the workflows, then run `doctor`. Prints the doctor checks (which flag missing
69
+ secrets with the exact `gh secret set` commands) and exits non-zero until the factory
70
+ is ready — commit `.github/`, push, file an issue.
71
+
72
+ ### `gp-foundry doctor`
73
+ Preflight: config validity, workflow drift, vendored actions present, `agent-setup` shim
74
+ present, `gh` auth, GitHub repo, required labels, required secrets, and whether `.github/`
75
+ is committed. Exit non-zero if any check fails. The repo-side checks (labels/secrets/commit)
76
+ skip cleanly when `gh` is unavailable or there's no GitHub remote.
77
+
78
+ ### `gp-foundry status`
79
+ Operator dashboard (needs `gh` + a GitHub repo): open work per lane (plan/build/needs-human),
80
+ agent PRs with mergeability + labels, stalled items (issues with no PR, idle PRs), and failed
81
+ workflow runs in the last 24h.
82
+
83
+ ## Typical sequences
84
+
85
+ **First-time setup (after the interview):**
86
+ ```bash
87
+ gp-foundry init
88
+ # …draft harness.dot, roles/*.md, policy/*.yaml, scope.yaml, foundry.config.yaml…
89
+ gp-foundry validate
90
+ gp-foundry graph # show the Mermaid diagram; iterate on the DOT with the user
91
+ gp-foundry build --dry-run # explain the diff
92
+ gp-foundry up # labels + vendor + build + doctor
93
+ # set secrets, commit spec + workflows together, push
94
+ ```
95
+
96
+ **Evolve (add a role / tighten a gate) — as a PR:**
97
+ ```bash
98
+ git checkout -b harness/add-copywriter
99
+ gp-foundry graph --json # understand current topology
100
+ # …edit harness.dot (add the node + edges) and create roles/copywriter.md with matching handoffs…
101
+ gp-foundry validate && gp-foundry build --dry-run # explain diff
102
+ gp-foundry build
103
+ git add -A && git commit && gh pr create # review-gated topology change
104
+ ```
105
+
106
+ **Interpreting failures:** on any non-zero exit, quote the diagnostic's `file:line`,
107
+ `message`, and `hint`, then propose the spec fix. Never work around a diagnostic by editing
108
+ generated YAML.
@@ -0,0 +1,99 @@
1
+ # Node types, edges, and guards — the DOT vocabulary
2
+
3
+ This is the vocabulary you draft `harness.dot` with. It mirrors the IR
4
+ (`src/ir/types.ts`) and the compiler's handler registry. A node is `type` × `role`:
5
+ the **type** is the mechanical GitHub interaction (closed set, chosen at build time);
6
+ the **role** is the behavioral identity (a `roles/<name>.md` file, open set, runtime-loaded).
7
+
8
+ ## Node types
9
+
10
+ | type | what it does mechanically | permissions | context | pushes code? |
11
+ |------|---------------------------|-------------|---------|--------------|
12
+ | `start` | entry point; the intake event enters here | none | — | no |
13
+ | `exit` | terminal / escape hatch (e.g. `needs_human`) | none | — | no |
14
+ | `analyst` | **reads and advises** — deliverable is an *artifact* (comment, answer, plan, spec, draft), NOT a code change. The safest, lowest-privilege agent. | `contents: read` (+ comment perm; `output=doc:<glob>` allows committing only to that glob) | issue / pr-diff / codebase | no (or docs-only via `output=doc:`) |
15
+ | `issue-agent` | analyst specialized on an issue (triage/shape a request) | `contents: read` + issues write | issue | no |
16
+ | `pr-review` | analyst specialized on a PR diff; posts a **verdict** | `contents: read` + PR write | pr-diff | no |
17
+ | `producer` | issue → branch → tested PR (the code-writer; "code-agent" is a fine synonym) | `contents: write` + PR write | issue | **yes** |
18
+ | `pr-fix` | reads review feedback, pushes fixes to the PR branch; bounded by `max_attempts` | `contents: write` + PR write | pr-review | **yes** |
19
+ | `scheduled-agent` | a maintenance agent on `schedule=` cron + manual dispatch, NO triggering issue/PR — it gathers its own work via `gh` (janitor rebase sweep, supervisor re-drive, retro learning) and its commits push to the base branch | `contents: write` + issues/PR write + `actions: write` | none | **yes** |
20
+ | `merge-gate` | evaluates merge policy (approval delay, CI green, size, protected paths, clean rebase) → merge / skip / label | `contents: write` + PR write | none | no (merges) |
21
+ | `human-gate` | pauses for a human via a GitHub **Environment** approval (brand/deploy sign-off) | per environment | none | no |
22
+ | `parallel` | fork bar of a **clean diamond**: exactly one in-edge (carrying the trigger), ≥2 bare out-edges to agent legs. Virtual — the whole diamond compiles into the fan_in's single workflow | none (virtual) | — | no |
23
+ | `fan_in` | join of the diamond: compiles to ONE workflow with each leg as a job plus this node `needs:`-joined after them (native Actions join — no polling, no markers). Role synthesizes the lanes' comments (e.g. THE verdict); optional `on_complete_label=` cascades a label. Lane roles must post ANALYSES, never `**Verdict:**` (validator warns) | `contents: read` + PR/issues write | pr-review / issue | no |
24
+
25
+ Rules of thumb:
26
+ - **Read-and-advise vs create-a-change is the deepest split, and it IS the permission
27
+ axis.** If the deliverable is words (a comment/plan/spec/draft), it's an `analyst`
28
+ family node and stays `contents: read`. If it changes files, it's a `producer`/`pr-fix`
29
+ and gets `contents: write`. Never give an advising node write-on-code.
30
+ - `issue-agent` and `pr-review` are `analyst` specialized by `context=` and output contract;
31
+ keep them named for clarity (design D10). Use plain `analyst` for Q&A / planning / design-docs.
32
+ - Every harness has exactly one `start` and at least one `exit` (the bounded escape).
33
+
34
+ ## Node attributes (DOT `[...]`)
35
+
36
+ | attr | on types | meaning |
37
+ |------|----------|---------|
38
+ | `type=` | all | the node type (required) |
39
+ | `role="agents/roles/x.md"` | agent types | job-description file (referenced, never inlined) |
40
+ | `on_complete_label=` | fan_in | label applied on join completion (resolves via config.labels) |
41
+ | `context=` | agent types | `issue` \| `pr-diff` \| `pr-review` \| `codebase` \| `none` |
42
+ | `output=` | `analyst` | `comment` \| `doc:<path-glob>` (docs-only write allowlist) |
43
+ | `gates="ci.yml,..."` | `pr-review` | named check workflows the review depends on |
44
+ | `max_attempts=N` | `pr-fix` | loop bound; pairs with an `attempts>=N` escape edge |
45
+ | `policy="policy/merge.yaml"` | `merge-gate` | merge-policy file |
46
+ | `schedule="*/30 * * * *"` | `merge-gate`, sweeps | cron cadence |
47
+ | `environment=NAME` | `human-gate` | GitHub Environment gating approval (**required** on human-gate) |
48
+
49
+ ## Edges — `a -> b [on=..., when=...]`
50
+
51
+ - `on="<event>"` — the GitHub event that fires `b`'s workflow. Well-known events:
52
+ `issues.opened`, `issues.labeled`, `issue_comment.created`, `pull_request.opened`,
53
+ `pull_request.synchronize`, `pull_request.labeled`, `pull_request.closed`,
54
+ `pull_request_review.submitted`, `push`, `schedule`, `workflow_dispatch`.
55
+ - `when="<guard>"` — a **GitHub-observable** guard compiled to an `if:`. Forms:
56
+ - `label=<key>` — the label named by `labels.<key>` in config is present (never a literal).
57
+ - `verdict=approve` / `verdict=request_changes` — parsed from a `pr-review`'s output.
58
+ - `ci=pass` — a required check concluded success.
59
+ - `attempts>=N` — the loop counter (the bounded-escape guard).
60
+ - boolean combinations: `ci=pass && size<gate && !protected_paths`.
61
+
62
+ A guard MUST be expressible in GitHub-observable primitives (events, labels, check
63
+ conclusions, schedules) — because GitHub is the executor, not a custom engine.
64
+
65
+ ## Invariants the model-checker enforces (design them in, don't fight them)
66
+
67
+ - **Reachability:** every node reachable from `start`; no dead ends except `exit`.
68
+ - **Bounded loops:** every cycle has a bounded escape edge to an `exit`
69
+ (e.g. `fixer -> needs_human [when="attempts>=3"]`). This is the dixie fixer↔merger
70
+ livelock class — caught at build time.
71
+ - **No label races:** two nodes must not trigger on the same event+guard.
72
+ - **Handoff parity:** a role's `handoffs` front-matter == that node's out-edges (both directions).
73
+ - **human-gate has an environment;** analyst nodes are `contents: read`; `output=doc:<glob>`
74
+ means the only committed paths match `<glob>`.
75
+
76
+ ## Reference example (dixie's harness, generalized)
77
+
78
+ ```dot
79
+ digraph harness {
80
+ start [type=start]
81
+ scout [type=issue-agent, role="roles/scout.md", context=issue]
82
+ planner [type=analyst, role="roles/planner.md", context=issue, output=comment]
83
+ builder [type=producer, role="roles/builder.md", context=issue]
84
+ reviewer [type=pr-review, role="roles/reviewer.md", context="pr-diff", gates="ci.yml"]
85
+ fixer [type=pr-fix, role="roles/fixer.md", max_attempts=3]
86
+ merge_gate [type=merge-gate, policy="policy/merge.yaml", schedule="*/30 * * * *"]
87
+ needs_human [type=exit]
88
+
89
+ start -> scout [on="issues.opened"]
90
+ scout -> planner [when="label=plan"] // label name resolved via config
91
+ scout -> builder [when="label=build"]
92
+ planner -> builder [when="label=build"]
93
+ builder -> reviewer [on="pull_request.opened"]
94
+ reviewer -> merge_gate [when="verdict=approve"]
95
+ reviewer -> fixer [when="verdict=request_changes"]
96
+ fixer -> reviewer [on="push"] // retry loop…
97
+ fixer -> needs_human [when="attempts>=3"] // …with a bounded escape
98
+ }
99
+ ```
@@ -0,0 +1,95 @@
1
+ # Starter role packs (E4) — adapt, don't invent from scratch
2
+
3
+ Once the interview reveals the domain (Q1), adapt from the matching pack so you propose a
4
+ sensible default graph instead of a blank one. A pack's roles are designed so their
5
+ `handoffs` form a valid graph out of the box. You then rename, drop, and re-wire to fit the
6
+ repo, and fill each role's repo-specific overlay. Types are domain-neutral; only the roles,
7
+ gates, and invariants change between packs.
8
+
9
+ ## Software pack (code repos)
10
+
11
+ The canonical "issues in → reviewed, auto-merged PRs out" pipeline.
12
+
13
+ | role | type | one-line job |
14
+ |------|------|--------------|
15
+ | Scout | `issue-agent` | triage an incoming issue; label it for a lane |
16
+ | Planner | `analyst` (output=comment) | for big/ambiguous issues, post a plan before building |
17
+ | Builder | `producer` | turn a labeled issue into a small, tested, shippable PR |
18
+ | Reviewer | `pr-review` | read the diff, run gates, post an approve/request-changes verdict |
19
+ | Fixer | `pr-fix` (max_attempts=3) | apply review feedback; bounded retry loop with Reviewer |
20
+ | merge-gate | `merge-gate` | enforce merge policy; auto-merge or label for a human (a gate, not a persona) |
21
+ | Janitor | `scheduled-agent` | rebase PRs the gate flagged `needs-rebase` so they can merge |
22
+ | Supervisor | `scheduled-agent` | sweep for stranded issues/PRs and re-drive them; escalate to `needs-human` after repeated nudges |
23
+ | Retro | `scheduled-agent` | mine the record for recurring lessons; write them to memory |
24
+
25
+ Default graph: `start → Scout → {Planner|Builder} → Reviewer ↔ Fixer → merge-gate`,
26
+ with `Fixer → needs_human [when="attempts>=3"]`, plus scheduled `Janitor` (rebase sweep),
27
+ `Supervisor` (self-healing re-drive), and `Retro` (learning). This is the shape in the
28
+ default `templates/harness.dot`.
29
+
30
+ ## Review panel (parallel lanes on any pack)
31
+
32
+ Fan a PR review out to independent lanes and join them into ONE verdict:
33
+
34
+ ```dot
35
+ builder -> split [on="pull_request.opened, pull_request.synchronize"]
36
+ split [type=parallel]
37
+ split -> lane_correct // [type=analyst, context="pr-diff"] posts an ANALYSIS comment
38
+ split -> lane_security // (never a '**Verdict:**' — the validator warns if lanes could)
39
+ lane_correct -> panel
40
+ lane_security -> panel
41
+ panel [type=fan_in, role="agents/roles/panel.md"] // synthesizes lanes → THE verdict review
42
+ panel -> merge_gate [when="verdict=approve"]
43
+ ```
44
+
45
+ The diamond compiles to one workflow: lanes run as parallel jobs, the panel job
46
+ `needs:` them (native join — a failed lane is a visibly red run, not a silent stall).
47
+
48
+ ## Content / marketing pack (proves domain-generality)
49
+
50
+ Same node types, same compiler, same runtime core — only roles, gates, and validation
51
+ change. The `human-gate` matters *more* here (brand risk), which is why it's first-class.
52
+
53
+ | role | type | one-line job |
54
+ |------|------|--------------|
55
+ | Brief-Triager | `issue-agent` | shape a content request into a brief |
56
+ | Copywriter | `producer` | draft copy in a PR |
57
+ | Brand-Critic | `pr-review` (gates="linkcheck.yml,spellcheck.yml") | check voice, links, spelling |
58
+ | Editor | `pr-fix` (max_attempts=2) | apply edit notes; bounded loop with Brand-Critic |
59
+ | Publish | `human-gate` (environment=production) | brand sign-off before go-live |
60
+
61
+ Default graph: `start → Brief-Triager → Copywriter → Brand-Critic ↔ Editor → Publish`.
62
+ Note the terminal is a **human-gate**, not an automated merge — the brand approval is the point.
63
+
64
+ ## Docs pack
65
+
66
+ | role | type | one-line job |
67
+ |------|------|--------------|
68
+ | Docs-Triager | `issue-agent` | shape a docs request |
69
+ | Writer | `producer` | draft/update docs in a PR |
70
+ | Doc-Reviewer | `pr-review` (gates="linkcheck.yml") | accuracy + style verdict |
71
+ | Doc-Fixer | `pr-fix` (max_attempts=2) | apply review notes |
72
+ | Doc-Shipper | `merge-gate` | merge on green |
73
+
74
+ ## Analyst-only / advisory pack (lowest privilege)
75
+
76
+ For repos that want Q&A, research, planning, or design-docs with **no code writes at all**.
77
+ Everything stays `contents: read`; the only output is a comment or a docs-path commit.
78
+
79
+ | role | type | one-line job |
80
+ |------|------|--------------|
81
+ | Answerer | `analyst` (context=codebase, output=comment) | answer questions about the repo |
82
+ | Planner | `analyst` (context=issue, output=doc:docs/plans/*) | draft a plan/spec as a committed doc |
83
+
84
+ Default graph: `start → {Answerer|Planner}`, no `producer`, no merge-gate — the safest harness.
85
+
86
+ ## Adapting a pack
87
+
88
+ 1. Pick the pack from Q1's domain answer.
89
+ 2. Rename roles to the repo's vocabulary; drop lanes the repo doesn't need (e.g. no Planner
90
+ if issues are always small).
91
+ 3. Re-wire edges to the handoffs the user described in Q3, keeping every loop bounded.
92
+ 4. Fill each `roles/<name>.md` repo-specific overlay (stack commands, conventions) — that
93
+ overlay is the only per-repo delta; the front-matter contract stays intact.
94
+ 5. Set the gates and `scope.yaml` invariants from Q2. For content/docs, a `human-gate` before
95
+ publish is usually correct; for code, a `merge-gate` policy usually is.
@@ -0,0 +1,15 @@
1
+ name: agent-setup
2
+ description: >-
3
+ Consumer-owned toolchain setup, run before every agent job. gp-foundry scaffolds
4
+ this shim; EDIT IT to add your project's toolchain (setup-python, setup-go, pnpm,
5
+ system deps, …) so agents can build and test your code.
6
+ runs:
7
+ using: composite
8
+ steps:
9
+ # Installs node + the coding-agent CLI (from the vendored runtime core).
10
+ - uses: ./.github/actions/setup-agent
11
+ with:
12
+ node-version: "22"
13
+ # Add your project toolchain below, e.g.:
14
+ # - uses: actions/setup-python@v5
15
+ # with: { python-version: "3.12" }
@@ -0,0 +1,64 @@
1
+ # Communication guide
2
+
3
+ You are one agent on a team that coordinates **entirely through GitHub** — issues, PRs,
4
+ comments, reviews, labels. Humans **and** the next agents read what you post. Write for both.
5
+
6
+ ## Identity
7
+
8
+ Lead every human-facing message (PR/issue comment, review, PR body) with your persona
9
+ header — your emoji + name, e.g. `## 👷 Builder`. It's how people scan who said what.
10
+
11
+ ## Tone
12
+
13
+ Concise, specific, warm-but-professional. State decisions plainly. No hedging, no filler,
14
+ no restating the task back to yourself.
15
+
16
+ ## Structure — a useful visible summary, agent context tucked below
17
+
18
+ Lead with a summary a human can **act on at a glance**. For a PR description or a review,
19
+ "useful" means the actual substance: **what changed, why, and how you verified it** — visible,
20
+ not hidden. Then use a collapsed `<details>` block for *supplementary* material aimed mainly at
21
+ the next agent (deep reasoning, the file-by-file walk, structured hand-off notes). `<details>`
22
+ is collapsed for humans but **fully visible to every agent** that reads the raw markdown — so
23
+ it's for depth the human usually won't need, never for the main message.
24
+
25
+ ```markdown
26
+ ## 👷 Builder
27
+
28
+ <one line: what this change is / does>
29
+
30
+ **What changed** — <the key edits, as a couple of bullets>
31
+ **Why** — <the reasoning / approach, when not obvious>
32
+ **Verified** — <how you tested it; e.g. `make test` green>
33
+
34
+ Closes #<n>
35
+
36
+ <details><summary>Notes for reviewers & agents</summary>
37
+
38
+ <supplementary depth: trade-offs, alternatives considered, follow-ups, file-by-file — the
39
+ context a successor may want but a human scanning does not need up front>
40
+
41
+ </details>
42
+ ```
43
+
44
+ Reserve HTML comments `<!-- like this -->` for machine-only state markers (invisible even when
45
+ expanded).
46
+
47
+ ## Handoffs — write for the next agent, not just for humans
48
+
49
+ Your note / plan / review is the **input** to the next role in your handoffs.
50
+
51
+ - State your decision **and** the reasoning + observations behind it (what you found, what
52
+ you ruled out, what's still uncertain).
53
+ - Handing off work → give a concrete, **actionable** brief, not a vague summary.
54
+ - Receiving work → read the upstream artifacts (triage notes, the plan, the review) and
55
+ **honor them**; don't re-litigate settled decisions.
56
+
57
+ ## Reviews
58
+
59
+ End a review with exactly one line: `**Verdict:** APPROVE` or `**Verdict:** REQUEST_CHANGES`.
60
+ For request-changes, make each ask a specific, addressable bullet — it is the Fixer's checklist.
61
+
62
+ ## No-ops
63
+
64
+ If you made no change, say so plainly and why. Never post an empty or confused message.
@@ -0,0 +1,49 @@
1
+ # foundry.config.yaml — consumer-repo global config, read at BUILD time by `gp-foundry`.
2
+ # Every value ships with a working default: a fresh `gp-foundry init && gp-foundry up`
3
+ # builds a runnable factory with NO edits here. Tune when you outgrow the defaults.
4
+
5
+ name: agent-harness
6
+
7
+ auth: # how the harness authenticates to GitHub for writes
8
+ # Pick ONE mode:
9
+ # pat — a fine-grained PAT in a repo secret: events cascade, one secret,
10
+ # no App to install. Easiest; the default. Scope the PAT to this
11
+ # repo with Contents + Pull requests + Issues + Actions read/write.
12
+ # app — GitHub App token: clean bot identity, cascades. Best for orgs.
13
+ # (set app_id_secret / app_key_secret instead of token_secret)
14
+ # github-token — the built-in GITHUB_TOKEN: zero setup BUT its commits/PRs never
15
+ # trigger other workflows, so any chained pipeline stalls. `validate`
16
+ # errors on this mode when the graph has chained stages.
17
+ mode: pat
18
+ token_secret: AGENT_PAT # gh secret set AGENT_PAT --body <fine-grained-pat>
19
+
20
+ identity: # git author for the agent's commits/PRs
21
+ bot_login: agent-bot
22
+ git_name: Agent Bot
23
+ git_email: agent-bot@users.noreply.github.com
24
+
25
+ agent: # the coding-agent CLI + default model
26
+ cli: claude
27
+ model: claude-opus-4-8
28
+ oauth_token_secret: CLAUDE_CODE_OAUTH_TOKEN # gh secret set CLAUDE_CODE_OAUTH_TOKEN --body <token>
29
+ # allowed_tools: "Read,Write,Edit,Glob,Grep,Bash(git:*),Bash(gh:*)" # roles may widen/narrow
30
+
31
+ repo:
32
+ base_branch: main
33
+ branch_prefix: agent/ # branches look like agent/<issue>-slug (matches policy branch_prefix)
34
+
35
+ labels: # semantic key -> actual repo label. Guards (`when="label=build"`) resolve
36
+ # through this map, so renaming a repo label is a one-line change HERE —
37
+ # but the role prose tells agents to apply the semantic name, so if you
38
+ # remap, update the role instructions to apply the mapped label too.
39
+ build: build
40
+ plan: plan
41
+
42
+ # NOTE: merge sizing/policy (max additions, protected paths, approval rules) lives in
43
+ # agents/policy/merge.yaml — the merge-gate reads THAT file at runtime, not this one.
44
+
45
+ runtime: # how generated workflows reference the runtime-core actions
46
+ # vendored — `gp-foundry vendor` copies the actions into .github/actions/ (default;
47
+ # self-contained, no external dependency, upgrade by re-running vendor).
48
+ # pinned — reference <owner_repo>/actions/<name>@<ref> centrally (set a SHA/tag).
49
+ mode: vendored
@@ -0,0 +1,54 @@
1
+ // harness.dot — the single source of truth for this repo's agent harness topology.
2
+ // `type` = mechanical GitHub interaction (chosen at build time); `role` = job description
3
+ // (a roles/*.md file, loaded at runtime). Edges are transitions: `on=` GitHub event,
4
+ // `when=` GitHub-observable guard. Compile with `gp-foundry build`. NEVER hand-edit the
5
+ // generated .github/workflows/*.yml — edit this graph and rebuild.
6
+ //
7
+ // This default graph is a complete "dark factory": issues in → reviewed, auto-merged PRs
8
+ // out, with self-healing (janitor + supervisor) and self-improving (retro) lanes. Every
9
+ // cycle MUST keep a bounded escape edge to an `exit` node.
10
+
11
+ digraph harness {
12
+ // ── nodes ─────────────────────────────────────────────────────────────────
13
+ start [type=start]
14
+
15
+ // intake: triage an incoming issue and route it to a lane
16
+ scout [type=issue-agent, role="agents/roles/scout.md", context=issue]
17
+
18
+ // optional design lane for big/ambiguous issues (read-only, posts a plan)
19
+ planner [type=analyst, role="agents/roles/planner.md", context=issue, output=comment]
20
+
21
+ // the producer: turns a labeled issue into a tested PR (the only code-writer here)
22
+ builder [type=producer, role="agents/roles/builder.md", context=issue]
23
+
24
+ // review: reads the diff, posts an approve / request-changes verdict
25
+ // (add gates="ci.yml" once the repo has a CI workflow the reviewer should wait for)
26
+ reviewer [type=pr-review, role="agents/roles/reviewer.md", context="pr-diff"]
27
+
28
+ // bounded fix loop with the reviewer
29
+ fixer [type=pr-fix, role="agents/roles/fixer.md", max_attempts=3]
30
+
31
+ // approval: automated merge policy (swap for a human-gate if approval must be human)
32
+ merge_gate [type=merge-gate, policy="agents/policy/merge.yaml", schedule="*/30 * * * *"]
33
+
34
+ // self-healing: rebase conflicted PRs; re-drive stranded issues/PRs
35
+ janitor [type=scheduled-agent, role="agents/roles/janitor.md", schedule="*/30 * * * *"]
36
+ supervisor [type=scheduled-agent, role="agents/roles/supervisor.md", schedule="17 * * * *"]
37
+
38
+ // self-improving: mine the record for recurring lessons → team memory
39
+ retro [type=scheduled-agent, role="agents/roles/retro.md", schedule="0 7 * * 1-5"]
40
+
41
+ // bounded escape hatch — the terminal a stuck unit lands in
42
+ needs_human [type=exit]
43
+
44
+ // ── edges ─────────────────────────────────────────────────────────────────
45
+ start -> scout [on="issues.opened"]
46
+ scout -> planner [when="label=plan"] // label names resolve via foundry.config.yaml
47
+ scout -> builder [when="label=build"]
48
+ planner -> builder [when="label=build"]
49
+ builder -> reviewer [on="pull_request.opened"]
50
+ reviewer -> merge_gate [when="verdict=approve"]
51
+ reviewer -> fixer [when="verdict=request_changes"]
52
+ fixer -> reviewer [on="push"] // retry loop…
53
+ fixer -> needs_human [when="attempts>=3"] // …with a bounded escape (enforced at runtime)
54
+ }
@@ -0,0 +1,54 @@
1
+ # policy/merge.yaml — the merge-gate's policy. Read by the runtime-core merge-gate
2
+ # action and evaluated into a {merge | skip | label} decision + audit comment.
3
+ #
4
+ # IMPORTANT: these are FLAT snake_case keys (normalized to camelCase at runtime).
5
+ # The action reads exactly these names — do not nest them under approval:/ci:/etc.
6
+
7
+ # Only consider PRs whose head branch starts with this prefix.
8
+ branch_prefix: "agent/"
9
+
10
+ # Approval — the Reviewer posts its verdict in a review BODY; count a body matching
11
+ # this regex as approval (a bot can't formally APPROVE its own PR).
12
+ approval_body_regex: "Verdict.*APPROVE"
13
+ # A matching body INVALIDATES earlier approvals (latest verdict wins). Keep it anchored
14
+ # to the verdict line — a bare substring would misread approvals that mention the
15
+ # earlier requested changes in prose.
16
+ rejection_body_regex: "Verdict.*REQUEST_CHANGES"
17
+ approval_delay_minutes: 0 # cool-off after approval before auto-merge (0 = none)
18
+
19
+ # CI — require the check rollup to be passing; optionally ignore named checks.
20
+ require_ci: true
21
+ ci_ignore_check_names: []
22
+
23
+ # Size — hand-written additions cap; over this, label for a human instead of merging.
24
+ # exclude_globs discount generated files/lockfiles from the count.
25
+ max_additions: 800
26
+ exclude_globs:
27
+ - "**/__pycache__/**"
28
+
29
+ # Protected paths — touching any of these blocks auto-merge (labels needs-human).
30
+ protected_paths:
31
+ - ".github/"
32
+
33
+ # Rebase / conflicts.
34
+ # - require_clean_rebase: false — GitHub's mergeable_state is computed async and races
35
+ # on fresh PRs; instead we let the merge ATTEMPT fail and react (see rebase_label).
36
+ # - rebase_label: applied when a merge attempt fails on a conflict; the 🧹 Janitor
37
+ # (scheduled sweep) picks up this label, rebases, and de-labels.
38
+ require_clean_rebase: false
39
+ rebase_label: needs-rebase
40
+
41
+ # Merge — squash, NOT rebase: the Janitor resolves conflicts with a merge commit, and a
42
+ # rebase-merge cannot rebase a branch containing merge commits.
43
+ merge_method: squash
44
+ delete_branch_on_merge: true
45
+
46
+ # A PR already carrying one of these is skipped (the Janitor/human owns it, not the gate).
47
+ blocking_labels:
48
+ - needs-human
49
+ - needs-rebase
50
+
51
+ # Labels applied on a skip outcome, so skips route to the right owner.
52
+ labels:
53
+ needs_human: needs-human # too-large / protected-path
54
+ rebase_needed: needs-rebase # proactive rebase label (used if require_clean_rebase: true)
@@ -0,0 +1,33 @@
1
+ <!-- roles/<name>.md — a job description (content, runtime-loaded). Editing the prose below
2
+ needs NO rebuild; only changing the `handoffs` (which must mirror the node's out-edges
3
+ in harness.dot) is a topology change that requires `gp-foundry build`. -->
4
+ ---
5
+ role: <RoleName> # human-readable identity, e.g. Builder / Copywriter
6
+ emoji: "<emoji>" # your persona emoji, e.g. "👷" — you lead every message with it
7
+ type: <node-type> # must equal this node's type in harness.dot
8
+ mission: <one sentence — what this role turns X into Y>
9
+ accountable_for: # the definition-of-done, as checkable bullets
10
+ - <e.g. tests pass>
11
+ - <e.g. stays in scope (scope.yaml)>
12
+ handoffs: # MUST equal this node's out-edges in harness.dot (validated both ways)
13
+ - to: <target-node-id> # the node id from harness.dot, e.g. merge_gate
14
+ when: <guard> # e.g. PR opened (mirrors the edge's on=/when=)
15
+ tools: "<allowed-tools list, e.g. Read,Write,Edit,Glob,Grep,Bash(git:*),Bash(gh:*)>"
16
+ quality_bar: <the non-negotiable, e.g. never report success with failing tests>
17
+ ---
18
+
19
+ ## <emoji> <RoleName>
20
+
21
+ You are the **<emoji> <RoleName>**. <one line: what you turn the input below into>.
22
+
23
+ 1. <the steps this role performs>
24
+ 2. <...>
25
+ 3. Communicate per the communication guide: lead every message with your `## <emoji> <RoleName>`
26
+ header; keep the visible summary substantive (what/why/verified — don't hide it in `<details>`);
27
+ and write your note / plan / review as a **brief the next role can act on** (see your `handoffs`).
28
+
29
+ ## Repo-specific guidance
30
+
31
+ <!-- The ONLY per-repo delta. Put stack commands, conventions, and gotchas here.
32
+ e.g. "Run `make generate` if proto/sqlc files change before testing." -->
33
+ - <repo-specific instruction>
@@ -0,0 +1,21 @@
1
+ # scope.yaml — the invariants from interview Q2. Canonical, CI-enforced.
2
+ # immutable_paths: agents can NEVER modify these; a CI check fails the PR and
3
+ # agent-fallback strips any such edits before pushing. This is the hard safety boundary.
4
+ # forbidden_paths / forbidden_operations: prompt-enforced (softer); an improve/gardener lane
5
+ # may adjust these, but never immutable_paths.
6
+
7
+ immutable_paths: # enforced by CI check, never modifiable by agents
8
+ - .github/workflows/ # the generated harness itself — agents must not self-edit YAML
9
+ # - <add paths that must never change, e.g. infra, secrets config>
10
+
11
+ forbidden_paths: # prompt-enforced, adjustable by a maintenance lane
12
+ # - <e.g. terraform/>
13
+
14
+ forbidden_operations:
15
+ # - <e.g. infrastructure changes>
16
+
17
+ guidance: # soft guidance injected into every agent's prompt
18
+ - prefer small, focused changes
19
+ - when in doubt, open a draft PR and explain what's left
20
+ # closes the Retro's learning loop: lessons it distills are read before working
21
+ - "before implementing, check .github/agents/memory/topics/ for relevant prior lessons"