Skip to content

Practical patterns, starters & CLI tools for loop engineering with AI coding agents. Design systems that prompt and orchestrate agents (inspired by Addy Osmani and Boris Cherny). Includes loop-audit, loop-init, loop-cost.

Add contributor onboarding quick wins (#124)

Cobus Greylingf18df044362a
diff --git a/.github/workflows/welcome-contributors.yml b/.github/workflows/welcome-contributors.yml
new file mode 100644
index 0000000..3f2d2ee
--- /dev/null
+++ b/.github/workflows/welcome-contributors.yml
@@ -0,0 +1,42 @@
+name: Welcome contributors
+
+on:
+ pull_request:
+ types: [opened]
+ paths:
+ - 'stories/**'
+ - 'docs/adopters.md'
+
+permissions:
+ pull-requests: write
+
+jobs:
+ welcome:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/github-script@v7
+ with:
+ script: |
+ const pr = context.payload.pull_request;
+ const isStory = pr.title.toLowerCase().includes('story') ||
+ pr.body?.toLowerCase().includes('stories/');
+ const opener = pr.user.login;
+
+ const body = [
+ `Thanks @${opener} for contributing${isStory ? ' a production story' : ''} — failures and honest wins are first-class here.`,
+ '',
+ '**What happens next**',
+ '- Maintainer aims for **same-day review** on story and adopter PRs (see [CONTRIBUTING.md — Maintainer response](https://github.com/cobusgreyling/loop-engineering/blob/main/CONTRIBUTING.md#maintainer-response-adopters--stories)).',
+ '- Small fixes may be merged quickly; larger asks get one focused review round.',
+ '',
+ '**Want a follow-up?** Comment if you would like help turning this into a tool example or a `good first issue` for someone else.',
+ '',
+ '— loop-engineering maintainers'
+ ].join('\n');
+
+ await github.rest.issues.createComment({
+ owner: context.repo.owner,
+ repo: context.repo.repo,
+ issue_number: pr.number,
+ body
+ });
\ No newline at end of file
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 404b869..afab8db 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -13,6 +13,19 @@ This repo is a **practical engineering reference**, not a hype collection. We we
| 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:** [Add your project to adopters](https://github.com/cobusgreyling/loop-engineering/issues/new?template=add-adopter.yml) · [Share a story issue](https://github.com/cobusgreyling/loop-engineering/issues/new?template=share-story.yml) · [`good first issue` backlog](https://github.com/cobusgreyling/loop-engineering/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)
+
## Pattern Requirements
Every new pattern must include all sections from [templates/pattern-template.md](./templates/pattern-template.md):
@@ -50,6 +63,16 @@ Also add an entry to `patterns/registry.yaml`.
- Failures are first-class content
- Tool-agnostic by default; tool-specific in labeled sections
+## Maintainer response (adopters & stories)
+
+PRs that only touch `stories/`, `docs/adopters.md`, or the [Add Adopter](https://github.com/cobusgreyling/loop-engineering/issues/new?template=add-adopter.yml) 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**: [GitHub Discussions](https://github.com/cobusgreyling/loop-engineering/discussions) (preferred) or issue with label `question`
diff --git a/README.md b/README.md
index 798221e..28d64a3 100644
--- a/README.md
+++ b/README.md
@@ -243,7 +243,7 @@ Addy Osmani:
## Contributing
-Share production patterns, tool mappings, and failure stories. See [CONTRIBUTING.md](CONTRIBUTING.md), [adopters](docs/adopters.md), and [GitHub Discussions](https://github.com/cobusgreyling/loop-engineering/discussions).
+Share production patterns, tool mappings, and failure stories. See [CONTRIBUTING.md](CONTRIBUTING.md) (contribution ladder + [`good first issue` backlog](https://github.com/cobusgreyling/loop-engineering/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)), [adopters](docs/adopters.md), and [GitHub Discussions](https://github.com/cobusgreyling/loop-engineering/discussions).
## Sources
diff --git a/scripts/create-good-first-issues.sh b/scripts/create-good-first-issues.sh
new file mode 100755
index 0000000..438a5b5
--- /dev/null
+++ b/scripts/create-good-first-issues.sh
@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+# Idempotent backlog bootstrap. Skips issues that already exist by title.
+set -euo pipefail
+
+REPO="cobusgreyling/loop-engineering"
+BODY_DIR="$(cd "$(dirname "$0")/issue-bodies" && pwd)"
+
+create_issue() {
+ local title="$1"
+ local labels="$2"
+ local body_file="$3"
+
+ if gh issue list --repo "$REPO" --search "in:title \"${title}\"" --state all --json title --jq '.[].title' | grep -Fxq "$title"; then
+ echo "SKIP (exists): $title"
+ gh issue list --repo "$REPO" --search "in:title \"${title}\"" --state open --json number,url --jq '.[0] | "#\(.number) \(.url)"'
+ return
+ fi
+
+ gh issue create --repo "$REPO" --title "$title" --label "$labels" --body-file "$body_file"
+}
+
+create_issue "Add Cursor daily-triage example" "good first issue,docs" "$BODY_DIR/cursor-daily-triage.md"
+create_issue "Add Windsurf daily-triage example" "good first issue,docs" "$BODY_DIR/windsurf-daily-triage.md"
+create_issue "Add Cursor and Windsurf columns to examples pattern table" "good first issue,docs" "$BODY_DIR/examples-cursor-windsurf-columns.md"
+create_issue "Expand Aider appendix in primitives-matrix" "good first issue,docs" "$BODY_DIR/aider-appendix.md"
+create_issue "Add Continue.dev row to primitives matrix" "good first issue,docs" "$BODY_DIR/continue-dev-matrix.md"
+create_issue "Share your week-one Daily Triage story" "good first issue,story" "$BODY_DIR/daily-triage-story.md"
+create_issue "Share a PR Babysitter failure story" "good first issue,story" "$BODY_DIR/pr-babysitter-story.md"
+create_issue "Add your project to the adopters list" "good first issue,docs" "$BODY_DIR/adopters-row.md"
+create_issue "Clarify loop-init --tool values in QUICKSTART cheat sheet" "good first issue,docs" "$BODY_DIR/quickstart-tool-values.md"
+create_issue "Add loop-triage constraints example for Cursor" "good first issue,docs" "$BODY_DIR/cursor-constraints.md"
+
+echo "Done. Open backlog:"
+echo "https://github.com/cobusgreyling/loop-engineering/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22"
\ No newline at end of file
diff --git a/scripts/issue-bodies/adopters-row.md b/scripts/issue-bodies/adopters-row.md
new file mode 100644
index 0000000..9823677
--- /dev/null
+++ b/scripts/issue-bodies/adopters-row.md
@@ -0,0 +1,12 @@
+## Goal
+If you run a loop from this repo or adapted from it, add yourself to the adopters wall.
+
+## Fast path
+Open the **Add Adopter** issue template — we add your row.
+
+## PR path
+Add a row to `docs/adopters.md` with: Project, Pattern(s), Tool, Level, Notes.
+
+Optional: paste your Loop Ready badge in your project README first.
+
+**Estimated time:** ~10 minutes. Same-day merge when possible.
diff --git a/scripts/issue-bodies/aider-appendix.md b/scripts/issue-bodies/aider-appendix.md
new file mode 100644
index 0000000..0a93a2f
--- /dev/null
+++ b/scripts/issue-bodies/aider-appendix.md
@@ -0,0 +1,12 @@
+## Goal
+`docs/primitives-matrix.md` mentions Aider in one line. Expand into a short appendix with scheduling and state conventions.
+
+## Files
+- `docs/primitives-matrix.md`
+
+## Acceptance criteria
+- [ ] New subsection **Appendix: Aider CLI** with scheduling, skills, state, verifier
+- [ ] One Daily Triage copy-paste command for week-one report-only
+- [ ] Link from appendix back to main matrix intro
+
+**Estimated time:** ~30 minutes
diff --git a/scripts/issue-bodies/continue-dev-matrix.md b/scripts/issue-bodies/continue-dev-matrix.md
new file mode 100644
index 0000000..2aa8335
--- /dev/null
+++ b/scripts/issue-bodies/continue-dev-matrix.md
@@ -0,0 +1,12 @@
+## Goal
+Document **Continue.dev** in the primitives matrix for contributors using VS Code plus Continue.
+
+## Files
+- `docs/primitives-matrix.md`
+
+## Acceptance criteria
+- [ ] Add Continue.dev column or dedicated appendix
+- [ ] Cover scheduling, skills path, STATE.md convention, maker/checker split
+- [ ] Honest note if a primitive is not first-class in Continue yet
+
+**Estimated time:** ~45 minutes
diff --git a/scripts/issue-bodies/cursor-constraints.md b/scripts/issue-bodies/cursor-constraints.md
new file mode 100644
index 0000000..445a3f8
--- /dev/null
+++ b/scripts/issue-bodies/cursor-constraints.md
@@ -0,0 +1,13 @@
+## Goal
+Grok, Claude, Codex, and Opencode ship `constraints.md` examples. Add Cursor equivalent.
+
+## Files
+- Create `examples/cursor/constraints.md`
+- Link from `examples/cursor/README.md`
+
+## Acceptance criteria
+- [ ] Mirror structure of `examples/grok/constraints.md`
+- [ ] Map constraints to `.cursor/rules/` or `AGENTS.md`
+- [ ] Reference `docs/safety.md` for denylist and human gates
+
+**Estimated time:** ~30 minutes
diff --git a/scripts/issue-bodies/cursor-daily-triage.md b/scripts/issue-bodies/cursor-daily-triage.md
new file mode 100644
index 0000000..1016300
--- /dev/null
+++ b/scripts/issue-bodies/cursor-daily-triage.md
@@ -0,0 +1,17 @@
+## Goal
+Add a copy-pasteable Daily Triage example for **Cursor** under `examples/cursor/`.
+
+## Files
+- Create `examples/cursor/daily-triage.md`
+- Create `examples/cursor/README.md` (index linking to daily-triage)
+- Link from `examples/README.md` tool table
+
+## Acceptance criteria
+- [ ] Follow structure of [`examples/grok/daily-triage.md`](../blob/main/examples/grok/daily-triage.md): command, supporting files, STATE shape, week-one report-only note
+- [ ] Map scheduling to Cursor **Automations** or Agent chat (see [primitives-matrix appendix](https://github.com/cobusgreyling/loop-engineering/blob/main/docs/primitives-matrix.md#appendix-editor-transfer-recipes-opencode-cursor--windsurf))
+- [ ] Link from `docs/QUICKSTART.md` Cursor section to the new example
+- [ ] No secrets or internal URLs
+
+**Estimated time:** ~30 minutes
+
+Comment **“I’ll take this”** to get assigned.
diff --git a/scripts/issue-bodies/daily-triage-story.md b/scripts/issue-bodies/daily-triage-story.md
new file mode 100644
index 0000000..5573ca8
--- /dev/null
+++ b/scripts/issue-bodies/daily-triage-story.md
@@ -0,0 +1,15 @@
+## Goal
+Add a real production story to `stories/`.
+
+## Files
+- New `stories/your-slug.md`
+- Update `stories/README.md` index row
+
+## Requirements
+- Name the pattern: Daily Triage
+- Include at least one failure or surprise
+- One-paragraph actionable lesson
+- Anonymize employer details if needed
+
+Template: `stories/README.md`. Same-day review for story PRs.
+**Estimated time:** ~45 minutes
diff --git a/scripts/issue-bodies/examples-cursor-windsurf-columns.md b/scripts/issue-bodies/examples-cursor-windsurf-columns.md
new file mode 100644
index 0000000..151f726
--- /dev/null
+++ b/scripts/issue-bodies/examples-cursor-windsurf-columns.md
@@ -0,0 +1,12 @@
+## Goal
+`examples/README.md` pattern coverage table lists Grok through GitHub Actions but not Cursor or Windsurf.
+
+## Files
+- `examples/README.md`
+
+## Acceptance criteria
+- [ ] Add **Cursor** and **Windsurf** columns to the pattern coverage table
+- [ ] Link to `examples/cursor/daily-triage.md` and `examples/windsurf/daily-triage.md`
+- [ ] Add Cursor and Windsurf rows to the top-level tool directory table
+
+**Estimated time:** ~20 minutes
diff --git a/scripts/issue-bodies/pr-babysitter-story.md b/scripts/issue-bodies/pr-babysitter-story.md
new file mode 100644
index 0000000..e9c65b9
--- /dev/null
+++ b/scripts/issue-bodies/pr-babysitter-story.md
@@ -0,0 +1,12 @@
+## Goal
+PR Babysitter is high-token and easy to misconfigure. We want another honest story in `stories/`.
+
+## Files
+- New `stories/your-pr-babysitter-slug.md`
+- Update `stories/README.md`
+
+## Inspiration
+- `stories/pr-babysitter-week-one.md`
+- `stories/why-we-killed-ci-sweeper.md`
+
+**Estimated time:** ~1 hour. Story PRs get same-day review.
diff --git a/scripts/issue-bodies/quickstart-tool-values.md b/scripts/issue-bodies/quickstart-tool-values.md
new file mode 100644
index 0000000..e2fc3ee
--- /dev/null
+++ b/scripts/issue-bodies/quickstart-tool-values.md
@@ -0,0 +1,12 @@
+## Goal
+New contributors confuse which `--tool` values `loop-init` accepts vs manual copy for Cursor, Windsurf, and OpenClaw.
+
+## Files
+- `docs/QUICKSTART.md`
+
+## Acceptance criteria
+- [ ] List scaffolded tools: grok, claude, codex, opencode vs manual copy: cursor, windsurf, openclaw
+- [ ] Pointer to `npx @cobusgreyling/loop-init --help` for pattern list
+- [ ] Docs only — no CLI changes
+
+**Estimated time:** ~20 minutes
diff --git a/scripts/issue-bodies/windsurf-daily-triage.md b/scripts/issue-bodies/windsurf-daily-triage.md
new file mode 100644
index 0000000..521d747
--- /dev/null
+++ b/scripts/issue-bodies/windsurf-daily-triage.md
@@ -0,0 +1,15 @@
+## Goal
+Add a copy-pasteable Daily Triage example for **Windsurf** under `examples/windsurf/`.
+
+## Files
+- Create `examples/windsurf/daily-triage.md`
+- Create `examples/windsurf/README.md`
+- Link from `examples/README.md` tool table
+
+## Acceptance criteria
+- [ ] Follow structure of [`examples/grok/daily-triage.md`](../blob/main/examples/grok/daily-triage.md)
+- [ ] Map scheduling to Cascade **Workflows** (`/workflow-name`) per [primitives-matrix appendix](https://github.com/cobusgreyling/loop-engineering/blob/main/docs/primitives-matrix.md#appendix-editor-transfer-recipes-opencode-cursor--windsurf)
+- [ ] Week-one report-only emphasis (no auto-fix)
+- [ ] Link from `docs/QUICKSTART.md` Windsurf bullet to the new example
+
+**Estimated time:** ~30 minutes