duaer-spec 0.5.1 → 0.6.1

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

@@ -1,52 +1,57 @@
 ---
-description: duaer-spec agent ops (isolated branch/worktree, commits, push opt-in)
+description: duaer-spec agent ops (develop+main, feat/fix, .worktree, push opt-in)
 alwaysApply: true
 ---
 
 # Agent development workflow
 
-Part of **duaer-spec**. Authoritative over Duaer when they conflict. This
-repository integrates on `main`. Adopting projects may document another
-integration branch in their baseline.
+Part of **duaer-spec**. Authoritative over Duaer when they conflict.
 
-## Language
+## Required branches
 
-Use English for code, identifiers, comments, commits, specs, and docs unless
-the project explicitly overrides.
+| 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 integration branch (`main` here; or project override)
-2. Create a unique branch: `<type>/<short-description>`
-3. Create a dedicated worktree at **`.worktree/<request-id>`** (required — not optional)
+1. Update local **`develop`** (hotfix: **`main`**)
+2. Create `feat/<name>` or `fix/<name>`
+3. Create worktree at **`.worktree/<request-id>`** (required)
 4. Develop only inside that worktree
-5. Never develop in the primary checkout or on the long-lived branch
-6. Never reuse or modify another agent's branch/worktree
-7. Never commit `.worktree/` (must stay gitignored)
+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/<request-id> -b <type>/<request-id> main
+git worktree add .worktree/<request-id> -b feat/<name> develop
 cd .worktree/<request-id>
 ```
+
 ## Immutable habits
 
-- Spec-sync: behavior changes update the relevant project specs/docs (and ADR when architecture/security/contracts change)
+- 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 the project's E2E scenario docs
-- Merge the request branch back into the local integration branch when done
-- Remove the request worktree and delete the merged branch after merge
-- Push only when the user explicitly asks for this request
-
-## GitHub issue intake
-
-If the user links an issue for this repo: verify the claim first; do not implement until it exists. Comment in the issue's language; close when conclusive. An issue link does not authorize push.
+- 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 PR intake
+## GitHub issue / PR intake
 
-If the user links a PR: judge the principle first. If sound, merge that PR (preserve commits); completeness gaps are follow-up after merge. Do not silently reimplement. A PR link does not authorize unrelated pushes or force-push of the contributor branch.
+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
 
@@ -54,4 +59,4 @@ If the user links a PR: judge the principle first. If sound, merge that PR (pres
 type(scope): description
 ```
 
-Types: `feat fix docs test chore refactor perf build ci` — English, imperative, one logical change.
+Types: `feat fix docs test chore refactor perf build ci` — English, imperative.

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

@@ -16,14 +16,22 @@ 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 integration branch, create
-   `<type>/<short-description>`, add worktree at `.worktree/<request-id>`,
+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`
    (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
 

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,36 +7,64 @@ Brief → work → accept **without** the human operating slash commands or CLI.
 
 ```bash
 npx duaer-spec init --here
-# pin: npx github:fujiezee/duaer-spec@v0.5.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 --branch develop
+npx duaer-spec init --here --ops
 ```
 
-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).
+
+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 must run the autonomous job loop on product work  
-- Playbook skill `duaer-do` (agent follows it; human need not invoke it)  
-- Optional step skills for large jobs (agent-only)  
-- Agent ops (`AGENTS.md`) when using `--all` / `--ops`
+- Always-on autonomous job loop  
+- `.duaer/handoff.json` — restart services on **develop** after worktree remove  
+- Agent ops: `AGENTS.md`, branching/release docs, mandatory `.worktree/`  
 
-## Power users / agents
+## Branch model (mandatory)
 
-| Tool | Who uses it |
+| Branch | Role |
 |---|---|
-| `/duaer-do` procedure | Agent (automatic) |
-| `/duaer-specify` … `/duaer-converge` | Agent, when splitting a large job |
-| `duaer status` / `duaer policy` | Optional diagnostics — not required of humans |
+| `main` | Production / online |
+| `develop` | Day-to-day integration |
+| `feat/<name>` | Features → `develop` |
+| `fix/<name>` | Fixes → `develop` (hotfix via `main`) |
+
+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

@@ -35,7 +35,8 @@ until the reported problem has been independently verified.
    close the issue when the conclusion is clear. If verification is
    inconclusive, comment with what was tried and leave the issue open.
 4. If the problem **does** exist: follow the isolated development workflow,
-   implement the smallest coherent fix, merge into local `main`, then comment
+   implement the smallest coherent fix, merge into local `develop` (or
+   hotfix into `main` then back-merge `develop`), then comment
    on the issue and close it.
 5. Write the issue comment in the issue's language (the language of the
    original title and body). Repository docs, code, and commits stay English
@@ -103,6 +104,23 @@ copy limited to the information and actions users need to complete the task:
 * Put rationale and implementation detail in documentation or code comments,
   not in the page UI, unless the user explicitly requests explanatory content.
 
+## Mandatory branch model
+
+Repositories that adopt this agent-ops contract **must** use:
+
+| Branch | Role |
+|---|---|
+| **`main`** | Production / officially online |
+| **`develop`** | Day-to-day integration and debugging |
+| **`feat/<name>`** | Feature work (from `develop` → merge to `develop`) |
+| **`fix/<name>`** | Bug fixes (from `develop` → `develop`; hotfixes from `main` → `main` then back to `develop`) |
+
+Do **not** develop on `main` or `develop`. Full flows (including go-live by
+issue type): [branching-and-release](docs/agent/branching-and-release.md).
+
+**duaer-spec itself** uses this model: integrate on **`develop`**, promote to
+**`main`** only when shipping.
+
 ## Mandatory Isolated Development
 
 Every request must use its own dedicated branch and worktree.
@@ -113,8 +131,9 @@ Landing-blocker commits, if needed, go on top of the author's branch.
 
 Before modifying any file, the agent must:
 
-1. Update the primary checkout's local `main`
-2. Create a unique branch from the updated `main`
+1. Update the primary checkout's local **`develop`** (or **`main`** for a
+   production hotfix)
+2. Create a unique branch from that base (`feat/…` or `fix/…`)
 3. Create a dedicated worktree **under the project** at `.worktree/<request-id>`
 4. Enter that worktree
 5. Only then begin development
@@ -122,13 +141,13 @@ Before modifying any file, the agent must:
 Worktrees live in **`.worktree/`** at the repository root. That directory is
 **mandatory**, not optional, and **must never be committed** (see `.gitignore`).
 
-Example:
+Example (normal feature):
 
 ```bash
-git switch main
+git switch develop
 git pull --ff-only
 mkdir -p .worktree
-git worktree add .worktree/<request-id> -b <type>/<request-id> main
+git worktree add .worktree/<request-id> -b feat/<request-id> develop
 cd .worktree/<request-id>
 ```
 
@@ -136,26 +155,21 @@ 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
 untracked.
-
-**This repository's default integration branch is `main`.** Adopting projects
-may substitute another long-lived branch (for example `develop`); document that
-override in the project baseline. Do not inherit git policy from `examples/`.
-
 ## Multi-Agent Isolation
 
 * Each agent must use its own branch and worktree
 * Never develop directly in the primary checkout
-* Never develop directly on `main` (or the project's integration branch)
+* Never develop directly on `main` or `develop`
 * Never reuse another agent's branch or worktree
 * Never modify files inside another request's worktree
 * Never switch another agent's branch
 * Never delete another agent's branch or worktree
 * Never include unrelated changes from another request
-* Do not commit local environment files, caches, databases, or secrets
+* Do not commit local environment files, caches, databases, secrets, or `.worktree/`
 
-The primary checkout is reserved for synchronizing and merging the integration
-branch. Shared toolchains and caches may be reused when that cannot modify
-tracked files or interfere with another worktree.
+The primary checkout is reserved for synchronizing and merging **`develop`**
+(and **`main`** on promote / hotfix). Shared toolchains and caches may be
+reused when that cannot modify tracked files or interfere with another worktree.
 
 ## Immutable Rules
 
@@ -186,25 +200,33 @@ explicitly requested by the user, **except** for forked third-party pull
 request heads when the project requires local suites before merge. Record the
 result in the pull request comment.
 
-### 4. Merge Back into Local `main`
+### 4. Merge Back into Local `develop` (or hotfix `main`)
 
-After development:
+After normal development:
 
 1. Complete targeted validation
 2. Review the complete diff
 3. Commit all logical changes
-4. Update the request branch with the latest local `main`
+4. Update the request branch with the latest local **`develop`**
 5. Resolve conflicts inside the request worktree
 6. Return to the primary checkout
-7. Merge the request branch into local `main`
+7. Merge the request branch into local **`develop`**
 8. Verify the expected commits are present
-9. Remove the request worktree
-10. Delete the merged request branch
-11. Push only when the user explicitly requested remote publishing for the
+9. Stop any server/process started from the request worktree; if the user still
+   needs a local service, start it from the primary checkout on **`develop`**
+10. Remove the request worktree
+11. Delete the merged request branch
+12. Push only when the user explicitly requested remote publishing for the
     current request
+13. Promote **`develop` → `main`** only when the user explicitly asks to ship /
+    go online (see [branching-and-release](docs/agent/branching-and-release.md))
+
+**Production hotfix:** base and merge into **`main`**, then merge the fix into
+**`develop`** so integration does not regress. Then clean up the worktree.
 
-If another agent has updated `main`, refresh the request branch before merging
-(`git fetch` then `git rebase main`, or merge if project policy requires it).
+If another agent has updated `develop`, refresh the request branch before
+merging (`git fetch` then `git rebase develop`, or merge if project policy
+requires it).
 
 Do not overwrite, reset, or discard changes already merged by another agent.
 
@@ -214,26 +236,30 @@ explicitly requests that exact operation.
 
 ### 5. Clean Up the Request Worktree
 
-Once the request branch is merged into local `main`, remove its worktree and
-delete the merged branch. Never leave a merged worktree on disk.
+Once the request branch is merged into local **`develop`** (or **`main`** for a
+hotfix), remove its worktree and delete the merged branch. Never leave a merged
+worktree on disk.
 
 ```bash
 git worktree remove .worktree/<request-id>
-git branch -d <type>/<request-id>
+git branch -d feat|fix/<request-id>
 git worktree prune
 ```
 
-* Remove only after verifying merge commits are present in local `main`
+* Remove only after verifying merge commits are present on the target long-lived branch
 * The worktree must be clean first
 * Use `git branch -d` (not `-D`)
 * Delete only your own worktree and branch
 * Never commit `.worktree/` (ignored)
+* 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
 
-1. Update local `main`
-2. Create a unique request branch
-3. Create and enter a dedicated worktree
+1. Update local **`develop`** (or **`main`** for hotfix)
+2. Create a unique `feat/` or `fix/` branch
+3. Create and enter `.worktree/<request-id>`
 4. Read the baseline and relevant specs (and Duaer memory when present)
 5. Identify affected specs, ADRs, E2E scenarios, and validation
 6. Implement the smallest coherent change
@@ -241,16 +267,19 @@ git worktree prune
 8. Run targeted, risk-based checks
 9. Review the complete diff
 10. Commit each logical change
-11. Refresh the branch against the latest local `main`
-12. Merge into local `main`
-13. Remove the request worktree and delete the merged branch
-14. Push only when explicitly requested for the current request
+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; **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
 
-Development must not begin before steps 1–3 are complete.
+Development must not begin before isolation steps 1–3 are complete.
 
-For feature work that uses Duaer, prefer
-`specify → plan → tasks → implement → converge` (or the hotfix short path).
-Agent ops in this file still govern isolation, commits, and merge.
+For feature work that uses Duaer, the agent runs the job loop autonomously
+(Brief → work → accept). Agent ops in this file still govern isolation, commits,
+and merge. Branch/release detail:
+[branching-and-release](docs/agent/branching-and-release.md).
 
 ## Commit Format
 
@@ -266,20 +295,20 @@ Allowed types: `feat fix docs test chore refactor perf build ci`
 
 ## Completion Checklist
 
-* [ ] Local `main` was updated before development
-* [ ] A unique request branch was created
-* [ ] A dedicated worktree was created
+* [ ] Local **`develop`** was updated before development (or **`main`** for hotfix)
+* [ ] A unique `feat/` or `fix/` branch was created
+* [ ] A dedicated worktree was created under `.worktree/`
 * [ ] All development occurred inside that worktree
 * [ ] No other agent's branch or worktree was modified
 * [ ] Relevant specs and E2E scenarios were updated
 * [ ] Targeted validation passed or was documented as unnecessary
-* [ ] No secrets, local data, or unrelated changes are included
+* [ ] No secrets, local data, `.worktree/`, or unrelated changes are included
 * [ ] All logical changes were committed
-* [ ] The branch was refreshed against the latest local `main`
-* [ ] Changes were merged into local `main`
-* [ ] The request worktree was removed after the merge
-* [ ] The merged request branch was deleted
+* [ ] The branch was refreshed against the latest local **`develop`** (or hotfix base)
+* [ ] Changes were merged into local **`develop`** (hotfix: **`main`** + back-merge **`develop`**)
+* [ ] Worktree-bound services stopped; worktree removed; short branch deleted
 * [ ] Remote publishing was skipped unless explicitly requested
+* [ ] Promotion **`develop` → `main`** only if the user asked to go online
 * [ ] If pushed, the remote, branch, commit set, and Git identity were verified
 * [ ] If a GitHub issue was linked: verified before work; commented in its
       language; closed when conclusive
@@ -295,7 +324,9 @@ Report:
 * Documentation updated
 * Validation performed or skipped
 * Commit hashes and messages
-* Merge result
+* Merge target (`develop` / `main`) and result
 * Worktree and branch cleanup result
+* Service handoff (stopped in worktree / restarted on develop) if applicable
 * Push target and result, or confirmation that nothing was pushed
+* Whether `main` was promoted (or N/A)
 * Linked GitHub issue / PR outcomes (or N/A)

package/CHANGELOG.md

@@ -1,36 +1,46 @@
 # Changelog
 
-## 0.5.0 — 2026-09-15
+## 0.6.1 — 2026-09-15
 
-### Autonomous digital employee
+### Worktree → develop service handoff
 
-- **Simplicity = humans do not operate the workflow**
-- Always-on rule: on product asks, the agent runs Brief → work → accept itself
-- Do not require `/duaer-do`, phase slash commands, or `duaer status` from humans
-- `duaer-do` is the agent’s internal playbook; install once, then talk
-- README / init / ADOPT / DUADER rewritten around “ask, don’t operate”
+- 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.4.0 — 2026-09-15
+## 0.6.0 — 2026-09-15
 
-### Simple everyday ops
+### Mandatory branch model + release flows
 
-- `/duaer-do` one-shot skill + `duaer status`
-- Step skills demoted to advanced (later reframed as agent-only in 0.5)
+- Required: `main` / `develop` / `feat/*` / `fix/*`
+- [`docs/agent/branching-and-release.md`](docs/agent/branching-and-release.md)
 
-## 0.3.0 — 2026-09-15
+## 0.5.1 — 2026-09-15
+
+- Mandatory `.worktree/` (gitignored)
+
+## 0.5.0 — 2026-09-15
 
-### Job handoff (not a repo lock)
+- Autonomous digital employee (ask, don’t operate phases)
+
+## 0.4.0 — 2026-09-15
+
+- Everyday `/duaer-do` path (later agent-internal)
+
+## 0.3.0 — 2026-09-15
 
-- `coach` / `strict` / `off` policy; active job; `duaer job` / `policy`
+- Job handoff policy
 
 ## 0.2.0 — 2026-09-15
 
-- `delivery.json` + checkable handoff state
+- `delivery.json`
 
 ## 0.1.1 — 2026-09-15
 
-- Digital-employee delivery OS positioning
+- Digital-employee positioning
 
 ## 0.1.0 — 2026-09-15
 
-- First public methodology release
+- First public release

package/README.md

@@ -26,10 +26,33 @@ required.
 Step skills and CLI checks exist for agents and power users — not as the
 everyday human UI.
 
+## Branches (mandatory)
+
+| Branch | Role |
+|---|---|
+| `main` | Production / online |
+| `develop` | Day-to-day integration |
+| `feat/<name>` | Features → `develop` |
+| `fix/<name>` | Fixes → `develop` (hotfix via `main`) |
+
+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.5.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> | --here
+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) {
@@ -48,13 +55,14 @@ function parseArgs(argv) {
     dir: '.',
     mode: 'all',
     force: false,
-    branch: 'main',
+    branch: 'develop',
     workplace: false,
     delivery: false,
     job: false,
     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')
@@ -227,7 +262,13 @@ function installOps(target, opts) {
   console.log('  .cursor/rules/agents-workflow.mdc, ai-ui-copy.mdc')
 
   ensureDir(join(target, 'docs', 'agent'))
-  for (const name of ['workflow.md', 'change-checklist.md', 'e2e-test-plan.md', 'README.md']) {
+  for (const name of [
+    'workflow.md',
+    'change-checklist.md',
+    'e2e-test-plan.md',
+    'branching-and-release.md',
+    'README.md',
+  ]) {
     copyPath(
       join(PKG_ROOT, 'docs', 'agent', name),
       join(target, 'docs', 'agent', name),
@@ -298,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
 `)
 }
 
@@ -590,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 {
@@ -608,6 +693,9 @@ function main() {
       case 'check':
         cmdCheck(opts)
         break
+      case 'handoff':
+        cmdHandoff(opts)
+        break
       case 'job':
       case 'status':
         cmdJob(opts)

package/docs/agent/README.md

@@ -6,6 +6,7 @@ Wins over Duaer and `examples/` when they conflict.
 | Doc | Description |
 |---|---|
 | [workflow.md](workflow.md) | Rules R1–R6, development loop, spec guidance |
+| [branching-and-release.md](branching-and-release.md) | **Required** `main`/`develop`/`feat`/`fix` + go-live by issue type |
 | [change-checklist.md](change-checklist.md) | Finish checklist |
 | [e2e-test-plan.md](e2e-test-plan.md) | E2E scenario catalog template |
 

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

@@ -0,0 +1,207 @@
+# Branching and release flows
+
+> Part of **duaer-spec** agent ops. Precedence: [`AGENTS.md`](../../AGENTS.md) ·
+> [workflow](workflow.md).  
+> Language: English for branch names and docs.
+
+This is **mandatory** for repositories that adopt duaer-spec agent ops.
+Yes: every such repo **must** have a production main branch, a development
+integration branch, feature branches, and bugfix branches.
+
+---
+
+## 1. Required branch model
+
+| Branch | Role | Who merges here |
+|---|---|---|
+| **`main`** | Production / officially online | Only **promotion / release** (or emergency hotfix) |
+| **`develop`** | Day-to-day integration and debugging | Finished `feat/*` and normal `fix/*` |
+| **`feat/<name>`** | One feature / one request | → `develop` when ready to integrate |
+| **`fix/<name>`** | One bugfix / one request | → `develop` (normal); or → `main` then `develop` (hotfix) |
+
+### Rules
+
+1. **Do not develop on `main` or `develop`.** Those are long-lived only.
+2. **Every request** uses a short-lived `feat/` or `fix/` branch **and** a
+   mandatory worktree at `.worktree/<request-id>` (never commit `.worktree/`).
+3. **Default base for new work:** updated local **`develop`**.
+4. **Going online** means promoting `develop` → `main` (or a release PR into
+   `main`) when the user **explicitly** asks to ship / go online.
+5. **Push** is always opt-in; never infer push from “merge” or “done”.
+
+### Naming
+
+```text
+feat/<short-description>   # new capability / improvement
+fix/<short-description>    # defect
+```
+
+Optional types when the project already uses them: `docs/`, `chore/`, `refactor/`,
+`test/`, `ci/` — still branch from `develop`, merge back to `develop` first.
+
+---
+
+## 2. Day-to-day development (feature or normal bug)
+
+```text
+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
+  → 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
+```
+
+Example:
+
+```bash
+git switch develop
+git pull --ff-only
+mkdir -p .worktree
+git worktree add .worktree/feat-login -b feat/login develop
+cd .worktree/feat-login
+# ... implement, commit ...
+cd ../..   # primary checkout
+git switch develop
+git merge 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
+```
+
+### 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"]
+  }
+}
+```
+
+---
+
+## 3. Go-live / online (promote to production)
+
+Use when the user explicitly asks to **ship**, **go online**, **release**, or
+**promote to production**.
+
+```text
+develop is green / accepted for release
+  → update local main and develop
+  → merge develop → main (or open/merge release PR main ← develop)
+  → tag / release notes if the project uses them
+  → push main (and tags) only if the user asked to publish
+  → deploy per project runbook (out of scope for duaer-spec itself)
+```
+
+Never merge a random `feat/*` straight into `main` for a normal feature.
+Features land on **`develop` first**, then ride a promotion to **`main`**.
+
+---
+
+## 4. Flows by problem type
+
+### A. New feature / improvement
+
+| Step | Action |
+|---|---|
+| Branch | `feat/<name>` from **`develop`** |
+| Worktree | `.worktree/<id>` (required) |
+| Integrate | Merge → **`develop`** |
+| Online | Later promotion **`develop` → `main`** when user asks to ship |
+
+### B. Normal bug (not blocking production)
+
+| Step | Action |
+|---|---|
+| Branch | `fix/<name>` from **`develop`** |
+| Worktree | `.worktree/<id>` |
+| Integrate | Merge → **`develop`** |
+| Online | Same as features: ship when promoting `develop` → `main` |
+
+### C. Production hotfix (must go live immediately)
+
+| Step | Action |
+|---|---|
+| Branch | `fix/<name>` from **`main`** |
+| Worktree | `.worktree/<id>` |
+| Online | Merge → **`main`** first (after validation) |
+| Backport | Merge the same fix into **`develop`** (or merge `main` into `develop`) so develop does not regress |
+| Cleanup | Remove worktree; delete `fix/<name>` |
+| Push | Only if the user asked to publish |
+
+### D. Docs / chore / CI-only
+
+Same as **A**: from `develop`, merge to `develop`. Promote with the next
+`develop` → `main` ship unless the user asks for an urgent docs-only release.
+
+### E. Linked GitHub issue
+
+Still: verify the claim (R5), then use **A/B/C** by issue type. Closing the
+issue does not mean push or promote to `main`.
+
+### F. Linked GitHub PR
+
+Judge principle (R6). Merge that PR into the correct target (`develop` for
+normal work, `main` only if it is already a production/hotfix PR). Completeness
+follow-up stays on `develop` unless it is a landing blocker.
+
+---
+
+## 5. What agents must not do
+
+- Develop or commit directly on `main` or `develop`
+- Skip `.worktree/` isolation
+- Merge feature work only to `main` and leave `develop` behind
+- Push, tag, or deploy without an explicit user ask for that action
+- Leave a merged worktree on disk
+- Assume a server started inside a worktree still runs after `worktree remove`
+
+---
+
+## 6. Primary checkout role
+
+The primary clone is for:
+
+- updating and merging **`develop`** (and **`main`** on promote/hotfix)
+- creating/removing `.worktree/<id>` entries
+
+All implementation edits happen inside the request worktree.
+
+---
+
+## 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  

package/docs/agent/change-checklist.md

@@ -43,11 +43,12 @@ See [R6](workflow.md#r6--merge-a-linked-pull-request-whose-principle-is-sound-th
 ## 1. Request Start
 
 - [ ] Existing uncommitted work is identified and preserved.
-- [ ] `origin/main` fetched; local `main` fast-forwarded when clean.
-- [ ] Dedicated `<type>/<short-description>` branch and worktree created from
-  that commit under **`.worktree/<request-id>`** (mandatory; never commit `.worktree/`).
+- [ ] `origin/develop` fetched; local `develop` fast-forwarded when clean
+  (hotfix: `main`).
+- [ ] Dedicated `feat/` or `fix/` branch and worktree under
+  **`.worktree/<request-id>`** (mandatory; never commit `.worktree/`).
 - [ ] Shared toolchains/caches reused where safe; mutable state stays local.
-- [ ] Current branch is not `main` before implementation begins.
+- [ ] Current branch is not `main` or `develop` before implementation begins.
 
 ---
 
@@ -95,10 +96,13 @@ See [spec update guidance](workflow.md#3-spec-update-guidance).
 ## 6. Merge / PR
 
 - [ ] Active job handoff considered by the **agent** (do not require the human to run CLI for routine work).
-- [ ] Branch refreshed against latest `main`.
-- [ ] Merged into local `main` (and/or remote PR/MR when required).
+- [ ] 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;
+  **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.
 
 ---
 
@@ -117,15 +121,16 @@ See [spec update guidance](workflow.md#3-spec-update-guidance).
 
 | # | Gate | Source |
 |---|---|---|
-| 1 | Branch + worktree from up-to-date `main` | [R4](workflow.md#r4--request-branch--worktree--merge-gate) |
+| 1 | Branch + `.worktree/` from up-to-date `develop` (hotfix: `main`) | [R4](workflow.md#r4--request-branch--worktree--merge-gate) · [branching](branching-and-release.md) |
 | 2 | Change implements the planned work | [Development loop](workflow.md#2-development-loop) |
 | 3 | Impacted specs updated | [R1](workflow.md#r1--spec-first--spec-sync) |
 | 4 | E2E docs updated or confirmed unnecessary | [R3](workflow.md#r3--e2e-coverage-doc) |
 | 5 | Targeted validation done or waived with reason | Development loop |
-| 5a | Active job handoff via `duaer job` (coach/strict) | Delivery OS — not a git lock |
+| 5a | Active job handoff by the agent (coach/strict) | Delivery OS — not a git lock |
 | 6 | Conventional commits | [R2](workflow.md#r2--commit-per-change) |
-| 7 | No secrets or local data | [§4](workflow.md#4-what-never-to-commit) |
-| 8 | Merged into `main`; worktree and branch removed | [R4](workflow.md#r4--request-branch--worktree--merge-gate) · [§6.1](#61-merge-cleanup) |
+| 7 | No secrets, local data, or `.worktree/` | [§4](workflow.md#4-what-never-to-commit) |
+| 8 | Merged to `develop` (hotfix: `main` + back-merge); worktree cleaned | [R4](workflow.md#r4--request-branch--worktree--merge-gate) |
+| 8a | `develop` → `main` only if user asked to go online | [branching-and-release](branching-and-release.md) |
 | 9 | Linked issue: verified, commented, closed when conclusive | [R5](workflow.md#r5--verify-linked-github-issues-before-work-then-reply-and-close) |
 | 10 | Linked PR: principle reviewed; merged when sound; follow-up after | [R6](workflow.md#r6--merge-a-linked-pull-request-whose-principle-is-sound-then-follow-up) |
 

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

@@ -31,6 +31,10 @@ the table for their app.
 | E2E-004 | Default `coach`: unfinished job — agent must not claim done | manual |
 | E2E-005 | Converge stamps `accepted`; agent reports ready for review | manual |
 | 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
 
@@ -42,3 +46,7 @@ the table for their app.
 | E2E-004 | policy coach | Handoff etiquette |
 | E2E-005 | `delivery.json` | Accept stamp |
 | 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/docs/agent/workflow.md

@@ -41,27 +41,29 @@ handling. They cannot be relaxed without explicit human override.
 
 ### R4 — Request branch + worktree + merge gate
 
-> **Every new request starts from `main` in a dedicated worktree on a dedicated
-> branch and finishes only after it is merged into `main`.**
+> **Every new request starts from `develop` (hotfix: `main`) in a dedicated
+> `.worktree/<id>` on a `feat/*` or `fix/*` branch, and finishes after merge
+> into that long-lived target. Going online is a separate `develop` → `main`
+> promotion when the user asks to ship.**
 
 - Before editing: preserve existing uncommitted work; fetch and fast-forward
-  local `main` when clean; create a new request branch and a dedicated worktree
-  at **`.worktree/<request-id>`** under the project root. Worktrees are
+  local **`develop`** when clean (hotfix: **`main`**); create a new request
+  branch and worktree at **`.worktree/<request-id>`**. Worktrees are
   **mandatory**. Never stash or overwrite another agent's work merely to start.
-- Name branches `<type>/<short-description>` (for example `feat/adopt-docs`).
-- Do not implement in the primary checkout or reuse another request's worktree.
+- Name branches `feat/<short-description>` or `fix/<short-description>`.
+- Do not implement in the primary checkout or on `main` / `develop`.
 - Keep `.worktree/` gitignored — never commit request worktrees.
-- Reuse shared toolchains and caches where safe; keep mutable or
-  concurrency-sensitive state worktree-local and ignored.
-- After validation: merge into local `main` (or via PR/MR when required), then
-  remove the request worktree and delete the merged branch immediately.
-- Push only when the user explicitly requests remote publishing for this
-  request.
+- After validation: merge into local **`develop`** (hotfix: **`main`**, then
+  back-merge **`develop`**), stop worktree-bound services, remove the worktree,
+  delete the short branch.
+- Push only when the user explicitly requests remote publishing.
+- Promote **`develop` → `main`** only when the user explicitly asks to go online.
 
-Adopting projects may replace `main` with another integration branch; document
-it in the project baseline. **duaer-spec itself uses `main`.** Example overlays
-under `examples/` do not change this repo's default.
+Full matrix by issue type:
+[branching-and-release](branching-and-release.md).
 
+**duaer-spec itself** requires `main` + `develop` + `feat/*` + `fix/*`.
+Example overlays under `examples/` do not change this.
 ### R5 — Verify linked GitHub issues before work, then reply and close
 
 > **A linked GitHub issue is not a task until the reported problem is shown to
@@ -84,16 +86,18 @@ unrelated pushes.
 ## 2. Development Loop
 
 1. **Intake** — If an issue or PR is linked, complete R5 / R6 first.
-2. **Isolate** — Update `main`, create branch + worktree (R4).
+2. **Isolate** — Update `develop` (hotfix: `main`), create `feat|fix` + `.worktree/` (R4).
 3. **Orient** — Read baseline, relevant specs, and Duaer memory when present.
-4. **Specify (when using Duaer)** — Feature / hotfix specs before coding.
+4. **Specify (when using Duaer)** — Agent runs Brief → work → accept autonomously.
 5. **Implement** — Smallest coherent change; update specs alongside (R1).
 6. **Verify** — Targeted checks; E2E runs only if the user asks (except fork
    landing rules in `AGENTS.md`).
 7. **Commit** — One logical change per commit (R2).
-8. **Merge & clean** — Refresh against `main`, merge, remove worktree (R4 / R5).
-9. **Report** — Use the Final Report section in `AGENTS.md`.
-
+8. **Merge & clean** — Merge to `develop` (hotfix: `main` + back-merge), stop
+   worktree services, remove worktree (R4).
+9. **Go online** — Only if asked: promote `develop` → `main`
+   ([branching-and-release](branching-and-release.md)).
+10. **Report** — Use the Final Report section in `AGENTS.md`.
 ---
 
 ## 3. Spec Update Guidance
@@ -114,6 +118,7 @@ when changing duaer-spec's own agent-ops contract.
 
 - Secrets, tokens, credentials, private keys
 - Local databases, caches, build artifacts, `node_modules/`
+- `.worktree/` (mandatory request worktrees)
 - Machine-specific paths or environment files with secrets
 - Unrelated changes from another request or agent
 

package/docs/baseline.md

@@ -1,10 +1,22 @@
 # Baseline (project-specific)
 
 Frozen decisions for the adopting project: language, stack, architecture
-boundaries, and integration-branch override (if not `main`).
+boundaries, and branch model.
 
-**duaer-spec itself:** English docs and commits; integration branch `main`;
-no application runtime.
+## Branch model (mandatory)
 
-When you copy agent ops into another repository, replace this file with that
-product's baseline (or point agents at the project's existing baseline path).
+| Branch | Role |
+|---|---|
+| `main` | Production / officially online |
+| `develop` | Day-to-day integration |
+| `feat/<name>` | Features |
+| `fix/<name>` | Bug fixes |
+
+See [branching-and-release](agent/branching-and-release.md).
+
+**duaer-spec itself:** English docs and commits; integrate on **`develop`**;
+promote to **`main`** when shipping; no application runtime.
+
+When you copy agent ops into another repository, keep this branch model unless
+the project explicitly documents a justified exception in an ADR (not
+recommended).

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "duaer-spec",
-  "version": "0.5.1",
-  "description": "Digital employees that run Spec→work→accept themselves — humans just ask",
+  "version": "0.6.1",
+  "description": "Digital employees: autonomous delivery; main/develop/feat/fix; worktree handoff",
   "type": "module",
   "bin": {
     "duaer": "bin/duaer.mjs",