alignfirst-setup-guide

AlignFirst Setup Guide

Route by the user's intent. Load only the references needed for that route. Docmap, workspace, and the AlignFirst skills can each be adopted independently.

Terminology

The AlignFirst CLI is the alignfirst npm package and bin. It provides guide, ticket, sync, plans, docmap, conventions, context, config, and doctor.

The AlignFirst skills are stubs that run the CLI. The nine command skills alspec, alplan, al, almerge, alreview, aldescription, alcatchup, alcatchupaad, and alcatchupspec keep disable-model-invocation: true; humans invoke them as /alspec in Claude Code, GitHub Copilot, Cursor, $alspec in Codex, or /skill:alspec in Pi. The optional alignfirst skill lets the agent recognize a protocol named in prose; a project whose instruction file starts with the canonical alignfirst context section provides this itself.

A work-files repository is an optional CLI mode configured through alignfirst plans setup.

aligndev, the AlignDev CLI, carries the assistant's playbook, coding-agent delegation, and project discovery. An OpenClaw assistant host installs it; a coding-agent assistant runs it through npx.

An Untouched Repository

When the user wants nothing written in the repository, every route below goes through companion-setup.md. The project's AlignFirst files then live in its companion directory, and only the tools that mode supports apply.

Named Tool

When the user names a tool, inspect the repository and proceed directly to that tool. Install or upgrade only what they requested.

• AlignFirst CLI, protocols, or skills: alignfirst-skills-setup.md. Install only the requested components; skills invoke the CLI through npx without a separate installation. For an existing v1, v2, or v3 installation, a machine with ~/.config/alignfirst/, or a companion registry with paths, start with alignfirst-upgrade.md.
• Work-files repository: plans-setup.md.
• docmap: docmap-setup.md. An instruction file with the old docmap body ("Mandatory for every task") needs Update the Docmap Snippet.
• workspace: workspace-setup.md. A ports group or setupProfiles in workspace.mjs needs Move Workspace Ports to the Dev-Server.
• AlignDev (aligndev): ask the user whether it serves an OpenClaw assistant or a coding agent (Claude Code, Codex or Pi). For OpenClaw, follow AlignDev for OpenClaw. For a coding agent, follow coding-agent-assistant.md, which installs the aligndev skill globally. An old ~/.alignfirst/aligndev.config.json needs Rename the AlignDev Settings.

Do not present the tooling menu or add unrelated tools on this route.

Tooling Recommendation

When the user asks what they can set up in a project, check the skills listed in your context and inspect the repository. Present global skills separately from project tooling. Let the user choose any subset before installing or configuring it.

Global Skills

Use the skill list in your context to check availability for the current agent:

• aligndev: the coding-agent assistant's playbook.
• alignfirst: recognition of protocols named in prose.
• paseo-alignfirst-workspace: recommended for Paseo users; explains how to use AlignFirst workspaces with Paseo.
• Command skills: alspec, alplan, al, almerge, alreview, aldescription, alcatchup, alcatchupaad, and alcatchupspec.

Report which are available and propose installing the missing ones globally for the current agent. A name absent from the list is unavailable in this session; it does not prove the skill is absent on disk. If the host exposes no skill list, report availability as unknown. This check needs no filesystem scan, installer command, or doctor run.

For approved installations, follow AlignFirst skills setup or the global aligndev skill procedure. Installing global skills alone does not configure the project or install Pi tools. The assistant-preparation route still skips command-skill installation unless the user separately requests those shortcuts.

For Paseo users, install paseo-alignfirst-workspace globally with approval. Replace <agent> with the current agent's installer target (claude-code, codex, or pi):

npx -y skills add https://github.com/paleo/alignfirst --global --yes \
  --agent <agent> --skill paseo-alignfirst-workspace </dev/null

Project Tooling

Recommend global skills, AlignFirst protocols, and Docmap regardless of the project's language or stack. Inspect existing footprints to distinguish adoption from what is already available:

• AlignFirst protocols provide collaborative specification, planning, implementation, merge, review, description, and catch-up workflows through the CLI. Command skills add shortcuts and can be installed on their own. A work-files repository is an optional sub-choice.
• docmap makes the repository's docs/ tree discoverable to agents and humans. It is available through the AlignFirst CLI or as the standalone @alignfirst/docmap package. A missing docs/ directory is an opportunity to bootstrap documentation, not a reason to omit the recommendation.
• workspace creates isolated git-worktree development environments. For a Node project, recommend installing and using @alignfirst/workspace through workspace setup. Detect Node usage from the project's runtime declarations, scripts, dependencies, or documentation; a package.json used only for tooling is insufficient. When workspace tooling already exists, recommend its documented workflow rather than a replacement. For other stacks, offer workspace only on request or when repository evidence supports it; keep existing non-Node implementations authoritative.

Determine whether a work-files repository exists before offering that option.

Project Instructions

Choose the AGENTS.md or CLAUDE.md discovery section from the project's adopted tools:

• AlignFirst skills or protocols: use the alignfirst context section from AlignFirst setup. It replaces Docmap - Seek Documentation; preserve any essential-documentation list and project-specific instructions.
• Docmap without AlignFirst skills or protocols: use Docmap - Seek Documentation from Docmap setup, with the project's actual Docmap command.
• Workspace only: add the workspace instructions.

Installing Docmap or workspace alone does not opt the project into AlignFirst protocols. Installing skills globally does not opt every repository into them.

AlignDev for OpenClaw

AlignDev for OpenClaw turns an OpenClaw assistant into a developer who works with AlignFirst. The assistant holds a chat identity, its channels and its sessions, and runs repository work through a coding agent (Claude Code, Codex or Pi) using the AlignFirst protocols.

One deployment is a dedicated Linux service account running the assistant under its own name and channel identity, on Slack or Discord, and in the OpenClaw apps. These two terms are used throughout this skill and the repositories it renders.

Preparing a project makes its repository compatible with an assistant. Creating an assistant builds and deploys it. Before rendering or upgrading, read the deployment boundary. All three overlays use named profiles and inventoried native stores. Pi preserves native authentication through an explicit writable auth.json exception; every other managed resource retains controlled-maintenance protection. Offline template checks do not replace live deployment acceptance.

Prepare a Project for an Assistant

Inspect the repository before changing it. A prepared project has all of these:

1. The canonical bootstrap section in AGENTS.md or CLAUDE.md, placed as the first ## section after the title and introduction. The README may offer a global CLI installation as a convenience. .alignfirst.json is required for an assistant-managed project and optional otherwise.
2. A clean aligndev project doctor --root <projects-directory> result after writing .alignfirst.json and before workspace setup. Stop preparation when the inventory is unhealthy.
3. Usable effective work files, untracked by the project's own repository. A separate work-files repository may track them. Before ticket or coding-session effects, follow the work-files-setup guide topic of aligndev for missing or project-tracked plans; its authorized companion selection leaves project content untouched without copying it.
4. docmap, including project scripts or CLI instructions. When the repository has no docs/ directory, bootstrap its documentation through docmap-bootstrapping.md as part of the preparation.
5. A documented worktree route. Existing project workspace tooling, including non-Node implementations, remains authoritative. Installing a full workspace system is optional; when selected, meet the AlignDev contract. Otherwise use aligndev worktree and document separate install/build/test and application-lifecycle commands.
6. The project's runtime requirements. For Node projects, declare the version (.nvmrc, .node-version or engines.node) so fnm selects it; ask which version when none exists. Other runtimes follow their documented tools.
7. A project-specific DEVELOPERS.md for an unfamiliar developer: commands, architecture, documentation map, development workflow, and verification procedures.

When the user says the repository must stay untouched, follow companion-setup.md with its section For an Assistant instead.

Every procedure that prepares a project for an assistant, a coding agent as the assistant included, skips the AlignFirst command skills and the global bootstrap line. The bootstrap section of item 1 stays. An assistant's service account keeps its global installation of this guide for its delegated coding agent.

Detect and verify the package manager, runtime, build, test, lint, dev-server, ports, shared directories, seeded configuration files, and team-plan details. Write only facts confirmed from the repository. Follow each selected tool reference above, then complete DEVELOPERS.md, naming the Node version declaration.

Create an Assistant

For creating or operating the assistant deployment itself, read aligndev-openclaw.md. Do not load that workflow for ordinary tool setup.

A Coding Agent as the Assistant

For Claude Code, Codex or a persistent Pi session acting as the assistant on one project, without OpenClaw, read coding-agent-assistant.md. Pi uses /skill:aligndev and a separately installed generic background tool; a Pi child uses the independent subagent package for plan/review delegation. Installing the skill alone supplies no executable tools.

Shared Investigation Rules

Detect the package manager from packageManager in package.json, then the root lockfile: package-lock.json means npm, pnpm-lock.yaml means pnpm, yarn.lock means yarn, and bun.lock or bun.lockb means bun. Fall back to npm.

Translate commands to that package manager. npm needs -- before script flags; pnpm and yarn omit run and the separator; bun keeps run but omits the separator.

Detect existing footprints before proposing changes:

• docmap: a docmap script, @alignfirst/docmap, alignfirst docmap in an instruction file, or docs/.
• workspace: documented workspace procedures, including non-Node tooling; a workspace script or @alignfirst/workspace is one footprint.
• A pre-@alignfirst install: @paleo/docmap or @paleo/workspace in the manifest. Before proposing anything else, replace the dependency with the @alignfirst name and rewrite the @paleo/ import specifiers in the wrapper scripts (scripts/workspace/*.mjs); the two scopes install side by side, so a manifest-only change leaves the wrappers importing the old package.
• AlignFirst: .alignfirst.json, .plans/, a bootstrap section running alignfirst context or npx alignfirst context, an AlignFirst instruction section, a canonical skill installation, or a companion reported by npx alignfirst config.
• work-files repository: a .plans symlink or plans.repositoryFolder in .alignfirst.json.
• Assistant preparation: the complete seven-part contract above.

Require a clean working tree immediately before project mutations. Read-only discovery and recommendations do not require one.