From 551d8db20db94879a50b551c382efa3d8a5971b2 Mon Sep 17 00:00:00 2001 From: rkoster Date: Thu, 25 Jun 2026 18:44:14 +0200 Subject: [PATCH 01/15] Add README with repo purpose, roadmap, and contribution pointers Signed-off-by: rkoster --- README.md | 48 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 48 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..293343d --- /dev/null +++ b/README.md @@ -0,0 +1,48 @@ +# Agentic Runtime — Working Group Notes + +> **Status: Phase 1 of 4 — Research (open for contributions).** +> This repository is in its initial ideation/research phase. The process described below +> is itself under review — see [`IDEATION.md`](./IDEATION.md) and please leave feedback on +> the pull request that introduces it. + +Research notes, design documents, and RFCs for the Cloud Foundry +[**Agentic Runtime Working Group**](https://github.com/cloudfoundry/community/blob/main/toc/working-groups/agentic-runtime.md). + +The working group's mission is to run AI agents and LLM-powered workloads as first-class +citizens on Cloud Foundry — deployed, managed, secured, scaled, and observed using the +same platform-native primitives developers and operators rely on today. + +## What this repo is for + +This repo bootstraps a **crowd-sourced, distributed research phase**. Anyone interested in +the future of agentic workloads on Cloud Foundry is invited to contribute **research +notes** as pull requests. The accumulated notes become the raw material for a +working-group workshop that identifies themes and spins up focused proof-of-concept and +RFC work. + +## The roadmap + +1. **Research (now)** — contributors submit research notes via PRs into [`research/`](./research). +2. **Workshop** — the working group clusters the notes into emergent themes. +3. **Match** — members align their interests to themes. +4. **POC / RFC** — per-theme tracks produce proofs-of-concept and Cloud Foundry RFCs. + +See [`IDEATION.md`](./IDEATION.md) for the full brief. + +## How to contribute + +Read [`CONTRIBUTING.md`](./CONTRIBUTING.md), copy [`research/TEMPLATE.md`](./research/TEMPLATE.md), +fill it in, and open a pull request. See [`research/cf-runtime-gaps.md`](./research/cf-runtime-gaps.md) +for a complete example. + +## Community + +- **Charter:** [toc/working-groups/agentic-runtime.md](https://github.com/cloudfoundry/community/blob/main/toc/working-groups/agentic-runtime.md) +- **Slack:** [#ai-wg](https://cloudfoundry.slack.com/archives/C0B214KJ1HA) on the Cloud Foundry workspace +- **Working groups:** [cloudfoundry/community](https://github.com/cloudfoundry/community/blob/main/toc/working-groups/WORKING-GROUPS.md) + +## License + +Apache 2.0 — see [`LICENSE`](./LICENSE). Contributions require a +[Developer Certificate of Origin](https://developercertificate.org/) sign-off +(`git commit -s`). From 208f51b0d77a53740b5cf9f38466c90edc34d828 Mon Sep 17 00:00:00 2001 From: rkoster Date: Thu, 25 Jun 2026 18:44:49 +0200 Subject: [PATCH 02/15] Add ideation brief describing the four-phase research process Signed-off-by: rkoster --- IDEATION.md | 98 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 98 insertions(+) create mode 100644 IDEATION.md diff --git a/IDEATION.md b/IDEATION.md new file mode 100644 index 0000000..b69be3d --- /dev/null +++ b/IDEATION.md @@ -0,0 +1,98 @@ +# Ideation Brief — Agentic Runtime Research Phase + +**Status:** Proposed (this brief is itself under review — feedback welcome on the PR). +**Working group:** [Cloud Foundry Agentic Runtime](https://github.com/cloudfoundry/community/blob/main/toc/working-groups/agentic-runtime.md) + +## Why this phase exists + +The Agentic Runtime Working Group is new, and the design space — running AI agents and +LLM-powered workloads as first-class citizens on Cloud Foundry — is broad and moving fast. +Before committing to specific designs or RFCs, we want to map the landscape together: +gather what the community already knows, surface prior art, and identify where Cloud +Foundry's primitives help or fall short. + +This repository is the home for that research. It is deliberately **lightweight and +open**: the goal is breadth of input from anyone interested, not polished deliverables. + +## The four-phase roadmap + +This research phase is step one of four: + +1. **Research (now, ~a few weeks).** Contributors submit short, sourced **research notes** + into [`research/`](./research) via pull requests. We want broad coverage of the agentic + ecosystem, relevant technologies, prior art, and Cloud Foundry gaps. +2. **Workshop.** The working group meets to read across the accumulated notes and cluster + them into **themes**. Themes are *not* defined up front — they emerge from what people + actually contribute. +3. **Match.** Working-group members align their interests with the identified themes and + form small groups around them. +4. **POC / RFC.** Each theme group spins up focused work — proofs-of-concept and Cloud + Foundry RFCs — feeding the platform roadmap. + +We are building only what Phase 1 needs right now. Structure for themes, POCs, and RFCs +will be added once the workshop has shaped it. + +## What to contribute in Phase 1 + +**In scope** — research notes that inform the design space, such as: + +- Analyses of agent frameworks, protocols, and platforms (how others solve a problem). +- Prior art and standards (e.g. identity, sandboxing, observability conventions). +- Cloud Foundry gaps and friction points for agentic workloads. +- Surveys of the surrounding ecosystem and where it's heading. + +**Out of scope for now** — finished solutions, designs, or RFCs. Those come in Phase 4, +after the workshop. A note may *raise* questions and point at possible directions, but its +job is to inform, not to settle on a final answer. + +## What makes a good research note + +- **Sourced.** Link to the primary material so others can dig in. +- **Summarized.** A few sentences capturing the essence — assume the reader is busy. +- **Connected to CF.** Say how it relates to Cloud Foundry primitives or gaps, even if the + connection is "this doesn't map cleanly, and here's why." +- **Honest about open questions.** Unknowns are valuable signal for the workshop. + +Each note follows a small template — see [`research/TEMPLATE.md`](./research/TEMPLATE.md) +and the worked example [`research/cf-runtime-gaps.md`](./research/cf-runtime-gaps.md). +[`CONTRIBUTING.md`](./CONTRIBUTING.md) explains the mechanics. + +## Tagging: how themes will emerge + +Each note carries free-form `tags` in its frontmatter. At the workshop we'll use these +tags to cluster notes into themes — so tagging well is how you influence the agenda. + +Tags are **descriptive, not prescriptive.** To reduce noise, here is a *non-binding* +starting vocabulary drawn from the working-group charter. Use these where they fit, and +invent new ones where they don't: + +- `identity` — workload/agent identity, authn, authz +- `runtime-lifecycle` — how agents are deployed, started, stopped, resumed +- `sandboxing-isolation` — execution isolation, policy enforcement +- `orchestration` — multi-step / multi-agent coordination +- `inter-agent-comms` — agent-to-agent and agent-to-tool protocols +- `observability-governance` — telemetry, audit, compliance +- `autoscaling` — event-driven and scale-to-zero patterns +- `ecosystem-survey` — landscape scans of tools, frameworks, vendors + +**These are hints, not buckets.** Don't file your note into a predetermined theme — just +describe it accurately and let the themes emerge. + +## Timeline + +Specific dates (the research window length and the workshop date) are set at the +working-group kickoff and announced in +[#ai-wg](https://cloudfoundry.slack.com/archives/C0B214KJ1HA) on Slack. Expect the research +window to run a few weeks. + +## How to participate + +1. Read [`CONTRIBUTING.md`](./CONTRIBUTING.md). +2. Add a note using the template and open a PR. +3. Join the conversation in [#ai-wg](https://cloudfoundry.slack.com/archives/C0B214KJ1HA). + +## Feedback on this process + +This brief is part of the first pull request *on purpose* — so the working group can shape +the process before research arrives at volume. If something here doesn't serve the goal, +say so on the PR. From c03af90a6ba1270999363d17bcf8949a5f4580cb Mon Sep 17 00:00:00 2001 From: rkoster Date: Thu, 25 Jun 2026 18:45:14 +0200 Subject: [PATCH 03/15] Add CONTRIBUTING guide for research-note submissions Signed-off-by: rkoster --- CONTRIBUTING.md | 66 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 66 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..e74495a --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,66 @@ +# Contributing + +Thanks for helping shape the future of agentic workloads on Cloud Foundry. During the +current **research phase**, contributions take the form of **research notes** added to +[`research/`](./research) via pull requests. + +For the why and the bigger picture, read [`IDEATION.md`](./IDEATION.md). + +## Quick start + +1. **Fork** this repository (or, if you're a working-group member with write access, create + a branch). +2. **Copy the template:** + ```bash + cp research/TEMPLATE.md research/my-topic.md + ``` +3. **Fill it in.** Keep it short and sourced. See + [`research/cf-runtime-gaps.md`](./research/cf-runtime-gaps.md) for a complete example and + [`research/README.md`](./research/README.md) for the frontmatter schema. +4. **Commit with a DCO sign-off:** + ```bash + git add research/my-topic.md + git commit -s -m "Add research note: my topic" + ``` +5. **Open a pull request.** A CI check validates your note's frontmatter and structure. A + working-group tech lead will give it a quick look and merge. + +## Filename convention + +- Lowercase **kebab-case**, ending in `.md`: `research/agent-frameworks.md`. +- If your topic collides with an existing note, add your GitHub handle as a suffix: + `research/agent-frameworks-rkoster.md`. + +## Frontmatter + +Every note starts with a YAML frontmatter block. Required keys: `title`, `author`, `date`, +`tags`, `status`, `sources`. The `cf_areas` key is optional. The full schema and field +descriptions live in [`research/README.md`](./research/README.md). + +Tagging well matters — tags are how the workshop clusters notes into themes. See the +suggested (non-binding) vocabulary in +[`IDEATION.md`](./IDEATION.md#tagging-how-themes-will-emerge). + +## Review & merge + +Research notes are low-risk, so we optimize for throughput: + +- CI validates frontmatter, filename, and required sections. +- Any working-group **tech lead** can merge once CI passes and the note is on-topic and not + a duplicate. +- Substantive review of *ideas* happens at the workshop, not as a merge gate. + +## Developer Certificate of Origin (DCO) + +All commits must be signed off, certifying you wrote the contribution or otherwise have the +right to submit it under the repository's license. Add `-s` to your commit: + +```bash +git commit -s -m "Add research note: my topic" +``` + +This appends a `Signed-off-by:` line. See [developercertificate.org](https://developercertificate.org/). + +## Code of conduct + +This project follows the [Cloud Foundry Code of Conduct](./CODE_OF_CONDUCT.md). From 428f2838e0c6346dbaf777a733f9d4a35b8fbad6 Mon Sep 17 00:00:00 2001 From: rkoster Date: Thu, 25 Jun 2026 18:45:31 +0200 Subject: [PATCH 04/15] Add Code of Conduct referencing the CF Foundation CoC Signed-off-by: rkoster --- CODE_OF_CONDUCT.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) create mode 100644 CODE_OF_CONDUCT.md diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..62bae26 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,13 @@ +# Code of Conduct + +The Cloud Foundry Agentic Runtime Working Group, like all Cloud Foundry community spaces, +operates under the **Cloud Foundry Foundation Code of Conduct**. + +Please read it here: https://www.cloudfoundry.org/code-of-conduct/ + +By participating in this repository — through issues, pull requests, reviews, or any other +interaction — you agree to abide by its terms. + +To report a concern, follow the reporting instructions in the linked Code of Conduct, or +reach a working-group lead in [#ai-wg](https://cloudfoundry.slack.com/archives/C0B214KJ1HA) +on the Cloud Foundry Slack. From b5039ae13fbf4b13c7973c34ad9446d4a6e77b0f Mon Sep 17 00:00:00 2001 From: rkoster Date: Thu, 25 Jun 2026 18:45:56 +0200 Subject: [PATCH 05/15] Document the research-note frontmatter schema and conventions Signed-off-by: rkoster --- research/README.md | 68 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 68 insertions(+) create mode 100644 research/README.md diff --git a/research/README.md b/research/README.md new file mode 100644 index 0000000..7fea1bc --- /dev/null +++ b/research/README.md @@ -0,0 +1,68 @@ +# Research notes + +This directory holds the working group's research notes for the current research phase +(see [`../IDEATION.md`](../IDEATION.md)). + +The directory is intentionally **flat**: every note is a single Markdown file here, with +metadata in YAML frontmatter. We do **not** sort notes into topic folders — themes are +identified later, at the workshop, by clustering on tags. Filing notes into folders now +would pre-impose the very themes we want to let emerge. + +## Adding a note + +Copy [`TEMPLATE.md`](./TEMPLATE.md), rename it to a kebab-case topic (`my-topic.md`), and +fill it in. See [`cf-runtime-gaps.md`](./cf-runtime-gaps.md) for a complete example, and +[`../CONTRIBUTING.md`](../CONTRIBUTING.md) for the full workflow. + +## Frontmatter schema + +Each note begins with a YAML frontmatter block: + +```yaml +--- +title: Cloud Foundry gaps for AI agents +author: Ruben Koster (@rkoster) +date: 2026-06-25 +tags: [ecosystem-survey, autoscaling, identity] +cf_areas: [diego, capi, uaa, loggregator] +status: draft +sources: + - https://example.com/source-one +--- +``` + +| Field | Required | Description | +|-------|----------|-------------| +| `title` | yes | Concise human-readable title. | +| `author` | yes | `Name (@github-handle)`. | +| `date` | yes | `YYYY-MM-DD`, the date the note was written. | +| `tags` | yes | List of free-form tags. Drives theme clustering — see the suggested vocabulary in [`../IDEATION.md`](../IDEATION.md#tagging-how-themes-will-emerge). | +| `cf_areas` | no | List of related Cloud Foundry components (e.g. `diego`, `capi`, `uaa`, `bosh`, `loggregator`). | +| `status` | yes | `draft` or `reviewed`. | +| `sources` | yes | List of URLs to the primary material. | + +## Body structure + +After the frontmatter, use these four sections: + +```markdown +## Summary + +Two to four sentences capturing the essence. + +## Key findings + +- Bullet points with the substantive takeaways. + +## CF relevance + +How this maps to Cloud Foundry primitives or gaps — including "it doesn't map cleanly, and +here's why." + +## Open questions + +- Unresolved questions worth raising at the workshop. +``` + +A CI check validates that every note has valid frontmatter, a kebab-case filename, and +these four sections. From a76eb65e564546e9a4f8ffb1cd83ad5206b5f058 Mon Sep 17 00:00:00 2001 From: rkoster Date: Thu, 25 Jun 2026 18:46:16 +0200 Subject: [PATCH 06/15] Add research-note template Signed-off-by: rkoster --- research/TEMPLATE.md | 33 +++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) create mode 100644 research/TEMPLATE.md diff --git a/research/TEMPLATE.md b/research/TEMPLATE.md new file mode 100644 index 0000000..36db377 --- /dev/null +++ b/research/TEMPLATE.md @@ -0,0 +1,33 @@ +--- +title: +author: (@your-github-handle) +date: 2026-01-01 +tags: [, ] +cf_areas: [] +status: draft +sources: + - +--- + + + +## Summary + + + +## Key findings + +- + +## CF relevance + + + +## Open questions + +- From 0e90df45aa721a33fb5e2427c743880e68f700f5 Mon Sep 17 00:00:00 2001 From: rkoster Date: Thu, 25 Jun 2026 18:46:48 +0200 Subject: [PATCH 07/15] Add worked example research note: CF gaps for AI agents Signed-off-by: rkoster --- research/cf-runtime-gaps.md | 72 +++++++++++++++++++++++++++++++++++++ 1 file changed, 72 insertions(+) create mode 100644 research/cf-runtime-gaps.md diff --git a/research/cf-runtime-gaps.md b/research/cf-runtime-gaps.md new file mode 100644 index 0000000..38f1861 --- /dev/null +++ b/research/cf-runtime-gaps.md @@ -0,0 +1,72 @@ +--- +title: Cloud Foundry gaps and friction points for AI agents +author: Ruben Koster (@rkoster) +date: 2026-06-25 +tags: [ecosystem-survey, autoscaling, identity, sandboxing-isolation, inter-agent-comms, observability-governance, runtime-lifecycle] +cf_areas: [diego, capi, uaa, loggregator, routing, buildpacks] +status: draft +sources: + - https://github.com/cloudfoundry/community/blob/main/toc/working-groups/agentic-runtime.md +--- + +> **This is the worked example note.** It shows the expected format and depth. Use it as a +> reference when writing your own — see [`../CONTRIBUTING.md`](../CONTRIBUTING.md). + +## Summary + +Cloud Foundry's runtime, routing, autoscaling, and observability stack is heavily optimized +for stateless HTTP applications. AI agents and LLM-powered workloads stress a different set +of assumptions — background workers, session state, per-agent identity, non-HTTP protocols, +and bursty scale-to-zero demand. This note catalogs seven gaps where CF's current +primitives create friction for agentic workloads, as a starting map for the research phase. + +## Key findings + +- **Async worker observability.** CF's observability, routing, and autoscaling are + HTTP-biased. Frameworks like CrewAI and AutoGen rely on background worker queues (e.g. + Celery) because of web-request timeouts, and CF has no native queue-depth autoscaling + (compared with Kubernetes KEDA). +- **Session-stateful workloads.** CF apps are stateless by default. There is no native + session persistence with auto-resume (unlike Azure's per-session VM sandboxes); state + must be externalized to bound services, which works but isn't integrated. +- **Agent identity model.** CF identity is app-centric (manifest `name`, service bindings), + with no per-agent identities, no agent-to-agent authentication, and no native agent + discovery. +- **Protocol diversity.** Agents use A2A, AG-UI (bidirectional streaming), MCP, webhooks, + and custom streaming protocols. CF routing is HTTP-centric; WebSockets/SSE are supported + but there's no abstraction for non-HTTP agent protocols. +- **Buildpack ecosystem.** No AI/agent-specific buildpacks exist — no standard packaging + for LangGraph/CrewAI/LlamaIndex, no OTel GenAI auto-instrumentation, no agent entrypoint + convention. +- **Scaling model.** CF's min/max-instance model doesn't match bursty agent demand; there's + no scale-to-zero with warm resume (Azure's per-session model) versus CF's per-replica + scaling. +- **Tool access & MCP integration.** Agents need to discover and call tools (databases, + APIs, MCP servers), but CF's service-binding model targets services, not tools, and MCP + servers must be deployed as apps with manual routing. + +| Gap | CF current state | What's needed | +|-----|------------------|---------------| +| Async worker observability | HTTP-biased | Queue-depth autoscaling, worker metrics | +| Session state | Stateless apps | Session persistence with auto-resume | +| Agent identity | App-centric | Per-agent identities, agent discovery | +| Protocol diversity | HTTP-centric | A2A, AG-UI, MCP routing | +| Buildpacks | No AI buildpacks | Agent framework buildpacks, OTel auto-instrumentation | +| Scaling | Per-replica | Per-session scaling, scale-to-zero with warm resume | +| Tool access | Service bindings | Tool discovery, MCP integration | + +## CF relevance + +Each gap points at a CF component that may need to evolve for agentic workloads: Diego and +CAPI for lifecycle/scaling and sandboxing, UAA for agent identity, Loggregator and OTel +conventions for observability, the routing tier for non-HTTP protocols, and the buildpack +ecosystem for packaging and instrumentation. Several gaps overlap (identity underpins both +agent-to-agent comms and tool access), which makes them good candidates for theme +clustering at the workshop. + +## Open questions + +- Which gaps are most urgent for real agent workloads people are trying to run on CF today? +- Where should a gap be closed by CF platform changes versus solved with buildpacks, + services, or conventions on top of existing primitives? +- Which gaps are interdependent enough to belong to a single theme/POC track? From 80c50fd569da588f237af55a24a06968f7a905f5 Mon Sep 17 00:00:00 2001 From: rkoster Date: Thu, 25 Jun 2026 18:47:15 +0200 Subject: [PATCH 08/15] Add CODEOWNERS and pull-request template Signed-off-by: rkoster --- .github/CODEOWNERS | 3 +++ .github/PULL_REQUEST_TEMPLATE.md | 17 +++++++++++++++++ 2 files changed, 20 insertions(+) create mode 100644 .github/CODEOWNERS create mode 100644 .github/PULL_REQUEST_TEMPLATE.md diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS new file mode 100644 index 0000000..2f5b48d --- /dev/null +++ b/.github/CODEOWNERS @@ -0,0 +1,3 @@ +# Review for this repo routes to the Agentic Runtime working-group leads. +# See: https://github.com/cloudfoundry/community/blob/main/toc/working-groups/agentic-runtime.md +* @beyhan @wayneeseguin @rkoster @itsouvalas diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..4b74496 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,17 @@ + + +## What is this note about? + + + +## Checklist + +- [ ] My note lives in `research/` and uses a lowercase kebab-case filename. +- [ ] It starts from `research/TEMPLATE.md` and has valid frontmatter + (`title`, `author`, `date`, `tags`, `status`, `sources`). +- [ ] It has the four sections: Summary, Key findings, CF relevance, Open questions. +- [ ] I added relevant `tags` (see the suggested vocabulary in `IDEATION.md`). +- [ ] Sources are linked. +- [ ] It's on-topic for agentic workloads on Cloud Foundry and not a duplicate of an + existing note. +- [ ] My commits are signed off (`git commit -s`) per the DCO. From e46cc36d090f1a6564443e65c243983deff775fd Mon Sep 17 00:00:00 2001 From: rkoster Date: Thu, 25 Jun 2026 18:47:43 +0200 Subject: [PATCH 09/15] Add research-note validation script Signed-off-by: rkoster --- .github/scripts/validate_notes.py | 125 ++++++++++++++++++++++++++++++ 1 file changed, 125 insertions(+) create mode 100644 .github/scripts/validate_notes.py diff --git a/.github/scripts/validate_notes.py b/.github/scripts/validate_notes.py new file mode 100644 index 0000000..b8941da --- /dev/null +++ b/.github/scripts/validate_notes.py @@ -0,0 +1,125 @@ +#!/usr/bin/env python3 +"""Validate research notes in research/. + +For every research/*.md file except README.md and TEMPLATE.md this checks: + - the filename is lowercase kebab-case ending in .md + - a YAML frontmatter block is present and parses + - required frontmatter keys are present and well-typed + - the four required body section headings are present + +Exits non-zero (printing every problem) if any note is invalid. +""" + +from __future__ import annotations + +import datetime as dt +import pathlib +import re +import sys + +import yaml + +RESEARCH_DIR = pathlib.Path("research") +SKIP = {"README.md", "TEMPLATE.md"} + +REQUIRED_KEYS = { + "title": str, + "author": str, + "date": object, # validated separately + "tags": list, + "status": str, + "sources": list, +} +ALLOWED_STATUS = {"draft", "reviewed"} +REQUIRED_SECTIONS = [ + "## Summary", + "## Key findings", + "## CF relevance", + "## Open questions", +] +FILENAME_RE = re.compile(r"^[a-z0-9]+(-[a-z0-9]+)*\.md$") +FRONTMATTER_RE = re.compile(r"^---\n(.*?)\n---\n", re.DOTALL) +DATE_RE = re.compile(r"^\d{4}-\d{2}-\d{2}$") + + +def validate_file(path: pathlib.Path) -> list[str]: + problems: list[str] = [] + name = path.name + + if not FILENAME_RE.match(name): + problems.append( + f"filename must be lowercase kebab-case ending in .md (got '{name}')" + ) + + text = path.read_text(encoding="utf-8") + + match = FRONTMATTER_RE.match(text) + if not match: + problems.append("missing YAML frontmatter block (must start with '---' on line 1)") + return [f"{path}: {p}" for p in problems] + + try: + meta = yaml.safe_load(match.group(1)) + except yaml.YAMLError as exc: + problems.append(f"frontmatter is not valid YAML: {exc}") + return [f"{path}: {p}" for p in problems] + + if not isinstance(meta, dict): + problems.append("frontmatter must be a YAML mapping") + return [f"{path}: {p}" for p in problems] + + for key, expected_type in REQUIRED_KEYS.items(): + value = meta.get(key) + if value in (None, "", [], {}): + problems.append(f"missing required frontmatter key '{key}'") + continue + if expected_type is not object and not isinstance(value, expected_type): + problems.append(f"frontmatter key '{key}' must be a {expected_type.__name__}") + + status = meta.get("status") + if isinstance(status, str) and status not in ALLOWED_STATUS: + problems.append( + f"'status' must be one of {sorted(ALLOWED_STATUS)} (got '{status}')" + ) + + date_val = meta.get("date") + if date_val not in (None, "", [], {}): + if isinstance(date_val, dt.date): + pass # YAML already parsed a date + elif isinstance(date_val, str) and DATE_RE.match(date_val): + pass + else: + problems.append("'date' must be in YYYY-MM-DD format") + + body = text[match.end():] + for section in REQUIRED_SECTIONS: + if not re.search(rf"^{re.escape(section)}\s*$", body, re.MULTILINE): + problems.append(f"missing required section heading '{section}'") + + return [f"{path}: {p}" for p in problems] + + +def main() -> int: + if not RESEARCH_DIR.is_dir(): + print(f"error: '{RESEARCH_DIR}/' directory not found", file=sys.stderr) + return 1 + + notes = sorted(p for p in RESEARCH_DIR.glob("*.md") if p.name not in SKIP) + + problems: list[str] = [] + for note in notes: + problems.extend(validate_file(note)) + + if problems: + print("Research note validation failed:\n") + for problem in problems: + print(f" - {problem}") + print(f"\n{len(problems)} problem(s) across {len(notes)} note(s).") + return 1 + + print(f"OK: {len(notes)} research note(s) valid.") + return 0 + + +if __name__ == "__main__": + sys.exit(main()) From 17cb35c318e70900518e6e3da8c7ac27cb412198 Mon Sep 17 00:00:00 2001 From: rkoster Date: Thu, 25 Jun 2026 18:48:01 +0200 Subject: [PATCH 10/15] Add CI workflow to validate research notes on PRs Signed-off-by: rkoster --- .github/workflows/lint.yml | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) create mode 100644 .github/workflows/lint.yml diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml new file mode 100644 index 0000000..65e7e49 --- /dev/null +++ b/.github/workflows/lint.yml @@ -0,0 +1,32 @@ +name: Validate research notes + +on: + pull_request: + paths: + - "research/**" + - ".github/scripts/validate_notes.py" + - ".github/workflows/lint.yml" + push: + branches: [main] + paths: + - "research/**" + - ".github/scripts/validate_notes.py" + - ".github/workflows/lint.yml" + +jobs: + validate: + runs-on: ubuntu-latest + steps: + - name: Check out + uses: actions/checkout@v4 + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: "3.12" + + - name: Install dependencies + run: pip install "pyyaml>=6" + + - name: Validate research notes + run: python .github/scripts/validate_notes.py From 746308366a3cbb2c4ba41d5aee22902c5fb79cc8 Mon Sep 17 00:00:00 2001 From: rkoster Date: Thu, 25 Jun 2026 19:22:46 +0200 Subject: [PATCH 11/15] Replace DCO sign-off guidance with the Cloud Foundry CLA CF projects gate on a CLA signed via the EasyCLA bot (prompted on the first PR), not a Developer Certificate of Origin. Point contributors at EasyCLA and drop the git commit -s instructions so we don't ask others to sign off unnecessarily. Signed-off-by: rkoster --- .github/PULL_REQUEST_TEMPLATE.md | 2 +- CONTRIBUTING.md | 19 ++++++++----------- README.md | 7 ++++--- 3 files changed, 13 insertions(+), 15 deletions(-) diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 4b74496..e363c0c 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -14,4 +14,4 @@ - [ ] Sources are linked. - [ ] It's on-topic for agentic workloads on Cloud Foundry and not a duplicate of an existing note. -- [ ] My commits are signed off (`git commit -s`) per the DCO. +- [ ] I've signed the Cloud Foundry CLA (the EasyCLA bot prompts you on your first PR). diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e74495a..3db86bc 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -17,10 +17,10 @@ For the why and the bigger picture, read [`IDEATION.md`](./IDEATION.md). 3. **Fill it in.** Keep it short and sourced. See [`research/cf-runtime-gaps.md`](./research/cf-runtime-gaps.md) for a complete example and [`research/README.md`](./research/README.md) for the frontmatter schema. -4. **Commit with a DCO sign-off:** +4. **Commit your note:** ```bash git add research/my-topic.md - git commit -s -m "Add research note: my topic" + git commit -m "Add research note: my topic" ``` 5. **Open a pull request.** A CI check validates your note's frontmatter and structure. A working-group tech lead will give it a quick look and merge. @@ -50,16 +50,13 @@ Research notes are low-risk, so we optimize for throughput: a duplicate. - Substantive review of *ideas* happens at the workshop, not as a merge gate. -## Developer Certificate of Origin (DCO) +## Contributor License Agreement (CLA) -All commits must be signed off, certifying you wrote the contribution or otherwise have the -right to submit it under the repository's license. Add `-s` to your commit: - -```bash -git commit -s -m "Add research note: my topic" -``` - -This appends a `Signed-off-by:` line. See [developercertificate.org](https://developercertificate.org/). +All committers to a Cloud Foundry Foundation project must sign a Contributor License +Agreement. You don't need to do anything up front: the **EasyCLA** bot comments on your +first pull request with a link to sign (individual or corporate). Once it's signed, the +CLA check goes green and your PR can be merged. You can also +[sign in to EasyCLA](https://corporate.v1.easycla.lfx.linuxfoundation.org/) ahead of time. ## Code of conduct diff --git a/README.md b/README.md index 293343d..5491d1b 100644 --- a/README.md +++ b/README.md @@ -43,6 +43,7 @@ for a complete example. ## License -Apache 2.0 — see [`LICENSE`](./LICENSE). Contributions require a -[Developer Certificate of Origin](https://developercertificate.org/) sign-off -(`git commit -s`). +Apache 2.0 — see [`LICENSE`](./LICENSE). By contributing you agree to the Cloud Foundry +[Contributor License Agreement](https://github.com/cloudfoundry/community/blob/main/CONTRIBUTING.md). +You don't need to do anything up front — the [EasyCLA](https://corporate.v1.easycla.lfx.linuxfoundation.org/) +bot prompts you to sign on your first pull request. From f81abbb991b5cf9727e896f626b9d3f1733daa65 Mon Sep 17 00:00:00 2001 From: rkoster Date: Thu, 25 Jun 2026 19:30:31 +0200 Subject: [PATCH 12/15] Refocus Phase 1 on outward research; drop seeded CF-gaps note MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The worked example research/cf-runtime-gaps.md read as a definitive, maintainer-authored list of Cloud Foundry gaps. Identifying gaps should be an outcome of Phase 1 — synthesized at the workshop from the body of research — not a starting point that pre-empts what contributors find or crowds out their own gap analyses. Remove that note (to revisit later) and recast the Phase 1 framing to encourage outward-looking research into the wider agentic ecosystem, with only a light Cloud Foundry lens per note. Repoint the former 'complete example' links at TEMPLATE.md and refresh the schema example to an outward-looking topic. Signed-off-by: rkoster --- CONTRIBUTING.md | 4 +-- IDEATION.md | 39 +++++++++++++------- README.md | 5 +-- research/README.md | 17 ++++----- research/TEMPLATE.md | 2 +- research/cf-runtime-gaps.md | 72 ------------------------------------- 6 files changed, 41 insertions(+), 98 deletions(-) delete mode 100644 research/cf-runtime-gaps.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3db86bc..425f4f6 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -14,8 +14,8 @@ For the why and the bigger picture, read [`IDEATION.md`](./IDEATION.md). ```bash cp research/TEMPLATE.md research/my-topic.md ``` -3. **Fill it in.** Keep it short and sourced. See - [`research/cf-runtime-gaps.md`](./research/cf-runtime-gaps.md) for a complete example and +3. **Fill it in.** Keep it short, sourced, and outward-looking (see + [`IDEATION.md`](./IDEATION.md) for what Phase 1 is after). See [`research/README.md`](./research/README.md) for the frontmatter schema. 4. **Commit your note:** ```bash diff --git a/IDEATION.md b/IDEATION.md index b69be3d..81713a4 100644 --- a/IDEATION.md +++ b/IDEATION.md @@ -8,8 +8,9 @@ The Agentic Runtime Working Group is new, and the design space — running AI agents and LLM-powered workloads as first-class citizens on Cloud Foundry — is broad and moving fast. Before committing to specific designs or RFCs, we want to map the landscape together: -gather what the community already knows, surface prior art, and identify where Cloud -Foundry's primitives help or fall short. +gather what the community already knows and surface prior art from the wider ecosystem. +With that map in hand, the workshop can then see where Cloud Foundry's primitives help or +fall short. This repository is the home for that research. It is deliberately **lightweight and open**: the goal is breadth of input from anyone interested, not polished deliverables. @@ -19,8 +20,9 @@ open**: the goal is breadth of input from anyone interested, not polished delive This research phase is step one of four: 1. **Research (now, ~a few weeks).** Contributors submit short, sourced **research notes** - into [`research/`](./research) via pull requests. We want broad coverage of the agentic - ecosystem, relevant technologies, prior art, and Cloud Foundry gaps. + into [`research/`](./research) via pull requests. We want broad, *outward-looking* + coverage of the wider agentic ecosystem — relevant technologies, prior art, and how + others solve these problems. Where Cloud Foundry fits comes later. 2. **Workshop.** The working group meets to read across the accumulated notes and cluster them into **themes**. Themes are *not* defined up front — they emerge from what people actually contribute. @@ -34,27 +36,38 @@ will be added once the workshop has shaped it. ## What to contribute in Phase 1 +**Look outward.** Phase 1 is about understanding the wider agentic and AI ecosystem — not +about cataloguing Cloud Foundry. Where Cloud Foundry's primitives help or fall short is +something we want to *discover* at the workshop, drawn from this research, rather than +assume up front. + **In scope** — research notes that inform the design space, such as: - Analyses of agent frameworks, protocols, and platforms (how others solve a problem). -- Prior art and standards (e.g. identity, sandboxing, observability conventions). -- Cloud Foundry gaps and friction points for agentic workloads. +- Prior art and standards — identity, sandboxing, observability, orchestration conventions. +- How adjacent runtimes and platforms (Kubernetes, serverless, other PaaS) handle agentic + workloads. - Surveys of the surrounding ecosystem and where it's heading. -**Out of scope for now** — finished solutions, designs, or RFCs. Those come in Phase 4, -after the workshop. A note may *raise* questions and point at possible directions, but its -job is to inform, not to settle on a final answer. +**Out of scope for now:** + +- Finished solutions, designs, or RFCs — those come in Phase 4, after the workshop. A note + may *raise* questions and point at possible directions, but its job is to inform, not to + settle on a final answer. +- Definitive Cloud Foundry gap lists. Identifying gaps is an **outcome** of this phase, + synthesized at the workshop from the body of research — not a starting point any one + contributor supplies. ## What makes a good research note - **Sourced.** Link to the primary material so others can dig in. - **Summarized.** A few sentences capturing the essence — assume the reader is busy. -- **Connected to CF.** Say how it relates to Cloud Foundry primitives or gaps, even if the - connection is "this doesn't map cleanly, and here's why." +- **Outward-looking, with a light CF lens.** The substance is the external research; add a + short note on why it might matter for Cloud Foundry. A loose or speculative connection is + fine — "not sure how this maps yet" is a perfectly good answer. - **Honest about open questions.** Unknowns are valuable signal for the workshop. -Each note follows a small template — see [`research/TEMPLATE.md`](./research/TEMPLATE.md) -and the worked example [`research/cf-runtime-gaps.md`](./research/cf-runtime-gaps.md). +Each note follows a small template — see [`research/TEMPLATE.md`](./research/TEMPLATE.md). [`CONTRIBUTING.md`](./CONTRIBUTING.md) explains the mechanics. ## Tagging: how themes will emerge diff --git a/README.md b/README.md index 5491d1b..0da8b27 100644 --- a/README.md +++ b/README.md @@ -32,8 +32,9 @@ See [`IDEATION.md`](./IDEATION.md) for the full brief. ## How to contribute Read [`CONTRIBUTING.md`](./CONTRIBUTING.md), copy [`research/TEMPLATE.md`](./research/TEMPLATE.md), -fill it in, and open a pull request. See [`research/cf-runtime-gaps.md`](./research/cf-runtime-gaps.md) -for a complete example. +fill it in, and open a pull request. In this phase we're especially interested in research +that looks **outward** at the wider agentic ecosystem — see [`IDEATION.md`](./IDEATION.md) +for scope. ## Community diff --git a/research/README.md b/research/README.md index 7fea1bc..d2ad43c 100644 --- a/research/README.md +++ b/research/README.md @@ -11,8 +11,7 @@ would pre-impose the very themes we want to let emerge. ## Adding a note Copy [`TEMPLATE.md`](./TEMPLATE.md), rename it to a kebab-case topic (`my-topic.md`), and -fill it in. See [`cf-runtime-gaps.md`](./cf-runtime-gaps.md) for a complete example, and -[`../CONTRIBUTING.md`](../CONTRIBUTING.md) for the full workflow. +fill it in. See [`../CONTRIBUTING.md`](../CONTRIBUTING.md) for the full workflow. ## Frontmatter schema @@ -20,11 +19,11 @@ Each note begins with a YAML frontmatter block: ```yaml --- -title: Cloud Foundry gaps for AI agents -author: Ruben Koster (@rkoster) +title: How LangGraph models multi-agent orchestration +author: Jane Doe (@janedoe) date: 2026-06-25 -tags: [ecosystem-survey, autoscaling, identity] -cf_areas: [diego, capi, uaa, loggregator] +tags: [orchestration, inter-agent-comms, ecosystem-survey] +cf_areas: [diego, capi] status: draft sources: - https://example.com/source-one @@ -56,8 +55,10 @@ Two to four sentences capturing the essence. ## CF relevance -How this maps to Cloud Foundry primitives or gaps — including "it doesn't map cleanly, and -here's why." +A short, light-touch note on why this might matter for Cloud Foundry. A loose or +speculative connection is fine — including "not sure how this maps yet." Synthesizing the +research into concrete Cloud Foundry gaps is the workshop's job, not something each note +has to settle. ## Open questions diff --git a/research/TEMPLATE.md b/research/TEMPLATE.md index 36db377..3b457b9 100644 --- a/research/TEMPLATE.md +++ b/research/TEMPLATE.md @@ -26,7 +26,7 @@ sources: ## CF relevance - + ## Open questions diff --git a/research/cf-runtime-gaps.md b/research/cf-runtime-gaps.md deleted file mode 100644 index 38f1861..0000000 --- a/research/cf-runtime-gaps.md +++ /dev/null @@ -1,72 +0,0 @@ ---- -title: Cloud Foundry gaps and friction points for AI agents -author: Ruben Koster (@rkoster) -date: 2026-06-25 -tags: [ecosystem-survey, autoscaling, identity, sandboxing-isolation, inter-agent-comms, observability-governance, runtime-lifecycle] -cf_areas: [diego, capi, uaa, loggregator, routing, buildpacks] -status: draft -sources: - - https://github.com/cloudfoundry/community/blob/main/toc/working-groups/agentic-runtime.md ---- - -> **This is the worked example note.** It shows the expected format and depth. Use it as a -> reference when writing your own — see [`../CONTRIBUTING.md`](../CONTRIBUTING.md). - -## Summary - -Cloud Foundry's runtime, routing, autoscaling, and observability stack is heavily optimized -for stateless HTTP applications. AI agents and LLM-powered workloads stress a different set -of assumptions — background workers, session state, per-agent identity, non-HTTP protocols, -and bursty scale-to-zero demand. This note catalogs seven gaps where CF's current -primitives create friction for agentic workloads, as a starting map for the research phase. - -## Key findings - -- **Async worker observability.** CF's observability, routing, and autoscaling are - HTTP-biased. Frameworks like CrewAI and AutoGen rely on background worker queues (e.g. - Celery) because of web-request timeouts, and CF has no native queue-depth autoscaling - (compared with Kubernetes KEDA). -- **Session-stateful workloads.** CF apps are stateless by default. There is no native - session persistence with auto-resume (unlike Azure's per-session VM sandboxes); state - must be externalized to bound services, which works but isn't integrated. -- **Agent identity model.** CF identity is app-centric (manifest `name`, service bindings), - with no per-agent identities, no agent-to-agent authentication, and no native agent - discovery. -- **Protocol diversity.** Agents use A2A, AG-UI (bidirectional streaming), MCP, webhooks, - and custom streaming protocols. CF routing is HTTP-centric; WebSockets/SSE are supported - but there's no abstraction for non-HTTP agent protocols. -- **Buildpack ecosystem.** No AI/agent-specific buildpacks exist — no standard packaging - for LangGraph/CrewAI/LlamaIndex, no OTel GenAI auto-instrumentation, no agent entrypoint - convention. -- **Scaling model.** CF's min/max-instance model doesn't match bursty agent demand; there's - no scale-to-zero with warm resume (Azure's per-session model) versus CF's per-replica - scaling. -- **Tool access & MCP integration.** Agents need to discover and call tools (databases, - APIs, MCP servers), but CF's service-binding model targets services, not tools, and MCP - servers must be deployed as apps with manual routing. - -| Gap | CF current state | What's needed | -|-----|------------------|---------------| -| Async worker observability | HTTP-biased | Queue-depth autoscaling, worker metrics | -| Session state | Stateless apps | Session persistence with auto-resume | -| Agent identity | App-centric | Per-agent identities, agent discovery | -| Protocol diversity | HTTP-centric | A2A, AG-UI, MCP routing | -| Buildpacks | No AI buildpacks | Agent framework buildpacks, OTel auto-instrumentation | -| Scaling | Per-replica | Per-session scaling, scale-to-zero with warm resume | -| Tool access | Service bindings | Tool discovery, MCP integration | - -## CF relevance - -Each gap points at a CF component that may need to evolve for agentic workloads: Diego and -CAPI for lifecycle/scaling and sandboxing, UAA for agent identity, Loggregator and OTel -conventions for observability, the routing tier for non-HTTP protocols, and the buildpack -ecosystem for packaging and instrumentation. Several gaps overlap (identity underpins both -agent-to-agent comms and tool access), which makes them good candidates for theme -clustering at the workshop. - -## Open questions - -- Which gaps are most urgent for real agent workloads people are trying to run on CF today? -- Where should a gap be closed by CF platform changes versus solved with buildpacks, - services, or conventions on top of existing primitives? -- Which gaps are interdependent enough to belong to a single theme/POC track? From 0dfab68af6c6f2545fab65f34b923e87bc0b9235 Mon Sep 17 00:00:00 2001 From: Ruben Koster Date: Fri, 26 Jun 2026 08:46:25 +0200 Subject: [PATCH 13/15] Update .github/PULL_REQUEST_TEMPLATE.md Co-authored-by: Beyhan Veli --- .github/PULL_REQUEST_TEMPLATE.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index e363c0c..52486ef 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -12,6 +12,4 @@ - [ ] It has the four sections: Summary, Key findings, CF relevance, Open questions. - [ ] I added relevant `tags` (see the suggested vocabulary in `IDEATION.md`). - [ ] Sources are linked. -- [ ] It's on-topic for agentic workloads on Cloud Foundry and not a duplicate of an - existing note. -- [ ] I've signed the Cloud Foundry CLA (the EasyCLA bot prompts you on your first PR). +- [ ] It's on-topic for agentic workloads on Cloud Foundry From 3829430715a8c6aa4cca7634527ef36986079d25 Mon Sep 17 00:00:00 2001 From: rkoster Date: Wed, 1 Jul 2026 14:11:01 +0200 Subject: [PATCH 14/15] Add an ideas/ lane as a low-barrier front of the funnel MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A full research note asks for sourcing and structure, which risks turning away contributors who have a spark but no time to write it up — or getting their PR rejected for not being a research note. Give ideas their own home so nothing gets lost at the top of the funnel. Add ideas/ with a README and a minimal TEMPLATE (a title is the only hard requirement). Extend validate_notes.py with a light validate_idea() that checks just the kebab-case filename and that a title is present, and widen the lint workflow to cover ideas/**. Reframe the docs around two lanes and a simple ideas -> research -> proposals pipeline, and cross-link the two so an idea can graduate into a sourced note. Signed-off-by: rkoster --- .github/scripts/validate_notes.py | 58 ++++++++++++++++++++++++++++--- .github/workflows/lint.yml | 6 ++-- CONTRIBUTING.md | 26 ++++++++++---- IDEATION.md | 17 ++++++--- README.md | 30 ++++++++++------ ideas/README.md | 29 ++++++++++++++++ ideas/TEMPLATE.md | 28 +++++++++++++++ research/README.md | 3 ++ 8 files changed, 168 insertions(+), 29 deletions(-) create mode 100644 ideas/README.md create mode 100644 ideas/TEMPLATE.md diff --git a/.github/scripts/validate_notes.py b/.github/scripts/validate_notes.py index b8941da..107abcf 100644 --- a/.github/scripts/validate_notes.py +++ b/.github/scripts/validate_notes.py @@ -1,5 +1,5 @@ #!/usr/bin/env python3 -"""Validate research notes in research/. +"""Validate research notes in research/ and ideas in ideas/. For every research/*.md file except README.md and TEMPLATE.md this checks: - the filename is lowercase kebab-case ending in .md @@ -7,7 +7,12 @@ - required frontmatter keys are present and well-typed - the four required body section headings are present -Exits non-zero (printing every problem) if any note is invalid. +Ideas are deliberately low-barrier. For every ideas/*.md file except README.md and +TEMPLATE.md this checks only: + - the filename is lowercase kebab-case ending in .md + - a title is present (a YAML 'title:' or a '# ' heading) + +Exits non-zero (printing every problem) if any note or idea is invalid. """ from __future__ import annotations @@ -20,6 +25,7 @@ import yaml RESEARCH_DIR = pathlib.Path("research") +IDEAS_DIR = pathlib.Path("ideas") SKIP = {"README.md", "TEMPLATE.md"} REQUIRED_KEYS = { @@ -40,6 +46,7 @@ FILENAME_RE = re.compile(r"^[a-z0-9]+(-[a-z0-9]+)*\.md$") FRONTMATTER_RE = re.compile(r"^---\n(.*?)\n---\n", re.DOTALL) DATE_RE = re.compile(r"^\d{4}-\d{2}-\d{2}$") +H1_RE = re.compile(r"^#\s+\S", re.MULTILINE) def validate_file(path: pathlib.Path) -> list[str]: @@ -99,25 +106,66 @@ def validate_file(path: pathlib.Path) -> list[str]: return [f"{path}: {p}" for p in problems] +def validate_idea(path: pathlib.Path) -> list[str]: + """Light validation: kebab-case filename plus a title of some kind.""" + problems: list[str] = [] + name = path.name + + if not FILENAME_RE.match(name): + problems.append( + f"filename must be lowercase kebab-case ending in .md (got '{name}')" + ) + + text = path.read_text(encoding="utf-8") + + has_title = False + body = text + match = FRONTMATTER_RE.match(text) + if match: + body = text[match.end():] + try: + meta = yaml.safe_load(match.group(1)) + except yaml.YAMLError as exc: + problems.append(f"frontmatter is not valid YAML: {exc}") + else: + if isinstance(meta, dict) and str(meta.get("title") or "").strip(): + has_title = True + + if not has_title and not H1_RE.search(body): + problems.append("idea needs a title (a YAML 'title:' or a '# ' heading)") + + return [f"{path}: {p}" for p in problems] + + def main() -> int: if not RESEARCH_DIR.is_dir(): print(f"error: '{RESEARCH_DIR}/' directory not found", file=sys.stderr) return 1 notes = sorted(p for p in RESEARCH_DIR.glob("*.md") if p.name not in SKIP) + ideas = ( + sorted(p for p in IDEAS_DIR.glob("*.md") if p.name not in SKIP) + if IDEAS_DIR.is_dir() + else [] + ) problems: list[str] = [] for note in notes: problems.extend(validate_file(note)) + for idea in ideas: + problems.extend(validate_idea(idea)) if problems: - print("Research note validation failed:\n") + print("Validation failed:\n") for problem in problems: print(f" - {problem}") - print(f"\n{len(problems)} problem(s) across {len(notes)} note(s).") + print( + f"\n{len(problems)} problem(s) across " + f"{len(notes)} research note(s) and {len(ideas)} idea(s)." + ) return 1 - print(f"OK: {len(notes)} research note(s) valid.") + print(f"OK: {len(notes)} research note(s) and {len(ideas)} idea(s) valid.") return 0 diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml index 65e7e49..cd1790a 100644 --- a/.github/workflows/lint.yml +++ b/.github/workflows/lint.yml @@ -1,15 +1,17 @@ -name: Validate research notes +name: Validate notes and ideas on: pull_request: paths: - "research/**" + - "ideas/**" - ".github/scripts/validate_notes.py" - ".github/workflows/lint.yml" push: branches: [main] paths: - "research/**" + - "ideas/**" - ".github/scripts/validate_notes.py" - ".github/workflows/lint.yml" @@ -28,5 +30,5 @@ jobs: - name: Install dependencies run: pip install "pyyaml>=6" - - name: Validate research notes + - name: Validate notes and ideas run: python .github/scripts/validate_notes.py diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 425f4f6..961c308 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,12 +1,23 @@ # Contributing Thanks for helping shape the future of agentic workloads on Cloud Foundry. During the -current **research phase**, contributions take the form of **research notes** added to -[`research/`](./research) via pull requests. +current **research phase** there are two ways to contribute, both via pull request: + +- A quick **idea** in [`ideas/`](./ideas) — low bar, no sourcing required. A place for + sparks, so nothing gets turned away for not yet being a full research note. +- A sourced **research note** in [`research/`](./research) — structured and cited. + +Ideas can graduate into research notes; link the two when they do. For the why and the bigger picture, read [`IDEATION.md`](./IDEATION.md). -## Quick start +## Adding an idea + +Copy [`ideas/TEMPLATE.md`](./ideas/TEMPLATE.md) to `ideas/my-idea.md`, jot down the spark, +and open a PR. The only hard rules are a kebab-case filename and a title — everything else +is optional. See [`ideas/README.md`](./ideas/README.md). + +## Adding a research note 1. **Fork** this repository (or, if you're a working-group member with write access, create a branch). @@ -45,10 +56,11 @@ suggested (non-binding) vocabulary in Research notes are low-risk, so we optimize for throughput: -- CI validates frontmatter, filename, and required sections. -- Any working-group **tech lead** can merge once CI passes and the note is on-topic and not - a duplicate. -- Substantive review of *ideas* happens at the workshop, not as a merge gate. +- For research notes, CI validates frontmatter, filename, and required sections. For + [`ideas/`](./ideas) it only checks the filename and that a title is present. +- Any working-group **tech lead** can merge once CI passes and the contribution is on-topic. +- Substantive debate about the *merits* of a contribution happens at the workshop, not as a + merge gate. ## Contributor License Agreement (CLA) diff --git a/IDEATION.md b/IDEATION.md index 81713a4..43d04d5 100644 --- a/IDEATION.md +++ b/IDEATION.md @@ -19,10 +19,12 @@ open**: the goal is breadth of input from anyone interested, not polished delive This research phase is step one of four: -1. **Research (now, ~a few weeks).** Contributors submit short, sourced **research notes** - into [`research/`](./research) via pull requests. We want broad, *outward-looking* - coverage of the wider agentic ecosystem — relevant technologies, prior art, and how - others solve these problems. Where Cloud Foundry fits comes later. +1. **Capture & research (now, ~a few weeks).** Contributors open pull requests with either + a quick **idea** in [`ideas/`](./ideas) — a spark, question, or pointer, at a low bar — + or a short, sourced **research note** in [`research/`](./research). We want broad, + *outward-looking* coverage of the wider agentic ecosystem — relevant technologies, prior + art, and how others solve these problems. Where Cloud Foundry fits comes later, and ideas + can graduate into research notes as they firm up. 2. **Workshop.** The working group meets to read across the accumulated notes and cluster them into **themes**. Themes are *not* defined up front — they emerge from what people actually contribute. @@ -41,6 +43,11 @@ about cataloguing Cloud Foundry. Where Cloud Foundry's primitives help or fall s something we want to *discover* at the workshop, drawn from this research, rather than assume up front. +**Two ways in.** Not everything needs to be a polished note. If you have a spark but no +time to write it up, drop it in [`ideas/`](./ideas) — we'd rather capture it than turn it +away for not being a full research note. A sourced, structured write-up belongs in +[`research/`](./research). The scope below applies to both. + **In scope** — research notes that inform the design space, such as: - Analyses of agent frameworks, protocols, and platforms (how others solve a problem). @@ -101,7 +108,7 @@ window to run a few weeks. ## How to participate 1. Read [`CONTRIBUTING.md`](./CONTRIBUTING.md). -2. Add a note using the template and open a PR. +2. Add an idea or a research note using the matching template, and open a PR. 3. Join the conversation in [#ai-wg](https://cloudfoundry.slack.com/archives/C0B214KJ1HA). ## Feedback on this process diff --git a/README.md b/README.md index 0da8b27..a6f1928 100644 --- a/README.md +++ b/README.md @@ -15,15 +15,19 @@ same platform-native primitives developers and operators rely on today. ## What this repo is for This repo bootstraps a **crowd-sourced, distributed research phase**. Anyone interested in -the future of agentic workloads on Cloud Foundry is invited to contribute **research -notes** as pull requests. The accumulated notes become the raw material for a -working-group workshop that identifies themes and spins up focused proof-of-concept and -RFC work. +the future of agentic workloads on Cloud Foundry is invited to contribute — either a quick +**idea** in [`ideas/`](./ideas) or a sourced **research note** in [`research/`](./research), +both as pull requests. The accumulated material becomes the raw input for a working-group +workshop that identifies themes and spins up focused proof-of-concept and RFC work. ## The roadmap -1. **Research (now)** — contributors submit research notes via PRs into [`research/`](./research). -2. **Workshop** — the working group clusters the notes into emergent themes. +Contributions flow along a simple pipeline — raw **ideas** grow into sourced **research**, +which later feeds **proposals**: + +1. **Capture & research (now)** — drop a spark in [`ideas/`](./ideas) or a sourced note in + [`research/`](./research), via PRs. +2. **Workshop** — the working group clusters the material into emergent themes. 3. **Match** — members align their interests to themes. 4. **POC / RFC** — per-theme tracks produce proofs-of-concept and Cloud Foundry RFCs. @@ -31,10 +35,16 @@ See [`IDEATION.md`](./IDEATION.md) for the full brief. ## How to contribute -Read [`CONTRIBUTING.md`](./CONTRIBUTING.md), copy [`research/TEMPLATE.md`](./research/TEMPLATE.md), -fill it in, and open a pull request. In this phase we're especially interested in research -that looks **outward** at the wider agentic ecosystem — see [`IDEATION.md`](./IDEATION.md) -for scope. +Two ways in, both via pull request: + +- **Have a quick idea?** Drop a short note in [`ideas/`](./ideas) — low bar, no sourcing + required. We'd rather capture it than turn it away for not being a full research note. +- **Ready to write it up?** Copy [`research/TEMPLATE.md`](./research/TEMPLATE.md), fill it + in, and add it to [`research/`](./research). + +Read [`CONTRIBUTING.md`](./CONTRIBUTING.md) for the workflow. In this phase we're especially +interested in research that looks **outward** at the wider agentic ecosystem — see +[`IDEATION.md`](./IDEATION.md) for scope. ## Community diff --git a/ideas/README.md b/ideas/README.md new file mode 100644 index 0000000..fdf076e --- /dev/null +++ b/ideas/README.md @@ -0,0 +1,29 @@ +# Ideas + +A low-barrier place for **sparks** — a question, a hunch, a link you haven't written up, +or a "someone should look into this." If it isn't ready to be a full +[research note](../research), it belongs here. We'd rather capture an idea than turn it +away for not being polished. + +Ideas are the front of the funnel: a good one can grow into a sourced research note, and +from there feed the workshop. + +## What belongs here + +- A topic worth researching, with a sentence on why. +- An open question about agentic workloads, runtimes, or the surrounding ecosystem. +- A pointer to something interesting — a project, paper, or protocol — you haven't + summarized yet. + +Anything more developed — sourced and structured — is a [research note](../research) +instead. Not sure which it is? Start here; it can graduate later. + +## Adding an idea + +Copy [`TEMPLATE.md`](./TEMPLATE.md) to a kebab-case filename (`my-idea.md`) and jot it +down. The only hard rules are a **kebab-case filename** and a **title** (a YAML `title:` +or a `# ` heading) — everything else is optional. Tags help the workshop cluster ideas, +so add them if you can. + +If your idea grows into — or came from — a research note, link the two under **Related** +so others can follow the trail. diff --git a/ideas/TEMPLATE.md b/ideas/TEMPLATE.md new file mode 100644 index 0000000..b5140f0 --- /dev/null +++ b/ideas/TEMPLATE.md @@ -0,0 +1,28 @@ +--- +title: +author: (@your-github-handle) +date: 2026-01-01 +tags: [] +--- + + + +## The idea + + + +## Why it might matter + + + +## What to research next + + + +## Related + + diff --git a/research/README.md b/research/README.md index d2ad43c..81cbdd5 100644 --- a/research/README.md +++ b/research/README.md @@ -13,6 +13,9 @@ would pre-impose the very themes we want to let emerge. Copy [`TEMPLATE.md`](./TEMPLATE.md), rename it to a kebab-case topic (`my-topic.md`), and fill it in. See [`../CONTRIBUTING.md`](../CONTRIBUTING.md) for the full workflow. +Not ready for a sourced write-up? Drop a spark in [`../ideas/`](../ideas) instead — it can +graduate into a research note later. + ## Frontmatter schema Each note begins with a YAML frontmatter block: From a2203e1394dac8e676195a7718f055291a3b093c Mon Sep 17 00:00:00 2001 From: rkoster Date: Wed, 1 Jul 2026 14:34:37 +0200 Subject: [PATCH 15/15] Frame ideas and research as linked lanes, not a linear pipeline MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Per review discussion, research is a reusable layer rather than a stage an idea passes through: a single research note can back several ideas, and it's the idea — once it has enough research behind it — that grows into a proposal. Adjust the README, CONTRIBUTING, IDEATION, and ideas/README wording to match, replacing the "ideas grow into research which feeds proposals" conveyor-belt framing with two linked lanes plus a many-to-one ideas/research relationship. Signed-off-by: rkoster --- CONTRIBUTING.md | 4 +++- IDEATION.md | 5 +++-- README.md | 5 +++-- ideas/README.md | 9 +++++---- 4 files changed, 14 insertions(+), 9 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 961c308..7a17abb 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -7,7 +7,9 @@ current **research phase** there are two ways to contribute, both via pull reque sparks, so nothing gets turned away for not yet being a full research note. - A sourced **research note** in [`research/`](./research) — structured and cited. -Ideas can graduate into research notes; link the two when they do. +Ideas and research link together: an idea points to the research that backs it, and one +research note can back several ideas. An idea with enough research behind it can later become +a proposal. For the why and the bigger picture, read [`IDEATION.md`](./IDEATION.md). diff --git a/IDEATION.md b/IDEATION.md index 43d04d5..9729b0e 100644 --- a/IDEATION.md +++ b/IDEATION.md @@ -23,8 +23,9 @@ This research phase is step one of four: a quick **idea** in [`ideas/`](./ideas) — a spark, question, or pointer, at a low bar — or a short, sourced **research note** in [`research/`](./research). We want broad, *outward-looking* coverage of the wider agentic ecosystem — relevant technologies, prior - art, and how others solve these problems. Where Cloud Foundry fits comes later, and ideas - can graduate into research notes as they firm up. + art, and how others solve these problems. Where Cloud Foundry fits comes later. Ideas and + research link together — one research note can back several ideas — and an idea with enough + research behind it can grow into a proposal. 2. **Workshop.** The working group meets to read across the accumulated notes and cluster them into **themes**. Themes are *not* defined up front — they emerge from what people actually contribute. diff --git a/README.md b/README.md index a6f1928..16619e8 100644 --- a/README.md +++ b/README.md @@ -22,8 +22,9 @@ workshop that identifies themes and spins up focused proof-of-concept and RFC wo ## The roadmap -Contributions flow along a simple pipeline — raw **ideas** grow into sourced **research**, -which later feeds **proposals**: +Contributions come in two linked lanes — raw **ideas** and the sourced **research** that +backs them. Research is reusable, so one note can support several ideas, and an idea with +enough research behind it can grow into a **proposal** later on: 1. **Capture & research (now)** — drop a spark in [`ideas/`](./ideas) or a sourced note in [`research/`](./research), via PRs. diff --git a/ideas/README.md b/ideas/README.md index fdf076e..212fec7 100644 --- a/ideas/README.md +++ b/ideas/README.md @@ -5,8 +5,8 @@ or a "someone should look into this." If it isn't ready to be a full [research note](../research), it belongs here. We'd rather capture an idea than turn it away for not being polished. -Ideas are the front of the funnel: a good one can grow into a sourced research note, and -from there feed the workshop. +Ideas are the front of the funnel. As an idea gathers supporting research it firms up and +feeds the workshop — and an idea with enough research behind it can grow into a proposal. ## What belongs here @@ -25,5 +25,6 @@ down. The only hard rules are a **kebab-case filename** and a **title** (a YAML or a `# ` heading) — everything else is optional. Tags help the workshop cluster ideas, so add them if you can. -If your idea grows into — or came from — a research note, link the two under **Related** -so others can follow the trail. +Link the research that backs your idea under **Related** so others can follow the trail. The +same research note can back more than one idea, so link it even if it already appears +elsewhere.