aligndev 0.28.1 → 0.30.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +16 -6
- package/dist/alignfirst-cli.js +22 -10
- package/dist/cli.d.ts +2 -0
- package/dist/cli.js +14 -12
- package/dist/code/claude-agent.js +1 -1
- package/dist/code/code-cli.js +3 -5
- package/dist/code/codex-agent.js +1 -1
- package/dist/code/machine-id.js +14 -3
- package/dist/code/pi-agent.js +1 -1
- package/dist/code/run-agent.js +37 -1
- package/dist/command-form.d.ts +5 -2
- package/dist/command-form.js +15 -6
- package/dist/guide/code-guide.d.ts +2 -2
- package/dist/guide/code-guide.js +4 -8
- package/dist/guide/guide-cli.js +82 -30
- package/dist/guide/render-template.d.ts +4 -4
- package/dist/guide/render-template.js +42 -21
- package/dist/guide/topics.d.ts +8 -3
- package/dist/guide/topics.js +26 -7
- package/dist/project/discovery.js +5 -12
- package/dist/project/layout.d.ts +22 -9
- package/dist/project/layout.js +101 -28
- package/dist/project/plans.d.ts +1 -1
- package/dist/project/plans.js +1 -1
- package/dist/project/render.js +3 -1
- package/dist/project/status.d.ts +2 -2
- package/dist/project/status.js +2 -2
- package/package.json +5 -1
- package/templates/guide/code.md +12 -3
- package/templates/guide/playbook/channel-handling.md +12 -17
- package/templates/guide/playbook/consultation.md +27 -30
- package/templates/guide/playbook/dispatcher.md +18 -0
- package/templates/guide/playbook/{discord-message-tool.md → message-tool.md} +29 -0
- package/templates/guide/playbook/playbook.md +55 -25
- package/templates/guide/playbook/project-lifecycle.md +33 -18
- package/templates/guide/playbook/project-workspace-setup.md +91 -71
- package/templates/guide/playbook/work-files-setup.md +2 -2
- package/templates/guide/playbook/working-session.md +207 -158
- package/templates/guide/project.md +4 -4
- package/dist/guide/guide-file.d.ts +0 -3
- package/dist/guide/guide-file.js +0 -26
- package/dist/worktree/add.d.ts +0 -20
- package/dist/worktree/add.js +0 -175
- package/dist/worktree/git.d.ts +0 -24
- package/dist/worktree/git.js +0 -103
- package/dist/worktree/remove.d.ts +0 -8
- package/dist/worktree/remove.js +0 -62
- package/dist/worktree/worktree-cli.d.ts +0 -10
- package/dist/worktree/worktree-cli.js +0 -122
- package/templates/guide/playbook/slack-message-tool.md +0 -23
|
@@ -1,11 +1,11 @@
|
|
|
1
1
|
# Runbook: Project workspace setup
|
|
2
2
|
|
|
3
|
-
{{#
|
|
3
|
+
{{#thread}}
|
|
4
4
|
The setup phase of a working session: get the workspace ready before handling the user's request. You're in a thread session, so your plain-text replies are your delivery — but only the message that **ends your turn** is guaranteed to post; mid-turn lines may never leave the transcript. The message you end the setup turn with must carry everything the user needs: the `[WORKSPACE]` banner (Step 4) and what you did or launched. Never call `message` `send`/`thread-reply` targeting your own thread: it posts everything twice.
|
|
5
|
-
{{/
|
|
6
|
-
{{#
|
|
5
|
+
{{/thread}}
|
|
6
|
+
{{#conversation}}
|
|
7
7
|
The setup phase of a working session: decide the workplace and get it ready before handling the user's request. The message you end the setup turn with carries the `[WORKSPACE]` banner (Step 4) and what you did or launched, or the question Step 2 or Step 5 asks the user.
|
|
8
|
-
{{/
|
|
8
|
+
{{/conversation}}
|
|
9
9
|
|
|
10
10
|
{{#openclaw}}
|
|
11
11
|
## Prerequisites — run both now, before Step 1
|
|
@@ -15,124 +15,142 @@ The setup phase of a working session: decide the workplace and get it ready befo
|
|
|
15
15
|
{{/codingAgent}}
|
|
16
16
|
|
|
17
17
|
{{#openclaw}}
|
|
18
|
-
- `{{
|
|
19
|
-
{{/openclaw}}
|
|
20
|
-
{{#codingAgent}}
|
|
21
|
-
- `{{ALIGNDEV}} guide code` — the delegation manual. Required every time you run this procedure, status requests included; do not skip it because no coding seems planned.
|
|
22
|
-
{{/codingAgent}}
|
|
23
|
-
{{#openclaw}}
|
|
24
|
-
- run `{{ALIGNDEV}} project status <PROJECT_PATH>` and retain its `DEVELOPERS.md` path as DEVELOPERS_PATH, then read that file when it exists — how to create a worktree or a branch.
|
|
18
|
+
- `{{GUIDE}} code` (`exec`) — the delegation manual. Required every time you run this procedure, status requests included; do not skip it because no coding seems planned.
|
|
25
19
|
{{/openclaw}}
|
|
26
20
|
{{#codingAgent}}
|
|
27
|
-
{{
|
|
28
|
-
- Read DEVELOPERS_PATH, retained by Step 1 of `{{ALIGNDEV}} guide working-session` — whether the project has workspace tooling, and how to create a worktree or a branch.
|
|
29
|
-
{{/hasGuide}}
|
|
21
|
+
- `{{GUIDE}} code` — the delegation manual. Required every time you run this procedure, status requests included; do not skip it because no coding seems planned.
|
|
30
22
|
{{/codingAgent}}
|
|
23
|
+
- Run `{{ALIGNFIRST}} developer-instructions` from the current workplace when known, otherwise deliberately from PROJECT_PATH — how to create a worktree or a branch. The command prints conventions even without a configured guide.
|
|
31
24
|
|
|
32
25
|
## Step 1 — Requirements
|
|
33
26
|
|
|
34
27
|
You need:
|
|
35
28
|
|
|
36
29
|
- **PROJECT** — The main-worktree directory name shown to the user.
|
|
37
|
-
{{#
|
|
30
|
+
{{#thread}}
|
|
38
31
|
- **PROJECT_PATH** — The canonical absolute main-worktree path recorded in the thread starter.
|
|
39
|
-
{{/
|
|
40
|
-
{{#
|
|
41
|
-
- **PROJECT_PATH** — The canonical absolute main-worktree path resolved by Step 1 of `{{
|
|
32
|
+
{{/thread}}
|
|
33
|
+
{{#conversation}}
|
|
34
|
+
- **PROJECT_PATH** — The canonical absolute main-worktree path resolved by Step 1 of `{{GUIDE}} working-session`.
|
|
42
35
|
- **The workplace and the default branch** — The session's worktree, its branch, and the project's default branch, retained by the same step.
|
|
43
|
-
{{/
|
|
36
|
+
{{/conversation}}
|
|
44
37
|
- **TICKET_ID** — The external ticket ID or the side ticket `side-N` reserved by the working session.
|
|
45
38
|
|
|
46
39
|
If PROJECT, PROJECT_PATH, or TICKET_ID is missing, do not proceed. Do not guess or reconstruct these values. Ask the user.
|
|
47
40
|
|
|
48
|
-
{{#
|
|
41
|
+
{{#thread}}
|
|
49
42
|
## Step 2 — Post the setup signal
|
|
50
43
|
|
|
51
44
|
Setting up a workspace takes a while, so tell the user it started before you start it. One short line, in their language, and nothing else — the thread's starter already states the known project, ticket and task, so restating them here just repeats a message they can see.
|
|
52
|
-
{{/
|
|
53
|
-
{{#
|
|
45
|
+
{{/thread}}
|
|
46
|
+
{{#conversation}}
|
|
54
47
|
## Step 2 — Decide the workplace
|
|
55
48
|
|
|
56
49
|
The workplace is the first case that matches:
|
|
57
50
|
|
|
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.
|
|
59
|
-
2. **The session's branch carries TICKET_ID** — work in place. Skip
|
|
60
|
-
3. **The session's
|
|
61
|
-
|
|
51
|
+
1. **The user's request or instructions name the place** — a directory, a branch, a workspace: work there. For a directory, apply Step 4's existing-workplace preparation, post its banner and go to Step 5. For a branch, Step 4 finds or attaches that branch rather than choosing another ticket branch.
|
|
52
|
+
2. **The session's branch carries TICKET_ID** — work in place. Skip the setup signal and branch selection: apply Step 4's existing-workplace preparation, post the `[WORKSPACE]` banner with the session's worktree and branch, then go to Step 5.
|
|
53
|
+
3. **The session's worktree is a fresh harness worktree** — a linked worktree (its `git rev-parse --git-common-dir` is not its own `.git`) with a clean tree, on a branch that carries no ticket ID or on a detached HEAD, with no commit beyond the default branch: after `git fetch`, `git rev-list --count origin/<default>..HEAD` is `0`. OpenClaw (branch `openclaw/<name>`), Claude Code, Codex and Paseo create such worktrees. Work in place on the ticket branch, without asking. First run Step 4's two checks for TICKET_ID. A status request never creates a branch: with no ticket branch, it ends as sub-path 3 of Step 4 does. Otherwise:
|
|
54
|
+
- The ticket branch has a registered workspace: use that workspace, as sub-path 1 of Step 4. The fresh worktree stays unused.
|
|
55
|
+
- The ticket branch exists without a workspace: run `git switch <branch>` in the session's worktree.
|
|
56
|
+
- No ticket branch: run `git switch -c {TICKET_ID}/{1-3-words} origin/<default>` in the session's worktree.
|
|
57
|
+
|
|
58
|
+
After a switch, skip the setup signal: apply Step 4's existing-workplace preparation, post the `[WORKSPACE]` banner with the session's worktree and its new branch, then go to Step 5.
|
|
59
|
+
4. **The session's branch is long-lived, or there is no session workplace** — the default branch, a name such as `main`, `master`, `develop`, `release` or `production`, or a conversation that started outside the project: open or create the ticket's workspace in Step 4, without asking.
|
|
60
|
+
5. **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.
|
|
61
|
+
|
|
62
|
+
**Registration in place.** Before the `[WORKSPACE]` banner, run `{{ALIGNFIRST}} workspace setup --json` in the selected worktree, in the foreground. This adopts its exact path and branch with its branch-local manifest or defaults. The banner reports the state returned.
|
|
63
|
+
{{#app}}
|
|
64
|
+
|
|
65
|
+
**An OpenClaw managed worktree.** A conversation created with a worktree runs in a checkout on branch `openclaw/<name>`, adopted by case 3. Switching it to the ticket branch takes it off `openclaw/<name>`, so OpenClaw retains it and never removes it, even when the conversation is archived or idle. From then on, the workspace rules apply to it like any other workspace, teardown and post-merge removal included. When OpenClaw owns deletion, run `{{ALIGNFIRST}} workspace teardown` before archiving it. Use `{{ALIGNFIRST}} workspace remove` only when the user has transferred deletion ownership.
|
|
66
|
+
{{/app}}
|
|
62
67
|
|
|
63
68
|
## Step 3 — Post the setup signal
|
|
64
69
|
|
|
65
70
|
Post the signal only when Step 2 opens or creates a workspace.
|
|
66
71
|
|
|
67
72
|
Setting up a workspace takes a while, so tell the user it started before you start it. One short line, in their language, and nothing else — the user already knows the project, ticket and task, so restating them here just repeats what they have seen.
|
|
68
|
-
{{/
|
|
73
|
+
{{/conversation}}
|
|
69
74
|
|
|
70
75
|
Vary the wording: "Je prépare le workspace", "Setting up the workspace", "Spinning up the environment", "Getting the worktree ready", "Preparing the branch". No questions, no waiting.
|
|
71
76
|
|
|
72
|
-
{{#
|
|
77
|
+
{{#thread}}
|
|
73
78
|
On some surfaces this line never posts (mid-turn text — see the delivery note at the top). Write it anyway, and count on the end-of-turn message, not on it, for anything the user must see.
|
|
74
|
-
{{/
|
|
79
|
+
{{/thread}}
|
|
75
80
|
|
|
76
|
-
{{#
|
|
81
|
+
{{#thread}}
|
|
77
82
|
When the task changed with the message that woke you — a ticket that just arrived in a conversation thread, a scope the user just corrected — add a one-line restatement of what you're now working on. That line is the thread's durable record of the new task, the way the starter was for the original one.
|
|
78
|
-
{{/
|
|
79
|
-
{{#
|
|
83
|
+
{{/thread}}
|
|
84
|
+
{{#conversation}}
|
|
80
85
|
When the task changed with the user's latest message — a ticket that just arrived, a scope the user just corrected — add a one-line restatement of what you're now working on. That line is the conversation's record of the new task.
|
|
81
|
-
{{/
|
|
86
|
+
{{/conversation}}
|
|
82
87
|
|
|
83
|
-
{{#
|
|
88
|
+
{{#thread}}
|
|
84
89
|
## Step 3 — Name the thread (Discord-only)
|
|
85
90
|
|
|
91
|
+
{{#discord}}
|
|
86
92
|
Rename the thread whenever its name doesn't match what you now know. Format: `<TICKET_ID> - <PROJECT> - <1-to-5-word description>`, the description covering the task. A ticket that just arrived, a project that was unknown when the thread opened, a task that turned out to be something else — each one calls for the rename.
|
|
87
93
|
|
|
88
94
|
Discord renames a thread through a post, so make the setup signal carry it: send that line with `message` `action: "send"`, passing the current thread's complete `chat_id` as `target`, the new name as `threadName`, and the line itself as `message`. Don't also write the line as plain text; that posts it twice. The post does not end the turn: Step 4 follows in the same turn, and the turn ends on the banner.
|
|
89
95
|
|
|
90
96
|
That single call is the whole exception. The post right after it, and every one that follows, is plain text again; with nothing to rename, the tool never targets your own thread.
|
|
91
|
-
{{/
|
|
97
|
+
{{/discord}}
|
|
98
|
+
{{/thread}}
|
|
92
99
|
|
|
93
|
-
{{#
|
|
100
|
+
{{#thread}}
|
|
94
101
|
## Step 4 — Set up the project workspace (worktree and branch)
|
|
95
|
-
{{/
|
|
96
|
-
{{#
|
|
102
|
+
{{/thread}}
|
|
103
|
+
{{#conversation}}
|
|
97
104
|
## Step 4 — Set up the workspace (worktree and branch)
|
|
98
|
-
{{/
|
|
105
|
+
{{/conversation}}
|
|
99
106
|
|
|
100
|
-
{{#
|
|
101
|
-
When the user named a directory, or a recorded workplace's branch already carries TICKET_ID,
|
|
102
|
-
{{/
|
|
107
|
+
{{#thread}}
|
|
108
|
+
When the user named a directory, or a recorded workplace's branch already carries TICKET_ID, retain that workplace: apply the existing-workplace preparation below, 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.
|
|
109
|
+
{{/thread}}
|
|
103
110
|
|
|
104
|
-
|
|
111
|
+
Run `{{ALIGNFIRST}} workspace --guide` from PROJECT_PATH. Use `{{ALIGNFIRST}} workspace` for configured and manifest-free projects. Never bypass it with raw `git worktree add`/`remove`/`prune` or directory deletion. An external owner retains Git creation and deletion; adopt its selected worktree and run teardown before it deletes the worktree.
|
|
112
|
+
|
|
113
|
+
**Existing-workplace preparation:** run `{{ALIGNFIRST}} workspace setup --path <exact-worktree-root> --json` yourself before reporting readiness or delegating. Setup preserves the selected path and branch. Without a path it discovers the current root, including from nested cwd. Conflicts remain untouched. Repair the reported problem and retry setup; relay failures and delete nothing. Work-files preparation requires the separate authorization in `{{GUIDE}} work-files-setup`. Before setup, read selected runtime placement from `{{ALIGNFIRST}} config --json`. Only project-local runtime requires ignored, untracked `.local-wt/`; with approval, use local Git exclusions when tracked rules must stay unchanged. Companion runtime creates no checkout runtime directory or link.
|
|
105
114
|
|
|
106
115
|
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:
|
|
107
116
|
|
|
108
117
|
- **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.
|
|
109
|
-
- **Worktrees**:
|
|
118
|
+
- **Worktrees**: `{{ALIGNFIRST}} workspace list --json` from PROJECT_PATH. Report a missing, locked, or prunable entry instead of repairing it.
|
|
110
119
|
|
|
111
120
|
Never assume the branch is new; `git worktree list` alone does not answer the branch question.
|
|
112
121
|
|
|
113
122
|
Whenever a branch exists, you work from its workspace — a status request included. "Status" means: set up the workspace, report its state (the banner below), sync the branch (Step 5), then report the work content (Step 6) — never `git log` from the main dir. Pick one sub-path:
|
|
114
123
|
|
|
115
|
-
1. **Branch + workspace already registered** →
|
|
124
|
+
1. **Branch + workspace already registered** → retain it and apply existing-workplace preparation above.
|
|
116
125
|
2. **Branch exists (local or remote), no workspace** → set up a workspace on the existing branch (don't create a new branch).
|
|
117
126
|
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
127
|
|
|
119
|
-
|
|
128
|
+
Run preparation yourself before coding delegation: `{{ALIGNFIRST}} workspace setup <existing-branch> --json` for sub-path 2, or `{{ALIGNFIRST}} workspace setup -c <new-branch> --from <explicit-base-ref> --json` for sub-path 3. Preserve a user-selected destination with `--path <absolute-path>`. Run in the foreground and wait for the returned readiness; setup does not start dev services. Use `{{ALIGNFIRST}} dev` separately when the task needs declared services.
|
|
120
129
|
|
|
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 `{{
|
|
130
|
+
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 `{{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.
|
|
122
131
|
|
|
123
|
-
{{#
|
|
132
|
+
{{#thread}}
|
|
133
|
+
{{#slack}}
|
|
134
|
+
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. 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.
|
|
135
|
+
{{/slack}}
|
|
136
|
+
{{#discord}}
|
|
124
137
|
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.
|
|
125
|
-
{{/
|
|
126
|
-
{{
|
|
138
|
+
{{/discord}}
|
|
139
|
+
{{/thread}}
|
|
140
|
+
{{#conversation}}
|
|
127
141
|
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.
|
|
128
|
-
{{/
|
|
142
|
+
{{/conversation}}
|
|
143
|
+
{{#app}}
|
|
129
144
|
|
|
130
|
-
|
|
145
|
+
End the setup turn on a message that carries the banner: text written earlier in the turn may never reach the user.
|
|
146
|
+
{{/app}}
|
|
147
|
+
|
|
148
|
+
{{#thread}}
|
|
131
149
|
Bold the values with your surface's markers rather than literal `**`, and translate the labels to the user's language:
|
|
132
|
-
{{/
|
|
133
|
-
{{#
|
|
150
|
+
{{/thread}}
|
|
151
|
+
{{#conversation}}
|
|
134
152
|
Bold the values in Markdown, and translate the labels to the user's language:
|
|
135
|
-
{{/
|
|
153
|
+
{{/conversation}}
|
|
136
154
|
|
|
137
155
|
```text
|
|
138
156
|
[WORKSPACE] **{PROJECT}** — Ticket: `{TICKET_ID}`
|
|
@@ -142,18 +160,18 @@ Branch: `{branch}`
|
|
|
142
160
|
Status: {running | ready | failed}
|
|
143
161
|
```
|
|
144
162
|
|
|
145
|
-
The lines below the tag report the workspace: after `Status:`, add what the setup output gives that the user can act on.
|
|
163
|
+
The lines below the tag report the workspace: after `Status:`, add what the setup output gives that the user can act on. With recipe `defaults`, describe `ready` as protocol-ready: Git, effective work files and runtime storage are prepared. Do not claim dependencies are installed, the application is built or services are running. Delegate repository-specific install/build/test work separately when needed.
|
|
146
164
|
|
|
147
|
-
{{#
|
|
165
|
+
{{#thread}}
|
|
148
166
|
## Step 5 — Sync an existing branch on takeover (sub-paths 1 & 2)
|
|
149
|
-
{{/
|
|
150
|
-
{{#
|
|
167
|
+
{{/thread}}
|
|
168
|
+
{{#conversation}}
|
|
151
169
|
## Step 5 — Sync an existing branch
|
|
152
|
-
{{/
|
|
170
|
+
{{/conversation}}
|
|
153
171
|
|
|
154
|
-
{{#
|
|
172
|
+
{{#conversation}}
|
|
155
173
|
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.
|
|
156
|
-
{{/
|
|
174
|
+
{{/conversation}}
|
|
157
175
|
|
|
158
176
|
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:
|
|
159
177
|
|
|
@@ -174,21 +192,23 @@ The `[WORKSPACE]` banner answers "is the env ready", not "where does the work st
|
|
|
174
192
|
- **Repo/workflow metadata**, which you may gather directly: `git log`/`status`/branch state, `gh` PR/issue state, the `.plans/` listing.
|
|
175
193
|
- **The ticket's AlignFirst artifacts** via `{{ALIGNDEV}} code new --ticket <id> --catchup`, run from the worktree: the agent loads the ticket history and returns a synthesis.
|
|
176
194
|
|
|
177
|
-
{{#
|
|
195
|
+
{{#thread}}
|
|
178
196
|
Combine them into the report and post it in the thread; use `--catchup` whenever the ticket history matters. Add `--protocol aad` or `--protocol spec` to continue with that protocol in the same `{{ALIGNDEV}} code` call. What you must **not** do is browse the source to describe how the code works — that's a delegation to the agent, not part of a status report.
|
|
179
|
-
{{/
|
|
180
|
-
{{#
|
|
197
|
+
{{/thread}}
|
|
198
|
+
{{#conversation}}
|
|
181
199
|
Combine them into the report and post it in the conversation; use `--catchup` whenever the ticket history matters. Add `--protocol aad` or `--protocol spec` to continue with that protocol in the same `{{ALIGNDEV}} code` call. What you must **not** do is browse the source to describe how the code works — that's a delegation to the agent, not part of a status report.
|
|
182
|
-
{{/
|
|
200
|
+
{{/conversation}}
|
|
183
201
|
|
|
184
202
|
## Step 7 — Start the work
|
|
185
203
|
|
|
186
|
-
{{
|
|
187
|
-
|
|
188
|
-
{{
|
|
189
|
-
{{
|
|
204
|
+
Run `{{ALIGNFIRST}} developer-instructions` from the selected workplace now that its path and branch are settled. Resolve any source-file editing location through `{{ALIGNFIRST}} config --json` there, using nullable `locations.developerInstructions`.
|
|
205
|
+
|
|
206
|
+
{{#thread}}
|
|
207
|
+
The workspace is ready. Before a coding delegation, apply the takeover-turn race checkpoint in the playbook (`{{GUIDE}}`). Then announce what you're about to do in one line and do it. The user's request is the go-ahead; asking them to confirm it again wastes a turn.
|
|
208
|
+
{{/thread}}
|
|
209
|
+
{{#conversation}}
|
|
190
210
|
The workspace is ready. Announce what you're about to do in one line and do it. The user's request is the go-ahead; asking them to confirm it again wastes a turn.
|
|
191
|
-
{{/
|
|
211
|
+
{{/conversation}}
|
|
192
212
|
|
|
193
213
|
{{#openclaw}}
|
|
194
214
|
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.
|
|
@@ -8,7 +8,7 @@ For explicit companion-only onboarding, start at section 3 under the onboarding
|
|
|
8
8
|
|
|
9
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
10
|
|
|
11
|
-
If `--json` is rejected, the selected AlignFirst CLI needs upgrading alongside AlignDev.
|
|
11
|
+
If `--json` is rejected, the selected AlignFirst CLI needs upgrading alongside AlignDev. Check the AlignFirst installation selected by `{{ALIGNFIRST}}`. For npm/npx, check the project's local `alignfirst` dependency first. Retry the JSON check after upgrading; do not substitute a plain-text check.
|
|
12
12
|
|
|
13
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
14
|
|
|
@@ -30,4 +30,4 @@ After approval:
|
|
|
30
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
31
|
5. Run `{{ALIGNFIRST}} plans check --json` again from PROJECT_PATH, and from any already selected worktree, then resume the interrupted operation.
|
|
32
32
|
|
|
33
|
-
This is the sole assistant preparation procedure. `{{
|
|
33
|
+
This is the sole assistant preparation procedure. `{{ALIGNFIRST}} workspace setup` and coding launches validate work files; they do not authorize this selection or provision missing plans.
|