aligndev 0.18.0 → 0.20.0

package/README.md

@@ -1,168 +1,72 @@
 # aligndev
 
-The AlignFirst Dev Kit CLI. It carries the assistant's playbook, runs a coding agent through [AlignFirst](https://github.com/paleo/alignfirst) protocols, and keeps the inventory of the host's projects and their port ranges. The assistant is an OpenClaw bot, or a coding agent working on one project.
+Autonomous software development. You say what you want; the assistant drives the coding agents and brings you the decisions.
 
-Run `aligndev` through `npx` (`npx -y aligndev …`), or install it with `npm install -g aligndev`. Through `npx`, it runs `alignfirst` through `npx` too, and its help and guides print both commands in that form. A global `aligndev` needs the `alignfirst` CLI on `PATH`: `npm install -g alignfirst`.
+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.
 
-Supported systems: Linux and macOS, and Windows through WSL.
+`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.
 
-## Commands
+## Two Ways to Run the Assistant
 
-```sh
-aligndev code <command> [<options>]      # run a coding agent through AlignFirst protocols
-aligndev project <command> [<options>]   # list projects, check the inventory, claim port ranges
-aligndev guide [<topic>]                 # print the playbook and the guides
-aligndev --help
-aligndev --version
-```
-
-Each command prints its own usage with `--help`.
+**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.
 
-### `aligndev code`
-
-```sh
-aligndev code new --protocol spec --ticket AB-123 --message "Feature description"
-aligndev code resume <sessionId> --protocol plan
-aligndev code new --message "Execute the plan: .plans/AB-123/A2-plan.md"
-aligndev code new --protocol aad --no-ticket --message "Task description"
-aligndev code new --ticket AB-123 --catchup --protocol aad --message-file message.md
-aligndev code status .plans/AB-123/_aligndev/20260829-135529.md
-aligndev code quota
-```
+**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.
 
-The coding agent `aligndev code` launches is **the coder**. Run `aligndev code` from the root of the target project. The project must have a `.plans/` directory, in its repository or in its companion directory.
+Either way, the agent is Claude Code or Codex. A coding-agent assistant launches its own kind by default.
 
-`aligndev code` reads the project's layout from `alignfirst config --json`. Session files go under its `_aligndev` location: `<ticket>/_aligndev/` or `_aligndev/`, below the project's `.plans/` unless the companion holds a separate tree. When some of the project's AlignFirst files exist in its companion, the normal permission modes make the companion writable for the coder (`--add-dir`), and a new session's prompt starts with the `alignfirst context` output.
+## Start in Claude Code or Codex
 
-A new protocol session needs a ticket. `--no-ticket` reserves the next side ticket through `alignfirst ticket --side` and passes it to the coder.
+The project needs an AlignFirst `.plans` directory, in its repository or in a [companion directory](https://github.com/paleo/alignfirst/tree/main/packages/alignfirst#companion-directories). The [setup guide](https://github.com/paleo/alignfirst/blob/main/skills/alignfirst-setup-guide/references/coding-agent-assistant.md) prepares it.
 
-`--catchup` loads the ticket's history (through `alignfirst ticket --catchup`) before the protocol and message. Alone, it returns a short synthesis.
+The agent needs network access and writes outside the repository, so the assistant launches it outside its sandbox: approve that request when it comes.
 
-`--message-file <path>` reads the message from a UTF-8 file, or from stdin with `-`. The prompt reaches the coder through stdin.
+### With the Skill
 
-`aligndev code status` reconciles and shows a run's durable status. It accepts a session file under `_aligndev/` or `<ticket>/_aligndev/` of the `_aligndev` location, or selects the newest run with `--ticket <id>`, `--no-ticket` or `--meta <key>`. If a recorded process is gone, it seals the session file as `status: failed`, `exitReason: terminated`. Linux records also store the process start time to detect pid reuse. Its `contextTokens` line reports what the run left in the coder's context window; a resumed session keeps growing across runs.
-
-`aligndev code quota` shows the selected coding agent's account limits, consumed percentages, and reset times. It works outside a project.
-
-### `aligndev project`
+Install the `aligndev` skill:
 
 ```sh
-aligndev project list [--json] [--root <path>]
-aligndev project doctor [--root <path>]
-aligndev project status <path> [--json] [--root <path>]
-aligndev project init [--root <path>] [--description <text>] [--port-range [<code>=]<first>-<last>]...
-aligndev project free-ports --size <n> [--range <code>] [--json] [--root <path>]
+npx skills add https://github.com/paleo/alignfirst --global --skill aligndev
 ```
 
-A projects directory groups projects and optional nested projects directories. Its `.alignfirst-projects.json` marker holds an optional description and port ranges. A direct child that is a Git main worktree is a project; linked Git worktrees are listed as its workspaces. A child outside Git with a root `.alignfirst.json` is an inventory issue. `list --json` and `status` report each project's companion directory and the location of its AlignFirst files. Two projects sharing one companion directory is an inventory issue.
+Then start a session in the project and invoke `/aligndev` in Claude Code, or `$aligndev` in Codex.
 
-```json
-{
-  "description": "Every project is a direct child of ~/projects.",
-  "portRanges": [
-    { "first": 28000, "last": 28599, "description": "Web projects, exposed through the gateway." },
-    { "code": "local", "first": 29000, "last": 29199, "description": "Desktop apps, never exposed." }
-  ]
-}
-```
-
-`--root` defaults to `projectsRoot` in the config, then to the working directory. `doctor` is a read-only health gate: it succeeds only when discovery completes with no inventory issue.
+### Without a Skill
 
-An older marker carrying `"portRange": { ... }` is rejected; replace the key with `"portRanges": [{ ... }]`. Project configuration in `.alignfirst.json` keeps its singular `portRange` key.
+Add this section to your global agent instructions (`~/.claude/CLAUDE.md`, `~/.codex/AGENTS.md`, or the equivalent):
 
-### `aligndev guide`
+```markdown
+## Aligndev
 
-```sh
-aligndev guide [<topic>] [--root <path>]
+When the user mentions **aligndev**, follow the `aligndev` playbook if it is already in context. Otherwise, run `npx -y aligndev guide` and follow it.
 ```
 
-Each topic renders the variant of the configured `platform`.
+Then ask your session to work with aligndev.
 
-| Topic | Output | Platforms |
-|-------|--------|-----------|
-| (none) | The playbook dispatcher. | both |
-| `working-session` | The work procedure: a thread under OpenClaw, the conversation for a coding agent. | both |
-| `project-workspace-setup`, `consultation` | Runbooks. | both |
-| `code` | The delegation guide. | both |
-| `channel-handling` | The channel and DM procedure. | `openclaw` |
-| `project-lifecycle` | The runbook to create, onboard or remove a project. | `openclaw` |
-| `slack-message-tool`, `discord-message-tool` | Extended `message` references. | `openclaw` |
-| `project` | The projects guide, followed by the directory sections when the root carries a marker. `--root` overrides `projectsRoot`. | `openclaw` |
+### Requirements
 
-Under `openclaw`, the playbook topics require `projectsRoot`.
+- Node.js 22.11 or later. The assistant runs `aligndev` through `npx`, so there is nothing to install.
+- Claude Code or Codex installed and logged in: `claude` then `/login`, or `codex login`.
+- Linux or macOS, or Windows through WSL.
 
 ## Configuration
 
-`aligndev` reads one file, `~/.config/alignfirst/aligndev.config.json`. The path is fixed: no environment variable overrides it. `aligndev code` and `aligndev guide` require it, `--help` included. Without it, they fail with an error naming the path and the required keys. `aligndev project`, `aligndev --help` and `aligndev --version` run without it.
-
-```json
-{
-  "platform": "openclaw",
-  "projectsRoot": "~/projects",
-  "code": {
-    "agent": "claude",
-    "models": ["opus", "sonnet"],
-    "skipPermissions": false,
-    "unset": ["ANTHROPIC_API_KEY"]
-  }
-}
-```
-
-A coding agent acting as the assistant needs only the required keys:
+`~/.alignfirst/aligndev.config.json` is optional. Without it, every key takes its default. For example, to launch Codex as the agent, whatever runs the assistant:
 
 ```json
 {
-  "platform": "codingAgent",
   "code": { "agent": "codex" }
 }
 ```
 
-- `platform` — required. Selects the variant of every `aligndev guide` topic: `openclaw` for an OpenClaw assistant, `codingAgent` for a coding agent acting as the assistant.
-- `projectsRoot` — the default projects directory of `aligndev project` and `aligndev guide project`. Required by the `openclaw` playbook. `~/` expands to the home directory; a relative path resolves against the config file's directory.
-- `code.agent` — required. The coder: `claude` or `codex`.
-- `code.models` — replaces the selected agent's accepted models.
-- `code.skipPermissions` — `true` selects each CLI's dangerous permission-bypass flag. Default: `false`.
-- `code.unset` — environment variables stripped from the coder's environment. `aligndev code` always strips the assistant session's identity variables first (`CLAUDECODE`, `CLAUDE_CODE_SESSION_ID`, `CODEX_THREAD_ID`, …), whatever the agent.
-
-Unknown keys are rejected. An unreadable file, invalid JSON or an invalid value fails every command that loads the config, with an error naming the file.
-
-Companion directories are declared in `~/.config/alignfirst/companions.json`, which the `alignfirst` CLI reads for both tools. See [its README](https://github.com/paleo/alignfirst/tree/main/packages/alignfirst#companion-directories).
-
-## Execution model
-
-`aligndev code` runs the coder as a direct **foreground** child of its own process. It streams a live transcript to stdout and to a per-run session file, whose frontmatter status goes from `running` to `succeeded` or `failed`, and blocks until the coder exits. It never backgrounds or detaches itself.
-
-Coding runs can be very long, so the caller always runs `aligndev code` as a background task and owns the backgrounding, as `aligndev guide code` prescribes:
-
-- Under OpenClaw, the assistant invokes it through the `exec` tool with `background: true` and `timeoutSeconds: 0`, and chains `openclaw system event --mode now --session-key <key>` onto the command.
-- A coding-agent assistant starts it with its own background-execution facility, with no time limit, and outside its sandbox. When the agent wakes the session as the command exits, as Claude Code does, the assistant handles the completion on that wake. Otherwise, the assistant checks its pending runs at the start of the next user turn.
-
-The completion turn locates the session file with `aligndev code status` and reads the result. The session file is the durable result handoff: frontmatter `sessionId` and status, and the `---- Result ----` block.
-
-If `aligndev code` is terminated, its signal handlers seal the session file (`status: failed`, `exitReason: terminated`), then send `SIGTERM` to the coder. After a short grace period, a `SIGKILL` guarantees no orphan is left behind. Only a `SIGKILL` of `aligndev` itself can leave a stale `running` status, which the next `status` call seals.
-
-When the coding agent's session on the host is missing or expired, `aligndev code` detects the authentication failure in its stream, seals the session file with `exitReason: auth_required`, and exits `2` with a one-line stderr message.
-
-## Coding agents
-
-Install the selected CLI and authenticate it on the host: run `claude`, then `/login`, for Claude Code; run `codex login` for Codex.
-
-Normal runs use Claude's `--permission-mode auto` or Codex's `--sandbox workspace-write`.
-
-Claude's default model list is `fable`, `opus`, `sonnet`, `haiku`. Codex's is `astra`, `sol`, `terra`, `luna`; `aligndev code` resolves a selected Codex alias against `codex debug models --bundled`. Set `code.models` to narrow the list or to advertise an explicit Codex slug such as `gpt-5.6-terra`.
-
-Session files record `agent`. A session resumes only with the same selected agent. Agentless legacy sessions stay readable but require a new session.
-
-## The `aligndev` skill
-
-The `aligndev` agent skill makes a Claude Code or Codex session the assistant of the project it runs in. Invoked as `/aligndev` in Claude Code, or `$aligndev` in Codex, it loads the playbook through `npx -y aligndev guide`, which needs `platform: "codingAgent"` in the config. Install it:
-
-```sh
-npx skills add https://github.com/paleo/alignfirst --global --skill aligndev
-```
+- `platform` — `codingAgent` (default) for a coding-agent assistant, `openclaw` for an OpenClaw bot.
+- `projectsRoot` — the projects directory of an OpenClaw host. Required by `openclaw`. `~/` expands to the home directory; a relative path resolves against `~/.alignfirst/`.
+- `code.agent` — the agent: `claude` or `codex`. Default: the coding agent that runs the assistant, detected from its environment. Set it to launch the other one, or when both are detected, as with Codex in a VS Code terminal where the Claude Code extension is installed.
+- `code.models` — the models the assistant may choose from. Default: Claude's `fable`, `opus`, `sonnet`, `haiku`, or Codex's `astra`, `sol`, `terra`, `luna`.
+- `code.skipPermissions` — `true` runs Claude Code with `--dangerously-skip-permissions` instead of `--permission-mode auto`, and Codex with `--dangerously-bypass-approvals-and-sandbox` instead of `--sandbox workspace-write`. Default: `false`.
+- `code.unset` — environment variables to hide from the agent, such as an API key meant for another tool on the host.
 
-The setup guide's [coding-agent assistant reference](https://github.com/paleo/alignfirst/blob/main/skills/alignfirst-setup-guide/references/coding-agent-assistant.md) covers the project, the configuration and the sandbox.
+Unknown keys and invalid values are errors.
 
-## Port claims
+## Under the Hood
 
-Run `aligndev project free-ports --size <n>` with the block size required by the project's workspace scheme: `perWorkspace × maxWorkspaces`. A marker entry without a code is the default range. Pass `--range <code>` to select a coded range. The setup guide writes the returned block as `portRange` in the project's `.alignfirst.json`.
+`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).

package/dist/cli.js

@@ -5,7 +5,7 @@ import { CODING_AGENTS } from "./code/coding-agent.js";
 import { resolveExecutableModel } from "./code/models.js";
 import { readQuota } from "./code/quota.js";
 import { resolveCommandForms } from "./command-form.js";
-import { loadConfig, missingConfigMessage, PLATFORMS } from "./config.js";
+import { loadConfig, PLATFORMS } from "./config.js";
 import { errorMessage } from "./errors.js";
 import { runGuide } from "./guide/guide-cli.js";
 import { runProject } from "./project/project-cli.js";
@@ -25,23 +25,18 @@ export async function main(options) {
         ctx.stderr.write(`${error}\n\n${renderHelp(ctx.forms.aligndev)}`);
         return 1;
     }
-    let config;
     try {
-        config = loadConfig(ctx.home);
+        const config = loadConfig(ctx.home);
+        if (command === "project")
+            return runProject(tokens, config, ctx);
+        if (command === "code")
+            return await runCode(tokens, config, ctx);
+        return runGuide(tokens, config, ctx);
     }
     catch (error) {
         ctx.stderr.write(`${errorMessage(error)}\n`);
         return 1;
     }
-    if (command === "project")
-        return runProject(tokens, config, ctx);
-    if (config === undefined) {
-        ctx.stderr.write(`${missingConfigMessage(ctx.home)}\n`);
-        return 1;
-    }
-    if (command === "code")
-        return runCode(tokens, config, ctx);
-    return runGuide(tokens, config, ctx);
 }
 function renderHelp(aligndev) {
     const usage = renderUsageRows([
@@ -61,8 +56,9 @@ ${usage}
 
 Run \`${aligndev} <command> --help\` for the usage of a command.
 
-Config: ~/.config/alignfirst/aligndev.config.json, with "platform" (${PLATFORMS.join(" or ")}) and
-"code.agent" (${CODING_AGENTS.join(" or ")}). \`${aligndev} code\` and \`${aligndev} guide\` require it.
+Config (optional): ~/.alignfirst/aligndev.config.json. "platform" (${PLATFORMS.join(" or ")})
+defaults to codingAgent. "code.agent" (${CODING_AGENTS.join(" or ")}) defaults to the coding agent that
+runs aligndev, detected from its environment.
 `;
 }
 // Each row is a command, optionally followed by its description in an aligned column.

package/dist/code/code-cli.d.ts

@@ -1,5 +1,5 @@
 import type { CommandForms } from "../command-form.js";
-import type { AligndevConfig, CodeConfig } from "../config.js";
+import { type CodeConfig, type LoadedConfig } from "../config.js";
 import type { Output } from "../output.js";
 import { type ProjectReport } from "../project/layout.js";
 import { type CodingAgent } from "./coding-agent.js";
@@ -51,7 +51,7 @@ export interface SessionArgs {
     model?: string;
     meta?: string;
 }
-export declare function runCode(tokens: string[], config: AligndevConfig, ctx: CodeContext): Promise<number>;
+export declare function runCode(tokens: string[], config: LoadedConfig, ctx: CodeContext): Promise<number>;
 export declare function parseCodeArgs(tokens: string[], aligndev: string): CodeCommand;
 export declare function validateSessionArgs(args: SessionArgs, models: readonly string[]): string | undefined;
 export declare function checkLaunchGuards(args: SessionArgs, agent: CodingAgent, realCwd: string, records: SessionRecord[]): string | undefined;

package/dist/code/code-cli.js

@@ -2,6 +2,7 @@ import { existsSync, readFileSync, realpathSync } from "node:fs";
 import { extname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { parseArgs } from "node:util";
 import { loadCatchup, loadContext, openTicket, reserveSideTicket } from "../alignfirst-cli.js";
+import { resolveCodeConfig } from "../config.js";
 import { errorMessage } from "../errors.js";
 import { companionInUse, readProjectReport, } from "../project/layout.js";
 import { createAgentAdapter } from "./coding-agent.js";
@@ -22,7 +23,7 @@ const SESSION_OPTIONS = {
     meta: { type: "string" },
     help: { type: "boolean", short: "h", default: false },
 };
-// Items whose companion copy the coder may edit: the companion becomes a writable directory.
+// Items whose companion copy the agent may edit: the companion becomes a writable directory.
 const WRITABLE_COMPANION_ITEMS = [
     ".alignfirst.json",
     ".alignfirst.md",
@@ -30,7 +31,7 @@ const WRITABLE_COMPANION_ITEMS = [
     "docs",
     ".plans",
 ];
-// Items the coder would not find in the repository: a new session gets `alignfirst context`.
+// Items the agent would not find in the repository: a new session gets `alignfirst context`.
 const CONTEXT_COMPANION_ITEMS = [
     ".alignfirst.json",
     ".alignfirst.md",
@@ -44,7 +45,7 @@ export async function runCode(tokens, config, ctx) {
         const command = parseCodeArgs(tokens, ctx.forms.aligndev);
         if (command.kind === "status")
             return showStatus(ctx, command.target);
-        const { code } = config;
+        const code = resolveCodeConfig(config, ctx.env);
         if (command.kind === "quota")
             return await showQuota(ctx, code);
         const models = resolveModels(code.agent, code.models);
@@ -610,8 +611,9 @@ Options (new, resume):
 
 ${requires}
 
-Config (~/.config/alignfirst/aligndev.config.json):
-  code.agent            Required coding agent: claude or codex (selected: ${agent}).
+Config (~/.alignfirst/aligndev.config.json):
+  code.agent            Coding agent: claude or codex (selected: ${agent}). Defaults to the coding
+                        agent that runs aligndev.
   code.models           List replacing the models accepted by --model.
   code.skipPermissions  true to run the coding agent with permission prompts disabled.
   code.unset            Env vars to strip from the coding agent child.

package/dist/code/coding-agent.d.ts

@@ -2,3 +2,4 @@ import type { AgentAdapter } from "./run-agent.js";
 export declare const CODING_AGENTS: readonly ["claude", "codex"];
 export type CodingAgent = (typeof CODING_AGENTS)[number];
 export declare function createAgentAdapter(agent: CodingAgent): AgentAdapter;
+export declare function detectCodingAgents(env: NodeJS.ProcessEnv): CodingAgent[];

package/dist/code/coding-agent.js

@@ -4,3 +4,13 @@ export const CODING_AGENTS = ["claude", "codex"];
 export function createAgentAdapter(agent) {
     return agent === "claude" ? createClaudeAdapter() : createCodexAdapter();
 }
+// Each coding agent marks the commands it runs: Claude Code sets `CLAUDECODE=1` (documented), and
+// Codex sets `CODEX_THREAD_ID`.
+export function detectCodingAgents(env) {
+    const detected = [];
+    if (env.CLAUDECODE === "1")
+        detected.push("claude");
+    if (env.CODEX_THREAD_ID !== undefined && env.CODEX_THREAD_ID !== "")
+        detected.push("codex");
+    return detected;
+}

package/dist/code/run-agent.js

@@ -2,7 +2,7 @@ import { spawn } from "node:child_process";
 import { appendTranscript, applyCompletion } from "./session-file.js";
 const TERMINATION_GRACE_MS = 2000;
 // A coding-agent session exports its own identity to every command it runs; when the assistant
-// runs in one, the coder must not inherit it.
+// runs in one, the agent it launches must not inherit it.
 const ASSISTANT_SESSION_VARIABLES = [
     "CLAUDECODE",
     "CLAUDE_CODE_SESSION_ID",

package/dist/config.d.ts

@@ -1,22 +1,25 @@
 import { type CodingAgent } from "./code/coding-agent.js";
 export declare const PLATFORMS: readonly ["openclaw", "codingAgent"];
 export type Platform = (typeof PLATFORMS)[number];
-export interface AligndevConfig {
+export interface LoadedConfig {
     path: string;
     platform: Platform;
     projectsRoot?: ProjectsRoot;
-    code: CodeConfig;
+    code: LoadedCodeConfig;
 }
 export interface ProjectsRoot {
     path: string;
     written: string;
 }
-export interface CodeConfig {
-    agent: CodingAgent;
+export interface LoadedCodeConfig {
+    agent?: CodingAgent;
     models?: string[];
     skipPermissions: boolean;
     unset: string[];
 }
-export declare function loadConfig(home: string): AligndevConfig | undefined;
-export declare function missingConfigMessage(home: string): string;
-export declare function requireProjectsRoot(config: AligndevConfig): ProjectsRoot;
+export interface CodeConfig extends LoadedCodeConfig {
+    agent: CodingAgent;
+}
+export declare function loadConfig(home: string): LoadedConfig;
+export declare function resolveCodeConfig(config: LoadedConfig, env: NodeJS.ProcessEnv): CodeConfig;
+export declare function requireProjectsRoot(config: LoadedConfig): ProjectsRoot;

package/dist/config.js

@@ -1,45 +1,41 @@
 import { existsSync, readFileSync } from "node:fs";
 import { dirname, isAbsolute, join, resolve } from "node:path";
 import { type } from "arktype";
-import { CODING_AGENTS } from "./code/coding-agent.js";
+import { CODING_AGENTS, detectCodingAgents } from "./code/coding-agent.js";
 import { errorMessage } from "./errors.js";
 export const PLATFORMS = ["openclaw", "codingAgent"];
 const codeSchema = type({
     "+": "reject",
-    agent: type.enumerated(...CODING_AGENTS),
+    "agent?": type.enumerated(...CODING_AGENTS),
     "models?": "string[]",
     "skipPermissions?": "boolean",
     "unset?": "string[]",
 });
 const configSchema = type({
     "+": "reject",
-    platform: type.enumerated(...PLATFORMS),
+    "platform?": type.enumerated(...PLATFORMS),
     "projectsRoot?": "string > 0",
-    code: codeSchema,
+    "code?": codeSchema,
 });
-// An absent file is a normal state: a machine where aligndev is not configured.
+// An absent file is a normal state: every key takes its default.
 export function loadConfig(home) {
-    const path = configPath(home);
-    if (!existsSync(path))
-        return;
-    const value = parseConfigFile(path);
+    const path = join(home, ".alignfirst", "aligndev.config.json");
+    const value = existsSync(path) ? parseConfigFile(path) : {};
+    const code = value.code ?? {};
     return {
         path,
-        platform: value.platform,
+        platform: value.platform ?? "codingAgent",
         ...(value.projectsRoot === undefined
             ? {}
             : { projectsRoot: resolveProjectsRoot(value.projectsRoot, home, path) }),
         code: {
-            agent: value.code.agent,
-            ...(value.code.models === undefined ? {} : { models: value.code.models }),
-            skipPermissions: value.code.skipPermissions ?? false,
-            unset: value.code.unset ?? [],
+            ...(code.agent === undefined ? {} : { agent: code.agent }),
+            ...(code.models === undefined ? {} : { models: code.models }),
+            skipPermissions: code.skipPermissions ?? false,
+            unset: code.unset ?? [],
         },
     };
 }
-function configPath(home) {
-    return join(home, ".config", "alignfirst", "aligndev.config.json");
-}
 function parseConfigFile(path) {
     let value;
     try {
@@ -61,9 +57,18 @@ function resolveProjectsRoot(written, home, path) {
         return { path: join(home, written.slice(2)), written };
     return { path: isAbsolute(written) ? written : resolve(dirname(path), written), written };
 }
-export function missingConfigMessage(home) {
-    return (`Error: no aligndev config at ${configPath(home)}. Create it with "platform" ` +
-        `(${PLATFORMS.join(" or ")}) and "code.agent" (${CODING_AGENTS.join(" or ")}).`);
+// The configured `code.agent` wins; otherwise, the coding agent that runs aligndev.
+export function resolveCodeConfig(config, env) {
+    const { agent } = config.code;
+    if (agent !== undefined)
+        return { ...config.code, agent };
+    const detected = detectCodingAgents(env);
+    if (detected.length === 1)
+        return { ...config.code, agent: detected[0] };
+    const problem = detected.length === 0
+        ? "no coding agent detected: run aligndev from Claude Code or Codex, or set"
+        : "both Claude Code and Codex detected: set";
+    throw new Error(`Error: ${problem} "code.agent" (${CODING_AGENTS.join(" or ")}) in ${config.path}.`);
 }
 export function requireProjectsRoot(config) {
     if (config.projectsRoot !== undefined)

package/dist/guide/code-guide.js

@@ -11,7 +11,7 @@ export function renderCodeGuide(platform, agent, models, forms) {
             ? "The project must be prepared for AlignFirst. `npx -y aligndev` runs the `alignfirst` CLI through `npx`."
             : "The project must be prepared for AlignFirst, with the `alignfirst` CLI installed (`npm install -g alignfirst`).",
         ALIGNFIRST_USE: forms.viaNpx
-            ? "`npx -y aligndev code` runs the `alignfirst` CLI through `npx`, and so does the coder: it runs `npx -y alignfirst guide <protocol>` in the project."
-            : "`aligndev code` requires the `alignfirst` CLI on `PATH`. The coder runs `alignfirst guide <protocol>` in the project, so the protocols come from the installed CLI.",
+            ? "`npx -y aligndev code` runs the `alignfirst` CLI through `npx`, and so does the agent: it runs `npx -y alignfirst guide <protocol>` in the project."
+            : "`aligndev code` requires the `alignfirst` CLI on `PATH`. The agent runs `alignfirst guide <protocol>` in the project, so the protocols come from the installed CLI.",
     });
 }

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

@@ -1,3 +1,3 @@
-import { type AligndevConfig } from "../config.js";
+import { type LoadedConfig } from "../config.js";
 import { type ProjectsCallerContext } from "../project/project-cli.js";
-export declare function runGuide(tokens: string[], config: AligndevConfig, ctx: ProjectsCallerContext): number;
+export declare function runGuide(tokens: string[], config: LoadedConfig, ctx: ProjectsCallerContext): number;

package/dist/guide/guide-cli.js

@@ -1,6 +1,6 @@
 import { parseArgs } from "node:util";
 import { resolveModels } from "../code/models.js";
-import { PLATFORMS, requireProjectsRoot } from "../config.js";
+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";
@@ -53,16 +53,16 @@ ${playbookTopics.join("\n")}
 }
 function renderTopic(args, config, ctx) {
     if (args.topic === "code")
-        return renderCodeTopic(config, ctx.forms);
+        return renderCodeTopic(config, ctx);
     if (args.topic === "project" && config.platform === "openclaw") {
         return renderProjectsGuideForRoot({ ...ctx, projectsRoot: config.projectsRoot }, args.root);
     }
     return renderPlaybookTopic(args.topic, config, ctx.forms);
 }
-function renderCodeTopic(config, forms) {
-    const { code } = config;
+function renderCodeTopic(config, ctx) {
+    const code = resolveCodeConfig(config, ctx.env);
     const models = resolveModels(code.agent, code.models);
-    return renderCodeGuide(config.platform, code.agent, models, forms);
+    return renderCodeGuide(config.platform, code.agent, models, ctx.forms);
 }
 function renderPlaybookTopic(topic, config, forms) {
     if (topic !== undefined)

package/dist/project/project-cli.d.ts

@@ -1,5 +1,5 @@
 import type { CommandForms } from "../command-form.js";
-import type { AligndevConfig, ProjectsRoot } from "../config.js";
+import type { LoadedConfig, ProjectsRoot } from "../config.js";
 import type { Output } from "../output.js";
 export interface ProjectsCallerContext {
     cwd: string;
@@ -13,5 +13,5 @@ export interface ProjectsCallerContext {
 export interface ProjectsContext extends ProjectsCallerContext {
     projectsRoot?: ProjectsRoot;
 }
-export declare function runProject(tokens: string[], config: AligndevConfig | undefined, caller: ProjectsCallerContext): number;
+export declare function runProject(tokens: string[], config: LoadedConfig, caller: ProjectsCallerContext): number;
 export declare function renderProjectsGuideForRoot(ctx: ProjectsContext, rootOption: string | undefined): string;

package/dist/project/project-cli.js

@@ -10,7 +10,7 @@ import { findFreeBlock } from "./ports.js";
 import { renderPortRangeJson, renderProjectDoctor, renderProjectDoctorFailure, renderProjectList, renderProjectListJson, renderProjectStatus, renderProjectStatusJson, } from "./render.js";
 import { getProjectStatus } from "./status.js";
 export function runProject(tokens, config, caller) {
-    const ctx = { ...caller, projectsRoot: config?.projectsRoot };
+    const ctx = { ...caller, projectsRoot: config.projectsRoot };
     try {
         return runProjectCommand(ctx, parseProjectsArgs(tokens));
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aligndev",
-  "version": "0.18.0",
+  "version": "0.20.0",
   "license": "CC0-1.0",
   "author": "Thomas MUR",
   "description": "The AlignFirst Dev Kit CLI: the assistant's playbook, coding-agent delegation, and project inventory.",
@@ -22,7 +22,7 @@
     "directory": "packages/aligndev"
   },
   "engines": {
-    "node": ">=24.16.0"
+    "node": ">=22.11.0"
   },
   "packageManager": "npm@11.19.0",
   "type": "module",