Help agents make decisions that reflect the user's judgment and continuously identify and address gaps between their work and the user's expectations.
Alignment is an essential part of working with AI. It deserves a dedicated document because expectations differ between users and evolve over time.
ALIGNS.md holds the user's current goals, priorities, preferences, constraints, and decision criteria.
Keep these separate from harness configuration and general agent instructions. AGENTS.md should explain when and how to use ALIGNS.md, while ALIGNS.md remains the source of alignment criteria.
Focus initially on alignment between an individual user and their agents. Team data pilots may use voluntary manual submissions and human review against explicitly agreed team criteria. Automatic multi-user agreement merging and conflict resolution remain outside scope. This limited team-data extension was requested on 2026-10-18 (Asia/Seoul); it does not authorize collecting any team's records or creating shared storage.
Provide an easy-to-use skill that works across new and existing projects. Make it discoverable through relevant skill directories and distribution services, verifying support and registration status rather than assuming universal coverage.
- Agents make decisions consistent with the user's stated criteria.
- Agents notice meaningful misalignment and propose corrections.
- Users spend less effort repeating expectations and correcting avoidable misunderstandings.
- The skill is easy to discover, adopt, and use.
- Ask only consequential, unresolved questions.
- Distinguish confirmed expectations from assumptions.
- Adjust autonomously within existing agreements.
- Reflect lasting changes when the user's intent is clear.
- Do not turn one-off exceptions into permanent preferences.
- Never rewrite agreements to justify an agent's own results.
- Continue independent work while a decision awaits clarification.
When my request is brief, use the existing conversation and project documents first. Ask only for missing information that would materially change the result or scope, grouping related questions. Make minor reversible choices and already delegated decisions within the authorized scope. Do not repeat answered questions.
The shared skill should help users agree on when to ask and when to proceed. Repeated misunderstandings can prompt a focused review of that preference. Keep task-specific answers separate from lasting criteria, and save the latter only on explicit direction or confirmation. Never infer a user's ability or personality from how little context they provide.
Check whether the target project uses Git.
Keep only current alignment criteria in ALIGNS.md. When Git is available, use its history to track changes instead of maintaining a separate alignment log.
If Git is unavailable, explain the history limitation. Do not initialize Git or create an alternative history file without a user request.
Review available changes since the last alignment for meaningful drift or new criteria. Do not repeat resolved questions without new evidence.
Record the last full alignment time only after the user confirms the document. Record partial confirmations separately without implying a full review.
Use ALIGNS.md for the project and agreement file, and hmmhmmhm/aligns.md for the
repository. Keep align as the skill name. Use https://aligns.md as the official website. The custom domain and SSL are
active; keep public site links and metadata on this domain. Preserve historical benchmark
evidence and its hashes when updating current branding.
- Keep English as the source of truth for repository documentation. Maintain Korean and Japanese README translations in the same change when shared content changes, preserving claims, instructions, section order, and images.
- Apply the appropriate humanizer skill to English, Korean, and Japanese prose.
- Do not use em dashes or emoji.
- Keep the README brief, with a centered title, useful badges, and a copyable installation request.
- Publish the project publicly under the MIT License.
Distribute the alignment method as a maintained skill. README and site copy should guide users to install it, rather than preserving a standalone interview prompt. Support native plugin updates where verified and a user-authorized, targeted refresh at alignment-session start elsewhere. Keep method updates separate from personal criteria and never promise universal background updates.
Suggest focused alignment after consequential judgment mismatches, repeated corrections that reveal missing criteria, and when users are unsure of direction. Before long autonomous runs, propose hypothetical scenarios for uncovered trade-offs and stopping boundaries. Fix clear errors without an interview. Make reflection an available habit, without imposing diaries or reminders.
Check the primary CLI at setup and whether it is the current client. Keep its native instruction file canonical, safely linking other compatible entrypoints when needed. Preserve distinct and nested instructions. Record the skill's invocation and update policy in project ALIGNS.md documents.
Offer numbered choices and a brief outline of the steps when the user invokes align without a clear purpose. Accept numbers and natural-language requests. When the purpose is already clear, begin that work without repeating the menu or asking the user to choose again. Keep the detailed procedure in the skill.
User-requested addition: 2026-10-18 (Asia/Seoul). Partial confirmation only. Add path 7 for placing the ALIGNS.md badge in a project's README. Recommend it only after confirming that the badge is absent. Reuse the provided badge, preserve existing README layout and translations, and do not duplicate an existing badge.
User-requested scope update: 2026-10-18 (Asia/Seoul). Partial confirmation only.
Add optional path 8 for collecting and reviewing decision examples, then exporting SFT, eligible DPO pairs, and held-out evaluation data for user-run fine-tuning. Agree on sources, scope, storage and review checkpoints before collecting. Prefer small candidate records at confirmed decision moments and batch review/export. Keep evidence and datasets separate from the current agreement. Distinguish actual, hypothetical and reconstructed examples, confirmed criteria, accepted answers and verified outcomes. Do not infer preference from silence or fabricate human labels.
Default to local storage outside shared repositories. Let the user choose Git tracking and remote upload separately. Do not train models or enable background logging. Skill development does not authorize collecting this user's records. A dataset supports later training; it does not itself change model weights or establish improved performance. Preserve task-group separation for evaluation.
User-requested scope update: 2026-10-18 (Asia/Seoul). Partial confirmation only.
Offer personal defaults across projects as an optional sixth alignment path, keeping existing menu numbers stable. Let users bring personal documents or notes they choose, without requiring a filename or format, separating common criteria from workplace rules and unneeded biographical details. Keep each agreement's scope and confirmation independent. Never publish a user's profile as shared skill content or fixtures.
Support local storage and, only when requested, an existing or cloned personal repository. Keep private agreements outside shared project repositories. A method update or project correction must not silently change personal defaults or enable remote synchronization. Preserve project-only use without recurring setup prompts.
User-requested scope update: 2026-10-18 (Asia/Seoul). Partial confirmation only.
Carry setup answers and menu choices into the next authorized step. Ask to save a concrete item when needed, reusing existing authorization. After completing an alignment item, summarize completion and offer a next choice, excluding completed, declined, or currently deferred topics. Recommend the best eligible next topic with a reason and show all other remaining paths, including those not yet explored. A general review or rehearsal does not complete the other paths. Account for all eight paths and explain exclusions before offering finish alone. Path 5 is navigation; the other paths remain optional and retain their scope requirements. Include a finish option. Use the client's supported structured-question UI when available in the active mode, with numbered text as fallback. Track progress in the conversation, not a new log. Continue already requested work; let the user choose before expanding scope. Honor stopping and single-item-only requests. Use natural-language invitations instead of requiring command syntax. Include a return invitation at most once when closing a session that actually performed self-alignment. Omit it from ordinary project work, installation-only work, skill development, and intermediate item completions. Reading the skill or applying existing criteria alone does not qualify. Honor requests to omit reminders and describe unavailable skills honestly.
Return-invitation policy confirmed: 2026-10-18 (Asia/Seoul). Partial confirmation only.
In Codex, preserve the chance to answer a required choice instead of sending a completion response immediately after dispatch. Wait using supported mechanisms; request acceptance alone does not prove the UI is visible. Provide a question resume link only when the host officially supports it, and do not invent one. Continue from the user's answer without requiring another invocation.
Make align useful alongside specialist skills for development, design, review, and writing. Apply the relevant confirmed personal criteria to their work. Keep a specialist's default style separate from the user's preferences, and reuse decisions already settled in ALIGNS.md. Maintain a separate document of recommended companion skills with sources and reasons to use them together.
Include incorrectly configured goals and unexpected loop stops among the occasions for focused alignment. Compare the requested outcome with the configured objective, stopping conditions, and actual result. Repair a known execution error directly; ask only about unresolved judgment criteria. The method must not imply that it can wake a stopped agent or that a review alone authorizes restarting work or expanding its scope.
Confirmed from conversation and hypothetical rehearsal: 2026-10-18 16:58 (Asia/Seoul). Partial confirmation only.
For interaction changes, prioritize the reported environment and affected user flow. Check whether the user can see the feature, operate it, and reach the next step. Distinguish simulations, tool acceptance, and observed runtime behavior; report unverified environments explicitly. This does not require testing every platform for every change.
Distinguish repository changes, deployment or package updates, and application in existing installations. State the minimum steps the user must take when a separate refresh is needed. Do not claim propagation to environments that have not been checked, or overwrite user settings to make a method update take effect.
When deployment has already been requested and the change is limited to reversible visual effects, deploy using the available successful checks even if the reported environment is inaccessible. Report that environment as unverified and explain how to roll back. Do not claim the original issue is verified fixed there. This default does not extend to data changes or work that is difficult to reverse.
Emphasize how carrying confirmed preferences forward reduces the user's effort in explaining preferences and correcting work. Use accessible benefit-focused copy in the README and landing page, with links to public benchmark evidence. Keep experiment methods and results available for independent review. Distinguish synthetic results from measured human effort and retain the original evidence.
Maintain English, Korean, and Japanese versions, defaulting to the browser's language and allowing manual language selection. Use the dark theme with a black, paper-textured background. Use Pretendard with sufficient font weight, and apply word-break and text-balance treatment across languages, including document examples.
Keep scrolling illustrations and text coordinated on desktop and mobile. Bound hero image proportions on wide screens while using the available space well. Keep the first screen's text readable without scroll-driven typing or focus; apply those text effects after the first section. Keep scroll animation enabled without an animation or theme toggle. Offer reusable project badges and use a GitHub icon for GitHub calls to action.
Support full paginated PR feedback collection and recent-first review. Offer accessible project conversations, including supported Codex and Claude records, as optional evidence. Show sources, scope and estimated retrieval/analysis time before collection; reuse the user's choice and refine estimates as work proceeds.
Use taste invariants during self-alignment: scoped, revisable criteria supported by the user's decisions across situations. Examine exceptions and conflicting evidence. Do not infer immutable personality traits, treat team feedback as personal consent, or promote repetition into an agreement. Keep the maintained method in the skill and confirmed current criteria in ALIGNS.md.
Primary client: Codex. Canonical instruction file: AGENTS.md.
Ask “Help me review this project's ALIGNS.md,” or describe the criteria you want
to revisit in ordinary language. No command is required. A clear request skips the menu.
This development repository discovers its local skill through
.agents/skills/align, linked to skills/align. Method changes are maintained
in this repository's Git history; do not install a second plugin copy here or
automatically pull over local development changes.
Source and user installation guide: https://github.com/hmmhmmhm/aligns.md .
Last aligned: 2026-10-18 12:51 (Asia/Seoul).