fix: align Open Design baseUrl contract

Author: juancarlosrodicio

opencode/agents/designer.md

@@ -61,15 +61,17 @@ Do not use Superpowers or any other skill. This agent is intentionally limited t
 Use Open Design through `OPEN_DESIGN_URL` and the provided tools only:
 
 1. Load `open-design`.
-2. Call `open_design_health` with no URL argument.
-3. Call `open_design_list_agents`.
-4. List skills and design systems if selection is unclear.
-5. Choose a fitting `skillId` and `designSystemId`.
-6. Use `open_design_create_project` for an editable workbench project.
-7. Use `open_design_run_design` only when the user explicitly asks to generate files.
-8. Return the project URL.
-
-Never pass or invent a manual `baseUrl`. Never try localhost or guessed ports yourself. The tool reads `OPEN_DESIGN_URL`.
+2. Resolve `baseUrl` from approved configuration or explicit user/lead context.
+3. If `baseUrl` is missing, stop and ask; do not guess or hardcode URLs.
+4. Call `open_design_health` with the resolved `baseUrl`.
+5. Call `open_design_list_agents` with the resolved `baseUrl`.
+6. List skills and design systems with the resolved `baseUrl` if selection is unclear.
+7. Choose a fitting `skillId` and `designSystemId`.
+8. Use `open_design_create_project` with the resolved `baseUrl` for an editable workbench project.
+9. Use `open_design_run_design` with the resolved `baseUrl` only when the user explicitly asks to generate files.
+10. Return the project URL.
+
+Never invent URLs or hardcode `baseUrl`. Never try localhost or guessed ports yourself.
 
 ## Handoff
 

opencode/commands/design.md

@@ -14,12 +14,14 @@ Mandatory flow:
 1. Search for and read `PRODUCT.md` and `DESIGN.md`.
 2. If either is missing, load `impeccable` and create or propose the missing document(s).
 3. Load `open-design`.
-4. Check `open_design_health` without URL arguments.
-5. Check `open_design_list_agents`.
-6. Choose the best Open Design `skillId`.
-7. Choose the best `designSystemId`.
-8. Use `open_design_run_design` only when generated files are explicitly requested.
-9. Otherwise use `open_design_create_project` for an editable workbench project.
-10. Return project URL, prompt, decisions, assumptions, risks, visual acceptance criteria, and developer handoff.
+4. Resolve `baseUrl` from approved safe configuration or explicit user/lead context.
+5. If `baseUrl` is missing, stop and ask; do not guess or hardcode URLs.
+6. Check `open_design_health` with the resolved `baseUrl`.
+7. Check `open_design_list_agents` with the resolved `baseUrl`.
+8. Choose the best Open Design `skillId`.
+9. Choose the best `designSystemId`.
+10. Use `open_design_run_design` with the resolved `baseUrl` only when generated files are explicitly requested.
+11. Otherwise use `open_design_create_project` with the resolved `baseUrl` for an editable workbench project.
+12. Return project URL, prompt, decisions, assumptions, risks, visual acceptance criteria, and developer handoff.
 
-Never pass `baseUrl` or invent URLs. The tool reads `OPEN_DESIGN_URL`.
+Never invent URLs or hardcode `baseUrl`; it must come from approved configuration/context.

opencode/docs/ai/harness/commands.md

@@ -55,6 +55,34 @@ Criteria:
 - `debugger` enters only for traces, results, or concrete previous evidence.
 - Output is scoped specs, atomic tasks, and validation.
 
+## Visible Auxiliary/Subtask Commands
+
+These commands are visible slash commands, but they do not add mandatory phases
+or promote sidecars by themselves. They inherit the barriers of the parent flow,
+or the `lead` barriers when used directly.
+
+### `/research`
+
+Contract: auxiliary/subtask `researcher`.
+
+Criteria:
+
+- Clarify technical/product uncertainty, APIs, libraries, risks, or architecture.
+- Do not implement and do not invoke `developer` by itself.
+- Return context, alternatives, risks, recommendation, and remaining unknowns.
+
+### `/implement`
+
+Contract: auxiliary/subtask `developer`.
+
+Criteria:
+
+- Execute approved changes or clear acceptance criteria.
+- Do not replace `/feature`, `/plan`, or `/scope` when research, design, spec,
+  or scope decisions are still missing.
+- Keep reasonable minimum validation and do not add mandatory review/evaluation
+  unless the parent flow requires it.
+
 ## `/design`
 
 Contract: `designer -> open design`.

opencode/skills/open-design/SKILL.md

@@ -25,7 +25,7 @@ Invalid examples:
 - `https://open-design.example.com/projects/my-project`
 - `https://open-design.example.com/projects/my-project/files/index.html`
 
-Tools read `OPEN_DESIGN_URL` from the environment. Do not pass a URL argument, compose URLs manually, or guess localhost ports.
+Resolve the tool `baseUrl` from approved configuration or explicit user/lead-provided context before calling Open Design tools. Do not invent, guess, or hardcode a URL. If no approved `baseUrl` is available, stop and ask for the missing configuration/context instead of trying a fallback.
 
 ## PRODUCT.md and DESIGN.md
 
@@ -44,6 +44,9 @@ Use only the Open Design tools:
 - `open_design_create_project`
 - `open_design_run_design`
 
+Pass the resolved `baseUrl` to every Open Design tool call, including health,
+list, create, and run calls.
+
 ## Modes
 
 ### Workbench

opencode/tools/open_design.ts

@@ -32,8 +32,8 @@ function randomId(length = 8): string {
     .slice(0, length)
 }
 
-function baseUrl() {
-  const raw = getEnv("OPEN_DESIGN_URL")
+function baseUrl(input?: string) {
+  const raw = input || getEnv("OPEN_DESIGN_URL")
   if (!raw) {
     throw new Error("OPEN_DESIGN_URL is not set. Example: export OPEN_DESIGN_URL='https://open-design.example.com'")
   }
@@ -205,39 +205,47 @@ async function streamOpenDesignChat(base: string, body: unknown) {
 
 export const health = tool({
   description: "Check whether the Open Design workbench is reachable.",
-  args: {},
-  async execute() {
-    const base = baseUrl()
+  args: {
+    baseUrl: tool.schema.string().optional(),
+  },
+  async execute(args) {
+    const base = baseUrl(args.baseUrl)
     const data = await requestJson(base, "/api/health")
     return JSON.stringify({ baseUrl: base, health: data }, null, 2)
   },
 })
 
 export const list_agents = tool({
   description: "List local agent CLIs detected by Open Design.",
-  args: {},
-  async execute() {
-    const base = baseUrl()
+  args: {
+    baseUrl: tool.schema.string().optional(),
+  },
+  async execute(args) {
+    const base = baseUrl(args.baseUrl)
     const data = await requestJson(base, "/api/agents")
     return JSON.stringify(data, null, 2)
   },
 })
 
 export const list_skills = tool({
   description: "List Open Design skills available in the workbench.",
-  args: {},
-  async execute() {
-    const base = baseUrl()
+  args: {
+    baseUrl: tool.schema.string().optional(),
+  },
+  async execute(args) {
+    const base = baseUrl(args.baseUrl)
     const data = await requestJson(base, "/api/skills")
     return JSON.stringify(data, null, 2)
   },
 })
 
 export const list_design_systems = tool({
   description: "List Open Design design systems available in the workbench.",
-  args: {},
-  async execute() {
-    const base = baseUrl()
+  args: {
+    baseUrl: tool.schema.string().optional(),
+  },
+  async execute(args) {
+    const base = baseUrl(args.baseUrl)
     const data = await requestJson(base, "/api/design-systems")
     return JSON.stringify(data, null, 2)
   },
@@ -246,6 +254,7 @@ export const list_design_systems = tool({
 export const create_project = tool({
   description: "Create an Open Design project and return its workbench URL without running generation.",
   args: {
+    baseUrl: tool.schema.string().optional(),
     name: tool.schema.string(),
     prompt: tool.schema.string(),
     skillId: tool.schema.string().optional(),
@@ -254,7 +263,7 @@ export const create_project = tool({
     fidelity: tool.schema.string().optional(),
   },
   async execute(args) {
-    const base = baseUrl()
+    const base = baseUrl(args.baseUrl)
     const projectId = `${safeSlug(args.name)}-${randomId(8)}`
     const body = {
       id: projectId,
@@ -276,6 +285,7 @@ export const create_project = tool({
 export const run_design = tool({
   description: "Create an Open Design project and run a design generation.",
   args: {
+    baseUrl: tool.schema.string().optional(),
     name: tool.schema.string(),
     prompt: tool.schema.string(),
     skillId: tool.schema.string(),
@@ -286,7 +296,7 @@ export const run_design = tool({
     fidelity: tool.schema.string().optional(),
   },
   async execute(args) {
-    const base = baseUrl()
+    const base = baseUrl(args.baseUrl)
     const projectId = `${safeSlug(args.name)}-${randomId(8)}`
 
     await requestJson(base, "/api/projects", {

scripts/check.sh

@@ -102,7 +102,7 @@ grep -q 'debugger' opencode/commands/evolve.md
 grep -q 'evolver' opencode/commands/evolve.md
 
 grep -q 'OPEN_DESIGN_URL' opencode/tools/open_design.ts
-! grep -q 'baseUrl:' opencode/tools/open_design.ts
+grep -q 'baseUrl: tool.schema.string().optional()' opencode/tools/open_design.ts
 ! grep -q 'randomUUID' opencode/tools/open_design.ts
 ! grep -q 'from "node:crypto"' opencode/tools/open_design.ts