Merge pull request #176 from cobusgreyling/feat/contributor-growth

feat: contributor growth — CLI CTAs, CONTRIBUTORS.md, backlog refresh

Author: cobusgreyling

CONTRIBUTING.md

@@ -79,6 +79,7 @@ Automation posts a welcome comment on new story/adopter PRs (see `.github/workfl
 - **Show your loop**: [Add Adopter issue](https://github.com/cobusgreyling/loop-engineering/issues/new?template=add-adopter.yml), Discussions, or a row in [docs/adopters.md](./docs/adopters.md)
 - **Loop Ready badge**: `npx @cobusgreyling/loop-audit . --badge` — paste into your README
 - **Good first issues**: look for label [`good first issue`](https://github.com/cobusgreyling/loop-engineering/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)
+- **Hall of fame**: [CONTRIBUTORS.md](./CONTRIBUTORS.md) — regenerate after merges with `npm run contributors:generate`
 - **Security**: see [SECURITY.md](./SECURITY.md) — do not file public issues for exploitable vulnerabilities
 
 Thank you for helping make this the go-to reference for loop engineering.

CONTRIBUTORS.md

@@ -0,0 +1,22 @@
+# Contributors
+
+Thank you to everyone who shipped docs, stories, examples, and tool fixes.
+
+*Generated 2026-07-06 via `node scripts/generate-contributors.mjs` — re-run after merges.*
+
+| Contributor | Highlights |
+|-------------|------------|
+| [@KhaiTrang1995](https://github.com/KhaiTrang1995) | #165 feat(loop-guard): size the token budget from loop-cost per pattern<br>#140 feat(loop-init): wire loop-context circuit breaker into scaffolding + ci-sweeper |
+| [@50thycal](https://github.com/50thycal) | story: `quant-loop-out-of-time.md`<br>story: `quant-loop-the-verifier-problem.md` |
+| [@neerajdad123-byte](https://github.com/neerajdad123-byte) | 3 commits |
+| [@ulises-jeremias](https://github.com/ulises-jeremias) | #98 docs(examples): add opencode tool coverage |
+| [@jiaobotao](https://github.com/jiaobotao) | #141 Add Hermes Agent example (daily-triage) + primitives matrix column |
+| [@k-anushka14](https://github.com/k-anushka14) | #156 docs: add Cursor PR Babysitter example |
+| [@roian6](https://github.com/roian6) | #127 docs: expand Aider primitives appendix |
+| [@Zhang-986](https://github.com/Zhang-986) | #138 fix(loop-sync): honor json output flag |
+
+## Your first PR
+
+Pick a scoped ~15 min task: [Contributor quickstart](https://github.com/cobusgreyling/loop-engineering/discussions/123).
+
+Same-day review on stories, adopters, and docs — see [CONTRIBUTING.md](./CONTRIBUTING.md).

README.md

@@ -247,7 +247,7 @@ Addy Osmani:
 
 ## Help wanted
 
-**First PR?** Start with the [contributor quickstart](https://github.com/cobusgreyling/loop-engineering/discussions/123) — ~10 min to ~1 hr tasks with same-day review on stories and adopters.
+**First PR?** Start with the [contributor quickstart](https://github.com/cobusgreyling/loop-engineering/discussions/123) — ~10 min to ~1 hr tasks with same-day review on stories and adopters. See [CONTRIBUTORS.md](CONTRIBUTORS.md) for everyone who has shipped so far.
 
 | Pick one | Issue |
 |----------|-------|

package.json

@@ -12,7 +12,9 @@
     "test:loop-context": "cd tools/loop-context && npm test",
     "test:mcp-server": "cd tools/mcp-server && npm test",
     "test:tools": "npm run test:loop-audit && npm run test:loop-init && npm run test:loop-cost && npm run test:loop-sync && npm run test:loop-context && npm run test:mcp-server",
-    "build:tools": "cd tools/loop-audit && npm run build && cd ../loop-init && npm run build && cd ../loop-cost && npm run build && cd ../loop-sync && npm run build && cd ../loop-context && npm run build && cd ../mcp-server && npm run build"
+    "build:tools": "cd tools/loop-audit && npm run build && cd ../loop-init && npm run build && cd ../loop-cost && npm run build && cd ../loop-sync && npm run build && cd ../loop-context && npm run build && cd ../mcp-server && npm run build",
+    "contributors:generate": "node scripts/generate-contributors.mjs",
+    "contributors:check": "node scripts/generate-contributors.mjs --check"
   },
   "devDependencies": {
     "ajv": "^8.17.1",

scripts/create-good-first-issues.sh

@@ -35,5 +35,14 @@ create_issue "Add examples/hermes/README.md index" "good first issue,docs" "$BOD
 create_issue "Add Windsurf PR Babysitter example doc" "good first issue,docs" "$BODY_DIR/windsurf-pr-babysitter-example.md"
 create_issue "Share a Post-Merge Cleanup production story" "good first issue,story" "$BODY_DIR/post-merge-cleanup-story.md"
 
+# Wave 2 — refresh backlog after Jul 2026 merges (idempotent; skips existing titles)
+create_issue "Add loop-context subsection to QUICKSTART" "good first issue,docs" "$BODY_DIR/quickstart-loop-context.md"
+create_issue "Add loop-mcp-server subsection to QUICKSTART" "good first issue,docs" "$BODY_DIR/quickstart-mcp-server.md"
+create_issue "Link Aider appendix from examples README" "good first issue,docs" "$BODY_DIR/examples-aider-link.md"
+create_issue "Add Hermes to examples README tool directory" "good first issue,docs" "$BODY_DIR/hermes-examples-readme.md"
+create_issue "Share an Issue Triage week-one story" "good first issue,story" "$BODY_DIR/issue-triage-story.md"
+create_issue "Add Opencode constraints example doc" "good first issue,docs" "$BODY_DIR/opencode-constraints-example.md"
+create_issue "Share a multi-loop coordination story" "good first issue,story" "$BODY_DIR/multi-loop-story.md"
+
 echo "Done. Open backlog:"
 echo "https://github.com/cobusgreyling/loop-engineering/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22"

scripts/generate-contributors.mjs

@@ -0,0 +1,171 @@
+#!/usr/bin/env node
+/**
+ * Regenerate CONTRIBUTORS.md from GitHub API + story attributions.
+ * Requires: gh auth login (read access to public repo is enough)
+ *
+ *   node scripts/generate-contributors.mjs
+ *   node scripts/generate-contributors.mjs --check   # exit 1 if file would change
+ */
+import { execFileSync } from 'node:child_process';
+import { readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const ROOT = path.resolve(__dirname, '..');
+const OUT = path.join(ROOT, 'CONTRIBUTORS.md');
+const REPO = 'cobusgreyling/loop-engineering';
+const MAINTAINER = 'cobusgreyling';
+const BOTS = new Set(['github-actions[bot]', 'dependabot[bot]', 'dependabot']);
+
+const CONTRIBUTOR_QUICKSTART =
+  'https://github.com/cobusgreyling/loop-engineering/discussions/123';
+
+function ghJson(args) {
+  return JSON.parse(execFileSync('gh', args, { encoding: 'utf8', cwd: ROOT }));
+}
+
+function ghApiPaginated(route) {
+  const out = execFileSync('gh', ['api', route, '--paginate'], { encoding: 'utf8', cwd: ROOT });
+  const items = [];
+  for (const line of out.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    const parsed = JSON.parse(trimmed);
+    if (Array.isArray(parsed)) items.push(...parsed);
+    else items.push(parsed);
+  }
+  return items;
+}
+
+function storyAttributions() {
+  const storiesDir = path.join(ROOT, 'stories');
+  const attributions = new Map();
+  let files;
+  try {
+    files = readdirSync(storiesDir).filter((f) => f.endsWith('.md'));
+  } catch {
+    return attributions;
+  }
+  const re = /Contributed by \[@([^\]]+)\]/g;
+  for (const file of files) {
+    const text = readFileSync(path.join(storiesDir, file), 'utf8');
+    for (const m of text.matchAll(re)) {
+      const login = m[1];
+      if (!attributions.has(login)) attributions.set(login, []);
+      attributions.get(login).push(`story: \`${file}\``);
+    }
+  }
+  return attributions;
+}
+
+async function main() {
+  const check = process.argv.includes('--check');
+
+  const apiContributors = ghApiPaginated(`repos/${REPO}/contributors`);
+
+  const mergedPrs = ghJson([
+    'pr',
+    'list',
+    '--repo',
+    REPO,
+    '--state',
+    'merged',
+    '--limit',
+    '200',
+    '--json',
+    'author,title,number',
+  ]);
+
+  const highlights = new Map();
+  for (const pr of mergedPrs) {
+    const login = pr.author?.login;
+    if (!login || login === MAINTAINER || pr.author?.is_bot) continue;
+    if (!highlights.has(login)) highlights.set(login, []);
+    const list = highlights.get(login);
+    if (list.length < 2) list.push(`#${pr.number} ${pr.title}`);
+  }
+
+  const storyAttrs = storyAttributions();
+
+  const people = new Map();
+  for (const c of apiContributors) {
+    const login = c.login;
+    if (login === MAINTAINER || BOTS.has(login) || login.endsWith('[bot]')) continue;
+    people.set(login, {
+      login,
+      contributions: c.contributions ?? 0,
+      highlights: highlights.get(login) ?? [],
+      stories: storyAttrs.get(login) ?? [],
+    });
+  }
+
+  for (const [login, stories] of storyAttrs) {
+    if (people.has(login)) {
+      people.get(login).stories = stories;
+      continue;
+    }
+    people.set(login, {
+      login,
+      contributions: 0,
+      highlights: highlights.get(login) ?? [],
+      stories,
+    });
+  }
+
+  const sorted = [...people.values()].sort((a, b) => {
+    const score = (p) => p.contributions + p.stories.length * 2 + p.highlights.length;
+    return score(b) - score(a) || a.login.localeCompare(b.login);
+  });
+
+  const generated = new Date().toISOString().slice(0, 10);
+  const lines = [
+    '# Contributors',
+    '',
+    'Thank you to everyone who shipped docs, stories, examples, and tool fixes.',
+    '',
+    `*Generated ${generated} via \`node scripts/generate-contributors.mjs\` — re-run after merges.*`,
+    '',
+    '| Contributor | Highlights |',
+    '|-------------|------------|',
+  ];
+
+  for (const p of sorted) {
+    const bits = [...p.highlights, ...p.stories];
+    const cell =
+      bits.length > 0
+        ? bits.map((b) => b.replace(/\|/g, '\\|')).join('<br>')
+        : `${p.contributions} commit${p.contributions === 1 ? '' : 's'}`;
+    lines.push(`| [@${p.login}](https://github.com/${p.login}) | ${cell} |`);
+  }
+
+  lines.push(
+    '',
+    '## Your first PR',
+    '',
+    'Pick a scoped ~15 min task: [Contributor quickstart](' + CONTRIBUTOR_QUICKSTART + ').',
+    '',
+    'Same-day review on stories, adopters, and docs — see [CONTRIBUTING.md](./CONTRIBUTING.md).',
+    '',
+  );
+
+  const content = lines.join('\n');
+
+  if (check) {
+    const existing = readFileSync(OUT, 'utf8');
+    if (existing !== content) {
+      console.error('CONTRIBUTORS.md is out of date. Run: node scripts/generate-contributors.mjs');
+      process.exit(1);
+    }
+    console.log('CONTRIBUTORS.md is up to date.');
+    return;
+  }
+
+  writeFileSync(OUT, content);
+  console.log(`Wrote ${OUT} (${sorted.length} contributors)`);
+}
+
+main().catch((err) => {
+  console.error(err instanceof Error ? err.message : err);
+  process.exit(1);
+});

scripts/issue-bodies/issue-triage-story.md

@@ -0,0 +1,13 @@
+## Goal
+Share an honest **Issue Triage** week-one story — win or failure — so others know how to run label-only automation safely.
+
+## Files
+- New file under `stories/` (follow format in existing stories)
+
+## Acceptance criteria
+- [ ] Which tool you used and how issues were scheduled (cron, `/loop`, GitHub Action, etc.)
+- [ ] Week-one constraints (propose labels only, no auto-close, human gate)
+- [ ] One surprise (good or bad)
+- [ ] What you would change before week two
+
+**Estimated time:** ~15 minutes

scripts/issue-bodies/multi-loop-story.md

@@ -0,0 +1,13 @@
+## Goal
+Share a **multi-loop coordination** story — running two or more loops (e.g. Daily Triage + PR Babysitter) without them fighting each other.
+
+## Files
+- New file under `stories/`
+
+## Acceptance criteria
+- [ ] Name the patterns and tools you combined
+- [ ] How you separated state files, schedules, or budgets
+- [ ] At least one failure mode (overlap, duplicate PRs, context bleed)
+- [ ] One actionable lesson for the next reader
+
+**Estimated time:** ~20 minutes

scripts/issue-bodies/opencode-constraints-example.md

@@ -0,0 +1,14 @@
+## Goal
+Add an **Opencode constraints** example so CLI-first users can copy a `loop-triage` skill with explicit guardrails.
+
+## Files
+- `examples/opencode/constraints-example.md` (new)
+- `examples/opencode/README.md` — link the new doc
+
+## Acceptance criteria
+- [ ] Show a minimal `skills/loop-triage/SKILL.md` snippet with 3–5 constraints (read-only week one, no force-push, etc.)
+- [ ] Show how it pairs with `loop-init --tool opencode`
+- [ ] Link to `docs/safety.md` and the Cursor constraints example for comparison
+- [ ] No secrets or internal URLs
+
+**Estimated time:** ~30 minutes

tools/loop-audit/dist/cli.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { auditProject } from './auditor.js';
+import { printContributorCta } from './contributor-cta.js';
 import { formatBadge, formatHuman, formatJson, formatMarkdown } from './reporter.js';
 const args = process.argv.slice(2);
 const target = args.find((a) => !a.startsWith('-')) || '.';
@@ -92,6 +93,8 @@ try {
         console.log('');
         console.log('See docs/loop-design-checklist.md and patterns/ for full guidance.');
     }
+    if (!json && !badge && !md)
+        printContributorCta();
     if (result.score < 40)
         process.exitCode = 2;
 }