review_minestom_design

Instructions

Implementation Reference

• src/minestom/planning.ts:148-231 (handler)

  The main execute handler for the review_minestom_design tool. Parses designNotes and featureType, evaluates the design against the feature blueprint's designChecks to identify strengths and gaps, performs feature-type-specific risky assumption checks, computes a fitAssessment (strong/partial/weak), and returns a structured review with recommended APIs, topics, and thread safety concerns.

  }).server(async (args) => {
  	const { designNotes, featureType } =
  		reviewMinestomDesignInputSchema.parse(args);
  	const blueprint = getFeatureBlueprint(featureType);
  	const loweredNotes = designNotes.toLowerCase();
  
  	const strengths = blueprint.designChecks
  		.filter((check) =>
  			check.keywords.some((keyword) => loweredNotes.includes(keyword)),
  		)
  		.map((check) => check.strength);
  
  	const gaps = blueprint.designChecks
  		.filter(
  			(check) =>
  				!check.keywords.some((keyword) => loweredNotes.includes(keyword)),
  		)
  		.map((check) => check.gap);
  
  	const riskyAssumptions: string[] = [];
  
  	if (
  		loweredNotes.includes("async") &&
  		!/(acquirable|scheduler|taskschedule|executiontype|sync)/.test(loweredNotes)
  	) {
  		riskyAssumptions.push(
  			"The design mentions async work without explaining how Minestom-owned state is reacquired or handed back safely.",
  		);
  	}
  
  	if (
  		featureType === "instance-setup" &&
  		loweredNotes.includes("per-player") &&
  		!loweredNotes.includes("sharedinstance")
  	) {
  		riskyAssumptions.push(
  			"Per-player world semantics are mentioned without clarifying whether `SharedInstance` or a separate `InstanceContainer` owns that state.",
  		);
  	}
  
  	if (
  		featureType === "scheduled-task" &&
  		!/(cancel|shutdown|stop)/.test(loweredNotes)
  	) {
  		riskyAssumptions.push(
  			"The design does not explain who cancels or tears down the scheduled task when the feature stops.",
  		);
  	}
  
  	if (
  		featureType === "server-bootstrap" &&
  		!/(instance|spawn|asyncplayerconfigurationevent)/.test(loweredNotes)
  	) {
  		riskyAssumptions.push(
  			"The bootstrap notes do not make the initial player-to-instance flow explicit.",
  		);
  	}
  
  	const fitAssessment =
  		strengths.length >= Math.max(blueprint.designChecks.length - 1, 2)
  			? "strong"
  			: strengths.length >= 2
  				? "partial"
  				: "weak";
  
  	const recommendedApis = getApisBySymbols(blueprint.keyApiSymbols).map(
  		(api) => ({
  			javadocUrl: api.javadocUrl,
  			packageName: api.packageName,
  			symbol: api.symbol,
  		}),
  	);
  
  	return reviewMinestomDesignOutputSchema.parse({
  		featureType,
  		fitAssessment,
  		gaps,
  		recommendedApis,
  		recommendedTopics: [blueprint.primaryTopic, ...blueprint.supportingTopics],
  		riskyAssumptions,
  		strengths,
  		threadTickConcerns: blueprint.threadSafetyNotes,
  	});
  });

• src/minestom/planning.ts:114-123 (schema)

  Input schema for the review_minestom_design tool. Accepts designNotes (free-form design description) and featureType (one of: server-bootstrap, command, event-listener, instance-setup, scheduled-task).

  const reviewMinestomDesignInputSchema = z.object({
  	designNotes: z
  		.string()
  		.describe(
  			"Free-form design notes or a proposed implementation approach to review.",
  		),
  	featureType: minestomFeatureTypeSchema.describe(
  		"The kind of Minestom feature the notes describe.",
  	),
  });

• src/minestom/planning.ts:125-140 (schema)

  Output schema for the review_minestom_design tool. Returns featureType, fitAssessment (strong/partial/weak), gaps, recommendedApis, recommendedTopics, riskyAssumptions, strengths, and threadTickConcerns.

  const reviewMinestomDesignOutputSchema = z.object({
  	featureType: minestomFeatureTypeSchema,
  	fitAssessment: reviewAssessmentSchema,
  	gaps: z.array(z.string()),
  	recommendedApis: z.array(
  		z.object({
  			javadocUrl: z.string().url(),
  			packageName: z.string(),
  			symbol: z.string(),
  		}),
  	),
  	recommendedTopics: z.array(minestomTopicSchema),
  	riskyAssumptions: z.array(z.string()),
  	strengths: z.array(z.string()),
  	threadTickConcerns: z.array(z.string()),
  });

• src/tools.ts:26-28 (registration)

  Registration of the reviewMinestomDesignTool in the tools array that gets exported as serverTools.

  	reviewMinestomDesignTool,
  	suggestMinestomLibrariesTool,
  );

• src/minestom/catalog.ts:1133-1137 (helper)

  Helper function getFeatureBlueprint() used by the review handler to look up the FeatureBlueprint for a given featureType, which contains designChecks, keyApiSymbols, threadSafetyNotes, etc.

  export function getFeatureBlueprint(
  	featureType: MinestomFeatureType,
  ): FeatureBlueprint {
  	return featureBlueprints[featureType];
  }