aligndev 0.26.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.
@@ -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`.