Alignfirst alignfirst

Collaborative problem-solving protocols. Write technical specifications (spec, or alspec), create implementation plans (plan, or alplan), or use Align-and-Do Protocol (AAD). Also generates PR/MR descriptions (aldescription) and code review reports (alreview).

install

source · Clone the upstream repo

git clone https://github.com/paleo/alignfirst

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/paleo/alignfirst "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/alignfirst" ~/.claude/skills/paleo-alignfirst-alignfirst && rm -rf "$T"

manifest: skills/alignfirst/SKILL.md

source content

AlignFirst Guide

If you don't already know which protocol to use, read overview.md first.

Protocols

Technical Specification (spec, or alspec): spec-protocol.md
Implementation Plans (plan, or alplan): plan-protocol.md
Align-and-Do Protocol (AAD): aad-protocol.md
Description (aldescription): description-protocol.md
Code Review (alreview): review-protocol.md

TASK_DIR Location

TASK_DIR is the directory where work files related to a task are stored. Usually, we use TASK_DIR =

.plans/{TICKET_ID}/

(a sub-directory of the

.plans

folder). If no ticket ID is known, ask the user for it.

Create TASK_DIR if it doesn't exist
Or, list existing files

File Naming Convention

Format:

{CYCLE_LETTER}{FILE_NUMBER}-{FILE_TYPE}.md

Common file types:

```
spec
```
- technical specification
```
plan
```
- implementation plan
```
AAD.summary
```
- AAD summary document
```
description
```
- PR/MR description
```
review
```
- code review report

Example structure:

.plans/
├── 123/
│   ├── A1-spec.md
│   ├── A2-plan.md
│   └── A3-AAD.summary.md
│   └── B1-spec.md

Notes

TICKET_ID is a unique identifier for the task, often an issue or ticket number.
Cycles are identified by a CYCLE_LETTER (A, B, C...). The user decides when to start a new one.
In a cycle, determine the next FILE_NUMBER from existing file names. Every new file must have a bumped file number.
Do not bother the user with CYCLE_LETTER or FILE_NUMBER. They are for internal organization. It's up to you to list the files and determine the last CYCLE_LETTER and FILE_NUMBER. Start CYCLE_LETTER with
```
A
```
if there is no existing cycle, and FILE_NUMBER with
```
1
```
. So you just need to ask for a ticket ID if you don't have one.
When the user requests a new cycle: bump CYCLE_LETTER and reset FILE_NUMBER.
There is no strict sequence of file types in the workflow. Available file types are also flexible; if you need a new one, just create it.