alignfirst 0.1.0-beta.2 → 0.1.0-beta.4

package/README.md

@@ -35,7 +35,7 @@ The guide installs the selected components and configures the repository. Remove
 ## Commands
 
 - `guide` — Print an AlignFirst protocol.
-- `ticket` — Resolve a ticket directory and its next file.
+- `ticket` — Resolve a ticket directory, load its history, or get its next file.
 - `sync` — Synchronize shared plans.
 - `plans` — Set up, check and archive plans.
 - `docmap` — Browse project documentation.
@@ -44,18 +44,19 @@ The guide installs the selected components and configures the repository. Remove
 - `config` — Report the effective project configuration.
 - `doctor` — Diagnose an AlignFirst setup.
 
-Run `alignfirst --help` for command usage or `alignfirst guide` for the collaboration guide.
+Run `alignfirst --help` for command usage or `alignfirst guide` to choose a protocol. `alignfirst guide <protocol>` prints the selected protocol followed by shared conventions. Add `--protocol-only` when those conventions are already in context.
 
 ## Agent skills
 
-Eight optional Agent Skill stubs expose the CLI to GitHub Copilot, Cursor, Claude Code, and Codex. The skills contain no protocols; they invoke `npx alignfirst guide`.
+Ten optional Agent Skill stubs expose the CLI to GitHub Copilot, Cursor, Claude Code, and Codex. Protocol skills reuse guides already in context and load missing guides through `npx -y alignfirst guide`. Catchup skills load ticket history through `npx -y alignfirst ticket --catchup`.
 
 Install them globally:
 
 ```sh
 npx skills add https://github.com/paleo/alignfirst --global \
   --skill alignfirst --skill al --skill alplan --skill alspec \
-  --skill aldescription --skill alreview --skill alcatchup --skill almerge
+  --skill aldescription --skill alreview --skill alcatchup --skill almerge \
+  --skill alcatchupaad --skill alcatchupspec
 ```
 
 Restart the agent after installation. Claude Code, GitHub Copilot, and Cursor expose skills with `/`; Codex uses `$`.
@@ -73,11 +74,17 @@ These examples use the `/` form. Replace it with `$` in Codex.
 | Review | `/alreview` | Review the current branch against its base. |
 | Merge | `/almerge` | Resolve merge or rebase conflicts. |
 | Catch up | `/alcatchup` | Load the current task history and continue. |
+| Catch up and align | `/alcatchupaad <request>` | Load history, then start AAD. |
+| Catch up and specify | `/alcatchupspec <request>` | Load history, then start specification. |
 
 To implement a plan, start a fresh agent context and ask it to execute the plan file.
 
 AlignFirst stores specifications, plans, and summaries in `.plans/<ticket-id>/`. It normally derives the ticket ID from the request or branch and asks when none is available. Files use a cycle letter and sequence number, such as `A1-spec.md` and `A2-plan.md`.
 
+## Catchup output
+
+`alignfirst ticket [<id>] --catchup` prints the ticket's Markdown files, plans excluded, each in a `<file>` block carrying its path and modification time. When the history exceeds the output budget, only the entry list is printed so the agent can read the relevant files.
+
 ## Updates
 
 ```sh

package/dist/cli.js

@@ -59,7 +59,7 @@ function renderHelp(ctx) {
 
 Usage:
   ${ctx.form} guide [<protocol>]
-  ${ctx.form} ticket [<id>]
+  ${ctx.form} ticket [<id>] [--catchup]
   ${ctx.form} sync [--auto-archive | --no-auto-archive]
   ${ctx.form} plans <command>
   ${ctx.form} docmap [<arguments>]

package/dist/commands/guide.js

@@ -11,7 +11,7 @@ import { resolvePlansMode } from "../plans/mode.js";
 import { detectTicketFromBranch } from "../plans/ticket.js";
 import { PROTOCOLS } from "../protocols.js";
 const TICKET_CMD_PLACEHOLDER = "{{TICKET_CMD}}";
-const TICKET_CONTEXT_PLACEHOLDER = "{{TICKET_CONTEXT}}";
+const TICKET_DETECTION_PLACEHOLDER = "{{TICKET_DETECTION}}";
 const PLANS_STATE_PLACEHOLDER = "{{PLANS_STATE}}";
 const COMMIT_RULE_PLACEHOLDER = "{{COMMIT_RULE}}";
 const BASE_BRANCH_RULE_PLACEHOLDER = "{{BASE_BRANCH_RULE}}";
@@ -102,9 +102,15 @@ function renderGuide(ctx, options) {
         return applyPlaceholders(readProtocolTemplate(options.protocol), placeholders);
     const core = renderCoreGuide(ctx, placeholders);
     if (options.protocol === undefined)
-        return core;
+        return `${readGuideTemplate("selection.md")}\n\n${core}`;
     const protocol = applyPlaceholders(readProtocolTemplate(options.protocol), placeholders);
-    return `${core.trimEnd()}\n\n${protocol.trimEnd()}`;
+    const [title, ...sections] = protocol.split("\n\n");
+    return [
+        title,
+        "This guide includes the selected protocol and shared conventions. Read both before starting.",
+        ...sections,
+        core,
+    ].join("\n\n");
 }
 function renderReviewerGuide(perspective, modules) {
     const templates = [
@@ -125,13 +131,13 @@ function buildGuidePlaceholders(ctx, protocol) {
     const detection = pattern === undefined ? undefined : detectTicketFromBranch(ctx.cwd, pattern);
     return {
         ticketCommand: detection?.kind === "detected" ? "{{CMD}} ticket" : "{{CMD}} ticket <id>",
-        ticketContext: renderTicketContext(pattern, detection),
+        ticketDetection: renderTicketDetection(pattern, detection),
         plansState: renderPlansState(ctx),
         commitRule: renderCommitRule(ctx),
         baseBranchRule: renderBaseBranchRule(ctx, protocol),
     };
 }
-function renderTicketContext(pattern, detection) {
+function renderTicketDetection(pattern, detection) {
     if (pattern === undefined)
         return "Ask the user for the ticket ID when it is not given.";
     if (detection?.kind === "detected")
@@ -146,7 +152,7 @@ function renderPlansState(ctx) {
         return `\`\`\`text\n${missingPlansMessage(ctx.form)}\n\`\`\``;
     try {
         return resolvePlansMode(ctx.cwd, ctx.form).kind === "shared"
-            ? "After every change in TASK_DIR, run `{{CMD}} sync`."
+            ? "After every change in TICKET_DIR, run `{{CMD}} sync`."
             : "";
     }
     catch {
@@ -156,7 +162,7 @@ function renderPlansState(ctx) {
 function renderCommitRule(ctx) {
     const commit = ctx.projectConfig?.config.git?.commit;
     if (commit === undefined)
-        return "(follow the convention you are aware of, or default to `<type>: [<ticket_id>] very short description`)";
+        return "(follow the convention you are aware of, or default to `<type>: [TICKET_ID] very short description`)";
     const { subject, side } = commitSubject(commit);
     const rule = side === undefined ? subject : `${subject}; ${side}`;
     return `(project convention: ${rule})`;
@@ -177,7 +183,7 @@ function applyPlaceholders(template, values) {
     return template
         .replaceAll(`${PLANS_STATE_PLACEHOLDER}\n\n`, () => values.plansState === "" ? "" : `${values.plansState}\n\n`)
         .replaceAll(TICKET_CMD_PLACEHOLDER, () => values.ticketCommand)
-        .replaceAll(TICKET_CONTEXT_PLACEHOLDER, () => values.ticketContext)
+        .replaceAll(TICKET_DETECTION_PLACEHOLDER, () => values.ticketDetection)
         .replaceAll(PLANS_STATE_PLACEHOLDER, () => values.plansState)
         .replaceAll(COMMIT_RULE_PLACEHOLDER, () => values.commitRule)
         .replaceAll(BASE_BRANCH_RULE_PLACEHOLDER, () => values.baseBranchRule);

package/dist/commands/ticket.js

@@ -1,12 +1,19 @@
 import { join, relative } from "node:path";
 import { parseArgs } from "node:util";
 import { CliError } from "../cli-error.js";
+import { formatLocalTimestamp, formatSize } from "../format.js";
 import { parseCommandArgs } from "../parse-args.js";
+import { renderCatchup } from "../plans/catchup.js";
 import { assertPlansGate } from "../plans/layout.js";
-import { deduceTicketFromBranch, nextFileName, peekSideTicket, reserveSideTicket, resolveTicketDir, validateTicketId, } from "../plans/ticket.js";
+import { deduceTicketFromBranch, nextFilePosition, peekSideTicket, reserveSideTicket, resolveTicketDir, validateTicketId, } from "../plans/ticket.js";
 const USAGE = `Usage:
-  {{FORM}} ticket [<id>] [--next <filename>] [--new-cycle] [--json] [--dry-run]
-  {{FORM}} ticket --side [--json] [--dry-run]
+  {{FORM}} ticket [<id>] [--next [<filename>]] [--new-cycle] [--json] [--dry-run]
+  {{FORM}} ticket --side [--next [<filename>]] [--new-cycle] [--json] [--dry-run]
+  {{FORM}} ticket [<id> | --side] --catchup
+
+--catchup prints the ticket's Markdown files, plans excluded, summaries included.
+Files over 64 KiB are listed without content. Above 30 KiB of output, only the entry
+list is printed.
 `;
 export function runTicket(ctx, args) {
     assertPlansGate(ctx.cwd, ctx.form);
@@ -15,27 +22,34 @@ export function runTicket(ctx, args) {
     if (parsed === undefined)
         return 0;
     const result = resolveTicket(ctx, parsed);
-    const next = parsed.next === undefined
-        ? undefined
-        : nextFileName(result.entries, parsed.next, parsed.newCycle);
+    if (parsed.catchup) {
+        ctx.stdout.write(renderCatchup(ctx.cwd, result, renderReport(ctx, parsed, result)));
+        return 0;
+    }
+    if (parsed.next !== undefined) {
+        writeNextReport(ctx, parsed, result, parsed.next);
+        return 0;
+    }
     if (parsed.json)
-        ctx.stdout.write(`${JSON.stringify(jsonReport(ctx, parsed, result, next), undefined, 2)}\n`);
+        ctx.stdout.write(`${JSON.stringify(jsonReport(ctx, parsed, result), undefined, 2)}\n`);
     else
-        ctx.stdout.write(renderReport(ctx, parsed, result, next));
+        ctx.stdout.write(renderReport(ctx, parsed, result));
     return 0;
 }
 function renderUsage(ctx) {
     return USAGE.replaceAll("{{FORM}}", ctx.form);
 }
 function parseTicketArgs(ctx, args, usage) {
+    const normalized = normalizeNextArgs(args);
     const { values, positionals } = parseCommandArgs(usage, () => parseArgs({
-        args,
+        args: normalized.args,
         options: {
-            next: { type: "string" },
+            next: { type: "boolean" },
             "new-cycle": { type: "boolean", default: false },
             json: { type: "boolean", default: false },
             "dry-run": { type: "boolean", default: false },
             side: { type: "boolean", default: false },
+            catchup: { type: "boolean", default: false },
             help: { type: "boolean", short: "h", default: false },
         },
         strict: true,
@@ -51,18 +65,46 @@ 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);
+    if (values.catchup && (values.next !== undefined || values.json || values["dry-run"]))
+        throw new CliError(`--catchup cannot be combined with --next, --json, or --dry-run.\n\n${usage}`);
+    if (normalized.filename !== undefined)
+        validateNextFilename(normalized.filename);
     const resolution = resolveTicketId(ctx, positionals[0], values.side, values["dry-run"]);
     return {
         ...resolution,
-        next: values.next,
+        next: values.next === undefined ? undefined : (normalized.filename ?? true),
         newCycle: values["new-cycle"],
         json: values.json,
         dryRun: values["dry-run"],
         side: values.side,
+        catchup: values.catchup,
     };
 }
+function normalizeNextArgs(args) {
+    const normalized = { args: [] };
+    for (let index = 0; index < args.length; ++index) {
+        const arg = args[index];
+        if (arg === "--") {
+            normalized.args.push(...args.slice(index));
+            break;
+        }
+        if (arg.startsWith("--next=")) {
+            normalized.filename = arg.slice("--next=".length);
+            normalized.args.push("--next");
+            continue;
+        }
+        normalized.args.push(arg);
+        if (arg !== "--next")
+            continue;
+        const following = args[index + 1];
+        delete normalized.filename;
+        if (following !== undefined && !following.startsWith("-")) {
+            normalized.filename = following;
+            ++index;
+        }
+    }
+    return normalized;
+}
 function validateNextFilename(filename) {
     if (filename.length === 0 || filename === "." || filename === ".." || /[\\/]/u.test(filename)) {
         throw new CliError("--next must be a non-empty single path segment.");
@@ -92,33 +134,55 @@ function resolveTicket(ctx, options) {
         };
     return resolveTicketDir(ctx.cwd, options.id, { dryRun: options.dryRun });
 }
-function jsonReport(ctx, options, result, next) {
+function writeNextReport(ctx, options, result, filename) {
+    const names = result.entries.map((entry) => entry.name);
+    const { cycleLetter, fileNumber } = nextFilePosition(names, options.newCycle);
+    const prefix = `${cycleLetter}${fileNumber}`;
+    const report = {
+        TICKET_DIR: `${relative(ctx.cwd, result.dir)}/`,
+        CYCLE_LETTER: cycleLetter,
+        FILE_NUMBER: fileNumber,
+        ...(filename === true ? { FILE_PREFIX: prefix } : { FILE_NAME: `${prefix}-${filename}` }),
+    };
+    if (options.json) {
+        ctx.stdout.write(`${JSON.stringify(report, undefined, 2)}\n`);
+        return;
+    }
+    const lines = Object.entries(report).map(([name, value]) => `- ${name}: \`${value}\``);
+    ctx.stdout.write(`${lines.join("\n")}\n`);
+}
+function jsonReport(ctx, options, result) {
     return {
-        id: result.id,
-        dir: relative(ctx.cwd, result.dir),
+        TICKET_ID: result.id,
+        TICKET_DIR: `${relative(ctx.cwd, result.dir)}/`,
         state: result.state,
         ...(options.branch === undefined ? {} : { branch: options.branch }),
-        entries: result.entries,
-        ...(next === undefined ? {} : { next: relative(ctx.cwd, join(result.dir, next)) }),
+        entries: result.entries.map((entry) => ({
+            ...entry,
+            modifiedAt: entry.modifiedAt.toISOString(),
+        })),
     };
 }
-function renderReport(ctx, options, result, next) {
+function renderReport(ctx, options, result) {
     const reservation = options.side && options.dryRun ? " (would be reserved)" : "";
     const deduction = options.branch === undefined ? "" : ` (deduced from branch ${options.branch})`;
     const directoryState = renderDirectoryState(result.state, options.dryRun);
     const directory = `${relative(ctx.cwd, result.dir)}/`;
     const lines = [
-        `Ticket ${result.id}${reservation}${deduction}`,
-        `Directory: ${directory}${directoryState}`,
+        `- TICKET_ID: \`${result.id}\`${reservation}${deduction}`,
+        `- TICKET_DIR: \`${directory}\`${directoryState}`,
     ];
     if (result.entries.length === 0)
         lines.push("Entries: (none)");
     else
-        lines.push("Entries:", ...result.entries.map((entry) => `  ${entry}`));
-    if (next !== undefined)
-        lines.push(`Next file: ${relative(ctx.cwd, join(result.dir, next))}`);
+        lines.push("Entries:", ...result.entries.map((entry) => `  ${renderEntry(entry)}`));
     return `${lines.join("\n")}\n`;
 }
+function renderEntry(entry) {
+    if (entry.size === undefined)
+        return entry.name;
+    return `${entry.name} (${formatSize(entry.size)}, ${formatLocalTimestamp(entry.modifiedAt)})`;
+}
 function renderDirectoryState(state, dryRun) {
     if (state === "existing")
         return "";

package/dist/conventions.js

@@ -38,9 +38,9 @@ function renderCommits(ctx) {
 }
 export function commitSubject(commit) {
     if (commit.ticketReference === "bracketed")
-        return { subject: "`type: [ticketId] summary`", side: "`type: summary` for `side-N`" };
+        return { subject: "`type: [TICKET_ID] 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: [#TICKET_ID] summary`", side: "`type: summary` for `side-N`" };
     return { subject: "`type: summary`" };
 }
 function renderPlans(ctx) {

package/dist/format.d.ts

@@ -0,0 +1,2 @@
+export declare function formatSize(bytes: number): string;
+export declare function formatLocalTimestamp(date: Date): string;

package/dist/format.js

@@ -0,0 +1,23 @@
+const KIB = 1024;
+const MIB = KIB * KIB;
+export function formatSize(bytes) {
+    if (bytes < KIB)
+        return `${bytes} B`;
+    if (bytes < MIB)
+        return `${trimDecimal(bytes / KIB)} KiB`;
+    return `${trimDecimal(bytes / MIB)} MiB`;
+}
+function trimDecimal(value) {
+    return value.toFixed(1).replace(/\.0$/, "");
+}
+export function formatLocalTimestamp(date) {
+    const offsetMinutes = -date.getTimezoneOffset();
+    const sign = offsetMinutes < 0 ? "-" : "+";
+    const offset = Math.abs(offsetMinutes);
+    const day = `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}`;
+    const time = `${pad(date.getHours())}:${pad(date.getMinutes())}`;
+    return `${day}T${time}${sign}${pad(Math.floor(offset / 60))}:${pad(offset % 60)}`;
+}
+function pad(value) {
+    return String(value).padStart(2, "0");
+}

package/dist/plans/catchup.d.ts

@@ -0,0 +1,2 @@
+import type { ResolvedTicketDir } from "./ticket.js";
+export declare function renderCatchup(cwd: string, ticket: ResolvedTicketDir, report: string): string;

package/dist/plans/catchup.js

@@ -0,0 +1,55 @@
+import { readFileSync } from "node:fs";
+import { join, relative } from "node:path";
+import { CliError } from "../cli-error.js";
+import { formatLocalTimestamp, formatSize } from "../format.js";
+const MAX_FILE_BYTES = 64 * 1024;
+const MAX_OUTPUT_BYTES = 30 * 1024;
+const PLAN_FILE = /^[A-Z]\d+-(?:main-plan|plan-.*)\.md$/;
+const OMISSION_NOTICE = `Content omitted: over the ${formatSize(MAX_FILE_BYTES)} limit.`;
+const TOO_LARGE_NOTICE = `History too large to print (over the ${formatSize(MAX_OUTPUT_BYTES)} budget). Read the relevant files among the entries above rather than all of them.`;
+export function renderCatchup(cwd, ticket, report) {
+    const files = ticket.entries.flatMap((entry) => catchupFile(cwd, ticket.dir, entry));
+    if (files.length === 0)
+        return `${report}\nNo Markdown files to load.\n`;
+    const outputBytes = files.reduce((total, file) => total + sectionBytes(file), Buffer.byteLength(report) + 1);
+    if (outputBytes > MAX_OUTPUT_BYTES)
+        return `${report}\n${TOO_LARGE_NOTICE}\n`;
+    return `${report}\n${files.map((file) => renderSection(cwd, file)).join("")}`;
+}
+function catchupFile(cwd, dir, entry) {
+    if (entry.size === undefined || !isHistoryFile(entry.name))
+        return [];
+    return [
+        {
+            path: relative(cwd, join(dir, entry.name)),
+            size: entry.size,
+            modified: formatLocalTimestamp(entry.modifiedAt),
+        },
+    ];
+}
+function isHistoryFile(name) {
+    return name.endsWith(".md") && (name.endsWith(".summary.md") || !PLAN_FILE.test(name));
+}
+function sectionBytes(file) {
+    const body = isOversized(file) ? Buffer.byteLength(OMISSION_NOTICE) : file.size;
+    return Buffer.byteLength(wrapSection(file, "")) + body;
+}
+function isOversized(file) {
+    return file.size > MAX_FILE_BYTES;
+}
+function wrapSection(file, body) {
+    return `<file path="${file.path}" modified="${file.modified}">\n${body}\n</file>\n\n`;
+}
+function renderSection(cwd, file) {
+    const body = isOversized(file) ? OMISSION_NOTICE : readBody(cwd, file);
+    return wrapSection(file, body.replace(/\n+$/, ""));
+}
+function readBody(cwd, file) {
+    try {
+        return readFileSync(join(cwd, file.path), "utf-8");
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new CliError(`Cannot load catchup file ${file.path}: ${detail}`);
+    }
+}

package/dist/plans/ticket.d.ts

@@ -2,7 +2,13 @@ export interface ResolvedTicketDir {
     id: string;
     dir: string;
     state: "existing" | "created" | "restored";
-    entries: string[];
+    entries: TicketEntry[];
+}
+/** `name` ends with a slash for a directory, which has no `size`. */
+export interface TicketEntry {
+    name: string;
+    size?: number;
+    modifiedAt: Date;
 }
 export interface ResolveTicketOptions {
     dryRun: boolean;
@@ -24,8 +30,12 @@ export type TicketDetection = {
 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(entries: readonly string[], filename: string, newCycle: boolean): string;
-export declare function listEntries(dir: string): string[];
+export interface NextFilePosition {
+    cycleLetter: string;
+    fileNumber: number;
+}
+export declare function nextFilePosition(entries: readonly string[], newCycle: boolean): NextFilePosition;
+export declare function listEntries(dir: string): TicketEntry[];
 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;

package/dist/plans/ticket.js

@@ -1,5 +1,5 @@
-import { existsSync, mkdirSync, readdirSync, renameSync, statSync } from "node:fs";
-import { join } from "node:path";
+import { existsSync, lstatSync, mkdirSync, readdirSync, renameSync, statSync, } from "node:fs";
+import { basename, join } from "node:path";
 import { CliError } from "../cli-error.js";
 import { isNodeError } from "../errors.js";
 import { gitOutputOrUndefined } from "../git.js";
@@ -7,6 +7,7 @@ import { archivesDir, plansDir } from "./layout.js";
 const FILE_PREFIX = /^([A-Z])(\d+)-/;
 const SIDE_TICKET = /^side-(\d+)$/;
 const PATH_SAFE_TICKET = /^[A-Za-z0-9._-]+$/;
+const ENTRY_ORDER = new Intl.Collator("en", { numeric: true });
 export function resolveTicketDir(cwd, id, { dryRun }) {
     const dir = join(plansDir(cwd), id);
     if (existsSync(dir))
@@ -63,25 +64,39 @@ function readEntries(dir) {
         return [];
     }
 }
-export function nextFileName(entries, filename, newCycle) {
+export function nextFilePosition(entries, 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)
-        return `A1-${filename}`;
+        return { cycleLetter: "A", fileNumber: 1 };
     const highestCycle = prefixes.reduce((highest, prefix) => (prefix.cycle > highest ? prefix.cycle : highest), "A");
     if (newCycle)
-        return `${String.fromCharCode(highestCycle.charCodeAt(0) + 1)}1-${filename}`;
+        return { cycleLetter: String.fromCharCode(highestCycle.charCodeAt(0) + 1), fileNumber: 1 };
     const highestNumber = Math.max(...prefixes.filter(({ cycle }) => cycle === highestCycle).map(({ number }) => number));
-    return `${highestCycle}${highestNumber + 1}-${filename}`;
+    return { cycleLetter: highestCycle, fileNumber: highestNumber + 1 };
 }
 export function listEntries(dir) {
     if (!existsSync(dir) || !statSync(dir).isDirectory())
         return [];
-    return readdirSync(dir, { withFileTypes: true })
-        .map((entry) => `${entry.name}${entry.isDirectory() ? "/" : ""}`)
-        .toSorted();
+    return readdirSync(dir)
+        .map((name) => describeEntry(join(dir, name)))
+        .toSorted((left, right) => ENTRY_ORDER.compare(left.name, right.name));
+}
+function describeEntry(path) {
+    const stat = statOrLink(path);
+    if (stat.isDirectory())
+        return { name: `${basename(path)}/`, modifiedAt: stat.mtime };
+    return { name: basename(path), size: stat.size, modifiedAt: stat.mtime };
+}
+function statOrLink(path) {
+    try {
+        return statSync(path);
+    }
+    catch {
+        return lstatSync(path);
+    }
 }
 export function isPathSafeTicketId(id) {
     return id !== "." && !id.includes("..") && PATH_SAFE_TICKET.test(id);

package/dist/protocols.d.ts

@@ -1,2 +1,2 @@
-export declare const PROTOCOLS: readonly ["spec", "plan", "aad", "catchup", "merge", "review", "description"];
+export declare const PROTOCOLS: readonly ["spec", "plan", "aad", "merge", "review", "description"];
 export type Protocol = (typeof PROTOCOLS)[number];

package/dist/protocols.js

@@ -1,9 +1 @@
-export const PROTOCOLS = [
-    "spec",
-    "plan",
-    "aad",
-    "catchup",
-    "merge",
-    "review",
-    "description",
-];
+export const PROTOCOLS = ["spec", "plan", "aad", "merge", "review", "description"];

package/dist/skills.d.ts

@@ -1,4 +1,4 @@
-export declare const STUB_SKILLS: readonly ["alignfirst", "alspec", "alplan", "al", "alcatchup", "almerge", "alreview", "aldescription"];
+export declare const STUB_SKILLS: readonly ["alignfirst", "alspec", "alplan", "al", "alcatchup", "alcatchupaad", "alcatchupspec", "almerge", "alreview", "aldescription"];
 export declare const SKILL_ROOTS: readonly [".agents/skills", ".claude/skills", ".codex/skills"];
 export interface InstalledSkill {
     root: string;

package/dist/skills.js

@@ -6,6 +6,8 @@ export const STUB_SKILLS = [
     "alplan",
     "al",
     "alcatchup",
+    "alcatchupaad",
+    "alcatchupspec",
     "almerge",
     "alreview",
     "aldescription",

package/package.json

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

package/templates/guide/core.md

@@ -1,54 +1,27 @@
-# AlignFirst Guide
+# Shared Conventions
 
-An agent that does not know which protocol to use runs `{{CMD}} guide overview`.
+## Ticket directory
 
-## Protocols
+TICKET_DIR holds a ticket's work files and includes a trailing slash. TICKET_ID is the external ticket ID or `side-N` for work without an external ticket.
 
-- **Technical Specification** (_spec_, or _alspec_): `{{CMD}} guide spec --protocol-only`
-- **Implementation Plans** (_plan_, or _alplan_): `{{CMD}} guide plan --protocol-only`
-- **Align-and-Do Protocol** (_AAD_): `{{CMD}} guide aad --protocol-only`
-- **Catch Up** (_catchup_, or _alcatchup_): `{{CMD}} guide catchup --protocol-only`
-- **Merge** (_merge_, or _almerge_): `{{CMD}} guide merge --protocol-only`
-- **Code Review** (_alreview_): `{{CMD}} guide review --protocol-only`
-- **Description** (_aldescription_): `{{CMD}} guide description --protocol-only`
+{{TICKET_DETECTION}}
 
-## TASK_DIR Location
-
-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_CONTEXT}}
+`{{TICKET_CMD}}` prints TICKET_DIR and its entries, creates a missing directory, and restores an archived one. Run it once to load the ticket directory context, unless `{{CMD}} ticket --catchup` already did.
 
 {{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.
-
-## File Naming Convention
+When the user says there is no external ticket, run `{{CMD}} ticket --side` and use the returned TICKET_ID in subsequent ticket commands. Reuse an existing `side-N` directory when the user refers to earlier work. Omit the ticket ID from commit messages.
 
-Format: `{CYCLE_LETTER}{FILE_NUMBER}-{FILE_TYPE}.md`
+## Work files
 
-**Common file types:**
+Files use `{CYCLE_LETTER}{FILE_NUMBER}-{FILE_TYPE}.md`. FILE_PREFIX combines the cycle letter and the file number within that cycle. FILE_NAME includes the prefix and extension.
 
-- `spec` - technical specification
-- `plan` - implementation plan
-- `AAD.summary` - AAD summary document
-- `description` - PR/MR description
-- `review` - code review report
-- `merge.summary` - merge conflicts resolution summary
+Immediately before creating each file, run `{{TICKET_CMD}} --next <filename>` with the extension included. It returns TICKET_DIR, CYCLE_LETTER, FILE_NUMBER, and FILE_NAME. Append FILE_NAME to TICKET_DIR to get the file path, preserving the leading dot and existing slash.
 
-**Example structure:**
+With no filename, `{{TICKET_CMD}} --next` returns FILE_PREFIX instead of FILE_NAME. Add `--new-cycle` to either form when the protocol or user calls for a new cycle.
 
-```text
-A1-spec.md
-A2-plan.md
-A3-AAD.summary.md
-B1-spec.md
-```
+Neither form reserves a number. Write the file before requesting another filename. With `--json`, the same information uses the same field names.
 
-## Notes
+Common file types are `spec`, `plan`, `AAD.summary`, `description`, `review`, and `merge.summary`. Use another type when needed.
 
-- **TICKET_ID** is a unique identifier for the task, often an issue or ticket number.
-- `{{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.
-- New file types are welcome.
+Cycle letters and file numbers are internal. Never discuss them with the user.

package/templates/guide/overview.md

@@ -8,8 +8,8 @@ AlignFirst is a set of collaborative protocols for working with a user on coding
 
 The standard workflow for most tasks. It produces formal artifacts at each stage:
 
-1. **Spec** (`/alspec`): Investigate the codebase, discuss with the user, then write a technical specification. There are usually several back-and-forths before the spec is written.
-2. **Plan** (`/alplan`): Read the spec, investigate further, then write implementation plan(s). The plan is a self-contained prompt for the implementing agent.
+1. **Spec** (`alspec` alias): Investigate the codebase, discuss with the user, then write a technical specification. There are usually several back-and-forths before the spec is written.
+2. **Plan** (`alplan` alias): Read the spec, investigate further, then write implementation plan(s). The plan is a self-contained prompt for the implementing agent.
 3. **Execute**: A new session implements the plan and writes a handover document summarizing the changes.
 
 After execution, additional rounds of AAD (see below) can address follow-up fixes or adjustments.
@@ -18,7 +18,7 @@ After execution, additional rounds of AAD (see below) can address follow-up fixe
 
 For smaller tasks that don't justify a formal spec and plan. Everything happens in one session: investigate, discuss, implement, summarize.
 
-Use AAD (`/al`) when:
+Use AAD (`al` alias) when:
 
 - The task is small or well-understood
 - It's a follow-up change after a plan has already been executed
@@ -32,19 +32,21 @@ Use Spec-Plan-Execute when:
 
 ## Catch Up
 
-A standalone utility (`/alcatchup`). It loads the ticket's history from its requests, specs, and summaries. It then follows the user's instructions or returns a short synthesis. To continue directly into a light workflow, use `/alcatchup then start an AAD: …`.
+`{{CMD}} ticket --catchup` loads the ticket's history: its requests, specs, reviews and summaries, without the plans. When the history is too large, the command lists the files instead and the agent reads the relevant ones.
+
+The `alcatchup` alias loads this context, then follows the user's instructions or returns a short synthesis. `alcatchupaad` and `alcatchupspec` load it, then start AAD or a specification.
 
 ## Description
 
-A standalone utility (`/aldescription`). It reads specs and summaries that have been generated for a ticket and produces a concise description of what was implemented. Typically used to generate a PR/MR description once the work is done.
+A standalone utility (`aldescription` alias). It reads specs and summaries that have been generated for a ticket and produces a concise description of what was implemented. Typically used to generate a PR/MR description once the work is done.
 
 ## Code Review
 
-A standalone utility (`/alreview`). It compares the current branch to a base branch (defaults to the repo's default branch) and runs parallel reviewers, each with its own perspective: intent, correctness, change safety, code quality. Ecosystem modules (strict TypeScript, JavaScript, Python) sharpen the language-specific checks. The findings are merged into a concise review report.
+A standalone utility (`alreview` alias). It compares the current branch to a base branch (defaults to the repo's default branch) and runs parallel reviewers, each with its own perspective: intent, correctness, change safety, code quality. Ecosystem modules (strict TypeScript, JavaScript, Python) sharpen the language-specific checks. The findings are merged into a concise review report.
 
 ## Merge
 
-A standalone utility (`/almerge`). After a merge or rebase, the agent investigates both sides, resolves the conflicts (with a special case for lock files), and writes a brief summary of the resolutions.
+A standalone utility (`almerge` alias). After a merge or rebase, the agent investigates both sides, resolves the conflicts (with a special case for lock files), and writes a brief summary of the resolutions.
 
 ## Typical Lifecycle of a Ticket
 

package/templates/guide/protocols/aad.md

@@ -2,12 +2,7 @@
 
 ## Pre-requisites
 
-You need:
-
-- the TASK_DIR — run `{{TICKET_CMD}}` (`{{CMD}} ticket --side` when there is no ticket)
-- the CYCLE_LETTER and FILE_NUMBER — continue the current cycle: `{{TICKET_CMD}} --next AAD.summary.md` prints the file to create
-
-Identify and state these values before starting the protocol.
+Run `{{TICKET_CMD}}` once to identify TICKET_DIR and load the ticket directory context (`{{CMD}} ticket --side` when there is no external ticket).
 
 ---
 
@@ -42,9 +37,7 @@ Do not use your question tool. Always ask in plain text. Your questions will be
 
 ## 3. Act
 
-When you and the user agree, create the summary file in TASK_DIR, then start implementing.
-
-Compose the filename using the current CYCLE_LETTER and the bumped FILE_NUMBER, then append `-AAD.summary.md`. For example, if the last file is `E5-plan-something.md`, create `E6-AAD.summary.md`. Do not overwrite an existing file.
+When you and the user agree, run `{{TICKET_CMD}} --next AAD.summary.md` to continue the current cycle. Append FILE_NAME to TICKET_DIR, then immediately create the summary file at that path. Do not overwrite an existing file. Start implementing after creating it.
 
 Maintain the file as a **live report** while you work.
 

package/templates/guide/protocols/description.md

@@ -2,18 +2,13 @@
 
 ## Pre-requisites
 
-You need:
-
-- the TASK_DIR — run `{{TICKET_CMD}}` (`{{CMD}} ticket --side` when there is no ticket)
-- the CYCLE_LETTER and FILE_NUMBER — start a new cycle: `{{TICKET_CMD}} --next description.md --new-cycle` prints the file to create
-
-Identify and state these values before starting the protocol.
+Run `{{TICKET_CMD}}` once to identify TICKET_DIR and load the ticket directory context (`{{CMD}} ticket --side` when there is no external ticket).
 
 ## Steps
 
-1. Find the current ticket plan directory.
-2. Create your description as a new file `{CYCLE_LETTER}1-description.md` with the next cycle letter, containing just the header — this reserves the filename.
-3. If a previous `*description.md` file exists in the TASK_DIR, find the latest one. Only read `*spec.md` and `*summary.md` files that come *after* it — earlier work is already covered.
+1. Run `{{TICKET_CMD}} --next description.md --new-cycle` to start a new cycle.
+2. Append FILE_NAME to TICKET_DIR, then immediately create the description at that path with just the header. Creating the file reserves the filename.
+3. If a previous `*description.md` file exists in the TICKET_DIR, find the latest one. Only read `*spec.md` and `*summary.md` files that come *after* it — earlier work is already covered.
    Otherwise, read all `*spec.md` and `*summary.md` files.
 4. Write the commit message and description into your file.
 

package/templates/guide/protocols/merge.md

@@ -2,12 +2,7 @@
 
 ## Pre-requisites
 
-You need:
-
-- the TASK_DIR — run `{{TICKET_CMD}}` (`{{CMD}} ticket --side` when there is no ticket)
-- the CYCLE_LETTER and FILE_NUMBER — continue the current cycle: `{{TICKET_CMD}} --next merge.summary.md` prints the file to create
-
-Identify and state these values before starting the protocol.
+Run `{{TICKET_CMD}}` once to identify TICKET_DIR and load the ticket directory context (`{{CMD}} ticket --side` when there is no external ticket).
 
 ---
 
@@ -25,7 +20,7 @@ Take the time to understand how things work in the incoming branch and in the cu
 
 ## 3. Resolve
 
-Create the summary file now: a new file `{CYCLE_LETTER}{FILE_NUMBER}-merge.summary.md` in the TASK_DIR. Log each notable resolution in it as you resolve (see step 5 for the expected content).
+Run `{{TICKET_CMD}} --next merge.summary.md` to continue the current cycle. Append FILE_NAME to TICKET_DIR, then immediately create the summary at that path. Log each notable resolution in it as you resolve (see step 5 for the expected content).
 
 Resolve the conflicts properly — preserve both intents whenever possible. Do not blindly accept one side.
 

package/templates/guide/protocols/plan.md

@@ -2,15 +2,14 @@
 
 ## Pre-requisites
 
-### Determine TASK_DIR, CYCLE_LETTER, and FILE_NUMBER
+### Determine TICKET_DIR and the spec file
 
 You need:
 
-- the TASK_DIR — run `{{TICKET_CMD}}` (`{{CMD}} ticket --side` when there is no ticket)
-- the CYCLE_LETTER and FILE_NUMBER — continue the current cycle: `{{TICKET_CMD}} --next plan.md` or `{{TICKET_CMD}} --next main-plan.md` prints the file to create
-- a **spec file** in the TASK_DIR
+- the TICKET_DIR and ticket directory context — run `{{TICKET_CMD}}` once (`{{CMD}} ticket --side` when there is no external ticket)
+- a **spec file** in the TICKET_DIR
 
-Identify and state these values before starting the protocol. If any of these pieces of information is missing, STOP AND ASK THE USER.
+Identify TICKET_DIR and the spec file before starting the protocol. If either is missing, STOP AND ASK THE USER.
 
 ## Phases
 
@@ -113,13 +112,13 @@ Example:
 _For all plans (single or specialized)_, add a final step named "Write a Handover Document" with this content:
 
 ```markdown
-Write a **handover document**. This document must contain the list of all files you updated. Also, summarize the changes made in a very concise way. Add only relevant information that will help your teammates understand what's new. Do not mention obvious information. It's not a course or a tutorial, if there is nothing to explain, then do not explain. Write this handover document in `{PLAN_FILE_PATH}.summary.md`. Ignore lint errors (formatting issues) in this file. At the end, give the path of this handover file to the user.
+Write a **handover document**. This document must contain the list of all files you updated. Also, summarize the changes made in a very concise way. Add only relevant information that will help your teammates understand what's new. Do not mention obvious information. It's not a course or a tutorial, if there is nothing to explain, then do not explain. Create its path by replacing the final `.md` in `{PLAN_FILE_PATH}` with `.summary.md`, then write the handover there. Ignore lint errors (formatting issues) in this file. At the end, give the path of this handover file to the user.
 ```
 
 Note:
 
 - This is a regular step, it should be numbered like the other steps. For example, if your plan has 5 steps, this becomes step 6.
-- Replace "{PLAN_FILE_PATH}" with the actual plan file path without extension (e.g., for plan `.plans/123/A2-plan-backend.md`, use `.plans/123/A2-plan-backend`, resulting in `.plans/123/A2-plan-backend.summary.md`).
+- Replace "{PLAN_FILE_PATH}" with the complete plan file path, such as `.plans/123/A2-plan-backend.md`. Its handover path is `.plans/123/A2-plan-backend.summary.md`.
 
 ### 3.5 Common Footer for All Plans
 
@@ -193,7 +192,7 @@ Write a **main plan handover document**. This document should:
    - State "Completed" if the plan was executed successfully
    - Detail any issues encountered during execution
 
-Keep this handover very short. Do not combine or repeat the content of individual handovers. Write this document in `{PLAN_FILE_PATH}.summary.md`. Ignore lint errors (formatting issues) in this file.
+Keep this handover very short. Do not combine or repeat the content of individual handovers. Create its path by replacing the final `.md` in `{PLAN_FILE_PATH}` with `.summary.md`, then write the handover there. Ignore lint errors (formatting issues) in this file.
 
 ---
 
@@ -204,34 +203,33 @@ Do not trust this plan blindly. Be sure you understand the codebase and all spec
 
 Note:
 
-- Replace "{PLAN_FILE_PATH}" with the actual plan file path without extension (e.g., for plan `.plans/123/A2-main-plan.md`, use `.plans/123/A2-main-plan`, resulting in `.plans/123/A2-main-plan.summary.md`)
+- Replace "{PLAN_FILE_PATH}" with the complete plan file path, such as `.plans/123/A2-main-plan.md`. Its handover path is `.plans/123/A2-main-plan.summary.md`.
 
 ## Phase 5. Writing Phase
 
 Write the plan file(s) according to the determined structure:
 
-Use `{{TICKET_CMD}} --next plan.md`, `{{TICKET_CMD}} --next main-plan.md`, or `{{TICKET_CMD}} --next plan-<descriptor>.md` to get the next number. Run one command per file.
+Continue the current cycle. Immediately before writing each file, run `{{TICKET_CMD}} --next plan.md`, `{{TICKET_CMD}} --next main-plan.md`, or `{{TICKET_CMD}} --next plan-<descriptor>.md`. Append FILE_NAME to TICKET_DIR to get its path. Write that file before requesting the next one.
 
 **Single Plan**:
 
-- **Single plan**: `{TASK_DIR}/{CYCLE_LETTER}{FILE_NUMBER}-plan.md`
+- **Single plan**: `{TICKET_DIR}{CYCLE_LETTER}{FILE_NUMBER}-plan.md`
   - Example: `.plans/123/A2-plan.md`
   - Handover: `.plans/123/A2-plan.summary.md`
   - No main plan needed
 
 **Multiple Plans**:
 
-- **Main plan**: `{TASK_DIR}/{CYCLE_LETTER}{FILE_NUMBER}-main-plan.md`
+- **Main plan**: `{TICKET_DIR}{CYCLE_LETTER}{FILE_NUMBER}-main-plan.md`
   - Example: `.plans/123/A2-main-plan.md`
   - Handover: `.plans/123/A2-main-plan.summary.md` (written after all specialized plans complete)
-- **Specialized plans**: `{TASK_DIR}/{CYCLE_LETTER}{FILE_NUMBER}-plan-{DESCRIPTOR}.md`
+- **Specialized plans**: `{TICKET_DIR}{CYCLE_LETTER}{FILE_NUMBER}-plan-{DESCRIPTOR}.md`
   - Use a descriptive name as `{DESCRIPTOR}` (e.g., work scope, stack area)
   - Example: `.plans/123/A3-plan-api.md`, `.plans/123/A4-plan-ui.md`
   - Handovers: `.plans/123/A3-plan-api.summary.md`, etc.
 
 **Important**:
 
-- Increment FILE_NUMBER for each plan file
 - Use lowercase, hyphenated descriptors for plan names (work scope descriptor)
 - When multiple plans are created, the main plan should be written first and have the lowest FILE_NUMBER
 - Be careful never to overwrite an existing file

package/templates/guide/protocols/review.md

@@ -4,19 +4,18 @@
 
 You need:
 
-- the TASK_DIR — run `{{TICKET_CMD}}` (`{{CMD}} ticket --side` when there is no ticket)
-- the CYCLE_LETTER and FILE_NUMBER — start a new cycle: `{{TICKET_CMD}} --next review.md --new-cycle` prints the file to create
+- the TICKET_DIR and ticket directory context — run `{{TICKET_CMD}}` once (`{{CMD}} ticket --side` when there is no external ticket)
 - {{BASE_BRANCH_RULE}}
 
-Identify and state these values before starting the protocol.
+Identify TICKET_DIR and the base branch before starting the protocol.
 
 ## Overview
 
 We need a code review for this branch, compared to the base branch. A code review, above all, guarantees that the codebase stays healthy.
 
-You are the orchestrator: you scope the work, run one reviewer subagent per perspective, then merge their findings into a single report. Reviewers work with fresh eyes — they derive intent from the code and the diff. Neither you nor the reviewers read specs, plans, summaries, or any file content in TASK_DIR.
+You are the orchestrator: you scope the work, run one reviewer subagent per perspective, then merge their findings into a single report. Reviewers work with fresh eyes — they derive intent from the code and the diff. Neither you nor the reviewers read specs, plans, summaries, or any file content in TICKET_DIR.
 
-Before starting, create your report as a new file `{CYCLE_LETTER}1-review.md` in the TASK_DIR, containing just the header — this reserves the filename. Write the report into it at the end.
+Before starting, run `{{TICKET_CMD}} --next review.md --new-cycle` to start a new cycle. Append FILE_NAME to TICKET_DIR, then immediately create the report at that path with just the header. Creating the file reserves the filename. Write the report into it at the end.
 
 ## Phase 1. Scoping
 

package/templates/guide/protocols/spec.md

@@ -2,12 +2,7 @@
 
 ## Pre-requisites
 
-You need:
-
-- the TASK_DIR — run `{{TICKET_CMD}}` (`{{CMD}} ticket --side` when there is no ticket)
-- the CYCLE_LETTER and FILE_NUMBER — start a new cycle: `{{TICKET_CMD}} --next spec.md --new-cycle` prints the file to create
-
-Identify and state these values before starting the protocol.
+Run `{{TICKET_CMD}}` once to identify TICKET_DIR and load the ticket directory context (`{{CMD}} ticket --side` when there is no external ticket).
 
 ## Phases
 
@@ -49,7 +44,7 @@ Do not use your question tool. Always ask in plain text. Your questions will be
 
 ## Phase 3. Specification Phase
 
-After the user approves your proposal, write the specification in a markdown file in TASK_DIR. Compose the filename with the current CYCLE_LETTER and the next FILE_NUMBER, e.g. `A1-spec.md`. Do not overwrite an existing file.
+After the user approves your proposal, run `{{TICKET_CMD}} --next spec.md --new-cycle` to start a new cycle. Append FILE_NAME to TICKET_DIR, then immediately write the specification at that path. Do not overwrite an existing file.
 
 - After the title, include a suggested commit message {{COMMIT_RULE}}. The shorter the better. Then list the required documentation and skills. List each doc file individually — never a folder. Always exclude `alignfirst` from skills. Omit any field with nothing to list. Example:
 

package/templates/guide/selection.md

@@ -0,0 +1,19 @@
+# AlignFirst Guide
+
+Follow the requested protocol if its guide is already in context. Otherwise, load it with the command below. Each named guide includes its protocol and shared conventions; add `--protocol-only` when those conventions are already in context.
+
+## Choose a protocol
+
+Use spec → plan → execution for most tasks, especially when the design is uncertain. Use AAD for small changes or follow-up work. Execute a written plan in a fresh agent session.
+
+| Protocol | Purpose | Command |
+| --- | --- | --- |
+| Specification (`alspec` alias) | Investigate, discuss, and write a technical specification. | `{{CMD}} guide spec` |
+| Planning (`alplan` alias) | Turn a specification into implementation plans. | `{{CMD}} guide plan` |
+| Align-and-Do (`AAD`, `al` aliases) | Investigate, agree, implement, and summarize a small change. | `{{CMD}} guide aad` |
+| Merge (`almerge` alias) | Merge an incoming branch and resolve conflicts. | `{{CMD}} guide merge` |
+| Review (`alreview` alias) | Review committed branch changes against a base branch. | `{{CMD}} guide review` |
+| Description (`aldescription` alias) | Write a concise description of implemented work. | `{{CMD}} guide description` |
+| Catch up (`alcatchup`, `alcatchupaad`, `alcatchupspec` aliases) | Load the ticket history, then continue, start AAD, or start a specification. | `{{CMD}} ticket --catchup` |
+
+For more detail on workflows and the ticket lifecycle, read `{{CMD}} guide overview`.

package/templates/guide/protocols/catchup.md

@@ -1,13 +0,0 @@
-# How to Catch Up With a Task
-
-## Pre-requisites
-
-You need the TASK_DIR — run `{{TICKET_CMD}}` (`{{CMD}} ticket --side` when there is no ticket).
-
-## Steps
-
-1. Determine TASK_DIR.
-2. Read every `*request.md`, `*spec.md` and `*summary.md` file in TASK_DIR, in filename order.
-3. When the user's message carries instructions, follow them with this context loaded, and write no synthesis. Otherwise reply with a short synthesis: what was requested, what was decided, what was done, what remains or is open.
-
-This protocol writes no file.