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

.claude-plugin/plugin.json

@@ -6,7 +6,9 @@
     "./commands/"
   ],
   "agents": [
-    "./agents/amphibious-code.md"
+    "./agents/amphibious-explore.md",
+    "./agents/amphibious-code.md",
+    "./agents/amphibious-verify.md"
   ],
   "skills": []
 }

.gitignore

@@ -24,4 +24,8 @@ __pycache__/
 .env
 
 # Node (if npx skills is used locally)
-node_modules/
+node_modules/
+
+
+# superpowers
+docs/superpowers/

CLAUDE.md

@@ -79,3 +79,18 @@ claude plugin install AmphiLoop
 | Command | When to Use |
 |---------|-------------|
 | **/build** | Unified entry point. Turn any task into a working bridgic-amphibious project. Accepts an optional domain flag (`/build --browser`) to inject pre-distilled context from `domain-context/<domain>/`. Without a flag, auto-detects the domain from `TASK.md` (or falls back to a generic flow). Users may additionally supply their own domain references in `TASK.md`. |
+
+## OpenClaw Integration
+
+The AmphiLoop repository **is** an OpenClaw native plugin. Installing it (`openclaw plugins install <repo> --link`) auto-registers a bundled skill that exposes `/amphiloop_build "<task spec>"` in any OpenClaw chat surface.
+
+| Aspect | How it works |
+|--------|--------------|
+| **Plugin install** | `openclaw plugins install /abs/path/AmphiLoop-02 --link` then `openclaw gateway restart`. Setup + verification details in `extensions/openclaw-skill/README.md`. |
+| **Native classification** | Three small files at repo root — `openclaw.plugin.json` (manifest), `package.json` (with `openclaw.extensions: ["./openclaw-entry.mjs"]`), and `openclaw-entry.mjs` (no-op entry) — make OpenClaw classify AmphiLoop as **native** (`Format: openclaw`) instead of falling back to Claude Code bundle detection from `.claude-plugin/plugin.json`. |
+| **Bundled skill** | The plugin manifest declares `"skills": ["./extensions/openclaw-skill"]`; OpenClaw auto-discovers `amphiloop-build/SKILL.md` under that directory. |
+| **Orchestration** | The OpenClaw host model drives Phases 2–3 (config + explore) directly, reading the methodology from `agents/amphibious-*.md` via the `{baseDir}/../..` path resolution. |
+| **Code generation (host ↔ coding-agent)** | Host writes `<projectRoot>/.amphiloop/AGENT_BRIEF.md` (lists the bridgic-* SKILL.md files the worker MUST read for correct API usage) + `<projectRoot>/.amphiloop/TODOS.md` (task list). Then opens **one** long-lived OpenClaw `coding-agent` session and sends a tiny pointer prompt. Worker reads brief, reads TODOs, completes them, ticks `[ ]` to `[x]`. |
+| **Verify-fix loop** | Phase 5 verify failures get **appended** to the same `TODOS.md` as new `[ ] FIX-N: ...` entries; host then sends a one-line "continue" to the same long-lived worker session. Up to 3 fix rounds. |
+| **Worker choice** | The skill asks the user at run start which worker to dispatch to (`claude` recommended, plus `codex` / `opencode` / `pi`). One worker per run, reused throughout. |
+| **Existing files** | All Claude Code-only artifacts (`hooks/`, `.claude-plugin/`, `commands/build.md`, `scripts/hook/`) remain in place. The new `package.json` + `openclaw-entry.mjs` + `openclaw.plugin.json` are the only repo-root additions; they coexist with the Claude Code manifest without conflict. |

agents/amphibious-code.md

@@ -37,22 +37,34 @@ Skill files (see Skill References below) and `## References` stay on-demand —
 
 ## Output Layout
 
-The agent installs its runtime dependencies into PROJECT_ROOT's uv env (creating it if absent) and produces a code-only `<project-name>/` subdirectory. The structure inside `<PROJECT_ROOT>/` may follow the pattern below:
+The agent installs its runtime dependencies into PROJECT_ROOT's uv env (creating it if absent) and produces a code-only `<project-name>/` subdirectory. The structure inside `<PROJECT_ROOT>/` **MUST match this layout exactly** — deviations break Phase 5 verify and downstream orchestration:
 
 ```
 <PROJECT_ROOT>/
 ├── pyproject.toml      # uv project manifest
 ├── uv.lock             # resolution lockfile
 ├── .venv/              # uv-managed virtualenv
 ├── .env                # only when llm_configured = yes
-└── <project-name>/     # this agent's generator_project — code only
+├── .bridgic/           # orchestrator workspace (build_context.md, explore/, verify/) — DO NOT write code here
+└── <project-name>/     # this agent's generator_project — ALL generated code lives inside here
     ├── amphi.py        # scaffold-created; this agent edits it
     ├── main.py         # this agent creates: entry point (LLM init + agent.arun)
     ├── README.md       # short, operational
     ├── log/            # runtime logs land here (configured in main.py)
-    └── result/         # task outputs land here
+    ├── result/         # task outputs land here
+    └── <support>.py    # any extra helpers/modules go here too — never at PROJECT_ROOT
 ```
 
+**`<project-name>/` is the project's own directory, not a Python import package.** The entry points (`amphi.py`, `main.py`) and the support modules all live **inside** `<project-name>/`. PROJECT_ROOT only carries uv metadata (`pyproject.toml`, `uv.lock`, `.venv/`, `.env`) and the orchestrator's `.bridgic/` workspace — never code.
+
+### Layout anti-patterns — never produce these
+
+- ❌ `amphi.py` / `main.py` placed at `<PROJECT_ROOT>/` (sibling of `pyproject.toml`) instead of inside `<project-name>/`. The entry points must be reached as `<PROJECT_ROOT>/<project-name>/main.py`.
+- ❌ Treating `<project-name>/` as a Python import package (adding `__init__.py`, importing it from a sibling `main.py` at PROJECT_ROOT). `<project-name>/` is the project root, not a package alongside other code.
+- ❌ Writing project code (`*.py`, `log/`, `result/`) under `<PROJECT_ROOT>/.bridgic/`. That directory is the orchestrator's workspace and is exclusive to `build_context.md`, `explore/`, `verify/`.
+- ❌ Creating `log/` or `result/` at PROJECT_ROOT instead of inside `<project-name>/`. They must sit next to `main.py` so `Path(__file__).parent / "log"` resolves correctly.
+- ❌ Splitting support modules (`config.py`, `tools.py`, helper files) out to PROJECT_ROOT. Any module imported by `amphi.py` or `main.py` must live inside `<project-name>/`.
+
 ---
 
 ## Phase 1: Initialize Project Skeleton
@@ -73,11 +85,15 @@ bash "{PLUGIN_ROOT}/skills/bridgic-amphibious/scripts/install-deps.sh" \
 
 ### 1.3 Scaffold `amphi.py`
 
+`cd` into `<project-name>/` **first**, then run the scaffolder. The cwd at the moment of `bridgic-amphibious create` is what determines where `amphi.py` lands — running it from `<PROJECT_ROOT>/` will drop the file at PROJECT_ROOT and violate the Output Layout.
+
 ```bash
 cd "<PROJECT_ROOT>/<project-name>"
 uv run bridgic-amphibious create --task "<one-line task description>"
 ```
 
+After the command returns, verify with `ls "<PROJECT_ROOT>/<project-name>/amphi.py"` — if `amphi.py` is missing or sitting at `<PROJECT_ROOT>/amphi.py` instead, stop and move it before continuing.
+
 ### 1.4 Create runtime directories
 
 ```bash
@@ -156,9 +172,16 @@ An async generator that yields `ActionCall` / `AgentCall` / `HumanCall`. Transla
    yield HumanCall(prompt="Confirm before deleting?")                                   # Human-only
    ```
 
-5. **Compute dynamic values at runtime.** Relative phrases in the task description ("past 7 days", "today", "last 30 days") must be computed inside the generator with `datetime` etc., not hardcoded at write time.
+5. **`HumanCall` vs `wait_for` — strict separation.** Two different waits exist; do not confuse them.
+
+   - **Waiting for the UI to settle** (page render, click reaction, animation): use `yield ActionCall("wait_for", time_seconds=N)` or condition-based `wait_for(text=..., text_gone=..., selector=...)`. Time-bounded.
+   - **Waiting for the user to act** (login, QR-code scan, CAPTCHA solve, destructive-action confirmation): use `yield HumanCall(prompt="...")`. The bridgic framework **truly blocks** that yield until a human response arrives. You do not — and must not — guess how long the user will take.
 
-6. **Keep generator-internal logic minimal.** Code between yields runs in the generator body. **If it raises, the generator is unrecoverable** — `asend()` cannot resume past an exception, so AMPHIFLOW skips per-step retry and jumps directly to full `on_agent` fallback. Keep inline code to variable assignment and pure helpers; push risky operations (network calls, parsing untrusted input) into `ActionCall`-wrapped tools where they can be retried.
+   **Forbidden**: using `wait_for(time_seconds=N)` (any N) to wait for a user action. User logins can take 5 seconds or 5 minutes; a fixed timer either fails too fast or wastes time. Any exploration step tagged `HUMAN:` MUST map to `HumanCall` in the generated code, never to `wait_for`.
+
+6. **Compute dynamic values at runtime.** Relative phrases in the task description ("past 7 days", "today", "last 30 days") must be computed inside the generator with `datetime` etc., not hardcoded at write time.
+
+7. **Keep generator-internal logic minimal.** Code between yields runs in the generator body. **If it raises, the generator is unrecoverable** — `asend()` cannot resume past an exception, so AMPHIFLOW skips per-step retry and jumps directly to full `on_agent` fallback. Keep inline code to variable assignment and pure helpers; push risky operations (network calls, parsing untrusted input) into `ActionCall`-wrapped tools where they can be retried.
 
 ### 2.4 `on_agent` — only for `AGENT` or `AMPHIFLOW`
 
@@ -321,3 +344,11 @@ if __name__ == "__main__":
 6. **No `config.py` by default.** Inline `os.getenv` in main.py. Split into a `config.py` only if env loading grows complex (many vars, validation, defaults).
 
 ---
+
+## Update build_context.md
+
+After Phase 4 completes, edit `<PROJECT_ROOT>/.bridgic/build_context.md`:
+1. Replace the `## Outputs → generator_project` placeholder line `generator_project: (filled by Phase 4)` with the absolute path to `<PROJECT_ROOT>/<project-name>/`.
+2. Refresh the `env_ready:` block: read `<PROJECT_ROOT>/pyproject.toml` and replace the content under `--- pyproject.toml ---` with its current text. This keeps Phase 5 (verify) accurate about which packages are installed.
+
+---

agents/amphibious-config.md

@@ -13,8 +13,12 @@ tools: ["AskUserQuestion", "Bash", "Read", "Write"]
 
 # Amphibious Config Agent
 
+> **Not a dispatchable subagent.** This agent is interactive (uses `AskUserQuestion` / equivalent ask-the-user mechanism) and runs **inline** in the calling command's thread. Do not register it under `.claude-plugin/plugin.json` `agents:` — only `amphibious-explore`, `amphibious-code`, and `amphibious-verify` are dispatchable.
+
 You are a build-pipeline configuration specialist. Your job is to interactively determine project-mode / LLM / domain-specific settings, run environment setup, and write the consolidated `build_context.md` that every later agent reads.
 
+Every user-facing prompt in this document follows `{PLUGIN_ROOT}/agents/human-interaction-protocol.md`. Inside Claude Code you are running inline in `/build`'s thread (Tier 1 — use `AskUserQuestion`); inside OpenClaw the host follows this same methodology in Tier 2 (chat message + await textual reply). The question content below is identical across both; only the transport differs.
+
 ## Input
 
 The calling command passes the inputs already established in Phase 1 of `/build`:
@@ -33,7 +37,9 @@ This agent runs interactively from the very first step; there are no startup fil
 
 ## Step 1: Project Mode
 
-Present via `AskUserQuestion`:
+**Ask the user** with these exact options. Use the platform's structured-question tool if one is available (e.g. Claude Code's `AskUserQuestion`); otherwise send the question as a single message and wait for the user's reply. **Do not also emit the question as chat text alongside the tool call** — the question is sent once.
+
+Question:
 
 > Choose project mode:
 >
@@ -54,13 +60,13 @@ Decide whether to set up LLM — set `llm_configured` to `yes` or `no`.
   ```
 
   - Exit 0: variables present — proceed.
-  - Exit 1: list missing variables; create `.env`, ask the user to fill it, re-run the check; do not proceed until exit 0.
+  - Exit 1: use the same ask-the-user mechanism as Step 1. Tell the user the missing variables and ask whether to (a) write a `.env` skeleton for them to fill, or (b) wait while they `export` the vars in their shell. Then re-run `check-dotenv.sh` until exit 0; do not proceed until exit 0.
 
   Set `llm_configured = yes`.
 
 - **If `project_mode == workflow`**: analyze the task description.
 
-  - **If task contains AI-suggestive operations** (e.g. "extract key information", "analyze content", "generate a report"), ask via `AskUserQuestion`:
+  - **If task contains AI-suggestive operations** (e.g. "extract key information", "analyze content", "generate a report"), ask using the same mechanism as Step 1:
 
     > Your task description mentions operations that may benefit from AI/LLM capabilities (e.g. content analysis, intelligent extraction). Configure an LLM?
     >
@@ -74,13 +80,28 @@ Decide whether to set up LLM — set `llm_configured` to `yes` or `no`.
 
 ## Step 3: Domain-specific Configuration
 
-If `SELECTED_DOMAIN` is resolved AND `{PLUGIN_ROOT}/domain-context/<SELECTED_DOMAIN>/config.md` exists, read that file and follow its instructions verbatim — it tells you which questions to ask the user (still via `AskUserQuestion`) and which keys to record. Capture each answer as `domain_config[<key>] = <value>`.
+If `SELECTED_DOMAIN` is resolved AND `{PLUGIN_ROOT}/domain-context/<SELECTED_DOMAIN>/config.md` exists, read that file and follow its instructions verbatim — it tells you which questions to ask the user (using the same ask-the-user mechanism as Step 1) and which keys to record. Capture each answer as `domain_config[<key>] = <value>`.
 
 If no `config.md` exists, skip this step and treat `domain_config` as empty.
 
 
 ## Step 4: Environment Setup
 
+### 4.0 Side-effect checkpoint (before running any setup script)
+
+Steps 1–3 only collected decisions; nothing on disk has been mutated yet beyond the `.env` skeleton (if Step 2 wrote one). Step 4.1 is the **first script that touches the user's toolchain** — it may install `uv` to PATH, create `pyproject.toml`, and otherwise alter PROJECT_ROOT in ways the user might want to see coming.
+
+Before invoking `setup-env.sh`, ask the user via the Human Interaction Protocol (Tier 1 in Claude Code, Tier 2 in OpenClaw — same content, different transport):
+
+> About to run environment setup against `{PROJECT_ROOT}`:
+> - verify the `uv` toolchain is on PATH (auto-install if missing)
+> - run `uv init --bare` if no `pyproject.toml` exists yet
+>
+> **1. Run setup now** — proceed with `setup-env.sh`.
+> **2. Pause** — I want to inspect or change something first.
+
+On **1** continue to 4.1. On **2** wait for the user's follow-up, then re-prompt.
+
 ### 4.1 uv toolchain + PROJECT_ROOT uv project
 
 ```bash

agents/amphibious-explore.md

@@ -8,7 +8,7 @@ description: >-
   re-observed each time the plan is carried out). Produces a pseudocode
   operation sequence with inline stability annotations plus any key-artifact
   files capturing the observed states the plan references.
-tools: ["Bash", "Read", "Grep", "Write", "Edit"]
+tools: ["AskUserQuestion", "Bash", "Read", "Grep", "Write", "Edit"]
 ---
 
 # Amphibious Explore Agent
@@ -94,10 +94,16 @@ To record loops and branches faithfully, you must **probe their boundaries and a
 
 Secondly, mark **human handoffs** — points where the task requires intervention that automation cannot resolve alone (authentication wall, CAPTCHA, destructive-confirm dialog, permissions you lack, ambiguous UI, unexpected error state). Record each as a `HUMAN:` step in the plan, describing what the human must do and the signal to resume.
 
-When you encounter a handoff during exploration, you **MUST** request human:
+When you encounter a handoff *during exploration itself* (e.g. the target site shows a login wall and you cannot probe further until the user logs in), you **MUST** ask the user following `{PLUGIN_ROOT}/agents/human-interaction-protocol.md`. Pick the highest tier your current runtime supports:
 
-- **Request** specific human intervention.
-- **Resume** exploration from the same point once the human confirms the obstacle is cleared.
+- **Claude Code subagent (Tier 1).** This agent's `tools:` declares `AskUserQuestion`. Use it: ask one focused question that names exactly what the user must do (e.g. "Please log into <site> in the open browser, then choose 1. `done` / 2. `cancel exploration`."). Wait for the structured reply before resuming.
+- **OpenClaw host running this methodology directly (Tier 2).** No `AskUserQuestion` here, but you have the chat / message channel captured by the host (`notifyChannel` / `notifyTarget`). Send a clearly formatted chat message that begins with `[USER ACTION REQUIRED]`, states exactly what to do (open which URL, click what, paste which token), and tells the user how to reply (`reply "done" once login completes`, or `reply with the token`). Wait for the user's textual reply before resuming.
+- **Subagent without `AskUserQuestion` and no chat channel (Tier 3 — fallback).** Stop work and return a structured "human input needed" status to the calling command — include the prompt text and the resume signal. The calling command runs in Tier 1 or Tier 2 and asks on your behalf, then re-dispatches you with the answer.
+- **Forbidden anti-pattern (all tiers).** Do **not** fall back to `echo "please do X" + until [ -f /tmp/flag ]; do sleep 3; done`. The user sees only a silent "Running" indicator and has no idea what is being asked. This is the canonical violation called out in the protocol.
+
+Once the user confirms the obstacle is cleared, **resume** exploration from the same point.
+
+Each `HUMAN:` step in the Operation Sequence will map **one-to-one** to a `HumanCall` yield in the generated code (see `amphibious-code.md` Phase 2.3). The framework blocks at that yield until the user responds — you do not need to estimate how long the user will take, and you must **not** record a fallback `wait_for(time_seconds=...)` to "give the user time".
 
 Finally, record only the **minimal chain of operations** needed to achieve the goal. Exclude:
 
@@ -128,7 +134,13 @@ After exploration, run the cleanup protocol recorded in the Domain Guidance to r
 
 ## Generate Report
 
-Write `exploration_report.md` plus all saved artifact files. The report has **up to three sections** — §1 is optional, §3 is omitted when no volatile data was captured.
+Write all outputs into `<PROJECT_ROOT>/.bridgic/explore/`:
+- `exploration_report.md` — the report itself
+- artifact files (e.g. `list_state.txt`, `detail_state.txt`) at the same directory level
+
+Do not nest under any further subdirectory. The path `<PROJECT_ROOT>/.bridgic/explore/` is the canonical location read by `amphibious-code.md` Phase 3 and `amphibious-verify.md`.
+
+The report has **up to three sections** — §1 is optional, §3 is omitted when no volatile data was captured.
 
 ### 1. Domain Guidance
 
@@ -206,3 +218,8 @@ A pseudocode-style list. Use indentation and control-flow keywords (`FOR`, `WHIL
 ### 3. Artifact Files
 
 List saved artifact paths. Each entry annotates **what extractable content** the file contains — enough for a reader to know which file documents which volatile data without opening every one.
+
+## Update build_context.md
+
+After writing the report and artifacts, edit `<PROJECT_ROOT>/.bridgic/build_context.md`:
+1. Replace the `## Outputs → exploration_report` placeholder line `exploration_report: (filled by Phase 3)` with the absolute path to `exploration_report.md` (e.g. `exploration_report: /abs/path/.bridgic/explore/exploration_report.md`).