SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsalignfirst-setup-guide

alignfirst-setup-guide

Deployment & operations

View repository

Updated 10-16 07:49

About this skill

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

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.

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 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 AlignDev 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 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 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, a canonical skill installation, or a companion reported by npx alignfirst config.
  • 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.