taskchef 7.27.1 → 7.28.0

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "taskchef",
-  "version": "7.27.1",
+  "version": "7.28.0",
   "description": "Dispatch work from a data-only workspace to visible Codex project tasks.",
   "author": {
     "name": "Favo Yang",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "taskchef",
-  "version": "7.27.1",
+  "version": "7.28.0",
   "description": "A non-blocking interactive dispatcher for visible Codex tasks.",
   "license": "MIT",
   "author": "Favo Yang",
@@ -37,6 +37,7 @@
     "docs/images/reported-work-duration-mobile.jpg",
     "index.js",
     "mcp",
+    "scripts/roles",
     "scripts/benchmark-dispatch-prepare.js",
     "scripts/e2e-benchmark.js",
     "src",

package/scripts/roles/resolve_roles.py

@@ -0,0 +1,172 @@
+#!/usr/bin/env python3
+"""Read native Codex agent preferences without applying their instruction layers.
+
+Requires Python 3.11+. Standalone, standard library only. TaskChef packages an
+identical copy; neither installation imports the other at runtime.
+"""
+import argparse
+import json
+import os
+from pathlib import Path
+import sys
+import tomllib
+
+ROLES = ('planner', 'implementer', 'reviewer')
+EFFORTS = ('none', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max', 'ultra')
+
+
+def read_layer(directory):
+    found = {}
+    problems = []
+    try:
+        with os.scandir(directory) as entries:
+            files = sorted(Path(entry.path) for entry in entries if entry.name.endswith('.toml'))
+        for file in files:
+            try:
+                if file.stat().st_size > 65536:
+                    raise ValueError('profile exceeds 64 KiB')
+                with file.open('rb') as stream:
+                    data = tomllib.load(stream)
+                name = data.get('name')
+                if name not in ROLES:
+                    if file.stem in ROLES:
+                        raise ValueError('name must match the role filename')
+                    continue
+                errors = []
+                for field in ('description', 'developer_instructions'):
+                    if not isinstance(data.get(field), str) or not data[field].strip():
+                        errors.append(f'{field} must be a nonempty string')
+                model = data.get('model')
+                effort = data.get('model_reasoning_effort')
+                entry = {'source': str(file), 'model': model, 'effort': effort, 'problems': errors}
+                if name in found:
+                    entry['problems'].append('duplicate role name in the same directory')
+                found[name] = entry
+            except (OSError, ValueError) as error:
+                # Do not expose TOML lines, which can contain unrelated private data.
+                message = f'{file}: unreadable or malformed agent TOML ({type(error).__name__})'
+                problems.append(message)
+                if file.stem in ROLES:
+                    found[file.stem] = {'source': str(file), 'model': None, 'effort': None, 'problems': [message]}
+    except FileNotFoundError:
+        return found, problems
+    except OSError:
+        message = f'{directory}: cannot read agent directory'
+        problems.append(message)
+        found = {role: {'source': str(directory), 'model': None, 'effort': None, 'problems': [message]} for role in ROLES}
+    return found, problems
+
+
+def resolve(project=None, codex_home=None, explicit_model=None, explicit_effort=None):
+    home = Path(codex_home or os.environ.get('CODEX_HOME') or Path.home() / '.codex').expanduser().resolve()
+    personal, problems = read_layer(home / 'agents')
+    local, local_problems = read_layer(Path(project).resolve() / '.codex' / 'agents') if project else ({}, [])
+    problems += local_problems
+    catalog = None
+    catalog_source = str(home / 'models_cache.json')
+    try:
+        cache = json.loads(Path(catalog_source).read_text())
+        if not isinstance(cache, dict) or not isinstance(cache.get('models'), list):
+            raise ValueError('invalid catalog')
+        for model in cache['models']:
+            if not isinstance(model, dict) or not isinstance(model.get('slug'), str):
+                raise ValueError('invalid model entry')
+            levels = model.get('supported_reasoning_levels')
+            if not isinstance(levels, list) or any(not isinstance(level, dict) or not isinstance(level.get('effort'), str) for level in levels):
+                raise ValueError('invalid effort catalog')
+        catalog = {model['slug']: model for model in cache['models']}
+    except FileNotFoundError:
+        pass
+    except (OSError, ValueError, KeyError, TypeError):
+        problems.append('Local Codex model catalog is unreadable or malformed; validate availability with the current native tool.')
+    results = []
+    for role in ROLES:
+        entry = local.get(role, personal.get(role))
+        source = entry['source'] if entry else None
+        model = entry['model'] if entry else None
+        effort = entry['effort'] if entry else None
+        errors = list(entry['problems']) if entry else []
+        if explicit_model is not None:
+            model, effort = explicit_model, explicit_effort
+            effective_source = 'explicit user model choice'
+            errors = []
+        else:
+            effective_source = source
+            if explicit_effort is not None:
+                effort = explicit_effort
+        if model is not None and (not isinstance(model, str) or not model.strip() or len(model) > 256):
+            errors.append('model must be a nonempty string of at most 256 characters')
+        if effort is not None and effort not in EFFORTS:
+            errors.append('reasoning effort is unsupported')
+        status = 'invalid' if errors else 'configured' if (model is not None or effort is not None) else 'missing'
+        availability = 'not checked; native tool must validate before dispatch'
+        if model and not errors and catalog is not None:
+            if model not in catalog:
+                errors.append('model absent from local Codex catalog; confirm against the current native tool before dispatch')
+                status = 'unavailable'
+            else:
+                supported = [v.get('effort') for v in catalog[model].get('supported_reasoning_levels', []) if isinstance(v, dict)]
+                if effort and effort not in supported:
+                    errors.append('effort absent from local model catalog; confirm against the current native tool')
+                    status = 'unavailable'
+                availability = 'present in cached catalog; current native tool is authoritative'
+        overrides = {}
+        if status == 'configured':
+            if model is not None:
+                overrides['model'] = model
+            if effort is not None:
+                overrides['thinking'] = effort
+        results.append({'role': role, 'source': source, 'effectiveSource': effective_source,
+                        'model': model, 'effort': effort, 'status': status,
+                        'availability': availability, 'problems': errors,
+                        'taskOverrides': overrides,
+                        'subagentOverrides': {('reasoning_effort' if k == 'thinking' else k): v for k, v in overrides.items()},
+                        'fallback': 'inherit parent settings' if role == 'reviewer' else 'native new-task default (not guaranteed dispatcher inheritance)'})
+    return {'roles': results, 'problems': problems, 'catalogSource': catalog_source if catalog is not None else None,
+            'precedence': 'explicit user model (and its explicit effort) > project role > personal role > native defaults; explicit effort alone overrides role effort',
+            'scope': 'Model and effort only; agent instructions, tools, permissions, and other TOML keys are not applied by this adapter.'}
+
+
+def setup(role, model, effort, codex_home=None):
+    home = Path(codex_home or os.environ.get('CODEX_HOME') or Path.home() / '.codex').expanduser().resolve()
+    existing, problems = read_layer(home / 'agents')
+    if role in existing or problems:
+        return {'created': False, 'role': role, 'problems': problems or ['existing role preserved'], 'source': existing.get(role, {}).get('source')}
+    if not model.strip() or len(model) > 256 or effort not in EFFORTS:
+        raise ValueError('invalid model or effort')
+    directory = home / 'agents'
+    directory.mkdir(parents=True, exist_ok=True)
+    target = directory / f'{role}.toml'
+    data = {'name': role, 'description': f'{role.capitalize()} model preferences',
+            'developer_instructions': f'Perform the assigned {role} work within the user\'s requested scope.',
+            'model': model, 'model_reasoning_effort': effort}
+    try:
+        with target.open('x') as stream:
+            stream.write(''.join(f'{key} = {json.dumps(value)}\n' for key, value in data.items()))
+    except FileExistsError:
+        return {'created': False, 'role': role, 'source': str(target), 'problems': ['existing file preserved']}
+    return {'created': True, 'role': role, 'source': str(target), 'model': model, 'effort': effort}
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('--project')
+    parser.add_argument('--codex-home')
+    parser.add_argument('--role', choices=ROLES)
+    parser.add_argument('--model')
+    parser.add_argument('--effort')
+    parser.add_argument('--setup', action='store_true')
+    args = parser.parse_args()
+    if args.setup:
+        if not (args.role and args.model and args.effort):
+            parser.error('--setup requires --role, --model, and --effort')
+        result = setup(args.role, args.model, args.effort, args.codex_home)
+    else:
+        result = resolve(args.project, args.codex_home, args.model, args.effort)
+        if args.role:
+            result['roles'] = [r for r in result['roles'] if r['role'] == args.role]
+    print(json.dumps(result, indent=2))
+
+
+if __name__ == '__main__':
+    main()

package/skills/taskchef-bootstrap/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: taskchef-bootstrap
-description: "Initialize, diagnose, or refresh TaskChef dispatcher workspaces, the Codex project index, task history, and managed AGENTS.md instructions. Use when creating a TaskChef workspace, indexing or reindexing Codex projects, importing, listing, or removing indexed projects, running TaskChef doctor, or repairing dispatcher setup. Do not dispatch user work or report on executor threads."
+description: "Initialize or repair the TaskChef dispatcher workspace and manage its local Codex project index. Use for setup, doctor, import, or reindex requests; not dispatch or executor reporting."
 ---
 
 # TaskChef Bootstrap
@@ -50,118 +50,35 @@ all deterministic workspace operations.
    End without dispatching unless the user
    separately requested work.
 
-## Index Codex projects
+## Project index operations
 
-TaskChef's project index is the local list of Codex projects available for
-delegation. It stores canonical paths and routing metadata such as curated
-names, descriptions, Git status, and GitHub repositories. It does not index
-repository contents or create a second kind of project.
+For adding, importing, removing, listing, or reindexing projects, read
+[project index](references/project-index.md). Preserve exact canonical local
+Codex project identity and existing curated entries; opening a folder is not
+proof of registration. Completion requires verifying the intended index entry.
 
-Index only Codex projects local to the TaskChef workspace's execution host.
-Remote connection projects are outside the v1 contract. Never index the
-TaskChef dispatcher workspace or a directory containing it; the dispatcher is
-the inbox, while indexed Codex projects own delegated work.
+## Optional model roles
 
-### Existing Codex project
+Offer planner, implementer, and reviewer profiles during setup. Model and effort
+preferences belong in user configuration, never defaults hard-coded in skills.
+If the user provides values, configure them without asking again. Otherwise
+explain the optional profiles and retain native defaults until values are chosen.
 
-1. List native local Codex projects once. Resolve the requested existing folder
-   with `realpath` and require an exact canonical-path match in that list. A
-   similar name, a parent or child directory, and a remote connection project
-   are not matches.
-2. Index the exact path with the existing `project add <canonical-path> --name
-   <curated-name> --description <curated-description> --json` CLI workflow.
-   Despite the command's historical `add` name, this writes one TaskChef index
-   entry for an existing Codex project. The CLI detects Git status, the exact
-   Git root, and a canonical GitHub `origin` when no repository option is
-   supplied. Repeated `--github-repo <canonical-url>` arguments replace that
-   detection and form the complete advertised repository list, so repeat the
-   origin explicitly when it should remain routable. Use `--no-github` when the
-   user intentionally wants an empty list.
-3. Run `project list --json` and require one indexed entry with the exact
-   canonical path and intended routing metadata. Only then report that the
-   Codex project is ready for delegation through TaskChef.
+Run `python3 <plugin-root>/scripts/roles/resolve_roles.py` to preview personal
+roles. Python 3.11+ is required for this optional helper. Create each requested
+missing profile with:
 
-### New or not-yet-saved Codex folder
-
-1. Create the folder only when the user explicitly asked to create it. Preserve
-   unrelated existing contents. Do not initialize Git unless requested or
-   clearly required by the user's broader task. Resolve the resulting existing
-   folder with `realpath`.
-2. Register or open that exact canonical folder with the supported
-   `<validated-codex-cli> app <canonical-path>` mechanism. Reuse a validated CLI
-   path supplied by the current Codex Desktop environment when available. Use
-   the same resolver contract as `workspace init --register-codex` otherwise:
-   an explicit `--codex-cli` path takes precedence over `TASKCHEF_CODEX_CLI`;
-   each must resolve to an executable that passes `app --help`. Without an
-   override, inspect `codex` executables from `PATH`, prefer a validated
-   candidate whose path contains `Contents/Resources`, and otherwise validate
-   only the first executable `codex` in PATH order. Never assume an arbitrary
-   shell `codex`, invoke `codex add`, or hard-code an application bundle path.
-3. Re-list native local Codex projects and require an exact canonical-path
-   match. Opening is a request, not proof that Codex saved the project. If the
-   exact match is absent, report that the folder was opened or registration was
-   requested but Codex registration remains unverified; do not index it in
-   TaskChef or call it delegation-ready.
-4. After Codex verification, index the project as in the existing-project path.
-   Run `project list --json` and verify the exact TaskChef index entry. Report
-   delegation readiness only after both the native Codex match and TaskChef
-   indexing are verified.
-
-For a managed `*-workspace` Codex project, advertise every relevant child or
-subrepository with repeated `--github-repo <canonical-github-url>` arguments,
-including the workspace repository itself when it can own issue or pull-request
-links. These explicit values are the complete list; automatic origin detection
-does not supplement them. This lets TaskChef route each canonical GitHub URL to
-the correct workspace rather than guessing from the folder name.
-
-### Reindex after Codex changes
-
-When the user asks TaskChef to reindex or catch up after saving more projects in
-Codex, list native local Codex projects once and run `project list --json` once
-before mutation. Compare exact canonical paths, then index each requested
-eligible Codex project that is missing from TaskChef by following the
-appropriate path above, sharing the batch verification instead of relisting
-after each write. After all additions, run `project list --json` once more and
-verify every intended canonical path and its routing metadata before reporting
-the index as current.
-
-Do not call `project add` for a path already in the TaskChef index; it rejects
-duplicate paths and must not be presented as a metadata refresh. Preserve
-existing curated entries, and do not remove entries merely because they are
-absent from the current Codex list. Refreshing or removing an existing entry
-requires an explicit user request and the project-management workflows below.
-
-## Manage the project index
-
-1. Bulk import with `project import <file|-> --json`. Input is a JSON array of
-   objects containing `path` plus optional `name`, `description`, and
-   `githubRepos`, which is always a JSON array of GitHub repository URLs. Before
-   importing, list native local Codex projects once, canonicalize every input
-   path, and require an exact local-project match for every entry. Reject or
-   report every unmatched path instead of indexing it. Import merges by
-   canonical path, preserves an existing name or description when omitted, and
-   unions existing and imported repository lists without duplicates. Use
-   `--replace` only when the user explicitly requests replacement. Run
-   `project list --json` afterward and verify every imported entry.
-2. Inspect indexed projects with `project list --json`. Remove by name with
-   `project remove`. Existing task entries keep their project snapshots.
-
-Example managed-workspace import entry:
-
-```json
-{
-  "name": "skills-workspace",
-  "path": "/workspace/skills-workspace",
-  "githubRepos": [
-    "https://github.com/example/skill-one",
-    "https://github.com/example/skill-two"
-  ],
-  "description": "Manages the listed child skill repositories."
-}
+```sh
+python3 <plugin-root>/scripts/roles/resolve_roles.py --setup --role <role> --model <requested-model> --effort <requested-effort>
 ```
 
-TaskChef accepts configuration schema version 2 only. Its optional exact
-`dashboard` object contains boolean `autostart`; absence means enabled and
-`false` opts out of MCP-lifecycle dashboard startup without disabling manual
-`$taskchef-dashboard` recovery. `githubRepos` is always an array; unsupported
-configuration is rejected without being rewritten.
+This authorized role setup may create `$CODEX_HOME/agents/<role>.toml` (default
+`~/.codex/agents/`) outside the dispatcher workspace. Existing definitions,
+including custom filenames, are preserved. Report conflicts and diagnostics;
+never overwrite a custom role. Re-run the preview and check model/effort against
+the available native interface. Missing roles are optional: TaskChef omits
+new-task overrides; reviewers inherit parent settings. Native new-task defaults
+are not guaranteed dispatcher inheritance. Read the delegate's
+[role resolution](../taskchef-delegate/references/model-roles.md) for precedence
+and adapter limits. Open the dashboard's `/#settings` preview to show the
+configured sources, requested effective settings, fallback, and problems.

package/skills/taskchef-bootstrap/references/project-index.md

@@ -0,0 +1,119 @@
+# Project index operations
+
+Resolve the plugin root and use its CLI as described in SKILL.md.
+
+## Index Codex projects
+
+TaskChef's project index is the local list of Codex projects available for
+delegation. It stores canonical paths and routing metadata such as curated
+names, descriptions, Git status, and GitHub repositories. It does not index
+repository contents or create a second kind of project.
+
+Index only Codex projects local to the TaskChef workspace's execution host.
+Remote connection projects are outside the v1 contract. Never index the
+TaskChef dispatcher workspace or a directory containing it; the dispatcher is
+the inbox, while indexed Codex projects own delegated work.
+
+### Existing Codex project
+
+1. List native local Codex projects once. Resolve the requested existing folder
+   with `realpath` and require an exact canonical-path match in that list. A
+   similar name, a parent or child directory, and a remote connection project
+   are not matches.
+2. Index the exact path with the existing `project add <canonical-path> --name
+   <curated-name> --description <curated-description> --json` CLI workflow.
+   Despite the command's historical `add` name, this writes one TaskChef index
+   entry for an existing Codex project. The CLI detects Git status, the exact
+   Git root, and a canonical GitHub `origin` when no repository option is
+   supplied. Repeated `--github-repo <canonical-url>` arguments replace that
+   detection and form the complete advertised repository list, so repeat the
+   origin explicitly when it should remain routable. Use `--no-github` when the
+   user intentionally wants an empty list.
+3. Run `project list --json` and require one indexed entry with the exact
+   canonical path and intended routing metadata. Only then report that the
+   Codex project is ready for delegation through TaskChef.
+
+### New or not-yet-saved Codex folder
+
+1. Create the folder only when the user explicitly asked to create it. Preserve
+   unrelated existing contents. Do not initialize Git unless requested or
+   clearly required by the user's broader task. Resolve the resulting existing
+   folder with `realpath`.
+2. Register or open that exact canonical folder with the supported
+   `<validated-codex-cli> app <canonical-path>` mechanism. Reuse a validated CLI
+   path supplied by the current Codex Desktop environment when available. Use
+   the same resolver contract as `workspace init --register-codex` otherwise:
+   an explicit `--codex-cli` path takes precedence over `TASKCHEF_CODEX_CLI`;
+   each must resolve to an executable that passes `app --help`. Without an
+   override, inspect `codex` executables from `PATH`, prefer a validated
+   candidate whose path contains `Contents/Resources`, and otherwise validate
+   only the first executable `codex` in PATH order. Never assume an arbitrary
+   shell `codex`, invoke `codex add`, or hard-code an application bundle path.
+3. Re-list native local Codex projects and require an exact canonical-path
+   match. Opening is a request, not proof that Codex saved the project. If the
+   exact match is absent, report that the folder was opened or registration was
+   requested but Codex registration remains unverified; do not index it in
+   TaskChef or call it delegation-ready.
+4. After Codex verification, index the project as in the existing-project path.
+   Run `project list --json` and verify the exact TaskChef index entry. Report
+   delegation readiness only after both the native Codex match and TaskChef
+   indexing are verified.
+
+For a managed `*-workspace` Codex project, advertise every relevant child or
+subrepository with repeated `--github-repo <canonical-github-url>` arguments,
+including the workspace repository itself when it can own issue or pull-request
+links. These explicit values are the complete list; automatic origin detection
+does not supplement them. This lets TaskChef route each canonical GitHub URL to
+the correct workspace rather than guessing from the folder name.
+
+### Reindex after Codex changes
+
+When the user asks TaskChef to reindex or catch up after saving more projects in
+Codex, list native local Codex projects once and run `project list --json` once
+before mutation. Compare exact canonical paths, then index each requested
+eligible Codex project that is missing from TaskChef by following the
+appropriate path above, sharing the batch verification instead of relisting
+after each write. After all additions, run `project list --json` once more and
+verify every intended canonical path and its routing metadata before reporting
+the index as current.
+
+Do not call `project add` for a path already in the TaskChef index; it rejects
+duplicate paths and must not be presented as a metadata refresh. Preserve
+existing curated entries, and do not remove entries merely because they are
+absent from the current Codex list. Refreshing or removing an existing entry
+requires an explicit user request and the project-management workflows below.
+
+## Manage the project index
+
+1. Bulk import with `project import <file|-> --json`. Input is a JSON array of
+   objects containing `path` plus optional `name`, `description`, and
+   `githubRepos`, which is always a JSON array of GitHub repository URLs. Before
+   importing, list native local Codex projects once, canonicalize every input
+   path, and require an exact local-project match for every entry. Reject or
+   report every unmatched path instead of indexing it. Import merges by
+   canonical path, preserves an existing name or description when omitted, and
+   unions existing and imported repository lists without duplicates. Use
+   `--replace` only when the user explicitly requests replacement. Run
+   `project list --json` afterward and verify every imported entry.
+2. Inspect indexed projects with `project list --json`. Remove by name with
+   `project remove`. Existing task entries keep their project snapshots.
+
+Example managed-workspace import entry:
+
+```json
+{
+  "name": "skills-workspace",
+  "path": "/workspace/skills-workspace",
+  "githubRepos": [
+    "https://github.com/example/skill-one",
+    "https://github.com/example/skill-two"
+  ],
+  "description": "Manages the listed child skill repositories."
+}
+```
+
+TaskChef accepts configuration schema version 2 only. Its optional exact
+`dashboard` object contains boolean `autostart`; absence means enabled and
+`false` opts out of MCP-lifecycle dashboard startup without disabling manual
+`$taskchef-dashboard` recovery. `githubRepos` is always an array; unsupported
+configuration is rejected without being rewritten.

package/skills/taskchef-copilot/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: taskchef-copilot
-description: "Explain and coordinate TaskChef executor outcomes from cached task briefs. Use when the user asks what finished, what needs attention, why a delegated task failed or needs input, what should happen next, asks to answer, follow up, resume, or continue the same recorded assignment in its existing task, or explicitly invokes the historical $taskchef-report name. The dashboard remains the primary monitoring UI. Use live Codex metadata only for an explicit fresh/live request or a meaningful focused contradiction, and never poll."
+description: "Explain TaskChef outcomes from cached briefs or continue an explicitly selected assignment in its existing task. Handles historical $taskchef-report requests; dashboard monitoring is separate."
 ---
 
 # TaskChef Copilot

package/skills/taskchef-delegate/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: taskchef-delegate
-description: "Dispatch actionable requests through the per-user TaskChef workspace into independently openable Codex project tasks. Use automatically for actionable work received in the canonical TaskChef dispatcher workspace. From any other project, use only when the user explicitly asks to delegate or split separate work into Codex tasks; TaskChef-related subject matter alone is not delegation intent. Record before creation, require executor self-linking, and never wait for executor completion."
+description: "Dispatch work received in the canonical TaskChef workspace into Codex tasks. Elsewhere, use only for explicit delegation of separate work; an existing executor keeps its assignment."
 ---
 
 # TaskChef Delegate
@@ -49,6 +49,13 @@ stop and report that the TaskChef plugin must be reloaded or installed.
 3. Route against configured project `name`, `description`, and canonical
    `githubRepos`; use `path` only as checkout identity. Require exactly one
    match and an exact native-project path. Ask instead of guessing.
+   Select `planner` for a requested planning assignment and `implementer` for
+   coding work. Use the matched project's `projectModelRoles` from preparation;
+   resolve explicit user choices and follow [model roles](references/model-roles.md).
+   Small coding changes need no separate planning task. For a planning/coding
+   split, the saved plan is the handoff to a separately requested implementation
+   assignment; do not switch models during a turn or coordinate phases automatically.
+   Resolve configuration problems before recording the task.
 4. Build each executor instruction in this exact shape:
 
    - Begin with the actual assignment on the first line and keep its complete

package/skills/taskchef-delegate/references/model-roles.md

@@ -0,0 +1,49 @@
+# Dispatch model roles
+
+Preparation includes personal and per-project model previews. Use the exact
+matched project's preview. Role preferences use native Codex agent TOML under
+`$CODEX_HOME/agents/` (default `~/.codex/agents/`) and that project's
+`.codex/agents/`; they are optional. The resolver requires Python 3.11+.
+
+Select `planner` for a planning assignment or `implementer` for coding. Pass
+its `taskOverrides` as native `model` and `thinking` arguments only after checking
+those values against the current create-task tool's supported model/effort
+choices. A missing role means omit both arguments and use the native new-task
+default. This is not guaranteed to inherit the dispatcher's model.
+
+Explicit user model choices take precedence over the project role, personal
+role, and native defaults. An explicit model without explicit effort omits effort and uses the native
+interface's omission behavior; do not mix in a different role's effort or claim
+a specific effective effort without evidence. Explicit effort
+alone replaces the resolved role effort. Project roles replace personal roles
+as a unit. To resolve explicit choices, or recheck a preview after configuration
+changes, run:
+
+```sh
+python3 <plugin-root>/scripts/roles/resolve_roles.py --project <project-path> --role implementer --model <user-model> --effort <user-effort>
+```
+
+Omit flags the user did not specify. Resolve the plugin root from this skill's
+real path, two parents above the skill directory. Do not substitute dispatcher
+paths for the target project or infer model names from skill prose.
+
+Report malformed profiles, duplicate names, unavailable models/efforts, and
+resolver failures. Do not quietly fall back and claim preferences were honored.
+The local model catalog is advisory: explain if a current native tool disproves
+its stale warning. Otherwise resolve the problem or obtain a valid explicit
+choice before task creation. Native creation failures retain normal TaskChef
+failure reporting. A preparation without role fields supports historical
+installations: check role files before deciding that no preferences exist.
+
+Only model and effort are adapted. The native agent file's instructions, tools,
+permissions, and other settings are not applied by create-task arguments. A
+role name in a title is not a native role selector. If the native interface adds
+a role selector, use it only with verified effective settings.
+
+For a plan-to-implementation handoff, a planner assignment can save
+`plans/addition.md` describing a pure addition function and the acceptance
+example `2 + 3 = 5`. A later implementer assignment reads that exact plan,
+implements the function, runs the example, and uses fresh reviewer subagents.
+The dispatcher returns after each creation; it does not wait for or launch
+subsequent phases automatically. A small addition change can instead go
+straight to the implementer.