aligndev 0.20.2 → 0.22.0

package/README.md

@@ -2,15 +2,33 @@
 
 Autonomous software development. You say what you want; the assistant drives the coding agents and brings you the decisions.
 
-You talk to an **assistant**, the way you would to a developer on your team. It never touches the code itself. It isolates each task in its own workspace, then hands the investigation and the coding to an AI coding agent, **the agent**, which follows the [AlignFirst](https://alignfirst.paroi.tech/) protocols: specify, plan, implement, review. The assistant reads the agent's work, tests it, asks you what only you can decide, and opens the pull request.
+See the [product page](https://alignfirst.paroi.tech/aligndev) for an overview.
+
+You talk to an **assistant**, the way you would to a developer on your team. It never touches the code itself. It isolates each task in its own workspace, then hands the investigation and the coding to an AI coding agent, **the agent**, which follows the AlignFirst protocols: specify, plan, implement. The assistant reads the agent's work, tests it, asks you what only you can decide, and opens the pull request.
 
 `aligndev` is the assistant's CLI. It gives the assistant its playbook, launches and tracks the agent, and keeps the inventory of your projects. You never run it yourself: the assistant does.
 
+## The Assistant's Workflow
+
+For each task, the assistant:
+
+1. Discusses the task with the agent and has it write a **spec**.
+2. Has it write the **plans**.
+3. Has the plans **executed** in a fresh session.
+4. Has a **code review** done in another session.
+5. Has the review findings **fixed** in yet another session.
+6. For UI changes, **tests manually** and checks the dev-server logs.
+7. Has fixes made as needed.
+8. Takes **screenshots** for good measure.
+9. Has the agent **open a draft PR**.
+
+A task can also start at any intermediate step.
+
 ## Two Ways to Run the Assistant
 
 **In your coding agent.** A Claude Code or Codex session becomes the assistant of the repository it starts in. You keep chatting in the same session; the agents it launches work in the background.
 
-**As an OpenClaw bot.** The [AlignFirst Dev Kit](https://alignfirst.paroi.tech/openclaw-dev-kit) deploys the assistant on a server, under its own name in Slack or Discord. It works on every project of the host, one thread per task.
+**As an OpenClaw bot.** [AlignDev for OpenClaw](#start-as-an-openclaw-bot) deploys the assistant on a server, under its own name in Slack or Discord. It works on every project of the host, one thread per task.
 
 Either way, the agent is Claude Code or Codex. A coding-agent assistant launches its own kind by default.
 
@@ -35,7 +53,7 @@ Then start a session in the project and invoke `/aligndev` in Claude Code, or `$
 Add this section to your global agent instructions (`~/.claude/CLAUDE.md`, `~/.codex/AGENTS.md`, or the equivalent):
 
 ```markdown
-## Aligndev
+## AlignDev
 
 When the user mentions **aligndev**, follow the `aligndev` playbook if it is already in context. Otherwise, run `npx -y aligndev guide` and follow it.
 ```
@@ -67,6 +85,25 @@ Then ask your session to work with aligndev.
 
 Unknown keys and invalid values are errors.
 
+## Start as an OpenClaw Bot
+
+AlignDev for OpenClaw runs the assistant as an OpenClaw bot. One deployment is a dedicated service account running the assistant under its own name and channel identity. The communication surface, the agent and the assistant's model provider are independent choices. Each task moves from a channel into its own thread, then into an isolated project workspace.
+
+```mermaid
+flowchart TD
+  U([User]) -->|Slack or Discord| O[OpenClaw]
+  O -->|aligndev guide and aligndev code| CA[Claude Code or Codex]
+  CA -->|AlignFirst protocols| FS[(Managed project)]
+```
+
+Install the setup skill where your agent will assemble the deployment's private administration repository:
+
+```sh
+npx -y skills add https://github.com/paleo/alignfirst --global --skill alignfirst-setup-guide
+```
+
+Then ask the agent to create an assistant. The skill collects the deployment values, renders one Slack or Discord variant and one Claude Code or Codex variant, and writes the installation, security, operation and recovery runbooks. Each managed project receives the full preparation contract: the AlignFirst bootstrap line, an optional work-files repository, docmap, isolated workspaces and a project-specific `DEVELOPERS.md`.
+
 ## Under the Hood
 
-`aligndev` documents itself for the assistant: `aligndev --help`, then `aligndev guide`, print everything it needs. Maintainers: see [aligndev Architecture](https://github.com/paleo/alignfirst/blob/main/docs/aligndev-architecture.md).
+`aligndev` documents itself for the assistant: `aligndev --help`, then `aligndev guide`, print everything it needs. Maintainers: see [aligndev Architecture](https://github.com/paleo/alignfirst/blob/main/docs/aligndev-architecture.md) and the [AlignDev for OpenClaw map](https://github.com/paleo/alignfirst/blob/main/docs/aligndev-openclaw/aligndev-openclaw.md).

package/dist/cli.js

@@ -49,7 +49,7 @@ function renderHelp(aligndev) {
         [`${aligndev} -h, --help`],
         [`${aligndev} -v, --version`],
     ]);
-    return `aligndev — the AlignFirst Dev Kit CLI.
+    return `aligndev — the AlignDev CLI.
 
 Usage:
 ${usage}

package/dist/code/code-cli.js

@@ -26,7 +26,7 @@ const SESSION_OPTIONS = {
 // Items whose companion copy the agent may edit: the companion becomes a writable directory.
 const WRITABLE_COMPANION_ITEMS = [
     ".alignfirst.json",
-    ".alignfirst.md",
+    ".alignfirst-instructions",
     "DEVELOPERS.md",
     "docs",
     ".plans",
@@ -34,7 +34,7 @@ const WRITABLE_COMPANION_ITEMS = [
 // Items the agent would not find in the repository: a new session gets `alignfirst context`.
 const CONTEXT_COMPANION_ITEMS = [
     ".alignfirst.json",
-    ".alignfirst.md",
+    ".alignfirst-instructions",
     "docs",
     ".plans",
 ];

package/dist/guide/code-guide.js

@@ -1,6 +1,6 @@
 import { renderGuideTemplate } from "./render-template.js";
 export function renderCodeGuide(platform, agent, models, forms) {
-    return renderGuideTemplate("code.md", platform, forms, {
+    return renderGuideTemplate("code.md", { platform }, forms, {
         AGENT: agent,
         AUTH_COMMAND: agent === "claude" ? "`claude`, then `/login`" : "`codex login`",
         PERMISSIONS: agent === "claude"

package/dist/guide/guide-cli.js

@@ -4,6 +4,7 @@ import { PLATFORMS, requireProjectsRoot, resolveCodeConfig, } from "../config.js
 import { errorMessage } from "../errors.js";
 import { renderProjectsGuideForRoot } from "../project/project-cli.js";
 import { renderCodeGuide } from "./code-guide.js";
+import { resolveGuideFile } from "./guide-file.js";
 import { renderGuideTemplate } from "./render-template.js";
 import { PLAYBOOK_DISPATCHER, PLAYBOOK_TOPICS } from "./topics.js";
 export function runGuide(tokens, config, ctx) {
@@ -57,20 +58,24 @@ function renderTopic(args, config, ctx) {
     if (args.topic === "project" && config.platform === "openclaw") {
         return renderProjectsGuideForRoot({ ...ctx, projectsRoot: config.projectsRoot }, args.root);
     }
-    return renderPlaybookTopic(args.topic, config, ctx.forms);
+    return renderPlaybookTopic(args.topic, config, ctx);
 }
 function renderCodeTopic(config, ctx) {
     const code = resolveCodeConfig(config, ctx.env);
     const models = resolveModels(code.agent, code.models);
     return renderCodeGuide(config.platform, code.agent, models, ctx.forms);
 }
-function renderPlaybookTopic(topic, config, forms) {
+function renderPlaybookTopic(topic, config, ctx) {
     if (topic !== undefined)
         assertPlaybookTopic(topic, config.platform);
-    const values = config.platform === "openclaw"
-        ? { PROJECTS_ROOT: requireProjectsRoot(config).written }
-        : undefined;
-    return renderGuideTemplate(`playbook/${topic ?? PLAYBOOK_DISPATCHER}.md`, config.platform, forms, values);
+    const name = `playbook/${topic ?? PLAYBOOK_DISPATCHER}.md`;
+    if (config.platform === "codingAgent") {
+        const active = { platform: config.platform, guideFile: resolveGuideFile(ctx) };
+        return renderGuideTemplate(name, active, ctx.forms);
+    }
+    return renderGuideTemplate(name, { platform: config.platform }, ctx.forms, {
+        PROJECTS_ROOT: requireProjectsRoot(config).written,
+    });
 }
 function assertPlaybookTopic(topic, platform) {
     const topics = PLAYBOOK_TOPICS[platform];

package/dist/guide/guide-file.d.ts

@@ -0,0 +1,3 @@
+import type { ProjectsCallerContext } from "../project/project-cli.js";
+import type { GuideFileCondition } from "./render-template.js";
+export declare function resolveGuideFile(ctx: ProjectsCallerContext): GuideFileCondition;

package/dist/guide/guide-file.js

@@ -0,0 +1,26 @@
+import { execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { readProjectReport } from "../project/layout.js";
+// The project's guide file for the coding-agent assistant, resolved from PROJECT_PATH, the main
+// worktree of the working directory: its `DEVELOPERS.md`, else its `README.md`, else none.
+export function resolveGuideFile(ctx) {
+    const projectPath = mainWorktree(ctx);
+    if (projectPath === undefined)
+        return "noGuide";
+    const report = readProjectReport(ctx.alignfirstCommand, projectPath, ctx.env);
+    if ("error" in report)
+        throw new Error(report.error);
+    if (report.locations["DEVELOPERS.md"].exists)
+        return "developers";
+    return existsSync(join(projectPath, "README.md")) ? "readme" : "noGuide";
+}
+function mainWorktree(ctx) {
+    try {
+        const commonDir = execFileSync("git", ["-C", ctx.cwd, "rev-parse", "--path-format=absolute", "--git-common-dir"], { encoding: "utf8", env: ctx.env, stdio: ["ignore", "pipe", "ignore"] }).trim();
+        return dirname(commonDir);
+    }
+    catch {
+        return;
+    }
+}

package/dist/guide/render-template.d.ts

@@ -1,4 +1,11 @@
 import type { CommandForms } from "../command-form.js";
 import { type Platform } from "../config.js";
-export declare function renderGuideTemplate(name: string, platform: Platform, forms: CommandForms, values?: Readonly<Record<string, string>>): string;
-export declare function renderPlatformBlocks(text: string, platform: Platform, templateName: string): string;
+declare const GUIDE_FILE_CONDITIONS: readonly ["developers", "readme", "noGuide"];
+export type GuideFileCondition = (typeof GUIDE_FILE_CONDITIONS)[number];
+export interface ActiveBlocks {
+    platform: Platform;
+    guideFile?: GuideFileCondition;
+}
+export declare function renderGuideTemplate(name: string, active: ActiveBlocks, forms: CommandForms, values?: Readonly<Record<string, string>>): string;
+export declare function renderBlocks(text: string, active: ActiveBlocks, templateName: string): string;
+export {};

package/dist/guide/render-template.js

@@ -1,59 +1,86 @@
 import { PLATFORMS } from "../config.js";
 import { readTemplate } from "../templates.js";
+const GUIDE_FILE_CONDITIONS = ["developers", "readme", "noGuide"];
+// Active for both guide files: `developers` and `readme`.
+const HAS_GUIDE = "hasGuide";
 const MARKER = /^\{\{([#/])([A-Za-z]+)\}\}$/;
-// Renders `templates/guide/<name>`: the platform blocks first, then the placeholders — the command
-// forms and every key of `values`.
-export function renderGuideTemplate(name, platform, forms, values = {}) {
+// Renders `templates/guide/<name>`: the blocks first, then the placeholders — the command forms
+// and every key of `values`.
+export function renderGuideTemplate(name, active, forms, values = {}) {
     const placeholders = {
         ALIGNDEV: forms.aligndev,
         ALIGNFIRST: forms.alignfirst,
         ...values,
     };
-    let text = renderPlatformBlocks(readTemplate(`guide/${name}`), platform, name);
+    let text = renderBlocks(readTemplate(`guide/${name}`), active, name);
     for (const [key, value] of Object.entries(placeholders)) {
         text = text.replaceAll(`{{${key}}}`, value);
     }
     return text.trimEnd();
 }
-// A block is `{{#<platform>}}` … `{{/<platform>}}`, each marker alone on its line. The active
-// platform's blocks keep their content; the others are removed. Blocks do not nest. The runs of
-// empty lines that removed blocks leave collapse to one.
-export function renderPlatformBlocks(text, platform, templateName) {
+// A block is `{{#<name>}}` … `{{/<name>}}`, each marker alone on its line. A platform block sits
+// at the top level; a condition block sits directly inside a `codingAgent` block. A line
+// is kept when every block around it is active. The runs of empty lines that removed blocks leave
+// collapse to one.
+export function renderBlocks(text, active, templateName) {
     const kept = [];
-    let open;
+    const open = [];
     for (const [index, line] of text.split("\n").entries()) {
         const marker = MARKER.exec(line);
         if (marker === null) {
-            if (open === undefined || open.platform === platform)
+            if (open.every((block) => isActive(block.name, active)))
                 kept.push(line);
             continue;
         }
         const [, kind, name] = marker;
         const lineNumber = index + 1;
-        if (!isPlatform(name)) {
-            throw blockError(templateName, lineNumber, `unknown platform "${name}"`);
-        }
-        if (kind === "#") {
-            if (open !== undefined) {
-                throw blockError(templateName, lineNumber, `block "${name}" nested in "${open.platform}"`);
-            }
-            open = { platform: name, line: lineNumber };
+        if (kind === "#")
+            open.push(openBlock(name, lineNumber, open, templateName));
+        else
+            closeBlock(name, lineNumber, open, templateName);
+    }
+    const unclosed = open.at(-1);
+    if (unclosed !== undefined) {
+        throw blockError(templateName, unclosed.line, `block "${unclosed.name}" is not closed`);
+    }
+    return collapseEmptyLines(kept).join("\n");
+}
+function isActive(name, active) {
+    if (name === HAS_GUIDE)
+        return active.guideFile === "developers" || active.guideFile === "readme";
+    return name === active.platform || name === active.guideFile;
+}
+function openBlock(name, line, open, templateName) {
+    const outer = open.at(-1);
+    if (isPlatform(name)) {
+        if (outer !== undefined) {
+            throw blockError(templateName, line, `platform block "${name}" inside "${outer.name}"`);
         }
-        else {
-            if (open?.platform !== name) {
-                throw blockError(templateName, lineNumber, `closing marker "${name}" without its block`);
-            }
-            open = undefined;
+        return { name, line };
+    }
+    if (isCondition(name)) {
+        if (outer?.name !== "codingAgent") {
+            throw blockError(templateName, line, `condition block "${name}" outside a codingAgent block`);
         }
+        return { name, line };
     }
-    if (open !== undefined) {
-        throw blockError(templateName, open.line, `block "${open.platform}" is not closed`);
+    throw blockError(templateName, line, `unknown block "${name}"`);
+}
+function closeBlock(name, line, open, templateName) {
+    if (!isPlatform(name) && !isCondition(name)) {
+        throw blockError(templateName, line, `unknown block "${name}"`);
     }
-    return collapseEmptyLines(kept).join("\n");
+    if (open.at(-1)?.name !== name) {
+        throw blockError(templateName, line, `closing marker "${name}" without its block`);
+    }
+    open.pop();
 }
 function isPlatform(name) {
     return PLATFORMS.includes(name);
 }
+function isCondition(name) {
+    return name === HAS_GUIDE || GUIDE_FILE_CONDITIONS.includes(name);
+}
 function blockError(templateName, line, detail) {
     return new Error(`Error: template ${templateName}, line ${line}: ${detail}.`);
 }

package/dist/project/guide.js

@@ -3,7 +3,7 @@ import { renderGuideTemplate } from "../guide/render-template.js";
 import { escapeAdditionalJsonCharacters, formatRange } from "./format.js";
 // The projects guide serves the OpenClaw playbook only.
 export function renderProjectsGuide(forms, inventory) {
-    const guide = renderGuideTemplate("project.md", "openclaw", forms);
+    const guide = renderGuideTemplate("project.md", { platform: "openclaw" }, forms);
     if (inventory === undefined)
         return guide;
     const sections = inventory.directories.map((directory) => renderDirectory(inventory, directory));

package/dist/project/layout.d.ts

@@ -1,5 +1,5 @@
 import type { PortRange } from "./markers.js";
-export type ItemName = ".alignfirst.json" | ".alignfirst.md" | "DEVELOPERS.md" | "docs" | ".plans" | "_aligndev";
+export type ItemName = ".alignfirst.json" | ".alignfirst-instructions" | "DEVELOPERS.md" | "docs" | ".plans" | "_aligndev";
 export interface ProjectReport {
     source: ConfigSource | null;
     cli: ProjectCliReport | null;

package/dist/project/layout.js

@@ -75,7 +75,7 @@ function parsePlans(value, path) {
         throw invalidReport(path);
     return value.folder === undefined ? {} : { folder: value.folder };
 }
-// The report's other companion fields (`entries`, `flags`) are alignfirst's concern.
+// The report's other companion fields (`key`, `flags`) are alignfirst's concern.
 function parseCompanion(value, path) {
     if (value === null)
         return null;
@@ -90,7 +90,7 @@ function parseLocations(value, path) {
     const location = (name) => parseLocation(value[name], path);
     return {
         ".alignfirst.json": location(".alignfirst.json"),
-        ".alignfirst.md": location(".alignfirst.md"),
+        ".alignfirst-instructions": location(".alignfirst-instructions"),
         "DEVELOPERS.md": location("DEVELOPERS.md"),
         docs: location("docs"),
         ".plans": location(".plans"),

package/dist/project/project-cli.js

@@ -36,7 +36,7 @@ function runProjectCommand(ctx, args) {
         return 0;
     }
     if (args.command === "status" && args.path !== undefined) {
-        const details = getProjectStatus(inventory, args.path);
+        const details = getProjectStatus(inventory, resolve(ctx.cwd, args.path));
         ctx.stdout.write(args.json ? renderProjectStatusJson(details) : renderProjectStatus(details));
         return 0;
     }
@@ -57,6 +57,7 @@ function renderUsage(aligndev) {
   ${aligndev} project --help
 
 --root defaults to projectsRoot in the aligndev config, then to the working directory.
+A relative status <path> starts from the working directory.
 `;
 }
 // The projects guide, followed by the directory sections when the root carries a marker.

package/dist/project/status.d.ts

@@ -21,4 +21,4 @@ export interface ProjectWorktree {
     name: string;
     path: string;
 }
-export declare function getProjectStatus(inventory: ProjectInventory, inputPath: string): ProjectDetails;
+export declare function getProjectStatus(inventory: ProjectInventory, projectPath: string): ProjectDetails;

package/dist/project/status.js

@@ -1,10 +1,10 @@
 import { execFileSync } from "node:child_process";
 import { realpathSync } from "node:fs";
-import { basename, isAbsolute, resolve } from "node:path";
+import { basename } from "node:path";
 import { errorMessage, isNodeError } from "../errors.js";
 const URL_WITH_AUTHORITY = /^[A-Za-z][A-Za-z\d+.-]*:\/\//u;
-export function getProjectStatus(inventory, inputPath) {
-    const path = resolveProjectPath(inventory.root, inputPath);
+export function getProjectStatus(inventory, projectPath) {
+    const path = realPathOrSelf(projectPath);
     const project = inventory.projects.find((candidate) => candidate.path === path);
     if (project === undefined) {
         throw new Error(`${path} is not a project of ${inventory.root}. Pass the main-worktree path of a git ` +
@@ -12,8 +12,7 @@ export function getProjectStatus(inventory, inputPath) {
     }
     return buildProjectDetails(project);
 }
-function resolveProjectPath(root, inputPath) {
-    const path = isAbsolute(inputPath) ? inputPath : resolve(root, inputPath);
+function realPathOrSelf(path) {
     try {
         return realpathSync(path);
     }

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "aligndev",
-  "version": "0.20.2",
+  "version": "0.22.0",
   "license": "CC0-1.0",
   "author": "Thomas MUR",
-  "description": "The AlignFirst Dev Kit CLI: the assistant's playbook, coding-agent delegation, and project inventory.",
+  "description": "The AlignDev CLI: the assistant's playbook, coding-agent delegation, and project inventory.",
   "keywords": [
     "ai",
     "agent",
@@ -15,7 +15,7 @@
     "projects",
     "worktrees"
   ],
-  "homepage": "https://alignfirst.paroi.tech/openclaw-dev-kit",
+  "homepage": "https://alignfirst.paroi.tech/aligndev",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/paleo/alignfirst.git",

package/templates/guide/playbook/channel-handling.md

@@ -62,7 +62,7 @@ A value the user did not supply and the lookup did not resolve stays missing. St
 - `threadName`: the name above
 - `channel`: `<channel>`
 
-The tool returns the thread's `chat_id` — that is the THREAD_ID. Post the Step 3 starter into the thread: call `message` with `action: "thread-reply"`, `threadId` set to the bare THREAD_ID, `message` set to the starter, and `channel` set to the current surface. Pass no `target`.
+Pass no `message`: content on `thread-create` would post ahead of the starter. The tool returns the thread's `chat_id` — that is the THREAD_ID. Post the Step 3 starter into the thread: call `message` with `action: "thread-reply"`, `threadId` set to the bare THREAD_ID, `message` set to the starter, and `channel` set to the current surface. Pass no `target`.
 
 **Slack** — Slack threads have no name. Call `message` with `action: "send"`, `target` set to the raw current `chat_id`, `threadId` set to the triggering message timestamp, `message` set to the Step 3 starter, and `channel` set to the current surface. The bare root timestamp is the THREAD_ID. Slack has no `thread-create`, `thread-reply`, or rename action.
 

package/templates/guide/playbook/consultation.md

@@ -12,16 +12,22 @@ The user consults you, and you consult the agent. It reads the repository; you w
 Run `{{ALIGNDEV}} project status <PROJECT_PATH>` and retain its `DEVELOPERS.md` path as DEVELOPERS_PATH. Read DEVELOPERS_PATH and run `{{ALIGNFIRST}} context` from PROJECT_PATH.
 {{/openclaw}}
 {{#codingAgent}}
+{{#hasGuide}}
 Read DEVELOPERS_PATH, retained by Step 1 of `{{ALIGNDEV}} guide working-session`, and run `{{ALIGNFIRST}} context` from PROJECT_PATH.
+{{/hasGuide}}
+{{#noGuide}}
+Run `{{ALIGNFIRST}} context` from PROJECT_PATH.
+{{/noGuide}}
 {{/codingAgent}}
 
 {{#openclaw}}
 Use the main worktree on the configured default branch. When the question explicitly concerns a branch or a PR, or follows ongoing branch work in this thread, use that branch's existing registered workspace instead: resolve it through the project's workspace guide, and report the limitation rather than inspecting a different branch when no workspace exists. In main-worktree mode (`{{ALIGNDEV}} guide project-workspace-setup`), that workspace is the main worktree while it holds the branch.
 {{/openclaw}}
 {{#codingAgent}}
-Use the main worktree on the configured default branch. When the question explicitly concerns a branch or a PR, or follows ongoing branch work in this conversation, use that branch's existing registered workspace instead: resolve it through the project's workspace guide, and report the limitation rather than inspecting a different branch when no workspace exists. In main-worktree mode (`{{ALIGNDEV}} guide project-workspace-setup`), that workspace is the main worktree while it holds the branch.
+Use the session's worktree and its branch as they are. When the question explicitly concerns another branch or a PR, use that branch's existing registered workspace instead: resolve it through the project's workspace guide, and report the limitation rather than inspecting a different branch when no workspace exists.
 {{/codingAgent}}
 
+{{#openclaw}}
 ## Step 2 — Refresh the default branch
 
 Skip this step when Step 1 selected an existing branch workspace; inspect its current state as it is, without the workspace setup or branch-sync procedure.
@@ -31,6 +37,14 @@ Before delegating against the default branch, verify that the main worktree is c
 Stop and report the obstacle when the branch is wrong, the worktree is dirty, the upstream is missing, or the refresh fails. Preserve local work: a question is never a reason to switch branches, stash, commit, reset, or resolve a merge.
 
 Retain `git rev-parse --short HEAD` after the refresh. Other sessions fast-forward the same worktree, so this records which revision the answer came from. Report it when something in the answer looks inconsistent, and in the Step 5 record.
+{{/openclaw}}
+{{#codingAgent}}
+## Step 2 — Record the revision
+
+Skip the refresh of the default branch: the tree stays as the user left it. A question is never a reason to switch branches, stash, commit, reset, or resolve a merge.
+
+Retain `git rev-parse --short HEAD`, the revision the answer comes from. Report it when something in the answer looks inconsistent, and in the Step 5 record.
+{{/codingAgent}}
 
 ## Step 3 — Delegate
 
@@ -41,7 +55,12 @@ Apply the takeover-turn checkpoint in the playbook (`{{ALIGNDEV}} guide`), then
 Run `{{ALIGNDEV}} code new --message` from the selected worktree, without `--protocol`, `--ticket`, or `--no-ticket`.
 {{/codingAgent}}
 
+{{#openclaw}}
 The message carries the complete question, however detailed, the selected branch, and an explicit constraint to investigate and answer without implementing changes. Include the environment refresh described in the working session when the main branch advanced. Use the delegation guide's background launch and completion procedure.
+{{/openclaw}}
+{{#codingAgent}}
+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.
+{{/codingAgent}}
 
 Retain the printed session id. Later turns of the same topic resume that session, so the discussion accumulates in one place.
 
@@ -54,7 +73,12 @@ Answer in the thread, in your own words, grounded in what the agent found.
 Answer in the conversation, in your own words, grounded in what the agent found.
 {{/codingAgent}}
 
+{{#openclaw}}
 A request for changes ends the consultation: return to the ticket and linked-workspace flow before anything is implemented.
+{{/openclaw}}
+{{#codingAgent}}
+A request for changes ends the consultation: return to the ticket and workspace flow before anything is implemented.
+{{/codingAgent}}
 
 ## Step 5 — Record a discussion
 

package/templates/guide/playbook/playbook.md

@@ -63,14 +63,23 @@ You work on one project: the repository where this session started. Keep these v
 - **PROJECT** — the main-worktree directory name shown to the user.
 - **PROJECT_PATH** — the absolute main-worktree path.
 
-Step 1 of `{{ALIGNDEV}} guide working-session` resolves both, and DEVELOPERS_PATH. PROJECT_PATH anchors project-file reads, main-worktree Git commands, and workspace tooling. After workspace setup, use the returned linked-worktree path for branch work and `{{ALIGNDEV}} code`.
+Step 1 of `{{ALIGNDEV}} guide working-session` resolves both, and the workplace: the session's worktree and its branch, by default.
+{{#hasGuide}}
+It also retains DEVELOPERS_PATH, the project's guide for you.
+{{/hasGuide}}
+PROJECT_PATH anchors project-file reads, main-worktree Git commands, and workspace tooling. Branch work and `{{ALIGNDEV}} code` happen in the workplace, which the setup procedure may move to a workspace.
 
 Creating, onboarding, or removing a project is not handled in this mode. When the user asks for it, say so.
 {{/codingAgent}}
 
 ## Tickets and AlignFirst protocols
 
+{{#openclaw}}
 Code reviews and explicitly requested AlignFirst protocols follow their protocol workflow, including its ticket and workspace requirements. Other read-only questions, advice and brainstormings need no ticket or AlignFirst protocol to start. They use the refreshed main worktree unless they explicitly concern another branch; follow the working session's consultation runbook, which also records a discussion worth keeping.
+{{/openclaw}}
+{{#codingAgent}}
+Code reviews and explicitly requested AlignFirst protocols follow their protocol workflow, including its ticket and workspace requirements. Other read-only questions, advice and brainstormings need no ticket or AlignFirst protocol to start. They use the session's worktree as it is; follow the working session's consultation runbook, which also records a discussion worth keeping.
+{{/codingAgent}}
 
 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.
 
@@ -94,7 +103,7 @@ You are an autonomous programmer. Instructions reach you from two places, and "t
 {{#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 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.
+  - This session runs in the repository, so the project's `AGENTS.md`, `CLAUDE.md` or companion `.alignfirst-instructions/context.md` is auto-loaded too. It still addresses the agent: its directives about investigating or implementing, such as "run `alignfirst context` before any investigation", are for the agent.
 {{/codingAgent}}
 
 Exception: a project's `DEVELOPERS.md` addresses the agent's user — you.
@@ -117,7 +126,7 @@ Coding runs are long. Run `{{ALIGNDEV}} code` through `exec` in the background,
 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.
 {{/openclaw}}
 {{#codingAgent}}
-To delegate, run `{{ALIGNDEV}} code` from PROJECT_PATH or the linked worktree created from it. 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.
+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.
 
 Coding runs are long. Run `{{ALIGNDEV}} code` in the background, as the delegation guide describes.
 {{/codingAgent}}

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

@@ -42,7 +42,7 @@ Before any discussion:
 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
+### Step 2 — Check the AlignDev 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.
 
@@ -79,7 +79,7 @@ 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. Run `{{ALIGNFIRST}} companion add` from PROJECT_PATH. It registers the project in the companion registry unless an entry already covers it, and creates the companion directory.
+1. Run `{{ALIGNFIRST}} companion register` from PROJECT_PATH. It registers the project in the companion registry unless it is registered.
 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 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.
@@ -92,9 +92,10 @@ Removal requires the listed PROJECT_PATH selected before the thread opened or su
 
 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.
+3. Show the user the complete linked-worktree path list and the main-worktree path. When the project status reports a companion directory, show it too and ask whether to keep or delete it. Wait for explicit confirmation of those exact paths, and for the answer about the companion directory.
 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.
+5. When the project status reports a companion, run `{{ALIGNFIRST}} companion unregister` from PROJECT_PATH. It removes the registry entry and keeps the companion directory. Add `--remove-dir --force` when the user chose to delete the companion directory.
+6. Remove only the confirmed main-worktree directory at PROJECT_PATH. Leave every additional directory reported by the inventory untouched.
+7. Refresh `{{ALIGNDEV}} project list --json`: the path must be absent from `projects`. Report any remaining workspace or filesystem discrepancy, and name the companion directory when it was kept.
 
 Apply the host-specific and project-specific constraints read earlier throughout the sequence.

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

@@ -4,10 +4,15 @@
 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.
+The setup phase of a working session: decide the workplace and get it 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, or the question Step 2 or Step 5 asks the user.
 {{/codingAgent}}
 
+{{#openclaw}}
 ## Prerequisites — run both now, before Step 1
+{{/openclaw}}
+{{#codingAgent}}
+## Prerequisites — before Step 1
+{{/codingAgent}}
 
 {{#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.
@@ -19,7 +24,9 @@ The setup phase of a working session: get the workspace ready before handling th
 - 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.
+{{#hasGuide}}
+- Read DEVELOPERS_PATH, retained by Step 1 of `{{ALIGNDEV}} guide working-session` — whether the project has workspace tooling, and how to create a worktree or a branch.
+{{/hasGuide}}
 {{/codingAgent}}
 
 ## Step 1 — Requirements
@@ -32,17 +39,40 @@ You need:
 {{/openclaw}}
 {{#codingAgent}}
 - **PROJECT_PATH** — The canonical absolute main-worktree path resolved by Step 1 of `{{ALIGNDEV}} guide working-session`.
+- **The workplace and the default branch** — The session's worktree, its branch, and the project's default branch, retained by the same step.
 {{/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.
 
+{{#openclaw}}
 ## 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}}
+## Step 2 — Decide the workplace
+
+{{#hasGuide}}
+The project has **workspace tooling** when DEVELOPERS_PATH describes workspaces.
+{{/hasGuide}}
+{{#noGuide}}
+The project has no **workspace tooling**.
+{{/noGuide}}
+
+The workplace is the first case that matches:
+
+1. **The user's request or instructions name the place** — a directory, a branch, a workspace: work there.
+2. **The session's branch carries TICKET_ID** — work in place. Skip Steps 3 and 4: post the `[WORKSPACE]` banner (format in Step 4) with the session's worktree and branch and `Status: ready`, then go to Step 5.
+3. **The session's branch is long-lived** — the default branch, or a name such as `main`, `master`, `develop`, `release` or `production`: open or create the ticket's workspace in Step 4, without asking.
+4. **Any other branch**, one carrying another ticket's ID included — end the turn on one message asking where to work. On the answer, "here" means the session's worktree as it is, handled as in case 2; a branch or a directory the user names falls under case 1.
+
+Without workspace tooling, case 3 also ends the turn on that question, and "here" means the ticket's branch in the session's worktree: `git switch <branch>` when it exists, else a fast-forward of the base branch, then `git switch -c {TICKET_ID}/{1-3-words}`. The banner then follows case 2.
+
+## Step 3 — Post the setup signal
+
+Post the signal only when Step 2 opens or creates a workspace.
+
 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}}
 
@@ -68,27 +98,34 @@ Discord renames a thread through a post, so make the setup signal carry it: send
 
 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}}
 
+{{#openclaw}}
 ## Step 4 — Set up the project workspace (worktree, branch, dev server)
+{{/openclaw}}
+{{#codingAgent}}
+## Step 4 — Set up the workspace (worktree, branch, dev server)
+{{/codingAgent}}
 
 {{#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}}
 
+{{#openclaw}}
 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.
+{{/openclaw}}
+{{#codingAgent}}
+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.
+{{/codingAgent}}
 
 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.
+{{#openclaw}}
 - **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.
+{{/openclaw}}
+{{#codingAgent}}
+- **Registered workspaces**: the workspace tooling's guide command (`workspace --guide`, with the project's own runner) gives the commands to **list registered workspaces** and to **set up a workspace** — on an existing branch, or on a new one. Use them.
+{{/codingAgent}}
 
 Never assume the branch is new; `git worktree list` alone does not answer the branch question.
 
@@ -102,7 +139,7 @@ Whenever a branch exists, you work from its workspace — a status request inclu
 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.
+The moment you have the workplace — in place, 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 the workplace.
 {{/codingAgent}}
 
 {{#openclaw}}
@@ -122,15 +159,15 @@ 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.
 
+{{#openclaw}}
 ### Main-worktree mode
+{{/openclaw}}
 
 {{#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}}
 
+{{#openclaw}}
 On a free main worktree, the sub-paths above run in PROJECT_PATH with plain `git switch`:
 
 1. **Already on the branch** → use it.
@@ -138,8 +175,18 @@ On a free main worktree, the sub-paths above run in PROJECT_PATH with plain `git
 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`.
+{{/openclaw}}
 
+{{#openclaw}}
 ## Step 5 — Sync an existing branch on takeover (sub-paths 1 & 2)
+{{/openclaw}}
+{{#codingAgent}}
+## Step 5 — Sync an existing branch
+{{/codingAgent}}
+
+{{#codingAgent}}
+In place on an existing branch, fetch first. A fast-forward of the branch onto its remote counterpart or onto the base branch, on a clean tree, is the only sync done without asking: do it, then report it in one line. Anything else — uncommitted changes, a remote branch that does not fast-forward, a base-branch catch-up that needs a merge commit — ends the turn on one message stating what will happen ("I'll commit your changes as WIP and merge `main`, OK?"). The list below runs on the user's yes. In a workspace you opened or created, the list runs directly.
+{{/codingAgent}}
 
 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:
 

package/templates/guide/playbook/working-session.md

@@ -10,7 +10,7 @@ Your plain text is your reply, on Discord and Slack alike, and only the message
 Keep progress and completion reports in this thread. A request to notify the user means reply here; use a DM or another surface only when the user explicitly names that destination.
 {{/openclaw}}
 {{#codingAgent}}
-You're handling work in this conversation, on one project: the repository where this session started. Workspace, consultation, and coding happen here.
+You're handling work in this conversation, on one project: the repository where this session started. Workspace, consultation, and coding happen here. The session's worktree and its branch are your workplace by default.
 
 Keep progress and completion reports in this conversation. A request to notify the user means a reply here.
 {{/codingAgent}}
@@ -52,9 +52,16 @@ A takeover turn starts with the plugin's `Take over this thread.` message from `
 Outside a git repository, tell the user to start the session inside the project's repository, and stop. Otherwise, resolve the project before any other step:
 
 - PROJECT_PATH is the main worktree of the session's working directory: the parent of `git rev-parse --path-format=absolute --git-common-dir`. PROJECT is its directory name.
-- Run `{{ALIGNFIRST}} config --json` from PROJECT_PATH and retain `locations["DEVELOPERS.md"].path` as DEVELOPERS_PATH. The report also names the project's companion directory, where its AlignFirst files may live.
+- The workplace is the session's worktree (`git rev-parse --show-toplevel`) and its branch (`git branch --show-current`).
+- Run `{{ALIGNFIRST}} config --json` from PROJECT_PATH. The default branch is `config.git.defaultBranch` in the report, else `git symbolic-ref --short refs/remotes/origin/HEAD` without its `origin/` prefix. The report also names the project's companion directory, where its AlignFirst files may live.
+{{#developers}}
+- Retain `locations["DEVELOPERS.md"].path` from the report as DEVELOPERS_PATH.
+{{/developers}}
+{{#readme}}
+- Retain `README.md` at the root of PROJECT_PATH as DEVELOPERS_PATH: the project has no `DEVELOPERS.md`, and its README is your guide.
+{{/readme}}
 
-These values hold for the whole session.
+These values hold for the whole session. Only `{{ALIGNDEV}} guide project-workspace-setup` moves the workplace.
 {{/codingAgent}}
 
 {{#openclaw}}
@@ -91,7 +98,7 @@ Everything else is unchanged: the same runbooks, the same ticket rules, the same
 {{#codingAgent}}
 ### Step 2 — Recover the request
 
-The request comes from this conversation; later messages supply missing values or correct it. TICKET_ID comes from the user, a resource URL, or the current branch name when it carries one. Branch, linked-worktree path, and dev-server URL live in the conversation under `[WORKSPACE]`.
+The request comes from this conversation; later messages supply missing values or correct it. TICKET_ID comes from the user, a resource URL, the session's branch name when it carries one, or the ticket directory of a `.plans/` path the user names, such as a plan to execute. Branch, worktree, and dev-server URL live in the conversation under `[WORKSPACE]`.
 {{/codingAgent}}
 
 ### Step 3 — Resolve deferred context
@@ -152,7 +159,15 @@ Skip this step for read-only questions and operational work.
 
 For new single-project work where the user explicitly says there is no ticket or asks for a side ticket:
 
+{{#openclaw}}
 1. Read DEVELOPERS_PATH and run `{{ALIGNFIRST}} context` from PROJECT_PATH.
+{{/openclaw}}
+{{#codingAgent}}
+1. Run `{{ALIGNFIRST}} context` from PROJECT_PATH.
+{{#hasGuide}}
+   Read DEVELOPERS_PATH.
+{{/hasGuide}}
+{{/codingAgent}}
 2. Run `{{ALIGNFIRST}} sync`, so identifier selection sees the current shared task set.
 {{#openclaw}}
 3. Run `{{ALIGNFIRST}} ticket --side` from PROJECT_PATH (`exec`). It creates the ticket directory and prints it as TICKET_DIR; TICKET_ID is the `side-N` it reports.
@@ -172,7 +187,7 @@ For new single-project work where the user explicitly says there is no ticket or
 The bot owns this reservation and the request capture; the agent receives TICKET_ID. Do not use `{{ALIGNDEV}} code new --no-ticket`: TICKET_ID must exist before delegation, for the request file and the workspace. Continue to workspace setup with the side ticket as TICKET_ID, then run the coding protocol from the returned linked worktree.
 {{/openclaw}}
 {{#codingAgent}}
-You own this reservation and the request capture; the agent receives TICKET_ID. Do not use `{{ALIGNDEV}} code new --no-ticket`: TICKET_ID must exist before delegation, for the request file and the workspace. Continue to workspace setup with the side ticket as TICKET_ID, then run the coding protocol from the returned linked worktree.
+You own this reservation and the request capture; the agent receives TICKET_ID. Do not use `{{ALIGNDEV}} code new --no-ticket`: TICKET_ID must exist before delegation, for the request file and the workspace. Continue with `{{ALIGNDEV}} guide project-workspace-setup`, which decides the workplace with the side ticket as TICKET_ID, then run the coding protocol from that workplace.
 {{/codingAgent}}
 
 {{#openclaw}}
@@ -190,7 +205,7 @@ The question on every turn is not a mode but a fact: does this request need a pr
 - **The request is a single-project change, protocol request, or ticket status request** — require PROJECT, PROJECT_PATH, and TICKET_ID. A starter with a request block is filed first ("Detailed requests" below). Then run `{{ALIGNDEV}} guide project-workspace-setup`, read it fully, and complete it before any other action, `git log` and codebase inspection included. Your first post is its setup signal (Step 2); the procedure attaches or sets up the workspace, whatever exists, and posts the `[WORKSPACE]` banner.
 {{/openclaw}}
 {{#codingAgent}}
-- **The request is a single-project change, protocol request, or ticket status request** — require PROJECT, PROJECT_PATH, and TICKET_ID. A detailed request is filed first ("Detailed requests" below). Then run `{{ALIGNDEV}} guide project-workspace-setup`, read it fully, and complete it before any other action, `git log` and codebase inspection included. Your first post is its setup signal (Step 2); the procedure attaches or sets up the workspace, whatever exists, and posts the `[WORKSPACE]` banner.
+- **The request is a single-project change, protocol request, or ticket status request** — require PROJECT, PROJECT_PATH, and TICKET_ID. A detailed request is filed first ("Detailed requests" below). Then run `{{ALIGNDEV}} guide project-workspace-setup`, read it fully, and complete it before any other action, `git log` and codebase inspection included. The procedure decides the workplace (in place, a workspace, or a question to the user) and posts the `[WORKSPACE]` banner once it is known.
 {{/codingAgent}}
 - **A required value is missing** — go to Step 7. Resolve or ask for it there. The moment the required values are known, follow the matching path above.
 
@@ -198,7 +213,7 @@ The question on every turn is not a mode but a fact: does this request need a pr
 Changes to an existing project happen inside a linked workspace. Read-only questions use the main worktree by default. The lifecycle procedure also uses it for new-project bootstrap through its initial commit and repository onboarding on a setup branch.
 {{/openclaw}}
 {{#codingAgent}}
-Changes to an existing project happen inside a linked workspace. Read-only questions use the main worktree by default.
+Changes happen in the workplace the setup procedure decides. Read-only questions use the session's worktree as it is.
 {{/codingAgent}}
 
 ### Step 7 — Handle the actual request
@@ -254,7 +269,12 @@ When one project owns a detailed change request, preserve it before delegation:
 5. When ticket editing is available, add the request-file path relative to the project to the ticket description.
 6. Continue through project workspace setup and `{{ALIGNDEV}} code` as usual.
 
+{{#openclaw}}
 When Step 5 reserved a side ticket `side-N`, the request is already captured. Continue through project workspace setup and delegate from the linked worktree.
+{{/openclaw}}
+{{#codingAgent}}
+When Step 5 reserved a side ticket `side-N`, the request is already captured. Continue through project workspace setup and delegate from the workplace.
+{{/codingAgent}}
 
 {{#openclaw}}
 Skip this capture workflow for a multi-project request with no main project and for operational work such as workspace cleanup or base-branch refresh. Delegate those requests to the agent without an AlignFirst protocol.
@@ -282,7 +302,12 @@ Delegate to the agent: workspace/branch/worktree creation, writing code (`alignf
 
 Thinking is delegated too. When you need *ideas*, a *design* direction, an *opinion*, or an approach — for the user or for your own next step — put the question to the agent and build on its answer. Never brainstorm alone: the agent grounds its ideas in the codebase; yours would come from memory. `{{ALIGNDEV}} guide consultation` is the procedure.
 
+{{#openclaw}}
 Global tools go in the prompt. Run `{{ALIGNDEV}} code` from the linked workspace for changes and from PROJECT_PATH only when the procedure explicitly works in the main worktree. The agent knows only that directory's project context: it can run the globally installed tools your own context lists, but it doesn't know they exist. When a delegated task can use one, name it in the prompt as **globally installed**. A task you would have kept because it needs such a tool is one more thing to delegate.
+{{/openclaw}}
+{{#codingAgent}}
+Global tools go in the prompt. Run `{{ALIGNDEV}} code` from the workplace, unless a procedure names another directory. The agent knows only that directory's project context: it can run the globally installed tools your own context lists, but it doesn't know they exist. When a delegated task can use one, name it in the prompt as **globally installed**. A task you would have kept because it needs such a tool is one more thing to delegate.
+{{/codingAgent}}
 
 Every single-project change delegation carries TICKET_ID in the `{{ALIGNDEV}} code` invocation or message as the delegation guide allows. Read-only questions omit the ticket option; a ticket mentioned by the user stays in the question's context. Operational maintenance may instead identify its existing branches and workspaces directly.
 
@@ -313,8 +338,18 @@ After writing or editing any file under `.plans/` yourself, run `{{ALIGNFIRST}}
 A project has up to three entry points:
 
 - `README.md` — presentation, getting-started procedure…
+{{#openclaw}}
+- `DEVELOPERS.md` — the agent's user, human or AI: you. Read it at DEVELOPERS_PATH.
+{{/openclaw}}
+{{#codingAgent}}
+{{#developers}}
 - `DEVELOPERS.md` — the agent's user, human or AI: you. Read it at DEVELOPERS_PATH.
-- `AGENTS.md` — the agent. When the project's instructions come from its companion, the companion's `.alignfirst.md` replaces it for the agent, and `{{ALIGNFIRST}} context` prints it.
+{{/developers}}
+{{#readme}}
+- `DEVELOPERS.md` — the agent's user, human or AI: you. This project has none, so `README.md` is also your guide, read at DEVELOPERS_PATH.
+{{/readme}}
+{{/codingAgent}}
+- `AGENTS.md` — the agent. When the project's instructions come from its companion, the companion's `.alignfirst-instructions/context.md` replaces it for the agent, and `{{ALIGNFIRST}} context` prints it.
 
 The rest of the documentation (`docs/`, …) addresses everybody.
 
@@ -327,23 +362,17 @@ A project can have documentation files. List them all from PROJECT_PATH, the ful
 {{#openclaw}}
 A project in main-worktree mode (`{{ALIGNDEV}} guide project-workspace-setup`) is the exception to this section: its main worktree leaves the base branch while a working thread holds it, and the edits happen there, on the thread's branch.
 {{/openclaw}}
-{{#codingAgent}}
-A project in main-worktree mode (`{{ALIGNDEV}} guide project-workspace-setup`) is the exception to this section: its main worktree leaves the base branch while a working session holds it, and the edits happen there, on the session's branch.
-{{/codingAgent}}
 
 {{#openclaw}}
 The main worktree at PROJECT_PATH stays on the base branch, except for the repository-onboarding setup branch defined in `{{ALIGNDEV}} guide project-lifecycle`. It is shared across sessions.
 {{/openclaw}}
 {{#codingAgent}}
-The main worktree at PROJECT_PATH stays on the base branch. It is shared across sessions.
+The main worktree at PROJECT_PATH belongs to the user. Edits on the base branch happen only when the user chose to work there.
 {{/codingAgent}}
 
 {{#openclaw}}
 Never edit files while the base branch is checked out, except while bootstrapping a new project before its initial commit as defined in `{{ALIGNDEV}} guide project-lifecycle`.
 {{/openclaw}}
-{{#codingAgent}}
-Never edit files while the base branch is checked out.
-{{/codingAgent}}
 
 Install dependencies in the main worktree from the committed lockfile, without rewriting it: `npm ci` with npm, or the frozen-lockfile install of the project's package manager. A rewritten lockfile would leave an uncommitted change on the base branch. Every prompt to the agent that installs dependencies in the main worktree states this rule.
 
@@ -351,11 +380,18 @@ Running the dev-server from the main worktree is fine.
 
 ### Linked worktrees and other branches
 
+{{#openclaw}}
 A project in main-worktree mode has no linked worktree: its branches are created and checked out in the main worktree with plain `git switch`, and the rule against a hand-made checkout does not apply to it. `git worktree add`/`remove`/`prune` stay out of bounds.
 
 After a project's initial commit exists, editing the codebase happens on another branch in a linked worktree. If you need one and it doesn't exist yet, follow the `{{ALIGNDEV}} guide project-workspace-setup` instructions to set it up.
 
 Worktrees belong to the workspace tooling. Every creation, reuse, and teardown goes through its commands — run the guide `DEVELOPERS.md` points to (`workspace --guide`) to get them. `git worktree add`/`remove`/`prune` and deleting a worktree directory are out of bounds, and so is a hand-made branch checkout outside a workspace. The registry is what makes a worktree visible to the other sessions and to the dev-server tooling.
+{{/openclaw}}
+{{#codingAgent}}
+A project with workspace tooling (Step 2 of `{{ALIGNDEV}} guide project-workspace-setup`) owns its worktrees through it. Every creation, reuse, and teardown goes through the commands its guide (`workspace --guide`) gives. `git worktree add`/`remove`/`prune` and deleting a worktree directory are out of bounds. The registry is what makes a worktree visible to the other sessions and to the dev-server tooling.
+
+Without workspace tooling, create a worktree with `git worktree add` only when the user asks for one.
+{{/codingAgent}}
 
 ### Updating a branch with the base branch
 
@@ -390,7 +426,12 @@ Delegate the sequence to the agent.
 
 ### Status update
 
+{{#openclaw}}
 - Check status from the recorded linked-worktree path. The takeover sync in `{{ALIGNDEV}} guide project-workspace-setup` has already fetched and merged the remote branch, so you are reporting the latest state.
+{{/openclaw}}
+{{#codingAgent}}
+- Check status from the workplace. The sync in `{{ALIGNDEV}} guide project-workspace-setup` has already fetched and merged the remote branch, so you are reporting the latest state.
+{{/codingAgent}}
 - Report where the work stands, drawing on two complementary sources: repo/workflow metadata you gather directly (`git log`/`status`/branch, `gh` PR state), and the ticket's AlignFirst artifacts via `{{ALIGNDEV}} code new --ticket <id> --catchup` (the agent synthesizes the ticket history). Don't browse the source to describe the code; that's a separate delegation.
 
 ### Dev-server while working
@@ -449,15 +490,20 @@ When the user brings up acceptance testing, first be sure who runs it — ask wh
 ### Project rules and docs
 
 {{#openclaw}}
-A project whose `.alignfirst.md` or `DEVELOPERS.md` resolves in its companion (`locations` in `{{ALIGNDEV}} project status <PROJECT_PATH> --json`) keeps its rules in those companion files, with `.alignfirst.md` in place of `AGENTS.md`. The agent edits them in place. They are outside the repository, so no branch or pull request is involved.
+A project whose `.alignfirst-instructions` or `DEVELOPERS.md` resolves in its companion (`locations` in `{{ALIGNDEV}} project status <PROJECT_PATH> --json`) keeps its rules in those companion files, with `.alignfirst-instructions/context.md` in place of `AGENTS.md`. The agent edits them in place. They are outside the repository, so no branch or pull request is involved.
 {{/openclaw}}
 {{#codingAgent}}
-A project whose `.alignfirst.md` or `DEVELOPERS.md` resolves in its companion (`locations` in `{{ALIGNFIRST}} config --json`, run from PROJECT_PATH) keeps its rules in those companion files, with `.alignfirst.md` in place of `AGENTS.md`. The agent edits them in place. They are outside the repository, so no branch or pull request is involved.
+A project whose `.alignfirst-instructions` or `DEVELOPERS.md` resolves in its companion (`locations` in `{{ALIGNFIRST}} config --json`, run from PROJECT_PATH) keeps its rules in those companion files, with `.alignfirst-instructions/context.md` in place of `AGENTS.md`. The agent edits them in place. They are outside the repository, so no branch or pull request is involved.
 {{/codingAgent}}
 
 Two triggers, both edited through the agent:
 
+{{#openclaw}}
 - You learn something non-obvious about how to work in a project — a command, a quirk, a convention not yet written down. Propose capturing it in DEVELOPERS_PATH, ask for confirmation, then have the agent make the edit.
+{{/openclaw}}
+{{#codingAgent}}
+- You learn something non-obvious about how to work in a project — a command, a quirk, a convention not yet written down. Propose capturing it in the project's `DEVELOPERS.md`, created at the repository root when the project has none, ask for confirmation, then have the agent make the edit.
+{{/codingAgent}}
 {{#openclaw}}
 - The user asks to retain a rule for the project. No confirmation needed: the rule goes into both `AGENTS.md` and `DEVELOPERS.md`. When the thread has an active ticket and the rule is simple, add it on the current branch, so the ticket's PR carries it. When the rule is complex or the thread has no ticket, reserve a side ticket (Step 5), set up a workspace on a new branch for the rule, and create a ready pull request.
 {{/openclaw}}
@@ -533,7 +579,12 @@ After creating the MR/PR (via `{{ALIGNDEV}} code`):
 
 Whenever you observe that a PR/MR is merged, delegate the post-merge maintenance to the agent without a protocol:
 
+{{#openclaw}}
 1. Remove the source branch's registered project workspace through the project's workspace tooling, when one exists. In main-worktree mode, switch the main worktree back to the merge target instead.
+{{/openclaw}}
+{{#codingAgent}}
+1. Remove the source branch's registered project workspace through the project's workspace tooling, when one exists. A branch worked on in place stays checked out: the user decides when to leave it.
+{{/codingAgent}}
 2. Refresh the merge target in the main worktree without switching the main worktree away from its base branch. Fetch and fast-forward it, then reinstall dependencies, rebuild, and run new migrations when the project requires them.
 3. Report the removed workspace and refreshed branch.
 
@@ -585,4 +636,9 @@ Creating a project, onboarding a repository to clone, or physically removing a p
 ### Forbidden
 
 - Never force push. Never rebase, reset, or amend a commit that exists on the remote.
+{{#openclaw}}
 - Never touch a worktree outside the workspace tooling. The main worktree of a project in main-worktree mode is the exception.
+{{/openclaw}}
+{{#codingAgent}}
+- Never touch a worktree outside the workspace tooling when the project has it. Without tooling, create or remove a worktree only when the user asks.
+{{/codingAgent}}