diff --git a/.reflection-state.json b/.reflection-state.json index 5c3b6a5..2a1ce9f 100644 --- a/.reflection-state.json +++ b/.reflection-state.json @@ -1,8 +1,5 @@ { "version": 1, - "last_run": "2026-03-24T10:36:46Z", - "processed": { - "memory/log/2026-03-17.110845.md": "5ac7f82c96613876a4ecf7f2b5506edf", - "memory/log/2026-03-24.215106.md": "3e039830da10338af26d31fc0959dff1" - } + "last_run": "2026-04-05T00:31:31Z", + "processed": {} } diff --git a/ABOUT.md b/ABOUT.md new file mode 100644 index 0000000..ea6ddb6 --- /dev/null +++ b/ABOUT.md @@ -0,0 +1 @@ +description: Reusable Claude Code skills library diff --git a/README.md b/README.md index 090c5ba..99b23f7 100644 --- a/README.md +++ b/README.md @@ -27,6 +27,11 @@ The install script creates symlinks from `~/.claude/skills/` to this repo, makin | orchestrate | `/orchestrate` | Check task state, launch container agents in git worktrees. Use `/loop 2m /orchestrate` for auto-polling. | | supervise | `/supervise` | Supervisor mode: 15-min tick dispatches/reaps MiniMax `mm-worktree-task` units, 30-min progress report. State in gitignored `.supervisor/`. | | spawn-session | `/spawn-session ` | Spawn a new detached tmux Claude Code session with Remote Control, named after the project (wraps `claude-tmux`). Attach later via `tmux attach` over VPN or drive from the Claude app. | +| minimax-voice | `/minimax-voice` | Synthesize spoken voice from text via the MiniMax TTS API (`minimax-gen voice`). | +| minimax-music | `/minimax-music` | Generate music or a song from a prompt via the MiniMax music API (`minimax-gen music`). | +| minimax-image | `/minimax-image` | Generate one or more images from a text prompt via the MiniMax image API (`minimax-gen image`). | +| minimax-video | `/minimax-video` | Generate a short video clip from a prompt or image via the MiniMax video API (`minimax-gen video`). | +| minimax-mesh | `/minimax-mesh` | Generate a 3D mesh (.blend, .stl, .obj, .glb) from a description via MiniMax LLM + headless Blender (`minimax-gen mesh`). | ## Adding a New Skill diff --git a/memory/log/2026-03-17.110845.md b/memory/log/2026-03-17.110845.md deleted file mode 100644 index 420f70d..0000000 --- a/memory/log/2026-03-17.110845.md +++ /dev/null @@ -1,13 +0,0 @@ -# Session Log — 2026-03-17 - -## Summary -Fixed the `/housekeeping` skill aborting mid-run because info-gathering scripts (`unreflected-logs`, `git-status-report`, `check-skills`, `validate-skill`) exit with code 1 as a status signal, which the skill's `!`command`` syntax treated as a failure. - -## Decisions -- Decision: Append `|| true` to all four bang-command invocations in the housekeeping skill — Rationale: These scripts use exit 1 to signal "issues found" (not errors), and the skill is read-only/informational, so suppressing the exit code is safe. - -## Gotchas Discovered -- **[skills]** Symptom: `!`command`` in SKILL.md fails when the command exits non-zero, even if the output is valid and informational — Fix: Append `|| true` to bang-commands that use exit codes as status signals rather than error indicators. - -## Key Context -- All four scripts in `small-scripts/scripts/` (`git-status-report`, `unreflected-logs`, `check-skills`, `validate-skill`) follow the same pattern: exit 0 = all clear, exit 1 = issues found. This is correct for CLI tools but incompatible with skill bang-command syntax without `|| true`. diff --git a/memory/log/2026-03-24.215106.md b/memory/log/2026-03-24.215106.md deleted file mode 100644 index 3203cdf..0000000 --- a/memory/log/2026-03-24.215106.md +++ /dev/null @@ -1,39 +0,0 @@ -# Session Log — 2026-03-24 - -## Summary - -Designed the M3 composable agent harness architecture for agent-runtimes, wrote the full plan and had a container agent write the harness spec. Created two new skills (`/decompose` and `/orchestrate`) for task decomposition and container agent dispatch with git worktree isolation. - -## Decisions - -- Decision: Harnesses live in a separate `agent-harnesses` repo under skynet org — Rationale: Versioned independently from agent-runtimes, allows different teams/projects to share harness definitions -- Decision: Three harness kinds (capability, context, composite) — Rationale: Separation of concerns between container overlays (tools) and session config (identity, context, skills) -- Decision: Context files mount at unique paths per layer, use `--append-system-prompt-file` — Rationale: Claude Code's native mechanism, no lossy merging, preserves all context layers distinctly -- Decision: Heavy capability layers use OCI mod images (LinuxServer.io pattern) — Rationale: Runtime install too slow for JDK/Rust; single-layer OCI images with modcache provide fast cached extraction -- Decision: Harness-injected actions with payload suppress — Rationale: Cross-cutting concerns (session logging) belong in harness, but payload must be able to override -- Decision: Git worktrees for container agent task isolation — Rationale: No file conflicts between concurrent agents, clean per-task branches, dependency chains branch from parent output -- Decision: No hardcoded concurrency limit — user approves `max_concurrent` during `/decompose` — Rationale: Token usage happens regardless of parallelism; more agents = faster, not more expensive -- Decision: Container agents launched with `docker run -d` (no `--rm`) — Rationale: Logs must survive for inspection after container exit - -## Gotchas Discovered - -- **[docker]** Symptom: Container agent failed with "No payload" error when launched with `docker run ... agent-claude:latest claude --print ...` — Fix: Must use `--entrypoint uid-wrapper.sh` to override the default entrypoint (which expects AGENT_PAYLOAD env var). The `claude-container.sh` script handles this correctly. -- **[skills]** Symptom: validate-skill failed on decompose skill with "Command binary 'ls' not covered" — Fix: Bang-command `!`ls spec/`` requires `Bash(ls *)` in allowed-tools. Every binary in bang-commands must be explicitly covered. -- **[skills]** Symptom: validate-skill warned about `Bash(git *)` being too broad in orchestrate skill — Fix: Acceptable warning — orchestrate needs worktree add/remove, branch, merge, and checkout. Specific subcommand patterns would need 6+ entries. - -## Key Context - -- LangChain research showed 52.8% → 66.5% improvement on Terminal Bench by modifying only the harness, not the model — validates harness design as highest-leverage work -- Claude Code's `--append-system-prompt-file` is the native context injection mechanism (one flag per file, preserves built-in prompt) -- Skills auto-discovered from `.claude/skills/` — just mount them into containers -- Anthropic's reference devcontainer uses iptables firewall allowlisting (adopted into our harness design) -- OpenCode reads `CLAUDE.md` and `~/.claude/skills/` by default — cross-tool compatibility is free -- K8s Agent Sandbox CRD (SIG Apps, March 2026) worth evaluating for M9 -- 95% step problem: 20 steps at 95% each = 36% success — keep harness layers to 3-5 - -## Process Notes - -- Container agent successfully wrote a 426-line spec from a detailed prompt — validates the pattern of using container agents for substantial spec/code work -- Research phase used 3 parallel agents effectively: LinuxServer.io patterns, broader container composition, and existing codebase analysis -- Second research round (Claude devcontainers, OpenCode, 2026 best practices) surfaced important design refinements that improved the plan -- The `/decompose` + `/orchestrate` + `/loop` workflow creates a "manager session" pattern where the human drives strategy while agents execute in parallel diff --git a/skills/end-session/SKILL.md b/skills/end-session/SKILL.md index b987ae5..534bd76 100644 --- a/skills/end-session/SKILL.md +++ b/skills/end-session/SKILL.md @@ -1,9 +1,11 @@ --- name: end-session description: > - End-of-session wrap-up. Captures a session log, updates CONTEXT.md for seamless - resumption, and refreshes project docs (README, CLAUDE.md, FUTURE.md) with anything - that changed this session. Just run /end-session when you're done working. + End-of-session wrap-up. Captures a session log; for planner-backed projects writes + a session status doc to the work-items store (the authoritative state source); + updates CONTEXT.md as a thin cache for planner projects or fully for non-planner + projects; refreshes project docs (README, CLAUDE.md, FUTURE.md) with anything that + changed this session. Just run /end-session when you're done working. allowed-tools: Read, Edit, Write, Grep, Glob, Bash(git log *), Bash(git diff *), Bash(date *), Bash(ls *), Bash(cat *), Bash(find *), Bash(rm *), Bash(mkdir *), Bash(sed *), Bash(python3 -m lib.cp_cli *) --- @@ -111,11 +113,57 @@ Write the file using this format: --- -## Phase 2: Update CONTEXT.md +## Phase 2: Update state — planning store (primary) or CONTEXT.md (fallback) -This is the most important phase for session resumption. CONTEXT.md tells the next session what to focus on. +**Detect whether the project has a planner:** look for `cp-cli planner` in the project's +CLAUDE.md. If found, the project has a live planner and Step 2.1 applies. Otherwise go +to Step 2.2 (CONTEXT.md-only flow). -### Step 2.1: Assess current state +> **Long-term goal:** for planner-backed projects, CONTEXT.md is being retired in favour +> of `scripts/get_context` as the authoritative live state source. Until it is removed, +> keep the CONTEXT.md "Current State" header updated as a thin cache — one line per major +> change — but do NOT write new narrative detail there. All narrative goes to work-items. + +### Step 2.1: Planning-store write-back (projects WITH a planner) + +The session is **not finished until delivered work is written back to the planner**. +`scripts/get_context` is what future sessions and agents see — stale items mislead them. + +1. **Assess what this session delivered or advanced**: milestones progressed/completed, + bugs fixed, features shipped, specs updated, pipelines deployed. + +2. **Write a session status document** (`session-YYYY-MM-DD-.md`) capturing: + - What was done and the key commits + - Root causes / decisions / gotchas discovered + - Current cluster/deployment state (image version, what's live) + - What's next + + Write to `/tmp/.md`, then upload to the most relevant item(s) with: + ```bash + python3 -m lib.cp_cli planner items documents put .md --file /tmp/.md + ``` + Upload to whichever item(s) the work actually belongs to (milestone, epic, bug, etc.). + If the work spans multiple items, one doc is enough — upload it to the primary one. + +3. **Update item flow states** for anything that completed this session: + - `python3 -m lib.cp_cli planner items update --flow-state completed` + - If the planner doesn't support direct state updates, note it in the doc and skip. + +4. **Check roll-up documents for contradictions**: any epic overview or delivery map that + summarises affected milestones must not contradict reality after this session's changes. + Fix what you have ground truth for; flag the rest. + +5. **Update CONTEXT.md as a thin cache only** — find the "Current State" section and + update just the cluster image version and a one-liner about what changed. Do NOT add + new narrative sections. Resist the urge to expand CONTEXT.md; that information belongs + in work-items. If CONTEXT.md doesn't exist yet, do not create it. + +6. If nothing this session touched milestone/epic-level state, still write a brief + session doc to the most relevant item so `scripts/get_context --show-rca` captures it. + +### Step 2.2: CONTEXT.md update (projects WITHOUT a planner) + +For projects with no planner, CONTEXT.md is still the primary handoff mechanism. Based on the full conversation, determine: - What work is actively in progress (not yet complete)? @@ -123,51 +171,52 @@ Based on the full conversation, determine: - What should the next session pick up first? - Are there blockers, pending decisions, or things to verify? -### Step 2.2: Update CONTEXT.md and context/ files - Follow the thin-index pattern: 1. **Remove completed entries** from CONTEXT.md that are no longer active. 2. **Add or update entries** for active work streams, linking to detail files in `context/`. -3. **Create or update `context/.md`** files with enough detail for a fresh session to resume without re-reading the full conversation: +3. **Create or update `context/.md`** files with enough detail for a fresh session to + resume without re-reading the full conversation: - What's the current state? - What was the last thing done? - What should be done next? - Any gotchas, blockers, or decisions pending? - Key file paths, commands, or references needed to continue. - -4. If `context/` directory doesn't exist and there are active work streams, create it with `mkdir -p context/`. +4. If `context/` directory doesn't exist and there are active work streams, create it. **Principles:** -- Write for a Claude session that has zero conversation history -- it only has CONTEXT.md and the linked files. +- Write for a Claude session with zero conversation history. - Be specific: file paths, branch names, error messages, command sequences. -- Don't duplicate what's in CLAUDE.md or MEMORY.md -- reference those instead. -- If there's nothing active (session wrapped up cleanly with no follow-up), say so in CONTEXT.md: `No active work streams. Project is at a clean stopping point.` +- Don't duplicate what's in CLAUDE.md or MEMORY.md — reference those instead. +- If there's nothing active: `No active work streams. Project is at a clean stopping point.` -### Step 2.3: Planning-store status write-back +### Step 2.3: RCA document write-back -If the project's CLAUDE.md declares a canonical planning store outside the repo (e.g. a -work-items repo managed via `cp-cli planner items …`, like `agent-runtimes-work-items`), -the session is **not finished until delivered work is written back to it**. Stale planning -stores mislead every future session and agent that treats them as canonical. +If this session root-caused a real incident — a bug, outage, or regression with a clear +symptom, root cause, and fix, not just routine debugging — and the project's planning store +supports an `incident` item type (check the store's `DATA_VALUES.md`/`CLAUDE.md` for an +`incident` type and an `rca--.md` naming convention; most projects will not have +this, in which case skip this step entirely): -1. **List what this session delivered or advanced**: milestones completed or progressed, - epics affected, specs shipped, pipelines deployed. -2. **For each affected item**, update its status in the planning store: - - CP reachable: update the item's flow state / status document via - `cp-cli planner items …` / `documents put` (see the project CLAUDE.md for the exact - workflow). - - CP unreachable but the store has a local git checkout: edit the status/plan/CONTEXT - docs there directly and note in CONTEXT.md that the edit needs upload/push. - - Neither: stage the update in the project's offline staging dir (e.g. - `local-planning//`) and record the pending upload in CONTEXT.md. -3. **Check roll-up documents for contradictions**: any epic overview, delivery map, or - roadmap doc that summarises the affected milestones must not now contradict reality - (e.g. still saying "pending" for work that shipped this session). Fix the rows you have - ground truth for; flag the ones you don't. -4. If nothing this session touched milestone/epic-level state, say so and move on. +1. **Find or create the `incident` item.** Search the planning store for an existing + `type: incident` item covering this incident before creating a new one. +2. **Write the full postmortem** as `rca--.md`, where `` is the date the + incident *occurred* (not today, if determinable from git history/logs) and `` is a + short kebab-case description. Cover symptom, root cause, fix, and impact — this is the + durable narrative; the item's `CONTEXT.md` body stays a short summary. +3. **Upload it to the `incident` item**: + - CP reachable: `python3 -m lib.cp_cli planner items documents put rca--.md --file ` + - CP unreachable but the store has a local git checkout: write the file directly under + `by-uuid//rca--.md` there and note in CONTEXT.md that it + needs a commit/push. + - Neither: stage it in the project's offline staging dir (e.g. `local-planning/`) and + record the pending upload in CONTEXT.md. +4. **Link every affected item** to the incident via the `impacted`/`impacted_by` + relationship verb (or whatever the store's `DATA_VALUES.md` names it) — one document on + the `incident` item, one relationship edge per affected item, not copies of the document. +5. If nothing this session rises to postmortem-worthy, skip this step and say so. -Skip this step entirely only when the project has no external planning store. +Skip this step entirely when the project has no external planning store. ### Step 2.4: RCA document write-back @@ -248,9 +297,9 @@ Print a concise summary: - Number of entries by section - Any files pruned or warnings issued -**Context update:** -- What CONTEXT.md now points to (active work streams) -- What the next session should pick up +**State update:** +- (planner project) Which items got a session doc uploaded; any flow-state changes; CONTEXT.md current-state one-liner +- (no-planner project) What CONTEXT.md now points to; what the next session should pick up **Doc updates:** - Which files were updated (FUTURE.md, README.md, CLAUDE.md) and what changed @@ -262,8 +311,8 @@ Print a concise summary: - Gotchas include **symptom AND fix**, not just "X was tricky" - Process lessons are phrased as **rules** ("Always X before Y") -- CONTEXT.md entries are **specific enough to resume from** without conversation history -- Context detail files include **file paths, branch names, and next steps** +- (planner) Session status doc is uploaded to the correct item; CONTEXT.md current-state is updated to one line +- (no-planner) CONTEXT.md entries are **specific enough to resume from** without conversation history; detail files include file paths, branch names, and next steps - Future items have all four fields (Problem/Idea/Open questions/Depends on) - Doc updates are **minimal and accurate** -- only touch what actually changed this session - README scripts section lists every script with purpose and usage diff --git a/skills/minimax-image/SKILL.md b/skills/minimax-image/SKILL.md new file mode 100644 index 0000000..bda65c7 --- /dev/null +++ b/skills/minimax-image/SKILL.md @@ -0,0 +1,71 @@ +--- +name: minimax-image +description: > + Generate one or more images from a text prompt via the MiniMax image API. + Use when the user wants an illustration, picture, logo, concept art, sprite, + icon, or visual. Trigger on phrases like "draw", "generate an image", + "create a picture", "make a sprite", "render", "show me what X looks like". +allowed-tools: Bash(minimax-gen image *), Bash(minimax-gen --help), Bash(mkdir *), Bash(ls *), Bash(test *), Bash(file *), Read +--- + +# /minimax-image — Image Generation + +Generate images from a text prompt. Single image or batch. + +## CLI + +```bash +# Single image +minimax-gen image "A castle on a hill at sunset, painterly" \ + --aspect-ratio 16:9 \ + --out /tmp/castle.png + +# Multiple images into a directory +minimax-gen image "A red apple, studio lighting" \ + --out /tmp/apples/ --n 4 --aspect-ratio 1:1 + +# Wider aspect for landscape scenes +minimax-gen image "Mountain valley at dawn, fog" \ + --aspect-ratio 21:9 --out /tmp/valley.png +``` + +The CLI is at `~/dev/claude/gamedev/minimax-gen/bin/minimax-gen`. + +## Aspect ratios + +`1:1` (default), `16:9`, `4:3`, `3:2`, `2:3`, `3:4`, `9:16`, `21:9`. + +Choose based on the use case: +- Sprites / icons → `1:1` +- Wallpapers / backgrounds → `16:9` or `21:9` +- Portraits / character → `2:3` or `9:16` + +Or pass `--width` and `--height` (both must be set, divisible by 8, 512–2048). + +## Output format + +The CLI writes whatever format the API returns (typically JPEG). The `--out` +suffix is corrected to match (`/tmp/castle.png` written as `/tmp/castle.jpg` if +the API returns JPEG). A sidecar `.meta.json` carries the prompt, trace_id, +and source URL. + +## Tips + +- `--prompt-optimizer` lets the API rewrite the prompt for better results. +- `--seed N` makes the result reproducible. +- URLs from the API expire in 24h — the CLI downloads the bytes so the file is + yours to keep. + +## After the call + +1. Show the path(s) written and the `trace_id` from the sidecar. +2. Suggest variations (different aspect, seed, prompt-optimizer on). +3. Do NOT print the meta JSON — point at the file. + +## Never do + +- Never echo, log, or commit the contents of `~/.claude-secrets/minimax-auth-token`. + +## Reference + +Full option list: `minimax-gen image --help` diff --git a/skills/minimax-mesh/SKILL.md b/skills/minimax-mesh/SKILL.md new file mode 100644 index 0000000..ff6b8fc --- /dev/null +++ b/skills/minimax-mesh/SKILL.md @@ -0,0 +1,107 @@ +--- +name: minimax-mesh +description: > + Generate a 3D mesh (.blend, .stl, .obj, .glb) from a natural-language + description via the MiniMax LLM + headless Blender 4.0. Use when the user + wants a 3D model, a low-poly asset, a weapon, a piece of furniture, a + vehicle, or any game-ready prop. Trigger on phrases like "3D model", + "low-poly", "Blender", "make a sword", "generate a barrel", "model a chest". +allowed-tools: Bash(minimax-gen mesh *), Bash(minimax-gen --help), Bash(blender --background *), Bash(mkdir *), Bash(ls *), Bash(test *), Bash(file *), Read +--- + +# /minimax-mesh — 3D Mesh Generation + +Generate a 3D asset from a description. The MiniMax LLM writes Blender Python +(`bpy`), the script is hardened, and headless Blender saves a `.blend` file (or +exports to `stl`/`obj`/`glb`). + +## CLI + +```bash +# Native Blender file (full editability) +minimax-gen mesh "a small wooden treasure chest with brass fittings" \ + --out /tmp/chest.blend + +# Game-ready export +minimax-gen mesh "a wooden barrel with metal hoops" \ + --format glb --out /tmp/barrel.glb + +# Pick a thinking depth and token budget +minimax-gen mesh "a simple wooden shield" \ + --effort medium --max-tokens 8192 \ + --out /tmp/shield.blend +``` + +The CLI is at `~/dev/claude/gamedev/minimax-gen/bin/minimax-gen`. + +## Output formats + +| Format | Use | +|---|---| +| `blend` (default) | full editable Blender file | +| `glb` | game engines (Godot, Three.js, Unity) | +| `obj` | traditional 3D tools | +| `stl` | 3D printing | + +When `--format` is not `blend`, the script also writes the `.blend` next to +the export so the user can edit it later. + +## Pick a model + +Default is `MiniMax-M3.1-Flash-Preview` at `--effort low`. It always thinks, so +effort is what keeps the token budget for code (live check 2026-10-13: low used +~100 reasoning tokens, max ~240, on a trivial prompt). Raise `--effort` for +complex scenes; bump `--max-tokens` with it because thinking counts against it. + +| Model | Use | +|---|---| +| `MiniMax-M3.1-Flash-Preview` (default) | `--effort low\|medium\|high\|xhigh\|max` | +| `MiniMax-M2.5-highspeed` | previous default, fast, clean code, no effort control | +| `MiniMax-M2.5` / `M2.7(-highspeed)` | older gens | +| `MiniMax-M3` | rarely usable here | + +## Bump max-tokens when the LLM truncates + +A simple scene is ~2–4 KB of Python. Default `--max-tokens 6144` is enough for +most; bump to 8192 or higher if a complex prompt gets cut off mid-script. + +## What you get + +- The `.blend` (or other format) at the requested path. +- A sidecar `.gen.py` with the LLM-generated Python code. **Always point + the user at this file** — it's reviewable, editable, and re-runnable. + +## After the call + +1. Show the path written, the script path, and the wall-clock seconds. +2. Suggest reasonable next steps (preview in Blender, edit the `.gen.py`, + rerun with a different prompt). +3. Do NOT run any post-processing that requires user confirmation without + asking — the LLM may have generated something unexpected. + +## Normalization (default 1×1×1 unit box) + +Every output is post-processed so the combined mesh fits inside a unit cube +with the longest axis = 1.0 and the other two scaled proportionally (≤ 1.0). +The geometry is also centred on the origin. This applies to the `.blend` +*and* to any export (`.glb`, `.obj`, `.stl`) derived from it. + +This is what the game-engine side expects: ask for a "6m player ship" and +scale the imported `player_ship.glb` by 6 in the engine — don't ask the +LLM for absolute sizes (it can't honour them reliably). Relative +proportions (long vs wide vs tall) are still useful in the prompt; the +absolute scale is taken care of here. + +Pass `--no-normalize` to keep the LLM-generated raw size (only do this +if you specifically want the LLM's dimensions — e.g. when asking for +"a 2m cube" and you literally want a 2m cube). + +## Never do + +- Never echo, log, or commit the contents of `~/.claude-secrets/minimax-auth-token`. +- Never auto-render high-res images or animations without asking — those cost + real credits. + +## Reference + +Full option list: `minimax-gen mesh --help` diff --git a/skills/minimax-music/SKILL.md b/skills/minimax-music/SKILL.md new file mode 100644 index 0000000..cd1684a --- /dev/null +++ b/skills/minimax-music/SKILL.md @@ -0,0 +1,75 @@ +--- +name: minimax-music +description: > + Generate music or a song from a prompt (and optional lyrics) via the MiniMax + music API. Use when the user wants music, a beat, a soundtrack, a theme song, + background music, or a melody. Trigger on phrases like "make a song", + "compose music", "background music", "theme tune", "lo-fi beat". +allowed-tools: Bash(minimax-gen music *), Bash(minimax-gen --help), Bash(mkdir *), Bash(ls *), Bash(test *), Bash(file *), Read +--- + +# /minimax-music — Music Generation + +Generate a music track via the MiniMax music API. Lyrics are optional. + +## CLI + +```bash +# Instrumental +minimax-gen music --prompt "epic, 120 bpm, brass, strings" --instrumental \ + --out /tmp/theme.mp3 + +# With lyrics (read from a file) +minimax-gen music --lyrics @lyrics.txt --prompt "indie folk, warm acoustic" \ + --out /tmp/song.mp3 + +# Auto-generated lyrics from the prompt +minimax-gen music --prompt "a love song with a slow build" --lyrics-optimizer \ + --out /tmp/love.mp3 +``` + +The CLI is at `~/dev/claude/gamedev/minimax-gen/bin/minimax-gen`. + +## Choose a model + +| Model | Use | +|---|---| +| `music-3.0` (default) | latest, paid (may queue 5+ min during peak) | +| `music-3.0-free` | free tier, 3 RPM, ~40s typical | +| `music-2.6` / `music-2.6-free` | previous gen | +| `music-cover` | needs `--audio-url` or `--audio-base64` reference | + +Tip: scripts and smoke tests should use `music-3.0-free` to avoid burning credits. + +## Structure tags for lyrics + +``` +[Intro] +[Verse 1] +[Pre Chorus] +[Chorus] +[Interlude] +[Bridge] +[Outro] +[Inst] +``` + +## Timeouts + +Music can take up to 5 minutes. Default `--timeout` is 600s. Bump it for longer +tracks or when the queue is busy. + +## After the call + +1. Show the path written and the `trace_id` from the sidecar `.meta.json`. +2. Note the duration (`duration_ms`) and size so the user knows what to expect. +3. Don't dump the meta JSON into chat — point at the file. + +## Never do + +- Never echo, log, or commit the contents of `~/.claude-secrets/minimax-auth-token`. +- Never pass the token on a command line. + +## Reference + +Full option list: `minimax-gen music --help` diff --git a/skills/minimax-video/SKILL.md b/skills/minimax-video/SKILL.md new file mode 100644 index 0000000..e524a14 --- /dev/null +++ b/skills/minimax-video/SKILL.md @@ -0,0 +1,61 @@ +--- +name: minimax-video +description: > + Generate a short video clip from a text prompt or an image via the MiniMax + video API. Use when the user wants video, a moving clip, animation, or a + short film. Trigger on phrases like "make a video", "animate this", "film", + "create a clip", "video of X". +allowed-tools: Bash(minimax-gen video *), Bash(minimax-gen --help), Bash(mkdir *), Bash(ls *), Bash(test *), Bash(file *), Read +--- + +# /minimax-video — Video Generation + +Generate a short video clip. Asynchronous — submit, poll, download. + +## CLI + +```bash +# Text-to-video +minimax-gen video --prompt "A paper plane gliding over a city" \ + --duration 6 --resolution 768P \ + --out /tmp/plane.mp4 + +# Image-to-video (animate a still) +minimax-gen video --image-url https://example.com/cover.jpg \ + --out /tmp/anim.mp4 +``` + +The CLI is at `~/dev/claude/gamedev/minimax-gen/bin/minimax-gen`. + +## Models and resolutions + +| Model | Resolutions | +|---|---| +| `MiniMax-Hailuo-2.3` (default) | `768P`, `1080P` | +| `MiniMax-Hailuo-2.3Fast` | `768P`, `1080P` (cheaper, faster) | +| `MiniMax-Hailuo-02` | legacy | + +`720p` is rejected — use `768P` or `1080P` (capitalised). + +## Duration + +Common: 6 seconds. The default is 6. + +## Timeouts + +Async work — total wall-clock can be 1–5 minutes. Default `--timeout` is 900s. +`--poll-interval` controls how often we ask the server for status (default 5s). + +## After the call + +1. Show the path written and the `task_id` from the sidecar `.meta.json`. +2. Note the resolution (`video_width` × `video_height`) and file size. +3. Do NOT print the meta JSON — point at the file. + +## Never do + +- Never echo, log, or commit the contents of `~/.claude-secrets/minimax-auth-token`. + +## Reference + +Full option list: `minimax-gen video --help` diff --git a/skills/minimax-voice/SKILL.md b/skills/minimax-voice/SKILL.md new file mode 100644 index 0000000..9bd170d --- /dev/null +++ b/skills/minimax-voice/SKILL.md @@ -0,0 +1,55 @@ +--- +name: minimax-voice +description: > + Synthesize spoken voice from text via the MiniMax TTS API. Use when the user wants + speech, narration, voice-over, audio book, or to hear a line read aloud. Trigger + on phrases like "say this", "voice this", "speak", "TTS", "read aloud", "narrate". +allowed-tools: Bash(minimax-gen voice *), Bash(minimax-gen --help), Bash(mkdir *), Bash(ls *), Bash(test *), Bash(file *), Read +--- + +# /minimax-voice — Text-to-Speech + +Generate an MP3 (or other audio format) from text using the MiniMax TTS API. + +## CLI + +```bash +minimax-gen voice "Hello, world." --out /tmp/hello.mp3 +minimax-gen voice "Greetings, traveller." --out /tmp/greeting.mp3 \ + --voice English_expressive_narrator --emotion calm --speed 1.1 +``` + +The CLI is at `~/dev/claude/gamedev/minimax-gen/bin/minimax-gen` (or any path the user has on `$PATH`). + +## Pick the voice + +`t2a_v2` offers 300+ voices. A few useful defaults: + +| Voice ID | Tone | +|---|---| +| `English_expressive_narrator` | warm, narrative (default) | +| `English_Graceful_Lady` | calm, feminine | +| `English_PassionateWarrior` | strong, dramatic | +| `English_Comedian` | upbeat, playful | + +For the full list, the API model `speech-2.8-hd` exposes them via the docs. + +## Audio format + +Default: `mp3` 32 kHz 128 kbps mono. Other formats: `pcm`, `flac`, `wav`, `opus`. + +## After the call + +1. Show the user the path written and the `trace_id` from the sidecar `.meta.json`. +2. Suggest reasonable next steps (preview, regenerate with different emotion). +3. Do NOT print the contents of the meta JSON to the chat — point at the file. + +## Never do + +- Never echo, log, or commit the contents of `~/.claude-secrets/minimax-auth-token`. +- Never pass the token on a command line — the CLI reads it from the file directly. +- Never write the token to any other file, even a temp file. + +## Reference + +Full option list: `minimax-gen voice --help` diff --git a/skills/reflect/SKILL.md b/skills/reflect/SKILL.md index 107055d..8a3f0e2 100644 --- a/skills/reflect/SKILL.md +++ b/skills/reflect/SKILL.md @@ -80,7 +80,10 @@ Update these files in order: 3. **README.md** — Update the milestone table status and the Scripts section with any new scripts. 4. **CLAUDE.md** — Update the repo structure if it changed, and add any new conventions or - patterns discovered. + patterns discovered. If the project follows the thin-index pattern (a `claude/` directory + with per-topic detail files referenced from CLAUDE.md), per-subsystem conventions belong + in the appropriate `claude/.md` file. Only edit the root CLAUDE.md for + always-applies guardrails, the architecture overview, or the pointer table itself. ### Step 4: Summary diff --git a/skills/switch-mode/SKILL.md b/skills/switch-mode/SKILL.md index 7e31c3c..17bd249 100644 --- a/skills/switch-mode/SKILL.md +++ b/skills/switch-mode/SKILL.md @@ -85,7 +85,6 @@ CLAUDE_MODE_TAG= CLAUDE_DRIVER= CLAUDE_ESCALATES_TO= CLAUDE_PROJECT= -CLAUDE_TIME_HORIZON=2 CLAUDE_ASYNC_OK= CLAUDE_AUTOLOOP= CLAUDE_PLAN_MODE_AUTO=