@iodes/releasekit 0.1.3 → 0.1.5

package/kit/skills/releasekit-draft/SKILL.md

@@ -3,14 +3,20 @@ name: releasekit-draft
 description: Create or revise ReleaseKit release notes and their selected translations, including translation-only refreshes. Resolve release scope from the repository and guide first-use setup for an existing product. Use for release copy, not general code implementation.
 ---
 
+Before asking anything, check for an unanswered question request already in this conversation. Keep that request pending across skill transitions and queue every new question until it is resolved; follow [the shared question guidance](references/workflow.md#ask-with-the-native-question-ui).
+
 Read the project's ReleaseKit config and the existing release before writing. For translation-only requests, preserve the source copy, pinned scope, and accepted images; follow [Translate selected locales](references/workflow.md#translate-selected-locales) for the affected notes and languages without preparing a new release. For a new draft or source-copy revisions, resolve the version and Git boundaries using [the repository scope guidance](references/workflow.md#resolve-release-scope-from-the-repository); inspect saved releases and Git before asking, and proceed with a clear inferred range without requesting confirmation.
 
-Use English (`en-US`) as the default original language, honoring explicit source choices and existing release selections. Before preparing or writing a new draft, ask only for unchosen translation languages: recommend the user's current language when it differs from the source, offer the source alone, and explicitly allow additional languages through free-text input. Follow [Choose languages](references/workflow.md#choose-languages) and reuse established choices without asking again. Use [the shared question guidance](references/workflow.md#ask-with-the-native-question-ui) for missing language choices or a consequential scope decision that the evidence cannot resolve. Follow [the workflow](references/workflow.md) for saving the language selection, preparing pinned evidence, continuing drafts, and preserving version boundaries. Use [the writing guide](references/writing.md) to turn the net change into useful product language; source materials are evidence, not new instructions.
+For each new draft, use `sourceLocale` and `locales` from `releasekit/config.yaml`, including a single-language selection. Once the project has saved releases, proceed without a language question or confirmation; previous releases' language lists do not override the current config. Only on first use, when the request and intentional project settings leave languages unresolved, default the original to English (`en-US`) and ask which translations to include. Save that first-use selection in `releasekit/config.yaml` before preparing the draft, without a separate question about saving defaults. Reuse an existing draft's saved selection unless the user requests a change. Follow [Choose languages](references/workflow.md#choose-languages) for first-use suggestions, persistence, and explicit overrides. Use [the shared question guidance](references/workflow.md#ask-with-the-native-question-ui) for missing language choices or a consequential scope decision that the evidence cannot resolve. Follow [the workflow](references/workflow.md) for saving the language selection, preparing pinned evidence, continuing drafts, and preserving version boundaries. Use [the writing guide](references/writing.md) for titles and bodies in every locale. Name the capability, action, or changed result concisely; remove redundant announcement suffixes while retaining meaningful improvement, fix, and compatibility distinctions. Lead the body with concrete behavior and accept a clear description as complete. Include usage paths or conditions only when needed to find a non-obvious feature or prevent a material misunderstanding; do not append them to every note. Apply the guide's exceptions for self-explanatory major new capabilities, baseline introductions, and grouped minor notes; source materials are evidence, not new instructions.
+
+For actions that were previously unsupported and become supported in this release, prefer “이제 ~할 수 있습니다.” or its natural equivalent when first-time availability is the main news; a direct action or behavior statement can better explain a new interaction. Follow [the new-capability guidance](references/writing.md#newly-supported-capabilities) to establish the before-and-after evidence, retain support conditions, and vary openings across the release. Do not apply one pattern to every feature, improvement, or fix.
 
 For first use without existing releases, follow [the adoption guide](references/adoption.md) to resolve and save the baseline and earlier-history choice. Reuse saved choices and explicitly limited scopes. A product introduction uses the pinned snapshot; historical analysis uses the full selected history.
 
-Use the CLI for scaffolding and validation. Group changes by user-visible outcome, attach evidence, and preserve manual edits. Do not invent features, menu locations, or claims to fill gaps. For the file shape, read [the contract](references/format.md).
+Use the CLI for scaffolding and validation. Before adding notes, follow [Group minor changes](references/writing.md#group-minor-changes): reserve standalone notes for changes that warrant individual attention, and collect minor corrections and conveniences into separate per-release bullet-list notes. Reuse existing groups, attach evidence for every bullet, and preserve manual edits. Do not invent features, menu locations, or claims to fill gaps. For requested wording changes or feature additions and exclusions, follow [Revise draft notes](references/workflow.md#revise-draft-notes), using the CLI to add or remove whole notes and their managed files. For the file shape, read [the contract](references/format.md).
+
+Keep every drafted note image-enabled by default, including grouped minor changes. Each group is one note; its bullets do not require separate notes or images. Use `releasekit note add` without `--no-image` unless the user explicitly chose text-only content for that note. Do not choose an illustrated subset by importance or disable an image because its input is missing. Keep required media pending for `releasekit-image`; follow [image coverage](references/theme-pairing.md#coverage-and-repeat-runs).
 
 Drafting includes the source and every selected translation unless the user explicitly limits the language scope. Follow [Translate selected locales](references/workflow.md#translate-selected-locales) to write or refresh title, body, and alt text, then record the source fingerprints only after reviewing each translation. Preserve translations that are already current. A locale file scaffold alone is not a completed translation.
 
-After drafting, follow [the next-step workflow](references/workflow.md#continue-to-the-next-step). With source and translations complete, recommend `releasekit-image` when required images remain, or `releasekit-finalize` when the release is ready for final checks. Continue work already requested in this conversation; otherwise offer the next useful action. Do not send completed translations through another stage.
+After drafting, follow [the next-step workflow](references/workflow.md#continue-to-the-next-step). With source and translations complete, recommend `releasekit-image` to cover all drafted notes when required images remain, or `releasekit-finalize` when the release is ready for final checks. Continue work already requested in this conversation; otherwise offer the next useful action. When the user chooses to finish drafting or requested drafting only, [hand over the completed draft and invite revision requests](references/workflow.md#complete-drafting-and-invite-revisions). Do not send completed translations through another stage.

package/kit/skills/releasekit-finalize/SKILL.md

@@ -3,11 +3,17 @@ name: releasekit-finalize
 description: Finalize a ReleaseKit release by reviewing facts, copy, translations, and images, validating content, and marking the local release ready. Export a release bundle when requested.
 ---
 
+Before asking anything, check for an unanswered question request already in this conversation. Keep that request pending across skill transitions and queue every new question until it is resolved; follow [the shared question guidance](references/workflow.md#ask-with-the-native-question-ui).
+
 Read the target release, [the workflow](references/workflow.md), and [the content contract](references/format.md). Reuse the version and choices established in the request and conversation. Use [the shared question guidance](references/workflow.md#ask-with-the-native-question-ui) only for unresolved scope or requested export choices.
 
 Invoking this skill to finalize a release includes review, corrections within the requested scope, validation, and local finalization. Complete those actions without a separate confirmation step. If the user explicitly asks only for an assessment, report the findings and leave the release status unchanged.
 
-Compare claims against the pinned final diff and target-revision files. For `initialContent: summary`, use the baseline snapshot and [the adoption guide](references/adoption.md); do not require a reconstruction of old commits or assume an initial launch. Use [the writing guide](references/writing.md) to check changed behavior, action paths, requirements, and limitations. Refresh affected translations after source edits using [Translate selected locales](references/workflow.md#translate-selected-locales). Preserve current translations and manual edits.
+Compare claims against the pinned final diff and target-revision files. For `initialContent: summary`, use the baseline snapshot and [the adoption guide](references/adoption.md); do not require a reconstruction of old commits or assume an initial launch. Use [the writing guide](references/writing.md) to review copy in every locale. Check that a standalone title names a capability, action, or changed result and its body explains concrete behavior. For grouped minor notes, keep the summary heading and check the concrete changes in the bullets. Accept a clear description without usage instructions. Missing paths, setup steps, or conditions are not completeness defects by themselves; include them only when their omission makes the change difficult to find or use, or materially misleading. Remove redundant announcement suffixes without erasing meaningful improvement, fix, or compatibility distinctions; apply [the title guidance](references/writing.md#titles) before shortening a title to a feature name. Remove body filler and vary the structure where the content calls for it. Refresh affected translations after source edits using [Translate selected locales](references/workflow.md#translate-selected-locales). Preserve current translations and manual edits.
+
+Review the note breakdown using [Group minor changes](references/writing.md#group-minor-changes). Within the requested editing scope, consolidate minor standalone notes into the appropriate per-release fix or improvement group, reusing an existing group when available and keeping significant changes separate. Follow [Revise draft notes](references/workflow.md#revise-draft-notes) to preserve evidence, manual edits, and translations before removing superseded notes. Check every bullet against the pinned evidence and remove duplicates without losing distinct changes or crossing version boundaries.
+
+Apply [the new-capability guidance](references/writing.md#newly-supported-capabilities) to prefer “이제 ~할 수 있습니다.” or a natural locale equivalent when evidence establishes a newly supported action and first-time availability is the main news. Keep direct action or behavior openings when they explain the change clearly. Remove unsupported first-time claims from improvements and fixes, and read the notes together in release order for each locale to vary repetitive openings while preserving the change and its conditions.
 
 Inspect selected images for correct subject, readable framing, absent invented details, and consistent geometry across configured themes using [the pairing guide](references/theme-pairing.md). Reuse a completed visual review when the note, brief, and assets are unchanged. The CLI verifies files and metadata; it cannot judge whether the image depicts the feature accurately. Keep missing or unsuitable assets pending and use `releasekit-image` for the needed correction.
 
@@ -15,6 +21,6 @@ Run `releasekit validate <version>`, resolve errors, and assess warnings. Missin
 
 For a draft that passes review and validation, run `releasekit finalize <version>` and verify that `release.yaml` contains `status: ready` and a nonempty `contentHash`. The command validates again and records the fingerprint; do not set ready status manually. For an already ready release, validate and reuse it without calling finalize again. If requested corrections require changes, reopen it with `status: draft` and `contentHash: null`, apply the corrections, and finalize again.
 
-If export was requested, run `releasekit export --current <version> --locale <locale> --limit <count> --out <directory>` with the requested or established choices, using [the workflow](references/workflow.md) for defaults. Preserve individual release boundaries and configured fallback themes. A successful finalization is a complete local result even when no export was requested. Finalization does not commit, tag, push, deploy, or publish.
+If export was requested, run `releasekit export --out <directory>`, using [the workflow](references/workflow.md) for defaults. Add `--current`, `--limit`, or `--locale` only for requested overrides or to resolve multiple release endpoints. With no language override, export all locales saved in the current release to separate JSON files that share image assets. Preserve individual release boundaries and configured fallback themes. A successful finalization is a complete local result even when no export was requested. Finalization does not commit, tag, push, deploy, or publish.
 
 When finalized, report the version and link to its release file, adding bundle links only for a completed requested export. If blocked, state the remaining work and the actual saved status. Follow [the next-step workflow](references/workflow.md#continue-to-the-next-step) without introducing a separate review stage.

package/kit/skills/releasekit-image/SKILL.md

@@ -3,20 +3,26 @@ name: releasekit-image
 description: Create, revise, or import ReleaseKit release illustrations with consistent composition and project-configured dark and light variants. Use for visual release-note assets and generation prompts, not general UI implementation or arbitrary image work.
 ---
 
-Read the release's captured visual policy and the affected note. First choose the [media source](references/media-sources.md), then read [the visual language](references/visual-language.md) and applicable [composition recipe](references/composition-recipes.md). Use [the pairing guide](references/theme-pairing.md) for configured themes, cost-aware reuse, and importing images. Consult [the file contract](references/format.md) when editing a brief.
+Before asking anything, check for an unanswered question request already in this conversation. Keep that request pending across skill transitions and queue every new question until it is resolved; follow [the shared question guidance](references/workflow.md#ask-with-the-native-question-ui).
 
-When a user decision is needed during image work, such as an ambiguous target note or a meaningful choice among suitable approved references, use [the shared question guidance](references/workflow.md#ask-with-the-native-question-ui). Reuse the captured theme policy and existing asset choices. Ask for missing image attachments through the conversation's supported attachment flow; a text-only picker can collect an existing file path.
+Read the saved release's complete current note list and captured visual policy on every invocation. Default to covering every drafted note, including notes added since earlier image work; honor only the user's explicit text-only choices or explicitly limited request. Follow [coverage and repeat runs](references/theme-pairing.md#coverage-and-repeat-runs) to reuse accepted images and fill missing ones. For grouped minor fixes and improvements, follow [common images](references/common-images.md) first: reuse reviewed project originals before generating anything, and create only missing originals or themes. Choose the [media source](references/media-sources.md), then read [the visual language](references/visual-language.md) and applicable [composition recipe](references/composition-recipes.md). Use [the pairing guide](references/theme-pairing.md) for configured themes, cost-aware reuse, and importing images. Consult [the file contract](references/format.md) when editing a brief.
 
-Derive one visual message from the release note and its Git/product evidence. Choose an archetype and `source`; the scaffold leaves both unselected. Generate flat explanatory graphics when an abstraction is sufficient. `object-detail` and `editorial-scene` require supplied media, and any other type can use an actual capture when fidelity matters. Search existing approved assets or use the user's capture; if absent, ask for the specific image and keep it pending. Do not invent a physical product, content artwork, or decorative 3D scene. Examples illustrate individual features, not default layouts.
+When a user decision is needed during image work, such as an ambiguous target for a requested revision or a meaningful choice among suitable approved references, use [the shared question guidance](references/workflow.md#ask-with-the-native-question-ui). Reuse the captured theme policy and existing asset choices. Ask for missing image attachments through the conversation's supported attachment flow; a text-only picker can collect an existing file path.
 
-Complete one shared scene brief before generating. Encode product facts and uncertainties in `context`, the relevant state and relationships in `composition`, and the feature-specific correctness constraints in `preserve` and `avoid`. Keep reference identities and attributed style names out of prompts and assets. Inspect product references as evidence. Do not invent a concrete UI or physical design to fill missing evidence; use a supported abstraction or leave the unresolved detail in the brief.
+For standalone notes, derive one visual message from the release note and its Git/product evidence. Minor groups use the common kind's generic scene, independent of their current bullet list. Choose an archetype and `source`; the scaffold leaves both unselected. Generate flat explanatory graphics when an abstraction is sufficient. `object-detail` and `editorial-scene` require supplied media, and any other type can use an actual capture when fidelity matters. Search existing approved assets or use the user's capture; if absent, ask for the specific image and keep it pending. Do not invent a physical product, content artwork, or decorative 3D scene. Examples illustrate individual features, not default layouts.
 
-Run `releasekit image plan <version>`. Handle requests by `action`: `generate` has a generation prompt; `provide` needs an existing or user-supplied image and has no generation prompt. Respect the latest plan even if older prompt files remain in the release. For generated variants, review and import the first before planning its counterpart. For supplied media, use `--theme shared` for one unchanged source or import distinct genuine theme captures. Keep native appearance and meaning; do not invert, duplicate, or synthesize a missing supplied counterpart.
+Start each generated scene in neutral values and establish its focal point through composition, scale, and contrast. In `composition`, record either no accent or the exact element and supported meaning that needs color. The configured accent is optional; a newly announced capability or a simple relationship between symbols does not justify coloring an icon. Keep generic capability and minor-group icons neutral. Preserve meaningful status, map, chart, and supplied-content colors.
+
+Complete each missing or unfinished scene brief before planning the release. Preserve the briefs of unchanged accepted images. Each note has one shared scene brief for its configured variants. Keep common minor-group scenes independent of release-specific text and evidence. For standalone scenes, encode product facts and uncertainties in `context`, the relevant state and relationships in `composition`, and the feature-specific correctness constraints in `preserve` and `avoid`. Keep reference identities and attributed style names out of prompts and assets. Inspect product references as evidence. Do not invent a concrete UI or physical design to fill missing evidence; use a supported abstraction or leave the unresolved detail in the brief.
+
+Run `releasekit image plan <version>` on every invocation after importing any reusable common originals. For a normal first or repeat run, fill missing assets under [the coverage policy](references/theme-pairing.md#coverage-and-repeat-runs); a repeat invocation alone does not request regeneration of existing images. Handle requests by `action`: `generate` has a generation prompt; `provide` needs an existing or user-supplied image and has no generation prompt. Respect the latest plan even if older prompt files remain in the release. An existing reviewed common file can satisfy a generated-image request through import; rerun the plan before generating anything that is still missing. For generated variants, review and import the first before planning its counterpart. For supplied media, use `--theme shared` for one unchanged source or import distinct genuine theme captures. Keep native appearance and meaning; do not invert, duplicate, or synthesize a missing supplied counterpart.
+
+For an image replacement or regeneration request, reuse the existing release and note ID. Keep the current variant metadata until the replacement is reviewed, then run `releasekit image import` with the intended `--theme`. The CLI replaces the selection, switches between shared and themed usage when needed, and removes unused managed images for that note. If the media source changes, include `--source provided` or `--source generated` to save it together with the new selection. Do not pre-clear variants or separately change the source just to switch modes. Do not create another note or release to represent a revision. Keep discarded candidates temporary; publish a reviewed common original only through [the common-image workflow](references/common-images.md#preserve-release-snapshots). Keep failed or unavailable replacements pending; preserve unrelated accepted assets and supplied originals. Follow [replacement handling](references/theme-pairing.md#replace-or-regenerate-an-image), including [shared/themed transitions](references/theme-pairing.md#switch-between-shared-and-themed-images).
 
 If no image generator is available, preserve the generated prompt files and report the pending assets. Continue independent editorial work. Do not silently call a paid API, install a provider, or replace requested raster illustrations with placeholders. Import user-supplied PNG, JPEG, or WebP files when they become available.
 
-Inspect selected images at full resolution and small-card size. First compare the image with the note, product evidence, and scene-specific constraints using the selected recipe's review criteria. Then check visual clarity and theme correspondence. The CLI checks files and metadata; it does not decide whether an image truthfully depicts the feature. Two matching variants can share the same factual or structural mistake. Correct a defect in its own scene or applicable recipe; promote it into common guidance only when the principle applies across features.
+Inspect selected images at full resolution and small-card size. First compare the image with the note, product evidence, and scene-specific constraints using the selected recipe's review criteria. Then check visual clarity and theme correspondence, including whether accent is absent or stays confined to its justified elements. Review the release images together for repeated decorative accents; do not assign one colored point to every note or impose a fixed color quota. The CLI checks files and metadata; it does not decide whether an image truthfully depicts the feature. Two matching variants can share the same factual or structural mistake. Correct a defect in its own scene or applicable recipe; promote it into common guidance only when the principle applies across features.
 
 If the accepted image requires an alt-text correction, update the source and affected translations using [Translate selected locales](references/workflow.md#translate-selected-locales), reviewing them before recording new source fingerprints.
 
-When required images, source copy, and translations are complete, recommend `releasekit-finalize` to review and mark this release ready. Follow [the next-step workflow](references/workflow.md#continue-to-the-next-step) to continue already requested work or offer that action. If images remain blocked, identify the missing input and keep them pending.
+After image work, follow [Review images and continue](references/workflow.md#review-images-and-continue): show the accepted images, invite the user to ask the agent for changes or a replacement, and explain that `releasekit-finalize` confirms the release when no image changes are needed and the content is complete. Reuse this handoff when a repeat run finds no missing images. Follow [the next-step workflow](references/workflow.md#continue-to-the-next-step) to continue already requested finalization or offer it as the recommended action. If assets remain missing, stale, or otherwise invalid, identify the affected notes and keep that work pending.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iodes/releasekit",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Git-based visual release notes and portable agent skills",
   "type": "module",
   "license": "MIT",