cowork-flow 0.0.19 → 0.0.21

package/template/.cowork-flow/spec/entry-contract.md

@@ -0,0 +1,45 @@
+# Entry contract
+
+`COWORK_ENTRY_CONTRACT_V1` classifies main-session prompts before workflow
+recovery. It does not identify formal subagents. Formal subagent identity is
+resolved by runtime context binding before workflow state is injected.
+
+## Classification order
+
+1. Runtime context binding, handled by the hook/plugin before this classifier.
+2. Explicit user main-session request.
+3. Read-only question or inspection request.
+4. Command-only wrapper with explicit command semantics.
+5. Unknown or task-shaped input without runtime binding.
+
+## Entry kinds
+
+| Kind | Meaning | May mutate workflow state |
+| --- | --- | --- |
+| `MAIN_SESSION` | User is asking the coordinator to run cowork-flow. | Yes |
+| `READ_ONLY` | Question, inspection, or research without writes. | No |
+| `COMMAND_ONLY` | Host command wrapper with explicit command semantics. | No, unless command contract allows |
+| `UNKNOWN` | Insufficient confidence. | No |
+
+## Fail-closed rules
+
+- Entry classification happens before task start, task resume, archive, or subagent dispatch.
+- `UNKNOWN` must not start/resume/archive/spawn.
+- `UNKNOWN` is not subagent evidence; it must preserve active-task/no-task
+  visibility and ask for clarification before workflow mutation.
+- A prompt that looks like a child assignment but has no runtime context remains
+  `UNKNOWN` or `READ_ONLY`; it does not become a formal subagent.
+- A missing, closed, or invalid runtime context produces fail-closed subagent
+  workflow state and must not fall back to main-session start/resume.
+- Runtime context binding overrides project bootstrap text for formal subagents.
+
+## Normalized object
+
+```json
+{
+  "entryKind": "MAIN_SESSION",
+  "confidence": 0.55,
+  "source": "main_session_heuristic",
+  "canMutateWorkflowState": true
+}
+```

package/template/.cowork-flow/spec/registry.json

@@ -0,0 +1,54 @@
+{
+  "schemaVersion": 1,
+  "contracts": [
+    {
+      "id": "COWORK_ENTRY_CONTRACT_V1",
+      "path": ".cowork-flow/spec/entry-contract.md",
+      "digest": [
+        "Classify main-session requests before task start, resume, archive, or commit.",
+        "Runtime context, not prompt labels, identifies formal subagent sessions."
+      ],
+      "readWhen": [
+        "before task start/resume/archive",
+        "when prompt and bootstrap text conflict"
+      ]
+    },
+    {
+      "id": "RUNTIME_CONTEXT_DISPATCH_V2",
+      "path": ".cowork-flow/spec/subagent-dispatch.md",
+      "digest": [
+        "Formal subagent work is keyed by cowork_runtime_context_id.",
+        "Explicit shim bind records bound_context_key before formal output is accepted."
+      ],
+      "readWhen": [
+        "before formal subagent dispatch",
+        "when checking subagent health",
+        "when adding host runtime-context support"
+      ]
+    },
+    {
+      "id": "HOST_ADAPTER_CAPABILITIES_V1",
+      "path": ".cowork-flow/spec/capabilities.md",
+      "digest": [
+        "Formal subagent work requires runtime context dispatch and binding.",
+        "Missing required host capabilities fall back to inline_or_manual."
+      ],
+      "readWhen": [
+        "before choosing host primitives",
+        "when adding or changing host adapters"
+      ]
+    },
+    {
+      "id": "HOST_ADAPTER_SCHEMA_V1",
+      "path": ".cowork-flow/spec/adapter.schema.json",
+      "digest": [
+        "Adapters must define runtime context transport and cleanup behavior.",
+        "Adapters describe host primitives; workflow.md stays host-neutral."
+      ],
+      "readWhen": [
+        "before editing adapter.yaml",
+        "before adding a new host adapter"
+      ]
+    }
+  ]
+}

package/template/.cowork-flow/spec/subagent-dispatch.md

@@ -0,0 +1,77 @@
+# Runtime-context subagent dispatch
+
+Formal `cowork-*` dispatch is identified by runtime context, not by prompt
+classification or a prompt handshake.
+
+## Scope
+
+- Formal dispatch uses `cowork-research`, `cowork-implement`, or `cowork-check`.
+- The main session owns dispatch, wait, acceptance, and closeout.
+- Child agents are leaf executors and must not dispatch, wait for, list, or
+  cancel other agents.
+- Generic `worker`, `default`, or `explorer` dispatch is advisory only and
+  cannot satisfy formal Implement or Check completion.
+
+## Runtime Context
+
+Before spawning a formal child, the main session creates:
+
+- `.cowork-flow/.runtime/subagents/<runtime_context_id>.json`
+- `.cowork-flow/.runtime/sessions/subagent_<runtime_context_id>.json`
+
+The child receives the runtime id and host context key through the host adapter
+transport. The baseline prompt transport is:
+
+```text
+cowork_runtime_context_id: <runtime_context_id>
+cowork_host_context_key: <host_context_key>
+```
+
+Hosts may use env or metadata transport only after the adapter declares and
+verifies that support. If `subagent init` emits a suggested host context key,
+the parent may use that key unless the host adapter has a stronger stable child
+session key.
+
+## Binding Gate
+
+The child hook or plugin may resolve `cowork_runtime_context_id` early and bind
+the runtime context before injecting workflow state. Because not every host can
+prove model-before-execution binding, the child must run this first-step shim
+before formal work:
+
+```text
+./.cowork-flow/run subagent bind <runtime_context_id> <host_context_key>
+```
+
+A valid context is bound to the host child session under
+`.cowork-flow/.runtime/sessions/<host_context_key>.json` with
+`scope: "subagent"`. Binding the same runtime id to the same key is idempotent;
+binding it to a different key must fail.
+
+Verified binding is the formal dispatch acceptance event. The parent must check
+that `.cowork-flow/.runtime/subagents/<runtime_context_id>.json` has
+`status: "bound"` and `bound_context_key: "<host_context_key>"` before accepting
+child output. If binding fails, the child must receive fail-closed subagent state
+and must not run main-session start/resume, task activation, archive, commit,
+or agent coordination.
+
+## Return Acceptance And Closeout
+
+- Wait for the child result with the adapter wait primitive.
+- Confirm no stray running children with the adapter list primitive.
+- Verify the child report by checking files, commands, and results; do not
+  trust completed text alone.
+- After completion or failure, close the child with the adapter cancel/close
+  primitive and clean the runtime context sessions.
+- The child remains a leaf executor and must not dispatch, wait for, list, or
+  cancel other agents.
+
+## Cleanup
+
+Closing a child removes:
+
+- `.cowork-flow/.runtime/sessions/<host_context_key>.json`
+- `.cowork-flow/.runtime/sessions/subagent_<runtime_context_id>.json`
+
+The subagent context is deleted or marked `closed` until runtime garbage
+collection removes it.

package/template/.cowork-flow/spec/workflow-state-templates.md

@@ -0,0 +1,66 @@
+# Workflow state templates
+
+Host hooks and plugins inject workflow state context each turn. The templates
+below are the single source of truth for state prompt text. Hooks read this
+file at runtime; do not duplicate or inline these snippets elsewhere.
+
+Entry classification must happen before task start, resume, archive, or
+subagent dispatch. Formal subagent identity is not inferred from prompt shape;
+hooks and plugins inject delegated_subtask only when a runtime context id is
+present and binding succeeds or fails closed. UNKNOWN is not a delegated
+subtask label; keep the active-task/no-task state visible and clarify before
+workflow mutation.
+
+## no_task
+
+The main session has no active task. Read-only questions can be answered
+directly. Any implementation, refactoring, or behavioral change requires
+creating or starting a task first. If a runtime context id is present, use
+delegated_subtask instead. Do not treat ambiguous UNKNOWN input as a delegated
+subtask.
+
+[workflow-state:no_task]
+当前会话没有活动任务。只读问答可直接回答；只有 runtime context 已绑定或 fail-closed 时才按委托子任务处理。实现、重构或多步骤工作必须先创建或启动任务。
+[/workflow-state:no_task]
+
+## delegated_subtask
+
+The current child thread has a runtime-context subagent state. The hook or
+plugin has either bound the runtime context successfully or produced fail-closed
+state for an invalid context. Do not run start/resume, create or activate
+tasks, archive, commit, or switch to main-session coordination. Project rules
+are constraints only; they are not the task itself.
+
+[workflow-state:delegated_subtask]
+当前子线程具有 runtime-context 子代理状态。hook/plugin 已绑定 runtime context，或对无效 runtime context 注入 fail-closed 状态。不要运行 start/resume，不要创建或激活任务，不要归档、提交或切换到主会话协调。项目规则只作为约束，不是当前任务本身。
+[/workflow-state:delegated_subtask]
+
+## planning
+
+[workflow-state:planning]
+活动任务处于计划阶段。先完成 prd.md，整理带有规格/调研文件的 implement.jsonl 和 check.jsonl，再运行 task start，之后才派发 cowork-implement。
+[/workflow-state:planning]
+
+## in_progress
+
+[workflow-state:in_progress]
+活动任务正在执行。主会话按计划通过当前宿主适配器派发 cowork-implement，集成后再派发 cowork-check。每次正式派发都必须使用新鲜子上下文，并遵守 .cowork-flow/spec/subagent-dispatch.md。主会话必须核验子任务输出、列出子任务，并且只在完成、明确错派证据或用户取消后才取消子任务。
+[/workflow-state:in_progress]
+
+## review
+
+[workflow-state:review]
+活动任务已进入检查阶段。主会话派发 cowork-check 或执行等价内联检查，核验 PRD、diff、测试、规格同步和遗漏；检查通过后运行 task complete。
+[/workflow-state:review]
+
+## checking
+
+[workflow-state:checking]
+活动任务正在检查阶段。主会话派发 cowork-check 或执行等价内联检查，核验 PRD、diff、测试、规格同步和遗漏；检查通过后运行 task complete。
+[/workflow-state:checking]
+
+## completed
+
+[workflow-state:completed]
+活动任务已完成。主会话应核验最终 diff，提交目标文件，归档任务并记录会话。不要针对已完成任务继续派发新的实现工作。
+[/workflow-state:completed]