alignfirst 0.1.0-beta.1 → 0.1.0-beta.3

package/README.md

@@ -1,6 +1,8 @@
 # alignfirst
 
-The AlignFirst CLI provides protocols, shared plans and project documentation in one command.
+The AlignFirst CLI provides collaborative software-development workflows, task files, shared plans, project conventions, documentation discovery, and setup diagnostics.
+
+## Installation
 
 Install it globally:
 
@@ -11,10 +13,26 @@ npm install -g alignfirst
 Or run the current version without installing it:
 
 ```sh
-npx -y alignfirst
+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.
 ```
 
-Commands:
+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 and its next file.
@@ -26,6 +44,61 @@ Commands:
 - `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. They reuse guides already in context and load missing guides through `npx -y alignfirst guide`.
+
+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
+```
+
+Restart the agent after installation. Claude Code, GitHub Copilot, and Cursor expose skills with `/`; Codex uses `$`.
+
+## Workflows
+
+These examples use the `/` form. Replace it with `$` in Codex.
+
+| Workflow | Command | Result |
+| --- | --- | --- |
+| Specification | `/alspec <request>` | Discuss and write a technical specification. |
+| Planning | `/alplan` | Turn a specification into one or more implementation plans. |
+| Align and do | `/al <request>` | Discuss and implement a small change, then write a summary. |
+| 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. |
+
+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`.
+
+## Updates
+
+```sh
+npm update -g alignfirst
+npx skills update --global --yes
+```
+
+## Upgrade from v1, v2, or v3
+
+Install the setup-guide skill and ask your agent to run its upgrade route:
+
+```sh
+npx skills add https://github.com/paleo/alignfirst --skill alignfirst-setup-guide
+```
+
+```text
+Use your alignfirst-setup-guide skill. Upgrade AlignFirst in this project.
+```
+
+_Note: the setup-guide skill can be removed safely after it's done._
+
+## License
 
-`@paleo/alcode` is the companion CLI for the AlignFirst Developer.
+CC0 1.0 Universal.

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.1",
+  "version": "0.1.0-beta.3",
   "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.9.1",
+    "@paleo/docmap": "~0.10.0-beta.0",
     "arktype": "^2.2.3",
     "semver": "^7.8.5"
   },

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`.