aligndev 0.27.0 → 0.28.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -53,22 +53,13 @@ Setting up a workspace takes a while, so tell the user it started before you sta
53
53
  {{#codingAgent}}
54
54
  ## Step 2 — Decide the workplace
55
55
 
56
- {{#hasGuide}}
57
- The project has **workspace tooling** when DEVELOPERS_PATH describes workspaces.
58
- {{/hasGuide}}
59
- {{#noGuide}}
60
- The project has no **workspace tooling**.
61
- {{/noGuide}}
62
-
63
56
  The workplace is the first case that matches:
64
57
 
65
- 1. **The user's request or instructions name the place** — a directory, a branch, a workspace: work there.
58
+ 1. **The user's request or instructions name the place** — a directory, a branch, a workspace: work there. For a directory, post its banner and go to Step 5. For a branch, Step 4 finds or attaches that branch rather than choosing another ticket branch.
66
59
  2. **The session's branch carries TICKET_ID** — work in place. Skip Steps 3 and 4: post the `[WORKSPACE]` banner (format in Step 4) with the session's worktree and branch and `Status: ready`, then go to Step 5.
67
60
  3. **The session's branch is long-lived** — the default branch, or a name such as `main`, `master`, `develop`, `release` or `production`: open or create the ticket's workspace in Step 4, without asking.
68
61
  4. **Any other branch**, one carrying another ticket's ID included — end the turn on one message asking where to work. On the answer, "here" means the session's worktree as it is, handled as in case 2; a branch or a directory the user names falls under case 1.
69
62
 
70
- Without workspace tooling, case 3 also ends the turn on that question, and "here" means the ticket's branch in the session's worktree: `git switch <branch>` when it exists, else a fast-forward of the base branch, then `git switch -c {TICKET_ID}/{1-3-words}`. The banner then follows case 2.
71
-
72
63
  ## Step 3 — Post the setup signal
73
64
 
74
65
  Post the signal only when Step 2 opens or creates a workspace.
@@ -100,32 +91,22 @@ That single call is the whole exception. The post right after it, and every one
100
91
  {{/openclaw}}
101
92
 
102
93
  {{#openclaw}}
103
- ## Step 4 — Set up the project workspace (worktree, branch, dev server)
94
+ ## Step 4 — Set up the project workspace (worktree and branch)
104
95
  {{/openclaw}}
105
96
  {{#codingAgent}}
106
- ## Step 4 — Set up the workspace (worktree, branch, dev server)
97
+ ## Step 4 — Set up the workspace (worktree and branch)
107
98
  {{/codingAgent}}
108
99
 
109
100
  {{#openclaw}}
110
- A project runs in **main-worktree mode** when DEVELOPERS_PATH is missing or has no workspaces section. Its main worktree at PROJECT_PATH is its only workspace, used by one working thread at a time. "Main-worktree mode" below adapts this step, and wherever the playbook names the linked workspace, you use PROJECT_PATH.
101
+ When the user named a directory, or a recorded workplace's branch already carries TICKET_ID, use that worktree as it is: post its banner and go to Step 5. When the user named a branch, find or attach it below rather than choosing another ticket branch.
111
102
  {{/openclaw}}
112
103
 
113
- {{#openclaw}}
114
- Otherwise, the workspace tooling owns worktrees. Run its main-worktree commands from PROJECT_PATH. Create, reuse, and tear worktrees down through its commands only — never `git worktree add`/`remove`/`prune`, never `rm -rf` on a worktree directory, never a branch checked out by hand outside a workspace. A worktree the tooling doesn't know about is invisible to every other session.
115
- {{/openclaw}}
116
- {{#codingAgent}}
117
- The workspace tooling owns worktrees. Run its main-worktree commands from PROJECT_PATH. Create, reuse, and tear worktrees down through its commands only — never `git worktree add`/`remove`/`prune`, never `rm -rf` on a worktree directory, never a branch checked out by hand outside a workspace. A worktree the tooling doesn't know about is invisible to every other session.
118
- {{/codingAgent}}
104
+ The project has workspace tooling when its developer guide documents one, whatever the implementation. Use it when present; otherwise use `{{ALIGNDEV}} worktree list/add/remove`. Never bypass it with raw `git worktree add`/`remove`/`prune` or directory deletion.
119
105
 
120
- First, fetch remote refs from PROJECT_PATH with `git fetch --prune`. Then check what already exists for the {TICKET_ID} — two checks, both required:
106
+ First, select the base ref from the project or user instructions, otherwise use the base branch's configured upstream. Use the local base ref when the repository has no remote; ask when the choice is unclear. Fetch its remote from PROJECT_PATH with `git fetch --prune <remote>` when applicable, and retain the selected base ref for creation and synchronization. Then check what already exists for the explicitly selected branch, or otherwise for {TICKET_ID} — two checks, both required:
121
107
 
122
108
  - **Branch**: from PROJECT_PATH, list the branches, local and remote (`git branch -a`), and look for one matching the {TICKET_ID}. No match means no branch yet — an answer, not a failure.
123
- {{#openclaw}}
124
- - **Registered workspaces**: `DEVELOPERS.md` names the project's guide command (`workspace --guide`, with the project's own runner). It gives the commands to **list registered workspaces** and to **set up a workspace** — on an existing branch, or on a new one. Use them.
125
- {{/openclaw}}
126
- {{#codingAgent}}
127
- - **Registered workspaces**: the workspace tooling's guide command (`workspace --guide`, with the project's own runner) gives the commands to **list registered workspaces** and to **set up a workspace** — on an existing branch, or on a new one. Use them.
128
- {{/codingAgent}}
109
+ - **Worktrees**: the project's workspace list command, or `{{ALIGNDEV}} worktree list --json` from PROJECT_PATH. Report a missing, locked, or prunable entry instead of repairing it.
129
110
 
130
111
  Never assume the branch is new; `git worktree list` alone does not answer the branch question.
131
112
 
@@ -133,13 +114,17 @@ Whenever a branch exists, you work from its workspace — a status request inclu
133
114
 
134
115
  1. **Branch + workspace already registered** → use it (no setup needed).
135
116
  2. **Branch exists (local or remote), no workspace** → set up a workspace on the existing branch (don't create a new branch).
136
- 3. **No branch** → for a status request, end the turn on a message reporting that no workspace or code work exists, with any request, spec, and summary files listed by the ticket preflight; create nothing. Any other request is new-work intent: in PROJECT_PATH, fast-forward the base branch from its freshly fetched remote ref so the new branch starts from the latest base, then set up a workspace on a new branch. Name it `{TICKET_ID}/{1-3-words}`, deriving the short description from the request. A fast-forward that brought in new commits leaves the main worktree stale, and no later step refreshes it: once the workspace is up, run the "Refreshing the workspace after a branch refresh" flow on the main worktree at PROJECT_PATH.
117
+ 3. **No branch** → for a status request, end the turn on a message reporting that no workspace or code work exists, with any request, spec, and summary files listed by the ticket preflight; create nothing. Any other request is new-work intent: name a new branch `{TICKET_ID}/{1-3-words}`, deriving the short description from the request. Start it from the selected base ref. Creating from that ref requires no checkout or clean main worktree.
118
+
119
+ With workspace tooling, delegate the setup through its documented commands. Without it, run `{{ALIGNDEV}} worktree add` yourself, before any coding delegation, on an absolute sibling path derived from PROJECT and the branch (branch slashes become dashes): `{{ALIGNDEV}} worktree add <path> <existing-branch> --json` for sub-path 2, `{{ALIGNDEV}} worktree add <path> -b <new-branch> <explicit-base-ref> --json` for sub-path 3.
120
+
121
+ The command refuses an occupied path, a dangling symlink included, a branch checked out elsewhere, an ambiguous remote branch, and missing or project-tracked plans. Relay the refusal instead of working around it: reuse the path it reports for an occupied branch, ask the user about an ambiguous remote, run `{{ALIGNDEV}} guide work-files-setup` for plans and retry; never force a second checkout or invent another path. It returns once the worktree and its work files are ready. Report its warnings, such as a tracked `.local` that stays branch-local, and on a late failure relay its recovery instructions and delete nothing.
137
122
 
138
123
  {{#openclaw}}
139
- The moment you have the linked workspace path — attached (sub-path 1) or freshly set up (2, 3) — post the `[WORKSPACE]` banner, before any `git` inspection or prose, and **include it again in the message you end the turn with**: the early post may not deliver on every surface, the final message always does (on Discord the Step 3 rename post also delivers). `workspace setup` blocks until the bootstrap reaches `ready` or `failed`; run it in the foreground (no `background` option) and report the state it returns. Run subsequent Git commands and `{{ALIGNDEV}} code` from that linked workspace, never PROJECT_PATH, except in main-worktree mode.
124
+ The moment you have the linked workspace path — attached (sub-path 1) or freshly set up (2, 3) — post the `[WORKSPACE]` banner, before any `git` inspection or prose, and **include it again in the message you end the turn with**: the early post may not deliver on every surface, the final message always does (on Discord the Step 3 rename post also delivers). Run the selected setup command in the foreground (no `background` option) and report the state it returns. Run subsequent Git commands and `{{ALIGNDEV}} code` from that linked workspace, never PROJECT_PATH, unless the user explicitly chose in-place work.
140
125
  {{/openclaw}}
141
126
  {{#codingAgent}}
142
- The moment you have the workplace — in place, attached (sub-path 1) or freshly set up (2, 3) — post the `[WORKSPACE]` banner, before any `git` inspection or prose. `workspace setup` blocks until the bootstrap reaches `ready` or `failed`; run it in the foreground and report the state it returns. Run subsequent Git commands and `{{ALIGNDEV}} code` from the workplace.
127
+ The moment you have the workplace — in place, attached (sub-path 1) or freshly set up (2, 3) — post the `[WORKSPACE]` banner, before any `git` inspection or prose. Run the selected setup command in the foreground and report the state it returns. Run subsequent Git commands and `{{ALIGNDEV}} code` from the workplace.
143
128
  {{/codingAgent}}
144
129
 
145
130
  {{#openclaw}}
@@ -157,25 +142,7 @@ Branch: `{branch}`
157
142
  Status: {running | ready | failed}
158
143
  ```
159
144
 
160
- The lines below the tag report the workspace: after `Status:`, add what the setup output gives that the user can act on.
161
-
162
- {{#openclaw}}
163
- ### Main-worktree mode
164
- {{/openclaw}}
165
-
166
- {{#openclaw}}
167
- The branch check applies; the registered-workspace check does not. Before any checkout, claim the main worktree. It is free when it is on the default branch with a clean `git status`, or already on this thread's {TICKET_ID} branch. Otherwise, end the turn telling the user the project is busy: name the checked-out branch and the uncommitted changes, and change nothing.
168
- {{/openclaw}}
169
-
170
- {{#openclaw}}
171
- On a free main worktree, the sub-paths above run in PROJECT_PATH with plain `git switch`:
172
-
173
- 1. **Already on the branch** → use it.
174
- 2. **Branch exists, not checked out** → `git switch <branch>`.
175
- 3. **No branch** → a status request ends as above. Otherwise, fast-forward the base branch as above, then `git switch -c {TICKET_ID}/{1-3-words}`.
176
-
177
- The `[WORKSPACE]` banner names the main worktree: `Worktree:` is the directory name of PROJECT_PATH, and `Status:` is `ready`.
178
- {{/openclaw}}
145
+ The lines below the tag report the workspace: after `Status:`, add what the setup output gives that the user can act on. For a worktree from `{{ALIGNDEV}} worktree add`, say that `ready` covers the worktree and work files only, and delegate the repository's documented install/build/test preparation separately before coding needs it.
179
146
 
180
147
  {{#openclaw}}
181
148
  ## Step 5 — Sync an existing branch on takeover (sub-paths 1 & 2)
@@ -188,12 +155,12 @@ The `[WORKSPACE]` banner names the main worktree: `Worktree:` is the directory n
188
155
  In place on an existing branch, fetch first. A fast-forward of the branch onto its remote counterpart or onto the base branch, on a clean tree, is the only sync done without asking: do it, then report it in one line. Anything else — uncommitted changes, a remote branch that does not fast-forward, a base-branch catch-up that needs a merge commit — ends the turn on one message stating what will happen ("I'll commit your changes as WIP and merge `main`, OK?"). The list below runs on the user's yes. In a workspace you opened or created, the list runs directly.
189
156
  {{/codingAgent}}
190
157
 
191
- Skip on sub-path 3 (no branch — nothing to sync). Otherwise, once the workspace is set up, bring the branch up to date *before* inspecting, working, or reporting a status — a teammate may have pushed since you last synced, and a report off a stale branch is wrong. In order:
158
+ Skip on sub-path 3 (no branch — nothing to sync). If Step 4 was skipped, select and fetch the base ref as described there. Once the workspace is set up, bring the branch up to date *before* inspecting, working, or reporting a status — a teammate may have pushed since you last synced, and a report off a stale branch is wrong. In order:
192
159
 
193
- 1. **Confirm the branch.** Check the worktree's checked-out branch carries the expected TICKET_ID. If it doesn't, stop and surface it to the user — don't work on the wrong branch.
160
+ 1. **Confirm the branch and the work files.** Check the worktree's checked-out branch matches the explicit user choice, or otherwise carries the expected TICKET_ID. If it doesn't, stop and surface it to the user — don't work on the wrong branch. Then run `{{ALIGNFIRST}} plans check` from the worktree.
194
161
  2. **Guard uncommitted work.** Run `git status`. If the worktree is dirty, have the agent commit a WIP first (even if it doesn't compile) — never sync over uncommitted work.
195
- 3. **Merge the remote branch.** If the branch has a remote counterpart, merge its freshly fetched ref into the local branch to catch up. Delegate to the agent (`merge` protocol) when it doesn't fast-forward or conflicts.
196
- 4. **Catch up with the base branch.** If the freshly fetched base branch (`origin/<base>`) has commits not yet in this branch, run the "Updating a branch with the base branch" flow — without asking; step 7 tells the user what came in.
162
+ 3. **Merge the remote branch.** If the branch has a remote counterpart, fetch its remote if it differs from the base's, then merge its freshly fetched ref into the local branch to catch up. Delegate to the agent (`merge` protocol) when it doesn't fast-forward or conflicts.
163
+ 4. **Catch up with the base branch.** If the selected base ref has commits not yet in this branch, run the "Updating a branch with the base branch" flow — without asking; step 7 tells the user what came in.
197
164
  5. **Refresh the workspace if commits came in.** If the merge brought in new commits, run the "Refreshing the workspace after a branch refresh" flow: reinstall dependencies, rebuild, run the new migrations.
198
165
  6. **Check for an open MR/PR** on this branch and note its state.
199
166
  7. **Report what changed.** If either merge brought in new commits, post a one-line summary so the user knows the ground shifted.
@@ -227,7 +194,7 @@ The workspace is ready. Announce what you're about to do in one line and do it.
227
194
  When the work is an `{{ALIGNDEV}} code` run, launch it as the delegation guide describes: background `exec` with `timeoutSeconds: 0`, then end the turn on the acknowledgement. Call nothing on the `{{ALIGNDEV}} code` session before the chained turn wakes you, whatever the `exec` acknowledgement suggests.
228
195
  {{/openclaw}}
229
196
  {{#codingAgent}}
230
- When the work is an `{{ALIGNDEV}} code` run, follow the delegation guide's parent-host route, then end the launch turn on the acknowledgement. A Pi parent first requires the available `background` tool and a persistent session; if either is missing, explain the setup problem instead of launching or promising completion.
197
+ When the work is an `{{ALIGNDEV}} code` run, launch it as the delegation guide describes for your parent host, then end the launch turn on the acknowledgement.
231
198
  {{/codingAgent}}
232
199
 
233
200
  Ask only when you genuinely can't proceed — the request is ambiguous enough that two readings lead to different work, or it turns on a product decision that isn't yours to make.
@@ -0,0 +1,33 @@
1
+ # Runbook: Work-files setup
2
+
3
+ Prepare usable work files before ticket reservation, request capture, coding delegation, or discussion recording. This procedure needs only PROJECT_PATH, the project's main-worktree path. It needs no ticket, branch, or new worktree.
4
+
5
+ For explicit companion-only onboarding, start at section 3 under the onboarding authorization, even when existing project plans are usable. That route requires registration and an explicit companion-plans selection independently of the readiness gate below.
6
+
7
+ ## 1. Check the effective work files
8
+
9
+ Run `{{ALIGNFIRST}} plans check --json` from PROJECT_PATH. It reads the effective `.plans` location from `{{ALIGNFIRST}} config --json`, where explicit `project` or `companion` selections win and, under `auto`, an existing companion copy wins over an existing project copy; when neither exists, a registered companion is the creation target. The check passes when that location is a usable directory with no file tracked by this project's own repository, through a tracked symlink, mixed tracked/untracked contents, or an alias into tracked files included. A separate work-files repository may track its contents, and an unused tracked project `.plans` is not a blocker when a usable companion is effective.
10
+
11
+ If `--json` is rejected, the selected AlignFirst CLI needs upgrading alongside AlignDev. With `npx`, check the project's local `alignfirst` dependency, which takes precedence over the cached or global CLI. Retry the JSON check after upgrading; do not substitute a plain-text check.
12
+
13
+ When an existing linked worktree is selected, run the command there too: it also requires the same effective target as the main worktree. A different location is an error: do not create a second history or repair links silently.
14
+
15
+ Usable, non-project-tracked effective plans need no preparation: resume the interrupted operation. Any other failure (broken links, invalid configuration, unreadable paths, conflicting non-directory files) is reported, not repaired.
16
+
17
+ ## 2. Obtain approval when preparation is needed
18
+
19
+ When effective plans are missing or project-tracked, including an add failure because the intended branch tracks project-local plans, ask in the user's language unless preparation is already authorized: "{Reason}. May I select companion-backed work files for all this project's worktrees, leaving the existing project work files untouched and unused?" Keep the all-worktree scope and preservation promise in the approval question. Do not copy, merge, migrate, archive, or delete existing work files, and do not ask about copying them.
20
+
21
+ Wait for approval before changing registration, selection, or directories. Do not reserve a temporary ticket or create a temporary worktree to prepare work files.
22
+
23
+ ## 3. Select and verify companion plans
24
+
25
+ After approval:
26
+
27
+ 1. If no companion is registered, run `{{ALIGNFIRST}} companion register` from PROJECT_PATH. This also preserves a profile-only registration.
28
+ 2. Reread `{{ALIGNFIRST}} config --json`. Retain `companion.dir` and `companion.key`; use the reported key exactly.
29
+ 3. Read `~/.alignfirst/companions/registry.json` before editing. Its project entries live under `projects`. Edit only `projects[companion.key]`, setting `items[".plans"]` to `"companion"` within that entry. Use the key reported by config, not a guessed key or a new top-level `items` object. Preserve all other fields, item settings, profile selections, and entries.
30
+ 4. Reread `{{ALIGNFIRST}} config --json`. Verify that `locations[".plans"].in` is `"companion"` and its path is the selected companion's `.plans`. Create that directory if missing, preserving existing contents. Do not create a worktree `.plans` link for companion plans.
31
+ 5. Run `{{ALIGNFIRST}} plans check --json` again from PROJECT_PATH, and from any already selected worktree, then resume the interrupted operation.
32
+
33
+ This is the sole assistant preparation procedure. `{{ALIGNDEV}} worktree add` and coding launches validate work files; they do not authorize this selection or provision missing plans.
@@ -24,11 +24,12 @@ A runbook is a procedure you read fully when its situation arises. Claim first,
24
24
  A runbook is a procedure you read fully when its situation arises.
25
25
  {{/codingAgent}}
26
26
 
27
+ - `{{ALIGNDEV}} guide work-files-setup` — the shared preparation gate before any operation that needs work files; requires only PROJECT_PATH.
27
28
  - `{{ALIGNDEV}} guide project-workspace-setup` — single-project changes, protocol requests, and ticket status requests, before project work.
28
29
  {{#openclaw}}
29
30
  - `{{ALIGNDEV}} guide project-lifecycle` — creating a project, onboarding a repository to clone, physically removing a project.
30
31
  {{/openclaw}}
31
- - `{{ALIGNDEV}} guide consultation` — questions, advice, brainstorming: read-only work that produces understanding rather than code.
32
+ - `{{ALIGNDEV}} guide consultation` — a standalone question, advice, or brainstorming: read-only work that produces understanding.
32
33
 
33
34
  {{#openclaw}}
34
35
  ## Take over a working session
@@ -53,7 +54,7 @@ Outside a git repository, tell the user to start the session inside the project'
53
54
 
54
55
  - PROJECT_PATH is the main worktree of the session's working directory: the parent of `git rev-parse --path-format=absolute --git-common-dir`. PROJECT is its directory name.
55
56
  - The workplace is the session's worktree (`git rev-parse --show-toplevel`) and its branch (`git branch --show-current`).
56
- - Run `{{ALIGNFIRST}} config --json` from PROJECT_PATH. The default branch is `config.git.defaultBranch` in the report, else `git symbolic-ref --short refs/remotes/origin/HEAD` without its `origin/` prefix. The report also names the project's companion directory, where its AlignFirst files may live.
57
+ - Run `{{ALIGNFIRST}} config --json` from PROJECT_PATH. The default branch is `config.git.defaultBranch` in the report, else the default branch identified by the project's instructions or configured remote. Ask when it is unclear. The report also names the project's companion directory, where its AlignFirst files may live.
57
58
  {{#developers}}
58
59
  - Retain `locations["DEVELOPERS.md"].path` from the report as DEVELOPERS_PATH.
59
60
  {{/developers}}
@@ -117,19 +118,21 @@ Resolve what the request leaves open:
117
118
  {{#openclaw}}
118
119
  - A request may need no project. Do not ask for one until the work itself requires project files.
119
120
  {{/openclaw}}
120
- - Code reviews and explicitly requested AlignFirst protocols follow the ticket and workspace flow. Other read-only questions, advice and brainstormings require PROJECT and PROJECT_PATH only. Follow `{{ALIGNDEV}} guide consultation` before ticket preflight, request capture, or workspace setup. A supplied ticket is context, not a requirement to create or update ticket artifacts.
121
121
  {{#openclaw}}
122
- - Single-project changes, protocol requests, and ticket status requests require PROJECT, PROJECT_PATH, and TICKET_ID. Ask only after the available resource, inventory, request, and ticket integration fail to supply them. An explicit no-ticket request follows Step 5 instead of asking for an external ID.
122
+ - Single-project changes, code reviews, protocol requests, and ticket status requests require PROJECT, PROJECT_PATH, and TICKET_ID. Ask only after the available resource, inventory, request, and ticket integration fail to supply them. An explicit no-ticket request follows Step 5 instead of asking for an external ID.
123
123
  {{/openclaw}}
124
124
  {{#codingAgent}}
125
- - Single-project changes, protocol requests, and ticket status requests require PROJECT, PROJECT_PATH, and TICKET_ID. Ask only after the available resource, request, and ticket integration fail to supply them. An explicit no-ticket request follows Step 5 instead of asking for an external ID.
125
+ - Single-project changes, code reviews, protocol requests, and ticket status requests require PROJECT, PROJECT_PATH, and TICKET_ID. Ask only after the available resource, request, and ticket integration fail to supply them. An explicit no-ticket request follows Step 5 instead of asking for an external ID.
126
126
  {{/codingAgent}}
127
+ - Consultations require only PROJECT and PROJECT_PATH to start. Follow `{{ALIGNDEV}} guide consultation` before ticket preflight, request capture, or workspace setup. A supplied ticket is context; the runbook decides whether to record the discussion.
127
128
 
128
129
  {{#openclaw}}
129
130
  Once a single-project request's PROJECT_PATH is known, run `{{ALIGNDEV}} project status <PROJECT_PATH>` and retain its `DEVELOPERS.md` path as DEVELOPERS_PATH. The report also names the project's companion directory, where its AlignFirst files may live.
130
131
  {{/openclaw}}
131
132
 
132
- For changes, protocol requests, and ticket status requests, as soon as PROJECT_PATH and TICKET_ID are known, and before project work, run `{{ALIGNFIRST}} sync`, then `{{ALIGNFIRST}} ticket {TICKET_ID}` from PROJECT_PATH. The second command validates the id and creates or restores TICKET_DIR before `{{ALIGNDEV}} code` can create session artifacts. Stop if either command fails. If either value becomes known later in the session, run the preflight then.
133
+ For changes, protocol requests, and ticket status requests, complete `{{ALIGNDEV}} guide work-files-setup` as soon as PROJECT_PATH is known, before known-ticket `sync`/`ticket`, side-ticket reservation, or request capture.
134
+
135
+ After that gate, as soon as PROJECT_PATH and TICKET_ID are known, and before project work, run `{{ALIGNFIRST}} sync`, then `{{ALIGNFIRST}} ticket {TICKET_ID}` from PROJECT_PATH. The second command validates the id and creates or restores TICKET_DIR before `{{ALIGNDEV}} code` can create session artifacts. Stop if either command fails. If either value becomes known later in the session, run the preflight then.
133
136
 
134
137
  TICKET_DIR lies in the work-files directory, `.plans/`, which may live in the project's companion. Use TICKET_DIR exactly as `{{ALIGNFIRST}} ticket` prints it, resolved from PROJECT_PATH when relative.
135
138
 
@@ -151,13 +154,13 @@ Project-workspace cleanup is not physical project removal; follow "Cleanup reque
151
154
  ### Step 5 — Reserve a side ticket for explicit no-ticket work
152
155
 
153
156
  {{#openclaw}}
154
- Skip this step for read-only questions, project lifecycle, and operational work. A new project's bootstrap through its initial commit stays in the lifecycle procedure.
157
+ Skip this step for consultations, project lifecycle, and operational work. A new project's bootstrap through its initial commit stays in the lifecycle procedure.
155
158
  {{/openclaw}}
156
159
  {{#codingAgent}}
157
- Skip this step for read-only questions and operational work.
160
+ Skip this step for consultations and operational work.
158
161
  {{/codingAgent}}
159
162
 
160
- For new single-project work where the user explicitly says there is no ticket or asks for a side ticket:
163
+ For new single-project work where the user explicitly says there is no ticket or asks for a side ticket, complete `{{ALIGNDEV}} guide work-files-setup` from PROJECT_PATH, then:
161
164
 
162
165
  {{#openclaw}}
163
166
  1. Read DEVELOPERS_PATH and run `{{ALIGNFIRST}} context` from PROJECT_PATH.
@@ -176,7 +179,7 @@ For new single-project work where the user explicitly says there is no ticket or
176
179
  3. Run `{{ALIGNFIRST}} ticket --side` from PROJECT_PATH. It creates the ticket directory and prints it as TICKET_DIR; TICKET_ID is the `side-N` it reports.
177
180
  {{/codingAgent}}
178
181
  {{#openclaw}}
179
- 4. Write `{TICKET_DIR}A1-request.md` with the complete recorded request. For a short request, use the starter's task line and the message that explicitly confirmed no ticket.
182
+ 4. Write `{TICKET_DIR}A1-request.md` with the complete original request from the starter's Request block, short requests included. Preserve every requirement and the explicit no-ticket choice, together with any later human corrections.
180
183
  {{/openclaw}}
181
184
  {{#codingAgent}}
182
185
  4. Write `{TICKET_DIR}A1-request.md` with the complete request. For a short request, use the user's request and the message that explicitly confirmed no ticket.
@@ -184,7 +187,7 @@ For new single-project work where the user explicitly says there is no ticket or
184
187
  5. Run `{{ALIGNFIRST}} sync`.
185
188
 
186
189
  {{#openclaw}}
187
- The bot owns this reservation and the request capture; the agent receives TICKET_ID. Do not use `{{ALIGNDEV}} code new --no-ticket`: TICKET_ID must exist before delegation, for the request file and the workspace. Continue to workspace setup with the side ticket as TICKET_ID, then run the coding protocol from the returned linked worktree.
190
+ You own this reservation and the request capture; the agent receives TICKET_ID. Do not use `{{ALIGNDEV}} code new --no-ticket`: TICKET_ID must exist before delegation, for the request file and the workspace. Continue to workspace setup with the side ticket as TICKET_ID, then run the coding protocol from the returned linked worktree.
188
191
  {{/openclaw}}
189
192
  {{#codingAgent}}
190
193
  You own this reservation and the request capture; the agent receives TICKET_ID. Do not use `{{ALIGNDEV}} code new --no-ticket`: TICKET_ID must exist before delegation, for the request file and the workspace. Continue with `{{ALIGNDEV}} guide project-workspace-setup`, which decides the workplace with the side ticket as TICKET_ID, then run the coding protocol from that workplace.
@@ -200,20 +203,21 @@ You own this reservation and the request capture; the agent receives TICKET_ID.
200
203
  The question on every turn is not a mode but a fact: does this request need a project workspace?
201
204
 
202
205
  - **The request is a code review or names an AlignFirst protocol** — follow the ticket and workspace flow below.
203
- - **The request is another read-only question, advice, or a brainstorming** — run `{{ALIGNDEV}} guide consultation`, read it fully, and follow it.
206
+ - **The question arises within ongoing work** — keep that work's workflow, ticket, and workplace.
207
+ - **The request is a consultation** — run `{{ALIGNDEV}} guide consultation`, read it fully, and follow it. A ticket's progress is a status request, handled by the next case.
204
208
  {{#openclaw}}
205
- - **The request is a single-project change, protocol request, or ticket status request** — require PROJECT, PROJECT_PATH, and TICKET_ID. A starter with a request block is filed first ("Detailed requests" below). Then run `{{ALIGNDEV}} guide project-workspace-setup`, read it fully, and complete it before any other action, `git log` and codebase inspection included. Your first post is its setup signal (Step 2); the procedure attaches or sets up the workspace, whatever exists, and posts the `[WORKSPACE]` banner.
209
+ - **The request is a single-project change, protocol request, or ticket status request** — a detailed change request is filed first ("Detailed requests" below). Then run `{{ALIGNDEV}} guide project-workspace-setup`, read it fully, and complete it before any other action, `git log` and codebase inspection included. Your first post is its setup signal (Step 2); the procedure attaches or sets up the workspace, whatever exists, and posts the `[WORKSPACE]` banner.
206
210
  {{/openclaw}}
207
211
  {{#codingAgent}}
208
- - **The request is a single-project change, protocol request, or ticket status request** — require PROJECT, PROJECT_PATH, and TICKET_ID. A detailed request is filed first ("Detailed requests" below). Then run `{{ALIGNDEV}} guide project-workspace-setup`, read it fully, and complete it before any other action, `git log` and codebase inspection included. The procedure decides the workplace (in place, a workspace, or a question to the user) and posts the `[WORKSPACE]` banner once it is known.
212
+ - **The request is a single-project change, protocol request, or ticket status request** — a detailed change request is filed first ("Detailed requests" below). Then run `{{ALIGNDEV}} guide project-workspace-setup`, read it fully, and complete it before any other action, `git log` and codebase inspection included. The procedure decides the workplace (in place, a workspace, or a question to the user) and posts the `[WORKSPACE]` banner once it is known.
209
213
  {{/codingAgent}}
210
214
  - **A required value is missing** — go to Step 7. Resolve or ask for it there. The moment the required values are known, follow the matching path above.
211
215
 
212
216
  {{#openclaw}}
213
- Changes to an existing project happen inside a linked workspace. Read-only questions use the main worktree by default. The lifecycle procedure also uses it for new-project bootstrap through its initial commit and repository onboarding on a setup branch.
217
+ Changes to an existing project happen inside a linked workspace unless the user explicitly chose in-place work. Consultations use the main worktree by default. The lifecycle procedure also uses it for new-project bootstrap through its initial commit and repository onboarding on a setup branch.
214
218
  {{/openclaw}}
215
219
  {{#codingAgent}}
216
- Changes happen in the workplace the setup procedure decides. Read-only questions use the session's worktree as it is.
220
+ Changes happen in the workplace the setup procedure decides. Consultations use the session's worktree as it is.
217
221
  {{/codingAgent}}
218
222
 
219
223
  ### Step 7 — Handle the actual request
@@ -237,6 +241,7 @@ On Discord the rename travels with a post: `message` `action: "send"` with the c
237
241
  Interpret every user message in the context of the current project — something to do, investigate, challenge, or advise on inside the codebase. The user is rarely asking you to perform the action _in the chat_; they're asking about the project.
238
242
 
239
243
  - **Code change.** "Set this text bolder" → bold it in the project, not in the chat reply.
244
+ - **Question, advice, or a design opinion.** Delegate to the agent in the workflow selected in Step 6. It grounds the answer in the repository. No code change unless asked.
240
245
 
241
246
  {{#openclaw}}
242
247
  Only when the message is unambiguously about chat content ("summarize this thread", "what does this mean") should you treat it as a regular conversation.
@@ -245,19 +250,11 @@ Only when the message is unambiguously about chat content ("summarize this threa
245
250
  Only when the message is unambiguously about chat content ("summarize this conversation", "what does this mean") should you treat it as a regular conversation.
246
251
  {{/codingAgent}}
247
252
 
248
- **Question, advice, or a design opinion.** The substance comes from the agent, which reads the repository. Follow `{{ALIGNDEV}} guide consultation`. No code change unless asked.
249
-
250
- ### Read-only questions
251
-
252
- A codebase question, advice, or a brainstorming follows `{{ALIGNDEV}} guide consultation`. Read it fully. It resolves the project, delegates the complete question to the agent, and records the discussion when one is worth keeping.
253
-
254
- A request for a ticket's progress follows "Status update" instead; it needs that ticket's history and workspace state.
255
-
256
253
  ### Detailed requests
257
254
 
258
255
  When one project owns a detailed change request, preserve it before delegation:
259
256
 
260
- 1. Establish TICKET_ID. When project or deployment instructions provide ticket-system access, create a ticket with a very short description in the user's language. When no access is provided, ask the user for the ticket ID.
257
+ 1. Complete `{{ALIGNDEV}} guide work-files-setup`, then establish TICKET_ID. When project or deployment instructions provide ticket-system access, create a ticket with a very short description in the user's language. When no access is provided, ask the user for the ticket ID.
261
258
  2. If this step established TICKET_ID, complete the known-ticket preflight now. Then run `{{ALIGNFIRST}} ticket {TICKET_ID} --next request.md` and append FILE_NAME to TICKET_DIR, exactly as printed, to get the request-file path.
262
259
  {{#openclaw}}
263
260
  3. Write the complete request text recorded in the starter's request block to that path. Keep its language. You may fix typos; preserve every detail.
@@ -277,49 +274,53 @@ When Step 5 reserved a side ticket `side-N`, the request is already captured. Co
277
274
  {{/codingAgent}}
278
275
 
279
276
  {{#openclaw}}
280
- Skip this capture workflow for a multi-project request with no main project and for operational work such as workspace cleanup or base-branch refresh. Delegate those requests to the agent without an AlignFirst protocol.
277
+ Skip this capture workflow for a multi-project request with no main project and for operational work such as workspace cleanup or base-branch refresh.
281
278
  {{/openclaw}}
282
279
  {{#codingAgent}}
283
- Skip this capture workflow for operational work such as workspace cleanup or base-branch refresh. Delegate those requests to the agent without an AlignFirst protocol.
280
+ Skip this capture workflow for operational work such as workspace cleanup or base-branch refresh.
284
281
  {{/codingAgent}}
285
282
 
286
283
  {{#openclaw}}
287
284
  ### Multi-project and operational work
288
285
 
289
- Delegate a multi-project request with no main project, workspace cleanup, base-branch refresh, and similar operational work to the agent without an AlignFirst protocol. Refresh `{{ALIGNDEV}} project list --json` when the affected project set is not already recorded. Run one project-bound agent session from each affected PROJECT_PATH and coordinate their results in the thread. For a base-branch refresh, the agent owns the initial fetch, the fast-forward, and any dependency, build, or migration refresh; an already-current branch is one possible result of that delegation. Supply the ticket ID when one identifies the workspaces and name every configured global tool the run can use. Set up project workspaces only when the operation needs them.
286
+ Workspace cleanup follows "Cleanup requests". Delegate a multi-project request with no main project, base-branch refresh, and other operational work to the agent without an AlignFirst protocol. Refresh `{{ALIGNDEV}} project list --json` when the affected project set is not already recorded. Run one project-bound agent session from each affected PROJECT_PATH and coordinate their results in the thread. For a base-branch refresh, the agent owns the initial fetch, the fast-forward, and any dependency, build, or migration refresh; an already-current branch is one possible result of that delegation. Supply the ticket ID when one identifies the workspaces, and name the global tools the operation needs. Set up project workspaces only when the operation needs them.
290
287
  {{/openclaw}}
291
288
  {{#codingAgent}}
292
289
  ### Operational work
293
290
 
294
- Delegate workspace cleanup, base-branch refresh, and similar operational work to the agent without an AlignFirst protocol, from PROJECT_PATH. For a base-branch refresh, the agent owns the initial fetch, the fast-forward, and any dependency, build, or migration refresh; an already-current branch is one possible result of that delegation. Supply the ticket ID when one identifies the workspaces and name every configured global tool the run can use. Set up project workspaces only when the operation needs them.
291
+ Workspace cleanup follows "Cleanup requests". Delegate base-branch refresh and other operational work to the agent without an AlignFirst protocol, from PROJECT_PATH. For a base-branch refresh, the agent owns the initial fetch, the fast-forward, and any dependency, build, or migration refresh; an already-current branch is one possible result of that delegation. Supply the ticket ID when one identifies the workspaces, and name the global tools the operation needs. Set up project workspaces only when the operation needs them.
295
292
  {{/codingAgent}}
296
293
 
297
294
  ### What you delegate vs do
298
295
 
299
296
  Lean toward delegating; the less you touch the project directly, the better.
300
297
 
301
- Delegate to the agent: workspace/branch/worktree creation, writing code (`alignfirst` protocols), commits, pushes, opening MR/PRs.
298
+ Delegate to the agent: the project's workspace setup, writing code (`alignfirst` protocols), commits, pushes, opening MR/PRs. You run `{{ALIGNDEV}} worktree list/add/remove` and `{{ALIGNDEV}} guide work-files-setup` yourself; neither needs a coding launch.
302
299
 
303
- Thinking is delegated too. When you need *ideas*, a *design* direction, an *opinion*, or an approach — for the user or for your own next step — put the question to the agent and build on its answer. Never brainstorm alone: the agent grounds its ideas in the codebase; yours would come from memory. `{{ALIGNDEV}} guide consultation` is the procedure.
300
+ Delegate reasoning too, whether for the user or your own next step. Ask the agent for ideas, design advice, opinions, or approaches, and build on its answer.
304
301
 
305
302
  {{#openclaw}}
306
- Global tools go in the prompt. Run `{{ALIGNDEV}} code` from the linked workspace for changes and from PROJECT_PATH only when the procedure explicitly works in the main worktree. The agent knows only that directory's project context: it can run the globally installed tools your own context lists, but it doesn't know they exist. When a delegated task can use one, name it in the prompt as **globally installed**. A task you would have kept because it needs such a tool is one more thing to delegate.
303
+ Run `{{ALIGNDEV}} code` from the linked workspace for changes and from PROJECT_PATH only when the procedure explicitly works in the main worktree.
307
304
  {{/openclaw}}
308
305
  {{#codingAgent}}
309
- Global tools go in the prompt. Run `{{ALIGNDEV}} code` from the workplace, unless a procedure names another directory. The agent knows only that directory's project context: it can run the globally installed tools your own context lists, but it doesn't know they exist. When a delegated task can use one, name it in the prompt as **globally installed**. A task you would have kept because it needs such a tool is one more thing to delegate.
306
+ Run `{{ALIGNDEV}} code` from the workplace, unless a procedure names another directory.
310
307
  {{/codingAgent}}
311
308
 
312
- Every single-project change delegation carries TICKET_ID in the `{{ALIGNDEV}} code` invocation or message as the delegation guide allows. Read-only questions omit the ticket option; a ticket mentioned by the user stays in the question's context. Operational maintenance may instead identify its existing branches and workspaces directly.
309
+ Every single-project change delegation carries TICKET_ID in the `{{ALIGNDEV}} code` invocation or message as the delegation guide allows. Consultation delegations omit the ticket option; a ticket mentioned by the user stays in the question's context. Operational maintenance may instead identify its existing branches and workspaces directly.
313
310
 
314
311
  Feel free to do the rest yourself (except coding) when it's more practical.
315
312
 
313
+ ### What the message carries
314
+
315
+ The agent reads the project's instructions, documentation and work files on its own. The message carries what it cannot read: the task, the user's requirements and decisions, and the globally installed tools the task needs, each named as **globally installed**. Point at a review, a spec or a plan by its path instead of restating it. Your playbook stays with you, except where it says to pass a rule to the agent. A task you would have kept because it needs a global tool is one more thing to delegate.
316
+
316
317
  ### A background run moves the report
317
318
 
318
319
  {{#openclaw}}
319
320
  Launching a background run ends the turn: the closing message is the launch acknowledgement, and the report moves to the run's completion turn. Each further run launched from that turn moves the report again.
320
321
  {{/openclaw}}
321
322
  {{#codingAgent}}
322
- Launching a background run ends the turn on its acknowledgement. For a Pi parent, first verify the `background` capability and a persistent parent, as the delegation guide requires; without them, explain installation instead of promising a later report. On a Pi notice, validate the job handle and retrieve the exact run with `status --result`. Continue authorized work or report genuine questions/blockers. A child's completed turn is not completion of the whole request. Further runs use the same launch procedure; repeated notices must not duplicate successor work. Claude Code and Codex retain their host-specific completion/fallback routes in the delegation guide.
323
+ Launching a background run ends the turn on its acknowledgement; the report moves to the run's completion, handled as the delegation guide describes for your parent host. A child's completed turn does not complete the whole request.
323
324
  {{/codingAgent}}
324
325
 
325
326
  ### The plan is not a gate
@@ -330,7 +331,7 @@ The agent usually has no question. When it does, answer it: a technical question
330
331
 
331
332
  ### Plan files are the agent's material
332
333
 
333
- Before acting on any file the user names under `.plans/`, run `{{ALIGNFIRST}} sync`. Then never read a plan file, main plans included. A request to execute a plan means: read the spec next to it when one exists — same directory, same leading letter (`A1-spec.md` for `A2-plan.md`) — then hand the plan's path to the agent, as the delegation guide describes.
334
+ Before acting on any file the user names under `.plans/`, complete `{{ALIGNDEV}} guide work-files-setup`, then run `{{ALIGNFIRST}} sync`. Then never read a plan file, main plans included. A request to execute a plan means: read the spec next to it when one exists — same directory, same leading letter (`A1-spec.md` for `A2-plan.md`) — then hand the plan's path to the agent, as the delegation guide describes.
334
335
 
335
336
  For the `.plans/` directory's task directories, cycles, filenames, and artifact conventions, run `{{ALIGNFIRST}} guide` from PROJECT_PATH; its output ends with the ticket directory and work file rules. Project instructions only define whether and how the directory is shared.
336
337
 
@@ -365,38 +366,19 @@ A project can have documentation files. List them all from PROJECT_PATH, the ful
365
366
  ### Main worktree and base branch
366
367
 
367
368
  {{#openclaw}}
368
- A project in main-worktree mode (`{{ALIGNDEV}} guide project-workspace-setup`) is the exception to this section: its main worktree leaves the base branch while a working thread holds it, and the edits happen there, on the thread's branch.
369
- {{/openclaw}}
370
-
371
- {{#openclaw}}
372
- The main worktree at PROJECT_PATH stays on the base branch, except for the repository-onboarding setup branch defined in `{{ALIGNDEV}} guide project-lifecycle`. It is shared across sessions.
369
+ The main worktree at PROJECT_PATH is shared across sessions. It stays on the base branch, and no codebase file is edited there, with three exceptions: bootstrapping a new project before its initial commit and the repository-onboarding setup branch, both defined in `{{ALIGNDEV}} guide project-lifecycle`, and an explicit user choice to work in place.
373
370
  {{/openclaw}}
374
371
  {{#codingAgent}}
375
372
  The main worktree at PROJECT_PATH belongs to the user. Edits on the base branch happen only when the user chose to work there.
376
373
  {{/codingAgent}}
377
374
 
378
- {{#openclaw}}
379
- Never edit files while the base branch is checked out, except while bootstrapping a new project before its initial commit as defined in `{{ALIGNDEV}} guide project-lifecycle`.
380
- {{/openclaw}}
381
-
382
375
  Install dependencies in the main worktree from the committed lockfile, without rewriting it: `npm ci` with npm, or the frozen-lockfile install of the project's package manager. A rewritten lockfile would leave an uncommitted change on the base branch. Every prompt to the agent that installs dependencies in the main worktree states this rule.
383
376
 
384
377
  Running the dev-server from the main worktree is fine.
385
378
 
386
379
  ### Linked worktrees and other branches
387
380
 
388
- {{#openclaw}}
389
- A project in main-worktree mode has no linked worktree: its branches are created and checked out in the main worktree with plain `git switch`, and the rule against a hand-made checkout does not apply to it. `git worktree add`/`remove`/`prune` stay out of bounds.
390
-
391
- After a project's initial commit exists, editing the codebase happens on another branch in a linked worktree. If you need one and it doesn't exist yet, follow the `{{ALIGNDEV}} guide project-workspace-setup` instructions to set it up.
392
-
393
- Worktrees belong to the workspace tooling. Every creation, reuse, and teardown goes through its commands — run the guide `DEVELOPERS.md` points to (`workspace --guide`) to get them. `git worktree add`/`remove`/`prune` and deleting a worktree directory are out of bounds, and so is a hand-made branch checkout outside a workspace. The registry is what makes a worktree visible to the other sessions and to the dev-server tooling.
394
- {{/openclaw}}
395
- {{#codingAgent}}
396
- A project with workspace tooling (Step 2 of `{{ALIGNDEV}} guide project-workspace-setup`) owns its worktrees through it. Every creation, reuse, and teardown goes through the commands its guide (`workspace --guide`) gives. `git worktree add`/`remove`/`prune` and deleting a worktree directory are out of bounds. The registry is what makes a worktree visible to the other sessions and to the dev-server tooling.
397
-
398
- Without workspace tooling, create a worktree with `git worktree add` only when the user asks for one.
399
- {{/codingAgent}}
381
+ `{{ALIGNDEV}} guide project-workspace-setup` selects or creates the workplace: through the project's workspace tooling when it has one, through `{{ALIGNDEV}} worktree list/add/remove` otherwise. Raw `git worktree add`/`remove`/`prune` and directory deletion are out of bounds.
400
382
 
401
383
  ### Updating a branch with the base branch
402
384
 
@@ -431,13 +413,7 @@ Delegate the sequence to the agent.
431
413
 
432
414
  ### Status update
433
415
 
434
- {{#openclaw}}
435
- - Check status from the recorded linked-worktree path. The takeover sync in `{{ALIGNDEV}} guide project-workspace-setup` has already fetched and merged the remote branch, so you are reporting the latest state.
436
- {{/openclaw}}
437
- {{#codingAgent}}
438
- - Check status from the workplace. The sync in `{{ALIGNDEV}} guide project-workspace-setup` has already fetched and merged the remote branch, so you are reporting the latest state.
439
- {{/codingAgent}}
440
- - Report where the work stands, drawing on two complementary sources: repo/workflow metadata you gather directly (`git log`/`status`/branch, `gh` PR state), and the ticket's AlignFirst artifacts via `{{ALIGNDEV}} code new --ticket <id> --catchup` (the agent synthesizes the ticket history). Don't browse the source to describe the code; that's a separate delegation.
416
+ A request for a ticket's progress goes through `{{ALIGNDEV}} guide project-workspace-setup`: its Step 5 brings the branch current and its Step 6 reports the work content.
441
417
 
442
418
  ### Dev-server while working
443
419
 
@@ -476,12 +452,7 @@ Either way, the report states the error and your decision.
476
452
 
477
453
  #### Dev-server log review
478
454
 
479
- {{#openclaw}}
480
- After using a dev-server, have a separate no-protocol agent run with the smallest available model inspect its logs: give it the log locations and ask for errors or unusual behavior. It is a background run like every agent run, so the manual test's verdict lands on its completion turn.
481
- {{/openclaw}}
482
- {{#codingAgent}}
483
- After using a dev-server, have a separate no-protocol agent run inspect its logs: give it the log locations and ask for errors or unusual behavior. Choose the smallest available model from the child's ordered list; for Pi without a finite ordered allowlist, use the configured/default model instead. Launch and retrieve its result through the delegation guide's parent-host route before reporting the manual test's verdict.
484
- {{/codingAgent}}
455
+ After using a dev-server, have a separate no-protocol agent run with the smallest available model (the default one when the child has no model list) inspect its logs: give it the log locations and ask for errors or unusual behavior. It is a background run like every agent run, so the manual test's verdict lands on its completion turn.
485
456
 
486
457
  Clean logs are required for the manual test to pass.
487
458
 
@@ -587,16 +558,11 @@ After creating the MR/PR (via `{{ALIGNDEV}} code`):
587
558
  - Post the MR/PR link.
588
559
  - Wait for the CI to run (wait two minutes, then check; if it's still pending, wait another two minutes, and check again). If it fails, report the failure, then fix it. If it succeeds, report the success to the user.
589
560
 
590
- Whenever you observe that a PR/MR is merged, delegate the post-merge maintenance to the agent without a protocol:
561
+ Whenever you observe that a PR/MR is merged:
591
562
 
592
- {{#openclaw}}
593
- 1. Remove the source branch's registered project workspace through the project's workspace tooling, when one exists. In main-worktree mode, switch the main worktree back to the merge target instead.
594
- {{/openclaw}}
595
- {{#codingAgent}}
596
- 1. Remove the source branch's registered project workspace through the project's workspace tooling, when one exists. A branch worked on in place stays checked out: the user decides when to leave it.
597
- {{/codingAgent}}
598
- 2. Refresh the merge target in the main worktree without switching the main worktree away from its base branch. Fetch and fast-forward it, then reinstall dependencies, rebuild, and run new migrations when the project requires them.
599
- 3. Report the removed workspace and refreshed branch.
563
+ 1. Remove the source branch's linked workspace as "Cleanup requests" describes. A branch worked on in place stays checked out: the user decides when to leave it.
564
+ 2. Delegate the refresh of the merge target without a protocol: in the main worktree, clean and on its base branch, fetch and fast-forward it, then reinstall dependencies, rebuild, and run new migrations when required.
565
+ 3. Report the removed workspace and refreshed branch. When unsuitable plans block the refresh delegation, the removal still happens; report the blocked refresh.
600
566
 
601
567
  ### Protected directories
602
568
 
@@ -611,20 +577,23 @@ When the user asks to tear down one named project workspace (or worktree) from i
611
577
  When the user asks to tear down one named project workspace (or worktree):
612
578
  {{/codingAgent}}
613
579
 
614
- 1. Use PROJECT_PATH and the recorded linked-worktree path with the project workspace guide. Have the agent remove the *workspace*. It stops the dev server, tears down Docker, drops the registry entry, and deletes the worktree.
615
- 2. Confirm the teardown to the user.
580
+ 1. Resolve the exact linked-worktree path through the selected tooling; ask the user when it is ambiguous. With workspace tooling, have the agent run its removal procedure, which also tears down the dev environment. Without it, stop whatever the project runs there, then run `{{ALIGNDEV}} worktree remove <exact-path>` from PROJECT_PATH yourself: it refuses a dirty or locked worktree, and you never force it. This direct removal needs no coding launch or work-files preparation, even when plans are unsuitable.
581
+ 2. Confirm what was removed.
616
582
  {{#openclaw}}
617
583
  3. Reset the thread session.
618
584
  {{/openclaw}}
619
585
 
620
586
  {{#openclaw}}
621
- When the user asks to clean the workspaces, run a no-protocol delegation from each affected PROJECT_PATH with this instruction:
587
+ When the user asks to clean the workspaces, for each affected PROJECT_PATH:
622
588
  {{/openclaw}}
623
589
  {{#codingAgent}}
624
- When the user asks to clean the workspaces, run a no-protocol delegation from PROJECT_PATH with this instruction:
590
+ When the user asks to clean the workspaces, from PROJECT_PATH:
625
591
  {{/codingAgent}}
626
592
 
627
- > List every registered workspace for this project. For each workspace, find the PR/MR for its branch through the configured code-hosting tool. Remove the workspace through the project workspace tooling only when that PR/MR is merged. Leave workspaces with no PR/MR or an unmerged PR/MR intact. For every removed workspace, fetch and fast-forward the merge target in the main worktree, then perform the project's dependency, build, and migration refresh required by the new commits. Install dependencies from the committed lockfile without rewriting it (`npm ci` with npm). Report every decision and the final base-branch state.
593
+ 1. List the worktrees through the selected tooling: the project's workspace list, or `{{ALIGNDEV}} worktree list --json`.
594
+ 2. For each linked workspace, find its branch's PR/MR through the configured code-hosting tool. Remove the workspace as in "Cleanup requests", only when that PR/MR is merged. Leave the others intact: in-place work, no PR/MR, or an unmerged PR/MR. Stop on the first failed removal.
595
+ 3. When a workspace was removed, delegate the merge target's refresh as after a merge above, installing from the committed lockfile without rewriting it (`npm ci` with npm).
596
+ 4. Report every decision, any blocked refresh, and the final base-branch state.
628
597
 
629
598
  {{#openclaw}}
630
599
  ### Resetting a thread session
@@ -646,9 +615,4 @@ Creating a project, onboarding a repository to clone, or physically removing a p
646
615
  ### Forbidden
647
616
 
648
617
  - Never force push. Never rebase, reset, or amend a commit that exists on the remote.
649
- {{#openclaw}}
650
- - Never touch a worktree outside the workspace tooling. The main worktree of a project in main-worktree mode is the exception.
651
- {{/openclaw}}
652
- {{#codingAgent}}
653
- - Never touch a worktree outside the workspace tooling when the project has it. Without tooling, create or remove a worktree only when the user asks.
654
- {{/codingAgent}}
618
+ - Create and remove worktrees only through the project's workspace tooling or `{{ALIGNDEV}} worktree`.