alignfirst-setup-guide

Files (91)

• SKILL.md
• .alignfirst.json · assets/aligndev-openclaw-template/base/
• .gitignore · assets/aligndev-openclaw-template/base/
• AGENTS.md · assets/aligndev-openclaw-template/base/
• DEVELOPERS.md · assets/aligndev-openclaw-template/base/
• README.md · assets/aligndev-openclaw-template/base/
• configuration.md · assets/aligndev-openclaw-template/base/docs/
• gotchas.md · assets/aligndev-openclaw-template/base/docs/
• 01-server-setup.md · assets/aligndev-openclaw-template/base/docs/installations/
• 02-admin-repository.md · assets/aligndev-openclaw-template/base/docs/installations/
• 03-toolchain.md · assets/aligndev-openclaw-template/base/docs/installations/
• 04-openclaw.md · assets/aligndev-openclaw-template/base/docs/installations/
• 05-openclaw-dependencies.md · assets/aligndev-openclaw-template/base/docs/installations/
• 06-security-hardening.md · assets/aligndev-openclaw-template/base/docs/installations/
• add-project.md · assets/aligndev-openclaw-template/base/docs/operations/
• configure-assistant.md · assets/aligndev-openclaw-template/base/docs/operations/
• recover-assistant.md · assets/aligndev-openclaw-template/base/docs/operations/
• update-assistant.md · assets/aligndev-openclaw-template/base/docs/operations/
• update-workspace.md · assets/aligndev-openclaw-template/base/docs/operations/
• overview.md · assets/aligndev-openclaw-template/base/docs/
• troubleshooting.md · assets/aligndev-openclaw-template/base/docs/
• .env.example · assets/aligndev-openclaw-template/base/infra/openclaw/
• .gitignore · assets/aligndev-openclaw-template/base/infra/openclaw/
• playwright-chromium · assets/aligndev-openclaw-template/base/infra/openclaw/apparmor/
• apply-heartbeat-scratch.sh · assets/aligndev-openclaw-template/base/infra/openclaw/bin/
• apply-workspace.sh · assets/aligndev-openclaw-template/base/infra/openclaw/bin/
• assistant-kill.sh · assets/aligndev-openclaw-template/base/infra/openclaw/bin/
• assistant-maintenance.sh · assets/aligndev-openclaw-template/base/infra/openclaw/bin/
• backup.sh · assets/aligndev-openclaw-template/base/infra/openclaw/bin/
• bootstrap-backup.sh · assets/aligndev-openclaw-template/base/infra/openclaw/bin/
• openclaw · assets/aligndev-openclaw-template/base/infra/openclaw/bin/
• deployment-policy.mjs · assets/aligndev-openclaw-template/base/infra/openclaw/
• deployment-profiles.mjs · assets/aligndev-openclaw-template/base/infra/openclaw/
• common.conf · assets/aligndev-openclaw-template/base/infra/openclaw/environment.d/
• heartbeat-scratch.md · assets/aligndev-openclaw-template/base/infra/openclaw/
• admin-npm · assets/aligndev-openclaw-template/base/infra/openclaw/node-runtime/
• check-project-runtimes.sh · assets/aligndev-openclaw-template/base/infra/openclaw/node-runtime/
• gateway-path.conf · assets/aligndev-openclaw-template/base/infra/openclaw/node-runtime/
• init.bash · assets/aligndev-openclaw-template/base/infra/openclaw/node-runtime/
• install-pi-launcher.sh · assets/aligndev-openclaw-template/base/infra/openclaw/node-runtime/
• pi-launcher.mjs · assets/aligndev-openclaw-template/base/infra/openclaw/node-runtime/
• project-shell · assets/aligndev-openclaw-template/base/infra/openclaw/node-runtime/
• .alignfirst-projects.json · assets/aligndev-openclaw-template/base/infra/openclaw/projects/
• seed.sh · assets/aligndev-openclaw-template/base/infra/openclaw/
• common.sh · assets/aligndev-openclaw-template/base/infra/openclaw/seed/
• IDENTITY.md · assets/aligndev-openclaw-template/base/infra/openclaw/workspace/
• SOUL.md · assets/aligndev-openclaw-template/base/infra/openclaw/workspace/
• USER.md · assets/aligndev-openclaw-template/base/infra/openclaw/workspace/
• package.json · assets/aligndev-openclaw-template/base/
• workspace.mjs · assets/aligndev-openclaw-template/base/scripts/workspace/
• CLAUDE.md · assets/aligndev-openclaw-template/variants/coding-agents/claude-code/
• 08-coding-agent.md · assets/aligndev-openclaw-template/variants/coding-agents/claude-code/docs/installations/
• aligndev.settings.json · assets/aligndev-openclaw-template/variants/coding-agents/claude-code/infra/openclaw/
• CLAUDE.md · assets/aligndev-openclaw-template/variants/coding-agents/claude-code/infra/openclaw/coding-agent/
• coding-agent.sh · assets/aligndev-openclaw-template/variants/coding-agents/claude-code/infra/openclaw/seed/
• 08-coding-agent.md · assets/aligndev-openclaw-template/variants/coding-agents/codex/docs/installations/
• aligndev.settings.json · assets/aligndev-openclaw-template/variants/coding-agents/codex/infra/openclaw/
• AGENTS.md · assets/aligndev-openclaw-template/variants/coding-agents/codex/infra/openclaw/coding-agent/
• coding-agent.sh · assets/aligndev-openclaw-template/variants/coding-agents/codex/infra/openclaw/seed/
• 08-coding-agent.md · assets/aligndev-openclaw-template/variants/coding-agents/pi/docs/installations/
• …and 31 more

SKILL.md (first lines)

# AlignFirst Setup Guide

## Check freshness first

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

```sh
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](references/alignfirst-skills-setup.md). Skills invoke the CLI without a separate installation. Existing v1/v2/v3 skills or old home layouts first use [alignfirst-upgrade.md](references/alignfirst-upgrade.md).
- **Work-files repository:** [plans-setup.md](references/plans-setup.md).
- **Docmap:** [docmap-setup.md](references/docmap-setup.md). For docs adoption, follow its bootstrapping/migration references when relevant.
- **Workspace, any stack:** [workspace-setup.md](references/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](references/upgrading-multi-stack-workspaces.md). 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](references/aligndev-openclaw.md); a coding-agent assistant uses [coding-agent-assistant.md](references/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:

```sh
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:

```text
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:

```json
{
  "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 developer guides.

## Project instructions

- Protocol adoption uses the canonical `alignfirst context` bootstrap from [skills setup](references/alignfirst-skills-setup.md#project-instructions), 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](references/workspace-setup.md#agent-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 a developer guide's relative path as `developerInstructions` when supplying it. Detailed project documentation belongs in `docs/` and is discovered through Docmap.

## A repository that must stay untouched

Use [companion-setup.md](references/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](references/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. Node projects declare their version through `.nvmrc`, `.node-version` or `engines.node`; ask when none exists. Python and other runtimes retain their documented tools. Running the CLI through Node/Bun does not change project commands.
6. A project-specific developer guide, commonly `DEVELOPERS.md` or `README.md`, with its relative path explicitly recorded as `developerInstructions`. Use `alignfirst developer-instructions` to read conventions and configured content, and nullable `locations.developerInstructions` to locate edits. Without a reference there is no filename fallback. Follow [Project documentation defaults](#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](references/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. Pi retains its approved writable `auth.json` exception; other managed resources 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](references/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

Detect the package manager from `packageManager`, then root lockfiles, falling back to npm. Translate application commands to the confirmed toolchain. CLI forms remain `npx -y alignfirst` for Node and `bunx --bun alignfirst` for explicit Bun; project scripts are optional conveniences.

From paleo/alignfirst, CC0-1.0.

More from paleo/alignfirst