aligndev 0.29.0 → 0.30.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.
@@ -8,26 +8,14 @@ The user consults you, and you consult the agent. It reads the repository; you w
8
8
 
9
9
  ## Step 1 — Select the worktree
10
10
 
11
- {{#openclaw}}
12
- Run `{{ALIGNDEV}} project status <PROJECT_PATH>` and retain its `DEVELOPERS.md` path as DEVELOPERS_PATH. Read DEVELOPERS_PATH and run `{{ALIGNFIRST}} context` from PROJECT_PATH.
13
- {{/openclaw}}
14
- {{#codingAgent}}
15
- {{#hasGuide}}
16
- Read DEVELOPERS_PATH, retained by Step 1 of `{{GUIDE}} working-session`, and run `{{ALIGNFIRST}} context` from PROJECT_PATH.
17
- {{/hasGuide}}
18
- {{#noGuide}}
19
- Run `{{ALIGNFIRST}} context` from PROJECT_PATH.
20
- {{/noGuide}}
21
- {{/codingAgent}}
22
-
23
11
  {{#thread}}
24
- Use the main worktree on the configured default branch. When the question explicitly concerns a branch or a PR, or follows ongoing branch work in this thread, use that branch's existing registered workspace instead: resolve it through the project's documented workspace list, or `{{ALIGNDEV}} worktree list --json` when no tooling exists. Report the limitation rather than inspecting a different branch when no worktree exists. Do not create a worktree merely to answer a question.
12
+ Use the main worktree on the configured default branch. When the question explicitly concerns a branch or a PR, or follows ongoing branch work in this thread, use that branch's existing registered workspace instead: resolve it through `{{ALIGNFIRST}} workspace list --json`. Report the limitation rather than inspecting a different branch when no worktree exists. Do not create a worktree merely to answer a question.
25
13
  {{/thread}}
26
14
  {{#app}}
27
- When this conversation started in a linked worktree of the project, use that worktree and its branch as they are. Otherwise use the main worktree on the configured default branch. When the question explicitly concerns another branch or a PR, or follows ongoing branch work in this conversation, use that branch's existing registered workspace instead: resolve it through the project's documented workspace list, or `{{ALIGNDEV}} worktree list --json` when no tooling exists. Report the limitation rather than inspecting a different branch when no worktree exists. Do not create a worktree merely to answer a question.
15
+ When this conversation started in a linked worktree of the project, use that worktree and its branch as they are. Otherwise use the main worktree on the configured default branch. When the question explicitly concerns another branch or a PR, or follows ongoing branch work in this conversation, use that branch's existing registered workspace instead: resolve it through `{{ALIGNFIRST}} workspace list --json`. Report the limitation rather than inspecting a different branch when no worktree exists. Do not create a worktree merely to answer a question.
28
16
  {{/app}}
29
17
  {{#codingAgent}}
30
- Use the session's worktree and its branch as they are. When the question explicitly concerns another branch or a PR, use that branch's existing registered workspace instead: resolve it through the project's documented workspace list, or `{{ALIGNDEV}} worktree list --json` when no tooling exists. Report the limitation rather than inspecting a different branch when no worktree exists. Do not create a worktree merely to answer a question.
18
+ Use the session's worktree and its branch as they are. When the question explicitly concerns another branch or a PR, use that branch's existing registered workspace instead: resolve it through `{{ALIGNFIRST}} workspace list --json`. Report the limitation rather than inspecting a different branch when no worktree exists. Do not create a worktree merely to answer a question.
31
19
  {{/codingAgent}}
32
20
 
33
21
  {{#openclaw}}
@@ -55,6 +43,8 @@ Retain `git rev-parse --short HEAD`, the revision the answer comes from. Report
55
43
 
56
44
  ## Step 3 — Delegate
57
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.
47
+
58
48
  Delegation creates session files under the work files, so complete `{{GUIDE}} work-files-setup` from PROJECT_PATH first.
59
49
 
60
50
  {{#thread}}
@@ -82,10 +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
- {{#hasGuide}}
86
- It also retains DEVELOPERS_PATH, the project's guide for you.
87
- {{/hasGuide}}
88
- PROJECT_PATH anchors project-file reads, 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}} 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.
89
86
 
90
87
  Creating, onboarding, or removing a project is not handled in this mode. When the user asks for it, say so.
91
88
  {{/codingAgent}}
@@ -121,7 +118,7 @@ You are an autonomous programmer. Instructions reach you from two places, and "t
121
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.
122
119
  {{/codingAgent}}
123
120
 
124
- Exception: a project's `DEVELOPERS.md` addresses the agent's user — you.
121
+ Exception: the explicitly configured developer instructions address the agent's user — you. Read them through `{{ALIGNFIRST}} developer-instructions` in the selected worktree.
125
122
 
126
123
  ## Effort estimates
127
124
 
@@ -20,7 +20,7 @@ Creation has a hard user-input gate. Before any filesystem, Git, port-allocation
20
20
 
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
- 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.
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 `devServer.ports` in the selected `alignfirst.json` or `.jsonc`. The selected parent's marker owns its port range. Report the manifest path and block.
24
24
  {{#thread}}
25
25
  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 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.
26
26
  {{/thread}}
@@ -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. 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.
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.
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. 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.
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.
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.
@@ -49,12 +49,12 @@ 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 `{{ALIGNDEV}} project status <PROJECT_PATH>` and retain its `DEVELOPERS.md` path as DEVELOPERS_PATH. When the project's workspace wrapper 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`.
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
53
  4. Install dependencies and build, 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 system is optional. The project is prepared when DEVELOPERS_PATH exists 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 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.
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 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.
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.
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
 
@@ -82,7 +82,7 @@ When the user reports the merge, or you observe it while checking the PR:
82
82
  2. Install dependencies and build.
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
- 5. Run the project's documented main-worktree workspace setup when it has one, otherwise its install/build/test commands.
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.
86
86
  6. Continue with the normal working-session flow for the original request through `{{GUIDE}} project-workspace-setup`.
87
87
 
88
88
  ### Prepare through the companion
@@ -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 `.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.
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.
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,10 +107,10 @@ 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 `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.
111
- 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.
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.
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
- 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.
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.
114
114
  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.
115
115
  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.
116
116
  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.
@@ -20,14 +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
- {{#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.
25
- {{/openclaw}}
26
- {{#codingAgent}}
27
- {{#hasGuide}}
28
- - Read DEVELOPERS_PATH, retained by Step 1 of `{{GUIDE}} working-session` — whether the project has workspace tooling, and how to create a worktree or a branch.
29
- {{/hasGuide}}
30
- {{/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
 
@@ -66,10 +59,10 @@ The workplace is the first case that matches:
66
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.
67
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.
68
61
 
69
- **Registration in place.** Working in place (cases 2 and 3, and "here" in case 5) in a linked worktree that the project's tooling does not list starts with its registration, run in the foreground before the `[WORKSPACE]` banner. With workspace tooling, run its documented adoption command in that worktree: `workspace setup` without a branch for the AlignFirst workspace system, after the project's install when its wrapper needs one. Without tooling, run `{{ALIGNDEV}} worktree setup --json` in that worktree: it shares the work files and reports readiness for Git and work files only. Neither runs on the main worktree. The banner reports the state the registration returns.
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.
70
63
  {{#app}}
71
64
 
72
- **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. After `workspace remove` or `{{ALIGNDEV}} worktree remove` deletes it, OpenClaw marks its record removed.
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.
73
66
  {{/app}}
74
67
 
75
68
  ## Step 3 — Post the setup signal
@@ -115,14 +108,14 @@ That single call is the whole exception. The post right after it, and every one
115
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.
116
109
  {{/thread}}
117
110
 
118
- The project has workspace tooling when its developer guide documents one, whatever the implementation. Use it when present; otherwise use `{{ALIGNDEV}} worktree list/add/setup/remove`. Never bypass it with raw `git worktree add`/`remove`/`prune` or directory deletion. An external tool owning Git creation and deletion is a separate case; adopt its selected worktree through the applicable setup tooling.
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.
119
112
 
120
- **Existing-workplace preparation:** follow the project's documented readiness/setup procedure when it has tooling. Otherwise run `{{ALIGNDEV}} worktree setup <exact-worktree-root> --json` yourself before reporting readiness or delegating. Registration alone does not prove readiness, including for externally created worktrees. Setup keeps the selected path and branch without creating or switching branches. Without a path, it discovers the current root even from nested cwd; an explicit path resolves relative to the caller and must name an exact registered root of the same repository. Conflicts remain untouched. Repair the reported problem and retry the idempotent setup to complete partial preparation. Relay failures and delete nothing; plans provisioning or migration requires the separate authorization in `{{GUIDE}} work-files-setup`.
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.
121
114
 
122
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:
123
116
 
124
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.
125
- - **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.
118
+ - **Worktrees**: `{{ALIGNFIRST}} workspace list --json` from PROJECT_PATH. Report a missing, locked, or prunable entry instead of repairing it.
126
119
 
127
120
  Never assume the branch is new; `git worktree list` alone does not answer the branch question.
128
121
 
@@ -132,7 +125,7 @@ Whenever a branch exists, you work from its workspace — a status request inclu
132
125
  2. **Branch exists (local or remote), no workspace** → set up a workspace on the existing branch (don't create a new branch).
133
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.
134
127
 
135
- 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.
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.
136
129
 
137
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.
138
131
 
@@ -167,7 +160,7 @@ Branch: `{branch}`
167
160
  Status: {running | ready | failed}
168
161
  ```
169
162
 
170
- 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 prepared by `{{ALIGNDEV}} worktree add` or `setup`, 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.
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.
171
164
 
172
165
  {{#thread}}
173
166
  ## Step 5 — Sync an existing branch on takeover (sub-paths 1 & 2)
@@ -208,6 +201,8 @@ Combine them into the report and post it in the conversation; use `--catchup` wh
208
201
 
209
202
  ## Step 7 — Start the work
210
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`.
205
+
211
206
  {{#thread}}
212
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.
213
208
  {{/thread}}
@@ -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. `{{ALIGNDEV}} worktree add` and coding launches validate work files; they do not authorize this selection or provision missing plans.
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.
@@ -82,16 +82,8 @@ 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` from PROJECT_PATH. The default branch is `config.git.defaultBranch` in the report, else the default branch identified by the project's instructions or configured remote. Ask when it is unclear. The report also names the project's companion directory, where its AlignFirst files may live.
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.
86
86
  {{/conversation}}
87
- {{#codingAgent}}
88
- {{#developers}}
89
- - Retain `locations["DEVELOPERS.md"].path` from the report as DEVELOPERS_PATH.
90
- {{/developers}}
91
- {{#readme}}
92
- - Retain `README.md` at the root of PROJECT_PATH as DEVELOPERS_PATH: the project has no `DEVELOPERS.md`, and its README is your guide.
93
- {{/readme}}
94
- {{/codingAgent}}
95
87
  {{#conversation}}
96
88
 
97
89
  These values hold for the whole session. Only `{{GUIDE}} project-workspace-setup` moves the workplace.
@@ -182,7 +174,7 @@ Resolve what the request leaves open:
182
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.
183
175
 
184
176
  {{#openclaw}}
185
- Once a single-project request's PROJECT_PATH is known, run `{{ALIGNDEV}} project status <PROJECT_PATH>` and retain its `DEVELOPERS.md` path as DEVELOPERS_PATH. The report also names the project's companion directory, where its AlignFirst files may live.
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.
186
178
  {{/openclaw}}
187
179
 
188
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.
@@ -222,15 +214,7 @@ Skip this step for consultations and operational work.
222
214
 
223
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:
224
216
 
225
- {{#openclaw}}
226
- 1. Read DEVELOPERS_PATH and run `{{ALIGNFIRST}} context` from PROJECT_PATH.
227
- {{/openclaw}}
228
- {{#codingAgent}}
229
- 1. Run `{{ALIGNFIRST}} context` from PROJECT_PATH.
230
- {{#hasGuide}}
231
- Read DEVELOPERS_PATH.
232
- {{/hasGuide}}
233
- {{/codingAgent}}
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.
234
218
  2. Run `{{ALIGNFIRST}} sync`, so identifier selection sees the current shared task set.
235
219
  {{#openclaw}}
236
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.
@@ -368,7 +352,7 @@ Workspace cleanup follows "Cleanup requests". Delegate base-branch refresh and o
368
352
 
369
353
  Lean toward delegating; the less you touch the project directly, the better.
370
354
 
371
- Delegate to the agent: the project's workspace setup, writing code (`alignfirst` protocols), commits, pushes, opening MR/PRs. You run `{{ALIGNDEV}} worktree list/add/setup/remove` and `{{GUIDE}} work-files-setup` yourself; neither needs a coding launch.
355
+ Delegate to the agent: writing code (`alignfirst` protocols), project-specific installation/build/test work, commits, pushes, opening MR/PRs. You run `{{ALIGNFIRST}} workspace` preparation and cleanup and `{{GUIDE}} work-files-setup` yourself; neither needs a coding launch.
372
356
 
373
357
  Delegate reasoning too, whether for the user or your own next step. Ask the agent for ideas, design advice, opinions, or approaches, and build on its answer.
374
358
 
@@ -417,17 +401,7 @@ After writing or editing any file under `.plans/` yourself, run `{{ALIGNFIRST}}
417
401
  A project has up to three entry points:
418
402
 
419
403
  - `README.md` — presentation, getting-started procedure…
420
- {{#openclaw}}
421
- - `DEVELOPERS.md` — the agent's user, human or AI: you. Read it at DEVELOPERS_PATH.
422
- {{/openclaw}}
423
- {{#codingAgent}}
424
- {{#developers}}
425
- - `DEVELOPERS.md` — the agent's user, human or AI: you. Read it at DEVELOPERS_PATH.
426
- {{/developers}}
427
- {{#readme}}
428
- - `DEVELOPERS.md` — the agent's user, human or AI: you. This project has none, so `README.md` is also your guide, read at DEVELOPERS_PATH.
429
- {{/readme}}
430
- {{/codingAgent}}
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.
431
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.
432
406
 
433
407
  The rest of the documentation (`docs/`, …) addresses everybody.
@@ -451,7 +425,7 @@ Running the dev-server from the main worktree is fine.
451
425
 
452
426
  ### Linked worktrees and other branches
453
427
 
454
- `{{GUIDE}} project-workspace-setup` selects and prepares the workplace: through the project's documented workspace tooling, including non-Node implementations, when it has one; through `{{ALIGNDEV}} worktree list/add/setup/remove` otherwise. Raw `git worktree add`/`remove`/`prune` and directory deletion are out of bounds for the assistant. External tools may own Git creation and deletion; prepare their selected existing worktree through the applicable tooling rather than creating another branch. Lightweight setup is idempotent, so repair reported conflicts and retry after partial preparation. It covers Git and work files only; repository preparation and shutdown remain separate, with no lightweight teardown command or pre-deletion hook.
428
+ `{{GUIDE}} project-workspace-setup` selects and prepares the workplace through `{{ALIGNFIRST}} workspace` with the branch-local manifest or defaults. Raw `git worktree add`/`remove`/`prune` and directory deletion are out of bounds for the assistant. External tools may own Git creation and deletion; adopt their selected existing worktree rather than creating another branch, then run `{{ALIGNFIRST}} workspace teardown` before their deletion. Repair reported conflicts and retry partial setup. Default readiness is protocol-ready; it does not install, build or start the application.
455
429
 
456
430
  ### Updating a branch with the base branch
457
431
 
@@ -490,7 +464,7 @@ A request for a ticket's progress goes through `{{GUIDE}} project-workspace-setu
490
464
 
491
465
  ### Dev-server while working
492
466
 
493
- Before non-trivial code changes, like executing a plan, always stop the dev-server. Otherwise it will consume resources and might even interfere with the work.
467
+ Before non-trivial code changes, like executing a plan, stop declared services with `{{ALIGNFIRST}} dev down`. They consume resources and might interfere with the work. Start them with `{{ALIGNFIRST}} dev` only when needed; default workspaces have no services.
494
468
 
495
469
  ### Tests, lint, build
496
470
 
@@ -546,26 +520,18 @@ When the user brings up acceptance testing, first be sure who runs it — ask wh
546
520
 
547
521
  ### Project rules and docs
548
522
 
549
- {{#openclaw}}
550
- A project whose `.alignfirst-instructions` or `DEVELOPERS.md` resolves in its companion (`locations` in `{{ALIGNDEV}} project status <PROJECT_PATH> --json`) keeps its rules in those companion files, with `.alignfirst-instructions/context.md` in place of `AGENTS.md`. The agent edits them in place. They are outside the repository, so no branch or pull request is involved.
551
- {{/openclaw}}
552
- {{#codingAgent}}
553
- A project whose `.alignfirst-instructions` or `DEVELOPERS.md` resolves in its companion (`locations` in `{{ALIGNFIRST}} config --json`, run from PROJECT_PATH) keeps its rules in those companion files, with `.alignfirst-instructions/context.md` in place of `AGENTS.md`. The agent edits them in place. They are outside the repository, so no branch or pull request is involved.
554
- {{/codingAgent}}
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.
555
524
 
556
525
  Two triggers, both edited through the agent:
557
526
 
558
- {{#openclaw}}
559
- - 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 DEVELOPERS_PATH, ask for confirmation, then have the agent make the edit.
560
- {{/openclaw}}
561
- {{#codingAgent}}
562
- - 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 project's `DEVELOPERS.md`, created at the repository root when the project has none, ask for confirmation, then have the agent make the edit.
563
- {{/codingAgent}}
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.
529
+
564
530
  {{#thread}}
565
- - The user asks to retain a rule for the project. No confirmation needed: the rule goes into both `AGENTS.md` and `DEVELOPERS.md`. 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.
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.
566
532
  {{/thread}}
567
533
  {{#conversation}}
568
- - The user asks to retain a rule for the project. No confirmation needed: the rule goes into both `AGENTS.md` and `DEVELOPERS.md`. When the session 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 session 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.
534
+ When the session 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 session 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.
569
535
  {{/conversation}}
570
536
 
571
537
  {{#openclaw}}
@@ -641,7 +607,7 @@ Whenever you observe that a PR/MR is merged:
641
607
  3. Report the removed workspace and refreshed branch. When unsuitable plans block the refresh delegation, the removal still happens; report the blocked refresh.
642
608
  {{#app}}
643
609
 
644
- This conversation's own worktree, once `{{GUIDE}} project-workspace-setup` adopted and registered it, is a linked workspace like any other: remove it too. The report then says that this conversation is finished and can be archived.
610
+ For this conversation's externally owned worktree, run `{{ALIGNFIRST}} workspace teardown` and report that it is ready for its owner to archive and delete. Adoption does not transfer deletion ownership.
645
611
  {{/app}}
646
612
 
647
613
  ### Protected directories
@@ -657,7 +623,7 @@ When the user asks to tear down one named project workspace (or worktree) from i
657
623
  When the user asks to tear down one named project workspace (or worktree):
658
624
  {{/conversation}}
659
625
 
660
- 1. Resolve the exact linked-worktree path through the selected tooling; ask the user when it is ambiguous. With workspace tooling, have the agent run its removal procedure, which also tears down the dev environment. When an external tool owns deletion, follow its lifecycle and arrange project-specific shutdown separately. Otherwise, without workspace tooling, stop whatever the project runs there, then run `{{ALIGNDEV}} worktree remove <exact-path>` from PROJECT_PATH yourself: it refuses a dirty or locked worktree, and you never force it. This direct removal needs no coding launch or work-files preparation, even when plans are unsuitable.
626
+ 1. Resolve the exact linked-worktree path through `{{ALIGNFIRST}} workspace list --json`; ask the user when it is ambiguous. Run `{{ALIGNFIRST}} workspace remove <exact-path>` from PROJECT_PATH yourself. It stops services, purges resources and protects dirty, locked, main, nested and shared-target paths; never force it. When an external tool owns deletion, run `{{ALIGNFIRST}} workspace teardown <exact-path>` instead, then let that owner delete it. Neither operation needs a coding launch or work-files preparation, even when plans are unsuitable. Stop on failure and retain state for retry.
661
627
  2. Confirm what was removed.
662
628
  {{#thread}}
663
629
  3. Reset the thread session.
@@ -673,7 +639,7 @@ When the user asks to clean the workspaces, for each affected PROJECT_PATH:
673
639
  When the user asks to clean the workspaces, from PROJECT_PATH:
674
640
  {{/codingAgent}}
675
641
 
676
- 1. List the worktrees through the selected tooling: the project's workspace list, or `{{ALIGNDEV}} worktree list --json`.
642
+ 1. List the worktrees through `{{ALIGNFIRST}} workspace list --json`.
677
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.
678
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).
679
645
  4. Report every decision, any blocked refresh, and the final base-branch state.
@@ -698,4 +664,4 @@ Creating a project, onboarding a repository to clone, or physically removing a p
698
664
  ### Forbidden
699
665
 
700
666
  - Never force push. Never rebase, reset, or amend a commit that exists on the remote.
701
- - Create and remove worktrees only through the project's workspace tooling or `{{ALIGNDEV}} worktree`.
667
+ - Create, adopt and clean workspaces through `{{ALIGNFIRST}} workspace`; preserve external deletion ownership.
@@ -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.
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.
8
8
 
9
9
  ## Commands
10
10
 
@@ -24,10 +24,10 @@ inventory issues.
24
24
 
25
25
  ## Port claims
26
26
 
27
- Run `{{ALIGNDEV}} project free-ports --size <n>` with the size of the project's port range: port names × expected concurrent workspaces. The directory section identifies the range for each project kind. Pass `--range <code>` for a coded range; the default needs no flag. The setup guide writes the returned block as `portRange` in the project's `.alignfirst.json`.
27
+ Run `{{ALIGNDEV}} project free-ports --size <n>` with the size of the project's port range: port names × expected concurrent workspaces. The directory section identifies the range for each project kind. Pass `--range <code>` for a coded range; the default needs no flag. This is a lookup, not a reservation. The setup guide writes the returned block in the selected merged configuration's `devServer.ports`.
28
28
 
29
- The project config is its registration. Deleting the project removes it from the listing. The workspace dev-server refuses a command when the project's `portRange` disagrees with the `ports` range of its config.
29
+ Git main-worktree discovery identifies the project. The `alignfirst config --json` report supplies validated workspace metadata; project/companion conventions carry no duplicate port claim.
30
30
 
31
31
  ## Reported issues
32
32
 
33
- The listing reports invalid project configs, non-main root projects, a `.alignfirst.json` outside a git main worktree, project or nested-directory ranges outside their enclosing range, overlapping project ranges, and projects whose registry entries resolve to the same companion directory.
33
+ The listing reports invalid project configs, non-main root projects, an `alignfirst.json` or `alignfirst.jsonc` outside a git main worktree, project or nested-directory ranges outside their enclosing range, overlapping project ranges, and projects whose registry entries resolve to the same companion directory.
@@ -1,3 +0,0 @@
1
- import type { ProjectsCallerContext } from "../project/project-cli.js";
2
- import type { GuideFileCondition } from "./render-template.js";
3
- export declare function resolveGuideFile(ctx: ProjectsCallerContext): GuideFileCondition;
@@ -1,26 +0,0 @@
1
- import { execFileSync } from "node:child_process";
2
- import { existsSync } from "node:fs";
3
- import { dirname, join } from "node:path";
4
- import { readProjectReport } from "../project/layout.js";
5
- // The project's guide file for the coding-agent assistant, resolved from PROJECT_PATH, the main
6
- // worktree of the working directory: its `DEVELOPERS.md`, else its `README.md`, else none.
7
- export function resolveGuideFile(ctx) {
8
- const projectPath = mainWorktree(ctx);
9
- if (projectPath === undefined)
10
- return "noGuide";
11
- const report = readProjectReport(ctx.alignfirstCommand, projectPath, ctx.env);
12
- if ("error" in report)
13
- throw new Error(report.error);
14
- if (report.locations["DEVELOPERS.md"].exists)
15
- return "developers";
16
- return existsSync(join(projectPath, "README.md")) ? "readme" : "noGuide";
17
- }
18
- function mainWorktree(ctx) {
19
- try {
20
- const commonDir = execFileSync("git", ["-C", ctx.cwd, "rev-parse", "--path-format=absolute", "--git-common-dir"], { encoding: "utf8", env: ctx.env, stdio: ["ignore", "pipe", "ignore"] }).trim();
21
- return dirname(commonDir);
22
- }
23
- catch {
24
- return;
25
- }
26
- }
@@ -1,10 +0,0 @@
1
- import { type Repository } from "./git.js";
2
- import { type WorktreeReport } from "./setup.js";
3
- import type { WorktreeContext } from "./worktree-cli.js";
4
- export interface AddOptions {
5
- path: string;
6
- branch: string;
7
- newBranch: boolean;
8
- start?: string;
9
- }
10
- export declare function addWorktree(ctx: WorktreeContext, repo: Repository, options: AddOptions): WorktreeReport;
@@ -1,81 +0,0 @@
1
- import { statSync } from "node:fs";
2
- import { dirname, resolve } from "node:path";
3
- import { errorMessage } from "../errors.js";
4
- import { canonicalPath, git, isInside, pathExists } from "./git.js";
5
- import { finishSetup, prepareDirectories, } from "./setup.js";
6
- export function addWorktree(ctx, repo, options) {
7
- const prepared = prepareAdd(ctx, repo, options);
8
- createGitWorktree(ctx, options, prepared);
9
- return finishSetup(ctx, repo, prepared.destination, { directories: prepared.directories, warnings: prepared.warnings }, options.branch);
10
- }
11
- function prepareAdd(ctx, repo, options) {
12
- const destination = validateDestination(ctx, repo, options.path);
13
- const branch = prepareBranch(ctx, repo, options);
14
- const prepared = prepareDirectories(ctx, repo, destination, branch.commit);
15
- return { destination, branch, ...prepared };
16
- }
17
- function validateDestination(ctx, repo, input) {
18
- const literal = resolve(ctx.cwd, input);
19
- if (pathExists(literal))
20
- throw new Error(`Destination already exists: ${literal}`);
21
- const destination = canonicalPath(literal);
22
- let ancestor = dirname(destination);
23
- while (!pathExists(ancestor))
24
- ancestor = dirname(ancestor);
25
- if (!statSync(ancestor).isDirectory())
26
- throw new Error(`Destination parent is not a directory: ${ancestor}`);
27
- for (const tree of repo.worktrees) {
28
- if (isInside(tree.path, destination) || isInside(destination, tree.path)) {
29
- throw new Error(`Destination overlaps registered worktree ${tree.path}. Choose a new sibling directory.`);
30
- }
31
- }
32
- return destination;
33
- }
34
- function prepareBranch(ctx, repo, options) {
35
- git(ctx, "check-ref-format", `refs/heads/${options.branch}`);
36
- if (options.branch.startsWith("-") || options.branch === "HEAD")
37
- throw new Error("Invalid branch name.");
38
- const occupied = repo.worktrees.find((tree) => tree.branch === options.branch);
39
- if (occupied !== undefined)
40
- throw new Error(`Branch ${options.branch} is already checked out at ${occupied.path}; reuse that worktree.`);
41
- const localRef = `refs/heads/${options.branch}`;
42
- const locals = git(ctx, "for-each-ref", "--format=%(refname)", "refs/heads").trim().split("\n");
43
- const exists = locals.includes(localRef);
44
- if (options.newBranch && exists)
45
- throw new Error(`Branch already exists: ${options.branch}`);
46
- let start = options.start ?? "HEAD";
47
- let create = options.newBranch;
48
- let track = false;
49
- if (!options.newBranch) {
50
- if (exists)
51
- start = localRef;
52
- else {
53
- const remotes = git(ctx, "for-each-ref", "--format=%(refname)", "refs/remotes")
54
- .trim()
55
- .split("\n")
56
- .filter((ref) => ref.slice("refs/remotes/".length).split("/").slice(1).join("/") === options.branch);
57
- if (remotes.length !== 1 || remotes[0] === undefined) {
58
- throw new Error(remotes.length === 0
59
- ? `No local or fetched remote branch: ${options.branch}`
60
- : `Ambiguous remote branch ${options.branch}: ${remotes.join(", ")}. Choose explicitly with -b <branch> <remote/ref>.`);
61
- }
62
- start = remotes[0];
63
- create = true;
64
- track = true;
65
- }
66
- }
67
- const commit = git(ctx, "rev-parse", "--verify", "--end-of-options", `${start}^{commit}`).trim();
68
- return { create, start: !create ? options.branch : start, commit, track };
69
- }
70
- function createGitWorktree(ctx, options, prepared) {
71
- const { branch, destination } = prepared;
72
- const createArgs = branch.create
73
- ? ["-b", options.branch, ...(branch.track ? ["--track"] : [])]
74
- : [];
75
- try {
76
- git(ctx, "worktree", "add", ...createArgs, "--", destination, branch.start);
77
- }
78
- catch (error) {
79
- throw new Error(`Git worktree creation failed: ${errorMessage(error)}\nInspect ${destination} and branch ${options.branch} for partial effects before retrying. No rollback was attempted.`);
80
- }
81
- }
@@ -1,24 +0,0 @@
1
- export interface GitContext {
2
- cwd: string;
3
- env: NodeJS.ProcessEnv;
4
- }
5
- export interface Repository {
6
- mainWorktree: string;
7
- commonDir: string;
8
- worktrees: Worktree[];
9
- }
10
- export interface Worktree {
11
- path: string;
12
- branch: string | null;
13
- main: boolean;
14
- exists: boolean;
15
- locked: boolean;
16
- prunable: boolean;
17
- }
18
- export declare function readRepository(ctx: GitContext): Repository;
19
- export declare function isProjectTrackedDirectory(ctx: GitContext, path: string, identity: string): boolean;
20
- export declare function readWorktrees(ctx: GitContext, mainWorktree: string): Worktree[];
21
- export declare function canonicalPath(path: string): string;
22
- export declare function pathExists(path: string): boolean;
23
- export declare function isInside(parent: string, path: string): boolean;
24
- export declare function git(ctx: GitContext, ...args: string[]): string;