This repo is a practical engineering reference, not a hype collection. We welcome patterns, stories, tool mappings, and honest failure reports.
Maintainer response: docs, stories, adopters, and small tests get a first response within 48 hours (same-day when possible). Comment I'll take this on a good first issue to get assigned.
| 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: Help wanted (README) · Add Adopter · Share a story · open 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
| Path | When | Setup |
|---|---|---|
| A — Content | Stories, examples, adopters, most docs | No install — edit markdown, open PR |
| B — One package | Fix a single CLI under tools/<pkg> |
cd tools/<pkg> && npm ci && npm test |
| C — Full monorepo | Registry / cross-package scripts | Root npm ci then commands below |
Stories and adopters get same-day review when possible. Live backlog: good first issue.
npm ci # at repo root – installs yaml/ajv for scripts/validate-registry.mjs
npm run validate:registry
npm run check:loop-initSee docs/area-owners.md. Docs/examples/stories PRs are co-reviewed by @AIMindCrafter (CODEOWNERS).
- 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
- Windows setup adheres to docs/QUICKSTART.md § Windows / CRLF notes
This project follows the Code of Conduct (Contributor Covenant).
In short:
- Engineering over hype
- Failures are first-class content
- Tool-agnostic by default; tool-specific in labeled sections
- Harassment and bad-faith participation are not tolerated
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: Ask anything (preferred) or issue with label
question - Show your loop: Show your loop, Add Adopter issue, or a row in docs/adopters.md
- Loop Ready badge:
npx @cobusgreyling/loop-audit . --badge— paste into your README - Good first issues: curated list in README § Help wanted; filter:
good first issue - Hall of fame: CONTRIBUTORS.md — regenerate after merges with
npm run contributors:generate - 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.