cowork-flow 0.0.2 → 0.0.4

package/template/.cowork-flow/run.cmd

@@ -0,0 +1,191 @@
+@echo off
+setlocal EnableExtensions
+
+set "MIN_PYTHON_LABEL=Python 3.8+"
+set "VERSION_CHECK=import sys; raise SystemExit(0 if sys.version_info >= (3, 8) else 1)"
+set "WORKFLOW_DIR=%~dp0"
+set "SCRIPTS_DIR=%WORKFLOW_DIR%scripts"
+set "SELECTED_PYTHON="
+set "SELECTED_PYTHON_ARG="
+set "REST_ARGS="
+
+if "%~1"=="" goto usage_error
+
+set "COMMAND_NAME=%~1"
+if not "%~2"=="" (
+  for /F "tokens=1,* delims= " %%A in ("%*") do set "REST_ARGS=%%B"
+)
+
+if /I "%COMMAND_NAME%"=="-h" goto usage
+if /I "%COMMAND_NAME%"=="--help" goto usage
+if /I "%COMMAND_NAME%"=="help" goto usage
+if /I "%COMMAND_NAME%"=="python" goto run_python_passthrough
+if /I "%COMMAND_NAME%"=="resume" goto run_resume
+if /I "%COMMAND_NAME%"=="task" goto run_task
+if /I "%COMMAND_NAME%"=="change" goto run_change
+if /I "%COMMAND_NAME%"=="get-context" goto run_get_context
+if /I "%COMMAND_NAME%"=="get_context" goto run_get_context
+if /I "%COMMAND_NAME%"=="get-developer" goto run_get_developer
+if /I "%COMMAND_NAME%"=="get_developer" goto run_get_developer
+if /I "%COMMAND_NAME%"=="init-developer" goto run_init_developer
+if /I "%COMMAND_NAME%"=="init_developer" goto run_init_developer
+if /I "%COMMAND_NAME%"=="add-session" goto run_add_session
+if /I "%COMMAND_NAME%"=="add_session" goto run_add_session
+
+if exist "%SCRIPTS_DIR%\%COMMAND_NAME%.py" (
+  call :run_script "%SCRIPTS_DIR%\%COMMAND_NAME%.py"
+  exit /b %ERRORLEVEL%
+)
+
+echo 错误：未知 cowork-flow 命令：%COMMAND_NAME% 1>&2
+call :print_usage 1>&2
+exit /b 2
+
+:usage
+call :print_usage
+exit /b 0
+
+:usage_error
+call :print_usage 1>&2
+exit /b 2
+
+:run_python_passthrough
+call :exec_python %REST_ARGS%
+exit /b %ERRORLEVEL%
+
+:run_resume
+call :run_script "%SCRIPTS_DIR%\resume.py"
+exit /b %ERRORLEVEL%
+
+:run_task
+call :run_script "%SCRIPTS_DIR%\task.py"
+exit /b %ERRORLEVEL%
+
+:run_change
+call :run_script "%SCRIPTS_DIR%\change.py"
+exit /b %ERRORLEVEL%
+
+:run_get_context
+call :run_script "%SCRIPTS_DIR%\get_context.py"
+exit /b %ERRORLEVEL%
+
+:run_get_developer
+call :run_script "%SCRIPTS_DIR%\get_developer.py"
+exit /b %ERRORLEVEL%
+
+:run_init_developer
+call :run_script "%SCRIPTS_DIR%\init_developer.py"
+exit /b %ERRORLEVEL%
+
+:run_add_session
+call :run_script "%SCRIPTS_DIR%\add_session.py"
+exit /b %ERRORLEVEL%
+
+:print_usage
+echo 用法：
+echo   .\.cowork-flow\run.cmd ^<command^> [args...]
+echo   .\.cowork-flow\run.cmd python [python-args...]
+echo.
+echo 常用 command：
+echo   resume
+echo   task
+echo   change
+echo   get-context
+echo   get-developer
+echo   init-developer
+echo   add-session
+echo.
+echo 解释器选择顺序：
+echo   COWORK_FLOW_PYTHON -^> PYTHON -^> python3 -^> python -^> py -3
+exit /b 0
+
+:candidate_is_valid
+set "CANDIDATE_CMD=%~1"
+set "CANDIDATE_ARG=%~2"
+
+where "%CANDIDATE_CMD%" >nul 2>nul
+if errorlevel 1 (
+  if not exist "%CANDIDATE_CMD%" exit /b 1
+)
+
+if not "%CANDIDATE_ARG%"=="" (
+  "%CANDIDATE_CMD%" "%CANDIDATE_ARG%" -c "%VERSION_CHECK%" >nul 2>nul
+) else (
+  "%CANDIDATE_CMD%" -c "%VERSION_CHECK%" >nul 2>nul
+)
+exit /b %ERRORLEVEL%
+
+:select_explicit_python
+set "ENV_NAME=%~1"
+set "ENV_VALUE=%~2"
+
+call :candidate_is_valid "%ENV_VALUE%" ""
+if not errorlevel 1 (
+  set "SELECTED_PYTHON=%ENV_VALUE%"
+  set "SELECTED_PYTHON_ARG="
+  exit /b 0
+)
+
+echo 错误：%ENV_NAME% 指向的解释器不可用或版本低于 %MIN_PYTHON_LABEL%：%ENV_VALUE% 1>&2
+echo 请设置 %ENV_NAME% 为可执行的 Python 3.8+ 解释器路径。 1>&2
+exit /b 127
+
+:select_python
+set "SELECTED_PYTHON="
+set "SELECTED_PYTHON_ARG="
+
+if not "%COWORK_FLOW_PYTHON%"=="" (
+  call :select_explicit_python "COWORK_FLOW_PYTHON" "%COWORK_FLOW_PYTHON%"
+  exit /b %ERRORLEVEL%
+)
+
+if not "%PYTHON%"=="" (
+  call :select_explicit_python "PYTHON" "%PYTHON%"
+  exit /b %ERRORLEVEL%
+)
+
+call :candidate_is_valid "python3" ""
+if not errorlevel 1 (
+  set "SELECTED_PYTHON=python3"
+  exit /b 0
+)
+
+call :candidate_is_valid "python" ""
+if not errorlevel 1 (
+  set "SELECTED_PYTHON=python"
+  exit /b 0
+)
+
+call :candidate_is_valid "py" "-3"
+if not errorlevel 1 (
+  set "SELECTED_PYTHON=py"
+  set "SELECTED_PYTHON_ARG=-3"
+  exit /b 0
+)
+
+echo 错误：需要 %MIN_PYTHON_LABEL%，但未找到可用解释器。 1>&2
+echo 已尝试：COWORK_FLOW_PYTHON、PYTHON、python3、python、py -3。 1>&2
+echo 可设置 COWORK_FLOW_PYTHON=C:\Path\To\python.exe 后重试。 1>&2
+exit /b 127
+
+:exec_python
+call :select_python
+if errorlevel 1 exit /b %ERRORLEVEL%
+
+if not "%SELECTED_PYTHON_ARG%"=="" (
+  "%SELECTED_PYTHON%" "%SELECTED_PYTHON_ARG%" %*
+) else (
+  "%SELECTED_PYTHON%" %*
+)
+exit /b %ERRORLEVEL%
+
+:run_script
+set "SCRIPT_PATH=%~1"
+
+if not exist "%SCRIPT_PATH%" (
+  echo 错误：找不到脚本：%SCRIPT_PATH% 1>&2
+  exit /b 2
+)
+
+call :exec_python "%SCRIPT_PATH%" %REST_ARGS%
+exit /b %ERRORLEVEL%

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

@@ -4,8 +4,8 @@
 Add a new session to journal file and update index.md.
 
 Usage:
-    python3 add_session.py --title "Title" --commit "hash" --summary "Summary"
-    echo "content" | python3 add_session.py --title "Title" --commit "hash"
+    ./.cowork-flow/run add-session --title "Title" --commit "hash" --summary "Summary"
+    echo "content" | ./.cowork-flow/run add-session --title "Title" --commit "hash"
 """
 
 from __future__ import annotations

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

@@ -92,11 +92,8 @@ def _has_text(path: Path) -> bool:
     return path.is_file() and bool(path.read_text(encoding="utf-8").strip())
 
 
-def _spec_files(change_dir: Path) -> list[Path]:
-    specs_dir = change_dir / "specs"
-    if not specs_dir.is_dir():
-        return []
-    return sorted(path for path in specs_dir.rglob("spec.md") if path.is_file())
+def _spec_file(change_dir: Path) -> Path:
+    return change_dir / "spec.md"
 
 
 def _resolve_link(repo_root: Path, base_dir: str, value: object) -> Path | None:
@@ -151,10 +148,8 @@ def validate_change(repo_root: Path, slug: str, quiet: bool = False) -> bool:
             errors.append("proposal.md is missing or empty")
 
         documentation_only = metadata.get("documentation_only") is True
-        if not documentation_only:
-            specs = _spec_files(change_dir)
-            if not specs or not any(_has_text(spec) for spec in specs):
-                errors.append("specs must include at least one non-empty behavior spec")
+        if not documentation_only and not _has_text(_spec_file(change_dir)):
+            errors.append("spec.md is missing or empty")
 
         if level == "L2" and not _has_text(change_dir / "design.md"):
             errors.append("design.md is required for L2 changes")
@@ -189,13 +184,12 @@ def create_change(args: argparse.Namespace) -> int:
         return 1
 
     change_dir.mkdir(parents=True)
-    (change_dir / "specs").mkdir()
     (change_dir / "proposal.md").write_text(
         f"# {slug}\n\nDescribe the proposed behavior change.\n",
         encoding="utf-8",
     )
     (change_dir / "design.md").write_text("", encoding="utf-8")
-    (change_dir / "specs" / ".gitkeep").write_text("", encoding="utf-8")
+    _spec_file(change_dir).write_text("", encoding="utf-8")
     _write_metadata(
         change_dir,
         {

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

@@ -174,7 +174,7 @@ def ensure_developer(repo_root: Path | None = None) -> None:
 
     if not check_developer(repo_root):
         print("Error: developer identity has not been initialized.", file=sys.stderr)
-        print(f"Run: python3 ./{DIR_WORKFLOW}/scripts/init_developer.py <your-name>", file=sys.stderr)
+        print(f"Run: ./{DIR_WORKFLOW}/run init-developer <your-name>", file=sys.stderr)
         sys.exit(1)
 
 

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

@@ -31,6 +31,8 @@ from .paths import (
     get_tasks_dir,
 )
 
+CONTEXT_JSONL_FILES = ("implement.jsonl", "check.jsonl", "debug.jsonl")
+
 # =============================================================================
 # Helper Functions
 # =============================================================================
@@ -191,6 +193,93 @@ def _get_current_task_snapshot(repo_root: Path) -> CurrentTaskSnapshot:
     )
 
 
+def _jsonl_file_references(jsonl_path: Path) -> list[str]:
+    """读取 JSONL 中声明的文件引用，忽略损坏行。"""
+    references: list[str] = []
+    if not jsonl_path.is_file():
+        return references
+
+    try:
+        lines = jsonl_path.read_text(encoding="utf-8").splitlines()
+    except (OSError, IOError):
+        return references
+
+    for line in lines:
+        if not line.strip():
+            continue
+        try:
+            data = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+
+        file_path = data.get("file")
+        if isinstance(file_path, str) and file_path.strip():
+            references.append(file_path.strip())
+
+    return references
+
+
+def _task_plan_references(repo_root: Path, snapshot: CurrentTaskSnapshot) -> list[str]:
+    """从当前任务上下文中提取 plan 文件引用。"""
+    if not snapshot.path:
+        return []
+
+    task_dir = repo_root / snapshot.path
+    plan_refs: list[str] = []
+    seen: set[str] = set()
+
+    data = snapshot.data or {}
+    metadata_candidates = [
+        data.get("plan"),
+        data.get("planFile"),
+        data.get("meta", {}).get("plan") if isinstance(data.get("meta"), dict) else None,
+        data.get("meta", {}).get("planFile") if isinstance(data.get("meta"), dict) else None,
+    ]
+
+    for candidate in metadata_candidates:
+        if isinstance(candidate, str) and candidate.startswith(f"{DIR_WORKFLOW}/plans/"):
+            seen.add(candidate)
+            plan_refs.append(candidate)
+
+    for jsonl_name in CONTEXT_JSONL_FILES:
+        for reference in _jsonl_file_references(task_dir / jsonl_name):
+            if not reference.startswith(f"{DIR_WORKFLOW}/plans/"):
+                continue
+            if reference in seen:
+                continue
+            seen.add(reference)
+            plan_refs.append(reference)
+
+    return plan_refs
+
+
+def _build_resume_checklist(
+    repo_root: Path,
+    snapshot: CurrentTaskSnapshot,
+) -> dict[str, list[str]]:
+    """构建最小恢复清单，只返回路径和命令，不展开文件内容。"""
+    commands = [f"./{DIR_WORKFLOW}/run resume"]
+    read_files: list[str] = []
+    notes: list[str] = []
+
+    if not snapshot.path:
+        notes.append("No current task. Use `.agent/skills/start` to classify the next file-changing request.")
+        notes.append("Do not bulk-read `.cowork-flow/spec/` or workspace journals; read details only after a task is selected.")
+        return {"commands": commands, "readFiles": read_files, "notes": notes}
+
+    current_task = snapshot.path
+    commands.append(f"./{DIR_WORKFLOW}/run task list-context {current_task}")
+
+    if snapshot.has_prd:
+        read_files.append(f"{current_task}/prd.md")
+
+    read_files.extend(_task_plan_references(repo_root, snapshot))
+    notes.append("Read current plan status only when continuing implementation.")
+    notes.append("Do not bulk-read `.cowork-flow/spec/` or workspace journals; follow JSONL references on demand.")
+
+    return {"commands": commands, "readFiles": read_files, "notes": notes}
+
+
 def _current_task_json(snapshot: CurrentTaskSnapshot) -> dict | None:
     """Build the record-mode currentTask JSON object."""
     current_task = snapshot.path
@@ -205,6 +294,45 @@ def _current_task_json(snapshot: CurrentTaskSnapshot) -> dict | None:
     }
 
 
+def _append_resume_checklist(
+    lines: list[str],
+    repo_root: Path,
+    snapshot: CurrentTaskSnapshot,
+) -> None:
+    """向文本上下文追加最小恢复清单。"""
+    lines.append("## RESUME CHECKLIST")
+    checklist = _build_resume_checklist(repo_root, snapshot)
+    commands = checklist["commands"]
+    read_files = checklist["readFiles"]
+
+    lines.append(f"- Recovery entrypoint (rerun only if context is stale): {commands[0]}")
+
+    if not snapshot.path:
+        lines.append("- No current task. Run `.agent/skills/start` before editing files.")
+        lines.append("- Do not bulk-read .cowork-flow/spec/ or workspace journals; choose a task first.")
+        lines.append("")
+        return
+
+    current_task = snapshot.path
+    prd_path = f"{current_task}/prd.md"
+    if prd_path in read_files:
+        lines.append(f"- Read current task PRD: {prd_path}")
+    else:
+        lines.append(f"- Current task PRD missing: {prd_path}")
+
+    lines.append(f"- List task context before reading details: {commands[1]}")
+
+    plan_files = [path for path in read_files if path.startswith(f"{DIR_WORKFLOW}/plans/")]
+    if plan_files:
+        for plan_file in plan_files:
+            lines.append(f"- Read current plan status: {plan_file}")
+    else:
+        lines.append("- No plan reference found in task context; do not search all plans unless needed.")
+
+    lines.append("- Do not bulk-read .cowork-flow/spec/ or workspace journals; follow JSONL references on demand.")
+    lines.append("")
+
+
 def _append_current_task(
     lines: list[str],
     snapshot: CurrentTaskSnapshot,
@@ -297,6 +425,7 @@ def get_context_json(repo_root: Path | None = None) -> dict:
     tasks_dir = get_tasks_dir(repo_root)
     journal_file = get_active_journal_file(repo_root)
     git_snapshot = _get_git_snapshot(repo_root)
+    current_task_snapshot = _get_current_task_snapshot(repo_root)
 
     journal_lines = 0
     journal_relative = ""
@@ -331,6 +460,7 @@ def get_context_json(repo_root: Path | None = None) -> dict:
             "lines": journal_lines,
             "nearLimit": journal_lines > 1800,
         },
+        "resumeChecklist": _build_resume_checklist(repo_root, current_task_snapshot),
     }
 
 
@@ -373,7 +503,7 @@ def get_context_text(repo_root: Path | None = None) -> str:
     lines.append("## DEVELOPER")
     if not developer:
         lines.append(
-            f"ERROR: Not initialized. Run: python3 ./{DIR_WORKFLOW}/{DIR_SCRIPTS}/init_developer.py <name>"
+            f"ERROR: Not initialized. Run: ./{DIR_WORKFLOW}/run init-developer <name>"
         )
         return "\n".join(lines)
 
@@ -383,13 +513,15 @@ def get_context_text(repo_root: Path | None = None) -> str:
     git_snapshot = _get_git_snapshot(repo_root)
     _append_git_status(lines, git_snapshot, repo_root)
     _append_recent_commits(lines, git_snapshot)
+    current_task_snapshot = _get_current_task_snapshot(repo_root)
     _append_current_task(
         lines,
-        _get_current_task_snapshot(repo_root),
+        current_task_snapshot,
         include_created=True,
         include_description=True,
         include_prd_hint=True,
     )
+    _append_resume_checklist(lines, repo_root, current_task_snapshot)
 
     # Active tasks
     lines.append("## ACTIVE TASKS")
@@ -503,11 +635,14 @@ def get_context_record_json(repo_root: Path | None = None) -> dict:
                 "meta": data.get("meta", {}),
             })
 
+    current_task_snapshot = _get_current_task_snapshot(repo_root)
+
     return {
         "developer": developer or "",
         "git": _git_json(git_snapshot),
         "myTasks": my_tasks,
-        "currentTask": _current_task_json(_get_current_task_snapshot(repo_root)),
+        "currentTask": _current_task_json(current_task_snapshot),
+        "resumeChecklist": _build_resume_checklist(repo_root, current_task_snapshot),
     }
 
 
@@ -535,7 +670,7 @@ def get_context_text_record(repo_root: Path | None = None) -> str:
     developer = get_developer(repo_root)
     if not developer:
         lines.append(
-            f"ERROR: Not initialized. Run: python3 ./{DIR_WORKFLOW}/{DIR_SCRIPTS}/init_developer.py <name>"
+            f"ERROR: Not initialized. Run: ./{DIR_WORKFLOW}/run init-developer <name>"
         )
         return "\n".join(lines)
 
@@ -570,7 +705,9 @@ def get_context_text_record(repo_root: Path | None = None) -> str:
     git_snapshot = _get_git_snapshot(repo_root)
     _append_git_status(lines, git_snapshot, repo_root)
     _append_recent_commits(lines, git_snapshot)
-    _append_current_task(lines, _get_current_task_snapshot(repo_root))
+    current_task_snapshot = _get_current_task_snapshot(repo_root)
+    _append_current_task(lines, current_task_snapshot)
+    _append_resume_checklist(lines, repo_root, current_task_snapshot)
 
     lines.append("========================================")
 

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

@@ -3,8 +3,8 @@
 Get Session Context for AI Agent.
 
 Usage:
-    python3 get_context.py           Output context in text format
-    python3 get_context.py --json    Output context in JSON format
+    ./.cowork-flow/run get-context           Output context in text format
+    ./.cowork-flow/run get-context --json    Output context in JSON format
 """
 
 from __future__ import annotations

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

@@ -3,7 +3,7 @@
 Initialize developer for workflow.
 
 Usage:
-    python3 init_developer.py <developer-name>
+    ./.cowork-flow/run init-developer <developer-name>
 
 This creates:
     - .cowork-flow/.developer file with developer info

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

@@ -0,0 +1,21 @@
+#!/usr/bin/env python3
+"""恢复 cowork-flow 会话的最小入口。"""
+
+from __future__ import annotations
+
+from common.git_context import get_context_text
+
+
+def main() -> int:
+    print("========================================")
+    print("COWORK-FLOW RESUME")
+    print("========================================")
+    print("Use this after new sessions, long-task resumes, or context compression.")
+    print("Read RESUME CHECKLIST first; load details on demand.")
+    print("")
+    print(get_context_text())
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())