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, or $alspec in Codex. 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 Dev Kit 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.

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, start with alignfirst-upgrade.md.
• Work-files repository: plans-setup.md.
• docmap: docmap-setup.md.
• workspace: workspace-setup.md.

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

Tooling Recommendation

When the user asks what the project could adopt, inspect the repository and present these independent choices:

• 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.
• workspace creates isolated git-worktree development environments.

Determine whether a work-files repository exists before offering that option. Let the user choose any subset.

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.

AlignFirst Dev Kit for OpenClaw

The Dev Kit 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 or Codex) 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. 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.

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. The work-files repository through alignfirst plans setup when the team has one.
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. workspace, adapted to the project's runtime and development lifecycle, meeting the Dev Kit contract.
6. A Node version declaration (.nvmrc, .node-version or engines.node) so fnm selects the project runtime. Ask which version to declare when the repository has none.
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 instead. The same contract lives in the project's companion directory, except the workspace system and the Node version file.

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 alignfirst-dev-kit.md. Do not load that workflow for ordinary tool setup.

A Coding Agent as the Assistant

For a coding agent (Claude Code or Codex) acting as the assistant on one project, without OpenClaw, read coding-agent-assistant.md.

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: a workspace script or @alignfirst/workspace.
• 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, or a canonical skill installation.
• work-files repository: a .plans symlink or plans.folder 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.

Temporary Local Installation

When this guide was installed only for the current project, remove it through the skills CLI after setup:

npx -y skills remove alignfirst-setup-guide --yes </dev/null

The CLI owns skills-lock.json. Leave global installations in place for other repositories. A assistant service account must retain a global installation for its delegated coding agent.