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