duaer-spec 0.6.0 → 0.6.2

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

@@ -42,7 +42,8 @@ cd .worktree/<request-id>
 - 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`**)
-- Stop worktree services → remove worktree → delete short branch
+- **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
 

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

@@ -27,6 +27,10 @@ For new behavior, fixes, refactors that change product behavior, or architecture
 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

package/.duaer/handoff.json

@@ -0,0 +1,9 @@
+{
+  "schemaVersion": 1,
+  "onWorktreeRemove": {
+    "stop": "Stop any process whose working directory is under the request worktree (dev servers, file watchers, local APIs).",
+    "restartFromPrimary": true,
+    "commands": []
+  },
+  "notes": "After merging into develop (or hotfix main), stop worktree-bound processes, remove .worktree/<id>, then restart from the primary checkout. Add commands such as \"npm run dev\" when this project needs a local service after handoff. Empty commands = stop only; agent still reports handoff."
+}

package/ADOPT.md

@@ -1,49 +1,39 @@
 # Adopt duaer-spec
 
-Install once so the coding agent behaves as a **digital employee**: it runs
-Brief → work → accept **without** the human operating slash commands or CLI.
-
-## Install (human, once)
+## Install
 
 ```bash
 npx duaer-spec init --here
-# pin: npx github:fujiezee/duaer-spec@v0.6.0 duaer init --here
 ```
 
+## Update
+
 ```bash
-npx duaer-spec init --here --method
-npx duaer-spec init --here --ops          # default integration note: develop
+npx duaer-spec update
 ```
 
-Ensure the repo has **`main`** and **`develop`**. Agent ops require both, plus
-`feat/*` / `fix/*` for work. See
-[`docs/agent/branching-and-release.md`](docs/agent/branching-and-release.md).
+That’s it. If you customized local files, glance at `git diff` once.
 
-After that: talk to the agent in plain language. Do not teach them `/duaer-*`.
+Ensure the repo has **`main`** and **`develop`**. See
+[`docs/agent/branching-and-release.md`](docs/agent/branching-and-release.md).
 
-## What gets installed
+Then talk to the agent in plain language.
 
-- Always-on rule: agent runs the autonomous job loop on product work  
-- Playbook skill `duaer-do` (agent follows it; human need not invoke it)  
-- Agent ops: `AGENTS.md`, branching/release docs, mandatory `.worktree/`  
-- Optional step skills for large jobs (agent-only)
+## Options
 
-## Branch model (mandatory)
+```bash
+npx duaer-spec init --here --method
+npx duaer-spec init --here --ops
+npx duaer-spec update --method    # rare; usually omit
+```
 
-| Branch | Role |
-|---|---|
-| `main` | Production / online |
-| `develop` | Day-to-day integration |
-| `feat/<name>` | Features → `develop` |
-| `fix/<name>` | Fixes → `develop` (hotfix via `main` then back to `develop`) |
+## What you get
 
-Go-live: promote `develop` → `main` only when you ask to ship.
+- Autonomous job loop (ask → Brief → work → accept)  
+- `.duaer/handoff.json` + `duaer handoff` after worktree remove  
+- Agent ops: `main` / `develop` / `feat` / `fix` + `.worktree/`  
 
 ## Precedence
 
-1. `AGENTS.md` — how employees operate  
-2. `DUADER.md` / `.duaer/` — how jobs are briefed  
-
-## Updates
-
-`duaer init --force` (review the diff) or pin a tag.
+1. `AGENTS.md`  
+2. `DUADER.md` / `.duaer/`  

package/AGENTS.md

@@ -251,7 +251,9 @@ git worktree prune
 * Use `git branch -d` (not `-D`)
 * Delete only your own worktree and branch
 * Never commit `.worktree/` (ignored)
-* Stop worktree-bound services before remove; restart from primary checkout if needed
+* Stop worktree-bound services before remove; then restart from the primary
+  checkout on **`develop`** via `.duaer/handoff.json` / `duaer handoff [--run]`
+  (mandatory handoff — see [branching-and-release](docs/agent/branching-and-release.md))
 
 ## Development Workflow
 
@@ -267,7 +269,8 @@ git worktree prune
 10. Commit each logical change
 11. Refresh against latest **`develop`** (or **`main`** for hotfix)
 12. Merge into local **`develop`** (hotfix: **`main`**, then back-merge to **`develop`**)
-13. Stop worktree services; remove worktree; delete short branch
+13. Stop worktree services; remove worktree; delete short branch; **handoff**
+    restart on `develop` (`duaer handoff [--run]` / `.duaer/handoff.json`)
 14. Push only when explicitly requested
 15. Promote **`develop` → `main`** only when the user explicitly asks to go online
 

package/CHANGELOG.md

@@ -1,47 +1,32 @@
 # Changelog
 
-## 0.6.0 — 2026-09-15
-
-### Mandatory branch model + release flows
-
-- Required branches: **`main`** (production), **`develop`** (integration),
-  **`feat/*`**, **`fix/*`**
-- New doc: [`docs/agent/branching-and-release.md`](docs/agent/branching-and-release.md)
-  — day-to-day, go-live, feature / bug / hotfix / issue / PR flows
-- Agent ops merge target is **`develop`**; promote to **`main`** only when
-  shipping; hotfixes from `main` then back-merge `develop`
-- Worktree cleanup includes stopping services and restarting on `develop` if needed
-- `duaer init` default `--branch` is `develop`
+## 0.6.2 — 2026-09-15
 
-## 0.5.1 — 2026-09-15
-
-### Mandatory in-repo worktrees
+### Simple update
 
-- Request worktrees **must** live under **`.worktree/<request-id>`**
-- `.worktree/` is gitignored; `duaer init` ensures the ignore rule
+- `npx duaer-spec update` refreshes an existing install (no `--force` flags to remember)
+- Remembers prior init mode from `.duaer/duaer-init.json`
+- README / ADOPT: install + update are each one line
 
-## 0.5.0 — 2026-09-15
+## 0.6.1 — 2026-09-15
 
-### Autonomous digital employee
+### Worktree → develop service handoff
 
-- Humans ask; agents run Brief → work → accept without slash-command ops
+- `.duaer/handoff.json` + `duaer handoff [--run]`
+- Mandatory restart on develop after worktree remove
 
-## 0.4.0 — 2026-09-15
-
-- `/duaer-do` + `duaer status` everyday path (later reframed as agent-internal)
-
-## 0.3.0 — 2026-09-15
+## 0.6.0 — 2026-09-15
 
-- Job handoff policy (`coach` / `strict` / `off`)
+- Mandatory `main` / `develop` / `feat/*` / `fix/*` + release flows
 
-## 0.2.0 — 2026-09-15
+## 0.5.1 — 2026-09-15
 
-- `delivery.json` handoff stamp
+- Mandatory `.worktree/` (gitignored)
 
-## 0.1.1 — 2026-09-15
+## 0.5.0 — 2026-09-15
 
-- Digital-employee positioning
+- Autonomous digital employee
 
-## 0.1.0 — 2026-09-15
+## 0.4.0 — 0.1.0
 
-- First public methodology release
+See git history for earlier notes.

package/README.md

@@ -13,8 +13,13 @@ talk; the employee runs the process.
 npx duaer-spec init --here
 ```
 
-Then use Cursor as usual — describe what you want. No slash-command chain
-required.
+## Update
+
+```bash
+npx duaer-spec update
+```
+
+Then use Cursor as usual — describe what you want.
 
 ## What the employee does (by itself)
 
@@ -38,10 +43,13 @@ everyday human UI.
 Go-live and flows by issue type:
 [`docs/agent/branching-and-release.md`](docs/agent/branching-and-release.md).
 
+**After merge:** `duaer handoff [--run]` restarts local services on `develop`
+(configure commands in `.duaer/handoff.json`).
+
 ## Optional
 
 ```bash
-npx duaer-spec@0.6.0 init --here --method   # method only
+npx duaer-spec init --here --method
 ```
 
 Details: [`ADOPT.md`](ADOPT.md) · Method: [`DUADER.md`](DUADER.md) · Ops: [`AGENTS.md`](AGENTS.md)

package/bin/duaer.mjs

@@ -15,6 +15,7 @@ import {
   statSync,
   writeFileSync,
 } from 'node:fs'
+import { spawn } from 'node:child_process'
 import { dirname, join, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
@@ -26,19 +27,16 @@ const POLICY_MODES = new Set(['off', 'coach', 'strict'])
 
 const USAGE = `duaer — digital-employee delivery (duaer-spec ${PKG.version})
 
-Human (once):
-  duaer init [--here]     Install so the agent works as a digital employee
+Install:  npx duaer-spec init --here
+Update:   npx duaer-spec update
 
-After install: talk to the agent in plain language. Do not operate /duaer-* phases.
+Then talk to the agent in plain language.
 
-Agent / optional diagnostics:
-  duaer status [dir]
-  duaer check | policy | version
+Also:
+  duaer handoff [--run]   Restart services on develop after worktree remove
+  duaer status | check | policy | version | help
 
-Init: --all (default) | --method | --ops | --force | --branch <n> (default: develop) | --here
-
-Example:
-  npx duaer-spec init --here
+Init options: --all | --method | --ops | --force | --branch <n> | --here
 `
 
 function parseArgs(argv) {
@@ -55,20 +53,29 @@ function parseArgs(argv) {
     allJobs: false,
     strict: false,
     policyMode: null,
+    run: false,
+    modeExplicit: false,
   }
   const rest = args.slice(1)
   for (let i = 0; i < rest.length; i++) {
     const a = rest[i]
-    if (a === '--all') out.mode = 'all'
-    else if (a === '--method') out.mode = 'method'
-    else if (a === '--ops') out.mode = 'ops'
-    else if (a === '--force') out.force = true
+    if (a === '--all') {
+      out.mode = 'all'
+      out.modeExplicit = true
+    } else if (a === '--method') {
+      out.mode = 'method'
+      out.modeExplicit = true
+    } else if (a === '--ops') {
+      out.mode = 'ops'
+      out.modeExplicit = true
+    } else if (a === '--force') out.force = true
     else if (a === '--here') out.dir = '.'
     else if (a === '--workplace') out.workplace = true
     else if (a === '--delivery') out.delivery = true
     else if (a === '--job') out.job = true
     else if (a === '--all-jobs') out.allJobs = true
     else if (a === '--strict' || a === '--gate') out.strict = true
+    else if (a === '--run') out.run = true
     else if (a === '--branch') {
       out.branch = rest[++i]
       if (!out.branch) throw new Error('--branch requires a value')
@@ -170,11 +177,37 @@ function writeDefaultPolicy(target, { force }) {
   console.log('  .duaer/delivery-policy.json (mode=coach)')
 }
 
+function defaultHandoff() {
+  return {
+    schemaVersion: 1,
+    onWorktreeRemove: {
+      stop:
+        'Stop any process whose working directory is under the request worktree (dev servers, file watchers, local APIs).',
+      restartFromPrimary: true,
+      commands: [],
+    },
+    notes:
+      'After merging into develop, stop worktree processes, remove .worktree/<id>, then restart from the primary checkout. Add commands such as "npm run dev" when needed.',
+  }
+}
+
+function writeDefaultHandoff(target, { force }) {
+  const path = join(target, '.duaer', 'handoff.json')
+  if (existsSync(path) && !force) {
+    console.log(`skip (exists): ${path}`)
+    return
+  }
+  ensureDir(dirname(path))
+  writeFileSync(path, JSON.stringify(defaultHandoff(), null, 2) + '\n')
+  console.log('  .duaer/handoff.json')
+}
+
 function installMethod(target, opts) {
   console.log('Installing Duaer method…')
   copyPath(join(PKG_ROOT, '.duaer'), join(target, '.duaer'), opts)
   console.log('  .duaer/')
   writeDefaultPolicy(target, opts)
+  writeDefaultHandoff(target, opts)
 
   ensureDir(join(target, '.cursor', 'skills'))
   const skillsRoot = join(PKG_ROOT, '.cursor', 'skills')
@@ -303,10 +336,31 @@ function cmdInit(opts) {
   console.log(`
 Hired.
 
-You: describe work in Cursor (plain language).
-Agent: runs Brief → work → accept by itself — do not operate slash phases.
+Talk to the agent in plain language.
+Later update:  npx duaer-spec update
+`)
+}
 
-Optional diagnostic: duaer status
+function cmdUpdate(opts) {
+  const target = resolve(opts.dir)
+  const marker = readJson(join(target, '.duaer', 'duaer-init.json'), null)
+  if (!marker && !existsSync(join(target, '.duaer')) && !existsSync(join(target, 'DUADER.md'))) {
+    console.log('No duaer install found here. Use: npx duaer-spec init --here')
+    process.exitCode = 1
+    return
+  }
+
+  if (!opts.modeExplicit && marker?.mode && ['all', 'method', 'ops'].includes(marker.mode)) {
+    opts.mode = marker.mode
+  }
+  if (marker?.branch) opts.branch = marker.branch
+  opts.force = true
+
+  console.log(`Updating → ${PKG.version}`)
+  cmdInit(opts)
+  console.log(`
+Updated.
+If you customized constitution / baseline / handoff commands, check git diff once.
 `)
 }
 
@@ -596,6 +650,49 @@ Not a git merge lock.
 `)
 }
 
+function cmdHandoff(opts) {
+  const target = resolve(opts.dir)
+  const cfg = readJson(join(target, '.duaer', 'handoff.json'), defaultHandoff())
+  const block = cfg.onWorktreeRemove || {}
+  const commands = Array.isArray(block.commands) ? block.commands.filter(Boolean) : []
+
+  console.log(`Handoff @ ${target}`)
+  console.log('(worktree → merged develop / hotfix main)\n')
+  console.log('1. Confirm request branch is merged into develop (hotfix: main + back-merge develop)')
+  console.log(`2. Stop: ${block.stop || defaultHandoff().onWorktreeRemove.stop}`)
+  console.log('3. git worktree remove .worktree/<id>  &&  git branch -d feat|fix/<name>')
+  console.log('4. Restart from primary checkout on the merged branch:\n')
+
+  if (!commands.length) {
+    console.log('   (no commands in .duaer/handoff.json)')
+    console.log('   Add e.g. "npm run dev" under onWorktreeRemove.commands')
+    console.log('   If you started a server in the worktree, re-run that same command here.')
+  } else {
+    for (const c of commands) console.log(`   $ ${c}`)
+  }
+
+  if (opts.run) {
+    if (!commands.length) {
+      console.log('\n--run: nothing to start (commands empty).')
+      return
+    }
+    console.log('')
+    for (const c of commands) {
+      const child = spawn(c, {
+        shell: true,
+        cwd: target,
+        detached: true,
+        stdio: 'ignore',
+      })
+      child.unref()
+      console.log(`started (detached) pid=${child.pid}: ${c}`)
+    }
+    console.log('\nServices should now be bound to the primary checkout, not .worktree/.')
+  } else if (commands.length) {
+    console.log('\nTip: duaer handoff --run   # start the commands above in the background')
+  }
+}
+
 function main() {
   let opts
   try {
@@ -611,9 +708,15 @@ function main() {
       case 'init':
         cmdInit(opts)
         break
+      case 'update':
+        cmdUpdate(opts)
+        break
       case 'check':
         cmdCheck(opts)
         break
+      case 'handoff':
+        cmdHandoff(opts)
+        break
       case 'job':
       case 'status':
         cmdJob(opts)

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

@@ -48,9 +48,11 @@ update develop
   → git worktree add .worktree/<id> -b feat|fix/<name> develop
   → work only in that worktree (Duaer job loop as needed)
   → merge into local develop
-  → stop any server started in the worktree
-  → remove .worktree/<id>; delete feat|fix/<name>
-  → (optional) start/restart services from the primary checkout on develop
+  → handoff (mandatory):
+       stop processes bound to the worktree
+       remove .worktree/<id>; delete feat|fix/<name>
+       restart services from the primary checkout on develop
+         (see .duaer/handoff.json / `duaer handoff [--run]`)
   → push develop only if the user asked
 ```
 
@@ -66,15 +68,44 @@ cd .worktree/feat-login
 cd ../..   # primary checkout
 git switch develop
 git merge feat/login
-# stop processes that used .worktree/feat-login
+
+# Handoff — do not skip
+# 1) stop anything started under .worktree/feat-login
 git worktree remove .worktree/feat-login
 git branch -d feat/login
+# 2) restart on develop (primary checkout)
+duaer handoff --run
+# or: npm run dev   # if listed in .duaer/handoff.json
 ```
 
-**After merge / before delete worktree:** if a local service was running from the
-worktree, stop it; if the user still needs it, start it again from the primary
-checkout on **`develop`** (merged tree). Do not expect the old worktree process
-to survive directory removal.
+### Worktree → develop service handoff (mandatory)
+
+Deleting a worktree **removes that directory**. Any server started there will
+break. Agents **must**:
+
+1. Merge the request branch into **`develop`** (hotfix: **`main`**, then
+   back-merge **`develop`**)
+2. **Stop** processes whose cwd is under `.worktree/<id>/`
+3. `git worktree remove .worktree/<id>` and delete the short branch
+4. **Restart** from the **primary checkout** on the merged long-lived branch:
+   - Read `.duaer/handoff.json` → `onWorktreeRemove.commands`
+   - Run `duaer handoff` (prints the plan) or `duaer handoff --run` (starts
+     configured commands in the background from the project root)
+   - If `commands` is empty but the agent started a server in the worktree,
+     restart the **same** command from the primary checkout on `develop`
+   - Tell the user the new service is on the merged branch, not the old worktree
+
+Configure per project by editing `.duaer/handoff.json`, for example:
+
+```json
+{
+  "schemaVersion": 1,
+  "onWorktreeRemove": {
+    "restartFromPrimary": true,
+    "commands": ["npm run dev"]
+  }
+}
+```
 
 ---
 

package/docs/agent/change-checklist.md

@@ -98,7 +98,8 @@ See [spec update guidance](workflow.md#3-spec-update-guidance).
 - [ ] Active job handoff considered by the **agent** (do not require the human to run CLI for routine work).
 - [ ] Branch refreshed against latest `develop` (hotfix: `main`).
 - [ ] Merged into local `develop` (hotfix: `main`, then back-merge `develop`).
-- [ ] Worktree services stopped; worktree removed; short branch deleted.
+- [ ] Worktree services stopped; worktree removed; short branch deleted;
+  **handoff** restart on `develop` (`duaer handoff` / `.duaer/handoff.json`).
 - [ ] Only this request's logical changes included.
 - [ ] Push performed only if the user explicitly asked for this request.
 - [ ] `develop` → `main` promotion only if the user asked to go online.

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

@@ -33,6 +33,8 @@ the table for their app.
 | E2E-006 | `duaer-do` skill describes agent-triggered loop | manual |
 | E2E-007 | Request worktrees use `.worktree/<id>`; `.worktree/` gitignored | manual |
 | 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 |
 
 ## Traceability
 
@@ -46,3 +48,5 @@ the table for their app.
 | E2E-006 | `duaer-do` | Internal playbook |
 | E2E-007 | `.worktree/` + `.gitignore` | Mandatory isolation |
 | 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 |

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "duaer-spec",
-  "version": "0.6.0",
-  "description": "Digital employees: autonomous Spec→work→accept; mandatory main/develop/feat/fix",
+  "version": "0.6.2",
+  "description": "Digital employees: autonomous delivery; main/develop/feat/fix; simple update",
   "type": "module",
   "bin": {
     "duaer": "bin/duaer.mjs",