Contributing to Loop Engineering

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.

Ways to Contribute

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/

Contribution Ladder

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

Pattern Requirements

Every new pattern must include all sections from templates/pattern-template.md:

1. Goal (one sentence)
2. Scheduling (per-tool commands)
3. Required skills
4. State schema (with example)
5. Typical cycle (numbered steps)
6. Verification strategy (maker/checker)
7. Human handoff points
8. Tool-specific notes (at least 2 tools)
9. Failure modes table
10. Success metrics

Also add an entry to patterns/registry.yaml.

Story Requirements

• Real experience (anonymize if needed)
• Name the pattern used
• Include at least one failure or surprise
• Actionable lesson in one paragraph

Contributor paths (pick one)

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.

Development Setup (Path C)

npm ci   # at repo root – installs yaml/ajv for scripts/validate-registry.mjs
npm run validate:registry
npm run check:loop-init

Area owners

See docs/area-owners.md. Docs/examples/stories PRs are co-reviewed by @AIMindCrafter (CODEOWNERS).

Pull Request Checklist

• Links work from README or relevant index
• No secrets, tokens, or internal URLs
• STATE.md examples use .example suffix (gitignored live state)
• Safety-sensitive patterns reference docs/safety.md
• Windows setup adheres to docs/QUICKSTART.md § Windows / CRLF notes

Code of Conduct

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

Maintainer Response (Adopters & Stories)

PRs that only touch stories/, docs/adopters.md, or the Add Adopter template get same-day review when possible:

1. Maintainer merges or requests one small fix within 24 hours
2. Public thank-you on the PR or issue (@mention the contributor)
3. 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).

Community

• 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.