hmmhmmhm/align.md/align

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 project criteria. An optional, explicitly linked personal ALIGNS.md holds confirmed defaults across projects. Updating the skill must never replace, reconfirm, or migrate those criteria automatically. Here, self-alignment means helping the user clarify their preferences and decision criteria and checking the agent’s work against them. The optional data path prepares examples for user-run fine-tuning; this skill does not train models or let the agent set its own values. 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. The skill name remains align; users can request it in natural language.

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. 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 setup or discovery repair, verify the required skills from the actual session workspace using the environment reference. When connecting project instructions, make align required for alignment work and preserve the user's other scoped skill requirements. A recommendation or installed skill is not automatically required. 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.
6. Set up or review personal ALIGNS.md defaults across projects (optional).
7. Add the ALIGNS.md badge to this project's README (only when absent).
8. Set up or review personal training-data collection and export (optional).

Before offering path 7, inspect the target README using README badge. Omit it when the badge is already present, declined, deferred, or outside the requested scope; preserve the other numbers. If the README cannot be inspected, report that limitation rather than guessing that a badge is missing.

Accept a numbered choice or a clear natural-language request as the starting path without showing the menu again. Preserve existing command aliases for users who already use them, but do not require or suggest a command to continue. Otherwise ask for a number or a free-form answer. Use the client's available structured-question UI when its active mode supports it. Follow session flow for capability limits, progress tracking, and the next-choice step. Keep stable numbers in labels and accept natural-language replies. 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; it does not authorize reading unspecified logs or all PRs. Reuse scope already given.

Option 6 follows personal alignment. Offer user-selected personal documents or notes as input, and local storage or an optional personal repository. Selection alone does not authorize cloning, publishing, or promoting source content to confirmed global criteria. Keep project-only use simple.

Option 7 follows README badge. Selection authorizes the scoped README edit, not publishing, remote changes, or a new alignment interview. Recheck before editing and skip an existing badge without duplication.

Option 8 follows training data. For explicitly requested team batches, also use team training data. Selection opens setup or review; agree on sources, scope, storage and review mode before collection. Reuse existing authorization without enabling unrelated collection. Keep data separate from ALIGNS.md. Do not train a model, commit, upload, or start a background collector merely because this path was selected. Developing this skill does not authorize collecting the developer's conversations as training data.

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; badge setup checks for an existing badge, adds it if absent, and verifies the README; training-data setup agrees on collection settings, records authorized candidates, and reviews examples before a requested export. 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, report that outcome without rewriting the agreement, then use the continuation rule below. Only include environment setup or instruction-file connection when needed for the selected task.

Keep the conversation moving

Users can ask in ordinary language whenever the skill is available: “Help me align this project's criteria,” “That decision missed what I meant,” or “Let's organize my preferences across projects.” Treat “자가정렬 진행해봅시다” as an explicit request to start or resume alignment, using available session progress. Accept “self alignment” and “self-alignment” in requests such as “Let’s do a self-alignment check” or “Help me with self alignment.” Keep earlier natural-language examples valid, including “Let’s review my alignment.” No exact phrase or command is required. Resolve intent from the conversation; unrelated uses of words like alignment do not trigger an interview. Do not promise invocation when the client cannot discover or load the skill.

Treat menu answers, client selection, source selection, and storage choices as intermediate steps in the active request. Keep the chosen purpose, scope, answered questions, and pending step in conversation context. After an answer, resume that step in the same turn: do the authorized work or ask the next consequential question. Do not end with “this path is suitable,” “run the skill,” or “say continue” when the user already asked for that work. Installation or discovery repair is a substep when setup and alignment were requested together; return to the alignment work after verifying it. An installation-only request does not authorize an interview.

When an item is ready to save, show the concrete criterion and destination scope, and ask once if saving has not already been authorized. Reuse clear authorization; do not ask again for each sentence or treat a pending answer as consent. After confirmation, save the item, complete its authorized connection and verification, and state what was actually saved. A single-item confirmation updates only that item's confirmation annotation, not the whole document's Last aligned time.

After completing an item in an active alignment session, always provide a next-choice step unless the user requested stopping or only that item. Follow session flow: summarize completion, exclude already completed or declined topics, recommend the best remaining eligible topic with a reason, show all other remaining paths, and offer a finish choice. Account for all eight paths before filtering: not yet explored is not completed or inapplicable. Path 7 is an exception: offer it only after confirming the README badge is absent. An unchosen history source or personal setup remains an optional next direction; a mismatch review can invite an example without asserting that one exists. Path 5 is navigation, not another exercise. Use the supported question UI, or one numbered text question if it cannot fit every remaining path. Do not silently end because the selected item is finished. If no eligible topic remains after the coverage check in session flow, explain the exclusions, recommend finishing and offer space for a user-named topic; do not invent a gap or restart the menu.

Continue already authorized multi-item work without another selection gate. Otherwise wait for the user's choice before starting new scope. Reuse an answered selection without asking for an invocation or “continue.” Respect tool availability and mode restrictions, and do not equate a default selection with an answer. In Codex, do not send a final/completion response immediately after an asynchronous question whose answer is required. Keep the question pending and use a supported interruptible wait. An accepted request does not prove UI display. Follow the Codex question-lifecycle guidance in session flow; include a question-resume link only when officially supplied or documented. In routine non-alignment work, apply existing criteria without a follow-up menu.

Make it easy to return

Offer a brief return invitation only when closing a session that actually used align to perform self-alignment. Show it at most once per session, not after each item. For example: “언제든 ‘자가정렬 진행해봅시다’라고 말씀해 주세요.” English: “Whenever you want to revisit your criteria, say ‘Let’s do a self-alignment check.’” Adapt naturally for other languages. Omit it during ordinary project work, installation-only work, and skill development or editing. Reading the skill or applying existing criteria does not count as a self-alignment session. Honor requests to omit reminders. Never load align just to add one. Keep required next choices and pending answers intact; an invitation must not close an unfinished session. Do not promise native routing or availability that has not been verified.

During authorized instruction refresh, replace older managed blocks that ask for ordinary-task reminders. A method update alone does not refresh existing blocks. Preserve other instructions and personal criteria.

Choose the smallest useful alignment