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.

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.yml
new file mode 100644
index 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 file
diff --git a/.github/workflows/welcome-contributors.yml b/.github/workflows/welcome-contributors.yml
index b8f997f..3e7f0cd 100644
--- a/.github/workflows/welcome-contributors.yml
+++ b/.github/workflows/welcome-contributors.yml
@@ -12,6 +12,7 @@ on:
- 'docs/**'
permissions:
+ contents: read
issues: write
pull-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.md
index 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.md
index 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.0
git 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 --help
npx @cobusgreyling/loop-cost --help
npx @cobusgreyling/loop-sync --help
npx @cobusgreyling/loop-context --help
+npx @cobusgreyling/loop-mcp-server --help
mkdir /tmp/loop-init-test && cd /tmp/loop-init-test
npx @cobusgreyling/loop-init . --pattern daily-triage --tool grok --dry-run
diff --git a/loop-constraints.md b/loop-constraints.md
new file mode 100644
index 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 file
diff --git a/skills/loop-constraints/SKILL.md b/skills/loop-constraints/SKILL.md
new file mode 100644
index 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 file
diff --git a/tools/mcp-server/CHANGELOG.md b/tools/mcp-server/CHANGELOG.md
new file mode 100644
index 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 file
diff --git a/tools/mcp-server/README.md b/tools/mcp-server/README.md
index 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:
```bash
cd tools/mcp-server && npm ci && npm test
diff --git a/tools/mcp-server/dist/index.js b/tools/mcp-server/dist/index.js
old mode 100644
new mode 100755
diff --git a/tools/mcp-server/package.json b/tools/mcp-server/package.json
index 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"