CheshireMew/ip-studio

IP Studio

Turn scattered identity clues or existing character art into a reusable, style-consistent character that can be used across sessions. Then, use that same identity to generate social media profiles, article visuals, and Codex v2 desktop pets.

Character creation delivers: a master reference image, a complete character profile, and documentation. Derivative visuals deliver: final images (after consistency and content checks) plus a traceable record. The Codex pet delivers: nine animation states, sixteen gaze directions, full QA evidence, and a ready-to-install pet directory.

The user only makes decisions that change the identity, communication direction, or an existing installation. The Agent handles structure completion, content extraction, image generation, image review, retries, saving, assembly, and validation.

First Decision

Based on the independent result the user wants, choose the primary path:

• Create or Modify Character Identity: Create from scratch, import an existing design, or modify a locked character. Go to the "Character Identity Path".
• Create Character Derivative Visuals: Avatars, profile banners, profile cards, article covers, explainer graphics, or article illustrations. Go to the "Derivative Visuals Path". If a locked character kit exists, consume it directly. If only approved images exist, first auto-import and lock the character. If no character exists, complete the Character Identity path first, then return to the derivative request.
• Create a Codex Pet: Make, check, package, or install a locked character as a Codex v2 desktop pet. Go to the "Codex Pet Path". If a character kit exists, consume it directly. If only approved images exist, first auto-import and lock the character. If no character exists, complete the Character Identity path first, then return to the pet request.

If a single request asks for a character, derivative images, and a pet simultaneously: lock the character first, then complete each result separately. The pet can only begin after the current character version is locked.

General personal branding, non-IP cover images, explainers, illustrations, photorealistic digital avatars, general animations (non-Codex pet), Live2D, video, standalone Windows pets, and other pet platforms stop here. Explain the adjacent capability boundaries.

If the user only types $ip-studio, treat it as a "create from scratch" request.

Information and Action Boundaries

Use information in this order:

1. Current request and the user's explicit choices.
2. Identity, purpose, and aesthetic clues that have already appeared in the current conversation.
3. Images, documents, links, and character folders provided or explicitly pointed to by the user.

If the character material is sufficient to determine the purpose, audience, character form, desired impression, and final style, proceed directly. If information that would change the character's direction is missing, compile three complete direction cards from the feasible solutions and let the user choose or combine them. Do not issue a questionnaire.

If the user explicitly delegates the choice to the Agent, adopt the direction card most suitable for the purpose and explain the selection.

For derivative visuals: first read the current content, the user-specified character kit, and the master reference image. Then read any logos, interfaces, data, or visual materials provided by the user. Only escalate a specific trade-off to the user if facts, name, brand direction, or core narrative cannot be determined from the materials, AND different answers would change the final image. For platform cropping and safe zones: if the current specification is known but the user hasn't provided a screenshot or dimensions, query the official platform documentation.

For the pet path: first read the current character profile and master reference image. Then read any additional visual references explicitly provided by the user. If the character name, pet name, style, and action posture can be stably inferred from the character kit, proceed. Only escalate a single trade-off to the user if one fixed feature cannot simultaneously maintain the character identity and the 192×208 pet geometry.

Do not proactively use the internet for brand research unless the user explicitly asks to supplement public brand clues for a request that only has a brand name and no character direction.

Calling this Skill grants authorization to: view the images provided by the user in the current task, use existing image generation and image reading capabilities, and create character kits, derivative visuals, and pet run directories in the writable workspace.

When the user asks to "create a usable Codex pet", writing to the local Codex pet directory is the final step of that result. If the same pet identifier is already occupied by different content, save the existing directory first and request a replacement decision. Other installation, upload, sending, and publishing actions are only performed when the user separately requests them.

This workflow does not delete existing character versions, official derivative images, pet run records, or previously saved old installations.

The reply language follows the user. Internal files use fixed English key names; the user does not need to read or edit these key names.

Character Identity Path

First, distinguish between creating from scratch, importing an existing design, and modifying a locked character. When importing, distinguish between features the user intentionally wants to keep and incidental details from the current image. When modifying, read character-profile.json and the single master reference image registered within it. Changing a fixed feature generates a new version.

After entering this path, read references/character-system.md. It handles: character direction, chibi diagnosis, image generation inputs, visual checks, color matching, and complex part processing. After completing each specialized action, return to the corresponding step in this section.

1. Build a Draft Profile

Run python scripts/character_kit.py schema to read the current profile contract. When a file draft is needed, run:

python scripts/character_kit.py draft <draft-profile-path> --character-id <slug> --display-name <name> --language <language>

First, write the known information into the draft. When the chibi direction is not yet decided, some fields may be left empty temporarily. Before generating the final image, the profile must be fully completed based on the user's choice or an already approved image, then rebuilt completely.

The profile records: body shape and proportions, head and face parts, torso and limbs, appendages (tail, wings, etc.), the exact location and area relationships for each color, pattern boundaries, material regions, clothing layers and connections, emblem geometry and attachment method, front/side/back structure, drawing style, and consistency boundaries.

The Agent proactively decides on side views, back views, seams, and material details that will not change the character's direction, marking them as agent_inferred in provenance.decisions. Only escalate disagreements to the user if they would change the silhouette, face, primary colors, emblem, or character meaning. Before the final image generation, run:

python scripts/character_kit.py prompt <draft-profile-path> --purpose master

This command first validates the profile's completeness, then generates a full identity prompt from the profile. Use the prompt output by this command for the subsequent image generation; do not write a separate identity description. Posture, action, scene, aspect ratio, and camera angle are passed only via the --task argument of that command.

2. Design with Chibi Diagnosis

From the same draft profile, independently generate three diagnostic sketches. Each sketch must be: single character, clear lines, sparse details, approximately 3.5 heads tall, front-facing neutral posture, clean background. The three sketches should form a real difference in silhouette, character form, or core symbol—not just a color change.

After generation, view each sketch. A diagnostic sketch should still present the main silhouette and one primary memory point in thumbnail view, with no missing limbs, structural breaks, irrelevant text, or design clutter.

At this stage, the profile is still a tentative design: automatically eliminate a diagnostic sketch only if it has a technical error or violates a feature the user has already confirmed. If a sketch has a sound structure and is recognizable but changes a detail not yet confirmed, keep it as a new branch and explain the change to the user. If a sketch truly fails, replace it once from the original profile; do not continue editing from a failed image.

Present the three passing sketches, along with a brief summary of their differences, to the user for selection or combination.

If an existing design is already approved by the user and the user only wants to build a profile, skip this step. When modifying a locked character, only return to this step if the silhouette, face, core colors, or emblem are being redesigned.

3. Generate the Official Master Reference Image

Write the user's choice back to the draft profile. Complete all structures required by the reference, item by item. Then use the script to generate the full prompt for the official candidate. The pass criterion: another Agent should be able to draw the front, side, and back views of the same character from the profile without needing to guess key identity details. Chibi diagnostics provide evidence for this choice only; they do not enter the character kit or become a reference for subsequent image generation.

The official master reference image should be: single character, full body, front-facing or slightly three-quarter view, neutral posture, clean background, no text, labels, or collages; all fixed features must be directly visible.

First, compare the image against the profile. Then, compare technical completeness. Auto-correct obvious generation errors; correct a maximum of two times during the official stage.

If the base colors, silhouette, face, or emblem change, create a new branch from the current profile and redraw. Only rendering flaws can be fixed locally; after fixing, re-check all fixed features.

If the same complex part is incorrect two consecutive times, follow the part branch in the reference to first determine its geometry, proportions, material, connections, visibility from each angle, and movement method. Write the confirmed structure back to the profile. Then, regenerate the full prompt and the entire character image using the script.

Show the passing official candidate to the user and request final approval. If the user has explicitly authorized the Agent to make the final decision in the current request, the Agent may choose the image that best matches the profile.

4. Verify Reusability

After the final image is approved, first cross-reference the structures actually established in the image with the profile: write approved design changes back to the corresponding fields. Do not overwrite confirmed settings with incidental generation details. Then, run:

python scripts/character_kit.py prompt <draft-profile-path> --purpose consistency --reference <approved-master-image> --task <different-pose-expression-and-simple-background>

Pass the prompt and master_reference output by the command together to the image generation capability. Generate a single consistency test image with a different pose, different expression, and simple background. The test image must retain: body shape, face, color placement, clothing connections, materials, and emblem. It is used only for this check; it is not written into the character kit or used as a subsequent reference.

If the test fails, first determine whether the profile description is missing or the master reference image is unstable. Then, update the corresponding producer and retry; correct a maximum of two times. If it is still necessary to abandon an already approved feature, escalate this single trade-off to the user for a decision.

5. Lock the Character Kit Losslessly

After the character passes the consistency check, use ip-studio-output/<character-slug>/ in the current writable workspace. Pass the draft profile and the official master image to the script:

python scripts/character_kit.py finalize <kit-folder> --profile <draft-profile-path> --master <master-image-path>
python scripts/character_kit.py check <kit-folder>

finalize validates the profile and image before writing. If a character already exists, it increments the version, saves the old profile and documentation into history/rNNN/, and preserves the old master image. If the command fails, read the error, correct the production input, and retry. Do not manually write version numbers, checksums, or documentation files that the script should have generated.

After the script succeeds, re-read character-profile.json and character-guide.md. Actually open the image pointed to by assets.master_reference. Run one more python scripts/character_kit.py prompt <kit-folder> --purpose scene --task <simple-reuse-task> to confirm that downstream processes can read the current profile and master image.

The character is considered locked only when the profile, documentation, images, and derived prompts are consistent AND the check passes.

Derivative Visuals Path

This path only consumes a locked character identity. Read references/visual-production.md. It handles: brief creation, composition, image generation, checking, and archiving for avatars, profile banners, profile cards, article covers, explainer graphics, and article illustrations. After completing each specialized action, return to this section.

1. Determine the Current Result(s)

Break the request into one or more clearly defined results:

• avatar: a 1:1 image compatible with both circular and square cropping. When the user says "avatar set", generate a simplified badge version and a rich portrait version separately.
• profile-banner: if no platform is specified, use a 3:1 generic profile banner. If a platform is specified, compose the image according to that platform's actual crop and overlay regions.
• profile-card: default 4:5 mobile profile card.
• cover: fixed 5:2 article cover.
• explainer: based on content, choose the image ratio from 4:5, 3:4, or 16:9.
• article-illustration: fixed 16:9 article illustration.

When the user says "profile set", default to generating an avatar and a profile banner. Only add a profile card if explicitly requested.

Each result has its own brief, generation, check, and archive process, sharing the same character version. One result's candidate images are not reused as derivatives for another result.

2. Create a Visual Brief

First run python scripts/visual_kit.py schema. Then, the Agent creates and fills out a draft brief:

python scripts/visual_kit.py draft <brief-path> --kind <kind> --visual-id <slug> --language <language>

Based on the true source of the content, determine: the core object, the knowledge gap, the mechanism or change, the conclusion after viewing, the brand role, the single primary structure, the character's action, the title, the label, and the color palette. Follow the current contract in references/visual-production.md for covers, explainer graphics, and article illustrations.

The character must perform a causal action in the content visual: personally receive, move, connect, split, select, block, transform, or bear the core object, producing a visible result. Avatars target thumbnail recognition. Profile banners and profile cards involve the character in real interaction with core symbols. The user does not need to view or edit the brief.

3. Generate and Auto-Check

Run:

python scripts/visual_kit.py prompt <kit-folder> --brief <brief-path>

Pass the prompt output by the command, along with the ordered image_references, to the image generation capability. These come from the current character profile, the single master reference image, the visual brief, and any other images provided by the user. Do not write a second character identity or content prompt.

After generation, actually open the image. Check, in the order specified by the reference: character consistency, content facts, the character's causal role in the action, the unique information structure, mobile hierarchy, readability of text and logos, and technical completeness.

If the check fails, correct the earliest erroneous judgment in the brief, then regenerate from the original character profile and content materials. Auto-correct a maximum of two times per official result. If it is still necessary to change a fact, narrative focus, or fixed character feature, escalate only that single trade-off to the user.

4. Archive the Final Image

After the user approves, or if the user has authorized the Agent to make the final decision, run:

python scripts/visual_kit.py finalize <kit-folder> --brief <brief-path> --image <approved-image>
python scripts/visual_kit.py check <visual-folder> --kit <kit-folder>

The official result is written to <kit-folder>/derivatives/<kind>/<visual-id>/. This directory stores: the final image, the visual brief, a snapshot of the character profile at that time, the complete image generation input, a copy of the input materials, and verification records. The current character profile, master reference image, and historical versions remain unchanged. Candidate images, auto-retry attempts, and consistency check materials are kept only in the task's temporary directory.

After the script succeeds, re-read visual-record.json. Actually open the final image registered within it. Confirm that the character version, master reference image, visual brief, image generation input, and the final image's checksum are all readable.

Stop once the current request is satisfied. Do not automatically scale it into other dimensions, meme packs, or media.

Codex Pet Path

This path only consumes a locked character identity. After entering, read references/pet-production.md. It handles: the Codex v2 spritesheet contract, nine animation states, sixteen gaze directions, line-by-line image generation, deterministic assembly, blind review, dynamic preview, final directory creation, and installation. Character identity, version updates, and other derivative visuals remain the responsibility of their respective paths.

At the start, establish a four-step visible progress indicator. Only advance after actual files or decisions exist:

1. Prepare the character and the pet run directory.
2. Generate the main image at the pet's dimensions.
3. Generate and check all actions and gaze directions.
4. Assemble, validate, and install the pet.

1. Create a Run Directory Linked to the Character Kit

First, call the workspace dependency loader. Use the Python absolute path it returns for every command in this path. Run:

"<workspace-python>" -B scripts/pet_kit.py schema
"<workspace-python>" -B scripts/pet_kit.py prepare <kit-folder>
"<workspace-python>" -B scripts/pet_kit.py check <run-folder> --stage prepared

prepare generates a full identity description at the pet's dimensions from the current character-profile.json. It copies a verifiable snapshot of the character profile, documentation, and the single master reference image. It generates the formal tasks for: the base image, the nine action states, four directional anchors, and two directional rows. The default location for a new run is <kit-folder>/derivatives/codex-pet/<pet-id>/runs/rNNN/. Old runs are not overwritten.

Independent accessories (e.g., a tail lantern) remain independent and swappable, while ensuring that the force path between fix points, collars, straps, rings, and accessories is continuously visible within the 192×208 canvas.

2. Generate the Pet's Main Image and Standard Actions

Before generating any images, fully load the current environment's $imagegen Skill. Run pet_kit.py ready <run-folder>, and only process the ready_jobs it returns. Each job reads the prompt and all image inputs registered in imagegen-jobs.json. The base image may start from just the character kit; other rows must include the character master reference image, the pet main image, and the corresponding layout reference.

After selecting a result, actually open the image, then run:

"<workspace-python>" -B scripts/pet_kit.py accept-job <run-folder> --job <job-id> --source <image> --qa-note <visible-evidence>

This command writes the passed result to its official location, performs the deterministic checks for that stage, and updates dependencies.

After the base image passes, generate: idle, left-move, right-move, wave, jump, fail, wait, task-running, and check-result — nine animation states. Each state uses the frame count and application semantics specified by the reference.

When actions are independent of each other, up to three lines may be generated in parallel if the environment allows; the user does not need to schedule tasks.

If flipping left-right does not change the face pattern, light direction, single-side accessories, or emblem meaning, running-left may be derived from an approved running-right using the per-frame mirror script specified by the reference. All other states are generated separately.

After the nine action states pass, generate, following the reference: the 8×9 intermediate spritesheet, an overview image, and nine GIFs. Actually view the images to check: identity, state, direction, looping, scale, and connections.

3. Generate Sixteen Gaze Directions

Based on the actual construction of the character's head, face, eyes, body, appendages, and accessories, the Agent writes qa/look-mechanics.md. This document determines: the fixed anchor points, who leads the gaze, who follows, occlusion for each direction, and the movement amplitude for every 22.5 degrees.

First, generate and approve four directional anchors: up, screen-right, down, and screen-left. Then, generate the 9th and 10th rows, each a full eight-direction family.

Directional rows are uniformly interpolated from the approved four-direction pose. The 10th row simultaneously reads the already completed 9th row, ensuring cross-row continuity. If a single direction fails, redo its entire eight-direction row; do not mix isolated fixed cells into the final spritesheet.

accept-job registers the directional row with the same scale, lower-body anchor point, and baseline, checking the formal cell edges before moving to the next stage.

If an already accepted action or direction fails during a subsequent overview, GIF, continuity check, or blind review, use the same accept-job command with the --replace-complete argument to accept the replacement image. The script moves the replaced job, any downstream jobs that depended on it, and any invalidated artifacts into versioned history, then continues from the earliest failure point. Do not manually change job states or reuse old atlases.

4. Final Check, Deliverable, and Installation

After the directional rows are complete, perform edge de-background-color on the full 8×11 spritesheet exactly once, following the reference. Then, in sequence, run: v2 size and transparency check, standard and final overview, nine GIFs, sixteen-direction diagram, adjacent continuity measurement, and three isolated directional blind reviews. The final image view result and visible evidence for each direction are written into the QA files specified by the reference. The pet is approved only after all four cardinal directions, character identity, accessory connections, action states, and spritesheet geometry pass.

Run:

"<workspace-python>" -B scripts/pet_kit.py finalize <run-folder>
"<workspace-python>" -B scripts/pet_kit.py check <run-folder> --stage final
"<workspace-python>" -B scripts/pet_kit.py install <run-folder>

finalize re-reads the character snapshot, thirteen visual tasks, deterministic reports, and image review conclusions, then generates the official pet directory containing only pet.json and spritesheet.webp. install writes it to the current Codex pet directory. If the same content already exists, do not write it again. If different content occupies the same identifier, return to the "Information and Action Boundaries" section to handle the replacement decision.

After installation, do not restart the application or click the settings toggle on behalf of the user.

When Tools Are Missing

When the Character Identity path has no image generation capability: complete the direction selection and the full draft profile. Run character_kit.py prompt --purpose master and deliver its output. Clearly state that the images and character kit are not yet complete.

When the Derivative Visuals path has no image generation capability: complete the visual brief and run visual_kit.py prompt. Deliver the completed communication judgment and image generation input. Clearly state that the final images and derivative archive are not yet complete.

If there is no writable workspace, you can display images and descriptions, but the results in the chat do not yet form a portable character kit or a verifiable derivative directory.

When the Pet path has no image generation capability: complete pet_kit.py prepare. Deliver the run directory linked to the character kit, the complete task diagram, and the first base image prompt. Clearly state that the action frames, spritesheet, and installation are not yet complete.

If there is no independent image-reading capability: complete all deterministic checks, then only present the directional blind review images and the final overview to the user for confirmation. Do not fabricate three blind reviews or an independent final conclusion.

Delivery and Stop

At the start of the Character Identity path, directly state whether the character is locked. Upon completion, display the official master reference image. Explain the core memory points, current version, and absolute path of the character kit. Then list possible derivative directions, but only continue to complete the result the user has explicitly named.

At the start of the Derivative Visuals path, directly state whether the images are complete or what is still missing. Upon completion, display each final image, then in one sentence explain the core relationship it expresses, the character version used, and the absolute save path. The user does not need to copy prompts, edit JSON, manually number, create branches, or organize images.

At the start of the Pet path, directly state whether the pet has been generated and installed. Upon completion, display the final overview image and at least one action preview. Then explain: the pet name, the character version used, whether the nine states and sixteen directions passed, the final deliverable directory, and the installation absolute path. Finally, only remind the user to restart or reopen Codex and enable the pet in the settings.

The completion criteria are:

• The character kit contains the current profile, documentation, a single master reference image, and readable historical versions. Chibi diagnostics and consistency test images are not long-term references.
• The derivative images consumed the actual production results of the character kit and the user's content. Both character identity and communication relationships were verified through actual image viewing.
• Each official derivative directory can re-validate the character version, visual brief, image generation input, input materials, and final image.
• The pet run directory can re-validate: character snapshot, master reference image, thirteen visual tasks, nine action previews, sixteen-direction semantics, blind reviews, transparency processing, v2 spritesheet, and official pet directory.
• Derivative images and the pet have not reversely changed the character identity. Other unrequested visuals, animations, or platform versions have not been automatically generated.