alignfirst 0.1.1 → 0.2.1

package/README.md

@@ -1,56 +1,10 @@
 # alignfirst
 
-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
-
-Install it globally:
-
-```sh
-npm install -g alignfirst
-```
-
-Or run the current version without installing it:
-
-```sh
-npx alignfirst
-```
-
-## Setup with your agent
-
-Temporarily install the setup-guide skill:
-
-```sh
-npx skills add https://github.com/paleo/alignfirst --skill alignfirst-setup-guide
-```
-
-Then ask your agent:
-
-```text
-Use your alignfirst-setup-guide skill. Set up AlignFirst in this project. Ask before installing anything globally.
-```
-
-The guide installs the selected components and configures the repository. Remove the setup-guide skill when setup is complete.
-
-## Commands
-
-- `guide` — Print an AlignFirst protocol.
-- `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.
-- `conventions` — Print the effective project conventions.
-- `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 the ticket directory and work file rules. Add `--protocol-only` when those rules are already in context.
+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 plans repository.
 
 ## Agent skills
 
-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:
+Nine Agent Skill stubs expose the CLI as commands in Claude Code, Codex, GitHub Copilot, and Cursor. Install them globally:
 
 ```sh
 npx skills add https://github.com/paleo/alignfirst --global \
@@ -65,7 +19,13 @@ Install the `alignfirst` skill when a project's `AGENTS.md` does not run `npx al
 npx skills add https://github.com/paleo/alignfirst --global --skill alignfirst
 ```
 
-Start a new agent session to load the skills.
+The skills run the CLI through `npx`, so installing it is optional.
+
+### Update the agent skills
+
+```sh
+npx skills update --global
+```
 
 ## Workflows
 
@@ -87,17 +47,54 @@ To implement a plan, start a fresh agent context and ask it to execute the plan
 
 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
+## Global CLI
+
+To type `alignfirst` instead of `npx alignfirst`, install the CLI globally:
+
+```sh
+npm install -g alignfirst
+```
+
+### Update the global CLI
 
-`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, with a notice telling the agent to read the relevant files and skip the plans.
+```sh
+npm update -g alignfirst
+```
 
-## Updates
+## Set up a project (with your agent)
+
+Temporarily install the setup-guide skill:
 
 ```sh
-npm install -g alignfirst@latest
-npx skills update --global --yes
+npx skills add https://github.com/paleo/alignfirst --skill alignfirst-setup-guide
+```
+
+Then ask your agent:
+
+```text
+Use your alignfirst-setup-guide skill. What AlignFirst tooling could we add in this project?
 ```
 
+The guide installs the selected components and configures the repository. You can remove the setup-guide skill once setup is complete.
+
+## CLI commands
+
+- `guide` — Print an AlignFirst protocol.
+- `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.
+- `conventions` — Print the effective project conventions.
+- `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 the ticket directory and work file rules. Add `--protocol-only` when those rules are already in context.
+
+### Catchup output
+
+`alignfirst ticket [<id>] --catchup` prints the ticket's Markdown files, plans excluded.
+
 ## Upgrade from v1, v2, or v3
 
 Install the setup-guide skill and ask your agent to run its upgrade route:
@@ -110,7 +107,7 @@ npx skills add https://github.com/paleo/alignfirst --skill alignfirst-setup-guid
 Use your alignfirst-setup-guide skill. Upgrade AlignFirst in this project.
 ```
 
-_Note: the setup-guide skill can be removed safely after it's done._
+You can remove the setup-guide skill once the upgrade is complete.
 
 ## License
 

package/dist/commands/guide.js

@@ -128,9 +128,10 @@ function renderCoreGuide(ctx, placeholders) {
 }
 function buildGuidePlaceholders(ctx, protocol) {
     const pattern = ctx.projectConfig?.config.ticketIdPattern;
-    const detection = pattern === undefined ? undefined : detectTicketFromBranch(ctx.cwd, pattern);
+    const template = ctx.projectConfig?.config.git?.branchNameTemplate;
+    const detection = detectTicketFromBranch(ctx.cwd, pattern, template);
     return {
-        ticketCommand: detection?.kind === "detected" ? "{{CMD}} ticket" : "{{CMD}} ticket <id>",
+        ticketCommand: detection.kind === "detected" ? "{{CMD}} ticket" : "{{CMD}} ticket <id>",
         ticketDetection: renderTicketDetection(pattern, detection),
         plansState: renderPlansState(ctx),
         commitRule: renderCommitRule(ctx),
@@ -138,11 +139,11 @@ function buildGuidePlaceholders(ctx, protocol) {
     };
 }
 function renderTicketDetection(pattern, detection) {
+    if (detection.kind === "detected")
+        return `Current ticket: \`${detection.id}\` (from branch \`${detection.branch}\`). The id argument of \`{{CMD}} ticket\` is optional and defaults to it; pass an id only when the user names another ticket.`;
     if (pattern === undefined)
         return "Ask the user for the ticket ID when it is not given.";
-    if (detection?.kind === "detected")
-        return `Current ticket: \`${detection.id}\` (from branch \`${detection.branch}\`). The id argument of \`{{CMD}} ticket\` is optional and defaults to it; pass an id only when the user names another ticket.`;
-    if (detection?.kind === "noMatch")
+    if (detection.kind === "noMatch")
         return `No ticket id on branch \`${detection.branch}\`. Ask the user for the id.`;
     return "No ticket id: detached HEAD. Ask the user for the id.";
 }

package/dist/commands/ticket.js

@@ -5,7 +5,7 @@ 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, deduceTicketFromExisting, nextFilePosition, peekSideTicket, reserveSideTicket, resolveTicketDir, validateTicketId, } from "../plans/ticket.js";
+import { detectTicketFromBranch, 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]
@@ -70,10 +70,11 @@ function parseTicketArgs(ctx, args, 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}`);
+    const next = values.next === undefined ? undefined : resolveNextRequest(normalized.requests, usage);
     const resolution = resolveTicketId(ctx, positionals[0], values);
     return {
         ...resolution,
-        next: values.next === undefined ? undefined : resolveNextRequest(normalized.requests, usage),
+        next,
         newCycle: values["new-cycle"],
         json: values.json,
         dryRun: values["dry-run"],
@@ -125,16 +126,23 @@ function validateNextFilename(filename) {
 function resolveTicketId(ctx, positional, flags) {
     const pattern = ctx.projectConfig?.config.ticketIdPattern;
     if (positional !== undefined) {
-        validateTicketId(positional, pattern);
+        validateTicketId(positional);
         return { id: positional };
     }
     if (flags.side)
         return { id: flags["dry-run"] ? peekSideTicket(ctx.cwd) : reserveSideTicket(ctx.cwd) };
+    const template = ctx.projectConfig?.config.git?.branchNameTemplate;
+    const detection = detectTicketFromBranch(ctx.cwd, pattern, template);
+    if (detection.kind === "detected") {
+        validateTicketId(detection.id);
+        return detection;
+    }
     if (pattern === undefined)
         return deduceTicketFromExisting(ctx.cwd, { sideAllowed: !flags.catchup });
-    const deduced = deduceTicketFromBranch(ctx.cwd, pattern);
-    validateTicketId(deduced.id, pattern);
-    return deduced;
+    if (detection.kind === "noBranch")
+        throw new CliError("Cannot deduce a ticket id from a detached HEAD.");
+    const templateDetail = template?.includes("{TICKET_ID}") ? ` and template "${template}"` : "";
+    throw new CliError(`Cannot deduce a ticket id from branch "${detection.branch}" with pattern "${pattern}"${templateDetail}.`);
 }
 function resolveTicket(ctx, options) {
     if (options.side && !options.dryRun)

package/dist/conventions.js

@@ -18,8 +18,8 @@ export function renderConventions(ctx) {
 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\`.`;
+        return "Ticket IDs: no configured format; ask the user for the ID. Without a ticket, or when the user asks for a side ticket, use the next `side-N`.";
+    return `Ticket IDs: \`${pattern}\`; infer a matching ID from the branch. Without a ticket, or when the user asks for a side ticket, use the next \`side-N\`.`;
 }
 function renderBranchNames(ctx) {
     const template = ctx.projectConfig?.config.git?.branchNameTemplate;
@@ -50,10 +50,10 @@ function renderPlans(ctx) {
     try {
         const mode = resolvePlansMode(ctx.cwd, ctx.form);
         const folder = ctx.projectConfig?.config.plans?.folder;
-        const sharedFolder = folder === undefined ? "" : ` (shared folder \`${folder}\`)`;
+        const sharedFolder = folder === undefined ? "" : ` (shared folder \`${folder}\`, a separate git repository)`;
         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.";
+            ? `Plans: use \`.plans\`${sharedFolder}; run \`${ctx.form} sync\` after changes.`
+            : "Plans: use `.plans`.";
         const archival = ctx.projectConfig?.config.plans?.autoArchive === true
             ? " Automatic archival is enabled."
             : "";

package/dist/plans/ticket.d.ts

@@ -37,11 +37,10 @@ export interface NextFilePosition {
 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;
+export declare function validateTicketId(id: string): void;
+export declare function detectTicketFromBranch(cwd: string, pattern?: string, template?: 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

@@ -7,9 +7,10 @@ import { gitOutputOrUndefined } from "../git.js";
 import { archivesDir, isTicketName, plansDir } from "./layout.js";
 const FILE_PREFIX = /^([A-Z])(\d+)-/;
 const SIDE_TICKET = /^side-(\d+)$/;
+const BRANCH_SEPARATORS = "[/_.-]";
+const SIDE_TICKET_BRANCH = new RegExp(`^side-\\d+(?=$|${BRANCH_SEPARATORS})`);
 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);
@@ -104,22 +105,49 @@ function statOrLink(path) {
 export function isPathSafeTicketId(id) {
     return id !== "." && !id.includes("..") && PATH_SAFE_TICKET.test(id);
 }
-export function validateTicketId(id, pattern) {
+export function validateTicketId(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) {
+export function detectTicketFromBranch(cwd, pattern, template) {
     const branch = currentBranch(cwd);
     if (branch === undefined)
         return { kind: "noBranch" };
-    const unanchored = pattern.replace(/^\^/, "").replace(/\$$/, "");
-    const match = new RegExp(unanchored).exec(branch);
+    const sideTicket = SIDE_TICKET_BRANCH.exec(branch);
+    if (sideTicket)
+        return { kind: "detected", id: sideTicket[0], branch };
+    if (pattern === undefined)
+        return { kind: "noMatch", branch };
+    if (template?.includes("{TICKET_ID}")) {
+        const match = branchPatternFromTemplate(template, unanchorPattern(pattern)).exec(branch);
+        const id = match?.[1];
+        if (id === undefined || !isPathSafeTicketId(id) || !isTicketName(id))
+            return { kind: "noMatch", branch };
+        return { kind: "detected", id, branch };
+    }
+    const match = new RegExp(unanchorPattern(pattern)).exec(branch);
     if (!match)
         return { kind: "noMatch", branch };
     return { kind: "detected", id: match[0], branch };
 }
+function unanchorPattern(pattern) {
+    return pattern.replace(/^\^/, "").replace(/\$$/, "");
+}
+function branchPatternFromTemplate(template, ticketPattern) {
+    const placeholder = /\{[^{}]+\}/g;
+    let source = "";
+    let cursor = 0;
+    for (const match of template.matchAll(placeholder)) {
+        source += escapeRegexLiteral(template.slice(cursor, match.index));
+        source += match[0] === "{TICKET_ID}" ? `((?:${ticketPattern})|side-\\d+)` : ".+";
+        cursor = match.index + match[0].length;
+    }
+    source += escapeRegexLiteral(template.slice(cursor));
+    return new RegExp(`^${source}$`);
+}
+function escapeRegexLiteral(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
 function currentBranch(cwd) {
     const branch = gitOutputOrUndefined(cwd, "branch", "--show-current");
     return branch === undefined || branch === "" ? undefined : branch;
@@ -157,7 +185,7 @@ function newestModification(dir) {
     return new Date(Math.max(...entries.map((entry) => entry.modifiedAt.getTime())));
 }
 function branchNamesTicket(branch, id) {
-    const escaped = id.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const escaped = escapeRegexLiteral(id);
     return new RegExp(`(^|${BRANCH_SEPARATORS})${escaped}($|${BRANCH_SEPARATORS})`).test(branch);
 }
 function renderMissingTicketId(tickets, sideAllowed) {
@@ -175,11 +203,3 @@ function renderMissingTicketId(tickets, sideAllowed) {
         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")
-        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/package.json

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

package/templates/guide/core.md

@@ -2,7 +2,7 @@
 
 ## 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.
+TICKET_DIR holds a ticket's work files and includes a trailing slash. TICKET_ID is the external ticket ID, or `side-N` for a side ticket: work without a ticket.
 
 {{TICKET_DETECTION}}
 
@@ -10,7 +10,7 @@ TICKET_DIR holds a ticket's work files and includes a trailing slash. TICKET_ID
 
 {{PLANS_STATE}}
 
-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.
+When the user says there is no ticket or asks for a side 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
 

package/templates/guide/protocols/aad.md

@@ -2,7 +2,7 @@
 
 ## Prerequisites
 
-Run `{{TICKET_CMD}}` once to identify TICKET_DIR and load the ticket directory context (`{{CMD}} ticket --side` when there is no external ticket).
+Run `{{TICKET_CMD}}` once to identify TICKET_DIR and load the ticket directory context (`{{CMD}} ticket --side` for a side ticket, when there is no ticket).
 
 ---
 

package/templates/guide/protocols/description.md

@@ -2,7 +2,7 @@
 
 ## Prerequisites
 
-Run `{{TICKET_CMD}}` once to identify TICKET_DIR and load the ticket directory context (`{{CMD}} ticket --side` when there is no external ticket).
+Run `{{TICKET_CMD}}` once to identify TICKET_DIR and load the ticket directory context (`{{CMD}} ticket --side` for a side ticket, when there is no ticket).
 
 ## Steps
 

package/templates/guide/protocols/merge.md

@@ -2,7 +2,7 @@
 
 ## Prerequisites
 
-Run `{{TICKET_CMD}}` once to identify TICKET_DIR and load the ticket directory context (`{{CMD}} ticket --side` when there is no external ticket).
+Run `{{TICKET_CMD}}` once to identify TICKET_DIR and load the ticket directory context (`{{CMD}} ticket --side` for a side ticket, when there is no ticket).
 
 ---
 

package/templates/guide/protocols/plan.md

@@ -6,7 +6,7 @@
 
 You need:
 
-- the TICKET_DIR and ticket directory context — run `{{TICKET_CMD}}` once (`{{CMD}} ticket --side` when there is no external ticket)
+- the TICKET_DIR and ticket directory context — run `{{TICKET_CMD}}` once (`{{CMD}} ticket --side` for a side ticket, when there is no ticket)
 - a **spec file** in the TICKET_DIR
 
 Identify TICKET_DIR and the spec file before starting the protocol. If either is missing, STOP AND ASK THE USER.

package/templates/guide/protocols/review.md

@@ -4,7 +4,7 @@
 
 You need:
 
-- the TICKET_DIR and ticket directory context — run `{{TICKET_CMD}}` once (`{{CMD}} ticket --side` when there is no external ticket)
+- the TICKET_DIR and ticket directory context — run `{{TICKET_CMD}}` once (`{{CMD}} ticket --side` for a side ticket, when there is no ticket)
 - {{BASE_BRANCH_RULE}}
 
 Identify TICKET_DIR and the base branch before starting the protocol.

package/templates/guide/protocols/spec.md

@@ -2,7 +2,7 @@
 
 ## Prerequisites
 
-Run `{{TICKET_CMD}}` once to identify TICKET_DIR and load the ticket directory context (`{{CMD}} ticket --side` when there is no external ticket).
+Run `{{TICKET_CMD}}` once to identify TICKET_DIR and load the ticket directory context (`{{CMD}} ticket --side` for a side ticket, when there is no ticket).
 
 ## Phases