vloop-operator
The operator's playbook for this repo — /vloop:operate, plus what this repository adds to it (where its rules live, its checks, the roadmap row at close, the release, the acceptance briefs). Use in an interactive session whenever the operator asks to run, resume, verify, close or merge a brief, cut a release, or what to do about a halt or a finding. Writing briefs is the vloop-architect skill's.
- License 许可
- MIT
- 所属仓库
- mvelosop/vloop
- 最近更新
- 2026-11-10
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- vloop-operator
- description
- The operator's playbook for this repo — /vloop:operate, plus what this repository adds to it (where its rules live, its checks, the roadmap row at close, the release, the acceptance briefs). Use in an interactive session whenever the operator asks to run, resume, verify, close or merge a brief, cut a release, or what to do about a halt or a finding. Writing briefs is the vloop-architect skill's.
03 SKILL.md 正文
Operating the loop here
Follow /vloop:operate — the plugin's playbook — for everything: before the
run, halts, verifying, recording, closing and merging. If it is not loaded, read
plugin/skills/operate/SKILL.md, which is the same text. This skill only adds
what is particular to this repository; where the two seem to disagree, say so to
the operator rather than picking one.
Where the rules live
CLAUDE.md points to them. When a failure needs the rule it breaks, walk the
domain (docs/domain/README-domain.md → domain-model.md → the context and
entity page) and cite the invariant by ID (B-4, P-4, S-2, M-5…) in
what you report and record. If the domain is silent, propose the rule to the
operator; it may belong in domain-model.md.
Running
- The run id is the brief's file name minus
.loop-brief; the work branch is named for it. - Gates run on macOS's BSD tools: no empty alternatives in
grep -E, nosed -iwithout a suffix, no\+/\|in basic regexes, nodate -d. A gate that breaks one of these is a gate defect. - VS Code's
branch.*.vscode-merge-baseand its pull-request extension'sbranch.*.github-pr-*keys are ignored by the guard; any other editor key still halts with exit 9.
Verifying
- The repository's checks are the ones in
CLAUDE.md→ Toolchain, all of them, run by you. - Before trying
vloop brief closeorvloop defect addfor real in a throwaway clone of this repo, rungit remote set-head origin mainin the clone: a local clone takes whatever branch was checked out as its default.
Closing
- Besides what
vloop brief closedoes, mark the brief's row indocs/design-notes/vloop-roadmap.mdconsumed. - After recording interventions, refresh their index:
tools/interventions-index.sh --write(--checkwhen verifying). - The squash-merge body's
Vloop-Brief:line goes in the same paragraph as any other trailer (Co-Authored-By:…), with no blank line between: git reads only the last paragraph as trailers, andtools/releasefinds the briefs by that trailer. Check after the merge withgit log -1 --format='%(trailers:key=Vloop-Brief,valueonly)'.
Releasing
Only when the operator asks for one: go run ./tools/release prepare <version>
opens the release PR; merge it on the operator's go-ahead; then
go run ./tools/release publish <version> tags, releases and proves the public
install. Record a ceremony intervention for it. Then install the release and
vloop upgrade in each repository that uses vloop. See tools/release/README.md.
The acceptance briefs' flaws stay where they are
A brief used for acceptance runs (the URL shortener template's) can hold a flaw
found in an earlier run, kept on purpose to see how the loop and the agents
handle it. Don't fix it, and don't describe it anywhere a session or a later fix
could learn it: issues, skills, evals, anything under plugin/. Record what the
run showed in the operator notes and the design notes, in words that don't give
the flaw away; a fix to vloop uses a synthetic case.
04 同仓库更多 Skills
work
Do exactly one task of the autonomous loop's plan and report on it. Invoked once per iteration by the driver as /vloop:work <task id>.
verify
Verify the built result of a whole run against its brief, in three passes, and report findings as verify/v2. Invoked once per complete run by the driver as /vloop:verify, in a session separate from the work and the reviews.
review
Independently verify one completed task of the autonomous loop and return a verdict. Invoked once per iteration by the driver as /vloop:review <task id>, in a session separate from the work.
review-brief
Independently review a vloop brief before it is marked ready — facts against the code, internal consistency, conflicts with the repository's own rules, decisions the author took that the operator has not approved, and whether the loop can actually run it — and return a verdict with findings. Use in a session separate from the one that wrote the brief, when asked to review a brief, or before running a brief that the same operator session wrote.
plan
Decompose a brief into .vloop/state/state.json — the task list the autonomous loop executes. Invoked once per run by the driver as /vloop:plan <brief path>.
operate
The operator's playbook — from a ready brief, check the repository, run it with vloop on a work branch, handle halts, verify the result independently, record defects and interventions, close the brief and merge. Use in an interactive session when asked to run, resume, verify, close or merge a brief, or what to do about a halt or a finding. Writing briefs is /vloop:create-brief's.