Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Development

Alignfirst

A monorepo of reusable skills and tools (plans, docmap, workspace, OpenClaw test harness) designed for AI-assisted software development workflows.

paleo · AI review on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add paleo/alignfirst

About this skill


name: alignfirst description: "Collaborative problem-solving protocols. Read when the user names AlignFirst or a protocol alias: spec, alspec, plan, alplan, AAD, al, catchup, alcatchup, merge, almerge, alreview, or aldescription." license: CC0 1.0 metadata: author: Paleo version: "3.12.0" repository: https://github.com/paleo/alignfirst

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
  • Catch Up (catchup, or alcatchup): catchup-protocol.md
  • Merge (merge, or almerge): merge-protocol.md
  • Code Review (alreview): review-protocol.md
  • Description (aldescription): description-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.

When .plans/{TICKET_ID}/ is missing, test whether the single path .plans/_archives/{TICKET_ID}/ exists. If it does, move it back to .plans/{TICKET_ID}/ before continuing. Never list .plans/_archives/: its content would flood the context with old ticket IDs.

  • Create TASK_DIR if it doesn't exist
  • Or, list all existing files (do not truncate)

Work without a ticket: when the user says there is no ticket, issue a side ticket, a ticket kept aside from the ticket system. Its ID is side-{N}: find the highest side-{N} directory in .plans/ and take N + 1 (side-1 if there is none). Reuse an existing side-{N} directory when the user refers to that earlier work. Omit the ticket ID from commit messages.

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
  • merge.summary - merge conflicts resolution summary

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 protocol or the user decides whether the next file continues the current cycle or starts a new one.
  • To determine the next filename in the current cycle: find the highest CYCLE_LETTER, then the highest FILE_NUMBER within it. Bump the number.
  • For a new cycle: bump CYCLE_LETTER and reset FILE_NUMBER to 1.
  • Do not bother the user with CYCLE_LETTER or FILE_NUMBER. They are for internal organization. Start CYCLE_LETTER with A if there is no existing cycle. So you just need to ask for a ticket ID if you don't have one.
  • 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.