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.
- package/README.md +21 -13
- package/dist/cli.js +11 -1
- package/dist/code/code-cli.js +20 -7
- package/dist/code/native-context.js +5 -3
- package/dist/config.d.ts +2 -2
- package/dist/config.js +16 -11
- package/dist/guide/topics.js +2 -1
- package/dist/project/plans.d.ts +9 -0
- package/dist/project/plans.js +40 -0
- package/dist/project/status.js +6 -24
- package/dist/worktree/add.d.ts +20 -0
- package/dist/worktree/add.js +175 -0
- package/dist/worktree/git.d.ts +24 -0
- package/dist/worktree/git.js +103 -0
- package/dist/worktree/remove.d.ts +8 -0
- package/dist/worktree/remove.js +62 -0
- package/dist/worktree/worktree-cli.d.ts +10 -0
- package/dist/worktree/worktree-cli.js +122 -0
- package/package.json +1 -1
- package/templates/guide/code.md +8 -23
- package/templates/guide/playbook/channel-handling.md +6 -4
- package/templates/guide/playbook/consultation.md +5 -3
- package/templates/guide/playbook/playbook.md +7 -26
- package/templates/guide/playbook/project-lifecycle.md +18 -16
- package/templates/guide/playbook/project-workspace-setup.md +20 -53
- package/templates/guide/playbook/work-files-setup.md +33 -0
- package/templates/guide/playbook/working-session.md +54 -90
|
@@ -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` —
|
|
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
|
|
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,
|
|
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
|
|
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
|
|
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
|
|
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
|
-
|
|
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
|
|
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** —
|
|
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** —
|
|
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
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
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,
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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.
|
|
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
|
|
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
|
-
|
|
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
|
-
{{
|
|
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
|
-
{{
|
|
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
|
-
|
|
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
|
|
561
|
+
Whenever you observe that a PR/MR is merged:
|
|
591
562
|
|
|
592
|
-
|
|
593
|
-
|
|
594
|
-
|
|
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.
|
|
615
|
-
2. Confirm
|
|
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,
|
|
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,
|
|
590
|
+
When the user asks to clean the workspaces, from PROJECT_PATH:
|
|
625
591
|
{{/codingAgent}}
|
|
626
592
|
|
|
627
|
-
|
|
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
|
-
{{
|
|
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`.
|