aligndev 0.28.1 → 0.30.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.
Files changed (50) hide show
  1. package/README.md +16 -6
  2. package/dist/alignfirst-cli.js +22 -10
  3. package/dist/cli.d.ts +2 -0
  4. package/dist/cli.js +14 -12
  5. package/dist/code/claude-agent.js +1 -1
  6. package/dist/code/code-cli.js +3 -5
  7. package/dist/code/codex-agent.js +1 -1
  8. package/dist/code/machine-id.js +14 -3
  9. package/dist/code/pi-agent.js +1 -1
  10. package/dist/code/run-agent.js +37 -1
  11. package/dist/command-form.d.ts +5 -2
  12. package/dist/command-form.js +15 -6
  13. package/dist/guide/code-guide.d.ts +2 -2
  14. package/dist/guide/code-guide.js +4 -8
  15. package/dist/guide/guide-cli.js +82 -30
  16. package/dist/guide/render-template.d.ts +4 -4
  17. package/dist/guide/render-template.js +42 -21
  18. package/dist/guide/topics.d.ts +8 -3
  19. package/dist/guide/topics.js +26 -7
  20. package/dist/project/discovery.js +5 -12
  21. package/dist/project/layout.d.ts +22 -9
  22. package/dist/project/layout.js +101 -28
  23. package/dist/project/plans.d.ts +1 -1
  24. package/dist/project/plans.js +1 -1
  25. package/dist/project/render.js +3 -1
  26. package/dist/project/status.d.ts +2 -2
  27. package/dist/project/status.js +2 -2
  28. package/package.json +5 -1
  29. package/templates/guide/code.md +12 -3
  30. package/templates/guide/playbook/channel-handling.md +12 -17
  31. package/templates/guide/playbook/consultation.md +27 -30
  32. package/templates/guide/playbook/dispatcher.md +18 -0
  33. package/templates/guide/playbook/{discord-message-tool.md → message-tool.md} +29 -0
  34. package/templates/guide/playbook/playbook.md +55 -25
  35. package/templates/guide/playbook/project-lifecycle.md +33 -18
  36. package/templates/guide/playbook/project-workspace-setup.md +91 -71
  37. package/templates/guide/playbook/work-files-setup.md +2 -2
  38. package/templates/guide/playbook/working-session.md +207 -158
  39. package/templates/guide/project.md +4 -4
  40. package/dist/guide/guide-file.d.ts +0 -3
  41. package/dist/guide/guide-file.js +0 -26
  42. package/dist/worktree/add.d.ts +0 -20
  43. package/dist/worktree/add.js +0 -175
  44. package/dist/worktree/git.d.ts +0 -24
  45. package/dist/worktree/git.js +0 -103
  46. package/dist/worktree/remove.d.ts +0 -8
  47. package/dist/worktree/remove.js +0 -62
  48. package/dist/worktree/worktree-cli.d.ts +0 -10
  49. package/dist/worktree/worktree-cli.js +0 -122
  50. package/templates/guide/playbook/slack-message-tool.md +0 -23
@@ -1,44 +1,59 @@
1
1
  # Working session
2
2
 
3
- {{#openclaw}}
4
- You're handling work inside a Slack or Discord thread. Lifecycle, workspace, consultation, and coding happen here.
3
+ {{#thread}}
4
+ {{#slack}}
5
+ You're handling work inside a Slack thread. Lifecycle, workspace, consultation, and coding happen here.
6
+ {{/slack}}
7
+ {{#discord}}
8
+ You're handling work inside a Discord thread. Lifecycle, workspace, consultation, and coding happen here.
9
+ {{/discord}}
5
10
 
6
11
  A thread usually arrives from a channel session, which delivered the starter and may have started this session with a message from AlignFirst Service. A human can also open a thread themselves and tag you in it; "A thread you did not open" below covers what changes. Either way this is a working thread, and you never open another from inside it.
7
12
 
8
- Your plain text is your reply, on Discord and Slack alike, and only the message that **ends your turn** is guaranteed to post: on most model providers, text written between tool calls never leaves the transcript. So the message you end a turn with carries everything the user needs from that turn: the workspace state, the launch ack, the report. Never call `message` `send`/`thread-reply` on this thread; it posts everything twice. The single exception is a Discord rename, which travels with a post (see "Thread name" below). Otherwise `message` serves `read`, reactions, cross-surface posts, and attachments.
13
+ {{#slack}}
14
+ Your plain text is your reply, and only the message that **ends your turn** is guaranteed to post: on most model providers, text written between tool calls never leaves the transcript. So the message you end a turn with carries everything the user needs from that turn: the workspace state, the launch ack, the report. Never call `message` `send`/`thread-reply` on this thread; it posts everything twice. `message` serves `read`, reactions, cross-surface posts, and attachments.
15
+ {{/slack}}
16
+ {{#discord}}
17
+ Your plain text is your reply, and only the message that **ends your turn** is guaranteed to post: on most model providers, text written between tool calls never leaves the transcript. So the message you end a turn with carries everything the user needs from that turn: the workspace state, the launch ack, the report. Never call `message` `send`/`thread-reply` on this thread; it posts everything twice. The single exception is a Discord rename, which travels with a post (see "Thread name" below). Otherwise `message` serves `read`, reactions, cross-surface posts, and attachments.
18
+ {{/discord}}
9
19
 
10
20
  Keep progress and completion reports in this thread. A request to notify the user means reply here; use a DM or another surface only when the user explicitly names that destination.
11
- {{/openclaw}}
21
+ {{/thread}}
12
22
  {{#codingAgent}}
13
23
  You're handling work in this conversation, on one project: the repository where this session started. Workspace, consultation, and coding happen here. The session's worktree and its branch are your workplace by default.
24
+ {{/codingAgent}}
25
+ {{#app}}
26
+ You're handling work in this app conversation. One conversation holds one work item. Lifecycle, workspace, consultation, and coding happen here.
27
+ {{/app}}
28
+ {{#conversation}}
14
29
 
15
30
  Keep progress and completion reports in this conversation. A request to notify the user means a reply here.
16
- {{/codingAgent}}
31
+ {{/conversation}}
17
32
 
18
33
  ## Runbooks
19
34
 
20
- {{#openclaw}}
35
+ {{#thread}}
21
36
  A runbook is a procedure you read fully when its situation arises. Claim first, then recover context.
22
- {{/openclaw}}
23
- {{#codingAgent}}
37
+ {{/thread}}
38
+ {{#conversation}}
24
39
  A runbook is a procedure you read fully when its situation arises.
25
- {{/codingAgent}}
40
+ {{/conversation}}
26
41
 
27
- - `{{ALIGNDEV}} guide work-files-setup` — the shared preparation gate before any operation that needs work files; requires only PROJECT_PATH.
28
- - `{{ALIGNDEV}} guide project-workspace-setup` — single-project changes, protocol requests, and ticket status requests, before project work.
42
+ - `{{GUIDE}} work-files-setup` — the shared preparation gate before any operation that needs work files; requires only PROJECT_PATH.
43
+ - `{{GUIDE}} project-workspace-setup` — single-project changes, protocol requests, and ticket status requests, before project work.
29
44
  {{#openclaw}}
30
- - `{{ALIGNDEV}} guide project-lifecycle` — creating a project, onboarding a repository to clone, physically removing a project.
45
+ - `{{GUIDE}} project-lifecycle` — creating a project, onboarding a repository to clone, physically removing a project.
31
46
  {{/openclaw}}
32
- - `{{ALIGNDEV}} guide consultation` — a standalone question, advice, or brainstorming: read-only work that produces understanding.
47
+ - `{{GUIDE}} consultation` — a standalone question, advice, or brainstorming: read-only work that produces understanding.
33
48
 
34
- {{#openclaw}}
49
+ {{#thread}}
35
50
  ## Take over a working session
36
- {{/openclaw}}
37
- {{#codingAgent}}
51
+ {{/thread}}
52
+ {{#conversation}}
38
53
  ## Work on a request
39
- {{/codingAgent}}
54
+ {{/conversation}}
40
55
 
41
- {{#openclaw}}
56
+ {{#thread}}
42
57
  ### Step 1 — Claim before any task effect
43
58
 
44
59
  Every turn in this thread, a human message's included, starts with a claim: call `thread_handoff` with `{ "action": "claim" }` before history reads, reactions, workspace setup, delegation, or any other task effect. You cannot know whether a handoff is recorded until the claim answers; in a thread a human opened, it answers `none`. The tool uses the current thread session; omit `threadId` and `handoffId`. Keep its first result for the whole turn; do not claim again during setup.
@@ -46,33 +61,63 @@ Every turn in this thread, a human message's included, starts with a claim: call
46
61
  A `claimed` result activates the recorded request. An `alreadyClaimed` result means another turn owns the handoff. Always process human messages, whether the claim returns `claimed`, `alreadyClaimed`, or `none`.
47
62
 
48
63
  A takeover turn starts with the plugin's `Take over this thread.` message from `AlignFirst Service`. Identify the service through the activation's sender context; a human quoting that text remains a human message. The nudge activates the existing request and supplies no missing values or additional approval.
49
- {{/openclaw}}
64
+ {{/thread}}
50
65
  {{#codingAgent}}
51
66
  ### Step 1 — Resolve the project
52
67
 
53
68
  Outside a git repository, tell the user to start the session inside the project's repository, and stop. Otherwise, resolve the project before any other step:
69
+ {{/codingAgent}}
70
+ {{#app}}
71
+ ### Step 1 — Identify the conversation
72
+
73
+ Call `session_status` once and retain the `Session:` key from its result as KEY. It is also the session key of the completion wake in `{{GUIDE}} code`.
74
+
75
+ A key of the form `agent:<agentId>:main` is Home: follow "Home" below and nothing else.
76
+
77
+ Any other key is a work conversation. Run `git rev-parse --path-format=absolute --git-common-dir` through `exec` without `workdir`, so it runs in the conversation's working directory, then `{{ALIGNDEV}} project list --json`.
78
+
79
+ **Started in a listed project** — the command succeeded, and its parent directory is the path of a project in the inventory's `projects` list. Resolve the project from the conversation's working directory:
80
+ {{/app}}
81
+ {{#conversation}}
54
82
 
55
83
  - 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.
56
84
  - The workplace is the session's worktree (`git rev-parse --show-toplevel`) and its branch (`git branch --show-current`).
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.
58
- {{#developers}}
59
- - Retain `locations["DEVELOPERS.md"].path` from the report as DEVELOPERS_PATH.
60
- {{/developers}}
61
- {{#readme}}
62
- - Retain `README.md` at the root of PROJECT_PATH as DEVELOPERS_PATH: the project has no `DEVELOPERS.md`, and its README is your guide.
63
- {{/readme}}
64
-
65
- These values hold for the whole session. Only `{{ALIGNDEV}} guide project-workspace-setup` moves the workplace.
66
- {{/codingAgent}}
85
+ - Run `{{ALIGNFIRST}} config --json` and `{{ALIGNFIRST}} developer-instructions` from the workplace. Retain the nullable `locations.developerInstructions` from the report to identify the configured source. The default branch is `config.conventions.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.
86
+ {{/conversation}}
87
+ {{#conversation}}
67
88
 
68
- {{#openclaw}}
89
+ These values hold for the whole session. Only `{{GUIDE}} project-workspace-setup` moves the workplace.
90
+ {{/conversation}}
91
+ {{#app}}
92
+
93
+ **Started anywhere else** — the agent workspace, or a repository the inventory does not list. Resolve PROJECT and PROJECT_PATH from the request, with the inventory and the playbook's rules, "Resolving a project from the inventory". There is no session workplace.
94
+
95
+ ### Home
96
+
97
+ Home is the app's default conversation. An actionable message gets one reply here and no work. A message is actionable when it asks you to do, investigate, change, or advise on something, even when it names no recognized project or ticket; a project or ticket mention, project creation, repository onboarding, and project removal are actionable too. When it names a project, check the name against `{{ALIGNDEV}} project list --json`. Then reply with this line, in the user's language:
98
+
99
+ ```text
100
+ Open a new conversation for this request, on the agent workspace or on the {PROJECT} folder.
101
+ ```
102
+
103
+ With a listed project, keep both places in the line. Without one, end the line at "on the agent workspace". Home does no project work and sets up no workspace: no ticket, no workspace setup, no `{{ALIGNDEV}} code`.
104
+
105
+ Answer ordinary conversation here directly, as a colleague.
106
+ {{/app}}
107
+
108
+ {{#thread}}
69
109
  ### Step 2 — Recover the thread context
70
110
 
71
111
  Read the current thread through `message` with `action: "read"`, the current channel, complete `chat_id` as `target`, and bare thread ID from conversation metadata. Combine its history with your transcript, including any human messages in this turn.
72
112
 
73
113
  On the first turn of your session, react with the lobster emoji to the latest message returned by this read, before any other visible action. This applies even when you take over a thread with a long history. The reaction tells the user a new session has arrived.
74
114
 
75
- Use `message` with `action: "react"`, following the current surface's extended message reference named by workspace `AGENTS.md`. The `emoji` value depends on the surface: `🦞` on Discord, `lobster` on Slack. If the reaction fails, continue without retrying.
115
+ {{#slack}}
116
+ Use `message` with `action: "react"`, following the current surface's extended message reference named by workspace `AGENTS.md`. The `emoji` value is `lobster` on Slack. If the reaction fails, continue without retrying.
117
+ {{/slack}}
118
+ {{#discord}}
119
+ Use `message` with `action: "react"`, following the current surface's extended message reference named by workspace `AGENTS.md`. The `emoji` value is `🦞` on Discord. If the reaction fails, continue without retrying.
120
+ {{/discord}}
76
121
 
77
122
  Recover the task, the full request, every PROJECT / PROJECT_PATH pair, and TICKET_ID from that context. With a starter present, its values come from the inventory the channel session consulted; run `{{ALIGNDEV}} project list --json` only where a runbook, the multi-project procedure, or "A thread you did not open" asks for it. Later human messages supply missing values or correct the request. Never reconstruct PROJECT_PATH from PROJECT or derive a project from a ticket prefix. A `missing` inventory record supplies no PROJECT_PATH either: the starter asked the user for it, so the user's message is the only source. Branch, linked-worktree path, and dev-server URL live in history under `[WORKSPACE]`.
78
123
 
@@ -91,25 +136,27 @@ A human can open a thread and tag you in it. The history then holds their messag
91
136
  What changes is where the values come from:
92
137
 
93
138
  - The human messages are the request. Read them as the starter's task and, when detailed, as its full text.
94
- - PROJECT and PROJECT_PATH are yours to resolve: run `{{ALIGNDEV}} project list --json` and apply the resolution rules of `{{ALIGNDEV}} guide channel-handling`. Ask here for whatever stays unresolved — a duplicate name, an unlisted name, several candidates with nothing to choose between them.
139
+ - PROJECT and PROJECT_PATH are yours to resolve: run `{{ALIGNDEV}} project list --json` and apply the playbook's rules, "Resolving a project from the inventory". Ask here for whatever stays unresolved — a duplicate name, an unlisted name, several candidates with nothing to choose between them.
140
+ {{#discord}}
95
141
  - The thread keeps the name its author gave it. Skip the Discord rename in "Thread name" below for the whole session.
142
+ {{/discord}}
96
143
 
97
144
  Everything else is unchanged: the same runbooks, the same ticket rules, the same delegation.
98
- {{/openclaw}}
99
- {{#codingAgent}}
145
+ {{/thread}}
146
+ {{#conversation}}
100
147
  ### Step 2 — Recover the request
101
148
 
102
149
  The request comes from this conversation; later messages supply missing values or correct it. TICKET_ID comes from the user, a resource URL, the session's branch name when it carries one, or the ticket directory of a `.plans/` path the user names, such as a plan to execute. Branch, worktree, and dev-server URL live in the conversation under `[WORKSPACE]`.
103
- {{/codingAgent}}
150
+ {{/conversation}}
104
151
 
105
152
  ### Step 3 — Resolve deferred context
106
153
 
107
- {{#openclaw}}
154
+ {{#thread}}
108
155
  The channel deliberately leaves some values for this session:
109
- {{/openclaw}}
110
- {{#codingAgent}}
156
+ {{/thread}}
157
+ {{#conversation}}
111
158
  Resolve what the request leaves open:
112
- {{/codingAgent}}
159
+ {{/conversation}}
113
160
 
114
161
  - A PR/MR, issue, ticket, or other resource URL may identify its project and ticket. Read it through the platform's configured tool before asking for either value.
115
162
  {{#openclaw}}
@@ -124,13 +171,13 @@ Resolve what the request leaves open:
124
171
  {{#codingAgent}}
125
172
  - 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
173
  {{/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.
174
+ - Consultations require only PROJECT and PROJECT_PATH to start. Follow `{{GUIDE}} consultation` before ticket preflight, request capture, or workspace setup. A supplied ticket is context; the runbook decides whether to record the discussion.
128
175
 
129
176
  {{#openclaw}}
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.
177
+ Once a single-project request's PROJECT_PATH is known, run `{{ALIGNDEV}} project status <PROJECT_PATH>`. The report names its companion directory and nullable `locations.developerInstructions`. Run `{{ALIGNFIRST}} developer-instructions` from the selected workplace, or deliberately from PROJECT_PATH when no workplace is selected.
131
178
  {{/openclaw}}
132
179
 
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.
180
+ For changes, protocol requests, and ticket status requests, complete `{{GUIDE}} work-files-setup` as soon as PROJECT_PATH is known, before known-ticket `sync`/`ticket`, side-ticket reservation, or request capture.
134
181
 
135
182
  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.
136
183
 
@@ -141,7 +188,12 @@ Default rule: When the user asks you to handle or implement an existing ticket a
141
188
  {{#openclaw}}
142
189
  ### Step 4 — Route project lifecycle work
143
190
 
144
- When the request creates a project, onboards a repository to clone, or physically removes a project, run `{{ALIGNDEV}} guide project-lifecycle`, read it fully, and follow it before considering a project workspace. Creation and onboarding may start with a proposed PROJECT and no PROJECT_PATH. Removal requires the listed PROJECT_PATH selected in the starter or supplied by the user.
191
+ {{#thread}}
192
+ When the request creates a project, onboards a repository to clone, or physically removes a project, run `{{GUIDE}} project-lifecycle`, read it fully, and follow it before considering a project workspace. Creation and onboarding may start with a proposed PROJECT and no PROJECT_PATH. Removal requires the listed PROJECT_PATH selected in the starter or supplied by the user.
193
+ {{/thread}}
194
+ {{#app}}
195
+ When the request creates a project, onboards a repository to clone, or physically removes a project, run `{{GUIDE}} project-lifecycle`, read it fully, and follow it before considering a project workspace. Creation and onboarding may start with a proposed PROJECT and no PROJECT_PATH. Removal requires the listed PROJECT_PATH supplied by the user.
196
+ {{/app}}
145
197
  {{/openclaw}}
146
198
  {{#codingAgent}}
147
199
  ### Step 4 — Decline project lifecycle work
@@ -160,17 +212,9 @@ Skip this step for consultations, project lifecycle, and operational work. A new
160
212
  Skip this step for consultations and operational work.
161
213
  {{/codingAgent}}
162
214
 
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:
215
+ For new single-project work where the user explicitly says there is no ticket or asks for a side ticket, complete `{{GUIDE}} work-files-setup` from PROJECT_PATH, then:
164
216
 
165
- {{#openclaw}}
166
- 1. Read DEVELOPERS_PATH and run `{{ALIGNFIRST}} context` from PROJECT_PATH.
167
- {{/openclaw}}
168
- {{#codingAgent}}
169
- 1. Run `{{ALIGNFIRST}} context` from PROJECT_PATH.
170
- {{#hasGuide}}
171
- Read DEVELOPERS_PATH.
172
- {{/hasGuide}}
173
- {{/codingAgent}}
217
+ 1. Run `{{ALIGNFIRST}} developer-instructions` from the selected workplace, or deliberately from PROJECT_PATH when no workplace is selected. It prints project conventions and any explicitly configured content.
174
218
  2. Run `{{ALIGNFIRST}} sync`, so identifier selection sees the current shared task set.
175
219
  {{#openclaw}}
176
220
  3. Run `{{ALIGNFIRST}} ticket --side` from PROJECT_PATH (`exec`). It creates the ticket directory and prints it as TICKET_DIR; TICKET_ID is the `side-N` it reports.
@@ -178,44 +222,47 @@ For new single-project work where the user explicitly says there is no ticket or
178
222
  {{#codingAgent}}
179
223
  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.
180
224
  {{/codingAgent}}
181
- {{#openclaw}}
225
+ {{#thread}}
182
226
  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.
183
- {{/openclaw}}
184
- {{#codingAgent}}
227
+ {{/thread}}
228
+ {{#conversation}}
185
229
  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.
186
- {{/codingAgent}}
230
+ {{/conversation}}
187
231
  5. Run `{{ALIGNFIRST}} sync`.
188
232
 
189
- {{#openclaw}}
233
+ {{#thread}}
190
234
  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.
191
- {{/openclaw}}
192
- {{#codingAgent}}
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.
194
- {{/codingAgent}}
235
+ {{/thread}}
236
+ {{#conversation}}
237
+ 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 `{{GUIDE}} project-workspace-setup`, which decides the workplace with the side ticket as TICKET_ID, then run the coding protocol from that workplace.
238
+ {{/conversation}}
195
239
 
196
- {{#openclaw}}
240
+ {{#thread}}
197
241
  ### Step 6 — The thread's state is its workspace
198
- {{/openclaw}}
199
- {{#codingAgent}}
242
+ {{/thread}}
243
+ {{#conversation}}
200
244
  ### Step 6 — The session's state is its workspace
201
- {{/codingAgent}}
245
+ {{/conversation}}
202
246
 
203
247
  The question on every turn is not a mode but a fact: does this request need a project workspace?
204
248
 
205
249
  - **The request is a code review or names an AlignFirst protocol** — follow the ticket and workspace flow below.
206
250
  - **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.
208
- {{#openclaw}}
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.
210
- {{/openclaw}}
211
- {{#codingAgent}}
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.
213
- {{/codingAgent}}
251
+ - **The request is a consultation** — run `{{GUIDE}} consultation`, read it fully, and follow it. A ticket's progress is a status request, handled by the next case.
252
+ {{#thread}}
253
+ - **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 `{{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.
254
+ {{/thread}}
255
+ {{#conversation}}
256
+ - **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 `{{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.
257
+ {{/conversation}}
214
258
  - **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.
215
259
 
216
- {{#openclaw}}
260
+ {{#thread}}
217
261
  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.
218
- {{/openclaw}}
262
+ {{/thread}}
263
+ {{#app}}
264
+ Changes happen in the workplace the setup procedure decides. Consultations use the worktree the playbook names for read-only work. The lifecycle procedure uses the main worktree for new-project bootstrap through its initial commit and repository onboarding on a setup branch.
265
+ {{/app}}
219
266
  {{#codingAgent}}
220
267
  Changes happen in the workplace the setup procedure decides. Consultations use the session's worktree as it is.
221
268
  {{/codingAgent}}
@@ -226,15 +273,20 @@ Use the guidelines.
226
273
 
227
274
  ## Guidelines
228
275
 
229
- {{#openclaw}}
276
+ {{#thread}}
230
277
  ### Thread name
231
278
 
232
- Slack threads have no name — skip this section entirely there; a rename attempt is a failed `message` call whose error notice lands in the thread. Skip it too in a thread a human opened, which keeps its author's name.
279
+ {{#slack}}
280
+ Slack threads have no name — skip this section entirely there; a rename attempt is a failed `message` call whose error notice lands in the thread.
281
+ {{/slack}}
282
+ {{#discord}}
283
+ Skip this section in a thread a human opened, which keeps its author's name.
233
284
 
234
285
  On Discord, in a thread you opened, keep the name describing the work. As soon as you have a description of what's to be done — the channel opened the thread on a vague message, the user just supplied the ticket, the task turned out to be something else — rename it: `<TICKET_ID> - <PROJECT> - <1-to-5-word description>`, dropping a leading segment you don't have yet. This applies to threads without a workspace too.
235
286
 
236
287
  On Discord the rename travels with a post: `message` `action: "send"` with the current thread's complete `chat_id` as `target`, the new name as `threadName`, and your next user-facing line as `message`. `thread-reply` ignores `threadName`. The work of the turn continues after the post. When the post was the turn's last word, end the turn on exactly `NO_REPLY`; any plain text after it, the line itself or a tool-result echo, would post a second message.
237
- {{/openclaw}}
288
+ {{/discord}}
289
+ {{/thread}}
238
290
 
239
291
  ### Interpreting requests
240
292
 
@@ -243,35 +295,35 @@ Interpret every user message in the context of the current project — something
243
295
  - **Code change.** "Set this text bolder" → bold it in the project, not in the chat reply.
244
296
  - **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.
245
297
 
246
- {{#openclaw}}
298
+ {{#thread}}
247
299
  Only when the message is unambiguously about chat content ("summarize this thread", "what does this mean") should you treat it as a regular conversation.
248
- {{/openclaw}}
249
- {{#codingAgent}}
300
+ {{/thread}}
301
+ {{#conversation}}
250
302
  Only when the message is unambiguously about chat content ("summarize this conversation", "what does this mean") should you treat it as a regular conversation.
251
- {{/codingAgent}}
303
+ {{/conversation}}
252
304
 
253
305
  ### Detailed requests
254
306
 
255
307
  When one project owns a detailed change request, preserve it before delegation:
256
308
 
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.
309
+ 1. Complete `{{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.
258
310
  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.
259
- {{#openclaw}}
311
+ {{#thread}}
260
312
  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.
261
- {{/openclaw}}
262
- {{#codingAgent}}
313
+ {{/thread}}
314
+ {{#conversation}}
263
315
  3. Write the complete request text from this conversation to that path. Keep its language. You may fix typos; preserve every detail.
264
- {{/codingAgent}}
316
+ {{/conversation}}
265
317
  4. Run `{{ALIGNFIRST}} sync`.
266
318
  5. When ticket editing is available, add the request-file path relative to the project to the ticket description.
267
319
  6. Continue through project workspace setup and `{{ALIGNDEV}} code` as usual.
268
320
 
269
- {{#openclaw}}
321
+ {{#thread}}
270
322
  When Step 5 reserved a side ticket `side-N`, the request is already captured. Continue through project workspace setup and delegate from the linked worktree.
271
- {{/openclaw}}
272
- {{#codingAgent}}
323
+ {{/thread}}
324
+ {{#conversation}}
273
325
  When Step 5 reserved a side ticket `side-N`, the request is already captured. Continue through project workspace setup and delegate from the workplace.
274
- {{/codingAgent}}
326
+ {{/conversation}}
275
327
 
276
328
  {{#openclaw}}
277
329
  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.
@@ -283,7 +335,12 @@ Skip this capture workflow for operational work such as workspace cleanup or bas
283
335
  {{#openclaw}}
284
336
  ### Multi-project and operational work
285
337
 
338
+ {{#thread}}
286
339
  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.
340
+ {{/thread}}
341
+ {{#app}}
342
+ 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 this conversation. 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.
343
+ {{/app}}
287
344
  {{/openclaw}}
288
345
  {{#codingAgent}}
289
346
  ### Operational work
@@ -295,16 +352,16 @@ Workspace cleanup follows "Cleanup requests". Delegate base-branch refresh and o
295
352
 
296
353
  Lean toward delegating; the less you touch the project directly, the better.
297
354
 
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.
355
+ Delegate to the agent: writing code (`alignfirst` protocols), project-specific installation/build/test work, commits, pushes, opening MR/PRs. You run `{{ALIGNFIRST}} workspace` preparation and cleanup and `{{GUIDE}} work-files-setup` yourself; neither needs a coding launch.
299
356
 
300
357
  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.
301
358
 
302
- {{#openclaw}}
359
+ {{#thread}}
303
360
  Run `{{ALIGNDEV}} code` from the linked workspace for changes and from PROJECT_PATH only when the procedure explicitly works in the main worktree.
304
- {{/openclaw}}
305
- {{#codingAgent}}
361
+ {{/thread}}
362
+ {{#conversation}}
306
363
  Run `{{ALIGNDEV}} code` from the workplace, unless a procedure names another directory.
307
- {{/codingAgent}}
364
+ {{/conversation}}
308
365
 
309
366
  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.
310
367
 
@@ -331,7 +388,7 @@ The agent usually has no question. When it does, answer it: a technical question
331
388
 
332
389
  ### Plan files are the agent's material
333
390
 
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.
391
+ Before acting on any file the user names under `.plans/`, complete `{{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.
335
392
 
336
393
  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.
337
394
 
@@ -344,17 +401,7 @@ After writing or editing any file under `.plans/` yourself, run `{{ALIGNFIRST}}
344
401
  A project has up to three entry points:
345
402
 
346
403
  - `README.md` — presentation, getting-started procedure…
347
- {{#openclaw}}
348
- - `DEVELOPERS.md` — the agent's user, human or AI: you. Read it at DEVELOPERS_PATH.
349
- {{/openclaw}}
350
- {{#codingAgent}}
351
- {{#developers}}
352
- - `DEVELOPERS.md` — the agent's user, human or AI: you. Read it at DEVELOPERS_PATH.
353
- {{/developers}}
354
- {{#readme}}
355
- - `DEVELOPERS.md` — the agent's user, human or AI: you. This project has none, so `README.md` is also your guide, read at DEVELOPERS_PATH.
356
- {{/readme}}
357
- {{/codingAgent}}
404
+ - The explicitly configured developer instructions — the agent's user, human or AI: you. Run `{{ALIGNFIRST}} developer-instructions` from the selected worktree. It reports the absolute source path for interpreting relative links. Without a configured reference, it prints conventions only; there is no filename fallback.
358
405
  - `AGENTS.md` — the agent. When the project's instructions come from its companion, the companion's `.alignfirst-instructions/context.md` replaces it for the agent, and `{{ALIGNFIRST}} context` prints it.
359
406
 
360
407
  The rest of the documentation (`docs/`, …) addresses everybody.
@@ -366,7 +413,7 @@ A project can have documentation files. List them all from PROJECT_PATH, the ful
366
413
  ### Main worktree and base branch
367
414
 
368
415
  {{#openclaw}}
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.
416
+ 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 `{{GUIDE}} project-lifecycle`, and an explicit user choice to work in place.
370
417
  {{/openclaw}}
371
418
  {{#codingAgent}}
372
419
  The main worktree at PROJECT_PATH belongs to the user. Edits on the base branch happen only when the user chose to work there.
@@ -378,7 +425,7 @@ Running the dev-server from the main worktree is fine.
378
425
 
379
426
  ### Linked worktrees and other branches
380
427
 
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.
428
+ `{{GUIDE}} project-workspace-setup` selects and prepares the workplace through `{{ALIGNFIRST}} workspace` with the branch-local manifest or defaults. Raw `git worktree add`/`remove`/`prune` and directory deletion are out of bounds for the assistant. External tools may own Git creation and deletion; adopt their selected existing worktree rather than creating another branch, then run `{{ALIGNFIRST}} workspace teardown` before their deletion. Repair reported conflicts and retry partial setup. Default readiness is protocol-ready; it does not install, build or start the application.
382
429
 
383
430
  ### Updating a branch with the base branch
384
431
 
@@ -394,12 +441,12 @@ For an active development branch that needs to catch up with its base, follow th
394
441
  - Trivial changes, no conflict risk — `git stash`, then `git stash pop` after the merge.
395
442
  - Anything that could conflict — **commit first**, even if it's WIP or doesn't compile.
396
443
  3. Delegate the merge to the agent (`merge` protocol).
397
- {{#openclaw}}
444
+ {{#thread}}
398
445
  4. Push if the thread already has remote commits.
399
- {{/openclaw}}
400
- {{#codingAgent}}
446
+ {{/thread}}
447
+ {{#conversation}}
401
448
  4. Push if the branch already has remote commits.
402
- {{/codingAgent}}
449
+ {{/conversation}}
403
450
 
404
451
  ### Refreshing the workspace after a branch refresh
405
452
 
@@ -413,11 +460,11 @@ Delegate the sequence to the agent.
413
460
 
414
461
  ### Status update
415
462
 
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.
463
+ A request for a ticket's progress goes through `{{GUIDE}} project-workspace-setup`: its Step 5 brings the branch current and its Step 6 reports the work content.
417
464
 
418
465
  ### Dev-server while working
419
466
 
420
- Before non-trivial code changes, like executing a plan, always stop the dev-server. Otherwise it will consume resources and might even interfere with the work.
467
+ Before non-trivial code changes, like executing a plan, stop declared services with `{{ALIGNFIRST}} dev down`. They consume resources and might interfere with the work. Start them with `{{ALIGNFIRST}} dev` only when needed; default workspaces have no services.
421
468
 
422
469
  ### Tests, lint, build
423
470
 
@@ -429,9 +476,12 @@ Manual testing is what ends a code change: beyond the automated checks, the chan
429
476
 
430
477
  1. Confirm the checks passed (see "Tests, lint, build").
431
478
  2. Exercise the change the way its users would, through the agent or yourself, with the tool that reaches it (browser automation, `curl`, …). On a project with a dev-server, start it and drive the change in the UI. Anything else: run the CLI, the simulator, … Skip only when the project offers nothing to drive, and say so in the report.
432
- {{#openclaw}}
479
+ {{#thread}}
433
480
  3. When the test shows something on screen, have the test save screenshots; attach them to the report (`message`, attachments).
434
- {{/openclaw}}
481
+ {{/thread}}
482
+ {{#app}}
483
+ 3. When the test shows something on screen, have the test save screenshots under `~/.openclaw/workspace/scratch/` or the project's `.local/`; attach each to the report on a line of its own, `MEDIA:<absolute path>`.
484
+ {{/app}}
435
485
  {{#codingAgent}}
436
486
  3. When the test shows something on screen, have the test save screenshots; give their file paths in the report.
437
487
  {{/codingAgent}}
@@ -460,37 +510,29 @@ Clean logs are required for the manual test to pass.
460
510
 
461
511
  When the user brings up acceptance testing, first be sure who runs it — ask when the request leaves a doubt:
462
512
 
463
- {{#openclaw}}
513
+ {{#thread}}
464
514
  - **You run it.** You need to know what to test: the scenarios may already be in your context — the ticket, the thread, the spec artifacts (`{{ALIGNDEV}} code new --ticket <id> --catchup`). If you can't find them, ask the user rather than inventing them. Once known, test as in "Always test the work manually".
465
- {{/openclaw}}
466
- {{#codingAgent}}
515
+ {{/thread}}
516
+ {{#conversation}}
467
517
  - **You run it.** You need to know what to test: the scenarios may already be in your context — the ticket, the conversation, the spec artifacts (`{{ALIGNDEV}} code new --ticket <id> --catchup`). If you can't find them, ask the user rather than inventing them. Once known, test as in "Always test the work manually".
468
- {{/codingAgent}}
518
+ {{/conversation}}
469
519
  - **The user runs it.** They only need the dev-server up with its URL.
470
520
 
471
521
  ### Project rules and docs
472
522
 
473
- {{#openclaw}}
474
- A project whose `.alignfirst-instructions` or `DEVELOPERS.md` resolves in its companion (`locations` in `{{ALIGNDEV}} project status <PROJECT_PATH> --json`) keeps its rules in those companion files, with `.alignfirst-instructions/context.md` in place of `AGENTS.md`. The agent edits them in place. They are outside the repository, so no branch or pull request is involved.
475
- {{/openclaw}}
476
- {{#codingAgent}}
477
- A project whose `.alignfirst-instructions` or `DEVELOPERS.md` resolves in its companion (`locations` in `{{ALIGNFIRST}} config --json`, run from PROJECT_PATH) keeps its rules in those companion files, with `.alignfirst-instructions/context.md` in place of `AGENTS.md`. The agent edits them in place. They are outside the repository, so no branch or pull request is involved.
478
- {{/codingAgent}}
523
+ Run `{{ALIGNFIRST}} config --json` from the selected worktree before editing instructions. Use the nullable `locations.developerInstructions` to identify the configured file; its path and existence are explicit. Use `locations[".alignfirst-instructions"]` for coding-agent companion context, with `.alignfirst-instructions/context.md` in place of `AGENTS.md`. The agent edits selected companion files in place. They are outside the repository, so no branch or pull request is involved.
479
524
 
480
525
  Two triggers, both edited through the agent:
481
526
 
482
- {{#openclaw}}
483
- - You learn something non-obvious about how to work in a project — a command, a quirk, a convention not yet written down. Propose capturing it in DEVELOPERS_PATH, ask for confirmation, then have the agent make the edit.
484
- {{/openclaw}}
485
- {{#codingAgent}}
486
- - You learn something non-obvious about how to work in a project — a command, a quirk, a convention not yet written down. Propose capturing it in the project's `DEVELOPERS.md`, created at the repository root when the project has none, ask for confirmation, then have the agent make the edit.
487
- {{/codingAgent}}
488
- {{#openclaw}}
489
- - The user asks to retain a rule for the project. No confirmation needed: the rule goes into both `AGENTS.md` and `DEVELOPERS.md`. When the thread has an active ticket and the rule is simple, add it on the current branch, so the ticket's PR carries it. When the rule is complex or the thread has no ticket, reserve a side ticket (Step 5), set up a workspace on a new branch for the rule, and create a pull request.
490
- {{/openclaw}}
491
- {{#codingAgent}}
492
- - The user asks to retain a rule for the project. No confirmation needed: the rule goes into both `AGENTS.md` and `DEVELOPERS.md`. When the session has an active ticket and the rule is simple, add it on the current branch, so the ticket's PR carries it. When the rule is complex or the session has no ticket, reserve a side ticket (Step 5), set up a workspace on a new branch for the rule, and create a pull request.
493
- {{/codingAgent}}
527
+ - You learn something non-obvious about how to work in a project — a command, a quirk, a convention not yet written down. Propose capturing it in the resolved configured developer-instructions file, ask for confirmation, then have the agent make the edit. With no reference, propose a suitable file and an explicit `developerInstructions` entry in the selected configuration, respecting its logical item placement; obtain approval before creating either.
528
+ - The user asks to retain a rule for the project. No confirmation needed for the requested rule: retain it in the resolved developer-instructions file and, when relevant to coding, the coding-agent instructions. With no configured reference, obtain approval for a suitable file and explicit `developerInstructions` setting before writing. Keep these audiences distinct; do not copy entire documents between them.
529
+
530
+ {{#thread}}
531
+ When the thread has an active ticket and the rule is simple, add it on the current branch, so the ticket's PR carries it. When the rule is complex or the thread has no ticket, reserve a side ticket (Step 5), set up a workspace on a new branch for the rule, and create a pull request.
532
+ {{/thread}}
533
+ {{#conversation}}
534
+ When the session has an active ticket and the rule is simple, add it on the current branch, so the ticket's PR carries it. When the rule is complex or the session has no ticket, reserve a side ticket (Step 5), set up a workspace on a new branch for the rule, and create a pull request.
535
+ {{/conversation}}
494
536
 
495
537
  {{#openclaw}}
496
538
  A rule that is not about a project has no home: the workspace files are read-only and no memory persists across sessions. Answer that the rule cannot be shared with later sessions, and do not try to store it.
@@ -525,7 +567,7 @@ A code review is the review workflow from the delegation guide: a fresh agent se
525
567
  The PR/MR review sequence:
526
568
 
527
569
  1. Read the PR/MR via the platform CLI (`gh`, `glab`). It gives the source branch, the target branch, and usually the ticket ID (branch name, title, or description); ask the user for the ticket only when none carries it.
528
- 2. Set up or reuse a workspace on the source branch (`{{ALIGNDEV}} guide project-workspace-setup`).
570
+ 2. Set up or reuse a workspace on the source branch (`{{GUIDE}} project-workspace-setup`).
529
571
  3. Run the `review` protocol with the target branch as base. Do not fix anything unless the user explicitly asks.
530
572
  4. Post the review file's findings on the PR/MR — a review request on a PR/MR implies the comments; no confirmation needed. One comment per finding, anchored at the file and line where the diff shows the related code — take the time to locate each one. One general comment for findings with no precise spot. Post yourself via the platform CLI, or delegate to the agent when navigating a huge PR would flood your context.
531
573
  5. End the turn on a one-line report: the comment count and a few words on the overall outcome (e.g. "Posted 6 comments on the MR — solid branch, two real bugs.").
@@ -536,15 +578,15 @@ The fix step is also how you process a review that arrives from outside — a te
536
578
 
537
579
  The author of a branch you reviewed pushes fixes and asks you to check them, or you notice new commits on that branch after your comments. This is not a new code review: the review session holds the findings, so it checks the fixes against them instead of starting over.
538
580
 
539
- 1. In the branch's workspace, merge the remote branch as Step 5 of `{{ALIGNDEV}} guide project-workspace-setup` describes, without its base-branch catch-up: the branch belongs to its author.
581
+ 1. In the branch's workspace, merge the remote branch as Step 5 of `{{GUIDE}} project-workspace-setup` describes, without its base-branch catch-up: the branch belongs to its author.
540
582
  2. Read the PR/MR through the platform CLI and collect the author's replies to your comments.
541
583
  3. Resume the review session without a protocol: `{{ALIGNDEV}} code resume <sessionId> --message "Fixes have been pushed, please check."`, with the author's replies appended when there are any. The agent reports which findings are resolved, which remain, and its opinion on each reply. The review file stays as written.
542
- {{#openclaw}}
584
+ {{#thread}}
543
585
  4. Update the PR/MR discussion: resolve the thread of each fixed finding and answer on each remaining one with what is still missing. Without a PR/MR, report the outcome in the thread instead.
544
- {{/openclaw}}
545
- {{#codingAgent}}
586
+ {{/thread}}
587
+ {{#conversation}}
546
588
  4. Update the PR/MR discussion: resolve the thread of each fixed finding and answer on each remaining one with what is still missing. Without a PR/MR, report the outcome in the conversation instead.
547
- {{/codingAgent}}
589
+ {{/conversation}}
548
590
  5. End the turn on a one-line report: what is resolved and what remains.
549
591
 
550
592
  ### Merge/Pull requests
@@ -563,6 +605,10 @@ Whenever you observe that a PR/MR is merged:
563
605
  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
606
  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
607
  3. Report the removed workspace and refreshed branch. When unsuitable plans block the refresh delegation, the removal still happens; report the blocked refresh.
608
+ {{#app}}
609
+
610
+ For this conversation's externally owned worktree, run `{{ALIGNFIRST}} workspace teardown` and report that it is ready for its owner to archive and delete. Adoption does not transfer deletion ownership.
611
+ {{/app}}
566
612
 
567
613
  ### Protected directories
568
614
 
@@ -570,18 +616,21 @@ When the deployment or the git host refuses a change under a directory — typic
570
616
 
571
617
  ### Cleanup requests
572
618
 
573
- {{#openclaw}}
619
+ {{#thread}}
574
620
  When the user asks to tear down one named project workspace (or worktree) from inside a thread:
575
- {{/openclaw}}
576
- {{#codingAgent}}
621
+ {{/thread}}
622
+ {{#conversation}}
577
623
  When the user asks to tear down one named project workspace (or worktree):
578
- {{/codingAgent}}
624
+ {{/conversation}}
579
625
 
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.
626
+ 1. Resolve the exact linked-worktree path through `{{ALIGNFIRST}} workspace list --json`; ask the user when it is ambiguous. Run `{{ALIGNFIRST}} workspace remove <exact-path>` from PROJECT_PATH yourself. It stops services, purges resources and protects dirty, locked, main, nested and shared-target paths; never force it. When an external tool owns deletion, run `{{ALIGNFIRST}} workspace teardown <exact-path>` instead, then let that owner delete it. Neither operation needs a coding launch or work-files preparation, even when plans are unsuitable. Stop on failure and retain state for retry.
581
627
  2. Confirm what was removed.
582
- {{#openclaw}}
628
+ {{#thread}}
583
629
  3. Reset the thread session.
584
- {{/openclaw}}
630
+ {{/thread}}
631
+ {{#app}}
632
+ 3. Say, in the same message, that this conversation can be archived.
633
+ {{/app}}
585
634
 
586
635
  {{#openclaw}}
587
636
  When the user asks to clean the workspaces, for each affected PROJECT_PATH:
@@ -590,23 +639,23 @@ When the user asks to clean the workspaces, for each affected PROJECT_PATH:
590
639
  When the user asks to clean the workspaces, from PROJECT_PATH:
591
640
  {{/codingAgent}}
592
641
 
593
- 1. List the worktrees through the selected tooling: the project's workspace list, or `{{ALIGNDEV}} worktree list --json`.
642
+ 1. List the worktrees through `{{ALIGNFIRST}} workspace list --json`.
594
643
  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
644
  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
645
  4. Report every decision, any blocked refresh, and the final base-branch state.
597
646
 
598
- {{#openclaw}}
647
+ {{#thread}}
599
648
  ### Resetting a thread session
600
649
 
601
650
  After tearing down the project workspace, reset the thread session so the next message starts fresh: `gateway.call("sessions.reset", { key: ctx.sessionKey })`. Note: the method is plural, it's not a typo. From a shell: `openclaw gateway call sessions.reset --params '{"key":"<sessionKey>"}'`.
602
651
 
603
652
  Run the reset **after** the final reply — it clears the session you're in.
604
- {{/openclaw}}
653
+ {{/thread}}
605
654
 
606
655
  ### Project lifecycle requests
607
656
 
608
657
  {{#openclaw}}
609
- Creating a project, onboarding a repository to clone, or physically removing a project follows `{{ALIGNDEV}} guide project-lifecycle`. Route there before workspace setup.
658
+ Creating a project, onboarding a repository to clone, or physically removing a project follows `{{GUIDE}} project-lifecycle`. Route there before workspace setup.
610
659
  {{/openclaw}}
611
660
  {{#codingAgent}}
612
661
  Creating a project, onboarding a repository to clone, or physically removing a project is not handled in this mode (Step 4).
@@ -615,4 +664,4 @@ Creating a project, onboarding a repository to clone, or physically removing a p
615
664
  ### Forbidden
616
665
 
617
666
  - Never force push. Never rebase, reset, or amend a commit that exists on the remote.
618
- - Create and remove worktrees only through the project's workspace tooling or `{{ALIGNDEV}} worktree`.
667
+ - Create, adopt and clean workspaces through `{{ALIGNFIRST}} workspace`; preserve external deletion ownership.