alignfirst 0.1.0-beta.0 → 0.1.0-beta.1

package/dist/commands/ticket.js

@@ -15,7 +15,9 @@ export function runTicket(ctx, args) {
     if (parsed === undefined)
         return 0;
     const result = resolveTicket(ctx, parsed);
-    const next = parsed.next === undefined ? undefined : nextFileName(result.dir, parsed.next, parsed.newCycle);
+    const next = parsed.next === undefined
+        ? undefined
+        : nextFileName(result.entries, parsed.next, parsed.newCycle);
     if (parsed.json)
         ctx.stdout.write(`${JSON.stringify(jsonReport(ctx, parsed, result, next), undefined, 2)}\n`);
     else
@@ -49,6 +51,8 @@ function parseTicketArgs(ctx, args, usage) {
         throw new CliError(`A ticket id cannot be combined with --side.\n\n${usage}`);
     if (values["new-cycle"] && values.next === undefined)
         throw new CliError(`--new-cycle requires --next.\n\n${usage}`);
+    if (values.next !== undefined)
+        validateNextFilename(values.next);
     const resolution = resolveTicketId(ctx, positionals[0], values.side, values["dry-run"]);
     return {
         ...resolution,
@@ -59,8 +63,13 @@ function parseTicketArgs(ctx, args, usage) {
         side: values.side,
     };
 }
+function validateNextFilename(filename) {
+    if (filename.length === 0 || filename === "." || filename === ".." || /[\\/]/u.test(filename)) {
+        throw new CliError("--next must be a non-empty single path segment.");
+    }
+}
 function resolveTicketId(ctx, positional, side, dryRun) {
-    const pattern = ctx.projectConfig?.config.ticketPattern;
+    const pattern = ctx.projectConfig?.config.ticketIdPattern;
     if (positional !== undefined) {
         validateTicketId(positional, pattern);
         return { id: positional };
@@ -68,7 +77,7 @@ function resolveTicketId(ctx, positional, side, dryRun) {
     if (side)
         return { id: dryRun ? peekSideTicket(ctx.cwd) : reserveSideTicket(ctx.cwd) };
     if (pattern === undefined)
-        throw new CliError("No ticket id given and .alignfirst.json has no ticketPattern: pass the id.");
+        throw new CliError("No ticket id given. Pass it.\nSetting ticketIdPattern in .alignfirst.json enables deduction from the current branch.");
     const deduced = deduceTicketFromBranch(ctx.cwd, pattern);
     validateTicketId(deduced.id, pattern);
     return deduced;

package/dist/context.d.ts

@@ -1,4 +1,4 @@
-import type { Overlay, ResolvedProjectConfig } from "./overlay.js";
+import type { ResolvedProjectConfig } from "./project-config.js";
 export interface Output {
     write(text: string): void;
 }
@@ -11,5 +11,4 @@ export interface CommandContext {
     form: string;
     version: string;
     projectConfig?: ResolvedProjectConfig;
-    overlay?: Overlay;
 }

package/dist/conventions.d.ts

@@ -0,0 +1,8 @@
+import type { CommandContext } from "./context.js";
+import type { CommitConfig } from "./project-config.js";
+export interface CommitSubject {
+    subject: string;
+    side?: string;
+}
+export declare function renderConventions(ctx: CommandContext): string;
+export declare function commitSubject(commit: CommitConfig): CommitSubject;

package/dist/conventions.js

@@ -0,0 +1,86 @@
+import { existsSync, lstatSync } from "node:fs";
+import { join } from "node:path";
+import { renderDefaultBranchLine, resolveDefaultBranch } from "./default-branch.js";
+import { gitOutputOrUndefined, gitSucceeds } from "./git.js";
+import { resolvePlansMode } from "./plans/mode.js";
+export function renderConventions(ctx) {
+    const lines = [
+        renderTicketIds(ctx),
+        renderBranchNames(ctx),
+        renderCommits(ctx),
+        renderDefaultBranchLine(resolveDefaultBranch(ctx.cwd, ctx.projectConfig?.config)),
+        renderPlans(ctx),
+        renderSearches(ctx),
+    ].filter((line) => line !== undefined);
+    return `${lines.join("\n")}\n`;
+}
+function renderTicketIds(ctx) {
+    const pattern = ctx.projectConfig?.config.ticketIdPattern;
+    if (pattern === undefined)
+        return "Ticket IDs: no configured format; ask the user for the ID. Without an external ticket, use the next `side-N`.";
+    return `Ticket IDs: \`${pattern}\`; infer a matching ID from the branch. Without an external ticket, use the next \`side-N\`.`;
+}
+function renderBranchNames(ctx) {
+    const template = ctx.projectConfig?.config.git?.branchNameTemplate;
+    return template === undefined ? undefined : `Branch names: \`${template}\`.`;
+}
+function renderCommits(ctx) {
+    const git = ctx.projectConfig?.config.git;
+    if (git?.commit === undefined) {
+        return git?.agentCoauthoring === false
+            ? "Commits: do not add an agent co-author trailer."
+            : undefined;
+    }
+    const { subject, side } = commitSubject(git.commit);
+    const rule = side === undefined ? `${subject}.` : `${subject}; use ${side}.`;
+    const coauthor = git.agentCoauthoring === false ? " Do not add an agent co-author trailer." : "";
+    return `Commits: ${rule}${coauthor}`;
+}
+export function commitSubject(commit) {
+    if (commit.ticketReference === "bracketed")
+        return { subject: "`type: [ticketId] summary`", side: "`type: summary` for `side-N`" };
+    if (commit.ticketReference === "bracketedHash")
+        return { subject: "`type: [#ticketId] summary`", side: "`type: summary` for `side-N`" };
+    return { subject: "`type: summary`" };
+}
+function renderPlans(ctx) {
+    if (!plansEntryExists(ctx.cwd))
+        return;
+    try {
+        const mode = resolvePlansMode(ctx.cwd, ctx.form);
+        const folder = ctx.projectConfig?.config.plans?.folder;
+        const sharedFolder = folder === undefined ? "" : ` (shared folder \`${folder}\`)`;
+        const base = mode.kind === "shared"
+            ? `Plans: use \`.plans\`${sharedFolder}; keep it out of product commits, and run \`${ctx.form} sync\` after changes.`
+            : "Plans: use `.plans`; keep it out of product commits.";
+        const archival = ctx.projectConfig?.config.plans?.autoArchive === true
+            ? " Automatic archival is enabled."
+            : "";
+        return `${base}${archival}`;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return `Plans: ${message.split("\n", 1)[0]}`;
+    }
+}
+function plansEntryExists(cwd) {
+    return lstatSync(join(cwd, ".plans"), { throwIfNoEntry: false }) !== undefined;
+}
+function renderSearches(ctx) {
+    const directories = [
+        ...(plansEntryExists(ctx.cwd) ? [".plans"] : []),
+        ...[".local", ".local-wt"].filter((name) => qualifiesIgnoredDirectory(ctx.cwd, name)),
+    ];
+    if (directories.length === 0)
+        return;
+    const rendered = directories.map((name) => `\`${name}\``);
+    const joined = rendered.length === 1
+        ? rendered[0]
+        : `${rendered.slice(0, -1).join(", ")} and ${rendered.at(-1)}`;
+    return `Searches: exclude ${joined} from broad codebase searches.`;
+}
+function qualifiesIgnoredDirectory(cwd, name) {
+    return (existsSync(join(cwd, name)) &&
+        gitSucceeds(cwd, "check-ignore", "-q", name) &&
+        gitOutputOrUndefined(cwd, "ls-files", "--", name) === "");
+}

package/dist/default-branch.d.ts

@@ -0,0 +1,8 @@
+import type { ProjectConfig } from "./project-config.js";
+export interface DefaultBranch {
+    name: string;
+    source: "config" | "cached";
+    remote?: string;
+}
+export declare function resolveDefaultBranch(cwd: string, config: ProjectConfig | undefined): DefaultBranch | undefined;
+export declare function renderDefaultBranchLine(branch: DefaultBranch | undefined): string;

package/dist/default-branch.js

@@ -0,0 +1,32 @@
+import { gitOutputOrUndefined, gitSucceeds } from "./git.js";
+export function resolveDefaultBranch(cwd, config) {
+    const configured = config?.git?.defaultBranch;
+    if (configured !== undefined)
+        return { name: configured, source: "config" };
+    const remote = resolveRemote(cwd);
+    if (remote === undefined)
+        return;
+    const prefix = `refs/remotes/${remote}/`;
+    const target = gitOutputOrUndefined(cwd, "symbolic-ref", "-q", `${prefix}HEAD`);
+    if (target === undefined || target === "" || !target.startsWith(prefix))
+        return;
+    if (!gitSucceeds(cwd, "rev-parse", "--verify", "-q", target))
+        return;
+    return { name: target.slice(prefix.length), source: "cached", remote };
+}
+function resolveRemote(cwd) {
+    const output = gitOutputOrUndefined(cwd, "remote");
+    if (output === undefined || output === "")
+        return;
+    const remotes = output.split("\n").filter((remote) => remote !== "");
+    if (remotes.includes("origin"))
+        return "origin";
+    return remotes.length === 1 ? remotes[0] : undefined;
+}
+export function renderDefaultBranchLine(branch) {
+    if (branch === undefined)
+        return "Default branch: unresolved; ask before default-branch operations.";
+    return branch.source === "cached"
+        ? `Default branch: ${branch.name} (cached).`
+        : `Default branch: ${branch.name}.`;
+}

package/dist/parse-args.d.ts

@@ -1 +1,3 @@
+import type { CommandContext } from "./context.js";
 export declare function parseCommandArgs<T>(usage: string, parse: () => T): T;
+export declare function parseBareCommandArgs(ctx: CommandContext, args: string[], usage: string): boolean;

package/dist/parse-args.js

@@ -1,5 +1,6 @@
 import { CliError } from "./cli-error.js";
 import { errorMessage } from "./errors.js";
+import { parseArgs } from "node:util";
 export function parseCommandArgs(usage, parse) {
     try {
         return parse();
@@ -9,3 +10,17 @@ export function parseCommandArgs(usage, parse) {
         throw new CliError(`${detail}\n\n${usage}`);
     }
 }
+export function parseBareCommandArgs(ctx, args, usage) {
+    const { values, positionals } = parseCommandArgs(usage, () => parseArgs({
+        args,
+        options: { help: { type: "boolean", short: "h", default: false } },
+        strict: true,
+        allowPositionals: true,
+    }));
+    if (positionals.length > 0)
+        throw new CliError(`Unexpected argument: ${positionals[0]}\n\n${usage}`);
+    if (!values.help)
+        return false;
+    ctx.stdout.write(usage);
+    return true;
+}

package/dist/plans/layout.d.ts

@@ -1,6 +1,9 @@
+import { CliError } from "../cli-error.js";
 export declare const PLANS_DIR = ".plans";
 export declare const ARCHIVES_DIR = "_archives";
 export declare function isTicketName(name: string): boolean;
 export declare function plansDir(cwd: string): string;
 export declare function archivesDir(cwd: string): string;
 export declare function assertPlansGate(cwd: string, form: string): void;
+export declare function missingPlansMessage(form: string): string;
+export declare function missingPlansError(form: string): CliError;

package/dist/plans/layout.js

@@ -15,5 +15,11 @@ export function archivesDir(cwd) {
 export function assertPlansGate(cwd, form) {
     if (existsSync(plansDir(cwd)))
         return;
-    throw new CliError(`Error: no \`.plans/\` directory found in the current directory. Run \`${form}\` from the root of an AlignFirst-managed project.`);
+    throw missingPlansError(form);
+}
+export function missingPlansMessage(form) {
+    return `No .plans/ directory in the current directory.\nLocal plans:  mkdir .plans && echo .plans >> .gitignore\nTeam plans:   ${form} plans setup <clone-dir>`;
+}
+export function missingPlansError(form) {
+    return new CliError(missingPlansMessage(form));
 }

package/dist/plans/mode.js

@@ -2,12 +2,12 @@ import { existsSync, lstatSync, realpathSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { CliError } from "../cli-error.js";
 import { gitOutput } from "../git.js";
+import { missingPlansError } from "./layout.js";
 export function resolvePlansMode(cwd, form) {
     const plansPath = join(cwd, ".plans");
     const stats = lstatSync(plansPath, { throwIfNoEntry: false });
     if (!stats)
-        throw new CliError(`.plans is missing. Clone the team plans repository, then run ${form} plans setup ` +
-            "(see the project documentation) — or create a plain .plans directory to keep plans local.");
+        throw missingPlansError(form);
     if (stats.isSymbolicLink() && !existsSync(plansPath))
         throw new CliError(`The .plans symlink is broken. Re-run ${form} plans setup with the clone location.`);
     if (!statSync(plansPath).isDirectory())

package/dist/plans/rebase.d.ts

@@ -0,0 +1,6 @@
+export interface StoppedRebase {
+    repoDir: string;
+    conflictedFiles: string[];
+}
+export declare function findStoppedRebase(repoDir: string): StoppedRebase | undefined;
+export declare function renderStoppedRebase(stopped: StoppedRebase, form: string): string;

package/dist/plans/rebase.js

@@ -0,0 +1,27 @@
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { gitOutputOrUndefined } from "../git.js";
+export function findStoppedRebase(repoDir) {
+    const inProgress = ["rebase-merge", "rebase-apply"].some((name) => {
+        const path = gitOutputOrUndefined(repoDir, "rev-parse", "--git-path", name);
+        return path !== undefined && path !== "" && existsSync(resolve(repoDir, path));
+    });
+    if (!inProgress)
+        return;
+    const conflicts = gitOutputOrUndefined(repoDir, "diff", "--name-only", "--diff-filter=U");
+    return {
+        repoDir,
+        conflictedFiles: conflicts?.split("\n").filter((path) => path !== "") ?? [],
+    };
+}
+export function renderStoppedRebase(stopped, form) {
+    const files = stopped.conflictedFiles.map((path) => `  ${path}`);
+    return [
+        `Plans synchronization stopped on a conflict in ${stopped.repoDir}:`,
+        ...files,
+        "Resolve the markers in these files, then run:",
+        `  git -C ${stopped.repoDir} add -A && git -C ${stopped.repoDir} rebase --continue`,
+        `  ${form} sync`,
+        `To discard the local side instead: git -C ${stopped.repoDir} rebase --abort`,
+    ].join("\n");
+}

package/dist/plans/ticket.d.ts

@@ -11,11 +11,22 @@ export interface DeducedTicket {
     id: string;
     branch: string;
 }
+export type TicketDetection = {
+    kind: "detected";
+    id: string;
+    branch: string;
+} | {
+    kind: "noMatch";
+    branch: string;
+} | {
+    kind: "noBranch";
+};
 export declare function resolveTicketDir(cwd: string, id: string, { dryRun }: ResolveTicketOptions): ResolvedTicketDir;
 export declare function reserveSideTicket(cwd: string): string;
 export declare function peekSideTicket(cwd: string): string;
-export declare function nextFileName(dir: string, filename: string, newCycle: boolean): string;
+export declare function nextFileName(entries: readonly string[], filename: string, newCycle: boolean): string;
 export declare function listEntries(dir: string): string[];
 export declare function isPathSafeTicketId(id: string): boolean;
 export declare function validateTicketId(id: string, pattern?: string): void;
+export declare function detectTicketFromBranch(cwd: string, pattern: string): TicketDetection;
 export declare function deduceTicketFromBranch(cwd: string, pattern: string): DeducedTicket;

package/dist/plans/ticket.js

@@ -63,9 +63,9 @@ function readEntries(dir) {
         return [];
     }
 }
-export function nextFileName(dir, filename, newCycle) {
-    const prefixes = readEntries(dir).flatMap((entry) => {
-        const match = FILE_PREFIX.exec(entry.name);
+export function nextFileName(entries, filename, newCycle) {
+    const prefixes = entries.flatMap((entry) => {
+        const match = FILE_PREFIX.exec(entry);
         return match ? [{ cycle: match[1], number: Number(match[2]) }] : [];
     });
     if (prefixes.length === 0)
@@ -90,15 +90,23 @@ export function validateTicketId(id, pattern) {
     if (!isPathSafeTicketId(id))
         throw new CliError(`Invalid ticket id: ${id}`);
     if (pattern !== undefined && !new RegExp(pattern).test(id) && !SIDE_TICKET.test(id))
-        throw new CliError(`Ticket id "${id}" does not match ticketPattern "${pattern}".`);
+        throw new CliError(`Ticket id "${id}" does not match ticketIdPattern "${pattern}".`);
 }
-export function deduceTicketFromBranch(cwd, pattern) {
+export function detectTicketFromBranch(cwd, pattern) {
     const branch = gitOutputOrUndefined(cwd, "branch", "--show-current");
     if (branch === undefined || branch === "")
-        throw new CliError("Cannot deduce a ticket id from a detached HEAD.");
+        return { kind: "noBranch" };
     const unanchored = pattern.replace(/^\^/, "").replace(/\$$/, "");
     const match = new RegExp(unanchored).exec(branch);
     if (!match)
-        throw new CliError(`Cannot deduce a ticket id from branch "${branch}" with pattern "${pattern}".`);
-    return { id: match[0], branch };
+        return { kind: "noMatch", branch };
+    return { kind: "detected", id: match[0], branch };
+}
+export function deduceTicketFromBranch(cwd, pattern) {
+    const result = detectTicketFromBranch(cwd, pattern);
+    if (result.kind === "noBranch")
+        throw new CliError("Cannot deduce a ticket id from a detached HEAD.");
+    if (result.kind === "noMatch")
+        throw new CliError(`Cannot deduce a ticket id from branch "${result.branch}" with pattern "${pattern}".`);
+    return result;
 }

package/dist/project-config.d.ts

@@ -1,27 +1,34 @@
 export declare const PROJECT_CONFIG_FILENAME = ".alignfirst.json";
-export declare const portRangeSchema: import("arktype/internal/variants/object.ts").ObjectType<{
-    first: number;
-    last: number;
-}, {}>;
 export interface ProjectConfig {
     schemaVersion: 1;
     cli?: string;
-    ticketPattern?: string;
+    ticketIdPattern?: string;
     plans?: PlansConfig;
     portRange?: PortRange;
-    project?: ProjectIdentity;
+    git?: GitConfig;
 }
 export interface PlansConfig {
-    folder: string;
+    folder?: string;
+    autoArchive?: boolean;
 }
 export interface PortRange {
     first: number;
     last: number;
 }
-export interface ProjectIdentity {
-    remote?: string;
-    paths?: string[];
+export interface GitConfig {
+    defaultBranch?: string;
+    branchNameTemplate?: string;
+    commit?: CommitConfig;
+    agentCoauthoring?: boolean;
 }
-export declare function validateProjectConfig(value: unknown, label: string): ProjectConfig;
-export declare function assertValidPortRange(range: PortRange, label: string): void;
+export interface CommitConfig {
+    style: "conventionalCommit";
+    ticketReference?: "bracketed" | "bracketedHash";
+}
+export interface ResolvedProjectConfig {
+    config: ProjectConfig;
+    source: "root";
+}
+export declare function resolveProjectConfig(cwd: string): ResolvedProjectConfig | undefined;
 export declare function readProjectConfig(dir: string): ProjectConfig | undefined;
+export declare function validateProjectConfig(value: unknown, label: string): ProjectConfig;

package/dist/project-config.js

@@ -1,45 +1,68 @@
 import { existsSync, readFileSync } from "node:fs";
-import { isAbsolute, join } from "node:path";
+import { join } from "node:path";
 import { type } from "arktype";
 import semver from "semver";
 import { CliError } from "./cli-error.js";
 import { errorMessage } from "./errors.js";
 export const PROJECT_CONFIG_FILENAME = ".alignfirst.json";
-export const portRangeSchema = type({
+const portRangeSchema = type({
     "+": "reject",
     first: "1 <= number.integer <= 65535",
     last: "1 <= number.integer <= 65535",
 });
 const plansSchema = type({
     "+": "reject",
-    folder: "string > 0",
+    "folder?": "string > 0",
+    "autoArchive?": "boolean",
 });
-const projectSchema = type({
+const commitSchema = type({
     "+": "reject",
-    "remote?": "string > 0",
-    "paths?": "string[]",
+    style: "'conventionalCommit'",
+    "ticketReference?": "'bracketed' | 'bracketedHash'",
+});
+const gitSchema = type({
+    "+": "reject",
+    "defaultBranch?": "string > 0",
+    "branchNameTemplate?": "string > 0",
+    "commit?": commitSchema,
+    "agentCoauthoring?": "boolean",
 });
 const projectConfigSchema = type({
     "+": "reject",
     schemaVersion: "1",
     "cli?": "string > 0",
-    "ticketPattern?": "string > 0",
+    "ticketIdPattern?": "string > 0",
     "plans?": plansSchema,
     "portRange?": portRangeSchema,
-    "project?": projectSchema,
+    "git?": gitSchema,
 });
+export function resolveProjectConfig(cwd) {
+    const config = readProjectConfig(cwd);
+    return config === undefined ? undefined : { config, source: "root" };
+}
+export function readProjectConfig(dir) {
+    const path = join(dir, PROJECT_CONFIG_FILENAME);
+    if (!existsSync(path))
+        return;
+    let value;
+    try {
+        value = JSON.parse(readFileSync(path, "utf-8"));
+    }
+    catch (error) {
+        throw invalidConfig(path, errorMessage(error));
+    }
+    return validateProjectConfig(value, path);
+}
 export function validateProjectConfig(value, label) {
     const config = projectConfigSchema(value);
     if (config instanceof type.errors)
         throw invalidConfig(label, config.summary.split("\n", 1)[0]);
     if (config.cli !== undefined && semver.validRange(config.cli) === null)
         throw invalidConfig(label, `cli is not a valid semver range: ${config.cli}`);
-    if (config.ticketPattern !== undefined)
-        assertValidPattern(config.ticketPattern, label);
+    if (config.ticketIdPattern !== undefined)
+        assertValidPattern(config.ticketIdPattern, label);
     if (config.portRange !== undefined)
         assertValidPortRange(config.portRange, label);
-    if (config.project !== undefined)
-        assertValidProjectIdentity(config.project, label);
     return config;
 }
 function invalidConfig(label, detail) {
@@ -50,30 +73,10 @@ function assertValidPattern(pattern, label) {
         new RegExp(pattern);
     }
     catch (error) {
-        throw invalidConfig(label, `ticketPattern is not a valid regular expression: ${errorMessage(error)}`);
+        throw invalidConfig(label, `ticketIdPattern is not a valid regular expression: ${errorMessage(error)}`);
     }
 }
-export function assertValidPortRange(range, label) {
+function assertValidPortRange(range, label) {
     if (range.first > range.last)
         throw invalidConfig(label, "portRange.first must not exceed portRange.last");
 }
-function assertValidProjectIdentity(project, label) {
-    if (project.remote === undefined && project.paths === undefined)
-        throw invalidConfig(label, "project must contain remote or paths");
-    const relativePath = project.paths?.find((path) => !isAbsolute(path));
-    if (relativePath !== undefined)
-        throw invalidConfig(label, `project.paths must contain only absolute paths: ${relativePath}`);
-}
-export function readProjectConfig(dir) {
-    const path = join(dir, PROJECT_CONFIG_FILENAME);
-    if (!existsSync(path))
-        return;
-    let value;
-    try {
-        value = JSON.parse(readFileSync(path, "utf-8"));
-    }
-    catch (error) {
-        throw invalidConfig(path, errorMessage(error));
-    }
-    return validateProjectConfig(value, path);
-}

package/dist/skills.d.ts

@@ -1,4 +1,3 @@
-import type { CommandContext } from "./context.js";
 export declare const STUB_SKILLS: readonly ["alignfirst", "alspec", "alplan", "al", "alcatchup", "almerge", "alreview", "aldescription"];
 export declare const SKILL_ROOTS: readonly [".agents/skills", ".claude/skills", ".codex/skills"];
 export interface InstalledSkill {
@@ -6,4 +5,3 @@ export interface InstalledSkill {
     version: string | undefined;
 }
 export declare function findInstalledSkill(home: string, name: string): InstalledSkill | undefined;
-export declare function installStubSkills(ctx: CommandContext, agents: string[]): void;

package/dist/skills.js

@@ -1,7 +1,5 @@
-import { execFileSync } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
-import { CliError } from "./cli-error.js";
 export const STUB_SKILLS = [
     "alignfirst",
     "alspec",
@@ -33,22 +31,3 @@ function readSkillVersion(path) {
         return;
     return /^\s+version:\s*"?([^"\r\n]+)"?\s*$/m.exec(metadata)?.[1]?.trim();
 }
-export function installStubSkills(ctx, agents) {
-    const skillArgs = STUB_SKILLS.flatMap((skill) => ["--skill", skill]);
-    const agentArgs = agents.flatMap((agent) => ["--agent", agent]);
-    try {
-        execFileSync("npx", [
-            "-y",
-            "skills",
-            "add",
-            "https://github.com/paleo/alignfirst",
-            "--global",
-            "--yes",
-            ...skillArgs,
-            ...agentArgs,
-        ], { cwd: ctx.cwd, env: ctx.env, stdio: "inherit" });
-    }
-    catch {
-        throw new CliError("Failed to install the AlignFirst skills globally.");
-    }
-}

package/dist/version-guard.d.ts

@@ -3,6 +3,5 @@ export interface CliRangeResult {
     range: string;
     satisfied: boolean;
 }
-export declare function defaultCliRange(version: string): string;
 export declare function checkCliRange(config: ProjectConfig | undefined, installedVersion: string, commandArgs: string[]): void;
 export declare function cliRangeResult(config: ProjectConfig | undefined, installedVersion: string): CliRangeResult | undefined;

package/dist/version-guard.js

@@ -1,12 +1,5 @@
 import semver from "semver";
 import { CliError } from "./cli-error.js";
-export function defaultCliRange(version) {
-    const parsed = semver.parse(version);
-    if (parsed === null)
-        throw new Error(`Invalid installed version: ${version}`);
-    const upper = parsed.major === 0 ? `0.${parsed.minor + 1}.0` : `${parsed.major + 1}.0.0`;
-    return `>=${version} <${upper}`;
-}
 export function checkCliRange(config, installedVersion, commandArgs) {
     const result = cliRangeResult(config, installedVersion);
     if (result === undefined || result.satisfied)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "alignfirst",
-  "version": "0.1.0-beta.0",
+  "version": "0.1.0-beta.1",
   "license": "CC0-1.0",
   "author": "Thomas MUR",
   "description": "The AlignFirst CLI: protocols, plans and docs in one command.",

package/templates/guide/core.md

@@ -14,9 +14,11 @@ An agent that does not know which protocol to use runs `{{CMD}} guide overview`.
 
 ## TASK_DIR Location
 
-**TASK_DIR** is `.plans/{TICKET_ID}/`. Run `{{CMD}} ticket <id>` and use the directory it prints. The command creates a missing directory, restores an archived one, and lists its entries.
+TASK_DIR holds the work files of a ticket. `{{TICKET_CMD}}` prints it and lists its entries; it creates a missing directory and restores an archived one.
 
-{{TICKET_ID_RULE}}
+{{TICKET_CONTEXT}}
+
+{{PLANS_STATE}}
 
 **Work without a ticket:** when the user says there is no ticket, run `{{CMD}} ticket --side`. Reuse an existing `side-N` directory when the user refers to that earlier work. Omit the ticket ID from commit messages.
 
@@ -36,18 +38,16 @@ Format: `{CYCLE_LETTER}{FILE_NUMBER}-{FILE_TYPE}.md`
 **Example structure:**
 
 ```text
-.plans/
-├── 123/
-│   ├── A1-spec.md
-│   ├── A2-plan.md
-│   └── A3-AAD.summary.md
-│   └── B1-spec.md
+A1-spec.md
+A2-plan.md
+A3-AAD.summary.md
+B1-spec.md
 ```
 
 ## Notes
 
 - **TICKET_ID** is a unique identifier for the task, often an issue or ticket number.
-- `{{CMD}} ticket <id> --next <filename>` prints the next filename in the current cycle, the extension included (`--next spec.md` giving `.plans/123/A2-spec.md`).
+- `{{TICKET_CMD}} --next <filename>` prints the path of the next file in the current cycle, the extension included (`--next spec.md` giving `A2-spec.md`).
 - `--new-cycle` starts a new cycle.
 - The protocol or the user decides whether to continue the current cycle or start a new one.
 - Cycle letters and file numbers are internal. Never discuss them with the user.