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
chore: maintenance — constraints dogfood, welcome workflow, mcp-server npm (#177)
Cobus Greyling996e34b58383
diff --git a/.github/workflows/release-loop-mcp-server.yml b/.github/workflows/release-loop-mcp-server.ymlnew file mode 100644index 0000000..d0a8641--- /dev/null+++ b/.github/workflows/release-loop-mcp-server.yml@@ -0,0 +1,63 @@+name: Release loop-mcp-server++on:+ push:+ tags:+ - 'loop-mcp-server-v*'+ workflow_dispatch:+ inputs:+ tag:+ description: 'Tag to publish (e.g. loop-mcp-server-v1.0.0)'+ required: true+ type: string++permissions:+ contents: read+ id-token: write++jobs:+ test-and-publish:+ runs-on: ubuntu-latest+ steps:+ - uses: actions/checkout@v7+ with:+ ref: ${{ github.event_name == 'workflow_dispatch' && format('refs/tags/{0}', github.event.inputs.tag) || github.ref }}++ - uses: actions/setup-node@v6+ with:+ node-version: '22'+ registry-url: 'https://registry.npmjs.org'+ cache: 'npm'+ cache-dependency-path: tools/mcp-server/package-lock.json++ - name: Ensure npm supports trusted publishing (OIDC)+ run: npm install -g npm@latest++ - name: Install, build, test+ working-directory: tools/mcp-server+ run: |+ npm ci+ npm run build+ npm test++ - name: Skip if version already published+ id: check+ working-directory: tools/mcp-server+ run: |+ VERSION=$(node -p "require('./package.json').version")+ if npm view "@cobusgreyling/loop-mcp-server@${VERSION}" version 2>/dev/null; then+ echo "Version ${VERSION} already on npm — skipping publish."+ echo "skip=true" >> "$GITHUB_OUTPUT"+ else+ echo "Publishing @cobusgreyling/loop-mcp-server@${VERSION}"+ echo "skip=false" >> "$GITHUB_OUTPUT"+ fi+ env:+ NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}++ - name: Publish to npm+ if: steps.check.outputs.skip != 'true'+ working-directory: tools/mcp-server+ run: npm publish --access public --provenance+ env:+ NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}\ No newline at end of filediff --git a/.github/workflows/welcome-contributors.yml b/.github/workflows/welcome-contributors.ymlindex b8f997f..3e7f0cd 100644--- a/.github/workflows/welcome-contributors.yml+++ b/.github/workflows/welcome-contributors.yml@@ -12,6 +12,7 @@ on:- 'docs/**'permissions:+ contents: readissues: writepull-requests: write@@ -24,17 +25,36 @@ jobs:script: |const pr = context.payload.pull_request;const opener = pr.user.login;- const files = await github.paginate(- github.rest.pulls.listFiles,- { owner: context.repo.owner, repo: context.repo.repo, pull_number: pr.number, per_page: 100 }+ const marker = '— loop-engineering maintainers';++ const comments = await github.paginate(+ github.rest.issues.listComments,+ { owner: context.repo.owner, repo: context.repo.repo, issue_number: pr.number, per_page: 100 });- const paths = files.map((f) => f.filename);+ if (comments.some((c) => c.body?.includes(marker))) {+ core.info('Welcome comment already present; skipping.');+ return;+ }++ let paths = [];+ try {+ const files = await github.paginate(+ github.rest.pulls.listFiles,+ { owner: context.repo.owner, repo: context.repo.repo, pull_number: pr.number, per_page: 100 }+ );+ paths = files.map((f) => f.filename);+ } catch (err) {+ core.warning(`Could not list PR files (${err.message}); inferring from title/body.`);+ }+const isStory = pr.title.toLowerCase().includes('story') ||pr.body?.toLowerCase().includes('stories/') ||paths.some((p) => p.startsWith('stories/'));const isAdopter = paths.some((p) => p === 'docs/adopters.md');- const isExample = paths.some((p) => p.startsWith('examples/'));- const isDocs = paths.some((p) => p.startsWith('docs/'));+ const isExample = paths.some((p) => p.startsWith('examples/')) ||+ pr.title.toLowerCase().includes('example');+ const isDocs = paths.some((p) => p.startsWith('docs/')) ||+ pr.title.toLowerCase().includes('docs:');let kind = 'a contribution';if (isStory) kind = 'a production story';@@ -42,16 +62,6 @@ jobs:else if (isExample) kind = 'a tool example';else if (isDocs) kind = 'a docs improvement';- const marker = '— loop-engineering maintainers';- const comments = await github.paginate(- github.rest.issues.listComments,- { owner: context.repo.owner, repo: context.repo.repo, issue_number: pr.number, per_page: 100 }- );- if (comments.some((c) => c.body?.includes(marker))) {- core.info('Welcome comment already present; skipping.');- return;- }-const body = [`Thanks @${opener} for contributing ${kind} — visible, reviewable PRs like this grow the reference for everyone.`,'',diff --git a/README.md b/README.mdindex 5f583f5..b6894d5 100644--- a/README.md+++ b/README.md@@ -90,7 +90,7 @@ For developers using Grok, Claude Code, Codex, Cursor, and other AI coding agent| [loop-cost](tools/loop-cost/) | Token spend estimator — `npx @cobusgreyling/loop-cost` || [loop-sync](tools/loop-sync/) | Drift detection between `STATE.md` and `LOOP.md` — `npx @cobusgreyling/loop-sync .` || [loop-context](tools/loop-context/) | Stateful memory manager + circuit breaker for long runs — `npx @cobusgreyling/loop-context --check --ledger run.json` |-| [loop-mcp-server](tools/mcp-server/) | MCP runtime lookup for patterns, skills, state — `node tools/mcp-server/dist/index.js` (repo v1; npm pending) |+| [loop-mcp-server](tools/mcp-server/) | MCP runtime lookup for patterns, skills, state — `npx @cobusgreyling/loop-mcp-server` || [Goal Engineering](https://github.com/cobusgreyling/goal-engineering) | **Companion:** loops discover, goals finish — `/goal` + [stack cookbook](https://github.com/cobusgreyling/goal-engineering/blob/main/docs/stack-cookbook.md) (`npx @cobusgreyling/goal doctor .`) || [Stories](stories/) | Real wins and honest failures || [Contributor quickstart](https://github.com/cobusgreyling/loop-engineering/discussions/123) | **Help wanted:** 12 scoped `good first issues` — comment *I'll take this* to get assigned |diff --git a/docs/RELEASE.md b/docs/RELEASE.mdindex 2ac578c..142c9ea 100644--- a/docs/RELEASE.md+++ b/docs/RELEASE.md@@ -1,6 +1,6 @@# Release playbook — npm packages-This repo ships five public npm packages from `tools/`:+This repo ships six public npm packages from `tools/`:| Package | Directory | Release tag ||---------|-----------|-------------|@@ -9,6 +9,7 @@ This repo ships five public npm packages from `tools/`:| `@cobusgreyling/loop-cost` | `tools/loop-cost` | `loop-cost-v*` || `@cobusgreyling/loop-sync` | `tools/loop-sync` | `loop-sync-v*` || `@cobusgreyling/loop-context` | `tools/loop-context` | `loop-context-v*` |+| `@cobusgreyling/loop-mcp-server` | `tools/mcp-server` | `loop-mcp-server-v*` |## One-time setup (trusted publishing — recommended)@@ -21,6 +22,7 @@ Link npm to GitHub, then for **each package** on [npmjs.com](https://www.npmjs.c| `@cobusgreyling/loop-cost` | `cobusgreyling/loop-engineering` | `release-loop-cost.yml` || `@cobusgreyling/loop-sync` | `cobusgreyling/loop-engineering` | `release-loop-sync.yml` || `@cobusgreyling/loop-context` | `cobusgreyling/loop-engineering` | `release-loop-context.yml` |+| `@cobusgreyling/loop-mcp-server` | `cobusgreyling/loop-engineering` | `release-loop-mcp-server.yml` |Names must match **exactly** (case-sensitive). No `NPM_TOKEN` secret is required when trusted publishing is configured.@@ -58,9 +60,13 @@ git push origin loop-sync-v1.0.0# loop-context (stateful memory manager + circuit breaker)git tag loop-context-v1.0.0git push origin loop-context-v1.0.0++# loop-mcp-server (MCP runtime lookup for patterns, skills, state)+git tag loop-mcp-server-v1.0.0+git push origin loop-mcp-server-v1.0.0```-Workflows: `.github/workflows/release-loop-audit.yml`, `.github/workflows/release-loop-init.yml`, `.github/workflows/release-loop-cost.yml`, `.github/workflows/release-loop-sync.yml`, `.github/workflows/release-loop-context.yml`.+Workflows: `.github/workflows/release-loop-audit.yml`, `.github/workflows/release-loop-init.yml`, `.github/workflows/release-loop-cost.yml`, `.github/workflows/release-loop-sync.yml`, `.github/workflows/release-loop-context.yml`, `.github/workflows/release-loop-mcp-server.yml`.## Verify after publish@@ -70,6 +76,7 @@ npx @cobusgreyling/loop-init --helpnpx @cobusgreyling/loop-cost --helpnpx @cobusgreyling/loop-sync --helpnpx @cobusgreyling/loop-context --help+npx @cobusgreyling/loop-mcp-server --helpmkdir /tmp/loop-init-test && cd /tmp/loop-init-testnpx @cobusgreyling/loop-init . --pattern daily-triage --tool grok --dry-rundiff --git a/loop-constraints.md b/loop-constraints.mdnew file mode 100644index 0000000..9774aaf--- /dev/null+++ b/loop-constraints.md@@ -0,0 +1,32 @@+# Loop Constraints — loop-engineering reference++> The `loop-constraints` skill reads this file at the start of every run.+> Constraints here are **binding** — the agent MUST follow them.++## Push & Merge+- Don't push before telling me+- Never auto-merge to main without human approval+- Always create a draft PR first; let me review before marking ready++## Paths+- Never edit `.env`, `.env.*`, `auth/`, `payments/`, `secrets/`, `credentials/`+- Never edit `tools/loop-audit/src/`, `docs/primitives*.md`, or showcase assets without human review+- Never edit infrastructure configs without human approval++## Code+- Always run tests before proposing a fix (`npm run test:tools` for tool changes)+- Never disable tests to make CI green+- Never refactor unrelated code — one fix per run+- Max 3 fix attempts per item; escalate after+- Enforce the attempt limit mechanically: log each try to `loop-ledger.json` and run `loop-context --check` before retrying (see the `loop-guard` skill)++## Communication+- Always tell me what you're about to do before doing it+- Never close an issue or PR without my approval++## Budget+- If token spend hits 80% of daily cap, switch to report-only+- If loop-pause-all is active, exit immediately++---+<!-- Repo-specific rules above. Add your own below. -->\ No newline at end of filediff --git a/skills/loop-constraints/SKILL.md b/skills/loop-constraints/SKILL.mdnew file mode 100644index 0000000..0c86ddf--- /dev/null+++ b/skills/loop-constraints/SKILL.md@@ -0,0 +1,48 @@+---+name: loop-constraints+description: >+ Read loop-constraints.md at the start of every run and enforce every rule.+ This skill runs BEFORE triage or any action skill. Constraints are binding.+user_invocable: true+---++# Loop Constraints Enforcer++You are the guardrail. Before any other work begins, you MUST:++1. Read `loop-constraints.md` from the project root.+2. Load every rule into your working memory.+3. Check if `loop-pause-all` is active → exit immediately.+4. Apply these rules to EVERY action that follows.++## How to enforce++- Before pushing: re-read the Push & Merge section. If ANY rule blocks it, stop and tell the human.+- Before editing a file: re-read the Paths section. If the path matches a denylist pattern, escalate.+- Before proposing a fix: re-read the Code section. Run tests. One fix per run.+- Before merging: re-read the Push & Merge section. Human must approve.++## Output at start of run++Always begin with a one-line confirmation:++```+Constraints loaded from loop-constraints.md: N rules active.+```++If no `loop-constraints.md` exists, say so and proceed with default safety rules from `docs/safety.md`.++## Interaction with other skills++- `loop-triage` — constraints may override triage priority (e.g. "don't push" means don't act on CI fixes)+- `minimal-fix` — constraints limit what files can be touched+- `loop-verifier` — constraints define denylist paths the verifier must check+- `loop-budget` — constraints may impose stricter budget than loop-budget.md++## Default constraints (when no file exists)++If `loop-constraints.md` is absent, enforce these minimums:+- Never edit `.env`, `.env.*`, `auth/`, `payments/`, `secrets/`, `credentials/`+- Never auto-merge to main+- Never disable tests+- Escalate after 3 failed fix attempts\ No newline at end of filediff --git a/tools/mcp-server/CHANGELOG.md b/tools/mcp-server/CHANGELOG.mdnew file mode 100644index 0000000..e5664df--- /dev/null+++ b/tools/mcp-server/CHANGELOG.md@@ -0,0 +1,7 @@+# Changelog — @cobusgreyling/loop-mcp-server++## 1.0.0 — 2026-07-06++- Initial npm release+- MCP resources for patterns, skills, state, budget, and audit tools+- `loop_list_patterns`, `loop_estimate_cost`, and related runtime lookup tools\ No newline at end of filediff --git a/tools/mcp-server/README.md b/tools/mcp-server/README.mdindex 554aa22..d1fc440 100644--- a/tools/mcp-server/README.md+++ b/tools/mcp-server/README.md@@ -6,7 +6,11 @@ Instead of stuffing all loop documentation into the prompt, agents can query onl## Quick Start-**v1 ships from this repo** (npm publish pending). From a cloned `loop-engineering` repo:+```bash+npx @cobusgreyling/loop-mcp-server+```++From a cloned `loop-engineering` repo:```bashcd tools/mcp-server && npm ci && npm testdiff --git a/tools/mcp-server/dist/index.js b/tools/mcp-server/dist/index.jsold mode 100644new mode 100755diff --git a/tools/mcp-server/package.json b/tools/mcp-server/package.jsonindex 56b568d..68535c9 100644--- a/tools/mcp-server/package.json+++ b/tools/mcp-server/package.json@@ -11,7 +11,7 @@"README.md"],"scripts": {- "build": "tsc",+ "build": "tsc && chmod +x dist/index.js","test": "npm run build && node --test test/server.test.mjs","prepublishOnly": "npm test","start": "node dist/index.js"