bitsky-tech · lynnlink · Apr 29, 2026 · Apr 20, 2026 · Apr 21, 2026 · Apr 21, 2026
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
@@ -6,10 +6,7 @@
     "./commands/"
   ],
   "agents": [
-    "./agents/browser-explorer.md",
-    "./agents/amphibious-generator.md",
-    "./agents/amphibious-verify.md"
-
+    "./agents/amphibious-code.md"
   ],
   "skills": []
 }
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -8,29 +8,33 @@ Agent skill & knowledge corpus for the Bridgic ecosystem — providing skills, a
 AmphiLoop/
 ├── CLAUDE.md                          ← this file
 ├── .claude-plugin/
-│   └── plugin.json                    ← Claude Code plugin registration
+│   ├── plugin.json                    ← Claude Code plugin registration
+│   └── marketplace.json               ← marketplace metadata
 ├── skills/                            ← domain knowledge: "what it is, how to use it"
 │   ├── manifest.ini                  ← skill source registry (repo, ref, paths)
 │   ├── README.md                      ← manifest docs + auto-generated skill table
 │   ├── bridgic-browser/               ← browser automation CLI + SDK
 │   ├── bridgic-amphibious/            ← dual-mode agent framework
 │   └── bridgic-llms/                  ← LLM providers and initialization
 ├── agents/                            ← execution methodology: "how to do it well"
-│   ├── browser-explorer.md            ← CLI exploration expertise
-│   ├── amphibious-generator.md        ← code generation expertise
+│   ├── amphibious-config.md           ← inline-loaded by /build Phase 2 (interactive; NOT a subagent)
+│   ├── amphibious-explore.md          ← abstract exploration methodology
+│   ├── amphibious-code.md             ← code generation expertise
 │   └── amphibious-verify.md           ← project verification expertise
 ├── commands/                          ← user-invocable workflows (thin orchestrators)
-│   └── build-browser.md               ← /build-browser pipeline
-├── examples/                          ← static example docs (not auto-scanned by Claude Code)
-│   ├── build-browser-code-patterns.md ← browser-specific code patterns
-│   └── build-browser-task-template.md ← TASK.md template for /build-browser Phase 1
+│   └── build.md                       ← /build pipeline (domain-agnostic; accepts --<domain>)
+├── domain-context/                    ← pre-distilled per-domain context injected by /build
+│   └── browser/                       ← intent.md, config.md, explore.md, code.md, verify.md
+│       └── script/                    ← domain-only helpers (e.g. browser-observe.sh)
+├── templates/                         ← static templates read by commands (not auto-scanned by Claude Code)
+│   └── build-task-template.md         ← unified TASK.md template (used by /build Phase 1)
 ├── hooks/                             ← auto-loaded by Claude Code
 │   └── hooks.json                     ← hook definitions
 └── scripts/
     ├── hook/                          ← hook script implementations
     │   └── inject-command-paths.sh     ← injects PLUGIN_ROOT + PROJECT_ROOT when a bridgic command loads
     ├── run/                           ← runtime scripts used by agents
-    │   ├── setup-env.sh               ← auto-install uv + uv init --bare
+    │   ├── setup-env.sh               ← verify uv toolchain (auto-installs if missing) and run `uv init --bare` in PROJECT_ROOT
     │   ├── check-dotenv.sh            ← .env LLM configuration validation
     │   └── monitor.sh                 ← run-and-monitor for amphibious-verify agent
     └── maintenance/                   ← plugin maintenance scripts (manual)
@@ -42,8 +46,9 @@ AmphiLoop/
 | Type | Purpose | Example |
 |------|---------|---------|
 | **Skill** | Domain knowledge reference — loaded on-demand by agents; synced from source repos via `manifest.ini` | bridgic-browser, bridgic-amphibious, bridgic-llms |
-| **Agent** | Deep execution methodology — delegated by commands | browser-explorer, amphibious-generator, amphibious-verify |
-| **Command** | Multi-step orchestrator invoked by user | /build-browser |
+| **Agent** | Deep execution methodology — delegated by commands | amphibious-explore, amphibious-code, amphibious-verify |
+| **Command** | Multi-step orchestrator invoked by user | /build |
+| **Domain Context** | Pre-distilled per-domain rules (`intent.md`, `config.md`, `explore.md`, `code.md`, `verify.md`) injected by `/build` when a domain is selected explicitly via `--<domain>` or auto-detected from `TASK.md` | domain-context/browser |
 
 ## Installation
 
@@ -65,12 +70,12 @@ claude plugin install AmphiLoop
 
 | Agent | When to Use |
 |-------|-------------|
-| **browser-explorer** | Systematically explore a website via CLI, produce structured exploration report |
-| **amphibious-generator** | Generate a complete bridgic-amphibious project from a task description with optional domain context |
+| **amphibious-explore** | Systematically explore a target environment via a domain toolset, produce an executable plan with stability-annotated operations |
+| **amphibious-code** | Generate a complete bridgic-amphibious project from a task description with optional domain context |
 | **amphibious-verify** | Verify a generated amphibious project: inject debug instrumentation, run with monitoring, validate results, clean up |
 
 ## Commands
 
 | Command | When to Use |
 |---------|-------------|
-| **/build-browser** | Turn a browser task into a working bridgic-amphibious project (parse → explore → generate → verify) |
+| **/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`. |
diff --git a/README-zh.md b/README-zh.md
@@ -14,6 +14,12 @@ AmphiLoop 将领域知识和执行方法论封装为三层结构：
 
 三者协同实现端到端流水线：**通过 CLI 探索网站** -> **生成双模 agent 项目** -> **验证执行** — 全程在 agent 内完成。
 
+## 延伸阅读
+
+关于 AmphiLoop 设计动机与思想的长文：
+
+[万字长文！两栖模式构建Agent，与OpenClaw/Hermes不一样的解法——开源AmphiLoop](https://zhangtielei.com/posts/blog-bridgic-amphiloop.html)
+
 ## 安装
 
 ```bash
@@ -24,52 +30,62 @@ claude plugin marketplace add bitsky-tech/AmphiLoop
 claude plugin install AmphiLoop
 ```
 
-或从本地仓库直接安装：
+或从本地仓库安装（把 `marketplace add` 指向本地目录即可——本仓库自带 `.claude-plugin/marketplace.json`，会被识别为 marketplace）：
 
 ```bash
 git clone https://github.com/bitsky-tech/AmphiLoop.git
-claude plugin install /path/to/AmphiLoop
+
+claude plugin marketplace add /path/to/AmphiLoop
+claude plugin install AmphiLoop
 ```
 
-安装后，skills、agents 和 commands（如 `/build-browser`）会自动在 Claude Code 中可用。
+安装后，skills、agents 和 commands（如 `/build`）会自动在 Claude Code 中可用。
 
 ## 使用
 
 ### Commands
 
 Commands 是用户可直接调用的工作流，使用 `/` 前缀触发：
 
-#### `/AmphiLoop:build-browser`
+#### `/AmphiLoop:build`
+
+统一流水线。描述任意任务，列出 agent 应读取的领域参考（SKILL、CLI 帮助、SDK 文档、风格指南），然后要求生成一个可运行项目：
+
+```
+/AmphiLoop:build
+
+我想把 ~/data/inputs 下所有 `orders_*.csv` 汇总成一个 summary.csv —
+按 customer 聚合出每个客户的总额。
+```
 
-描述一个浏览器自动化任务，并要求生成一个稳定可运行的项目：
+**领域标志（可选）** — 在命令后追加 `--<domain>`，即可注入 `domain-context/<domain>/` 下预先蒸馏好的领域上下文。当前已支持：`--browser`。
 
 ```
-/AmphiLoop:build-browser
+/AmphiLoop:build --browser
 
 打开 https://example.com，搜索 "product"，提取前 5 条结果。
 我需要一个能稳定运行的项目。
 ```
 
-你的输入应包含两个关键意图：
-1. **浏览器自动化任务** — 在目标网站上要做什么（导航、点击、提取等）
-2. **生成稳定项目的请求** — 你需要一个能可靠运行的程序/项目
+不带标志时，`/build` 会根据 `TASK.md` 自动识别领域（若没有匹配则回退到通用流程）。用户可随时在 `TASK.md` 中补充额外领域参考。
 
 **执行流程：**
 
-1. **Parse** — 从任务描述中提取 URL、目标和预期输出
-2. **Setup** — 检查环境（uv、依赖、`.env`）
-3. **Explore** — 委派 `browser-explorer` agent 通过 CLI 系统性探索目标网站
-4. **Generate** — 委派 `amphibious-generator` agent 生成完整项目及所有源文件
-5. **Verify** — 委派 `amphibious-verify` agent 注入调试插桩、运行项目、验证结果
+1. **Initialize Task** — 生成 `TASK.md` 模板，用户填写目标、预期输出、**领域参考**；若未带标志则自动识别领域
+2. **Configure Pipeline** — 项目模式（Workflow / Amphiflow）、按需的 LLM 配置，以及任何领域特定配置（例如 `--browser` 模式下询问浏览器环境模式）
+3. **Setup Environment** — 检查 `uv`，执行 `uv init`
+4. **Explore** — 委派 `amphibious-explore` agent 读取用户提供的领域参考并探索环境
+5. **Generate** — 委派 `amphibious-code` agent 生成完整项目及所有源文件
+6. **Verify** — 委派 `amphibious-verify` agent 注入调试插桩、运行项目、验证结果
 
 ### Agents
 
 Agents 是由 commands 调度的执行专家，不由用户直接调用：
 
 | Agent | 功能 |
 |-------|------|
-| **browser-explorer** | 通过 CLI 系统性探索网站，生成结构化的探索报告和快照 |
-| **amphibious-generator** | 根据任务描述和探索报告生成完整的 bridgic-amphibious 项目 |
+| **amphibious-explore** | 通过领域工具集系统性探索目标环境，生成带稳定性标注的可执行操作序列与关键快照 |
+| **amphibious-code** | 根据任务描述和探索报告生成完整的 bridgic-amphibious 项目 |
 | **amphibious-verify** | 注入调试插桩、监控运行、验证结果、清理环境 |
 
 ### Skills
@@ -96,23 +112,24 @@ AmphiLoop/
 │   ├── bridgic-amphibious/      #   双模 Agent 框架
 │   └── bridgic-llms/            #   LLM 提供商集成
 ├── agents/                      # 执行方法论（3 个 agents）
-│   ├── browser-explorer.md      #   CLI 探索专家
-│   ├── amphibious-generator.md  #   代码生成专家
+│   ├── amphibious-explore.md    #   抽象探索方法论
+│   ├── amphibious-code.md       #   代码生成专家
 │   └── amphibious-verify.md     #   项目验证专家
 ├── commands/                    # 用户可调用的工作流
-│   └── build-browser.md         #   端到端流水线
-├── examples/                    # 静态示例文档（不会被自动扫描）
-│   ├── build-browser-code-patterns.md
-│   └── build-browser-task-template.md
+│   └── build.md                 #   统一流水线（可选 --<domain> 标志）
+├── domain-context/              # /build 注入的预蒸馏领域上下文
+│   └── browser/                 #   intent.md / config.md / explore.md / code.md / verify.md（含 script/）
+├── templates/                   # 命令使用的静态模板（不会被自动扫描）
+│   └── build-task-template.md         #   /build 使用的统一 TASK.md 模板
 ├── hooks/                       # 自动加载的事件处理器
 │   └── hooks.json
 └── scripts/                     # Hook 与工具脚本
     ├── hook/
     │   └── inject-command-paths.sh
     ├── run/
-    │   ├── setup-env.sh         #   环境配置（uv、依赖、playwright）
+    │   ├── setup-env.sh         #   校验 uv 工具链；在 PROJECT_ROOT 执行 uv init --bare
     │   ├── check-dotenv.sh      #   LLM 模型配置校验
-    │   └── monitor.sh
+    │   └── monitor.sh           #   amphibious-verify 的 run-and-monitor 脚本
     └── maintenance/
         └── sync-skills.sh       #   从源仓库同步 skills（基于 manifest.ini）
 ```

diff --git a/README.md b/README.md
@@ -14,6 +14,12 @@ AmphiLoop packages domain knowledge and execution methodology into three layers:
 
 Together, they enable an end-to-end pipeline: **explore a website via CLI** -> **generate a dual-mode agent project** -> **verify execution** — all within an agent.
 
+## Further Reading
+
+Long-form pieces on the motivation and design philosophy behind AmphiLoop:
+
+[Beyond Autonomous: Why I'm Building an Amphibious Agent](https://pub.towardsai.net/beyond-autonomous-why-im-building-an-amphibious-agent-fcae9a409220)
+
 ## Installation
 
 ```bash
@@ -24,52 +30,61 @@ claude plugin marketplace add bitsky-tech/AmphiLoop
 claude plugin install AmphiLoop
 ```
 
-Or install directly from a local checkout:
+Or install from a local checkout (point `marketplace add` at the local directory — it's read as a marketplace because the repo ships `.claude-plugin/marketplace.json`):
 
 ```bash
 git clone https://github.com/bitsky-tech/AmphiLoop.git
-claude plugin install /path/to/AmphiLoop
+claude plugin marketplace add /path/to/AmphiLoop
+claude plugin install AmphiLoop
 ```
 
-After installation, skills, agents, and commands (e.g. `/build-browser`) are automatically available in Claude Code.
+After installation, skills, agents, and commands (e.g. `/build`) are automatically available in Claude Code.
 
 ## Usage
 
 ### Commands
 
 Commands are user-invocable workflows. Invoke them with the `/` prefix:
 
-#### `/AmphiLoop:build-browser`
+#### `/AmphiLoop:build`
+
+Unified pipeline. Describe any task, list the domain references the agents should read (SKILLs, CLI help, SDK docs, style guides), and ask to generate a runnable project:
+
+```
+/AmphiLoop:build
+
+I want to aggregate all `orders_*.csv` files under ~/data/inputs into a single
+summary.csv — one row per customer with totals.
+```
 
-Describe a browser automation task and ask to generate a stable, runnable project:
+**Domain flag (optional)** — append `--<domain>` to inject pre-distilled domain context from `domain-context/<domain>/`. Currently supported: `--browser`.
 
 ```
-/AmphiLoop:build-browser
+/AmphiLoop:build --browser
 
 Go to https://example.com, search for "product", and extract the first 5 results.
 I want a project that can run this reliably.
 ```
 
-Your input should contain two key intents:
-1. **A browser automation task** — what to do on the target website (navigate, click, extract, etc.)
-2. **A request to generate a stable project** — you want a working program/project that can run reliably
+Without a flag, `/build` auto-detects the domain from `TASK.md` (and falls back to a generic flow if none matches). Users can always supply additional domain references in `TASK.md`.
 
 **What happens under the hood:**
 
-1. **Parse** — Extracts URL, goal, and expected output from your task description
-2. **Setup** — Checks environment (uv, dependencies, `.env`)
-3. **Explore** — Delegates to `browser-explorer` agent to systematically explore the target website via CLI
-4. **Generate** — Delegates to `amphibious-generator` agent to produce a complete project with all source files
-5. **Verify** — Delegates to `amphibious-verify` agent to inject debug instrumentation, run the project, and validate results
+1. **Initialize Task** — Writes a `TASK.md` template where you fill in goal, expected output, and **Domain References**; auto-detects the domain if no flag was given
+2. **Configure Pipeline** — Project mode (Workflow vs Amphiflow), LLM config if needed, plus any domain-specific configuration (e.g. browser environment mode when `--browser` is active)
+3. **Setup Environment** — Checks `uv`, runs `uv init`
+4. **Explore** — Delegates to `amphibious-explore` agent, which reads your domain references and probes the environment
+5. **Generate** — Delegates to `amphibious-code` agent to produce a complete project with all source files
+6. **Verify** — Delegates to `amphibious-verify` agent to inject debug instrumentation, run the project, and validate results
 
 ### Agents
 
 Agents are execution specialists delegated by commands. They are not called directly by users but are orchestrated internally:
 
 | Agent | What It Does |
 |-------|-------------|
-| **browser-explorer** | Systematically explores a website via CLI, produces a structured exploration report with snapshots |
-| **amphibious-generator** | Generates a complete bridgic-amphibious project from a task description and exploration report |
+| **amphibious-explore** | Systematically explores a target environment via a domain-supplied toolset, produces an executable plan with stability-annotated operations and supporting snapshots |
+| **amphibious-code** | Generates a complete bridgic-amphibious project from a task description and exploration report |
 | **amphibious-verify** | Injects debug instrumentation, runs the project with monitoring, validates results, and cleans up |
 
 ### Skills
@@ -96,23 +111,24 @@ AmphiLoop/
 │   ├── bridgic-amphibious/      #   Dual-mode agent framework
 │   └── bridgic-llms/            #   LLM provider integration
 ├── agents/                      # Execution methodology (3 agents)
-│   ├── browser-explorer.md      #   CLI exploration expert
-│   ├── amphibious-generator.md  #   Code generation expert
+│   ├── amphibious-explore.md    #   Abstract exploration methodology
+│   ├── amphibious-code.md       #   Code generation expert
 │   └── amphibious-verify.md     #   Project verification expert
 ├── commands/                    # User-invocable workflows
-│   └── build-browser.md         #   End-to-end pipeline
-├── examples/                    # Static example docs (not auto-scanned)
-│   ├── build-browser-code-patterns.md
-│   └── build-browser-task-template.md
+│   └── build.md                 #   Unified pipeline (accepts optional --<domain> flag)
+├── domain-context/              # Pre-distilled per-domain context injected by /build
+│   └── browser/                 #   intent.md, config.md, explore.md, code.md, verify.md (+ script/)
+├── templates/                   # Static templates read by commands (not auto-scanned)
+│   └── build-task-template.md         #   Unified TASK.md template used by /build
 ├── hooks/                       # Auto-loaded event handlers
 │   └── hooks.json
 └── scripts/                     # Hook & utility implementations
     ├── hook/
     │   └── inject-command-paths.sh
     ├── run/
-    │   ├── setup-env.sh         #   Environment setup (uv, deps, playwright)
+    │   ├── setup-env.sh         #   Verify uv toolchain; uv init --bare in PROJECT_ROOT
     │   ├── check-dotenv.sh      #   LLM configuration validation
-    │   └── monitor.sh
+    │   └── monitor.sh           #   Run-and-monitor for amphibious-verify
     └── maintenance/
         └── sync-skills.sh       #   Sync skills from source repos via manifest.ini
 ```