duaer-spec 0.6.2 → 0.6.4

package/.cursor/rules/agents-workflow.mdc

@@ -24,7 +24,9 @@ Before editing files for a new request:
 
 1. Update local **`develop`** (hotfix: **`main`**)
 2. Create `feat/<name>` or `fix/<name>`
-3. Create worktree at **`.worktree/<request-id>`** (required)
+3. Create worktree at **`.worktree/feat-<name>`** or **`.worktree/fix-<name>`**
+   (slash → hyphen). Do **not** reuse the Brief folder name
+   (`.duaer/specs/<nnn-slug>/`) as the worktree id.
 4. Develop only inside that worktree
 5. Never develop on `main` / `develop` or in the primary checkout
 6. Never reuse another agent's branch/worktree
@@ -32,8 +34,9 @@ Before editing files for a new request:
 
 ```bash
 mkdir -p .worktree
-git worktree add .worktree/<request-id> -b feat/<name> develop
-cd .worktree/<request-id>
+git worktree add .worktree/feat-login -b feat/login develop
+cd .worktree/feat-login
+# Brief lives inside the checkout, e.g. .duaer/specs/002-login/
 ```
 
 ## Immutable habits

package/.cursor/rules/duaer-spec.mdc

@@ -17,9 +17,11 @@ If this conflicts with root `AGENTS.md` (worktrees, commits, Issue/PR),
 For new behavior, fixes, refactors that change product behavior, or architecture:
 
 0. **Isolate first (mandatory):** update **`develop`** (hotfix: **`main`**),
-   create `feat|fix/<name>`, add worktree at `.worktree/<request-id>`,
-   work only there. Never skip the worktree. Never commit `.worktree/`.
-   Never develop on `main` or `develop`.
+   create `feat|fix/<name>`, add worktree at `.worktree/feat-<name>` or
+   `.worktree/fix-<name>` (slash → hyphen). Never name the worktree after the
+   Brief folder (do **not** use `.worktree/<nnn-slug>` when the Spec is
+   `.duaer/specs/<nnn-slug>/`). Work only in the worktree. Never commit
+   `.worktree/`. Never develop on `main` or `develop`.
 1. **Silently follow** the procedure in `.cursor/skills/duaer-do/SKILL.md`
    (assign Brief → light tasks → implement → converge → handoff line).
 2. Do **not** wait for `/duaer-do` or any other skill invocation.

package/.cursor/skills/duaer-do/SKILL.md

@@ -32,6 +32,10 @@ Do **not** lecture about methodology. Do **not** ask them to run commands.
    - Matching active job (`.duaer/active-job.json` + `spec.md`) → update acceptance if needed.
    - Else create `.duaer/specs/<nnn-slug>/spec.md` and `.duaer/active-job.json`
      (same outcome as specify). Keep small asks short: what / why / acceptance.
+   - The Brief path is **not** the worktree path. Isolation uses
+     `.worktree/feat-<name>/` (or `fix-…`); the Spec stays under
+     `.duaer/specs/<nnn-slug>/` inside that checkout. Never set both names to
+     the same `<nnn-slug>`.
 
 2. **Break down** — If `tasks.md` missing, write a short checklist from the Spec.
    Skip a heavy plan unless architecture or contracts change.

package/ADOPT.md

@@ -12,10 +12,15 @@ npx duaer-spec init --here
 npx duaer-spec update
 ```
 
-That’s it. If you customized local files, glance at `git diff` once.
+Do **not** use `init --here --force` as the everyday refresh. `update` reuses
+the mode/branch from `.duaer/duaer-init.json`.
+
+If you customized constitution / baseline / `.duaer/handoff.json` commands,
+glance at `git diff` once and keep your overrides.
 
 Ensure the repo has **`main`** and **`develop`**. See
-[`docs/agent/branching-and-release.md`](docs/agent/branching-and-release.md).
+[`docs/agent/branching-and-release.md`](docs/agent/branching-and-release.md)
+(Chinese: [`README.zh-CN.md`](README.zh-CN.md)).
 
 Then talk to the agent in plain language.
 

package/AGENTS.md

@@ -147,10 +147,31 @@ Example (normal feature):
 git switch develop
 git pull --ff-only
 mkdir -p .worktree
-git worktree add .worktree/<request-id> -b feat/<request-id> develop
-cd .worktree/<request-id>
+git worktree add .worktree/feat-login -b feat/login develop
+cd .worktree/feat-login
 ```
 
+**Two different folders — do not give them the same name:**
+
+| Layer | Path | Role |
+|---|---|---|
+| Worktree | `.worktree/feat-<name>/` | Full git checkout for isolation |
+| Brief | `.duaer/specs/<nnn-slug>/` | Job Spec / tasks / delivery stamp |
+
+A worktree is a **complete** repo copy, so Briefs live *inside* it:
+
+```text
+.worktree/feat-login/.duaer/specs/002-login/spec.md
+```
+
+That is expected. What is **wrong** is reusing the Brief folder name as the
+worktree id (e.g. `.worktree/002-login/.../specs/002-login/`) — it looks like
+double nesting and confuses humans. Always:
+
+* Branch: `feat/<name>` or `fix/<name>`
+* Worktree: `.worktree/feat-<name>` or `.worktree/fix-<name>` (slash → hyphen)
+* Brief: `.duaer/specs/<nnn-slug>/` (numbered catalog; may differ from `<name>`)
+
 Branch and worktree names must be unique and clearly associated with the request.
 Do **not** place request worktrees outside the repo (for example `../worktrees/`)
 unless the project baseline explicitly overrides this and still keeps them

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 0.6.4 — 2026-09-15
+
+### Worktree ≠ Brief folder name
+
+- Clarify two layers: `.worktree/feat-<name>/` (full checkout) vs
+  `.duaer/specs/<nnn-slug>/` (Brief)
+- Forbid naming the worktree after the Brief slug (avoids
+  `.worktree/002-x/.../specs/002-x/` double naming)
+
+## 0.6.3 — 2026-09-15
+
+### Docs: update path in installed 说明
+
+- `DUADER.md` and `docs/agent/branching-and-release.md` document `npx duaer-spec update`
+- Add `README.zh-CN.md` (install / update / branches)
+- ADOPT clarifies: do not use `init --force` for everyday refresh
+
 ## 0.6.2 — 2026-09-15
 
 ### Simple update

package/DUADER.md

@@ -7,9 +7,10 @@ runs Brief → work → accept. Humans are not the operators of the phase machin
 
 ## Human experience
 
-1. One-time: `npx duaer-spec init --here`  
-2. Ongoing: describe work in chat  
-3. Review the handoff line (accepted / not yet)
+1. One-time install: `npx duaer-spec init --here`  
+2. Later refresh: `npx duaer-spec update`  
+3. Ongoing: describe work in chat  
+4. Review the handoff line (accepted / not yet)
 
 ## Agent procedure (autonomous)
 
@@ -33,13 +34,20 @@ Humans need not configure it for everyday use.
 ## Layout
 
 ```text
-.duaer/active-job.json
-.duaer/specs/<nnn-slug>/spec.md|tasks.md|delivery.json
-.cursor/rules/duaer-spec.mdc      # autonomous behavior
-.cursor/skills/duaer-do/          # default job loop
+.worktree/feat-<name>/                 # git isolation (full checkout)
+  .duaer/active-job.json
+  .duaer/specs/<nnn-slug>/             # Brief (≠ worktree folder name)
+    spec.md | tasks.md | delivery.json
+.cursor/rules/duaer-spec.mdc           # autonomous behavior
+.cursor/skills/duaer-do/               # default job loop
 ```
 
+Worktree and Brief are different layers. Prefer
+`.worktree/feat-login/.duaer/specs/002-login/` — not
+`.worktree/002-login/.duaer/specs/002-login/`.
+
 ## Related
 
 - Adopt: [`ADOPT.md`](ADOPT.md)
+- Branches / go-live: [`docs/agent/branching-and-release.md`](docs/agent/branching-and-release.md)
 - Agent ops: [`AGENTS.md`](AGENTS.md)

package/README.md

@@ -21,6 +21,8 @@ npx duaer-spec update
 
 Then use Cursor as usual — describe what you want.
 
+中文说明：[`README.zh-CN.md`](README.zh-CN.md)
+
 ## What the employee does (by itself)
 
 1. Writes a Brief (Spec) for the ask  

package/README.zh-CN.md

@@ -0,0 +1,43 @@
+# duaer-spec
+
+**Duaer** 把 AI 编程助手变成**数字员工**：你用自然语言提需求，它自己跑 Spec → 实现 → 验收；只有交接干净才算完成。
+
+你**不用**操作流程。装一次之后，说话即可。
+
+## 安装
+
+```bash
+npx duaer-spec init --here
+```
+
+## 更新
+
+```bash
+npx duaer-spec update
+```
+
+若你改过本地 constitution / baseline / `handoff.json` 命令，看一眼 `git diff` 即可。
+
+## 必须有的分支
+
+| 分支 | 作用 |
+|---|---|
+| `main` | 生产 / 正式上线 |
+| `develop` | 日常集成、联调 |
+| `feat/<name>` | 功能 → 合进 `develop` |
+| `fix/<name>` | 缺陷 → 合进 `develop`（紧急从 `main` 出，再回补 `develop`） |
+
+不同问题怎么上线：[`docs/agent/branching-and-release.md`](docs/agent/branching-and-release.md)
+
+合并后：`duaer handoff [--run]` 在 `develop` 上重启本地服务（命令写在 `.duaer/handoff.json`）。
+
+### 目录不要同名套娃
+
+Worktree 是整仓副本，Brief 在仓库内的 `.duaer/specs/`：
+
+```text
+正确: .worktree/feat-login/.duaer/specs/002-login/spec.md
+错误: .worktree/002-login/.duaer/specs/002-login/spec.md   ← worktree 名不要用 specs 目录名
+```
+
+英文源：[`README.md`](README.md) · 采纳细节：[`ADOPT.md`](ADOPT.md)

package/docs/agent/README.md

@@ -10,4 +10,6 @@ Wins over Duaer and `examples/` when they conflict.
 | [change-checklist.md](change-checklist.md) | Finish checklist |
 | [e2e-test-plan.md](e2e-test-plan.md) | E2E scenario catalog template |
 
-Root contract: [`AGENTS.md`](../../AGENTS.md). Adoption: [`ADOPT.md`](../../ADOPT.md).
+Root contract: [`AGENTS.md`](../../AGENTS.md).  
+Adoption: [`ADOPT.md`](../../ADOPT.md) — `npx duaer-spec init --here` / `npx duaer-spec update`.  
+Chinese summary: [`README.zh-CN.md`](../../README.zh-CN.md).

package/docs/agent/branching-and-release.md

@@ -36,6 +36,18 @@ feat/<short-description>   # new capability / improvement
 fix/<short-description>    # defect
 ```
 
+Worktree directory = branch with `/` → `-`:
+
+```text
+branch feat/login  →  .worktree/feat-login
+branch fix/timer   →  .worktree/fix-timer
+```
+
+Duaer Brief folders are separate: `.duaer/specs/<nnn-slug>/`. Because a worktree
+is a full checkout, Specs appear as
+`.worktree/feat-login/.duaer/specs/002-login/spec.md`. That nesting is normal.
+Do **not** reuse `<nnn-slug>` as the worktree folder name.
+
 Optional types when the project already uses them: `docs/`, `chore/`, `refactor/`,
 `test/`, `ci/` — still branch from `develop`, merge back to `develop` first.
 
@@ -199,9 +211,20 @@ All implementation edits happen inside the request worktree.
 
 ---
 
+## 7. Install and update (adopters)
+
+```bash
+npx duaer-spec init --here     # once
+npx duaer-spec update          # later refresh — no --force recipe
+```
+
+Details: [`ADOPT.md`](../../ADOPT.md). Chinese summary: [`README.zh-CN.md`](../../README.zh-CN.md).
+
 ## Related
 
 - [workflow.md](workflow.md) — R4 and development loop  
 - [change-checklist.md](change-checklist.md) — finish checklist  
 - [baseline.md](../baseline.md) — frozen: `develop` + `main`  
-- [ADOPT.md](../../ADOPT.md) — install into another repo  
+- [ADOPT.md](../../ADOPT.md) — install / update into another repo  
+- [README.zh-CN.md](../../README.zh-CN.md) — Chinese install, update, branches  
+

package/docs/agent/e2e-test-plan.md

@@ -35,6 +35,9 @@ the table for their app.
 | E2E-008 | Docs require main+develop+feat+fix and typed go-live flows | manual |
 | E2E-009 | After merge, handoff restarts services on develop (`duaer handoff`) | manual |
 | E2E-010 | `npx duaer-spec update` refreshes an existing install | manual |
+| E2E-011 | Installed docs (`DUADER.md`, `docs/agent/`) document `update` | manual |
+| E2E-012 | `README.zh-CN.md` covers install, update, branch model | manual |
+| E2E-013 | Worktree id ≠ Brief `<nnn-slug>`; path is `.worktree/feat-…/.duaer/specs/…` | manual |
 
 ## Traceability
 
@@ -50,3 +53,6 @@ the table for their app.
 | E2E-008 | `branching-and-release.md` | Branch + release matrix |
 | E2E-009 | `.duaer/handoff.json` / `duaer handoff` | Service handoff |
 | E2E-010 | `duaer update` | One-line refresh |
+| E2E-011 | DUADER + agent docs | Update path in installed 说明 |
+| E2E-012 | `README.zh-CN.md` | Chinese 说明文档 |
+| E2E-013 | AGENTS / branching naming | Avoid double `<nnn-slug>` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "duaer-spec",
-  "version": "0.6.2",
+  "version": "0.6.4",
   "description": "Digital employees: autonomous delivery; main/develop/feat/fix; simple update",
   "type": "module",
   "bin": {
@@ -18,7 +18,8 @@
     "docs/agent",
     "docs/baseline.md",
     "LICENSE",
-    "README.md"
+    "README.md",
+    "README.zh-CN.md"
   ],
   "publishConfig": {
     "access": "public"