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.
- package/README.md +7 -5
- package/dist/alignfirst-cli.js +1 -2
- package/dist/cli.js +1 -11
- package/dist/code/code-cli.js +1 -1
- package/dist/guide/guide-cli.js +3 -6
- package/dist/guide/render-template.d.ts +0 -4
- package/dist/guide/render-template.js +3 -21
- package/dist/project/discovery.js +5 -12
- package/dist/project/layout.d.ts +22 -9
- package/dist/project/layout.js +101 -28
- package/dist/project/plans.d.ts +1 -1
- package/dist/project/render.js +3 -1
- package/dist/project/status.d.ts +2 -2
- package/dist/project/status.js +2 -2
- package/package.json +3 -2
- package/templates/guide/code.md +3 -1
- package/templates/guide/playbook/consultation.md +5 -15
- package/templates/guide/playbook/playbook.md +2 -5
- package/templates/guide/playbook/project-lifecycle.md +11 -11
- package/templates/guide/playbook/project-workspace-setup.md +10 -15
- package/templates/guide/playbook/work-files-setup.md +1 -1
- package/templates/guide/playbook/working-session.md +17 -51
- package/templates/guide/project.md +4 -4
- package/dist/guide/guide-file.d.ts +0 -3
- package/dist/guide/guide-file.js +0 -26
- package/dist/worktree/add.d.ts +0 -10
- package/dist/worktree/add.js +0 -81
- package/dist/worktree/git.d.ts +0 -24
- package/dist/worktree/git.js +0 -103
- package/dist/worktree/remove.d.ts +0 -8
- package/dist/worktree/remove.js +0 -62
- package/dist/worktree/setup.d.ts +0 -18
- package/dist/worktree/setup.js +0 -192
- package/dist/worktree/worktree-cli.d.ts +0 -10
- package/dist/worktree/worktree-cli.js +0 -140
|
@@ -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
|
|
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
|
|
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
|
|
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
|
-
{{
|
|
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:
|
|
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
|
|
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.
|
|
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.
|
|
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 `{{
|
|
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
|
|
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`
|
|
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.
|
|
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
|
|
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
|
|
111
|
-
2. List every linked worktree with its exact absolute path, through
|
|
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
|
|
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
|
-
{{
|
|
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.**
|
|
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.
|
|
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
|
-
|
|
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:**
|
|
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**:
|
|
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
|
-
|
|
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.
|
|
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. `{{
|
|
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
|
|
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
|
|
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
|
-
{{
|
|
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:
|
|
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
|
-
{{
|
|
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
|
|
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,
|
|
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
|
-
{{
|
|
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
|
-
|
|
559
|
-
-
|
|
560
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
-
|
|
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,
|
|
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.
|
package/dist/guide/guide-file.js
DELETED
|
@@ -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
|
-
}
|
package/dist/worktree/add.d.ts
DELETED
|
@@ -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;
|
package/dist/worktree/add.js
DELETED
|
@@ -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
|
-
}
|
package/dist/worktree/git.d.ts
DELETED
|
@@ -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;
|