eliteforge-makefile-spec

EliteForge Makefile Specification

Goal

Generate a file located at the repository root: Makefile: keep the external commands and parameters unified, adapt the internal implementation to the actual detected repository topology, build system, artifact publishing method, Docker configuration and application shell, and remain compatible with GNU Make 3.81, macOS and Windows. An existing Makefile must be refactored in place; do not layer duplicate recipes on top.

Unified Public Interface

• All repositories must define help、doctor、install、clean、format、lint、test、build、dev、deploy。
• No longer generate check、run、verify public targets; when migrating an existing Makefile, keep hidden compatibility aliases only where repository automation still has callers.
• All Makefiles accept the VERSION and SKIP_TESTS command-line variables, for example make build VERSION=1.2.3 SKIP_TESTS=true. Pass variables only to targets where they are semantically applicable and actually supported by the repository; do not silently ignore values that were passed in.
• deploy Only publish versioned packages or build artifacts, such as JARs, npm packages or Python packages; it is not responsible for deploying running services.
• Docker capabilities are unified as docker-build、docker-run、docker-stop、docker-push; application shell capabilities are unified as app-build、app-dev、app-clean。
• The generated syntax must be compatible with GNU Make 3.81. Windows compatibility means GNU Make on Windows; do not claim compatibility with NMake.

Output Path

Determine the main Makefile path according to the following priority:

1. The file path explicitly specified by the user for the current task;
2. Under the repository directory explicitly specified by the user, Makefile；
3. <git-top-level>/Makefile。

If the input is a directory, append Makefileat the end. Unless the user explicitly requests another file name, use the case-sensitive standard file name Makefile. Treat this file as the single source of truth; do not create or modify other project files without an explicit user request.

Required Reading

1. Every task reads references/target-contract.md。
2. Every task reads references/detection-rules.md。
3. Read only the corresponding sections in references/ecosystem-adapters.md according to the detected technology stack.
4. Read this when the repository is a multi-project repository, has Docker/Compose or an application shell, needs to orchestrate multiple development processes, or already has a relatively complex Makefile: references/orchestration-patterns.md。

Execution Flow

1. Inventory the Repository

After determining the repository root directory, run the skill's built-in read-only detector using an absolute path:

python3 <skill-dir>/scripts/inspect_repository.py <repository-root> [--no-git-root]

When the user explicitly limits the task scope to a subdirectory within a larger Git repository, pass in --no-git-root. Record the repository topology, component list, lock files and package managers, existing Makefile, Docker/Compose files, application shell evidence, CI files and warnings from the detection results.

2. Verify the Evidence

Read all relevant manifest files, as well as existing Makefiles, package scripts, build plugins, repository scripts, CI, Dockerfile/Compose files and the parts of repository documentation that contain commands. Verify the version source, test-skipping parameter, artifact repository, release tasks, image names and Registry. Before changing old target names, first search the repository for any remaining callers.

Do not draw conclusions based solely on directory names. Resolve package manager conflicts, main application ownership or runtime path conflicts before editing; ask the user only when repository evidence cannot eliminate an ambiguity that would materially affect the result.

3. Design the Mapping

Map target-contract.md Every unified target and dynamic variable maps to a command that actually exists in the repository. For multi-project repositories, determine the component dependency order and hide component operations behind _... private targets. For Docker or application shells, use only the stable capability target names defined by the contract.

Prefer commands, wrapper scripts, lock files, and repository-local binaries that have been verified by CI. Do not invent missing scripts, and do not silently switch package managers, build configurations, test scopes, version sources, artifact flows, or primary development entry points.

4. Generate or refactor the Makefile

Strictly implement the unified target and parameter interface. Consolidate repeated logic into variables, reusable recipes, or private targets. Keep old targets only as lightweight compatibility aliases that do not appear in help output, and only when automation within the repository still calls them.

Makefile syntax must not use features provided only after GNU Make 3.81. Recipes must use repository-relative paths, execute non-interactively, and be scoped; prefer calling cross-platform repository tools or wrapper scripts; handle operating system differences explicitly with OS=Windows_NT. Preserve lock files and user data. Do not add global installations,sudo, destructive Git/Docker cleanup, unscoped deletions, or expose secrets in commands or help text.

doctor Must distinguish between required tools for the unified main path and optional capability tools, and check the wrapper or command corresponding to the current operating system. When local unified targets do not depend on Docker, a missing Docker may only produce a non-blocking warning.

Do not create additional helper scripts just to bypass the Makefile design. If correct cross-platform or process lifecycle behavior must depend on new non-Makefile files, stop and ask the user to expand the task scope.

5. Verification

Execute in the repository root:

1. make help；
2. For each unified target and generated capability target, execute make --no-print-directory -n <target>；
3. make doctor；
4. Use VERSION=0.0.0-test SKIP_TESTS=true to perform a dry run on build、deploy and applicable capability targets, confirming that dynamic variables are correctly consumed or explicitly rejected;
5. On non-Windows environments, execute make --no-print-directory -n OS=Windows_NT <target>on targets, and statically check the Windows branch;
6. When dependencies are ready and execution falls within the current task scope, run make lint、make test and make build。

Do not execute install、dev、deploy、docker-run、docker-push or other long-running targets that change local or remote state solely for verification. Report every command not executed and the reason. When actual testing on Windows is impossible, clearly state that only a static check of the Windows branch was completed. Before completion, fix syntax errors, missing target dependencies, unsafe cleanup, duplicated work, unconsumed variables, and inconsistent target semantics.

Mandatory Rules

• All repositories must use completely consistent unified public target names and semantics.
• Technology stack and component differences must not leak into the public interface.
• User-facing help, check, skip, warning, and error messages in the Makefile must be in Chinese; commands, target names, and technical identifiers remain unchanged.
• lint Must aggregate the configured non-modifying format checks, static checks, type checks, and compilation checks;build Must cover all local deliverables,dev Must cover the complete usable development topology.
• deploy Must publish the software packages or artifacts corresponding to VERSION ; when the version, artifact, or release target cannot be resolved, it must fail and must not pretend to succeed.
• SKIP_TESTS=true May only skip tests implicit in the lifecycle such as install、build、deploy , and must not prevent explicit test Target skips tests.
• Docker and the application shell must be detected, but local builds must not be forced through Docker because of this.
• docker-push Images with explicit version tags must be pushed; silent pushing is prohibited latest。
• Only non-release capabilities that truly do not exist may explicitly output 跳过：; unsupported dev or deploy must output a clear 错误：。
• GNU Make 3.81 must be supported; the use of .ONESHELL、.RECIPEPREFIX、.WAIT、$(file ...), grouped targets &: , and other newer syntax is prohibited.
• When a wrapper exists in the repository, replacing it with system tools is prohibited.
• Commands that were only dry-run or have been skipped must not be claimed as successfully verified.

Completion Report

Return:

• Output the Makefile path;
• Detected repository topology and supporting evidence;
• Detected Docker/Compose and application shell capabilities;
• A summary of the mapping from unified targets to actual implementations;
• VERSION、SKIP_TESTS and other applicable targets for override variables;
• Scope of macOS, Windows, and GNU Make 3.81 compatibility verification;
• Verification commands and results;
• Unresolved ambiguities, or intentionally retained compatibility aliases.