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
|
@@ -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
|
|
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.
|
|
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.
|
|
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":
|
|
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.
|
|
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
|
|
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
|
|
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
|
|
83
|
-
2.
|
|
84
|
-
3.
|
|
85
|
-
4.
|
|
86
|
-
5.
|
|
87
|
-
6.
|
|
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.
|
|
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.
|
|
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
|
|
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
|
|
97
|
+
## Step 4 — Set up the workspace (worktree and branch)
|
|
107
98
|
{{/codingAgent}}
|
|
108
99
|
|
|
109
100
|
{{#openclaw}}
|
|
110
|
-
|
|
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
|
-
{{
|
|
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,
|
|
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
|
-
{{
|
|
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:
|
|
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).
|
|
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.
|
|
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).
|
|
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
|
|
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,
|
|
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.
|