claw/docs/superpowers/plans/2026-04-06-scene-skill-runtime-routing-plan.md

Scene Skill Runtime Routing Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Add a first scene-routing slice that recognizes staged business scenes from natural language and dispatches them through browser-backed execution, with fault-details-report using direct browser execution and 95598-repair-city-dispatch using agent-mediated browser execution.

Architecture: Introduce a small registry module that loads the first staged scene.json contracts plus runtime dispatch policy from the external skill_staging root. Route matched scenes through one of two paths: direct_browser scenes execute through compat orchestration without the model choosing tools, while agent_browser scenes stay in the existing agent flow but get scene-specific browser-first prompt injection. Both modes must still execute through the existing BrowserScriptSkillTool / browser backend path so the final business action uses browser-internal methods.

Tech Stack: Rust, serde/JSON metadata loading, existing compat orchestration/runtime/workflow layers, browser-backed skill tools, focused cargo test coverage.

---

File Map

Create:

• src/runtime/scene_registry.rs — load staged scene metadata, attach runtime dispatch policy, expose matching helpers for the first slice.
• tests/scene_registry_test.rs — focused tests for registry loading, matching, and policy behavior.

Modify:

• src/runtime/mod.rs — export the new scene registry module/types used by runtime and compat layers.
• src/compat/config_adapter.rs — verify the moved external skill_staging root resolves to the staged skills child, and only change path resolution if a targeted regression proves it is insufficient.
• src/runtime/engine.rs — inject scene-specific browser-first contracts for agent_browser scenes and keep existing Zhihu prompt behavior intact.
• src/compat/workflow_executor.rs — extend route detection and direct execution support for fault-details-report using the browser-backed skill path.
• src/compat/orchestration.rs — let primary orchestration prefer direct execution for direct_browser scenes while leaving agent_browser scenes in the agent path.
• src/compat/browser_script_skill_tool.rs — expose the thinnest reusable browser-backed execution helper needed so direct scene execution can reuse the same browser_script semantics instead of drifting into a duplicate local path.
• src/compat/runtime.rs — ensure runtime sees the staged skills root and continues exposing browser-backed scene tools.
• tests/compat_config_test.rs — add path-resolution coverage for the staged external root.
• tests/runtime_profile_test.rs — add scene-specific instruction contract assertions.
• tests/browser_script_skill_tool_test.rs — add coverage for any new reusable direct-execution helper introduced in the browser-script layer.
• tests/compat_runtime_test.rs — add orchestration/direct-route coverage for the new scene behavior.

Reference:

• docs/superpowers/specs/2026-04-06-scene-skill-runtime-routing-design.md
• D:\data\ideaSpace\rust\sgClaw\claw\claw\skills\skill_staging\scenes\fault-details-report\scene.json
• D:\data\ideaSpace\rust\sgClaw\claw\claw\skills\skill_staging\scenes\95598-repair-city-dispatch\scene.json
• D:\data\ideaSpace\rust\sgClaw\claw\claw\skills\skill_staging\skills\fault-details-report\SKILL.toml
• D:\data\ideaSpace\rust\sgClaw\claw\claw\skills\skill_staging\skills\95598-repair-city-dispatch\SKILL.toml

Task 1: Add Scene Registry And Matching

Files:

• Create: src/runtime/scene_registry.rs

• Modify: src/runtime/mod.rs

• Test: tests/scene_registry_test.rs

• Step 1: Write the failing registry tests

Add tests that prove the first-slice registry can:

• load fault-details-report with dispatch_mode = direct_browser
• load 95598-repair-city-dispatch with dispatch_mode = agent_browser
• match natural-language phrases like 导出故障明细 and 95598抢修市指监测
• ignore missing/broken scene files without panicking

Example assertions to include:

assert_eq!(entry.scene_id, "fault-details-report");
assert_eq!(entry.dispatch_mode, DispatchMode::DirectBrowser);
assert_eq!(entry.tool_name(), "fault-details-report.collect_fault_details");
assert_eq!(entry.expected_domain, "__scene_fault_details__");

assert_eq!(matched.scene_id, "95598-repair-city-dispatch");
assert_eq!(matched.dispatch_mode, DispatchMode::AgentBrowser);

• Step 2: Run the new registry tests to verify they fail

Run:

cargo test scene_registry --test scene_registry_test -- --nocapture

Expected: FAIL because src/runtime/scene_registry.rs and the exported registry APIs do not exist yet.

• Step 3: Implement the minimal scene registry module

Create src/runtime/scene_registry.rs with:

• a small deserialized scene metadata struct for scene.json
• a DispatchMode enum
• a single runtime registry-entry struct combining scene metadata plus runtime policy
• first-slice hardcoded runtime policy for the two initial scenes
• helper methods like:

pub fn load_first_slice_scene_registry() -> Vec<SceneRegistryEntry>
pub fn match_scene_instruction(instruction: &str) -> Option<SceneRegistryEntry>

Use deterministic keyword/alias matching only. Do not add embeddings, fuzzy search, or generic scoring infrastructure beyond what the spec requires.

• Step 4: Export the registry from src/runtime/mod.rs

Expose the new types/helpers needed by runtime and compat layers, for example:

mod scene_registry;

pub use scene_registry::{
    load_first_slice_scene_registry,
    match_scene_instruction,
    DispatchMode,
    SceneRegistryEntry,
};

• Step 5: Run the registry tests to verify they pass

Run:

cargo test scene_registry --test scene_registry_test -- --nocapture

Expected: PASS

• Step 6: Commit Task 1

git add src/runtime/scene_registry.rs src/runtime/mod.rs tests/scene_registry_test.rs
git commit -m "feat: add staged scene registry matching"

Task 2: Verify Staged Skills Root Resolution

Files:

• Modify if needed: src/compat/config_adapter.rs:94

• Modify if needed: src/compat/runtime.rs:152

• Test: tests/compat_config_test.rs

• Step 1: Write the targeted staged-root path test

Add a focused test that proves an external configured skill_staging root resolves to its skills child and preserves current nested-skills behavior.

Add a test shape like:

let staged_root = root.join("external/skill_staging");
fs::create_dir_all(staged_root.join("skills")).unwrap();
fs::create_dir_all(staged_root.join("scenes")).unwrap();

let settings = DeepSeekSettings {
    api_key: "key".to_string(),
    base_url: "https://api.deepseek.com".to_string(),
    model: "deepseek-chat".to_string(),
    skills_dir: Some(staged_root.clone()),
};

assert_eq!(resolve_skills_dir(&root, &settings), staged_root.join("skills"));

• Step 2: Run the focused config test and record the actual result

Run:

cargo test --test compat_config_test resolve_skills_dir_ -- --nocapture

Expected: either

• PASS immediately, proving current path resolution already supports the staged-root contract, or

• FAIL with a concrete staged-root regression that justifies a minimal config fix.

• Step 3: Only if the staged-root test fails, implement the narrowest config fix

If the test fails, update src/compat/config_adapter.rs so configured external staged roots resolve to the staged skill package directory used by runtime skill loading. Keep the change narrow:

• preserve current behavior for normal skills roots

• add the smallest extra branch needed for the failing staged-root case

• do not create a broad path-discovery system

• Step 4: Verify runtime alignment with the resolved staged skills root

Confirm src/compat/runtime.rs still uses the resolved skills_dir as-is. If no runtime code change is needed after the test outcome, leave the file untouched and rely on test coverage.

• Step 5: Run the focused config tests to verify they pass

Run:

cargo test --test compat_config_test resolve_skills_dir_ -- --nocapture

Expected: PASS

• Step 6: Commit Task 2

git add src/compat/config_adapter.rs src/compat/runtime.rs tests/compat_config_test.rs
git commit -m "test: verify staged scene skill root resolution"

Task 3: Inject Agent-Browser Scene Contract For 95598

Files:

• Modify: src/runtime/engine.rs:135

• Test: tests/runtime_profile_test.rs

• Step 1: Write the failing instruction-contract tests

Add focused tests proving that when the instruction matches 95598-repair-city-dispatch, RuntimeEngine::build_instruction(...) includes a scene-specific browser contract requiring the tool 95598-repair-city-dispatch.collect_repair_orders first.

Example assertion pattern:

let instruction = engine.build_instruction(
    "请做95598抢修市指监测",
    Some("https://example.invalid/dispatch"),
    Some("95598抢修-市指"),
    true,
);

assert!(instruction.contains("95598-repair-city-dispatch.collect_repair_orders"));
assert!(instruction.contains("browser workflow, not a text-only task"));
assert!(instruction.contains("generic browser probing only after"));

Also add a negative control showing unrelated tasks do not receive this scene contract.

• Step 2: Run the focused runtime-profile tests to verify they fail

Run:

cargo test --test runtime_profile_test 95598 -- --nocapture

Expected: FAIL because no scene-specific contract is injected yet.

• Step 3: Implement minimal scene-aware prompt injection

Update src/runtime/engine.rs to:

• query the new scene matcher
• when the matched scene is agent_browser, append a scene execution contract section
• preserve existing Zhihu prompt sections unchanged

Keep the contract explicit and narrow, for example:

Scene execution contract:
- Matched scene: 95598-repair-city-dispatch
- Required tool: 95598-repair-city-dispatch.collect_repair_orders
- This is a browser workflow, not a text-only task.
- Business data must come from the matched browser-backed scene tool.
- Only use generic browser probing after the matched scene tool fails.

Do not add hard allowed-tool narrowing in this task; slice one only promises instruction-level enforcement.

• Step 4: Run the focused runtime-profile tests to verify they pass

Run:

cargo test --test runtime_profile_test 95598 -- --nocapture

Expected: PASS

• Step 5: Commit Task 3

git add src/runtime/engine.rs tests/runtime_profile_test.rs
git commit -m "feat: inject 95598 scene browser contract"

Task 4: Add Direct Browser Route For Fault Details

Files:

• Modify: src/compat/workflow_executor.rs:58

• Modify: src/compat/orchestration.rs:9

• Modify: src/compat/browser_script_skill_tool.rs:101

• Test: tests/browser_script_skill_tool_test.rs

• Test: tests/compat_runtime_test.rs

• Step 1: Write the failing route-detection tests

Add focused tests that prove:

• natural language like 导出故障明细 is detected as a direct scene route
• primary orchestration is selected for that scene
• missing scene metadata leaves unrelated routing unchanged

Target the existing routing seams with test shapes like:

assert!(sgclaw::compat::orchestration::should_use_primary_orchestration(
    "导出故障明细",
    Some("https://example.invalid/fault"),
    Some("故障明细"),
));

and a focused route assertion using the new route enum variant.

• Step 2: Run the focused route tests to verify they fail

Run:

cargo test --test compat_runtime_test fault_details -- --nocapture

Expected: FAIL because no direct scene route exists yet.

• Step 3: Write the failing browser-script helper tests

Add focused tests in tests/browser_script_skill_tool_test.rs for the thinnest reusable helper needed by direct scene execution. The tests should prove that the helper:

• reads the packaged script from the skill root

• wraps args exactly like BrowserScriptSkillTool

• invokes browser Eval

• returns normalized serialized output

• fails clearly when required fields like expected_domain are missing

• Step 4: Run the focused browser-script helper tests to verify they fail

Run:

cargo test --test browser_script_skill_tool_test -- --nocapture

Expected: FAIL because the reusable helper does not exist yet.

• Step 5: Implement the reusable browser-backed execution helper

Update src/compat/browser_script_skill_tool.rs with the smallest reusable helper that direct scene execution can call while preserving the same browser_script semantics as normal skill execution. Keep it narrow:

• reuse the same script loading and wrapping rules

• require explicit expected_domain

• return normalized serialized output

• do not introduce a second browser-script execution model

• Step 6: Implement the direct fault-details route on top of that helper

Update src/compat/workflow_executor.rs to:

• introduce a new direct route variant for fault-details-report
• extend detect_route(...) to return it when the scene matcher says direct_browser
• build required args from scene runtime policy
• call the reusable browser-script execution helper
• return normalized serialized tool output

If required scene args cannot be derived safely, return a clear failure instead of guessing.

• Step 7: Wire primary orchestration to prefer the new direct scene route

Update src/compat/orchestration.rs so should_use_primary_orchestration(...) and the direct execution branch treat the new fault-details-report route like the existing direct Zhihu routes.

• Step 8: Run the focused direct-route and helper tests to verify they pass

Run:

cargo test --test browser_script_skill_tool_test -- --nocapture && cargo test --test compat_runtime_test fault_details -- --nocapture

Expected: PASS

• Step 9: Commit Task 4

git add src/compat/browser_script_skill_tool.rs src/compat/workflow_executor.rs src/compat/orchestration.rs tests/browser_script_skill_tool_test.rs tests/compat_runtime_test.rs
git commit -m "feat: add direct fault-details scene routing"

Task 5: Verify Tool Exposure, Browser-Surface Fallback, And Mixed Routing Together

Files:

• Modify if needed: src/compat/runtime.rs:142

• Test: tests/compat_runtime_test.rs

• Test: tests/runtime_profile_test.rs

• Test: tests/scene_registry_test.rs

• Step 1: Write the failing integration-shape tests

Add focused assertions that prove the mixed-mode design works together:

• staged browser-backed tool names are exposed
• fault-details-report uses direct routing
• 95598-repair-city-dispatch stays in the agent path but gets scene-specific browser-first instruction injection
• browser-surface-disabled turns do not gain scene browser contracts
• browser-surface-disabled turns do not trigger direct_browser scene execution
• missing scene metadata preserves unchanged runtime behavior for unrelated tasks
• unrelated Zhihu behavior still works the same way

Use existing test seams instead of broad integration scaffolding.

• Step 2: Run the focused mixed-routing tests to verify they fail

Run:

cargo test --test scene_registry_test -- --nocapture && cargo test --test compat_runtime_test scene_ -- --nocapture && cargo test --test runtime_profile_test scene_ -- --nocapture

Expected: FAIL until the mixed-routing assertions are implemented.

• Step 3: Make the minimum runtime adjustments needed

Only if required by the tests, adjust src/compat/runtime.rs so the loaded staged skills from the resolved external root are visible in the same way as existing browser-backed skills. Keep the shape of build_browser_script_skill_tools(...) and runtime tool assembly intact.

• Step 4: Run the focused mixed-routing tests to verify they pass

Run:

cargo test --test scene_registry_test -- --nocapture && cargo test --test compat_runtime_test scene_ -- --nocapture && cargo test --test runtime_profile_test scene_ -- --nocapture

Expected: PASS

• Step 5: Run the broader targeted verification sweep

Run:

cargo test --test browser_script_skill_tool_test -- --nocapture && cargo test --test scene_registry_test -- --nocapture && cargo test --test compat_config_test resolve_skills_dir_ -- --nocapture && cargo test --test runtime_profile_test -- --nocapture && cargo test --test compat_runtime_test fault_details -- --nocapture

Expected: PASS

• Step 6: Commit Task 5

git add src/compat/runtime.rs tests/scene_registry_test.rs tests/compat_runtime_test.rs tests/runtime_profile_test.rs
git commit -m "feat: wire staged scene mixed routing"

Task 6: Final Verification And Handoff

Files:

• Verify: src/runtime/scene_registry.rs

• Verify: src/compat/config_adapter.rs

• Verify: src/runtime/engine.rs

• Verify: src/compat/workflow_executor.rs

• Verify: src/compat/orchestration.rs

• Verify: tests/scene_registry_test.rs

• Verify: tests/compat_config_test.rs

• Verify: tests/runtime_profile_test.rs

• Verify: tests/compat_runtime_test.rs

• Step 1: Run the full focused verification set

Run:

cargo test --test scene_registry_test -- --nocapture && cargo test --test compat_config_test -- --nocapture && cargo test --test runtime_profile_test -- --nocapture && cargo test --test compat_runtime_test -- --nocapture

Expected: PASS

• Step 2: If any test fails, fix only the minimal root cause and re-run the same command

Do not broaden scope. Keep fixes limited to scene registry, path resolution, prompt injection, or direct routing.

• Step 3: Review the resulting diff against the spec

Manually verify:

• fault-details-report is direct-browser

• 95598-repair-city-dispatch is agent-browser

• both still use browser-backed execution semantics

• no broad Zhihu refactor slipped in

• the new scene-routing abstraction stays registry-driven

• Step 4: Commit the final verification pass

git add src/runtime/scene_registry.rs src/runtime/mod.rs src/compat/config_adapter.rs src/runtime/engine.rs src/compat/workflow_executor.rs src/compat/orchestration.rs src/compat/runtime.rs tests/scene_registry_test.rs tests/compat_config_test.rs tests/runtime_profile_test.rs tests/compat_runtime_test.rs
git commit -m "test: verify scene skill runtime routing"