duaer-spec 0.5.0 → 0.5.1

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

@@ -14,16 +14,23 @@ integration branch in their baseline.
 Use English for code, identifiers, comments, commits, specs, and docs unless
 the project explicitly overrides.
 
-## Isolated development
+## 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 and develop only there
-4. Never develop in the primary checkout or on the long-lived branch
-5. Never reuse or modify another agent's branch/worktree
-
+3. Create a dedicated worktree at **`.worktree/<request-id>`** (required — not optional)
+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)
+
+```bash
+mkdir -p .worktree
+git worktree add .worktree/<request-id> -b <type>/<request-id> main
+cd .worktree/<request-id>
+```
 ## Immutable habits
 
 - Spec-sync: behavior changes update the relevant project specs/docs (and ADR when architecture/security/contracts change)

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

@@ -16,6 +16,9 @@ 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>`,
+   work only there. Never skip the worktree. Never commit `.worktree/`.
 1. **Silently follow** the procedure in `.cursor/skills/duaer-do/SKILL.md`
    (assign Brief → light tasks → implement → converge → handoff line).
 2. Do **not** wait for `/duaer-do` or any other skill invocation.

package/AGENTS.md

@@ -115,20 +115,27 @@ Before modifying any file, the agent must:
 
 1. Update the primary checkout's local `main`
 2. Create a unique branch from the updated `main`
-3. Create a dedicated worktree for that branch
-4. Enter the new worktree
+3. Create a dedicated worktree **under the project** at `.worktree/<request-id>`
+4. Enter that worktree
 5. Only then begin development
 
+Worktrees live in **`.worktree/`** at the repository root. That directory is
+**mandatory**, not optional, and **must never be committed** (see `.gitignore`).
+
 Example:
 
 ```bash
 git switch main
 git pull --ff-only
-git worktree add ../worktrees/<request-id> -b <type>/<request-id> main
-cd ../worktrees/<request-id>
+mkdir -p .worktree
+git worktree add .worktree/<request-id> -b <type>/<request-id> main
+cd .worktree/<request-id>
 ```
 
 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
@@ -211,7 +218,7 @@ Once the request branch is merged into local `main`, remove its worktree and
 delete the merged branch. Never leave a merged worktree on disk.
 
 ```bash
-git worktree remove ../worktrees/<request-id>
+git worktree remove .worktree/<request-id>
 git branch -d <type>/<request-id>
 git worktree prune
 ```
@@ -220,6 +227,7 @@ git worktree prune
 * The worktree must be clean first
 * Use `git branch -d` (not `-D`)
 * Delete only your own worktree and branch
+* Never commit `.worktree/` (ignored)
 
 ## Development Workflow
 

package/bin/duaer.mjs

@@ -194,6 +194,21 @@ function installMethod(target, opts) {
 
   copyPath(join(PKG_ROOT, 'DUADER.md'), join(target, 'DUADER.md'), opts)
   console.log('  DUADER.md')
+  ensureWorktreeGitignore(target)
+}
+
+function ensureWorktreeGitignore(target) {
+  const gi = join(target, '.gitignore')
+  const line = '.worktree/'
+  let text = existsSync(gi) ? readFileSync(gi, 'utf8') : ''
+  if (text.split(/\r?\n/).some((l) => l.trim() === line)) {
+    console.log('  .gitignore already ignores .worktree/')
+    return
+  }
+  if (text.length && !text.endsWith('\n')) text += '\n'
+  text += `# duaer-spec: mandatory request worktrees (do not commit)\n${line}\n`
+  writeFileSync(gi, text, 'utf8')
+  console.log('  .gitignore ← .worktree/')
 }
 
 function installOps(target, opts) {
@@ -220,6 +235,7 @@ function installOps(target, opts) {
     )
   }
   console.log('  docs/agent/')
+  ensureWorktreeGitignore(target)
 
   const baselineSrc = join(PKG_ROOT, 'docs', 'baseline.md')
   const baselineDst = join(target, 'docs', 'baseline.md')

package/docs/agent/change-checklist.md

@@ -45,7 +45,7 @@ See [R6](workflow.md#r6--merge-a-linked-pull-request-whose-principle-is-sound-th
 - [ ] 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.
+  that commit 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.
 

package/docs/agent/workflow.md

@@ -45,10 +45,12 @@ handling. They cannot be relaxed without explicit human override.
 > branch and finishes only after it is merged into `main`.**
 
 - Before editing: preserve existing uncommitted work; fetch and fast-forward
-  local `main` when clean; create a new request branch and worktree from that
-  commit. Never stash or overwrite another agent's work merely to start.
+  local `main` when clean; create a new request branch and a dedicated worktree
+  at **`.worktree/<request-id>`** under the project root. 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.
+- 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "duaer-spec",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "Digital employees that run Spec→work→accept themselves — humans just ask",
   "type": "module",
   "bin": {