cowork-flow 0.0.7 → 0.0.9

package/package.json

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

package/template/.agent/skills/agent-team-execution/SKILL.md

@@ -12,15 +12,18 @@ Use this skill after a task is active and an approved `.cowork-flow/plans/*.md`
 1. Run `./.cowork-flow/run agent-team prepare <task-dir> --plan <plan-file>`.
 2. Review `agent-team/dispatch-plan.yaml` for unsafe parallelism, file conflicts, missing context, or weak agent matches.
 3. Run `./.cowork-flow/run agent-team next <task-dir>` to get ready assignments.
-4. In Codex, dispatch the ready assignments to the recommended agent types. Tell each worker it is not alone in the codebase, must respect the write boundary, must not revert others' edits, and must list changed files.
-5. While workers run, coordinate: answer questions, unblock context gaps, and integrate non-conflicting results.
-6. Record outputs with `record-result` and reviews with `record-review`.
-7. Use `retry` only after adding missing context, changing agent choice, or splitting an oversized assignment.
-8. Run `complete` before claiming the agent team work is done.
+4. In Codex with `[features] multi_agent = true`, dispatch each ready assignment with `spawn_agent` using the generated `agent-team/assignments/<assignment-id>.md` prompt content. Dispatch multiple ready assignments in parallel only after confirming their write files do not overlap.
+5. Collect each spawned worker result with `wait_agent`, then call `close_agent` to free the worker slot. Tell each worker it is not alone in the codebase, must respect the write boundary, must not revert others' edits, and must list changed files.
+6. Only fall back to manual prompt execution when the current host does not expose `spawn_agent`, `wait_agent`, or `close_agent`. Do not use manual execution merely because the assignment is stored as Markdown.
+7. While workers run, coordinate: answer questions, unblock context gaps, and integrate non-conflicting results.
+8. Record outputs with `record-result` and reviews with `record-review`.
+9. Use `retry` only after adding missing context, changing agent choice, or splitting an oversized assignment.
+10. Run `complete` before claiming the agent team work is done.
 
 ## Rules
 
 - The script suggests; the main agent decides.
 - Do not parallelize assignments with overlapping write files.
 - Do not skip spec review or quality review.
+- In Codex, `agent-team` is coordinator-dispatched: the Python script generates assignments, and the main agent performs the real `spawn_agent` / `wait_agent` / `close_agent` calls.
 - Do not rely on chat history for state; write results through `agent-team` commands.

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

@@ -1,66 +1,27 @@
 ---
 name: start
-description: Use when beginning a development session in a project that uses the cowork-flow template
+description: Use when starting or resuming work in a project that uses the cowork-flow template, after context compression, or before any request that may modify repository files. Initialize session context and route work into the L0/L1/L2 workflow.
 ---
 
 # Start Session
 
-Initialize your AI development session and begin working on tasks.
+Use this skill as the entrypoint for cowork-flow projects.
 
-<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>
+Any request that changes repository files MUST first be classified as `L0`, `L1`, or `L2`, then follow the matching workflow in `.cowork-flow/workflow.md`.
+Do not use direct-edit shortcuts unless the user explicitly tells you not to use cowork-flow for this task.
 
----
-
-## Operation Types
-
-| Marker | Meaning | Executor |
-|--------|---------|----------|
-| `[AI]` | Bash scripts or tool calls executed by AI | You (AI) |
-| `[USER]` | Skills executed by user | User |
-
----
+## Start
 
-## Initialization `[AI]`
-
-### Step 1: Understand Development Workflow
-
-First, read the workflow guide and the project-level collaboration rules:
+1. Read `AGENTS.md` and `.cowork-flow/workflow.md`.
+2. Run `./.cowork-flow/run resume`.
+3. If developer identity is missing, run:
 
 ```bash
-cat .cowork-flow/workflow.md
-cat AGENTS.md
+./.cowork-flow/run get-developer
+./.cowork-flow/run init-developer <developer-name>
 ```
 
-**Follow the instructions in `workflow.md` and `AGENTS.md`** - they contain:
-- Core principles (Read Before Write, Follow Standards, etc.)
-- File system structure
-- Development process
-- 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
-./.cowork-flow/run resume
-```
-
-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
+4. Read only the spec index files:
 
 ```bash
 for f in .cowork-flow/spec/frontend/index.md .cowork-flow/spec/backend/index.md .cowork-flow/spec/guides/index.md; do
@@ -68,361 +29,55 @@ for f in .cowork-flow/spec/frontend/index.md .cowork-flow/spec/backend/index.md
 done
 ```
 
-> **Important**: The index files are navigation — they list the actual guideline files (e.g., `error-handling.md`, `conventions.md`, `mock-strategies.md`).
-> At this step, just read the indexes to understand what's available.
-> When you start actual development, you MUST go back and read the specific guideline files relevant to your task, as listed in the index's Pre-Development Checklist.
-
-### Step 4: Report and Ask
-
-Report what you learned and ask: "What would you like to work on?"
+5. Report current context:
+   - current developer
+   - current task
+   - active tasks
+   - worktree state
+   - anything that may affect the next step
 
----
-
-## Task Classification
-
-When user describes a task, classify it:
-
-| Type | Criteria | 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
+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>`.
 
-> **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.
-> The overhead is minimal, but the benefit is significant.
+## Route The Request
 
-> **Subtask Decomposition**: If brainstorm reveals multiple independent work items,
-> consider creating subtasks using `--parent` flag or `add-subtask` command.
-> See the brainstorm skill's Step 8 for details.
+After context is loaded, choose exactly one path.
 
-### Behavior Change Gate
+### Question Only
 
-Before entering Task Workflow, classify the change as `L0` / `L1` / `L2` using `.cowork-flow/workflow.md`.
+Use this path when the user only wants explanation, analysis, or review, and no repository files need to change.
 
-- `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. `./.cowork-flow/run change create <slug>`
-  2. `superpowers:brainstorming` to create or complete `proposal/spec`
-  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.
+- Answer directly.
+- If the request turns into a file change, stop and reclassify it as `L0`, `L1`, or `L2`.
 
-Only return to the task workflow after the spec and plan gates are complete.
+### Repository Change
 
-Before Phase 2, always complete this task handoff:
-
-1. Create or update `.cowork-flow/plans/YYYY-MM-DD-<slug>.md` with the execution checklist
-2. Create or bind a task directory
-3. Ensure `prd.md` summarizes the approved `proposal/spec/design/plan`
-4. Add the approved change artifacts and plan into task context
-5. Treat the plan file as a living execution artifact: keep checkbox state and current execution status synced during implementation, not only at the end
-
-- If the task came from **Simple Task**, resume with **Path B Step 2 (Create Task Directory)** and **Step 3 (Write PRD)**, then do the task handoff above and continue to Phase 2.
-- If the task came from **Brainstorm**, reuse the brainstorm-created task directory and PRD, then do the same task handoff and continue with **Path A / Phase 2**.
-
----
+Use this path for any repository edit, including small docs, comments, tests, refactors, or behavior changes.
 
-## Question Only
+1. Classify the task using `.cowork-flow/workflow.md`:
+   - `L0`: no external behavior change
+   - `L1`: bounded behavior change
+   - `L2`: cross-layer or important behavior change
+2. Follow the matching workflow in `.cowork-flow/workflow.md`:
+   - `L0`: section 6
+   - `L1` / `L2`: section 7
+3. Before editing files, ensure task context exists under `.cowork-flow/tasks/<task>/`.
+4. Before handoff, follow workflow verification, state sync, and session recording requirements.
 
-For questions that do not modify repository files, work directly:
-
-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.
-
----
-
-## L0 / Simple Task
-
-For simple, well-defined tasks that modify files without external behavior change:
-
-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)
-   - Configure context (Step 6)
-   - Activate task (Step 7)
-   - Implement (Phase 3, Step 8)
-   - Check quality (Step 9)
-   - Complete (Step 10)
-
----
+Do not maintain a second implementation checklist in this skill.
 
-## Complex Task - Brainstorm First
+## Required Routing Rules
 
-For complex or vague tasks, **automatically start the brainstorm process** — do NOT skip directly to implementation.
-
-See `$brainstorm` for the full process. Summary:
-
-1. **Acknowledge and classify** - State your understanding
-2. **Create task directory** - Track evolving requirements in `prd.md`
-3. **Ask questions one at a time** - Update PRD after each answer
-4. **Propose approaches** - For architectural decisions
-5. **Confirm final requirements** - Get explicit approval
-6. **If behavior changes are involved, complete the Behavior Change Gate**
-7. **Proceed to Task Workflow** - Reuse the brainstorm-created task directory/PRD, complete the task handoff, then continue from Phase 2 with clear requirements and plan
-
----
-
-## Task Workflow (Development Tasks)
-
-**Why this workflow?**
-- Run a dedicated research pass before coding
-- Configure specs in jsonl context files
-- Implement using injected context
-- Verify with a separate check pass
-- Result: Code that follows project conventions automatically
-
-### Overview: Two Entry Points
-
-```
-From Brainstorm (Complex Task):
-  PRD confirmed → Research → Configure Context → Activate → Implement → Check → Complete
-
-From Simple Task:
-  Confirm → Create Task → Write PRD → Research → Configure Context → Activate → Implement → Check → Complete
-```
-
-**Key principle: Research happens AFTER requirements are clear (PRD exists).**
-
----
-
-### Phase 1: Establish Requirements
-
-#### Path A: From Brainstorm (skip to Phase 2)
-
-PRD and task directory already exist from brainstorm. Skip directly to Phase 2.
-
-#### Path B: From Simple Task
-
-**Step 1: Confirm Understanding** `[AI]`
-
-Quick confirm:
-- What is the goal?
-- What type of development? (frontend / backend / fullstack)
-- Any specific requirements or constraints?
-
-If unclear, ask clarifying questions.
-
-**Step 2: Create Task Directory** `[AI]`
-
-```bash
-TASK_DIR=$(./.cowork-flow/run task create "<title>" --slug <name>)
-```
-
-**Step 3: Write PRD** `[AI]`
-
-Create `prd.md` in the task directory with:
-
-```markdown
-# <Task Title>
-
-## Goal
-<What we're trying to achieve>
-
-## Requirements
-- <Requirement 1>
-- <Requirement 2>
-
-## Acceptance Criteria
-- [ ] <Criterion 1>
-- [ ] <Criterion 2>
-
-## Technical Notes
-<Any technical decisions or constraints>
-```
-
----
-
-### Phase 2: Prepare for Implementation (shared)
-
-> Both paths converge here. PRD and task directory must exist before proceeding.
-
-**Step 4: Code-Spec Depth Check** `[AI]`
-
-If the task touches infra or cross-layer contracts, do not start implementation until code-spec depth is defined.
-
-Trigger this requirement when the change includes any of:
-- New or changed command/API signatures
-- Database schema or migration changes
-- Infra integrations (storage, queue, cache, secrets, env contracts)
-- Cross-layer payload transformations
-
-Must-have before proceeding:
-- [ ] Target code-spec files to update are identified
-- [ ] Concrete contract is defined (signature, fields, env keys)
-- [ ] Validation and error matrix is defined
-- [ ] At least one Good/Base/Bad case is defined
-
-**Step 5: Research the Codebase** `[AI]`
-
-Based on the confirmed PRD, run a focused research pass and produce:
-
-1. Relevant spec files in `.cowork-flow/spec/`
-2. Existing code patterns to follow (2-3 examples)
-3. Files that will likely need modification
-
-Use this output format:
-
-```markdown
-## Relevant Specs
-- <path>: <why it's relevant>
-
-## Code Patterns Found
-- <pattern>: <example file path>
-
-## Files to Modify
-- <path>: <what change>
-```
-
-**Step 6: Configure Context** `[AI]`
-
-Initialize default context:
-
-```bash
-./.cowork-flow/run task init-context "$TASK_DIR" <type>
-# type: backend | frontend | fullstack
-```
-
-Add specs found in your research pass:
-
-```bash
-# For each relevant spec and code pattern:
-./.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
-./.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
-./.cowork-flow/run task start "$TASK_DIR"
-```
-
-This sets `.current-task` so hooks can inject context.
-
----
-
-### Phase 3: Execute (shared)
-
-**Step 8: Implement** `[AI]`
-
-Implement the task described in `prd.md`.
-
-- Follow all specs injected into implement context
-- Keep changes scoped to requirements
-- Run the project verification commands from `AGENTS.md` or `.cowork-flow/config.yaml` before finishing
-- If executing an approved plan with independent work, use `agent-team-execution`: run `agent-team prepare`, review the dispatch plan, use `agent-team next` for ready assignments, and finish with `agent-team complete`.
-
-**Step 9: Check Quality** `[AI]`
-
-Run a quality pass against check context:
-
-- Review all code changes against the specs
-- Fix issues directly
-- Ensure lint and typecheck pass
-
-**Step 10: Complete** `[AI]`
-
-1. Verify lint and typecheck pass
-2. Report what was implemented
-3. Follow the current session convention for completion:
-   - Test the changes
-   - Have the agreed executor handle business-code changes according to project policy
-   - Run `$record-session` to record this session
-
----
-
-## Continuing Existing 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
-3. Ask user: "Continue working on <task-name>?"
-
-If yes, resume from the appropriate step (usually Step 7 or 8).
-
----
+- If the task is vague, complex, or has multiple possible interpretations, use the project brainstorming flow before implementation.
+- If the task changes behavior, do not skip `change -> spec -> plan`; for `L2`, do not skip `design.md`.
+- If an approved plan has independent work and `.cowork-flow/config.yaml` enables agent teams, use `agent-team-execution` and finish that path with `agent-team complete`.
+- If context was compressed or the task is being resumed, use the minimal recovery path below instead of bulk-reading the repo.
 
 ## 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:
+When resuming after a long task, a new session, or context compression:
 
 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]`
-
-| Skill | When to Use |
-|---------|-------------|
-| `$start` | Begin a session (this skill) |
-| `$finish-work` | Final verification before handoff or commit |
-| `$record-session` | After task completion and project commit/handoff policy is satisfied |
-
-### AI Scripts `[AI]`
-
-| Script | Purpose |
-|--------|---------|
-| `./.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]`
-
-| Phase | Purpose | Context Source |
-|-------|---------|----------------|
-| research | Analyze codebase | direct repo inspection |
-| implement | Write code | `implement.jsonl` |
-| check | Review & fix | `check.jsonl` |
-| debug | Fix specific issues | `debug.jsonl` |
-
----
-
-## Key Principle
+2. Follow `RESUME CHECKLIST` from `resume.py`.
+3. Read only the current PRD, current plan status, and the jsonl references needed for the current phase.
+4. Do not bulk-read `.cowork-flow/spec/`, all plans, all tasks, or workspace journals.
 
-> **Code-spec context is injected, not remembered.**
->
-> The Task Workflow ensures agents receive relevant code-spec context automatically.
-> This is more reliable than hoping the AI "remembers" conventions.

package/template/.cowork-flow/.version

@@ -1 +1 @@
-0.0.7
+0.0.9

package/template/.cowork-flow/agent-team/agents.yaml

@@ -13,10 +13,6 @@ agents:
       - code
       - test
     file_patterns:
-      - "src/**"
-      - "template/**"
-      - "tests/**"
-      - "test/**"
     risk_limits:
       max_parallel_write_conflicts: 0
     prompt: |
@@ -32,10 +28,6 @@ agents:
       - test
       - verification
     file_patterns:
-      - "tests/**"
-      - "test/**"
-      - "src/**"
-      - "template/**"
     risk_limits:
       max_parallel_write_conflicts: 0
     prompt: |
@@ -52,10 +44,6 @@ agents:
       - bugfix
       - code
     file_patterns:
-      - "src/**"
-      - "template/**"
-      - "tests/**"
-      - "test/**"
     risk_limits:
       max_parallel_write_conflicts: 0
     prompt: |
@@ -71,10 +59,6 @@ agents:
       - review
       - documentation
     file_patterns:
-      - ".cowork-flow/changes/**"
-      - ".cowork-flow/plans/**"
-      - "README.md"
-      - "template/**"
     risk_limits:
       max_parallel_write_conflicts: 0
     prompt: |
@@ -91,10 +75,6 @@ agents:
       - review
       - verification
     file_patterns:
-      - "src/**"
-      - "template/**"
-      - "tests/**"
-      - "test/**"
     risk_limits:
       max_parallel_write_conflicts: 0
     prompt: |
@@ -110,10 +90,6 @@ agents:
       - docs
       - documentation
     file_patterns:
-      - "README.md"
-      - "AGENTS.md"
-      - ".cowork-flow/**/*.md"
-      - ".agent/skills/**"
     risk_limits:
       max_parallel_write_conflicts: 0
     prompt: |
@@ -130,11 +106,6 @@ agents:
       - release
       - review
     file_patterns:
-      - "package.json"
-      - "package-lock.json"
-      - "scripts/**"
-      - "README.md"
-      - ".cowork-flow/changes/**"
     risk_limits:
       max_parallel_write_conflicts: 0
     prompt: |

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

@@ -7,7 +7,7 @@ import re
 from pathlib import Path
 
 
-TASK_RE = re.compile(r"^### Task\s+(\d+):\s*(.+?)\s*$")
+TASK_RE = re.compile(r"^#{2,3} Task\s+(\d+):\s*(.+?)\s*$")
 FILE_RE = re.compile(r"^-\s+(Create|Modify|Test):\s+`([^`]+)`")
 DEP_RE = re.compile(r"depends on Task\s+(\d+)", re.IGNORECASE)
 

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

@@ -5,22 +5,27 @@
 开发过程必须形成稳定闭环：
 
 ```text
-获取上下文 -> 阅读规范 -> 任务分级 -> 规格与计划 -> 执行实现 -> 验证审阅 -> 状态同步 -> session 记录
+获取上下文 -> 阅读规范 -> 任务分级 -> 目标/规格/计划 -> 执行实现 -> 验证审阅 -> 状态同步 -> session 记录
 ```
 
-所有任务先明确目标和验收标准，再进入实现；所有完成结论都必须有验证证据。命令示例默认使用 macOS / Linux / Git Bash / WSL；Windows cmd / PowerShell 使用 `.\.cowork-flow\run.cmd <command>` 替代 `./.cowork-flow/run <command>`。
+所有任务先明确目标和验收标准，再进入实现；所有完成结论都必须有验证证据。
+
+命令示例默认使用 macOS / Linux / Git Bash / WSL；Windows cmd / PowerShell 使用 `.\.cowork-flow\run.cmd <command>` 替代 `./.cowork-flow/run <command>`。
 
 ---
 
 ## 2. 职责边界
 
-| 对象 | 负责内容 |
-|------|----------|
-| `cowork-flow change` | 行为变更治理：`proposal` 说明为什么改，`spec` 定义外部行为与验收标准，`design` 记录复杂或跨层设计取舍，`change.yaml` 保存状态/分级/关联 plan 与 task，`archive` 归档完成后的行为规格。 |
-| `superpowers` | 工作方法：`brainstorming` 澄清需求和方案，`writing-plans` 拆可执行计划，`test-driven-development` 约束实现，`executing-plans` 顺序执行，`subagent-driven-development` 并行拆分，`verification-before-completion` 完成前取证。 |
-| `.cowork-flow` | 任务状态和上下文：当前开发者、当前任务、PRD、`implement/check/debug` 上下文、journal、session 记录和任务归档。 |
+cowork-flow 只负责保存流程状态和任务上下文；具体执行方法由当前 agent 宿主提供。
+
+| 对象 | 定位 | 主要产物 |
+|------|------|----------|
+| `cowork-flow change` | 行为变更规格 | `proposal.md`、`spec.md`、`design.md`、`change.yaml` |
+| `.cowork-flow/tasks` | 任务执行上下文 | `prd.md`、`implement.jsonl`、`check.jsonl`、`debug.jsonl` |
+| `.cowork-flow/plans` | 实施计划 | 可执行步骤、验证方式、当前执行状态 |
+| `agent 执行方法` | 需求澄清、计划拆分、TDD、subagent 调度、完成前验证 | 由宿主能力或可用技能提供 |
 
-`.cowork-flow` 不替代 superpowers，也不替代项目验证命令。除一次性原型、生成代码、纯配置文件等明确例外并经人工确认外，功能新增、缺陷修复、重构和行为变更都必须按 RED-GREEN-REFACTOR 推进；复杂或难点问题按深度优先。
+`.cowork-flow` 不替代 agent 的执行判断，也不替代项目验证命令。
 
 ---
 
@@ -54,6 +59,11 @@
 
 ```bash
 ./.cowork-flow/run resume
+```
+
+如 `resume` 输出不足以判断当前状态，再补充执行：
+
+```bash
 ./.cowork-flow/run task list
 git status
 git log --oneline -10
@@ -80,11 +90,23 @@ done
 
 所有任务先分级，再选择流程。
 
-| 等级 | 适用场景 | 流程 |
-|------|----------|------|
-| L0：无外部行为变化 | 文档整理、小范围重构、测试补充、注释/格式/脚本清理、不改变用户可观察行为的内部调整 | 任务 -> 读取规范 -> 简短计划 -> 实现 -> 验证 -> 记录 session |
-| L1：局部行为变化 | 单模块功能调整、单接口行为变化、局部数据处理逻辑变化、有明确边界的新能力 | cowork-flow change -> brainstorming -> writing-plans -> 任务上下文 -> 执行计划 -> 验证 -> 归档与记录 |
-| L2：跨层或重要行为变化 | 跨前后端或跨服务变更；API / DB / 消息 / 缓存 / 文件等契约变化；架构边界变化；影响发布、迁移、安全、权限或兼容性的变更 | cowork-flow change -> brainstorming -> design.md -> writing-plans -> 任务上下文 -> 执行计划 -> 多视角审阅 -> 验证 -> 归档与记录 |
+### L0：无外部行为变化
+
+适用：文档整理、小范围重构、测试补充、注释/格式/脚本清理、不改变用户可观察行为的内部调整。
+
+流程：任务 -> 读取规范 -> 简短计划 -> 实现 -> 验证 -> 记录 session。
+
+### L1：局部行为变化
+
+适用：单模块功能调整、单接口行为变化、局部数据处理逻辑变化、有明确边界的新能力。
+
+流程：cowork-flow change -> brainstorming -> writing-plans -> 任务上下文 -> 执行计划 -> 验证 -> 归档与记录。
+
+### L2：跨层或重要行为变化
+
+适用：跨前后端或跨服务变更；API / DB / 消息 / 缓存 / 文件等契约变化；架构边界变化；影响发布、迁移、安全、权限或兼容性的变更。
+
+流程：cowork-flow change -> brainstorming -> design.md -> writing-plans -> 任务上下文 -> 执行计划 -> 多视角审阅 -> 验证 -> 归档与记录。
 
 ---
 
@@ -130,7 +152,8 @@ done
 - 遵循 `.cowork-flow/spec/` 中的相关规范。
 - 变更保持聚焦。
 - 若执行中发现行为变化升级，立即重新分级并进入 L1 / L2 流程。
-- 执行计划中的每个实现步骤必须优先进入 `superpowers:test-driven-development` 循环，不得先写生产代码再补测试。
+- 涉及代码逻辑或行为时，必须优先进入 `superpowers:test-driven-development` 循环，不得先写生产代码再补测试。
+- 纯文档、格式或说明性修改按 PRD 验收标准验证，不强行补无意义测试。
 
 ---
 
@@ -177,35 +200,39 @@ done
 
 将 proposal、spec、design（如存在）、implementation plan、相关 `.cowork-flow/spec/`、相关代码模式或契约文件加入任务上下文。
 
-### 7.7 按 superpowers 方法执行
+### 7.7 执行
+
+执行 plan 前，先判断**是否存在适合拆分的独立任务**。
 
-执行 plan 前，先判断**是否存在适合并行执行的独立任务**。并行是优化手段，不是完成定义；`agent_team.enabled` 只决定在适合并行时优先使用哪种机制，不决定是否必须并行。
+只要宿主支持 subAgent，且任务适合拆分，就应优先采用 subagent 执行。`agent_team.enabled` 只决定是否使用 cowork-flow 内置 agent-team 调度，不决定是否可以使用 subagent。
 
-适合并行的条件包括：
+并行是优化手段，不是完成定义；不得为了满足流程形式而强行拆分高耦合任务。
+
+适合使用 subagent 的条件包括：
 
 - 子任务之间没有共享写文件，或共享写文件已有明确顺序边界。
 - 子任务之间没有强顺序依赖。
 - 每个子任务都有清晰输入、输出和验收方式。
 - 主 agent 能在集成前独立审查每个结果。
-- 并行带来的收益大于调度、审阅和集成成本。
+- subagent 带来的收益大于调度、审阅和集成成本。
 
-不适合并行的情况包括：
+不适合使用 subagent 的情况包括：
 
 - 改动集中在同一组强耦合文件。
 - 需要密集的 TDD 红绿循环或即时反馈。
 - parser、schema、runtime、测试需要同步演进。
 - 子任务边界不清，拆分后的主要成本会落在集成。
-- 任务规模小于并行调度成本。
+- 任务规模小于 subagent 调度成本。
 
-不得为了满足流程形式而强行拆分高耦合任务。若不适合并行，必须简要记录不使用并行的理由，并在当前会话中按 plan 顺序执行。
+若不适合使用 subagent，必须简要记录理由，并在当前会话中按 plan 顺序执行。
 
-若适合并行：
+若适合使用 subagent：
 
-- 当 `.cowork-flow/config.yaml` 中设置 `agent_team.enabled: true` 时，使用 `./.cowork-flow/run agent-team prepare <task-dir> --plan <plan-file>` 生成调度图，再用 `./.cowork-flow/run agent-team next <task-dir>` 获取可并行 assignments，由主 agent 审核并调度 subAgent。
-- 当 `.cowork-flow/config.yaml` 中设置 `agent_team.enabled: false` 且宿主支持 subAgent 时，可使用 `superpowers:subagent-driven-development` 开启多 agent 并行执行。
-- 当宿主不支持 subAgent 或任务不适合并行时，使用 `superpowers:executing-plans` 或当前会话顺序执行。
+- 当 `.cowork-flow/config.yaml` 中设置 `agent_team.enabled: true` 时，优先使用 `./.cowork-flow/run agent-team prepare <task-dir> --plan <plan-file>` 生成调度图，再用 `./.cowork-flow/run agent-team next <task-dir>` 获取 assignments，由主 agent 审核并调度 subAgent。
+- 当 `agent_team.enabled: false` 但宿主支持 subAgent 时，使用 `superpowers:subagent-driven-development` 或宿主等价机制开启多 agent 执行。
+- 当宿主不支持 subAgent 或任务不适合拆分时，使用 `superpowers:executing-plans` 或当前会话顺序执行。
 
-无论是否并行，都必须严格遵循 `superpowers:test-driven-development`，不得先写生产代码再补测试。
+无论是否使用 subagent，都必须严格遵循 `superpowers:test-driven-development`，不得先写生产代码再补测试。
 
 执行中必须持续同步：
 
@@ -236,7 +263,7 @@ done
 完成前至少确认：
 
 - 相关测试通过
-- 新增或修改的行为有测试先失败、再通过的验证证据
+- 新增或修改的代码行为有测试先失败、再通过的验证证据
 - lint / format / build / typecheck 按项目要求通过
 - 行为符合 cowork-flow change 规格或 PRD
 - 相关 `.cowork-flow/spec/` 已同步
@@ -279,6 +306,13 @@ L2 任务完成前需要多视角审阅：行为契约、数据流、错误处
 ./.cowork-flow/run change archive <slug>
 ```
 
+在windows下遇到归档异常,尝试使用下面脚本修复：
+
+```bash
+$user = "$env:USERDOMAIN\$env:USERNAME"
+icacls .\.cowork-flow /grant "$($user):(OI)(CI)(F)" /T
+```
+
 ---
 
 ## 10. 状态持久化与恢复
@@ -337,6 +371,6 @@ L2 任务完成前需要多视角审阅：行为契约、数据流、错误处
 - cowork-flow change 规格或计划中的必要步骤已完成
 - 验证命令已按项目要求执行
 - 失败、跳过或无法执行的验证已明确说明
-- 相关规范已更新
+- 必要的相关规范已更新，或已说明无需更新
 - change metadata、计划状态、任务状态不冲突
 - session 已记录

package/template/AGENTS.md

@@ -95,20 +95,6 @@
     - 如果跟丢上下文，先停下来重新整理。
 
 <!-- COWORK-FLOW:START -->
-# cowork-flow 强门禁
-
-若与项目自定义说明冲突，以项目说明和用户明确指令为准。
-
-命令示例默认使用 macOS / Linux / Git Bash / WSL 写法；Windows cmd / PowerShell 中使用 `.\.cowork-flow\run.cmd <command>` 替代 `./.cowork-flow/run <command>`。
-
-1. 每次新会话、重新接手任务、或上下文明显丢失时，先执行 `./.cowork-flow/run resume`，再进入 `.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 时，如存在可独立并行任务，且 `.cowork-flow/config.yaml` 中已设置 `agent_team.enabled: true`，可使用 `./.cowork-flow/run agent-team prepare <task-dir> --plan <plan-file>` 与 `agent-team next` 生成并执行 agent-team 调度；主 agent 仍负责协调、审阅和状态回写。
-7. 收尾前必须跑验证、同步 plan / task / change 状态，完成 `finish-work` 检查，再按项目策略记录 session。
-8. 多轮对话、长任务恢复或上下文压缩后，先运行 `./.cowork-flow/run resume` 并查看 `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