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
40 changes: 0 additions & 40 deletions .claude/skills/loopflow/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -51,8 +51,6 @@ allow edits automatically, but ask me before <classes> action policy
each cycle: plan, then act, then observe the repeated steps (any subset, in order)
also: <pass>, <pass> extra finishing passes after the goal is met
use skills: <a>, <b> named skills the loop may invoke during plan/act
use skills recommended by ctx ctx recommends + installs the skills for the goal (needs the ctx MCP server); add `for "<intent>"` to override the query
top up skills from ctx run-time: pull more skills from ctx when a cycle fails and reflects
remember in "<file.md>" cross-run memory: read lessons on start, append an outcome on stop
when it fails: reflect on <focus>, then plan again
when it passes and the goal is met: stop
Expand All @@ -69,9 +67,6 @@ models: fast <m>, strong <m> model tiering — plan/reflect/also→fast, act→s
schedule: <when> run unattended on a cadence
runner: <agent> which agent executes the loop
target: <dir> operate on another directory/repo
recommend skills with ctx ctx is this file's skill source — recommends + installs skills per loop goal
grant ctx: skills, agents, mcps, harnesses capability groups ctx may recommend (fail-closed; default skills+agents; mcps/harnesses are recommend-only)
ctx may use my own model "<provider>/<model>" declares a user-owned model — unlocks harness recommendations (dry-run only)
```

Predicates:
Expand Down Expand Up @@ -173,34 +168,6 @@ Walk these quickly, naming the keyword each time so they learn it:
Don't forget the menu in Step 2 also covers `use the <method> method` — pull a whole
preset (e.g. BMAD) instead of hand-picking passes.

### Skill discovery — offer ctx when the right skills aren't named yet

`use skills:` assumes the skills already exist in `~/.claude/skills`. If the user doesn't
already know which skills the loop needs, offer to let **ctx**
([claude-ctx](https://github.com/stevesolun/ctx)) pick them: it recommends the smallest
useful bundle for the goal and installs the bodies, so the names resolve. It is **opt-in**
and only works when the ctx MCP server is attached (`claude mcp add ctx -- ctx-mcp-server`).

When ctx's tools are available (`ctx__loop_provision`, `ctx__recommend_bundle`):
1. After the goal is set, call `ctx__recommend_bundle` (read-only preview) or
`ctx__loop_provision` with the goal — show the user the recommended skills with their
reasons before installing anything.
2. On approval, `ctx__loop_provision` installs them and returns the resolved names. Write a
real `use skills: <names>` line **and** a `use skills recommended by ctx` line — the
first keeps the `.loop` self-contained and reproducible; the second lets a headless
`loop run` re-resolve the bundle from ctx.
3. Offer `top up skills from ctx` if the loop should pull more skills when a cycle fails.
4. **Beyond skills** — if the goal needs more than skills, add a `grant ctx: skills, agents,
mcps, harnesses` line for the groups that apply (fail-closed; omit it for skills-only).
`mcps` and `harnesses` are **recommend-only** — ctx surfaces them with an install command
the user runs; the loop never auto-installs them. Harnesses additionally need a
`ctx may use my own model "<provider>/<model>"` line, and always come as a `--dry-run`
command. Pass the granted groups (and own-model) to `ctx__loop_provision` as `permissions` /
`own_llm` / `model_provider` / `model`.

When ctx is **not** attached, skip this silently and author `use skills:` by hand as usual —
the loop runs the same either way.

Offer the defaults inline (*"I'll add a tests + security pass, gate the migration, a
6-try guard, work on a branch, one model throughout, no schedule — sound right?"*) so the
whole interview is one exchange. Name every topic once even when you default it, so the
Expand Down Expand Up @@ -323,13 +290,6 @@ the user explicitly asks for the headless runner.)
- **plan** — inspect the `look at:` files; decide the smallest change toward the goal.
If the loop declares `use skills:`, you may invoke those named skills (via the Skill
tool) to do the work — coordinate them rather than re-deriving everything inline.
- **ctx skills** — if the loop declares `recommend skills with ctx` /
`use skills recommended by ctx`, resolve the bundle once at the start of the run: call
`ctx__loop_provision` with the goal (and any `for "<intent>"`) to install the skills
and get their names, then treat those as part of `use skills:` for this run. If the
loop also says `top up skills from ctx`, call `ctx__loop_topup` with your reflection
after a failed cycle and fold any new skills in before re-planning. If the ctx tools
aren't attached, skip this and run with whatever `use skills:` already names.
- **act** — make the edits. Honor the policy: for `ask me before <X>`, ask the user
before doing X (migrations, pushes, etc.); auto classes you may do directly.
- **observe** — run the `done when` check and read pass/fail. For a command or named test,
Expand Down
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -15,3 +15,4 @@ packages/cli/.claude/

# Synced from the repo template library at build (single source of truth: /templates)
packages/vscode/templates/
.env*
50 changes: 0 additions & 50 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -69,8 +69,6 @@ allow edits automatically, but ask me before <classes> action policy
each cycle: plan, then act, then observe the repeated steps (any subset, in order)
also: <pass>, <pass> extra finishing passes run after the goal is met
use skills: <a>, <b> named skills the loop may invoke during plan/act
use skills recommended by ctx let ctx pick + install the skills for the goal (needs the ctx MCP server); add `for "<intent>"` to override the query
top up skills from ctx run-time: pull more skills from ctx when a cycle fails and reflects (pairs with the line above)
remember in "<file.md>" cross-run memory: read lessons on start, append an outcome on stop
reflect turn a failure into context for the next plan (the back-edge)

Expand All @@ -91,9 +89,6 @@ each cycle: plan, then act, then observe (config tier: the default cycle for e
rigor: vibe coding | structured ai-assisted | agentic engineering (the spectrum dial; structured/agentic give every loop a back-edge + thrash guard for free)
mode: conductor | orchestrator (supervision posture: in-session/sync vs async/opens-a-PR)
runs as: <identity> (an auditable principal for unattended runs)
recommend skills with ctx (config tier: ctx is this file's skill source — recommends + installs skills per loop goal; see "Skill source: ctx" below)
grant ctx: skills, agents, mcps, harnesses (config tier: capability groups the file lets ctx recommend; fails closed, default skills+agents; mcps/harnesses are recommend-only)
ctx may use my own model "<provider>/<model>" (config tier: declares a user-owned/local/API model — unlocks ctx harness recommendations, always dry-run)
observe: (config-tier block) trace every cycle / meter tokens and cost / stop and warn if cost exceeds "$N"
sandbox: (config-tier block) no network access / allow egress to "host" only / cap cpu at … memory at … time at …
hooks: (loop body block) before each cycle | after act | on commit | on stop : "<cmd>" passes|finds nothing (a failing hook blocks)
Expand Down Expand Up @@ -160,51 +155,6 @@ then have the loop coordinate them. Don't invent a loop around skills that don't
prove the skill manually, then wire it in (as an execution skill via `use skills:`, or as a
verifier via `done when the skill "…" approves`). See `examples/skills_memory.loop`.

### Skill source: ctx — let a recommender pick + install the skills

`use skills:` assumes the skills already exist in `~/.claude/skills`. **ctx**
([claude-ctx](https://github.com/stevesolun/ctx)) fills that gap: point it at a goal and it
recommends + installs the smallest useful bundle so the names resolve.

```loop
recommend skills with ctx # config tier: ctx is this file's skill source

loop "harden the stripe webhook handler":
goal: webhook retries are idempotent and signature-checked, with tests
use skills recommended by ctx for "stripe webhook idempotency" # bake at author time, resolve at run time
top up skills from ctx when a step needs more # pull more on a failing cycle
done when "pnpm test api/webhooks" passes
```

- **Author time** (`/loopflow`): ctx recommends for the goal, you approve, the names are
installed and written into a `use skills:` line so the `.loop` stays self-contained.
- **Run time** (`loop run`): the runtime resolves `use skills recommended by ctx` via the ctx
MCP server before the first plan, and `top up skills from ctx` after a failed cycle reflects.
- **No ctx attached?** The lines are inert — the loop runs exactly as it would without them.

**Beyond skills — the full capability set.** By default ctx provisions only `skills`
(and the agents Loop loads the same way). A `grant ctx:` line widens what ctx may recommend to
any of `skills, agents, mcps, harnesses`, **failing closed** — only listed groups are returned:

```loop
recommend skills with ctx
grant ctx: skills, agents, mcps, harnesses # capability grants (fail-closed)
ctx may use my own model "ollama/llama3.1" # unlocks harness recs (dry-run only)

loop "stand up a local agent loop":
goal: an MCP agent loop running on local ollama with filesystem access
use skills recommended by ctx
done when "pytest tests/agent_loop" passes
```

- **skills / agents** — install into `~/.claude/skills`, merge into the cycle's skill set.
- **mcps** — recommend-only: surfaced on a `ctx` event, never auto-registered.
- **harnesses** — only with `ctx may use my own model "…"`, ship as an explicit `--dry-run`
command, never auto-install.

Setup: `claude mcp add ctx -- ctx-mcp-server` (needs `pip install claude-ctx`). Full
walkthrough: `docs/ctx-integration-guide.md`.

### `remember in` — cross-run memory

A loop forgets everything between runs unless you give it a memory file. `remember in` makes
Expand Down
16 changes: 9 additions & 7 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,13 @@ Versions track the `@loop-lang/loop` installer package.

## [Unreleased]

### Removed
- **External skill-recommender integration** — the external skill-source clauses have been
removed from the grammar, runtime, and docs. The plain `use skills: <a>, <b>` clause and
named-skill verifiers (`done when the skill "…" approves`) are unaffected — list resolved
skill names directly. The removed lines no longer parse; delete them from any existing
`.loop` files.

## [0.7.1] — 2026-07-02

> `@loop-lang/loop` 0.7.1 · `@loop-lang/{parser,runtime,stdlib,viz}` 0.4.1 · `loopflow` (vscode) 0.5.4
Expand All @@ -28,11 +35,6 @@ Versions track the `@loop-lang/loop` installer package.
> `@loop-lang/loop` 0.7.0 · `@loop-lang/{parser,runtime,stdlib,viz}` 0.4.0 · `loopflow` (vscode) 0.5.0

### Added
- **ctx as a skill source** — `recommend skills with ctx` / `use skills recommended by ctx`
/ `top up skills from ctx`: a loop equips itself via the ctx MCP server before the first
plan and re-equips after a failed cycle reflects. Capability grants
(`grant ctx: skills, agents, mcps, harnesses`, fail-closed) and own-model gating
(`ctx may use my own model "…"`, dry-run-only harness recommendations).
- **Verification reliability** — the flake guard (`done when "…" passes 3 times`: every
run must pass, first failure short-circuits) and judge panels
(`the skill "…" approves by 3 judges`: majority of independent verdicts, early-exit
Expand All @@ -56,8 +58,8 @@ Versions track the `@loop-lang/loop` installer package.
### Changed
- **New logo** — the gap ring (one ring, one gap: the loop still iterating), with a
solid-tile variant as the favicon / app icon across the site and README.
- `loopflow` (vscode) 0.5.0 — bundles the 0.4.0 parser (judge panels, flake guard, ctx
lines all recognized); output panel renders `⏩ resumed` events.
- `loopflow` (vscode) 0.5.0 — bundles the 0.4.0 parser (judge panels, flake guard all
recognized); output panel renders `⏩ resumed` events.

## [0.6.0] — 2026-06-29

Expand Down
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -93,7 +93,7 @@ Taught with a worked example in the [tutorial](https://loopflow.live/#evals); fu

## Skills and memory

A loop can coordinate proven skills (`use skills: check-weather, analyze-workout`), let a review skill be the verdict (`done when the skill "workout-review" approves`), and keep cross-run memory in a markdown file (`remember in "morning-run.memory.md"`). With [ctx](https://github.com/stevesolun/ctx) attached as the skill source, `use skills recommended by ctx` provisions the right bundle before the first plan — opt-in, fail-closed, inert without ctx. Details: [manual](docs/MANUAL.md#skill-source-ctx), [integration guide](docs/ctx-integration-guide.md), [`examples/skills_memory.loop`](examples/skills_memory.loop), [`examples/ctx_capabilities.loop`](examples/ctx_capabilities.loop).
A loop can coordinate proven skills (`use skills: check-weather, analyze-workout`), let a review skill be the verdict (`done when the skill "workout-review" approves`), and keep cross-run memory in a markdown file (`remember in "morning-run.memory.md"`). Details: [manual](docs/MANUAL.md), [`examples/skills_memory.loop`](examples/skills_memory.loop).

## The vocabulary — learn it once

Expand Down
28 changes: 2 additions & 26 deletions docs/MANUAL.md
Original file line number Diff line number Diff line change
Expand Up @@ -89,7 +89,7 @@ loop "<name>":

| Line | Zone |
|---|---|
| `use skills:` / `use skills recommended by ctx` / `remember in` / `knowledge:` / `examples:` | 2 · boundaries (capabilities & context) |
| `use skills:` / `remember in` / `knowledge:` / `examples:` | 2 · boundaries (capabilities & context) |
| `plan from "<file>"` | 2 · boundaries (the plan is an input) |
| `also:` (finishing passes) | 3 · engine (extra movement after the goal) |
| `hooks:` | 4 · safety net (deterministic checkpoints) |
Expand Down Expand Up @@ -220,7 +220,7 @@ self-contained (no external assets) and binds to `127.0.0.1` only.

Every meaningful thing a run does is a **structured event** — `loop-start`, each
`node-enter` / `node-exit` (with the attempt number), `observe` (pass/fail + output),
`transition`, `reflect`, `loop-back`, human gates, `ctx` provision/top-up, `git` actions,
`transition`, `reflect`, `loop-back`, human gates, `git` actions,
`hook` results, the `model` tier per phase, `stop` (with the reason), `loop-end`, and the
pipeline / flow / for-each envelopes. The live dashboard renders this stream; you can also
**persist it** — to a local file and/or a remote collector — for auditing, debugging a
Expand Down Expand Up @@ -599,30 +599,6 @@ These add agentic-engineering discipline to Loop. All are optional; a simple loo
See [`examples/agentic/`](../examples/agentic/) for one file per feature; run `loop-run explain
<file>` on any of them to read it back in plain English.

### Skill source: ctx

[ctx](https://github.com/stevesolun/ctx) can act as a file's **skill source** —
recommending and installing capabilities per loop goal. All lines are opt-in and **inert
without the ctx MCP server** (the loop runs exactly as it would without them).

| Line | Tier | What it does |
|---|---|---|
| `recommend skills with ctx` | config | ctx is this file's skill source. |
| `use skills recommended by ctx` (optional `for "<intent>"`) | loop body | Resolve + install the skill bundle for the goal before the first plan; `for "…"` overrides the query. |
| `top up skills from ctx` (optional `when a step needs more`) | loop body | Pull more skills after a failed cycle reflects. |
| `grant ctx: skills, agents, mcps, harnesses` | config | Capability groups ctx may recommend — **fail-closed** (default `skills, agents`; only listed groups are returned). |
| `ctx may use my own model "<provider>/<model>"` | config | Declares a user-owned/local/API model — unlocks harness recommendations. |

Semantics of the groups: **skills / agents** install into `~/.claude/skills` and merge into
the cycle's skill set. **mcps** are recommend-only — surfaced on a `ctx` event with a
suggested install command, never auto-registered. **harnesses** recommend only when an
own-model is declared, and ship as an explicit `--dry-run` install command — never an
automatic install.

Setup and the full capability walkthrough: [ctx-integration-guide](ctx-integration-guide.md).
Examples: [`examples/ctx_skills.loop`](../examples/ctx_skills.loop),
[`examples/ctx_capabilities.loop`](../examples/ctx_capabilities.loop).

### Git strategy

A `git:` block sets the version-control strategy for the run. It can appear at the top of
Expand Down
Loading
Loading