alignfirst

AlignFirst is an agent skill designed to bridge the gap between user intent and AI-generated code by enforcing rigorous, collaborative problem-solving protocols. It acts as an orchestrator for software development tasks, ensuring that AI agents investigate, discuss, and document their decisions before modifying the codebase. By requiring a TASK_DIR context, AlignFirst keeps track of task-specific history, making it ideal for complex or long-running development efforts that span multiple sessions. The skill integrates seamlessly into developer environments like Cursor, GitHub Copilot, and Claude Code, turning these platforms into structured engineering assistants.

• Technical Specification (alspec): Conducts deep investigations to produce formal design documents prior to implementation.

• Implementation Planning (alplan): Breaks down complex features into actionable steps, allowing for multi-agent coordination or sequential work.

• Align-and-Do (AAD): A lightweight, high-speed protocol for quick fixes and routine updates, emphasizing immediate collaboration.

• Automated Documentation: Generates PR/MR descriptions and structured code review reports by parsing existing specs and summary files.

• Context Persistence: Maintains state across sessions using a local .plans directory, preventing context window exhaustion and providing clear project audit trails.

• Best for: Software engineers, technical leads, and developers working on complex features who require consistent, documented progress.

• Workflow: Start by running the specified protocols (alspec, alplan, or al). The agent will manage the CYCLE_LETTER and FILE_NUMBER to maintain an organized repository of work artifacts.

• Inputs/Outputs: Requires a unique TICKET_ID for each task. Produces markdown artifacts within the project’s .plans/ directory. These files serve as the primary source of truth for the agent during execution.

• Constraints: Recommended to add .plans to .gitignore. Requires an initial configuration of AGENTS.md or CLAUDE.md to detect ticket formatting and project-specific commit conventions for optimal results.