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 +4 -3
- package/dist/cli.js +1 -1
- package/dist/code/code-cli.js +44 -27
- package/dist/code/models.js +1 -1
- package/dist/config.d.ts +1 -0
- package/dist/config.js +30 -6
- package/dist/guide/code-guide.d.ts +1 -1
- package/dist/guide/code-guide.js +4 -3
- package/dist/guide/guide-cli.js +3 -3
- package/dist/project/discovery.js +1 -1
- package/dist/project/layout.js +1 -1
- package/dist/project/project-cli.js +1 -1
- package/package.json +1 -1
- package/templates/guide/code.md +7 -7
- package/templates/guide/playbook/project-lifecycle.md +4 -4
- package/templates/guide/project.md +5 -5
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.
|
|
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
|
|
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.
|
|
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
|
`;
|
package/dist/code/code-cli.js
CHANGED
|
@@ -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,
|
|
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
|
|
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
|
-
})
|
|
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 =
|
|
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
|
-
|
|
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:
|
|
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>
|
|
607
|
-
default
|
|
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.
|
|
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
|
|
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
|
package/dist/code/models.js
CHANGED
|
@@ -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
|
|
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
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.
|
|
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
|
|
75
|
+
return agent;
|
|
60
76
|
const detected = detectCodingAgents(env);
|
|
61
77
|
if (detected.length === 1)
|
|
62
|
-
return
|
|
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;
|
package/dist/guide/code-guide.js
CHANGED
|
@@ -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>`
|
|
8
|
-
: "Normal runs use `--sandbox workspace-write`, plus `--add-dir <companion>`
|
|
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`).",
|
package/dist/guide/guide-cli.js
CHANGED
|
@@ -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
|
|
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
|
|
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
|
|
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) {
|
package/dist/project/layout.js
CHANGED
|
@@ -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`, `
|
|
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
|
|
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
package/templates/guide/code.md
CHANGED
|
@@ -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
|
|
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
|
|
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
|
|
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
|
-
"
|
|
244
|
-
|
|
245
|
-
|
|
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
|
|
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 <
|
|
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 <
|
|
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":
|
|
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.
|
|
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,
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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.
|