cowork-flow 0.0.2 → 0.0.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 fisklikewater
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -128,43 +128,55 @@ cowork-flow sync .
 cowork-flow sync . --dry-run
 ```
 
-`sync` 默认保护 `AGENTS.md`、`.cowork-flow/config.yaml`、`.cowork-flow/workflow.md`、`.cowork-flow/spec/`、任务、计划、变更和 workspace 记录。只有明确传入 `--force` 时才覆盖保护文件。
+`sync` 默认刷新 `.agent/skills/`、`.cowork-flow/scripts/` 和 `AGENTS.md` 中的 `<!-- COWORK-FLOW:START --> ... <!-- COWORK-FLOW:END -->` 托管块，保留 `AGENTS.md` 托管块之外的项目自定义内容。`.cowork-flow/config.yaml`、`.cowork-flow/workflow.md`、`.cowork-flow/spec/`、任务、计划、变更和 workspace 记录默认受保护。只有明确传入 `--force` 时才整文件覆盖保护文件。
 
 ## 常用入口
 
+模板内置统一入口来运行 Python 工作流脚本：
+
+- macOS / Linux / Git Bash / WSL：`./.cowork-flow/run`
+- Windows cmd / PowerShell：`.\.cowork-flow\run.cmd`
+
+入口会按 `COWORK_FLOW_PYTHON`、`PYTHON`、`python3`、`python`、`py -3`
+的顺序查找 Python 3.8+ 解释器，避免不同环境中 `python` / `python3`
+命令不一致的问题。
+
+下面示例使用 macOS / Linux 写法；Windows 原生命令行中把
+`./.cowork-flow/run` 替换为 `.\.cowork-flow\run.cmd`。
+
 初始化或查看开发者身份：
 
 ```bash
-python3 ./.cowork-flow/scripts/get_developer.py
-python3 ./.cowork-flow/scripts/init_developer.py <developer-name>
+./.cowork-flow/run get-developer
+./.cowork-flow/run init-developer <developer-name>
 ```
 
 查看当前上下文：
 
 ```bash
-python3 ./.cowork-flow/scripts/get_context.py
-python3 ./.cowork-flow/scripts/task.py list
+./.cowork-flow/run get-context
+./.cowork-flow/run task list
 ```
 
 创建并验证行为变更：
 
 ```bash
-python3 ./.cowork-flow/scripts/change.py create <slug>
-python3 ./.cowork-flow/scripts/change.py validate <slug>
+./.cowork-flow/run change create <slug>
+./.cowork-flow/run change validate <slug>
 ```
 
 创建并启动任务：
 
 ```bash
-python3 ./.cowork-flow/scripts/task.py create "<title>" --slug <task-name>
-python3 ./.cowork-flow/scripts/task.py start <task-dir>
+./.cowork-flow/run task create "<title>" --slug <task-name>
+./.cowork-flow/run task start <task-dir>
 ```
 
 记录 session：
 
 ```bash
-python3 ./.cowork-flow/scripts/get_context.py --mode record
-python3 ./.cowork-flow/scripts/add_session.py \
+./.cowork-flow/run get-context --mode record
+./.cowork-flow/run add-session \
   --title "<session-title>" \
   --commit "<commit-or-handoff-ref>" \
   --summary "<summary>"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cowork-flow",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "description": "CLI for installing and maintaining cowork-flow collaboration templates.",
   "type": "module",
   "bin": {
@@ -14,7 +14,7 @@
   ],
   "scripts": {
     "test": "node --test",
-    "test:template": "python3 -m unittest discover tests -v",
+    "test:template": "./template/.cowork-flow/run python -m unittest discover tests -v",
     "pack:check": "npm_config_cache=/tmp/cowork-flow-npm-cache npm pack --dry-run --json",
     "test:all": "npm test && npm run test:template && npm run pack:check"
   },

package/src/lib/copy-template.js

@@ -1,5 +1,5 @@
 import { constants } from 'node:fs';
-import { access, copyFile, mkdir, readdir, writeFile } from 'node:fs/promises';
+import { access, chmod, copyFile, mkdir, readFile, readdir, stat, writeFile } from 'node:fs/promises';
 import { dirname, join, relative } from 'node:path';
 
 import { templateRoot } from './paths.js';
@@ -110,9 +110,14 @@ const SAFE_SYNC_PREFIXES = [
 
 const SAFE_SYNC_FILES = new Set([
   '.cowork-flow/.gitignore',
-  '.cowork-flow/.version'
+  '.cowork-flow/.version',
+  '.cowork-flow/run',
+  '.cowork-flow/run.cmd'
 ]);
 
+const COWORK_FLOW_START = '<!-- COWORK-FLOW:START -->';
+const COWORK_FLOW_END = '<!-- COWORK-FLOW:END -->';
+
 function isProtectedSyncFile(relativePath) {
   return PROTECTED_SYNC_FILES.has(relativePath)
     || PROTECTED_SYNC_PREFIXES.some((prefix) => relativePath.startsWith(prefix));
@@ -124,6 +129,48 @@ function isSafeSyncFile(relativePath) {
     || relativePath.endsWith('/.gitkeep');
 }
 
+function replaceManagedBlock(targetContent, templateContent) {
+  const targetStart = targetContent.indexOf(COWORK_FLOW_START);
+  const targetEnd = targetContent.indexOf(COWORK_FLOW_END, targetStart + COWORK_FLOW_START.length);
+  const templateStart = templateContent.indexOf(COWORK_FLOW_START);
+  const templateEnd = templateContent.indexOf(COWORK_FLOW_END, templateStart + COWORK_FLOW_START.length);
+
+  if (targetStart === -1 || targetEnd === -1 || templateStart === -1 || templateEnd === -1) {
+    return null;
+  }
+
+  const targetBlockEnd = targetEnd + COWORK_FLOW_END.length;
+  const templateBlockEnd = templateEnd + COWORK_FLOW_END.length;
+  return [
+    targetContent.slice(0, targetStart),
+    templateContent.slice(templateStart, templateBlockEnd),
+    targetContent.slice(targetBlockEnd)
+  ].join('');
+}
+
+async function buildAgentsSyncAction({ source, destination, exists, options }) {
+  if (!exists || options.force) {
+    return {
+      action: exists ? 'update' : 'create',
+      source,
+      destination,
+      relativePath: 'AGENTS.md'
+    };
+  }
+
+  const [templateContent, targetContent] = await Promise.all([
+    readFile(source, 'utf8'),
+    readFile(destination, 'utf8')
+  ]);
+  const content = replaceManagedBlock(targetContent, templateContent);
+
+  if (content === null) {
+    return { action: 'protected', source, destination, relativePath: 'AGENTS.md' };
+  }
+
+  return { action: 'update', source, destination, relativePath: 'AGENTS.md', content };
+}
+
 export async function buildSyncPlan(targetDir, options = {}) {
   if (!await pathExists(join(targetDir, '.cowork-flow'))) {
     throw new Error(`Target is not initialized: ${targetDir}`);
@@ -140,6 +187,11 @@ export async function buildSyncPlan(targetDir, options = {}) {
     const source = join(templateRoot, file);
     const destination = join(targetDir, file);
     const exists = await pathExists(destination);
+    if (file === 'AGENTS.md') {
+      actions.push(await buildAgentsSyncAction({ source, destination, exists, options }));
+      continue;
+    }
+
     const protectedFile = isProtectedSyncFile(file) && !options.force && exists;
     const safeFile = isSafeSyncFile(file);
 
@@ -192,6 +244,8 @@ export async function applyPlan(actions, options = {}) {
       await writeFile(item.destination, item.content, 'utf8');
     } else {
       await copyFile(item.source, item.destination);
+      const sourceStats = await stat(item.source);
+      await chmod(item.destination, sourceStats.mode & 0o777);
     }
   }
 }

package/template/.agent/skills/record-session/SKILL.md

@@ -24,7 +24,7 @@ Do not archive a task while the plan file still shows stale progress.
 ### Step 1: Get Context & Check Tasks
 
 ```bash
-python3 ./.cowork-flow/scripts/get_context.py --mode record
+./.cowork-flow/run get-context --mode record
 ```
 
 [!] Archive tasks whose work is **actually done** — judge by work status, not the `status` field in task.json:
@@ -33,20 +33,20 @@ python3 ./.cowork-flow/scripts/get_context.py --mode record
 - Don't skip archiving just because `status` still says `planning` or `in_progress`
 
 ```bash
-python3 ./.cowork-flow/scripts/task.py archive <task-name>
+./.cowork-flow/run task archive <task-name>
 ```
 
 ### Step 2: One-Click Add Session
 
 ```bash
 # Method 1: Simple parameters
-python3 ./.cowork-flow/scripts/add_session.py \
+./.cowork-flow/run add-session \
   --title "Session Title" \
   --commit "hash1,hash2" \
   --summary "Brief summary of what was done"
 
 # Method 2: Pass detailed content via stdin
-cat << 'EOF' | python3 ./.cowork-flow/scripts/add_session.py --title "Title" --commit "hash"
+cat << 'EOF' | ./.cowork-flow/run add-session --title "Title" --commit "hash"
 | Feature | Description |
 |---------|-------------|
 | Change | Description |
@@ -72,7 +72,7 @@ EOF
 
 | Command | Purpose |
 |---------|---------|
-| `python3 ./.cowork-flow/scripts/get_context.py --mode record` | Get context for record-session |
-| `python3 ./.cowork-flow/scripts/add_session.py --title "..." --commit "..."` | **One-click add session (recommended)** |
-| `python3 ./.cowork-flow/scripts/task.py archive <name>` | Archive completed task (auto-commits) |
-| `python3 ./.cowork-flow/scripts/task.py list` | List active tasks |
+| `./.cowork-flow/run get-context --mode record` | Get context for record-session |
+| `./.cowork-flow/run add-session --title "..." --commit "..."` | **One-click add session (recommended)** |
+| `./.cowork-flow/run task archive <name>` | Archive completed task (auto-commits) |
+| `./.cowork-flow/run task list` | List active tasks |

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

@@ -7,6 +7,14 @@ description: Use when beginning a development session in a project that uses the
 
 Initialize your AI development session and begin working on tasks.
 
+<HARD-GATE>
+Any request that changes repository files MUST go through this skill's task workflow.
+Questions may be answered directly, but file edits are at least `L0` and require a task,
+PRD, context initialization, task activation, verification, and session recording.
+Do not use a direct-edit shortcut unless the user explicitly tells you not to use
+cowork-flow for this task.
+</HARD-GATE>
+
 ---
 
 ## Operation Types
@@ -36,16 +44,21 @@ cat AGENTS.md
 - Best practices
 - Project-specific collaboration and documentation rules
 
+Command examples use macOS / Linux / Git Bash / WSL syntax. In native Windows
+cmd or PowerShell, replace `./.cowork-flow/run <command>` with
+`.\.cowork-flow\run.cmd <command>`.
+
 > **Important**:
 > Reusable skills are already part of the template. During project onboarding, put project-specific facts in `AGENTS.md`, `.cowork-flow/workflow.md`, `.cowork-flow/config.yaml`, and `.cowork-flow/spec/` rather than editing `SKILL.md`.
 
 ### Step 2: Get Current Context
 
 ```bash
-python3 ./.cowork-flow/scripts/get_context.py
+./.cowork-flow/run resume
 ```
 
-This shows: developer identity, git status, current task (if any), active tasks.
+This shows: developer identity, git status, current task (if any), active tasks, and
+the minimal `RESUME CHECKLIST` for loading task details on demand.
 
 ### Step 3: Read Guidelines Index
 
@@ -71,13 +84,19 @@ When user describes a task, classify it:
 
 | Type | Criteria | Workflow |
 |------|----------|----------|
-| **Question** | User asks about code, architecture, or how something works | Answer directly |
-| **Trivial Fix** | Typo fix, comment update, single-line change, < 5 minutes | Direct Edit |
-| **Simple Task** | Clear goal, 1-2 files, well-defined scope | Quick confirm → Task Workflow |
-| **Complex Task** | Vague goal, multiple files, architectural decisions | **Brainstorm → Task Workflow** |
+| **Question** | User asks about code, architecture, or how something works, and no repository files need to change | Answer directly after session context is loaded |
+| **L0 Change** | Docs, tests, comments, config, small refactors, or any file change without external behavior change | Task Workflow, no Behavior Change Gate |
+| **L1 Change** | Bounded behavior change in one module or one interface | Behavior Change Gate → Task Workflow |
+| **L2 Change** | Cross-layer, architectural, migration, permission, compatibility, release, or security-impacting change | Behavior Change Gate + `design.md` → Task Workflow |
+| **Unclear / Complex** | Vague goal, multiple possible interpretations, or architectural decisions | **Brainstorm → classify L0/L1/L2 → gated workflow** |
 
 ### Decision Rule
 
+> **Any file change must enter L0 / L1 / L2 workflow.**
+>
+> A typo, comment, one-line fix, or "quick" change is still a repository change.
+> Do not treat small size as permission to skip PRD, context, verification, or session recording.
+>
 > **If in doubt, use Brainstorm + Task Workflow.**
 >
 > Task Workflow ensures code-specs are injected to the right context, resulting in higher quality code.
@@ -93,9 +112,9 @@ Before entering Task Workflow, classify the change as `L0` / `L1` / `L2` using `
 
 - `L0`: No external behavior change. Continue with the existing Task Workflow.
 - `L1`: Behavior change in a bounded module. Do **not** go straight to PRD/Research. First run:
-  1. `python3 ./.cowork-flow/scripts/change.py create <slug>`
+  1. `./.cowork-flow/run change create <slug>`
   2. `superpowers:brainstorming` to create or complete `proposal/spec`
-  3. `python3 ./.cowork-flow/scripts/change.py validate <slug>`
+  3. `./.cowork-flow/run change validate <slug>`
   4. `superpowers:writing-plans` to produce the implementation plan
 - `L2`: Same as `L1`, plus required `design.md`. Multi-perspective review happens after implementation in the review gate.
 
@@ -114,24 +133,24 @@ Before Phase 2, always complete this task handoff:
 
 ---
 
-## Question / Trivial Fix
+## Question Only
 
-For questions or trivial fixes, work directly:
+For questions that do not modify repository files, work directly:
 
-1. Answer question or make the fix
-2. If code was changed, follow the current session convention for verification, business-code commit or handoff, and `$record-session`
+1. Answer the question.
+2. If the answer reveals that files should change, stop and re-enter Task Classification.
+3. Do not modify files from this section.
 
 ---
 
-## Simple Task
+## L0 / Simple Task
 
-For simple, well-defined tasks:
+For simple, well-defined tasks that modify files without external behavior change:
 
-1. Quick confirm: "I understand you want to [goal]. Shall I proceed?"
-2. If no, clarify and confirm again
-3. Determine whether the task is `L0`, `L1`, or `L2`.
-4. **If it is `L1/L2`, complete the Behavior Change Gate first. After that, execute Path B Step 2 and Step 3, complete the task handoff, then continue with Phase 2.**
-5. **If it is `L0`, execute ALL steps below without stopping. Do NOT ask for additional confirmation between steps.**
+1. Clarify only if the goal, scope, or verification method is unclear.
+2. Determine whether the task is `L0`, `L1`, or `L2`.
+3. **If it is `L1/L2`, complete the Behavior Change Gate first. After that, execute Path B Step 2 and Step 3, complete the task handoff, then continue with Phase 2.**
+4. **If it is `L0`, execute ALL steps below without stopping. Do NOT ask for additional confirmation between steps. Do NOT switch to ad hoc direct editing.**
    - Create task directory (Phase 1 Path B, Step 2)
    - Write PRD (Step 3)
    - Research codebase (Phase 2, Step 5)
@@ -202,7 +221,7 @@ If unclear, ask clarifying questions.
 **Step 2: Create Task Directory** `[AI]`
 
 ```bash
-TASK_DIR=$(python3 ./.cowork-flow/scripts/task.py create "<title>" --slug <name>)
+TASK_DIR=$(./.cowork-flow/run task create "<title>" --slug <name>)
 ```
 
 **Step 3: Write PRD** `[AI]`
@@ -275,7 +294,7 @@ Use this output format:
 Initialize default context:
 
 ```bash
-python3 ./.cowork-flow/scripts/task.py init-context "$TASK_DIR" <type>
+./.cowork-flow/run task init-context "$TASK_DIR" <type>
 # type: backend | frontend | fullstack
 ```
 
@@ -283,25 +302,25 @@ Add specs found in your research pass:
 
 ```bash
 # For each relevant spec and code pattern:
-python3 ./.cowork-flow/scripts/task.py add-context "$TASK_DIR" implement "<path>" "<reason>"
-python3 ./.cowork-flow/scripts/task.py add-context "$TASK_DIR" check "<path>" "<reason>"
+./.cowork-flow/run task add-context "$TASK_DIR" implement "<path>" "<reason>"
+./.cowork-flow/run task add-context "$TASK_DIR" check "<path>" "<reason>"
 ```
 
 If this task came through the Behavior Change Gate, add the approved artifacts before coding:
 
 ```bash
-python3 ./.cowork-flow/scripts/task.py add-context "$TASK_DIR" implement ".cowork-flow/changes/<slug>/proposal.md" "Approved change proposal"
-python3 ./.cowork-flow/scripts/task.py add-context "$TASK_DIR" implement ".cowork-flow/changes/<slug>/specs/.../spec.md" "Approved behavior spec"
-python3 ./.cowork-flow/scripts/task.py add-context "$TASK_DIR" implement ".cowork-flow/changes/<slug>/design.md" "Approved design for L2 changes"
-python3 ./.cowork-flow/scripts/task.py add-context "$TASK_DIR" implement ".cowork-flow/plans/YYYY-MM-DD-<slug>.md" "Approved implementation plan"
-python3 ./.cowork-flow/scripts/task.py add-context "$TASK_DIR" check ".cowork-flow/changes/<slug>/specs/.../spec.md" "Check implementation against approved spec"
-python3 ./.cowork-flow/scripts/task.py add-context "$TASK_DIR" check ".cowork-flow/plans/YYYY-MM-DD-<slug>.md" "Check implementation against approved plan"
+./.cowork-flow/run task add-context "$TASK_DIR" implement ".cowork-flow/changes/<slug>/proposal.md" "Approved change proposal"
+./.cowork-flow/run task add-context "$TASK_DIR" implement ".cowork-flow/changes/<slug>/spec.md" "Approved behavior spec"
+./.cowork-flow/run task add-context "$TASK_DIR" implement ".cowork-flow/changes/<slug>/design.md" "Approved design for L2 changes"
+./.cowork-flow/run task add-context "$TASK_DIR" implement ".cowork-flow/plans/YYYY-MM-DD-<slug>.md" "Approved implementation plan"
+./.cowork-flow/run task add-context "$TASK_DIR" check ".cowork-flow/changes/<slug>/spec.md" "Check implementation against approved spec"
+./.cowork-flow/run task add-context "$TASK_DIR" check ".cowork-flow/plans/YYYY-MM-DD-<slug>.md" "Check implementation against approved plan"
 ```
 
 **Step 7: Activate Task** `[AI]`
 
 ```bash
-python3 ./.cowork-flow/scripts/task.py start "$TASK_DIR"
+./.cowork-flow/run task start "$TASK_DIR"
 ```
 
 This sets `.current-task` so hooks can inject context.
@@ -339,7 +358,7 @@ Run a quality pass against check context:
 
 ## Continuing Existing Task
 
-If `get_context.py` shows a current task:
+If `resume.py` shows a current task:
 
 1. Read the task's `prd.md` to understand the goal
 2. Check `task.json` for current status
@@ -349,6 +368,23 @@ If yes, resume from the appropriate step (usually Step 7 or 8).
 
 ---
 
+## Resume / Context Compression
+
+When a conversation has many rounds, a task runs for a long time, or context was
+compressed, resume with the smallest useful context:
+
+1. Run `./.cowork-flow/run resume`.
+2. Follow the `RESUME CHECKLIST` section.
+3. Read the current task `prd.md`.
+4. Run `./.cowork-flow/run task list-context <task-dir>` and read only the jsonl references needed for the current phase.
+5. If a plan is listed, read its current execution status before continuing implementation.
+
+Do not bulk-read `.cowork-flow/spec/`, all plans, all tasks, or workspace journals
+just because context was compressed. Use the checklist as the minimal recovery
+anchor, then load details on demand.
+
+---
+
 ## Skills Reference
 
 ### User Skills `[USER]`
@@ -363,13 +399,14 @@ If yes, resume from the appropriate step (usually Step 7 or 8).
 
 | Script | Purpose |
 |--------|---------|
-| `python3 ./.cowork-flow/scripts/get_context.py` | Get session context |
-| `python3 ./.cowork-flow/scripts/task.py create` | Create task directory |
-| `python3 ./.cowork-flow/scripts/task.py init-context` | Initialize jsonl files |
-| `python3 ./.cowork-flow/scripts/task.py add-context` | Add spec to jsonl |
-| `python3 ./.cowork-flow/scripts/task.py start` | Set current task |
-| `python3 ./.cowork-flow/scripts/task.py finish` | Clear current task |
-| `python3 ./.cowork-flow/scripts/task.py archive` | Archive completed task |
+| `./.cowork-flow/run resume` | Resume session with minimal context checklist |
+| `./.cowork-flow/run get-context` | Get session context |
+| `./.cowork-flow/run task create` | Create task directory |
+| `./.cowork-flow/run task init-context` | Initialize jsonl files |
+| `./.cowork-flow/run task add-context` | Add spec to jsonl |
+| `./.cowork-flow/run task start` | Set current task |
+| `./.cowork-flow/run task finish` | Clear current task |
+| `./.cowork-flow/run task archive` | Archive completed task |
 
 ### Workflow Phases `[AI]`
 

package/template/.cowork-flow/.version

@@ -1 +1 @@
-0.0.2
+0.0.4

package/template/.cowork-flow/run

@@ -0,0 +1,162 @@
+#!/bin/sh
+set -u
+
+MIN_PYTHON_LABEL="Python 3.8+"
+VERSION_CHECK='import sys; raise SystemExit(0 if sys.version_info >= (3, 8) else 1)'
+
+WORKFLOW_DIR=$(CDPATH= cd "$(dirname "$0")" && pwd) || exit 1
+SCRIPTS_DIR="$WORKFLOW_DIR/scripts"
+
+print_usage() {
+  cat <<'EOF'
+用法：
+  ./.cowork-flow/run <command> [args...]
+  ./.cowork-flow/run python [python-args...]
+
+常用 command：
+  resume
+  task
+  change
+  get-context
+  get-developer
+  init-developer
+  add-session
+
+解释器选择顺序：
+  COWORK_FLOW_PYTHON -> PYTHON -> python3 -> python -> py -3
+EOF
+}
+
+candidate_is_valid() {
+  candidate_cmd=$1
+  candidate_arg=${2:-}
+
+  command -v "$candidate_cmd" >/dev/null 2>&1 || return 1
+
+  if [ -n "$candidate_arg" ]; then
+    "$candidate_cmd" "$candidate_arg" -c "$VERSION_CHECK" >/dev/null 2>&1
+  else
+    "$candidate_cmd" -c "$VERSION_CHECK" >/dev/null 2>&1
+  fi
+}
+
+select_explicit_python() {
+  env_name=$1
+  env_value=$2
+
+  if candidate_is_valid "$env_value"; then
+    SELECTED_PYTHON=$env_value
+    SELECTED_PYTHON_ARG=
+    return 0
+  fi
+
+  echo "错误：$env_name 指向的解释器不可用或版本低于 ${MIN_PYTHON_LABEL}：$env_value" >&2
+  echo "请设置 $env_name 为可执行的 Python 3.8+ 解释器路径。" >&2
+  exit 127
+}
+
+select_python() {
+  SELECTED_PYTHON=
+  SELECTED_PYTHON_ARG=
+
+  if [ -n "${COWORK_FLOW_PYTHON:-}" ]; then
+    select_explicit_python "COWORK_FLOW_PYTHON" "$COWORK_FLOW_PYTHON"
+    return 0
+  fi
+
+  if [ -n "${PYTHON:-}" ]; then
+    select_explicit_python "PYTHON" "$PYTHON"
+    return 0
+  fi
+
+  if candidate_is_valid "python3"; then
+    SELECTED_PYTHON=python3
+    return 0
+  fi
+
+  if candidate_is_valid "python"; then
+    SELECTED_PYTHON=python
+    return 0
+  fi
+
+  if candidate_is_valid "py" "-3"; then
+    SELECTED_PYTHON=py
+    SELECTED_PYTHON_ARG=-3
+    return 0
+  fi
+
+  echo "错误：需要 ${MIN_PYTHON_LABEL}，但未找到可用解释器。" >&2
+  echo "已尝试：COWORK_FLOW_PYTHON、PYTHON、python3、python、py -3。" >&2
+  echo "可设置 COWORK_FLOW_PYTHON=/path/to/python3 后重试。" >&2
+  exit 127
+}
+
+exec_python() {
+  select_python
+
+  if [ -n "$SELECTED_PYTHON_ARG" ]; then
+    exec "$SELECTED_PYTHON" "$SELECTED_PYTHON_ARG" "$@"
+  fi
+
+  exec "$SELECTED_PYTHON" "$@"
+}
+
+run_script() {
+  script_path=$1
+  shift
+
+  if [ ! -f "$script_path" ]; then
+    echo "错误：找不到脚本：$script_path" >&2
+    exit 2
+  fi
+
+  exec_python "$script_path" "$@"
+}
+
+if [ "$#" -eq 0 ]; then
+  print_usage >&2
+  exit 2
+fi
+
+command_name=$1
+shift
+
+case "$command_name" in
+  -h|--help|help)
+    print_usage
+    exit 0
+    ;;
+  python)
+    exec_python "$@"
+    ;;
+  resume)
+    run_script "$SCRIPTS_DIR/resume.py" "$@"
+    ;;
+  task)
+    run_script "$SCRIPTS_DIR/task.py" "$@"
+    ;;
+  change)
+    run_script "$SCRIPTS_DIR/change.py" "$@"
+    ;;
+  get-context|get_context)
+    run_script "$SCRIPTS_DIR/get_context.py" "$@"
+    ;;
+  get-developer|get_developer)
+    run_script "$SCRIPTS_DIR/get_developer.py" "$@"
+    ;;
+  init-developer|init_developer)
+    run_script "$SCRIPTS_DIR/init_developer.py" "$@"
+    ;;
+  add-session|add_session)
+    run_script "$SCRIPTS_DIR/add_session.py" "$@"
+    ;;
+  *)
+    if [ -f "$SCRIPTS_DIR/$command_name.py" ]; then
+      run_script "$SCRIPTS_DIR/$command_name.py" "$@"
+    fi
+
+    echo "错误：未知 cowork-flow 命令：$command_name" >&2
+    print_usage >&2
+    exit 2
+    ;;
+esac