From 8d3557e176a8adaabd780acbd8171080fd5f39b6 Mon Sep 17 00:00:00 2001 From: "sanze.li" <2522048902@qq.com> Date: Wed, 21 Oct 2026 16:14:00 +0800 Subject: [PATCH] docs: explain how ~go works through a plan and where the modes live The README quick start now says what ~go does: it works through the plan one task at a time (implement, verify, review, then check it off), pauses for missing facts or your decisions, and after an interruption or handover continues with the next unfinished task that can proceed. The command cheat sheet drops routing jargon, and the pages follow. How Sopify Works gains a short "Task loop and modes" section covering the retry and blocking rules, when receipts are written, and the four separate mode dimensions (request intent, workflow.mode, plan level, interaction). The example config lists the current plan levels instead of the retired background/design/tasks and "full" layouts. Co-Authored-By: Claude Opus 5.5 --- README.md | 8 ++++---- README.zh-CN.md | 8 ++++---- docs/how-sopify-works.en.md | 13 +++++++++++++ docs/how-sopify-works.md | 13 +++++++++++++ examples/sopify.config.yaml | 6 +++--- index.html | 4 ++-- zh-CN.html | 2 +- 7 files changed, 40 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index 4a77108c..11717ea7 100644 --- a/README.md +++ b/README.md @@ -53,11 +53,11 @@ Sopify asks about anything still unresolved and writes `.sopify/plan/YYYYMMDD_si **3. Run the plan, then archive it.** ```text -~go # implement the plan task by task, recording verification evidence -~go finalize # move the finished plan to .sopify/history/ +~go # run or resume the current plan +~go finalize # once all tasks are complete, archive the plan to .sopify/history/ ``` -The plan and its evidence stay in Git, so another supported tool can resume the work. +`~go` works through the plan one task at a time: implement, then verify and review, mark the task done once checks pass, and move to the next. It pauses when a fact is missing or a decision requires your input, and continues after you answer. After an interruption, a tool switch, or a handover, type `~go` again: it reads the plan and its evidence, then continues with the next unfinished task that can proceed. In a fresh clone, if the target plan is unclear, it asks which one to continue. A finished plan stays in `plan/` until you run `~go finalize`. See [How Sopify Works](./docs/how-sopify-works.en.md#task-loop-and-modes) for the read order and pause rules. ### What lands in your repo @@ -106,7 +106,7 @@ These are handled directly and never enter the plan workflow. A plan starts only | Command | When to type it | |---|---| | `~go plan ` | New work that needs a plan — asks first when anything is unclear, writes `.sopify/plan//plan.md` only after you answer, and changes no code | -| `~go` | Start or continue. Routes the current request, and resumes the active plan when there is one | +| `~go` | Run or resume the current plan; routine questions and small fixes are answered directly without resuming a plan | | `~go finalize` | Close out the active plan and move it to `.sopify/history/` | ## Supported Hosts diff --git a/README.zh-CN.md b/README.zh-CN.md index 949826cf..9347c3cf 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -53,11 +53,11 @@ Sopify 会先追问还没定的事实，等你在对话里回答后才写 `.sopi **3. 执行方案，做完归档。** ```text -~go # 按任务推进方案，并记录验收证据 -~go finalize # 把做完的方案移到 .sopify/history/ +~go # 执行或继续当前方案 +~go finalize # 全部完成后，把方案归档到 .sopify/history/ ``` -方案和证据都留在 Git 里，换到其他受支持的工具时可以接续。 +`~go` 按方案里的任务逐项推进：每一项先实现，再验证和复审，通过后才勾选，然后进入下一项。缺少事实或需要你拍板时，它会停下来；你回答后再继续。中断、换工具或换人之后，再输入 `~go`，它会先读方案和验收记录，从下一个可执行的未完成任务继续。新 clone 的仓库如果目标方案不明确，会先问你继续哪一个。全部完成的方案留在 `plan/`，直到你运行 `~go finalize`。读取顺序和暂停规则见 [Sopify 如何工作](./docs/how-sopify-works.md#任务循环与模式)。 ### 仓库里会多出什么 @@ -106,7 +106,7 @@ iwr https://github.com/evidentloop/sopify/releases/latest/download/install.ps1 - | 命令 | 什么时候输入 | |---|---| | `~go plan <需求>` | 需要方案的新工作——不清楚时先追问，等你回答后才写 `.sopify/plan//plan.md`，不改代码 | -| `~go` | 开始或继续。按当前请求路由，有活动方案时就接续 | +| `~go` | 执行或继续当前方案；日常问答和小修直接响应，不触发方案接续 | | `~go finalize` | 收口当前活动方案，并移到 `.sopify/history/` | ## 支持的宿主 diff --git a/docs/how-sopify-works.en.md b/docs/how-sopify-works.en.md index f0b8b5cc..4e2fc6fe 100644 --- a/docs/how-sopify-works.en.md +++ b/docs/how-sopify-works.en.md @@ -57,6 +57,19 @@ The workflow includes two canonical checkpoint types: Both are expressed through `current_handoff.required_host_action`, not separate state files. +### Task Loop and Modes + +- **Task loop**: Develop picks the next ready task from `tasks.md` (or `plan.md` for a light plan) by dependency and number, then runs implement → verify → review. A task is checked `[x]` only after verification and every review pass. After a first verification failure, it may retry once with the failure context; after a second failure, or without a retry, it records the root cause and then fixes and re-verifies, leaves the result unverified, marks the task blocked `[!]`, or sends the plan back for review. While a task is blocked, only tasks that do not depend on it continue. +- **Completion and archive**: Once tasks, verification and any required knowledge updates are done, the plan is marked `ready_to_archive` and stays in `plan/`. Only `~go finalize` moves it to `history/`. +- **Receipts**: An execution event in a managed plan writes `exec_NNN`; a verification or audit result adopted as formal evidence writes `verify_NNN`; archiving writes `final`. Planning without execution or verification events writes none, and plain questions and unmanaged small fixes stay outside the receipt flow. + +| Dimension | Values | Notes | +|---|---|---| +| Request intent | question, small fix, new plan, continue, finalize | Decided by the host on every turn; questions and small fixes do not enter the plan workflow | +| `workflow.mode` | `adaptive` (default), `strict`, `minimal` | Optional: `strict` confirms after analysis and design; `minimal` skips planning but keeps authorization and protocol boundaries | +| Plan level | `light`, `standard`, `architecture` | Chosen by Design: `plan.md` only; plus `tasks.md`; plus `design.md` | +| Interaction | chat, non-interactive | A non-interactive session ends its turn when it asks a question; send the answer with the next request. The host's first automatic project setup needs an interactive session | + ## Protocol Entry (4-Step Read Chain) When the host detects `.sopify/` and the user request targets managed plan / continuation / finalize: diff --git a/docs/how-sopify-works.md b/docs/how-sopify-works.md index 1f311d18..51f46b31 100644 --- a/docs/how-sopify-works.md +++ b/docs/how-sopify-works.md @@ -57,6 +57,19 @@ Sopify 主要做三件事： 两者都通过 `current_handoff.required_host_action` 表达，不再是独立 state 文件。 +### 任务循环与模式 + +- **任务循环**：Develop 从 `tasks.md`（light 方案为 `plan.md`）里按依赖和编号选择可执行项，逐项「实现 → 验证 → 复审」，验证与各项复审均通过后才勾选 `[x]`。首次验证失败可带失败上下文自动重试一次；再次失败或放弃重试时记录根因，按原因修复后再验证、保留未验证状态、标为阻塞 `[!]` 或退回方案审查。有阻塞项时，只继续不依赖它的任务。 +- **完成与归档**：任务、验证和所需的知识更新完成后，方案标为 `ready_to_archive` 并留在 `plan/`；只有 `~go finalize` 才归档到 `history/`。 +- **回执**：受管方案实际发生执行事件时写 `exec_NNN`，验证或审计结果被采用为正式证据时写 `verify_NNN`，归档时写 `final`。只有规划而没有执行、验证事件时不写；普通问答和非受管小修不进入回执流程。 + +| 维度 | 取值 | 说明 | +|---|---|---| +| 请求意图 | 问答、小修、新方案、继续、收口 | 宿主每轮先判断；问答和小修不进入方案流程 | +| `workflow.mode` | `adaptive`（默认）、`strict`、`minimal` | 可选配置：`strict` 在分析和设计后逐阶段确认；`minimal` 省略规划，仍遵守授权和协议边界 | +| 方案级别 | `light`、`standard`、`architecture` | 由 Design 选择：只有 `plan.md`；加 `tasks.md`；再加 `design.md` | +| 交互方式 | 对话、非交互 | 非交互会话遇到提问会结束本轮，下一次请求需带上答案；宿主首次自动绑定项目时需要交互会话 | + ## 协议入口（4 步读链） 当宿主检测到 `.sopify/` 且用户请求指向 managed plan / continuation / finalize 时： diff --git a/examples/sopify.config.yaml b/examples/sopify.config.yaml index e684f898..8d1f80d0 100644 --- a/examples/sopify.config.yaml +++ b/examples/sopify.config.yaml @@ -49,9 +49,9 @@ workflow: plan: # Plan level: # - auto: Select based on task complexity - # - light: Single file (plan.md) - # - standard: Three files (background.md, design.md, tasks.md) - # - full: Complete structure with ADR and diagrams + # - light: plan.md + # - standard: plan.md + tasks.md + # - architecture: plan.md + tasks.md + design.md level: auto # Note: model compare configuration was removed with the retired compare runtime. diff --git a/index.html b/index.html index 331ebe64..11010e1f 100644 --- a/index.html +++ b/index.html @@ -156,8 +156,8 @@

The host executes. Sopify keeps the work resumable

plans, decisions, and verification evidence as project files in .sopify/.

- Ask to continue, or use ~go, and the host resumes an unfinished plan from those files. A - local handoff pointer provides a same-workspace resume hint. + ~go runs or resumes the current plan from those files; routine questions and small fixes are + answered directly without resuming a plan. A local handoff pointer provides a same-workspace resume hint.

.sopify/plan/…
    diff --git a/zh-CN.html b/zh-CN.html index 59254b7e..c6d0d2e5 100644 --- a/zh-CN.html +++ b/zh-CN.html @@ -150,7 +150,7 @@

    收口归档

    产品形态

    宿主负责执行，Sopify 让工作可接续

    Sopify 是一套规则和 Skill，装进你已经在用的 AI 编程工具。它把方案、决策和验收证据作为项目文件保存在 .sopify/ 并纳入 Git。

    -

    明确要求继续，或输入 ~go，宿主才会从这些记录接续未完成的方案；本地交接指针为同一工作区提供接续提示。

    +

    输入 ~go 执行或继续当前方案；日常问答和小修直接响应，不触发方案接续。本地交接指针为同一工作区提供接续提示。

    .sopify/plan/…
    • Codex · 已验证