Skip to content

feat: OpenClaw plugin port + Claude Code doc alignment (Phase 1)#3

Open
NiceCode666 wants to merge 4 commits intomainfrom
feature/openclaw-plugin-integration
Open

feat: OpenClaw plugin port + Claude Code doc alignment (Phase 1)#3
NiceCode666 wants to merge 4 commits intomainfrom
feature/openclaw-plugin-integration

Conversation

@NiceCode666
Copy link
Copy Markdown
Contributor

@NiceCode666 NiceCode666 commented Apr 30, 2026

Summary

Phase 1 of migrating AmphiLoop from a Claude Code-only plugin to a dual-platform (Claude Code + OpenClaw) plugin. Two coherent change sets bundled in this PR:

  1. OpenClaw native plugin integration — adds the plumbing so AmphiLoop installs as Format: openclaw (not falling back to Claude Code bundle detection). The bundled skill amphiloop-build exposes /amphiloop_build in any OpenClaw chat surface, delegating every code-writing step to OpenClaw's built-in coding-agent skill via a .amphiloop/AGENT_BRIEF.md + .amphiloop/TODOS.md working-directory protocol.
  2. Claude Code documentation adjustments (A1–A10) — makes commands/build.md + agents/amphibious-*.md the canonical source of truth for pipeline methodology. A future PR will reduce the OpenClaw SKILL.md to a thin wrapper that delegates to those files, listing only OpenClaw-specific deltas (worker dispatch, AGENT_BRIEF/TODOS protocol, AskUserQuestion → message translation).

Why this shape

The first cut of the OpenClaw SKILL.md (added in commit 1 of this PR) restates the 5-phase pipeline in its own ~210 lines. That restatement has already drifted from commands/build.md in 4 concrete ways — exploration output path (.bridgic/exploration/ vs .bridgic/explore/), missing Phase 1 (TASK.md template + domain auto-detection), missing protocols (setup-env.sh, env_ready refresh of build_context.md), unresolved {PLUGIN_ROOT} placeholder when the worker reads agent docs.

Two further runtime issues were discovered during testing:

  • The verify-fix loop ran in the host's context, compressing bug reports into one-line FIX entries before handing back to the worker — losing the worker's Phase 4 mental model.
  • Generated code used wait_for(time_seconds=N) to wait for user actions (login, QR scan); user-action latency is unbounded so a fixed timer is wrong by construction.

The A8 + A9 + A10 entries in this PR address those runtime issues at the methodology level. The full design is in the (gitignored) spec at docs/superpowers/specs/2026-04-30-openclaw-claude-code-flow-mirror-design.md.

What changed

Commit 1 — OpenClaw integration

  • openclaw.plugin.json — native plugin manifest
  • package.json + openclaw-entry.mjs — classifies AmphiLoop as openclaw format
  • extensions/openclaw-skill/amphiloop-build/SKILL.md — 5-phase pipeline with worker dispatch
  • extensions/openclaw-skill/README.md — install / verify docs
  • CLAUDE.md — adds OpenClaw Integration section
  • .gitignore — ignores docs/superpowers/ (internal planning notes)

Commit 2 — Claude Code adjustments (A1–A10)

  • agents/amphibious-config.md — A1 (tool-neutral question wording) + A7 frontmatter note
  • agents/amphibious-explore.md — A2 (canonical output path) + A3 (own build_context.md update) + A9 (HUMAN handoff → HumanCall mapping)
  • agents/amphibious-code.md — A4 (own build_context.md update) + A8 (HumanCall vs wait_for discipline)
  • agents/amphibious-verify.md — A6 (uv run --project syntax check) + A10 (OpenClaw human-intervention bridge addendum)
  • commands/build.md — A5 (remove orphaned refresh paragraph)
  • .claude-plugin/plugin.json — A7 (register all 3 dispatchable agents)

Test plan

  • `openclaw plugins inspect amphiloop` reports `Format: openclaw, Status: loaded`
  • `openclaw skills info amphiloop-build` reports `✓ Ready` with all worker binaries detected (claude / codex / opencode / pi)
  • `openclaw skills info coding-agent` reports `✓ Ready`
  • `python3 -c 'import json; json.load(open(".claude-plugin/plugin.json"))'` parses without error
  • `grep` verification of all 10 A-item edits (see commit 2 message)
  • Live `/AmphiLoop:build` run on Claude Code against a small task — confirm no behavior regression
  • Live `/amphiloop_build` run on OpenClaw against the same task — confirm cross-platform consistency (modulo Phase 4 worker-dispatch differences and current Phase-5 SKILL.md drift, which is the next PR's scope)

Out of scope (next PR)

  • Refactor extensions/openclaw-skill/amphiloop-build/SKILL.md into a thin wrapper around commands/build.md + agent docs.
  • Phase 5 redesign so verify also dispatches to the long-lived coding-agent worker (with the AMPHI-HUMAN-REQUEST sentinel bridge protocol introduced by A10).

@NiceCode666
feat: add OpenClaw native plugin integration
8b9042d 
Adds the plumbing required to install AmphiLoop as a native OpenClaw
plugin (Format: openclaw, not Claude Code bundle). The bundled skill
exposes /amphiloop_build in any OpenClaw chat surface, delegating
every code-writing step to the built-in coding-agent skill via a
TODO-protocol working directory.

- openclaw.plugin.json: native plugin manifest
- package.json + openclaw-entry.mjs: classifies AmphiLoop as openclaw
  format (otherwise OpenClaw falls back to Claude Code bundle detection
  via .claude-plugin/plugin.json)
- extensions/openclaw-skill/amphiloop-build/SKILL.md: 5-phase pipeline
  with worker dispatch via .amphiloop/AGENT_BRIEF.md + TODOS.md
- extensions/openclaw-skill/README.md: install / verify docs
- CLAUDE.md: adds OpenClaw Integration section
- .gitignore: ignores docs/superpowers/ (internal planning notes)
@NiceCode666
docs: Claude Code documentation adjustments for OpenClaw flow mirror …
2e8f73f 
…(A1-A10)

Foundation for migrating AmphiLoop from a Claude Code-only plugin to a
dual-platform plugin. Makes commands/build.md + agents/amphibious-*.md the
canonical source of truth for pipeline methodology so a future PR can reduce
the OpenClaw SKILL.md to a thin wrapper that delegates phase methodology to
those files.

A1: tool-neutral question wording in amphibious-config.md so OpenClaw
    (no AskUserQuestion equivalent) and Claude Code follow identical
    semantics. Forbids duplicating the question as chat text alongside
    the tool call.

A2: explicit canonical exploration output dir <PROJECT_ROOT>/.bridgic/explore/
    in amphibious-explore.md (was implicit; OpenClaw skill had drifted
    to .bridgic/exploration/).

A3 + A4: build_context.md refresh ownership moved from commands/build.md
    (orphaned paragraph) into amphibious-explore.md and amphibious-code.md
    as explicit closing sections of each agent's contract.

A5: orphaned 'After Phases 3 and 4, refresh build_context.md' paragraph
    in commands/build.md removed (work now owned by agents).

A6: amphibious-verify.md Phase 4.2 syntax check uses
    'uv run --project <PROJECT_ROOT> python -m py_compile' so it runs
    against the same Python interpreter the project's uv env was set up
    with.

A7: .claude-plugin/plugin.json registers all 3 dispatchable agents
    (amphibious-explore, amphibious-code, amphibious-verify).
    amphibious-config.md is intentionally omitted (interactive, runs
    inline) — a frontmatter note documents that.

A8: amphibious-code.md adds a Best Practice in Phase 2.3 forbidding
    wait_for(time_seconds=N) for user-action waits (login, QR scan,
    CAPTCHA). HumanCall is the correct primitive — bridgic framework
    blocks the yield until the user responds.

A9: amphibious-explore.md makes the runtime mapping HUMAN: -> HumanCall
    explicit in the Operation Sequence section so explorers don't record
    wait_for fallbacks.

A10: amphibious-verify.md gains an OpenClaw addendum describing the
    sentinel + flag-file bridge protocol the long-lived coding-agent
    worker uses to surface monitor.sh exit-2 (human input required)
    events to the host orchestrator. No effect on Claude Code subagent
    execution.
@NiceCode666
docs: enhance human interaction protocol and output layout clarity
585ed08 
Updated the human interaction protocol across multiple agents to ensure consistent user prompts and responses during the build pipeline. Added detailed instructions for handling human intervention scenarios, emphasizing the importance of explicit user engagement at every phase transition.

Revised output layout specifications in amphibious-code.md and related documents to clarify the directory structure and enforce mandatory placement of generated files within the project directory. Introduced anti-patterns to avoid, ensuring users adhere to best practices in project organization.

These changes aim to streamline user experience and maintain clarity in project structure across both Claude Code and OpenClaw platforms.
@NiceCode666
docs: update SKILL.md for improved argument parsing and pipeline clarity
18c31f1 
Enhanced the SKILL.md documentation to clarify argument parsing and the overall pipeline structure for the AmphiLoop build process. Added detailed sections on input handling, domain selection, and mandatory step transitions to ensure users understand the flow and requirements during project setup. This update aims to streamline user interaction and reinforce best practices in project organization.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@NiceCode666