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.
@@ -1,6 +1,6 @@
1
1
  # Runbook: Project lifecycle
2
2
 
3
- Use this procedure only to create a project, onboard a repository to clone, or physically remove a project. Project-workspace creation and cleanup follow `{{ALIGNDEV}} guide project-workspace-setup` and the project's workspace tooling.
3
+ Use this procedure only to create a project, onboard a repository to clone, or physically remove a project. Project-workspace creation and cleanup follow `{{ALIGNDEV}} guide project-workspace-setup`.
4
4
 
5
5
  ## Start with the project guide
6
6
 
@@ -21,8 +21,8 @@ Creation has a hard user-input gate. Before any filesystem, Git, port-allocation
21
21
  1. Settle the stack, allowed parent directory, project name, and port requirements with the user. Use the `{{ALIGNDEV}} guide project` output to constrain the choices.
22
22
  2. Create the main-worktree directory under the selected allowed parent. Initialize its Git repository on `main`.
23
23
  3. Once the directory contains its `.git` directory, retain the canonical path as PROJECT_PATH. When the project declares ports, run `{{ALIGNDEV}} project free-ports --root <selected parent directory> --size <port names × concurrent workspaces> [--range <code>]` and retain the block; preparation through the setup guide writes it into `.alignfirst.json`. The selected parent's marker owns its port range. Report that `.alignfirst.json` was written and name the block.
24
- 4. Create `.plans/`, then run `{{ALIGNFIRST}} sync`. With an external ticket, run `{{ALIGNFIRST}} ticket {TICKET_ID} --next request.md` and append FILE_NAME to TICKET_DIR, exactly as printed, to get the path. Otherwise run `{{ALIGNFIRST}} ticket --side`; TICKET_ID is the reported `side-N`, and the path is `{TICKET_DIR}A1-request.md`. Write the complete creation request there from the starter and every later human message that supplied the gate's values. Record the project name, selected parent, stack, port requirements, and requested stopping point; never copy only the starter's task line. Then run `{{ALIGNFIRST}} sync`. The bot chooses the identifier and writes the request; the agent does neither. A later plans setup migrates this content when it replaces the directory with a symlink.
25
- 5. Before delegating the bootstrap, run `{{ALIGNDEV}} guide code`. On a takeover turn, apply the pre-delegation race checkpoint in the playbook (`{{ALIGNDEV}} guide`) immediately before `{{ALIGNDEV}} code new`. Then bootstrap directly from PROJECT_PATH through `{{ALIGNDEV}} code new --message`, with no protocol. Explicitly instruct it to use `alignfirst-setup-guide` and prepare the repository for an assistant. It must run `{{ALIGNDEV}} project doctor` after writing `.alignfirst.json` and before workspace setup, stopping on an unhealthy inventory. Include `.local/` as a gitignored shared directory in the workspace mechanism. Follow the selected stack and the host-specific guide.
24
+ 4. Complete `{{ALIGNDEV}} guide work-files-setup` with the approved bootstrap scope, then run `{{ALIGNFIRST}} sync`. With an external ticket, run `{{ALIGNFIRST}} ticket {TICKET_ID} --next request.md` and append FILE_NAME to TICKET_DIR, exactly as printed, to get the path. Otherwise run `{{ALIGNFIRST}} ticket --side`; TICKET_ID is the reported `side-N`, and the path is `{TICKET_DIR}A1-request.md`. Write the complete creation request there from the starter and every later human message that supplied the gate's values. Record the project name, selected parent, stack, port requirements, and requested stopping point; never copy only the starter's task line. Then run `{{ALIGNFIRST}} sync`. You choose the identifier and write the request; the agent does neither. A later plans setup migrates this content when it replaces the directory with a symlink.
25
+ 5. Before delegating the bootstrap, run `{{ALIGNDEV}} guide code`. On a takeover turn, apply the pre-delegation race checkpoint in the playbook (`{{ALIGNDEV}} guide`) immediately before `{{ALIGNDEV}} code new`. Then bootstrap directly from PROJECT_PATH through `{{ALIGNDEV}} code new --message`, with no protocol. Explicitly instruct it to use `alignfirst-setup-guide` and prepare the repository for an assistant. It must run `{{ALIGNDEV}} project doctor` after writing `.alignfirst.json` and before workspace setup, stopping on an unhealthy inventory. The workspace system is optional. When the project installs it, include `.local/` as a gitignored shared directory in its mechanism; otherwise the project uses `{{ALIGNDEV}} worktree` and documents its install/build/test preparation. Follow the selected stack and the host-specific guide.
26
26
  6. Verify the project through the setup guide, run `{{ALIGNFIRST}} sync`, and make its initial commit on `main` in PROJECT_PATH. Do not ask for confirmation before committing.
27
27
  7. When a remote destination is known from the request, environment, or host instructions, configure it when needed and push `main`. Do not ask for confirmation before pushing. When no destination is known, or the user requested a local-only project, leave the committed project local and report that no remote was configured.
28
28
  8. After that commit and push when applicable, return to the normal working-session flow. Every subsequent branch change uses a linked project workspace.
@@ -44,7 +44,7 @@ Before any discussion:
44
44
 
45
45
  ### Step 2 — Check the AlignDev contract
46
46
 
47
- The contract is the one the `alignfirst-setup-guide` lists under "Prepare a Project for an Assistant": the `alignfirst context` bootstrap section, docmap, the workspace system, and a `DEVELOPERS.md` with a workspaces section. The workspace system and its section belong to the contract only for a project that installs them; a project without them runs in main-worktree mode. When DEVELOPERS_PATH exists, the project is prepared: continue with the normal working-session flow for the user's request. Otherwise, continue to Step 3.
47
+ The contract is the one the `alignfirst-setup-guide` lists under "Prepare a Project for an Assistant": project context, usable work files outside the project's tracked tree, documentation, runtime commands, and a developer guide. The workspace system is optional. The project is prepared when DEVELOPERS_PATH exists and `{{ALIGNDEV}} guide work-files-setup` passes without preparation: continue with the normal working-session flow for the user's request. Otherwise, continue to Step 3.
48
48
 
49
49
  ### Step 3 — Warn and ask
50
50
 
@@ -58,7 +58,7 @@ Ask the user to approve this procedure and whether `.plans` must be shared throu
58
58
 
59
59
  On approval:
60
60
 
61
- 1. Create `.plans/` in the main worktree and run `{{ALIGNFIRST}} sync`. Run `{{ALIGNFIRST}} ticket --side` from PROJECT_PATH, write `{TICKET_DIR}A1-request.md` with the recorded request, then run `{{ALIGNFIRST}} sync`.
61
+ 1. Complete `{{ALIGNDEV}} guide work-files-setup` under the approved preparation, then run `{{ALIGNFIRST}} sync`. Run `{{ALIGNFIRST}} ticket --side` from PROJECT_PATH, write `{TICKET_DIR}A1-request.md` with the recorded request, then run `{{ALIGNFIRST}} sync`.
62
62
  2. Create `{TICKET_ID}/alignfirst-setup` in the main worktree. This setup branch is the second main-worktree exception, next to new-project bootstrap.
63
63
  3. Run `{{ALIGNDEV}} guide code`. From PROJECT_PATH, delegate the preparation to the agent without a protocol: use the `alignfirst-setup-guide` skill and prepare the repository for an assistant, with the user's work-files repository decision and its URL. It must run `{{ALIGNDEV}} project doctor` after writing `.alignfirst.json` and before workspace setup, stopping on an unhealthy inventory. Instruct the agent to commit and push the branch. The setup guide's rule against pushing addresses a human's laptop session, not this procedure.
64
64
  4. Have the agent create a ready pull request, not a draft.
@@ -70,32 +70,34 @@ When the user reports the merge, or you observe it while checking the PR:
70
70
 
71
71
  1. In the main worktree, switch back to the default branch, pull, and delete the local setup branch.
72
72
  2. Install dependencies and build.
73
- 3. When the user chose the work-files repository, clone it under `{{PROJECTS_ROOT}}` when no clone exists there (the projects guide names the repository), then run `{{ALIGNFIRST}} plans setup {{PROJECTS_ROOT}}/<clone>` from PROJECT_PATH. Otherwise, run `mkdir .plans`.
73
+ 3. When the user chose the work-files repository, clone it under `{{PROJECTS_ROOT}}` when no clone exists there (the projects guide names the repository), then run `{{ALIGNFIRST}} plans setup {{PROJECTS_ROOT}}/<clone>` from PROJECT_PATH. Otherwise keep the prepared plans. Then verify with `{{ALIGNDEV}} guide work-files-setup`.
74
74
  4. Run `{{ALIGNDEV}} project doctor`. Stop when the inventory is unhealthy.
75
- 5. Run the project's `workspace setup` on the main worktree.
75
+ 5. Run the project's documented main-worktree workspace setup when it has one, otherwise its install/build/test commands.
76
76
  6. Continue with the normal working-session flow for the original request through `{{ALIGNDEV}} guide project-workspace-setup`.
77
77
 
78
78
  ### Prepare through the companion
79
79
 
80
80
  The preparation targets the project's companion directory. It writes nothing in the repository and creates no branch, commit or pull request.
81
81
 
82
- 1. Run `{{ALIGNFIRST}} companion register` from PROJECT_PATH. It registers the project in the companion registry unless it is registered.
83
- 2. Unless the user already said, ask whether `.plans` must be shared through a work-files repository, and for its URL if so. Wait for the answer.
84
- 3. When the user chose the work-files repository, clone it under `{{PROJECTS_ROOT}}` when no clone exists there.
85
- 4. Run `{{ALIGNDEV}} guide code`. From PROJECT_PATH, delegate the preparation to the agent without a protocol: use the `alignfirst-setup-guide` skill and follow its procedure "Set up a project through its companion" for an assistant, with the work-files clone path when there is one.
86
- 5. Run `{{ALIGNDEV}} project doctor`. Stop when the inventory is unhealthy.
87
- 6. Continue with the normal working-session flow for the original request through `{{ALIGNDEV}} guide project-workspace-setup`. The project runs in main-worktree mode.
82
+ 1. Run `{{ALIGNFIRST}} companion register` from PROJECT_PATH. It keeps an existing registration and profile selection.
83
+ 2. Complete `{{ALIGNDEV}} guide work-files-setup` from PROJECT_PATH, starting at section 3: the Step 3 approval authorizes it, even when existing project plans are usable. It selects companion plans and leaves the existing work files in place without copying them.
84
+ 3. Reread `{{ALIGNFIRST}} config --json`. Verify that `.plans` and every item to write resolve inside `companion.dir`. Missing `.alignfirst.json` and `DEVELOPERS.md` must have companion destinations. If an explicit item selection points a required write into the project, stop and resolve that selection with the user. Retain the reported companion `DEVELOPERS.md` path as DEVELOPERS_PATH.
85
+ 4. Unless the user already said, ask whether `.plans` must be shared through a work-files repository, and for its URL if so. Wait for the answer.
86
+ 5. When the user chose the work-files repository, clone it under `{{PROJECTS_ROOT}}` when no clone exists there.
87
+ 6. Run `{{ALIGNDEV}} guide code`. From PROJECT_PATH, delegate the preparation to the agent without a protocol: use the `alignfirst-setup-guide` skill and follow its procedure "Set up a project through its companion" for an assistant, with the work-files clone path when there is one.
88
+ 7. Run `{{ALIGNDEV}} project doctor`. Stop when the inventory is unhealthy.
89
+ 8. Continue with the normal working-session flow for the original request through `{{ALIGNDEV}} guide project-workspace-setup`.
88
90
 
89
91
  ## Remove a project
90
92
 
91
93
  Removal requires the listed PROJECT_PATH selected before the thread opened or supplied by the user.
92
94
 
93
95
  1. Run and read `{{ALIGNDEV}} guide project`, then refresh `{{ALIGNDEV}} project list --json` and resolve the listed project at PROJECT_PATH. Run `{{ALIGNDEV}} project status <PROJECT_PATH>` and retain its `DEVELOPERS.md` path as DEVELOPERS_PATH, and its companion directory when it reports one. Read DEVELOPERS_PATH, then run and read the project workspace guide it names, if any.
94
- 2. A project in main-worktree mode (DEVELOPERS_PATH missing or without a workspaces section) has no linked workspace to enumerate: its list holds PROJECT_PATH alone. Otherwise, use the project workspace tooling to enumerate every registered linked workspace and its exact absolute path. Include the exact PROJECT_PATH for the main worktree.
96
+ 2. List every linked worktree with its exact absolute path, through the project's workspace list or, without workspace tooling, `{{ALIGNDEV}} worktree list --json` from PROJECT_PATH. Add the exact PROJECT_PATH for the main worktree. Check every worktree, the main one included, for staged, unstaged, or untracked unignored changes. A dirty worktree stops the removal before anything is unregistered or deleted, and so does a missing or locked registration until it is resolved.
95
97
  3. Show the user the complete linked-worktree path list and the main-worktree path. When the project status reports a companion directory, show it too and ask whether to keep or delete it. Wait for explicit confirmation of those exact paths, and for the answer about the companion directory.
96
- 4. Remove each confirmed linked workspace through the project workspace tooling. Stop immediately if any removal fails; keep the main worktree intact.
98
+ 4. Remove each confirmed linked workspace through the project's workspace tooling or, without it, stop whatever the project runs there and run `{{ALIGNDEV}} worktree remove <exact-path>` yourself. No coding launch or plans preparation is needed for that. Stop immediately if any removal fails; keep the main worktree intact.
97
99
  5. When the project status reports a companion, run `{{ALIGNFIRST}} companion unregister` from PROJECT_PATH. It removes the registry entry and keeps the companion directory. Add `--remove-dir --force` when the user chose to delete the companion directory.
98
- 6. Remove only the confirmed main-worktree directory at PROJECT_PATH. Leave every additional directory reported by the inventory untouched.
100
+ 6. Recheck that the main worktree is clean, then remove only the confirmed main-worktree directory at PROJECT_PATH. Leave every additional directory reported by the inventory untouched.
99
101
  7. Refresh `{{ALIGNDEV}} project list --json`: the path must be absent from `projects`. Report any remaining workspace or filesystem discrepancy, and name the companion directory when it was kept.
100
102
 
101
103
  Apply the host-specific and project-specific constraints read earlier throughout the sequence.
@@ -53,22 +53,13 @@ Setting up a workspace takes a while, so tell the user it started before you sta
53
53
  {{#codingAgent}}
54
54
  ## Step 2 — Decide the workplace
55
55
 
56
- {{#hasGuide}}
57
- The project has **workspace tooling** when DEVELOPERS_PATH describes workspaces.
58
- {{/hasGuide}}
59
- {{#noGuide}}
60
- The project has no **workspace tooling**.
61
- {{/noGuide}}
62
-
63
56
  The workplace is the first case that matches:
64
57
 
65
- 1. **The user's request or instructions name the place** — a directory, a branch, a workspace: work there.
58
+ 1. **The user's request or instructions name the place** — a directory, a branch, a workspace: work there. For a directory, post its banner and go to Step 5. For a branch, Step 4 finds or attaches that branch rather than choosing another ticket branch.
66
59
  2. **The session's branch carries TICKET_ID** — work in place. Skip Steps 3 and 4: post the `[WORKSPACE]` banner (format in Step 4) with the session's worktree and branch and `Status: ready`, then go to Step 5.
67
60
  3. **The session's branch is long-lived** — the default branch, or a name such as `main`, `master`, `develop`, `release` or `production`: open or create the ticket's workspace in Step 4, without asking.
68
61
  4. **Any other branch**, one carrying another ticket's ID included — end the turn on one message asking where to work. On the answer, "here" means the session's worktree as it is, handled as in case 2; a branch or a directory the user names falls under case 1.
69
62
 
70
- Without workspace tooling, case 3 also ends the turn on that question, and "here" means the ticket's branch in the session's worktree: `git switch <branch>` when it exists, else a fast-forward of the base branch, then `git switch -c {TICKET_ID}/{1-3-words}`. The banner then follows case 2.
71
-
72
63
  ## Step 3 — Post the setup signal
73
64
 
74
65
  Post the signal only when Step 2 opens or creates a workspace.
@@ -100,32 +91,22 @@ That single call is the whole exception. The post right after it, and every one
100
91
  {{/openclaw}}
101
92
 
102
93
  {{#openclaw}}
103
- ## Step 4 — Set up the project workspace (worktree, branch, dev server)
94
+ ## Step 4 — Set up the project workspace (worktree and branch)
104
95
  {{/openclaw}}
105
96
  {{#codingAgent}}
106
- ## Step 4 — Set up the workspace (worktree, branch, dev server)
97
+ ## Step 4 — Set up the workspace (worktree and branch)
107
98
  {{/codingAgent}}
108
99
 
109
100
  {{#openclaw}}
110
- A project runs in **main-worktree mode** when DEVELOPERS_PATH is missing or has no workspaces section. Its main worktree at PROJECT_PATH is its only workspace, used by one working thread at a time. "Main-worktree mode" below adapts this step, and wherever the playbook names the linked workspace, you use PROJECT_PATH.
101
+ When the user named a directory, or a recorded workplace's branch already carries TICKET_ID, use that worktree as it is: post its banner and go to Step 5. When the user named a branch, find or attach it below rather than choosing another ticket branch.
111
102
  {{/openclaw}}
112
103
 
113
- {{#openclaw}}
114
- Otherwise, the workspace tooling owns worktrees. Run its main-worktree commands from PROJECT_PATH. Create, reuse, and tear worktrees down through its commands only — never `git worktree add`/`remove`/`prune`, never `rm -rf` on a worktree directory, never a branch checked out by hand outside a workspace. A worktree the tooling doesn't know about is invisible to every other session.
115
- {{/openclaw}}
116
- {{#codingAgent}}
117
- The workspace tooling owns worktrees. Run its main-worktree commands from PROJECT_PATH. Create, reuse, and tear worktrees down through its commands only — never `git worktree add`/`remove`/`prune`, never `rm -rf` on a worktree directory, never a branch checked out by hand outside a workspace. A worktree the tooling doesn't know about is invisible to every other session.
118
- {{/codingAgent}}
104
+ The project has workspace tooling when its developer guide documents one, whatever the implementation. Use it when present; otherwise use `{{ALIGNDEV}} worktree list/add/remove`. Never bypass it with raw `git worktree add`/`remove`/`prune` or directory deletion.
119
105
 
120
- First, fetch remote refs from PROJECT_PATH with `git fetch --prune`. Then check what already exists for the {TICKET_ID} — two checks, both required:
106
+ First, select the base ref from the project or user instructions, otherwise use the base branch's configured upstream. Use the local base ref when the repository has no remote; ask when the choice is unclear. Fetch its remote from PROJECT_PATH with `git fetch --prune <remote>` when applicable, and retain the selected base ref for creation and synchronization. Then check what already exists for the explicitly selected branch, or otherwise for {TICKET_ID} — two checks, both required:
121
107
 
122
108
  - **Branch**: from PROJECT_PATH, list the branches, local and remote (`git branch -a`), and look for one matching the {TICKET_ID}. No match means no branch yet — an answer, not a failure.
123
- {{#openclaw}}
124
- - **Registered workspaces**: `DEVELOPERS.md` names the project's guide command (`workspace --guide`, with the project's own runner). It gives the commands to **list registered workspaces** and to **set up a workspace** — on an existing branch, or on a new one. Use them.
125
- {{/openclaw}}
126
- {{#codingAgent}}
127
- - **Registered workspaces**: the workspace tooling's guide command (`workspace --guide`, with the project's own runner) gives the commands to **list registered workspaces** and to **set up a workspace** — on an existing branch, or on a new one. Use them.
128
- {{/codingAgent}}
109
+ - **Worktrees**: the project's workspace list command, or `{{ALIGNDEV}} worktree list --json` from PROJECT_PATH. Report a missing, locked, or prunable entry instead of repairing it.
129
110
 
130
111
  Never assume the branch is new; `git worktree list` alone does not answer the branch question.
131
112
 
@@ -133,13 +114,17 @@ Whenever a branch exists, you work from its workspace — a status request inclu
133
114
 
134
115
  1. **Branch + workspace already registered** → use it (no setup needed).
135
116
  2. **Branch exists (local or remote), no workspace** → set up a workspace on the existing branch (don't create a new branch).
136
- 3. **No branch** → for a status request, end the turn on a message reporting that no workspace or code work exists, with any request, spec, and summary files listed by the ticket preflight; create nothing. Any other request is new-work intent: in PROJECT_PATH, fast-forward the base branch from its freshly fetched remote ref so the new branch starts from the latest base, then set up a workspace on a new branch. Name it `{TICKET_ID}/{1-3-words}`, deriving the short description from the request. A fast-forward that brought in new commits leaves the main worktree stale, and no later step refreshes it: once the workspace is up, run the "Refreshing the workspace after a branch refresh" flow on the main worktree at PROJECT_PATH.
117
+ 3. **No branch** → for a status request, end the turn on a message reporting that no workspace or code work exists, with any request, spec, and summary files listed by the ticket preflight; create nothing. Any other request is new-work intent: name a new branch `{TICKET_ID}/{1-3-words}`, deriving the short description from the request. Start it from the selected base ref. Creating from that ref requires no checkout or clean main worktree.
118
+
119
+ With workspace tooling, delegate the setup through its documented commands. Without it, run `{{ALIGNDEV}} worktree add` yourself, before any coding delegation, on an absolute sibling path derived from PROJECT and the branch (branch slashes become dashes): `{{ALIGNDEV}} worktree add <path> <existing-branch> --json` for sub-path 2, `{{ALIGNDEV}} worktree add <path> -b <new-branch> <explicit-base-ref> --json` for sub-path 3.
120
+
121
+ The command refuses an occupied path, a dangling symlink included, a branch checked out elsewhere, an ambiguous remote branch, and missing or project-tracked plans. Relay the refusal instead of working around it: reuse the path it reports for an occupied branch, ask the user about an ambiguous remote, run `{{ALIGNDEV}} guide work-files-setup` for plans and retry; never force a second checkout or invent another path. It returns once the worktree and its work files are ready. Report its warnings, such as a tracked `.local` that stays branch-local, and on a late failure relay its recovery instructions and delete nothing.
137
122
 
138
123
  {{#openclaw}}
139
- The moment you have the linked workspace path — attached (sub-path 1) or freshly set up (2, 3) — post the `[WORKSPACE]` banner, before any `git` inspection or prose, and **include it again in the message you end the turn with**: the early post may not deliver on every surface, the final message always does (on Discord the Step 3 rename post also delivers). `workspace setup` blocks until the bootstrap reaches `ready` or `failed`; run it in the foreground (no `background` option) and report the state it returns. Run subsequent Git commands and `{{ALIGNDEV}} code` from that linked workspace, never PROJECT_PATH, except in main-worktree mode.
124
+ The moment you have the linked workspace path — attached (sub-path 1) or freshly set up (2, 3) — post the `[WORKSPACE]` banner, before any `git` inspection or prose, and **include it again in the message you end the turn with**: the early post may not deliver on every surface, the final message always does (on Discord the Step 3 rename post also delivers). Run the selected setup command in the foreground (no `background` option) and report the state it returns. Run subsequent Git commands and `{{ALIGNDEV}} code` from that linked workspace, never PROJECT_PATH, unless the user explicitly chose in-place work.
140
125
  {{/openclaw}}
141
126
  {{#codingAgent}}
142
- The moment you have the workplace — in place, attached (sub-path 1) or freshly set up (2, 3) — post the `[WORKSPACE]` banner, before any `git` inspection or prose. `workspace setup` blocks until the bootstrap reaches `ready` or `failed`; run it in the foreground and report the state it returns. Run subsequent Git commands and `{{ALIGNDEV}} code` from the workplace.
127
+ The moment you have the workplace — in place, attached (sub-path 1) or freshly set up (2, 3) — post the `[WORKSPACE]` banner, before any `git` inspection or prose. Run the selected setup command in the foreground and report the state it returns. Run subsequent Git commands and `{{ALIGNDEV}} code` from the workplace.
143
128
  {{/codingAgent}}
144
129
 
145
130
  {{#openclaw}}
@@ -157,25 +142,7 @@ Branch: `{branch}`
157
142
  Status: {running | ready | failed}
158
143
  ```
159
144
 
160
- The lines below the tag report the workspace: after `Status:`, add what the setup output gives that the user can act on.
161
-
162
- {{#openclaw}}
163
- ### Main-worktree mode
164
- {{/openclaw}}
165
-
166
- {{#openclaw}}
167
- The branch check applies; the registered-workspace check does not. Before any checkout, claim the main worktree. It is free when it is on the default branch with a clean `git status`, or already on this thread's {TICKET_ID} branch. Otherwise, end the turn telling the user the project is busy: name the checked-out branch and the uncommitted changes, and change nothing.
168
- {{/openclaw}}
169
-
170
- {{#openclaw}}
171
- On a free main worktree, the sub-paths above run in PROJECT_PATH with plain `git switch`:
172
-
173
- 1. **Already on the branch** → use it.
174
- 2. **Branch exists, not checked out** → `git switch <branch>`.
175
- 3. **No branch** → a status request ends as above. Otherwise, fast-forward the base branch as above, then `git switch -c {TICKET_ID}/{1-3-words}`.
176
-
177
- The `[WORKSPACE]` banner names the main worktree: `Worktree:` is the directory name of PROJECT_PATH, and `Status:` is `ready`.
178
- {{/openclaw}}
145
+ The lines below the tag report the workspace: after `Status:`, add what the setup output gives that the user can act on. For a worktree from `{{ALIGNDEV}} worktree add`, say that `ready` covers the worktree and work files only, and delegate the repository's documented install/build/test preparation separately before coding needs it.
179
146
 
180
147
  {{#openclaw}}
181
148
  ## Step 5 — Sync an existing branch on takeover (sub-paths 1 & 2)
@@ -188,12 +155,12 @@ The `[WORKSPACE]` banner names the main worktree: `Worktree:` is the directory n
188
155
  In place on an existing branch, fetch first. A fast-forward of the branch onto its remote counterpart or onto the base branch, on a clean tree, is the only sync done without asking: do it, then report it in one line. Anything else — uncommitted changes, a remote branch that does not fast-forward, a base-branch catch-up that needs a merge commit — ends the turn on one message stating what will happen ("I'll commit your changes as WIP and merge `main`, OK?"). The list below runs on the user's yes. In a workspace you opened or created, the list runs directly.
189
156
  {{/codingAgent}}
190
157
 
191
- Skip on sub-path 3 (no branch — nothing to sync). Otherwise, once the workspace is set up, bring the branch up to date *before* inspecting, working, or reporting a status — a teammate may have pushed since you last synced, and a report off a stale branch is wrong. In order:
158
+ Skip on sub-path 3 (no branch — nothing to sync). If Step 4 was skipped, select and fetch the base ref as described there. Once the workspace is set up, bring the branch up to date *before* inspecting, working, or reporting a status — a teammate may have pushed since you last synced, and a report off a stale branch is wrong. In order:
192
159
 
193
- 1. **Confirm the branch.** Check the worktree's checked-out branch carries the expected TICKET_ID. If it doesn't, stop and surface it to the user — don't work on the wrong branch.
160
+ 1. **Confirm the branch and the work files.** Check the worktree's checked-out branch matches the explicit user choice, or otherwise carries the expected TICKET_ID. If it doesn't, stop and surface it to the user — don't work on the wrong branch. Then run `{{ALIGNFIRST}} plans check` from the worktree.
194
161
  2. **Guard uncommitted work.** Run `git status`. If the worktree is dirty, have the agent commit a WIP first (even if it doesn't compile) — never sync over uncommitted work.
195
- 3. **Merge the remote branch.** If the branch has a remote counterpart, merge its freshly fetched ref into the local branch to catch up. Delegate to the agent (`merge` protocol) when it doesn't fast-forward or conflicts.
196
- 4. **Catch up with the base branch.** If the freshly fetched base branch (`origin/<base>`) has commits not yet in this branch, run the "Updating a branch with the base branch" flow — without asking; step 7 tells the user what came in.
162
+ 3. **Merge the remote branch.** If the branch has a remote counterpart, fetch its remote if it differs from the base's, then merge its freshly fetched ref into the local branch to catch up. Delegate to the agent (`merge` protocol) when it doesn't fast-forward or conflicts.
163
+ 4. **Catch up with the base branch.** If the selected base ref has commits not yet in this branch, run the "Updating a branch with the base branch" flow — without asking; step 7 tells the user what came in.
197
164
  5. **Refresh the workspace if commits came in.** If the merge brought in new commits, run the "Refreshing the workspace after a branch refresh" flow: reinstall dependencies, rebuild, run the new migrations.
198
165
  6. **Check for an open MR/PR** on this branch and note its state.
199
166
  7. **Report what changed.** If either merge brought in new commits, post a one-line summary so the user knows the ground shifted.
@@ -227,7 +194,7 @@ The workspace is ready. Announce what you're about to do in one line and do it.
227
194
  When the work is an `{{ALIGNDEV}} code` run, launch it as the delegation guide describes: background `exec` with `timeoutSeconds: 0`, then end the turn on the acknowledgement. Call nothing on the `{{ALIGNDEV}} code` session before the chained turn wakes you, whatever the `exec` acknowledgement suggests.
228
195
  {{/openclaw}}
229
196
  {{#codingAgent}}
230
- When the work is an `{{ALIGNDEV}} code` run, follow the delegation guide's parent-host route, then end the launch turn on the acknowledgement. A Pi parent first requires the available `background` tool and a persistent session; if either is missing, explain the setup problem instead of launching or promising completion.
197
+ When the work is an `{{ALIGNDEV}} code` run, launch it as the delegation guide describes for your parent host, then end the launch turn on the acknowledgement.
231
198
  {{/codingAgent}}
232
199
 
233
200
  Ask only when you genuinely can't proceed — the request is ambiguous enough that two readings lead to different work, or it turns on a product decision that isn't yours to make.
@@ -0,0 +1,33 @@
1
+ # Runbook: Work-files setup
2
+
3
+ Prepare usable work files before ticket reservation, request capture, coding delegation, or discussion recording. This procedure needs only PROJECT_PATH, the project's main-worktree path. It needs no ticket, branch, or new worktree.
4
+
5
+ For explicit companion-only onboarding, start at section 3 under the onboarding authorization, even when existing project plans are usable. That route requires registration and an explicit companion-plans selection independently of the readiness gate below.
6
+
7
+ ## 1. Check the effective work files
8
+
9
+ Run `{{ALIGNFIRST}} plans check --json` from PROJECT_PATH. It reads the effective `.plans` location from `{{ALIGNFIRST}} config --json`, where explicit `project` or `companion` selections win and, under `auto`, an existing companion copy wins over an existing project copy; when neither exists, a registered companion is the creation target. The check passes when that location is a usable directory with no file tracked by this project's own repository, through a tracked symlink, mixed tracked/untracked contents, or an alias into tracked files included. A separate work-files repository may track its contents, and an unused tracked project `.plans` is not a blocker when a usable companion is effective.
10
+
11
+ If `--json` is rejected, the selected AlignFirst CLI needs upgrading alongside AlignDev. With `npx`, check the project's local `alignfirst` dependency, which takes precedence over the cached or global CLI. Retry the JSON check after upgrading; do not substitute a plain-text check.
12
+
13
+ When an existing linked worktree is selected, run the command there too: it also requires the same effective target as the main worktree. A different location is an error: do not create a second history or repair links silently.
14
+
15
+ Usable, non-project-tracked effective plans need no preparation: resume the interrupted operation. Any other failure (broken links, invalid configuration, unreadable paths, conflicting non-directory files) is reported, not repaired.
16
+
17
+ ## 2. Obtain approval when preparation is needed
18
+
19
+ When effective plans are missing or project-tracked, including an add failure because the intended branch tracks project-local plans, ask in the user's language unless preparation is already authorized: "{Reason}. May I select companion-backed work files for all this project's worktrees, leaving the existing project work files untouched and unused?" Keep the all-worktree scope and preservation promise in the approval question. Do not copy, merge, migrate, archive, or delete existing work files, and do not ask about copying them.
20
+
21
+ Wait for approval before changing registration, selection, or directories. Do not reserve a temporary ticket or create a temporary worktree to prepare work files.
22
+
23
+ ## 3. Select and verify companion plans
24
+
25
+ After approval:
26
+
27
+ 1. If no companion is registered, run `{{ALIGNFIRST}} companion register` from PROJECT_PATH. This also preserves a profile-only registration.
28
+ 2. Reread `{{ALIGNFIRST}} config --json`. Retain `companion.dir` and `companion.key`; use the reported key exactly.
29
+ 3. Read `~/.alignfirst/companions/registry.json` before editing. Its project entries live under `projects`. Edit only `projects[companion.key]`, setting `items[".plans"]` to `"companion"` within that entry. Use the key reported by config, not a guessed key or a new top-level `items` object. Preserve all other fields, item settings, profile selections, and entries.
30
+ 4. Reread `{{ALIGNFIRST}} config --json`. Verify that `locations[".plans"].in` is `"companion"` and its path is the selected companion's `.plans`. Create that directory if missing, preserving existing contents. Do not create a worktree `.plans` link for companion plans.
31
+ 5. Run `{{ALIGNFIRST}} plans check --json` again from PROJECT_PATH, and from any already selected worktree, then resume the interrupted operation.
32
+
33
+ This is the sole assistant preparation procedure. `{{ALIGNDEV}} worktree add` and coding launches validate work files; they do not authorize this selection or provision missing plans.