paleo/alignfirst/alignfirst-setup-guide

AlignFirst Setup Guide

Check freshness first

Before investigation, recommendations or setup, fetch the upstream skill read-only:

curl --fail --silent --show-error --location --max-time 20 --range 0-1023 \
  https://raw.githubusercontent.com/paleo/alignfirst/refs/heads/main/skills/alignfirst-setup-guide/SKILL.md \
  | sed -n '1,/^---$/p'

It prints only the upstream frontmatter. Compare its metadata.version with this loaded skill's metadata.version using semantic version ordering, not string ordering.

• Upstream is newer: stop and suggest npx skills update -g. Explain that it updates all global skills. Do not run it. Ask the user to restart or reload the agent after updating so it reads the new instructions.
• Fetch fails or either version is missing or invalid: stop and report that freshness could not be verified. Proceed only with explicit user approval.

Never use npx skills check for this gate; it aliases update and can install updates. Maintainers must bump metadata.version whenever this skill, its references or its assets change.

Routing

Route by the user's intent. Inspect the repository and load the relevant references before changes. Protocols, skills, Docmap and workspaces can each be adopted independently. Require a clean working tree immediately before project mutations; read-only discovery needs no clean-tree gate.

Named tool

Install or upgrade only what the user requested. Do not add unrelated tools or present the full menu.

• CLI, protocols or skills: alignfirst-skills-setup.md. Skills invoke the CLI without a separate installation. Legacy full-content skills, _docs/ instructions or old home layouts first use alignfirst-upgrade.md.
• Work-files repository: plans-setup.md.
• Docmap: docmap-setup.md. For docs adoption, follow its bootstrapping/migration references when relevant.
• Workspace, any stack: workspace-setup.md. Node, Python, Rust and monorepos use the same alignfirst workspace/alignfirst dev CLI. No project wrapper or local kernel dependency is needed. Never recommend reimplementing the kernel for another language.
• Retired `.alignfirst.json`, workspace wrappers or old runtime registries: clean-break upgrade runbook. Account for all resources and worktrees before conversion.
• AlignDev: ask whether it serves an OpenClaw assistant or a coding agent. OpenClaw uses aligndev-openclaw.md; a coding-agent assistant uses coding-agent-assistant.md.

Tooling recommendation

When asked what to adopt, inspect repository evidence and available skills. Present global skills separately from project tooling. Let the user choose any subset before installation.

Global choices are aligndev (assistant playbook), alignfirst (protocol recognition), paseo-alignfirst-workspace (Paseo lifecycle), and command shortcuts alspec, alplan, al, almerge, alreview, aldescription, alcatchup, alcatchupaad, alcatchupspec. Command skills retain disable-model-invocation: true. Humans use /name in Claude/Copilot/Cursor, $name in Codex and /skill:name in Pi. The protocol-recognition skill is unnecessary when canonical project context instructions already supply it.

A missing name in the session's skill list means unavailable here, not absent on disk. If the host exposes no list, availability is unknown. This check needs no filesystem scan or installer. Install globally only with approval, using the selected reference's current command. A skill alone supplies no executable Pi tools. Preserve duplicate-tool audits and native trust/permission policies.

Recommend protocols and Docmap regardless of language. Workspace isolation is also language-neutral; preserve existing project commands by expressing them in the selected configuration's workspace recipe. An absent manifest supplies protocol-ready defaults. Detect existing tooling and propose conversion rather than running incompatible old wrappers against new registries. Determine whether a separate work-files repository already exists before offering one.

Paseo setup

When the user uses Paseo, recommend installing paseo-alignfirst-workspace globally with approval:

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

Add --agent <host> to target the user's coding host. Recommend adding this line to the system prompt in Paseo settings:

You are running inside Paseo.

Keep project-specific hooks in paseo.json. Run these commands inside the target worktree, adding the project's runtime prefix when needed:

{
  "worktree": {
    "setup": "npx -y alignfirst workspace setup",
    "teardown": "npx -y alignfirst workspace teardown"
  }
}

The published CLI works before local dependencies or build output exist. Teardown hooks preserve the worktree for the tool's deletion step. For agent-initiated removal, read the workspace skill, archive first, then use workspace remove. Keep Paseo-specific lifecycle instructions out of project agent instructions and assistant guides.

Project instructions

• Protocol adoption uses the canonical alignfirst context bootstrap from skills setup, replacing redundant Docmap discovery prose while preserving essential-documentation lists and project-specific rules.
• Docmap-only adoption uses its own discovery snippet.
• Workspace-only adoption uses workspace instructions.

Global skills do not opt every repository into protocols. Workspace and Docmap adoption alone do not opt it into protocols either.

Project documentation defaults

Keep generated entry points minimal. Preserve useful existing project content.

• README.md contains the local environment installation procedure. With workspaces, use a ## Local environment installation section containing npx -y alignfirst workspace setup, with the project's runtime prefix when needed. Include prerequisites or manual steps only when required to make that procedure work. Omit generic tooling explanations, optional global installations, command catalogs and pending-work notices by default.
• DEVELOPERS.md, titled # Developer Reference, is the entry point for an assistant session. Include confirmed daily development commands, especially how to build and test, plus project-specific guidance needed to use them. Link to the most important documentation when it helps the assistant begin work; keep this selection short. When those details are undecided, the title alone is sufficient. Omit generic AlignFirst explanations, full documentation indexes, status filler and verification lists for the setup itself.
• Record an assistant guide's relative path as assistantInstructionsFile when supplying it. Detailed project documentation belongs in docs/ and is discovered through Docmap.

A repository that must stay untouched

Use companion-setup.md. Protocols and Docmap can keep all selected files outside the repository. A registration's defaultLocation: "companion" can also select the complete recipe and external runtime. This creates no checkout runtime directory/link or runtime ignore rule. Placement is not a write sandbox: project commands, shared directories, application outputs and Git operations retain their writes. Obtain approval for those effects.

Prepare a project for an assistant

An assistant coordinates the conversation and delegates coding to the coding agent through AlignDev. Prepare these facts before normal ticket/coding effects:

1. Canonical context bootstrap as the first ## section of AGENTS.md or CLAUDE.md, after title/introduction. alignfirst.json or alignfirst.jsonc with schemaVersion: 1 is required for an assistant-managed project and optional otherwise. Companion-only projects place selected instructions/settings outside the repository.
2. Usable effective plans, untracked by the product repository. A separate work-files repository may track them. Use the separately authorized aligndev guide work-files-setup for missing/project-tracked plans, before ticket reservation, request capture or coding effects. Preserve old history without unsolicited copying.
3. Docmap and meaningful project docs. When docs/ is absent and documentation is part of preparation, follow docmap-bootstrapping.md.
4. A unified workspace route through alignfirst workspace. The optional recipe in the selected merged configuration declares project commands; without workspace/devServer, setup is protocol-ready and performs no install/build/start. Prepare effective plans and selected runtime storage first; only project runtime requires ignored/untracked .local-wt/. Document separate stack commands when defaults are used.
5. Confirmed runtime requirements. Honor Node projects' .nvmrc, .node-version or engines.node; without a declaration, use current Node LTS unless the project's requirements say otherwise. Python and other runtimes retain their documented tools. Running the CLI through Node/Bun does not change project commands.
6. A project-specific assistant guide, commonly DEVELOPERS.md or README.md, with its relative path explicitly recorded as assistantInstructionsFile. Use alignfirst assistant-instructions to read project guidance and custom content, and nullable locations.assistantInstructionsFile to locate edits. Without a reference there is no filename fallback. Follow Project documentation defaults. Include confirmed daily commands, especially build and test, relevant project constraints, and useful references to essential documentation. Put local installation in the README, and include public URLs when services exist. Keep tool-specific lifecycle hooks in the tool's configuration.
7. aligndev project doctor --root <projects-directory> passes after settings/manifest creation and before workspace setup. A range belongs solely in devServer.ports; use project free-ports as a lookup when the inventory owns an enclosing range.

Assistant preparation skips command-skill installation and global bootstrap changes unless separately requested. Companion-only preparation follows its authorization and location checks. Native coding-agent permissions are unchanged; report protected-path refusals rather than bypassing them.

Create or operate an OpenClaw assistant

Read aligndev-openclaw.md, including its deployment gate, before rendering/upgrading. The generated private admin repository owns installation/operations runbooks. Do not load deployment procedures for ordinary project tooling.

The three overlays use named profiles and inventoried native stores. The entire service ~/.alignfirst/ tree stays service-owned and writable, without immutable or append-only flags. Pi retains its approved writable auth.json exception; other managed resources outside ~/.alignfirst/ remain maintenance-protected. Offline template checks do not certify deployment, OS hardening, authentication or conversation behavior. Do not perform live/admin operations without separate authorization.

A coding agent as the assistant

For Claude Code, Codex or a persistent Pi session on one project, read coding-agent-assistant.md. Pi uses /skill:aligndev and separately installed executable capabilities; installing a skill alone provides none. OpenClaw remains the persistent parent for its deployment route.

Investigation rules