AlignFirst Skill

AlignFirst enables AI agents to write the code you would write. It's distributed as an Agent Skill and works well with:

• GitHub Copilot
• Cursor
• Claude Code
• OpenAI Codex

Installation

Give your agent this installation prompt.

Usage

Generate Technical Specification

A specification can be written long before the implementation. The agent helps you write it by investigating and initiating a discussion:

/alspec [something to do]

The agent will discuss with you, then write a _plans/123/A1-spec.md file.

Note: 123 is the ticket ID. If it can be deduced from the branch name, it will. Otherwise the agent will ask you. A1 means it's the first file of cycle A (files are organized by cycles).

Generate Implementation Plan(s)

Plans orchestrate what agents or subagents will do:

/alplan

The agent reads the spec and writes a plan _plans/123/A2-plan.md, or a main plan _plans/123/A2-main-plan.md with several sub-plans.

Implementation

Clear the context, then execute the plan(s):

Execute the plan `_plans/123/A2-main-plan.md`

The agent executes the plan and writes .summary.md files.

Align-and-Do Protocol (AAD)

There is also a lighter prompt for small tasks without specs or plans. Here's how to trigger it:

/al [something to do]

The agent will discuss it with you first, then work directly on the codebase. At the end, a _plans/123/A1-AAD.summary.md file will be written.

Additional Information

About Agent Skills

Agent Skills is an open standard that works out of the box in Claude Code. Here are the documentations:

• Copilot in VS Code
• Cursor
• Claude Code
• Codex
• Gemini CLI
• Antigravity

Rationale

Specs, plans, and summaries must be written in well-organized (git-ignored) local files, because:

1. The context window is limited, the compression mechanism is opaque, and we want to be able to continue an unfinished task in a fresh session.
2. It's a way to keep track of what was agreed upon with the agent and what has been done.

Is it "Spec-Driven Development" (SDD)?

I don't know. If you have a clue, let me know, I'm interested.

Technical Documentation Authoring Skill

The Technical Documentation Authoring skill is independent of AlignFirst but is provided here. It helps you create skills that document your project:

1. Give your agent this installation prompt.

2. Clear the context, then ask it:

   Help me bootstrap our project skills. Use technical-documentation-authoring.

It can also work alongside AlignFirst:

/al We need a documentation about [topic]. Use technical-documentation-authoring.

Upgrades, Migrations

• Upgrade from v1: If you have an old _docs/alignfirst/ installation, migrate to the Agent Skills standard
• Install AlignFirst Skill
• Install Technical Documentation Authoring Skill
• Update Skills: Update installed AlignFirst and/or Technical Documentation Authoring skills to the latest version

License

CC0 1.0 Universal.