alignfirst 0.1.0-beta.5 → 0.1.0-beta.7

package/README.md

@@ -1,6 +1,6 @@
 # alignfirst
 
-The AlignFirst CLI provides collaborative software-development workflows, task files, shared plans, project conventions, documentation discovery, and setup diagnostics.
+The AlignFirst CLI provides collaborative software-development workflows, work files, and documentation discovery. Work files are organized by ticket and kept either git-ignored in the project or synchronized through a team repository.
 
 ## Installation
 
@@ -40,26 +40,32 @@ The guide installs the selected components and configures the repository. Remove
 - `plans` — Set up, check and archive plans.
 - `docmap` — Browse project documentation.
 - `conventions` — Print the effective project conventions.
-- `context` — Print the conventions and the documentation map.
+- `context` — Print the conventions, the documentation map when `docs/` exists, and the protocol aliases.
 - `config` — Report the effective project configuration.
 - `doctor` — Diagnose an AlignFirst setup.
 
-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.
+Run `alignfirst --help` for command usage or `alignfirst guide` to choose a protocol. `alignfirst guide <protocol>` prints the selected protocol followed by the ticket directory and work file rules. Add `--protocol-only` when those rules are already in context.
 
 ## Agent skills
 
-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`.
+Nine optional Agent Skill stubs expose the CLI as commands in Claude Code, Codex, GitHub Copilot, and Cursor. 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 al --skill alplan --skill alspec --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 `$`.
+Install the `alignfirst` skill when a project's `AGENTS.md` does not run `npx alignfirst context`; it lets the agent recognize a protocol named in prose:
+
+```sh
+npx skills add https://github.com/paleo/alignfirst --global --skill alignfirst
+```
+
+Start a new agent session to load the skills.
 
 ## Workflows
 
@@ -73,9 +79,9 @@ These examples use the `/` form. Replace it with `$` in Codex.
 | Description | `/aldescription` | Summarize the work and propose a commit message. |
 | 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. |
+| Catch up | `/alcatchup` | Load the current ticket history and continue. |
+| Catch up and AAD | `/alcatchupaad <request>` | Load ticket history, then start AAD. |
+| Catch up and spec | `/alcatchupspec <request>` | Load ticket history, then start specification. |
 
 To implement a plan, start a fresh agent context and ask it to execute the plan file.
 

package/dist/commands/context.js

@@ -1,3 +1,6 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { renderCommandForm } from "../command-form.js";
 import { renderConventions } from "../conventions.js";
 import { parseBareCommandArgs } from "../parse-args.js";
 import { runDocmap } from "./docmap.js";
@@ -5,7 +8,16 @@ export function runContext(ctx, args) {
     const usage = `Usage: ${ctx.form} context\n`;
     if (parseBareCommandArgs(ctx, args, usage))
         return 0;
-    ctx.stdout.write(renderConventions(ctx));
-    ctx.stdout.write("\n");
+    ctx.stdout.write(`# Project Conventions\n\n${renderConventions(ctx)}`);
+    const code = existsSync(join(ctx.cwd, "docs")) ? writeDocmapSection(ctx) : 0;
+    ctx.stdout.write(`\n${renderProtocolsSection(ctx)}`);
+    return code;
+}
+function writeDocmapSection(ctx) {
+    ctx.stdout.write("\n# Docmap Usage\n\n");
     return runDocmap(ctx, []);
 }
+function renderProtocolsSection(ctx) {
+    const template = readFileSync(new URL("../../templates/context/protocols.md", import.meta.url), "utf-8");
+    return renderCommandForm(template, ctx.form);
+}

package/dist/commands/guide.js

@@ -107,7 +107,7 @@ function renderGuide(ctx, options) {
     const [title, ...sections] = protocol.split("\n\n");
     return [
         title,
-        "This guide includes the selected protocol and shared conventions. Read both before starting.",
+        "This guide includes the selected protocol, followed by the ticket directory and work file rules. Read both before starting.",
         ...sections,
         core,
     ].join("\n\n");
@@ -124,7 +124,7 @@ function renderCoreGuide(ctx, placeholders) {
     const core = applyPlaceholders(readGuideTemplate("core.md"), placeholders);
     if (ctx.projectConfig !== undefined)
         return core;
-    return `${core.trimEnd()}\n\n## Project conventions\n\n${renderConventions(ctx).trimEnd()}`;
+    return `${core.trimEnd()}\n\n## Project Conventions\n\n${renderConventions(ctx).trimEnd()}`;
 }
 function buildGuidePlaceholders(ctx, protocol) {
     const pattern = ctx.projectConfig?.config.ticketIdPattern;

package/dist/commands/plans.js

@@ -5,6 +5,7 @@ import { CliError } from "../cli-error.js";
 import { assertMainWorktreeRoot } from "../git.js";
 import { parseBareCommandArgs, parseCommandArgs } from "../parse-args.js";
 import { archiveEntry, archiveThresholdDays, autoArchive } from "../plans/archive.js";
+import { isTicketName } from "../plans/layout.js";
 import { linkPlans } from "../plans/link.js";
 import { resolvePlansMode } from "../plans/mode.js";
 import { findStoppedRebase, renderStoppedRebase } from "../plans/rebase.js";
@@ -156,9 +157,10 @@ function resolveArchiveTarget(ctx, args, usage) {
     const stats = statSync(target, { throwIfNoEntry: false });
     if (!stats?.isDirectory() || realpathSync(dirname(target)) !== realpathSync(plansDir))
         throw new CliError(`${argument} must be an existing directory directly under .plans.`);
-    if (basename(target).startsWith("_"))
+    const name = basename(target);
+    if (!isTicketName(name))
         throw new CliError(`${argument}: names starting with _ are not tickets.`);
-    return target;
+    return join(plansDir, name);
 }
 function isPathArgument(argument) {
     return argument.includes("/") || argument.includes("\\");

package/dist/commands/ticket.js

@@ -5,22 +5,22 @@ 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, nextFilePosition, peekSideTicket, reserveSideTicket, resolveTicketDir, validateTicketId, } from "../plans/ticket.js";
+import { deduceTicketFromBranch, deduceTicketFromExisting, 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 [--next [<filename>]] [--new-cycle] [--json] [--dry-run]
-  {{FORM}} ticket [<id> | --side] --catchup
+  {{FORM}} ticket [<id>] --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);
     const usage = renderUsage(ctx);
     const parsed = parseTicketArgs(ctx, args, usage);
     if (parsed === undefined)
         return 0;
+    assertPlansGate(ctx.cwd, ctx.form);
     const result = resolveTicket(ctx, parsed);
     if (parsed.catchup) {
         ctx.stdout.write(renderCatchup(ctx.cwd, result, renderReport(ctx, parsed, result)));
@@ -65,11 +65,12 @@ 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.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 (values.catchup &&
+        (values.side || values.next !== undefined || values.json || values["dry-run"]))
+        throw new CliError(`--catchup cannot be combined with --side, --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"]);
+    const resolution = resolveTicketId(ctx, positionals[0], values);
     return {
         ...resolution,
         next: values.next === undefined ? undefined : (normalized.filename ?? true),
@@ -110,16 +111,16 @@ function validateNextFilename(filename) {
         throw new CliError("--next must be a non-empty single path segment.");
     }
 }
-function resolveTicketId(ctx, positional, side, dryRun) {
+function resolveTicketId(ctx, positional, flags) {
     const pattern = ctx.projectConfig?.config.ticketIdPattern;
     if (positional !== undefined) {
         validateTicketId(positional, pattern);
         return { id: positional };
     }
-    if (side)
-        return { id: dryRun ? peekSideTicket(ctx.cwd) : reserveSideTicket(ctx.cwd) };
+    if (flags.side)
+        return { id: flags["dry-run"] ? peekSideTicket(ctx.cwd) : reserveSideTicket(ctx.cwd) };
     if (pattern === undefined)
-        throw new CliError("No ticket id given. Pass it.");
+        return deduceTicketFromExisting(ctx.cwd, { sideAllowed: !flags.catchup });
     const deduced = deduceTicketFromBranch(ctx.cwd, pattern);
     validateTicketId(deduced.id, pattern);
     return deduced;

package/dist/conventions.js

@@ -1,6 +1,7 @@
 import { existsSync, lstatSync } from "node:fs";
 import { join } from "node:path";
 import { renderDefaultBranchLine, resolveDefaultBranch } from "./default-branch.js";
+import { errorMessage } from "./errors.js";
 import { gitOutputOrUndefined, gitSucceeds } from "./git.js";
 import { resolvePlansMode } from "./plans/mode.js";
 export function renderConventions(ctx) {
@@ -59,8 +60,7 @@ function renderPlans(ctx) {
         return `${base}${archival}`;
     }
     catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        return `Plans: ${message.split("\n", 1)[0]}`;
+        return `Plans: ${errorMessage(error).split("\n", 1)[0]}`;
     }
 }
 function plansEntryExists(cwd) {

package/dist/plans/catchup.js

@@ -1,6 +1,7 @@
 import { readFileSync } from "node:fs";
 import { join, relative } from "node:path";
 import { CliError } from "../cli-error.js";
+import { errorMessage } from "../errors.js";
 import { formatLocalTimestamp, formatSize } from "../format.js";
 const MAX_FILE_BYTES = 64 * 1024;
 const MAX_OUTPUT_BYTES = 30 * 1024;
@@ -49,7 +50,6 @@ function readBody(cwd, file) {
         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}`);
+        throw new CliError(`Cannot load catchup file ${file.path}: ${errorMessage(error)}`);
     }
 }

package/dist/plans/layout.d.ts

@@ -1,9 +1,11 @@
+import { type Stats } from "node:fs";
 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;
+/** Returns the lstat of `.plans`, so callers can tell a symlink from a directory. */
+export declare function assertPlansGate(cwd: string, form: string): Stats;
 export declare function missingPlansMessage(form: string): string;
 export declare function missingPlansError(form: string): CliError;

package/dist/plans/layout.js

@@ -1,4 +1,4 @@
-import { existsSync } from "node:fs";
+import { existsSync, lstatSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { CliError } from "../cli-error.js";
 export const PLANS_DIR = ".plans";
@@ -12,10 +12,17 @@ export function plansDir(cwd) {
 export function archivesDir(cwd) {
     return join(plansDir(cwd), ARCHIVES_DIR);
 }
+/** Returns the lstat of `.plans`, so callers can tell a symlink from a directory. */
 export function assertPlansGate(cwd, form) {
-    if (existsSync(plansDir(cwd)))
-        return;
-    throw missingPlansError(form);
+    const path = plansDir(cwd);
+    const stats = lstatSync(path, { throwIfNoEntry: false });
+    if (!stats)
+        throw missingPlansError(form);
+    if (stats.isSymbolicLink() && !existsSync(path))
+        throw new CliError(`The .plans symlink is broken. Re-run ${form} plans setup with the clone location.`);
+    if (!statSync(path).isDirectory())
+        throw new CliError(`.plans is not a directory. Remove it, then run ${form} plans setup (see the project documentation).`);
+    return stats;
 }
 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>`;

package/dist/plans/mode.js

@@ -1,17 +1,11 @@
-import { existsSync, lstatSync, realpathSync, statSync } from "node:fs";
+import { realpathSync } from "node:fs";
 import { join } from "node:path";
 import { CliError } from "../cli-error.js";
 import { gitOutput } from "../git.js";
-import { missingPlansError } from "./layout.js";
+import { assertPlansGate } from "./layout.js";
 export function resolvePlansMode(cwd, form) {
     const plansPath = join(cwd, ".plans");
-    const stats = lstatSync(plansPath, { throwIfNoEntry: false });
-    if (!stats)
-        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())
-        throw new CliError(`.plans is not a directory. Remove it, then run ${form} plans setup (see the project documentation).`);
+    const stats = assertPlansGate(cwd, form);
     if (plansRepositoryId(plansPath, stats.isSymbolicLink(), form) === repositoryId(cwd))
         return { kind: "local" };
     return { kind: "shared", repoToplevel: gitOutput(plansPath, "rev-parse", "--show-toplevel") };

package/dist/plans/ticket.d.ts

@@ -39,4 +39,9 @@ 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;
+export interface DeduceFromExistingOptions {
+    sideAllowed: boolean;
+}
+/** Without a ticket id pattern, the branch can still name an existing ticket directory. */
+export declare function deduceTicketFromExisting(cwd: string, { sideAllowed }: DeduceFromExistingOptions): DeducedTicket;
 export declare function deduceTicketFromBranch(cwd: string, pattern: string): DeducedTicket;

package/dist/plans/ticket.js

@@ -2,12 +2,15 @@ import { existsSync, lstatSync, mkdirSync, readdirSync, renameSync, statSync, }
 import { basename, join } from "node:path";
 import { CliError } from "../cli-error.js";
 import { isNodeError } from "../errors.js";
+import { formatLocalTimestamp } from "../format.js";
 import { gitOutputOrUndefined } from "../git.js";
-import { archivesDir, plansDir } from "./layout.js";
+import { archivesDir, isTicketName, 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 });
+const BRANCH_SEPARATORS = "[/_.-]";
+const LISTED_TICKETS = 10;
 export function resolveTicketDir(cwd, id, { dryRun }) {
     const dir = join(plansDir(cwd), id);
     if (existsSync(dir))
@@ -102,14 +105,14 @@ export function isPathSafeTicketId(id) {
     return id !== "." && !id.includes("..") && PATH_SAFE_TICKET.test(id);
 }
 export function validateTicketId(id, pattern) {
-    if (!isPathSafeTicketId(id))
+    if (!isPathSafeTicketId(id) || !isTicketName(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 ticketIdPattern "${pattern}".`);
 }
 export function detectTicketFromBranch(cwd, pattern) {
-    const branch = gitOutputOrUndefined(cwd, "branch", "--show-current");
-    if (branch === undefined || branch === "")
+    const branch = currentBranch(cwd);
+    if (branch === undefined)
         return { kind: "noBranch" };
     const unanchored = pattern.replace(/^\^/, "").replace(/\$$/, "");
     const match = new RegExp(unanchored).exec(branch);
@@ -117,6 +120,61 @@ export function detectTicketFromBranch(cwd, pattern) {
         return { kind: "noMatch", branch };
     return { kind: "detected", id: match[0], branch };
 }
+function currentBranch(cwd) {
+    const branch = gitOutputOrUndefined(cwd, "branch", "--show-current");
+    return branch === undefined || branch === "" ? undefined : branch;
+}
+/** Without a ticket id pattern, the branch can still name an existing ticket directory. */
+export function deduceTicketFromExisting(cwd, { sideAllowed }) {
+    const tickets = listTickets(cwd);
+    const branch = currentBranch(cwd);
+    if (branch !== undefined) {
+        const matches = tickets.filter((ticket) => branchNamesTicket(branch, ticket.id));
+        if (matches.length === 1)
+            return { id: matches[0].id, branch };
+    }
+    throw new CliError(renderMissingTicketId(tickets, sideAllowed));
+}
+function listTickets(cwd) {
+    return [
+        ...ticketDirectories(plansDir(cwd), false),
+        ...ticketDirectories(archivesDir(cwd), true),
+    ].toSorted((left, right) => right.modifiedAt.getTime() - left.modifiedAt.getTime());
+}
+function ticketDirectories(dir, archived) {
+    return readEntries(dir)
+        .filter((entry) => entry.isDirectory() && isTicketName(entry.name))
+        .map((entry) => ({
+        id: entry.name,
+        archived,
+        modifiedAt: newestModification(join(dir, entry.name)),
+    }));
+}
+function newestModification(dir) {
+    const entries = listEntries(dir);
+    if (entries.length === 0)
+        return statSync(dir).mtime;
+    return new Date(Math.max(...entries.map((entry) => entry.modifiedAt.getTime())));
+}
+function branchNamesTicket(branch, id) {
+    const escaped = id.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    return new RegExp(`(^|${BRANCH_SEPARATORS})${escaped}($|${BRANCH_SEPARATORS})`).test(branch);
+}
+function renderMissingTicketId(tickets, sideAllowed) {
+    const hint = sideAllowed
+        ? "Pass a ticket id, or --side for a new side ticket."
+        : "Pass a ticket id.";
+    if (tickets.length === 0)
+        return `No ticket id given. ${hint}`;
+    const listed = tickets.slice(0, LISTED_TICKETS);
+    const width = Math.max(...listed.map((ticket) => ticket.id.length));
+    const lines = listed.map((ticket) => `  ${ticket.id.padEnd(width)}  ${formatLocalTimestamp(ticket.modifiedAt)}` +
+        (ticket.archived ? " (archived)" : ""));
+    const rest = tickets.length - listed.length;
+    if (rest > 0)
+        lines.push(`  … ${rest} more`);
+    return `No ticket id given. Existing tickets:\n${lines.join("\n")}\n${hint}`;
+}
 export function deduceTicketFromBranch(cwd, pattern) {
     const result = detectTicketFromBranch(cwd, pattern);
     if (result.kind === "noBranch")

package/dist/project-config.js

@@ -75,6 +75,26 @@ function assertValidPattern(pattern, label) {
     catch (error) {
         throw invalidConfig(label, `ticketIdPattern is not a valid regular expression: ${errorMessage(error)}`);
     }
+    if (hasInnerAnchor(pattern))
+        throw invalidConfig(label, "ticketIdPattern must be one anchored expression; group alternatives: ^(ABC|XYZ)-\\d+$");
+}
+/** Branch detection unanchors the pattern by trimming its ends, so inner anchors never match. */
+function hasInnerAnchor(pattern) {
+    let inClass = false;
+    for (let i = 0; i < pattern.length; ++i) {
+        const char = pattern[i];
+        if (char === "\\")
+            ++i;
+        else if (inClass)
+            inClass = char !== "]";
+        else if (char === "[")
+            inClass = true;
+        else if (char === "^" && i !== 0)
+            return true;
+        else if (char === "$" && i !== pattern.length - 1)
+            return true;
+    }
+    return false;
 }
 function assertValidPortRange(range, label) {
     if (range.first > range.last)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "alignfirst",
-  "version": "0.1.0-beta.5",
+  "version": "0.1.0-beta.7",
   "license": "CC0-1.0",
   "author": "Thomas MUR",
   "description": "The AlignFirst CLI: protocols, plans and docs in one command.",
@@ -34,7 +34,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@paleo/docmap": "~0.10.0-beta.0",
+    "@paleo/docmap": "~0.10.0-beta.1",
     "arktype": "^2.2.3",
     "semver": "^7.8.5"
   },

package/templates/context/protocols.md

@@ -0,0 +1,5 @@
+# AlignFirst Protocols
+
+`{{CMD}} guide <protocol>` prints a collaborative protocol to follow when the user names AlignFirst or a protocol alias. A guide already in context is not reloaded. Each named guide includes the ticket directory and work file rules; `--protocol-only` omits them when they are already in context.
+
+Aliases: `alspec` → `spec`, `alplan` → `plan`, `al` or `AAD` → `aad`, `almerge` → `merge`, `alreview` → `review`, `aldescription` → `description`. `alcatchup` stands for `{{CMD}} ticket --catchup` followed by the user's instructions; `alcatchupaad` and `alcatchupspec` run it before the `aad` or `spec` protocol.

package/templates/guide/core.md

@@ -1,6 +1,6 @@
-# Shared Conventions
+# Ticket Directory and Work Files
 
-## Ticket directory
+## Ticket Directory
 
 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.
 
@@ -12,7 +12,7 @@ TICKET_DIR holds a ticket's work files and includes a trailing slash. TICKET_ID
 
 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.
 
-## Work files
+## Work Files
 
 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.
 

package/templates/guide/overview.md

@@ -36,17 +36,21 @@ Use Spec-Plan-Execute when:
 
 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
+## Standalone Utilities
 
-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.
+Each utility runs on its own, outside the workflows.
 
-## Code Review
+### Description
 
-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.
+`aldescription` alias. Reads the specs and summaries of a ticket and writes a concise description of the implemented work, typically for a PR or MR.
 
-## Merge
+### Review
 
-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.
+`alreview` alias. Compares the current branch to a base branch (the repository's default branch unless another is given) 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
+
+`almerge` alias. Merges an incoming branch, or resolves the conflicts of a merge or rebase in progress. The agent investigates both sides, resolves each conflict (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

@@ -1,6 +1,6 @@
 # Align-and-Do Protocol (AAD)
 
-## Pre-requisites
+## Prerequisites
 
 Run `{{TICKET_CMD}}` once to identify TICKET_DIR and load the ticket directory context (`{{CMD}} ticket --side` when there is no external ticket).
 

package/templates/guide/protocols/description.md

@@ -1,6 +1,6 @@
-# How to Write a Description for Implemented Work
+# Description Protocol
 
-## Pre-requisites
+## Prerequisites
 
 Run `{{TICKET_CMD}}` once to identify TICKET_DIR and load the ticket directory context (`{{CMD}} ticket --side` when there is no external ticket).
 

package/templates/guide/protocols/merge.md

@@ -1,6 +1,6 @@
-# How to Resolve Merge Conflicts
+# Merge Protocol
 
-## Pre-requisites
+## Prerequisites
 
 Run `{{TICKET_CMD}}` once to identify TICKET_DIR and load the ticket directory context (`{{CMD}} ticket --side` when there is no external ticket).
 
@@ -8,7 +8,7 @@ Run `{{TICKET_CMD}}` once to identify TICKET_DIR and load the ticket directory c
 
 This protocol applies when a merge or rebase has produced conflicts, or when the user provides an incoming branch to merge. Follow the steps below.
 
-## 1. Check git status
+## 1. Check Git Status
 
 Run `git status` to check for conflicts.
 
@@ -29,7 +29,7 @@ Resolve the conflicts properly — preserve both intents whenever possible. Do n
 1. Accept all the changes from the incoming branch.
 2. After all other conflicts are resolved, run the proper install command so the package manager re-applies the current branch's dependency changes.
 
-## 4. Finalize the merge
+## 4. Finalize the Merge
 
 Finalize the merge using git's default commit message (e.g. `git commit --no-edit`). Do not write your own commit message — git has already prepared the proper merge message.
 
@@ -44,11 +44,11 @@ Example:
 ```markdown
 # Merge Summary - [very short title]
 
-## Notable resolutions
+## Notable Resolutions
 
 - `path/to/file.ts`: [what made it tricky and which choice was made, in one or two sentences]
 
-## Lock file
+## Lock File
 
 [Only if there was a lock file conflict: which lock file, which install command was run]
 ```

package/templates/guide/protocols/plan.md

@@ -1,8 +1,8 @@
-# How to Write Implementation Plans
+# Planning Protocol
 
-## Pre-requisites
+## Prerequisites
 
-### Determine TICKET_DIR and the spec file
+### Determine TICKET_DIR and the Spec File
 
 You need:
 
@@ -17,14 +17,14 @@ Before starting, **read the spec file** and understand it entirely.
 
 In order to generate implementation plans, you MUST follow this process:
 
-1. **Investigation Phase**: Explore the codebase, understand the current implementation, and identify the problem
-2. **Analysis Phase**: Determine the plan structure (single or multiple plans) and identify relevant documentation and skills
-3. **Designing Phase - Implementation Plan(s)**: Design plan(s) based on the analysis - If you discover issues or missing design decisions, STOP AND ASK THE USER
-4. **Designing Phase - Main Plan**: If multiple plans, design a main plan to coordinate them
-5. **Writing Phase**: Write the plan file(s)
-6. **Review Phase**: Critically review and improve the plan(s)
+1. **Investigation**: Explore the codebase, understand the current implementation, and identify the problem
+2. **Analysis**: Determine the plan structure (single or multiple plans) and identify relevant documentation and skills
+3. **Plan Design**: Design plan(s) based on the analysis - If you discover issues or missing design decisions, STOP AND ASK THE USER
+4. **Main Plan Design**: If multiple plans, design a main plan to coordinate them
+5. **Writing**: Write the plan file(s)
+6. **Review**: Critically review and improve the plan(s)
 
-## Phase 1. Investigation Phase
+## Phase 1. Investigation
 
 Check your context for available **documentation** and **skills**. Read every document and skill relevant to any aspect of the task — this is not optional. For each skill, also **read its relevant references**.
 
@@ -34,7 +34,7 @@ Use the SPEC text as a starting point, but do not trust it blindly. Verify the c
 
 For each operation in the spec, search for existing functions that do a similar job.
 
-## Phase 2. Analysis Phase
+## Phase 2. Analysis
 
 Based on your investigation, determine the plan structure:
 
@@ -55,7 +55,7 @@ Identify which **documentation** and **skills** are relevant for the work. Omit
 - List the documentation and skills that the implementing agent should read and follow. Always exclude `alignfirst` from skills.
 - For complex skills with reference files, identify specific files that should be loaded
 
-## Phase 3. Designing Phase - Implementation Plan Structure
+## Phase 3. Plan Design
 
 Design an implementation plan based on the SPEC. Include all useful information from the spec. If the spec is already detailed enough, you can extract and reuse parts of it. Add implementation details, file paths, and a breakdown into steps that weren't in the spec.
 
@@ -132,7 +132,7 @@ Do not trust this plan blindly. Be sure you understand the codebase and the plan
 **IMPORTANT**: Do NOT use external search tools (Context7, web search, documentation fetching) during implementation unless explicitly allowed in this plan. All context should be provided in this plan or discoverable in the codebase.
 ```
 
-## Phase 4. Designing Phase - Main Plan
+## Phase 4. Main Plan Design
 
 **Create a main plan only when multiple plans are created. Skip this section entirely if not applicable.**
 
@@ -205,7 +205,7 @@ Note:
 
 - 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
+## Phase 5. Writing
 
 Write the plan file(s) according to the determined structure:
 
@@ -236,7 +236,7 @@ Continue the current cycle. Immediately before writing each file, run `{{TICKET_
 
 _Important Note: There will be lint errors in the markdown files you write. Ignore them. NEVER FIX LINT ERRORS (FORMATTING ISSUES) IN THE PLANS._
 
-## Phase 6. Review Phase
+## Phase 6. Review
 
 When you think the plan(s) are complete, read them again with a critical eye and edit them to improve them.
 

package/templates/guide/protocols/review.md

@@ -1,6 +1,6 @@
-# How to Write a Code Review Report
+# Review Protocol
 
-## Pre-requisites
+## Prerequisites
 
 You need:
 
@@ -37,7 +37,7 @@ Before starting, run `{{TICKET_CMD}} --next review.md --new-cycle` to start a ne
 
 ## Phase 2. Perspective Reviews
 
-**Small diff** (roughly under 100 changed lines, outside generated files and lockfiles): skip the subagents. Execute the perspectives yourself, sequentially — intent, correctness, safety, quality — reading the same files. The rest of the protocol is unchanged.
+**Small diff** (roughly under 100 changed lines, outside generated files and lockfiles): skip the subagents. Execute the perspectives yourself, sequentially — intent, correctness, change safety, code quality — reading the same files. The rest of the protocol is unchanged.
 
 Otherwise, launch four reviewer subagents in parallel:
 
@@ -45,8 +45,8 @@ Otherwise, launch four reviewer subagents in parallel:
 | --- | --- | --- |
 | Intent | `intent` | none |
 | Correctness | `correctness` | from Phase 1 |
-| Change safety | `safety` | from Phase 1 |
-| Quality | `quality` | from Phase 1 |
+| Change Safety | `safety` | from Phase 1 |
+| Code Quality | `quality` | from Phase 1 |
 
 Each subagent prompt must contain:
 

package/templates/guide/protocols/spec.md

@@ -1,6 +1,6 @@
-# How to Write a Technical Specification
+# Specification Protocol
 
-## Pre-requisites
+## Prerequisites
 
 Run `{{TICKET_CMD}}` once to identify TICKET_DIR and load the ticket directory context (`{{CMD}} ticket --side` when there is no external ticket).
 
@@ -8,13 +8,13 @@ Run `{{TICKET_CMD}}` once to identify TICKET_DIR and load the ticket directory c
 
 When the user asks you for a SPEC (technical specification), you MUST follow this process:
 
-1. **Investigation Phase**: Research the codebase to understand the current implementation and identify the problem
-2. **Discussion Phase**: Collaborate with the user to explore the problem space and potential solutions BEFORE writing the specification file
-3. **Specification Phase**: Only after user approval, write the final specification file
+1. **Investigation**: Research the codebase to understand the current implementation and identify the problem
+2. **Discussion**: Collaborate with the user to explore the problem space and potential solutions BEFORE writing the specification file
+3. **Specification**: Only after user approval, write the final specification file
 
 The discussion phase is MANDATORY. Remember that you are a newcomer to this project while the user has extensive experience with the codebase and will be happy to help guide you.
 
-## Phase 1. Investigation Phase
+## Phase 1. Investigation
 
 Check your context for available **documentation** and **skills**. Read every document and skill relevant to any aspect of the task — this is not optional. For each skill, also **read its relevant references**.
 
@@ -22,7 +22,7 @@ Investigate the codebase yourself, find the relevant source code, think carefull
 
 Always seek a clean break solution by default. Never consider backward compatibility unless explicitly requested.
 
-## Phase 2. Discussion Phase
+## Phase 2. Discussion
 
 Engage in a thorough collaborative discussion covering:
 
@@ -42,7 +42,7 @@ You should ask questions freely to ensure you fully understand:
 
 Do not use your question tool. Always ask in plain text. Your questions will be the opportunity for a real discussion.
 
-## Phase 3. Specification Phase
+## Phase 3. Specification
 
 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.
 

package/templates/guide/selection.md

@@ -1,8 +1,8 @@
 # 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.
+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 the ticket directory and work file rules; add `--protocol-only` when those rules are already in context.
 
-## Choose a protocol
+## 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.