duaer-spec 0.6.0 → 0.6.1

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

@@ -7,26 +7,51 @@ Brief → work → accept **without** the human operating slash commands or CLI.
 
 ```bash
 npx duaer-spec init --here
-# pin: npx github:fujiezee/duaer-spec@v0.6.0 duaer init --here
+# pin: npx github:fujiezee/duaer-spec@v0.6.1 duaer init --here
 ```
 
 ```bash
 npx duaer-spec init --here --method
-npx duaer-spec init --here --ops          # default integration note: develop
+npx duaer-spec init --here --ops
 ```
 
-Ensure the repo has **`main`** and **`develop`**. Agent ops require both, plus
-`feat/*` / `fix/*` for work. See
+Ensure the repo has **`main`** and **`develop`**. See
 [`docs/agent/branching-and-release.md`](docs/agent/branching-and-release.md).
 
-After that: talk to the agent in plain language. Do not teach them `/duaer-*`.
+After that: talk to the agent in plain language.
+
+## Updating an existing install
+
+Already ran `duaer init` before? Refresh managed files:
+
+```bash
+npx duaer-spec@latest init --here --force
+```
+
+Then:
+
+1. **Review the git diff** — keep your project-specific edits to
+   `.duaer/memory/constitution.md`, `project-context.md`, `docs/baseline.md`,
+   and especially **`.duaer/handoff.json` `commands`** (your restart scripts).
+2. Restore any local overrides you still need.
+3. Confirm `.gitignore` still contains `.worktree/`.
+4. No need to re-learn slash commands — talk to the agent as before.
+
+Pin a version if you prefer:
+
+```bash
+npx duaer-spec@0.6.1 init --here --force
+# or
+npx github:fujiezee/duaer-spec@v0.6.1 duaer init --here --force
+```
+
+Adopters are **not** auto-updated; re-run init when you want a newer revision.
 
 ## What gets installed
 
-- Always-on rule: agent runs the autonomous job loop on product work  
-- Playbook skill `duaer-do` (agent follows it; human need not invoke it)  
+- Always-on autonomous job loop  
+- `.duaer/handoff.json` — restart services on **develop** after worktree remove  
 - Agent ops: `AGENTS.md`, branching/release docs, mandatory `.worktree/`  
-- Optional step skills for large jobs (agent-only)
 
 ## Branch model (mandatory)
 
@@ -35,15 +60,11 @@ After that: talk to the agent in plain language. Do not teach them `/duaer-*`.
 | `main` | Production / online |
 | `develop` | Day-to-day integration |
 | `feat/<name>` | Features → `develop` |
-| `fix/<name>` | Fixes → `develop` (hotfix via `main` then back to `develop`) |
+| `fix/<name>` | Fixes → `develop` (hotfix via `main`) |
 
-Go-live: promote `develop` → `main` only when you ask to ship.
+After merge: **`duaer handoff [--run]`** (stop worktree services → restart on develop).
 
 ## 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.

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,42 +1,41 @@
 # Changelog
 
+## 0.6.1 — 2026-09-15
+
+### Worktree → develop service handoff
+
+- Mandatory handoff after merge: stop worktree-bound processes, remove
+  `.worktree/<id>`, restart from primary checkout on `develop`
+- `.duaer/handoff.json` configures restart commands (e.g. `npm run dev`)
+- CLI: `duaer handoff` / `duaer handoff --run`
+- Docs: update path for existing installs (`init --force` + review diff)
+
 ## 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`
+- Required: `main` / `develop` / `feat/*` / `fix/*`
+- [`docs/agent/branching-and-release.md`](docs/agent/branching-and-release.md)
 
 ## 0.5.1 — 2026-09-15
 
-### Mandatory in-repo worktrees
-
-- Request worktrees **must** live under **`.worktree/<request-id>`**
-- `.worktree/` is gitignored; `duaer init` ensures the ignore rule
+- Mandatory `.worktree/` (gitignored)
 
 ## 0.5.0 — 2026-09-15
 
-### Autonomous digital employee
-
-- Humans ask; agents run Brief → work → accept without slash-command ops
+- Autonomous digital employee (ask, don’t operate phases)
 
 ## 0.4.0 — 2026-09-15
 
-- `/duaer-do` + `duaer status` everyday path (later reframed as agent-internal)
+- Everyday `/duaer-do` path (later agent-internal)
 
 ## 0.3.0 — 2026-09-15
 
-- Job handoff policy (`coach` / `strict` / `off`)
+- Job handoff policy
 
 ## 0.2.0 — 2026-09-15
 
-- `delivery.json` handoff stamp
+- `delivery.json`
 
 ## 0.1.1 — 2026-09-15
 
@@ -44,4 +43,4 @@
 
 ## 0.1.0 — 2026-09-15
 
-- First public methodology release
+- First public release

package/README.md

@@ -38,10 +38,21 @@ 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`).
+
+## Updating
+
+```bash
+npx duaer-spec@latest init --here --force   # review diff; keep handoff commands
+```
+
+Details: [`ADOPT.md`](ADOPT.md)#updating-an-existing-install
+
 ## Optional
 
 ```bash
-npx duaer-spec@0.6.0 init --here --method   # method only
+npx duaer-spec@0.6.1 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,25 @@ 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
+Human (once / update):
+  duaer init [--here] [--force]   Install or refresh into a project
 
-After install: talk to the agent in plain language. Do not operate /duaer-* phases.
+After install: talk to the agent in plain language.
 
-Agent / optional diagnostics:
+Agent / optional:
+  duaer handoff [dir] [--run]   After merge: print/restart services on develop
   duaer status [dir]
   duaer check | policy | version
 
 Init: --all (default) | --method | --ops | --force | --branch <n> (default: develop) | --here
 
+Update existing install:
+  npx duaer-spec@latest init --here --force
+  # then review git diff; keep project-specific constitution / baseline / handoff commands
+
 Example:
   npx duaer-spec init --here
+  duaer handoff --run
 `
 
 function parseArgs(argv) {
@@ -55,6 +62,7 @@ function parseArgs(argv) {
     allJobs: false,
     strict: false,
     policyMode: null,
+    run: false,
   }
   const rest = args.slice(1)
   for (let i = 0; i < rest.length; i++) {
@@ -69,6 +77,7 @@ function parseArgs(argv) {
     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 +179,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')
@@ -304,9 +339,10 @@ function cmdInit(opts) {
 Hired.
 
 You: describe work in Cursor (plain language).
-Agent: runs Brief → work → accept by itself — do not operate slash phases.
+Agent: runs Brief → work → accept; uses develop + .worktree/; after merge runs handoff.
 
-Optional diagnostic: duaer status
+Update later: npx duaer-spec@latest init --here --force  (review the diff)
+Handoff:      duaer handoff [--run]   # restart services on develop after worktree remove
 `)
 }
 
@@ -596,6 +632,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 {
@@ -614,6 +693,9 @@ function main() {
       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 | ADOPT documents `init --force` update path for existing installs | 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 | `ADOPT.md` Updating | Existing installs |

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.1",
+  "description": "Digital employees: autonomous delivery; main/develop/feat/fix; worktree handoff",
   "type": "module",
   "bin": {
     "duaer": "bin/duaer.mjs",