aligndev 0.22.1 → 0.23.0-preview.topics.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -68,17 +68,18 @@ Then ask your session to work with aligndev.
68
68
 
69
69
  ## Configuration
70
70
 
71
- `~/.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:
71
+ `~/.alignfirst/aligndev.settings.json` is optional. Without it, every key takes its default. For example, to launch Codex as the agent, whatever runs the assistant, with `sol` as the default model:
72
72
 
73
73
  ```json
74
74
  {
75
- "code": { "agent": "codex" }
75
+ "code": { "agent": "codex", "defaultModel": "sol" }
76
76
  }
77
77
  ```
78
78
 
79
79
  - `platform` — `codingAgent` (default) for a coding-agent assistant, `openclaw` for an OpenClaw bot.
80
80
  - `projectsRoot` — the projects directory of an OpenClaw host. Required by `openclaw`. `~/` expands to the home directory; a relative path resolves against `~/.alignfirst/`.
81
81
  - `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.
82
+ - `code.defaultModel` — the model of a new session started without `--model`, one of `code.models`. Default: the agent's own default. A resumed session keeps its model.
82
83
  - `code.models` — the models the assistant may choose from. Default: Claude's `fable`, `opus`, `sonnet`, `haiku`, or Codex's `astra`, `sol`, `terra`, `luna`.
83
84
  - `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`.
84
85
  - `code.unset` — environment variables to hide from the agent, such as an API key meant for another tool on the host.
@@ -102,7 +103,7 @@ Install the setup skill where your agent will assemble the deployment's private
102
103
  npx -y skills add https://github.com/paleo/alignfirst --global --skill alignfirst-setup-guide
103
104
  ```
104
105
 
105
- 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`.
106
+ 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 context` section in its `AGENTS.md`, an optional work-files repository, docmap, isolated workspaces and a project-specific `DEVELOPERS.md`.
106
107
 
107
108
  ## Under the Hood
108
109
 
package/dist/cli.js CHANGED
@@ -56,7 +56,7 @@ ${usage}
56
56
 
57
57
  Run \`${aligndev} <command> --help\` for the usage of a command.
58
58
 
59
- Config (optional): ~/.alignfirst/aligndev.config.json. "platform" (${PLATFORMS.join(" or ")})
59
+ Config (optional): ~/.alignfirst/aligndev.settings.json. "platform" (${PLATFORMS.join(" or ")})
60
60
  defaults to codingAgent. "code.agent" (${CODING_AGENTS.join(" or ")}) defaults to the coding agent that
61
61
  runs aligndev, detected from its environment.
62
62
  `;
@@ -1,4 +1,4 @@
1
- import { existsSync, readFileSync, realpathSync } from "node:fs";
1
+ import { existsSync, mkdirSync, readFileSync, realpathSync } from "node:fs";
2
2
  import { extname, isAbsolute, join, relative, resolve, sep } from "node:path";
3
3
  import { parseArgs } from "node:util";
4
4
  import { loadCatchup, loadContext, openTicket, reserveSideTicket } from "../alignfirst-cli.js";
@@ -23,14 +23,6 @@ const SESSION_OPTIONS = {
23
23
  meta: { type: "string" },
24
24
  help: { type: "boolean", short: "h", default: false },
25
25
  };
26
- // Items whose companion copy the agent may edit: the companion becomes a writable directory.
27
- const WRITABLE_COMPANION_ITEMS = [
28
- ".alignfirst.json",
29
- ".alignfirst-instructions",
30
- "DEVELOPERS.md",
31
- "docs",
32
- ".plans",
33
- ];
34
26
  // Items the agent would not find in the repository: a new session gets `alignfirst context`.
35
27
  const CONTEXT_COMPANION_ITEMS = [
36
28
  ".alignfirst.json",
@@ -362,12 +354,13 @@ async function runSession(args, code, ctx) {
362
354
  const contextContent = args.resume === undefined && companionInUse(report, CONTEXT_COMPANION_ITEMS)
363
355
  ? loadContext(alignfirstCommand, cwd, env)
364
356
  : undefined;
357
+ const model = selectModel(args, code, records);
365
358
  const sessionFilePath = resolveSessionFilePath(tree.sessionsDir, ticket, now);
366
- writeInitialSessionFile(sessionFilePath, buildFrontmatter(args, agent, now, tree.cwd, ticket));
359
+ writeInitialSessionFile(sessionFilePath, buildFrontmatter({ args, agent, model, now, realCwd: tree.cwd, ticket }));
367
360
  stdout.write(`Session file: ${displayPath(tree.cwd, sessionFilePath)}\n\n`);
368
361
  let executableModel;
369
362
  try {
370
- executableModel = await modelResolver(agent, args.model, {
363
+ executableModel = await modelResolver(agent, model, {
371
364
  cwd,
372
365
  env: buildAgentEnv(env, code.unset),
373
366
  });
@@ -384,7 +377,7 @@ async function runSession(args, code, ctx) {
384
377
  stderr.write(`${message}\n`);
385
378
  return 1;
386
379
  }
387
- const result = await runAgent(buildRunConfig({
380
+ const runConfig = buildRunConfig({
388
381
  args,
389
382
  code,
390
383
  report,
@@ -396,7 +389,9 @@ async function runSession(args, code, ctx) {
396
389
  catchupContent,
397
390
  contextContent,
398
391
  alignfirst: forms.alignfirst,
399
- }), createAgentAdapter(agent), stdout);
392
+ });
393
+ createMissingCompanion(report, runConfig.additionalDirectories);
394
+ const result = await runAgent(runConfig, createAgentAdapter(agent), stdout);
400
395
  if (args.resume === undefined && result.sessionId) {
401
396
  stdout.write(`\nSession ID: ${result.sessionId}\n`);
402
397
  }
@@ -421,7 +416,7 @@ export function checkLaunchGuards(args, agent, realCwd, records) {
421
416
  return (`Error: session ${args.resume} is still running (pid ${running.frontmatter.pid}); ` +
422
417
  "wait for it to finish or kill it.");
423
418
  }
424
- const latest = [...matches].sort((a, b) => b.frontmatter.startedAt.localeCompare(a.frontmatter.startedAt))[0];
419
+ const latest = latestRecord(matches);
425
420
  if (latest.frontmatter.agent === null) {
426
421
  return (`Error: session ${args.resume} predates agent-aware sessions and cannot be resumed; ` +
427
422
  "start a new session.");
@@ -441,6 +436,10 @@ export function checkLaunchGuards(args, agent, realCwd, records) {
441
436
  }
442
437
  return;
443
438
  }
439
+ // The newest record of a non-empty list: a resumed session has one record per run.
440
+ function latestRecord(records) {
441
+ return [...records].sort((a, b) => b.frontmatter.startedAt.localeCompare(a.frontmatter.startedAt))[0];
442
+ }
444
443
  function unknownResumeError(resume, records) {
445
444
  if (records.length === 0) {
446
445
  return `Error: unknown session id ${resume}; no session records exist.`;
@@ -485,19 +484,31 @@ function inferTicketFromMessage(message) {
485
484
  return;
486
485
  return [...candidates][0];
487
486
  }
488
- function buildFrontmatter(args, agent, now, realCwd, ticket) {
487
+ // `--model` wins. Otherwise a new session takes `code.defaultModel`, and a resume keeps the model
488
+ // of its latest run, unchecked against the current allowlist. `undefined` leaves the agent's
489
+ // default.
490
+ function selectModel(args, code, records) {
491
+ if (args.model !== undefined)
492
+ return args.model;
493
+ if (args.resume === undefined)
494
+ return code.defaultModel;
495
+ const runs = records.filter((r) => r.frontmatter.sessionId === args.resume);
496
+ return latestRecord(runs).frontmatter.model ?? undefined;
497
+ }
498
+ function buildFrontmatter(input) {
499
+ const { args, now, ticket } = input;
489
500
  return {
490
501
  status: "running",
491
- agent,
502
+ agent: input.agent,
492
503
  protocol: args.protocol ?? null,
493
504
  ticket: ticket ?? null,
494
- model: args.model ?? null,
505
+ model: input.model ?? null,
495
506
  sessionId: null,
496
507
  command: formatCommand(args),
497
508
  meta: args.meta ?? null,
498
509
  pid: process.pid,
499
510
  pidStartTime: readPidStartTime(process.pid),
500
- cwd: realCwd,
511
+ cwd: input.realCwd,
501
512
  startedAt: now.toISOString(),
502
513
  endedAt: null,
503
514
  exitReason: null,
@@ -548,15 +559,19 @@ export function buildRunConfig(input) {
548
559
  resume: args.resume,
549
560
  executableModel: input.executableModel,
550
561
  skipPermissions: code.skipPermissions,
551
- additionalDirectories: !code.skipPermissions &&
552
- report.companion !== null &&
553
- companionInUse(report, WRITABLE_COMPANION_ITEMS)
554
- ? [report.companion.dir]
555
- : [],
562
+ additionalDirectories: !code.skipPermissions && report.companion !== null ? [report.companion.dir] : [],
556
563
  unset: code.unset,
557
564
  env: input.env,
558
565
  };
559
566
  }
567
+ // A registered companion becomes writable before its directory exists: create it for the agent.
568
+ function createMissingCompanion(report, additionalDirectories) {
569
+ const { companion } = report;
570
+ if (companion === null || companion.exists || !additionalDirectories.includes(companion.dir)) {
571
+ return;
572
+ }
573
+ mkdirSync(companion.dir, { recursive: true });
574
+ }
560
575
  function renderHelp(agent, models, forms) {
561
576
  const { aligndev, alignfirst } = forms;
562
577
  const permissionMode = agent === "claude"
@@ -603,23 +618,25 @@ Options (new, resume):
603
618
  --catchup Load the ticket history before the message. new only.
604
619
  -m, --message "..." Message to send. Required for spec/aad, or without protocol/catchup.
605
620
  --message-file <path> Read the message from a UTF-8 file, or stdin with -. Exclusive with -m.
606
- --model <model> Model for a new session: one of ${models.join(", ")}. Omit to use the
607
- default model.
621
+ --model <model> One of ${models.join(", ")}. A new session defaults to
622
+ code.defaultModel, else to the coding agent's default. A resume keeps the
623
+ session's model.
608
624
  --meta "..." Opaque handoff string, stored verbatim in the session file frontmatter
609
625
  (\`meta:\`). aligndev never interprets it; a later reader of the session file
610
626
  (e.g. the caller reporting the run's outcome) can use it.
611
627
 
612
628
  ${requires}
613
629
 
614
- Config (~/.alignfirst/aligndev.config.json):
630
+ Config (~/.alignfirst/aligndev.settings.json):
615
631
  code.agent Coding agent: claude or codex (selected: ${agent}). Defaults to the coding
616
632
  agent that runs aligndev.
633
+ code.defaultModel Default model of a new session, one of the models accepted by --model.
617
634
  code.models List replacing the models accepted by --model.
618
635
  code.skipPermissions true to run the coding agent with permission prompts disabled.
619
636
  code.unset Env vars to strip from the coding agent child.
620
637
 
621
638
  Selected-agent permissions: ${permissionMode}
622
- The normal mode also makes the project's companion directory writable when it is in use.
639
+ The normal mode also makes the project's companion directory writable.
623
640
  ${modelBehavior}
624
641
 
625
642
  ${aligndev} code runs a coding agent in the foreground and blocks until it finishes, streaming the
@@ -81,7 +81,7 @@ function runCodexModelCatalog(context) {
81
81
  function codexAliasError(alias, error) {
82
82
  const detail = error instanceof Error ? error.message : String(error);
83
83
  return (`Unable to resolve Codex model alias ${JSON.stringify(alias)}: ${detail}. ` +
84
- "Update the Codex CLI, or set `code.models` in the aligndev config to an explicit full model " +
84
+ "Update the Codex CLI, or set `code.models` in the aligndev settings to an explicit full model " +
85
85
  "slug and select that value.");
86
86
  }
87
87
  function isRecord(value) {
package/dist/config.d.ts CHANGED
@@ -13,6 +13,7 @@ export interface ProjectsRoot {
13
13
  }
14
14
  export interface LoadedCodeConfig {
15
15
  agent?: CodingAgent;
16
+ defaultModel?: string;
16
17
  models?: string[];
17
18
  skipPermissions: boolean;
18
19
  unset: string[];
package/dist/config.js CHANGED
@@ -1,11 +1,13 @@
1
1
  import { existsSync, readFileSync } from "node:fs";
2
2
  import { dirname, isAbsolute, join, resolve } from "node:path";
3
3
  import { CODING_AGENTS, detectCodingAgents } from "./code/coding-agent.js";
4
+ import { resolveModels } from "./code/models.js";
4
5
  import { errorMessage } from "./errors.js";
5
6
  import { arrayOf, boolean, literal, nonEmptyString, object, optional, parseShape, string, } from "./json-shape.js";
6
7
  export const PLATFORMS = ["openclaw", "codingAgent"];
7
8
  const codeShape = object({
8
9
  agent: optional(literal(...CODING_AGENTS)),
10
+ defaultModel: optional(nonEmptyString),
9
11
  models: optional(arrayOf(string)),
10
12
  skipPermissions: optional(boolean),
11
13
  unset: optional(arrayOf(string)),
@@ -15,10 +17,11 @@ const configShape = object({
15
17
  projectsRoot: optional(nonEmptyString),
16
18
  code: optional(codeShape),
17
19
  });
18
- // An absent file is a normal state: every key takes its default.
20
+ // An absent file is a normal state: every key takes its default. A leftover file under the old
21
+ // name is an error, so a missed rename never silently drops the user's settings.
19
22
  export function loadConfig(home) {
20
- const path = join(home, ".alignfirst", "aligndev.config.json");
21
- const value = existsSync(path) ? parseConfigFile(path) : {};
23
+ const path = join(home, ".alignfirst", "aligndev.settings.json");
24
+ const value = existsSync(path) ? parseConfigFile(path) : absentConfig(home);
22
25
  const code = value.code ?? {};
23
26
  return {
24
27
  path,
@@ -28,12 +31,20 @@ export function loadConfig(home) {
28
31
  : { projectsRoot: resolveProjectsRoot(value.projectsRoot, home, path) }),
29
32
  code: {
30
33
  ...(code.agent === undefined ? {} : { agent: code.agent }),
34
+ ...(code.defaultModel === undefined ? {} : { defaultModel: code.defaultModel }),
31
35
  ...(code.models === undefined ? {} : { models: code.models }),
32
36
  skipPermissions: code.skipPermissions ?? false,
33
37
  unset: code.unset ?? [],
34
38
  },
35
39
  };
36
40
  }
41
+ function absentConfig(home) {
42
+ if (existsSync(join(home, ".alignfirst", "aligndev.config.json"))) {
43
+ throw new Error("Error: ~/.alignfirst/aligndev.config.json was renamed: " +
44
+ "move it to ~/.alignfirst/aligndev.settings.json");
45
+ }
46
+ return {};
47
+ }
37
48
  function parseConfigFile(path) {
38
49
  let value;
39
50
  try {
@@ -52,19 +63,32 @@ function resolveProjectsRoot(written, home, path) {
52
63
  return { path: join(home, written.slice(2)), written };
53
64
  return { path: isAbsolute(written) ? written : resolve(dirname(path), written), written };
54
65
  }
55
- // The configured `code.agent` wins; otherwise, the coding agent that runs aligndev.
56
66
  export function resolveCodeConfig(config, env) {
67
+ const code = { ...config.code, agent: resolveAgent(config, env) };
68
+ checkDefaultModel(code, config.path);
69
+ return code;
70
+ }
71
+ // The configured `code.agent` wins; otherwise, the coding agent that runs aligndev.
72
+ function resolveAgent(config, env) {
57
73
  const { agent } = config.code;
58
74
  if (agent !== undefined)
59
- return { ...config.code, agent };
75
+ return agent;
60
76
  const detected = detectCodingAgents(env);
61
77
  if (detected.length === 1)
62
- return { ...config.code, agent: detected[0] };
78
+ return detected[0];
63
79
  const problem = detected.length === 0
64
80
  ? "no coding agent detected: run aligndev from Claude Code or Codex, or set"
65
81
  : "both Claude Code and Codex detected: set";
66
82
  throw new Error(`Error: ${problem} "code.agent" (${CODING_AGENTS.join(" or ")}) in ${config.path}.`);
67
83
  }
84
+ function checkDefaultModel(code, path) {
85
+ if (code.defaultModel === undefined)
86
+ return;
87
+ const models = resolveModels(code.agent, code.models);
88
+ if (models.includes(code.defaultModel))
89
+ return;
90
+ throw new Error(`Error: code.defaultModel must be one of: ${models.join(", ")}, in ${path}.`);
91
+ }
68
92
  export function requireProjectsRoot(config) {
69
93
  if (config.projectsRoot !== undefined)
70
94
  return config.projectsRoot;
@@ -1,4 +1,4 @@
1
1
  import type { CodingAgent } from "../code/coding-agent.js";
2
2
  import type { CommandForms } from "../command-form.js";
3
3
  import type { Platform } from "../config.js";
4
- export declare function renderCodeGuide(platform: Platform, agent: CodingAgent, models: readonly string[], forms: CommandForms): string;
4
+ export declare function renderCodeGuide(platform: Platform, agent: CodingAgent, models: readonly string[], defaultModel: string | undefined, forms: CommandForms): string;
@@ -1,12 +1,13 @@
1
1
  import { renderGuideTemplate } from "./render-template.js";
2
- export function renderCodeGuide(platform, agent, models, forms) {
2
+ export function renderCodeGuide(platform, agent, models, defaultModel, forms) {
3
3
  return renderGuideTemplate("code.md", { platform }, forms, {
4
4
  AGENT: agent,
5
5
  AUTH_COMMAND: agent === "claude" ? "`claude`, then `/login`" : "`codex login`",
6
6
  PERMISSIONS: agent === "claude"
7
- ? "Normal runs use `--permission-mode auto`, plus `--add-dir <companion>` when the project's AlignFirst files live in its companion directory. `code.skipPermissions: true` in the aligndev config selects `--dangerously-skip-permissions`"
8
- : "Normal runs use `--sandbox workspace-write`, plus `--add-dir <companion>` when the project's AlignFirst files live in its companion directory. `code.skipPermissions: true` in the aligndev config selects `--dangerously-bypass-approvals-and-sandbox`",
7
+ ? "Normal runs use `--permission-mode auto`, plus `--add-dir <companion>` for a project with a companion directory. `code.skipPermissions: true` in the aligndev settings selects `--dangerously-skip-permissions`"
8
+ : "Normal runs use `--sandbox workspace-write`, plus `--add-dir <companion>` for a project with a companion directory. `code.skipPermissions: true` in the aligndev settings selects `--dangerously-bypass-approvals-and-sandbox`",
9
9
  MODELS: models.map((model) => `\`${model}\``).join(", "),
10
+ DEFAULT_MODEL: defaultModel === undefined ? "the coding agent's default" : `\`${defaultModel}\``,
10
11
  ALIGNFIRST_SETUP: forms.viaNpx
11
12
  ? "The project must be prepared for AlignFirst. `npx -y aligndev` runs the `alignfirst` CLI through `npx`."
12
13
  : "The project must be prepared for AlignFirst, with the `alignfirst` CLI installed (`npm install -g alignfirst`).",
@@ -42,11 +42,11 @@ function renderUsage(forms) {
42
42
  ${forms.aligndev} guide [<topic>] [--root <path>]
43
43
  ${forms.aligndev} guide --help
44
44
 
45
- Without a topic, prints the playbook of the platform set in the aligndev config.
45
+ Without a topic, prints the playbook of the platform set in the aligndev settings.
46
46
 
47
47
  Topics:
48
48
  code The delegation guide for \`${forms.aligndev} code\`.
49
- project The projects guide, openclaw only. --root overrides projectsRoot in the aligndev config.
49
+ project The projects guide, openclaw only. --root overrides projectsRoot in the aligndev settings.
50
50
 
51
51
  Playbook topics, by platform:
52
52
  ${playbookTopics.join("\n")}
@@ -63,7 +63,7 @@ function renderTopic(args, config, ctx) {
63
63
  function renderCodeTopic(config, ctx) {
64
64
  const code = resolveCodeConfig(config, ctx.env);
65
65
  const models = resolveModels(code.agent, code.models);
66
- return renderCodeGuide(config.platform, code.agent, models, ctx.forms);
66
+ return renderCodeGuide(config.platform, code.agent, models, code.defaultModel, ctx.forms);
67
67
  }
68
68
  function renderPlaybookTopic(topic, config, ctx) {
69
69
  if (topic !== undefined)
@@ -228,7 +228,7 @@ function findEnclosingRange(ranges, claim) {
228
228
  return;
229
229
  return ranges?.find((range) => containsRange(range, claim));
230
230
  }
231
- // Two projects can share a companion only through a `_` in a directory name.
231
+ // Two projects share a companion only when their registry `dir` values resolve to the same path.
232
232
  function reportSharedCompanions(projects, issues) {
233
233
  const projectsByCompanion = new Map();
234
234
  for (const project of projects) {
@@ -83,7 +83,7 @@ function parsePlans(value, path) {
83
83
  throw invalidReport(path);
84
84
  return value.folder === undefined ? {} : { folder: value.folder };
85
85
  }
86
- // The report's other companion fields (`key`, `flags`) are alignfirst's concern.
86
+ // The report's other companion fields (`key`, `items`) are alignfirst's concern.
87
87
  function parseCompanion(value, path) {
88
88
  if (value === null)
89
89
  return null;
@@ -56,7 +56,7 @@ function renderUsage(aligndev) {
56
56
  ${aligndev} project free-ports --size <n> [--range <code>] [--json] [--root <path>]
57
57
  ${aligndev} project --help
58
58
 
59
- --root defaults to projectsRoot in the aligndev config, then to the working directory.
59
+ --root defaults to projectsRoot in the aligndev settings, then to the working directory.
60
60
  A relative status <path> starts from the working directory.
61
61
  `;
62
62
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "aligndev",
3
- "version": "0.22.1",
3
+ "version": "0.23.0-preview.topics.0",
4
4
  "license": "CC0-1.0",
5
5
  "author": "Thomas MUR",
6
6
  "description": "The AlignDev CLI: the assistant's playbook, coding-agent delegation, and project inventory.",
@@ -120,10 +120,10 @@ Keep session files in place; they are the durable audit trail.
120
120
  | `--message "..."` | Message to send, written in English. `-m` is the short form. Required for `spec`, `aad`, and when neither `--protocol` nor `--catchup` is given. A message file also satisfies this requirement. |
121
121
  | `--message-file <path>` | Read a UTF-8 message file; `-` reads stdin. Mutually exclusive with `--message`. |
122
122
  | `--catchup` | Load the ticket history before the protocol and message. `new` only, requires a ticket. Alone, it returns a short synthesis. |
123
- | `--model <model>` | One of {{MODELS}}. Prefer the default model (omit the flag). |
123
+ | `--model <model>` | One of {{MODELS}}. A new session defaults to {{DEFAULT_MODEL}}; a resume keeps the session's model. Prefer the default (omit the flag). |
124
124
  | `--meta "..."` | Opaque handoff string stored verbatim in the session file's `meta:` frontmatter. `{{ALIGNDEV}} code` never reads it — it's for you to stash context the run's later reader needs (e.g. where to report the outcome). |
125
125
 
126
- The current coding agent is `{{AGENT}}`. `code.models` in the aligndev config replaces its displayed allowlist. Codex aliases `astra`, `sol`, `terra`, and `luna` resolve to the newest bundled matching slug only when selected; a configured full slug passes through unchanged.
126
+ The current coding agent is `{{AGENT}}`. `code.models` in the aligndev settings replaces its displayed allowlist. Codex aliases `astra`, `sol`, `terra`, and `luna` resolve to the newest bundled matching slug only when selected; a configured full slug passes through unchanged.
127
127
 
128
128
  `{{ALIGNDEV}} code status` checks that a `running` process still owns its recorded pid. A dead run is sealed as `status: failed`, `exitReason: terminated` before the command reports it. `{{ALIGNDEV}} code quota` works without a `.plans` directory and does not start a coding session. Its output follows the selected agent's available account limits.
129
129
 
@@ -236,16 +236,16 @@ Prefer `--message-file` for long or multi-line messages. A quoted heredoc delimi
236
236
 
237
237
  ## Answering the agent's questions
238
238
 
239
- During spec and AAD sessions the agent asks numbered questions, `Q1`, `Q2`…, each with a ➡️ recommendation. Resume **without a protocol** to answer. Compose the answers in English, all in one message, numbered to match:
239
+ During spec and AAD sessions each question opens a topic, `T1`, `T2`…, with a ➡️ recommendation. Resume **without a protocol** to answer. Compose the answers in English, all in one message, numbered to match:
240
240
 
241
241
  ```bash
242
242
  {{ALIGNDEV}} code resume <sessionId> --message \
243
- "Q1 - Explore the codebase and give me your opinion.
244
- Q2 - Is that a good design? We need the cleanest code possible.
245
- Q3 - Yes, it should be optional."
243
+ "T1 - Explore the codebase and give me your opinion.
244
+ T2 - Is that a good design? We need the cleanest code possible.
245
+ T3 - Yes, it should be optional."
246
246
  ```
247
247
 
248
- A question your reply skips stays open. Accept a whole round only once your user has settled every decision that is theirs: "All recommendations accepted, except Q3: <what to do instead>."
248
+ A question your reply skips or answers partially stays open under its topic. Accept a whole round only once your user has settled every decision that is theirs: "All recommendations accepted, except T3: <what to do instead>."
249
249
 
250
250
  **Technical questions** — architecture, patterns, existing behavior, anything answerable by reading the code. Never escalate these to the user. Push the agent to investigate: *"Explore the codebase to find out, and give me your opinion."*, *"Do not rush. Take the time to fully understand the situation first."*, *"What would be the elegant, proper, simple yet robust solution?"*, *"Check if a similar pattern is already implemented elsewhere in the codebase."*
251
251
 
@@ -20,7 +20,7 @@ Creation has a hard user-input gate. Before any filesystem, Git, port-allocation
20
20
 
21
21
  1. Settle the stack, allowed parent directory, project name, and port requirements with the user. Use the `{{ALIGNDEV}} guide project` output to constrain the choices.
22
22
  2. Create the main-worktree directory under the selected allowed parent. Initialize its Git repository on `main`.
23
- 3. Once the directory contains its `.git` directory, retain the canonical path as PROJECT_PATH. When the project declares ports, run `{{ALIGNDEV}} project free-ports --root <selected parent directory> --size <perWorkspace × maxWorkspaces> [--range <code>]` and retain the block; preparation through the setup guide writes it into `.alignfirst.json`. The selected parent's marker owns its port range. Report that `.alignfirst.json` was written and name the block.
23
+ 3. Once the directory contains its `.git` directory, retain the canonical path as PROJECT_PATH. When the project declares ports, run `{{ALIGNDEV}} project free-ports --root <selected parent directory> --size <port names × concurrent workspaces> [--range <code>]` and retain the block; preparation through the setup guide writes it into `.alignfirst.json`. The selected parent's marker owns its port range. Report that `.alignfirst.json` was written and name the block.
24
24
  4. Create `.plans/`, then run `{{ALIGNFIRST}} sync`. With an external ticket, run `{{ALIGNFIRST}} ticket {TICKET_ID} --next request.md` and append FILE_NAME to TICKET_DIR, exactly as printed, to get the path. Otherwise run `{{ALIGNFIRST}} ticket --side`; TICKET_ID is the reported `side-N`, and the path is `{TICKET_DIR}A1-request.md`. Write the complete creation request there from the starter and every later human message that supplied the gate's values. Record the project name, selected parent, stack, port requirements, and requested stopping point; never copy only the starter's task line. Then run `{{ALIGNFIRST}} sync`. The bot chooses the identifier and writes the request; the agent does neither. A later plans setup migrates this content when it replaces the directory with a symlink.
25
25
  5. Before delegating the bootstrap, run `{{ALIGNDEV}} guide code`. On a takeover turn, apply the pre-delegation race checkpoint in the playbook (`{{ALIGNDEV}} guide`) immediately before `{{ALIGNDEV}} code new`. Then bootstrap directly from PROJECT_PATH through `{{ALIGNDEV}} code new --message`, with no protocol. Explicitly instruct it to use `alignfirst-setup-guide` and prepare the repository for an assistant. It must run `{{ALIGNDEV}} project doctor` after writing `.alignfirst.json` and before workspace setup, stopping on an unhealthy inventory. Include `.local/` as a gitignored shared directory in the workspace mechanism. Follow the selected stack and the host-specific guide.
26
26
  6. Verify the project through the setup guide, run `{{ALIGNFIRST}} sync`, and make its initial commit on `main` in PROJECT_PATH. Do not ask for confirmation before committing.
@@ -39,12 +39,12 @@ Before any discussion:
39
39
 
40
40
  1. Select a parent directory allowed by `{{ALIGNDEV}} guide project`. Ask the user when several qualify.
41
41
  2. Clone the repository into that parent. PROJECT is the clone's directory name; PROJECT_PATH is its canonical path.
42
- 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`.
42
+ 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 <port names × concurrent workspaces> [--range <code>]` and retain the block; preparation through the setup guide writes it into `.alignfirst.json`.
43
43
  4. Install dependencies and build, following the repository's own README.
44
44
 
45
45
  ### Step 2 — Check the AlignDev contract
46
46
 
47
- 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.
47
+ The contract is the one the `alignfirst-setup-guide` lists under "Prepare a Project for an Assistant": the `alignfirst context` bootstrap section, 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.
48
48
 
49
49
  ### Step 3 — Warn and ask
50
50
 
@@ -72,7 +72,7 @@ When the user reports the merge, or you observe it while checking the PR:
72
72
  2. Install dependencies and build.
73
73
  3. When the user chose the work-files repository, clone it under `{{PROJECTS_ROOT}}` when no clone exists there (the projects guide names the repository), then run `{{ALIGNFIRST}} plans setup {{PROJECTS_ROOT}}/<clone>` from PROJECT_PATH. Otherwise, run `mkdir .plans`.
74
74
  4. Run `{{ALIGNDEV}} project doctor`. Stop when the inventory is unhealthy.
75
- 5. Run the project's `workspace setup` on the main worktree. Add `--profile remote` when the deployment sets `REMOTE_DEV_DOMAIN`.
75
+ 5. Run the project's `workspace setup` on the main worktree.
76
76
  6. Continue with the normal working-session flow for the original request through `{{ALIGNDEV}} guide project-workspace-setup`.
77
77
 
78
78
  ### Prepare through the companion
@@ -4,7 +4,7 @@ A projects directory groups projects and optional nested projects directories. I
4
4
 
5
5
  A project is a git main worktree, direct child of a projects directory. Its linked worktrees are listed as its workspaces. Other child directories, those that are not git repositories, appear under `others`.
6
6
 
7
- A project's AlignFirst files may live in its companion directory, declared in the companion registry `~/.alignfirst/companions/registry.json`. `{{ALIGNDEV}} project status <path>` gives each location.
7
+ A project's AlignFirst files may live in its companion directory, the `dir` of its entry in the companion registry `~/.alignfirst/companions/registry.json`. `{{ALIGNDEV}} project status <path>` gives each location.
8
8
 
9
9
  ## Commands
10
10
 
@@ -17,17 +17,17 @@ A project's AlignFirst files may live in its companion directory, declared in th
17
17
  {{ALIGNDEV}} guide project [--root <path>]
18
18
  ```
19
19
 
20
- `--root` selects the projects directory. It defaults to `projectsRoot` in the aligndev config, then to the working directory.
20
+ `--root` selects the projects directory. It defaults to `projectsRoot` in the aligndev settings, then to the working directory.
21
21
 
22
22
  `doctor` is a read-only health gate. It exits successfully only when discovery completes with no
23
23
  inventory issues.
24
24
 
25
25
  ## Port claims
26
26
 
27
- Run `{{ALIGNDEV}} project free-ports --size <n>` with the block size required by the project's workspace scheme: `perWorkspace × maxWorkspaces`. The directory section identifies the range for each project kind. Pass `--range <code>` for a coded range; the default needs no flag. The setup guide writes the returned block as `portRange` in the project's `.alignfirst.json`.
27
+ Run `{{ALIGNDEV}} project free-ports --size <n>` with the size of the project's port range: port names × expected concurrent workspaces. The directory section identifies the range for each project kind. Pass `--range <code>` for a coded range; the default needs no flag. The setup guide writes the returned block as `portRange` in the project's `.alignfirst.json`.
28
28
 
29
- The project config is its registration. Deleting the project removes it from the listing. The workspace kernel refuses a `workspace` command when the project's `portRange` disagrees with its port scheme.
29
+ The project config is its registration. Deleting the project removes it from the listing. The workspace dev-server refuses a command when the project's `portRange` disagrees with the `ports` range of its config.
30
30
 
31
31
  ## Reported issues
32
32
 
33
- The listing reports invalid project configs, non-main root projects, a `.alignfirst.json` outside a git main worktree, project or nested-directory ranges outside their enclosing range, overlapping project ranges, and projects sharing one companion directory.
33
+ The listing reports invalid project configs, non-main root projects, a `.alignfirst.json` outside a git main worktree, project or nested-directory ranges outside their enclosing range, overlapping project ranges, and projects whose registry entries resolve to the same companion directory.