# Minecraft Image Asset Recipes

Load this file when the user names a specific asset type and you need a sharper
handoff recipe, naming convention, or review target.

## Quick Map

| Asset type | Bias | Review target | Notes |
|---|---|---|---|
| `pack.png` icon | Strong silhouette, simple square composition | Reads cleanly at `64x64` | Use the project's requested dimensions and destination |
| Release banner | Hero scene plus copy-safe negative space | Works on desktop and mobile crop | Save extra source/composed versions only when useful to the requested handoff |
| Thumbnail/store card | Central focal point, high contrast | Still legible in feed or marketplace grids | Keep text minimal |
| Texture concept | Flat material study | Easy to repaint into `16x16`, `32x32`, or `64x64` | Treat as concept, not final asset |
| Server banner/header | Branding plus environmental cue | Still reads when cropped wide | Avoid dense scene clutter |
| UI mockup | Clear panel hierarchy | Space remains for real UI elements | Keep typography flexible |

## `pack.png`

Recommended filenames:

- `pack-icon-concept-a.png`
- `pack-icon-concept-b.png`
- `pack.png` for the final when that destination was requested

Recipe:

1. Generate one square asset with a strong subject, or multiple concepts when alternatives were requested.
2. Down-select based on tiny-size readability, not only full-size detail.
3. Keep decorative text out unless the brand absolutely requires it.
4. Save the result into the requested destination. A clear request to replace `pack.png` authorizes that edit without another approval round.

## Release Banner

Recommended filenames:

- `release-banner-art.png`
- `release-banner-composed.png`

Recipe:

1. Ask for a wide composition with explicit negative space for title text.
2. Prefer one clear hero subject or scene instead of several equal focal points.
3. If final text is still unsettled, save art-only and overlay text later.

## Thumbnail or Store Card

Recipe:

1. Optimize for quick scanning at small size.
2. Use one dominant color story and one dominant subject.
3. Avoid dense paragraphs or interface text inside the generated image.

## Texture Concept

Recommended filenames:

- `ore-texture-concept-v1.png`
- `machine-casing-lookdev.png`

Recipe:

1. Keep the image flat, front-on, and lighting-neutral.
2. Ask for material qualities, not scene storytelling.
3. When pack integration is in scope, complete the pixel cleanup, tiling, and file references; otherwise deliver the concept as requested.

## Server Banner or Header

Recipe:

1. Call out the server tone explicitly: cozy SMP, competitive PvP, fantasy RPG, tech network, etc.
2. Reserve one side for logo or server name.
3. Ask for a composition that survives wide crop and partial mobile crop.

## UI Mockup

Recipe:

1. Identify whether the deliverable is background art, a full mockup, or a visual direction sample.
2. Leave generous blank regions for slots, labels, and action buttons.
3. If the design may become code later, keep layout logic simple and repeatable.

# Minecraft Image Prompt Patterns

Load this file when the request needs a stronger prompt shape than the base
`SKILL.md` workflow provides. Keep prompts specific, but do not over-specify
every surface if the user asked for a fast concept pass.

## Base Spec

Use this template when translating a loose request into a structured prompt:

```text
Use case: <pack-icon | texture-concept | promo-art | server-banner | ui-mockup>
Asset target: <where the image will ship>
Minecraft context: <vanilla-faithful | modded industrial | fantasy server | etc.>
Primary subject: <main thing to show>
Important details: <must-show motifs, mobs, blocks, items, biome cues>
Composition: <square icon | wide banner | flat texture sheet | UI panel background>
Palette: <color direction>
Style: <pixel-art-inspired | painterly splash art | clean mockup>
Keep: <details that must survive revisions>
Avoid: <logos, watermarks, clutter, extra text, off-theme props>
```

## Fresh Generation Pattern

Use when there is no source image to preserve.

```text
Create a new <asset target> for a Minecraft project.
Show <primary subject>.
Style: <style>.
Composition: <composition>.
Palette: <palette>.
Constraints: <hard constraints>.
Avoid: <negative constraints>.
```

## Existing Image Edit Pattern

Use when there is a local image, concept board, or prior generated asset.

```text
Edit the provided image.
Change only: <background / palette / specific objects / framing>.
Keep unchanged: <logo, silhouette, text layout, main character, icon shape>.
Target use: <asset target>.
Avoid: <negative constraints>.
```

Focus edit prompts on deltas. Do not restate the entire scene unless the prior
result drifted significantly.

## Pack Icon Pattern

Use when the final asset must still read at `64x64`.

```text
Create a square Minecraft pack icon with a bold central silhouette.
Primary subject: <item, mob, biome emblem, or landmark>.
Keep the composition simple and readable at tiny size.
Use strong contrast and minimal small detail.
No text, no watermark, no decorative border unless requested.
```

## Texture Concept Pattern

Use when the image is concept art that will later be simplified manually into a
final tile texture.

```text
Create a flat front-on texture concept for <block or item material>.
No perspective, no scene background, neutral lighting.
Make it easy to simplify into a small Minecraft texture later.
Style direction: <vanilla-faithful | noisy industrial | magical crystal | etc.>.
```

## Release Banner Pattern

Use when the output needs copy-safe negative space for titles or release text.

```text
Create a wide Minecraft release banner for <project>.
Show <hero scene>.
Leave clean negative space on the <left or right> for title text.
Favor a strong focal point and mobile-readable composition.
No embedded logo or text unless exact copy was provided.
```

## UI Mockup Pattern

Use when exploring plugin, mod, or server UX without implementing code yet.

```text
Create a Minecraft UI mockup background for <screen or panel>.
Reserve clear space for <buttons, slots, status text, tabs>.
Keep it readable, high-contrast, and aligned to a <vanilla | fantasy | tech> tone.
No tiny unreadable labels unless exact text was requested.
```

## Revision Loop

For follow-up turns, change one major variable at a time:

- composition
- palette
- subject emphasis
- lighting
- background complexity

Example:

```text
Keep the same icon silhouette and palette.
Reduce background detail and make the pickaxe head glow brighter.
```

#!/usr/bin/env bash
set -euo pipefail

usage() {
  cat <<'EOF'
Usage:
  bash ./scripts/scaffold-asset-brief.sh --type <asset-type> --name <slug> [--out <dir>] [--overwrite]

Examples:
  bash ./scripts/scaffold-asset-brief.sh --type pack-icon --name starforge
  bash ./scripts/scaffold-asset-brief.sh --type release-banner --name skylands --out docs/briefs
EOF
}

TYPE=""
NAME=""
OUT_DIR="__AUTO__"
OVERWRITE=0

SCRIPT_DIR="$(CDPATH= cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd -P)"
SKILL_DIR="$(CDPATH= cd -- "$SCRIPT_DIR/.." && pwd -P)"
HOME_DIR=""

if [[ -n "${HOME:-}" && -d "${HOME:-}" ]]; then
  HOME_DIR="$(CDPATH= cd -- "$HOME" && pwd -P)"
elif [[ -n "${USERPROFILE:-}" && -d "${USERPROFILE:-}" ]]; then
  HOME_DIR="$(CDPATH= cd -- "$USERPROFILE" && pwd -P)"
fi

while [[ $# -gt 0 ]]; do
  case "$1" in
    --type)
      TYPE="${2:-}"
      shift 2
      ;;
    --name)
      NAME="${2:-}"
      shift 2
      ;;
    --out)
      OUT_DIR="${2:-}"
      shift 2
      ;;
    --overwrite)
      OVERWRITE=1
      shift
      ;;
    -h|--help)
      usage
      exit 0
      ;;
    *)
      echo "Unknown argument: $1" >&2
      usage >&2
      exit 1
      ;;
  esac
done

infer_workspace_dir() {
  local cwd
  local oldpwd
  local candidate=""

  if [[ -n "${CODEX_WORKSPACE_ROOT:-}" && -d "${CODEX_WORKSPACE_ROOT:-}" ]]; then
    printf '%s\n' "$(CDPATH= cd -- "$CODEX_WORKSPACE_ROOT" && pwd -P)"
    return 0
  fi

  cwd="$(pwd -P)"
  if [[ "$cwd" != "$SKILL_DIR" && "$cwd" != "$SCRIPT_DIR" && "$cwd" != "$SKILL_DIR/"* ]]; then
    printf '%s\n' "$cwd"
    return 0
  fi

  if [[ -n "${OLDPWD:-}" && -d "${OLDPWD:-}" ]]; then
    oldpwd="$(CDPATH= cd -- "$OLDPWD" && pwd -P)"
    if [[ "$oldpwd" != "$SKILL_DIR" && "$oldpwd" != "$SCRIPT_DIR" && "$oldpwd" != "$SKILL_DIR/"* ]]; then
      printf '%s\n' "$oldpwd"
      return 0
    fi
  fi

  case "$SKILL_DIR" in
    */.agents/skills/*|*/.codex/skills/*|*/.claude/skills/*)
      candidate="$(CDPATH= cd -- "$SKILL_DIR/../../.." && pwd -P)"
      ;;
    */plugins/minecraft-codex-skills/skills/*)
      candidate="$(CDPATH= cd -- "$SKILL_DIR/../../../.." && pwd -P)"
      ;;
  esac

  if [[ -n "$candidate" && -n "$HOME_DIR" && "$candidate" == "$HOME_DIR" ]]; then
    case "$SKILL_DIR" in
      "$HOME_DIR/.agents/skills/"*|"$HOME_DIR/.codex/skills/"*|"$HOME_DIR/.claude/skills/"*)
        candidate=""
        ;;
    esac
  fi

  if [[ -n "$candidate" && "$candidate" != "$SKILL_DIR" && "$candidate" != "$SCRIPT_DIR" ]]; then
    printf '%s\n' "$candidate"
    return 0
  fi

  return 1
}

is_absolute_path() {
  local value="$1"
  [[ "$value" == /* || "$value" =~ ^[A-Za-z]:[\\/] ]]
}

resolve_out_dir() {
  local value="$1"
  local workspace=""
  local workspace_file=""

  if [[ "$value" == "__AUTO__" ]]; then
    workspace_file="$(mktemp)"
    if ! infer_workspace_dir >"$workspace_file"; then
      rm -f "$workspace_file"
      return 1
    fi
    cat "$workspace_file"
    rm -f "$workspace_file"
    return 0
  fi

  if is_absolute_path "$value"; then
    printf '%s\n' "$value"
    return 0
  fi

  workspace_file="$(mktemp)"
  if ! infer_workspace_dir >"$workspace_file"; then
    rm -f "$workspace_file"
    echo "Could not infer a project workspace for the relative --out path: $value" >&2
    echo "Re-run the command from your project workspace, set CODEX_WORKSPACE_ROOT, or pass an absolute --out path." >&2
    return 1
  fi
  workspace="$(cat "$workspace_file")"
  rm -f "$workspace_file"

  printf '%s\n' "${workspace%/}/${value#./}"
}

if [[ -z "$TYPE" || -z "$NAME" ]]; then
  echo "--type and --name are required" >&2
  usage >&2
  exit 1
fi

slug="$(printf '%s' "$NAME" | tr '[:upper:]' '[:lower:]' | sed -E 's/[^a-z0-9]+/-/g; s/^-+//; s/-+$//')"
if [[ -z "$slug" ]]; then
  echo "Could not derive a safe slug from --name" >&2
  exit 1
fi

requested_out_dir="$OUT_DIR"
resolved_out_dir=""
resolved_out_file="$(mktemp)"
if ! resolve_out_dir "$requested_out_dir" >"$resolved_out_file"; then
  rm -f "$resolved_out_file"
  if [[ "$requested_out_dir" == "__AUTO__" ]]; then
    echo "Could not infer a project workspace for the asset brief." >&2
    echo "Re-run the command from your project workspace or pass --out <dir> explicitly." >&2
  fi
  exit 1
fi
resolved_out_dir="$(cat "$resolved_out_file")"
rm -f "$resolved_out_file"
OUT_DIR="$resolved_out_dir"

mkdir -p "$OUT_DIR"
target="${OUT_DIR%/}/${slug}-asset-brief.md"

if [[ -e "$target" && "$OVERWRITE" -ne 1 ]]; then
  echo "Refusing to overwrite existing file: $target" >&2
  echo "Pass --overwrite if replacement is intentional." >&2
  exit 1
fi

cat >"$target" <<EOF
# ${NAME} Asset Brief

- Asset type: ${TYPE}
- Slug: ${slug}
- Owner: <project or repo name>
- Final path: <where the approved asset should live>

## Goal

<What should this image accomplish?>

## Minecraft Context

<Vanilla-faithful, modded tech, fantasy RPG server, etc.>

## Primary Subject

<Main subject or focal point>

## Must Keep

- <Details that should survive revisions>

## Avoid

- <Watermarks, extra logos, clutter, off-theme props>

## Composition

<Square icon, wide banner, flat texture sheet, mockup panel, etc.>

## Palette

<Color direction>

## Text

<Exact text if any, or state "none">

## Review Notes

- Tiny-size readability:
- Mobile crop concerns:
- Handoff target:
EOF

echo "Wrote $target"