aligndev 0.21.0 → 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/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.21.0",
+  "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/playbook.md

@@ -103,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.

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/working-session.md

@@ -349,7 +349,7 @@ A project has up to three entry points:
 - `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.md` replaces it for the agent, and `{{ALIGNFIRST}} context` prints it.
+- `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.
 
@@ -490,10 +490,10 @@ 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: