@open-agent-toolkit/cli 0.0.68 → 0.0.69

package/assets/docs/contributing/skills.md

@@ -21,6 +21,7 @@ Skill behavior is defined by frontmatter plus the process contract in each `SKIL
 - Keep prerequisites and expected artifacts concrete.
 - Spell out blocked vs allowed activities for state-advancing skills.
 - Define user-facing progress indicators for longer workflows.
+- Define a pre-work capability and authorization gate for skills that delegate to subagents, workers, or reviewers.
 - Keep output obligations explicit so downstream skills and users know what changed.
 
 ## Contract components
@@ -28,6 +29,7 @@ Skill behavior is defined by frontmatter plus the process contract in each `SKIL
 - Mode assertion (purpose, blocked/allowed activities)
 - Preconditions and required artifacts
 - User-facing progress indicator expectations
+- Delegation capability detection and fallback behavior, when the skill dispatches helper agents
 - Output obligations
 - Escalation/guardrail behavior
 
@@ -59,6 +61,21 @@ Skill behavior is defined by frontmatter plus the process contract in each `SKIL
 - Use `create-agnostic-skill` when you want a reusable workflow skill that is not OAT-specific.
 - Use existing lifecycle skills as examples for progress banners, prerequisites, and artifact updates.
 
+## Delegation-Capable Skills
+
+Skills that dispatch subagents, workers, reviewers, or fresh-context helper sessions need a capability model before work starts. Do not assume delegation is available, and do not silently downgrade just because the runtime needs user authorization.
+
+At minimum, the skill contract should:
+
+- Probe whether the host can dispatch the required helper role(s).
+- Distinguish `available`, `authorization required`, and `not resolved`.
+- Ask once at skill start when authorization is required, with the approval scope stated clearly.
+- Lock the selected tier for the run unless the user explicitly changes execution mode.
+- Stop before side effects if delegation is required for correctness and authorization remains unresolved.
+- Document the fallback path and any quality or independence tradeoff.
+
+Use `create-agnostic-skill` or `create-oat-skill` as the starting point; both include the current delegation guidance and optional capability-detection template.
+
 ## Reading project state
 
 Skills that need fields from the active project's `state.md` (e.g. `phase`, `phaseStatus`, `workflowMode`, `docsUpdated`, `lastCommit`) MUST query the CLI instead of hand-parsing YAML with `grep`/`awk`.

package/assets/public-package-versions.json

@@ -1,6 +1,6 @@
 {
-  "cli": "0.0.68",
-  "docs-config": "0.0.68",
-  "docs-theme": "0.0.68",
-  "docs-transforms": "0.0.68"
+  "cli": "0.0.69",
+  "docs-config": "0.0.69",
+  "docs-theme": "0.0.69",
+  "docs-transforms": "0.0.69"
 }

package/assets/skills/create-agnostic-skill/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: create-agnostic-skill
-version: 1.2.1
+version: 1.3.0
 description: Use when adding a reusable workflow skill for AI coding agents. Scaffolds a new .agents/skills skill using the Agent Skills open standard.
 argument-hint: '[skill-name]'
 disable-model-invocation: true
@@ -60,6 +60,7 @@ If not provided in arguments, ask for:
 - **Model invocation**: Should the agent be able to invoke this automatically? (default: no)
 - **User invocable**: (Claude Code only) Should this appear in the `/` menu? (default: yes)
 - **Tool restrictions**: (Claude Code only) Which tools should the skill be allowed to use?
+- **Delegation**: Will the skill dispatch subagents or require a fresh-context worker/reviewer? If yes, define the capability probe, authorization gate, fallback tier, and approval scope.
 - **Supporting files**: Does the skill need templates, scripts, or reference files?
 
 ### Step 2: Apply Progressive Disclosure
@@ -295,9 +296,62 @@ Do **not** hard-code a specific Codex question tool name in skill prose unless t
 
 **When NOT to:**
 
-- Autonomous/subagent skills — use argument defaults or flags to drive decisions instead of prompting mid-execution
+- Long-running autonomous skills after work has started — resolve required decisions in a pre-work gate, then lock the choice for the run
 - Questions with open-ended answers — just ask conversationally in the skill prose
 
+### Delegation and Subagent Capability
+
+Skills that dispatch subagents, reviewers, workers, or fresh-context helper sessions must define a pre-work capability model. Do not let generated skills assume delegation is available, silently downgrade because authorization is required, or ask repeated approval questions mid-run.
+
+**When to include this section:**
+
+- The skill uses provider subagents, task workers, reviewers, or multi-agent execution
+- The skill's quality depends on fresh context or isolated review/implementation
+- The skill has a fallback mode when delegation is unavailable
+
+**Required guidance for delegation-capable skills:**
+
+1. **Probe before work starts.** Check whether the host can dispatch the needed worker/reviewer and whether dispatch requires user authorization.
+2. **Separate capability states.** Report `available`, `authorization required`, or `not resolved`; do not treat authorization-required as unavailable.
+3. **Ask once when authorization is required.** Use a concise question that names the delegation scope for the run. Approval should cover the stated worker roles and phases; a decline should select the documented fallback.
+4. **Lock the tier.** Once selected, keep the execution mode for the run unless the user explicitly changes it.
+5. **Fail closed before side effects.** If delegation is required for correctness and authorization is unresolved, stop before edits, writes, external side effects, or long-running work.
+6. **Document fallback behavior.** If inline or single-agent execution is acceptable, explain when it applies. If it changes quality, artifact freshness, or review independence, say so.
+
+**Portable provider wording:**
+
+- Claude Code: use Task/subagent dispatch when available; if the skill benefits from structured prompts, include `AskUserQuestion` in `allowed-tools`.
+- Cursor: use the provider's explicit agent invocation or natural-language agent handoff when supported.
+- Codex: use multi-agent spawning when available; if the host requires explicit user authorization before spawning, ask before falling back.
+- Fallback: use inline/single-agent execution only when the user declines delegation or the runtime truly cannot dispatch the required agent.
+
+**Good pre-work pattern:**
+
+```markdown
+### Step 0.5: Capability Detection
+
+Before edits, writes, external side effects, or long-running work, detect whether the required helper agents are available.
+
+- Available without authorization → Tier 1: delegated execution.
+- Authorization required → ask once: "Authorize `{worker/reviewer}` delegation for this run?"
+  - Approved → Tier 1.
+  - Declined → Tier 2: documented fallback.
+- Not resolved / unsupported → Tier 2: documented fallback.
+
+Report:
+
+`Selected: Tier {1|2} — {Delegated|Fallback}; Reason: {available|authorized|user declined delegation|dispatch unavailable|required role unresolved}`
+
+Lock the selected tier for the run.
+```
+
+**Anti-patterns:**
+
+- Selecting inline fallback just because the user did not pre-mention subagents, when the skill itself requires delegation and authorization can be requested
+- Asking for authorization after implementation or review has already started
+- Re-asking for each phase when the first approval explicitly covered the run
+- Hiding fallback quality differences from the user
+
 ### Progress Feedback
 
 For multi-step skills, print brief progress updates so the user knows what's happening:

package/assets/skills/create-agnostic-skill/references/skill-template.md

@@ -13,11 +13,12 @@ Adjust based on complexity—not all sections are required:
 5. **Arguments** - Parameters parsed from `$ARGUMENTS`
 6. **Prerequisites** - Required setup or context (if applicable)
 7. **Workflow/Steps** - Numbered steps using "Step 1, 2, 3..." naming
-8. **Quality Standards** - Checklist format for docs skills (if applicable)
-9. **Examples** - Both "Basic Usage" and "Conversational" styles
-10. **Reference** - Links to relevant documentation
-11. **Troubleshooting** - Common issues and solutions
-12. **Success Criteria** - Checklist of completion conditions
+8. **Capability Detection** - Required before work starts if the skill dispatches subagents/workers/reviewers
+9. **Quality Standards** - Checklist format for docs skills (if applicable)
+10. **Examples** - Both "Basic Usage" and "Conversational" styles
+11. **Reference** - Links to relevant documentation
+12. **Troubleshooting** - Common issues and solutions
+13. **Success Criteria** - Checklist of completion conditions
 
 ## Annotated Template
 
@@ -87,6 +88,24 @@ Parse from `$ARGUMENTS`:
 
 ## Workflow
 
+<!-- Include this Step 0.5 only if the skill dispatches subagents, workers, reviewers, or fresh-context helpers. -->
+
+### Step 0.5: Capability Detection
+
+Before edits, writes, external side effects, or long-running work, detect whether required helper agents are available.
+
+- Available without authorization → Tier 1: delegated execution.
+- Authorization required → ask once: "Authorize `{worker/reviewer}` delegation for this run?"
+  - Approved → Tier 1.
+  - Declined → Tier 2: documented fallback.
+- Not resolved / unsupported → Tier 2: documented fallback.
+
+Report the selected tier and reason before starting work:
+
+`Selected: Tier {1|2} — {Delegated|Fallback}; Reason: {available|authorized|user declined delegation|dispatch unavailable|required role unresolved}`
+
+Lock the selected tier for the run unless the user explicitly changes it.
+
 ### Step 1: First Step Title
 
 Clear instructions in imperative form. Tell the agent what to do.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-agent-toolkit/cli",
-  "version": "0.0.68",
+  "version": "0.0.69",
   "private": false,
   "description": "Open Agent Toolkit CLI",
   "homepage": "https://github.com/voxmedia/open-agent-toolkit/tree/main/packages/cli",
@@ -33,7 +33,7 @@
     "ora": "^9.0.0",
     "yaml": "2.8.2",
     "zod": "^3.25.76",
-    "@open-agent-toolkit/control-plane": "0.0.68"
+    "@open-agent-toolkit/control-plane": "0.0.69"
   },
   "devDependencies": {
     "@types/node": "^22.10.0",