# Alignfirst Setup Guide

> >-

- **Type:** Skill
- **Install:** `agentstack add skill-paleo-alignfirst-alignfirst-setup-guide`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [paleo](https://agentstack.voostack.com/s/paleo)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** CC0-1.0
- **Upstream author:** [paleo](https://github.com/paleo)
- **Source:** https://github.com/paleo/alignfirst/tree/main/skills/alignfirst-setup-guide

## Install

```sh
agentstack add skill-paleo-alignfirst-alignfirst-setup-guide
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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](references/docmap-setup.md) — install the docmap CLI, then optionally bootstrap or migrate docs.
- [workspace-setup.md](references/workspace-setup.md) — implement the worktree system (adapt the [asset scripts](assets/), install `@paleo/workspace`).
- [alignfirst-skills-setup.md](references/alignfirst-skills-setup.md) — install the AlignFirst skills and configure the project.

**Upgrading from an older AlignFirst** (v1/v2): route through [alignfirst-upgrade.md](references/alignfirst-upgrade.md), which detects the version and follows [alignfirst-upgrade-from-v1.md](references/alignfirst-upgrade-from-v1.md) or [alignfirst-upgrade-from-v2.md](references/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:

```sh
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")'
```

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [paleo](https://github.com/paleo)
- **Source:** [paleo/alignfirst](https://github.com/paleo/alignfirst)
- **License:** CC0-1.0

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** yes
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-paleo-alignfirst-alignfirst-setup-guide
- Seller: https://agentstack.voostack.com/s/paleo
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.