Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .Knowledge/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@
| f2s-doc-routing | `.Knowledge/topics/f2s-stock-docs-vs-req-docs.md` | stock-docs / req-docs 目录分工 | stock:[目录边界说明](.Knowledge/stock-docs/<目录边界说明>.md)(可选) |
| fallback-triage | `.Knowledge/topics/f2s-fallback-triage.md` | 未命中或低置信度:分诊与澄清 | stock:[路由分诊说明](.Knowledge/stock-docs/<分诊说明>.md)(可选) |
| config-precheck | `.Knowledge/topics/f2s-config-precheck.md` | 执行 `f2s-*` 前读 `flow2spec.config.json` / 编排开关(含 `intentRecognition` 意图识别)/ 更新检测 | Codex 长文:仓库根 `.codex/topics/f2s-config-check.md`;Claude/Cursor/Codex hooks:[路由摘要](topics/f2s-config-precheck.md) |
| f2s-task | `.Knowledge/topics/f2s-task.md` | 变更追踪、`.task/` 任务清单与跨会话续作 | stock:[任务清单与变更追踪](stock-docs/Flow2Spec-任务清单与变更追踪.md);长文:`rules/f2s-task.*` |
| f2s-task | `.Knowledge/topics/f2s-task.md` | 变更追踪、`.task/` 任务清单与跨会话/跨电脑续作 | stock:[任务清单与变更追踪](stock-docs/Flow2Spec-任务清单与变更追踪.md);长文:`rules/f2s-task.*` |
| f2s-req-plan | `.Knowledge/topics/f2s-req-plan.md` | 需求/方案规划与实现;始终维护 `.task/` | 技能:`skills/f2s-req-plan/SKILL.md`;依赖 `f2s-task` |
| f2s-git-commit | `.Knowledge/topics/f2s-git-commit.md` | 提交代码;默认检查知识库覆盖,快捷提交跳过覆盖检查 | 技能:`skills/f2s-git-commit/SKILL.md`;模板:[f2s-git-commit](../templates/skills/f2s-git-commit/SKILL.md) |
| flow2spec-presentations | `.Knowledge/topics/f2s-flow2spec-presentations.md` | 本仓 Astro 宣传网站、文档导航与遗留 HTML 演示稿维护约定 | stock:[对外网站与演示](stock-docs/Flow2Spec-对外介绍演示.md) |
Expand Down
2 changes: 1 addition & 1 deletion .Knowledge/manifest-routing.json
Original file line number Diff line number Diff line change
Expand Up @@ -173,7 +173,7 @@
"topics": [
"flow2spec-collaboration"
],
"summary": "任务状态本地隔离、共享知识 delta 合入与 revision 冲突处理"
"summary": "任务按身份隔离与跨电脑续作、知识 delta 合入及 revision 冲突处理"
},
{
"task": "flow2spec-doctor",
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -48,6 +48,10 @@
- **归档**:完成后将 `active/<task-name>/` 整体移至 `completed/<YYYYMMDD>-<task-name>/`,并从 `todo.json` 删除对应条目;若数组为空可删除 `todo.json`。
- **子任务与 Git worktree**:`subAgent=true` 或并行子任务若使用 **`git worktree`**(或 IDE 等价隔离目录),须在子任务结束或主 agent 合并后 **`git worktree remove`** 并 `git worktree list` 自检,禁止长期遗留孤儿 worktree;细则见配置根 **`rules/f2s-flow2spec-unified-entry.*`**。

### Git 与跨电脑续作

`.gitignore` 使用 `.task/completed/` 与 `.task/*/completed/`,仅忽略两种布局的已完成归档。进行中的 `active/`、`todo.json` 与任务上下文可随代码提交、推送,在另一台电脑拉取后续作;两端应保持相同 `collaboration.developerId`(或相同的 Git 身份解析结果)。`init` 会将旧的整目录 `.task/` 忽略规则迁为上述两条规则。

### 3.1 `user-todos.md` 与 `acceptance.md`:用户侧两份文件,职责分离

| 文件 | 谁在做 | 内容焦点 | 写入时机 |
Expand Down
8 changes: 7 additions & 1 deletion .Knowledge/topics/f2s-task.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
id: f2s-task
revision: 0
revision: 1
summary: "任务清单 .task 目录的创建、续作与归档规则"
primary: policy
confidence: manual
Expand Down Expand Up @@ -49,6 +49,12 @@ TASK_ROOT/ ← `.task` 或 `.task/<developerId>`

用户代办**必须**落在与 `task.md` 同目录的 **`user-todos.md`**;归档前**必须**生成与 `task.md` 同目录的 **`acceptance.md`**(验收清单),二者职责分离。细则见配置根 **`rules/f2s-task.*`**。

## Git 与跨电脑续作

- `.gitignore` 使用 `.task/completed/` 与 `.task/*/completed/`,忽略单人及多人布局的已完成归档。
- `active/`、`todo.json` 与任务上下文可提交并推送;另一台电脑拉取后,使用相同 developerId 解析到原 TASK_ROOT 续作。
- `init` 自动将旧的整目录 `.task/` 忽略规则迁为上述两条规则。

## 跨会话续作

新会话先解析 `TASK_ROOT`;若存在该根下 `todo.json`,将用户首条消息与**仅该文件**内 `keywords` 匹配:
Expand Down
10 changes: 6 additions & 4 deletions .Knowledge/topics/flow2spec-collaboration.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
id: flow2spec-collaboration
revision: 0
summary: "任务状态本地隔离、共享知识 delta 合入与 revision 冲突处理"
revision: 2
summary: "任务按身份隔离与跨电脑续作、知识 delta 合入及 revision 冲突处理"
dependsOn: [f2s-task]
primary: feature
confidence: manual
Expand All @@ -11,11 +11,13 @@ tags: [policy]

## 适用场景

执行前须先读依赖主题 `f2s-task`。

用于回答 Flow2Spec 多人共用知识库、developerId 任务隔离、kb-delta 合入、topic revision 冲突与团队进度可见性。

## 协作边界

- `.task/<developerId>/` 保存个人 checklist、会话上下文与用户代办,默认不进 Git;Agent 只读写当前 `TASK_ROOT`。
- `.task/<developerId>/` 保存个人 checklist、会话上下文与用户代办;进行中任务可随代码提交,completed 归档由 `.task/completed/` 与 `.task/*/completed/` 忽略;Agent 只读写当前 `TASK_ROOT`。
- `.Knowledge/` 保存团队共享事实,随代码通过 Git / PR 评审。
- `collaboration.enabled` 只控制任务根是否按 developerId 分层,不关闭知识库协作。

Expand All @@ -28,7 +30,7 @@ tags: [policy]

## 团队观察面

团队进度以 PR、commit、`.Knowledge/` diff、`req-docs/` 与项目里程碑为准。`.task/` 是本地过程状态,不作为团队看板。
团队进度以 PR、commit、`.Knowledge/` diff、`req-docs/` 与项目里程碑为准。`.task/` 保存个人过程状态,可通过 Git 同步进行中任务以跨电脑续作;两端保持相同 developerId。

## 下钻入口

Expand Down
3 changes: 2 additions & 1 deletion .gitignore
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
.agents/
.task/
.task/completed/
.task/*/completed/
.DS_Store
docs/*.json
.Knowledge/update-check.json
Expand Down
2 changes: 1 addition & 1 deletion docs/en/commands-reference.md
Original file line number Diff line number Diff line change
Expand Up @@ -703,7 +703,7 @@ It checks:
- whether `flow2spec.config.json`, root `AGENTS.md`, and `.Knowledge/manifest-routing.json` exist and are usable
- whether detected `.codex`, `.claude`, and `.cursor` roots contain their required entry and hook files
- the resolved `developerId`, source, and `TASK_ROOT`; falling back to the legacy `.task/` root produces a warning
- whether the root `.gitignore` ignores `.task/`
- whether the root `.gitignore` ignores `.task/completed/` and `.task/*/completed/` while allowing active tasks to be committed
- strict knowledge graph health, topic revisions, and routing metadata drift

Human-readable output marks each check with `[PASS]`, `[WARN]`, or `[FAIL]` and includes a repair suggestion when applicable. `--json` returns a stable `ok / package / cwd / summary / checks` structure for CI and scripts.
Expand Down
20 changes: 10 additions & 10 deletions docs/en/team-collaboration.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,9 @@

# Team Collaboration

Flow2Spec does not put every piece of runtime state into Git. It separates two kinds of information: what one developer is currently doing stays local; knowledge that can affect team decisions enters the repository.
Flow2Spec isolates task state by developer. Active tasks can travel with the code through Git for continuation on another computer, while confirmed team knowledge lives in `.Knowledge/`.

- `.task/` is personal working state and is ignored by Git by default.
- `.task/` holds personal working state. Active tasks and `todo.json` can be committed; completed archives are ignored.
- `.Knowledge/` is team knowledge and is reviewed, committed, and pulled with the code.

`developerId`, `kb-delta.json`, and topic revisions make this boundary executable.
Expand All @@ -15,7 +15,7 @@ Flow2Spec does not put every piece of runtime state into Git. It separates two k

| Content | Typical path | Visibility | Collaboration model |
| --- | --- | --- | --- |
| Personal task state | `.task/<developerId>/` | Current developer and local Agent | Resume locally; do not commit |
| Personal task state | `.task/<developerId>/` | Members who pull the relevant commits | Resume by developerId; archive completed tasks locally |
| Project knowledge | `.Knowledge/` | Everyone who pulls the repository | Delta merge and Git review |
| Implementation and formal docs | Source code and `docs/` | Everyone who pulls the repository | Branches, PRs, and commits |

Expand Down Expand Up @@ -126,7 +126,7 @@ skill forms a knowledge change
-> task is archived locally after its gates pass
```

`plan` does not write files. `apply` plans again immediately before writing, so a stale preview cannot force an outdated change onto disk. The delta remains local with the task; the `.Knowledge/` diff is the shared result.
`plan` does not write files. `apply` plans again immediately before writing, so a stale preview cannot force an outdated change onto disk. The delta stays with the task and can be committed for continuation; the `.Knowledge/` diff holds the confirmed result.

---

Expand All @@ -150,7 +150,7 @@ flow2spec kb build
flow2spec kb check --strict
```

After apply, inspect the real `.Knowledge/` diff and commit it with the implementation. `.task/` should not appear among staged files.
After apply, inspect the real `.Knowledge/` diff and commit it with the implementation. Include active tasks and `todo.json` when continuation on another computer is needed.

---

Expand Down Expand Up @@ -182,7 +182,7 @@ Step 4 cannot be replaced by concatenating text. The conflict exists to force a
- Give each developer a stable, readable `collaboration.developerId`, especially on shared machines.
- Pull before starting; keep a knowledge change and its implementation in the same PR or in traceable commits.
- Keep topics focused. Oversized topics enlarge both the routing surface and the revision conflict surface.
- Do not add `.task/` back to Git or use `todo.json` as a team board.
- Ignore `.task/completed/` and `.task/*/completed/`; active tasks can be committed, while `todo.json` remains a personal continuation index.
- Prefer delta-producing `f2s-kb-*` workflows for topic changes. Direct edits bypass revision preflight.
- Review the `.Knowledge/` diff before merging. “Mergeable” means structurally safe, not necessarily correct business wording.
- Keep the team on one Flow2Spec version so CLI schemas and templates agree.
Expand All @@ -191,27 +191,27 @@ Step 4 cannot be replaced by concatenating text. The conflict exists to force a

## 7. How managers see progress

Managers cannot see another developer's active `.task/` checklist, by design. Team progress should come from durable commitments and outputs:
Committed active checklists provide task context. Formal team progress should come from durable commitments and outputs:

- PRs or draft PRs for current delivery and blockers;
- commits and `.Knowledge/` diffs for actual capability or rule changes;
- `.Knowledge/req-docs/` for approved work waiting for implementation;
- milestones for results spanning multiple commits;
- the team's issue tracker, board, or status reports for owners and deadlines.

If the team needs shared work-in-progress state, integrate the existing issue tracker instead of synchronizing `.task/active/`, which may contain session context, tentative judgments, and user todos with a different lifecycle.
Use `.task/active/` for resumable working state and the existing issue tracker for owners, deadlines, and blockers. Completed archives stay local. Archiving a previously committed active task produces deletions that should travel with the next commit.

---

## 8. Common questions

### If `.task/` is local, why keep developerId?
### If `.task/` can travel through Git, why keep developerId?

Shared workspaces, build machines, and devcontainers can host multiple identities. More importantly, `TASK_ROOT` gives the Agent an enforceable boundary for task continuation.

### Does switching computers restore active tasks?

No. `.task/` is local. Put confirmed handoff information in a PR, requirement document, or `.Knowledge/`.
Commit and push the active task and `todo.json`, then pull them on the other computer. Keep the same `collaboration.developerId` or Git identity resolution so the Agent resumes from the same `TASK_ROOT`.

### Does `collaboration.enabled: false` disable knowledge collaboration?

Expand Down
2 changes: 1 addition & 1 deletion docs/命令说明.md
Original file line number Diff line number Diff line change
Expand Up @@ -821,7 +821,7 @@ flow2spec doctor --json
- `flow2spec.config.json`、根 `AGENTS.md` 与 `.Knowledge/manifest-routing.json` 是否存在且可用
- 已存在的 `.codex`、`.claude`、`.cursor` 配置根是否包含必要入口和 hooks
- 实际解析出的 `developerId`、来源与 `TASK_ROOT`;无法识别身份而回退到 `.task/` 时给出警告
- 根 `.gitignore` 是否忽略 `.task/`
- 根 `.gitignore` 是否仅忽略 `.task/completed/` 与 `.task/*/completed/`,保留进行中任务可提交
- 知识图、topic revision 和 routing 元数据是否通过严格校验

文本输出用 `[PASS]`、`[WARN]`、`[FAIL]` 标记每项,并在异常项后给出修复建议。`--json` 输出稳定的 `ok / package / cwd / summary / checks` 结构,便于 CI 或脚本消费。
Expand Down
24 changes: 12 additions & 12 deletions docs/团队协作.md
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
# 团队协作

Flow2Spec 的团队协作不是把所有运行状态都塞进 Git。它先把内容分成两类:个人正在做什么,留在本地;已经足以影响团队判断的知识,进入仓库。
Flow2Spec 按开发者隔离个人任务现场;进行中的任务可随代码通过 Git 同步,便于换电脑续作。团队确认的知识统一保存在 `.Knowledge/`。

对应到目录就是一句话:

- `.task/` 是个人过程,默认不进 Git;
- `.task/` 保存个人过程;`active/` 与 `todo.json` 可提交,completed 归档默认忽略;
- `.Knowledge/` 是团队知识,和代码一起评审、提交、拉取。

这条边界比具体命令更重要。边界立住以后,`developerId`、`kb-delta.json` 和 topic revision 都只是让它可执行的机制。
Expand All @@ -15,11 +15,11 @@ Flow2Spec 的团队协作不是把所有运行状态都塞进 Git。它先把内

| 内容 | 典型路径 | 谁能看到 | 怎么协作 |
| --- | --- | --- | --- |
| 个人任务现场 | `.task/<developerId>/` | 当前开发者和本机 Agent | 本地续作,不提交 |
| 个人任务现场 | `.task/<developerId>/` | 拉取了相关提交的成员 | 按 developerId 续作,completed 本地归档 |
| 项目知识 | `.Knowledge/` | 拉取了仓库的所有成员 | delta 合入、Git 评审 |
| 实现与正式文档 | 业务代码、`docs/` | 拉取了仓库的所有成员 | 常规分支、PR、commit |

`.task/` 里可以有尚未验证的判断、执行到一半的 checklist、需要用户处理的代办。它们对当前会话有用,却不等于团队事实。把这类文件推给所有人,得到的通常不是透明度,而是一批没人敢删、也没人知道是否过期的运行残留。
`.task/` 里可以有尚未验证的判断、执行到一半的 checklist、需要用户处理的代办。它们对当前会话有用,却不等于团队事实。进行中任务通过 Git 同步后,Agent 仍只读写当前 `TASK_ROOT`;已完成任务按归档规则收尾。

`.Knowledge/` 正好相反。Agent 会用它判断业务规则、实现边界和读取路径,因此团队成员必须看到同一个版本。知识可以暂时不完整,但不能按开发者各存一份。

Expand Down Expand Up @@ -166,7 +166,7 @@ git pull
flow2spec kb status
```

`kb status` 检查 routing 漂移、topic 健康度,以及 **当前 TASK_ROOT** 下 active 任务里的 delta。它看不到 Bob 本机的 `.task/`,也不应该看到。
`kb status` 检查 routing 漂移、topic 健康度,以及 **当前 TASK_ROOT** 下 active 任务里的 delta。即使已拉取其他人的任务,它也只扫描当前身份的任务根。

### 工作中

Expand All @@ -185,7 +185,7 @@ flow2spec kb check --strict

### 收工

知识已 apply 后,先看 `.Knowledge/` 的真实 diff,再和实现一起提交。`.task/` 不在 staged files 里。
知识已 apply 后,先看 `.Knowledge/` 的真实 diff,再和实现一起提交。需要跨电脑续作时,可一并提交进行中任务与 `todo.json`。

```bash
git diff -- .Knowledge
Expand Down Expand Up @@ -228,7 +228,7 @@ revision 是磁盘乐观锁,不是远端服务上的全局锁。它不会隔
- 每个人配置稳定、可读的 `collaboration.developerId`,共享机器上尤其如此;
- 开工先拉取,知识变更和对应实现放在同一个 PR 或一组能互相追溯的提交里;
- topic 按单一职责拆分。topic 过大不仅影响路由,也会扩大 revision 冲突面;
- 不直接把 `.task/` 加回 Git,不用 `todo.json` 充当团队看板;
- `.gitignore` 使用 `.task/completed/` 与 `.task/*/completed/`;进行中任务可提交,`todo.json` 用于个人续作;
- topic 正文尽量走 `f2s-kb-*` 形成 delta。直接手改可以被 Git 记录,却绕过了 revision 预检;
- 合并前看 `.Knowledge/` diff,不只看 `kb plan` 的“mergeable”。结构可合并不代表业务表述一定正确;
- 团队统一 Flow2Spec 版本。CLI schema 和模板能力不一致时,协作问题很难靠流程约定补救。
Expand All @@ -239,7 +239,7 @@ topic 已经大到频繁互相阻塞时,先判断它是否混进了多个独

## 7. 管理者怎么看进度

`.task/` 不进 Git,manager 自然看不到每个人的 active checklist。这不是缺了一个同步功能,而是所有权边界:尚未验证的个人过程不该自动变成团队记录。
已提交的 active checklist 可用于了解个人任务现场;正式团队进度以已确认的承诺与产出为准。

团队进度应从已经形成承诺或产出的地方看:

Expand All @@ -249,21 +249,21 @@ topic 已经大到频繁互相阻塞时,先判断它是否混进了多个独
- 项目里程碑:跨多个提交的阶段性结果;
- 团队原有的 issue、项目看板或日报:负责人、截止时间和阻塞项。

如果团队确实需要共享“进行中”状态,优先接已有 issue 或看板,而不是同步 `.task/active/`。后者包含会话上下文、临时判断和用户代办,权限与生命周期都不同。
`.task/active/` 用于保存可续作的过程状态;团队负责人、截止时间与阻塞项可继续由已有 issue 或看板管理。

有人可能想把 `.task/<id>/completed/` 白名单放回 Git。这可以作为团队自定义方案,但不是 Flow2Spec 默认流程。采用前至少要定清楚保留周期、敏感信息清理、谁负责归档,以及它和正式里程碑的关系,否则很快会出现两套进度真值。
`.task/completed/` 与 `.task/*/completed/` 默认保留在本地。归档此前已提交的 active 任务时,Git 会显示原路径删除;该删除随下一次提交同步。

---

## 8. 常见问题

### `.task/` 已经是本地目录,为什么还要 developerId?
### `.task/` 可以通过 Git 同步,为什么还要 developerId?

同一台构建机、devcontainer 或共享工作区可能有多个身份;更重要的是,Agent 需要一个明确的读取边界。`TASK_ROOT` 让“不要续作别人的任务”从提醒变成可检查的路径约束。

### 换一台电脑后,原来的 active 任务会自动出现吗?

不会。`.task/` 默认不进 Git,它是本机过程状态。跨机器交接应把已确认内容写进 PR、需求文档或 `.Knowledge/`,不要依赖复制任务目录。
将进行中任务和 `todo.json` 提交、推送,再在另一台电脑拉取即可。两端应配置相同 `collaboration.developerId`,或确保 Git 身份解析结果相同;Agent 随后按原 `TASK_ROOT` 续作。

### `collaboration.enabled: false` 会关闭知识库协作吗?

Expand Down
6 changes: 3 additions & 3 deletions package-lock.json

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

Loading
Loading