Agent Instructions

Codex is the primary client for this repository. Keep AGENTS.md as the canonical project instruction file. Read ALIGNS.md before making decisions.

Required skills

• align: required for explicit alignment requests and focused alignment reviews. The local source is skills/align/SKILL.md; discovery uses .agents/skills/align.
• humanizer: required when writing or editing English prose.
• humanizer-ko: required when writing or editing Korean prose.
• japanese-humanizer: required for the final prose pass when writing or editing Japanese text, after translation or factual work is complete.

Check availability for the task using the procedure below. Skill names may be namespaced by the host. Recommendations in docs/recommended-skills.md are optional.

README language consistency

README.md is the English source of truth for all translations in docs/translated-readme/. When any version changes, review every language version and update all affected translations in the same change.

Resolve substantive changes in English first, then synchronize translations. Keep claims, numbers, instructions, section order, and images consistent. Adapt wording naturally and preserve working relative links. Language-only wording fixes do not require unnecessary edits to other versions.

Apply the appropriate humanizer skill when editing each language.

Ongoing personal alignment

At the first relevant task in a session, check the project's required skills against the current client's available-skill list or equivalent discovery evidence. Check again only after a client, workspace, or installation change, or a load failure. A file or symlink alone does not prove discovery. Load and follow align for explicit alignment requests and the focused reviews below; load other required skills when their declared task scope applies. Routine work only needs the existing agreement, not a new alignment interview.

If a required skill is missing, distinguish discovery failure from a missing source or runtime dependency. Report the affected skill once. A readable trusted local source can supply the method if its needed resources are usable; disclose this as manual loading, not native invocation. Otherwise continue independent work and identify the blocked step. Repair only within authorized scope, preserving the chosen installation route; do not silently add a duplicate, install globally, or claim a required skill was used when it was not.

If user-level instructions explicitly link a personal ALIGNS.md, apply its relevant confirmed defaults alongside this project's criteria and agreed exceptions. Keep private content out of shared files. Do not search for unlinked profiles or promote project feedback to global rules. Use align's personal-scope procedure when the user requests personal setup or a consequential scope conflict remains unresolved.

Read ALIGNS.md at the start of work and apply its current criteria to scope, important decisions, and result review. At an alignment session, follow its recorded method-update policy once before loading the skill; preserve pinned versions and use the installed method if updating is unavailable. Do not poll for updates on every task. Use the installed align skill for focused clarification when important judgment diverges, repeated corrections suggest a missing criterion, the user is unsure of the next direction, or a loop or goal exposes unresolved scope, completion, or stopping criteria. Compare the request, configured objective, actual state, and results. Fix known errors directly. Before a long run with untested boundaries, offer hypothetical rehearsal without executing scenarios or launching the run. A review does not authorize a restart, budget increase, or override of a user stop. The skill acts during active turns; it cannot wake a stopped agent.

When earlier feedback could clarify criteria, offer selected PR or project conversation review with recent/full scope and estimated time. Reuse a clear choice; do not scan personal logs or store inferred preferences automatically.

For brief requests, use available project context and confirmed criteria first. Ask about missing information only when it materially changes the result or scope; group related questions. Proceed with minor reversible choices and already delegated judgments within authorized scope. Repeated context-related misunderstandings can warrant a focused align review of when to ask. Do not infer a lasting preference from brevity or from a task-specific answer.

When using specialist skills, carry relevant confirmed ALIGNS.md criteria into the task brief and result review. Keep skill defaults separate from user preferences. Resolve conflicts already settled by the agreement without asking again; clarify only consequential unresolved choices. Follow the applicable instruction hierarchy and permissions, and report exceptions to specialist checks honestly instead of rewriting criteria or claiming an unearned pass.

During an alignment session, carry each answer into the next authorized step. Track completed, declined, deferred, and pending items in conversation context. After completing an item, provide a next-choice step: summarize the result, exclude completed or declined topics, recommend an eligible remaining topic, and include a finish choice. Prefer an available structured-question tool allowed in the active mode; otherwise use numbered text. If nothing remains, recommend finishing without inventing gaps. Continue already requested work without another gate, but wait before new scope. Honor stop and single-item-only requests, and do not append alignment menus to routine work.

For Codex choice questions, an accepted request is not an answer or proof of UI display. Do not send a final/completion response while a required async answer is pending. Continue independent authorized work or use supported interruptible waits of at most 60 seconds each; do not treat timeout as consent or keep waiting after cancellation or a superseding request. Follow align's session-flow guidance for hosts without a wait mechanism. Include “Answer questions” / “질문에 대답하기” only when an official resume URL is supplied or documented; never invent a link. Resume the selected step after the answer, without another invocation request.

Account for all eight paths before choosing follow-ups. Keep unexplored paths available; an unchosen history source or missing personal file does not exclude paths 3 or 6. Offer path 2 conditionally if the user has a mismatch example. Path 7 adds a README badge: offer it only after inspecting the target README and confirming an ALIGNS.md badge is absent. Exclude existing badges and personal-only sessions without a project; a missing or unreadable README is a prerequisite gap. Path 8 optionally sets up personal training-data collection or export. Keep it available without enabling collection; follow the training-data reference only when selected or already authorized. Declining it does not limit other paths. Path 5 is navigation. Show all remaining paths with one recommendation and a finish choice; use numbered text if the question UI cannot fit them all. Before offering only finish, briefly account for completed, declined, deferred, out-of-scope, or blocked paths. Never treat a general review or rehearsal as completion of the rest.

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.

Reuse existing answers. Fix clear execution errors directly. Ask only about consequential uncertainty, continue independent work, and do not reopen a declined or resolved review without new evidence. A new method version does not change the user's agreement. Store lasting criteria only on explicit direction or confirmation; never rewrite them to justify a mistake. Preserve Last aligned unless the user confirms the whole document. Keep current criteria in ALIGNS.md and use Git history when available. Do not initialize Git or create another log.

If align remains unavailable, apply ALIGNS.md to routine work and give the specific discovery or installation repair needed, using the trusted source https://github.com/hmmhmmhm/aligns.md. Do not report a method-based alignment review as complete without loading the method. Follow the applicable instruction hierarchy and permissions.