feat: add the alignfirst CLI and rework the alproject package

.alignfirst.json

@@ -0,0 +1,16 @@
+{
+  "schemaVersion": 1,
+  "ticketIdPattern": "^\\d+$",
+  "plans": {
+    "folder": "alignfirst",
+    "autoArchive": true
+  },
+  "git": {
+    "defaultBranch": "main",
+    "branchNameTemplate": "{TICKET_ID}/{slug-1-3-words}",
+    "commit": {
+      "style": "conventionalCommit"
+    },
+    "agentCoauthoring": false
+  }
+}

.changeset/alcode-catchup.md

@@ -0,0 +1,5 @@
+---
+"@paleo/alcode": minor
+---
+
+Breaking change: the `catchup` value of `--protocol` is removed; `new --catchup` replaces it and loads the ticket history before the protocol and message. `--message-file <path|->` reads the message from a file or stdin. The prompt reaches the coding agent through stdin. `--no-ticket` reads `TICKET_ID` from the `alignfirst` report.

.changeset/alcode-projects-and-alignfirst.md

@@ -0,0 +1,5 @@
+---
+"@paleo/alcode": minor
+---
+
+Breaking change: `reserve-side-ticket` is removed, and the `alignfirst` CLI is a prerequisite, run by `new --no-ticket` and by the delegated prompt.

.changeset/alignfirst-initial-release.md

@@ -0,0 +1,5 @@
+---
+"alignfirst": minor
+---
+
+Initial release of the AlignFirst CLI.

.changeset/alproject-marker-model.md

@@ -0,0 +1,5 @@
+---
+"@paleo/alproject": major
+---
+
+Breaking change: the host registry (`~/.alproject.json`, `register`, `unregister`) is replaced by markers. A project's committed `.alignfirst.json` is its registration, and `.alignfirst-projects.json` marks a projects directory. New commands: `doctor`, `init`, `free-ports`, `--guide`. Requires the `alignfirst` CLI on `PATH`.

.changeset/docmap-embedded-commands.md

@@ -0,0 +1,5 @@
+---
+"@paleo/docmap": minor
+---
+
+The CLI can be embedded with an injected command prefix.

.changeset/workspace-port-claim.md

@@ -0,0 +1,5 @@
+---
+"@paleo/workspace": minor
+---
+
+The kernel checks `portRange` in `.alignfirst.json` against the port scheme.

.github/workflows/release.yml

@@ -81,7 +81,7 @@ jobs:
       - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
         with:
           node-version: 24
-      - name: Verify signatures and provenance
+      - name: Verify published packages
         shell: bash
         env:
           PUBLISHED: ${{ needs.publish.outputs.published-packages }}
@@ -98,6 +98,11 @@ jobs:
             sleep 30
           done
           npm audit signatures
+          alignfirst_version=$(node -e 'console.log(JSON.parse(process.env.PUBLISHED).find((p) => p.name === "alignfirst")?.version ?? "")')
+          if [ -n "$alignfirst_version" ]; then
+            [ "$(./node_modules/.bin/alignfirst --version)" = "$alignfirst_version" ]
+            ./node_modules/.bin/alignfirst docmap --version
+          fi
           # npm audit signatures reports invalid signatures, never absent ones
           for spec in $pkgs; do
             predicate=$(npm view "$spec" dist.attestations.provenance.predicateType)

AGENTS.md

@@ -1,6 +1,8 @@
 # Repository Guidelines
 
-Always ignore the `.plans`, `.local` and `.local-wt` directories when searching the codebase.
+## AlignFirst
+
+Before inspecting or changing this repository, run `npx alignfirst context` once from the repository root and follow its output.
 
 ## Tooling
 
@@ -22,40 +24,22 @@ This repository is on *GitHub*.
 
 ## Packages
 
-- `@paleo/alcode` — coding agent wrapper for the AlignFirst developer.
-- `@paleo/alproject` — local project registry for the AlignFirst developer
+- `alignfirst` — the AlignFirst CLI: protocols, plans and docs
+- `@paleo/alcode` — coding agent wrapper for the AlignFirst Developer
+- `@paleo/alproject` — project inventory and port allocation for the AlignFirst Developer host
 - `@paleo/docmap` — lightweight documentation system for AI agents and humans
 - `@paleo/openclaw-channel-mock-core` — shared library for synthetic OpenClaw channel plugins (bus, actions, factories)
 - `@paleo/openclaw-slack-mock` — Slack-shaped channel plugin for test scenarios
 - `@paleo/openclaw-discord-mock` — Discord-shaped channel plugin for test scenarios
 - `@paleo/openclaw-test` — Dockerised regression-test harness (bus, scenario driver, judge, Compose stack)
-- `@paleo/plans-share` — share the `.plans` directory through a team plans repository
 - `@paleo/workspace` — run multiple git-worktree dev environments side by side
 
-## Docmap - Seek Documentation
-
-*Before* any investigation or code exploration, run `npm run docmap`, then read the relevant documentation. Mandatory for every task.
-
 ## Workspaces
 
 A **workspace** is a git worktree (with its branch) plus its own dev setup: symlinked shared directories and seeded config files. Workspaces are isolated, so you can work on several branches in parallel. This repository has no dev server, so the system runs portless: nothing to start, no `dev` script.
 
 Run `npm run workspace -- --guide` for the full procedures.
 
-## AlignFirst - Ticket ID, Commit Message, Branch Name
-
-_Ticket ID_: Format is numeric. Use the ticket ID if explicitly provided. Otherwise, deduce it from the current branch name (no confirmation needed). If the branch name is unavailable, get it via `git branch --show-current`. Only ask the user as a last resort.
-
-Commit message convention: we use conventional commit, e.g., `feat: add new feature`. Do not mention the ticket ID. Do not add a "Co-Authored-By:" line.
-
-Branch naming convention: `<ticket-id>/<1-3-words>`.
-
-### Team Plans Repository
-
-In the main worktree, `.plans` is a symlink into a clone of the team plans repository (folder `alignfirst/`). Plans are shared with the team through that repository and are never committed in this one.
-
-After every change in `.plans/`, synchronize the plans: `npm run plans:sync`.
-
 ## Skills to read before editing
 
 - TypeScript or JavaScript file: read the `top-down-typescript` skill first (`.agents/skills/top-down-typescript/SKILL.md`).

DEVELOPERS.md

@@ -21,6 +21,8 @@ Run `npm run workspace -- --guide` to learn the full procedures.
 
 ## Everyday commands
 
+The tooling runs through the `alignfirst` CLI built in this workspace, so run `npm run build` first.
+
 | Command | Purpose |
 |---------|---------|
 | `npm run build` | Build every package |
@@ -29,3 +31,5 @@ Run `npm run workspace -- --guide` to learn the full procedures.
 | `npm run docmap` | Browse the project documentation |
 | `npm run workspace -- <command>` | Manage worktree workspaces (`--guide` for the procedures) |
 | `npm run plans:sync` | Publish and retrieve the task plans (`.plans`) |
+
+In the main worktree, `.plans` is a symlink to the `alignfirst/` folder in a team plans repository clone. The folder is shared with the team and never committed here.

README.md

@@ -2,13 +2,13 @@
 
 Companion products for AI-assisted software work. They can be used independently.
 
-## AlignFirst skills
+## `alignfirst` CLI
 
-Collaborative spec/plan/AAD/merge/review protocols. See [alignfirst-skills.md](alignfirst-skills.md).
+The `alignfirst` CLI provides the AlignFirst workflows. See [the CLI README](packages/alignfirst/README.md) for installation and usage.
 
-### Team plans repository
+### Agent skills
 
-`@paleo/plans-share` shares the `.plans` directory of the AlignFirst skills among a team, through a dedicated plans repository. See [packages/plans-share/README.md](packages/plans-share/README.md).
+Nine Agent Skill stubs expose the CLI through commands such as `/alspec` in Claude Code and `$alspec` in Codex. See [the Agent skills section](packages/alignfirst/README.md#agent-skills).
 
 ## Docmap - Agent-discoverable documentation
 

alignfirst-developer-tests/.env.local.example

@@ -25,12 +25,9 @@ OPENCLAW_WORKSPACE_DIR=./workspace
 # gateway's baked copy so playbook edits iterate without a rebuild (relative to this dir).
 ALIGNFIRST_DEVELOPER_PLAYBOOK_SKILL_DIR=../skills/alignfirst-developer-openclaw-playbook
 
-# Required: host path to the built @paleo/alcode package (the coding-delegation CLI the
-# gateway runs; its --guide is the delegation manual). Build it first:
-# `npm run build --workspace @paleo/alcode` from the repo root, so packages/alcode/dist
-# exists. Live-mounted read-only at /opt/alcode (guide edits in templates/ iterate live);
-# a /usr/local/bin/alcode wrapper on PATH resolves to it.
-ALIGNFIRST_CODE_DIR=../packages/alcode
+# Required: host path to the monorepo root. Run `npm run build` there first so the
+# mounted alcode, alignfirst, and docmap packages have built output.
+ALIGNFIRST_REPO_DIR=..
 
 # Required: coding agent launched by alcode inside the gateway. Codex is the recommended primary
 # harness path. This does not select the OpenClaw conversation model.

alignfirst-developer-tests/Dockerfile

@@ -12,23 +12,21 @@ USER root
 # Fixture runtime deps (git for `git init` / worktree, curl for the playbook's
 # verification step — "confirm the app still serves" — pnpm via Corepack for
 # the project's dev scripts). Plus the per-command mock-cli shim symlinks
-# this consumer wants intercepted. `claude`, `codex`, `gh`, and `alproject` are shimmed. `alcode` runs for real,
+# this consumer wants intercepted. `claude`, `codex`, and `gh` are shimmed. `alcode` runs for real,
 # and its selected coding-agent subprocess resolves back to the shim via PATH order.
 RUN apk add --no-cache git curl && \
     corepack enable && corepack prepare pnpm@latest --activate && \
-    for name in claude codex gh alproject; do ln -sf mock-cli-shim "/opt/openclaw-test/mocks/bin/$name"; done && \
-    mkdir -p /home/claw/projects /home/claw/external-projects /home/claw/lifecycle-projects && \
-    chown claw:claw /home/claw/projects /home/claw/external-projects \
-      /home/claw/lifecycle-projects
+    for name in claude codex gh; do ln -sf mock-cli-shim "/opt/openclaw-test/mocks/bin/$name"; done && \
+    mkdir -p /home/claw/projects && \
+    chown claw:claw /home/claw/projects
 
-# PATH wrapper for the real `@paleo/alcode` CLI. The package's built output is
-# live-mounted at /opt/alcode (`${ALIGNFIRST_CODE_DIR}:/opt/alcode:ro` in the compose
-# overlay), so alcode edits iterate without a rebuild — mirroring the skill
-# live-mount. `/usr/local/bin` sits after `/opt/openclaw-test/mocks/bin` in
-# PATH, so this wrapper is only reached for `alcode` (never shimmed), while
-# alcode's own coding-agent subprocess still hits the shim.
-RUN printf '#!/bin/sh\nexec node /opt/alcode/bin/alcode.mjs "$@"\n' > /usr/local/bin/alcode && \
-    chmod +x /usr/local/bin/alcode
+# PATH wrappers for the real CLIs. `/opt/alignfirst` is the read-only monorepo root
+# mount, so @paleo/docmap, arktype, and semver resolve through its root node_modules.
+# `alproject` spawns `alignfirst`.
+RUN printf '#!/bin/sh\nexec node /opt/alignfirst/packages/alcode/bin/alcode.mjs "$@"\n' > /usr/local/bin/alcode && \
+    printf '#!/bin/sh\nexec node /opt/alignfirst/packages/alignfirst/bin/alignfirst.mjs "$@"\n' > /usr/local/bin/alignfirst && \
+    printf '#!/bin/sh\nexec node /opt/alignfirst/packages/alproject/bin/alproject.mjs "$@"\n' > /usr/local/bin/alproject && \
+    chmod +x /usr/local/bin/alcode /usr/local/bin/alignfirst /usr/local/bin/alproject
 
 # PATH wrapper for the `openclaw` CLI. OpenClaw is only a local npm dependency
 # of /opt/openclaw-test/src (nothing puts its node_modules/.bin on the exec
@@ -81,18 +79,16 @@ RUN npm ci --include=dev && \
     npm cache clean --force
 
 # Single fixture template baked into the image. scripts/reset-fixture.mjs copies
-# from here to each configured fixture parent at scenario start, materializing the
-# distinct projects (nimbus, lumen, and external-parent orion) with per-name patches.
+# from here into the nested fixture tree at scenario start, materializing nimbus,
+# lumen, and external-team project orion with per-name patches.
 COPY --chown=claw:claw projects-fixture/template/ /opt/alignfirst-developer-tests/fixtures/template/
 RUN cd /opt/alignfirst-developer-tests/fixtures/template && \
     pnpm install --frozen-lockfile --prod=false
 
 # Install AlignFirst skills under /home/claw/.agents/skills/ (the path OpenClaw scans).
 RUN npx -y skills add https://github.com/paleo/alignfirst --global --yes \
       --agent universal --agent claude-code \
-      --skill alignfirst --skill al --skill alplan --skill alspec \
-      --skill aldescription --skill alreview --skill alcatchup \
-      --skill almerge --skill alignfirst-setup-guide \
+      --skill alignfirst-setup-guide \
       --skill alignfirst-developer-openclaw-playbook
 
 USER root