This repo is a practical engineering reference, not a hype collection. We welcome patterns, stories, tool mappings, and honest failure reports.
| Contribution | Where |
|---|---|
| New loop pattern | patterns/ + patterns/registry.yaml |
| Production story | stories/ |
| Tool example | examples/{grok,claude-code,codex,openclaw,opencode,github-actions}/ |
| Skill template | templates/ |
| Starter kit | starters/ |
| Doc improvement | docs/ |
Start small — every merged PR counts.
| Step | Time | What to contribute |
|---|---|---|
| 1 | ~15 min | Typo fix, adopters row, primitives-matrix row, or examples/README.md link |
| 2 | ~1 hr | Production story in stories/ or tool example in examples/{tool}/ |
| 3 | Half day | New starter, skill template, or MCP cookbook entry |
| 4 | Full day | Full pattern in patterns/ + patterns/registry.yaml entry |
Fastest paths: Add your project to adopters · Share a story issue · good first issue backlog
Every new pattern must include all sections from templates/pattern-template.md:
- Goal (one sentence)
- Scheduling (per-tool commands)
- Required skills
- State schema (with example)
- Typical cycle (numbered steps)
- Verification strategy (maker/checker)
- Human handoff points
- Tool-specific notes (at least 2 tools)
- Failure modes table
- Success metrics
Also add an entry to patterns/registry.yaml.
- Real experience (anonymize if needed)
- Name the pattern used
- Include at least one failure or surprise
- Actionable lesson in one paragraph
- Links work from README or relevant index
- No secrets, tokens, or internal URLs
-
STATE.mdexamples use.examplesuffix (gitignored live state) - Safety-sensitive patterns reference docs/safety.md
- Engineering over hype
- Failures are first-class content
- Tool-agnostic by default; tool-specific in labeled sections
PRs that only touch stories/, docs/adopters.md, or the Add Adopter template get same-day review when possible:
- Maintainer merges or requests one small fix within 24 hours
- Public thank-you on the PR or issue (
@mentionthe contributor) - Optional follow-up issue if the contributor wants a second PR (e.g. expand story → pattern example)
Automation posts a welcome comment on new story/adopter PRs (see .github/workflows/welcome-contributors.yml).
- Questions: GitHub Discussions (preferred) or issue with label
question - Show your loop: Add Adopter issue, Discussions, or a row in docs/adopters.md
- Loop Ready badge:
npx @cobusgreyling/loop-audit . --badge— paste into your README - Good first issues: look for label
good first issue - Security: see SECURITY.md — do not file public issues for exploitable vulnerabilities
Thank you for helping make this the go-to reference for loop engineering.