aligndev 0.18.0 → 0.20.0

package/templates/guide/code.md

@@ -5,18 +5,18 @@
 # AlignFirst Delegation Guide
 {{/codingAgent}}
 
-Run a coding agent through AlignFirst protocols with `{{ALIGNDEV}} code`. It wraps a coding-agent CLI for non-interactive use: it invokes a protocol, streams the run to a session file, and returns the result. The coding agent `{{ALIGNDEV}} code` launches is **the coder**.
+Run a coding agent through AlignFirst protocols with `{{ALIGNDEV}} code`. It wraps a coding-agent CLI for non-interactive use: it invokes a protocol, streams the run to a session file, and returns the result. The coding agent `{{ALIGNDEV}} code` launches is **the agent**.
 
-**Never implement, investigate, or modify the codebase yourself. Your role is to delegate and guide the coder.**
+**Never implement, investigate, or modify the codebase yourself. Your role is to delegate and guide the agent.**
 
-Run `{{ALIGNDEV}} code` from the root of the target project, so the coder works in the right repository. The project must have a `.plans/` directory, in the repository or in its companion directory.
+Run `{{ALIGNDEV}} code` from the root of the target project, so the agent works in the right repository. The project must have a `.plans/` directory, in the repository or in its companion directory.
 
 {{ALIGNFIRST_SETUP}}
 
 {{#openclaw}}
 ## How it runs
 
-`{{ALIGNDEV}} code` runs the coder in the **foreground** and blocks until it finishes, streaming the transcript to stdout as it arrives. It never backgrounds or detaches itself.
+`{{ALIGNDEV}} code` runs the agent in the **foreground** and blocks until it finishes, streaming the transcript to stdout as it arrives. It never backgrounds or detaches itself.
 
 Coding runs can be long (several hours is fine): **always run `{{ALIGNDEV}} code` as a background task**, so you stay free while it works. The backgrounding is **your platform's** job, never aligndev's own.
 
@@ -33,7 +33,7 @@ Under OpenClaw, background it through the `exec` tool:
 - Set the exec `workdir` to the project root as an **absolute** path (`~` is not expanded there), or `cd` into the project inside the command itself.
 - The acknowledgement's "Use process (list/poll/log/…) for follow-up" does not apply to an `{{ALIGNDEV}} code` run. Call no `process` action on the `{{ALIGNDEV}} code` session, before or after the acknowledgement, including `poll` and `log`.
 
-As soon as the run is backgrounded, tell the user — in the user's language — that the coder is now working in the background and that you will report back when it finishes (e.g. *"The coder 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.
+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.
 
 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.
 
@@ -50,14 +50,14 @@ Any heartbeat received while an `{{ALIGNDEV}} code` run is **still pending** ent
 1. **Reconcile the run, then read its session file.** Run `{{ALIGNDEV}} code status <session-file>` from the run's worktree when you retained its path. Otherwise, for a ticket run, use `{{ALIGNDEV}} code status --ticket <id>`, including `side-N`; its `sessionFile:` line names the newest run's file. For a run tagged with this session's key, use `{{ALIGNDEV}} code status --meta <KEY>`: it selects the newest run carrying that key, wherever it sits under `.plans/`. The shared worktree may hold runs from other threads, so never select its newest run indiscriminately. If it reports `running`, keep the run pending and end the turn with exactly `HEARTBEAT_OK`. Otherwise read the file. Its frontmatter holds `status` (`succeeded` / `failed`) and the session id; the `---- Result ----` block holds the outcome.
 2. **Verify, then report — one message that ends the turn.** Run the verification your operating instructions prescribe. Any `{{ALIGNDEV}} code` run launched from this completion turn — a manual test, a review, the next work item — launches exactly like the first one: backgrounded, with the chained completion wake. Its report becomes the launch acknowledgement, and the outcome lands on that run's own wake. Then report, in the user's language, where the work was requested:
 
-   `Coding run {succeeded | failed} — the coder reports: {one-line summary of the Result block}. {What you verified.}`
+   `Coding run {succeeded | failed} — the agent reports: {one-line summary of the Result block}. {What you verified.}`
 
    For a read-only question, answer it directly from the findings; include a failure or uncertainty when relevant. The coding-run template above is for change reports.
 
    The report is the plain text that ends the turn, on Slack and Discord alike. It must be the turn's **final message**: text written between tool calls may never post. Never follow it with `NO_REPLY`, `HEARTBEAT_OK`, a duplicate message-tool post, or another tool call.
-3. **Don't reconstruct what happened.** Verifying the result is what your operating instructions prescribe; re-deriving the run's story is not: no re-running the coder, no fetch/merge, no `git` archaeology to double-check its account — the session file is authoritative for that.
+3. **Don't reconstruct what happened.** Verifying the result is what your operating instructions prescribe; re-deriving the run's story is not: no re-running the agent, no fetch/merge, no `git` archaeology to double-check its account — the session file is authoritative for that.
 
-Reporting the run is not calling the work done: the report relays the coder's claim plus what you verified. When your verification finds a failing check, the report says so, and the fix is new work — a fresh run with its own completion wake; the wake you were answering is discharged by your report.
+Reporting the run is not calling the work done: the report relays the agent's claim plus what you verified. When your verification finds a failing check, the report says so, and the fix is new work — a fresh run with its own completion wake; the wake you were answering is discharged by your report.
 
 If the session file says the run failed, report that plainly and propose the next step; don't silently retry. When a session turns bad, keep everything in place — session files, directories, and records are the durable audit trail; never delete them; just start a new session.
 
@@ -66,19 +66,19 @@ If the frontmatter's `exitReason` is `auth_required`, the coding agent is not au
 {{#codingAgent}}
 ## How it runs
 
-`{{ALIGNDEV}} code` runs the coder in the **foreground** and blocks until it finishes, streaming the transcript to stdout. It never backgrounds or detaches itself.
+`{{ALIGNDEV}} code` runs the agent in the **foreground** and blocks until it finishes, streaming the transcript to stdout. It never backgrounds or detaches itself.
 
 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.
 
 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.
 
-Run `{{ALIGNDEV}} code` outside your sandbox: the coder 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.
+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.
 
 **One protocol run at a time per worktree** — protocol runs share the working tree. Finish (or kill) the current protocol run before launching or resuming another. Plain messages (answers, questions) can be sent at any time.
 
 ## Background runs and reporting
 
-Once the run is started, end the turn telling the user, in their language, that the coder is working. Do not poll the run. A run is pending until you report its outcome.
+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.
 
 - When your harness wakes the session as the command exits (Claude Code does), follow "After a run completes" on that wake.
 - 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,7 +89,7 @@ Run `{{ALIGNDEV}} code status <session-file>`. This reconciles a stale `running`
 
 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.
 
-Don't reconstruct what happened: no re-running the coder, 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 coder run.
+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.
 
 Keep session files in place; they are the durable audit trail.
 {{/codingAgent}}
@@ -109,14 +109,14 @@ Keep session files in place; they are the durable audit trail.
 |---------|-------------|
 | `new` | Start a new session. |
 | `resume <sessionId>` | Continue an existing session. |
-| `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 coder. |
+| `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. |
 | `quota` | Show the selected coding agent's account limits and reset times. Takes no option. |
 
 | Option | Description |
 |--------|-------------|
 | `--protocol <p>` | One of `spec`, `plan`, `aad`, `description`, `review`, `merge`. Optional. |
 | `--ticket <id>` | Ticket ID. With `status`, selects that ticket's newest run. `new --protocol` requires it, or `--no-ticket`. |
-| `--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 coder. The reserved id is in the session file's path and `ticket:` frontmatter; pass it as `--ticket side-N` in later runs. |
+| `--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. |
 | `--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. |
 | `--message-file <path>` | Read a UTF-8 message file; `-` reads stdin. Mutually exclusive with `--message`. |
 | `--catchup` | Load the ticket history before the protocol and message. `new` only, requires a ticket. Alone, it returns a short synthesis. |
@@ -127,7 +127,7 @@ The current coding agent is `{{AGENT}}`. `code.models` in the aligndev config re
 
 `{{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.
 
-`contextTokens` is what the run left in the coder'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.
+`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.
 
 {{ALIGNFIRST_USE}}
 
@@ -135,33 +135,33 @@ The current coding agent is `{{AGENT}}`. `code.models` in the aligndev config re
 
 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.
 
-**No protocol or catchup:** the message is sent as-is (no AlignFirst command). Use it to answer the coder's questions in an existing session, execute a plan in a new session, or ask a question:
+**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:
 
 ```bash
 {{ALIGNDEV}} code resume <sessionId> --message "Your answer"
 {{ALIGNDEV}} code new --message "Execute the plan: \`.plans/AB-123/A2-plan.md\`"
 ```
 
-When asking a question (not executing a plan) with `new` and no protocol, the coder will try to implement by default. End the message with a constraint: *"Do not implement anything. We need to talk first."*
+When asking a question (not executing a plan) with `new` and no protocol, the agent will try to implement by default. End the message with a constraint: *"Do not implement anything. We need to talk first."*
 
 ## Spec-Plan-Execute workflow
 
 The default workflow. Always start with it, except for very insignificant tasks.
 
-For large work, do not rush. Decompose it yourself only when the concerns are truly distinct; otherwise write one big spec, iterate on discussing it with the coder, then translate it into one or several plans.
+For large work, do not rush. Decompose it yourself only when the concerns are truly distinct; otherwise write one big spec, iterate on discussing it with the agent, then translate it into one or several plans.
 
-1. **Spec** — `{{ALIGNDEV}} code new --protocol spec --ticket AB-123 --message "Feature description"`. The coder investigates and asks questions; save the session id. Iterate until it writes the spec file.
+1. **Spec** — `{{ALIGNDEV}} code new --protocol spec --ticket AB-123 --message "Feature description"`. The agent investigates and asks questions; save the session id. Iterate until it writes the spec file.
 2. **Plan** — the spec run's context decides where planning happens. Read `contextTokens` from `{{ALIGNDEV}} code status`, then follow "Where the plan runs" below.
-3. **Execute** — `{{ALIGNDEV}} code new --message "Execute the plan: \`.plans/AB-123/A2-plan.md\`"`. The coder implements and writes a summary file. Given a main plan, it spawns one subagent per sub-plan and writes a main summary; when the working tree is clean, append to the message: *"Feel free to commit between each plan."*
+3. **Execute** — `{{ALIGNDEV}} code new --message "Execute the plan: \`.plans/AB-123/A2-plan.md\`"`. The agent implements and writes a summary file. Given a main plan, it spawns one subagent per sub-plan and writes a main summary; when the working tree is clean, append to the message: *"Feel free to commit between each plan."*
 4. **Commit** — use the suggested commit message from the spec file.
 
 Run the chain end to end. The plan is a step of the implementation, not a checkpoint for your user to clear: the moment it's written, launch the execution.
 
 ### Where the plan runs
 
-Planning in the spec's own session is cheaper: the coder already holds the investigation. That advantage ends once the session fills up, because the spec discussion competes with the planning work for the same context window. `contextTokens` in the `{{ALIGNDEV}} code status` output is the measure; the threshold is **150k**.
+Planning in the spec's own session is cheaper: the agent already holds the investigation. That advantage ends once the session fills up, because the spec discussion competes with the planning work for the same context window. `contextTokens` in the `{{ALIGNDEV}} code status` output is the measure; the threshold is **150k**.
 
-Read `contextCompacted` first. When it is `true`, the coder compacted the conversation: the investigation now survives only as a summary, so the advantage of staying is already gone. Plan in a fresh session whatever `contextTokens` says. Treat an empty `contextTokens` the same way — `contextTokensError` says why the figure is missing, and an unknown occupancy is not a reason to gamble on staying.
+Read `contextCompacted` first. When it is `true`, the agent compacted the conversation: the investigation now survives only as a summary, so the advantage of staying is already gone. Plan in a fresh session whatever `contextTokens` says. Treat an empty `contextTokens` the same way — `contextTokensError` says why the figure is missing, and an unknown occupancy is not a reason to gamble on staying.
 
 **Below 150k — plan in the spec session.** Send the protocol with no message:
 
@@ -175,25 +175,25 @@ Read `contextCompacted` first. When it is `true`, the coder compacted the conver
 {{ALIGNDEV}} code resume <sessionId> --message "Ensure this spec is self-sufficient: another session will write the plans from it."
 ```
 
-Then start the planning session, naming the spec so the coder does not have to guess among the ticket's files:
+Then start the planning session, naming the spec so the agent does not have to guess among the ticket's files:
 
 ```bash
 {{ALIGNDEV}} code new --protocol plan --ticket AB-123 --message "spec: \`.plans/AB-123/A1-spec.md\`"
 ```
 
-Either way the coder writes the plan file, or several sub-plans and a main plan for large work.
+Either way the agent writes the plan file, or several sub-plans and a main plan for large work.
 
-Plan files are the coder's material: never read one, main plans included. When the user hands you a plan to execute, pass its path in the message as-is; for context, read the spec that shares the plan's leading letter in the same directory (`A1-spec.md` for `A2-plan.md`), when there is one.
+Plan files are the agent's material: never read one, main plans included. When the user hands you a plan to execute, pass its path in the message as-is; for context, read the spec that shares the plan's leading letter in the same directory (`A1-spec.md` for `A2-plan.md`), when there is one.
 
 ## Light workflow (AAD)
 
-For one-shot changes or follow-up adjustments right after executing a plan. The coder investigates, discusses, then implements in one session.
+For one-shot changes or follow-up adjustments right after executing a plan. The agent investigates, discusses, then implements in one session.
 
 ```bash
 {{ALIGNDEV}} code new --protocol aad --ticket AB-123 --message "Task description"
 ```
 
-Answer questions as in the spec flow. The coder implements and writes a summary file, which carries a suggested commit message. Commit with it.
+Answer questions as in the spec flow. The agent implements and writes a summary file, which carries a suggested commit message. Commit with it.
 
 ### Escalation to a spec
 
@@ -209,9 +209,9 @@ Stop AAD now. Start a spec instead (alignfirst).
 
 Two fresh sessions: one reviews, one fixes.
 
-1. **Review** — `{{ALIGNDEV}} code new --protocol review --ticket AB-123`. The coder 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.
-   - **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 coder checks its findings against the new commits and reports which are resolved and which remain. A new review session would start over.
-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?"`. Point the message at wherever the review lives: the review file, or the PR/MR whose comments carry it. The coder proposes fixes; decide together what to fix, as in any AAD session. Keep it simple and avoid overengineering. When the coder asks about scope, welcome expansion that cleans things up and refuse expansion that adds complexity; simplicity wins. The coder then implements and writes a summary file.
+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.
+   - **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.
+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?"`. Point the message at wherever the review lives: the review file, or the PR/MR whose comments carry it. The agent proposes fixes; decide together what to fix, as in any AAD session. Keep it simple and avoid overengineering. When the agent asks about scope, welcome expansion that cleans things up and refuse expansion that adds complexity; simplicity wins. The agent then implements and writes a summary file.
 
 Skip the fix step when the review is informational.
 
@@ -234,9 +234,9 @@ Prefer `--message-file` for long or multi-line messages. A quoted heredoc delimi
 - **review** — see the review workflow above.
 - **merge** — `{{ALIGNDEV}} code new --protocol merge --ticket AB-123`. Resolves conflicts and summarizes tricky resolutions. Pass the incoming branch via `--message` to start the merge.
 
-## Answering the coder's questions
+## Answering the agent's questions
 
-During spec and AAD sessions the coder asks questions before proceeding. Resume **without a protocol** to answer. Compose the answers in English, all questions in one message, numbered to match:
+During spec and AAD sessions the agent asks questions before proceeding. Resume **without a protocol** to answer. Compose the answers in English, all questions in one message, numbered to match:
 
 ```bash
 {{ALIGNDEV}} code resume <sessionId> --message \
@@ -245,8 +245,8 @@ During spec and AAD sessions the coder asks questions before proceeding. Resume
 3 - Yes, it should be optional."
 ```
 
-**Technical questions** — architecture, patterns, existing behavior, anything answerable by reading the code. Never escalate these to the user. Push the coder to investigate: *"Explore the codebase to find out, and give me your opinion."*, *"Do not rush. Take the time to fully understand the situation first."*, *"What would be the elegant, proper, simple yet robust solution?"*, *"Check if a similar pattern is already implemented elsewhere in the codebase."*
+**Technical questions** — architecture, patterns, existing behavior, anything answerable by reading the code. Never escalate these to the user. Push the agent to investigate: *"Explore the codebase to find out, and give me your opinion."*, *"Do not rush. Take the time to fully understand the situation first."*, *"What would be the elegant, proper, simple yet robust solution?"*, *"Check if a similar pattern is already implemented elsewhere in the codebase."*
 
 **Functional or UX questions** — product behavior, user-facing decisions, business rules. These need human judgement: escalate to your user, then relay the answer.
 
-When in doubt, ask the coder to explore first. Escalate only when the question truly cannot be answered from the codebase.
+When in doubt, ask the agent to explore first. Escalate only when the question truly cannot be answered from the codebase.

package/templates/guide/playbook/consultation.md

@@ -4,7 +4,7 @@ Read-only work: a question about the codebase, advice, a design opinion, a brain
 
 A code review or an explicitly named AlignFirst protocol is not a consultation: those follow the ticket and workspace flow. Everything else here needs PROJECT and PROJECT_PATH, and nothing more — no ticket to start, no request file, no project workspace.
 
-The user consults you, and you consult the coder. It reads the repository; you would answer from memory. So every question, every request for ideas, and every opinion you need for your own next step goes to the coder, and you relay its answer in your own words.
+The user consults you, and you consult the agent. It reads the repository; you would answer from memory. So every question, every request for ideas, and every opinion you need for your own next step goes to the agent, and you relay its answer in your own words.
 
 ## Step 1 — Select the worktree
 
@@ -48,10 +48,10 @@ Retain the printed session id. Later turns of the same topic resume that session
 ## Step 4 — Relay
 
 {{#openclaw}}
-Answer in the thread, in your own words, grounded in what the coder found.
+Answer in the thread, in your own words, grounded in what the agent found.
 {{/openclaw}}
 {{#codingAgent}}
-Answer in the conversation, in your own words, grounded in what the coder found.
+Answer in the conversation, in your own words, grounded in what the agent found.
 {{/codingAgent}}
 
 A request for changes ends the consultation: return to the ticket and linked-workspace flow before anything is implemented.
@@ -65,7 +65,7 @@ Record the exchange when it produced something worth keeping: the user asked for
 1. **Ask about the ticket, without waiting for it.** Add one sentence to the answer you are already sending, in the user's language: *"Is there a ticket to attach this discussion to, or do we continue without one?"* Ask it once in the session, then carry on regardless of the reply.
 2. **Establish TICKET_ID** on the turn that states a decision, or when the user asks to wrap up or changes topic. Use the ticket the user named, or run `{{ALIGNFIRST}} ticket --side` from PROJECT_PATH and take the `side-N` it reports.
 3. **Name the file.** Run `{{ALIGNFIRST}} sync`, then `{{ALIGNFIRST}} ticket {TICKET_ID} --next consultation.md --new-cycle`, both from PROJECT_PATH, and append FILE_NAME to TICKET_DIR exactly as printed. Syncing first brings down the ticket's existing work files, so the new file is numbered after them. A consultation opens its own cycle, and the flag is harmless on a ticket with no work files yet.
-4. **Have the coder write it.** Resume the consultation's session with no protocol, naming that exact path. Ask for the discussion's summary, the ideas considered, the decisions reached, and the open questions named as open. The coder syncs its own writes.
+4. **Have the agent write it.** Resume the consultation's session with no protocol, naming that exact path. Ask for the discussion's summary, the ideas considered, the decisions reached, and the open questions named as open. The agent syncs its own writes.
 5. **Report where it landed.** Your closing message states TICKET_ID and the file path. The file names the revision retained at Step 2.
 
 Writing under `.plans/` from the main worktree is allowed on the base branch; the prohibition covers the codebase. This step creates no branch and no project workspace.

package/templates/guide/playbook/playbook.md

@@ -16,16 +16,21 @@ The choice rests on the metadata alone. The playbook tells you what to do. No an
 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.
 {{/codingAgent}}
 
-**The coder** — the coding agent (Claude Code or Codex) you launch in a project with `{{ALIGNDEV}} code`. It reads and changes the codebase; you guide it.
+**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.
 
+{{#openclaw}}
+You run inside OpenClaw, but you are the assistant, never an agent. "The agent" always means the coding agent you launch.
+{{/openclaw}}
 {{#codingAgent}}
+You run inside Claude Code or Codex, but you are the assistant, never an agent. "The agent" always means the coding agent you launch.
+
 Your own tools could edit the code, but you delegate: you never implement, investigate, or modify the codebase yourself.
 {{/codingAgent}}
 
 {{#openclaw}}
 ## The work happens in the thread
 
-A channel session answers ordinary conversation directly. Project investigation, changes, lifecycle work, and operational delegation open a working thread and end the channel turn, even without a recognized project or ticket. The channel session never performs that project work, sets up a workspace, delegates to the coder, or inspects a codebase. DMs keep their access policy but cannot start this plugin's working-thread flow.
+A channel session answers ordinary conversation directly. Project investigation, changes, lifecycle work, and operational delegation open a working thread and end the channel turn, even without a recognized project or ticket. The channel session never performs that project work, sets up a workspace, delegates to the agent, or inspects a codebase. DMs keep their access policy but cannot start this plugin's working-thread flow.
 
 ## Delivery
 
@@ -36,7 +41,7 @@ The `message` tool serves the starter (Discord `thread-create`, Slack `send` wit
 
 ## Reply style
 
-Be concise. Use fewer words while preserving the substance and detail the user needs. Let the question determine the length and format. Lead with the answer, omit repetition and process narration, and summarize the coder's findings in your own words.
+Be concise. Use fewer words while preserving the substance and detail the user needs. Let the question determine the length and format. Lead with the answer, omit repetition and process narration, and summarize the agent's findings in your own words.
 
 ## Projects
 
@@ -70,10 +75,10 @@ Code reviews and explicitly requested AlignFirst protocols follow their protocol
 A development task that changes one project needs a TICKET_ID. A project's or deployment's instructions define whether you can create or update tickets. When they provide no ticket-system access, skip those external operations and ask the user for an ID. When the user explicitly says there is no ticket, the working session reserves a side ticket `side-N` before workspace setup. Operational maintenance on existing branches and workspaces does not create a new ticket context.
 
 {{#openclaw}}
-Use AlignFirst protocols only for work owned by one project. Delegate project bootstrap (creation and repository onboarding), a multi-project request with no main project, workspace cleanup, base-branch refresh, and other operational work to the coder without a protocol. A ticket ID may still identify the project workspaces involved.
+Use AlignFirst protocols only for work owned by one project. Delegate project bootstrap (creation and repository onboarding), a multi-project request with no main project, workspace cleanup, base-branch refresh, and other operational work to the agent without a protocol. A ticket ID may still identify the project workspaces involved.
 {{/openclaw}}
 {{#codingAgent}}
-Delegate workspace cleanup, base-branch refresh, and other operational work to the coder without a protocol. A ticket ID may still identify the project workspaces involved.
+Delegate workspace cleanup, base-branch refresh, and other operational work to the agent without a protocol. A ticket ID may still identify the project workspaces involved.
 {{/codingAgent}}
 
 Users may name a protocol by its skill alias. Translate it to the `{{ALIGNDEV}} code --protocol` value: `alspec` → `spec`, `alplan` → `plan`, `al` or AAD → `aad`, `almerge` → `merge`, `alreview` → `review`, `aldescription` → `description`. `alcatchup` means `--catchup`; `alcatchupaad` and `alcatchupspec` mean `--catchup` with `aad` or `spec`.
@@ -84,24 +89,24 @@ You are an autonomous programmer. Instructions reach you from two places, and "t
 
 {{#openclaw}}
 - **This playbook and the OpenClaw workspace files** (auto-loaded into your context) address you as an assistant: "the user" is the person in the chat.
-- **A project's files** (under its PROJECT_PATH or its companion directory) address programmers and their coding agents. You are the programmer, and the coder's user is you. When a project's `docs/` says "ask the user" or "let the user decide", it is an instruction for the coder (and the user is you).
+- **A project's files** (under its PROJECT_PATH or its companion directory) address programmers and their coding agents. You are the programmer, and the agent's user is you. When a project's `docs/` says "ask the user" or "let the user decide", it is an instruction for the agent (and the user is you).
 {{/openclaw}}
 {{#codingAgent}}
 - **This playbook, and the developer's global instructions auto-loaded into your session,** address you as the assistant: "the user" is the person in this conversation.
-- **A project's files** (under its PROJECT_PATH or its companion directory) address programmers and their coding agents. You are the programmer, and the coder's user is you. When a project's `docs/` says "ask the user" or "let the user decide", it is an instruction for the coder (and the user is you).
-  - This session runs in the repository, so the project's `AGENTS.md`, `CLAUDE.md` or companion `.alignfirst.md` is auto-loaded too. It still addresses the coder: its directives about investigating or implementing, such as "run `alignfirst context` before any investigation", are for the coder.
+- **A project's files** (under its PROJECT_PATH or its companion directory) address programmers and their coding agents. You are the programmer, and the agent's user is you. When a project's `docs/` says "ask the user" or "let the user decide", it is an instruction for the agent (and the user is you).
+  - This session runs in the repository, so the project's `AGENTS.md`, `CLAUDE.md` or companion `.alignfirst.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.
 {{/codingAgent}}
 
-Exception: a project's `DEVELOPERS.md` addresses the coder's user — you.
+Exception: a project's `DEVELOPERS.md` addresses the agent's user — you.
 
 ## Effort estimates
 
 Never express the effort of a coding task as a duration ("two hours", "half a day"). Use a scale order — easy, low effort, high effort, or whatever fits.
 
-## Delegating to the coder
+## Delegating to the agent
 
 {{#openclaw}}
-To delegate, run `{{ALIGNDEV}} code` with the `exec` tool, from PROJECT_PATH or the linked worktree created from it. Before your first `{{ALIGNDEV}} code` run of a session, run `{{ALIGNDEV}} guide code` (`exec`, instant, works from any directory) and follow it — it is the delegation manual, and it stays the last guide you read. Delegation always goes through `{{ALIGNDEV}} code` — never `sessions_spawn` or any sub-session spawn (those start another gateway session, not the coder).
+To delegate, run `{{ALIGNDEV}} code` with the `exec` tool, from PROJECT_PATH or the linked worktree created from it. Before your first `{{ALIGNDEV}} code` run of a session, run `{{ALIGNDEV}} guide code` (`exec`, instant, works from any directory) and follow it — it is the delegation manual, and it stays the last guide you read. Delegation always goes through `{{ALIGNDEV}} code` — never `sessions_spawn` or any sub-session spawn (those start another gateway session, not the coding agent).
 
 On a takeover turn, immediately before its first coding delegation, read the current thread again through `message` with the current channel, complete `chat_id` as `target`, and bare thread ID. This catches human instructions that arrived during setup. Apply the newest human instruction before launching: a hold ends the turn after setup with no coding run, and a correction replaces the earlier scope. Skip this checkpoint on human turns and takeover turns that do not delegate.
 
@@ -133,7 +138,7 @@ Keep scratch artifacts out of tracked git directories.
 
 ## Vocabulary
 
-- **the coder** — the coding agent (Claude Code or Codex) you launch in a project with `{{ALIGNDEV}} code`. It reads and changes the codebase; you guide it.
+- **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.
 - **ticket** — an issue or card.
 - **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_.
 - **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_.

package/templates/guide/playbook/project-lifecycle.md

@@ -12,7 +12,7 @@ Each marked projects directory governs its own direct children. Apply only the s
 
 Creation may begin with a proposed PROJECT and no PROJECT_PATH.
 
-Project creation is bootstrap work, not an AlignFirst protocol. Through the initial commit, every delegation to the coder uses a fresh session with a plain message. Never pass `--protocol`, even when `.plans/` exists or the bootstrap resembles development work.
+Project creation is bootstrap work, not an AlignFirst protocol. Through the initial commit, every delegation to the agent uses a fresh session with a plain message. Never pass `--protocol`, even when `.plans/` exists or the bootstrap resembles development work.
 
 Before creating a directory, load the `alignfirst-setup-guide` skill. If the skill is unavailable or cannot be read, project creation is disabled: report that requirement and stop. Use the skill throughout the bootstrap.
 
@@ -21,7 +21,7 @@ Creation has a hard user-input gate. Before any filesystem, Git, port-allocation
 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.
 2. Create the main-worktree directory under the selected allowed parent. Initialize its Git repository on `main`.
 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 <perWorkspace × maxWorkspaces> [--range <code>]` and retain the block; preparation through the setup guide writes it into `.alignfirst.json`. The selected parent's marker owns its port range. Report that `.alignfirst.json` was written and name the block.
-4. Create `.plans/`, 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`. The bot chooses the identifier and writes the request; the coder does neither. A later plans setup migrates this content when it replaces the directory with a symlink.
+4. Create `.plans/`, 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`. The bot chooses the identifier and writes the request; the agent does neither. A later plans setup migrates this content when it replaces the directory with a symlink.
 5. Before delegating the bootstrap, run `{{ALIGNDEV}} guide code`. On a takeover turn, apply the pre-delegation race checkpoint in the playbook (`{{ALIGNDEV}} guide`) immediately before `{{ALIGNDEV}} code new`. Then bootstrap directly from PROJECT_PATH through `{{ALIGNDEV}} code new --message`, with no protocol. Explicitly instruct it to use `alignfirst-setup-guide` and prepare the repository for an assistant. It must run `{{ALIGNDEV}} project doctor` after writing `.alignfirst.json` and before workspace setup, stopping on an unhealthy inventory. Include `.local/` as a gitignored shared directory in the workspace mechanism. Follow the selected stack and the host-specific guide.
 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.
 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.
@@ -31,7 +31,7 @@ The direct main-worktree bootstrap is the creation exception. It ends with the i
 
 ## Onboard a repository
 
-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 coder uses a fresh session with a plain message, never a protocol.
+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.
 
 ### Step 1 — Clone and build
 
@@ -50,7 +50,7 @@ The contract is the one the `alignfirst-setup-guide` lists under "Prepare a Proj
 
 When the user says the repository must stay untouched, follow "Prepare through the companion" below instead of Steps 3 to 5.
 
-End the turn on a message that explains the procedure: a branch created in the main worktree, preparation commits by the coder, a pull request the user must merge, and work waiting for that merge before the original request resumes.
+End the turn on a message that explains the procedure: a branch created in the main worktree, preparation commits by the agent, a pull request the user must merge, and work waiting for that merge before the original request resumes.
 
 Ask the user to approve this procedure and whether `.plans` must be shared through a work-files repository. If yes, ask for the repository URL. If no, `.plans` stays a plain directory. Wait for explicit approval.
 
@@ -60,8 +60,8 @@ On approval:
 
 1. Create `.plans/` in the main worktree and run `{{ALIGNFIRST}} sync`. Run `{{ALIGNFIRST}} ticket --side` from PROJECT_PATH, write `{TICKET_DIR}A1-request.md` with the recorded request, then run `{{ALIGNFIRST}} sync`.
 2. Create `{TICKET_ID}/alignfirst-setup` in the main worktree. This setup branch is the second main-worktree exception, next to new-project bootstrap.
-3. Run `{{ALIGNDEV}} guide code`. From PROJECT_PATH, delegate the preparation to the coder without a protocol: use the `alignfirst-setup-guide` skill and prepare the repository for an assistant, with the user's work-files repository decision and its URL. It must run `{{ALIGNDEV}} project doctor` after writing `.alignfirst.json` and before workspace setup, stopping on an unhealthy inventory. Instruct the coder to commit and push the branch. The setup guide's rule against pushing addresses a human's laptop session, not this procedure.
-4. Have the coder create a ready pull request, not a draft.
+3. Run `{{ALIGNDEV}} guide code`. From PROJECT_PATH, delegate the preparation to the agent without a protocol: use the `alignfirst-setup-guide` skill and prepare the repository for an assistant, with the user's work-files repository decision and its URL. It must run `{{ALIGNDEV}} project doctor` after writing `.alignfirst.json` and before workspace setup, stopping on an unhealthy inventory. Instruct the agent to commit and push the branch. The setup guide's rule against pushing addresses a human's laptop session, not this procedure.
+4. Have the agent create a ready pull request, not a draft.
 5. End the turn on the PR link and state that work resumes once the PR is merged.
 
 ### Step 5 — After the merge
@@ -79,10 +79,10 @@ When the user reports the merge, or you observe it while checking the PR:
 
 The preparation targets the project's companion directory. It writes nothing in the repository and creates no branch, commit or pull request.
 
-1. Read the `Companion:` line of `{{ALIGNDEV}} project status <PROJECT_PATH>`. `(none)` means no entry of `~/.config/alignfirst/companions.json` matches the project. You cannot write that file: the deployment locks `~/.config/alignfirst/`. End the turn asking the operator for an entry covering PROJECT_PATH, and stop there.
+1. Read the `Companion:` line of `{{ALIGNDEV}} project status <PROJECT_PATH>`. `(none)` means no entry of `~/.alignfirst/companions.json` matches the project. You cannot write that file: the deployment locks `~/.alignfirst/`. End the turn asking the operator for an entry covering PROJECT_PATH, and stop there.
 2. 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.
 3. When the user chose the work-files repository, clone it under `{{PROJECTS_ROOT}}` when no clone exists there.
-4. Run `{{ALIGNDEV}} guide code`. From PROJECT_PATH, delegate the preparation to the coder without a protocol: use the `alignfirst-setup-guide` skill and follow its procedure "Prepare a project through its companion", with the work-files clone path when there is one.
+4. Run `{{ALIGNDEV}} 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.
 5. Run `{{ALIGNDEV}} project doctor`. Stop when the inventory is unhealthy.
 6. Continue with the normal working-session flow for the original request through `{{ALIGNDEV}} guide project-workspace-setup`. The project runs in main-worktree mode.
 

package/templates/guide/playbook/project-workspace-setup.md

@@ -144,8 +144,8 @@ The `[WORKSPACE]` banner names the main worktree: `Worktree:` is the directory n
 Skip on sub-path 3 (no branch — nothing to sync). Otherwise, once the workspace is set up, bring the branch up to date *before* inspecting, working, or reporting a status — a teammate may have pushed since you last synced, and a report off a stale branch is wrong. In order:
 
 1. **Confirm the branch.** Check the worktree's checked-out branch carries the expected TICKET_ID. If it doesn't, stop and surface it to the user — don't work on the wrong branch.
-2. **Guard uncommitted work.** Run `git status`. If the worktree is dirty, have the coder commit a WIP first (even if it doesn't compile) — never sync over uncommitted work.
-3. **Merge the remote branch.** If the branch has a remote counterpart, merge its freshly fetched ref into the local branch to catch up. Delegate to the coder (`merge` protocol) when it doesn't fast-forward or conflicts.
+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.
+3. **Merge the remote branch.** If the branch has a remote counterpart, 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.
 4. **Catch up with the base branch.** If the freshly fetched base branch (`origin/<base>`) 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.
 5. **Refresh the workspace if commits came in.** If the merge brought in new commits, run the "Refreshing the workspace after a branch refresh" flow: reinstall dependencies, rebuild, run the new migrations.
 6. **Check for an open MR/PR** on this branch and note its state.
@@ -158,13 +158,13 @@ Only for a status request; otherwise skip to Step 7. The Step 4 banner comes fir
 The `[WORKSPACE]` banner answers "is the env ready", not "where does the work stand". For the work content — what was done, what remains — draw on two complementary sources:
 
 - **Repo/workflow metadata**, which you may gather directly: `git log`/`status`/branch state, `gh` PR/issue state, the `.plans/` listing.
-- **The ticket's AlignFirst artifacts** via `{{ALIGNDEV}} code new --ticket <id> --catchup`, run from the worktree: the coder loads the ticket history and returns a synthesis.
+- **The ticket's AlignFirst artifacts** via `{{ALIGNDEV}} code new --ticket <id> --catchup`, run from the worktree: the agent loads the ticket history and returns a synthesis.
 
 {{#openclaw}}
-Combine them into the report and post it in the thread; use `--catchup` whenever the ticket history matters. Add `--protocol aad` or `--protocol spec` to continue with that protocol in the same `{{ALIGNDEV}} code` call. What you must **not** do is browse the source to describe how the code works — that's a delegation to the coder, not part of a status report.
+Combine them into the report and post it in the thread; use `--catchup` whenever the ticket history matters. Add `--protocol aad` or `--protocol spec` to continue with that protocol in the same `{{ALIGNDEV}} code` call. What you must **not** do is browse the source to describe how the code works — that's a delegation to the agent, not part of a status report.
 {{/openclaw}}
 {{#codingAgent}}
-Combine them into the report and post it in the conversation; use `--catchup` whenever the ticket history matters. Add `--protocol aad` or `--protocol spec` to continue with that protocol in the same `{{ALIGNDEV}} code` call. What you must **not** do is browse the source to describe how the code works — that's a delegation to the coder, not part of a status report.
+Combine them into the report and post it in the conversation; use `--catchup` whenever the ticket history matters. Add `--protocol aad` or `--protocol spec` to continue with that protocol in the same `{{ALIGNDEV}} code` call. What you must **not** do is browse the source to describe how the code works — that's a delegation to the agent, not part of a status report.
 {{/codingAgent}}
 
 ## Step 7 — Start the work