alignfirst 0.1.0-beta.2 → 0.1.0-beta.3

package/README.md

@@ -44,11 +44,11 @@ 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`.
+Eight optional Agent Skill stubs expose the CLI to GitHub Copilot, Cursor, Claude Code, and Codex. They reuse guides already in context and load missing guides through `npx -y alignfirst guide`.
 
 Install them globally:
 

package/dist/commands/guide.js

@@ -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 = [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "alignfirst",
-  "version": "0.1.0-beta.2",
+  "version": "0.1.0-beta.3",
   "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,23 @@
-# AlignFirst Guide
+# Shared Conventions
 
-An agent that does not know which protocol to use runs `{{CMD}} guide overview`.
+## Task directory
 
-## Protocols
-
-- **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`
-
-## 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.
+TASK_DIR holds a ticket's work files. TICKET_ID identifies the task, usually by its issue or ticket number.
 
 {{TICKET_CONTEXT}}
 
-{{PLANS_STATE}}
+`{{TICKET_CMD}}` prints TASK_DIR and its entries, creates a missing directory, and restores an archived one. Adding `--next <filename>` also prints the next file path.
 
-**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
-
-Format: `{CYCLE_LETTER}{FILE_NUMBER}-{FILE_TYPE}.md`
+{{PLANS_STATE}}
 
-**Common file types:**
+When the user says there is no ticket, run `{{CMD}} ticket --side`. Reuse an existing `side-N` directory when the user refers to earlier work. Omit the ticket ID from commit messages.
 
-- `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
+## Work files
 
-**Example structure:**
+Files use `{CYCLE_LETTER}{FILE_NUMBER}-{FILE_TYPE}.md`, such as `A1-spec.md` or `A2-AAD.summary.md`.
 
-```text
-A1-spec.md
-A2-plan.md
-A3-AAD.summary.md
-B1-spec.md
-```
+Use `{{TICKET_CMD}} --next <filename>` to get the next path in the current cycle, including the extension. For example, `--next spec.md` may return a path ending in `A2-spec.md`. Add `--new-cycle` when the protocol or user calls for a new cycle.
 
-## 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/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 (`spec`, `alspec`) | Investigate, discuss, and write a technical specification. | `{{CMD}} guide spec` |
+| Planning (`plan`, `alplan`) | Turn a specification into implementation plans. | `{{CMD}} guide plan` |
+| Align-and-Do (`AAD`, `al`) | Investigate, agree, implement, and summarize a small change. | `{{CMD}} guide aad` |
+| Catch up (`catchup`, `alcatchup`) | Load the task history, then continue or summarize. | `{{CMD}} guide catchup` |
+| Merge (`merge`, `almerge`) | Merge an incoming branch and resolve conflicts. | `{{CMD}} guide merge` |
+| Review (`review`, `alreview`) | Review committed branch changes against a base branch. | `{{CMD}} guide review` |
+| Description (`aldescription`) | Write a concise description of implemented work. | `{{CMD}} guide description` |
+
+For more detail on workflows and the ticket lifecycle, read `{{CMD}} guide overview`.