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.

fix: publish umbrella CLI as @cobusgreyling/loop-cli 0.1.1

Cobus Greyling5b152f819513
diff --git a/LOOP.md b/LOOP.md
index 8be21ea..a711122 100644
--- a/LOOP.md
+++ b/LOOP.md
@@ -72,7 +72,7 @@ See [docs/multi-loop.md](docs/multi-loop.md). Priority: CI Sweeper → PR Babysi
node tools/loop/dist/cli.js doctor .
node tools/loop/dist/cli.js status .
node tools/loop-audit/dist/cli.js . --suggest
-npx @cobusgreyling/loop init . --pattern daily-triage --tool grok # after npm publish
+npx @cobusgreyling/loop-cli init . --pattern daily-triage --tool grok # after npm publish
# same as: npx @cobusgreyling/loop-init . --pattern daily-triage --tool grok
bash scripts/before-after-demo.sh
```
diff --git a/README.md b/README.md
index cf4012b..7f75c03 100644
--- a/README.md
+++ b/README.md
@@ -10,7 +10,7 @@
<p align="center">
<a href="https://github.com/cobusgreyling/loop-engineering/stargazers"><img src="https://img.shields.io/github/stars/cobusgreyling/loop-engineering?style=social" alt="GitHub stars"></a>
<a href="https://github.com/cobusgreyling/loop-engineering/actions/workflows/audit.yml"><img src="https://img.shields.io/github/actions/workflow/status/cobusgreyling/loop-engineering/audit.yml?label=loop-audit%20dogfood" alt="loop-audit dogfood"></a>
- <a href="https://www.npmjs.com/package/@cobusgreyling/loop"><img src="https://img.shields.io/npm/v/@cobusgreyling/loop?label=loop" alt="loop npm"></a>
+ <a href="https://www.npmjs.com/package/@cobusgreyling/loop-cli"><img src="https://img.shields.io/npm/v/@cobusgreyling/loop-cli?label=loop" alt="loop npm"></a>
<a href="https://www.npmjs.com/package/@cobusgreyling/loop-audit"><img src="https://img.shields.io/npm/v/@cobusgreyling/loop-audit?label=loop-audit" alt="loop-audit npm"></a>
<a href="https://www.npmjs.com/package/@cobusgreyling/loop-init"><img src="https://img.shields.io/npm/v/@cobusgreyling/loop-init?label=loop-init" alt="loop-init npm"></a>
<a href="https://www.npmjs.com/package/@cobusgreyling/loop-cost"><img src="https://img.shields.io/npm/v/@cobusgreyling/loop-cost?label=loop-cost" alt="loop-cost npm"></a>
@@ -37,13 +37,13 @@
```bash
# Front door (recommended) — one binary for init + doctor + status
-npx @cobusgreyling/loop init . --pattern daily-triage --tool grok
-npx @cobusgreyling/loop doctor .
+npx @cobusgreyling/loop-cli init . --pattern daily-triage --tool grok
+npx @cobusgreyling/loop-cli doctor .
# Same as before (still fully supported — forks need not change)
npx @cobusgreyling/loop-init .
# Optional: also scaffold a versioned harness (harness-foundry)
-npx @cobusgreyling/loop init . --with-foundry
+npx @cobusgreyling/loop-cli init . --with-foundry
```
`loop init` (or `loop-init`) scaffolds skills, state, and budget files, then prints your **Loop Ready** score and first loop command. `loop doctor` combines audit + sync + file checks into top-3 next actions. Swap `--tool` for `claude`, `codex`, or `opencode`. Use `--with-foundry` when you want the loop as a composable runtime stack. See [docs/cli-front-door.md](docs/cli-front-door.md).
@@ -88,7 +88,7 @@ For developers using Grok, Claude Code, Codex, Cursor, and other AI coding agent
| Start here | Description |
|------------|-------------|
| [Quickstart (5 min)](docs/QUICKSTART.md) | `loop init` → `loop doctor` → first loop — **start here if you just landed** |
-| [CLI front door](docs/cli-front-door.md) | Unified `@cobusgreyling/loop` — old packages stay open |
+| [CLI front door](docs/cli-front-door.md) | Unified `@cobusgreyling/loop-cli` — old packages stay open |
| [Loop Engineering essay](https://cobusgreyling.substack.com/p/loop-engineering) | The concept, primitives, and Grok mapping — read for the why |
| [Pattern Picker](docs/pattern-picker.md) | Which loop to run first — **start here if unsure** |
| [Primitives Matrix](docs/primitives-matrix.md) | Cross-tool loop primitive mapping — bookmark this |
@@ -96,9 +96,9 @@ For developers using Grok, Claude Code, Codex, Cursor, and other AI coding agent
| [Patterns](patterns/README.md) | 7 production patterns + [interactive picker](https://cobusgreyling.github.io/loop-engineering/#interactive) |
| [Starters](starters/) | Clone-and-run kits (Grok, Claude Code, Codex, Opencode) |
| [Opencode examples](examples/opencode/) | CLI-first loops: cron/systemd + `opencode run`, skills, worktrees |
-| [**loop** (front door)](tools/loop/) | **Unified CLI** — `npx @cobusgreyling/loop init \| doctor \| status \| audit \| cost` · [cli-front-door](docs/cli-front-door.md) |
-| [loop-audit](tools/loop-audit/) | Loop Readiness Score CLI (v1.7 — constraints + governance + **Harness Runtime**) — `npx @cobusgreyling/loop audit . --suggest` · also `loop-audit` |
-| [loop-init](tools/loop-init/) | Scaffold starters + budget/run-log + constraints (v1.5) — `npx @cobusgreyling/loop init . --pattern daily-triage --tool grok` · also `loop-init` |
+| [**loop** (front door)](tools/loop/) | **Unified CLI** — `npx @cobusgreyling/loop-cli init \| doctor \| status \| audit \| cost` · [cli-front-door](docs/cli-front-door.md) |
+| [loop-audit](tools/loop-audit/) | Loop Readiness Score CLI (v1.7 — constraints + governance + **Harness Runtime**) — `npx @cobusgreyling/loop-cli audit . --suggest` · also `loop-audit` |
+| [loop-init](tools/loop-init/) | Scaffold starters + budget/run-log + constraints (v1.5) — `npx @cobusgreyling/loop-cli init . --pattern daily-triage --tool grok` · also `loop-init` |
| [harness-foundry](https://github.com/cobusgreyling/harness-foundry) | **Companion runtime:** versioned stacks, sessions, traces — `npx @cobusgreyling/harness-foundry init --from loop-engineering:daily-triage` |
| [outerloop](https://github.com/cobusgreyling/outerloop) | **Companion governance:** evidence → verdict → answerability |
| [loop-cost](tools/loop-cost/) | Token spend estimator — `npx @cobusgreyling/loop-cost` |
@@ -122,8 +122,8 @@ memory-engineering → loop-engineering → harness-foundry → outerloop → fl
| Layer | You get | Start |
|-------|---------|--------|
| **Memory** | Tiers, recall budget, Memory Ready score | [memory-engineering](https://github.com/cobusgreyling/memory-engineering) |
-| **Design** (this repo) | Patterns, starters, Loop Ready score | `npx @cobusgreyling/loop init .` then `loop doctor .` |
-| **Runtime** | Versioned harness, traces, evolve | `npx @cobusgreyling/loop init . --with-foundry` or [Foundry showcase](https://github.com/cobusgreyling/harness-foundry/blob/main/docs/showcase.md) |
+| **Design** (this repo) | Patterns, starters, Loop Ready score | `npx @cobusgreyling/loop-cli init .` then `loop doctor .` |
+| **Runtime** | Versioned harness, traces, evolve | `npx @cobusgreyling/loop-cli init . --with-foundry` or [Foundry showcase](https://github.com/cobusgreyling/harness-foundry/blob/main/docs/showcase.md) |
| **Govern** | Evidence, verdict, answerability | [outerloop](https://github.com/cobusgreyling/outerloop) |
| **Fleet** | Registry, inbox, budgets, kill switch | `npx @cobusgreyling/fleet-init .` · [Fleet Ready](https://github.com/cobusgreyling/fleet-engineering/blob/main/docs/fleet-ready-score.md) |
@@ -225,15 +225,15 @@ Machine-readable index: [patterns/registry.yaml](patterns/registry.yaml) (7 patt
```bash
# 1. Scaffold + Loop Ready score (printed automatically)
-npx @cobusgreyling/loop init . --pattern daily-triage --tool grok
+npx @cobusgreyling/loop-cli init . --pattern daily-triage --tool grok
# 2. One health check (audit + sync + files → top 3 actions)
-npx @cobusgreyling/loop doctor .
+npx @cobusgreyling/loop-cli doctor .
# 3. Optional: cost estimate / badge / day-2 dashboard
-npx @cobusgreyling/loop cost --pattern daily-triage --level L1
-npx @cobusgreyling/loop badge .
-npx @cobusgreyling/loop status .
+npx @cobusgreyling/loop-cli cost --pattern daily-triage --level L1
+npx @cobusgreyling/loop-cli badge .
+npx @cobusgreyling/loop-cli status .
# 4. See scores climb: empty → L1 → L2
bash scripts/before-after-demo.sh
diff --git a/docs/QUICKSTART.md b/docs/QUICKSTART.md
index 4b6ccde..5564c5d 100644
--- a/docs/QUICKSTART.md
+++ b/docs/QUICKSTART.md
@@ -8,7 +8,7 @@ Landed from [X](https://x.com), the [showcase](https://cobusgreyling.github.io/l
**Week one rule:** report only. No auto-fix, no auto-merge. Read what the loop writes before you let it act.
-**Front door:** prefer the unified CLI (`@cobusgreyling/loop`). Dedicated packages (`loop-init`, `loop-audit`, …) stay fully supported — see [cli-front-door.md](./cli-front-door.md).
+**Front door:** prefer the unified CLI (`@cobusgreyling/loop-cli`). Dedicated packages (`loop-init`, `loop-audit`, …) stay fully supported — see [cli-front-door.md](./cli-front-door.md).
## 1. Pick your pain (30 seconds)
@@ -21,11 +21,11 @@ Or start with **Daily Triage** if you just want to learn loop discipline with lo
Run this in the root of any git project (no clone required):
```bash
-npx @cobusgreyling/loop init . --pattern daily-triage --tool grok
+npx @cobusgreyling/loop-cli init . --pattern daily-triage --tool grok
# One health check (audit + sync + top 3 actions):
-npx @cobusgreyling/loop doctor .
+npx @cobusgreyling/loop-cli doctor .
# Optional one-command funnel into harness-foundry:
-npx @cobusgreyling/loop init . --pattern daily-triage --tool grok --with-foundry
+npx @cobusgreyling/loop-cli init . --pattern daily-triage --tool grok --with-foundry
```
Equivalent (old door, still supported):
@@ -37,7 +37,7 @@ npx @cobusgreyling/loop-init . --pattern daily-triage --tool grok
Swap `--pattern` for any pattern from [patterns/registry.yaml](../patterns/registry.yaml). List all patterns:
```bash
-npx @cobusgreyling/loop init --help
+npx @cobusgreyling/loop-cli init --help
```
### Which `--tool` values work?
@@ -57,7 +57,7 @@ npx @cobusgreyling/loop init --help
## 3. Check cost before you schedule (30 seconds)
```bash
-npx @cobusgreyling/loop cost --pattern daily-triage --level L1 --cadence 1d
+npx @cobusgreyling/loop-cli cost --pattern daily-triage --level L1 --cadence 1d
# same as: npx @cobusgreyling/loop-cost --pattern daily-triage --level L1 --cadence 1d
```
@@ -68,7 +68,7 @@ Adjust `--pattern`, `--level` (L1 → L2 → L3), and `--cadence` to match what
When a loop starts fixing code unattended, wire a **circuit breaker** so it escalates instead of retrying the same failure forever. `loop-init` scaffolds `loop-ledger.json` and a `loop-guard` skill for fix-capable patterns; check the ledger before each retry:
```bash
-npx @cobusgreyling/loop context --check --ledger loop-ledger.json
+npx @cobusgreyling/loop-cli context --check --ledger loop-ledger.json
# same as: npx @cobusgreyling/loop-context --check --ledger loop-ledger.json
```
@@ -78,21 +78,21 @@ Exit `0` = continue · `2` = escalate to a human. The breaker trips on max itera
```bash
# Prefer doctor for day-to-day (includes audit + sync)
-npx @cobusgreyling/loop doctor .
+npx @cobusgreyling/loop-cli doctor .
# Or audit alone:
-npx @cobusgreyling/loop audit . --suggest
+npx @cobusgreyling/loop-cli audit . --suggest
```
Scores 0–100 with concrete next steps. Re-run after each improvement. Paste a badge when you're proud of the score:
```bash
-npx @cobusgreyling/loop badge .
+npx @cobusgreyling/loop-cli badge .
```
When the score is **≥ 80**, audit (and `loop init`) nudge you to version the loop as a [harness-foundry](https://github.com/cobusgreyling/harness-foundry) stack — declarative runtime, traces, outerloop emit:
```bash
-npx @cobusgreyling/loop init . --with-foundry
+npx @cobusgreyling/loop-cli init . --with-foundry
npx @cobusgreyling/harness-foundry validate
npx @cobusgreyling/harness-foundry run --goal "Verify harness wiring"
```
@@ -102,7 +102,7 @@ npx @cobusgreyling/harness-foundry run --goal "Verify harness wiring"
`loop audit` scores readiness; `loop sync` checks that your `STATE.md` and `LOOP.md` still agree. When they drift — you edit `LOOP.md` to add a loop but never wire it into `STATE.md`, or a starter update leaves one file behind — a scheduled loop can run against stale instructions. `loop doctor` runs this for you.
```bash
-npx @cobusgreyling/loop sync .
+npx @cobusgreyling/loop-cli sync .
# same as: npx @cobusgreyling/loop-sync .
```
diff --git a/docs/RELEASE.md b/docs/RELEASE.md
index 6650d26..29312aa 100644
--- a/docs/RELEASE.md
+++ b/docs/RELEASE.md
@@ -1,10 +1,10 @@
# Release playbook — npm packages
-This repo ships public npm packages from `tools/`. **Front door for users:** `@cobusgreyling/loop` ([cli-front-door.md](./cli-front-door.md)). Sibling packages stay published and supported.
+This repo ships public npm packages from `tools/`. **Front door for users:** `@cobusgreyling/loop-cli` ([cli-front-door.md](./cli-front-door.md)). Sibling packages stay published and supported.
| Package | Directory | Release tag |
|---------|-----------|-------------|
-| `@cobusgreyling/loop` | `tools/loop` | `loop-v*` |
+| `@cobusgreyling/loop-cli` | `tools/loop` | `loop-v*` |
| `@cobusgreyling/readiness-core` | `tools/readiness-core` | `readiness-core-v*` |
| `@cobusgreyling/loop-audit` | `tools/loop-audit` | `loop-audit-v*` |
| `@cobusgreyling/loop-init` | `tools/loop-init` | `loop-init-v*` |
@@ -23,7 +23,7 @@ Link npm to GitHub, then for **each package** on [npmjs.com](https://www.npmjs.c
| Package | Repository | Workflow filename |
|---------|--------------|-------------------|
-| `@cobusgreyling/loop` | `cobusgreyling/loop-engineering` | `release-loop.yml` |
+| `@cobusgreyling/loop-cli` | `cobusgreyling/loop-engineering` | `release-loop.yml` |
| `@cobusgreyling/readiness-core` | `cobusgreyling/loop-engineering` | `release-readiness-core.yml` |
| `@cobusgreyling/loop-audit` | `cobusgreyling/loop-engineering` | `release-loop-audit.yml` |
| `@cobusgreyling/loop-init` | `cobusgreyling/loop-engineering` | `release-loop-init.yml` |
diff --git a/docs/cli-front-door.md b/docs/cli-front-door.md
index c153da8..6a08b9d 100644
--- a/docs/cli-front-door.md
+++ b/docs/cli-front-door.md
@@ -1,4 +1,4 @@
-# CLI front door — `@cobusgreyling/loop`
+# CLI front door — `@cobusgreyling/loop-cli`
> **Additive.** Old packages stay fully supported. This is the recommended entry for new users, forks, and agents.
@@ -6,15 +6,15 @@
Loop Engineering ships several focused CLIs (`loop-init`, `loop-audit`, `loop-cost`, …). That is great for maintainers; it is hard for first-time adopters to remember.
-`@cobusgreyling/loop` is a **thin umbrella**:
+`@cobusgreyling/loop-cli` is a **thin umbrella**:
1. One binary people can remember
2. **Pass-through** to existing tools (same flags)
3. **doctor** / **status** for activation and day-2 habit
```text
-npx @cobusgreyling/loop init . -p daily-triage -t grok
-npx @cobusgreyling/loop doctor .
+npx @cobusgreyling/loop-cli init . -p daily-triage -t grok
+npx @cobusgreyling/loop-cli doctor .
```
## Map (new → same as before)
@@ -42,7 +42,7 @@ npx @cobusgreyling/loop doctor .
| 2 | Blocked | hard-fail if you require scaffold |
```bash
-npx @cobusgreyling/loop doctor . --json
+npx @cobusgreyling/loop-cli doctor . --json
```
## Forks & contributors
diff --git a/docs/index.html b/docs/index.html
index be564d1..b2077a3 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -78,7 +78,7 @@ title: Loop Engineering — Showcase
<div class="badge">Open source · Tool-agnostic · Production-ready · L3 dogfood · 7 patterns · Interactive tools</div>
<h1>Stop prompting.<br>Design the loop.<br>Get a score.</h1>
<p class="lead">
- Run one command in any repo. <code>@cobusgreyling/loop</code> is the front door (<code>init</code> + <code>doctor</code>). <code>loop-init</code> still works. Prints your <strong>Loop Ready</strong> score plus the first run line.
+ Run one command in any repo. <code>@cobusgreyling/loop-cli</code> is the front door (<code>init</code> + <code>doctor</code>). <code>loop-init</code> still works. Prints your <strong>Loop Ready</strong> score plus the first run line.
</p>
<div class="code-block" style="max-width:720px;margin:0 auto 24px;">
<div class="code-header">
@@ -86,8 +86,8 @@ title: Loop Engineering — Showcase
<span>terminal — try now</span>
<button onclick="copyNpxInit()" class="copy-btn">Copy</button>
</div>
- <pre>npx @cobusgreyling/loop init .
-npx @cobusgreyling/loop doctor .</pre>
+ <pre>npx @cobusgreyling/loop-cli init .
+npx @cobusgreyling/loop-cli doctor .</pre>
</div>
<div class="hero-cta">
<a href="#start" class="btn btn-primary">Try in 60 seconds →</a>
@@ -463,7 +463,7 @@ flowchart TB
<span>terminal — minimal loop</span>
</div>
<pre><span class="comment"># Scaffold starter (or copy manually)</span>
-npx @cobusgreyling/loop init . --pattern daily-triage --tool grok
+npx @cobusgreyling/loop-cli init . --pattern daily-triage --tool grok
<span class="comment"># Score loop readiness (PRs get audit comments in CI)</span>
npx @cobusgreyling/loop-audit . --suggest
@@ -706,7 +706,7 @@ npx @cobusgreyling/loop-audit . --suggest
<script>
// Copy helpers for hero
function copyNpxInit() {
- const txt = 'npx @cobusgreyling/loop init .';
+ const txt = 'npx @cobusgreyling/loop-cli init .';
navigator.clipboard.writeText(txt).then(() => {
const b = event.currentTarget; // best effort
});
@@ -819,7 +819,7 @@ const PATTERNS = {
patternId: 'ci-sweeper',
costLevel: 'L2',
costCadence: '15m',
- npx: 'npx @cobusgreyling/loop init . --pattern ci-sweeper --tool grok',
+ npx: 'npx @cobusgreyling/loop-cli init . --pattern ci-sweeper --tool grok',
loop: '/loop 15m Run ci-triage on failing CI. Update ci-sweeper-state.md. Fix only regressions in worktree. Max 3 attempts.',
patternHref: 'https://github.com/cobusgreyling/loop-engineering/blob/main/patterns/ci-sweeper.md',
starterHref: 'https://github.com/cobusgreyling/loop-engineering/tree/main/starters/ci-sweeper'
@@ -830,7 +830,7 @@ const PATTERNS = {
patternId: 'pr-babysitter',
costLevel: 'L1',
costCadence: '10m',
- npx: 'npx @cobusgreyling/loop init . --pattern pr-babysitter --tool grok',
+ npx: 'npx @cobusgreyling/loop-cli init . --pattern pr-babysitter --tool grok',
loop: '/loop 10m Run pr-review-triage. Update pr-babysitter-state.md. Worktree + verifier. No auto-merge by default.',
patternHref: 'https://github.com/cobusgreyling/loop-engineering/blob/main/patterns/pr-babysitter.md',
starterHref: 'https://github.com/cobusgreyling/loop-engineering/tree/main/starters/pr-babysitter'
@@ -841,7 +841,7 @@ const PATTERNS = {
patternId: 'daily-triage',
costLevel: 'L1',
costCadence: '1d',
- npx: 'npx @cobusgreyling/loop init . --pattern daily-triage --tool grok',
+ npx: 'npx @cobusgreyling/loop-cli init . --pattern daily-triage --tool grok',
loop: '/loop 1d Run loop-triage. Update STATE.md. No auto-fix in week one.',
patternHref: 'https://github.com/cobusgreyling/loop-engineering/blob/main/patterns/daily-triage.md',
starterHref: 'https://github.com/cobusgreyling/loop-engineering/tree/main/starters/minimal-loop'
@@ -852,7 +852,7 @@ const PATTERNS = {
patternId: 'dependency-sweeper',
costLevel: 'L2',
costCadence: '6h',
- npx: 'npx @cobusgreyling/loop init . --pattern dependency-sweeper --tool grok',
+ npx: 'npx @cobusgreyling/loop-cli init . --pattern dependency-sweeper --tool grok',
loop: '/loop 6h Run dependency-triage. Patch-only auto-fix in worktree + verifier. Escalate majors.',
patternHref: 'https://github.com/cobusgreyling/loop-engineering/blob/main/patterns/dependency-sweeper.md',
starterHref: 'https://github.com/cobusgreyling/loop-engineering/tree/main/starters/dependency-sweeper'
@@ -863,7 +863,7 @@ const PATTERNS = {
patternId: 'post-merge-cleanup',
costLevel: 'L1',
costCadence: '1d',
- npx: 'npx @cobusgreyling/loop init . --pattern post-merge-cleanup --tool grok',
+ npx: 'npx @cobusgreyling/loop-cli init . --pattern post-merge-cleanup --tool grok',
loop: '/loop 1d Run post-merge-scan on recent merges. Update post-merge-state.md. Small fixes only.',
patternHref: 'https://github.com/cobusgreyling/loop-engineering/blob/main/patterns/post-merge-cleanup.md',
starterHref: 'https://github.com/cobusgreyling/loop-engineering/tree/main/starters/post-merge-cleanup'
@@ -874,7 +874,7 @@ const PATTERNS = {
patternId: 'changelog-drafter',
costLevel: 'L1',
costCadence: '1d',
- npx: 'npx @cobusgreyling/loop init . --pattern changelog-drafter --tool grok',
+ npx: 'npx @cobusgreyling/loop-cli init . --pattern changelog-drafter --tool grok',
loop: '/loop 1d Run changelog-scan + draft-release-notes. Write RELEASE_NOTES_DRAFT.md. Human review only.',
patternHref: 'https://github.com/cobusgreyling/loop-engineering/blob/main/patterns/changelog-drafter.md',
starterHref: 'https://github.com/cobusgreyling/loop-engineering/tree/main/starters/changelog-drafter'
@@ -885,7 +885,7 @@ const PATTERNS = {
patternId: 'issue-triage',
costLevel: 'L1',
costCadence: '1d',
- npx: 'npx @cobusgreyling/loop init . --pattern issue-triage --tool grok',
+ npx: 'npx @cobusgreyling/loop-cli init . --pattern issue-triage --tool grok',
loop: '/loop 1d Run issue-triage. Update issue-triage-state.md. Propose labels and priorities only — no auto-close.',
patternHref: 'https://github.com/cobusgreyling/loop-engineering/blob/main/patterns/issue-triage.md',
starterHref: 'https://github.com/cobusgreyling/loop-engineering/tree/main/starters/issue-triage'
@@ -992,7 +992,7 @@ function setupSimulator() {
} else if (score >= 78 && hasVerifier && hasState && !costReady) {
level = 'L2';
assess = 'Strong signals but missing cost observability — add budget + run log before L3.';
- reco = 'npx @cobusgreyling/loop init . --pattern daily-triage --tool grok (scaffolds loop-budget.md + loop-run-log.md)';
+ reco = 'npx @cobusgreyling/loop-cli init . --pattern daily-triage --tool grok (scaffolds loop-budget.md + loop-run-log.md)';
} else if (score >= 78 && hasVerifier && hasState && costReady && !hasActivity) {
level = 'L2';
assess = 'Strong structure but no proven loop runs yet.';
@@ -1008,7 +1008,7 @@ function setupSimulator() {
} else {
level = 'L0';
assess = 'Not loop-ready — start with a starter from this repo (minimal-loop or pr-babysitter).';
- reco = 'npx @cobusgreyling/loop init . --pattern daily-triage --tool grok';
+ reco = 'npx @cobusgreyling/loop-cli init . --pattern daily-triage --tool grok';
}
scoreEl.textContent = score;
diff --git a/skills/install-loop/SKILL.md b/skills/install-loop/SKILL.md
index 16653b5..f933079 100644
--- a/skills/install-loop/SKILL.md
+++ b/skills/install-loop/SKILL.md
@@ -2,7 +2,7 @@
name: install-loop
description: >
Install Loop Engineering into a project via the unified CLI front door
- (@cobusgreyling/loop). Prefer this over invoking loop-init / loop-audit
+ (@cobusgreyling/loop-cli). Prefer this over invoking loop-init / loop-audit
separately. Week-one is report-only; never enable auto-merge or unattended
fixes unless the human explicitly asks and doctor is healthy.
---
@@ -14,7 +14,7 @@ description: >
Leave the repo with a scaffolded **report-only** loop, a **Loop Ready** score, and clear next actions — using the **single** CLI:
```bash
-npx @cobusgreyling/loop
+npx @cobusgreyling/loop-cli
```
Do **not** deprecate or remove existing `loop-init` / `loop-audit` usages you find; both doors stay valid. Prefer `loop` for new work.
@@ -24,8 +24,8 @@ Do **not** deprecate or remove existing `loop-init` / `loop-audit` usages you fi
1. **Detect context**
- If `LOOP.md` or `STATE.md` already exists, run doctor only (skip init unless human asks to re-scaffold):
```bash
- npx @cobusgreyling/loop doctor . --json
- npx @cobusgreyling/loop status .
+ npx @cobusgreyling/loop-cli doctor . --json
+ npx @cobusgreyling/loop-cli status .
```
- Otherwise continue.
@@ -44,26 +44,26 @@ Do **not** deprecate or remove existing `loop-init` / `loop-audit` usages you fi
4. **Scaffold**
```bash
- npx @cobusgreyling/loop init . --pattern <pattern> --tool <tool>
+ npx @cobusgreyling/loop-cli init . --pattern <pattern> --tool <tool>
```
Optional harness (only if human wants Foundry): add `--with-foundry`.
5. **Doctor**
```bash
- npx @cobusgreyling/loop doctor .
+ npx @cobusgreyling/loop-cli doctor .
```
- Exit `0` = healthy · `1` = warnings · `2` = blocked
- Follow the **top 3** printed actions; do not invent extra architecture.
6. **Cost check** before high-cadence schedules:
```bash
- npx @cobusgreyling/loop cost -p <pattern> -l L1 -c 1d
+ npx @cobusgreyling/loop-cli cost -p <pattern> -l L1 -c 1d
```
7. **Week-one rule**
- Report only. No auto-fix, no auto-merge.
- Tell the human the first `/loop` or scheduler command from init output.
- - Suggest badge only when score is strong: `npx @cobusgreyling/loop badge .`
+ - Suggest badge only when score is strong: `npx @cobusgreyling/loop-cli badge .`
## Compatibility
diff --git a/tools/loop/CHANGELOG.md b/tools/loop/CHANGELOG.md
index 689d615..d7bbfae 100644
--- a/tools/loop/CHANGELOG.md
+++ b/tools/loop/CHANGELOG.md
@@ -1,9 +1,13 @@
# Changelog
+## 0.1.1
+
+- Package name: `@cobusgreyling/loop-cli` (npm-safe; bin `loop-cli`)
+- Fix bin field so `npx @cobusgreyling/loop-cli` installs a runnable CLI
+- `main` entry for tooling
+
## 0.1.0
-- Initial unified CLI front door: `init`, `audit`, `cost`, `sync`, `context`, `worktree`, `gate`, `mcp`, `sandbox` pass-through
-- `doctor` — audit + sync + structural checks, top 3 actions, exit 0/1/2, `--json`
-- `status` — day-2 dashboard from STATE / LOOP / run-log / ledger
-- `badge` — alias for `loop-audit --badge`
-- `wizard` / bare help — week-one path without removing old packages
+- Initial unified CLI front door (published under provisional name; superseded by 0.1.1 naming)
+- Pass-through: init, audit, cost, sync, context, worktree, gate, mcp, sandbox
+- `doctor` / `status` / `badge` / `wizard`
diff --git a/tools/loop/README.md b/tools/loop/README.md
index 8243f8d..ba06029 100644
--- a/tools/loop/README.md
+++ b/tools/loop/README.md
@@ -1,10 +1,10 @@
-# @cobusgreyling/loop
+# @cobusgreyling/loop-cli
**Unified front door** for [Loop Engineering](https://github.com/cobusgreyling/loop-engineering) CLIs.
```bash
-npx @cobusgreyling/loop init . --pattern daily-triage --tool grok
-npx @cobusgreyling/loop doctor .
+npx @cobusgreyling/loop-cli init . --pattern daily-triage --tool grok
+npx @cobusgreyling/loop-cli doctor .
```
This package does **not** replace `loop-init`, `loop-audit`, or the other tools. It wraps them and adds **doctor** + **status** so week-one activation is one mental model.
@@ -28,16 +28,16 @@ This package does **not** replace `loop-init`, `loop-audit`, or the other tools.
```bash
# 1. Scaffold (report-only)
-npx @cobusgreyling/loop init . --pattern daily-triage --tool grok
+npx @cobusgreyling/loop-cli init . --pattern daily-triage --tool grok
# 2. One health check
-npx @cobusgreyling/loop doctor .
+npx @cobusgreyling/loop-cli doctor .
# 3. Optional cost estimate
-npx @cobusgreyling/loop cost -p daily-triage -l L1 -c 1d
+npx @cobusgreyling/loop-cli cost -p daily-triage -l L1 -c 1d
# 4. Day-2 dashboard
-npx @cobusgreyling/loop status .
+npx @cobusgreyling/loop-cli status .
```
### Doctor exit codes
@@ -49,8 +49,8 @@ npx @cobusgreyling/loop status .
| `2` | Blocked (score &lt; 40, critical drift, or not scaffolded) |
```bash
-npx @cobusgreyling/loop doctor . --json
-npx @cobusgreyling/loop status . --json
+npx @cobusgreyling/loop-cli doctor . --json
+npx @cobusgreyling/loop-cli status . --json
```
## Compatibility (old doors stay open)
diff --git a/tools/loop/dist/cli.js b/tools/loop/dist/cli.js
index a918728..690808f 100755
--- a/tools/loop/dist/cli.js
+++ b/tools/loop/dist/cli.js
@@ -1,13 +1,13 @@
#!/usr/bin/env node
/**
- * @cobusgreyling/loop — unified front door for Loop Engineering CLIs.
+ * @cobusgreyling/loop-cli — unified front door for Loop Engineering CLIs.
* Additive: loop-init, loop-audit, and siblings stay fully supported.
*/
import { runTool } from './pass-through.js';
import { runDoctor, formatDoctorHuman } from './doctor.js';
import { runStatus, formatStatusHuman } from './status.js';
import { defaultPlan, executePlan, printNonInteractiveHelp, resolvePattern, resolveTool, runInteractiveWizard, } from './wizard.js';
-const VERSION = '0.1.0';
+const VERSION = '0.1.1';
const PASS_THROUGH = new Set([
'init',
'audit',
@@ -35,8 +35,8 @@ Usage:
loop context|worktree|gate|mcp|sandbox [args…]
Week-one (recommended):
- npx @cobusgreyling/loop init . --pattern daily-triage --tool grok
- npx @cobusgreyling/loop doctor .
+ npx @cobusgreyling/loop-cli init . --pattern daily-triage --tool grok
+ npx @cobusgreyling/loop-cli doctor .
Doctor exit codes:
0 healthy
diff --git a/tools/loop/dist/doctor.js b/tools/loop/dist/doctor.js
index e26ca13..62839f9 100644
--- a/tools/loop/dist/doctor.js
+++ b/tools/loop/dist/doctor.js
@@ -88,14 +88,14 @@ export async function runDoctor(target) {
actions.push({
priority: 1,
text: 'Scaffold a first loop (report-only week one)',
- command: 'npx @cobusgreyling/loop init . --pattern daily-triage --tool grok',
+ command: 'npx @cobusgreyling/loop-cli init . --pattern daily-triage --tool grok',
});
}
else if (!stateName) {
actions.push({
priority: 2,
text: 'Add a state file (STATE.md or pattern state)',
- command: 'npx @cobusgreyling/loop init . --pattern daily-triage --tool grok',
+ command: 'npx @cobusgreyling/loop-cli init . --pattern daily-triage --tool grok',
});
}
if (!loopMd) {
@@ -108,7 +108,7 @@ export async function runDoctor(target) {
actions.push({
priority: 10,
text: 'Add loop-budget.md with daily token caps and kill switch',
- command: 'npx @cobusgreyling/loop init . --pattern daily-triage --tool grok',
+ command: 'npx @cobusgreyling/loop-cli init . --pattern daily-triage --tool grok',
});
}
if (!runLog) {
@@ -121,14 +121,14 @@ export async function runDoctor(target) {
actions.push({
priority: 5,
text: 'Raise Loop Ready above 40 before scheduling unattended work',
- command: `npx @cobusgreyling/loop audit ${target} --suggest`,
+ command: `npx @cobusgreyling/loop-cli audit ${target} --suggest`,
});
}
if (syncLevel === 'critical') {
actions.push({
priority: 4,
text: 'Fix STATE ↔ LOOP drift before the next scheduled run',
- command: `npx @cobusgreyling/loop sync ${target}`,
+ command: `npx @cobusgreyling/loop-cli sync ${target}`,
});
}
for (const rec of auditRecs.slice(0, 3)) {
@@ -138,12 +138,12 @@ export async function runDoctor(target) {
actions.push({
priority: 90,
text: 'Optional next: version the loop as a harness (Foundry)',
- command: 'npx @cobusgreyling/loop init . --with-foundry',
+ command: 'npx @cobusgreyling/loop-cli init . --with-foundry',
});
actions.push({
priority: 91,
text: 'Share your score',
- command: `npx @cobusgreyling/loop badge ${target}`,
+ command: `npx @cobusgreyling/loop-cli badge ${target}`,
});
}
// Dedupe by text, keep best priority
diff --git a/tools/loop/dist/status.js b/tools/loop/dist/status.js
index 12aab47..a709827 100644
--- a/tools/loop/dist/status.js
+++ b/tools/loop/dist/status.js
@@ -51,15 +51,15 @@ export async function runStatus(target) {
if (recentRuns[0]?.pattern && !patterns.includes(recentRuns[0].pattern)) {
patterns.unshift(recentRuns[0].pattern);
}
- let nextHint = 'Run: npx @cobusgreyling/loop doctor .';
+ let nextHint = 'Run: npx @cobusgreyling/loop-cli doctor .';
if (!stateName && !loopRaw) {
- nextHint = 'Scaffold: npx @cobusgreyling/loop init . --pattern daily-triage --tool grok';
+ nextHint = 'Scaffold: npx @cobusgreyling/loop-cli init . --pattern daily-triage --tool grok';
}
else if (recentRuns.length === 0) {
nextHint = 'Schedule a report-only first run and append loop-run-log.md';
}
else if (readyScore !== null && readyScore >= 80) {
- nextHint = 'Optional: npx @cobusgreyling/loop badge . · harness: loop init . --with-foundry';
+ nextHint = 'Optional: npx @cobusgreyling/loop-cli badge . · harness: loop init . --with-foundry';
}
return {
target: root,
diff --git a/tools/loop/dist/wizard.js b/tools/loop/dist/wizard.js
index b31c503..85aa4d3 100644
--- a/tools/loop/dist/wizard.js
+++ b/tools/loop/dist/wizard.js
@@ -88,12 +88,12 @@ export function printNonInteractiveHelp() {
console.log(formatWizardBanner());
console.log(`Week-one path (copy/paste):
- npx @cobusgreyling/loop init . --pattern daily-triage --tool grok
- npx @cobusgreyling/loop doctor .
+ npx @cobusgreyling/loop-cli init . --pattern daily-triage --tool grok
+ npx @cobusgreyling/loop-cli doctor .
Or pick a pain point, then scaffold:
-${PAIN_OPTIONS.map((p) => ` ${p.id}. ${p.label}\n npx @cobusgreyling/loop init . -p ${p.pattern} -t grok`).join('\n\n')}
+${PAIN_OPTIONS.map((p) => ` ${p.id}. ${p.label}\n npx @cobusgreyling/loop-cli init . -p ${p.pattern} -t grok`).join('\n\n')}
Commands:
loop init|audit|cost|sync|doctor|status|badge|wizard
diff --git a/tools/loop/package.json b/tools/loop/package.json
index 88b8988..3df8191 100644
--- a/tools/loop/package.json
+++ b/tools/loop/package.json
@@ -1,10 +1,10 @@
{
- "name": "@cobusgreyling/loop",
- "version": "0.1.0",
- "description": "Unified Loop Engineering CLI — one front door for init, audit, cost, sync, doctor, and status. Existing packages stay supported. npx @cobusgreyling/loop doctor .",
+ "name": "@cobusgreyling/loop-cli",
+ "version": "0.1.1",
+ "description": "Unified Loop Engineering CLI front door \u2014 init, audit, cost, sync, doctor, status. Existing packages stay supported. npx @cobusgreyling/loop-cli doctor .",
"type": "module",
"bin": {
- "loop": "./dist/cli.js"
+ "loop-cli": "dist/cli.js"
},
"files": [
"dist",
@@ -48,5 +48,6 @@
"devDependencies": {
"@types/node": "^22.0.0",
"typescript": "^5.9.3"
- }
+ },
+ "main": "dist/cli.js"
}
diff --git a/tools/loop/src/cli.ts b/tools/loop/src/cli.ts
index ca3ccf2..e0206f2 100644
--- a/tools/loop/src/cli.ts
+++ b/tools/loop/src/cli.ts
@@ -1,6 +1,6 @@
#!/usr/bin/env node
/**
- * @cobusgreyling/loop — unified front door for Loop Engineering CLIs.
+ * @cobusgreyling/loop-cli — unified front door for Loop Engineering CLIs.
* Additive: loop-init, loop-audit, and siblings stay fully supported.
*/
import { runTool } from './pass-through.js';
@@ -16,7 +16,7 @@ import {
type WizardPlan,
} from './wizard.js';
-const VERSION = '0.1.0';
+const VERSION = '0.1.1';
const PASS_THROUGH = new Set([
'init',
@@ -46,8 +46,8 @@ Usage:
loop context|worktree|gate|mcp|sandbox [args…]
Week-one (recommended):
- npx @cobusgreyling/loop init . --pattern daily-triage --tool grok
- npx @cobusgreyling/loop doctor .
+ npx @cobusgreyling/loop-cli init . --pattern daily-triage --tool grok
+ npx @cobusgreyling/loop-cli doctor .
Doctor exit codes:
0 healthy
diff --git a/tools/loop/src/doctor.ts b/tools/loop/src/doctor.ts
index eb2e276..b19d143 100644
--- a/tools/loop/src/doctor.ts
+++ b/tools/loop/src/doctor.ts
@@ -138,13 +138,13 @@ export async function runDoctor(target: string): Promise<DoctorReport> {
actions.push({
priority: 1,
text: 'Scaffold a first loop (report-only week one)',
- command: 'npx @cobusgreyling/loop init . --pattern daily-triage --tool grok',
+ command: 'npx @cobusgreyling/loop-cli init . --pattern daily-triage --tool grok',
});
} else if (!stateName) {
actions.push({
priority: 2,
text: 'Add a state file (STATE.md or pattern state)',
- command: 'npx @cobusgreyling/loop init . --pattern daily-triage --tool grok',
+ command: 'npx @cobusgreyling/loop-cli init . --pattern daily-triage --tool grok',
});
}
if (!loopMd) {
@@ -157,7 +157,7 @@ export async function runDoctor(target: string): Promise<DoctorReport> {
actions.push({
priority: 10,
text: 'Add loop-budget.md with daily token caps and kill switch',
- command: 'npx @cobusgreyling/loop init . --pattern daily-triage --tool grok',
+ command: 'npx @cobusgreyling/loop-cli init . --pattern daily-triage --tool grok',
});
}
if (!runLog) {
@@ -170,14 +170,14 @@ export async function runDoctor(target: string): Promise<DoctorReport> {
actions.push({
priority: 5,
text: 'Raise Loop Ready above 40 before scheduling unattended work',
- command: `npx @cobusgreyling/loop audit ${target} --suggest`,
+ command: `npx @cobusgreyling/loop-cli audit ${target} --suggest`,
});
}
if (syncLevel === 'critical') {
actions.push({
priority: 4,
text: 'Fix STATE ↔ LOOP drift before the next scheduled run',
- command: `npx @cobusgreyling/loop sync ${target}`,
+ command: `npx @cobusgreyling/loop-cli sync ${target}`,
});
}
for (const rec of auditRecs.slice(0, 3)) {
@@ -187,12 +187,12 @@ export async function runDoctor(target: string): Promise<DoctorReport> {
actions.push({
priority: 90,
text: 'Optional next: version the loop as a harness (Foundry)',
- command: 'npx @cobusgreyling/loop init . --with-foundry',
+ command: 'npx @cobusgreyling/loop-cli init . --with-foundry',
});
actions.push({
priority: 91,
text: 'Share your score',
- command: `npx @cobusgreyling/loop badge ${target}`,
+ command: `npx @cobusgreyling/loop-cli badge ${target}`,
});
}
diff --git a/tools/loop/src/status.ts b/tools/loop/src/status.ts
index 3228228..1ea9850 100644
--- a/tools/loop/src/status.ts
+++ b/tools/loop/src/status.ts
@@ -75,13 +75,13 @@ export async function runStatus(target: string): Promise<StatusReport> {
patterns.unshift(recentRuns[0].pattern);
}
- let nextHint = 'Run: npx @cobusgreyling/loop doctor .';
+ let nextHint = 'Run: npx @cobusgreyling/loop-cli doctor .';
if (!stateName && !loopRaw) {
- nextHint = 'Scaffold: npx @cobusgreyling/loop init . --pattern daily-triage --tool grok';
+ nextHint = 'Scaffold: npx @cobusgreyling/loop-cli init . --pattern daily-triage --tool grok';
} else if (recentRuns.length === 0) {
nextHint = 'Schedule a report-only first run and append loop-run-log.md';
} else if (readyScore !== null && readyScore >= 80) {
- nextHint = 'Optional: npx @cobusgreyling/loop badge . · harness: loop init . --with-foundry';
+ nextHint = 'Optional: npx @cobusgreyling/loop-cli badge . · harness: loop init . --with-foundry';
}
return {
diff --git a/tools/loop/src/wizard.ts b/tools/loop/src/wizard.ts
index d23eb0e..51150a4 100644
--- a/tools/loop/src/wizard.ts
+++ b/tools/loop/src/wizard.ts
@@ -108,12 +108,12 @@ export function printNonInteractiveHelp(): void {
console.log(formatWizardBanner());
console.log(`Week-one path (copy/paste):
- npx @cobusgreyling/loop init . --pattern daily-triage --tool grok
- npx @cobusgreyling/loop doctor .
+ npx @cobusgreyling/loop-cli init . --pattern daily-triage --tool grok
+ npx @cobusgreyling/loop-cli doctor .
Or pick a pain point, then scaffold:
-${PAIN_OPTIONS.map((p) => ` ${p.id}. ${p.label}\n npx @cobusgreyling/loop init . -p ${p.pattern} -t grok`).join('\n\n')}
+${PAIN_OPTIONS.map((p) => ` ${p.id}. ${p.label}\n npx @cobusgreyling/loop-cli init . -p ${p.pattern} -t grok`).join('\n\n')}
Commands:
loop init|audit|cost|sync|doctor|status|badge|wizard