diff --git a/README.md b/README.md index 4a77108..11717ea 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 949826c..9347c3c 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 f0b8b5c..4e2fc6f 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 1f311d1..51f46b3 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 e684f89..8d1f80d 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 331ebe6..11010e1 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 59254b7..c6d0d2e 100644 --- a/zh-CN.html +++ b/zh-CN.html @@ -150,7 +150,7 @@

    收口归档

    产品形态

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

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

    -

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

    +

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

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