Initial rrweb SGrobot skill package

references/sgrobot-adapter.md

@@ -0,0 +1,74 @@
+# SGrobot Adapter Reference
+
+## Boundary
+
+SGrobot uses two runtime artifact families:
+
+- `plan_templates/<task>/PlanTemplate.toml`: business orchestration, selectable as a digital employee task.
+- `.sgclaw-workspace/skills/<skill>/SKILL.toml`: atomic runtime capability loaded by Skill Catalog.
+
+The Codex-facing `SKILL.md` in this repository only teaches an agent how to generate those artifacts.
+
+## Generated Flow Shape
+
+For each rrweb semantic trace, generate one business-specific package:
+
+```text
+plan_templates/rrweb-<flow>/PlanTemplate.toml
+.sgclaw-workspace/skills/rrweb-<flow>-execute/SKILL.toml
+.sgclaw-workspace/skills/rrweb-<flow>-execute/scripts/execute_trace.js
+.sgclaw-workspace/skills/rrweb-<flow>-execute/trace.semantic.json
+```
+
+Do not generate a single universal runtime skill that expects `trace_path` unless SGrobot core gains stable per-step argument passing. Current stable PlanTemplate usage binds a step to a skill name; the runtime resolves that skill's primary tool.
+
+## PlanTemplate Mapping
+
+Use three steps:
+
+1. `open-target-page`: `skills = ["browser.open_url"]`; description includes the trace `startUrl`.
+2. `run-recorded-flow`: `skills = ["rrweb-<flow>-execute"]`; executes generated page script with sgBrowser.
+3. `save-result`: `skills = ["json.save_result"]`; saves structured output.
+
+Set `requires_approval = true` on `run-recorded-flow` when `--default-mode execute` is used and the trace includes mutating actions such as `click`, `fill`, `select`, `check`, `submit`, or `risk = "write"`.
+
+## Runtime Skill Mapping
+
+Generated `SKILL.toml` should use:
+
+```toml
+[[tools]]
+name = "execute_trace"
+kind = "sgbrowser_action"
+command = "sgBrowserExcuteJsCodeByDomain"
+expected_domain = "<domain from startUrl>"
+
+[tools.args]
+script_path = "scripts/execute_trace.js"
+```
+
+Keep `sgBrowserExcuteJsCodeByDomain` and the `sgBrowerserOpenPage` spelling used by the existing SGrobot project. Do not replace this path with Playwright, CDP, or a generic browser action.
+
+## Runtime Script Rules
+
+The generated `execute_trace.js` runs inside the target page. It should:
+
+- Default to `dry-run` unless the generator is called with `--default-mode execute`.
+- Resolve target elements by stable CSS selector first, XPath second, visible text fallback last.
+- Return structured JSON with `ok`, `mode`, `trace_id`, `url`, `title`, and per-action results.
+- Stop on the first failed action and include an error message.
+
+## Verification
+
+After generating into a SGrobot repo:
+
+```bash
+node scripts/generate_sgrobot_flow.mjs --trace examples/basic-trace.json --out /Users/zhaoyilun/projects/sgrobot-architecture-design --default-mode dry-run
+```
+
+Then verify in SGrobot:
+
+```powershell
+Invoke-RestMethod 'http://127.0.0.1:42617/api/debug/plans?limit=20' | ConvertTo-Json -Depth 5
+Invoke-RestMethod 'http://127.0.0.1:42617/api/skill' | ConvertTo-Json -Depth 4
+```