feat: Self-Repair protocol for automatic adapter fixing#866
Merged
Conversation
When an AI agent uses opencli and a command fails, the agent automatically diagnoses the failure, fixes the adapter, and retries. - Add CLAUDE.md with Self-Repair protocol (auto-loaded by Claude Code) - Add designs/self-repair-protocol.md documenting the approach - Update opencli-repair skill: add Safety Boundaries (AUTH/BROWSER → STOP, sourcePath-only scope, max 3 rounds), fix AUTH_REQUIRED guidance - Update opencli-usage skill: add Self-Repair section Key design decisions: - Repair target is always RepairContext.adapter.sourcePath (works for both repo-local clis/ and user-local ~/.opencli/clis/) - Only adapter files may be modified, never core src/ - Max 3 repair rounds per failure - AUTH_REQUIRED and BROWSER_CONNECT are hard stops (report, don't modify)
- Remove "Auth changed (AUTH_REQUIRED)" exploration section from opencli-repair skill — contradicted the hard stop rule above it - Update design doc: scope language matches repo-local + explicit skill delivery model, not universal product behavior - Update usage skill: reference sourcePath instead of "files under clis/"
CLAUDE.md was wrong — users don't work inside the opencli repo, and the protocol shouldn't assume Claude Code. The skill is the portable delivery mechanism for any AI agent. - Rename skills/opencli-repair → skills/opencli-autofix - Remove CLAUDE.md (not the right delivery mechanism) - Update all references in usage skill and design doc - Design doc rewritten to reflect skill-first approach
When a command fails with a repairable error (SELECTOR, EMPTY_RESULT, COMMAND_EXEC, or generic http/not-found), the error output now includes a hint telling agents to re-run with OPENCLI_DIAGNOSTIC=1 for repair context. This is the trigger mechanism that bridges the gap between "command failed" and "agent enters autofix loop". Non-repairable errors (AUTH_REQUIRED, BROWSER_CONNECT, ARGUMENT) do not emit the hint — these require user action, not adapter fixes.
Remove hint from CommandExecutionError (covers env/launcher/runtime issues, not adapter drift) and generic http errors (often temporary site issues). Keep hint only for SelectorError, EmptyResultError, and generic not-found — clear adapter-drift signals.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
When an AI agent uses opencli and a command fails due to a site change, the agent automatically diagnoses the failure, fixes the adapter, and retries — without human intervention or pre-written spec files.
This is the Self-Repair MVP, a simpler alternative to the spec/runner framework in PR #863. Instead of requiring pre-authored command specs, the command itself is the spec — the agent just retries it after fixing.
Supersedes the direction of #863 (which is deferred to Phase 2 as an "asset/hardening layer").
Changes
CLAUDE.md(new) — Project-level agent instructions with Self-Repair protocol. Auto-loaded by Claude Code sessions.designs/self-repair-protocol.md(new) — Design document explaining the approach.skills/opencli-repair/SKILL.md(updated) — Added Safety Boundaries section: AUTH/BROWSER → STOP, sourcePath-only scope, max 3 repair rounds. Fixed AUTH_REQUIRED guidance.skills/opencli-usage/SKILL.md(updated) — Added Self-Repair section + reference to repair skill.Key design decisions
RepairContext.adapter.sourcePath(works for both repo-localclis/and user-local~/.opencli/clis/)src/AUTH_REQUIREDandBROWSER_CONNECTare hard stops (report to user, don't modify code)src/diagnostic.ts)Scope clarification
This PR establishes the Self-Repair protocol as a repo-local workflow for Claude agents working in the opencli repo. For the broader "any AI agent using opencli anywhere" scenario, the updated
opencli-repairskill serves as the portable mechanism (agents can load it explicitly). A runtime trigger layer (e.g.,--auto-repairflag inexecution.ts) is a potential Phase 2 addition.Test plan
CLAUDE.mdloads automatically in a new Claude Code session in the opencli repoopencli-repairskill Safety Boundaries section is consistent with CLAUDE.mdRepairContext.adapter.sourcePathresolves correctly for both repo and~/.opencli/clis/adapters