claw/docs/superpowers/specs/2026-04-09-config-owned-direct-skill-dispatch-design.md

Config-Owned Direct Skill Dispatch Design

Goal: Preserve the current minimal submit flow where sgClaw accepts natural-language input, directly invokes one configured staged browser skill without calling an LLM, and keeps dispatch ownership in sgClaw configuration rather than external skill metadata.

Status: Approved design direction for the next slice. The current minimal direct-submit path already works; this document records the ownership boundary that future dispatch-policy work should follow.

---

Decision Summary

1. Keep direct-skill selection in sgClaw configuration.
2. Continue using skillsDir plus directSubmitSkill as the only control surface for the no-LLM direct path.
3. Do not add sgClaw-specific dispatch fields to files under D:/data/ideaSpace/rust/sgClaw/claw/claw/skills/skill_staging in this slice.
4. Keep the currently bound skill as fault-details-report.collect_fault_details.
5. When dispatch expands beyond one fixed skill, add the next policy layer on the sgClaw side first, not in scene.json or SKILL.toml.

---

Current Minimal Flow

The intended user experience stays unchanged:

• the user types natural language into the input box
• sgClaw receives BrowserMessage::SubmitTask
• sgClaw loads runtime config
• if directSubmitSkill is configured, sgClaw bypasses LLM routing and directly resolves the configured staged skill from skillsDir
• sgClaw executes the target browser_script tool through the browser runtime and returns the result
• if directSubmitSkill is absent, sgClaw falls back to the existing orchestration / compat behavior

This keeps the first slice small while preserving a clear seam for future expansion.

---

Ownership Boundary

sgClaw configuration owns dispatch choice

sgClaw configuration is responsible for deciding whether submit-task should bypass the LLM path and which direct skill should run.

For the current slice, that means:

• skillsDir tells sgClaw where to load staged skills from
• directSubmitSkill tells sgClaw which skill.tool should be used for the direct path

Example:

{
  "skillsDir": "D:/data/ideaSpace/rust/sgClaw/claw/claw/skills/skill_staging",
  "directSubmitSkill": "fault-details-report.collect_fault_details"
}

skill_staging owns skill identity and execution assets

Files under D:/data/ideaSpace/rust/sgClaw/claw/claw/skills/skill_staging remain responsible for describing the skill package, tool identity, and browser-script implementation.

For the current bound skill:

• 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/skills/fault-details-report/SKILL.toml
• D:/data/ideaSpace/rust/sgClaw/claw/claw/skills/skill_staging/skills/fault-details-report/scripts/collect_fault_details.js

These files already provide enough information for sgClaw to locate the package and run the tool. This slice does not add a new dispatch field inside them.

---

Why This Boundary Is Recommended

One source of truth for routing

If sgClaw configuration owns the direct-skill decision, the operator can switch the direct skill by changing config only. There is no need to edit code and no need to mutate external skill assets just to change routing.

Avoid freezing external manifest semantics too early

skill_staging is an external skill asset set. Adding sgClaw-specific dispatch metadata now would couple the staged-skill format to one integration strategy before the policy model is stable.

Preserve a clean migration path

The current minimal path is intentionally narrow: one fixed configured direct skill, no LLM dispatch, no per-skill policy registry yet. Keeping dispatch control in sgClaw makes it easier to add a broader policy layer later without rewriting the staged-skill package format first.

---

Explicit Non-Goals

This design does not do the following:

• redesign the submit-task protocol
• move dispatch control into scene.json or SKILL.toml
• require every staged skill to declare direct_browser or llm_agent right now
• expand the current direct path into generic natural-language intent classification
• change the browser-script execution model
• change the current fallback orchestration / compat execution semantics when directSubmitSkill is not configured

---

Current Skill Contract

The current direct path remains intentionally deterministic.

For fault-details-report.collect_fault_details, sgClaw derives only the minimum required arguments:

• expected_domain from the current page_url
• period from an explicit YYYY-MM token in the user's natural-language input

That means the UX still looks like natural-language submission, but the runtime does not ask an LLM to infer intent or invent missing parameters. If the period is missing, sgClaw should return a clear error instead of guessing.

---

Future Dispatch Policy Direction

When more than one staged skill needs routing control, the next layer should still begin on the sgClaw side.

Recommended direction:

• keep directSubmitSkill as the current bootstrap switch for the minimal fixed-skill path
• introduce a sgClaw-owned registry or config mapping that can later express skill.tool -> direct_browser | llm_agent
• keep external skill manifests unchanged until the policy surface proves stable in real use

Only after the routing model is stable should we consider whether external skill metadata needs a default dispatch hint.

---

Resulting Design Rule

For this project, the direct-skill decision remains config-owned:

• sgClaw config decides whether submit-task bypasses the LLM path
• staged skill metadata identifies what the skill is and how its browser tool runs
• future per-skill dispatch policy should be added in sgClaw first, not in skill_staging

This is the approved baseline for the next dispatch-policy slice.