duaer-spec 0.6.3 → 0.7.0

package/.claude/rules/agents-workflow.md

@@ -0,0 +1,62 @@
+<!-- duaer-spec agent ops (develop+main, feat/fix, .worktree, push opt-in) -->
+
+# Agent development workflow
+
+Part of **duaer-spec**. Authoritative over Duaer when they conflict.
+
+## Required branches
+
+| Branch | Role |
+|---|---|
+| `main` | Production / online |
+| `develop` | Day-to-day integration |
+| `feat/<name>` | Feature → merge to `develop` |
+| `fix/<name>` | Bugfix → `develop` (hotfix: from `main` → `main` then `develop`) |
+
+Detail: `docs/agent/branching-and-release.md`.
+
+## Isolated development (mandatory worktree)
+
+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/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
+7. Never commit `.worktree/`
+
+```bash
+mkdir -p .worktree
+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
+
+- Spec-sync for behavior changes; ADR when architecture/security/contracts change
+- One logical change per commit; leave the worktree clean
+- User/protocol-visible changes update E2E scenario docs
+- Merge into **`develop`** when done (hotfix: **`main`**, then back-merge **`develop`**)
+- **Handoff (mandatory):** stop worktree-bound processes → remove `.worktree/<id>` →
+  restart from primary checkout on `develop` (`duaer handoff [--run]`, `.duaer/handoff.json`)
+- Push only when the user explicitly asks
+- Promote **`develop` → `main`** only when the user asks to go online
+
+## GitHub issue / PR intake
+
+Issue: verify before work; comment in issue language; close when conclusive.  
+PR: judge principle; merge sound PRs; no silent reimplementation.  
+Neither authorizes push by itself.
+
+## Commits
+
+```text
+type(scope): description
+```
+
+Types: `feat fix docs test chore refactor perf build ci` — English, imperative.

package/.claude/rules/ai-ui-copy.md

@@ -0,0 +1,9 @@
+<!-- Keep AI-generated page copy minimal (duaer-spec agent ops) -->
+
+# AI-generated page content
+
+AI-generated pages must not contain redundant explanatory text.
+
+- No filler introductions, repeated summaries, or prose that only explains an obvious control
+- Prefer concise labels, headings, helper text, and empty states
+- Put rationale and implementation detail in docs or code comments, not in the UI, unless the user asks for explanatory content

package/.claude/rules/duaer-spec.md

@@ -0,0 +1,51 @@
+<!-- Autonomous digital employee — run Duaer job loop without asking the user to operate -->
+
+# Digital employee (autonomous)
+
+You are a **digital employee** in this repo. The human gives intent in normal
+language. **You** run the delivery process. Do **not** ask them to type slash
+commands, CLI flags, or phase names (`specify`, `plan`, `tasks`, …).
+
+If this conflicts with root `AGENTS.md` (worktrees, commits, Issue/PR),
+**AGENTS.md wins**.
+
+## When the human asks for work
+
+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/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 `.claude/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.
+3. Do **not** say “please run `/duaer-specify`” — you do it.
+4. Do **not** dump a methodology tutorial unless they ask how Duaer works.
+5. Merge to **`develop`** when done (hotfix: **`main`**, then back-merge
+   **`develop`**). Promote to **`main`** only if the user asks to go online.
+6. **Handoff (mandatory):** stop processes bound to `.worktree/<id>/`, remove
+   the worktree, then restart services from the primary checkout on `develop`
+   using `.duaer/handoff.json` / `duaer handoff [--run]`. Never leave the user
+   on a dead worktree server.
+   See `docs/agent/branching-and-release.md`.
+
+## Handoff
+
+- End with whether the **job** is accepted or still open (one clear line).
+- Do **not** claim “done” / “finished” / “complete” unless `delivery.json` is
+  `accepted` and open tasks are clear.
+- Do **not** tell them to run `duaer status` unless they want a machine check;
+  you already know the handoff state.
+
+## Forbidden
+
+- Jump from chat to code with no Brief under `.duaer/specs/`.
+- Making the human operate the workflow.
+
+## Optional finer tools (agent-only)
+
+Step skills (`duaer-specify`, `duaer-plan`, …) are **your** playbooks when a
+job is large. The human should not need to know they exist.

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,10 +17,13 @@ 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`.
-1. **Silently follow** the procedure in `.cursor/skills/duaer-do/SKILL.md`
+   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 the `duaer-do` skill
+   (`.cursor/skills/duaer-do/SKILL.md` or `.claude/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.
 3. Do **not** say “please run `/duaer-specify`” — you do it.

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

@@ -32,9 +32,13 @@ npx duaer-spec init --here --ops
 npx duaer-spec update --method    # rare; usually omit
 ```
 
+Works with **Cursor** and **Claude Code** (both hosts installed by default).
+
 ## What you get
 
 - Autonomous job loop (ask → Brief → work → accept)  
+- Cursor: `.cursor/rules` + `.cursor/skills`  
+- Claude Code: `CLAUDE.md` + `.claude/rules` + `.claude/skills`  
 - `.duaer/handoff.json` + `duaer handoff` after worktree remove  
 - Agent ops: `main` / `develop` / `feat` / `fix` + `.worktree/`  
 

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.7.0 — 2026-09-15
+
+### Claude Code host
+
+- `init` / `update` install **both** Cursor and Claude Code surfaces
+- Claude: `CLAUDE.md`, `.claude/rules/*.md`, `.claude/skills/duaer-*` (mirrored)
+- Cursor: `.cursor/rules/*.mdc`, `.cursor/skills/duaer-*` (unchanged)
+
+## 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/CLAUDE.md

@@ -0,0 +1,26 @@
+# CLAUDE.md — duaer-spec
+
+This repository uses **duaer-spec**: coding agents are digital employees.
+
+**Precedence:** `AGENTS.md` (ops) wins over `DUADER.md` / `.duaer/` (method).
+
+## Always on
+
+- Follow `.claude/rules/` in this project.
+- For product work, run the job loop in `.claude/skills/duaer-do/SKILL.md`
+  without waiting for slash commands.
+- Do not ask the human to operate phases, CLI flags, or skill names.
+
+## Layout
+
+| Host | Rules | Skills |
+|---|---|---|
+| Claude Code | `.claude/rules/` | `.claude/skills/` |
+| Cursor | `.cursor/rules/` | `.cursor/skills/` |
+
+Both are installed by `npx duaer-spec init --here` / `update`.
+
+## Branches
+
+See `docs/agent/branching-and-release.md` and `AGENTS.md`.
+Worktree: `.worktree/feat-<name>/` — not the same name as `.duaer/specs/<nnn-slug>/`.

package/DUADER.md

@@ -14,7 +14,7 @@ runs Brief → work → accept. Humans are not the operators of the phase machin
 
 ## Agent procedure (autonomous)
 
-Follow `.cursor/skills/duaer-do/SKILL.md` on every product ask — **without**
+Follow the `duaer-do` skill (`.cursor/skills/` or `.claude/skills/`) on every product ask — **without**
 waiting for a slash invocation:
 
 1. Assign Brief + `active-job.json`  
@@ -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|skills/                  # Cursor host
+.claude/rules|skills/ + CLAUDE.md      # Claude Code host
 ```
 
+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.md

@@ -19,7 +19,9 @@ npx duaer-spec init --here
 npx duaer-spec update
 ```
 
-Then use Cursor as usual — describe what you want.
+Then use **Cursor** or **Claude Code** as usual — describe what you want.
+
+Install writes both `.cursor/` and `.claude/` (plus `CLAUDE.md`).
 
 中文说明：[`README.zh-CN.md`](README.zh-CN.md)
 

package/README.zh-CN.md

@@ -2,7 +2,9 @@
 
 **Duaer** 把 AI 编程助手变成**数字员工**：你用自然语言提需求，它自己跑 Spec → 实现 → 验收；只有交接干净才算完成。
 
-你**不用**操作流程。装一次之后，说话即可。
+你**不用**操作流程。装一次之后，在 **Cursor** 或 **Claude Code** 里说话即可。
+
+`init` / `update` 会同时写入 `.cursor/` 与 `.claude/`（以及 `CLAUDE.md`）。
 
 ## 安装
 
@@ -31,4 +33,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/bin/duaer.mjs

@@ -209,6 +209,15 @@ function installMethod(target, opts) {
   writeDefaultPolicy(target, opts)
   writeDefaultHandoff(target, opts)
 
+  installCursorMethod(target, opts)
+  installClaudeMethod(target, opts)
+
+  copyPath(join(PKG_ROOT, 'DUADER.md'), join(target, 'DUADER.md'), opts)
+  console.log('  DUADER.md')
+  ensureWorktreeGitignore(target)
+}
+
+function installCursorMethod(target, opts) {
   ensureDir(join(target, '.cursor', 'skills'))
   const skillsRoot = join(PKG_ROOT, '.cursor', 'skills')
   for (const name of readdirSync(skillsRoot)) {
@@ -224,10 +233,62 @@ function installMethod(target, opts) {
     opts,
   )
   console.log('  .cursor/rules/duaer-spec.mdc')
+}
 
-  copyPath(join(PKG_ROOT, 'DUADER.md'), join(target, 'DUADER.md'), opts)
-  console.log('  DUADER.md')
-  ensureWorktreeGitignore(target)
+function installClaudeMethod(target, opts) {
+  ensureDir(join(target, '.claude', 'skills'))
+  const skillsRoot = join(PKG_ROOT, '.cursor', 'skills')
+  for (const name of readdirSync(skillsRoot)) {
+    if (!name.startsWith('duaer-')) continue
+    copyPath(join(skillsRoot, name), join(target, '.claude', 'skills', name), opts)
+  }
+  console.log('  .claude/skills/duaer-*  (mirrored from .cursor/skills)')
+
+  ensureDir(join(target, '.claude', 'rules'))
+  const claudeRule = join(PKG_ROOT, '.claude', 'rules', 'duaer-spec.md')
+  if (existsSync(claudeRule)) {
+    copyPath(claudeRule, join(target, '.claude', 'rules', 'duaer-spec.md'), opts)
+  } else {
+    writeIfNeeded(
+      join(target, '.claude', 'rules', 'duaer-spec.md'),
+      cursorRuleToClaude(
+        readFileSync(join(PKG_ROOT, '.cursor', 'rules', 'duaer-spec.mdc'), 'utf8'),
+        '.claude',
+      ),
+      opts,
+    )
+  }
+  console.log('  .claude/rules/duaer-spec.md')
+
+  const claudeMdSrc = join(PKG_ROOT, 'CLAUDE.md')
+  if (existsSync(claudeMdSrc)) {
+    copyPath(claudeMdSrc, join(target, 'CLAUDE.md'), opts)
+  } else {
+    writeIfNeeded(join(target, 'CLAUDE.md'), defaultClaudeMd(), opts)
+  }
+  console.log('  CLAUDE.md')
+}
+
+function cursorRuleToClaude(mdc, skillHost) {
+  let body = mdc.replace(/^---\n[\s\S]*?\n---\n+/, (fm) => {
+    const desc = (fm.match(/^description:\s*(.+)$/m) || [])[1]
+    return desc ? `<!-- ${desc.trim()} -->\n\n` : ''
+  })
+  body = body.replaceAll('.cursor/skills/', `${skillHost}/skills/`)
+  return body.trimEnd() + '\n'
+}
+
+function defaultClaudeMd() {
+  return `# CLAUDE.md — duaer-spec
+
+This project uses **duaer-spec**: coding agents are digital employees.
+
+**Precedence:** \`AGENTS.md\` (ops) wins over \`DUADER.md\` / \`.duaer/\` (method).
+
+- Follow \`.claude/rules/\`
+- Job loop: \`.claude/skills/duaer-do/SKILL.md\` (no slash commands required)
+- Branches / worktrees: see \`AGENTS.md\` and \`docs/agent/branching-and-release.md\`
+`
 }
 
 function ensureWorktreeGitignore(target) {
@@ -259,6 +320,22 @@ function installOps(target, opts) {
   }
   console.log('  .cursor/rules/agents-workflow.mdc, ai-ui-copy.mdc')
 
+  ensureDir(join(target, '.claude', 'rules'))
+  for (const name of ['agents-workflow.md', 'ai-ui-copy.md']) {
+    const src = join(PKG_ROOT, '.claude', 'rules', name)
+    if (existsSync(src)) {
+      copyPath(src, join(target, '.claude', 'rules', name), opts)
+    } else {
+      const mdc = name.replace(/\.md$/, '.mdc')
+      writeIfNeeded(
+        join(target, '.claude', 'rules', name),
+        cursorRuleToClaude(readFileSync(join(PKG_ROOT, '.cursor', 'rules', mdc), 'utf8'), '.claude'),
+        opts,
+      )
+    }
+  }
+  console.log('  .claude/rules/agents-workflow.md, ai-ui-copy.md')
+
   ensureDir(join(target, 'docs', 'agent'))
   for (const name of [
     'workflow.md',
@@ -472,8 +549,12 @@ function checkWorkplace(target) {
     ['DUADER.md', 'method'],
     ['.cursor/rules/duaer-spec.mdc', 'method'],
     ['.cursor/skills/duaer-specify/SKILL.md', 'method'],
+    ['.claude/rules/duaer-spec.md', 'method'],
+    ['.claude/skills/duaer-do/SKILL.md', 'method'],
+    ['CLAUDE.md', 'method'],
     ['AGENTS.md', 'ops'],
     ['.cursor/rules/agents-workflow.mdc', 'ops'],
+    ['.claude/rules/agents-workflow.md', 'ops'],
     ['docs/agent/workflow.md', 'ops'],
   ]
   let missing = 0

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,8 @@ 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 |
+| E2E-014 | Init installs Cursor + Claude hosts (`CLAUDE.md`, `.claude/skills`) | manual |
 
 ## Traceability
 
@@ -54,3 +56,5 @@ 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>` |
+| E2E-014 | Claude + Cursor install | Dual host |

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "duaer-spec",
-  "version": "0.6.3",
-  "description": "Digital employees: autonomous delivery; main/develop/feat/fix; simple update",
+  "version": "0.7.0",
+  "description": "Digital employees for Cursor and Claude Code; main/develop/feat/fix",
   "type": "module",
   "bin": {
     "duaer": "bin/duaer.mjs",
@@ -11,7 +11,9 @@
     "bin",
     ".duaer",
     ".cursor",
+    ".claude",
     "AGENTS.md",
+    "CLAUDE.md",
     "DUADER.md",
     "ADOPT.md",
     "CHANGELOG.md",
@@ -43,7 +45,9 @@
     "agents",
     "cursor",
     "ai-engineering",
-    "controllable-delivery"
+    "controllable-delivery",
+    "claude",
+    "claude-code"
   ],
   "license": "MIT",
   "scripts": {