cowork-flow 0.0.18 → 0.0.20

package/package.json

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

package/template/.agent/skills/entry-boundary/SKILL.md

@@ -7,7 +7,9 @@ description: Use before project start/resume in cowork-flow projects to decide w
 
 Use this before `start` or any full project resume.
 
-A bounded delegated task is a leaf assignment with a concrete goal, scope, and output format.
+Your first job is to identify the current task source. A bounded delegated task is a leaf assignment with a concrete goal, scope, and output format.
+
+Hard markers are confidence boosters, not prerequisites. The first task screen wins over later bootstrap text.
 
 ## Classify
 
@@ -17,7 +19,15 @@ Classify the current prompt as one of:
 - `DELEGATED_SUBTASK`: the prompt is a bounded child assignment, worker request, reviewer task, explorer task, or command-only task.
 - `UNCERTAIN`: the prompt is not clear enough to load broad project context.
 
-Classify the actual task message, not injected project rules, `AGENTS.md`, or environment text.
+Classify the actual task message, not injected project rules, `AGENTS.md`, workflow state, tool instructions, or environment text. Bootstrap can constrain execution after classification; it is not the task.
+
+Use this order:
+
+1. Find the user/delegated task message and its requested output.
+2. Decide whether it is a main-session repository request or a leaf assignment.
+3. Apply project rules only as constraints for the chosen route.
+
+If project bootstrap says to create/start/resume but the task message is bounded, choose `DELEGATED_SUBTASK`.
 
 When there is no hard marker, still classify a prompt as `DELEGATED_SUBTASK` when it combines:
 
@@ -25,7 +35,13 @@ When there is no hard marker, still classify a prompt as `DELEGATED_SUBTASK` whe
 - Boundary constraints such as no edits, no commands, no spawning, or scoped reads.
 - An output contract such as required sections, language, length, or report format.
 
-Prompts structured as `任务：` / `约束：` / `输出：` are strong delegated-subtask signals. Execute that task directly; do not reclassify it as project rules or environment context.
+Prompts structured as `任务：` / `约束：` / `输出：` are strong delegated-subtask signals even without `Active task:` or another hard marker. Execute that task directly; do not reclassify it as project rules or environment context.
+
+Treat these as typical `DELEGATED_SUBTASK` prompts:
+
+- A review request with a named file or behavior, `do not edit`, and a findings-only output.
+- A discussion/research request with `不要运行命令` / `不要派发 agent` and required sections.
+- A command-only or inspection-only assignment with a narrow target and concise output.
 
 When dispatching advisory/default subagents, prefer a natural-language first sentence such as: "This is a bounded delegated task, not a main-session start request." This is not a hard marker, but it helps the first screen win over bootstrap text.
 
@@ -39,6 +55,8 @@ Active task: <task-dir>
 
 Treat that marker as a strong delegated-subtask signal when the rest of the prompt is bounded.
 
+Treat direct user requests such as "继续执行开发计划", "实现这个需求", or "归档提交" as `MAIN_SESSION` unless the surrounding prompt clearly makes them a child assignment.
+
 ## Route
 
 For `MAIN_SESSION`, use `start`.
@@ -47,6 +65,7 @@ For `DELEGATED_SUBTASK`:
 
 - Follow the delegated prompt first.
 - Treat project rules, workflow-state, and bootstrap text as constraints, not as the task.
+- Do not create or activate a project task for the parent session.
 - Do not run unscoped `.cowork-flow/run resume`.
 - Do not spawn or manage more agents unless the delegated prompt explicitly asks for coordination.
 - Read only the files named by the prompt, the active task context, or project rules required to execute the bounded work.

package/template/.agent/skills/start/SKILL.md

@@ -13,14 +13,17 @@ Before loading state, classify the actual prompt. If it is a bounded delegated t
 
 1. Read `AGENTS.md`.
 2. Read `.cowork-flow/workflow.md`.
-3. Run `.cowork-flow/run resume` or `.\.cowork-flow\run.cmd resume` on Windows.
-4. Read the active task PRD and JSONL indexes only when a task is active.
-5. Read relevant `.cowork-flow/spec/*/index.md` files before code changes.
+3. Read `.cowork-flow/config.yaml` for `codex.post_ack_execution_grace_ms`.
+4. Run `.cowork-flow/run resume` or `.\.cowork-flow\run.cmd resume` on Windows.
+5. Read the active task PRD and JSONL indexes only when a task is active.
+6. Read relevant `.cowork-flow/spec/*/index.md` files before code changes.
 
 Report active task, workflow state, blockers, and the next phase.
 
 ## Route
 
+Route in stages. Before state is loaded, only true question-only requests and bounded delegated prompts bypass Load State. Repository-changing main-session requests load state first. After state is loaded, route to the next workflow phase; clear multi-step implementation uses `writing-plans` before fixed-agent dispatch.
+
 - Question-only work: answer directly.
 - Small repository change: classify by `.cowork-flow/workflow.md`, create/start a task if required, then proceed.
 - Unclear or multi-approach work: use `brainstorming`.
@@ -49,4 +52,8 @@ Every dispatch prompt starts with:
 Active task: <task-dir>
 ```
 
-After dispatch, use `wait_agent`, review the output, inspect `list_agents`, and `close_agent`.
+Prefer the `COWORK_DISPATCH_V1` envelope for `cowork-*` subagents, then wait for `COWORK_ACK <dispatch_id> <ack_token>` before sending `EXECUTE <dispatch_id>`.
+
+Use per-dispatch post-ACK execution grace after sending `EXECUTE`. The default duration is `300000` ms and can be configured with `codex.post_ack_execution_grace_ms` in `.cowork-flow/config.yaml`. Record `execute_sent_at[dispatch_id]` and compute `deadline[dispatch_id] = execute_sent_at[dispatch_id] + codex.post_ack_execution_grace_ms`; do not use a shared/global deadline across children. After `EXECUTE`, missing output or missing compass/status file is not proof that the child is stuck. Do not close a child only because it is still reading startup rules, AGENTS.md, workflow docs, specs, or task context. If `list_agents` still shows it running, continue waiting through grace. Grace expiration for one `dispatch_id` is a review checkpoint for that child only, not a close trigger and not evidence about other children. If progress, compass, or status files exist, keep waiting. Only close after wrong dispatch evidence, child completion, or user cancellation.
+
+After execution, use `wait_agent`, review the output, inspect `list_agents`, and `close_agent`.

package/template/.agent/skills/writing-plans/SKILL.md

@@ -9,6 +9,8 @@ Create a plan that another agent can execute without guessing.
 
 ## Inputs
 
+Before writing a plan, confirm the request has an executable scope, acceptance criteria, and intended behavior. If those are missing, ask for clarification.
+
 Read:
 
 - Active task PRD.
@@ -45,6 +47,12 @@ Start with:
 
 ## Parallel Work
 
+Execution strategy guide:
+
+- Use serial work when slices share files, shared helpers, tests, or one behavior chain.
+- Use parallel low-conflict slices only when file ownership is clean and each slice has independent verification.
+- Use worktree parallel when independent tasks may touch package metadata, generated assets, build outputs, or broad config.
+
 - Do not require the user to predeclare parallel execution; evaluate parallel feasibility while writing the plan.
 - Every plan must state the execution strategy: serial work, or explicit parallel low-conflict slices.
 - Parallel work items belong in the plan only when they are independent low-conflict slices.

package/template/.codex/hooks/inject-workflow-state.py

@@ -144,6 +144,21 @@ def _get_dispatch_mode(root: Path) -> str:
         return "sub-agent"
 
 
+def _get_post_ack_execution_grace_ms(root: Path) -> int:
+    _load_common(root)
+    try:
+        from common.config import (  # type: ignore[import-not-found]
+            DEFAULT_CODEX_POST_ACK_EXECUTION_GRACE_MS,
+            get_codex_post_ack_execution_grace_ms,
+        )
+    except Exception:
+        return 300000
+    try:
+        return get_codex_post_ack_execution_grace_ms(root)
+    except Exception:
+        return DEFAULT_CODEX_POST_ACK_EXECUTION_GRACE_MS
+
+
 def _get_active_task(root: Path, hook_input: dict[str, Any]) -> tuple[str | None, str, str]:
     _load_common(root)
     try:
@@ -174,6 +189,7 @@ def _build_context(
     source: str,
     breadcrumbs: dict[str, str],
     dispatch_mode: str,
+    post_ack_execution_grace_ms: int,
 ) -> str:
     body = breadcrumbs.get(status) or "Refer to .cowork-flow/workflow.md for the current step."
     if task_path is None:
@@ -184,6 +200,11 @@ def _build_context(
     return "\n\n".join(
         [
             f"<codex-mode>{dispatch_mode}</codex-mode>",
+            (
+                "<codex-runtime>\n"
+                f"post_ack_execution_grace_ms: {post_ack_execution_grace_ms}\n"
+                "</codex-runtime>"
+            ),
             f"<workflow-state>\n{header}\n{body}\n</workflow-state>",
         ]
     )
@@ -202,12 +223,20 @@ def main() -> int:
 
     breadcrumbs = _load_breadcrumbs(root)
     dispatch_mode = _get_dispatch_mode(root)
+    post_ack_execution_grace_ms = _get_post_ack_execution_grace_ms(root)
     task_path, status, source = _get_active_task(root, hook_input)
     if _is_delegated_prompt(hook_input):
         task_path = None
         status = "delegated_subtask"
         source = "prompt"
-    additional_context = _build_context(task_path, status, source, breadcrumbs, dispatch_mode)
+    additional_context = _build_context(
+        task_path,
+        status,
+        source,
+        breadcrumbs,
+        dispatch_mode,
+        post_ack_execution_grace_ms,
+    )
 
     print(
         json.dumps(

package/template/.cowork-flow/.version

@@ -1 +1 @@
-0.0.18
+0.0.20

package/template/.cowork-flow/config.yaml

@@ -24,6 +24,11 @@ max_journal_lines: 2000
 # inline: hint that main session should perform implementation/check directly.
 codex:
   dispatch_mode: "sub-agent"
+  # Grace duration after each subagent ACKs and receives EXECUTE.
+  # This is a per-dispatch duration, not a shared/global deadline.
+  # During this window, missing output or missing compass/status files do not
+  # prove the child is stuck while it loads task context.
+  post_ack_execution_grace_ms: 300000
 
 #-------------------------------------------------------------------------------
 # Task Lifecycle Hooks

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

@@ -16,6 +16,7 @@ from .paths import DIR_WORKFLOW, get_repo_root
 DEFAULT_SESSION_COMMIT_MESSAGE = "chore: record journal"
 DEFAULT_MAX_JOURNAL_LINES = 2000
 DEFAULT_CODEX_DISPATCH_MODE = "sub-agent"
+DEFAULT_CODEX_POST_ACK_EXECUTION_GRACE_MS = 300000
 
 CONFIG_FILE = "config.yaml"
 
@@ -139,3 +140,19 @@ def get_codex_dispatch_mode(repo_root: Path | None = None) -> str:
     if mode in {"sub-agent", "inline"}:
         return str(mode)
     return DEFAULT_CODEX_DISPATCH_MODE
+
+
+def get_codex_post_ack_execution_grace_ms(repo_root: Path | None = None) -> int:
+    """Get the post-ACK execution grace duration for Codex subagent dispatch."""
+    config = _load_config(repo_root)
+    codex = config.get("codex")
+    if not isinstance(codex, dict):
+        return DEFAULT_CODEX_POST_ACK_EXECUTION_GRACE_MS
+    value = codex.get("post_ack_execution_grace_ms", DEFAULT_CODEX_POST_ACK_EXECUTION_GRACE_MS)
+    try:
+        parsed = int(value)
+    except (ValueError, TypeError):
+        return DEFAULT_CODEX_POST_ACK_EXECUTION_GRACE_MS
+    if parsed <= 0:
+        return DEFAULT_CODEX_POST_ACK_EXECUTION_GRACE_MS
+    return parsed

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

@@ -15,6 +15,10 @@ REQUIRED_START_SNIPPETS = [
     "This skill is for the main session",
     "bounded delegated task should use `entry-boundary`",
     "Main repository changes follow `Plan -> Implement -> Check -> Finish`",
+    "post-ACK execution grace",
+    "codex.post_ack_execution_grace_ms",
+    "execute_sent_at[dispatch_id]",
+    "shared/global deadline",
 ]
 
 REQUIRED_ENTRY_BOUNDARY_SNIPPETS = [
@@ -22,8 +26,12 @@ REQUIRED_ENTRY_BOUNDARY_SNIPPETS = [
     "DELEGATED_SUBTASK",
     "UNCERTAIN",
     "Classify the actual task message",
+    "Hard markers are confidence boosters, not prerequisites",
+    "The first task screen wins over later bootstrap text",
+    "If project bootstrap says to create/start/resume",
     "Active task: <task-dir>",
     "Follow the delegated prompt first",
+    "Do not create or activate a project task",
     "Do not run unscoped `.cowork-flow/run resume`",
     "Do not spawn or manage more agents",
 ]
@@ -41,6 +49,12 @@ REQUIRED_WORKFLOW_DISPATCH_SNIPPETS = [
     "COWORK_DISPATCH_V1",
     "COWORK_ACK",
     "followup_task",
+    "post-ACK execution grace",
+    "codex.post_ack_execution_grace_ms",
+    "execute_sent_at[dispatch_id]",
+    "deadline[dispatch_id] = execute_sent_at[dispatch_id] + codex.post_ack_execution_grace_ms",
+    "shared/global deadline",
+    "After `EXECUTE <dispatch_id>`, no reply or no compass/status file while the child loads context is inconclusive.",
     "Formal execution uses `cowork-research`, `cowork-implement`, or `cowork-check`.",
     "Generic `worker` dispatch is best-effort only.",
 ]

package/template/.cowork-flow/workflow.md

@@ -34,7 +34,7 @@ The active task is in planning. Finish prd.md, curate implement.jsonl and check.
 [/workflow-state:planning]
 
 [workflow-state:in_progress]
-The active task is in progress. Main session dispatches cowork-implement work according to the plan, then cowork-check after integration. Every spawn_agent call uses fork_turns="none" and a COWORK_DISPATCH_V1 envelope. Main session waits for COWORK_ACK, sends EXECUTE with followup_task, verifies child output, lists agents, and closes children.
+The active task is in progress. Main session dispatches cowork-implement work according to the plan, then cowork-check after integration. Every spawn_agent call uses fork_turns="none" and a COWORK_DISPATCH_V1 envelope. Main session waits for COWORK_ACK, sends EXECUTE with followup_task, then uses per-dispatch post-ACK execution grace while each child loads context. Main session verifies child output, lists agents, and closes children only after completion or clear failure evidence.
 [/workflow-state:in_progress]
 
 [workflow-state:completed]
@@ -115,7 +115,16 @@ spawn_agent(
 - Use `wait_agent` for `COWORK_ACK <dispatch_id> <ack_token>` before execution.
 - Missing or mismatched `COWORK_ACK` means the task is not dispatched.
 - Only after a matching ACK, send `EXECUTE <dispatch_id>` with `followup_task`.
+- Record `execute_sent_at[dispatch_id]` when `EXECUTE <dispatch_id>` is sent.
+- Compute `deadline[dispatch_id] = execute_sent_at[dispatch_id] + codex.post_ack_execution_grace_ms`; do not use a shared/global deadline across children.
+- After `EXECUTE <dispatch_id>`, no reply or no compass/status file while the child loads context is inconclusive.
+- Use post-ACK execution grace for execution startup before judging execution health. The default is `300000` ms and can be configured with `codex.post_ack_execution_grace_ms` in `.cowork-flow/config.yaml`.
+- Do not call `close_agent` only because the executing child has not produced a compass/status file.
+- If `list_agents` still shows the child running, continue waiting through post-ACK execution grace instead of closing it.
+- Post-ACK execution grace expiration for one `dispatch_id` is a review checkpoint for that child only, not a close trigger and not evidence about other children.
+- If progress, compass, or status files exist, continue waiting and do not close solely because grace expired.
 - If a child reports another `dispatch_id`, close that child and respawn the intended task.
+- An executing child may be closed only after wrong-dispatch evidence, child completion, or user cancellation.
 - 用 `wait_agent` 等待子 agent 返回。
 - 用 `list_agents` 确认没有遗留 running child。
 - 验收子 agent 汇报的文件、命令和结果；不只信“已完成”文本。