AlignFirst

How AlignFirst works

Software engineering tools built for 2026

Three independent tools and a teammate.

AlignFirst overviewAlignFirst combines three tools and a teammate. AlignFirst Skills guide a coding agent from specification to plans and execution. Workspaces provide isolated Git worktrees for parallel development. Docmap gives your coding agents a table of contents for the project documentation. AlignDev provides an assistant that drives Claude Code or Codex, in your own coding-agent session or as an OpenClaw bot in Slack or Discord. AlignFirst Skills, Workspaces, Docmap and AlignDev are for any stack.AlignFirstSoftware engineering tools built for 2026/alspec/alplanexecuteAlignFirst SkillsDevelop with a clear flow:spec → plans → execution.Shared work files keepthe team aligned.For any stackWorkspacesIsolated dev-servers inGit worktrees, withoutchanging your tools.For any stackDocmapA table of contents forthe documentations availableto your coding agents.For any stackAlignDevAn assistant that drives Claude Code orCodex for you. In your own session, or asan OpenClaw bot 🦞 in Slack or Discord.For any stack
For any stack

Workspaces

Isolated dev-servers in Git worktrees, without changing your tools.

~/project$ npx alignfirst workspace setup --full✓ branch   ✓ worktree   ✓ dev setup prepared
Play the Workspaces demonstration
For any stack

Docmap

A table of contents for the documentation available to your coding agents.

docs/permissions/↳ adding-a-permission.md↳ permission-model.md
Play the Docmap demonstration
For any stack

AlignDev

An assistant that drives Claude Code or Codex for you, in your own session or as an OpenClaw bot in Slack or Discord.

You↔Assistant↔Agents
Explore AlignDev

Workspaces

For any stack

Create an isolated place for each task.

Home

This configured Node project example uses npx alignfirst workspace setup --full to prepare the branch, worktree and dev setup. npx alignfirst dev checks that setup before starting services. Logs stay in the terminal and in files the coding agent can read.

dev@laptop: ~/repos/hello-world

dev@laptop:~/repos/hello-world$ npx alignfirst workspace setup -c ABC-1234/new-permission --full

Workspace setup complete!

Worktree type: linked

Status: pending

Workspace: hello-world-ABC-1234-new-permission

Branch: ABC-1234/new-permission

Path: ~/repos/hello-world-ABC-1234-new-permission

Start the dev server with:  npx alignfirst dev

WORKSPACE_CREATED path=~/repos/hello-world-ABC-1234-new-permission

branch=ABC-1234/new-permission

Finalizing… (0s) — tail: ~/repos/hello-world-ABC-1234-new-permission/.local-wt/logs/workspace-setup.log

… ready

dev@laptop:~/repos/hello-world$ cd ../hello-world-ABC-1234-new-permission/

dev@laptop:~/repos/hello-world-ABC-1234-new-permission$ npx alignfirst dev

Starting docker dev server...

[+] Running 2/2

✔ Container hello-world-ABC-1234-new-permission-database  Running  0.0s

✔ Container hello-world-ABC-1234-new-permission-mailpit  Running  0.0s

Starting api dev server...

Starting frontend dev server...

[api] > tsx watch --clear-screen=false src/main.ts

[frontend] > vite --port 18110

[frontend] VITE v7.1.5  ready in 486 ms

[frontend] ➜  Local:  http://localhost:18110/

[frontend] ➜  Network: use --host to expose

[api] Connected to postgres://localhost:18112/hello_world

[api] Applied 0 pending migrations

[api] Listening on http://localhost:18111

[api] ✔  TSC  Initializing type checker...

[api] >  TSC  Found 0 issues.

Dev servers started! (workspace: hello-world-ABC-1234-new-permission)

Open:

autologin: http://localhost:18110/auth/local?email=admin@test.dev

Details:

frontend: http://localhost:18110/  log: .local-wt/logs/frontend.log

api: http://localhost:18111/  log: .local-wt/logs/api.log

database: localhost:18112/hello_world  log: docker compose logs -f database

Ready to run the setup.

AlignFirst Skills

For any stack

Learn the workflow: you drive the coding agent, one step at a time.

Home

At the core is the spec → plans → execution workflow. This lesson shows how to use /alspec and /alplan.

Other AlignFirst skills are simple and effective. Resolve merge conflicts with /almerge, perform code reviews with /alreview, prepare PR/MR descriptions with /aldescription, load the current task context with /alcatchup, and handle small implementations with /al.

From spec to plans to executionA lesson in the spec, plans and execution workflow. A coding agent window, titled Coding agent (Claude Code, Codex, GitHub Copilot, Cursor…), on branch ABC-1234/new-permission, with you drawn on the left and the coding agent on the right. A composer at the bottom types each of your messages and waits for you to press Send. A yellow note on a board explains each step before you send it. Note 1, Spec: send /alspec with the feature; the agent asks until every topic is settled, then writes the spec. You send /alspec New feature: We need a distinct permission for… Two dashed outlines appear under the conversation, what you imagined on the left and what the agent understood on the right. The agent uses Docmap, explores the codebase, thinks, then asks: Grant it to existing admins by default? You answer: No, it must be granted explicitly. The exchange continues in fast-forward, and the outlines slide closer at each exchange until they coincide and read Aligned!. The agent says: Every topic is settled. Writing the spec. The conversation scrolls, the agent writes A1-spec.md, the folder .plans/ABC-1234/ receives it with a brief highlight, the Spec check turns green, and the agent says: The specification is ready. Next, plan the implementation. Note 2, Plan: /alplan turns the spec into plans. You send /alplan. The agent reads the spec, explores, works on a progress bar, decides to split the work into two sub-plans, and A2-main-plan.md, A3-plan-api.md and A4-plan-frontend.md land in the folder in alphabetical order. Note 3, Execute: clear the session, then ask the agent to execute the main plan. You send Execute `.plans/ABC-1234/A2-main-plan.md`: the conversation clears, Session cleared blinks once in the emptied window, then two sub-agents run the sub-plans, api first and frontend once the api is done, and each writes its .summary.md, then the main agent writes A2-main-plan.summary.md; each summary slots in beside its plan. A last pink note sticks under the folder: the work files are shared with the team and can be synced to a plans repository. Beneath the window, three steps, spec, plans and execution, separated by a big grey chevron, each with a grey check that turns green when the step is done.Coding agentClaude Code, Codex, GitHub Copilot, Cursor…ABC-1234/new-permissionyoucodingagent/alspec New feature: We need a distinct permission for…Docmap • Exploring the codebase • ThinkingGrant it to existing admins by default?No, it must be granted explicitly.what you imaginedwhat the agent understoodAligned!Every topic is settled. Writing the spec.WriteA1-spec.mdThe specification is ready. Next, plan the implementation./alplanReading the spec and exploring the codebase.WorkingThis is sizeable work across two stacks.I'll split it into two sub-plans: api, then frontend.WriteA2-main-plan.md·A3-plan-api.md·A4-plan-frontend.mdThree plans, ready to execute.Session clearedExecute `.plans/ABC-1234/A2-main-plan.md`Following the main plan: two sub-plans, two sub-agents.A3 · apiA4 · frontendAll plans completed..plans/ABC-1234/Can't wait to see some work files!A1-spec.mdA2-main-plan.mdA2-main-plan.summary.mdA3-plan-api.mdA3-plan-api.summary.mdA4-plan-frontend.mdA4-plan-frontend.summary.md1 · SpecSend /alspec with thefeature. The agentasks until everytopic is settled,then writes the spec.2 · Plan/alplan turnsthe spec intoplans.3 · ExecuteClear the session,then ask the agentto execute themain plan.Shared with the teamWork files can be synced to a plansrepository, so anyone can catch up.SpecSpecPlansPlansExecutionExecution

Learn the workflow: you drive the coding agent, one step at a time.

Files .plans/ABC-1234/

  • A1-spec.md
  • A2-main-plan.md
  • A2-main-plan.summary.md
  • A3-plan-api.md
  • A3-plan-api.summary.md
  • A4-plan-frontend.md
  • A4-plan-frontend.summary.md

Shared with the team. Work files can be synced to a plans repository, so anyone can catch up.

Coding agent ABC-1234/new-permission

/alspec New feature: We need a distinct permission for…

Every topic is settled. Writing the spec.

Writing A1-spec.md.

The specification is ready. Next, plan the implementation.

/alplan

Reading the spec and exploring the codebase.

This is sizeable work across two stacks. I'll split it into two sub-plans: api, then frontend.

The main plan and both sub-plans are ready.

Session cleared

Execute `.plans/ABC-1234/A2-main-plan.md`

Following the main plan.

The api sub-agent runs first, then the frontend sub-agent. Each writes its summary.

✓ All plans completed.

  1. 1 · Spec. Send /alspec with the feature. The agent asks until every topic is settled, then writes the spec.
  2. 2 · Plan. /alplan turns the spec into plans.
  3. 3 · Execute. Clear the session, then ask the agent to execute the main plan.

Our main workflow Spec Plans Execution

Docmap

For any stack

The agent discovers the documentation structure, then reads the relevant files.

Home

Docmap’s whole footprint in your project is one section of AGENTS.md (or CLAUDE.md).

AGENTS.md

## Docmap - Seek Documentation

At the start of the session, before any investigation or code exploration, run `npx -y alignfirst docmap`. Then read the documentation relevant to the task.

Discovering project documentationThe demonstration opens on the footprint alone: a line stating that Docmap’s whole footprint in your project is one section of AGENTS.md, or CLAUDE.md, the excerpt of that section in the middle of an otherwise empty screen, and a control that hands the screen over to the agent. Once asked, the screen fades and the scene stands in its place; nothing travels. An AGENTS.md excerpt instructs the agent: At the start of the session, before any investigation or code exploration, run npx -y alignfirst docmap. Then read the documentation relevant to the task. A static file tree stands in the first column on the left, showing docs with permissions expanded; four collapsed folders stand for the rest of a documentation that counts dozens of documents. A caret blinks in the empty composer, then the request New feature: We need a distinct permission for… is typed in four word groups. As soon as the word permission is complete, it lights up together with the permissions folder and the two files whose names contain it, adding-a-permission.md and permission-model.md. Playback waits for the visitor to press Send while a note explains that the project has dozens of documents, so the root listing stays short, and that the CLI lets the agent open permissions and find the relevant files. The composer empties and the request appears at the top of the standalone conversation on branch ABC-1234/new-permission. The agent runs npx -y alignfirst docmap. Docmap answers at once, so the call arrives already done and its output lands beside it, in the first panel on the right: a short CLI-help excerpt shows commands for listing the root and a sub-directory, followed by an ellipsis. With dozens of documents, the root listing then shows the five folders and the one root document, code-style.md, with its title and summary. The command lights up in the same colour in both the AGENTS.md excerpt and the call, and the panel's index 1 lights in its own colour together with the 1 on the call it answers, long enough to pair them. The agent then runs npx -y alignfirst docmap permissions, which lights permissions in one colour in three places at once: the call, the file tree and that first output panel. A second output panel lands with it, lighting its index 2 with the call's own 2 the same way, and lists the four files with their titles, adding-a-permission.md, api-checks.md, frontend-checks.md and permission-model.md, and two summaries: How to declare and enforce a permission, and Roles, and who may grant what. The agent finally reads docs/permissions/adding-a-permission.md and docs/permissions/permission-model.md in a single Read, lighting both paths in one colour in both the second panel and the Read, then says it will look at how permissions are checked in the code. The conversation uses the full panel height, then scrolls just enough to reveal a last line holding nothing but an ellipsis. The tool calls remain fully visible, and the demonstration ends there, on work that carries on.Filesdocs/architecture/data/operations/permissions/adding-a-permission.mdapi-checks.mdfrontend-checks.mdpermission-model.mdtesting/code-style.mdAGENTS.mdAGENTS.md## Docmap - Seek DocumentationAt the start of the session, before any investigation or codeexploration, run`npx -y alignfirst docmap`. Then read thedocumentation relevant to the task.AgentABC-1234/new-permissionYouNew feature: We need a distinct  permission  for…Bash1npx -y alignfirst docmapBash2npx -y alignfirst docmap permissionsReaddocs/permissions/adding-a-permission.mddocs/permissions/permission-model.mdNow let me look at how permissions are checked in the code.…1Bash output · docs/Commands:npx -y alignfirst docmapnpx -y alignfirst docmap dir-a…# Documentation## Sub-directories- architecture/- data/- operations/- permissions/- testing/- `docs/code-style.md` — Code style — Coding  standards and formatting rules.2Bash output · docs/permissions/# `permissions/`- `docs/permissions/adding-a-permission.md` —  Adding a permission — How to declare and  enforce a permission.- `docs/permissions/api-checks.md` — API checks- `docs/permissions/frontend-checks.md` —  Frontend checks- `docs/permissions/permission-model.md` —  Permission model — Roles, and who may grant  what.

Files your project

  • docs/
  • permissions/
  • adding-a-permission.md
  • api-checks.md
  • frontend-checks.md
  • permission-model.md
  • code-style.md
  • AGENTS.md

Agent ABC-1234/new-permission

New feature: We need a distinct  permission  for…

✓ 1 · Explore the documentation

npx -y alignfirst docmap

CLI help (excerpt)

Commands:
npx -y alignfirst docmap
npx -y alignfirst docmap dir-a
…

✓ 2 · Find the relevant topic

npx -y alignfirst docmap permissions

✓ 3 · Read the documentation

docs/permissions/adding-a-permission.md

docs/permissions/permission-model.md

Now let me look at how permissions are checked in the code.

…

Three lines in AGENTS.md, and the agent discovers the documentation structure, then reads the relevant files.

AlignDev

For any stack

More than a tool. An assistant.

Home

Your assistant is an AI developer

It delegates the code

As a modern developer, it delegates pretty much everything to Claude Code or Codex.

It keeps work isolated

It uses worktrees and branches on any stack.

It checks the real thing

For UI changes in a web project, it tests in the browser, monitors development server logs, and requests corrections if needed. It keeps screenshots before opening a PR.

It reviews your code

The agent can review code on a GitHub PR or a GitLab MR.

In your terminal or in Slack

It runs in your Claude Code or Codex session, or as an OpenClaw bot on a VPS, in Slack or Discord.

You

You can work on the move

With OpenClaw, an intermittent connection is enough for some tasks, for example on a train. Some work can be done from a phone.

You can try it yourself

It exposes the dev-servers of the web applications it works on, so you can try out a new feature yourself.

You can build without coding

The assistant can handle tickets from start to finish when they do not require a major design decision.

You can ask anything about the code

Asking questions about the codebase becomes easy for everyone.

You can call it a day

A human developer can prepare the plans in the afternoon and entrust their execution to the assistant before leaving.

Notes around the board

A developer at heart

Built by a developer, for developers and their teams.

A taste of next year

In 2027, it will become obvious to everyone that this is how a developer should work. AlignDev lets you experience it ahead of time.

About AlignFirst

Home
Thomas MUR

The person behind the project

Thomas MUR

Freelance developer. Creator of AlignFirst.

I started AlignFirst to help me work with coding agents. It grew from a few prompts into tools we now use every day. They follow a simple principle: agree on what to build before generating the code.

Want to try AlignFirst? My advice is free, and I’m happy to help you get started.

Licenses

Open source

AlignFirst’s skills, CLI, Docmap, Workspaces and AlignDev are published under CC0 1.0. The OpenClaw integration plugin and testing packages use the MIT license.

AlignFirst on GitHub

Built through daily use

  1. The first prompts

    I wrote prompts to generate specs and plans, and added a documentation index to the agent’s instruction file.

  2. From prompts to skills

    Those prompts became agent skills.

  3. Docmap

    I found a documentation helper in OpenClaw’s codebase and generalized it into what became Docmap.

  4. Workspaces

    Workspaces grew out of my effort to turn OpenClaw into a developer using AlignFirst. We now use them daily as human developers, too.

  5. AlignDev

    The first version of AlignDev went live: an OpenClaw assistant that works in Discord and Slack.

  6. AlignDev in coding agents

    AlignDev now also works inside a coding agent.

Get started

Home

Add the AlignFirst tooling to your project

Set up AlignFirst
with your agent.

The setup guide helps you choose and install the tools that fit your project.

  1. Install the setup skill

    Run this command in your terminal. You can install the skill globally or just for this project.

    npx skills add https://github.com/paleo/alignfirst --global --skill alignfirst-setup-guide

  2. Ask your agent

    Open your project with your coding agent and send:

    Use your alignfirst-setup-guide skill. What can I set up in this project?

Once setup is complete, you can uninstall the guide skill. Your project no longer needs it.