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