AlignFirst

How AlignFirst works

Software engineering tools built for 2026

Three independent tools and a teammate.

AlignFirst overviewAlignFirst combines three tools. Workspaces provide isolated Git worktrees for parallel development. AlignFirst Skills guide a coding agent from specification to plans and execution inside every workspace. Docmap feeds that workflow with the project documentation. AlignFirst Dev Kit for OpenClaw turns an OpenClaw assistant into a developer in Slack or Discord that delegates tasks to Claude Code or Codex.AlignFirstSoftware engineering tools built for 2026WorkspacesIsolated dev-servers inGit worktrees. The freedomof Conductor or Paseo,without changing your tools./alspec/alplanexecuteAlignFirst SkillsDevelop with a clear flow:spec → plans → execution.Shared work files keepthe team aligned.DocmapA table of contents forthe documentations availableto your coding agents.feature-1feature-2feature-3SPECPLANSEXECUTEdocs/APITech stackGuidesAlignFirst Dev Kit for OpenClawYour OpenClaw assistant🦞in Slack or Discord.Delegate tasks to Claude Code or Codex, work from anywhere,and extend your productive hours.

Workspaces

Isolated dev-servers in Git worktrees. The freedom of Conductor or Paseo, without changing your tools.

~/project$ pnpm workspace setup✓ branch   ✓ worktree   ✓ server
Play the Workspaces demonstration

Workspaces

Create an isolated place for each task, without changing your tools.

Home

The workspace setup command prepares a branch, a worktree and an isolated dev-server. The dev command is made for humans and AI agents alike: it shows the dev-server logs as usual, and exposes them to the agent simultaneously through log files.

dev@laptop: ~/repos/hello-world

dev@laptop:~/repos/hello-world$ pnpm workspace setup -c ABC-1234/document-preview

$ node scripts/workspace/workspace.mjs setup -c ABC-1234/document-preview

Workspace setup complete!

Worktree type: linked

Status: pending

Workspace: hello-world-ABC-1234-document-preview

Branch: ABC-1234/document-preview

Path: ~/repos/hello-world-ABC-1234-document-preview

WORKSPACE_CREATED path=~/repos/hello-world-ABC-1234-document-preview

branch=ABC-1234/document-preview

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

… ready

dev@laptop:~/repos/hello-world$ cd ../hello-world-ABC-1234-document-preview/

dev@laptop:~/repos/hello-world-ABC-1234-document-preview$ pnpm dev

$ node scripts/workspace/dev-server.mjs

Starting docker dev server...

[+] up 2/2

✔ Container hello-world-ABC-1234-document-preview-database  Running  0.0s

✔ Container hello-world-ABC-1234-document-preview-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-document-preview)

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

Align on the spec together, let the agent plan, then execute the plans in a fresh session.

Home
From spec to plans to executionA conversation window on branch ABC-1234/document-preview, with you drawn on the left and the agent on the right. A composer at the bottom types each of your messages and waits for you to press Send. First: /alspec New feature: users need to preview draft documents. 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: Preview saved drafts or unsaved changes too? You answer: Unsaved changes too, without publishing. The exchange continues in fast-forward, and the outlines slide closer at each exchange until they coincide and read Aligned!. You send: We're good. Write the spec. The conversation scrolls, the agent writes A1-spec.md and the folder .plans/ABC-1234/ receives it with a brief highlight. You send /alplan in the same conversation. 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. 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 yellow note stuck to the folder says the work files are shared with the team and can be synced to a plans repository. Beneath, three step labels, spec, plans and execution, separated by a big grey chevron, light up and get a check in turn.Coding agentABC-1234/document-previewyouagent/alspec New feature: users need to preview draft documents.Docmap • Exploring the codebase • ThinkingPreview saved drafts or unsaved changes too?Unsaved changes too, without publishing.what you imaginedwhat the agent understoodAligned!We're good. Write the spec.WriteA1-spec.md/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.mdShared with the teamWork files can besynced to a plansrepository, so anyonecan catch up.SpecSpecPlansPlansExecutionExecution

Align on the spec together, let the agent plan, then execute the plans in a fresh session.

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/document-preview

Send the request below to start the conversation.

/alspec New feature: users need to preview draft documents.

We're good. Write 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.

Our main workflow SpecPlansExecution

Docmap

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

Home
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 excerpt returns to the top and the rest of the scene arrives around it. An AGENTS.md excerpt instructs the agent: Before investigating code, run npx -y alignfirst docmap and read the relevant documentation. A static file tree stands in the first column on the left, showing docs with document-edit expanded. A caret blinks in the empty composer, then the request New feature: users need to preview draft documents is typed in four word groups. Playback waits for the visitor to press Send while a note explains that the CLI lets the agent open document-edit and find the relevant documentation file. The composer empties and the request appears at the top of the standalone conversation on branch ABC-1234/document-preview. The agent runs npx -y alignfirst docmap. Docmap answers at once, so the call arrives already done and its simplified output lands beside it, in the first panel on the right, listing documentation directories and code-style.md. 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 document-edit, which lights document-edit 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 document-format.md, drafts.md and lifecycle.md, including the summary How drafts are saved and versioned. The agent finally reads docs/document-edit/drafts.md, lighting that path in one colour in both the second panel and the Read, then says it will look at how drafts are rendered in the code. The conversation scrolls the request out of sight to make room. A last line holds nothing but an ellipsis, the conversation settles once more, and the demonstration ends there, on work that carries on.Docmap’s whole footprint in your projectis one section ofAGENTS.md(orCLAUDE.md).Filesdocs/architecture/data/document-edit/document-format.mddrafts.mdlifecycle.mdoperations/testing/code-style.mdAGENTS.mdAGENTS.md## Docmap — Seek DocumentationBefore investigating code, run`npx -y alignfirst docmap`andread the relevant documentation.AgentABC-1234/document-previewYouNew feature: users need to preview  draft  documents.Bash1npx -y alignfirst docmapBash2npx -y alignfirst docmap document-editReaddocs/document-edit/drafts.mdNow let me look at how drafts are rendered in the code.…1Bash output · docs/# Documentation## Sub-directories- architecture/- data/- document-edit/- operations/- testing/- docs/code-style.md — Code style — Codingstandards and formatting rules.2Bash output · docs/document-edit/# document-edit/- docs/document-edit/document-format.md — Format- docs/document-edit/drafts.md — DraftsHow drafts are saved and versioned.- docs/document-edit/lifecycle.md — Lifecycle

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

AGENTS.md

## Docmap — Seek Documentation

Before investigating code, run `npx -y alignfirst docmap` and read the relevant documentation.

Files your project

  • docs/
  • architecture/
  • document-edit/
  • document-format.md
  • drafts.md
  • lifecycle.md
  • code-style.md
  • AGENTS.md

Agent ABC-1234/document-preview

New feature: users need to preview  draft  documents.

✓ 1 · Explore the documentation

npx -y alignfirst docmap

✓ 2 · Find the relevant topic

npx -y alignfirst docmap document-edit

✓ 3 · Read the documentation

docs/document-edit/drafts.md

Now let me look at how drafts are rendered in the code.

…

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

AlignFirst Dev Kit for OpenClaw AI developer

More than a tool. A partner.

Home

Your OpenClaw developer

It delegates the code

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

It keeps work isolated

It works cleanly in worktrees and branches.

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 draft PR.

It reviews your code

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

In Slack and Discord

This is an OpenClaw instance that uses a VPS as a workstation. OpenClaw communicates in Slack or Discord.

You

You can work on the move

An intermittent connection can be enough to work on some tasks, for example on a train. Some of the work can also be done from a phone.

You can try it yourself

OpenClaw exposes the local dev-servers of the web applications it is working on. So you can try out a new feature yourself.

You can build without coding

OpenClaw 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 OpenClaw 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. OpenClaw 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 and Workspaces 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. A teammate in Discord and Slack

    The very first version of the AlignFirst Dev Kit for OpenClaw works.

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.