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.

docs: clarify loop-init --tool values and add Cursor constraints example (#135)

Cobus Greyling37b07789a49b
diff --git a/docs/QUICKSTART.md b/docs/QUICKSTART.md
index 13acfdb..b85d2d3 100644
--- a/docs/QUICKSTART.md
+++ b/docs/QUICKSTART.md
@@ -22,7 +22,23 @@ Run this in the root of any git project (no clone required):
npx @cobusgreyling/loop-init . --pattern daily-triage --tool grok
```
-Swap `--tool grok` for `claude`, `codex`, or `opencode` if needed. Swap `--pattern` for any pattern from [patterns/registry.yaml](../patterns/registry.yaml).
+Swap `--pattern` for any pattern from [patterns/registry.yaml](../patterns/registry.yaml). List all patterns:
+
+```bash
+npx @cobusgreyling/loop-init --help
+```
+
+### Which `--tool` values work?
+
+| `--tool` value | Scaffolded by `loop-init`? | Notes |
+|----------------|---------------------------|-------|
+| `grok` | Yes (default) | Native `/loop` scheduling |
+| `claude` | Yes | Native `/loop` + `$skill` invocation |
+| `codex` | Yes | Automations tab for scheduling |
+| `opencode` | Yes | Cron/systemd + `opencode run` |
+| `cursor` | No — manual copy | Copy skills + `STATE.md`; use Automations — see [examples/cursor/](../examples/cursor/) |
+| `windsurf` | No — manual copy | Copy skills + `STATE.md`; use Workflows — see [examples/windsurf/](../examples/windsurf/) |
+| `openclaw` | No — manual copy | Copy `skills/` + `STATE.md`; use `openclaw cron` — see [examples/openclaw/](../examples/openclaw/) |
`loop-init` copies the starter kit, creates `STATE.md`, `LOOP.md`, `loop-budget.md`, and `loop-run-log.md`, then **prints your Loop Ready score** and first command.
@@ -113,9 +129,13 @@ Commit the scaffold + first run update so `loop-audit` sees activity on the next
## Copy-paste cheat sheet
```bash
-# Scaffold (swap --tool for claude | codex | opencode)
+# Scaffold — --tool accepts: grok | claude | codex | opencode
+# (cursor, windsurf, openclaw: manual copy — see table in section 2)
npx @cobusgreyling/loop-init . --pattern daily-triage --tool grok
+# List patterns and flags
+npx @cobusgreyling/loop-init --help
+
# Cost check
npx @cobusgreyling/loop-cost --pattern daily-triage --level L1 --cadence 1d
diff --git a/examples/cursor/README.md b/examples/cursor/README.md
index 3db32fb..878270b 100644
--- a/examples/cursor/README.md
+++ b/examples/cursor/README.md
@@ -5,6 +5,7 @@ Copy-pasteable loop patterns for Cursor, using **Automations** (cloud cron) or m
| Example | Cadence | Risk | File |
|---|---|---|---|
| Daily Triage | 1d–2h (Automation or manual) | Low | [daily-triage.md](daily-triage.md) |
+| Constraints | Every loop run (before triage) | Low | [constraints.md](constraints.md) |
No `loop-init --tool cursor` yet — copy `SKILL.md` + `STATE.md` from any starter (e.g. `starters/minimal-loop`), then follow the example to wire scheduling.
diff --git a/examples/cursor/constraints.md b/examples/cursor/constraints.md
new file mode 100644
index 0000000..15094bc
--- /dev/null
+++ b/examples/cursor/constraints.md
@@ -0,0 +1,73 @@
+# Constraints — Cursor
+
+Binding rules your loop must never break. The `loop-constraints` skill reads `loop-constraints.md` at the start of every run.
+
+Cursor has no native `/constraints` or `/loop` command — you enforce rules with a skill, always-on rules, and an Automation (or manual Agent) prompt that runs constraints **before** triage.
+
+## Quick start
+
+Create the constraint file and skill:
+
+```bash
+mkdir -p .cursor/skills/loop-constraints
+cp templates/SKILL.md.loop-constraints .cursor/skills/loop-constraints/SKILL.md
+cp templates/loop-constraints.md loop-constraints.md
+```
+
+Edit `loop-constraints.md` and add your rules:
+
+```markdown
+# Loop Constraints
+
+- Don't push before telling me.
+- Never edit auth/ or payments/.
+- Always run tests before proposing a fix.
+```
+
+Optional: mirror critical rules in `.cursor/rules/loop-constraints.mdc` so they apply even outside Automations (see [safety.md](../../docs/safety.md) for path denylist examples).
+
+## Before every loop run
+
+In Cursor → Automations (or Agent chat on cadence), run constraints **first**, then triage:
+
+```text
+Run the loop-constraints skill. Read loop-constraints.md and enforce every rule.
+Then run loop-triage. Update STATE.md (High Priority + Watch List only).
+No auto-fix in week one. Escalate anything touching the denylist in docs/safety.md.
+```
+
+## How it works
+
+1. `loop-constraints.md` lives at the repo root — one rule per line below the header.
+2. `loop-constraints` skill lives at `.cursor/skills/loop-constraints/SKILL.md` (copy from `templates/SKILL.md.loop-constraints`).
+3. Every loop run starts with the constraints skill — it reads the file and bakes rules into context before triage or any action skill runs.
+4. Optional always-on rules in `.cursor/rules/` reinforce denylist paths and human gates from [safety.md](../../docs/safety.md).
+
+## Manual copy (no loop-init yet)
+
+There is no `loop-init --tool cursor` yet. Copy from any starter:
+
+```bash
+cp starters/minimal-loop/STATE.md.example STATE.md
+mkdir -p .cursor/skills/loop-triage .cursor/skills/loop-constraints
+cp templates/SKILL.md.loop-triage .cursor/skills/loop-triage/SKILL.md
+cp templates/SKILL.md.loop-constraints .cursor/skills/loop-constraints/SKILL.md
+cp templates/loop-constraints.md loop-constraints.md
+```
+
+Audit after copying:
+
+```bash
+npx @cobusgreyling/loop-audit . --suggest
+```
+
+## Safety
+
+Constraints are *binding*. If a rule can be misinterpreted, rewrite it — the loop will not second-guess, the human will. Encode path denylist and auto-merge policy from [safety.md](../../docs/safety.md) in both `loop-constraints.md` and `.cursor/rules/`.
+
+## References
+
+- [templates/loop-constraints.md](../../templates/loop-constraints.md) — default constraint set
+- [templates/SKILL.md.loop-constraints](../../templates/SKILL.md.loop-constraints) — constraints skill template
+- [docs/safety.md](../../docs/safety.md) — denylist, human gates, auto-merge policy
+- [daily-triage.md](./daily-triage.md) — week-one triage Automation prompt
\ No newline at end of file