cowork-flow 0.0.2 → 0.0.3

package/README.md

@@ -128,7 +128,7 @@ 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` 时才整文件覆盖保护文件。
 
 ## 常用入口
 

package/package.json

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

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, copyFile, mkdir, readFile, readdir, writeFile } from 'node:fs/promises';
 import { dirname, join, relative } from 'node:path';
 
 import { templateRoot } from './paths.js';
@@ -113,6 +113,9 @@ const SAFE_SYNC_FILES = new Set([
   '.cowork-flow/.version'
 ]);
 
+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 +127,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 +185,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);
 

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
@@ -42,10 +50,11 @@ cat AGENTS.md
 ### Step 2: Get Current Context
 
 ```bash
-python3 ./.cowork-flow/scripts/get_context.py
+python3 ./.cowork-flow/scripts/resume.py
 ```
 
-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 +80,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.
@@ -114,24 +129,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)
@@ -339,7 +354,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 +364,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 `python3 ./.cowork-flow/scripts/resume.py`.
+2. Follow the `RESUME CHECKLIST` section.
+3. Read the current task `prd.md`.
+4. Run `python3 ./.cowork-flow/scripts/task.py 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,6 +395,7 @@ If yes, resume from the appropriate step (usually Step 7 or 8).
 
 | Script | Purpose |
 |--------|---------|
+| `python3 ./.cowork-flow/scripts/resume.py` | Resume session with minimal context checklist |
 | `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 |

package/template/.cowork-flow/.version

@@ -1 +1 @@
-0.0.2
+0.0.3

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"python3 ./{DIR_WORKFLOW}/{DIR_SCRIPTS}/resume.py"]
+    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"python3 ./{DIR_WORKFLOW}/{DIR_SCRIPTS}/task.py 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),
     }
 
 
@@ -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),
     }
 
 
@@ -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/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())

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

@@ -382,7 +382,10 @@ def _resolve_task_dir(target_dir: str, repo_root: Path) -> Path:
 def get_implement_base() -> list[dict]:
     """Get base implement context entries."""
     return [
+        {"file": "AGENTS.md", "reason": "Project collaboration rules and workflow gates"},
         {"file": f"{DIR_WORKFLOW}/workflow.md", "reason": "Project workflow and conventions"},
+        {"file": f"{DIR_WORKFLOW}/{DIR_SPEC}/guides/index.md", "reason": "Pre-implementation thinking guides"},
+        {"file": f"{DIR_WORKFLOW}/{DIR_SPEC}/guides/pre-implementation-checklist.md", "reason": "Mandatory pre-coding checklist"},
     ]
 
 
@@ -408,6 +411,7 @@ def get_check_context(dev_type: str, repo_root: Path) -> list[dict]:
     """Get check context entries."""
     entries = [
         {"file": _skill_path("finish-work"), "reason": "Finish work checklist"},
+        {"file": _skill_path("record-session"), "reason": "Session recording and state sync"},
     ]
 
     if dev_type in ("backend", "frontend", "fullstack"):
@@ -420,6 +424,7 @@ def get_debug_context(dev_type: str, repo_root: Path) -> list[dict]:
     """Get debug context entries."""
     entries: list[dict] = [
         {"file": _skill_path("break-loop"), "reason": "Deep bug analysis workflow"},
+        {"file": _skill_path("update-spec"), "reason": "Capture implementation lessons and contracts"},
     ]
 
     if dev_type in ("backend", "frontend", "fullstack"):
@@ -434,6 +439,53 @@ def _write_jsonl(path: Path, entries: list[dict]) -> None:
     path.write_text("\n".join(lines) + "\n", encoding="utf-8")
 
 
+def _read_text_if_present(path: Path) -> str:
+    """读取文本文件并返回去空白后的内容；不存在或读取失败时返回空字符串。"""
+    if not path.is_file():
+        return ""
+
+    try:
+        return path.read_text(encoding="utf-8").strip()
+    except (OSError, IOError):
+        return ""
+
+
+def _task_start_blockers(task_dir: Path) -> list[str]:
+    """返回启动任务前必须处理的准备阻塞项。"""
+    blockers: list[str] = []
+
+    task_json = task_dir / FILE_TASK_JSON
+    if not task_json.is_file():
+        blockers.append("task.json is missing")
+
+    prd_file = task_dir / "prd.md"
+    if not _read_text_if_present(prd_file):
+        blockers.append("prd.md is missing or empty")
+
+    for jsonl_name in CONTEXT_JSONL_FILES:
+        jsonl_file = task_dir / jsonl_name
+        if not _read_text_if_present(jsonl_file):
+            blockers.append(f"{jsonl_name} is missing or empty")
+
+    return blockers
+
+
+def _task_context_validation_issues(task_dir: Path, repo_root: Path) -> list[str]:
+    """返回任务上下文文件的校验问题。"""
+    issues: list[str] = []
+
+    for jsonl_name in CONTEXT_JSONL_FILES:
+        jsonl_file = task_dir / jsonl_name
+        if not _read_text_if_present(jsonl_file):
+            continue
+
+        error_count = _validate_jsonl(jsonl_file, repo_root)
+        if error_count > 0:
+            issues.append(f"{jsonl_name} has {error_count} validation error(s)")
+
+    return issues
+
+
 def _iter_jsonl_lines(path: Path):
     """Yield line number and content from a JSONL file."""
     with path.open("r", encoding="utf-8") as f:
@@ -856,6 +908,28 @@ def cmd_start(args: argparse.Namespace) -> int:
         print(f"Hint: Use task name (e.g., 'my-task') or full path (e.g., '{DIR_WORKFLOW}/tasks/01-31-my-task')")
         return 1
 
+    blockers = _task_start_blockers(full_path)
+    if blockers:
+        print(colored("Error: Task is not ready to start yet", Colors.RED), file=sys.stderr)
+        for blocker in blockers:
+            print(f"  - {blocker}", file=sys.stderr)
+        print(
+            "Hint: write prd.md, run python3 ./.cowork-flow/scripts/task.py init-context <dir> <dev_type>, then retry",
+            file=sys.stderr,
+        )
+        return 1
+
+    validation_issues = _task_context_validation_issues(full_path, repo_root)
+    if validation_issues:
+        print(colored("Error: Task context validation failed", Colors.RED), file=sys.stderr)
+        for issue in validation_issues:
+            print(f"  - {issue}", file=sys.stderr)
+        print(
+            "Hint: run python3 ./.cowork-flow/scripts/task.py validate <dir> and fix the reported issues",
+            file=sys.stderr,
+        )
+        return 1
+
     # Convert to relative path for storage
     try:
         task_dir = str(full_path.relative_to(repo_root))

package/template/.cowork-flow/spec/guides/pre-implementation-checklist.md

@@ -4,7 +4,7 @@
 
 - 这次改动属于 `L0`、`L1` 还是 `L2`？
 - 是否涉及 API、数据库、异步链路、权限或状态流转？
-- 是否需要先补 OpenSpec？
+- 是否需要先补 `cowork-flow change`？
 - 是否已经明确成功标准和验证方式？
 - 是否已经搜索过相似实现与可复用能力？
 

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

@@ -81,7 +81,7 @@ python3 ./.cowork-flow/scripts/init_developer.py <developer-name>
 每次开始工作先执行：
 
 ```bash
-python3 ./.cowork-flow/scripts/get_context.py
+python3 ./.cowork-flow/scripts/resume.py
 python3 ./.cowork-flow/scripts/task.py list
 git status
 git log --oneline -10
@@ -387,7 +387,29 @@ python3 ./.cowork-flow/scripts/change.py archive <slug>
 
 ---
 
-## 11. 禁止事项
+## 11. 恢复与上下文压缩
+
+多轮对话、长任务、中断恢复或上下文压缩后，必须先走最小恢复层，再按需读取细节。
+
+| 层级 | 读取内容 | 使用时机 |
+|------|----------|----------|
+| 最小恢复层 | `resume.py` 输出中的 `RESUME CHECKLIST` | 每次恢复、压缩后、重新接手任务 |
+| 任务执行层 | 当前任务 `prd.md`、当前 plan 状态、`task.py list-context <task-dir>` | 准备继续实现或检查前 |
+| 细节规范层 | jsonl 指向的具体 spec、代码模式或计划段落 | 当前修改确实需要该细节时 |
+
+恢复规则：
+
+- 先执行 `python3 ./.cowork-flow/scripts/resume.py`。
+- 按 `RESUME CHECKLIST` 读取当前 PRD、当前 plan 和 `list-context` 输出。
+- 不要全量重读 `.cowork-flow/spec/`、所有 plan、所有 task 或 workspace journal。
+- 如果 plan 有 `Current Execution Status`，先读该段以确定下一步。
+- 如果 jsonl 指向的规范过多，先根据当前阶段选择最小相关集合。
+
+恢复目标是重建“现在该做什么”和“当前门禁是否满足”，不是把全部历史重新塞进上下文。
+
+---
+
+## 12. 禁止事项
 
 - 不跳过上下文读取直接编码。
 - 不在未验证时声称完成。
@@ -398,7 +420,7 @@ python3 ./.cowork-flow/scripts/change.py archive <slug>
 
 ---
 
-## 12. 完成定义
+## 13. 完成定义
 
 一个任务只有在以下条件同时满足时，才算完成：
 

package/template/.superpowers/brainstorming/SKILL.md

@@ -26,7 +26,7 @@ You MUST create a task for each of these items and complete them in order:
 3. **Ask clarifying questions** — one at a time, understand purpose/constraints/success criteria
 4. **Propose 2-3 approaches** — with trade-offs and your recommendation
 5. **Present design** — in sections scaled to their complexity, get user approval after each section
-6. **Write design doc** — save to `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md` and commit
+6. **Write change artifacts** — save proposal/spec/design in `.cowork-flow/changes/<slug>/` and commit
 7. **Spec self-review** — quick inline check for placeholders, contradictions, ambiguity, scope (see below)
 8. **User reviews written spec** — ask user to review the spec file before proceeding
 9. **Transition to implementation** — invoke writing-plans skill to create implementation plan
@@ -108,7 +108,10 @@ digraph brainstorming {
 
 **Documentation:**
 
-- Write the validated design (spec) to `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md`
+- Write the validated change artifacts under `.cowork-flow/changes/<slug>/`
+  - `proposal.md` explains why the behavior should change
+  - `specs/.../spec.md` defines external behavior and acceptance criteria
+  - `design.md` records important design trade-offs for L2 work
   - (User preferences for spec location override this default)
 - Use elements-of-style:writing-clearly-and-concisely skill if available
 - Commit the design document to git

package/template/.superpowers/brainstorming/spec-document-reviewer-prompt.md

@@ -4,7 +4,7 @@ Use this template when dispatching a spec document reviewer subagent.
 
 **Purpose:** Verify the spec is complete, consistent, and ready for implementation planning.
 
-**Dispatch after:** Spec document is written to docs/superpowers/specs/
+**Dispatch after:** Spec or design document is written under `.cowork-flow/changes/<slug>/`
 
 ```
 Task tool (general-purpose):

package/template/.superpowers/requesting-code-review/SKILL.md

@@ -57,7 +57,7 @@ HEAD_SHA=$(git rev-parse HEAD)
 
 [Dispatch code reviewer subagent]
   DESCRIPTION: Added verifyIndex() and repairIndex() with 4 issue types
-  PLAN_OR_REQUIREMENTS: Task 2 from docs/superpowers/plans/deployment-plan.md
+  PLAN_OR_REQUIREMENTS: Task 2 from .cowork-flow/plans/deployment-plan.md
   BASE_SHA: a7981ec
   HEAD_SHA: 3df7661
 

package/template/.superpowers/subagent-driven-development/SKILL.md

@@ -130,7 +130,7 @@ Implementer subagents report one of four statuses. Handle each appropriately:
 ```
 You: I'm using Subagent-Driven Development to execute this plan.
 
-[Read plan file once: docs/superpowers/plans/feature-plan.md]
+[Read plan file once: .cowork-flow/plans/feature-plan.md]
 [Extract all 5 tasks with full text and context]
 [Create TodoWrite with all tasks]
 

package/template/.superpowers/writing-plans/SKILL.md

@@ -15,7 +15,7 @@ Assume they are a skilled developer, but know almost nothing about our toolset o
 
 **Context:** If working in an isolated worktree, it should have been created via the `superpowers:using-git-worktrees` skill at execution time.
 
-**Save plans to:** `docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md`
+**Save plans to:** `.cowork-flow/plans/YYYY-MM-DD-<feature-name>.md`
 - (User preferences for plan location override this default)
 
 ## Scope Check
@@ -135,7 +135,7 @@ If you find issues, fix them inline. No need to re-review — just fix and move
 
 After saving the plan, offer execution choice:
 
-**"Plan complete and saved to `docs/superpowers/plans/<filename>.md`. Two execution options:**
+**"Plan complete and saved to `.cowork-flow/plans/<filename>.md`. Two execution options:**
 
 **1. Subagent-Driven (recommended)** - I dispatch a fresh subagent per task, review between tasks, fast iteration
 

package/template/AGENTS.md

@@ -95,14 +95,22 @@
     - 如果跟丢上下文，先停下来重新整理。
 
 <!-- COWORK-FLOW:START -->
-# cowork-flow Instructions
+# cowork-flow 强门禁
 
-These instructions are for AI assistants working in this project.
+若与项目自定义说明冲突，以项目说明和用户明确指令为准。
+
+1. 每次新会话、重新接手任务、或上下文明显丢失时，先执行 `python3 ./.cowork-flow/scripts/resume.py`，再进入 `.agent/skills/start`。
+2. 执行 `start` 时，先读 `AGENTS.md`、`.cowork-flow/workflow.md` 和 `resume.py` 的输出，不要直接编码。
+3. 任何会修改仓库文件的请求，都必须先分级为 `L0` / `L1` / `L2`，再进入对应流程；不要把“很小”当成可以绕过流程的理由。
+4. `L1` / `L2` 行为变更必须先有 `change -> spec -> plan`；`L2` 还必须有 `design.md`，然后才能进入实现。
+5. 实现前必须把任务上下文写入 `.cowork-flow/tasks/<task>/implement.jsonl`、`check.jsonl`、`debug.jsonl`，并在 `start` 之后再改代码。
+6. 收尾前必须跑验证、同步 plan / task / change 状态，完成 `finish-work` 检查，再按项目策略记录 session。
+7. 多轮对话、长任务恢复或上下文压缩后，先运行 `python3 ./.cowork-flow/scripts/resume.py` 并查看 `RESUME CHECKLIST`；只读取清单列出的 PRD、当前 plan 和 jsonl 引用，不要全量重读 `.cowork-flow/spec/` 或历史 journal。
 
 Use the `.agent/skills/start` skill when starting a new session to:
 - Initialize your developer identity
 - Understand current project context
-- Read relevant guidelines
+- Enforce the task workflow gates before any implementation
 
 Use `@/.cowork-flow/` to learn:
 - Development workflow (`workflow.md`)