duaer-spec 0.6.3 → 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/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,14 @@
 # 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 说明

package/DUADER.md

@@ -34,12 +34,18 @@ 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)

package/README.zh-CN.md

@@ -31,4 +31,13 @@ npx duaer-spec update
 
 合并后：`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/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.
 

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

@@ -37,6 +37,7 @@ the table for their app.
 | 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
 
@@ -54,3 +55,4 @@ the table for their app.
 | 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.3",
+  "version": "0.6.4",
   "description": "Digital employees: autonomous delivery; main/develop/feat/fix; simple update",
   "type": "module",
   "bin": {