refactor: generalize /build with domain-context and abstract agents#1
Merged
refactor: generalize /build with domain-context and abstract agents#1
Conversation
Made-with: Cursor
…ghten the build-browser pipeline so the generated faithfully implements every numbered step from the exploration report (refs and values verbatim, no substitution for steps already captured), and have the verifier cross-check against the report. Merge launch + monitor into a single script: PID-file based resume after human intervention, recursive process-tree kill on timeout, and stale-request cleanup on exit 2 to prevent resume races.
- Delete commands/build-browser.md; /build now accepts an optional --<domain> flag (or auto-detects from TASK.md) to inject pre-distilled context from domain-context/<domain>/ - Add domain-context/browser/ with intent / config / explore / code / verify slices; add Phase 2b in /build for per-domain config with a single end-of-Phase-2 summary confirmation owned by the command - Rename amphibious-explore internal phase "Explore Domain Context" → "Analyse Task"; update all cross-references in commands/build.md - Restructure exploration operation-sequence format: action-only step lines with parameters / stability / notes on indented # comment lines - Sync README / README-zh / CLAUDE.md / hook script comments to the new topology; drop stale build-browser-code-patterns.md reference
…ct paths Drop LOG_FILE and VERIFY_DIR positional args from monitor.sh — the script now derives everything under <WORK_DIR>/.bridgic/verify/ and prints the resolved paths to stdout on every exit. Callers only supply WORK_DIR (and optional TIMEOUT), eliminating a class of mismatches where the monitored VERIFY_DIR didn't line up with where the program actually wrote human_request.json. Update amphibious-verify agent doc to match the new signature.
Add a parameter-setting note in the explore phase: if the task requires login, launch the browser in non-headless mode so the user can complete authentication interactively.
Restructure the /build pipeline to cut redundant token cost and improve hierarchy of the shared build context. Build context as a single index: - /build now writes .bridgic/build_context.md after Phase 2 with Task / Pipeline / References / Environment / Outputs sections. - Task is a TASK.md pointer (not an embedded summary), keeping the user- authored file as the single source of truth. - explore / code / verify agents take exactly two inputs (build_context_path, domain_context_path) and read heavier files (TASK.md, references, SKILL.md) on demand. Phase 2 + 3 merged into agents/amphibious-config.md: - Externalise project-mode, LLM-config, domain-config, env setup, and build_context.md write into a single inline-loaded methodology doc. - /build executes its steps in the main thread instead of delegating to a subagent, since this phase is interactive. - Pipeline workflow renumbered to 5 phases. Agent slimming: - amphibious-explore: stability annotations only on values that vary; probe only branches that affect recorded output; skip artifact section when no VOLATILE parameter exists. - amphibious-code: skills moved to on-demand reads; inline cheatsheet of the common bridgic-amphibious / bridgic-llms imports. - amphibious-verify: Phase 1.1 / 1.2 / 1.3 each gated on a grep precondition (skip RunMode.WORKFLOW override when already pinned, skip human_input override when no HumanCall, skip loop slicing when no dynamic loop). - monitor.sh: success-path log tail trimmed from 30 to 10 lines.
Pull updated bridgic-amphibious skill content from fix/skills-and-amphibious-fallback (manifest ref bump). Notable upstream changes: - Scaffold reduced to a single amphi.py (no more multi-file project tree). CLI no longer takes -n; --base-dir / --task only. Runtime concerns (LLM credentials, entry script) are intentionally left to the caller. - bridgic-amphibious now resolved through the btsk-repo private index with version pin ==0.1.1.dev17 (deps.ini). install-deps.sh requires BRIDGIC_DEV_INDEX env var. - AMPHIFLOW fallback documentation split: ActionCall tool failure (per-step retry) vs generator-internal exception (jumps directly to full on_agent fallback).
The bridgic-amphibious scaffold now produces a single amphi.py instead
of a multi-file project tree, and pins itself to a private package
index. Realign every doc and script that referenced the old layout.
Generated project layout (Phase 4 of /build) is now:
<PROJECT_ROOT>/<project-name>/
pyproject.toml # install-deps.sh
amphi.py # scaffold; agent edits
main.py # this agent writes (entry point)
.env (if LLM) # placeholders, user fills
log/ result/ # mkdir
The subdir isolates the uv project from PROJECT_ROOT, which is now just
a workspace holding TASK.md and .bridgic/.
Per-file changes:
- agents/amphibious-code.md: full rewrite. Phase 1 = mkdir +
install-deps.sh + scaffold + log/result. Phase 2 reorganised into
Context / Hooks / on_workflow / on_agent / Tools / Helpers. Phase 4
builds main.py with inline os.getenv (no separate config.py by
default). Added best practices: AMPHIFLOW generator-internal
exception caveat, override-only-needed hooks, think_unit
max_attempts sizing, snapshot() phase boundaries, request_human
auto-injection, mode-to-method override mapping.
- agents/amphibious-verify.md: agents.py -> amphi.py; monitor.sh
invocation uses absolute {generator_project} (no PROJECT_ROOT
double-prefix).
- agents/amphibious-config.md: Step 4 split — 4.1 verify uv, 4.2
fail-fast on missing BRIDGIC_DEV_INDEX, 4.3 domain tool install
deferred to explore agent.
- commands/build.md: Phase 4 mode/LLM mapping no longer mentions
config.py; generator_project documented as the populated subdir.
- domain-context/browser/code.md: agents.py / workers.py / helpers.py
/ tools.py / task.md sections folded into amphi.py-centric sections;
main.py example uses hardcoded GOAL constant.
- scripts/run/setup-env.sh: dropped uv init; only verifies uv
toolchain. PROJECT_ROOT no longer becomes a uv project.
- CLAUDE.md: list amphibious-config.md in agents/ tree (inline-only);
refresh setup-env.sh description.
added 7 commits
April 27, 2026 15:00
- amphibious-config Step 4: drop the BRIDGIC_DEV_INDEX check section; Step 4 now only verifies the uv toolchain. 4.3 renumbered to 4.2. - amphibious-code Phase 1.2: drop the BRIDGIC_DEV_INDEX precondition note after install-deps.sh. Phase 5 (.env + generated README, which also surfaced BRIDGIC_DEV_INDEX as a prerequisite) and the final Output recap removed entirely. - amphibious-explore: trim the "three concerns" preamble; the same structure is already enforced by the report sections below. - build Phase 1: wording tweak — read TASK.md and "understand" instead of "extract" (no behavioural change).
…strap
- commands/build.md: lift per-phase delegation prose into one
"Agent invocation contract" section; Phases 3/4/5 reference it instead
of repeating the two-path rules. Correct setup-env description to
toolchain-only (per-project uv init lives inside <project-name>/).
- amphibious-{explore,code,verify}.md: add a Bootstrap section telling
each subagent to batch its certainly-required startup Reads in a
single parallel tool turn (Round 1 = invocation paths, Round 2 =
paths derived from build_context.md). Trims cache-read amplification
at agent startup.
- amphibious-config.md: enumerate skills in the build_context.md schema
as a name -> SKILL.md absolute-path map.
- domain-context/browser/{config,verify}.md: Phase 6 -> Phase 5 to match
the simplified 5-phase pipeline.
- Tighten Input/prose in agents/*.md and domain-context/browser/code.md
without behavioural change.
- setup-env.sh now runs `uv init --bare` in PROJECT_ROOT and appends
pyproject.toml to the ENV_READY block; every later phase uv-adds
into this single shared env.
- amphibious-code installs runtime deps into PROJECT_ROOT and reads
.env via Path(__file__).parent.parent — no more .env relocation.
- monitor.sh and the verify agent's human_input override now write
under <PROJECT_ROOT>/.bridgic/verify/, next to build_context.md
and explore/, instead of polluting the generator project.
- build_context.md schema drops the skills: index (skill paths now
live inline in agent docs); env_ready: carries the pyproject.toml
dump, refreshed after Phase 3 / 4.
- New domain-context/browser/script/browser-observe.sh wrapper bundles
act + tabs + snapshot into one explore tool call.
- browser code.md aligns runtime user_data_dir to
{PROJECT_ROOT}/.bridgic/browser/, matching config / explore / verify.
- sync-skills.sh README table drops the now-redundant Ref column.
- CLAUDE.md / README trees and script descriptions synced.
- build.md: Phases 3 and 5 now execute their methodology inline (Phase 2 style) instead of delegating to subagents, so HUMAN: handoffs and the verify-time human_input signal-file loop reach the user without crossing a subagent boundary. Phase 4 stays as the only subagent delegation. The shared `build_context_path` / `domain_context_path` resolution moved up into the Path variables block. - amphibious-config.md: added subagent-style frontmatter (name / description / tools), retitled "Amphibious Config Agent", introduced ## Input and ## Bootstrap sections so its form parallels explore / code / verify even though /build runs it inline. - plugin.json: only amphibious-code is registered as a subagent now; config / explore / verify are inline-only methodology docs.
Merged
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
2 participants
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
Generalizes the build pipeline from a browser-only flow into a domain-agnostic one, restructures the agents around abstract methodology, and tightens the runtime contract shared by all phases.
Pipeline & commands
/build-browserinto a single/buildcommand that accepts an optional--<domain>flag; without a flag, the domain is auto-detected fromTASK.mdand falls back to a generic flow.domain-context/<domain>/(currentlybrowser/) holding pre-distilledintent.md,config.md,explore.md,code.md,verify.md(+script/) injected by/buildwhen a domain is selected.templates/build-task-template.mdas the single TASK.md template used by/buildPhase 1./buildinvocation contract and adds subagent bootstrap so phases share context.Agents
amphibious-explore(replacesbrowser-explorer),amphibious-code(renamed fromamphibious-generator),amphibious-verify.amphibious-config— inline-loaded by/buildPhase 2 (interactive; not a subagent).Runtime & scripts
uvproject atPROJECT_ROOTacross all build phases (setup-env.shrunsuv init --bare).scripts/run/monitor.sh: PID-file based resume after human intervention, recursive process-tree kill on timeout, stale-request cleanup on exit.inject-command-paths.sh) suppliesPLUGIN_ROOT/PROJECT_ROOTto bridgic commands.Skills & docs
bridgic-amphibiousskill (SKILL.md, api-reference.md, architecture.md) and bumpsmanifest.ini.plugin.jsonwith the newamphi.pyscaffold.claude plugin marketplace add <local-path>followed byclaude plugin install AmphiLoop.agents/browser-explorer.md,agents/amphibious-generator.md,commands/build-browser.md,examples/build-browser-*.md.Test plan
claude plugin marketplace add <local-path>thenclaude plugin install AmphiLoopsucceeds from a fresh checkout/AmphiLoop:build(no flag) on a non-browser TASK.md falls back to the generic flow/AmphiLoop:build --browseron a browser TASK.md picks updomain-context/browser/and runs the full Initialize → Configure → Setup → Explore → Generate → Verify pipeline end-to-end--browserresolves to the browser domainuvproject atPROJECT_ROOT; phases 4–6 reuse it without re-initscripts/run/monitor.shresumes from PID file after a paused/interactive session and cleanly tree-kills on timeoutscripts/maintenance/sync-skills.shproduces a clean diff against currentskills/content.github/workflows/validate.ymlpasses on the PR