Alignfirst setup guide

Skill paleo/alignfirst/skills/alignfirst-setup-guide

Companion products for AI-assisted software work.

Install

npx -y skills add paleo/alignfirst --skill alignfirst-setup-guide

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

What its author says it does

Copied from the file, not written here

Setup-time companion to install or upgrade any subset of {docmap, workspace, alignfirst skills} in a consumer repo. Use when asked to install, set up, or upgrade docmap, the workspace worktree system, or the AlignFirst skills.

The file declares its own license as CC0 1.0. That is the author’s claim about this one file, and it is not the same thing as the license GitHub reports for the repository, which is listed with the other numbers below.

SKILL.md

3.6 KB, as published. Nobody here has run it

AlignFirst Setup Guide

A one-time companion for setting up a consumer repository. It installs any subset of three independent tools:

docmap — agent-discoverable documentation under docs/.
workspace — worktree-based concurrent local dev environments.
alignfirst skills — collaborative spec/plan/AAD/review protocols.

Pick any combination. Each has its own reference; this skill investigates the repo, agrees on scope, then follows the matching reference(s).

Follow these four steps in order. Do not skip ahead: complete each before starting the next.

Step 1 — Investigate

Detect the stack and package manager: check the packageManager field in package.json, else the root lockfile — package-lock.json → npm, pnpm-lock.yaml → pnpm, yarn.lock → yarn, bun.lockb/bun.lock → bun — falling back to npm. Record the result — every reference in Step 3 reuses this one detection rather than repeating it.

Commands in this guide are written for npm; convert each one to the detected manager — both when you run it and when you write it into project files. Only npm needs a -- separator to pass flags to a script (npm run docmap -- --guide); pnpm and yarn drop the run and the separator (pnpm docmap --guide), and bun keeps run but needs no separator (bun run docmap --guide). Install verbs differ too (npm install -D vs pnpm add -D / yarn add -D / bun add -D).

Then detect each tool's existing footprint:

docmap: a docmap script, a @paleo/docmap dependency, or a docs/ directory.
workspace: a workspace script or a @paleo/workspace dependency.
alignfirst skills: an installed alignfirst skill, a .plans/ directory, or an ## AlignFirst section in AGENTS.md / CLAUDE.md.

Step 2 — Discuss

Present the findings and agree with the user on which tools to install or upgrade. Any combination is valid.

Step 3 — Set up

Require a clean working tree first (git status). If it isn't clean, stop and ask the user to commit or stash. Then follow the matching reference(s):

docmap-setup.md — install the docmap CLI, then optionally bootstrap or migrate docs.
workspace-setup.md — implement the worktree system (adapt the asset scripts, install @paleo/workspace).
alignfirst-skills-setup.md — install the AlignFirst skills and configure the project.

Upgrading from an older AlignFirst (v1/v2): route through alignfirst-upgrade.md, which detects the version and follows alignfirst-upgrade-from-v1.md or alignfirst-upgrade-from-v2.md.

Step 4 — After setup

This skill is temporary. Once setup is done, the user can uninstall it. Provide them the command:

npx skills remove alignfirst-setup-guide --yes

# prune the entry in skills-lock.json
node --input-type=module -e 'import {readFileSync as r,writeFileSync as w} from "node:fs";const f="skills-lock.json",j=JSON.parse(r(f));delete j.skills["alignfirst-setup-guide"];w(f,JSON.stringify(j,null,2)+"\n")'