---
name: align
description: Establish and maintain personal project alignment in ALIGNS.md, including selected PR or conversation history review for scoped taste invariants. Use when goals or priorities are unclear, important decisions diverge from the user's expectations, repeated corrections expose a missing criterion, or a long autonomous run needs judgment calibration. Apply existing agreements without reopening routine decisions.
license: MIT
metadata:
  version: "0.6.0"
---

# Align

Help a user and their agent agree on what good work means and keep decisions
consistent with that agreement. The maintained skill supplies the method;
project-root `ALIGNS.md` holds the user's current criteria. Updating the skill
must never replace, reconfirm, or migrate those criteria automatically.
Use the user's language and project conventions. Do not import preferences
from the skill's source repository.

## Existing installations

The agreement filename is now `ALIGNS.md`. If a project still has `ALIGN.md`,
read it as the existing agreement. When migration is authorized, rename the file
and update its instruction references without changing its criteria or confirmation
date. If both files exist, compare them with the user before choosing or merging;
never silently overwrite either. `$align` remains the invocation.

## Read before asking

Identify the target project, applicable instructions, existing `ALIGNS.md`,
relevant conversation, and changes that could affect the current decision.
Check whether Git is available and this is a work tree. Use available history
and uncommitted work; a timestamp does not prove all later work was reviewed.
If history is unavailable, explain only material gaps. Do not initialize Git
or create an alternative alignment log without a request.

At initial setup, or after the user changes tools, read
[environment setup](references/environment.md). Establish which CLI is primary
and whether it is the current client. Reuse explicit context; ask once if it
is unclear. Do not infer the main client just from a filename or installed binary.
Inspect the actual instruction entrypoints before proposing any changes.
For an open-purpose invocation, defer setup questions until a path is selected.

## Start with a numbered choice when the purpose is open

When the user invokes align without a clear purpose, show this short menu in
their language after reading the available project context. Keep numbers stable:

1. Set or review the project's direction and personal criteria.
2. Review a recent decision that missed expectations.
3. Find candidate criteria in selected PR or conversation history.
4. Rehearse judgment before a long autonomous run.
5. Recommend a starting point from the current project context.

Accept an explicit numbered invocation such as `$align 3` as that starting path
without showing the menu again. Otherwise ask for a number or a free-form answer.
If the client offers choice buttons, keep the numbers in their labels; plain
text is sufficient. Treat a number as
an answer to the most recent pending menu, including a history-scope menu.
Do not show the start menu again after a valid choice. For an ambiguous answer,
clarify only the ambiguous part. An unanswered menu does not select a default.

Skip this menu when the request, earlier choice, or active task already gives a
clear purpose, including implicit activation during a mismatch. Do not turn a
routine task, conceptual question, or known execution error into a menu session.
For option 5, recommend one path with a reason from known context and begin its
first useful question, if one remains. Do not invent preferences or collect
history to recommend.

Option 3 opens the source, scope and time-estimate choice in
[history review](references/history.md);
it does not authorize reading unspecified logs or all PRs. Reuse scope already given.

After selecting a path, give one brief outline of the relevant steps:
**check context → clarify unresolved choices → summarize criteria → save authorized
changes**. Name the current step at meaningful transitions, not on every reply.
Adapt the outline: history review starts with source/scope selection and evidence;
rehearsal uses hypothetical decisions without executing the run. Skip completed
steps and do not add confirmation gates. Saving follows the authorization rules
below; selecting a path alone does not confirm lasting criteria. If no criterion
changes, close with the outcome instead of rewriting the agreement. Only include
environment setup or instruction-file connection when needed for the selected task.

## Choose the smallest useful alignment

| Situation | Action |
| --- | --- |
| New project | Clarify intended outcome and consequential trade-offs before choosing implementation details. |
| Existing work without ALIGNS.md | Describe what exists, then ask what should stay or change. Existing code is not evidence of consent. |
| Routine task within the agreement | Apply the criteria and proceed. No interview or gratuitous report. |
| Important disagreement or repeated correction | Compare expectation and result, repair what is already clear, then use the focused drift review below. |
| User does not know what to do next | Offer a brief alignment conversation with concrete options. Do not invent a roadmap or start work without a direction. |
| Long autonomous or repeated run | Check agreed boundaries and offer a short hypothetical rehearsal if consequential judgments are untested. |
| Loop or goal configured, stopped, or marked complete against expectations | Compare the request, configured objective, actual state, and results. Repair known errors; clarify only unresolved scope, completion, or stopping criteria. |

For drift, uncertainty, or autonomous work, read
[recurring alignment](references/recurring.md). A suggestion is not a new
scheduled task or permission to run unattended.

## Learn from selected history

When earlier feedback could reduce the user's effort, offer the optional
[history review](references/history.md). Let the user choose recent or full PR
history, accessible project conversations, or neither, with estimated retrieval
and analysis times. Reuse a clear choice; never scan all personal logs by default.

Use **taste invariants** as candidates for criteria that hold across observed
situations within a stated scope. Find supporting decisions and counterexamples;
keep personal preferences separate from team requirements and one-off exceptions.
Repeated feedback is evidence to discuss, not permission to save a permanent rule.
Apply confirmed criteria during self-alignment and revisit them when new user
evidence changes the agreement. Do not claim a personality trait is immutable.

## When context is missing

A short request may delegate judgment. Read relevant project context and apply
confirmed criteria before asking for more detail. Do not infer a user's ability,
personality, or preferred questioning style from message length.

Ask when a missing fact could materially change the result or scope. Briefly
explain what depends on the answer, and group related questions in one round.
Offer concrete options when useful. Within authorized scope, proceed with minor,
reversible choices and judgments already delegated; state assumptions when they
matter. An unanswered question is not consent. Continue independent work while
a consequential choice remains open.

If repeated misunderstandings suggest a mismatch in when to ask, use the
[context review](references/recurring.md#when-missing-context-causes-rework).
Keep task facts in task context. Record a lasting questioning preference in
ALIGNS.md only when explicitly requested or confirmed, with its scope. Do not
require a preference interview for every short request.

If the user asks you to learn or remember their preferences but has supplied no
concrete criterion, ask for one before creating an agreement. Keep proposals in
the conversation unless a file draft was requested. Do not fill ALIGNS.md with
copied tool restrictions or setup metadata to stand in for missing preferences.
An explicit lasting criterion can be saved directly; do not reconfirm it.

## Agree through conversation

Ask 1-3 related questions about consequential unresolved matters. Reuse clear
answers and accepted decisions. Cover only relevant gaps: outcome, success,
scope, priorities, constraints, things to avoid, and autonomy boundaries.
Use a concrete choice to clarify a vague preference. Label inferences and
hypotheticals; neither is an agreement.

Once the essentials are clear, show a short draft. Do not keep interviewing
to fill categories. Save after confirmation or explicit authorization for the
specific lasting change. Honor delegated drafting scope, marking unconfirmed
parts as draft. A correction to one result is not automatically a lasting rule.

## Keep the agreement current

Preserve unrelated content. Record requirements separately from defaults, with
a reason where it changes decisions. Keep detailed tasks and the skill's full
method out of ALIGNS.md. At initial setup or a requested full review, include a
short **Revisit alignment** section with the items below. A narrow criterion
update must not expand into environment setup merely because this section is
missing; mention a material discovery problem only when it affects the work.

- A working invocation for this client, plus the portable request
  “Use the align skill to review this project's ALIGNS.md with me.”
- The trusted source `https://github.com/hmmhmmhm/aligns.md`, installed route and
  supported update method. Never claim an unverified installation or auto-update.
- The chosen primary CLI and canonical instruction file, and any unresolved
  setup issue. Keep this current instead of accumulating setup history.
- User-agreed review occasions or autonomy boundaries when relevant. Do not
  invent a daily schedule, reminders, telemetry, or an alignment diary.

Keep current criteria only and use Git history when available. Git availability
does not authorize staging, committing, or publishing. Never revise agreements
to justify the agent's mistake or its preferred outcome. Follow the applicable
instruction hierarchy and distinguish a one-off exception from a lasting change.

End with `Last aligned: YYYY-MM-DD HH:mm (time zone)` only at actual full user
confirmation. Use a known zone, or explicitly labeled UTC. Reading, editing,
updating the skill, and automatic review are not confirmation. For partial
confirmation, annotate only affected criteria with their latest confirmation
times and preserve the full timestamp. Replace superseded annotations instead
of logging them. An unconfirmed draft ends `Last aligned: Not yet confirmed.`
Do not invent a date for an undated agreement.

## Connect future sessions

Use the environment reference to connect the canonical instruction file to
ALIGNS.md and to the installed skill. Prefer a short maintained trigger block
from [the instruction template](assets/instruction-block.md), not a copy of
this workflow. Add it once and preserve other instructions. For additional
clients, use safe relative symlinks when their format and loading rules allow;
never replace distinct files or nested policies with links without reconciling
and obtaining authorization for the concrete replacement.

Method updates use the installer's supported route. Read
[installation and updates](references/installation.md) when installing,
repairing discovery, or updating. During ordinary work use the installed version;
do not fetch or change it every turn. An update does not authorize publishing
project data or changing the user's criteria.

Finish an alignment session with the agreed changes, consequential open issues,
and saved paths. In routine work, return to the task without a closing approval
question. If the user declines a suggestion, continue within existing agreements
and do not repeat it without new evidence.