cowork-flow 0.0.14 → 0.0.16

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cowork-flow",
-  "version": "0.0.14",
+  "version": "0.0.16",
   "description": "CLI for installing and maintaining cowork-flow collaboration templates.",
   "type": "module",
   "bin": {

package/template/.agent/skills/agent-team-execution/SKILL.md

@@ -23,11 +23,20 @@ Use this skill after a task is active and an approved `.cowork-flow/plans/*.md`
 
 Do not invoke `superpowers:subagent-driven-development` from this skill. Agent-team has its own persisted state machine; use Codex subagent orchestration directly and keep `agent-team` as the source of truth for ready assignments, results, reviews, retries, and completion.
 
-### Codex Orchestration Prompt
-
-- Ask Codex explicitly to spawn subagents. Use this wording for each ready batch: `Spawn one <agent_type> agent per ready assignment, wait for all requested results, and summarize each result by assignment id.`
-- Codex handles spawning, routing follow-up instructions, waiting for results, and closing completed agent threads. Do not look for an `agent-team` spawn subcommand; the Python script only prepares state and prompts.
+### Codex Tool Dispatch
+
+- In Codex hosts that expose real multi-agent tools, dispatch workers with `spawn_agent`, wait for all requested results with `wait_agent`, and close completed child threads with `close_agent`.
+- For each ready assignment, read `agent-team/assignments/<assignment-id>.md` and use that file's body as the child `message`.
+- When `agent-team/adapters/codex.json` provides `suggestedTaskName`, pass that value as the child `task_name` so the Codex App can start from a readable label instead of a raw assignment id.
+- After each `spawn_agent` call returns, immediately capture the host-provided `nickname` and canonical `task_name`, then persist them with `./.cowork-flow/run agent-team record-spawn <task-dir> --assignment <id> --task-name <returned-task-name> [--nickname <returned-nickname>]`.
+- `prepare` also emits `agent-team/assignments/<assignment-id>.context.json`. If a worker needs cowork-flow recovery, route it through `./.cowork-flow/run --context-file <that-file> resume` instead of plain `resume`.
+- Set `agent_type` from the assignment and pass `fork_turns: none` so the worker starts as a fresh child thread instead of inheriting coordinator history.
+- The child `message` must be the assignment prompt body only. Do not prepend coordinator dispatch wording such as `Spawn one ... agent`, because that wording can leak into the child thread and make it think it is the coordinator.
+- Treat `recommended_agent` as the registry match and prompt source, not as the Codex spawn target unless it also names a real Codex custom agent.
+- Prefer the host `nickname` for human-facing display once it is available. Do not invent your own alias when the host already returned one.
+- After dispatching a ready batch, wait for all requested results, summarize each result by assignment id, then record outcomes through `agent-team`.
 - Use `/agent` in interactive CLI sessions when you need to inspect, steer, stop, or close active agent threads.
+- Only fall back to manual or another host-level dispatch path if the current Codex host does not expose real subagent tools.
 
 ### Subagent Evidence Gate
 
@@ -39,11 +48,9 @@ Do not invoke `superpowers:subagent-driven-development` from this skill. Agent-t
 ### Fresh Worker Per Assignment
 
 - Spawn one agent per ready assignment. Use the assignment's `agent_type` as the Codex spawn target; built-in Codex agent types include `default`, `worker`, and `explorer`, and project or personal custom agents may add more.
-- Do not request a full-history fork when you also specify `agent_type`. In Codex hosts that expose real subagent dispatch tools, full-history fork cannot be combined with `agent_type` and the spawn call will be rejected.
-- Treat `recommended_agent` as the agent-team registry match and prompt source, not as the Codex spawn target unless it also names a real Codex custom agent.
+- Keep `fork_turns: none`; do not request a full-history fork for these worker dispatches.
 - Spawn a fresh worker for each ready assignment. Do not reuse the main agent context as the worker context.
-- When the host offers fork controls, prefer a fresh child thread with explicit prompt context over inherited full history. Put the assignment Markdown, write boundary, and any needed task facts directly in the worker prompt.
-- Use `agent-team/assignments/<assignment-id>.md` as the worker prompt body.
+- Put the assignment Markdown, write boundary, and any needed task facts directly in the worker prompt body.
 - Add this scene-setting to every worker prompt: it is not alone in the codebase, it must respect the listed write boundary, it must not revert other agents' edits, and it must report changed files plus exact verification commands.
 - Dispatch multiple ready assignments in parallel only after confirming their write files do not overlap. If they overlap, dispatch them sequentially or repair the dependency graph.
 

package/template/.cowork-flow/.version

@@ -1 +1 @@
-0.0.14
+0.0.16

package/template/.cowork-flow/agent-team/agents.yaml

@@ -16,6 +16,7 @@ agents:
     risk_limits:
       max_parallel_write_conflicts: 0
     prompt: |
+      Use the assignment brief as the source of truth; do not broaden scope.
       Implement the smallest change that satisfies the approved plan and tests.
       Write or update focused regression tests first, keep edits scoped, and report exact verification commands.
 
@@ -31,6 +32,7 @@ agents:
     risk_limits:
       max_parallel_write_conflicts: 0
     prompt: |
+      Use the assignment brief as the source of truth; do not broaden scope.
       Design tests that fail for the broken behavior and pass for the intended behavior.
       Prefer clear behavior assertions over implementation details, and include the command that proves the result.
 
@@ -47,6 +49,7 @@ agents:
     risk_limits:
       max_parallel_write_conflicts: 0
     prompt: |
+      Use the assignment brief as the source of truth; do not broaden scope.
       Find the root cause before changing code. Reproduce the failure, compare with nearby working patterns,
       then make the smallest fix and verify the original symptom.
 
@@ -62,6 +65,7 @@ agents:
     risk_limits:
       max_parallel_write_conflicts: 0
     prompt: |
+      Use the assignment brief as the source of truth; review only the requested scope.
       Review the proposal, spec, plan, and task PRD for contradictions, missing acceptance criteria,
       unclear scope, and behavior that is not covered by verification.
 
@@ -78,6 +82,7 @@ agents:
     risk_limits:
       max_parallel_write_conflicts: 0
     prompt: |
+      Use the assignment brief as the source of truth; review only the requested scope.
       Review the diff for correctness, maintainability, focused scope, and meaningful tests.
       Check that verification evidence matches the behavior being claimed.
 
@@ -93,6 +98,7 @@ agents:
     risk_limits:
       max_parallel_write_conflicts: 0
     prompt: |
+      Use the assignment brief as the source of truth; do not broaden scope.
       Write concise project documentation that reflects actual commands, files, and workflow behavior.
       Avoid aspirational text that is not backed by the implementation.
 
@@ -109,5 +115,6 @@ agents:
     risk_limits:
       max_parallel_write_conflicts: 0
     prompt: |
+      Use the assignment brief as the source of truth; review only the requested scope.
       Review release-facing changes for versioning, packaging, documentation, and command safety.
       Confirm that generated artifacts and publish steps are intentional.

package/template/.cowork-flow/scripts/agent_team.py

@@ -11,6 +11,7 @@ import sys
 from pathlib import Path
 
 from common.agent_team import (
+    build_adapter_payload,
     build_dispatch_plan,
     build_initial_metrics,
     build_initial_status,
@@ -21,6 +22,11 @@ from common.agent_team import (
     write_json,
 )
 from common.config import get_agent_team_enabled
+from common.execution_context import (
+    build_internal_execution_context_parser,
+    execution_context_from_namespace,
+    worker_command_block_message,
+)
 from common.paths import DIR_WORKFLOW, get_repo_root
 
 
@@ -216,6 +222,7 @@ GATED_COMMANDS = {
     "prepare",
     "status",
     "next",
+    "record-spawn",
     "record-result",
     "record-review",
     "retry",
@@ -298,6 +305,16 @@ def _copy_payload(source: str | None, destination_dir: Path, assignment_id: str,
     shutil.copyfile(source_path, destination_dir / f"{assignment_id}-attempt-{attempt}.json")
 
 
+def _assignment_display_label(assignment_id: str, assignment: dict[str, object]) -> str:
+    nickname = assignment.get("spawn_nickname")
+    if isinstance(nickname, str) and nickname.strip():
+        return nickname.strip()
+    task_name = assignment.get("spawn_task_name")
+    if isinstance(task_name, str) and task_name.strip():
+        return task_name.strip()
+    return assignment_id
+
+
 def _record_assignment(
     task_dir: Path,
     assignment_id: str,
@@ -386,24 +403,40 @@ def cmd_prepare(args: argparse.Namespace) -> int:
 
     registry = load_agent_registry(_agent_team_config_dir(repo_root) / "agents.yaml")
     dispatch_plan = build_dispatch_plan(tasks, registry)
+    try:
+        task_dir_relative = task_dir.resolve().relative_to(repo_root.resolve()).as_posix()
+    except ValueError:
+        task_dir_relative = str(task_dir)
+    for assignment in dispatch_plan["assignments"]:
+        assignment_id = str(assignment["id"])
+        assignment["worker_context_file"] = (
+            f"{task_dir_relative}/agent-team/assignments/{assignment_id}.context.json"
+        )
+        assignment["worker_prompt_file"] = (
+            f"{task_dir_relative}/agent-team/assignments/{assignment_id}.md"
+        )
     (runtime_dir / "dispatch-plan.yaml").write_text(
         render_dispatch_plan(dispatch_plan),
         encoding="utf-8",
     )
     write_json(runtime_dir / "status.json", build_initial_status(dispatch_plan))
     write_json(runtime_dir / "metrics.json", build_initial_metrics(dispatch_plan))
-    write_json(
-        adapters_dir / f"{dispatch_plan['adapter']}.json",
-        {
-            "adapter": dispatch_plan["adapter"],
-            "mode": "coordinator-dispatched",
-            "assignmentCount": len(dispatch_plan["assignments"]),
-        },
-    )
+    write_json(adapters_dir / f"{dispatch_plan['adapter']}.json", build_adapter_payload(dispatch_plan))
 
     for assignment in dispatch_plan["assignments"]:
         prompt_path = assignments_dir / f"{assignment['id']}.md"
+        context_path = assignments_dir / f"{assignment['id']}.context.json"
         prompt_path.write_text(render_assignment_prompt(assignment), encoding="utf-8")
+        write_json(
+            context_path,
+            {
+                "version": 1,
+                "mode": "worker",
+                "taskDir": task_dir_relative,
+                "assignment": assignment["id"],
+                "promptFile": assignment["worker_prompt_file"],
+            },
+        )
 
     print(f"prepared agent-team runtime assignments={len(dispatch_plan['assignments'])}")
     return 0
@@ -424,6 +457,23 @@ def cmd_status(args: argparse.Namespace) -> int:
 
     for status_name in sorted(counts):
         print(f"{status_name}: {counts[status_name]}")
+    if getattr(args, "verbose", False):
+        for assignment_id in sorted(status_data["assignments"]):
+            assignment = status_data["assignments"][assignment_id]
+            display_label = _assignment_display_label(assignment_id, assignment)
+            parts = [
+                assignment_id,
+                f"status={assignment.get('status', 'unknown')}",
+                f"role={assignment.get('role', 'unknown')}",
+                f"label={display_label}",
+            ]
+            spawn_task_name = assignment.get("spawn_task_name")
+            if isinstance(spawn_task_name, str) and spawn_task_name.strip():
+                parts.append(f"task_name={spawn_task_name.strip()}")
+            spawn_nickname = assignment.get("spawn_nickname")
+            if isinstance(spawn_nickname, str) and spawn_nickname.strip():
+                parts.append(f"nickname={spawn_nickname.strip()}")
+            print("\t".join(parts))
     return 0
 
 
@@ -452,6 +502,31 @@ def cmd_next(args: argparse.Namespace) -> int:
     return 0
 
 
+def cmd_record_spawn(args: argparse.Namespace) -> int:
+    task_dir = _resolve_path(get_repo_root(), args.task_dir)
+    try:
+        status_data = _load_status(task_dir)
+    except FileNotFoundError as error:
+        print(f"Error: {error}", file=sys.stderr)
+        return 1
+
+    assignments = status_data["assignments"]
+    if args.assignment not in assignments:
+        print(f"Error: assignment not found: {args.assignment}", file=sys.stderr)
+        return 1
+
+    assignment = assignments[args.assignment]
+    assignment["spawn_task_name"] = args.task_name
+    assignment["spawn_nickname"] = args.nickname.strip() if args.nickname else None
+    _save_json(_runtime_dir(task_dir) / "status.json", status_data)
+
+    label = _assignment_display_label(args.assignment, assignment)
+    print(
+        f"recorded spawn {args.assignment} task_name={args.task_name} label={label}"
+    )
+    return 0
+
+
 def cmd_record_result(args: argparse.Namespace) -> int:
     task_dir = _resolve_path(get_repo_root(), args.task_dir)
     try:
@@ -522,7 +597,10 @@ def cmd_complete(args: argparse.Namespace) -> int:
 
 
 def build_parser() -> argparse.ArgumentParser:
-    parser = argparse.ArgumentParser(description="Manage Cowork Flow agent team runtime")
+    parser = argparse.ArgumentParser(
+        description="Manage Cowork Flow agent team runtime",
+        parents=[build_internal_execution_context_parser()],
+    )
     subparsers = parser.add_subparsers(dest="command", required=True)
 
     init_parser = subparsers.add_parser("init", help="Initialize agent team configuration")
@@ -535,12 +613,20 @@ def build_parser() -> argparse.ArgumentParser:
 
     status_parser = subparsers.add_parser("status", help="Show agent team status")
     status_parser.add_argument("task_dir", help="Task directory")
+    status_parser.add_argument("--verbose", action="store_true", help="Show per-assignment details")
     status_parser.set_defaults(func=cmd_status)
 
     next_parser = subparsers.add_parser("next", help="Show ready assignments")
     next_parser.add_argument("task_dir", help="Task directory")
     next_parser.set_defaults(func=cmd_next)
 
+    record_spawn_parser = subparsers.add_parser("record-spawn", help="Record spawned agent details")
+    record_spawn_parser.add_argument("task_dir", help="Task directory")
+    record_spawn_parser.add_argument("--assignment", required=True, help="Assignment id")
+    record_spawn_parser.add_argument("--task-name", required=True, help="Canonical task_name returned by spawn_agent")
+    record_spawn_parser.add_argument("--nickname", help="Host-provided nickname returned by spawn_agent")
+    record_spawn_parser.set_defaults(func=cmd_record_spawn)
+
     record_result_parser = subparsers.add_parser("record-result", help="Record assignment result")
     record_result_parser.add_argument("task_dir", help="Task directory")
     record_result_parser.add_argument("--assignment", required=True, help="Assignment id")
@@ -571,6 +657,17 @@ def build_parser() -> argparse.ArgumentParser:
 def main() -> int:
     parser = build_parser()
     args = parser.parse_args()
+    execution_context = execution_context_from_namespace(args)
+    if execution_context.is_worker:
+        print(
+            worker_command_block_message(
+                execution_context,
+                f"agent-team {args.command}",
+                "Workers must not inspect or mutate agent-team coordinator state.",
+            ),
+            file=sys.stderr,
+        )
+        return 2
     if args.command in GATED_COMMANDS and not get_agent_team_enabled(get_repo_root()):
         print(
             "Error: agent-team is disabled. Set agent_team.enabled: true in .cowork-flow/config.yaml.",

package/template/.cowork-flow/scripts/common/agent_team.py

@@ -140,6 +140,18 @@ ROLE_TASK_TYPES = {
     "quality-reviewer": {"review", "verification"},
 }
 
+ROLE_PROMPT_TITLES = {
+    "implementer": "Implement",
+    "spec-reviewer": "Spec review",
+    "quality-reviewer": "Quality review",
+}
+
+ROLE_TASK_NAME_PREFIXES = {
+    "implementer": "implement",
+    "spec-reviewer": "spec_review",
+    "quality-reviewer": "quality_review",
+}
+
 
 def _role_config(registry: dict[str, object] | None, role: str) -> dict[str, object]:
     agents = registry.get("agents", {}) if registry else {}
@@ -334,6 +346,37 @@ def _select_agent(role: str, task: dict[str, object], registry: dict[str, object
     prompt = best_config.get("prompt") if isinstance(best_config, dict) else ""
     return best_name, agent_type, prompt if isinstance(prompt, str) else ""
 
+
+def _slugify_task_title(title: object) -> str:
+    if not isinstance(title, str):
+        return "assignment"
+    tokens = re.findall(r"[a-z0-9]+", title.lower())
+    return "_".join(tokens) if tokens else "assignment"
+
+
+def _assignment_prompt_title(assignment: dict[str, object]) -> str:
+    role = str(assignment.get("role", ""))
+    title = str(assignment.get("title", "")).strip() or str(assignment.get("id", "Assignment"))
+    prefix = ROLE_PROMPT_TITLES.get(role, "Assignment")
+    return f"{prefix}: {title}"
+
+
+def _assignment_task_name_seed(assignment: dict[str, object]) -> str:
+    role = str(assignment.get("role", ""))
+    prefix = ROLE_TASK_NAME_PREFIXES.get(role, _slugify_task_title(role))
+    title_slug = _slugify_task_title(assignment.get("title", ""))
+    return f"{prefix}_{title_slug}" if title_slug else prefix
+
+
+def _apply_assignment_naming(assignments: list[dict[str, object]]) -> None:
+    seen: dict[str, int] = {}
+    for assignment in assignments:
+        assignment["prompt_title"] = _assignment_prompt_title(assignment)
+        seed = _assignment_task_name_seed(assignment)
+        count = seen.get(seed, 0) + 1
+        seen[seed] = count
+        assignment["suggested_task_name"] = seed if count == 1 else f"{seed}_{count}"
+
 def build_dispatch_plan(
     tasks: list[dict[str, object]],
     registry: dict[str, object] | None = None,
@@ -372,6 +415,7 @@ def build_dispatch_plan(
                     "commands": task.get("commands", []),
                 }
             )
+    _apply_assignment_naming(assignments)
 
     return {
         "version": 1,
@@ -438,6 +482,8 @@ def build_initial_status(dispatch_plan: dict[str, object]) -> dict[str, object]:
             "task": assignment["task"],
             "recommended_agent": assignment["recommended_agent"],
             "agent_type": assignment["agent_type"],
+            "spawn_task_name": None,
+            "spawn_nickname": None,
             "agent_prompt": assignment.get("agent_prompt", ""),
         }
 
@@ -455,6 +501,42 @@ def build_initial_metrics(dispatch_plan: dict[str, object]) -> dict[str, object]
     }
 
 
+def build_adapter_payload(dispatch_plan: dict[str, object]) -> dict[str, object]:
+    payload: dict[str, object] = {
+        "adapter": dispatch_plan["adapter"],
+        "mode": "coordinator-dispatched",
+        "assignmentCount": len(dispatch_plan["assignments"]),
+    }
+    if dispatch_plan["adapter"] != "codex":
+        return payload
+
+    payload["spawnDefaults"] = {
+        "spawnAgent": True,
+        "forkTurns": "none",
+        "promptSource": "assignment-file",
+    }
+    payload["spawnResult"] = {
+        "captureFields": ["task_name", "nickname"],
+        "displayNamePreference": ["nickname", "task_name", "assignmentId"],
+        "recordSpawnCommandTemplate": (
+            "./.cowork-flow/run agent-team record-spawn {taskDir} "
+            "--assignment {assignmentId} --task-name {task_name} [--nickname {nickname}]"
+        ),
+    }
+    payload["assignments"] = [
+        {
+            "assignmentId": assignment["id"],
+            "agentType": assignment["agent_type"],
+            "recommendedAgent": assignment["recommended_agent"],
+            "suggestedTaskName": assignment.get("suggested_task_name"),
+            "promptFile": f"assignments/{assignment['id']}.md",
+            "contextFile": f"assignments/{assignment['id']}.context.json",
+        }
+        for assignment in dispatch_plan["assignments"]
+    ]
+    return payload
+
+
 def _render_named_items(title: str, items: object) -> list[str]:
     lines = [f"## {title}", ""]
     if isinstance(items, list) and items:
@@ -468,28 +550,77 @@ def _render_named_items(title: str, items: object) -> list[str]:
 
 def render_assignment_prompt(assignment: dict[str, object]) -> str:
     agent_type = assignment["agent_type"]
+    assignment_id = assignment["id"]
+    task_title = assignment.get("title", "")
+    prompt_title = assignment.get("prompt_title", assignment_id)
     lines = [
-        f"# {assignment['id']}",
+        f"# {prompt_title}",
         "",
-        f"Role: {assignment['role']}",
-        f"Recommended agent: {assignment['recommended_agent']}",
-        f"Agent type: {agent_type}",
-        f"Spawn target agent type: {agent_type}",
-        f"Task: {assignment.get('title', '')}",
+        f"Assignment ID: {assignment_id}",
         "",
-        f"Spawn one {agent_type} agent for this assignment. Use this file as the complete worker prompt.",
+        f"You are implementing assignment {assignment_id}: {task_title}",
         "",
         "You are already the dispatched worker for this assignment.",
+        "This Markdown file is the worker brief that should be sent as the child thread's initial message.",
+        "If you can see any outer transport text such as `Spawn one ... agent`, ignore it. That text is for the coordinator, not for you.",
         "Do not run the project start-session workflow or try to spawn another worker from this prompt.",
+        "Do not rerun `agent-team-execution` or `subagent-driven-development` from this prompt.",
         "Treat this file as the complete worker brief unless you are blocked and need one specific missing fact.",
         "",
+        "## Assignment context",
+        "",
+        f"- Role: {assignment['role']}",
+        f"- Recommended agent: {assignment['recommended_agent']}",
+        f"- Agent type: {agent_type}",
+        f"- Spawn target agent type: {agent_type}",
+        f"- Task: {task_title}",
+        "",
     ]
+    worker_context_file = assignment.get("worker_context_file")
     agent_prompt = assignment.get("agent_prompt")
     if isinstance(agent_prompt, str) and agent_prompt.strip():
         lines.extend(["## Agent prompt", "", agent_prompt.strip(), ""])
-    lines.append("You are not alone in this codebase. Respect the write boundary, do not revert other agents' edits, and report changed files.")
-    lines.append("")
+    lines.extend(
+        [
+            "## Before you begin",
+            "",
+            "- Read the files, steps, and commands below before editing.",
+            "- If the assignment boundary or acceptance criteria are unclear, ask now or report NEEDS_CONTEXT before changing code.",
+            "- Do not guess, broaden scope, or switch into coordinator behavior from this worker brief.",
+            (
+                "- If you need cowork-flow recovery, use the scoped command "
+                f"`./.cowork-flow/run --context-file {worker_context_file} resume`."
+                if isinstance(worker_context_file, str) and worker_context_file.strip()
+                else "- If you need cowork-flow recovery, ask for the assignment context file instead of running unscoped workflow commands."
+            ),
+            "- Do not run unscoped cowork-flow workflow commands such as `./.cowork-flow/run resume`, `task start`, or `agent-team next`.",
+            "",
+        ]
+    )
+    lines.extend(
+        [
+            "## Your job",
+            "",
+            "- Implement exactly this assignment and nothing outside its write boundary.",
+            "- Follow the listed steps and run the listed verification commands when applicable.",
+            "- You are not alone in this codebase. Respect other agents' edits and never revert work you did not make.",
+            "- If the brief is missing a required fact, report NEEDS_CONTEXT with the specific missing fact instead of guessing.",
+            "",
+        ]
+    )
     lines.extend(_render_named_items("Files", assignment.get("files")))
     lines.extend(_render_named_items("Steps", assignment.get("steps")))
     lines.extend(_render_named_items("Commands", assignment.get("commands")))
+    lines.extend(
+        [
+            "## Report format",
+            "",
+            "- Status: DONE | DONE_WITH_CONCERNS | BLOCKED | NEEDS_CONTEXT",
+            "- What changed, or what was attempted if blocked",
+            "- Files changed",
+            "- Exact verification commands and results",
+            "- Concerns or follow-up needed",
+            "",
+        ]
+    )
     return "\n".join(lines)

package/template/.cowork-flow/scripts/common/execution_context.py

@@ -0,0 +1,253 @@
+"""Execution context helpers for coordinator and worker scoped cowork-flow commands."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from dataclasses import dataclass
+from pathlib import Path
+
+from .paths import DIR_WORKFLOW, get_repo_root
+
+
+MODE_COORDINATOR = "coordinator"
+MODE_WORKER = "worker"
+
+
+class ExecutionContextError(ValueError):
+    """Raised when execution context flags are invalid."""
+
+
+@dataclass(frozen=True)
+class ExecutionContext:
+    mode: str = MODE_COORDINATOR
+    assignment: str | None = None
+    task_dir: str | None = None
+    prompt_file: str | None = None
+    context_file: str | None = None
+
+    @property
+    def is_worker(self) -> bool:
+        return self.mode == MODE_WORKER
+
+    @property
+    def is_default(self) -> bool:
+        return (
+            self.mode == MODE_COORDINATOR
+            and self.assignment is None
+            and self.task_dir is None
+            and self.prompt_file is None
+            and self.context_file is None
+        )
+
+
+def _strip(value: object) -> str | None:
+    if not isinstance(value, str):
+        return None
+    stripped = value.strip()
+    return stripped or None
+
+
+def _load_context_file(path: str) -> dict[str, object]:
+    context_path = Path(path)
+    try:
+        return json.loads(context_path.read_text(encoding="utf-8"))
+    except FileNotFoundError as error:
+        raise ExecutionContextError(f"context file not found: {path}") from error
+    except json.JSONDecodeError as error:
+        raise ExecutionContextError(f"context file is not valid JSON: {path}") from error
+    except OSError as error:
+        raise ExecutionContextError(f"failed to read context file: {path}") from error
+
+
+def _build_parser(
+    *,
+    add_help: bool,
+    mode_flag: str,
+    assignment_flag: str,
+    task_dir_flag: str,
+    prompt_file_flag: str,
+    context_file_flag: str,
+) -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(add_help=add_help)
+    parser.add_argument(mode_flag, choices=[MODE_COORDINATOR, MODE_WORKER], help=argparse.SUPPRESS)
+    parser.add_argument(assignment_flag, help=argparse.SUPPRESS)
+    parser.add_argument(task_dir_flag, help=argparse.SUPPRESS)
+    parser.add_argument(prompt_file_flag, help=argparse.SUPPRESS)
+    parser.add_argument(context_file_flag, help=argparse.SUPPRESS)
+    return parser
+
+
+def build_public_execution_context_parser(add_help: bool = False) -> argparse.ArgumentParser:
+    return _build_parser(
+        add_help=add_help,
+        mode_flag="--mode",
+        assignment_flag="--assignment",
+        task_dir_flag="--task-dir",
+        prompt_file_flag="--prompt-file",
+        context_file_flag="--context-file",
+    )
+
+
+def build_internal_execution_context_parser(add_help: bool = False) -> argparse.ArgumentParser:
+    return _build_parser(
+        add_help=add_help,
+        mode_flag="--execution-mode",
+        assignment_flag="--execution-assignment",
+        task_dir_flag="--execution-task-dir",
+        prompt_file_flag="--execution-prompt-file",
+        context_file_flag="--execution-context-file",
+    )
+
+
+def _context_from_values(
+    *,
+    mode: str | None,
+    assignment: str | None,
+    task_dir: str | None,
+    prompt_file: str | None,
+    context_file: str | None,
+) -> ExecutionContext:
+    file_data: dict[str, object] = {}
+    if context_file:
+        file_data = _load_context_file(context_file)
+
+    resolved_mode = _strip(mode) or _strip(file_data.get("mode")) or MODE_COORDINATOR
+    if resolved_mode not in {MODE_COORDINATOR, MODE_WORKER}:
+        raise ExecutionContextError(f"unsupported execution mode: {resolved_mode}")
+
+    resolved_assignment = _strip(assignment) or _strip(file_data.get("assignment"))
+    resolved_task_dir = _strip(task_dir) or _strip(file_data.get("taskDir"))
+    resolved_prompt_file = _strip(prompt_file) or _strip(file_data.get("promptFile"))
+
+    if resolved_mode == MODE_WORKER:
+        if not resolved_task_dir or not resolved_assignment:
+            raise ExecutionContextError(
+                "worker mode requires task dir and assignment (pass --context-file or --task-dir with --assignment)"
+            )
+        if not resolved_prompt_file:
+            resolved_prompt_file = (
+                f"{resolved_task_dir}/agent-team/assignments/{resolved_assignment}.md"
+            )
+    elif resolved_assignment or resolved_task_dir or resolved_prompt_file:
+        raise ExecutionContextError("assignment-scoped execution fields require worker mode")
+
+    return ExecutionContext(
+        mode=resolved_mode,
+        assignment=resolved_assignment,
+        task_dir=resolved_task_dir,
+        prompt_file=resolved_prompt_file,
+        context_file=_strip(context_file),
+    )
+
+
+def parse_public_execution_context_args(argv: list[str]) -> tuple[ExecutionContext, list[str]]:
+    parser = build_public_execution_context_parser(add_help=False)
+    leading: list[str] = []
+    remaining = list(argv)
+    index = 0
+    while index < len(argv):
+        token = argv[index]
+        if token in {"--mode", "--assignment", "--task-dir", "--prompt-file", "--context-file"}:
+            if index + 1 >= len(argv):
+                raise ExecutionContextError(f"missing value for {token}")
+            leading.extend([token, argv[index + 1]])
+            index += 2
+            continue
+        break
+
+    remaining = argv[index:]
+    namespace, leftover = parser.parse_known_args(leading)
+    if leftover:
+        raise ExecutionContextError(f"unsupported execution context arguments: {' '.join(leftover)}")
+    context = _context_from_values(
+        mode=getattr(namespace, "mode", None),
+        assignment=getattr(namespace, "assignment", None),
+        task_dir=getattr(namespace, "task_dir", None),
+        prompt_file=getattr(namespace, "prompt_file", None),
+        context_file=getattr(namespace, "context_file", None),
+    )
+    return context, remaining
+
+
+def execution_context_from_namespace(namespace: argparse.Namespace) -> ExecutionContext:
+    return _context_from_values(
+        mode=getattr(namespace, "execution_mode", None),
+        assignment=getattr(namespace, "execution_assignment", None),
+        task_dir=getattr(namespace, "execution_task_dir", None),
+        prompt_file=getattr(namespace, "execution_prompt_file", None),
+        context_file=getattr(namespace, "execution_context_file", None),
+    )
+
+
+def context_to_internal_cli_args(context: ExecutionContext) -> list[str]:
+    if context.is_default:
+        return []
+    if context.context_file:
+        return ["--execution-context-file", context.context_file]
+
+    args = ["--execution-mode", context.mode]
+    if context.task_dir:
+        args.extend(["--execution-task-dir", context.task_dir])
+    if context.assignment:
+        args.extend(["--execution-assignment", context.assignment])
+    if context.prompt_file:
+        args.extend(["--execution-prompt-file", context.prompt_file])
+    return args
+
+
+def worker_command_block_message(
+    context: ExecutionContext,
+    command: str,
+    reason: str,
+) -> str:
+    assignment = context.assignment or "unknown-assignment"
+    return f"Blocked: worker mode cannot run `{command}` for assignment {assignment}. {reason}"
+
+
+def build_worker_resume_text(
+    context: ExecutionContext,
+    repo_root: Path | None = None,
+) -> str:
+    if repo_root is None:
+        repo_root = get_repo_root()
+
+    lines = [
+        "========================================",
+        "WORKER CONTEXT",
+        "========================================",
+        "",
+        "## EXECUTION MODE",
+        f"Mode: {context.mode}",
+        f"Assignment: {context.assignment or 'unknown'}",
+        f"Task directory: {context.task_dir or 'unknown'}",
+    ]
+    if context.prompt_file:
+        lines.append(f"Prompt file: {context.prompt_file}")
+    if context.context_file:
+        lines.append(f"Context file: {context.context_file}")
+    lines.extend(
+        [
+            "",
+            "## READ FIRST",
+            f"- Read worker brief: {context.prompt_file or '(missing prompt file)'}",
+        ]
+    )
+    if context.task_dir and (repo_root / context.task_dir / "prd.md").is_file():
+        lines.append(f"- Read task PRD: {context.task_dir}/prd.md")
+    lines.extend(
+        [
+            "- Follow only the files, steps, and commands named in the worker brief.",
+            "",
+            "## RULES",
+            "- Do not switch into coordinator behavior from this worker-scoped context.",
+            "- Do not run unscoped cowork-flow workflow commands from this worker thread.",
+            "- If you are blocked, report NEEDS_CONTEXT instead of activating tasks or coordinating other workers.",
+            "",
+            f"Use scoped cowork-flow commands like: ./{DIR_WORKFLOW}/run --context-file "
+            f"{context.context_file or '<assignment-context.json>'} resume",
+            "",
+            "========================================",
+        ]
+    )
+    return "\n".join(lines)

package/template/.cowork-flow/scripts/resume.py

@@ -3,10 +3,34 @@
 
 from __future__ import annotations
 
+import argparse
+
+from common.execution_context import (
+    build_internal_execution_context_parser,
+    build_worker_resume_text,
+    execution_context_from_namespace,
+)
 from common.git_context import get_context_text
 
 
-def main() -> int:
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        description="Resume cowork-flow session context",
+        parents=[build_internal_execution_context_parser()],
+    )
+    args = parser.parse_args(argv)
+    context = execution_context_from_namespace(args)
+
+    if context.is_worker:
+        print("========================================")
+        print("COWORK-FLOW WORKER RESUME")
+        print("========================================")
+        print("Use this only when a dispatched worker needs assignment-scoped recovery.")
+        print("Do not switch back into the coordinator workflow from this entrypoint.")
+        print("")
+        print(build_worker_resume_text(context))
+        return 0
+
     print("========================================")
     print("COWORK-FLOW RESUME")
     print("========================================")

package/template/.cowork-flow/scripts/run.py

@@ -8,6 +8,12 @@ import subprocess
 import sys
 from pathlib import Path
 
+from common.execution_context import (
+    ExecutionContextError,
+    context_to_internal_cli_args,
+    parse_public_execution_context_args,
+)
+
 COMMAND_SCRIPTS = {
     "resume": "resume.py",
     "task": "task.py",
@@ -24,11 +30,15 @@ COMMAND_SCRIPTS = {
     "agent_team": "agent_team.py",
 }
 
+CONTEXT_AWARE_COMMANDS = {"resume", "task", "agent-team"}
+
 
 def print_usage() -> None:
     print(
         """Usage:
   ./.cowork-flow/run <command> [args...]
+  ./.cowork-flow/run --context-file <assignment-context.json> <command> [args...]
+  ./.cowork-flow/run --mode worker --task-dir <task-dir> --assignment <id> <command> [args...]
   ./.cowork-flow/run python [python-args...]
 
 Common commands:
@@ -62,7 +72,16 @@ def run_script(script_name: str, args: list[str]) -> int:
 
 
 def main(argv: list[str] | None = None) -> int:
-    args = list(sys.argv[1:] if argv is None else argv)
+    raw_args = list(sys.argv[1:] if argv is None else argv)
+    if not raw_args:
+        print_usage()
+        return 2
+
+    try:
+        context, args = parse_public_execution_context_args(raw_args)
+    except ExecutionContextError as error:
+        print(f"Error: {error}", file=sys.stderr)
+        return 2
     if not args:
         print_usage()
         return 2
@@ -73,6 +92,12 @@ def main(argv: list[str] | None = None) -> int:
         print_usage()
         return 0
     if command == "python":
+        if not context.is_default:
+            print(
+                "Error: execution context flags are not supported with the `python` passthrough command.",
+                file=sys.stderr,
+            )
+            return 2
         return run_python(rest)
 
     script_name = COMMAND_SCRIPTS.get(command)
@@ -85,7 +110,14 @@ def main(argv: list[str] | None = None) -> int:
             print_usage()
             return 2
 
-    return run_script(script_name, rest)
+    if not context.is_default and command not in CONTEXT_AWARE_COMMANDS:
+        print(
+            f"Error: execution context flags are only supported for: {', '.join(sorted(CONTEXT_AWARE_COMMANDS))}",
+            file=sys.stderr,
+        )
+        return 2
+
+    return run_script(script_name, [*context_to_internal_cli_args(context), *rest])
 
 
 if __name__ == "__main__":

package/template/.cowork-flow/scripts/task.py

@@ -65,6 +65,11 @@ from common.task_utils import (
     archive_task_complete,
 )
 from common.config import get_hooks
+from common.execution_context import (
+    build_internal_execution_context_parser,
+    execution_context_from_namespace,
+    worker_command_block_message,
+)
 
 CONTEXT_JSONL_FILES = ["implement.jsonl", "check.jsonl", "debug.jsonl"]
 DONE_STATUSES = ("completed", "done")
@@ -1357,6 +1362,7 @@ def main() -> int:
     parser = argparse.ArgumentParser(
         description="Task Management Script for cowork-flow workflow",
         formatter_class=argparse.RawDescriptionHelpFormatter,
+        parents=[build_internal_execution_context_parser()],
     )
     subparsers = parser.add_subparsers(dest="command", help="Commands")
 
@@ -1421,11 +1427,33 @@ def main() -> int:
     p_listarch.add_argument("month", nargs="?", help="Month (YYYY-MM)")
 
     args = parser.parse_args()
+    execution_context = execution_context_from_namespace(args)
 
     if not args.command:
         show_usage()
         return 1
 
+    worker_blocked_commands = {
+        "create",
+        "init-context",
+        "add-context",
+        "start",
+        "finish",
+        "archive",
+        "add-subtask",
+        "remove-subtask",
+    }
+    if execution_context.is_worker and args.command in worker_blocked_commands:
+        print(
+            worker_command_block_message(
+                execution_context,
+                f"task {args.command}",
+                "Workers must not activate, archive, or mutate cowork-flow task state.",
+            ),
+            file=sys.stderr,
+        )
+        return 2
+
     commands = {
         "create": cmd_create,
         "init-context": cmd_init_context,