aligndev 0.0.0 → 0.18.0

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

@@ -0,0 +1,100 @@
+# Runbook: Project lifecycle
+
+Use this procedure only to create a project, onboard a repository to clone, or physically remove a project. Project-workspace creation and cleanup follow `{{ALIGNDEV}} guide project-workspace-setup` and the project's workspace tooling.
+
+## Start with the project guide
+
+Run `{{ALIGNDEV}} guide project` and read the complete output before any lifecycle action. This call is mandatory for creation, onboarding, and removal; the JSON project inventory does not replace it. The sections it renders for each projects directory carry the host's allowed directories, their descriptions, and port ranges. The project kind supplies the range code: when the selected parent lists a matching coded range, pass its code with `--range`; the default range needs no flag. Follow those constraints throughout this procedure.
+
+Each marked projects directory governs its own direct children. Apply only the selected parent's description and ranges; do not inherit an ancestor's creation policy. When that description permits the requested creation and the user explicitly says to proceed, continue without asking another person. Seek named-role approval only when the selected parent's description requires it.
+
+## Create a project
+
+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.
+
+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.
+
+Creation has a hard user-input gate. Before any filesystem, Git, port-allocation, plan, or delegation effect, the user must have supplied or approved the project name, selected parent, stack, and port requirements, including that no ports are needed. Do not fill these values from the projects guide or defaults. If any is missing, ask for all missing values and end the turn. For a new Node.js project whose user did not name an exact version, use the service user's current Node major for the version declaration; do not ask for a version separately.
+
+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.
+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.
+8. After that commit and push when applicable, return to the normal working-session flow. Every subsequent branch change uses a linked project workspace.
+
+The direct main-worktree bootstrap is the creation exception. It ends with the initial commit and the push when a remote destination is known. If the user then requests more changes without a ticket, return to the working-session flow: reserve `side-N`, create a linked workspace, and delegate from it.
+
+## 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.
+
+### Step 1 — Clone and build
+
+Before any discussion:
+
+1. Select a parent directory allowed by `{{ALIGNDEV}} guide project`. Ask the user when several qualify.
+2. Clone the repository into that parent. PROJECT is the clone's directory name; PROJECT_PATH is its canonical path.
+3. Retain the canonical path as PROJECT_PATH. Run `{{ALIGNDEV}} project status <PROJECT_PATH>` and retain its `DEVELOPERS.md` path as DEVELOPERS_PATH. When the project's workspace wrapper declares ports, run `{{ALIGNDEV}} project free-ports --root <selected parent directory> --size <perWorkspace × maxWorkspaces> [--range <code>]` and retain the block; preparation through the setup guide writes it into `.alignfirst.json`.
+4. Install dependencies and build, following the repository's own README.
+
+### Step 2 — Check the Dev Kit contract
+
+The contract is the one the `alignfirst-setup-guide` lists under "Prepare a Project for an Assistant": AlignFirst skills configuration, docmap, the workspace system, and a `DEVELOPERS.md` with a workspaces section. The workspace system and its section belong to the contract only for a project that installs them; a project without them runs in main-worktree mode. When DEVELOPERS_PATH exists, the project is prepared: continue with the normal working-session flow for the user's request. Otherwise, continue to Step 3.
+
+### Step 3 — Warn and ask
+
+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.
+
+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.
+
+### Step 4 — Prepare the project on a branch
+
+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.
+5. End the turn on the PR link and state that work resumes once the PR is merged.
+
+### Step 5 — After the merge
+
+When the user reports the merge, or you observe it while checking the PR:
+
+1. In the main worktree, switch back to the default branch, pull, and delete the local setup branch.
+2. Install dependencies and build.
+3. When the user chose the work-files repository, clone it under `{{PROJECTS_ROOT}}` when no clone exists there (the projects guide names the repository), then run `{{ALIGNFIRST}} plans setup {{PROJECTS_ROOT}}/<clone>` from PROJECT_PATH. Otherwise, run `mkdir .plans`.
+4. Run `{{ALIGNDEV}} project doctor`. Stop when the inventory is unhealthy.
+5. Run the project's `workspace setup` on the main worktree. Add `--profile remote` when the deployment sets `REMOTE_DEV_DOMAIN`.
+6. Continue with the normal working-session flow for the original request through `{{ALIGNDEV}} guide project-workspace-setup`.
+
+### Prepare through the companion
+
+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.
+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.
+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.
+
+## Remove a project
+
+Removal requires the listed PROJECT_PATH selected before the thread opened or supplied by the user.
+
+1. Run and read `{{ALIGNDEV}} guide project`, then refresh `{{ALIGNDEV}} project list --json` and resolve the listed project at PROJECT_PATH. Run `{{ALIGNDEV}} project status <PROJECT_PATH>` and retain its `DEVELOPERS.md` path as DEVELOPERS_PATH, and its companion directory when it reports one. Read DEVELOPERS_PATH, then run and read the project workspace guide it names, if any.
+2. A project in main-worktree mode (DEVELOPERS_PATH missing or without a workspaces section) has no linked workspace to enumerate: its list holds PROJECT_PATH alone. Otherwise, use the project workspace tooling to enumerate every registered linked workspace and its exact absolute path. Include the exact PROJECT_PATH for the main worktree.
+3. Show the user the complete linked-worktree path list and the main-worktree path. Wait for explicit confirmation of those exact paths.
+4. Remove each confirmed linked workspace through the project workspace tooling. Stop immediately if any removal fails; keep the main worktree intact.
+5. Remove only the confirmed main-worktree directory at PROJECT_PATH. Leave every additional directory reported by the inventory untouched, the companion directory included.
+6. Refresh `{{ALIGNDEV}} project list --json`: the path must be absent from `projects`. Report any remaining workspace or filesystem discrepancy, and name the companion directory left in place.
+
+Apply the host-specific and project-specific constraints read earlier throughout the sequence.

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

@@ -0,0 +1,186 @@
+# Runbook: Project workspace setup
+
+{{#openclaw}}
+The setup phase of a working session: get the workspace ready before handling the user's request. You're in a thread session, so your plain-text replies are your delivery — but only the message that **ends your turn** is guaranteed to post; mid-turn lines may never leave the transcript. The message you end the setup turn with must carry everything the user needs: the `[WORKSPACE]` banner (Step 4) and what you did or launched. Never call `message` `send`/`thread-reply` targeting your own thread: it posts everything twice.
+{{/openclaw}}
+{{#codingAgent}}
+The setup phase of a working session: get the workspace ready before handling the user's request. The message you end the setup turn with carries the `[WORKSPACE]` banner (Step 4) and what you did or launched.
+{{/codingAgent}}
+
+## Prerequisites — run both now, before Step 1
+
+{{#openclaw}}
+- `{{ALIGNDEV}} guide code` (`exec`) — the delegation manual. Required every time you run this procedure, status requests included; do not skip it because no coding seems planned.
+{{/openclaw}}
+{{#codingAgent}}
+- `{{ALIGNDEV}} guide code` — the delegation manual. Required every time you run this procedure, status requests included; do not skip it because no coding seems planned.
+{{/codingAgent}}
+{{#openclaw}}
+- run `{{ALIGNDEV}} project status <PROJECT_PATH>` and retain its `DEVELOPERS.md` path as DEVELOPERS_PATH, then read that file when it exists — how to create a worktree or a branch.
+{{/openclaw}}
+{{#codingAgent}}
+- read DEVELOPERS_PATH, retained by Step 1 of `{{ALIGNDEV}} guide working-session`, when it exists — how to create a worktree or a branch.
+{{/codingAgent}}
+
+## Step 1 — Requirements
+
+You need:
+
+- **PROJECT** — The main-worktree directory name shown to the user.
+{{#openclaw}}
+- **PROJECT_PATH** — The canonical absolute main-worktree path recorded in the thread starter.
+{{/openclaw}}
+{{#codingAgent}}
+- **PROJECT_PATH** — The canonical absolute main-worktree path resolved by Step 1 of `{{ALIGNDEV}} guide working-session`.
+{{/codingAgent}}
+- **TICKET_ID** — The external ticket ID or the side ticket `side-N` reserved by the working session.
+
+If PROJECT, PROJECT_PATH, or TICKET_ID is missing, do not proceed. Do not guess or reconstruct these values. Ask the user.
+
+## Step 2 — Post the setup signal
+
+{{#openclaw}}
+Setting up a workspace takes a while, so tell the user it started before you start it. One short line, in their language, and nothing else — the thread's starter already states the known project, ticket and task, so restating them here just repeats a message they can see.
+{{/openclaw}}
+{{#codingAgent}}
+Setting up a workspace takes a while, so tell the user it started before you start it. One short line, in their language, and nothing else — the user already knows the project, ticket and task, so restating them here just repeats what they have seen.
+{{/codingAgent}}
+
+Vary the wording: "Je prépare le workspace", "Setting up the workspace", "Spinning up the environment", "Getting the worktree ready", "Preparing the branch". No questions, no waiting.
+
+{{#openclaw}}
+On some surfaces this line never posts (mid-turn text — see the delivery note at the top). Write it anyway, and count on the end-of-turn message, not on it, for anything the user must see.
+{{/openclaw}}
+
+{{#openclaw}}
+When the task changed with the message that woke you — a ticket that just arrived in a conversation thread, a scope the user just corrected — add a one-line restatement of what you're now working on. That line is the thread's durable record of the new task, the way the starter was for the original one.
+{{/openclaw}}
+{{#codingAgent}}
+When the task changed with the user's latest message — a ticket that just arrived, a scope the user just corrected — add a one-line restatement of what you're now working on. That line is the conversation's record of the new task.
+{{/codingAgent}}
+
+{{#openclaw}}
+## Step 3 — Name the thread (Discord-only)
+
+Rename the thread whenever its name doesn't match what you now know. Format: `<TICKET_ID> - <PROJECT> - <1-to-5-word description>`, the description covering the task. A ticket that just arrived, a project that was unknown when the thread opened, a task that turned out to be something else — each one calls for the rename.
+
+Discord renames a thread through a post, so make the setup signal carry it: send that line with `message` `action: "send"`, passing the current thread's complete `chat_id` as `target`, the new name as `threadName`, and the line itself as `message`. Don't also write the line as plain text; that posts it twice. The post does not end the turn: Step 4 follows in the same turn, and the turn ends on the banner.
+
+That single call is the whole exception. The post right after it, and every one that follows, is plain text again; with nothing to rename, the tool never targets your own thread.
+{{/openclaw}}
+{{#codingAgent}}
+## Step 3 — Not applicable
+
+Continue with Step 4.
+{{/codingAgent}}
+
+## Step 4 — Set up the project workspace (worktree, branch, dev server)
+
+{{#openclaw}}
+A project runs in **main-worktree mode** when DEVELOPERS_PATH is missing or has no workspaces section. Its main worktree at PROJECT_PATH is its only workspace, used by one working thread at a time. "Main-worktree mode" below adapts this step, and wherever the playbook names the linked workspace, you use PROJECT_PATH.
+{{/openclaw}}
+{{#codingAgent}}
+A project runs in **main-worktree mode** when DEVELOPERS_PATH is missing or has no workspaces section. Its main worktree at PROJECT_PATH is its only workspace, used by one working session at a time. "Main-worktree mode" below adapts this step, and wherever the playbook names the linked workspace, you use PROJECT_PATH.
+{{/codingAgent}}
+
+Otherwise, the workspace tooling owns worktrees. Run its main-worktree commands from PROJECT_PATH. Create, reuse, and tear worktrees down through its commands only — never `git worktree add`/`remove`/`prune`, never `rm -rf` on a worktree directory, never a branch checked out by hand outside a workspace. A worktree the tooling doesn't know about is invisible to every other session.
+
+First, fetch remote refs from PROJECT_PATH with `git fetch --prune`. Then check what already exists for the {TICKET_ID} — two checks, both required:
+
+- **Branch**: from PROJECT_PATH, list the branches, local and remote (`git branch -a`), and look for one matching the {TICKET_ID}. No match means no branch yet — an answer, not a failure.
+- **Registered workspaces**: `DEVELOPERS.md` names the project's guide command (`workspace --guide`, with the project's own runner). It gives the commands to **list registered workspaces** and to **set up a workspace** — on an existing branch, or on a new one. Use them.
+
+Never assume the branch is new; `git worktree list` alone does not answer the branch question.
+
+Whenever a branch exists, you work from its workspace — a status request included. "Status" means: set up the workspace, report its state (the banner below), sync the branch (Step 5), then report the work content (Step 6) — never `git log` from the main dir. Pick one sub-path:
+
+1. **Branch + workspace already registered** → use it (no setup needed).
+2. **Branch exists (local or remote), no workspace** → set up a workspace on the existing branch (don't create a new branch).
+3. **No branch** → for a status request, end the turn on a message reporting that no workspace or code work exists, with any request, spec, and summary files listed by the ticket preflight; create nothing. Any other request is new-work intent: in PROJECT_PATH, fast-forward the base branch from its freshly fetched remote ref so the new branch starts from the latest base, then set up a workspace on a new branch. Name it `{TICKET_ID}/{1-3-words}`, deriving the short description from the request. A fast-forward that brought in new commits leaves the main worktree stale, and no later step refreshes it: once the workspace is up, run the "Refreshing the workspace after a branch refresh" flow on the main worktree at PROJECT_PATH.
+
+{{#openclaw}}
+The moment you have the linked workspace path — attached (sub-path 1) or freshly set up (2, 3) — post the `[WORKSPACE]` banner, before any `git` inspection or prose, and **include it again in the message you end the turn with**: the early post may not deliver on every surface, the final message always does (on Discord the Step 3 rename post also delivers). `workspace setup` blocks until the bootstrap reaches `ready` or `failed`; run it in the foreground (no `background` option) and report the state it returns. Run subsequent Git commands and `{{ALIGNDEV}} code` from that linked workspace, never PROJECT_PATH, except in main-worktree mode.
+{{/openclaw}}
+{{#codingAgent}}
+The moment you have the linked workspace path — attached (sub-path 1) or freshly set up (2, 3) — post the `[WORKSPACE]` banner, before any `git` inspection or prose. `workspace setup` blocks until the bootstrap reaches `ready` or `failed`; run it in the foreground and report the state it returns. Run subsequent Git commands and `{{ALIGNDEV}} code` from that linked workspace, never PROJECT_PATH, except in main-worktree mode.
+{{/codingAgent}}
+
+{{#openclaw}}
+Bold the values with your surface's markers rather than literal `**`, and translate the labels to the user's language:
+{{/openclaw}}
+{{#codingAgent}}
+Bold the values in Markdown, and translate the labels to the user's language:
+{{/codingAgent}}
+
+```text
+[WORKSPACE] **{PROJECT}** — Ticket: `{TICKET_ID}`
+
+Worktree: `{dirname}`
+Branch: `{branch}`
+Status: {running | ready | failed}
+```
+
+The lines below the tag report the workspace: after `Status:`, add what the setup output gives that the user can act on.
+
+### Main-worktree mode
+
+{{#openclaw}}
+The branch check applies; the registered-workspace check does not. Before any checkout, claim the main worktree. It is free when it is on the default branch with a clean `git status`, or already on this thread's {TICKET_ID} branch. Otherwise, end the turn telling the user the project is busy: name the checked-out branch and the uncommitted changes, and change nothing.
+{{/openclaw}}
+{{#codingAgent}}
+The branch check applies; the registered-workspace check does not. Before any checkout, claim the main worktree. It is free when it is on the default branch with a clean `git status`, or already on this session's {TICKET_ID} branch. Otherwise, end the turn telling the user the project is busy: name the checked-out branch and the uncommitted changes, and change nothing.
+{{/codingAgent}}
+
+On a free main worktree, the sub-paths above run in PROJECT_PATH with plain `git switch`:
+
+1. **Already on the branch** → use it.
+2. **Branch exists, not checked out** → `git switch <branch>`.
+3. **No branch** → a status request ends as above. Otherwise, fast-forward the base branch as above, then `git switch -c {TICKET_ID}/{1-3-words}`.
+
+The `[WORKSPACE]` banner names the main worktree: `Worktree:` is the directory name of PROJECT_PATH, and `Status:` is `ready`.
+
+## Step 5 — Sync an existing branch on takeover (sub-paths 1 & 2)
+
+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.
+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.
+7. **Report what changed.** If either merge brought in new commits, post a one-line summary so the user knows the ground shifted.
+
+## Step 6 — Status request: the work content
+
+Only for a status request; otherwise skip to Step 7. The Step 4 banner comes first — post it before delegating; by now the Step 5 sync has brought the branch current, so the report reflects the latest state.
+
+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.
+
+{{#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.
+{{/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.
+{{/codingAgent}}
+
+## Step 7 — Start the work
+
+{{#openclaw}}
+The workspace is ready. Before a coding delegation, apply the takeover-turn race checkpoint in the playbook (`{{ALIGNDEV}} guide`). Then announce what you're about to do in one line and do it. The user's request is the go-ahead; asking them to confirm it again wastes a turn.
+{{/openclaw}}
+{{#codingAgent}}
+The workspace is ready. Announce what you're about to do in one line and do it. The user's request is the go-ahead; asking them to confirm it again wastes a turn.
+{{/codingAgent}}
+
+{{#openclaw}}
+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.
+{{/openclaw}}
+{{#codingAgent}}
+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.
+{{/codingAgent}}
+
+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.

package/templates/guide/playbook/slack-message-tool.md

@@ -0,0 +1,23 @@
+# Extended `message` actions on Slack
+
+The workspace `AGENTS.md` carries the core calls for history recovery and attachments. Read this reference when you need a reaction, edit, delete, or search.
+
+## Targets and IDs
+
+The inbound conversation metadata provides `chat_id` and `message_id`.
+
+For `target`, pass `chat_id` exactly as provided, including its `channel:` prefix. For `threadId`, pass only the bare thread ID.
+
+## Supported actions
+
+Slack supports `send`, `read`, `react`, `edit`, `delete`, `search`, and `sendAttachment`. The channel dispatcher uses `send` with an explicit `threadId` for the starter; cross-surface messages and attachments also use explicit actions. Ordinary replies in the current thread use plain delivery and must not be duplicated through `message`. Slack threads have no name and Slack has no `thread-create` or `thread-reply` action.
+
+```jsonc
+{ "action": "send", "channel": "<Slack surface id>", "target": "<channel chat_id>", "threadId": "<triggering root timestamp>", "message": "<starter>" }
+```
+
+## Reactions
+
+```jsonc
+{ "action": "react", "channel": "<Slack surface id>", "target": "<chat_id>", "messageId": "<message id>", "emoji": "lobster" }
+```