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.
TypeScript agentic-aiai-agentsai-codinganthropicautomationclaudeclaude-codecodexcoding-agentsdevops-automationdevtoolsgithub-actionsgrokllmloop-engineeringmcpprompt-engineering
Add contributor onboarding quick wins (#124)
Cobus Greylingf18df044362a
diff --git a/.github/workflows/welcome-contributors.yml b/.github/workflows/welcome-contributors.ymlnew file mode 100644index 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 filediff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 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 RequirementsEvery 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.mdindex 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).## Sourcesdiff --git a/scripts/create-good-first-issues.sh b/scripts/create-good-first-issues.shnew file mode 100755index 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 filediff --git a/scripts/issue-bodies/adopters-row.md b/scripts/issue-bodies/adopters-row.mdnew file mode 100644index 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.mdnew file mode 100644index 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 minutesdiff --git a/scripts/issue-bodies/continue-dev-matrix.md b/scripts/issue-bodies/continue-dev-matrix.mdnew file mode 100644index 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 minutesdiff --git a/scripts/issue-bodies/cursor-constraints.md b/scripts/issue-bodies/cursor-constraints.mdnew file mode 100644index 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 minutesdiff --git a/scripts/issue-bodies/cursor-daily-triage.md b/scripts/issue-bodies/cursor-daily-triage.mdnew file mode 100644index 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.mdnew file mode 100644index 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 minutesdiff --git a/scripts/issue-bodies/examples-cursor-windsurf-columns.md b/scripts/issue-bodies/examples-cursor-windsurf-columns.mdnew file mode 100644index 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 minutesdiff --git a/scripts/issue-bodies/pr-babysitter-story.md b/scripts/issue-bodies/pr-babysitter-story.mdnew file mode 100644index 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.mdnew file mode 100644index 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 minutesdiff --git a/scripts/issue-bodies/windsurf-daily-triage.md b/scripts/issue-bodies/windsurf-daily-triage.mdnew file mode 100644index 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