aligndev 0.23.3 → 0.25.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.
Files changed (48) hide show
  1. package/README.md +74 -19
  2. package/dist/alignfirst-cli.d.ts +1 -0
  3. package/dist/alignfirst-cli.js +43 -1
  4. package/dist/cli.js +7 -14
  5. package/dist/code/claude-agent.d.ts +1 -1
  6. package/dist/code/claude-agent.js +25 -11
  7. package/dist/code/code-cli.d.ts +9 -4
  8. package/dist/code/code-cli.js +216 -84
  9. package/dist/code/codex-agent.d.ts +2 -2
  10. package/dist/code/codex-agent.js +24 -8
  11. package/dist/code/codex-rollout.d.ts +1 -1
  12. package/dist/code/codex-rollout.js +9 -5
  13. package/dist/code/coding-agent.d.ts +1 -1
  14. package/dist/code/coding-agent.js +13 -4
  15. package/dist/code/models.d.ts +2 -2
  16. package/dist/code/models.js +27 -15
  17. package/dist/code/native-context.d.ts +2 -0
  18. package/dist/code/native-context.js +21 -0
  19. package/dist/code/pi-agent.d.ts +2 -0
  20. package/dist/code/pi-agent.js +240 -0
  21. package/dist/code/quota-process.d.ts +9 -0
  22. package/dist/code/quota-process.js +165 -0
  23. package/dist/code/quota.d.ts +2 -3
  24. package/dist/code/quota.js +92 -98
  25. package/dist/code/run-agent.d.ts +12 -3
  26. package/dist/code/run-agent.js +48 -19
  27. package/dist/code/session-file.d.ts +3 -0
  28. package/dist/code/session-file.js +33 -10
  29. package/dist/config.d.ts +44 -7
  30. package/dist/config.js +163 -36
  31. package/dist/guide/code-guide.d.ts +2 -2
  32. package/dist/guide/code-guide.js +17 -6
  33. package/dist/guide/guide-cli.js +16 -7
  34. package/dist/json-shape.d.ts +3 -0
  35. package/dist/json-shape.js +23 -0
  36. package/dist/package-version.d.ts +1 -0
  37. package/dist/package-version.js +7 -0
  38. package/dist/project/layout.d.ts +4 -0
  39. package/dist/project/layout.js +28 -10
  40. package/dist/project/render.js +3 -1
  41. package/dist/project/status.d.ts +2 -1
  42. package/dist/project/status.js +1 -0
  43. package/package.json +1 -1
  44. package/templates/guide/code.md +102 -21
  45. package/templates/guide/playbook/consultation.md +5 -0
  46. package/templates/guide/playbook/playbook.md +12 -2
  47. package/templates/guide/playbook/project-workspace-setup.md +1 -1
  48. package/templates/guide/playbook/working-session.md +10 -0
@@ -4,7 +4,7 @@ export function renderProjectList(inventory) {
4
4
  if (inventory.projects.length === 0)
5
5
  lines.push(" (none)");
6
6
  for (const project of inventory.projects) {
7
- lines.push(`- Name: ${renderOutputValue(project.name)}`, ` Path: ${renderOutputValue(project.path)}`, ` Directory: ${renderOutputValue(project.directory)}`, ` Port range: ${renderProjectRange(project.portRange, project.portRangeCode)}`, ` Workspaces: ${renderValues(project.workspaces)}`);
7
+ lines.push(`- Name: ${renderOutputValue(project.name)}`, ` Path: ${renderOutputValue(project.path)}`, ` Directory: ${renderOutputValue(project.directory)}`, ` Port range: ${renderProjectRange(project.portRange, project.portRangeCode)}`, ` AlignDev profile: ${renderNullableValue(project.description.aligndev?.profile ?? null)}`, ` Workspaces: ${renderValues(project.workspaces)}`);
8
8
  }
9
9
  lines.push("", "Directories:");
10
10
  if (inventory.directories.length === 0)
@@ -47,6 +47,7 @@ export function renderProjectListJson(inventory) {
47
47
  portRange: project.portRange ?? null,
48
48
  portRangeCode: project.portRangeCode ?? null,
49
49
  companion: project.description.companion,
50
+ aligndev: project.description.aligndev,
50
51
  locations: project.description.locations,
51
52
  workspaces: project.workspaces,
52
53
  })),
@@ -86,6 +87,7 @@ export function renderProjectStatus(details) {
86
87
  ` Port range: ${renderProjectRange(details.portRange ?? undefined, details.portRangeCode ?? undefined)}`,
87
88
  ` Config source: ${details.configSource ?? "(none)"}`,
88
89
  ` Companion: ${renderCompanion(details.companion)}`,
90
+ ` AlignDev profile: ${renderNullableValue(details.aligndev?.profile ?? null)}`,
89
91
  ` DEVELOPERS.md: ${renderLocation(details.locations["DEVELOPERS.md"])}`,
90
92
  ` Work files: ${renderLocation(details.locations[".plans"])}`,
91
93
  ` Work-files folder: ${renderNullableValue(details.plansFolder)}`,
@@ -1,5 +1,5 @@
1
1
  import type { ProjectInventory } from "./discovery.js";
2
- import type { CompanionReport, ConfigSource, ItemLocation, ItemName } from "./layout.js";
2
+ import type { AligndevProjectSettings, CompanionReport, ConfigSource, ItemLocation, ItemName } from "./layout.js";
3
3
  import type { PortRange } from "./markers.js";
4
4
  export interface ProjectDetails {
5
5
  name: string;
@@ -12,6 +12,7 @@ export interface ProjectDetails {
12
12
  ticketIdPattern: string | null;
13
13
  configSource: ConfigSource | null;
14
14
  companion: CompanionReport | null;
15
+ aligndev: AligndevProjectSettings | null;
15
16
  locations: Record<ItemName, ItemLocation>;
16
17
  workspaces: string[];
17
18
  worktrees: ProjectWorktree[];
@@ -34,6 +34,7 @@ function buildProjectDetails(project) {
34
34
  ticketIdPattern: project.description.config?.ticketIdPattern ?? null,
35
35
  configSource: project.description.source,
36
36
  companion: project.description.companion,
37
+ aligndev: project.description.aligndev,
37
38
  locations: project.description.locations,
38
39
  workspaces: project.workspaces,
39
40
  worktrees: readWorktrees(project.path),
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "aligndev",
3
- "version": "0.23.3",
3
+ "version": "0.25.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.",
@@ -13,6 +13,8 @@ Run `{{ALIGNDEV}} code` from the root of the target project, so the agent works
13
13
 
14
14
  {{ALIGNFIRST_SETUP}}
15
15
 
16
+ Each ticketed run writes `.plans/<ticket>/_aligndev/<stamp>.md`. This file is the durable record of the run. It may live in the project's companion directory; the `sessionFile:` line of `{{ALIGNDEV}} code status` gives the actual path. Its frontmatter carries `status` (`running` → `succeeded`/`failed`) and the `sessionId`, and the `---- Result ----` block holds the outcome. A run that answers more than once lists each response oldest first, separated by `---- Later result ----`. A substantive report may precede a short later acknowledgement; report the substantive outcome.
17
+
16
18
  {{#openclaw}}
17
19
  ## How it runs
18
20
 
@@ -35,8 +37,6 @@ Under OpenClaw, background it through the `exec` tool:
35
37
 
36
38
  As soon as the run is backgrounded, tell the user — in the user's language — that the agent is now working in the background and that you will report back when it finishes (e.g. *"The agent is running in the background — I'll let you know as soon as it's done."*). Post it even when the user asked to be notified only at completion: this line is the promise of exactly that, not an interruption — a launch with no acknowledgement reads as a session gone silent. The acknowledgement is the plain text that ends the turn on every surface. Only the final message is guaranteed to post, so write nothing and call no tool after it. Do **not** also post it via `message`, and do **not** poll.
37
39
 
38
- Each ticketed run writes `.plans/<ticket>/_aligndev/<stamp>.md`. This file is the durable record of the run. It may live in the project's companion directory; the `sessionFile:` line of `{{ALIGNDEV}} code status` gives the actual path. Its frontmatter carries `status` (`running` → `succeeded`/`failed`) and the `sessionId`, and the `---- Result ----` block holds the outcome.
39
-
40
40
  **One protocol run at a time per workspace and per ticket** — protocol runs share the working tree, and the ticket's work files. Finish (or kill) the current protocol run before launching or resuming another. Plain messages (answers, questions) can be sent at any time.
41
41
 
42
42
  ## After a background run completes
@@ -66,32 +66,66 @@ If the frontmatter's `exitReason` is `auth_required`, the coding agent is not au
66
66
  {{#codingAgent}}
67
67
  ## How it runs
68
68
 
69
- `{{ALIGNDEV}} code` runs the agent in the **foreground** and blocks until it finishes, streaming the transcript to stdout. It never backgrounds or detaches itself.
69
+ `{{ALIGNDEV}} code` runs the agent in the **foreground** until it exits. It never backgrounds or detaches itself. By default it streams the transcript to stdout; `--quiet` suppresses that stream while preserving the durable session file and control/diagnostic output.
70
+
71
+ Choose the launch facility from your **parent host**, independently of the selected child `{{AGENT}}`. The selected profile chooses the child only. All three children (Claude Code, Codex, Pi) remain available from any supported parent.
70
72
 
71
- Its first line, `Session file: <path>`, names the run's session file, the durable record of the run; retain that path. The file may live in the project's companion directory. Its frontmatter carries `status` (`running` → `succeeded`/`failed`) and the `sessionId`, and the `---- Result ----` block holds the outcome.
73
+ **One protocol run at a time per worktree and per ticket** — protocol runs share the working tree, and the ticket's work files. Finish (or cancel) the current protocol run before launching or resuming another. Plain messages (answers, questions) can be sent at any time.
72
74
 
73
- Coding runs can be long (several hours is fine), and a foreground command is subject to your tool timeout (10 minutes in Claude Code). **Always start `{{ALIGNDEV}} code` with your own background-execution facility, with no time limit.** Never detach it with `&` or a detach wrapper.
75
+ ## Background runs and reporting
74
76
 
75
- Run `{{ALIGNDEV}} code` outside your sandbox: the agent needs network access, and it writes outside the project, to its own session storage and possibly to the companion directory. In Codex, request escalated permissions for the command. In Claude Code with sandboxing enabled, run it with the sandbox disabled.
77
+ ### Pi parent
76
78
 
77
- **One protocol run at a time per worktree and per ticket** — protocol runs share the working tree, and the ticket's work files. Finish (or kill) the current protocol run before launching or resuming another. Plain messages (answers, questions) can be sent at any time.
79
+ Before launching, establish that the `background` tool is available and that this parent stays alive after its acknowledgement. A one-shot print/JSON process is not a persistent assistant. Missing capability is an installation problem: explain that the parent needs `pi install npm:@alignfirst/pi-background`. The AlignDev skill alone supplies no executable tools. Do not substitute a blocking ordinary bash call, shell `&`, `nohup`, or a detach wrapper, or promise a wake without the facility.
78
80
 
79
- ## Background runs and reporting
81
+ Retain these distinct values for each run:
80
82
 
81
- Once the run is started, end the turn telling the user, in their language, that the agent is working. Do not poll the run. A run is pending until you report its outcome.
83
+ - The original absolute worktree and this parent conversation's identity.
84
+ - The returned background job handle (`job.id`), which authorizes job status and cancellation.
85
+ - A fresh unique per-run `--meta` key, never reused for a successor or resume.
86
+ - The exact AlignDev session-file path once resolved, including a companion location when applicable.
87
+ - The child conversation ID (`sessionId`) for resume. It is neither a job handle nor a run-file path.
82
88
 
83
- - When your harness wakes the session as the command exits (Claude Code does), follow "After a run completes" on that wake.
84
- - Otherwise (Codex has no such wake today), the report waits for the user's next message. At the start of each later user turn, before anything else, check every pending run with `{{ALIGNDEV}} code status <session-file>`, and report the ones that finished.
89
+ Prepare the literal delegated prompt in a UTF-8 file, then launch the ordinary quoted shell command through `background` with `action: "start"` and `cwd`. Supply `--quiet --meta <unique-run-key>` yourself; the extension never parses or appends CLI options. This example assumes `/tmp/aligndev-request.txt` already contains the request. Generate a fresh key for every actual launch; the UUID below illustrates one run:
85
90
 
86
- ## After a run completes
91
+ ```json
92
+ {"action":"start","command":"{{ALIGNDEV}} code new --message-file '/tmp/aligndev-request.txt' --quiet --meta 'a20bc7c1-c056-4d07-8cc2-90fe491a6df6'","cwd":"/srv/projects/example","label":"coding run"}
93
+ ```
94
+
95
+ For resume, use `{{ALIGNDEV}} code resume <sessionId> --message-file <path> --quiet --meta <fresh-run-key>` from the original worktree. A Pi child must resume from its recorded directory. Use safe shell quoting for paths and options; never interpolate raw user text into a command. A quoted heredoc with `--message-file -` is another literal-input route.
96
+
97
+ Start returns after OS spawn acknowledgement. Retain its handle, key and cwd immediately; **do not wait for the `Session file:` control line**. End the launch turn with an acknowledgement in the user's language, then call no tool and do not poll while waiting. Natural completion requests an idle turn or a follow-up after busy work. A completion notice is only a wake hint.
98
+
99
+ On a notice:
100
+
101
+ 1. Query `background` with `{"action":"status","id":"<returned-job-id>"}` first. This event-triggered ownership check is not a waiting or polling loop. Disregard an inactive origin or an unknown/retired/cleared handle: it can be a stale native notice after clear, navigation or reload and authorizes no workflow action. A still-running job authorizes no completion report.
102
+ 2. For a current-owner terminal job, run `{{ALIGNDEV}} code status <exact-file> --result` from its original worktree. If the path is not yet known, use `{{ALIGNDEV}} code status --meta <unique-run-key> --result` there. Resolve the returned `sessionFile:` relative to that worktree when necessary, retain its exact path, and use that path thereafter. Never fall back to the newest workspace or ticket run when identity is unknown. A launch can fail before creating a run file; report that failure rather than choosing another run.
103
+ 3. Read the authoritative status, `exitReason`, child `sessionId` and final Result from this response. `--result` excludes the transcript; the CLI imposes no numeric byte cap on final result text. Background output contains only quiet control/diagnostic output. Inspect it with `action: "output"`, or inspect the durable transcript, only for a specific diagnostic need.
104
+ 4. Continue authorized verification and dependent work, or ask genuine user questions and report authentication failures or blockers. One child turn does not complete the whole request. Record which outcome you handled so a repeated notice cannot duplicate reporting or launch successor work twice. Never rerun coding merely to retry reporting.
105
+
106
+ Cancel through `background` with `{"action":"stop","id":"<returned-job-id>"}`. It gives attached work a five-second graceful window before escalation, allowing the CLI to seal its durable file. Preserve session files; `clear` removes only a terminal generic job record and its retained output.
87
107
 
88
- Run `{{ALIGNDEV}} code status <session-file>`. This reconciles a stale `running` record before reporting its status. Then read the session file and report the outcome to the user in this conversation. If the run failed, say so plainly and propose the next step; don't silently retry.
108
+ **Host limits:** standalone manual compaction or cancelled/failed navigation can delay a notice until another ordinary turn. Interruption or native queue clearing can lose automatic continuation. Already-submitted notices can appear after navigation or reload; validate ownership as above. Delivery is not exactly once. Normal shutdown, session replacement, successful tree navigation and `/reload` cancel owned work; crash recovery is not promised.
89
109
 
90
- An `exitReason` of `auth_required` in the frontmatter (`{{ALIGNDEV}} code` also exits `2`) means the coding agent is not authenticated on this machine. Tell the user to authenticate with {{AUTH_COMMAND}}, and do not retry.
110
+ Pi uses ordinary OS permissions and saved project trust, not an implied sandbox. `profile.skipPermissions` does not elevate Pi or force project approval.
91
111
 
92
- Don't reconstruct what happened: no re-running the agent, no `git` archaeology to double-check its account — the session file is authoritative for that. Verifying the result is different: run the verification your operating instructions prescribe before reporting. A failing check is new work, in a new agent run.
112
+ ### Claude Code parent
93
113
 
94
- Keep session files in place; they are the durable audit trail.
114
+ Coding runs can be long (several hours is fine), and a foreground command is subject to your tool timeout (10 minutes in Claude Code). Use your own background-execution facility with no time limit. 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.
115
+
116
+ ### Codex parent
117
+
118
+ Use your established background-execution facility with no time limit and request escalated permissions for `{{ALIGNDEV}} code`. Retain the initial `Session file: <path>` control line. End the launch turn on its acknowledgement without polling. Where no completion bridge is configured, the report waits for the user's next message. At the start of each later user turn, before anything else, check every pending run with `{{ALIGNDEV}} code status <session-file>`, and report the ones that finished. This fallback does not assert that Codex lacks native queue capability.
119
+
120
+ Neither parent detaches with `&` or a wrapper. A run is pending until its outcome is handled.
121
+
122
+ ## After a run completes
123
+
124
+ **Pi parent:** use the ownership and result-only procedure above. **Claude Code or Codex parent:** run `{{ALIGNDEV}} code status <session-file>` to reconcile stale status, then read the session file and report in this conversation.
125
+
126
+ An `exitReason` of `auth_required` (`{{ALIGNDEV}} code new/resume` exits `2`) means the selected child is not authenticated on this machine. Tell the user to authenticate with {{AUTH_COMMAND}}, and do not retry. Other launch/run failures exit `1`; success exits `0`. A successful `status` query exits `0` even for a failed run: read its `status` and `exitReason`.
127
+
128
+ Don't reconstruct what happened: no re-running the agent, no `git` archaeology to double-check its account — the session file is authoritative for that. Run the verification your operating instructions prescribe. A failing check is new work, in a new agent run; do not silently retry. Keep session files as the durable audit trail.
95
129
  {{/codingAgent}}
96
130
 
97
131
  ## CLI reference
@@ -101,31 +135,73 @@ Keep session files in place; they are the durable audit trail.
101
135
  {{ALIGNDEV}} code new --catchup --ticket <id> [--protocol <protocol>] [--message-file <path|->]
102
136
  {{ALIGNDEV}} code new --message "..."
103
137
  {{ALIGNDEV}} code resume <sessionId> [--protocol <protocol>] [--message "..."]
138
+ {{#openclaw}}
104
139
  {{ALIGNDEV}} code status (<session-file> | --ticket <id> | --no-ticket)
105
- {{ALIGNDEV}} code quota
140
+ {{/openclaw}}
141
+ {{#codingAgent}}
142
+ {{ALIGNDEV}} code new --message-file <path> --quiet --meta <unique-run-key>
143
+ {{ALIGNDEV}} code resume <sessionId> --message-file <path> --quiet --meta <unique-run-key>
144
+ {{ALIGNDEV}} code status (<session-file> | --ticket <id> | --no-ticket | --meta <key>) [--result]
145
+ {{/codingAgent}}
146
+ {{ALIGNDEV}} code quota [--profile <name>]
106
147
  ```
107
148
 
108
149
  | Command | Description |
109
150
  |---------|-------------|
110
151
  | `new` | Start a new session. |
111
152
  | `resume <sessionId>` | Continue an existing session. |
153
+ {{#openclaw}}
112
154
  | `status` | Reconcile and show one run's durable status, including `contextTokens`. Give the session file, or `--ticket <id>` / `--no-ticket` to select the newest run of that scope. Does not start the agent. |
113
- | `quota` | Show the selected coding agent's account limits and reset times. Takes no option. |
155
+ | `quota` | Show the profile's native quota source and account limits. Accepts `--profile`; independent of the coding child. |
156
+ {{/openclaw}}
157
+ {{#codingAgent}}
158
+ | `status` | Reconcile and show one run's durable status, including `contextTokens`. Select exactly one file, `--ticket <id>`, `--no-ticket`, or `--meta <key>`; scope/key selectors choose their newest matching run. Does not start the agent. |
159
+ | `quota` | Show the profile's native quota source and account limits. Accepts `--profile`; independent of the coding child. |
160
+ {{/codingAgent}}
114
161
 
115
162
  | Option | Description |
116
163
  |--------|-------------|
164
+ | `--profile <name>` | Select a complete named profile for new/resume/quota or agent-specific help; also accepted by `guide code`. Rejected on status. |
117
165
  | `--protocol <p>` | One of `spec`, `plan`, `aad`, `description`, `review`, `merge`. Optional. |
118
166
  | `--ticket <id>` | Ticket ID. With `status`, selects that ticket's newest run. `new --protocol` requires it, or `--no-ticket`. |
119
167
  | `--no-ticket` | With `status`, selects the newest run outside a ticket. With `new --protocol`, `{{ALIGNDEV}} code` reserves the next side ticket through `{{ALIGNFIRST}} ticket --side` and passes it to the agent. The reserved id is in the session file's path and `ticket:` frontmatter; pass it as `--ticket side-N` in later runs. |
120
168
  | `--message "..."` | Message to send, written in English. `-m` is the short form. Required for `spec`, `aad`, and when neither `--protocol` nor `--catchup` is given. A message file also satisfies this requirement. |
121
169
  | `--message-file <path>` | Read a UTF-8 message file; `-` reads stdin. Mutually exclusive with `--message`. |
122
170
  | `--catchup` | Load the ticket history before the protocol and message. `new` only, requires a ticket. Alone, it returns a short synthesis. |
123
- | `--model <model>` | One of {{MODELS}}. A new session defaults to {{DEFAULT_MODEL}}; a resume keeps the session's model. Prefer the default (omit the flag). |
171
+ | `--model <model>` | {{MODEL_POLICY}}. A new session defaults to {{DEFAULT_MODEL}}; a resume keeps the session's model. Prefer the default (omit the flag). |
172
+ {{#openclaw}}
124
173
  | `--meta "..."` | Opaque handoff string stored verbatim in the session file's `meta:` frontmatter. `{{ALIGNDEV}} code` never reads it — it's for you to stash context the run's later reader needs (e.g. where to report the outcome). |
174
+ {{/openclaw}}
175
+ {{#codingAgent}}
176
+ | `--meta <key>` | On `new/resume`, store an opaque handoff key verbatim. On `status`, select the newest run with that exact key anywhere in the active session tree. Use a unique key per run for exact asynchronous lookup. |
177
+ | `--quiet` | `new/resume` only. Suppress live transcript stdout, preserving the durable transcript, initial `Session file:` line, new `Session ID:`, and failure diagnostics. |
178
+ | `--result` | `status` only. Append a terminal run's final Result when present, without transcript output. Running runs show metadata only. No numeric final-text byte cap. |
179
+ {{/codingAgent}}
180
+
181
+ {{#openclaw}}
182
+ The current coding agent is `{{AGENT}}`, profile `{{PROFILE}}`. The profile's nonempty `models` replaces its displayed allowlist. Codex aliases `astra`, `sol`, `terra`, and `luna` resolve to the newest bundled matching slug only when selected; a configured full slug passes through unchanged.
183
+
184
+ `{{ALIGNDEV}} code status` checks that a `running` process still owns its recorded pid. A dead run is sealed as `status: failed`, `exitReason: terminated` before the command reports it. `{{ALIGNDEV}} code quota` works without a `.plans` directory and does not start a coding session. Its output belongs to the selected native quota CLI's account; account pairing with the coding child is not verified.
185
+ {{/openclaw}}
186
+ {{#codingAgent}}
187
+ The current coding agent is `{{AGENT}}`, profile `{{PROFILE}}`. A nonempty profile `models` list replaces its accepted model list. Pi has no finite allowlist by default: native selectors pass through unchanged, preferably `provider/model`, with optional thinking suffix. For a Pi child without `--model`, a new run uses profile `defaultModel`, else Pi's own default; a resume retains and validates its recorded model. Codex aliases `astra`, `sol`, `terra`, and `luna` resolve to the newest bundled matching slug only when selected; a configured full slug passes through unchanged.
188
+
189
+ `{{ALIGNDEV}} code status` checks that a `running` process still owns its recorded pid. A dead run is sealed as `status: failed`, `exitReason: terminated` before the command reports it. `{{ALIGNDEV}} code quota` needs no `.plans` and starts no session. Its output belongs to the selected native quota CLI's account; account pairing with the coding child is not verified.
190
+ {{/codingAgent}}
191
+
192
+ ### Profiles and resume
193
+
194
+ Effective profile: `{{PROFILE}}`; agent: `{{AGENT}}`; native configuration: `{{NATIVE_CONFIG}}`. Environment values are omitted. Login must use the same effective environment as the child: apply profile `unset/env/configDir`, including HOME, PATH and credential routing, from the same working directory. A bare login in another shell may use a different account.
195
+
196
+ New-session, help, guide and quota selection: explicit `--profile` → project's registry selection → global `code.profile` → detected-agent `code.defaultProfiles` → detected built-in defaults. Resume inserts the latest run's recorded named profile before the global default. A missing selected profile is an error; profiles never merge. Help, guide and quota use the actual cwd and require no `.plans`.
125
197
 
126
- The current coding agent is `{{AGENT}}`. `code.models` in the aligndev settings replaces its displayed allowlist. Codex aliases `astra`, `sol`, `terra`, and `luna` resolve to the newest bundled matching slug only when selected; a configured full slug passes through unchanged.
198
+ Profiles select native configuration/authentication through `configDir` or the corresponding effective environment variable: `CLAUDE_CONFIG_DIR`, `CODEX_HOME`, or `PI_CODING_AGENT_DIR`. `~/` uses the configured home; relative paths use the settings directory. Authenticate in this selected native configuration, not a different account. `env` values are literal non-secret configuration; `unset` removes inherited variables. Credentials remain in native stores or provisioned process environments. Parent identities are stripped after these overrides. Environment values are never recorded in session metadata.
127
199
 
128
- `{{ALIGNDEV}} code status` checks that a `running` process still owns its recorded pid. A dead run is sealed as `status: failed`, `exitReason: terminated` before the command reports it. `{{ALIGNDEV}} code quota` works without a `.plans` directory and does not start a coding session. Its output follows the selected agent's available account limits.
200
+ Select a user-facing model name, validate it against the accepted names, expand one `modelAliases` mapping, then apply native handling. Without a nonempty `models` override, Claude/Codex add alias names to their native default names; Pi accepts any nonblank selector. Pi exact provider-qualified IDs pin models; fuzzy selectors and thinking suffixes pass through to Pi. Use separate Pi profiles for Codex-backed and Anthropic-backed choices; AlignDev never guesses providers or accounts. Omitted quota uses a native Claude/Codex profile's environment; Pi needs explicit `quota.source: "codex"` or `"claude"`. `"none"` disables quota. Explicit quota starts from the caller environment, applies only quota `unset/env/configDir` and strips parent identities. It never copies coding-profile overrides or Pi credentials. Set quota `configDir` for the intended native account; omission deliberately keeps inherited/default storage. Quota paths follow profile expansion rules. Do not infer account pairing from model selection or retry against a different account after failure.
201
+
202
+ Resume keeps the latest user-facing model unless `--model` replaces it; new-session defaults are ignored. A retained name disallowed by the selected profile requires an explicit accepted replacement. Null keeps the native conversation model. Retained aliases use current mappings, which can change their native targets. Resume requires the same agent and native identity; Pi also requires its recorded real directory. An unavailable conversation fails under the selected account with no fallback, copying or replacement conversation. Run metadata records the effective profile (or null), agent, model name, native ID and cwd. Historical records stay readable; status does not validate launch profiles.
203
+
204
+ Direct launch keys under `code` are retired. Move them into `code.profiles.<name>` and select the name with `code.profile`; no automatic conversion occurs.
129
205
 
130
206
  `contextTokens` is what the run left in the agent's context window, measured from its last model response. It describes the conversation, so resuming a session carries the figure forward and each run reports a larger one.
131
207
 
@@ -133,7 +209,12 @@ The current coding agent is `{{AGENT}}`. `code.models` in the aligndev settings
133
209
 
134
210
  {{PERMISSIONS}}.
135
211
 
212
+ {{#openclaw}}
136
213
  For `new` runs, the `Session ID:` is printed to stdout and written with `agent: {{AGENT}}` in the session file frontmatter. Save it to resume the conversation later. Resume requires the same selected agent; agentless legacy sessions require a new session.
214
+ {{/openclaw}}
215
+ {{#codingAgent}}
216
+ For `new` runs, the child `Session ID:` is printed to stdout and recorded as `sessionId` with `agent: {{AGENT}}` in the durable session file. An asynchronous Pi parent retains it from authoritative `status --result` retrieval, without waiting at launch. Save it for resume, which requires the same selected child; agentless legacy sessions require a new session.
217
+ {{/codingAgent}}
137
218
 
138
219
  **No protocol or catchup:** the message is sent as-is (no AlignFirst command). Use it to answer the agent's questions in an existing session, execute a plan in a new session, or ask a question:
139
220
 
@@ -62,7 +62,12 @@ The message carries the complete question, however detailed, the selected branch
62
62
  The message carries the complete question, however detailed, the selected branch, and an explicit constraint to investigate and answer without implementing changes. Use the delegation guide's background launch and completion procedure.
63
63
  {{/codingAgent}}
64
64
 
65
+ {{#openclaw}}
65
66
  Retain the printed session id. Later turns of the same topic resume that session, so the discussion accumulates in one place.
67
+ {{/openclaw}}
68
+ {{#codingAgent}}
69
+ Retain the child session id, from authoritative completion retrieval for an asynchronous Pi launch. Follow the delegation guide instead of waiting for it at launch. Later turns of the same topic resume that session, so the discussion accumulates in one place.
70
+ {{/codingAgent}}
66
71
 
67
72
  ## Step 4 — Relay
68
73
 
@@ -16,13 +16,18 @@ The choice rests on the metadata alone. The playbook tells you what to do. No an
16
16
  You are the AlignFirst assistant in a coding-agent session, and the user talks to you in this conversation. Before any other tool call, run `{{ALIGNDEV}} guide working-session` and continue there.
17
17
  {{/codingAgent}}
18
18
 
19
+ {{#openclaw}}
19
20
  **The agent** — the coding agent (Claude Code or Codex) you launch in a project with `{{ALIGNDEV}} code`. It reads and changes the codebase; you guide it.
21
+ {{/openclaw}}
22
+ {{#codingAgent}}
23
+ **The agent** — the selected child (Claude Code, Codex or Pi) you launch in a project with `{{ALIGNDEV}} code`. It reads and changes the codebase; you guide it.
24
+ {{/codingAgent}}
20
25
 
21
26
  {{#openclaw}}
22
27
  You run inside OpenClaw, but you are the assistant, never an agent. "The agent" always means the coding agent you launch.
23
28
  {{/openclaw}}
24
29
  {{#codingAgent}}
25
- You run inside Claude Code or Codex, but you are the assistant, never an agent. "The agent" always means the coding agent you launch.
30
+ You run inside Claude Code, Codex or Pi as the parent assistant. "The agent" always means the selected child, independently of your host.
26
31
 
27
32
  Your own tools could edit the code, but you delegate: you never implement, investigate, or modify the codebase yourself.
28
33
  {{/codingAgent}}
@@ -126,7 +131,7 @@ Coding runs are long. Run `{{ALIGNDEV}} code` through `exec` in the background,
126
131
  For a `target` parameter, keep the whole `chat_id`, prefix included (e.g. `"channel:#####"`). Never reconstruct, paraphrase, or guess a `chat_id`. A `threadId` parameter is different: pass only the bare thread ID from the conversation metadata or tool result, never a `thread:<channel>/<id>` target.
127
132
  {{/openclaw}}
128
133
  {{#codingAgent}}
129
- To delegate, run `{{ALIGNDEV}} code` from the workplace, or from PROJECT_PATH for operational work. Before your first `{{ALIGNDEV}} code` run of a session, run `{{ALIGNDEV}} guide code` and follow it — it is the delegation manual, and it stays the last guide you read. Delegation always goes through `{{ALIGNDEV}} code` — never your own subagents or tasks, and never an AlignFirst protocol skill run by yourself.
134
+ To delegate, run `{{ALIGNDEV}} code` from the workplace, or from PROJECT_PATH for operational work. Before your first `{{ALIGNDEV}} code` run of a session, run `{{ALIGNDEV}} guide code` and follow it — it is the delegation manual, and it stays the last guide you read. Delegation always goes through `{{ALIGNDEV}} code` — never your own subagents, `subagent` tool or tasks, and never an AlignFirst protocol skill run by yourself. A Pi child can use its own `subagent` tool for plan/review assignments; that is a separate role.
130
135
 
131
136
  Coding runs are long. Run `{{ALIGNDEV}} code` in the background, as the delegation guide describes.
132
137
  {{/codingAgent}}
@@ -147,7 +152,12 @@ Keep scratch artifacts out of tracked git directories.
147
152
 
148
153
  ## Vocabulary
149
154
 
155
+ {{#openclaw}}
150
156
  - **the agent** — the coding agent (Claude Code or Codex) you launch in a project with `{{ALIGNDEV}} code`. It reads and changes the codebase; you guide it. Call it _the agent_ with the user too.
157
+ {{/openclaw}}
158
+ {{#codingAgent}}
159
+ - **the agent** — the selected child (Claude Code, Codex or Pi) launched with `{{ALIGNDEV}} code`. Call it _the agent_ with the user too.
160
+ {{/codingAgent}}
151
161
  - **ticket** — an issue or card.
152
162
  - **project workspace** — in a project, it means branch + worktree + isolated dev server. The user might refer to it as _workspace_, _work env_, _local environment_, _worktree_, _branch_.
153
163
  - **dev server** (or *your server*) — the local instance of the project running in the worktree, with hot reload, etc. The user might refer to it as _server_, _local server_, or even the _env URL_.
@@ -227,7 +227,7 @@ The workspace is ready. Announce what you're about to do in one line and do it.
227
227
  When the work is an `{{ALIGNDEV}} code` run, launch it as the delegation guide describes: background `exec` with `timeoutSeconds: 0`, then end the turn on the acknowledgement. Call nothing on the `{{ALIGNDEV}} code` session before the chained turn wakes you, whatever the `exec` acknowledgement suggests.
228
228
  {{/openclaw}}
229
229
  {{#codingAgent}}
230
- When the work is an `{{ALIGNDEV}} code` run, launch it in the background as the delegation guide describes, then end the turn on the acknowledgement.
230
+ When the work is an `{{ALIGNDEV}} code` run, follow the delegation guide's parent-host route, then end the launch turn on the acknowledgement. A Pi parent first requires the available `background` tool and a persistent session; if either is missing, explain the setup problem instead of launching or promising completion.
231
231
  {{/codingAgent}}
232
232
 
233
233
  Ask only when you genuinely can't proceed — the request is ambiguous enough that two readings lead to different work, or it turns on a product decision that isn't yours to make.
@@ -315,7 +315,12 @@ Feel free to do the rest yourself (except coding) when it's more practical.
315
315
 
316
316
  ### A background run moves the report
317
317
 
318
+ {{#openclaw}}
318
319
  Launching a background run ends the turn: the closing message is the launch acknowledgement, and the report moves to the run's completion turn. Each further run launched from that turn moves the report again.
320
+ {{/openclaw}}
321
+ {{#codingAgent}}
322
+ Launching a background run ends the turn on its acknowledgement. For a Pi parent, first verify the `background` capability and a persistent parent, as the delegation guide requires; without them, explain installation instead of promising a later report. On a Pi notice, validate the job handle and retrieve the exact run with `status --result`. Continue authorized work or report genuine questions/blockers. A child's completed turn is not completion of the whole request. Further runs use the same launch procedure; repeated notices must not duplicate successor work. Claude Code and Codex retain their host-specific completion/fallback routes in the delegation guide.
323
+ {{/codingAgent}}
319
324
 
320
325
  ### The plan is not a gate
321
326
 
@@ -471,7 +476,12 @@ Either way, the report states the error and your decision.
471
476
 
472
477
  #### Dev-server log review
473
478
 
479
+ {{#openclaw}}
474
480
  After using a dev-server, have a separate no-protocol agent run with the smallest available model inspect its logs: give it the log locations and ask for errors or unusual behavior. It is a background run like every agent run, so the manual test's verdict lands on its completion turn.
481
+ {{/openclaw}}
482
+ {{#codingAgent}}
483
+ After using a dev-server, have a separate no-protocol agent run inspect its logs: give it the log locations and ask for errors or unusual behavior. Choose the smallest available model from the child's ordered list; for Pi without a finite ordered allowlist, use the configured/default model instead. Launch and retrieve its result through the delegation guide's parent-host route before reporting the manual test's verdict.
484
+ {{/codingAgent}}
475
485
 
476
486
  Clean logs are required for the manual test to pass.
477
487