docs(workflow): teach profile selection and project scripts

Author: Waishnav

skills/dynamic-workflows/SKILL.md

@@ -56,7 +56,7 @@ return { summary, findings }
 
 | API | Notes |
 |---|---|
-| `agent(prompt, opts?)` | Throws on failure. `opts`: `label`, `phase`, `schema`, `model`, `effort`, `provider`, `isolation: 'worktree'` |
+| `agent(prompt, opts?)` | Throws on failure. `opts`: `label`, `phase`, `schema`, `model`, `effort`, `profile` or `provider`, `isolation: 'worktree'` |
 | `parallel(thunks)` | Barrier; throw → `null` slot |
 | `pipeline(items, ...stages)` | Per-item chains; no cross-item barrier |
 | `phase(title)` / `log(msg)` | Progress; journaled |
@@ -85,7 +85,13 @@ const out = await agent('Return JSON findings', {
 
 ### Providers
 
-Default: first **enabled ∩ available** provider (`agentProviders.enabled` in config, else all live providers in product order). Override with `opts.provider` or `meta.defaultProvider`.
+Profiles exposed by `open_workspace` may be selected with `opts.profile`. The
+profile supplies instructions, provider, model, and effort defaults; per-call
+`model` and `effort` override those defaults. `profile` and `provider` are
+mutually exclusive.
+
+Without a profile, default provider resolution is `opts.provider` →
+`meta.defaultProvider` → first **enabled ∩ available** provider.
 
 ### Resume
 

src/workflow-contracts.test.ts

@@ -51,6 +51,10 @@ assert.throws(
   () => agentOptsSchema.parse({ provider: "made-up" }),
   /Invalid option/,
 );
+assert.throws(
+  () => agentOptsSchema.parse({ profile: "reviewer", provider: "codex" }),
+  /mutually exclusive/,
+);
 assert.throws(() => agentOptsSchema.parse({ schema: [] }), /expected record/i);
 assert.throws(() => jsonValueSchema.parse(new Date()), /invalid input/i);
 assert.throws(() => jsonValueSchema.parse(() => undefined), /invalid input/i);
@@ -113,6 +117,8 @@ if (false) {
   // @ts-expect-error providers are exhaustive
   await agent("x", { provider: "made-up" });
 
+  await agent("review", { profile: "reviewer", effort: "high" });
+
   const tuple = await parallel([
     async () => "text",
     async () => 42,

src/workflow-tools.ts

@@ -47,7 +47,7 @@ const WORKFLOW_UI_WAIT_MAX_MS = 30_000;
 const WORKFLOW_API_CHEATSHEET = `
 Workflow scripts (JS only):
   export const meta = { name, description, phases?, defaultProvider?, concurrency? }
-  agent(prompt, { label?, phase?, schema?, model?, effort?, provider?, isolation?: 'worktree' })
+  agent(prompt, { label?, phase?, schema?, model?, effort?, profile? | provider?, isolation?: 'worktree' })
   parallel(thunks) → Array<T|null>   // barrier; throw → null
   pipeline(items, ...stages)        // no cross-item barrier
   phase(title); log(msg); args