Start

Guided start

The entry point for building a Minecraft plugin. It detects state, asks where you are, configures the target stack (writes .mcplugin/config.yml), then offers to scaffold the project. It won't silently run steps: at the config→scaffold boundary it asks first, and beyond scaffolding it hands off (features, build, run are each their own command).

Ground every version/Java/coordinate fact in the references — don't rely on memory (Minecraft changed materially in 2026). Read as needed (relative to this skill; Glob **/references/... as a fallback):

• ../../references/api/VERSION.md — version→Java→api-version matrix, 2026 changes
• ../../references/platforms.md — platform trade-offs
• ../../references/build-systems.md — coordinates per build tool

Phase 1: Detect project state (silently)

Use this to tailor recommendations; don't dump it:

• Stack configured? Read .mcplugin/config.yml if it exists (this may be a returning user).
• Project scaffolded? Glob pom.xml, build.gradle*, src/main/java/**/*.java.
• Descriptor present? Glob **/plugin.yml / **/paper-plugin.yml.
• Existing/foreign plugin? Java/build files but no .mcplugin/config.yml = the user brought a project the toolkit hasn't been told about yet.

Phase 2: Ask where the user is

Use AskUserQuestion:

• Prompt: "Welcome — let's build a Minecraft plugin. Where are you starting from?"
• Options:
  • A) Brand new — No project yet. Make a plugin from scratch.
  • B) Have an idea — Knows roughly what it should do; set it up and build it.
  • C) Existing project — Already has plugin code/build files.
  • D) Just configure — Only wants to set/change platform, MC version, or build tool.

Wait for the answer; validate against Phase 1 (e.g. picked A but code exists → point that out). For B, ask them to describe the plugin in one sentence (what it does in-game) and reflect it back before continuing.

Phase 3: Configure the stack + project identity

End this phase with a written .mcplugin/config.yml. This is the same configuration /setup-platform performs — done here so a new user answers everything in one flow.

• If .mcplugin/config.yml already exists (returning user): show the current stack and ask (AskUserQuestion) "Keep this stack, or change it?" Keep → skip to Phase 4. Change → ask the questions below.
• Path C (existing project): infer platform, MC version, Java, build tool, and identity from pom.xml/build.gradle*/plugin.yml; summarize what you found and ask the user to confirm or correct it — don't ask from scratch.
• Paths A / B / D (and C when nothing to infer): ask with AskUserQuestion, only what's still unknown:
  1. Platform — Paper (recommended), Spigot, Folia, Velocity (proxy), with a short trade-off each from platforms.md. If they pick Folia or a proxy, note it changes how every feature is written and confirm they meant it.
  2. Minecraft version — offer the current stable and the dominant classic line as concrete options (e.g. 26.1.x (newest, Java 25), 1.21.x (widest ecosystem, Java 21)) plus "other (I'll type it)". If they want the latest and you have WebFetch, verify the current build at https://papermc.io/downloads/paper and say what you found; else use the newest version in VERSION.md and tell them to confirm there.
  3. Build tool — Maven, Gradle (Kotlin DSL), Gradle (Groovy). No preference → default Maven and say so.

Then gather the project identity & plugin.yml metadata (per ../../references/project-config.md) by asking each field as its own question with AskUserQuestion — one field per question, a sensible default as the first option (the user picks it or types their own via "Other"), grouped a few at a time: plugin name · base package (group id) · version [1.0.0] · main class [= plugin name] · description · author(s) · contributors [none] · website [none] · console prefix [none]. For path C, pre-fill each default from the existing pom.xml/plugin.yml.

Derive the rest from the references — never guess: stack values version_scheme (year for 26.x+, classic for 1.x), java_version, api_version, paper_api_version (exact coordinate for the build tool + scheme — Gradle wants 26.1.2.build.+, Maven a range like [26.1.2.build,); classic is 1.21.4-R0.1-SNAPSHOT); and identity values artifact_id (name lowercased), package (group_id.artifact_id unless overridden), main (package.main_class). If a value is uncertain because the version is newer than the references, say so and point to the live source rather than inventing it.

Create .mcplugin/ and write the full schema from project-config.md (this write is the phase's purpose — no separate "may I write?"); leave optional fields blank if the user skipped them:

# Stack + identity for this plugin — written by /start (or /setup-platform). Skills read this.
platform: paper
mc_version: "1.21.4"
build_tool: maven
version_scheme: classic                     # derived
api_version: "1.21"                         # derived
java_version: 21                            # derived
paper_api_version: "1.21.4-R0.1-SNAPSHOT"   # derived
plugin_name: DungeonCrawler
group_id: com.lucastudios
plugin_version: "1.0.0"
description: "Diablo-style dungeon crawler on a vanilla Minecraft Java Edition client"
authors: [Lucastudios]
contributors: [Vaguestan Development]        # blank if none (kept, not omitted)
website: "lucastudios.com"                   # blank if none (kept, not omitted)
prefix: "DungeonCrawler-MC"                  # blank if none (kept, not omitted)
main_class: Main
artifact_id: dungeoncrawler                 # derived
package: com.lucastudios.dungeoncrawler     # derived
main: com.lucastudios.dungeoncrawler.Main   # derived

Then show the resolved stack + identity in a short table and state the required JDK plainly (e.g. "This target needs Java 21 — make sure java -version reports 21+").

Phase 4: Offer to continue into scaffolding

The stack is configured. Decide the next move with the user — don't silently barrel ahead, and don't silently stop. Ask explicitly (AskUserQuestion):

• Prompt: "Stack saved ({platform} {mc_version}, {build_tool}). Scaffold the project now, or stop here?"
• Options:
  • Scaffold now — generate the project skeleton straight away.
  • Stop here — I'll run the next step myself.

If Scaffold now: run the scaffolding flow defined by the /scaffold skill rather than improvising — read ../scaffold/SKILL.md (Glob **/skills/scaffold/SKILL.md as fallback) and follow it: gather any missing project identity (plugin name, base package), fill the templates, and show the build file + plugin.yml for approval before writing (never skip that approval just because you're chaining from /start). After scaffolding, show the remaining arc and stop.

If Stop here: reply with a single line — "Type /scaffold to begin." — and stop.

Either way, show the arc for reference and point to /help if they're unsure what a skill does:

1. /scaffold — generate the buildable project skeleton.
2. Implement — /add-command, /add-listener, /add-config, /add-gui, /add-storage.
3. /build → /run-server → /plugin-review.

Do not auto-run anything past scaffolding — features, build, and run each need the user's specific intent, so hand off to them.

Edge cases

• Already fully set up (config + project exist and they chose "keep"): skip ahead — "You're set up: {platform} {mc_version}, {build_tool}. Add a feature (/add-command, …), /build, or /run-server. Or tell me what the plugin should do."
• User doesn't fit an option: let them describe their situation and adapt.