alignfirst

The AlignFirst CLI provides collaborative software-development workflows, work files, and documentation discovery. Work files are organized by ticket and kept either git-ignored in the project or synchronized through a work-files repository.

See the product page for a demonstration.

Agent skills

Nine Agent Skill stubs expose the CLI as commands in Claude Code, Codex, GitHub Copilot, and Cursor. Install them globally:

npx skills add https://github.com/paleo/alignfirst --global \
  --skill al --skill alplan --skill alspec --skill aldescription \
  --skill alreview --skill alcatchup --skill almerge \
  --skill alcatchupaad --skill alcatchupspec

Install the alignfirst skill when a project's AGENTS.md does not run npx alignfirst context; it lets the agent recognize a protocol named in prose:

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

The skills run the CLI through npx, so installing it is optional.

Update the agent skills

npx skills update --global

Workflows

These examples use the / form. Replace it with $ in Codex.

| Workflow | Command | Result | | --- | --- | --- | | Specification | /alspec <request> | Discuss and write a technical specification. | | Planning | /alplan | Turn a specification into one or more implementation plans. | | Align and do | /al <request> | Discuss and implement a small change, then write a summary. | | Description | /aldescription | Summarize the work and propose a commit message. | | Review | /alreview | Review the current branch against its base. | | Merge | /almerge | Resolve merge or rebase conflicts. | | Catch up | /alcatchup | Load the current ticket history and continue. | | Catch up and AAD | /alcatchupaad <request> | Load ticket history, then start AAD. | | Catch up and spec | /alcatchupspec <request> | Load ticket history, then start specification. |

To implement a plan, start a fresh agent context and ask it to execute the plan file.

AlignFirst stores the work files of a ticket, such as specifications, plans and summaries, in .plans/<ticket-id>/. It normally derives the ticket ID from the request or branch and asks when none is available. Files use a cycle letter and sequence number, such as A1-spec.md and A2-plan.md.

Global CLI

To type alignfirst instead of npx alignfirst, install the CLI globally:

npm install -g alignfirst

Update the global CLI

npm update -g alignfirst

Set up a project (with your agent)

Temporarily install the setup-guide skill:

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

Then ask your agent:

Use your alignfirst-setup-guide skill. What AlignFirst tooling could we add in this project?

The guide installs the selected components and configures the repository. You can remove the setup-guide skill once setup is complete.

CLI commands

• guide — Print an AlignFirst protocol.
• ticket — Resolve a ticket directory, load its history, or get its next file.
• sync — Synchronize the work files with the work-files repository.
• plans — Link .plans to the work-files repository, check the link, archive tickets.
• docmap — Browse project documentation.
• conventions — Print the effective project conventions.
• context — Print the conventions, the documentation map when docs/ exists, and the protocol aliases.
• config — Report the effective project configuration.
• doctor — Diagnose an AlignFirst setup.

Run alignfirst --help for command usage or alignfirst guide to choose a protocol. alignfirst guide <protocol> prints the selected protocol followed by the ticket directory and work file rules. Add --protocol-only when those rules are already in context.

Catchup output

alignfirst ticket [<id>] --catchup prints the ticket's Markdown files, plans excluded.

Upgrade from v1, v2, or v3

Install the setup-guide skill and ask your agent to run its upgrade route:

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

Use your alignfirst-setup-guide skill. Upgrade AlignFirst in this project.

You can remove the setup-guide skill once the upgrade is complete.

License

CC0 1.0 Universal.