feat: model invokable workflow skills

.agents/agents/oat-phase-implementer.md

@@ -1,6 +1,6 @@
 ---
 name: oat-phase-implementer
-version: 1.0.0
+version: 1.0.2
 description: Implements a single plan phase end-to-end — reads artifacts once, executes tasks sequentially, commits per task, self-reviews, and returns a structured summary. Dispatched by oat-project-implement.
 tools: Read, Write, Edit, Bash, Grep, Glob
 color: cyan
@@ -33,6 +33,16 @@ You will be given a "Phase Scope" block including:
 - **artifact_paths**: Paths to `plan.md`, `design.md`, `spec.md`, `implementation.md`, `discovery.md` (whichever exist for the project's mode)
 - **commit_convention**: Commit message format from plan.md (e.g., `feat({scope}): {description}`)
 - **workflow_mode**: `spec-driven` | `quick` | `import` (default `spec-driven`)
+- **model_axis**: Optional model dispatch state selected by the orchestrator (`selected:<value>`, `inherited`, `not-applicable`, or `host-auto`)
+- **effort_axis**: Optional effort dispatch state selected by the orchestrator (`selected:<value>`, `provider-default`, `inherited`, `not-applicable`, or `host-auto`)
+- **dispatch_ceiling**: Optional resolved provider ceiling that capped/selected this dispatch
+- **ceiling_source**: Optional source for the resolved ceiling (`repo config`, `project state`, or `preflight prompt`)
+- **provider_default_effort**: Optional Codex provider default effort, used only to explain base/unpinned fallback dispatches
+- **dispatch_rationale**: Optional short rationale for the model/effort axis choices
+
+The `model_axis`, `effort_axis`, `dispatch_ceiling`, `ceiling_source`, and `provider_default_effort` fields describe dispatch state the orchestrator already chose; they are descriptive context for your report, not actions for you to take. Echo whatever values were provided in your summary. If a field is absent, report it as "not provided."
+
+For Codex, `provider-default` means the base/unpinned role follows Codex configured/provider default effort. It does not mean OAT inherited the parent session ceiling.
 
 If `mode: fix`, the block also includes:
 
@@ -77,6 +87,8 @@ For each task in the phase, in the order declared in plan.md:
 3. Run the task's verification commands. Record pass/fail.
 4. Commit using the plan's commit convention. Include only files the task declared.
 
+Track your implementation confidence as `high`, `medium`, or `low` throughout the phase. If you are blocked because the work needs more reasoning or provider capability than the current dispatch appears to provide, say that explicitly in the report, include the current dispatch control when known, and do not keep retrying at the same capability as if the issue were missing context.
+
 **Do not:**
 
 - Skip tasks or reorder them.
@@ -116,6 +128,12 @@ Report format:
 **Phase:** {phase-id}
 **Tasks executed:** {N} of {N}
 **Commits:** {sha1}..{shaN}
+**Confidence:** high | medium | low
+**Model axis:** {model_axis if provided, otherwise "not provided"}
+**Effort axis:** {effort_axis if provided, otherwise "not provided"}
+**Dispatch ceiling:** {dispatch_ceiling if provided, otherwise "not provided"}
+**Ceiling source:** {ceiling_source if provided, otherwise "not provided"}
+**Provider default effort:** {provider_default_effort if provided, otherwise "not provided"}
 
 ### Task Outcomes
 
@@ -179,6 +197,12 @@ If a fix introduces a regression or doesn't address its finding, either re-fix w
 **Phase:** {phase-id}
 **Findings addressed:** {N} critical, {N} important
 **Commits:** {sha1}..{shaN}
+**Confidence:** high | medium | low
+**Model axis:** {model_axis if provided, otherwise "not provided"}
+**Effort axis:** {effort_axis if provided, otherwise "not provided"}
+**Dispatch ceiling:** {dispatch_ceiling if provided, otherwise "not provided"}
+**Ceiling source:** {ceiling_source if provided, otherwise "not provided"}
+**Provider default effort:** {provider_default_effort if provided, otherwise "not provided"}
 
 ### Fix Outcomes
 

.agents/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:

.agents/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.

.agents/skills/create-oat-skill/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: create-oat-skill
-version: 1.2.0
+version: 1.3.0
 description: Use when adding a new oat-* workflow skill or lifecycle action. Scaffolds the skill with OAT conventions like mode assertions, progress banners, and project-root resolution.
 argument-hint: '[skill-name]'
 disable-model-invocation: true
@@ -51,6 +51,7 @@ If not provided, ask the user for:
 - Description using the create-agnostic-skill formula: `Use when [trigger condition]. [What it does for disambiguation].`
 - Whether this is `oat-*` (should be for this skill)
 - Whether it needs project context (`activeProject` in `.oat/config.local.json`) or is repo-level
+- Whether it dispatches OAT subagents/workers/reviewers, and if so which roles, what fallback is acceptable, and whether authorization covers the full run or only a narrower checkpoint
 
 ### Step 2: Draft the Skill Using the OAT Template
 
@@ -61,6 +62,7 @@ Use `.agents/skills/create-oat-skill/references/oat-skill-template.md` as the ba
 - `## Mode Assertion`
 - `## Progress Indicators (User-Facing)` (with separator banner)
 - `### Step 0: Resolve Active Project` (if project-scoped)
+- `### Step 0.5: Capability Detection and Tier Selection` (if the skill dispatches subagents/workers/reviewers)
 - `## Success Criteria`
 
 **Required frontmatter metadata:**
@@ -104,6 +106,19 @@ Use `.agents/skills/create-oat-skill/references/oat-skill-template.md` as the ba
   - Fallback: ask in plain conversational text
 - Do not hard-code a specific Codex question tool name in the skill text unless the host/runtime contract is guaranteed.
 
+**Subagent/worker availability (required when the skill delegates):**
+
+- Follow the delegation guidance from `.agents/skills/create-agnostic-skill/SKILL.md`.
+- Add a pre-work capability step before any edits, artifact writes, external side effects, test runs, or long-running work.
+- Distinguish `available`, `authorization required`, and `not resolved`; authorization-required is not the same as unavailable.
+- If authorization is required, ask once at skill start and state the approval scope:
+  - Which roles are authorized (for example, `oat-phase-implementer`, `oat-reviewer`, or generic workers)
+  - Whether approval applies to the whole run, one phase, one review, or one checkpoint
+  - What fallback is selected if the user declines
+- Lock the selected tier for the run unless the user explicitly changes execution mode.
+- Fail closed before side effects if delegation is required for correctness and authorization remains unresolved.
+- For Codex, mention multi-agent spawning generically. Do not pin a custom `agent_type` unless the role is guaranteed by the active host config or the skill instructs the agent how to fall back to built-in roles/self-contained prompts.
+
 ### Step 4: Create Files
 
 Create:
@@ -173,6 +188,51 @@ pnpm test
 
 Verify the skill appears in `packages/cli/assets/skills/` after build. If a test asserts the exact skill list for the category (e.g., non-interactive mode expectations), update that test to include the new skill.
 
+## Reading project state
+
+Skills that need to read 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`.
+
+For one field, use `--field`:
+
+```bash
+WORKFLOW_MODE=$(oat project status --field project.workflowMode 2>/dev/null || echo null)
+```
+
+If the skill is reading a resolved project path instead of the active project pointer, add `--project-path`:
+
+```bash
+WORKFLOW_MODE=$(oat project status --project-path "$PROJECT_PATH" --field project.workflowMode 2>/dev/null || echo null)
+```
+
+For multiple fields, use `--shell` so the CLI fetches project state once and prints shell-safe assignments:
+
+```bash
+eval "$(oat project status --shell \
+  PHASE=project.phase \
+  PHASE_STATUS=project.phaseStatus \
+  WORKFLOW_MODE=project.workflowMode 2>/dev/null)"
+```
+
+### Contract notes
+
+- **Null sentinel behavior:** YAML `null` in `state.md` surfaces as the literal string `null`, matching the prior `grep | awk` behavior. Missing fields also print or assign `null` after project status resolves successfully.
+- `--field <path>` reads arbitrary dot paths from the project status payload. Scalars print as raw values; objects and arrays print as compact JSON.
+- `--shell NAME=path ...` prints shell-safe single-quoted assignments. Variable names must match `[A-Za-z_][A-Za-z0-9_]*`.
+- `--project-path <path>` reads from a repo-relative or absolute project path instead of `.oat/config.local.json`'s active project pointer.
+- Skill snippets assume `oat` is available on `PATH`; do not repeat per-skill `command -v oat` fallback blocks. CI/cloud environments without a global install can provide this `npx`-backed shim once per checkout:
+
+  ```bash
+  mkdir -p .oat/bin
+  cat > .oat/bin/oat <<'EOF'
+  #!/usr/bin/env bash
+  exec npx @open-agent-toolkit/cli "$@"
+  EOF
+  chmod +x .oat/bin/oat
+  export PATH="$PWD/.oat/bin:$PATH"
+  ```
+
+- Do **not** use this pattern to write state — state writes stay in their existing skill sections.
+
 ## Examples
 
 ### Basic Usage

.agents/skills/create-oat-skill/references/oat-skill-template.md

@@ -78,6 +78,37 @@ If `PROJECT_PATH` is missing/invalid:
 - Persist with `oat config set activeProject "$PROJECT_PATH"`.
 - TODO(back-compat): validate `oat config` exists on older target branches before relying on this snippet.
 
+<!-- Include this step only if the skill dispatches subagents, workers, reviewers, or fresh-context helpers. -->
+
+### Step 0.5: Capability Detection and Tier Selection
+
+Before edits, artifact writes, external side effects, test runs, or long-running work, detect whether required helper agents are available.
+
+Detection logic:
+
+- If the host can dispatch the required role(s) without extra authorization → Tier 1.
+- If the host can dispatch the required role(s) but requires user authorization, ask once before continuing:
+
+  ```
+  This skill normally delegates {implementation/review/analysis} to {role list}. Authorize delegated execution for this run?
+  ```
+
+  - Approved → Tier 1.
+  - Declined → Tier 2.
+
+- If the host cannot dispatch the required role(s), or a required role is unresolved → Tier 2.
+
+Report:
+
+```
+[preflight] Checking subagent availability…
+  → {role list}: {available | authorization required | not resolved}
+  → Selected: Tier {1 | 2} — {Subagents | Inline}
+  → Reason: {available without auth | authorized | user declined delegation | dispatch unavailable | required role unresolved}
+```
+
+Lock the selected tier for the run unless the user explicitly changes execution mode. If delegation is required for correctness and authorization is unresolved, stop before side effects instead of silently falling back.
+
 ### Step 1: {First Step}
 
 {Instructions…}