detect-mods-directory

name	detect-mods-directory
description	Locates and validates the correct Minecraft mods directory for an existing modpack or launcher instance. Use when a task needs the mods folder path before analyzing, importing, detecting, or migrating Minecraft mods.

Detect Mods Directory

The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL are to be interpreted as described in RFC 2119.

Find the real Minecraft mods directory before operating on mod files. The agent MUST NOT guess when the evidence is weak.

Valid Mods Directory

A valid candidate MUST satisfy these rules:

• The directory name MUST be exactly mods.
• The same parent directory MUST contain config/.
• The same parent directory MAY contain options.txt and logs/; these OPTIONAL markers SHOULD increase confidence when present.
• The mods/ directory MAY contain non-mod files, but it SHOULD primarily contain .jar files for a Forge-style modpack.
• Nested directories inside mods/ are valid and MUST NOT disqualify the candidate.
• If no credible mods/ directory is found, the agent MUST stop and ask the user for the correct path.

Workflow

1. The agent MUST start from paths provided by the user.
2. If no path is provided, the agent SHOULD inspect likely workspace paths only and MUST NOT scan unrelated system-wide locations unless the user asks.
3. The agent MUST search for directories named exactly mods.
4. For each candidate, the agent MUST inspect the parent directory for REQUIRED marker config/ and OPTIONAL confidence markers options.txt and logs/.
5. The agent MUST inspect the immediate contents of mods/ and note whether .jar files are the primary file type.
6. The agent MUST keep nested directories as valid contents.
7. The agent SHOULD select the strongest candidate and report its path plus the evidence used.
8. If multiple candidates are similarly strong, the agent MUST ask the user to choose.
9. If no candidate is credible, the agent MUST ask the user for the path to the Minecraft instance or mods directory.

Candidate Scoring

The agent SHOULD prefer the candidate with the most evidence:

• Strong: directory name is mods, parent contains REQUIRED config/, parent also contains OPTIONAL options.txt and logs/, and mods/ contains mostly .jar files.
• Acceptable: directory name is mods, parent contains REQUIRED config/, and mods/ contains .jar files.
• Weak: directory name is mods but parent lacks REQUIRED config/, or contents lack Minecraft modpack evidence.

The agent MAY use strong or acceptable candidates. The agent MUST NOT proceed with a weak candidate unless the user confirms it.

Output

When reporting the result, the agent MUST include:

• The selected mods/ path.
• The parent directory path.
• Which sibling markers were found: REQUIRED config/, OPTIONAL options.txt, OPTIONAL logs/.
• A brief summary of mods/ contents, including whether .jar files are present and whether nested directories exist.

Guardrails

• The agent MUST NOT rename, move, delete, or modify files while detecting the directory.
• The agent MUST NOT assume every directory named mods is a Minecraft mods directory.
• The agent MUST NOT reject a candidate only because mods/ contains nested folders or a few non-JAR files.
• The agent MUST NOT continue to mod analysis, packwiz detection, or migration until the directory is identified or confirmed by the user.