Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion LOOP.md
Original file line number Diff line number Diff line change
Expand Up @@ -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-cli init . --pattern daily-triage --tool grok # after npm publish
npx @cobusgreyling/loop 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
```
Expand Down
30 changes: 15 additions & 15 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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-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"><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-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>
Expand All @@ -37,13 +37,13 @@

```bash
# Front door (recommended) — one binary for init + doctor + status
npx @cobusgreyling/loop-cli init . --pattern daily-triage --tool grok
npx @cobusgreyling/loop-cli doctor .
npx @cobusgreyling/loop init . --pattern daily-triage --tool grok
npx @cobusgreyling/loop 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-cli init . --with-foundry
npx @cobusgreyling/loop 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).
Expand Down Expand Up @@ -88,17 +88,17 @@ 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-cli` — old packages stay open |
| [CLI front door](docs/cli-front-door.md) | Unified `@cobusgreyling/loop` — 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 |
| [Loop Design Checklist](docs/loop-design-checklist.md) | Ship readiness rubric |
| [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-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` |
| [**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` |
| [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` |
Expand All @@ -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-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) |
| **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) |
| **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) |

Expand Down Expand Up @@ -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-cli init . --pattern daily-triage --tool grok
npx @cobusgreyling/loop init . --pattern daily-triage --tool grok

# 2. One health check (audit + sync + files → top 3 actions)
npx @cobusgreyling/loop-cli doctor .
npx @cobusgreyling/loop doctor .

# 3. Optional: cost estimate / badge / day-2 dashboard
npx @cobusgreyling/loop-cli cost --pattern daily-triage --level L1
npx @cobusgreyling/loop-cli badge .
npx @cobusgreyling/loop-cli status .
npx @cobusgreyling/loop cost --pattern daily-triage --level L1
npx @cobusgreyling/loop badge .
npx @cobusgreyling/loop status .

# 4. See scores climb: empty → L1 → L2
bash scripts/before-after-demo.sh
Expand Down
24 changes: 12 additions & 12 deletions docs/QUICKSTART.md
Original file line number Diff line number Diff line change
Expand Up @@ -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-cli`). 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`). Dedicated packages (`loop-init`, `loop-audit`, …) stay fully supported — see [cli-front-door.md](./cli-front-door.md).

## 1. Pick your pain (30 seconds)

Expand All @@ -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-cli init . --pattern daily-triage --tool grok
npx @cobusgreyling/loop init . --pattern daily-triage --tool grok
# One health check (audit + sync + top 3 actions):
npx @cobusgreyling/loop-cli doctor .
npx @cobusgreyling/loop doctor .
# Optional one-command funnel into harness-foundry:
npx @cobusgreyling/loop-cli init . --pattern daily-triage --tool grok --with-foundry
npx @cobusgreyling/loop init . --pattern daily-triage --tool grok --with-foundry
```

Equivalent (old door, still supported):
Expand All @@ -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-cli init --help
npx @cobusgreyling/loop init --help
```

### Which `--tool` values work?
Expand All @@ -57,7 +57,7 @@ npx @cobusgreyling/loop-cli init --help
## 3. Check cost before you schedule (30 seconds)

```bash
npx @cobusgreyling/loop-cli cost --pattern daily-triage --level L1 --cadence 1d
npx @cobusgreyling/loop cost --pattern daily-triage --level L1 --cadence 1d
# same as: npx @cobusgreyling/loop-cost --pattern daily-triage --level L1 --cadence 1d
```

Expand All @@ -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-cli context --check --ledger loop-ledger.json
npx @cobusgreyling/loop context --check --ledger loop-ledger.json
# same as: npx @cobusgreyling/loop-context --check --ledger loop-ledger.json
```

Expand All @@ -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-cli doctor .
npx @cobusgreyling/loop doctor .
# Or audit alone:
npx @cobusgreyling/loop-cli audit . --suggest
npx @cobusgreyling/loop 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-cli badge .
npx @cobusgreyling/loop 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-cli init . --with-foundry
npx @cobusgreyling/loop init . --with-foundry
npx @cobusgreyling/harness-foundry validate
npx @cobusgreyling/harness-foundry run --goal "Verify harness wiring"
```
Expand All @@ -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-cli sync .
npx @cobusgreyling/loop sync .
# same as: npx @cobusgreyling/loop-sync .
```

Expand Down
6 changes: 3 additions & 3 deletions docs/RELEASE.md
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
# Release playbook — npm packages

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.
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.

| Package | Directory | Release tag |
|---------|-----------|-------------|
| `@cobusgreyling/loop-cli` | `tools/loop` | `loop-v*` |
| `@cobusgreyling/loop` | `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*` |
Expand All @@ -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-cli` | `cobusgreyling/loop-engineering` | `release-loop.yml` |
| `@cobusgreyling/loop` | `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` |
Expand Down
10 changes: 5 additions & 5 deletions docs/cli-front-door.md
Original file line number Diff line number Diff line change
@@ -1,20 +1,20 @@
# CLI front door — `@cobusgreyling/loop-cli`
# CLI front door — `@cobusgreyling/loop`

> **Additive.** Old packages stay fully supported. This is the recommended entry for new users, forks, and agents.

## Why

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-cli` is a **thin umbrella**:
`@cobusgreyling/loop` 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-cli init . -p daily-triage -t grok
npx @cobusgreyling/loop-cli doctor .
npx @cobusgreyling/loop init . -p daily-triage -t grok
npx @cobusgreyling/loop doctor .
```

## Map (new → same as before)
Expand Down Expand Up @@ -42,7 +42,7 @@ npx @cobusgreyling/loop-cli doctor .
| 2 | Blocked | hard-fail if you require scaffold |

```bash
npx @cobusgreyling/loop-cli doctor . --json
npx @cobusgreyling/loop doctor . --json
```

## Forks & contributors
Expand Down
Loading