Rootloom 可检查工程工作流集合
提供小差异、可审查、可追溯证据的工程编码工作流。
使用前，准备这些
输入素材：代码库、技术环境与任务验收条件
- 在下方原始文档中确认支持的 AI 工具、模型和运行依赖。
- 打开原仓库，按作者的安装说明完成配置；模型 API 或外部服务可能需要单独开通。
- 用自己的素材试运行，再检查事实、版式与输出文件。
许可证：MIT
来源快照：2026-09-15。README ↗
原项目许可证与版权声明
MIT License Copyright (c) 2026 liyanqing Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
可以这样开始
Rootloom
Turn Codex code changes into inspectable engineering work.
A native OpenAI Codex plugin for finding the right place to change,
plus an Agent Plugins preview for portable Change, Review, and Project Guidance.
What is Rootloom?
Rootloom is a local engineering workflow with a full native OpenAI Codex plugin and a separate Agent Plugins portable preview. The native plugin exposes four Skills for changing code, reviewing changes, maintaining repository guidance, and managing optional setup. The portable preview exposes Change, Review, and Project Guidance without Codex-only Hooks or Setup. Rootloom is not another coding agent and it does not replace your editor, tests, or CI. Governed and machine-evidence work remain modes of Change, not extra public workflows.
You still describe the task in plain language. Rootloom changes how Codex approaches it:
- read the repository and its local rules before editing;
- judge the risk and define a sensible scope;
- for a defect, trace the symptom to the boundary that owns the behavior;
- make the smallest coherent change;
- verify the main path, the owning invariant, and an adjacent path;
- report the commands that actually ran, their results, and what remains uncertain.
For most work, this is the only invocation you need:
$operating-coding-change
Fix the reconnect race and verify reconnect, clean disconnect, and cancellation.
Why use it?
Coding agents are good at producing plausible patches. Plausible is not the same as correct, reviewable, or complete.
| A common failure | What Rootloom asks Codex to do instead |
|---|---|
| Patch the line closest to the error | Find the component that owns the violated behavior |
| Keep editing until one test passes | State the intended scope and preserve unrelated work |
| Test only the happy path | Check the primary path, the invariant, and a nearby alternate or failure path |
| Say “tests passed” without a useful record | Name the exact commands that ran and the result of each |
| Treat exit code 0 as proof of completion | Check whether scope, repository state, or captured evidence changed afterward |
| Add process to every task | Use a lightweight daily workflow; opt into deeper evidence only when it changes a decision |
The practical value is simple: fewer fixes at the wrong layer, smaller diffs, clearer reviews, and completion claims you can inspect.
Rootloom makes the work easier to examine. It does not make a model infallible or turn passing tests into proof of correctness.
Quick start
You need Codex CLI or desktop with plugin support, Git, and Python 3.11+.
1. Install the plugin
codex plugin marketplace add liyanqing90/rootloom
codex plugin add rootloom@rootloom
Installation is complete after those two commands.
2. Start a new Codex task
Plugin Skills are discovered when a task starts. No project configuration, daemon, or separate Rootloom command is required.
3. Ask for the work
$operating-coding-change
The worker can reconnect after cancellation and create two active sessions.
Find the cause, fix it without changing the public API, and run the relevant tests.
A useful completion report should now answer four concrete questions:
Cause Where did the behavior originate, and which invariant was broken?
Change Which files and behavior changed?
Verification Which commands actually ran, and what did each prove?
Risk What remains unverified or uncertain?
That is Rootloom's everyday path. You do not need an evidence bundle, global setup, or every Skill in the plugin to use it.
Read large files in proportion to the task
Start with bounded reads that answer the task. When repeated reads or substantial context cost justify preprocessing, Change can use the optional Artifact Context Lane: a local standard-library helper hashes and deduplicates files and caches intent-specific receipts. Raw bytes stay at their source; finalized receipts are capped at 24 KiB. Preparation accepts up to 16 files, at most 512 MiB each and 1 GiB of unique contents. Once the unique total exceeds that limit, it rejects the bundle before reading later files or writing a manifest or draft; duplicate contents count once.
A cache miss can use one host-owned worker with no inherited conversation. If that facility is unavailable, continue with bounded reads and skip the receipt optimization. Explicit user isolation, file access, upload, and retention limits still apply. The helper makes no model or network request; the optional worker adds a model call, while cache hits add none. Rootloom cannot erase already-recorded attachments or task history and does not require a fresh task merely because a file was already read.
Agent Plugins portable preview
portable/rootloom/ is a separate Agent Plugins 1.0.0 package containing exactly
operating-coding-change, operating-code-review, and project-guidance. Compatible clients discover those
Skills from the package's root plugin.json and fixed skills/ directory. Installation,
updates, permissions, and client UX remain client-owned parts of the Agent Plugins
Working Draft, so use the target client's own flow and select portable/rootloom/ as
the plugin root.
Cursor, VS Code, GitHub Copilot CLI, and Kiro use this same package without platform manifests or duplicated Skills; only their loader configuration differs. Copilot cloud still needs a published, resolvable marketplace entry, which Rootloom does not yet provide. Codex keeps its native package because its managed Hook, Setup, and interface surface are intentionally larger than Agent Plugins v1.
The preview includes Review, Project Guidance, and Direct, Scoped, and Governed Change. Persistent guidance still requires exact user intent. The package deliberately omits Setup, Hooks, Rules, Memory, MCP, OpenAI UI metadata, and the plugin-wide Evidence helpers. It includes the optional standard-library Artifact Context helper. Hosts without a no-history worker can use ordinary bounded reads without creating a cached semantic receipt. An explicit Evidence request therefore fails closed instead of fabricating an evidence bundle. Do not install the native and portable packages into the same client because duplicate-Skill precedence is not standardized.
Repository checks prove package shape, containment, Agent Skills metadata, relative References, and synchronization with the native source. A disposable Codex CLI smoke also proves that Codex can install an isolated package whose Skill surface contains exactly those three directories and a self-contained helper. Static and synthetic tests also exercise opt-in host adapter envelopes, but do not prove runtime discovery, activation, or identical behavior in Cursor, VS Code, GitHub Copilot, Kiro, or every other compatible client. See Agent Plugins portable preview for exact Cursor, VS Code, Copilot, and Kiro loading instructions, runtime smoke gates, migration, and rollback.
Choose the workflow that matches the task
| You want Codex to… | Use | When to reach for it |
|---|---|---|
| Build, fix, refactor, migrate, deploy, or capture strict evidence | $operating-coding-change | The single implementation entry; it routes Direct, Scoped, Governed, Evidence, and External Action modes |
| Review a diff, PR, migration, or design without editing | $operating-code-review | You want findings and evidence, not a patch |
Seed, refresh, refine, or validate repository AGENTS.md | $project-guidance | Project commands or durable invariants should persist |
| Install, upgrade, inspect, or roll back optional global setup | $setup-rootloom | You want cross-project guidance or Autonomy Rules |
Rootloom Core always presents these four entries. Change loads detailed governed,
external-action, verification, or Evidence References only when the task requires them.
Version numbers and serialized artifacts do not trigger compatibility by themselves:
regenerable internal records stay Scoped and current-only, while rollback restores the
complete old release and historical replay uses its matching runtime.
Runtime compatibility requires evidence of a real post-cutover consumer.
Project Guidance may validate when active repository guidance requests inspection, but
persistent seed, refresh, or refinement requires explicit user intent; natural-language
requests naming the guidance file are sufficient and need not name the Skill. A repository may
authorize one refinement of one file only with the exact standalone
<!-- rootloom:refine-once version=1 --> marker; repository prose alone never authorizes a write.
How an ordinary change works
Your request
↓
Repository evidence and local guidance
↓
Risk + scope
↓
Root cause for a defect / intended behavior for a feature
↓
Focused change
↓
Behavior-based verification
↓
Evidence-backed completion report
For a defect, Rootloom pushes the investigation toward an explicit chain:
symptom → trigger → owning boundary → violated invariant → cause
For a feature, there is no invented “root cause”; the workflow states the intended behavior and ownership instead. Verification is derived from what changed rather than from whichever test command is easiest to run.
Why “the command passed” is not enough
Rootloom's own development produced a useful example. A verification command exited successfully, but while running it created a newly ignored .env file and copied its synthetic value into an ordinary file. The command passed; the reviewed repository state did not remain the same.
The post-verification capture caught that difference, quarantined the sensitive path, kept changed content out of the patch bundle, and failed the strict review instead of issuing a passing completion claim.
The full scenario and executable regression are documented in The command passed, the review failed.
When you need stronger evidence
Most tasks should stay on the normal edit-and-test path. When a change needs a
reproducible local record, ask $operating-coding-change explicitly for Evidence Mode.
The optional evidence path can bind:
- the Git and repository state before the change;
- allowed and forbidden paths;
- behavior claims to commands that actually ran;
- a second repository capture after verification;
- machine-observed results separately from human semantic judgment.
It produces a local bundle containing the captured patch, test log, and machine-readable summary. This is an inspectable review record, not a security proof or an immutable audit system. See Architecture and Maturity and guarantees for the exact contract.
For the usual strict intake → edit → finalize loop, resources/evidence/orchestrate_evidence.py
offers prepare and finish. It composes the existing intake, sealed contract, and
finalizer without changing their wire formats. finish still requires an explicit
semantic-review assertion. This is a single-command verification convenience path:
multiple targets or specialized commands, migrations, mixed-version checks, security
boundaries, and build-plus-runtime proof use the low-level lifecycle.
Technical contract reference
Rootloom 4 Core remains An inspectable personal engineering workflow for Codex. Its public surface is Change, Review, Project Guidance, and Setup. Optional Autonomy is installed through Setup; deterministic Evidence is an explicit Change mode. Experimental Project Memory is a separate plugin and repository evidence remains authoritative.
The opt-in Evidence path uses resources/evidence/analyze_change.py for advisory analysis.
analyze_change.py --write-baseline can write analyzer-only evidence, while governed
intake publishes an exact contract with seal_contract.py. Strict review uses
--strict; machine consumers should read quality_status and the stable capability
field evidence_complete. REVIEW_EVIDENCE_COMPLETE means the evidence chain is
complete, while REVIEW_REQUIRED_WITH_REDACTIONS means material redaction prevents
that claim.
Core Reset v2 retains historical model comparisons and the optional research command
make core-reset-release-eval CORE_RESET_RESULTS=/absolute/path/results-v2.json.
Its fixed 135-cell matrix and historical efficiency thresholds are no longer release gates.
The retained 4.3.0 report describes that version only;
it is not evidence for a later candidate.
Current releases use checks selected from the actual change, package/Setup validation, and behavior comparisons when the workflow changes. The 4.4 change uses six scenarios with one current/candidate pair each, serially on the same model, reasoning effort, and isolation. Task outcomes and permission boundaries determine acceptance; latency and available usage are observations. This small comparison cannot establish general performance gains. See the 4.4 workflow decision. The tag workflow checks source/package integrity, Setup behavior, and tag/version identity.
Repository state is accepted only after two consecutive bounded captures agree. Each capture lifecycle is bounded by --max-capture-seconds. A material metadata change, including a newly discovered ignored addition, activates metadata-only quarantine before ordinary content capture. Classification uses is_sensitive_material_path; Rootloom is not a content-aware secret scanner.
--reviewable-path is an intake-only declaration for exact eligible files. It rejects ignored files, symlinks, hardlinks, ambiguous duplicates, strong secret material, and Git entries marked assume-unchanged or skip-worktree. The summary's reviewability_policy reports exact paths and policy_provenance; historical declarations that no longer meet current policy return reintake-required before content is read.
Evidence and bundle paths must be outside both the repository worktree and the resolved Git common directory. Optional authorization modes are Single action, Standard, and Full: Standard is Persistent across tasks, but every task still needs an explicit goal and resolved scope; Full is never inferred. The Archived Assurance Edition remains available at codex/enterprise-assurance without an active maintenance promise.
Optional personal setup
Installing Rootloom only exposes its four Skills. It does not write
~/.codex/AGENTS.md, install command Rules, enable a Hook, run Evidence helpers, or
install/read Project Memory.
If you want Rootloom's working agreement across projects, ask for the optional setup explicitly:
$setup-rootloom
Show me the personal preset plan, then install it if there are no conflicts.
Setup is plan-first, backup-backed, conflict-refusing, and reversible within its documented limits. It does not change your model, reasoning effort, sandbox, approval policy, providers, MCP servers, plugins, or apps. See Setup, update, and rollback.
What Rootloom is—and is not
Rootloom is deliberately narrow:
- It is a single-agent engineering workflow with a full native OpenAI Codex plugin.
- It is an Agent Plugins 1.0.0 portable preview for Change, Review, and Project Guidance.
- It is local, inspectable, and Python-standard-library-only at runtime.
- It is not a specification framework, test runner, linter, secret scanner, CI system, or replacement for human review.
- It is not a sandbox for untrusted verification commands.
- It does not promise equivalent Hooks, Setup, permissions, Evidence, or model behavior across coding-agent clients.
Specification tools such as GitHub Spec Kit and OpenSpec help define work before implementation. Tests, linters, scanners, and CI execute their own checks. Rootloom sits at the execution and review boundary: why this change, why here, what ran, and what evidence supports completion.
Product shape
Rootloom Core
├── Change: Direct / Scoped / Governed / Evidence
├── Review
├── Project Guidance
├── Setup
├── Optional Autonomy: authorization modes / Command Rules
└── Optional Evidence resources: Analyzer / Baseline / Contract / Seal / Finalizer
Rootloom Memory
└── Separate experimental plugin
The unmaintained 1.2.19 implementation is preserved as the Archived Assurance Edition. Human approval state machines, immutable audit chains, multi-agent audit runners, and recovery journals are not part of main.
Optional Rootloom Memory
Project Memory is no longer discovered by Core. Install it only when you want explicit, repository-owned historical lessons:
codex plugin add rootloom-memory@rootloom
Its $project-memory Skill preserves rootloom-project-memory-v1, remains advisory,
and never overrides current source, tests, schemas, or runtime evidence.
Documentation
- Architecture
- Setup, update, and rollback
- Maturity and guarantees
- Guidance design
- Troubleshooting
- Migrate from Rootloom 3.x to 4.0
- Migrate from Rootloom 4.0 to 4.1
- Contributing
Website telemetry
The public GitHub Pages site loads the official VibeLoft browser runtime once from the global index.html. Rootloom does not install a telemetry package, send manual page views, contact Supabase from the browser, or configure an alternate collector. The runtime owns its random first-party device ID, coarse environment digest, GPC/DNT handling, navigation coverage, retry behavior, and failure isolation. Because the published runtime is obfuscated, the release gate pins the exact SHA-256 of a request-blocked browser-reviewed build and fails closed on any upstream change. See the accepted website telemetry decision for the exact boundary, review procedure, and rollback.
Development
make check-changed BASE=origin/main
make validate
make test
make check
make compatibility-smoke
make telemetry-check
# Preview the website at http://localhost:8000
python3 -m http.server 8000
check-changed is the default development path: it selects tests from changed owners
across committed, staged, and unstaged tracked work, while excluding unrelated untracked
files. Use INCLUDE_UNTRACKED=1 only when they all belong to the task. Unknown executable
paths or shared test-selection infrastructure fall back to the full suite. test and
check are explicit full-suite targets. CI keeps one canonical full run on main;
routine additional environments repeat named compatibility cases, while broad version
matrices and full portable subsets are scheduled or manually invoked.