aligndev 0.30.1 → 0.31.1

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 CHANGED
@@ -35,7 +35,7 @@ For a coding-agent assistant, parent host and delegated child are independent: a
35
35
 
36
36
  ## Configuration boundary
37
37
 
38
- AlignDev requires the workspace-aware `alignfirst config --json` report: top-level `workspace` metadata with absolute registry/runtime paths, `selectionOrigins`, logical locations and independent `aligndev` selection. One selected `alignfirst.json`/`.jsonc` with `schemaVersion: 1` holds nested conventions, plans, explicit developer instructions and optional recipes. Project configuration rejects unknown properties. Companion/global settings retain tolerant warnings. Inventory ranges come only from workspace `devServer.ports`; `project free-ports` looks up a free block without reserving it.
38
+ AlignDev requires the workspace-aware `alignfirst config --json` report: top-level `workspace` metadata with absolute registry/runtime paths, `selectionOrigins`, logical locations and independent `aligndev` selection. One selected `alignfirst.json`/`.jsonc` with `schemaVersion: 1` holds nested conventions, plans, explicit assistant instructions and optional recipes. Project configuration rejects unknown properties. Companion/global settings retain tolerant warnings. Inventory ranges come only from workspace `devServer.ports`; `project free-ports` looks up a free block without reserving it.
39
39
 
40
40
  ## Start in Claude Code, Codex or Pi
41
41
 
@@ -43,7 +43,7 @@ The project needs usable AlignFirst work files, untracked by the project's own r
43
43
 
44
44
  The assistant directly runs `alignfirst workspace` for configured and manifest-free projects on every stack. Project recipes live in the selected merged `alignfirst.json`/`.jsonc`, from project or companion; no wrapper or local kernel dependency is required. Prepare usable effective plans and selected runtime storage first. Local storage requires ignored, untracked `.local-wt/`; companion storage needs no checkout runtime directory. Without a manifest, readiness is protocol-ready: no installation, build, ports or services are implied. Coding delegation and project-specific commands remain separate.
45
45
 
46
- External tools such as Paseo run `npx -y alignfirst workspace setup` inside their selected checkout, then `workspace teardown` before their own deletion. Setup preserves the path/branch and retains partial preparation on failure for retry. Teardown stops/purges and releases state while preserving files and Git; remove additionally performs protected Git deletion and preserves branches. Failed cleanup retains identity even after PIDs exit. Adoption does not transfer external deletion ownership. See `alignfirst workspace --guide` and [the upgrade runbook](https://github.com/paleo/alignfirst/blob/main/docs/upgrading-multi-stack-workspaces.md).
46
+ External-tool hooks run `npx -y alignfirst workspace setup` inside their selected checkout, then `workspace teardown` before their own deletion. Setup preserves the path/branch and retains partial preparation on failure for retry. Teardown stops/purges and releases state while preserving files and Git; remove additionally performs protected Git deletion and preserves branches. Failed cleanup retains identity even after PIDs exit. An agent removing the workspace directly uses `workspace remove`. See `alignfirst workspace --guide` and [the upgrade runbook](https://github.com/paleo/alignfirst/blob/main/docs/upgrading-multi-stack-workspaces.md).
47
47
 
48
48
  The child needs network access and access to its selected work files. Parent-host elevation and the child's permission policy are separate. A shared symlink grants no sandbox permission. In native Codex 0.162.1 host probes, normal `workspace-write` denied writes through shared project `.plans` and `.local` links (`Errno 30`). Prepared companion plans passed through the existing `--add-dir <companion>` route; shared `.local` and outside-root writes remained denied. Report denied real paths. For companion plans, obtain approval through the `work-files-setup` topic of `aligndev guide`, preserving existing project files. Do not silently bypass the sandbox or grant the whole main repository write access.
49
49
 
@@ -85,7 +85,7 @@ Then ask your session to work with aligndev.
85
85
  ### Requirements
86
86
 
87
87
  - Node.js 22.11 or later with `npx -y aligndev`, or Bun with `bunx --bun aligndev` (`bun x --bun` is equivalent). Bun 1.4.4 is the tested CLI baseline; compatibility with every older release is not promised.
88
- - The selected child installed and authenticated under the same effective environment and cwd as the child. Apply the profile's `unset/env/configDir`, including HOME, PATH and credential routing, before using `claude` then `/login`, `codex login`, or `pi` then `/login <provider>` (or configured provider credentials). A bare login in another shell may select another account. Pi requires Node.js 22.19 or later; the Pi adapter and extensions target Pi 1.3.0.
88
+ - The selected child installed and authenticated under the same effective environment and cwd as the child. Apply the profile's `unset/env/configDir`, including HOME, PATH and credential routing, before using `claude` then `/login`, `codex login`, or `pi` then `/login <provider>` (or configured provider credentials). A bare login in another shell may select another account. Pi keeps its own runtime requirements; see the [extension compatibility baseline](https://github.com/paleo/alignfirst/blob/main/docs/pi-extensions.md#supported-and-tested-baseline).
89
89
  - For Pi, select a usable native model, preferably `provider/model` (optional thinking suffix). Authenticate in the same account/configuration used by the child; never expose credential values in diagnostics.
90
90
  - Linux or macOS, or Windows through WSL.
91
91
 
@@ -192,7 +192,11 @@ npx -y skills add https://github.com/paleo/alignfirst --global --skill alignfirs
192
192
 
193
193
  Deployments require null or a string for every coding profile and enabled explicit quota source; omission is invalid there. Generated service defaults use null. Inventory still records absolute filesystem paths, while native commands unset the directory variable for null or set its resolved value for a string.
194
194
 
195
- Then ask the agent to create an assistant. The skill collects the deployment values, renders one Slack or Discord variant and one Claude Code, Codex or Pi variant, and writes the installation, security, operation and recovery runbooks. Each managed project receives the preparation contract: project context, usable work files, docmap, runtime procedures and an explicitly referenced developer guide, in the repository or its companion. `alignfirst developer-instructions` prints conventions and that content without filename discovery. The workspace recipe is optional; default preparation is protocol-ready.
195
+ Then ask the agent to create an assistant. The skill collects the deployment values, renders one Slack or Discord variant and one Claude Code, Codex or Pi variant, and writes the installation, security, operation and recovery runbooks. Each managed project receives the preparation contract: project context, usable work files, docmap, runtime procedures and an explicitly referenced assistant guide, in the repository or its companion. `alignfirst assistant-instructions` reads project guidance and any explicitly referenced content. The workspace recipe is optional; default preparation is protocol-ready.
196
+
197
+ ## Maintainer checks
198
+
199
+ From the repository root, run the complete `npm run build`, then `npm run test:integration --workspace aligndev`. Filtered integration files require the same build. Preflight checks provisioning only; rebuild after source changes.
196
200
 
197
201
  ## Under the Hood
198
202
 
@@ -36,7 +36,9 @@ export function forwardSettingsWarnings(stderr) {
36
36
  function isSettingsWarning(line) {
37
37
  if (/[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]/u.test(line))
38
38
  return false;
39
- return /^Warning: ignoring unknown companion registry setting /u.test(line);
39
+ return (/^Warning: ignoring unknown companion registry setting /u.test(line) ||
40
+ /^Warning: developerInstructions is deprecated in .+; use assistantInstructionsFile instead\. assistantInstructionsFile takes precedence when both are set\.$/u.test(line) ||
41
+ line === "Warning: developer-instructions is deprecated; use assistant-instructions instead.");
40
42
  }
41
43
  export function describeAlignfirst(command, cwd, env) {
42
44
  const runner = ["npx", "bunx", "pnpm", "yarn"].includes(command[0]);
@@ -127,7 +127,7 @@ function captureHeader(event, state) {
127
127
  event.cwd.trim() === "" ||
128
128
  typeof event.timestamp !== "string" ||
129
129
  !Number.isFinite(Date.parse(event.timestamp))) {
130
- return invalidProtocol(state, "invalid or unsupported session header (requires pi 1.3.0)");
130
+ return invalidProtocol(state, "invalid or unsupported session header (requires pi 1.4.0)");
131
131
  }
132
132
  state.headerSeen = true;
133
133
  if (state.expectedSessionId !== undefined && event.id !== state.expectedSessionId) {
@@ -1,5 +1,5 @@
1
1
  import type { PortRange } from "./markers.js";
2
- export type ItemName = "alignfirst" | ".alignfirst-instructions" | "developerInstructions" | "workspaceRuntime" | "docs" | ".plans" | "_aligndev";
2
+ export type ItemName = "alignfirst" | ".alignfirst-instructions" | "assistantInstructionsFile" | "workspaceRuntime" | "docs" | ".plans" | "_aligndev";
3
3
  export interface ProjectReport {
4
4
  source: ConfigSource | null;
5
5
  workspace: WorkspaceConfigReport;
@@ -10,8 +10,8 @@ export interface ProjectReport {
10
10
  selectionOrigins: Record<ItemName, SelectionOrigin>;
11
11
  }
12
12
  export type SelectionOrigin = "item" | "defaultLocation" | "builtin";
13
- export type ProjectLocations = Record<Exclude<ItemName, "developerInstructions">, ItemLocation> & {
14
- developerInstructions: ItemLocation | null;
13
+ export type ProjectLocations = Record<Exclude<ItemName, "assistantInstructionsFile">, ItemLocation> & {
14
+ assistantInstructionsFile: ItemLocation | null;
15
15
  };
16
16
  export interface AligndevProjectSettings {
17
17
  profile: string;
@@ -29,7 +29,7 @@ export interface ProjectConfigView {
29
29
  conventions?: {
30
30
  ticketIdPattern?: string;
31
31
  };
32
- developerInstructions?: string;
32
+ assistantInstructionsFile?: string;
33
33
  plans?: {
34
34
  repositoryFolder?: string;
35
35
  };
@@ -35,7 +35,7 @@ function isOutdatedReport(value) {
35
35
  !(isRecord(value.locations) &&
36
36
  "alignfirst" in value.locations &&
37
37
  ".alignfirst-instructions" in value.locations &&
38
- "developerInstructions" in value.locations &&
38
+ "assistantInstructionsFile" in value.locations &&
39
39
  "workspaceRuntime" in value.locations &&
40
40
  isRecord(value.workspace) &&
41
41
  "registryDir" in value.workspace &&
@@ -43,7 +43,7 @@ function isOutdatedReport(value) {
43
43
  }
44
44
  function outdatedAlignfirst(path) {
45
45
  return (`The alignfirst CLI used in ${path} is too old: aligndev requires the workspace-aware ` +
46
- "alignfirst config --json contract (merged configuration, developerInstructions, workspaceRuntime and selectionOrigins). Upgrade alignfirst.");
46
+ "alignfirst config --json contract (merged configuration, assistantInstructionsFile, workspaceRuntime and selectionOrigins). Upgrade alignfirst.");
47
47
  }
48
48
  function parseProjectReport(value, path) {
49
49
  if (!isRecord(value))
@@ -111,15 +111,15 @@ function parseConfig(value, path) {
111
111
  if (value.conventions !== undefined && !isRecord(value.conventions))
112
112
  throw invalidReport(path);
113
113
  const ticketIdPattern = value.conventions?.ticketIdPattern;
114
- const developerInstructions = value.developerInstructions;
115
- if (developerInstructions !== undefined && typeof developerInstructions !== "string")
114
+ const assistantInstructionsFile = value.assistantInstructionsFile;
115
+ if (assistantInstructionsFile !== undefined && typeof assistantInstructionsFile !== "string")
116
116
  throw invalidReport(path);
117
117
  const plans = parsePlans(value.plans, path);
118
118
  if (ticketIdPattern !== undefined && typeof ticketIdPattern !== "string")
119
119
  throw invalidReport(path);
120
120
  return {
121
121
  ...(ticketIdPattern === undefined ? {} : { conventions: { ticketIdPattern } }),
122
- ...(developerInstructions === undefined ? {} : { developerInstructions }),
122
+ ...(assistantInstructionsFile === undefined ? {} : { assistantInstructionsFile }),
123
123
  ...(plans === undefined ? {} : { plans }),
124
124
  };
125
125
  }
@@ -164,7 +164,7 @@ function parseLocations(value, path) {
164
164
  return {
165
165
  alignfirst: location("alignfirst"),
166
166
  ".alignfirst-instructions": location(".alignfirst-instructions"),
167
- developerInstructions: value.developerInstructions === null ? null : location("developerInstructions"),
167
+ assistantInstructionsFile: value.assistantInstructionsFile === null ? null : location("assistantInstructionsFile"),
168
168
  workspaceRuntime: location("workspaceRuntime"),
169
169
  docs: location("docs"),
170
170
  ".plans": location(".plans"),
@@ -184,7 +184,7 @@ function parseItemRecord(value, path, parse) {
184
184
  return {
185
185
  alignfirst: parse(value.alignfirst),
186
186
  ".alignfirst-instructions": parse(value[".alignfirst-instructions"]),
187
- developerInstructions: parse(value.developerInstructions),
187
+ assistantInstructionsFile: parse(value.assistantInstructionsFile),
188
188
  workspaceRuntime: parse(value.workspaceRuntime),
189
189
  docs: parse(value.docs),
190
190
  ".plans": parse(value[".plans"]),
@@ -88,7 +88,7 @@ export function renderProjectStatus(details) {
88
88
  ` Config source: ${details.configSource ?? "(none)"}`,
89
89
  ` Companion: ${renderCompanion(details.companion)}`,
90
90
  ` AlignDev profile: ${renderNullableValue(details.aligndev?.profile ?? null)}`,
91
- ` Developer instructions: ${renderLocation(details.locations.developerInstructions)}`,
91
+ ` Assistant instructions: ${renderLocation(details.locations.assistantInstructionsFile)}`,
92
92
  ` Work files: ${renderLocation(details.locations[".plans"])}`,
93
93
  ` Work-files folder: ${renderNullableValue(details.plansFolder)}`,
94
94
  ` Ticket id pattern: ${renderNullableValue(details.ticketIdPattern)}`,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "aligndev",
3
- "version": "0.30.1",
3
+ "version": "0.31.1",
4
4
  "license": "CC0-1.0",
5
5
  "author": "Thomas MUR",
6
6
  "description": "The AlignDev CLI: the assistant's playbook, coding-agent delegation, and project inventory.",
@@ -38,11 +38,11 @@
38
38
  "access": "public"
39
39
  },
40
40
  "dependencies": {
41
- "@alignfirst/docmap": "~0.12.0",
42
- "@alignfirst/workspace": "~0.42.0"
41
+ "@alignfirst/docmap": "~0.13.0",
42
+ "@alignfirst/workspace": "~0.42.1"
43
43
  },
44
44
  "devDependencies": {
45
- "@types/node": "~26.6.5",
45
+ "@types/node": "~26.6.6",
46
46
  "rimraf": "~6.1.3",
47
47
  "typescript": "~7.0.2",
48
48
  "vitest": "~5.0.5"
@@ -295,6 +295,7 @@ Two fresh sessions: one reviews, one fixes.
295
295
  1. **Review** — `{{ALIGNDEV}} code new --protocol review --ticket AB-123`. The agent reviews the current branch against the base branch and writes a review file; its path is in the run's result. The base defaults to the repository's default branch; override it via `--message "Base branch: \`develop\`"`. Retain the session id.
296
296
  - **Follow up** (someone else's branch, its author pushed fixes) — `{{ALIGNDEV}} code resume <sessionId> --message "Fixes have been pushed, please check."`, in the review session, with the author's replies to the review appended when there are any. The agent checks its findings against the new commits and reports which are resolved and which remain. A new review session would start over.
297
297
  2. **Fix** (optional, always in a fresh session — never in the review session) — `{{ALIGNDEV}} code new --protocol aad --ticket AB-123 --message "Here is a code review: \`.plans/AB-123/B1-review.md\`. What should we fix?"`. Send this message as it is, pointed at wherever the review lives: the review file, or the PR/MR whose comments carry it. The agent challenges the findings and proposes fixes; decide together what to fix, as in any AAD session. The goal is the project's code quality, and a finding is not an order: welcome a fix or an expansion that cleans things up, refuse one that adds complexity; simplicity wins. The agent then implements and writes a summary file.
298
+ 3. **Recheck** (recommended after fixes) — resume the original review session without a protocol. Point at the fix summary and list unchanged findings with a few words of rationale each. Ask the reviewer to check the fixes, look for regressions they introduced, and assess those decisions. You decide what to do with its feedback.
298
299
 
299
300
  Skip the fix step when the review is informational.
300
301
 
@@ -43,7 +43,7 @@ Retain `git rev-parse --short HEAD`, the revision the answer comes from. Report
43
43
 
44
44
  ## Step 3 — Delegate
45
45
 
46
- Run `{{ALIGNFIRST}} developer-instructions` from the selected worktree after any refresh. It prints that worktree's conventions and configured guide, with its source path. Use `{{ALIGNFIRST}} config --json` there when you need the nullable `locations.developerInstructions`; do not substitute main's file or a filename fallback.
46
+ Run `{{ALIGNFIRST}} assistant-instructions` from the selected worktree after any refresh. It prints that worktree's conventions and configured guide, with its source path. Use `{{ALIGNFIRST}} config --json` there when you need the nullable `locations.assistantInstructionsFile`; do not substitute main's file or a filename fallback.
47
47
 
48
48
  Delegation creates session files under the work files, so complete `{{GUIDE}} work-files-setup` from PROJECT_PATH first.
49
49
 
@@ -82,7 +82,7 @@ You work on one project: the repository where this session started. Keep these v
82
82
  - **PROJECT_PATH** — the absolute main-worktree path.
83
83
 
84
84
  Step 1 of `{{GUIDE}} working-session` resolves both, and the workplace: the session's worktree and its branch, by default.
85
- Run `{{ALIGNFIRST}} developer-instructions` in the selected workplace for its conventions and explicitly configured developer guide. PROJECT_PATH anchors main-worktree Git commands and workspace tooling. Branch work and `{{ALIGNDEV}} code` happen in the workplace, which the setup procedure may move to a workspace.
85
+ Run `{{ALIGNFIRST}} assistant-instructions` in the selected workplace for its conventions and explicitly configured assistant guide. PROJECT_PATH anchors main-worktree Git commands and workspace tooling. Branch work and `{{ALIGNDEV}} code` happen in the workplace, which the setup procedure may move to a workspace.
86
86
 
87
87
  Creating, onboarding, or removing a project is not handled in this mode. When the user asks for it, say so.
88
88
  {{/codingAgent}}
@@ -118,7 +118,7 @@ You are an autonomous programmer. Instructions reach you from two places, and "t
118
118
  - This session runs in the repository, so the project's `AGENTS.md`, `CLAUDE.md` or companion `.alignfirst-instructions/context.md` is auto-loaded too. It still addresses the agent: its directives about investigating or implementing, such as "run `alignfirst context` before any investigation", are for the agent.
119
119
  {{/codingAgent}}
120
120
 
121
- Exception: the explicitly configured developer instructions address the agent's user — you. Read them through `{{ALIGNFIRST}} developer-instructions` in the selected worktree.
121
+ Exception: the explicitly configured assistant instructions address the agent's user — you. Read them through `{{ALIGNFIRST}} assistant-instructions` in the selected worktree.
122
122
 
123
123
  ## Effort estimates
124
124
 
@@ -28,10 +28,10 @@ Creation has a hard user-input gate. Before any filesystem, Git, port-allocation
28
28
  4. Complete `{{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 this conversation, every human message that supplied the gate's values included. Record the project name, selected parent, stack, port requirements, and requested stopping point. 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.
29
29
  {{/app}}
30
30
  {{#thread}}
31
- 5. Before delegating the bootstrap, run `{{GUIDE}} code`. On a takeover turn, apply the pre-delegation race checkpoint in the playbook (`{{GUIDE}}`) immediately before `{{ALIGNDEV}} code new`. Then bootstrap directly from PROJECT_PATH through `{{ALIGNDEV}} code new --message`, with no protocol. Instruct it to use `alignfirst-setup-guide`, prepare the merged configuration with explicit developer instructions, effective plans and selected runtime storage, then run `{{ALIGNDEV}} project doctor` before `{{ALIGNFIRST}} workspace setup`. Only project runtime needs ignored/untracked `.local-wt/`. Stop on unhealthy inventory. Recipes are optional; defaults are protocol-ready. Document separate install/build/test commands.
31
+ 5. Before delegating the bootstrap, run `{{GUIDE}} code`. On a takeover turn, apply the pre-delegation race checkpoint in the playbook (`{{GUIDE}}`) immediately before `{{ALIGNDEV}} code new`. Then bootstrap directly from PROJECT_PATH through `{{ALIGNDEV}} code new --message`, with no protocol. Instruct it to use `alignfirst-setup-guide`, prepare the merged configuration with explicit assistant instructions, effective plans and selected runtime storage, then run `{{ALIGNDEV}} project doctor` before `{{ALIGNFIRST}} workspace setup`. Only project runtime needs ignored/untracked `.local-wt/`. Stop on unhealthy inventory. Recipes are optional; defaults are protocol-ready. Document separate install/build/test commands.
32
32
  {{/thread}}
33
33
  {{#app}}
34
- 5. Before delegating the bootstrap, run `{{GUIDE}} code`. Then bootstrap directly from PROJECT_PATH through `{{ALIGNDEV}} code new --message`, with no protocol. Instruct it to use `alignfirst-setup-guide`, prepare the merged configuration with explicit developer instructions, effective plans and selected runtime storage, then run `{{ALIGNDEV}} project doctor` before `{{ALIGNFIRST}} workspace setup`. Only project runtime needs ignored/untracked `.local-wt/`. Stop on unhealthy inventory. Recipes are optional; defaults are protocol-ready. Document separate install/build/test commands.
34
+ 5. Before delegating the bootstrap, run `{{GUIDE}} code`. Then bootstrap directly from PROJECT_PATH through `{{ALIGNDEV}} code new --message`, with no protocol. Instruct it to use `alignfirst-setup-guide`, prepare the merged configuration with explicit assistant instructions, effective plans and selected runtime storage, then run `{{ALIGNDEV}} project doctor` before `{{ALIGNFIRST}} workspace setup`. Only project runtime needs ignored/untracked `.local-wt/`. Stop on unhealthy inventory. Recipes are optional; defaults are protocol-ready. Document separate install/build/test commands.
35
35
  {{/app}}
36
36
  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.
37
37
  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.
@@ -43,18 +43,18 @@ The direct main-worktree bootstrap is the creation exception. It ends with the i
43
43
 
44
44
  The user hands you a repository URL to clone instead of asking for a new project. Onboarding is bootstrap work like creation. Before the project is prepared, every delegation to the agent uses a fresh session with a plain message, never a protocol.
45
45
 
46
- ### Step 1 — Clone and build
46
+ ### Step 1 — Clone and prepare
47
47
 
48
48
  Before any discussion:
49
49
 
50
50
  1. Select a parent directory allowed by `{{ALIGNDEV}} guide project`. Ask the user when several qualify.
51
51
  2. Clone the repository into that parent. PROJECT is the clone's directory name; PROJECT_PATH is its canonical path.
52
- 3. Retain the canonical path as PROJECT_PATH. Run `{{ALIGNFIRST}} developer-instructions` there. When the project's selected configuration 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 `devServer.ports` in the selected `alignfirst.json` or `.jsonc`.
53
- 4. Install dependencies and build, following the repository's own README.
52
+ 3. Retain the canonical path as PROJECT_PATH. Run `{{ALIGNFIRST}} assistant-instructions` there. When the project's selected configuration 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 `devServer.ports` in the selected `alignfirst.json` or `.jsonc`.
53
+ 4. Install dependencies and build as needed, following the repository's own README.
54
54
 
55
55
  ### Step 2 — Check the AlignDev contract
56
56
 
57
- 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 manifest is optional. Run `{{ALIGNFIRST}} config --json` and `{{ALIGNFIRST}} developer-instructions` from PROJECT_PATH. The project is prepared when the explicitly configured `locations.developerInstructions` exists, the command succeeds, and `{{GUIDE}} work-files-setup` passes without preparation: continue with the normal working-session flow for the user's request. Otherwise, continue to Step 3.
57
+ 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 an assistant guide. The workspace manifest is optional. Run `{{ALIGNFIRST}} config --json` and `{{ALIGNFIRST}} assistant-instructions` from PROJECT_PATH. The project is prepared when the explicitly configured `locations.assistantInstructionsFile` exists, the command succeeds, and `{{GUIDE}} work-files-setup` passes without preparation: continue with the normal working-session flow for the user's request. Otherwise, continue to Step 3.
58
58
 
59
59
  ### Step 3 — Warn and ask
60
60
 
@@ -70,7 +70,7 @@ On approval:
70
70
 
71
71
  1. Complete `{{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`.
72
72
  2. Create `{TICKET_ID}/alignfirst-setup` in the main worktree. This setup branch is the second main-worktree exception, next to new-project bootstrap.
73
- 3. Run `{{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 prepare merged `alignfirst.json` with explicit developer instructions, effective plans and selected runtime storage (ignored/untracked `.local-wt/` only for project runtime), then run `{{ALIGNDEV}} project doctor` before `{{ALIGNFIRST}} workspace setup`, stopping on 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.
73
+ 3. Run `{{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 prepare merged `alignfirst.json` with explicit assistant instructions, effective plans and selected runtime storage (ignored/untracked `.local-wt/` only for project runtime), then run `{{ALIGNDEV}} project doctor` before `{{ALIGNFIRST}} workspace setup`, stopping on 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.
74
74
  4. Have the agent create a pull request.
75
75
  5. End the turn on the PR link and state that work resumes once the PR is merged.
76
76
 
@@ -79,7 +79,7 @@ On approval:
79
79
  When the user reports the merge, or you observe it while checking the PR:
80
80
 
81
81
  1. In the main worktree, switch back to the default branch, pull, and delete the local setup branch.
82
- 2. Install dependencies and build.
82
+ 2. Install dependencies and rebuild only where the incoming changes require it.
83
83
  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 `{{GUIDE}} work-files-setup`.
84
84
  4. Run `{{ALIGNDEV}} project doctor`. Stop when the inventory is unhealthy.
85
85
  5. Prepare effective plans and selected runtime storage (ignored/untracked `.local-wt/` only for project runtime), then run `{{ALIGNFIRST}} workspace setup` on main. Delegate any separately required install/build/test work.
@@ -91,7 +91,7 @@ The preparation targets the project's companion directory. It writes nothing in
91
91
 
92
92
  1. Run `{{ALIGNFIRST}} companion register` from PROJECT_PATH. It keeps an existing registration and profile selection.
93
93
  2. Complete `{{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.
94
- 3. Reread `{{ALIGNFIRST}} config --json`. Verify that `.plans` and every item to write resolve inside `companion.dir`. Missing `locations.alignfirst` must have a companion destination. `locations.developerInstructions` is null until a reference is configured: propose a suitable file and explicit `developerInstructions` setting under the onboarding authorization, then reread the report and verify its companion destination before creating the file. If an explicit item selection points a required write into the project, stop and resolve that selection with the user.
94
+ 3. Reread `{{ALIGNFIRST}} config --json`. Verify that `.plans` and every item to write resolve inside `companion.dir`. Missing `locations.alignfirst` must have a companion destination. `locations.assistantInstructionsFile` is null until a reference is configured: propose a suitable file and explicit `assistantInstructionsFile` setting under the onboarding authorization, then reread the report and verify its companion destination before creating the file. If an explicit item selection points a required write into the project, stop and resolve that selection with the user.
95
95
  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.
96
96
  5. When the user chose the work-files repository, clone it under `{{PROJECTS_ROOT}}` when no clone exists there.
97
97
  6. Run `{{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.
@@ -107,7 +107,7 @@ Removal requires the listed PROJECT_PATH selected before the thread opened or su
107
107
  Removal requires the listed PROJECT_PATH supplied by the user.
108
108
  {{/app}}
109
109
 
110
- 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 companion directory when it reports one. Run `{{ALIGNFIRST}} developer-instructions` and read `{{ALIGNFIRST}} workspace --guide` deliberately from PROJECT_PATH for main's instructions.
110
+ 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 companion directory when it reports one. Run `{{ALIGNFIRST}} assistant-instructions` and read `{{ALIGNFIRST}} workspace --guide` deliberately from PROJECT_PATH for main's instructions.
111
111
  2. List every linked worktree with its exact absolute path, through `{{ALIGNFIRST}} workspace 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.
112
112
  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.
113
113
  4. Remove each confirmed linked workspace with `{{ALIGNFIRST}} workspace remove <exact-path>` yourself. For externally owned worktrees, run `{{ALIGNFIRST}} workspace teardown <exact-path>` and wait for their owner to delete them. No coding launch or plans preparation is needed for that. Stop immediately if any removal fails; keep the main worktree intact. After linked cleanup succeeds, run `{{ALIGNFIRST}} workspace teardown <PROJECT_PATH>` before unregistering the companion or deleting main. A teardown failure also stops removal and retains all remaining paths/state.
@@ -20,7 +20,7 @@ The setup phase of a working session: decide the workplace and get it ready befo
20
20
  {{#codingAgent}}
21
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.
22
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.
23
+ - Run `{{ALIGNFIRST}} assistant-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.
24
24
 
25
25
  ## Step 1 — Requirements
26
26
 
@@ -50,7 +50,7 @@ The workplace is the first case that matches:
50
50
 
51
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
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:
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>`) and coding-agent hosts 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
54
  - The ticket branch has a registered workspace: use that workspace, as sub-path 1 of Step 4. The fresh worktree stays unused.
55
55
  - The ticket branch exists without a workspace: run `git switch <branch>` in the session's worktree.
56
56
  - No ticket branch: run `git switch -c {TICKET_ID}/{1-3-words} origin/<default>` in the session's worktree.
@@ -179,7 +179,7 @@ Skip on sub-path 3 (no branch — nothing to sync). If Step 4 was skipped, selec
179
179
  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.
180
180
  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.
181
181
  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.
182
- 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.
182
+ 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.
183
183
  6. **Check for an open MR/PR** on this branch and note its state.
184
184
  7. **Report what changed.** If either merge brought in new commits, post a one-line summary so the user knows the ground shifted.
185
185
 
@@ -201,7 +201,7 @@ Combine them into the report and post it in the conversation; use `--catchup` wh
201
201
 
202
202
  ## Step 7 — Start the work
203
203
 
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`.
204
+ Run `{{ALIGNFIRST}} assistant-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.assistantInstructionsFile`.
205
205
 
206
206
  {{#thread}}
207
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.
@@ -82,7 +82,7 @@ Any other key is a work conversation. Run `git rev-parse --path-format=absolute
82
82
 
83
83
  - PROJECT_PATH is the main worktree of the session's working directory: the parent of `git rev-parse --path-format=absolute --git-common-dir`. PROJECT is its directory name.
84
84
  - The workplace is the session's worktree (`git rev-parse --show-toplevel`) and its branch (`git branch --show-current`).
85
- - Run `{{ALIGNFIRST}} config --json` and `{{ALIGNFIRST}} developer-instructions` from the workplace. Retain the nullable `locations.developerInstructions` from the report to identify the configured source. The default branch is `config.conventions.git.defaultBranch` in the report, else the default branch identified by the project's instructions or configured remote. Ask when it is unclear. The report also names the project's companion directory, where its AlignFirst files may live.
85
+ - Run `{{ALIGNFIRST}} config --json` and `{{ALIGNFIRST}} assistant-instructions` from the workplace. Retain the nullable `locations.assistantInstructionsFile` from the report to identify the configured source. The default branch is `config.conventions.git.defaultBranch` in the report, else the default branch identified by the project's instructions or configured remote. Ask when it is unclear. The report also names the project's companion directory, where its AlignFirst files may live.
86
86
  {{/conversation}}
87
87
  {{#conversation}}
88
88
 
@@ -174,7 +174,7 @@ Resolve what the request leaves open:
174
174
  - Consultations require only PROJECT and PROJECT_PATH to start. Follow `{{GUIDE}} consultation` before ticket preflight, request capture, or workspace setup. A supplied ticket is context; the runbook decides whether to record the discussion.
175
175
 
176
176
  {{#openclaw}}
177
- Once a single-project request's PROJECT_PATH is known, run `{{ALIGNDEV}} project status <PROJECT_PATH>`. The report names its companion directory and nullable `locations.developerInstructions`. Run `{{ALIGNFIRST}} developer-instructions` from the selected workplace, or deliberately from PROJECT_PATH when no workplace is selected.
177
+ Once a single-project request's PROJECT_PATH is known, run `{{ALIGNDEV}} project status <PROJECT_PATH>`. The report names its companion directory and nullable `locations.assistantInstructionsFile`. Run `{{ALIGNFIRST}} assistant-instructions` from the selected workplace, or deliberately from PROJECT_PATH when no workplace is selected.
178
178
  {{/openclaw}}
179
179
 
180
180
  For changes, protocol requests, and ticket status requests, complete `{{GUIDE}} work-files-setup` as soon as PROJECT_PATH is known, before known-ticket `sync`/`ticket`, side-ticket reservation, or request capture.
@@ -214,7 +214,7 @@ Skip this step for consultations and operational work.
214
214
 
215
215
  For new single-project work where the user explicitly says there is no ticket or asks for a side ticket, complete `{{GUIDE}} work-files-setup` from PROJECT_PATH, then:
216
216
 
217
- 1. Run `{{ALIGNFIRST}} developer-instructions` from the selected workplace, or deliberately from PROJECT_PATH when no workplace is selected. It prints project conventions and any explicitly configured content.
217
+ 1. Run `{{ALIGNFIRST}} assistant-instructions` from the selected workplace, or deliberately from PROJECT_PATH when no workplace is selected. It prints project conventions and any explicitly configured content.
218
218
  2. Run `{{ALIGNFIRST}} sync`, so identifier selection sees the current shared task set.
219
219
  {{#openclaw}}
220
220
  3. Run `{{ALIGNFIRST}} ticket --side` from PROJECT_PATH (`exec`). It creates the ticket directory and prints it as TICKET_DIR; TICKET_ID is the `side-N` it reports.
@@ -401,7 +401,7 @@ After writing or editing any file under `.plans/` yourself, run `{{ALIGNFIRST}}
401
401
  A project has up to three entry points:
402
402
 
403
403
  - `README.md` — presentation, getting-started procedure…
404
- - The explicitly configured developer instructions — the agent's user, human or AI: you. Run `{{ALIGNFIRST}} developer-instructions` from the selected worktree. It reports the absolute source path for interpreting relative links. Without a configured reference, it prints conventions only; there is no filename fallback.
404
+ - The explicitly configured assistant instructions — the agent's user, human or AI: you. Run `{{ALIGNFIRST}} assistant-instructions` from the selected worktree. It reports the absolute source path for interpreting relative links. Without a configured reference, it prints project guidance; there is no filename fallback.
405
405
  - `AGENTS.md` — the agent. When the project's instructions come from its companion, the companion's `.alignfirst-instructions/context.md` replaces it for the agent, and `{{ALIGNFIRST}} context` prints it.
406
406
 
407
407
  The rest of the documentation (`docs/`, …) addresses everybody.
@@ -452,8 +452,8 @@ For an active development branch that needs to catch up with its base, follow th
452
452
 
453
453
  Every time a branch refresh brings in new commits (`git pull`, `git merge`, fast-forward, base-branch merge, …):
454
454
 
455
- 1. Reinstall dependencies with the project's package manager.
456
- 2. Rebuild, if the project needs it.
455
+ 1. Install dependencies if the incoming changes invalidate the installed dependencies.
456
+ 2. Rebuild affected outputs if needed for the next task.
457
457
  3. Run the database migrations, if the new commits added some.
458
458
 
459
459
  Delegate the sequence to the agent.
@@ -468,13 +468,13 @@ Before non-trivial code changes, like executing a plan, stop declared services w
468
468
 
469
469
  ### Tests, lint, build
470
470
 
471
- The project's checks are routine hygiene. The agent usually runs them on its own; have it run the checks only when they were forgotten.
471
+ The project's checks are routine hygiene. The agent usually runs them on its own; request only missing, relevant checks. Scope automated checks and other development tooling to the task's needs, reusing valid results and skipping unnecessary work. Broaden for uncertain impact or project requirements. Pass this rule to the agent and report material omissions.
472
472
 
473
473
  ### Always test the work manually
474
474
 
475
475
  Manual testing is what ends a code change: beyond the automated checks, the change gets exercised before any MR/PR and before telling the user it's finished. On the completion turn, verify first, then report, one consolidated message that ends the turn:
476
476
 
477
- 1. Confirm the checks passed (see "Tests, lint, build").
477
+ 1. Confirm the applicable checks passed (see "Tests, lint, build").
478
478
  2. Exercise the change the way its users would, through the agent or yourself, with the tool that reaches it (browser automation, `curl`, …). On a project with a dev-server, start it and drive the change in the UI. Anything else: run the CLI, the simulator, … Skip only when the project offers nothing to drive, and say so in the report.
479
479
  {{#thread}}
480
480
  3. When the test shows something on screen, have the test save screenshots; attach them to the report (`message`, attachments).
@@ -520,12 +520,12 @@ When the user brings up acceptance testing, first be sure who runs it — ask wh
520
520
 
521
521
  ### Project rules and docs
522
522
 
523
- Run `{{ALIGNFIRST}} config --json` from the selected worktree before editing instructions. Use the nullable `locations.developerInstructions` to identify the configured file; its path and existence are explicit. Use `locations[".alignfirst-instructions"]` for coding-agent companion context, with `.alignfirst-instructions/context.md` in place of `AGENTS.md`. The agent edits selected companion files in place. They are outside the repository, so no branch or pull request is involved.
523
+ Run `{{ALIGNFIRST}} config --json` from the selected worktree before editing instructions. Use the nullable `locations.assistantInstructionsFile` to identify the configured file; its path and existence are explicit. Use `locations[".alignfirst-instructions"]` for coding-agent companion context, with `.alignfirst-instructions/context.md` in place of `AGENTS.md`. The agent edits selected companion files in place. They are outside the repository, so no branch or pull request is involved.
524
524
 
525
525
  Two triggers, both edited through the agent:
526
526
 
527
- - You learn something non-obvious about how to work in a project — a command, a quirk, a convention not yet written down. Propose capturing it in the resolved configured developer-instructions file, ask for confirmation, then have the agent make the edit. With no reference, propose a suitable file and an explicit `developerInstructions` entry in the selected configuration, respecting its logical item placement; obtain approval before creating either.
528
- - The user asks to retain a rule for the project. No confirmation needed for the requested rule: retain it in the resolved developer-instructions file and, when relevant to coding, the coding-agent instructions. With no configured reference, obtain approval for a suitable file and explicit `developerInstructions` setting before writing. Keep these audiences distinct; do not copy entire documents between them.
527
+ - You learn something non-obvious about how to work in a project — a command, a quirk, a convention not yet written down. Propose capturing it in the resolved configured assistant-instructions file, ask for confirmation, then have the agent make the edit. With no reference, propose a suitable file and an explicit `assistantInstructionsFile` entry in the selected configuration, respecting its logical item placement; obtain approval before creating either.
528
+ - The user asks to retain a rule for the project. No confirmation needed for the requested rule: retain it in the resolved assistant-instructions file and, when relevant to coding, the coding-agent instructions. With no configured reference, obtain approval for a suitable file and explicit `assistantInstructionsFile` setting before writing. Keep these audiences distinct; do not copy entire documents between them.
529
529
 
530
530
  {{#thread}}
531
531
  When the thread has an active ticket and the rule is simple, add it on the current branch, so the ticket's PR carries it. When the rule is complex or the thread has no ticket, reserve a side ticket (Step 5), set up a workspace on a new branch for the rule, and create a pull request.
@@ -560,7 +560,7 @@ _Note: Before every code review, always start by updating both the base branch a
560
560
 
561
561
  A code review is the review workflow from the delegation guide: a fresh agent session (`review` protocol) writes a review file, then an optional fix step runs in a second fresh session, never in the review session. What to do with the review file depends on the case:
562
562
 
563
- - **Wrapping up your own work** — before creating a MR/PR, run the full workflow automatically, fix step included: decide the fixes with the agent in the AAD discussion. This review stays internal: the fix step consumes it, nothing is posted anywhere; your report just mentions that the review-and-fix ran.
563
+ - **Wrapping up your own work** — before creating a MR/PR, run the review and fix steps automatically: decide the fixes with the agent in the AAD discussion. Consider returning to the review session afterward, as the delegation guide describes. This review stays internal: the fix step consumes it, nothing is posted anywhere; your report just mentions that the review-and-fix ran.
564
564
  - **The user asks to review a PR/MR** (e.g. a teammate's branch) — follow the PR/MR review sequence below.
565
565
  - **The user asks to review a branch or workspace** — check for an open PR/MR on that branch first; if one exists, follow the PR/MR review sequence. Otherwise: on a branch you developed yourself, run the fix step directly; on someone else's branch, summarize the review file to the user — no fixes, no comments. Take the TICKET_ID from the branch name; ask the user when it carries none.
566
566
 
@@ -593,7 +593,7 @@ The author of a branch you reviewed pushes fixes and asks you to check them, or
593
593
 
594
594
  You are the judge of when the ticket's scope is done — a ticket can span several coding sessions, so no single run completion decides it. When you judge it done, create the MR/PR without asking.
595
595
 
596
- Before creating it: the code compiles, lint and tests pass, and you exercised the change manually (see "Always test the work manually"). Then run the review workflow with its fix step (see "Code review" above) — automatic, part of creating any MR/PR.
596
+ Before creating it: the applicable checks pass (see "Tests, lint, build"), and you exercised the change manually (see "Always test the work manually"). Then run the review workflow with its fix step (see "Code review" above) — automatic, part of creating any MR/PR.
597
597
 
598
598
  After creating the MR/PR (via `{{ALIGNDEV}} code`):
599
599
 
@@ -603,7 +603,7 @@ After creating the MR/PR (via `{{ALIGNDEV}} code`):
603
603
  Whenever you observe that a PR/MR is merged:
604
604
 
605
605
  1. Remove the source branch's linked workspace as "Cleanup requests" describes. A branch worked on in place stays checked out: the user decides when to leave it.
606
- 2. Delegate the refresh of the merge target without a protocol: in the main worktree, clean and on its base branch, fetch and fast-forward it, then reinstall dependencies, rebuild, and run new migrations when required.
606
+ 2. Delegate the refresh of the merge target without a protocol: in the main worktree, clean and on its base branch, fetch and fast-forward it, then apply "Refreshing the workspace after a branch refresh".
607
607
  3. Report the removed workspace and refreshed branch. When unsuitable plans block the refresh delegation, the removal still happens; report the blocked refresh.
608
608
  {{#app}}
609
609
 
@@ -641,7 +641,7 @@ When the user asks to clean the workspaces, from PROJECT_PATH:
641
641
 
642
642
  1. List the worktrees through `{{ALIGNFIRST}} workspace list --json`.
643
643
  2. For each linked workspace, find its branch's PR/MR through the configured code-hosting tool. Remove the workspace as in "Cleanup requests", only when that PR/MR is merged. Leave the others intact: in-place work, no PR/MR, or an unmerged PR/MR. Stop on the first failed removal.
644
- 3. When a workspace was removed, delegate the merge target's refresh as after a merge above, installing from the committed lockfile without rewriting it (`npm ci` with npm).
644
+ 3. When a workspace was removed, delegate the merge target's refresh as after a merge above. Any needed installation uses the committed lockfile without rewriting it (`npm ci` with npm).
645
645
  4. Report every decision, any blocked refresh, and the final base-branch state.
646
646
 
647
647
  {{#thread}}
@@ -4,7 +4,7 @@ A projects directory groups projects and optional nested projects directories. I
4
4
 
5
5
  A project is a git main worktree, direct child of a projects directory. Its linked worktrees are listed as its workspaces. Other child directories, those that are not git repositories, appear under `others`.
6
6
 
7
- A project's AlignFirst files may live in its companion directory, the `dir` of its entry in the companion registry `~/.alignfirst/companions/registry.json`. `{{ALIGNDEV}} project status <path>` gives each location, including nullable `locations.developerInstructions`. Run `{{ALIGNFIRST}} developer-instructions` from the selected worktree for its conventions and configured developer guide.
7
+ A project's AlignFirst files may live in its companion directory, the `dir` of its entry in the companion registry `~/.alignfirst/companions/registry.json`. `{{ALIGNDEV}} project status <path>` gives each location, including nullable `locations.assistantInstructionsFile`. Run `{{ALIGNFIRST}} assistant-instructions` from the selected worktree for its conventions and configured assistant guide.
8
8
 
9
9
  ## Commands
10
10