---
name: mioku-developer
description: Build, review, refactor, or explain Mioku plugins, services, framework integrations, and plugin AI skills against the real Mioku repository layout. Use when working on Mioku architecture, `plugins/*`, `src/services/*`, `skills.ts`, `runtime.ts`, plugin `package.json -> mioku.*`, WebUI `config.md`, or system services such as `60s`, `ai`, `config`, `help`, `screenshot`, and `webui`. Exclude legacy Minecraft plugin/service work unless the user explicitly asks for it.
---

# Mioku Developer

Use this skill to make repository-accurate changes for Mioku. Treat the checked-out source as the source of truth and use the bundled references to avoid drifting back to older plugin contracts.

## Start Here

Follow this order:

1. Confirm whether the task is framework-level, plugin-level, service-level, AI-skill-level, or WebUI config-page work.
2. Inspect the target files in the repository before proposing changes.
3. Read only the relevant reference files:
   - `references/architecture.md` for startup flow, discovery, auto-registration, and layer boundaries
   - `references/plugin-development.md` for plugin package shape, `skills.ts`, `runtime.ts`, `config.md`, and help conventions
   - `references/service-development.md` for service contract, discovery, lifecycle, and plugin consumption
   - `references/system-services.md` for built-in non-Minecraft service APIs and caveats
4. Implement changes in the repository's established style.
5. Validate with `bun run build` for edits under `src/`, `plugins/`, or `src/services/`.

## Core Rules

- Prefer repository source over prose docs when they disagree.
- Treat Mioku as a layer on top of `mioki`: `mioki` handles bot/events/plugin execution, Mioku adds service discovery, plugin metadata discovery, auto help registration, and AI skill loading.
- Keep normal plugin `index.ts` focused on runtime behavior only.
- Declare required services only in `package.json -> mioku.services`.
- Declare help only in `package.json -> mioku.help`.
- Export global plugin AI skills only from `skills.ts`.
- Do not add `help` or `skill` fields onto the plugin object for normal plugins.
- Do not call `helpService.registerHelp(...)` or `aiService.registerSkill(...)` from normal plugins unless the task is explicitly changing Mioku framework internals.
- Simple plugins/services can stay in one focused file.
- As complexity grows, split by responsibility into small files instead of growing one large `index.ts` or one large shared helper file.
- Use `runtime.ts` only as a bridge when `skills.ts` needs mutable state created during `setup()`.
- Do not rely on module-local singletons inside `runtime.ts`; prefer `src/core/plugin-runtime-state.ts`.
- Ignore legacy Minecraft plugin/service code unless the user explicitly asks for it.

## Plugin Workflow

When creating or editing a plugin:

1. Read `package.json`, `index.ts`, and `skills.ts` if present.
2. Ensure the plugin directory name, plugin name, and package naming stay aligned.
3. Put declarative metadata in `package.json`.
4. Put event handlers, config registration, service wiring, and cleanup in `index.ts`.
5. Keep small plugins simple. As the plugin grows, move pure reusable logic into `shared.ts`, `utils.ts`, or other focused modules instead of one oversized file.
6. Add `runtime.ts` only when `skills.ts` must access setup-created state, and back it with the shared runtime registry.
7. If the plugin needs WebUI editing, define `config.md` with `<configName>.<jsonPath>` keys.

## Service Workflow

When creating or editing a service:

1. Keep the service under `src/services/<name>/`.
2. Export a `MiokuService` object from `index.ts`.
3. Keep small services simple; split larger services into focused modules such as `types.ts`, `client.ts`, `utils.ts`, or domain-specific files.
4. Expose a typed API on `service.api`.
5. Initialize resources in `init()` and release them in optional `dispose()`.
6. Remember that Mioku injects service APIs into plugins through `ctx.services.<name>`.
7. Check whether plugin docs, examples, or imports need updates when service API shape changes.

## AI Skill Workflow

When the task involves plugin AI tools:

1. Read `references/plugin-development.md` and `references/system-services.md`.
2. Prefer plugin-scoped skills exported from `skills.ts` as `AISkill[]`.
3. Keep tool handlers small and predictable.
4. Pass runtime state through `runtime.ts` instead of closing over `setup()` locals, using the shared runtime registry rather than plain module-level state.
5. Use `ai` service runtime features only when the plugin truly needs model calls or chat runtime integration.

## Validation

- Run `bun run build` after meaningful code changes in Mioku.
- If behavior changed, verify the affected startup path, message command, or service usage locally.
- Call out repository quirks that affect generated code, such as the current `src/services/config/tpyes.ts` filename typo.