Merge pull request #43 from computerlovetech/claude/ralph-loops-format-hPdcv

Author: kasperjunge

ralphloops/README.md

@@ -0,0 +1,72 @@
+# `ralphloops/` — staging area for ralphloops.io and ralphloops/ralphloops
+
+This directory is a **staging area** for the Ralph Loops project. It
+contains two things that will eventually move to their own homes:
+
+- **[`website/`](website/)** — the static site for
+  [ralphloops.io](https://ralphloops.io/). Minimal, technical,
+  inspired by [agentskills.io](https://agentskills.io/).
+- **[`repo/`](repo/)** — the contents of the future
+  `ralphloops/ralphloops` GitHub repository: specification, creator
+  docs, implementor docs, example loop packages, JSON Schema,
+  conformance fixtures, RFCs, and governance.
+
+## Why it lives here for now
+
+The `ralphloops` GitHub organization and repo do not exist yet. This
+subdirectory lets us develop the format, the spec, and the site
+alongside Ralphify (one reference implementation) until we're ready
+to move it out.
+
+When the `ralphloops` org is created:
+
+1. Copy `ralphloops/repo/` into the new `ralphloops/ralphloops` repo.
+2. Deploy `ralphloops/website/` to the ralphloops.io domain.
+3. Remove this staging directory from the Ralphify repo.
+
+## Positioning
+
+Ralph Loops is positioned everywhere as:
+
+> **An open proposed format for portable Ralph-style agent loops.**
+
+- It is **not** a standard.
+- It is **not** a Ralphify feature.
+- It is **inspired by** Geoffrey Huntley's Ralph loop methodology and
+  does not claim ownership of that methodology.
+- Ralphify is **one reference runtime** for the format, not the
+  format itself.
+
+## Layout
+
+```
+ralphloops/
+├── README.md              # this file
+├── website/               # ralphloops.io static site
+│   ├── index.html
+│   ├── styles.css
+│   ├── specification/
+│   ├── loop-creation/
+│   │   ├── quickstart/
+│   │   └── best-practices/
+│   ├── implementors/
+│   │   ├── overview/
+│   │   └── reference/
+│   ├── examples/
+│   └── governance/
+└── repo/                  # ralphloops/ralphloops repo contents
+    ├── README.md
+    ├── LICENSE
+    ├── CONTRIBUTING.md
+    ├── CODE_OF_CONDUCT.md
+    ├── GOVERNANCE.md
+    ├── VERSIONING.md
+    ├── specification/
+    ├── loop-creation/
+    ├── implementors/
+    ├── examples/          # six reference loop packages
+    ├── schemas/
+    ├── tests/             # conformance corpus
+    ├── rfcs/
+    └── .github/
+```

ralphloops/repo/.github/ISSUE_TEMPLATE/bug-in-fixture-or-example.md

@@ -0,0 +1,23 @@
+---
+name: Bug in a fixture or example
+about: Report a problem with a conformance fixture or example loop
+title: "[bug] "
+labels: ["bug", "examples"]
+---
+
+## Where
+
+<!-- Path to the fixture or example (e.g. tests/valid/full/ or
+     examples/fix-failing-tests/). -->
+
+## What's wrong
+
+<!-- What did you expect? What did you see? -->
+
+## How to reproduce
+
+<!-- Steps, runtime used, commands run. -->
+
+## Suggested fix
+
+<!-- Optional — what change would resolve the issue? -->

ralphloops/repo/.github/ISSUE_TEMPLATE/rfc-proposal.md

@@ -0,0 +1,39 @@
+---
+name: RFC proposal
+about: Propose a non-trivial change to the Ralph Loops format
+title: "[rfc] "
+labels: ["rfc"]
+---
+
+## Summary
+
+<!-- One paragraph describing the proposed change. -->
+
+## Motivation
+
+<!-- Why is this change needed? What problem does it solve? -->
+
+## Proposal
+
+<!-- What specifically would change? Metadata, path rules, runtime
+     contract, compatibility classes, etc. -->
+
+## Impact
+
+- **Breaking?** <!-- yes/no -->
+- **Target version:** <!-- e.g. 0.2 -->
+- **Affected documents:** <!-- specification/... -->
+
+## Alternatives considered
+
+<!-- What else did you look at? Why this one? -->
+
+## Unresolved questions
+
+<!-- Anything you haven't worked out yet. -->
+
+---
+
+If this is accepted for further discussion, a maintainer will ask you
+to write it up as a file under `rfcs/` using the template at
+`rfcs/0001-format-principles.md`.

ralphloops/repo/.github/ISSUE_TEMPLATE/spec-clarification.md

@@ -0,0 +1,22 @@
+---
+name: Spec clarification
+about: The specification is ambiguous or unclear
+title: "[clarify] "
+labels: ["spec", "clarification"]
+---
+
+## Which part of the spec?
+
+<!-- Link to the file and section in specification/ -->
+
+## What is ambiguous?
+
+<!-- Describe what you read and what you couldn't decide. -->
+
+## What interpretations are possible?
+
+<!-- List the plausible readings. -->
+
+## Why it matters
+
+<!-- What decision depends on resolving this? -->

ralphloops/repo/CODE_OF_CONDUCT.md

@@ -0,0 +1,32 @@
+# Code of Conduct
+
+Ralph Loops follows the
+[Contributor Covenant v2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/).
+
+## Our pledge
+
+We as members, contributors, and maintainers pledge to make participation in
+our community a harassment-free experience for everyone, regardless of age,
+body size, visible or invisible disability, ethnicity, sex characteristics,
+gender identity and expression, level of experience, education, socio-economic
+status, nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies
+when an individual is officially representing the community in public spaces.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the maintainers listed in [`GOVERNANCE.md`](GOVERNANCE.md). All
+complaints will be reviewed and investigated promptly and fairly.
+
+## Attribution
+
+This Code of Conduct is adapted from the
+[Contributor Covenant](https://www.contributor-covenant.org), version 2.1.

ralphloops/repo/CONTRIBUTING.md

@@ -0,0 +1,69 @@
+# Contributing to Ralph Loops
+
+Thanks for helping shape Ralph Loops. This repository is the canonical source
+for the Ralph Loops format: its specification, examples, conformance tests,
+and governance.
+
+## What lives here
+
+- **`specification/`** — the normative format spec
+- **`loop-creation/`** — creator-facing docs
+- **`implementors/`** — runtime-author docs
+- **`examples/`** — reference loop packages
+- **`schemas/`** — JSON Schema for frontmatter metadata
+- **`tests/`** — valid/invalid conformance fixtures
+- **`rfcs/`** — RFCs for non-trivial changes
+
+Code for specific runtimes (e.g. Ralphify) does **not** live here.
+
+## Kinds of contributions we welcome
+
+- Typo, clarity, and wording fixes in the spec and docs
+- New conformance fixtures under `tests/valid/` and `tests/invalid/`
+- New example loops under `examples/`
+- RFCs proposing additions or changes to the format
+- Translations and accessibility improvements to docs
+
+## Discussion first, PR second
+
+For anything beyond a typo or a small clarification, please open an issue or
+a discussion first. This is especially true for spec changes. We prefer
+small, well-scoped PRs over large, speculative ones.
+
+## Spec changes require an RFC
+
+Any change that affects what a Ralph Loop *is* — required fields, path
+resolution rules, compatibility classes, runtime contract, etc. — must go
+through the RFC process under `rfcs/`. Use `rfcs/0001-format-principles.md`
+as a template.
+
+Additive, backwards-compatible clarifications to existing fields may be
+landed directly as a PR against `specification/`.
+
+## Adding an example loop
+
+Each example under `examples/` must include:
+
+1. A `RALPH.md` with complete, valid frontmatter
+2. A short `README.md` explaining what the loop is for
+3. At least one bundled supporting file (script, doc, template, or fixture)
+4. Realistic exit conditions and validation steps
+
+Prefer outcome-oriented names (`fix-failing-tests`, not `my-loop-1`).
+
+## Adding conformance fixtures
+
+- Valid fixtures go under `tests/valid/<name>/`.
+- Invalid fixtures go under `tests/invalid/<name>/` with a short
+  `REASON.md` file explaining why the fixture is invalid.
+
+## Style
+
+- Prose: plain English, short sentences, no hype language.
+- Normative keywords (MUST, SHOULD, MAY) follow RFC 2119 semantics.
+- Code fences should declare a language where applicable.
+
+## Code of conduct
+
+Participation in this project is governed by our
+[Code of Conduct](CODE_OF_CONDUCT.md).

ralphloops/repo/GOVERNANCE.md

@@ -0,0 +1,64 @@
+# Governance
+
+Ralph Loops is an **open proposed format** for portable Ralph-style agent
+loops. This document describes how the format is stewarded and evolved.
+
+## Status
+
+The current format version is `0.1`. All `0.x` versions are draft and
+subject to change. A stable `1.x` line will be cut once the format has
+proven itself across multiple runtimes and loop packages in the wild.
+
+## Non-ownership of Ralph methodology
+
+Ralph Loops is a community-oriented format proposal **inspired by**
+[Geoffrey Huntley's Ralph loop methodology](https://ghuntley.com/ralph/).
+This repository defines the package format. It does **not** define, own,
+or gate the broader Ralph methodology itself.
+
+## Maintainers
+
+The format is maintained by a small group of stewards who land PRs, review
+RFCs, and cut spec releases. Current maintainers are listed in the
+repository `MAINTAINERS` file. Additional maintainers are added by
+consensus of existing maintainers based on sustained, thoughtful
+contribution.
+
+## Decision making
+
+- **Typos, clarifications, small doc fixes.** Any maintainer may merge
+  after a brief review.
+- **Additive, backwards-compatible spec changes.** Require review from at
+  least one other maintainer and an open discussion thread.
+- **Breaking changes.** Require an accepted RFC under `rfcs/` and
+  consensus among active maintainers.
+
+We prefer rough consensus over formal voting. If consensus cannot be
+reached, the maintainers may choose to defer the decision rather than
+force it through.
+
+## RFC process
+
+1. Open a discussion or issue describing the problem and the proposed change.
+2. If the change is non-trivial, draft an RFC under `rfcs/` using the
+   template in `rfcs/0001-format-principles.md`.
+3. Maintainers and community members review and comment.
+4. The RFC author revises in response to feedback.
+5. A maintainer either accepts, rejects, or defers the RFC.
+6. Accepted RFCs ship in a future `ralphloops_version` release, referenced
+   from `specification/changelog.md`.
+
+## Stewardship principles
+
+- Keep the format small.
+- Prefer portability over runtime-specific convenience.
+- Prefer human-readability over machine-centric schemas.
+- Do not claim ownership of the broader Ralph methodology.
+- Do not favor any single runtime in normative text.
+- Ship breaking changes through RFCs, not surprises.
+
+## Relationship to runtimes
+
+Runtimes like [Ralphify](https://ralphify.co/) are welcome to ship features
+that go beyond the format, but the format itself stays neutral. Runtime-
+specific behavior belongs in runtime documentation, not in the spec.

ralphloops/repo/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ralph Loops contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.